Workmate

Workmate —— 跨平台、本地优先的「数字员工」AI 工作台

语言： 中文 (zh-CN) · English

采用「根 README 索引 + 语言分档」结构，本文件为中文全文。

Workmate 是一套桌面级 Agent 工作台：其中的“数字员工”可以对话、运行项目编排、使用 Skills、检索知识库 / MCP 连接 / 联网搜索、管理资产与自动化，并且能通过本地通道网关被外部 IM（Telegram / 飞书）乃至远程中继终端调度。与常见“聊天壳 + 状态都在前端”的 Agent 应用不同，Workmate 把重编排放进服务端状态机：桌面 UI、网关进程与未来的远程终端共享同一份会话、审批、运行、资产与项目状态。

当前实现快照与验收边界见 docs/current-state.md。

协作约定（人与 AI）：根目录 AGENTS.md · 文档中心 · 工程规则

仓库刻意保持 Electron 壳“薄”：

Electron shell  →  本地 Fastify API  →  agent-core（pi / AgentScope / dsh）→ providers
Vue renderer ────── HTTP / SSE ────────┘
通道网关 ───────── HTTP / SSE ──────────┘（Telegram / 飞书 / 远程中继）

AgentScope 迁移说明见 docs/migrations/agentscope.md；协议 ABI 见 docs/architecture/agentscope-abi.md。
并发执行机制说明见 docs/architecture/concurrency-runtime.md；压测与验收清单见 docs/architecture/concurrency-verification.md。
可重复执行的并发回归入口为 pnpm concurrency:regression（会先跑 dsh MCP/Skills 桥接 case）。独立验证：pnpm dsh:regression。

快速入口：

• 运行形态说明：docs/guides/runtime-modes.md
• 发布前检查清单：docs/releases/checklist.md
• 双运行形态改造说明：docs/releases/dual-runtime-release-notes.md

能力一览

仓库结构（pnpm monorepo）

当前完整架构与模块职责见 docs/architecture/architecture.md。

安装与使用

桌面安装包可从发布页下载安装。当前 macOS 安装包未签名，首次下载后如果系统阻止启动，可在终端执行：

xattr -cr "/Applications/Workmate.app"

如果你尚未把应用拖入 Applications，也可以对下载目录中的 .app 执行同样命令，然后再手动打开。

如需通过 npm 安装并使用 CLI / Web Launcher：

npm install -g @next-open-ai/workmate
workmate doctor
workmate init
workmate start

常见使用入口：

1. 桌面版：安装后直接启动应用，在界面内完成模型、员工、知识库、自动化与通道配置。
2. npm / CLI：适合本地拉起 Web Launcher，常用入口为 workmate doctor、workmate init、workmate start。
3. 源码开发：在仓库根目录执行 pnpm install && pnpm dev，用于联调 desktop + api + renderer。

快速开始

要求：Node.js ≥ 22、pnpm ≥ 10（packageManager 已固定）。
如需 AgentScope sidecar，还需要 Python ≥ 3.10。

pnpm install
pnpm dev        # 桌面开发：先构建 workspace 包，再起 Vite + Electron
pnpm typecheck
pnpm build
pnpm package    # electron-builder 打安装包

如需启动独立 Web 运行时或 npm 形态：

pnpm web:build
pnpm web:start

如果通过 npm 安装发布包，可使用：

npm install -g @next-open-ai/workmate
workmate doctor
workmate init
workmate start

本地常用校验命令：

pnpm dsh:regression
pnpm concurrency:regression
pnpm agentscope:smoke
pnpm quality:console       # 打开本机测试控制台 http://127.0.0.1:47840

默认开发界面端口为 47831，本地 API 为 47832，测试控制台为 47840；刻意避开常被占用的 5173。
默认数据目录为 ~/.workmate。

在“设置 → 模型”配置 Provider 之前不会存储/使用任何模型密钥。无头/CI 冒烟脚本见 scripts/*-smoke.mjs 与设计文档。

运行形态

Workmate 当前有 4 种实际运行形态：

完整能力对齐矩阵见 docs/guides/runtime-modes.md。

架构现实

如果你要基于当前仓库做评估，这几个事实最关键：

• 编排层是服务端唯一真相源：/api/orch/** + SSE 才是会话 / run / 项目的正式接口面。
• Electron 主进程刻意保持“薄”，不直接发模型请求。
• 模型 / 搜索 / 通道等密钥仍保留在主进程 safeStorage，不会写入 domain.json。
• 默认执行引擎是 pi；AgentScope 与 dsh 是挂在统一产品面下的可选执行后端。
• 本地 embedding sidecar 仍处于演进中：当前已有架构方案、provider 契约、状态管理与桌面控制面，但真正内嵌本地推理后端仍在产品化。

相关设计入口：

• docs/architecture/execution-backend.md
• docs/architecture/dsh-sidecar.md
• docs/architecture/agentscope-abi.md
• docs/architecture/embedding-local-sidecar-architecture.md
• docs/architecture/embedding-local-sidecar-implementation-plan.md

发布

推送形如 v0.1.0 的 SemVer tag 会触发桌面发布工作流。

当前 CI 实际产出：

Intel macOS 与 Linux 打包暂在 CI 停用（细节见 .github/workflows/release.yml 注释）。

文档导航

通道网关里程碑状态

许可

MIT License（MIT 许可）。