Multica 核心运行机制

CLI 不是一组孤立命令，而是把外部世界的若干系统 缝合到 Multica 内部状态机的唯一胶水层。 一台机器装一个 multica 二进制 + 一份认证态，就能让本地工具链、Git 仓库、服务端 （云或自建）按统一协议协作。

CLI 承接的五个外部系统

几个关键承接细节

① 用 setup 同一条命令切换"云 / 自建"

multica setup                                # 默认接入 Multica Cloud
multica setup self-host \                    # 接入自建后端
  --server-url https://api.internal.co \
  --app-url    https://app.internal.co \
  --profile    staging                       # profile 隔离多环境

配置写入 ~/.multica/config.json（带 profile 时为 config-{profile}.json）， Token 落 OS keychain。同台机器可以在多个 profile 间切换 —— 日常云、办公自建、客户私有，互不污染。

② Daemon 探测本地 agent 工具链

// 先用 exec.LookPath 快路径
for _, name := range []string{"claude", "codex", "copilot", "gemini",
                              "openclaw", "opencode", "hermes",
                              "pi", "cursor-agent", "kimi", "kiro-cli"} {
    if p, err := exec.LookPath(name); err == nil { detected = append(detected, p); continue }
}
// 失败再走"读 ~/.zshrc / ~/.bashrc"的兜底
// 原因：GUI 启动的进程不继承交互式 shell 的 PATH
// （fnm/nvm/volta/brew 都靠 rc 文件初始化）
resolveAgentsViaLoginShell(...)

③ CLI 还是 agent "回写"的入口

Agent 在 daemon 起的进程里跑完后，可以直接调 multica issue update --status done / multica issue comment add 把结果写回。 服务端通过请求头里的 X-Task-ID + X-Agent-ID 识别是 agent 身份的调用 —— 同一套 CLI，既是用户终端又是 agent 的"回写 SDK"。

Multica 没有内存态调度器，所有状态都落在四张表上，所有转移都是单语句的 UPDATE ... RETURNING。DB 即真理，server 重启 0 影响。

2.1 Task 状态机

关键设计： "失败"是终态，但满足条件的失败会复制一行新任务（attempt+1， parent_task_id 指回上一次），实现轻量重试且历史可追溯。

2.2 失败原因 × 重试策略

重试白名单 retryableReasons 见 service/task.go:1237-1241。 其余失败需要人介入或新 session 重跑。

2.3 Claim 的核心 SQL（最值得看的一段）

多个 daemon 并发抢同一个 agent 的队列，靠 FOR UPDATE SKIP LOCKED 在数据库层做无锁分发； 同时用 NOT EXISTS 子查询实现 per-(agent, issue) 序列化 —— 同一个 (agent, issue) 上不会同时跑两个任务。

UPDATE agent_task_queue
SET status = 'dispatched', dispatched_at = now()
WHERE id = (
    SELECT atq.id FROM agent_task_queue atq
    WHERE atq.agent_id = $1 AND atq.status = 'queued'
      AND NOT EXISTS (
          -- 关键：保证 (agent, issue) 维度串行
          SELECT 1 FROM agent_task_queue active
          WHERE active.agent_id = atq.agent_id
            AND active.status IN ('dispatched', 'running')
            AND (
              (atq.issue_id IS NOT NULL          AND active.issue_id          = atq.issue_id)
           OR (atq.chat_session_id IS NOT NULL   AND active.chat_session_id   = atq.chat_session_id)
           OR (atq.issue_id IS NULL              -- quick-create 任务用全 NULL 去重
               AND atq.chat_session_id IS NULL
               AND atq.autopilot_run_id IS NULL)
            )
      )
    ORDER BY atq.priority DESC, atq.created_at ASC
    LIMIT 1 FOR UPDATE SKIP LOCKED
)
RETURNING *;

两个细节： ① SKIP LOCKED 让多 daemon 抢锁时直接跳过已被别人锁住的行，零等待； ② 同一 (agent, issue) 在 dispatched/running 时新任务无法 claim —— 天然实现"同一 ticket 不会两个任务并发跑"。

2.4 四张表的联动

2.5 超时 / 阈值速查

2.6 任务取消全链路

1. 用户在 UI 点 Cancel → CancelTask（service/task.go:708-731）
2. DB 状态转移：queued / dispatched / running → cancelled
3. Daemon 端 watcher watchTaskCancellation 每秒查 GetTaskStatus
4. 检测到 cancelled → 优雅 kill agent 进程
5. 广播 task:cancelled 事件 → UI 隐藏进度条 + 重算 agent.status

Multica 没有专门的 mention 表，评论正文本身就是协议。 agent 之间互相 @、用户 @ agent、@ squad，统一靠 Markdown 链接里的 schema 解析。 一段评论可能包含若干 mention，每个都可能触发一个新任务 —— 因此防环逻辑是这套机制能不能用的关键。

3.1 @mention 的 Markdown 协议

评论里的所有 mention 都长这样：

[@Alice](mention://member/uuid-of-alice)
[@CodeReviewer](mention://agent/uuid-of-agent)
[@BackendTeam](mention://squad/uuid-of-squad)
[MUL-123](mention://issue/uuid-of-issue)
[@all](mention://all/all)

解析靠一条正则就能拿到全部信息：

type Mention struct {
    Type string // "member" | "agent" | "squad" | "issue" | "all"
    ID   string
}

var MentionRe = regexp.MustCompile(
    `\[@?(.+?)\]\(mention://(member|agent|squad|issue|all)/([0-9a-fA-F-]+|all)\)`,
)

设计取舍： mention 不入独立表，留在评论 content 里动态解析； 评论删除时关联的 task 通过 trigger_comment_id ON DELETE SET NULL 自动断关联。

3.2 评论 → 任务的触发链

3.3 三层防环（最关键的工程细节）

Agent A 评论里 @ Agent B、B 完成后又 @ A —— 如果不防环就是个无限循环。 Multica 把防护拆成三层，每层互不替代：

① 自触发防护

// 评论作者就是被 @ 的那个 agent，直接跳过
if authorType == "agent" && authorID == m.ID {
    continue
}

② Squad Leader 级防环

// 上一个任务已经是 leader 角色，再被 @ 就跳过
// 不然 squad leader 评论后会立刻给自己再派一个 leader 任务
if authorType == "agent" &&
   authorID == uuidToString(squad.LeaderID) &&
   h.lastTaskWasLeader(ctx, issue.ID, squad.LeaderID) {
    continue
}

③ Pending 去重

hasPending, _ := h.Queries.HasPendingTaskForIssueAndAgent(ctx,
    db.HasPendingTaskForIssueAndAgentParams{
        IssueID: issue.ID,
        AgentID: agentUUID,
    })
if hasPending {
    continue  // 该 agent 在这个 issue 上已经有 queued/dispatched/running 任务
}

3.4 Squad Leader 自动充当路由层

@BackendTeam 这种 squad mention 在 enqueueMentionedAgentTasks 里走特殊分支：

if m.Type == "squad" {
    squad, _ := h.Queries.GetSquad(ctx, parseUUID(m.ID))
    leaderID := squad.LeaderID

    // Squad leader 防环：见 3.3 ②
    if authorType == "agent" && authorID == uuidToString(leaderID) &&
       h.lastTaskWasLeader(ctx, issue.ID, leaderID) {
        continue
    }

    // 入队时标记 is_leader_task = true
    h.TaskService.EnqueueTaskForSquadLeader(ctx, issue, leaderID, comment.ID)
    continue
}
if m.Type != "agent" { continue }  // member / issue / all 不直接派任务

补充规则： 一条 member 评论里完全没有 @ 时，会自动触发 squad leader 帮忙分配 —— leader 因此天然成为"如果没人接，我兜底"的路由层。

3.5 端到端例子：用户 → Agent A → Agent B

整条链上没有中心调度器：每一步都是"一条评论 + 解析 + 防环 + 一条 SQL"。 实现简单但很有韧性 —— DB 是唯一真相源，任何环节中断后只要再有评论进来， 链条就能从断点接着走。