1. 位置与配置
发布包 release/ 内含两个可执行文件：NTLauncher-vX.Y.Z-windows.exe（GUI，无控制台）、ntlauncher-cli.exe（CLI，有控制台）。
运行时在 CLI 同目录生成：
config.json—— 与 GUI 共用run-state.json—— CLI 运行状态，自动维护logs/—— launch 默认日志目录
2. 通用约定
- 退出码：
0= 成功，1= 失败。 --json：所有命令支持，stdout 输出机器可读 JSON；失败时向 stderr 输出{"success":false,"error":"..."}。- 并发：一个 CLI 进程前台阻塞启动一个实例；多个 CLI 进程可并行启动不同实例。
- 作用域：
status/stop只管理由 CLI 启动的实例。
ntlauncher-cli list-instances [--json] ntlauncher-cli list-accounts [--json] ntlauncher-cli launch --instance-id <ID> [--account-id <ID>] [--log-file <PATH>] [--json] ntlauncher-cli status [--json] ntlauncher-cli stop --instance-id <ID> [--json] ntlauncher-cli --help
3. 命令参考
list-instances —— 列出已安装实例
{"success":true,"instances":[{"id":1,"name":"苦难年代","version":"v0.0.1","game_version":"1.20.1","install_state":"Installed"}]}
install_state：NotInstalled / Installing / Installed / UpdateAvailable / Error。
list-accounts —— 列出账号
{"success":true,"accounts":[{"id":"acc-uuid","username":"Steve","account_type":"offline","uuid":null,"is_selected":true}]}
account_type：offline / official / thirdparty；is_selected = launch 缺省 --account-id 时使用的账号。
launch —— 启动实例（阻塞直到游戏退出）
| 参数 | 必填 | 说明 |
|---|---|---|
--instance-id <ID> | 是 | 实例 ID |
--account-id <ID> | 否 | 缺省用选中账号，再缺省用第一个 |
--log-file <PATH> | 否 | 缺省写入 <配置目录>/logs/instance-<id>-<名称>-<时间戳>.log |
--json | 否 | 机器可读 |
成功：{"success":true,"instance_id":1,"instance_name":"...","log_file":"...","message":"Minecraft 启动流程已完成"}
失败（stderr）：{"success":false,"error":"错误信息\n\n最近 Minecraft 日志：\n..."}（含日志 tail）
status —— 查询运行中的实例
{"success":true,"running":[{"instance_id":1,"instance_name":"...","pid":12345,"started_at":"2025-01-01T00:00:00+08:00","log_file":"..."}]}
自动校验 PID 存活并清理残留。
stop —— 停止实例
{"success":true,"stopped":true,"instance_id":1}
进程已自行退出时仍清理记录并返回成功；无记录返回错误 + 退出码 1。
--help —— 查看帮助
输出所有命令及其参数说明。
4. Agent 使用示例（PowerShell）
# 启动并等待退出
$instances = & .\ntlauncher-cli.exe list-instances --json | ConvertFrom-Json
$id = $instances.instances[0].id
$result = & .\ntlauncher-cli.exe launch --instance-id $id --json
if ($LASTEXITCODE -ne 0) { throw "启动失败: $result" }
# 后台启动 + 轮询 + 停止
Start-Process .\ntlauncher-cli.exe -ArgumentList @("launch","--instance-id","$id","--json") -NoNewWindow
$status = & .\ntlauncher-cli.exe status --json | ConvertFrom-Json
$running = $status.running | Where-Object { $_.instance_id -eq $id }
if ($running) { & .\ntlauncher-cli.exe stop --instance-id $id --json }
5. 注意事项
launch是前台阻塞命令：Agent 调用时设置合理超时（10-20 分钟），需中途终止时在另一进程执行stop。- 并行启动多个实例请使用多个 CLI 进程。
- 真实启动依赖：实例已安装完成（
install_state == "Installed"）、Java 环境可用；启动流程与 GUI 完全一致。 run-state.json与logs/由 CLI 自动维护，勿手动修改；配置目录跟随 CLI 可执行文件位置。