BlueArchiveToolkit/CURRENT_STATUS.md

BlueArchiveToolkit 当前工作区状态

• 更新时间：2026-08-31
• 状态来源：本地工作区盘点、代码验证和最新提交
• 状态分支：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 序号计算百分比。

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 逐文件校验/补下载；后台状态目录包含 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 首次启动会在二进制所在目录释放 .env 配置模板（0600），之后每次启动自动加载（不覆盖已存在的环境变量），支持 BAT_OUTPUT/BAT_LOCALIZED_OUTPUT/BAT_IMPORT_REPOSITORY/BAT_IMPORT_CAS_ROOT/BAT_IMPORT_RESOURCE_DB/BAT_STATE_DIR/BAT_AUTO_DISCOVER/BAT_WATCH/BAT_DAEMON/BAT_PROXY 和 BAT_TRANSLATION_* 等键，实现编辑 .env 后无参启动；优先级为命令行参数 > 进程环境变量 > .env > 内置默认值，BAT_SKIP_ENV_FILE=1 可整体禁用；Redis 键为预留。daemon 任务历史持久化在 <state-dir>/bat-tasks.json（版本化、0600 原子写），重启后任务经 task.* 仍可查，中断任务标记 task_interrupted（BAT-ERR-700005）。

15. issue 43 已补齐 Rust bat 的 res / parse / i18n 工作流入口：支持资源拉取、解析刷新、可再生解析缓存清理、离线翻译工作台、人工文本查看/修改/清空、工作台发布前校验、有限 TextAsset 汉化发布、人工校对状态标记、既有 patch 能力的批量重打包、单次/限定次数/周期执行和版本化 schedule CRUD。issue 44 已接入 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 不维护第二套状态。issue 46 已提供 bat-api 内嵌 dashboard MVP，静态资产由 Go embed 暴露在 /admin/dashboard/，页面直接调用已有鉴权接口控制资源、调度、翻译、任务、日志、parse TextUnit 查询和 localized 发布/回滚。该例外只编排已有解析和 patch 能力，不扩大解析器覆盖；完整 AssetBundle 重打包和完整 Web 协作后台仍是后续工作。G-008（产品级 Go 同步 CLI）已决策关闭。真实官方网络全量拉取 smoke 已固化（G-018 已关闭）；真实大文件与运行报告默认在 /tmp 隔离目录，不纳入 Git。Go 细节见 docs/reports/GO_STATUS.md。

当前翻译交接还包括 translation-tasks.sqlite 和版本化 translation-handoff.json； translation.tasks 查询单项 worker 状态，translation.handoff 查询完整 job/unit/provider run 状态。当前下载实现使用默认 8 个独立 worker，完成后动态领取 任务，最终资源报告按 pull plan 顺序输出。

---

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

待完成：

• 领域服务模块仍为空。
• Glossary、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。

待完成：

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

bat-assetbundle

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

冻结说明：自 2026-07-30 起，解析模块进入维护冻结。冻结期只允许修复编译、测试、clippy、崩溃、错误诊断、真实运行回归和文档不一致；不新增 TypeTree 语义类型、不扩大 UnityFS / AssetBundle / Addressables 解析覆盖、不开放新的写入型解析 RPC/CLI，也不以合成 fixture 宣称新增解析能力。冻结细则见 docs/reports/PARSER_FREEZE.md。

当前已有：

• 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 --json 进程边界；未来稳定 SDK 也优先于 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（issue #46）；完整协作后台仍未完成

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

---

4. 已验证结果

近期 Rust 侧复核已运行并通过：

cargo fmt --check
cargo test --offline --workspace --quiet
cargo clippy --offline --workspace --all-targets -- -D warnings
cargo test --offline -p bat-patch --quiet
cargo test --offline -p bat-assetbundle --quiet
cargo test --offline -p bat-infrastructure official_parse --quiet
cargo test --offline -p bat-infrastructure dispatch_parse --quiet
cargo test --offline -p bat-infrastructure localized_patch --quiet

本次 bat-api 侧复核已运行并通过：

env GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache make test-go-api
env GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache make build-go-api
env GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache go vet ./internal/api/... ./internal/backendrpc/... ./cmd/bat-api/...
make check-docs

未执行 / 后置：

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

---

5. 当前生产运行边界

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

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 contract fixture，Go mirror 测试会防止字段名、null 语义和 game_main_config_bootstrap 再次漂移。bat-api 已补 launcher 资源引导兼容端点、玩家-facing HTTP 控制面和鉴权调度/translation 管理接口（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、localized.publish 和 localized.rollback 可经 dashboard 转发），响应只来自已发布 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. 当前阻塞项

GitHub issue 状态：#1 已关闭；#17 的历史决定不代表当前下载实现，现行默认并发为 8，范围 1..=256，每个独立 worker 完成后立即领取下一个任务，进度按完成事件即时统计并保持 report 计划顺序；子 issue #20–#23 均已关闭。其他 open issue 的实时标签以 GitHub 为准。

下一阶段必须优先完成：

1. Issue #1（P0，主体已实现）：bat.sock Unix socket JSON-RPC 已扩展为面向 Go 服务层的 Rust Resource Backend API。统一 envelope（ok、status、error、data、request_id）与 BAT-ERR 错误码模型已落地；daemon.*（status/logs/stop/restart/reload/refresh/doctor）、resource.*（state/sync/verify/repair/manifest/list/index）、schedule.*（list/add/update/remove/run）、parse.*（status/text_units/errors）、translation.*（tasks/handoff/task.update/proofread/worker.run）、localized.*（status/publish/rollback）、catalog.*（status/refresh/diff/versions）、task.*（status/list/cancel/logs）、文件级 patch.apply 与 unityfs.patch_text_asset / unityfs.patch_string_field / unityfs.patch_field 已实现，长任务返回 task_id 可轮询（任务执行器单 worker FIFO，与 watch 循环互斥；任务历史持久化于 <state-dir>/bat-tasks.json，daemon 重启后仍可查，中断任务标记 task_interrupted）；错误码已接入下载、launcher/metadata、server-info/marker 与配置校验路径。剩余：通用 manifest 驱动发布、复杂 unityfs.* 语义编辑、task.create（按设计由语义方法创建）、daemon.clean-stable（由 CLI 侧按进程生命周期显式执行，live RPC 内不做在线清理）、Redis 任务后端（.env 已预留配置键，接入时机另议）。Go 层通过 RPC 调用 Rust backend，不走 FFI（FFI 降级说明见 docs/architecture/official-resource-backend.md §7）。
2. Go 侧：进度见 docs/reports/GO_STATUS.md。G-008 已关闭；bat-api 资源 bootstrap/分发 MVP 已落地，已含 /v1/bootstrap、/v1/launcher/bootstrap、launcher 资源 metadata 兼容、HTTP 鉴权/限流/日志/反代适配、动态 JSON no-store、OpenAPI、管理控制白名单、task/log/parse/translation admin 查询控制、内嵌 dashboard、CDN Range/缓存头、RPC 周期刷新和 USERGUIDE 基础章节；仓库内 Rust/Go snapshot contract fixture 与同机 live smoke 已落地。失效 resource_root 或 manifest 不完整时会清空旧索引并使 /readyz 返回 503；编码 dot-segment 会在路由规范化前拒绝。refresh mtime/size 增量缓存和可选持久化另议。
3. 文本提取 / 翻译队列 / Patch 输入：official-textunit-index.json、official-textunit-tasks.json 与 crowdin-textunit-queue.json 已生成；TextUnit 明细、解析错误和离线翻译任务状态/失败原因已可查询，translation.tasks / translation.handoff 已提供 Go typed helper 和 bat-api dashboard 查询入口，translation.task.update 已提供 Rust CLI、Go typed helper 和 bat-api dashboard 状态回写入口，且支持人工校对从当前 TextUnit 索引提交 translation_results；translation.worker.run 已提供 mock/Crowdin provider worker、lease、重试和 TextUnit 译文结果落库，translation.proofread 已提供人工校对状态标记入口。受支持 TextAsset、TypeTree string field 和 managed-reference string field 已可从 workbench/worker 结果生成 localized patch，在独立 staging 校验后发布并显式 rollback，相关 status/publish/rollback RPC 与 bat-api 控制入口已暴露。剩余为翻译记忆、通用 manifest 发布和复杂重打包。
4. Issue #3（已完成当前目标）：AssetBundle UnityFS 基础解析校验已覆盖 header、block、directory、LZ4/LZMA、alignment、总大小、计数、路径安全、重复 directory、边界和隔离 UnityPy 真实样本；复杂对象解析与发布级重打包继续跟踪 G-005。
5. Issue #2（已完成当前目标）：Addressables JSON/compact catalog 已提取 bundle provider、name、hash/size/CRC、资源类型和依赖关系，并贯通 ResourceEntry、SQLite 与 resource.index 输出；独立二进制格式仍明确拒绝。
6. 通用 Binary/JSON/Text Patch 基础已落地；受支持 localized patch 发布/rollback 已具备回归测试，复杂 AssetBundle 重打包、通用 manifest 发布和真实翻译记忆仍后置。

非阻塞跟踪项：官方同步长期运行测试正在进行，运行报告将在后续提供。

---

7. 下一步建议

立即任务：

1. Issue #1 收尾：协议基础设施、最小方法集、catalog.*、parse.*、localized.*、task.*、resource.repair、daemon.restart、文件级 patch.apply / unityfs.patch_text_asset / unityfs.patch_string_field / unityfs.patch_field、任务持久化、错误码模型与文档均已完成；剩余通用 manifest 发布、复杂 unityfs.* 语义编辑以及 task.create、daemon.clean-stable 的设计边界确认。
2. 真实官方网络全量下载长期运行报告（make official-smoke）；issue #19 的同机 live 联调已完成。
3. 跟进官方同步长期运行测试报告。
4. AssetBundle / Addressables（issue #3 / #2）；CAS 用户级导入（G-011）。

---

• 当前总体完成度：不再固定写单一百分比，以各模块状态、GO_STATUS.md 和 issue 为准。
• 当前基线状态：Rust bat 同步闭环可用；Go bat-api 资源 bootstrap/分发 MVP + 玩家-facing HTTP 控制面 + launcher 资源引导兼容 + RPC 周期刷新/诊断 + readiness + 内嵌 dashboard + backendrpc 可用；CAS 用户级导入、TextUnit 明细索引/查询、增量 Crowdin 离线队列、通用 Binary/JSON/Text Patch 基础和受支持 localized patch 发布/rollback 可用；完整 AssetBundle 重打包、完整 Web 协作后台与通用 manifest 发布未完成。
• 下一工程里程碑：翻译记忆、通用 manifest Patch 构建、复杂 AssetBundle 解析和重打包；bat-api 同机 live 联调已完成。