开篇导读
很多人做 AI Agent 时，最容易盯着模型参数、系统提示词、工具数量，却忽略了一个非常关键的细节：每一个工具自己的提示词。它看起来只是一个 description 字段，实际上却在悄悄决定模型什么时候用工具、怎样用工具、不能做什么、遇到风险怎么收敛。
这套设计可以理解为"微型驾驭器"：系统提示词像总纲，决定整体角色和大方向；工具提示词像每个岗位的操作规程，决定具体动作是否安全、准确、可控。真正好用的 Agent，不只是把工具塞进模型，而是给每个工具都写清楚行为边界。
内容结构
**•**1. 工具提示词的本质：微型行为控制器
**•**2. 六类核心工具的提示词设计：Bash、Edit、Read、Grep、Agent、Skill
**•**3. 工程落地方法：安全、预算、缓存、委派、运行时兜底
**•**4. 七条通用原则：从功能说明升级为行为契约
一、先抓住本质：工具提示词不是介绍词，而是行为控制器
很多人做 AI Agent 时，最容易盯着模型参数、系统提示词、工具数量，却忽略了一个非常关键的细节：每一个工具自己的提示词。它看起来只是一个 description 字段，实际上却在悄悄决定模型什么时候用工具、怎样用工具、不能做什么、遇到风险怎么收敛。
这套设计可以理解为"微型驾驭器"：系统提示词像总纲，决定整体角色和大方向；工具提示词像每个岗位的操作规程，决定具体动作是否安全、准确、可控。真正好用的 Agent，不只是把工具塞进模型，而是给每个工具都写清楚行为边界。
下面按 Bash、Edit、Read、Grep、Agent、Skill 六类核心工具展开，重点讲清楚它们背后的提示词工程方法。全篇尽量不用复杂术语，用工程视角说透：为什么这样设计、解决什么问题、普通团队怎么复用。
二、双层驾驭架构：系统提示词管战略，工具提示词管动作
如果只靠系统提示词，模型只能获得一套全局规范，比如"要安全""要谨慎""要优先使用专用工具"。但到了实际执行时，模型面对的是一个个具体工具：读文件、改文件、搜索内容、执行命令、委派子任务、加载技能。每个动作的风险都不一样，所以不能只靠一个大而全的总提示词。
更稳的做法，是把规则拆到工具层。搜索工具负责告诉模型怎样搜；编辑工具负责告诉模型修改前必须读；命令工具负责告诉模型哪些命令危险；技能工具负责告诉模型什么时候先加载技能。这样一来，模型每次看到某个工具时，就同步看到这个工具的使用规矩。
这种设计的价值在于"就近约束"。模型不需要从一大段全局规则里回忆某个工具的细节，而是在调用工具前直接看到最相关的行为协议。
三、BashTool：最强万能工具，必须先被"降权使用"
Bash 是最危险也最有用的工具。它可以运行命令、调用脚本、读写文件、搜索内容、操作 Git，甚至可以绕过很多专用工具的结构化约束。所以成熟的设计不会鼓励模型"什么都用 Bash"，而是反过来把 Bash 的流量导向更专用的工具。
这就是"万能工具降级"的核心思想：通用入口不是不能用，而是不能滥用。凡是能用专用工具完成的动作，就尽量交给专用工具。比如找文件交给 Glob，搜内容交给 Grep，读文件交给 Read，改文件交给 Edit，写文件交给 Write，普通沟通直接输出文本。
为什么要这样做？因为专用工具通常有更好的结构化输入、更清晰的权限检查、更容易审计的结果呈现。Bash 命令本质上是一串文本，模型一旦生成复杂命令，系统很难像审查结构化工具那样精准控制。
四、BashTool 的安全核心：不是会执行命令，而是知道哪些命令不能碰
一个能跑命令的 Agent，真正的难点不在于"跑得起来"，而在于"不会把用户环境搞坏"。因此 BashTool 里最重要的一类规则，是围绕 Git、安全命令、后台任务、超时、路径、并发方式展开的操作协议。
Git 操作尤其敏感。比如修改全局配置、强制推送、硬重置、跳过 hooks、误用 git add .、在用户没要求时主动提交，这些都可能导致数据丢失、泄露敏感文件、破坏团队分支历史。工具提示词必须把这些高风险动作明确压住。
这里有一个非常值得借鉴的写法：不要只说"禁止"，还要说明原因。模型理解原因后，更容易在相似场景下做出稳妥决策。例如"不强推主分支"不是口号，而是为了保护团队共享历史；"不要跳过 hooks"是为了避免绕过质量检查和签名验证。
五、命令执行也要有节奏：并发、串行、失败容忍要分清
BashTool 的另一个价值点，是把多命令执行拆成清晰决策：独立任务可以并行；有依赖的任务要串行；前一步失败就不该继续的，用严格链路；前一步失败也能继续的，才允许松散串行。
这听起来像基础常识，但对模型非常重要。模型在没有约束时，容易把多个命令堆在一起，既不方便观察，也不方便失败恢复。好的工具提示词会把这些执行策略写清楚，让模型在生成命令之前先判断依赖关系。
另外，针对 sleep 的抑制也很关键。很多自动化脚本习惯用等待和轮询兜底，但 Agent 场景中，大量 sleep 会拖慢体验、浪费轮次，还可能掩盖真正错误。更好的策略是：能立即执行就立即执行，长任务走后台，失败先诊断根因，不要盲目 sleep 循环。
六、FileEditTool：编辑前必须先读取，这是反幻觉的底线
文件编辑是 AI 编码里最容易出事故的动作之一。模型如果没看过当前文件，就直接生成修改内容，本质上是在凭印象做手术：它可能记错文件结构、猜错缩进、替换错相似片段，甚至把不存在的内容当成真实内容。
因此 FileEditTool 的核心规则非常直接：编辑之前必须先读取。这个规则不是礼貌提醒，而是提示词和运行时共同执行的硬约束。提示词提前告诉模型"没读过会失败"，运行时负责真正检查。
这套双层保护很适合企业级工具设计。提示词层减少无效调用，运行时层兜底安全。只靠提示词容易被模型偶尔忽略；只靠运行时虽然安全，但会浪费一次失败调用。两层一起上，体验和安全都更稳。
七、old_string 的关键：不是越长越安全，而是刚好唯一
编辑工具通常需要模型提供待替换的旧文本。很多人以为旧文本越长越安全，其实不一定。太短可能匹配多个位置，导致工具无法判断；太长会浪费上下文，还容易因为多一个空格、少一个换行而匹配失败。
更合理的策略是"最小唯一"：用足够少、但能明确定位目标的相邻内容来匹配。比如两到四行相邻内容，通常既能保证唯一性，又不会带来太高 token 成本。
还有一个细节非常重要：Read 工具返回内容时可能带行号前缀，Edit 工具的提示词要明确告诉模型，真正参与匹配的是行号之后的文件内容，不能把行号符号、箭头、制表符前缀混进替换文本。这个规则本质上是工具之间的接口契约。
八、FileReadTool：读取不是越多越好，而是要按预算读取
很多 Agent 效果差，不是因为模型不聪明，而是因为上下文被无关内容塞满了。FileReadTool 的设计正好体现了"资源感知"：默认读一定范围，必要时再精准读取；小文件可以完整理解，大文件要分页、分段、分位置处理。
默认读取约 2000 行，是一个工程折中。它足够覆盖大部分单文件场景，又不会一下吃掉太多上下文。模型如果已经知道目标位置，就应该用更精准的 offset/limit 读取，减少无关内容进入上下文。
除了普通文本，读取工具还要声明自己能处理哪些多模态内容，比如图片、PDF、Notebook。更关键的是，这些能力必须和运行时能力对齐：能处理才声明，不能处理就不要写进工具提示词。否则模型会反复尝试不可用能力，浪费时间和上下文。
九、GrepTool：搜索任务要走专用通道，不能绕回 Bash
GrepTool 的提示词很短，但力度很强：搜索内容时始终使用 Grep，不要让模型通过 Bash 去调用 grep 或 rg。这并不是为了形式统一，而是为了保证权限、忽略规则、结果上限都能被系统接管。
专用搜索工具往往会附带读权限检查、版本控制目录排除、忽略模式处理、结果数量控制。如果模型直接用 Bash 跑命令，就可能绕过这些保护层。
这就形成了一个双向闭环：BashTool 里告诉模型"搜索不要用 Bash"；GrepTool 里告诉模型"搜索应该用 Grep"。单边提示容易漏，双向约束才更稳。
十、GrepTool 的上下文保护：默认少返回，必要时再展开
搜索工具最容易制造"结果洪水"。一个常见词可能命中几百上千行，如果全部塞进上下文，模型后续推理质量反而会下降。GrepTool 通过输出模式和 head_limit 建立了结果预算。
默认只返回匹配文件路径，是一种非常聪明的策略：先帮模型缩小范围，再决定是否展开具体内容。只有当需要查看匹配行时，才切到 content 模式；当需要判断分布时，才看 count 模式。
head_limit 则是最后一道阀门。默认限制结果数量，避免一次搜索污染上下文；同时保留"显式解除限制"的方式，给复杂场景留出口。这就是"安全默认值 + 逃生舱口"的典型设计。
十一、AgentTool：委派不是偷懒，而是上下文隔离与专业化协作
当任务变复杂时，主 Agent 不可能把所有搜索结果、日志、文件内容都塞进自己的主上下文。AgentTool 的价值在于把一部分工作交给子代理，让子代理在自己的上下文里探索，最后只把结论带回来。
这带来三个好处：第一，主上下文不被搜索噪声淹没；第二，可以给不同子代理配置不同工具权限；第三，可以把重复性角色沉淀成可复用的专门代理。
但委派也有风险。最常见的问题是父代理把理解工作直接扔出去，比如"你根据调查结果修一下"。这种指令太模糊，容易让子代理既做研究又做决策，最后上下文断层。更好的做法是父代理自己先理解任务，再把具体、完整、可执行的目标交出去。
十二、动态 agent 列表为什么要外移：为了保护缓存命中率
AgentTool 的提示词会受到运行时状态影响：有哪些 agent、每个 agent 能用哪些工具、是否允许 fork、是否处于协调模式。若把这些动态信息全部塞进工具描述，一旦列表变化，工具 schema 就会频繁变化，提示词缓存也会频繁失效。
更好的办法是把稳定内容和动态内容拆开。工具描述保持稳定，只说明"可用 agent 列表会在单独消息中出现"；真正频繁变化的列表，通过额外消息注入。这样既让模型看到最新可用能力，又不破坏工具描述层的缓存稳定性。
这背后是一个很重要的上下文工程原则：高频变化的信息不要污染低频稳定的结构。稳定结构越稳定，缓存越容易命中，系统成本越低。
十三、Fork 子代理：继承上下文，但不能偷看、抢跑、瞎猜
Fork 子代理可以理解为"从当前上下文分出去做事"。它继承父代理已经知道的信息，因此适合研究、实现、排查等任务，不需要重新解释背景。相比从零创建的子代理，fork 更轻量。
但 fork 也需要纪律。父代理不能随意偷看中间输出，否则子代理本来要隔离的搜索噪声又回到主上下文。父代理也不能在 fork 还没完成时抢先猜测结果，更不能编造 fork 发现了什么。
正确做法是：给 fork 一个明确指令，让它独立完成；等它返回后，再由父代理做综合判断。这样才能既获得并行探索能力，又不破坏主线推理。
十四、SkillTool：技能目录不能无限膨胀，必须做预算管理
技能系统最容易被低估的成本，是"目录本身也消耗上下文"。如果有几十上百个技能，每个技能都带一段很长描述，即使没有真正加载技能，也会让模型一开始就背上沉重负担。
SkillTool 的设计思路是：技能列表只是发现入口，不是完整教材。模型只需要知道有哪些技能、什么时候可能用，真正的技能细节应该在命中后再加载。
因此技能列表要有固定预算，并按优先级降级：预算足够时完整展示；超预算时裁剪描述；还不够时低优先级技能只保留名称。这样才能让技能生态变大时，系统仍然保持轻量。
十五、SkillTool 的阻塞性要求：匹配技能后先加载，再回答
一个成熟的技能系统，还要防止模型"先说一段，再加载技能"。如果技能中有更专业的流程、规范、模板，模型先输出的内容很可能与技能要求不一致。
所以 SkillTool 需要强约束：一旦判断某个技能匹配当前任务，就先调用技能，再基于技能内容继续处理。这种做法能保证专业流程优先进入上下文。
同时还要防止重复加载。如果当前轮次已经出现技能标记，说明技能内容已经注入，模型应该直接遵循，而不是再次调用。这能避免同一技能反复进入上下文，造成冗余和成本浪费。
十六、六类工具放在一起看：成熟 Agent 的四种能力
把六类工具放在一起看，会发现它们并不是简单的功能集合，而是覆盖了四类关键能力：行为约束、资源管理、协作编排、缓存优化。
行为约束解决"能不能安全做"；资源管理解决"会不会把上下文撑爆"；协作编排解决"复杂任务怎么分工"；缓存优化解决"长期使用成本是否可控"。
很多团队做 Agent 时，只关注工具数量，却没有建立这四类能力。结果就是：工具很多，行为很散；功能很强，事故也多；短期能演示，长期成本高。真正工程化的 Agent，一定要同时考虑这四个维度。
十七、六类工具提示词对比表
下面这张表可以作为设计 AI Agent 工具体系时的检查清单。
|--------------|----------|-------------------|------------------|
| 工具 | 核心问题 | 主要策略 | 可复用启示 |
| BashTool | 万能但高风险 | 流量导向、Git 防线、命令节奏 | 通用工具要主动降权使用 |
| FileEditTool | 容易误改文件 | 编辑前读取、最小唯一匹配、缩进契约 | 关键动作要有前置条件和运行时兜底 |
| FileReadTool | 上下文容易爆 | 默认行数、精准读取、分页读取 | 读取是为决策服务，不是越多越好 |
| GrepTool | 搜索结果易泛滥 | 专用入口、语法纠偏、结果上限 | 高频工具要有安全默认值 |
| AgentTool | 复杂任务难分工 | 动态列表、fork 纪律、委派质量 | 委派要保护主上下文与决策责任 |
| SkillTool | 技能目录会膨胀 | 1% 预算、三级截断、按需加载 | 可扩展能力必须做成本控制 |
十八、落地原则一：建立双向闭环，不要只写单边规则
如果你不希望模型用 Bash 做搜索，只在 Bash 里写"不要搜索"还不够。更稳的做法，是在 Bash 里写"搜索请用 Grep"，同时在 Grep 里写"搜索任务请始终用我"。
这就是双向闭环。一个工具负责拒绝不该属于自己的任务，另一个工具负责接住该属于自己的任务。单向约束像提示，双向闭环更像路由规则。
十九、落地原则二：每条禁令最好带原因
模型不是传统程序，它会根据语义做迁移判断。如果只写"不要做某事"，模型在相似但不完全一样的场景中可能会绕开。
如果写清楚原因，模型更容易把规则迁移到新场景。例如不要直接用 shell 搜索，不只是因为"规定如此"，而是因为专用搜索工具带权限检查、忽略规则和结果控制。理解原因后，模型更容易在未知场景中选择安全路径。
二十、落地原则三：工具能力必须和运行时一致
提示词里写了某个能力，运行时就必须能兑现。否则模型会反复尝试失败，既浪费轮次，也污染上下文。
例如某个环境不支持 PDF 解析，那读取工具的提示词就不应该声明可以处理 PDF。某个功能只在特定模式下可用，也应该用条件注入，让模型只在能力真实存在时才看到相关说明。
二十一、落地原则四：保守默认值 + 显式逃生舱口
凡是可能产生大结果或副作用的工具，都应该默认保守。搜索结果要有限制，读取行数要有限制，PDF 页数要有限制，命令超时要有限制。
但保守不等于封死。复杂任务确实可能需要解除限制，所以应提供明确出口，并让模型知道"谨慎使用"。这种设计比完全放开更安全，也比完全禁止更灵活。
二十二、落地原则五：动态内容要外移，稳定内容要缓存
工具描述、系统提示词、固定协议，这些内容越稳定，越适合放在可缓存前缀里。agent 列表、运行时权限、插件状态、环境变量，这些内容变化频繁，就应该单独注入。
稳定内容和动态内容混在一起，会导致任何小变化都让缓存失效。长期看，这会增加延迟和成本。工程化 Agent 必须从第一天就考虑缓存边界。
二十三、落地原则六：把工具描述当作接口文档写
工具之间经常存在上下游关系。Read 的输出会成为 Edit 的输入；Grep 的结果会引导 Read 精准读取；Agent 的输出会回到父代理做综合判断。
因此工具提示词不仅要描述自己，还要描述与其他工具的接口契约：哪些前缀不能带入，哪些字段必须唯一，哪些结果只是摘要，哪些内容不能提前读取。
二十四、落地原则七：技能与子代理都要防止"浅层调用"
很多 Agent 失败，不是因为没有技能和子代理，而是因为调用方式太浅。看到关键词就加载技能，看到复杂任务就丢给子代理，这会制造新的混乱。
技能应该解决可重复流程，子代理应该承担隔离上下文或专业执行。父代理仍然要负责理解问题、拆解目标、判断结果。把"理解"交出去，往往会导致主线丢失。
二十五、普通团队怎么复用这套方法
第一步，先列出你的工具清单，把工具分成通用工具、专用工具、高风险工具、大输出工具、委派工具、技能工具。不同类别的工具，提示词重点不同。
第二步，为通用工具写流量导向表。凡是有专用工具能做的事情，都写清楚"不要用通用工具做，应该交给哪个专用工具"。
第三步，为高风险工具写安全协议。涉及文件修改、数据库写入、生产环境、支付、权限、Git、部署的工具，都应该有明确禁令、原因说明和运行时兜底。
第四步，为大输出工具写预算规则。搜索、读取、日志、报表、批量查询都要有默认上限，并允许在明确需要时扩大范围。
第五步，为委派类工具写质量标准。子代理不是垃圾桶，不能把模糊任务丢进去。要说明背景、目标、限制、输出格式，以及父代理自己保留哪些判断责任。
二十六、总结：优秀工具提示词的终点，是让 Agent 从"能干活"变成"会负责"
工具提示词的价值，不是把工具功能介绍一遍，而是把模型的局部动作变成可控行为。它要告诉模型：这个工具适合什么、不适合什么；什么时候应该先做准备；结果应该多大；失败后该诊断还是重试；哪些动作永远不要擅自执行。
从 BashTool 到 SkillTool，可以看到一条非常清晰的工程化路线：用流量导向减少误用，用前置条件减少幻觉，用资源预算保护上下文，用动态外移保护缓存，用委派纪律保护主线判断。
真正成熟的 AI Agent，并不是工具越多越好，而是每个工具都有清晰职责、明确边界、安全默认值和成本意识。把工具提示词写成行为契约，Agent 才能从"会调用工具"升级为"能稳定完成任务"。
资料参考：https://pan.baidu.com/s/1Fm6rZSZkY3q2NcrmTfTMeQ?pwd=6fkr