Multica：让 AI 编码智能体上看板协作的开源团队工作区——架构、运行时与自部署实战指南

本文以 Multica 官方中文 README 为主体，带你吃透这套"人和 AI 智能体同队工作"的开源自托管平台：它如何把 23 种智能体 CLI 变成看板上的"同事"、任务从指派到人工验收的完整流转、23 种受支持运行时的底层注册机制、Docker Compose / Helm 自部署流程，以及 make dev 一键拉起整套开发环境的实现原理。读完你可以独立完成自部署、接入自己的机器作为运行时、派任务给智能体并审计它的每次执行。

一、Multica 解决什么问题

Multica 的官方定位一句话概括："智能体，也在看板上。"它要解决的痛点在 README.zh.md 中描述得很具体：当你同时开着 Claude Code、Codex 和另外几个智能体时，每一个都关在自己的终端标签页里，会话一关就什么都不记得，同一段上下文你一天要重复讲很多遍——智能体越加越多，人反而越忙。

Multica 的解法是把智能体和人类队友放进同一个工作区：

• 任务派给智能体后，它自己接手，在你的机器上跑（而不是某个云端沙箱）；
• 执行过程中边做边评论，卡住了主动说，完成后把任务**挪到"审核中"**等人工验收；
• 从最初的想法、中间的每一次执行和决定，到最后的 diff，全部挂在同一个任务下，无需任何人重新捋上下文；
• 没有任何东西能不经人点头就上线——验收权始终在人。

围绕这一核心，README 将产品能力归纳为三组：

1. 组一支队伍

• 23 种智能体 CLI：Claude Code、Codex、Cursor、Copilot、Kimi、OpenCode 等，不用只挑一个，可以全部招进来；
• 智能体也是队友：给智能体起个名字、选个提供方、配一台运行时，它就上了看板，跟人类同事没有区别；
• 小队（Squads）：人和智能体混编成队，由 leader 决定谁来接活；
• Skills：解决过一次的问题沉淀成技能，全团队的智能体都能复用；
• 你自己的运行时：智能体的"工位"就是你的机器——守护进程跑在笔记本或云主机上，代码不出门。

2. 把活交出去

• 分配任务：像挑同事一样挑一个智能体当负责人，剩下的它自己来；
• 自动化（Autopilots）：日报、巡检、周报按 cron 自己跑，不用人催；
• Chat：直接问工作区，或者不建任务就把活派出去；
• 项目（Projects）：把工作归类，顺手挂上智能体要用的仓库和文档。

3. 看得见，也管得住

• 执行日志：每次工具调用、命令和报错都带时间戳，可以完整回放；
• Token 用量：每次运行花了多少，按智能体、按任务都看得到；
• 人来验收：活先进入"审核中"，不直接进 main，上不上线由人决定；
• 收件箱（Inbox）：只在智能体需要你拍板时提醒，而不是每一步都来打扰；
• 重试与超时：失败的 task 会自动重试，或者停下来告诉你为什么。

此外还有一组"整套都归你"的能力：整套自部署（Docker Compose 或 Helm）、任意 Git 服务（GitHub、GitLab、Gitea、Forgejo、自建实例）、按团队隔离的工作区、owner/admin/member 角色加到"谁能跑哪些智能体"的细粒度权限、明确的智能体安全边界，以及 Slack、飞书、钉钉（社区维护）等消息渠道。客户端覆盖 Web、桌面端（macOS/Windows/Linux）和移动端——注意 iOS 端目前需要自己从源码编译安装，尚未上架 App Store。

二、开始使用与五分钟跑通第一个智能体

使用前提只有一个：跑智能体的那台机器上，装好并登录好至少一个受支持的智能体 CLI（Claude Code、Codex、Cursor 均可）。Multica 负责驱动这些 CLI，但不替你安装。

README 给出的五分钟流程如下，完整继承自原文档：

1. 登录。 在浏览器里打开 multica.ai，或者打开 Multica 桌面端（macOS / Windows / Linux 均可下载）。打开桌面端后，这台电脑就自动注册成一个运行时，并顺带检测已安装的智能体 CLI。
2. 接入一台电脑。 所谓运行时，就是智能体干活用的机器——你的笔记本，或者一台云主机。使用网页版、或者想再接一台机器时，打开侧边栏的运行时，点右上角的添加电脑，把弹窗里的两条命令粘到那台机器的终端里即可。
3. 创建智能体。 打开侧边栏的智能体，点新建智能体。选中刚接入的运行时，选一个提供方，起个名字——或者选通过 AI 创建，描述几句，配置自动生成。这个名字就是它之后在看板和评论里的身份。
4. 派给它一件事。 建一个任务，负责人选成这个智能体。它会自己接手、在你的机器上跑、边做边评论，干完把任务挪到"审核中"。

界面上能点的操作，CLI 和 API 里都能调——智能体操作 Multica 本身，用的就是同一套 CLI（参考 CLI_AND_DAEMON.md）。

三、运行时：23 种智能体 CLI 的接入清单

Multica 不自带模型，它驱动的是你本来就装好、登录好的那些智能体 CLI，所以换提供方就是切个下拉框，谈不上迁移成本。README 给出的官方支持清单（23 种）如下：

Provider	CLI 命令	Provider	CLI 命令
Claude Code	claude	OpenAI Codex	codex
Cursor Agent	cursor-agent	GitHub Copilot CLI	copilot
OpenCode	opencode	OpenClaw	openclaw
Hermes	hermes	Pi	pi
Antigravity	agy	CodeBuddy	codebuddy
DevEco Code	deveco	Grok	grok
Kimi	kimi	Kiro CLI	kiro-cli
Qoder CLI	qodercli	Qoder CN	qoderclicn
Qwen Code	qwen	QwenPaw	qwenpaw
Reasonix	reasonix	Trae CLI	traecli
DeepSeek Harness	dsh	Oh-My-Pi	omp
Dim	dim

源码视角：运行时注册机制

README 中的 23 种 CLI 只是当前版本的面貌，源码揭示了这套清单是如何扩展和分层的。

协议家族白名单。 在 server/pkg/agent/agent.go 中，SupportedTypes 列出了当前代码库实际支持的 24 个"协议家族"（protocol family），包括 claude、codex、cursor、copilot、opencode、deveco、openclaw、hermes、pi、kimi、reasonix、dsh、kiro、antigravity、qoder、qoderclicn、traecli、grok、qwen、qwenpaw、mcode、dim、zeroclaw 等。源码注释明确说明：这份白名单必须与数据库 runtime_profile.protocol_family 的 CHECK 约束保持同步。

迁移链印证了快速扩张。 在 server/migrations/ 目录下可以看到一路追加运行时的迁移文件：134_runtime_profile_add_qoder.up.sql、136_runtime_profile_add_traecli.up.sql、175_runtime_profile_add_deveco.up.sql、179_runtime_profile_add_grok.up.sql，一直到 185_agent_task_accountable_user.up.sql 共 185 个迁移版本——这与 README"我们几乎每个工作日都发版，main 走得很快"的说法互相印证。

内置运行时身份层。 在 server/pkg/agent/builtin_runtimes.go 中，还有一层"运行时身份"（runtime identity）注册表：多个 CLI 可以共用同一个协议后端。例如 omp（Oh-My-Pi）就是一个独立 CLI，但走的是 pi 家族的 JSON 事件协议，其描述符集中声明了 CLI 名（omp）、环境变量前缀（MULTICA_OMP，即 MULTICA_OMP_PATH/MULTICA_OMP_MODEL 覆盖项）、显示名（"Oh-My-Pi"）、技能目录（.omp/skills）等。源码注释指出："给现有运行时加一个兼容 fork，只需要加一条描述符，而不是一次跨栈改动"。ResolveBackend() 是守护进程构建后端的唯一生产入口：运行时身份走 NewRuntime()，协议家族走 New()，且采用 fail-closed 策略——后端不支持覆盖时直接报错，而不是默默降级。

模型发现与降级。 每种运行时的 ModelDiscovery 策略各不相同（如 omp 用 omp models --json，与 pi 的 --list-models 输出格式不兼容）；当 CLI 缺失或版本过旧时，ListModels 吞掉错误并降级为手动填写模型名，而不是执行一个语义不兼容的命令。

四、整套自部署：Docker Compose 与 Helm

README 中"整套自部署"折叠块给出的官方命令完整继承如下：

curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --with-server
multica setup self-host

Windows 上先设置 $env:MULTICA_MODE="with-server"，再运行 PowerShell 安装脚本： irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex。

这会拉取 GHCR 上的官方镜像，需要 Docker。如果你的 GHCR 标签还没发布，可以在代码目录里跑 make selfhost-build 兜底。详细指南见 SELF_HOSTING.md，Helm 部署配置在 deploy/helm/multica/ 目录。

源码视角：自部署的落地细节

Makefile 中 selfhost 目标的实际行为比 README 描述更细：

• 首次运行自动生成 .env：从 .env.example 复制，并用 openssl rand 生成随机的 JWT_SECRET（hex 32）、POSTGRES_PASSWORD（hex 24）和 MULTICA_VCS_SECRET_KEY（base64 32），自动区分 Darwin 与其他系统的 sed 语法；
• 镜像拉取失败即给出兜底指引：若官方标签未发布，会明确提示改用 make selfhost-build（从当前 checkout 构建 backend/web 后启动）；
• Compose 版本守门：REQUIRE_COMPOSE 前置检查会拒绝 legacy v1 的 docker-compose，因为自部署 compose 文件使用 compose-spec 语法（顶层 name:、无 version: 字段），v1 无法解析，提前失败并给出可操作的错误信息；
• 启动后健康等待：scripts/selfhost-wait.sh 负责等待服务就绪。

docker-compose.selfhost.yml 中，PostgreSQL 使用 pgvector/pgvector:pg17 镜像（对应架构表中的 PostgreSQL 17 与 pg_trgm 等扩展需求），backend 与 web 分别拉取 GHCR 上的 multica-backend 与 multica-web 镜像，可用 MULTICA_IMAGE_TAG 指定标签。Dockerfile 基于 golang:1.26-alpine 构建、alpine:3.21 运行；docker/entrypoint.sh 负责容器启动逻辑。

五、架构与核心技术栈

README 给出的架构总览（完整继承）：

        Web  ·  桌面端 (macOS/Windows/Linux)  ·  iOS
                          │
                          ▼
   ┌──────────────┐   ┌──────────────┐   ┌──────────────────┐
   │   Next.js    │──>│   Go 后端    │──>│   PostgreSQL     │
   │    前端      │<──│  (Chi + WS)  │<──│   (17)           │
   └──────────────┘   └──────┬───────┘   └──────────────────┘
                             │  通过 WebSocket 下发 task
                      ┌──────┴───────┐
                      │   守护进程   │  跑在你的机器上，紧挨着你的代码
                      └──────┬───────┘
                             │  拉起
                      ┌──────┴───────────────────────────────┐
                      │  Claude Code · Codex · Cursor · …    │
                      │  （上面 23 种运行时里的任意一种）    │
                      └──────────────────────────────────────┘

层级	技术栈
Web	Next.js 16 (App Router)
桌面端	Electron，复用 Web 的 UI 包
移动端	Expo / React Native (iOS)
后端	Go (Chi router, sqlc, gorilla/websocket)
数据库	PostgreSQL 17（pgcrypto + pg_trgm）
智能体运行时	本地守护进程拉起上面 23 种智能体 CLI 中的任意一个

仓库源码对上述架构的印证

• Web 层：apps/web/package.json 中 next 为 ^16.2.5，与"Next.js 16"一致；
• 桌面端：apps/desktop/package.json 使用 electron ^39.2.6，构建配置见 electron.vite.config.ts，确实复用 packages/ 下的共享 UI 包；
• 移动端：apps/mobile/package.json 使用 expo ~55.0.23 + react-native 0.83.6，编译安装到 iPhone 的步骤见 apps/mobile/README.md；
• Go 后端：server/go.mod 声明 go 1.26.6，核心依赖 go-chi/chi/v5（路由）、gorilla/websocket（实时通道）、jackc/pgx/v5（数据库驱动）、spf13/cobra（CLI）、robfig/cron/v3（Autopilot 定时触发）等，与架构表逐项对应；SQL 层通过 sqlc 生成类型安全代码（server/sqlc.yaml）；
• 数据模型：server/migrations/ 下 185 个版本化迁移覆盖了 issue、task_queue、chat、autopilot、squad、runtime_profile、task_usage 等核心领域；pg_trgm 扩展用于 issue 标题/描述等字段的模糊搜索索引（如 138_issue_title_trgm_index.up.sql），与"PostgreSQL 17（pgcrypto + pg_trgm）"的说明吻合；
• 任务下发链路：Go 后端经 WebSocket 把 task 下发给守护进程（server/internal/daemonws/、server/internal/realtime/），守护进程运行在用户机器上，"紧挨着你的代码"拉起对应的智能体 CLI 执行——这正是"代码不出门"架构承诺的实现路径。

六、本地开发与贡献流程

README"开发"章节完整继承如下：

环境要求： Node.js 22、pnpm 10.28.2、Go 1.26.6、Docker。

make dev

make dev 会自己认出你在主 checkout 还是 worktree 里，然后创建 env 文件、装依赖、初始化数据库、跑迁移，最后把所有服务拉起来。想参与贡献，先看 CONTRIBUTING.md；iOS 客户端在 apps/mobile/ 目录。项目"几乎每个工作日都发版"，记得常拉最新代码。

源码视角：make dev 背后做了什么

scripts/dev.sh 揭示了完整引导链，也解释了 README 那句"认出主 checkout 还是 worktree"的机制：

1. 前置检查：逐个探测 node、pnpm、go、docker 是否存在，缺失时报出具体清单并退出（第 7–18 行）；
2. worktree 检测：在 git worktree 中 .git 是一个文件而非目录，脚本据此选用 .env.worktree 并调用 scripts/init-worktree-env.sh 生成带唯一数据库名和端口的 env 文件；主 checkout 则从 .env.example 复制出 .env（第 21–34 行）；
3. 装依赖：node_modules 不存在时执行 pnpm install；
4. 数据库：scripts/ensure-postgres.sh 确保 PostgreSQL 就绪（共享 Docker 容器，主 checkout 与 worktree 共用），随后 go run ./cmd/migrate up 跑全部迁移；
5. 启动服务：并发拉起 server（Go 后端，默认 http://localhost:8080）与 pnpm dev:web（前端，默认 http://localhost:3000）。

Makefile 还提供了更细粒度的动词：make setup / make start / make stop（安装依赖、跑迁移、启停前后端）、make check（typecheck + TS 测试 + Go 测试 + Playwright E2E 全流水线，见 scripts/check.sh）、make test（先确保目标库存在并应用迁移，再以 --race 跑 Go 测试）、make db-reset（仅对本地库生效，远程 DATABASE_URL 会直接拒绝）、make up C=api,web,daemon（按组件选择，还支持 Electron 桌面端组件）、make multica ARGS=...（直接从 Go 源码树运行 CLI，-ldflags 注入 version/commit/date）。E2E 测试用例位于 e2e/ 目录，由 playwright.config.ts 驱动。

七、为什么叫 Multica 与开源协议

Multiplexed Information and Computing Agent——向 Multics 致意。那是 20 世纪 60 年代的操作系统，首创了分时：多个人共享同一台机器，却又都像独占它一样。

Multica 团队认为，智能体让"分时"重新成立了——只不过这一次，系统里被多路复用的"用户"，既是人，也是机器：软件团队不再天然是"一个工程师、一个任务、一次一个上下文切换"，小团队不该因为人少就只能干出小团队的量。更长的论证见 VISION.zh.md。

协议方面：LICENSE 为 Multica License——Apache License 2.0 全文并入，外加针对托管服务、商业嵌入和品牌标识的附加条件；自部署、改代码、在它之上做东西都可以。署名信息见 NOTICE。

八、延伸阅读索引

README 的"我想……从这里看"表格是官方推荐的文档入口，其中仓库内文档的对应关系（外部在线文档此处仅列出主题，不在文中给出外链）：

我想……	仓库内对应文档
搞清楚这套系统怎么运转 / 核心概念	在线文档 Concepts、How Multica Works
部署在自己的基础设施上	SELF_HOSTING.md、SELF_HOSTING_ADVANCED.md、SELF_HOSTING_AI.md
用脚本驱动它 / CLI 与守护进程	CLI_AND_DAEMON.md、CLI_INSTALL.md
参与贡献	CONTRIBUTING.md
了解愿景与命名由来	VISION.zh.md、VISION.md
安装 CLI（shell 脚本）	scripts/install.sh、scripts/install.ps1

总结

Multica 的核心价值可以浓缩为三点：智能体即队友（统一命名、上板、被分配、被审计，与人同权同流）、运行时即你的机器（守护进程本地拉起 23 种 CLI，代码不出门，换提供方零迁移成本）、验收权在人（任务必经"审核中"，任何变更不点头不上线）。技术上它是一个结构清晰的 monorepo：Next.js 16 前端 + Go 1.26/Chi/WebSocket 后端 + PostgreSQL 17 + 本地守护进程，185 个数据库迁移和持续追加的 runtime_profile 迁移链证明了其高速迭代节奏。无论你是想自部署一套"AI 同事"工作区，还是研究多智能体任务编排的工程实现（运行时协议家族分层、fail-closed 的后端解析、模型发现降级、worktree 隔离的开发环境），这个仓库都提供了完整的、可直接对照源码阅读的参考实现。