本章总览
技术难点用问题—方案—文件结构讲解真实工程挑战。不是炫技，而是帮你建立「生产级 Agent 难在哪」的判断力。
学完本章你应该能
- 理解流式 tool_use 为何难
- 理解压缩与权限的产品-工程权衡
核心概念（先读懂这些）
难点来自约束叠加
API 约束 + 终端 UX + 安全 + 成本，四者同时满足才形成现有设计。
1. 流式 Tool Use 并发执行
**问题Claude API 以 streaming 方式返回 content blocks，tool_use 块可能在 text 块之前/之间到达。Agent 需要在收包过程中就开始执行工具，而非等完整响应。
**解决方案StreamingToolExecutor 维护 TrackedTool 队列。concurrency-safe 工具(Read/Grep/WebFetch)可并行；Bash/Edit 等 exclusive 工具独占执行。Bash 出错时 siblingAbortController 终止兄弟进程但不 abort 整个 turn。
**关键文件services/tools/StreamingToolExecutor.ts · services/tools/toolExecution.ts · query.ts
2. 上下文窗口管理与自动压缩
**问题多轮对话 + 工具结果会快速填满 200K token 上下文。需在合适时机压缩历史，且压缩后不能丢失关键信息或破坏 API message 格式。
**解决方案autoCompact 监控 token 使用率，接近阈值时调用 compactConversation 生成摘要替换旧消息。支持 microcompact(API 级)、sessionMemory、reactiveCompact 多种策略。GrowthBook 控制阈值参数。
**关键文件services/compact/autoCompact.ts · services/compact/compact.ts · utils/tokens.ts
3. 编译期 Feature Gate (Bun DCE)
**问题内部功能(KAIROS/DAEMON/COORDINATOR)不能泄露到公开发布包。需要编译期条件剔除，而非运行时 if。
**解决方案Bun 的 feature() 是编译内建函数。内部构建 feature("KAIROS")=true，外部=false，Dead Code Elimination 完全移除。108 个模块因此不在 npm 包中。
**关键文件tools.ts · main.tsx · query.ts · bun:bundle
4. 权限系统与用户信任
**问题Agent 可执行 Shell/写文件/访问网络。需在安全与效率间平衡：每次弹窗确认 vs 自动批准 vs 完全绕过。
**解决方案CanUseToolFn 钩子链：check permission mode → yolo classifier(AI 判断) → 用户弹窗 → deny/allow。PermissionMode: default/plan/acceptEdits/bypassPermissions。Denial tracking 防止重复询问。
**关键文件hooks/useCanUseTool.ts · utils/permissions/ · components/permissions/
5. MCP 协议集成
**问题需同时连接多个 MCP 服务器(stdio/SSE/HTTP)，动态发现 tools/resources，处理 auth/elicitation，与内置工具共存。
**解决方案services/mcp/client.ts 管理连接池。MCPTool 将 MCP tool 映射为 Claude tool schema。ListMcpResourcesTool/ReadMcpResourceTool 暴露资源访问。Server approval UI 首次连接确认。
**关键文件services/mcp/client.ts · tools/MCPTool/ · services/mcp/auth.ts
6. 冷启动性能优化
**问题CLI 工具用户对启动速度敏感。4684 行 main.tsx + 135ms imports 不可接受。
**解决方案cli.tsx --version 零 import 快速路径；MDM/Keychain prefetch 与 import 并行；startupProfiler 埋点；动态 import 延迟加载 REPL/MCP。
**关键文件entrypoints/cli.tsx · main.tsx · utils/startupProfiler.js
7. 子代理 (AgentTool) 递归
**问题主 Agent 可派发 Explore/Bash 子代理，子代理又有自己的 query 循环。需隔离 context、追踪成本、限制深度。
**解决方案AgentTool 创建独立 ToolUseContext，继承 canUseTool 但限制工具集。runAgent.ts 启动子 query 循环。forkedAgent 支持 self-fork。QueryGuard 防止无限递归。
**关键文件tools/AgentTool/runAgent.ts · utils/forkedAgent.ts · utils/QueryGuard.ts
8. 会话持久化与恢复
**问题用户期望 /resume 恢复完整会话：messages、文件状态、权限历史、compact 边界。
**解决方案sessionStorage.ts 将会话序列化到 ~/.claude/projects/。FileStateCache 追踪已读文件快照。Compact boundary message 标记压缩点。Migration 处理旧格式升级。
**关键文件utils/sessionStorage.ts · utils/fileStateCache.ts · commands/resume/
本章小结与延伸
每难一点都对应具体文件。读完后去 challenges 提到的路径验证。 继续学习：