Multica架构源码解析:Go后端、Next.js前端与本地Daemon三角如何协作调度AI Agent
Multica架构源码解析:Go后端、Next.js前端与本地Daemon三角如何协作调度AI Agent
Multica 是一个开源、可自托管的 AI Agent 协作工作区:你可以像给同事派活一样把 Issue 指派给 AI 编程 Agent。本文带你拆解 Multica 的源码架构——Go 后端、Next.js 前端与本地 Daemon 这三块是如何协作完成 AI Agent 的任务调度、执行与结果回写的,帮助新手快速建立对 Multica 整体架构的认知。
一、三分钟看懂 Multica 架构全景
Multica 的架构可以用一张图概括:Web / 桌面 / 移动端三种客户端 → Go 后端(Chi 路由 + WebSocket)→ PostgreSQL 17,后端再通过 WebSocket 指挥运行在你机器上的 Agent Daemon,由它真正启动 Claude Code、Codex 等 AI CLI 干活。
| 层 | 技术栈 | 源码位置 |
|---|---|---|
| Web 前端 | Next.js 16(App Router) | apps/web/ |
| 桌面端 | Electron(复用 Web UI 包) | apps/desktop/ |
| 移动端 | Expo / React Native | apps/mobile/ |
| 后端 | Go(Chi、sqlc、gorilla/websocket) | server/ |
| 数据库 | PostgreSQL 17(pgcrypto + pg_trgm) |
server/migrations/ |
| Agent 运行时 | 本地 Daemon,驱动 26 种 Agent CLI | server/internal/daemon/ |
二、Go 后端:API、WebSocket 与数据层
后端全部代码位于 server/,依赖管理见 server/go.mod,主要分三块:
1. HTTP API 服务
- 入口在 server/cmd/server/main.go,路由定义集中在 server/cmd/server/router.go,涵盖附件下载、Autopilot webhook、GitHub webhook、Slack/飞书等 IM 频道绑定等端点。
- 业务处理逻辑集中在 server/internal/handler/(400+ 个文件),领域服务位于 server/internal/service/。
2. 实时通道:两套 WebSocket Hub
- 面向浏览器的实时广播在 server/internal/realtime/hub.go,支持 Redis relay 实现多实例水平扩展(见 server/internal/realtime/redis_relay.go)。
- 面向本地 Daemon 的长连接在 server/internal/daemonws/hub.go,是后端"指挥"你电脑上 Agent 执行任务的主干道。
3. 数据库迁移
server/migrations/ 下有 158 个迁移文件,从 001_init 到 158_agent_task_queue_chat_input_task_id,完整记录了 Issue、Agent、任务队列(agent_task_queue)、Chat、Autopilot、Squad 等数据模型是如何逐步演进的——这是理解 Multica 数据模型最快的路径。
三、Next.js 前端:一次开发,三端共享
Multica 前端最值得关注的设计是**「共享包 + 多端壳」**模式:
packages/ ← 共享层(业务逻辑 + UI 组件)
├── core/ 业务逻辑包:issues、agents、chat、runtimes、realtime 等 60+ 模块
├── ui/ 基础 UI 组件
└── views/ 页面级视图(Issues、Agents、Chat、Settings…)
apps/
├── web/ Next.js 16 网站(App Router + 页面 API 代理)
├── desktop/ Electron 壳,直接复用 packages/views 的 UI
└── mobile/ Expo / React Native 壳
- 共享类型与 API 客户端:packages/core/ 中的 packages/core/api/、packages/core/issues/、packages/core/agents/。
- 桌面端构建配置:apps/desktop/electron.vite.config.ts、打包规则见 apps/desktop/electron-builder.yml。
- Web 端代理层:apps/web/proxy.ts。
也就是说,Electron 和手机 App 里看到的界面,和浏览器里是同一套 React 组件,这正是它"同一工作区,多端一致"体验的来源。
四、本地 Daemon:任务调度的真正执行者
Multica 自己不内置任何大模型,而是驱动你机器上已安装的 Agent CLI(Claude Code、Codex、Cursor 等 26 种)。桥梁就是 Daemon——一个由 multica CLI 启动的本地守护进程。
启动与注册
multica setup # 一条命令:配置 + 登录 + 启动 daemon
Daemon 的核心逻辑在 server/internal/daemon/daemon.go,Run 主循环位于 server/internal/daemon/daemon.go#L2075。它会:
- 探测本机 Agent CLI:server/internal/daemon/agents_probe.go 扫描 PATH,识别各家 CLI 及版本;
- 向服务器注册 Runtime:通过 WebSocket 上报"这台机器上有哪些 AI 可用",代码在 server/internal/daemon/daemon.go 的注册/重注册逻辑中;
- 拉取并执行任务:收到后端下发的 Task 后,由 server/internal/daemon/client.go 走批量 claim 协议领任务,再
fork/exec启动对应 Agent CLI。
完整使用文档见 CLI_AND_DAEMON.md(含认证、Token、日志、自动更新等细节)。
💡 安全模型的关键点:你的代码从不离开这台机器——Daemon 只把任务描述发上去,把执行过程与结果流式传回。
五、一次 AI Agent 任务的完整调度链路
把前后端拼起来,一条 Issue 从指派到交付的完整链路是:
- 触发:Issue 指派给 Agent、@mention、Chat 消息或 Autopilot 定时任务,都会在
agent_task_queue表中入队(建表见 server/migrations/004_agent_runtime_loop.up.sql)。 - 下发:后端 daemonws Hub 通过 WebSocket 通知对应 Runtime,Daemon 领走任务。
- 执行:Daemon 启动目标 Agent CLI,在它的工作目录中读写代码;每一步(Bash 命令、文件编辑、工具调用)都带时间戳回传。
- 回写:执行日志写入 Issue 时间线,完成后 Issue 自动移入 Review 列——合不合入,由人说了算。
任务失败重试、租约(lease)、超时控制等机制,可以在 server/internal/service/ 与 server/migrations/055_task_lease_and_retry.up.sql 中找到对应实现。
六、值得继续深挖的源码入口清单
| 想了解 | 从这里开始 |
|---|---|
| 后端路由与 API | server/cmd/server/router.go |
| 任务队列数据模型 | server/migrations/ 中带 task_queue 的迁移 |
| Daemon 生命周期与注册 | server/internal/daemon/daemon.go |
| 浏览器实时推送 | server/internal/realtime/hub.go |
| 前端共享业务逻辑 | packages/core/issues/ |
| 桌面端打包 | apps/desktop/electron-builder.yml |
| 本地部署 | docker-compose.selfhost.yml、SELF_HOSTING.md |
| Helm 部署(K8s) | deploy/helm/multica/ |
# 本地跑起整个开发环境(Node 22 + pnpm 10 + Go 1.26 + Docker)
git clone https://gitcode.com/GitHub_Trending/mu/multica
cd multica
make dev
结语
Multica 的架构精髓在于**「控制面与执行面分离」**:Go 后端只负责记录与协调(Issue、任务队列、实时通知),真正消耗算力的 AI 执行发生在你的本地 Daemon 上,通过 WebSocket 长连接双向贯通;Next.js 前端则以共享包模式横跨 Web、桌面、移动端三种壳。这种三角协作模型既保证了代码不出本机,又让 AI Agent 获得了"像同事一样接活、汇报、交付"的完整体验。顺着本文的目录清单读下去,你可以在一个下午内摸清 Multica 的骨架。




