跳到主要内容

附录 A：源码导航与阅读路线

A.1 先建立五层目录地图​

multica-0.4.10/
├── server/
│   ├── cmd/                 # Server、CLI、Migration、Backfill 入口
│   ├── internal/            # 私有控制平面与 Daemon 实现
│   ├── pkg/                 # Agent、Protocol、DB、Redaction 等可复用包
│   └── migrations/          # PostgreSQL 演进历史
├── packages/
│   ├── core/                # Headless API、Query、Store、Schema、Realtime
│   ├── ui/                  # 无业务 Core 依赖的视觉 Primitive
│   └── views/               # 跨 Web/Desktop 共享业务 View
├── apps/
│   ├── web/                 # Next.js Host
│   ├── desktop/             # Electron Host + Daemon 管理
│   ├── mobile/              # 独立 Expo/React Native 实现
│   └── docs/                # 产品文档站
├── deploy/helm/multica/     # Kubernetes Chart
├── .github/workflows/       # CI/Release
├── Dockerfile*              # Backend/Web Image
└── docker-compose*.yml      # 本地与 Self-host

阅读时先判断问题属于：

  • 控制平面；
  • 执行平面；
  • 交互平面；
  • 外部集成；
  • 运维平面。

否则很容易在同名的 Task、Session、Runtime、Message 间来回跳。

A.2 最短架构阅读路线​

第一次只读这些文件：

  1. README.md：产品表面与启动方式；
  2. server/cmd/server/main.go：Server 组合根；
  3. server/cmd/server/router.go：Middleware、Handler 与 Route；
  4. server/internal/service/task.go：任务状态机；
  5. server/internal/daemon/daemon.go：本地执行主循环；
  6. server/pkg/agent/agent.go：Provider 抽象；
  7. packages/core/api/client.ts：前端 HTTP 边界；
  8. packages/core/realtime/use-realtime-sync.ts：前端事件一致性；
  9. packages/views/issues：共享业务 UI；
  10. apps/web/app/[workspaceSlug]：Route-driven Host。

这条路线先建立控制流，再补数据模型。若先从 262 个 Migration 逐个读，成本很高且缺少产品语义。

A.3 Server 启动问题看哪里​

问题首要文件关键内容
Server 启动了什么cmd/server/main.goPool、Redis、Bus、Worker、Shutdown
Route 在哪里注册cmd/server/router.goChi Route Group 与 Handler Wiring
Health 为何失败cmd/server/health.goDB Ping、完整 Migration Set
DB Pool 为什么慢cmd/server/dbstats.goPool 参数与周期统计
Runtime 被标离线cmd/server/runtime_sweeper.goHeartbeat/Liveness 与 Sweeper
Migration 卡住cmd/migrate/main.goAdvisory Lock、Hook、执行顺序
配置来自哪里docker-compose.selfhost.yml主要环境变量与默认值

A.4 认证与 Workspace 问题看哪里​

问题首要文件
JWT/PAT/Task Token 分流middleware/auth.go
Daemon Token 与兼容路径middleware/daemon_auth.go
Workspace Slug/ID 优先级middleware/workspace.go
Token 生成与 Hashauth/jwt.go
Cookie 与登录handler/auth.go
PAT 缓存internal/auth
Owner/Human Actor Guardhandler/actor_guards.go
Rate Limit/代理 IPmiddleware/ratelimit.go

排障时同时记录 Token Prefix、Auth Path、Workspace ID 与 Actor Source。只说“401”信息不足。

A.5 Issue、Comment 与触发问题看哪里​

问题首要文件搜索词
Issue CRUD/Assignmenthandler/issue.goCreateIssue、Assign、shouldEnqueue
Comment 创建与回复handler/comment.goCreateComment
Mention 解析handler/comment.gocomputeCommentAgentTriggers
Mention 权限handler/comment.gocanInvokeAgent
线程 Root/Replyqueries/comment.sqlGetThreadRoot
Issue Serviceservice/issue.goEnqueueTask
Trigger Outcome UIcore/issuestrigger outcome

先确认 Comment 是否已写库，再确认 Trigger Outcome。不要把“评论成功”与“Agent 入队成功”当同一个状态。

A.6 Task 卡住看哪里​

queued​

dispatched​

running​

terminal 但投影异常​

A.7 Daemon 启动与 Runtime 问题看哪里​

问题首要文件
配置默认/Envdaemon/config.go
Daemon 构造与 Rundaemon/daemon.go
Runtime 注册/重注册daemon/daemon.go
API Clientdaemon/client.go
WS Controldaemon/wakeup.go
Reconciledaemon/reconcile.go
本地健康端点daemon/health.go
自更新daemon/auto_update.go
磁盘统计/GCdaemon/diskusage.go、daemon/gc.go

A.8 执行环境问题看哪里​

子问题文件
Fresh Prepare/Reuseexecenv/execenv.go
可杀死 Helperexecenv/isolation.go
Task Env/Markerexecenv/context.go
Sidecar 清理execenv/sidecar_manifest.go
Runtime 指令文件execenv/runtime_config.go
Codex HOMEexecenv/codex_home.go
Codex Sandboxexecenv/codex_sandbox.go
Hermes HOMEexecenv/hermes_home.go
OpenClaw Configexecenv/openclaw_config.go
Repo Cachedaemon/repocache

任何“Cleanup”代码都要先分清 Managed Environment 与 Local Directory，后者必须保留用户内容。

A.9 增加或修复 Provider 看哪里​

入口是 pkg/agent/agent.go 的 Backend Factory。

当前 Provider 文件通常按名称分开：

扩展时还要同步：

  • Model Listing：models.go；
  • Thinking 映射：thinking.go；
  • Daemon Binary Discovery/Version；
  • Provider HOME/Skill/MCP；
  • Prompt 走 stdin 还是 argv；
  • Windows Launcher；
  • Protocol Fixture 与 Terminal Error；
  • Frontend Provider Schema/Icon。

A.10 Context、Prompt 与 Session 看哪里​

问题文件
Claim Payload 字段daemon/types.go
Opening Promptdaemon/prompt.go
Task Snapshot 组装handler/daemon.go
Prior Session 查询queries/agent.sql
Session Poisondaemon/poisoned.go
Thread Namedaemon/thread_name.go
Agent Templateinternal/agenttmpl

Prompt Bug 常常不是字符串问题，而是 Claim Payload 缺字段、Resume 选错 Session 或 Context Snapshot 时机错误。

A.11 Skill、MCP 与 Connected App 看哪里​

子系统文件
Skill CRUD/Importhandler/skill.go
Archive Importhandler/skill_import_archive.go
Skill Bundle Wirepkg/skillbundle
Daemon Skill Cachedaemon/skill_cache.go
Runtime Local Skilldaemon/local_skills.go
Runtime MCPdaemon/runtime_mcp.go
Connected App Schemaruntimeapps
Composio Adapterintegrations/composio

A.12 Realtime 与缓存问题看哪里​

Server​

Frontend​

查缓存 Bug 时同时检查 Event Payload 是否携带 Workspace/Issue/Chat Session ID，以及 Query Key 是否包含 Workspace Namespace。

A.13 Web、Desktop、Mobile 问题看哪里​

Web​

Desktop​

Mobile​

Mobile 不是直接复用 Views：

修改共享 API Contract 时必须分别检查 Core Schema 与 Mobile Schema。

A.14 Chat、通知与外部渠道看哪里​

子系统文件
Chat API/Projectionhandler/chat.go
Chat SQLqueries/chat.sql
Inboxhandler/inbox.go
Notification Listenercmd/server/notification_listeners.go
Channel Engineintegrations/channel
Slackintegrations/slack
Lark/Feishuintegrations/lark
Channel SQL/Dedupqueries/channel.sql
CLI Chat Readcmd_chat.go

外部消息丢失优先沿 Message ID → Dedup Claim → Identity Binding → Chat Message → Debounced Trigger → Task 查。

A.15 Squad 看哪里​

调试协作循环时保留 Leader Task、Worker Task、Trigger Comment、Source Task 与 Deferred Escalation 的所有 ID。

A.16 Autopilot 与 Webhook 看哪里​

Webhook 返回 Accepted 只表示 Admission/Run 已持久化；Delivery Worker 与实际 Task仍可能随后失败。

A.17 GitHub/VCS 看哪里​

GitHub App​

Token-based VCS​

查 PR 状态倒退时比较 Provider Event Timestamp、持久 Row Updated At 与 Monotonic Upsert 条件。

A.18 CLI 问题看哪里​

任务内 CLI 身份问题重点看 newAPIClient、resolveToken、resolveWorkspaceID 与 Daemon Task Marker。

A.19 数据库演进怎么读​

推荐顺序：

  1. pkg/db/queries：先从业务 Query理解当前访问模式；
  2. pkg/db/generated/models.go：看当前 Row Shape；
  3. migrations：只追相关表的演进；
  4. 对照 Handler/Service 的事务边界；
  5. 最后看 Test Fixture。

不要从旧 Migration中的外键/级联规则直接推断当前新表规范；仓库约束明确要求新设计减少数据库 FK/Cascade，由 Service 维护跨域一致性。

A.20 测试与部署看哪里​

问题文件
本地总入口Makefile
Go Test Wrapperscripts/test-go.sh
Web/Go CI.github/workflows/ci.yml
Mobile CI.github/workflows/mobile-verify.yml
Release.github/workflows/release.yml
Composedocker-compose.selfhost.yml
Helmdeploy/helm/multica
Metricsinternal/metrics

A.21 实用搜索命令​

在 multica-0.4.10 根目录运行：

# 找一个 HTTP Route 的注册与 Handler
rg -n '"/api/.+keyword|func \(h \*Handler\).*Keyword' server

# 找一个事件的生产者与消费者
rg -n 'task:completed|EventTaskCompleted' server packages apps

# 找一个数据库 Query 的定义与调用
rg -n 'CreateAgentTask|ClaimAgentTask' server/pkg/db/queries server/internal

# 找状态写入
rg -n "status = 'running'|Status:.*running|EventTaskRunning" server

# 找全部环境变量
rg -o 'os\.Getenv\("[A-Z0-9_]+"\)|os\.LookupEnv\("[A-Z0-9_]+"\)' server \
  | sort -u

# 找 Provider 分支
rg -n 'provider ==|switch provider|case "codex"|case "claude"' server/internal/daemon server/pkg/agent

# 找 Frontend Query Key 与失效点
rg -n 'queryKey:|invalidateQueries|setQueryData' packages/core

# 找跨 Workspace 风险点
rg -n 'WorkspaceID|workspace_id|X-Workspace' server/internal/handler server/internal/service

# 找并发所有权语句
rg -n 'FOR UPDATE|SKIP LOCKED|advisory_lock|claim_token|lease' server

# 找输入长度限制
rg -n 'MaxBytesReader|LimitReader|max.*Bytes' server/internal/handler

A.22 一次代码改动的追踪模板​

若要增加一个业务字段：

Migration
  → sqlc Query / Generated Model
  → Handler Request/Response
  → Service Transaction/Event
  → Protocol Event Payload
  → Core Zod/Type
  → Query Key/Mutation/Realtime
  → Shared View
  → Web/Desktop Host
  → Mobile 独立 Schema/Screen
  → CLI（若暴露）
  → Tests/Docs

若要增加一个任务能力：

Agent/Runtime 配置
  → Task 入队快照
  → Claim Response
  → daemon.Task
  → ExecEnv Materialization
  → Prompt/Provider Args
  → Message/Usage/Terminal
  → UI/CLI

中间任何一层遗漏，常见结果是“配置能保存但运行看不到”或“Server发了字段但旧客户端解析丢失”。

A.23 推荐专题路线​

后端开发者​

01 → 03 → 04 → 05 → 06 → 12 → 20 → 21。

Daemon/Provider 开发者​

01 → 06 → 07 → 08 → 09 → 10 → 11 → 19 → 21。

前端开发者​

02 → 04 → 05 → 12 → 13 → 14 → 15 → 21。

平台/SRE​

03 → 04 → 06 → 07 → 12 → 17 → 20 → 21。

集成开发者​

04 → 05 → 11 → 12 → 15 → 17 → 18 → 20。

多 Agent 工作流开发者​

05 → 06 → 10 → 16 → 17 → 21。

A.24 阅读源码时的五个防误判提示​

  1. 目录标签与 package version不同：本快照目录是 0.4.10，根 package.json 仍是 0.2.0。
  2. Task、Session、Chat Session不同：先看字段归属。
  3. Event 不等于事实源：事件可能重放、丢失或乱序。
  4. Provider 能力不完全对称：同一 Backend Interface 后仍有协议分支。
  5. Mobile 不是 Core/Views 的薄 Host：API Contract变更需要单独更新。

附录 B 将这些对象、状态和不变量压成速查表。