BlueArchiveToolkit/docs/architecture/assetbundle.md

# AssetBundle 与资源解析路线图

- **更新时间**：2026-07-25
- **适用范围**：Rust 解析引擎、官方同步后的解析缓存、CAS/ResourceRepository 接入、后续文本提取和 Patch 发布。
- **权威关联**：`PROJECT_PLAN.md` Milestone 3/4/5/8，`docs/reports/CURRENT_GAPS.md` G-005/G-007/G-011/G-011D。

---

## 1. 目标边界

解析系统的目标不是把下载流程写成一次性脚本，而是建立可长期维护的资源理解层：

1. 官方资源同步负责拉取、校验和发布原版资源。
2. 解析器只读取已发布或 staging 中已校验的资源，不修改原始文件。
3. 解析结果写入派生缓存、CAS 索引或后续文本提取索引。
4. 汉化产物只能由 Patch/发布阶段写入 `localized-output`，不能写回官方资源目录。
5. 解析器必须与 CLI、daemon、Go API、Patch 业务流程解耦。

当前官方同步完成后会维护 `official-parse-cache.json`。它是官方 release 的派生索引，不是汉化产物；本地 URL、相对路径、size 和 BLAKE3 未变化时应复用旧解析结果并跳过重复解析。

---

## 2. 分层模型

解析能力按从外到内分层：

| 层级 | 输入 | 输出 | 当前状态 |
| --- | --- | --- | --- |
| 官方 seed manifest | `TableCatalog.bytes`、`BundlePackingInfo.bytes`、`MediaCatalog.bytes` | 完整下载 URL、相对路径、hash 校验边界 | 已用于下载计划，仍需沉淀更多结构化字段 |
| Addressables catalog | `catalog_*.zip` 内 JSON/bin catalog、`catalog_*.hash` | asset path、provider、dependencies、size、CRC、bundle name | JSON/compact 当前样本已覆盖，仍需更多真实结构变体 |
| UnityFS container | `.bundle`、zip 内 bundle | header、block、directory、解压文件、基础摘要 | 已支持基础解包、LZ4/LZMA、边界校验 |
| Serialized file | UnityFS directory 文件 | header、type table、TypeTree node、object table、TextAsset bytes | 已支持基础表结构和 TextAsset bytes |
| Unity 对象字段 | TextAsset、MonoBehaviour、ScriptableObject | 可翻译文本单元、上下文、资源定位 | TextAsset bytes 已有入口，字段级反序列化未完成 |
| Patch 发布前解析 | 已翻译文本、中间格式、原版资源 | 可验证 patch manifest、汉化 release 目录 | 未完成 |

---

## 3. 当前已落地能力

`crates/bat-assetbundle` 已经承担解析核心：

1. `UnityFsParser` 解析 UnityFS header、block info、directory。
2. 支持 LZ4/LZMA block info 和数据 block 解压。
3. 支持 block info at end 和官方样本中出现的 block data alignment。
4. 能从 UnityFS directory 提取文件 bytes。
5. `serialized` 模块能读取 Unity serialized file header、type table、TypeTree node 元数据、object table。
6. 能提取 TextAsset 的 name 和原始 bytes。
7. `ResourceImportService` 能把 AssetBundle 摘要、TextAsset/Table/Media 分类写入导入报告。
8. 官方同步后 `OfficialParseCacheService` 能从 `official-download-manifest.json` 遍历所有资源，解析直接 bundle 和 zip 内条目，非候选资源记录为 unsupported。

当前还不能宣称完整：

1. MonoBehaviour/ScriptableObject 的 TypeTree 字段级反序列化未完成。
2. Unity managed reference、PPtr、array/map、string alignment 等复杂字段未完整覆盖。
3. Addressables bin/compact catalog 结构变体仍需真实样本驱动补齐。
4. 解析结果尚未自动进入用户级 CAS + ResourceRepository 查询流程。
5. 不能重写 AssetBundle，也不能生成可发布汉化 patch。

---

## 4. 补全顺序

### P0：解析缓存和样本闭环

目标：让官方同步后的解析结果可复用、可诊断、可回归。

交付：

1. `official-parse-cache.json` 记录 manifest entry、zip entry、解析状态、Unity 版本、文件数、TextAsset 数、错误摘要和缓存复用状态。
2. 解析直接 `.bundle` / `.unity3d` 和 zip 内全部文件条目，不能只假设 `FullPatch_*.zip`。
3. 非候选资源记录为 unsupported，不影响官方同步发布。
4. 缺失、损坏或无法解析的 bundle 记录 failed，但不回滚已经完成校验的官方原版 release。
5. 用合成 fixture、隔离真实样本和回归 fixture 覆盖缓存复用、zip 内条目、非候选资源、解析失败。

验收：

1. 第二次运行同一 release 时能看到解析缓存复用计数。
2. 修改任意 manifest entry 的 size/BLAKE3 后，只重新解析对应资源。
3. 解析缓存不会写入 `localized-output`。

### P1：Addressables catalog 完整化

目标：把“能列出资源”推进到“能稳定定位 bundle、依赖、校验字段和资源类型”。

交付：

1. 覆盖 JSON catalog、compact JSON、可能的二进制 catalog 入口。
2. 解析 provider id、internal id、primary key、dependency key、resource type、bundle name、hash、size、CRC。
3. 明确 `catalog_*.hash` 只作为 Addressables remote catalog marker，不套用 seed `.hash` 的 xxHash32 规则。
4. 将 Windows/Android catalog 样本拆成可复现 fixture，不把大文件纳入 Git。
5. 对未知结构返回明确错误或保真 raw metadata，不静默丢字段。

验收：

1. 当前目标版本 Windows/Android catalog 样本集合解析通过。
2. 解析结果能反查 bundle 文件和依赖链。
3. size/CRC/hash 字段能参与本地文件验证或至少进入诊断报告。

### P2：Unity Serialized 字段级解析

目标：把 Unity object table 推进到可提取文本字段。

交付：

1. TypeTree schema 内部表示稳定化：node path、type、name、size、flags、array 信息。
2. 实现基础字段 reader：bool、integer、float、string、bytes、array、map、PPtr、managed reference 占位。
3. 支持 TextAsset script/name 的结构化读取，而不只保留 raw bytes。
4. 支持 MonoBehaviour 和 ScriptableObject 的 TypeTree 字段遍历。
5. 对缺 TypeTree 或 stripped 类型返回可诊断错误，保留 raw object bytes 作为后备。

验收：

1. 合成 fixture 覆盖标量、数组、嵌套结构、string alignment。
2. 隔离真实样本能输出稳定 JSON field tree。
3. 解析错误包含 file path、object path id、class id、字段路径和偏移。

### P3：文本提取中间层

目标：为日语汉化提供稳定、可回写定位的文本单元。

交付：

1. 定义 `TextUnit`：source text、resource path、archive entry、object path id、field path、语言、版本、上下文。
2. TextAsset 支持 JSON/CSV/TSV/plain text 的可配置探测。
3. MonoBehaviour/ScriptableObject 按字段路径和类型策略提取字符串。
4. 保留重复文本和上下文，不在解析阶段做会丢定位的合并。
5. 导出 JSONL 作为第一稳定格式，CSV/XLIFF 可后置。

验收：

1. 提取不会修改官方资源。
2. 每条文本能追溯回原 bundle、serialized file、path id 和字段路径。
3. 同一文本在不同上下文中保持可区分。

### P4：CAS/Repository 用户级接入

目标：让解析结果进入可查询资源库，而不是只停留在文件系统缓存。

交付：

1. 官方同步完成后可配置触发导入 CAS + ResourceRepository。
2. ResourceRepository 保存版本、平台、资源类型、bundle path、TextAsset 名称、TextUnit 索引摘要。
3. 支持 CLI/RPC 查询资源、bundle、TextAsset、解析错误和缓存状态。
4. schema 迁移版本化，旧库可重复升级。

验收：

1. 可以按版本、路径、类型、hash、TextAsset 名称查询。
2. 解析缓存和 repository 数据能从同一 manifest fingerprint 追溯。
3. CAS 对象跨版本复用，不重复存储相同文件。

### P5：Patch 发布前置解析

目标：让解析结果成为可生成汉化 patch 的输入。

交付：

1. 定义 patch manifest：目标官方版本、输入 TextUnit 版本、输出文件、hash、回滚信息。
2. 支持 TextAsset raw bytes 替换的最小 patch 路径。
3. MonoBehaviour/ScriptableObject 字段替换必须依赖 P2 字段级解析结果。
4. Patch 产物写入 `localized-output/.staging/<id>`，校验通过后发布到 `localized-output/versions/<id>` 并切换 `current`。
5. 成功后发布状态从 `not_localized` 切到 `localized`。

验收：

1. Patch 失败不影响 `bat-resources/current`。
2. 汉化 release 保留官方相对目录结构。
3. `localized` 状态能证明原版和汉化两套资源都已发布。

---

## 5. 解析器接口原则

1. 解析器输入只接受 bytes、逻辑路径和可选上下文，不直接访问下载器状态。
2. 解析器输出必须可序列化，供 CLI/RPC/API、缓存和测试 golden 使用。
3. 错误必须带位置：URL 或路径、archive entry、UnityFS directory、object path id、field path、offset。
4. 未识别结构优先保留 raw metadata，不做低保真猜测。
5. 解析器不写 `bat-resources` 和 `bat-localized`，写文件由上层缓存、导入或 Patch 发布流程负责。

---

## 6. Fixture 策略

1. 合成 fixture 放入代码仓库，覆盖边界和回归。
2. 真实小样本可放入仓库前必须确认体积、许可和可复现性。
3. 大型真实官方资源只允许放在 `/tmp`、隔离测试目录或用户显式提供的远端测试目录，不纳入 Git。
4. 每个新增 fixture 必须说明覆盖的真实风险：字段变体、压缩模式、越界、hash mismatch、zip 内路径、TypeTree 结构等。

---

## 7. 近期关闭路径

优先顺序：

1. 完成 Addressables Windows/Android 当前版本 catalog 样本集合，关闭 G-007 当前阶段。
2. 完成 TypeTree 字段 reader 和 MonoBehaviour/ScriptableObject 遍历，推进 G-005。
3. 将 `official-parse-cache.json` 摘要接入 CAS/ResourceRepository 用户级导入，推进 G-011。
4. 定义 TextUnit JSONL 和最小 TextAsset 提取命令，衔接 Milestone 5。
5. 在 Patch 引擎落地后实现 `localized` 发布状态切换，关闭 G-011D 的核心发布缺口。