如果你最近在终端里重度使用 Claude Code 或者 Codex 写代码大概会有一种很矛盾的感觉效果很爽但过程很散。命令跑完就结束了会话记录躺在本地目录里想找回昨天的设计决策只能去翻一堆 JSONL换个项目又是白纸一张背景材料得重新贴一遍想在另一台机器上接着干基本等于从头再来。Easy Web Vibecoding 这个项目就是冲着这几个痛点来的——它把 Claude Code / Codex 这类命令行 AI 编码工具封装成一个带持久化能力的 Web AI 编码工作区浏览器打开就能用会话、上下文、文件变更都能按项目保存和恢复。如果你正被终端会话的碎片化困扰或者想把 AI 编码能力嵌入团队工作流这篇内容可以给你一套直接照搬的架构思路和若干真实踩坑记录。1. 为什么 Claude Code / Codex 需要一个带记忆的浏览器工作区1.1 终端里的 AI 编码爽点与痛点一样明显先说清楚一点Claude Code、Codex 本身做得很强。直接在命令行里交代任务、看它改代码、跑测试这种紧密的循环是 IDE 插件比不了的。但用到一定频率后几个问题会特别扎眼。第一是会话碎片化。今天上午做数据库重构下午写 API 层晚上修一个 bug每一轮都是独立会话。工具会在本地存 session 历史可那是工具视角的存档不是你的工作台。你想基于上午的结论继续推进就得找到上午那条会话的 session id然后用--resume恢复。运气好的话能找到运气不好直接忘记当时聊到哪了。第二是上下文断裂。每次开新会话模型对项目的了解为零。你不得不把这个项目是干什么的、目录结构长啥样、代码风格是什么、目前的坑有哪些重新粘贴一遍。我第一次在连续三个会话里重复粘贴同一份技术方案说明时就意识到这事必须自动化。第三是多设备和团队协作的隔阂。你在本地终端跑出来的结果同事看不到换台电脑所有上下文都不在。对于让 AI 帮忙改代码的场景这种隔离特别致命——因为 AI 编码本身就是一个过程而不是一次命令过程丢了结果很难被信任。1.2 持久化到底在持久化什么很多人一听持久化就以为是 Redis 那种防止宕机丢数据的东西概念上有一点关系但实际要解决的问题完全不同。我给这套工作区定了三层持久化目标缺一不可会话持久化能把中断的对话现场完整恢复包括之前讨论过的约束条件、已经达成的设计取舍。上下文持久化项目背景、技术栈说明、代码规范、常见坑能沉淀下来并在每次新会话自动注入。状态持久化AI 对文件做的每一次修改都有记录改了哪个文件、为什么改、改了之后能不能回退全部可追溯。如果要用一个类比就是你的编码工作区不再是一张即写即走的便利贴而是一本带目录、带修订历史、带书签的工程笔记。Redis 的 RDB/AOF 解决的是进程挂了数据不丢这套工作区解决的是人换了场景、换了设备之后上下文不丢。技术上我确实借鉴了全量快照加增量日志的思路后面会详细展开。1.3 什么人最需要这样一套东西我实际用下来三类人受益最明显。一类是像我这样一天要并行推进三四个任务的个人重度用户工作区能按项目把任务分组来回切换不迷路第二类是两三人小组共用一个开发账号的团队AI 会话不再锁在某个人的终端里产出和过程都能共享第三类是在远程开发机、云主机上跑命令行的用户——CLI 装在远端但通过浏览器访问省去到处同步环境的麻烦。当然如果你只是偶尔用命令行让 AI 改个正则、写个脚本那确实不需要这么大动干戈直接用官方 CLI 就够了。2. 工作区架构拆解把终端里的 AI 编码工具搬进浏览器2.1 整体结构与数据流整个工作区分成四层浏览器前端、后端服务、CLI 工具层、存储层。前端是聊天面板加文件树加 diff 视图的布局后端我用 Node.js 写负责起子进程、解析输出、读写存储、推送流式结果CLI 层就是 Claude Code 和 Codex 的可执行文件存储层用 SQLite 加文件系统SQLite 存结构化数据原始 JSONL 流保留在磁盘上做审计。一次完整请求的数据流是这样的浏览器输入消息 → 后端创建任务记录 → 后端按工作区配置启动 CLI 子进程 → CLI 的 JSONL 输出被逐行解析 → 解析结果写入 SQLite 和增量日志 → 同时通过 SSE 推回前端渲染。这个链路最关键的一点是后端和 CLI 之间通信永远走结构化输出而不是去解析给人看的终端文本。我见过不少类似项目为了省事直接抓终端彩色输出结果换个主题颜色、换个错误格式就全崩了。结构化输出是持久化的地基。2.2 SSE 为什么够用而不是非要 WebSocket刚开始我也考虑过 WebSocket但做了一阵子后确定 SSEServer-Sent Events在大部分场景是更优解。AI 编码的本质是长时间的单向流式输出服务器不断把新的 token 推给浏览器中间浏览器基本不需要往服务器发东西。SSE 天然支持断线重连自带事件 ID实现起来只有几十行代码。WebSocket 要处理心跳、粘包、连接状态同步工程复杂度高一个量级。唯一让我觉得不够用的是取消生成这种反向操作但解决办法很简单——单独做一个普通的 POST 接口前端点取消时调一下后端给子进程发 SIGINT没必要为此维持一条双向长连接。还有一个容易忽略的点如果工作区部署在 Nginx 后面SSE 会被缓冲导致用户看到的是一顿一顿的输出。需要在反向代理层关掉缓冲或者干脆在测试阶段先用直连端口跑。2.3 子进程管理是整个项目最容易翻车的地方CLI 工具有交互模式和非交互模式两种用法。交互模式pty能拿到最完整的工具能力但要处理终端仿真、输入回显、控制字符复杂度非常高。我的实践是后端统一走非交互模式Claude Code 用-p参数执行单轮任务Codex 用exec子命令两者都支持结构化 JSONL 输出。关于每次任务起一个新进程还是常驻一个长进程我一开始图省事想长驻后来被状态污染坑了几次就改成了任务级进程每个任务启动独立的 CLI 进程结束后立即退出。代价是每次请求多几百毫秒启动开销换来的是任务之间完全隔离不会有历史环境变量残留也不会出现上个任务的输出混进下个任务。Node.js 里启动子进程的核心代码大概是这样的const { spawn } require(child_process); function runCliTask({ cli, args, cwd, onLine, onExit }) { const child spawn(cli, args, { cwd, env: process.env, stdio: [ignore, pipe, pipe], }); let buffer ; child.stdout.on(data, (chunk) { buffer chunk; const lines buffer.split(\n); buffer lines.pop(); for (const line of lines) { if (line.trim()) onLine(line); } }); child.on(exit, (code) onExit(code)); return child; }这里的buffer处理非常重要。JSONL 流不是按行到达的一个完整的 JSON 行可能被拆成多次 data 事件不攒够了再切分就会出现解析错误。另外超时和取消一定要挂在进程组级别光杀掉子进程本身它派生出去的 git 命令、测试进程可能还在跑。3. 持久化三件套会话、上下文、文件快照的落地设计3.1 会话持久化把 CLI 的 session id 变成工作区的一等公民Claude Code 和 Codex 都有自己的会话恢复机制Claude Code 可以用--resume加 session id 回到之前的对话Codex 也支持类似的 session 管理。我的做法不是重造一套对话存储而是把 CLI 原生 session id 作为字段存进自己的数据库在工作区层面建立映射。这样一个任务结束后就算后端重启、浏览器关掉只要数据库里还存着工作区 A Claude session id xxx 最终任务状态用户随时可以点一个按钮恢复现场。数据库表设计上核心是三张表workspaces存项目信息sessions存 CLI 会话映射messages存解析后的消息记录。CREATE TABLE workspaces ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, project_path TEXT NOT NULL, cli_tool TEXT NOT NULL, -- claude / codex system_prompt TEXT DEFAULT , created_at TEXT DEFAULT CURRENT_TIMESTAMP ); CREATE TABLE sessions ( id INTEGER PRIMARY KEY AUTOINCREMENT, workspace_id INTEGER NOT NULL, cli_session_id TEXT, -- Claude / Codex 原生的会话 ID status TEXT DEFAULT active, -- active / completed / failed current_task_id INTEGER, created_at TEXT DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (workspace_id) REFERENCES workspaces(id) ); CREATE TABLE messages ( id INTEGER PRIMARY KEY AUTOINCREMENT, session_id INTEGER NOT NULL, role TEXT NOT NULL, -- user / assistant / tool content TEXT NOT NULL, raw_json TEXT, -- 保留原始 JSONL created_at TEXT DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (session_id) REFERENCES sessions(id) );我特意保留了raw_json字段。解析出来的结构化字段是给人看的原始 JSONL 是给审计和排错用的两份都留缺一不可。很多线上问题靠结构化日志根本看不出原因翻原始输出才发现是某个工具返回了异常格式。3.2 上下文持久化让每个新会话都从懂事开始这一层是我觉得整个工作区价值密度最高的部分。做法不复杂每个工作区维护一份workspace_knowledge里面包含项目说明、技术栈、目录约定、关键命令、常见坑。每次发起新任务时后端把这份知识注入到系统提示词里。关键在设计知识的更新机制。纯手动维护肯定坚持不下去我的方案是自动摘要加人工确认每个任务结束后后端额外让模型生成一段两百字以内的摘要内容包括这个任务做了什么、对项目有哪些新的认知、有什么需要注意的陷阱然后追加到知识库。下次开会话时模型就带着之前十几个任务的教训来干活效果提升非常明显。上下文模板我写得很简单核心就一段你在项目 {project_name} 中工作。 项目简介{description} 技术栈{stack} 代码约定{conventions} 已知注意点{known_issues} 请基于以上背景处理用户请求。如果请求涉及你没有把握的历史决策先查看 review 记录再动手。这里有个容易被低估的细节知识库一定按工作区隔离不能全局共享。不同项目的约定经常冲突全局混在一起反而会让模型精神分裂。宁可每个项目重复存几段通用内容也不能省这个隔离。3.3 文件变更追踪把 AI 的每一次修改变成可回退的决策记录AI 编码工具会直接改文件这是风险点。我要求后端在任务开始前记录 git 基线任务结束后生成 diff并把每次修改的文件列表存进file_changes表。CREATE TABLE file_changes ( id INTEGER PRIMARY KEY AUTOINCREMENT, task_id INTEGER NOT NULL, file_path TEXT NOT NULL, change_type TEXT NOT NULL, -- added / modified / deleted diff_content TEXT NOT NULL, commit_hash_before TEXT, commit_hash_after TEXT, reviewed INTEGER DEFAULT 0, created_at TEXT DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (task_id) REFERENCES sessions(id) );实际操作中我还会在任务开始前自动打一个 git commit任务结束后再打一个。这样想回到任意时间点都能直接git reset。很多人担心自动 commit 会污染提交历史我的经验是新建一个ai-work分支专门放这些自动提交确认无误后再 cherry-pick 到主分支既安全又干净。4. 从零接入 Claude Code 和 Codex关键参数与配置细节4.1 Claude Code走上--output-format jsonl这条路Claude Code 的非交互模式是后端接入的最佳入口。命令长这样claude -p 重构 userService 中的数据库查询逻辑 \ --output-format jsonl \ --verbose \ --session-id 存在的会话ID-p表示非交互打印模式适合程序化调用--output-format jsonl让输出变成一行一个 JSON 对象每个对象都有type字段标明是 user 消息、assistant 文本还是工具调用结果。后端拿到这些行以后按type分发到不同处理逻辑即可。--verbose这个参数容易被忽略但它能输出很多中间状态包括思考过程和内部工具调用对追踪为什么模型做了这个决定特别有用。我在长期运行的服务器上还会加一个--dangerously-skip-permissions跳过交互式授权确认——注意这必须配合工作区的文件变更追踪机制才能用否则 AI 改文件完全没有人工审查环节风险极高。4.2 Codex用exec子命令驱动任务式编码Codex 这边我主要用codex exec它的设计是一次执行一个任务和我的任务级进程模型天然契合。基本调用codex exec 给 README.md 补充 API 文档 \ --json \ --config /path/to/workspace/codex/config.toml--json选项让输出变成结构化 JSON 流和 Claude Code 的 JSONL 非常像后端可以复用同一套解析管道。需要注意Codex 的模型配置在config.toml里不同项目可能需要不同模型所以我把配置文件按工作区隔离每个 workspace 绑定一份config.toml任务启动时通过--config指定。对于想要接入兼容协议模型服务的场景比如本地模型或者第三方兼容端点关键配置通常是这样model 你配置的模型名 model_provider compatible只要 CLI 能访问到你配置的 API 地址就可以正常工作。本地模型服务的优势是数据不出开发机比如通过 LMStudio 这类工具在本地起一个兼容服务然后把地址指过去直接将 API Address 配置为环境变量指向模型服务地址是同样可行的方案核心原则是保证 CLI 工具所在的环境能访问到对应服务地址即可。4.3 配置管理CC Switch 与工作区配置快照用久了你就发现配置管理是个隐形的深坑。Claude Code 有它自己的配置目录Codex 也有不同项目可能要不同的模型、不同的系统提示、甚至不同的 API 端点。我一开始手动改环境变量切来切去经常出错。CC Switch 这类工具解决的是多套配置快速切换的问题它维护多份 CLI 配置切换时把对应配置写到实际读取位置。我把这个思路进一步整合到工作区里每个 workspace 保存一份配置快照包含 CLI 类型、模型名、API 地址等关键字段启动任务时后端把快照同步到子进程的环境变量。这里必须提醒一个极其容易踩的坑后端是常驻进程如果切换了 CC Switch 的配置但后端进程没有重启那么子进程继承的仍然是旧的、缓存的环境变量。我在 5.1 节会讲一个真实案例问题现象非常隐蔽。4.4 跑通一次完整请求从浏览器到代码落盘整个链路搭建完验证起来分四步走启动服务创建 workspace绑定一个真实项目目录。在浏览器里发一条消息后端日志能看到任务记录生成。为了排查方便先用 curl 测 SSE 接口curl -N http://localhost:3000/api/tasks/stream?taskIdxxx能逐段看到输出流说明链路通了。任务结束后去数据库里查file_changes表有没有记录再刷新前端页面确认工作区是否保存了完整会话。我建议前三次跑都开着后端日志重点看 CLI 子进程的启动参数和环境变量是否正确。这一段链路涉及的环节太多前端、后端、CLI、存储任何一处拼错都可能表现为浏览器没反应。5. 实跑一个多月踩到的坑连接失败、断流、进程残留5.1 本地端点连接失败类错误一次标准定位过程有一次切换 CC Switch 配置后往 Codex 发请求后端立即返回一个类似本地端点连接失败请求 /responses 失败的错误。当时第一反应是网络问题折腾了半小时才发现根本不是。完整排查链路是这样的看后端日志发现是 CLI 子进程报的错后端与 CLI 之间的管道一切正常。在命令行里手动执行同一条codex exec命令结果成功。这排除了模型服务和网络的问题。对比手动执行和后端子进程的环境差异发现关键点在环境变量——CC Switch 切完配置后把 API 地址写进了它管理的配置文件但常驻的后端进程环境变量还是启动时的旧值加载的仍然是旧的端点地址。重启后端进程错误消失。这个案例给我的教训很深刻常驻服务加动态配置必须考虑配置热加载或者显式的重启。现在我的后端在每次任务启动前都会重新读取一次配置快照从根上规避了这类问题。如果你也遇到切完配置就报错的情况先别怀疑网络检查你后端进程的环境变量。5.2 长任务断连SSE 保活和任务恢复跑一个五六分钟的代码生成任务浏览器端经常出现连接已断开的提示。刚开始我以为是自己实现有问题排查发现服务端日志显示一切正常CLI 子进程还在跑但前端已经收不到数据了。看细节发现是连接的中间层存在空闲断开机制。SSE 连接保持打开但没有数据时长连接会被切断。解决方法是服务端定时发送 SSE 注释行作为心跳const heartbeat setInterval(() { res.write(: keepalive\n\n); }, 15000);同时我在设计上刻意把任务执行和浏览器连接解耦。任务状态由后端持久化驱动浏览器断开后任务照常执行前端 EventSource 自动重连后通过GET /api/tasks/:id/status拿到中间错过的输出。这一点对于远程开发环境尤其重要断网不等于任务断了。5.3 进程残留与端口占用多次重启后端后端口被占用或者旧任务还偷偷在改文件。原因是直接杀 Web 服务进程时它派生的 CLI 子进程成了孤儿进程继续跑。解决办法是创建独立的进程组杀掉服务时连组一起杀。Node.js 里可以用detached: true配合process.kill(-pid)Windows 上则用taskkill /pid pid /T /F杀整个进程树。另一个习惯是启动后端前检查端口占用端口被占时明确提示而不是等到请求才报错——这个小改动能让你少骂很多次脏话。5.4 输出截断、乱码与 JSON 解析失败最后一个高频问题CLI 输出偶发一行 JSON 没读完的截断错误。原因通常是管道缓存或行缓冲处理不当解决方式就是前面代码里的 buffer 攒行法——先按分隔符切剩下的留在 buffer 里等下一块数据。还有一个是真乱码Windows 控制台的代码页和 UTF-8 不一致时JSON 里的中文全变问号。我在启动子进程时强行设置LANGzh_CN.UTF-8或PYTHONIOENCODINGutf-8之类的环境变量并确认终端服务以 UTF-8 运行问题基本绝迹。6. 下一步从能用到好用6.1 多人协作与操作审计目前在做的第一个升级是多人协作给用户加登录和角色任务归属到人。所有 AI 对文件的修改默认进入 review 队列人工确认后才落到主分支。这会牵扯到把 diff 视图做得更好用——能看到 AI 改了哪几行、为什么要改、对应的是哪条指令这样的审计能力在实际协作里比想象中重要得多。6.2 自动摘要与项目知识库第二个方向是知识沉淀的自动化。现在每完成一个任务我已经让模型自动生成摘要进知识库但这只是第一版。下一步打算把项目的文档目录也纳入索引让模型在需要时能主动检索历史文档而不是只靠注入的摘要。简单场景下先直接拼接文档关键段落避免过早引入向量检索的复杂度等文档库大到拼接不合理了再考虑检索增强。6.3 一点真实的个人体会做这个项目的过程中我最深的感受是持久化不是存储层面的问题而是产品层面的问题。会话、上下文、文件状态这三种持久化在做第一版架构时就该分开设计混在一起后面一定返工。另一个让我意外的经验是任务标签这个很小功能带来的收益——给每个任务打上bugfix、refactor、docs这类标签几周后按标签筛选历史任务时你会发现那些当初随手加的 tag 变成了极有价值的项目脉络。如果你也打算搭一个自己的工作区我建议从一开始就加上这个字段成本极低回报远超预期。