WebContainers 集成方案 — CmdCode UI Agent 浏览器内 Node.js 虚拟机

👤 用户

我记得当时生成ui.html网页的时候，我之前不是装了一个bash的虚拟机嘛，基于 WebContainers 提供浏览器内的 Node.js 虚拟环境，实现文件读写、命令执行。那你从各方面理解一下这个功能，还有WebContainers保留的可用之处吗？他还能干啥？因为服务器已经基本上把所有bash命令全部禁了。

🤖 Hermes Agent

背景

CmdCode ui.html 是一个纯前端 AI Agent 聊天界面，运行在 https://cmdcode.cn。其架构为：

前端：浏览器内 Agent 循环（DeepSeek V4 Flash + MiniMax M2.7）
工具：通过 PHP proxy 代理到 MiniMax/OpenCode API
bash：走 apiCall → PHP proxy → 服务器 exec() → 被禁用
文件操作：走 apiCall → PHP proxy → 服务器 PHP 文件函数 → 可用

服务器（XinCache 虚拟主机）禁用了 exec/shell_exec/system/popen/proc_open/passthru，以及所有 PHP 命令执行函数。Agent 的 bash 工具在提示词中明确标记为「不可用」。

WebContainers 是什么

由 StackBlitz 开发的基于 WebAssembly 的浏览器内 Node.js 运行时。将 Node.js 核心编译为 Wasm，在浏览器沙箱中运行，不需要任何服务器端执行能力。

技术栈

层级	技术	说明
Runtime	Wasm 编译的 Node.js	真正 Node.js 在浏览器里执行
文件系统	OPFS (Origin Private FS)	每个源独立持久化沙箱
进程管理	Web Worker	独立 stdout/stderr 隔离
网络	Service Worker	拦截 fetch，支持 HTTP 服务器
包管理	npm registry fetch	浏览器直连 npm，不走服务器

集成后架构对比

当前架构：

用户输入 → Agent循环(浏览器) → 工具调用
├─ bash → apiCall → PHP代理 → exec() ❌ 被禁
├─ read → apiCall → PHP代理 → PHP readfile ✅
├─ write → apiCall → PHP代理 → PHP file_put ✅
├─ edit → apiCall → PHP代理 → PHP patch ✅
└─ 其他工具 → proxyRequest → MiniMax/OpenCode API ✅

集成后架构：

用户输入 → Agent循环(浏览器) → 工具调用
├─ bash → WebContainer.spawn → ✅ 浏览器内 npm/node/npx
├─ read → wc://path → OPFS | apiCall → PHP ✅ (双模式)
├─ write → wc://path → OPFS | apiCall → PHP ✅ (双模式)
├─ edit → wc://path → OPFS | apiCall → PHP ✅ (双模式)
├─ [新增] xterm终端 → WebContainer 直接交互
└─ 其他工具 → proxyRequest → MiniMax/OpenCode API ✅

WebContainers 可用命令清单

命令	状态	说明
npm install	✅	安装任何 npm 包
npm run build	✅	跑构建
node script.js	✅	执行 JS/TS 脚本
npx eslint/prettier	✅	工具链
npx vitest/jest	✅	跑测试
npx tsx/ts-node	✅	跑 TypeScript
npx prisma	✅	数据库工具
npx serve	✅	启动预览服务器
git clone (HTTP)	✅	克隆仓库
npm init	✅	初始化项目
node -e "..."	✅	快速验证

curl / wget	❌	用 node fetch 替代
ping / traceroute	❌	浏览器限制无法绕过
apt / yum / dnf	❌	无 root 权限
systemctl	❌	无 systemd
docker / podman	❌	无法运行容器

👤 用户

需要你把 WebContainers 集成到 ui.html 的方案展开。

🤖 Hermes Agent

六阶段集成方案

阶段 1：CDN 引入 + WebContainer 初始化

改动量：~50 行 JS

在 <head> 添加 Import Map：

<script type="importmap">
{
  "imports": {
    "@webcontainer/api": "https://esm.sh/@webcontainer/api@1"
  }
}
</script>

JS 初始化函数：bootWebContainer() 在页面加载完后台异步启动，不阻塞主流程。包含 wcExecCommand()、wcReadFile()、wcWriteFile()、wcListDir() 四个封装函数。

阶段 2：改造 bash 工具

改动量：~30 行变更

将 bash 工具 handler 从

async bash(args,ctx){
  const res=await apiCall('bash',{command:args.command,...});
  ...
}

改为调用 wcExecCommand()，返回 stdout/stderr/exitCode。如果 WebContainer 未就绪，返回降级提示。

阶段 3：文件工具双模式

改动量：~50 行

约定路径前缀 wc:// 表示 WebContainer OPFS 文件系统，其余路径走原 PHP 后端。在 read/write/edit 三个工具 handler 最前面加前缀判断：

if (args.file_path.startsWith('wc://')) {
  // 走 WebContainer OPFS
} else {
  // 走原来 PHP 后端路径
}

阶段 4：更新系统提示词

改动量：~5 行

将 注意：bash 工具在虚拟主机上不可用（php 执行函数被禁用），请勿尝试使用。 更新为 bash 工具在浏览器内 WebContainer 中可用（支持 npm、node、npx、git 等常见命令）。读写文件时使用 wc:// 前缀可操作浏览器内项目文件，否则操作服务器文件。

阶段 5：xterm.js 终端面板（可选）

改动量：~200 行

添加 xterm.js 终端 UI，连接到 WebContainer 的 shell 进程，用户可手动输入命令。包含 terminalToggle 按钮和 terminalContainer 面板。

阶段 6：文件管理器扩展（可选）

改动量：~50 行

在文件管理器增加「WebContainer 项目文件」Tab，渲染 wcListDir() 结果，支持 OPFS 内的文件创建/删除/编辑。

三种实施路线对比

方案	代码量	难度	效果
A. 最小化	~130 行	⭐⭐	bash可用 + 文件双模式
B. 标准	~330 行	⭐⭐⭐	包含交互式终端面板
C. 完整	~380 行	⭐⭐⭐	包含 WebContainer 文件管理器 Tab

风险和注意事项

风险	影响	缓解
某些浏览器不支持 SharedArrayBuffer	WebContainer 无法启动	try-catch 降级，bash 提示「不支持」
esm.sh CDN 被墙	国内访问慢	备选 cdn.jsdelivr.net 或 unpkg.com
WebContainer 非全部 bash 命令	curl/wget 不可用	提示词注明支持范围
OPFS 数据随浏览器清理	项目文件丢失	新增「同步到服务器」按钮
首次加载 2-6 秒	启动延迟	页面加载后后台启动，不阻塞

👤 用户

[引用上方可用命令清单 + 方案A建议] … 执行技能文档推送

🤖 Hermes Agent（结论）

推荐方案：方案 A（最小化）

理由：

代码增量仅 ~130 行，ui.html 从 1339 行变为 ~1470 行，改动可控
bash 工具从「不可用」变为「可用」——这是质变
xterm 终端面板对聊天式 agent 交互增益不大——用户习惯打字让 agent 干
不影响现有 PHP 后端功能——所有媒体生成、用户认证、服务器文件管理照旧
完美降级——WebContainer 启动失败时，bash 提示「不支持」，其他功能完全不变

WebContainers 的定位总结

WebContainers 不是替代 PHP 后端，而是填补服务器被阉割的短板。两者是互补关系。

PHP 后端：MiniMax API 代理、用户认证、数据库、媒体文件存储、全局持久化
WebContainers：npm install、node 脚本、构建工具、代码测试、dev server 预览

两者协作，才能让 Agent 真正「能做又能说」。