AI 应用后端工程化：从原型到可交付系统 · 第 07 篇 · 第二章 · 知识与工具
当工具从两个增长到几十个时，分类、描述、参数、图标和测试共同决定它们是否仍然可用。
两个工具时，开发者记得每个函数叫什么、需要什么参数。二十个工具时，模型开始选错，前端不知道如何展示，测试也无法确认某个 Provider 是否完整。工具规模增长后，问题不再是“再写一个函数”，而是如何建立可发现、可校验、可维护的能力目录。
工具需要一张完整身份证
工具实现只是身份证的一部分。名称要稳定，描述要帮助模型区分相似能力，参数要机器可校验，分类与图标帮助人类查找，供应商信息说明凭证和生命周期。
flowchart TD
Provider[能力提供方] --> ToolA[工具定义 A]
Provider --> ToolB[工具定义 B]
Category[分类目录] --> ToolA
Category --> ToolB
Schema[参数 Schema] --> ToolA
Runtime[运行时注册表] --> Provider
UI[管理界面] --> Category
Test[契约测试] --> Provider
名称最好表达动作与对象，例如 weather.get_forecast，避免 do_it 或充满实现细节的类名。描述需要说明什么时候使用和什么时候不要使用。两个都叫“搜索”的工具，一个查公开网页，一个查内部知识库，如果描述没有范围，模型只能靠运气选择。
配置与代码各放什么
分类名称、展示顺序、模型可见描述和参数元数据适合配置化；真正的副作用、认证处理和错误转换仍应由代码实现。全写死在代码里，运营调整一个展示名称也要发布；全部交给 YAML，又会把复杂逻辑藏进难以测试的字符串。
name: weather.get_current
category: weather
description: 查询指定城市的当前天气，不用于历史天气统计
parameters:
city:
type: string
required: true
credential_fields:
- api_key
加载配置时应尽早校验。重复工具名、缺失实现、未知参数类型都应让服务启动失败，而不是等用户第一次调用才暴露。启动失败虽然显眼，却比运行中静默漏掉半个 Provider 更安全。
分类不是为了颜色好看
分类可以帮助前端展示，也可以参与权限和上下文控制。例如访客只能看到查询类工具，管理员才能看到写入类工具；当前任务只需要地图能力时，无需把图像生成和邮件工具全部发给模型。
但分类不应代替权限。把工具放进“安全”分类不会让它自动安全，真正授权仍要检查调用者、参数和资源。分类是粗粒度导航，策略才是执行时判断。
Provider Manager 的职责
Provider Manager 连接静态目录与运行时实例。它读取配置，检查凭证，构造工具对象，并提供稳定查询接口。管理器应避免在列表展示时就建立昂贵网络连接；只有实际调用或健康检查时才初始化外部客户端。
凭证也不应混进普通工具元数据返回给前端。目录可以告诉用户“缺少 api_key”，但不能把值回显。多租户系统还要按调用者选择凭证，不能把第一个加载的密钥做成全局单例。
测试目录，而不只测试函数
函数单测能证明输入城市后得到天气，却不能证明 Provider 配置中声明的工具都成功注册。目录需要自己的契约测试：每个工具名唯一、Schema 可解析、实现可调用、分类存在、敏感字段没有被序列化。
还应测试 API 层展示的路径与参数。一次路由重命名可能让后台实现仍然通过单测，管理界面却全部 404。提交历史中紧跟工具管理功能出现的测试调整，正说明契约发生变化时，测试也需要同步表达新世界。
目录失控的症状
最常见症状是同一能力被包装多次：get_weather、query_weather 和 weather_search 实际调用同一接口。模型难以选择，指标被分散，修复要改三处。另一个症状是描述无限增长，把示例、限制和认证说明全塞给模型，工具 Schema 自身就消耗大量上下文。
治理方法包括稳定命名规范、弃用期、描述长度预算和目录审查。变更工具参数属于 API 变更，应考虑旧会话中仍保存着旧 call 的情况。
插件系统也遵循同一规律
IDE 插件、支付渠道和数据连接器都需要目录、Provider、配置与运行时实例。工具系统只是把调用者换成了模型。可以用同一张检查表评审：身份是否唯一，能力是否可发现，配置是否可验证，运行是否可隔离，失败是否可观察。
练习：为“公开网页搜索、内部文档搜索、数据库精确查询”设计三个工具定义。要求模型从描述中能区分使用场景，参数 Schema 不重叠，分别标注权限和结果上限。再写测试遍历目录，检查名称唯一和实现存在。
三条提交证据
3b77c6a：增加内置工具分类与 Provider 管理，能力开始目录化。10e0335：补充处理器、服务和路由，目录进入管理接口。d44a38d：调整测试以匹配新 API，确认目录与外部契约需要共同验证。
这三步从核心目录走到 API，再走到测试。一个可维护工具系统也应沿这三层同时成立，而不是只有运行时函数能被调用。