模型: openai/gpt-5.4
生成日期: 2026-04-01
书名: Claude Code VS OpenCode：架构、设计与未来
章节: 第19章 — 工具设计的艺术
Token用量: 约 6,700 input + 1,850 output
19.3 工具输出的认知成本
讨论 agent 工具设计时，人们往往最先关注“这个工具能不能做某件事”，却常常忽略另一个同样关键的问题：这个工具的输出，会迫使模型额外做多少脑力活？ 对 agent 来说，输出格式不是表面问题，而是直接决定可靠性、延迟、token 成本和稳定性的核心因素。
本节的核心原则可以直接表述为：把工作路由给最便宜且最可靠的执行者。 如果某件事可以由确定性算法完成，就不该交给 LLM；如果数据库或索引系统能做，就不该先把原始材料倒给模型再让它手动整理；如果输出本来就应该是排序后的、分组后的、裁剪后的状态，那就应该由宿主先整理好再交给模型。
最经典的例子就是排序。让 LLM 去给一组数据排序，既贵又不稳定；让程序里的 sort 算法去做，几乎免费而且结果保证正确。这个例子听起来很基础，但它揭示的是更一般的原则：模型不应该替计算机做机械整理。
在真实工具系统里，这种错误经常以更隐蔽的形式出现。比如：
- 搜索工具直接吐出几百条原始匹配，而实际上模型只需要按文件聚合后的前十条；
- 目录读取结果顺序不稳定，模型每次都要重新理解排序关系；
- 诊断工具返回大块非结构化文本，而不是按 severity（严重级别）和位置分组；
- diff 工具把大量上下文噪声一起返回，模型得自己筛；
- 统计信息本来可以提前计算，却交给模型在上下文里再数一遍。
这些都在制造 cognitive cost（认知成本）。这里的认知成本不是心理学严格定义，而是一个工程表达：模型为了把机器输出变成“可决策状态”，还要额外花多少 token 和推理步骤。越多这类机械性加工，模型可用来做真正高价值判断的预算就越少。
因此，工具设计者要不断问自己：输出里哪些是 useful signal（有用信号），哪些只是 mechanical burden（机械负担）？前者服务于判断，后者本应由宿主或算法先处理。
一个高质量工具输出，通常有四个特点。
第一，预结构化。信息一出来就是贴近下一步决策的形状。比如搜索工具支持 content、files_with_matches、count 三种模式，让 agent 直接拿到它当前最需要的抽象层级，而不是永远接收最大量原始数据。
第二，有边界。默认输出不能无限膨胀。可能很大的结果，应该支持 limit、分页、摘要视图和进一步展开路径。否则模型会被海量无关细节淹没。
第三，稳定。顺序尽量确定、字段命名统一、相同状态下重复调用结果风格一致。稳定性会显著降低 agent 的理解摩擦。
第四，面向用途。工具返回的不是底层库最容易吐出来的格式，而是最利于后续行动的格式。带行号的文件内容比纯文本更利于定位；按严重级别分组的诊断比原始 dump 更利于排序处理；已经过滤掉噪声的 diff 比原始混杂输出更利于决策。
这背后其实对应三类不同 executor（执行者）：
- Deterministic executor（确定性执行者）：排序、计数、验证、解析、过滤、结构化变换；
- Retrieval executor（检索执行者）：搜索引擎、索引、数据库、LSP、MCP 服务；
- Model executor（模型执行者）：解释、优先级判断、综合、规划、歧义消解。
很多系统出问题，不是模型不会做高层工作，而是架构让模型去冒充前两类执行者。于是 agent 看起来很“笨”或“浪费”，本质上并不是 intelligence failure（智能不足），而是 labor misallocation（劳动分配错误）。
OpenCode 给出的启示，是工具职责分层清楚会自然推动输出更可控。OMO 的启示，是编排工具不只是“再加一个功能”，而是可以帮助系统把工作转移给更合适的执行者，例如把探索、检索、验证拆给不同上下文和不同工具链。Claude Code 则展示了更成熟产品的一种方向：通过强输出整形，让模型少做机械工作，多做软件工程判断。
这里还有一个非常现实的 token economics（token 经济学）问题。工具明明很好，但如果每次调用都返回冗长文本，模型就要反复读、反复扫、反复整理。这样工具越多，系统反而越贵。于是未来好的工具，不一定是“返回最多信息”的工具，而更可能是“返回最恰当状态”的工具。
这会带来一个重要设计原则：围绕 decision point（决策节点）设计输出，而不是围绕后端实现方便设计输出。
如果模型接下来要决定“先读哪个文件”，那搜索结果就应该帮助它快速锁定候选；
如果模型接下来要决定“先修哪个错误”，那诊断结果就应该突出严重度和位置；
如果模型接下来要判断“这个动作是否安全”，那输出里就应该包含策略相关信号，而不是让模型自行猜测。
换句话说，工具输出不应该只是 data return（数据返回），而应该是 decision-ready state（可直接进入决策的状态）。这是工具设计成熟与否的分水岭。
未来 agent 工具栈大概率会越来越像一个认知流水线：检索层先找准材料，确定性层先做便宜而正确的整理，模型层最后做需要主观判断和综合推理的部分。只要这个分工做对了，系统就会显得更聪明、更快、更稳。因为模型终于不再被迫把 token 花在本该由程序先完成的整理劳动上。
因此，评估一个工具时，不能只问“它能不能拿到信息”，更要问“它的输出逼着模型再做多少本不该做的机械活”。如果答案是很多，那这个工具即便功能强，也仍然是未完成设计。真正优秀的工具，返回的不是原材料，而是下一步行动所需的清晰状态。