ContextSpy：让 AI 编码代理的上下文窗口变得「可见」

随着 Claude Code、GitHub Copilot、opencode 等 AI 编码代理承担越来越复杂的开发任务，开发者很难直观看到「每次请求究竟把哪些内容塞进了上下文窗口」。Show HN 上发布的 ContextSpy 正是一款针对这一痛点的诊断工具：它通过本地 HTTPS 代理拦截发往 LLM 的请求，把系统提示、工具定义、文件内容、对话历史等不同来源的 token 进行分类统计，并在浏览器仪表盘中实时呈现。

工具定位与核心功能

ContextSpy 自比为「LLM 领域的 CPU 或内存剖析器」。它启动一个本地 HTTPS 代理（对本地部署的模型则使用反向代理），截获所有发往大模型的请求并写入本地 SQLite 数据库；同时在 127.0.0.1:5173 启动一个 Web 仪表盘，供用户跨会话、跨时间查看请求的 token 构成与变化。代理端口为 8888，所有服务都仅绑定到本地，不对外暴露。

目前支持 Claude Code、opencode、Codex CLI 等常见 AI 编码代理，并提供 macOS（Apple Silicon）的 Homebrew 一键安装方式，也覆盖 Linux、Windows 与 PyPI 安装路径。

为什么需要上下文剖析

• Token 成本被低估：在代理工作流中，输入 token 的数量通常是输出 token 的 20–50 倍甚至更多。原文给出的对比是，Opus 4.8 输出价格为 $25 / 百万 token，而 gpt-5-nano 仅 $0.40，但实际账单大头往往来自输入上下文。
• 上下文膨胀速度惊人：一次新会话通常以 5000–10000 token 起步，到第 25 轮左右可能膨胀到 3 万–5 万 token，接近模型窗口上限并触发压缩；后续每次调用都会把完整上下文作为 prompt 一并发送。
• 大上下文并非免费：扩展窗口会带来三重代价——API 费用上升、计算与延迟增加，以及「上下文腐化」——研究表明模型精度在 100k token 附近开始明显下降，花了更贵的钱却拿到了更便宜模型的水平。

隐私与数据保留

ContextSpy 不向云端上传任何数据，所有抓取内容均保存在本地数据库中。它会把请求原始内容默认保存 7 天后清除（可通过 ~/.contextspy/config.toml 的 [retention] 配置），聚合后的 token 计数与分类结果则长期保留，清除操作仅在服务启动时执行。

使用建议

作者建议把 ContextSpy 当作「专项剖析与优化工具」短期运行，而不是常驻的监控系统：开启代理、记录一次完整任务流、查看仪表盘中的 token 分布与增长曲线，再针对性裁剪系统提示、工具结果或对话历史，以控制成本与延迟。所有数据都保留在本机，开发者可在结束会话后通过 contextspy reset-db 手动清理数据库。