00-index

Multica 学习文档索引

这组文档用于快速建立 /Users/bytedance/proj/multica-main 的代码地图。项目本身已经有 .codegraph/ 索引，后续排查代码时优先用 codegraph explore "<问题或符号>" 和 codegraph node <文件或符号>，再补充读取源码。

推荐阅读顺序

1. 01-project-overview 先看产品定位、monorepo 结构、技术栈、主要目录和工程规则。

2. 02-backend-architecture 理解 Go API 服务如何启动、路由如何分组、Handler/Service/sqlc/事件总线如何协作。

3. 09-backend-technical-deep-dive 面向后端学习的技术细拆：认证、workspace 隔离、router/handler/service/sqlc、task 状态机、daemon 执行、WebSocket/Redis relay、调度和排障。前端只覆盖 HTTP/WS 契约。

4. 03-frontend-architecture 可选阅读。你关注后端时，只需要看其中 API client、WebSocket client、Realtime cache 同步这些和后端契约强相关的部分。

5. 10-agent-development-design 以后端 Agent 开发为主线，理解 Agent 配置、runtime 绑定、task 入队、daemon claim、execenv、provider backend、MCP/custom env、安全边界和扩展点。

6. 11-codex-provider-flow 以 Codex 为具体 provider 例子，拆解 codex app-server、per-task CODEX_HOME、MCP 写入 config.toml、thread/resume、turn/start、消息映射、usage 和结果回写。

7. 12-codex-prompt-result-node-flow 用节点图串起真实用户评论、comment/task 落库、prompt 包装、turn/start、Codex 事件流、task_message、issue 评论和 task complete 的完整数据形态。

8. 13-codex-json-node-graph 一张 Mermaid 图，把用户输入、server 路由、task、daemon、Codex JSON-RPC、CLI 回帖、兜底评论这些节点都画成可读 JSON 块，适合复盘“一个 prompt 最终怎么变成结果”。

9. 04-data-events-and-realtime 理解数据库、sqlc、事件总线、WebSocket 和 Redis relay。

10. 14-agent-prompts-catalog 分类整理代码里写出来、会进入 agent 运行上下文的 prompt / instruction：本轮 BuildPrompt、AGENTS.md / CLAUDE.md runtime brief、.agent_context、squad briefing、内置 skills、provider 包装、agent 模板和 onboarding 种子 issue prompt。

11. 15-squad-child-issue-lifecycle 以 squad 的 child issue 主线拆解：leader 创建 staged child issues、teammate 执行、写回 DB、stage barrier 唤醒 leader、leader 推进下一阶段，以及这条链路中的 session 复用规则。

12. 16-agent-workdir-worktree-git-collaboration 专门拆解 agent 执行目录、Git worktree、独立分支、commit/push/PR、issue comment 和 local_directory 例外，避免把 workdir、worktree、branch、PR 混成一个概念。

13. 05-agent-runtime-and-cli 理解 CLI、daemon、本地 agent runtime、任务 claim/start/progress/complete/fail 的主链路。

14. 06-product-model-from-docs-site 从官方中文文档站提炼产品模型：工作区、issue、agent、runtime、task、skill、squad、autopilot、集成，以及对应源码入口。

15. 07-end-to-end-flows-with-examples 用 acme-ai / CodeSmith / ACME-42 / task_9001 这组锚点数据串起分配、@、chat、autopilot、project resource、squad、skill、GitHub、飞书等端到端链路。

16. 08-ops-auth-integrations-and-troubleshooting 理解 Cloud/Self-host、认证与 token、关键环境变量、WebSocket/daemon 排障、GitHub/Lark/Autopilot webhook 集成。

17. 17-diagrams 集中查看框架图、组件图、数据关系图、请求链路图、任务执行时序图等 Mermaid 图。

一句话心智模型

Multica 是一个人类 + AI agent 协作的任务管理平台：

• 用户在 Web/Desktop/Mobile 或 CLI 创建/更新 issue、agent、project、skill、autopilot。
• Go 后端用 Chi 暴露 API，用 sqlc 访问 PostgreSQL，用事件总线产生 activity/inbox/realtime 副作用。
• 前端通过 @multica/core 的 API client、React Query hooks 和 Zustand stores 访问数据。
• 本地 daemon 注册为 runtime，轮询或被 WS 唤醒后 claim task，再调用 Claude/Codex/OpenCode 等 agent CLI 执行任务，并把进度和结果回报给后端。
• WebSocket 将 issue/task/chat/inbox 等事件推送给在线客户端，客户端主要通过 Query cache patch/invalidate 自愈。
• Agent 系统的窄腰是 agent_task_queue：所有触发入口先变成 task，daemon claim 后再把 Agent 配置、workspace/project/context、skills、MCP、custom env 和 task token 组装成一次 provider 执行。

最常用源码入口

关注点	入口文件
API 服务启动	server/cmd/server/main.go
HTTP 路由总表	server/cmd/server/router.go
Handler 聚合结构	server/internal/handler/handler.go
任务服务	server/internal/service/task.go
Issue 服务	server/internal/service/issue.go
Autopilot 服务	server/internal/service/autopilot.go
事件总线	server/internal/events/bus.go
Realtime Hub	server/internal/realtime/hub.go
Daemon 主循环	server/internal/daemon/daemon.go
Agent CLI 统一接口	server/pkg/agent/agent.go
CLI 入口	server/cmd/multica/main.go
sqlc 查询	server/pkg/db/queries/*.sql
sqlc 生成代码	server/pkg/db/generated/*.go
Next.js 根布局	apps/web/app/layout.tsx
Workspace 布局	apps/web/app/[workspaceSlug]/layout.tsx
Dashboard 布局	apps/web/app/[workspaceSlug]/(dashboard)/layout.tsx
Electron renderer	apps/desktop/src/renderer/src/App.tsx
Desktop 路由	apps/desktop/src/renderer/src/routes.tsx
API client	packages/core/api/client.ts
WebSocket client	packages/core/api/ws-client.ts
Realtime cache 同步	packages/core/realtime/use-realtime-sync.ts

学习时优先追的几条主线

• 用户请求：App/Web/Desktop -> packages/core/api -> server/cmd/server/router.go -> handler -> service/sqlc -> events.Bus -> WS
• Agent 执行：issue/comment/assign/autopilot -> TaskService enqueue -> daemon claim -> agent.Backend.Execute -> daemon report -> TaskService terminal side effects
• 实时同步：handler/service Publish -> registerListeners -> realtime.Hub/Redis relay -> WSClient -> useRealtimeSync -> React Query cache
• 数据变更：migration -> pkg/db/queries/*.sql -> sqlc generated -> handler/service call
• 产品语义：先看官方文档源 apps/docs/content/docs/*.zh.mdx，再用 learning-doc/06 和 learning-doc/07 把概念映射到代码。