Open Claude Cowork：基于 Electron + React + ACP 的本地多 Agent 协作桌面应用

面向“多任务、多 Agent、可本地执行”的 AI 协作场景，这个仓库提供了一个完整的桌面端实现：前端负责多任务与对话体验，主进程负责 ACP 连接、权限与系统能力，SQLite 做本地持久化，整体可离线运行并适配多个 Agent CLI。

1. 项目定位与核心价值

Open Claude Cowork 的核心定位是：让多个 AI Agent 以统一协议（ACP）在桌面端被管理、对话与协作。其特点可以概括为：

任务为中心：每个任务绑定独立工作区与 Agent 会话，适合长期协作。
ACP 统一协议：通过 @agentclientprotocol/sdk 统一接入不同 Agent CLI。
可控权限与工具调用可视化：工具调用、权限请求会被 UI 捕获并可人工确认。
本地数据与隐私优先：任务与设置落在本地 SQLite 中。

2. 技术栈与工程化选型

从 package.json 和构建配置来看，该项目是一个标准的 Electron 桌面应用，技术关键点如下：

主进程：Electron + Node.js（TypeScript）
渲染层：React + Ant Design + Tailwind CSS
构建工具：Rsbuild（分别构建 main 与 render）
数据库：better-sqlite3（WAL 模式）
协议：ACP（Agent Client Protocol）
打包：electron-builder + plop 执行构建流程

相关路径参考：package.json, builder/rsbuild.*.ts, builder.js, plopfile.js。

3. 架构总览（Main/Renderer/ACP）

整体架构可以简化为三层：

Renderer (React UI) │ window.electron.invoke / on ▼ Main Process (Electron) ├─ IPC: env / db / agent / dialog ├─ ACP: AcpAgentManager → AcpAgent → AcpConnection └─ SQLite: settings / tasks

Renderer 通过 preload.ts 暴露的 window.electron 调用 IPC。
Main 负责连接 Agent、权限处理、文件读写、持久化。
ACP 协议通过 @agentclientprotocol/sdk 驱动 JSON-RPC 流。

核心入口文件：src/main/index.ts、src/main/preload.ts、src/render/index.tsx、src/render/AppNew.tsx。

4. 核心模块详解

4.1 Main 进程与 IPC 桥接

主进程入口在 src/main/index.ts，主要职责包括：

初始化数据库（initDB()）
注册自定义协议 wallpaper://
创建窗口（BrowserWindow）并加载 URL
注册 IPC 模块：env, dialog, db, agent

IPC handler 分布：

环境与系统能力：src/main/ipc/env.ts
选择文件/目录：src/main/ipc/dialog.ts
数据库 CRUD：src/main/ipc/db.ts
Agent 管理：src/main/ipc/agent.ts

src/main/preload.ts 则通过 contextBridge 暴露最小能力：

window.electron.send / invoke / on

这保证了渲染层与主进程通信的安全边界。

4.2 ACP 接入链路（核心）

ACP 的接入由四个核心类构成：

AcpDetector（src/main/acp/AcpDetector.ts）
- 扫描本地 CLI（如 qwen、gemini、npx）
- 返回可用 Agent 列表
- 检测命令来自 ACP_BACKENDS_ALL（src/types/acpTypes.ts）
AcpAgentManager（src/main/acp/AcpAgentManager.ts）
- 管理当前 Agent 实例、复用连接
- 解析命令、处理本地 bin 与 Node 运行时逻辑
- 提供 connect/send/stop/newSession/loadSession 等入口
AcpAgent（src/main/acp/AcpAgent.ts）
- 会话级别控制，负责 initialize → newSession → prompt
- 支持 @file 文本扩展（读取工作区文件并拼入 prompt）
- 将 ACP 原始更新转为 UI 可用消息
AcpConnection（src/main/acp/AcpConnection.ts）
- spawn 子进程，并通过 ndJsonStream 建立 JSON-RPC 流
- 支持权限请求、文件读写、runShellCommand 扩展
- 具备 prompt 超时与暂停/恢复机制

这种分层使 ACP 逻辑清晰：连接、会话、消息适配、UI 通知各自隔离。

4.3 本地数据模型

数据库在 src/main/db/store.ts 初始化：

settings：保存自定义路径、主题、壁纸等
tasks：任务维度记录
- id/title/workspace
- agent_command/agent_env
- messages/session_id/model_id/token_usage
- created_at/updated_at/last_active_at

任务数据在 Renderer 内通过 IPC 持久化（db:create-task, db:update-task）。

4.4 渲染层交互与消息模型

核心 UI 在 src/render/AppNew.tsx，特征包括：

多任务状态管理：任务列表、当前任务、任务级连接状态
消息流与合并：
- MessageComposer 合并流式文本与 tool_call 更新
- messageTransformer 在 ACP 消息与 UI 消息之间转换
环境检测与引导：EnvironmentSetup.tsx
设置与 Agent 配置：SettingsModal.tsx

消息合并策略（src/render/utils/messageComposer.ts）体现为：

msg_id 复用 → 文本流式拼接
toolCallId 对应 → tool call 状态更新合并
thought 单独拼接

这保证了对话体验可连续显示，同时保留工具调用信息。

4.5 权限与工具调用展示

ACP 支持权限请求与工具调用。在本项目中：

Main 在 AcpConnection.requestPermission 时会挂起 prompt 超时
Renderer 收到 permission_request 后展示 UI
用户反馈通过 agent:permission-response 返还给主进程
tool call 日志以 tool_call/tool_call_update 形式进入消息流

4.6 环境与 Node 运行时管理

为了支持本地 CLI Agent，需要 Node + npm：

env:check 检测 Node/npm 版本
env:set-node-runtime 支持 custom Node 路径
env:run-install-command 支持一键安装（mac/linux nvm，Windows choco）

对应 UI 在 EnvironmentSetup.tsx，会进行引导并展示执行日志。

5. 关键流程拆解

5.1 应用启动流程

main/index.ts 初始化 DB
注册 wallpaper:// 协议
创建窗口并加载 Renderer
注册 IPC handlers
初始化 ACP CLI 检测器

5.2 会话与消息流（关键）

Renderer (SendBox) → ipc invoke agent:connect → AcpAgentManager.connect() → AcpAgent.connect() → AcpConnection.spawn + initialize → session/new → session/update (streaming) → MessageTransformer → UI