OpenMuse 架构深度解析Expo 客户端、Hono 服务端、任务引擎与浏览器 Worker 如何紧密协作【免费下载链接】openmuseA personal agent with a browser, terminal, files, and work that keeps going built with CopilotKit and AG-UI.项目地址: https://gitcode.com/gh_mirrors/op/openmuseOpenMuse 是一个自带浏览器、终端和文件能力的个人 AI 代理项目基于 CopilotKit 与 AG-UI 协议构建。这篇文章带你快速读懂它的 OpenMuse 架构Expo 多端客户端、Hono 服务端、持久任务引擎与独立浏览器 Worker 四层如何分工协作让你像搭积木一样理解一个生产级 AI Agent 单仓库Monorepo的设计思路。上图是 OpenMuse 的移动端界面代理在聊天里内嵌浏览器卡片结果直接长在对话中。一、先鸟瞰一个 Monorepo四个应用 三个共享包OpenMuse 采用 pnpm workspace 管理见 pnpm-workspace.yaml核心目录分工非常清晰目录角色一句话说明apps/mobile/Expo 客户端一套 React Native 代码同时跑 iOS、Android 和 Webapps/server/Hono 服务端API、CopilotKit 运行时、任务引擎、文件与持久化apps/worker/浏览器 Worker独立的 Playwright Chromium 服务带持久化配置档apps/computer/Linux 容器可选的 Docker 终端与/workspace文件工作区packages/domain/共享领域模型任务、目标、监控等类型定义与请求校验packages/integrations/集成适配器GoogleGmail/日历、PDF 等协议适配packages/backends/预留后端OpenBot HTTP 适配器的身份边界tests/端到端测试工作流、持久化、权限与浏览器契约测试官方文档入口在 docs/README.md建议对照阅读。二、客户端层Expo 如何让一份代码跑三个平台apps/mobile是一个共享的 React Native 工作区见 apps/mobile/README.md一份源码三种运行形态pnpm --dir apps/mobile ios、android跑原生开发构建web则通过 React Native Web 渲染同一套界面无头 CopilotKit hooks聊天、AG-UI 流式事件、工具卡片渲染全部由src/下的组件驱动如 src/chat.tsx 与 src/agent-workspace.tsx平台差异隔离PDF 阅读、日期输入等组件按.native.tsx/.web.tsx拆成两个文件如 src/PdfReader.native.tsx状态逻辑保持共享客户端只做两件事展示工作流和调认证 API。浏览器预览与控制台只使用服务端签发的短时效 URL代理令牌绝不落到客户端。三、服务端层Hono CopilotKit 运行时的组合拳服务入口只有几行核心逻辑apps/server/src/index.ts读取配置 → 创建 PGlite/PostgreSQL 存储 → 恢复被中断的动作 → 启动任务 Worker → 用 Hono 挂载 HTTP 服务。真正的编排都在 apps/server/src/app.ts上图中代理查到的学校邮件直接以卡片形式嵌入对话这就是内联结果体验的由来。关键设计点单一身份边界所有/api/*路由先经auth中间件解析 ownerapp.ts#L126-L137文件内容与浏览器控制台走签名 URL 验证令牌只存在于服务端内存CopilotKit 运行时挂载/api/copilotkit/*转发给CopilotRuntimeapps/server/src/agent.ts支持三种代理后端内置示例代理、模型直连OpenAI/Anthropic/Google、或外部 AG-UI 端点——兼容任意 agent harness正源于此CORS 与请求体限制白名单 Origin、12MB 请求上限PDF ≤10MB错误统一转成可读 JSONapp.ts#L48-L90四、任务引擎让工作掉不掉线都接着跑这是 OpenMuse 架构里最有意思的部分核心在 apps/server/src/engine/持久任务任务、进度、输入请求、审批全部落库TaskWorker通过SQL 租约lease抢占任务engine/service.ts——进程重启后未完成的租约会被回收并继续执行维护循环每 60 秒对账一次持久记录补发丢失的结果、恢复被接受的 Idea、刷新数据源service.ts#L59-L116可分离部署任务 Worker 默认内嵌在 API 进程里生产环境可设TASK_WORKER_ENABLEDfalse后单独跑pnpm dev:worker多个 Worker 靠 SQL 租约互相协调但只保留一个 API 实例不自动重试危险写操作对结果不确定的外部写入如发邮件OpenMuse 宁可停下让你复核也不盲目重放配合 PGlite本地嵌入式 Postgres数据落在.openmuse/目录或独立 PostgreSQL任务在断电、重启后依然可恢复。五、浏览器 Worker一个只信任服务端的独立进程apps/worker/ 是一个完全独立的 Node/Playwright 服务apps/worker/README.md设计上有几道明显的安全边界令牌隔离只有持有 ≥32 位随机WORKER_TOKEN的服务端能调用它鉴权用 SHA-256 哈希 恒定时间比较apps/worker/src/server.ts令牌永远不会发给浏览器或手机持久化 Chromium 配置档每个会话对应一个 UUID 配置档Cookie 在优雅关闭时保存重启 Worker 后登录态与 PDF 下载都还在资源限额3 个并发会话、30 分钟空闲关闭、20 秒导航超时、每会话最多 20 个 10MiB 的 PDF网络出口管控只允许公网 80/443 端口DNS 结果逐个校验内网回环代理直连解析到的 IP防止 DNS 重绑定绕过容器以无特权用户运行、只读根文件系统、无 Docker socket启动方式二选一本地pnpm dev:browser或docker compose --env-file .env -f infra/compose.yaml up --build -dinfra/compose.yaml。六、协作全貌一次请求如何穿过四层你发出指令Chat → Expo 客户端AG-UI 事件流 认证 API → Hono 服务端身份解析、CopilotKit 运行时 → 任务引擎落库建任务SQL 租约驱动执行 → 浏览器 Worker导航、读取、截图、下载 PDF → Linux 容器可选终端命令、文件读写 → 结果内联回聊天邮件卡片、浏览器卡片、PDF 文档架构全景图可参考 README.md 的 Architecture 章节。当代理正在浏览时你在 App 里点Take control打开的正是 Worker 中同一个 Chromium 会话——这就是可见工作的体验基础。七、本地跑起来三步体验完整架构git clone https://gitcode.com/gh_mirrors/op/openmuse openmuse cd openmuse pnpm install --frozen-lockfile cp .env.example .env npx copilotkitlatest login npx copilotkitlatest project select # 生成 CPK_INTELLIGENCE_API_KEY 后写入 .env pnpm dev另开终端执行pnpm dev:web打开localhost:8081即可体验API 健康检查在localhost:8787/api/health。浏览器 Worker 则需先设置BROWSER_WORKER_URL与WORKER_TOKEN见 apps/worker/README.md。八、小结这套架构最值得借鉴的三件事职责切分到进程级别UI、API、浏览器、终端容器互不侵入浏览器 Worker 只信任服务端令牌天然隔离了最不可信的任意网页把持久化当第一公民SQL 租约 维护循环让 AI 工作不怕进程重启这是 alpha 项目里少见的工程化细节AG-UI 协议解耦代理后端客户端与任务引擎不关心模型是谁换模型、换代理框架都只动服务端一处配置OpenMuse 的架构证明了一件事个人 AI 代理不必是一个黑盒Expo、Hono、任务引擎与浏览器 Worker 各自独立又可组合MIT 协议下源码完全开放值得每一个想搭自己 Agent 的开发者逐层拆解。【免费下载链接】openmuseA personal agent with a browser, terminal, files, and work that keeps going built with CopilotKit and AG-UI.项目地址: https://gitcode.com/gh_mirrors/op/openmuse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考