缓存预热器 yoggu/dsh-cache-warmer

dsh-cache-warmer

用环形消耗图估算 缓存时间，观察缓存 token 用量，并提供可选的成本感知预热。设置只放在 Plugins → Cache warmer，不在全局 Settings 弹窗里。界面支持英文和中文；弹窗里是复选框，设置页是原生风格开关。

环境要求与安装

当前实现需要兼容的 Harness 运行时，以及它标准的 LLM、会话投影、凭证和存储服务，还需要随附的 pi-ai 适配器。原生预热按 llm-pi-ai 0.2.0-rc.2 / pi-ai 0.99.1 审核；适配器或序列化器版本不同会直接失败关闭，直到重新审核。历史的有界 OpenRouter 路径还会额外校验它的目录快照。这个插件没有单独的 pi-ai 依赖需要升级。

安装 GitHub 上最新的带标签 release：

dsh plugin --profile web add 'https://github.com/yoggu/dsh-cache-warmer.git#v0.1.7'

或者链接本地 checkout：

git clone --branch v0.1.7 --depth 1 https://github.com/yoggu/dsh-cache-warmer.git
cd dsh-cache-warmer
dsh plugin --profile web add "link:$(pwd)"

安装期间请保留链接的 checkout。替换已安装的包版本后重启 DSH，然后刷新浏览器。更早的标签不包含当前全部防护措施。预热默认 关闭，需要一次新的真实模型请求、显式启用模型并给出预估生命周期、以及每个会话单独选择加入。更新或安装插件本身不会发起预热请求。

当前 checkout 走的是所属的 llm-pi-ai 原生服务商路由，包括 API key 和 OAuth 认证。兼容的文本聊天模型无论服务商叫什么都能预热；非 pi-ai 适配器只能观察。v0.1.6 及更早版本没有这个原生服务商扩展。不需要可选的 modelPricing 服务。插件复用原生凭证解析和 OAuth 刷新，不会把凭证复制到自己的文件里。

Codex / 已登录的 Responses： 这些路由不保证服务端有输出上限。要在插件设置里单独开启 Allow best-effort warming (Codex / OAuth)，同时还要配置模型策略和每个会话的同意。这项默认关闭，历史保存的策略也一样。客户端取消不保证隐藏推理或服务商生成会停止，成本估算也不是支出或配额上限。

设置与生命周期

三个基础设置仍然是 autoWarmNewChats（false）、activeMinutes（60）和 idleMinutes（30）。设为 0 就关闭对应阶段。两个截止时间都从 最后一次真实模型请求 起算，不是从刷新或工具结束的时间起算。已有会话逐个选择加入。子会话 / 子代理会话不会自动预热。
按 30 分钟估算缓存生命周期，会在第 27 分钟安排一次决策。空闲截止时间设为 30 分钟时，最多只发送一次刷新（且仅在值得刷新时）；一旦命中成功，估算的过期时间可推迟到第 57 分钟。截止时间控制的是请求，不是服务商的驱逐。窗口更长时可能允许更多次刷新；不存在人为设定的三次尝试上限。

已知生命周期：在 min(0.9 × lifetime, lifetime − 10 seconds) 处决策。定时器会重新检查截止时间、当前上下文、权限、路由身份和成本收益。新请求会抢占已过时的工作。模型/设置/账户路由变更、替换/压缩、取消和销毁都会让已捕获的请求失效。预热永远不会延长活动截止时间。

模型与缓存策略

Plugins → Cache warmer → Model cache policies 会自动列出所有已注册 Harness 服务商路由所声明的模型，包括 Codex 账户、pi-ai 服务商和 DeepSeek。可按模型/服务商搜索，或按服务商筛选；更改服务商配置后刷新目录。无需手动填写模型 ID。发现流程列出的是声明的模型，并不证明已通过认证或支持缓存。服务商不可用不会清除已保存的覆盖项。各服务商共享 5 秒的发现截止时间；浏览器设置和模型列表读取有 10 秒超时，并提供 Retry，响应体卡住时同样适用。刷新失败会保留上一次的模型列表和未保存的设置，而不是让页面一直加载。

不假设任何服务商上报的生命周期，也不假设 Codex 内置的生命周期。每个模型都有：

- Enable warming：允许为该模型预热；关闭后保留其生命周期。按聊天单独选择加入仍然生效。
- Estimated cache lifetime (minutes)：1 到 10080 之间的整数。留空表示未知，因此即使已启用也不会发送自动预热。
- Reset to default：恢复为未知生命周期并关闭预热。历史 Codex 规则永远不会启用传输。
- 传输状态：不支持的模型仍会显示在列表中，并附上说明，而不是直接消失。

modelPolicies 中只保存你精确指定的服务商/模型覆盖项，不保存发现到的目录。重复的配对会被拒绝；最多 100 条覆盖项。自定义规则会替换默认规则，包括留空或关闭的值。已禁用的模型仍可显示估算倒计时和观测到的缓存命中，但不会发送刷新。仅观测的路由（包括原生预热不可用或未同意时的 Codex）即使没有上报的保留模式，也会显示显式配置的生命周期；倒计时需要观测到一次缓存命中，且不会启用后台预热。

更改生命周期不会改变服务商请求的保留策略，也不保证过期；所有值都只是本地规划假设。服务商侧缓存被禁用（cacheRetention: none）仍会阻止调度。保存设置会取消已捕获的目标；需要出现新的真实请求，预热才会恢复。
兼容性：已有的 enabled: false 规则保留其显示的生存期，并保持禁用。旧字段 useCodexDefaults 为兼容设置仍可接受，但不再授予账户路由预热。旧的 shortMinutes/longMinutes 行会保守迁移：两个已知值取较小的那个；只要有一个未知，统一后的值就保持未知。保存时写入单个 cacheMinutes 字段。同一行里混用新旧生存期字段会被拒绝。

保存的覆盖示例（仅为说明性假设，不是 OpenRouter TTL 声明）：

{
"modelPolicies": [
{
"provider": "openrouter",
"model": "~deepseek/deepseek-v4-flash-latest",
"enabled": true,
"cacheMinutes": 5
}
]
}

生存期不能新增刷新传输通道。准入使用实际注册的 llm-pi-ai 适配器及其精确配置的原生模型，而不是按服务商名称的允许列表。兼容的原生协议可以预热；不支持的协议、非聊天模型和非 pi-ai 路由仍然可见，并附带原因。刷新仍然需要缓存证据、已知价格、节省阈值和未过期的活动窗口。Bedrock 目前仍不可用，因为它的原生 SDK 无法通过这个接缝禁用重试。

经济性（独立于预热权限）

已发布的标价假设使用 calculateCost，来自拥有该功能的 @deepseek-ai/dsh-llm-pi-ai 适配器自己审阅过的 pi-ai 副本，每个假设都使用全新的 usage 和 cost 对象。不依赖 modelPricing，价格估算也绝不会新增预热传输通道。原生准入在发送前会重新检查实际适配器、快照和精确模型；缺失、未知、变更、格式错误或非有限的开销一律按失败关闭处理。自定义端点/协议覆盖不会仅因为模型 ID 与目录匹配就继承已验证的计费。Anthropic 长保留写入按一小时写入费率计价；未报告的层级在写入记账时保守地按长保留处理。没有已知价格的自定义模型不会被视为免费。每次决策使用当前捕获请求的输入，而不是累积的会话用量。缓存读取/写入计数与未缓存输入互不重叠；原生价格层级由 pi-ai 处理。

expected savings = continuation probability × avoided miss cost − refresh cost

默认值使用 Pi 的概率假设：100% 活跃、15% 空闲，最低预期净收益为 $0.05。Plugins → Cache warmer → Advanced → Cost checks 暴露以下项：

- minExpectedBenefitUsd —— 扣除刷新成本后的最低预期净收益；默认 0.05，接受从 0 到 1000 USD 的有限数字。这不是支出预算。
- idleContinuationPercent —— 空闲时继续的假定概率；默认 15，接受从 0 到 100 的整数百分比。这是固定的规划假设，不是学习到的预测。设为零会禁用空闲预热；活跃假设仍为 100%。
调低最小值或调高空闲概率，都会增加预热和用量。这些设置改变的是「刷新是否值得」，而不是缓存生命周期或决策时机。省略这些设置的旧客户端会保留当前值。保存会取消已捕获的目标，并要求重新发起一次真实请求，与其他预热设置一样。

保守地只计入观测到的可复用 token，其余部分按未缓存输入费率计费，并预留输出成本。缺少价格或证据仍会阻止预热，即使阈值为零也一样。便宜的 OpenRouter DeepSeek Flash 上下文通常过不了默认阈值，这是有意为之。

成本预测是 API 等价的标价估算，不是账单，也不能证明配额用量减少。原生刷新会预留一份规划输出额度，外加一段额外未缓存输入，用于短的 keepalive 后缀，从而保留捕获的消息前缀。服务端限定的序列化器会校验其最终输出上限；Codex 以及可能的 OAuth Responses 仅由客户端限定。它们的输出额度是启发式估算，不是保证的最大账单。没有可信用量记录的已中止请求仍不计价。历史上的离线 OpenRouter 传输预留八个输出 token，并保留前缀，不带后缀。

服务商行为

原生 pi-ai 路由

插件会解析实际拥有所选路由的适配器，复用其不可变的原生配置档/模型及其现有认证上下文，并构建一个隔离的刷新能力。这样能保留原生重放、工具 schema、推理控制和会话亲和性，同时不执行工具、不修改转录。影响缓存的推理或工具选择设置不会被悄悄改写以求更小的请求。如果某个请求所需的原生思考预算放不进刷新边界，则报告为不可用。适配器内部实现和序列化器会按版本审查；出现偏差就失败关闭。附件和服务商侧计费工具不会被悄悄转成普通文本刷新。

Codex 使用 SSE，以避免共享 WebSocket 续传状态。它请求一个极小的回复，并有客户端截止时间/输出保护，但其后端不提供有保证的输出 token 上限。它单独的最佳努力同意是强制的。非 pi-ai 的 deepseek-official 和已退役的自定义账户适配器仍只做观测；通过 llm-pi-ai 配置的等价模型可以按其原生协议被接纳。

OpenRouter

OpenRouter 采用原生服务商的精确准入机制，并强制加上路由防护：只允许受支持的输出参数，禁止回退与请求费用，价格上限取自目录。经过审查的原生 Chat Completions 序列化器可以表达这些控制项；OpenRouter Anthropic、Responses 以及其他序列化器仍只做观察，直到有等价的路由接缝经过审查。已配置的端点和请求头来自拥有它的适配器，绝不使用猜测出来的配置。动态路由别名，例如 auto、openrouter/free 和 openrouter/fusion，以及未知的计费方式和未经审查的序列化器能力，一律失败关闭。具体、经目录核实的免费模型与动态别名是两回事。历史上那套有边界的 OpenRouter 实现仍然保留，用于兼容和离线验证；它固定的目录并不授权无关的原生服务商。

每条原生路由的过期时间默认都是 unknown。启用模型并配置一个预估生命周期，才能进行成本感知的调度；每个会话仍需单独选择加入。原生刷新有十秒的客户端截止时间和 1 MiB 的序列化请求上限。输出上限取决于协议，并在原生序列化之后检查；仅客户端的路由需要额外同意。只支持文本和工具上下文；附件请求会被拒绝，而不是被悄悄改动。不会执行任何工具调用。

路由要求提供参数，禁止回退与请求费用，并根据所选模型已安装目录中跨档位的价格，推导出提示词和补全的价格上限。它不再对每个模型强加旧的 $1/M 提示词和 $2/M 补全上限。这些是传输层的护栏，不是面向用户的预算，也不是计费保证。缺少缓存证据或价格，或者预期节省不足，仍然会阻止预热。

此前获得授权的合成 DeepSeek 请求只证明了缓存复用，并未证明留存，也没有端到端的定时实况结果。通用传输用回环请求验证，而不是付费推理。服务商缓存本身可以在没有自动预热的情况下工作。

计费与持久化

每个会话的选择加入和累计预热用量存放在插件存储的不同域中。弹窗显示预热尝试次数，以及单独核算的 API 等价成本；没有用量记录的不完整或中止请求会标记为未计价。预热用量不会计入普通转录派生的 token 成本总计。本插件不持久化请求体、提示词和凭据。重启或重新加载后，需要有一次新的真实请求，自动预热才会恢复；历史证据仍可能显示预估倒计时。凭据或账号更新也会使已捕获的请求和缓存证据失效；OAuth 记录轮换被保守地一并纳入。

请求捕获与诊断

捕获需要精确的 AgentLoop 请求身份，光有匹配的会话 id 或消息结构还不够。链接安装可能带有第二份 Harness LLM 对等依赖，它的请求标记注册表与正在运行的主机相互独立。warmer 从拥有注入 LlmRuntime 的模块解析公共标记（用 instanceof 校验），并以正在运行的可执行文件作为回退解析锚点。如果在不常见的嵌入式布局中无法解析出拥有者，warming 会以失败关闭，并给出明确的诊断信息。

弹窗左上角显示 Cache warming，右上角显示简短的 warming 状态：Scheduled、Warming、Waiting、Skipped、Stopped、Disabled 或 Unavailable，下方跟一句简短说明。金额估算仍单独占行，不追加到状态后面。Keep cache warm 复选框位于所有信息行之上。Cache lifetime 显示生命周期假设；Time remaining 显示预估倒计时。冗余的 active/idle 阶段行已省略。Scheduled 表示确实存在定时器，且当前检查通过；发送前会再检查一次条件。仅有值得做的估算或倒计时，并不代表已安排刷新。

弹窗区分「快照缺失」与「请求已捕获但仍在进行中」。认证状态端点还会报告 warmingState、requestCaptured、requestCompleted、lastRequestCompletedAt 和 nextRefreshAt。已完成的请求可以正确地产生经济性跳过，尤其是在空闲时。

Verification

npm test 覆盖自动模型发现、部分失败/超时、双语可搜索设置、按模型启用、独立经济性、仅观察路由、27/30 分钟时间线、生命周期取消、失败、重复刷新、持久化、不执行 transcript/tool，以及使用实际发布的 OpenRouter 和原生 Completions、Responses、Azure、Codex、Anthropic、Google Generative/Vertex、Mistral 和 pi-messages 序列化器的回环线上测试。原生测试覆盖原始影响缓存的控件、凭据权威、可重试错误、输出限制和停滞流截止时间。合成凭据仅限回环使用；测试套件不发送付费请求。离线测试无法证实实时计划缓存收益，需要另行获得服务商授权的测试。
集成测试需要被测 Harness 依赖，以及经过审查的 pi-ai 适配器；不需要自定义 Codex 账号适配器。开发锁文件和根目录的 npm override 把 pi-ai 固定为 0.99.1，保证独立测试可复现。这个 checkout 级别的 override 不会升级或替换正在运行的 Harness 所拥有的适配器；运行时准入仍会检查其实际版本。跨 peer 身份测试走真实的 Cordis 代理和 prepared-call waterfall；当测试安装被去重、无法复现独立 registry 布局时，它们会明确报告跳过。

License

MIT；见 LICENSE。