企业官网建设流程全解析

第一次从源码跑通 MindsHub Cowork：本地部署 AI 智能体工作空间 4 步走

【免费下载链接】mindshubThe unified workspace where open-source models get things done for you.项目地址: https://gitcode.com/GitHub_Trending/mi/mindshub

第一次从源码搭 MindsHub Cowork，最容易卡住的不是代码本身，而是这个仓库是"超级项目"——一个仓库里装着前端、后端 API、智能体引擎、数据引擎 4 个子模块，克隆漏了子模块、本地没跳过 SSO 登录，都会在启动阶段报错。本文按"克隆 → 装依赖 → 起服务 → 验证"的主线，带你用 4 个递进任务在浏览器里跑通最小闭环，全程只需要 Git、Node 和 uv 三样工具。

它到底解决什么

MindsHub Cowork 是一个统一工作空间：你把一个完整任务（写报告、做分析、搭内部小工具）委托给它，它调用可路由的开源/商用模型和开源智能体（默认 Anton、备选 Hermes），把产出变成文档、仪表盘、可发布的网页应用。数据源（Postgres、BigQuery、Notion 等）通过内置 vault 接入，凭证按连接隔离，智能体拿不到原始密钥。

这个仓库是平台的 superproject，适合两类人：想本地自托管这套 AI 工作空间的使用者，以及想改前端/后端任一模块的开发者。

动手前自查

确认命令都可用：

git --version && node -v && uv --version

主线任务：4 步跑通最小闭环

子任务 1：完整克隆超级项目

目标：拿到包含全部 4 个子模块的完整代码。

步骤：

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

如果当时忘了加--recurse-submodules，补一句：

git submodule update --init --recursive

验证：ls frontend backend/core_api backend/core_agent backend/data-vault，四个目录里都应有源码文件而不是空目录。

容易卡住的点：仓库对每个子模块只记录一个 commit 指针（tag-pinned），不执行--recurse-submodules时子模块目录会是空的，后续make setup会在uv sync阶段找不到uv.lock而失败。

子任务 2：一条命令装齐所有依赖

目标：让前端和两个 Python 后端各自拿到完整依赖。

步骤：

make setup

它做三件事：npm ci装 frontend/ 依赖、uv sync分别初始化 backend/core_api/ 和 backend/core_agent/ 的虚拟环境。

验证：跑make refs，能打印出三个模块当前用的 ref（默认main）就说明 Makefile 与配置读取正常。

容易卡住的点：首次执行会拉取大量包，耗时较长属正常；若网络慢，先给 npm 和 uv 配好镜像源再重试，避免中途失败留下半装状态。

子任务 3：浏览器模式启动并跳过 SSO

目标：在http://localhost:5173打开本地网页版，而不是被重定向到官方登录页。

步骤：

1. 在frontend/src/renderer/下创建.env文件（注意 Vite 的根是src/renderer，不是frontend/），内容只有一行：

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

2. 启动：

   make dev-web

   它会同时拉起 FastAPI 后端（http://127.0.0.1:26866，自动启动）和 Vite 前端。

3. 浏览器打开http://localhost:5173/。

验证：页面不再跳转 SSO，直接进入 onboarding 界面，可以在此填入自己的模型 API key（BYOK）。

容易卡住的点：忘了第 1 步就会在首次加载时被重定向走，误以为服务挂了；.env放错目录（放到frontend/根下）Vite 也读不到。

子任务 4：验证后端健康检查

目标：确认 Python 智能体运行时真正就绪，而不只是页面能打开。

步骤：

curl http://127.0.0.1:26866/health

（Docker 部署时，docker-compose.yml 里的 healthcheck 用的就是同一个端点。）

验证：返回 200 即后端存活；再回到浏览器发一条简单指令，能收到模型回复说明"前端 → API → 模型"链路全通。

容易卡住的点：若报 "Anton Python interpreter not found"，是uv工具安装目录名不一致，补一个软链接即可：

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

接入真实场景：给它接一个数据库

跑通最小闭环后，让它干点真活。Cowork 的数据入口是 backend/data-vault/ 这个安全密钥库：

1. 在应用内添加一个数据连接（如 Postgres），只填连接信息，凭证由 vault 按连接范围保存；
2. 委托任务时指明数据源，例如"统计上周订单量并生成图表"；
3. 智能体查询结果后，产出物（Artifacts）可以直接渲染成仪表盘或文档，发布成一个可分享的在线链接。

区别在于：你不需要自己写 API 调用或前端页面，"查数据 → 出报告 → 可分享"这条链在同一个工作空间内完成，且换模型（下拉切换 Anton/Hermes 引擎、不同提供方模型）后项目状态保留。

避坑清单

现象：启动报Can't locate revision或数据库迁移报错。原因：本仓库与桌面端共用~/.cowork/cowork.db，两条运行路径的代码版本不一致时迁移会错位。解法：确认make dev和桌面端用的是同一份 ref（make refs查看），实在对不齐时执行make flush从零重装。

现象：make flush后数据全部消失。原因：它按设计会删除~/.cowork（数据库、项目）和~/.anton（模型密钥），无回滚。解法：把它只当作"恢复损坏环境"的最后手段；执行前先备份这两个目录，CI 里才用FORCE=1。

现象：git status里子模块一片 dirty，或拉取后行为怪异。原因：子模块配了ignore = all，父仓库不会提示指针落后。解法：不开发模块时，拉完代码执行make baseline把子模块对齐到固定 commit。

现象：端口冲突或想直接容器化运行。原因：本地模式占用 5173（前端）和 26866（API）两个端口。解法：换用 Docker 栈：

make docker-build && make docker-up

API 端口映射见 docker-compose.yml，数据落在cowork-data卷里。

延伸一句话

想改代码的话，从dev.env.example复制出dev.env指定模块分支，再用make use+make dev就能对本地源码热重载开发；完整多分支工作流写在 CLAUDE.md 里，进阶部署（VPC、离线）参考仓库 README 的 Deploy 一节即可。

收尾

到这里，你已经从源码把 MindsHub Cowork 的本地闭环跑起来了：克隆、装依赖、跳过 SSO、健康检查，四步之后一个能查数据、能出报告、能发布成网页的 AI 工作空间就在localhost上。卡住了就去翻 README.zh.md 或到社区提问，动手本身比读十篇教程都快。

【免费下载链接】mindshubThe unified workspace where open-source models get things done for you.项目地址: https://gitcode.com/GitHub_Trending/mi/mindshub