@aibyzero/byz 0.0.0 → 0.1.2

package/workflows/cm/skills/cm-prd/references/change-mode.md

@@ -0,0 +1,145 @@
+# $cm-prd 模式文件 — 变更模式
+
+> 由 $cm-prd 模式判断检测到 `--change` 时读取本文件。规则内容与主文件同源拆分,语义未变。
+
+## 变更模式
+
+当输入 `$cm-prd --change {N}.{feature-name} 变更内容` 时执行。
+
+### Step C1: 定位已有 specs
+
+在 `{SPECS_DIR}/` 中查找匹配的编号目录。
+
+如果只传了序号（如 `--change 1`），自动匹配 `1.*` 目录。
+
+找不到则报错提示。
+
+### Step C2: 读取现有 specs
+
+读取该目录下的：
+
+- `requirements.md` — 当前需求
+- `design.md` — 当前设计
+- `tasks.md` — 当前任务（注意哪些已完成 `[x]`）
+- `test-cases.json` — 可选 AI 测试合同；存在时按
+  `../../../runtime/test-contract.md` 读取
+
+### Step C3: 解析变更内容
+
+变更内容可以是：
+
+- 纯文本描述变更
+- 文件路径（新的需求文档）
+- URL
+- `--cases {json/md/txt路径}` 或本轮直接粘贴的新测试用例
+
+### Step C4: 对比分析
+
+**调用 `cm-product-manager` skill 的变更影响分析**：除识别增删改外，评估波及哪些已完成任务（返工风险）、哪些验收标准失效。
+
+变更内容涉及**交易/资产/支付/代币/证券/金融营销**时，同时协同 `cm-finance-expert`：对变更做领域正确性审核与营销红线扫描，新引入的合规问题并入变更摘要供人审。
+
+将变更内容与现有 requirements.md 对比，识别：
+
+- **新增**的功能需求
+- **修改**的功能需求
+- **删除**的功能需求
+- 对验收标准的影响
+
+### Step C5: 更新 requirements.md
+
+- 在「需求版本」表中追加新版本行：
+
+```markdown
+## 需求版本
+
+| 日期       | 版本 | 说明             |
+| ---------- | ---- | ---------------- |
+| 2026-04-11 | v1   | 初始需求         |
+| 2026-04-15 | v2   | 新增微信登录方式 |
+```
+
+- 在功能需求中标注变更：
+
+```markdown
+## 功能需求
+
+1. [F-001] 邮箱 + 密码登录
+2. [F-002] 手机号 + 验证码登录
+3. [F-003] Tab 切换登录方式
+4. [F-004] ~~短信验证码 5 分钟过期~~ `[v2 删除]`
+5. [F-005] 微信扫码登录 `[v2 新增]`
+6. [F-006] 表单验证 `[v2 修改: 新增微信回调校验]`
+```
+
+### Step C6: 更新 design.md
+
+- 追加设计版本
+- 新增/修改受影响的功能模块设计
+- 不动未受影响的模块
+- 标注变更原因
+
+### Step C7: 更新 tasks.md
+
+- 追加任务版本
+- 已完成的任务 `[x]` 保持不动
+- 受变更影响的未完成任务标记 `[CHANGED]` 并更新描述
+- 因变更作废的任务标记 `[DROPPED]`
+- 新增的任务标记 `[NEW]`
+
+```markdown
+## 任务列表
+
+### 功能 1: 登录表单
+
+- [x] T-001: 创建登录页面和 Tab 切换组件 ~30min
+- [x] T-002: 实现邮箱登录表单 ~30min
+- [ ] T-003: 实现手机号登录表单 ~30min `[CHANGED v2: 去掉倒计时]`
+- [ ] ~~T-004: 短信过期逻辑~~ `[DROPPED v2]`
+
+### 功能 2: 微信登录 `[NEW v2]`
+
+- [ ] T-008: [NEW] 微信 OAuth 回调处理 ~30min
+- [ ] T-009: [NEW] 微信登录按钮组件 ~15min
+```
+
+### Step C7.5: 更新 AI 测试合同
+
+C7 完成后先按 `runtime/test-contract.md` 更新 `test-cases.json`：保留未受影响
+用例，新增/修改受影响 AC 的用例，移除已删除需求对应的 generated 用例。变更会
+删除或弱化 `origin: "user"` 用例时，必须在 C4 暂停取得明确确认；未确认则保留
+需求与用例并将冲突列入摘要。最后重新校验 AC→TC→Task 引用和 JSON。
+
+### Step C8: 输出变更摘要
+
+```
+📝 需求变更: 1.user-auth v1 → v2
+
+新增: 2 个功能需求, 2 个任务
+修改: 1 个功能需求, 1 个任务
+删除: 1 个功能需求, 1 个任务
+未受影响: 3 个已完成任务保持不动
+测试合同: 新增 2 / 修改 1 / 待删除 1
+
+请产品审查变更后，运行 $cm-ai 继续开发（会跳过已完成任务）
+```
+
+---
+
+## 示例用法
+
+```bash
+# 新建需求 — 提供项目文件夹路径，docs/ 下放需求文档
+$cm-prd ~/projects/my-app-specs
+$cm-prd /path/to/project-specs
+
+# 需求变更 — 同样基于项目文件夹，指定要变更的 feature
+$cm-prd --change 1.user-auth 新增微信扫码登录方式
+$cm-prd --change 2 ~/projects/my-app-specs
+```
+
+**审批位重置**：变更落盘后，将 `{SPECS_DIR}/.cm-specs-status` 重置为
+`awaiting_review`，运行 `scripts/cm-spec-manifest.py` 重算 requirements/design/tasks/
+test-cases 的完整 `specFiles`，并同步兼容字段 `testCases`；按 `runtime/logging.md` 写 `spec_lifecycle/changed`、
+`spec_lifecycle/awaiting_review` 和 `run_done`。改过的规格等于没审过，N1 入口闸将
+再次要求确认。

package/workflows/cm/skills/cm-prd/references/context-scope.md

@@ -0,0 +1,62 @@
+# $cm-prd Step 4 — 渐进式上下文范围
+
+本规则只优化 `cm-prd` 消费项目上下文的范围，不改变 `/codebase-context dev` 的全量
+加载语义，也不减少规格、测试或审查产物。设置 `CONTEXT_SCOPE=targeted|full`。
+
+## 1. 固定基础上下文
+
+两种范围都先按 `runtime/project-context.md` 读取 AGENTS/CLAUDE 约束，以及存在的
+`coding-style.md`、`testing.md`、`security.md` 和本需求已命中层的规则。需求源、项目
+描述文件和两层目录概览已经由 Step 1–3 读取，不重复打开。
+
+存在 `docs/codebase-context/` 时先读 `00-index.md`；再用需求中的页面名、路由、可见
+文案、接口名、类型名和业务术语做代码搜索，定位候选模块、直接调用方与最近测试。
+搜索只用于定位，不把命中源码或需求正文写入运行日志。
+
+## 2. 范围判定
+
+只有以下条件**全部满足**才设置 `CONTEXT_SCOPE=targeted`：
+
+- 存量项目，且本次初步只对应一条已有业务线路和一个现有模块；
+- 候选源文件、直接调用关系和可执行验证入口均已定位；
+- 地图已覆盖该线路，或小项目的直接代码搜索足以证明波及面；
+- 未命中主 `SKILL.md` Step 9.5 的任何方案对抗审查触发条件；
+- 需求不存在会改变实现范围的开放问题。
+
+任一条件不满足即设置 `CONTEXT_SCOPE=full`。Greenfield、目标未定位、地图盲区、跨
+业务线路、范围不确定也直接走 full，不为了命中快线猜测边界。
+
+## 3. 加载清单
+
+`targeted` 且业务地图存在时读取：
+
+- 固定：`00-index.md`、`01-overview.md`、`03-architecture.md`、
+  `07-business-logic.md`、`08-conventions.md`；
+- 涉及 API/service 或调用契约时追加 `04-api-routes.md`；
+- 涉及类型、模型、存储或字段时追加 `05-data-models.md`；
+- 涉及页面/UI、共享组件、Hook、Store 或复用判断时追加 `06-core-modules.md`；
+- 不读取仅用于地图维护追溯的 `09-changelog.md`，也不为定位成功的任务重读
+  `02-directory.md`。
+
+随后只读候选源文件、直接调用方和最近测试。`full` 保持现有行为：地图存在时加载
+00–09 全部 10 份；地图不存在或标记为小项目时直接读取完整相关代码范围。
+
+## 4. 执行期升级
+
+Step 5–10 任一阶段发现第二条业务线路、额外模块、地图盲区或上述风险信号时，必须在
+继续生成最终 design/tasks 前执行 `targeted → full`：补齐 00–09 或完整相关代码范围，
+重做波及面与任务边界检查。只允许升级，不允许 full 降回 targeted。
+
+## 5. 日志与摘要
+
+初次判定后按 `runtime/logging.md` 写 `decision` / `phase: context_scope`，数据只包含：
+
+- `context_scope`: `targeted | full`；
+- `reason_code`: `single_module_identified | greenfield | target_unresolved |
+  map_blind_spot | cross_module | contract_or_data | security_sensitive |
+  dependency_or_architecture | large_feature | scope_uncertain`；
+- `context_docs`: 已加载地图的相对文件名数组；无地图时为空数组。
+
+发生升级时再写一条 `decision` / `phase: context_scope`，增加
+`transition: targeted_to_full`、`reason_code: scope_expanded` 和不含业务正文的原因分类。
+摘要卡显示 `上下文范围: 定向 | 完整 | 定向→完整（{reason_code}）`。

package/workflows/cm/skills/cm-prd/references/greenfield.md

@@ -0,0 +1,80 @@
+# $cm-prd 模式文件 — 0→1 空项目分支（GREENFIELD）
+
+> 由 $cm-prd Step 3 判定 GREENFIELD=true 时读取本文件。规则内容与主文件同源拆分,语义未变。
+
+## 0→1 空项目分支（GREENFIELD）
+
+Step 3 检测到 `GREENFIELD=true` 时叠加以下规则。核心思想：**架构决策也是需求的产物，走同一条 specs 流水线**——选型即设计，搭建即任务，享受同样的人审卡点、断点恢复和审计链。
+
+### G1: 技术选型确认（并入 Step 5.5）
+
+**先读完需求再谈选型，推荐必须从需求特征推导，不套通用默认。** 流程：
+
+0. **交付形态必问（第一问，不可默认）**：Web / iOS / Android / 小程序 / 桌面 / 多端——这是所有架构决策的第一分叉，需求没写就必须问，答案强制写入 ADR 和 CLAUDE.md 的「交付形态」字段。**历史事故：需求只说"做一个 XX"，AI 默认 Web，用户要的是 App**
+1. **联网校验当前最佳实践**：确认交付形态后，用当前运行时可用的网络搜索能力查该形态的当年主流架构搭配（脚手架生态迭代快，不可凭记忆推荐）；网络不可用 → 使用 `{CM_WORKFLOW_ROOT}/templates/arch-reference.md` 基准表兜底，并向用户标注快照日期建议复核；联网发现基准表过时 → 顺手更新它
+2. **提取需求特征**并给出架构含义（展示推导过程，让人能审）：
+
+```text
+需求特征 → 架构含义（示例）
+- 营销页/需要 SEO      → SSR/SSG 框架（Next/Nuxt/Astro）
+- 纯工具/管理后台      → SPA 即可（Vite + React/Vue）
+- 实时行情/推送        → WebSocket/SSE 支撑,考虑轻后端
+- 多端(Web+小程序)     → 跨端框架(Taro/uni-app)或分仓
+- 有交易/资产          → 后端必选,金融铁律生效(decimal/审计)
+- 团队约束/部署条件    → 一票否决项,压过所有技术偏好
+```
+
+2.5 **团队首选脚手架优先**：`arch-reference.md` 中标注「团队首选」的脚手架（当前为 better-t-stack），当其能力矩阵覆盖本次选型所需组件时，推荐方案默认基于它生成（一条命令出全栈，前端/后端/ORM/鉴权按选型定制）；能力矩阵覆盖不了的场景按特征正常推导，不硬套
+3. 基于特征给出 **2-3 套定制方案**，每套包含：技术栈、取舍、**对应的脚手架命令**（如 `npx create-expo-app`、`npx create-next-app`、`npm create vite@latest`、`taro init`），并标注推荐项及推导理由（含联网校验的来源）。**命令验证边界：只许 `--help` 核实参数、`--dry-run` 验证组合，不得实际生成项目**——生成是 T-001 的职责，G1 阶段生成会让 N1 撞上"目录非空 + T-001 未勾选"信号，凭空多一次人工确认（实测教训）
+4. 人做选择题，不做填空题；确认结果连同脚手架命令写入 ADR，bootstrap T-001 直接使用该命令。**写入 ADR 的必须是全参数命令**（含包管理器等全部选项）——缺参数的命令会在无人值守执行时停下来交互式提问；现代脚手架（如 better-t-stack）完成/dry-run 时会回显"可复现完整命令"，抄它进 ADR 是标准做法
+
+必须覆盖的提问维度：
+
+- 团队已熟悉的技术栈（这是约束，不是偏好）
+- 部署条件（自有服务器 / 云 / Serverless / 内网）
+- 版本控制（默认本地 git init，写成"默认 X 如不符请指出"；用户明确不用 → bootstrap 的 CLAUDE.md 版本控制字段记 `none`，全链路降级）
+- 性能与规模预期
+- 第三方服务预算（数据库、鉴权、存储是自建还是用托管服务）
+
+**选型未确认前不得进入 Step 6。**
+
+### G2: 生成 0.bootstrap feature（在业务 feature 之前）
+
+编号固定为 `0`，业务 feature 从 `1` 开始：
+
+```text
+{SPECS_DIR}/
+├── docs/
+├── 0.bootstrap/          ← 0→1 专属
+│   ├── requirements.md   # 非功能需求：团队约束、部署条件、性能要求、预算
+│   ├── design.md         # 即 ADR：候选方案对比表、最终选型、每项理由
+│   └── tasks.md          # 见下方任务模板
+└── 1.{business-feature}/
+```
+
+`design.md` 按 ADR（架构决策记录）写：候选方案对比表（方案 / 优势 / 代价 / 是否入选）+ 最终选型清单 + 每项决策的理由。**这份文件就是日后回答"当时为什么选 X"的唯一出处。**
+
+`tasks.md` 任务模板（按需裁剪）：
+
+```markdown
+- [ ] T-001: 用官方脚手架生成项目骨架（{选定的 create 命令}）；脚手架未自带 git 时执行 git init ~15min
+- [ ] T-002: 生成 .claude/ 规范（等同 $cm-init 产出，基于已选型技术栈） ~15min
+- [ ] T-003: CI 与部署骨架（lint/test/build 流水线，环境变量模板） ~30min ——**计划迭代 ≥3 个 feature 的项目不得裁剪本任务**：测试是基建不是环节，第一周省下的半小时会在第五周连本带利还（实测两次 demo 裁剪 + 行业重度实践共同教训）
+- [ ] T-004: 公共底座（请求封装、错误处理、基础布局/入口结构） ~30min
+```
+
+### G3: 业务 feature 的生成规则
+
+业务 feature 的 design.md 基于 **G1 已确认的选型**生成（此时规范文件尚不存在，以选型结论为准）。执行时序由 $cm-ai 保证：`0.bootstrap` 最优先执行，完成后规范已落地，后续 feature 加载的就是真实的 CLAUDE.md 和 rules。
+
+### G4: 后续架构变更
+
+架构调整走已有变更模式：`$cm-prd --change 0.bootstrap 数据库从 SQLite 换 Postgres`——ADR 追加版本行，决策演进全程留痕。
+
+**执行中发现架构错配的标准处置**（如 $cm-ai 跑到一半发现交付形态/框架不对）：
+
+1. **干净停点**：当前任务走完 N5（标记+落盘）再停
+2. **形态确认与回收率评估**（先问清目标形态再动手）：PWA/壳 ≈90% 可回收 / 跨端框架 30-60%（逻辑与 API 层可迁，UI 重写）/ 原生 ≈10%（只有 specs 与契约可复用）
+3. `$cm-prd --change 0.bootstrap 交付形态从 X 改为 Y` → ADR 记 v2，受影响任务标 `[DROPPED]`/`[NEW]`（含显式迁移任务），已完成可保留的不动
+4. **旧代码移入 `legacy/`**，可回收部分由迁移任务显式搬运；重跑 $cm-ai 时 N1 的目录信号会强制确认目录处置
+5. 断点恢复按新标记续跑

package/workflows/cm/skills/cm-prd/references/phase-timing.md

@@ -0,0 +1,60 @@
+# $cm-prd 阶段耗时事件
+
+本规则复用 `runtime/logging.md` 的 `progress/start|complete`。时间以事件 envelope 的
+`at` 为准，不新增计时器，不写调用方猜测的 `duration_ms`，也不启动心跳。
+
+## 1. 事件配对
+
+每个实际执行阶段在开始前写 `progress/start`，完成后写 `progress/complete`。一对事件
+必须具有相同的 `operation_id`、`phase_name` 和 `segment`；`segment` 从 1 开始。
+
+开始事件只记录上述三个字段。完成事件可追加以下最小元数据：
+
+- `outcome`: `completed | awaiting_input | blocked`；
+- `context_scope`、`feature_count`、`functional_count`、`ac_count`、`task_count`、
+  `test_case_count`、`finding_count` 等非负计数或枚举；
+- 审查阶段可记录 `reviewer`、`independent`、`verdict` 和相对 evidence 路径。
+
+不得记录需求、源码、diff、prompt、模型回答、开放问题正文或用户回复正文。未实际执行
+的阶段不写 start/complete，也不为了让图表完整伪造 `skipped`。
+
+## 2. 新建模式边界
+
+| operation_id / phase_name | start | complete |
+| --- | --- | --- |
+| `prd-context` / `context_load` | Step 4 读取项目上下文前 | 初次 `CONTEXT_SCOPE` 判定和加载完成后 |
+| `prd-requirements` / `requirements_analysis` | Step 5 分析需求前 | Step 8 `requirements.md` 写完后 |
+| `prd-design` / `design_generation` | Step 8.5 开始前 | Step 9 `design.md` 写完、Step 9.5 审查前 |
+| `prd-design-review` / `design_review` | Step 9.5 实际触发审查前 | 审查凭证落盘且处置完成后 |
+| `prd-task-split` / `task_split` | Step 10 拆任务前 | `tasks.md` 写完后 |
+| `prd-spec-validation` / `spec_validation` | Step 10.4 前 | Step 10.5 测试合同校验与规格自检完成后 |
+| `prd-spec-review` / `spec_review` | Step 10.6 审查前 | 审查凭证落盘且处置完成后 |
+
+Step 9.5 未触发时不写 `prd-design-review`；已有 `decision/design_review` 继续记录跳过原因。
+
+## 3. 变更模式边界
+
+| operation_id / phase_name | start | complete |
+| --- | --- | --- |
+| `prd-context` / `context_load` | C1 定位 specs 前 | C3 现有 specs 与变更输入读取完成后 |
+| `prd-requirements` / `requirements_analysis` | C4 对比分析前 | C5 `requirements.md` 更新完成后 |
+| `prd-design` / `design_generation` | C6 前 | `design.md` 更新完成后 |
+| `prd-task-split` / `task_split` | C7 前 | `tasks.md` 更新完成后 |
+| `prd-spec-validation` / `spec_validation` | C7.5 前 | 测试合同更新、引用校验和审批位重算完成后 |
+
+变更模式没有实际执行 Step 9.5/10.6 时，不写 review timing 事件。
+
+## 4. 暂停、恢复与失败
+
+需要等待用户回答、登录或选择时，在硬停车前写当前阶段 `progress/complete`，设置
+`outcome: awaiting_input`。恢复后用相同 operation/phase、递增后的 `segment` 写新一对
+start/complete；因此后续分析只汇总 active segments，不把人工等待算成执行耗时。
+
+阶段无法继续时写 complete + `outcome: blocked`，随后按主流程写 warning/error/run_done。
+同一 segment 不得出现两个 complete；恢复不得复用已关闭的 segment。
+
+## 5. 最终报告
+
+最终摘要只说明“阶段耗时事件已记录”，不手算或猜测耗时。需要复盘时运行
+`python3 {CM_WORKFLOW_ROOT}/scripts/cm-prd-timing.py --last 5`；它只读全局镜像，按
+operation_id + phase_name + segment 配对时间戳，并明确显示未配对事件。

package/workflows/cm/skills/cm-prd/references/spec-self-check.md

@@ -0,0 +1,22 @@
+# $cm-prd Step 10.5 — 规格自检
+
+输出摘要卡之前，先对刚生成的三件套与可选测试合同跑机器可查项。机器项由 AI
+自行清干净，人审只留业务意图。
+
+## 通用自检项
+
+- [ ] 任务依赖无环；单 feature ≤15 个任务；同一文件/组件的行为未拆散到多任务
+- [ ] 每条 AC 都能回答“怎么验证”；验证方式不明的 AC 视为不过
+- [ ] test-cases.json 语法/结构合法，AC→TC→Task 完整，用户用例未被弱化
+- [ ] 任务产物查重：不与项目已有资产重复；有地图查 04/05/06，无地图用代码搜索核实
+
+## 二开附加项（存在业务地图时）
+
+- [ ] **引用真实性**：specs 提到的每个存量文件/函数/组件名都已用代码搜索核实
+  真实存在（二开引用不存在的存量代码，人审通常发现不了、执行期才会失败）
+- [ ] **B5 合规**：feature 未跨多条 07 业务线路；跨模块任务已列出模块清单
+- [ ] **B3 合规**：修改存量模块的 feature，第一个任务是防护网基线
+- [ ] **B2 完整**：design.md 含「波及面」段，所列模块在地图/代码中真实存在
+
+有不过项时自行修正 specs 后重跑，最多 2 轮。2 轮后仍不过的项不得静默放行，
+写入摘要卡「风险点」交人裁决。自检结果一行附在摘要卡底部。

package/workflows/cm/skills/cm-product-manager/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: cm-product-manager
+description: 产品经理 Skill，负责需求分析、用户故事与验收标准编写、歧义清单生成、变更影响分析、业务验收走查；把关型角色，不做技术设计与技术测试
+---
+
+# cm-product-manager — 产品经理
+
+把关型角色：把需求问对、拆对、验收对。**本 skill 的产出是结构化的问题和标准，业务拍板永远是人**——绝不替用户做业务决策。
+
+## 触发条件
+
+- `/cm-prd` 需求分析阶段（Step 5 / 5.5）自动调用
+- `/cm-prd --change` 变更影响分析（Step C4）时调用
+- `/cm-ai` 的 N6 中，feature 完成触发的 QA 通过后，执行业务验收走查
+
+## 职责边界
+
+- **管**：需求提取、用户故事、验收标准、优先级建议、歧义识别、变更影响分析、业务验收走查
+- **不管**：技术设计（→ 各工种 skill）、技术测试（→ cm-qa-engineer）、业务决策（→ 人）
+
+## 工作流程
+
+### 1. 需求分析（服务 /cm-prd Step 5）
+
+**输入前置**：原始需求文档缺失、为空或不可读 → 直接上报「输入不完整」终止本步，不得凭目录名/项目名想象需求；文档存在但某功能只有标题无描述 → 该功能整体进歧义清单，不产出想象的 AC。
+
+从原始需求文档提取，产出结构化结果：
+
+- **用户故事**：作为 {角色}，我想要 {功能}，以便 {价值}——价值说不清的功能标记为疑问，进歧义清单
+- **功能需求**：[F-xxx] 编号，一句话一条，用**可验证的表述**（不写"优化体验"这类无法验证的描述）
+- **非功能需求**：性能 / 安全 / 兼容性——来自文档明示，或场景推断（推断的标注"待确认"）
+- **验收标准**：[AC-xxx] 每条可测试——写"密码错误 5 次锁定 10 分钟"，不写"登录要安全"
+- **数据指标**（营销类功能强制；判定：功能目的含拉新/转化/促活/留存/推送触达任一项即为营销类，存疑按营销类处理）：定义埋点事件与成功指标（转化率/留存等），作为 AC 或非功能需求写入
+
+### 2. 歧义清单（服务 Step 5.5，反问式）
+
+对每个功能过一遍五问，答不上的进开放问题清单：
+
+1. 目标用户是谁？多角色时权限差异是什么？
+2. 边界在哪？本期做到什么程度，明确**不做**什么？交付形态是否与现有项目一致（存量项目上出现"App/小程序"字样的需求 = 架构变更信号，必须显式确认）？
+3. 什么算成功？有没有可观察的完成判据？
+4. 异常怎么办？失败 / 超时 / 冲突时用户看到什么？
+5. 有没有敏感操作？支付 / 删除 / 隐私相关 → 必须人工确认
+
+**克制原则**：只列真正无法合理推断的问题；可以合理默认的写成"默认 X，如不符请指出"——不做无限追问式的确认（SuperPowers 的教训）。
+
+### 3. 拆分与优先级建议（服务 Step 6-7）
+
+- feature 按**用户可感知的完整功能**切，不按技术层切（技术分层是 task 的事）
+- MVP 优先：主流程 feature 在前，增强类在后
+- 标注 feature 间依赖，给执行顺序建议
+
+### 4. 变更影响分析（服务 --change 模式）
+
+- 对比新旧需求 → 新增 / 修改 / 删除清单
+- 影响面评估：波及哪些**已完成任务**（返工风险）、哪些验收标准失效
+- 输出变更摘要供人审，不自行决定取舍
+
+### 5. 业务验收走查（服务 N6，feature 级 QA 通过后）
+
+技术测试归 QA，本步是**用户视角**的走查：
+
+- **AC 逐条对照**：每条标注 通过 / 不通过 / 需人工验证，**结果回写 requirements.md 的 AC checkbox**（与 QA 的技术核验共用同一落盘位置）。**冲突规则**：QA 已标 `[x]` 而业务走查不通过 → 不得改回 `[ ]`（会抹掉 QA 结论），改为在该条后追加 `⚠ 走查不通过: {原因}` 并计入业务偏差清单——技术通过≠业务通过，两个结论都留痕
+- **流程闭环**：按用户故事从入口走到结果，中断处记录
+- **文案与提示**：错误提示是否说人话、关键操作有无确认、空状态有无引导
+- **业务偏差处理**：实现与需求本意不符 → 小偏差记入走查报告**并写入 LESSONS.md**（走查报告是会话输出，落盘靠 LESSONS）；涉及需求本意的偏差 → **暂停问人**，不自行认定"也可以"
+
+## 常见坑
+
+| 问题 | 处理 |
+| ---- | ---- |
+| 验收标准写成技术指标 | AC 用用户可观察的行为表述，技术指标归入非功能需求 |
+| 需求按技术层拆成 feature | 按用户可感知功能切；前端/后端分工是 task 层的事 |
+| 歧义问题一次问太多 | 只问无法合理默认的，其余写"默认 X，如不符请指出" |
+| 业务走查时替用户拍板 | 偏差只记录和上报，是否接受由人决定 |
+| 用户故事沦为格式套话 | 写不出"以便 {价值}"的功能，本身就是一个开放问题 |
+
+## 输出
+
+- **需求分析**：用户故事 + 编号功能需求 + 验收标准（直接进 requirements.md 对应章节）
+- **歧义清单**：开放问题列表，每条带"为什么需要确认"
+- **变更影响摘要**（变更模式）：新增/修改/删除 + 返工风险
+- **验收走查报告**（N6）：AC 逐条结论 + 流程走查记录 + 业务偏差清单

package/workflows/cm/skills/cm-qa-engineer/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: cm-qa-engineer
+description: QA 工程师 Skill，执行功能测试、E2E 测试、可视化回归、验收标准核验，自动适配项目测试框架
+---
+
+# cm-qa-engineer — QA 工程师
+
+在开发任务完成后执行整体质量验证。自动识别项目测试框架。
+
+## 调用模式
+
+| 模式 | 调用方 | 写入权限 |
+| --- | --- | --- |
+| `implementation` | `$cm-ai` 的 N6 | 可按既有规范补测试并回写 AC |
+| `readonly` | `$cm-test` | 只运行与取证；禁止改源码、测试、依赖、快照和 specs |
+
+未显式指定时，只有 `$cm-ai` 自动调用可默认 `implementation`；`$cm-test` 必须显式
+传入 `readonly`，其只读边界优先于本 Skill 后续任何“补全/修复/回写”指令。
+
+## 工作流程
+
+### 1. 识别测试框架
+
+自动检测，不做硬编码假设：
+
+- **单元/组件测试**：Vitest / Jest / Mocha / pytest / Go testing / Rust cargo test
+- **E2E 测试**：Playwright / Cypress / Selenium / Puppeteer
+- **覆盖率工具**：c8 / istanbul / coverage.py / go cover
+- implementation 模式如项目未配置测试框架，根据技术栈推荐并安装
+- readonly 模式缺少框架或依赖 → 记 `BLOCKED`，不得安装
+
+### 2. 读取上下文
+
+- requirements.md 中的验收标准
+- design.md 了解功能模块和接口契约
+- test-cases.json（如存在）按 `../../runtime/test-contract.md` 读取
+- `.claude/rules/testing.md`（如存在）
+- 扫描现有测试文件了解测试模式和覆盖情况
+
+### 3. 补全测试（仅 implementation）
+
+对开发阶段未写测试的代码补充：
+
+- **组件**：渲染测试、交互测试、Props 边界
+- **API/服务层**：正常流、异常流、边界值
+- **工具函数**：输入输出覆盖
+- **数据库层**：migration 可执行、查询结果正确
+
+遵循项目已有的测试文件命名和目录约定。
+
+readonly 模式跳过本节，不得创建、修改或修复任何测试。
+
+**二开回归范围跟波及面走**：design.md 存在「波及面」段时，回归测试范围 = 新功能 AC + 波及面清单上的存量功能逐项冒烟——新功能好不好是一半，老功能没坏才是另一半。
+
+**禁止前提共谋（硬规则）**：断言含具体数值时，测试输入必须**多参数化**（至少覆盖 2-3 组不同前提），禁止测试与被测代码共享同一默认前提——硬编码值在唯一被测前提下"恰好成立"是已实证的盲区模式（实跑教训：断言与配置都默认 A4，切 A5 即错位 39.9mm，参数化后现形）。
+
+### 4. 运行测试
+
+调用方 `$cm-ai` N6 或 `$cm-test` 负责 `test_run/start` 与 `test_run/complete`；
+本 Skill 不重复写调用级边界。存在 AI 测试合同时，本 Skill 在每个 blocking case
+实际执行前写 `test_run/case_start`，并以 `case_complete` 或 `case_blocked` 唯一
+收口；每次真实重试携带递增 `attempt`。仅当本轮存在 CM specs 时才在关键阶段同步
+更新 `.cm-status.json`，standalone `$cm-test` 不创建该文件，也不使用后台心跳。
+
+```bash
+# 根据项目实际命令执行
+npm run test              # 或 pnpm test / cargo test / pytest
+npm run test -- --coverage  # 覆盖率
+npx playwright test       # E2E
+```
+
+收集：通过数/失败数/覆盖率。
+
+有 test-cases.json 时，正式命令证据与用例逐条关联；不能用静态 logic
+`SUPPORTED` 计入命令通过数。
+
+### 5. 可视化回归（如涉及 UI）
+
+1. 识别交付形态并启动正式测试载体：Web 启动开发服务器；微信小程序执行正式构建并
+   打开微信开发者工具。小程序同时读取
+   `../cm-miniprogram-engineer/references/release-checklist.md`，不得用 H5/Web target
+   冒充小程序运行结果。
+2. Web 选择浏览器驱动（按优先级）：
+   - **检查项目配置**：如 `.claude/rules/testing.md` 中指定了 `browser_driver`，使用用户指定的方式
+   - **默认：Playwright CDP（无头模式）** — 不弹窗，适合截图对比、DOM 断言、样式回归等大多数场景
+   - **自动升级：Chrome DevTools MCP** — 当检测到以下场景时切换：需要登录态/Cookie 持久化、OAuth/第三方弹窗交互、需要观察真实动画/过渡效果、用户明确要求实时调试
+   - 切换前输出：`🔄 切换到 Chrome DevTools MCP — 原因: {原因}，浏览器窗口将弹出`
+   微信小程序不进入此浏览器驱动分支：基础交互走开发者工具模拟器，授权、设备差异和
+   平台 API 走预览/体验版真机；工具或账号不可用时对应 blocking case 为 `BLOCKED`。
+3. 截图保存
+4. 对比基准截图（如有）
+5. test-cases.json 中的 browser cases 逐条执行 steps、断言 expected，并记录
+   `PASS | FAIL | BLOCKED`；cleanup 失败时记 `BLOCKED`
+6. 临时 profile、进程、模型别名或 fixture 使用前写 `resource/acquired`，清理后
+   用同一 `resource_id` 写 `resource/released`；每次新获取生成新的 ID，释放后的
+   ID 不复用。写入 `cleanup_failed` 后保持 `BLOCKED`，不得把断言通过当作整个用例通过
+
+> **用户覆盖**：在 `.claude/rules/testing.md` 中添加 `browser_driver: playwright | chrome-mcp | ask` 可固定选择或设为每次询问。
+
+### 6. 验收标准核验
+
+逐条检查 requirements.md 中的验收标准：
+
+```markdown
+- [x] [AC-001] 描述 → 已通过测试验证
+- [ ] [AC-002] 描述 → ⚠️ 需手动验证
+```
+
+标注每条的验证方式（自动/手动/无法自动化）。
+
+implementation 模式的核验结果必须回写 requirements.md 的验收标准 checkbox
+（`[x] [AC-001] → 已通过测试验证`）。readonly 模式只写测试报告，不改
+requirements.md。
+
+### 7. 处理失败
+
+- 测试失败 → 判断是代码 bug、测试问题还是环境阻塞
+- implementation：代码 bug 汇报主 agent，测试问题可修复后重跑，最多 3 轮
+- readonly：保留原始失败，只报告给 `$cm-test`；不得修测试或代码，不自动调用
+  `$cm-fix`
+
+## 常见坑
+
+| 问题                     | 处理                                   |
+| ------------------------ | -------------------------------------- |
+| 测试环境和开发环境不一致 | 检查 test 配置中的环境变量和 mock 设置 |
+| 异步测试超时             | 增加 timeout，检查是否缺少 await       |
+| E2E 测试不稳定（flaky）  | 用 `waitFor` 代替固定延时，重试机制    |
+| 覆盖率统计不准           | 检查 coverage 配置的 include/exclude   |
+
+## 输出
+
+```text
+📋 QA 报告
+
+测试: {N} 通过 / {N} 失败 / 覆盖率 {N}%
+E2E: {状态}
+AI 测试合同: logic {N}/{N} 已核验 · browser {N}/{N} 已执行
+验收标准: {N}/{total} 通过, {N} 需手动验证
+安全扫描: {状态}
+结论: {PASSED / FAILED / NEEDS_MANUAL}
+```