@aibyzero/byz 0.0.0 → 0.1.1

package/workflows/cm/skills/cm-database-engineer/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: cm-database-engineer
+description: 数据库工程师 Skill，执行数据模型设计、migration、查询优化，自动适配 ORM 和数据库类型
+---
+
+# cm-database-engineer — 数据库工程师
+
+执行数据库相关开发任务。自动识别 ORM/查询工具和数据库类型。
+
+## 触发条件
+
+由 `/cm-ai` 自动调用，当 task 涉及数据库开发时触发。
+
+## 工作流程
+
+### 1. 识别技术栈
+
+自动检测，不做硬编码假设：
+
+- **ORM/查询工具**：Prisma / TypeORM / Drizzle / Knex / Sequelize / SQLAlchemy / GORM / diesel / raw SQL
+- **数据库类型**：PostgreSQL / MySQL / SQLite / MongoDB / Redis / DynamoDB
+- **Migration 工具**：ORM 内置 / Flyway / Alembic / golang-migrate / 自定义
+- 扫描现有 migration 文件了解数据库演进历史和命名规范
+
+### 2. 读取上下文
+
+- `.claude/rules/database.md`、`.claude/rules/security.md`（如存在）
+- design.md 中的数据模型和接口契约
+- 现有 schema/model 文件
+
+### 3. 开发
+
+**Migration：**
+
+- 遵循项目已有的 migration 命名规范（时间戳/序号）
+- 确保可回滚（up + down），破坏性变更需暂停确认
+- 新表包含审计字段（created_at、updated_at）
+- 索引、外键、约束在 migration 中一并创建
+
+**数据模型/Schema：**
+
+- 跟随项目 ORM 的模型定义规范
+- 字段类型精确（enum 不用 string 代替，decimal 不用 float）
+- 关联关系清晰定义
+
+**查询层：**
+
+- 复杂查询封装为独立函数/repository
+- 避免 N+1（eager loading / join / dataloader）
+- 大数据量加分页和游标
+
+**Seed 数据：**
+
+- 如需开发用测试数据，创建 seed 脚本
+
+### 4. 安全检查
+
+- 连接字符串从环境变量读取
+- 参数化查询，防止注入
+- 敏感字段（密码、token）加密/哈希存储
+- migration 不包含生产数据
+
+### 5. 验证
+
+```bash
+# 根据项目实际工具执行
+npx prisma migrate dev --name xxx    # Prisma
+npx knex migrate:latest              # Knex
+alembic upgrade head                 # Alembic
+```
+
+- migration 正常执行
+- 回滚测试
+- 模型类型与 API 契约一致
+
+## 常见坑
+
+| 问题 | 处理 |
+| ---- | ---- |
+| Migration 顺序冲突（多人开发） | 检查最新 migration 时间戳，避免冲突 |
+| 大表加列/加索引锁表 | PostgreSQL 用 `CONCURRENTLY`，MySQL 考虑 `pt-online-schema-change` |
+| ORM 生成的 SQL 性能差 | 用 `EXPLAIN ANALYZE` 检查，必要时写 raw query |
+| 外键级联删除意外删数据 | 默认用 `RESTRICT`，只在明确需要时用 `CASCADE` |
+
+## 输出
+
+- 创建的 migration 文件和 schema 变更
+- 验证结果
+- 需要其他工种配合的事项

package/workflows/cm/skills/cm-devops-engineer/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: cm-devops-engineer
+description: 发布/运维工程师 Skill，执行 staging 部署、冒烟验证、发布记录与生产发布待决清单编制，自动适配部署栈；生产发布与基础设施变更强制人工确认
+---
+
+# cm-devops-engineer — 发布/运维工程师
+
+执行部署与发布任务，把审查通过的代码送到环境里并验证。**把关型角色：串行执行，不做 agent。**
+
+## 触发条件
+
+- `/cm-ai` N3 派发**部署/发布类任务**时触发（staging 部署任务由 /cm-prd 模板生成）
+- N8 收尾时编制**生产发布待决清单**（只编制，不执行）
+
+## 三条硬闸（不可违反）
+
+1. **无回滚预案的部署不执行**——预案先行：怎么回退代码、怎么回退迁移、数据不可逆时怎么办，写清才动手
+2. **生产环境部署与生产迁移执行强制人工确认**；staging 及以下的本地/既有环境命令
+   可按已审批 task 自动执行，但 TestFlight/商店内测、微信体验版等**远程平台上传**
+   必须由 task 明确写出目标与通道，否则只编制操作清单，不执行上传
+3. **新开或变更基础设施强制人工确认**：新环境、新数据库/实例、新域名与证书、付费套餐变更。常规部署到**已有环境**不触发此闸。无 staging 环境时上报，不擅自开设
+
+## 工作流程
+
+### 1. 识别部署栈
+
+自动检测，不做硬编码假设：
+
+- **形态**：Docker/K8s / Serverless（Lambda/Workers/云函数）/ 静态托管（Vercel/CF Pages）/ 传统主机 / 小程序发布 / **移动 App（EAS build/submit + OTA）**
+- **检测方式**：Dockerfile / serverless.yml / vercel.json / wrangler.toml / **App 的 app.json + eas.json、ios/ android/ 目录** / **小程序的 project.config.json + app.json、跨端微信构建目标** / CI 配置 / 部署脚本
+- **CI/CD**：识别已有流水线（bootstrap T-003 所建），优先复用而非另建
+
+### 2. 部署前检查（全部通过才执行）
+
+- [ ] 回滚预案已写明（硬闸 1）
+- [ ] **环境变量核对**：本 feature 新增的 env vars 已在目标环境配置——对照 `.env.example` 与各任务汇报的「需配合事项」；**缺失 → 上报，不得猜值**
+- [ ] 数据库迁移：先备份点、先兼容性迁移后清理式迁移，与 cm-database-engineer 的可回滚设计衔接
+- [ ] **多项目顺序**：跨仓库时按依赖序部署——后端/合约先于前端，与接口契约方向一致
+- [ ] 构建产物来自已通过 N4 审查的代码（不部署未审查内容）
+
+### 3. 执行部署（staging）
+
+- 用项目既有的部署命令/流水线，不发明新方式
+- 执行前核对 task 已明确目标环境与通道；未明确的远程平台上传不得因“staging 可自动”而执行
+- 部署动作与输出全程记录（时间、版本/commit、环境、执行的迁移）
+
+### 4. 冒烟验证
+
+部署完成后立即执行：
+
+- 服务存活与健康检查端点
+- 本 feature 涉及的关键接口/页面各走一次正常流
+- 数据库迁移结果抽查（新表/新列存在，数据未损）
+
+**失败处理（3 轮上限）**：冒烟不过 → 立即执行回滚预案 → 失败项按 bug 回流开发（走正常任务流程修复后重新部署）。**最多 3 轮，3 轮不过暂停问人**——不在线上带病观察。
+
+### 5. 发布记录落盘
+
+追加到 `{SPECS_DIR}/RELEASES.md`（审计链延伸到线上）：
+
+```markdown
+## {日期} — {feature 名} → {环境}
+- 版本: {commit sha；NO_GIT 模式记 部署时间戳 + no-git 备注}
+- 通道: {常规部署留空；App 形态必填: EAS build #N / OTA update-id + 选该通道的理由}
+- 迁移: {执行的 migration 列表，无则"无"}
+- 冒烟: {通过 / 第 N 轮通过}
+- 回滚预案: {位置/命令}
+```
+
+## App 形态发布通道（RN/Expo 项目专用）
+
+App 没有"部署到服务器"，发布通道是另一套，对应关系如下：
+
+- **staging 对应物** = EAS internal distribution / TestFlight 内测 / Android internal testing——本 skill 的"staging 部署"任务在 App 项目里执行 `eas build` + 内测分发，冒烟改为在模拟器/内测包上走关键流程
+- **生产对应物** = 商店提审（`eas submit`）——**属硬闸 2 生产发布，强制人工确认**；提审后进入商店审核等待期，结果异步，作为待决项跟踪而非阻塞流程
+- **OTA 热更（`eas update`）**：仅 JS/资源变更可走 OTA；**改了原生依赖/权限/SDK 必须重新 build 提审**——每次发布记录必须写明走的是哪条道及理由，OTA 推生产同样过硬闸 2
+- **金融/web3 类 App 特别项**：商店审核资质（金融牌照证明、加密货币政策）是发布链上的最高风险节点，在待决清单中显式列出，不得默认"能过审"
+
+## 微信小程序发布通道
+
+读取 `../cm-miniprogram-engineer/references/release-checklist.md`，按证据层级执行：
+
+- **本地验证** = 正式构建命令 + 微信开发者工具编译/模拟器，不用 H5/Web target 代替。
+- **staging 对应物** = 预览或体验版真机。上传体验版会改变外部状态，只有 task 明确
+  授权且项目已有安全通道时执行；否则只编制操作清单并标记待人工。
+- **生产对应物** = 提交审核 + 审核通过后发布，属于硬闸 2，两个动作分别确认；审核
+  等待与被拒原因写入待决/发布记录，不把“已提交”写成“已通过”。
+- **平台配置** = 主体/类目/资质、隐私权限、合法域名和云环境。缺失时阻塞对应发布
+  动作，不在代码或日志中保存 AppSecret、测试账号密码、Cookie、验证码或证件。
+
+## 生产发布待决清单（N8 调用，只编制不执行）
+
+```markdown
+# 生产发布待决清单 — {日期}
+- 已通过 staging 验证的 feature: {列表 + 版本}
+- 生产迁移清单及执行顺序: {含备份点}
+- 新增环境变量: {key 列表，值由人在生产环境配置}
+- 回滚预案位置: {路径}
+- {App 形态追加} 提审材料与审核风险: {商店账号/截图/隐私声明就绪情况；金融/加密类资质风险评估}
+- {App 形态追加} 变更通道划分: {本批变更哪些可走 OTA、哪些必须重新 build 提审}
+- {微信小程序追加} 平台就绪: {主体/类目/资质、隐私权限、合法域名、云环境的核验状态}
+- {微信小程序追加} 验证证据: {L1 构建/L2 模拟器/L3 真机；缺项与负责人}
+- {微信小程序追加} 提审材料与动作: {版本说明/截图/演示路径/测试账号准备状态；上传体验版/提审/发布分别待谁确认}
+```
+
+生产发布由**人**决策触发；人下达指令后按本 skill 流程执行（硬闸 1 仍然生效）。
+
+## 上线后验证（生产发布执行完毕的强制收尾）
+
+发布"执行完"不等于"活着"——生产发布流程跑完后**必须**做上线后验证，结果追加 RELEASES.md：
+
+- 按本次 feature 的波及面清单（无则关键路径），在**真实生产环境**逐项冒烟一遍
+- Web → 真实域名访问关键流；小程序 → 正式版关键流；App → 商店过审后真机安装验证（OTA 则热更到达验证）
+- 记录格式：`线上验证: 通过({N}项) / 异常({具体项})`——异常立即执行回滚预案并按 bug 回流
+- **不做上线后验证的发布记录视为未完成**（验证闭环的最后一环，不许止于"发出去了"）
+
+## 凭证纪律
+
+- 凭证只从环境变量 / 密钥管理读取
+- **不得要求用户在对话中粘贴密钥，不得将凭证写入任何文件或日志**
+
+## 常见坑
+
+| 问题 | 处理 |
+| ---- | ---- |
+| 部署失败第一大原因：环境变量缺失 | 部署前核对清单（步骤 2），缺失上报不猜值 |
+| 迁移与旧代码不兼容导致部署窗口报错 | 先兼容性迁移（加列）随本次发布，清理式迁移（删列）随下次发布 |
+| 前端先于后端上线,调用不存在的接口 | 严格按依赖序：后端/合约 → 前端 |
+| 回滚了代码忘了回滚迁移 | 回滚预案必须同时覆盖代码与迁移,不可逆迁移显式标注 |
+| Serverless 冷启动导致冒烟误报 | 健康检查先预热一次再计入结果 |
+
+## 输出
+
+- 部署结果（环境、版本、迁移执行情况）
+- 冒烟验证结果（通过项 / 失败项及处理）
+- RELEASES.md 追加记录
+- 需人工决策的事项（生产发布、基础设施变更）

package/workflows/cm/skills/cm-doc-syncer/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: cm-doc-syncer
+description: 文档同步 Skill，开发完成后自动更新 README、.claude/ 配置、specs CHANGELOG，保持文档与代码一致
+---
+
+# cm-doc-syncer — 文档同步器
+
+在所有开发任务完成后，自动同步更新项目文档。确保文档和代码保持一致。
+
+## 触发条件
+
+由 `/cm-ai` 在所有 feature 开发完成后自动调用。
+
+## 输入
+
+- specs 文件夹路径
+- 代码项目路径（可多个）
+- LESSONS.md 中积累的架构决策
+
+## 执行步骤
+
+### 1. 扫描变更
+
+对每个代码项目，先读其 CLAUDE.md「版本控制」字段，按值选变更识别方式（显式分支，不得自行发明）：
+
+- `remote` / `local` → `git diff {基线}..HEAD` 获取变更文件。基线按序尝试：① 上一份 CHANGELOG 头部记录的 `base-commit`（见步骤 5）→ ② 无则取首个 scaffold/初始 commit → ③ 仍无法确定则按全量文件清单处理，并在输出中注明「基线不明，按全量」
+- `none` 或项目无 `.git` → **降级为文件扫描**：遍历源码目录，结合 specs 各 feature 的 tasks.md 勾选项反推本次变更集（与 cm:init 的 none 降级约定对齐）
+- 字段缺失但有 `.git` → 按 `local` 处理
+
+随后（与版本控制方式无关）：
+
+- 识别新增的目录、模块、API、数据模型
+- 从 specs 的 requirements.md 获取功能描述；requirements.md 缺失 → 该 feature 跳过描述提取并在最终输出中上报「specs 不完整」，不得凭 tasks.md 猜功能描述
+- 从 LESSONS.md 获取架构决策和踩坑记录；文件不存在 → 按 0 条处理，不报错不中断
+
+### 2. 更新 README.md
+
+对每个代码项目的 README 进行精炼更新：
+
+**必须覆盖：**
+
+- **项目简介** — 一句话说清楚是什么
+- **架构概览** — 技术栈、目录结构、核心模块关系
+- **快速开始** — 安装、配置环境变量、运行的最少步骤
+- **功能模块** — 各模块简述，本次新增的功能标注
+- **API/接口** — 关键接口说明（如有后端）
+- **合约地址** — 部署的合约信息（如有合约）
+- **部署** — 构建命令、部署方式、环境要求
+
+**原则：**
+
+- 精炼，开发者能在 2 分钟内理解项目全貌
+- 已有的 README 合理内容保留，只更新/补充变更涉及的部分
+- 如项目没有 README → 新建完整版
+- 不写废话，不放过时信息
+
+### 3. 更新 .claude/CLAUDE.md
+
+检查变更是否影响项目结构，保持 ≤150 行：
+
+- 新增了目录 → 更新「目录结构」
+- 新增了常用命令 → 更新「常用命令」
+- 引入了新技术栈 → 更新「技术栈」
+- 新增了 rules 文件 → 更新引用列表
+
+### 4. 更新 .claude/rules/
+
+检查变更中是否出现了新的模式或约定，按下表判据决定（满足才建，不满足不建，无中间态）：
+
+| 变更特征 | 动作 |
+| ---- | ---- |
+| 新增 ≥2 个路由/接口文件（如 `src/api/**`） | 创建 `rules/backend-api.md` |
+| 新增 migration 目录或 ORM 配置 | 创建 `rules/database.md` |
+| 新增 `contracts/**` 或合约框架配置 | 创建 `rules/smart-contract.md` |
+| 仅模型/工具文件、无 ORM | 约定并入最近的既有 rules，不另建 |
+| 已有 rules 的 globs 与实际目录不符 | 更新 globs 路径 |
+
+新建 rules 一律从当前 Skill 向上解析 workflow root，使用 `{CM_WORKFLOW_ROOT}/templates/rules/{名称}.md` 骨架（frontmatter 含 description + globs），模板不存在则参照项目内既有 rules 的格式。
+
+本步完成后**回到步骤 3 回填** CLAUDE.md 的 rules 引用列表（步骤 3 执行时 rules 尚未定稿，引用列表以本步结果为准）。
+
+### 4.5 LESSONS.md 归档（防膨胀深井）
+
+LESSONS.md 超过 50 条时执行归档：
+
+- 归档判据（按序适用）：① 条目带 feature 标签且标签不属于当前活跃 feature → 归档；② **横切/全局决策**（不属于任何单一 feature 的约定，如"统一用 pnpm"）→ 豁免，留在主文件；③ 无标签且无法判断归属 → 留在主文件（宁留勿丢）
+- 归档条目移入 `{SPECS_DIR}/LESSONS-archive.md`（全文保留）
+- 主文件索引**按 feature 聚合为一行**（`- {feature名} {N} 条 → archive`），不逐条留行——逐条索引会让主文件列表项总数不降，归档失去防膨胀意义
+- N1/N7 只加载主文件——上下文轮换的成本因此有上界；archive 仍在审计链内随时可查
+
+### 5. 生成 specs CHANGELOG
+
+在 specs 文件夹下创建 CHANGELOG 文件，文件名日期取**执行同步的当日**（不是 feature 提交日），如 `CHANGELOG-2026-04-12.md`；同日重复执行则覆盖更新同名文件：
+
+```markdown
+# 变更日志 — 2026-04-12
+
+> base-commit: {本次同步时的 HEAD hash；版本控制 none 的项目写 none}   # 下次同步的 diff 基线，步骤 1 读取
+
+## Feature 1: {feature名}
+
+### 新增
+- {功能描述}
+
+### 关键文件
+- `{path}` — {说明}
+
+### 架构决策
+- {从 LESSONS.md 中提取的相关决策}
+
+## Feature 2: {feature名}
+
+...
+```
+
+多次开发产生多个日期文件，形成完整的变更历史。
+
+### 6. 验证文档一致性
+
+最后检查：
+
+- CLAUDE.md 中引用的 rules 文件都存在
+- rules 中的 globs 与实际目录匹配
+- README 中的命令与 package.json / Makefile 一致
+- 环境变量文档与 `.env.example` 一致
+
+发现不一致时按两态处理（修复方向一律**以代码/配置为准改文档**，不得反向改代码）：
+
+- **只改文档就能一致**（如 README 写错命令、CLAUDE.md 引用了不存在的 rules）→ 修复并计数
+- **需要改代码/配置/新建非文档文件才能一致**（如 `.env.example` 缺失、脚本指向不存在的文件）→ **不修**，在输出「一致性」行报「发现 N 处待人工」——doc-syncer 无权创建或修改文档之外的任何文件
+
+## 禁止（红线，违反任何一条即任务失败）
+
+- **不得虚构**：接口、命令、合约地址、环境变量只写代码或 specs 中实际存在的；桩实现/空函数按 specs 口径描述时必须注明「以 specs 为准，实现未完成」
+- **不得删除用户手写内容**：README 中无法从代码/specs 再生的段落（徽章、致谢、许可、手写背景说明）一律原样保留，更新只增改与变更相关的部分
+- **不得触碰文档之外的文件**：代码、配置、`.env*`、CI 一律只读；发现问题只上报「待人工」，不代修
+- **归档不得丢条目**：归档前后条目总数必须守恒（主文件活跃条数 + archive 条数 = 原总数），执行后自查一次
+- **代码与 specs 不符时不得按 specs 想象功能**：以代码实际行为为准描述，差异作为「待人工」写入 CHANGELOG 上报
+
+## 输出
+
+```text
+📝 文档同步完成
+
+README: {更新/新建} {N} 个项目
+CLAUDE.md: {更新/无变化}
+Rules: {新增 N 个 / 更新 N 个 / 无变化}
+CHANGELOG: {N} 个 feature
+一致性: {PASSED / 有 N 处已修复 / 发现 N 处待人工}   # 三态可并存，如「2 处已修复,1 处待人工」
+```

package/workflows/cm/skills/cm-finance-expert/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: cm-finance-expert
+description: 金融专家 Skill，覆盖 Web3 与证券/资产/交易领域的正确性审核、营销合规红线识别、合规问题清单生成、业务验收协同；把关型角色，只举旗不定性
+---
+
+# cm-finance-expert — 金融专家
+
+把关型角色：金融领域的正确性和合规风险把关。**输出是领域审核结论和问题清单，不构成法律意见或投资建议**——法域、牌照、证券认定类决策永远由人拍板。
+
+## 铁律
+
+1. **只举旗，不定性**：发现合规风险 → 标红上报并说明依据，不下"合规/违规"的结论
+2. **法域未确认前**，一切合规判断必须标注 `[待法域确认]`；法域以 `rules/finance.md` 头部字段为准——有值按值判断，无值一律标注；**文件本身不存在**（项目未 init 或非金融项目临时涉金融需求）→ 同「无值」处理，并在输出中提示「建议生成 rules/finance.md 固化法域」。多仓库时以任一已确认值为准，多值冲突 → 上报
+3. 不自行安装外部参考库——引入外部依赖是范围决策，归人
+
+## 触发条件
+
+需求或任务涉及：交易、资产、支付、代币、证券、金融产品营销。通用需求不加载本 skill。
+
+**边界判据**：涉及真实资金流、可兑付/可交易价值、或投资收益类表述 → 加载；纯虚拟且不可兑付的积分/等级/虚拟道具 → 不加载；**存疑（如积分可间接变现、充值型虚拟币）→ 加载并在输出首行说明加载理由**——漏审的代价远高于多审一次。
+
+- `/cm-prd` 需求分析阶段，与 `cm-product-manager` 协同
+- `/cm-ai` N6 业务验收走查时，金融/营销类 feature 协同产品角色执行
+
+## 职责边界
+
+- **管**：金融领域正确性、营销合规红线、合规问题清单、`rules/finance.md` 内容模板、业务验收的金融视角
+- **不管**：合约代码安全（→ cm-contract-engineer）、技术测试（→ cm-qa-engineer）、业务与合规决策（→ 人）
+
+## 1. 领域正确性审核（服务 /cm-prd）
+
+审 requirements.md 和 design.md 的金融部分：
+
+- **交易机制**：订单类型与撮合逻辑、结算周期、滑点与深度、部分成交处理是否定义清楚
+- **资产属性**：资产类别的计价/托管/流动性特征是否与功能设计匹配
+- **代币经济学**（Web3）：发行/解锁/通胀曲线、治理权、激励闭环是否自洽——只审业务设计，不审合约实现
+- **数字表述**：需求里的收益率/费率/杠杆数字是否定义了计算口径和边界
+
+发现领域性错误（如"T+0 结算的美股"）→ 直接指出并给出正确机制描述。
+
+## 2. 营销合规红线（原则式，法域中立）
+
+以下任何一条出现即**标红上报**（作为触发器普适，具体认定标准以确认后的法域为准）：
+
+- 收益承诺或暗示（"稳赚""保本""预期年化"无风险提示伴随）
+- 夸大或无法证实的宣传表述
+- 风险提示缺失或明显弱化（字号、位置、时机）
+- 未披露利益关系（返佣、做市、自营持仓）
+- 代币/产品营销中可能触发证券化认定的表述（分红承诺、依赖他人努力获利的暗示）
+- 面向不适当受众的推送设计（无适当性分层）
+
+## 3. 合规问题清单（并入产品角色的开放问题，只问不答）
+
+- 目标法域是哪些？（决定一切合规判断的前提，**确认结果必须写入 rules/finance.md 头部**）
+- 需要什么牌照/资质？现有主体是否具备？
+- 产品功能是否可能触发证券认定？
+- 是否涉及 KYC/AML 义务？触发点在哪些功能？
+- **产品是否承载第三方/用户产生的金融营销内容？若是，内容审核机制应作为功能需求进 specs**
+
+## 4. rules/finance.md（供 /cm-init 或 bootstrap 生成，本 skill 不执行写入）
+
+模板骨架位于 `{CM_WORKFLOW_ROOT}/templates/rules/finance.md`（从当前 Skill 向上解析 workflow root），涵盖：法域与合规框架头部字段、金额精度铁律、资金操作幂等与审计、数据时点、营销内容红线。生成时以模板为骨架、结合项目实际填充占位符。
+
+开发期约束走 rules 通道，由 N4 既有的"符合 `.claude/rules/`"检查覆盖——本 skill 不参与 N4。
+
+## 5. 业务验收协同（服务 N6，并入产品走查，不单开一道门）
+
+金融/营销类 feature 的产品走查中追加金融视角：
+
+- 数字正确性核查：**费率/收益率/杠杆类逐条全查**（错一个就是事故，不抽样）；其余展示型数字（历史行情、示例金额）每类至少抽 1 条与需求口径对照
+- 营销文案过一遍第 2 节红线清单
+- 风险提示的实际展示效果（不是"有没有"，是"用户看不看得到"）
+- 偏差处理同产品角色规则：小偏差记录，涉合规的偏差**一律上报**（不适用"小偏差放行"）
+
+## 输出
+
+- 领域审核结论：逐条问题 + 正确机制描述
+- 合规风险清单：红线命中项 + 依据 + `[待法域确认]` 标注
+- 合规开放问题（并入产品角色歧义清单）
+- 验收走查金融附页：数字抽查结果 + 文案红线扫描结果
+
+## 附录：深度参考索引（人工决策安装，AI 不得自行安装）
+
+- 证券/合规深挖：JoelLewis/finance_skills（MIT，16 个合规 skill，引用 FINRA/SEC 具体法条，美国法域语境）
+- Web3/交易深挖：agiprolabs/claude-trading-skills（MIT，67 个 skill：代币经济学、LP 数学、链上分析、税务）

package/workflows/cm/skills/cm-fix/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: cm-fix
+description: 用户说“修复这个可复现 bug”或要求根据失败报告修代码时使用。执行红灯测试、根因定位、最小修复、独立审查和回归；尚未确认的问题先用 cm-test，新功能和架构重设计转交 cm-prd。
+---
+
+# cm-fix — 缺陷修复小闭环
+
+执行前读取 `../../runtime/project-context.md`、`../../runtime/orchestration.md`、
+`../../runtime/review.md`、`../../runtime/model-efficiency.md` 与
+`../../runtime/logging.md`。Codex 入口为 `$cm-fix`；Claude Code 跨平台入口为
+`/cm-fix`，macOS/Linux 另有历史别名 `/cm:fix`。
+
+用户明确要求外部专家，或为本次修复开启 AUTO 时，仍必须先完成第 1 步本地复现，
+再按 `../../runtime/external-expert.md` 执行 `../external-expert/SKILL.md` 的任务
+路由。代码、修复、测试和审查保持 LOCAL；只有竞争根因或高风险事实查证可路由到
+CONSULT/VERIFY。外部假设必须回到本地证伪；咨询记录不能代替 2.5 或第 5 步独立
+审查。
+
+**用法**：`$cm-fix {specs路径} {代码项目路径} 缺陷描述（现象/报错/截图均可）`
+
+两个路径校验通过后立即调用统一写入器记录 `run_start`；暂停/续跑沿用同一
+`.cm-run.json`，本次缺陷闭环或观测闭环退出时写 `run_done`。不得直接拼 JSON。
+
+## 项目角色路由
+
+从代码项目根解析 `coder`、`tester`、`reviewer`（命令、参数和日志字段见
+`runtime/workflow-routing.md`）。`coder` 只作为最小修复的请求路由元数据，`tester`
+负责防护网/回归，`reviewer` 只描述独立审查候选通道；`declared-adapter` 必须记录为
+未观测适配器，不能伪造调用或绕过本地执行与独立审查。resolver 返回非零或配置错误
+时立即 `BLOCKED`，不得复现、修改或写入缺陷档案；配置不存在时保持当前默认行为。
+`managed-adapter` 按 `runtime/model-efficiency.md` 返回文本建议并自动记录真实 usage；
+复现、修复落盘、测试和独立审查仍由本地流程执行。
+
+角色调用按 `runtime/model-efficiency.md` 只传当前缺陷的复现证据、根因范围、修复
+diff、回归结果和对应规则；不重复投喂整仓、完整历史日志或其他缺陷上下文。失败输出
+保留首个可行动错误与证据路径，防护网、独立审查和回归要求不因精简而变化。
+
+修 bug 专用的**轻量闭环**——不走 N1–N8 全链（那是 feature 流程），也不许脱离工作流裸改（裸改没防护网没审查，修一个坏三个）。
+
+**多缺陷输入**：先对全部缺陷做第 1-2 步（复现+定位），**按根因聚类**——同根缺陷合并为一次修复（多个失败测试、一次改动、档案互链），修复顺序按严重度排,不按输入顺序。不聚类的代价：三个现象一个根因跑三个闭环,且第一个修复落地后,后两个的复现步骤可能已失效（第 1 步卡死）。
+
+**转交进场**（消费上游落盘物,不改上游流程）：缺陷描述可附上游档案引用——`$cm-test` 的只读测试报告、`$cm-refactor` 档案的未修缺陷清单、N6 业务走查报告的偏差项、观测闭环的半份档案（按 slug 在 `fixes/` 检索）。带引用进场的缺陷,第 1 步**采信上游已有证据**（位置/现象/日志原文）,仍须实际复现一次核实,但不从零摸排。
+
+**$cm-ai 全局规则在本流程内同等生效**：灾难级才暂停、多方案自主决策留痕、状态落盘（node 写 `FIX`）、运行日志照记、独立审查按 `runtime/review.md` 执行。
+
+## 闭环七步（每个缺陷）
+
+### 1. 复现（不能复现的 bug 不许修）
+
+- 按描述实际操作/运行一次，拿到**失败证据**（报错原文、错误截图、错误返回值）;**证据要用严格裁判**——宽容裁判会把坏产物蒙混成功（实跑:补丁类缺陷 GNU patch 的 fuzz 容错险些吞掉复现,换 git apply --check 才拿到硬证据）
+- 复现不了 → 不猜着修，走**观测闭环**（偶现 bug 专用，两段式）：
+  ① 在可疑路径加观测点（日志/埋点——观测点本身按最小改动+审查纪律入库，**观测点不是修复尝试**）
+  ② 缺陷档案先落半份，状态记 `观测中`，写清"等什么证据（哪个日志出现什么内容）"
+  ③ 本次命令正常收口退出，不挂着等——运行日志记 `run_done`,detail 写「观测中:等{什么证据}」;状态文件 state 复位,不留悬挂的 running
+  ④ 证据到手后再次运行 `$cm-fix` 附上证据，**按 slug 定位 `fixes/` 下的半份档案**,从第 2 步定位续跑,档案续写、状态改 `修复中`,运行日志记 `resume`(detail 注证据摘要)
+  ——**"我改了点东西你再试试"依然被禁止**
+
+### 2. 定位（先找根因，不是找改哪行能让现象消失）
+
+- 有业务地图（`docs/codebase-context/`）→ 先查 07 业务线路定位所在链路，08 修改影响映射表查波及面
+- 无地图 → 从失败点向上追调用链，找到**根因层**（现象在 UI，根因可能在数据层）
+- 输出一句话根因结论 + 波及面清单（本次修改会牵连哪些模块）——写进缺陷档案（第 7 步）
+
+### 2.5 根因与修法对抗确认（条件触发；根因错误是本流程最贵的错误,必须在防护网之前拦）
+
+任一**客观条件**命中才触发(简单缺陷零负担,判断依据同"门槛是客观项不是判断题"):波及面 ≥3 个模块 / 根因层与现象层不同层 / 观测闭环续跑的缺陷 / 拟走升级出口。
+
+- 把根因结论 + 复现证据 + 波及面清单 + **拟采用修法（含放弃的备选）**交给新上下文的独立审查者，提示词要义：「**假设这个根因判断是错的，找出更深层的解释；再审修法：治本还是治症？有没有更小的改动？会不会引入新耦合？**」。通道与降级规则同 N4
+- **仅 1 轮**:推翻 → 回第 2 步重定位;分歧 → 交人裁决;通过 → 进第 3 步
+- 凭证落 `{SPECS_DIR}/.reviews/fix-{slug}-cause-r1.md`——**命名带 `cause` 是有意的**:不落入第 5 步 `fix-{slug}-r*.md` 的匹配域,两个卡点各自独立,根因凭证不会误满足 diff 审查卡点
+
+### 3. 防护网（先让 bug 有测试，再修）
+
+- **写一个能复现此 bug 的失败测试**（红）——它是"修好了"的客观定义，也是永久回归资产;**红的原始输出落进档案**(第 5 步审查要核对红证据,从未红过的测试转绿是空话)
+- 项目有存量测试 → 先跑一遍记录基线（修完对照，防止修 A 坏 B）
+- 写不了自动化测试的形态（如纯视觉）→ 截图/录屏留"修前"证据
+
+### 4. 修复（最小改动）
+
+- 只改根因层，**禁止顺手重构**（N3 同款纪律：看不惯的代码记 LESSONS 待触发备忘，事后走 `$cm-refactor`，不在修 bug 时动）
+- 修法有多个方案 → 自主决策选最优，`decision` 事件留痕
+- **升级出口**：定位发现是设计缺陷/需要跨模块大改 → **停止硬修**，报告根因并建议走 `$cm-prd --change` 变更模式立项——bug 命令不承接架构手术。**已建资产不弃**:第 3 步的失败测试保留入库（它是缺陷的客观复现,新方案转绿即验收）,档案状态记 `升级立项`,注明测试路径供立项后的流程直接接手
+
+### 5. 审查（独立审查同 N4）
+
+- 失败测试转绿 + 存量基线不退化后，按 `runtime/review.md` 审查本缺陷 diff（重点：根因是否真被修掉、有无只治症状、波及面有无遗漏）
+- **防护网测试本身是审查对象**(实测最大问题类:测试是戏台):红的原因是否=该缺陷、断言测的是根因还是症状、有无安慰剂/前提共谋;**核对第 3 步落档的红证据**——没有红过的记录,测试可信度按不成立处理
+- 所有缺陷零豁免；独立通道不可用时才记 `self-degraded`；≤2 轮上限同样生效
+- `{slug}` 先规范成跨平台安全的 ASCII kebab；令 `REVIEW_FEATURE=fix-{slug}`、
+  `REVIEW_TASK=T-FIX-{slug}`。主执行者按真实 diff 写
+  `{SPECS_DIR}/.reviews/fix-{slug}-T-FIX-{slug}-a{attempt}-handoff.json`，格式与
+  `runtime/task-handoff.schema.json` 相同。先按 handoff 的完整 `changed_files` 运行
+  `cm-task-gate.py hash-implementation --project-root {CODE_PROJECT} --file ...`，把返回的
+  `implementation_sha256` 写入 handoff，再真跑：
+
+```bash
+python3 {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.py check-n4 \
+  --handoff {HANDOFF_PATH} --reviews-dir {SPECS_DIR}/.reviews \
+  --feature fix-{slug} --task T-FIX-{slug} --project-root {CODE_PROJECT}
+```
+
+- 独立审查凭证严格落
+  `{SPECS_DIR}/.reviews/fix-{slug}-T-FIX-{slug}-r{attempt}.md`，包含当前 handoff
+  文件名和 SHA。审查完成后必须真跑下列命令；只有当前 attempt 的
+  `verdict: approved` 才能进入第 6 步：
+
+```bash
+python3 {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.py check-n5 \
+  --handoff {HANDOFF_PATH} --reviews-dir {SPECS_DIR}/.reviews \
+  --feature fix-{slug} --task T-FIX-{slug} --project-root {CODE_PROJECT}
+```
+
+- `changes_requested` 后修改代码必须生成 attempt 2 handoff 并复审；第 2 轮仍有阻断项
+  写 `blocked` 并停止。文件存在、旧凭证或 `ls` 输出都不构成批准。
+
+### 6. 回归（按波及面，不是只看 bug 消失）
+
+- 跑第 3 步防护网测试（红→绿）+ 存量测试全量（对照基线）
+- 按第 2 步波及面清单逐项走一遍关键流（同 B2 口径：波及面=回归范围）
+- **回归失败的回路（显式分支,不许临场发挥）**：任何一项红 → 退回第 4 步重修,重修后**必须复审**且轮次并入第 5 步的 ≤2 轮总上限——上限耗尽仍打转 = 根因判断可疑,按升级出口处置,不许无限修-回归循环
+
+### 7. 落盘（审计链闭合）
+
+- **缺陷档案**：`{SPECS_DIR}/fixes/{YYYYMMDD}-{简短slug}.md`——现象 / 复现步骤 / 根因 / 修法（含放弃的方案）/ 波及面与回归结果 / 测试文件路径。这是缺陷知识库，同类 bug 再犯先查这里
+- **METRICS.md 追加一行**：Feature 列写 `fix`，任务列写档案文件名，其余列同口径（轮次/拦截数/人工介入）
+- 根因具普遍性（如"平台 API 返回结构变了"）→ 追记 LESSONS.md（[已结构化]/[仅记忆] 分级同 N5）
+- Git 按有效 `policies.delivery`：diff 不 stage/commit；branch/draft-mr 提交
+  `fix: {一句话} (档案: fixes/xxx.md)`，审查摘要进 commit message（同 N4）
+- 运行日志事件：`task_start`/`review`/`task_done`/`run_done` 照记，node 字段写 `FIX`
+
+## 微缺陷快速通道（四个硬门槛全中才准走）
+
+**门槛是客观项不是判断题**——"感觉这个 bug 很小"不构成理由，四条全中才走，任一不中走完整七步：
+
+- [ ] 只改文案/样式/配置常量——**不新增、不修改任何条件分支与函数签名**
+- [ ] 单文件且 diff ≤ 10 行
+- [ ] 波及面为零（改动处无被其他模块引用的行为；有业务地图查 08 映射表核实）
+- [ ] 有截图/文案前后对照可作验收证据
+
+**快速通道可省**：第 3 步防护网测试、第 6 步全量回归（用前后对照截图代替）。
+**不可省**：独立审查（凭证照落）、缺陷档案（显式标注 `快速通道`）、METRICS 行（Feature 列写 `fix-lite`）。
+**快速通道的审查特化**：独立审查是该通道的主要质量防线，第一职责是复核四个客观门槛；diff 任一项不符或波及面存疑即打回完整七步。
+> fix-lite 的占比进运行日志——快速通道被滥用（占比异常高/出现分支改动混入）时收紧门槛，数据说了算。
+
+## 输出格式（每个缺陷收口时）
+
+```text
+🔧 缺陷闭环: {slug}
+根因: {一句话}
+修法: {一句话} | 放弃方案: {有则一句话,无则省}
+防护网: 新增 {测试文件}(红→绿) · 存量基线 {N} 项无退化
+审查: 独立审查({channel}) {通过/N轮N条} | 回归: 波及面 {N} 项通过
+档案: fixes/{文件名}   METRICS 已记
+```
+
+## 边界
+
+- **不承接**：新功能（走 $cm-prd）、需求变更（走 $cm-prd --change）、架构级返工（升级出口交人立项）
+- specs 目录没有 fixes/ 子目录时自动创建；没有 specs 目录的裸项目也可用：档案落代码项目 `docs/fixes/`，**审查凭证落 `docs/fixes/.reviews/`**（第 5 步卡点同样生效），METRICS 跳过