CM Workflow

安装在 Codex 或 Claude Code 中的规格驱动开发工作流。 从明确需求、人工确认，到实现、独立审查与测试，让每项交付都有可检查的依据。

快速开始 · 升级旧版本 · 选择命令 · 支持范围 · 使用手册 · 更新日志

最近更新

0.16.1

• 安装时会问你要不要开启新版提示。此前安装完只有一句含糊的「自动更新器未自动启用」，已经开启的人也会看到这句（是错的），没开启的人又不会当回事，结果几乎没人用上这个功能。现在安装器会先看你实际配没配，再决定说什么；没配且是手动安装时，问一句、你答 y 才写入。用 --yes 静默安装的不会被改动任何配置，只会打印该加什么。
• 它只加一条「有新版就告诉你」的提示，不会顺手打开后台自动升级——那是另一回事，仍需你自己决定。你的 settings.json 里原有的内容（比如自定义状态栏）不会被动。

0.15.4

• /cm-check 新增快速模式：日常只想确认「装没装对、版本对不对」时，跑快速检查约 12 秒出结果，不再等十几分钟。完整检查的时间几乎全花在逐个文件核对引用关系上，快速模式跳过这一段。结论会明确标为「仅机械检查」而不是「通过」——跳过的部分不会被说成检查过了。机械检查本身发现的问题照常报错，不会被跳过。

0.15.3

• /cm-check 在 Claude 版安装上不再假报 BLOCKED：有两组检查查的是 Codex 插件专属文件，Claude 版安装本来就没有，此前只能算「查不了」，于是健康的安装也永远拿不到 PASSED。现在按安装方式区分：不属于本安装方式的产物记为「不适用」，而真正证据不足的仍然照常阻塞——不是靠放水换来的通过。
• 顺带修掉 cm-check 报告里的版本号在 Claude 版安装上总是空的问题。

0.15.2

• 同 feature 并行开发现在可用：无依赖、改动文件互不重叠的任务可分组，各自在独立 Git 工作树开发，再串行合并回主分支，成员 QA 延后到该 feature 最后一个任务统一执行。此前这个能力只存在于代码里、没有文档，从正常入口用不到。需要注意的是：当前会话模式下写代码仍是逐个进行，并行重叠的是审查与流程开销，不要按成倍提速预期。
• 升级注意：并行成员分支改名为 cm/{批次前缀}/{feature}/{任务号}。此前被阻断的成员会留下不带批次前缀的分支并永久占住名字，导致同一任务再也跑不了批次。升级前创建、尚未跑完的并行批次请用旧版本收尾。
• QA 环境支持桌面与后端/CLI/库项目：此前只能填 Web / App / 小程序，纯后端或命令行项目要开 QA 只能谎报成网页。现在可以如实声明。
• METRICS 新增「执行方式」列：区分任务是串行跑的还是并行组成员，这样才能看出并行到底省了多少时间。

0.15.1

• cm-security 现在会记运行日志：安全扫描开跑与收尾各写一条运行日志（范围、结论词、发现数量、覆盖率、报告路径），与其余主流程命令一致；扫描逻辑、报告门禁与只读边界均未改动。此前 cm-security 是唯一没接入运行日志合同的主流程命令，cm-check 会因此报一处断链。
• 修复 Claude 安装下的版本号误判：~/.claude 是 Claude Code 自己的主目录，那里出现与 CM 无关的 VERSION 文件时，cm-check 会把它当成 CM 版本——轻则版本号报错，该文件版本号更高时 cm-check 会直接返回 blocked 跑不下去。现按安装模式读取版本标志，Claude 安装认 templates/cm-VERSION，源码仓库仍认根 VERSION。

0.15.0

• 兼容性变更（升级前必读）：旧布局执行存储恢复时返回 store_layout_legacy，请用旧版本收尾或退休该 runId，旧文件不会自动迁移；显式将 roles.browser_qa.adapter 设为非 browser 却沿用含 browser 的默认测试策略会被拒绝，需要浏览器 QA 时请改为 browser（保留 model: none, source: local）或删除角色覆盖以继承默认值，不需要时请显式将 policies.tests 设为如 [logic, commands]，阻塞 browser 用例仍须另行处理验收范围并重新审批；含新字段的运行日志会被旧版本按未知键拒绝，请用 0.15.0 或兼容该字段的后续版本继续运行，不要用旧版本回放这类日志。
• 同 feature 并行开发：无依赖任务可在各自工作树中并行开发，再串行合并到主分支，成员 QA 延后到末任务统一执行；批次会自动提交与合并，首次推进前请保持 Git 主工作区干净（含未跟踪文件），被阻塞成员的 WIP 与原因会保留。
• 规格审批位统一写入：cm-prd 与 cm-ai 共用 .cm-specs-status 原子写入入口，模型不再手拼审批文件；cm-ai 新增 --approve --approval-response，记录审批后重新核验准入，--yes 不能代替审批。
• cm-security 报告门禁：新增 --finalize --scan ... --review ...，由代码校验逐路径复核、补齐漏报并判定报告结论，模型不再自述最终状态；无发现且扫描覆盖为 FULL 时仍为 REVIEWED_PARTIAL，报告保留通过校验的分析与修复建议。
• 浏览器验收能力提前声明：开启 QA 且规格需要浏览器验收时，单任务与批次入口在启动或恢复时要求显式传入 --browser-qa available|unavailable，不再等到最后一步才暴露能力缺失；不可用时请换到具备浏览器能力的会话，或调整验收范围并重新审批规格，这是能力声明，并非自动探测。
• 开发阻塞原因可追溯：开发结果 blocked 的可选 reason 现在能从 CLI 结构化输出落盘为 blockedReason，并保留在并行成员日志和 WIP 提交正文中，恢复排查时可查看具体原因。

0.14.0

• 运行定义不再手写：cm-ai 准入新增只读 --print-run-definition，把它已经解析出的 specs/代码根、feature 与任务直接生成为合法运行定义（--scope 必填，因为"本任务允许改哪些文件"是框架推不出来的唯一一项）；invalid_config 改为点名多余/缺失字段、版本与文件类型。
• N6 QA 更贴合实际进度：feature 未完成时只执行已完成任务的用例，其余记入 deferred_cases 延后到 feature 收尾；five_tasks_without_qa 不再把已收尾 feature 的历史计为积压；QA 因宿主或环境证据问题整体 BLOCKED 时可用 --rerun-blocked-qa 显式重跑一轮，QA 结束同步写回状态镜像。
• 审查证据更可判：受保护检查的证据追加测试计数（host check exited 0 (tests 27, pass 27, fail 0)），原始输出仍不进入审查数据。
• cm-fix 先复现再修：按描述未复现时不直接进观测闭环，先沿输入值、前置状态、时序、环境、规模五个维度单维度构造场景，上限 3 个场景或 15 分钟，命中即作为红灯测试骨架；缺陷档案新增复现尝试记录。
• cm-init 配置核验：机械核验配置草稿与所选运行时预设一致，并按版本控制与 UI 模块事实裁剪新建配置的 delivery/tests。

0.13.4

• 第二轮真项目 dogfood 修复：在 specs 与代码分离的真实项目上再跑一遍 cm-init → cm-prd → cm-ai（Codex 写码、Claude CLI 独立审查、feature 收尾 QA）并修复沿路暴露的 3 处运行时缺陷——cm-init 现在机械核验配置草稿与所选运行时预设一致并按项目事实裁剪新建配置的 delivery/tests；cm-ai 的 N6 在 feature 未完成时只执行已完成任务的用例、其余记入 deferred_cases，five_tasks_without_qa 不再把已收尾 feature 的历史计为积压；QA 因宿主/环境证据问题整体 BLOCKED 时可用 --rerun-blocked-qa 显式重跑一轮，QA 结束同步写回状态镜像。详见更新日志。

0.13.3

• cm-runtime 直接敲就是向导：不带参数运行时按编号三问——改哪一层（当前项目 / 用户级默认）→ 手上有哪个 AI（只有 Codex / 只有 Claude / 两个都有）→ 谁写代码，预览后确认才写入，然后回显有效配置；非终端环境只打印用法并退出 2，脚本化仍用 show / set / unset --user。
• 中英文提示跟随系统语言：安装器、向导与人类可读诊断按 CM_WORKFLOW_LANG > LC_ALL > LC_MESSAGES > LANG > Node Intl 判定中文或英文（Windows 安装器传 Get-Culture）；预设名、机器字段与退出码不变。

0.13.2

• 安装时声明单/双 AI 与谁写代码：install.sh / install.ps1 / install-codex.sh 装完后问一次"只有 Codex / 只有 Claude / 两个都有→谁写代码"，保存为用户级默认 ~/.cm-workflow/runtimes.yml（--yes 或非终端跳过）；配置解析顺序改为 项目 > 用户默认 > 未声明，cm-init 有默认时不再重复询问。
• 新增 cm-runtime：show 查看当前有效声明与来源，set <preset> 切换当前项目，set --user / unset --user 管理用户默认；只改派发偏好，不影响已创建的任务运行。

0.13.1

• 真项目 dogfood 修复：在 specs 与代码分离的真实项目上把 cm-init → cm-prd → cm-ai 跑到 run_done（Codex 写码、Claude CLI 独立审查、N6 QA），修复沿路暴露的 11 处运行时缺陷——cm-prd 摘要门禁与会话恢复死锁、cm-ai 准入标点、开发结果校验顺序、会话模式审查超时、Claude CLI 新事件与心跳上限、开发/审查包携带已批准规格、已完成 run 事后附加 QA 与中断 QA 重跑；详见更新日志。

0.13.0

• 双运行时协作与容灾：runtimes.available 声明可用运行时，protected host 按 coder/reviewer 配置跨家派发（2026-09-17 已完成真实模型双向单文件小任务验收各一次，均停在 N6 QA 待决；QA/N8 不在验收范围、仍未验收）；--failover 仅在启动前探测选路，scripts/cm-failover.mjs 提供只读断点交接，详见能力边界。

0.12.0

• 安全扫描：新增 cm-security，结合业务地图检查代码改动，输出漏洞候选、业务影响和未检查范围。
• 自动升级：cm-check 默认检查新版并升级受支持的已管理安装；离线或不支持自动升级时明确提示。

0.11.0

• 影响分析与单测：cm-test 自动分析分支差异和单测覆盖率；明确要求“补齐单测”后，继续补测、重跑与审查。

查看完整更新日志 →

从需求到交付

AI 写完代码以后，你还需要知道：需求是否对齐、测试是否真正执行、修改是否经过独立审查，以及中断后该从哪里继续。CM Workflow 把这些要求放进同一条开发流程。

需求 → 可开发规格 → 人工确认 → 实现 → 独立审查 → 测试与 QA → 交付

在 Codex 中，一次典型使用是：

$cm-prd ~/projects/my-app-specs

审阅生成的需求、设计和任务，明确确认后：

规格已确认，开始实现。
$cm-ai ~/projects/my-app-specs ~/code/my-app

新任务默认进入 JS workflow，无需再指定“使用改造后的 JS workflow”。 Skills 提供业务规则与工种能力，JS 运行器管理执行阶段和证据门禁，当前 Codex 或 Claude Code 会话执行实际工具请求。

tasks.md 是任务状态的权威来源。聊天里的“完成了”、静态分析和界面进度，不能替代真实测试、独立审查与完成凭证。

快速开始：Codex

准备好 Git、Python 3.9+、Node.js 24.14+，以及带有内置插件创建辅助工具的当前 Codex。安装器和部分共享工具的最低要求是 Node 18；默认 JS 开发流程需要 Node 24.14+。

以下主路径以 macOS 为准；其他环境先看支持范围。安装与升级使用同一条命令：

npx @aibyzero/cm-workflow@latest install

已有源码安装可以直接使用这条命令升级，无需先卸载；仍更新同一个 Codex 插件。首次安装可能出现 npm 下载确认，已有插件会另外询问是否覆盖。

需要从 GitHub 源码安装时，将仓库克隆到独立目录，不要放在 ~/plugins/cm-workflow，该目录由安装器管理：

git clone https://github.com/kingxiaozhe/cm-workflow.git
cd cm-workflow
./install-codex.sh

安装后新开一个 Codex 任务，运行：

$cm-check

自检用于检查安装和工作流合同。具体项目的功能测试与真实模型审查，在后续开发流程中分别执行。

仓库直接分发 Skills 和脚本，无需在仓库根目录运行 npm install 或构建。完整安装行为、覆盖范围和卸载说明见安装指南。

需要固定版本时可使用 npx @aibyzero/[email protected] install，请在 CM Workflow 源码仓库以外的目录执行，例如用户主目录。npm 安装入口复用原安装器，要求与覆盖范围见安装指南。

升级旧版本

推荐直接执行 npx @aibyzero/cm-workflow@latest install。升级仍然使用同一个安装器：替换其管理的插件目录，保留独立源码仓库、项目代码与规格。直接修改已安装插件的内容会被覆盖；之后再运行旧源码的安装器可能降级。

继续使用源码升级时，在原来的 源码 checkout 中先检查本地修改：

git status --short

有未提交修改时先保存或处理；工作区干净后执行：

git switch main
git pull --ff-only origin main
./install-codex.sh

安装器会列出覆盖内容并要求确认。明确接受无人值守覆盖时，可以使用 ./install-codex.sh --yes。升级 Node 到 24.14+ 后，安装与运行都应使用该版本。

完成后新开 Codex 任务，运行 $cm-check，再使用 $cm-ai。只更新 Git 源码不会更新已安装插件；已打开的任务也可能仍加载旧版 Skill。

升级后的执行规则：

• 新任务默认走 JS；不支持的宿主、环境或配置会明确阻断，不会静默切回旧流程。
• 已有 JS 运行按原身份、配置和恢复约束续接；不能通过更换运行标识绕过阻断。
• 已确认的旧兼容任务继续沿原流程恢复，不会因升级自动迁移。记录缺失或归属冲突时先只读核对；新任务只有在用户明确选择时才使用旧兼容流程。

选择命令

以下是十个核心入口（含独立配置工具 cm-runtime）。Codex 使用 $cm-*，Claude Code 使用 /cm-*。

你想做什么	Codex 入口	产出或下一步
把模糊点子变成需求	$cm-idea	形成 PRD，进入规格阶段
第一次接管已有仓库	$cm-init	建立项目上下文与规范
把需求拆成可开发任务	$cm-prd {specs路径}	需求、设计、任务和审批材料
执行已经确认的规格	$cm-ai {specs路径} {项目路径}	实现、审查、QA 与交付记录
安全扫描与业务复核	$cm-security（全量用 --all）	漏洞候选、业务影响与未检查范围
测试已有功能	$cm-test {项目路径}	分层测试结果与证据
修复可复现缺陷	$cm-fix {specs路径} {项目路径} {问题}	红灯测试、最小修复、回归验证
整理结构并保持行为	$cm-refactor	按行为等价约束分批重构
查看/切换运行时声明	$cm-runtime 三问向导；支持 show / set / unset --user	会话随对话语言、终端随系统语言中英提示；仅影响新 run
检查安装与工作流	$cm-check	环境、引用和合同检查结果

需要单独讨论方案或研究复杂问题时，可显式使用可选工具 $external-expert。外部建议由本地核验，不能代替独立代码审查或测试证据。详见使用手册与外部专家合同。

跑通第一个项目

1. 准备代码与需求

假设代码在 ~/code/my-app，规格放在独立的 ~/projects/my-app-specs。将 PRD、需求说明或原型材料放入 specs 的 docs/。

已有代码仓库可先在代码目录中运行 $cm-init；全新项目直接从 $cm-prd 开始，由规格确定项目形态与初始化任务。

2. 生成并确认规格

$cm-prd ~/projects/my-app-specs

每个 Feature 会形成：

requirements.md   # 用户故事与验收条件
design.md         # 技术方案与修改边界
tasks.md          # 可执行任务与权威任务状态
test-cases.json   # 可选的结构化测试合同

检查需求、方案、任务和验收条件后，明确确认规格。审批绑定完整规格清单；需求、设计或测试目标变化后需要重新确认，正常勾选任务不会被当成需求变更。

3. 执行与检查交付

规格已确认，开始实现。
$cm-ai ~/projects/my-app-specs ~/code/my-app

JS 运行器按 N1–N8 管理初始化、Feature、开发、审查、任务完成、QA、上下文重载和收尾。任务完成与整轮运行完成分别检查；必需 QA 或文档核验未通过时，不能宣布整轮交付完成。

交付策略可以是本地 diff、本地 branch 或 draft-mr。实际 Git 操作仍受宿主能力和当前授权约束；配置 draft-mr 本身不会授予 push 或创建 PR/MR 的权限。生产发布保留人工确认。

测试已有功能

没有测试合同时，先从已有代码生成用例草稿：

$cm-test ~/code/my-app 用户登录 --generate-cases

生成草稿后流程停止，并返回 test-cases.generated.json 的实际路径；这一步不会执行用例。审阅预期行为，把已确认用例的 origin 改为 user，并删除对应的 [需确认] 标记，再运行：

$cm-test ~/code/my-app --cases {生成结果返回的用例文件路径} --all

将占位符替换为那份已确认草稿的实际路径。已有 specs 测试合同时，也可以用 --specs {specs路径} --feature {Feature完整名称} 选择相应用例。

证据层	能说明什么
logic	代码入口、分支与状态逻辑是否支持预期；属于静态检查
commands	项目声明的测试、类型检查或构建命令是否真实运行并通过
browser	在可用且获准的浏览器环境中，用户操作是否产生预期结果

cm-test 默认不修改业务源码，但会写测试报告与证据。缺少环境或工具时会报告缺口，不把静态检查算作浏览器通过；需要修复时明确进入 cm-fix。

中断后如何继续

CM 从磁盘记录恢复上下文，而不是只依赖聊天历史。

记录	用途
requirements.md、design.md、tasks.md	规格与任务状态
.cm-specs-status	人工审批与规格清单
.cm-status.json、.cm-run.json	当前状态与恢复指针
.reviews/	交接、独立审查和相关凭证
运行日志.jsonl	specs 内的权威事件日志
METRICS.md、LESSONS.md	执行度量与复盘经验

再次调用 cm-ai 时，先核对已有运行的归属和恢复条件。恢复受原配置、内容和会话身份约束；不满足时明确阻断。已登记但结果未知的审查不会自动重发，必须先核对并按规定处理。

跨项目日志位于本机 ~/.cm-workflow/logs/，是可重建的私有镜像，不是遥测。它只保存规范化运行元数据，不收集源码、Prompt、模型回答或凭证。详见日志合同。

支持范围

安装成功、共享工具通过 CI 和完整 JS 开发实测是不同的验证范围。

环境	安装 / 入口	JS 开发流程的当前边界
Codex · macOS	npx @aibyzero/cm-workflow@latest install 或 ./install-codex.sh；$cm-*	默认 JS 入口已接入，有本地安装与工具执行证据；不等于所有业务场景、真实模型审查都已验收
Claude Code · macOS	./install.sh；/cm-*	使用同一 JS 核心，当前会话入口已接入；2026-09-17 真实模型双向单文件小任务验收各一次，均停在 N6 QA 待决；QA/N8 不在验收范围、仍未验收
Linux / WSL2	对应 Bash 安装器	runner 已有平台准入；尚缺目标环境端到端实测，Claude 隔离配置诊断目前限 macOS
Claude Code · 原生 Windows	install.ps1；/cm-*	PowerShell 安装和共享工具有 CI 覆盖；原生 Windows JS runner 尚不支持
Pi / BYZ	Pi package	分发同一组 Skills 与 Prompts；包加载不代表已具备 Codex/Claude 的 JS 工具宿主

所有 JS 开发入口要求 Node 24.14+。同仓 specs、多代码根、批次、受保护写入与审查授权的具体条件见 JS workflow 控制与当前会话入口及 cm-ai 宿主接入。

其他安装方式：Claude Code 与 Pi / BYZ

先按快速开始克隆仓库。Claude Code 在 macOS / Linux 中运行：

./install.sh

Windows 需要 PowerShell 5.1+ 和 Git for Windows（Git Bash）：

powershell -ExecutionPolicy Bypass -File install.ps1

安装后新开 Claude Code 会话，运行 /cm-check。macOS / Linux 还保留历史 /cm:* 别名；Windows 使用 /cm-*。

Pi package 安装：

pi install git:github.com/kingxiaozhe/cm-workflow

Pi 资源加载器直接发现 Skills 与 Prompts，不运行上述安装器，也不会把文件复制到 Codex 或 Claude Code 的全局目录。详细行为见安装指南。

配置与深入阅读

交互安装会询问单/双 AI 与谁写代码，保存到 ~/.cm-workflow/runtimes.yml；--yes / -Yes 或非 TTY 跳过且不写。运行时声明按 项目 > 用户级默认 > 未声明 解析。$cm-runtime 可查看/切换，已创建 run 保留原配置。

项目配置放在代码根目录的 .cm-workflow.yml，可从配置模板开始。角色路由和执行策略必须落在实际宿主已支持的能力内；声明模型或适配器不等于已实际调用。

文档	内容
使用手册	命令参数、场景和完整流程
安装指南	覆盖安装、可选更新器与卸载
JS workflow 控制	当前宿主、恢复、QA 与能力限制
Workflow 配置	角色与策略字段
任务门禁	交接、Review 与完成校验
公开示例规格	规格文件的组织方式

维护与贡献

skills/ 保存工作流与角色规则，runtime/js/cm-ai/ 保存共享 JS 实现，scripts/ 提供入口与验证工具。compat/claude-commands/ 只做历史命令转发；根 package.json 保存 Pi/BYZ 包元数据和 npm 安装命令入口，无 npm 依赖或构建脚本。

入口目录与计数：10 个核心入口（包括独立工具 cm-runtime），11 个工种 Skill 与 6 个兼容 agent；独立工具不参与工种配对。

skills/
├── cm-{idea,init,prd,ai,test,security,fix,refactor,check}/
├── cm-runtime/                  # 独立声明工具，不进入 N1–N8
├── cm-*-engineer/、cm-*-expert/、cm-*-manager/、cm-doc-syncer/
└── codebase-context/、external-expert/、darwin-skill/
compat/claude-commands/cm-runtime.md  # macOS/Linux /cm:runtime 别名
scripts/cm-runtime.mjs           # 原子配置写入与共享诊断

基础检查：

./scripts/cm-check-runtime.sh
python3 scripts/validate-public-repo.py
python3 scripts/scan-public-safety.py

升版或修改 Pi/BYZ、Codex 分发面时，从干净 checkout 运行分发面冒烟；它校验 Pi manifest、用本机 BYZ 检查本地 workflow root，并把 Codex 安装隔离到一次性 HOME：

./scripts/cm-release-smoke.sh

按改动范围补充对应夹具与实跑，详见 CONTRIBUTING.md。版本以 VERSION 与插件 manifest 的基础版本为准；安装副本的 +codex.* 后缀用于刷新缓存。

安全问题请按 SECURITY.md 私下报告。

License

MIT License。Darwin Skill 与 Kenney CC0 素材的来源和许可见 THIRD_PARTY_NOTICES.md。