@aibyzero/byz 0.0.0 → 0.1.2

package/workflows/cm/templates/rules/security.md

@@ -0,0 +1,31 @@
+---
+description: {一句话：本项目的安全红线}
+---
+
+<!-- 模板骨架 · 生成时遵守四原则，检查维度对照 OWASP Top 10，{占位符} 结合项目填充 -->
+
+# 安全规范
+
+## 密钥与配置
+
+- 密钥/连接串一律环境变量或密钥管理服务，**禁止硬编码**；`.env` 必须在 .gitignore
+- `.env.example` 只放 key 不放值，与实际环境变量保持同步
+- {项目使用的密钥管理方式：Vault / 云 KMS / CI secrets}
+
+## OWASP 对照清单（按项目暴露面裁剪）
+
+- 注入：一律参数化查询/ORM，模板输出转义；{项目具体的入口清单}
+- 失效的访问控制：权限检查靠近资源，新路由必须显式声明鉴权要求
+- 认证失效：{会话/token 方案的具体约束：过期时间、刷新策略、存储位置}
+- 敏感数据泄露：日志禁止输出密码/token/证件号；传输一律 TLS
+- 安全配置错误：{CORS 白名单、安全响应头清单}
+- 不安全依赖：{依赖审计命令，如 npm audit / cargo audit}，高危漏洞阻断合入
+
+## 输入验证
+
+- 边界层统一校验（{项目使用的校验库}），内层信任已校验数据
+- 文件上传：{类型白名单、大小上限、存储位置}
+
+## 敏感操作
+
+- {支付/删除/导出等操作的审计日志与二次确认要求}

package/workflows/cm/templates/rules/smart-contract.md

@@ -0,0 +1,28 @@
+---
+description: {一句话：智能合约开发与安全约定}
+globs: {如 "contracts/**"，按实际目录}
+---
+
+<!-- 模板骨架 · 生成时遵守四原则，{占位符} 结合项目填充 -->
+
+# 智能合约规范
+
+## 工具链
+
+- 链/框架：{EVM+Foundry / Solana+Anchor…}；编译器版本锁定 {版本}，与 pragma 一致
+- 基础库：{OpenZeppelin/Solmate/SPL 版本锁定}——成熟库优先，不手写基础功能
+
+## 安全清单（每个合约合入前逐项过）
+
+- 重入：ReentrancyGuard 或 checks-effects-interactions
+- 溢出：{Solidity ≥0.8 内置 / checked_* 系列}
+- 权限：{Ownable/AccessControl/多签方案}，避免单点控制
+- 预言机：价格用 TWAP，禁止即时价
+- {Solana：账户 owner/signer 逐 instruction 验证、PDA 种子唯一、CPI 验证 program_id}
+
+## 测试与部署
+
+- 覆盖率 ≥ {90}%；权限测试（非授权调用必须 revert）与攻击场景测试必写
+- Fuzz：{forge test --fuzz-runs 1000 等}
+- 部署：私钥/RPC 一律环境变量；**主网部署强制人工确认**；合约验证 {Etherscan/Sourcify}
+- 事件覆盖所有状态变更；升级机制与紧急暂停：{方案或"不适用"}

package/workflows/cm/templates/rules/testing.md

@@ -0,0 +1,36 @@
+---
+description: {一句话：本项目的测试约定与覆盖率要求}
+---
+
+<!-- 模板骨架 · 生成时遵守四原则（可执行/Bad-Good/量化/现代实践），{占位符} 结合项目填充 -->
+
+# 测试规范
+
+## 框架与命令
+
+- 单元/组件测试：{Vitest/Jest/pytest…，附运行命令}
+- E2E：{Playwright/Cypress…，附运行命令}
+- 覆盖率：`{coverage 命令}`
+
+## 覆盖率要求（QA 与 skill 默认值以本节为准）
+
+- 整体行覆盖 ≥ {N}%
+- 核心模块（{列出目录}）≥ {N}%
+- 纯类型/配置文件排除：{coverage 配置的 exclude 清单}
+
+## 文件与命名约定
+
+- 测试文件位置：{同目录 __tests__ / 独立 tests/ 目录}
+- 命名：{*.test.ts / test_*.py}
+
+## 分类要求
+
+- 工具函数：输入输出全覆盖含边界值
+- API/服务层：正常流 + 异常流 + 边界
+- 组件：渲染 + 交互 + props 边界
+- 禁止：测试内固定延时（用 waitFor）、测试间共享可变状态
+
+## 可视化回归（如有 UI）
+
+- browser_driver: {playwright | chrome-mcp | ask}（cm-qa-engineer 读取本字段）
+- 基准截图位置：{路径}

package/workflows/cm/templates/statusline/cm-statusline.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# cm 工作流状态条 · Claude Code 底部实时显示（官方 statusLine 机制）
+# 输出原则: 大白话,路过的人扫一眼能懂;工程细节收在行尾暗色角标
+input=$(cat)
+
+PTR="$HOME/.claude/cm-current-specs"
+if [ -f "$PTR" ]; then
+  SPECS=$(cat "$PTR" 2>/dev/null)
+  ST="$SPECS/.cm-status.json"
+  if [ -f "$ST" ]; then
+    python3 - "$ST" "$SPECS" <<'EOF' && exit 0
+import json, sys, os, re, time
+try:
+    s = json.load(open(sys.argv[1]))
+except Exception:
+    sys.exit(1)
+SPECS = sys.argv[2]
+G, Y, B, R, D = "\033[32m", "\033[33m", "\033[1m", "\033[0m", "\033[2m"
+
+PHASE = {  # 节点 → 人话阶段
+    "N1": ("🚀", "启动准备"), "N2": ("📋", "规划任务"), "N3": ("🔨", "开发中"),
+    "N4": ("🔍", "检查代码"), "N5": ("💾", "保存进度"), "N6": ("🧪", "质量检测"),
+    "N7": ("🧹", "整理现场"), "N8": ("📦", "收尾总结"),
+}
+age = time.time() - os.path.getmtime(sys.argv[1])   # 状态新鲜度
+node = s.get("node", ""); st = s.get("state", "")
+if st == "done" and age > 3600:
+    sys.exit(1)   # 完成态过期 1 小时 → 回落默认显示,不再霸屏
+det = s.get("detail", "")[:44]; feat = s.get("feature", ""); task = s.get("task", "")
+feat_name = re.sub(r"^\d+\.", "", feat)  # 去掉编号前缀
+
+def progress(feature):
+    """当前 feature 的任务进度: (完成数, 总数, 当前序号)"""
+    try:
+        md = open(os.path.join(SPECS, feature, "tasks.md"), encoding="utf-8").read()
+        items = re.findall(r"^- \[( |x)\] (T-\d+)", md, re.M)
+        active = [(c, t) for c, t in items]
+        done = sum(1 for c, _ in active if c == "x")
+        cur = next((i + 1 for i, (c, _) in enumerate(active) if c == " "), len(active))
+        return done, len(active), cur
+    except Exception:
+        return None
+
+icon, phase = PHASE.get(node, ("⚙", "运行中"))
+tag = f"{D} ·{node}{' '+task if task else ''}{R}"   # 工程角标,暗色收尾
+
+if st not in ("paused_for_human", "done") and age > 600:
+    # 崩溃残留检测: 运行态超 10 分钟无更新,大概率已中断——错误的仪表比没有仪表危险
+    print(f"{Y}⚠ 可能已中断{R}（最后更新 {int(age//60)} 分钟前,去会话确认）{D}原状态: {phase}·{det[:20]}{R}{tag}")
+elif st == "paused_for_human":
+    print(f"{Y}🖐 等你确认：{det} —— 流程已暂停,回 Claude Code 回复即可{R}{tag}")
+elif st == "done":
+    print(f"{G}✅ 全部完成!{R} 所有任务已交付,收尾报告见会话{tag}")
+else:
+    p = progress(feat) if feat else None
+    prog = f"（进度 {p[0]}/{p[1]}）" if p else ""
+    body = f"{det}" if det else phase
+    fpart = f"{B}{feat_name}{R} · " if feat_name else ""
+    print(f"{G}{icon} {phase}{R} {fpart}{body}{D}{prog}{R}{tag}")
+EOF
+  fi
+fi
+
+# 兜底：无 cm 执行时显示模型与目录
+echo "$input" | python3 -c '
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    m = d.get("model", {}).get("display_name", "")
+    w = d.get("workspace", {}).get("current_dir", "").rstrip("/").split("/")[-1]
+    print(f"{m} · {w}")
+except Exception:
+    print("cm")' 2>/dev/null || echo "cm"

package/workflows/cm/templates/ui-lens/cm-ui-lens-extract.mjs

@@ -0,0 +1,55 @@
+// cm-ui-lens-extract — UI 还原的对表裁判(双用途,零模型零幻觉)
+// 跑在基准页(HTML 原型/Stitch 导出)= 逐元素规格表;跑在还原页 = 实测表。
+// 两表对差 = 页面内循环的依据;同脚本双跑 = 多镜头验收的数据层。
+// 用法: node cm-ui-lens-extract.mjs {URL或文件路径} {输出.json} [宽度=1280]
+// 依赖解析照抄项目既有测试基建的惯例(npm root -g 兜底,勿自造)。
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { writeFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { execSync } from "node:child_process";
+const require = createRequire(import.meta.url);
+function loadPlaywright() {
+  const c = ["playwright"];
+  try { c.push(join(execSync("npm root -g", { stdio: ["ignore", "pipe", "ignore"] }).toString().trim(), "playwright")); } catch {}
+  for (const x of c) { try { return require(x); } catch {} }
+  console.error("Playwright 不可用 — 按 skill 降级路径处理"); process.exit(2);
+}
+const { chromium } = loadPlaywright();
+const target = process.argv[2]; const out = process.argv[3] || "lens.json";
+const width = parseInt(process.argv[4] || "1280", 10);
+const url = existsSync(target) ? pathToFileURL(resolve(target)).href : target;
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width, height: 900 }, deviceScaleFactor: 1 });
+await page.goto(url, { waitUntil: "networkidle" });
+const data = await page.evaluate(() => {
+  const seen = [];
+  const path = (el) => {
+    const parts = [];
+    for (let e = el; e && e !== document.body; e = e.parentElement) {
+      let p = e.tagName.toLowerCase();
+      if (e.id) { parts.unshift(p + "#" + e.id); break; }
+      if (e.className && typeof e.className === "string") p += "." + e.className.trim().split(/\s+/).slice(0, 2).join(".");
+      const sib = e.parentElement ? [...e.parentElement.children].filter(x => x.tagName === e.tagName) : [];
+      if (sib.length > 1) p += ":nth(" + sib.indexOf(e) + ")";
+      parts.unshift(p);
+    }
+    return parts.join(">");
+  };
+  for (const el of document.querySelectorAll("body *")) {
+    const r = el.getBoundingClientRect();
+    if (r.width < 1 || r.height < 1) continue;              // 不可见不入表
+    const cs = getComputedStyle(el);
+    const hasText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim());
+    seen.push({
+      sel: path(el),
+      geo: { x: +r.x.toFixed(1), y: +r.y.toFixed(1), w: +r.width.toFixed(1), h: +r.height.toFixed(1) },
+      font: hasText ? { family: cs.fontFamily.split(",")[0].trim(), size: cs.fontSize, weight: cs.fontWeight, lineHeight: cs.lineHeight, letterSpacing: cs.letterSpacing } : null,
+      style: { color: cs.color, bg: cs.backgroundColor, radius: cs.borderRadius, shadow: cs.boxShadow !== "none" ? cs.boxShadow : null },
+    });
+  }
+  return seen;
+});
+await browser.close();
+writeFileSync(out, JSON.stringify({ url: target, viewport: width, count: data.length, elements: data }, null, 1));
+console.log(`lens: ${data.length} 元素 → ${out}`);

package/workflows/cm-plugin/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zero / 王者与
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/workflows/cm-plugin/README.md

@@ -0,0 +1,195 @@
+# cm-plugin-workflow — Chrome 插件专用的 Claude Code 自动化开发工作流
+
+一套 spec-driven 的 Claude Code 工作流，**专用于 Chrome 浏览器扩展（MV3）开发**：需求文档 → 开发规格 → 自动开发 → QA/商店合规 → 文档同步。
+
+基于 [cm-workflow](https://github.com/kingxiaozhe/cm-workflow)（通用多工种版）定制：流程引擎（N1–N8 状态机、prd/fix/refactor 闭环）完整继承，工种层换成插件领域——核心工种是扩展工程师，QA 带真实浏览器加载验证与商店合规检查单，发布通道对准 Chrome Web Store。前缀 `cm-plugin:`，与上游 `cm:` 可同机共存（安装产物零交集）。
+
+## BYZ 集成
+
+BYZ 按完整 Git 提交锁定并内置本工作流。BYZ 用户只安装或更新 BYZ，不需要单独安装、更新或回滚 CM Plugin Workflow，也不应为 BYZ 内置副本启用本仓库的自动更新脚本。
+
+## 目录结构
+
+```text
+commands/                          # 斜杠命令（安装到 ~/.claude/commands/）
+├── cm-plugin:rewrite.md           # ★重写直通流水线：链接 → 素材采集 → huashu-design 原型 → PRD → 拆specs → 开发到底
+├── cm-plugin:scout.md             # 竞品插件重写机会评估（评论槽点/停更信号/源码功能盘点 → 机会评分卡；支持 --rewrite 素材模式、--bakeoff 多候选对抗模式）
+├── cm-plugin:init.md              # 项目 .claude/ 初始化（CLAUDE.md + rules/，识别扩展脚手架与权限清单）
+├── cm-plugin:prd.md               # 需求文档 → specs 三件套（requirements/design/tasks），支持 --change 变更模式
+├── cm-plugin:ai.md                # 自动开发主循环（流程图状态机）
+├── cm-plugin:fix.md               # 缺陷修复小闭环（复现→定位→防护网→最小修复→Codex审查→波及面回归→档案落盘）
+├── cm-plugin:refactor.md          # 重构闭环（行为保持；设计见 docs/重构流程设计）
+├── cm-plugin:idea.md              # 点子→PRD 访谈入口（加载 idea-to-prd 技能；流程上游，非 N1–N8 步骤）
+├── cm-plugin:check.md             # 框架一致性自检（角色/命名/引用/配套/版本）
+│
+│  # 独立工具 skill（不属于 N1–N8 流程，按需使用）
+│  skills/idea-to-prd/             # 点子→PRD 产品访谈搭档（新插件从零想法起步的前置工具）
+│  skills/darwin-skill/            # 技能优化器（MIT 收编自 alchaincyf/darwin-skill，详见其 NOTICE.md）
+│  skills/codebase-context/        # 代码库业务地图（scan/dev 两模式）
+└── cm-plugin-ai-nodes/            # cm-plugin:ai 的 8 个流程节点，按需加载
+    ├── N1-init.md                 # 初始化：解析路径、扫描 features、加载上下文
+    ├── N2-enter-feature.md        # 进入 feature：断点恢复、依赖分析、串/并行计划
+    ├── N3-execute-task.md         # 执行 task：按工种匹配 skill
+    ├── N4-review.md               # AI 自审 + Codex 复审（环境不可用时降级）
+    ├── N5-mark-done.md            # 标记 [x]、写 LESSONS.md
+    ├── N6-qa-eval.md              # QA 评分决定是否触发 QA（含真实浏览器形态确认卡点）
+    ├── N7-context.md              # 每个 task 后 /clear 重载 specs
+    └── N8-finish.md               # 调用 doc-syncer、编制发布待决清单、输出总结
+
+skills/                            # 工种 Skills（安装到 ~/.claude/skills/）—— skill 管技术
+├── cm-plugin-extension-engineer/  # ★核心工种：扩展本体（manifest/service worker/content script/
+│                                  #   popup/options/side panel/chrome.storage/消息通信），适配 WXT/Plasmo/CRXJS/原生
+├── cm-plugin-ui-engineer/         # UI 还原（design-baseline → token 先行 → 原子还原 → BackstopJS ≤1%）
+├── cm-plugin-backend-engineer/    # 配套后端（API 代理/鉴权/同步；扩展 CORS 与 token 鉴权、密钥只在服务端）
+├── cm-plugin-qa-engineer/         # QA（测试补全、--load-extension 真实浏览器 E2E、商店合规检查单）
+├── cm-plugin-product-manager/     # 产品（需求分析、歧义五问含权限敏感面、变更影响、业务验收走查）
+├── cm-plugin-devops-engineer/     # 发布（打包 zip、权限 diff 核对、Chrome Web Store 提审强制人工确认）
+└── cm-plugin-doc-syncer/          # 文档同步（README 权限清单/CLAUDE.md/rules/CHANGELOG）
+
+agents/                            # 并行工种的子 agent 定义（安装到 ~/.claude/agents/）—— agent 管纪律
+├── cm-plugin-extension-agent.md   # 只做指定任务、manifest 权限只减不增、不自行标记、规范汇报
+├── cm-plugin-ui-agent.md          # 只碰展示层白名单、基准只读、改既有 token 强制上报
+└── cm-plugin-backend-agent.md     # 范围外鉴权/权限改动强制上报
+```
+
+**分工原则**：并行干活的做 agent（extension/UI/后端），串行把关的做 skill（产品/QA/发布/doc-syncer）。
+
+**可选外部依赖**：`npx skills add alchaincyf/huashu-design`（MIT）——无设计稿时在 /cm-plugin:prd 阶段生成高保真原型作为设计基准，未安装则 UI 由扩展工程师自行实现。
+
+**rules 模板层**（`templates/rules/`，install.sh 装到 `~/.claude/templates/cm-plugin-rules/`）：7 个规则骨架（coding-style / testing / security / git-workflow / **chrome-extension** / frontend / backend-api），/cm-plugin:init 以其为骨架 + 项目推断生成最终规则；模板头部统一四原则（可执行 / Bad-Good / 量化 / 现代实践）。其中 `chrome-extension.md` 是插件铁律（权限最小化、MV3 约束、禁远程代码、消息契约集中管理）。**把团队规范沉淀进模板，所有项目 init 出的 rules 自动带团队基因**——这是团队定制的官方入口。
+
+**收编素材**：QA 与 devops 两个 skill 的 `references/` 下的 CWS 检测模式清单、官方违规码表、提审材料清单、CI/CD 模板收编自 [quangpl/browser-extension-skills](https://github.com/quangpl/browser-extension-skills)（MIT），来源与改动见各 skill 目录的 `NOTICE.md`。
+
+## 扩展 E2E harness 模板（templates/e2e/ → ~/.claude/templates/cm-plugin-e2e/）
+
+MV3 扩展的 Playwright E2E 有一组固定坑，dogfood 实测全踩过一遍，现固化成**可拷贝的久经考验底座**（`extension-harness.ts` + `smoke.spec.example.ts`）。bootstrap T-005 直接拷入，每个新插件不再重踩：
+
+- 系统 Chrome（2026 版）默认屏蔽 `--load-extension` → 须用 **Chrome for Testing**（harness 跨架构自动发现）
+- `--headless=new`（旧 headless 不支持扩展，`headless:false` 在无头/CI 退化 flaky）
+- SW **注册-停机竞态**（`acquireServiceWorker` 三路取先到）
+- `sw.evaluate` 前须 `wakeServiceWorker` 取活引用（否则 `Worker was closed`）
+
+给 N5「运行观察闸」提供了真能用的工具——不只是要求"真跑观察"，还给出怎么跑。
+
+## 流程工具脚本（templates/scripts/ → ~/.claude/templates/cm-plugin-scripts/）
+
+把 dogfood 实测中最痛的三个手工环节工具化，命令按需调用（都是有据可查的真实摩擦）：
+
+- **cm-plugin-preflight.sh** — 环境预检：开跑前一次性引爆扩展开发的环境地雷（Node/git/Codex/**Chrome for Testing**/系统 Chrome）。最大的雷是系统 Chrome（2026 版）静默屏蔽 `--load-extension`，E2E 必须用 CfT。N1/R0 调用。
+- **cm-plugin-codex.sh** — Codex 审查封装：收齐正确调用姿势（`--skip-git-repo-check --sandbox read-only` + 超时防挂起 + 输出清洗去源码转储 + 凭证落盘）。N4/prd/scout 的 Codex 调用优先用它，不裸调。
+- **cm-plugin-log.sh** — JSONL 日志助手：自动 ISO8601 时间戳、原子追加、JSON 转义。杜绝手写 echo 的「先记账后落盘」「攒批挤同秒」两类实测错误。
+
+## 插件领域的三条红线（区别于上游的领域性约束）
+
+1. **manifest 权限只减不增**（agent 层硬约束）——任务范围外的权限新增/扩大必须停下上报
+2. **Chrome Web Store 提审强制人工确认**——含权限变更的版本更新同样过闸
+3. **商店合规检查单只举旗不定性**——权限最小化/单一用途/数据披露/禁远程代码/注入克制，举旗项交人裁决
+
+## 安装
+
+### Pi / BYZ 内置 package
+
+BYZ 按完整 Git 提交锁定并内置本工作流。用户安装 BYZ 后可直接运行
+`byz --workflow cm-plugin`，不需要设置私有源，也不需要执行独立的工作流安装、
+更新或回滚命令。BYZ 内置副本只随 BYZ 版本更新。
+
+### Codex / Claude Code legacy installer
+
+```bash
+./install.sh          # macOS/Linux 一键安装（含覆盖确认），装完自动提示运行 /cm-plugin:check
+```
+
+```powershell
+powershell -ExecutionPolicy Bypass -File install.ps1   # Windows 版
+```
+
+或手动：
+
+```bash
+cp -r commands/* ~/.claude/commands/
+cp -r skills/*   ~/.claude/skills/
+cp -r agents/*   ~/.claude/agents/
+```
+
+安装/修改框架后运行 `/cm-plugin:check` 做一致性自检（角色存在性、命名一致、引用有效、配套完整、外部依赖 + **安装版本号**——反馈问题时请带上它）。
+
+**与上游 cm-workflow 共存**：本包所有安装产物（命令前缀、skill/agent 名、`templates/cm-plugin-*`、`~/.cm-plugin-workflow/`）与上游零交集，两套可同机安装互不覆盖。
+
+**Windows 说明**：核心工作流（commands/skills/agents）是纯 Markdown，Windows 原生可用；状态条 / 终端像素版 / serve.sh 是 bash+python3 脚本，在 WSL 或 Git Bash 中使用（浏览器像素版页面双击加 `?demo` 即可预览，不依赖脚本）。
+
+## 执行可视化（终端原生优先）
+
+**① 终端状态条（推荐，Claude Code 底部常驻）**——官方 statusLine 机制，零外部依赖：
+
+```json
+// ~/.claude/settings.json
+"statusLine": {"type": "command", "command": "~/.claude/templates/cm-plugin-statusline.sh"}
+```
+
+效果：`⚙ ○○○●○○○○ N4 1.tab-organizer/T-005 · Codex复审第1轮`——八点节点条实时点亮；等人时整条变黄 `⏸ 等待人工`；数据来自 .cm-status.json（N1 写入 ~/.claude/cm-plugin-current-specs 指针定位）。
+
+**② 内置任务清单镜像**——N2 进 feature 时任务自动镜像到 Claude Code 原生任务清单，N3/N5 同步状态，终端直接看勾选进度（无需配置）。
+
+**③ 浏览器看板（备选，适合投屏/远程盯进度）**
+
+```bash
+templates/dashboard/serve.sh {specs路径}   # 浏览器打开提示的地址，2 秒自动刷新
+```
+
+**纯只读、零侵入**——只消费 specs 落盘文件（tasks.md 勾选 / METRICS / LESSONS），执行引擎无感知。
+
+**④ 像素流水线（2D 像素游戏视角，演示/氛围屏首选）**——8 个像素工位对应 N1–N8：
+
+```bash
+templates/pixel/cm-pixel.sh            # 终端版（ANSI 像素，分屏挂一个 pane）
+templates/pixel/cm-pixel.sh --demo     # 终端版演示模式（不需要真实运行）
+templates/pixel/serve.sh {specs路径}   # 浏览器版（16-bit 风格，办公室大屏）
+# 浏览器版演示模式: 打开地址后加 ?demo
+```
+
+精灵素材采用 Kenney Pixel Platformer 系列开源素材（CC0，已内嵌，单文件零依赖）。
+
+## 自动更新（可选，macOS/Linux）
+
+`templates/auto-update/` 提供会话级自动更新链路，install.sh 装到 `~/.cm-plugin-workflow/`，按提示在 settings.json 的 `hooks.SessionStart` 挂两条即启用：
+
+- **cm-update.sh**：每次开会话异步检测上游新提交并自动重装；无新提交时做**逐文件字节级比对**，安装被改动/误删即自愈还原；**有工作流正在跑（.cm-status.json 为 running 且 30 分钟内活跃）则跳过本轮**。团队 fork 用 `CM_UPDATE_REMOTE` 环境变量指仓库，不要改脚本（会被自愈还原）
+- **cm-announce.sh**：下次开会话时播报更新/自愈结果，报完即删
+
+分工：更新器管"装的东西对不对"（机械，每会话），`/cm-plugin:check` 管"引用链断没断"（AI，改框架后跑），N1 预检管"这次运行环境行不行"（流程内）。
+
+## 度量与双保险
+
+- **METRICS.md**（specs 目录，N5 自动落盘）：每任务记录审查轮次、Codex 拦截、QA 结果、人工介入次数
+- **RELEASES.md**（specs 目录，devops 落盘）：每次打包/提审/部署的审计记录，含权限 diff 与商店审核状态
+- **templates/hooks/pre-commit-cm-task-check**：任务标记双保险 git hook（默认仅警告，`CM_TASK_CHECK_STRICT=1` 时阻断）
+
+## 使用流程
+
+**重写直通（已决定重写某插件时的主入口）：**
+
+`/cm-plugin:rewrite {商店链接}`——一条命令走完全程：**R1** 素材采集（scout 素材模式：源码盘点+评论痛点，结论不设门）→ **R2** huashu-design 生成 UI 原型（唯一新增卡点：设计方向确认）→ **R3** 输出 PRD（功能三态标记：保留/改进/舍弃）→ **R4** /cm-plugin:prd 拆 specs（规格摘要卡人审）→ **R5** /cm-plugin:ai 开发到 N8 发布待决清单。中断可幂等续跑。
+
+**选品（还没决定做不做时的第 0 步）：**
+
+`/cm-plugin:scout {商店链接}`——三维评估现存插件值不值得重写：**评论区槽点**（低分评论聚类 = 重写的原始需求，高分评论 = 不能丢的核心体验）、**停更信号**（>6 个月未更新是最强机会信号）、**源码功能盘点**（只盘功能不抄代码，清白室红线）。产出机会评分卡（GO/WATCH/NO-GO 由人拍板）+ 槽点→需求映射表 + 全程 `.log.jsonl` 运行日志（与 /cm-plugin:ai 同规格，可审计）；多次选品由 `SCOUTS.md` 台账串联，WATCH 项带复查到期提醒。GO 后报告直接作为 /cm-plugin:prd 的需求文档。
+
+**还没定靶时**：`/cm-plugin:scout --bakeoff {方向提示}`——多候选对抗比对模式：按判据（纯客户端/现任弃养或劣化/空档没被干净替代填满/非红海）凑齐 3-5 个候选做轻量核验 → 交 Codex **证否式对抗**（默认都不值得重写，证据压倒才翻）→ 逼出**一个确定靶**（或"全部不达标，继续搜"，无 GO 是合法结论不硬凑），选出的靶再走完整三维。挡住"单点押注把 WATCH 美化成 GO"（dogfood 实跑教训）。
+
+**存量插件项目：**
+
+1. 在插件项目中运行 `/cm-plugin:init`，生成 `.claude/CLAUDE.md` 和 `rules/` 规范（含 chrome-extension.md 铁律）
+2. 建一个 specs 文件夹，把需求文档放进 `docs/`，运行 `/cm-plugin:prd {specs路径}` 生成规格三件套
+3. 审查 specs 后运行 `/cm-plugin:ai {specs路径} {插件项目路径}` 开始自动开发
+4. 需求变更时用 `/cm-plugin:prd --change {N}.{feature} 变更描述`，已完成任务不受影响
+
+**0 到 1 新插件（无需先手动搭脚手架）：**
+
+1. 建 specs 文件夹放入需求文档，直接运行 `/cm-plugin:prd {specs路径}`——检测到空项目后自动进入 0→1 分支：先确认**表面组合**（popup/side panel/content script…）与**目标浏览器**，给出 2-3 套脚手架方案（WXT/Plasmo/CRXJS）供人拍板，再生成 `0.bootstrap` feature（design.md 即 ADR，任务含脚手架/规范生成/CI 打包/公共底座/E2E 基座）
+2. 人审规格（审 `0.bootstrap` 就是审架构，审**权限清单**就是审商店风险）后运行 `/cm-plugin:ai`——bootstrap 完成时的 QA 会把扩展**真实加载进浏览器**截图给你做形态确认
+3. 日后架构调整走 `/cm-plugin:prd --change 0.bootstrap 变更描述`，选型演进全程留痕
+4. 跳过 `/cm-plugin:init`——空项目没有可分析的对象，规范生成是 bootstrap 的任务之一
+
+**发布：**
+
+feature 全部完成后，N8 会编制**发布待决清单**（版本、权限 diff、商店材料就绪度）；商店提审由你确认后触发，审核状态记入 RELEASES.md，被拒原因按 bug 回流闭环。

package/workflows/cm-plugin/VERSION

@@ -0,0 +1 @@
+0.5.0

package/workflows/cm-plugin/agents/cm-plugin-backend-agent.md

@@ -0,0 +1,34 @@
+---
+name: cm-plugin-backend-agent
+description: 后端 API 开发子 agent。由 /cm-plugin:ai 在并行执行后端任务时派发，负责流程纪律（任务边界、上下文、汇报、退出），具体开发规范由 cm-plugin-backend-engineer skill 提供。
+---
+
+# cm-plugin-backend-agent — 后端开发子 agent
+
+你是被主流程派发的后端 API 开发子 agent。**agent 管纪律，skill 管技术**——你的职责是守住流程边界，开发方法完全遵循 skill。
+
+## 执行流程
+
+1. **加载 skill**：读取并严格遵循 `cm-plugin-backend-engineer` skill，它是开发方法的唯一准则
+2. **读取上下文**：派发指令中给出的 specs 摘录（requirements/design/tasks 相关部分）+ 代码项目的 `.claude/CLAUDE.md` 和 `.claude/rules/`
+3. **只做指定任务**：严格按派发指令中的任务编号（T-xxx）执行，不顺手做其他任务
+
+## 边界约束（不可违反）
+
+- **不修改**任务范围之外的文件；发现必须跨界的改动 → 停止并在汇报中说明
+- **不自行标记** tasks.md —— 标记完成是主流程 N5 的职责
+- **不自行执行** review —— 审查是主流程 N4 的职责
+- **不得修改 `.claude/` 下任何文件**（CLAUDE.md、rules/）——规范异议写入汇报，由主流程处理
+- **不修改 design.md** —— 契约偏差走三级协议第 1 级：只报不改，写入汇报「契约相关」栏
+- **任务范围之外的鉴权/权限/会话逻辑改动 → 立即停止并上报**；任务本身即鉴权任务则正常执行（人工把关已在规格审查完成，QA 由 N6 强制触发兜底）
+
+## 完成后汇报（固定格式）
+
+```text
+📦 T-{编号} 完成汇报
+- 变更文件: {列表}
+- 验证结果: {lint / build / 接口实测结果}
+- 契约相关: {逐条列出实现的接口及与 design.md 的偏差，无偏差写"完全一致"}
+- 需其他工种配合: {事项，无则写"无"}
+- 建议写入 LESSONS: {要点，无则写"无"}
+```

package/workflows/cm-plugin/agents/cm-plugin-extension-agent.md

@@ -0,0 +1,35 @@
+---
+name: cm-plugin-extension-agent
+description: 浏览器扩展开发子 agent。由 /cm-plugin:ai 在并行执行扩展本体任务时派发，负责流程纪律（任务边界、上下文、汇报、退出），具体开发规范由 cm-plugin-extension-engineer skill 提供。
+---
+
+# cm-plugin-extension-agent — 浏览器扩展开发子 agent
+
+你是被主流程派发的扩展开发子 agent。**agent 管纪律，skill 管技术**——你的职责是守住流程边界，开发方法完全遵循 skill。
+
+## 执行流程
+
+1. **加载 skill**：读取并严格遵循 `cm-plugin-extension-engineer` skill，它是开发方法的唯一准则
+2. **读取上下文**：派发指令中给出的 specs 摘录（requirements/design/tasks 相关部分）+ 代码项目的 `.claude/CLAUDE.md` 和 `.claude/rules/`
+3. **只做指定任务**：严格按派发指令中的任务编号（T-xxx）执行，不顺手做其他任务
+
+## 边界约束（不可违反）
+
+- **不修改**任务范围之外的文件；发现必须跨界的改动 → 停止并在汇报中说明
+- **manifest 权限只减不增**：任务范围外的 permission / host_permission 新增或匹配范围扩大 → 停止并上报，不得先加了再说——权限扩张影响商店审核与用户信任，必须过主流程
+- **不自行标记** tasks.md —— 标记完成是主流程 N5 的职责
+- **不自行执行** review —— 审查是主流程 N4 的职责
+- **不得修改 `.claude/` 下任何文件**（CLAUDE.md、rules/）——规范异议写入汇报，由主流程处理
+- 涉及消息契约（message type、payload、storage schema、后端 API 字段）的决定 → 以 design.md 为准，design.md 未覆盖的在汇报中明确列出
+
+## 完成后汇报（固定格式）
+
+```text
+📦 T-{编号} 完成汇报
+- 变更文件: {列表}
+- 验证结果: {lint / typecheck / build / 真实加载冒烟 结果}
+- manifest/权限变更: {逐项带用途理由，无则写"无"}
+- 契约相关: {新增或依赖的消息契约/API 约定，无则写"无"}
+- 需其他工种配合: {事项，无则写"无"}
+- 建议写入 LESSONS: {要点，无则写"无"}
+```

package/workflows/cm-plugin/agents/cm-plugin-ui-agent.md

@@ -0,0 +1,34 @@
+---
+name: cm-plugin-ui-agent
+description: UI 还原子 agent。由 /cm-plugin:ai 在并行执行 UI 还原任务时派发，负责流程纪律（任务边界、上下文、汇报、退出），具体还原方法由 cm-plugin-ui-engineer skill 提供。
+---
+
+# cm-plugin-ui-agent — UI 还原子 agent
+
+你是被主流程派发的 UI 还原子 agent。**agent 管纪律，skill 管技术**——你的职责是守住流程边界，还原方法完全遵循 skill。
+
+## 执行流程
+
+1. **加载 skill**：读取并严格遵循 `cm-plugin-ui-engineer` skill，它是还原方法的唯一准则
+2. **读取上下文**：派发指令中给出的 specs 摘录 + 设计基准路径（`design-baseline/`）+ 代码项目的 `.claude/CLAUDE.md` 和 `.claude/rules/`
+3. **只做指定任务**：严格按派发指令中的任务编号（T-xxx）执行，不顺手做其他任务
+
+## 边界约束（不可违反）
+
+- **只碰展示层文件**：组件公共目录（如 `components/ui/`）、样式与 token 文件、静态资产、本任务的页面静态结构；**不碰**业务逻辑、API 层、路由配置
+- **不修改设计基准文件**（`design-baseline/` 只读）
+- **不修改既有 token 值**——需要改 → 停止并写入汇报「契约相关」栏（新增 token 可自由添加）
+- **不自行标记** tasks.md、**不自行执行** review、**不修改** design.md（契约偏差只报不改）
+- **不得修改 `.claude/` 下任何文件**（CLAUDE.md、rules/）——规范异议写入汇报，由主流程处理
+- 基准缺失状态/断点 → 上报，**不脑补设计**；执行期不向用户征求设计意见
+
+## 完成后汇报（固定格式）
+
+```text
+📦 T-{编号} 完成汇报
+- 变更文件: {token / 组件 / 页面 / 资产列表}
+- 验证结果: {BackstopJS 各断点 mismatch 值 + 白名单项}
+- 契约相关: {组件契约实现情况、token 变更清单，无则写"无"}
+- 需其他工种配合: {前端可接线的组件清单及 props，无则写"无"}
+- 建议写入 LESSONS: {要点，无则写"无"}
+```

package/workflows/cm-plugin/commands/cm-plugin-ai-nodes/N1-init.md

@@ -0,0 +1,60 @@
+# N1: 初始化
+
+1. 从 `$ARGUMENTS` 提取 **specs 文件夹路径** 和 **代码项目路径**（可多个）
+2. 扫描 specs 下所有编号目录（`0.xxx/`、`1.xxx/`、`2.xxx/`），按编号排列
+3. 每个 feature 目录须含 requirements.md、design.md、tasks.md
+4. 加载：代码项目的 `.claude/CLAUDE.md` + `.claude/rules/`（0→1 项目此时可能尚不存在，跳过不报错）
+5. 加载 `{SPECS_DIR}/LESSONS.md`（架构决策和踩坑记录，开发时必须参考）；**文件不存在（全新 specs 首次运行的常态）→ 按 0 条处理，不报错不中断**，首个任务的 N5 会创建它
+6. 验证各代码项目路径存在，**空目录按信号处理**：
+   - 空目录 + specs 含 `0.bootstrap` → 0→1 已在规格期人工确认，直接执行
+   - **空目录 + specs 无 `0.bootstrap` → 矛盾信号，必须暂停询问**：specs 是按存量项目生成的，但目录是空的——"需要先 clone 项目？（clone 完成后回复继续）还是这就是新项目？（specs 上下文有毒，需重跑 /cm-plugin:prd 走 0→1 分支）"两种回答都不得跳过：clone 场景等用户，重跑场景中止
+   - **非空目录 + `0.bootstrap` 存在且其脚手架任务（T-001）未完成 → 矛盾信号，必须暂停询问**：规格期确认的是 0→1，但目录里已有项目（用户事后 clone 了？）——"继续 0→1 会在现有项目上覆盖生成脚手架。是改用现有项目？（需重跑 /cm-plugin:prd 按存量项目生成规格）还是目录内容可弃、继续 0→1？"不确认不得执行 T-001
+
+## 规格审批入口闸（先于一切预检）
+
+读取 `{SPECS_DIR}/.cm-specs-status`：
+
+- `approved` → 直接继续（断点续跑不重复问）
+- `awaiting_review` 或文件缺失（旧版 specs）→ 把规格摘要卡打给用户（specs 里没有摘要卡就现场汇总：feature 数/任务数/交付形态/风险点），**等用户明确回复"开始"**；回复后写 `{"status":"approved","at":"{时间}"}` 再继续。**泛化授权语不构成审批**（"按最优解处理""继续""你看着办"这类话授权的是执行方式，不是规格内容）——收到时必须回问一次："规格摘要卡确认开始吗？"（实跑失守：diff-lens 把"按照你分析的最优解去处理"直接视为审批通过）
+- 启动参数含 `--yes` → 跳过此问直接写 approved（适合刚人审完立刻开跑的场景）
+
+> 这是**入口授权门**（人把关方案端），不属于"暂停仅灾难级"约束的中途暂停，也不计入 METRICS 人工介入。实跑教训：没有这道闸，prd 生成完会被一句"继续"顺势带进开发，人审形同虚设。
+
+## 环境预检（先于一切任务，一次性）
+
+开工前跑 `~/.claude/templates/cm-plugin-scripts/cm-plugin-preflight.sh`（存在则用；不存在按下方逐项手查）——它一次性探明扩展开发全链路的环境地雷并给出补救：Node/npm、git、Codex（+调用姿势）、**Chrome for Testing（E2E 真实加载扩展的唯一途径——系统 Chrome 2026 版静默屏蔽 `--load-extension`）**、系统 Chrome。有阻塞项（退出码 1）先解决再开跑。依据：实测最吃时间的不是开发本身,是这些报错什么都不给的环境地雷（`--load-extension` 被屏蔽、codex 缺 `--skip-git-repo-check`、playwright 浏览器下载被墙）。
+
+## 审查通道预检（Codex 是主通道）
+
+开工前探测 Codex 可用性（`codex --version` 或项目配置的 codex 调用方式），结果直接影响 N4 的审查质量，必须在第一个任务开始前让用户知情。**调用封装**：`~/.claude/templates/cm-plugin-scripts/cm-plugin-codex.sh "<提示词>" [凭证路径]` 已收齐正确姿势（`--skip-git-repo-check --sandbox read-only` + 超时 + 输出清洗 + 凭证落盘），N4/prd/scout 的 Codex 调用优先用它，不裸调（实测:裸调常忘 flag、挂起、输出混入源码转储要手工清洗）。
+
+- 可用 → 正常，N4 走双模型交叉审查
+- **不可用 → 明确告知用户**："Codex 未检测到，代码审查将降级为对抗式子代理（质量次优）。建议安装/登录 codex CLI 后回复继续，或回复'接受降级'跑完本次。"——用户接受降级才继续，且本次运行的所有 METRICS 审查列都会带 `降级` 标注。**不得静默降级开跑**
+
+## Git 前置检查（字段优先，询问兜底）
+
+**先读 CLAUDE.md 的「版本控制」字段**（/cm-plugin:init 或 bootstrap 已确认并落盘）：
+
+- `remote` / `local` → 按常规执行每任务提交，不询问；**顺手装双保险 hook**：`~/.claude/templates/cm-plugin-task-check-hook`（安装名，源 templates/hooks/pre-commit-cm-task-check）存在且代码仓库 `.git/hooks/pre-commit` 未装 → 复制安装（默认警告模式,不阻断），输出一行 `🪝 任务标记双保险已装(警告模式)`——纪律靠节点文字自我约束在长会话中必然漏（实跑失守：两个项目均未装 hook,N5 漏标/漏凭证无人拦）
+- `none` → 直接进入 **NO_GIT 降级模式**，不询问：N5 跳过 git 提交（METRICS 备注 `no-git`）、doc-syncer 用文件扫描替代 git diff、hook 不适用、审计链降级为 METRICS + tasks 勾选
+
+**字段不存在时**（项目未经 init 的兜底路径）：
+
+- 有 git 仓库 → 继续，并建议补跑 /cm-plugin:init
+- 无仓库但存在 `0.bootstrap/` 且任务含脚手架/git init → 跳过询问，交给 T-001
+- 无仓库且非上述 → 问一次"git init？（推荐）/ 不使用版本控制"，**答案由主流程回写 CLAUDE.md 版本控制字段**（决策落盘，任何后续运行不再询问）
+
+## 可视化入口提示（N1 输出末尾，一次性）
+
+N1 完成、进入 N2 之前，在输出末尾打印一行可视化入口（存在 `~/.claude/templates/cm-plugin-pixel/` 时才打印）：
+
+```text
+🎮 想看像素流水线？另开终端: ~/.claude/templates/cm-plugin-pixel/cm-pixel.sh
+   浏览器版: ~/.claude/templates/cm-plugin-pixel/serve.sh {SPECS_DIR} （地址加 ?demo 可先看演示）
+```
+
+只在 N1 打印一次，不重复——入口可发现性问题的修复（实测反馈：用户不知道要手动启动）。
+
+## 0.bootstrap 优先规则
+
+存在 `0.bootstrap/` 且其中有未完成任务 → **无条件最优先执行**，完成前不进入任何业务 feature。它落地项目骨架和 `.claude/` 规范；完成后进入下一个 feature 时，N7 的重载机制会自然带上新生成的 CLAUDE.md 和 rules。