fix(framework): 宪法+目录框架整改——统一权限体系、覆盖后端路径、补齐提示词、工作流闭环

- 权限矩阵: 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
2026-05-23 20:55:12 +08:00
parent 63038dd124
commit 4083fadb2a
26 changed files with 554 additions and 107 deletions
@@ -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/",
@@ -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": {
@@ -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"]
  }
-}
+}
@@ -1 +1,6 @@
-# coding
+# Dev AI 提示词库
+
+| 文件 | 说明 |
+|------|------|
+| [code-style.md](code-style.md) | 代码风格、命名规范、目录组织 |
+| [doc-template.md](doc-template.md) | impact.md / acceptance.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` 全局变量）
@@ -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。
@@ -1 +1,5 @@
-# testing
+# QA AI 提示词库
+
+| 文件 | 说明 |
+|------|------|
+| [bug-report.md](bug-report.md) | 测试反馈 / Bug 报告模板与格式规范 |
@@ -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 条**：聚焦最重要的