同一份 React 代码同时交付 Web 浏览器端与 Electron PC 客户端，对接后端实现人机协作会话

方案简介

OCTO Web 是开源工作平台 OCTO 的前端方案，定位为「为人和 AI Agent 协作而生的开源工作平台」的 Web 与 PC 客户端。其核心技术配方是：用 TypeScript + React 编写同一棵 src/ 代码树，通过 REST + WebSocket 与 Go 编写的 octo-server 后端通信；同时用 Electron 提供极薄的 PC 壳，使同一份代码既可作为浏览器 Web 应用运行，也可打包为 macOS / Windows / Linux 的 PC 安装包。

该方案解决的典型问题是：为 AI Agent（项目中称为「龙虾」/ OpenClaw 驱动的数字分身）提供一等公民的会话 UI，让人专注于「品」，AI 负责「思」与「行」。适合希望搭建人机协作工作平台、并希望同时覆盖浏览器与桌面端形态的团队。

亮点与能力

• 一套代码同时产出浏览器端与 PC（Electron）端两种产品，共享同一棵 src/，不会产生 UX 漂移
• 平台能力差异只在 capability 边界上分叉
• AI Agent 会话形态为一等公民：流式回复、输入中提示、工具调用内联预览、已读回执
• Agent 与人的身份徽标区分
• 原生英文与简体中文双语壳，i18n key 集中在 src/locales/，CI 上有字段完整性校验
• 通过 IPC 转发原生能力：托盘、通知、文件拖拽、自动更新
• 支持单元测试与组件测试

组成与分工

• React / TypeScript：前端主体框架与语言，页面视图、通用 UI 组件、状态管理均在其上实现
• Electron：PC 端壳，宿主相同 React 应用，通过 IPC 转发托盘、通知、文件拖拽、自动更新等原生能力
• REST + WebSocket：src/api/ 中与 octo-server 通信的客户端协议，支撑流式回复等实时会话能力
• octo-server：Go 编写的后端 API，负责业务编排与龙虾 Agent 调度，默认监听 http://localhost:8080
• Vite（VITE_API_* 环境变量）：环境配置机制，通过 .env.local 指向自有后端
• pnpm：包管理与构建脚本执行工具

前置要求

前置要求（依据材料）：

• 需要可运行的 octo-server 后端（默认连接 http://localhost:8080）
• 使用 pnpm 作为包管理器

克隆与安装命令（材料原文）：

bash
git clone https://github.com/Mininglamp-OSS/octo-web.git
cd octo-web
pnpm install
pnpm dev

项目采用 Apache License 2.0 许可。

实施步骤

1. 克隆并安装依赖

bash
git clone https://github.com/Mininglamp-OSS/octo-web.git
cd octo-web
pnpm install

2. 启动开发环境

bash
pnpm dev

默认连接 http://localhost:8080 的 octo-server。

3. 指向自有后端（可选）

复制 .env.example 为 .env.local 并修改其中的 VITE_API_* 字段。

4. 构建与打包

bash
pnpm build # 构建浏览器产物
pnpm pc:dev # Electron 壳加载 dev 构建
pnpm pc:package # 打可分发的 PC 安装包（macOS / Windows / Linux）

PC 打包支持 macOS / Windows / Linux 三个平台。

使用与配置要点

跑通后的关键使用方式：

• 日常开发用 pnpm dev；构建浏览器产物用 pnpm build
• PC 端开发调试用 pnpm pc:dev（Electron 壳加载 dev 构建），发布用 pnpm pc:package
• 质量验证：pnpm test 运行单元测试与组件测试
• 后端地址通过 .env.local 中的 VITE_API_* 字段配置
• 多语言资源集中在 src/locales/，新增文案需保证英中字段完整性（CI 有校验）

注意事项与常见问题

• 平台能力差异只在 capability 边界上分叉，浏览器端不依赖任何 Electron，不要在 Web 代码中直接使用 Electron API
• Electron 壳刻意保持很薄，原生能力通过 IPC 转发
• 上游脚手架来自 TangSengDaoDaoWeb，实时消息内核为 WuKongIM（由 octo-server 驱动），完整第三方清单见 NOTICE
• 安全问题请按 SECURITY.zh.md 上报，不要走公开 issue
• 项目遵循 Release-as-product 原则：一个 release 一次 squash，单仓即可复现

优缺点

• ✓ 一套代码两种产品形态
• ✓ 流式回复与 Agent 徽标等原生会话体
• ✕ 平台能力差异需在 capability
• ✕ 依赖 octo-server 才能运行

出处

本方案挖掘自开源项目 Mininglamp-OSS/octo-web，方案内容与实施命令均来自其 README 原文。