很多人以为 Agent 的能力来自模型,其实日常使用中更直接的变量是工具集。同一个模型,给它 read/write/edit/grep/glob 和只给它一个 shell,表现会差出一个量级。
工具就是一个带文案的函数
每个工具在模型眼里长这样:
{
"name": "edit",
"description": "Edit an existing UTF-8 text file by replacing literal text.",
"parameters": {
"file_path": "string",
"old_string": "string",
"new_string": "string",
"replace_all": "boolean"
}
}
关键在 description。模型的「工具选择」不是查表,而是把用户意图和这段文字做语义匹配。所以你写工具描述的时候,实际上是在写提示词:
- 写「读取文件」→ 模型会在该用
grep的地方也用read,然后把整个 5000 行文件拉进上下文。 - 写「按字面量替换文本;old_string 必须在文件中唯一出现,否则报错」→ 模型会先
read确认上下文,再构造足够长的锚点。
我在自己写的插件里踩过这个坑:一个内部工具描述只写了「查询数据」,结果模型拿它当万能入口,参数乱填。补上一句「必须先调用 xxx 拿 id,否则会返回 400」,误用率立刻掉下来。工具描述不是文档,是接口契约的一部分。
为什么 DSH 把 shell 和文件操作分开
直觉上,一个 shell 就够了:cat 读、sed 写、rg 搜。为什么还要单独做 read/write/edit/grep/glob?
三个理由,都是踩出来的:
1. 可观测性。 read 带行号返回,edit 返回 diff 片段。模型看到的和人类看到的是同一份结构化输出,而不是一坨终端文本。
▸ edit(src/config.ts)
- export const TIMEOUT = 3000;
+ export const TIMEOUT = 15000;
2. 可约束性。 文件工具走的是 harness 的沙箱后端,能按策略拦截(只读、限定工作区)。shell 是一张空白支票,拦不住。
3. 少一次幻觉。 sed -i 在 macOS 和 GNU 上参数不同,cat 遇到二进制会吐乱码。文件工具把这些平台差异吃掉,模型不需要记住。
代价是工具数量变多,模型要在更多选项里挑。这引出下一条。
工具粒度:少而稳 > 多而细
我见过一些 MCP server 一口气暴露 60 个工具,每个对应一个 REST 端点。结果是模型经常选错,或者串三个工具才完成一件事。
DSH 这边的做法偏保守:核心工具十几个,覆盖「读、写、改、搜、跑、取网页、派子代理」。剩下的能力用 MCP 按需挂载。
判断粒度有个简单标准:如果两个工具在 80% 的场景下要连着调用,它们应该合并成一个。
比如「列出数据库表」和「看表结构」,分开就是两次往返;合成 get_schema_context(tables) 一次就够。反过来,「执行查询」和「执行写操作」必须分开——因为它们的风险等级和审批策略完全不同。
MCP:把外部世界翻译成工具
MCP(Model Context Protocol)解决的是「我的系统不在模型的知识里」这个问题。挂一个 SSH server,远端主机就变成了工具:
▸ ssh_exec(alias="prod-web-1", command="systemctl status nginx --no-pager")
↳ active (running)
挂一个 DB server,数据库 schema 就变成了可查询的上下文。
用 MCP 有几个实践上的注意点:
凭据留在服务端。 好用的 MCP server 不接受 host/user/password 参数,只接受一个 alias,真实凭据由服务端持有。这样模型(和它的日志)永远看不到密码。
输出要限流。 ssh_exec 的返回如果直接把 dmesg 全量吐出来,上下文瞬间爆掉。所以要有 max_output_bytes、limit、truncated 标记,让模型知道「这不是全部」。
错误要结构化。 返回 exit_code / stdout / stderr 三个字段,比返回一段拼接字符串有用得多——模型能立刻分辨「命令跑成功了但业务失败」和「命令本身没跑起来」。
错误处理决定了 Agent 能不能自己爬起来
一个工具返回什么,几乎决定了 Agent 下一步做什么。我总结了三档:
| 返回形态 | 模型行为 |
|---|---|
| 裸字符串 + 异常栈 | 大概率原样重试,浪费三轮 |
{ok:false, code, message} |
能针对 code 换策略 |
{ok:false, code, message, hint} |
通常一次就修好 |
hint 那一条最值钱。比如文件工具返回:
{
"ok": false,
"code": "NOT_UNIQUE",
"message": "old_string matched 3 locations",
"hint": "Extend old_string with surrounding lines, or set replace_all=true"
}
模型看到 hint 就知道该加长锚点,而不是把同样的调用再发一遍。你多写一行 hint,能省掉它三次无效重试。
小结
工具层是 Agent 的地基,而它的设计原则意外地朴素:
- 描述即契约,写清楚前置条件和失败语义;
- 读写搜跑分开,换取可观测与可约束;
- 粒度按调用频率合并,按风险等级拆分;
- 错误返回带 hint,让重试有方向。
下一篇讲怎么把这些工具编排成可复用的流程——也就是 Skill。

文章评论