Tool系统：声明式registry与安全边界

如果说LLM是agent的”大脑”，那么tool就是agent的”双手”。大脑负责思考”该做什么”，双手负责”把它做成”。没有tool，agent只是一个能说会道的chatbot——它知道答案，但无法触碰世界。但tool也是一把双刃剑：一个能执行bash命令的tool，意味着模型手里有了一把可以操作你整个操作系统的钥匙。如何让agent既能”动手”又不”乱来”，是tool系统设计的核心命题。

这篇文章会从tool系统的基本概念讲起，对比几种主流的工具管理方案，然后深入看aptbot如何在”能力”和”安全”之间找到平衡。

一、概念：tool是什么，为什么需要工具系统

1.1从”说话”到”做事”

先做一个思想实验。假设你有一个AI助手，你对它说：”帮我查一下服务器上还有多少磁盘空间。”

如果它只是一个chatbot，它会告诉你：”你可以用 df -h 命令查看。”然后你自己去命令行执行。

如果它是一个带tool的agent，它会直接调用bash工具执行 df -h，把结果读回来，然后告诉你当前磁盘使用情况。

这就是tool的意义——它把LLM从”建议者”变成了”执行者”。模型不再只是告诉你该做什么，而是真正帮你做了。

1.2 tool在ReAct循环中的位置

在ReAct循环中，tool是”行动”环节的具体载体：

1. 推理（Reasoning）：模型判断”我需要知道磁盘空间”
2. 行动（Acting）：模型调用bash工具执行 df -h
3. 观察（Observation）：工具返回执行结果
4. 回到步骤1：模型基于结果做下一步决策

每一步的”行动”都由一个tool完成。所以tool系统本质上是一个从LLM的意图到实际操作的桥梁。LLM说”我要读文件”，文件就被读回来了；LLM说”我要改代码”，代码就被改了。

1.3工具系统的三个核心职责

任何一个agent的工具系统，都需要回答三个问题：

1. 模型怎么知道有哪些工具可用？——工具需要被”告知”模型。通常通过function calling协议，把工具的名字、描述、参数结构注入到LLM的请求中。
2. 模型怎么调用工具？——LLM返回一个结构化的调用请求（工具名 + 参数），系统需要正确地把这个请求路由到对应的实现函数并执行。
3. 调用的边界在哪？——不是所有操作都应该允许。工具系统必须有安全边界，防止模型有意或无意地执行危险操作。

这三个问题看似简单，但不同的项目给出了截然不同的答案。它们的差异恰恰反映了不同的设计哲学。

二、通用设计方案

2.1工具的定义与注册

无论是哪种实现，工具系统都有两个基本抽象：工具定义和工具注册中心。

工具定义描述”一个工具长什么样”，通常包含：

• 名称：模型用来引用这个工具的唯一标识
• 描述：自然语言说明，告诉模型”这个工具什么时候用”
• 参数结构：期望的参数列表及各自的类型、约束
• 执行函数：实际执行逻辑

工具注册中心是一个容器，持有所有可用工具的集合。它的核心职责是：

• 管理工具的增删改
• 在需要时把所有工具的定义格式化成LLM能理解的格式（如function calling schema）
• 在模型请求调用时，根据名称找到对应的工具并执行

下图展示了tool系统从注册到执行再到安全防护的完整架构：

2.2工具与LLM的交互流程

一个典型的tool调用周期如下：

1. 系统把所有工具的name + description + parameter schema组装成function calling定义，随user message一起发给LLM
2. LLM推理后决定”我需要调用某个工具”，返回一个结构化的调用请求
3. 系统解析请求，从注册中心找到对应的工具
4. 校验参数是否合法
5. 执行工具函数
6. 把执行结果作为tool result返回给LLM
7. LLM基于结果继续推理

这个流程看起来直接，但每一步都有工程化的权衡——参数要校验多严格？超时怎么处理？结果太大怎么办？这些细节决定了工具系统的可靠性与安全性。

2.3工具能力边界的设定策略

在设计工具集时，有一个根本性的决策：应该提供少而大的”万能工具”，还是多而小的”专用工具”？

• 万能工具策略：提供一个能执行任意代码的工具（如 code_run），模型可以用它完成几乎所有事。优点是工具列表极短，缺点是安全边界难以收窄。
• 专用工具策略：把能力拆成多个小工具（读文件、写文件、执行命令、搜索等），每个工具的能力范围明确受限。优点是安全边界清晰，缺点是工具列表较长，模型需要学习更多工具。

这不是技术能力的差异，而是设计哲学的差异——信任模型多一点，还是约束模型多一点。

三、市面其他工具管理方案对比

现有agent项目在工具管理上大致可以分为三种设计路线。理解它们各自的取舍，能帮我们看清aptbot为什么选择了当前这条路。

3.1方案A：多工具宽松策略

这套路线的出发点是”给模型尽可能多的工具选择”。工具数量可能多达30-50个，每个工具能力范围定义得比较宽松，安全约束主要依赖模型自身判断。

设计特点：

• 工具种类丰富：涵盖文件操作、代码分析、网络请求、数据库查询等各类场景。模型几乎能找到”专用于当前任务”的工具。
• 安全依赖system prompt：不在工具层做硬性安全校验，而是通过在system prompt里写”不要删除重要文件””不要执行危险命令”来约束模型行为。
• 参数校验宽松：参数类型检查是基本的，但不会在schema层加复杂约束（比如路径白名单、命令黑名单）。

优势：

• 模型生态丰富，上手就能处理各种任务
• 对开发者实现简单——工具定义少，安全逻辑少

劣势：

• 安全风险集中：宽松工具 + 松校验意味着一旦模型出现幻觉或被prompt injection攻击，能造成的破坏范围大
• 依赖模型自身的判断力：当模型在边界情况下（比如被用户要求”忽略安全规则”），不会在工具层被拦截
• 工具数量多导致function calling的token开销大

3.2方案B：万能工具策略

这套路线走向另一个极端——只提供一个或少量的”万能”工具（如 code_run），让模型用代码来完成所有操作。这在一些Python生态的agent项目中比较常见。

设计特点：

• 单一入口：所有操作都通过一个工具执行。读文件用代码、写文件用代码、调API用代码——模型用Python脚本表达一切意图。
• 工具列表极短：可能只有2-3个工具，function calling的token开销极低。
• 安全压力后移：安全边界不在工具层处理，而是在Python执行沙箱中实现（如果有的话）。

优势：

• 设计极简——工具注册和路由逻辑只有几十行代码
• 对模型能力释放最充分：模型可以写任意复杂的逻辑，不受工具能力边界限制
• function calling的token开销最小

劣势：

• 安全边界难以收窄：一次 code_run 就是一次完整代码执行。要控制它不读 /etc/passwd、不写 ~/.ssh、不执行sudo，需要额外实现Python沙箱，复杂度不亚于多工具方案。
• 调试成本高：模型写的代码出bug时，agent自己要读traceback、修改代码、重试，每次失败的token成本可能远超多工具方案。
• 不适合”精确编辑”类任务：改文件中的某一行，在专用工具方案中是一个原子操作（edit工具）；在万能工具方案中需要模型写一段读写-解析-替换-保存的Python脚本，出错概率更高。

3.3方案C：声明式注册 + 多层安全

这套路线在工具定义阶段就引入严格的结构化约束，并将安全防线分散在多个层次，而不是集中在一处。

设计特点：

• 声明式注册：每个工具是一个独立的声明式对象，包含name、description、inputSchema、execute四个字段。工具注册是显式的——不存在”隐式可用”的工具。
• schema层安全：参数的校验不仅做类型检查，还包含业务约束（路径必须是相对路径、命令长度上限、禁止包含特定字符）。
• 执行层安全：超时控制、资源限制（大文件拒绝）、路径遍历防护等。
• 行为层安全：system prompt明确告知边界，作为第一道行为引导。

优势：

• 安全防线多层且明确——每一层都拦截不同的威胁面
• 工具列表可枚举、可审计——看一眼registry就知道agent能做什么
• 每个工具独立测试，不依赖完整agent环境

劣势：

• 需要更多的框架代码——每加一个工具都要写schema + execute + 安全校验
• 工具数量增多时，function calling的token成本线性增长
• 对开发者的约束感更强——不能”随手加一个工具”而不思考安全边界

3.4三种方案对比

维度	方案A（多工具宽松）	方案B（万能工具）	方案C（声明式 + 多层安全）
工具数量	30-50个	1-3个	4-10个
安全边界	依赖system prompt	依赖沙箱（如有）	多层防线（schema/执行/行为）
参数校验	基础类型检查	无（或极基础）	类型 + 业务约束
function calling token	高	极低	中
调试方便性	中	低（模型自调试）	高（每个工具独立测试）
实现复杂度	低	中（沙箱复杂）	中高
适合场景	快速原型	数据科学 / 批量处理	产品级agent

四、aptbot的设计特点

4.1少而精的工具集

aptbot 0.2.x内置4个工具，覆盖”执行/读/写/记忆”四类基本操作：

• bash：执行shell命令。最强大也最危险，是agent “动手”的主要途径。命令执行受30秒超时控制。
• read：读文件。比bash更受限——只读不写，且有大文件OOM防护（超过阈值拒绝读取）。
• edit：改文件。基于”找旧字符串、替换新字符串”的精确编辑模式，避免整文件覆盖的风险。
• update_working_memory：让agent主动更新自己的工作记忆。这是agent “记住”事情的工具。

这4个工具看起来朴素，但90% 的agent日常任务（代码维护、文档修改、项目探索）都能用它们完成。这是有意为之的选择——工具少意味着模型选择工具时决策负担小，每个工具的description可以写得详细，模型更容易理解何时用哪个。

对比方案B的”一个工具包揽一切”，aptbot的选择是”每个工具只做一件事，但做得清晰”。对比方案A的”30-50个工具”，aptbot选择克制——只在添加明确需要的新工具时扩展工具集。

4.2声明式注册，使能力可枚举

每个工具都实现 AgentTool 接口，通过 ToolRegistry 声明式注册：

AgentTool 接口：
• name: string          → 工具名
• description: string   → 给模型看的说明
• inputSchema: TypeBox  → 参数结构的 schema
• execute(args, ctx)    → 实际执行函数

工具不直接在agent循环中被调用，而是先注册到registry。每一轮循环时，agent loop从registry取出所有工具定义，自动组装成function calling列表发给LLM。LLM返回调用请求后，loop再从registry中查找对应工具执行。

这样做有三个好处：

1. 可枚举：看一眼registry的注册列表，就知道agent拥有哪些能力。做安全审计时不需要追着代码到处找”哪里注册了工具”。
2. 可替换：要替换一个工具的实现（比如把bash工具的底层从 exec 换成 spawn），只需要改注册时的execute函数，不动agent循环的代码。
3. 可测试：每个工具可以独立测试。你不需要启动整个agent来测试read工具在文件不存在时的行为。

4.3 TypeBox schema校验：在参数进入执行前守住第一道门

每个工具的inputSchema使用TypeBox定义。LLM返回的参数必须通过schema校验才能进入execute函数。

校验解决两类问题：

1. 模型输出不稳定：LLM偶尔会返回结构错乱的JSON——缺字段、类型错、多余字段。TypeBox的strict模式会把这些问题挡在execute之外，避免工具内部因为参数不符合预期而崩溃。

2. 安全约束前置：schema本身就可以编码安全规则。比如路径参数约束为相对路径（禁止绝对路径）、命令长度设上限、不允许包含管道符或重定向符。这些约束在参数到达execute之前就被拦截。

校验失败的反馈不会静默丢弃，而是以结构化的错误信息返回给LLM，让它在下一轮修正参数。这形成了一个有趣的闭环：模型尝试 → 校验拦截 → 错误反馈 → 模型修正。模型在交互中学会了”哪些参数是合法的”。

4.4多层安全防线

aptbot的安全设计不是一个单点，而是一个多层防护体系：

第一层：systemPrompt行为引导

在system prompt中明确写入了安全约束——“不要修改 .env文件””不要执行sudo””不要写入 ~/.ssh目录””不要git push –force”等。

这一层不是技术防线（模型可以违反），而是行为引导。它解决的是”模型不知道某些操作危险”的问题——大多数违规不是因为模型恶意，而是因为它没被告知这是禁区。明确告知边界后，大多数模型会遵守。

第二层：TypeBox schema参数约束

每个工具的inputSchema中编码了参数级别的限制。比如确保路径是相对路径、命令长度不超过阈值等。这层拦截的是”参数不合法”的调用。

第三层：30秒硬超时

bash工具执行的任何命令不能超过30秒。超时后先SIGTERM给进程优雅退出机会，再过几秒未退出则SIGKILL强制终止。这防止agent卡死在等待命令完成上——比如 npm install 因网络问题挂起、错误的 sleep 1000 测试、意外触发的死循环脚本。

30秒是经验值。大多数有意义的命令（git操作、文件处理、测试运行）在30秒内完成。太短（5秒）会误杀合理操作，太长（5分钟）会让agent卡死。这是”保护agent不被卡死”与”允许合理长任务”之间的折中。

第四层：大文件OOM防护

read工具在读文件前检查文件大小，超过阈值（如10MB）拒绝读取。这防止agent因为”好奇地”读了一个巨大的日志文件或二进制文件，导致Node.js进程内存溢出崩溃。没有这道防线，agent很容易把自己读死。

第五层：路径遍历防护（path-guard）

bash和edit工具都涉及文件路径。模型可能（有意或无意）尝试路径遍历攻击：../../etc/passwd、/etc/shadow、~/.ssh/id_rsa。

path-guard把所有路径规范化为workspace内的绝对路径：

1. 解析所有 .. 和符号链接，得到真实的绝对路径
2. 检查该路径是否在workspace根目录之内
3. 不在则拒绝

这实际上是最小化的”沙箱”——不引入OS级沙箱（chroot、容器、Docker），只用路径校验，但对该项目定位已经足够。

五层防线的关系是：systemPrompt引导行为，schema约束参数，超时和OOM保护资源，path-guard锁定路径。任何一层被突破，还有下一层兜底。这比方案A的”全靠system prompt”要安全得多，也比方案B的”全靠沙箱”要简单得多。

五、发展方向

工具系统在aptbot的未来演进中，有几个值得关注的方向：

5.1更丰富的工具生态

当前4个工具覆盖了基本操作，但还有很多场景需要新工具：搜索（grep/find的封装）、网络请求（HTTP GET/POST）、Git操作的高级封装（不只是通过bash执行git命令）。后续版本会根据实际需求逐步扩展工具集，但会保持”少而精”的原则——每个新工具必须经过充分的必要性论证。

5.2工具链的组合能力

当前每个工具独立运行，工具之间不感知彼此。未来可以考虑”工具链”的概念——把多个工具步骤组合成一条流水线，agent可以一次调度多个工具（比如”读A文件、读B文件、对比差异、写入C文件”），减少往返LLM的轮次。

5.3更细粒度的权限控制

当前的安全防线是”全局一刀切”——所有session共享相同的工具权限。未来可以引入per-user或per-session的权限策略，比如”在项目A中禁止bash工具””在只读模式下所有写操作需要用户确认”。这能让aptbot更安全地在多项目、多用户场景下使用。

5.4工具执行的可观测性

当前工具的执行结果是直接返回给LLM的，用户只通过日志看到执行过程。未来可以加入更丰富的可观测性——实时展示工具执行进度、资源消耗、执行轨迹，让用户能像看CI/CD pipeline一样追踪agent的操作。

小结

Tool系统是agent的”双手”，也是它与外部世界交互的最危险接口。这篇文章从三个维度拆解了工具系统的设计：

1. 概念层面：tool让agent从”说话”变成”做事”，是ReAct循环中”行动”环节的具体实现载体。工具系统需要回答”模型怎么知道有哪些工具””怎么调用””边界在哪”三个核心问题。

2. 方案对比：方案A（多工具宽松）追求丰富的工具生态但安全依赖模型自觉；方案B（万能工具）追求极简的接口但安全压力后移到沙箱层；方案C（声明式注册 + 多层安全）用结构化定义和分层防护换取可控性。

3. aptbot的选择：4个工具覆盖”执行/读/写/记忆”基本操作，ToolRegistry声明式注册使能力可枚举，TypeBox schema守住参数入口，五层安全防线（systemPrompt → schema → 超时 → OOM → path-guard）在多个层面拦截风险。

下一篇文章，我们看Memory系统：agent如何在多轮对话和跨会话之间”记住”该记住的信息。