欢迎来到 claude-tap 的深度逆向与架构知识库。

在传统的软件开发中,我们习惯于阅读结构化的日志和调用栈。但在 AI Agent 时代,Agent 运行在你的终端里,就像一个神秘的"黑盒"——你只能看到它在屏幕上打印出的最终一句话,却不知道它在底层的几十轮 ReAct 循环中,脑子里闪过了什么念头、调用了什么工具、又为什么突然陷入了死循环。

claude-tap 的定位,就是在这个黑盒上套一层**"高透明度的玻璃罩"**。让每一次模型请求的 System Prompt、工具 Schema、Tool Call 细节、流式响应、Token 变化以及上下文演进轨迹,全部以可视化的方式无损呈现在你面前。

这里不是官方冷冰冰的 API 说明书,而是一份源自真实 Trace 逆向分析的工程笔记。

本知识库分为三个核心板块,建议按照以下路线进行探索:

• 项目产品介绍 :Agent 可观测性到底解决了什么痛点?我们的核心价值与边界在哪里?
• 项目架构介绍 :透视 claude-tap 内部的组件协作,理解流式数据从捕获到最终呈现的流水线。
• 观察机制详解:如何拦截 Agent 流量 :详解反向代理、正向代理、Global Monitor,以及 Cursor 的本地 transcript 监听。
• 流式传输入门:SSE 与 WebSocket :SSE 与 WebSocket 的协议模型、在 Trace 中的识别,以及连接资源与选型。

• Claude Code 工作机制(9 篇系列) :通过真实 Trace 拆解 Claude Code 的上下文压缩、分层记忆、Skills 沉淀与任务规划。
• Codex App 工作机制(9 篇系列) :通过 forward proxy 捕获的 Codex App 流量与 viewer 截图,拆解 typed input、工具循环、token/cache 与 App 动态工具。
• Codex CLI 工作机制:从真实 Trace 理解 :探索 OpenAI Codex CLI 的 Responses API、WebSocket 双向通信与状态管理。
• Antigravity 工作机制:从真实 Trace 理解 :逆向 Google Code Assist 底层协议与自定义 URL 桥接逻辑。
• 当前支持 Agent 横向对比 :横向对比各大 Agent 的认证、传输协议、Schema 风格及可观测性实现难点。

• 如何阅读一份 Trace :像侦探一样阅读 Trace 视图,通过上下文因果链快速还原和诊断 Agent 的失控行为。
• 新增 Agent 支持方法论 :如何为 claude-tap 编写配置,扩展支持全新的 Coding Agent 客户端。
• 使用 Q&A 与常见问题 :记录真实使用过程中的证书报错、数据跳号及环境兼容解决方案。
• 经典排障案例笔记 :DeepSeek 降级兼容、Codex WebSocket 解密等典型实战切片。

1. 零侵入捕获:不修改 Agent 源码;通过环境变量 / 启动参数 /(可选)用户配置写入,把流量导入本地代理,尽量保持被测 Agent 的真实运行路径。
2. 流式重组(SSE/WebSocket Reassembler):实时将 SSE 碎片和 WebSocket 帧拼装回完整结构,为分析提供高质量的"第一现场"。
3. 归一化视图(Normalization):将各厂商协议抽象为通用的 System、Messages、Tools、Response 及 Usage,实现"一套界面,看懂所有 Agent"。
4. 本地 SQLite 主存储:默认写入 ~/.local/share/claude-tap/traces.sqlite3(可用 CLOUDTAP_DB 覆盖);导出默认 compact / .ctap。