OpenWork · 工程架构解读

OpenWork · 工程架构解读

基于 OpenCode 引擎构建的桌面应用与能力分享平台——讲透「一次创建、随处分享」背后的工程架构

这本教程讲什么

本教程是开源项目「OpenWork」的体系化中文教程。OpenWork 是一个开源的桌面应用与控制平面(control plane),用于分享和运行 AI 工作流(agentic workflows)——可以把它理解为 Claude Code / Codex 桌面端的开源替代,但它的野心不止于「一个桌面 App」:它的核心理念是**「一次创建,随处分享」**——你创建一套技能、一组 MCP 连接、一套服务,就能跨工具(Codex、Claude Code、Cursor 等任意兼容 Agent)、跨队友、跨机器复用。

它的硬核之处藏在三个设计决策里:第一,它不是从零造引擎,而是基于一个开源 AI 编码 Agent 引擎(OpenCode)构建——它通过「反向托管 + 运行时配置注入」接管引擎,不修改用户文件;第二,它用一套自研的极简 HTTP 中枢(服务端)承担整个产品的文件系统与能力管理,路由是正则编译式的,鉴权是四档的;第三,它最精巧的一笔是 meta-MCP 双工具脊柱——云端只暴露两个工具(检索能力 / 执行能力),能力数量可以无限增长,但 Agent 看到的工具永远只有两个。这套架构让它既能跑在你本地,也能扩展成企业级多组织 SaaS。

本教程不教你如何点桌面 App 的按钮,而是带你读它的工程图纸:三进程模型如何协作、服务端如何成为中枢、能力如何被治理与分享、桌面端如何管理引擎生命周期、前端如何跨浏览器与桌面复用、企业控制平面如何从 0 搭起。每章都回答「它解决什么问题、背后原理是什么、为什么这样设计」。

三章学习路径一览

本教程按「跑起来 → 看懂架构 → 逐子系统拆解 → 拔高」的递进逻辑组织,共十三章加一个附录:

第 1 章 环境准备与首次跑通 ── 本地一键起桌面端,接入第一个 Agent
   安装 · 桌面/Server 双启动 · 接入 Agent · 第一次会话
        │
第 2 章 整体架构:三进程模型与控制流 ── 建立全局地图
   三进程拓扑 · Server-consumption first · 控制流旅程 · 能力四源
        │
第 3 ~ 5 章 服务端与引擎托管 ── 平台的中枢
   HTTP 路由 · 鉴权作用域 · 引擎托管与配置注入
        │
第 6 ~ 8 章 能力体系与实时协同 ── 「分享」的工程实现
   四类能力 CRUD · meta-MCP 双工具脊柱 · Reload 事件
        │
第 9 ~ 11 章 桌面、前端、连接 ── 用户体验三件套
   Electron 主进程 · 前端分层 · Connect Link 分享
        │
第 12 ~ 13 章 企业与交付 ── 从个人工具到生产平台
   Den 控制平面 · 部署分发 · 工程方法论
        │
附录 A 术语表 · 速查 · 排错
​

如果你想快速试用,看第 1 章;想理解整体设计,第 2 章是地图;想知道「一次创建、随处分享」凭什么成立,重点读第 7 章 meta-MCP;想看企业级 SaaS 怎么搭,看第 12 章。

章节目录

第 1 章 环境准备与首次跑通
技术栈与环境要求、安装方式、桌面端与服务端双启动、接入任意兼容 Agent(加一个 MCP)、第一次工作区会话。读完你能把 OpenWork 跑起来并完成第一次 Agent 会话。

第 2 章 整体架构:三进程模型与控制流(全书地图)
三进程拓扑(渲染进程→Electron 主进程→服务端→引擎)与职责边界、「服务端消费优先(Server-consumption first)」设计哲学、一次用户操作的控制流旅程、能力四源与 meta-MCP 全局图。读完你能画出整张架构图并解释每一层的存在理由。

第 3 章 Server 核心:HTTP 中枢与路由引擎
正则编译式路由匹配引擎、能力声明契约、引擎反向代理与头清理、静态 UI 兜底与跨域。读完你能解释一个自研极简 HTTP 路由如何承担整个产品的中枢。

第 4 章 鉴权、令牌与权限作用域
四档鉴权模式、三级权限作用域(所有者/协作者/查看者)、查看者强制只读代理、审批模式与令牌服务。读完你能解释多级权限如何保证只读安全。

第 5 章 OpenCode 引擎托管与运行时配置注入
反向托管引擎(子进程生成 + 信任进程注册)、运行时配置文件注入(环境变量传递)、三方配置合并去重、配置新鲜度同步。读完你能解释 OpenWork 如何「接管」引擎而不修改用户文件。

第 6 章 能力体系:Skills / 插件 / MCP / Commands
四类可分享资源(Skills 渐进式披露指令、Commands 模板、MCP server 连接、Plugins 与 Extensions 统一 manifest)的增删改查与跨工具复用。读完你能管理四类能力并理解它们的边界。

第 7 章 meta-MCP:两工具无限能力的脊柱(全书核心)
检索能力的四源搜索、执行能力的统一执行、策略治理与外部能力、Memory Bank 持久化记忆。读完你能解释为何 Agent 看到的工具永远只有两个却能力无限。

第 8 章 Reload 事件系统与实时协同
Reload 事件与指纹(fingerprint)机制、SSE 轮询与客户端感知、引擎重载触发链、实时协同的边界。读完你能解释配置与能力变更如何实时驱动引擎重载。

第 9 章 Desktop 深度:Electron 主进程与运行时管理
运行时管理器的端口区间与粘滞端口(sticky port)、IPC 命令注册表与强校验契约、CDP 端口探测与架构自校正、自动更新与跨平台品牌图标。读完你能解释主进程如何管理引擎子进程生命周期。

第 10 章 前端 App:分层架构与 Platform 抽象
内核/外壳/领域三层分层、Platform Provider 抽象(服务端/SDK/全局同步)、会话/产物/语音/终端领域模块、桌面桥接代理。读完你能解释同一套 React 单页应用如何同时跑在浏览器与桌面。

第 11 章 Connect Link 连接分享与多端接入
签名式深链(验签 + 防重放)、交换式传输、多端接入模式(消息平台连接器)、语音模式与语义化 UI 控制。读完你能用一条深链安全地「一键分享/连接」。

第 12 章 企业控制平面:Den 架构与治理
Den 全家桶(后端/Web/推理/网关/控制器)、多组织与单点登录/SCIM、市场与能力治理、计费与云部署(Helm on AKS/EKS/GKE)。读完你能解释企业级多组织 SaaS 如何从 0 搭。

第 13 章 部署分发与工程方法论
多 flavor 打包(云版/企业版)、Docker/Helm/AUR 分发、帧帧证明(fraimz)评估方法论、多 Agent 协作范式与发布流程。读完你能把这套体系交付到生产并理解其开发方法论。

附录 A 术语表 · 命令速查 · 常见报错排查
全书术语词典(中英对照)、高频命令与接口速查、报错→原因→排查三列表。

适合读者

本教程适合想读懂一个工业级 AI Agent 桌面平台与控制平面的工程师与架构师:

• 用过 Claude Code / Codex 桌面端,想知道背后架构的开发者
• 想搭建团队级或企业级 AI 工作流平台的平台工程师
• 对 Electron + React + 本地服务端架构感兴趣的前端/桌面端工程师
• 研究多 Agent 协作、能力分享、控制平面设计的架构师
• 想二次开发或贡献代码的开源爱好者

前置知识:

• 熟悉 TypeScript / JavaScript,了解 React
• 对 Electron、HTTP 服务端、进程管理的基本概念
• 了解「AI Agent」「MCP」的基本概念
• 读过引擎(OpenCode)教程会有帮助但非必需——本教程在第 5 章会回顾必要的引擎概念

教程说明

• 本教程对照的原文来自 OpenWork 开源项目。若你使用的版本与本教程有差异,请以本地源码为最终依据。
• 本教程与引擎(OpenCode)教程各自独立成篇:本教程在第 5 章会回顾必要的引擎托管概念,不要求先读引擎教程;但若你想深入理解引擎本身的会话循环、上下文管理等内核机制,可参阅引擎教程。