1. 项目概述深入AI编码代理的“黑匣子”如果你正在使用Claude Code这类AI编码助手有没有那么一刻感到好奇当你在终端里输入一个指令比如“帮我重构这个API控制器”背后到底发生了什么AI助手是如何理解你的意图又是如何一步步调用工具、生成代码的整个过程就像一个“黑匣子”我们只能看到最终输出的代码却对中间复杂的决策链、API交互和工具调用过程一无所知。这正是Coding Agent Explorer要解决的问题——它是一款基于.NET构建的实时代理与可视化仪表盘专门用于拦截、分析和可视化Claude Code与Anthropic API之间的每一次通信。简单来说Coding Agent Explorer就是一个“中间人”。它在你本地的Claude Code客户端和远端的Anthropic API服务器之间架起一座透明的桥梁。所有流经这座桥的数据——无论是你提交的提示词、AI返回的流式响应、调用的MCP工具请求还是Claude Code内部触发的各种钩子事件——都会被它捕获、解析并以清晰直观的方式呈现在一个Web仪表盘中。这不仅仅是查看原始的JSON数据而是将其转化为开发者能轻松理解的对话时间线、HTTP请求详情和工具调用视图。为什么需要这样一个工具对于开发者而言尤其是那些希望深入理解AI Agent工作原理、进行调试或教学的人来说这种透明性至关重要。它能帮你调试与优化当AI助手给出的代码不符合预期时你可以追溯完整的交互历史看看是提示词理解有偏差还是某个工具调用返回了错误数据。学习与教学直观地展示AI编码代理的“思考过程”是学习Prompt工程、理解MCP协议以及教授AI开发概念的绝佳方式。性能监控实时查看每次请求的Token消耗、响应时间帮助你评估不同提示策略的成本与效率。这个项目完全开源基于.NET技术栈意味着它轻量、高效并且可以轻松地在Windows、macOS和Linux上运行。接下来我将带你从零开始深入它的每一个核心组件并分享在实际使用中积累的配置技巧和避坑经验。2. 核心架构与设计思路解析2.1 为什么选择反向代理模式Coding Agent Explorer的核心是一个运行在本地8888端口的反向代理。这种设计选择背后有深刻的考量。首先非侵入性是关键。我们不想、也不能去修改Claude Code客户端或Anthropic API服务器的代码。反向代理模式完美地解决了这个问题——你只需要通过环境变量告诉Claude Code“请把你的所有请求都发送到localhost:8888”剩下的路由和转发工作由代理自动完成。对Claude Code而言这个代理就是它眼中的“API服务器”对真正的API服务器而言这个代理就是一个普通的客户端。这种透明性使得工具可以无缝接入现有工作流。其次数据捕获的完整性得以保证。作为所有流量的必经之路代理可以无遗漏地捕获到原始的HTTP请求和响应包括Headers、Body以及Server-Sent Events流。这是实现深度分析的基础。项目使用了微软官方的YARP库来构建这个反向代理。YARP是一个高性能、可扩展的反向代理工具包专为.NET设计它抽象了底层HTTP转发的复杂性让我们可以专注于实现请求/响应的捕获和转换逻辑。注意由于代理运行在本地且仅监听localhost这意味着它默认是安全的不会将你的API流量暴露到外部网络。你的API密钥等敏感信息在代理层会被自动脱敏处理这是设计时首要考虑的安全原则。2.2 实时仪表盘SignalR的力量捕获数据只是第一步如何让开发者实时地看到这些数据同样重要。项目采用ASP.NET Core内置的SignalR技术来构建实时通信层。每当代理捕获到一个新的请求、响应或SSE事件时后端服务会通过SignalR Hub立即向所有已连接的Web客户端广播消息。前端仪表盘一个纯HTML/JS/CSS的单页应用在加载时就会建立这个SignalR连接。因此你在Claude Code终端中的每一次操作几乎都能在仪表盘上得到毫秒级的反馈。这种实时性对于调试动态的、流式的AI交互过程至关重要。你可以在AI生成代码的同时在仪表盘上看到Token是如何被逐个消耗的或者观察一个复杂的工具调用链是如何被拆解和执行的。2.3 内存存储与性能权衡考虑到这是一个本地调试和教学工具项目选择了内存存储作为数据持久化方案。所有捕获的请求、事件都被存储在一个内存中的环形缓冲区里默认容量是1000条。当数量超过上限时最旧的数据会被自动丢弃。这个设计是性能与实用性的平衡。将数据保存在内存中避免了磁盘I/O带来的延迟保证了仪表盘响应的极致速度。同时1000条的容量对于单次调试会话或教学演示来说通常绰绰有余。当然这也意味着关闭Coding Agent Explorer后所有历史数据都会丢失。如果你有长期审计或分析的需求可能需要基于现有的IRequestStore接口自行实现一个持久化存储例如存入SQLite或文件。2.4 模块化设计三大视图各司其职仪表盘提供了三个互补的视图从不同维度呈现相同的数据集这是项目设计上的一个亮点HTTP Inspector面向“协议层”。它以表格形式展示原始的HTTP事务适合需要查看精确的Header、状态码、耗时和原始JSON体的开发者。这是进行底层网络问题排查的利器。Conversation View面向“业务层”。它将原始的API调用序列重构成一个类似聊天界面的时间线。在这里你能看到“用户说”、“AI说”、“工具被调用”这样的自然语言描述使得复杂的多轮交互变得一目了然。这是理解AI“思考”逻辑的最佳视图。MCP Observer面向“工具层”。它专门用于拦截和展示Claude Code与外部MCP服务器之间的通信。这对于开发或调试自定义MCP工具至关重要你可以清晰地看到工具列表的获取、参数传递和结果返回的全过程。这种分离关注点的设计使得无论是新手想快速了解对话脉络还是专家需要深挖某个请求的细节都能找到合适的切入点。3. 环境搭建与核心配置详解3.1 基础环境准备.NET SDK的版本选择项目明确要求.NET 10 SDK或更高版本。这是一个硬性要求因为项目可能使用了C# 12或.NET 10引入的新API。我建议直接从 微软官方下载页面 获取最新的.NET SDK而不是使用系统包管理器可能提供的旧版本。安装完成后在终端运行dotnet --version确认版本号。实操心得如果你机器上同时存在多个.NET版本可以通过global.json文件在项目目录下锁定特定版本。在CodingAgentExplorer根目录创建一个global.json文件内容为{sdk: {version: 10.0.0}}这样可以确保构建环境的一致性避免因SDK版本差异导致的意外问题。3.2 项目获取与初次运行获取项目代码很简单使用Git克隆即可git clone https://github.com/tndata/CodingAgentExplorer.git cd CodingAgentExplorer接下来是标准的.NET项目构建和运行流程dotnet build dotnet run --project CodingAgentExplorer这两条命令会编译项目并启动应用。成功启动后控制台会输出类似以下信息表明四个核心服务端点已经就绪info: Microsoft.Hosting.Lifetime[14] Now listening on: http://localhost:8888 # 反向代理端口 (Claude Code连接此端口) info: Microsoft.Hosting.Lifetime[14] Now listening on: http://localhost:9999 # MCP代理端口 (用于MCP Observer) info: Microsoft.Hosting.Lifetime[14] Now listening on: http://localhost:5000 # HTTP仪表盘端口 info: Microsoft.Hosting.Lifetime[14] Now listening on: https://localhost:5001 # HTTPS仪表盘端口 (浏览器自动打开)在Windows系统上执行dotnet run后默认浏览器会自动打开https://localhost:5001。在macOS或Linux上你需要手动在浏览器中访问这个地址。3.3 配置Claude Code使用代理环境变量的艺术这是最关键的一步——让Claude Code的流量经过我们的代理。Claude Code通过ANTHROPIC_BASE_URL这个环境变量来指定其API端点。我们需要将它从默认的https://api.anthropic.com改为我们的代理地址http://localhost:8888。项目贴心地为不同平台提供了脚本Linux/macOS使用source EnableProxy.sh。务必注意这里必须用source命令或.点号而不是直接执行bash EnableProxy.sh。因为source会在当前Shell进程中执行脚本从而使得设置的环境变量对后续的claude命令生效。如果直接用bash执行环境变量会设置在一个子Shell中退出脚本后就失效了。Windows (CMD)直接运行EnableProxy.bat即可。Windows (PowerShell)需要手动设置环境变量$env:ANTHROPIC_BASE_URL http://localhost:8888。完成设置后强烈建议验证一下环境变量是否已生效# Linux/macOS/PowerShell echo $ANTHROPIC_BASE_URL # Windows CMD echo %ANTHROPIC_BASE_URL%应该输出http://localhost:8888。重要提示这些脚本设置的环境变量都是会话级的只对当前打开的终端窗口有效。关闭终端窗口设置就会失效。这其实是一个安全且方便的特性避免了全局环境变量污染。当你完成调试后运行对应的DisableProxy脚本或直接关闭终端即可。3.4 仪表盘初探与视图切换打开浏览器访问https://localhost:5001你会看到仪表盘的主页。页面顶部通常会有标签页或导航栏让你在HTTP Inspector、Conversation View和MCP Observer三个核心视图间切换。此时如果你在配置好代理的终端里运行任何claude命令比如claude status仪表盘上应该立即出现对应的HTTP请求记录。在HTTP Inspector视图你会看到一个表格新增了一行显示了请求方法、路径、状态码和耗时。在Conversation View你可能会看到一条“Session Start”之类的系统消息。这表明代理已经成功介入并开始工作了。4. 核心功能深度解析与实操4.1 HTTP Inspector网络请求的显微镜HTTP Inspector视图是理解底层通信的基石。它的界面通常是一个表格每一行代表一次HTTP请求/响应往返。点击任意一行可以展开查看详情面板这里的信息最为丰富请求详情包括完整的URL、HTTP方法、所有请求头。特别注意Authorization或x-api-key这样的头部你会看到它们的值被自动替换成了[REDACTED]这是代理的安全特性。请求体Body也会以格式化Pretty-Print的JSON形式展示方便你检查发送给API的提示词、系统指令等具体内容。响应详情展示状态码、响应头以及最重要的——响应体。对于Claude API的流式响应这里会显示为一个SSE事件列表。每个事件都是一个独立的JSON块你可以清晰地看到AI是如何“思考”并逐步输出内容的。时序与用量这里会显示请求的发起时间、总耗时、以及估算的Token使用情况输入Token、输出Token。这对于成本监控和性能优化非常有帮助。实操技巧当你发现Claude Code行为异常时首先检查HTTP Inspector。查看失败请求的状态码如429表示速率限制401表示认证失败。仔细比对请求体中的messages数组确认你的提示词是否被正确编码和传递。有时一个多余的换行符或编码问题都可能导致AI理解偏差。4.2 Conversation View对话逻辑的翻译官如果说HTTP Inspector展示的是“机器语言”那么Conversation View展示的就是“人类语言”。这个视图的目标是将一系列离散的API调用重构为一个连贯的、可读的对话故事。它的工作原理是解析每个API请求/响应中的messages和tool_calls字段。例如一个用户消息会被渲染为“User”气泡AI的回复被渲染为“Assistant”气泡。当AI决定调用一个工具比如读取文件时视图会显示一个“Tool Call”事件并附上工具名和参数。当工具返回结果后又会显示一个“Tool Result”事件。这个视图的强大之处在于它能整合HookAgent发送的事件。例如一个PreToolUse钩子事件会作为一个系统消息插入到时间线中明确告诉你“AI即将调用工具X”。这使得整个Agent的执行流程变得完全透明。避坑指南Conversation View的渲染依赖于对Anthropic API数据结构的正确解析。如果未来API格式发生重大变更这个视图可能需要更新。不过由于项目开源你可以根据最新的API文档来调整相关的解析逻辑主要在Services/目录下的模型类中。4.3 MCP Observer工具调用的监视器Model Context Protocol是Claude Code与外部世界交互的桥梁。MCP Observer视图允许你“窃听”Claude Code与任何HTTP MCP服务器之间的所有对话。配置步骤确保Coding AgentExplorer正在运行。在浏览器中打开https://localhost:5001/mcp/index.html。在“Destination URL”输入框中填入你想要观察的真实MCP服务器地址例如https://learn.microsoft.com/api/mcp然后点击“Set”。最关键的一步在终端中告诉Claude Code使用我们的代理作为MCP服务器claude mcp add --transport http mcp_proxy http://localhost:9999这个命令创建了一个名为mcp_proxy的MCP服务器配置其地址指向本地代理的9999端口。完成以上步骤后所有Claude Code发往MCP服务器的请求都会先经过9999端口的代理被仪表盘捕获和展示后再被转发到你设置的真实目的地。在MCP Observer视图你会看到类似HTTP Inspector的列表但内容专门针对MCP的JSON-RPC协议。你可以看到initialize、tools/list、tools/call等方法的调用。点击一个tools/call请求你能看到调用了哪个工具、传递了什么参数以及服务器返回的具体内容如查询到的文档片段。实操心得在开发自己的MCP工具时这个视图是无价之宝。你可以实时验证工具的定义tools/list的返回是否正确调试工具调用tools/call的参数解析和响应格式是否符合MCP规范。它极大地缩短了MCP工具开发的反馈循环。4.4 HookAgent深度集成的事件捕获器HookAgent是一个独立的、轻量级的命令行工具它的唯一使命就是充当Claude Code钩子系统与Coding AgentExplorer仪表盘之间的信使。工作原理Claude Code在执行特定动作如会话开始、用户提交提示、工具调用前后等时会调用外部配置的钩子命令。它会将事件信息JSON格式通过标准输入传递给这个命令并等待命令执行完毕读取其退出码和标准输出/错误。HookAgent就是这个被调用的命令。它做三件事从标准输入读取Claude Code传来的JSON数据。收集当前的环境变量如项目目录CLAUDE_PROJECT_DIR。将所有这些信息通过HTTP POST发送到运行在localhost:5000的仪表盘后端。将仪表盘返回的响应可包含自定义的退出码、输出信息传回给Claude Code。部署HookAgent首先运行项目根目录的发布脚本生成可执行文件。Windows:publish.batmacOS/Linux:bash publish.sh这会在Published/目录下生成HookAgent可执行文件。将生成的HookAgent文件夹包含可执行文件复制到你的项目工作目录下或者将其所在目录添加到系统的PATH环境变量中以便全局调用。将项目HookAgent/Sample-Settings-*目录下的settings.json文件复制到你的项目根目录下的.claude/文件夹中。这个配置文件定义了15种不同的钩子事件并指定它们都调用HookAgent命令。一个关键细节在Windows上即使使用CMD或PowerShellClaude Code内部也是通过一个兼容层来调用钩子命令的这个兼容层期望类Unix的路径分隔符。因此在settings.json中指定HookAgent路径时必须使用正斜杠例如command: HookAgent/HookAgent.exe即使你在Windows上。验证是否工作在启动Claude Code会话之前你可以手动测试HookAgent。打开一个终端确保仪表盘在运行然后执行echo {hook_event_name:UserPromptSubmit,session_id:test} | ./HookAgent/HookAgent如果一切正常你应该立即在Conversation View中看到一条“UserPromptSubmit”事件出现。如果仪表盘没运行HookAgent会安静地以0退出码结束不会阻塞Claude Code。5. 高级应用场景与故障排查5.1 场景一调试复杂的多步骤代码生成任务假设你让Claude Code“为我的用户模型添加CRUD API端点”。结果生成的代码结构混乱。如何排查打开Conversation View查看完整的对话时间线。确认你的初始指令是否被准确理解。AI是否先要求了更多上下文它是否将任务分解成了多个子步骤切换到HTTP Inspector找到生成代码的那个具体API响应。展开响应体查看AI返回的完整消息。也许AI提供了多个选项或解释了它的设计思路但这些在终端输出中被简化了。检查工具调用在Conversation View中关注PreToolUse和PostToolUse事件。AI读取了哪些现有文件它调用了write_file工具几次每次写入的内容是什么可能问题出在它基于一个过时的或错误理解的文件内容进行了生成。分析Token使用在HTTP Inspector中查看该请求的Token计数。如果输入Token异常多可能是你的系统指令或上下文过于冗长干扰了AI的主要任务。5.2 场景二开发与调试自定义MCP工具你为团队内部知识库编写了一个MCP工具query_kb但在Claude Code中调用时总返回空。配置MCP Observer将目的地URL设置为你的MCP服务器地址如http://localhost:8080并在Claude Code中注册代理。观察tools/list请求首先确认你的工具是否正确地出现在Claude Code获取的工具列表中。检查工具的名称、描述、输入参数schema是否与你的服务器定义一致。观察tools/call请求与响应当你在Claude Code中触发工具调用时在MCP Observer中会看到对应的请求。检查请求中的参数是否正确。然后查看服务器的响应。如果响应体是空的或者格式不符合MCP规范例如缺少content字段这里会一目了然。查看服务器日志结合MCP Observer显示的请求ID和时间戳去你的MCP服务器日志中查找对应的处理记录进行交叉比对。5.3 常见问题与解决方案速查表问题现象可能原因排查步骤与解决方案仪表盘无法打开(localhost:5001)1. Coding AgentExplorer未成功启动。2. 端口被占用。3. 浏览器HTTPS证书警告。1. 检查终端是否有错误输出确保dotnet run成功。2. 运行netstat -ano | findstr :5001(Win) 或lsof -i :5001(macOS/Linux) 查看端口占用修改appsettings.json中的端口。3. 这是开发自签名证书的正常警告点击“高级”-“继续前往”即可。Claude Code请求未出现在仪表盘1.ANTHROPIC_BASE_URL环境变量未设置或设置错误。2. 代理服务(8888端口)未运行。3. Claude Code使用了缓存的配置。1. 在运行claude的终端中用echo $ANTHROPIC_BASE_URL确认变量值为http://localhost:8888。2. 确认Coding AgentExplorer控制台显示8888端口在监听。3. 尝试重启Claude Code或使用新终端。HookAgent事件未显示1. HookAgent可执行文件路径配置错误。2..claude/settings.json文件未放置正确。3. HookAgent与仪表盘通信失败。1. 检查settings.json中的command路径Windows确保用正斜杠。2. 确认settings.json在项目根目录的.claude/文件夹下。3. 手动运行echo ... | HookAgent测试并查看仪表盘后端日志。MCP Observer中无流量1. MCP服务器URL未在仪表盘界面设置。2. Claude Code中未正确添加MCP代理配置。3. 当前对话未触发MCP工具调用。1. 刷新MCP Observer页面确认“Destination URL”已设置并显示“Connected”。2. 运行claude mcp list确认mcp_proxy在列表中。3. 在Claude Code中尝试明确要求使用MCP工具如“请用MCP工具查询文档”。仪表盘界面卡顿或无更新1. 捕获的请求数量过多(接近1000条)。2. 浏览器内存占用过高。3. SignalR连接断开。1. 点击仪表盘上的“Clear”按钮清空历史记录。2. 刷新浏览器页面。3. 检查浏览器开发者工具(F12)的“网络”选项卡查看WebSocket连接状态。5.4 性能与资源管理建议Coding AgentExplorer作为本地调试工具通常资源消耗不大。但如果你进行长时间、高强度的会话需要注意内存使用内存中最多存储1000条请求每条请求的完整数据包括Header、Body都会保存。对于非常复杂的对话或大型文件传输这可能会占用较多内存。如果发现内存增长定期点击仪表盘上的“Clear”按钮清理记录。网络延迟代理会增加微小的网络延迟因为请求需要额外经过本地环路。对于绝大多数调试场景这个延迟可以忽略不计。但在进行性能基准测试时请记得禁用代理。磁盘空间项目本身不写日志到磁盘除非你修改了配置。发布脚本生成的Published/文件夹包含所有运行时文件占用空间约几十MB清理即可释放。这个工具打开了一扇窗让我们得以窥见AI编码代理内部精巧而复杂的运作机制。从模糊的自然语言指令到一行行可执行的代码中间经历的解析、规划、工具调用和生成步骤现在都变得清晰可见。无论是用于解决一个棘手的生成问题还是作为教学工具向他人展示AI Agent的能力边界亦或是作为自己开发MCP工具时的调试伴侣Coding Agent Explorer都提供了一个不可多得的视角。