Agent 架构设计可复用模式总结

1. 概述：从三大 Agent 源码萃取设计范式

通过对 OpenCode、Codex 和 Claude Code 源码的全面剖析，我们可以抽离出构建生产级 AI Agent（例如个人 agent 工作流 util6-agents 或团队自研 Agent 引擎）的四大核心通用模式：

┌─────────────────────────────────────────────────────────┐
│              Reusable Agent Architecture Patterns       │
│                                                         │
│  1. 状态驱动主循环 (State-Driven Turn Machine)           │
│  2. 分级蒸馏上下文策略 (Multi-Tier Compaction Strategy)   │
│  3. 最小权限沙箱与防护墙 (Zero-Trust Sandbox Guard)       │
│  4. 解耦协议客户端 (Protocol-First External Adaptation) │
└─────────────────────────────────────────────────────────┘

---

2. 模式一：状态驱动的主循环 (State-Driven Turn Machine)

核心解构（借鉴 Codex & OpenCode）：

传统的 Agent 往往写成单次 while(has_tool_call) 的线性死循环，容易导致打断困难、死锁或状态混乱。

• 模式方案：建立显式的 AgentStatus（Idle / Running / AwaitingApproval / Compacting / Error）。
• 可复用借鉴：
  • 将每次用户输入或自动提议抽象为标准的 Turn。
  • 使用异步消息队列（如 Rust mpsc 或 Node.js EventEmitter）分发状态，UI 与引擎层完全解耦。

---

3. 模式二：分级蒸馏上下文策略 (Multi-Tier Compaction Strategy)

核心解构（借鉴 Claude Code & Codex）：

在长会话场景下，直接暴力的滑动窗口截断（Sliding Window）容易丢失关键 System Message 或需求设定；而全量 LLM Summarize 又开销昂贵。

• 模式方案：结合 Snip/Microcompact + LLM Summarization 的多级防线：
  1. Tier 1 (SnipCompact)：静态裁减。清空旧工具产生的巨量大文本日志 (Observation Output)，仅保留 Tool Name 与 Status。
  2. Tier 2 (Auto Compaction)：当估算 Token 接近上限（如 80%）时，通过定型 Prompt 生成带前缀的结构化摘要，替换历史 Turns。
  3. Tier 3 (Mid-turn Shield)：在单次循环内部做局部防溢出拦截。

---

4. 模式三：最小权限沙箱与防护墙 (Zero-Trust Sandbox Guard)

核心解构（借鉴 Codex）：

不能依赖 LLM 的自觉性来保证安全性。必须在工具执行引擎的前端建立强硬的安全防线。

• 模式方案：
  1. AST / 标准化解析：下发命令前先做 Shell 语法 AST 拆解，屏蔽类似 python -c "..." 等无监控危险指令。
  2. 三级 Approval：Always / Granular / Never。
  3. 宿主隔离容器：对于高风险写操作，优先在受限 Namespace / 虚拟目录内实施，防止危险写操作扩散到项目目录外。

---

5. 模式四：解耦协议客户端 (Protocol-First Adaptation)

核心解构（借鉴 OpenCode & Codex）：

将工具能力（Tool System）与 Agent 主控制流完全拆离。

• 模式方案：
  • 标准化 MCP 接入：统一通过 Model Context Protocol 暴露扩展工具，Agent 核心只实现标准的 MCP Host 客户端。
  • 按需延迟连接 (Lazy Binding)：不随 Agent 启动挂载全部 MCP 进程，而是根据当前任务激活对应的 Skill/Server，有效减少资源消耗。

---

6. 总结与落地指南

在建设 util6-agents 或构建定制 Agent 工作流时，应当：

1. 优先使用显式状态机与事件通道驱动 Turn 循环；
2. 规范化输入输出的增量 Trace 落盘（SQLite + JSONL）；
3. 实现安全前置评估（禁止危险内联代码执行）；
4. 拥抱 MCP 与 Skill 规范，实现生态能力的高效复用。