Cm Prd

cm-prd — 需求文档 → 开发规格生成

执行前读取 ../../runtime/project-context.md、../../runtime/review.md、 ../../runtime/model-efficiency.md 与 ../../runtime/logging.md。在需求、方案或任务拆分 命中重要歧义/对抗审查时，追加读取 ../../runtime/steelman-review.md；它是推理合同， 不增加审查轮次或审批状态。Codex 入口为 $cm-prd；Claude Code 跨平台入口为 /cm-prd，macOS/Linux 另有历史别名 /cm:prd。

新建和变更模式都读取 references/phase-timing.md，只为实际执行的阶段写配对 progress/start|complete；人工等待前关闭 segment，恢复后递增，不手算耗时。

用户明确要求外部专家，或为本次规格任务开启 AUTO 时，读取 ../../runtime/external-expert.md 并执行 ../external-expert/SKILL.md 的任务路由。 AUTO 可把复杂方案比较路由到 CONSULT、权威事实查证路由到 VERIFY，其余保持 LOCAL。 外部结论属于需求/设计输入，必须在本地对照项目事实并进入正常规格人审；AUTO 不 授权外发 docs 或代码内容。

支持两种模式：新建需求和需求变更。

输入参数

用户本轮输入 格式：

• 新建模式：$cm-prd {项目文件夹路径}
• 变更模式：$cm-prd --change {N}.{feature-name} 变更内容描述
• 可选用例输入：追加 --cases {json/md/txt路径}，或在本轮消息直接粘贴用例

用户提供一个项目文件夹路径，文件夹结构约定：

{项目文件夹}/
├── docs/           ← 需求文档（必须存在，PRD 从这里读取）
├── 1.xxx/          ← 已有的 specs（如有）
├── 2.xxx/          ← 本次生成的 specs
└── ...

JS 准入与当前会话执行

在读取需求正文、解析角色、写 run_start、创建或修改 specs 之前，把已解析路径和模式传给：

node "{CM_WORKFLOW_ROOT}/scripts/cm-prd-entry.mjs" \
  --skill-dir "{CM_WORKFLOW_ROOT}/skills/cm-prd" \
  --project "{CODE_PROJECT}" --specs "{SPECS_DIR}" \
  [--change "{N 或 N.feature}"] [--cases "{用例文件路径}"]

准入只核对路径/清单，不读正文或授权写入；selection_required请用户选feature，blocked按reason停。 两种模式ready后读取references/js-host.md，以当前会话连接JS宿主；下方步骤提供业务约束，不再手写日志/规格/审批位。 变更、已审修订、恢复及原材料真正变更时，读取references/js-change-recovery.md；输入替换须明确授权终止旧批次，再关联新批次全量重审。 两条路径均保留原Step 0–11和人审停点；变更描述、粘贴用例由Skill保留，不能当成工具授权。

项目角色路由

路径验证通过后，使用 {CM_WORKFLOW_ROOT}/scripts/cm-workflow-config.mjs 读取有效配置， 分别解析 analyst（需求分析）、planner（方案/任务拆分）及 policies.generate_cases：

node {CM_WORKFLOW_ROOT}/scripts/cm-workflow-config.mjs \
  --project {CODE_PROJECT} --role analyst --runtime {codex|claude} --print-role
node {CM_WORKFLOW_ROOT}/scripts/cm-workflow-config.mjs \
  --project {CODE_PROJECT} --role planner --runtime {codex|claude} --print-role
node {CM_WORKFLOW_ROOT}/scripts/cm-workflow-config.mjs \
  --project {CODE_PROJECT} --print-effective

把返回的 adapter、model、source 和 route_state 当作本轮的请求路由元数据， 在对应分析/规划提示中注明；model 是别名，不能声称为已观测的后端模型。每次角色 边界按 runtime/workflow-routing.md 写一条 decision/phase: route 事件。配置未提供 时使用内置默认值；resolver 返回非零或配置错误时立即 BLOCKED 并报告字段路径， 不得进入分析/规划或生成规格。配置的适配器当前运行时不可用时记录 warning/degrade， 不得伪造调用成功或把外部专家变成编码执行器。

analyst 与 planner 的上下文和输出按 runtime/model-efficiency.md 分包：前者只取 当前需求与相关业务地图，后者接收分析结论、波及模块、约束和 AC 候选。稳定规则前缀 与动态需求分离；不得为方便而重复发送完整项目地图、全部源码或前序对话。只有真实 适配器响应返回 usage 时才记录计数。route_state: managed-adapter 时按共享合同调用 cm-openai-compatible-call.py，由它写唯一的 model_usage；不得由 Skill 重复写。

generate_cases: false 只关闭 CM 根据需求自动补生成的 origin: generated 用例；用户 或需求源已提供的测试用例仍须保留、规范化并进入审批，不能用项目配置删除测试意图。

项目/specs 路径验证通过后按 runtime/logging.md 写 run_start。生成规格、重置 审批位或终止时分别写 spec_lifecycle 与 run_done；详细需求和设计内容不进入主日志。

模式判断

如果 用户本轮输入 以 --change 开头 → 读取 references/change-mode.md 执行变更模式（C1–C8） 否则 → 进入新建模式

新建模式

Step 1: 解析输入，读取需求文档

从 用户本轮输入 提取项目文件夹路径，记为 SPECS_DIR。

读取 {SPECS_DIR}/docs/ 下的所有文件作为需求源：

• 支持 .md、.txt、.pdf、.html 等文档格式

• HTML 交互原型（可点击 PRD）→ 执行交互遍历协议，禁止只做静态截图。可交互原型是一份可执行的需求文档，必须用无头浏览器（Playwright / Chrome DevTools）主动遍历：

  1. 枚举每个页面的全部可交互元素（按钮/链接/tab/表单/开关/列表项…）
  2. 逐个操作并记录三元组：元素 → 动作 → 结果（跳转到哪/弹了什么/状态怎么变/无响应）
  3. 产出功能点清单：每个有响应的交互 → 对应一条 [F-xxx]；点了没反应的 → 列为"原型死区"进开放问题（问用户：是原型没做完，还是本就不需要？不许静默丢弃）
  4. 覆盖率自检：可交互元素总数 = 功能需求数 + 死区数，对不上不得进入 Step 6
  5. 遍历过程中逐状态截图（Step 8.5 的候选基准）；三元组记录直接生成交互流 AC 与 E2E 走查清单

  原型首先是需求，其次才是视觉候选。注意原型通病：只画理想态——异常态/空态/边界值靠 Step 5.5 歧义五问补齐

• 如果 docs/ 下有多个文件，全部读取并综合分析

• 输入含 --cases 或本轮粘贴了测试用例时，将其作为用户来源交给 Step 10.4； JSON 先做语法校验，Markdown/文本在生成时归一化为测试合同

• 如果 docs/ 不存在或为空，报错提示用户先在 docs/ 下放入需求文档

Step 2: 获取项目名称

• 从当前目录的 package.json name 字段、Cargo.toml、go.mod 等提取项目名
• 如无法提取，使用当前目录名
• 转为 kebab-case，记为 PROJECT_NAME

Step 3: 探测项目架构类型

代码项目根的确定（防在错误目录生成脏规格）：用户本轮输入 中显式给了代码项目路径（如 代码在~/code/app）→ 以其为准；未给 → 用当前工作目录（约定:在代码项目内运行本命令），但必须先自检——当前目录含项目描述文件或源码、且其内容与需求文档所述业务相符；明显不符（如当前目录是另一个项目/工具仓库）→ 停下询问代码项目路径，不得静默把错误目录当项目上下文（空目录检测只兜全空 case，兜不住"错但有效"的目录）。

扫描项目根目录、配置文件、目录结构、依赖声明，自行判断架构类型（monorepo / 多仓库 / 单体应用 / Web3 等）。记录 ARCH_TYPE。

交付形态为微信小程序，或项目存在原生 project.config.json + app.json、Taro/uni-app 微信构建目标时，标记 DELIVERY_SHAPE=wechat-miniprogram 并读取 ../cm-miniprogram-engineer/references/platform-readiness.md。只出现“小程序”字样但 形态证据不足时进入 Step 5.5 确认，不得根据仓库名猜测。

空项目检测：代码项目不存在、或为空目录（无 package.json / Cargo.toml / go.mod 等项目描述文件，且无源码目录）→ 先问用户确认空目录的含义，不得自行假设：

"代码目录为空——这是【全新项目】（走 0→1 分支，我来推荐架构和脚手架），还是【存量项目还没 clone】（请先 clone 到该目录，再重新运行 $cm-prd）？"

• 确认全新项目 → 标记 GREENFIELD=true，读取 references/greenfield.md 叠加 G1–G4 规则，Step 4 跳过
• 确认未 clone → 中止本次执行，提示 clone 完成后重跑（在不存在的项目上下文上生成 design.md 是有毒规格）

Step 4: 读取项目上下文（存量项目 = 二开模式，叠加 B 规则）

• 按 runtime/project-context.md 读取项目约束和本需求相关规则，扫描两层目录了解模块划分
• 读取 references/context-scope.md，先做定向代码搜索，再设置 CONTEXT_SCOPE=targeted|full、加载对应地图/代码，并写 decision/context_scope 日志
• B1 代码库参考文档判定：先读代码项目根 CLAUDE.md 的「业务地图」字段（多层仓库 下以代码项目根为准，仓库根 CLAUDE.md 无此字段再看地图 00-index 头部；init 已判定过， 仍须核对相关内容与当前代码）。字段=已生成/已刷新或目录存在 → 按 context-scope 渐进加载并核实；字段= 跳过(小项目) → 不建议 scan，按范围直接读代码；字段缺失且文档不存在 → 按共享回写合同 定向还原本次链路，将必要地图文档纳入后续任务范围，不强制先全量 scan；skill 未安装 → 提示重装最新包并按 直接代码搜索继续。任何路径都不得因追求 targeted 猜测波及面

二开模式追加规则（GREENFIELD=false 且本次需求会修改存量代码时生效）→ 读取 references/brownfield.md 执行 B2 波及面 / B3 防护网基线 / B4 增量 specs / B5 拆分锚定地图。

Step 5: 分析需求

调用 cm-product-manager skill 执行本步和 Step 5.5——用户故事、编号功能需求、验收标准的编写方法和歧义五问以该 skill 为准。

需求涉及交易/资产/支付/代币/证券/金融营销时，同时加载 cm-finance-expert skill 协同：领域正确性审核 + 营销合规红线扫描 + 合规开放问题（并入 Step 5.5）。法域确认结果须写入代码项目 .claude/rules/finance.md 头部字段；文件不存在时，以 {CM_WORKFLOW_ROOT}/templates/rules/finance.md 为骨架现场补生成，并在 AGENTS.md 与 CLAUDE.md 的相关规则说明中补充引用。

从文档中提取功能目标、用户故事、验收标准、约束条件、依赖。

命中重要歧义或方案分歧时，按 ../../runtime/steelman-review.md 区分已观察事实、参与者主张、当前推断和未知项；“用户真正想要什么”只能写成可修正假设，不能替用户补全业务规则。

Step 5.5: 开放问题确认

分析需求后，如果存在以下情况，必须暂停并与用户对话确认，不要自行假设：

• 需求描述模糊或有歧义的功能点
• 多种技术实现方案且差异较大
• 缺少关键信息（如目标平台、兼容性要求、第三方服务选型）
• 业务逻辑有矛盾或不完整
• 涉及权限、支付、敏感操作等需要明确确认的功能

DELIVERY_SHAPE=wechat-miniprogram 时追加平台就绪检查：账号主体、服务类目/资质、 变现路径、权限与隐私、后端/合法域名和发布通道。会改变功能可行性或范围但未确认的 项目必须暂停；只影响后续提审的材料可记为发布待决，不阻塞本地规格与开发。平台政策 结论须记录当前官方查证日期与来源，无法查证时保留开放问题。

格式：

❓ 需要确认以下问题：

1. {问题描述} — {为什么需要确认}
2. {问题描述} — {为什么需要确认}

请逐一回复后继续生成 specs

所有问题确认完毕后再进入 Step 6。

双向钢人审查只用于暴露假设和失败场景：支持方与反方都取最强版本，但按证据质量加权；无法验证的反方写入开放问题，不强迫给确定结论。

Step 6: 推断 feature 名称

根据需求内容生成一个简洁的 kebab-case 英文名称。

Step 7: 生成 specs 目录

检查 {SPECS_DIR}/ 下已有的编号目录（如 1.xxx/、2.xxx/），取最大编号 +1。

{SPECS_DIR}/
├── docs/                        ← 需求文档（输入）
├── 1.比如这是一个已有的标题/     ← 已有 specs
└── 2.{feature-name}/            ← 本次新建
    ├── requirements.md
    ├── design.md
    ├── tasks.md
    └── test-cases.json           ← 有可观察行为时生成

Step 8: 生成 requirements.md

# {Feature 名称} — 需求规格

## 概述

{一句话描述}

## 项目信息

- 项目名: {PROJECT_NAME}
- 架构类型: {ARCH_TYPE}

## 需求版本

| 日期         | 版本 | 说明     |
| ------------ | ---- | -------- |
| {YYYY-MM-DD} | v1   | 初始需求 |

## 用户故事

- 作为 {角色}，我想要 {功能}，以便 {价值}

## 功能需求

1. [F-001] {需求描述}
2. [F-002] {需求描述}

## 非功能需求

- 性能: {要求}
- 安全: {要求}
- 兼容性: {要求}

## 验收标准

- [ ] [AC-001] {标准描述}

## 依赖

- {外部服务/库}

## 平台就绪（仅微信小程序生成）

{按 cm-miniprogram-engineer/references/platform-readiness.md 记录状态、证据与负责人；
不写任何密钥、证件、Cookie 或测试账号密码}

## 开放问题

- {待确认事项}

Step 8.5: UI 设计基准（涉及 UI 的 feature）

feature 涉及页面/界面时，在生成 design.md 前确定设计基准：

• 有 Figma/设计稿 → 通过 MCP 导出截图 + token 提取物，落盘 {SPECS_DIR}/{N}.{feature-name}/design-baseline/（防链接失效与云端改版导致基准漂移）
• 有 Stitch 项目 → 通过 Stitch MCP 拉取设计并导出 HTML/CSS 落盘 design-baseline/；导出的 HTML 按 Step 1 交互遍历协议处理（多屏/流转设计可直接提取交互流与功能点）——Stitch 导出物默认按像素基准对待（它就是设计本体，不是示意）
• 有 HTML 交互原型（Step 1 已截图）→ 必须人工三选一确认基准档位（中性提问不带引导；高保真原型建议像素档，线框灰稿建议结构档）：
  • ① 像素基准：UI 与交互 1:1 还原——截图落盘 design-baseline/ 作 BackstopJS 基准（≤1%），且交互流提取为 E2E 走查清单（每个跳转/状态切换/反馈逐条断言，交互不 1:1 视为验收失败）
  • ② 结构基准（多数原型的合理档）：页面结构、信息层级、交互流程必须一致，视觉样式可再设计——验收为逐页元素清单核对 + 流程走查
  • ③ 纯参考：仅辅助理解需求，无对照验收——选此档即明确接受 UI 由 AI 自行发挥（历史事故：原型被降为参考后，产出与原型完全不符） 档位写入 design.md「设计基准」节；无论哪档，原型的页面清单与跳转流程都已是需求的一部分（Step 1 规则），流程不允许自由发挥
• 无设计稿且环境已安装 huashu-design skill → 调用其生成高保真原型（要求包含 hover/空态/错误态等交互态），落盘同上；人审规格时一并确认设计方向（复用既有强制卡点，执行期零设计决策）
• 两者皆无 → 不建基准、不生成 UI 还原任务，该 feature 的 UI 由前端任务按 design.md 自行实现；可提示用户 npx skills add alchaincyf/huashu-design

基准机读化(四种来源统一要求——截图给人看,规格表给 AI 抄):design-baseline/ 除截图外必须含逐元素规格表(spec-sheet.json:字体五件套/色值/几何/间距)。AI 看图估值的精度天花板极低,是还原度不理想的头号根因(实跑反馈);规格表按基准形态产出:

• Figma MCP → 直接读取节点精确值(排版/填充/自动布局间距)导出成表,不经截图转译
• Stitch 导出 / HTML 原型 → 用 {CM_WORKFLOW_ROOT}/templates/ui-lens/cm-ui-lens-extract.mjs 对基准页提取计算值成表；样式值优先移植改造而非重新想象
• 纯截图(最弱形态) → 色板可精确采样成表;几何只能估算——规格表标注「几何估算档」,并明确提示用户:有 Figma/原型源尽量给源,纯截图基准的还原精度天花板显著更低
• 基准字体文件一并落盘(还原页先加载同款字体再对比,防字体回退噪声淹没真差异)

有基准时，design.md 记录基准路径，且「接口契约」节须包含组件契约（组件名 / props / 事件）。

Step 9: 生成 design.md

复用 Step 4 已加载的项目约束与规则；根据最终波及层补读新命中的相关规则，禁止再次 全量读取未变化的 CLAUDE/rules。设计方案必须遵循项目已有的技术规范和约定。

按功能模块设计，每个模块说明涉及哪些层（前端、后端、数据库、合约等），具体分层根据项目实际架构决定，不做硬编码限制。

# {Feature 名称} — 技术设计

## 设计版本

| 日期         | 版本 | 说明     |
| ------------ | ---- | -------- |
| {YYYY-MM-DD} | v1   | 初始设计 |

## 项目架构

- 架构类型: {ARCH_TYPE}
- 涉及层: {根据项目实际情况列出}

## 功能模块设计

### 模块 1: {模块名}

{技术方案，遵循 .claude/rules/ 中的规范}

**涉及层及关键设计:**

{根据项目实际分层描述，如数据模型、API 接口、组件设计、合约接口等}

### 模块 2: {模块名}

...

## 接口契约

{API、RPC、合约接口等 — 根据项目类型决定}

## 数据模型

{数据表/模型/链上存储 — 根据项目类型决定}

## 安全考虑

{基于 .claude/rules/security.md 和项目特有的安全规范}

## 技术决策

| 决策 | 选项 | 理由 |
| ---- | ---- | ---- |