multica-runtimes-and-repos

Multica 运行时与仓库

快速开始

如果遇到 "agent 未运行" 或 "仓库检出失败"，在做出任何更改之前，先阅读调用链：

multica agent get <agent-id> --output json
multica runtime list --output json
multica repo checkout <repo-url>

运行时和仓库命令会影响正在执行的 Agent。不要仅仅为了测试就重启守护进程、更新运行时或检出任意仓库。

核心模型

运行时是 Agent 背后的执行目标。守护进程拥有本地运行时进程，并从服务器领取排队中的任务。

调用链如下：

1. 用户操作创建或更新一行 agent_task_queue；
2. 该任务指向一个 Agent 和一个运行时；
3. 服务器尽可能通过守护进程 websocket 唤醒运行时；
4. 守护进程轮询/领取该任务；
5. 服务器返回任务上下文、仓库、项目资源、先前会话/工作目录提示以及任务令牌；
6. 守护进程准备工作目录并启动提供商 CLI；
7. multica repo checkout 与本地守护进程通信，而非直接与 GitHub 通信。

CLI

multica runtime list --output json
multica runtime usage <runtime-id> --output json
multica runtime activity <runtime-id> --output json
multica runtime update <runtime-id> --target-version <version> --output json
multica runtime delete <runtime-id>
multica repo checkout <url>
multica repo checkout <url> --ref <branch-or-sha>

runtime update 和 runtime delete 是写操作。启动运行时更新仅限其所有者或工作区所有者/管理员；如果原始发起者的管理员角色发生变化，他们可以继续轮询该特定的进行中请求。runtime delete 会移除运行时注册；如果仍有活跃 Agent 绑定，它会拒绝执行，除非用户显式传入 --cascade，这会先解绑那些 Agent 并取消其排队中/运行中的任务，然后再删除运行时。解绑会保留 Agent 及其拥有的一切——指令、技能、对话、标签、频道安装、自动驾驶和任务历史——仅清除 agent.runtime_id；被解绑的 Agent 无法运行，直到它再次绑定到某个运行时（multica agent update <id> --runtime-id <runtime-id>），并且每条触发路径都会以 agent_runtime_required 拒绝它。repo checkout 会在任务工作目录中创建一个专用分支。大多数运行时使用链接工作树；Linux 和 Windows Codex 使用任务本地 Git 元数据，这样任务可以在不使共享 .repos 缓存可写的情况下进行暂存和提交。

repo checkout 需要同时具备 MULTICA_DAEMON_PORT 和注入的任务级 MULTICA_TOKEN；它旨在从活跃守护进程任务内部、并在该任务的工作目录（或其子目录）中运行。本地守护进程会根据其活跃任务注册表对令牌进行认证，自行推导工作区/任务/Agent 身份，并拒绝调用方提供的、位于该任务之外的工作目录。如果任一变量缺失，说明你不在正常的 Agent 检出路径中。当项目 github_repo 资源的 resource_ref.ref 存在时，repo checkout <url> 会默认使用该 ref 作为当前任务的目标；显式的 repo checkout <url> --ref <branch-or-sha> 会覆盖它。

任务 CLI 边界

守护进程会为 Multica API 命令注入一个任务范围的 mat_ 凭据，以及一个任务私有的本地 Multica 配置根目录。在该受管任务上下文中：

• 诸如 issue list、issue get 和 issue runs 之类的 API 命令使用注入的任务身份，绝不会回退到守护进程 Owner 保存的 Multica 配置文件。
• config show 和 config set 仅作用于任务本地的 Multica 状态。缺少任务配置根目录时会失败关闭。
• auth status 可以验证任务身份，但会在其输出中省略所有令牌材料。
• daemon status 和 daemon disk-usage 报告承载此任务的运行时：status 探测守护进程注入的健康检查端口，disk-usage 扫描守护进程注入的工作区根目录。两者都拒绝 --profile，disk-usage 还拒绝 --all-profiles 和 --workspaces-root，并且其 STATUS 列保持空白，因为填充它会消耗 Owner 的凭据。
• 人类/本地配置文件及守护进程命令 —— 包括 login、logout、setup、workspace switch、本地运行时配置文件路径变更、daemon start / stop / restart、daemon logs 和 daemon probe-runtimes —— 均不可用。尤其是 daemon stop 会终止运行此任务及其上每个同级任务的守护进程。

仅 MULTICA_DAEMON_PORT 本身是一个弱信号，用于纵深防御的任务安全 API 和配置文件解析，并不能作为拒绝人类/本地命令的任务身份。真正的任务还会携带 MULTICA_AGENT_ID / MULTICA_TASK_ID、MULTICA_TASK_CONFIG_ROOT 或守护进程管理的工作目录标记。当端口是唯一信号时，daemon status 使用所选主机配置文件推导出的健康检查端口；普通的 API 和解析配置文件的命令仍会失败关闭。主机操作员不应导出 MULTICA_DAEMON_PORT；守护进程会从所选配置文件推导其主机健康检查端口，并自行将该变量注入任务。

守护进程仍会为诸如 gh、aws、kubectl 和 npm 等提供商工具保留真实的 HOME 和 XDG 变量。这是 CLI 解析加固，而非硬性文件系统保密：同一 OS 用户下的进程仍可打开明确已知的 Owner 路径。要实现更强的隔离，需要专用的 Unix 用户、容器、虚拟机或等效的 OS 边界。

调试未能运行的 Agent

按此顺序检查：

1. 是否本应创建一个任务？检查 issue/comment/autopilot 上下文。
2. 负责人是 Agent 还是小队？小队会路由到其队长。
3. Agent 是否已归档，或绑定到执行者无法使用的运行时？
4. 运行时是否在线？multica runtime list --output json。
5. 守护进程最近是否发送过心跳？运行时 last_seen_at 是可见的线索。
6. 任务是否已被认领，还是卡在 pending/running/等待本地目录状态？
7. 如果仓库检出失败，请在检查任务/项目上下文中是否存在仓库上下文后对其进行分类。

仓库

运行时简报列出了此任务可用的仓库。除非用户明确要求绑定新的项目资源，否则将该列表视为 Agent 检出的权威依据。

工作区仓库和项目资源不是一回事：

• 工作区仓库元数据可以出现在工作区上下文中；
• github_repo 项目资源是持久的项目上下文，可能影响未来的任务；可选的 resource_ref.ref 会为该项目中任务的默认检出 ref 固定版本；
• local_directory 资源指向守护进程拥有的路径，并带有本地机器的假设。

不要仅仅因为 repo checkout 失败就添加项目资源。首先要确定用户要求的是持久的项目上下文还是仅仅是一次任务检出。

更多有来源支持的细节：references/runtimes-and-repos-source-map.md。