2026-05-25 16:49:36 +08:00
|
|
|
|
# 架构决策记录 (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/` 分享层
|
2026-05-25 17:23:06 +08:00
|
|
|
|
|
|
|
|
|
|
## ADR-008: 框架/项目双分支 + 同步机制
|
|
|
|
|
|
|
|
|
|
|
|
- 日期: 2026-05-25
|
|
|
|
|
|
- 状态: 已采纳
|
|
|
|
|
|
- 决策: 采用双分支策略：`main` 分支开发具体项目（ErrLens），`ai_project` 分支保持为去敏的通用模板。通过 `sync-template.sh` 从 main 单向同步框架层变化到模板分支
|
|
|
|
|
|
- 理由:
|
|
|
|
|
|
- 框架层变化需要传播到模板，但重做去敏化消耗巨大（~100K tokens）
|
|
|
|
|
|
- 两个分支的差异本质是"变量替换"，可以脚本自动化
|
|
|
|
|
|
- 框架层（AGENTS/权限/提示词/工作流）和项目层（任务/日志/代码）的边界清晰
|
|
|
|
|
|
- 影响:
|
|
|
|
|
|
- 新增 `SYNC.md` 定义框架层/项目层边界
|
|
|
|
|
|
- 新增 `sync-template.sh` 实现自动同步
|
|
|
|
|
|
- 新增 `TEMPLATE.yaml` + `init.sh` 实现一键初始化
|
|
|
|
|
|
- AI 项目框架从此可复用，token 节省 95%+
|
2026-05-26 12:00:52 +08:00
|
|
|
|
|
|
|
|
|
|
## 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 可用性
|
