# 运行时

Runtimes 是 agentteam 可为智能体运行的 AI coding-agent 实现。`builtin` 是随 AgentTeam Desktop
发布的 AgentTeam-managed OpenCode runtime；OpenCode、Claude Code、Codex、Kimi Code binary 仍作为高级
detect/use/configure 路径保留。Agent 引用 runtime 名称；daemon 会把 Agent 配置转换成
具体 runtime 会话，并注入频道协作所需的本地 MCP bridge 信息。

## 支持类型

runtime 检测按优先级排序：

| Runtime type | 默认 binary | 说明 |
|--------------|-------------|------|
| `builtin` | AgentTeam-managed `opencode` | 随 AgentTeam Desktop 发布；默认参数为 `serve`，健康检查为 `/global/health` |
| `opencode` | `opencode` | OpenCode 路径，来自 PATH 或手动 binary 配置 |
| `claude` | `claude` | Claude Code 交互式 runtime |
| `codex` | `codex` | Codex app-server 集成路径；agentteam 会启动 `codex app-server` 子命令入口 |
| `kimi` | `kimi` | Kimi Code Agent Client Protocol 集成路径；agentteam 会启动 `kimi acp` |
| `pi` | `pi` | Pi RPC 集成路径；agentteam 会启动 `pi --mode rpc` |

runtime 类型校验仍接受 `claude-code` 作为 `claude` 的历史别名；`builtin` 使用 OpenCode driver，但 binary 会从 AgentTeam Desktop artifact 中解析，而不是使用用户安装的 OpenCode。

## 检测

对于内置运行时，resolver 使用 AgentTeam Desktop release artifact 随包发布的 managed binary。
如果 managed OpenCode 缺失、不可执行或与 build-time expected version 不匹配，表示
AgentTeam Desktop 安装不完整。

对于外部 runtime，daemon 可以在 `PATH` 和常见包管理器安装目录中查找默认 binary。
fallback 位置包括 npm prefix 目录、用户 bin 目录、Homebrew 路径，Scoop、Chocolatey、WinGet links 等 Windows package-manager shim 目录，以及 nvm、fnm、Volta、asdf、mise 等常见 Node manager 路径。OpenCode 使用 `opencode` runtime type，也可以通过手动 binary path 选择。Kimi Code 使用 `kimi` runtime type，并且必须提供公开的 `kimi acp` 入口。AgentTeam 启动 Kimi 时会注入智能体已配置的模型 provider，不会调用 Kimi 的交互式登录流程。
在 Windows 上，显式 runtime 检测还会读取用户和系统环境注册表中的 `PATH`，因此新增 runtime 目录后无需重启 AgentTeam Desktop 即可通过重新检测发现。
检测会记录：

- runtime type
- binary 名称
- 解析后的路径
- binary 是否已安装
- binary 是否可作为 AgentTeam 启动候选
- runtime 支持 `--version` 时的版本信息
- setup 未完成时的 reason code 和说明

检测会在启动时运行，dashboard 的 Runtime 管理器也可以按需重新检测。daemon 不再用周期性的 runtime 子进程探测结果持续重建执行注册表，避免瞬时探测失败把可用 agent runtime 驱逐。

Dashboard 会把 runtime 检测状态拆开，而不是把所有非 ready runtime 都显示成未安装。LLM
模型和凭证属于 Agent 配置或专门的 runtime 配置 API，不影响这里的 runtime ready 判断：

| 状态 | 含义 |
|------|------|
| `missing` | 找不到可用 binary，或内置运行时缺失 |
| `unsupported` | 找到了 binary，但缺少必要能力或版本不受支持 |
| `ready` | runtime 已安装且能力满足 |

## Managed 与外部 runtime 策略

AgentTeam Desktop 不再为 OpenCode、Claude Code、Codex、Kimi Code runtime 提供一键安装或升级。
dashboard 和 CLI runtime surface 只负责检测、能力校验、状态展示和修复建议。

以下 runtime installer surface 被有意移除：

- dashboard runtime 安装/升级按钮
- runtime SSE installer endpoint
- runtime install-command endpoint
- `agentteam onboard --runtime` installer 选择
- `agentteam doctor --fix-runtime` 自动安装行为
- 启动路径或 app-build 路径的 OpenCode 自动安装

内置运行时跟随 AgentTeam Desktop 升级。release artifact 必须包含对应平台的 OpenCode 可执行文件；
macOS app bundle 中的 managed 路径示例是
`Contents/Resources/runtimes/opencode/opencode`，非 bundle 布局中可位于 desktop
可执行文件旁的 `runtimes/opencode/opencode`，并在同一个 `runtimes/opencode/`
目录放置 `models.json`。本地 `make build` 也会把同一 managed
runtime 路径放到 `bin/agentteam` 旁用于开发测试；这不表示安装或升级外部 OpenCode runtime。
release build 可以声明 expected OpenCode 版本；版本不匹配会报告为 AgentTeam Desktop 安装不完整。

`agentteam onboard --runtime` 只打印检测状态。`agentteam doctor --fix-runtime` 只打印修复建议。
两者都不会安装外部 runtime。

## Runtime 配置

标准化后的 runtime 记录包含：

| 字段 | 含义 |
|------|------|
| `name` | Agent 引用的 runtime 名称 |
| `type` | 支持的 runtime type |
| `enabled` | runtime 是否可用 |
| `binary` | binary 名称或路径 |
| `args` | 额外进程参数 |
| `port` | runtime 需要端口时使用 |
| `health.path` | 健康检查 endpoint |
| `health.interval` | 健康检查间隔 |
| `health.timeout` | 健康检查超时 |
| `env` | 额外环境变量 |

默认 runtime 记录主要来自检测和 type 默认值。持久化 profile 记录仍可以携带手动
binary path、args、health 设置和环境变量覆盖，用于高级外部 runtime 路径。

对于外部 runtime，AgentTeam Desktop 会从用户 shell 启动环境中采集已 export
的变量，并在启动 runtime 子进程时补进去，前提是 daemon 进程里没有同名变量。
这样 fish、zsh、bash 等 shell 中配置的自定义 LLM 凭证、region、API version、
profile 等参数可以被 runtime 读取。这份 shell 环境只用于 runtime 启动和
runtime `env_key` 解析，不会写回 daemon 进程环境。`PATH` 仍由 runtime
检测和启动路径逻辑单独处理。

权限、skills 和 MCP 设置由 AgentTeam 的 Agent 启动配置组装，并在会话启动时传给 runtime 进程。

## MCP 回环代理处理

当 runtime 通过 `127.0.0.1`、`localhost` 或 `::1` 访问 agentteam 本地 MCP bridge 时，系统 HTTP 代理可能破坏本地流量。`AGENTTEAM_MCP_AGENTTEAMBACK_NO_PROXY` 用来控制回环地址的 `NO_PROXY` 注入：

| 值 | 行为 |
|----|------|
| `auto` | 默认值；仅 MCP endpoint 为本地地址时追加回环 host |
| `on` | 总是追加回环 host |
| `off` | 从不修改 `NO_PROXY` / `no_proxy` |