# xfe-se 命令行

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

```powershell
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。

```powershell
& $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`。哈希不一致时，由游戏端拒绝覆盖；不要在未知结果的超时后盲目重复部署，先读取方块当前状态。

```powershell
& $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` 取消等待；游戏线程中已经开始的操作无法通过关闭客户端回滚。