MindsHub Cowork 源码构建与多模块开发实战：从 Superproject 架构到本地运行的完整指南

本文以 MindsHub（minds）仓库的中文 README 为主线，系统讲解 MindsHub Cowork——一个让开源模型真正"干活"的统一工作空间——的产品定位、核心功能与源码级运行方式。读完本文，你可以从零克隆仓库并用 make 体系搭建开发环境、在子模块功能分支上开发而不污染父仓库状态、用 Docker 完成容器化部署，并理解这套"超级项目（superproject）"工程组织方式的底层设计。

MindsHub Cowork 是什么

MindsHub Cowork 是一个统一工作空间，你可以在这里委托完整的项目——应用、网站、调研、分析、报告、定时运维——并获得可直接分享的成品结果。连接你的数据，将工作路由到任意模型（开源或商用），运行开源智能体，并将其产出转化为可发布的网页应用。它是开源的，可以运行在任何地方——你的电脑、你的 VPC，或托管应用中。

本仓库是平台超级项目（superproject）：它整合了桌面/网页应用、智能体后端和数据引擎，让你可以从源码构建并运行整套技术栈。根据 CLAUDE.md 的说明，仓库包含 4 个子模块：

路径	对应仓库	版本固定方式
frontend	mindsdb/cowork	tag-pinned
backend/core_api	mindsdb/cowork-server	tag-pinned
backend/core_agent	mindsdb/anton	tag-pinned
backend/data-vault	mindsdb/data-vault	main 分支

父仓库本身只保存指向各子模块提交 SHA 的指针，代码实体在子模块中——这也是后文"功能分支工作流"存在的原因。

能做什么：定位与内置功能

面向每一位知识工作者——创作者、策略制定者与运营者：

• 自动化涉及读写的重复性多步骤工作：报告、监控、周期性工作流以及定时运维任务；
• 构建内部 AI 工具与成果物——应用、仪表盘、演示文稿、文档、分析报告——无需工程开发，并发布到可分享给团队的在线链接。

内置功能包含五个核心支柱：

• 数据连接（Data Vault）。 安全的密钥库（vault）可连接 BigQuery、Postgres、Gmail、Drive、HubSpot、Notion、Linear 等系统。凭证按连接单独限定范围——智能体永远看不到原始密钥。对应 backend/data-vault 子模块。
• 模型路由（Model Router）。 在前沿模型（Claude、GPT、Gemini）与开源模型（DeepSeek、Qwen、Kimi）之间自由切换，无需为每个提供方单独配置密钥。
• 开源智能体。 运行可互换的开源执行引擎（harness）——Anton（默认）与 Hermes——通过下拉菜单即可切换。对应 backend/core_agent 子模块（Anton 引擎）。
• 成果物（Artifacts）。 将智能体的产出转化为文档、仪表盘、应用与代码，并发布到在线链接。
• 记忆、技能与定时任务。 跨会话记忆、可复用的技能库，以及按计划运行的任务。

快速开始

选择最适合你的方式：

• 网页版 —— 无需安装，直接打开 MindsHub 控制台（console.mindshub.ai）并登录；
• macOS —— 下载桌面应用（.pkg 安装包）；
• Windows —— 下载桌面应用（.exe 安装包）；
• Linux —— 从源码构建（下文详述）。

免费即可开始使用；Pro 版本解锁全部前沿模型与私有成果物。

从源码构建

1. 克隆仓库

git clone --recurse-submodules https://gitcode.com/GitHub_Trending/mi/mindshub.git
cd mindshub

如果克隆时未带 --recurse-submodules，可事后补初始化：git submodule update --init --recursive。

2. 安装依赖

make setup

从 Makefile 的源码可以看到，setup 目标同时依赖三个"stamp"文件，分别驱动三类依赖安装：

• frontend/package-lock.json → 触发 npm ci（frontend 模块）；
• backend/core_api/uv.lock → 触发 uv sync --directory backend/core_api；
• backend/core_agent/uv.lock → 触发 uv sync --directory backend/core_agent。

即 make setup 一次性完成 npm 依赖与两个 Python 虚拟环境的安装（参见 Makefile）。

3. 运行

模式	命令
桌面应用（Electron），支持热重载	make dev 或 make watch
浏览器网页应用，支持热重载	make dev-web
生产构建	make build
打包 macOS 版本	make dist-mac
打包 Windows 版本	make dist-win
从本地未提交的源码构建 macOS .app	make pack-local
清除所有本地安装与数据（从零开始）	make flush

其中 make dev 的实现值得细看（Makefile）：它在后台启动 uvicorn cowork.server:app --reload，并把 backend/core_api/cowork 与 backend/core_agent/anton 两个目录都挂到热重载监听列表，随后在前台运行 npm --prefix frontend run dev——前端、FastAPI 后端、智能体引擎三者同步热重载。make dev-web 则改用 BUILD_TARGET=web npm run dev:renderer 以浏览器 SPA 形态运行（Makefile）。

make flush：从零开始的破坏性重置

从零开始： make flush 会移除本地运行环境（cowork-server uv 工具及 backend/*/.venv），并删除 ~/.anton（提供方密钥）与 ~/.cowork（数据库、hermes、项目）中的应用状态。用它来测试从零安装流程，或从损坏的安装中恢复。执行前会要求确认——传入 FORCE=1 可跳过确认。之后运行 make setup 或启动应用即可重新安装全部内容。⚠️ 此操作会删除你的对话记录和已保存的密钥。

Makefile 中的实际删除清单更完整：

• cowork-server uv 工具（含遗留的 anton-agent 工具）——Electron 应用运行时通过 uv tool install 安装的服务端；
• backend/core_api/.venv 与 backend/core_agent/.venv —— Makefile 开发流程用 uv sync 构建的虚拟环境;
• ~/.anton —— 提供方密钥 / .env；
• ~/.cowork —— 数据库、hermes、projects。

值得注意的是它有意保留 uv 本身及 uv 管理的 Python 运行时（属于共享基础设施，不属于 anton/cowork 安装的一部分）。确认逻辑上，若 FORCE=1 则跳过 read -p 交互提示，方便 CI 与脚本化执行。

在功能分支上开发（子模块工作流）

本仓库是一个超级项目，将每个模块（frontend、backend/core_api、backend/core_agent、backend/data-vault）固定（pin）到某个提交。要在模块分支上开发而不污染 git status 或与固定版本产生冲突，工作流如下：

1. 在（已加入 .gitignore 的）dev.env 中选择你的分支

从模板复制，模板为 dev.env.example：

cp dev.env.example dev.env      # 然后设置 REF=feat/my-thing（或按模块设置 API_REF=…）

dev.env 支持两种粒度（dev.env.example 注释）：

# 所有模块用同一个分支：
REF=feat/my-thing

# …或按模块覆盖（优先级高于 REF）：
FRONTEND_REF=feat/ui-thing
API_REF=feat/server-thing
AGENT_REF=feat/agent-thing

make 会自动读取该配置（Makefile 中的 -include dev.env 与 REF ?= main 默认值），一个开关适用于两种运行方式：

命令	作用
make use	按 dev.env 中的配置检出所有子模块的分支
make dev / make watch	以本地源码热重载方式运行 Electron 应用
make dev-web	以本地源码热重载方式运行网页版 SPA
make server + make app	从配置的分支（重新）安装桌面服务端，然后启动
make server-local + make app-local	从本地未提交的源码安装桌面服务端，然后启动
make pack-local	从本地未提交的源码构建 macOS .app（无需推送）
make refs	显示下一次运行将使用的分支引用
make baseline	将子模块重置为固定的提交版本
make pin	将当前子模块提交记录为超级项目的固定版本（一次明确的提交）

源码级原理：两种运行路径、同一套 ref

make 是分支引用的唯一事实来源，两条运行路径都遵循 dev.env：

• 本地源码路径：make dev / dev-web 直接运行本地子模块源码，跟随 make use 检出的分支；
• uv-tool 安装路径：Electron 桌面端的服务端是一个按环境变量 COWORK_SERVER_REF / ANTON_REF 键控的 uv tool install（Makefile 中 export 了这两个变量；当 AGENT_REF 非 main 时还会追加 --with "anton-agent @ git+…@$(AGENT_REF)" 参数覆盖智能体来源）。

两条路径共享 ~/.cowork/cowork.db，因此必须保持同一 ref：一方应用过的数据库迁移必须存在于另一方，否则应用会在启动时报 Can't locate revision … 崩溃。漂移时用 make flush 重置。

make server 的具体安装命令（Makefile）：

UV_PYTHON_PREFERENCE=only-managed uv tool install \
    "git+https://github.com/mindsdb/cowork-server.git@$(API_REF)" $(_ANTON_WITH) \
    --force --reinstall --python '>=3.12,<3.14'

而 make server-local 则直接以 $(CURDIR)/backend/core_api 为源安装，无需提交或推送；若还需使用本地的 core_agent，按 Makefile 的提示把 backend/core_api/pyproject.toml 中 [tool.uv.sources] 的 anton-agent 指向 { path = "../../core_agent" } 后重跑即可（推送前记得恢复 git 源）。

ignore = all 与 make pin：固定的版本只能"显式"变更

子模块配置了 ignore = all，因此你在分支上的工作永远不会显示为超级项目的更改——父仓库的 git status 始终保持干净。这是唯一能静默"子模块有新提交"提示的设置（ignore = dirty 不行）。固定版本只能通过 make pin 变更：

• make baseline 执行 git submodule update --init --recursive，把所有子模块拉回父仓库固定的提交；
• make pin 执行 git add frontend backend/core_api backend/core_agent backend/data-vault，若有差异则提交一条 chore: bump submodule pins（Makefile）——这是一次有意的、可评审的提交，而非日常开发噪音。

完整流程见 CLAUDE.md。

随处部署：Docker 与部署拓扑

Cowork 的设计支持灵活部署——云端、VPC、本地部署、离线隔离环境以及混合基础设施——让你完全掌控自己的基础设施、模型、权限与数据。仓库内提供了开箱即用的 Compose 编排（docker-compose.yml），包含两个服务：

• api 服务：基于 docker/api.Dockerfile 构建。构建阶段用 python:3.12-slim + uv pip install ./core_agent ./core_api 打出虚拟环境；运行时以非 root 用户 cowork（uid 1000）运行，监听 0.0.0.0:26866（COWORK_SERVER_HOST / COWORK_SERVER_PORT），SQLite 数据库挂载到命名卷 cowork-data（容器内路径 /home/cowork/.cowork，与桌面端 ~/.cowork 布局一致），并内置每 30 秒一次、超时 5 秒、重试 3 次的 /health 健康检查。
• web 服务：基于 docker/web.Dockerfile 构建。构建阶段用 node:22-slim 执行 npm ci --ignore-scripts 与 npm run build:web，产出物 dist/renderer-web/ 交给 nginx:alpine 对外服务 80 端口；docker/nginx.conf 将 /v1/ 前缀的请求反向代理到 http://api:26866（proxy_read_timeout 120s），其余请求回退到 index.html（SPA 路由）。

Compose 中 web 服务通过 depends_on.condition: service_healthy 等待 api 健康检查通过后才启动；对 api 服务可注入 ANTHROPIC_API_KEY 等模型提供方凭证（docker-compose.yml 中有注释占位）。

在 Compose 之外，由于前端（Electron/SPA）、服务端（uv tool 安装的 cowork-server）与数据（~/.cowork 卷）彼此解耦，同一套构建产物可分别落入云端托管、VPC、本地机器或离线隔离环境——这正是 README 所述"随处部署"的工程基础。

帮助、贡献与安全

• 提出问题 —— 加入项目 Discord 社区；
• 报告 Bug —— 提交 GitHub issue，并附上复现步骤；
• 查阅文档 —— 使用指南、部署说明与 API（仓库内 docs/ 目录亦包含 API 文档与设置页）；
• 参与贡献 —— Cowork 是开源项目，欢迎代码、集成、文档、Bug 报告与功能建议，参见 CONTRIBUTING.md；
• 安全 —— 发现安全漏洞不要创建公开 issue，请按 SECURITY.md 私下提交报告。

本仓库基于 MIT 许可证 发布；所捆绑的组件遵循各自的许可证，详情参阅各子模块仓库。

小结

MindsHub 仓库的价值不仅在于一个"统一工作空间"产品，更在于它示范了一套可复用的多模块开源工程范式：用 superproject + 子模块 pin 固定版本，用 dev.env 让每位开发者在各自的模块分支上工作而 git status 保持干净，用 make use / baseline / pin 三件套完成"切分支—回基线—升 pin"的完整生命周期，再用 Makefile 把"本地源码热重载"与"uv tool 安装"两条运行路径统一到同一套 ref 之上。对需要在本地搭建、二次开发或私有化部署 MindsHub Cowork 的工程师来说，本文给出的命令与源码依据（Makefile、CLAUDE.md、docker-compose.yml）可直接照做。