1. 项目缘起一个“套娃”式想法的诞生最近几个月Claude Code 在开发者圈子里火得一塌糊涂。作为一个深度体验过 Cursor、GitHub Copilot 和 Codeium 的老码农我第一时间就上手了 Claude Code。它的代码生成质量、对上下文的超强理解能力尤其是那个“思考过程”的展示确实让人眼前一亮。但用着用着一个老问题又浮现了调试。当 Claude Code 生成了一段复杂的逻辑或者重构了某个模块后我总想深入看看它内部到底是怎么“想”的变量状态如何流转函数调用栈是否清晰。可惜Claude Code 本身并没有提供一个像 Chrome DevTools 那样强大的、可视化的运行时调试面板。这个痛点让我萌生了一个有点“套娃”的想法能不能用 Claude Code 本身来为 Claude Code 开发一个专属的 DevTools 呢听起来像是自己造轮子来修自己的车但仔细一想这恰恰是检验一个 AI 编码助手能力的绝佳场景。它需要理解一个复杂 IDE 插件的架构、能够生成用于调试和监控其他代码的代码并且最终产物要具备良好的交互性。这不仅是功能的实现更是一次对 AI 辅助开发边界的探索。于是我决定动手把这个想法变成现实。2. 核心需求与架构设计我们要一个什么样的“DevTools”在开始敲代码之前明确目标至关重要。我们想要的不是一个简单的日志输出窗口而是一个功能相对完整、对开发者友好的调试辅助工具。我将其核心需求拆解为以下几点实时上下文洞察能够实时查看并可视化 Claude Code 在处理当前文件时其内部维护的“工作区上下文”是什么。这包括了它“看到”的哪些相关文件、从注释中提取的需求摘要、以及它对自己即将生成代码的“意图”理解。代码生成过程追踪像 Chrome DevTools 的 Performance 面板一样能够记录一次代码生成请求的完整生命周期。从接收用户指令到模型推理再到最终代码块输出每个阶段的耗时和关键节点都应该被捕捉和展示。生成代码的即时分析与验证在代码生成后无需手动复制粘贴工具能自动对生成的代码块进行基础语法检查、潜在风险提示例如是否引入了未声明的变量是否有可能的安全问题甚至可以估算复杂度。非侵入式集成这个 DevTools 本身不能影响 Claude Code 的正常工作。它应该作为一个独立的侧边栏面板或弹出窗口存在通过安全的 API 或事件监听机制与主进程通信避免直接修改 Claude Code 的核心源码。基于这些需求我设计了初步的架构。整个工具将分为三个主要部分数据采集层Agent这是一个运行在后台的轻量级服务或 VSCode 扩展。它的核心任务是“监听”。通过 VSCode 的扩展 API 和可能的进程间通信IPC它需要钩住HookClaude Code 插件与 Anthropic 服务通信的关键节点以及 Claude Code 内部的一些事件如上下文更新、代码生成开始/结束。这一层负责收集原始数据并进行初步的结构化处理。数据处理与转发层Bridge采集到的原始数据可能是杂乱的这一层负责过滤、聚合和格式化数据。例如将多次连续的上下文更新合并为一次“上下文快照”计算代码生成各阶段的耗时。然后通过 WebSocket 或类似的技术将处理好的数据实时推送给前端界面。可视化呈现层UI Dashboard一个独立的 Web 应用或基于 Webview 的 VSCode 面板。它接收来自 Bridge 的数据流并使用图表、树形组件、代码高亮编辑器等可视化元素将数据直观地展现出来。这是开发者直接交互的部分。这个架构的关键在于“松耦合”。数据采集层尽量轻量且专注UI 层可以独立开发和迭代中间通过一个清晰的数据协议进行通信。这样即使未来 Claude Code 的 API 有变动我们也只需要调整数据采集层而不必重写整个工具。3. 技术选型与实现难点在 VSCode 的生态里“做手术”确定了架构接下来就是技术选型。由于目标是给 VSCode 的 Claude Code 插件做工具自然要深度融入 VSCode 的生态。数据采集层毫无疑问选择VSCode Extension API。我们需要开发一个自己的 VSCode 扩展。难点在于如何“监听”另一个扩展Claude Code的内部状态直接访问其内存或变量是不可能的因为每个扩展都运行在独立的进程中。这里有几个突破口命令CommandsVSCode 扩展可以通过vscode.commands.registerCommand暴露命令。我们可以尝试查找 Claude Code 是否暴露了任何可用于诊断的内部命令通常不会。事件Events更可行的方法是监听 VSCode 本身的事件以及文本编辑器的变化。例如监听onDidChangeTextDocument可以知道代码何时被修改可能是 Claude Code 生成的监听onDidChangeActiveTextEditor可以知道焦点切换。但这只能获得间接信息。输出通道OutputChannel许多扩展会将日志输出到特定的 OutputChannel。我们可以尝试读取或监听 Claude Code 的输出通道来获取信息。这是相对容易且非侵入式的方法。网络请求拦截终极方案如果上述方法都无法获得足够数据最直接但也最复杂的方式是拦截 Claude Code 与 Anthropic 后端服务的网络通信。这可以在 Node.js 层面通过劫持http(s).request或使用像mitmproxy这样的代理来实现。但这需要极其谨慎因为涉及敏感的数据API Key、对话内容和安全问题必须在本机、离线、且仅用于调试的目的下进行并明确提示用户风险。我们的工具初期应避免使用此方法除非有非常清晰的安全提示和用户授权。数据处理与转发层这一层可以集成在采集层扩展里用一个简单的Node.js 服务器实现使用ws库创建 WebSocket 服务。它接收来自采集模块的数据做简单加工后广播给所有连接的 UI 客户端。可视化呈现层为了获得最大的灵活性和美观度我选择使用React TypeScript Vite构建一个独立的 Web 应用。然后通过 VSCode 的Webview API将这个 Web 应用嵌入到一个自定义的侧边栏面板中。这样我们可以利用丰富的 React 图表库如 Recharts、Ant Design Charts来绘制时间线、旭日图等并用 Monaco EditorVSCode 使用的编辑器来高亮显示被追踪的代码。注意安全与伦理边界在实现过程中尤其是涉及监听其他扩展或网络数据时必须时刻牢记安全与隐私。我们的工具应该所有数据处理均在用户本地完成不上传任何信息。明确告知用户工具正在收集哪些数据。提供一键清除所有本地收集数据的选项。在涉及潜在敏感操作如网络拦截时必须有显眼的、需要用户主动确认的授权步骤。正如网络热词中警告的“不要将代码粘贴到你不了解或尚未审阅自己的 devtools 控制台中”我们构建的工具本身也必须经得起审阅确保其行为是可预测、无恶意的。4. 分步实现实录从零搭建 Claude Code DevTools4.1 第一步创建 VSCode 扩展骨架首先使用 Yeoman 和generator-code脚手架快速生成一个 VSCode 扩展项目。npm install -g yo generator-code yo code在向导中选择“New Extension (TypeScript)”并命名为claude-code-devtools。生成的项目结构包含了package.json、src/extension.ts等核心文件。接下来修改package.json中的activationEvents和contributes。我们不希望扩展自动激活而是在用户需要时通过命令手动打开 DevTools 面板。{ activationEvents: [ onCommand:claude-code-devtools.openPanel ], contributes: { commands: [{ command: claude-code-devtools.openPanel, title: Open Claude Code DevTools }], viewsContainers: { activitybar: [{ id: claude-code-devtools, title: Claude DevTools, icon: media/icon.svg }] }, views: { claude-code-devtools: [{ id: claude-code-devtools.view, name: Insights }] } } }4.2 第二步实现 Webview 面板和数据通信在src/extension.ts中我们需要实现打开 Webview 面板的逻辑并建立扩展主进程与 Webview渲染进程之间的双向通信。// src/extension.ts import * as vscode from vscode; import * as path from path; export function activate(context: vscode.ExtensionContext) { // 注册命令用于打开面板 const disposable vscode.commands.registerCommand(claude-code-devtools.openPanel, () { // 创建并显示 Webview 面板 const panel vscode.window.createWebviewPanel( claudeCodeDevTools, Claude Code DevTools, vscode.ViewColumn.Two, // 在第二栏打开 { enableScripts: true, retainContextWhenHidden: true, // 面板隐藏时保持状态 localResourceRoots: [vscode.Uri.file(path.join(context.extensionPath, dist))] // 指向我们构建的 Web 应用 } ); // 设置 Webview 的 HTML 内容指向我们构建好的 React 应用入口文件 const appDistPath vscode.Uri.file(path.join(context.extensionPath, dist, index.html)); const appDistUri panel.webview.asWebviewUri(appDistPath); panel.webview.html getWebviewContent(appDistUri); // 处理来自 Webview 的消息 panel.webview.onDidReceiveMessage( async message { switch (message.command) { case alert: vscode.window.showErrorMessage(message.text); return; case requestData: // 当 Webview 请求数据时从数据采集器获取并发送回去 const data dataCollector.getSnapshot(); panel.webview.postMessage({ command: dataUpdate, data }); return; } }, undefined, context.subscriptions ); // 定期向 Webview 推送数据更新模拟 const intervalId setInterval(() { if (panel.visible) { const liveData dataCollector.getLiveData(); panel.webview.postMessage({ command: liveDataUpdate, data: liveData }); } }, 1000); // 每秒更新一次 // 面板关闭时清理定时器 panel.onDidDispose(() { clearInterval(intervalId); }, null, context.subscriptions); }); context.subscriptions.push(disposable); } function getWebviewContent(appUri: vscode.Uri): string { return !DOCTYPE html html langen head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleClaude Code DevTools/title /head body div idroot/div script src${appUri}/script /body /html; }4.3 第三步构建独立的前端 React 应用在项目根目录下我们新建一个frontend文件夹并使用 Vite 初始化一个 ReactTS 项目。cd /path/to/your/extension mkdir frontend cd frontend npm create vitelatest . -- --template react-ts安装必要的依赖npm install recharts socket.io-client monaco-editor/react我们的前端应用需要做几件事使用socket.io-client连接到扩展后台的 WebSocket 服务器用于接收实时数据流。使用 Recharts 渲染图表。使用monaco-editor/react展示代码片段。构建完成后将输出dist目录复制到扩展根目录的dist文件夹下供 Webview 引用。一个简单的App.tsx组件框架如下// frontend/src/App.tsx import { useEffect, useState } from react; import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, Legend } from recharts; import Editor from monaco-editor/react; import ./App.css; interface DataPoint { timestamp: number; contextSize: number; generationTime: number | null; } function App() { const [dataStream, setDataStream] useStateDataPoint[]([]); const [currentCode, setCurrentCode] useStatestring(// 生成的代码将显示在这里...); // 模拟从 WebSocket 接收数据 useEffect(() { const mockInterval setInterval(() { const newPoint: DataPoint { timestamp: Date.now(), contextSize: Math.floor(Math.random() * 1000), // 模拟上下文大小 generationTime: Math.random() 0.7 ? Math.random() * 3000 : null, // 模拟偶尔的生成耗时 }; setDataStream(prev [...prev.slice(-50), newPoint]); // 只保留最近50个点 }, 1000); return () clearInterval(mockInterval); }, []); // 监听来自 VSCode 扩展主进程的消息 (通过 postMessage) useEffect(() { const handleMessage (event: MessageEvent) { const message event.data; if (message.command liveDataUpdate) { console.log(Received live data:, message.data); // 更新状态... } if (message.command codeGenerated) { setCurrentCode(message.code || ); } }; window.addEventListener(message, handleMessage); return () window.removeEventListener(message, handleMessage); }, []); return ( div classNamedevtools-container h1Claude Code DevTools/h1 div classNamedashboard div classNamechart-section h2上下文大小与生成耗时趋势/h2 LineChart width{800} height{300} data{dataStream} CartesianGrid strokeDasharray3 3 / XAxis dataKeytimestamp tickFormatter{(ts) new Date(ts).toLocaleTimeString()} / YAxis yAxisIdleft / YAxis yAxisIdright orientationright / Tooltip / Legend / Line yAxisIdleft typemonotone dataKeycontextSize stroke#8884d8 name上下文大小(词元) / Line yAxisIdright typemonotone dataKeygenerationTime stroke#82ca9d name生成耗时(ms) connectNulls / /LineChart /div div classNamecode-section h2最近生成的代码/h2 Editor height400px languagetypescript themevs-dark value{currentCode} options{{ readOnly: true, minimap: { enabled: false } }} / /div /div /div ); } export default App;4.4 第四步实现核心数据采集器这是最具挑战性的一步。我们需要在扩展的后台src/dataCollector.ts实现一个类负责收集数据。如前所述我们从最安全、最易实现的方式开始。// src/dataCollector.ts import * as vscode from vscode; import { PerformanceObserver, performance } from perf_hooks; export class ClaudeCodeDataCollector { private contextSize: number 0; private lastGenerationStartTime: number | null null; private lastGenerationDuration: number | null null; private outputChannel: vscode.OutputChannel; constructor() { this.outputChannel vscode.window.createOutputChannel(Claude Code Internals); this.setupListeners(); } private setupListeners(): void { // 1. 监听编辑器活动变化推测可能是上下文切换 vscode.window.onDidChangeActiveTextEditor((editor) { if (editor) { this.onContextPotentialChange(activeEditorChange); } }); // 2. 监听文档变化这可能是 Claude Code 在插入代码 vscode.workspace.onDidChangeTextDocument((event) { // 这里可以添加启发式规则判断变化是否很大、是否在特定区域等来推测是否是 AI 生成 // 例如如果变化是短时间内的大段插入且内容看起来像生成的代码 if (event.contentChanges.length 0) { const change event.contentChanges[0]; if (change.text.length 50 !change.text.includes(//) change.text.includes(function)) { this.onCodeGenerated(change.text); } } }); // 3. 尝试查找并监听 Claude Code 的输出通道如果存在 // VSCode 的 API 没有直接获取其他扩展 OutputChannel 的方法。 // 一个变通方法是我们假设用户将 Claude Code 的输出重定向到我们的频道或者我们定期去“读取”可见的输出面板。 // 这是一个高级功能初期可以留空。 } private onContextPotentialChange(reason: string): void { // 这里可以模拟或尝试计算当前上下文的“大小” // 例如获取当前打开的所有相关文件的内容长度 // 这是一个简化版 this.contextSize Math.floor(Math.random() * 500 200); // 模拟 this.outputChannel.appendLine([${new Date().toISOString()}] Context updated (${reason}). Estimated size: ${this.contextSize}); } private onCodeGenerated(codeSnippet: string): void { const endTime performance.now(); if (this.lastGenerationStartTime) { this.lastGenerationDuration endTime - this.lastGenerationStartTime; this.outputChannel.appendLine([${new Date().toISOString()}] Code generation completed. Duration: ${this.lastGenerationDuration.toFixed(2)}ms); this.lastGenerationStartTime null; } // 触发事件通知 UI 更新 // 这里需要通过我们之前建立的通信机制通知 Webview } // 模拟一个生成开始事件在实际中可能需要更复杂的探测 public simulateGenerationStart(): void { this.lastGenerationStartTime performance.now(); this.outputChannel.appendLine([${new Date().toISOString()}] Code generation started.); } public getSnapshot(): any { return { contextSize: this.contextSize, lastGenerationDuration: this.lastGenerationDuration, timestamp: Date.now(), }; } public getLiveData(): any { // 返回实时数据流 return this.getSnapshot(); } } export const dataCollector new ClaudeCodeDataCollector();这个采集器目前还很基础主要依靠启发式规则和模拟数据。要使其真正强大需要更深入地对 Claude Code 插件进行逆向工程或等待其提供官方诊断接口。5. 集成、调试与效果展示将前端构建产物复制到扩展目录并修改 VSCode 扩展的打包脚本package.json中的scripts。{ scripts: { vscode:prepublish: npm run package, compile: tsc -p ./, watch: tsc -watch -p ./, package: vsce package, build-frontend: cd frontend npm run build, copy-frontend: copyfiles -u 1 frontend/dist/**/*.* ./dist/, build: npm run compile npm run build-frontend npm run copy-frontend } }现在运行npm run build会先编译 TypeScript 扩展代码再构建 React 前端最后将前端资源复制到正确位置。在 VSCode 中按下F5启动一个扩展开发宿主窗口。在新窗口中按下CtrlShiftP输入 “Open Claude Code DevTools” 执行命令你就能在侧边栏看到我们开发的工具面板了。效果展示 面板左侧是一个实时更新的折线图展示了“估算的上下文大小”和“上次代码生成耗时”随时间变化的趋势。当你使用 Claude Code 生成代码时如果能成功触发我们的探测逻辑图表上会出现一个代表生成耗时的峰值点。面板右侧是一个代码编辑器会显示最后一次探测到的、可能是由 Claude Code 生成的大段代码。下方还可以扩展出更多标签页例如“上下文文件列表”、“API 调用日志”、“性能分析详情”等。6. 遇到的坑与进阶思考在实际开发中我遇到了几个预料之中和预料之外的坑VSCode 扩展的隔离性这是最大的障碍。我们无法直接访问另一个扩展的运行时状态。目前的解决方案监听编辑器事件、分析输出都是间接且脆弱的。一个更稳定的方案是推动 Claude Code 的开发者提供一个官方的诊断 API或MCPModel Context Protocol服务器专门用于暴露调试信息。这样任何第三方调试工具都可以通过标准协议安全地获取数据。性能开销频繁的事件监听和数据处理可能会对 IDE 性能产生轻微影响。我们需要精心设计数据采样频率并对非活动窗口暂停数据收集。requestIdleCallback或 Web Worker 可以用来处理一些计算密集型的数据聚合任务。数据准确性通过启发式规则判断“是否由 AI 生成”误差很大。未来可以探索利用 Claude Code 生成代码时可能留下的“指纹”如特定的注释格式、代码风格来辅助判断或者结合更底层的编辑事件分析。功能深度目前的工具更像是一个“监视器”而非真正的“调试器”。一个真正的 DevTools 应该允许开发者“干预” AI 的行为例如手动编辑或添加上下文、重放某次生成请求、对生成的代码进行单步“心理模拟”等。这需要与 AI 模型有更深度的交互接口实现难度极大。这个项目让我深刻体会到为 AI 编码助手开发 DevTools其意义远不止于方便调试。它更像是一架“望远镜”让我们这些使用者能够窥见 AI 在编程时的“思考过程”从而更好地理解其能力边界建立更有效的协作模式。虽然目前这个工具还比较原始但它验证了技术路径的可行性。随着 Claude Code 等工具的生态逐渐开放我相信这类辅助调试和洞察的工具会变得越来越重要也期待有更强大、更官方的解决方案出现。毕竟最好的 DevTools或许最终应该由工具的创造者自己来提供。
