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，冻结期只接受稳定性、诊断、真实回归和文档一致性修复。

---

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 发布前置链路。