# CM Workflow 使用手册

CM Workflow 使用手册：从当前目标出发选择正确命令

命令选择 · 首次开发 · 常见路线 · 测试说明 · 状态恢复 · 常见卡点

这不是一份需要从头背完的命令字典。每次回来时，先判断自己**现在想做什么**，再从对应入口开始。 > **记住三条就够了：** 一个代码项目通常只需运行一次 `$cm-init`；新需求先 `$cm-prd`、人工确认后再 `$cm-ai`；`$cm-test` 默认只报告问题，真正修复使用 `$cm-fix`。 ## 先确认你的运行环境 本文示例默认使用 Codex。Claude Code 使用同一套工作流，只需替换命令前缀： | 环境 | 命令写法 | 示例 | | --- | --- | --- | | Codex | `$cm-*` | `$cm-check`、`$cm-ai` | | Claude Code | `/cm-*` | `/cm-check`、`/cm-ai` | 安装后必须新开会话，再运行 `$cm-check`。如果检查通过，就不需要每次任务都重复执行它。 `cm-check` 默认先查 npm 稳定版，有新版就升级已管理的插件，再检查升级后的目录， 不需要另加参数或再次确认。升级后其他 Skills 需新开会话加载。离线时继续本地检查， 但会明确提示“无法确认最新版”。源码仓库、Pi/BYZ 等其他管理器安装保留原方式， 自动升级当前支持 macOS Codex 个人本地市场和 macOS/Linux Claude。 有其他 CM 任务在运行时先结束或暂停；临时只想检查，可说“cm-check，只检查，不升级”。 `cm-ai` 的新任务默认使用 JS Workflow，无需额外指定执行方式。它要求 Node.js 24.14+； macOS 已有本地验证，Linux 尚缺目标环境验证，原生 Windows 尚不支持。 已有运行按原执行方式续接，升级不自动迁移旧任务；新任务只有明确选择旧兼容流程才走兼容入口。 JS 缺少运行条件时会报告缺口，不会静默切回旧流程。默认选择不替代规格审批与各项调用授权。 ## 我现在该用哪个命令？

按当前目标选择 CM Workflow 命令

| 你现在的情况 | 使用入口 | 会改业务源码吗？ | 完成后的下一步 | | --- | --- | --- | --- | | 只有一个模糊点子 | `$cm-idea` | 否，只产出 PRD | 把 PRD 放入 specs 的 `docs/`，运行 `$cm-prd` | | 第一次接管已有项目 | `$cm-init` | 否，但会生成项目规则和上下文 | 准备需求文档或直接测试已有功能 | | 已有需求文档 | `$cm-prd {specs路径}` | 否，只整理规格 | 人工审查摘要、方案和任务 | | 修改已经存在的功能 | `$cm-prd --change …` | 否，只增加变更规格 | 人工审查后运行 `$cm-ai` | | 规格已经确认 | `$cm-ai {specs路径} {代码路径}` | **是** | 查看审查、测试和交付凭证 | | 想测试已有功能 | `$cm-test …` | 否，默认只写报告与证据 | 对失败项决定修环境、补规格或 `$cm-fix` | | 已确认是缺陷 | `$cm-fix …` | **是** | 查看红灯测试、修复和回归结果 | | 只想改善代码结构 | `$cm-refactor …` | **是**，但不得改变行为 | 查看等价性验证和审查结果 | | 想讨论方案、研究问题或查论文 | `$external-expert …` | 否 | 查看外部原始回答、本地裁决与待验证项 | | 查看/切换单双 AI、谁写谁审 | `$cm-runtime` | 仅明确 set/unset 时写声明 | 查看来源与预设 | | 安装或入口不正常 | `$cm-check` | 自动升级 CM 安装，不改业务代码 | 查看升级与自检结果 | ### 不想记命令，也可以直接描述目标 Codex 与 Claude Code 会先根据 Skill 的 `description` 判断入口。自然语言分流不是 硬编码路由：目标明确时可以直接说，目标有歧义时应先确认；需要确定入口时仍可显式 点名 `$cm-*` 或 `/cm-*`。自然表达**只负责选择流程**，不能替代规格批准、生产确认 或其他人工闸门。 | 入口 | 明确点名 | 自然表达 | 模糊或越界时 | | --- | --- | --- | --- | | `cm-idea` | `$cm-idea 帮我梳理这个点子` | “我有个产品想法，先帮我聊清楚” | 已有完整需求文档 → `cm-prd` | | `cm-init` | `$cm-init` | “第一次接管这个仓库，先生成项目规则” | 空项目或普通改代码 → 不触发 | | `cm-prd` | `$cm-prd {specs路径}` | “把这份需求拆成方案、任务和验收标准” | 要求直接编码 → 先确认 specs 是否已审批 | | `cm-ai` | `$cm-ai {specs路径} {代码路径}` | “规格已经审查通过，按 specs 开始实现” | 仅说“继续”或规格未审 → 不批准编码 | | `cm-test` | `$cm-test …` | “验证一下现有登录功能，再用浏览器走查” | 用户只说“好像有问题” → 先测试，不自动修 | | `cm-fix` | `$cm-fix …` | “这个 bug 已经能复现，请按失败报告修复” | 尚未复现 → `cm-test`；新增需求 → `cm-prd` | | `cm-refactor` | `$cm-refactor …` | “只整理这段代码结构，不改变行为” | 要改变功能或修 bug → 转交对应流程 | | `cm-runtime` | `$cm-runtime show` | “两个工具都有，改为 Claude 写、Codex 审” | 不安装、不改当前 run | | `cm-check` | `$cm-check` | “检查一下 CM 是否安装正确，为什么没有命令” | 测试业务功能 → `cm-test` | ## 两个目录不要混淆 CM Workflow 经常同时使用两个目录： ```text ~/code/my-app/ ← 代码项目：真正的源码、测试和 Git 仓库 ~/projects/my-app-specs/ ← specs 项目：需求、方案、任务和运行凭证 ├── docs/ ← 先把 PRD、需求说明、原型说明放这里 ├── 1.user-login/ │ ├── requirements.md │ ├── design.md │ ├── tasks.md │ └── test-cases.json ← 可选，保存测试意图 ├── .cm-specs-status ├── .cm-status.json ├── .cm-run.json ← 当前/最近一次运行标识 ├── .cm-run.lock ← 并发写入锁（自动维护） ├── .reviews/ ← task handoff、独立 Review、PRD 处置回执与测试证据 └── 运行日志.jsonl ``` - **代码项目**回答“要修改什么”。 - **specs 项目**回答“为什么改、准备怎么改、做到哪一步、证据在哪里”。 - 两者可以在不同路径，也可以由你按项目习惯组织；命令里把路径说清楚即可。 ### 可选的项目角色与模型配置 如果不同项目需要不同角色或模型，可以把 `{CM_WORKFLOW_ROOT}/templates/cm-workflow.yml` 复制到代码项目根目录，命名为 `.cm-workflow.yml` 后修改。它只配置角色、适配器、模型别名和测试/交付策略，不保存任何 凭据；配置缺失时仍使用当前默认流程。检查有效配置： ```bash node {CM_WORKFLOW_ROOT}/scripts/cm-workflow-config.mjs --project {代码项目路径} node {CM_WORKFLOW_ROOT}/scripts/cm-workflow-config.mjs --project {代码项目路径} --print-effective ``` 常见的请求分工是：编码角色选择 Codex CLI/订阅，需求和方案角色选择 Claude/Fable 等 兼容 API，测试和浏览器 QA 使用本地工具，外部专家继续通过显式浏览器调用和既有降级 链运行。`route_state: declared-adapter` 只代表项目请求了该适配器，当前运行时没有 观察到它实际执行；不要把配置别名当成后端模型或测试结果。 角色到节点的映射、`route_state` 和日志字段见 `{CM_WORKFLOW_ROOT}/runtime/workflow-routing.md`。 策略会实际投影到流程：`generate_cases` 控制自动补测试用例，`tests` 控制可选 QA 类型，`auto_fix` 控制 QA 失败后的修复方式，`delivery` 选择 diff、本地 branch 或 Draft MR。`draft-mr` 仍会在 push/MR 前询问一次明确授权，配置本身不是远端权限。 ## 第一次完整开发

从需求、规格、人工确认到实现、审查和 QA 的完整流程

### 1. 接管代码项目 进入真正的代码仓库，在新会话中运行： ```text $cm-init ``` 它会分析项目并生成适用于 Agent 的项目规则与代码库上下文。已有项目通常只需执行一次；项目结构或关键命令大幅变化时再更新。 ### 2. 准备需求资料 创建一个 specs 目录，把 PRD、需求说明或原型说明放进 `docs/`： ```text ~/projects/my-app-specs/ └── docs/ └── user-login.md ``` 如果你只有一句点子，先运行 `$cm-idea` 形成 PRD，再把结果保存到这里。 ### 3. 生成可审查规格 ```text $cm-prd ~/projects/my-app-specs ``` 它会产出 `requirements.md`、`design.md`、`tasks.md`，并在需要时生成 `test-cases.json`。这一步**不会开始写业务代码**。 ### 4. 人工确认 检查工作流给出的需求摘要、方案、任务边界和验收条件。确认没有问题后，再进入实现。 `$cm-ai` 遇到 `.cm-specs-status` 为 `awaiting_review` 时会暂停。你必须明确回复“开始”；普通的“继续”不算审批。 ### 5. 执行实现 每个任务实现后，CM 会先生成结构化 handoff，记录本轮修改文件、真实验证、证据、 阻塞和范围偏差；它只是执行证据，不会自行勾选 `tasks.md`。随后独立 Review 写入 `approved / changes_requested / blocked`。只有当前轮为 `approved` 时，N5 才能标记 完成；第 1 轮要求修改会回到实现，第 2 轮仍阻塞则停止等待人工处理。 默认仍是串行。只读探索可以并行；两个任务要同时修改代码时，必须位于同一仓库的 不同 Git Worktree 和不同分支，否则工作流自动降级串行。 ```text $cm-ai ~/projects/my-app-specs ~/code/my-app ``` 多个代码项目时直接说明各自路径： ```text $cm-ai ~/projects/my-app-specs 前端在~/code/web，后端在~/code/api ``` 工作流会按 N1–N8 串行执行任务、测试、独立审查和归档。非人工确认节点会自动继续，不需要你反复输入“继续”。 ### 6. 查看交付凭证 完成后重点查看： - `tasks.md`：任务是否真正完成； - `.reviews/`：每轮独立审查和测试证据； - `.cm-run.json`：当前会话是否复用同一次运行； - `运行日志.jsonl`：过程是否可回放； - `METRICS.md`、`LESSONS.md`：本次度量和沉淀； - 代码仓库中的 diff、测试与提交。 ### 7. 跨项目统一查看日志 CM 会在首次记录事件时自动创建本机用户级日志目录： ```text ~/.cm-workflow/logs/ ├── index.jsonl ← 每次运行的开始/完成索引 └── runs/ └── YYYY-MM/ └── {run_id}.jsonl ← 这一轮的完整标准化事件 ``` 它汇总 `cm-prd`、`cm-ai`、`cm-test`、`cm-fix`、`cm-refactor` 和 `external-expert` 的运行开始、规格状态、测试执行、修复/重构、外部专家路由以及 提交交付等事件。常用查看方式： ```bash tail -n 20 ~/.cm-workflow/logs/index.jsonl find ~/.cm-workflow/logs/runs -name '*.jsonl' -type f python3 /path/to/cm-workflow/scripts/cm-prd-timing.py --last 5 python3 /path/to/cm-workflow/scripts/cm-usage-report.py --last 10 ``` `cm-prd-timing.py` 给出最近几次 `$cm-prd` 的阶段活跃耗时、最慢阶段、人工暂停次数和实际 触发的方案/规格审查次数。它是只读报告，不会修改项目状态；未配对事件只会标记， 不会猜测耗时。将 `/path/to/cm-workflow` 替换为当前 CM Workflow 安装目录。 `cm-usage-report.py` 只汇总适配器真实返回并写入日志的 API 用量：按流程、阶段、角色和模型 分开显示 input/output/cache counts；拿不到 usage 的调用保持 `unavailable`，不会猜 Token 或费用；同时区分 success/error/blocked/cancelled。已经 claim 但没有有效完成事件的 调用会单列为 `unresolved`，不计入调用、结果或 Token。需要机器读取时追加 `--json`。 项目角色使用 `adapter: openai-compatible` 时，CM 可在真实 HTTP 响应边界自动记录上述 数据。启动 Codex/Claude 前显式配置本次调用环境（密钥不要写进项目文件）： ```bash export CM_OPENAI_COMPATIBLE_ENABLED=true export CM_OPENAI_COMPATIBLE_BASE_URL="https://你的中转站/v1" export CM_OPENAI_COMPATIBLE_API_KEY="你的密钥" ``` 然后在 `.cm-workflow.yml` 为需要的分析、规划或编码辅助角色配置 `adapter: openai-compatible`、模型别名和 `source: api`。CM 会按 `runtime/model-efficiency.md` 生成最小角色包并调用内置边界；Prompt 和回答会发给该配置 API，但不会进入 CM 日志。远程地址必须使用 HTTPS。版本 1 不支持把该适配器配置给 `reviewer`，因为文本 API 回答不能替代 N4 的独立审查凭证，配置校验会在调用前拒绝。 如果希望写到其他本机目录，可在运行 Codex 或 Claude Code 前设置： ```bash export CM_WORKFLOW_LOG_HOME="$HOME/my-cm-logs" ``` 这不是云端遥测。项目 specs 中的 `运行日志.jsonl` 仍是权威记录，全局日志只是便于 汇总分析的私有镜像；它不会记录 Prompt、模型原始回答、外部会话链接、源码正文或凭证。 全局镜像写入失败时，带 specs 的工作流会在项目日志记录 `degrade` 后继续；没有项目 日志可兜底的独立运行则会明确失败。 ## 六条常见任务路线
路线 A：我只有一个产品点子 ```text $cm-idea 我想做一个支持团队审批的发布工具 ``` 按访谈形成 PRD后： 1. 把 PRD 保存到 `{specs路径}/docs/`； 2. 运行 `$cm-prd {specs路径}`； 3. 人工检查 specs； 4. 运行 `$cm-ai {specs路径} {代码路径}` 并明确回复“开始”。
路线 B：已有项目要开发新功能 ```text $cm-init $cm-prd ~/projects/my-app-specs $cm-ai ~/projects/my-app-specs ~/code/my-app ``` `$cm-init` 只在首次接管或项目事实明显变化时执行。后续功能通常从准备需求文档和 `$cm-prd` 开始。
路线 C：要修改已经存在的功能 ```text $cm-prd --change 2.user-login 登录失败五次后锁定账号 30 分钟 ``` 这是**行为变更**，需要更新需求、设计和任务，不能直接塞进 `$cm-fix` 或 `$cm-refactor`。审查变更规格后，再运行 `$cm-ai`。
路线 D：已有功能没有测试用例 先让 AI 从代码逻辑生成测试意图草稿： ```text $cm-test ~/code/my-app 用户登录 --generate-cases ``` 草稿中的 `[需确认]` 表示 AI 无法仅凭代码确认的业务意图。人工确认后，在生成的 `test-cases.generated.json` 中删除已确认项的 `[需确认]` 前缀，并把对应 `origin` 改为 `user`，再执行： ```text $cm-test ~/code/my-app --cases /生成报告路径/test-cases.generated.json --all ``` 如果用例已经保存为 feature 的 `test-cases.json`，也可以使用 `--specs {specs路径} --feature {N.feature}`。不想生成草稿时，则直接描述功能做 一次只读测试： ```text $cm-test ~/code/my-app 用户登录 ```
路线 E：已经确认是一个缺陷 ```text $cm-fix ~/projects/my-app-specs ~/code/my-app 登录成功后仍然停留在登录页 ``` `$cm-fix` 会先建立可复现的红灯测试，再定位根因、做最小修复、回归并审查。跨服务、异步或偶现问题会在本地记录最小观测、调用链和假设；仅在无法稳定复现时才进入“观测中”，证据到手后按原 slug 续跑。已可复现的问题则带着证据链走正常七步。若调查发现实际需要新增行为或改变契约，应退出修复流，改走 `$cm-prd --change`。
路线 F：代码能工作，但结构需要整理 ```text $cm-refactor ~/projects/my-app-specs ~/code/my-app 拆分过大的订单服务，不改变外部行为 ``` 重构必须先锁定行为基线。若目标包含新能力、接口变化或数据库语义变化，它就不是重构，应改走变更规格。
## 十个入口速查 | 入口 | 主要输入 | 主要产出 | 关键边界 | | --- | --- | --- | --- | | `$cm-runtime` | 预设与项目/用户范围 | 声明、来源与原子配置写入 | 不进入 N1–N8；仅影响新 run | | `$cm-check` | 当前安装 | 版本更新 + 机械与语义检查报告 | 默认升级已管理插件，不自动修业务或配置 | | `$cm-idea` | 一句话点子 | 可交付 PRD | 不自动进入 `$cm-prd` | | `$cm-init` | 当前代码项目 | `AGENTS.md`、兼容规则、代码库上下文 | 不实现业务功能 | | `$cm-prd` | specs 的 `docs/` | requirements、design、tasks、可选测试合同 | 在人工审查处停止 | | `$cm-ai` | 已审查 specs + 代码项目 | 实现、测试、审查和恢复凭证 | 超出 specs 的修改不应自行扩张 | | `$cm-test` | 代码、功能说明或测试用例 | 草稿、报告、截图和日志 | 默认只读，不装依赖、不修代码 | | `$cm-fix` | 可复现缺陷 | 红灯测试、最小修复、回归和审查 | 不承载新需求设计 | | `$cm-refactor` | 重构目标与行为基线 | 等价重构、验证和审查 | 不允许改变外部行为 | | `$external-expert` | 产品问题、研究问题或待批判材料 | 外部原始回答、本地裁决、待验证项 | 默认显式触发、可为本次任务 AUTO、文本优先、不改代码、不满足 N4 | ## 什么情况交给外部专家？ ```text $external-expert 帮我比较事件驱动和定时轮询两个方案，重点分析恢复和成本 $external-expert 根据这段脱敏日志提出根因假设，并为每个假设设计证伪步骤 $external-expert 研究 durable agent workflow 的论文，只使用论文或官方资料支撑结论 $external-expert --auto 判断这个问题应留在本地、咨询专家还是做权威核验 ``` 外部专家适合产品讨论、方案取舍、问题研究、学术研究、根因假设、测试设计和对抗 审查。默认是 `EXPLICIT`；`--auto`、“本次任务自动分流”或“模式：AUTO”只为当前 任务开启智能路由，结束即失效。单独安装的全局分流器不会自动替你开启 CM AUTO。 | 路由 | 什么时候使用 | | --- | --- | | `LOCAL` | 编码、命令、测试执行、页面 QA、Git、普通仓库操作与 N4 | | `CONSULT` | 多方案、竞争解释、冲突约束、深度批判或大量材料综合 | | `VERIFY` | 时效性、高风险、发布级事实或必须依赖官方/一手来源 | | `HANDOFF` | 只有你明确要求只转交并返回链接时 | AUTO 永不选择 HANDOFF。混合任务只外发可分离的讨论或研究部分，代码与最终验收仍 由本地完成。它不读取本地仓库的隐含内容；确需发送本地文件时，工作流会逐个展示普通文件 解析符号链接后的规范绝对路径，并要求用户在当前调用中紧随这份清单重新确认。目录、 glob、未解析符号链接、所有归档、编码归档、归档衍生批量上下文、`.env`、Token、 Cookie、私钥、浏览器状态和客户数据始终禁止外发；AUTO 本身不是文件授权。 Codex Desktop 在浏览器能力可用、用户已登录且有可写的持久证据位置时可以新建外部 对话；否则会输出完整 handoff packet 供手工复制。每个独立问题使用新对话，回答 较慢时不会重复发送。 发送前会检查模型选择器，并按 `Pro → Extra High → High` 选择第一个可用模式，不再 为降级单独询问。三者都不可用时不会发送任何内容，外部专家记为 `SKIPPED`，当前 任务继续由本地 Codex/Claude 完成；Medium 和 Instant 不参与降级。只有你明确说 “必须 Pro”或“不允许降级”时，Pro 不可用才会暂停。 也可以显式写“模式：LOCAL / CONSULT / VERIFY / HANDOFF”。显式模式优先于 AUTO； HANDOFF 只提交一次并返回对话链接，不读取回答，也不声称完成或正确。 外部回答回来后，本地主执行者会把关键建议标记为 `accepted`、`rejected` 或 `needs-verification`。学术研究的关键来源仍需本地打开核验；外部声称运行了测试 不能作为执行证据。请求、原始回答和裁决在有 specs 时保存到 `.external/`，不会 冒充 `.reviews/` 中的 N4 凭证。 ## `$cm-test` 到底会测试什么？ 日常直接运行 `$cm-test`：自动识别主分支，分析当前分支全部已提交差异， 列出受影响业务，并运行项目现有的单测覆盖率检查。没有覆盖率工具就明确标“未测得”。 要一起补测试，说 **“cm-test，并补齐单测”**；也可看完报告后回复 **“补齐单测”**。 只补已授权测试文件，随后重跑并独立审查；不擅自修改产品代码或安装测试框架。 开发需求/修 bug 时，这项检查在最终独立审查前完成。 ```text $cm-test {代码项目} {功能描述} --generate-cases $cm-test {代码项目} --specs {specs路径} --feature {N.feature} --all $cm-test {代码项目} --cases {用例文件路径} --browser $cm-test {代码项目} --explore {页面或用户流程} ``` | 模式 | 做什么 | 不代表什么 | | --- | --- | --- | | `logic` | 沿代码入口追踪分支、状态变化和输出 | 静态支持不能冒充运行通过 | | `commands` | 运行项目正式声明的测试、类型检查和构建命令 | 替代命令不能冒充正式命令 | | `browser` | 模拟用户操作并保存可观察结果、截图和日志 | 页面能打开不等于业务流程通过 | | `all` | 组合 logic、commands、browser；有明确测试目标时的默认模式 | 某一层 PASS 不能覆盖另一层 FAIL | 测试环境缺依赖时，`$cm-test` 会记录 `BLOCKED`，不会擅自安装依赖或降低断言。先人工修复环境，再重跑原命令。 ## 我现在走到哪一步了？ 磁盘状态比聊天记录可靠。忘记进度时，检查这些文件： | 看到的状态 | 表示什么 | 下一步 | | --- | --- | --- | | `.cm-specs-status = awaiting_review` | 规格已生成，等待人工确认 | 查看摘要和 specs，运行 `$cm-ai` 后明确回复“开始” | | `.cm-specs-status = approved` | 规格已批准 | 运行或重新运行同一个 `$cm-ai` 命令 | | `.cm-status.json` 显示 `running` | 执行曾经开始 | 在新会话重跑同一命令，从磁盘恢复 | | `.cm-status.json` 显示 `paused_for_human` | 正在等待人工决策 | 读取暂停原因，再明确批准或调整 | | `tasks.md` 仍有 `[ ]` | 还有未完成任务 | 重跑 `$cm-ai`，不要手工伪造完成状态 | | `.cm-status.json` 显示 `done` | 流程节点已完成 | 仍需检查 review、测试与 Git 结果 | | 测试报告为 `FAIL` | 已得到失败证据 | 若是缺陷，进入 `$cm-fix` | | 测试报告为 `BLOCKED` | 环境不具备执行条件 | 修复环境后重跑，不能写成 PASS |

新会话从任务、状态、审查和日志等磁盘记录恢复

### 新会话怎么继续？ 不用让新会话读取旧聊天。进入相同项目，重新运行原命令即可： ```text $cm-ai ~/projects/my-app-specs ~/code/my-app ``` 工作流会从 `tasks.md`、`.cm-status.json`、`.cm-run.json`、`.reviews/` 和 `运行日志.jsonl` 重建上下文，并从未完成位置继续。 任务和 AC 的正常 `[x]` 进度不会触发重新审批；如果任务/AC 文案、方案或测试合同 发生变化，入口仍会恢复为 `awaiting_review`，要求重新审查规格。 ## 常见卡点 ### 找不到 `$cm-*` 或 `/cm-*` 安装后需要新开会话。先运行 `$cm-check`；仍不可用时重新检查安装路径和安装输出。 ### `$cm-prd` 提示没有输入文档 确认 `{specs路径}/docs/` 存在且至少包含一份非空需求文档。不要把代码目录误传成 specs 目录。 ### `$cm-ai` 一直停在审查状态 这是人工闸门，不是故障。阅读摘要与 specs，确认无误后明确回复“开始”。“继续”“好的”不会被当作规格批准。 ### `$cm-test` 没有自动修复问题 这是设计边界。`$cm-test` 默认只读；确认是缺陷后，显式运行 `$cm-fix`。 ### 不确定是修复、重构还是变更 用这条判断： - **原本承诺的行为没有做到** → `$cm-fix`； - **外部行为不变，只整理结构** → `$cm-refactor`； - **用户可见行为、接口或业务规则要变化** → `$cm-prd --change`。 ## 可复制的最小清单 ```text # 1. 安装健康检查（安装后或异常时） $cm-check # 2. 首次接管代码项目（在代码仓库中） $cm-init # 3. 从需求文档生成规格 $cm-prd ~/projects/my-app-specs # 4. 人工审查后执行 $cm-ai ~/projects/my-app-specs ~/code/my-app # 5. 测试已有功能 $cm-test ~/code/my-app 用户登录 # 6. 修复已确认缺陷 $cm-fix ~/projects/my-app-specs ~/code/my-app 缺陷描述 # 7. 做行为等价重构 $cm-refactor ~/projects/my-app-specs ~/code/my-app 重构目标 # 8. 讨论方案或研究问题（不会修改代码） $external-expert 你的问题 ``` ## 始终由人确认的动作 工作流不会替你自动决定以下事项： - 规格是否可以进入实施； - 生产发布与真实资金操作； - 密钥、凭证和权限变更； - 破坏性 migration； - 超出已批准任务范围的修改。 ## 延伸阅读 - [安装指南](installation.md)：Codex、Claude Code 与 Windows 安装细节。 - [架构说明](architecture.md)：状态真相、审查通道与测试合同。 - [README](../README.md)：项目定位、能力全景与维护入口。 ## 主动安全检查 ```text $cm-security $cm-security --all $cm-security {项目路径} --semgrep-rules {外部本地规则文件} --osv-db {外部缓存目录} ``` 默认检查当前分支相对主分支的差异及已跟踪未提交修改；`--all` 检查全部已跟踪文件。 先读业务地图，再运行现有本地工具并复核鉴权、注入、文件/命令/网络边界。 扫描不自动安装工具、下载规则/数据库、修改代码或发布；工具缺失会继续可做的复核， 结果明确标记部分覆盖。未跟踪文件、受保护路径、Git 历史不在默认扫描范围。 报告给出位置、业务影响、证据、修复建议与未检查项。工具结果不等于安全保证； 需要修复时再明确交给 cm-fix。详细参数见 `skills/cm-security/references/scan-contract.md`。 ## 运行时默认与切换 交互安装在核心成功后询问“只有 Codex / 只有 Claude / 两个都有”，两家都有再问谁写代码。 结果保存为 `~/.cm-workflow/runtimes.yml`；已有文件显示当前值并默认保留。 `--yes` / `-Yes` 或非 TTY 跳过提问且不写文件。测试时可用 `CM_WORKFLOW_HOME` 覆盖目录。 优先级：**项目 > 用户级默认 > 未声明**。项目没有 `runtimes.available` 才读取用户文件； 显式项目角色字段覆盖用户预设的角色默认值，矛盾配置报字段路径并阻断。 `cm-init` 遇到用户默认直接继承、报告 `来源: 用户级默认`，两级都没有才询问。 | 预设 | 写代码 | 审代码 | | --- | --- | --- | | `codex-only` | Codex | Codex 的独立新上下文 | | `claude-only` | Claude | Claude 的独立新上下文 | | `codex-codes` | Codex | Claude | | `claude-codes` | Claude | Codex | 直接输入 `$cm-runtime`（Claude Code 为 `/cm-runtime`）即可由会话按当前对话语言三问： `[1] 当前项目 / [2] 用户级默认` → `[1] 只有 Codex / [2] 只有 Claude / [3] 两个都有` （选 3 再选 `[1] Codex 写、Claude 审（推荐） / [2] Claude 写、Codex 审`）→ 显示预设和当前值并确认。 终端无参数运行 `node /scripts/cm-runtime.mjs [--project PATH]` 进入同一向导。 有项目配置时范围默认 1，否则默认 2；无配置选 1 会提示从模板新建。工具问题必须选择； Ctrl+C、必选问题连续三次空输入或拒绝确认均不写。非 TTY 无参数打印用法并退出 2。 安装器、终端向导与人类可读诊断按系统语言显示中文或英文： `CM_WORKFLOW_LANG=zh|en` > `LC_ALL` > `LC_MESSAGES` > `LANG` > Node Intl > 英文兜底； locale 以 `zh` 开头用中文，其他用英文。Windows 安装器传入 `Get-Culture` 作为 locale。 机器字段、预设名和退出码保持不变；用户默认文件的注释也随语言切换。 自动化可继续使用显式子命令： ```text $cm-runtime show $cm-runtime set claude-codes --project /path/to/project $cm-runtime set --user codex-codes $cm-runtime unset --user ``` Claude Code 用 `/cm-runtime`，macOS/Linux 兼容 `/cm:runtime`；终端入口为 `node /scripts/cm-runtime.mjs`。`show` 显示 `runtimes_source: project|user|none`、 有效预设（无法精确匹配时为 custom）、coder/reviewer adapter/source。CLI 缺失只 WARN，不代表配额检测。 `set` 只改声明和 coder/reviewer 的 adapter/source，保留模型、策略、注释、格式等其他原文； 新配置从模板生成。`set --user` 改全局默认，`unset --user` 只删除用户默认，不清项目声明。 这些操作不修改正在运行的 run；run 创建时已绑定配置。`set` 记录独立的 `decision/route` 日志， 不借用业务 run 指针；若日志失败会明确提示“配置已写、日志失败”。`show` 不写日志。