From 4083fadb2a427137b699d897c39d53ae6f3d3026 Mon Sep 17 00:00:00 2001 From: hwd32 Date: Sat, 23 May 2026 20:55:12 +0800 Subject: [PATCH] =?UTF-8?q?fix(framework):=20=E5=AE=AA=E6=B3=95+=E7=9B=AE?= =?UTF-8?q?=E5=BD=95=E6=A1=86=E6=9E=B6=E6=95=B4=E6=94=B9=E2=80=94=E2=80=94?= =?UTF-8?q?=E7=BB=9F=E4=B8=80=E6=9D=83=E9=99=90=E4=BD=93=E7=B3=BB=E3=80=81?= =?UTF-8?q?=E8=A6=86=E7=9B=96=E5=90=8E=E7=AB=AF=E8=B7=AF=E5=BE=84=E3=80=81?= =?UTF-8?q?=E8=A1=A5=E9=BD=90=E6=8F=90=E7=A4=BA=E8=AF=8D=E3=80=81=E5=B7=A5?= =?UTF-8?q?=E4=BD=9C=E6=B5=81=E9=97=AD=E7=8E=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 权限矩阵: RL/R/W/RW 四态替代 ✅/❌，三文件语义对齐 - 目录重构: server/config/types 移入 src/，projects/*/src/ 全覆盖 - 提示词库: 新增 code-style.md / doc-template.md / bug-report.md - 工作流: 8阶段→4阶段，新增 retry 循环 + escalation 升级规则 - 审核报告: reports/quality-reports/framework-review-2026-05-23.md --- .ai/config/coder.json | 13 +- .ai/config/tester.json | 5 +- .ai/config/workflow.json | 37 ++-- .ai/prompts/coding/README.md | 7 +- .ai/prompts/coding/code-style.md | 105 ++++++++++ .ai/prompts/coding/doc-template.md | 76 ++++++++ .ai/prompts/testing/README.md | 6 +- .ai/prompts/testing/bug-report.md | 67 +++++++ AGENTS.md | 109 ++++++----- projects/P01_errlens_app/ENVIRONMENT.md | 12 +- projects/P01_errlens_app/docs/02_架构设计.md | 38 ++-- .../P01_errlens_app/{ => src}/config/dev.ts | 0 .../P01_errlens_app/{ => src}/config/index.ts | 0 .../P01_errlens_app/{ => src}/config/prod.ts | 0 .../{ => src}/server/nest-cli.json | 0 .../{ => src}/server/package.json | 0 .../{ => src}/server/src/app.controller.ts | 0 .../{ => src}/server/src/app.module.ts | 0 .../{ => src}/server/src/app.service.ts | 0 .../interceptors/http-status.interceptor.ts | 0 .../{ => src}/server/src/main.ts | 0 .../{ => src}/server/tsconfig.json | 0 .../{ => src}/types/global.d.ts | 0 .../{ => src}/types/lucide.d.ts | 0 projects/P01_errlens_app/tsconfig.json | 2 +- .../framework-review-2026-05-23.md | 184 ++++++++++++++++++ 26 files changed, 554 insertions(+), 107 deletions(-) create mode 100644 .ai/prompts/coding/code-style.md create mode 100644 .ai/prompts/coding/doc-template.md create mode 100644 .ai/prompts/testing/bug-report.md rename projects/P01_errlens_app/{ => src}/config/dev.ts (100%) rename projects/P01_errlens_app/{ => src}/config/index.ts (100%) rename projects/P01_errlens_app/{ => src}/config/prod.ts (100%) rename projects/P01_errlens_app/{ => src}/server/nest-cli.json (100%) rename projects/P01_errlens_app/{ => src}/server/package.json (100%) rename projects/P01_errlens_app/{ => src}/server/src/app.controller.ts (100%) rename projects/P01_errlens_app/{ => src}/server/src/app.module.ts (100%) rename projects/P01_errlens_app/{ => src}/server/src/app.service.ts (100%) rename projects/P01_errlens_app/{ => src}/server/src/interceptors/http-status.interceptor.ts (100%) rename projects/P01_errlens_app/{ => src}/server/src/main.ts (100%) rename projects/P01_errlens_app/{ => src}/server/tsconfig.json (100%) rename projects/P01_errlens_app/{ => src}/types/global.d.ts (100%) rename projects/P01_errlens_app/{ => src}/types/lucide.d.ts (100%) create mode 100644 reports/quality-reports/framework-review-2026-05-23.md diff --git a/.ai/config/coder.json b/.ai/config/coder.json index ffe122f..74a7f71 100644 --- a/.ai/config/coder.json +++ b/.ai/config/coder.json @@ -1,23 +1,28 @@ { "name": "Dev AI", "role": "代码开发者", + "description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。", "responsibilities": [ "编写业务代码", "生成技术文档", - "维护代码质量" + "定义验收标准", + "评估变更影响", + "维护共享资源" ], "allowed_paths": [ "projects/*/src/", "projects/*/docs/", "shared/", - "review/*/task.md", "review/*/acceptance.md", "review/*/impact.md" ], + "read_only_paths": [ + "review/*/task.md", + "review/*/feedback/" + ], "forbidden_paths": [ "projects/*/tests/", - "reports/", - "review/*/feedback/" + "reports/" ], "prompt_templates": { "coding": ".ai/prompts/coding/", diff --git a/.ai/config/tester.json b/.ai/config/tester.json index eef3c42..4dc107f 100644 --- a/.ai/config/tester.json +++ b/.ai/config/tester.json @@ -1,6 +1,7 @@ { "name": "QA AI", "role": "测试工程师", + "description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。", "responsibilities": [ "编写测试用例", "执行测试", @@ -13,11 +14,13 @@ "review/*/acceptance.md", "review/*/feedback/" ], + "read_only_paths": [ + "review/*/task.md" + ], "forbidden_paths": [ "projects/*/src/", "projects/*/docs/", "shared/", - "review/*/task.md", "review/*/impact.md" ], "prompt_templates": { diff --git a/.ai/config/workflow.json b/.ai/config/workflow.json index 5fe31c7..86127fe 100644 --- a/.ai/config/workflow.json +++ b/.ai/config/workflow.json @@ -11,33 +11,13 @@ "name": "开发实现", "actor": "dev-ai", "input": "review/{task_id}/task.md", - "output": ["projects/*/src/", "projects/*/docs/"] + "output": ["projects/*/src/", "projects/*/docs/", "review/{task_id}/impact.md", "review/{task_id}/acceptance.md"] }, { - "name": "影响评估", - "actor": "dev-ai", - "output": "review/{task_id}/impact.md" - }, - { - "name": "验收标准定义", - "actor": "dev-ai", - "output": "review/{task_id}/acceptance.md" - }, - { - "name": "测试设计", + "name": "测试验证", "actor": "qa-ai", "input": ["review/{task_id}/task.md", "review/{task_id}/acceptance.md"], - "output": "projects/*/tests/" - }, - { - "name": "测试执行", - "actor": "qa-ai", - "output": ["reports/test-results/", "reports/reviews/"] - }, - { - "name": "反馈提交", - "actor": "qa-ai", - "output": "review/{task_id}/feedback/round{round}.md" + "output": ["projects/*/tests/", "reports/test-results/", "review/{task_id}/feedback/round{round}.md"] }, { "name": "验收确认", @@ -45,9 +25,18 @@ "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"] } -} \ No newline at end of file +} diff --git a/.ai/prompts/coding/README.md b/.ai/prompts/coding/README.md index 2c25e4e..d4c0f7c 100644 --- a/.ai/prompts/coding/README.md +++ b/.ai/prompts/coding/README.md @@ -1 +1,6 @@ -# coding +# Dev AI 提示词库 + +| 文件 | 说明 | +|------|------| +| [code-style.md](code-style.md) | 代码风格、命名规范、目录组织 | +| [doc-template.md](doc-template.md) | impact.md / acceptance.md 等文档模板 | diff --git a/.ai/prompts/coding/code-style.md b/.ai/prompts/coding/code-style.md new file mode 100644 index 0000000..d6c7317 --- /dev/null +++ b/.ai/prompts/coding/code-style.md @@ -0,0 +1,105 @@ +# 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. 样式文件 +``` + +示例： +```typescript +import { useState } from 'react'; +import Taro from '@tarojs/taro'; +import { Button } from '@/components/ui/button'; +import { formatDate } from './lib/date'; +import './index.css'; +``` + +## 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` 全局变量） diff --git a/.ai/prompts/coding/doc-template.md b/.ai/prompts/coding/doc-template.md new file mode 100644 index 0000000..adfbb9b --- /dev/null +++ b/.ai/prompts/coding/doc-template.md @@ -0,0 +1,76 @@ +# 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。 diff --git a/.ai/prompts/testing/README.md b/.ai/prompts/testing/README.md index 5697da2..70b0387 100644 --- a/.ai/prompts/testing/README.md +++ b/.ai/prompts/testing/README.md @@ -1 +1,5 @@ -# testing +# QA AI 提示词库 + +| 文件 | 说明 | +|------|------| +| [bug-report.md](bug-report.md) | 测试反馈 / Bug 报告模板与格式规范 | diff --git a/.ai/prompts/testing/bug-report.md b/.ai/prompts/testing/bug-report.md new file mode 100644 index 0000000..4722524 --- /dev/null +++ b/.ai/prompts/testing/bug-report.md @@ -0,0 +1,67 @@ +# 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 条**：聚焦最重要的 diff --git a/AGENTS.md b/AGENTS.md index 320e789..208a03a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,10 +29,13 @@ - ✅ 评估变更影响 (`review/*/impact.md`) - ✅ 维护共享资源 (`shared/`) +**可读但不可写：** +- 👁 任务描述 (`review/*/task.md`) —— 只读，不可修改 +- 👁 测试反馈 (`review/*/feedback/`) —— 只读，用于修 Bug + **禁止操作：** - ❌ 修改测试代码 (`projects/*/tests/`) - ❌ 修改测试报告 (`reports/`) -- ❌ 提交测试反馈 (`review/*/feedback/`) ### QA AI (测试AI) **职责范围：** @@ -41,11 +44,14 @@ - ✅ 补充验收标准 (`review/*/acceptance.md`) - ✅ 提交测试反馈 (`review/*/feedback/`) +**可读但不可写：** +- 👁 任务描述 (`review/*/task.md`) —— 只读，了解测试目标 + **禁止操作：** - ❌ 修改业务代码 (`projects/*/src/`) - ❌ 修改技术文档 (`projects/*/docs/`) - ❌ 修改共享资源 (`shared/`) -- ❌ 修改任务描述和影响评估 +- ❌ 修改影响评估 (`review/*/impact.md`) ### 人类负责人 **职责范围：** @@ -59,22 +65,14 @@ ## 工作流程 ``` -┌─────────────┐ ┌─────────────┐ ┌─────────────┐ -│ 需求分析 │ ──→ │ 开发实现 │ ──→ │ 影响评估 │ -│ (人类) │ │ (Dev AI) │ │ (Dev AI) │ -└─────────────┘ └─────────────┘ └─────────────┘ - │ │ │ - ▼ ▼ ▼ -┌─────────────┐ ┌─────────────┐ ┌─────────────┐ -│ 验收标准 │ ──→ │ 测试设计 │ ──→ │ 测试执行 │ -│ (Dev AI) │ │ (QA AI) │ │ (QA AI) │ -└─────────────┘ └─────────────┘ └─────────────┘ - │ - ▼ -┌─────────────┐ ┌─────────────┐ -│ 反馈提交 │ ──→ │ 验收确认 │ -│ (QA AI) │ │ (人类) │ -└─────────────┘ └─────────────┘ +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ 需求分析 │ ───→ │ 开发实现 │ ───→ │ 测试验证 │ ───→ │ 验收确认 │ +│ (人类) │ │ (Dev AI) │ │ (QA AI) │ │ (人类) │ +└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ + ↑ │ + │ Bug → 修复 │ + └──────────────────────┘ + (最多 2 轮) ``` ### 详细流程说明 @@ -84,51 +82,62 @@ - 输出: `review/{task_id}/task.md` **2. 开发实现阶段** -- Dev AI 根据任务描述编写代码 -- 输出: `projects/*/src/`, `projects/*/docs/` +- Dev AI 读取任务描述，编写代码 + 文档 +- 同时输出验收标准和变更影响范围 +- 输出: `projects/*/src/`, `projects/*/docs/`, `review/{task_id}/impact.md`, `review/{task_id}/acceptance.md` -**3. 影响评估阶段** -- Dev AI 分析变更影响范围 -- 输出: `review/{task_id}/impact.md` +**3. 测试验证阶段** +- QA AI 根据验收标准编写测试，执行测试，生成报告 +- 测试反馈写入 `review/{task_id}/feedback/round{round}.md` +- 输出: `projects/*/tests/`, `reports/test-results/`, `review/{task_id}/feedback/` -**4. 验收标准定义** -- Dev AI 定义验收标准 -- QA AI 可补充测试要点 -- 输出: `review/{task_id}/acceptance.md` +### 缺陷修复循环 -**5. 测试设计阶段** -- QA AI 根据验收标准编写测试用例 -- 输出: `projects/*/tests/` +| 规则 | 说明 | +|------|------| +| 最大轮次 | 3 轮（初始测试 + 最多 2 轮修复复查） | +| 循环范围 | 测试失败 → Dev AI 修复 → QA AI 复查 | +| 跳过项 | 修复轮次中 Dev AI **只修 Bug**，不重新写 acceptance/impact | +| 触发升级 | 第 3 轮仍有 BLOCKER 或 HIGH 级别 Bug → 暂停流转，待人类裁决 | -**6. 测试执行阶段** -- QA AI 执行测试并生成报告 -- 输出: `reports/test-results/`, `reports/quality-reports/` +``` +Round 1: Dev 开发 → QA 测试 → 3 个 Bug +Round 2: Dev 修复 → QA 复查 → 1 个 Bug（MEDIUM） +Round 3: Dev 修复 → QA 复查 → 0 个 Bug ✅ → 提交人类验收 +``` -**7. 反馈提交阶段** -- QA AI 提交测试反馈 -- 输出: `review/{task_id}/feedback/round{round}.md` +如果 Round 3 仍有 BLOCKER/HIGH： +``` +Round 3: Dev 修复 → QA 复查 → 仍 1 个 HIGH → ⚠️ 升级给人类裁决 +``` -**8. 验收确认阶段** -- 人类负责人审核测试结果 -- 确认任务完成或返回修改 +**4. 验收确认阶段** +- 人类审核测试报告，确认任务完成或驳回 +- 确认后任务状态更新为 DONE，移入 `review/archived/` --- ## 目录权限矩阵 +> **图例**：`-` = 无权访问    `R` = 只读    `W` = 可写（含读）    `RW` = 读写 + | 目录路径 | Dev AI | QA AI | 人类 | |---------|--------|-------|------| -| `.ai/` | ❌ | ❌ | ✅ | -| `shared/` | ✅ | ❌ | ✅ | -| `projects/*/src/` | ✅ | ❌ | ✅ | -| `projects/*/tests/` | ❌ | ✅ | ✅ | -| `projects/*/docs/` | ✅ | ❌ | ✅ | -| `review/*/task.md` | ❌ | ❌ | ✅ | -| `review/*/acceptance.md` | ✅ | ✅ | ✅ | -| `review/*/impact.md` | ✅ | ❌ | ✅ | -| `review/*/feedback/` | ❌ | ✅ | ✅ | -| `reports/` | ❌ | ✅ | ✅ | -| `.github/` | ❌ | ❌ | ✅ | +| `.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 访问（等效于 `-`）。 --- diff --git a/projects/P01_errlens_app/ENVIRONMENT.md b/projects/P01_errlens_app/ENVIRONMENT.md index dc2bb42..af24505 100644 --- a/projects/P01_errlens_app/ENVIRONMENT.md +++ b/projects/P01_errlens_app/ENVIRONMENT.md @@ -57,9 +57,9 @@ npm install ### 3. 安装后端依赖 ```bash -cd server +cd src/server pnpm install -cd .. +cd ../.. ``` ### 4. 配置环境变量 @@ -80,7 +80,7 @@ PROJECT_DOMAIN= API_BASE_URL=/api ``` -**后端环境变量 (`server/.env`)**: +**后端环境变量 (`src/server/.env`)**: ```bash # 服务端口 PORT=3000 @@ -120,7 +120,7 @@ pnpm dev:tt pnpm dev:server # 或 -cd server +cd src/server pnpm dev ``` @@ -166,7 +166,7 @@ pnpm validate ### 开发环境 ```bash -cd server +cd src/server # 运行迁移 pnpm drizzle-kit migrate @@ -187,7 +187,7 @@ P01_errlens_app/ │ ├── lib/ # 工具库 │ └── network.ts # API 封装 │ -├── server/ # 后端源码 (NestJS) +│ ├── server/ # 后端源码 (NestJS) │ └── src/ │ ├── tests/ # 测试代码 diff --git a/projects/P01_errlens_app/docs/02_架构设计.md b/projects/P01_errlens_app/docs/02_架构设计.md index 471b05a..b66ac72 100644 --- a/projects/P01_errlens_app/docs/02_架构设计.md +++ b/projects/P01_errlens_app/docs/02_架构设计.md @@ -82,25 +82,25 @@ P01_errlens_app/ │ │ │ └── network.ts # API 请求封装 │ -├── server/ # 后端源码 (NestJS) -│ ├── src/ -│ │ ├── app.module.ts # 根模块 -│ │ ├── app.controller.ts # 根控制器 -│ │ ├── app.service.ts # 根服务 -│ │ └── main.ts # 入口文件 +│ ├── server/ # 后端源码 (NestJS) +│ │ ├── src/ +│ │ │ ├── app.module.ts # 根模块 +│ │ │ ├── app.controller.ts# 根控制器 +│ │ │ ├── app.service.ts # 根服务 +│ │ │ └── main.ts # 入口文件 +│ │ │ +│ │ ├── nest-cli.json +│ │ ├── tsconfig.json +│ │ └── package.json │ │ -│ ├── nest-cli.json -│ ├── tsconfig.json -│ └── package.json -│ -├── config/ # 构建配置 -│ ├── index.ts # 通用配置 -│ ├── dev.ts # 开发环境配置 -│ └── prod.ts # 生产环境配置 -│ -├── types/ # 类型定义 -│ ├── global.d.ts -│ └── lucide.d.ts +│ ├── config/ # 构建配置 +│ │ ├── index.ts # 通用配置 +│ │ ├── dev.ts # 开发环境配置 +│ │ └── prod.ts # 生产环境配置 +│ │ +│ ├── types/ # 类型定义 +│ │ ├── global.d.ts +│ │ └── lucide.d.ts │ ├── tests/ # 测试代码 │ ├── unit/ # 单元测试 @@ -160,7 +160,7 @@ P01_errlens_app/ ### 4. 后端模块 ``` -server/src/ +src/server/src/ ├── controllers/ # 控制器 ├── services/ # 业务逻辑 ├── modules/ # NestJS 模块 diff --git a/projects/P01_errlens_app/config/dev.ts b/projects/P01_errlens_app/src/config/dev.ts similarity index 100% rename from projects/P01_errlens_app/config/dev.ts rename to projects/P01_errlens_app/src/config/dev.ts diff --git a/projects/P01_errlens_app/config/index.ts b/projects/P01_errlens_app/src/config/index.ts similarity index 100% rename from projects/P01_errlens_app/config/index.ts rename to projects/P01_errlens_app/src/config/index.ts diff --git a/projects/P01_errlens_app/config/prod.ts b/projects/P01_errlens_app/src/config/prod.ts similarity index 100% rename from projects/P01_errlens_app/config/prod.ts rename to projects/P01_errlens_app/src/config/prod.ts diff --git a/projects/P01_errlens_app/server/nest-cli.json b/projects/P01_errlens_app/src/server/nest-cli.json similarity index 100% rename from projects/P01_errlens_app/server/nest-cli.json rename to projects/P01_errlens_app/src/server/nest-cli.json diff --git a/projects/P01_errlens_app/server/package.json b/projects/P01_errlens_app/src/server/package.json similarity index 100% rename from projects/P01_errlens_app/server/package.json rename to projects/P01_errlens_app/src/server/package.json diff --git a/projects/P01_errlens_app/server/src/app.controller.ts b/projects/P01_errlens_app/src/server/src/app.controller.ts similarity index 100% rename from projects/P01_errlens_app/server/src/app.controller.ts rename to projects/P01_errlens_app/src/server/src/app.controller.ts diff --git a/projects/P01_errlens_app/server/src/app.module.ts b/projects/P01_errlens_app/src/server/src/app.module.ts similarity index 100% rename from projects/P01_errlens_app/server/src/app.module.ts rename to projects/P01_errlens_app/src/server/src/app.module.ts diff --git a/projects/P01_errlens_app/server/src/app.service.ts b/projects/P01_errlens_app/src/server/src/app.service.ts similarity index 100% rename from projects/P01_errlens_app/server/src/app.service.ts rename to projects/P01_errlens_app/src/server/src/app.service.ts diff --git a/projects/P01_errlens_app/server/src/interceptors/http-status.interceptor.ts b/projects/P01_errlens_app/src/server/src/interceptors/http-status.interceptor.ts similarity index 100% rename from projects/P01_errlens_app/server/src/interceptors/http-status.interceptor.ts rename to projects/P01_errlens_app/src/server/src/interceptors/http-status.interceptor.ts diff --git a/projects/P01_errlens_app/server/src/main.ts b/projects/P01_errlens_app/src/server/src/main.ts similarity index 100% rename from projects/P01_errlens_app/server/src/main.ts rename to projects/P01_errlens_app/src/server/src/main.ts diff --git a/projects/P01_errlens_app/server/tsconfig.json b/projects/P01_errlens_app/src/server/tsconfig.json similarity index 100% rename from projects/P01_errlens_app/server/tsconfig.json rename to projects/P01_errlens_app/src/server/tsconfig.json diff --git a/projects/P01_errlens_app/types/global.d.ts b/projects/P01_errlens_app/src/types/global.d.ts similarity index 100% rename from projects/P01_errlens_app/types/global.d.ts rename to projects/P01_errlens_app/src/types/global.d.ts diff --git a/projects/P01_errlens_app/types/lucide.d.ts b/projects/P01_errlens_app/src/types/lucide.d.ts similarity index 100% rename from projects/P01_errlens_app/types/lucide.d.ts rename to projects/P01_errlens_app/src/types/lucide.d.ts diff --git a/projects/P01_errlens_app/tsconfig.json b/projects/P01_errlens_app/tsconfig.json index 9c5e7e2..dcc5a05 100644 --- a/projects/P01_errlens_app/tsconfig.json +++ b/projects/P01_errlens_app/tsconfig.json @@ -24,6 +24,6 @@ "@/*": ["./src/*"] } }, - "include": ["./src", "./types", "./config"], + "include": ["./src"], "compileOnSave": false } diff --git a/reports/quality-reports/framework-review-2026-05-23.md b/reports/quality-reports/framework-review-2026-05-23.md new file mode 100644 index 0000000..ef3bfb0 --- /dev/null +++ b/reports/quality-reports/framework-review-2026-05-23.md @@ -0,0 +1,184 @@ +# ErrLens 宪法 + 目录框架 整改报告 + +> 审核日期：2026-05-23 +> 审核范围：AGENTS.md、AI 配置文件、目录结构、提示词库、工作流 +> 审核标准：三文件一致性、路径覆盖率、语义完备性、工作流闭环 + +--- + +## 修改总览 + +| # | 硬伤 | 动作 | 修改文件数 | +|---|------|------|----------| +| 1 | 三文件对 Dev AI 操作 task.md 权限矛盾 | 统一语义，引入 R/W/RW 体系 | 3 | +| 2 | coder.json 漏掉 AGENTS.md 中的职责 | 补全职责列表 | 1 | +| 3 | `projects/*/src/` 不覆盖后端代码 | server/config/types 移入 src/ | 4 | +| 4 | `.ai/prompts/` 完全空白 | 创建 3 份提示词 + 2 份索引 | 5 | +| 5 | JSON 配置无语义定义 | 加 description + 优先级规则 | 3 | +| 6 | Workflow 缺少循环分支 | 8 阶段→4 阶段 + retry 配置 | 2 | + +--- + +## 详细变更 + +### 硬伤 1+2+5：权限体系统一 + +**发现问题**：`AGENTS.md`、`coder.json`、`tester.json` 对同一路径的权限有三种不同说法。 + +| 文件 | 原来对 `review/*/task.md` 的说法 | +|------|------| +| AGENTS.md 权限矩阵 | Dev AI = ❌（禁止） | +| coder.json | `allowed_paths` 包含它（允许） | +| workflow.json | Dev AI 的 input 是它（只读） | + +**修改内容**： + +| 文件 | 变更内容 | +|------|---------| +| `AGENTS.md` | ① 权限矩阵引入 `R`/`W`/`RW`/`-` 四态（替代 ✅/❌）② 角色描述增加「可读但不可写」段落 ③ 加图例、优先级声明、默认行为声明 | +| `.ai/config/coder.json` | ① 引入 `description` 语义定义 ② `allowed_paths` 只放可写路径 ③ 新增 `read_only_paths` 放只读路径 ④ 补全 5 项职责（与 AGENTS.md 对齐） | +| `.ai/config/tester.json` | 同上改造，QA AI 的 `task.md` 从 forbidden 移到 `read_only_paths` | + +**修改后的关键权限交叉点**： + +| 路径 | Dev AI | QA AI | 含义 | +|------|--------|-------|------| +| `review/*/task.md` | 只读 | 只读 | 两人都能看任务，都不能改 | +| `review/*/feedback/` | 只读 | 读写 | 只有 QA 能写反馈，Dev 只能看 | +| `review/*/impact.md` | 读写 | 禁止 | 只有 Dev 能写影响评估 | +| `projects/*/src/` | 读写 | 禁止 | 业务代码只有 Dev 能碰 | + +**新增规则**： +- 解析优先级：`forbidden > read_only > allowed`（禁止规则永远优先） +- 默认行为：未出现在权限表中的路径，默认禁止所有 AI 访问 + +--- + +### 硬伤 3：后端代码纳入权限保护伞 + +**发现问题**：`projects/*/src/` glob 匹配不到 `server/`、`config/`、`types/`。 + +**执行操作**： + +| 操作 | 详情 | +|------|------| +| 目录移动 | `server/` → `src/server/`、`config/` → `src/config/`、`types/` → `src/types/` | +| 引用修复 | `tsconfig.json`（include 简化）、`ENVIRONMENT.md`（3 处 `cd server` → `cd src/server`）、`docs/02_架构设计.md`（2 处目录结构图 + 代码路径） | + +**效果**：一条 `projects/*/src/` 权限规则覆盖全部业务代码——前端、NestJS 后端、Taro 构建配置、全局类型声明。 + +--- + +### 硬伤 4：.ai/prompts/ 从空壳到可用 + +**发现问题**：`coder.json` 和 `tester.json` 引用 `prompt_templates` 路径，但实际文件只含一行标题。 + +**新增文件**： + +| 文件 | 用途 | +|------|------| +| `.ai/prompts/coding/code-style.md` | 代码风格：命名规范、目录组织（前端+NestJS+Python）、导入顺序、API 规范、禁止事项 | +| `.ai/prompts/coding/doc-template.md` | impact.md 和 acceptance.md 的标准化模板 | +| `.ai/prompts/testing/bug-report.md` | QA AI 反馈格式：严重程度定义（BLOCKER/HIGH/MEDIUM/LOW）、轮次规则、升级条件 | +| `.ai/prompts/coding/README.md` | 重写为可用的文件索引 | +| `.ai/prompts/testing/README.md` | 重写为可用的文件索引 | + +--- + +### 硬伤 6：Workflow 从线性到闭环 + +**发现问题**：8 阶段纯线性流程，没有「测试失败 → 修复 → 再测」的建模。 + +**修改内容**： + +| 文件 | 变更 | +|------|------| +| `.ai/config/workflow.json` | ① 8 阶段合并为 4 阶段（开发实现包含了 impact + acceptance）② 新增 `retry` 配置：`max_rounds=3`，`loop=["测试验证","开发实现"]` ③ 新增 `escalation` 规则 | +| `AGENTS.md` | ① 流程图改版，增加循环箭头 ② 新增「缺陷修复循环」章节 ③ 详细的 round 示例 | + +**修改后的流程**： + +``` +需求分析（人类） + ↓ +开发实现（Dev AI）= 代码 + 文档 + impact + acceptance + ↓ +测试验证（QA AI）= 测试 + 报告 + feedback + ↓ ↑ + │ 有 Bug → │（最多 2 轮修复复查） + ↓ └── 第 3 轮仍有 Bug → 升级给人类裁决 +验收确认（人类） +``` + +**retry 配置详情**： + +```json +{ + "retry": { + "max_rounds": 3, + "loop": ["测试验证", "开发实现"], + "escalation": { + "trigger": "第 3 轮测试仍有 BLOCKER 或 HIGH 级别 Bug", + "action": "暂停任务流转，等待人类负责人裁决" + }, + "skip_acceptance_on_retry": true + } +} +``` + +--- + +## 宪法健康状态 + +| 维度 | 改前 | 改后 | +|------|------|------| +| 权限一致性（三文件对齐） | ❌ 矛盾 | ✅ 统一 | +| 权限粒度（读/写分离） | ❌ 只有全或无 | ✅ R/W/RW 三态 | +| JSON 可读性（有语义定义） | ❌ 无解释 | ✅ 有 description | +| 路径覆盖率（src/ 覆盖全部业务代码） | ❌ 漏掉后端 | ✅ 全覆盖 | +| 提示词库 | ❌ 空壳 | ✅ 3 份可用 | +| 工作流建模（含循环） | ❌ 纯线性 | ✅ 含 retry + escalation | +| 默认行为（路径不在表中） | ❌ 未定义 | ✅ 默认禁止 | +| 优先级（规则冲突时） | ❌ 未定义 | ✅ forbidden 优先 | + +--- + +## 仍待处理的遗留事项 + +| 事项 | 状态 | 说明 | +|------|------|------| +| P01 文档内容 | ⚠️ 未改 | 需求/架构/接口文档内容仍是"代码检测"，后续需重写为"错题本" | +| shared/ 数据协议层 | ⚠️ 仍是空白 | 需要建 `shared/schemas/` 定义跨项目数据模型 | +| shared/ 模板文件 | ⚠️ 缺少 | `shared/templates/` 中没有 task.md 模板 | +| CI/CD 流水线 | ⚠️ 空目录 | `.github/workflows/` 只有 README 占位 | +| Coze 扣子实际能力验证 | ❓ 未知 | 能否操作 Git、能否执行测试——决定 QA AI 验收标准如何定 | + +--- + +## 涉及文件清单 + +### 修改的文件（11 个） +1. `AGENTS.md` +2. `.ai/config/coder.json` +3. `.ai/config/tester.json` +4. `.ai/config/workflow.json` +5. `.ai/prompts/coding/README.md` +6. `.ai/prompts/testing/README.md` +7. `projects/P01_errlens_app/tsconfig.json` +8. `projects/P01_errlens_app/ENVIRONMENT.md` +9. `projects/P01_errlens_app/docs/02_架构设计.md` + +### 新增的文件（5 个） +10. `.ai/prompts/coding/code-style.md` +11. `.ai/prompts/coding/doc-template.md` +12. `.ai/prompts/testing/bug-report.md` + +### 移动的目录（3 个） +- `projects/P01_errlens_app/server/` → `projects/P01_errlens_app/src/server/` +- `projects/P01_errlens_app/config/` → `projects/P01_errlens_app/src/config/` +- `projects/P01_errlens_app/types/` → `projects/P01_errlens_app/src/types/` + +--- + +**报告生成时间**：2026-05-23 +**审核执行者**：Dev AI (Trae)