Agent 架构参考项目索引
用途： 从零构建 Agent 时的设计参考。每个项目列出核心设计、值得借鉴的点、以及最终是否采纳及其原因。 状态： 待逐一深入分析 关联： 司南（Honcho + 路由/ACL/传播控制层）将作为记忆层集成
一、框架级参考
| 项目 | 核心设计 | 值得借鉴 | 分析状态 |
|---|---|---|---|
| Smolagents (HF) | Code-as-Action，Agent 写 Python 代码调工具而非 JSON。~1000 行核心。GAIA 44.2% | 极简 core loop、Code-as-Action 模式、tool sandbox | ⏳ |
| LangGraph | 图状态机 + 显式状态管理 + checkpointing。错误恢复率 ~90%（实测 2000 次） | 状态即持久化、checkpoint 回滚、图模式的状态传递 | ⏳ |
| CrewAI | 角色编排（role/goal/backstory/tools）。但 token 消耗 2-3×，错误恢复 ~0% | 教训：角色通信协议不设计好就是三个话痨传纸条 | ⏳ |
| AutoGen / AG2 (微软) | 对话式多 Agent 协调。2026 已进维护模式，微软推荐 MAF 替代 | 教训：纯对话式协调不可扩展 | ⏳ |
| Mastra | TypeScript 全栈，agents + workflows + RAG + memory + evals + telemetry 一体 | 完整的 agent lifecycle 设计、内建 OpenTelemetry 埋点 | ⏳ |
| Pydantic AI | 类型安全驱动，Agent = Pydantic model。FastAPI 风格 DX | 类型安全接口设计、structured output 验证+重试（Instructor） | ⏳ |
二、工业级参考
| 项目 | 核心设计 | 值得借鉴 | 分析状态 |
|---|---|---|---|
| Claude Code (Anthropic) | while-true 循环只占 1.6% 代码，98.4% 是确定性基础设施 | 7 层安全、5 级上下文压缩 pipeline（有熔断）、27 hook 事件、subagent git worktree 隔离、4 种扩展面 | ⏳ |
| Aider | Repo Map（代码签名压缩）、4 种编辑模式、Git 作为真理源 | Repo Map 算法、多编辑模式适配（diff/udiff/whole/architect）、git 回滚 | ⏳ |
| SWE-Agent (Princeton) | ACI（Agent-Computer Interface）概念——工具接口设计比模型选择更重要 | ACI 方法论、定制化工具 bundle、YAML 定义的轻量工具 | ⏳ |
| OpenCode (160K+ stars) | Go 实现，75+ 模型提供商，隐私优先 | 多 provider 抽象层、Go 工程化架构、零数据存储设计 | ⏳ |
三、设计思想参考
| 项目 | 核心设计 | 值得借鉴 | 分析状态 |
|---|---|---|---|
| MetaGPT | 结构化 SOP 驱动多 Agent 协作。输入需求 → PRD/设计文档/代码，文档即通信 | SOP 驱动协作、结构化文档通信（降低 token 消耗）、角色通过文档流转而非对话 | ⏳ |
| Honcho (Plastic Labs) | Peer 模型的分层记忆 + Deriver/Dialectic/Dreaming 三层推理。36k 行 Python | Dreaming（自治 Agent 循环）、Deriver（消息→观察）、Dialectic（5 级推理深度）。司南的底座 | ✅ 已完成源码分析（notes/honcho-code-analysis.md） |
四、分析维度
每个项目深入分析时按以下框架记录：
## [项目名]
### 架构
- 核心循环 / 状态管理 / 工具调度
- 代码量分布（核心 vs 外围）
### 值得借鉴的设计决策
- [1] ...
- [2] ...
### 不适合我们的部分（以及原因）
- [1] ...
- [2] ...
### 与司南的集成点
- 记忆层怎么接入
- ACL/路由怎么配合
### 采纳结论
- ✅ 采纳 / ❌ 不采纳 / ⚠️ 部分采纳
- 理由：
五、阅读优先级
按大锤建议 + 适合从零参考的排序：
- Smolagents — 先理解最小可行 agent 长什么样（~1000 行核心）
- Aider Repo Map — 上下文压缩最佳实践
- SWE-Agent ACI — 顶层设计思想决定工具成败
- Claude Code 论文（arXiv 2604.14228）— 看完小框架再看完整图景
- MetaGPT SOP 文档流 — 跟司南的路由/传播理念天然契合
- LangGraph / Mastra / Pydantic AI — 框架级对比，需要时再深入
- CrewAI / AutoGen — 教训参考，不需要花太多时间