OpenWork · 第 1 章 环境准备与首次跑通

OpenWork · 第 1 章 环境准备与首次跑通

章节摘要:OpenWork 的安装不像装一个普通桌面 App 那样「双击就完事」——它是一个由工作区(pnpm workspace)与任务编排(Turborepo)管理的多包单体仓库,跑起来时桌面外壳、本地服务端、底层引擎会同时启动并彼此通信。本章先把这些环境前提讲清楚:为什么需要特定运行时(Bun 给服务端、Node 给桌面外壳)、包管理为什么严格限定、依赖为什么用目录(catalog)锁定版本。然后带你完成「桌面端 + 服务端」双启动,再把任意一个兼容 Agent(Codex、Claude Code、Cursor 等)通过加一个 OpenWork MCP 接进来,完成第一次工作区会话。读完本章,你会有一个能跑的本地环境,以及一份对「一次 Agent 会话在 OpenWork 里到底由哪些进程协作完成」的直观感受——这正是第 2 章三进程模型讨论的地基。

学习目标

阅读完本章,你应当能够:

1. 列出 OpenWork 的技术栈与环境要求,并解释每项依赖为何必要(为什么服务端用 Bun、桌面用 Node、包管理严格限定)。
2. 完成仓库克隆与依赖安装,理解工作区与任务编排工具如何管理多包。
3. 启动桌面端与服务端双形态,并解释两者各自的角色。
4. 把任意兼容 Agent 通过加一个 OpenWork MCP 接入,完成第一次工作区会话。
5. 在遇到常见启动问题时,知道该从哪些地方排查(端口、运行时版本、依赖锁定)。

核心概念速览

一句话总结:装好工作区、双启动桌面与服务端、用一个 MCP 接入 Agent、跑第一次会话——本章只做这四件事,但它把「OpenWork 能用」变成了一件确定的事。

子章节导航

01 技术栈与环境要求

讲技术栈:服务端运行时(Bun)、桌面外壳(Node + Electron)、前端(React)、严格包管理、目录(catalog)锁定版本、补丁依赖。给出环境自检清单与「为什么这么限定」的工程理由。

02 安装与桌面/服务端双启动

讲仓库克隆、依赖安装,以及如何同时启动桌面外壳与服务端。重点说明双启动时两者各自的角色——桌面是用户看到的界面,服务端是真正的中枢。

03 接入任意兼容 Agent

讲如何把一个兼容 Agent(Codex、Claude Code、Cursor 等)通过加一个 OpenWork MCP 接入。这一节展示了 OpenWork「跨工具复用」的核心承诺——你不需要换 Agent,只要加一个 MCP。

04 第一次工作区会话

跑通之后,完成第一次工作区会话:创建工作区、发起对话、观察 Agent 如何调用能力。这一节是第 2 章三进程模型的预告片。

子章节之间的逻辑关系

本章遵循「确认前提 → 装好启动 → 接入 Agent → 跑通会话」的动手路径:

环境要求 (01)  ──确认机器能跑
   │
   ▼
双启动 (02)    ──把它装上,双形态启动
   │
   ▼
接入 Agent (03) ──用 MCP 接入你的 Agent
   │
   ▼
第一次会话 (04) ──看见多进程如何协作
   │
   ▼
第 2 章:这些进程协作背后的三进程模型
​

前三节是「让它能用」,最后一节是「用起来之后看一眼底层」——正是这种从结果反推结构的视角,把本章和第 2 章的架构讨论自然衔接起来。

前置知识与后续延伸

前置知识:

• 基本的命令行与终端使用经验
• 一个可用的兼容 Agent(Codex / Claude Code / Cursor 等)或一个模型 API 凭据
• 对「AI Agent」「MCP」的基本概念

本章为后续章节奠定的基础:

• 双启动体验(02)为第 2 章三进程模型提供直观前奏
• 接入 Agent(03)为第 7 章 meta-MCP 理解「Agent 如何看到能力」铺垫
• 工作区概念(04)为第 3、5 章理解服务端的工作区管理铺路