# OpenCat 通过 Git 安装机器人评测 MCP

适用于 Windows、Python 3.11 Native 运行模式。电脑只需预装 Git 和 uv，
无需下载 wheel、克隆开发源码或运行准备命令。

## 添加配置

在 OpenCat 的“扩展 → MCP → 添加服务器”中填写：

| 字段 | 内容 |
|---|---|
| 服务器名称 | `robot_eval` |
| 传输方式 | `STDIO` |
| 可执行文件 | `uvx`（PATH 中找不到时填写实际 `uvx.exe` 绝对路径） |
| 转发的环境变量名 | `CODEX_HOME` |

参数每行一个：

```text
--python
3.11
--from
git+https://github.com/leanglin/ai-embodied-eval-mcp-dist.git@<发行说明中的完整commit>
robot-eval-mcp-launcher
```

把占位符替换为发行说明中的完整 40 位 commit，不要使用浮动分支。
Git 地址放在参数中，HTTP URL 栏仅用于远程 MCP 服务。

## 首次启动

启动器自动下载校验安装包、准备依赖、初始化机器狗 Profile，并安装六个 Skills 和 Agent。
用户只需在本地凭据窗口的密码框中填写一次个人平台 Token，用户名保持 `platform`。
关闭窗口后仍可添加 MCP，之后通过智能体要求“配置平台 Token”再次打开窗口。

当前发行包按维护者要求直接内置机器狗 SSH、MinIO 共享默认凭据。
这些值可从公开安装包提取，不应视为保密信息。个人 Token、本机修改值不进入分发包。
G1 两个 SSH 凭据没有内置值，使用 G1 前可要求智能体打开对应配置窗口。

v0.5.1 起，首次连接先提供两个安装工具，不必等待完整依赖下载：

1. `get_setup_status` 查询安装阶段、错误码、Windows 错误号和日志位置。
2. `retry_setup` 重试失败或被宿主中断的安装；正在安装时复用当前尝试。
3. 安装成功后，安装连接会关闭。点击“重新加载配置”即可连接完整的 103 个评测工具。
   切换瞬间可能暂时显示 failed；若恰好重载过早，待连接结束后再次重载。

安装状态中的两个工具仅用于安装，不代表完整评测工具已就绪。
普通工具探测和 MCP 重载不会主动取消已经启动的安装。
OpenCat 默认启动时限仍为 30 秒；`uvx` 获取 Python 或启动器本身发生在握手之前，
这部分网络过慢仍可能超时，重载会重新获取。下载失败或安装中断后，可对智能体说“重试 MCP 安装”。

安装目录：`%LOCALAPPDATA%\ai-embodied-eval-mcp\versions\<版本>-<SHA256>\`。
日志为该目录的 `install.log`，各 OpenCat Profile 状态位于 `profiles\<标识>\status.json`。
每次尝试的独立记录位于同级 `attempts\<尝试标识>\`；遗留运行状态以查询工具的存活判断为准。
Runtime 数据独立保存在 `%LOCALAPPDATA%\ai-embodied-eval-mcp\runtime`。
其他旧安装如使用不同数据目录不会被自动迁移。

安装器、Runtime 和凭据窗口接受 OpenCat 的 Windows Job 管理。
普通 MCP 重载或切换会话可复用共享 Runtime；关闭 OpenCat、切换 Shared/Isolated Profile、
重启或崩溃其 app-server 会终止所属进程，正在进行的评测可能中断。
多个连接共享 Runtime 时，其生命周期由最初启动它的宿主决定；关闭该宿主也会影响其他连接。
任务证据保留，重启后按中断恢复规则检查，不自动重放机器人操作。
`health_check` 的 `process_lifetime` 字段标识 `host_managed`、`standalone` 或 `unknown`。

Skills 一般自动刷新；未出现时使用 Skills 页的“重新加载 Skills”。

## 修改与升级

- 可对智能体说“修改机器狗 SSH 密码”“修改 MinIO 凭据”或“更新个人平台 Token”。
  智能体打开本地输入窗口，保存到 Windows 凭据库，不需要把密码发进聊天。
- `get_credential_status` 返回配置及窗口状态，`configure_credentials` 在用户授权后打开指定窗口。
- 只在本机缺失时初始化共享默认值；已有凭据、用户 Profile 修改不会被新版默认值覆盖。
- 从旧版本更新时，只替换 Git 参数中的 commit。新版使用独立版本目录，旧安装包不会被覆盖。
- v0.5.2 修复 `supplemental_robot_log_path` 返回为 `path-ref://` 后触发的 Profile 读取错误。
  升级后原有 Profile 可直接读取，补充日志路径无需清空，也无需重新保存 Profile。
- 升级时将 Git commit 更换为新发行说明中的值。活动任务会阻止 Runtime 切换，任务完成后重载。
- 已使用新版的共享 Runtime 不自动降级；同版本号对应不同安装包会报冲突。
- 原有 wheel 安装仍受支持。表单配置模式的初始化、Doctor 和卸载不改写或删除手动保存的 MCP 配置。

验收时要求智能体读取 `list_profiles`、`get_profile`，并携带该 Profile 的 `profile_id`
调用 `get_capabilities`。未绑定 Profile 的能力查询可能显示 `NATIVE_PROFILE_NOT_CONFIGURED`，
该提示本身不表示已保存的配置损坏。

## 管理员维护

发布流程：构建并验证版本 wheel，运行 `scripts/build-git-distribution.py` 生成
小型公开仓库和独立 Release 附件；提交并推送包含固定清单的 Git commit，再上传对应版本 Release wheel。
仓库中的清单校验 wheel SHA-256；完整依赖由带哈希的锁文件约束。

开发仓库提供 `scripts/publish-git-distribution.ps1 -StageDirectory <生成目录>`。
发布机需要 GitHub CLI，并先完成 `gh auth login`；脚本创建公开分发仓库、发布不可覆盖的版本，
校验匿名 Git 访问和附件哈希，并生成可直接填写的 `OPENCAT-CONFIG.txt`。

默认值维护在开发仓库 `src/robot_eval_mcp/builtin_credentials.py`。
只允许登记共享默认凭据，个人 Token 和任何本机覆盖值不得加入。

可从持久安装环境运行 `robot-eval-opencat doctor --codex-home <当前Profile目录>` 诊断。
`prepare-only` 只负责资源、Profile 和 Runtime 初始化，不接管 MCP 配置。