chore(skill): 清理全部 23 条历史校验警告

- 11 个超 20KB 的 SKILL.md 拆分，大章节移入 references/details.md - 7 处非标准字段（arguments/user_invocable）移入 metadata - 修 req-dev 4 条相对链接；validate 跳过行内代码避免 ![](...) 误报 - validate-skills.py: 23 warns -> 0 warns，0 errors
2026-10-31 22:21:07 +08:00
parent 7d47762303
commit 237631147a
29 changed files with 4013 additions and 3928 deletions
@@ -0,0 +1,187 @@
+# skills 详细内容
+
+## 命令参考
+
+### 撰写命令
+
+**`/req new [标题]`** — 对话式创建需求（仅 draft）
+- 参数：`--priority=high|medium|low`，`--project=<name>`，`--category=feature|bug|improvement`
+- 流程：描述→提取关键信息→用户故事→验收标准→`ai-proj req create`→ Gate 1 需求讨论
+
+**`/req draft <描述>`** — 一句话快速创建 draft，AI 自动补全
+
+**`/req edit [REQ-ID]`** — 编辑需求：`ai-proj req get` → 询问修改点 → `ai-proj req update` → 显示变更摘要
+
+**`/req check [REQ-ID]`** — 完整性检查（Gate 4）：
+```
+✅ 三段式结构完整 / ✅ 验收标准: 4 条 / ✅ 讨论结论已记录 / ❌ PRD 文档缺失
+```
+
+**`/req split [REQ-ID]`** — 拆分为开发任务（后端/前端/测试）并关联
+
+### 原型设计
+
+**`/req prototype [REQ-ID]`** — 基于 PRD 生成 Stitch 原型：
+1. 读取 PRD 文档，提取 UI 相关描述
+2. 创建 Stitch 项目 + 生成页面（调用 req-prototype 子技能）
+3. 截图回填 PRD「4.2 界面原型」章节
+- 参数：`--device [desktop|mobile|tablet]`，`--model [pro|flash]`
+
+**`/req prototype edit [REQ-ID] --prompt "..."`** — 修改已有原型
+
+**`/req prototype variant [REQ-ID]`** — 生成设计变体供选择
+
+### 提交评审
+
+**`/req submit [REQ-ID]`** ⭐ — 从 draft 到 pending 的唯一合法路径：
+1. Gate 1: description 末尾有「## 讨论结论」
+2. Gate 2: 讨论结论经过用户确认
+3. Gate 3: 有 linkRole=prd 任务且附有文档
+4. Gate 4: 执行 `/req check` 全部通过
+5. → `ai-proj req submit --id <id>` → 展示 PRD 摘要 → 等待评审
+
+**`/req review pass [REQ-ID]`** — 评审通过（必须用户明确确认后才调用 `ai-proj req approve --id <id>`）
+
+**`/req review reject [REQ-ID] [原因]`** — 评审驳回，必须提供原因
+
+### 阶段管理
+
+**`/req` 或 `/req list`** — 按状态分组列出所有需求（`ai-proj req list`）
+
+**`/req status [REQ-ID]`** — 查看需求详情（`ai-proj req get --id <id>`）、进度、关联任务
+
+**`/req next [REQ-ID]`** — 推进到下一阶段：
+1. 检查当前阶段任务完成度
+2. 智能跳阶段检测（无 implementation 任务时建议跳过 review/testing）
+3. `ai-proj req advance --id <id> --to <stage>`（门禁检查，未通过→AskUserQuestion，**禁止 AI 自动 force**）
+4. ⭐ 内容门禁检查（review/testing/staging 阶段）
+5. 自动创建目标阶段建议任务
+6. 展示：「✅ 已创建: #XXXX {任务名}。如需撤销请说明」
+
+**dev → review 门禁**：
+- `pr_created`: PR 已创建
+- `quality_gate`: CI 质量门禁通过记录（质量门禁未通过时提示：「CI 质量门禁未通过，请先运行 `/req ci`」）
+
+**阶段顺序**：`analysis → design → dev → review → testing → [待部署池] → released`
+
+**`/req resume [REQ-ID]`** — 会话断点恢复：`ai-proj req get --id <id>` 获取 delivery_stage + 任务状态 + 建议操作
+
+### 开发命令
+
+**`/req dev [REQ-ID]`** — 启动开发：
+1. `ai-proj req tasks --id <id>` 找 implementation 任务
+2. `ai-proj task start --id <task_id>` 更新任务状态为开发中
+3. `/pr start` 从 origin/main 建分支
+
+**`/req cr [REQ-ID]`** — 代码评审（前置：开发任务完成）：
+1. `ai-proj req tasks --id <id>` 确认所有 implementation 任务已完成
+2. `git diff` / `find` 确定变更范围（文件数、行数）
+3. 读取所有变更文件源码（非 test 文件）
+4. **五视角扫描**：逐一用攻击者/泄露者/并发者/边界者/依赖者视角审查
+5. **约定检查**：运行所有 `scripts/check-*.sh --ci`，将结果写入 CR 报告
+6. **⭐ Bug 约定建议**（bug 类需求自动触发：category=bug，或标题含 fix/修复/bug，或描述含根因/复现步骤）：
+   - 分析本次 bug 的根因模式
+   - 判断可检测性：能写 grep 找到同类问题？（规则见 convention-flow.md「可检测性判断」）
+     - 不可检测 → 仅在 CR 报告记录根因，跳过
+     - 可检测 → 检查已有 `scripts/check-*.sh` 是否已覆盖 → 已覆盖则跳过
+   - 扫描代码库统计同类模式数量 N
+   - AskUserQuestion（N=0: 防未来复发；N>0: 防恶化+逐步清理）
+   - 是 → 执行 convention flow → 产出物**单独 commit**（`chore: 建立 {name} 约定`）
+7. `ai-proj task create` 创建【代码评审】任务并关联需求（linkRole=code_review）
+8. `ai-proj create-and-attach` 附加 CR 报告文档（必须含五视角扫描结果 + 约定检查结果）
+9. 展示发现摘要，AskUserQuestion 确认是否创建 bug 修复任务
+10. 若有 High/Critical 发现 → `ai-proj task create` 创建关联修复任务
+
+**`/req ci [REQ-ID]`** — CI 质量门禁检查与自动修复：
+1. `check-ci-status.sh` 检查当前分支 CI 状态
+   - 通过 → 写入 `quality_gate` 门禁证据（`gate-callback.sh`）→ 完成
+   - 运行中 → `--wait` 等待最多 5 分钟
+   - 失败 → 进入自动修复循环
+2. 自动修复循环（最多 3 轮）：
+   a. `fetch-ci-logs.sh --failed-only` 获取失败 job 日志
+   b. AI 诊断根因（见错误模式目录）
+   c. 自动修复代码
+   d. 本地验证（`go vet ./...` / `npx tsc --noEmit`）
+   e. `git commit && git push`
+   f. `check-ci-status.sh --trigger --wait` 等待新 CI
+   g. 通过 → 写入门禁证据 → 完成
+   h. 仍失败 → 下一轮（超过 3 轮 → AskUserQuestion 是否继续）
+- 参数：`--trigger` 手动触发 CI，`--wait` 等待完成，`--no-fix` 仅诊断不修复
+
+**错误模式目录**：
+
+| 失败 Job | 错误模式 | 修复策略 |
+|----------|---------|---------|
+| architecture-gate | 架构 ratchet 违规 | 读取违规文件，用 service 层替代直接 database import |
+| backend-lint (go vet) | `file.go:42: unreachable code` | 读取文件，修复具体问题 |
+| backend-lint (gofmt) | `Files need gofmt:` | 运行 `gofmt -s -w` |
+| backend-lint (go test) | `--- FAIL: TestXxx` | 读取测试和实现，修复根因 |
+| frontend-lint (ESLint) | `warnings N > 4600` | 对比 main，只修复新增警告 |
+| frontend-lint (Prettier) | `unformatted N > 1000` | `npx prettier --write` 变更文件 |
+| frontend-lint (TS) | `errors N > 60` | 对比 main，只修复新增类型错误 |
+
+**`/req test [REQ-ID]`** — 测试（前置：代码评审通过），遵循 dev-test 技能的 5-Gate 流程
+
+**`/req deploy [--project <name>] [--env production]`** — 项目级批量部署（Staging 已自动化，push develop 即触发）：
+1. 收集待部署需求（delivery_stage=testing + 全 test 任务 completed）
+2. AskUserQuestion 确认范围
+3. `ai-proj task create` 创建【部署】批次任务（linkRole=deploy）
+4. 部署前检查（变更检测、数据库迁移）
+5. 执行 `./scripts/build-and-push.sh prod --detect --deploy --wait --verify`
+6. **Deploy Gate 1: 健康检查** — `/health` 返回 200
+7. **Deploy Gate 2+3: PDV 验收**（为每个需求创建独立验收任务）：
+   a. `ai-proj task create --title "【验收】PDV: {需求标题}"` 创建验收任务
+   b. `ai-proj req link --id <req_id> --task-ids <task_id> --link-role verification` 关联需求
+   c. 从需求关联任务中提取前端变更范围（页面路由、菜单项、关键 API）
+   d. 生成验收检查清单（页面可达 + 菜单可见 + 基础渲染 + API 连通）
+   e. 用 Playwright 对部署环境执行冒烟测试：`E2E_BASE_URL=<部署环境URL> npx playwright test e2e/pdv/ --project=chromium`
+   f. 收集截图证据
+   g. `ai-proj task append-doc --id <task_id>` 附加验收文档（检查项表格 + 截图 + 结论）
+   h. **全部通过** → `ai-proj task complete --id <task_id>` → Gate 2+3 放行
+   i. **任一失败** → 任务保持 in_progress，**阻断推进**，报告失败项
+8. `ai-proj task append-doc` 记录【部署】任务文档（构建日志 + 健康检查 + PDV 结果摘要）
+9. `ai-proj req advance --id <id> --to released` 批量推进（仅 Gate 1-3 全部通过的需求）
+
+**`/req done [REQ-ID]`** — 类型化归档门禁 + git commit + push + `ai-proj req archive --id <id>`：
+
+**Gate 0（强制）：AC 验收逐条确认** — 在所有类型检查之前执行：
+1. `ai-proj req get --id <id>` 获取需求描述
+2. 提取 `## 验收标准` 章节下的所有 `- [ ]` / `- [x]` 条目
+3. **无验收标准**：AskUserQuestion 警告并要求用户确认为何无 AC，必须说明跳过原因才能继续
+4. **有未勾选项（`- [ ]`）**：逐条列出，AskUserQuestion 请用户对每条提供验证证据（截图/curl 输出/日志）或明确标记为 N/A + 说明原因
+5. **全部已勾选（`- [x]`）**：展示 AC 摘要，直接继续
+6. AC 确认通过后，将每条 AC 的验证结果追加到需求描述（`ai-proj req update`），格式：`- [x] {原AC内容}（验证于 YYYY-MM-DD）`
+
+**类型检查（Gate 0 通过后）**：
+- **推断类型**：有 implementation → code；无 implementation 有 prd/test → skill；仅 deploy → ops
+- **code 检查**：delivery_stage=released + deploy 任务完成 + verification 任务完成（PDV 通过） + 部署文档 + 所有任务完成
+- **skill 检查**：delivery_stage≥testing + 所有任务完成
+- **ops 检查**：deploy 任务完成 + 所有任务完成
+
+### PRD 文档创建（通过任务中转）
+
+```bash
+# create-and-attach 只支持任务 ID（task_documents 外键约束）
+# 1. 创建任务
+ai-proj task create --title "【评审】PRD: 用户认证功能"
+
+# 2. 关联需求
+ai-proj req link --id 711 --task-ids 5214
+
+# 3. 附加文档到任务
+ai-proj task append-doc --id 5214 --content "# PRD: 用户认证功能\n..."
+```
+
+### 阶段任务 Checklist
+
+| 阶段 | 建议任务 | linkRole |
+|------|----------|----------|
+| analysis | 【评审】PRD: {需求标题} | prd |
+| design | 【评审】技术设计: {需求标题} | design |
+| dev | 【开发-后端】{需求标题}、【开发-前端】{需求标题} | implementation |
+| review | 【代码评审】{需求标题} | code_review |
+| review | 【约定】{约定名称}（bug 类需求，convention flow 自动创建） | documentation |
+| testing | 【测试】集成测试: {需求标题} | test |
+| deploy | 由 `/req deploy` 批量创建 | deploy |
+| released | 【验收】PDV: {需求标题}（`/req deploy` 自动创建） | verification |
+