MindsHub Cowork 实战指南：从源码构建、Make 目标详解到子模块分支工作流

2026-09-05 19:15:49作者：盛欣凯Ernestine

本文基于 MindsHub 官方 README 的西班牙语版本（README.es.md）编写，围绕 MindsHub Cowork 这套"统一工作区"平台展开：它让开发者把完整项目（应用、网站、研究、分析、定时运维）委派给可替换的开源/闭源模型驱动的智能体，并把结果发布为可分享的 Web 应用。读完全文后，你将掌握从源码克隆并运行整套技术栈的方法、每个 make 目标的真实行为、make flush 的破坏性边界，以及基于 git 子模块的多分支开发工作流。

一、MindsHub Cowork 是什么

按 README.es.md 的定义，MindsHub Cowork 是一个"统一工作区"（espacio de trabajo unificado）：你可以委派整个项目——应用、网站、研究、分析、报告、定时运维——然后拿到可直接分享的完成结果。核心能力包括连接数据源、把工作路由到任意模型（开源或闭源）、运行开源智能体，并把智能体输出转换成可发布的 Web 应用。它是开源项目，可运行在任意环境：你自己的机器、你的 VPC，或托管版应用。

该仓库是一个平台超项目（superproyecto）：它把桌面/网页应用、智能体后端与数据引擎聚合在一起，使你可以从源码构建并运行整条技术栈。用 Makefile 第 1 行起的变量定义来看，整条技术栈恰好对应四个目录：

超项目路径	角色
`frontend`	Electron 桌面应用 + Web SPA（`make dev` / `make dev-web` 的渲染层）
`backend/core_api`	FastAPI 服务端 `cowork.server:app`（`make dev` 中由 uvicorn 启动）
`backend/core_agent`	智能体 harness（默认 Anton，另有可切换的 Hermes）
`backend/data-vault`	数据连接凭证保险库（data vault）

需要说明的是：这四个目录在本仓库中均以 git 子模块形式存在，具体仓库映射见 .gitmodules 与 CLAUDE.md——frontend → mindsdb/cowork、backend/core_api → mindsdb/cowork-server、backend/core_agent → mindsdb/anton、backend/data-vault → mindsdb/data-vault，且全部配置了 ignore = all。克隆时若未带子模块，目录会是空的，需执行 git submodule update --init --recursive 补齐。

二、上手方式：四种路径

README 的 "Primeros pasos" 一节给出四条等价的入口，读者按环境任选其一：

Web —— 无需安装任何东西：打开托管控制台（console.mindshub.ai）并登录即可使用。
macOS：下载桌面端安装包（.pkg 格式）。
Windows：下载桌面端安装包（.exe 格式）。
Linux：从源码编译，即本文后续重点讲解的 make 流程。

免费版即可开始使用；Pro 订阅则解锁全部前沿模型与私有 artifacts（私有发布物）。

平台能做什么

面向所有知识工作者（创作者、策略人员、运营人员），README 给出两类核心场景：

自动化（Automatiza）：把涉及"读+写"的重复性多步骤工作交给系统——报告、监控、周期性工作流与定时运维任务。
构建（Crea）：不需要工程背景即可创建内部 AI 工具与产物——应用、仪表盘、演示文稿、文档、分析——并发布到一条可分享的在线 URL。

内置能力清单（Qué incluye）

README 列出了平台的五项内置能力，这也是理解后续构建与部署配置的钥匙：

数据连接（Datos conectados）：一个安全保险库（vault）连接 BigQuery、Postgres、Gmail、Drive、HubSpot、Notion、Linear 等系统。凭证按连接隔离——智能体永远看不到原始密钥。对应实现即子模块 backend/data-vault。
Model Router（模型路由器）：在前沿模型（Claude、GPT、Gemini）与开源模型（DeepSeek、Qwen、Kimi）之间切换，而无需为每个提供商单独配置密钥。
开源智能体（Agentes abiertos）：运行可互换的开源 harness——默认 Anton，另有 Hermes——从下拉菜单中切换。
Artifacts（产物）：把智能体输出转成文档、仪表盘、应用与代码，并发布到在线 URL。
记忆、技能与调度（Memoria, habilidades y programación）：跨会话记忆、可复用的技能库、按时间表执行的任务。

三、从源码构建：克隆、依赖安装与 Make 目标

这是 README "Compílalo desde el código fuente" 一节的完整流程，共三步。

第 1 步：克隆仓库

git clone --recurse-submodules https://github.com/mindsdb/minds.git
cd minds

注意 --recurse-submodules 不可省略：超项目本体只保存四个子模块的 commit 指针，不带该参数的克隆会得到空的 frontend 与 backend/* 目录。若已经克隆完成，可执行 git submodule update --init --recursive 补齐（见 CLAUDE.md）。

第 2 步：安装依赖

make setup

对照 Makefile 源码可以看到，setup 并非单一动作，它依赖三个"戳记"目标，按需触发三种安装：

$(_NPM_STAMP): $(FRONTEND)/package-lock.json
	npm --prefix $(FRONTEND) ci

$(_API_STAMP): $(API)/uv.lock
	uv sync --directory $(API)

$(_AGENT_STAMP): $(AGENT)/uv.lock
	uv sync --directory $(AGENT)

setup: $(_NPM_STAMP) $(_API_STAMP) $(_AGENT_STAMP)  ## install all module dependencies (npm + uv venvs)

即：前端用 npm ci 锁定安装，backend/core_api 与 backend/core_agent 两个 Python 模块各自用 uv sync 建立 .venv。README 的徽章标注了 Python 版本要求为 3.10–3.13；而桌面端服务端的安装（make server）在 Makefile 中进一步收紧为 --python '>=3.12,<3.14' 并要求 UV_PYTHON_PREFERENCE=only-managed，这是桌面路径与开发路径的一个实际差异。

第 3 步：运行——各模式 Make 目标

README 的运行模式表如下，并附源码级说明：

模式	命令	源码中实际做什么
桌面应用（Electron），带热重载	`make dev` 或 `make watch`	`uv run --directory backend/core_api uvicorn cowork.server:app --reload`（同时监听 `backend/core_api/cowork` 与 `backend/core_agent/anton` 两个目录），后台并行 `npm --prefix frontend run dev`；`watch` 是 `dev` 的别名
浏览器中的 Web 应用，带热重载	`make dev-web`	同样的 uvicorn 后端 + `cd frontend && BUILD_TARGET=web npm run dev:renderer -- --open`
生产构建	`make build`	`npm --prefix frontend run build`（仅渲染层生产构建）
打包 macOS	`make dist-mac`	`npm --prefix frontend run dist:mac`
打包 Windows	`make dist-win`	`npm --prefix frontend run dist:win`
从本地未提交代码编译 macOS `.app`	`make pack-local`	先执行 `server-local`，再 `npm run build` + `electron-builder --mac --arm64 --dir`，产物输出到 `/tmp/minds-build` 后拷回 `frontend/release/`（不产 DMG，iCloud 安全）
清空全部本地安装与数据（从零开始）	`make flush`	见下文专节

此外 Makefile 还提供了 README 运行表之外的 Docker 目标：make docker-build（docker compose build）、make docker-up（docker compose up）、make docker-down（docker compose down），配合 docker-compose.yml 使用，详见第六节。

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

README 用引用块给出了 make flush 的完整语义，Makefile 的实现与之逐条对应：

卸载 cowork-server uv 工具（以及遗留的 anton-agent 工具）——这是 Electron 桌面应用所用的运行时；
删除 backend/core_api/.venv 与 backend/core_agent/.venv——这是 Makefile 开发流程（uv sync）所用的 venv；
删除 ~/.anton（提供商密钥 / .env）与 ~/.cowork（数据库、hermes、项目）。

它用于从零测试安装流程，或从坏掉的安装中恢复。执行前会提示确认，传 FORCE=1 可跳过（CI/脚本场景）；下一次 make setup 或应用启动会重新安装一切。

make flush          # 交互确认
make flush FORCE=1  # 跳过确认

⚠️ 这是不可逆操作：会删除你的对话与已保存的密钥。CLAUDE.md 还补充了一个实现细节——flush 刻意保留 uv 本身与 uv 管理的 Python 运行时，因为它们是共享基础设施，不属于 anton/cowork 的安装范畴。

四、子模块分支开发工作流（本仓库最关键的协作机制）

README "Trabajar en ramas de funcionalidades (submódulos)" 一节解释了超项目的分支治理模型：每个模块（frontend、backend/core_api、backend/core_agent、backend/data-vault）都被 pin 到一个 commit；要在模块分支上开发而又不弄脏 git status、不与他人争夺 pin，仓库提供了一套 make 驱动的工作流。

4.1 在 gitignored 的 dev.env 中挑选分支

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

dev.env.example 的注释给出了两种写法：REF=feat/my-thing 让所有模块同分支，或用 FRONTEND_REF / API_REF / AGENT_REF 按模块覆盖（模块级变量优先于全局 REF）。Makefile 揭示了其默认值与传递链路：

-include dev.env

REF          ?= main
API_REF      ?= $(REF)
AGENT_REF    ?= $(REF)
FRONTEND_REF ?= $(REF)

export COWORK_SERVER_REF := $(API_REF)
export ANTON_REF := $(AGENT_REF)

也就是说，dev.env 不配置时一切默认跟随 main；而 COWORK_SERVER_REF / ANTON_REF 这两个环境变量会被导出给 Electron 桌面端的 uv-tool 安装器（前端侧对应 frontend/src/main/server-source.ts），使得**"本地源码开发"与"桌面应用安装"两条运行路径遵循同一套 refs**。当 AGENT_REF 不是 main 时，make server 还会向 uv 追加 --with "anton-agent @ git+…@$(AGENT_REF)" 参数。

4.2 make 如何跟随这份配置

README 的命令对照表（与 Makefile 实现一致）：

命令	作用
`make use`	按 `dev.env` 的 refs 在所有子模块上执行 `fetch` + `checkout`
`make dev` / `make watch`	以热重载运行 Electron 应用，针对本地已签出的源码
`make dev-web`	以热重载运行 Web SPA，针对本地已签出的源码
`make server` + `make app`	从配置的分支（重新）安装桌面端 uv 工具并启动应用
`make server-local` + `make app-local`	从本地未提交源码安装桌面端服务器并启动（无需 push）
`make pack-local`	从本地未提交源码构建 macOS `.app`（无需 push）
`make refs`	打印下一次运行将使用的各模块 refs
`make baseline`	`git submodule update --init --recursive`，把子模块重置回 pin 的 commit
`make pin`	把子模块当前 commit 记录为超项目的 pin（一次刻意、可评审的提交）

4.3 为什么 git status 永远干净、pin 只由 make pin 移动

README 的关键句是："Los submódulos están configurados con ignore = all"。对照 .gitmodules 可以确认每个子模块条目都带 ignore = all；CLAUDE.md 进一步说明：这是唯一能压制"new commits in <module>"提示的设置（ignore = dirty 不够），因此在任何模块上做的日常分支工作都永远不会出现在父仓库的 git status 中。相应地，pin 的唯一变动途径是 make pin——Makefile 中它执行 git add 四个子模块路径，若无变化则打印 "Nothing to pin"，有变化则提交 chore: bump submodule pins。

CLAUDE.md 还给出两条对桌面端开发者重要的实现级注意事项：

两条路径共享数据库：桌面应用与 make dev 共用 ~/.cowork/cowork.db。若一边执行了迁移而另一边没有对应 revision，应用会在启动时崩溃（Can't locate revision …）；出现漂移时用 make flush 重置。
未提交代码开发：make app-local 直接从 backend/core_api/ 安装 cowork-server 并自动设置 COWORK_SERVER_DISABLE_AUTOUPDATE=1，防止安装器从 git 重新下载、覆盖你的分支。若想同时未提交开发 core_agent，需临时把 backend/core_api/pyproject.toml 的 [tool.uv.sources] 中 anton-agent 改为 { path = "../../core_agent" } 再重跑（推送前恢复 git 源）。

五、本地 Web 模式：跳过 SSO 与首次符号链接修复

CLAUDE.md 补充了一条 README 未展开但本地开发必经的路径：make dev-web 启动后可访问 http://localhost:5173/，FastAPI 后端自动运行在 http://127.0.0.1:26866。

由于 Web 应用默认首次加载会重定向到 MindsHub SSO，本地开发需在 frontend/src/renderer/.env（注意 Vite 的根目录是 src/renderer 而非 frontend/）中创建：

echo "VITE_SKIP_AUTH=true" > frontend/src/renderer/.env

然后重启 npm run dev:web，即可跳过 Keycloak 重定向，直接进入可填入 BYOK API key 的 onboarding 界面。若遇到 "Anton Python interpreter not found"，是因为 dev:web 脚本期望 ~/.local/share/uv/tools/anton/，而 uv 实际可能装成了 anton-agent，建一个符号链接即可修复：

ln -s ~/.local/share/uv/tools/anton-agent ~/.local/share/uv/tools/anton

六、随处部署（Despliega en cualquier lugar）

README "Despliega en cualquier lugar" 一节声明 Cowork 面向 云端、VPC、本地机房、离线隔离（air-gapped）与混合基础设施设计，让用户完全掌控基础设施、模型、权限与数据。仓库内的可运行落地是 docker-compose.yml + docker/ 下的两个 Dockerfile，由 make docker-build / make docker-up / make docker-down 驱动：

api 服务：用 docker/api.Dockerfile 构建（python:3.12-slim，uv 安装 core_agent + core_api 两个包，最终 CMD ["cowork-server"]），以非 root 用户 cowork 运行，监听 26866 端口；数据持久化到命名卷 cowork-data 的 /home/cowork/.cowork（对应 DATABASE_URI=sqlite:////home/cowork/.cowork/cowork.db）。健康检查每 30 秒请求一次 http://127.0.0.1:26866/health（start_period 20s、重试 3 次）；
web 服务：Nginx 前端镜像（docker/web.Dockerfile + docker/nginx.conf），映射 3000:80，并声明 depends_on: api: condition: service_healthy——即 Web 层只有在 API 通过健康检查后才启动；
可选的 ANTHROPIC_API_KEY 类提供商密钥通过 ANTON_*_API_KEY 环境变量注入（compose 文件第 10 行注释示例）。

这套 compose 配置正是"数据、数据库位置、健康契约"在容器环境下与 ~/.cowork 状态模型保持一致的直接体现，也解释了为什么 make flush 要针对 ~/.cowork 与 ~/.anton 两个目录清理状态。

七、支持、安全与许可证

求助：加入 Discord 社区提问；通过 GitHub issue 报告 bug（附复现步骤）；查阅官方文档站获取指南、配置与 API。企业级 SLA 或定制部署可联系团队。
安全：发现漏洞时不要打开公开 issue，应通过安全策略私有报告；仓库配套文件为 SECURITY.md。
贡献：Cowork 欢迎代码、集成、文档、bug 报告与新功能想法，贡献流程见 CONTRIBUTING.md。
许可证：本仓库以 MIT 许可证发布（LICENSE）；各捆绑组件受其各自仓库的许可证约束。

八、小结：一张图理解整条链路

综合以上源码证据，MindsHub 的构建与运行链路可归纳为：

超项目层：minds 仓库只保存四个子模块的 commit 指针（.gitmodules），ignore = all 保证日常分支工作不污染父仓库；
依赖层：make setup = 前端 npm ci + 两个 Python 模块的 uv sync（Makefile）；
开发层：make dev / make dev-web 用 uvicorn --reload 同时监听 core_api 与 core_agent 源码，前端以 Vite 热重载运行（Makefile）；
桌面层：make server / make app（及 -local 变体）通过 uv-tool 从指定 ref 或本地源码安装 cowork-server，环境变量 COWORK_SERVER_REF / ANTON_REF 与开发层同源（Makefile）；
部署层：Docker Compose 把 API（26866 + 健康检查 + ~/.cowork 卷）与 Web（Nginx，3000）组成容器栈（docker-compose.yml）；
重置层：make flush 覆盖 uv tool、两个 venv 与 ~/.anton、~/.cowork 全部状态，FORCE=1 免确认（Makefile）。

对希望参与 MindsHub 开发的工程师而言，最实用的起步路径是：git clone --recurse-submodules → make setup → make dev（桌面）或 make dev-web（浏览器，配 VITE_SKIP_AUTH=true）；进入多分支协作时，再用 dev.env + make use / make refs / make baseline / make pin 四件套管理模块分支与 pin。