BlueArchiveToolkit/docs/architecture/assetbundle.md

# AssetBundle 与资源解析路线图

- **更新时间**：2026-08-19
- **适用范围**：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。
- **维护冻结**：解析扩展遵循 [`docs/reports/PARSER_FREEZE.md`](../reports/PARSER_FREEZE.md)，冻结期只接受稳定性、诊断、真实回归和文档一致性修复。

---

## 1. 目标边界

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

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

当前官方同步在新 release 发布后会先维护 `official-resource-changes.json` 和 `crowdin-translation-handoff.json`，再维护 `official-parse-cache.json`、`official-textunit-index.json`、`official-textunit-tasks.json` 和 `crowdin-textunit-queue.json`。这些都是官方 release 的派生索引，不是汉化产物；up-to-date 轮询在已有有效解析缓存、TextUnit 明细索引和 TextUnit 队列时只读取摘要，不重复解析。

---

## 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、alignment、大小/计数/路径/边界校验 |
| Serialized file | UnityFS directory 文件 | header、type table、TypeTree node、object table、TextAsset bytes | 已支持基础表结构和 TextAsset bytes |
| Unity 对象字段 | TextAsset、MonoBehaviour、ScriptableObject | 可翻译文本单元、上下文、资源定位 | TypeTree 基础字段读取、`SerializedReference` / prefixed managed-reference metadata alias、payload 提取和字符串提取已落地，真实结构覆盖继续扩大 |
| Patch 发布前解析 | 已翻译文本、中间格式、原版资源 | 可验证 patch manifest、汉化 release 目录 | UnityFS TextAsset 前置已落地，通用 Binary/JSON/Text Patch 与文件级 patch / UnityFS 写入入口可用，发布级 build/rollback 未开放 |

---

## 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. 对 block/directory 计数先按剩余字节做有界检查，避免损坏输入触发超大内存分配。
6. `serialized` 模块能读取 Unity serialized file header、type table、TypeTree node 元数据、object table。
7. 能提取 TextAsset 的 name 和原始 bytes。
8. TypeTree field reader 已支持基础标量、string、bytes、array、vector/staticvector 嵌套 `Array` 形态、`List<T>` / `HashSet<T>` 集合 alias、map、PPtr、enum `value__` backing field、`LayerMask` / `BitField` 的 `m_Bits` backing field、嵌套对象、常见固定 Unity float/int/hash 值类型的 leaf 和 direct child TypeTree 形态、unknown fixed-size raw bytes 保留和同长度替换、TypeTree-covered managed reference、TypeTree-covered managed reference registry 记录、`m_ManagedReferences` / `RefIds` / `m_RefIds` / verbose type 字段等 registry 命名变体、`id` / `typeInfo` 等 metadata 命名变体、`data` / `value` / `payload` / `object` / `managedReferencePayload` / `referencePayload` / `serializedReferencePayload` / `managedReferenceValue` / `referenceValue` / `serializedReferenceValue` / `managedReferenceObject` / `referenceObject` / `serializedReferenceObject` / `managedReferenceData` / `referenceData` / `serializedData` 等 payload 命名变体、managed-reference full typename 拆解和字段 offset/size 诊断。
9. `TextUnitExtractor` 已把 JSON/CSV/TSV/plain TextAsset、TypeTree 字符串字段和 TypeTree-covered managed reference payload 字符串输出为可序列化 TextUnit/JSONL；zip 场景保留 archive entry，TextUnit 明细包含 serialized file、path id、class id、field path、字段 offset/byte size、format、asset name 和上下文。managed-reference 类型元数据保留为 payload context，不进入翻译文本队列；即使 registry 暂时只能走 fallback 字段遍历，`RefIds`、`className`、`namespaceName`、`asmName` 等元数据别名也会被跳过，payload/value/object 家族和 `managedReferenceData` / `referenceData` / `serializedData` 仍按 payload 处理，并按 `RefIds[n]` 等记录前缀或子字段推导 metadata，避免多条 fallback record 混用 managed-reference context。
10. `ResourceImportService` 能把 AssetBundle 摘要、TextAsset/Table/Media 分类和 TextUnit 摘要写入导入报告。
11. 官方同步后 `OfficialParseCacheService` 能从 `official-download-manifest.json` 遍历所有资源，解析直接 bundle 和 zip 内条目，非候选资源记录为 unsupported，并缓存 TextUnit 数量/格式/诊断摘要，同时写出 `official-textunit-index.json` 供 `parse.text_units` / `parse.errors` 查询。

当前还不能宣称完整：

1. TypeTree-covered managed reference 字段和 registry 记录已可结构化解码并参与文本提取，常见 registry 命名别名（含 `m_ManagedReferences`、`RefIds`、`m_RefIds`、verbose type 字段）、metadata 命名别名（含 `id`、`typeInfo`）、payload 命名别名（含 `data`、`value`、`payload`、`object`、`managedReferencePayload`、`referencePayload`、`serializedReferencePayload`、`managedReferenceValue`、`referenceValue`、`serializedReferenceValue`、`managedReferenceObject`、`referenceObject`、`serializedReferenceObject`、`managedReferenceData`、`referenceData`、`serializedData`）、full typename 拆解和 payload-only TextUnit 提取已有回归覆盖，多记录 registry 聚合也已有单元回归；fallback 字段遍历会跳过常见 registry 元数据字符串，避免误入翻译队列，并按记录前缀或子字段可推导 metadata 保留 managed-reference TextUnit context。enum `value__` backing field 和 `LayerMask` / `BitField` 的 `m_Bits` backing field 已可语义化解码和替换；`Vector2f/3f/4f`、`Quaternionf`、`ColorRGBA`、`Rectf`、`AABB/Bounds/Ray`、`Matrix4x4f`、`Vector2Int/Vector3Int`、`RectInt`、`BoundsInt`、`RangeInt`、`GUID`、`Hash128` 等固定 Unity 值类型的 leaf 和 direct child TypeTree 形态已可结构化解码和语义替换；array/vector/staticvector/List/HashSet/map 元素与 registry payload 字段已保留独立 field path、offset 和 byte size，可用于字符串元素 patch，managed-reference registry payload 字符串、enum、bit_field、unknown fixed-size raw bytes、object 字段组合和 TypeTree schema 支撑的 array/vector/List/HashSet/map 已可整体变长替换，`first/second` 与 `key/value` map entry schema 已有 serialized 和 UnityFS 重建回归，ScriptableObject `key/value` map 解析、变长替换和 UnityFS 重建已有专门回归，且嵌套 vector `Array`、`List<T>` / `HashSet<T>` 集合 alias、enum、bit_field、unknown fixed-size raw bytes 与 managed-reference payload 字段已有重建回归覆盖；解析模块当前处于维护冻结，未见样本驱动的完整 managed reference registry / map entry 变体、unknown 字段结构语义和版本差异冻结后再推进。
2. Addressables 当前目标 JSON/compact 字段链已补齐；未识别的独立二进制格式仍返回明确错误，不静默降级。
3. 官方 release 已可配置导入 CAS + ResourceRepository，并可通过 `resource.index` 查询现有资源索引；Resource metadata 已记录 release、平台、bundle path、parse status、TextAsset 名称和 TextUnit 摘要。
4. 不能完成复杂对象字段重打包，也不能从真实 Crowdin 结果自动生成完整汉化文件集合。

---

## 4. 补全顺序

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

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

交付：

1. `official-resource-changes.json` 记录当前 release 相对上一完整 release 的新增、变更、删除资源，以及解析/翻译候选计数。
2. `crowdin-translation-handoff.json` 只包含新增+变更资源，作为后续 Crowdin worker 的本地队列输入；当前解析阶段不直接调用 Crowdin API。
3. `official-parse-cache.json` 记录 manifest entry、zip entry、解析状态、Unity 版本、文件数、TextAsset 数、TextUnit 数/格式、错误摘要和缓存复用状态。
4. `official-textunit-index.json` 持久化单条 TextUnit 和解析错误，保留 destination、archive entry、serialized file、path id、class id、field path、offset 和 format 等定位信息。
5. `official-textunit-tasks.json` 只从 Added/Modified 资源、parse cache 和 TextUnit 明细索引派生，记录可翻译 TextUnit 任务和跳过原因。
6. `crowdin-textunit-queue.json` 只包含已经产生 TextUnit 的离线任务，当前不调用 Crowdin 网络 API。
7. 解析直接 `.bundle` / `.unity3d` 和 zip 内全部文件条目，不能只假设 `FullPatch_*.zip`。
8. 非候选资源记录为 unsupported，不影响官方同步发布。
9. 缺失、损坏或无法解析的 bundle 记录 failed，但不回滚已经完成校验的官方原版 release。
10. 用合成 fixture、隔离真实样本和回归 fixture 覆盖资源变更集、Crowdin handoff、TextUnit 队列、缓存复用、zip 内条目、非候选资源、解析失败。

验收：

1. 新 release 发布时能生成资源变更集，新增+变更资源进入解析/翻译候选，删除资源不进入翻译队列。
2. 第二次 up-to-date 轮询不会重复解析已有有效缓存和 TextUnit 明细索引。
3. 修改任意 manifest entry 的 size/BLAKE3 后，变更集能标记对应资源并让后续解析/翻译只消费候选。
4. 解析缓存、handoff 和 TextUnit 队列不会写入汉化发布根。

### 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，不静默丢字段。

本次 issue #2 交付已完成上述 JSON/compact 字段链：provider ID、bundle name、
primary/dependency key、resource type、hash、size 和 CRC 会进入 `ResourceEntry`，
并通过 SQLite `ResourceRepository` 持久化；旧索引会按列迁移继续可读。独立二进制
catalog 仍按“明确不支持”处理，不把低保真路径伪装成完整解析。

验收：

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、vector/staticvector 嵌套 `Array`、`List<T>` / `HashSet<T>` 集合 alias、map、PPtr、enum `value__` backing field、`LayerMask` / `BitField` 的 `m_Bits` backing field、常见固定 Unity 值类型的 leaf/direct-child 形态，以及 unknown fixed-size raw bytes 保留和同长度替换。
3. TextAsset 已有专用 name/bytes 读取，避免和字段级遍历重复报错。
4. MonoBehaviour 和 ScriptableObject 的 TypeTree 字段遍历入口已落地，复杂版本差异继续补 fixture。
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、bundle path、archive entry、serialized file、object path id、class id、field path、字段 offset/byte size、版本和上下文；managed-reference payload 会额外写入 reference id、full type name、assembly、namespace 和 class 上下文。
2. TextAsset 已支持 JSON/CSV/TSV/plain text 探测，二进制 payload 单独计数。
3. MonoBehaviour/ScriptableObject 已按字段路径提取字符串。
4. 保留重复文本和上下文，不在解析阶段做会丢定位的合并。
5. 已提供 JSONL 第一稳定格式，CSV/XLIFF 可后置。

验收：

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

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

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

交付：

1. 官方同步完成后可配置触发导入 CAS + ResourceRepository（已具备 `--import-repository` / `BAT_IMPORT_REPOSITORY=1`）。
2. ResourceRepository 已保存官方 manifest 资源的类型、路径、hash、size 和 metadata；metadata 包含 release、平台、bundle path、parse status、TextAsset 名称、TextUnit 数量/格式。
3. 支持 RPC/CLI 查询资源、bundle、TextAsset、解析错误和缓存状态；当前 `resource.index` 会返回资源 metadata，`parse-status` 会返回 TextUnit 索引和队列摘要，`parse-text-units` / `parse-errors` 会按当前 release 查询明细，`localized-status` 会校验 patch manifest。
4. schema 迁移可重复执行；当前 SQLite 已有 `crc` 和 `metadata_json` 兼容迁移。

验收：

1. 可以按版本、路径、类型、hash 查询，并在结果 metadata 中看到 TextAsset / TextUnit 摘要。
2. 解析缓存、资源变更集和 repository 数据能从同一 manifest fingerprint 追溯。
3. CAS 对象跨版本复用，不重复存储相同文件。

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

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

交付：

1. 已定义 `localized-patch-manifest.json`：目标官方版本、localized release、输出文件、hash、size、byte delta、TextAsset 操作和回滚信息。
2. 已支持 UnityFS TextAsset raw bytes 替换的最小 patch 路径。
3. MonoBehaviour/ScriptableObject 字段替换必须依赖 P2 字段级解析结果。
4. Patch 产物写入配置化汉化发布根下的 `.staging/<id>`，校验通过后发布到 `versions/<id>` 并切换 `current`。
5. 成功后发布状态从 `not_localized` 切到 `localized`；`localized.status` 要求 state、current symlink 和 patch manifest 同时匹配当前官方 release。

验收：

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

---

## 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. 基于 `translation.worker.run` 推进翻译记忆和 Patch 构建。
4. 扩展翻译任务结果在 CAS/ResourceRepository 查询面的索引，推进 G-011。
5. 在通用 Binary/JSON/Text Patch 基础上继续扩展复杂 AssetBundle 重打包和发布流程统一，保留当前 UnityFS TextAsset patch 发布前置链路。