BlueArchiveToolkit/CURRENT_STATUS.md

# BlueArchiveToolkit 当前工作区状态

- **更新时间**：2026-09-08
- **状态来源**：本地工作区盘点、代码验证和最新提交
- **状态分支**：`experiment`
- **最新已推送功能提交**：以当前 `git log --oneline -1` 为准
- **权威计划**：`PROJECT_PLAN.md`
- **Go 进度权威**：`docs/reports/GO_STATUS.md`

---

## 1. 总体判断

当前项目处于 **稳定基线完成、CAS V1 已落地、Rust 官方资源同步链路已具备可持续生产运行形态、Go 侧以 `bat-api` 资源 bootstrap/分发 MVP + `backendrpc` 为正式服务入口（同步/运维命令行仍为近乎全自动的 Rust `bat`）** 阶段。

Rust 侧官方日服资源链路已经从实验验证推进到正式入口：

1. 首次运行可以通过 `--auto-discover` 从官方 HTTP metadata 解析 `GameMainConfig`，自动获得 `app-version`、`connection-group` 和 `server-info`；解密出的 `GameMainConfig` JSON 会校验已知字段，避免把错误解密结果当成成功。自动发现会记录 launcher metadata、launcher CDN config、remote manifest 文件列表 digest、选中的 `resources.assets` 来源和 `GameMainConfig` 摘要。
2. 不安装、不启动、不依赖已安装官方启动器。
3. 默认平台为 `Windows + Android`。
4. 能生成官方全量 pull plan，执行真实下载，维护 release 内的 `official-download-manifest.json`。
5. 下载后使用本地 manifest 的 size + BLAKE3 校验复用文件；所有 `.zip` 在下载验收、复用、本地 audit/verify 时做 ZIP 结构校验；官方 seed `.hash` 使用标准 `xxHash32(seed=0)` 强校验（早期实现的非标准 avalanche 常量已修正）。
6. 支持 `.part` 断点续传、失败后 clean retry、本地 manifest audit/repair、失败 staging 恢复复用、403/404/5xx 分类重试（重试带指数退避）、下载 quarantine 诊断，以及旧 launcher 包官方 primary/backup CDN 切换。启动器/server-info 先行更新但 client-patch seed marker 或必需 seed catalog 尚未开放时，会进入 `waiting_for_official_resources`，保留现有 `current`，不创建失败 staging，也不写入失败版本循环；启用 `--auto-discover` 的非 dry-run 会写入 `<output>/official-launcher-bootstrap.pending.json` 作为维护期证据。下载默认使用 8 个独立 worker，范围为 `1..=256`；每个 worker 完成当前 URL 后立即从共享计划队列领取下一个任务，进度按实际完成顺序即时上报，最终 report 资源列表仍按计划顺序输出。manifest/quarantine 簿记与 seed `.hash` 校验仍逐项执行，`fail-fast` 与「不发布不完整资源」不变量不变。下载进度按已完成数量单调上报，不再使用 plan 序号计算百分比。新 staging 还会按规范化 destination 查找已发布历史 release，重新校验 size、BLAKE3 和 ZIP 结构后用硬链接或跨文件系统复制复用；历史文件不满足条件时再验证配置的 CAS 对象，最后才回退网络，并把 `release_reused`、`cas_reused`、`downloaded` 和复用诊断写入报告。
7. 支持 curl 传输层本地代理：默认自动检测 `HTTPS_PROXY` / `ALL_PROXY` / `HTTP_PROXY` 及小写环境变量（带凭据的代理推荐用环境变量配置），也可用 `--proxy <URL>` 显式指定或 `--no-proxy` 强制直连；代理决策会写入 progress log、daemon log 和 `bat doctor` 诊断输出。代理凭据不落世界可读位置：日志/`status` 脱敏，传给 curl 经 `ALL_PROXY` 环境变量而非 argv，`--daemon` 下经环境变量下传后台子进程、不进子进程 argv 或 `bat-status.json`，复用凭据存于 `bat-proxy.secret`（`0600`）且 `clean-stable` 会清除。
8. `bat --watch` 可常驻运行，`bat --daemon` 可后台运行并用 `bat status` / `bat stop` / `bat restart` / `bat reload` / `bat logs` 管理；daemon 使用 `bat.sock` Unix socket JSON-RPC 作为 live 控制通道，PID/状态/日志文件作为快照和 fallback，`bat-events.jsonl` 记录带轮转的结构化事件日志，`bat-control.lock` 串行化控制命令；正常检查默认每 1 小时一次；远端和本地一致时默认静默，失败后默认 60 秒快速重试，官方资源端尚未开放时状态为 `waiting` 并同样按错误重试间隔探测；`resource.state` / `catalog.status` / `parse.status` / `localized.status` 会返回 `status` 与稳定 `status_code`（如 `official.up_to_date`、`official.published`、`parse.completed`、`translation.queued_offline`、`localized.published`、`distribution.ready`），供 `bat-api` 等读侧判断阶段、终态和重试属性；CLI 默认向 stdout 输出人类可读摘要，向 stderr 输出 ASCII banner、progress log、失败分类和 quarantine 状态，需要机器输出时使用 `--json --no-progress`。
9. 远端 snapshot 未变化但输出目录为空时，会按首次运行执行全量拉取；官方 seed `.hash` 校验失败时会清理对应 manifest 条目，避免失败产物被后续本地 audit 误判为可复用。
10. 默认官方原版资源目录是 `./bat-resources`，默认汉化产物目录是 `./bat-localized`，默认后台状态目录是 `/tmp/bat-pid`；官方资源目录是发布根目录，包含 `current` symlink、`versions/<id>` 和 `.staging/<id>`，非 dry-run 会先写 staging，校验完成后发布 versioned 目录并原子切换 `current`；启用 `--auto-discover` 的 release 会包含 `official-launcher-bootstrap.json`，up-to-date 轮询会为旧 release 补写该产物；如果上一轮同一 app version、bundle version 和 Addressables root 的 staging 失败但目录仍安全存在，下一轮会复用该 staging 并按 manifest 逐文件校验/补下载；从 CAS 复用的 release 会在自身目录保存版本化 `official-cas-reuse-references.json`，孤儿 staging 清理或 release 清理时按清单递减 CAS 引用，避免 CAS GC 误删仍被 release 使用的对象；后台状态目录包含 `bat.sock`、`bat.pid`、`bat-status.json`、`bat-daemon.log`、`bat-events.jsonl`、任务历史 `bat-tasks.json` 和短生命周期 `bat-control.lock`；非 dry-run 使用 `--output/.official-sync.lock` 防止并发写同一资源目录，live daemon 会阻止前台写命令直接修改它正在管理的同一目录。
11. 官方同步会拒绝危险输出目录、路径逃逸和现有 symlink 路径组件；下载目标、`.part`、manifest、snapshot、PID、status、log 和控制锁文件不会跟随 symlink，daemon 状态类文件默认以 `0600` 权限创建。
12. `<output>/official-version-state.json` 会明确保存当前已完成版本、正在拉取版本、上一个可用版本和失败版本；同一 app version、bundle version 和 Addressables root 的失败只保留最新一条，同一版本开始重新拉取或后续发布成功时会清理对应失败记录；`bat status` 会显示最后成功时间、下次检查时间、最后错误摘要、当前阶段、当前下载 URL 进度、版本状态摘要、最近历史失败版本和原因、结构化日志路径和轮转日志路径，人类可读输出不会把完整版本状态 JSON 内联打印。
13. 资源导入链路已支持 CAS + `ResourceRepository` 索引写入，官方同步可用 `--import-repository` / `BAT_IMPORT_REPOSITORY=1` 在已校验 release 发布后触发导入，默认 CAS 路径为 `<output>/.cas`、SQLite 索引为 `<output>/resources.sqlite`，也可通过 `--import-cas-root`、`--import-resource-db`、`BAT_IMPORT_CAS_ROOT`、`BAT_IMPORT_RESOURCE_DB` 覆盖；`resource.index` RPC/CLI 可按类型、hash、路径模式、官方 release ID、平台、destination、bundle path、archive entry、parse status 和 TextUnit format 分页查询现有索引，release、平台、bundle path 和常用数组 metadata 过滤已下推到 SQLite，数据库不存在时返回 `available=false` 且不会创建空库；`bat doctor cas` 可只读检查既有 CAS 根目录、对象目录、元数据库文件和对象统计，不会因诊断创建空库。`Resource` metadata 已通过 `metadata_json` 兼容迁移保存 release、平台、bundle path、parse status、TextAsset 名称和 TextUnit 数量/格式；当前/上一个/结构变化 catalog、失败 staging 复用、403/404、hash mismatch、CRC、metadata 迁移与 UnityFS 边界校验均有离线回归 fixture 或单测覆盖。
14. 非 dry-run 官方同步在校验完成并发布后，会先对比上一完整 release 与当前 release 的 `official-download-manifest.json`，在当前 release 下写入 `official-resource-changes.json` 和 `crowdin-translation-handoff.json`；同一 destination 只有 size 或 BLAKE3 改变才算 modified，仅 URL/CDN 根变化但内容相同不会触发解析/翻译候选。随后刷新 `official-parse-cache.json` 和 `official-textunit-index.json`，并从 Added/Modified 资源、parse cache 与 TextUnit 明细索引派生 `official-textunit-tasks.json` 和 `crowdin-textunit-queue.json`；删除资源只进入差异记录，不进入 TextUnit/Crowdin 队列。`parse.text_units` 和 `parse.errors` RPC/CLI 可按 destination、archive entry、path id、class id、field path 和 format 查询当前 release 的 TextUnit 明细与解析错误；`translation.tasks` RPC/CLI 可按 release、destination、archive entry、任务状态、parse status、TextUnit format 和 reason presence 查询离线 TextUnit 翻译任务状态与跳过/失败原因；`translation.task.update` 可回写 provider worker 状态，`translation.worker.run` 可触发 Rust provider worker 独立 claim/lease/retry 并落库 TextUnit 级译文结果，`translation.proofread` 可把汉化 workflow 标记为人工校对中；TextUnit 已包含 class id、field path、字段 offset/byte size 等可追溯定位。Crowdin provider 通过 `CROWDIN_*` 环境变量接入，mock provider 支持本地 fixture；up-to-date 轮询在已有有效解析缓存、TextUnit 明细索引和 TextUnit 队列时只读取摘要，不重复解析。官方同步报告默认 `localized_release_status=not_localized`，含义是原版资源已经发布、汉化资源未发布；受支持的 UnityFS TextAsset、TypeTree string field 和 managed-reference string field 发布成功后会写带 trace 的 `localized-patch-manifest.json`，校验 hash/size/diff/rollback 后才允许 `localized.status` 返回 `status=published`、`status_code=localized.published` 和 `localized_release_status=localized`，并可用 `localized.rollback` 显式恢复上一 release。`bat` 首次启动会在二进制所在目录释放 `config.toml.example` 配置模板（`0600`），`config.toml` 存在且 Unix 权限为 `0600` 或更严格时读取并使用它；`config.toml` 不存在时仅保留模板，不自动读取 example，运行时继续使用环境变量和内置默认值。优先级为命令行参数 > 进程环境变量 > `config.toml` > 内置默认值，`BAT_SKIP_ENV_FILE` 已废弃且不再影响启动；Redis 键为预留。daemon 任务历史持久化在 `<state-dir>/bat-tasks.json`（版本化、`0600` 原子写），重启后任务经 `task.*` 仍可查，中断任务标记 `task_interrupted`（`BAT-ERR-700005`）。官方同步报告还分别统计当前 manifest 复用、历史 release 复用、CAS 复用、网络传输字节和复用回退诊断，下载事件状态使用 `release_reused`、`cas_reused`、`downloaded` 等稳定值。

15. Rust `bat` 已提供 `res` / `parse` / `i18n` 工作流入口：支持资源拉取、解析刷新、可再生解析缓存清理、离线翻译工作台、人工文本查看/修改/清空、工作台发布前校验、有限 TextAsset 汉化发布、人工校对状态标记、既有 patch 能力的批量重打包、单次/限定次数/周期执行和版本化 schedule CRUD。`translation.worker.run` 已接入 provider worker：默认并发 8、范围 `1..=256`，每个 worker 独立 claim 下一项任务并落库 lease、失败分类、重试计划和 TextUnit 译文结果。schedule 查询现在按一级工作流过滤，删除/执行会校验作用域，单轮执行可限制计划数；schedule CRUD、翻译任务查询/交接视图、翻译任务状态回写、provider worker 触发和 `translation.proofread` 状态标记已通过 `bat.sock` 的 RPC 以及 `bat-api` 的鉴权管理接口暴露，dashboard 不维护第二套状态。`bat-api` 已提供内嵌 dashboard MVP，静态资产由 Go embed 暴露在 `/admin/dashboard/`，页面直接调用已有鉴权接口控制资源、调度、翻译、任务、日志、parse TextUnit 查询和 localized 发布/回滚。该工作流只编排已有解析和 patch 能力，不扩大解析器覆盖；完整 AssetBundle 重打包和完整 Web 协作后台仍是后续工作。真实官方网络全量拉取 smoke 已固化，真实大文件与运行报告默认在 `/tmp` 隔离目录，不纳入 Git。Go 细节见 `docs/reports/GO_STATUS.md`。

当前翻译交接还包括 `translation-tasks.sqlite` 和版本化 `translation-handoff.json`；跨 release 的 Translation Memory V1 位于 `<output>/translation-memory.sqlite`，不放在 `versions/<id>` 或 release task 库中；
`translation.tasks` 查询单项 worker 状态，`translation.handoff` 查询完整
job/unit/provider run 状态；`translation.memory.summary/query/confirm` 提供
Rust-owned TM 的摘要、source/context 查询和显式 trusted 确认，`bat-api` 仅作
typed 管理转发。当前下载实现使用默认 8 个独立 worker，完成后动态领取
任务，最终资源报告按 pull plan 顺序输出。
项目级 Glossary V1 位于 `<output>/glossary.sqlite`，独立于 release task 和 TM；
Rust `bat` 持有 term/alias/recommended/allowed/category/priority、全局或
TextUnit scope、source history 和 approved review。worker、TM 复用、人工 task
结果和 workbench publish 都执行确定性 QA；blocking deviation 必须携带
稳定 `qa_identity` 以及 reviewer/reason/provenance 的显式 override，所有接受路径都会
按当前 QA 精确校验 identity。`translation.glossary.*` 已通过
`bat.sock` 暴露，Go `bat-api` 仅做鉴权 typed forwarding。

---

## 2. 权威文档入口

- `README.md`：项目概览、当前可用能力和快速验证。
- `PROJECT_PLAN.md`：最终目标、里程碑和近期任务。
- `DOCS_INDEX.md`：文档阅读顺序和索引。
- `docs/guides/official-resource-test-pull.md`：官方资源拉取与自动更新用户指南。
- `docs/guides/official-full-pull-smoke.md`：真实官方全量拉取 smoke runbook 和可重复命令。
- `docs/guides/bat-workflows.md`：Rust `bat` 的 `res` / `parse` / `i18n` 工作流、调度计划和 `bat-api` 调度接口。
- `docs/architecture/official-resource-backend.md`：官方资源后端设计和审核说明。
- `docs/architecture/assetbundle.md`：解析补全路线图，覆盖 Addressables、UnityFS、Serialized 字段级解析、文本提取、CAS 接入和 Patch 发布前置。
- `docs/reports/CURRENT_GAPS.md`：当前缺口和关闭顺序。

历史 Week 2/Week 3 报告只作追溯，不再代表当前状态。

---

## 3. 当前模块状态

### Rust workspace

已显式纳入 workspace：

- `core`
- `adapters`
- `infrastructure`
- `crates/bat-assetbundle`
- `crates/bat-cas-engine`
- `crates/bat-ffi`
- `crates/bat-patch`

### `bat-core`

状态：**领域模型和仓储接口骨架可用**

已包含：

- `GameClient`
- `GameVersion`
- `Resource`
- `Translation`
- `CasRepository`
- `ResourceRepository`
- `TranslationRepository`

待完成：

- 领域服务模块仍为空。
- Provider、Patch、Manifest 等后续仓储/服务接口需要补齐。
- 公共错误模型需要与 CLI/API 错误码统一。

### `bat-adapters`

状态：**适配器框架可用，官方日服规则和 Addressables 当前样本解析已推进**

已包含：

- Unity adapter trait、注册表、Unity 2021.3 adapter 基础解析与校验。
- Manifest driver trait、Addressables driver、注册表。
- Addressables JSON/compact catalog 的 path、hash、size、address、dependencies、provider ID、bundle name、CRC、metadata 解析。
- 真实形态 Addressables fixture/golden 测试。
- 当前 catalog、上一个版本 catalog、结构变化 catalog 的离线回归 fixture。
- 官方日服 `server-info`、URL 规则、平台 discovery 和 inventory 枚举；`MediaCatalog.bytes` 使用官方相对路径生成媒体 URL，覆盖 `GameData/`、`Prologue/` 下的 zip/mp4/png/jpg/ogg/wav 等媒体资源，避免把叶子文件名误拼到媒体根目录。

待完成：

- `crates/bat-assetbundle` 已具备 UnityFS 容器、对象表、TypeTree 元数据、基础字段读取、TextAsset 和 TextUnit 提取；UnityFS 容器已补充总大小、计数、路径、重复 directory、LZMA 和边界校验，并通过 UnityPy 真实 bundle 隔离回归；已有 TextAsset、TypeTree string field 和 managed-reference string field 的 localized patch 发布闭环，真实复杂版本差异、整体 AssetBundle 重打包和通用 Patch 仍未实现。
- Addressables parser 已覆盖当前真实形态 fixture/golden 与 `m_Crc`，但仍需继续覆盖二进制/压缩字段组合和更细失败诊断。
- 客户端发现、备份、应用补丁流程尚未连接真实实现。

### `bat-cas-engine`

状态：**CAS V1 已完成**

已包含：

- BLAKE3 Hash。
- 原子文件写入：临时文件、fsync、rename、目录 sync。
- 文件系统对象存储：put/get/exists/delete/list/stats。
- SQLite 对象元数据和引用计数。
- 引用计数增加、减少、查询。
- GC 候选查询和 GC 删除。
- 并发写入相同内容测试。
- 损坏对象 Hash mismatch 检测。
- infrastructure 仓储适配层。

待完成：

- 更复杂的跨进程压力测试。
- 未来需要时扩展流式大文件写入。
- 未来需要时扩展非 SQLite 元数据后端。

### `bat-infrastructure`

状态：**CAS 适配层、ResourceRepository 和官方资源同步入口可用**

已包含：

- `FileSystemCasRepository` 作为 `bat-core::CasRepository` 适配层。
- `InMemoryResourceRepository`。
- `SqliteResourceRepository`。
- 官方 pull plan 构建。
- `OfficialResourcePullService`：官方 URL 拒绝策略、目标路径映射、下载 manifest、下载 quarantine、`.part` 续传、curl 代理配置、403/404/5xx 分类重试、ZIP 结构校验、官方 seed `.hash` 校验、本地全量 verify。
- `OfficialUpdateService`：官方 metadata auto-discover、bootstrap cache、snapshot diff、marker diff、本地 audit/repair、失败 staging 恢复。
- `bat`：正式 CLI binary，支持 one-shot、`--proxy` / `--no-proxy`、`--watch`、`--daemon`、`status`、`stop`、`restart`、`reload`、`refresh`、`logs`、`verify`、`repair`、`doctor` 和 `clean-stable`。
- `report_output.rs`、`terminal_output.rs`：分别负责结果报告渲染和前台终端诊断、帮助、进度及结构化日志输出。

待完成：

- 基于已接入的 `translation.worker.run` 继续推进完整 Patch 构建/rollback；继续扩展更丰富的 TextUnit/TM/Glossary 查询和通用 Patch 发布资源视图。
- 真实线上全量下载 smoke 已固化为 `scripts/official-full-pull-smoke.sh` 和 `make official-smoke`；实际运行报告由脚本写入隔离输出目录。
- 增加更多权限和极端文件系统场景测试。

### `bat-assetbundle`

状态：**UnityFS 解包、TypeTree 字段读取、TextUnit 提取和受支持 localized patch 发布已可用；复杂结构覆盖与整体 AssetBundle 重打包仍待继续补齐**

解析扩展当前按路线图和真实 fixture 验收推进。

当前已有：

- `UnityFsParser`、`UnityFsBundle`、`ParsedAssetBundle`、`RawAssetBundle` 等正式类型。
- UnityFS header、block info、directory 解析。
- block info at end、LZ4/LZMA block info 解压、LZ4/LZMA 数据 block 解压、directory 文件提取、压缩/解压数据区大小和 directory 越界诊断。
- Unity serialized file header、type table、TypeTree node 元数据、object table 和 TextAsset bytes 提取。
- TypeTree 基础字段 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 值类型（`Vector2f/3f/4f`、`Quaternionf`、`ColorRGBA`、`Rectf`、`AABB/Bounds/Ray`、`Matrix4x4f`、`Vector2Int/Vector3Int`、`RectInt`、`BoundsInt`、`RangeInt`、`GUID`、`Hash128`）的 leaf 和 direct child TypeTree 形态、unknown fixed-size raw bytes 保留、TypeTree-covered managed reference / `SerializedReference` alias、TypeTree-covered managed reference registry 记录、常见 registry 命名别名（含 `m_ManagedReferences` / `RefIds` / verbose type 字段 / `managedReference*` 与 `serializedReference*` prefixed metadata）、managed-reference payload 命名别名（含 `data` / `value` / `payload` / `object` / `managedReferencePayload` / `referencePayload` / `serializedReferencePayload` / `managedReferenceValue` / `referenceValue` / `serializedReferenceValue` / `managedReferenceObject` / `referenceObject` / `serializedReferenceObject` / `managedReferenceData` / `referenceData` / `serializedData` / `serializedReferenceData`）、managed-reference full typename 拆解和 offset/size 诊断；array/vector/List/HashSet/map 元素与 registry payload 字段会保留独立 field path、offset 和 byte size，字符串元素可作为 patch 输入定位，enum 会暴露为语义化 `{type_name, storage_type, value}`，bit field 会暴露为语义化 `{type_name, storage_type, bits}`，object 字段组合、固定 Unity 值类型、enum、bit_field、unknown fixed-size raw bytes 同长度替换与 TypeTree schema 支撑的 array/vector/List/HashSet/map 已支持整体替换、长度变化和空容器扩容，map entry 的 `first/second` 与 `key/value` 字段命名已有重建回归覆盖。
- `TextUnitExtractor` 支持 JSON/CSV/TSV/plain TextAsset 探测、TypeTree 字段字符串提取和 JSONL 输出；TextUnit 明细包含 serialized file、path id、class id、field path、字段 offset/byte size、format、asset name 和上下文。managed-reference registry 的类型名、namespace、assembly 等元数据不会进入翻译文本队列，而是写入 payload TextUnit context；未能聚合成结构化 `references` 的 fallback registry 字段也会按 `RefIds[n]` 等记录前缀或子字段推导 managed-reference metadata 并写入 payload context，避免多条 fallback record 混用类型上下文。
- `ResourceImportService` 和 `official-parse-cache.json` 已包含 TextUnit 数量、格式和诊断摘要。
- `official-textunit-index.json` 已持久化单条 TextUnit 与解析错误；`parse.text_units` / `parse.errors` RPC 和 CLI 可分页过滤查询。
- `bat-adapters` 的 Unity 2021.3 adapter 已改为版本选择薄层，复用 `bat-assetbundle`，避免两套 UnityFS parser。

待完成：

- 真实 MonoBehaviour、ScriptableObject 版本差异、复杂容器结构调整、unknown 字段结构语义和未见样本驱动的完整 managed reference registry / map entry 变体覆盖；TypeTree-covered managed reference 字段与 registry 记录已可结构化解码，常见 full typename 可拆解为 assembly/namespace/class，不做低保真猜测。
- 复杂对象整体结构修改后的发布级 AssetBundle 重打包；UnityFS TextAsset、TypeTree string 字段、managed-reference registry payload 字符串、基础语义字段、enum、bit_field、object 字段组合和 TypeTree schema 支撑的 array/vector/map 整体替换的文件级链路已具备重建后校验，受支持 localized patch 已有独立 staging、manifest、current、状态校验和显式 rollback；整体 AssetBundle 发布仍未完成。
- 真实资源 fixture 覆盖对象级解析和文本提取。
- 详细补全顺序见 `docs/architecture/assetbundle.md`。

### `bat-patch`

状态：**通用 Binary/JSON/Text Patch 基础可用；受支持 localized patch 发布/rollback 已完成，通用 Patch 发布仍未完成**

当前已有确定性 Binary hunk diff/apply、RFC 6902 JSON Patch apply、UTF-8 Text Patch、通用 Patch manifest、BLAKE3/size 完整性校验和 rollback 元数据。`patch.apply` RPC 与 `patch-apply` CLI 已可对显式 source/patch/target 文件执行 Binary/JSON/Text patch，并返回 size/BLAKE3 报告；`unityfs.patch_text_asset` / `unityfs.patch_string_field` / `unityfs.patch_field` RPC 和 `unityfs-patch-text-asset` / `unityfs-patch-string-field` / `unityfs-patch-field` CLI 已可对显式 UnityFS bundle 输出目标文件。`unityfs.patch_field` 支持 bool、signed/unsigned integer、float raw bits、string、bytes、enum、bit_field、固定 Unity float/int/hash 值类型的 leaf/direct-child 形态、unknown fixed-size raw bytes 同长度替换、PPtr、object 字段组合和 TypeTree schema 支撑的 array/vector/List/HashSet/map 整体替换语义 JSON 值；array/vector/List/HashSet/map 扩容会复用当前首个元素或 TypeTree data node 的编码 schema，空容器扩容已用合成 fixture 覆盖，嵌套 vector `Array`、`List<T>` 和 `HashSet<T>` 形态、enum、bit_field、unknown fixed-size raw bytes、managed-reference registry `data` 和 `managedReferenceData` payload 字符串已有重建后重解析 fixture。`bat-assetbundle` + `LocalizedPatchService` 已能对 UnityFS TextAsset、TypeTree string field 和 managed-reference string field 执行替换，写入带 TextUnit/provider/review/rollback trace 的 localized patch manifest，在独立 staging 校验后发布汉化 release，并通过 `localized.publish` / `localized.rollback` RPC、`i18n publish` / `i18n rollback` CLI 和 bat-api 控制面暴露；`LocalizedPatchManifest` 可转换为通用 `bat_patch::PatchManifest`，通用 manifest 驱动发布仍未迁移。

待完成：

- 未见样本驱动的 map entry schema 变化、unknown 字段结构语义、完整 managed reference registry 变体驱动字段修改后的语义重打包。
- 通用 manifest 驱动的跨类型 patch build/apply/diff 发布；当前 localized 发布仅接受已验证 TextUnit 对应的受支持 UnityFS 文本字段，并不等价于整体 AssetBundle 重打包。
- `unityfs.inspect`、复杂 UnityFS 语义编辑和写入型发布工作流仍未开放。

### `bat-ffi`

状态：**可选无状态兼容层，非主集成边界**

已包含：

- `bat_version`。
- `bat_manifest_inspect_json`：解析 Addressables manifest 并返回 JSON summary。
- `bat_sync_plan_json`：根据 current/previous snapshot 生成官方同步计划 JSON。
- `internal/ffi/ffi.go` 提供可选 CGO 兼容包装骨架。

定位约束：

- `bat-ffi` 只暴露粗粒度、无状态、一次调用一次 JSON 输入输出的 C ABI helper。
- 它不持有 downloader、daemon、CAS handle、资源目录锁或长生命周期状态。
- 新的 Go 集成和生产运维读侧默认应调用 `bat.sock` RPC；`bat --json` 仅是
  Rust CLI 的机器输出形态，`bat-ffi` 仍是可选兼容层。
- FFI 仅用于需要嵌入 C ABI 的兼容场景，不能作为官方同步控制面或主集成边界。

待完成：

- 错误码与结构化响应约定。
- 如确有兼容需求，再补发布用头文件、构建脚本和跨平台产物。

### Go / API / Web

状态：**边界已确定；资源分发 MVP 已落地。权威细节见 `docs/reports/GO_STATUS.md`。**

| 角色 | 所有者 | 状态 |
|---|---|---|
| 同步/运维命令行（近乎全自动） | Rust `bat` | 产品入口 |
| 资源 bootstrap / 分发 HTTP | Go `cmd/bat-api` | bootstrap + CDN MVP + RPC 周期刷新/诊断 + readiness + 内嵌 dashboard |
| daemon RPC client | `internal/backendrpc` | 完成 |
| 试验 CLI | `cmd/bat` → `bin/bat-go` | 非产品 |
| FFI | `internal/ffi` | 可选 |
| 空目录 `api/` `pkg/` 等 | 占位 | 无实现 |
| Web | `web/` | 内嵌 dashboard MVP；完整协作后台仍未完成 |

默认 Go/docs 门禁：`make test-go-api`、`make build-go-api`、`make check-docs`（无 FFI）。

---

## 4. 已验证结果

以下命令已于 2026-09-04 在本地工作区执行并通过：

```bash
cargo fmt --all -- --check
cargo check --workspace --locked
cargo test --workspace --locked
cargo clippy --workspace --all-targets --locked -- -D warnings
```

Go 与文档门禁：

```bash
GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache make test-go-api
GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache make build-go-api
GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache go test ./...
GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache go vet ./...
make check-docs
```

当前仍未作为本地事实确认的项目包括：

- 真实官方全量 smoke 长期运行报告；命令已固化为 `make official-smoke`。
- `bat-api` 同机 live 联调：已由 `make bat-api-local-live-smoke` 在 `/tmp` 隔离目录完成；真实官方网络全量下载仍由 `make official-smoke` 独立跟踪。
- 完整 Web 协作后台。

---

## 5. 当前生产运行边界

当前唯一可作为 Linux 生产资源同步任务运行的入口仍是 Rust binary：

```bash
cargo run -p bat-infrastructure --bin bat -- \
  --auto-discover \
  --output /var/lib/bluearchive-toolkit/official \
  --watch
```

资源 HTTP bootstrap / 只读分发入口是 Go `cmd/bat-api`。生产拓扑下它与 Rust `bat` 同环境运行，经 `bat.sock` RPC 获取当前 `resource_root`，不在配置里写死资源目录；本地开发不能全量跑 `bat` 时用 fixture 和 Go 门禁验证。`internal/api/testdata/contract/` 已固化来自 Rust 输出并经归一化的 `catalog.status`、`resource.manifest`、`official-sync-snapshot.json` 和 Glossary query contract fixture，Go mirror 测试会防止字段名、null 语义和 provenance 再次漂移；TM/Glossary 另有 Rust/Go 字段镜像测试覆盖 match、trust、translated text、term history 和 source provenance。`bat-api` 已补 launcher 资源引导兼容端点、玩家-facing HTTP 控制面和鉴权调度/translation/TM/Glossary 管理接口（token 鉴权、限流、访问日志、反代 IP 适配、动态 JSON no-store、OpenAPI、管理控制白名单；`reload` / `refresh` / `restart` / `sync` / `verify` / `repair` / `catalog-refresh`、`schedule.*`、`task.*` 查询/取消、`daemon.logs`、`parse.*` 查询、`translation.tasks` / `translation.handoff` 查询、`translation.task.update`、`translation.worker.run`、`translation.proofread`、`translation.memory.summary/query/confirm`、`translation.glossary.*`、`localized.publish` 和 `localized.rollback` 可经 dashboard/API 转发），响应只来自已发布 snapshot/RPC，不提供官方账号登录、游戏网关协议或完整 package update manifest。

生产要求：

1. 使用独立输出目录，例如 `/var/lib/bluearchive-toolkit/official`。
2. 不要指向已有游戏客户端目录。
3. 不要指向 `/home/wanye/D/BlueArchive` 这类开发或人工维护资源目录。
4. `--auto-discover` 可以下载官方 metadata，并按官方 manifest 临时获取 `resources.assets` 以解析 `GameMainConfig`；旧 ZIP manifest 才会下载临时 game zip。该流程不会安装或启动官方 launcher。
5. 推荐生产形态是 systemd 直接托管前台 `bat --watch`，unit 模板位于 `deployments/systemd/bluearchive-toolkit-official-sync.service`，稳定 binary 路径为 `/opt/bluearchive-toolkit/bin/bat`，资源发布根目录为 `/var/lib/bluearchive-toolkit/official`，生产读取方读取 `/var/lib/bluearchive-toolkit/official/current`，日志通过 `journalctl -u bluearchive-toolkit-official-sync.service` 查看；不使用 systemd 时也可用 `bat --daemon` 自托管，daemon 状态、`bat-daemon.log` 和 `bat-events.jsonl` 建议放在 `/var/lib/bluearchive-toolkit/daemon-state`。定时检查逻辑已经在 Rust 内部，正常检查默认 1 小时，失败重试默认 60 秒，每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会强制执行一次自动刷新。

详细运行说明见 `docs/guides/deployment.md` 和 `docs/guides/official-resource-test-pull.md`。

---

## 6. 当前开发基础与后续工作

Issue 状态不作为本地实现状态的权威来源；本次复核未把远端 Issue 列表作为已验证事实。
当前实现以源码、测试、稳定契约和本文件的模块状态为准。

当前非阻塞验证跟踪：

- 使用 `make official-smoke` 执行真实官方网络长期运行测试，并将报告留在隔离目录。

后续工程顺序：

1. 继续复杂 AssetBundle：真实样本、复杂字段解析和发布级重打包。
2. 继续通用 Patch：manifest 驱动、双 release 查询和清理策略。
3. 继续资源查询和翻译基础设施：更丰富的查询和 Provider
   扩展体系。
4. 在资源和翻译契约稳定后推进完整 Web 协作后台和完整游戏业务 API。

---

- **当前总体完成度**：不固定写单一百分比，以各模块状态、源码、测试和契约为准。
- **当前基线状态**：Rust `bat` 同步闭环可用；Go `bat-api` 资源 bootstrap/分发 MVP、
  HTTP 控制面、launcher 资源引导兼容、RPC 周期刷新/诊断、readiness、内嵌 dashboard
  和 `backendrpc` 可用；CAS 用户级导入、TextUnit 明细索引/查询、增量离线队列、
  通用 Binary/JSON/Text Patch 基础和受支持 localized patch 发布/rollback 可用；
  完整 AssetBundle 重打包、完整 Web 协作后台、模糊 TM 匹配和通用 manifest 发布未完成。
- **下一工程里程碑**：复杂 AssetBundle 解析和重打包、通用 manifest Patch
  构建，以及真实官方资源长期运行验证。