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
@@ -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)