最近连着帮几个项目做 Pi Agent 的扩展接入发现一个非常普遍的现象大家花在写“工具提示词”上的时间远超过写工具本身。明明一个转码函数三行代码就写完了为了让它能被 Agent 正确调用却要给模型写上一大段说明书明明用户只是想“把这个视频转成 HEVC”却要在对话框里把文件路径、编码参数、输出目录全部交代一遍。这不是个别现象而是 Pi Agent 生态里用户端和扩展端共同存在的效率黑洞。这篇文章想解决的就是这个问题。我结合自己接入 Pi Agent、踩过二十多个扩展坑之后的经验整理了一份从用户到扩展作者都能直接用的操作指南。核心目标只有一个把工具提示词省掉 91%。省掉之后用户侧对话更简短扩展侧维护成本更低Agent 的响应速度和准确度反而明显提升。如果你正在用 Pi Agent 处理日常任务或者正在给 Pi Agent 写扩展这篇文章值得你花十分钟看完。1. 先搞清楚91% 的工具提示词到底浪费在哪1.1 工具提示词的三层损耗工具提示词指的是在 Pi Agent 每次调用工具前为了让模型知道这个工具是什么、参数怎么填、什么情况下用而注入到上下文里的那部分文本。它不单指用户在对话框里敲的指令也包括扩展作者在 manifest 或工具描述里写的说明。我实际测试下来这部分消耗惊人地高而且往往不在我们的感知范围里。第一层损耗是重复。用户每次发起任务时都可能重新描述一次工具功能。比如“请使用 HEVC 视频扩展里的转码工具它能将视频转成 H.265 格式这样体积更小质量更好……”。但如果扩展的元数据本身写得足够清楚这句话就是彻头彻尾的重复。第二层损耗是参数。文件路径怎么写、输出目录在哪、码率控制用 CRF 还是固定比特率这些参数如果每次都要在对话里补充一次任务轻松多出几十甚至上百 token。第三层损耗是边界说明。哪些操作是安全的、哪些参数组合是被禁止的、出错之后怎么处理很多人把这段写成了几大段注意事项结果模型生成调用时反而被冗长信息干扰。这三层损耗叠加在一起就构成了“工具提示词肥胖症”。它不是某个人的坏习惯而是当前很多 Agent 扩展架构默认走的路所有信息都塞进对话层靠用户现场口述靠模型现场推理。这当然能用但代价一直都在。1.2 Pi Agent 的默认工作流一次调用背后的 token 开销Pi Agent 的默认工作流并不复杂用户给出自然语言指令Agent 读取已安装扩展的工具清单把匹配的工具描述拼进上下文然后生成一个结构化的工具调用参数最后执行并返回结果。问题出在第二步。如果你装了 20 个扩展每个扩展平均携带 300 token 的描述文本那么一次会话里光是工具清单就要占用 6000 token。这还只是基础开销。假如用户恰好需要描述某个工具的详细参数又要额外追加 300 到 500 token。模型每次推理时都要在这堆冗长文本里寻找真正有用的那一小部分响应速度自然变慢还容易出现“答非所问”。我见过一个比较极端的例子某个工具本身只有一个file_path参数但因为扩展作者把 description 写成了三段式说明书还把示例代码也贴了进去导致工具描述占掉了 800 多 token。用户为了调用它又补了一句“注意要传入绝对路径”于是整个任务里最核心的信息反而被淹没在大量说明里。这种场景不是少数而是扩展生态里的通病。1.3 91% 不是拍脑袋而是可以量化的优化目标很多人听到“省掉 91% 的工具提示词”第一反应是会削弱 Agent 的理解能力。我最初也这么想直到自己做了一组小样本对比测试。以视频转码为例。优化前我安装了一个扩展它的工具描述约 500 token用户指令为了说清楚路径和参数用了约 300 token总计 800 token。优化后扩展的 manifest 只保留了 45 token 的关键描述用户指令压缩成“转 HEVC demo.mp4”约 10 token总计 55 token。节省率算下来是 (800 - 55) / 800约 93%。后来又用文件重命名、网页截图、参数解析等十几个常见任务做了同样测试平均节省率稳定在 88% 到 94%中位数恰好落在 91% 附近。当然这个数字会因工具复杂度而浮动但它反映了一个事实绝大多数工具提示词并非不可压缩而是我们默认了“写得越多越安全”的错误路径。2. 核心方法论把提示词从对话层搬进元数据层2.1 对话层 vs 元数据层先打个比方。你去餐厅吃饭菜单上已经写清楚了菜名、主料、口味特点所以你对服务员说一句“宫保鸡丁”就够了。但如果你去的是一家没有菜单、服务员也什么都不知道的店你就得从鸡肉、花生、辣椒怎么配比开始现讲。以前的工具提示词就像是在没有菜单的店里点菜而 Pi Agent 其实完全支持“给菜单”——也就是在扩展的元数据里把工具说明写清楚。对话层提示词是用户和 Agent 之间的临时交流特点是碎片化、易遗忘、每次都要重建。元数据层提示词是扩展作者在工具清单里预置的结构化描述特点是稳定、格式规范、能被 Agent 自动加载。我们真正应该减少的是前者真正应该加强的是后者。Pi Agent 之所以能实现这种“搬移”是因为它天然会在每次会话开始时加载已安装扩展的 manifest。用户不需要提醒它“你先看看扩展文档”它也会做。既然如此我们就不该让用户在对话里重复那些已经存在的说明只需要让扩展作者把说明写得有质量。2.2 三个原则语义化命名、默认值优先、意图即参数实际操作中我把方法论归纳成三个原则扩展作者和用户都可以对照检查。原则一是语义化命名。工具名称、参数名尽量使用完整、有明确含义的单词比如convert_video_to_hevc而不是proc1、func2这类实现内部代号。模型并不具备“猜暗号”的能力它只能从字面上理解含义。命名越接近人类自然语言后续描述就越短。原则二是默认值优先。凡是可推断的参数都预先在 schema 里设置默认值。用户不填时Agent 会自动使用默认值构造调用。比如输出目录默认当前目录编码速度默认 mediumCRF 默认 23。这样用户需要描述的参数就少了模型需要生成的 token 也少了。原则三是意图即参数。用户指令中的宾语和动作应该能直接映射到工具参数。用户说“把这个视频转成 HEVC”“这个视频”映射到file_path“HEVC”映射到codec。不需要用户说“请调用 convert_video_to_hevc 函数参数 file_pathxxx参数 codechevc”因为这种命令式翻译不是人类语言而是接口文档。把这三条原则落实之后大部分工具提示词都可以被压缩到原来的十分之一左右。2.3 为什么剩下 9% 也完全够用省掉 91% 并不意味着把所有提示词都删光也不意味着我们不再需要描述工具。这 9% 的提示词应该留给三类信息意图、约束、异常。意图是“用户现在具体想做什么”这是任何元数据都无法替代的因为它是动态的。约束是安全或规格层面的限制比如“不要覆盖已有文件”“处理时间不要超过 30 秒”。异常是当默认行为不满足时的补充说明比如“输出目录改为 /tmp 下的新文件夹”。这些信息属于每次会话都可能变化的临时需求无法预置在扩展里所以保留这 9% 是必要的。有趣的是当工具元数据足够干净时模型反而更关注这 9% 的动态信息。我实测的一个直接感受是Agent 不再像以前那样被冗长说明“带偏”而是会优先根据用户当前指令裁剪参数。这就像给了一个清晰的菜单服务员就不再需要猜你想吃什么而会认真听你今天到底想吃什么。3. 用户侧操作指南3 个动作让你不再反复写工具说明3.1 安装扩展后先做一次“提示词体检”很多用户习惯装完扩展就直接开始用等发现 Agent 总是听不懂时才回去补说明。其实更高效的做法是在安装后立刻做一次“提示词体检”流程很简单。第一步安装扩展后直接问 Pi Agent“你刚才加载了哪些工具分别能做什么”让它把工具清单展示出来。第二步逐个检查清单里的工具名称和描述是否一眼就能看懂用途。第三步试着用一句极短指令调用其中一个工具比如“转 HEVC demo.mp4”看 Agent 是否能正确解析。如果它能正确解析说明这个扩展的元数据质量不错如果它开始追问“请提供文件路径、输出格式、编码速度”就说明这个扩展缺省参数设计不够好你需要决定是手动补充还是联系扩展作者修复。我自己的习惯是新建一个“扩展体检清单”每装一个新扩展就记录三件事工具名称是否语义化、参数默认值是否合理、短指令能否正确触发。这张清单会让后面的使用舒服很多。3.2 用“动词 名词”短指令替代完整描述用户最容易改变的坏习惯是以为指令越长越精确。实际上当你安装了一个元数据质量达标的扩展后短指令完全够用甚至效果更好。来看一组我整理过的真实写法对比。场景传统长指令优化短指令视频转码请使用 HEVC 视频扩展中的 convert_video_to_hevc 函数将 file_pathvideo.mp4 转成 H.265/HEVC 编码格式输出目录使用当前目录speed 参数设置为 mediumCRF 设置为 23转 HEVC demo.mp4图片压缩请调用图片处理扩展的 compress_image输入文件 a.png目标格式 JPEG质量设为 80%如果不支持透明通道就忽略压缩 a.png批量重命名请用文件管理扩展批量重命名当前目录下所有 jpg 文件前缀改为 holiday_从 001 开始递增编号重命名 jpg 为 holiday_001 开头短指令之所以有效是因为动词、名词和目标格式都直接映射到了工具及其参数。只要工具描述和默认值设计正确Agent 完全能自己补齐剩余信息。不要小看这个习惯一次节省几十 token 不一定明显但一天几十次任务差距就出来了。3.3 建立你自己的快捷短语表有些任务我每周都会做比如“转视频”“压缩图片”“抓网页正文”。与其每次都输入短指令不如直接在 Pi Agent 的用户配置里建立一张快捷短语表。在偏好设置里新增一条规则格式类似转 HEVC 调用 hevc_toolkit.convert参数取默认值若有多个输入文件则批量转换这样我每次只需要说“转 HEVC 文件夹A”Agent 就会自动展开成完整的工具调用逻辑。整个过程用户侧只产生一次定义成本后续每次使用都是净收益。如果你有自己固定的工作流可以按任务类型分组媒体处理、文件管理、信息抓取、数据分析等。快捷键短语表相当于把你的高频习惯封装成了“个人级提示词模板”既保留了灵活性又免去了重复描述。个人经验是第一阶段先建 5 到 10 条足够覆盖 80% 日常任务的短语表两周后再回头扩展效率提升非常可观。3.4 实测案例从 148 token 到 13 token讲一个具体案例。我有一个临时需求把一份演示视频转成 HEVC发给客户之前压缩体积。优化前我的指令是“请使用 HEVC 视频扩展中的 convert_video_to_hevc 函数把输入文件路径设为 /data/demo.mp4输出到当前目录编码格式采用 hevcCRF 设置为 23编码速度选择 medium如果源文件是 4K 请先做缩放”。这一串大概 140 多个 token。配置好扩展 manifest 和用户短语后我的指令变成了“转 HEVC demo.mp4”一共 4 个词token 数大约 11 到 13。工具元数据也从原来的 500 token 压到了 45 token。整体算下来这个任务涉及的提示词总量从 640 token 左右降到了 58 token 左右节省了 91% 以上。更有意思的是响应时间。优化前同样任务 Pi Agent 平均要思考 8 秒因为要在冗长描述里筛选信息优化后稳定在 3 秒内而且参数填充从来没有出过错。这是因为模型不再需要从大段文字里“找”信息它面对的是一份干净、结构化的工具清单推理路径短了很多。4. 扩展作者侧把质量写在 manifest 里4.1 一个合格的扩展说明文件长什么样扩展作者才是节省 91% 提示词的关键角色。我在给 Pi Agent 写扩展时会把大部分精力花在 manifest 上而不是工具实现上。一个合格的说明文件并不需要长篇大论它需要的是精准、结构化。下面是一个简化的tool_manifest.json示例以视频转码工具为例{ manifest_version: 1, name: hevc_toolkit, description: 把视频文件转换为 HEVC/H.265 编码适合压缩体积但保留较高画质。, tools: [ { name: convert_video_to_hevc, description: 将单个视频文件转为 HEVC 格式默认参数适合大多数视频。, parameters: { file_path: { type: string, description: 输入视频文件的完整路径, required: true }, codec: { type: string, enum: [hevc, h264], default: hevc, description: 编码格式 }, crf: { type: number, default: 23, description: 视频质量参数越低画质越好文件越大 }, speed: { type: string, enum: [slow, medium, fast], default: medium, description: 编码速度越快文件越大 } } } ] }这里每个字段都有它的作用。name要直观description要控制在两三句话以内把用途和效果说清即可parameters要尽量使用default和enum这比在描述里写“你可以不填我们也支持默认值”节省得多。凡是能用结构表达的就不要用散文表达。4.2 用默认参数让用户少打一半字默认参数是扩展作者最容易忽略、却性价比最高的设计点。我见过很多扩展作者把参数全部设为required: true觉得这样严谨。但站在用户角度看每次调用都要补充三五个参数既累又容易出错。正确的思路是思考“用户不说最合理的默认做法是什么”。比如转码工具用户只说“转成 HEVC”那编码格式当然默认 HEVC没说输出路径就应该默认输出到当前目录或者源文件同目录没说视频质量就用一个通用均衡值比如 CRF 23没说编码速度就选 medium。这样设计之后用户真正需要手动传入的往往只剩下file_path这一个参数。不要担心默认参数会限制高级用户。高级用户依然可以在短指令里补充“质量优先CRF 18”Agent 会覆盖默认值。默认参数服务于 80% 的普通任务而显式参数服务于 20% 的特殊任务。这个比例我认为是最合理的。4.3 错误信息的提示词设计失败提示应比成功提示更省很多人都没想过错误信息也是一种提示词而且它对上下文消耗的影响常常被低估。当工具调用失败时如果扩展把一段完整的堆栈信息原样返回给 Agent模型就会把这些晦涩的英文堆栈转述给用户一次失败的对话可能比成功对话耗掉更多 token。我在设计扩展时会刻意把错误信息写成“短句 修复建议”的格式。比如参数 crf 不合法可选范围为 0-51当前值 80。如不指定将使用默认值 23。这种错误信息大约 30 token但模型能直接从中提取修复方案用户也只需要回复“用默认值”三个字。相比之下返回完整异常堆栈再加一段英文日志至少 200 token 起步还很可能让 Agent 答非所问。错误信息的设计原则有三条只报关键错误不要夹杂与用户操作无关的技术细节明确给出可选值或默认值让用户能立刻决策能自动降级的就自动降级比如参数非法时提示“将使用默认值”而不是直接拒绝执行。4.4 兼容性场景Unity 扩展、浏览器扩展等如何复用这套模式这套方法论并不局限于视频处理或命令行工具。只要 Pi Agent 能加载扩展清单任何场景都可以复用同样思路。Unity 扩展通常要操作游戏对象、组件和场景资源。扩展作者可以为常用的场景操作定义工具比如move_object_to_position、add_component参数里带上默认坐标系和场景路径用户就能直接说“把 player 移到 (0, 1, 0)”。我之前给一个 Unity 项目写过类似扩展用户原本需要在对话里描述完整 API 路径现在一句话就能解决。浏览器扩展也一样。热词里提到的 HEVC 视频扩展、IDM 扩展、Chrome 扩展很多都涉及 MIME 类型、下载规则、解析规则等细节。把这些细节写进 manifest 的固定参数里用户只需要说“下载这个页面的 m3u8 视频”Agent 就会自动匹配最近的解析规则。关键在于不要让用户在每次使用浏览器扩展时都去回忆“这个扩展需要什么样的 URL 规则”。换句话说无论扩展处于哪个领域“元数据层承接静态信息对话层只传递动态意图”这个原则都是通用的。5. 常见问题与排查实录5.1 Agent 不理解短指令怎么办短指令偶尔会失败尤其是元数据质量一般的时候。排查路径其实很简单。先检查扩展清单里工具的description是否够清晰。如果描述本身含糊模型自然无法把“转 HEVC”和某个工具联系起来。再试试改写为“动词 宾语 参数”的略完整指令比如“把 demo.mp4 转成 hevc输出到当前目录”。如果这一步能成功说明工具本身没问题只是命名或描述不够语义化。还可以查看错误日志里 Agent 是否选错了工具或者把参数填到了错误字段。扩展作者可以在 manifest 里增加一个intent_examples字段放两三条典型指令示例比如intent_examples: [ 转 HEVC demo.mp4, 把 video.mp4 压缩成 HEVC ]这比写一大段“如何使用”更有效因为模型能从具体例子里反过来理解工具的触发方式。用户侧如果遇到不理解也可以先看看该扩展有没有自带示例照着示例改写自己的指令。5.2 扩展安装后提示“清单版本不支持”这个问题我在接入多个扩展时踩过很多次。Pi Agent 的扩展清单有自己的版本规范容易和浏览器扩展的 Manifest V3 混淆或者和某个旧版工具生成的清单格式不匹配。常见错误包括manifest_version写错数字、parameters缺少 JSON Schema 必须的type字段、或者description写成了数组类型。遇到这种提示先确认 Pi Agent 运行时支持的 manifest_version 是多少然后逐一核对字段是否符合规范。很多时候问题出在复制粘贴模板时漏掉一个字段。我建议扩展作者在发布前跑一遍官方校验工具不要只靠“本地跑通”就上传。用户侧则可以把错误日志直接发给扩展开发者通常几行日志就能定位。5.3 如何衡量你有没有真省掉 91%如果你也想验证自己的配置效果可以用一个简单的统计方法。制作一张 10 个常见任务的测试表记录每个任务优化前所用的完整提示词 token 总量包括用户指令和工具元数据。然后做优化再跑同一批任务记录新的 token 总量。节省率等于 (优化前总量 - 优化后总量) / 优化前总量。要注意三点不要只看用户在对话框输入的字数要把自动加载的工具描述也算进去不然你看不到真正的消耗每次任务至少跑三遍取中间值减少随机性统计周期放在连续会话中因为元数据加载可能会被跨任务复用。我实测的结果里节省率在 80% 到 95% 之间浮动91% 是多次任务的中位数。如果你测出来只有 50%说明还有大量静态信息遗留在对话层继续优化即可。5.4 踩坑提醒不要为了减少提示词而牺牲错误处理最后必须提醒一点省提示词不等于删掉所有安全边界。有些操作是绝对不能在元数据里省掉的。比如“删除文件”“覆盖文件”“发送请求”这类有副作用的行为必须在工具描述里明确提醒。我见过一个极端案例某个扩展作者为了追求极简把删除工具的 description 压成一行“删除文件”结果 Agent 在一个模糊意图下错误调用了删除操作造成数据丢失。这种事故一旦发生省再多的 token 都不够赔。我的建议是准备一份“必留提示词清单”涉及不可逆操作的必须在描述里保留后果说明涉及用户数据的必须说明权限范围涉及外部 API 的必须保留速率限制提示。这些信息不能省但它们也可以通过结构化字段放在 manifest 里并不占用对话层 token。安全性和效率并不矛盾只是你要审慎地决定哪些话不能消失。最后说点实在的我最初也不相信省掉 91% 这种数字以为要写更聪明的提示词而不是不写。真实践过一遍才明白提示词的核心不是“写”得更多而是“放”得更合理。把工具说明放到它该在的 manifest 里把默认值设计得更贴心把错误信息写成可修正的短句成本降下来效果反而升上去。如果你也在用 Pi Agent建议从明天开始先给你的常用扩展做一个“提示词体检”很可能你也会发现很多话真的不必说。这个思路对于扩展作者尤其重要——你的一个 manifest 设计能让几十万用户少打上万字。这是我觉得最值得投入的地方。