mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 03:56:44 +08:00
nyaKazuha
4192d7ee4c
Distinguish terminal HTTP errors from retryable CDN/network failures, record quarantined resources, and report failed download progress. Fixes #7
187 lines
10 KiB
Markdown
187 lines
10 KiB
Markdown
# BlueArchive Toolkit
|
||
|
||
**BlueArchiveToolkit** 是一个面向长期维护的 Blue Archive 资源管理、解析、翻译和补丁工具套件。
|
||
|
||
当前仓库仍不是完整产品，但 Rust 侧已经具备一条可运行的官方日服资源同步链路：可以在 Linux 上通过官方 HTTP metadata 自动发现资源入口，拉取 Windows + Android 官方资源，保存同步 snapshot，校验本地下载清单，并用 `--watch` 常驻定期检查更新。Go CLI、API Server、Web、完整 AssetBundle 解析、翻译系统和 Patch 系统仍在后续阶段。
|
||
|
||
---
|
||
|
||
## 当前可用
|
||
|
||
- Rust workspace 和 monorepo 结构。
|
||
- `bat-core` 领域对象和仓储接口骨架。
|
||
- `bat-adapters` Unity、Manifest、Client 集成框架，以及当前真实形态 Addressables catalog 解析覆盖。
|
||
- `bat-cas-engine` CAS V1：原子写入、BLAKE3 校验、引用计数、GC、并发写入测试、损坏检测。
|
||
- `bat-infrastructure` CAS 适配层、SQLite Resource Repository、官方资源 pull/update 服务。
|
||
- `bat`：官方资源自动发现、全量拉取、原子发布到 `current -> versions/<id>`、本地 manifest audit/repair、`.part` 断点续传、403/404/5xx 分类重试、下载 quarantine 诊断、ZIP 结构校验、官方 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。
|
||
- 文档路线图、当前状态、缺口清单、官方资源运行指南。
|
||
|
||
仍未完成：
|
||
|
||
- Go CLI 最小可用入口。
|
||
- 完整 UnityFS / AssetBundle 解析。
|
||
- 真实 Patch apply/diff。
|
||
- Translation Memory、Glossary、AI Provider。
|
||
- API Server、SDK、Web 管理后台。
|
||
|
||
详细状态见：
|
||
|
||
- [当前状态](CURRENT_STATUS.md)
|
||
- [完整开发计划](PROJECT_PLAN.md)
|
||
- [文档索引](DOCS_INDEX.md)
|
||
- [当前缺口清单](docs/reports/CURRENT_GAPS.md)
|
||
- [官方资源拉取与自动更新指南](docs/guides/official-resource-test-pull.md)
|
||
- [官方全量拉取 Smoke Runbook](docs/guides/official-full-pull-smoke.md)
|
||
- [官方资源后端说明](docs/architecture/official-resource-backend.md)
|
||
|
||
---
|
||
|
||
## 快速验证
|
||
|
||
前置要求：
|
||
|
||
- Rust 1.75+
|
||
- Go 1.22+
|
||
- `curl`
|
||
- `unzip`，仅旧版 launcher manifest 指向整包 ZIP 且 `--auto-discover` 需要从 ZIP 解析 `GameMainConfig` 时使用；当前目录型 manifest 会直接下载 `resources.assets`
|
||
|
||
运行当前主要测试：
|
||
|
||
```bash
|
||
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 -- --nocapture
|
||
```
|
||
|
||
查看官方同步命令：
|
||
|
||
```bash
|
||
cargo run -p bat-infrastructure --bin bat -- --help
|
||
```
|
||
|
||
只做官方资源更新判断，不写同步状态：
|
||
|
||
```bash
|
||
cargo run -p bat-infrastructure --bin bat -- \
|
||
--auto-discover \
|
||
--dry-run
|
||
```
|
||
|
||
常驻自动更新，正常情况下默认每 1 小时检查一次；每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会强制执行一次自动刷新。远端和本地一致时静默。下载或发现失败时默认 60 秒后重试，可用 `--error-retry 60s` 调整：
|
||
|
||
```bash
|
||
cargo run -p bat-infrastructure --bin bat -- \
|
||
--auto-discover \
|
||
--watch \
|
||
--error-retry 60s
|
||
```
|
||
|
||
后台自动运行可以把 `--watch` 换成 `--daemon`。默认资源目录是 `./bat-resources`，默认后台状态目录是 `/tmp/bat-pid`。daemon 会在状态目录下创建 `bat.sock` 作为 Unix socket JSON-RPC 控制通道，同时写入 `bat.pid`、`bat-status.json`、`bat-daemon.log`、`bat-events.jsonl` 和短生命周期的 `bat-control.lock`；`bat-events.jsonl` 是带轮转的结构化 JSONL 事件日志，`bat-status.json` 保存最后成功时间、下次检查时间、最后错误摘要和当前下载进度，`bat-control.lock` 用于串行化 `status/stop/restart/reload/logs/refresh` 等控制命令：
|
||
|
||
```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` 显式传入同步参数。后台 daemon 正在管理某个资源目录时，前台 `run/watch/refresh/repair` 不能直接写同一目录；默认形态的 `refresh` 会改走 RPC，显式参数导致无法走 RPC 时需要先 `stop`。
|
||
|
||
`bat` 会拒绝危险输出目录、路径逃逸和现有 symlink 路径组件；下载目标、`.part`、manifest、snapshot、PID、status、log 和控制锁文件不会跟随 symlink，daemon 状态类文件默认以 `0600` 权限创建。
|
||
|
||
非 dry-run 同步不会把新文件直接写进生产可读目录。资源会先下载到 `<output>/.staging/<id>`，完成 manifest、BLAKE3、ZIP 和官方 `.hash` 校验后移动到 `<output>/versions/<id>`，再原子切换 `<output>/current` symlink；生产读取方应只读取 `<output>/current`。
|
||
|
||
资源操作命令默认输出人类可读摘要，并在没有显式 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` 会以只读方式检查当前官方计划、`current` 指向的 active release 中 download manifest 的 size+BLAKE3、ZIP 结构，以及本地已有官方 seed `.bytes/.hash` 对的 xxHash32；发现缺失、远端变化或本地损坏会返回非 0。`repair` 会在异常资源存在时复用当前同步链路重新下载必要文件。`clean-stable` 只清理 `.part`、临时状态文件、失效或损坏的 PID/锁/socket，不删除正式资源。
|
||
|
||
下载失败会按 curl exit 和 HTTP 状态分类：403/404/普通 4xx 视为不可重试，5xx、429、DNS、连接、超时、中断和网络类错误会按尝试次数重试。某个 URL 最终失败后会写入 `<output>/current` 或 staging 下的 `official-download-quarantine.json`，stderr progress、daemon status 和 `bat-events.jsonl` 会记录失败类型、HTTP 状态、是否可重试、尝试次数和 quarantine 状态；同步会中断并阻止发布不完整资源。旧 launcher 包下载路径会在官方 primary CDN 失败后切换官方 backup CDN。
|
||
|
||
CLI 默认启动时会向 stderr 打印 `BlueArchiveToolkit` ASCII banner，并继续把阶段进度日志写到 stderr，例如自动发现、拉取 catalog、audit、总体下载进度、单文件下载进度、校验结果摘要、snapshot 和 publish；命令结果默认以人类可读摘要写到 stdout。需要给上层程序保留稳定结构化输出时加 `--json --no-progress`，只想关闭横幅但保留日志时可加 `--no-banner`。
|
||
|
||
真实官方网络全量拉取 smoke 已固化为可重复命令，默认使用 `/tmp/bat-official-smoke-<UTC timestamp>/` 隔离目录，不会写入已有客户端、生产目录或开发机人工维护资源目录：
|
||
|
||
```bash
|
||
scripts/official-full-pull-smoke.sh
|
||
|
||
# 或
|
||
make official-smoke
|
||
```
|
||
|
||
该 smoke 会执行 dry-run plan、首次全量拉取、二次 `up_to_date` 检查、本地文件破坏后的 `repair`、repair 后 `verify`，并在 `report/SMOKE_REPORT.md` 记录命令、输出目录、active release、文件数量、release 大小和被破坏文件。大型官方资源文件不纳入 Git。
|
||
|
||
生产资源输出目录必须使用独立目录，不要指向已有客户端目录，也不要指向 `/home/wanye/D/BlueArchive` 这类人工维护或开发资源目录。需要覆盖默认位置时，用 `--output <资源目录>`；需要覆盖后台状态目录时，用 `--state-dir <状态目录>`。
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
- Rust：CAS、官方资源同步核心、AssetBundle/Patch 引擎、FFI。
|
||
- Go：计划中的最小 CLI、服务编排、API Server、SDK；当前仅有 FFI 包骨架。
|
||
- PostgreSQL：计划中的服务端主数据库。
|
||
- Redis：计划中的缓存、队列状态、限流和短期锁。
|
||
- Vue 3 + TypeScript：计划中的 Web 管理后台。
|
||
- Docker / Docker Compose：数据库和后续服务部署配置。
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
BlueArchiveToolkit/
|
||
├── core/ # Rust 领域模型和仓储接口
|
||
├── adapters/ # Rust 适配器框架与官方资源规则
|
||
├── infrastructure/ # Rust 基础设施、官方同步、CAS/ResourceRepository 适配
|
||
├── crates/ # Rust 引擎 crate
|
||
│ ├── bat-cas-engine/
|
||
│ ├── bat-assetbundle/
|
||
│ ├── bat-patch/
|
||
│ └── bat-ffi/
|
||
├── internal/ffi/ # Go 调用 Rust FFI 的早期包装
|
||
├── cmd/ # Go CLI 入口，尚未实现
|
||
├── pkg/ # Go SDK 包，尚未实现
|
||
├── api/ # API 定义，尚未实现
|
||
├── web/ # Web 管理后台，尚未实现
|
||
├── deployments/ # Docker 和部署配置
|
||
├── docs/ # 文档、历史报告和分析资料
|
||
├── Cargo.toml
|
||
├── go.mod
|
||
└── Makefile
|
||
```
|
||
|
||
---
|
||
|
||
## 开发优先级
|
||
|
||
近期优先级：
|
||
|
||
1. 落地 Go CLI 最小可用入口：`bat doctor`、`bat sync --help`、Rust 同步命令包装。
|
||
2. 补齐 AssetBundle UnityFS header/block/directory 解析。
|
||
3. 扩展 Addressables catalog 解析覆盖，继续用真实形态 fixture/golden 锁定行为。
|
||
4. 将官方同步结果接入 CAS + ResourceRepository 的用户级工作流。
|
||
5. 按 smoke runbook 在具备网络和磁盘窗口的环境中执行真实官方全量拉取，并保留本地报告。
|
||
|
||
不建议在 Go CLI、资源解析和文本提取基础能力完成前优先开发 Web UI。
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
本项目采用 MIT 许可证，见 [LICENSE](LICENSE)。
|