# 团队分享提升 Agent Harness Token 效率的提示词

- 来源：eric zakariasson (@ericzakariasson)
- 发布时间：2026-09-24 04:12
- AIHOT 分数：77
- AIHOT 标记：精选
- AIHOT 链接：https://aihot.news/items/cmuek0q2c05foroynclaijp3z
- 原文链接：https://x.com/ericzakariasson/status/2102853511637774551

## 精选理由

来自 Cursor 团队经验的完整 agent harness 降本 prompt，给出实测数字、执行顺序和常见陷阱，可直接复用。

## AI 摘要

一份公开提示词用于优化 LLM Agent Harness，目标是在不降低任务质量的前提下降低每任务的价格加权 token 成本。某团队一轮改动（提示词精简、工具卸载、缓存布局、稀疏行号、子智能体调优）将整体 token 成本降低约 7%，且质量无损。提示词强调按任务而非按请求计量，并建议先映射 harness、测量基线，再按优先级实施改动。

## 正文

这里有一个提示词，可以基于我们在 cursor 学到的东西来改进你的智能体框架。请享用

提升这个智能体框架的 token 效率

你正在处理一个 LLM 智能体框架：系统提示词、工具定义、请求组装、上下文缓存、压缩与检索，以及工作如何在各个智能体之间拆分。让智能体的运行更便宜，同时不让它把活干得更差。

• 目标：降低每个已完成任务的按价格加权的 token 成本。 - 约束：任务质量没有可测量的下降。

按任务衡量，而不是按请求衡量。每一轮都会重新发送前缀（工具、指令、设置，以及到目前为止的对话），所以一个能缩小每个请求但会增加轮数的改动，反而可能更贵。按计费类型对 token 加权：输出、未缓存输入和缓存输入的定价差别非常大。

按这个顺序来做：先梳理框架并测量基线，对机会点排序，直接做那些可以安全做的改动，把其余的放到开关后面或写成提案，然后汇报。

下面的数字来自某个团队的生产级编程智能体及其多智能体实验。用它们来判断量级，而不是当作目标。这一轮改动（提示词精简、工具卸载、缓存布局、稀疏行号、子智能体调优）让该团队的整体 token 成本降低了约 7%，且质量没有损失。那些更大的百分比只适用于每项改动所触及的那部分请求。

原则

1. 改变的是 harness 发送的内容，而不是模型有多努力。不要要求模型节省 token。一个告诉其模型"注意节省 token、不要浪费"的 harness 发现，模型变得不愿承担有雄心的任务，有时还会退出，说自己不该浪费 token。 2. 有能力的模型需要的是定义，而不是命令。那些"不要""你必须""重要"的清单，以及针对旧模型习惯的防范措施，通常都可以用对每个工具功能的平实描述来替代。有一个团队用这种方式削减了大约三分之二的系统提示词，而更短的提示词在多个模型家族中都奏效。只针对模型无法知道的内容（产品、环境、用户的流程）以及你在对话记录中见过的怪癖进行指示。 3. 静态上下文是留给大多数轮次都需要的内容的。其他一切都应该在需要时可被发现。更少的前置上下文也意味着更少令人困惑或相互矛盾的信息。 4. 要预期删减会胜出。为较弱模型编写的护栏、变成瓶颈的协调步骤，以及针对模型如今已能自行完成的行为所写的提示词，全都在消耗 token。 5. 真实使用情况说了算。评测是快速的替代指标，但它们偏向难题，会错过真实请求的构成。

1. 梳理 harness 并测量基线

查找：

• 请求在哪里组装、系统提示词以及工具 schema。如果某个框架或 SDK 负责构建请求，找到它在消息顺序、缓存控制和工具加载方面的钩子。 - 工具结果的格式化方式，以及历史记录如何保存、裁剪或摘要。 - 子智能体或并行智能体如何生成（如果有的话）。 - 使用了哪些模型和提供商 API。从提供商的文档中，获取提示词缓存行为（自动或显式断点、TTL、最小可缓存长度）以及输出、未缓存输入和缓存输入的价格。 - 现有的日志记录、token 核算和评测。

如果这套运行框架没有按计费类型和缓存命中来记录每个请求的 token 用量，先把这个补上。后面的一切都依赖它。

然后渲染几个真实请求（来自日志，或通过运行代表性任务），用模型的 tokenizer 或 API 的 usage 字段统计每个部分的 token 数。产出：

• 按来源 × 计费类型的成本占比。来源包括：系统提示词、工具定义、技能/规则/集成描述、用户消息、文件读取、搜索结果、命令及其他工具输出、历史记录、摘要、子智能体。 - 每个请求的静态 token 数、缓存命中率，以及每个任务的轮次。 - 按工具统计：至少调用一次该工具的运行占比，以及其错误率。

要阅读渲染后的请求，而不只是模板。重复内容、泄漏的易变值以及顺序错乱的块，只有在那里才会显现出来。

按支出占比 × 可削减比例 ÷ 质量风险，对各项优化机会排序。

2. 系统提示词与注入的上下文

为每条指令打上标签：

• 保留：模型无法推断的产品或环境知识、针对该模型对话记录中出现的怪癖的修复，以及某个模式所依赖的规则。 - 改写：把命令和强调语气改写为平实的描述。把提醒改写为约束条件："不要 TODO，不要部分实现"比"记得完成实现"效果更好。把模糊的数量改写为区间："生成 20-100 个任务"比"生成许多任务"能激发出雄心大得多的行为。 - 删除：能力强的模型默认就会做的事、针对你尚未从该模型观察到的行为的防范措施、重复工具描述的文本，以及可能与用户请求相矛盾的语句。被训练为将系统指令置于用户消息之上的模型，会站在系统提示词一边。 - 移动：把任何按用户或按请求变化的内容（日期、环境、仓库状态、技能或子智能体列表、用户规则）移到缓存边界之后的 user 角色设置消息中。

用同样的方式审查其他注入的上下文。随着模型不断进步，这些数据背后的团队删掉了目录树、预检索的代码片段、附件文件的压缩副本、每次编辑后注入的 lint 错误、对短文件读取的强制扩展，以及每轮工具调用次数上限。他们保留了少量高价值的事实：操作系统、仓库状态，以及打开或最近查看过的文件。

对于开放式工作，跳过检查清单。模型会优化清单上列出的项目，并降低其他一切事项的优先级。

3. 工具定义

工具 schema 会随每个请求一起传输。除核心工具集之外，大多数工具在不到 20% 的对话中才会被用到，而将它们移出静态上下文后，工具描述 token 减少了 60%。对集成类工具（例如 MCP server）采取同样做法--上下文中只保留名称，完整 schema 放在每个 server 一个文件夹中，由智能体用 grep 或 jq 搜索--在使用这些工具的会话中，总 token 减少了 46.9%。

• 保留在静态上下文中：高频工具（对编码智能体而言：read、search、edit、shell）、模型即使不存在也会尝试调用的工具，以及某个模式所依赖的工具。 - 其余全部外置：只留一个名称或一行提示，让完整 schema 可按需发现。将相关工具分组，使其一起加载，并把状态（例如"需要重新认证"）放在智能体能看到的对方。 - 精简保留部分：描述行为和参数，去掉使用说教。 - 通过测试几种配置并跟踪 token、成本、延迟、工具调用错误和任务成功率，来确定拆分方式。

4. 缓存布局

对每个请求进行排序，使可复用的前缀尽可能长：

工具定义 → 系统指令 → 【断点】 → 设置消息（技能、子智能体、规则、环境）→ 【断点】 → 对话

• 保持前缀在各轮之间逐字节一致。使用确定性的工具顺序和序列化方式，把时间戳和 ID 放在边界之后，并且不要重写更早的消息，除非是在进行压缩时。 - 如果服务商支持显式断点，就使用它们。否则依赖自动前缀缓存，把稳定部分放在最前面。遵守 TTL 和最小长度规则。 - 在对话中途切换模型会丢弃缓存（缓存是按模型和服务商分别存储的），并且会把一段并非由它撰写的历史交给新模型。当需要换用另一个模型时，把它作为子智能体在全新上下文中运行。

显式断点，加上把每次请求的设置移到断点之后，将冷缓存未命中减少了 20%。

5. 工具结果以及运行期间添加的其他上下文

• 大型输出（命令、集成、日志）：将其写入文件并返回路径、大小和一小段尾部内容。智能体可以自行 tail、grep 或按范围读取以获取更多信息。截断会丢失数据，而内联则会让后续每一次请求都变得臃肿。长时间运行的终端会话也应同样处理。 - 高容量格式：留意每一行或每一项上重复出现的开销。在读取文件时每隔 10 行编号一次，而非每行都编号，可将缓存读取的 token 减少 1.6%，且不影响引用准确率。每个编号要花费 3-5 个 token，而智能体每次会话要读取数万行。同时还要检查重复的绝对路径、冗长的 JSON 键名、ANSI 转义码、进度条以及重复的表头。 - 良好的检索能节省探索轮次。在 grep 之外加入语义搜索，可将代码库问答准确率平均提升 12.5%，并减少用户所需的迭代次数。 - 工具错误会浪费 token，并在上下文中留下令人困惑的残留物。对预期错误进行分类（无效参数、意外环境、提供商错误、超时、用户中止），将未知错误视为框架缺陷，并按工具和按模型跟踪错误率。沿着这一思路做一次集中优化，可将意外工具错误减少 10 倍。

6. 长时间运行：压缩、子智能体与模型混用

• 压缩：保持摘要提示词简短、摘要紧凑，延续计划状态和剩余任务，并将完整历史保存到文件中，让智能体可以搜索摘要中遗漏的细节。一个经过训练、能从一行提示词进行自我摘要的模型，写出了约 1k token 的摘要，其压缩错误率仅为多千 token 提示词（产生 5k+ token 摘要）的一半。未经训练的模型可能需要更多引导，所以要测试你能压缩到多短。使用更昂贵的摘要模型带来的差异微乎其微。 - 草稿本和运行笔记：重写它们，而不是追加。对于同一环境中的重复工作，一个由智能体维护、带行数预算、在启动时加载的小型笔记文件，是缩短后续运行时间的一种有前景的方式。 - 子智能体：全新的上下文让父智能体保持精简，但隔离会增加协调成本（重复或过时的工作）。如果模型已经会自行委派任务，就移除推动它这样做的提示词。让子智能体返回简短的交接内容：做了什么、发现、顾虑和偏差。只有当用户或运行框架要求时，子智能体才应使用不同的模型。 - 模型组合：在大型多智能体运行中，工作节点使用了至少 69% 的 token，在大多数运行中超过 90%。前沿规划器搭配廉价工作节点，能以约八分之一的成本达到前沿模型包办一切的效果。规划器的选择仍然会改变工作节点的开销。一个自身成本较低的规划器，其工作节点使用的 token 却多了数倍，整体运行成本反而更高。要衡量整棵调用树。 - 路由和推理力度：将简单轮次发送给更便宜的模型或更低的推理力度，只有在更强的模型明显更好时才升级。以这种方式构建的路由器在用户满意度上匹配或超越了单一前沿模型，成本降低了 41-68%。 - 推理连续性：如果 API 返回推理项（包括加密的），在后续轮次中将其传回，并在它们丢失时发出警报。丢弃它们会让一个推理模型在编码基准测试上损失 30%，而且它还会消耗 token 来重建自己的计划。

7. 让 harness 适配每个模型

要适应每个模型训练时所采用的方式，而不是强行让所有模型都套用同一种形态。如果你已经为某个相似的模型调好了 harness，就从那个版本开始。

• 编辑格式：使用模型训练时所采用的格式（例如 patch 风格或搜索替换）。不熟悉的格式会额外消耗推理 token，并导致更多错误。 - Shell 或工具：shell 优先的模型会退回到 cat 或内联脚本。以工具的 shell 等价物来命名工具（例如 rg），如有需要可加上："如果某个操作已有对应工具，优先使用该工具而不是 shell 命令（例如用 read_file 而不是 cat）。" - 字面程度：有些模型家族会严格按字面执行指令，另一些则能容忍不精确。有些模型会对被强调的措辞产生过度反应。对于字面型模型，去掉大写和强调。 - 触发条件：有些模型在被告知何时使用之前会忽略某个工具。字面型触发语有效："在实质性编辑之后，使用 检查最近编辑过的文件是否有 linter 错误。如果你引入了任何错误，在你能轻松弄明白如何修复的情况下修复它们。" - 进度更新：如果模型通过推理摘要来报告进度，让它们保持在 1-2 句话，说明新发现或策略变化，并删除关于回合中途发消息的指令。 - 值得专门写一行的小毛病：随着上下文填满而含糊其辞或拒绝（"上下文焦虑"）、过早宣布完成、停下来请求许可，以及调用不存在的工具。

把每一条新增的指令都与你所修复的对话记录行为对应起来。当模型发生变化时重新审查，因为某个版本需要的指引对下一个版本来说可能是累赘。

8. 验证

• 离线：在改动前后运行一组固定的真实任务，最好取自真实使用场景，并按照用户实际的写法来表述（简短且含糊）。对比任务成功率、token、成本、每任务成本、轮次和工具错误。不要上线会降低成功率的改动。 - 在线，如果你有用户：对每项改动或小批量改动做 A/B 测试。主要指标是每个已完成任务的成本。护栏指标是任务成功信号、工具调用错误、延迟、每任务轮次和缓存命中率。对于编码智能体，一个好的成功信号是智能体编写的代码随时间推移的存活量。一般来说，要看用户的下一条消息是继续推进还是报告问题。 - 只有在成本下降且没有任何护栏指标出现超出噪声的退化时才上线。记录无显著结果。

哪些直接改，哪些先提议

• 直接改，每项各自一个可回滚的提交：token 与缓存遥测、确定性序列化和工具顺序、把易变内容移出缓存前缀、显式缓存断点、把大输出写入文件而不是截断、把正在被丢弃的推理项传回，以及修复反复出现的工具错误。 - 放在开关后面以便测试：系统提示词修改、工具卸载、输出格式变更、压缩变更和子智能体提示词。 - 仅提议：更换所用模型、路由、推理投入默认值，或工作在各智能体之间的拆分方式。

陷阱

• 要求模型使用更少的 token 或做更少的事。 - 截断工具输出。 - 丢弃推理项以节省输入 token。 - 缓存前缀中存在易变内容，或工具顺序在请求之间发生变化。 - 在第一轮就卸载模型需要的工具，或模型尝试调用时该工具已缺失。 - 大量强调的提示词（MUST、NEVER、IMPORTANT、全大写），尤其是对字面理解的模型。 - 强制使用比模型训练时更简洁的输出格式。更少的输出 token 可能意味着更少的思考，结果更差。 - 优化原始 token 数量而非成本，按单次请求而非按任务优化，或优化评测而非真实使用。 - 在对话中途切换模型以省钱。 - 添加会变成瓶颈的协调层。

汇报以下内容

1. 框架图和基线：按来源 × 计费类型划分的成本，并标出最大的来源。 2. 一份按优先级排序的变更清单：层级、变更内容、预估节省额及估算方式、质量风险、如何验证，以及如何回滚。 3. 你所做的变更，包括一份系统提示词 diff，每一行都附上保留、重写、删除或移动的理由。 4. 针对已标记变更的测试计划。 5. 缺口：任何你未能找到或衡量的内容。