为Codex装上可视化仪表盘：让AI编码过程不再黑盒

说实话，用Codex跑任务的那段时间，我做的最多的一件事就是盯着终端窗口发呆。看着日志一行行刷过去，我经常忍不住问自己：它现在到底在干什么？分析到第几步了？改了哪几个文件？测试到底过没过？终端就像一个黑匣子，AI在里面忙得热火朝天，我只能站在门外干等。这种憋屈感在某天下午达到了顶峰——我丢给它一个"把项目里所有API错误处理统一重构"的任务，然后它沉默了四分钟，我完全不知道它是卡住了还是在认真干活。就在那一刻我决定，必须给Codex造一个"可视化办公室"：一块实时更新的网页面板，把任务进度、文件变更、测试结果、Token消耗全部摆到明面上。这篇文章就是整个搭建过程的完整记录，从需求拆解、架构设计到核心代码实现，再到那些折腾了我好几个晚上的坑，希望对那些想让Codex从"黑盒"变成"透明车间"的开发者有点用。

1. 为什么要给一个终端工具做"办公室"——需求拆解与方案选型

1.1 终端里的Codex到底缺什么

先说清楚，Codex本身是很好用的命令行AI编码工具，你给它一个任务描述，它会自主分析代码、修改文件、运行测试，甚至能连着执行多条命令。但问题恰恰出在"自主"这两个字上——任务一旦跑起来，过程对你来说基本不可见。

我列一下最直接的几个痛点：

• 过程黑洞：你不知道当前正在执行的操作是什么，只能看到刷屏的输出，经常是"执行了但又像没执行"。
• 多任务混乱：同时跑两三个Codex任务时，每个终端的进度完全靠记忆区分，切来切去很容易搞混。
• 文件变更不可回溯：任务结束以后，我常常需要自己再用git diff去看它到底改了哪些文件，有些改动甚至被后续操作覆盖掉了。
• 失败定位困难：一个任务失败，你只看到最后一段报错，不知道是哪一步引发的，更不知道之前改过的文件里哪些是好的、哪些需要回滚。
• 无法沉淀数据：这个任务跑了多久？改了多少文件？测试通过率多少？这些数据如果不额外记录，过几天就全忘了，想复盘都没得复盘。

说白了，终端输出适合人盯着看，但不适合"管理"。我要的是一个全局的、状态化的、可回溯的视图。这就像你在工位上干活，领导随时瞄一眼就能知道你做到哪一步了——可视化办公室要做的事情就是这个。

1.2 两条技术路线：原生JSON流 vs 终端输出解析

在动手之前，我先研究了一遍Codex能提供什么。一开始我以为只有一个办法：用PTY（伪终端）把Codex的输出整个捕获下来，然后从带颜色、带进度符的文本里硬解析出结构化信息。这条路想想都头疼，光是处理ANSI转义序列、表格对齐、滚动刷新就够喝一壶的了。

后来我注意到Codex其实支持结构化输出模式，它能把整个执行过程拆成一条一条的JSON事件流，每行一个事件，包含事件类型、时间戳、任务ID、负载数据。这条路线简直是专门给做工具的人准备的。

我做了个简单的对比：

所以结论很直接：优先用原生JSON事件流，只把终端文本作为兜底/辅助信息来源。这不是说有PTY方案就完全不能用，而是从工程效率和健壮性考虑，结构化输出明显更划算。

1.3 为什么不做IDE插件，而是做Web面板

确定了数据源之后，还有个选型问题：可视化层放哪里？

我身边不少朋友第一反应是"这不做个VSCode插件不就完了"。做插件当然可以，但有几个问题：

• 绑定IDE：VSCode插件只能在IDE里用，万一你某天换了编辑器，整个可视化方案就废了。
• 依赖UI框架：IDE的Webview开发调试成本其实不低，样式控制也受限于IDE宿主环境。
• 无法全局总览：如果你同时用Windsurf、Cline、Codex好几个工具，插件就只能管自己那一亩三分地。
• 不好做数据沉淀：插件里做的图表、统计、历史记录，想导出或者接入别的系统很麻烦。

做Web面板的好处是：前端就是一个普通的React/Vue页面，后端提供WebSocket接口，整个方案完全独立于Codex运行。它甚至可以跑在另一台开发机上，这边跑Codex，那边用浏览器打开面板看进度。而且Web页面的自由度极高，你完全可以把它做成一个数据大屏，把任务耗时、变更统计、测试趋势全部可视化出来。

最终定的架构方案是：

• 采集层：一个Node.js服务作为"事件网关"，负责启动和管理Codex子进程，读取JSON事件流。
• 状态层：网关内部维护任务状态机、文件变更聚合、测试结果统计。
• 展示层：浏览器Web面板，通过WebSocket实时接收事件和状态快照。

2. 可视化办公室的整体架构与数据流向

2.1 整体架构：一个采集服务加一块网页大屏

一句话概括这套系统：Codex事件流 -> 事件网关（Node.js） -> WebSocket -> 浏览器可视化面板。

用文字把架构图画一下：

[Codex CLI 子进程] | | 结构化JSON事件流（stdout按行输出） v [事件网关（Node.js服务）] | 事件解析、状态归并、聚合统计 | 内存快照 + 增量事件 v [WebSocket服务器（端口4321）] | v [浏览器可视化面板（React + ECharts）] | 任务总览区 | 事件时间线 | 文件变更清单 | 测试结果看板

网关是整个系统的中枢：它既是Codex的父进程，又是前端的数据源。前端这边，我参考了数据可视化大屏的布局思路，把面板分成四个主要功能区：

• 任务总览区：顶部展示所有任务的状态、耗时、进度条，类似一个"任务指挥中心"。
• 事件时间线：中间的实时事件流，按类型着色，能筛选，能看到每个工具调用、文件读取、命令执行。
• 文件变更清单：左侧侧边栏，实时累计任务修改过的文件列表，标记新增/修改/删除。
• 测试结果看板：右侧区域，展示测试用例的通过/失败/跳过，以及失败用例的摘要。

这样一个布局下来，任务跑到哪一步、动了哪些文件、测试过没过，一眼就能看全，完全不需要再去翻终端。

2.2 核心数据模型设计

做可视化最怕的就是前端拿到的数据乱七八糟。我在设计阶段就定下了五个核心数据模型，所有展示组件只依赖这五类事件，其他杂七杂八的字段一律不进前端。

// 任务生命周期事件 interface TaskEvent { type: 'task_started' | 'task_completed' | 'task_failed' | 'task_canceled'; task_id: string; ts: number; // 事件时间戳 meta?: { // 附加元信息 model?: string; duration_ms?: number; exit_code?: number; error?: string; }; } // 一次工具调用事件（读写文件、执行命令等） interface ToolCallEvent { type: 'tool_call'; task_id: string; ts: number; tool_name: string; // 'edit' | 'shell' | 'read' | 'test' 等 status: 'started' | 'completed' | 'failed'; target?: string; // 操作对象，比如文件路径 detail?: string; // 工具参数摘要 duration_ms?: number; } // 文件变更事件 interface FileChangeEvent { type: 'file_change'; task_id: string; ts: number; path: string; change_type: 'add' | 'modify' | 'delete'; added_lines: number; removed_lines: number; } // 诊断/报错事件 interface DiagnosticEvent { type: 'diagnostic'; task_id: string; ts: number; severity: 'warning' | 'error'; text: string; source: string; // 哪个工具或流程产生的 file?: string; line?: number; } // 测试结果事件 interface TestResultEvent { type: 'test_result'; task_id: string; ts: number; test_name: string; status: 'passed' | 'failed' | 'skipped'; duration_ms: number; failure_text?: string; }

设计这几个模型的时候我反复问自己一个问题：前端做展示时，最小需要拿到的字段是什么？多余的一个不加，缺的一个不省。比如ToolCallEvent里加一个detail字段，是为了前端能显示"执行了npm test"这类信息；而FileChangeEvent里的增删行数，是为了让面板上的文件列表能显示本次变更规模，而不只是一个光秃秃的文件名。

2.3 事件流规范化的三步处理

Codex原生的JSON事件流并不是直接可以推给前端的。事件格式虽然结构化，但原始事件更偏底层，直接用会带来两个问题：一是事件类型太碎，前端要写一堆if分支；二是缺乏聚合状态，前端每次都得自己算"目前一共改了多少文件"。

所以我在网关里做了三步处理：

1. 过滤：去掉不需要的底层日志事件，只保留跟任务执行、文件操作、诊断、测试相关的核心事件。
2. 补上下文：给每个事件补充对应的任务ID（因为Codex可能并发执行多个会话）、统一时间戳格式，以及一些计算字段（比如工具调用耗时）。
3. 聚合：在内存中维护累计状态。收到file_change就更新文件变更列表；收到test_result就更新测试统计；收到task_started/completed就更新任务状态机。

这一步做完，前端拿到的就不再是一堆孤立事件，而是一个持续变化的状态模型 + 增量事件流，渲染起来非常轻松。

3. 核心实现：把Codex的执行过程变成实时可看的事件流

3.1 用子进程接管Codex，按行解析JSON事件

网关最重要的职责，就是启动Codex子进程并读取事件流。这里有一个很容易踩的细节：子进程的stdout是流式输出的，可能会把一条JSON事件切成两半，也可能把好几条事件黏在一次data回调里。所以拿到数据不能直接JSON.parse，必须先做按行缓冲。

下面是我用的核心代码，按行解析的逻辑很经典：

const { spawn } = require('node:child_process'); class CodexSession { constructor(taskId, prompt, projectRoot) { this.taskId = taskId; this.projectRoot = projectRoot; this.buffer = ''; this.lastActivityAt = Date.now(); this.timer = null; } start() { // 以JSON事件流模式启动codex const child = spawn('codex', ['exec', '--json', this.taskDescription()], { cwd: this.projectRoot, env: process.env, shell: false, detached: false, // 关键：让子进程跟随父进程退出，防止僵尸进程 }); this.child = child; child.stdout.on('data', (chunk) => { this.buffer += chunk.toString(); // 按换行符切分，只能把最后一个不完整片段留在buffer里 const lines = this.buffer.split('\n'); this.buffer = lines.pop(); // 最后一段可能不完整，留着等下次data for (const line of lines) { const trimmed = line.trim(); if (!trimmed) continue; try { const event = JSON.parse(trimmed); this.handleEvent(event); } catch (err) { // JSON解析失败的兜底：可能是事件里混入了非JSON日志 this.handleRawLine(trimmed); } } this.lastActivityAt = Date.now(); this.scheduleIdleCheck(); }); child.stderr.on('data', (chunk) => { emitEvent('task_log', { taskId: this.taskId, stream: 'stderr', text: chunk.toString() }); }); child.on('exit', (code, signal) => { this.finalize(code, signal); }); child.on('error', (err) => { emitEvent('task_failed', { taskId: this.taskId, error: err.message }); }); } handleEvent(event) { // 归一化事件类型后交给网关统一处理 const normalized = normalizeCodexEvent(this.taskId, event); if (normalized) { gateway.consumeEvent(normalized); } } handleRawLine(line) { // 这里可以做ANSI清洗后作为文本日志展示，但不下发到业务状态机 } scheduleIdleCheck() { clearTimeout(this.timer); this.timer = setTimeout(() => { const idleMs = Date.now() - this.lastActivityAt; if (idleMs > IDLE_TIMEOUT_MS) { // 超时兜底：终止任务，避免前端永远停在running状态 emitEvent('task_timeout', { taskId: this.taskId, idleMs }); this.child.kill('SIGTERM'); } }, IDLE_TIMEOUT_MS); } }

这段代码里最核心的是按行缓冲的处理。我最初直接用chunk.toString().split('\n')，结果大量事件被截断解析失败，后来才反应过来流式数据的粘包和半包问题。另外shell: false也很重要，直接以可执行文件方式启动进程，避免中间套一层shell导致进程管理出问题。

3.2 WebSocket推送：快照加增量，前端一进来就能恢复状态

事件解析完还不够，前端要实时看到状态，最直接的方式就是WebSocket。我用了ws这个库，写了一个简单的推送服务。

这里的关键设计是快照加增量模式：

const { WebSocketServer } = require('ws'); const wss = new WebSocketServer({ port: 4321 }); wss.on('connection', (socket) => { // 连接建立后，先把当前所有任务的状态快照推给前端 const snapshot = gateway.getSnapshot(); socket.send(JSON.stringify({ type: 'snapshot', data: snapshot })); // 再订阅后续增量事件 const unsubscribe = gateway.subscribe((event) => { if (socket.readyState === socket.OPEN) { socket.send(JSON.stringify({ type: 'event', data: event })); } }); socket.on('close', () => unsubscribe()); socket.on('error', () => unsubscribe()); }); // 心跳保活：每15秒ping一次，前端收到ping回pong，超过45秒没收到pong就断开 setInterval(() => { wss.clients.forEach((client) => { if (client.readyState === client.OPEN) { client.ping(); } }); }, 15000);

快照加增量这套组合拳，解决了前端刷新后一片空白的问题。刷新页面时，前端重新建立连接，网关立刻把当前所有任务的状态、文件列表、测试统计一次性推过去，之后只需要增量更新即可。如果没有快照，前端要等任务重新跑一遍才能恢复状态，那体验就太糟了。

3.3 可视化面板的核心组件实现

前端我选了React + ECharts，因为ECharts在数据可视化大屏场景下实在太成熟了，面积图、环形图、散点图全部开箱即用。

面板的具体实现按区块来说：

• 任务总览区：每个任务渲染成一个卡片，包含状态灯（运行中/成功/失败/超时）、任务描述、已用时间、工具调用次数。下面的进度条根据当前已完成的事件占预期事件的比例动态推进——如果拿不到预估总数，就用"持续运行秒数"代替进度条。

• 事件时间线：这是最核心的组件。我用了一个虚拟滚动列表，每一条事件渲染成一行，左侧是时间戳，中间是事件图标和摘要，右侧是关联文件路径。整个列表支持按事件类型过滤（只看文件变更、只看测试、只看命令执行）。为了不让列表无限增长导致内存爆炸，我限制了最多展示最近500条。

• 文件变更清单：这个组件收到file_change事件后，按文件路径做累加整理。每个文件显示当前累计新增/删除的行数，用一个颜色标记区分新增、修改、删除。点击文件行可以在右侧弹出该文件最近的变更事件列表，非常方便做完任务之后快速review。

• 测试结果看板：用ECharts的环形图展示通过/失败/跳过的比例，下方是失败用例列表，点击能看到失败摘要。这个看板对跑测试类任务的场景特别有价值，我经常就是盯着这个看板等测试结果。

还有一个细节：长列表的性能优化。一开始我直接每次事件来了就setState追加，结果事件一密集页面就卡。后来我改成把事件流放到一个"缓冲队列"里，每200ms批量flush一次到React state，操作流畅度立刻上来了。

4. 实现过程中最折腾的几个坑

4.1 ANSI转义符差点毁了解析器

第一个坑说来搞笑。我自信满满地以为Codex的JSON事件流肯定干干净净，结果跑起来之后，解析器时不时抛异常。

排查定位到原因：虽然主体是JSON，但个别日志字段里仍然夹带着终端颜色控制符。比如\u001b[32m✓ test passed\u001b[0m这种字段，整个JSON.parse并没有失败，失败的是我后续对字段内容的处理——我在前端直接把字符串渲染出去，结果页面上一堆[32m之类的诡异文本。

解决方式有两处：

• 后端在解析事件时，顺手对文本类字段做一次ANSI剥离。
• 前端渲染时再兜底清洗一次。

清洗工具就一行正则：

const ANSI_PATTERN = /\u001b\[[0-9;]*m/g; function stripAnsi(text) { return text.replace(ANSI_PATTERN, ''); }

这里我的经验是：能清洗的地方早点清洗，别把脏数据留到前端处理。因为前端可能有多个组件都要渲染文本，每个组件都写一遍清洗逻辑容易漏，不如在网关阶段集中处理。

4.2 任务状态机：pending/running/done的边界问题

我最初设计的任务状态只有三态：pending -> running -> done。结果上线第一天就翻车了——有个任务跑了很久没动静，前端一直显示running，但实际上Codex进程早就退出了，只是退出事件没被正确处理。

后来我把状态机重新设计成：

pending -> running -> completed / failed / canceled / timeout

并且规定：任何非终态到终态的迁移，都必须有对应的触发事件。同时网关里增加了一个兜底逻辑：

• 子进程exit事件到达时，如果当前状态是running，根据退出码判定是 completed 还是 failed。
• 如果长时间没有事件产生（我设置的阈值是10分钟），自动标记 timeout 并杀掉进程。
• 如果用户手动关闭了面板上的任务，发送 cancel 信号给网关，网关再 kill 子进程。

有了这套状态机，前端的任务卡片总算不会永远卡在"运行中"了。这个坑给我的教训是：不要相信"正常流程"，一定要为异常流程设计显式的终态和超时机制。尤其是AI编码工具，它的执行时间摇摆非常大，有时候你以为它卡死了，其实它只是在深度思考，所以超时阈值也得设置得宽一点。

4.3 WebSocket断线重连与历史状态恢复

第三个坑出在WebSocket上。前端打开面板盯着看是没问题的，但一旦刷新页面，连接断开，重新建立连接后所有状态全没了——因为事件网关是内存态的，不会主动重放历史事件。

我当时有两个选择：

1. 给事件网关加持久化存储，把事件落盘，重连后全量重放。
2. 用内存环形队列缓存最近的N条事件，重连时先把"当前状态快照"推过去，再把增量补上。

我选了第二个方案，理由很实在：

• 持久化存储需要引入数据库或者日志文件，部署复杂度上升。
• 环形队列500条以内就够了，因为最新事件覆盖了绝大部分场景，历史特别久远的事件价值不大。

具体实现就是维护一个全局的环形队列，同时保留每个任务的状态摘要：

class EventRingBuffer { constructor(capacity) { this.capacity = capacity; this.items = []; this.start = 0; // 环形队列头指针 this.size = 0; } push(item) { const idx = (this.start + this.size) % this.capacity; this.items[idx] = item; if (this.size < this.capacity) { this.size++; } else { this.start = (this.start + 1) % this.capacity; } } toList() { const result = []; for (let i = 0; i < this.size; i++) { result.push(this.items[(this.start + i) % this.capacity]); } return result; } }

WebSocket连接建立时，网关先把所有任务的状态快照推过去，紧接着把环形队列里的增量事件按顺序重放一遍。前端收到快照后直接替换当前状态，收到增量事件就追加渲染。这样前端刷新后几乎无感恢复，体验好了很多。

还有一个容易忽略的点是心跳保活。如果网络环境不稳定，连接可能会被中间设备静默断掉，两端都不知道。我加了一个15秒的ping/pong机制，前端发现超过45秒没有收到ping，就主动重连；网关发现连接断开，就清理对应的订阅者。

4.4 子进程崩溃与僵尸进程

最后一个坑是最隐蔽的。我有一次改完代码重启网关，结果发现系统里残留了好几个codex进程，它们还在跑着旧任务，占用CPU和网络资源。

原因是我之前用spawn('codex', ...)启动子进程时，没有设置detached: false，默认情况下子进程和父进程的生命周期没有强绑定，万一网关进程被强杀或者崩溃，子进程就会变成"孤儿进程"继续活着。

解决方法是组合拳：

• spawn时显式设置detached: false，让子进程跟随父进程退出而终止。
• 网关进程在收到SIGINT/SIGTERM信号时，统一遍历所有存活子进程并发送SIGTERM。
• 网关进程兜底：启动时检查上一次留下的子进程，如果发现就清理掉。

process.on('SIGINT', () => { // 统一清理所有子进程 for (const session of sessions.values()) { session.child?.kill('SIGTERM'); } process.exit(0); });

这个坑给我的启示是：做任何子进程管理，都要把"进程被外部强杀"这个场景考虑进去。你以为父进程退出子进程自然会跟着退出，但实际上在Node.js里并不是这样。写代码时多写几行清理逻辑，能省掉很多半夜排查诡异Bug的时间。

5. 实测效果、数据表现与后续可扩展方向

5.1 一周实测：我看到了以前看不到的东西

把可视化办公室跑起来之后，我连续用了一周，统计了一下效果。

我给一组真实的测试数据参考：

最让我意外的是，以前我总以为某个任务"跑了不到一分钟就结束了"，实际上面板显示它跑了将近6分钟，只是终端输出大部分时间看起来像"卡住不动"。还有一次任务失败，以前只能看到失败日志，现在通过时间线能看到失败前最后一步操作是对某个配置文件做了一处编辑，而且那个文件正是失败测试用例引用到的模块——定位问题的时间大大缩短了。

可视化带来的最大收益，不是说它让你"看"到了什么新鲜东西，而是它让你第一次能系统的观察AI编码工具的执行习惯和瓶颈。哪些类型的任务容易耗时、哪些文件容易被反复修改、测试经常挂在哪个环节，这些数据沉淀下来，对你优化任务拆分方式非常有帮助。

5.2 这个可视化办公室还能怎么长

目前这套系统还只是单人本地使用，但扩展空间很大：

• 多项目接入：网关启动时注册多个项目目录，每个项目一个任务列表，做成一个全局的总控台，适合同时维护多个代码仓库的场景。
• 成本和Token跟踪：把每次任务消耗的Token数量累计成曲线，直观看到每天/每周的消耗趋势，对预算控制很有价值。
• 通知渠道接入：任务完成、失败、超时的时候通过现有通知渠道推送到手机，就不用一直盯着面板了。
• 历史回放模式：把一次任务的所有事件按时间轴重放，拖进度条就能看到AI在某一个时刻正在做什么，对教学和复盘非常友好。
• 嵌入已有看板：如果你的团队已经有统一的数据大屏或监控中心，完全可以把这个面板作为一个iframe模块嵌进去，让所有开发者都能看到当前有哪些Codex任务在跑。

5.3 一点经验沉淀

整个项目做下来，我最大的感受是：给Codex做可视化，核心不在于前端炫不炫，而在于把不可见的执行过程变成可检查的数据。

如果你也想做类似的事情，我的建议是：

1. 优先用结构化输出，不要硬解析终端文本。终端文本解析是一场灾难，你永远不知道下一行输出会是什么格式。
2. 先把事件规范化做好，再做UI。事件模型不稳定的时候就开始写前端组件，后面一定返工返到哭。
3. 状态机要提前设计终态。pending、running、completed、failed、canceled、timeout这些状态想清楚，再开始写逻辑。
4. 进程管理一定要考虑异常退出。子进程清理、超时兜底、断线重连，这些边界场景才是这个项目真正花时间的地方。

这段时间的经历也让我对AI辅助编程有了更深的体感：AI工具本身确实能干很多活，但如果你能给它配上一个"仪表盘"，你对自己的项目状态和AI的工作方式会有完全不同的掌控感。这个可视化办公室现在还长在我电脑里，每天跑任务都会开着它，那种从"干等"变成"看着它干活"的感觉，真的很爽。