docs: update bat runtime documentation

README.md

@@ -13,7 +13,7 @@
 - `bat-adapters` Unity、Manifest、Client 集成框架，以及当前真实形态 Addressables catalog 解析覆盖。
 - `bat-cas-engine` CAS V1：原子写入、BLAKE3 校验、引用计数、GC、并发写入测试、损坏检测。
 - `bat-infrastructure` CAS 适配层、SQLite Resource Repository、官方资源 pull/update 服务。
-- `bat-official-sync`：官方资源自动发现、全量拉取、本地 manifest audit/repair、`.part` 断点续传、官方 seed `.hash` 校验、snapshot/cache、`--watch` 常驻更新。
+- `bat`：官方资源自动发现、全量拉取、本地 manifest audit/repair、`.part` 断点续传、官方 seed `.hash` 校验、snapshot/cache、`--watch` 常驻更新、`--daemon` 后台运行，以及 Unix socket JSON-RPC 后台控制命令 `status/stop/restart/reload/refresh/logs/verify/repair/doctor/clean-stable`。
 - `bat-ffi` 粗粒度 JSON 接口：Manifest inspect 和官方 sync plan。
 - 文档路线图、当前状态、缺口清单、官方资源运行指南。
 
@@ -52,39 +52,64 @@
 cargo test -p bat-adapters -- --nocapture
 cargo test -p bat-ffi -- --nocapture
 cargo test -p bat-infrastructure -- --nocapture
-cargo test -p bat-infrastructure --bin bat-official-sync -- --nocapture
+cargo test -p bat-infrastructure --bin bat -- --nocapture
 ```
 
 查看官方同步命令：
 
 ```bash
-cargo run -p bat-infrastructure --bin bat-official-sync -- --help
+cargo run -p bat-infrastructure --bin bat -- --help
 ```
 
 只做官方资源更新判断，不写同步状态：
 
 ```bash
-cargo run -p bat-infrastructure --bin bat-official-sync -- \
+cargo run -p bat-infrastructure --bin bat -- \
   --auto-discover \
-  --platforms Windows,Android \
-  --output /tmp/ba-official-update \
   --dry-run
 ```
 
 常驻自动更新，正常情况下默认每 1 小时检查一次；每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会强制执行一次自动刷新。远端和本地一致时静默。下载或发现失败时默认 60 秒后重试，可用 `--error-retry 60s` 调整：
 
 ```bash
-cargo run -p bat-infrastructure --bin bat-official-sync -- \
+cargo run -p bat-infrastructure --bin bat -- \
   --auto-discover \
-  --platforms Windows,Android \
-  --output /tmp/ba-official-update \
   --watch \
   --error-retry 60s
 ```
 
-CLI 默认启动时会向 stderr 打印 `BlueArchiveToolkit` ASCII banner，并继续把人类可读的阶段进度日志写到 stderr，例如自动发现、拉取 catalog、audit、下载第 N/总数个 URL 等；成功后的稳定 JSON report 仍写到 stdout。需要给上层程序保留纯机器输出时可加 `--no-progress`，只想关闭横幅但保留日志时可加 `--no-banner`。
+后台自动运行可以把 `--watch` 换成 `--daemon`。默认资源目录是 `./bat-resources`，默认后台状态目录是 `/tmp/bat-pid`。daemon 会在状态目录下创建 `bat.sock` 作为 Unix socket JSON-RPC 控制通道，同时写入 `bat.pid`、`bat-status.json` 和 `bat-daemon.log` 作为快照和故障排查文件：
 
-生产输出目录必须使用独立状态目录，不要指向已有客户端目录，也不要指向 `/home/wanye/D/BlueArchive` 这类人工维护或开发资源目录。
+```bash
+cargo run -p bat-infrastructure --bin bat -- \
+  --auto-discover \
+  --daemon
+
+cargo run -p bat-infrastructure --bin bat -- status
+cargo run -p bat-infrastructure --bin bat -- logs
+cargo run -p bat-infrastructure --bin bat -- restart
+cargo run -p bat-infrastructure --bin bat -- reload
+cargo run -p bat-infrastructure --bin bat -- stop
+```
+
+`status`、`stop`、`logs`、`reload` 和默认形态的 `refresh` 会优先连接 live RPC socket；socket 不可用时，状态和停止命令会回退到 PID/状态文件兼容路径。`reload` 不再强制重启进程，而是让后台 watch 循环重新自动发现并执行强制刷新：空闲睡眠时立即唤醒，正在同步时排队到当前轮结束后执行。确实需要替换启动参数时使用 `restart` 或给 `reload` 显式传入同步参数。
+
+资源操作命令默认输出人类可读摘要，并在没有显式 metadata 参数时默认走官方自动发现。脚本或上层程序需要稳定结构化输出时加 `--json`：
+
+```bash
+cargo run -p bat-infrastructure --bin bat -- refresh
+cargo run -p bat-infrastructure --bin bat -- refresh --force --json
+cargo run -p bat-infrastructure --bin bat -- verify
+cargo run -p bat-infrastructure --bin bat -- repair
+cargo run -p bat-infrastructure --bin bat -- doctor
+cargo run -p bat-infrastructure --bin bat -- clean-stable
+```
+
+`verify` 会以只读方式检查当前官方计划、本地 download manifest 的 size+BLAKE3，以及本地已有官方 seed `.bytes/.hash` 对的 xxHash32；发现缺失、远端变化或本地损坏会返回非 0。`repair` 会在异常资源存在时复用当前同步链路重新下载必要文件。`clean-stable` 只清理 `.part`、临时状态文件和失效锁/PID，不删除正式资源。
+
+CLI 默认启动时会向 stderr 打印 `BlueArchiveToolkit` ASCII banner，并继续把阶段进度日志写到 stderr，例如自动发现、拉取 catalog、audit、下载第 N/总数个 URL 等；命令结果默认以人类可读摘要写到 stdout。需要给上层程序保留稳定结构化输出时加 `--json --no-progress`，只想关闭横幅但保留日志时可加 `--no-banner`。
+
+生产资源输出目录必须使用独立目录，不要指向已有客户端目录，也不要指向 `/home/wanye/D/BlueArchive` 这类人工维护或开发资源目录。需要覆盖默认位置时，用 `--output <资源目录>`；需要覆盖后台状态目录时，用 `--state-dir <状态目录>`。
 
 ---