claude-webcache

Claude Code 的跨会话 WebFetch 缓存。

Claude Code 内置的 WebFetch 仅在单个会话内缓存 15 分钟的结果。claude-webcache 将其扩展到跨会话，并可无限期保留（默认 TTL 为 7 天，可配置）。

Open new session  ->  your past fetches are still there.
Cache hit         ->  instant.
Cache miss        ->  same as built-in WebFetch.

为什么使用它

每当你在不同会话中重新获取相同的 URL（如文档、API 参考、研究页面）时，你每次都要支付完整的获取成本。15 分钟的会话内缓存会在你的下一次冲刺（sprint）之前过期。claude-webcache 会保留获取的内容，以便第二个会话可以直接命中缓存。

安装

选项 1 -- Claude Code 插件（推荐）

在终端中运行一行命令：

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

然后将使用模式添加到你的 ~/.claude/CLAUDE.md 中（参见 使用模式）。

💡 为什么使用 CLI 子命令而不是 TUI 的 /plugin install？ TUI 流程目前通过 Claude Code 的 remoteMarketplaceClient 后端路由，该后端存在一个公开的服务器端 Bug，会拒绝所有第三方插件源，并报错 Failed to install: This plugin uses a source type your Claude Code version does not support.。参见 anthropics/claude-code#41653 以及约 20 个相关的开放问题。上述 CLI 子命令在本地使用 NativeMarketplaceReader，不受此影响。

备选方案（如果你的设置中 CLI 子命令也失败）：

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。

使用模式

添加到你的 ~/.claude/CLAUDE.md 中，以便 Claude 通过缓存路由网页获取请求：

## WebFetch caching (claude-webcache)

Before calling WebFetch, call `cached_fetch(url, prompt)` first.
- If it returns text -> use that, do NOT call WebFetch.
- If it returns `[CACHE_MISS] <url>` -> call WebFetch as normal, then call `cache_store(url, prompt, output)` with the result.

就是这样。在未来的任何会话中，相同的 URL + 相同的提示词 = 即时命中缓存。

工具 (MCP)

存储

SQLite 位于 ~/.webcache/cache.db（WAL 模式，并发安全）。缓存键 = SHA256(url + "|" + prompt)。

SessionStart 钩子

在每个新会话中，该钩子会注入一行统计信息：

webcache: 142 pages cached, 38 hits, last fetch 3h ago

如果缓存为空，则跳过注入。

TTL

默认 7 天。过期条目会在下次读取相同键时被删除。通过引入 src/cache.js 并调用 purgeExpired() 来手动执行清理。

限制

• 缓存键包含提示词 -> 同一 URL 上的不同提示词是独立的条目。选择一致的提示词（例如始终使用 "extract title and main content"）以最大化命中率。

• 输出是 WebFetch 返回的任何内容（已由模型总结）。缓存不会对其进行重新处理。

• 没有语义搜索，没有嵌入。仅限精确的 (url, prompt) 匹配。

许可证

MIT -- 参见 LICENSE。