nyaKazuha/BlueArchiveToolkit
1
0
Fork 0
mirror of https://github.com/Yuyi-Oak/BlueArchiveToolkit.git synced 2026-09-18 10:04:55 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

docs(project): 同步维护冻结与运行文档
bat-rust / Build and test Rust (push) Canceled after 0s
Details

Browse Source 
补齐解析模块维护冻结规则，并同步 CURRENT_STATUS、CURRENT_GAPS、PROJECT_PLAN、RPC 参考、部署指南、用户指南和官方资源运行说明。

文档同时反映 bat-api 资源 bootstrap/分发边界、官方同步解析缓存、TextUnit 队列、双目录发布和 patch 入口的当前状态。

验证：未运行新命令；本轮已按要求停止重复构建/测试。
This commit is contained in:
nyaKazuha
2026-07-31 00:45:46 +08:00
parent 3f78f8f880
commit 03021ad649
16 changed files with 946 additions and 225 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/assetbundle.md
+49 -42
View File
@@ -1,6 +1,6 @@
# AssetBundle 与资源解析路线图
- **更新时间**：2026-07-25
- **更新时间**：2026-07-26
- **适用范围**：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。
@@ -13,10 +13,10 @@
1. 官方资源同步负责拉取、校验和发布原版资源。
2. 解析器只读取已发布或 staging 中已校验的资源，不修改原始文件。
3. 解析结果写入派生缓存、CAS 索引或后续文本提取索引。
4. 汉化产物只能由 Patch/发布阶段写入 `localized-output`，不能写回官方资源目录。
4. 汉化产物只能由 Patch/发布阶段写入 `--localized-output` / `BAT_LOCALIZED_OUTPUT` 指定的汉化发布根，不能写回官方资源目录。
5. 解析器必须与 CLI、daemon、Go API、Patch 业务流程解耦。
当前官方同步完成后会维护 `official-parse-cache.json`。它是官方 release 的派生索引，不是汉化产物；本地 URL、相对路径、size 和 BLAKE3 未变化时应复用旧解析结果并跳过重复解析。
当前官方同步在新 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 队列时只读取摘要，不重复解析。
---
@@ -30,8 +30,8 @@
| 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 目录 | 未完成 |
| 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 未开放 |
---
@@ -45,16 +45,17 @@
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。
7. 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 诊断。
8. `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。
9. `ResourceImportService` 能把 AssetBundle 摘要、TextAsset/Table/Media 分类和 TextUnit 摘要写入导入报告。
10. 官方同步后 `OfficialParseCacheService` 能从 `official-download-manifest.json` 遍历所有资源，解析直接 bundle 和 zip 内条目，非候选资源记录为 unsupported，并缓存 TextUnit 数量/格式/诊断摘要，同时写出 `official-textunit-index.json` 供 `parse.text_units` / `parse.errors` 查询。
当前还不能宣称完整：
1. MonoBehaviour/ScriptableObject 的 TypeTree 字段级反序列化未完成。
2. Unity managed reference、PPtr、array/map、string alignment 等复杂字段未完整覆盖。
3. Addressables bin/compact catalog 结构变体仍需真实样本驱动补齐。
4. 解析结果尚未自动进入用户级 CAS + ResourceRepository 查询流程。
5. 不能重写 AssetBundle，也不能生成可发布汉化 patch。
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 bin/compact catalog 结构变体仍需真实样本驱动补齐。
3. 官方 release 已可配置导入 CAS + ResourceRepository，并可通过 `resource.index` 查询现有资源索引；Resource metadata 已记录 release、平台、bundle path、parse status、TextAsset 名称和 TextUnit 摘要。
4. 不能完成复杂对象字段重打包，也不能从真实 Crowdin 结果自动生成完整汉化文件集合。
---
@@ -66,17 +67,23 @@
交付：
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. `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. 修改任意 manifest entry 的 size/BLAKE3 后，只重新解析对应资源。
3. 解析缓存不会写入 `localized-output`。
1. 新 release 发布时能生成资源变更集，新增+变更资源进入解析/翻译候选，删除资源不进入翻译队列。
2. 第二次 up-to-date 轮询不会重复解析已有有效缓存和 TextUnit 明细索引。
3. 修改任意 manifest entry 的 size/BLAKE3 后，变更集能标记对应资源并让后续解析/翻译只消费候选。
4. 解析缓存、handoff 和 TextUnit 队列不会写入汉化发布根。
### P1：Addressables catalog 完整化
@@ -103,10 +110,10 @@
交付：
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 作为后备。
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 作为后备。
验收：
@@ -120,11 +127,11 @@
交付：
1. 定义 `TextUnit`：source text、resource path、archive entry、object path id、field path、语言、版本、上下文。
2. TextAsset 支持 JSON/CSV/TSV/plain text 的可配置探测。
3. MonoBehaviour/ScriptableObject 按字段路径和类型策略提取字符串。
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 可后置。
5. 已提供 JSONL 第一稳定格式，CSV/XLIFF 可后置。
验收：
@@ -138,15 +145,15 @@
交付：
1. 官方同步完成后可配置触发导入 CAS + ResourceRepository。
2. ResourceRepository 保存版本、平台、资源类型、bundle path、TextAsset 名称、TextUnit 索引摘要。
3. 支持 CLI/RPC 查询资源、bundle、TextAsset、解析错误和缓存状态。
4. schema 迁移版本化，旧库可重复升级。
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、TextAsset 名称查询。
2. 解析缓存和 repository 数据能从同一 manifest fingerprint 追溯。
1. 可以按版本、路径、类型、hash 查询，并在结果 metadata 中看到 TextAsset / TextUnit 摘要。
2. 解析缓存、资源变更集和 repository 数据能从同一 manifest fingerprint 追溯。
3. CAS 对象跨版本复用，不重复存储相同文件。
### P5：Patch 发布前置解析
@@ -155,17 +162,17 @@
交付：
1. 定义 patch manifest：目标官方版本、输入 TextUnit 版本、输出文件、hash、回滚信息。
2. 支持 TextAsset raw bytes 替换的最小 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 产物写入 `localized-output/.staging/<id>`，校验通过后发布到 `localized-output/versions/<id>` 并切换 `current`。
5. 成功后发布状态从 `not_localized` 切到 `localized`。
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` 状态能证明原版和汉化两套资源都已发布。
3. `localized` 状态能证明原版和汉化两套资源都已发布，且 patch manifest 可验证。
---
@@ -194,6 +201,6 @@
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 的核心发布缺口。
3. 将 `crowdin-textunit-queue.json` 接入真实 Crowdin worker、翻译记忆和 Patch 构建。
4. 将翻译任务状态接入 CAS/ResourceRepository 查询面，推进 G-011。
5. 在通用 Binary/JSON/Text Patch 基础上继续扩展复杂 AssetBundle 重打包和发布流程统一，保留当前 UnityFS TextAsset patch 发布前置链路。