OpenRig slice 脚手架解析：从 `placeholder` 模板到可执行的 SPEC 工作流

• 人工智能
• AI Agent
• 多智能体
• Agent 编排
• 代码智能体
• CLI

【免费下载链接】openrig

Multi-agent harness that runs Claude Code and Codex together as one system

项目地址：https://gitcode.com/GitHub_Trending/op/openrig

点击查看免费下载

本指南深入剖析 OpenRig（一个将 Claude Code 与 Codex 编排为统一多 Agent 系统的控制平面）中，rig scope slice create生成新 slice 时所依据的官方模板——packages/cli/src/lib/scope-templates/placeholder.md。你将掌握：该模板如何构成一个 slice 的 SPEC 骨架（Intent → Mini-requirements → Proof contract）、每个 frontmatter 字段（id / slice / mission / status / intent / depends_on）的含义与写入方、rig scope命令族如何消费并审计这些字段，以及为何“未完成的模板占位符”会被系统刻意识别为“尚未编写”而非“已交付”。读完即可用rig scope亲手搭出符合 SDLC 约定的 slice，并理解从模板占位符到最终证据闭环的完整流转。

模板总览：一个 slice 的生命起点

OpenRig 的所有 slice 与 mission 文档都不是手工从零敲出来的——rig scope slice create从scope-templates/目录读取 Markdown 模板，执行占位符替换后落盘。placeholder.md就是其中默认（且最通用）的 slice 模板：当你执行rig scope slice create <mission> <slug>而未显式指定--template时，使用的正是它。

从模板加载器源码可以看到模板被设计成“与源码同住”的文档：

• 源码树（packages/cli/src/lib/scope/ → ../scope-templates）与构建产物（dist/lib/scope-templates）都会被探测，第一个存在者胜出；
• 模板是普通 Markdown，可像文档一样编辑，构建时由 packages/cli/package.json 的build脚本cp src/lib/scope-templates/*.md dist/lib/scope-templates/复制进发布包；
• 渲染时用applyPlaceholders做纯字符串替换：{{id}}、{{slice_number}}、{{slug}}、{{mission}}、{{title}}、{{created_date}}、{{intent}}、{{depends_on}}等占位符一一对应RenderOpts接口的字段。

对 slice 而言，占位符值由 packages/cli/src/commands/scope.ts 的buildSliceCreateCommand在创建时计算：

• nn：nextSliceNN取该 mission 下已有 slice 序号的下一个，文件夹命名为NN-slug（如03-fix-login）；
• id：由sliceIdFromMission(missionId, nn)铸成missionId.NN形式的稳定 dot-ID；
• title：默认由titleFromSlug将 slug 转成首字母大写的展示名；
• intent：默认等于 title，也可用--intent显式提供。

模板全文（含渲染后语义）

--- id: {{id}} slice: {{slice_number}}-{{slug}} mission: {{mission}} status: placeholder stage: wip verified: {{created_date}} against scaffold (rig scope create) created: {{created_date}} intent: {{intent_yaml}} depends_on: {{depends_on}} --- # Slice {{slice_number}} — {{title}} ## Intent {{intent}} ## Mini-requirements 1. [The concise one-glance requirement tier — numbered observable outcomes. For a small slice this may BE the whole plan.] ## Proof contract - [ ] [One promised deliverable, written as an observable outcome — captured. Each item pairs with its proof via `rig proof add … --evidences` (media attached with `--media`); UI deliverables name their planned mockup.] ## Source material - [Paths or refs] ## Intent visual Non-visual slices: mark this section N/A. - Intent image: Intent visual - Durable diff: change.diff - Regenerate preview: from `packages/ui`, run `{{intent_visual_build_command}}` to rebuild `twin-out/intent.html` (gitignored). ## Status - TODO: [next steps] ## Dependencies - [Cross-slice / cross-release] --- > **How you work this slice (SOP):** conventions SSOT: `docs/reference/sdlc-conventions.md` (installed: `$OPENRIG_HOME/reference/sdlc-conventions.md`) — read its COMPONENT MENU first: your mission chooses the build path (the simple default flow · the wave model · the assigned rigorous overlay) and the planning rigor (the P0–P4 dial); do not assume the heavy flow unless your mission or dispatch assigns it. Full flow for the default path: the `mission-slice-sop` skill. The floor on every path: track on PROGRESS.md; evidence lands via `rig proof add` (never hand-placed); a slice is **not done** until its promised outcomes have evidence; verify with `rig scope audit`.

这段模板浓缩了 OpenRig 的核心理念：意图先于实现、可观测结果先于代码、证据先于宣称完成。它是SDLC 约定文档（docs/reference/sdlc-conventions.md，安装后位于$OPENRIG_HOME/reference/sdlc-conventions.md）在磁盘上的第一处落地。

Frontmatter 字段逐项拆解

模板 frontmatter 的每个字段都对应一条约定，且多数由 CLI 在创建时自动铸入。下表汇总字段、含义与来源：

字段	模板占位符	含义	写入方
id	{{id}}	稳定 dot-ID（<mission-id>.<NN>）	rig scope slice create自动铸入
slice	{{slice_number}}-{{slug}}	文件夹名（NN-slug）	CLI 按序号计算
mission	{{mission}}	所属 mission 名称	CLI 传入
status	固定值placeholder	初始状态，声明“尚未编写内容”	模板固定
stage	固定值wip	认识论成熟度等级（P0 起点）	模板固定
verified	{{created_date}} against scaffold (rig scope create)	证明来源行	CLI 铸入创建日期
created	{{created_date}}	创建日期（ISO）	todayDateISO()
intent	{{intent_yaml}}	作者的意图，JSON 序列化	CLI（--intent或默认 title）
depends_on	{{depends_on}}	兄弟 slice 的构建顺序依赖（dot-ID 列表）	CLI（--depends-on，JSON 数组）

几个值得注意的实现细节：

• status: placeholder是设计而非占位符文字：新创建的 slice 首先处于“占位”状态。与此对应，intent会被 JSON 序列化进 frontmatter（applyPlaceholders中JSON.stringify(opts.intent ?? opts.title)），便于机器读取。
• verified行自带 provenance：模板初始值写明“against scaffold (rig scope create)”，遵守“不允许裸时间戳”的约定——它声明了自己是“对脚手架的验证”，而不是对实现的验证。后续用rig scope slice verified <slice> --against <source>覆写为对真实实现的验证。
• stage属于受控枚举：packages/cli/src/lib/scope/types.ts 定义了六档STAGE_VALUES：wip | provisional | established | canonical | superseded | retired。模板锚定在最低档wip，rig scope slice stage <slice> <new-stage>会拒绝枚举外的任意值，且superseded必须用--successor指名继任者。

正文四大节的约定语义

模板正文固定了五个 Markdown 小节，其中三个是SDLC 约定要求的“约定小节”，顺序固定、标题精确：

Intent（意图）

{{intent}}被替换为创建时写入的意图文本。约定要求它是“逐字记录的意图”。TUI 与审计工具都通过精确标题## Intent来定位它——scope-convention-scaffold.test.ts 中用常量CONVENTION_SECTIONS = ["## Intent", "## Mini-requirements", "## Proof contract"]校验脚手架输出必须按序包含这三节。

Mini-requirements（微型需求）

模板给的是编号列表占位1. [...]。这一层的地位特殊：它是对人类操作者第一个结构化检查点，批准从这一层开始（见sdlc-conventions.md的 A2 节）。对小型 slice（bug 修复、研究笔记），“mini-requirements 可能就是整份规格”——这正是模板注释“For a small slice this may BE the whole plan”的来源。

从占位符识别源码看，编号条目还有一层机器语义：hasAuthoredNumberedItem会扫描正文中形如1./1)的条目，仅当至少存在一条文本非占位符的编号条目时才判定“已编写”。这意味着：一个仍停留在1. [...]的 slice，在系统眼里就是尚未进入可批准状态的“脚手架”，而不是一份已完成的规格。

Proof contract（证明契约）

复选框列表，每项是一个“可观测结果”形式的承诺交付物。模板示例- [ ] [...]之后，真实写法应如下（来自sdlc-conventions.mdB1 节）：

## Proof contract - [ ] The consolidated `rig ps` default renders all rigs with a rollup footer — captured. - [ ] UI: the slice review tab renders the three-section stack — screenshot vs the locked mockup.

每条契约项之后通过rig proof add … --evidences <编号或文本>与证据工件一一配对——这正是 TUI 的 DELIVERED 区渲染“计划 ↔ 交付”配对的数据来源。UI 交付物必须附带计划 mockup（plannedRef）；后端/文档类 slice 无需 mockup，缺失也不算缺口。

Source material / Intent visual / Status / Dependencies

这四个小节按需填写：Source material 记录路径或参考；Intent visual 针对 UI slice（非视觉 slice 标 N/A，模板也明确要求）；Status 是 TODO 列表；Dependencies 记录跨 slice / 跨 release 依赖。模板末尾的 SOP 引用块是给 agent 的操作指引——默认路径走mission-slice-sopskill，重型流程（Part B）必须由人类或编排器显式指派，agent 不得自选。

从模板到磁盘：rig scope slice create的实际产物

当运行以下命令时（模板默认placeholder）：

rig scope slice create release-0.6.1 login-timeout \ --title "Login Timeout Handling" \ --intent "Users see a clear timeout message instead of a hung session." \ --depends-on "OPR.0.6.1.2"

buildSliceCreateCommand 会按序完成：校验模板种类与 slug → 计算NN、铸造 dot-ID → 渲染 SPEC 正文与 PROOF 骨架 → 原子落盘（失败时整体回滚）→ 写入slice.yaml并更新 mission 的组成清单。最终目录形态：

<mission>/slices/03-login-timeout/ ├── SPEC.md # 即 placeholder 模板渲染结果 ├── slice.yaml # openrig.slice/v0alpha1 清单（指向 SPEC.md / PROGRESS.md / PROOF.md） ├── PROGRESS.md # 验收清单（渲染自 slice-progress.md 模板） ├── PROOF.md # 证据摘要骨架（渲染自 proof.md 模板） └── proof/ # 证据工件目录（初始为空）

• PROGRESS.md由 slice-progress.md 渲染，固定三个验收项：- [ ] Implementation complete、- [ ] Tests passing、- [ ] Review approved。这三个常量被scaffold-placeholder.ts 的GENERIC_SCAFFOLD_ACCEPTANCE精确引用并做防漂移同步测试。
• PROOF.md由 proof.md 渲染，内置“drop 动词”指引：媒体文件放入proof/后必须用rig proof add <id> --artifact-type qa --verdict PASS --candidate-sha <tip> --money-evidence "<one line>" --evidences "1" --media "screenshot-01.png"挂接，手工放文件而不 drop 会被视为未配对、unverified。
• --readme-only开关会在 SPEC.md frontmatter 插入progress_rail: readme-only，从而不生成 PROGRESS.md（适用于只靠 README 轨道的轻量 scope）。

占位符识别：系统如何区分“脚手架”与“已编写”

这个模板里所有方括号内容（如1. [...]、- [ ] [...]）并非随意示例，而是被核心代码当作语义标记消费的。三个谓词构成完整识别文法：

1. isScaffoldPlaceholderText(text)：修剪后文本完全被方括号包裹（^\[.*\]$）即为脚手架占位符。注意这是刻意设计：[a] and [b]这种“方括号包裹的真实交付物”同样会被识别为占位符——文法忠实，不搞特例。
2. hasAuthoredNumberedItem(body)：正文中只要存在一条非占位符的编号条目（1.或1)形式）即视为已编写。这是评审与审计共同依赖的“唯一已编写编号条目文法”。
3. isPlaceholderOnlyBlock(block)/isPristineScaffoldSection(body)：按行判定一个区块是否“全占位”。isPristineScaffoldSection额外剥掉编号/复选框/列表前缀再判定——用于证明契约的来源选择：selectProofContractBody按“已编写的 SPEC → PRD → README → null”的优先级挑选当前契约，只有未污染（pristine）的 SPEC 小节才允许让位给 README。

这套文法的价值在于：审计与评审永远不把模板残留当成已交付内容。一个只写了模板原样的 slice，在rig scope audit眼中就是“无已编写编号条目”，无法通过“开始批准”的门槛。

验证与审计：rig scope audit

SDLC 约定（A6 节）规定审计是建议性、fail-open的：记录与建议，绝不阻塞写入路径。审计入口rig scope audit --mission <name>会检查：

• 三大约定小节（## Intent/## Mini-requirements/## Proof contract）是否按序存在（缺失时 UI 渲染为静默的“—”）；
• 目录命名是否符合NN-slug约定（不符合产生id_convention_violation高优先级 finding）；
• proof/工件是否携带合法 C1 头、UI slice 是否引用 mockup；
• 依赖图（Ready:/Waiting:/Advisory:三类）是否与depends_on一致。

审计同样消费占位符文法：一个仍处于模板原样的 slice 会被如实报告为“尚未编写”，而不是“内容通过”。这正是“unknown 报为 unknown，而非失败”的诚实原则在工具链中的体现。

从占位符到证据闭环：完整流转图

rig scope slice create → SPEC.md（模板渲染，status: placeholder） │ ▼ 作者填写 Intent / Mini-requirements / Proof contract（替换方括号占位） │ ▼ rig scope slice progress --add/--set → PROGRESS.md 验收行（确定性更新） rig scope slice approve --scope spec → plan-lock（Part B 流程，锁 SPEC 与 mockup） │ ▼ 构建 → 视觉比对 → rig proof add … --evidences "1,3" --media "walk.webm,panel.png" │ （证据 drop，写入 C1 头） ▼ rig scope slice approve --scope delivery → proof-lock（终态签核） │ ▼ rig scope audit / rig workspace validate → 建议性审计，全链路闭环

贯穿始终的两条纪律：证据必须经rig proof add落地，绝不手工放置；slice 直到其承诺结果具备证据才算完成。模板中status: placeholder的初始值、verified行的 provenance、以及方括号占位符的机器识别，共同保证了这条闭环不会因为“看起来写了”而提前虚报完成——这正是 OpenRig 在编排多 Agent 系统时，把“诚实”落成可审计机制的核心手段。

如需深入，可继续阅读：SDLC 约定 SSOT、mission-slice-sop skill、模板加载与渲染实现、scope CLI 全部动词、以及脚手架约定测试。

赞分享

• 人工智能
• AI Agent
• 多智能体
• Agent 编排
• 代码智能体
• CLI

【免费下载链接】openrig

Multi-agent harness that runs Claude Code and Codex together as one system

项目地址：https://gitcode.com/GitHub_Trending/op/openrig

点击查看免费下载

相关推荐

• 项目架构解析：从模板到可执行文件的完整工作流程

  项目架构解析：从模板到可执行文件的完整工作流程 iPhone 14 15 特定区域天线激活项目采用了一个简洁而高效的技术架构，通过模板配置文件和Python脚本

• Nuclei 引擎架构深度解析：从模板 DSL 到协议执行的工作流全解

  Nuclei 引擎架构深度解析：从模板 DSL 到协议执行的工作流全解 Nuclei 是一款基于 YAML 模板 DSL 的快速、可定制的漏洞扫描引擎，其核心价

  网络安全应用安全漏洞扫描

• Hardhat 3 项目模板机制深度解析：从 `hardhat --init` 到可运行脚手架

  Hardhat 3 项目模板机制深度解析：从 hardhat init 到可运行脚手架 本文聚焦 Hardhat 3 内置的 Templates（项目模板） 体

  开发工具区块链CLI