@aibyzero/byz 0.0.0 → 0.1.2

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 卖点）

package/workflows/cm-plugin/docs//346/265/213/350/257/225/346/214/207/345/274/225-/345/277/253/351/200/237/344/270/212/346/211/213.md

@@ -0,0 +1,189 @@
+# cm-plugin 工作流(Chrome 插件版) · 使用与配置手册(v0.4.2)
+
+> 对着本手册从上往下做即可。遇到问题,先跑 `/cm-plugin:check` 看首行版本号,反馈问题时带上它。
+
+---
+
+# 第一部分:配置手册(装好约 20 分钟,只做一次)
+
+## 0. 前置要求
+
+| 依赖 | 要求 | 用途 |
+| ---- | ---- | ---- |
+| Claude Code | 最新版 | 主引擎 |
+| Node.js | >=18 | Codex CLI / 脚手架 |
+| git | 任意新版 | 审计链(每任务一提交) |
+| python3 | 3.8+(可选) | 状态条/像素可视化 |
+
+**Windows 用户**:核心工作流(commands/skills/agents)是纯 Markdown,原生可用;状态条和终端像素版是 bash+python3 脚本,请在 **Git Bash 或 WSL** 里用(Claude Code 终端选 Git Bash 即可)。
+
+## 1. 清理旧版(装过旧包的机器必做,全新机器跳过)
+
+```bash
+rm -rf ~/.claude/commands/cm-plugin:* ~/.claude/commands/cm-plugin-ai-nodes ~/.claude/commands/cm-plugin-prd-modes \
+       ~/.claude/skills/cm-plugin-* \
+       ~/.claude/agents/cm-plugin-* ~/.claude/templates/cm-plugin-*
+```
+
+只删 cm-plugin 家族——上游 cm-workflow 的安装物(cm:*、cm-*)和你的其他 skill 一律不碰。
+
+## 2. 安装
+
+```bash
+git clone git@github.com:kingxiaozhe/cm-plugin-workflow.git
+cd cm-plugin-workflow
+bash install.sh          # macOS/Linux/Git Bash
+```
+
+```powershell
+powershell -ExecutionPolicy Bypass -File install.ps1   # Windows 原生
+```
+
+装完看最后一行:**"完成(已安装版本: v0.4.2)"**——显示别的号就说明装的不是最新版。
+
+## 3. Codex 主通道(代码审查的第二个模型,强烈建议装)
+
+```bash
+npm i -g @openai/codex
+codex login                # 用 ChatGPT 账号登录(Plus 订阅即可,审查用量很小)
+codex "hi"                 # ★关键一步:测公司网络能否连通 OpenAI
+```
+
+- `codex "hi"` 有正常回复 → 通,完成
+- 卡住/报错 → 公司网络对 OpenAI 出口有限制,**先解决网络**(找 IT 或配代理)
+- 实在装不了 → 工作流照常能跑:审查自动降级为对抗式子代理(质量次优),且开跑前会明确告知你、要你点头才继续——不会静默降级
+
+## 4. 状态条(可选,推荐)
+
+在 `~/.claude/settings.json` 里加:
+
+```json
+"statusLine": {"type": "command", "command": "~/.claude/templates/cm-plugin-statusline.sh"}
+```
+
+效果:Claude Code 底部实时显示 `🔨 开发中 market-board · 正在开发数据接口(进度 2/6)`;等你确认时整条变黄。
+
+## 5. 像素流水线(可选,纯娱乐+演示)
+
+```bash
+~/.claude/templates/cm-plugin-pixel/cm-pixel.sh --demo        # 终端版演示,Ctrl-C 退出
+~/.claude/templates/cm-plugin-pixel/serve.sh {specs路径}      # 浏览器版;地址后加 ?demo 看演示
+```
+
+## 6. 安装自检(必做)
+
+在 Claude Code 里运行:
+
+```text
+/cm-plugin:check
+```
+
+**期待结果**:首行显示 `安装版本: v0.4.2`,版本一致性行显示"一致",结论 PASSED。
+
+| 自检红项 | 处理 |
+| ---- | ---- |
+| 版本不一致 / 未知 | 混装或旧包,回到第 1 步清理重装 |
+| Codex 降级 | 回到第 3 步;或接受降级继续 |
+| 状态条未配 | 可选项,不影响运行 |
+
+---
+
+# 第二部分:使用手册
+
+## 全景:你在整个流程里只做 4 件事
+
+```text
+放需求 → 审规格(一张摘要卡) → 回答暂停点(很少) → 收数据
+其余全部自动:拆解/开发/双模型审查/测试/提交/文档同步
+```
+
+## 场景 A:全新项目(从零开始)
+
+```bash
+mkdir -p my-app-specs/docs
+# 把需求文档放进 docs/(md/txt/pdf/可交互 html 都行;一句话需求写个 txt 也行)
+```
+
+Claude Code 中:
+
+```text
+/cm-plugin:prd my-app-specs
+```
+
+会发生什么(按顺序):
+
+1. **问交付形态**(Web/App/小程序…)——这是最重要的一问,想清楚再答
+2. 联网核实架构 → 给 2-3 套方案(团队首选 better-t-stack 优先)→ **你做选择题**
+3. 大方案自动过第二模型对抗审查(Step 9.5)
+4. 生成规格三件套 + 自动机器自检(Step 10.5)
+5. 输出**规格摘要卡**——一屏看完:形态/功能点/AC/开放问题/风险点/自检结果。**这是你最重要的审查时刻**,有疑问点开对应文件细看
+
+确认无误后:
+
+```text
+/cm-plugin:ai specs在my-app-specs,代码在my-app
+```
+
+之后基本不用管。**唯一必到场的卡点**:骨架搭完后它会发首屏截图问"这个形态对吗?"——看一眼回一句。
+
+## 场景 B:老项目二开(存量项目加功能/改功能)
+
+```bash
+cd 你的项目根目录
+```
+
+```text
+/cm-plugin:init          # 自动分析项目、生成规范;>30 个源文件会自动生成"业务地图"(全项目逻辑文档)
+/cm-plugin:prd {specs路径}
+/cm-plugin:ai ...
+```
+
+二开时工作流会自动多做这些(不用你操心):按业务地图拆分 feature、给要改的老模块画**波及面**、先跑**防护网**(有测试资产就先全量跑一遍锁基线)、开发时禁止顺手重构、QA 按波及面回归老功能、收尾把改动回写业务地图。
+
+⚠ 多项目混装的仓库:scan 会让你选定扫哪个子项目,**别在仓库根上扫**。
+
+## 场景 C:需求变更(做到一半需求改了)
+
+```text
+/cm-plugin:prd --change 2.feature-name 变更内容描述
+```
+
+已完成的工作不推翻,任务清单增量更新([NEW]/[CHANGED]/[DROPPED]),重跑自动跳过已完成项。
+
+## 运行中你会看到什么
+
+| 现象 | 含义 | 你要做什么 |
+| ---- | ---- | ---- |
+| 状态条绿色滚动 | 正常干活 | 不用管 |
+| 状态条变黄 🖐 | 灾难级问题等你拍板(删数据/合规/形态错向) | 回 Claude Code 回一句 |
+| 状态条 ⚠ 可能已中断 | 超 10 分钟没动静 | 去会话看一眼,必要时重跑 /cm-plugin:ai(断点续跑,不会重做) |
+| 内置任务清单在勾选 | 任务进度镜像 | 看着爽 |
+| 🔁 回读行 | 每任务完成的强制自证 | 缺这行=任务没真完成 |
+
+**暂停很少**:技术选型、实现路径、审查分歧都是 AI 自己决策并留痕的;它停下来问你的,一定是真需要你的事。
+
+## 收尾必做 3 件事(这次测试的核心目的)
+
+1. **跑 `/cost`**,把费用数字回填到 N8 提示的成本行——这是"单任务成本<人工工时"门槛的唯一数据源,**这次测试最重要的一个数字**
+2. 看一眼 `度量汇总.md`(N8 自动生成):任务数/介入次数/一次通过率/拦截数
+**三道执行闸(继承自上游实跑失守修复)**:①prd 生成完会硬停车,开发必须由你运行 /cm-plugin:ai 启动,N1 会先出摘要卡等你回"开始"(嫌烦加 --yes);②每轮 Codex 审查的原始输出自动存进 specs/.reviews/,没凭证任务标记不了,收尾还会对账;③反馈时把 .reviews/ 一起带回,我能看到每轮审查真实说了什么。
+
+**从零想法开新项目**:只有一句话点子时,先跑 `/cm-plugin:idea 你的点子`(或直接说"我有个点子…")(产品访谈搭档,一次一题帮你聊成成熟 PRD,交易/web3 项目自动加载领域包),聊出的 PRD 存进 docs/ 再走 /cm-plugin:prd。已有需求文档则直接 /cm-plugin:prd,两者互不影响。
+
+**修 bug 用 `/cm-plugin:fix`**：`/cm-plugin:fix {specs路径} {代码路径} 现象描述`——不走全流程,七步小闭环:复现→定位根因→先写失败测试→最小修复→Codex 审查→波及面回归→缺陷档案落盘(specs/fixes/)。修不动的大问题它会建议转 /cm-plugin:prd --change 立项,不会硬改。
+
+3. **带回来给我**:`METRICS.md` + `LESSONS.md` + **`运行日志.jsonl`**(自动记录:节点切换/审查轮次/暂停原因/自主决策,一行一事件) + 你的体感(哪一步最烦人/哪次暂停不该停)——这是下一版升级的全部依据
+
+## 常见问题速查
+
+| 症状 | 原因 → 处理 |
+| ---- | ---- |
+| 某功能"不存在" | 九成是旧包 → `/cm-plugin:check` 看版本 → 重装 |
+| 像素版没画面 | 先跑 `--demo` 排除;花屏=终端不支持真彩色,换 Windows Terminal/iTerm2 |
+| Codex 每个任务都降级 | 网络断了 → 连续 2 个任务降级流程会自动暂停提醒你 |
+| scan 把多个项目扫混了 | 在仓库根跑了 → cd 到子项目根重跑 `/codebase-context scan --full` |
+| 断电/会话断了 | 直接重跑 /cm-plugin:ai,状态都在磁盘上,自动从断点继续 |
+
+---
+
+*版本 v0.4.2 · 反馈问题请附 /cm-plugin:check 首行的版本号*

package/workflows/cm-plugin/docs//351/207/215/346/236/204/346/265/201/347/250/213/350/256/276/350/256/241/README.md

@@ -0,0 +1,17 @@
+# 重构流程总体设计
+
+综合 cm 小闭环纪律与 Anthropic 迁移方法论(claude.com/blog/ai-code-migration +
+anthropics/code-migration-kit)的重构流程设计图。**已实现为 `commands/cm-plugin:refactor.md`**
+(v0.9.31 落地,v0.9.32 补齐完整融合)——图与命令互为对照,任何一侧修改必须同步另一侧,
+图与实现不得漂移。
+
+- `refactor-flow.png` — 静态图
+- `refactor-flow.mp4` — 动画版(演示用)
+- `refactor-flow.excalidraw` — 可编辑源(拖进 excalidraw.com 修改)
+- `refactor-flow.spec.json` — archscribe 图纸源,可重新渲染全部格式:
+  `python3 ~/.claude/skills/archscribe/scripts/render_animated_diagram.py --spec refactor-flow.spec.json --outdir out --formats png,gif,mp4,svg,html,excalidraw`
+
+核心设计决策:分流门先于一切(缺陷→fix/行为变→prd/结构→本流程)、G0 可行性
+("不重构"合法)、判官自验证(原码必绿坏码必红,无判官不开工)、规模双轨
+(单文件轻量道/跨模块批量道)、三条"修上游"回环(修订排队/三次重复=规则bug/
+行为差异=回滚)、人只在三处签核(门在阶段之间,阶段内零停车)。