💡 可借鉴的 Agent 设计思路

问题：Agent 需要同时处理"会话状态管理"（跨轮次记忆、费用跟踪、SDK输出）和"行为循环"（API调用、工具执行），两者职责不同但又紧密耦合。

Claude Code 方案：外层 QueryEngine（AsyncGenerator）管理会话生命周期，内层 queryLoop（无限 while 循环）只关心一次请求的完整"思考-行动-观察"周期。外层通过 for await...of 消费内层产出的消息流。

两层之间通过 yield* 传递消息，内层的每个 yield 都会透传到 SDK 调用者。这让内层可以独立测试，外层可以专注于状态管理。

问题：等待 API 流式响应完全结束再开始执行工具，会造成显著延迟（API 延迟 + 工具执行延迟串行叠加）。

Claude Code 方案：StreamingToolExecutor 在 API 流式过程中，一旦某个 tool_use 块到达，立即异步开始执行该工具，无需等待整个响应完成。通过 isConcurrencySafe() 判断哪些工具可以并发：读操作（文件读/搜索/MCP）并发执行，写操作（文件写/Bash）串行执行。这通常可以节省数百毫秒的延迟。

问题：系统提示词是一个复杂的动态文档，随功能增加变得难以维护。不同部分有不同的缓存需求（静态/动态），手动拼接容易出错。

Claude Code 方案：每个提示词段由独立函数生成，通过 systemPromptSection(name, fn) 注册到注册表，由框架统一调用并缓存。静态段（角色定义、行为规范）走全局 Prompt Cache，动态段（环境信息、MCP 指令）每轮重新计算。BOUNDARY 标记精确分隔缓存域。

问题：Agent 工具调用权限控制需要平衡"自动化效率"和"用户安全"，纯人工确认太慢，完全自动化太危险。

Claude Code 方案：12步决策管道，越危险的检查越靠前，部分检查"免疫绕过"（即使 bypassPermissions 模式也无法跳过）。5种权限模式满足不同使用场景（开发调试 vs 生产部署）。规则引擎支持精细的内容级规则（如只允许 git status，禁止 git push）。

问题：生产环境中的 Agent 会遭遇各种 API 错误（上下文过长、输出截断、模型不可用），如果每种错误都暴露给用户，体验极差。

Claude Code 方案： (1) 413 prompt_too_long → 触发 Reactive Compact，自动摘要历史消息后重试； (2) max_output_tokens → 先升级到 64k max_tokens，再注入 nudge 消息最多重试 3 次； (3) 模型过载 → 自动切换 fallback 模型，清空孤儿消息，用系统通知告知用户。 三条路径相互独立，失败时才最终将错误暴露给用户。

问题：长任务中对话历史会无限增长，最终触发上下文限制导致任务中断。手动压缩打断用户工作流。

Claude Code 方案：每轮迭代前检查 token 数量，超过阈值时调用独立的压缩 API 生成摘要，以摘要替换原始历史（AutoCompact）。TOKEN_BUDGET 特性允许用户指定目标 token 消耗量，不足时自动注入 nudge 消息促使 Agent 继续工作直至目标达到。

问题：大型任务需要多 Agent 并行执行，但 LLM 的对话模型天生是同步单线程的，如何实现真正的并行？

Claude Code 方案：主 Agent 通过 AgentTool 派发异步 Worker，立即返回不等待。Worker 的结果以 XML 格式（task-notification）注入到主 Agent 的下一轮用户消息中，主 Agent 通过 task-id 识别来源并综合处理。SendMessageTool 允许主 Agent 向运行中的 Worker 发送追加指令。

问题：第三方工具（MCP 服务器）的工具名称可能与内置工具冲突，且连接状态可随时变化。如何设计可插拔的工具生态系统？

Claude Code 方案：所有 MCP 工具自动添加 mcp__服务器名__工具名 前缀命名空间，避免冲突。服务器连接状态有明确的状态机（connected/pending/failed/needs-auth/disabled），UI 实时反映。工具发现通过 ListTools RPC，结果被 memoize 缓存。Agent 的 MCP 配置支持继承（子 Agent 获得父 Agent 的所有 MCP clients）和扩展（Agent 定义文件中声明专属 MCP 服务器）。

问题：Agent 框架需要同时支持多种定制场景：完全自定义的 Agent、系统集成商的定制、用户的个性化偏好，以及框架的默认行为。如何优雅管理这些层次？

Claude Code 方案：4层优先级覆盖链：overridePrompt（完全覆盖）→ Coordinator 提示词 → Agent 定义提示词 → 用户自定义提示词 → 默认提示词。每层可以"替换"或"追加"，appendSystemPrompt 则无论哪层都追加到末尾。

问题：不同的部署场景（企业合规、安全审计、工作流集成）需要在 Agent 行为的关键节点插入自定义逻辑，但又不希望侵入核心代码。

Claude Code 方案：4类 hooks：pre-tool-use（工具调用前，可修改输入或拒绝）、post-tool-use（工具完成后，可检查输出）、user-prompt-submit（用户提交前）、stop（助手消息完成后，可阻止 Agent 继续）。Hooks 以 shell 命令形式配置，通过 stdin/stdout 交互，语言无关。