xfe-se 命令行

用于从本机调用游戏中的 XFE Agent。命令行不直接修改存档，也不加载游戏程序集；所有游戏操作由 Agent 在游戏更新线程执行。

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 返回采样数量、时长与文件路径。指定的输出文件会被重新创建。

所有命令的 stdout 都是 JSON；诊断信息仅写入 stderr。退出码：0 成功，1 本地文件/权限错误，2 参数错误，3 管道或协议错误，4 Agent 返回业务错误，130 用户取消。请求限制为 1 MiB，响应限制为 4 MiB。Ctrl+C 取消等待；游戏线程中已经开始的操作无法通过关闭客户端回滚。