企业官网建设流程全解析

最近这一个月，我几乎把Codex当成了日常主力开发工具。它确实能在终端里连续干很久，但真正折磨人的是它像个黑盒：到底卡在哪一步、改了哪个文件、现在跑在哪个任务上？等它输出一大段日志，我才发现它五分钟前就陷入某个死循环了。与其继续“盲操作”，我干脆给Codex搭了一个可视化办公室。

这个想法其实很朴素。把每一个Codex会话当成一个员工工位，把文件的读取、写入、测试、提交当成员工手里的动作和产出，再把所有会话的状态、耗时、工具调用全部摊开在大屏上，一眼就能看出谁在干活，谁在等反馈，谁在处理紧急任务。我花了一周时间把这个东西从零到一做了出来，期间踩了不少坑。本文把整个设计思路、技术选型、核心实现和排查过程都写清楚，希望能给同样被终端黑盒困扰的人一点参考。

1. 为什么给Codex加办公室：三个让我下决心的痛点

1.1 过程不可见，出了问题只能事后看日志

Codex默认在终端里运行，输出的是连续的文本流。它调用工具、读写文件、跑测试、提交代码，全都在这个流里。平时跑短任务还好，一旦任务复杂，它会连续工作十几分钟甚至更久。这时候终端窗口就像一台不停吐纸的打印机，信息是有的，但人没法时刻盯着。

最难受的场景是：我切到别的窗口干了半小时，回来一看，Codex早就因为某个报错卡在重试循环里了。这半小时的算力全被浪费，而我只能靠翻滚动日志来复盘它到底在哪一步出了岔子。日志不是不好，但它是一种“事后工具”，我需要的是“实时状态”。

1.2 多会话并行时，任务归属彻底混乱

Codex支持同时开多个会话，实际用起来我会开三到五个：一个改后端接口，一个写前端页面，一个跑数据分析，偶尔还有一个做代码评审。在终端里管理这几个会话全靠手动切换，经常发生的情况是：我忘了某个会话当前执行到什么阶段，或者两个会话改到了同一个文件，产生了冲突。

这种并行场景下，终端的信息密度完全不够用。我需要的是一块面板，像办公室工位图一样，每个人在做什么、在哪个项目上、当前进度如何，全部一目了然。这比“打开第几个标签页”要直观太多。

1.3 历史复盘几乎没有，第二天就忘了昨天跑了什么

终端日志不会主动整理，第二天想看昨天的会话干了什么，只能一层层往上翻，还要面对大量无用的中间输出。更别提跨天的对比：昨天和今天各跑了多少任务、哪些文件被高频修改、哪个会话耗时最长，这些统计信息几乎不可能从原始日志里快速得到。

我知道市面上有些终端录制工具可以回放，但回放不是复盘，我需要的是结构化数据：某段时间内执行了哪些操作、哪些文件被改动、哪些操作失败了。所以这个“可视化办公室”从一开始就不止是显示实时状态，还要承担数据沉淀的功能。后来我确实靠它养出了一份很有价值的开发行为数据。

2. 整体架构：探针、解析、展示三层流水线

2.1 探针层：用PTY接管Codex进程

第一件事是要让Codex的输出能被程序主动读取。很多人第一反应是直接用subprocess管道重定向stdout，但实测下来有个问题：Codex这类交互式CLI工具会检测到非终端环境，改变输出行为，甚至直接不输出某些内容，包括交互式确认提示和部分颜色标记。我的做法是用PTY（伪终端）来启动它，让进程以为自己在一个真实终端里运行。

import os import pty import subprocess master, slave = pty.openpty() proc = subprocess.Popen( ["codex", "exec", "--skip-git-repo-check"], stdin=slave, stdout=slave, stderr=slave, cwd="/path/to/project", ) os.close(slave)

用伪终端的好处是能拿到最完整的输出，包括进度条和转义序列。坏处是解析复杂度上来了，这些后面在踩坑部分细说。探针层的基本职责很简单：把PTY输出按字节流读出来，交给解析层。

2.2 解析层：把终端输出变成结构化事件

探针层产出的是原始字节流，里面夹杂着大量ANSI转义码、回车符、进度条刷新内容。解析层要做两件事：清理这些噪声，然后把文本切分成有意义的事件。

我定义了一套基础事件类型：

这些事件会带上统一的时间戳和会话ID，然后写入事件总线。我用的是Python的asyncio队列，解析进程只负责往队列里塞事件，持久化进程和WebSocket推送进程各自消费队列。这样可以避免一个环节卡住导致整个链路阻塞。

2.3 展示层：浏览器里的实时仪表盘

展示层做成了一个独立的Web应用，跑在本地端口上。前端通过WebSocket和后端保持长连接，后端一收到解析层产生的事件就实时推给前端。前端不做轮询，所有状态更新都靠推送，这样延迟非常低，基本是秒级的。

技术栈选型上，前端我用了React + Vite，后端用了FastAPI，中间用WebSocket通信。选React是因为组件化表达工位卡片很顺手，Vite的启动速度和HMR体验也好。FastAPI的异步特性和asyncio事件循环天然配合，不需要额外搞消息队列。数据持久化用SQLite，单文件，零运维。

整套系统的架构流其实只有一条主路：Process -> PTY Output -> 解析器 -> 结构化事件 -> 事件总线 -> SQLite和WebSocket -> 浏览器。我在代码里没有引入超过两个以上的中间件，就是为了让底层链路足够短，好排查问题。

3. 核心数据结构：一切状态都落到SQLite

3.1 表结构设计

我数据库设计了三张核心表：sessions、actions、events。sessions表存会话基本信息，actions表存每个会话执行过的操作，events表存原始事件流。这样一个设计既能满足实时展示，又方便事后统计。

CREATE TABLE sessions ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT UNIQUE NOT NULL, project_path TEXT NOT NULL, current_status TEXT DEFAULT 'active', start_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP, end_time TIMESTAMP, exit_code INTEGER ); CREATE TABLE actions ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL, action_type TEXT NOT NULL, file_path TEXT, tool_name TEXT, detail TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (session_id) REFERENCES sessions(session_id) ); CREATE TABLE events ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT NOT NULL, event_type TEXT NOT NULL, payload TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );

3.2 为什么选SQLite而不是内存存储

一开始我图快，把所有状态都放在内存里，用一个全局字典维护。跑了半天之后发现两个问题：第一，一旦后端服务重启，所有历史数据全丢，连会话状态都没了；第二，内存字典在多协程并发写的时候需要加锁，容易出bug。SQLite单机部署完全够用，而且Python标准库就带驱动，不需要额外依赖。

3.3 事件驱动如何避免前端轮询

前端不用轮询，是因为后端在事件循环里主动推送。我在FastAPI里维护了一个WebSocket连接池，解析层每产生一个新事件，就广播给所有连接的客户端。连接池的实现也很简单，就是一个set集合，每个连接注册进去，断开时移除。

connected_clients: set[WebSocket] = set() async def broadcast_event(event: dict): dead_clients = [] for client in connected_clients: try: await client.send_json(event) except Exception: dead_clients.append(client) for d in dead_clients: connected_clients.remove(d)

这里有个很实际的经验：WebSocket连接不一定是被正常关闭的，浏览器直接刷新页面、断网、切后台都会导致底层连接断开，但服务端的socket不一定立刻感知。所以每次广播时要做异常捕获，遍历时把挂掉的连接剔掉，不然连接池会越积越多，内存涨得很快。

4. 界面设计与办公隐喻落地

4.1 总览大屏：工位状态一目了然

界面分两层，第一层是全局总览，类似办公室的进门大屏。每个会话是一个“工位卡片”，卡片上有四个关键信息：会话ID、当前状态、运行时长、最近活动。状态用颜色区分，active是绿色，waiting是黄色，error是红色，finished是灰色。

这个设计帮我彻底解决了一个问题：看起来活跃的会话其实在等输入。Codex有时会暂停等用户确认，但终端里很难分辨。在仪表盘上，我把“等待”单独标记出来，一旦会话超过两分钟没有新事件，卡片颜色就从绿色变成黄色，并且显示“疑似阻塞”。这个逻辑其实很简单，就是判断当前时间和该会话最后一条事件的时间差。

4.2 工位卡片：每个会话的详细状态

点击任意一张工位卡片，可以进入会话详情页。详情页左边是文件操作时间线，右边是工具调用记录。文件操作时间线按时间顺序列出该会话改过哪些文件，每个文件图标显示是created、modified还是deleted。工具调用记录则展示Codex调用了什么工具、传了什么参数、返回是否正常。

我最常看的是工具调用记录。因为很多问题出在Codex反复调用同一个工具导致死循环。详情页里如果发现某个工具在短时间内被调用超过十次，我会标红提醒。这个功能是从实际踩坑里长出来的，后面会细说。

4.3 让“可视化”真正有用的一些细节

界面做出来之后我调了几轮，发现一些细节对体验影响很大。第一个是时间显示格式：不要只显示时间戳，要显示相对时间，比如“3分钟前”。人看相对时间比看具体时间快得多。第二个是自动滚动策略：默认情况下新事件产生时，列表不要自动滚到底部，不然你正在看半中间的内容会被打乱。我加了一个“自动滚动”开关，需要时手动打开。

第三个细节是搜索过滤。多会话并行时，同一时间可能有几十个操作在发生，总览大屏会显得很吵。我给总览页加了一个简单的过滤栏，可以按项目路径搜索，也可以按状态筛选。比如只看error状态的会话、只看某个项目下的操作。这个功能实现成本很低，但实际使用频率极高。

5. 踩坑实录：四个差点让我放弃的问题

5.1 缓冲把输出堵在管道里

第一个遇到的坑是输出延迟。最初探针层启动Codex后，我直接read字节流，发现输出不是实时的，而是积攒一段时间后突然涌出一大段。后来查了资料才明白，进程在PTY环境下的输出会经过行缓冲，管道满了才flush一次。

解决办法是设置PTY的原始模式，关闭行缓冲。具体做法是用termios库设置终端属性：

import termios import tty attrs = termios.tcgetattr(slave) tty.setraw(slave) termios.tcsetattr(slave, termios.TCSANOW, attrs)

这样设置之后，输出几乎可以做到毫秒级刷新。这个坑让我意识到，解析类工具最怕的就是底层数据延迟，延迟会让上层所有实时性都失效。所以探针层的第一个指标必须是“原始输出到解析器的延迟”。

5.2 ANSI转义码和进度条解析

这是最烦的解析问题。Codex在终端会输出大量ANSI转义序列，包括颜色、光标移动、清屏等。如果不过滤这些字符，事件分割时会不断出错，比如把一条事件切成两半。

我的处理是先剥掉所有ANSI转义码，再根据关键词切分事件。剥除用正则：

import re ANSI_PATTERN = re.compile(r'(\x1b\[[0-9;]*[a-zA-Z]|\x1b\][^\x07]*\x07?)') def clean_ansi(text: str) -> str: return ANSI_PATTERN.sub('', text)

但是进度条还有另一个坑：它不是一次输出一行，而是用\r覆盖同一行实现刷新。剥掉ANSI后，文本里会带有大量\r符号，如果直接按行切分，进度条的每一帧都会被当成新行。解决办法是先把\r替换成\n，再做行切分。同时过滤掉那些看起来像纯进度条的行，比如只包含数字、百分比和[]的。

这个坑让我明白一个道理：终端输出解析是个精细活，不能靠猜测，必须对着实际的字节流反复调试。我写了一个小工具，把原始输出dump成hex，观察每个控制字符，最后才确定解析规则。

5.3 僵尸进程造成“假在线”状态

有段时间总览页上一直显示某个会话活跃，但点进去看操作记录，已经十几分钟没有新事件了。查下来发现，是Codex进程提前退出，但PTY的slave端没有正确关闭，导致探针层的读操作阻塞在read上，一直拿不到EOF。

如果不用PTY，用subprocess管理的进程在子进程退出后，readline会返回空字符串，很好检测。但PTY下，slave端是系统文件描述符，父进程不会自动收到子进程退出事件，必须显式处理child退出信号。

我的解决方案是定期轮询子进程状态，加上心跳检测。心跳的机制是：如果某个会话超过3分钟没有任何输出，就主动检查子进程poll()返回值；如果poll()返回非None，说明子进程已经退出，立刻标记会话为finished，并关闭对应的文件描述符。

5.4 WebSocket刷新导致连接风暴

界面开发调试期间，我有一次开着浏览器自动刷新，结果后端连接池里瞬间多了几十个连接，每个连接都在重复推送事件，CPU占用直接飙高。这其实不算bug，但暴露了一个问题：连接管理不够严格。

后来我做了两件事。第一是每次WebSocket建立连接时，限制每个IP的连接数，同一浏览器只保留最近的两个连接。第二是增加一个心跳ping/pong，30秒一次，检查连接是否真的还活着。这两招之后，连接风暴再也没出现过。

6. 性能实测与参数调优

6.1 端到端延迟

整体做通之后，我测了一遍端到端延迟：从Codex产出输出到浏览器界面更新，在本地局域网环境下的延迟基本在150到300毫秒之间。这个延迟包括PTY读取、ANSI剥离、事件切分、WebSocket推送、浏览器渲染五个环节。

对于实时监控来说，这个延迟完全可以接受。延迟主要消耗在两个地方：一是Python解析器的正则处理，二是WebSocket广播。正则处理我后续做了优化，把一些高频匹配规则合并成一个复合正则，延迟又降了大约40毫秒。

6.2 内存与连接数

同时开五个Codex会话时，后端进程的常驻内存大概在350MB左右，其中大部分是Python运行和连接池占用的。前端页面在Chrome里的内存占用大约是120MB，对于本地开发工具来说完全可接受。

连接数方面，默认只允许一个浏览器最多开两个WebSocket连接，并发会话数在五个左右时，整个系统非常稳定，跑了一整天也没出现内存泄漏的情况。SQLite文件在持续运行八小时后大约增长到4.6MB，包含几千条events记录，查询性能依然毫秒级。

6.3 配置调整清单

整个系统我抽象了三个配置参数：刷新间隔、心跳超时、阻塞阈值。刷新间隔控制多快检查每个会话的新事件，默认100毫秒；心跳超时控制判定会话断开需要多久，默认30秒；阻塞阈值控制会话多久没新事件就标记为疑似阻塞，默认两分钟。

这三个参数一开始都设置得很激进，比如刷新间隔设到10毫秒，结果CPU占用明显上升。后来根据实际调试降到100毫秒，在五个会话负载下，CPU占用稳定在12%以内。这个经验说明，监控类系统不需要追求极致的刷新率，100毫秒到500毫秒之间的更新速度对肉眼来说都是流畅的，但CPU开销差了好几倍。

7. 经验总结与后续扩展

7.1 这套系统如何改变了我的开发方式

搭完这个可视化办公室后，作用体现在一个具体的细节上：我的注意力成本大幅降低了。以前我需要在终端、编辑器、浏览器几个窗口来回切换，现在只需要把仪表盘挂在副屏上，偶尔瞟一眼，就能知道所有会话的状态。有事的时候再切过去处理，不必像以前那样守着终端等待。

另一个改变是数据驱动。第二周开始，我看到SQLite里积累的数据，突然意识到这可是现成的代码活动分析报告。它能告诉我哪个文件被改动最多、哪个会话耗时最长、哪个工具的调用频率最高。这些数据对优化我自己的开发流程很有帮助，比如我发现测试工具被回调的频率异常高，后来排查出是项目里某个测试用例本身不稳定导致的。

7.2 下一步计划

目前可视化的重点是会话状态和操作记录，下一步我想把规划类信息也纳进来。比如让Codex一开始列出它依赖计划，然后把我完全从进度条中解放出来。这样整个系统就不止是一个终端监控工具，而是一个真正的开发过程工作台。

另外一个想做的事是引入多台机器的支持，让仪表盘不仅能监控一台电脑上的Codex会话，还能聚合局域网内其他机器上的任务。这个功能需要把事件总线换成消息队列，架构会更复杂一些，但换来的是多节点的统一视图，对跨设备协作意义很大。这两块内容还在写代码，等有阶段性成果了我再回来更新。

最后再多说一句实际体会：监控类项目看起来小，但真正把它做好很费工夫，尤其是输出解析和连接管理这两个部分，属于在文档里绝对找不到答案的领域。希望本文这些踩坑过程能帮你少走一点弯路。