hwd32/ai_soc_sw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
473f61b4cc20e6525118d643f006615999e20083
ai_soc_sw/.ai/knowledge/decisions.md
T
tupingr 473f61b4cc feat(template): ADR-013 Skill 替代脚本 — 框架脱敏/初始化机制重构 
- 废弃 ADR-008 双分支+shell脚本方案（ai_project分支已过时）
- 新增 project-init Skill：export（脱敏导出） + init（初始化新项目）双模式
- 保留 SYNC.md（框架/项目边界）+ TEMPLATE.yaml（变量定义）
- L-006: 当 AI 是执行者时，Skill 优于 Shell 脚本
- 3 文件替代 4文件+1分支，零维护成本

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-26 15:33:05 +08:00

13 KiB
Raw Blame History

架构决策记录 (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」协作框架的实质性落地——从抽象角色到具体平台+模型绑定
Reference in New Issue View Git Blame Copy Permalink