https://liaohch3.com/tags/claude-tap/Recent content in Claude-Tap on liaohch3Hugo -- gohugo.iozh-cnSun, 03 May 2026 23:42:53 +0800https://liaohch3.com/posts/claude-tap-trace-viewer/Sun, 03 May 2026 23:42:53 +0800https://liaohch3.com/posts/claude-tap-trace-viewer/<p>今天发了一条推文介绍 <a class="link" href="https://github.com/liaohch3/claude-tap" target="_blank" rel="noopener" >claude-tap</a>。这里把背景和截图整理成一篇博客，方便以后回看。</p> <p>我的主业是 Agent 开发，日常经常需要研究 Claude Code / Codex 这类工具的上下文工程：system prompt 怎么写，messages 怎么组织，tools 怎么传，tool results 怎么回灌，token 又花在了哪里。</p> <p>以前社区里有一个 <code>claude-trace</code>，但它已经不太适配最新的 Claude Code。所以我重新做了一个工具：<code>claude-tap</code>。</p> <h2 id="claude-tap-做什么">claude-tap 做什么 </h2><p>一句话：<strong>把 Claude Code / Codex 的真实请求抓出来，生成本地 HTML trace viewer。</strong></p> <p>它会在本地启动一个 proxy，把客户端发给上游模型服务的请求记录下来，最后生成 JSONL trace 和一个自包含的 HTML 页面。这个页面可以直接打开，不依赖服务端。</p> <img src="https://liaohch3.com/images/claude-tap/github-overview.jpg" alt="claude-tap GitHub 项目首页" loading="lazy"> <p>它主要解决的是一个很具体的问题：不要只猜 Agent harness 怎么设计，而是直接看真实请求。</p> <h2 id="看见完整上下文">看见完整上下文 </h2><p>Claude Code / Codex 真正发给模型的内容，通常比我们肉眼在终端里看到的复杂很多。除了用户消息，还有 system prompt、developer instructions、工具定义、历史消息、continuation 信息、token usage 等。</p> <p>这些东西如果只靠猜，很容易误判。trace viewer 能把每次 LLM call 展开看：</p> <img src="https://liaohch3.com/images/claude-tap/trace-overview.jpg" alt="在 trace viewer 中查看 Codex 请求上下文" loading="lazy"> <p>对我来说，最有价值的是能看到这些细节：</p> <ul> <li>system prompt / instructions</li> <li>messages / input</li> <li>tools schema</li> <li>tool calls 和 tool results</li> <li>token usage</li> <li>WebSocket / SSE 事件</li> </ul> <p>这对于研究一个 Agent 工具为什么这样行动、为什么上下文变大、为什么某次调用结果不稳定，都很有帮助。</p> <h2 id="看见工具调用和结果">看见工具调用和结果 </h2><p>Agent 工具链里，LLM call 本身只是一部分。很多行为真正发生在工具调用阶段。</p> <p>比如 Codex 调用 <code>exec_command</code> 时，模型到底生成了什么参数，工具返回了什么结果，下一轮又如何把结果喂回模型，这些都可以在 viewer 里展开看。</p> <img src="https://liaohch3.com/images/claude-tap/tool-calls.jpg" alt="查看工具调用和工具结果" loading="lazy"> <p>这类信息平时散落在终端输出和内部状态里，直接读很麻烦。放进 trace viewer 后，就比较适合复盘和对比。</p> <h2 id="对比连续请求">对比连续请求 </h2><p>另一个我常用的功能是 diff。</p> <p>Agent 在连续几轮调用中，新增了哪些消息，工具结果如何进入上下文，<code>previous_response_id</code>、metadata、prompt cache 等字段怎么变化，都可以直接对比。</p> <img src="https://liaohch3.com/images/claude-tap/diff-view.jpg" alt="对比连续请求的差异" loading="lazy"> <p>这对调试上下文工程很有用。尤其是在改 prompt、改 tool schema、改 harness 逻辑之后，可以直接看新旧请求差异，而不是只看最终回答。</p> <h2 id="为什么是本地-html">为什么是本地 HTML </h2><p>我做这个工具时有一个很明确的边界：数据默认留在本地。</p> <p>trace 里会包含 system prompt、上下文、工具结果，有些项目里还会出现路径、日志、内部配置等信息。把它做成一个本地 HTML viewer，比较适合个人研究、团队内部复盘和问题定位。</p> <p>它不是一个生产监控平台，也不想先把数据上传到某个云服务。它更像一个开发者工具：需要的时候打开，用完之后 trace 文件还在你自己的机器上。</p> <h2 id="试用">试用 </h2><p>项目地址：</p> <p><a class="link" href="https://github.com/liaohch3/claude-tap" target="_blank" rel="noopener" >https://github.com/liaohch3/claude-tap</a></p> <p>安装：</p> <div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>uv tool install claude-tap </span></span></code></pre></div><p>追踪 Claude Code：</p> <div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>claude-tap </span></span></code></pre></div><p>追踪 Codex：</p> <div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;"><code class="language-bash" data-lang="bash"><span style="display:flex;"><span>claude-tap --tap-client codex </span></span></code></pre></div><p>如果你也在研究 Agent、Claude Code、Codex、上下文工程，欢迎试用、提 issue 或 star。</p> <p>原推文：</p> <p><a class="link" href="https://x.com/liaohch3/status/2050964318070673581" target="_blank" rel="noopener" >https://x.com/liaohch3/status/2050964318070673581</a></p>