企业官网建设流程全解析

1. 这到底是什么：给Codex套一层办公室

如果你用过Codex（或者说云端的代码生成环境），应该有过这种感觉：它很强，什么都能干，但看它干活特别无聊。终端里一行行日志刷过去，偶尔蹦出一个文件路径，你根本不知道它现在到底在干什么、卡在哪里、改了几个文件、Token还剩多少。盯着屏幕半天，只觉得眼睛酸，没觉得它有“在办公”。

我给自己的Codex工作流加了一个可视化办公室，简单说，就是在不改动Codex核心能力的前提下，给它的全部执行过程加一个Web面板。这个面板跑在本地浏览器里，能看到当前任务的执行状态、已变更的文件列表、对话历史快照、Token和运行资源的实时消耗，甚至可以在面板里直接发起新的指令，不用再切回终端。做完之后最大的感受是：Codex从“一台能写代码的机器”变成了“一个有自己的工位、能看到进度、能交流的同事”。

这个项目适合什么人参考？首先是每天都在用AI写代码、做代码生成与重构的开发者；其次是喜欢折腾本地工具链、对前后端联调有基础的人。不需要高深算法，不需要大型架构，只要你懂一点Python、懂一点前端三件套，就可以照着搭一个自己的版本。这篇文章我不打算只给成品效果截图，而是把整个拆解过程、选型原因、关键代码、踩坑记录完整写出来，你可以直接照着复现。

2. 方案选型：为什么偏要自己写一个面板

先说我尝试过的几条路，以及最后为什么放弃。

第一是Codex官方自带的交互界面。它的界面本身不差，但信息密度很低，更偏向“对话式”而非“工作台”：你很难一眼看出改了哪些文件、哪些步骤耗时最长、哪个环节在死循环。它给你的是一段一段的回答，不是一张“工作进度表”。第二类方案是IDE插件，装一个扩展，把Codex接进编辑器侧边栏。插件的优点是省事，但问题在于它和我的日常任务流冲突——我不是一直在IDE里工作，很多时候是直接调API或者跑脚本，IDE插件管不住终端里发生的执行。第三类，也是最常见的，就是老老实实看终端日志。这个方案最原始，成本为零，但可观测性最差，尤其是当Codex连续执行二三十条命令的时候，前后文一混，你根本记不清它刚才究竟做了什么。

所以最后我决定自己写一个“可视化办公室”。这里的“办公室”不是给程序员看的Dashboard，也不是给管理层看的监控大屏，而是一个面向我自己的、能随时打开随时关掉的本地Web工作台。它的核心诉求只有三个：让我能看到“它现在在干嘛”、让我能看到“它刚才干了什么”、让我能“直接指挥它继续干”。

从技术上看，Codex服务端其实会把执行过程中的文本流、命令、文件变更、Token消耗这些信息通过事件方式抛出来（不同版本暴露的事件字段略有差异，但核心事件流是稳定存在的）。我只需要做一层本地代理，把这些结构化事件接住，再从前端把它们渲染成面板。选择Web方案还有一个很实际的原因：浏览器是通用终端，不需要装任何客户端，手机、平板也能访问同一个小面板。

整个架构我把它分成三层理解：第一层是“调度层”，即Codex的Agent进程本身，它负责决策，也负责产生原始状态；第二层是“服务层”，我用一个FastAPI进程来做事件收集、状态聚合和转发，相当于给Codex装了台“监控录像机”；第三层是“展示层”，一个不依赖框架的单页HTML，通过WebSocket接收状态，更新UI。之所以不引入React或Vue，是因为这个项目没有复杂交互，原生JS完全够用，还能少踩一堆依赖和构建工具的坑，这个选择在后面的维护期帮了我大忙。

3. 办公室的骨架：整体结构、数据流与目录设计

先看一张目录结构图，这是我项目里实际在用的布局：

codex-office/ ├── agent/ │ └── wrapper.py # 包裹Codex执行进程的代理入口 ├── server/ │ ├── main.py # FastAPI服务，负责事件接收与WebSocket转发 │ ├── state.py # 全局状态管理器 │ └── events.py # 事件类型定义与解析 ├── web/ │ ├── index.html # 单页面板 │ ├── style.css # 样式 │ └── app.js # 前端逻辑，WebSocket连接与渲染 ├── storage/ │ └── sessions.db # SQLite轻量存储，保留会话快照 └── run.sh # 一键启动脚本

数据流是这样的：Codex执行进程产生的原始输出，首先进入wrapper层，wrapper按行解析，把文本日志转成结构化事件，写入内存队列；FastAPI服务从队列里消费事件，更新全局状态管理器，并通过WebSocket把增量推给前端页面；前端根据事件类型，渲染成7个不同的面板区块。同时，状态管理器会在每次关键事件后把快照写入SQLite，这样即使刷新页面，也能恢复最近的工作状态。

事件类型我定义了这么几种：

# events.py EVENT_TASK_START = "task_start" # 新任务开始 EVENT_COMMAND_RUN = "command_run" # 执行命令 EVENT_COMMAND_DONE = "command_done" # 命令执行结束 EVENT_FILE_CHANGED = "file_changed" # 文件发生变更 EVENT_TOKEN_USAGE = "token_usage" # Token消耗更新 EVENT_AGENT_MESSAGE = "agent_message" # Agent文本回复 EVENT_STATUS_CHANGE = "status_change" # 状态机流转 EVENT_ERROR = "error" # 异常信息

后端全局状态管理器的核心数据结构也很简单，就是一张不断更新的“工作现场表”：

# state.py class OfficeState: def __init__(self): self.current_task = None self.task_history = [] self.file_changes = [] self.token_usage = {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0} self.commands = [] self.last_status = "idle" self.started_at = None self.last_updated = None

这张表就是整个办公室的“工牌”，所有的记录都围绕它展开。前端面板的7个区块分别对应：任务总览、执行进度、文件变更、命令历史、Token仪表、Agent信息流、控制台输入。每个区块的数据来源，最终都归到这一个状态对象上，这样实现起来简单、排查也好做。

4. 核心环节实现：六大面板是怎么一步步搭起来的

4.1 任务总览与执行进度面板

这是整个办公室的门面，也是信息密度最高的区域。它需要回答三个问题：现在是什么任务、这个任务完成了多少、现在处于什么阶段。

任务总量如何计算？我用一个粗粒度的估算方式：把一次任务中所有命令行的执行当作“子步骤”，每次执行一条命令，进度加1；当前进度就是“已完成命令数 / 总预计命令数”。但“总预计命令数”没法提前知道，所以我把进度条做成“动态式”——根据当前正在执行的命令，不停更新“正在处理哪一步”。

前端渲染时，我维护一个taskTimer定时器，每500毫秒从WebSocket收到的增量里读取最新的进度百分比。这个百分比由后端实时计算：

# main.py 片段 def compute_progress(command_count_done, command_count_planned): if command_count_planned <= 0: return 0 return min(100, round(command_count_done * 100 / command_count_planned))

注意这里有个坑：Codex执行时并不是所有命令都有明确的成功或失败标志。有些命令会长时间挂起，比如跑测试或下载依赖。所以我特意增加了一个“运行中”状态，标记当前正在执行哪条命令。这样一来，哪怕进度条卡住，我也知道它卡在哪一条命令上，而不是两眼一抹黑。

面板的视觉结构是：顶部一条总进度条，下面跟着最近5条任务状态信息，包括任务开始时间、当前正在执行的命令、最近一条错误信息。这一块的价值在于，它把“看日志才能知道的当前状态”变成了“打开网页3秒就懂”。

4.2 文件变更看板：git状态与时间线的结合

Codex干活的一大特点是，它会频繁修改文件。不改不知道，一改吓一跳——有时候一次任务能触发几十个文件变更。光看终端输出是看不出来文件之间的关联的，而文件变更看板就是用来解决这个问题的。

我这边处理文件变更事件的思路是：不自己解析diff，而是直接调用git命令拿状态。因为Codex的工作目录本身就是git仓库，所以每一次文件变更事件触发时，我就在后端执行一次git status --porcelain和git diff --stat，把变更文件清单和变更行数抓出来，再结合事件触发的时间戳，渲染出一个“文件变更时间线”。

# wrapper.py 内的git信息提取指令 git status --porcelain git diff --stat HEAD

前端展示时，用红色代表修改，绿色代表新增，黄色代表删除，并且按时间顺序排列。点开一个文件，还能弹出它近期的变更行数。这里有一个花了不少心思的设计：我不把变更面板做成“当前瞬时状态”，而是做成“会话内变更历史”。因为Codex在完成一个功能时，往往会先写好再删掉再重写，如果只看最终状态，你会错过很多决策过程，而看历史流，就能看出它到底走了哪些弯路。这个面板我后来用下来，已经变成了我审视Codex工作质量最重要的窗口。

4.3 对话历史与上下文快照

对话历史这块听起来简单，但真正做起来有细节。Codex的文本输出并不总是按条到达的，它有时候会一次性吐一大段，有时候又会分块输出。如果直接按行抓，界面就会碎得很厉害。

我的做法是把Agent的文本输出做“缓冲后再切分”：每收到一条agent_message事件，把文本存到会话缓冲区，超过200个字符或者遇到换行符，再作为一条完整的消息渲染到前端。这样既能保证界面整洁，又不会丢失内容。

上下文快照是一个我自己加的小功能。Codex在一开始会读到项目结构和关键文件，这些初始信息往往决定了后续任务的质量，但执行中很容易被滚屏覆盖。我做了一个“初始上下文”面板，在任务开始时把Agent读取文件列表抓一次，存成快照；当任务执行到10分钟、30分钟、60分钟时各再抓一次，形成对比。这样我能从外部观察到，Agent的工作焦点是始终如一，还是在中途发生了漂移。这个信息对判断复杂任务是否“跑偏”非常有用。

4.4 运行资源与Token仪表盘

Token消耗是大部分人的盲区。不花自己的钱，对Token的消耗是没有痛感的，直到某一天发现配额居然被吃掉一大截，才急忙去算账。可视化办公室一定要展示Token仪表，而且最好是实时的。

要拿到Token数据也非常简单：Codex的API或SDK在每次任务响应里都会返回usage字段，wrapper层把它拦截下来，解析成prompt_tokens、completion_tokens、total_tokens三个值，连同时间戳一起存进状态表。前端的仪表盘用三个环形进度条展示：总量、输入量、输出量，下面一行小字展示自任务开始以来的Token消耗曲线（用Canvas画的迷你折线图）。

除了Token，我还加了CPU和内存占用显示。方法很土，但足够有效：每隔2秒执行一次ps命令，抓出Codex子进程的CPU和内存占用量。这样当某一阶段变得特别慢时，我能第一时间判断是网络等待、API限流，还是本地资源被卡住。下面就是我这个简单的采集逻辑：

# server/main.py 片段 import subprocess, json, time def collect_system_usage(pid): try: result = subprocess.run( ["ps", "-o", "%cpu,%mem,rss", "-p", str(pid)], capture_output=True, text=True, check=True ) lines = result.stdout.strip().split("\n") if len(lines) < 2: return {"cpu": 0, "mem": 0, "rss": 0} parts = lines[1].split() return {"cpu": float(parts[0]), "mem": float(parts[1]), "rss_kb": int(parts[2])} except Exception: return {"cpu": 0, "mem": 0, "rss": 0}

这个函数在后端以2秒为周期循环执行，把结果推给前端。有一点必须提醒：不要再在子进程里递归采集它自己，否则会看到CPU占用虚高，而且容易陷入循环调用。

4.5 一键操作区：直接在面板里指挥Agent

可视化办公室不能只是“看板”，它必须能“操作”。我留了一个“指挥台”区域，里面放了三个高频操作按钮：暂停当前任务、继续执行、终止全部任务。这三个操作都通过后端的受控接口调用进程管理指令实现。

暂停的实现不是直接杀进程，而是向进程发送SIGSTOP信号，让Codex停在它执行的那一点上；继续则发送SIGCONT。为什么不用终止？因为终止之后，所有的工作状态和上下文缓存全部丢失，重来的恢复成本极高，而暂停只是冻结，随时可以恢复。这个区别在长任务中尤其重要，测试跑一半想先去处理别的事，暂停回来，一切照旧。

暂停和继续按钮只是第一步。我还设计了一个输入框，允许在面板里手动输入新的指令，传回给正在运行的Agent。本质上，就是在Web端模拟了一次新的对话。这个功能的价值在于，人不再需要被迫盯着终端等它执行完，而是可以在面板里持续交互，把终端彻底关掉。

这里要贴一个容易出问题的地方：WebSocket和Agent进程的消息是两条路径。如果直接让前端通过WebSocket把指令发给服务端，再让服务端同步转发给Agent进程，会有竞态问题——Agent可能正在执行某条命令，你插入的指令会排在系统队列外，可能导致状态错乱。我的解决方案是加了一个简单的“锁”：当正在执行某条命令时，新的外部指令进入等待队列，并提示“Agent忙碌中”，等命令执行完成后再自动发送。这个机制非常朴素，但避免了我踩过的一次大坑。

4.6 面向前端的渲染：原生JS与状态分层

前端我用了一张HTML页面加一个JavaScript文件。因为不引入框架，所有逻辑都是直接的DOM操作。设计上坚持“状态与视图分离”：前端维护一个uiState对象，WebSocket每收到一次增量，就更新这个对象，然后触发一次统一的render()，而不是用一大堆分散的DOM操作改来改去。这样做的好处非常明显——排查问题的时候，你只需要检查一个状态对象，不必在几十个回调函数里捉迷藏。

// app.js 核心渲染入口 function render() { renderProgress(uiState.progress); renderFileTimeline(uiState.files); renderTokenMeters(uiState.tokens); renderCommandList(uiState.commands); renderAgentMessages(uiState.messages.slice(-20)); renderStatus(uiState.status); renderSystemUsage(uiState.system); }

WebSocket收到数据时：

socket.onmessage = function(event) { const payload = JSON.parse(event.data); Object.assign(uiState, payload); render(); };

使用Object.assign做无脑合并，是刻意的选择。Codex的状态事件频率高、字段杂，如果前端每次都做全量比对和差异化更新，代码量会膨胀两倍，还容易出bug。无脑合并导致的问题是，某些字段更新频率高，会导致整个页面重渲染，但实际上只改一个数字也无所谓——因为页面本身就是轻量级的，这个性能开销完全可以忽略。

最后是夜间模式。不是说非要变黑底白字才叫夜间模式，而是这套面板经常会开着过夜——任务跑一个通宵，第二天早上看一眼结果。所以配色方面我直接用暗色底、高对比度文字，默认就是“夜间友好”。省去切换的逻辑，也省去一个样式变量。

5. 实测实录：真实跑一个跨平台项目时的现场记录

光说不练假把式。我拿一次真实的任务做了测试：让Codex从零写一个批量图片重命名工具，要求支持拖拽文件夹、自动识别EXIF时间、生成重命名日志。这是一个中等复杂度的任务，正好能体现可视化办公室的全流程。

任务开始后，面板顶部亮起“task_start”事件，状态栏显示“规划中”。过了大约4秒，第一条命令进场，是Codex在扫描当前目录结构。执行进度条从0跳到6%，文件时间线里出现了几条目录读取记录。这个时候我发现它读了一个不该读的缓存目录，立刻在指挥台输入了一条新指令：“忽略cache和dist目录”，命令进入等待队列，等它当前这条命令结束后自动发出。这在传统终端里，需要人一眼不眨盯输出，但在面板里就成了一个顺手的操作。

中间有一段时间进度条卡在30%不动了。面板左侧的Agent信息流显示它正在分析一个图片库，CPU占用在12%上下，说明不是死锁，而是计算量大。我按了暂停，去泡了杯咖啡，回来按继续，状态无缝恢复。最终执行到97%，文件看板显示它新建了12个文件，修改了5个，删除2个；Token仪表显示这次任务共消耗34000多个Token，其中输入占了大部分——因为图片库的路径信息被反复读取了多次。最终我确认代码可用，这一轮的“办公室使用记录”也完整保存在SQLite里。

实测下来，面板对任务质量的判断真的有帮助：我看到了Codex在一次修改中连续重写了同一个函数三次，这个信号用日志根本发现不了。从那以后，我开始在Codex的提示词里加上“先给出设计方案，确认后再动手”，面板的观察价值就完全体现出来了。

6. 常见问题与排查技巧实录

做这个项目时踩的坑并不少，有些问题在传统开发流程中不会出现，但因为加入了事件采集与双通道通信，新问题随之产生。我整理成速查表，方便你对照解决。

有一条心得值得单独说：不要试图捕获Codex输出的“全部”，要捕获“全部的结构化事件”。文本日志里可能存在大量重复、噪音或控制字符，如果原封不动传给前端，面板会变得比终端还乱。最关键的一步是在服务端做“事件清洗”：按类型分类，只保留有价值的字段，其余一律丢弃。宁可在存储时省一点，也不要让前端被迫处理垃圾数据。

还有一坑是关于端口占用的。FastAPI默认监听8000端口，但我本机经常有其他服务占用这个端口，导致面板起不来。我后来在run.sh里加了一个自动探测端口的小逻辑：

# run.sh 片段 PORT=${PORT:-8642} while lsof -i:"$PORT" >/dev/null 2>&1; do echo "端口 $PORT 已被占用，切换到 $((PORT+1))" PORT=$((PORT+1)) done

选择8642作为默认端口是因为这个号段很少被开发服务器占用，冲突概率低。这个细节虽小，却省了很多闷头调试的时间。

7. 这个办公室还能怎么扩展，以及我踩过最大的坑

整个项目做完之后，我思考过它还能往哪个方向扩展。最简单的是做“多任务队列”：当Codex需要处理多个项目任务时，面板变成类似看板的卡片式管理，每个任务占一张卡片，每个卡片有自己的状态、进度、Token统计。这个扩展的技术增量不大，因为已有的状态管理是天然为多实例预留的，只要把state.py的KEY从单key改成任务ID多key就行。更有价值的是把同一面板开放给团队，几个人同时看一个Agent干活，相当于把个人工具变成了共享协作屏。

我还试过接一个语音播报模块。因为Python生态里现成的语音包很多，在后台把task_start、command_done、error这三类事件转成语音提示，我就再也不用一直盯着面板，代码跑完的时候它会说一声“已完成”。这个模块代码不过50行，但使用体验提升非常明显。如果你有空闲时间，建议也加上。

说到最大的坑，我觉得不是技术性的，而是我在一开始犯的战略错误：第一次做这个面板时，我花大量时间做UI美化，做了各种炫酷的动态效果、圆角卡片、平滑过渡动画，结果真正要用的数据却迟迟没有接上。那一次几乎浪费了两天时间，最后全部推翻重来。如果你也想搭一个类似的东西，我的最核心建议是：先打通数据流，再考虑好看。只要数据是准的，哪怕界面丑得像Excel，它也已经比终端高出一个维度了。反过来说，界面再精美，数据延迟3秒，那它就是个精致的废物。

这个项目最吸引我的，其实不是“可视化”这三个字，而是它让我第一次“看见”了AI的工作过程。当我看到那些文件调整的细节脉络，看到Token消耗的时间曲线，看到Agent自己反复改同一个函数的记录，我对AI的信任度和判断力都有了质的变化。如果你也在用Codex做正经的长周期任务，这个办公室值得你花一个周末去搭起来。