模型: openai/gpt-5.4
生成日期: 2026-04-01
书名: Claude Code VS OpenCode：架构、设计与未来
章节: 第19章 — 工具设计的艺术
Token用量: 约 6,600 input + 1,800 output
19.1 ACI原则
如果说过去几十年软件行业不断强调 HCI，也就是 Human-Computer Interface（人机交互），那么在 agent 时代，系统设计者必须同样认真地对待 ACI：Agent-Computer Interface（智能体-计算机接口）。HCI 研究的是人如何理解并操作系统；ACI 研究的是模型如何理解并操作工具环境。二者相似，但绝不是同一个问题。
很多工具对人类工程师看起来非常直观，对 agent 却并不直观。一个函数名含糊一点，人类还能靠经验猜；一个参数名不统一，人类还能看上下文推断；两个能力重叠的工具并列摆着，人类还能试一下再修正。但模型不是这样工作的。它在有限 token 预算内完成规划、选工具、解释输出、推进任务，任何模糊接口都会变成决策噪音。
因此本节的核心主张非常明确：在 ACI 上投入的心力，至少应当与 HCI 一样多。 你会认真设计按钮文案、菜单结构、错误提示、快捷键和确认弹窗，那你也应该认真设计 tool name（工具名）、tool description（工具描述）、参数 schema（结构化参数）、默认行为、返回格式以及误用保护。
这里最实用的一条经验就是：把工具描述写成“给初级工程师看的 docstring（文档字符串）”。 docstring 是很多编程语言中贴在函数、类、模块上的说明文本，用来解释“这个东西做什么、怎么用、注意什么”。为什么说要面向“初级工程师”？因为这样可以同时避免两个极端。
一个极端是写得过短，例如“搜索文件”“执行命令”“读取内容”。这些描述技术上不算错，但对 agent 几乎没有指导意义。另一个极端是写得过抽象、过依赖隐性知识，好像默认使用者已经完全理解系统全貌。这样的描述对模型也并不友好。
好的 ACI 描述应该至少回答四个问题：
- 这个工具解决什么问题？
- 什么时候该用它？
- 什么时候不该用它？
- 有哪些边界、风险或相邻替代工具？
比如下面两种描述就有明显差异。
- “Searches files.”
- “Search file contents using regex. Prefer this when locating text patterns across many files. Do not use for filename discovery; use glob instead.”
前者只是一个标签，后者才像真正的接口说明。它不仅告诉 agent 这个工具“能做什么”，还告诉 agent “什么时候应该选它、什么时候不该选它”。后者多消耗的那一点 token，换来的是后续大量错误选择的减少，非常划算。
因此，ACI 的第一原则是 affordance clarity（可供性清晰）。可供性本来是设计学/HCI 里的概念，指某个对象是否能让使用者自然感知“它该怎么被使用”。在 agent 场景里，这种可供性主要通过文本和结构来表达。模型要从工具定义中推断的不只是 capability（能力），还有意图边界。
第二个原则，是要把 tool boundary（工具边界） 讲清楚。大多数工具误用，不是因为系统没有能力，而是因为系统里有多个相邻能力，但界线模糊。例如 glob、grep、read、lsp_symbols、ast_grep 五者都和“找代码”有关，但它们解决的是不同层次的问题：文件名模式匹配、内容正则搜索、直接读取、语义符号检索、语法树模式匹配。如果边界不清，模型就会花大量 token 做“选哪个工具”的工作。
第三个原则，是引入 poka-yoke（防错设计）。这是制造业与质量工程里的概念，中文常译为“防呆”或“防误操作设计”。它的思想很简单：不要只靠使用者足够小心，而要把系统设计成不容易犯错。在 agent 工具设计里，poka-yoke 极其重要。
典型做法包括：
- 把
workdir作为显式参数，避免 agent 用脆弱的cd && ...方式拼 shell； - 在 bash 工具说明里明确禁止用它做文件读取，因为有专门的 read 工具更安全；
- 对高风险工具写清 side effects（副作用）与前置检查要求；
- 对会产出大量输出的工具做边界限制或分页；
- 在说明里直接点名相邻替代工具，减少误判；
- 用强类型 schema 替代模糊自由文本，降低参数填错概率。
也就是说，一个好工具不仅“能用”，还应该被设计成“最顺手的用法大概率就是正确用法”。这就是 agent 世界里的防错设计。
第四个原则，是 semantic consistency（语义一致性）。人类对命名不一致的容忍度很高；模型则更容易在细小差异中产生额外认知负担。如果一个工具用 filePath，另一个用 path，第三个用 filename，第四个用 target，而它们说的本质上都是文件路径，那么模型每次都要做概念对齐。参数命名、字段命名、返回结构、错误风格，越一致越好。
第五个原则，是 progressive disclosure（渐进式展开）。这不是说工具描述要越短越好，而是说应该把最关键的路径信息放在最上面：主要用途、优先选择场景、强烈禁止场景。少见边缘条件可以放在后面。因为 agent 选工具通常发生在活跃执行循环中，描述必须先让它迅速抓住主干。
OpenCode 给我们的启示，是类型化、可编程的工具定义会天然促进 ACI 的整洁。OMO 的启示，是不仅基础文件工具需要好描述，编排类工具也尤其需要强描述，否则 agent 会在委派、回收、后台运行这些高杠杆动作上频繁失误。Claude Code 的启示，则是成熟产品会把大量 anti-footgun guidance（防踩坑指导）直接写进工具契约里，而不是寄希望于模型“自己懂”。
从实践角度，可以给每个工具设计一份 ACI 检查表：
- 名字是不是动作导向且足够具体？
- 描述是否说明何时该用？
- 是否明确说明何时不该用？
- 参数名是否与系统其余部分一致？
- 是否写清副作用与安全边界？
- 如果和别的工具重叠，边界是否已被明确区分？
- 输出格式是否减轻而不是增加模型后处理负担？
从更大的视角看，ACI 不是工具层面的微优化，而是整个 agent 系统的认知基础设施。差的 ACI 会在每个任务里悄悄收税：选错工具、来回试探、重复纠正、token 浪费、规划不稳。好的 ACI 则会悄悄放大所有能力：更快进入正轨、更稳定地调用工具、更少反复、更高自治可信度。
所以，工具设计绝不是“把函数暴露出来”这么简单。它更像在给模型设计一套工作语言。HCI 决定人是否愿意用你的产品，ACI 则决定 agent 是否真的能稳定用好你的系统。未来构建优秀 coding agent 的团队，必须把 ACI 当成一门正式设计学，而不只是工程附属品。