关于 audit-prompt-caching
用于审计 LLM 请求路径中的提示词与前缀缓存,面向工程师和 Agent。它先检查适用性、遥测、路由、成本及隔离,再决定是否建议改动。
主要功能
- 01划分缓存平面
- 02验证使用遥测
- 03评估前缀稳定性
- 04审计路由与 KV 部署
- 05生成基于证据的报告
适用场景
- 01排查提示词缓存未命中
- 02检查缓存相关成本或延迟变化
- 03审计 Agent 循环与提示词构造
- 04评估 vLLM 或 SGLang 的 KV 复用
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ sernote/ audit-prompt-caching --skill audit-prompt-caching安装后在 Claude Code 中输入/audit-prompt-caching确认已加载。
包含的文件
除 SKILL.md 外,安装时一起下载的参考资料和脚本。
agents/openai.yamlevals/evals.jsontrigger_eval.jsonreferences/agent-tools.mdanthropic.mdazure-openai.mdbedrock.mddeepseek.mdeconomics.mdgemini.mdmastra.mdmechanics.mdminimax.mdmistral.mdmoonshot.mdobservability.mdopenai.mdopenrouter.mdoperational-playbook.mdpredeploy-checklist.mdqwen.mdreport-template.mdrouting-evidence.mdrules.jsonsglang.mdtencent.mduse-cases.mdvercel-ai-sdk.mdvllm.mdxai.md详细介绍
提示词缓存审计
将大模型提示词/前缀缓存未命中视为请求路径工程问题进行诊断: 稳定且可复用的前缀、提供商遥测、缓存感知路由,以及存续时间足够长、可供复用的条目。只有当前缀稳定、足够长、重复出现、可测量且安全时,才值得调整缓存。除非适用性、遥测和信任边界检查有充分依据,否则不要添加缓存控制项、密钥、盐值、提供商固定项、路由提示或扩大缓存共享范围。
适用场景
在重复的提示词前缀可能影响成本、TTFT、预填充延迟或可自托管 KV 复用的大模型调用中使用此技能。典型触发情形:
- 出现
cached_tokens=0、cache_read_input_tokens=0、cache_write_tokens、有写入无读取,或用量字段不明确;GPT-5.6+ 的prompt_cache_options/prompt_cache_breakpoint;或从prompt_cache_retention迁移。 - 缓存对话中途更改工作量或推理设置:逐步设置
reasoning.effort、GPT-6configuration_update、Claude 逐消息设置output_config.effort、切换思考模式。 - 缓存命中率、TTFT、预填充延迟或输入 Token 成本发生变化;长提示词、共享上下文、长时间运行的 Agent 或工具循环相关的大模型成本或速度出现退化;或者报告的命中率不可信。
- 大模型请求结构发生变化,且重复的长提示词、TTFT、缓存 Token 遥测或大模型成本很重要:检查提示词文本、消息顺序、请求构建器、工具、架构、
response_format、提供商 API 接口、模型/路由器设置、Agent 循环或上下文压缩。 - 长系统提示词、工具目录、架构、静态文档、少样本/RAG 上下文、提供商缓存 API,或存在 KV 压力、分词器/聊天模板漂移、缓存盐值或 APC 基准测试(如
vllm bench serve、prefix_repetition和benchmark_prefix_caching.py)的 vLLM/SGLang 多副本 KV 部署。
不适用场景
以下情况不要使用此技能:
- 通用提示词编写、提示词质量编辑,或普通的短提示词编辑,且不涉及重复前缀、TTFT、缓存遥测或大模型成本问题
- 通用 RAG 设计,除非任务涉及重复上下文的放置/可缓存性
- 仅涉及 Token 计数或上下文窗口大小估算
- 仅涉及响应缓存,除非要将其与提示词前缀缓存进行比较
- 非大模型前端/后端性能,或非推理场景下的 Kubernetes 路由
- 缺少用量数据或未明确说明假设的推测性节省成本声明
模式:代码审计(可访问代码仓库)、顾问模式(没有代码库,仅询问缺失的诊断问题)、Agent 审计(工具、MCP、循环、压缩)和部署审计(vLLM/SGLang、Kubernetes、网关、副本)。
vLLM 审计:镜像摘要/版本/SHA、功能是否存在、实际生效的保留策略/来源、KV 组拓扑/几何结构、实际生效的调度器块大小(scheduler_block_size)、哈希算法、种子兼容状态,以及层级类型。保留策略/几何结构不匹配与跨进程哈希不匹配必须分别处理。源码/夜间构建应通过功能检测,而不是猜测最低版本;版本与行为对照表见 references/vllm.md。
缓存平面检查
开始诊断前,说明涉及哪些缓存平面; 同时涉及多个平面很常见,每个平面都需要各自的证据:
gateway_response:在网关或代理处复用响应。provider_prompt:由提供商管理、并体现在用量遥测中的提示词/前缀缓存。engine_kv:在可自托管推理引擎内部复用注意力 KV。external_kv:持久化在推理进程外部或移出该进程的 KV 块。semantic_response:基于相似度复用先前的响应。
不要根据提供商或模型名称、路由或用量字段推断缓存平面,也不要合并不同平面:网关响应缓存命中不等于提供商前缀复用。
将每个涉及的缓存平面都传给 render_audit_report.py --cache-plane,并在审计发现中指出受影响的平面。
使用证据契约
在将命中率视为可用于决策的证据之前,请从 analyze_usage_logs.py --jsonl-normalized 读取规范化事件字段:schema_version、
source_fields(每个规范值来自哪个原始字段)、
accounting_semantics(inclusive、additive、ambiguous)、
denominator_status 和 warnings。
valid:该比率可作为有效证据。ambiguous:封装层语义尚未明确,或没有测量到输入;应将该比率称为不可用于决策,不得声称节省了成本。invalid:适配器不变量遭到违反;请先修正核算方式。
聚合结果采用最差状态(invalid > ambiguous > valid)。
不要另建规范化器,也不要绕过此契约手动计算比率;请扩展现有适配器。路径:references/observability.md。
缓存诊断摘要
报告 applicability、evidence_quality、
prefix_stability、usage_accounting、
routing_locality、economics 和 isolation,每项必须且只能使用一个状态:pass/warning/fail/unknown/not_applicable。
所有未经证实的维度都应保留为 unknown,不要省略,也绝不要将它们汇总成分数、排名或等级。usage_accounting: pass 需要有效的分母;routing_locality: pass 只表示局部性,不代表批准上线。参见 references/report-template.md。
证据边界
稳定前缀方案需要有实际观测到的渲染后载荷,或已确定的请求构造边界。区分稳定指令和工具、有界的半稳定上下文,以及特定于请求的历史记录和用户输入。将顺序描述为已观测到的应用载荷属性;除非有引用的服务提供商证据,否则绝不要将其描述为普遍适用的服务提供商内部序列化顺序。
隔离审查应基于证据并保持被动:检查配置或跟踪记录中可见的缓存键范围、租户和凭证边界,以及脱敏风险。主动进行跨租户探测需要单独授权,不在审查范围内。
项目背景门槛
在判定严重程度或建议修改项目之前,请审查热点路径、重复频率、提示词系列和缓存适用性。
梳理提示词系列、请求构造器、模型/服务提供商路由、Agent 循环、部署路径和使用频率。区分高频重复路径与低频任务、一次性提示词、管理流程、实验,以及没有可共享稳定前缀的系列。针对每项发现,标记其对审查路径是适用、有条件适用还是不适用;只有在代码/配置背景表明缺少哪些证据后,才要求提供遥测数据。
如果某条路由使用频率低、提示词短、大多具有唯一性、主要受输出/工具延迟影响、因隐私而隔离,或没有稳定的长前缀,就应指出提示词缓存并非该路径的合适手段,并从可执行发现中删除通用缓存警告。
适用性门槛
在建议修改提示词缓存之前,请检查:
- 可复用前缀:静态或半静态前缀是否高于服务提供商/模型的阈值,或足够大以便进行自托管 KV 复用?
- 重复频率:同一前缀在过期或被逐出前是否会被重复使用足够多次?
- 精确稳定性:目标请求中的工具、架构、指令、示例、媒体、文档和前置消息是否在字节/Token 层面保持稳定?
- 遥测数据:是否能获取缓存读写字段、输入/输出 Token、TTFT/预填充耗时、路由/模型和提示词版本?
- 成本构成:输入预填充成本是否显著,还是输出 Token、解码时间和工具占主导?
- 安全边界:扩大复用范围是否会违反租户、隐私、数据驻留、ZDR 或侧信道要求?
如果未通过门槛,请说明缓存目前为何并非合适的手段,并建议进行测量、重构提示词、修复路由或采用其他优化方式。
这些门槛用于约束严重程度和拟议变更,不影响记录源机制。渲染器不可用会限制缓存影响声明:应分别说明已证实的上游行为和缺失的下游环节。
语言匹配规则
默认使用用户的语言作答。准确保留提供商/API 字段名,例如 cached_tokens、cache_write_tokens、prompt_cache_options、prompt_cache_breakpoint、configuration_update、output_config.effort、cache_control、cachePoint、TTFT 和 prompt_cache_key,但用用户的语言解释这些字段。
Agent 优先的输出契约
选择能够回答请求的最精简契约:
- 快速分诊:推测提供商/引擎、涉及的层面、最可能的阻塞因素、接下来需要的证据、一条安全的后续命令。
- 代码审计发现:先给出决策摘要,然后列出文件和行号层面的发现、通过的检查,以及验证命令。
- 提供商迁移风险:在建议修改前,对比缓存语义、用量字段、前缀布局、路由和成本假设。
- Agent 循环审计:稳定的工具、早期消息、逐步前缀哈希、缓存字段、输出令牌、压缩事件。
- 部署审计:对于 vLLM、SGLang、Kubernetes、网关、自动扩缩容或多副本推理,将路由局部性和 KV 预算作为首要原因分析。
- 不值得缓存:当适用性门槛未通过,或输出解码、外部工具、速率限制或隐私隔离才是主要因素时,说明应改为调整什么,以及需要哪些证据才能重新评估提示缓存。
对于项目变更问题,如果单一答案准确,应首先回答 Change needed: yes、Change needed: no 或 Change needed: unknown until <specific evidence>。如果涉及的变更类型不同,应拆分为 Measurement change、Prompt behavior change、Provider/routing change、Confidence、Do first 和 Do not do yet。
证据要求是提出变更建议的前提。仅针对性能、容量和成本结果,如果当前配置满足其既定 SLO、目标和预算,则回答 Change needed: no;这不构成这些维度上的发现、警告或前置条件。结果良好不能免除隔离、隐私/ZDR、数据驻留、提供商正确性或明确合规审查方面的要求。如果基于声称结果良好而回答无需变更,但缺少结果目标或证据,则回答 Change needed: unknown until <specific evidence>,而非 no;这不会覆盖适用性门槛或 Not worth caching 的决定性否定契约。缺陷需要有测得的结果差距,而非仅凭实现名称认定。引用的政策、清单、标准或工单属于意图声明,而非测量结果;对于非结果类或安全规则,不要将其忽略:应升级处理或核实其权威性和依据,并且只有在技术上适当时,才将基于实现名称的规则改述为结果条件。不要仅为满足基于实现名称的规则而凭空设计金丝雀、试点、影子流量或测量活动。对于拟议的路由或副本/KV 拓扑变更,加载 references/mechanics.md 并应用路由结果门槛。
有证据支撑的发现
每条可执行的发现都应说明不确定性,并提供可证伪的验证路径:
source | severity | provider/engine | issue | evidence | evidence_type | confidence | impact_condition | cache impact | safe_first_action | fix | validation | do_not_do_yet
证据:代码/遥测、提供商文档假设、需要验证。将 provider_dashboard_aggregate 和 provider_usage_api_aggregate 分开处理;没有请求/路由关联时,不作因果判断。只有对高频、重复、长时间稳定前缀的路径,才讨论影响;不保证节省。
将输出分为 已确认的发现(适用于此路径的代码/配置/遥测证据)、假设(需要用量日志、渲染后的负载、路由指标或提供商文档验证)和 不适用(根据项目上下文排除的一般性建议)。
明确调用时的默认审查方式
如果明确调用此技能,且用户只要求“review”“сделай ревью”或类似内容,则默认对可用的差异或代码库进行以缓存为重点的审查,将其视为提示/前缀/KV 缓存审计,并首先报告缓存影响方面的发现。除非用户明确要求,否则不要进行通用代码审查。
用例映射
审计前先对请求进行分类。更深入的产物矩阵:references/use-cases.md。
| 场景 | 常见触发因素 | 优先检查 |
|---|---|---|
| 成本或迁移 | 账单增加、服务提供商对比、未显示折扣 | 使用日志、账单导出、Token 估算、服务提供商参考资料 |
| 提示词/代码 | cached_tokens=0、构建器已更改、架构漂移 | 提示词渲染器、SDK 调用、工具、response_format、序列化 |
| 机制/延迟 | 命中未降低成本/延迟、解码占主导 | references/mechanics.md、TTFT 跟踪、输出长度、流式传输时间戳 |
| 部署 | vLLM/SGLang 未命中、扩容后 TTFT 变化 | Docker/Kubernetes/Helm/网关配置、引擎标志、KV 指标、references/mechanics.md |
| 可观测性/CI | 仪表板、发布防护措施、前缀冒烟测试 | references/observability.md、跟踪、快照、前缀/工具/架构哈希 |
| 快速分诊 | 命中率低、账单高、TTL 理解混乱、封装层含义不明 | references/operational-playbook.md、使用字段、渲染后的请求对 |
场景参考资料
除上述「用例映射」列出的内容外,成本或迁移场景需加载 references/economics.md;发布或事件处理需加载 references/predeploy-checklist.md;Agent、MCP 和动态工具需加载 references/agent-tools.md;反模式规则需加载 references/rules.json。
捆绑脚本
在确定性证据优于文字说明时,使用脚本:
scripts/prefix_stability_check.py:比较完整输入;--canonical-json为可选项,且不能证明显式断点复用。scripts/layout_linter.py:检查 GPT-5.6/GPT-6 Astra 布局和缓存控制,以及 AP-15 工作量连续性(configuration_update、Claude 按消息设置的output_config);封装层尚未验证,且标头不可见,因此会报告 Claude beta 标头,但不会验证它。scripts/analyze_usage_logs.py:规范化 JSON/JSONL/CSV 使用数据和cache_write_tokens;仅在已知封装层语义时使用--accounting-mode。scripts/analyze_routing_logs.py:依据references/routing-evidence.md联接已规范化的决策/结果 JSONL;保留缺失的证据,并区分预测目标。它不是原生日志解析器,也不会做出发布决策。scripts/estimate_cache_roi.py:估算读取/写入成本;付费写入需使用--cache-write-rate和--cache-write-input-price-per-mtok。scripts/extract_llm_calls.py:扫描服务提供商/缓存/路由/引擎信号,包括 YAML/Python/Compose、.sh、.service和Makefile中的 vLLM 保留策略/哈希;排除.env,且不会运行时探测。它仅用于词法定位:始终省略代码片段,并且可能匹配注释、死代码或被覆盖的配置;它不会解析生效中的配置值或来源优先级。在部署审计期间,打开每个path:line并验证解析后的运行时配置;路径保持原样。scripts/render_audit_report.py:合并使用数据/发现结果,支持可重复的--cache-plane、诊所状态标志和可选的--roi-json。scripts/validate_skill_package.py:验证 frontmatter、参考资料、eval JSON 和 Python 语法;scripts/run_trigger_eval.py汇总触发覆盖情况。
Token 和成本估算均为近似值;服务提供商的使用数据和账单导出仍是权威依据。
脚本透明度规则
运行任何捆绑脚本前,说明每个脚本会读取和写入什么,以及是否使用网络。说明运行脚本的必要性、扫描范围是整个代码仓库还是指定路径,以及预期耗时类别:几秒、几十秒或几分钟。对于大型代码仓库或范围狭窄的问题,默认进行定向扫描。如果脚本可能读取机密信息、环境文件、生成的产物、大型日志或生产环境导出数据,请说明这一点并征求批准,除非用户已明确要求进行该项扫描。捆绑脚本不会将文件发送到网络服务。
新鲜度门槛
提供商信息变化频繁。在对定价、缓存折扣、存储或写入溢价、当前模型、区域可用性、阈值、粒度、TTL、保留期限、用量字段、API 参数、工具搜索、允许使用的工具、延迟加载或缓存控制语义作出确切说明前,请打开相关提供商参考资料,并在可浏览网页时核实官方来源。
如果无法查阅官方文档,请说明提供商信息尚未核实,并避免给出确切数字;随附的参考资料仅供参考,并不代表当前事实。
提供商检测
搜索 SDK 导入语句、API 基础 URL、模型名称、部署清单和引擎标志。如果信号重叠,请先加载包装器/路由器参考资料,再提供通用的提供商建议。
- OpenRouter:
openrouter、openrouter.ai/api/v1、openrouter/auto->references/openrouter.md。 - 先查包装器:
references/azure-openai.md、references/bedrock.md、references/qwen.md、references/vercel-ai-sdk.md、references/mastra.md。 - 直接接入:OpenAI ->
references/openai.md;Anthropic ->references/anthropic.md;DeepSeek ->references/deepseek.md;Gemini ->references/gemini.md;YandexGPT ->references/yandexgpt.md;z.ai ->references/zai.md。 - 兼容 OpenAI 的提供商(在用量记录中标注提供商,以便明确含计或附加计费语义):Moonshot/Kimi ->
references/moonshot.md;MiniMax ->references/minimax.md;xAI Grok ->references/xai.md;Mistral ->references/mistral.md;Tencent Hunyuan ->references/tencent.md;Xiaomi MiMo ->references/xiaomi.md。 - 自托管:
vllm、vllm bench serve、prefix_repetition、benchmark_prefix_caching.py、KV 缓存事件或 KV 传输连接器 ->references/vllm.md;SGLang/RadixAttention/HiCache/PD 解耦 ->references/sglang.md。
如果无法明确判断,请询问正在使用哪个提供商/引擎。
审计流程
- 检测模式、提供商/引擎、缓存层面和场景;加载匹配的参考资料,并应用新鲜度门槛。
- 执行项目上下文门槛和适用性门槛,然后在确定性证据有帮助时使用
scripts/extract_llm_calls.py扫描代码/配置。 - 检查提供商调用、提示词构建器、缓存控制、SDK 参数、环境变量默认值、网关/路由器、Compose/Kubernetes/Helm、引擎标志和副本拓扑。对于待审查的可复用集合,追踪“生产者 → 纳入/更新决策 → 最后一个可见的序列化表示”。检查集合已纳入但未更改的更新遭到抑制的情况;使用
references/agent-tools.md中的生命周期检查。 - 按顺序梳理提示词结构:工具、架构、系统/开发者指令、示例、静态文档、检索上下文、历史记录、用户数据、易变值;将每个部分标记为静态、半静态、动态或易变。仅在用量日志、渲染后的负载对、跟踪记录或账单有助于确认发现、比较前缀、计算投资回报率或关联事件时,才索取这些材料。
- 应用用量证据规范并测量读取/写入、TTFT/预填充、解码、路由/副本、部署和 Agent 步骤的影响;对于 Agent,还应纳入
prefix_hash、tools_count、哈希、输出、流式传输、压缩,以及路由到的提供商/模型。 - 应用
references/rules.json;报告证据类型、置信度、影响条件、安全操作、修复方案、验证方法、do_not_do_yet和诊所摘要。 - 对于 vLLM,在保留前核实版本/SHA 和功能范围;审计各组几何结构、
scheduler_block_size、层级和哈希兼容性,并区分保留/几何结构、跨进程哈希和cache_salt隔离。 - 修改代码时,在声称成功前验证前缀稳定性。
随附的固定样例是示例和回归数据;脚本接受常规 JSON、 JSONL、CSV 用量日志和请求负载。
审计手册
在完成提供商检测和新鲜度门控后,使用以下起始项:
- OpenAI cached_tokens=0:检查长度、前缀漂移、API 用量字段、断点、输出占比和包装层。在使用 GPT-5.6 前检查
prompt_cache_key路由;在较新的模型中,该字段对于用量统计是可选的。 - GPT-5.6 付费写入:验证
prompt_cache_options和标记区块,将包含在输入总量中的cached_tokens/cache_write_tokens与输入总量区分开;在声称节省成本前,要求使用当前定价。当易变后缀导致隐式写入频繁变动时,优先使用显式模式。 - 对话中途更改 Effort:请求级别的 effort 或 thinking 更改可能重写前缀(AP-15)。在 GPT-6 标准单 Agent 路由上使用
configuration_update,或在支持的 Claude 模型(包括 Opus 5.5)上使用逐消息设置output_config.effort。在提供商参考资料中检查模型、beta 版和接入界面的支持情况;确认下一轮的读取情况。 - Claude/Bedrock/OpenRouter 有写入但无读取:区分写入/创建字段与读取/命中字段,然后检查断点位置、断点前的动态内容、TTL/保留时间、模型/区域/API 支持、回退路由,以及实际路由到的提供商/模型。
- Gemini Interactions 或托管会话缓存:区分显式缓存对象与不透明的延续句柄(
previous_interaction_id、previous_response_id),将其保留在预期的对话中,并在比较路由前将total_cached_tokens统一按包含缓存量的口径处理。 - KV 事件、HiCache 或 PD 解耦:区分前缀不匹配、驱逐、层级间传输/卸载、事件传递和解码侧 KV 复用。优先比较 TTFT/预填充和工作节点/层级指标。
- 长 Agent 循环中的动态工具:检查
tools_count、排序后的工具名称/前缀哈希、模式、用量和经济性;直接使用 OpenAI Responses/Vercel 时,采用经过版本/模型验证的允许列表;使用 Chat Completions/不支持的包装层/端点时,需要线路层面的证据;自托管环境可能会屏蔽信息。 - 命中率高但未节省成本:区分输入成本节省、总成本和最终延迟。检查输出 token 占比、解码时间、外部工具时间、TPM/速率限制,以及读取/写入定价假设。
- OpenAI 兼容包装层存在歧义:如果 OpenAI SDK 由
base_url、Azure、OpenRouter、Bedrock、DashScope/Qwen 或其他网关包装,则先加载该包装层的参考资料。 - 自托管多副本未命中:检查分词器/聊天模板漂移、
max_model_len、KV 压力/驱逐、网关/服务路由、路由/副本命中指标;路由门控规则见:references/mechanics.md。 - vLLM 保留策略和跨进程哈希:收集镜像摘要/版本/SHA、
功能是否存在、有效保留策略的来源/值、具体的
SlidingWindowSpec/SlidingWindowMLASpec/MambaSpec与全注意力 分组、scheduler_block_size、层级类型、哈希算法,以及安全种子 兼容状态。应用发布版本线矩阵;切勿根据架构名称推断是否符合条件, 也切勿将PYTHONHASHSEED视为隔离机制。 - 新提供商文档:将新提供商的事实与当前代码、参考资料、评估和测试进行比较;如果项目已体现相应行为,则建议不做更改。
规则类别
references/rules.json 保存了机器可读的 AP-1 至 AP-15 清单。
AP-9b 是隔离/信任边界;AP-14 是已获授权的共享组内的技术哈希兼容性;AP-15 是缓存对话中的工作量/推理配置连续性。将规则转化为发现项时,使用以下优先级分类:
| 优先级 | 类别 | 示例 |
|---|---|---|
| P0 | 提供商正确性 | 用量字段、阈值、缓存激活、TTL/保留期限 |
| P1 | 前缀稳定性 | 静态内容优先排序、开头不含易变值、工具/架构稳定、恒定或按位置变更的工作量 |
| P2 | 测量 | 分母状态、缓存比率、写入与读取、输出占比、TTFT |
| P3 | 架构 | RAG/CAG、平面分离、多租户边界、路由局部性 |
| P4 | 报告 | 文件行号发现项、前后布局、ROI 假设、验证 |
严重程度
先判断适用性,再判断严重程度
只有通过项目上下文门槛和适用性门槛后,才评定严重程度。在冷门、稀疏、单次运行、受输出限制或不可缓存的路由中,确实存在反模式也不意味着严重程度一定高。
- 严重:在大型共享前缀、昂贵模型、高流量、长 Agent 轨迹或多副本生产路径上,确认指标下降或缓存未命中。
- 高:可能导致热门路径的缓存失效,或证据表明缓存/成本/TTFT 受到显著影响,但指标不完整。
- 中:此模式可能导致缓存碎片化,但影响取决于流量特征。
- 低:防御性清理、文档或监控改进。
如果热门程度、前缀长度、调用频率或成本影响未知,优先评为 medium 或 needs validation,并说明哪些情况会使严重程度上调或下调。
报告格式
默认先简要列出发现项,优先使用包含证据的格式:
file:line | severity | provider/engine | issue | cache impact | fix | validation。
完整交接报告请加载 references/report-template.md。
Agent 优先的质量标准
定稿前:
- 回答所提问题:是否需要修改、无需修改,还是证据不足。
- 如果同时存在包装器/路由器和通用提供商的参考资料,优先采用前者;没有参考资料且未通过新鲜度门槛时,不得对具体提供商做出确切判断。
- 区分平面、缓存未命中、写入但未读取、不经济的命中、解码受限的延迟、速率限制压力,以及隐私驱动的隔离。
- 提供可证伪的验证方法:前缀指纹、用量字段、路由/副本指标,或成本/延迟拆分。
- 如果适用「不值得缓存」约定,不要建议使用缓存控制、缓存键或路由提示。
验证
只有满足对应范围的检查后,才能声称修复有效:
- 前缀修复:不同用户、时间戳和查询下,渲染后的可缓存前缀指纹保持不变。
- 提供商修复:根据提供商参考资料,重复调用时缓存读取/缓存令牌字段持续增加。
- 路由变更:按照
references/mechanics.md中的完整Routing Outcome Gate验证;可自托管的非路由修复:在具有代表性的工作负载下,前缀命中率/KV 压力有所改善。
建议添加 CI/冒烟检查,对具有代表性的提示词进行渲染,并在可缓存前缀意外变化时失败。
建议询问的问题
如果没有代码库,只询问尚缺的信息:提供商或引擎;涉及的缓存平面;审计类型(成本/迁移、提示词/代码、Agent、部署、可观测性/CI);可用材料(请求代码、渲染后的提示词、用量日志、部署配置、仪表板、评估结果);输入、中位数/p95 静态前缀和输出令牌数,以及 Agent 步数;可见的缓存用量字段;副本和网关数量;跨步骤的工具/架构稳定性;历史记录的处理方式;缓存键、盐值或路由提示是按用户区分,还是按前缀族共享;以及命中率或 TTFT 下降之前发生了什么变化。