企业官网建设流程全解析

1. 为什么需要一个持久化的 Web AI 编码工作区

如果你最近半年一直在用 Claude Code 或者 Codex 这类 AI 编码工具，大概率会遇到一个很烦人的问题：每次关掉终端、重启电脑、或者切换项目目录，之前跟 AI 聊出来的上下文就全没了。尤其是做那种跨天、跨模块的中大型项目，你不得不反复把项目背景、技术栈、目录结构、编码规范重新喂一遍，光这一套“开场白”就得花十几分钟。更别提有时候你在公司电脑上跑了一半的任务，回家想接着弄，结果发现会话状态根本带不走。

Easy Web Vibecoding 这个项目，本质上就是冲着这个痛点来的。它做的事情说起来很简单：给 Claude Code 和 Codex 这类命令行 AI 编码工具，套一层持久化的 Web 工作区。你可以把它理解成一个“带记忆的浏览器控制台”，所有跟 AI 的对话、代码片段、文件变更记录、任务进度，全部存在服务端，换设备、换浏览器、甚至换网络环境，打开网页就能接着干。它解决的不是“AI 能不能写代码”的问题，而是“AI 写代码的过程能不能被管理、被追溯、被复用”的问题。

这个内容适合谁看？三类人最值得花时间研究。第一类是重度依赖 Claude Code 或 Codex 做日常开发的工程师，尤其是手里同时维护多个项目、经常需要在不同机器之间切换的人。第二类是小团队的技术负责人，想让团队共享一套 AI 编码的上下文和规范，而不是每个人各自为战。第三类是对 Web AI 工作区这个方向感兴趣、想自己搭一套类似环境的技术爱好者。哪怕你只是刚装好 Claude Code，还没搞明白怎么让它记住项目结构，这套思路也能帮你少走很多弯路。

我自己的使用场景比较典型：手头有三个长期项目，一个是用 Python 做数据处理，一个是 Node.js 的后端服务，还有一个是嵌入式相关的 C 代码调试。以前每次切换项目，都要重新跟 AI 解释“这个项目是干嘛的、用什么框架、有哪些约定”。用了持久化工作区之后，每个项目对应一个独立的 Web 会话空间，打开就是上次的进度，AI 甚至能记得上周讨论过的某个函数命名争议。这种体验上的差别，用过就回不去了。

2. 核心架构拆解：Web 工作区到底是怎么套在 CLI 工具外面的

2.1 整体分层设计思路

Easy Web Vibecoding 的架构并不复杂，但每一层的职责划分得很清楚。最底层是 Claude Code 或 Codex 的 CLI 进程，它们负责实际的代码生成、文件读写、命令执行。中间层是一个常驻的服务端进程，负责管理会话状态、持久化存储、以及跟 CLI 进程通信。最上层是浏览器里的 Web 界面，提供对话窗口、文件树、变更 diff、任务看板这些交互元素。

为什么要做成三层而不是直接让浏览器调 CLI？核心原因是 CLI 工具本身的设计假设是“单次会话、本地终端”。Claude Code 和 Codex 在启动时会加载当前目录的上下文，会话结束后进程退出，状态不保留。如果你直接在浏览器里模拟终端输入输出，会遇到两个问题：一是进程生命周期难以管理，二是多个浏览器标签页同时操作同一个项目会冲突。加一层服务端之后，CLI 进程可以由服务端统一拉起和回收，会话状态存在数据库里，Web 端只负责展示和发送指令，职责就清晰了。

另一个关键设计是“项目即工作区”的隔离模型。每个项目目录对应一个独立的工作区实例，拥有自己的会话历史、文件快照和配置。这样做的好处是，你在 A 项目里跟 AI 讨论的架构方案，不会污染 B 项目的上下文。我试过把两个项目混在一个会话里，结果 AI 经常把两个项目的函数名搞混，生成出来的代码张冠李戴。隔离之后这个问题彻底消失。

2.2 持久化层选型与数据模型

持久化这块，项目默认用的是 SQLite 加本地文件系统的组合。会话消息、任务状态、配置项存在 SQLite 里，文件快照和生成的代码产物存在项目目录下的.vibecoding隐藏文件夹中。为什么不用 Postgres 或者 MySQL？因为这套工具的目标用户大多是个人开发者或小团队，部署越简单越好。SQLite 零配置、单文件、备份方便，对于单机场景完全够用。如果你确实需要多人协作，可以把 SQLite 换成 Postgres，项目本身留了适配接口。

数据模型上，核心表大概有这么几张：workspaces记录项目路径和基本信息，sessions记录每个会话的元数据，messages存对话消息，snapshots存文件快照，tasks存任务进度。消息表里有一个context_window字段，用来标记这条消息属于哪个上下文窗口。这个设计很关键，因为 Claude Code 和 Codex 都有上下文长度限制，当对话太长时需要做摘要或者截断。有了这个字段，服务端可以精确控制哪些消息进入当前上下文，哪些被归档。

注意：SQLite 在高并发写入时会有锁竞争问题。如果你同时开多个浏览器标签页操作同一个工作区，建议把busy_timeout调到 5000ms 以上，否则偶尔会遇到database is locked的错误。这个坑我在早期版本里踩过，后来在配置里加了一行就解决了。

2.3 与 Claude Code / Codex 的通信机制

服务端跟 CLI 进程的通信，用的是标准输入输出加 JSON 消息协议。具体来说，服务端启动 CLI 进程时，会保持 stdin 和 stdout 的管道打开，然后按照约定的格式发送指令和接收结果。Claude Code 和 Codex 都支持非交互模式，可以通过参数传入 prompt 并输出结构化结果，这是整个方案能成立的前提。

这里有一个细节值得展开：CLI 进程的启动参数。以 Claude Code 为例，常用的参数包括--print用于非交互输出、--output-format json用于结构化结果、--max-turns控制最大轮次。Codex 那边类似，有--quiet和--json之类的选项。服务端会根据当前任务类型动态拼接这些参数。比如做代码生成时用 JSON 输出方便解析，做交互式调试时用流式输出方便实时展示。

通信协议的消息格式大概是这样的：每条消息有一个type字段，取值包括prompt、response、tool_call、error等。prompt是 Web 端发来的用户输入，response是 CLI 返回的文本结果，tool_call是 AI 请求执行某个工具（比如读文件、跑命令），error是异常信息。服务端收到tool_call后，可以选择自动执行或者转发给 Web 端让用户确认。这个确认机制很重要，否则 AI 可能在你不知情的情况下删掉重要文件。

3. 从零搭建：环境准备与核心配置实操

3.1 基础环境要求与依赖安装

先说硬件和系统要求。这套东西对机器性能要求不高，但有几个硬性条件。操作系统方面，macOS、Linux、Windows 的 WSL2 环境都可以，原生 Windows 支持在逐步完善中。Node.js 版本建议 18 以上，因为 Claude Code 和 Codex 的 npm 包都依赖较新的运行时特性。内存建议 8GB 起步，如果你要同时跑多个工作区，16GB 会更从容。

安装步骤我按实际操作的顺序列一下。第一步，确认 Node.js 和 npm 可用：

node -v npm -v

如果版本低于 18，建议用 nvm 或者 fnm 切换。第二步，全局安装 Claude Code 和 Codex 的 CLI 工具。Claude Code 的安装命令是npm install -g @anthropic-ai/claude-code，Codex 的安装命令根据你用的版本有所不同，常见的是npm install -g @openai/codex或者通过官方提供的安装脚本。安装完成后，用claude --version和codex --version验证。

第三步，克隆 Easy Web Vibecoding 的仓库并安装依赖：

git clone <项目仓库地址> cd easy-web-vibecoding npm install

第四步，配置环境变量。项目根目录下有一个.env.example文件，复制成.env后填入必要配置。核心配置项包括PORT（Web 服务端口，默认 3000）、DB_PATH（SQLite 文件路径）、WORKSPACE_ROOT（工作区根目录）、CLAUDE_BIN（Claude Code 可执行文件路径）、CODEX_BIN（Codex 可执行文件路径）。如果你用的是自定义安装路径，这里要写绝对路径。

提示：在 Windows 上，CLI 可执行文件路径通常带.cmd后缀，比如claude.cmd。如果启动时报“找不到命令”，先检查这个路径是否正确。我帮朋友排查过好几次，都是路径里少了后缀或者用了正斜杠。

3.2 工作区初始化与项目接入

环境装好之后，下一步是创建工作区。启动服务：

npm run start

浏览器打开http://localhost:3000，你会看到一个简洁的界面，左侧是工作区列表，右侧是主操作区。点击“新建工作区”，填入项目名称和项目目录的绝对路径。服务端会做几件事：检查目录是否存在、读取项目的基本信息（比如package.json或requirements.txt）、初始化 SQLite 记录、在项目目录下创建.vibecoding文件夹用于存放快照。

这里有一个实操心得：项目目录最好选在文件系统层级较浅的位置，比如/home/user/projects/myapp而不是/home/user/documents/work/2024/projects/myapp。原因是一些 CLI 工具在处理深层路径时，输出日志里的路径会很长，影响可读性。另外，如果项目目录里有大量node_modules或者虚拟环境文件夹，建议在配置里加排除规则，否则文件快照会变得很大。

工作区创建完成后，你可以配置这个工作区的默认 AI 工具（Claude Code 还是 Codex）、默认模型、以及系统提示词。系统提示词这块值得花点时间。我通常会把项目的技术栈、目录结构约定、代码风格要求写进去。比如“这是一个 Python 3.11 项目，使用 FastAPI 框架，所有接口函数必须有类型注解，数据库操作统一走 repository 层”。这样每次新会话开始时，AI 自动就带着这些背景知识，不用重复交代。

3.3 会话持久化与上下文管理配置

持久化的核心配置在config/session.json里。几个关键参数需要理解。max_context_messages控制进入当前上下文的最大消息数，默认 50。超过这个数量的旧消息会被归档，但不会删除，你随时可以在历史记录里翻看。summary_threshold控制何时触发自动摘要，默认是上下文占用达到 80% 时。snapshot_interval控制文件快照的频率，默认每 5 轮对话存一次。

为什么要有自动摘要？因为 Claude Code 和 Codex 的上下文窗口虽然大，但也不是无限的。当对话轮次很多时，如果不做处理，要么超出限制报错，要么响应变慢。自动摘要的做法是，把较早的对话内容压缩成一段简短的摘要，保留关键决策和结论，丢弃中间的试错过程。我实测下来，开启摘要后，一个持续三天的项目会话，上下文占用能控制在合理范围内，AI 对早期决策的记忆也没有明显丢失。

注意：自动摘要会调用一次额外的 AI 请求，这会消耗 token。如果你的 API 额度比较紧张，可以把summary_threshold调高到 90%，或者改成手动触发。另外，摘要质量跟模型能力有关，用较弱的模型做摘要可能会丢失重要细节。我一般建议摘要也用跟主对话相同的模型。

4. 日常使用中的核心操作与效率技巧

4.1 多项目并行时的会话切换策略

同时维护多个项目的人，最关心的就是切换效率。Easy Web Vibecoding 的 Web 界面支持多标签页，每个标签页可以绑定不同的工作区。我的习惯是，把当前正在活跃开发的项目放在第一个标签页，需要偶尔查看的项目放在后面。切换时直接点标签页，会话状态自动恢复，不需要重新加载。

但这里有个细节：如果你在 A 工作区让 AI 执行一个耗时较长的任务（比如重构整个模块），然后切到 B 工作区干活，A 的任务会在后台继续跑。服务端会记录任务状态，完成后在界面上给出通知。这个异步执行的能力很实用，相当于你有了一个可以并行工作的 AI 助手。不过要注意，同时跑太多任务会占用较多系统资源，建议控制在 2 到 3 个以内。

另一个技巧是“会话分叉”。有时候你在一个会话里讨论了两个不同的方案，想分别深入。可以在某个节点点击“从此处分叉”，服务端会复制当前上下文创建一个新会话，两个会话独立演进。这个功能在做技术选型对比时特别好用，你可以让 AI 在分叉 A 里实现方案一，在分叉 B 里实现方案二，最后对比结果。

4.2 文件变更追踪与回滚操作

AI 编码最让人不放心的就是它改了哪些文件、改了什么。Easy Web Vibecoding 的文件变更追踪功能，会在每次 AI 执行写操作后，生成一个 diff 视图。左侧是修改前的版本，右侧是修改后的版本，新增行绿色、删除行红色，跟 Git 的 diff 类似。你可以逐文件审查，确认无误后点击“接受”，有问题的点击“回滚”。

回滚的底层实现是基于快照的。前面提到snapshots表存了文件快照，每次 AI 写文件前，服务端会先存一份当前版本。回滚时直接把快照覆盖回去。这个机制比 Git 更轻量，不需要你手动 commit，但代价是快照会占用磁盘空间。我的经验是，对于代码文件，快照占用可以忽略不计；但如果项目里有大体积的二进制文件被 AI 碰到，快照会迅速膨胀。所以建议在配置里把二进制文件类型加入排除列表。

提示：回滚操作是不可逆的，回滚之后当前版本就没了。如果你不确定要不要回滚，可以先“另存为分支”，相当于把当前状态复制一份再回滚。这个操作在界面上是一个不起眼的按钮，但关键时刻能救命。我有一次差点把 AI 改好的一个模块回滚掉，幸好先存了分支。

4.3 团队共享工作区的配置要点

小团队用这套东西，核心诉求是共享上下文和规范。Easy Web Vibecoding 支持把工作区配置导出成 JSON 文件，其他人导入后就能获得相同的系统提示词、模型配置和排除规则。但要注意，会话历史默认是不共享的，每个人有自己的会话空间。如果你想让团队看到某个会话，可以把它标记为“公开”，公开后的会话所有工作区成员都能查看。

团队场景下还有一个实用功能是“规范注入”。你可以在工作区配置里定义一个conventions字段，里面写团队的编码规范，比如“所有 API 返回统一用{code, data, message}结构”、“日志必须包含 trace_id”。服务端在每次发送 prompt 时，会自动把这些规范拼接到系统提示词后面。这样即使团队成员忘了交代，AI 也会遵守规范。我帮一个五人团队配过这个，他们反馈说代码 review 时因为风格问题打回的次数明显减少了。

不过团队共享要注意权限控制。默认配置下，任何能访问 Web 界面的人都能操作所有工作区。如果你们的服务暴露在内网，建议加上简单的登录认证。项目本身留了 auth 中间件的扩展点，接一个 LDAP 或者 OAuth 都不难。实在不想折腾，至少把服务绑定到127.0.0.1而不是0.0.0.0，避免被同网络的其他机器访问。

5. 常见故障排查与避坑经验实录

5.1 CLI 进程启动失败类问题

最常见的问题就是服务端拉不起 Claude Code 或 Codex 进程。表现是 Web 界面发送消息后一直转圈，日志里报spawn ENOENT或者command not found。排查思路分三步。第一步，确认 CLI 在终端里能直接运行。打开一个普通终端，输入claude --version，如果能输出版本号，说明安装没问题。第二步，检查.env里的CLAUDE_BIN路径。这里有个坑：如果你用 nvm 管理 Node.js，CLI 可执行文件在 nvm 的版本目录下，而不是/usr/local/bin。用which claude命令可以查到真实路径。第三步，检查服务端进程的运行用户是否有权限执行该文件。

还有一种情况是 CLI 能启动但立即退出。这通常是认证问题。Claude Code 和 Codex 都需要配置 API 密钥或者登录账号。如果你在终端里已经登录过，服务端进程一般能继承配置。但如果服务端是以系统服务方式运行的，可能读不到你的用户级配置。解决办法是在.env里显式传入 API 密钥，或者把服务端也配成用你的用户身份运行。

注意：有些 CLI 工具在非交互模式下对认证状态更敏感。我遇到过终端里能用、服务端拉起来就报认证失败的情况，最后发现是环境变量HOME不一致导致的。服务端进程的HOME指向了/root而不是我的用户目录，自然读不到配置。在启动脚本里显式设置HOME就解决了。

5.2 上下文丢失与摘要异常处理

上下文丢失的表现是，AI 突然“失忆”，不记得之前讨论过的内容。先检查messages表里消息是否还在。如果消息在但 AI 不记得，大概率是上下文窗口管理出了问题。查看context_window字段，确认当前活跃窗口包含了哪些消息。有时候是因为摘要触发得太频繁，把重要信息压缩掉了。可以临时把summary_threshold调到 95% 观察一下。

摘要异常还有一种表现是摘要内容质量很差，比如把关键的函数名摘要没了。这通常是因为摘要用的模型跟主对话模型不一致，或者摘要 prompt 设计得不好。项目默认的摘要 prompt 是英文的，如果你主要用中文交流，建议改成中文 prompt，摘要质量会好很多。我实测过，中文项目用中文摘要，关键信息保留率明显更高。

如果上下文实在乱了，还有一个“重置上下文”的选项。它会保留文件快照和任务记录，但清空对话历史，相当于让 AI 重新开始，但项目状态还在。这个操作要谨慎，因为清空后 AI 就不知道你之前的设计决策了。我一般只在上下文彻底混乱、修复成本高于重建时才用。

5.3 文件快照膨胀与磁盘清理

用了一段时间后，.vibecoding文件夹可能会变得很大。先看看是哪些文件占的空间。常见元凶是node_modules、.git、虚拟环境目录、以及构建产物目录。这些目录本来就不该被 AI 修改，应该加入排除列表。配置项是exclude_patterns，支持 glob 语法。比如：

{ "exclude_patterns": [ "**/node_modules/**", "**/.git/**", "**/venv/**", "**/__pycache__/**", "**/dist/**", "**/*.log" ] }

加了排除之后，新产生的快照就不会包含这些目录。但已有的快照不会自动清理，需要手动跑一次清理命令：

npm run cleanup -- --workspace <工作区名称> --keep-days 7

这个命令会删除 7 天前的快照，保留最近的。我一般设成保留 14 天，既能回溯最近两周的变更，又不会占太多空间。对于个人项目，快照文件夹控制在几百 MB 以内是合理的；如果超过 1GB，就该检查排除规则了。

5.4 常见问题速查表

这张表里的每一条，都是我在实际使用中真实遇到过的。尤其是最后一条，回滚前存分支这个习惯，帮我避免过至少两次重大损失。AI 改代码有时候会改出意想不到的效果，你觉得它改坏了，回滚之后才发现原来那个版本里有个小改动其实是对的。有分支备份的话，还能找回来。

6. 进阶玩法：把工作区接入本地模型与自定义工具链

6.1 接入本地模型的配置方法

有些场景下你可能不想用云端 API，比如处理敏感代码、或者想省 token 费用。Easy Web Vibecoding 支持把 Claude Code 或 Codex 的后端指向本地模型服务。以 Claude Code 为例，它支持通过环境变量指定 API 端点。你可以在本地跑一个兼容 OpenAI 接口的模型服务，然后把ANTHROPIC_BASE_URL或者对应的配置指向本地地址。

具体配置在.env里加几行：

CLAUDE_BASE_URL=http://localhost:1234/v1 CLAUDE_API_KEY=local-model CLAUDE_MODEL=your-local-model-name

Codex 那边类似，有OPENAI_BASE_URL和OPENAI_API_KEY的对应配置。本地模型的选择上，代码能力比较强的开源模型都可以试试。不过要有心理准备，本地模型在复杂任务上的表现跟云端大模型还是有差距，适合做简单的代码补全、注释生成、格式转换这类任务。复杂重构和架构设计，还是建议用云端模型。

提示：本地模型服务的并发能力通常有限。如果你在 Web 工作区里同时跑多个任务，本地模型可能会排队甚至超时。建议把工作区的并发任务数限制为 1，或者给本地模型服务配一个请求队列。

6.2 自定义工具链与脚本扩展

Easy Web Vibecoding 留了一个工具扩展机制，允许你注册自定义的 CLI 命令，让 AI 可以调用。比如你可以注册一个run-tests工具，AI 写完代码后自动跑测试；注册一个lint-fix工具，自动格式化代码。工具定义放在tools/目录下，每个工具一个 JSON 文件，描述工具名称、参数、执行命令。

举个例子，一个跑测试的工具定义：

{ "name": "run_tests", "description": "运行项目测试套件", "command": "npm test", "args": ["--silent"], "timeout": 120000 }

注册之后，AI 在需要验证代码时会主动调用这个工具。服务端执行命令并把输出返回给 AI，AI 根据测试结果决定下一步。这个机制把 AI 从“只会写代码”扩展到了“能验证代码”，实用性提升很大。我配了一个跑 lint 的工具后，AI 生成的代码风格问题少了很多，因为它自己会先跑一遍 lint 再交给我。

6.3 工作区数据的备份与迁移

最后说一个容易被忽视但很重要的事：备份。你的会话历史、任务记录、快照都在本地，万一磁盘坏了或者误删了，损失不小。最简单的备份方式是定期打包.vibecoding文件夹和 SQLite 数据库文件。项目提供了一个导出命令：

npm run export -- --workspace <名称> --output backup.zip

导出的 zip 包含该工作区的全部数据。恢复时用npm run import导入即可。我一般每周导一次，存到外部硬盘或者同步盘里。如果你用 Git 管理项目，也可以把.vibecoding加入.gitignore，然后单独用一个私有仓库存备份，这样既不影响主仓库，又能享受版本管理的好处。

迁移到新机器时，除了导入数据，还要注意 CLI 工具的版本一致性。不同版本的 Claude Code 或 Codex，输出格式可能有细微差别。如果迁移后出现解析错误，先检查两边 CLI 版本是否一致。我遇到过从旧版本迁移到新版本后，JSON 输出字段名变了导致解析失败的情况，升级一下服务端的解析逻辑就好了。

这套东西我用了大概三个月，最大的感受是它把 AI 编码从“一次性对话”变成了“可持续的工程实践”。以前跟 AI 协作像是在打零工，每次都要重新交代背景；现在更像是在带一个记得住事的助手，项目越做越顺。如果你也在用 Claude Code 或 Codex，强烈建议花一个下午把工作区搭起来，后面省下的时间绝对值得。