pipexerp/ai-proj-helper
8
0
Fork 0
Code Issues Pull Requests 3 Actions 2 Packages Projects Releases Wiki Activity
Files
b390c29af3fbe062f2aa4868b9233ac7c1e47d1b
ai-proj-helper/skills-req/req-plugin/skills/references/details.md
T
johnQ 237631147a 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

10 KiB
Raw Blame History

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 文档创建（通过任务中转）

# 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
Reference in New Issue View Git Blame Copy Permalink