emucap

# emucap — 模拟器监视器 + HITL 适配器 > 한국어 안내: [README.ko.md](README.ko.md) 用于调试复古游戏补丁的 MCP 基础设施。AI 代理读取并控制正在运行的模拟器的内存、状态和屏幕，以便它可以分析人类用普通语言描述的问题。一个通用的核心加上每个模拟器的适配器支持多个模拟器 — Mesen2（超级任天堂），Mednafen 分支（土星 · PlayStation · PC 引擎 · Mega Drive/Genesis），Flycast（梦幻城），以及 MAME（PC-98）。 **v0.1.0 — 测试版。** 该仓库正在积极、持续地开发中；接口和行为可能会在更新之间发生变化。 根据 GPL-2.0-or-later 许可。参见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。 ## 平台 Rust 核心（两个 MCP）和 Rust `launch` 工具是跨平台的（macOS on Apple Silicon + Intel，Linux，Windows）。每个模拟器的构建/启动需求因操作系统而异 — 在自动化不足的地方，代理从上游说明中安装模拟器并指向 emucap，而 `status` 报告主机上实际可用的工具。在 Windows 上，优先使用 Rust `launch` 工具和记录的环境变量覆盖，而不是 Unix shell 启动器。 ## 让代理执行安装 该仓库的构建允许 **代理（Claude Code，Codex，…）自行执行安装**。非开发者可以直接将仓库交给代理，并说： > “按照本仓库的 README 中的 '代理安装步骤' 来构建 emucap 并将其注册为 MCP 服务器。” 代理按顺序执行以下步骤。核心构建很轻；仅在需要时构建每个模拟器的适配器。 **您（代理）是用户的界面。** 假设用户不是开发者，可能不熟悉终端甚至不习惯安装桌面程序，并且不会阅读此文件 — 您阅读并完成工作。自行运行终端步骤。当某一步骤需要用户在 GUI 中点击某些内容（例如 Mesen2 设置）时，一步一步地指导用户：命名菜单及其位置（“顶部菜单栏”），引用确切的按钮/复选框标签，并在继续之前确认用户已完成。适应用户的操作系统 — 本指南的 shell 命令为 Unix 风格；在 Windows 上使用等效命令（并参见上面的平台说明）。 ### 1. 先决条件（代理检查并在缺少时安装） - **Rust** — 使用 `command -v cargo` 检查。如果缺少：`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y && . "$HOME/.cargo/env"` - **C 编译器**（用于构建捆绑的 SQLite）— macOS：`xcode-select -p || xcode-select --install`。Linux：`cc --version || sudo apt-get install -y build-essential`。Windows：安装 MSVC C++ 构建工具（Rust 安装程序可能会提示）；然后从普通的 PowerShell 构建。 - **git**。 ### 2. 构建核心 从仓库根目录： ```sh cargo build --release --bin emucap --bin emucap-mcp --bin emucap-track-mcp --bin emucap-broker --bin emucap-mame-pc98-bridge ``` 输出：`target/release/emucap-mcp`（**控制 MCP** — 驱动模拟器），`emucap-track-mcp`（**跟踪 MCP** — 实验账本，无模拟器），`emucap`（案例捆绑 CLI），`emucap-broker`（多会话代理），以及 `emucap-mame-pc98-bridge`（PC-98 启动助手）。所有依赖项均来自 crates.io，SQLite 是捆绑的，因此 **除了 Rust 和 C 编译器之外，源代码构建不需要其他任何东西**。第一次构建较慢，因为依赖项正在下载；后续构建速度很快。 ### 3. 注册 MCP 服务器（两个） emucap 分为 **两个 MCP，您需要注册这两个 MCP** — 代理组成它们（参见 §2b）。 - **控制 MCP** (`emucap-mcp`) — 模拟器驱动引擎。读取内存、状态和屏幕；控制输入、保存状态和断点；并从分析动词返回结果（`bisect` / `regression_run` / `verify_determinism`）。 - **跟踪 MCP** (`emucap-track-mcp`) — 实验账本（`.emucap/`）。启动 (`run_start`)、记录 (`log_*`) 和查询 (`query_runs` / `compare_runs` / `summarize_runs`) 运行。它 **不知道模拟器**（无模拟器）。它是控制 MCP 的附加组件，因此控制 MCP 在没有它的情况下也能正常工作。 **Claude Code：** ```sh claude mcp add emucap-control -- "$(pwd)/target/release/emucap-mcp" claude mcp add emucap-track -- "$(pwd)/target/release/emucap-track-mcp" ``` **Codex**: ```sh tools/register-codex-mcp.sh ``` 在 Windows 上，在 PowerShell 中运行 `tools/register-codex-mcp.ps1`。脚本使用 `target/release/` 中的源构建二进制文件，并注册 `emucap` 和 `emucap-track`。 根据需要使用环境变量进行调整：`EMUCAP_PORT`（控制 MCP，默认 47800，如果被占用则自动推进到下一个端口），`EMUCAP_TRACK_ROOT`（跟踪 MCP 的账本位置，默认为 `.emucap` 在工作仓库的 git 根目录下）。 注册后，重新连接代理会话（`/mcp`）。由于 **每个 MCP 都暴露自己的 `bootstrap`，** 成功意味着控制 MCP 的 `bootstrap`（模拟器入口）和跟踪 MCP 的 `bootstrap`（账本入口）都出现在工具列表中。如果它们没有出现，请重新构建发布版本并重新连接 — MCP 服务器运行发布二进制文件，因此调试构建不会被拾取。 ### 3b. 三层，由代理组成 三层协同工作但保持独立（类比：② 跟踪 MCP 类似 MLflow，① 控制 MCP 类似 TensorFlow）： 1. **模拟器控制**（控制 MCP）— 一个领域无关的实时控制引擎。单独完成（您可以无需跟踪进行调试）。 2. **实验管理**（跟踪 MCP）— 一个附加组件。它 **不需要了解** ①；它在上面分层以记录和查询实验。 3. **应用程序/方法论**（例如本地化补丁技能）— 顶层 **组合** ① 和 ② 的层（此插槽可替换（本地化、粉丝游戏、AI TAS — 任何在此处的内容都重用下面两层不变）。 两个 MCP 永远不会相互调用 — **代理组成它们**: - **传递 rom_sha1**：通过控制 MCP 的 `get_rom_info` （`.sha1`）读取 ROM 标识符，并将其传递给跟踪 MCP 的 `run_start(rom_sha1=…)`（如果适配器缺少 `get_rom_info`，则回退到 `shasum -a1 <content>`）。传递 `connection_ref`（控制 MCP 的 `status` 连接名称，或 `"port:N"`）会自动完成该连接上的上一个未完成的运行。 - **分析动词仅返回**：`bisect` / `regression_run` / `verify_determinism` 具有控制 MCP 驱动模拟器并 **返回** 结果而无需写入账本。要记录它，请通过跟踪 MCP 的 `log_gate` / `log_metric` 记录结果。 - **显式记录干预**：状态更改如 `write_memory` / `load_state` / `reset` / 输入不会自动记录，因此请通过跟踪 MCP 的 `log_intervention` 记录它们以保持再现保真度。 ### 4. 首次运行（代理以 bootstrap 启动） 每个 emucap 任务都以 `bootstrap` 开始。要求代理“调用 emucap `bootstrap`”，它返回 `listening_port`、`runtime_paths`（每个适配器的绝对构建路径和旧版备用启动器）、支持的系统以及关于启动内容的询问。然后 `launch_plan(content_path, system?)` 返回首选的 MCP `launch` 工具参数。代理调用 `launch` 并在几秒钟后检查 `status`。由于 **bootstrap 还会显示适配器安装路径和备用方案**，因此代理永远不需要在文件系统中查找。 ## 每个模拟器的适配器（代理在需要时安装） 选择一个开始。**Mesen2 是最轻量级的 — 无需源代码构建。** - **Mesen2（超级任天堂）** — 安装 Mesen2 应用程序，并允许 GUI 中的脚本窗口进行一次网络访问。适配器 Lua 与仓库一起提供，因此无需构建。→ `adapters/mesen2/README.md` - **Mednafen（土星 · PSX · PCE · MD）** — 使用 `adapters/mednafen/build.sh` 构建分支（需要 SDL：macOS `brew install sdl2`，Linux `libsdl2-dev`）。一个二进制文件处理所有四个系统。PSX 和 PCE-CD 需要 BIOS 文件（未提交到仓库）。→ `adapters/mednafen/README.md` - **Flycast（梦幻城）** — 使用 `adapters/flycast/build.sh` 构建；它在 emucap 拥有的工作树中构建，并将任何 `FLYCAST_SRC` 检查视为只读输入。→ `adapters/flycast/README.md` - **MAME（PC-98）** — 使用 `adapters/mame-pc98/build.sh` 从源代码构建 MAME（速度慢，占用大量磁盘）。→ `adapters/mame-pc98/README.md` ## 了解更多 - 构建内容、原因和二进制文件 → `CLAUDE.md` - 每个模拟器的内存类型、按钮名称、断点和启动故障排除 → 每个 `adapters/*/README.md` 二进制文件：`emucap`（案例捆绑：`finalize` / `inspect`），`emucap-mcp`（控制 MCP — 实时模拟器控制，stdio），`emucap-track-mcp`（跟踪 MCP — 实验账本，无模拟器，stdio），`emucap-broker`（多会话连接共享）。