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 演示(MP4)

试用演示: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_REORDER | MCP 服务器重连或以非确定性顺序注册工具 | 传入 --heal 以确定性方式排序 tools[](以及 Gemini functionDeclarations[] ) |
| TOOL_MUTATED | 动态工具描述或 schema 字段在会话中途发生变化 | 将静态工具描述固定在缓存前缀之外 |
| VOLATILE_SYSTEM | 时间戳、UUID 或可变状态字符串落入 $.system / $.systemInstruction 中 | 将动态元数据移到末尾的用户轮次 |
| TTL_EXPIRED | 字节 100% 匹配,但两轮之间间隔超过 5m | 保持交互式会话活跃,或选择扩展 TTL |
| MODEL_CHANGED | 模型名称在会话中途切换 | 每个缓存前缀只用一个模型 |
| PREFIX_TOO_SHORT | Prompt 低于 OpenAI( 1,024 )或 Gemini( 1,024 / 2,048 )的隐式缓存下限 | 在上下文增长超过阈值前属预期现象 |
诚实的对比
文章标题:Kvdiff – 本地代理,展示破坏你 LLM 提示缓存的字节
正文:
| 功能 | kvdiff | ccusage / codexbar | ContextSpy | Langfuse / Phoenix |
|---|---|---|---|---|
| 安装与基础设施 | 1 条命令( npx ),内置 node:sqlite | 1 条命令( 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。