Newshot

Kvdiff – 本地代理,展示导致 LLM 提示缓存失效的字节

Translation(model translation, not the source's own text)

kvdiff

零代码本地代理,精确定位破坏你 LLM prompt cache 的那个确切 UTF-8 字节(Anthropic、OpenAI、Google Gemini / Antigravity、llama.cpp/vLLM),统计浪费的金额,并可选地实时自动修复前缀。

观看 15 秒 kvdiff 演示
观看 15 秒 kvdiff 演示

观看 15 秒 kvdiff 演示(MP4)

kvdiff prompt-cache 瀑布图与字节差异检查器
kvdiff prompt-cache 瀑布图与字节差异检查器

试用演示:npx @drod915/kvdiff --demo

5 秒内看到一次 Prompt-Cache 失效(无需任何 API Key)


        npx @drod915/kvdiff --demo
      

打开 http://127.0.0.1:4318,预置了两个真实场景的会话:

  • Claude Code + 15 个 MCP 工具(16 轮):第 1 轮以 0% 预热 prompt cache,第 2-13 轮以 94% 缓存命中运行。第 14 轮时,mcp-github 重连并重排了工具 schema:kvdiff 高亮出确切的红色字节偏移($.tools[9].name,字节 1,670),计算浪费的成本($0.38),并展示在 --heal 下第 15 轮缓存命中率跳回 97%。
  • Antigravity / Gemini 2.5 Pro(5 轮):捕获第 4 轮注入到 $.systemInstruction.parts[0].text 中的易变时间戳。
用 vhs demo/kvdiff.tape 在终端中录制演示。

快速开始

零代码改动即可包装任意编码 agent CLI:


        # Claude Code (Anthropic Messages API)
npx @drod915/kvdiff -- claude

# Codex CLI / OpenCode (OpenAI Responses & Chat APIs)
npx @drod915/kvdiff -- codex

# Gemini CLI / Antigravity API workflows (Google Gemini API)
npx @drod915/kvdiff -- gemini

# Opt-in deterministic tool-schema healing
npx @drod915/kvdiff --heal -- claude
      

或作为常驻本地代理运行,用于 Antigravity、Cursor、IDE 插件或本地 llama.cpp/vLLM:


        # Cloud providers (Anthropic, OpenAI, Google Gemini / Antigravity)
npx @drod915/kvdiff serve --port 4318

# Local llama.cpp / vLLM KV-cache prefix reuse debugging
npx @drod915/kvdiff serve --port 4318 --upstream-local http://127.0.0.1:8080
      

然后将你的客户端 base URL 指向:

  • ANTHROPIC_BASE_URL=http://127.0.0.1:4318
  • OPENAI_BASE_URL=http://127.0.0.1:4318/v1
  • GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:4318

kvdiff 能捕获什么

失效类型线上实际发生了什么修复方法
TOOL_REORDERMCP 服务器重连或以非确定性顺序注册工具传入 --heal 以确定性方式排序 tools[](以及 Gemini functionDeclarations[] )
TOOL_MUTATED动态工具描述或 schema 字段在会话中途发生变化将静态工具描述固定在缓存前缀之外
VOLATILE_SYSTEM时间戳、UUID 或可变状态字符串落入 $.system / $.systemInstruction 中将动态元数据移到末尾的用户轮次
TTL_EXPIRED字节 100% 匹配,但两轮之间间隔超过 5m保持交互式会话活跃,或选择扩展 TTL
MODEL_CHANGED模型名称在会话中途切换每个缓存前缀只用一个模型
PREFIX_TOO_SHORTPrompt 低于 OpenAI( 1,024 )或 Gemini( 1,024 / 2,048 )的隐式缓存下限在上下文增长超过阈值前属预期现象

诚实的对比

文章标题:Kvdiff – 本地代理,展示破坏你 LLM 提示缓存的字节

正文:

功能kvdiffccusage / codexbarContextSpyLangfuse / Phoenix
安装与基础设施1 条命令( npx ),内置 node:sqlite1 条命令( npx /二进制)1 条命令( npx )Docker + Postgres/ClickHouse
线上级 UTF-8 字节 LCP + JSONPath 差异是否(读取事后日志)否(Token 类别饼图)否
可选的实时前缀修复( --heal )是否否否
多提供商( Anthropic + OpenAI + Gemini/Antigravity + llama.cpp )是专注单一提供商Anthropic/OpenAI是
默认零变更直通是(OAuth/beta 请求头保持不变)不适用(离线日志读取器)是SDK 插桩
竞品胜出之处-零代理搭建;跨过往月份的历史账单总计很棒高层级 Token 细目可视化生产团队评估、提示版本管理、多用户云端追踪

架构


        flowchart LR
    Agent["Coding Agent / IDE\n(Claude Code · Codex · Antigravity · Gemini · llama.cpp)"] -->|"HTTP (127.0.0.1:4318)"| Proxy["kvdiff Proxy\nZero-mutation default\n(opt-in --heal)"]
    Proxy -->|"Immediate chunked SSE flush"| Upstream["Upstream Provider\nAnthropic · OpenAI · Gemini · Local"]
    Proxy -.->|"Non-blocking SSE tee"| Engine["UTF-8 Byte LCP +\nJSONPath Mapper +\nBreak Classifier"]
    Engine --> DB[("~/.kvdiff/kvdiff.db\nNode 24 node:sqlite WAL")]
    DB --> UI["Localhost Waterfall UI\n127.0.0.1:4318"]
      

安全与隐私保证

  • 100% 本地:默认绑定到 127.0.0.1。流量仅存储在 ~/.kvdiff/kvdiff.db。零遥测,零云账户。
  • 默认严格零变更:不使用 --heal 时,kvdiff 会原样转发你的原始请求字节以及每一个非逐跳请求头(Authorization、x-api-key、x-goog-api-key、anthropic-beta、openai-beta),不做任何修改。
  • 零缓冲 SSE:流式响应在从上游到达时逐块向下游刷新。
  • 安全的 --heal 不变式:--heal 会对 tools 和工具定义键进行排序,规范化 JSON 格式,并在排序后将 Anthropic 末尾缓存断点保留在最后一个工具上。它绝不会重排 messages[]、contents[]、parts[]、content[]、input[] 或 JSON Schema enum[]。

开发


        git clone https://github.com/flipcyde101/kvdiff.git
cd kvdiff
npm install
npm run typecheck
npm run build
npm test
      

发现了缓存中断模式或提供商边缘情况?请到 github.com/flipcyde101/kvdiff/issues 提交 issue。

许可证

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗