跳转到内容
Chorus Chorus

OpenSpec 模式

支持规格模式的 Chorus 插件会解析出一个规格模式，也就是方案编写采用的形态。OpenSpec 模式是其中 一种，只要当前仓库能用 OpenSpec，它就是默认模式。开启后，AI-DLC 工作流 照常运行，只是不再把自由格式的 Markdown 直接敲进 Chorus，而是由 Agent 用 openspec CLI 在磁盘上编写结构化文件，再把它们镜像进 方案的文档草稿。磁盘上的文件是工作副本，Chorus 草稿是审阅者在方案页面上阅读的忠实镜像。

三种规格模式

Section titled “三种规格模式”
模式Agent 写什么什么时候用到
openspecopenspec/changes/<slug>/ 下的结构化文件，并镜像进草稿仓库能用 OpenSpec 时的默认模式
lite.chorus/specs/<slug>/ 下的 Chorus 原生轻量规格仓库用不了 OpenSpec 时的默认模式
off自由格式草稿，完全不写本地规格文件只在你显式要求时

六种支持规格模式的插件采用相同的解析规则，但解析时机和查看方式不同：

运行时何时解析、在哪里查看
Claude Code、Codex、Kiro、Pi会话启动时（Kiro 为 Agent 启动时）解析，注入的 ## Spec Mode 上下文会写明结果。
dsh插件加载时解析，在首个 Agent 步骤注入 ## Spec Mode 上下文。
OpenClaw阶段技能执行到规格模式步骤时运行随插件提供的解析器，没有 SessionStart 注入。用 /chorus spec 或 /chorus status 查看模式。

例如，解析为 OpenSpec 时会报告 CHORUS_SPEC_MODE=openspec。不要因为没有连接提示就推断模式。

模式如何选定

Section titled “模式如何选定”

按优先级排列：

  1. 显式的 CHORUS_SPEC_MODE 优先。 把它设为 openspec、lite 或 off，即可为某个 shell、 某个仓库或某个 CI 任务钉死模式。
  2. 否则，只要 OpenSpec 可用，它就是默认模式。 可用意味着三点同时成立：仓库根目录存在 openspec/ 目录（由 openspec init 创建）、openspec CLI 在 PATH 中、且 OpenSpec 没有被 关闭（见切换到别的模式）。
  3. 否则就是 lite，这是 Chorus 原生的兜底模式，什么都不用安装。

如果你在用不了 OpenSpec 的地方钉死了 CHORUS_SPEC_MODE=openspec，会话会明确说出来，并且工作流 会停下，而不是悄悄换成别的形态。

请先消除原因（安装 CLI、执行 openspec init，或重新启用 OpenSpec），或者改选一个能用的模式。你 要求过的模式绝不会被静默降级。

无法识别的 CHORUS_SPEC_MODE 值会按未设置处理，并给出说明；请使用上述三个精确值。独立技能分发包不包含规格模式路由，仍按自由格式编写。

安装与初始化

Section titled “安装与初始化”

OpenSpec 是 Fission AI 提供的一个 Node CLI。先全局安装，再在 Agent 编写方案的仓库里初始化：

Terminal window
npm install -g @fission-ai/openspec
openspec init

openspec init 会创建 openspec/ 工作目录（changes/、specs/、配置及说明文件）。启动时解析的 运行时需要重启会话；dsh 需要重新加载插件；OpenClaw 在下一次规格模式步骤重新解析。解析所在进程必须 同时能找到 openspec/ 目录与 CLI。

插件安装见智能体平台参考。

proposal、develop、yolo 中的变化

Section titled “proposal、develop、yolo 中的变化”

模式开启后，proposal、develop、yolo 技能会以一个 kebab-case slug 在磁盘上编写变更，并把三类 文件镜像进 Chorus 方案的文档草稿：

  • PRD：openspec/changes/<slug>/proposal.md
  • 技术设计：openspec/changes/<slug>/design.md
  • 规格（每个能力一份）：openspec/changes/<slug>/specs/<capability>/spec.md

openspec/changes/<slug>/tasks.md 不被镜像：Chorus 的任务草稿才是任务的唯一真实来源， 因此 OpenSpec 的任务清单留在磁盘上。

为了让后续运行能恢复该变更，方案描述里会带上一行精确内容：

OpenSpec change slug: <slug>

镜像是逐字节忠实的，插件把每个文件的字节流写入草稿，而不是让模型重新逐字敲一遍内容，从而保证 磁盘文件与 Chorus 草稿完全一致。你无需自己执行，这由插件的技能借助原生 MCP 客户端 chorus mcp call <tool> --arg-file content=<file> 完成；仅当 chorus 命令行工具不在 PATH 中时，才回退到旧版 chorus-api.sh / chorus-mcp-call.sh 封装脚本。具体契约（其遇错即停规则 与审批后的再同步）保留在权威来源中，本页不再复述，参见 docs/OPENSPEC_MODE.md 与插件技能 public/chorus-plugin/skills/openspec-aware/SKILL.md。

openspec archive 何时运行

Section titled “openspec archive 何时运行”

openspec archive 被推迟到变更的最后一步。当该变更的最后一个任务通过验证后，Agent 按所在运行时的 钩子提醒或技能说明运行：

Terminal window
openspec archive <slug>

归档会把该变更移出 openspec/changes/，并把其规格增量合并进 openspec/specs/ 下的长期规格。 随后插件会把更新后的 openspec/specs/<capability>/spec.md 文件反向镜像回对应的 Chorus 文档， 在此之前变更一直在进行中，Chorus 只会看到增量规格，因此不存在需要处理的半合并状态。

切换到别的模式

Section titled “切换到别的模式”

三个开关，按优先级排列：

  1. CHORUS_SPEC_MODE（所有运行时）。最直接的控制方式，它直接说出你想要哪个模式，而不是描述 你想避开什么：

    Terminal window
    export CHORUS_SPEC_MODE=lite   # Chorus 原生本地规格
    export CHORUS_SPEC_MODE=off    # 自由格式，不写本地规格文件

  2. enableOpenSpec userConfig 开关（仅 Claude Code 插件，默认开启）。在插件的安装配置中把 它关掉，即可在插件层面让 OpenSpec 变为不可用，包括归档提醒。

  3. CHORUS_OPENSPEC_MODE=off 环境变量（所有运行时）。这是更早期的、按 shell 生效的 OpenSpec 退出方式，目前仍然有效：

    Terminal window
    export CHORUS_OPENSPEC_MODE=off

请注意后两者现在的含义：它们让 OpenSpec 不可用，于是会话落到 lite，而不是落到自由格式。如果 你完全不想要本地规格文件，请显式选择 off。无论用哪种方式，磁盘上已有的 openspec/ 目录都保持 不动，新方案也不会加上 OpenSpec 的 slug 行。

面向 Agent

Section titled “面向 Agent”
  • 触发条件。 proposal、develop、yolo 技能使用运行时已解析的 CHORUS_SPEC_MODE。有注入的 ## Spec Mode 时读取该上下文；OpenClaw 则在每次规格模式步骤运行随插件提供的解析器。其他运行时 缺少注入上下文时，按其技能的备用流程处理，不要根据文字说明自行重写解析规则。 CHORUS_OPENSPEC_ACTIVE=1 表示可用的 openspec；lite 遵循 spec-lite，off 内联编写。 显式要求的 openspec 无法满足时必须停止，不能回退。最后一个任务通过验证后，按运行时的钩子 或技能说明执行 openspec archive <slug>，不要假定所有运行时都有 PostToolUse。
  • 约束。 每一次文档草稿的镜像调用都必须经由 chorus mcp call <tool> '<json>' --arg-file content=<file>（原生 MCP 客户端），并把文件字节 逐字节流式写入；仅当 chorus 不在 PATH 中时，才回退到旧版 chorus-api.sh mcp-tool / chorus-mcp-call.sh 封装脚本。切勿把文档内容内联重敲，且遇到任何错误都要停止。不要镜像 tasks.md。方案描述必须带上精确的 OpenSpec change slug: <slug> 一行。模式不是 openspec 时，不要搭建 openspec/changes/，也不要加 slug 行。独立的 public/skill/ 分发包不支持规格模式。
  • 引用来源。 public/chorus-plugin/bin/resolve-spec-mode.sh（模式解析的唯一真实来源）、 docs/OPENSPEC_MODE.md（面向用户的概述），以及权威技能 public/chorus-plugin/skills/openspec-aware/SKILL.md（Claude Code）与 plugins/chorus/skills/openspec-aware/SKILL.md（Codex）。