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

refactor: 通用技能按类别拆分为独立目录

Browse Source 
skills/ → skills-dev(9), skills-req(10), skills-ops(4),
skills-integration(8), skills-biz(4), skills-workflow(7)

generate-marketplace.py 改为自动扫描所有 skills-* 目录。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
John Qiu
2026-03-14 11:31:58 +10:30
parent ea266e9cce
commit 712063071c
170 changed files with 341 additions and 346 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
skills-req/req-plugin/.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,8 @@
{
"name": "req-plugin",
"description": "需求工作流管理入口。用于 /req 命令使用、需求生命周期管理、需求撰写（含草稿门禁）。",
"version": "2.0.0",
"author": {
"name": "qiudl"
}
}

111
skills-req/req-plugin/README.md Normal file
View File

@@ -0,0 +1,111 @@
# req - 需求全流程工作流管理技能
> 版本: v3.9.0 | 更新日期: 2026-01-25
## 概述
`req` 技能是一个深度集成 ai-proj MCP 工具的需求管理解决方案，支持需求全生命周期管理：从创建、评审、开发、测试到发布归档。
## 快速开始
```bash
# 列出待处理需求
/req list
# 创建新需求
/req new 商品管理模块
# 开始开发
/req dev REQ-2026-0001
# 提交评审
/req review REQ-2026-0001
# 归档完成
/req done REQ-2026-0001
```
## 核心命令
| 命令 | 功能 |
|------|------|
| `/req` 或 `/req list` | 列出需求 |
| `/req new [标题]` | 创建新需求 |
| `/req dev [REQ-ID]` | 开始开发 |
| `/req test [REQ-ID]` | 执行测试 |
| `/req review [REQ-ID]` | 提交评审 |
| `/req done [REQ-ID]` | 归档需求 |
| `/req status [REQ-ID]` | 查看状态 |
## 扩展命令 (v3.3.0+)
| 命令 | 功能 |
|------|------|
| `/req priority [REQ-ID] [high/medium/low]` | 设置优先级 |
| `/req depends [REQ-ID] --on [REQ-ID]` | 设置依赖 |
| `/req deadline [REQ-ID] [日期]` | 设置截止日期 |
| `/req sprint [REQ-ID] [sprint-id]` | 分配迭代 |
| `/req assign [REQ-ID] [用户]` | 指派负责人 |
| `/req generate-tasks [REQ-ID]` | 自动生成任务 |
| `/req stats [REQ-ID]` | 查看统计 |
## Hook 自动同步 (v3.5.0+)
支持在以下事件自动触发同步：
- `requirement.created` - 创建需求
- `requirement.approved` - 需求审批通过
- `requirement.archived` - 需求归档
- `task.completed` - 任务完成
- `document.updated` - 文档更新
## 多人审批 (v3.7.0+)
```bash
/req review pass REQ-2026-0001 # 审批通过
/req review reject REQ-2026-0001 # 审批拒绝
/req review status REQ-2026-0001 # 查看审批状态
```
## 需求状态流转
```
draft → pending → reviewing → approved → archived
↓
rejected
```
## 文件结构
```
~/.claude/skills/req/
├── SKILL.md # 完整技能文档
├── README.md # 本文件
├── notify.sh # 邮件通知脚本
└── update-siyuan-release.sh # 思源笔记更新脚本
```
## 依赖
- **ai-proj MCP 服务** - 需求、任务、文档管理
- **思源笔记 MCP** - 文档同步（可选）
- **邮件服务** - 通知功能（可选）
## 详细文档
完整命令说明、配置选项和使用示例请参阅 [SKILL.md](./SKILL.md)。
## 版本历史
| 版本 | 日期 | 主要变更 |
|------|------|----------|
| v3.9.0 | 2026-01-25 | 生产环境截图验证必须步骤 |
| v3.8.0 | 2026-01-13 | 废弃命令文档化 |
| v3.7.0 | 2026-01-13 | 多人审批增强 |
| v3.6.0 | 2026-01-13 | new/dev/done 命令增强 |
| v3.5.0 | 2026-01-13 | Hook 自动同步机制 |
| v3.4.0 | 2026-01-13 | generate-tasks, stats 命令 |
| v3.3.0 | 2026-01-13 | priority/depends/deadline/sprint/assign 命令 |
---
*由 Claude AI 维护*

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

@@ -0,0 +1,115 @@
# 代码评审指南 (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 Normal file
View File

@@ -0,0 +1,273 @@
# 部署指南
## 部署流程概览
```
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 ...
```

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

@@ -0,0 +1,115 @@
# 代码评审指南 (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/docs/deploy-guide.md Normal file
View File

@@ -0,0 +1,273 @@
# 部署指南
## 部署流程概览
```
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/docs/hook-sync.md Normal file
View File

@@ -0,0 +1,55 @@
# 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/docs/mcp-auth-config.md Normal file
View File

@@ -0,0 +1,64 @@
# 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/docs/notification-config.md Normal file
View File

@@ -0,0 +1,42 @@
# 通知与自动化配置
## 邮件通知
### 默认邮件组
| 收件人 |
|--------|
| 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/docs/prd-review-guide.md Normal file
View File

@@ -0,0 +1,126 @@
# 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/docs/siyuan-integration.md Normal file
View File

@@ -0,0 +1,50 @@
# 思源笔记集成
需求的 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"
```

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

@@ -0,0 +1,177 @@
# 测试环境流程指南
> 测试必须按照以下环境顺序依次进行，每个环境通过后才能进入下一个环境。
## 测试环境流程
```
[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/docs/workflow-example.md Normal file
View File

@@ -0,0 +1,120 @@
# 完整开发工作流示例
以「酷采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 | 生命周期总结 | 归档 |

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

@@ -0,0 +1,55 @@
# 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 Normal file
View File

@@ -0,0 +1,64 @@
# 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 Normal file
View File

@@ -0,0 +1,42 @@
# 通知与自动化配置
## 邮件通知
### 默认邮件组
| 收件人 |
|--------|
| 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/ |

455
skills-req/req-plugin/notify.sh Executable file
View File

@@ -0,0 +1,455 @@
#!/bin/bash
# REQ 需求发布通知脚本 v3.2.0
# 用于在需求发布完成后发送邮件通知到邮件组
# 功能：HTML正文(含文档内容) + Markdown附件
# ==================== 配置 ====================
# 默认邮件组
DEFAULT_EMAIL_GROUP=(
"qiudl@zhiyuncai.com"
"fuxing@zhiyuncai.com"
"haiqing@zhiyuncai.com"
"wuweier@zhiyuncai.com"
)
# 思源笔记配置
SIYUAN_API_URL="${SIYUAN_URL:-http://100.118.62.18:6806}"
SIYUAN_TOKEN="${SIYUAN_TOKEN:-nfnycjb1g8vbexb2}"
SIYUAN_NOTEBOOK_NAME="需求管理"
# 发件人
FROM_NAME="REQ 需求管理系统"
# 临时目录
TMP_DIR="/tmp/req-notify-$$"
# ==================== 函数定义 ====================
# 使用方法
usage() {
echo "Usage: $0 -r <REQ-ID> -t <type> [-e <emails>] [-m <message>] [-a <attachment>] [-n]"
echo ""
echo "Options:"
echo " -r REQ-ID 需求编号 (如 REQ-2026-0007)"
echo " -t type 通知类型: prd|dev|test|deploy|archive"
echo " -e emails 收件人邮箱，多个用逗号分隔 (覆盖默认邮件组)"
echo " -a attachment 附件文件路径 (可选，覆盖自动获取)"
echo " -n 不附加文档 (仅发送通知)"
echo " -m message 附加消息"
echo " -h 显示帮助"
echo ""
echo "默认邮件组 (${#DEFAULT_EMAIL_GROUP[@]} 人):"
for email in "${DEFAULT_EMAIL_GROUP[@]}"; do
echo " - $email"
done
echo ""
echo "通知类型与文档映射:"
echo " prd → 01-PRD"
echo " dev → 02-开发设计"
echo " test → 03-测试报告"
echo " deploy → 04-发布记录"
echo " archive → 05-生命周期总结"
exit 1
}
# 清理临时文件
cleanup() {
rm -rf "$TMP_DIR" 2>/dev/null
}
trap cleanup EXIT
# 从思源笔记获取文档内容
fetch_siyuan_doc() {
local doc_path="$1"
local output_file="$2"
echo "正在从思源笔记获取文档: $doc_path"
# 1. 先查询文档 ID
local query="SELECT id, content FROM blocks WHERE type='d' AND hpath LIKE '%${doc_path}%' LIMIT 1"
local response=$(curl -s -X POST "${SIYUAN_API_URL}/api/query/sql" \
-H "Authorization: Token ${SIYUAN_TOKEN}" \
-H "Content-Type: application/json" \
-d "{\"stmt\": \"${query}\"}")
local doc_id=$(echo "$response" | jq -r '.data[0].id // empty')
if [ -z "$doc_id" ]; then
echo "警告: 未找到文档 $doc_path"
return 1
fi
# 2. 导出文档为 Markdown
local export_response=$(curl -s -X POST "${SIYUAN_API_URL}/api/export/exportMdContent" \
-H "Authorization: Token ${SIYUAN_TOKEN}" \
-H "Content-Type: application/json" \
-d "{\"id\": \"${doc_id}\"}")
local content=$(echo "$export_response" | jq -r '.data.content // empty')
if [ -z "$content" ]; then
echo "警告: 文档内容为空"
return 1
fi
# 3. 保存到文件
echo "$content" > "$output_file"
echo "文档已保存: $output_file ($(wc -c < "$output_file") 字节)"
return 0
}
# 根据通知类型获取文档路径
get_doc_path() {
local req_id="$1"
local notify_type="$2"
case $notify_type in
prd) echo "/${req_id}/01-PRD" ;;
dev) echo "/${req_id}/02-开发设计" ;;
test) echo "/${req_id}/03-测试报告" ;;
deploy) echo "/${req_id}/04-发布记录" ;;
archive) echo "/${req_id}/05-生命周期总结" ;;
*) echo "" ;;
esac
}
# 获取文档文件名
get_doc_filename() {
local req_id="$1"
local notify_type="$2"
case $notify_type in
prd) echo "${req_id}_01-PRD.md" ;;
dev) echo "${req_id}_02-开发设计.md" ;;
test) echo "${req_id}_03-测试报告.md" ;;
deploy) echo "${req_id}_04-发布记录.md" ;;
archive) echo "${req_id}_05-生命周期总结.md" ;;
*) echo "${req_id}_文档.md" ;;
esac
}
# 获取通知标题
get_subject() {
local req_id="$1"
local notify_type="$2"
case $notify_type in
prd) echo "[REQ-PRD] ${req_id} PRD文档已完成" ;;
dev) echo "[REQ-开发] ${req_id} 开发完成" ;;
test) echo "[REQ-测试] ${req_id} 测试完成" ;;
deploy) echo "[REQ-发布] ${req_id} 已成功发布" ;;
archive) echo "[REQ-归档] ${req_id} 已归档" ;;
*) echo "[REQ] ${req_id} 通知" ;;
esac
}
# 获取通知类型描述
get_type_desc() {
local notify_type="$1"
case $notify_type in
prd) echo "PRD文档完成" ;;
dev) echo "开发完成" ;;
test) echo "测试完成" ;;
deploy) echo "发布完成" ;;
archive) echo "需求归档" ;;
*) echo "状态更新" ;;
esac
}
# 将 Markdown 转换为 HTML (简单转换)
markdown_to_html() {
local md_content="$1"
# 转义 HTML 特殊字符
local escaped=$(echo "$md_content" | sed 's/&/\&amp;/g; s/</\&lt;/g; s/>/\&gt;/g')
# 转换标题
escaped=$(echo "$escaped" | sed -E 's/^### (.*)$/<h3>\1<\/h3>/g')
escaped=$(echo "$escaped" | sed -E 's/^## (.*)$/<h2>\1<\/h2>/g')
escaped=$(echo "$escaped" | sed -E 's/^# (.*)$/<h1>\1<\/h1>/g')
# 转换粗体
escaped=$(echo "$escaped" | sed -E 's/\*\*([^*]+)\*\*/<strong>\1<\/strong>/g')
# 转换代码块
escaped=$(echo "$escaped" | sed -E 's/`([^`]+)`/<code>\1<\/code>/g')
# 转换列表项
escaped=$(echo "$escaped" | sed -E 's/^- (.*)$/<li>\1<\/li>/g')
escaped=$(echo "$escaped" | sed -E 's/^\* (.*)$/<li>\1<\/li>/g')
# 转换复选框
escaped=$(echo "$escaped" | sed 's/\[x\]/✅/g; s/\[ \]/⬜/g')
# 转换表格分隔线（简化处理）
escaped=$(echo "$escaped" | sed '/^|[-|]*$/d')
# 转换表格行
escaped=$(echo "$escaped" | sed -E 's/^\| (.+) \|$/<tr><td>\1<\/td><\/tr>/g')
escaped=$(echo "$escaped" | sed 's/ \| /<\/td><td>/g')
# 转换换行
escaped=$(echo "$escaped" | sed 's/$/<br>/g')
# 转换水平线
escaped=$(echo "$escaped" | sed 's/^---$/<hr>/g')
echo "$escaped"
}
# 生成邮件正文 (HTML格式，包含文档内容)
generate_body_html() {
local req_id="$1"
local notify_type="$2"
local timestamp="$3"
local extra_message="$4"
local doc_path="$5"
local doc_content="$6"
local type_desc=$(get_type_desc "$notify_type")
# 转换文档内容为 HTML
local doc_html=""
if [ -n "$doc_content" ]; then
doc_html=$(markdown_to_html "$doc_content")
fi
cat <<EOF
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<style>
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; line-height: 1.6; color: #333; max-width: 900px; margin: 0 auto; padding: 20px; }
.header { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; padding: 30px; border-radius: 10px 10px 0 0; }
.header h1 { margin: 0 0 10px 0; font-size: 24px; }
.header .req-id { font-size: 18px; opacity: 0.9; }
.summary { background: #f8f9fa; padding: 20px 30px; border: 1px solid #e9ecef; }
.info-table { width: 100%; border-collapse: collapse; margin: 15px 0; }
.info-table td { padding: 10px 15px; border-bottom: 1px solid #dee2e6; }
.info-table td:first-child { font-weight: 600; color: #495057; width: 100px; }
.status-badge { display: inline-block; padding: 4px 12px; border-radius: 15px; font-size: 13px; font-weight: 600; }
.status-success { background: #d4edda; color: #155724; }
.doc-section { background: #fff; border: 1px solid #e9ecef; border-top: none; padding: 30px; }
.doc-title { background: #343a40; color: white; padding: 15px 30px; margin: 0; font-size: 16px; }
.doc-content { font-size: 14px; line-height: 1.8; }
.doc-content h1 { font-size: 22px; color: #2c3e50; border-bottom: 2px solid #667eea; padding-bottom: 10px; margin-top: 25px; }
.doc-content h2 { font-size: 18px; color: #34495e; margin-top: 20px; }
.doc-content h3 { font-size: 16px; color: #495057; margin-top: 15px; }
.doc-content code { background: #f4f4f4; padding: 2px 6px; border-radius: 3px; font-family: 'SF Mono', Monaco, monospace; font-size: 13px; }
.doc-content table { border-collapse: collapse; width: 100%; margin: 15px 0; }
.doc-content td, .doc-content th { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
.doc-content tr:nth-child(even) { background: #f9f9f9; }
.doc-content li { margin: 5px 0; }
.doc-content hr { border: none; border-top: 1px solid #eee; margin: 20px 0; }
.footer { background: #f1f3f4; padding: 15px 30px; border-radius: 0 0 10px 10px; font-size: 12px; color: #666; text-align: center; }
</style>
</head>
<body>
<div class="header">
<h1>📋 需求${type_desc}通知</h1>
<div class="req-id">${req_id}</div>
</div>
<div class="summary">
<table class="info-table">
<tr><td>需求编号</td><td><strong>${req_id}</strong></td></tr>
<tr><td>通知类型</td><td>${type_desc}</td></tr>
<tr><td>完成时间</td><td>${timestamp}</td></tr>
<tr><td>状态</td><td><span class="status-badge status-success">✓ 已完成</span></td></tr>
</table>
$(if [ -n "$extra_message" ]; then echo "<p><strong>📝 说明：</strong>${extra_message}</p>"; fi)
</div>
$(if [ -n "$doc_html" ]; then
echo "<div class=\"doc-title\">📄 完整文档内容</div>"
echo "<div class=\"doc-section\"><div class=\"doc-content\">${doc_html}</div></div>"
fi)
<div class="footer">
此邮件由 <strong>REQ 需求管理系统</strong> 自动发送 | 文档同步自思源笔记：需求管理${doc_path}<br>
完整 Markdown 文档已作为附件发送
</div>
</body>
</html>
EOF
}
# 发送带附件的邮件 (MIME格式)
send_email_with_attachment() {
local recipient="$1"
local subject="$2"
local body_html="$3"
local attachment_file="$4"
local attachment_name="$5"
local boundary="----=_Part_$(date +%s)_$RANDOM"
# 读取附件内容并 base64 编码
local attachment_content=""
if [ -f "$attachment_file" ]; then
attachment_content=$(base64 < "$attachment_file")
fi
# 构建 MIME 邮件
{
echo "Subject: =?UTF-8?B?$(echo -n "$subject" | base64)?="
echo "To: $recipient"
echo "MIME-Version: 1.0"
echo "Content-Type: multipart/mixed; boundary=\"$boundary\""
echo ""
echo "--$boundary"
echo "Content-Type: text/html; charset=UTF-8"
echo "Content-Transfer-Encoding: base64"
echo ""
echo "$body_html" | base64
# 添加附件
if [ -n "$attachment_content" ]; then
echo ""
echo "--$boundary"
echo "Content-Type: text/markdown; charset=UTF-8; name=\"$attachment_name\""
echo "Content-Transfer-Encoding: base64"
echo "Content-Disposition: attachment; filename=\"$attachment_name\""
echo ""
echo "$attachment_content"
fi
echo ""
echo "--$boundary--"
} | msmtp "$recipient" 2>/dev/null
return $?
}
# ==================== 主程序 ====================
# 解析参数
REQ_ID=""
NOTIFY_TYPE=""
CUSTOM_EMAILS=""
CUSTOM_ATTACHMENT=""
NO_ATTACHMENT=false
EXTRA_MESSAGE=""
while getopts "r:t:e:a:m:nh" opt; do
case $opt in
r) REQ_ID="$OPTARG" ;;
t) NOTIFY_TYPE="$OPTARG" ;;
e) CUSTOM_EMAILS="$OPTARG" ;;
a) CUSTOM_ATTACHMENT="$OPTARG" ;;
n) NO_ATTACHMENT=true ;;
m) EXTRA_MESSAGE="$OPTARG" ;;
h) usage ;;
*) usage ;;
esac
done
# 验证必需参数
if [ -z "$REQ_ID" ] || [ -z "$NOTIFY_TYPE" ]; then
echo "Error: -r 和 -t 参数是必需的"
usage
fi
# 验证通知类型
case $NOTIFY_TYPE in
prd|dev|test|deploy|archive) ;;
*)
echo "Error: 未知的通知类型: $NOTIFY_TYPE"
echo "支持的类型: prd, dev, test, deploy, archive"
exit 1
;;
esac
# 构建收件人列表
declare -a RECIPIENTS
if [ -n "$CUSTOM_EMAILS" ]; then
IFS=',' read -ra RECIPIENTS <<< "$CUSTOM_EMAILS"
else
RECIPIENTS=("${DEFAULT_EMAIL_GROUP[@]}")
fi
# 获取时间戳
TIMESTAMP=$(date "+%Y-%m-%d %H:%M:%S")
# 获取文档信息
DOC_PATH=$(get_doc_path "$REQ_ID" "$NOTIFY_TYPE")
DOC_FILENAME=$(get_doc_filename "$REQ_ID" "$NOTIFY_TYPE")
SUBJECT=$(get_subject "$REQ_ID" "$NOTIFY_TYPE")
# 创建临时目录
mkdir -p "$TMP_DIR"
# 准备附件和文档内容
ATTACHMENT_FILE=""
DOC_CONTENT=""
if [ "$NO_ATTACHMENT" = false ]; then
if [ -n "$CUSTOM_ATTACHMENT" ] && [ -f "$CUSTOM_ATTACHMENT" ]; then
ATTACHMENT_FILE="$CUSTOM_ATTACHMENT"
DOC_CONTENT=$(cat "$ATTACHMENT_FILE")
echo "使用指定附件: $ATTACHMENT_FILE"
else
# 从思源笔记获取文档
ATTACHMENT_FILE="${TMP_DIR}/${DOC_FILENAME}"
if fetch_siyuan_doc "$DOC_PATH" "$ATTACHMENT_FILE"; then
DOC_CONTENT=$(cat "$ATTACHMENT_FILE")
else
echo "警告: 无法获取文档，将发送不带附件的邮件"
ATTACHMENT_FILE=""
fi
fi
fi
# 生成邮件正文（包含文档内容）
BODY_HTML=$(generate_body_html "$REQ_ID" "$NOTIFY_TYPE" "$TIMESTAMP" "$EXTRA_MESSAGE" "$DOC_PATH" "$DOC_CONTENT")
# 显示发送信息
echo "=========================================="
echo "📧 发送需求通知邮件"
echo "=========================================="
echo "需求编号: $REQ_ID"
echo "通知类型: $NOTIFY_TYPE ($(get_type_desc "$NOTIFY_TYPE"))"
echo "邮件主题: $SUBJECT"
echo "附件: $(if [ -n "$ATTACHMENT_FILE" ]; then echo "$DOC_FILENAME"; else echo "无"; fi)"
echo "收件人列表 (${#RECIPIENTS[@]} 人):"
for email in "${RECIPIENTS[@]}"; do
echo " 📬 $email"
done
echo "=========================================="
# 发送邮件
SUCCESS_COUNT=0
FAIL_COUNT=0
for RECIPIENT in "${RECIPIENTS[@]}"; do
RECIPIENT=$(echo "$RECIPIENT" | tr -d ' ')
if [ -z "$RECIPIENT" ]; then
continue
fi
if send_email_with_attachment "$RECIPIENT" "$SUBJECT" "$BODY_HTML" "$ATTACHMENT_FILE" "$DOC_FILENAME"; then
echo "✅ 已发送: $RECIPIENT"
((SUCCESS_COUNT++))
else
echo "❌ 发送失败: $RECIPIENT"
((FAIL_COUNT++))
fi
done
# 显示结果
echo "=========================================="
echo "📊 发送完成"
echo " ✅ 成功: $SUCCESS_COUNT"
echo " ❌ 失败: $FAIL_COUNT"
echo " 🕐 时间: $TIMESTAMP"
echo "=========================================="
if [ $FAIL_COUNT -gt 0 ]; then
echo "部分邮件发送失败，请检查 ~/.msmtp.log"
exit 1
fi
exit 0

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

@@ -0,0 +1,126 @@
# 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 Normal file
View File

@@ -0,0 +1,50 @@
# 思源笔记集成
需求的 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"
```

384
skills-req/req-plugin/skills/SKILL.md Normal file
View File

@@ -0,0 +1,384 @@
---
name: req
description: 需求工作流管理。用于 /req 命令使用、需求全生命周期管理（创建→PRD→评审→开发→测试→部署→归档）。当用户提到需求管理、/req 命令、REQ-XXX 相关任务时自动激活。
arguments: <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 确认 + 记录跳过原因 |
## 需求创建强制规则
```bash
# ✅ 正确：传完整业务字段
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 报告模板
```markdown
## 代码评审报告 - {需求标题}
日期: 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 文档创建（通过任务中转）
```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 |
| 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 速查
```bash
# 需求操作
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-prd` | PRD 文档编写 + 评审方法论 |
| `dev-test` | 测试 + 质量门禁 |

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

@@ -0,0 +1,177 @@
# 测试环境流程指南
> 测试必须按照以下环境顺序依次进行，每个环境通过后才能进入下一个环境。
## 测试环境流程
```
[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'
```
## 测试失败处理
| 失败阶段 | 处理方式 |
|---------|---------|
| 本机测试 | 修复代码，重新运行本机测试 |
| 预发布测试 | 修复代码，重新从本机测试开始 |
| 生产环境测试 | 修复代码，重新从本机测试开始 |
> 任何阶段测试失败，修复后必须从本机测试环境重新开始。

142
skills-req/req-plugin/update-siyuan-release.sh Executable file
View File

@@ -0,0 +1,142 @@
#!/bin/bash
# REQ 发布记录自动更新脚本
# 用于在发布完成后自动更新思源笔记中的发布记录
# 思源笔记配置
SIYUAN_URL="${SIYUAN_URL:-http://100.118.62.18:6806}"
SIYUAN_TOKEN="${SIYUAN_TOKEN:-nfnycjb1g8vbexb2}"
# 使用方法
usage() {
echo "Usage: $0 -r <REQ-ID> -d <doc-id> [-v <version>] [-e <env>] [-s <status>]"
echo ""
echo "Options:"
echo " -r REQ-ID 需求编号 (如 REQ-2026-0007)"
echo " -d doc-id 思源笔记文档 ID"
echo " -v version 发布版本号 (默认: v1.0.0)"
echo " -e env 发布环境 (默认: production)"
echo " -s status 发布状态: success|failed (默认: success)"
echo " -h 显示帮助"
exit 1
}
# 解析参数
REQ_ID=""
DOC_ID=""
VERSION="v1.0.0"
ENVIRONMENT="production"
STATUS="success"
while getopts "r:d:v:e:s:h" opt; do
case $opt in
r) REQ_ID="$OPTARG" ;;
d) DOC_ID="$OPTARG" ;;
v) VERSION="$OPTARG" ;;
e) ENVIRONMENT="$OPTARG" ;;
s) STATUS="$OPTARG" ;;
h) usage ;;
*) usage ;;
esac
done
# 验证必需参数
if [ -z "$REQ_ID" ] || [ -z "$DOC_ID" ]; then
echo "Error: -r 和 -d 参数是必需的"
usage
fi
# 获取当前时间
TIMESTAMP=$(date "+%Y-%m-%d %H:%M:%S")
DATE=$(date "+%Y-%m-%d")
# 状态显示
if [ "$STATUS" = "success" ]; then
STATUS_ICON="✅"
STATUS_TEXT="已发布"
else
STATUS_ICON="❌"
STATUS_TEXT="发布失败"
fi
# 生成追加内容
APPEND_CONTENT=$(cat <<EOF
---
## 发布记录更新 - $TIMESTAMP
| 项目 | 内容 |
|------|------|
| 发布版本 | $VERSION |
| 发布环境 | $ENVIRONMENT |
| 发布时间 | $TIMESTAMP |
| 发布状态 | $STATUS_ICON $STATUS_TEXT |
### 自动化流程执行记录
- $STATUS_ICON 代码构建完成
- $STATUS_ICON 服务部署完成
- $STATUS_ICON 健康检查通过
- $STATUS_ICON 邮件通知已发送
> 此记录由 REQ 需求管理系统自动生成
EOF
)
# 创建临时 JSON 文件
TMP_FILE=$(mktemp)
# 首先获取现有文档内容
echo "正在获取文档内容..."
EXISTING_CONTENT=$(curl -s -X POST "$SIYUAN_URL/api/block/getBlockKramdown" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"id\": \"$DOC_ID\"}" | jq -r '.data.kramdown // ""')
if [ -z "$EXISTING_CONTENT" ]; then
echo "Warning: 无法获取现有文档内容，将创建新内容"
EXISTING_CONTENT="# 发布记录\n\n## 文档信息\n\n| 属性 | 值 |\n|------|----|\n| 需求编号 | $REQ_ID |"
fi
# 追加新内容
NEW_CONTENT="${EXISTING_CONTENT}${APPEND_CONTENT}"
# 转义特殊字符用于 JSON
ESCAPED_CONTENT=$(echo "$NEW_CONTENT" | jq -Rs '.')
# 创建更新请求 JSON
cat > "$TMP_FILE" <<EOF
{
"id": "$DOC_ID",
"dataType": "markdown",
"data": $ESCAPED_CONTENT
}
EOF
# 更新文档
echo "正在更新思源笔记文档..."
RESPONSE=$(curl -s -X POST "$SIYUAN_URL/api/block/updateBlock" \
-H "Authorization: Token $SIYUAN_TOKEN" \
-H "Content-Type: application/json" \
-d @"$TMP_FILE")
# 清理临时文件
rm -f "$TMP_FILE"
# 检查结果
CODE=$(echo "$RESPONSE" | jq -r '.code')
if [ "$CODE" = "0" ]; then
echo "发布记录更新成功"
echo " 需求: $REQ_ID"
echo " 文档 ID: $DOC_ID"
echo " 版本: $VERSION"
echo " 环境: $ENVIRONMENT"
echo " 状态: $STATUS_TEXT"
exit 0
else
MSG=$(echo "$RESPONSE" | jq -r '.msg')
echo "发布记录更新失败: $MSG"
exit 1
fi

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

@@ -0,0 +1,120 @@
# 完整开发工作流示例
以「酷采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 | 生命周期总结 | 归档 |