这是基于我们在 Cursor 团队的实践经验，为您优化代理系统框架提供的提示。希望对您有帮助。

提升此代理系统框架的令牌效率

您正在开发一个LLM代理系统框架：涵盖系统提示、工具定义、请求组装、上下文缓存、压缩与检索，以及任务在多个代理间的分配。目标是降低运行成本，同时不降低代理完成任务的质量。

• 目标：降低每个完成任务的、按价格加权后的令牌成本。
• 约束：任务质量不得有可衡量的下降。请以任务而非请求为单位衡量。每轮对话都会重新发送前缀（工具、指令、设置及当前对话历史），因此一个能缩小每次请求体积但增加对话轮次的改动，总体成本可能更高。令牌需按计费类型（输出、未缓存输入、缓存输入）进行权重计算，因为它们的价格差异很大。 请按以下顺序工作：绘制系统框架图并测量基线；对优化机会进行排序；直接实施安全的改动；将其余改动置于功能标志后或形成提案；最后撰写报告。 下文图表数据来源于某个团队的生产编码代理及其多代理实验。请用其衡量规模，而非作为目标值。仅一轮这样的改动（提示精简、工具卸载、缓存布局优化、稀疏行号、子代理调优），就使该团队的整体令牌成本降低了约7%，且质量无损失。更大的百分比仅适用于该改动所触及的部分请求。

原则

1. 改变系统框架发送的内容，而非模型的工作强度。 不要要求模型节省令牌。一个提示其模型“注意节省令牌，避免浪费”的系统框架发现，模型变得不愿执行有挑战性的任务，有时甚至会退出，称自己不应该浪费令牌。
2. 强大的模型需要定义，而非指令。 “不要”、“你必须”、“重要”等指令列表，以及防范旧版模型习惯的规则，通常可以替换为对每个工具功能的简单描述。一个团队以此方式削减了约三分之二的系统提示，且更短的提示在不同模型家族间都有效。仅针对模型无法知晓的内容（产品、环境、用户流程）以及您在对话记录中发现的特殊情况进行指示。
3. 静态上下文用于大多数轮次所需的内容。 其他所有内容都应可在需要时被发现。更少的预设上下文也意味着更少令人困惑或相互矛盾的信息。
4. 预期删除会带来收益。 为较弱模型编写的护栏、已成为瓶颈的协调步骤、以及为模型已能自主完成的行为而设置的提示，都在消耗令牌。
5. 实际使用情况决定一切。 评估是快速的替代指标，但它们偏向于困难问题，并会遗漏真实请求的混合情况。

1. 绘制系统框架图并测量基线

查找：

• 请求组装的位置、系统提示和工具模式。如果框架或SDK构建了请求，请找出其在处理消息顺序、缓存控制和工具加载方面的钩子。
• 工具结果的格式，以及历史记录的保存、修剪或摘要方式。
• 子代理或并行代理的生成方式（如果存在）。
• 所使用的模型和提供商API。从提供商文档中获取提示缓存行为（自动或显式断点、TTL、最小可缓存长度）以及输出、未缓存输入和缓存输入的价格。
• 现有的日志记录、令牌核算和评估。如果系统框架没有按计费类型和缓存命中率记录每个请求的令牌使用情况，请首先添加此功能。后续一切工作都依赖于此。 然后，呈现几个真实请求（来自日志，或通过运行代表性任务），使用模型的分词器或API的使用字段，计算每个部分的令牌数。 产出：
• 按来源×计费类型划分的成本占比。来源：系统提示、工具定义、技能/规则/集成描述、用户消息、文件读取、搜索结果、命令及其他工具输出、历史记录、摘要、子代理。
• 每个请求的静态令牌数、缓存命中率以及每任务的对话轮次。
• 按工具划分：至少调用过一次该工具的运行占比及其错误率。 阅读渲染后的请求，而不仅仅是模板。重复内容、泄露的易变值和顺序错乱的块只在渲染后才会显现。 按（支出占比 × 可移除比例 ÷ 质量风险）对优化机会进行排序。

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

标记每一条指令：

• 保留：模型无法推断的产品或环境知识、针对此模型在对话记录中发现的特殊性进行的修复、以及某个模式所依赖的规则。
• 重写：将指令和强调性措辞改为简单描述。将提醒改为约束：“不要TODO，不要部分实现”比“记得完成实现”效果更好。将模糊的数量改为范围：“生成20-100个任务”比“生成很多任务”能获得更具雄心的行为。
• 删除：模型默认就能做到的事情、针对您未从此模型观察到的行为进行的防护、重复工具描述的文本、以及可能与用户请求产生矛盾的行。经过训练将系统指令置于用户消息之上的模型会偏信系统提示。
• 移动：任何按用户或按请求变化的内容（日期、环境、仓库状态、技能或子代理列表、用户规则）移动到缓存边界之后的用户角色设置消息中。 同样方式审计其他注入的上下文。随着模型改进，产出这些数据的团队移除了目录树、预检索的代码片段、附加文件的压缩副本、每次编辑后注入的lint错误、对短文件读取的强制扩展，以及每轮工具调用上限。他们保留了小而高价值的事实：操作系统、仓库状态、以及打开或最近查看的文件。跳过开放式工作的检查清单。模型会优化列出的项目，并降低其他所有事项的优先级。

3. 工具定义

工具模式随每个请求发送。大多数核心工具集之外的工具在每次对话中被需要的比例低于20%，将其移出静态上下文可削减60%的工具描述令牌。对集成工具（如MCP服务器）做同样操作——在上下文中仅保留名称，在每个服务器的一个文件夹中存储完整模式，供代理通过grep或jq搜索——可将使用这些工具的会话的总令牌数削减46.9%。

• 保留在静态上下文：高频工具（对于编码代理：读取、搜索、编辑、shell）、模型即使在工具缺失时也会尝试调用的工具、以及某个模式所依赖的工具。
• 卸载其余工具：仅保留名称或一行指针，使完整模式可按需发现。将相关工具分组以便一起加载，并将状态（如“需要重新认证”）放在代理会看到的地方。
• 精简保留项：描述行为和参数，移除使用说教。
• 通过测试几种配置，并跟踪令牌数、成本、延迟、工具调用错误和任务成功率，来确定最佳拆分方案。

4. 缓存布局

排列每个请求，使可重用的前缀尽可能长： 工具定义 → 系统指令 → [断点] → 设置消息（技能、子代理、规则、环境） → [断点] → 对话

• 保持前缀在轮次间字节相同。使用确定性的工具顺序和序列化，将时间戳和ID放在边界之后，除非进行压缩，否则不要重写早期消息。
• 如果提供商支持，使用显式断点。 否则，依赖自动前缀缓存，并将稳定部分放在前面。遵守TTL和最小长度规则。
• 在对话中途切换模型会丢弃缓存（缓存按模型和提供商划分），并将一个新模型从未编写过的历史记录交予它。当需要不同模型时，将其作为子代理运行，并提供全新上下文。显式断点加上将按请求的设置移至其后，将冷缓存未命中率降低了20%。

5. 运行过程中添加的工具结果及其他上下文

• 大型输出（命令、集成、日志）：将其写入文件，返回路径、大小和一小段尾部。代理可以通过tail、grep或读取范围来获取更多内容。截断会丢失数据，内联则会膨胀每个后续请求。长期运行的终端会话也应同样处理。
• 高容量格式：查找每行或每项重复的开销。对文件读取每10行（而非每行）进行编号，在不影响引用准确性的情况下，将缓存读取令牌数削减了1.6%。每个编号耗费3-5个令牌，而代理每个会话会读取数万行。同时检查重复的绝对路径、冗长的JSON键、ANSI代码、进度条和重复的头部。
• 良好的检索可节省探索轮次。 在grep之外添加语义搜索，使代码库问答的准确率平均提高了12.5%，并减少了用户所需的迭代次数。
• 工具错误浪费令牌，并在上下文中留下令人困惑的残留物。 对预期错误（无效参数、意外环境、提供商错误、超时、用户中止）进行分类，将未知错误视为系统框架缺陷，并按工具和模型跟踪错误率。一个专注的努力使意外工具错误减少了10倍。

6. 长时间运行：压缩、子代理与模型混合

• 压缩：保持摘要提示简短且摘要紧凑，携带计划状态和剩余任务，并将完整历史记录保存到一个文件中，以便代理搜索摘要中遗漏的细节。一个经过训练能从一行提示进行自我摘要的模型，撰写约1k令牌的摘要，其压缩错误率仅为生成5k+令牌摘要的多千令牌提示的一半。未经训练的模型可能需要更多指导，因此测试你能将提示精简到何种程度。使用更昂贵的摘要模型收效甚微。
• 草稿本和运行笔记：重写它们，而非追加。对于在一个环境中的重复工作，一个由代理维护的小型笔记文件（有行数限制），并在启动时加载，是缩短后续运行的一种有前景的方法。
• 子代理：全新上下文使父代理保持精简，但隔离增加了协调成本（重复或过时的工作）。如果模型已经自行委托，则移除推动其这样做的提示。让子代理返回简短交接：已完成的内容、发现、关注点和偏差。子代理仅在用户或系统框架要求时才应使用不同的模型。
• 模型混合：在大型多代理运行中，工作者至少使用了69%的令牌，在大多数运行中超过90%。一个前沿规划器加上廉价工作者，其成本约为一个完成所有工作的前沿模型的八分之一。规划器的选择仍然影响工作者开支。一个自身成本较低的规划器，其工作者使用的令牌数却是数倍，导致总运行成本更高。测量整棵树。
• 路由与推理努力：将简单的轮次发送给更便宜的模型或更低努力程度的模型，仅在明确需要更强模型时才升级。以此方式构建的路由器，在用户满意度上匹配或超过单一前沿模型，同时成本降低41-68%。
• 推理连续性：如果API返回推理项（包括加密的），请在后续轮次中传递回去，并在它们丢失时发出警报。丢弃它们使一个推理模型在编码基准测试上下降了30%，并且它消耗了令牌来重建其计划。

7. 使系统框架适应每个模型

适应每个模型所训练的内容，而非强求统一。如果您已为类似模型调优过系统框架，请从该版本开始。

• 编辑格式：使用模型所训练的格式（例如，补丁式或搜索替换式）。不熟悉的格式会消耗额外的推理令牌并导致更多错误。
• Shell或工具：优先使用shell的模型会回退到cat或内联脚本。以shell等效项（如rg）为工具命名，必要时添加：“如果存在某个操作的工具，请优先使用工具而非shell命令（例如，使用read_file而非cat）。”
• 字面性：有些模型家族严格按字面意思遵循指令，而另一些则容忍不精确。有些模型在强调性措辞上会陷入循环。对字面模型，去除大写和强调。
• 触发器：有些模型在被告知何时使用工具之前会忽略它。一个字面的触发器有效：“进行实质性编辑后，使用该工具检查最近编辑的文件是否有linter错误。如果您能轻松弄清楚如何修复，请修复它们。”
• 进度更新：如果模型通过推理摘要报告进度，请将其限制在1-2句话，注明新发现或策略变更，并移除关于轮次中途发送消息的指示。
• 值得针对一行的特殊性：上下文填充时的犹豫或拒绝（“上下文焦虑”）、过早宣布完成、停下来请求许可、以及调用不存在的工具。将每条新增指令与其在对话记录中修复的行为联系起来。模型变更时重新审计，因为一个版本需要的指导对下一个版本可能是多余的。

8. 验证

• 离线：在更改前后运行一组固定的现实任务，最好来自真实使用场景，并按照用户实际书写方式（简短且模糊）。比较任务成功率、令牌数、每任务成本、轮次和工具错误。不要发布会降低成功率的更改。
• 在线（如果有用户）：对每项更改或小捆绑包进行A/B测试。主要指标是每完成任务的成本。护栏指标是任务成功信号、工具调用错误、延迟、每任务轮次和缓存命中率。对于编码代理，一个好的成功信号是代理编写的代码随时间的存活率。通常，检查用户的下一条消息是转而讨论其他事情还是报告问题。
• 仅在成本下降且没有任何护栏指标的退化超出噪音水平时发布。记录无效结果。

什么应该直接更改，什么应该提出建议

• 直接更改（各自单独可回滚提交）：令牌和缓存遥测、确定性序列化和工具顺序、将易变内容移出缓存前缀、显式缓存断点、将大型输出写入文件而非截断、传递回被丢弃的推理项、以及修复重复出现的工具错误。
• 置于标志后更改以便测试：系统提示编辑、工具卸载、输出格式更改、压缩更改和子代理提示。
• 仅提出建议：关于运行哪些模型、路由、推理努力默认值、或任务在代理间如何分配的更改。

陷阱

• 要求模型使用更少的令牌或做得更少。
• 截断工具输出。
• 为节省输入令牌而丢弃推理项。
• 将易变内容放在缓存前缀中，或工具顺序在请求间变化。
• 卸载模型在第一轮就需要或在缺失时会尝试调用的工具。
• 强调性过强的提示（MUST，NEVER，IMPORTANT，全大写），尤其对于字面模型。
• 强制使用比模型训练时更简洁的输出格式。更少的输出令牌可能意味着思考减少和结果变差。
• 优化原始令牌数而非成本，按请求而非按任务优化，或使用评估而非真实使用场景。
• 在对话中途切换模型以节省成本。
• 添加成为瓶颈的协调层。

报告请包含

1. 系统框架图与基线：按来源×计费类型划分的成本，并标出最大的来源。
2. 已排序的更改列表：层级、更改内容、预估节省及估算方式、质量风险、如何验证、以及如何回滚。
3. 您所做的更改，包括系统提示差异，对每一行标注保留、重写、删除或移动的原因。
4. 用于已标记更改的测试计划。
5. 缺口：您无法找到或测量的任何内容。