xfe-se 命令行
用于调用游戏中的 XFE Agent,以及管理本机未加载的存档。实时操作通过 Agent 在游戏更新线程执行;host / world 命令无需游戏端连接,也不加载游戏程序集。
dotnet build src/XFE.SeAgent.Cli -c Release
$seAgent = "src/XFE.SeAgent.Cli/bin/Release/net10.0/xfe-se.exe"
& $seAgent --help
& $seAgent discover
& $seAgent call world.status --pid 12345
& $seAgent call blocks.get --pid 12345 --params '{"entityId":"1234567890123456789"}'
discover 读取 %LOCALAPPDATA%/XFE/SpaceEngineersAgent/endpoints/<PID>.json,检查进程仍存在、启动时间及可执行文件路径一致,过滤陈旧记录。只有一个有效游戏实例时,可以省略目标参数;多个实例必须指定 --pid 或 --pipe XFE.SE.Agent.<PID>。明确指定 --pipe 时直接连接所选本机管道。--endpoint-directory 可覆盖端点记录目录,主要供隔离验证使用。
call 的 --params 接受 JSON 对象或 @文件路径。请求超时通过 --timeout 指定秒数,默认 30,最大 30。
& $seAgent call pb.read --pid 12345 --params '{"entityId":"1234567890123456789"}'
& $seAgent deploy --pid 12345 --block 1234567890123456789 --file ./script.cs --expected-hash <pb.read返回的当前SHA256>
& $seAgent call pb.run --pid 12345 --params '{"entityId":"1234567890123456789","argument":"status"}'
deploy 必须提供当前脚本的 SHA-256,发送 pb.deploy 的 entityId、source、expectedSha256。哈希不一致时,由游戏端拒绝覆盖;不要在未知结果的超时后盲目重复部署,先读取方块当前状态。
& $seAgent watch --pid 12345 --block 1234567890123456789,2345678901234567890 --seconds 30 --interval 1 --out ./telemetry.jsonl
watch 调用 telemetry.snapshot,将 entityIds 作为十进制字符串数组传递。输出文件每行包含 capturedUtc 和原始 response,每个采样后刷新到磁盘;命令结束时 stdout 返回采样数量、时长与文件路径。指定的输出文件会被重新创建。
无连接诊断与离线部署
& $seAgent host status
& $seAgent world list
& $seAgent world inspect --path 'C:\Saves\MyWorld'
& $seAgent world read --path 'C:\Saves\MyWorld' --block 1234567890123456789
& $seAgent world backup --path 'C:\Saves\MyWorld'
& $seAgent world deploy --manifest ./deployment.json
& $seAgent world deploy --manifest ./deployment.json --apply true
& $seAgent world restore --backup 'C:\path\to\deployment-backup'
host status 同时列出游戏进程、有效 Agent 端点及日志推断的存档状态。日志必须同时匹配进程启动时间和可执行文件;状态不明或目标正在加载/运行时拒绝离线写入。若游戏未加载插件,诊断会提示通过 XFE 加载器启动;不会假装已经连接或自动退出当前游戏。检查结果来自日志,不能取代已连接时的 world.status。
world list 默认枚举当前用户的 SpaceEngineers/Saves,可用 --root 指定存档根目录。inspect 返回 sector 文件 SHA-256、实际网格上所有编程块的 ID、名称、源码哈希、字符数、Storage 哈希和启用状态;不包含投影蓝图中的编程块。read 返回指定编程块的完整源码与 Storage。读取已加载世界时这些是磁盘内容。
部署清单(路径为示例,摘要必须来自实际文件):
{
"version": 1,
"worldPath": "C:\\Saves\\MyWorld",
"expectedSectorSha256": "<inspect 返回的 sectorSha256>",
"scripts": [
{
"entityId": "1234567890123456789",
"expectedSha256": "<inspect 返回的旧源码 sha256>",
"sourcePath": "./script.cs",
"sourceSha256": "<新源码 UTF-8 文本的 SHA-256>"
}
]
}
sourcePath 相对于清单目录解析;ID 必须为十进制字符串。源码哈希使用 UTF-8 文本(去除文件 BOM,保留换行)。每份源码不超过 100000 个 UTF-16 字符、文件不超过 1 MiB。每份清单最多 1024 个不同编程块,不允许未知字段、缺失哈希或重复 ID。
world deploy 默认只预演,返回每个方块的新旧摘要及需要失效的二进制缓存。--apply true 才写入:重新检查存档使用状态和文件哈希,备份所有活动文件(不含游戏历史 Backup 目录),只替换指定 Program,核对整个 XML 的其他内容等价后原子替换 sector,并移除已备份的 .sbsB数字 缓存。Storage、CustomData、启用状态、其他脚本、世界设置、硬件和体素不改变。游戏下次加载时重新编译;离线部署不会声称游戏内编译已成功。
备份默认位于 %LOCALAPPDATA%/XFE/SpaceEngineersAgent/backups/<时间与随机编号>,含 backup.json 哈希清单和 files/ 原文件。world backup --out NEW_DIRECTORY 可单独保存完整离线快照。路径不能指向目标存档内部或现有目录;不跟随符号链接和目录联接。
world restore 撤销一次部署并恢复旧二进制缓存;必须使用部署事务的备份,且全部活动文件仍与部署完成时一致。加载并保存产生变化后会拒绝自动回滚,避免抹去游戏进度。普通 world backup 快照用于人工恢复或复制成另一个存档,不接受事务回滚命令。程序崩溃后的部分事务保留原 XML/备份,需先检查实际文件;不会绕过哈希冲突强制覆盖。
所有命令的 stdout 都是 JSON;诊断信息仅写入 stderr。退出码:0 成功,1 本地文件/权限错误,2 参数错误,3 管道或协议错误,4 Agent 返回业务错误,5 离线存档校验/冲突错误,130 用户取消。实时请求限制为 1 MiB,响应限制为 4 MiB。Ctrl+C 取消实时等待;游戏线程中已经开始的操作无法通过关闭客户端回滚。离线写入事务会完成提交或恢复后才返回,操作期间请勿加载目标存档。