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 的核心发布缺口。