1. 为什么需要一个持久化的 Web AI 编码工作区1.1 从本地终端到浏览器编码工作流的迁移逻辑过去大半年Claude Code 和 Codex 这两类 AI 编码工具几乎成了开发者日常绕不开的东西。但真正长期用下来的人都会发现一个很现实的问题它们默认都活在终端里。终端本身没问题轻量、快、跟系统贴合可一旦你开始同时跑多个项目、多个会话或者需要在不同设备之间切换终端方案的短板就暴露得非常明显——会话一关就断上下文一丢就得重来历史记录散落在各个 shell 里想回溯某次改动到底是怎么生成的基本靠翻 scrollback。Easy Web Vibecoding 这个项目要解决的就是这件事。它的核心定位很直接把 Claude Code / Codex 这类 AI 编码能力包装成一个持久化的 Web 工作区。所谓持久化包含三层意思。第一层是会话持久化你关掉浏览器再打开之前的对话、上下文、正在编辑的文件状态都还在第二层是工作区持久化项目文件、依赖、运行环境不随会话销毁而消失第三层是配置持久化模型接入方式、代理设置、快捷键、主题这些个性化配置一次配好长期复用。这个思路为什么值得做因为 AI 编码的真实使用场景早就不是问一句答一句的玩具阶段了。现在一个完整的编码任务可能是让 AI 读十几个文件、改五六个模块、跑一轮测试、再根据报错迭代三四轮。这种长链路任务对上下文连续性的要求极高终端方案在会话管理上天然吃亏。Web 工作区把状态托管在服务端浏览器只是渲染层这就从架构上解决了连续性问题。适合谁来用三类人最受益。一是同时维护多个项目的独立开发者需要快速在项目间切换而不丢上下文二是团队里想把 AI 编码能力共享出来的场景一个人配好环境其他人通过浏览器直接接入三是经常换设备的人公司电脑、家里台式、笔记本打开浏览器就是同一个工作区不用每台机器重新装一遍 Claude Code 或者 Codex。1.2 核心需求拆解持久化到底解决哪些痛点把持久化 Web AI 编码工作区这个需求拆开看实际要解决的是四个具体痛点。痛点一会话生命周期与任务生命周期不匹配。一个编码任务可能持续几小时甚至跨天但终端会话往往因为网络抖动、误关窗口、系统休眠而中断。Web 工作区把会话状态存在服务端浏览器断线重连后能恢复到断线前的状态任务生命周期不再被会话生命周期绑架。痛点二多工具切换成本高。Claude Code 和 Codex 各有各的强项实际工作中经常需要交叉使用。但两个工具的命令行界面、配置方式、认证流程都不一样来回切换很烦。Web 工作区可以在同一界面下管理多个后端用统一的交互层去调用不同的 AI 编码引擎。痛点三环境配置重复劳动。每换一台机器Claude Code 安装、Codex 安装、Node 版本、依赖、认证 token全套走一遍。Web 工作区把环境收敛到服务端一处客户端零配置。痛点四协作与审计困难。终端里的 AI 编码过程是黑盒别人看不到你让 AI 做了什么、AI 改了什么。Web 工作区天然有日志和状态记录方便回看和分享。理解了这四个痛点就能明白为什么这个项目不是把终端搬到浏览器这么简单而是一次针对 AI 编码工作流的架构重设计。2. 整体架构设计与技术选型考量2.1 前后端分离为什么浏览器只做渲染层Easy Web Vibecoding 的架构核心是前后端彻底分离。前端是一个纯浏览器应用负责界面渲染、输入输出、文件树展示、diff 高亮这些展示层工作后端是一个常驻服务负责会话管理、文件系统操作、AI 引擎调用、进程管理这些有状态的工作。这么设计的原因很实在。AI 编码任务本质上是有状态的长任务它需要持续访问文件系统、维持对话上下文、管理子进程。如果把这些放在浏览器里受限于浏览器的沙箱模型和生命周期根本做不稳。浏览器标签页一关Web Worker 就没了IndexedDB 虽然能存数据但存不了进程状态。所以有状态的部分必须放服务端浏览器只做无状态的展示和输入。这个划分带来的直接好处是你可以用任何设备、任何浏览器接入同一个工作区体验完全一致。手机浏览器打开看到的是同一个会话、同一份文件树、同一段对话历史。这在终端方案里是做不到的。2.2 会话持久化的实现路径状态存哪里、怎么恢复会话持久化是这个项目的技术核心实现上分三层。第一层是对话状态。每次用户输入、AI 回复、工具调用结果都作为一条消息记录写入服务端的持久化存储。存储介质选型上轻量场景用 SQLite 就够了单文件、零运维、支持事务如果要多实例部署换成 PostgreSQL。消息记录里除了内容本身还要存时间戳、关联的会话 ID、引用的文件快照这样恢复时能完整重建上下文。第二层是文件系统状态。工作区里的项目文件是真实存在于服务端磁盘上的不是虚拟的。AI 对文件的修改直接落盘所以文件状态天然持久。这里要注意的是并发控制——如果同一个工作区被多个浏览器同时打开文件写入需要加锁否则会出现两个会话互相覆盖的情况。常见做法是按文件粒度加读写锁或者用乐观并发控制加版本号校验。第三层是运行时状态。比如正在跑的 dev server、正在执行的测试进程、终端里挂着的长任务。这部分状态最难持久化因为进程本身是有生命周期的。实际方案通常是进程状态记录在服务端进程崩溃或服务重启后根据记录尝试恢复对于无法恢复的进程至少保留它的输出日志让用户知道之前跑到哪了。恢复流程是这样的浏览器连接时带上会话 ID服务端根据 ID 查出对话历史、文件快照、运行时记录然后把状态推给前端重建界面。整个过程对用户透明感觉就像从没离开过。2.3 多引擎接入Claude Code 与 Codex 如何统一调度Claude Code 和 Codex 虽然都是 AI 编码工具但它们的调用方式、认证机制、输出格式都不一样。要在一个工作区里统一调度需要一个抽象层。抽象层的设计思路是定义一套统一的编码引擎接口包含几个核心方法初始化会话、发送指令、接收流式输出、执行工具调用、销毁会话。每个具体引擎Claude Code 适配器、Codex 适配器实现这套接口把各自的差异封装在适配器内部。上层的工作区逻辑只跟接口打交道不关心底层是哪个引擎。这样做的好处是扩展性强。以后要接入新的 AI 编码引擎只需要写一个新的适配器工作区逻辑不用动。同时用户可以在同一个会话里切换引擎——比如先用 Claude Code 做架构设计再切到 Codex 做具体实现上下文通过工作区层传递两个引擎都能看到完整的项目状态。认证方面每个引擎的 token 或 API key 存在服务端的加密配置里前端不接触敏感凭证。这样即使浏览器被他人使用也拿不到底层凭证。2.4 技术栈选型为什么是这套组合具体技术栈上后端我倾向于 Node.js TypeScript。原因很直接Claude Code 和 Codex 的官方工具链本身就是 Node 生态的用 Node 做后端能最大程度复用官方 SDK 和 CLI减少适配成本。TypeScript 则是为了在适配器这种多实现场景下保证类型安全减少运行时错误。前端用 React Vite。React 的组件模型适合做文件树、对话流、diff 视图这类复杂 UIVite 的开发体验和构建速度在同类工具里属于第一梯队。状态管理上工作区状态复杂但结构清晰用 Zustand 这类轻量方案就够没必要上 Redux。持久化存储默认 SQLite通过 better-sqlite3 这类同步驱动访问简单可靠。文件监听用 chokidar跨平台表现稳定。进程管理用 Node 的 child_process配合 node-pty 做终端模拟。这套选型的核心原则是贴近官方工具链、减少中间层、优先成熟稳定。AI 编码工具本身迭代很快技术栈越简单跟进官方更新时越省力。3. 核心功能模块的实操要点3.1 工作区初始化从零到可用的完整流程工作区初始化是整个系统的入口流程设计得好不好直接决定第一次使用的体验。完整流程分五步。第一步创建workspace。用户在界面上点新建工作区输入名称选择基础镜像或模板。服务端在指定目录下创建workspace文件夹初始化 git 仓库写入默认配置文件。这里有个细节workspace目录要跟服务端的代码目录隔离避免用户项目文件污染服务本身。第二步配置引擎。选择要接入的 AI 编码引擎填入对应的认证信息。Claude Code 需要配置 API 凭证或订阅认证Codex 需要配置对应的 token。这些信息加密后存入服务端配置库前端只显示已配置状态不回显明文。第三步拉取或初始化项目。可以从 git 仓库克隆也可以从模板创建或者直接上传文件。克隆时要注意大仓库的处理建议加--depth 1做浅克隆加快初始化速度。如果项目有依赖这一步可以顺带触发依赖安装。第四步环境准备。根据项目类型自动检测并准备运行环境。Node 项目检测 package.jsonPython 项目检测 requirements.txt 或 pyproject.toml。环境准备可以异步进行界面显示进度不阻塞用户操作。第五步启动会话。环境就绪后创建第一个 AI 会话把项目结构、关键文件内容作为初始上下文喂给引擎。这一步的上下文构造很关键不能把所有文件都塞进去要有选择地挑入口文件、配置文件、README控制在引擎的上下文窗口内。整个流程走下来理想情况三五分钟能完成。慢的地方通常在依赖安装和仓库克隆这两步要做好进度反馈避免用户以为卡死了。3.2 会话管理多会话并行与上下文隔离多会话并行是这个工作区相对终端方案的一大优势。你可以同时开三个会话一个在改前端组件一个在调后端接口一个在写测试。三个会话各自有独立的上下文互不干扰。实现上每个会话是一个独立的状态容器包含自己的对话历史、文件访问记录、运行时进程。会话之间通过工作区共享文件系统但对话上下文严格隔离。这样设计的原因是如果把多个任务的上下文混在一起AI 很容易串味改前端的时候突然去动后端代码。会话隔离的具体做法是给每个会话维护一个上下文窗口管理器。管理器负责决定哪些文件内容、哪些历史消息进入当前请求的上下文。当会话涉及的文件变化时管理器更新上下文当上下文接近窗口上限时管理器按重要性淘汰旧内容。这个淘汰策略直接影响 AI 的表现常见做法是保留最近的消息、保留被频繁引用的文件、淘汰一次性的工具调用输出。会话之间如果需要共享信息通过工作区级的共享笔记或者显式的引用其他会话功能来实现而不是隐式共享上下文。这样既保持了隔离又保留了协作的可能。3.3 文件操作与 diff 可视化让 AI 改动可审阅AI 编码最让人不放心的地方就是它到底改了什么。终端方案里改动直接落盘你只能事后 git diff。Web 工作区可以做得更好改动实时可视化审阅后再决定是否接受。实现上AI 的每次文件修改都先走一个变更暂存层。暂存层记录修改前后的内容生成 diff推送到前端展示。前端用类似 Monaco Editor 的 diff 视图渲染左边原文右边新文改动高亮。用户可以选择接受、拒绝、或者部分接受。这个机制的价值在于把 AI 从直接改文件变成提议改动。对于关键文件这个审阅步骤能避免很多低级错误。当然如果用户信任 AI也可以开启自动接受模式改动直接落盘diff 只作为记录。diff 可视化还有个隐藏好处它是很好的学习材料。看 AI 怎么改代码本身就是一种提升。很多用户反馈用久了之后自己写代码的思路都受 AI 影响变得更规范。3.4 终端与进程管理Web 里的完整开发环境一个完整的编码工作区不能只有 AI 对话还得有终端。跑测试、装依赖、起服务这些操作离不开命令行。Web 工作区里的终端通过 node-pty 在服务端创建伪终端前端通过 WebSocket 双向传输输入输出体验跟本地终端基本一致。进程管理上要区分前台进程和后台进程。前台进程占用终端比如你正在跑的交互式命令后台进程不占终端比如 dev server。后台进程要有独立的管理面板显示运行状态、资源占用、日志输出支持重启和停止。这里有个实操要点长任务的输出要限流。有些命令会疯狂输出日志如果全量推送到前端浏览器会卡死。做法是在服务端做输出缓冲按时间窗口批量推送或者只推送增量。同时保留完整日志在服务端需要时再拉取。进程的持久化也要考虑。服务重启后之前跑的后台进程会丢失。方案是记录进程的启动命令和工作目录重启后提供恢复进程的选项让用户决定是否重新拉起。对于 dev server 这类幂等的进程可以配置为自动恢复。4. 常见问题与排查技巧实录4.1 引擎连接类问题认证失败与超时的排查实际使用中引擎连接问题占了故障的大头。最常见的几类我整理成表方便对照排查。问题现象可能原因排查方向解决方式认证失败提示凭证无效token 过期或配置错误检查服务端配置库中的凭证重新配置凭证确认格式正确连接超时请求无响应网络问题或服务端未启动检查服务端进程和网络连通性重启服务确认端口监听正常会话创建成功但无输出引擎进程启动失败查看服务端引擎进程日志检查引擎依赖是否安装完整输出中断会话卡住上下文超限或进程崩溃查看会话日志和进程状态清理上下文重启会话排查这类问题的通用思路是分层定位先确认服务端活着再确认引擎进程活着再确认认证有效最后确认网络通。一层层排除比盲目重启有效得多。有个容易忽略的点凭证的存储和读取。如果服务端用了加密存储加密密钥的管理要小心。密钥丢了所有凭证都解不开只能重新配置。建议密钥单独备份或者用系统级的密钥管理服务。4.2 会话状态异常上下文丢失与恢复失败会话状态异常通常表现为打开工作区发现对话历史没了或者文件状态跟预期不符。这类问题的根因往往在持久化层。上下文丢失最常见的原因是存储写入失败但没报错。SQLite 在磁盘满或者权限问题时写入可能静默失败。排查时要检查存储文件的权限和磁盘空间同时给写入操作加上错误处理和重试。恢复失败则可能是快照不完整。如果会话恢复依赖文件快照而快照生成时文件正在被修改快照就会不一致。解决方式是生成快照时加文件锁或者用文件系统的快照能力如 ZFS、Btrfs 的快照保证一致性。还有个隐蔽的问题会话 ID 冲突。如果会话 ID 生成算法不够随机多实例部署时可能撞 ID导致会话串台。用 UUID v4 这类高熵方案能避免。4.3 性能问题大项目下的响应优化项目一大工作区就容易卡。卡的地方主要有三处文件树加载、diff 渲染、上下文构造。文件树加载慢是因为一次性读取了所有文件。优化方式是懒加载只加载展开的目录配合文件监听做增量更新。对于 node_modules 这类目录默认折叠并排除监听。diff 渲染卡是因为改动文件太大。优化方式是虚拟滚动只渲染可视区域的 diff 行对于超大文件只显示改动附近的上下文而不是全文 diff。上下文构造慢是因为要扫描大量文件。优化方式是建立文件索引记录每个文件的摘要和最近访问时间构造上下文时直接查索引不用实时扫描。索引在文件变化时增量更新。实测下来一个中等规模的项目几千个文件优化后工作区首屏加载能控制在两秒内diff 渲染基本无感上下文构造在几百毫秒级别。这个性能水平日常使用完全够。4.4 独家避坑经验那些文档里不会写的事踩过的坑里有几个特别值得说。第一别在服务端跑不可信代码。AI 生成的代码可能包含危险操作如果工作区直接执行风险很大。建议对执行环境做隔离用容器或者沙箱限制文件系统和网络访问。至少要把工作区目录和系统目录隔离开。第二WebSocket 要有心跳和重连。浏览器和服务的长连接很容易因为网络切换、休眠而断。没有心跳机制的话断了都不知道。加上心跳和自动重连断线恢复体验会好很多。第三日志要分级且可轮转。工作区跑久了日志会撑爆磁盘。按级别分文件配置轮转策略保留最近若干天的日志。排查问题时再调高日志级别。第四配置要有版本。工作区配置格式会随版本演进老配置在新版本可能不兼容。给配置加版本号升级时做迁移避免用户升级后配置全丢。第五给用户留逃生通道。Web 工作区再方便也要保证用户能随时把项目导出、把会话记录下载。别把用户数据锁死在系统里这是基本的信任基础。5. 部署与扩展的实操建议5.1 单机部署最快跑起来的方案想快速体验单机部署是最省事的。一台有 Node 环境的机器克隆代码装依赖配置引擎凭证启动服务浏览器访问就行。关键配置项有几个监听端口、工作区根目录、存储路径、引擎凭证。这些通过环境变量或者配置文件注入。建议用.env文件管理别硬编码在代码里。单机部署的注意点是资源限制。AI 编码任务吃内存和 CPU如果机器配置一般要限制并发会话数避免把机器跑挂。同时给工作区目录留足磁盘空间AI 生成的文件和日志增长很快。启动方式上开发用npm run dev生产用 pm2 或者 systemd 做进程守护保证服务崩溃后自动拉起。5.2 多用户场景隔离与配额如果要给团队用多用户隔离是必须的。每个用户有独立的工作区目录、独立的会话空间、独立的凭证配置。用户之间不能互相访问对方的工作区。隔离的实现靠用户 ID 做命名空间。工作区路径带上用户 ID存储查询带上用户 ID 过滤进程管理也按用户分组。凭证存储要加密且每个用户的凭证用独立的密钥或者至少独立的盐。配额管理上限制每个用户的并发会话数、磁盘用量、CPU 时间。超限时给出明确提示而不是默默失败。配额数据定期统计展示在用户面板上让用户心里有数。5.3 后续扩展方向还能怎么玩这个工作区的架构留了不少扩展空间。接入更多引擎。除了 Claude Code 和 Codex还可以接入其他 AI 编码工具。适配器模式让这件事变得简单写个新适配器就行。工作区模板。把常用项目类型做成模板新建工作区时选模板自动初始化项目结构和依赖。这对新手特别友好。会话分享。把一次完整的 AI 编码会话导出成可分享的链接别人打开能看到完整的对话和改动过程。这对团队知识沉淀很有价值。CI 集成。把工作区的 AI 编码能力接到 CI 流程里比如 PR 自动让 AI 做代码审查、自动修复 lint 问题。这是把 AI 编码从个人工具变成团队基础设施的关键一步。移动端优化。现在的界面主要面向桌面移动端体验还有提升空间。优化触控交互、简化界面让手机上也能顺畅用。这些扩展方向里我个人最看好会话分享和 CI 集成。前者解决知识传递后者解决规模化都是团队场景的刚需。6. 我个人的一些使用体会用这套工作区大半年最大的感受是AI 编码的瓶颈从来不是模型能力而是工作流。模型再强如果会话老是断、上下文老是丢、改动老是看不清实际效率也上不去。持久化 Web 工作区解决的正是工作流层面的问题它让 AI 编码从偶尔用用变成可以依赖。另一个体会是审阅机制比想象中重要。一开始我图快开了自动接受结果 AI 改错了几次关键文件回滚很麻烦。后来改成关键文件必须审阅虽然慢一点但整体反而更顺因为省去了返工。这个权衡每个团队要根据自己的情况定但我的建议是宁可慢一点也要保留审阅。最后分享一个小技巧给工作区配一个项目级的 AI 指令文件把项目的编码规范、目录约定、常用命令写进去每次会话初始化时自动加载。这样 AI 的输出会更贴合项目风格减少后期调整。这个文件我一般叫AI_GUIDE.md放在项目根目录效果立竿见影。