docs: align project status with official sync pipeline

Update the authoritative docs, guides, architecture notes, gap list, deployment guidance, handoff notes, and changelog to reflect the current Rust official resource sync boundary.

CHANGELOG.md

@@ -13,10 +13,19 @@
 - 配置 Docker Compose 支持本地和远程数据库
 - 添加 Makefile 统一构建入口
 - 创建架构文档和开发指南
+- 完成 CAS V1：原子写入、BLAKE3 校验、SQLite 引用计数、GC、并发写入测试和损坏检测
+- 新增官方日服资源同步链路：auto-discover、pull plan、snapshot、marker diff、本地 manifest audit/repair
+- 新增 `bat-official-sync` Rust binary，支持 one-shot、`--watch`、默认 1 小时间隔和 JSON report
+- 新增官方资源下载校验：官方 URL 拒绝、`.part` 续传、重试、本地 size+BLAKE3、官方 seed `.hash` 校验
+- 新增 Addressables 当前真实形态 fixture/golden 测试
+- 新增 SQLite Resource Repository 和粗粒度 FFI JSON 接口
+- 补齐官方资源运行、架构、状态、缺口和交接文档
 
 ### 计划
-- [ ] 实现 CAS 存储引擎
+- [x] 实现 CAS 存储引擎
-- [ ] 实现资源同步系统
+- [x] 实现 Rust 官方资源同步核心链路
+- [ ] 实现 Go CLI 最小可用入口
+- [ ] 记录真实官方网络全量下载 smoke test
 - [ ] 实现 AssetBundle 解析器
 - [ ] 实现翻译系统
 - [ ] 实现 Patch 引擎

CURRENT_STATUS.md

@@ -1,54 +1,42 @@
 # BlueArchiveToolkit 当前工作区状态
 
-**更新时间**：2026-06-29  
+- **更新时间**：2026-07-06
-**状态来源**：本地工作区盘点与命令验证  
+- **状态来源**：本地工作区盘点、代码验证和最新提交
-**状态分支**：`experiment`  
+- **状态分支**：`experiment`
-**权威计划**：`PROJECT_PLAN.md`
+- **最新功能提交**：`789402c feat: add official resource sync pipeline`
+- **权威计划**：`PROJECT_PLAN.md`
 
 ---
 
 ## 1. 总体判断
 
-当前项目处于 **稳定基线完成、CAS V1 已落地、官方资源链路验证完成、资源同步与解析待实装** 阶段。
+当前项目处于 **稳定基线完成、CAS V1 已落地、Rust 官方资源同步链路已具备最小生产运行形态、Go CLI/API/Web 仍未落地** 阶段。
 
-旧文档中存在 Week 3 “完成”和“回滚”两类互相冲突的报告。以当前代码为准，历史 Week 3 不再作为状态依据；当前 CAS V1 已由新实现接管，AssetBundle、Patch、Go CLI/API/Web 仍有明显占位或未实现部分。
+Rust 侧官方日服资源链路已经从实验验证推进到正式入口：
+
+1. 首次运行可以通过 `--auto-discover` 从官方 HTTP metadata 解析 `GameMainConfig`，自动获得 `app-version`、`connection-group` 和 `server-info`。
+2. 不安装、不启动、不依赖已安装官方启动器。
+3. 默认平台为 `Windows + Android`。
+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 小时检查一次；远端和本地一致时默认静默。
+8. 非 dry-run 使用 `--output/.official-sync.lock` 防止并发写同一状态目录。
+
+仍需明确：这不是完整产品完成。Go CLI 最小入口、完整 AssetBundle 解析、Patch、翻译系统、API Server 和 Web 仍是后续工作；真实官方网络全量下载 smoke test 尚未记录在仓库文档中。
 
 ---
 
-## 2. 工作区整理结果
+## 2. 权威文档入口
 
-### 根目录保留
+- `README.md`：项目概览、当前可用能力和快速验证。
+- `PROJECT_PLAN.md`：最终目标、里程碑和近期任务。
+- `DOCS_INDEX.md`：文档阅读顺序和索引。
+- `docs/guides/official-resource-test-pull.md`：官方资源拉取与自动更新用户指南。
+- `docs/architecture/official-resource-backend.md`：官方资源后端设计和审核说明。
+- `docs/reports/CURRENT_GAPS.md`：当前缺口和关闭顺序。
 
-根目录现在主要保留入口文件和工程配置：
+历史 Week 2/Week 3 报告只作追溯，不再代表当前状态。
-
-- `README.md`
-- `PROJECT_PLAN.md`
-- `CURRENT_STATUS.md`
-- `DOCS_INDEX.md`
-- `CHANGELOG.md`
-- `CLAUDE.md`
-- `Cargo.toml`
-- `Cargo.lock`
-- `go.mod`
-- `Makefile`
-- `LICENSE`
-
-### 已归档
-
-历史阶段报告已移动到：
-
-- `docs/reports/historical/root/`
-- `docs/reports/historical/week2/`
-- `docs/reports/historical/week3/`
-- `docs/reports/historical/build-logs/`
-- `docs/reports/historical/quality/`
-- `docs/reports/historical/nested-docs/`
-
-原先误嵌套的 `docs/docs/archive` 已合并到：
-
-- `docs/archive/`
-
-原先空的重复目录 `docs/docs` 和 `docs/adapters` 已删除。
 
 ---
 
@@ -68,7 +56,7 @@
 
 ### `bat-core`
 
-状态：**接口和领域骨架基本完成**
+状态：**领域模型和仓储接口骨架可用**
 
 已包含：
 
@@ -88,22 +76,21 @@
 
 ### `bat-adapters`
 
-状态：**适配器框架可用，真实解析能力不足**
+状态：**适配器框架可用，官方日服规则和 Addressables 当前样本解析已推进**
 
 已包含：
 
 - Unity adapter trait、注册表、Unity 2021.3 adapter 骨架。
 - Manifest driver trait、Addressables driver、注册表。
-- Client integration、backup、discovery trait。
+- Addressables JSON catalog 的 path、hash、size、address、dependencies、metadata 解析。
+- 真实形态 Addressables fixture/golden 测试。
+- 官方日服 `server-info`、URL 规则、平台 discovery 和 inventory 枚举。
 
 待完成：
 
 - Unity bundle parse/serialize 仍是后续阶段能力。
-- Addressables Catalog 复杂字段解析未完成。
+- Addressables parser 仍需继续覆盖更多官方 catalog 结构变体和失败诊断。
 - 客户端发现、备份、应用补丁流程尚未连接真实实现。
-- 官方资源 pull plan / update check 已明确 Linux 生产路径：显式 `--auto-discover` 或已审计 metadata snapshot，不安装、不执行官方启动器。
-- 官方 launcher bootstrap、GameMainConfig bootstrap 保留为底层显式开发/审计辅助路径。
-- 官方 bootstrap / pull 测试夹具已收敛到 `experiment` 分支语义下，并通过了官方链路回归。
 
 ### `bat-cas-engine`
 
@@ -127,6 +114,26 @@
 - 未来需要时扩展流式大文件写入。
 - 未来需要时扩展非 SQLite 元数据后端。
 
+### `bat-infrastructure`
+
+状态：**CAS 适配层、ResourceRepository 和官方资源同步入口可用**
+
+已包含：
+
+- `FileSystemCasRepository` 作为 `bat-core::CasRepository` 适配层。
+- `InMemoryResourceRepository`。
+- `SqliteResourceRepository`。
+- 官方 pull plan 构建。
+- `OfficialResourcePullService`：官方 URL 拒绝策略、目标路径映射、下载 manifest、`.part` 续传、重试、官方 seed `.hash` 校验。
+- `OfficialUpdateService`：官方 metadata auto-discover、bootstrap cache、snapshot diff、marker diff、本地 audit/repair。
+- `bat-official-sync`：正式 CLI binary，支持 one-shot 和 `--watch`。
+
+待完成：
+
+- 将官方同步下载结果作为用户级流程自动导入 CAS + ResourceRepository。
+- 为真实线上全量下载建立受控 smoke test 记录。
+- 增加更多失败恢复和权限场景测试。
+
 ### `bat-assetbundle`
 
 状态：**占位**
@@ -160,88 +167,110 @@
 
 ### `bat-ffi`
 
-状态：**骨架**
+状态：**粗粒度 JSON API 可用，稳定边界仍需继续收敛**
 
-已能编译并引用 Rust 引擎 crate，但尚未提供完整稳定 FFI API。
+已包含：
+
+- `bat_version`。
+- `bat_manifest_inspect_json`：解析 Addressables manifest 并返回 JSON summary。
+- `bat_sync_plan_json`：根据 current/previous snapshot 生成官方同步计划 JSON。
+- `internal/ffi/ffi.go` 提供 Go 包装骨架。
+
+待完成：
+
+- Go CLI 调用链路。
+- 错误码与结构化响应约定。
+- 发布用头文件、构建脚本和跨平台产物。
 
 ### Go / API / Web
 
-状态：**目录存在，功能未实现**
+状态：**Go FFI 包骨架存在，CLI/API/Web 仍未实现**
 
-当前 `cmd/`、`internal/`、`pkg/`、`api/`、`web/` 多数为空目录或只有目录结构，没有 Go package 可测试。
+当前情况：
 
-`Makefile` 已调整：在 Go package 尚未实现时，Go build/test/check/fmt/lint 会明确跳过，避免误报失败。
+- `internal/ffi/ffi.go` 已存在。
+- `cmd/`、`pkg/`、`api/`、`web/` 仍无可用产品入口。
+- `go test ./...` 在没有 Go package 时可能无测试可运行；Makefile 会清晰跳过空 Go 阶段。
 
 ---
 
-## 4. 本次验证结果
+## 4. 已验证结果
 
-已运行：
+最新功能提交前已运行并通过：
 
 ```bash
-cargo test --workspace
+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
+git diff --cached --check
 ```
 
-结果：通过。
+提交后确认：
-
-已运行：
 
 ```bash
-cargo test -p bat-infrastructure --test official_game_main_config_bootstrap -- --nocapture
+git status --short
-cargo test -p bat-infrastructure
-cargo test -p bat-adapters
 ```
 
-结果：通过。
+结果：工作区干净。
 
-已运行：
+未执行：
 
-```bash
+- 真实官方网络全量下载 smoke test。
-go test ./...
+- Go CLI 端到端测试，因为 Go CLI 尚未实现。
-```
+- Web/API 测试，因为 Web/API 尚未实现。
-
-结果：当前没有 Go package，因此无测试可运行。`Makefile` 已修正为跳过该状态。
 
 ---
 
-## 5. 当前阻塞项
+## 5. 当前生产运行边界
 
-### Git 元数据
+当前唯一可作为 Linux 生产资源同步任务运行的入口是 Rust binary：
 
-原 `.git/` 是空目录，无法恢复原历史。本轮已新初始化 Git 仓库，并完成当前工作分支的整理。
+```bash
+cargo run -p bat-infrastructure --bin bat-official-sync -- \
+  --auto-discover \
+  --platforms Windows,Android \
+  --output /var/lib/bluearchive-toolkit/official \
+  --watch
+```
 
-当前状态：
+生产要求：
 
-- `git status --short --branch` 可用。
+1. 使用独立输出目录，例如 `/var/lib/bluearchive-toolkit/official`。
-- 原历史未恢复。
+2. 不要指向已有游戏客户端目录。
-- 当前分支已切到 `experiment`，用于承载实验性 fixture 调整。
+3. 不要指向 `/home/wanye/D/BlueArchive` 这类开发或人工维护资源目录。
-- 当前分支已切到 `experiment`，用于承载实验性 fixture 调整。
+4. `--auto-discover` 可以下载官方 metadata 和临时 game zip 以解析 `GameMainConfig`，但不会安装或启动官方 launcher。
+5. systemd service、容器或 Go 进程可以负责守护 `bat-official-sync --watch`，但定时检查逻辑已经在 Rust 内部。
 
-### 核心能力未实装
+详细运行说明见 `docs/guides/official-resource-test-pull.md`。
+
+---
+
+## 6. 当前阻塞项
 
 下一阶段必须优先完成：
 
-1. Manifest 真实解析。
+1. Go CLI 最小可用入口：`bat doctor`、`bat sync --help`、Rust 官方同步命令包装。
-2. Go CLI 基础入口。
+2. 官方同步结果接入 CAS + ResourceRepository 的用户级工作流。
-3. AssetBundle 解析。
+3. AssetBundle UnityFS 基础解析。
-4. 文本提取中间格式。
+4. Addressables parser 对更多官方 catalog 结构的覆盖。
-
+5. 真实官方网络全量下载 smoke test 记录。
-不建议在这些完成前优先推进 Web UI。
+6. Patch 和翻译系统仍应后置。
 
 ---
 
-## 6. 下一步建议
+## 7. 下一步建议
 
 立即任务：
 
-1. 完成 Manifest 真实字段解析和资源模型映射。
+1. 实现 Go CLI 最小框架和 `doctor`。
-2. 落地 Go CLI 的 `doctor` 和基础命令框架。
+2. 为 `bat-official-sync` 增加发布型构建/安装说明和服务化验证。
-3. 设计 Resource Repository 的持久化 schema。
+3. 补端到端 smoke：dry-run、真实下载到隔离目录、二次运行静默 up-to-date、本地损坏后 repair。
-4. 决定哪些 experiment 改动需要回流到 `dev`。
+4. 开始 AssetBundle parser 的 UnityFS header/block/directory。
 
 ---
 
-**当前总体完成度**：约 18%  
+- **当前总体完成度**：约 22%
-**当前基线状态**：已建立可继续开发的 Git 基线。  
+- **当前基线状态**：Rust 官方资源同步链路已具备可运行闭环；产品级 CLI/API/Web 仍未完成。
-**下一工程里程碑**：Manifest 真实解析与 Go CLI 基础入口。  
+- **下一工程里程碑**：Go CLI 最小可用 + 官方同步端到端 smoke + AssetBundle 解析起步。
-**当前阶段文档**：`docs/reports/current-stage-prepush.md`

DOCS_INDEX.md

@@ -1,16 +1,18 @@
 # BlueArchiveToolkit 文档索引
 
-**更新时间**：2026-06-29  
+- **更新时间**：2026-07-06
-**说明**：本索引用于快速定位当前权威文档和历史资料。
+- **说明**：本索引用于快速定位当前权威文档和历史资料。
 
 ---
 
 ## 1. 权威入口
 
-- `README.md`：项目概览和快速开始。
+- `README.md`：项目概览、当前可用能力和快速开始。
 - `PROJECT_PLAN.md`：完整开发计划和最终目标路线图。
 - `CURRENT_STATUS.md`：当前工作区真实状态。
 - `docs/reports/CURRENT_GAPS.md`：当前实现缺口和关闭顺序。
+- `docs/guides/official-resource-test-pull.md`：官方资源拉取与自动更新用户指南。
+- `docs/architecture/official-resource-backend.md`：官方资源后端职责、工作原理和审核说明。
 - `CHANGELOG.md`：版本变更记录。
 - `CLAUDE.md`：长期开发约束和项目要求。
 
@@ -19,11 +21,10 @@
 ## 2. 架构与指南
 
 - `docs/architecture/README.md`：总体架构设计。
-- `docs/architecture/official-resource-backend.md`：官方资源后端职责、工作原理和审核说明。
 - `docs/api/README.md`：API 设计入口。
 - `docs/guides/development.md`：开发指南。
 - `docs/guides/deployment.md`：部署指南。
-- `docs/guides/official-resource-test-pull.md`：官方资源拉取用户指南。
+- `docs/guides/official-resource-test-pull.md`：官方资源拉取与自动更新用户指南。
 - `docs/reports/current-stage-prepush.md`：当前阶段说明与推送前核查记录。
 - `docs/reports/current-status-handoff.md`：给下一次对话使用的当前进度交接说明。
 - `docs/guides/baseline.md`：稳定工程基线指南。
@@ -70,27 +71,32 @@
 
 1. `CURRENT_STATUS.md`
 2. `PROJECT_PLAN.md`
-3. `docs/reports/CURRENT_GAPS.md`
+3. `docs/guides/official-resource-test-pull.md`
-4. `docs/guides/baseline.md`
+4. `docs/architecture/official-resource-backend.md`
-5. `docs/architecture/README.md`
+5. `docs/reports/CURRENT_GAPS.md`
-6. `docs/guides/development.md`
+6. `docs/guides/baseline.md`
+7. `docs/architecture/README.md`
+8. `docs/guides/development.md`
 
 ---
 
 ## 6. 状态摘要
 
-当前总体完成度约 **18%**。
+当前总体完成度约 **22%**。
 
 已完成：
 
 - Rust 领域模型和仓储接口骨架。
 - Unity/Manifest/Client 适配器框架。
-- 基础 CAS 文件系统存储。
+- CAS V1：原子写入、BLAKE3 校验、引用计数、GC、并发测试和损坏检测。
 - 文档整理和路线图重制。
-- 官方资源链路验证和实验性 fixture 收敛。
+- Rust 官方资源同步闭环：`bat-official-sync`、`--auto-discover`、`--watch`、snapshot、manifest audit/repair、官方 seed `.hash` 校验。
+- Addressables 当前真实形态 fixture/golden 覆盖。
+- SQLite Resource Repository 和粗粒度 FFI JSON 接口。
 
 优先待办：
 
-- 完成 Manifest 真实解析。
+- 落地 Go CLI 最小可用入口。
-- 启动 Go CLI 入口。
+- 记录真实官方网络全量下载 smoke test。
-- 设计 Resource Repository 持久化 schema。
+- 将官方同步结果接入 CAS + ResourceRepository 的用户级流程。
+- 开始 AssetBundle UnityFS 解析。

PROJECT_PLAN.md

@@ -1,9 +1,9 @@
 # BlueArchiveToolkit 完整开发计划
 
-**项目名称**：BlueArchiveToolkit  
+- **项目名称**：BlueArchiveToolkit
-**文档版本**：2026-06-28 重制版  
+- **文档版本**：2026-07-06 状态收口版
-**权威状态**：以本文档和 `CURRENT_STATUS.md` 为准，旧阶段报告仅作历史参考。  
+- **权威状态**：以本文档和 `CURRENT_STATUS.md` 为准，旧阶段报告仅作历史参考。
-**最终目标**：构建一个可长期维护、可扩展、可审计的 Blue Archive 资源管理、文本提取、翻译和补丁平台。
+- **最终目标**：构建一个可长期维护、可扩展、可审计的 Blue Archive 资源管理、文本提取、翻译和补丁平台。
 
 ---
 
@@ -22,7 +22,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 
 ## 2. 当前真实状态
 
-本节来自 2026-06-28 的工作区盘点和本地验证。
+本节来自 2026-07-06 的工作区盘点、本地验证和最新功能提交。
 
 ### 已具备
 
@@ -31,22 +31,30 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 3. `bat-adapters` 已实现 Unity、Manifest、Client 集成的框架和注册表。
 4. `bat-cas-engine` 已完成 CAS V1：原子写入、BLAKE3 Hash、SQLite 引用计数、GC、并发测试、损坏检测。
 5. `bat-infrastructure` 已改为 CAS 仓储适配层，不再重复实现对象存储。
-6. `bat-ffi` 已能引用 CAS、AssetBundle、Patch crates。
+6. `bat-infrastructure` 已提供官方资源 pull/update 服务，正式入口是 `bat-official-sync`。
-7. 文档已整理：根目录保留入口文档，历史报告进入 `docs/reports/historical/`，误嵌套的 `docs/docs` 已合并。
+7. `bat-official-sync` 支持 `--auto-discover`、`--watch`、默认 1 小时间隔、本地 manifest audit/repair、官方 seed `.hash` 校验和 snapshot/cache。
+8. `bat-ffi` 已提供 Manifest inspect 和官方 sync plan 的粗粒度 JSON API。
+9. 文档已整理：根目录保留入口文档，历史报告进入 `docs/reports/historical/`，误嵌套的 `docs/docs` 已合并。
 
 ### 仍是骨架或占位
 
 1. AssetBundle 解析器仍是占位 trait，未解析 UnityFS、压缩块、TypeTree 或对象表。
 2. Patch 的 Binary/JSON 模块仍返回空结果，不具备真实补丁能力。
-3. Go CLI/API/SDK 目录目前没有实际 package。
+3. Go CLI/API/SDK 仍没有产品级入口；只有 `internal/ffi` 的早期包装。
-4. Manifest 真实复杂字段解析尚未完成。
+4. Addressables parser 已覆盖当前真实形态 fixture/golden，但还不是完整 Unity Addressables/SBP catalog 兼容层。
-5. Web、数据库迁移、OpenAPI、插件加载机制尚未实现。
+5. 官方同步结果尚未作为用户级流程自动导入 CAS + ResourceRepository。
-6. 原 Git 历史未恢复；当前仓库以新初始化基线为准。
+6. 真实官方网络全量下载 smoke test 尚未记录。
+7. Web、数据库迁移、OpenAPI、插件加载机制尚未实现。
+8. 原 Git 历史未恢复；当前仓库以新初始化基线为准。
 
 ### 已验证
 
-1. `cargo test --workspace` 通过。
+1. `cargo test -p bat-adapters -- --nocapture` 通过。
-2. `go test ./...` 当前无 Go package；`Makefile` 已调整为在 Go 未实现阶段明确跳过。
+2. `cargo test -p bat-ffi -- --nocapture` 通过。
+3. `cargo test -p bat-infrastructure -- --nocapture` 通过。
+4. `cargo test -p bat-infrastructure --bin bat-official-sync -- --nocapture` 通过。
+5. `cargo run -p bat-infrastructure --bin bat-official-sync -- --help` 可用。
+6. `go test ./...` 当前无 Go 产品 package；`Makefile` 已调整为在 Go 未实现阶段明确跳过。
 
 ---
 
@@ -63,7 +71,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 ### 3.2 技术决策
 
 1. **Rust**：保留为核心引擎语言，用于 CAS、AssetBundle、Patch、完整资源拉取和更新检查核心逻辑，FFI 仅作为可选边界。
-2. **Go**：用于 CLI、同步器、API Server、任务编排、Provider 集成。
+2. **Go**：用于最小稳定 CLI、服务编排、API Server、任务编排、Provider 集成；不强制要求 Rust 核心能力必须写成库供 Go 调用。
 3. **PostgreSQL**：作为服务端主数据库，承载翻译记忆库、术语库、任务、审核和用户权限。
 4. **SQLite**：仅作为本地 CLI 可选元数据后端，必须通过仓储抽象隔离，不能绑定业务逻辑。
 5. **Redis**：用于服务端缓存、任务状态、限流和短期锁。
@@ -158,15 +166,19 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 
 **目标**：能够获取、解析和同步 Blue Archive 资源清单。
 
+**当前状态**：部分完成。Rust 官方日服资源同步链路已经具备正式 one-shot 和 `--watch` 常驻入口；Go CLI、完整解析覆盖、CAS 导入编排和真实线上 smoke 仍待完成。
+
 交付物：
 
-1. 完成 Addressables Catalog 的真实字段解析。
+1. Addressables Catalog 真实字段解析：**部分完成**。当前已覆盖 path、hash、size、address、dependencies、metadata 和真实形态 fixture/golden；仍需继续覆盖更多官方 catalog 结构变体。
-2. 定义资源版本、区域、渠道、远端 URL、Hash、大小、依赖关系模型。
+2. 资源版本、区域、渠道、远端 URL、Hash、大小、依赖关系模型：**部分完成**。`Resource` 和官方 endpoint/snapshot 模型已扩展；仍需冻结 Go CLI/API 可见模型。
-3. 实现 Go 下载器：并发、断点续传、限速、重试、校验、缓存。
+3. Rust 官方下载器：**已完成当前生产入口需要的核心能力**。包含官方 URL 校验、`.part` 续传、重试、本地 manifest size+BLAKE3 校验、官方 seed `.hash` 校验和 repair。
-4. 实现 `sync`、`manifest inspect`、`cache status`。
+4. Rust 自动更新入口：**已完成当前生产入口**。`bat-official-sync` 支持 snapshot、marker diff、bootstrap cache、one-shot、`--watch` 和默认 1 小时间隔。
-5. 将下载结果写入 CAS，并写入 Resource Repository。
+5. Go CLI：**未完成**。需要实现 `bat doctor`、`bat sync --help`、Rust 官方同步命令包装和 JSON/human 输出。
-6. Linux 生产同步支持显式 `--auto-discover` 或已审计 metadata snapshot，不依赖已安装官方启动器。
+6. 用户级 `sync`、`manifest inspect`、`cache status`：**未完成**。Rust FFI 已提供 Manifest inspect 和 sync plan JSON 边界，但 Go CLI 尚未串联。
-7. 实现自动更新检查：保存上次官方 snapshot，定期 discovery，对比变化后按需拉取。
+7. 下载结果写入 CAS + ResourceRepository：**部分完成**。CAS 和 SQLite ResourceRepository 已存在，官方同步入口尚未把完整下载结果作为用户级流程自动导入。
+8. Linux 生产同步不依赖已安装官方启动器：**已完成当前 Rust 入口**。`--auto-discover` 只使用官方 HTTP metadata 和临时目录解析 `GameMainConfig`。
+9. 真实官方网络全量下载 smoke test：**未完成记录**。需要在隔离目录执行并记录 dry-run、首次下载、二次 up-to-date 和本地损坏 repair。
 
 验收标准：
 
@@ -174,8 +186,10 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 2. 断点续传和失败重试有可重复测试。
 3. Manifest 解析失败时给出可定位的字段和偏移信息。
 4. 同一资源跨版本复用同一 CAS 对象。
-5. 生产同步入口必须显式选择 `--auto-discover` 或显式提供官方 `server-info` URL、`connection-group` 和 `app-version`，不得隐式启动 launcher/bootstrap 链路。
+5. 生产同步入口必须显式选择 `--auto-discover` 或显式提供官方 `server-info` URL、`connection-group` 和 `app-version`，不得安装或启动 launcher。
 6. 自动更新入口必须做到无变化不下载，有变化下载成功后才写入新 snapshot。
+7. `--watch` 模式必须在 Rust 内部保持持久检查能力，外部 supervisor 只负责进程守护。
+8. 真实官方网络 smoke 必须记录输出目录、命令、结果摘要和未纳入仓库的大文件位置。
 
 ---
 
@@ -352,11 +366,11 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 
 ## 5. 推荐执行顺序
 
-近期不要直接跳到 Web 或 AI Provider。项目当前的真实瓶颈是基础存储和解析能力。
+近期不要直接跳到 Web 或 AI Provider。项目当前的真实瓶颈是 Go CLI 入口、资源解析、同步结果进入 CAS/ResourceRepository，以及真实端到端验证。
 
 建议顺序：
 
-1. 完成 Milestone 3 和 4，让资源能被同步和解析。
+1. 完成 Milestone 3 剩余项和 Milestone 4，让资源能被同步、索引和解析。
 2. 完成 Milestone 5，再开始翻译系统。
 3. 完成 Milestone 6 和 7，建立可审计翻译流程。
 4. 完成 Milestone 8，形成可交付补丁。
@@ -366,12 +380,14 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 
 ## 6. 近期 10 个具体任务
 
-1. 完成 Manifest 真实解析字段和资源模型映射。
+1. 落地 Go CLI 的最小生产入口：`bat doctor`、`bat sync --help`、`bat official sync --help`。
-2. 落地 Go CLI 的最小生产入口：`bat doctor`、`bat sync --help`。
+2. 让 Go CLI 能调用 `bat-official-sync` 或 FFI/进程边界，并稳定转发 JSON report。
-3. 设计 Resource Repository 的持久化 schema 和迁移策略。
+3. 记录一次真实官方网络 smoke：dry-run、首次下载、二次 up-to-date、本地损坏 repair。
-4. 开始 AssetBundle UnityFS header/block/directory 解析。
+4. 将官方同步下载结果接入 CAS + `SqliteResourceRepository` 的用户级流程。
-5. 为 CLI 和 CAS 增加 `doctor cas` 诊断入口。
+5. 继续扩展 Addressables parser 的真实 catalog 变体覆盖和错误诊断。
-6. 更新开发指南，使安装、测试、当前限制一致。
+6. 开始 AssetBundle UnityFS header/block/directory 解析。
+7. 为 CLI 和 CAS 增加 `doctor cas` 诊断入口。
+8. 为 `bat-official-sync --watch` 增加发布型构建、systemd service 示例和运维检查清单。
 
 ---
 
@@ -401,6 +417,16 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 1. Rust 提供稳定引擎能力，不承担 CLI 编排，但负责完整资源拉取和更新检查的核心逻辑。
 2. Go 负责用户命令、最小稳定 CLI、服务编排、网络和 Provider。
 3. 跨边界优先进程或 SDK，FFI 只作为可选的粗粒度、安全、可测试 API。
+4. Rust 不需要被强制写成 Go 调用库；当前 `bat-official-sync --watch` 是允许长期运行的 Rust 生产任务。
+
+### 官方资源真实下载风险
+
+处理策略：
+
+1. 所有真实下载必须写入隔离输出目录。
+2. 不允许把 `/home/wanye/D/BlueArchive` 或已安装客户端目录当作开发输出目录。
+3. smoke test 只记录命令、状态和摘要，不把大体积官方资源纳入 Git。
+4. 下载成功后必须通过 `official-download-manifest.json` audit 和官方 seed `.hash` 校验报告确认。
 
 ### 过早做 Web
 
@@ -413,11 +439,11 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 
 ## 8. 当前完成度评估
 
-按最终目标计算，当前总体完成度约为 **18%**。
+按最终目标计算，当前总体完成度约为 **22%**。
 
-已完成的是稳定基线、架构骨架、部分接口和 CAS V1，不是完整产品能力。下一阶段的关键不是继续堆目录，而是把 Manifest、CLI 基础入口和 AssetBundle 解析链路做实。
+已完成的是稳定基线、架构骨架、部分接口、CAS V1 和 Rust 官方资源同步闭环，不是完整产品能力。下一阶段的关键不是继续堆目录，而是把 Go CLI 最小入口、官方同步端到端验证、CAS/ResourceRepository 编排和 AssetBundle 解析链路做实。
 
 ---
 
-**下一份应更新文档**：`CURRENT_STATUS.md`  
+- **下一份应更新文档**：真实官方网络 smoke 记录
-**下一项工程任务**：完成 Manifest 真实解析和 Go CLI 基础入口。
+- **下一项工程任务**：Go CLI 最小可用入口和官方同步端到端 smoke。

README.md

@@ -2,64 +2,97 @@
 
 **BlueArchiveToolkit** 是一个面向长期维护的 Blue Archive 资源管理、解析、翻译和补丁工具套件。
 
-当前项目仍处于早期开发阶段：Rust 领域模型、适配器框架和生产级 CAS V1 已经存在；资源同步、完整 AssetBundle 解析、翻译系统、Patch、CLI、API Server 和 Web 后台仍在持续完善。当前官方资源实验与推送准备在 `experiment` 分支进行。
+当前仓库仍不是完整产品，但 Rust 侧已经具备一条可运行的官方日服资源同步链路：可以在 Linux 上通过官方 HTTP metadata 自动发现资源入口，拉取 Windows + Android 官方资源，保存同步 snapshot，校验本地下载清单，并用 `--watch` 常驻定期检查更新。Go CLI、API Server、Web、完整 AssetBundle 解析、翻译系统和 Patch 系统仍在后续阶段。
 
 ---
 
-## 项目目标
+## 当前可用
-
-最终系统计划支持：
-
-- 资源同步：Manifest、版本管理、增量同步、Hash 校验、断点续传、重试、缓存。
-- CAS 存储：内容寻址、去重、引用计数、垃圾回收、多版本共享、完整性校验。
-- Unity AssetBundle：插件化解析 TextAsset、Localization、MonoBehaviour、ScriptableObject 等资源。
-- 文本提取：剧情、UI、系统文本、配置文本的标准化导出。
-- 翻译系统：Translation Memory、Glossary、AI Provider、审核流、历史记录。
-- Patch 系统：增量 Patch、Binary Patch、JSON Patch、Rollback、Integrity Check。
-- CLI / API / Web / SDK：提供本地工具、服务端接口、管理后台和外部集成能力。
-
----
-
-## 当前状态
-
-已具备：
 
 - Rust workspace 和 monorepo 结构。
 - `bat-core` 领域对象和仓储接口骨架。
-- `bat-adapters` Unity、Manifest、Client 集成框架。
+- `bat-adapters` Unity、Manifest、Client 集成框架，以及当前真实形态 Addressables catalog 解析覆盖。
-- `bat-cas-engine` CAS V1：原子写入、Hash 校验、引用计数、GC、并发写入测试、损坏检测。
+- `bat-cas-engine` CAS V1：原子写入、BLAKE3 校验、引用计数、GC、并发写入测试、损坏检测。
-- `bat-infrastructure` CAS 仓储适配层。
+- `bat-infrastructure` CAS 适配层、SQLite Resource Repository、官方资源 pull/update 服务。
-- `bat-ffi` 基础 crate 边界。
+- `bat-official-sync`：官方资源自动发现、全量拉取、本地 manifest audit/repair、`.part` 断点续传、官方 seed `.hash` 校验、snapshot/cache、`--watch` 常驻更新。
-- 官方日服资源 auto-discover、pull plan、update check 用户流程；launcher bootstrap 仅作为底层显式开发/审计辅助路径。
+- `bat-ffi` 粗粒度 JSON 接口：Manifest inspect 和官方 sync plan。
-- 文档路线图和当前缺口清单。
+- 文档路线图、当前状态、缺口清单、官方资源运行指南。
-- 当前阶段说明与推送前核查文档。
 
-未完成：
+仍未完成：
 
-- 真实 AssetBundle 解析。
+- Go CLI 最小可用入口。
+- 完整 UnityFS / AssetBundle 解析。
 - 真实 Patch apply/diff。
-- Go CLI、API Server、SDK。
-- Web 管理后台。
 - Translation Memory、Glossary、AI Provider。
+- API Server、SDK、Web 管理后台。
+- 真实官方网络全量下载 smoke test 尚未在本仓库记录。
 
 详细状态见：
 
 - [当前状态](CURRENT_STATUS.md)
 - [完整开发计划](PROJECT_PLAN.md)
-- [当前缺口清单](docs/reports/CURRENT_GAPS.md)
 - [文档索引](DOCS_INDEX.md)
-- [当前阶段说明](docs/reports/current-stage-prepush.md)
+- [当前缺口清单](docs/reports/CURRENT_GAPS.md)
+- [官方资源拉取与自动更新指南](docs/guides/official-resource-test-pull.md)
+- [官方资源后端说明](docs/architecture/official-resource-backend.md)
+
+---
+
+## 快速验证
+
+前置要求：
+
+- Rust 1.75+
+- Go 1.22+
+- `curl`
+- `unzip`，仅 `--auto-discover` 在 launcher metadata 变化并需要解析 `GameMainConfig` 时使用
+
+运行当前主要测试：
+
+```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-official-sync -- --nocapture
+```
+
+查看官方同步命令：
+
+```bash
+cargo run -p bat-infrastructure --bin bat-official-sync -- --help
+```
+
+只做官方资源更新判断，不写同步状态：
+
+```bash
+cargo run -p bat-infrastructure --bin bat-official-sync -- \
+  --auto-discover \
+  --platforms Windows,Android \
+  --output /tmp/ba-official-update \
+  --dry-run
+```
+
+常驻自动更新，默认每 1 小时检查一次；远端和本地一致时静默：
+
+```bash
+cargo run -p bat-infrastructure --bin bat-official-sync -- \
+  --auto-discover \
+  --platforms Windows,Android \
+  --output /tmp/ba-official-update \
+  --watch
+```
+
+生产输出目录必须使用独立状态目录，不要指向已有客户端目录，也不要指向 `/home/wanye/D/BlueArchive` 这类人工维护或开发资源目录。
 
 ---
 
 ## 技术栈
 
-- Rust：CAS、AssetBundle、Patch、FFI 等核心引擎。
+- Rust：CAS、官方资源同步核心、AssetBundle/Patch 引擎、FFI。
-- Go：CLI、资源同步、API Server、任务编排、SDK。
+- Go：计划中的最小 CLI、服务编排、API Server、SDK；当前仅有 FFI 包骨架。
-- PostgreSQL：服务端主数据库。
+- PostgreSQL：计划中的服务端主数据库。
-- Redis：缓存、队列状态、限流和短期锁。
+- Redis：计划中的缓存、队列状态、限流和短期锁。
-- Vue 3 + TypeScript：Web 管理后台。
+- Vue 3 + TypeScript：计划中的 Web 管理后台。
-- Docker / Docker Compose：本地开发和部署。
+- Docker / Docker Compose：数据库和后续服务部署配置。
 
 ---
 
@@ -68,15 +101,15 @@
 ```text
 BlueArchiveToolkit/
 ├── core/                  # Rust 领域模型和仓储接口
-├── adapters/              # Rust 适配器框架
+├── adapters/              # Rust 适配器框架与官方资源规则
-├── infrastructure/        # 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 入口，尚未实现
-├── internal/              # Go 内部包，尚未实现
 ├── pkg/                   # Go SDK 包，尚未实现
 ├── api/                   # API 定义，尚未实现
 ├── web/                   # Web 管理后台，尚未实现
@@ -89,42 +122,17 @@ BlueArchiveToolkit/
 
 ---
 
-## 本地验证
-
-前置要求：
-
-- Rust 1.75+
-- Go 1.22+
-- Docker 与 Docker Compose，后续数据库开发需要
-
-当前可运行的主要验证命令：
-
-```bash
-cargo test --workspace
-```
-
-也可以使用 Makefile：
-
-```bash
-make help
-make test
-make check
-```
-
-说明：Go CLI/API 尚未实现，因此 Makefile 中的 Go build/test/check/fmt/lint 会在没有 Go package 时明确跳过。
-
----
-
 ## 开发优先级
 
 近期优先级：
 
-1. 完成 Manifest 真实解析。
+1. 落地 Go CLI 最小可用入口：`bat doctor`、`bat sync --help`、Rust 同步命令包装。
-2. 启动 Go CLI 的 `doctor` 和基础命令框架。
+2. 补齐 AssetBundle UnityFS header/block/directory 解析。
-3. 设计 Resource Repository 的持久化 schema。
+3. 扩展 Addressables catalog 解析覆盖，继续用真实形态 fixture/golden 锁定行为。
-4. 开始 AssetBundle 解析框架实装。
+4. 将官方同步结果接入 CAS + ResourceRepository 的用户级工作流。
+5. 执行并记录一次真实官方网络全量下载 smoke test。
 
-不建议在 Manifest、AssetBundle 和文本提取基础能力完成前优先开发 Web UI。
+不建议在 Go CLI、资源解析和文本提取基础能力完成前优先开发 Web UI。
 
 ---
 

docs/api/README.md

@@ -2,9 +2,11 @@
 
 本目录包含 BlueArchive Toolkit 的 API 文档。
 
+当前 API Server 尚未实现，本文件只记录规划边界，不代表已有可运行 HTTP 服务或 OpenAPI 产物。
+
 ## OpenAPI 规范
 
-OpenAPI 文档位于 `openapi/` 目录，使用 OpenAPI 3.0 标准。
+OpenAPI 文档将在 API Server 落地后生成，目标使用 OpenAPI 3.0 标准。当前仓库尚未提供 `openapi/` 生成产物。
 
 ## 文档生成
 
@@ -43,4 +45,4 @@ API 文档将在开发过程中自动生成和更新。
 
 ---
 
-更多详细文档将在 Phase 6 实现 API Server 时补充。
+更多详细文档将在 API Server 实现后补充。

docs/architecture/README.md

@@ -4,12 +4,14 @@
 
 BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建一个可持续维护十年以上的工业级开源项目。
 
-当前文档描述目标架构。实际实现状态以根目录 `CURRENT_STATUS.md` 和 `PROJECT_PLAN.md` 为准。
+当前文档描述目标架构和已经落地的关键边界。实际实现状态以根目录 `CURRENT_STATUS.md` 和 `PROJECT_PLAN.md` 为准。
 
 当前已经可用的官方资源入口包括：
 
-- `infrastructure/examples/official_pull_plan.rs`：Linux 生产资源拉取路径，显式读取官方 `server-info` 输入。
+- `infrastructure/src/bin/bat_official_sync.rs`：Linux 官方资源同步正式入口，支持 one-shot 和 `--watch` 常驻更新。
-- `infrastructure/examples/official_update_check.rs`：Linux 自动更新检查入口，保存 snapshot 并按需拉取。
+- `infrastructure/src/official_update.rs`：官方自动更新核心服务，负责 auto-discover、snapshot、marker diff、本地 audit/repair。
+- `infrastructure/examples/official_pull_plan.rs`：开发/审计用 pull plan 入口。
+- `infrastructure/examples/official_update_check.rs`：历史/开发入口，生产优先使用 `bat-official-sync`。
 - `infrastructure/examples/official_launcher_bootstrap.rs`：显式开发/审计辅助路径，用于核查官方 launcher metadata，不是生产运行依赖。
 - `docs/guides/official-resource-test-pull.md`
 
@@ -33,14 +35,14 @@ BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建
 
 | 模块 | 语言 | 理由 |
 |------|------|------|
-| CLI、API Server、下载器 | Go | 并发模型优秀、部署简单、生态成熟 |
+| CLI、API Server、服务编排 | Go | 并发模型优秀、部署简单、生态成熟 |
-| AssetBundle 解析、Patch 引擎、CAS 引擎 | Rust | 零成本抽象、内存安全、性能极致 |
+| 官方资源同步核心、AssetBundle 解析、Patch 引擎、CAS 引擎 | Rust | 零成本抽象、内存安全、性能和二进制处理更可靠 |
 | Web 管理后台 | Vue 3 + TypeScript | 渐进式、类型安全、生态完善 |
 
 ### 3. 数据流设计
 
 ```
-用户请求 → CLI/API → Go 业务层 → Rust 核心层 → CAS 存储 → 数据库
+用户请求 → CLI/API → Go 业务层 → Rust 核心/同步层 → CAS 存储 → 数据库
          ↓                    ↓
       Web UI              缓存层 (Redis)
 ```
@@ -89,25 +91,41 @@ cas/
 
 ---
 
-### 2. 资源同步器 (Go)
+### 2. 官方资源同步器 (Rust 当前实现，Go 后续编排)
 
-**职责**：从游戏服务器下载资源、增量更新、完整性校验
+**职责**：从官方日服 HTTP metadata 自动发现资源入口，下载 Windows + Android 官方资源，增量检查，完整性校验，保持本地状态。
+
+**当前实现**：
+
+- `OfficialUpdateService`：auto-discover、snapshot、marker diff、本地 manifest audit/repair。
+- `OfficialResourcePullService`：官方 URL 校验、`.part` 断点续传、重试、下载 manifest、官方 seed `.hash` 校验。
+- `bat-official-sync`：正式 binary，支持 one-shot 和 `--watch`。
+
+**当前数据流**：
 
-**架构**：
 ```
-Manifest Parser → Version Manager → Downloader → CAS Storage
+官方 metadata → GameMainConfig → server-info → discovery endpoints
      ↓
-                              Task Queue (多线程)
+seed catalog → inventory → pull plan → downloader → output directory
      ↓
-                              Progress Reporter
+official-sync-snapshot.json + official-download-manifest.json
 ```
 
-**特性**：
+**已具备特性**：
-- 多线程并发下载
+
-- 断点续传（Range 请求）
+- 不安装、不执行官方 launcher。
-- 自动重试机制（指数退避）
+- 默认平台 `Windows + Android`。
-- 限速支持
+- `--auto-discover` 自动获取 `app-version`、`connection-group` 和 `server-info`。
-- Hash 校验（下载后立即验证）
+- `--watch` 常驻检查，默认 1 小时。
+- 远端 marker 无变化且本地 manifest clean 时不下载。
+- 本地文件损坏时 repair。
+- 官方 seed `.hash` 强校验；Addressables `catalog_*.hash` 作为变更 marker。
+
+**后续 Go 职责**：
+
+- 提供最小稳定 CLI。
+- 包装或调用 Rust 同步入口，转发 JSON report。
+- 编排 API Server、任务队列、Provider 和用户配置。
 
 ---
 
@@ -369,7 +387,10 @@ API Server (多实例)
 更多详细设计文档：
 
 - [官方资源后端说明](./official-resource-backend.md)
-- [CAS 存储引擎设计](./cas-storage.md)
-- [AssetBundle 解析器设计](./assetbundle-parser.md)
-- [翻译系统设计](./translation-system.md)
 - [API 设计](../api/README.md)
+
+待创建的详细设计文档：
+
+- `docs/architecture/cas.md`
+- `docs/architecture/assetbundle.md`
+- `docs/architecture/translation.md`

docs/architecture/official-resource-backend.md

@@ -233,16 +233,15 @@ Linux 生产路径：
 - 下载层能在本地文件 size/BLAKE3/path 或 manifest 不匹配时重新下载
 - 官方 seed `.hash` mismatch 会导致下载失败，而不是降级为本地 BLAKE3 猜测
 - 非官方 URL 会在 fetch/download 入口被拒绝
+- 尚未在仓库中记录真实官方网络全量下载 smoke test
 
 相关验证主要来自：
 
-- `cargo test -p bat-adapters`
+- `cargo test -p bat-adapters -- --nocapture`
-- `cargo test -p bat-infrastructure`
+- `cargo test -p bat-ffi -- --nocapture`
-- `cargo test -p bat-adapters --examples`
+- `cargo test -p bat-infrastructure -- --nocapture`
-- `cargo test -p bat-infrastructure --examples`
 - `cargo test -p bat-infrastructure --bin bat-official-sync -- --nocapture`
-- `cargo clippy -p bat-adapters -- -D warnings`
+- `cargo run -p bat-infrastructure --bin bat-official-sync -- --help`
-- `cargo clippy -p bat-infrastructure -- -D warnings`
 
 ## 6. 审核重点
 

docs/guides/baseline.md

@@ -1,7 +1,7 @@
 # 稳定工程基线指南
 
-**更新时间**：2026-06-28  
+- **更新时间**：2026-07-06
-**目标**：让工作区处于可继续开发核心功能的可信状态。
+- **目标**：让工作区处于可继续开发核心功能的可信状态。
 
 ---
 
@@ -17,6 +17,7 @@
 6. 当前缺口有集中清单和关闭顺序。
 7. 架构边界有 ADR 记录。
 8. 基础验证命令通过。
+9. Rust 官方资源同步入口有明确运行文档和生产边界。
 
 ---
 
@@ -40,9 +41,10 @@ cargo clippy --workspace -- -D warnings
 
 说明：
 
-1. 当前没有 Go package，因此 Go build/test/check/fmt/lint 会明确跳过。
+1. 当前没有 Go 产品入口，因此 Go build/test/check/fmt/lint 会在空 Go 阶段明确跳过。
 2. 如果后续新增 Go package，必须让 `go test ./...` 和 `go vet ./...` 纳入硬性验证。
 3. 当前 `golangci-lint` 可选；当 Go 代码进入主要开发阶段后，应纳入 CI。
+4. 官方同步相关修改必须额外运行 `cargo test -p bat-infrastructure --bin bat-official-sync -- --nocapture`。
 
 ---
 
@@ -84,16 +86,19 @@ git check-ignore -v Cargo.lock CLAUDE.md
 
 ## 5. 下一阶段入口
 
-CAS V1 完成后，下一阶段优先推进：
+CAS V1 和 Rust 官方同步闭环完成后，下一阶段优先推进：
 
-1. Manifest 真实解析。
+1. Go CLI 的 `doctor` 和基础命令框架。
-2. Go CLI 的 `doctor` 和基础命令框架。
+2. 真实官方网络全量下载 smoke 记录。
-3. Resource Repository 持久化 schema。
+3. 官方同步结果接入 CAS + ResourceRepository。
+4. AssetBundle UnityFS 解析。
 
 优先阅读：
 
 1. `PROJECT_PLAN.md`
 2. `CURRENT_STATUS.md`
 3. `docs/reports/CURRENT_GAPS.md`
-4. `docs/architecture/adr/0001-engine-and-application-boundaries.md`
+4. `docs/guides/official-resource-test-pull.md`
-5. `docs/architecture/adr/0002-cas-v1-design-boundary.md`
+5. `docs/architecture/official-resource-backend.md`
+6. `docs/architecture/adr/0001-engine-and-application-boundaries.md`
+7. `docs/architecture/adr/0002-cas-v1-design-boundary.md`

docs/guides/deployment.md

@@ -2,11 +2,11 @@
 
 ## 架构概览
 
-BlueArchive Toolkit 支持多种部署模式：
+BlueArchive Toolkit 的部署文档分为当前可用模式和目标模式：
 
-1. **本地开发模式**：代码在本地，连接远程数据库
+1. **本地开发模式**：代码在本地，连接本地或远程数据库。
-2. **单机部署**：所有组件运行在一台服务器
+2. **官方资源同步生产任务**：当前可用，运行 Rust `bat-official-sync --watch`。
-3. **分布式部署**：多实例 API Server + 独立数据库服务器
+3. **完整单机/分布式部署**：目标模式，等待 API Server、数据库迁移和 Web 实现后补齐。
 
 ---
 
@@ -98,9 +98,98 @@ REDIS_PORT=6379
 
 ---
 
-## 模式 3：生产环境部署
+## 模式 3：官方资源同步生产任务
 
-待补充（Phase 6 实现 API Server 后）
+当前可部署的生产任务是 Rust 官方资源同步 binary。API Server 和 Web 尚未实现，不能按完整服务端产品部署。
+
+### 构建
+
+```bash
+cargo build --release -p bat-infrastructure --bin bat-official-sync
+```
+
+产物：
+
+```text
+target/release/bat-official-sync
+```
+
+### 目录约定
+
+推荐生产状态目录：
+
+```text
+/var/lib/bluearchive-toolkit/official/
+```
+
+该目录会保存：
+
+- `official-sync-snapshot.json`
+- `official-bootstrap-cache.json`
+- `official-download-manifest.json`
+- `.official-sync.lock`
+- 下载得到的官方资源文件
+
+不要把输出目录设为：
+
+- 已安装游戏客户端目录
+- 官方启动器安装目录
+- 开发机现有资源目录，例如 `/home/wanye/D/BlueArchive`
+- Git 工作区目录
+
+### 一次性检查
+
+```bash
+/opt/bluearchive-toolkit/bin/bat-official-sync \
+  --auto-discover \
+  --platforms Windows,Android \
+  --output /var/lib/bluearchive-toolkit/official \
+  --dry-run
+```
+
+### 常驻自动更新
+
+```bash
+/opt/bluearchive-toolkit/bin/bat-official-sync \
+  --auto-discover \
+  --platforms Windows,Android \
+  --output /var/lib/bluearchive-toolkit/official \
+  --watch
+```
+
+`--watch` 是 Rust 内部持久检查模式，默认每 1 小时执行一次检查。远端和本地一致时默认静默；有远端变化或本地文件损坏时自动下载或 repair，并输出 JSON report。
+
+### systemd service 示例
+
+systemd 只负责进程守护，不负责定时逻辑：
+
+```ini
+[Unit]
+Description=BlueArchiveToolkit official resource sync
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=bat
+Group=bat
+ExecStart=/opt/bluearchive-toolkit/bin/bat-official-sync --auto-discover --platforms Windows,Android --output /var/lib/bluearchive-toolkit/official --watch
+Restart=on-failure
+RestartSec=30
+StateDirectory=bluearchive-toolkit
+NoNewPrivileges=true
+
+[Install]
+WantedBy=multi-user.target
+```
+
+如果业务层需要热更新、热重载或发布新资源，应该由上层服务在观察到 JSON report 或 snapshot 变化后决定。Rust 同步进程只负责拉取、校验和维护本地状态。
+
+---
+
+## 模式 4：完整生产环境部署
+
+待补充（API Server、数据库迁移和 Web 实现后）
 
 ---
 
@@ -172,4 +261,4 @@ docker exec bat-redis redis-cli ping
 
 ---
 
-更多问题请查看 [故障排查指南](./troubleshooting.md)（待创建）
+更多当前状态请查看 `CURRENT_STATUS.md`、`docs/reports/CURRENT_GAPS.md` 和本文件中的健康检查命令。

docs/guides/development.md

@@ -104,26 +104,45 @@ git push origin feature/your-feature-name
 
 ## 测试
 
-### 单元测试
+### 当前必跑测试
 
 ```bash
-# Go
+cargo test -p bat-adapters -- --nocapture
-go test ./...
+cargo test -p bat-ffi -- --nocapture
-
+cargo test -p bat-infrastructure -- --nocapture
-# Rust
+cargo test -p bat-infrastructure --bin bat-official-sync -- --nocapture
-cargo test
 ```
 
+Go CLI 尚未实现时，`go test ./...` 可能没有产品级 package 可运行；Makefile 会在空 Go 阶段清晰跳过。
+
 ### 集成测试
 
 ```bash
-# 需要先启动数据库
+cargo test --workspace
-make dev
-
-# 运行集成测试
-go test -tags=integration ./...
 ```
 
+带真实本地资源的测试默认不应启用。只有在明确需要时，才通过对应 `BAT_REAL_*` 环境变量读取隔离样本路径。不要默认读取 `/home/wanye/D/BlueArchive` 或任何已有客户端目录。
+
+### 官方资源同步手动检查
+
+查看参数：
+
+```bash
+cargo run -p bat-infrastructure --bin bat-official-sync -- --help
+```
+
+dry-run：
+
+```bash
+cargo run -p bat-infrastructure --bin bat-official-sync -- \
+  --auto-discover \
+  --platforms Windows,Android \
+  --output /tmp/ba-official-dev \
+  --dry-run
+```
+
+开发环境真实下载必须使用 `/tmp` 或其他隔离目录，不要写入现有资源目录。
+
 ### 基准测试
 
 ```bash
@@ -161,10 +180,7 @@ cargo fetch
 
 ### 2. 测试失败
 
-确保数据库已启动：
+先确认失败是否来自真实网络或本地资源路径。默认测试应使用 fixture/mock，不应依赖官方线上资源或开发机已有资源目录。
-```bash
-make dev
-```
 
 ### 3. FFI 绑定问题
 
@@ -176,4 +192,4 @@ cargo build
 
 ---
 
-更多问题请查看 [FAQ](./faq.md)（待创建）或提交 Issue。
+更多当前状态请查看 [当前状态](../../CURRENT_STATUS.md) 和 [当前缺口清单](../reports/CURRENT_GAPS.md)。

docs/guides/official-resource-test-pull.md

@@ -15,6 +15,42 @@
 - 任何本地客户端目录
 - 任何已安装的官方启动器或 Windows 客户端
 
+## 0. 快速入口
+
+查看命令参数：
+
+```bash
+cargo run -p bat-infrastructure --bin bat-official-sync -- --help
+```
+
+构建生产 binary：
+
+```bash
+cargo build --release -p bat-infrastructure --bin bat-official-sync
+```
+
+使用 release binary 做一次 dry-run：
+
+```bash
+target/release/bat-official-sync \
+  --auto-discover \
+  --platforms Windows,Android \
+  --output /var/lib/bluearchive-toolkit/official \
+  --dry-run
+```
+
+常驻自动更新：
+
+```bash
+target/release/bat-official-sync \
+  --auto-discover \
+  --platforms Windows,Android \
+  --output /var/lib/bluearchive-toolkit/official \
+  --watch
+```
+
+生产输出目录必须是独立状态目录。不要使用已有游戏客户端目录、官方启动器安装目录、人工维护资源目录，或开发机上的 `/home/wanye/D/BlueArchive`。
+
 ## 1. 当前流程
 
 Linux 生产运行时链路只走官方日服 HTTP 资源，不安装、不启动、不依赖官方启动器二进制：

docs/reports/CURRENT_GAPS.md

@@ -1,8 +1,8 @@
 # 当前实现缺口清单
 
-**更新时间**：2026-06-28  
+- **更新时间**：2026-07-06
-**用途**：集中跟踪当前代码中的占位实现、设计缺口和下一步验收项。  
+- **用途**：集中跟踪当前代码中的占位实现、设计缺口和下一步验收项。
-**权威计划**：`../../PROJECT_PLAN.md`
+- **权威计划**：`../../PROJECT_PLAN.md`
 
 ---
 
@@ -145,18 +145,23 @@
 
 ### G-007：Addressables Catalog 解析不完整
 
+状态：**部分关闭**
+
 现象：
 
-- 复杂压缩字段解析仍标记 TODO。
+- `AddressablesCatalogDriver` 已能解析当前真实形态 JSON catalog fixture/golden。
+- 已输出 path、hash、size、resource_type、address、dependencies、metadata。
+- 仍需覆盖更多官方 catalog 结构变体、二进制/压缩字段组合和更明确的失败诊断。
 
 影响：
 
-- 真实 Manifest 解析可能只能覆盖简单样本。
+- 当前解析能力可以服务 Manifest inspect 和部分资源索引，但还不能宣称完整兼容所有 Unity Addressables/SBP catalog 形态。
 
 验收：
 
-- 能解析项目目标版本的真实 Catalog 样本。
+- 能解析项目目标版本的真实 Catalog 样本集合。
 - 解析结果包含资源 key、provider、dependency、hash、size、path。
+- 对不支持的 catalog 结构返回明确错误，而不是静默丢字段。
 
 ---
 
@@ -167,7 +172,8 @@
 现象：
 
 - `cmd/bat` 目录存在，但无 `main.go`。
-- `go test ./...` 当前无 package。
+- `internal/ffi/ffi.go` 已存在，但还不是用户可运行 CLI。
+- `go test ./...` 当前没有产品级 Go package 覆盖。
 
 影响：
 
@@ -217,14 +223,19 @@
 
 ### G-011：Resource Repository 未持久化
 
+状态：**部分关闭**
+
 影响：
 
-- 无法可靠记录资源版本、资源路径、依赖和 CAS hash 映射。
+- `SqliteResourceRepository` 已存在，可按领域 repository 接口保存资源元数据。
+- 官方同步下载结果尚未作为用户级流程自动写入 CAS + ResourceRepository。
+- 迁移、版本化 schema 和 CLI 查询入口仍需补齐。
 
 验收：
 
 - schema 和迁移可重复执行。
 - 可按版本、类型、hash、路径查询资源。
+- 官方同步后的资源可通过 CLI 查询并能追溯到 CAS 对象。
 
 ### G-012：Translation Memory 未实现
 
@@ -266,32 +277,37 @@
 
 ### G-015：README 与当前真实状态不完全一致
 
+状态：**已关闭**
+
 现象：
 
-- README 描述了最终架构，但部分功能尚未实现。
+- 旧 README 描述了最终架构，但部分功能尚未实现。
 
 验收：
 
 - README 明确区分已实现、开发中、规划中。
 
-状态：
+处理结果：
 
-- 已部分修正，当前 README 已明确列出已具备与未完成项，并增加当前阶段说明入口。
+- README 已明确区分当前可用能力、未完成模块、官方同步运行命令和近期优先级。
 
 ### G-016：架构文档需要更新为当前路线图
 
+状态：**已关闭当前阶段**
+
 现象：
 
-- `docs/architecture/README.md` 仍描述理想架构，缺少当前状态和边界冻结记录。
+- 旧 `docs/architecture/README.md` 偏目标架构，容易让读者误以为 Go 同步器和 API/Web 已经可用。
 
 验收：
 
 - 增加 ADR 或架构决策记录。
 - 明确 Rust/Go/DB/Plugin 边界。
 
-状态：
+处理结果：
 
-- 已部分修正，`docs/architecture/README.md` 已增加当前可用官方资源入口，但仍保留目标架构描述，因此只算阶段性对齐完成。
+- 架构 README 已明确当前 Rust 官方同步入口、Go 计划边界和目标架构差异。
+- 官方资源后端说明由 `docs/architecture/official-resource-backend.md` 承载。
 
 ### G-017：CI 未落地
 
@@ -303,15 +319,37 @@
 
 - GitHub Actions 或等价 CI 执行 format、lint、test、build。
 
+### G-018：真实官方网络全量下载 smoke test 未记录
+
+状态：**未关闭**
+
+现象：
+
+- 本地测试覆盖 mock、fixture、synthetic import 和 CLI 参数。
+- 尚未在隔离输出目录记录一次真实官方网络全量下载。
+
+影响：
+
+- 无法用文档证明当前 `bat-official-sync` 在真实官方网络环境下完成首次下载、二次静默 up-to-date 和本地损坏 repair。
+
+验收：
+
+- 使用独立目录执行 dry-run。
+- 执行真实首次下载，不指向任何现有客户端或人工维护资源目录。
+- 二次运行返回 `up_to_date`，watch 模式在 up-to-date 时静默。
+- 人工破坏一个本地文件后，audit 检出并 repair。
+- 记录命令、摘要、输出目录和未纳入 Git 的大文件位置。
+
 ---
 
 ## 6. 当前关闭顺序建议
 
-1. G-007
+1. G-008
-2. G-008
+2. G-018
-3. G-005
+3. G-011
-4. G-011
+4. G-007
-5. G-012
+5. G-005
-6. G-006
+6. G-012
+7. G-006
 
-这个顺序优先建立可信工作区和基础存储，再推进资源同步、解析、翻译和补丁。
+这个顺序优先补齐用户入口和真实端到端验证，再推进资源索引、解析、翻译和补丁。

docs/reports/current-stage-prepush.md

@@ -1,50 +1,72 @@
 # 当前阶段说明
 
-**更新时间**：2026-06-29  
+- **更新时间**：2026-07-06
-**状态分支**：`experiment`  
+- **状态分支**：`experiment`
-**用途**：推送前核查与当前阶段交付说明。
+- **最新功能提交**：`789402c feat: add official resource sync pipeline`
+- **用途**：当前阶段交付说明、推送前核查和下一步依据。
 
 ## 1. 当前目标
 
-当前阶段聚焦两件事：
+当前阶段的目标已经从“验证官方资源链路”推进到“让 Rust 官方资源同步具备可运行闭环，并为 Go CLI 最小入口做准备”。
 
-1. 准备推送前的项目核查。
+已完成的阶段目标：
-2. 补齐当前阶段的文档说明。
+
+1. Rust 官方资源拉取入口不依赖已安装官方启动器。
+2. 自动发现官方 `app-version`、`connection-group`、`server-info`。
+3. 拉取 Windows + Android 官方资源集合。
+4. 保存 snapshot，按远端 marker 和本地 manifest 判断是否需要更新。
+5. 支持 `bat-official-sync --watch` 常驻检查，默认每 1 小时运行一次。
+6. 通过文档明确生产目录不能指向已有客户端或开发资源目录。
 
 ## 2. 当前实现状态
 
-已确认可用的内容：
+已确认可用：
 
-- `bat-cas-engine` 的 CAS V1 已完成。
+- `bat-cas-engine` CAS V1。
-- `bat-adapters` 的官方日服 URL 规则和官方 pull plan / update check 已可用。
+- `bat-adapters` 官方日服 URL 规则、server-info 解析、平台 discovery、inventory 枚举。
-- Linux 生产资源拉取路径已明确为显式 `--auto-discover` 或已审计 metadata snapshot，不安装、不执行官方启动器。
+- `AddressablesCatalogDriver` 对当前真实形态 fixture/golden 的解析。
-- 官方 launcher bootstrap、官方 GameMainConfig bootstrap 保留为底层显式开发/审计辅助路径。
+- `OfficialResourcePullService` 的官方 URL 拒绝、`.part` 续传、重试、本地 manifest、官方 seed `.hash` 校验。
-- `bat-infrastructure` 的官方 bootstrap / pull integration 测试已通过。
+- `OfficialUpdateService` 的 auto-discover、bootstrap cache、v2 snapshot、remote marker diff、本地 audit/repair。
-- 官方资源链路已经明确只接受官方 host，不依赖 `bluearchive.cafe` 镜像。
+- `bat-official-sync` one-shot 和 `--watch`。
+- `bat-ffi` 的 Manifest inspect 和 sync plan JSON API。
+- `SqliteResourceRepository`。
 
-实验性处理内容：
+仍未完成：
 
-- 官方 bootstrap / pull 测试夹具已收敛为 synthetic fixture，并单独留在 `experiment` 分支语义下。
+- Go CLI 最小可用入口。
-- 这些 fixture 只用于验证官方链路，不代表运行时真实线上值。
+- 官方同步下载结果自动导入 CAS + ResourceRepository 的用户级流程。
+- 真实官方网络全量下载 smoke 记录。
+- 完整 AssetBundle 解析。
+- Patch、翻译系统、API Server、Web。
 
 ## 3. 当前核查结果
 
-已执行的验证：
+已执行并通过：
 
-- `cargo test -p bat-infrastructure --test official_game_main_config_bootstrap -- --nocapture`
+```bash
-- `cargo test -p bat-infrastructure`
+cargo test -p bat-adapters -- --nocapture
-- `cargo test -p bat-adapters`
+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
+git diff --cached --check
+```
 
-结果：
+提交后确认：
 
-- 全部通过。
+```bash
+git status --short
+```
+
+结果：工作区干净。
 
 ## 4. 当前结论
 
-当前代码可以继续进入推送准备阶段，但仓库仍包含大量未整理的既有改动，暂不应把当前工作区视作“只剩最终提交”的干净状态。
+当前 Rust 官方资源同步链路已经具备可运行闭环，但仓库还不是完整产品。下一步不应继续只扩展 example，而应补齐 Go CLI 最小入口、真实网络 smoke、CAS/ResourceRepository 编排和 AssetBundle 解析。
 
-下一步应当继续做：
+## 5. 下一步
 
-- 归整实验性改动与主线改动的边界。
+1. 实现 Go CLI：`bat doctor`、`bat sync --help`、`bat official sync --help`。
-- 按分支策略确认哪些内容允许进入 `dev`，哪些应保留在 `experiment`。
+2. 为 `bat-official-sync` 做真实官方网络 smoke，输出目录必须隔离。
-- 再做一次提交前检查和差异审阅。
+3. 将官方同步下载结果接入 CAS + `SqliteResourceRepository`。
+4. 开始 AssetBundle UnityFS header/block/directory 解析。

docs/reports/current-status-handoff.md

@@ -1,50 +1,60 @@
 # 当前进度交接
 
-**更新时间**：2026-06-30  
+- **更新时间**：2026-07-06
-**状态分支**：`experiment`  
+- **状态分支**：`experiment`
-**用途**：给下一次对话快速恢复上下文，优先以当前工作区与已验证结果为准。
+- **最新功能提交**：`789402c feat: add official resource sync pipeline`
+- **用途**：给下一次对话快速恢复上下文，优先以当前工作区和已验证结果为准。
 
 ## 1. 现在处在什么阶段
 
-当前项目已经完成基础整理和 CAS V1，官方资源链路也已经验证过，下一阶段重点是把“资源同步”从验证推进到可继续扩展的真实实现。
+项目已经完成基础整理、CAS V1 和 Rust 官方资源同步闭环。下一阶段重点是 Go CLI 最小可用、真实官方网络 smoke、同步结果进入 CAS/ResourceRepository，以及 AssetBundle 解析起步。
 
 已确认的事实：
 
-- `cargo test --workspace` 通过。
+- 当前分支为 `experiment`。
-- `git status --short --branch` 可用，当前分支为 `experiment`。
 - `bat-cas-engine` 的 CAS V1 已完成。
-- 官方资源链路已收敛到只接受官方 host，默认验证平台是 `Windows` + `Android`。
+- `bat-official-sync` 是当前官方资源同步正式入口。
-- 真实下载相关测试目前是通过 mock / fixture 验证，不是自动去拉线上全量资源。
+- Linux 生产链路不安装、不启动、不依赖官方启动器。
+- `--auto-discover` 通过官方 HTTP metadata 和临时目录解析 `GameMainConfig`。
+- 默认平台是 `Windows + Android`。
+- 真实下载会维护 `official-download-manifest.json`，并使用 size + BLAKE3、本地 audit/repair 和官方 seed `.hash` 校验。
+- `--watch` 是 Rust 内部常驻检查模式，默认 1 小时；外部 systemd/container 只负责守护进程。
 
 ## 2. 现在不要误解的点
 
-- `cargo test --workspace` 只会跑测试，不等于自动开始真实下载。
+- `cargo test` 不会自动开始真实全量下载。
-- 仓库里确实有几个本地实样本测试，但它们是 `#[ignore]`，只有显式启用对应 `BAT_REAL_*` 环境变量才会读本地文件。
+- 仓库里的本地实样本测试仍应显式启用，不应默认读取 `/home/wanye/D/BlueArchive`。
 - `bluearchive.cafe` 不是官方资源域名，不能当成官方链路使用。
-- 当前运行时不应依赖“本地客户端一定存在”的假设。
+- 生产输出目录必须独立，不要指向已有客户端目录、官方启动器安装目录或开发资源目录。
+- Go CLI 尚未实现；当前可运行同步入口是 Rust binary。
+- `catalog_*.hash` 当前作为 Addressables marker，不按官方 seed `.hash` 的 `xxHash32(seed=0)` 规则做内容强校验。
 
 ## 3. 当前还没做完什么
 
 仍待实现的主线工作：
 
-1. `Manifest` / Addressables 的真实解析。
+1. Go CLI 最小入口：`bat doctor`、`bat sync --help`、`bat official sync --help`。
-2. `sync`、`manifest inspect`、`cache status` 这些 CLI 入口。
+2. 真实官方网络 smoke：dry-run、首次下载、二次 up-to-date、本地损坏 repair。
-3. 资源持久化 schema，以及下载结果写入 CAS + ResourceRepository。
+3. 官方同步下载结果进入 CAS + `SqliteResourceRepository` 的用户级流程。
-4. 端到端的真实同步测试。
+4. Addressables parser 覆盖更多真实 catalog 结构。
-5. 之后再推进 AssetBundle 解析、文本提取、翻译库、补丁系统。
+5. AssetBundle UnityFS header/block/directory 解析。
+6. Patch、翻译库、API Server、Web。
 
 ## 4. 下一次对话最合适的起点
 
-建议直接从 `Milestone 3：Manifest 与资源同步` 开始，先把这条链路收紧：
+建议从 Go CLI 最小可用开始：
 
-1. 真实 `Manifest` 字段解析。
+1. 读取 `README.md`、`CURRENT_STATUS.md`、`PROJECT_PLAN.md`。
-2. 资源版本、平台、URL、Hash、大小模型确认。
+2. 读取 `docs/guides/official-resource-test-pull.md` 和 `docs/architecture/official-resource-backend.md`。
-3. 下载器和缓存落地。
+3. 实现 `cmd/bat` 和最小命令树。
-4. 端到端验证能否从官方入口跑通同步。
+4. 将 `bat-official-sync` 的 JSON report 作为 Go CLI 输出的稳定来源。
 
 ## 5. 相关入口
 
+- `README.md`
 - `PROJECT_PLAN.md`
 - `CURRENT_STATUS.md`
-- `docs/reports/current-stage-prepush.md`
+- `DOCS_INDEX.md`
+- `docs/reports/CURRENT_GAPS.md`
 - `docs/guides/official-resource-test-pull.md`
+- `docs/architecture/official-resource-backend.md`