pipexerp/ai-proj-helper
6
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

chore(marketplace): add publish-plugin, rewrite init.sh, cleanup obsolete plugins

Browse Source 
- Add publish-plugin: marketplace publish + Feishu bot notification
- Rewrite init.sh: SSE-first, fixed prod API, remove env selection
- Update CLAUDE.md, README.md, claude-config.yaml
- Update skills: req-plugin, req-prd-plugin, pull-request-plugin
- Delete sync-skills.sh (obsolete)
- Delete deprecated plugins: skills-ops/*, skills-projects/*, old skills-dev/req duplicates
- Regenerate marketplace.json (27 plugins)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
John Qiu
2026-03-14 15:09:07 +10:30
parent 5878c1f852
commit dcdae8c636
79 changed files with 610 additions and 13407 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
skills-req/executing-plans-plugin/.claude-plugin/plugin.json
View File

@@ -1,8 +0,0 @@
{
"name": "executing-plans-plugin",
"description": "Plugin for executing-plans",
"version": "1.0.0",
"author": {
"name": "qiudl"
}
}

96
skills-req/executing-plans-plugin/skills/SKILL.md
View File

@@ -1,96 +0,0 @@
---
name: executing-plans
description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
---
# Executing Plans
## Overview
Load plan, review critically, create branch, execute tasks in batches, report for review between batches.
**Core principle:** Batch execution with checkpoints for architect review.
**Announce at start:** "I'm using the executing-plans skill to implement this plan."
## The Process
### Step 1: Load and Review Plan
1. Read plan file
2. Review critically - identify any questions or concerns about the plan
3. If concerns: Raise them with your human partner before starting
4. If no concerns: Proceed to branch setup
### Step 2: Setup Branch
**Before any implementation, ensure proper branch isolation.**
1. Check if already on a feature branch for this task
2. If not, use `/pr start` to create one:
```bash
/pr start <type> <REQ-id> <name>
# Example: /pr start feature REQ-123 user-login
```
3. If no REQ-id available, ask user or create branch manually:
```bash
git fetch origin
git checkout -b <type>/<descriptive-name> origin/main
```
4. Confirm branch is ready before proceeding
**Branch types:** `feature`, `fix`, `refactor`
### Step 3: Create Tasks and Execute Batch
**Default: First 3 tasks**
1. Create TodoWrite tasks from plan
2. For each task in batch:
- Mark as in_progress
- Follow each step exactly (plan has bite-sized steps)
- Run verifications as specified
- Mark as completed
### Step 4: Report
When batch complete:
- Show what was implemented
- Show verification output
- Say: "Ready for feedback."
### Step 5: Continue
Based on feedback:
- Apply changes if needed
- Execute next batch
- Repeat until complete
### Step 6: Complete Development
After all tasks complete and verified:
- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
- Follow that skill to verify tests, present options, execute choice
## When to Stop and Ask for Help
**STOP executing immediately when:**
- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
- Plan has critical gaps preventing starting
- You don't understand an instruction
- Verification fails repeatedly
**Ask for clarification rather than guessing.**
## When to Revisit Earlier Steps
**Return to Review (Step 1) when:**
- Partner updates the plan based on your feedback
- Fundamental approach needs rethinking
**Don't force through blockers** - stop and ask.
## Remember
- Review plan critically first
- **Create feature branch before implementation**
- Follow plan steps exactly
- Don't skip verifications
- Reference skills when plan says to
- Between batches: just report and wait
- Stop when blocked, don't guess

8
skills-req/req-commands-plugin/.claude-plugin/plugin.json
View File

@@ -1,8 +0,0 @@
{
"name": "req-commands-plugin",
"description": "需求命令详细参考。含撰写命令（new/draft/edit/check/split/history/compare）和流程命令（submit/review/phase/next/deploy/done）。",
"version": "2.0.0",
"author": {
"name": "qiudl"
}
}

436
skills-req/req-commands-plugin/skills/SKILL.md
View File

@@ -1,436 +0,0 @@
---
name: req-commands
description: 需求命令详细参考。当需要查看 /req 命令的详细用法、参数、示例时使用。
---
# req 命令参考
## 基础命令
### `/req` 或 `/req list`
列出所有需求，按状态分组显示。
### `/req new [标题]`
创建新需求。
- 参数：`--priority=high|medium|low`，`--project=<name>`，`--category=feature|bug|improvement`
- 创建后提示使用 `req-prd` 技能编写 PRD
### `/req status [REQ-ID]`
查看需求详情、进度、关联任务。
## 阶段管理命令
### `/req phase [REQ-ID]`
查看需求当前开发阶段和任务状态。
**执行逻辑**：
1. `get_requirement(id)` → 获取 `delivery_stage`
2. `get_requirement_tasks(id)` → 获取所有关联任务
3. 按 linkRole 分组展示，标注当前阶段任务完成度
**输出示例**：
```
REQ-20260218-0013 | 阶段: dev (开发)
────────────────────────────────────
✅ analysis (评审)
✅ #6035 【评审】PRD: 需求全生命周期阶段化管理
✅ #6040 【评审】技术设计: 数据模型
▶ dev (开发) ← 当前阶段
🔄 #6042 【开发-后端】实现阶段管理 API [in_progress]
⬜ #6043 【开发-前端】阶段可视化组件 [todo]
⬜ review (代码评审)
(无任务)
⬜ testing (测试)
(无任务)
```
### `/req next [REQ-ID]`
检测当前阶段完成度，推进到下一阶段。
**执行逻辑**：
1. 获取当前 `delivery_stage` 和该阶段所有任务
2. 检查任务完成度：
- 全部完成 → 提示「当前阶段已完成，是否推进到 {下一阶段}？」
- **部分未完成 → 显示未完成任务列表 + AskUserQuestion**：
- 选项 A: "强制推进（需说明原因）"
- 选项 B: "返回完成任务"
- 用户选 A → 输入跳过原因 → `advance_delivery_stage(force=true)`
- 记录到需求历史: `POST /requirements/{id}/history`，comment 包含跳过原因
- **⚠️ 禁止 AI 自动使用 force=true，必须经过 AskUserQuestion 确认**
3. **智能跳阶段检测**（推进前）：
- `get_requirement_tasks(id)` → 收集所有 linkRole
- 如果目标阶段与当前 linkRole 不匹配，主动建议跳过：
- 无 `implementation` → 推进到 review/testing 时提示「该需求无代码任务，建议跳过此阶段」
- 无 `code_review` → 推进到 review 时提示跳过
- 无 `test` → 推进到 testing 时提示跳过
- 通过 AskUserQuestion 确认：「跳过」或「仍然创建任务」
4. 用户确认推进后：
- 更新 `delivery_stage` 到下一阶段
- **自动创建**目标阶段的建议任务（`create_stage_task` 批量创建，无需询问）
- 展示已创建任务列表：「✅ 已创建: #XXXX 【代码评审】CR: {需求标题}。如需撤销请说明」
- ⚠️ 仅当用户主动要求撤销时才删除已创建任务
**阶段顺序**：
```
analysis → design → dev → review → testing → [待部署池] → released
↑ /req deploy 批量推进
```
**linkRole 到阶段的映射**：
| linkRole | 所属阶段 |
|----------|----------|
| prd | analysis |
| design | design |
| implementation | dev |
| code_review | review |
| test | testing |
| deploy (staging) | staging |
| deploy (prod) | released |
## 会话恢复命令
### `/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 | 需求全生命周期 AI 开发管理优化
状态: approved | 阶段: dev (开发)
📊 任务进度: 2/4 完成
✅ #6051 【开发-后端】实现 advance_delivery_stage MCP 工具
✅ #6052 【开发-后端】实现 create_stage_task 组合 MCP 工具
🔄 #6053 【开发-Skill】req-commands 阶段 checklist 模板化 [in_progress]
⬜ #6054 【开发-Skill】会话断点恢复机制 [todo]
▶ 建议操作:
1. 继续任务 #6053（当前 in_progress）
2. 执行 /req next 推进阶段
3. 执行 /req phase 查看完整阶段视图
```
**自动行为**：
- 如果有 `in_progress` 任务，提示继续该任务
- 如果当前阶段所有任务已完成，提示执行 `/req next`
- 如果需求已 `archived`，告知用户无需操作
## 评审命令
### `/req review [REQ-ID]`
提交评审。**前置条件**：必须有 PRD 文档。
**评审等待机制（强制）**：
1. `submit_requirement(id)` → status 变为 pending
2. 展示 PRD 要点摘要：
```
PRD 评审摘要
─────────────────────
标题: {需求标题}
核心方案: {1-2句总结}
验收标准: {N}项
改动范围: {文件列表}
```
3. **AskUserQuestion**: "请确认 PRD 是否通过评审"
- "通过评审" → `approve_requirement(id)`
- "需要修改" → 回到编辑流程
4. **⚠️ 禁止 AI 自动审批**，必须等待用户明确选择
### `/req review pass [REQ-ID]`
评审通过。支持多人审批。参数：`--comment="审批意见"`
### `/req review reject [REQ-ID] [原因]`
评审驳回。必须提供驳回原因。
### `/req review status [REQ-ID]`
查看审批进度（多人审批时）。
## 开发命令
### `/req dev [REQ-ID]`
启动开发，自动选择优先级最高的 todo 任务并开始计时。
- 参数：`--task=<task-id>` 指定任务
- 优先启动 `implementation` 角色任务
- **自动设置** `delivery_stage = dev`（如尚未设置）
### `/req cr [REQ-ID]`
代码评审。**前置条件**：开发任务完成。
- 显示 Git diff 摘要
- 生成代码评审检查清单
- **自动设置** `delivery_stage = review`
### `/req test [REQ-ID]`
启动测试。**前置条件**：代码评审通过。
- 参数：`--skip-cr --reason="原因"` 跳过代码评审
- **自动设置** `delivery_stage = testing`
- **⭐ 遵循 `req-test-gate` v2 技能的 5 道门禁**
**执行逻辑（5-Gate 流程，详见 `req-test-gate` 技能）**：
1. **Gate 1 前置条件**：CR 已通过 + 开发任务全部完成（不可跳过）
2. **Gate 2 测试执行**：推断需求类型（code/skill/ops），分阶段验证
- **code 类型四阶段**：
- **2A 静态验证**：编译 + 单元测试 + 条件前端/iOS 测试
- **2B 集成验证**：API 端点 + DB 约束 + 错误处理
- **2C 冒烟测试**：Staging 环境健康检查 + 核心流程（已部署时）
- **2D 原型符合性**：对比原型 HTML 的结构/字段/交互/状态（有原型时）
- **skill**: 关键词一致性 + 规则无歧义 + 边界情况（至少 3 项）
- **ops**: 部署命令可执行 + 健康检查
3. **Gate 3 质量验证**：派遣 test-validator 子代理审查测试质量
- code 类型：总是触发 | skill 类型：≥5 测试项时触发 | ops 类型：不触发
- Critical 缺陷必须修复，Important 缺陷需 AskUserQuestion 确认
4. **Gate 4 文档持久化（不可跳过）**：`create-and-attach` 将完整测试报告写入测试任务文档
- 文档模板见 `req-test-gate` 技能的「最小必填模板」（含 2A-2D 阶段标记）
- 必须包含：前置条件结果 + 测试执行表格 + 质量验证摘要 + 通过/失败结论
- 无此文档 → `/req deploy` 前置检查会警告
5. **Gate 5 回归贡献（code 类型）**：检查是否有 linkRole=regression 任务和用例文档
- v2.0 过渡期为警告级别，不阻塞
- 提醒补充回归测试用例到回归池
### `/req deploy [--project <name>] [--env <environment>]`
**项目级批量部署**。收集所有待部署需求，一次构建部署。
- **这是项目级动作**，不是单需求操作
- `--project` 默认为当前项目，`--env` 默认为 `staging`
- 参数：`--platform=web|ios|android`
- **⭐ 遵循 `req-test-gate` v2 的 Deploy Gates (DG1-DG6)**
**执行逻辑**：
1. **前置检查（强制）**：
- 对每个待部署需求，检查 testing 阶段任务是否有文档附件（`has_task_document`）
- ✅ 有文档 → 继续
- ⚠️ 无文档 → AskUserQuestion「测试任务 #XXXX 无测试记录文档，确认继续部署？」
2. **收集待部署需求**：
- `delivery_stage = testing` 且所有 test 任务 completed
- 有 implementation 任务（排除纯运维/文档需求）
3. **展示待部署列表** → `AskUserQuestion` 确认部署范围
4. **创建部署批次任务**：
- 标题：`【部署】{project} {date} ({N} requirements)`
- 对每个选中需求：`link_tasks_to_requirement(role=deploy)`
5. **Deploy Gates (DG1-DG6)**（详见 `req-test-gate/deploy-gates.md`）：
- **DG1 迁移检查（不可跳过）**：对比 migrations/ vs 数据库，有新 migration 先备份再执行
- **DG2 Staging 部署**：构建镜像 + 部署到 singapore
- **DG3 冒烟测试**：健康检查 + 登录 + 新 API 验证
- **DG4 影响域回归**：根据 module-deps.json 运行对应回归套件（无套件时跳过）
- **DG5 性能基线（推荐）**：关键 API 响应时间检查
- **DG6 生产部署（不可跳过）**：部署 + 健康检查，失败立即回滚
6. **部署后强制检查点**：
- ✅ **部署文档创建**（必须）：`create-and-attach` 到部署任务，包含 Deploy Gates 结果表格
- ☑️ **截图验证**（可选）：有 chrome-dev MCP → 执行截图；无 → 记录跳过
7. **部署成功后**：
- 所有关联需求 `advance_delivery_stage → released`
- `complete_task(部署任务)`
**单需求兼容**：当仅 1 个需求待部署时，流程自动退化为单需求部署。
### `/req done [REQ-ID]`
完成归档。参数：`--force` 强制归档。
**类型化归档门禁（强制）**：
1. `get_requirement_tasks(id)` → 获取所有关联任务
2. **推断需求类型**（从 linkRole 集合判断）：
- **code**: 有 `implementation` 角色任务 → 代码需求
- **skill**: 无 `implementation`，有 `prd`/`code_review`/`test` → Skill/文档需求
- **ops**: 仅 `deploy` 角色任务 → 运维需求
3. **按类型执行检查清单**：
| 检查项 | code | skill | ops |
|--------|------|-------|-----|
| delivery_stage = released | ✅ | - | - |
| delivery_stage >= testing | - | ✅ | - |
| deploy 任务已完成 | ✅ | - | ✅ |
| 部署文档存在 | ✅ | - | - |
| 所有关联任务已完成 | ✅ | ✅ | ✅ |
4. **检查结果处理**：
- 全部通过 → 展示检查清单 + AskUserQuestion "确认归档？"
- 有缺失 → 显示缺失项 + AskUserQuestion "是否强制归档？"
- 用户确认 → 进入步骤 5
5. **Git 提交（强制）**：
- `git add` 本需求相关变更文件
- `git commit -m "feat(skill): REQ-XXXX 需求标题"`（或 `fix`/`refactor` 等合适的 type）
- `git push origin <current-branch>`
- ⚠️ 提交前确认无敏感文件（.env、credentials 等）
6. `archive_requirement(id)`
7. 归档后生成生命周期总结，触发同步
### `/req regression [--module <name>] [--mode <mode>]`
**运行回归测试**。系统级持续质量活动。
- `--module` 指定模块（okr/task/auth/...），不指定则按影响域推断
- `--mode` 执行模式：`impact`（影响域）| `critical`（关键路径）| `full`（全量）
- 默认模式：`impact`（根据最近变更推断影响域）
**执行逻辑**（详见 `req-test-gate/regression.md`）：
1. **确定范围**：
- 指定 module → 直接运行该模块回归套件
- 未指定 → `git diff --name-only` 获取变更 → 查 `module-deps.json` → 推断影响域
2. **运行回归套件**：
- 执行 `regression-suite/suites/` 下对应脚本
- 记录每个用例的 PASS/FAIL 状态
3. **回归判定**：
- 对比上次运行结果
- 上次 PASS + 本次 FAIL → 标记为「回归」
4. **结果处理**：
- 全部通过 → 展示通过率
- 有回归 → AskUserQuestion「是否为回归项创建 bug 需求？」
- 有新失败 → 展示失败列表，建议排查
5. **报告输出**：
```
回归测试结果 - {module/all}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
模式: {impact/critical/full}
套件: {N} 个 | 用例: {M} 个
✅ 通过: {P} | ❌ 失败: {F} | 🔴 回归: {R}
```
**当前状态**：回归套件待初始化，首次运行会提示建立基线。
## 辅助命令
### `/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)
☐ 【设计】数据模型设计 (linkRole: design) [可选]
```
### dev（开发）
```
☐ 【开发-后端】{需求标题} (linkRole: implementation)
☐ 【开发-前端】{需求标题} (linkRole: implementation) [可选]
☐ 【开发-MCP】{需求标题} (linkRole: implementation) [可选]
```
### review（代码评审）
```
☐ 【代码评审】{需求标题} (linkRole: code_review)
```
### testing（测试）
```
☐ 【测试】单元测试: {需求标题} (linkRole: test)
☐ 【测试】集成测试: {需求标题} (linkRole: test) [可选]
```
**按需求类型的最低测试标准**：
| 需求类型 | 最低测试要求 |
|----------|-------------|
| **code** | `go test` 或前端测试通过 + API 验证 + 截图验证 |
| **skill** | 关键词跨文件一致性 + 规则无歧义验证 + 边界情况检查（至少 3 项） |
| **ops** | 部署命令可执行 + 健康检查通过 |
**skill 类型测试 checklist**（最低 3 项）：
```
☐ 关键词一致性：grep 验证核心概念在所有相关 skill 文件中对齐
☐ 规则无歧义：每条规则的触发条件和执行动作明确，无二义性
☐ 边界情况：至少验证 1 个边界场景（如混合类型需求的分类）
☐ 交叉引用：文件间的引用（如"见 xxx 技能"）指向正确 [可选]
```
### 部署（项目级，由 `/req deploy` 触发）
部署不再按单需求创建任务，而是通过 `/req deploy` 批量收集待部署需求：
```
testing 完成的需求 → 进入「待部署池」
/req deploy → 创建批次任务：【部署】{project} {date} ({N} requirements)
关联到所有选中需求 (linkRole: deploy)
部署成功后批量推进 → released
```
### `/req next` 执行流程（更新版）
1. `get_requirement(id)` → 获取 `delivery_stage`
2. `get_requirement_tasks(id)` → 获取关联任务，收集 linkRole 集合
3. **智能跳阶段检测**：检查目标阶段是否与 linkRole 匹配
- 不匹配 → AskUserQuestion「建议跳过 {阶段}，是否同意？」
- 用户同意跳过 → 递归检测下一阶段
- 用户拒绝 → 继续推进到该阶段
4. **门禁检查**：`advance_delivery_stage(id, nextStage)` 自动检查
- 通过 → 进入步骤 4.5
- 未通过 → 显示阻塞任务，AskUserQuestion 确认 force（禁止自动 force）
4.5. **⭐ 内容门禁检查（防空转）**：对关键阶段的已完成任务验证文档附件
- **适用阶段**: review（CR 报告）、testing（测试结果）、staging（部署文档）
- **检查逻辑**：
```
对当前阶段的每个 completed 任务:
has_task_document(taskId) → 有文档？
✅ 有 → get_task_document(taskId) → 检查质量:
- review: ≥500字符 + 含 file:line 代码引用 + 含结论章节
- testing: 含测试项表格 + 含通过/失败结论 + ≥200字符
（详见 req-test-gate 技能 Gate 4 文档质量门禁）
- staging: 含健康检查结果 + 含镜像/commit 信息
❌ 无 → 阻止推进，提示「任务 #XXXX 缺少 {类型} 文档」
```
- **未通过处理**：AskUserQuestion「内容门禁未通过，选择操作」
- 选项 A: "补充文档后重试"
- 选项 B: "强制跳过（记录原因）" → 记录跳过原因到需求历史
- **⚠️ 禁止 AI 自动跳过**，必须经过 AskUserQuestion
5. **自动创建阶段任务**：`create_stage_task` 批量创建目标阶段建议任务
- 展示已创建列表：「✅ 已创建: #XXXX {任务名}。如需撤销请说明」
- 用户主动要求撤销时才删除
## 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` v2 5-Gate 流程: 前置检查 → 类型化测试(2A-2D) → test-validator 子代理 → `create-and-attach` 持久化 → 回归贡献检查 |
| `/req deploy` | 前置检查 + Deploy Gates(DG1-DG6): 迁移→staging→冒烟→回归→性能→生产 + 部署文档 |
| `/req regression` | `git diff` 影响域推断 + 运行回归套件 + 回归判定 + 可选创建 bug 需求 |
| `/req done` | 类型推断 + 检查清单 + `AskUserQuestion` + `archive_requirement`（⚠️ 禁止直接调用 archive） |
| `/req review` | `submit_requirement` |
| `/req review pass` | `approve_requirement` |
| `/req review reject` | `reject_requirement` |
| `/req link` | `link_tasks_to_requirement` |
## 任务关联类型
| link_role | 说明 | 阶段前缀 | 进度权重 |
|-----------|------|----------|----------|
| prd | PRD 文档 | 【评审】 | 0.1 |
| design | 技术设计 | 【评审】 | 0.05 |
| implementation | 开发实现 | 【开发】 | 0.5 |
| code_review | 代码评审 | 【代码评审】 | 0.05 |
| test | 测试验证 | 【测试】 | 0.15 |
| deploy | 部署发布 | 【部署】 | 0.1 |
| regression | 回归用例 | 【回归】 | 0.0 |
| documentation | 文档编写 | 【文档】 | 0.05 |

8
skills-req/req-deploy-plugin/.claude-plugin/plugin.json
View File

@@ -1,8 +0,0 @@
{
"name": "req-deploy-plugin",
"description": "Plugin for req-deploy",
"version": "1.0.0",
"author": {
"name": "qiudl"
}
}

18
skills-req/req-deploy-plugin/skill.json
View File

@@ -1,18 +0,0 @@
{
"name": "req-deploy",
"version": "1.0.0",
"description": "需求部署技能。用于 Docker 镜像构建、Staging/Production 环境部署、API 验证、前端截图验证、部署文档创建。当用户执行 /req deploy 或需要部署需求时自动激活。",
"triggerPatterns": [
"部署",
"deploy",
"staging",
"production",
"镜像构建",
"docker build",
"Jenkins",
"生产环境",
"预发布"
],
"autoActivate": false,
"hidden": false
}

1957
skills-req/req-deploy-plugin/skills/SKILL.md
View File

File diff suppressed because it is too large Load Diff

115
skills-req/req-plugin/code-review-guide.md
View File

@@ -1,115 +0,0 @@
# 代码评审指南 (Code Review Guide)
代码评审是测试阶段的前置条件，确保代码质量在测试前得到验证。
## 评审时机
```
开发完成 → 代码评审 → 测试
↑ ↓
└── 发现问题，修复后重新评审
```
## 评审检查清单
### 1. 代码风格
- [ ] 符合项目编码规范（Go/TypeScript）
- [ ] 命名清晰有意义
- [ ] 代码格式统一（已运行 lint/format）
### 2. 安全性
- [ ] 无 SQL 注入风险
- [ ] 无 XSS 漏洞
- [ ] 无敏感信息硬编码（密码、密钥）
- [ ] 权限检查完善
### 3. 错误处理
- [ ] 异常捕获完善
- [ ] 错误信息友好（不暴露内部细节）
- [ ] 边界条件处理
### 4. 性能
- [ ] 无 N+1 查询
- [ ] 无不必要的循环/递归
- [ ] 大数据量有分页处理
### 5. 日志与监控
- [ ] 关键操作有日志
- [ ] 日志级别适当
- [ ] 无敏感信息输出到日志
### 6. 测试覆盖
- [ ] 关键逻辑有单元测试
- [ ] 测试用例有效
### 7. 文档
- [ ] 复杂逻辑有注释
- [ ] API 有文档说明
## 评审方式
| 方式 | 适用场景 |
|------|----------|
| 自评 (Self Review) | AI 开发的代码，Claude 自动检查 |
| 他人评审 (Peer Review) | 团队协作，提交 PR 等待评审 |
| 结对评审 (Pair Review) | 复杂功能，实时讨论 |
## 执行流程
### `/req cr` 命令执行步骤
1. **验证开发完成**
```
检查所有 implementation 任务状态 = completed
```
2. **生成变更摘要**
```bash
git diff --stat HEAD~N # N = 开发期间的提交数
git diff --name-only HEAD~N
```
3. **显示检查清单**
- 输出上述检查清单
- 逐项确认或标记问题
4. **记录评审结果**
- 通过：创建 code_review 任务并标记 completed
- 不通过：列出问题，等待修复后重新评审
## 常见问题
### Go 后端
- 未检查 `error` 返回值
- 缺少 `defer` 关闭资源
- 并发访问未加锁
### TypeScript 前端
- `any` 类型滥用
- 缺少空值检查
- 未处理异步错误
### 数据库
- 缺少索引
- 大事务未拆分
- 未考虑并发更新
## 评审不通过时
```
/req cr REQ-XXXX
→ 发现问题:
⚠️ handlers/task_handler.go:245 - 缺少错误处理
⚠️ pages/TaskList.tsx:88 - 存在 XSS 风险
→ 请修复后重新执行 /req cr
```
## 跳过评审（紧急情况）
```bash
/req test REQ-XXXX --skip-cr --reason="紧急生产修复"
```
> 跳过评审需记录原因，事后补充评审。

273
skills-req/req-plugin/deploy-guide.md
View File

@@ -1,273 +0,0 @@
# 部署指南
## 部署流程概览
```
Staging 部署（手动） Production 部署（Jenkins）
↓ ↓
本地构建 :test 镜像 本地构建 :latest 镜像
↓ ↓
推送到 DockerHub 推送到 DockerHub
↓ ↓
显示部署命令 调用 Jenkins API
↓ ↓
用户手动执行 自动触发部署
↓ ↓
验证 API 轮询构建状态
↓
验证 API
```
## 环境说明
| 环境 | 触发方式 | 镜像标签 | 用途 |
|------|----------|----------|------|
| staging | 手动 SSH | `:test` | 预发布测试 |
| production | Jenkins API | `:latest` | 正式生产 |
## 镜像构建规范
> ⚠️ **重要**: 必须理解 Dockerfile target 和镜像标签的区别
### Dockerfile Target vs 镜像标签
| 概念 | 说明 | 示例 |
|------|------|------|
| **Dockerfile Target** | 构建阶段，决定镜像内容 | `--target production`, `--target test` |
| **镜像标签** | 版本标识，决定部署环境 | `:test`, `:latest` |
### 正确的构建方式
| 用途 | Dockerfile Target | 镜像标签 | 镜像大小 |
|------|-------------------|----------|----------|
| **Staging 部署** | `--target production` | `:test` | ~50MB |
| **Production 部署** | `--target production` | `:latest` | ~50MB |
| **运行单元测试** | `--target test` | 无需推送 | ~900MB+ |
### 常见错误
❌ **错误做法**：用 `--target test` 构建部署镜像
```bash
# 错误！这会生成 900MB+ 的镜像，包含测试框架和源代码
docker buildx build --target test -t xxx:test ...
```
✅ **正确做法**：用 `--target production` 构建部署镜像
```bash
# 正确！生成 ~50MB 的精简镜像，只包含二进制文件
docker buildx build --target production -t xxx:test ...
```
### Staging vs Production 镜像区别
两者都使用 `--target production` 构建，区别在于：
| 区别点 | Staging (`:test`) | Production (`:latest`) |
|--------|-------------------|------------------------|
| 镜像标签 | `:test` | `:latest` |
| 前端 API URL | `staging.ai.pipexerp.com` | `ai.pipexerp.com` |
| 后端代码 | 完全相同 | 完全相同 |
| 部署服务器 | singapore | tools_ai_proj |
> **注意**: 不是把 staging 镜像部署到生产，而是测试通过后用生产 URL **重新构建** `:latest` 镜像
## Staging 部署
### 前置条件
> ⚠️ **必须完成本机测试才能部署 staging**
| 检查项 | 说明 |
|--------|------|
| 代码评审 | `/req cr` 已完成 |
| 后端单元测试 | `go test ./... -v` 全部通过 |
| **前端截图验证** | 使用 chrome-dev MCP 截图确认 UI 正确显示 |
如果本机测试未通过，将拒绝部署并提示：
```
→ ❌ 本机测试未完成，禁止部署到 staging
→ 请先执行: /req test REQ-XXX
```
### 命令格式
```bash
/req deploy REQ-XXX --env staging [--service <service>]
```
### 支持的服务
| 服务 | 说明 |
|------|------|
| `backend` | 后端 API 服务 |
| `frontend` | 前端 Web 应用 |
| `all` | 全部服务（默认） |
### 执行流程
1. **构建镜像**（本地执行）
```bash
# 后端
docker buildx build --platform linux/amd64 \
-f backend/Dockerfile --target production \
-t saltthing123/ai-proj-backend:test --push backend/
# 前端（注意 API URL 配置）
docker buildx build --platform linux/amd64 \
-f frontend/Dockerfile.prod --target production \
--build-arg REACT_APP_API_URL=https://staging.ai.pipexerp.com/api/v1 \
--build-arg REACT_APP_API_BASE_URL=https://staging.ai.pipexerp.com/api/v1 \
-t saltthing123/ai-proj-frontend:test --push frontend/
```
2. **部署命令**（用户手动执行）
```bash
ssh singapore "cd /opt/ai-project-staging && \
sudo docker-compose pull && \
sudo docker-compose up -d"
```
3. **验证**
```bash
curl -s https://staging.ai.pipexerp.com/api/v1/health | jq .
```
## Production 部署
### 命令格式
```bash
/req deploy REQ-XXX --env production [--service <service>]
```
### 支持的服务
| 服务 | 镜像名 | Jenkins 参数 |
|------|--------|--------------|
| `backend` | saltthing123/ai-proj-backend | SERVICE=backend |
| `frontend` | saltthing123/ai-proj-frontend | SERVICE=frontend |
| `ios` | - | SERVICE=ios |
| `android` | - | SERVICE=android |
| `all` | 全部 | SERVICE=all（默认） |
### 执行流程
1. **构建镜像**（本地执行）
```bash
# 后端
docker buildx build --platform linux/amd64 \
-f backend/Dockerfile --target production \
-t saltthing123/ai-proj-backend:latest --push backend/
# 前端
docker buildx build --platform linux/amd64 \
-f frontend/Dockerfile.prod --target production \
--build-arg REACT_APP_API_URL=https://ai.pipexerp.com/api/v1 \
--build-arg REACT_APP_API_BASE_URL=https://ai.pipexerp.com/api/v1 \
-t saltthing123/ai-proj-frontend:latest --push frontend/
```
2. **触发 Jenkins 部署**
```bash
source ~/.config/devops/credentials.env
curl -X POST "$JENKINS_URL/job/ai-proj/buildWithParameters" \
-u "$JENKINS_USER:$JENKINS_TOKEN" \
--data "SERVICE=backend&IMAGE_TAG=latest"
```
3. **查看构建状态**
```bash
source ~/.config/devops/credentials.env
curl -s "$JENKINS_URL/job/ai-proj/lastBuild/api/json" \
-u "$JENKINS_USER:$JENKINS_TOKEN" | jq '.result, .building'
```
4. **验证**
```bash
curl -s https://ai.pipexerp.com/api/v1/health | jq .
```
## 安全约束
- **禁止自动 SSH 部署到生产服务器**
- 生产环境部署必须通过 Jenkins API 触发
- Staging 部署命令只显示，由用户手动执行
- 构建失败时必须显示错误原因和解决方案
## 项目配置
### AI-Proj
| 配置项 | 值 |
|--------|-----|
| Jenkins Job | ai-proj |
| Staging 服务器 | singapore |
| Production 服务器 | tools_ai_proj |
| DockerHub 用户 | saltthing123 |
### Coolbuy-Paas
| 配置项 | 值 |
|--------|-----|
| Jenkins Job | coolbuy-paas |
| Staging 服务器 | fnos 测试环境 |
| Production 服务器 | 39.106.88.83 |
| DockerHub 用户 | saltthing123 |
## 常见问题
### Docker 推送失败
**错误**: `push access denied`
**解决**:
```bash
docker login
# 输入 Docker Hub 凭据
```
### Jenkins 构建失败
**查看日志**:
```bash
source ~/.config/devops/credentials.env
curl -s "$JENKINS_URL/job/ai-proj/lastBuild/consoleText" \
-u "$JENKINS_USER:$JENKINS_TOKEN" | tail -100
```
### 镜像架构不匹配
**错误**: `exec format error`
**原因**: 在 ARM64 (M1/M2 Mac) 构建的镜像部署到 AMD64 服务器
**解决**: 构建时必须指定 `--platform linux/amd64`
### 镜像体积异常大（900MB+）
**错误**: 构建的镜像超过 100MB
**原因**: 使用了错误的 Dockerfile target
**检查**:
```bash
# 查看镜像层大小
docker history <image>:<tag> --no-trunc --format "{{.Size}}\t{{.CreatedBy}}" | head -10
```
**常见原因**:
| 层内容 | 大小 | 说明 |
|--------|------|------|
| `go mod download` | 600MB+ | Go 依赖包（不应出现在生产镜像） |
| `ginkgo/gomega` | 200MB+ | 测试框架（不应出现在生产镜像） |
| `COPY . .` | 100MB+ | 源代码（不应出现在生产镜像） |
**解决**: 确保使用 `--target production` 而不是 `--target test`
```bash
# 错误
docker buildx build --target test ...
# 正确
docker buildx build --target production ...
```

55
skills-req/req-plugin/hook-sync.md
View File

@@ -1,55 +0,0 @@
# Hook 自动同步机制
Hook 机制可在特定事件发生时自动触发同步，无需手动执行。
## 支持的 Hook 事件
| 事件 | 触发条件 | 自动执行操作 |
|------|---------|-------------|
| `requirement.created` | 创建新需求 | 同步需求到远程 |
| `requirement.submitted` | 提交评审 | 发送评审通知 |
| `requirement.approved` | 需求评审通过 | 同步需求 + 关联任务到远程 |
| `requirement.archived` | 需求归档 | 最终同步 + 同步到思源笔记 + 发送通知 |
| `task.completed` | 任务完成 | 同步任务状态到远程 |
## 配置 Hook
在 `.claude/settings.local.json` 中配置：
```json
{
"hooks": {
"requirement.approved": {
"enabled": true,
"actions": ["sync_requirement_to_remote", "sync_tasks_to_remote"]
},
"requirement.archived": {
"enabled": true,
"actions": ["sync_requirement_to_remote", "sync_to_siyuan", "send_notification"]
},
"task.completed": {
"enabled": true,
"actions": ["sync_task_to_remote"]
}
}
}
```
## 手动触发 Hook
```bash
/req hook trigger requirement.approved REQ-2026-0010
```
## 查看 Hook 执行历史
```bash
/req hook history REQ-2026-0010
```
## 禁用/启用 Hook
```bash
/req hook disable REQ-2026-0010
/req hook enable REQ-2026-0010
```

64
skills-req/req-plugin/mcp-auth-config.md
View File

@@ -1,64 +0,0 @@
# MCP 认证配置
## 环境选择原则
> 需求和任务的主数据源是**生产环境 (ai.pipexerp.com)**。
> 所有需求创建、任务创建、查询、更新操作必须在生产环境执行。
| 环境 | 用途 | API 地址 |
|------|------|----------|
| **生产环境** | 需求创建、任务创建、数据管理 | https://ai.pipexerp.com/api/v1 |
| 本地环境 | 代码开发调试、功能测试 | http://localhost:8080/api/v1 |
## MCP 配置
确保 `~/.claude/.mcp.json` 配置：
```json
{
"mcpServers": {
"ai-proj": {
"type": "stdio",
"command": "node",
"args": ["/path/to/mcp-task-bridge/dist/index.js"],
"env": {
"TASK_API_BASE": "https://ai.pipexerp.com/api/v1",
"TASK_API_TOKEN": "aiproj_pk_xxxxxxxx...",
"SYNC_REMOTE_API_BASE": "https://ai.pipexerp.com/api/v1",
"SYNC_REMOTE_API_KEY": "aiproj_pk_xxxxxxxx..."
}
}
}
}
```
## 认证方式
### PAT 秘钥（推荐）
- 格式: `aiproj_pk_` + 64 字符十六进制（共 74 字符）
- 优势: 长期有效，无需频繁更新
### dev-quick-login（备选）
仅在 PAT 秘钥不可用时使用：
```bash
curl -s -X POST "http://localhost:8080/api/v1/auth/dev-quick-login" \
-H "Content-Type: application/json" \
-d '{"username":"qiudl"}' | jq -r '.data.access_token'
```
> JWT token 有效期 24 小时，日常使用推荐 PAT 秘钥。
## 验证 PAT 秘钥
```bash
# 测试本地
curl -s -H "X-API-Key: aiproj_pk_xxx..." \
"http://localhost:8080/api/v1/tasks?limit=1" | jq '.success'
# 测试远程
curl -s -H "Authorization: Bearer aiproj_pk_xxx..." \
"https://ai.pipexerp.com/api/v1/tasks?limit=1" | jq '.success'
```

42
skills-req/req-plugin/notification-config.md
View File

@@ -1,42 +0,0 @@
# 通知与自动化配置
## 邮件通知
### 默认邮件组
| 收件人 |
|--------|
| qiudl@zhiyuncai.com |
| fuxing@zhiyuncai.com |
| haiqing@zhiyuncai.com |
| wuweier@zhiyuncai.com |
### 通知类型
| 类型 | 触发时机 | 邮件主题 | 附件文档 |
|------|----------|----------|----------|
| `prd` | PRD完成 | [REQ-PRD] REQ-XXXX PRD文档已完成 | 01-PRD.md |
| `dev` | 开发完成 | [REQ-开发] REQ-XXXX 开发完成 | 02-开发设计.md |
| `test` | 测试完成 | [REQ-测试] REQ-XXXX 测试完成 | 03-测试报告.md |
| `deploy` | 发布完成 | [REQ-发布] REQ-XXXX 已发布 | 04-发布记录.md |
| `archive` | 归档 | [REQ-归档] REQ-XXXX 已归档 | 05-生命周期总结.md |
### 使用方式
```bash
# 使用默认邮件组
/req notify REQ-2026-0007 --type deploy
# 自定义收件人
~/.claude/skills/req/notify.sh -r REQ-2026-0007 -t deploy -e "user1@example.com,user2@example.com"
# 不发送附件
~/.claude/skills/req/notify.sh -r REQ-2026-0007 -t archive -n
```
## 脚本文件
| 脚本 | 功能 | 位置 |
|------|------|------|
| notify.sh | 发送邮件通知 | ~/.claude/skills/req/ |
| update-siyuan-release.sh | 更新思源笔记发布记录 | ~/.claude/skills/req/ |

126
skills-req/req-plugin/prd-review-guide.md
View File

@@ -1,126 +0,0 @@
# PRD 评审方法论
> 评审 PRD 是需求流程中的关键质量关卡。
## 评审流程
1. **结构完整性检查** - 检查 PRD 是否包含所有必要章节
2. **需求清晰度评估** - 验证需求描述是否明确无歧义
3. **技术可行性分析** - 评估技术方案是否可实现
4. **数据模型验证** - 检查数据结构设计是否合理
5. **API 设计审查** - 验证接口设计是否符合规范
## PRD 评审检查清单
### 一、结构完整性检查
| 检查项 | 必须 | 说明 |
|--------|------|------|
| 基本信息 | ✓ | 需求编号、标题、创建日期、作者 |
| 需求背景 | ✓ | 为什么需要这个功能 |
| 目标用户 | ✓ | 明确功能面向的用户群体 |
| 功能描述 | ✓ | 详细的功能需求说明 |
| 用户故事 | ○ | As a... I want... So that... |
| 数据模型 | ✓ | 数据库表结构设计 |
| API 设计 | ✓ | RESTful 接口定义 |
| 页面原型 | ○ | 界面布局和交互说明 |
| 非功能需求 | ○ | 性能、安全、可用性要求 |
| 验收标准 | ✓ | 明确的功能验收条件 |
> ✓ = 必须包含, ○ = 建议包含
### 二、需求清晰度评估（SMART 原则）
| 原则 | 检查点 | 示例 |
|------|--------|------|
| **S**pecific | 需求描述是否具体明确 | ❌ "支持搜索" → ✅ "支持按需求编号、标题模糊搜索" |
| **M**easurable | 是否有量化指标 | ❌ "快速响应" → ✅ "响应时间 < 200ms" |
| **A**chievable | 技术上是否可行 | 评估现有技术栈能否支持 |
| **R**elevant | 是否与业务目标相关 | 功能是否解决实际问题 |
| **T**ime-bound | 是否有明确的时间范围 | 开发周期、上线日期 |
### 三、技术可行性分析
| 检查维度 | 评估内容 |
|----------|----------|
| 技术栈兼容性 | 现有技术栈是否支持所需功能 |
| 系统架构影响 | 是否需要修改现有架构 |
| 第三方依赖 | 是否引入新的外部依赖 |
| 性能影响 | 对系统性能的潜在影响 |
| 安全考量 | 是否存在安全风险 |
| 数据迁移 | 是否需要数据迁移方案 |
### 四、数据模型验证
| 检查项 | 说明 |
|--------|------|
| 表结构设计 | 字段类型、约束、索引是否合理 |
| 关联关系 | 外键、多对多关系是否正确 |
| 命名规范 | 表名、字段名是否符合项目规范 |
| 扩展性 | 是否预留扩展字段 |
| 数据量预估 | 数据增长预估和存储方案 |
| 查询性能 | 常用查询是否有索引支持 |
### 五、API 设计审查
| 检查项 | 标准 |
|--------|------|
| RESTful 规范 | URL 使用名词、HTTP 方法语义正确 |
| 响应格式 | 统一的响应结构 `{success, data, message}` |
| 错误处理 | 明确的错误码和错误信息 |
| 分页设计 | 列表接口支持分页 `?page=1&page_size=20` |
| 参数验证 | 必填参数、类型、范围说明 |
| 版本控制 | API 路径包含版本 `/api/v1/...` |
## 评审意见模板
### 通过模板
```
✅ PRD 评审通过
【评审结论】
PRD 文档结构完整，需求描述清晰，技术方案可行，建议批准进入开发阶段。
【肯定之处】
- 需求背景阐述清晰
- 数据模型设计合理
- API 接口规范
【建议改进】（非阻塞）
- 建议补充性能测试用例
- 建议增加边界条件说明
【评审人】xxx
【评审时间】2026-01-24 10:00
```
### 驳回模板
```
❌ PRD 评审驳回
【驳回原因】
1. 数据模型缺少索引设计
2. API 接口缺少错误处理说明
3. 搜索功能需求描述模糊
【修改要求】
□ 补充数据表索引设计
□ 明确 API 错误码定义
□ 细化搜索功能的具体实现方式
【驳回人】xxx
【驳回时间】2026-01-24 10:00
```
## 常见驳回原因
| 类别 | 常见问题 | 改进建议 |
|------|----------|----------|
| 结构缺失 | 缺少数据模型或 API 设计 | 补充完整的技术设计章节 |
| 需求模糊 | 功能描述不够具体 | 按 SMART 原则重新描述 |
| 边界不清 | 缺少边界条件和异常处理 | 补充边界条件和错误场景 |
| 设计缺陷 | 数据模型或 API 设计不合理 | 重新设计并说明理由 |
| 范围过大 | 需求范围过大难以实现 | 拆分为多个小需求 |
| 验收不明 | 缺少验收标准 | 补充可验证的验收条件 |

50
skills-req/req-plugin/siyuan-integration.md
View File

@@ -1,50 +0,0 @@
# 思源笔记集成
需求的 5 阶段文档统一存储到思源笔记中。
## 文档结构
```
需求管理/
└── REQ-2026-XXXX/
├── 01-PRD.md # 产品需求文档
├── 02-开发设计.md # 开发技术文档
├── 03-测试报告.md # 测试验收报告
├── 04-发布记录.md # CI/CD发布记录
└── 05-生命周期总结.md # 需求归档总结
```
## 同步命令
```bash
/req sync-siyuan REQ-2026-0007
```
## 自动同步时机
| 阶段 | 触发命令 | 同步文档 |
|------|---------|---------|
| PRD 完成 | `/req review` | 01-PRD.md |
| 开发完成 | `/req test` | 02-开发设计.md |
| 测试完成 | `/req deploy` | 03-测试报告.md |
| 发布完成 | 发布任务完成 | 04-发布记录.md |
| 归档完成 | `/req done` | 05-生命周期总结.md (全量同步) |
## MCP 工具调用
```python
# 创建文档
mcp__siyuan__createDocWithMd(
notebook="需求管理",
path="/REQ-2026-0007/01-PRD",
markdown=prd_content
)
```
## 配置
环境变量（可选）：
```bash
export SIYUAN_URL="http://100.118.62.18:6806"
export SIYUAN_TOKEN="your-token"
```

178
skills-req/req-plugin/skills/SKILL.md
View File

@@ -376,9 +376,185 @@ ai-proj req tasks --id <id> # 查看关联任务
**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` | 最终同步 + 思源笔记 |
**手动同步**：
```typescript
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 文档编写 + 评审方法论 |
| `dev-test` | 测试 + 质量门禁 |
| `req-test-gate` | 测试 5-Gate + Deploy Gates |
| `req-dev` | PRD 到代码转换、开发计划 |

177
skills-req/req-plugin/test-guide.md
View File

@@ -1,177 +0,0 @@
# 测试环境流程指南
> 测试必须按照以下环境顺序依次进行，每个环境通过后才能进入下一个环境。
## 测试环境流程
```
[1] 本机环境 ─── 通过 ──→ [2] 预发布环境 ─── 通过 ──→ [3] 生产环境
│ │ │
↓ 失败 ↓ 失败 ↓ 失败
修复并重测 回到步骤[1] 回到步骤[1]
```
## 项目环境配置表
| 项目 | 本机环境 | 预发布环境 | 生产环境 |
|------|---------|-----------|---------|
| ai-proj | localhost:3000/8080 | staging.ai.pipexerp.com | ai.pipexerp.com |
| coolbuy-paas | localhost | fnos 测试环境 | 39.106.88.83:8888 |
| coolbuy-platform | localhost | fnos 测试环境 | 生产服务器 |
## 第一阶段：本机测试环境
> ⚠️ **关键约束**：本机测试必须全部通过，才能部署到 staging 环境。
**测试内容**：
- 单元测试 - 测试单个函数/方法，Mock 外部依赖
- 集成测试 - 测试模块间交互，使用测试数据库
- 功能验证 - 验证功能逻辑正确性
- **前端截图验证** - 使用 chrome-dev MCP 截图确认 UI 显示正确
### 后端测试
```bash
# Go 后端单元测试
go test ./... -v
# 指定模块测试
go test ./backend/handlers/... -v
go test ./backend/services/... -v
```
### 前端截图验证（⚠️ 必须步骤）
> **重要**：前端改动必须通过截图验证，不能只测后端 API。这一步经常被忽略，导致功能未正确显示。
**验证流程**：
1. **确保本机服务运行**
```bash
# 终端1：后端
cd backend && go run main.go
# 终端2：前端
cd frontend && npm start
```
2. **使用 chrome-dev MCP 截图验证**
```python
# 步骤1：导航到目标页面
mcp__chrome-dev__navigate_page(url="http://localhost:3000/requirements/686")
# 步骤2：等待页面加载完成（可选）
mcp__chrome-dev__wait_for(selector=".requirement-detail")
# 步骤3：截图
mcp__chrome-dev__take_screenshot()
# 步骤4：检查截图中功能是否正确显示
# - 新增的列/字段是否显示
# - 样式是否正确
# - 数据是否正确渲染
```
3. **常见验证场景**
| 改动类型 | 验证页面 | 检查项 |
|---------|---------|--------|
| 列表新增列 | 列表页面 | 新列是否显示、数据是否正确 |
| 表单新增字段 | 表单页面 | 字段是否显示、能否正常输入 |
| 样式调整 | 相关页面 | 样式是否生效、布局是否正确 |
| 权限控制 | 相关页面 | 按钮/菜单是否正确显示/隐藏 |
4. **截图保存**
- 截图应保存到测试任务文档中作为验证记录
- 命名规范：`REQ-XXXXX-本机测试-功能名称.png`
### 前端截图验证示例
```
/req test REQ-20260125-0002
→ 检查代码评审... ✓ 已完成
→ 验证开发任务... ✓ 已完成
=== 本机测试阶段 ===
1. 后端单元测试
→ go test ./backend/handlers/requirement_handler_test.go -v
→ ✓ 3/3 测试通过
2. 前端截图验证
→ 启动 chrome-dev MCP...
→ 导航到: http://localhost:3000/requirements/687
→ 截图验证...
→ ✓ 任务ID列正确显示 (#5284 格式)
→ ✓ 列宽度和样式正确
→ 截图已保存
=== 本机测试通过 ===
→ 可以执行: /req deploy REQ-20260125-0002 --env staging
```
### 通过标准
- [ ] 所有后端单元测试通过
- [ ] **前端截图验证通过**（有前端改动时必须）
- [ ] 功能在本地环境正常运行
- [ ] 无控制台错误
- [ ] 截图已保存到测试文档
### 跳过前端验证
仅当改动不涉及前端时，可使用 `--backend-only` 参数：
```bash
/req test REQ-XXXXX --backend-only
```
## 第二阶段：预发布环境
**测试内容**：
- E2E 测试 - 测试完整用户流程
- 跨浏览器测试 - Chrome、Firefox、Safari
- 性能测试 - 页面加载时间、API 响应时间
**通过标准**：
- [ ] 功能在预发布环境正常运行
- [ ] 与生产环境配置一致
- [ ] 无跨环境兼容性问题
## 第三阶段：生产环境
**测试内容**：
- UAT 验收 - 用户验收测试
- 冒烟测试 - 核心功能快速验证
- 回归测试 - 确保未破坏现有功能
**通过标准**：
- [ ] 功能在生产环境正常运行
- [ ] 用户验收通过
- [ ] 无生产环境特有问题
## API 验证清单
```bash
# 1. 本机环境
curl -s "http://localhost:8080/api/v1/requirements?search=REQ-2026" \
-H "Authorization: Bearer $TOKEN" | jq '.data | length'
# 2. 预发布环境
curl -s "https://staging.ai.pipexerp.com/api/v1/requirements?search=REQ-2026" \
-H "X-API-Key: $SYNC_REMOTE_API_KEY" | jq '.data | length'
# 3. 生产环境
curl -s "https://ai.pipexerp.com/api/v1/requirements?search=REQ-2026" \
-H "X-API-Key: $SYNC_REMOTE_API_KEY" | jq '.data | length'
```
## 测试失败处理
| 失败阶段 | 处理方式 |
|---------|---------|
| 本机测试 | 修复代码，重新运行本机测试 |
| 预发布测试 | 修复代码，重新从本机测试开始 |
| 生产环境测试 | 修复代码，重新从本机测试开始 |
> 任何阶段测试失败，修复后必须从本机测试环境重新开始。

120
skills-req/req-plugin/workflow-example.md
View File

@@ -1,120 +0,0 @@
# 完整开发工作流示例
以「酷采3.0 标签管理模块」为例的完整需求生命周期。
## 第一步：创建需求
```bash
/req new 酷采3.0 商品标签管理模块
```
执行：`mcp__ai-proj__create_requirement` → 自动分配 display_id（如 REQ-2026-0006）
## 第二步：编写 PRD 文档
调用 `req-prd` 技能：
1. 创建 PRD 任务并关联到需求
2. 调用 `mcp__ai-proj__create-and-attach` 写入 PRD 文档
## 第三步：创建开发子任务
```python
# 创建子任务
mcp__ai-proj__create_subtask(parentId=PRD任务ID, title="后端：数据模型设计")
mcp__ai-proj__create_subtask(parentId=PRD任务ID, title="后端：Store/Biz实现")
mcp__ai-proj__create_subtask(parentId=PRD任务ID, title="后端：API Handler实现")
mcp__ai-proj__create_subtask(parentId=PRD任务ID, title="前端：页面开发")
# 批量关联到需求
mcp__ai-proj__link_tasks_to_requirement(requirementId=需求ID, taskIds=[...])
```
## 第四步：提交并审批需求
```bash
/req review # draft → pending
/req review pass # pending → approved
```
## 第五步：执行开发任务
```bash
/req dev REQ-2026-0006
```
按分层架构开发：Model → Store → Biz → Handler → Router
## 第六步：代码评审
```bash
/req cr REQ-2026-0006
```
开发完成后必须进行代码评审，评审通过后才能进入测试。
## 第七步：创建测试任务
```python
mcp__ai-proj__create_subtask(parentId=测试父任务, title="后端：单元测试")
mcp__ai-proj__create_subtask(parentId=测试父任务, title="后端：集成测试")
mcp__ai-proj__create_subtask(parentId=测试父任务, title="E2E：端到端测试")
mcp__ai-proj__create_subtask(parentId=测试父任务, title="UAT：用户验收测试")
```
## 第八步：执行测试
```bash
/req test REQ-2026-0006
```
按环境顺序：本机 → 预发布 → 生产
## 第九步：CI/CD 发布
```bash
/req deploy REQ-2026-0006 --env staging
```
## 第十步：完成归档
```bash
/req done REQ-2026-0006
```
自动生成需求生命周期总结文档，归档需求。
---
## 标准任务结构
```
需求: REQ-2026-XXXX
├── PRD 任务 (父任务，包含 PRD 文档)
│ ├── 后端：数据模型设计 (implementation)
│ ├── 后端：业务层实现 (implementation)
│ ├── 后端：API 实现 (implementation)
│ └── 前端：页面开发 (implementation)
│
├── 代码评审任务 (code_review) ← 必须步骤
│
├── 测试任务 (父任务)
│ ├── 单元测试 (test)
│ ├── 集成测试 (test)
│ ├── E2E测试 (test)
│ └── UAT验收 (test, 包含测试报告)
│
└── 发布任务 (父任务，包含发布记录)
├── Docker 镜像构建 (deploy)
├── 前端资源构建 (deploy)
└── 部署到环境 (deploy)
```
## 5 阶段文档
| 序号 | 文档 | 阶段 |
|------|------|------|
| 01 | PRD | 需求定义 |
| 02 | 开发设计 | 开发实现 |
| 03 | 测试报告 | 测试验收 |
| 04 | 发布记录 | CI/CD部署 |
| 05 | 生命周期总结 | 归档 |

113
skills-req/req-prd-plugin/skills/SKILL.md
View File

@@ -1,6 +1,6 @@
---
name: req-prd
description: 产品设计与需求管理。用于 PRD 文档编写、需求分析、用户故事创建、功能设计和原型规划。当用户提到产品设计、PRD、需求文档、功能规划、用户故事相关任务时自动激活。
description: 产品设计与需求管理。用于 PRD 文档编写、需求分析、用户故事创建、功能设计和原型规划、PRD 评审。当用户提到产品设计、PRD、需求文档、功能规划、用户故事、PRD 评审相关任务时自动激活。
---
# 产品需求设计 Skill (req-prd)
@@ -657,3 +657,114 @@ mcp__ai-proj__export_task_document_to_file
- 数据安全分级
- 敏感操作审计
- 权限最小化原则
---
## PRD 评审方法论
PRD 评审是需求流程的关键质量关卡。
### 评审流程
```
PRD 提交 → 结构检查 → 清晰度评估 → 技术可行性 → 数据模型 → API 审查 → 结论
```
### 结构完整性检查
| 检查项 | 必须 | 说明 |
|--------|:----:|------|
| 基本信息 | ✓ | 编号、标题、日期、作者 |
| 需求背景 | ✓ | 为什么需要这个功能 |
| 目标用户 | ✓ | 面向的用户群体 |
| 功能描述 | ✓ | 详细功能需求 |
| 数据模型 | ✓ | 数据库表结构 |
| API 设计 | ✓ | RESTful 接口 |
| 验收标准 | ✓ | 验收条件 |
| 用户故事 | ○ | As a... I want... |
| 页面原型 | ○ | 界面布局 |
| 非功能需求 | ○ | 性能、安全 |
### 需求清晰度（SMART 原则）
| 原则 | 检查点 |
|------|--------|
| **S**pecific | 描述是否具体明确 |
| **M**easurable | 是否有量化指标 |
| **A**chievable | 技术上是否可行 |
| **R**elevant | 是否与业务目标相关 |
| **T**ime-bound | 是否有时间范围 |
**示例**：
- ❌ "用户可以搜索需求"
- ✅ "用户可按编号精确搜索、按标题模糊搜索、按状态筛选，结果分页显示"
### 技术可行性
| 维度 | 评估内容 |
|------|----------|
| 技术栈兼容 | 现有栈是否支持 |
| 架构影响 | 是否需修改架构 |
| 第三方依赖 | 是否引入新依赖 |
| 性能影响 | 潜在性能问题 |
| 安全考量 | 安全风险 |
### 数据模型验证
| 检查项 | 说明 |
|--------|------|
| 表结构 | 字段类型、约束、索引 |
| 关联关系 | 外键、多对多 |
| 命名规范 | 符合项目规范 |
| 扩展性 | 预留扩展字段 |
| 查询性能 | 常用查询有索引 |
### API 设计审查
| 检查项 | 标准 |
|--------|------|
| RESTful | URL 用名词，HTTP 方法语义正确 |
| 响应格式 | `{success, data, message}` |
| 错误处理 | 明确的错误码 |
| 分页 | `?page=1&page_size=20` |
| 版本控制 | `/api/v1/...` |
### 评审结论模板
**通过**：
```
✅ PRD 评审通过
【结论】文档完整，需求清晰，方案可行，建议批准。
【肯定】需求背景清晰、数据模型合理、API 规范
【建议】（非阻塞）补充性能测试用例
【评审人】xxx 【时间】2026-xx-xx
```
**驳回**：
```
❌ PRD 评审驳回
【原因】
1. 数据模型缺少索引
2. API 缺少错误处理
3. 搜索需求描述模糊
【修改要求】
□ 补充索引设计
□ 明确错误码
□ 细化搜索实现
【驳回人】xxx 【时间】2026-xx-xx
```
### 常见驳回原因
| 类别 | 问题 | 建议 |
|------|------|------|
| 结构缺失 | 缺数据模型或 API | 补充技术设计 |
| 需求模糊 | 描述不具体 | 按 SMART 重写 |
| 边界不清 | 缺异常处理 | 补充边界条件 |
| 设计缺陷 | 模型/API 不合理 | 重新设计 |
| 范围过大 | 难以实现 | 拆分为多需求 |
| 验收不明 | 缺验收标准 | 补充验收条件 |

8
skills-req/req-review-plugin/.claude-plugin/plugin.json
View File

@@ -1,8 +0,0 @@
{
"name": "req-review-plugin",
"description": "PRD 评审方法论。用于需求评审、PRD 文档审查、评审意见编写。当执行 /req review 或需要评审 PRD 文档时使用。",
"version": "1.0.0",
"author": {
"name": "qiudl"
}
}

113
skills-req/req-review-plugin/skills/SKILL.md
View File

@@ -1,113 +0,0 @@
---
name: req-review
description: PRD 评审方法论。用于需求评审、PRD 文档审查、评审意见编写。当执行 /req review 或需要评审 PRD 文档时使用。
---
# PRD 评审方法论
PRD 评审是需求流程的关键质量关卡。
## 评审流程
```
PRD 提交 → 结构检查 → 清晰度评估 → 技术可行性 → 数据模型 → API 审查 → 结论
```
## 结构完整性检查
| 检查项 | 必须 | 说明 |
|--------|:----:|------|
| 基本信息 | ✓ | 编号、标题、日期、作者 |
| 需求背景 | ✓ | 为什么需要这个功能 |
| 目标用户 | ✓ | 面向的用户群体 |
| 功能描述 | ✓ | 详细功能需求 |
| 数据模型 | ✓ | 数据库表结构 |
| API 设计 | ✓ | RESTful 接口 |
| 验收标准 | ✓ | 验收条件 |
| 用户故事 | ○ | As a... I want... |
| 页面原型 | ○ | 界面布局 |
| 非功能需求 | ○ | 性能、安全 |
## 需求清晰度（SMART 原则）
| 原则 | 检查点 |
|------|--------|
| **S**pecific | 描述是否具体明确 |
| **M**easurable | 是否有量化指标 |
| **A**chievable | 技术上是否可行 |
| **R**elevant | 是否与业务目标相关 |
| **T**ime-bound | 是否有时间范围 |
**示例**：
- ❌ "用户可以搜索需求"
- ✅ "用户可按编号精确搜索、按标题模糊搜索、按状态筛选，结果分页显示"
## 技术可行性
| 维度 | 评估内容 |
|------|----------|
| 技术栈兼容 | 现有栈是否支持 |
| 架构影响 | 是否需修改架构 |
| 第三方依赖 | 是否引入新依赖 |
| 性能影响 | 潜在性能问题 |
| 安全考量 | 安全风险 |
## 数据模型验证
| 检查项 | 说明 |
|--------|------|
| 表结构 | 字段类型、约束、索引 |
| 关联关系 | 外键、多对多 |
| 命名规范 | 符合项目规范 |
| 扩展性 | 预留扩展字段 |
| 查询性能 | 常用查询有索引 |
## API 设计审查
| 检查项 | 标准 |
|--------|------|
| RESTful | URL 用名词，HTTP 方法语义正确 |
| 响应格式 | `{success, data, message}` |
| 错误处理 | 明确的错误码 |
| 分页 | `?page=1&page_size=20` |
| 版本控制 | `/api/v1/...` |
## 评审结论模板
**通过**：
```
✅ PRD 评审通过
【结论】文档完整，需求清晰，方案可行，建议批准。
【肯定】需求背景清晰、数据模型合理、API 规范
【建议】（非阻塞）补充性能测试用例
【评审人】xxx 【时间】2026-xx-xx
```
**驳回**：
```
❌ PRD 评审驳回
【原因】
1. 数据模型缺少索引
2. API 缺少错误处理
3. 搜索需求描述模糊
【修改要求】
□ 补充索引设计
□ 明确错误码
□ 细化搜索实现
【驳回人】xxx 【时间】2026-xx-xx
```
## 常见驳回原因
| 类别 | 问题 | 建议 |
|------|------|------|
| 结构缺失 | 缺数据模型或 API | 补充技术设计 |
| 需求模糊 | 描述不具体 | 按 SMART 重写 |
| 边界不清 | 缺异常处理 | 补充边界条件 |
| 设计缺陷 | 模型/API 不合理 | 重新设计 |
| 范围过大 | 难以实现 | 拆分为多需求 |
| 验收不明 | 缺验收标准 | 补充验收条件 |

8
skills-req/req-workflow-plugin/.claude-plugin/plugin.json
View File

@@ -1,8 +0,0 @@
{
"name": "req-workflow-plugin",
"description": "需求完整工作流。用于从创建到归档的完整流程、Hook 自动同步、测试环境流程。当需要了解需求完整生命周期或同步策略时使用。",
"version": "1.0.0",
"author": {
"name": "qiudl"
}
}

198
skills-req/req-workflow-plugin/skills/SKILL.md
View File

@@ -1,198 +0,0 @@
---
name: req-workflow
description: 需求完整工作流。用于从创建到归档的完整流程、Hook 自动同步、测试环境流程。当需要了解需求完整生命周期或同步策略时使用。
---
# 需求完整工作流
从 PRD 到归档的完整流程。
## 需求创建环境选择
> **重要**：正式需求应直接在**生产环境** (`mcp__ai-proj-prod__*`) 创建。
> 仅在功能测试、流程验证时使用开发环境 (`mcp__ai-proj-dev__*`)。
> 如果在开发环境创建了需求后同步到生产，`due_date`、`reviewer_id`、`allow_self_approve` 等字段会丢失，需手动补充。
## 完整流程概览（阶段化）
```
1. /req new → 创建需求 (draft)
2. req-prd 技能 → 编写 PRD（创建【评审】PRD 任务）
3. /req review → 提交评审 (pending)
4. /req review pass → 评审通过 (approved, delivery_stage=analysis)
5. /req next → 推进到 design/dev 阶段
6. /req dev → 启动开发（创建【开发】任务, delivery_stage=dev）
7. req-dev 技能 → 编写开发文档
8. /req next → 推进到 review 阶段
9. /req cr → 代码评审（创建【代码评审】任务, delivery_stage=review）
10. /req next → 推进到 testing 阶段
11. /req test → 测试验收（创建【测试】任务, delivery_stage=testing）
12. /req next → 推进到 staging 阶段
13. /req deploy staging → 部署 staging（创建【部署】任务, delivery_stage=staging）
14. /req next → 推进到 released 阶段
15. /req deploy prod → 部署生产（创建【部署】任务, delivery_stage=released）
16. /req done → 归档 (archived)
```
**每个阶段都有明确的任务、检查点和交付物，防止遗漏。**
## 5 阶段文档
| 阶段 | 文档名 | 技能 |
|------|--------|------|
| PRD | 01-PRD.md | `req-prd` |
| 开发 | 02-开发设计.md | `req-dev` |
| 测试 | 03-测试报告.md | 自动生成 |
| 发布 | 04-发布记录.md | 自动生成 |
| 归档 | 05-生命周期总结.md | 自动生成 |
## Hook 自动同步
需求操作自动触发同步，无需手动执行：
| 事件 | 触发操作 |
|------|----------|
| `requirement.created` | 同步到远程 |
| `requirement.approved` | 同步需求和任务 |
| `task.completed` | 同步任务状态 |
| `requirement.archived` | 最终同步 + 思源笔记 |
**手动同步**（如需）：
```typescript
mcp__ai-proj__sync_requirement_to_remote(requirementId)
mcp__ai-proj__batch_sync_tasks_to_remote(taskIds)
```
**同步已知限制**：
| 字段 | 同步支持 | 说明 |
|------|----------|------|
| title, description, status, priority | ✅ | 正常同步 |
| project_id | ✅ | 正常同步 |
| **due_date** | ❌ | **不会同步**，需手动通过 REST API 在目标环境补充 |
| reviewer_id | ❌ | 不会同步 |
| allow_self_approve | ❌ | 不会同步 |
> **经验教训**（2026-02-20）：`sync_requirement_to_remote` 不同步 `due_date` 字段。同步后务必在目标环境验证并手动补充缺失字段。
## 测试环境流程
**必须按顺序执行，任何阶段失败后从本机重新开始**：
```
[本机] → 通过 → [预发布] → 通过 → [生产]
↑ │ │
└─────────────────┴──── 失败 ────┘
```
| 环境 | 用途 | 验证方式 |
|------|------|----------|
| 本机 | 开发调试 | `go test ./...` |
| 预发布 | 集成测试 | API 验证 |
| 生产 | 最终验收 | API + 功能验证 |
## 任务关联规范
创建任务时设置 `link_role` 并加阶段前缀：
| 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% |
**进度计算**：按 link_role 权重统计已完成任务。
## 标准任务结构（阶段化）
```
需求 REQ-xxx
├── 📝 analysis 阶段
│ └── 【评审】PRD: {需求标题} (linkRole: prd)
├── 📐 design 阶段
│ └── 【评审】技术设计: {需求标题} (linkRole: design)
├── 💻 dev 阶段
│ ├── 【开发-后端】{描述} (linkRole: implementation)
│ └── 【开发-前端】{描述} (linkRole: implementation)
├── 🔍 review 阶段
│ └── 【代码评审】CR: {需求标题} (linkRole: code_review)
├── 🧪 testing 阶段
│ └── 【测试】集成测试: {需求标题} (linkRole: test)
├── 🚀 staging 阶段
│ └── 【部署】部署到 staging (singapore) (linkRole: deploy)
└── 🏁 released 阶段
├── 【部署】部署到 prod (tools_ai_proj) (linkRole: deploy)
└── 【验收】功能验收确认 (linkRole: documentation)
```
**命名规则**：所有任务标题必须以阶段前缀开头（如【评审】、【开发】、【部署】）。
## 环境配置
**双环境 MCP 配置**：区分开发测试和生产环境
```json
// ~/.claude/.mcp.json
{
"mcpServers": {
"ai-proj-dev": {
"type": "stdio",
"command": "node",
"args": ["/path/to/mcp-task-bridge/dist/index.js"],
"env": {
"TASK_API_BASE": "http://localhost:8080/api/v1",
"TASK_API_TOKEN": "aiproj_pk_xxx...",
"NODE_ENV": "development"
}
},
"ai-proj-prod": {
"type": "stdio",
"command": "node",
"args": ["/path/to/mcp-task-bridge/dist/index.js"],
"env": {
"TASK_API_BASE": "https://ai.pipexerp.com/api/v1",
"TASK_API_TOKEN": "aiproj_pk_xxx...",
"NODE_ENV": "production"
}
}
}
}
```
**环境使用指南**：
| 环境 | 使用场景 | 工具前缀 |
|------|----------|----------|
| `ai-proj-dev` | 功能测试、流程验证、本地调试 | `mcp__ai-proj-dev__*` |
| `ai-proj-prod` | 正式需求管理、生产数据操作 | `mcp__ai-proj-prod__*` |
**跨机器支持**：
- `ai-proj-dev` 支持 melbourne 和 adelaide 机器的本地环境（都是 localhost:8080）
- 无论在哪台开发机器上，都使用 `ai-proj-dev` 连接本地 API
**项目配置**：
```json
// .claude/settings.local.json
{
"env": {
"REQUIREMENT_PROJECT": "coolbuy-paas"
}
}
```
## 思源笔记集成
归档时自动同步 5 阶段文档到思源笔记：
- 路径：`需求管理/REQ-XXXX/`
- 文档：01-PRD.md ~ 05-生命周期总结.md
手动同步：`/req sync-siyuan [REQ-ID]`
## 邮件通知
发送邮件：`/req notify [REQ-ID] --type <prd|dev|test|deploy|archive>`
默认收件人：项目邮件组（见项目配置）

8
skills-req/requirement-plugin/.claude-plugin/plugin.json
View File

@@ -1,8 +0,0 @@
{
"name": "requirement-plugin",
"description": "[已废弃] 需求撰写功能已合并到 req-plugin。请使用 /req 命令。",
"version": "2.0.0",
"author": {
"name": "qiudl"
}
}

30
skills-req/requirement-plugin/skills/SKILL.md
View File

@@ -1,30 +0,0 @@
---
name: requirement
description: "[已废弃] 请使用 /req 命令。需求撰写功能已合并到 req 技能中。"
arguments: <subcommand> [args]
---
# Requirement 技能 - 已合并到 req
> **此技能已废弃。** 所有需求撰写命令已合并到 `req` 技能中。
## 命令迁移对照
| 原命令 | 新命令 | 说明 |
|--------|--------|------|
| `/requirement new` | `/req new` | 对话式创建需求（仅创建草稿） |
| `/requirement draft <描述>` | `/req draft <描述>` | 快速生成需求草稿 |
| `/requirement edit <ID>` | `/req edit <ID>` | 编辑需求内容 |
| `/requirement review <ID>` | `/req check <ID>` | 需求完整性检查 |
| `/requirement split <ID>` | `/req split <ID>` | 拆分为开发任务 |
| `/requirement history <ID>` | `/req history <ID>` | 查看变更历史 |
| `/requirement compare <ID>` | `/req compare <ID>` | 版本对比 |
| `/requirement list` | `/req` 或 `/req list` | 列出需求 |
## 重要变更
- 需求创建后**只能是 draft 状态**，禁止自动提交
- 从 draft 到提交评审需通过 **4 道门禁**（讨论 → 确认 → PRD → 完整性检查）
- 提交评审使用 `/req submit`（原 `/req review`）
请使用 `/req` 命令，详细参考见 `req` 和 `req-commands` 技能。