CodeSmith工具架构解析：五十工具共用一个槽位

当一个Agent内置五十多个工具，加上MCP外部工具、动态库扩展工具和子代理工具，总数轻松过百。它们如何被统一治理？CodeSmith的答案是：所有工具都插入同一个槽位，让每一个横切关注点只在接口处实现一次。

本文基于CodeSmith v0.5.0（commit 3a74c82f）源码，拆解这个槽位的三层trait设计、统一注册机制、调度流水线以及容错修复阶梯。

三层Trait：槽位的家族谱系

槽位有三层血统，分别住在三个独立的crate中。

最底层是框架层的Tool（crates/agent/src/tools/mod.rs:46-78），一个最小的、与主机无关的契约，其文档注释自称是“LangChain BaseTool的类比”。它只有name、description、input_schema和一个返回boxed future的run方法。它刻意不知道审批和沙箱的存在，注释明确写道这一层的能力只是“给主机的建议性元数据”——框架核心不做把关，把关是主机的事。

中间层是生产层的ToolSpec（crates/agent-runtime/src/tools/spec.rs:809-886），真正干活的那一层，也因此臃肿得多。其最有主见的设计是能力即审批策略。

fn approval_requirement(&self) -> ApprovalRequirement {
    let caps = self.capabilities();
    if caps.contains(&ToolCapability::ExecutesCode) {
        ApprovalRequirement::Required
    } else if caps.contains(&ToolCapability::WritesFiles) {
        ApprovalRequirement::Suggest
    } else {
        ApprovalRequirement::Auto
    }
}

执行代码的一律需要审批，写文件的一律建议审批，其余自动通过。审批等级不是每个工具各自声明的孤立旋钮，而是从能力集推导出来的。新工具只需如实声明自己的能力，闸门会自己就位。如果需要按输入细粒度控制，还有approval_requirement_for_input钩子——同一个执行代码的工具，rm和ls可以区别对待。

接口上还有两个安静但关键的方法：validate_input在审批前集中做语义校验，defer_loading注册工具却不发给模型，把激活留给按需的工具搜索。

最外层是接缝层的ToolDispatcher（crates/agent-runtime/src/tool_dispatch.rs:53-105）：每一轮引擎只持有这个Box<dyn ...>，通过一个“急切的、与输入无关”的元数据快照查询工具，从不依赖TUI的具体注册表。动机写在模块注释里：ToolContext携带约三十个与主机耦合的服务字段（终端、通知、任务管理器等），“不能住在runtime crate里”。

三层合读：框架层定义“可被执行”，生产层定义“如何被治理”，接缝层定义“在看不到细节的前提下被治理”。 每一层只知道它该知道的事。

Boxed Future 是 Rust 异步编程中的一个惯例术语，指将 async 块或 Future 通过 Box::pin 装箱后返回的 Pin<Box<dyn Future<Output = T> + Send>>。因为 async fn 在 trait 方法中的返回类型还未完全稳定，且不同实现返回的具体 Future 类型各不相同、大小未知，直接用 impl Future 作为 trait 方法返回值目前不可行。装箱的代价是一次堆分配和一层动态分发，换来的是 trait 对象化——Tool 能被写成 dyn Tool，允许注册表持有异构工具集合。CodeSmith 选择这一折衷，正是为了让五十多个来源不同的工具都能被同一套接口擦除类型后统一调度，与 Arc<dyn ToolSpec> 的存储方式一脉相承。

统一注册：五湖四海归一个Vec

每个工具最终都成为同一个注册表里的Arc<dyn ToolSpec>：内置工具直接实现它，MCP工具经适配器包装，扩展工具通过ExtensionToolSpecAdapter桥接。子代理的工具面由与父代理相同的builder构建——注释称之为“保持同步”——这正是子代理可以递归生成子代理的原因。

MCP能力判定从保守处出发：只有名字里带list_mcp/read_mcp的发现类助手才算只读，其余一律视为“需要审批、需要网络”。

“除非是已知的发现类助手，否则保守地将MCP工具视为需要审批和网络访问。” — crates/tui/src/tools/registry.rs:867-925模块注释

注册表入口有一道fail-closed关卡（crates/agent-runtime/src/tools/registry.rs:484-642）：工具名必须匹配^[a-zA-Z0-9_-]{1,64}$，schema根必须是对象。不合规的工具既不会panic也不会返回400——它被替换成一个FailClosedTool，描述写着“不可用：此工具初始化失败且处于fail-closed状态。不要调用它。”对它的任何调用永远返回不可用。注释点明了原因：如果一个坏插件的定义在轮次中途爆炸，它“要么在轮次中途panic，要么触发一个会让每一个工具失效的400”——一个坏工具的罪过不能连坐所有工具。

五十件武器听起来威风，但“多”本身就是一种病：超过一百个工具后，最先进的模型做选择题也开始出错；把它们全部平铺进上下文既吃token，又让工具集的每次变动都刺穿KV Cache。

业界答案分三层，一层比一层“按需”。第一层是索引化：Cursor将MCP工具描述同步到文件夹，模型默认只看到名字索引——A/B测试显示MCP相关任务的总token消耗下降46.9%；Anthropic基于检索的预过滤在注入前按语义相似度筛选候选，在一百多个工具的场景下把工具使用准确率从49%提升到74%。

第二层是API原生化：OpenAI的tool_search、CodeSmith的defer_loading、Codex CLI默认开启的BM25检索——静态前缀只保留工具名和一行简介，完整schema在模型按需请求后追加到上下文末尾，此后固定在轨迹中的原始位置持续命中缓存。

第三层是主动发现：MCP-Zero完全不预置schema，Agent在思考时声明“我需要什么能力”，系统按语义两跳路由（先服务器后工具），从数千候选中匹配注入，报告token节省约98%。

CodeSmith介于第一层和第二层之间：defer_loading注册工具却不发给模型，激活走两遍法——常驻工具在前，中途激活的工具追加到目录尾部，保持已缓存的字节前缀不断裂。

MCP（Model Context Protocol） 是 Anthropic 于 2024 年底开源的一套开放协议，用于让模型通过标准客户端–服务器接口访问外部工具与数据源。一个 MCP 服务器可以暴露一组工具定义（名称、描述、JSON Schema）以及资源、提示模板等能力；客户端（这里是 CodeSmith 这类 Agent 主机）连接后把远端工具适配成本地统一接口。它的价值在于解耦：工具作者不必为每个 Agent 各写一份集成，主机也不必硬编码每项能力。代价是治理界面变宽——远端服务器的 schema 质量参差不齐、能力声明未必可信，这正是 CodeSmith 对 MCP 采取保守审批策略、并在 schema 清洗环节为脏 schema 兜底的根本原因。

调度流水线：从流式到回填

从模型发出结构化tool_use到结果落回上下文，完整流水线如下：

SSE流
├─ ToolUse块开始：记录id/name，arguments为空
├─ InputJsonDelta：逐片组装input_buf
│    （注释：参数JSON从不展示给用户，只缓冲组装）
│    只读工具可在此刻投机启动
├─ 块结束：finalize_tool_input解析参数
▼
规划（串行）
├─ 截断闸门：轮次被输出上限切断时，参数解析失败的调用直接拒绝并告知重发
├─ loop_guard：同名+同参数，第3次直接阻断
├─ 审批决策：按能力或按输入
▼
批处理
├─ 连续的可并行只读工具聚成并发批
├─ 其余各自成串行批
▼
执行
├─ 并发批：FuturesUnordered，按序启动，逆序完成（LIFO配对）
├─ 串行批：审批闸门（Event::ApprovalRequired → 阻塞等待用户）
├─ RwLock：可并行取读锁，串行工具取写锁；工具调工具的重入跳过锁防死锁
▼
后处理（串行，按索引）
├─ loop_guard记录成功/失败（连续3次失败警告/8次暂停）
├─ LSP诊断收集、read_file结果观察
└─ 回填：网络来源结果先包裹在<external_content>定界符中，再推入ToolResult块

流水线上有两个细节值得停留。第一是投机提早启动：参数还在流式传入时，已被判定为只读的工具就提前出发——模型说完话时，文件已经读完。赌注是“参数的后半段不会推翻只读判定”，对read_file这类工具这是稳赢的赌。

但网络工具最近被请出了这个赌场：网络策略默认改为Prompt后，网络工具的逐输入审批等级可能是Required，而投机调度发生在审批决策之前——静态近似看不到因主机而变的策略，于是fail-closed。注释把账算得很清楚：策略允许的主机什么也没失去——调用只是从“投机提早”退回“执行时正常发起”。审批语义一变，可提早启动的名单就必须重新计算。

第二是审批指纹——一紧一松：拒绝用精确指纹——拒绝rm -rf /tmp/x不该顺带压制另一个不同的调用；批准用更宽松的arity感知指纹——你批准过cargo build后，cargo build --release在会话内不再打断你。对绕过严格，对省事宽松，两把尺子指向相反方向，各管各的场景。

并发批纪律背后是一条教科书原则：每个工具都应声明是否支持并发执行，默认为否（fail-safe）；失败只在同一批并行调用内传播，绝不上溯到父操作。 翻译成具体场景：一次读三个文件，其中一个不存在，只有它报错，另外两个照常返回——整个任务当然不能因此中止。

CodeSmith在两个地方落地这条原则。并发资格靠声明：tool_plan_is_parallel_safe要求read_only && supports_parallel，加上无需审批和非交互。失败边界靠结构：并发批按预分配槽位回收结果，batches.rs注释称之为“保索引的drain——完成顺序无关紧要”——单个future的失败只污染自己的槽位。

SSE（Server-Sent Events） 是建立在 HTTP 上的单向流式协议，服务端以 text/event-stream 持续推送若干 event:/data: 分帧。主流大模型 API 的流式输出都基于它：文本增量、tool_use 块开始、input_json_delta 参数分片、块结束各有独立事件。理解流水线的关键就在这——模型的工具调用参数不是一次性到达，而是被切成若干分片沿 SSE 推送，客户端必须逐片拼装成完整 JSON 后才能解析。协议本身不保证分片落在 JSON 语法的自然边界上，字符串可能被从中间切开，这也是参数修复阶梯中"分块边界切穿 JSON 字符串"这一常见死法的直接来源。

容错：把模型的抖手当作常量

模型越界时，剥离机制处理；模型在协议内但打晃时，修复阶梯接管。

参数修复：DeepSeek^广告将tool_calls.function.arguments作为流式增量发送，模块注释记录两种常见死法——SSE分块边界切穿JSON字符串中间，重组后留下尾逗号或未闭合括号；以及某些本地后端在字符串值内发出字面控制字符。修复阶梯有五级：严格解析→剥离字符串中的控制字符→移除}/]前的尾逗号→闭合未闭合括号→剥离多余闭合符。上限1 MiB，超过则拒绝修复。兜底永远成功：所有阶梯失败时返回空对象{}——派发总能继续，代价只是工具侧报一个缺字段。但兜底是有情境的：轮次被输出上限截断时，阶梯被强制关闭——半句话绝不能被修复成可执行命令。

名称修复：模型把工具名拼错时，解析阶梯接管：精确小写→连字符转下划线→CamelCase转snake_case→剥离_tool后缀→模糊前缀匹配。仍然无命中？连报错也不空手而归：编辑距离≤3的候选会以“Did you mean: ...”列出。调用了从未注册的延迟加载工具？水合结果不仅报错，还附上正确的字段名映射（old_string → search，new_string → replace）加"retry_required": true。错误消息本身就是教科书——纠正下一次调用所需的一切就在那一条消息里。

Schema清洗：发往模型前做保语义变换——anyOf:[X,{type:"null"}]折叠为可空X，裸对象补上空properties，悬空的required条目剪除——专为各种MCP服务器吐出的脏schema被API严格模式拒绝而设。

敌意作为美德

解析容忍有一条绝不能越过的线：你可以修复抖手，但不可接纳伪造。 crates/agent-runtime/tests/protocol_recovery.rs:1-23的模块注释值得全文阅读：

//! 这些测试的存在是为了让引擎对伪造的工具调用包装器
//! （助手文本中的XML/Replit/markdown伪调用）保持敌意。
//! ...
//! 2. 旧式基于文本的`tool_parser`不把较新的
//!    `<function_calls>`包装器当作真实工具调用——只有旧式的
//!    `[TOOL_CALL]`和`<invoke>`形状曾经产生结构化调用，
//!    不应有任何东西悄悄重新启用基于文本的执行。
//!
//! 要点是模型输出中的协议漂移应该是可见的（我们仍然剥离它
//! 并发出状态通知），而不是被悄悄转化为工具执行。

旧文本解析器tool_parser.rs仍在仓库中，模块头自我介绍：“引擎不再调用此解析器”——退役但留在账上。它活着的遗产是那条铁律的边界：歪参数可以修复，因为那是协议内的损坏；格式完全不对的“调用”必须剥离，因为那是协议外的伪造——修复后者等于为攻击者开通道。

结果的经济学

工具结果回填直接连接上下文账本。Shell输出上限30,000字节，但切分不是一刀切：头部保留22K，尾部保留8K——尾部预算留给错误消息和测试摘要，正是最常在结尾出现的高价值内容。

被截断的中段不是永远丢弃，而是进入磁盘信封：截断触发瞬间，完整输出原子写入~/.codesmith/tool_outputs/，头尾照旧留在上下文。截断标记上附加检索指针（Full output saved; call retrieve_tool_result ref=<id> to view it.），模型照抄即可取回中段。三个截断点全部接通；文件保留7天，启动时清理。

溢出本身有四道护栏。其一，Running状态的轮询不溢出：否则每次轮询都全量重写累积输出——O(轮询次数×字节数)的磁盘折腾——只有观察到最终状态的轮询才写最终视图。其二，任务被驱逐（stale）后不溢出：stale详情只保留保存的尾部，用覆盖之前溢出的完整输出是降级，不如不给检索指针。其三，合成溢出id纳入pid：tool_outputs目录跨进程共享，毫秒+序号会在同一毫秒启动的两个进程间碰撞。其四，写失败从静默降级改为记录warn!：检索指针承诺“完整输出在磁盘上”，静默失败会悄悄打破承诺。

至于通用工具结果的100 KB溢出阈值，流水线一直存在但长期没有生产调用者——是shell的30KB预算先接了线。工具目录的序列化结果缓存在OnceLock中并按名称排序（又是前缀缓存）；超大输出走摘要路线，超大结果变成var_handle token。

KV Cache 是大模型推理时的键值缓存：Transformer 每层对已生成 token 的注意力和值向量算过一次后可以复用于后续 token，避免重复计算，使多轮对话的成本从二次方降到线性。前缀缓存（prefix caching）是它的进一步优化——若新请求的 token 前缀与已缓存序列逐字节相同，这段前缀可直接命中缓存。因此任何插入、删除或改写轨迹中较早位置的内容都会让缓存从改动点失效，后续 token 全部重算。这正是工具目录必须按名称排序、延迟加载的工具只能追加到目录尾部、截断输出时保留头尾的原因：稳定字节前缀本身就是被显式保护的资产。

结语：挂在槽位上的一切

回顾这个槽位的价值：审批从能力推导（继快照之后的又一颗后悔药），并发通过读写锁声明，目录通过排序赚取缓存命中，坏工具fail-closed不连坐，抖手配五级扶手，伪造遭遇敌意剥离，结果回填自带经济学——每一个横切关注点都挂在一个接口的钩子上，工具实现者只写业务逻辑。 这就是“五十武器，一槽位”的全部含义：抽象不是少写代码——而是让每一项治理动作只写一次。

但槽位只保证工具“如何被治理”。每件武器自带的使用手册——为什么read_file劝你别用cat，为什么edit_file在多重匹配时报错，为什么fetch_url把169.254.169.254视为致命威胁——是另一门手艺。