cm-workflow

CM Workflow

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

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

最近更新

0.17.0

• 升级注意：新建 cm-ai 运行改用 --control-config 选能力（development / bootstrap / qa / qaFix 四个模式），不再传一串 --allow-*；--human-authorized 已删除。已经在跑的旧运行继续按原协议走完，两种入口不能互用。
• 审查不再逐轮要授权：常规独立审查在已确认范围内自动推进最多两轮；N4 不再先让作者自审。门禁的目标收缩为「防手滑、防过期证据」，文档写明它不承诺抵抗拥有完整写权限的人。
• N6 质检改成固定检查点：feature 完成、连续五项没做 QA，以及 migration、认证、授权、支付、API 这些关键路径命中就触发，不再打四维分数。
• 手工走 N1–N8 的项目也能核对改动清单：N3 编辑前先 capture-baseline，N4/N5 和完成入口按实际新增、修改、删除的文件核对 changed_files；兼容任务第二轮阻断后可以做一次有来源声明的受控补正。
• 提醒更结实：设置、锁和状态文件被换成链接、管道或超大文件时直接跳过不卡住；发送失败能从 notify.log 看出是超时（5）、断网（3）还是意外错误（6）。

0.16.9

• 新增 /cm:notify（Codex 里是 $cm-notify）：卡住、结束、等待的手机提醒可以在 Bark（iOS）和 pushplus（微信）之间一条命令切换，同一时刻只开一个。能看到两个渠道的密钥有没有填好（只说填没填，不显示内容），能发一条测试推送确认真的收得到，也能先预览、再自定义提醒的标题和正文。暂不支持 Windows。见使用手册。
• 答案缺失、无效、迟到或进程断了，cm-ai 不再卡住：外部应答缺口第 1～4 批补完。遇到这些情况，现在会以可以重试的方式退出，或者直接拒绝并用中文告诉你下一步。比如文档同步失败只重做文档同步，不用把开发重做一遍；审查授权被拒后，只有你明确确认才会重新授权，不会自己重试。
• 提醒更省心：默认文案把「下一步」放第一行，时间改成本机时间；运行时读取提醒设置也更安全：设置文件被换成符号链接、命名管道等非普通文件时，会关闭提醒并记一行诊断，不会跟随链接，也不会等待命名管道的写入方。读取仍是同步操作，在很慢的文件系统上没有超时上限。
• 测试在 CI 里更快：把最慢的两份测试拆开并行跑，CI 的测试分组也按实际耗时分配，不影响任何使用行为。

0.16.8

• 卡住时能推到手机：在 ~/.cm-workflow/notify.json 配一条本机命令后，流程停在要人处理、整个流程跑完、宿主等你应答超时（检查类按 45 分钟）、宿主开着却 45 分钟没人发下一步，都会提醒一次；同一件事 6 小时内只发一次，带限流，发送失败不影响流程。见使用手册。
• 提醒能做到什么写清楚了：只发一次不补发、关机或睡眠时不发、没有常驻监督进程；会话自己派出去的后台命令不在范围内。cm-ai 宿主说明「启动前」新增派发纪律：后台命令带超时、不另写等待脚本、非交互调用 Codex 要关输入、拿到终态先核对再重跑。
• 省 token：cm-ai 每次启动必读的宿主说明从 75KB 减到 25KB，异常恢复按需再读；单任务、cm-prd、cm-fix 收尾时建议换新会话开始下一项；新增只读的 token 用量报告 scripts/cm-token-report.mjs。
• 质检不再卡死：执行超时、范围内文件被改、浏览器证据放错位置、已作废任务的用例、被独立 cm-fix 修过的任务，都有明确出口；cm-fix 二轮诊断不合格或原因审查无结论，也不再停在 unknown。
• 受保护路径与批次选择：任务 scope 含 AGENTS.md、CLAUDE.md 等保护文件时在建运行前拦截；--feature N.slug 可显式先做后面的批次；并行组「只能新建文件」改由 runtime 强制；当前会话开发可指定另一工具审查（--review-runtime）。
• 手动核对宿主：node scripts/cm-patrol.mjs --report 查看哪个宿主进程没收尾。

0.16.7

• 首次规划按目标组织任务：相关低风险文案、样式和小交互可合并为能独立验证和回滚的任务；保护基线、明确独立边界及真实契约依赖继续保留。
• 既有运行保持兼容：不改角色配置、已有任务列表或每任务 N4 独立审查；在途规划请求继续使用原始指引。
• 收益仍待验证：有限规划对照为 2→2、4→4，未显示任务数下降，也未证明 token 或费用节省；高风险仅验证原设计门禁。

0.16.6

• 运行时配置默认保留：打开 cm-runtime 先看当前配置和来源，主动选择修改才进入预设向导；高级模型入口只提供说明和校验方法。
• 外部模型按 provider 配置：单任务、批次及修复可显式启用 cm-model-setup.mjs 的模型及可选强度；宿主保持当前模型，run 冻结参数，未知调用停止重派。见配置与恢复边界。
• 确认前看清影响：预览目标、字段变化和项目覆盖关系，最终 [y/N] 回车不保存；确认期间配置改变会要求重新预览。安装后的配置可跳过，已有用户默认优先保留。
• 保留模型别名并提示兼容性：切换预设不改已有模型或正在运行的任务；配置校验不代表新适配器一定支持该模型。

0.16.5

这一版修的都是拿 cm-ai 跑真实项目（AI潮）时撞上的阻断：跑到一半卡死、报错看不懂、只能手改文件才能继续的情况，现在大多有了明确的出口。

• 中断和超时不再卡死运行：宿主在审查中途被杀或审查进程出错，可以在原运行上留痕放弃并重派审查；在开发或收尾中途被杀，可以留痕放弃这一步、正式关闭原运行，再新建运行重做；QA 评估超时、检查超时都能重试，环境原因造成的 QA 阻断可以在原代码上重跑。
• 重试是真的重做：审查退回后第二轮用第二轮的答案，清理后重试真正重跑开发，检查没过不送审；重试次数和收尾不会再撞上限把自己锁死。
• 规格中途改了也能接着跑：任务进行中重新批准规格，只要改动只涉及其他任务，就能显式换绑到新规格继续；批次成员会写明能走的出口。
• 报错说人话：启动参数不对会点名是哪个参数、和创建时哪里不同；cm-prd 审查闸门的每种拒绝都带固定错误码和原因，不再只报 unavailable；扫描代码目录时跳过系统和构建杂文件，出错写明路径。
• 规则任务（通常是 T-002）能用单任务驱动跑完：会话核验没通过时停在可重试的状态，改好后在原运行重新生成和核验，不会再落到无法恢复的 unknown。
• 重做任务会带上旧的审查意见：审查轮次用完后新建运行重做，第一轮开发和审查会看到上个运行最后一次审查的问题清单（只作参考，不跳过审查）。

0.16.4

• 项目类型通知不再导致审查失败：Claude Code CLI 2.1.x 在 Xcode 等项目目录里会多发一条「项目类型」通知，而且可能排在初始化消息前面，CM 的审查解析器不认它，真实审查就以 transport_incomplete 收场。现在审查方和开发方的解析器都能接受这条通知，其余消息仍按原规则严格校验。
• 规格批准后还能继续改：批准规格时，.cm-specs-status 里「上一次变更记录」的编号被丢掉，此后任何 cm-prd --change 都报审查记录被改动，规格批准后就改不了。现在批准和摘要发布都会保留它；已经丢了的规格，按 skills/cm-prd/references/js-change-recovery.md 核对：能证明是哪一份变更归档对应这次批准时才人工补回，证据有歧义就停下交人重审。
• 大任务不用再手改安装文件：一个开发答案超过 64 KiB（一次写好几个源文件）时宿主会拒收。现在单任务和批次宿主都支持 --input-limit BYTES（最多 4 MiB），只影响传输，恢复时也能换。
• cm-prd 自检命令有输出不再误判失败：驾驭员跑自检命令时，只要命令打印了东西就被当成失败，现已修正。
• /cm-check 按实际运行时打标签：从 Claude Code 跑自检时，独立审查通道不再被误标成「已声明未派发」。新增 --runtime codex|claude，优先级为 --runtime > 环境变量 CM_RUNTIME；两者都没有时标「未判定」，不再乱下结论。

0.16.3

• 审查过的任务可以显式重做了：独立审查用过的交接文件不能覆盖。QA 因宿主或环境证据不足而 BLOCKED、且满足重跑条件时，原本就能在原运行上用 --rerun-blocked-qa 重跑 QA；但确需重新开发、新建运行时，会一直报 handoff_exists，任务就跑不起来。现在报错会直接给出三条出路：原运行修订填错的 QA 配置、原运行重跑被环境卡住的 QA，或把任务改回 - [ ] 后用新运行带 --supersede-reviewed-evidence --supersede-reason 重做。旧交接和审查回执按内容摘要归档到 .reviews/.superseded/，不会删除。
• 换一个聊天会话也能接着跑：cm-ai 的单任务运行（及其 QA 修复子运行）和 cm-fix 都能由新会话接手原运行；批次运行和旧受保护兼容入口不在此列。新会话第一次签审查授权前会记进存档，并被排除在审查员之外，只读打开不写记录。0.16.1～0.16.2 期间已换会话签过授权的旧 cm-fix 运行，仍只能由当时签授权的会话继续。
• 流程不再把自己锁死：cm-prd 的拆分审查可以修正需求与设计，自检失败可以交人裁决，原材料中途变了可以正式结束旧批次再开新批次；cm-fix 的本地步骤结果丢失时可以显式放弃重做，诊断为 design_change 的运行能走到升级收尾，最终审查要求补测试时第二轮也能继续；cm-refactor 审查要求补判官测试时，第二轮可以受控修订。
• 九个工作流宿主都有单步驾驭员：scripts/cm-*-drive.mjs 一次推进一步，先按「这一步会问什么」查齐答案文件再发指令，缺什么在启动前就说清楚，已知的缺口不会再半路把运行留在 unknown；宿主若问到预检没覆盖的问题，驾驭员会明说这一步将停在 unknown。人工文件只提供判断和内容，执行证据只来自真实运行的命令。
• 审查预检能认出错误的模型名：本机 Claude CLI 不认识的审查模型 id（例如 CLI 2.1.x 上的 claude-opus-5-5，应写 claude-opus-5）现在在预检时就判失败，不会拖到真实审查才以 transport_incomplete 收场。

0.16.2

• 重名当场拦下、出错能定位：任务编号重名在建运行时就报错，不再等到红灯测试把一轮做废；失败诊断带上是哪一行代码拦的。CI 改为自动收集全部检查，只固定排除 7 份需要 Codex 沙箱的测试，这 7 份在发版冒烟时补跑；改名前的 METRICS 旧表头也能继续识别。

0.16.1

• cm-fix 能走到收尾：收尾不再只认 delivery: diff；换会话能打开原运行；做过 pod install 的 iOS 项目也能拍基线快照。

0.16.0

• cm-ai 从「跑不完」到「跑得完」：交接文件撞名不再卡死任务；独立审查与 QA 用例的等待时间可以单独调大；新增可选的交付前验证闸门 --verification-precheck，只拦不放。

0.15.5

• 安装时会问你要不要开启新版提示。此前安装完只有一句含糊的「自动更新器未自动启用」，已经开启的人也会看到这句（是错的），没开启的人又不会当回事，结果几乎没人用上这个功能。现在安装器会先看你实际配没配，再决定说什么；没配且是手动安装时，问一句、你答 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 是任务状态的权威来源。聊天里的“完成了”、静态分析和界面进度，不能替代真实测试、独立审查与完成凭证。

详细流程图（建议设计示意）

以下两图是建议设计示意，非当前版本完整正式状态机。图中的阶段、检查项和恢复分支用于讨论流程设计，不表示相关功能均已实现；当前能力与约束以实际运行版本、使用手册和 JS workflow 控制为准。点击图片可查看原尺寸。

阶段总图

展示任务拆解与验收、开发自检、独立审查、测试证据及收尾交付之间的关系，以及问题修复后的返回路径。

异常恢复

展示阻塞或超时后的现场保存、原因判断、有界恢复与暂停决策思路；恢复成功仍需回到对应环节取得验收证据。

快速开始：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/cm-workflow@0.17.0 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、cm-notify）。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 默认查看并保留；主动选修改才进入预设向导	中英提示；预览后明确确认才写；高级模型入口只提供说明；仅影响新 run
切换手机提醒渠道	$cm-notify 查看；bark / pushplus 切换；test 发测试推送；preview 预览文案；off 关闭	同一时刻只开一个渠道；密钥由你自己填进文件，命令只检查能否解析、从不显示；暂不支持 Windows
检查安装与工作流	$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 时，先核对已有运行的归属和恢复条件。恢复受原配置、内容和会话身份约束；不满足时明确阻断。已登记但结果未知的审查不会自动重发，必须先核对并按规定处理。

换了聊天会话时，当前会话模式的单任务运行用 --mode resume 并声明创建运行的原会话即可接手，不需要新建运行（批次运行和旧受保护兼容入口不支持换会话）。卡住时按报错给的出路走，都需要显式授权并留下记录：

卡在哪	怎么继续
QA 配置填错（如漏了测试命令）	保留上一版 workflow 文件，原运行用新的 --workflow-config 加 --allow-qa，再带 --revise-qa-config 旧文件 --qa-config-revision-reason "原因" 续验
QA 因宿主或环境证据不足而 BLOCKED（最新一轮已完成、无失败、轮次未满）	原运行 --rerun-blocked-qa 重跑一轮
审查已用过交接、确需重做开发	把任务改回 - [ ]，新运行带 --supersede-reviewed-evidence --supersede-reason "原因"
cm-fix 某个本地步骤卡在 unknown	先确认旧进程已停，以 --allow-abandon 启动后发 abandon_step 并写明原因；只适用于复现、诊断、测试、修复、回归、复盘、走查等本地步骤，根因审查、最终审查、Learning 写回和交接不适用

具体参数见 cm-ai 宿主接入 与 cm-fix 宿主接入。

跨项目日志位于本机 ~/.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 真实模型双向单文件小任务验收各一次；2026-09-25 在临时项目上用当前会话开发、Claude CLI 独立审查跑到 N6 QA，并实测 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 在 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 的全局目录。详细行为见安装指南。

配置与深入阅读

交互安装可跳过运行时配置；已有用户默认优先保留，主动配置后再以 [y/N] 明确确认保存到 ~/.cm-workflow/runtimes.yml。--yes / -Yes 或非 TTY 跳过且不写。运行时声明按 项目 > 用户级默认 > 未声明 解析。$cm-runtime 默认查看并保留，主动修改时预览影响、保留模型别名，配置改变后须重新确认；已创建 run 保留原配置。

配置独立审查时，--review-model 要写本机 CLI 实际接受的完整模型 id，预检会替你核对；真实审查一次常超过一分钟，建议在审查配置里把 timeoutMs 调大（上限一小时）。没等到结果就超时时记为可续跑的审查超时，同一轮最多重派一次；已经收到部分结果的超时要先核对，不会自动重派。

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

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

维护与贡献

skills/ 保存工作流与角色规则，runtime/js/cm-ai/ 保存共享 JS 实现，scripts/ 提供入口、单步驾驭员（cm-*-drive.mjs）与验证工具。experiments/js-orchestration/ 是历史兼容夹具，CI 单独跑它但不阻断合并。compat/claude-commands/ 只做历史命令转发；根 package.json 保存 Pi/BYZ 包元数据和 npm 安装命令入口，无 npm 依赖或构建脚本。

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

skills/
├── cm-{idea,init,prd,ai,test,security,fix,refactor,check}/
├── cm-runtime/                  # 独立声明工具，不进入 N1–N8
├── cm-notify/                   # 独立提醒渠道工具，不进入 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 别名
compat/claude-commands/cm-notify.md   # macOS/Linux /cm:notify 别名
scripts/cm-runtime.mjs           # 原子配置写入与共享诊断
scripts/cm-notify.mjs            # 提醒渠道切换；发送器 runtime/js/notify-send.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、neat-freak 只读核对原则与 Kenney CC0 素材的来源和许可见 THIRD_PARTY_NOTICES.md。