这里建议大家把重点放在“可控”两个字上。Tool 不是越多越好,也不是给一个万能 Shell 就算完事。真正好用的 Tool Registry,一定是参数可校验、权限可限制、执行可审计。下面这张图把“窄而可靠”的工具设计和“万能 Shell”的高风险做了一个很直观的对比。
![图片[1]-小节二:Tool Registry 怎么设计——Coding Agent 需要的是“窄而可靠”的 Tool,而不是万能 Shell-大赛人网](https://www.dsrw.com/wp-content/uploads/2026/11/image-1797.png)
这一章我们只保留一组非常核心的 Tool:
list_files
search_files
read_file
edit_file
run_pytest
如果需要,还可以增加:
write_file
run_python
但第一版不追求 Tool 多。
为什么 Tool 越多不一定越好?
Tool 太多:
模型更难选
Schema 更复杂
权限更难控制
Trace 更难读
所以一个 Coding Agent 最先应该有:
读
搜
改
测
四类能力。
Registry
最小接口:
class ToolRegistry:
def __init__(self):
self._tools = {}
def register(
self,
name,
func,
):
self._tools[name] = func
def execute(
self,
name,
**kwargs,
):
if name not in self._tools:
raise KeyError(name)
return self._tools[name](
**kwargs
)
真实项目再增加:
schema
description
permission
risk
为什么不直接全用 run_shell?
因为 Shell 能做很多事。
但:
万能能力
=
更大攻击面。
例如读取文件,最好:
read_file
而不是:
cat file
修改文件,最好:
edit_file
而不是:
sed -i
这样每个动作都更容易:
校验
审计
限制
Trace
测试 Tool
Coding Agent 最关键的真实反馈之一就是:
pytest。
所以默认开放的是:
run_pytest
它把可执行范围收窄到:
当前 Python 3.9 解释器
python3 -m pytest
而不是任意命令。确实需要 Shell 时,我们再把它作为单独的高风险 Tool 接入,让命令白名单、超时、工作目录和审批规则都显式可见。这里很容易为了方便先开一个万能入口,最后却很难解释 Agent 到底获得了哪些权限。
Tool Result 要结构化
例如:
{
"ok": false,
"returncode": 1,
"stdout": "...",
"stderr": "...",
"duration_ms": 1250
}
这样 Agent 更容易判断:
失败类型
是否重试
是否需要读文件
这也方便 Trace。
© 版权声明
文章版权归作者所有,未经允许请勿转载。
THE END
















请登录后查看评论内容