内容
# bg-agent
*A keyframe from an autonomous run: the agent navigates Candlekeep through JSON world state alone.*
通过**结构化文本 / MCP 接口**而不是屏幕来玩 **Baldur's Gate**（和其他 Infinity Engine 游戏）。LLM 代理读取 JSON 世界状态并发出动词动作（`move_to`、`attack`、`talk`、`loot`、`choose_dialogue`等）——无视觉，无像素坐标。
它通过在 [GemRB](https://github.com/gemrb/gemrb)（开源 Infinity Engine 重实现，它嵌入 CPython）中嵌入一个小型桥梁，以及一个薄的 MCP 服务器，代理连接到该服务器。**原始游戏二进制文件从未被触及，游戏数据也未被包含或获取** —— 您只需指向您拥有的游戏副本。
> 状态：工作原型。**感知、导航、掠夺、暂停/摄像头控制在 GemRB 的捆绑演示游戏和经典 Baldur's Gate 1 上均可正常运行**。与 NPC 的对话部分连接（参见 `docs/AGENT_FAILURES.md`）。真正的无头渲染是一个跟踪的后续；目前它在一个窗口中运行。在 macOS（Apple Silicon）上构建/验证。
## 工作原理
```
LLM 代理（例如 Claude Code）
│ MCP 工具调用：get_state, move_to, attack, talk, loot, choose_dialogue, ...
mcp/server.py ← 薄的、类型化的 MCP 包装器（不了解引擎内部实现）
│ 基于本地 TCP 的行分隔 JSON {id,method,params} -> {id,ok,data|error}
bridge/bg_bridge.py ← 在 GemRB 的嵌入式 Python 中运行
├─ 后台线程：阻塞套接字 I/O -> 线程安全队列 （此处无引擎调用）
└─ GemRB.SetTimer 在引擎的 MAIN 线程上泵送：排空队列，调用 GemRB.*，回复
GemRB 引擎（C++，+ 小补丁） ── 您的 Infinity Engine 游戏数据
```
设计说明和完整的反向工程 GemRB API 接口在 `docs/FINDINGS.md` 中；架构和里程碑计划在 `docs/PLAN.md` 中。
## 这里有什么
```
bridge/ 引擎内的 GemRB Python：bg_bridge.py（状态+动词+套接字），bg_quickstart.py，
以及演示探针（bg_probe.py，bg_action.py）
engine-patches/ 应用于 GemRB 检查点的 C++/CMake/GUIScript 小补丁：
0001 — 无头 CLI 构建 + GetAreaActors/GetAreaObjects/DialogStart/
TakeAllFromContainer/GetDialogState 助手
0002 — GUIScript 自动启动钩子（演示 + bg1 快速启动）
cpp/ C++ 帮助器的可读副本（补丁是权威的）
mcp/ server.py（FastMCP）+ requirements.txt
context/ CLAUDE.md — 动词 API + AD&D 2e 基础知识，代理在游戏前读取
test/ client.py（协议烟雾测试），bg.py（一键 CLI），play_demo.py
config/ demo.cfg.sample / bg1.cfg.sample（run.sh 生成实际的配置文件）
docs/ FINDINGS.md，PLAN.md，AGENT_FAILURES.md
setup.sh 克隆 GemRB，应用补丁，安装桥梁脚本，构建
run.sh 生成配置文件，签名（macOS），启动引擎 + 桥梁
```
## 快速开始（macOS，Apple Silicon）
```bash
brew install cmake sdl2 sdl2_mixer python@3.11
# 1) 克隆 GemRB，应用补丁，安装桥梁脚本，构建
./setup.sh
# 2) 运行捆绑的 DEMO 游戏（无需拥有游戏数据）+ 桥梁
./run.sh
# 3) 从另一个 shell 测试桥梁（无需 LLM）
python3 test/bg.py get_state
python3 test/client.py
# 4) 为 LLM 代理提供 MCP 服务器
python3 -m venv mcp/.venv && mcp/.venv/bin/pip install -r mcp/requirements.txt
cp .mcp.json.sample .mcp.json # 编辑 <PROJECT_ROOT>；为 Claude Code 注册服务器
```
## 运行您自己的游戏（例如 Baldur's Gate 1）
您必须拥有该游戏。 将 `GAME_PATH` 指向包含 `chitin.key` 的文件夹：
```bash
GAME_TYPE=bg1 GAME_PATH=/path/to/your/bg1 ./run.sh
```
`GAME_TYPE` 与 GemRB 的匹配（`bg1`、`bg2`、`iwd`、`pst`等）；自动启动快速启动目前适用于 `demo` 和 `bg1`。
## 安全
引擎内的桥梁是运行游戏的未经身份验证的控制套接字。它默认为 `127.0.0.1`，除非设置 `BG_AGENT_ALLOW_REMOTE=1`，否则拒绝非环回绑定。在 LAN 或互联网上使用时，请不要暴露它而不添加您自己的隔离/身份验证层。
## 构建/运行时说明（macOS）
补丁和 `run.sh` 处理了几个 macOS 特有的细节，所有这些都记录在 `docs/FINDINGS.md §3` 中：构建无头 CLI 二进制文件而不是 GUI Cocoa 包装器，`-DDISABLE_WERROR=1`（新的 clang/libc++），跳过 `ibtool` nib 步骤，以及 **重新签名 Homebrew 的 SDL2**（GemRB 的构建使它的代码签名失效，否则在 `dlopen` 时会导致内核 `SIGKILL`）。无需完整的 Xcode。
## 法律
GemRB 仅是引擎。您必须从您合法拥有的副本中提供 Infinity Engine 游戏数据。该项目**不**包含任何游戏资产，也不会下载它们。
## 许可证
MIT（该项目自己的代码）。GemRB 本身是 GPL-2.0-or-later；`engine-patches/` 中的文件是与 GemRB 的差异，当应用时继承其许可证。
