feat(assetbundle): 完善官方资源解析与双目录发布

PROJECT_PLAN.md

@@ -34,27 +34,29 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 6. `bat-infrastructure` 已提供官方资源 pull/update 服务，正式入口是 Rust binary `bat`。
 7. `bat` 支持 `--auto-discover`、`--watch`、`--daemon`、默认 1 小时间隔、本地 manifest audit/repair、官方 seed `.hash` 校验、snapshot/cache，以及基于 Unix socket JSON-RPC 的 live control/backend 方法（`daemon.status/logs/stop/reload/refresh/doctor`、`resource.sync/verify/repair/state/manifest/list`、`catalog.*`、`task.*`）；`restart` 和 `clean-stable` 仍由 CLI 侧按进程生命周期显式执行。
 8. `bat-ffi` 已提供 Manifest inspect 和官方 sync plan 的可选无状态粗粒度 JSON C ABI helper。
-9. 文档已整理：根目录保留入口文档，历史报告进入 `docs/reports/historical/`，误嵌套的 `docs/docs` 已合并。
+9. 官方原版资源默认发布到 `./bat-resources`，汉化产物默认发布到独立的 `./bat-localized`；当前官方同步报告会标记 `localized_release_status=not_localized`，表示原版资源已发布、汉化资源未发布。
+10. 官方同步校验完成后会在 active release 下生成 `official-parse-cache.json`，未变化文件按 URL、相对路径、size 和 BLAKE3 复用解析结果。
+11. 文档已整理：根目录保留入口文档，历史报告进入 `docs/reports/historical/`，误嵌套的 `docs/docs` 已合并。
 
 ### 仍是骨架或占位
 
-1. `bat-assetbundle` 仍是占位 crate；完整 UnityFS、压缩块、TypeTree 或对象表解析未完成。
+1. `bat-assetbundle` 已具备 UnityFS 解包和 TextAsset 提取基础能力（header/block info/directory、LZ4/LZMA block info 与数据 block、directory 文件提取、serialized file object table、TypeTree node 元数据、TextAsset bytes），但 MonoBehaviour/ScriptableObject 字段级解析、重打包和 Patch 仍未完成。
 2. `bat-patch` 的 Binary/JSON 模块仍返回明确的未实现错误，不具备真实补丁能力。
-3. Go CLI/API/SDK 仍没有产品级入口；当前 `bat-api` module 只有 `internal/backendrpc` Rust daemon RPC client、`cmd/bat` 试验骨架与 `internal/ffi` 兼容包装。
+3. Go 侧边界已冻结（见 `docs/reports/GO_STATUS.md`）：同步/运维命令行 = Rust `bat`；资源分发 = `cmd/bat-api` MVP；`internal/backendrpc` 完成；`cmd/bat` 仅为试验（`bin/bat-go`）。完整游戏业务 API / Web / SDK 仍未完成。
 4. Addressables parser 已覆盖当前真实形态 fixture/golden，但还不是完整 Unity Addressables/SBP catalog 兼容层。
 5. 官方同步结果尚未作为用户级流程自动导入 CAS + ResourceRepository。
-6. 真实官方网络全量下载 smoke 已固化为可重复脚本和 runbook（G-018 已关闭）；真实运行记录处于长期运行测试阶段，报告待后续提供。
-7. Web、数据库迁移、OpenAPI、插件加载机制尚未实现。
-8. 原 Git 历史未恢复；当前仓库以新初始化基线为准。
+6. 汉化 Patch 发布流程尚未完成；`localized` 发布状态、`localized-output/current` 切换、回滚和完整性校验仍需由 Patch 阶段落地。
+7. 真实官方网络全量下载 smoke 已固化为可重复脚本和 runbook（G-018 已关闭）；真实运行记录处于长期运行测试阶段，报告待后续提供。
+8. Web、数据库迁移、OpenAPI、插件加载机制尚未实现。
+9. 原 Git 历史未恢复；当前仓库以新初始化基线为准。
 
 ### 已验证
 
 1. `cargo test --workspace --quiet` 通过。
 2. `cargo clippy --workspace --all-targets -- -D warnings` 通过。
-3. `go test ./...` 通过，但目前没有 Go 产品级测试覆盖。
-4. `go vet ./...` 通过。
-5. `go build -o /tmp/bat-go-cli ./cmd/bat` 通过。
-6. `target/debug/bat --help` 可用。
+3. `make test-go-api` / `make build-go-api` 覆盖 `internal/api` 与 `internal/backendrpc`。
+4. `go vet` 覆盖 bat-api 相关包。
+5. `target/debug/bat --help`（Rust）可用。
 
 ---
 
@@ -141,7 +143,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 
 **目标**：完成可长期使用的 Content Addressable Storage。
 
-**当前状态**：已完成 CAS V1。Go CLI/API 产品入口尚未完成；`bat-api` 已有 `internal/backendrpc` typed RPC client 和 `cmd/bat` 试验骨架；Rust 继续承载完整资源拉取与更新检查核心逻辑；`bat-ffi` 仅保留为可选兼容层。
+**当前状态**：已完成 CAS V1。Rust 承载完整资源拉取与更新检查；Go 以 `bat-api` 资源分发 MVP + `backendrpc` 为服务入口（`GO_STATUS.md`）；`bat-ffi` 仅可选兼容层。
 
 交付物：
 
@@ -174,11 +176,13 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 2. 资源版本、区域、渠道、远端 URL、Hash、大小、依赖关系模型：**部分完成**。`Resource` 和官方 endpoint/snapshot 模型已扩展；仍需冻结 Go CLI/API 可见模型。
 3. Rust 官方下载器：**已完成当前生产入口需要的核心能力**。包含官方 URL 校验、`.part` 续传、重试、本地 manifest size+BLAKE3 校验、官方 seed `.hash` 校验和 repair。
 4. Rust 自动更新入口：**已完成当前生产入口**。`bat` 支持 snapshot、marker diff、bootstrap cache、one-shot、`--watch`、`--daemon`、默认 1 小时间隔、北京时间固定强制刷新，以及 Unix socket JSON-RPC 后台运维命令返回。
-5. Go 产品入口：**未完成**。`internal/backendrpc` 已提供 Go 调 Rust daemon 的 typed RPC client；当前 `cmd/bat` 仅有 `doctor`、`manifest inspect`、`sync plan` 试验能力，尚不构成产品级 CLI；若要继续由 Go 承担用户入口，需要单独收敛命令集和调用边界。
+5. Go 入口边界：**已冻结**。同步命令行 = Rust `bat`（G-008 关闭）；资源分发 = `bat-api` MVP（G-009 部分完成）。详见 `docs/reports/GO_STATUS.md`。
 6. 用户级 `sync`、`manifest inspect`、`cache status`：**未完成**。Rust `bat --json` 是当前稳定进程边界；`bat-ffi` 只提供可选兼容用的 Manifest inspect 和 sync plan JSON helper。
 7. 下载结果写入 CAS + ResourceRepository：**部分完成**。CAS 和 SQLite ResourceRepository 已存在，官方同步入口尚未把完整下载结果自动作为用户级流程导入。
 8. Linux 生产同步不依赖已安装官方启动器：**已完成当前 Rust 入口**。`--auto-discover` 只使用官方 HTTP metadata 和临时目录解析 `GameMainConfig`。
 9. 真实官方网络全量下载 smoke test：**命令已固化（G-018 已关闭）**。`scripts/official-full-pull-smoke.sh` / `make official-smoke` 已固化 dry-run、首次下载、二次 up-to-date 和本地损坏 repair 的可重复流程；真实运行处于长期运行测试阶段，报告待后续提供。
+10. 官方发布后的解析缓存：**已完成基础入口**。`official-parse-cache.json` 基于下载 manifest 覆盖直接 UnityFS bundle、zip 内 UnityFS 条目和非候选资源记录；本地文件未变化时跳过重复解析。
+11. 汉化发布状态：**已完成状态模型准备**。官方同步默认报告 `not_localized`，表示只发布原版资源；后续 Patch 阶段发布汉化资源后才切换为 `localized`。
 
 验收标准：
 
@@ -190,6 +194,8 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 6. 自动更新入口必须做到无变化不下载，有变化下载成功后才写入新 snapshot。
 7. `--watch` 模式必须在 Rust 内部保持持久检查能力，外部 supervisor 只负责进程守护。
 8. 真实官方网络 smoke 必须记录输出目录、命令、结果摘要和未纳入仓库的大文件位置。
+9. 官方原版资源目录和汉化产物目录必须物理分离，不能相同或互相嵌套。
+10. 官方同步完成后必须能区分 `not_localized` 和 `localized`，不能把原版资源发布状态与汉化产物发布状态混为一谈。
 
 ---
 
@@ -199,19 +205,25 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 
 交付物：
 
-1. 解析 UnityFS header、blocks、directory、metadata、objects。
-2. 支持 LZ4/LZMA 解压，记录压缩块校验。
-3. 实现 TypeTree/ObjectInfo 读取。
-4. 实现 TextAsset、MonoBehaviour、ScriptableObject 的可扩展解析入口。
-5. 增加解析器注册表和版本适配器。
-6. 编写 `bundle inspect`、`bundle extract`。
+1. **解析缓存闭环**：官方同步发布后生成 `official-parse-cache.json`，覆盖 manifest 全部条目、直接 bundle、zip 内 bundle、非候选资源和解析失败诊断；未变化文件按 URL、相对路径、size 和 BLAKE3 复用解析结果。
+2. **Addressables 完整化**：覆盖 Windows/Android JSON、compact JSON 和后续二进制 catalog 入口，解析 provider、internal id、primary key、dependency、bundle name、hash、size、CRC 和资源类型。
+3. **UnityFS 容器层**：继续完善 header、block info、directory、data block、压缩、alignment、边界错误、directory 文件提取和真实样本回归。
+4. **Serialized file 层**：稳定 Unity serialized file header、type table、TypeTree node、object table、path id、class id 和 raw object bytes 表示。
+5. **字段级解析层**：实现 TypeTree 字段 reader，支持 bool、integer、float、string、bytes、array、map、PPtr 和 managed reference 诊断占位。
+6. **文本对象入口**：实现 TextAsset、MonoBehaviour、ScriptableObject 的可扩展提取入口，输出可追溯到 bundle、serialized file、path id 和 field path 的文本定位。
+7. **工具与接口**：编写 `bundle inspect`、`bundle extract`、`text extract` 的最小稳定入口；CLI/RPC/API 使用解析器输出，不直接耦合解析内部结构。
+8. **汉化发布前置**：解析结果必须能作为 Patch 输入；Patch 发布阶段才写 `localized-output` 并切换 `localized` 状态。
 
 验收标准：
 
-1. 能解析真实样本或明确结构化测试样本。
-2. 错误报告包含 bundle 名称、偏移、字段和 Unity 版本。
-3. 解析器和业务流程解耦。
-4. 不支持的 Unity 版本返回明确错误，不做隐式猜测。
+1. 能解析结构化测试样本、离线回归 fixture 和隔离真实样本。
+2. 错误报告包含 URL/路径、archive entry、UnityFS directory、object path id、class id、field path、offset 和 Unity 版本。
+3. 解析器和业务流程解耦；解析器不直接写 `bat-resources` 或 `bat-localized`。
+4. 不支持的 Unity 版本或 TypeTree 结构返回明确错误，不做隐式猜测。
+5. `official-parse-cache.json` 能跳过未变化资源的重复解析，且不会影响官方原版资源发布。
+6. 文本提取结果能追溯到原始资源位置，并可作为后续 Patch manifest 输入。
+
+详细分层路线图见 `docs/architecture/assetbundle.md`。
 
 ---
 
@@ -296,6 +308,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 2. 任一步失败都能回滚到补丁前状态。
 3. 不直接覆盖未经备份的客户端文件。
 4. Patch 生成与应用有端到端测试。
+5. 汉化产物写入独立 `localized-output`，保留官方相对目录结构；只有完整 Patch 发布并通过校验后才切换为 `localized`。
 
 ---
 
@@ -366,7 +379,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 
 ## 5. 推荐执行顺序
 
-近期不要直接跳到 Web 或 AI Provider。项目当前的真实瓶颈是 Go 产品入口边界、资源解析、同步结果进入 CAS/ResourceRepository，以及真实端到端验证。
+近期不要直接跳到 Web 或 AI Provider。项目当前的真实瓶颈是资源解析、同步结果进入 CAS/ResourceRepository、`bat-api` 与全量 release 联调，以及真实端到端验证。
 
 建议顺序：
 
@@ -380,15 +393,14 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 
 ## 6. 近期具体任务
 
-优先完善 Rust `bat` 后端，并同步收敛 Go 产品入口边界。当前事实是 Rust `bat` 已承担可用的资源同步/运维入口，`bat-api/internal/backendrpc` 已提供 Go 到 Rust daemon 的本机 RPC client，Go `cmd/bat` 仍只是试验骨架，`bat-api` HTTP 服务仍是独立目标（issue #19 / G-009）：
+优先完善 Rust 解析与资源库接入，并联调 Go 资源分发。边界见 `docs/reports/GO_STATUS.md`：
 
-1. 对 issue #17 做验收并关闭或更新范围：多线程下载与指数退避实现已合入，但 GitHub issue 仍 open。
-2. 继续逆向 Addressables catalog，扩大 bundle hash/size/CRC 等可校验字段覆盖（issue #2）。
-3. 对 AssetBundle/UnityFS 做引擎级解析：header/block/directory/metadata/object table（issue #3 / G-005）。
-4. 将官方同步下载结果接入 CAS + `SqliteResourceRepository` 的用户级流程（G-011）。
-5. 收敛 Go 产品入口：明确继续推进最小 Go CLI，或把用户 CLI 固化为 Rust `bat` 并把 Go 侧集中到 `bat-api`。
-6. 实现 `bat-api`（仿官方 API 的 Go HTTP 服务，含鉴权/签名验签，issue #19 / G-009）。
-7. 为 CAS 增加 `doctor cas` 诊断入口。
+1. issue #17 已关闭（顺序下载 + 指数退避）。
+2. G-008 已决策关闭：同步/运维命令行 = 近乎全自动的 Rust `bat`。
+3. G-009 / issue #19：`bat-api` 资源分发 MVP 已落地；优先服务器联调；拉取仍在 Rust `bat`。
+4. 继续 Addressables（issue #2）与 UnityFS（issue #3 / G-005）。
+5. 官方同步结果接入 CAS + ResourceRepository 用户级流程（G-011）。
+6. 为 CAS 增加 `doctor cas` 诊断入口。
 
 ---
 
@@ -416,7 +428,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 处理策略：
 
 1. Rust 提供稳定引擎能力，并在当前阶段承担可生产运行的官方资源同步 CLI、watch 和 daemon。
-2. Go 的长期职责包括用户命令、最小稳定 CLI、服务编排、网络和 Provider；当前 Go 产品入口尚未完成，不能把 `cmd/bat` 试验骨架视为完成。
+2. Go 的长期职责包括资源分发 HTTP（`bat-api`）、服务编排、网络和 Provider；同步/运维命令行由近乎全自动的 Rust `bat` 承担。不能把试验性 `cmd/bat` 视为产品 CLI。
 3. 跨边界优先进程或 SDK，FFI 只作为可选的粗粒度、无状态、安全、可测试兼容 API。
 4. Rust 不需要被强制写成 Go 调用库；当前 `bat --watch` / `bat --daemon` 是允许长期运行的 Rust 生产任务。
 
@@ -442,7 +454,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 
 按最终目标计算，当前总体完成度不再固定写单一百分比，以模块状态和 issue 收敛情况为准。
 
-已完成的是稳定基线、架构骨架、部分接口、CAS V1 和 Rust 官方资源同步闭环，不是完整产品能力。下一阶段的关键不是继续堆目录，而是把 Go 产品入口边界、官方同步端到端验证、CAS/ResourceRepository 编排和 AssetBundle 解析链路做实。
+已完成的是稳定基线、架构骨架、部分接口、CAS V1、Rust 官方资源同步闭环，以及 Go `bat-api` 资源分发 MVP。下一阶段的关键是官方同步结果进入 CAS/ResourceRepository、AssetBundle 解析，以及 bat-api 与全量 release 联调。
 
 ---