人工智能AI Agent多智能体Agent 编排代码智能体CLI【免费下载链接】openrigMulti-agent harness that runs Claude Code and Codex together as one system项目地址https://gitcode.com/GitHub_Trending/op/openrig点击查看免费下载本篇技术指南围绕 OpenRig 内置的缺陷修复切片模板bug-fix展开它是 OpenRig 的 Slice切片脚手架家族中专用于 Bug 修复的一等模板当你运行rig scope slice create并指定--template bug-fix时CLI 会依据它生成一份结构完整的SPEC.md其中自带 Intent、Mini-requirements、Proof contract 以及经典的 Repro/Expected/Actual 三段式问题描述。读完本文你将掌握该模板的每一处占位符、每一条章节的写法与约束理解它如何与rig proof add、rig scope audit、SDLC 约定docs/reference/sdlc-conventions.md及系统性调试技能协同把修一个 Bug从一句口头诉求变成一条可追踪、可审计、有证据闭环的工程切片。一、模板的定位bug-fix 在 Slice 模板家族中的角色OpenRig 把可交付工作拆成Mission任务→ Slice切片两层。Slice 是承载一次具体交付的最小工作单元而rig scope slice create在创建切片时通过--template决定SPEC.md的初始骨架。在 packages/cli/src/lib/scope/types.ts 中Slice 模板的合法取值被定义为一个封闭集合export type SliceTemplateKind | placeholder | bug-fix | backlog-deprecation | backlog-tech-debt | release-feature | research;也就是说bug-fix与placeholder、backlog-deprecation、backlog-tech-debt、release-feature、research并列是模板家族中专门服务缺陷修复这一工作形态的成员。它的设计意图很明确对于一次 Bug 修复模板允许整份计划就是一次可观察的修复结果模板原文中 Mini-requirements 的提示语就是 The fix as an observable outcome. For a bug fix this may BE the whole plan.同时强制要求提供可复现步骤、预期/实际行为、影响面与修复提案让一次修复从一开始就具备可验证性。在 OpenRig 的语义里Slice 不只是一个任务卡片一次rig scope slice create会同时落下一组配套文件SPEC.md、slice.yaml、PROGRESS.md、PROOF.md、proof/目录这部分在 packages/cli/test/scope-convention-scaffold.test.ts 中被逐模板断言为固定产物集合。bug-fix 模板生成的正是这一整套可审计切片的入口文档。二、模板的物理位置与加载机制模板本体位于 packages/cli/src/lib/scope-templates/bug-fix.md与其余 Slice/Mission 模板同目录存放。它之所以能以.md形式被 CLI 读取是因为加载器在 packages/cli/src/lib/scope/templates.ts 中通过fileURLToPath直接按候选根解析文件路径——开发态src/lib/scope/的上级scope-templates/、构建态dist/lib/scope/的上级与发布包回退路径依次探测第一个存在的目录胜出从而保证本地开发与安装包两种布局下都能找到模板。渲染时templates.ts 的applyPlaceholders会做纯文本占位符替换{{id}}、{{slice_number}}、{{slug}}、{{mission}}、{{title}}、{{created_date}}、{{intent_yaml}}、{{intent}}、{{depends_on}}等随后renderSliceTemplate(kind, opts)依据kind如bug-fix拼出模板文件名并返回渲染后的正文。也就是说模板文件是以文档形式存在、由代码驱动渲染的单一事实来源修改模板即修改脚手架行为。三、逐节拆解 bug-fix 模板frontmatter 与六个正文小节3.1 frontmatter切片的身份与元数据模板头部是一段 YAML frontmatter所有字段在rig scope slice create时由渲染器自动填入无需手工编写字段填充来源说明idsliceIdFromMission(missionId, nn)稳定点号 ID形如OPR.0.3.2.2项目前缀 版本 序号规则见 packages/cli/src/lib/scope/dot-id.tssliceNN-slug目录名后缀如05-perf-fixNN 由nextSliceNN自动寻找永不复用已用编号mission命令参数所属 Mission 的文件夹名如release-0.3.2status固定值placeholder切片创建时的初始状态stage固定值wip认识论成熟度阶段合法枚举见types.ts的STAGE_VALUESwip/provisional/established/canonical/superseded/retiredverified{{created_date}} against scaffold (rig scope create)记录此文件仅经过脚手架验证的事实防止把模板占位当成已实现created{{created_date}}创建日期ISOintent--intent参数以 JSON 字符串形式写入的意图声明缺省回退为标题depends_on--depends-on参数兄弟切片点号 ID 数组渲染为 JSONscope.ts会校验其必须是本 Mission 前缀下的合法 slice 点号 ID3.2 正文六段从意图到修复提案模板正文在# Slice {{slice_number}} — {{title}}标题之后依次展开六个 H2 小节## Intent—— 一句或一小段话说明为什么要修。来自--intent参数缺省等于标题。## Mini-requirements—— 一瞥即懂的需求层用编号的可观察结果表达。对于 Bug 修复模板明示这一条可能就是整份计划The fix as an observable outcome。## Proof contract—— 证明契约用复选框- [ ]逐条写下承诺的可观察交付物。模板给出的示例行是[The repro no longer reproduces / the regression test pins it — captured. Pair with proof via rig proof add … --evidences (media attached with --media).]提示两条典型的 Bug 修复证据复现不再出现或回归测试钉住了该行为并指明证据须经rig proof add落盘、媒体用--media附带。## Repro/## Expected/## Actual—— 经典的缺陷三要素复现步骤、预期行为、实际行为。这是模板对 Bug 修复工作形态最直接的适配直接对应能否稳定复现这一调试铁律。## Impact—— 谁受影响、严重程度如何用于支撑优先级判断。## Fix proposal—— 可选的修复思路模板标注 Optional不强制。四、真实使用流程从命令到磁盘上的切片4.1 创建命令与参数rig scope slice create在 packages/cli/src/commands/scope.ts 中定义语法为rig scope slice create mission slug [options]常用选项选项作用--template kind模板种类合法值见SLICE_TEMPLATE_KINDS默认placeholderBug 修复请显式传bug-fix--title text显示标题缺省为 slug 的标题化结果titleFromSlug--intent text写入 SPEC.md frontmatter 的意图缺省等于标题--depends-on dot-id...声明对兄弟切片点号 ID 的构建顺序依赖--readme-only只写progress_rail: readme-only标记不脚手架PROGRESS.md--json输出机器可读结果一个真实的创建示例rig scope slice create release-0.3.2 perf-fix \ --template bug-fix \ --title Fix agent-seat double-attach deadlock \ --intent Two agents attaching the same seat must not deadlock the seat registry \ --depends-on OPR.0.3.2.1创建过程scope.ts会依次定位 Mission → 计算下一个 NN如05→ 拼出切片目录slices/05-perf-fix/→ 校验依赖点号 ID → 渲染模板 → 在同一事务边界内写入SPEC.md、PROGRESS.md、slice.yaml、PROOF.md并创建空proof/目录任何一步失败都会回滚整个目录与父 Mission 的写入绝不留下半成品。4.2 命令行为有测试背书packages/cli/test/scope-commands.test.ts 的 HG-4 用例直接验证了本模板以--template bug-fix创建切片后读回SPEC.md必须包含## Repro与## Expected小节。同文件还断言了PROGRESS.md默认生成AC-1以及根级PROOF.md 空proof/目录的脚手架行为OPR.0.4.1.23。这些测试共同保证了模板 → 文件系统这条链路的稳定性。4.3 落地后的目录结构一次创建后切片目录如下slices/05-perf-fix/ ├── SPEC.md # 由 bug-fix 模板渲染出的切片说明本模板的核心产物 ├── slice.yaml # slice 清单spec: SPEC.md / progress: PROGRESS.md / proof: PROOF.md ├── PROGRESS.md # 验收状态轨Acceptance 复选框 ├── PROOF.md # 收尾时填写的证明摘要绑定 SPEC.md 的证明契约 └── proof/ # 证明工件目录截图、录屏、命令输出等媒体五、模板占位与真写的边界审计如何识别偷懒模板中的方括号文本如[Steps to reproduce]、[Expected behavior]不是普通的待办说明而是被专门识别的脚手架占位符标记。packages/cli/src/lib/scope/scaffold-placeholder.ts 定义了唯一语法文本去除首尾空白后若整体被方括号包裹^\[.*\]$即判定为脚手架占位、非作者内容。该判定同时被 scope audit、review compose、slice-detail projector 三方消费且该文件在 CLI 与 daemon 两个包中是字节等价的双胞胎twin由 CI 强制保持一致。这意味着直接照抄模板把[Expected behavior]留在SPEC.md里审计时不会算作已撰写内容。rig scope audit实现在 packages/cli/src/lib/scope/scope-audit.ts会据此给出相应 findingmini_requirements_missing_or_malformedlow## Mini-requirements缺失或虽有编号列表但全是占位文本proof_contract_missing_or_malformedlow## Proof contract缺失或复选框行全是占位文本scope-audit.ts要求至少有一条作者撰写的复选框项才算有效契约missing_proofmedium切片已处于 done/proven 状态却缺少根级PROOF.md且proof/目录为空packages/cli/test/scope-audit.test.ts 有对应用例。因此把模板落盘之后的第一步工作就是用真实内容替换每一处方括号占位。审计对 Bug 修复切片的直接意义是Repro/Expected/Actual 与证明契约缺一不可占位不算数。六、证据闭环rig proof add与 PROOF.mdbug-fix 模板的 Proof contract 提示语明确要求证据经由rig proof add … --evidences媒体用--media落盘而绝不手工放置。对应命令实现在 packages/cli/src/commands/proof.tsrig proof add slice \ --artifact-type qa \ --verdict PASS \ --candidate-sha the-proven-tip \ --money-evidence one line of money evidence \ --file artifact.md \ --evidences 1 \ --media screenshot-01.png,regression-output.txt \ --self-check I looked at the captures; they show the claim关键参数与约束--artifact-type与--verdict是两个封闭集合ratified closed sets按 docs/reference/sdlc-conventions.md 的 B3 节扩展它们属于约定变更而非本地编辑artifact_type ∈ guard | qa | rev1-r1 | rev1-r2 | adjudicationverdict ∈ CLEAR | BLOCKING | CONCERNING | PASS | NOT-CLEAR--candidate-sha是 C1 头的联结键join key该工件所评判的被证明候选提交--evidences指明本次 drop 覆盖证明契约中的哪些条目条目文本或 1 基索引该引用由logical-checkbox语法packages/cli/src/lib/scope/logical-checkbox.ts统一解析——review 合成、切片详情投影与 CLI 证据索引校验共用同一套语法保证按索引引用时各方指向同一条承诺项--media中的媒体路径必须是相对于切片proof/目录的相对路径proof.ts在 drop 时即校验其非绝对路径且不逃逸切片目录--self-check记录代理确实看过证据的声明。落盘后工件获得合法的 C1 头五个必填字段slice、candidate_sha、artifact_type、verdict、money_evidence。与之配套的收尾文档模板是 packages/cli/src/lib/scope-templates/proof.md它要求写明这证明了什么、工件清单媒体置于proof/下以及残留问题Residue / caveats并由 impl/QA 结对在切片收尾时填写。直接往proof/丢文件而不走 drop是文档明示的反模式——交付物会停留在未配对、unverified状态审计也会照实标记。七、SOP 遵从模板底部的怎么干这个切片bug-fix 模板底部附有一段 SOP 指引它把模板与 OpenRig 的 SDLC 约定体系连成一体。核心指向是约定 SSOTdocs/reference/sdlc-conventions.md安装包内位于$OPENRIG_HOME/reference/sdlc-conventions.md。按该文档工作方式是一份组件菜单而非流水线构建路径三选一简单默认流Part A默认且始终适用、wave 模型切片在互不重叠的文件领域并行构建、集成者串行合并、独立评审见 docs/reference/wave-sdlc.md、以及被指派的严格覆盖层Part B仅当人类操作者或中继该决定的中枢把重路径指派给具名工作时才可启用代理不得自行选择 Part B证明契约、plan-lock、C1 drop、proof-lock 都在 Part B。规划严格度旋钮 P0–P4按工作性质拨动P0 只要 mini-requirements 与指针简单、可逆的工作P1 是带证明契约的规范默认P2 在规范冻结前增加研究轮P3 增加非作者的对抗性评审并让修正落入证明契约P4 则要求从零盲写的设计稿与先前方案对比。完整参考见 docs/reference/planning-dial.md。默认流的完整教学由mission-slice-sop技能提供对应 Part A 的简单 SDLC。所有路径的共同底线进度记录在PROGRESS.md状态枚举active | done | blocked见 packages/cli/src/lib/scope/progress-edit.ts证据一律经rig proof add落盘、绝不手工放置切片在承诺的可观察结果拥有证据之前不算完成最终以rig scope audit校验。对一次 Bug 修复切片而言SOP 的落地顺序通常为用 bug-fix 模板脚手架 → 替换占位、写实 Repro/Expected/Actual 与证明契约 → 按 P 拨号选择规划严格度 → 修复过程中在PROGRESS.md记录状态 → 用rig proof add提交复现消失或回归测试命中的证据 → 收尾时填写PROOF.md→rig scope audit复核。八、与系统性调试技能的自然衔接bug-fix 模板的 Repro/Expected/Actual 结构与 OpenRig 内置的 skills/_canonical/process/systematic-debugging/SKILL.md 形成天然互补该技能的铁律是先找根因再动手修症状修复就是失败其 Phase 1 明确要求稳定复现Reproduce Consistently、细读错误信息、检查近期变更、在多组件系统中逐层取证。这些恰好是模板中Repro、Expected、Actual、Impact四节要沉淀的内容——模板负责把调试纪律固化成文档结构技能负责指导填出高质量内容。而模板 Proof contract 提示的repro 不再复现 / 回归测试钉住行为两种证据形态也正是该技能 Phase 4修根因而非症状的可验证外化。九、小结bug-fix 模板的完整闭环把全部环节串起来一次符合规范的 Bug 修复切片走的是这样一条证据链rig scope slice create mission slug --template bug-fix生成SPEC.md含 frontmatter 点号 ID、Intent、Mini-requirements、Proof contract、Repro/Expected/Actual、Impact、Fix proposal并同步落盘slice.yaml、PROGRESS.md、PROOF.md、proof/用真实内容替换全部方括号占位——占位会被 scaffold-placeholder.ts 识别不算作者内容按 sdlc-conventions.md 的组件菜单选择构建路径与 P0–P4 严格度在PROGRESS.md持续跟踪用rig proof add以 C1 头落盘证据--evidences回指证明契约条目、--media附带proof/下媒体收尾填写PROOF.mdrig scope audit最终校验切片在证据齐备前不算 done。这套机制的独特之处在于bug-fix 模板不是一张待填表格而是一条被渲染器、审计器、证明命令三方共同约束的契约——它让修 Bug这件在传统工程里最容易被口头交代、事后无法追证的工作在 OpenRig 中获得了与功能开发同等的结构、证据与可审计性。赞分享人工智能AI Agent多智能体Agent 编排代码智能体CLI【免费下载链接】openrigMulti-agent harness that runs Claude Code and Codex together as one system项目地址https://gitcode.com/GitHub_Trending/op/openrig点击查看免费下载相关推荐OpenRig 技术债务治理实战用 backlog-tech-debt Slice 模板把存量债变成可审计、可验证的工作切片OpenRig 技术债务治理实战用 backlog tech debt Slice 模板把存量债变成可审计、可验证的工作切片 本文围绕 OpenRig 仓库中人工智能AI Agent多智能体Agent 编排代码智能体CLI别再让Issue被关闭用openJiuwen缺陷报告模板写出快速被复现修复的Bug别再让Issue被关闭用openJiuwen缺陷报告模板写出快速被复现修复的Bug 提交过开源项目Issue的朋友可能都有过这样的经历满怀期待地报了一个BECC 缺陷修复编排指南用 /orch-fix-defect 实现红测试驱动的 Bug 修复ECC 缺陷修复编排指南用 /orch fix defect 实现红测试驱动的 Bug 修复 本文以 ECCThe agent harness perfor人工智能AI 技能AI 插件AI 评测Agent 评测MCP Clients开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考