@aibyzero/byz 0.1.1 → 0.1.3

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 断点续跑）——幂等续跑，不重复劳动

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

@@ -0,0 +1,202 @@
+# /cm-plugin:scout — 竞品插件重写机会评估
+
+`$ARGUMENTS` — Chrome Web Store 插件链接（或插件名，先搜到链接再执行）；可选 `--rewrite`（素材模式：由 /cm-plugin:rewrite 流水线调用或用户已决定重写时使用——三维流程、日志、裁量全部照常，但 verdict 仅作参考不设门，一票否决级事实仍须举旗知情；台账结论标注 `重写直通`）；可选 `--bakeoff`（多候选对抗模式，见下）。
+
+流程最上游的选品环节：判断一个现存插件**值不值得重写**。产出机会评分卡 + 槽点→需求映射表；结论为 GO 时衔接 `/cm-plugin:idea`（需访谈补全）或直接 `/cm-plugin:prd`。
+
+## 两种模式（按 $ARGUMENTS 分派）
+
+- **模式 A · 单靶三维评估（默认）**：$ARGUMENTS 是具体扩展链接/名 → 直接走 Step 0-4。
+- **模式 B · 多候选对抗比对（`--bakeoff`，或 $ARGUMENTS 为空/只给方向提示如"找个弃养的开发者工具"）**：还没定靶时用——先走下方「候选对抗比对」凑齐多候选、交 Codex 证否式对抗，逼出**一个确定靶**（或"继续搜"），选出的靶再对它走 Step 0-4。**dogfood 教训**：单点押注会把 WATCH 级机会因"想开工"美化成 GO，多候选 + Codex 对抗是唯一挡板（实跑：一次单靶 scout 判 WATCH 后差点被推去开发，加对抗才拦住，且 Codex 独立点出"把单根因多症状重复计数凑 GO"的偏差）。
+
+## 候选对抗比对（模式 B）
+
+### B1 候选发现（≥2，建议 3-5）
+
+按判据搜候选，每个只做**轻量核验**（商店页基础信息 + 快扫评论 + 停更信号），**不跑完整三维**——三维留给对抗选出的赢家。判据（好靶要正面命中，缺项即降权）：
+
+| # | 判据 | 为什么 |
+| - | ---- | ---- |
+| 1 | 纯客户端，核心价值不绑对方后端 | 云存/账号同步/服务端解析类=数据必经其服务器，本地重写会丢差异化 |
+| 2 | 现任已弃养或劣化 | >6 月无更新，或被收购后加广告/权限膨胀/强制付费墙 |
+| 3 | **空档没被干净活跃替代填满**（最难最关键） | 必须实查赛道现在谁占位、是否活跃且干净；已有 1-2 个活跃开源清洁替代=红海，降权 |
+| 4 | 有 ≥2 个**独立根因**的高频结构槽点，纯客户端 MV3 可修 | 同一根因的多症状只算 1 类（防重复计数凑 GO） |
+| 5 | 用户基数千级以上 | 需求已验证 |
+
+**排除红海/死区**（直接不入池）：新标签页、JSON viewer、截图、广告拦截（MV3 死区）、下载器/去 paywall（法务）、密码管理（安全敏感）。台账（SCOUTS.md）已评过的目标不重复入池。
+
+### B2 候选档案落盘
+
+每候选一段写入 `bakeoff-candidates-{YYYYMMDD}.md`：基数/评分、停更、**槽点按根因聚类**（每类标证据：评论原文/issue，注明有几个独立簇）、空档评估（谁占位·活跃否·干净否）、后端依赖检查、数据置信度（高=CWS 实测 / 中=聚合站或检索）。**纪律**：根因聚类不按用户表述——症状不同但同根因（如挂起器的"标签组丢失/重启丢失/定时恢复失败"同属持久化设计）只计 1 类。
+
+### B3 Codex 对抗比对（强制，证否式）
+
+候选档案交 Codex，立场**证否**（默认每个都不值得重写，除非证据压倒）。提示词要义：逐个 steelman-against（尤其攻击：核心价值是否绑后端 / 空档是否已被干净替代填满 / 现任是否活跃到你修的槽点他下版就修 / 赛道是否红海到差异化稀薄）→ 排名 → 定唯一结论（哪个最该推进，**或明确"全部不达 GO 线，继续搜"**）+ 每个候选离 GO 还差哪个关键证据。凭证 tee 到 `bakeoff-{YYYYMMDD}-verdict.md`，记一行 `bakeoff` 事件（detail 注明 Codex 结论）。Codex 未装走 N4 三级降级链。依据同 Step 3 的 GO 对抗：选品是全流水线最贵决策，人审素材全出自同一模型，须异源把关。
+
+**提名人偏差自查清单（每轮对抗必附给 Codex，也自查）**：① 把"可修 bug"当"市场空档"（可修 ≠ 用户会迁移）② 把一个根因的多症状重复计数成多类 ③ 死亡产品偏差（醒目的尸体周围常已长出成熟替代）④ 用户基数错置（大基数先证现任分发/品牌优势，不证新品可获取市场）⑤ 隐私偏好投射（"权限更干净/纯离线"是工程师易高估的价值）⑥ 低估现任反应速度、夸大实现、低估获客。
+
+### B4 输出与衔接
+
+- **选出一个靶** → 对它走 Step 0-4 完整三维；三维再 GO 才进 /cm-plugin:rewrite 或 /cm-plugin:prd。
+- **全部不达标** → "继续搜"是**合法结论，不硬凑**（把无 GO 坦然写进台账，扩大搜寻再来一轮）。
+- 对抗记录落盘 `bakeoff-{YYYYMMDD}.md`（排名 + Codex 结论 + 偏差自查），与候选档案、台账同目录。
+
+## 工具前提
+
+- **商店页的主通道是 WebFetch，不是浏览器自动化**——Chrome 禁止扩展脚本化 Web Store（报错 "The extensions gallery cannot be scripted"），claude-in-chrome 在商店页连截图都会被拦（实跑教训：OneTab 试跑首次导航即撞墙）。商店主页 + `/reviews` 子页分别 WebFetch
+- **评论通道上限**：WebFetch 的 `/reviews` 页只能拿到最新一屏（约 10 条，无法翻页/按低分排序）——这是已知系统性限制，按维度一的"快扫/深扫"分级处理，不重复记 degrade（实跑教训：两次试跑同一条采样不足 degrade 连发，纯噪音）。评分卡永远标注实际采样量与扫级
+- 维度三的 CRX 获取用更新服务直链（无需安装）：
+
+```bash
+curl -sL -o ext.crx "https://clients2.google.com/service/update2/crx?response=redirect&prodversion=138.0.0.0&acceptformat=crx2,crx3&x=id%3D{扩展ID}%26uc"
+python3 -c "d=open('ext.crx','rb').read(); open('ext.zip','wb').write(d[d.find(b'PK\x03\x04'):])"   # 剥 CRX3 头
+unzip -q ext.zip -d unpacked
+```
+
+## Step 0: 读选品台账（有台账先读，没有首跑自建）
+
+报告目录下的 `SCOUTS.md` 是跨次运行的选品台账。启动时先读：
+
+- **目标已在台账** → 输出上次结论与日期，问用户"重评还是查看旧报告"——防重复评估浪费
+- **台账有到期的 WATCH 项**（复查到期日 ≤ 今天）→ 在本次输出开头列出提醒，无论本次目标是谁
+- 台账不存在 → 本次结束时创建
+
+台账格式（一行一目标，结束时追加/更新）：
+
+```markdown
+| 日期 | 目标(ID) | 结论 | 复查到期 | 触发条件摘要 | 报告 |
+| 2026-07-18 | OneTab | WATCH | 2026-10-18 | 云同步跳票/再停更>6月/转收费墙 | scout-OneTab-20260718.md |
+```
+
+> WATCH 的语义是"持续观察"，但 scout 是一次性命令——台账就是把观察窗落到纸面的机制（实跑教训：首批试跑 OneTab 判 WATCH+3 个月窗口后，该信息只躺在报告里，无任何机制促成复查）。
+
+## Step 1: 基础信息采集（商店页首屏）
+
+打开商店页，采集并落表：
+
+| 字段 | 用途 |
+| ---- | ---- |
+| 名称 / 开发者 | 识别 |
+| 用户数 | 市场验证信号——**这是最值钱的数据**：大基数=需求已被验证，省掉冷启动赌注 |
+| 评分 + 评分分布 | 总分高但 1 星占比高 = 典型的"老用户失望"形态 |
+| 最近更新时间 | 维度二输入 |
+| 权限清单 | 商店页通常不展示完整权限——**以维度三解包出的 manifest 为准**（实跑教训：OneTab 商店页无权限列表） |
+| 价格/内购 | 商业模式参考 |
+
+## Step 2: 三维评估
+
+### 维度一：槽点挖掘（评论区 = 免费的需求文档）
+
+1. 采样分两级（评分卡必须标注本次用的哪级）：
+   - **快扫（默认）**：WebFetch `/reviews` 页可见评论（约 10 条，通道硬上限，不算降级不记 degrade）——足够支撑 WATCH/NO-GO 方向判断
+   - **深扫（GO 候选必做）**：快扫结论倾向 GO 时，输出评分卡后**必须**附标准补样请求并记 `sample_request` 事件："请打开评论区 → 排序选最新 → 筛 1-3 星 → 翻 3-5 页，把内容粘贴给我，我补聚类后更新报告与结论"——GO 是要花真金白银开发的，不允许建立在 10 条采样上
+2. 高分评论也扫一遍——用户夸什么就是**不能丢的核心体验**（重写砸了核心功能等于白做）
+3. 聚类成槽点清单，每类记：
+
+```markdown
+| # | 槽点 | 频次 | 严重度 | 原文引用(1-2条) | 转化为需求 |
+| 1 | 更新后收费墙锁了导出 | 12 | 高 | "..." | 导出功能免费 |
+```
+
+**纪律**：频次≥3 的槽点才进清单主体（孤例进附录）；「转化为需求」列用需求语言写（做什么），不写情绪语言（他们多烂）。
+
+### 维度二：停更信号
+
+按最近更新距今分层（阈值可被用户参数覆盖）：
+
+- **< 1 个月 → 🔴 竞品活跃**——对方还在迭代，你修的槽点他下版可能就修了；单靠此维度不给机会分
+- **1-6 个月 → 🟡 疑似放缓**——结合评论区"开发者是否回复"判断（长期不回复差评 = 放缓实锤）
+- **> 6 个月 → 🟢 大概率弃养**——机会信号最强；顺手查开发者其他插件是否同样停更（整体跑路 vs 单品放弃）
+
+### 维度三：功能盘点（源码分析）
+
+1. 获取解包源码：已安装则取 Chrome 扩展目录；未安装用 CRX 下载解包（如 CRX Viewer）
+2. 盘点并落表：manifest 版本与**权限清单**（对照实际功能，标出冗余权限——这是我们"权限更干净"的卖点）、表面组合（popup/side panel/content script/…）、功能清单（每个功能一行：入口/行为/依赖的 API）、技术栈线索（框架/构建工具/是否有后端调用）、明显的实现短板（如轮询代 alarms、全局 content script 注入）
+3. 估算重写成本：功能清单 × 我们的任务粒度 ≈ feature 数与预估工时
+
+**清白室红线（不可违反）**：源码只用于产出**功能与交互的文字盘点**。禁止复制任何代码、素材、文案、图标、品牌元素进新项目；盘点表里不粘贴源码片段（描述行为，不摘抄实现）。重写 = 按槽点清单重新实现，抄袭既是侵权也过不了商店 impersonation 审查（Red Copper）。
+
+## Step 3: 机会评分卡（输出主体）
+
+**GO 对抗确认（结论为 GO/GO 附条件时强制；WATCH/NO-GO 跳过——错误成本不对称，错误的 GO 烧几十小时开发，错误的 WATCH 只错过机会）**：日志自检通过后、出评分卡前，把评分卡草稿 + 5 条 judgment + 关键证据（槽点原文/停更数据/竞品数据）交 Codex，提示词要义："**假设这个 GO 是错的，找出被忽略的否决因素**——竞品是否被低估？槽点是否真的可修？维护成本是否被轻描淡写？"（句式同 cm-plugin:fix 2.5）。**仅 1 轮**：推翻 → 回对应维度补证；分歧 → 写入评分卡「风险点」交人裁决；通过 → 出卡。凭证 tee 到报告同目录 `scout-{插件名}-verdict-r1.md`，记一行 `judgment`（aspect=`verdict-weight`，detail 注明 Codex 结论）。Codex 未装走 N4 三级降级链。依据：选品 GO 是全流水线最贵的单一决策，此前唯一把关是人拍板，而人审素材全部出自同一模型——与 prd 9.5 补齐前的方案盲区同构。
+
+**出结论前的日志自检卡点**（对齐 N5 凭证对账思路）：回读本次 `.log.jsonl`，确认 ① `dimension_done` ≥3（D1/D2/D3 各一）且 `fetch` ≥1；② `judgment` 覆盖全部 5 个 aspect（cluster/severity/structural/competitor/verdict-weight）——缺维度说明没真跑，缺裁量说明判断没留痕，**任一不齐不得出 verdict**，先补齐（理论上漏跑一个维度、跳过全部裁量记录也能写出通顺的结论，唯一防线是这次对账）。自检结果记一行 `decision` 事件。
+
+```text
+┌─ 🔭 重写机会评分卡 — {插件名} ──────────────
+│ 用户基数: {N}（{万级+/千级/百级}） · 评分 {X}({分布})
+│ 维度一 槽点: {N} 类 {N} 条低分评论（Top3: …）
+│ 维度二 停更: {🔴/🟡/🟢} 最近更新 {日期}（距今 {N} 天）
+│ 维度三 盘点: {N} 个功能 / 权限 {N} 项(冗余 {N}) / 预估 {N} feature ≈ {X}h
+│ 竞争密度: {同类插件中活跃的有几个,是否已有人在做"修好版"}
+│ 结论: GO / WATCH（缺什么信号） / NO-GO（一票否决项）
+│ 一票否决检查: 核心价值依赖对方后端? 领域需要资质? 槽点全是没法修的(如网站改版)?
+└─────────────────────────────────────────────
+```
+
+判定基准（AI 给建议，**人拍板**）：
+
+- **GO**：用户基数千级以上 + 高频槽点 ≥3 类可修 + 停更 🟡/🟢
+- **WATCH**：信号不齐（如竞品活跃但槽点结构性——收费墙类对方不会自己拆）
+- **NO-GO**：任一一票否决项命中
+
+## 运行日志（与 /cm-plugin:ai 同规格，贯穿全程）
+
+每个步骤执行时**同步追加**（不覆盖）事件到报告同目录的 `scout-{插件名}-{YYYYMMDD}.log.jsonl`，一行一个 JSON；`at` 一律 ISO 8601 带时区偏移（`date +%Y-%m-%dT%H:%M:%S%z`）。
+
+**写入纪律（两条都是实跑抓出的失守）**：
+
+- **每事件在其步骤完成后立即单独追加，禁止攒批**——攒到一个 bash 里补记会让 5 条事件挤进同一秒，时间线失真、耗时分析报废（实跑教训：两次试跑各有 2-3 组同秒批量，真实的几十秒间隔在日志里消失）
+- **事件只记已发生的事实**——`report_saved` 必须在报告文件写盘**之后**记录，记录时核验文件存在并把字节数写进 `n`（实跑教训：两次试跑 report_saved 均早于实际落盘 28-38 秒，日志预支了还没发生的事）
+
+**结构化字段**（自由文本 detail 无法机器聚合，跨运行统计要靠这几个可选字段）：`dim`（D1/D2/D3，维度类事件必带）、`channel`（webfetch/browser/manual/crx，获取类事件必带）、`n`（数量值：采样条数/文件字节数/文件数等）、`aspect`（judgment 事件必带，取值见主观裁量节）。示例：
+
+```json
+{"at":"2026-07-18T10:09:32+0800","event":"fetch","channel":"webfetch","dim":"D1","n":10,"detail":"reviews 页成功: 1-2星 9 条"}
+```
+
+**必记事件（event 取值固定）**：
+
+- `scout_start`：目标 URL、扩展 ID、参数（如自定义停更阈值）
+- `fetch`：每次页面获取——通道（webfetch/browser/人工粘贴）、目标页（store/reviews）、结果（成功/失败原文）
+- `degrade`：任何降级——浏览器被拦（CWS 禁脚本化）、评论采样不足（记实际条数）、CRX 下载失败等，**detail 记失败原文**
+- `dimension_done`：D1/D2/D3 各维度完成时记一行结论摘要（如 `D2: 🔴 距今13天`）
+- `crx`：CRX 下载与解包结果（文件大小、zip offset、文件数）+ **版本核对**：解包 manifest 的 version 必须与商店页版本一致，不一致记入 detail（防更新服务回旧版，维度三盘的就不是现行版本）
+- `sample_request`：向用户发出人工补样请求（深扫路径）
+- `decision`：过程中的流程性取舍（如快扫出结论的理由、通道选择）
+- `judgment`：**主观裁量事件**（与 decision 的区别：decision 记"流程怎么走"，judgment 记"判断怎么下"），格式与固定裁量点见下节
+- `bakeoff`：模式 B 的 Codex 对抗比对结论（候选数、排名、选出的靶或"继续搜"、凭证路径）
+- `verdict`：最终结论（GO/WATCH/NO-GO）+ 一句话理由 + 一票否决检查结果 + **flip 条件**（什么情况下本结论会翻转）
+- `report_saved`：报告落盘路径（写盘后记录，`n`=文件字节数）
+
+### 主观裁量的日志纪律（judgment 事件）
+
+事实类事件（fetch/crx）谁跑都一样，**主观裁量才是 scout 结论的真正来源，也是最需要被审计的部分**——摘要式日志只能让人质疑结论，裁量级日志才能让人在具体判断点上反驳。以下 5 个固定裁量点**每个至少记一条 judgment**，多次裁量多条：
+
+| # | aspect 取值 | 记什么 |
+| --- | ---- | ---- |
+| 1 | `cluster` | 槽点聚类归属——**边界评论必记**：某条评论既可归 A 类也可归 B 类时，归了哪类、为什么；无边界情况则记"聚类无争议"一条 |
+| 2 | `severity` | 每类槽点的严重度定级依据——判"高"的标准（影响核心功能 / 涉信任或数据安全 / 用户明确流失）命中了哪条，为什么不是"中" |
+| 3 | `structural` | **结构性/非结构性判定**（对结论影响最大的一次裁量）：这个槽点现任能不能自己修？判定依据 + 反例检验（"如果 X 发生就说明我判错了"） |
+| 4 | `competitor` | 竞品对比权衡：占位者的强弱怎么比的（用户量/活跃度/是否覆盖同一批槽点逐项对比），为什么判"窗口仍在/已关"| 
+| 5 | `verdict-weight` | 三因子权衡：基数/槽点/停更各自往哪个方向拉、哪个因子起了决定作用、离翻转结论差多远 |
+
+**每条 judgment 的 detail 必含四段**（写不出弃选项 = 没做对比，重想）：`采纳: … / 依据: {指向具体证据,如"评论 2026-02-12 原文"} / 弃选: {另一种判法及不采纳的理由} / flip: {什么新证据会翻转本裁量}`。示例：
+
+```json
+{"at":"…","event":"judgment","aspect":"structural","dim":"D1","detail":"采纳: Avast信任崩塌=结构性 / 依据: 槽点主体是开发商身份而非功能,2026-02两条差评点名卖数据 / 弃选: 判非结构性(理由:若GEN剥离品牌可自愈)——弃因剥离无迹象且收购已4年 / flip: GEN宣布出售该产品线或独立开源"}
+```
+
+**写入优先用日志助手**：`~/.claude/templates/cm-plugin-scripts/cm-plugin-log.sh <日志文件> <event> <detail> [k=v ...]`——自动 ISO8601 时间戳、原子追加、JSON 转义（中文/引号/换行都安全）。实测教训：手写 `echo '{...}' >> log` 犯过「先记账后落盘」「攒批挤同秒」两类错，助手从机制上杜绝。
+
+写日志与执行同时机同成本，不得跳过、不得事后补写。**反馈 scout 质量问题时把这份日志连报告一起带回**——事实事件回答"数据是什么"，judgment 事件回答"判断怎么下的"，两层齐了才构成完整凭证（实跑教训：首次 OneTab 试跑无日志全靠记忆还原；前两轮虽有日志，但"结构性判定"这个决定 GO/WATCH 分野的关键裁量被压缩在 dimension_done 一句话里，人无法在判断点上反驳）。
+
+## Step 4: 落盘与衔接
+
+结论无论 GO 与否都落盘 `scout-{插件名}-{YYYYMMDD}.md`（含评分卡 + 三张表 + 原文引用），位置：用户指定目录，未指定放当前目录；`.log.jsonl` 同目录。**随后更新 `SCOUTS.md` 台账**（Step 0 的格式；WATCH 项必须填复查到期日），最后记 `report_saved` 事件收尾。
+
+**GO 后的衔接（人确认后执行）**：
+
+- 需求还需访谈补全 → `/cm-plugin:idea`，把 scout 报告作为访谈输入
+- 槽点清单已够成型 → 建 specs 文件夹，scout 报告放入 `docs/`，直接 `/cm-plugin:prd {specs路径}`——槽点→需求映射表就是需求文档主体，「高分评论=不能丢的核心体验」进非功能需求
+- 权限清单进 prd 的权限基线：**我们的 manifest 必须 ⊆ 对方合理权限**（"更干净的权限"写进商店 listing 卖点）