docs: update bat runtime documentation

This commit is contained in:
2026-07-12 23:04:26 +08:00
parent f7255f7c04
commit bd9f50c85c
14 changed files with 195 additions and 115 deletions
+9 -10
View File
@@ -20,9 +20,9 @@ Rust 侧官方日服资源链路已经从实验验证推进到正式入口:
4. 能生成官方全量 pull plan,执行真实下载,维护 `official-download-manifest.json`
5. 下载后使用本地 manifest 的 size + BLAKE3 校验复用文件;官方 seed `.hash` 使用 `xxHash32(seed=0)` 强校验。
6. 支持 `.part` 断点续传、失败后 clean retry、本地 manifest audit/repair。
7. `bat-official-sync --watch` 可常驻运行,正常检查默认每 1 小时一次;远端和本地一致时默认静默,失败后默认 60 秒快速重试;CLI 默认向 stderr 输出 ASCII banner 和人类可读 progress log。
7. `bat --watch` 可常驻运行,`bat --daemon` 可后台运行并用 `bat status` / `bat stop` / `bat restart` / `bat reload` / `bat logs` 管理;daemon 使用 `bat.sock` Unix socket JSON-RPC 作为 live 控制通道,PID/状态/日志文件作为快照和 fallback;正常检查默认每 1 小时一次;远端和本地一致时默认静默,失败后默认 60 秒快速重试;CLI 默认向 stdout 输出人类可读摘要,向 stderr 输出 ASCII banner 和 progress log,需要机器输出时使用 `--json --no-progress`
8. 远端 snapshot 未变化但输出目录为空时,会按首次运行执行全量拉取;官方 seed `.hash` 校验失败时会清理对应 manifest 条目,避免失败产物被后续本地 audit 误判为可复用。
9. 非 dry-run 使用 `--output/.official-sync.lock` 防止并发写同一状态目录。
9. 默认资源目录是 `./bat-resources`,默认后台状态目录是 `/tmp/bat-pid`;该目录包含 `bat.sock``bat.pid``bat-status.json``bat-daemon.log`非 dry-run 使用 `--output/.official-sync.lock` 防止并发写同一资源目录。
仍需明确:这不是完整产品完成。Go CLI 最小入口、完整 AssetBundle 解析、Patch、翻译系统、API Server 和 Web 仍是后续工作;真实官方网络全量下载 smoke test 尚未记录在仓库文档中。
@@ -125,9 +125,9 @@ Rust 侧官方日服资源链路已经从实验验证推进到正式入口:
- `InMemoryResourceRepository`
- `SqliteResourceRepository`
- 官方 pull plan 构建。
- `OfficialResourcePullService`:官方 URL 拒绝策略、目标路径映射、下载 manifest、`.part` 续传、重试、官方 seed `.hash` 校验。
- `OfficialResourcePullService`:官方 URL 拒绝策略、目标路径映射、下载 manifest、`.part` 续传、重试、官方 seed `.hash` 校验、本地全量 verify
- `OfficialUpdateService`:官方 metadata auto-discover、bootstrap cache、snapshot diff、marker diff、本地 audit/repair。
- `bat-official-sync`:正式 CLI binary,支持 one-shot`--watch`
- `bat`:正式 CLI binary,支持 one-shot`--watch``--daemon``status``stop``restart``reload``refresh``logs``verify``repair``doctor``clean-stable`
待完成:
@@ -203,8 +203,8 @@ Rust 侧官方日服资源链路已经从实验验证推进到正式入口:
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 run -p bat-infrastructure --bin bat-official-sync -- --help
cargo test -p bat-infrastructure --bin bat -- --nocapture
cargo run -p bat-infrastructure --bin bat -- --help
git diff --cached --check
```
@@ -229,9 +229,8 @@ git status --short
当前唯一可作为 Linux 生产资源同步任务运行的入口是 Rust binary
```bash
cargo run -p bat-infrastructure --bin bat-official-sync -- \
cargo run -p bat-infrastructure --bin bat -- \
--auto-discover \
--platforms Windows,Android \
--output /var/lib/bluearchive-toolkit/official \
--watch
```
@@ -242,7 +241,7 @@ cargo run -p bat-infrastructure --bin bat-official-sync -- \
2. 不要指向已有游戏客户端目录。
3. 不要指向 `/home/wanye/D/BlueArchive` 这类开发或人工维护资源目录。
4. `--auto-discover` 可以下载官方 metadata,并按官方 manifest 临时获取 `resources.assets` 以解析 `GameMainConfig`;旧 ZIP manifest 才会下载临时 game zip。该流程不会安装或启动官方 launcher。
5. systemd service、容器或 Go 进程可以负责守护 `bat-official-sync --watch`,但定时检查逻辑已经在 Rust 内部正常检查默认 1 小时,失败重试默认 60 秒,每天北京时间(UTC+8)`03:00``16:00``18:00` 会强制执行一次自动刷新。
5. systemd service、容器或 Go 进程可以负责守护 `bat --watch`,也可以用 `bat --daemon` 启动后台模式;`--daemon` 的管理命令优先走 `/tmp/bat-pid/bat.sock` Unix socket JSON-RPC定时检查逻辑已经在 Rust 内部正常检查默认 1 小时,失败重试默认 60 秒,每天北京时间(UTC+8)`03:00``16:00``18:00` 会强制执行一次自动刷新。
详细运行说明见 `docs/guides/official-resource-test-pull.md`
@@ -266,7 +265,7 @@ cargo run -p bat-infrastructure --bin bat-official-sync -- \
立即任务:
1. 实现 Go CLI 最小框架和 `doctor`
2.`bat-official-sync` 增加发布型构建/安装说明和服务化验证。
2.`bat` 增加发布型构建/安装说明和服务化验证。
3. 补端到端 smoke:dry-run、真实下载到隔离目录、二次运行静默 up-to-date、本地损坏后 repair。
4. 开始 AssetBundle parser 的 UnityFS header/block/directory。