跳转到主要内容

​
概述

编程模式（Coding Mode）是一种专门的 Agent 模式，支持在浏览器中进行 AI 驱动的 Web 应用开发。当用户在首页选择 网页（Website） 分类时，Zeus 进入编程模式 — AI 在远程沙盒中编写代码，修改通过 iframe 实时预览面板即时呈现。 该模式由可配置的沙盒 Provider（E2B / OpenSandbox / Daytona） 驱动，预装了 Next.js 15 + Tailwind CSS + shadcn/ui 技术栈。

​
架构

​
核心组件

组件路径作用
沙盒模板ai-backend/sandbox-templates/e2b/nextjs/ 或 sandbox-templates/opensandbox/预构建的沙盒镜像，包含 Next.js + 依赖
Coding 沙盒工具ai-backend/src/utils/tools/built_in/coding_sandbox.py沙盒中的文件操作和命令执行
编程模式提示词ai-backend/src/repository/prompts/modes/coding_mode.md编程行为的系统提示词
CodingPreviewweb/src/components/agent/coding-preview/基于 iframe 的实时预览组件
codingStoreweb/src/store/codingStore.ts管理预览 URL 和沙盒状态的 Zustand Store

​
沙盒模板

为了避免每次会话都运行 npm install 导致启动缓慢，Zeus 使用预构建的沙盒模板，包含：
  • Node.js 22
  • pnpm（全局安装）
  • Next.js 15（App Router、TypeScript、Tailwind CSS、ESLint、src 目录）
  • shadcn/ui（预装常用组件）
  • 额外依赖：lucide-react、framer-motion、clsx、tailwind-merge
  • 代码智能工具：typescript、typescript-language-server、pyright、@biomejs/biome（全局预装，用于 LSP 诊断和 CLI linting）
  • 启动命令：npx next dev --turbo（等待端口 3000 就绪）

​
E2B 模板

cd apps/ai-backend/sandbox-templates/e2b
bun install
# 生产模板
bun run build:nextjs
# 开发模板（较少资源）
bun run build:nextjs:dev
构建完成后，新沙盒启动约 3-5 秒，所有依赖已预装。

​
OpenSandbox 镜像

cd apps/ai-backend/sandbox-templates/opensandbox/zeus-base
docker build -t zeus-base:latest .

​
模板文件（E2B）

文件用途
template.tsE2B 模板定义（基础镜像、安装步骤、启动命令）
build.ts生产环境构建脚本
build.dev.ts开发环境构建脚本
files/page.tsx默认落地页脚手架
files/layout.tsx根布局（Inter 字体）
files/globals.css全局样式（含 shadcn CSS 变量）

​
编程沙盒工具

编程模式下，Agent 拥有一组专用工具，操作沙盒文件系统：
工具描述
coding_write_file在项目中创建或覆盖文件。支持 upsert — Next.js HMR 自动刷新预览。
coding_read_file读取项目中的文件内容。
coding_grep使用正则表达式搜索文件内容（类似 grep/ripgrep）。自动排除 node_modules、.next、.git。
coding_exec_sh在项目目录中执行 Shell 命令（如 pnpm add dayjs）。
coding_list_files列出项目目录结构（排除 node_modules、.next、.git）。
这些工具与标准的 sandbox_* 工具（面向 Python）是分开的。编程工具始终操作沙盒容器中的 /home/user/project/ 目录。

​
代码智能 (LSP)

在 Agent 模式下，Zeus 提供 lsp 工具用于代码智能分析，支持：
操作说明
diagnostics获取文件的类型错误和警告（类似 tsc --noEmit）
definition跳转到符号定义位置
references查找符号的所有引用
hover获取符号的类型信息和文档
document_symbols列出文件中的所有符号
workspace_symbols在项目中搜索符号
支持的语言服务器：TypeScript (typescript-language-server)、Python (pyright)、Go (gopls)、Rust (rust-analyzer)。 此外，write 和 edit 工具在保存文件后会自动运行 CLI linter（tsc、pyright、biome、eslint），将诊断结果附加到工具输出中。

​
模式流程

​
入口

  1. 用户在首页选择 网页（Website） 分类
  2. HomeChatInput 在 sessionStorage 中存储 zeus_pending_mode = 'coding'
  3. 用户提交查询，创建项目和会话
  4. 导航到聊天页面

​
聊天页面初始化

  1. 聊天页面从 sessionStorage 读取 zeus_pending_mode
  2. 设置 chatStore.settings.mode = 'coding'
  3. 清除 sessionStorage 中的 key
  4. 右侧面板渲染 CodingPreview 而非 Workspace

​
后端流程

  1. Agent 服务检测到 mode == 'coding'
  2. 通过 init_coding_sandbox() 初始化编程沙盒（使用 zeus-nextjs 模板）
  3. 从沙盒获取预览 URL（sandbox.get_host(3000)）
  4. 发送 coding_ready SSE 事件，包含 preview_url 和 sandbox_id
  5. 将 CODING_SANDBOX_TOOLS 注入 Agent 工具列表
  6. 加载 coding_mode.md 系统提示词
  7. Agent 开始使用编程工具处理用户请求

​
前端 SSE 处理

  1. stream-processor.ts 接收 coding_ready 事件
  2. 更新 codingStore 中的预览 URL 和沙盒 ID
  3. CodingPreview 组件渲染包含预览 URL 的 iframe
  4. 后续文件写入触发 Next.js HMR — iframe 自动刷新

​
预览面板

CodingPreview 组件提供：
  • iframe 展示 运行中的 Next.js 开发服务器
  • 实时指示器 显示开发服务器状态（绿色圆点）
  • 刷新按钮 手动重新加载预览
  • 新标签页打开 按钮，支持全屏查看
  • 加载状态 沙盒初始化期间显示
  • 折叠状态 面板最小化时显示
预览依赖 Next.js 的热模块替换（HMR）— 当 AI 向沙盒写入文件时，开发服务器检测到变化并自动将更新推送到 iframe。

​
会话隔离

Zeus 确保工作区状态（沙盒文件、网站预览、工具执行、待办事项、Agent 轨迹）按聊天会话完全隔离。在会话之间切换时，不会将一个会话的数据泄露到另一个会话中。

​
机制

工作区状态由 trajectoryStore 管理，它维护一个以 session ID 为键的 SessionWorkspaceSnapshot 内存缓存：
  • 保存 / 恢复：当用户从会话 A 导航到会话 B 时，会话 A 的完整工作区状态会被保存到 _sessionCache。如果会话 B 有缓存快照，则立即恢复；否则初始化一个干净的工作区。
  • SSE 会话守卫：切换会话时不会中断后端的 SSE 事件流（以允许后端 Agent 继续在后台执行）。stream-processor.ts 中的守卫会检查每个传入事件的 session ID 是否与 _currentSessionId 匹配。属于后台会话的事件仍然会被消费并通过 RealtimeEventSaver 保存到数据库，但所有 store 更新（UI 状态变化）会被跳过。
  • 状态恢复：当用户返回之前的会话时，缓存快照提供即时的工作区恢复。此外，loadEventsFromDb 会从持久化事件中重建完整状态，包括 Agent 在后台完成的所有工作。

​
后台 Agent 执行

当用户从 Agent 正在执行的会话切走时：
  1. SSE 流继续消费事件（后端的 StreamingResponse 生成器不会被中断）。
  2. 后端沙盒保持存活 — sandbox_manager.set_session() 调用 _detach_unlocked()，仅清除内存中的 provider 引用而不销毁容器。
  3. 无论会话是否在前台，RealtimeEventSaver 都会将事件持久化到数据库。
  4. 当用户返回时，可以通过 Redis 中存储的 sandbox_id 重新连接沙盒。

​
沙盒 ID

sandboxId 是会话级工作区快照的一部分。每个会话维护自己的沙盒标识，切换会话时会自动保存和恢复正确的 sandboxId。

​
工具注入与模式过滤

编程模式拥有独立的工具集，替换标准沙盒工具：
工具类别Agent 模式Ask 模式Plan 模式Coding 模式
Filesystem（读写）全部只读只读禁用
TodoList全部全部全部全部
Memory读写禁用只读读写
RAG全部只读全部全部
Sandbox（Python）全部禁用禁用禁用
LSP（代码智能）全部禁用禁用禁用
Coding Sandbox禁用禁用禁用全部
Web Search全部全部全部全部
MCP/OAuth全部只读只读全部
Browser/Desktop全部禁用禁用禁用

​
配置

​
环境变量

变量描述默认值
SANDBOX_PROVIDER沙盒 Provider 类型e2b
SANDBOX_TIMEOUT沙盒超时时间（秒）3600
E2B_API_KEYE2B API 密钥（E2B Provider 必需）—
E2B_SANDBOX_TEMPLATEE2B 模板名称zeus-nextjs
OPENSANDBOX_API_URLOpenSandbox Server 地址（OpenSandbox Provider 必需）http://localhost:8880
OPENSANDBOX_IMAGEOpenSandbox 沙盒镜像zeus-base:latest

​
依赖

Python（ai-backend）：
  • e2b — E2B 云端沙盒 Provider
  • opensandbox-sdk — Alibaba OpenSandbox 自托管沙盒 Provider（可选）
Node.js（sandbox-templates/e2b）：
  • e2b — 用于构建 E2B 自定义模板
  • dotenv — 环境变量加载

​
部署

在编程模式中构建项目后，Zeus 支持通过 Deploy API 将项目部署到生产环境。提供三种部署目标：

​
Vercel

通过 Vercel REST API 将沙盒项目部署到 Vercel。
字段类型说明
sandbox_idstring活跃的 E2B 沙盒 ID
vercel_tokenstring你的 Vercel API Token
project_namestring（可选）Vercel 项目名称（默认 zeus-<sandbox_id>）
POST /api/deploy/vercel
流程：连接到沙盒 → 下载源码文件（排除 node_modules、.next、.git）→ 上传到 Vercel API → 返回部署 URL。

​
服务器（SSH）

通过 SSH + rsync 部署到自有服务器，然后运行 Docker 部署脚本。
字段类型说明
sandbox_idstring活跃的 E2B 沙盒 ID
server_hoststring服务器主机名或 IP
server_portintSSH 端口（默认 22）
server_userstringSSH 用户名
server_passwordstringSSH 密码
server_pathstring服务器上的部署路径
web_portint网站访问端口（默认 4000）
POST /api/deploy/server
流程：从沙盒下载源码 → rsync 到服务器 → 执行 deploy/script/deploy-saas.sh 完成容器化部署。

​
Freestyle

使用 Freestyle API 部署，提供持久化预览 URL（*.style.dev）。
字段类型说明
sandbox_idstring活跃的 E2B 沙盒 ID
session_idstring会话 ID（用于一致的域名映射）
custom_domainstring（可选）自定义域名
POST /api/deploy/freestyle
同一会话的多次部署会更新同一个域名。Freestyle 自动检测框架并处理构建和托管。

​
部署环境变量

变量说明默认值
FREESTYLE_API_KEYFreestyle API 密钥（Freestyle 部署必需）—