@aibyzero/byz 0.0.0 → 0.1.2

package/workflows/cm-plugin/commands/cm-plugin:prd.md

@@ -0,0 +1,403 @@
+# /cm-plugin:prd — 需求文档 → 开发规格生成
+
+支持两种模式：新建需求和需求变更。
+
+## 输入参数
+
+`$ARGUMENTS` 格式：
+
+- **新建模式**：`/cm-plugin:prd {项目文件夹路径}`
+- **变更模式**：`/cm-plugin:prd --change {N}.{feature-name} 变更内容描述`
+
+用户提供一个项目文件夹路径，文件夹结构约定：
+
+```text
+{项目文件夹}/
+├── docs/           ← 需求文档（必须存在，PRD 从这里读取）
+├── 1.xxx/          ← 已有的 specs（如有）
+├── 2.xxx/          ← 本次生成的 specs
+└── ...
+```
+
+## 模式判断
+
+如果 `$ARGUMENTS` 以 `--change` 开头 → **读取 `~/.claude/commands/cm-plugin-prd-modes/change-mode.md`** 执行变更模式（C1–C8）
+否则 → 进入新建模式
+
+---
+
+## 新建模式
+
+### Step 1: 解析输入，读取需求文档
+
+从 `$ARGUMENTS` 提取项目文件夹路径，记为 `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/ 下有多个文件，全部读取并综合分析
+- 如果 docs/ 不存在或为空，报错提示用户先在 docs/ 下放入需求文档
+
+### Step 2: 获取项目名称
+
+- 从当前目录的 `package.json` name 字段、`Cargo.toml`、`go.mod` 等提取项目名
+- 如无法提取，使用当前目录名
+- 转为 kebab-case，记为 `PROJECT_NAME`
+
+### Step 3: 探测项目架构类型
+
+**代码项目根的确定（防在错误目录生成脏规格）**：`$ARGUMENTS` 中显式给了代码项目路径（如 `代码在~/code/app`）→ 以其为准；未给 → 用当前工作目录（约定:在代码项目内运行本命令），但**必须先自检**——当前目录含项目描述文件或源码、且其内容与需求文档所述业务相符；明显不符（如当前目录是另一个项目/工具仓库）→ **停下询问代码项目路径**，不得静默把错误目录当项目上下文（空目录检测只兜全空 case，兜不住"错但有效"的目录）。
+
+扫描项目根目录、配置文件、目录结构、依赖声明，自行判断架构类型（纯扩展单仓 / 扩展+后端 monorepo / 多仓库等）。记录 `ARCH_TYPE`。
+
+**空项目检测**：代码项目不存在、或为空目录（无 package.json / Cargo.toml / go.mod 等项目描述文件，且无源码目录）→ **先问用户确认空目录的含义，不得自行假设**：
+
+> "代码目录为空——这是【全新项目】（走 0→1 分支，我来推荐架构和脚手架），还是【存量项目还没 clone】（请先 clone 到该目录，再重新运行 /cm-plugin:prd）？"
+
+- 确认全新项目 → 标记 `GREENFIELD=true`，**读取 `~/.claude/commands/cm-plugin-prd-modes/greenfield.md`** 叠加 G1–G4 规则，Step 4 跳过
+- 确认未 clone → **中止本次执行**，提示 clone 完成后重跑（在不存在的项目上下文上生成 design.md 是有毒规格）
+
+### Step 4: 读取项目上下文（存量项目 = 二开模式，叠加 B 规则）
+
+- 读取各仓库的 `.claude/CLAUDE.md` 了解技术栈
+- 读取 `.claude/rules/` 下所有规则文件
+- 扫描目录结构，了解现有模块划分
+- **B1 加载代码库参考文档**：**先读代码项目根 CLAUDE.md 的「业务地图」字段**（多层仓库下以代码项目根为准，仓库根 CLAUDE.md 无此字段再看地图 00-index 头部；init 已判定过，不重复判断）：字段=已生成/已刷新 或 `docs/codebase-context/` 存在 → 按 `codebase-context` skill dev 模式加载 10 份文档（后续步骤查重与波及面分析的数据源）；字段=跳过(小项目) → **不建议 scan，直接读代码**（小项目全量读的成本本来就低）；字段缺失且文档不存在 → 建议先执行 `/codebase-context scan`；**skill 本身未安装** → 提示重装最新包，本次降级为直接读代码，波及面分析降级为 grep 推断（照常可跑，只是更贵更粗）
+
+**二开模式追加规则**（GREENFIELD=false 且本次需求会修改存量代码时生效）→ **读取 `~/.claude/commands/cm-plugin-prd-modes/brownfield.md`** 执行 B2 波及面 / B3 防护网基线 / B4 增量 specs / B5 拆分锚定地图。
+
+
+### Step 5: 分析需求
+
+**调用 `cm-plugin-product-manager` skill 执行本步和 Step 5.5**——用户故事、编号功能需求、验收标准的编写方法和歧义五问以该 skill 为准。
+
+需求涉及**新增权限 / 收集用户数据 / 注入第三方网站 / 加载远程内容**时，在本步同时做**商店合规预扫**（检查方法以 `cm-plugin-qa-engineer` skill 的商店合规检查单为准）：每项权限给出用途理由、标记单一用途政策风险点、列出需要隐私政策披露的数据项——发现的问题作为合规开放问题并入 Step 5.5 一并确认，确认结果写入 requirements.md 非功能需求节与 design.md 安全考虑节。**权限问题在规格期确认的成本是一句话，上架被拒后的成本是整轮返工。**
+
+从文档中提取功能目标、用户故事、验收标准、约束条件、依赖。
+
+### Step 5.5: 开放问题确认
+
+分析需求后，如果存在以下情况，**必须暂停并与用户对话确认**，不要自行假设：
+
+- 需求描述模糊或有歧义的功能点
+- 多种技术实现方案且差异较大
+- 缺少关键信息（如目标平台、兼容性要求、第三方服务选型）
+- 业务逻辑有矛盾或不完整
+- 涉及权限、支付、敏感操作等需要明确确认的功能
+
+格式：
+
+```
+❓ 需要确认以下问题：
+
+1. {问题描述} — {为什么需要确认}
+2. {问题描述} — {为什么需要确认}
+
+请逐一回复后继续生成 specs
+```
+
+所有问题确认完毕后再进入 Step 6。
+
+### Step 6: 推断 feature 名称
+
+根据需求内容生成一个简洁的 kebab-case 英文名称。
+
+### Step 7: 生成 specs 目录
+
+检查 `{SPECS_DIR}/` 下已有的编号目录（如 `1.xxx/`、`2.xxx/`），取最大编号 +1。
+
+```text
+{SPECS_DIR}/
+├── docs/                        ← 需求文档（输入）
+├── 1.比如这是一个已有的标题/     ← 已有 specs
+└── 2.{feature-name}/            ← 本次新建
+    ├── requirements.md
+    ├── design.md
+    └── tasks.md
+```
+
+### Step 8: 生成 requirements.md
+
+```markdown
+# {Feature 名称} — 需求规格
+
+## 概述
+
+{一句话描述}
+
+## 项目信息
+
+- 项目名: {PROJECT_NAME}
+- 架构类型: {ARCH_TYPE}
+
+## 需求版本
+
+| 日期         | 版本 | 说明     |
+| ------------ | ---- | -------- |
+| {YYYY-MM-DD} | v1   | 初始需求 |
+
+## 用户故事
+
+- 作为 {角色}，我想要 {功能}，以便 {价值}
+
+## 功能需求
+
+1. [F-001] {需求描述}
+2. [F-002] {需求描述}
+
+## 非功能需求
+
+- 性能: {要求}
+- 安全: {要求}
+- 兼容性: {要求}
+
+## 验收标准
+
+- [ ] [AC-001] {标准描述}
+
+## 依赖
+
+- {外部服务/库}
+
+## 开放问题
+
+- {待确认事项}
+```
+
+### 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`
+
+有基准时，design.md 记录基准路径，且「接口契约」节须包含**组件契约**（组件名 / props / 事件）。
+
+### Step 9: 生成 design.md
+
+**必须先读取项目 `.claude/CLAUDE.md` 和 `.claude/rules/` 下所有规范文件**，设计方案必须遵循项目已有的技术规范和约定。
+
+按功能模块设计，每个模块说明涉及哪些层（service worker / content script / popup / options / side panel / 配套后端等），具体分层根据项目实际架构决定，不做硬编码限制。**涉及多个扩展上下文的模块必须写清消息通信方向与消息格式**（谁发起、经过谁、`chrome.runtime.sendMessage` 还是 port 长连接）——上下文间通信契约是扩展开发的头号返工源。
+
+```markdown
+# {Feature 名称} — 技术设计
+
+## 设计版本
+
+| 日期         | 版本 | 说明     |
+| ------------ | ---- | -------- |
+| {YYYY-MM-DD} | v1   | 初始设计 |
+
+## 项目架构
+
+- 架构类型: {ARCH_TYPE}
+- 涉及层: {根据项目实际情况列出}
+
+## 功能模块设计
+
+### 模块 1: {模块名}
+
+{技术方案，遵循 .claude/rules/ 中的规范}
+
+**涉及层及关键设计:**
+
+{根据项目实际分层描述，如数据模型、API 接口、组件设计、合约接口等}
+
+### 模块 2: {模块名}
+
+...
+
+## 接口契约
+
+{扩展内消息契约（message type / payload / 响应）、配套后端 API 等 — 根据项目类型决定}
+
+## 数据模型
+
+{chrome.storage 分区(local/sync/session)与 schema、IndexedDB、后端数据表 — 根据项目类型决定}
+
+## 安全考虑
+
+{基于 .claude/rules/security.md 和项目特有的安全规范}
+
+## 技术决策
+
+| 决策 | 选项 | 理由 |
+| ---- | ---- | ---- |
+```
+
+### Step 9.5: 方案对抗审查（最贵的决策补上第二双眼睛）
+
+design.md 生成后，满足任一触发条件 → 交**第二模型对抗审查一轮**（Codex 主通道；不可用按 N4 降级链用对抗子代理）：
+
+- GREENFIELD 的 ADR（架构选型是最贵决策）
+- 二开且修改存量模块（方案错误会伤及老功能）
+- design 含新模块、依赖方向变化或跨模块数据流
+- 功能点 F ≥ 5 的大 feature
+
+**投喂内容**:requirements.md + design.md 全文 + 项目 `.claude/rules/` 相关规范 +(二开)「波及面」段与被改存量模块现状代码——只给 design 不给上下文,审查质量减半(10.6 有投喂清单本步没有,内部不一致,此处补齐)。
+提示词要义："**这是隔壁同事做的方案，详细审查一下**"——重点查架构隔离、模块边界、与现有管线的耦合、数据流缺口；只报告有具体失败场景的问题，零发现明说（审查产出纪律同 N4）。**仅 1 轮**：采纳项修正 design.md 后进 Step 10；分歧项写入摘要卡「风险点」交人裁决。小 feature 不触发，零额外负担。
+**凭证落盘**:审查原文 tee 到 `{SPECS_DIR}/.reviews/prd-{feature}-design-r1.md`——摘要卡「方案对抗审查」行必须与凭证对得上,无凭证的数字是自报(凭证教义全框架一体,规格期不豁免)。
+
+> 依据：代码有 N4 对抗、规格有 10.5 自检，唯独技术方案此前无第二模型把关——而方案错误是最贵的错误（行业重度实践的最大单笔收益正是方案期拦截架构缺陷）。
+
+### Step 10: 生成 tasks.md
+
+**按功能拆任务。** AI 执行时根据 design.md 自动判断每个任务涉及哪些层。
+
+```markdown
+# {Feature 名称} — 任务清单
+
+## 任务版本
+
+| 日期         | 版本 | 说明     |
+| ------------ | ---- | -------- |
+| {YYYY-MM-DD} | v1   | 初始任务 |
+
+## 项目信息
+
+- 项目名: {PROJECT_NAME}
+- 架构类型: {ARCH_TYPE}
+- specs 路径: {SPECS_DIR}/{N}.{feature-name}/
+
+## 任务列表
+
+### UI 还原（仅当存在 design-baseline 时生成本节）
+
+- [ ] T-001: 还原 {页面/组件} ~30min（基准: design-baseline/；本 feature 的扩展功能任务依赖本任务）
+
+### 功能 1: {功能名}
+
+- [ ] T-002: {任务描述} ~{预估时间}
+- [ ] T-003: {任务描述} ~{预估时间}
+
+### 功能 2: {功能名}
+
+- [ ] T-003: {任务描述} ~{预估时间}
+
+### 集成与测试
+
+- [ ] T-010: 联调测试 ~{预估时间}
+- [ ] T-011: E2E 测试 ~{预估时间}
+- [ ] T-012: 部署 staging 并冒烟验证 ~15min（依赖本 feature 全部开发与测试任务）
+
+> 部署任务前提：项目存在部署形态（Dockerfile / CI 配置 / 部署脚本，或 0→1 项目——bootstrap 已建 CI 骨架）才生成 T-012；**纯本地工具、库等无部署形态的项目不生成**，避免执行期反复触发"无 staging 环境"上报。
+
+## 依赖关系
+
+- T-002 依赖 T-001
+
+## 风险点
+
+- {可能遇到的问题及应对}
+```
+
+**任务拆解原则：**
+
+- 按功能拆，AI 执行时读 design.md 自动识别涉及哪些层；**二开项目按 B5 锚定业务地图**（feature 沿 07 线路、任务尽量单模块）
+- 原子性，可独立完成和验证
+- **同一组件/同一文件内的行为不拆分为多个任务**（如"渲染列表项"和"列表项的删除确认"归一个任务）——拆开会导致执行时自然合并、任务标记与提交失配（实跑验证的教训）
+- 预估完成时间（5min / 15min / 30min / 1h）
+- **粒度控制**：每个子 specs（feature 目录）不宜过大，单个 tasks.md 控制在 **10-15 个任务以内**。如果需求过大，应在 Step 6 之前拆成多个独立的 feature 目录（如 `2.user-auth-login`、`3.user-auth-register`），每个 feature 有自己的 requirements/design/tasks 三件套。这样 cm-plugin:ai 执行时上下文可控，不会因为 specs 太大导致丢失关键信息。
+
+### Step 10.5: 规格自检（机器项，AI 自查自修，人不参与）
+
+输出摘要卡之前，先对刚生成的三件套跑一遍机器可查项——**机器项 AI 自己清干净，人审只留业务意图**：
+
+**通用自检项（所有项目）：**
+
+- [ ] 任务依赖无环；单 feature ≤15 个任务；同一文件/组件的行为未拆散到多任务
+- [ ] 每条 AC 都能回答"怎么验证"（验证方式不明的 AC 视为不过）
+- [ ] 任务产物查重：不与项目已有资产重复造（有地图查 04/05/06，无地图 Grep 核实）
+
+**二开附加项（存在业务地图时）：**
+
+- [ ] **引用真实性（治引用幻觉）**：specs 中提到的每个存量文件/函数/组件名，用 Grep 逐个核实真实存在——二开 spec 引用不存在的存量代码，人审查不出来、执行期才炸
+- [ ] **B5 合规**：feature 未跨多条 07 业务线路；跨模块任务已在描述中列模块清单
+- [ ] **B3 合规**：修改存量模块的 feature，第一个任务是防护网基线
+- [ ] **B2 完整**：design.md 含「波及面」段，且所列模块在地图/代码中真实存在
+
+**处置规则**：有不过项 → AI 自行修正 specs 后重跑自检，**最多 2 轮**；2 轮后仍不过的项不许静默放行，写入摘要卡「风险点」交人裁决。自检结果一行附在摘要卡底部。
+
+### Step 10.6: Codex 规格审查（装了就用，未装才跳过）
+
+10.5 自检是机器项，查不出"**拆得对不对**"。自检通过后，把拆分结果交 Codex 过第二模型（触发口径同 N4：`codex` 可用即触发，未安装/不可用才跳过）：
+
+- **投喂内容**：requirements.md 功能点清单 + tasks.md 全文 + design.md「波及面」段（二开）——喂拆分结果，不喂三件套全文
+- **提示词要义**："这是隔壁同事拆的开发任务单，审查拆分质量：①任务边界有无重叠/遗漏 ②依赖顺序会不会卡死 ③粒度是否适合单任务交付验证 ④二开：波及面清单有没有漏掉会被牵连的模块。只报有具体后果的问题，没有问题就明说。"
+- **处置**：采纳项修正 specs 后重跑一次 10.5 自检；分歧项写入摘要卡「风险点」交人裁决。**仅 1 轮**，不与 Codex 拉扯
+- **凭证落盘**:审查原文 tee 到 `{SPECS_DIR}/.reviews/prd-{feature}-split-r1.md`,摘要卡「Codex 规格审查」行与之对应
+- **不设降级链**：Codex 未装 → 直接跳过并在摘要卡标注（规格审查是增益层；代码审查 N4 才是强制层）
+- 调用失败处理同 N4 纪律：失败原文记录，超时重试 1 次，仍失败按未装处理
+
+> 依据：拆分质量是二开乱改的最后闸门——10.5 只能查机器项（引用真实性、依赖环），"这个任务拆得会不会漏改关联模块"需要第二模型的判断力。
+
+### Step 11: 输出总结（附规格摘要卡 + 审查清单）
+
+**先输出规格摘要卡**——人审的第一入口是这张一屏卡片，不是三个长文件（实跑教训：直接丢长文件，人审会退化成扫一眼就"通过"）：
+
+```text
+┌─ 📋 规格摘要卡 ────────────────────────────
+│ 交付形态: {扩展表面组合,如 side panel+content script}   ← 第一分叉,看错全错
+│ 目标浏览器: {Chrome / Chrome+Edge / 含 Firefox}
+│ 权限清单: {permissions + host_permissions,逐项带用途}   ← 商店审核与用户信任的焦点
+│ Feature: {N 个}: {名称列表}
+│ 功能点: {N} 个 | AC: {N} 条 | 任务: {N} 个(预估 {x}h)
+│ 开放问题: {已答 N / 共 N}——{逐条一行: 问题→答案}
+│ 风险点: {商店合规/权限扩张/破坏性操作等敏感项,无则"无"}
+│ UI 基准: {像素级/结构级/纯参考/无}
+│ 🔎 规格自检: {N}/{N} 通过{（未过项已列入风险点）}
+│ 🧠 方案对抗审查: {通过 / {N}条已修 / 跳过(未触发)}
+│ 🤖 Codex 规格审查: {通过 / {N}条已修 / 跳过(未装)}
+└────────────────────────────────────────────
+有疑问的行,点开对应文件细看;摘要卡没问题再走下面的审查清单。
+```
+
+完成后报告：
+
+- Feature 名称和序号、Specs 路径、涉及的技术层、总任务数和预估总时间
+
+并输出**规格审查清单**——人审规格不是"看一眼"，按此逐项检查：
+
+```text
+📋 规格审查清单（人审时逐项勾选）
+- [ ] 任务跨 feature 查重：同一产物（文件/模块）未出现在多个任务中（实跑教训：bootstrap 底座与 feature 数据层重复）
+- [ ] 依赖关系完整：每个任务的前置依赖已声明，无环
+- [ ] AC 可测试：每条验收标准都能回答"怎么验证"
+- [ ] 粒度合规：同一组件/文件的行为未拆成多任务；单 feature ≤15 个任务
+- [ ] 开放问题已全部回答，敏感决策（法域/支付/权限）有人工确认记录
+- [ ] **交付形态与需求意图一致**（要 App 别画成网页），且已写入 ADR 与 CLAUDE.md 字段
+- [ ] **原型功能点覆盖 100%**（有交互原型时）：遍历记录中每个可交互元素都有对应 [F-xxx] 或死区标注，无静默丢弃
+```
+
+**规格审批位落盘**：报告输出后，写入 `{SPECS_DIR}/.cm-specs-status` 单行 JSON：
+`{"status":"awaiting_review","at":"{时间}","features":["1.xxx",...]}`
+
+**硬停车（不可违反）**：本命令的终点就是摘要卡与审查清单——**任何情况下不得在本会话顺势启动开发**，对话里的"继续"不构成开发授权。提示用户：**逐项审查通过后，运行 `/cm-plugin:ai` 开始开发**（N1 有入口闸：未审批的 specs 会先要求确认摘要卡）
+
+---
+
+---
+
+## 模式文件（按需读取,勿全量加载）
+
+- 0→1 全新项目: `cm-plugin-prd-modes/greenfield.md`（G1 选型/G2 bootstrap/G3 业务生成/G4 架构变更处置）
+- 存量二开: `cm-plugin-prd-modes/brownfield.md`（B2–B5）
+- 需求变更: `cm-plugin-prd-modes/change-mode.md`（C1–C8）
+
+> 拆分目的: 主文件只承载通用流程,执行器按分支加载对应规则——注意力预算优先(v0.9.11 机械拆分,语义零变更)。

package/workflows/cm-plugin/commands/cm-plugin:refactor.md

@@ -0,0 +1,147 @@
+# /cm-plugin:refactor — 重构闭环(行为保持)
+
+**用法**:`/cm-plugin:refactor {specs路径} {代码项目路径} 重构目标描述(哪块代码/为什么难维护)`
+
+结构调整专用闭环。**前提:什么都没坏,行为一丝不变**——设计依据见 `docs/重构流程设计/`(cm 小闭环纪律 × Anthropic 迁移方法论,核心教义:修规则,不修产物)。
+
+**分流门(先于一切,答错门就是错流程)**:
+
+- 有缺陷要修 → `/cm-plugin:fix`
+- 行为要变(哪怕"变得更合理")→ `/cm-plugin:prd --change`
+- 渐进式采用(如 JS→TS 逐文件、加类型注解)→ 不用本命令,直接改
+- 结构问题且行为保持 → 本命令
+
+**cm-plugin:ai 全局规则同等生效**:灾难级才暂停、多方案自主决策留痕、状态落盘(node 写 `REFACTOR`)、运行日志照记、Codex 纪律(装了就用,降级走 N4 三级链)。
+
+**续跑检测(先于 G0)**:`{SPECS_DIR}/refactors/` 下存在未收口 slug(档案无收口节 / 运行日志该 slug 无 `done` 事件)→ **按磁盘状态定位续跑站点**(RULEBOOK 版本、batch-log 完成集、队列缺口),G0 不重问、判官按 G0.5 重验后继续;无在制状态才走全新 G0。"队列=磁盘"的可恢复性必须有恢复入口才算数(对照系:cm-plugin:ai 有 tasks 断点、fix 有 slug 续跑,最长时的批量重构反而没有——本条补齐)。
+
+## G0: 可行性(人门)
+
+1. **动机量化**:动机必须落到可测指标——行数超限 / 重复块 N 处 / 依赖方向违规 / 圈复杂度。"代码不优雅"不构成动机
+2. **认领待触发备忘**:扫描 `{SPECS_DIR}/LESSONS.md` 的「待触发备忘」段,结构类条目(标记来源含"重构/拆分/看不惯")与本次目标相关的 → 列入范围并在输出注明认领;收口时销账(改状态为已认领,注档案路径)——备忘的回流出口(实跑教训:备忘只写不读,到期无人认领)
+3. 波及面:谁引用这块代码(有业务地图查 03/08,无地图 grep 调用方)
+4. 输出可行性摘要:范围清单 / 动机指标现值 / 波及面 / 预估轨道(轻量或批量)/ **预算可见乘法**(批量道必填:文件数 × 单文件估耗 = 总预算,拍脑袋的总数不作数)。**「不重构」是合法结论**——收益盖不住风险就明说,命令到此收口
+5. **🛑 人签核后才进下一步**(签核=踢下一阶段;阶段内不再停车)
+
+## G0.5: 判官自验证(无判官不开工)
+
+判官 = 能平等裁决改前改后代码的机械标准,分两层:
+
+- **基线层**:存量测试全量跑绿并记录;无测试资产 → 先写现状快照测试(B3 同款,锁行为不判对错)
+- **差分层**:对将被重构的入口函数/接口,构造代表性输入集(含边界值),记录改前输出;**harness 的环境解析照抄项目既有测试的做法**(依赖怎么找、浏览器怎么起)——自造解析必踩环境坑(实跑:playwright 全局安装,裸 import 失败,照抄 smoke.mjs 的 npm root -g 解析才通)(实证方法:12 组输入逐字节对比,json-keeper 拆 core.js 验证过)
+
+**自验证(判官没被验证过,就不配当判官)**:
+
+- 在**原代码**上跑 → 必须全绿
+- 在**故意破坏的代码**上跑(手动种 ≥2 处行为变异,如改一个返回值、删一个分支)→ 必须变红;**不红的判官修到红为止**,变异恢复后再开工
+- 判官报大面积失败时先怀疑判官(比较器空白处理/序列化陷阱是已知假阳性源),"一个把所有东西都判失败的裁判,通常是它坏了"
+
+## 规模门(客观判据,不是感觉)
+
+- 范围 ≤3 个文件 且 无跨模块搬迁 且 无文件增删 → **轻量道**
+- 其余 → **批量道**
+- **版本控制 = none → 禁入批量道**(批量改动无 git 回滚是裸奔):只许轻量道并输出强警告,或建议先 git init
+
+## 轻量道(五步,一次跑完)
+
+1. **重构**:只动结构不动行为;**禁止顺手修 bug**(与 N3"禁止顺手重构"互为镜像)——发现缺陷 → 停下记录现象与位置进档案,收口后走 `/cm-plugin:fix`。夹带修复会毁掉差分判官:行为变了,是重构失手还是修复生效?无法归因
+2. **等价验证**:基线全绿 + 差分逐项一致;**任何行为差异 = 该步失败回滚**——"差异其实更合理"也不例外,那是行为变更,走 prd --change 立项后再做
+3. **审查**:Codex 纪律同 N4(降级链/≤2 轮);**投喂**:全部 diff + RULEBOOK(批量道)+ 判官证据(judge-report/diff-report 摘要)——审查者没有等价证据,判「有无夹带」就只能凭感觉;重点:有无夹带行为变更、结构是否真的改善、差分覆盖够不够。凭证 tee 到 `{SPECS_DIR}/.reviews/refactor-{slug}-r{轮次}.md`,**无凭证不许进第 4 步**
+4. **落盘**:档案 `{SPECS_DIR}/refactors/{YYYYMMDD}-{slug}.md`(动机指标改前改后对照 / 等价验证方式与结果 / 发现未修缺陷清单);METRICS 行 Feature 列写 `refactor`;commit `refactor: {一句话} (档案: refactors/xxx.md)`
+5. **规则毕业**:本次收敛出的持久约定(如"路由文件导出形态")→ 写进代码项目 `.claude/rules/` 对应文件——一次重构的规则,变成项目的永久基因;**项目无 `.claude/rules/`(未经 /cm-plugin:init)→ 降级记入 LESSONS `[仅记忆]` 并在档案注明,提示补跑 /cm-plugin:init 后迁入**(实跑 DEV-003:diff-lens 未 init,毕业规则无处可去)
+
+## 批量道(五站 + 三条修上游回环)
+
+> 教义:个别失败交给循环烧掉,**重复失败控诉的是规则**——修规则重新生成,不修产物。
+
+### 站 1: 规则手册
+
+- 建 `{SPECS_DIR}/refactors/{slug}/RULEBOOK.md`,meta 规则:**两个 agent 会答得不同的问题,答案进手册**(目标形态/命名映射/禁用模式/逃生舱标记 `TODO(refactor):`)
+- 依赖图定批次顺序(文件粒度 + 模块粒度都查环)
+- **手册在循环内只读**:任何批内 diff 碰 RULEBOOK = 自动审查发现;修订排队给人,批间应用
+
+### 站 2: 压力测试(人门)
+
+- **双译对比(bakeoff)**:同 2-3 个最难的文件派两个隔离 agent——一个严格守 RULEBOOK,一个**从不知道手册存在**;第三个 agent 逐处 diff,每处差异裁决为「规则正确 / 规则缺失 / 规则错误」——差异清单就是规则修订清单(比"跑一遍看看"锐利:每个 diff 都是对某条规则的判决)
+- 试点:按批量道管线原样跑通(含站 3 禁令与站 4 裁决);**试点产物可弃,唯一留下的是规则修订**
+- 采样规模:批量 ≥10 单元 → 取 2-3 个最难文件;<10 单元 → 取 ⌈20%⌉ 且至少 1 个;偏离记偏差日志(实跑 DEV-001:5 单元取 1,规程数字对小批不成比例)
+- 🛑 规则定稿人签核后才扇出
+
+### 站 3: 批量执行
+
+- **队列 = 磁盘**:完成的客观定义是"该文件的重构产物存在且通过站 4"——可恢复、可并行、不靠记忆
+- **配置禁令**:开跑前验证代码项目 `.claude/settings.json` 已含 `~/.claude/templates/cm-plugin-refactor-denies.json` 的禁令(循环内禁 git 变更操作、禁重型测试命令——由人安装,本命令只验证,**未装不扇出**;禁令理由:能跑 git reset 的并行 agent 一次能毁掉全组的在途工作)
+- 扇出**复用既有工种 agent**(后端文件派 cm-plugin-backend-agent,前端派 cm-plugin-extension-agent……),派发指令附 RULEBOOK 摘录 + 该文件的差分输入集;agent 纪律(只做指定文件/不碰界外/不自行标记)原样生效
+- **分层用模型**:机械扇出的实现 agent 用低配模型(Agent 派发时指定 model 参数),审查与规则修订用高配——token 成本集中在循环里,分层是批量道成本结构的关键
+- 每个完成文件末尾带状态尾注 `// REFACTOR STATUS: confidence={high|medium|low} todos={N}`;审查者对账实际 `TODO(refactor)` 数,**尾注少报即为审查发现**
+- 提交在批次边界由主流程执行,循环 agent 不 commit
+
+### 站 3.5: 装配(主流程职责,不派 agent)
+
+- 按各单元 delta 清单执行**编排层改写**与**加载登记类波及物**(HTML script 注册 / 打包白名单 / 构建清单);agent 汇报的「需其他工种配合」在本站**强制逐条消费**,漏项即偏差记 DEV
+- 装配产物(编排层 + 登记文件)与模块产物**同等过站 4-5 判官链**——装配是全程唯一无规则手册护航的手写高危区(实跑:全程唯一真 bug 出自装配期,root 缺绑定,站 5 拦截)
+
+### 站 4: 机械裁决
+
+- **裁判有价格,价格决定位置**:typecheck/lint 便宜 → 进每文件循环;整体构建/重型测试贵 → 批末跑一次,错误清单按模块切片成下一批队列
+- **同类错误第 3 次出现 = 规则 bug**:停止修实例 → 修订 RULEBOOK(排队人批)→ **重新生成该批**,不手工补丁(手工补丁让第 500 个文件和第 5 个文件长得不一样)
+- **批间的一切规则驱动重生成/规范化变换视同新产物,必须重过站 4-5 判官链**——机械变换是上下文盲的(实跑:挂载行统一变换把 `root.` 写进无 root 绑定的 IIFE,启动即挂,站 5 金样前的 smoke 拦截)
+
+### 站 5: 行为等价
+
+- 判官上场:基线全量绿 + 差分全组一致;差异 = 回滚该批重做
+- 判官报异常先按 G0.5 自验证复查判官本身,再信判决
+
+### 收口(同轻量道 3-5 + 追加)
+
+- 审查凭证、档案(落 `refactors/{slug}/` 目录,与 RULEBOOK 同处)、METRICS、规则毕业照常
+- **偏差日志**:跳过的环节、放宽的检查,一行一条记入档案 `DEV-{序号} | 日期 | 跳过了什么 | 谁批准`——没人记录的偏差就是没人批准的偏差
+- **结构同步**:重构天然改变文件结构——按 cm-plugin-doc-syncer 口径同步项目 README / CLAUDE.md 的目录与模块描述(调用 skill,不动其命令文件);收口清单含**波及物核对**:批内全部「需配合事项」逐条销账(实跑失误:U1 汇报的 README 同步在收口被漏,靠事后审计才发现)
+
+## 收口人门(轻量道与批量道共用,全流程第三处签核)
+
+🛑 **双计数呈签核后本命令才算闭环**:基线 {N} 项全绿 + 差分 {M} 组一致,连同档案、动机指标改前改后对照、**预算对账**(G0 预估 vs 实耗:agent 调用次数/时长,写入 METRICS 备注)一并打给人——不对账的预算永远是拍脑袋。与 G0、站 2 构成全流程恰好三处人门——门在阶段之间,签核=踢下一阶段,阶段内零停车(与 `docs/重构流程设计/` 的图一致,图与实现不得漂移)。
+
+## 运行日志必记事件(node 写 `REFACTOR`,格式同 cm-plugin:ai 全局规则)
+
+- `node_enter`:进入每道门/每站(G0、G0.5、规模门、各站、收口)
+- `pause` / `resume`:**三处人门各一对**(G0 签核、站 2 规则定稿、收口 done-gate)——人门无 pause 记录 = 门没停,审计可查
+- `decision`:规则修订采纳(修了哪条/为什么)、轨道选择、判官修复
+- `task_start` / `task_done`:轻量道按次;批量道按**批次**记,detail 必带数字(完成 N/总数 M · 差分通过率 · 动机指标现值)——单文件粒度不灌主日志,进明细层 batch-log(见下节)
+- `error`:判官假阳性排查、批次重生成(记明"第几次重复触发规则修订")、行为差异回滚
+- `done`:收口(双计数写进 detail)
+
+## 重构专属明细日志(事件层之下的第二层,轻量道不豁免只减薄)
+
+> 为什么比 feature 开发厚:新开发的失败是"没做出来",看得见;重构的失败是"**悄悄改了行为**",事后归因全靠明细。事件级日志答得了"发生过什么",答不了"这个行为差异是哪个文件、哪版规则、哪次批次引入的"。
+
+- **judge-report.md**(`refactors/{slug}/`):判官档案——基线清单与结果、自验证变异清单(**种了什么变异 / 抓到没有**,漏抓的怎么修到抓到)、假阳性排查记录。判官的可信度证据,不是口头的"验证过了"
+- **diff-report.md**:差分明细——每组输入 / 改前输出 / 改后输出 / 结论,逐组落盘(不是一句"全部一致");出现差异时该组全文保留,回滚后补记处置
+- **batch-log.jsonl**(批量道):单文件粒度一行一条:`{file, agent, model, rulebook_rev, diff_pass, todos, confidence, duration}`——**归因链的关键是 `rulebook_rev`**:每个产物记录由哪版规则生成,行为差异出现时可精确定位"这批是坏规则的产物"而不是逐文件猜
+- **RULEBOOK 修订史**(手册内置表):`版本 | 日期 | 触发实例(哪个失败) | 旧条文 → 新条文 | 裁决人`——规则演进必须可追溯,否则"修规则不修产物"就成了无账本的改法
+- **回滚记录**:每次回滚在档案记一节(回滚了哪批 / 回到哪个 commit / 触发差异的输入组 / 归因结论),并与主日志 `error` 事件双写互指
+
+## 落盘物清单(审计链)
+
+| 落盘物 | 位置 |
+| ---- | ---- |
+| 运行日志 + 状态 | `{SPECS_DIR}/运行日志.jsonl` 追加 · `.cm-status.json`(状态条自动显示 REFACTOR 进度) |
+| 明细层(判官/差分/批次/回滚) | `refactors/{slug}/` 下 judge-report.md · diff-report.md · batch-log.jsonl(批量道) |
+| 可行性摘要 + 档案 | `{SPECS_DIR}/refactors/{日期}-{slug}.md`(批量道为同名目录) |
+| RULEBOOK(批量道) | `refactors/{slug}/RULEBOOK.md` |
+| 审查凭证 | `{SPECS_DIR}/.reviews/refactor-{slug}-r{N}.md` |
+| 度量 | METRICS.md 追加行,Feature 列 `refactor` |
+| 毕业规则 | 代码项目 `.claude/rules/` 对应文件 |
+| 备忘销账 | LESSONS.md 待触发备忘状态更新 |
+
+## 边界
+
+- **不承接**:缺陷(→ /cm-plugin:fix)、行为变更(→ /cm-plugin:prd --change)、架构级重设计(升级出口:交人经 /cm-plugin:prd 立项——重设计下规则手册变设计文档、试点对比失效,是另一种流程)
+- **不触发 cm-plugin-qa-engineer**:行为等价验证就是重构的 QA,行为没变就没有新 AC
+- 没有 specs 目录的裸项目:档案落代码项目 `docs/refactors/`,凭证落 `docs/refactors/.reviews/`,METRICS 跳过(同 /cm-plugin:fix 惯例)
+
+**对上游方法论的三处有意改编**(是取舍不是遗漏,放弃了什么留痕):
+
+- kit 的重设计模式(规则手册变设计文档)→ 整体分流给 `/cm-plugin:prd` 立项——cm 已有方案对抗审查链,不重复造
+- kit 的双对抗审查+第三方仲裁 → 用 cm 既有 N4 纪律(≤2 轮+分歧记录)——全框架审查纪律保持单一来源
+- kit 的缺口清单(gap inventory)→ 不设——那是跨语言迁移特有物(目标语言强制要求表),同语言行为保持重构由波及面清单承担残余职能

package/workflows/cm-plugin/commands/cm-plugin:rewrite.md

@@ -0,0 +1,90 @@
+# /cm-plugin:rewrite — 插件重写直通流水线
+
+`$ARGUMENTS` — 商店链接（必填）+ specs 目录 + 代码目录（可选，缺省时在链接同级新建 `{插件名}-rewrite-specs/` 与 `{插件名}-rewrite/`）+ `--yes`（透传给 R5 的 ai 入口闸）。
+
+**定位**：用户**已经决定重写**某个现存插件时的一键主流程——从链接进，到开发完成出。区别于单独的 `/cm-plugin:scout`（评估该不该做）：本命令里评估结论不设门，素材直接向下游流动。
+
+```text
+R0 环境预检 → R1 素材采集 → R1.5 验证边界声明 → R2 UI 原型(huashu-design) → R3 输出 PRD
+     → R4 拆 specs(/cm-plugin:prd) → R5 开发到底(/cm-plugin:ai N1→N8)
+                【卡点1: 设计方向】      【卡点2: 规格摘要卡】  【既有卡点: 形态确认/合规旗/运行观察】
+```
+
+全流程新增的人工卡点只有 1 个（R2 设计方向确认），其余全部复用下游命令的既有闸——不为直通牺牲任何安全卡点，也不重复设闸。
+
+## R0: 环境预检（先于 R1，一次性）
+
+跑 `~/.claude/templates/cm-plugin-scripts/cm-plugin-preflight.sh`——把扩展开发全链路的环境地雷提前引爆（Node/git/Codex/**Chrome for Testing**/系统 Chrome）。有阻塞项先解决：整条流水线到 R5 才用到的 E2E 加载扩展能力，如果现在不查，会在开发到一半时才撞上「系统 Chrome 屏蔽 --load-extension」（实测教训）。提示项不阻塞。
+
+## R1: 素材采集（scout 素材模式）
+
+执行 `/cm-plugin:scout {链接}` 的完整三维流程（Step 0 台账、日志、judgment 裁量全部照常），**仅一处不同**：
+
+- **verdict 不设门**——用户已决定重写，GO/WATCH/NO-GO 仅作为参考意见写进报告，流程不因结论停止
+- **例外（必须举旗一次）**：评估中发现**一票否决级事实**（核心功能依赖对方私有后端、领域需要资质、法律风险）→ 暂停陈述事实并等用户确认"知情，继续"——已决定 ≠ 不需要知道新发现的地雷。确认后继续，拒绝则终止
+- 产物落盘到 `{SPECS_DIR}/docs/`：scout 报告（槽点→需求映射表 + 功能盘点表 + 权限基线）+ `.log.jsonl` + 台账行（结论标注 `重写直通`）
+
+### R1.5: 验证边界声明（先于开发，一次性，防"最后才发现有道门只能人过"）
+
+在进 R2 前，把本次重写**哪些质量能在开发环境自动验证、哪些必须人在环**显式列成 `{SPECS_DIR}/docs/verification-boundary.md`，并在输出中告知用户。目的：把"我验不了、需要你做"的现实提到开工前说清，而不是拖到提审门槛才浮出来（实跑教训：ClearConsent 的"内置规则真站命中率需欧盟 IP 实测"直到提审前一刻才暴露，覆盖率门禁险些空过）。
+
+固定四问，逐条给出「能自动验 / 需人在环」判定 + 理由：
+
+1. **核心功能能否在本地/CI 复现验证？** 依赖真实第三方环境（特定地域、真实账号、真实设备、真实网站结构）的部分标记为「需人在环」，并写清需要什么条件（如"欧盟 IP"、"真机"、"付费账号"）。
+2. **UI/交付形态能否自动截图核验？** 能 → 归 N5 运行观察闸；不能（依赖真实上下文）→ 标人工。
+3. **有没有"上架/发布"这类只能人做的门？** 商店提审、真实覆盖率抽测、商标查重等——提前列为用户专属待办。
+4. **数据/合规验证靠什么？** 机器可验的进 check/QA，需人裁决的（法域、隐私披露真实性）标人工。
+
+这份声明是 R5 收尾时「发布待决清单」里"用户专属项"的来源——两处对齐，不重复也不遗漏。
+
+## R2: UI 原型（huashu-design，卡点 1）
+
+依据 R1 的**功能盘点表**（对方有什么）+ **槽点清单**（要改什么）+ **高分守护项**（不能丢什么），调用 `huashu-design` skill 生成高保真原型：
+
+- 覆盖对方全部核心表面（popup/options/side panel/content script 注入 UI，以功能盘点为准），**槽点对应的改进点必须在原型中可见**（如"无可见性"槽点 → 原型里就要有透明度面板）
+- 要求包含 hover/空态/错误态交互态（prd 设计基准的既有要求）
+- **清白室红线延伸到设计**：原型是按需求重新设计，禁止照抄对方界面布局与视觉（功能同类 ≠ 界面像素级复刻，抄界面同样构成 impersonation 风险）
+- 落盘 `{SPECS_DIR}/docs/design-baseline/`
+- **卡点 1：把原型截图/预览地址发给用户确认设计方向**——"方向对吗？要调什么？"确认后才进 R3（原型返工成本远低于代码返工）
+
+`huashu-design` 未安装 → 提示 `npx skills add alchaincyf/huashu-design`；用户不装 → 跳过 R2，R4 走 prd 的"无设计稿"分支（UI 由扩展工程师按 design.md 自行实现），显式告知这一降级
+
+## R3: 输出 PRD
+
+把 R1 素材 + R2 已确认原型转写成标准 PRD，落盘 `{SPECS_DIR}/docs/prd.md`，固定骨架：
+
+```markdown
+# {新插件名} PRD（重写自 {对方名}）
+## 背景与机会          ← R1 评分卡摘要 + 对方现状
+## 目标用户与守护项    ← 高分评论定位的核心体验，逐条列为"不可回退项"
+## 功能清单            ← R1 功能盘点表 × 三态标记: [保留]/[改进(对应槽点#N)]/[舍弃(理由)]
+## 槽点→需求映射       ← R1 原表直入，每条痛点对应一个功能需求或非功能需求
+## 权限基线            ← 必须 ⊆ 对方合理权限；每项带用途理由（商店提审直接复用）
+## 设计基准            ← design-baseline/ 索引 + 与功能清单的页面对应关系
+## 非功能需求          ← 商店合规（单一用途表述）、性能、数据迁移（如需导入对方导出格式）
+```
+
+**R3 机械自检（写完即验，不过不进 R4）**——素材转写的风险是「丢件」，全部可机械对账：① R1 功能盘点表的每一行在功能清单中有三态标记（保留/改进/舍弃），零遗漏；② 槽点清单每条在「槽点→需求映射」有对应行；③ 权限基线 ⊆ 对方 manifest 权限集（逐项比对）；④ design-baseline 索引的文件真实存在。核对结果一行附在 PRD 末尾（`自检: 4/4 通过` / 缺项清单），缺项修完再过。能机械验的绝不靠嘴（init 3.5 同款基因）。
+
+PRD 写完输出一屏摘要，不设独立卡点（设计已在 R2 确认，规格审查在 R4——两头有闸，中间不重复停车）。
+
+## R4: 拆 specs（/cm-plugin:prd，卡点 2）
+
+执行 `/cm-plugin:prd {SPECS_DIR}`：prd.md + scout 报告就是需求文档，design-baseline 已就位——
+
+- 设计基准三档定级由 prd 既有流程询问（重写场景默认建议**结构级**：布局/层级/文案对照验收，色值间距不逐像素）
+- 空代码目录 → 自动走 0→1 分支，选型对着 R1 功能盘点推导（表面组合已知，脚手架 2-3 套供拍板）
+- **卡点 2：规格摘要卡人审**（prd 既有闸，权限清单是重写场景的审查重点）
+
+## R5: 开发到底（/cm-plugin:ai）
+
+规格获批后执行 `/cm-plugin:ai {SPECS_DIR} {代码目录}`（`--yes` 按入参透传）：
+
+- N1→N8 完整状态机，bootstrap 最优先、形态确认卡点（真实浏览器加载截图）、商店合规举旗、Codex 复审、METRICS/LESSONS 全部照常
+- 数据迁移 feature（若 PRD 含"导入对方导出格式"）建议排在首个业务 feature——对方用户迁移过来的第一体验就是"我的数据能带过来"
+- 终点 = N8 输出总结 + **发布待决清单**（版本/权限 diff/商店材料就绪度），商店提审仍由人确认触发（devops 硬闸不变）
+
+## 断点与状态
+
+- 各阶段完成即在会话输出一行 `📍 R{N} 完成 → R{N+1}`；R4 起状态可视化走 ai 的 `.cm-status.json` 既有机制
+- 中断后重跑本命令：检测 `{SPECS_DIR}/docs/` 下已有产物（scout 报告→跳过 R1；design-baseline 且已确认→跳过 R2；prd.md→跳过 R3；specs 三件套→直接 R5 断点续跑）——幂等续跑，不重复劳动