最小架构

一个最小 Agent 不需要插件和复杂 UI，但必须有清晰边界。

推荐架构：

CLI
  -> QueryEngine
  -> AgentLoop
  -> ModelClient
  -> ToolRegistry
  -> ToolExecutor
  -> PermissionGate
  -> SessionStore

这条简化链路对应 Claude Code 中的几个源码角色：

• QueryEngine.submitMessage()：接收输入并维护会话。
• queryLoop()：执行模型和工具循环。
• Tool：描述工具接口。
• runTools()：执行工具调用。
• hasPermissionsToUseTool()：权限判断。
• assembleToolPool()：组合内置工具和外部工具。
• autoCompactIfNeeded()：长上下文治理。

模块职责

CLI

负责读取用户输入、显示输出、处理退出。

QueryEngine

负责维护一次会话：

• messages。
• session id。
• tool registry。
• permission gate。
• abort controller。

AgentLoop

负责 ReAct 循环：

• 调模型。
• 找 tool_use。
• 执行工具。
• 写回 tool_result。
• 决定是否继续。

ModelClient

封装模型 API。不要让 AgentLoop 直接依赖某个 SDK 的细节。

ToolRegistry

管理可用工具，并生成模型需要的 tool schema。

PermissionGate

统一判断工具是否能执行。

SessionStore

持久化消息和元数据。

模块依赖方向

保持单向依赖：

CLI -> QueryEngine -> AgentLoop -> ToolExecutor -> Tool

不要让 Tool 反向调用 CLI，也不要让 ModelClient 知道 UI。