企业官网建设流程全解析

最近这段时间，我几乎把日常编码都交给了 Claude Code 和 Codex 这两个 AI 编码命令行工具。用起来确实爽，需求说清楚，剩下的活 AI 自己干——这就是圈里说的 Vibecoding，一种由 AI 主导实现的开发状态。可爽归爽，终端里干活的老问题也被放大了：会话不会等你。关掉终端、切换项目、换台机器，前面聊了一下午的上下文就没了，一切回到最初的问候语。所以我干脆做了个东西，叫Easy Web Vibecoding，一个专为 Claude Code / Codex 收拾现场的持久化 Web AI 编码工作区。

这个工作区做的事情不复杂：把两个 CLI 工具的进程接到浏览器里，会话、配置、项目改动全做持久化。你上午在台式机上聊到一半的需求，晚上用笔记本打开工作区还能原样续上。文章我会从设计思路、持久化实现、Web 交互、后端接入这几个角度展开，最后把集成过程中踩过的坑一块儿复盘。适合正在用或准备用 Claude Code / Codex 做实际项目、又被会话和配置问题折腾过的开发者参考。

1. 痛点观察：CLI 编码工具什么都好，就是不记得事情

1.1 三个高频体验问题

新接触 Claude Code 和 Codex 的开发者，第一周基本都会处于新鲜感爆棚的状态：代码写得飞快，重构说一声就做，终端里噼里啪啦全是 AI 的输出。但新鲜感褪去之后，实际干活时的几个问题会越来越扎眼。

第一个问题是会话上下文天然易碎。这两个工具本质上都是"一次性会话"的思路：你新开一个终端窗口，它就是一个全新的开始。就算某些 CLI 提供了续接参数，跨工具、跨项目、换设备之后找回来的路径也很绕。我经常是上午在公司台式机上让 Claude Code 改 API 层，下午回家想用笔记本接着搞，发现得先想清楚"刚才那个项目在哪个目录、当时用的什么命令"，再折腾恢复，运气不好还要从头解释一遍需求。

第二个问题是多项目、多工具并行时，终端窗口能堆成山。我实际工作里经常同时开 Claude Code 和 Codex，一个负责重构后端，一个负责写测试。再算上不同项目的终端 Tab，切换成本非常高，稍不留神就把 A 项目的上下文发给了 B 项目的会话，AI 一顿操作猛如虎，结果改了不该改的文件。

第三个问题是审阅 AI 产出物不方便。终端里看 diff 特别费劲，复杂改动用眼睛滚动日志，缺少一个并排的编辑界面去对照。AI 说它"已重构完成"，你想确认到底动了哪些文件、改了几行代码，在纯终端环境里只能靠肉眼。

这三个问题单拎出来都不致命，但叠在一起，就成了日常开发里持续的摩擦力。我当时的想法很简单：把这几个 CLI 工具的会话统一放到一个 Web 工作区里，让文件树、编辑器、diff、会话历史出现在同一个界面，并且让状态跨会话、跨设备保留。

1.2 长期使用的瓶颈在于连续性

我理解 Vibecoding 这类开发方式的本质，是一种低摩擦、高节奏的人机协作状态：AI 负责产出代码，人负责判断方向、验收结果。它的体验根基不是某个大模型有多强，而是"AI 记得我们聊到哪了"。这个"记得"不是模型通用的记忆能力，而是具体到当前项目、当前会话的连续性。

没有持久化，Vibecoding 就会退化成每天重复自我介绍的社交流程。所以我在设计 Easy Web Vibecoding 时，第一优先级不是加更多花哨 UI，而是把状态持久化做扎实。这里的"状态"我拆成了三类：会话历史、项目快照、后端配置。会话历史让对话能续上；项目快照让代码现场能还原；后端配置让你不用每天重复设置模型和密钥。三者合起来，才是一个完整的"现场"。

2. 核心架构：一个 Node 进程同时托管 Codex 与 Claude Code 会话

2.1 为什么调度层选 Node.js

确定要做这个工作区之后，第一个选型问题就是后端用什么语言。我几乎没有犹豫就选了 Node.js，理由很实际。

第一，Claude Code 和 Codex 本身都是 npm 安装的 CLI 工具，用 Node 的child_process去调起它们最直接，依赖是同语言生态，环境变量、参数拼接、流处理全是熟悉的 API。第二，这两个工具输出的是高频流式数据，Node 的子进程流处理和事件驱动模型非常契合这种场景。第三，交互式 CLI 普遍要求挂一个伪终端（PTY），Node 生态里有现成的node-pty库可以解决，省掉自己写 C 扩展的麻烦。

如果换 Python 或 Go，也不是不行，但要么得自己处理 PTY 和 ANSI 转义，要么得费劲地对接 npm 工具链，成本明显高。做这类"管 CLI 的工具"，跟着 CLI 的生态走是最省力的。

2.2 子进程生命周期与流解析

工作区启动时，后端会为每个会话spawn一个对应的 CLI 进程。这里有个关键细节：交互式 CLI 要求 TTY 环境，否则会退化成非交互模式，很多能力（比如长任务中的暂停、多步确认）就没了。所以我不直接用pipe，而是用 PTY 方式启动：

• spawn一个 PTY，工作目录锁定到当前项目目录；
• 环境变量由工作区统一注入，不依赖用户 shell profile；
• 读取输出时，优先使用 CLI 提供的 JSON 流输出模式，让每个事件自带类型和结构化字段；
• 如果某个 CLI 版本不支持 JSON 流，退路是拿到原始输出后清洗 ANSI 转义序列，再按行回放。

内部事件结构大概是这样的，每条记录对应一次动作：

{ "type": "tool_exec", "sessionId": "c010f8a2-...", "ts": "2025-06-01T10:24:11Z", "tool": "Edit", "file": "src/server/index.js", "detail": "refactor route handler", "result": "OK" }

这样的设计，前端拿到结构化事件后想怎么渲染都行：文本是文本，工具调用是工具调用，diff 是 diff，互不干扰。原始输出我也会同步存储一份，方便排查问题。

2.3 会话信息的传输通道：WebSocket

前端和后端的通信，我选了 WebSocket 而不是 HTTP 轮询。原因也简单：消息频率太高，轮询要么延迟大要么请求多；而且前端需要随时向后端下发指令，比如取消当前任务、切换模型——这是双向通信，WebSocket 天然合适。

我维护了多条消息通道，用message.type区分事件类型：session（会话切换）、tool（工具结果）、heartbeat（心跳）、error（报错）。断线重连也做了处理：前端重连后带上lastEventId，后端会把断线期间遗漏的事件补发回来，保证界面状态连贯。

3. 持久化是灵魂：三类状态怎么做到断点续传

3.1 会话文件：JSONL 的记录格式与恢复逻辑

持久化的第一层是会话文件。我选择了 JSONL 格式，一行一个事件，追加写入。目录结构大体是这样：

data/ projects/<项目名>/ config.json sessions/<sessionId>.jsonl snapshots/ summaries/<sessionId>.md

恢复会话时，后端把这些事件顺序读回来，前端按时间线直接渲染，视觉上和"刚才没关过"一样。进程层面的恢复则是这样：工作区重启时，优先调用 CLI 自带的续接参数把原会话拉起来；如果 CLI 不支持，就退而求其次，把 JSONL 里最近的完整消息注入提示词，至少保证人工上下文不丢。

元数据我放在 SQLite 里统一管理，开启 WAL 模式，保证并发读写不锁库。正文 JSONL 放文件系统，两边配合：SQLite 管索引和检索，文件系统管大块内容。

3.2 项目快照与 Git 自动 diff

会话文件只是对话层面的持久化，项目代码层面的持久化同样重要。我做了这样的机制：每产生一次文件相关的事件，后端自动执行一次git status --porcelain和git diff --stat，把改动摘要作为一条事件写进会话流。这样界面上会显示"这轮对话产生了 3 处文件变更，+120 行 / -45 行"，一眼就能知道 AI 干了多少正事。

这里有个设计原则：自动只读观测，不碰 Git 历史。工作区不会自动 commit，避免干扰开发者自己管理提交的习惯。但提供"创建快照"按钮，按下去就在一个带日期的分支上做 commit，比如vibecode/2025-06-01。这样，"恢复现场"就从"恢复对话文字"升级成了"恢复那一刻的代码状态"。

3.3 上下文压缩策略：长对话如何塞进新会话

Token 预算是长会话绕不开的话题。一个项目聊到深处，消息条数动辄上百，上下文窗口很快见底。我的做法是两层压缩。

第一层，接近阈值时触发摘要压缩。让当前模型把之前的历史"摘要化"，重点保留三类信息：已经做出的决策、改动过的文件和路径、还没完成的事项。摘要本身也按 JSONL 记录下来，方便追溯。第二层，恢复会话时，工作区采用"摘要 + 最近 20 条完整消息"的组合作为上下文启动，而不是全量回放。实测下来，长会话的 token 消耗能降一半以上，而模型对项目当前状态的理解没有明显掉线。

需要警惕的是压缩不能无脑重复。摘要累加次数太多会越来越失真，我设了上限，超过之后做两级摘要：先按主题分块摘要，再汇总成总摘要，比单次硬压缩保真度高得多。

3.4 可选的状态缓存层：Redis 持久化怎么配才不丢数据

单机单实例场景，SQLite 完全够用，没必要上 Redis。但你要是想让多台开发机共享同一个工作区状态，或者让多个后端实例做负载均衡，这时候 Redis 就派上用场了——会话状态放 Redis，所有实例读到同一份数据。

一旦上了 Redis，就要面对 Redis 自身的持久化问题。RDB 是定时全量快照，掉电可能丢最近几分钟数据；AOF 是追加写日志，配合appendfsync everysec最多丢 1 秒数据。我的推荐配置是：

appendonly yes appendfsync everysec auto-aof-rewrite-percentage 100 auto-aof-rewrite-min-size 64mb

everysec是性能和安全的折中。如果使用 RDB 模式，用于纯缓存场景可以接受，但会话状态不可丢，建议还是开 AOF。AOF 文件无限膨胀的问题靠自动重写解决，上面两条auto-aof-rewrite-*就是干这个的。

RDB 和 AOF 的取舍，可以看这个表：

4. 浏览器里的开发体验：文件树、内嵌终端与差异预览

4.1 用 Monaco 复用 VS Code 级编辑体验

Web 工作区的编辑器，我直接选了 Monaco——和 VS Code 同一个内核，语法高亮、智能提示、多光标这些能力等于白送。要是用浏览器原生textarea做编辑器，项目稍微大一点就根本没法用，光一个跳转到定义就够折腾。

工作区左侧是项目文件树，点击文件在编辑器打开；AI 改完文件，编辑器通过 WebSocket 收到刷新事件后自动加载最新内容。实际体验下来，编辑体验和 VS Code 几乎没有区别，这给"能不能彻底脱离本地编辑器"这个问题提供了一个可行的答案。

4.2 流式渲染 AI 输出：从 ANSI 到 HTML

CLI 通过 PTY 输出的内容里，除了 AI 正文，还有大量 ANSI 转义序列——颜色、光标移动、清屏指令。这些直接塞进 HTML 会乱套。我的处理分两步：先解析 ANSI 转义，把颜色信息映射成 CSS class；再把工具调用（Bash、Edit 等）渲染成可折叠的卡片，默认只展示命令和结果摘要，点击展开看完整输出。

diff 内容尤其值得单独处理。识别到git diff输出后，前端会切成左右对照的视图，插入、删除、修改分别高亮，人眼扫一遍就知道 AI 改了什么，比在终端里盯滚动日志强十倍。聊天记录一长，渲染性能也要考虑。我做了虚拟列表，只渲染视口附近的节点，滚动时回收远端 DOM。实测几百条长消息的会话滚动起来也流畅。

4.3 多会话标签与项目绑定

工作区是一个"项目维度"的组织方式：打开工作区后，先选项目，再开会话。每个标签页绑一个 CLI 进程、一个 JSONL 会话文件、一个工作目录。你完全可以并行跑多个任务：一个会话让 Claude Code 重构后端，另一个会话让 Codex 写测试，互不干扰。

多设备访问也算刚需。让服务绑定0.0.0.0之后，局域网内的平板、手机都能连上来。我经常在家用 iPad 连台式机上的工作区，看看昨天的日志、改改需求描述，体验比远程桌面轻量得多。

5. 后端切换实战：从官方 API 到本地模型/兼容 API

5.1 配置中心统一管理

Claude Code 和 Codex 的配置差异不小。工作区里做一个统一的配置中心，把后端差异收口，启动进程前自动转成对应的环境变量和启动参数，避免每次重启重新配。

一份典型的配置长这样：

backend: codex # claude | codex model: deepseek-chat base_url: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY allowed_tools: ["Bash", "Edit", "WebSearch"]

配置中心统一管理的好处是，换模型、换后端都只改一份文件，CLI 进程始终从同一份配置里读取，不会再出现"这个终端配的是 A 模型，另一个终端配的是 B 模型"的混乱。

5.2 Claude Code 的配置要点

Claude Code 配置的核心是三个东西：API Key、模型选择、工具白名单。API Key 通过ANTHROPIC_API_KEY注入，模型名写清楚用哪个版本，工具白名单控制 AI 能调用的能力范围。

在 Web 工作区里有坑：通过子进程启动的 CLI 不读你终端的 shell profile。你明明在.bashrc里 export 过 Key，但工作区 spawn 出来的进程压根没走那套加载逻辑，结果就是"终端里好好的，工作区里报 401"。解决方式是配置中心显式注入环境变量，不依赖 shell 环境。这个坑我后面还会细讲。

5.3 Codex 接入 OpenAI 兼容 API：以 DeepSeek 为例

Codex 走的是 OpenAI 的 Responses 协议，默认请求/responses端点。而 DeepSeek 这类第三方服务，通常实现的是更常见的/chat/completions。能不能接入，取决于对端是否实现了/responses。

配置上，核心是两行环境变量：

OPENAI_API_KEY=DEEPSEEK_API_KEY OPENAI_BASE_URL=https://api.deepseek.com/v1

模型名要写对：deepseek-chat或deepseek-reasoner。如果目标服务不提供/responses，而你又必须用 Codex，就只能在中间加一个转换层——自己写一个极简的转发服务，接收到/responses格式的请求，转成/chat/completions，再把流式响应转发回去。几十行代码的事，但协议细节不少，这个具体放在踩坑部分说。

5.4 用 LMStudio 把本地模型拉进来

本地模型接入是很多人的联想场景——数据不出内网，或者纯粹为了省成本。以 LMStudio 为例，它启动后暴露一个 OpenAI 兼容端点http://127.0.0.1:1234/v1，工作区里把base_url指过去就能用。

但要注意，不是随便一个本地模型都能当好编码代理。模型必须支持工具调用（tool calling / function calling），否则 AI 只能聊天，没法真正执行 Bash、改文件。实测下来，Qwen 这类工具调用能力稳定的模型优先，纯聊天优化的模型做编码代理会非常吃力。还要务实一点：本地模型跑小项目、做代码解释、生成单元测试没问题；大型重构、长上下文任务，还是交给云端的旗舰模型更靠谱。

6. 集成路上踩过的三个坑与完整排查链路

6.1 切换 Codex 端点后 /responses 调用失败

现象：把 Codex 从官方端点切到另一个兼容服务后，发第一条消息就报错，日志里出现类似"codex endpoint /responses ... failed while handling ..."的提示，前端会话直接中断。

我的排查链路是这样的。第一步，绕开 CLI，用 curl 直接打目标端点，确认问题在服务端还是客户端：

curl -v https://api.example.com/v1/responses \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ -d '{"model":"deepseek-chat","input":"hi"}'

第二步，看返回状态码。404 或 405，通常是对端根本没实现/responses；401 是鉴权问题；429 是限流。我当时拿到的是 404，基本锁定：对端只有/chat/completions，没有/responses。第三步，检查 Base URL 路径有没有拼接重复。比如上游 Base URL 已经是/v1，你又在配置里拼了/v1/responses，实际请求会变成/v1/v1/responses，必然 404。这个低级错误排查成本很低，但要耐心看完整 URL。

最终解决是加了一层转换服务，把/responses映射到/chat/completions，流式响应再原路返回给 CLI。教训非常明确：接第三方端点前，先 curl 验明协议，别在配置里瞎试。

6.2 auth token is unavailable：环境变量与凭据加载顺序

另一个高频报错是 Codex 启动时抛 "auth token is unavailable"，但宿主终端里明明 export 过 API Key。这属于典型的配置来源混乱。

排查第一步，检查 CLI 的凭据加载顺序。这类工具一般优先级是：本地登录态文件 > 环境变量 > 交互登录。系统里如果残留过旧的登录态，CLI 会优先读它，而那个 token 可能早就失效了，环境变量里的新 Key 根本不生效。排查第二步，检查工作区里的 env 是否真正传到了子进程。Web 工作区 spawn 的进程，继承的是 Node 进程的环境变量，不读 shell profile。你export在.bashrc里的 Key，它看不见。排查第三步，核对变量名。是OPENAI_API_KEY还是CODEX_API_KEY，不同 CLI 版本认的变量名不一样，配置中心里写错名字，进程拿不到值，自然也报 token unavailable。

最后我的解决方案是：配置中心里为每个后端独立维护全局 env，启动进程前逐个注入，并且健康检查时打印当前 Key 的来源，一眼看出是环境变量还是文件。这个问题表面是 token 丢失，本质是"配置来源混了"，统一收口之后就没再犯过。

6.3 长任务跑挂：PTY 缓冲区与进程假死

有一次让 agent 重构一个大目录，跑了十几分钟，前端突然不更新了。任务没结束，但不再有输出。检查子进程还活着，stdout 却卡住了。

根因是 PTY 输出缓冲区被填满。进程持续吐数据，某个环节消费不及时，输出管线就阻塞了，AI 代理以为还在等待输出，任务直接挂起。这种问题在终端里几乎不会出现，因为终端一直在消费输出；但包成 Web 服务后，任何一个中间环节处理速度跟不上，就会连锁阻塞。

排查时我给所有 CLI 输出都打了时间戳日志，定位到"最后一行输出是什么时候"，再查前端是否还活着：手动推一条消息过去，如果前端有响应，说明 WebSocket 链路正常，问题就在进程输出解析端。解决手段有三个：保证 stdout 被实时消费，读一行写一行存储、推一行前端；加心跳探测，每 5 秒检查子进程存活和队列增长情况，连续 3 次没进展就 kill 并自动重启，再用最近会话快照恢复现场；给单条工具执行加软超时，超过设定分钟数视为异常，取消任务而不是干等。

6.4 附带一个高频小坑：会话恢复时上下文叠罗汉

最后补充一个每次恢复都会遇到的坑。某些 CLI 自带的续接功能会把上次历史整个加载进上下文，而工作区如果又把 JSONL 里最近的完整消息拼进提示词，模型就会同时收到两遍重复内容，越聊越犯傻。

我把恢复策略做成了配置项，三选一：只用 CLI 原生恢复、只用工作区摘要加最近消息、两者都禁用（手动指定）。默认走原生恢复，CLI 不支持时才退化到摘要方案。这样从机制上避免重复注入，也避免了"恢复一次，傻半分"的体验问题。

7. 实际使用体验与后续规划

这个项目我自己用了一段时间，日常工作流已经完全切换到工作区里了。上午在台式机上让 Claude Code 改后端逻辑，下午出去用笔记本打开同一个项目目录，会话、改动摘要、快照全都在，不需要重新回忆。局域网内用平板接力的场景也很顺手，改需求、看日志都不需要正襟危坐地坐在工位上。

上下文压缩带来的收益是实打实的：一个长会话的 token 消耗降了一半以上，模型对项目当前状态的理解并没有明显掉线。这说明"摘要 + 最近消息"的组合在工程上是成立的方向。

后续规划里，我把摘要质量放在第一位，想针对长项目做更结构化的项目记忆，而不是单纯压缩文本。其次是多人实时协作，让两个人同时盯一个会话，避免 AI 干活时没人 review。最后是插件体系，让用户自定义某种工具结果的渲染方式——比如内部框架的日志格式、SQL 执行结果的可视化。

做完这个项目我最大的体会是：工具的高频使用不是因为它功能多，而是因为它"记得"你。每次打开工作区，上次聊到一半的实现方案、改过的文件、还没试的思路，都原样摆在那里。这种"接着干"的感觉，才是 Vibecoding 真正的氛围，也才是 AI 编码工具从玩具变成生产力的分界线。如果你也在折腾 Claude Code / Codex 的 Web 化封装，欢迎多交流。上面这些坑基本是我踩出来的第一手经验，能帮你少走不少弯路。