企业官网建设流程全解析

1. 为什么AI需要一个专属工具箱文件

第一次看到TOOLS.md这个文件名的时候，我脑子里冒出的第一个念头是：又多了一个要维护的文档。毕竟手头已经有README.md讲项目概况，有SKILL.md记录能力清单，还有SOUL.md承载人格设定，再塞一个TOOLS.md进去，怎么看都像是给自己找活干。但真正把一套 AI Agent 跑起来、并且让它稳定干活之后，我才意识到这个文件不是可选项，而是整个体系里最容易被低估的那块拼图。

先说清楚它是什么。TOOLS.md本质上是一份面向 AI 的工具能力声明文件，它用结构化的方式告诉模型：你现在手上有哪些工具可以用、每个工具叫什么名字、接受什么参数、返回什么结果、什么场景下该调用它、什么情况下绝对不能碰。你可以把它理解成给 AI 写的一份"设备操作手册"，只不过这份手册不是给人看的，是给模型在推理过程中实时查阅的。

它解决的问题非常具体。在没有TOOLS.md的时候，我遇到过太多这样的情况：模型明明有能力调用某个接口，却因为不知道这个接口存在而选择用自然语言瞎编；或者知道有工具，但参数传错、格式不对，调用直接失败；再或者更糟，模型在不该调用工具的时候乱调，把只读操作变成了写操作。这些问题的根源都不是模型不够聪明，而是工具边界没有被清晰定义。

适合读这份内容的人，我大致分三类。第一类是正在做 AI Agent 应用开发的工程师，尤其是用 OpenClaw 这类框架做本地部署或者集成到聊天平台的；第二类是产品经理或者技术负责人，需要理解为什么一个 AI 项目里要维护这么多 Markdown 文件，各自分工是什么；第三类是自己折腾本地大模型、想让模型真正"动手干活"而不是只聊天的爱好者。不管你是哪一类，只要你的 AI 需要调用外部能力，TOOLS.md就绕不开。

我后面会把这套东西拆开讲：它和SKILL.md、SOUL.md到底怎么分工，文件内部该怎么写，参数怎么设计，实际部署时会踩哪些坑，以及怎么排查那些"工具明明注册了却调不动"的玄学问题。这些都是我在实际项目里一行一行试出来的，不是从文档里抄的。

2. 四个核心文件的职责边界与协作逻辑

2.1 TOOLS.md、SKILL.md、SOUL.md 到底谁管什么

很多人第一次接触这套文件体系时会懵，因为名字看起来都差不多，都是大写加.md，感觉像是同一类东西拆成了好几份。实际上它们的分工非常明确，我用一个生活化的类比来说明：把 AI 想象成一个刚入职的员工。

SOUL.md是这个员工的性格和价值观。它决定了这个员工说话是什么调性、遇到模糊指令时倾向于保守还是激进、面对用户情绪时怎么回应。这是最底层的东西，改一次影响全局。

SKILL.md是这个员工的技能清单。它记录的是"我会做什么"，比如会写代码、会做数据分析、会翻译、会总结长文。这是能力层面的描述，偏向于"知识"和"方法论"。

TOOLS.md是这个员工的工具箱和操作规范。它记录的是"我手边有哪些具体设备、每个设备怎么开、什么情况下该用哪个"。技能是抽象的，工具是具体的。会写代码是技能，但具体调用哪个编译命令、传什么参数、输出到哪里，这是工具层面的事。

我见过不少人把这三者混在一起写，结果就是文件越来越臃肿，模型读起来抓不住重点。分开写之后，最大的好处是修改隔离。你想调整 AI 的性格，只动SOUL.md；想加一个新能力，动SKILL.md；想接入一个新接口，动TOOLS.md。互不干扰，回归测试的范围也小。

2.2 为什么工具声明必须独立成文件

有人会问，既然SKILL.md已经在描述能力了，为什么不把工具信息直接塞进去？我的实践经验是：技能是稳定的，工具是易变的。

一个 AI 的"会总结"这个技能，可能半年都不会变。但它背后调用的总结工具，可能这周用的是本地模型，下周换成了云端接口，参数格式完全不一样。如果两者混在一个文件里，每次换工具都要动技能描述，很容易改出问题。

更关键的是上下文窗口的消耗。模型每次推理能读的内容是有限的。SKILL.md通常比较长，因为技能描述需要展开讲。而TOOLS.md需要的是高密度、结构化、可快速检索。把工具信息独立出来，可以针对性地做精简和格式化，让模型在需要调用工具时能快速定位，而不是在一大段技能描述里翻找。

还有一个很实际的原因：权限和审计。工具调用往往涉及实际操作，比如发消息、写文件、访问网络。把这些单独放在一个文件里，方便做权限控制和安全审查。你可以在TOOLS.md里明确标注哪些工具是只读的、哪些是写入的、哪些需要二次确认。这种信息混在技能描述里根本没法管。

2.3 文件之间的引用关系怎么设计

实际项目里，这三个文件不是孤立的，它们之间有引用关系。我的做法是在SKILL.md里描述技能时，如果某个技能依赖具体工具，就明确指向TOOLS.md里的对应条目。比如写"具备发送消息的能力，具体工具定义见 TOOLS.md 中的 message_send 条目"。

这样做的好处是单一事实来源。工具的具体参数只在TOOLS.md里定义一次，其他地方只引用不重复。避免了改了一处忘了另一处导致的不一致。

SOUL.md一般不直接引用工具，但它会影响工具的使用策略。比如SOUL.md里如果设定"这个 AI 倾向于谨慎，涉及写操作前要确认"，那么TOOLS.md里对应的写工具就应该标注需要确认。这是一种隐式的协作。

我整理了一个简单的对照表，方便快速理解三者的差异：

这张表我在团队内部培训新人时一直在用，基本上看一眼就能明白各自定位。

3. TOOLS.md 内部结构该怎么设计

3.1 单个工具条目的标准字段

写TOOLS.md最核心的工作就是定义每一个工具条目。我试过很多种写法，最后稳定下来的字段结构是这样的：名称、描述、参数、返回值、调用时机、限制条件、示例。这七个字段缺一不可，少一个都会在实际运行中出问题。

名称必须是唯一的、机器可读的标识符，用下划线或者驼峰都行，但要全项目统一。我踩过的坑是早期混用了两种命名风格，结果模型有时候会猜错名字。

描述是给模型看的自然语言说明，要写清楚这个工具"做什么"而不是"怎么做"。描述里不要塞实现细节，那些放在别的地方。

参数是最容易出问题的部分。每个参数要标明名称、类型、是否必填、取值范围、默认值。类型一定要明确，是字符串还是数字还是布尔，模型对类型很敏感。

返回值要说明返回的数据结构，尤其是当返回值会被后续步骤使用时。如果返回的是 JSON，最好把字段结构写出来。

调用时机这个字段很多人会忽略，但它极其重要。它告诉模型"什么情况下应该调用这个工具"。写得好能大幅减少误调用。

限制条件包括频率限制、权限要求、前置条件等。比如"每分钟最多调用 10 次"或者"需要先完成认证"。

示例给出一到两个具体的调用例子，包括输入和预期输出。模型通过示例学习的效果远好于纯文字描述。

3.2 参数描述为什么最容易翻车

我统计过自己项目里工具调用失败的原因，超过六成是参数问题。不是模型不会调，是参数没描述清楚。

最常见的错误是类型模糊。比如写"参数 count 表示数量"，模型可能传字符串 "5" 也可能传数字 5，如果后端严格校验类型，就会失败。正确写法是"参数 count，整数类型，表示要处理的数量，取值范围 1 到 100"。

第二个坑是枚举值没列全。比如一个工具支持多种模式，描述里只写了"mode 表示模式"，模型就会瞎猜。必须把所有合法值列出来，比如"mode，字符串，可选值为 fast、balanced、accurate，默认 balanced"。

第三个坑是嵌套结构没说明。有些工具的参数是对象或者数组，如果不把内部结构写清楚，模型生成的 JSON 结构经常对不上。我的做法是直接给一个完整的参数示例，让模型照着套。

提示：参数描述里尽量避免"等等"、"之类的"这种模糊词。模型会把这些当成真的还有别的选项，然后开始编。

3.3 调用时机描述怎么写才有效

"调用时机"这个字段我一开始觉得可有可无，后来发现它直接决定了工具调用的准确率。写得好，模型知道什么时候该动手；写得差，模型要么该调不调，要么不该调乱调。

有效的调用时机描述应该包含触发条件和排除条件。触发条件是"当用户请求 X 时调用"，排除条件是"当 Y 情况下不要调用"。

举个例子，一个发送消息的工具，触发条件写"当用户明确要求向某个联系人发送消息，且已经提供了消息内容时调用"。排除条件写"当用户只是在讨论消息功能、或者询问如何发消息时，不要调用"。

这种正反两面的描述能大幅降低误触发。我实测下来，加了排除条件之后，误调用率能降一半以上。

还有一个技巧是优先级说明。当多个工具都能完成类似任务时，要告诉模型优先用哪个。比如"如果有本地工具和远程工具都能完成，优先用本地工具，因为更快"。

3.4 一个完整的工具条目示例

光说理论不够，我直接给一个实际项目里用过的条目，你可以照着改：

### tool: file_read **描述**：读取指定路径的文件内容，返回文本。仅支持读取文本文件，不支持二进制文件。 **参数**： - path（字符串，必填）：文件的绝对路径或相对于工作目录的路径 - encoding（字符串，可选）：文件编码，可选值为 utf-8、gbk，默认 utf-8 - max_lines（整数，可选）：最多读取的行数，默认读取全部，取值范围 1 到 10000 **返回值**： - 成功时返回对象：{ "success": true, "content": "文件内容", "lines": 行数 } - 失败时返回对象：{ "success": false, "error": "错误原因" } **调用时机**： - 当用户要求查看、读取、打开某个文件内容时调用 - 当需要获取文件内容作为后续处理输入时调用 - 当用户只是询问文件是否存在、或讨论文件相关话题时，不要调用 **限制条件**： - 单次读取不超过 10000 行 - 不支持读取二进制文件 - 路径必须在允许的工作目录范围内 **示例**： 输入：{ "path": "./data/config.json", "encoding": "utf-8" } 输出：{ "success": true, "content": "{...}", "lines": 42 }

这个结构看起来有点啰嗦，但正是这种啰嗦让模型调用时的准确率上了一个台阶。我对比过精简版和完整版，完整版的首次调用成功率明显更高。

4. 实操：从零搭建一份可用的 TOOLS.md

4.1 先盘点你手头到底有哪些工具

动手写之前，先做一件事：把所有可调用的能力列出来。这一步很多人跳过，直接开始写文件，结果写到一半发现漏了工具，又回头补，结构就乱了。

盘点的时候按来源分类。一类是系统内置工具，比如文件读写、命令执行、网络请求这些框架自带的能力。另一类是自定义工具，你自己封装的接口或者函数。第三类是外部集成工具，比如对接的第三方服务。

每一类下面再按功能分组。文件操作一组、网络操作一组、数据处理一组、消息通信一组。分组的好处是后面写文件时结构清晰，模型检索也快。

我一般会用一个简单的表格先做盘点，确认没有遗漏再开始写正式文件：

这张表填完，TOOLS.md的骨架基本就有了。

4.2 按功能分组组织文件结构

盘点完之后，正式文件按功能分组来组织。我的习惯是用二级标题分大类，三级标题放具体工具。这样模型在检索时可以先定位大类，再找具体工具，效率更高。

大类的划分不要太细，一般五到八个大类就够了。太细会导致模型在检索时来回跳，太粗又起不到分类的作用。常见的分类有：文件与目录操作、网络与请求、数据处理与转换、消息与通知、系统与命令、外部服务集成。

每个大类开头写一段简短的说明，告诉模型这个大类下的工具大概是什么用途。这段说明不用长，两三句话就行，但能帮模型快速判断该不该在这个大类里找工具。

4.3 参数校验规则要写进文件

这一点是我踩了大坑之后才补上的。早期我只写参数类型，不写校验规则，结果模型经常传一些边界值导致工具报错。后来我在参数描述里直接加上校验规则，情况就好多了。

校验规则包括：数值范围、字符串长度限制、格式要求（比如必须是邮箱格式、必须是 URL）、枚举值列表。把这些写清楚，模型在生成参数时就会自我约束。

比如一个发送消息的工具，接收者参数我会写"recipient，字符串，必填，必须是系统中已存在的联系人标识，长度 1 到 64 个字符，不能包含空格"。这种详细的约束能挡掉大量无效调用。

4.4 给每个工具标注安全等级

安全等级这个字段是我强烈建议加的。把工具分成三个等级：只读、写入、危险。

只读工具随便调，不会造成副作用。写入工具会改变状态，调用前要谨慎。危险工具可能造成不可逆的影响，比如删除文件、发送对外消息，这类工具要标注需要二次确认。

标注方式很简单，在工具条目里加一行"安全等级：写入"。然后在SOUL.md里约定"调用写入及以上等级的工具前，先向用户确认"。这样两层配合，安全性就有保障了。

我实际项目里，加了安全等级标注之后，误操作导致的问题几乎归零。这个投入产出比非常高。

5. 部署集成时的真实踩坑记录

5.1 工具注册了但模型调不动

这是最常见的问题，没有之一。表现是：TOOLS.md里明明写了工具，模型也知道有这个工具，但就是不调用，或者调用时报"工具不存在"。

排查思路我总结了一个顺序。第一步查文件是否被正确加载。很多框架需要显式指定要加载哪些 Markdown 文件，如果TOOLS.md没在加载列表里，写了等于没写。第二步查格式是否符合解析要求。不同框架对 Markdown 的解析规则不一样，有的要求特定标题层级，有的要求特定字段名。第三步查工具名是否和实际注册的一致。文件里写的是file_read，代码里注册的是readFile，对不上就调不动。

我遇到过一次特别隐蔽的：文件里工具名用了中文全角字符，看起来和半角一模一样，但解析时就是匹配不上。这种问题只能靠仔细检查字符编码来发现。

5.2 参数传递总是格式错误

参数格式错误的表现是工具被调用了，但执行失败，报参数不合法。原因通常是模型生成的参数结构和工具期望的不一致。

解决办法有两个方向。一是在TOOLS.md里把参数结构写得更死，直接给完整的 JSON 示例，让模型照着套。二是在工具封装层做兼容处理，对常见的不一致做自动转换，比如字符串数字自动转数字。

我倾向于两个都做。文件里写清楚是治本，封装层做兼容是兜底。双保险下来，参数问题基本能压到很低。

5.3 工具调用陷入死循环

这个坑比较隐蔽。表现是模型反复调用同一个工具，每次都得到相似结果，然后继续调，停不下来。

根本原因通常是工具的返回值没有给模型足够的终止信号。比如一个查询工具，每次都返回"没有找到结果"，但描述里没说"没有结果时应该停止查询"，模型就会一直试。

解决办法是在工具的返回值说明里明确写"如果没有结果，返回 success: false，此时不应重试"。同时在调用时机里加一条"同一工具连续调用超过 3 次无有效结果时，停止调用并告知用户"。

5.4 常见问题速查表

我把实际项目中遇到的问题整理成了一张表，方便快速对照排查：

这张表我贴在工位上，遇到问题先扫一眼，大部分情况能直接定位。

6. 让工具调用更稳的几个进阶技巧

6.1 用示例驱动代替规则堆砌

我早期写TOOLS.md喜欢堆规则，一条接一条，写得像法律条文。后来发现模型对规则的遵循度其实一般，但对示例的模仿能力极强。

所以现在我更倾向于多给示例，少写抽象规则。一个工具给两到三个典型调用示例，覆盖正常情况、边界情况、错误情况。模型看示例就能学会怎么调，比读一堆规则有效得多。

示例的写法也有讲究。不要只给输入，要给完整的输入输出对。最好再配一句简短的说明，讲清楚这个示例演示的是什么场景。

6.2 给工具加"使用场景"标签

除了调用时机，我还会给每个工具加一组场景标签，比如"日常查询"、"批量处理"、"紧急操作"。这些标签不直接给模型看，而是用于我自己的管理和调试。

当发现某类场景下工具调用频繁出错时，我可以快速定位到相关工具，集中优化。这种标签化管理在工具数量多的时候特别有用。

6.3 定期做工具调用的回归测试

TOOLS.md不是写完就完事的，它需要维护。我给自己定的规矩是：每次修改文件后，跑一遍核心工具的调用测试。

测试不用很复杂，准备一组典型的用户请求，看模型是否能正确选择工具、正确传参、正确处理返回。这组测试用例我维护在一个单独的列表里，每次改完文件就跑一遍。

这个习惯帮我挡掉了很多"改了一处坏了另一处"的问题。尤其是当工具之间有依赖关系时，回归测试几乎是必须的。

6.4 版本管理和变更记录

TOOLS.md一定要纳入版本管理。每次修改都要有记录，写清楚改了什么、为什么改。因为工具定义的变更会直接影响模型行为，出问题时需要能回溯到具体是哪次改动导致的。

我的做法是在文件末尾加一个变更记录区，按时间倒序记录每次修改。格式很简单：日期、修改人、修改内容、修改原因。这个记录在排查回归问题时价值极高。

7. 关于这套文件体系的一些个人体会

折腾这套东西大半年，我最大的感受是：AI Agent 的稳定性，很大程度上不取决于模型多强，而取决于你给它的边界多清晰。TOOLS.md就是画边界的那支笔。

我见过太多项目，模型选得很先进，框架搭得很花哨，但实际跑起来各种问题，根源都在于工具定义含糊。反过来，有些项目用的模型不算顶尖，但TOOLS.md写得极其扎实，运行起来反而很稳。

还有一个体会是，这套文件体系的价值会随着项目复杂度上升而放大。工具少的时候，怎么写都行。工具一多，没有清晰的结构和规范，维护成本会指数级上升。所以我的建议是，从一开始就按规范来写，哪怕现在只有三五个工具。养成习惯之后，后面扩展会轻松很多。

最后分享一个小技巧：把TOOLS.md当成一份要交给别人的文档来写。想象你明天要休假，同事需要接手你的 AI 项目，他能不能只看这份文件就搞清楚所有工具怎么用。如果能，说明你写到位了；如果不能，说明还有模糊的地方需要补。这个标准比任何规范都管用。