Pi Agent 的 Token 成本控制：核心是 Prompt Cache 前缀稳定性

1. Pi Agent 长会话为什么越跑越贵：从 Deferred Tools 加载顺序说起

Pi Agent 这类 Coding Agent 和普通 LLM 应用在成本结构上有一个本质差异：每一轮对话都要把整个对话历史重新发一遍。系统提示词、工具定义、全部消息，一个不落。一个跑了 30 轮的会话，累计发送的 prompt token 是单轮的几十倍。所以「降低成本」的核心不是让模型少说话，而是让那些重复发送的部分尽可能命中 Prompt Cache。

Prompt Cache 的匹配规则是前缀匹配：请求的前 N 个 token 必须和缓存内容完全一致才能命中。而工具定义恰好位于请求的最前面——系统提示词之后、消息之前。这就埋下了一个隐患：如果对话进行到第 10 轮时，某个技能被加载、或某个扩展动态注册了一个新工具，你把这个新工具追加进工具定义列表，请求前缀就变了。前 10 轮辛苦累积的整个缓存前缀——系统提示词 + 工具定义 + 10 轮历史——全部作废，第 11 轮要按全价重新发送并重新写入缓存。对一个已经有 10 万 token 历史的会话，这一次「新增工具」的代价就是 10 万 token 的全价重新计费。

我试过在一个 15 轮左右的会话里手动加了个工具，页脚的成本数字直接跳了一截，当时还以为是模型涨价了。后来翻源码才明白，问题出在工具定义的加载顺序上。

Pi 的解法叫 Deferred Tools：把中途新增的工具放进 transcript，而不是前缀。transcript 是追加式的，在消息历史末尾追加内容不会破坏前面的缓存前缀。于是「新增一个工具」的代价从「击穿 10 万 token 前缀」降到「在 transcript 末尾多几百 token」。

这篇文章会从 Deferred Tools 的加载顺序和系统提示词拼接两个角度，拆解前缀稳定性设计，给出可复制的缓存命中诊断脚本与前缀对齐配置模板，并演示验证缓存命中率提升的对比步骤。适合正在用 Pi Agent 跑长会话、发现 Token 账单不对劲的开发者。

先搞清楚钱花在哪。Pi 的 Usage 类型把每次请求的 Token 分成四个计费桶，单价差异极大：

关键推论：一个长会话里绝大部分 Token 是重复发送的 prompt。如果这些 token 全部落在 input 桶，成本是落在 cacheRead 桶的约 10 倍。所以 Prompt Cache 命中率是压倒性的第一优先级，其他手段（压缩、截断、模型路由）都是次要的。

Pi 的 TUI 页脚专门显示这四个桶的实时数据，其中 CH 就是缓存命中率：

if (usageTotals.input) statsParts.push(`↑${formatTokens(usageTotals.input)}`); if (usageTotals.output) statsParts.push(`↓${formatTokens(usageTotals.output)}`); if (usageTotals.cacheRead) statsParts.push(`R${formatTokens(usageTotals.cacheRead)}`); if (usageTotals.cacheWrite) statsParts.push(`W${formatTokens(usageTotals.cacheWrite)}`); if ((usageTotals.cacheRead > 0 || usageTotals.cacheWrite > 0) && latestCacheHitRate !== undefined) { statsParts.push(`CH${latestCacheHitRate.toFixed(1)}%`); }

CH 被放在页脚这个「始终可见」的位置，而不是藏在某个 /stats 命令里，是一个明确的设计表态：缓存命中率是用户需要持续关注的一等指标。你如果只盯着 input 和 output 两个数字，很容易忽略掉真正的大头——那些本该命中却全价重发的 prompt token。

2. TaoToken 前置：把 Base URL、Key、Model ID 三件套配稳

要让上面的缓存机制真正生效，第一步是把请求稳定地打到支持 Prompt Cache 的端点上。这里用 TaoToken 做接入示例，它的 API 地址是https://taotoken.net/api，兼容 Anthropic 和 OpenAI 两种消息格式，Pi Agent 里可以直接配。

配置的核心是三件套：Base URL、API Key、Model ID。三者缺一不可，而且 Model ID 必须和端点实际支持的模型名完全一致，否则请求会被拒或者静默降级到不支持缓存的模型上——后者更麻烦，因为你看不到报错，只会发现 CH 一直是 0。

先拿 Key。打开https://taotoken.net/api-keys，创建一个新 Key，复制出来。注意 Key 只在创建时完整显示一次，关掉页面就看不到了，建议直接存进环境变量而不是硬编码进配置文件。

export TAOTOKEN_API_KEY="sk-你的key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"

然后是 Model ID。不同 Provider 的模型命名不一样，Anthropic 格式下常见的是claude-sonnet-4-5、claude-opus-4-5这类，OpenAI 格式下是gpt-4o、gpt-4o-mini这类。你可以在https://taotoken.net/models查到当前可用的完整列表。选模型时有个原则：如果你要跑长会话，优先选支持 Prompt Cache 的模型，Haiku 系列和 4.5 以前的 Claude 对 tool_reference 的支持有限，Deferred Tools 的优化在它们身上会退化成普通模式。

Pi Agent 的配置文件通常在~/.pi/config.json或项目根目录的.pi/config.json。一个最小可用的配置长这样：

{ "provider": { "type": "anthropic-messages", "baseUrl": "https://taotoken.net/api", "apiKey": "${TAOTOKEN_API_KEY}", "model": "claude-sonnet-4-5" }, "cacheRetention": "short", "sessionAffinity": true }

这里cacheRetention设成short是默认值，用 Provider 的标准缓存 TTL（Anthropic 默认 5 分钟）。如果你经常「边想边做、离开几十分钟再回来」，可以改成long，Anthropic 会用cache_control.ttl: "1h"，OpenAI 会用prompt_cache_retention: "24h"，用更高的缓存写入费换取跨长时间间隔的命中。但要注意，long需要 Provider 侧确认支持，很多第三方代理不接受 ttl 字段，盲目发送会导致整个请求被拒。Pi 里有个supportsLongCacheRetention的 compat 字段做能力探测，默认关闭、白名单开启。

sessionAffinity打开后，Pi 会在请求头里带上会话亲和性标识，让同一会话的请求尽量落到持有缓存的那个后端节点上。Prompt Cache 是存在 Provider 后端某个具体节点上的，如果第 11 轮请求被负载均衡路由到另一个节点，即便前缀完全一致也会 miss。这个 header 的格式有三种（openai / openai-nosession / openrouter），Pi 会根据 baseUrl 自动探测。

配好之后，先别急着跑长会话。用一次简单的请求验证三件套是否生效：

curl -s https://taotoken.net/api/v1/messages \ -H "x-api-key: $TAOTOKEN_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-4-5", "max_tokens": 64, "messages": [{"role": "user", "content": "ping"}] }'

如果返回里有正常的 content 字段，说明 Base URL 和 Key 没问题。如果返回 401，检查 Key 是否复制完整、有没有多余空格。如果返回 404 或 model not found，检查 Model ID 拼写。

3. 可复制配置：前缀对齐模板与缓存断点放置

配置能跑通只是第一步，真正决定缓存命中率的是前缀对齐。这一节给出可以直接复制的配置模板，覆盖 Anthropic 和 OpenAI 两种格式。

Anthropic 的 Prompt Cache 需要显式标记断点（cache_control），Pi 在三个位置放置断点，覆盖「每轮都重复发送」的三大块内容。

断点一：系统提示词。OAuth 场景下还会多一个前置 block（Claude Code 身份声明），两个 block 都加缓存标记，保证不管走 API Key 还是订阅 OAuth，系统提示词都被缓存。

} else if (context.systemPrompt) { params.system = [{ type: "text", text: sanitizeSurrogates(context.systemPrompt), ...(cacheControl ? { cache_control: cacheControl } : {}), }]; }

断点二：最后一个工具定义。只在最后一个工具上打标记，而不是每个工具都打——Anthropic 的缓存断点语义是「缓存到这个位置为止的全部前缀」，所以标记最后一个工具就等于缓存了「系统提示词 + 全部工具定义」这整段前缀。断点数量本身有配额限制（Anthropic 最多 4 个），这种「只在段落末尾打一个」的放置方式把配额用在了最有价值的地方。

...(cacheControl && index === tools.length - 1 ? { cache_control: cacheControl } : {}),

断点三：最后一条 user 消息的最后一个 block。这个断点是「滚动」的——每一轮对话，缓存边界都往后推到最新的用户消息/工具结果。效果是：第 N 轮把前 N-1 轮的完整历史写入缓存，第 N+1 轮就能把这段历史整体作为 cacheRead 读回来。这是长会话成本控制的主力机制，会话越长，这个断点带来的节省越大。

if (cacheControl && params.length > 0) { const lastMessage = params[params.length - 1]; if (lastMessage.role === "user") { const lastBlock = lastMessage.content[lastMessage.content.length - 1]; if (lastBlock && (lastBlock.type === "text" || lastBlock.type === "image" || lastBlock.type === "tool_result")) { (lastBlock as any).cache_control = cacheControl; } } }

注意它显式检查了tool_result类型。因为在 Agent 场景里，最后一条 user 角色消息经常是一批工具结果（而非用户手打的文字），如果只处理 text 类型，工具调用密集的轮次就会全部漏掉缓存。这是一个「通用 LLM SDK 容易忽略、但 Agent 场景必须处理」的细节。

OpenAI 的 Prompt Cache 是自动的，不需要断点标记，但需要一个 cache key 来提高路由命中率：

const disableImplicitPromptCache = cacheRetention === "none" && compat.supportsExplicitPromptCacheMode; const params = { model: model.id, input: messages, stream: true, prompt_cache_key: cacheRetention === "none" ? undefined : clampOpenAIPromptCacheKey(options?.sessionId), prompt_cache_retention: getPromptCacheRetention(compat, cacheRetention), prompt_cache_options: disableImplicitPromptCache ? { mode: "explicit" } : undefined, store: false, };

三个细节值得说。prompt_cache_key用 sessionId，同一个 Pi 会话的所有请求共享一个 cache key，让 OpenAI 侧能把它们识别为「同一个不断增长的前缀」。clampOpenAIPromptCacheKey截断到 64 字符，超长 key 会被 API 拒绝，与其让请求整体失败，不如截断——截断后仍然是同一会话内稳定的 key，不影响命中。截断用Array.from(key)按码点而非字节切分，避免把一个 emoji 或中文字符切成半个非法 UTF-8 序列。store: false不让 Provider 侧持久化请求内容，这不是成本优化，而是隐私默认值——用缓存不等于同意存档。

现在把 Deferred Tools 的配置也加上。核心是splitDeferredTools()，它决定哪些工具进前缀、哪些进 transcript：

export function splitDeferredTools( context: Context, enabled: boolean, normalizeName: ToolNameNormalizer = identityToolName, ): { immediate: Tool[]; deferred: Map<string, Tool> } { const uniqueTools = new Map<string, Tool>(); for (const tool of context.tools ?? []) uniqueTools.set(normalizeName(tool.name), tool); if (!enabled) return { immediate: [...uniqueTools.values()], deferred: new Map() }; const deferredNames = new Set<string>(); const usedNames = new Set<string>(); for (const message of context.messages) { if (message.role === "assistant") { for (const block of message.content) { if (block.type === "toolCall") usedNames.add(normalizeName(block.name)); } } else if (message.role === "toolResult") { for (const name of message.addedToolNames ?? []) { const normalizedName = normalizeName(name); if (!usedNames.has(normalizedName)) deferredNames.add(normalizedName); } } } const immediate: Tool[] = []; const deferred = new Map<string, Tool>(); for (const [name, tool] of uniqueTools) { if (deferredNames.has(name)) deferred.set(name, tool); else immediate.push(tool); } return { immediate, deferred }; }

toolResult.addedToolNames是关键数据来源。当某次工具调用（比如加载一个技能）导致新工具被注册时，这个工具结果消息会记录「我新增了哪些工具」。这些「中途新增」的工具被归入 deferred，不进入工具定义前缀，而是序列化到 transcript 里（Anthropic 用tool_referenceblock，OpenAI 用tool_search_outputitem），并带上defer_loading: true。

usedNames的作用是：如果一个工具已经被实际调用过（toolCall 出现在 assistant 消息里），说明它的定义已经稳定存在于某个位置，就不再需要 defer 处理了，避免对已稳定的工具做无意义的搬移。

还有一个兜底逻辑不能少：

let immediateTools = toolPlacement.immediate; let deferredTools = [...toolPlacement.deferred.values()]; if (immediateTools.length === 0 && deferredTools.length > 0) { immediateTools = deferredTools; deferredTools = []; }

如果所有工具都被判为 deferred（极端情况：这个会话的全部工具都是中途加载的），会把它们全部提回 immediate——因为「工具定义列表为空但 transcript 里有工具引用」对多数 Provider 是非法请求。优化不能以破坏正确性为代价。

能力探测也很保守：

function defaultSupportsToolReferences(model: Model<"anthropic-messages">): boolean { if (model.provider !== "anthropic" || model.id.includes("haiku")) return false; const version = model.id.match(/^claude-(?:opus|sonnet|fable)-(\d+)(?:-(\d+))?(?:-|$)/); if (!version) return false; const major = Number(version[1]); const minor = version[2] && version[2].length < 8 ? Number(version[2]) : 0; return major > 4 || (major === 4 && minor >= 5); }

默认只对「第一方 Anthropic、非 Haiku、Claude 4.5 及以上」启用。Haiku 会拒绝客户端发来的tool_referenceblock，4.5 以前的模型不支持 tool search。默认关闭、白名单开启：一个能省钱但可能让请求失败的优化，宁可少省一点也不能让用户的请求报错。

4. 验证请求：缓存命中诊断脚本与对比步骤

配置写好了，怎么知道缓存真的命中了？这一节给出一个可复制的诊断脚本，以及提升前后的对比步骤。

先写诊断脚本。核心思路是解析每一轮请求的 usage 数据，算出「本应命中却没命中」的 token 量。Pi 的cache-stats.ts里定义了一个 miss 的计算方式：

const missedTokens = Math.min(prev.promptTokens, promptTokens) - usage.cacheRead; if (missedTokens <= NOISE_FLOOR_TOKENS) return undefined; // NOISE_FLOOR_TOKENS = 1024

定义是：上一轮请求的 prompt 里已经有的内容（理论上这轮应该整段从缓存读），实际却没从缓存读到的部分。取min(prev.promptTokens, promptTokens)是因为这轮 prompt 可能比上轮短（压缩后），只能按两者较小值来算「本应命中的上限」。

NOISE_FLOOR_TOKENS = 1024的噪声地板很重要：缓存断点有粒度（block 级别），每轮总会有几百 token 落在断点之外，这是机制固有的，不算浪费。只有超过 1024 token 的 miss 才计入，避免每一轮都报一个无意义的「你浪费了 200 token」警告。

成本计算不用静态定价表，而是从这条消息自己的 usage.cost 反推实际单价：

const paidTokens = usage.input + usage.cacheWrite; const paidPerToken = paidTokens > 0 ? (usage.cost.input + usage.cost.cacheWrite) / paidTokens : 0; const readPerToken = usage.cacheRead > 0 ? usage.cost.cacheRead / usage.cacheRead : (models.getModel(message.provider, message.model)?.cost.cacheRead ?? 0) / 1_000_000; return { missedTokens, missedCost: missedTokens * Math.max(0, paidPerToken - readPerToken), ... };

因为 miss 的 token 只可能落在 input 或 cacheWrite 桶里，这条消息的成本明细里就直接包含了它们的真实计费单价（含 cacheWrite 溢价）。这样即便 Provider 有促销折扣、阶梯定价或者定价表过期，算出的「多花了多少钱」依然准确。Math.max(0, ...)保证异常定价数据不会产生负成本。

把这段逻辑包成一个独立脚本，跑在会话日志上：

// cache-diagnose.ts import { readFileSync } from "fs"; interface UsageEntry { type: string; provider: string; model: string; usage: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: { input: number; output: number; cacheRead: number; cacheWrite: number; total: number }; }; } const NOISE_FLOOR_TOKENS = 1024; function diagnose(entries: UsageEntry[]) { let prev: { promptTokens: number; reportedCache: boolean } | undefined; let totalMissed = 0; let totalMissedCost = 0; for (const entry of entries) { if (entry.type === "compaction" || entry.type === "branch_summary") { prev = undefined; continue; } const usage = entry.usage; const promptTokens = usage.input + usage.cacheRead + usage.cacheWrite; if (!prev || promptTokens <= 0 || (usage.cacheRead + usage.cacheWrite === 0 && !prev.reportedCache)) { prev = { promptTokens, reportedCache: usage.cacheRead + usage.cacheWrite > 0 }; continue; } const missedTokens = Math.min(prev.promptTokens, promptTokens) - usage.cacheRead; if (missedTokens > NOISE_FLOOR_TOKENS) { const paidTokens = usage.input + usage.cacheWrite; const paidPerToken = paidTokens > 0 ? (usage.cost.input + usage.cost.cacheWrite) / paidTokens : 0; const readPerToken = usage.cacheRead > 0 ? usage.cost.cacheRead / usage.cacheRead : 0; const missedCost = missedTokens * Math.max(0, paidPerToken - readPerToken); totalMissed += missedTokens; totalMissedCost += missedCost; console.log(`miss: ${missedTokens} tokens, ~$${missedCost.toFixed(4)}`); } prev = { promptTokens, reportedCache: usage.cacheRead + usage.cacheWrite > 0 }; } console.log(`total missed: ${totalMissed} tokens, ~$${totalMissedCost.toFixed(4)}`); } const entries: UsageEntry[] = JSON.parse(readFileSync(process.argv[2], "utf-8")); diagnose(entries);

跑法：

npx tsx cache-diagnose.ts ./session-usage.json

现在做对比验证。第一步，在没开 Deferred Tools 的配置下跑一个 10 轮以上的会话，记录页脚的 CH 值和诊断脚本输出的 total missed。第二步，把splitDeferredTools的 enabled 打开，重跑一个结构类似的会话，再记录一次。

实测下来，在工具调用密集的会话里，开启 Deferred Tools 后 CH 通常能从 60% 左右提升到 85% 以上，total missed 下降一个数量级。提升最明显的场景是「中途加载技能」——不开 Deferred Tools 时，每次加载技能都会击穿整个前缀，诊断脚本会报一个几万 token 的 miss；开启后，这个 miss 会降到几百 token 的噪声级别。

还有一个验证点：会话亲和性。如果你发现 CH 忽高忽低、没有规律，很可能是请求被路由到了不同节点。检查请求头里有没有带上x-session-id或session_id，以及 Provider 是否支持。有些代理不接受带下划线的session_idheader，会当成非法 header 拒绝，这时需要切到openai-nosession模式，只发x-client-request-id。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

配置和验证过程中最容易撞上的几类报错，逐个拆。

401 Unauthorized。最常见的原因是 Key 没传对。检查三处：环境变量TAOTOKEN_API_KEY是否真的 export 了（echo $TAOTOKEN_API_KEY看有没有值）；配置文件里是${TAOTOKEN_API_KEY}还是硬编码了一个过期 Key；请求头字段名对不对——Anthropic 格式用x-api-key，OpenAI 格式用Authorization: Bearer。如果三处都对还是 401，去https://taotoken.net/api-keys确认这个 Key 还在有效期内、没有被禁用。

local proxy failed。这个报错通常出现在你本地起了代理层（比如某些工具会自己起一个 localhost 转发）但代理没起来或者端口被占。先确认代理进程在不在，再确认端口没被别的程序占用。如果你没主动起代理，检查配置里有没有残留的baseUrl指向http://localhost:xxxx——把 baseUrl 改回https://taotoken.net/api通常就好了。

reading choices 相关报错。这类报错一般出现在解析响应时，choices字段读不到。原因通常是请求打到了 OpenAI 格式的端点，但配置里写的是 Anthropic 格式（或反过来）。Anthropic 格式的响应是content数组，OpenAI 格式才是choices数组。检查配置里的provider.type和实际端点是否匹配。另一个可能是 Model ID 写错了，端点返回了一个错误结构，解析器按正常结构去读choices自然读不到。

OAuth 相关报错。如果你走的是订阅 OAuth 而不是 API Key，注意 OAuth 场景下系统提示词会多一个前置 block（Claude Code 身份声明）。如果这个 block 缺失或者格式不对，请求会被拒。另外 OAuth 的 token 有刷新机制，长时间会话中途 token 过期也会报错，重新走一次授权流程即可。用 API Key 的话不会有这个问题，长会话更稳。

CH 一直是 0。这个不是报错但比报错更隐蔽。可能的原因有三个：Model ID 指向了一个不支持 Prompt Cache 的模型（比如 Haiku 系列）；cacheRetention被设成了none；或者 Provider 根本不报告缓存数据。第三种情况下，Pi 的reportedCache粘性标记会起作用——只要这段扫描区间内曾经有任何一轮报告过缓存活动，就认为这个 Provider 支持缓存，此后出现的零缓存轮次才被当作真实 miss。如果从头到尾都没报告过，诊断脚本不会产生噪声告警，但你也拿不到命中率数据，这时需要换一个支持缓存的模型或端点。

miss 提示太频繁。Pi 的 UI 提示有三层过滤：双阈值（missedTokens >= 20000 或 missedCost >= $0.1 才提示）、归因只陈述可观测事实（切换了模型、或者空闲超过缓存 TTL）、可关闭（getShowCacheMissNotices()设置项）。如果你觉得还是太吵，先检查是不是真的在频繁切模型或长时间空闲——这两个是真实成本，关掉提示不等于成本消失。如果确认是误报，再考虑调高阈值。

排查时有个通用原则：先看页脚的四个桶数字，再看诊断脚本的 miss 明细，最后才去翻源码。大部分问题在第一步就能定位——input 桶异常大就是缓存没命中，cacheWrite 桶异常大就是缓存被反复击穿，output 桶异常大就是思考等级设太高。

6. 把前缀稳定性变成默认习惯

回到最开始那个问题：Pi Agent 长会话为什么越跑越贵。答案不在「模型说了太多话」，而在「重复发送的 prompt 没有命中缓存」。而缓存没命中的头号原因，是前缀被中途新增的工具、动态拼接的系统提示词、或者不稳定的会话标识给破坏了。

三条贯穿性的原则，可以直接搬进你的日常配置习惯。

成本优化的重心在「前缀稳定性」，不在「少发内容」。Deferred Tools 这个机制不减少任何一个 token 的发送量，它做的只是「把新增内容放到不破坏缓存前缀的位置」，收益却可能是几万 token 的全价重新计费。理解「prompt cache 是前缀匹配」这一个事实，比任何压缩技巧都更能降低成本。你可以在https://taotoken.net/api的接入文档里找到更多关于缓存断点放置的说明。

优化永不以正确性为代价。Deferred Tools 在能力探测上采用默认关闭加白名单（Haiku 会拒绝 tool_reference、旧模型不支持 tool search），在 immediate 为空时无条件回退，supportsLongCacheRetention在第三方代理上可关闭。每一个省钱机制都配了一条「这个 Provider 不支持时怎么办」的退路。你配cacheRetention: "long"之前，先确认端点接不接受 ttl 字段，不接受就老老实实用short。

成本必须可见，但不能变成噪声。这是cache-stats.ts整个模块的设计张力：既要让用户知道钱花在哪（20k token / $0.1 双阈值触发提示、压缩自身成本明示、切模型代价明示），又要坚决避免误报（1024 噪声地板、压缩豁免、reportedCache 粘性标记、只陈述可观测归因）。一个天天喊「你浪费了 200 token」的提示，最终会被用户关掉，从此真正的重大浪费也一起看不见了。告警的价值取决于它的信噪比，不取决于它的完备性。

如果你要跑长期编码任务或者多 Agent 协作，建议直接上 Coding Plan，把会话亲和性和缓存保留策略一次性配好，省得每开一个新会话都要重新调。配好之后，把诊断脚本挂到会话日志上定期跑一次，CH 低于 80% 就去看 miss 明细，基本能覆盖绝大多数成本异常。