BlueArchiveToolkit/docs/reports/historical/PARSER_FREEZE.md

解析模块维护冻结（历史记录）

状态：历史记录，已解除 生效时间：2026-07-30 解除时间：2026-09-04

本文保留解析模块维护冻结期间的原始规则和例外说明。冻结已于 2026-09-04 解除，以下内容不构成当前开发约束；当前解析开发以源码、测试、 CURRENT_STATUS.md 和 docs/architecture/assetbundle.md 为准。

---

原冻结记录

原记录发布时状态：生效中

冻结目标：停止继续扩大 UnityFS / AssetBundle / Addressables / TypeTree 解析能力，把当前工作重心切换到运行稳定性、代码审核问题、文档一致性和发布链路可靠性。

冻结范围

冻结覆盖以下 Rust 解析相关模块和对外入口：

• crates/bat-assetbundle
• adapters/src/unity*
• infrastructure/src/official_parse.rs
• infrastructure/src/resources.rs 中解析缓存、TextUnit 索引和解析状态相关逻辑
• unityfs.*、parse.*、text.* 相关 RPC / CLI 契约
• Addressables catalog、UnityFS、serialized file、TypeTree、TextUnit、AssetBundle patch 相关文档声明

允许变更

冻结期只允许以下解析相关变更：

• 修复编译失败、格式化失败、clippy 报错和测试失败。
• 修复真实运行中已经复现的 panic、错误状态污染、重复解析、缓存失效、状态不一致或诊断误导。
• 补充回归测试，前提是测试覆盖的是已存在能力的稳定性问题，不宣称新增解析能力。
• 修正文档、CLI 帮助、RPC 参考和状态文件中与当前实现不一致的解析能力声明。
• 改善错误信息、日志字段、状态记录和失败恢复，但不得改变解析输出契约，除非是修复错误契约且同步迁移说明。

issue 43 的明确例外

本次 issue 43 经用户明确授权，允许新增 bat 的工作流编排入口：

• parse run 只刷新已有解析输出、TextUnit 索引和翻译队列；
• parse repack 只调用已有 TextAsset、TypeTree string 和受支持语义字段 patch 实现；
• i18n 工作台和 publish 只消费已有 TextUnit 输出，并发布独立汉化 release。

该例外不解冻解析器，不新增 UnityFS/AssetBundle/Addressables/TypeTree 解析类型、字段覆盖、catalog 结构或合成 fixture 能力。后续任何扩大解析覆盖的变更仍需单独解冻授权。

issue 2/3 的开发例外

授权时间：2026-08-19

用户明确授权将 issue #2/#3 作为解析开发进展继续推进。本次例外允许：

• Addressables JSON/compact catalog 的 provider、bundle name、hash、size、CRC、资源类型和依赖关系字段补全，以及对应 SQLite/fixture 回归；
• UnityFS 已有 header、block、directory、压缩和 alignment 能力的校验加固，以及隔离真实 bundle 回归；
• 更新解析路线图、状态和 RPC/CLI 资源索引字段说明。

本次例外不包含发布级复杂对象重打包、完整 Unity 版本兼容承诺或新的汉化发布控制面；这些仍按后续 Patch/发布路线单独验收。

禁止变更

冻结期禁止以下解析相关变更：

• 新增 TypeTree 语义类型、字段族、managed reference 变体、Unity 内建结构体覆盖或 Addressables catalog 结构覆盖。
• 用纯合成 fixture 推进“完整解析”并把它记录为已支持能力。
• 开放新的写入型 unityfs.* / patch.* RPC 或 CLI。
• 修改解析结果 schema、TextUnit schema、patch field JSON 语义或缓存状态格式，除非它是阻断级 bug 修复并附带兼容策略。
• 将解析器和官方同步、汉化发布、Go API、Crowdin 或客户端流程进一步耦合。

解冻条件

解析扩展重新启动前必须同时满足：

• Rust bat 官方同步、daemon、status、校验、断点续传、增量更新和解析缓存链路稳定。
• 当前 P0/P1 维护 issue 已关闭或被明确降级。
• bat-api 与 Rust RPC / CLI 契约完成字段统一和联调验证。
• 真实资源 fixture、验证命令和验收标准已写入文档，不能只依赖合成样本。

冻结期验证

解析相关维护变更至少运行：

cargo fmt --check
cargo test -p bat-assetbundle --locked
cargo clippy -p bat-assetbundle --all-targets --locked -- -D warnings

如果变更影响 bat CLI、RPC、官方解析缓存或 TextUnit 索引，还必须补充对应 bat-infrastructure 测试或说明未运行原因。