XFE Space Engineers Agent Bridge

专为 AI Agent 编写的 Space Engineers 客户端调试插件。通过 XFE 自研加载器进入真实游戏，提供本机 JSON RPC 和 xfe-se 命令行客户端；不依赖旧版/新版第三方插件加载器。

构建与安装

需要 Windows、.NET 10 SDK、.NET Framework 4.8 和已安装的 Space Engineers。插件引用本机游戏 DLL，不随项目分发游戏程序集。

./build.ps1 -GameBin64 'D:\SteamLibrary\steamapps\common\SpaceEngineers\Bin64'

也可设置环境变量 SE_GAME_BIN64，或创建被 Git 忽略的 Directory.Build.local.props，填写 MSBuild 的 GameBin64 属性。输出插件为 src/XFE.SeAgent.Plugin/bin/Release/net48/XFE.SeAgent.Plugin.dll；客户端为 src/XFE.SeAgent.Cli/bin/Release/net10.0/xfe-se.exe。

在 XFE ToolBox 的太空工程师插件管理器中导入并启用此 DLL，然后启动游戏。已经构建 XFE Loader 时，也可用 PowerShell 7 执行 tools/Start-DebugSession.ps1：它检查加载器完整性、保留已有插件、备份并更新清单后启动游戏；发现游戏已运行时会拒绝启动，需先正常保存退出。-InstallOnly 只安装。

调试存档

读取接口可用于观察当前世界。部署脚本、执行命令、修改设备、主动相机探测、暂停和物理停止只接受明确授权的离线测试副本。在主菜单也可加载已授权的副本，不自动卸载另一个正在运行的世界。

python tools/prepare_debug_world.py

该脚本需要 Python 3.11+，按修改时间寻找包含 AMS 编程块的存档，排除历史备份并创建副本，将副本设为离线、关闭自动保存，记录原文件 SHA-256 与编程块清单。也可传入 --source <存档目录>。原始存档不写入。结果位于 artifacts/world-preparation.json。

授权配置位于 %LOCALAPPDATA%/XFE/SpaceEngineersAgent/config.json，只记录副本绝对路径：

{ "allowedWorldPaths": ["C:\\path\\to\\XFE Agent Debug AMS"] }

配置在插件初始化时读取。修改授权列表后需要重启游戏。

Agent 接入

游戏加载插件后，在 %LOCALAPPDATA%/XFE/SpaceEngineersAgent/endpoints/<PID>.json 发布管道地址。客户端核对 PID、启动时间和可执行文件路径，忽略失效记录；多个游戏实例需显式选择 --pid 或 --pipe。

$cli = './src/XFE.SeAgent.Cli/bin/Release/net10.0/xfe-se.exe'
& $cli discover
& $cli call agent.capabilities
& $cli call world.status
& $cli call world.load --params '@artifacts/load-world.json'
& $cli call blocks.list --params '{"name":"XFEAMS","limit":64}'
& $cli call pb.read --params '{"entityId":"139184150457569825"}'
& $cli deploy --block 139184150457569825 --file 'C:\path\script.cs' --expected-hash '<pb.read 返回的 sha256>'
& $cli watch --block 139184150457569825 --seconds 60 --interval 1 --out artifacts/miner7.jsonl

load-world.json 格式为 { "path": "测试副本绝对路径" }。实体编号使用十进制字符串，避免 JavaScript Number 丢失 64 位精度。标准输出仅为 JSON；错误详情在标准错误输出，同时返回非零退出码。完整 CLI 参数见客户端说明，接口参数见 API 参考。

调试能力

接口	用途
`agent.ping` / `agent.capabilities` / `agent.events`	协议探测、能力查询、带序号的事件日志
`world.status` / `world.load` / `world.save` / `world.pause` / `world.exit`	世界就绪状态、测试副本加载/保存、由插件持有的暂停，以及保存成功后正常退出游戏
`grids.list` / `grids.get`	网格标识、位置和朝向、包围盒、速度及物理状态
`blocks.list` / `blocks.get`	设备、所属刚性网格、CustomData 与详细信息
`blocks.actions` / `blocks.action`	枚举和执行实际终端动作
`blocks.properties` / `blocks.setProperty`	枚举并设置受支持的终端属性类型
`pb.read` / `pb.inspect`	源码、哈希、配置、持久数据、Echo、编译错误、运行预算以及受限的脚本实例字段快照
`pb.deploy` / `pb.run`	带预期哈希校验和备份的源码部署、真实编译、运行参数
`telemetry.snapshot`	电池、气罐、推力和覆盖、陀螺、连接器、相机、库存、文本屏幕、编程块、舰船质量和速度
`cameras.scan`	使用指定实际摄像机的充能和视场进行探测，返回命中位置与实体
`grid.stop`	测试网格清速度、推力/陀螺覆盖；可同时禁用其编程块，防止下一帧再次施力
`debug.screenshot`	请求引擎输出游戏截图，便于与遥测核对

PB 部署备份保存在测试存档的 Storage/XFE.AgentBridge/Backups 中，含原源码、CustomData 和 Storage。编译失败通过结果和编译错误字段呈现；不要把“已写入”当作“编译成功”。

pb.inspect 只遍历脚本程序集自身字段和有限集合，深度最多 3 层、总节点和字符串均有限制。不会执行任意 C#、调用用户指定的反射方法或遍历整个游戏对象图。

通信和执行语义

管道名为 XFE.SE.Agent.<PID>，ACL 仅允许当前 Windows 用户并拒绝网络登录身份，不开 TCP 端口。每个连接发送一行 UTF-8 JSON，获得一行响应：

{"id":"query-1","method":"world.status","params":{},"timeoutMs":10000}

成功响应为 { "id": "query-1", "result": {} }；失败响应为 { "id": "query-1", "error": { "code": "…", "message": "…" } }。

后台线程只处理管道与 JSON，所有游戏访问排队到游戏 Update 线程。最多 4 个连接、128 个排队请求，单条请求不超过 1 MiB、响应不超过 4 MiB、超时不超过 30 秒；限制在解析和序列化阶段生效。

过期、断开或已取消的排队请求不会再触发操作。已经开始执行的游戏操作无法从后台线程安全中断；遇到此类超时应先查询实际状态，再决定是否重试。主动相机扫描会消耗真实充能；排障时应与业务脚本的扫描时间区分。

验证与调试记录

dotnet run --project tests/XFE.SeAgent.Tests -c Release
python -m unittest discover -s tests -p test_world_copy.py -v

自动测试覆盖协议边界、当前用户管道、真实队列与取消行为、客户端发现/调用/部署/连续记录，以及隔离目录中的存档复制。游戏 API 编译和游戏内实测分开记录，见实测记录。artifacts 保存本机原始证据，默认不提交存档、遥测中的完整源码或个人路径。

tools/trace_ams.py 可同时记录 AMS 的真实脚本状态、扫描和绕行字段与网格速度。它只接受脚本哈希匹配的压缩字段映射；更新 AMS 后需重新核对映射。通用记录使用 xfe-se watch，不依赖 AMS 版本。处理 pb.inspect 结果时须保留字段名称的大小写，Python JSON 或 PowerShell 7 的 ConvertFrom-Json -AsHashtable 均可。