ai_soc_sw/.ai/knowledge/decisions.md

# 架构决策记录 (ADR)

## ADR-001: "1 人 + 2 AI" 协作框架

- 日期: 2026-05-23
- 状态: 已采纳（后升级为 1 人 + 3 AI）
- 决策: 采用人类负责人 + Dev AI + QA AI 的三角协作模式
- 理由: 单人开发需要 AI 辅助，但 AI 不能互审，需要人类做最终决策
- 影响: 定义了 R/W/RW/- 四级权限体系

## ADR-002: 四级权限体系

- 日期: 2026-05-23
- 状态: 已采纳
- 决策: 采用 `-`(禁止) / `R`(只读) / `W`(可写) / `RW`(读写) 四级权限，比二进制的读写更精细
- 理由: AI 角色需要明确的边界，"只读但不能写"和"完全不可见"需要区分
- 影响: 所有目录访问按权限矩阵执行，`forbidden > read_only > allowed` 优先级

## ADR-003: 根级 docs/ 目录

- 日期: 2026-05-23
- 状态: 已采纳
- 决策: 项目级文档放在根目录 `docs/` 而非子项目内
- 理由: 跨项目共享的文档（架构设计、开发规范）不应属于某个子项目
- 影响: docs/ 由 Arch AI 和 Dev AI 共同维护

## ADR-004: 独立 tools/ 和 data/ 目录

- 日期: 2026-05-23
- 状态: 已采纳
- 决策: 开发工具脚本和训练数据从 shared/ 中独立出来
- 理由: tools 和 data 的使用场景和权限需求与 shared 不同
- 影响: Arch AI 和 Dev AI 可写 tools/ 和 data/，QA AI 只能读 data/

## ADR-005: 工作流重试和升级机制

- 日期: 2026-05-23
- 状态: 已采纳
- 决策: 测试 → 修复循环最多 3 轮，Round 3 仍有 BLOCKER/HIGH 则升级给人类
- 理由: 防止无限循环，确保严重问题得到人类关注
- 影响: `skip_acceptance_on_retry: true`，修复轮次不重写验收标准

## ADR-006: resume-context Skill 多机同步

- 日期: 2026-05-23
- 状态: 已采纳
- 决策: 通过 `resume-context` Skill 实现换电脑时上下文恢复
- 理由: 用户在家和公司两台电脑开发，需要快速恢复 AI 工作上下文
- 影响: 角色检测、关键文档加载、上下文摘要生成

## ADR-007: 分层信息架构 + Token 预算

- 日期: 2026-05-25
- 状态: 已采纳
- 决策: 采用四层信息架构（工作台 → 路线图 → 阶段上下文 → 知识沉淀），每层有 token 预算
- 理由: AI 上下文窗口有限（~200K tokens），旧 AGENTS.md 单体文件浪费 token；每个 AI 角色只需要知道自己该干什么
- 影响: 所有 AI 从 `.ai/roles/{role}/` 启动；新增 `ROADMAP.md`、`DASHBOARD.md`、`docs/share/` 分享层

## ADR-008: 框架/项目双分支 + 同步机制

- 日期: 2026-05-25
- 状态: 已废弃（被 ADR-013 替代，2026-05-26）
- 决策: ~~采用双分支策略：`main` 分支开发具体项目（ErrLens），`ai_project` 分支保持为去敏的通用模板。通过 `sync-template.sh` 从 main 单向同步框架层变化到模板分支~~ 废弃原因：双分支维护成本高，容易过时。ai_project 分支在新架构升级后已严重落后于 main
- 理由（原）:
  - 框架层变化需要传播到模板，但重做去敏化消耗巨大（~100K tokens）
  - 两个分支的差异本质是"变量替换"，可以脚本自动化
  - 框架层（AGENTS/权限/提示词/工作流）和项目层（任务/日志/代码）的边界清晰
- 影响（原）:
  - 新增 `SYNC.md` 定义框架层/项目层边界（保留，被 ADR-013 复用）
  - 新增 `sync-template.sh` 实现自动同步（已删除）
  - 新增 `TEMPLATE.yaml` + `init.sh` 实现一键初始化（TEMPLATE.yaml 保留，init.sh 删除）
  - AI 项目框架从此可复用，token 节省 95%+

## ADR-013: Skill 替代脚本 — 框架脱敏/初始化的正确方式

- 日期: 2026-05-26
- 状态: 已采纳
- 决策: 废弃 ADR-008 的「双分支 + shell 脚本」方案，改为「Skill + 配置文件」方案。框架脱敏和项目初始化由 `project-init` Skill 按需执行，不再维护独立模板分支
- 理由:
  - **双分支方案的问题已被验证**：ADR-008 的 ai_project 分支在新架构升级（dashboard.md / .ai/tasks/ / 归档）后严重过时，SYNC.md 和 sync-template.sh 的文件清单全是旧结构引用
  - **AI 是执行者，不需要可执行脚本**：shell 脚本是给人类或 CI 用的。但当前场景中，脱敏/初始化是由 AI（Claude Code）执行的——AI 需要的是清晰的规格说明（SYNC.md + TEMPLATE.yaml + Skill 指令），而不是可执行脚本
  - **Skill 方案不过时**：脚本写死了文件列表，框架一变脚本就过时。Skill 描述的是「方法」——读 SYNC.md 获取边界 → 读 TEMPLATE.yaml 获取变量 → 执行替换。框架变化时只需更新 SYNC.md，Skill 本身不变
  - **零维护成本**：不再需要 sync-template.sh、init.sh、独立 Git 分支。3 个文件（SYNC.md + TEMPLATE.yaml + Skill）vs 旧方案的 4 个文件 + 1 个分支
- 关键洞察:
  - **「脚本优于 Skill」的前提是执行者是机器**。当执行者是 AI 时，Skill（语义描述 + 约束）优于脚本（硬编码文件列表）
  - **边界定义文件（SYNC.md）是长期资产**，脚本是短期负债——脚本依赖边界定义，但边界定义不应绑定于特定的执行方式
- 影响:
  - 保留 `SYNC.md`（更新为新架构文件结构）
  - 保留 `TEMPLATE.yaml`（变量定义）
  - 新增 `.trae/skills/project-init/SKILL.md`
  - 废弃 `sync-template.sh`、`init.sh`
  - 废弃 `ai_project` 分支（不再维护，仅保留历史参考）

## ADR-009: 人机协同数据质量闭环

- 日期: 2026-05-26
- 状态: 已采纳
- 决策: 不依赖 AI 一次识别准确。AI 识别结果作为"草稿"入库，经用户确认/修正后才进入分析和推荐管道。所有修正记录保留为 P02 训练数据。
- 理由:
  - 手写体 OCR 准确率无法保证 100%（尤其中小学生潦草字迹），错误数据直接进入分析会污染薄弱点诊断和练习推荐
  - 传统方案（调高 AI 准确率）成本极高且天花板低。人机协同方案将"用户修正"从成本转化为资产
  - 每一次用户修正 = 一条免费的标注数据，是训练自有模型的核心资源
- 关键设计:
  - verification_status 状态机: raw → reviewed → corrected（+ stale 兜底）
  - 分字段置信度: 每个 AI 字段独立评分，低置信度高亮
  - 数据质量门控: AnalysisReport 和 Recommendation 仅使用 reviewed+ 数据
  - CorrectionLog: AI 值 vs 用户修正值的完整记录
  - 交互设计: 置信度绿/黄/红三级 UI，批量确认降低摩擦
- 影响:
  - error_items 表新增 verification_status + ai_confidence 列
  - 新增 correction_logs 表
  - 分析/推荐查询需加 verification_status 过滤
  - P02 阶段训练数据来源从"外部标注"变为"内部修正记录"

## ADR-010: 题库抽象层设计 —— Adapter Pattern 多源统一接入

- 日期: 2026-05-26
- 状态: 已采纳
- 决策: 采用 Adapter Pattern（适配器模式）实现多题库源的统一接入。自有题库（PDF 录入）和第三方题库（作业帮 API）通过 `QuestionBankAdapter` 接口统一路由，调用方无感知。
- 理由:
  - 旧架构仅自有题库，新架构决定了双题库源（自有 PDF + 作业帮 API），且未来可能有更多来源
  - 如果直接在主业务逻辑中写 `if (source === 'zuoyebang')` 分支判断，每加一个题库源就要改业务代码
  - Adapter Pattern 将"题库源差异"封装在适配器内部，业务逻辑只依赖 `QuestionBankAdapter` 接口
  - 架构已明确: 决策 #1（双题库源）要求"架构层抽象适配"
- 关键设计:
  - 接口定义: `QuestionBankAdapter { source, search(params), getById(id), healthCheck() }`
  - 适配器工厂: `AdapterFactory` 按 `source` 字段路由到对应适配器实例
  - 搜索策略: 并行查询所有适配器 → 合并去重 → 自有题库优先排序
  - 新增题库源: 只需实现 `QuestionBankAdapter` 接口 + 注册到工厂，零业务代码改动
- 影响:
  - `modules/question-bank/adapters/` 目录结构: `base-adapter.ts`, `self-built.adapter.ts`, `zuoyebang.adapter.ts`, `adapter.factory.ts`
  - `questions` 表 `source` 字段 = 适配器路由 key（`self_built` | `zuoyebang` | 未来扩展）
  - `external_id` 字段存储第三方题库的原始 ID，自有题库此字段为空
  - 健康检查: 每个适配器实现 `healthCheck()`，用于监控外部 API 可用性

## ADR-011: 不急于引入多 Agent 编排层 —— 先精简，后分层

- 日期: 2026-05-26
- 状态: 已采纳
- 决策: 当前阶段不引入正式的多 Agent 编排框架（MegaAgent 式 Boss-Admin-Worker 三层架构）。保留「1 人 + 3 AI」角色划分作为逻辑框架，但实际协作由 Claude Code 子 Agent 机制承载。先做 `.ai/` 配置精简（47 → ~20 文件），再评估是否需要模型分层
- 理由:
  - **规模不匹配**：当前是 1 人项目，不是 10 人团队。「编排层」就是人类 + Claude Code 本身，不需要额外的编排 Agent
  - **行业共识未形成**：2025-2026 年业界分裂为两派——多 Agent 编排派（Anthropic/NUS/华为 openJiuwen）和单 Agent 上下文工程派（Cognition/Devin）。后者认为多 Agent 在编码领域是伪命题，隐性决策冲突和整合成本 > 并行收益。Anthropic 也部分承认「编码任务的可并行性远低于研究任务」
  - **架构已是负担**：`.ai/` 47 个文件，Phase 2 代码一行没写。继续加架构层只会加重问题
  - **子 Agent 甜蜜点已确认**：只读研究/探索是最有效的子 Agent 场景，并行编码效果不佳——这与我们当前的实际使用模式一致
- 关键判断:
  - **按业务上下文划分优于按角色划分**（来自 Microsoft 参考架构 + MegaAgent 实践）。如果未来引入多 Agent，应按「认证流」「错题录入流」「推荐流」划分，而非 Arch/Dev/QA
  - **调度层必须是确定性代码**（来自 Microsoft 参考架构）。用 LLM 做任务路由是反模式，应使用脚本/CI/工作流引擎
  - **模型分层（Opus→Sonnet→Haiku）的方向正确**，但应在 Phase 3 功能完善阶段引入，而非现在。MegaAgent 实测成本可降至全 Opus 的 ~1/10
- 影响:
  - `.ai/` 配置精简为近期行动项
  - Arch AI today.md + queue.md 合并
  - Phase 3 前重新评估 Agent 架构，届时根据团队规模和实际瓶颈决定

## ADR-012: 跨平台「高模型指挥小模型」协作架构

- 日期: 2026-05-26
- 状态: 已采纳 + 已落地（2026-05-26 同日，D-001 人类确认后立即执行）
- 决策: 确认当前实际的三平台协作架构——Claude Code + DeepSeek V4 Pro（Arch AI）、Trae CN + GLM-4.6（Coder AI）、Coze CN（Tester AI）——并以此为基准设计任务交接协议。Git 仓库是平台间唯一的通信介质
- 理由:
  - **ADR-011 的前提假设错误**：之前认为所有 AI 角色都在 Claude Code 内切换，因此得出了「架构太多了，先精简」的结论。但实际上三个角色运行在三个完全不同的平台/IDE 上，文档是它们之间唯一的通信协议
  - **跨平台意味着零共享上下文**：Trae + GLM-4.6 不会知道 Claude Code 里讨论了什么。Coze 沙盒不会知道架构设计的细节。所有上下文必须通过 Git 仓库中的文件显式传递
  - **这恰好是一个自然的「高模型指挥小模型」架构**：Arch AI（Claude + DeepSeek V4，最强推理 + 最强 Agent 框架）→ Coder AI（Trae + GLM-4.6，中配模型）→ Tester AI（Coze CN，沙盒执行）
- 关键设计:

**模型能力边界**:

| 角色 | 平台+模型 | 擅长 | 不擅长 |
|------|----------|------|--------|
| Arch | Claude Code + DeepSeek V4 | 架构推理、方案设计、任务分解 | 大量代码输出（token 成本高） |
| Coder | Trae + GLM-4.6 | 代码生成、文件操作 | 复杂推理、多文件协调 |
| Tester | Coze CN | 沙盒执行、自动化验证 | 架构判断、代码修改 |

**任务交接协议（Git 是唯一集成总线）**:
```
Arch 写 task → commit → Coder pull → 读 task → 写代码
    → commit → Tester pull → 跑测试 → 写 report
    → commit → Arch 读报告做决策
```

**关键约束**:
1. 每个 task 必须自包含——不能假设 Coder AI 「知道前面的讨论」。必须包含：明确的输入文件、输出文件、约束条件、参考 ADR
2. 任务粒度适配 GLM-4.6——单文件或强内聚的 2-3 个文件，跨模块协调由 Arch AI 在设计阶段完成
3. 每次 commit 粒度 = 恰好一个交接单元
4. Coze 沙盒做真正的自动化测试闭环——拉代码 → 执行 → 生成 JSON 报告 → commit 回仓库

- 影响:
  - **推翻 ADR-011 的「精简」结论**：架构文档不能砍，但需要重新定位——从「给自己看的备忘录」变成「跨平台的可靠交接协议」
  - Task 模板需要升级：增加「输入」「输出」「约束」「参考 ADR」四个必填字段
  - Dev AI queue.md 的每个任务 description 需要能独立阅读理解，不依赖上下文
  - 这是对 ADR-001「1 人 + 3 AI」协作框架的实质性落地——从抽象角色到具体平台+模型绑定