4.11 设计洞察

1. 统一接口的力量

所有工具——无论是直接访问进程内状态的内置工具、通过 JSON-RPC 连接的 MCP 工具、还是运行在独立 VM 中的 REPL 工具——都共享同一个 Tool<Input, Output, P> 泛型接口。这意味着从输入验证、权限检查、Hook 到执行和结果处理，整条流水线对所有工具完全相同。新增一个 MCP 服务端不需要修改任何执行逻辑，只需要实现 call() 并提供 inputSchema。这种统一性是 Claude Code 能够在不增加系统复杂度的前提下从 20 个工具扩展到 60+ 个工具的关键。

2. 安全语义编码为类型

isReadOnly、isDestructive、isConcurrencySafe 不只是布尔标记——它们是参与运行时决策的活跃方法。isReadOnly(input) 接收工具输入作为参数，这意味着同一工具对不同输入可以有不同的安全语义。例如，BashTool 对 ls 返回 isReadOnly: true，对 rm 返回 false。这种细粒度的输入感知安全标记让并发调度器和权限系统能做出更精确的决策，而非对整个工具一刀切。

3. 渲染即工具

每个工具自带 React 渲染方法（renderToolUseMessage、renderToolResultMessage 等），而非由统一的渲染器根据工具类型分发。这种"自描述渲染"设计意味着工具最了解自己的输入输出应该如何展示——FileEditTool 渲染带颜色的 diff，BashTool 渲染带退出码的终端输出，GrepTool 渲染带行号的搜索结果。新增工具时只需实现自己的 UI.tsx，不需要修改任何全局渲染逻辑。

4. Feature Gate 的编译时裁剪

通过 Bun 的 feature() 编译时宏和死代码消除，外部构建从物理上不包含内部工具的代码。运行时的 if (isInternal) 检查可以绕过；编译产物中干脆不存在相关代码，即使拿到构建产物也无法还原。

5. Fail-closed 安全默认值

TOOL_DEFAULTS 中 isConcurrencySafe: () => false 和 isReadOnly: () => false 的选择源于失败模式的不对称性。如果一个工具实际上是只读的但被标记为非只读（忘记 opt-in），后果是用户收到不必要的权限弹窗——烦人但安全。反过来，如果一个有写入副作用的工具被错误标记为只读（忘记 opt-out），后果是它可能在没有权限检查的情况下与其他写入工具并发执行，导致数据损坏——危险且隐蔽。这种不对称性决定了默认值必须选择"安全但可能过度限制"的方向。

6. 纵深防御的分层验证

BashTool 的安全不依赖任何单一防线。它有 7+ 层重叠的安全机制：Tree-sitter AST 解析、正则模式匹配、引用内容提取、路径约束验证、sed 白名单验证、沙箱隔离、权限规则系统。每一层都有已知的局限性（正则可以被精心构造的输入绕过、tree-sitter 可能不可用、沙箱可能不被平台支持），但设计哲学是：任何单层都可以失败，攻击者却需要同时绕过所有层才能成功。这使得利用难度呈指数级增长。

7. Prompt Cache 稳定性作为架构约束

多个看似无关的设计决策实际上都被同一个"隐形"约束驱动——prompt cache 命中率：

• assembleToolPool() 的分区排序（防止 MCP 工具变动污染内置工具的缓存键）
• backfillObservableInput() 只修改 UI 层的浅拷贝而非 API 输入（防止修改消息内容导致缓存失效）
• ToolSearch 延迟加载（延迟工具不进入系统提示词前缀，前缀保持稳定，缓存持续命中）

缓存未命中意味着 API 需要重新处理数千个 token 的系统提示词，增加延迟和成本。这个经济学约束深刻地塑造了架构，但不阅读多个组件很难察觉到。