From 3491827fbc58bdd7de2a6e5b3a50db60a6cca07a Mon Sep 17 00:00:00 2001 From: hwd32 Date: Sat, 23 May 2026 21:20:39 +0800 Subject: [PATCH] =?UTF-8?q?feat(skill):=20=E6=9B=B4=E6=96=B0=20Skill=20?= =?UTF-8?q?=E6=96=87=E4=BB=B6=E4=B8=BA=20v2.0=20=E6=96=B0=E6=A1=86?= =?UTF-8?q?=E6=9E=B6=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ai-collab-setup/SKILL.md: 升级为 v2.0 - 采用 R/W/RW/- 四态权限体系 - 新增 read_only_paths 和 forbidden_paths 配置 - 工作流增加 retry 和 escalation 机制 - 新增提示词模板（code-style.md、doc-template.md、bug-report.md） - 目录结构新增 src/server/、src/config/、src/types/ - add-subproject/SKILL.md: 升级为 v2.0 - 目录结构新增 src/server/、src/config/、src/types/ 子目录 - 示例任务增加完整的 feedback/round1.md 格式 - impact.md 增加影响的功能模块和环境依赖变更段落 - 脚本兼容 Windows PowerShell 和 Linux/macOS - ENVIRONMENT.md 默认使用 pnpm 包管理器 --- .trae/skills/add-subproject/SKILL.md | 85 ++- .trae/skills/ai-collab-setup/SKILL.md | 932 +++++++++++++++++++++++--- 2 files changed, 913 insertions(+), 104 deletions(-) diff --git a/.trae/skills/add-subproject/SKILL.md b/.trae/skills/add-subproject/SKILL.md index 7f05d82..ebfb7c7 100644 --- a/.trae/skills/add-subproject/SKILL.md +++ b/.trae/skills/add-subproject/SKILL.md @@ -11,7 +11,7 @@ description: "Adds a new subproject to the existing '1 Human + 2 AI' collaborati - 项目目录结构（src/、tests/、docs/） - 环境配置文件（ENVIRONMENT.md） - README.md 占位文件 -- 示例任务目录 +- 示例任务目录（含 task.md、acceptance.md、impact.md、feedback/） ## 使用方法 @@ -40,6 +40,9 @@ add-subproject --project_name="web_admin" --project_number="P03" projects/ └── P03_web_admin/ # 新项目目录 ├── src/ # Dev AI 工作区 + │ ├── server/ # NestJS 后端（如需要） + │ ├── config/ # 构建配置 + │ ├── types/ # 全局类型 │ └── README.md ├── tests/ # QA AI 工作区 │ └── README.md @@ -55,19 +58,27 @@ projects/ review/ └── active/ └── P03-001/ # 新项目的第一个任务 - ├── task.md - ├── acceptance.md - ├── impact.md - └── feedback/ + ├── task.md # 任务描述（人类创建，AI 只读） + ├── acceptance.md # 验收标准 + ├── impact.md # 变更影响范围 + └── feedback/ # 测试反馈 └── round1.md ``` ## 执行命令 ```bash -# 获取下一个项目编号 +# 获取下一个项目编号（PowerShell 兼容版本） get_next_project_number() { - ls -la projects/ | grep -E '^P[0-9]+_' | sort | tail -1 | sed 's/P\([0-9]*\)_.*$/\1/' + # 兼容 Linux/macOS + if command -v ls >/dev/null 2>&1; then + ls -la projects/ | grep -E '^P[0-9]+_' | sort | tail -1 | sed 's/P\([0-9]*\)_.*$/\1/' + # 兼容 Windows PowerShell + elif command -v powershell >/dev/null 2>&1; then + powershell -Command "(Get-ChildItem projects -Directory | Where-Object { $_.Name -match '^P\d+_' } | Sort-Object Name | Select-Object -Last 1).Name -replace 'P(\d+)_.*', '$1'" + else + echo "0" + fi } # 创建项目目录 @@ -76,7 +87,7 @@ NEXT_NUM=$(get_next_project_number) PROJECT_NUM="P$(printf '%02d' $((NEXT_NUM + 1)))" PROJECT_DIR="projects/${PROJECT_NUM}_${PROJECT_NAME}" -mkdir -p "${PROJECT_DIR}"/{src,tests,docs} +mkdir -p "${PROJECT_DIR}"/{src/{server,config,types},tests,docs} # 创建 ENVIRONMENT.md cat > "${PROJECT_DIR}/ENVIRONMENT.md" << EOF @@ -84,12 +95,13 @@ cat > "${PROJECT_DIR}/ENVIRONMENT.md" << EOF ## 依赖 - Node.js >= 20.x +- pnpm >= 9.0.0 ## 安装 -npm install +pnpm install ## 运行 -npm start +pnpm dev EOF # 创建文档 @@ -122,8 +134,8 @@ cat > "${PROJECT_DIR}/docs/03_接口定义.md" << EOF EOF # 创建 README.md -echo "# ${PROJECT_NAME}" > "${PROJECT_DIR}/src/README.md" -echo "# tests" > "${PROJECT_DIR}/tests/README.md" +echo "# ${PROJECT_NAME} - src" > "${PROJECT_DIR}/src/README.md" +echo "# ${PROJECT_NAME} - tests" > "${PROJECT_DIR}/tests/README.md" # 创建示例任务 mkdir -p "review/active/${PROJECT_NUM}-001/feedback" @@ -166,25 +178,45 @@ cat > "review/active/${PROJECT_NUM}-001/impact.md" << EOF |---------|---------|---------| | ${PROJECT_DIR}/ | 新增 | LOW | +## 影响的功能模块 +- [x] 项目初始化 + ## 需要回归测试的场景 - 无（新项目） + +## 环境依赖变更 +- 无 EOF cat > "review/active/${PROJECT_NUM}-001/feedback/round1.md" << EOF # ${PROJECT_NUM}-001 - 第一轮测试反馈 -## 测试结果 -- 通过：0 -- 失败：0 +## 基本信息 +- 测试时间: $(date +%Y-%m-%d) +- 测试项目: ${PROJECT_NUM}_${PROJECT_NAME} +- 测试环境: 待配置 + +## 测试结果概览 +| 指标 | 数值 | +|------|------| +| 测试用例总数 | 0 | +| 通过 | 0 | +| 失败 | 0 | +| 跳过 | 0 | +| 代码覆盖率 | 0% | ## 反馈 -待执行测试 +待 Dev AI 完成开发后执行测试 EOF -# 更新 README.md -echo "- [${PROJECT_NUM}_${PROJECT_NAME}](${PROJECT_DIR})" >> README.md +# 更新 README.md（如果存在） +if [ -f README.md ]; then + echo "- [${PROJECT_NUM}_${PROJECT_NAME}](${PROJECT_DIR})" >> README.md +fi echo "✅ 子项目 ${PROJECT_NUM}_${PROJECT_NAME} 创建成功！" +echo "📖 请阅读 AGENTS.md 了解协作规则" +echo "🚀 在 review/active/${PROJECT_NUM}-001/ 下查看示例任务结构" ``` ## 使用场景 @@ -203,12 +235,19 @@ echo "✅ 子项目 ${PROJECT_NUM}_${PROJECT_NAME} 创建成功！" skill 执行后： 1. 检查 `projects/${PROJECT_NUM}_${PROJECT_NAME}/` 目录结构 -2. 修改 `ENVIRONMENT.md` 配置项目依赖 -3. 更新 `docs/` 目录的文档内容 -4. 开始在 `review/active/${PROJECT_NUM}-001/` 任务下工作 +2. 阅读 `review/active/${PROJECT_NUM}-001/task.md` 示例任务 +3. 根据实际需求修改 `task.md` 为真实任务 +4. Dev AI 开始开发 --- -**Version**: 1.0 +**Version**: 2.0 **Created**: 2026-05-22 -**Based On**: ErrLens AI Programming Project \ No newline at end of file +**Updated**: 2026-05-23 +**Based On**: ErrLens AI Programming Project +**Changes from v1**: +- 目录结构新增 src/server/、src/config/、src/types/ 子目录 +- 示例任务增加完整的 feedback/round1.md 格式（含基本信息表格） +- impact.md 增加「影响的功能模块」和「环境依赖变更」段落 +- 脚本兼容 Windows PowerShell 和 Linux/macOS +- ENVIRONMENT.md 默认使用 pnpm 包管理器 diff --git a/.trae/skills/ai-collab-setup/SKILL.md b/.trae/skills/ai-collab-setup/SKILL.md index 985c48b..2978969 100644 --- a/.trae/skills/ai-collab-setup/SKILL.md +++ b/.trae/skills/ai-collab-setup/SKILL.md @@ -9,8 +9,10 @@ description: "Creates complete '1 Human + 2 AI' collaboration framework with dir 一键创建"1 人+2AI（Coder+Tester）"协作框架，包括： - 完整的目录结构 -- AI 角色定义与权限约定（AGENTS.md） -- AI 配置文件 +- AI 角色定义与权限约定（AGENTS.md）—— R/W/RW/- 四态权限体系 +- AI 配置文件（含 read_only_paths、forbidden_paths、description） +- 提示词模板（code-style.md、doc-template.md、bug-report.md） +- 工作流配置（4 阶段 + retry + escalation） - 示例任务模板 - README 文档 @@ -28,22 +30,33 @@ description: "Creates complete '1 Human + 2 AI' collaboration framework with dir ### 目录结构 ``` . -├── AGENTS.md # AI 宪法（角色定义 + 权限约定） +├── AGENTS.md # AI 宪法（角色定义 + 权限约定 + R/W/RW/- 矩阵） ├── README.md # 项目说明 ├── .gitignore ├── .ai/ │ ├── config/ -│ │ ├── coder.json # Dev AI 配置 -│ │ ├── tester.json # QA AI 配置 -│ │ └── workflow.json # 工作流配置 +│ │ ├── coder.json # Dev AI 配置（含 read_only_paths） +│ │ ├── tester.json # QA AI 配置（含 read_only_paths） +│ │ └── workflow.json # 工作流配置（含 retry + escalation） │ └── prompts/ │ ├── coding/ # 编码提示词 +│ │ ├── README.md +│ │ ├── code-style.md # 代码风格规范 +│ │ └── doc-template.md # impact.md / acceptance.md 模板 │ └── testing/ # 测试提示词 +│ ├── README.md +│ └── bug-report.md # Bug 报告模板（BLOCKER/HIGH/MEDIUM/LOW） ├── projects/ │ ├── P01_app/ -│ │ ├── src/ # Dev AI 工作区 +│ │ ├── src/ # Dev AI 工作区（前端 + 后端 + 配置） +│ │ │ ├── server/ # NestJS 后端 +│ │ │ ├── config/ # 构建配置 +│ │ │ └── types/ # 全局类型 │ │ ├── tests/ # QA AI 工作区 │ │ ├── docs/ +│ │ │ ├── 01_需求概要.md +│ │ │ ├── 02_架构设计.md +│ │ │ └── 03_接口定义.md │ │ └── ENVIRONMENT.md │ └── P02_training/ │ ├── src/ @@ -53,21 +66,22 @@ description: "Creates complete '1 Human + 2 AI' collaboration framework with dir ├── review/ │ ├── active/ # 活跃任务 │ │ ├── P01-001/ -│ │ │ ├── task.md -│ │ │ ├── acceptance.md -│ │ │ ├── impact.md -│ │ │ └── feedback/ +│ │ │ ├── task.md # 任务描述（人类创建，AI 只读） +│ │ │ ├── acceptance.md # 验收标准 +│ │ │ ├── impact.md # 变更影响范围 +│ │ │ └── feedback/ # 测试反馈 +│ │ │ └── round1.md │ │ ├── P01-002/ │ │ └── CROSS-001/ -│ └── archived/ # 归档任务 +│ └── archived/ # 归档任务（按季度） │ └── 2026-Q2/ ├── shared/ │ ├── scripts/ │ ├── templates/ │ └── utils/ ├── reports/ -│ ├── test-results/ -│ └── quality-reports/ +│ ├── test-results/ # 测试结果 +│ └── quality-reports/ # 质量评审报告 └── .github/workflows/ ``` @@ -75,15 +89,21 @@ description: "Creates complete '1 Human + 2 AI' collaboration framework with dir **AGENTS.md** - AI 宪法： - 三个角色定义（人类、Dev AI、QA AI） -- 权限矩阵 -- 工作流程（8 个步骤） +- R/W/RW/- 四态权限矩阵 +- 工作流程（4 阶段 + 缺陷修复循环） +- retry 配置（max_rounds=3，escalation 规则） - 沟通规范 - 命名规范 **AI 配置文件**： -- `.ai/config/coder.json` - Dev AI 权限和职责 -- `.ai/config/tester.json` - QA AI 权限和职责 -- `.ai/config/workflow.json` - 工作流配置 +- `.ai/config/coder.json` - Dev AI 权限和职责（含 read_only_paths、forbidden_paths） +- `.ai/config/tester.json` - QA AI 权限和职责（含 read_only_paths、forbidden_paths） +- `.ai/config/workflow.json` - 工作流配置（含 retry + escalation） + +**提示词模板**： +- `.ai/prompts/coding/code-style.md` - 代码风格、命名规范、目录组织 +- `.ai/prompts/coding/doc-template.md` - impact.md / acceptance.md 标准化模板 +- `.ai/prompts/testing/bug-report.md` - Bug 报告模板，严重程度定义 **示例任务**： - `review/active/P01-001/` - 示例任务（包含 task、acceptance、impact、feedback） @@ -94,8 +114,8 @@ description: "Creates complete '1 Human + 2 AI' collaboration framework with dir ```bash # 1. 创建目录结构 mkdir -p .ai/{config,prompts/{coding,testing}} \ - projects/{P01_app,P02_training}/{src,tests,docs} \ - review/{active/{P01-001, P01-002, CROSS-001},archived/2026-Q2}/feedback \ + projects/{P01_app,P02_training}/{src/{server,config,types},tests,docs} \ + review/{active/{P01-001,P01-002,CROSS-001},archived/2026-Q2}/feedback \ shared/{scripts,templates,utils} \ reports/{test-results,quality-reports} \ .github/workflows @@ -105,62 +125,371 @@ cat > AGENTS.md << 'EOF' # AI 角色定义与权限约定 ## 团队架构 +``` +┌─────────────────────────────────────────────┐ +│ 人类负责人 │ +│ 需求分析 · 架构设计 · 最终决策 │ +└───────────────────┬─────────────────────────┘ + │ + ┌───────────┴───────────┐ + ▼ ▼ +┌───────────────┐ ┌───────────────┐ +│ Dev AI │ │ QA AI │ +│ 代码编写 │ │ 测试设计 │ +│ 文档生成 │ │ 测试执行 │ +│ 影响评估 │ │ 质量保障 │ +└───────────────┘ └───────────────┘ +``` -| 角色 | 是谁 | 干什么 | 不干什么 | -|------|------|--------|----------| -| 人类 | 你 | 下指令、审阅、做决策 | 不写代码、不写测试 | -| Dev AI | Claude/TRAE 等 | 写代码 + 文档、修 bug | 不动 tests/、不跑测试 | -| QA AI | 扣子编程 AI | 写测试、跑测试、写反馈 | 不动 src/、不改业务代码 | +--- -## 目录权限矩阵 +## 角色职责 -| 目录 | Dev AI | QA AI | 人类 | -|------|--------|-------|------| -| projects/*/src/ | ✅ | ❌ | ✅ | -| projects/*/tests/ | ❌ | ✅ | ✅ | -| projects/*/docs/ | ✅ | ❌ | ✅ | -| review/*/task.md | ❌ | ❌ | ✅ | -| review/*/acceptance.md | ✅ | ✅ | ✅ | -| review/*/impact.md | ✅ | ❌ | ✅ | -| review/*/feedback/ | ❌ | ✅ | ✅ | -| shared/ | ✅ | ❌ | ✅ | -| reports/ | ❌ | ✅ | ✅ | +### Dev AI (编码AI) +**职责范围：** +- ✅ 编写业务代码 (`projects/*/src/`) +- ✅ 生成技术文档 (`projects/*/docs/`) +- ✅ 定义验收标准 (`review/*/acceptance.md`) +- ✅ 评估变更影响 (`review/*/impact.md`) +- ✅ 维护共享资源 (`shared/`) + +**可读但不可写：** +- 👁 任务描述 (`review/*/task.md`) —— 只读，不可修改 +- 👁 测试反馈 (`review/*/feedback/`) —— 只读，用于修 Bug + +**禁止操作：** +- ❌ 修改测试代码 (`projects/*/tests/`) +- ❌ 修改测试报告 (`reports/`) + +### QA AI (测试AI) +**职责范围：** +- ✅ 编写测试用例 (`projects/*/tests/`) +- ✅ 执行测试并生成报告 (`reports/`) +- ✅ 补充验收标准 (`review/*/acceptance.md`) +- ✅ 提交测试反馈 (`review/*/feedback/`) + +**可读但不可写：** +- 👁 任务描述 (`review/*/task.md`) —— 只读，了解测试目标 + +**禁止操作：** +- ❌ 修改业务代码 (`projects/*/src/`) +- ❌ 修改技术文档 (`projects/*/docs/`) +- ❌ 修改共享资源 (`shared/`) +- ❌ 修改影响评估 (`review/*/impact.md`) + +### 人类负责人 +**职责范围：** +- ✅ 可以修改所有目录 +- ✅ 审核 AI 输出质量 +- ✅ 解决 AI 之间的冲突 +- ✅ 最终决策和验收 + +--- ## 工作流程 -1. 人类创建 task.md -2. Dev AI 写代码、文档、impact.md -3. 人类审核 -4. QA AI 写测试、执行、写 feedback -5. 人类确认或返回修改 +``` +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ 需求分析 │ ───→ │ 开发实现 │ ───→ │ 测试验证 │ ───→ │ 验收确认 │ +│ (人类) │ │ (Dev AI) │ │ (QA AI) │ │ (人类) │ +└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ + ↑ │ + │ Bug → 修复 │ + └──────────────────────┘ + (最多 2 轮) +``` -## 任务状态 +### 详细流程说明 -TODO → IN_PROGRESS → REVIEW → DONE → ARCHIVED +**1. 需求分析阶段** +- 人类负责人创建任务单 +- 输出: `review/{task_id}/task.md` + +**2. 开发实现阶段** +- Dev AI 读取任务描述，编写代码 + 文档 +- 同时输出验收标准和变更影响范围 +- 输出: `projects/*/src/`, `projects/*/docs/`, `review/{task_id}/impact.md`, `review/{task_id}/acceptance.md` + +**3. 测试验证阶段** +- QA AI 根据验收标准编写测试，执行测试，生成报告 +- 测试反馈写入 `review/{task_id}/feedback/round{round}.md` +- 输出: `projects/*/tests/`, `reports/test-results/`, `review/{task_id}/feedback/` + +### 缺陷修复循环 + +| 规则 | 说明 | +|------|------| +| 最大轮次 | 3 轮（初始测试 + 最多 2 轮修复复查） | +| 循环范围 | 测试失败 → Dev AI 修复 → QA AI 复查 | +| 跳过项 | 修复轮次中 Dev AI **只修 Bug**，不重新写 acceptance/impact | +| 触发升级 | 第 3 轮仍有 BLOCKER 或 HIGH 级别 Bug → 暂停流转，待人类裁决 | + +``` +Round 1: Dev 开发 → QA 测试 → 3 个 Bug +Round 2: Dev 修复 → QA 复查 → 1 个 Bug（MEDIUM） +Round 3: Dev 修复 → QA 复查 → 0 个 Bug ✅ → 提交人类验收 +``` + +如果 Round 3 仍有 BLOCKER/HIGH： +``` +Round 3: Dev 修复 → QA 复查 → 仍 1 个 HIGH → ⚠️ 升级给人类裁决 +``` + +**4. 验收确认阶段** +- 人类审核测试报告，确认任务完成或驳回 +- 确认后任务状态更新为 DONE，移入 `review/archived/` + +--- + +## 目录权限矩阵 + +> **图例**：`-` = 无权访问    `R` = 只读    `W` = 可写（含读）    `RW` = 读写 + +| 目录路径 | Dev AI | QA AI | 人类 | +|---------|--------|-------|------| +| `.ai/` | `-` | `-` | `RW` | +| `shared/` | `RW` | `-` | `RW` | +| `projects/*/src/` | `RW` | `-` | `RW` | +| `projects/*/tests/` | `-` | `RW` | `RW` | +| `projects/*/docs/` | `RW` | `-` | `RW` | +| `review/*/task.md` | `R` | `R` | `RW` | +| `review/*/acceptance.md` | `RW` | `RW` | `RW` | +| `review/*/impact.md` | `RW` | `-` | `RW` | +| `review/*/feedback/` | `R` | `RW` | `RW` | +| `reports/` | `-` | `RW` | `RW` | +| `.github/` | `-` | `-` | `RW` | + +> **解析优先级**：当同一条路径被多个规则匹配时，`forbidden > read_only > allowed`。禁止规则永远优先。 +> +> **默认行为**：任何未出现在上表中的路径，默认禁止所有 AI 访问（等效于 `-`）。 + +--- + +## 沟通规范 + +### Dev AI → QA AI +在 `review/{task_id}/` 目录提交： +- **验收标准** (`acceptance.md`) - 明确测试目标 +- **变更影响范围** (`impact.md`) - 指导回归测试 +- **环境准备** 参考项目级 `ENVIRONMENT.md` + +### QA AI → Dev AI +在 `review/{task_id}/feedback/` 目录提交： +- **测试结果报告** (`round{round}.md`) +- **Bug清单** - 列出问题和严重程度 +- **改进建议** - 代码优化建议 + +--- + +## 命名规范 + +### 项目命名 +``` +P01_项目名称 # P01 表示项目编号 +``` + +### 任务编号 +``` +P01-001 # P01 项目编号 + 001 任务编号 +``` + +### 分支命名 +``` +feature/P01-001-login # 功能开发 +bugfix/P01-001-password # Bug修复 +test/P01-001-testcases # 测试用例 +``` + +### 提交信息 +``` +feat(P01-001): 实现用户登录功能 +fix(P01-001): 修复密码验证问题 +docs(P01-001): 更新接口文档 +test(P01-001): 添加登录测试用例 +``` + +--- + +## AI 配置文件说明 + +| 文件 | 说明 | +|------|------| +| `.ai/config/coder.json` | Dev AI 配置（权限、职责） | +| `.ai/config/tester.json` | QA AI 配置（权限、职责） | +| `.ai/config/workflow.json` | 工作流配置（阶段、触发器） | +| `.ai/prompts/coding/` | 编码提示词模板 | +| `.ai/prompts/testing/` | 测试提示词模板 | EOF # 3. 创建 README.md cat > README.md << 'EOF' # AI 协作项目 +一个"人+2AI"协作模式的 AI 辅助编程项目仓库。 + +--- + ## 目录结构 -详见 AGENTS.md +``` +. +├── AGENTS.md # AI角色定义+权限约定+工作流 +├── README.md +├── .gitignore +├── .ai/ # AI协作核心配置 +│ ├── config/ +│ │ ├── coder.json # Dev AI 配置 +│ │ ├── tester.json # QA AI 配置 +│ │ └── workflow.json # 工作流配置 +│ └── prompts/ +│ ├── coding/ # 编码提示词模板 +│ └── testing/ # 测试提示词模板 +├── projects/ # 项目代码 +│ ├── P01_app/ # 主应用项目 +│ │ ├── src/ # 业务代码 (Dev AI) +│ │ ├── tests/ # 测试代码 (QA AI) +│ │ ├── docs/ # 项目文档 (Dev AI) +│ │ └── ENVIRONMENT.md # 项目级环境准备 +│ └── P02_training/ # AI训练项目 +│ ├── src/ +│ ├── tests/ +│ ├── docs/ +│ └── ENVIRONMENT.md +├── review/ # 交接中心 +│ ├── active/ # 活跃任务 +│ └── archived/ # 已完成任务（按季度归档） +├── shared/ # 共享资源 +│ ├── scripts/ +│ ├── templates/ +│ └── utils/ +├── reports/ # 统一报告 +│ ├── test-results/ +│ └── quality-reports/ +└── .github/ # CI/CD配置 + └── workflows/ +``` -## 快速开始 +--- -1. 在 review/active/ 下创建任务目录 -2. 编写 task.md -3. Dev AI 开始工作 +## 团队角色 + +| 角色 | 是谁 | 干什么 | 不干什么 | +|------|------|--------|----------| +| **人类负责人** | 你 | 下指令、审阅、做决策、定验收标准 | 不写代码、不写测试 | +| **Dev AI** | Claude/TRAE/元宝等 | 写业务代码+文档、修bug、写impact | 不动tests/、不跑测试 | +| **QA AI** | 扣子编程AI | 写测试、跑测试、写反馈 | 不动src/、不改业务代码 | + +--- + +## 工作流程 + +1. **你**在 `review/active/P01-001/` 下写 `task.md`（要做什么） +2. **你或Dev AI**补充 `acceptance.md`（怎么算做完了） +3. **Dev AI** 在 `projects/P01_app/src/` 写代码，在 `docs/` 写文档，写 `impact.md` +4. **你**审一眼，没问题就触发QA AI +5. **QA AI** 读 `task.md` + `acceptance.md` + `impact.md`，按 `ENVIRONMENT.md` 准备环境，在 `tests/` 写测试并执行，写 `feedback/round1.md` +6. **有bug** → 你看反馈 → 让Dev AI修 → 回到步骤3（round2） + **通过** → 你确认 → 任务关闭，报告归档到 `reports/` + +--- + +## 任务状态流转 + +``` +TODO → IN_PROGRESS → REVIEW → DONE → ARCHIVED（移入archived/季度目录） +``` + +`task.md` 中添加状态字段： +``` +status: TODO | IN_PROGRESS | REVIEW | DONE | ARCHIVED +``` EOF -# 4. 创建 AI 配置 +# 4. 创建 .gitignore +cat > .gitignore << 'EOF' +# Dependencies +node_modules/ +vendor/ +__pycache__/ +*.pyc +*.pyo +venv/ + +# Build outputs +dist/ +build/ +*.log +*.out + +# IDE +.vscode/ +.idea/ +*.swp +*.swo + +# OS +Thumbs.db +.DS_Store + +# Environment variables +.env +.env.local +.env.*.local +.env.production + +# Test reports +reports/test-results/*.json +reports/test-results/*.xml + +# Model files +models/ +*.pt +*.pth +*.onnx + +# Data files +data/ +*.csv +*.jsonl + +# Temporary files +*.tmp +*.temp +*.bak +EOF + +# 5. 创建 AI 配置文件（新版：含 read_only_paths、forbidden_paths、description） cat > .ai/config/coder.json << 'EOF' { "name": "Dev AI", "role": "代码开发者", - "allowed_paths": ["projects/*/src/", "projects/*/docs/", "shared/"], - "forbidden_paths": ["projects/*/tests/", "reports/"] + "description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。", + "responsibilities": [ + "编写业务代码", + "生成技术文档", + "定义验收标准", + "评估变更影响", + "维护共享资源" + ], + "allowed_paths": [ + "projects/*/src/", + "projects/*/docs/", + "shared/", + "review/*/acceptance.md", + "review/*/impact.md" + ], + "read_only_paths": [ + "review/*/task.md", + "review/*/feedback/" + ], + "forbidden_paths": [ + "projects/*/tests/", + "reports/" + ], + "prompt_templates": { + "coding": ".ai/prompts/coding/", + "documentation": ".ai/prompts/coding/" + } } EOF @@ -168,8 +497,31 @@ cat > .ai/config/tester.json << 'EOF' { "name": "QA AI", "role": "测试工程师", - "allowed_paths": ["projects/*/tests/", "reports/"], - "forbidden_paths": ["projects/*/src/", "shared/"] + "description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。", + "responsibilities": [ + "编写测试用例", + "执行测试", + "生成测试报告", + "提供反馈" + ], + "allowed_paths": [ + "projects/*/tests/", + "reports/", + "review/*/acceptance.md", + "review/*/feedback/" + ], + "read_only_paths": [ + "review/*/task.md" + ], + "forbidden_paths": [ + "projects/*/src/", + "projects/*/docs/", + "shared/", + "review/*/impact.md" + ], + "prompt_templates": { + "testing": ".ai/prompts/testing/" + } } EOF @@ -178,29 +530,329 @@ cat > .ai/config/workflow.json << 'EOF' "workflow": "human-ai-collaboration", "roles": ["human", "dev-ai", "qa-ai"], "stages": [ - {"name": "需求分析", "actor": "human"}, - {"name": "开发实现", "actor": "dev-ai"}, - {"name": "测试执行", "actor": "qa-ai"}, - {"name": "验收确认", "actor": "human"} - ] + { + "name": "需求分析", + "actor": "human", + "output": "review/{task_id}/task.md" + }, + { + "name": "开发实现", + "actor": "dev-ai", + "input": "review/{task_id}/task.md", + "output": ["projects/*/src/", "projects/*/docs/", "review/{task_id}/impact.md", "review/{task_id}/acceptance.md"] + }, + { + "name": "测试验证", + "actor": "qa-ai", + "input": ["review/{task_id}/task.md", "review/{task_id}/acceptance.md"], + "output": ["projects/*/tests/", "reports/test-results/", "review/{task_id}/feedback/round{round}.md"] + }, + { + "name": "验收确认", + "actor": "human", + "input": ["review/{task_id}/feedback/", "reports/test-results/"] + } + ], + "retry": { + "max_rounds": 3, + "loop": ["测试验证", "开发实现"], + "escalation": { + "trigger": "第 3 轮测试仍有 BLOCKER 或 HIGH 级别 Bug", + "action": "暂停任务流转，等待人类负责人裁决" + }, + "skip_acceptance_on_retry": true + }, + "ci_triggers": { + "on_push_to_main": ["run-tests", "generate-reports"], + "on_pr_open": ["run-tests", "code-review"], + "on_task_update": ["notify-qa-ai"] + } } EOF -# 5. 创建示例任务 +# 6. 创建提示词模板 +cat > .ai/prompts/coding/README.md << 'EOF' +# Dev AI 提示词库 + +| 文件 | 说明 | +|------|------| +| [code-style.md](code-style.md) | 代码风格、命名规范、目录组织 | +| [doc-template.md](doc-template.md) | impact.md / acceptance.md 等文档模板 | +EOF + +cat > .ai/prompts/testing/README.md << 'EOF' +# QA AI 提示词库 + +| 文件 | 说明 | +|------|------| +| [bug-report.md](bug-report.md) | 测试反馈 / Bug 报告模板与格式规范 | +EOF + +cat > .ai/prompts/coding/code-style.md << 'EOF' +# Dev AI 代码风格规范 + +## 适用技术栈 + +| 层 | 技术 | 语言 | +|-----|------|------| +| 前端 | Taro 4 + React 18 | TypeScript 5.x | +| 样式 | Tailwind CSS 4 | — | +| 后端 | NestJS 10 | TypeScript 5.x | +| 训练 | PyTorch 2.0 | Python 3.10+ | + +--- + +## 1. 文件命名 + +| 类型 | 规则 | 示例 | +|------|------|------| +| 页面组件 | kebab-case | `error-detail.tsx` | +| UI 组件 | kebab-case | `button.tsx` | +| 工具函数 | kebab-case | `format-date.ts` | +| 类型定义 | kebab-case | `error-entry.d.ts` | +| NestJS 模块 | kebab-case | `auth.module.ts` | +| Python 模块 | snake_case | `data_loader.py` | + +## 2. 目录组织（前端） + +``` +src/ +├── pages/{page-name}/ # 页面 —— 一个目录一个页面 +│ ├── index.tsx +│ ├── index.config.ts +│ └── index.css +├── components/ # 通用组件 +│ └── {component-name}/ +│ └── index.tsx +├── lib/ # 工具函数、hooks +├── types/ # 全局类型声明 +├── server/ # NestJS 后端 +└── config/ # Taro 构建配置 +``` + +## 3. 目录组织（NestJS 后端） + +``` +src/server/src/ +├── modules/{name}/ # 一个模块一个目录 +│ ├── {name}.module.ts +│ ├── {name}.controller.ts +│ ├── {name}.service.ts +│ ├── dto/ +│ └── entities/ +├── common/ # 共享：拦截器、守卫、管道 +└── main.ts +``` + +## 4. 命名风格 + +**TypeScript：** +- 组件：PascalCase —— `ErrorCard` +- 函数/变量：camelCase —— `getUserProfile` +- 常量：UPPER_SNAKE —— `MAX_PAGE_SIZE` +- 接口/类型：PascalCase —— `ErrorEntry` + +**Python：** +- 类：PascalCase —— `DataLoader` +- 函数/变量：snake_case —— `load_dataset` +- 常量：UPPER_SNAKE —— `BATCH_SIZE` + +## 5. 导入顺序（TypeScript） + +``` +1. 第三方库 +2. Taro 相关 +3. 项目内部（@/ 别名） +4. 相对路径 +5. 样式文件 +``` + +## 6. 组件规范 + +- 优先使用函数组件，不用 class 组件 +- 一个文件只有一个 export default 组件 +- 组件 props 必须声明类型接口 +- 跨端兼容：避免使用 `document`、`window`（用 Taro API 代替） + +## 7. API 调用规范 + +- 前端统一使用 `@/network.ts` 中的 `Network.request`，不要直接调用 `Taro.request` +- 后端Controller 只做参数校验和路由，业务逻辑放在 Service +- API 响应统一使用 Envelope 格式 `{ code, msg, data }` + +## 8. 不能做的事 + +- 不要在 `src/` 下写测试文件（测试在 `tests/`） +- 不要引入未经 package.json 声明的依赖 +- 不要在组件中硬编码后端地址（用 `PROJECT_DOMAIN` 全局变量） +EOF + +cat > .ai/prompts/coding/doc-template.md << 'EOF' +# Dev AI 文档模板 + +下面三个模板用于 Dev AI 在 `review/{task_id}/` 下产出标准化文件。 + +--- + +## A. impact.md 模板（变更影响范围） + +```markdown +# {TASK_ID} - 变更影响范围 + +## 修改的文件 +| 文件路径 | 修改类型 | 影响等级 | +|---------|---------|---------| +| projects/P01_errlens_app/src/server/src/modules/auth/auth.service.ts | 新增 | HIGH | +| projects/P01_errlens_app/src/server/src/modules/auth/dto/login.dto.ts | 新增 | MEDIUM | + +> 影响等级：HIGH=核心逻辑变更 | MEDIUM=新增文件 | LOW=注释/格式 + +## 影响的功能模块 +- [x] 用户认证模块 +- [ ] 错题管理模块（无影响） + +## 需要回归测试的场景 +- 场景1: 用户登录成功流程 +- 场景2: 密码错误返回 401 +- 场景3: Token 过期后刷新 + +## 环境依赖变更 +- 新增依赖: bcrypt, @nestjs/jwt +- 数据库迁移: 新增 users 表 +``` + +**要点：** +- `修改的文件` 必须使用从仓库根目录开始的完整路径 +- 影响等级要实事求是，不要全写 HIGH +- `需要回归测试的场景` 要写**用户视角**的场景，不是代码内部细节 + +--- + +## B. acceptance.md 模板（验收标准） + +```markdown +# {TASK_ID} - 验收标准 + +## 功能验收 +- [ ] 用户可以注册新账户（邮箱+密码） +- [ ] 密码强度不足时提示明确错误信息 +- [ ] 登录成功返回有效 JWT Token + +## 非功能验收 +- [ ] API 响应时间 < 200ms +- [ ] 密码使用 bcrypt 加密存储 +- [ ] JWT Token 有效期 24 小时 + +## 测试覆盖要求 +- 单元测试覆盖率: >= 80% +- 集成测试覆盖率: >= 60% +- E2E 测试场景: >= 3 个 + +## 验收通过条件 +- 所有功能点验证通过 +- 测试覆盖率达标 +- 无重大安全漏洞 +``` + +**要点：** +- 功能验收用「用户可以…」句式，让 QA AI 和人类都能看懂 +- 每个功能点对应 task.md 里的一项交付物 +- 非功能验收写具体的可测量指标，不要写「性能好」「代码整洁」 + +--- + +## C. 没有 task.md 模板 + +task.md 由人类负责人创建，Dev AI 只读不写。Dev AI 如需补充技术细节，写在 impact.md 的「技术备注」段落中，不要直接修改 task.md。 +EOF + +cat > .ai/prompts/testing/bug-report.md << 'EOF' +# QA AI Bug 报告模板 + +以下模板用于 QA AI 在 `review/{task_id}/feedback/round{round}.md` 中提交测试反馈。 + +--- + +## 模板 + +```markdown +# {TASK_ID} - 第 {N} 轮测试反馈 + +## 基本信息 +- 测试时间: YYYY-MM-DD +- 测试项目: P01_errlens_app / P02_errlens_training / P03_errlens_web +- 测试环境: Node 20.x / Python 3.10 + +## 测试结果概览 +| 指标 | 数值 | +|------|------| +| 测试用例总数 | N | +| 通过 | N | +| 失败 | N | +| 跳过 | N | +| 代码覆盖率 | XX% | + +## 失败用例清单 + +### Bug #1: {简短标题} +- **严重程度**: BLOCKER / HIGH / MEDIUM / LOW +- **涉及文件**: `projects/...`（完整路径） +- **测试场景**: 用户登录时输入正确密码 +- **预期结果**: 返回 200 和 JWT Token +- **实际结果**: 返回 500 Internal Server Error +- **复现步骤**: + 1. POST /api/auth/login + 2. body: {"email": "test@example.com", "password": "correct"} +- **建议修复**: 检查 auth.service.ts 第 42 行的异常处理 + +### Bug #2: ... +（同上格式） + +## 改进建议（非 Bug） +- 建议 1: 登录接口缺少限流保护 +- 建议 2: 密码重置的邮件模板可以更友好 + +## 下一步 +- [ ] Dev AI 修复上述 Bug 后，QA AI 进行第 {N+1} 轮测试 +- [ ] 如第 3 轮仍未通过，升级给人类负责人裁决 +``` + +--- + +## 严重程度定义 + +| 级别 | 含义 | 举例 | +|------|------|------| +| BLOCKER | 核心功能不可用，无法继续测试 | 登录接口直接崩溃、数据库连不上 | +| HIGH | 功能逻辑错误，用户无法正常使用 | 登录成功但不返回 Token | +| MEDIUM | 功能可用但与预期有偏差 | 返回的日期格式不对、错误码不对 | +| LOW | 不影响功能的瑕疵 | 提示文案不友好、缺少空值校验 | + +## 规则 + +1. **每轮反馈用新文件**：`round1.md` → `round2.md` → `round3.md` +2. **最多 3 轮**：第 3 轮仍有 BLOCKER/HIGH Bug → 在报告中标注「建议人类负责人介入」 +3. **涉及文件必须用完整路径**：从仓库根目录开始，方便 Dev AI 定位 +4. **改进建议不要超过 3 条**：聚焦最重要的 +EOF + +# 7. 创建示例任务 cat > review/active/P01-001/task.md << 'EOF' # P01-001 - 示例任务 ## 任务信息 - 任务编号：P01-001 - 项目：P01_app +- 创建时间：2026-05-22 +- 负责人：Dev AI - 状态：TODO ## 任务描述 -这是一个示例任务，展示任务单的结构。 +这是一个示例任务，展示任务单的结构。实际使用时请替换为真实需求。 ## 交付物 -- src/example.js -- tests/example.test.js +- `projects/P01_app/src/` 下的业务代码 +- `projects/P01_app/docs/` 下的技术文档 EOF cat > review/active/P01-001/acceptance.md << 'EOF' @@ -210,8 +862,15 @@ cat > review/active/P01-001/acceptance.md << 'EOF' - [ ] 功能点 1 - [ ] 功能点 2 +## 非功能验收 +- [ ] API 响应时间 < 200ms + ## 测试覆盖要求 -- 单元测试覆盖率：>= 80% +- 单元测试覆盖率: >= 80% + +## 验收通过条件 +- 所有功能点验证通过 +- 测试覆盖率达标 EOF cat > review/active/P01-001/impact.md << 'EOF' @@ -220,33 +879,110 @@ cat > review/active/P01-001/impact.md << 'EOF' ## 修改的文件 | 文件路径 | 修改类型 | 影响等级 | |---------|---------|---------| -| src/example.js | 新增 | HIGH | +| projects/P01_app/src/example.ts | 新增 | HIGH | + +## 影响的功能模块 +- [x] 示例模块 ## 需要回归测试的场景 -- 场景 1 +- 场景1: 示例功能正常使用 + +## 环境依赖变更 +- 无 EOF cat > review/active/P01-001/feedback/round1.md << 'EOF' # P01-001 - 第一轮测试反馈 -## 测试结果 -- 通过：0 -- 失败：0 +## 基本信息 +- 测试时间: 2026-05-22 +- 测试项目: P01_app +- 测试环境: 待配置 + +## 测试结果概览 +| 指标 | 数值 | +|------|------| +| 测试用例总数 | 0 | +| 通过 | 0 | +| 失败 | 0 | +| 跳过 | 0 | +| 代码覆盖率 | 0% | ## 反馈 -待执行测试 +待 Dev AI 完成开发后执行测试 EOF -# 6. 创建项目环境文件 +# 8. 创建 P01-002 示例任务（占位） +mkdir -p review/active/P01-002/feedback + +cat > review/active/P01-002/task.md << 'EOF' +# P01-002 - 待创建 + +## 任务信息 +- 任务编号：P01-002 +- 项目：P01_app +- 状态：TODO + +## 任务描述 +待人类负责人创建 +EOF + +cat > review/active/P01-002/acceptance.md << 'EOF' +# P01-002 - 验收标准 + +待 Dev AI 补充 +EOF + +cat > review/active/P01-002/impact.md << 'EOF' +# P01-002 - 变更影响范围 + +待 Dev AI 补充 +EOF + +echo "# feedback" > review/active/P01-002/feedback/README.md + +# 9. 创建 CROSS-001 跨项目任务（占位） +mkdir -p review/active/CROSS-001/feedback + +cat > review/active/CROSS-001/task.md << 'EOF' +# CROSS-001 - 跨项目任务 + +## 任务信息 +- 任务编号：CROSS-001 +- 项目：多个项目 +- 状态：TODO + +## 任务描述 +待人类负责人创建 +EOF + +cat > review/active/CROSS-001/acceptance.md << 'EOF' +# CROSS-001 - 验收标准 + +待 Dev AI 补充 +EOF + +cat > review/active/CROSS-001/impact.md << 'EOF' +# CROSS-001 - 变更影响范围 + +待 Dev AI 补充 +EOF + +echo "# feedback" > review/active/CROSS-001/feedback/README.md + +# 10. 创建项目环境文件 cat > projects/P01_app/ENVIRONMENT.md << 'EOF' # P01_app - 环境准备 ## 依赖 - Node.js >= 20.x -- npm >= 10.x +- pnpm >= 9.0.0 ## 安装 -npm install +pnpm install + +## 运行 +pnpm dev EOF cat > projects/P02_training/ENVIRONMENT.md << 'EOF' @@ -255,10 +991,35 @@ cat > projects/P02_training/ENVIRONMENT.md << 'EOF' ## 依赖 - Python >= 3.10 - PyTorch >= 2.0 +- CUDA >= 11.8 (GPU训练) ## 安装 pip install -r requirements.txt EOF + +# 11. 创建占位文件 +echo "# src" > projects/P01_app/src/README.md +echo "# tests" > projects/P01_app/tests/README.md +echo "# docs" > projects/P01_app/docs/README.md + +echo "# src" > projects/P02_training/src/README.md +echo "# tests" > projects/P02_training/tests/README.md +echo "# docs" > projects/P02_training/docs/README.md + +echo "# scripts" > shared/scripts/README.md +echo "# templates" > shared/templates/README.md +echo "# utils" > shared/utils/README.md + +echo "# test-results" > reports/test-results/README.md +echo "# quality-reports" > reports/quality-reports/README.md + +echo "# workflows" > .github/workflows/README.md + +echo "# 2026-Q2 archived tasks" > review/archived/2026-Q2/README.md + +echo "✅ AI 协作框架创建成功！" +echo "📖 请阅读 AGENTS.md 了解协作规则" +echo "🚀 在 review/active/ 下创建你的第一个真实任务开始开发" ``` ## 使用场景 @@ -275,13 +1036,22 @@ EOF ## 后续步骤 skill 执行后： -1. 检查 `review/active/P01-001/` 示例任务 -2. 根据实际需求修改 `AGENTS.md` -3. 创建第一个真实任务 -4. 开始协作开发 +1. 阅读 `AGENTS.md` 了解协作规则和权限体系 +2. 检查 `review/active/P01-001/` 示例任务结构 +3. 根据实际需求修改 `AGENTS.md` 中的技术栈说明 +4. 在 `review/active/` 下创建第一个真实任务 +5. 开始协作开发 --- -**Version**: 1.0 -**Created**: 2026-05-22 -**Based On**: ErrLens AI Programming Project \ No newline at end of file +**Version**: 2.0 +**Created**: 2026-05-23 +**Updated**: 2026-05-23 +**Based On**: ErrLens AI Programming Project +**Changes from v1**: +- 权限体系从 ✅/❌ 升级为 R/W/RW/- 四态 +- 新增 read_only_paths、forbidden_paths 配置 +- 工作流从线性升级为 4 阶段 + retry + escalation +- 新增提示词模板（code-style.md、doc-template.md、bug-report.md） +- JSON 配置新增 description 语义定义 +- 目录结构新增 src/server/、src/config/、src/types/ 子目录 \ No newline at end of file