ai-proj-helper/skills-req/req-plugin/skills/SKILL.md

name, description, arguments

name	description	arguments
req	需求工作流管理。用于 /req 命令使用、需求全生命周期管理（创建→PRD→评审→开发→测试→部署→归档）。当用户提到需求管理、/req 命令、REQ-XXX 相关任务时自动激活。	<subcommand> [args]

req - 需求工作流管理

需求全流程工作流管理，与 ai-proj CLI 深度集成。

需求生命周期

审批状态（status）：

draft ──[讨论]──► draft(已讨论) ──[PRD]──► pending ──[pass]──► approved ──► archived
          │                                    │
      与 AI 讨论                           [reject]
      明确方案                                 ▼
                                           rejected

开发阶段（delivery_stage，approved 后启用）：

analysis → design → dev → review → testing → [待部署池] → released
  评审       评审    开发   代码评审   测试    等待批量部署   已上线

部署模型：各需求独立走到 testing → 进入待部署池；/req deploy 一次构建批量推进到 released。

⭐ 关键约束

• 需求创建后，必须与 AI 进行一次需求讨论，明确方案后再编写 PRD
• 讨论结束后必须输出方案确认摘要（强制流程：讨论 → 摘要 → 用户确认 → PRD）：
  1. AI 输出结构化摘要（## 讨论结论 章节），ai-proj req update 追加到 description 末尾
  2. AskUserQuestion 确认：「方案确认通过」或「需要修改」
  3. 用户确认后才能开始 PRD 编写，禁止跳过确认
• 需求描述三段式（技术方案写入 PRD，不写在需求中）：
  1. 需求描述 — 问题背景、现状痛点
  2. 预期结果 — 期望达到的效果
  3. 验收标准 — 可检查的完成条件（checklist，≥2 条）
• PRD 文档是提交评审的前置条件；代码评审是测试的前置条件
• force=true 禁止自动使用 — 门禁未通过时必须 AskUserQuestion 确认 + 记录跳过原因
• 评审必须用户确认 — 禁止 AI 自审批
• 归档前门禁检查 — /req done 按需求类型（code/skill/ops）动态检查
• 部署是项目级动作，由 /req deploy 统一触发
• 需求完成后必须 git 提交并 push — commit 格式：feat(skill): REQ-XXXX 需求标题
• 操作前先确认实际 ID — 从 URL 提取 ID（如 /requirements/897 → ID=897）
• 务实路线关闭也必须补全关联任务 — 每个进度条阶段需创建关联任务
• 阶段内容门禁（防空转） — /req next 时检查关键阶段任务是否有实质内容

禁止直接调用（必须走命令流程）

禁止直接调用	必须通过	原因
ai-proj req create with allowSelfApprove	/req new	禁止自动提交，必须创建为 draft
ai-proj req submit (直接调用)	/req submit	必须先通过 4 道门禁检查
ai-proj req archive	/req done	必须先执行类型化门禁检查
ai-proj req approve	/req review pass	必须先展示 PRD 摘要并等待用户确认
ai-proj req advance --to <stage> (force)	/req next	必须先 AskUserQuestion 确认 + 记录跳过原因

需求创建强制规则

# ✅ 正确：传完整业务字段
ai-proj req create \
  --title "需求标题" \
  --description "## 需求描述\n...\n## 预期结果\n...\n## 验收标准\n..." \
  --priority medium \
  --category feature \
  --due-date "2026-03-15"
# → 结果必定是 draft 状态

从 draft 到 submit 的 4 道门禁

Gate 1: 需求讨论 ── description 末尾有「## 讨论结论」章节
Gate 2: 方案确认 ── AskUserQuestion 获得「方案确认通过」
Gate 3: PRD 文档 ── linkRole=prd 的任务存在且有文档
Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD 存在

完整工作流

1.  /req new         → 创建需求 (draft)
2.  需求讨论         → 输出结论摘要，用户确认
3.  req-prd 技能     → 编写 PRD（创建【评审】PRD 任务）
4.  /req submit      → 提交评审 (pending)，含 4 道门禁
5.  /req review pass → 评审通过 (approved, delivery_stage=analysis)
6.  /req next        → 推进到 design/dev 阶段
7.  /req dev         → 启动开发（创建【开发】任务, delivery_stage=dev）
8.  /req next        → 推进到 review 阶段
9.  /req cr          → 代码评审（创建【代码评审】任务）
10. /req next        → 推进到 testing 阶段
11. /req test        → 测试验收（5-Gate 流程）
12. /req deploy      → 批量部署（DG1-DG6 Deploy Gates）
13. /req done        → 归档 (archived) + git commit + push

5 阶段文档：

阶段	文档名	技能
PRD	01-PRD.md	req-prd
测试	02-测试报告.md	自动生成
发布	03-发布记录.md	自动生成
归档	04-生命周期总结.md	自动生成

任务命名规范

linkRole	前缀	示例
prd	【评审】	【评审】PRD: 用户认证功能
design	【评审】	【评审】技术设计: 数据模型
implementation	【开发】	【开发-后端】实现 API
code_review	【代码评审】	【代码评审】CR: 代码审查
test	【测试】	【测试】集成测试验证
deploy	【部署】	【部署】部署到 staging
documentation	【文档】	【文档】API 文档更新

阶段内容门禁（防空转）

/req next 推进时，对关键阶段检查任务是否有实质内容（文档附件）：

离开阶段	检查标准
review	CR 任务有文档，字数 ≥ 500，含 file:line 代码引用，含五视角扫描结果，含结论章节
testing	测试任务有文档，含测试结果表格，含通过/失败结论
staging	部署任务有文档，含健康检查结果

未通过 → AskUserQuestion（补充文档 or 强制跳过+记录原因）

CR 五视角扫描法

核心原则：实现阶段关注"怎么让它跑通"，评审阶段关注"怎么让它出错"。AI 必须切换到对抗性思维，逐一用以下 5 个视角扫描代码。

视角	思维模式	扫描问题
1. 攻击者	"我怎么绕过/滥用它？"	跨租户数据泄露、越权访问、参数注入、重放攻击
2. 泄露者	"它暴露了什么不该暴露的？"	错误消息泄露信息、日志记录敏感数据、响应包含内部细节
3. 并发者	"两个请求同时来会怎样？"	竞态条件、双重扣款、幂等性缺失、锁粒度
4. 边界者	"极端输入会怎样？"	空值/零值/负值/超长字符串、类型溢出、分页越界
5. 依赖者	"外部服务挂了会怎样？"	超时处理、重试策略、降级方案、连接泄露

每个视角的具体扫描清单：

视角1: 攻击者（多租户安全）

• 所有 Store 层查询是否带 tenant_id 过滤？（特别是通过 ID 直接查询的方法）
• 用户只能操作自己的数据？（consumer_id 校验）
• URL/请求参数是否有注入风险？（SQL、URL、命令注入）
• 外部输入是否直接拼接到查询/URL？（应使用参数化查询或编码）

视角2: 泄露者（信息安全）

• 错误消息是否泄露业务状态？（如"手机号未注册"暴露用户存在性）
• 日志是否打印了密码、token、密钥？
• 响应是否包含不必要的内部字段？（如内部 ID、数据库字段名）

视角3: 并发者（数据一致性）

• 涉及金额变更是否使用事务 + 悲观锁？
• 关键操作是否有幂等保护？（bizNo 唯一索引）
• 全局状态（如进程内计数器）重启后是否安全？

视角4: 边界者（健壮性）

• 必填参数是否有 binding:"required" 校验？
• 数值参数是否有范围校验？（min/max）
• 分页参数是否有默认值和上限？

视角5: 依赖者（可靠性）

• HTTP 客户端是否设置超时？
• 外部 API 调用失败是否有合理的错误处理？
• token 类型是否可区分？（access vs refresh 不同过期策略）

CR 报告模板

## 代码评审报告 - {需求标题}
日期: YYYY-MM-DD
评审范围: {N} 个文件, {M} 行变更

### 变更概要
{1-3 句描述}

### 五视角扫描结果

#### 1. 攻击者视角
{扫描发现，或 "未发现问题"}

#### 2. 泄露者视角
{扫描发现，或 "未发现问题"}

#### 3. 并发者视角
{扫描发现，或 "未发现问题"}

#### 4. 边界者视角
{扫描发现，或 "未发现问题"}

#### 5. 依赖者视角
{扫描发现，或 "未发现问题"}

### 审查发现汇总
| 严重度 | 文件:行号 | 视角 | 描述 | 建议 |
|--------|----------|------|------|------|
| {Critical/High/Medium/Low} | {file:line} | {攻击者/泄露者/...} | {问题} | {建议} |

### 测试覆盖
| 测试类型 | 数量 | 状态 |
|----------|------|------|
| ... | ... | ... |

### 结论
{通过 / 有条件通过 / 需修改}

命令参考

撰写命令

/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 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 {任务名}。如需撤销请说明」

阶段顺序：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. ai-proj task create 创建【代码评审】任务并关联需求（linkRole=code_review）
6. ai-proj create-and-attach 附加 CR 报告文档（必须含五视角扫描结果）
7. 展示发现摘要，AskUserQuestion 确认是否创建 bug 修复任务
8. 若有 High/Critical 发现 → ai-proj task create 创建关联修复任务

/req test [REQ-ID] — 测试（前置：代码评审通过），遵循 dev-test 技能的 5-Gate 流程

/req deploy [--project <name>] [--env <env>] — 项目级批量部署：

1. 收集待部署需求（delivery_stage=testing + 全 test 任务 completed）
2. AskUserQuestion 确认范围
3. ai-proj task create 创建部署批次任务
4. Deploy Gates DG1-DG6：staging 部署 → 冒烟测试 → 回归 → 生产部署
5. ai-proj task append-doc 记录部署文档
6. ai-proj req advance --id <id> --to released 批量推进

/req done [REQ-ID] — 类型化归档门禁 + git commit + push + ai-proj req archive --id <id>：

• 推断类型：有 implementation → code；无 implementation 有 prd/test → skill；仅 deploy → ops
• code 检查：delivery_stage=released + deploy 任务完成 + 部署文档 + 所有任务完成
• 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
testing	【测试】集成测试: {需求标题}	test
deploy	由 /req deploy 批量创建	deploy

测试环境流程

[本机] → 通过 → [预发布] → 通过 → [生产]
   ↑                │              │
   └────────────────┴─── 失败 ─────┘

任务关联规范

link_role	阶段前缀	所属阶段	进度权重
prd	【评审】	analysis	10%
design	【评审】	design	5%
implementation	【开发】	dev	50%
code_review	【代码评审】	review	5%
test	【测试】	testing	15%
deploy	【部署】	staging/released	10%
documentation	【文档】	any	5%

标准任务结构

需求 REQ-xxx
├── 📝 analysis  → 【评审】PRD: {需求标题}                    (linkRole: prd)
├── 📐 design    → 【评审】技术设计: {需求标题}               (linkRole: design)
├── 💻 dev       → 【开发-后端】、【开发-前端】{描述}          (linkRole: implementation)
├── 🔍 review    → 【代码评审】CR: {需求标题}                 (linkRole: code_review)
├── 🧪 testing   → 【测试】集成测试: {需求标题}               (linkRole: test)
├── 🚀 staging   → 【部署】部署到 staging                     (linkRole: deploy)
└── 🏁 released  → 【部署】部署到 prod                        (linkRole: deploy)

ai-proj CLI 速查

# 需求操作
ai-proj req list                          # 列出需求
ai-proj req get --id <id>                 # 查看详情
ai-proj req create --title "..." ...      # 创建需求
ai-proj req update --id <id> ...          # 更新需求
ai-proj req submit --id <id>              # 提交评审
ai-proj req approve --id <id>             # 批准需求
ai-proj req advance --id <id> --to <stage> # 推进阶段
ai-proj req link --id <id> --task-ids ... # 关联任务
ai-proj req tasks --id <id>               # 查看关联任务

有效值

审批状态: draft, pending, reviewing, approved, rejected, archived

开发阶段: backlog, analysis, design, dev, review, integration, testing, staging, released

linkRole: prd, design, implementation, code_review, test, deploy, regression, documentation

详细阶段管理命令

/req phase [REQ-ID]

查看需求当前开发阶段和任务状态。

执行逻辑：

1. get_requirement(id) → 获取 delivery_stage
2. get_requirement_tasks(id) → 获取所有关联任务
3. 按 linkRole 分组展示，标注当前阶段任务完成度

输出示例：

REQ-20260218-0013 | 阶段: dev (开发)
────────────────────────────────────
✅ analysis (评审)
   ✅ #6035 【评审】PRD: 需求全生命周期阶段化管理
▶ dev (开发) ← 当前阶段
   🔄 #6042 【开发-后端】实现阶段管理 API [in_progress]
   ⬜ #6043 【开发-前端】阶段可视化组件 [todo]
⬜ review (代码评审)
⬜ testing (测试)

/req resume [REQ-ID]

从上次中断的位置恢复工作。会话被截断后的首选命令。

执行逻辑：

1. 若无 REQ-ID → list_requirements(status=approved) 找最近活跃需求
2. get_requirement(id) → 获取 delivery_stage
3. get_requirement_tasks(id) → 获取所有关联任务及状态
4. 汇总展示恢复上下文

输出格式：

📋 恢复工作上下文
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
需求: REQ-20260218-0016 | 需求标题
状态: approved | 阶段: dev (开发)

📊 任务进度: 2/4 完成
  ✅ #6051 【开发-后端】实现 API
  🔄 #6053 【开发-Skill】xxx [in_progress]
  ⬜ #6054 【开发-Skill】xxx [todo]

▶ 建议操作:
  1. 继续任务 #6053（当前 in_progress）
  2. 执行 /req next 推进阶段

/req regression [--module <name>] [--mode <mode>]

运行回归测试。系统级持续质量活动。

• --module 指定模块，不指定则按影响域推断
• --mode：impact（影响域，默认）| critical（关键路径）| full（全量）

执行逻辑：

1. 确定范围：指定 module → 直接运行；未指定 → git diff + module-deps.json 推断
2. 运行 regression-suite/suites/ 下对应脚本
3. 对比上次运行结果，标记回归（上次 PASS + 本次 FAIL）
4. 有回归 → AskUserQuestion「是否创建 bug 需求？」

辅助命令

/req link [REQ-ID] --task-id [TASK-ID] — 关联任务到需求

/req decompose [REQ-ID] — 分解需求为任务，自动加阶段前缀

/req generate-tasks [REQ-ID] — 根据 PRD 自动生成开发任务，带【开发】前缀

/req priority [REQ-ID] [low|medium|high] — 设置需求优先级

/req stats [REQ-ID|--all] — 查看需求统计信息

阶段任务 Checklist 模板

/req next 推进到新阶段时，通过 create_stage_task 自动创建建议任务：

analysis（评审）

☐ 【评审】PRD: {需求标题}          (linkRole: prd)
☐ 【评审】技术设计: {需求标题}      (linkRole: design) [可选]

design（设计）

☐ 【设计】技术方案: {需求标题}      (linkRole: design)

dev（开发）

☐ 【开发-后端】{需求标题}           (linkRole: implementation)
☐ 【开发-前端】{需求标题}           (linkRole: implementation) [可选]

review（代码评审）

☐ 【代码评审】{需求标题}            (linkRole: code_review)

testing（测试）

☐ 【测试】单元测试: {需求标题}       (linkRole: test)
☐ 【测试】集成测试: {需求标题}       (linkRole: test) [可选]

部署（由 /req deploy 批量触发）

testing 完成 → 进入「待部署池」→ /req deploy 创建批次任务

按需求类型的最低测试标准：

需求类型	最低测试要求
code	go test 或前端测试通过 + API 验证 + 截图验证
skill	关键词一致性 + 规则无歧义 + 边界情况（至少 3 项）
ops	部署命令可执行 + 健康检查通过

MCP 工具映射

命令	MCP 工具
/req	list_requirements
/req new	create_requirement
/req phase	get_requirement + get_requirement_tasks
/req next	advance_delivery_stage + create_stage_task
/req resume	get_requirement + get_requirement_tasks
/req dev	get_requirement + get_requirement_tasks + start_task_with_timer
/req cr	get_requirement_tasks + Git diff
/req test	req-test-gate 5-Gate 流程
/req deploy	Deploy Gates DG1-DG6
/req regression	git diff + 回归套件
/req done	类型推断 + 检查清单 + archive_requirement
/req review	submit_requirement
/req review pass	approve_requirement
/req link	link_tasks_to_requirement

环境选择

重要：正式需求应直接在生产环境 (mcp__ai-proj-prod__*) 创建。 仅在功能测试、流程验证时使用开发环境 (mcp__ai-proj-dev__*)。 开发环境同步到生产时，due_date、reviewer_id、allow_self_approve 等字段会丢失，需手动补充。

Hook 自动同步

需求操作自动触发同步，无需手动执行：

事件	触发操作
requirement.created	同步到远程
requirement.approved	同步需求和任务
task.completed	同步任务状态
requirement.archived	最终同步 + 思源笔记

手动同步：

mcp__ai-proj__sync_requirement_to_remote(requirementId)
mcp__ai-proj__batch_sync_tasks_to_remote(taskIds)

同步已知限制：

字段	同步支持	说明
title, description, status, priority	✅	正常同步
due_date	❌	不会同步，需手动补充
reviewer_id	❌	不会同步
allow_self_approve	❌	不会同步

思源笔记集成

归档时自动同步 5 阶段文档到思源笔记：

• 路径：需求管理/REQ-XXXX/
• 文档：01-PRD.md ~ 05-生命周期总结.md
• 手动同步：/req sync-siyuan [REQ-ID]

相关技能

技能	用途
req-prd	PRD 文档编写 + 评审方法论
req-test-gate	测试 5-Gate + Deploy Gates
req-dev	PRD 到代码转换、开发计划