claude-webcache

claude-webcache

Claude Code 的跨会话持久化 WebFetch 缓存。缓存读取仅需约 0.07ms，比重新获取快几个数量级。

Claude Code 内置的缓存有效期为 15 分钟，且仅限当前会话。每次开启新会话都会从头重新获取。claude-webcache 会将结果持久化到本地 SQLite 数据库中，实现即时命中缓存，无网络开销。

Session 1  →  WebFetch("docs.example.com")  →  fetched, auto-cached ✓
Session 2  →  cached_fetch("docs.example.com")  →  instant hit, no network call
Session 7  →  cached_fetch("docs.example.com")  →  still instant, unlimited TTL

**v0.1.5+：**每次 WebFetch 都会通过 PostToolUse 钩子自动保存，无需任何配置。

安装

claude plugin marketplace add theYahia/claude-webcache && claude plugin install claude-webcache@theyahia

适用于：Claude Code CLI · 桌面应用（Mac/Windows）· VS Code 扩展 · JetBrains 插件——所有环境使用相同命令。

完成。从现在开始，每次 WebFetch 都会自动缓存。

你也可以选择将使用模式添加到 ~/.claude/CLAUDE.md，以便在获取内容之前先检查缓存（重复 URL 可完全省去 WebFetch 调用）。

**插件 TUI 无法使用？**Claude Code 中有一个未修复的 Bug（#41653），/plugin install 会因“source type not supported”而拒绝第三方来源。请使用上面的 CLI 命令——它绕过 TUI，运行正常。

备用方式（无市场）：

git clone https://github.com/theYahia/claude-webcache && claude --plugin-dir ./claude-webcache/plugin

选项 2 — npm 全局安装

npm i -g @theyahia/claude-webcache

需要 Node.js 22.5+（使用内置的 node:sqlite——无需原生依赖，也无需安装步骤）。

然后在 ~/.claude/settings.json 中注册（将路径替换为 npm root -g 的输出）：

{
  "mcpServers": {
    "claude-webcache": {
      "command": "node",
      "args": ["/path/from/npm-root-g/claude-webcache/scripts/mcp-server.cjs"]
    }
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear|compact",
        "hooks": [
          { "type": "command", "command": "node /path/from/npm-root-g/claude-webcache/scripts/hook-stats.cjs" }
        ]
      }
    ]
  }
}

选项 3 — 克隆（贡献者）

请参阅 CONTRIBUTING.md。

使用模式（可选——用于获取前检查缓存）

**v0.1.5+ 会自动缓存每次 WebFetch。**以下模式为可选：将其添加到 ~/.claude/CLAUDE.md，以便在执行 WebFetch 之前先检查缓存——重复 URL 可完全省去 WebFetch 调用。

自动读取（v0.5+）：无需操作。PreToolUse 钩子会在每次 WebFetch/WebSearch 前检查缓存。命中时会提供缓存副本并跳过网络请求；未命中时会正常执行调用，并由 PostToolUse 钩子保存结果。今后任何会话中，相同 URL + 相同提示词（或相同搜索查询）都会即时命中，且无网络开销。

如果需要，仍可手动查询：调用 cached_fetch(url, prompt)（或 cached_search(query)）——返回缓存文本；如果不存在，则返回 [CACHE_MISS] …。使用 WEBCACHE_AUTOREAD=0 禁用自动读取。

⚠ 安全——需要身份验证的 URL

缓存会将 URL 与响应一起存储在 ~/.webcache/cache.db 中。默认情况下，claude-webcache 会在写入前从存储的 URL 中移除明显的凭据（user:pass@host，以及名称为 token、api_key、apikey、access_token、auth、secret、password、key、signature 等的查询参数）。

**这只是显示层面的脱敏，并非密钥层面的脱敏。**缓存键仍会对原始 URL 进行哈希，因此再次获取相同的认证 URL 时会命中缓存。如果需要更严格的取舍：

export WEBCACHE_STRICT_REDACT=1

启用 WEBCACHE_STRICT_REDACT=1 后，缓存键也会根据脱敏后的 URL 计算——仅 ?token=A 与 ?token=B 不同的端点会冲突并占用同一个槽位。这适用于透传身份验证（内容相同），但不适用于个性化端点（不同用户会看到彼此缓存的数据）。

**总之：**优先使用基于请求头的身份验证（Authorization: 请求头），而非嵌入 URL 的令牌。不要将 ~/.webcache/cache.db 提交到 Git。

命名空间

多个项目共用一台机器？按项目隔离缓存：

WEBCACHE_NAMESPACE=gosdelo  claude    # cache writes/reads scoped to ns "gosdelo"
WEBCACHE_NAMESPACE=qsearch  claude    # separate ns, no cross-contamination

默认命名空间是空字符串 ""（与 v0.3 行为相同，共享缓存）。通过 CLI 检查或管理各命名空间：claude-webcache namespaces、claude-webcache --namespace gosdelo stats。

工具（MCP）

工具	参数	返回值
cached_fetch	url、prompt	缓存的文本，或 [CACHE_MISS] <url>
cached_search	query	缓存的 WebSearch 结果，或 [CACHE_MISS] <query>（websearch 命名空间，TTL 较短）
cache_store	url、prompt、output	stored
cache_stats	global?	{ namespace, total, hits, misses, hit_rate, last, db_size_bytes, evicted, oversize_skipped, last_hook_error_at, top_urls, ... }
cache_list	limit?、offset?、global?	最近访问的 URL（最新的排在最前）
cache_invalidate	url	{ deleted: N } — 删除当前命名空间中该 URL 的所有条目
cache_clear	older_than_days?、confirm?	{ deleted: N } — 按缓存年龄部分清除，或使用 confirm:"YES" 全部清除
cache_warm	entries: [{url,prompt}] 或 urls[]+prompt	{ hits, misses, invalid } — 一次调用批量预热
cache_refresh	url、prompt	[CACHE_MISS] <url> — 使缓存失效并提示重新获取

CLI

npm 包附带 claude-webcache 二进制文件，可用于临时检查，还提供本地 Web 控制面板：

claude-webcache stats                            # JSON stats
claude-webcache stats --by-domain                # per-domain breakdown
claude-webcache list 20                          # 20 most-recent URLs
claude-webcache list 50 --offset 100             # pagination
claude-webcache invalidate https://news.com/123  # drop one URL
claude-webcache refresh https://news.com/123 --prompt "extract title"   # invalidate one (url,prompt) pair
claude-webcache warm urls.txt --prompt "extract" # bulk pre-flight check
claude-webcache clear --older-than-days 30       # partial wipe
claude-webcache clear --confirm YES              # full wipe (requires explicit confirm)
claude-webcache clear-logs                       # truncate ~/.webcache/hook.log
claude-webcache namespaces                       # list all namespaces present
claude-webcache export --out cache.json --all    # export metadata
claude-webcache dashboard                        # open http://localhost:37778
claude-webcache --namespace gosdelo stats        # scope command to namespace

控制面板会显示按命中次数排序的热门 URL、热门域名（含平均命中次数／最近获取时间／条目数），以及完整的可搜索分页列表，并提供一键失效和刷新按钮。仅使用标准库，无需安装额外依赖。

配置（环境变量）

变量	默认值	作用
WEBCACHE_TTL_DAYS	unlimited	全局 TTL，单位为天。0 或未设置 = 永不过期。
WEBCACHE_MAX_SIZE_MB	unlimited	超出此大小后，下次写入时 LRU 淘汰会删除约 20% 的最旧条目（按 last_hit_at 排序；每 100 次写入触发一次，且有防抖）。
WEBCACHE_DOMAIN_TTL	none	各域名的 TTL JSON：{"news.com":1,"reuters.com":1,"arxiv.org":0}。单位为天；0 = 永不过期。会匹配后缀域名，包括子域名。匹配时优先于全局 TTL。
WEBCACHE_NAMESPACE	""（共享）	按项目隔离缓存。不同命名空间之间互不可见。
WEBCACHE_MAX_OUTPUT_MB	10	拒绝大于 N MB 的 WebFetch 响应。统计信息会跟踪 oversize_skipped 计数器和 last_oversize_url。
WEBCACHE_COMPRESS	off	1 会对 ≥4 KB 的响应启用 gzip。以 base64 格式存储在 TEXT 列中。现有未压缩行仍可正常读取（BC）。
WEBCACHE_STRICT_REDACT	off	1 会让缓存键使用经过脱敏的 URL — 无论令牌值如何，同一端点都会发生冲突。参见上文的安全性说明。
WEBCACHE_QUIET	off	1 会禁止钩子向 stderr 输出内容（仍会写入 ~/.webcache/hook.log 文件日志）。
WEBCACHE_DEBUG	off	1 会启用自动缓存钩子的详细跟踪信息。
WEBCACHE_SEARCH_TTL_HOURS	6	缓存的 WebSearch 结果（websearch 命名空间）的 TTL。搜索排名会变化，因此默认 TTL 较短。0 = 永不过期。
WEBCACHE_AUTOREAD	on	0 会禁用 PreToolUse 自动读取钩子（缓存仍会通过 PostToolUse 填充；你需要通过 cached_fetch／cached_search 手动读取）。

SessionStart 钩子

每次新会话都会注入一行提示，让 Claude 知道缓存可用：

webcache [ns=gosdelo] 142 pages cached, 87% hit rate, last fetch 3h ago

缓存为空时不会输出内容。使用默认命名空间时会省略 [ns=...]。

存储

SQLite 位于 ~/.webcache/cache.db（WAL 模式，synchronous=NORMAL，busy_timeout=5000）。 缓存键 = SHA256(namespace + "|" + canonical(url) + "|" + prompt)。默认 TTL：不限时（设置 WEBCACHE_TTL_DAYS=N 可配置 N 天后过期）。

URL 规范化（v0.4+）：主机名转为小写，移除默认端口（:80/:443），移除片段，按字母顺序排列查询参数。因此，https://EXAMPLE.com/p?b=2&a=1#frag 和 https://example.com/p?a=1&b=2 会生成相同的缓存键，不会因 URL 格式差异而静默未命中。

字段	类型
key	TEXT PRIMARY KEY
url	TEXT（已脱敏）
prompt_hash	TEXT
output	TEXT（当 compressed=1 时采用 gzip+base64）
cached_at	INTEGER（毫秒纪元时间）
hit_count	INTEGER
last_hit_at	INTEGER
namespace	TEXT（默认为 ""）
compressed	INTEGER（0/1）

通过 WAL 和 5 秒的 busy_timeout 实现并发安全——多个 Claude Code 会话可同时读写，不会出现 SQLITE_BUSY 错误。

限制

• 缓存键包含提示词——使用一致的提示词以最大限度提高命中率。
• 输出内容与 WebFetch 返回的内容相同（已经过摘要处理）。不会重新处理。
• 不支持语义搜索。仅精确匹配 (namespace, canonical_url, prompt)。

基准测试

在已填充的数据库上进行的单进程延迟测试（N=10000 条记录，每条输出 1KB），通过 npm run bench 测量：

操作	p50	p95	p99	ops/sec
write	0.09ms	0.15ms	2.66ms	5,800
read_hit	0.07ms	0.12ms	0.23ms	7,600
read_miss	0.04ms	0.07ms	0.13ms	17,600
list_50	0.11ms	0.16ms	0.53ms	7,400

存储开销：每条记录约 2 KB（对于 1 KB 负载），包括键、索引、WAL 和新增的 v0.4 列。对于文本较多的响应，启用 WEBCACHE_COMPRESS=1 后，预计可缩小 3–7 倍。

WebFetch 通常需要 1–5 秒完成网络请求——缓存命中快约 15,000–70,000 倍。在你的硬件上复现：npm run bench。基准测试方法和每次运行保存的完整结果元数据（CPU、RAM、OS、提交记录）请参阅 bench/README.md。

相关项目

• claude-mem — 跨会话持久记忆（与 claude-webcache 互补：记忆与 Web 缓存）
• WWmcp — 面向非西方 API 的 46 个 MCP 服务目录

许可证

MIT — 参见 LICENSE。

---

WWmcp 的一部分 · Telegram： @vhodvai