开篇导读很多人做 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搜索任务要走专用通道不能绕回 BashGrepTool 的提示词很短但力度很强搜索内容时始终使用 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?pwd6fkr