说实话用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、负载数据。这条路线简直是专门给做工具的人准备的。我做了个简单的对比方案解析成本实时性稳定性信息完整度Codex原生JSON事件流低按行JSON.parse即可高事件实时吐出高前提是选对模式高能拿到任务状态、工具调用、文件变更、测试结果等结构化字段PTY捕获终端输出高需要处理ANSI和乱码中受输出缓冲影响中输出格式一变就废低大量信息混杂在文本里提取困难日志文件轮询中需要定时读取和增量解析低有延迟中日志轮转容易中断中所以结论很直接优先用原生JSON事件流只把终端文本作为兜底/辅助信息来源。这不是说有PTY方案就完全不能用而是从工程效率和健壮性考虑结构化输出明显更划算。1.3 为什么不做IDE插件而是做Web面板确定了数据源之后还有个选型问题可视化层放哪里我身边不少朋友第一反应是这不做个VSCode插件不就完了。做插件当然可以但有几个问题绑定IDEVSCode插件只能在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分支二是缺乏聚合状态前端每次都得自己算目前一共改了多少文件。所以我在网关里做了三步处理过滤去掉不需要的底层日志事件只保留跟任务执行、文件操作、诊断、测试相关的核心事件。补上下文给每个事件补充对应的任务ID因为Codex可能并发执行多个会话、统一时间戳格式以及一些计算字段比如工具调用耗时。聚合在内存中维护累计状态。收到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上。前端打开面板盯着看是没问题的但一旦刷新页面连接断开重新建立连接后所有状态全没了——因为事件网关是内存态的不会主动重放历史事件。我当时有两个选择给事件网关加持久化存储把事件落盘重连后全量重放。用内存环形队列缓存最近的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 一周实测我看到了以前看不到的东西把可视化办公室跑起来之后我连续用了一周统计了一下效果。我给一组真实的测试数据参考指标数据一周内执行任务总数23个平均任务时长4分18秒单个任务最长耗时17分52秒累计文件变更数87个文件新增23、修改61、删除3执行测试用例总数341个通过329个失败12个工具调用总次数216次最让我意外的是以前我总以为某个任务跑了不到一分钟就结束了实际上面板显示它跑了将近6分钟只是终端输出大部分时间看起来像卡住不动。还有一次任务失败以前只能看到失败日志现在通过时间线能看到失败前最后一步操作是对某个配置文件做了一处编辑而且那个文件正是失败测试用例引用到的模块——定位问题的时间大大缩短了。可视化带来的最大收益不是说它让你看到了什么新鲜东西而是它让你第一次能系统的观察AI编码工具的执行习惯和瓶颈。哪些类型的任务容易耗时、哪些文件容易被反复修改、测试经常挂在哪个环节这些数据沉淀下来对你优化任务拆分方式非常有帮助。5.2 这个可视化办公室还能怎么长目前这套系统还只是单人本地使用但扩展空间很大多项目接入网关启动时注册多个项目目录每个项目一个任务列表做成一个全局的总控台适合同时维护多个代码仓库的场景。成本和Token跟踪把每次任务消耗的Token数量累计成曲线直观看到每天/每周的消耗趋势对预算控制很有价值。通知渠道接入任务完成、失败、超时的时候通过现有通知渠道推送到手机就不用一直盯着面板了。历史回放模式把一次任务的所有事件按时间轴重放拖进度条就能看到AI在某一个时刻正在做什么对教学和复盘非常友好。嵌入已有看板如果你的团队已经有统一的数据大屏或监控中心完全可以把这个面板作为一个iframe模块嵌进去让所有开发者都能看到当前有哪些Codex任务在跑。5.3 一点经验沉淀整个项目做下来我最大的感受是给Codex做可视化核心不在于前端炫不炫而在于把不可见的执行过程变成可检查的数据。如果你也想做类似的事情我的建议是优先用结构化输出不要硬解析终端文本。终端文本解析是一场灾难你永远不知道下一行输出会是什么格式。先把事件规范化做好再做UI。事件模型不稳定的时候就开始写前端组件后面一定返工返到哭。状态机要提前设计终态。pending、running、completed、failed、canceled、timeout这些状态想清楚再开始写逻辑。进程管理一定要考虑异常退出。子进程清理、超时兜底、断线重连这些边界场景才是这个项目真正花时间的地方。这段时间的经历也让我对AI辅助编程有了更深的体感AI工具本身确实能干很多活但如果你能给它配上一个仪表盘你对自己的项目状态和AI的工作方式会有完全不同的掌控感。这个可视化办公室现在还长在我电脑里每天跑任务都会开着它那种从干等变成看着它干活的感觉真的很爽。