@aibyzero/byz 0.1.1 → 0.1.2

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/
+行为差异=回滚)、人只在三处签核(门在阶段之间,阶段内零停车)。