1. 项目缘起从“黑盒”对话到“解剖”Agent最近在折腾各种AI Agent和Skill开发不知道你有没有这种感觉很多时候Agent就像一个“黑盒”。你给它一个指令它返回一段结果中间到底发生了什么它“想”了什么调用了哪些工具为什么最终给出了这个答案很多时候我们只能看到输入和输出中间的“思考”过程尤其是那些复杂的、多步骤的会话就像一团迷雾。特别是在调试一个复杂的Skill或者排查Agent为什么给出了一个匪夷所思的回答时这种无力感尤为强烈。你只能对着最终的错误结果干瞪眼或者一遍遍重试试图复现问题效率极低。这让我想起了神话故事里的“照妖镜”——管你是什么妖魔鬼怪在镜子前一照都得现出原形。那么能不能给AI Agent也做一个“照妖镜”呢这个想法催生了「照妖镜」Skill项目。它的核心目标非常简单粗暴将Agent的一次完整会话过程从“黑盒”变成“白盒”让你能清晰地看到“真身”原始的、未经处理的会话日志与“灵魂”经过解析、结构化、可交互的思维链的对比。这不是一个简单的日志查看器而是一个深度分析工具旨在帮助开发者、产品经理甚至是终端用户理解AI决策的内在逻辑从而进行精准的优化、调试和信任构建。2. “照妖镜”的设计哲学不止于日志查看市面上已经有一些工具可以查看AI的请求和响应比如OpenAI Playground的控制台或者一些SDK自带的调试模式。但「照妖镜」Skill的定位不同它追求的是更深层次的“可观测性”。我们可以从两个核心维度来理解它的设计2.1 “真身”维度原始会话日志的忠实记录所谓“真身”就是最原始、未经任何修饰的会话数据流。这包括了原始请求体你发送给AI模型的完整Prompt包括系统指令、用户消息、上下文历史以及任何通过API传递的参数如temperature, max_tokens等。原始响应流AI模型返回的原始流式或非流式响应。对于支持思维链Chain-of-Thought或类似机制的模型如Claude这里会包含模型在“思考”过程中生成的所有中间文本这些往往是理解其推理过程的关键。工具调用记录如果Agent配置了函数调用Function Calling或工具使用Tool Use能力这里会精确记录每次工具调用的请求函数名、参数和工具的返回结果。元数据请求的时间戳、使用的模型名称、消耗的Token数、响应延迟等。“真身”部分的目标是完整性和保真度。它不做任何解释只是忠实地记录下发生的一切作为后续分析的“原始证据”。这部分数据通常以结构化的JSON格式存储便于程序化处理。2.2 “灵魂”维度结构化思维链的可视化呈现如果只有“真身”那它只是一个高级日志文件。“照妖镜”的核心价值在于“灵魂”部分——对原始日志进行深度解析和重构呈现出AI的“思维过程”。思维链提取与结构化对于像Claude这样的模型其响应中可能夹杂着类似“让我想想...”、“首先我需要...”这样的内部独白。Skill需要能智能地识别并提取这些“思考”片段将它们与最终的“回答”片段分离开来并组织成清晰的步骤。例如一个数学解题过程可以被解析为“步骤1理解问题 - 步骤2列出已知条件 - 步骤3尝试公式A - 步骤4发现公式A不适用 - 步骤5改用公式B - 步骤6计算并得出答案”。工具调用图谱对于使用了多个工具的复杂Agent单纯的列表记录不够直观。“灵魂”视图可以生成一个工具调用时序图或依赖关系图。清晰地展示出是用户提问触发了工具A工具A的结果又作为输入触发了工具B最后综合工具B的结果和初始上下文模型才生成了最终回答。这种可视化对于理解Agent的工作流和排查循环调用或死锁问题至关重要。决策点高亮与溯源在长长的思维链中哪里是关键的决策转折点为什么Agent在某个环节选择了方案A而不是方案B“照妖镜”可以尝试通过对比不同“思考”片段的置信度如果模型提供、或者通过关联工具调用的结果来高亮这些决策点。点击某个决策点可以直接关联到触发它的“思考”文本和当时可用的上下文实现决策溯源。“真身”与“灵魂”的联动对比这是交互设计的精髓。界面并排展示“原始日志”窗口和“解析视图”窗口。当你在“灵魂”视图解析视图中点击某一个思维步骤或工具调用节点时“真身”视图原始日志会自动滚动并高亮对应的原始文本区域。这种双向绑定让你能瞬间在“人类可读的解析”和“机器原始的记录”之间建立联系彻底看清每一句“人话”背后对应的“机器码”。3. 技术实现拆解如何打造这面“镜子”要实现上述功能我们需要一个清晰的技术栈和实现路径。这里以集成到VSCode的Claude Code插件生态为例进行说明因为这是目前很多AI编码助手的常见场景。3.1 核心架构事件拦截、解析与渲染整个Skill可以看作一个三层管道[数据采集层] - [解析引擎层] - [可视化渲染层]数据采集层这是第一步也是最关键的一步——拿到原始会话数据。有两种主流思路中间件模式推荐不修改Claude Code或Agent的核心代码而是创建一个“中间件”或“代理”。所有发给AI模型的请求和从AI模型返回的响应都先经过这个中间件。中间件在将数据透传给真实后端的同时复制一份完整的交互数据包括流式响应的每一个chunk存储到本地。这种方式侵入性低通用性强。在实现上可以劫持fetch或XMLHttpRequest或者对于Electron应用如VSCode可以拦截其IPC通信。插件API模式如果目标平台如某个Agent框架提供了完善的插件API允许插件订阅会话事件如onRequestStart,onTokenGenerated,onToolCall那么直接使用这些API是最规范的方式。这需要研究具体平台的插件开发文档。实操心得从零开始中间件模式是更稳妥的选择。你可以先针对一个固定的URL端点比如Claude Code与后端通信的特定API进行拦截和日志记录快速验证可行性。但要注意数据脱敏和安全避免记录和存储含有敏感信息的Token或密钥。解析引擎层这一层负责处理“脏数据”提炼出“灵魂”。它接收原始日志通常是JSON然后运行一系列解析器通用JSON解析器提取基础字段模型、时间戳、Token数。消息角色解析器区分system,user,assistant消息并识别assistant消息中可能存在的tool_calls部分。思维链探测解析器难点这是核心算法。一种简单规则是查找以特定关键词如“Thought:”, “I need to”, “首先”开头并以行动指令如“Action:”, “调用工具”或最终答案结尾的文本块。更高级的做法可以训练一个小型分类模型或者利用一个轻量级LLM如本地运行的Phi-3 mini来对响应文本进行分段和分类标注。工具调用关系分析器分析多次工具调用的输入输出尝试构建调用顺序和依赖关系。例如工具B的输入参数中包含了工具A输出结果里的某个字段则可以判定B依赖于A。可视化渲染层将解析后的结构化数据通过Web界面呈现出来。可以考虑使用React TypeScript构建交互式UI的主流选择。D3.js 或 AntV G6用于绘制复杂的工具调用关系图、思维链流程图。Monaco Editor用于高亮显示原始JSON日志提供类似代码编辑器的查看体验可折叠、语法高亮。状态管理使用Zustand或Redux来管理“真身”和“灵魂”视图的联动状态如当前选中的节点。3.2 与Claude Code/Codex的集成实战假设我们要为VSCode中的Claude Code插件开发这个Skill。Claude Code通常通过VSCode的扩展API与UI交互并与后端服务通信。环境侦察首先需要弄清楚Claude Code的数据流。打开VSCode开发者工具Developer: Toggle Developer Tools切换到Network网络面板然后在Claude Code的输入框里进行一次对话。观察有哪些网络请求其请求体和响应体是什么格式。你很可能找到向https://api.anthropic.com/...或类似后端发送的POST请求。这就是我们要拦截的关键端点。创建VSCode扩展使用yo code脚手架生成一个新的VSCode扩展项目。我们主要需要实现一个TreeDataProvider来在侧边栏显示历史会话列表以及一个WebviewPanel来承载复杂的“照妖镜”分析界面。实现请求拦截在扩展的激活函数中我们可以尝试通过vscode.debug.registerDebugAdapterTrackerFactory如果Claude Code使用Debug Adapter Protocol或更通用的方法——重写window.fetch和XMLHttpRequest——来拦截特定URL模式的请求。注意这种方法需要谨慎可能与其他扩展冲突且随着VSCode或Claude Code更新可能失效。更优雅的方式是寻找Claude Code是否暴露了日志接口或事件总线。// 示例一个非常基础的fetch拦截思路概念性代码生产环境需完善 const originalFetch window.fetch; window.fetch async function(resource, init) { const requestUrl typeof resource string ? resource : resource.url; // 判断是否为Claude Code的后端API请求 if (requestUrl.includes(api.anthropic.com) init?.method POST) { const requestClone init.body ? JSON.parse(init.body) : null; console.log([照妖镜] 拦截到请求:, requestUrl, requestClone); const response await originalFetch.call(this, resource, init); const responseClone response.clone(); const responseBody await responseClone.json(); console.log([照妖镜] 拦截到响应:, responseBody); // 将日志存储到扩展的全局状态或发送到Webview // ... your logic here ... // 返回原始响应 return response; } return originalFetch.call(this, resource, init); };构建Webview分析界面在WebviewPanel中使用React构建双栏界面。左侧栏以树形结构或时间线展示所有拦截到的会话。点击一个会话后右侧分为上下两栏上栏是“真身”原始JSON使用Monaco Editor显示下栏是“灵魂”用流程图展示思维链用列表展示工具调用。实现联动当用户在“灵魂”视图的流程图中点击一个节点例如“步骤3调用搜索引擎工具”我们需要解析出这个节点在原始JSON日志中对应的文本范围可能是response.choices[0].message.content中的某一段。然后通过postMessage通知Webview中的Monaco Editor让其滚动到指定位置并高亮该段文本。3.3 解析算法从杂乱文本中提取思维链这是技术挑战最大的一部分。对于Claude模型其思维链可能没有固定的格式。一个实用的、渐进式的解析策略如下基于规则的第一轮粗筛定义一组正则表达式或关键词列表用于捕捉常见的思维链开头和结尾。# 示例简单的规则匹配 thought_patterns [ r^(让我想想|首先|第一步|我们需要|Thought:|I think), r^(因此|所以|最终|答案是|Answer:|最终输出) ] # 将响应文本按行或按句分割尝试匹配这些模式来划分段落。利用消息结构如果Agent框架在消息格式上做了规范比如明确使用了thinking和/thinking这样的XML标签来包裹内部思考那么解析将变得非常简单。遗憾的是很多情况下并没有。引入轻量级LLM进行标注进阶当规则无法准确分割时可以调用一个本地的小模型如通过Ollama运行的Llama 3.2 3B或Phi-3.5 mini进行文本分类。Prompt可以设计为“请将以下AI助手的回复分割成连续的‘思考步骤’和‘最终回答’部分。如果某一段是内部推理输出type: reasoning如果是最终给用户的答案输出type: final_answer。只输出JSON格式。” 这种方法准确率高但会引入额外的延迟和计算资源消耗适合离线分析模式。工具调用的标准化处理这部分相对规范。通常工具调用会以结构化格式如JSON嵌入在消息的tool_calls字段中。解析器需要将tool_calls数组中的每个元素与其后一条包含tool_responses的消息关联起来形成一个“调用-响应”对。4. 应用场景与价值谁需要这面“镜子”“照妖镜”Skill的价值远不止于“好玩”或“炫技”它在多个实际场景中能发挥关键作用对于开发者Agent/Skill CreatorDebugging神器当你的Agent行为异常时不再需要盲目猜测。直接打开“照妖镜”回溯整个会话看看到底是哪一步的“思考”出了偏差或者是哪个工具返回了意外结果导致最终答案错误。定位问题的效率提升十倍不止。Prompt工程优化你可以清晰地看到不同的系统指令System Prompt是如何影响模型思考路径的。是Prompt A让模型更早地意识到了需要调用工具还是Prompt B让它的推理更缜密通过对比不同Prompt下的“灵魂”视图你可以进行数据驱动的Prompt优化。性能分析与优化统计每个会话中思考步骤的多少、工具调用的次数和耗时。你会发现某些复杂问题导致模型陷入了不必要的长链思考。这可以帮助你重新设计Agent的工作流比如引入更早的“决策点”来打断低效推理或者优化工具的设计以减少调用层级。对于产品经理与运营者理解用户与AI的交互瓶颈分析大量会话日志发现用户经常在哪些问题上AI的思考过程变得冗长或混乱这可能是产品功能设计或知识库的短板需要针对性加强。构建信任与透明度对于面向最终用户的产品提供一个“查看AI思考过程”的按钮由“照妖镜”的简化版提供支持可以极大地增加产品的透明度和可信度。用户不再觉得AI是个神秘的“黑箱”而是能看到其逻辑即使最终答案不对也更容易理解原因。对于AI研究者与学习者学习高级Prompt技巧通过观察优秀Agent的思考过程就像在看高手的“棋谱”是学习如何构建有效Prompt和Agent工作流的绝佳方式。模型行为研究对比不同模型如Claude 3.5 Sonnet vs GPT-4o在解决同一问题时的思维链差异可以直观地感受不同模型的能力特点和“性格”偏向。5. 开发中的“坑”与应对策略在实现这样一个深度集成的工具时踩坑是必然的。以下是我在构思和类似项目实践中遇到的一些典型问题坑1数据拦截的稳定性与兼容性问题直接覆写window.fetch的方法非常脆弱。Claude Code插件更新后其内部通信机制可能改变其他扩展也可能做类似拦截导致冲突在VSCode的Webview安全沙箱中这种方法可能根本不可用。应对优先寻找官方接口彻底查阅Claude Code或目标Agent框架的官方插件开发文档看是否有事件订阅机制。降级方案如果无法实现实时拦截可以做一个“日志导入分析”功能。让用户手动导出Claude Code的会话日志如果它提供此功能或者定期从某个日志文件中读取数据然后由“照妖镜”进行离线分析。虽然失去了实时性但核心的分析价值仍在。使用更底层的调试工具对于桌面端应用可以考虑使用像Fiddler或Charles这样的代理工具全局抓包然后让“照妖镜”Skill去读取这些代理工具生成的日志文件。这需要用户进行额外配置但通用性最强。坑2思维链解析的准确率问题基于规则的解析器面对模型自由生成的、格式多变的文本准确率很难保证。可能会把最终答案的一部分误判为思考或者漏掉一些没有明显标志的推理步骤。应对规则启发式不要只依赖开头关键词。结合段落长度、是否包含疑问句、是否在描述过程而非给出结论等启发式规则进行综合判断。提供手动校正界面在“照妖镜”的UI中允许用户对自动解析的结果进行手动合并、拆分或重新标注。并将用户校正后的结果作为训练数据反馈给系统逐步优化规则或微调一个小型分类模型。明确适用范围在Skill说明中坦诚其局限性说明它对于格式相对规范的Claude/Codex响应效果较好对于完全自由格式的文本可能解析不全。坑3性能与数据量问题长时间的编码会话日志可能非常庞大。在Webview中渲染一个包含数万行JSON的Monaco Editor或者绘制一个包含上百个节点的复杂关系图可能导致界面卡顿。应对虚拟滚动与分页对原始日志和思维链步骤列表实施虚拟滚动只渲染可视区域内的内容。增量加载与聚合初始只加载会话的元数据和概要。当用户点击查看详情时再按需加载该会话的完整日志和解析结果。对于工具调用图如果节点过多可以先展示一个高级别的聚合视图如将同一类型的多次调用合并为一个节点。Web Worker将耗时的解析计算如使用本地LLM进行标注放到Web Worker中执行避免阻塞主线程和UI响应。坑4隐私与安全问题会话日志可能包含敏感的代码片段、业务数据或个人隐私信息。如何安全地存储、传输和展示这些数据应对本地优先所有日志数据默认只存储在用户本地不上传任何云端。在Skill的设置中明确强调这一点。数据脱敏选项提供设置选项允许用户自动过滤掉日志中可能包含的密码、密钥、IP地址等模式的内容通过正则表达式。清晰的权限告知在Skill安装或首次运行时明确告知用户它会读取和分析哪些数据取得用户知情同意。6. 开源与生态展望将“照妖镜”Skill开源其意义在于构建一个标准。我希望它不仅仅是一个工具更成为一种可观测性的实践范式。开源后社区可以共同开发针对不同Agent框架的适配器目前设计可能偏向Claude Code但通过插件化架构可以轻松为其他框架如LangChain, LlamaIndex, CrewAI开发数据采集适配器让“照妖镜”成为多框架通用的调试平台。丰富解析器插件库社区可以贡献针对不同模型GPT, Gemini, DeepSeek等或特定任务代码生成、数据分析、创意写作优化的思维链解析器。定义共享的日志格式标准或许可以推动一个轻量级的“AI会话跟踪格式”类似OpenTelemetry for AI让不同的Agent框架和工具都能以统一的格式输出可解析的日志从而被“照妖镜”这样的工具消费。这个项目的最终愿景是让开发和理解AI Agent变得像调试普通软件一样拥有清晰的堆栈信息、执行轨迹和变量状态。当“照妖镜”照向Agent时我们看到的将不再是一个模糊的魔法黑箱而是一个由逻辑、数据和决策构成的、清晰可见的数字生命体。这不仅是技术的进步更是人机协作走向深度信任和高效协同的必经之路。