feat(assetbundle): 完善官方资源解析与双目录发布

docs/architecture/assetbundle.md

@@ -0,0 +1,199 @@
+# 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 的核心发布缺口。

docs/architecture/official-resource-backend.md

@@ -6,6 +6,12 @@
 
 这个后端只处理 **日服官方资源**，只接受官方 `.jp/.com` 域名下的资源链路。
 
+**Release 布局、URL→磁盘映射、seed 模板与 bat-api 分发 path 的冻结契约**见：
+
+- `docs/architecture/resource-release-layout.md`
+
+---
+
 明确排除：
 
 - `bluearchive.cafe`
@@ -207,8 +213,10 @@
 10. 下载先写入 `<output>/.staging/<id>`；若已有 active release，会先 seed staging 以复用已验证文件；若 version-state 中存在同一版本的失败 staging，则优先复用该 staging 并跳过 active seed，避免旧 active 覆盖已下载的新文件。
 11. 下载、manifest、本地 BLAKE3、ZIP 和官方 `.hash` 校验完成后写入新的 snapshot。
 12. 将 staging rename 为 `<output>/versions/<id>`，再原子替换 `<output>/current` symlink 指向该 versioned 目录。
+13. 发布完成后刷新 active release 下的 `official-parse-cache.json`；未变化文件按 manifest 的 URL、相对路径、size 和 BLAKE3 复用旧解析结果。
+14. 官方同步报告默认给出 `localized_release_status=not_localized`，表示原版资源已发布、汉化资源未发布；后续 Patch 发布阶段完成后才切换为 `localized`，表示原版和汉化两套资源都已发布。
 
-该入口不安装、不执行官方启动器，也不读取生产外的本地客户端目录。Rust 正式 binary `bat` 支持单次运行、`--watch` 常驻模式、`--daemon` 后台模式，以及 `status`、`stop`、`restart`、`reload`、`logs`、`refresh`、`verify`、`repair`、`doctor`、`clean-stable` 管理命令。`--daemon` 会在后台状态目录下创建 `bat.sock`，使用 Unix socket JSON-RPC 作为 live control plane；`bat.pid`、`bat-status.json` 和 `bat-daemon.log` 是快照、诊断和兼容 fallback；`bat-events.jsonl` 是带轮转的结构化 JSONL 事件日志；`bat-control.lock` 串行化控制命令，并在 stale/corrupt 时由下一次控制命令或 `clean-stable` 恢复。`bat-status.json` 和 `status` 子命令包含最后成功时间、下次检查时间、最后错误摘要、当前阶段和当前下载 URL 进度。PID、status、log 和控制锁文件创建时使用私有权限，读取和写入时不跟随 symlink。`status`、`stop`、`logs`、`reload`、默认形态的 `refresh` 和默认形态的 `repair` 优先走 RPC；`reload` 会唤醒或排队 watch 循环重新自动发现并强制刷新，默认 `repair` 会通过 `resource.repair` 入队本地 manifest 审计+修复任务，`restart` 才负责重启进程或替换启动参数；显式 `--proxy` / `--no-proxy` 会作为启动参数保存并在后台重启时复用。后台 daemon 管理某个资源目录时，前台 `run/watch/refresh/repair` 不允许直接写入同一目录；默认形态 `refresh` 会通过 RPC 触发后台刷新，默认形态 `repair` 会通过 RPC 入队任务。正常情况下默认每 1 小时执行一次检查；每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会中断普通 sleep 并强制执行一次自动刷新，该轮注入 `force=true`。远端和本地一致时静默等待下次检查，不一致时自动下载或 repair。下载、发现或校验失败时不等待完整正常周期，默认 60 秒后重试；如果固定时间强制刷新失败，会保留 pending force 并按失败重试周期继续重试，可用 `--error-retry` 或 `--error-retry-seconds` 调整。默认资源输出目录是 `./bat-resources`，默认后台状态目录是 `/tmp/bat-pid`，二者通过 `--output` 和 `--state-dir` 分别配置。单次运行仍保留为核心幂等路径，systemd service、容器或 Go 进程可以只负责守护该常驻进程；cron/systemd timer 调单次模式只是可选集成方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。
+该入口不安装、不执行官方启动器，也不读取生产外的本地客户端目录。Rust 正式 binary `bat` 支持单次运行、`--watch` 常驻模式、`--daemon` 后台模式，以及 `status`、`stop`、`restart`、`reload`、`logs`、`refresh`、`verify`、`repair`、`doctor`、`clean-stable` 管理命令。`--daemon` 会在后台状态目录下创建 `bat.sock`，使用 Unix socket JSON-RPC 作为 live control plane；`bat.pid`、`bat-status.json` 和 `bat-daemon.log` 是快照、诊断和兼容 fallback；`bat-events.jsonl` 是带轮转的结构化 JSONL 事件日志；`bat-control.lock` 串行化控制命令，并在 stale/corrupt 时由下一次控制命令或 `clean-stable` 恢复。`bat-status.json` 和 `status` 子命令包含最后成功时间、下次检查时间、最后错误摘要、当前阶段和当前下载 URL 进度。PID、status、log 和控制锁文件创建时使用私有权限，读取和写入时不跟随 symlink。`status`、`stop`、`logs`、`reload`、默认形态的 `refresh` 和默认形态的 `repair` 优先走 RPC；`reload` 会唤醒或排队 watch 循环重新自动发现并强制刷新，默认 `repair` 会通过 `resource.repair` 入队本地 manifest 审计+修复任务，`restart` 才负责重启进程或替换启动参数；显式 `--proxy` / `--no-proxy` 会作为启动参数保存并在后台重启时复用。后台 daemon 管理某个资源目录时，前台 `run/watch/refresh/repair` 不允许直接写入同一目录；默认形态 `refresh` 会通过 RPC 触发后台刷新，默认形态 `repair` 会通过 RPC 入队任务。正常情况下默认每 1 小时执行一次检查；每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会中断普通 sleep 并强制执行一次自动刷新，该轮注入 `force=true`。远端和本地一致时静默等待下次检查，不一致时自动下载或 repair。下载、发现或校验失败时不等待完整正常周期，默认 60 秒后重试；如果固定时间强制刷新失败，会保留 pending force 并按失败重试周期继续重试，可用 `--error-retry` 或 `--error-retry-seconds` 调整。默认官方原版资源输出目录是 `./bat-resources`，默认汉化产物目录是 `./bat-localized`，默认后台状态目录是 `/tmp/bat-pid`，三者分别通过 `--output`、`--localized-output` 和 `--state-dir` 配置；官方目录和汉化目录不能相同或互相嵌套。单次运行仍保留为核心幂等路径，systemd service、容器或 Go 进程可以只负责守护该常驻进程；cron/systemd timer 调单次模式只是可选集成方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。
 
 对应实现主要在：
 
@@ -304,14 +312,22 @@ JSON-RPC 2.0 服务，是面向上层服务（Go 层）的**主要跨语言边
 
 ### 7.2 Go 层职责边界
 
-- Go 层负责：BlueArchive 客户端请求处理、HTTP API、鉴权、内容分发，
-  以及通过 `internal/backendrpc` 作为 RPC client 调用本机 daemon
-  （连接 `bat.sock`，每行一个 JSON-RPC 请求/响应）。当前 Go 产品入口
-  尚未完成，`cmd/bat` 仍是试验骨架。
-- Rust daemon 负责：官方资源自动拉取与校验、catalog 更新检查、
+- Go 层负责：资源内容分发（`cmd/bat-api`）、HTTP API 进程配置、以及通过
+  `internal/backendrpc` 作为 RPC client 调用本机 daemon（连接 `bat.sock`，
+  每行一个 JSON-RPC 请求/响应）。`cmd/bat` 仍是试验骨架，不是产品级用户 CLI。
+- **`bat-api`（资源分发，issue #19）**：
+  - 只读提供 Rust `bat` 已发布 release 中的资源字节（官方 CDN host/path 形态）。
+  - 版本/清单发现优先走 RPC：先 `daemon.status`，再 `daemon.doctor`，再
+    `catalog.status` / `resource.manifest`（可用 `--socket` 指定 socket 文件）。
+  - 支持 `.env` / 环境变量配置监听端口、public base URL、RPC socket，并预留
+    database/redis 键供后续 API 持久化；**不**负责资源自动拉取。
+  - 可选改写 server-info 中的 `AddressablesCatalogUrlRoot` 指向自身；不伪装
+    完整游戏业务 API，launcher 全链非本服务关闭条件。
+- Rust `bat` / daemon 负责：官方资源自动发现与拉取、校验、catalog 更新检查、
   版本状态与发布、任务队列/日志/错误/进度管理等长期状态型工作。
-- Go 层**不**直接嵌入 Rust FFI，不直接读写 daemon 的状态文件与资源
-  目录内部结构；跨语言交互只经 RPC 契约。
+- Go 层**不**直接嵌入 Rust FFI，不直接读写 daemon 的状态文件；跨语言控制面
+  只经 RPC 契约。文件字节从 RPC 给出的 `resource_root`（或显式
+  `--resource-root`）读取，与 daemon 同机或共享文件系统部署。
 
 ### 7.3 FFI 的定位（降级说明）
 

docs/architecture/resource-release-layout.md

@@ -0,0 +1,311 @@
+# 官方资源 Release 布局与资源侧契约
+
+- **更新时间**：2026-07-24
+- **用途**：冻结日服官方资源在本地发布根上的布局、URL 映射、seed 规则，以及 `bat-api` 分发 path 的 1:1 对应关系。
+- **范围**：资源发现 / 清单 / 落盘 / 只读分发（**不是**完整游戏业务 API）。
+- **权威代码**：
+  - URL / 平台 / seed：`adapters/src/official/yostar_jp.rs`
+  - inventory 抽取：`adapters/src/official/inventory.rs`
+  - 落盘与 manifest：`infrastructure/src/official_download.rs`（`destination_for_url`）
+  - 发布布局：`infrastructure/src/official_update.rs`
+  - 分发：`cmd/bat-api` + `internal/api`（见 `docs/reports/GO_STATUS.md`）
+
+---
+
+## 1. 产品边界（资源侧）
+
+| 角色 | 组件 | 职责 |
+|---|---|---|
+| 同步 / 运维（近乎全自动） | Rust `bat` | auto-discover、拉取、校验、发布、watch/daemon、RPC 后端 |
+| 资源只读分发 | Go `bat-api` | 按官方 CDN path 提供已发布字节；经 `bat.sock` 发现版本 |
+| 试验 CLI | Go `cmd/bat` → `bin/bat-go` | 非产品；禁止与 Rust `bat` 重名 |
+
+**禁止**：把已安装客户端目录或 `/home/wanye/D/BlueArchive` 当作生产输入；真实全量样本优先服务器 release 或 `/tmp` 隔离目录。
+
+---
+
+## 2. 发布根布局（L1）
+
+```text
+<output>/                          # 官方原版资源发布根（--output / BAT_OUTPUT）
+  current -> versions/<id>         # 原子 symlink，生产读侧
+  versions/<id>/                   # 已发布 versioned release（= resource_root）
+    official-download-manifest.json
+    official-parse-cache.json       # 校验后派生解析缓存，不是汉化产物
+    official-sync-snapshot.json    # 常在 active root / current 下
+    prod-clientpatch.bluearchiveyostar.com/
+      <root_token>/
+        TableBundles/
+          TableCatalog.bytes
+          TableCatalog.hash
+          <table files...>           # e.g. ExcelDB.db, Excel.zip
+        Windows_PatchPack/
+          BundlePackingInfo.bytes
+          BundlePackingInfo.hash
+          catalog_StandaloneWindows64.zip
+          catalog_StandaloneWindows64.hash
+          FullPatch_NNN.zip
+        Android_PatchPack/
+          BundlePackingInfo.bytes
+          BundlePackingInfo.hash
+          catalog_Android.zip
+          catalog_Android.hash
+          FullPatch_NNN.zip
+        MediaResources-Windows/
+          Catalog/MediaCatalog.bytes
+          Catalog/MediaCatalog.hash
+          GameData/...
+          Prologue/...
+        MediaResources/              # Android
+          Catalog/MediaCatalog.bytes
+          Catalog/MediaCatalog.hash
+          ...
+    yostar-serverinfo.bluearchiveyostar.com/   # 若曾下载 server-info
+      <name>.json
+  .staging/<id>/                   # 未发布写侧（失败可复用）
+  official-version-state.json      # 发布根级版本状态
+  official-bootstrap-cache.json    # auto-discover 缓存
+
+<localized-output>/                # 汉化产物发布根（--localized-output / BAT_LOCALIZED_OUTPUT）
+  current -> versions/<id>         # 已汉化后才切换；未汉化状态不发布
+  versions/<id>/                   # 与官方相对路径一致的汉化资源
+  localized-version-state.json     # 预留：后续 Patch 发布阶段维护，官方同步阶段不写入
+```
+
+官方资源发布和汉化发布是两个独立状态：
+
+- `not_localized`：官方原版资源已经完成下载、校验和发布，汉化资源尚未发布；这是官方同步完成后的默认状态。
+- `localized`：同一官方版本的原版资源和汉化资源都已发布，生产侧可以同时提供两套资源。
+
+### 2.1 读侧 vs 写侧
+
+| 阶段 | 根目录 |
+|---|---|
+| 下载写入 | `<output>/.staging/<id>` |
+| 发布完成 | rename 到 `versions/<id>`，再切换 `current` |
+| 生产读取 / bat-api | `current` 解析后的 versioned 目录，或 RPC 给出的 `version.resource_root` |
+
+---
+
+## 3. URL → 磁盘映射（核心不变量）
+
+实现：`OfficialResourcePullService::destination_for_url`。
+
+```text
+https://{host}/{path...}  →  <resource_root>/{host}/{path...}
+```
+
+规则：
+
+1. 仅 `https://`
+2. host 必须是官方 JP 资源 host（见下节）
+3. path 分段不得为 `.` / `..`
+4. **禁止** query / fragment（否则直接拒绝，避免同路径覆盖）
+5. 分段经 sanitize 后 join；结果必须在 `resource_root` 内
+
+### 3.1 官方 host
+
+| Host | 用途 |
+|---|---|
+| `prod-clientpatch.bluearchiveyostar.com` | Addressables / Table / Media / PatchPack 内容 |
+| `yostar-serverinfo.bluearchiveyostar.com` | server-info JSON |
+
+（launcher 包 CDN 属于启动器链，**不是**默认资源 release 主体。）
+
+### 3.2 bat-api 对外 path（1:1）
+
+```text
+GET {public-base-url}/prod-clientpatch.bluearchiveyostar.com/<root_token>/...
+    ≡ 磁盘 <resource_root>/prod-clientpatch.bluearchiveyostar.com/<root_token>/...
+```
+
+默认仅服务 **download manifest 索引内且 Present + size 匹配** 的文件。
+
+---
+
+## 4. `official-download-manifest.json`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `version` | u32 | 当前为 `1` |
+| `entries` | map URL → entry | 按完整官方 URL 为键（有序 BTreeMap） |
+
+每条 entry：
+
+| 字段 | 说明 |
+|---|---|
+| `url` | 官方 https URL |
+| `destination` | 相对 resource_root 的路径（`host/path...`） |
+| `bytes` | 文件大小 |
+| `blake3` | 本地 BLAKE3 hex |
+
+**权威清单**：拉取闭环写入的 manifest；`bat-api` / RPC `resource.manifest` 以此为应有集合，再以磁盘校验 Present。
+
+---
+
+## 5. 发现与 seed URL 规则（L2）
+
+常量根：
+
+- server-info：`https://yostar-serverinfo.bluearchiveyostar.com`
+- client-patch：`https://prod-clientpatch.bluearchiveyostar.com`
+
+`AddressablesCatalogUrlRoot` 形如：
+
+```text
+https://prod-clientpatch.bluearchiveyostar.com/<root_token>
+```
+
+默认平台：`Windows` + `Android`。
+
+### 5.1 平台目录名
+
+| 平台 | Patch 目录 | Media 目录 | Addressables catalog zip |
+|---|---|---|---|
+| Windows | `Windows_PatchPack` | `MediaResources-Windows` | `catalog_StandaloneWindows64.zip` |
+| Android | `Android_PatchPack` | `MediaResources` | `catalog_Android.zip` |
+
+### 5.2 Seed 端点模板
+
+共享（非平台）：
+
+```text
+{CLIENT_PATCH}/{token}/TableBundles/TableCatalog.bytes
+{CLIENT_PATCH}/{token}/TableBundles/TableCatalog.hash
+```
+
+每平台：
+
+```text
+{CLIENT_PATCH}/{token}/{PatchDir}/BundlePackingInfo.bytes
+{CLIENT_PATCH}/{token}/{PatchDir}/BundlePackingInfo.hash
+{CLIENT_PATCH}/{token}/{PatchDir}/{catalog_zip}
+{CLIENT_PATCH}/{token}/{PatchDir}/{catalog_base}.hash
+{CLIENT_PATCH}/{token}/{MediaDir}/Catalog/MediaCatalog.bytes
+{CLIENT_PATCH}/{token}/{MediaDir}/Catalog/MediaCatalog.hash
+```
+
+### 5.3 Content URL 模板
+
+| 类型 | 模板 |
+|---|---|
+| Table 文件 | `{CLIENT_PATCH}/{token}/TableBundles/{Name}` |
+| Patch pack | `{CLIENT_PATCH}/{token}/{PatchDir}/{FullPatch_NNN.zip}` |
+| Media 文件 | `{CLIENT_PATCH}/{token}/{MediaDir}/{relative_path}` |
+
+`relative_path` 示例：`GameData/Audio/VOC_JP/JP_Airi.zip`、`Prologue/Scenario/Event/10000_Title_Sound.ogg`。
+
+### 5.4 校验分层
+
+| 对象 | 算法 / 规则 |
+|---|---|
+| seed `.bytes` + `.hash` | 官方 `.hash` 为 **xxHash32(seed=0)** 的十进制文本；强校验 |
+| 一般已下载文件 | 本地 manifest **size + BLAKE3** |
+| `.zip` | 另加 ZIP central/local 结构校验 |
+| `catalog_*.hash` | Addressables/SBP **Hash128 文本标记**，**不是** seed 的 xxHash32 规则 |
+
+---
+
+## 6. Inventory 抽取规则（L3，当前实现）
+
+实现：`adapters/src/official/inventory.rs`（**可打印串启发式**，非完整 schema 反序列化）。
+
+| Catalog | 抽取逻辑 | 风险 |
+|---|---|---|
+| `BundlePackingInfo.bytes` | 可打印串中扩展名为 `zip` 且匹配 `FullPatch_NNN.zip`（总长 17，中间 3 位数字） | 漏抽非 FullPatch 包名（当前有意只 FullPatch） |
+| `TableCatalog.bytes` | 可打印串中 `.db`/`.zip` 文件名；**出现次数 ≥ 2** 才收录 | 依赖「双份列表」启发式；形态变化会漏/多 |
+| `MediaCatalog.bytes` | 可打印串中相对路径，扩展名 zip/mp4/png/jpg/jpeg/ogg/wav | 路径须 `is_plausible_relative_path` |
+
+**R2 待真机核对**：用服务器全量 seed 字节跑抽取，与 manifest 中 content URL 集合 diff；有未解释差异再改 inventory + fixture。
+
+仓库内已有：`adapters/tests/fixtures`、`infrastructure/tests/fixtures/official_regression`；**不能替代**全量 release 实勘。
+
+---
+
+## 7. 客户端资源请求假设（R3，服务 bat-api）
+
+| 面 | 假设（当前工程） | bat-api 行为 |
+|---|---|---|
+| client-patch 内容 | GET 官方 path；无业务鉴权头（资源 CDN） | `GET/HEAD /prod-clientpatch.../...` 原样字节 |
+| server-info | GET JSON；字段 PascalCase（`ConnectionGroups` 等） | 可选加载并**只改** `AddressablesCatalogUrlRoot` 指向 `{public-base}/prod-clientpatch.../{token}` |
+| seed `.hash` | 纯文本十进制（可含空白） | 原样分发 |
+| Range / 断点 | 官方客户端下载器用 Range；bat 用 curl `.part` | **本轮 bat-api 可不实现 Range**；记入后续 |
+| 业务 ApiUrl/Gateway | 游戏协议 | **不改写、不仿造** |
+
+Addressables 改写后客户端拼接：
+
+```text
+{rewritten_root}/TableBundles/TableCatalog.bytes
+≡ {public-base}/prod-clientpatch.../{token}/TableBundles/TableCatalog.bytes
+```
+
+与磁盘映射一致。
+
+---
+
+## 8. RPC 与分发发现顺序
+
+`bat-api`（及任何 Go 服务层）发现当前 release：
+
+1. `daemon.status`
+2. `daemon.doctor`
+3. `catalog.status`（`version.resource_root`、`addressables_root`、app/bundle）
+4. `resource.manifest` 分页（url / destination / bytes / blake3）
+5. 在 `resource_root` 上 Lstat 校验 Present / size
+
+**不读** `bat-status.json` / `bat-tasks.json` 作为常规路径。
+
+配置：`--socket` / `BAT_API_SOCKET`；应急 `--resource-root`。见 `cmd/bat-api/.env.example`。
+
+---
+
+## 9. issue #2 / #3 样本索引（R4/R5 预置）
+
+在服务器 release 上优先采集到 `/tmp` 隔离目录（**不入库大文件**）：
+
+| 用途 | 建议路径模式 |
+|---|---|
+| Addressables（#2） | `{PatchDir}/catalog_*.zip` 解压后的 JSON/bin + 旁路 `.hash` |
+| UnityFS（#3） | `FullPatch_*.zip` 内抽样 `.bundle`，或已解包 bundle |
+| seed 加固（R2） | 各平台 `TableCatalog` / `BundlePackingInfo` / `MediaCatalog` 的 `.bytes`+`.hash` |
+
+字段目标（#2，已有 `m_Crc` 部分）：继续扩大 hash/size/CRC/依赖等可校验字段覆盖。
+结构目标（#3）：header / block / directory / metadata / object table 引擎级解析。
+
+---
+
+## 10. 服务器实勘清单（R1，等 SSH）
+
+连接信息到位后只读执行：
+
+1. `readlink current` → version id
+2. 顶层是否仅有官方 host 目录 + manifest/snapshot
+3. manifest 条目数 vs 磁盘抽样 size
+4. RPC 四步（status → doctor → catalog.status → manifest 首页）
+5. 将结论写入 `docs/reports/resource-server-survey-YYYYMMDD.md`（无凭据）
+
+所需：
+
+```text
+SSH: user@host -p PORT
+资源目录: .../official
+bat.sock 或 state-dir: ...
+```
+
+---
+
+## 11. 相关文档
+
+- `docs/reports/GO_STATUS.md` — Go 边界与进度
+- `docs/architecture/official-resource-backend.md` — 拉取后端总览
+- `docs/reference/rpc-backend-api.md` — RPC 契约
+- `docs/guides/official-resource-test-pull.md` — 用户向运行说明
+- `docs/reports/CURRENT_GAPS.md` — G-009 / #2 / #3
+
+---
+
+## 12. 变更纪律
+
+1. 改 URL 模板或落盘规则 → **必须**同步本文 + 相关单测。
+2. 改 inventory 启发式 → 说明覆盖的真实风险并补 fixture。
+3. 真机实勘若发现与本文冲突 → **以真机为准** 修代码与本文，禁止静默分叉。

docs/guides/deployment.md

@@ -227,10 +227,11 @@ systemctl status bluearchive-toolkit-official-sync.service
 journalctl -u bluearchive-toolkit-official-sync.service -f
 sudo -u bat /opt/bluearchive-toolkit/bin/bat doctor \
   --output /var/lib/bluearchive-toolkit/official \
+  --localized-output /var/lib/bluearchive-toolkit/localized \
   --state-dir /run/bluearchive-toolkit
 ```
 
-`--watch` 是 Rust 内部持久检查模式，正常情况下默认每 1 小时执行一次检查，并且每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会强制执行一次自动刷新。固定时间刷新会中断普通 interval 的 sleep，该轮注入 `force=true`；如果失败，会按失败重试周期继续重试。远端和本地一致时默认静默；有远端变化或本地文件损坏时自动下载或 repair，并输出人类可读摘要。下载、发现或校验失败时默认 60 秒后重试，可显式加 `BAT_ERROR_RETRY=60s` 或调整 service `ExecStart`。默认平台是 `Windows,Android`，无需显式传 `--platforms`；需要覆盖时用 systemd drop-in 重写 `ExecStart`。默认资源目录是 `./bat-resources`，生产 service 显式使用 `/var/lib/bluearchive-toolkit/official`。生产读取方应读取 `/var/lib/bluearchive-toolkit/official/current`；同步中的文件只会进入 `.staging/<id>`，校验完成后才发布为 `versions/<id>` 并切换 `current`。
+`--watch` 是 Rust 内部持久检查模式，正常情况下默认每 1 小时执行一次检查，并且每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会强制执行一次自动刷新。固定时间刷新会中断普通 interval 的 sleep，该轮注入 `force=true`；如果失败，会按失败重试周期继续重试。远端和本地一致时默认静默；有远端变化或本地文件损坏时自动下载或 repair，并输出人类可读摘要。下载、发现或校验失败时默认 60 秒后重试，可显式加 `BAT_ERROR_RETRY=60s` 或调整 service `ExecStart`。默认平台是 `Windows,Android`，无需显式传 `--platforms`；需要覆盖时用 systemd drop-in 重写 `ExecStart`。默认官方原版资源目录是 `./bat-resources`，默认汉化产物目录是 `./bat-localized`；生产 service 显式使用 `/var/lib/bluearchive-toolkit/official` 和 `/var/lib/bluearchive-toolkit/localized`，两者不能相同或互相嵌套。生产读取方应读取 `/var/lib/bluearchive-toolkit/official/current`；同步中的原版文件只会进入 `.staging/<id>`，校验完成后才发布为 `versions/<id>` 并切换 `current`。官方同步报告 `localized_release_status=not_localized` 表示汉化资源尚未发布；后续 Patch 发布才切换 `/var/lib/bluearchive-toolkit/localized/current`。
 
 ### 可选模式：CLI 自托管 `--daemon`
 
@@ -240,6 +241,7 @@ sudo -u bat /opt/bluearchive-toolkit/bin/bat doctor \
 sudo -u bat /opt/bluearchive-toolkit/bin/bat \
   --auto-discover \
   --output /var/lib/bluearchive-toolkit/official \
+  --localized-output /var/lib/bluearchive-toolkit/localized \
   --state-dir /var/lib/bluearchive-toolkit/daemon-state \
   --daemon
 
@@ -262,9 +264,11 @@ systemd 模式：
 - 当前可读 release：`/var/lib/bluearchive-toolkit/official/current`
 - 资源状态：`/var/lib/bluearchive-toolkit/official/current/official-sync-snapshot.json`
 - 下载 manifest：`/var/lib/bluearchive-toolkit/official/current/official-download-manifest.json`
+- 解析缓存：`/var/lib/bluearchive-toolkit/official/current/official-parse-cache.json`
 - 历史 release：`/var/lib/bluearchive-toolkit/official/versions/<id>`
 - 同步 staging：`/var/lib/bluearchive-toolkit/official/.staging/<id>`
 - 资源写锁：`/var/lib/bluearchive-toolkit/official/.official-sync.lock`
+- 汉化 release（Patch 发布后）：`/var/lib/bluearchive-toolkit/localized/current`
 - 运行期目录：`/run/bluearchive-toolkit/`
 
 standalone `--daemon` 模式：
@@ -279,10 +283,10 @@ standalone `--daemon` 模式：
 ### 生产维护命令
 
 ```bash
-sudo -u bat /opt/bluearchive-toolkit/bin/bat refresh --output /var/lib/bluearchive-toolkit/official
-sudo -u bat /opt/bluearchive-toolkit/bin/bat refresh --force --output /var/lib/bluearchive-toolkit/official
-sudo -u bat /opt/bluearchive-toolkit/bin/bat verify --output /var/lib/bluearchive-toolkit/official
-sudo -u bat /opt/bluearchive-toolkit/bin/bat repair --output /var/lib/bluearchive-toolkit/official
+sudo -u bat /opt/bluearchive-toolkit/bin/bat refresh --output /var/lib/bluearchive-toolkit/official --localized-output /var/lib/bluearchive-toolkit/localized
+sudo -u bat /opt/bluearchive-toolkit/bin/bat refresh --force --output /var/lib/bluearchive-toolkit/official --localized-output /var/lib/bluearchive-toolkit/localized
+sudo -u bat /opt/bluearchive-toolkit/bin/bat verify --output /var/lib/bluearchive-toolkit/official --localized-output /var/lib/bluearchive-toolkit/localized
+sudo -u bat /opt/bluearchive-toolkit/bin/bat repair --output /var/lib/bluearchive-toolkit/official --localized-output /var/lib/bluearchive-toolkit/localized
 sudo -u bat /opt/bluearchive-toolkit/bin/bat doctor --output /var/lib/bluearchive-toolkit/official --state-dir /run/bluearchive-toolkit
 sudo -u bat /opt/bluearchive-toolkit/bin/bat clean-stable --output /var/lib/bluearchive-toolkit/official --state-dir /run/bluearchive-toolkit
 ```

docs/guides/development.md

@@ -141,11 +141,18 @@ git push origin feature/your-feature-name
 cargo fmt --check
 cargo test --workspace
 cargo clippy --workspace --all-targets -- -D warnings
-go test ./...
-go vet ./...
+make test-go-api
+make build-go-api
+go vet ./internal/api/... ./internal/backendrpc/... ./cmd/bat-api/...
 ```
 
-Go 产品入口尚未完成，但仓库已有 `internal/backendrpc` Rust daemon RPC client、`cmd/bat` 试验骨架与 `internal/ffi` 兼容包装。提交前应运行 `go test ./...` 和 `go vet ./...`；`internal/backendrpc` 使用 fake transport 覆盖 JSON-RPC envelope、错误和 typed helper，不能把这些测试误认为 Go 产品级 CLI/API 已完成。
+Go 边界与进度以 `docs/reports/GO_STATUS.md` 为准：
+
+- **同步/运维命令行** = Rust `bat`（近乎全自动）
+- **资源分发服务** = `cmd/bat-api`（`make build-go-api`）
+- **默认 Go 门禁** = `make test-go-api`（无 FFI）
+- 试验 CLI 产物为 `bin/bat-go`（`make build-go-cli`），**禁止**与 Rust `bat` 重名
+- 修改 FFI 时再跑 `make test-go-ffi`
 
 ### 常用聚焦命令
 
@@ -160,7 +167,7 @@ cargo clippy -p bat-core -p bat-adapters -p bat-infrastructure --all-targets --
 
 官方资源同步、下载、daemon、status、verify 或 repair 相关改动必须至少覆盖 `bat-infrastructure` 和 `bat` 二进制测试。
 
-`bat-ffi` 只是可选无状态 C ABI 兼容层。修改 FFI 导出、JSON schema、错误返回或 `internal/ffi` CGO 包装时必须运行 `cargo test -p bat-ffi -- --nocapture`；未来 Go 产品入口和生产同步默认应通过 `internal/backendrpc` 调用 daemon RPC，或在 one-shot/fallback 场景使用 Rust `bat --json` 进程边界。
+`bat-ffi` 只是可选无状态 C ABI 兼容层。修改 FFI 时必须运行 `cargo test -p bat-ffi -- --nocapture`。Go 服务层默认经 `internal/backendrpc` 调 daemon；同步任务由 Rust `bat` 执行，不由 Go 试验 CLI 承担。
 
 ### 集成测试
 
@@ -186,7 +193,7 @@ cargo run -p bat-infrastructure --bin bat -- \
   --dry-run
 ```
 
-开发环境真实下载默认写入 `./bat-resources`；如果要覆盖，必须使用 `/tmp` 或其他隔离目录，不要写入现有资源目录。
+开发环境真实官方资源下载默认写入 `./bat-resources`；汉化产物默认写入独立的 `./bat-localized`。如果要覆盖，官方原版资源使用 `--output` / `BAT_OUTPUT`，汉化产物使用 `--localized-output` / `BAT_LOCALIZED_OUTPUT`。两者都必须使用 `/tmp` 或其他隔离目录，不要写入现有资源目录，也不要把汉化输出覆盖到官方原版资源目录。
 
 生产或 CI 环境不得依赖安装官方启动器。需要启动器信息时，只能分析启动器资源、官方 manifest 或公开更新数据，并将解析结果固化为可验证流程。
 

docs/guides/official-resource-test-pull.md

@@ -45,7 +45,7 @@ target/release/bat \
   --watch
 ```
 
-默认资源输出目录是 `./bat-resources`，默认后台状态目录是 `/tmp/bat-pid`。资源输出目录是发布根目录：非 dry-run 同步先写 `<output>/.staging/<id>`，校验完成后移动到 `<output>/versions/<id>`，再原子切换 `<output>/current` symlink；生产读取方应读取 `current`。后台状态目录会保存 `bat.sock`、`bat.pid`、`bat-status.json`、`bat-daemon.log`、`bat-events.jsonl` 和短生命周期的 `bat-control.lock`；其中 `bat.sock` 是 live daemon 的 Unix socket JSON-RPC 控制通道，`bat-events.jsonl` 是带轮转的结构化 JSONL 事件日志，`bat-status.json` 保存最后成功时间、下次检查时间、最后错误摘要和当前下载进度，`bat-control.lock` 串行化 `status/stop/restart/reload/logs/refresh/repair` 等控制命令。生产资源输出目录必须是独立目录；需要覆盖时用 `--output <资源目录>`，不要使用已有游戏客户端目录、官方启动器安装目录、人工维护资源目录，或开发机上的 `/home/wanye/D/BlueArchive`。
+默认官方原版资源输出目录是 `./bat-resources`，默认汉化产物目录是 `./bat-localized`，默认后台状态目录是 `/tmp/bat-pid`。官方资源输出目录是发布根目录：非 dry-run 同步先写 `<output>/.staging/<id>`，校验完成后移动到 `<output>/versions/<id>`，再原子切换 `<output>/current` symlink；生产读取方应读取 `current`。后台状态目录会保存 `bat.sock`、`bat.pid`、`bat-status.json`、`bat-daemon.log`、`bat-events.jsonl` 和短生命周期的 `bat-control.lock`；其中 `bat.sock` 是 live daemon 的 Unix socket JSON-RPC 控制通道，`bat-events.jsonl` 是带轮转的结构化 JSONL 事件日志，`bat-status.json` 保存最后成功时间、下次检查时间、最后错误摘要和当前下载进度，`bat-control.lock` 串行化 `status/stop/restart/reload/logs/refresh/repair` 等控制命令。生产官方资源目录和汉化产物目录都必须是独立目录；需要覆盖官方目录时用 `--output <资源目录>`，需要覆盖汉化目录时用 `--localized-output <目录>` 或 `BAT_LOCALIZED_OUTPUT`，不要使用已有游戏客户端目录、官方启动器安装目录、人工维护资源目录，或开发机上的 `/home/wanye/D/BlueArchive`。
 
 同步流程会拒绝危险输出目录、路径逃逸和现有 symlink 路径组件；下载目标、`.part`、manifest、snapshot、PID、status、log 和控制锁文件不会跟随 symlink，daemon 状态类文件默认以 `0600` 权限创建。
 
@@ -210,6 +210,8 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \
 - 真实更新会输出 `downloaded_count`、`resumed_count`、`skipped_count`、`transferred_bytes`、`official_seed_hash_verified_count`。
 - 校验报告分层输出 `official_seed_hash_verified_count`、`local_manifest_verified_count`、`addressables_marker_checked_count`、`unverified_marker_count`。
 - 下载阶段复用同一套本地清单、ZIP 结构校验和 `.part` 续传逻辑；没有清单或校验不匹配的文件会重新下载。
+- 校验和发布完成后会刷新 `<output>/current/official-parse-cache.json`。解析缓存从 `official-download-manifest.json` 的全部条目出发，处理直接 UnityFS bundle 和 zip 内 UnityFS 条目；catalog、hash、媒体等非 UnityFS 文件记录为不支持，不视为同步失败。本地 URL、相对路径、size 和 BLAKE3 未变化时复用缓存并跳过重复解析。
+- 官方同步报告中的 `localized_release_status=not_localized` 表示原版资源已发布、汉化资源未发布，这是当前官方同步阶段的正常完成状态；后续 Patch 发布完成后才应切换为 `localized`，表示原版和汉化两套资源都已发布。
 
 资源同步状态文件默认分布如下：
 
@@ -217,6 +219,7 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \
 - `<output>/official-bootstrap-cache.json`：`--auto-discover` 的 `GameMainConfig` 解析缓存。launcher metadata 未变时复用缓存；metadata 变化时才通过官方 HTTP 按 manifest 下载必要 `resources.assets` 或旧版 game zip 到临时目录解析。
 - `<output>/official-version-state.json`：资源发布根目录的持久版本状态，包含当前已完成版本、正在拉取版本、上一个可用版本和失败版本。
 - `<output>/current/official-download-manifest.json`：本地下载强校验清单，记录 URL、相对路径、size 和 BLAKE3。
+- `<output>/current/official-parse-cache.json`：官方资源发布后的派生解析缓存，记录 bundle/zip 条目解析摘要和缓存复用情况；它不是汉化产物。
 - `<output>/current/official-download-quarantine.json` 或当前 staging 下同名文件：下载最终失败的 URL 诊断记录，包含失败类型、HTTP 状态、是否可重试、尝试次数和最后错误。
 
 先 dry-run：
@@ -251,7 +254,7 @@ cargo run -p bat-infrastructure --bin bat -- \
   --watch
 ```
 
-后台自动运行使用 `--daemon`。它会启动一个脱离终端的 watch 子进程，资源默认写入 `./bat-resources`，后台控制和状态默认写入 `/tmp/bat-pid`：
+后台自动运行使用 `--daemon`。它会启动一个脱离终端的 watch 子进程，官方原版资源默认写入 `./bat-resources`，汉化产物默认写入 `./bat-localized`，后台控制和状态默认写入 `/tmp/bat-pid`：
 
 ```bash
 cargo run -p bat-infrastructure --bin bat -- \
@@ -310,7 +313,7 @@ cargo run -p bat-infrastructure --bin bat -- \
 
 默认平台是 `Windows,Android`，无需显式传 `--platforms`；只有要覆盖默认平台时才传。`--interval` 是正常检查周期，默认 `1h`；watch/daemon 模式还会在每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 强制执行一次自动刷新，该轮会注入 `force=true`，并且会中断普通 interval 的 sleep。`--error-retry` 是下载、发现或校验失败后的重试周期，默认 `60s`，也可以用 `--error-retry-seconds 60`。CLI 默认启动时向 stderr 打印 `BlueArchiveToolkit` ASCII banner，并把阶段进度日志写到 stderr，包括自动发现、proxy、server-info、marker、catalog、audit、download、snapshot 和 publish 阶段；download 阶段会输出已完成计数和单文件开始/完成状态，下载执行保持顺序处理，已完成计数保持单调不倒退，audit 阶段会输出官方 `.hash`、本地 BLAKE3、需修复项和 ZIP 结构校验结果摘要。daemon 还会写 `bat-events.jsonl` 结构化日志并按大小轮转。命令结果默认以人类可读摘要写到 stdout。需要纯机器输出时加 `--json --no-progress`，需要显式开启进度日志则用 `--progress`；只想关闭横幅但保留日志时可加 `--no-banner`。错误时 stderr 输出 JSON error，watch 模式下错误 JSON 的 `next_retry_seconds` 使用失败重试周期；如果未关闭 progress，错误 JSON 前可能已有 banner 和进度日志。普通错误 exit `1`，资源目录锁冲突 exit `75`，`verify` 或 `doctor` 发现问题也返回非 0。
 
-生产可以直接运行 `--watch`，也可以用 `--daemon` 后台运行，或者用 systemd service、容器或 Go 进程守护它。cron/systemd timer 仍可调用单次模式，但不再是 Rust 自动更新的唯一方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。生产资源目录应使用独立输出目录，不要指向现有客户端或人工维护的资源目录；上层读取资源时应读取 `--output/current`，不要读取 `.staging` 或 `versions` 中未切换的目录。非 dry-run 每轮会创建 `--output/.official-sync.lock`，防止并发写同一资源目录；live daemon 还会阻止前台写命令直接修改它正在管理的同一目录。
+生产可以直接运行 `--watch`，也可以用 `--daemon` 后台运行，或者用 systemd service、容器或 Go 进程守护它。cron/systemd timer 仍可调用单次模式，但不再是 Rust 自动更新的唯一方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。生产官方资源目录应使用独立输出目录，不要指向现有客户端或人工维护的资源目录；上层读取原版资源时应读取 `--output/current`，不要读取 `.staging` 或 `versions` 中未切换的目录。汉化 Patch/导出应写入 `--localized-output`，并保留官方相对目录结构，不能写回 `--output/current`。发布状态分两档：`not_localized` 只发布原版资源、不发布汉化资源；`localized` 发布原版和汉化两套资源。非 dry-run 每轮会创建 `--output/.official-sync.lock`，防止并发写同一官方资源目录；live daemon 还会阻止前台写命令直接修改它正在管理的同一目录。
 
 需要只做探测时可以加 `--dry-run`。需要关闭本地 audit 或 repair 时可以显式使用 `--no-audit-local` 或 `--no-repair`，但生产同步默认应保持开启。
 

docs/reports/CURRENT_GAPS.md

@@ -1,6 +1,8 @@
 # 当前实现缺口清单
 
-- **更新时间**：2026-07-20
+- **更新时间**：2026-07-24
+- **Go 进度权威**：`GO_STATUS.md`
+- **资源布局 / 逆向契约**：`../architecture/resource-release-layout.md`
 - **用途**：集中跟踪当前代码中的占位实现、设计缺口和下一步验收项。
 - **权威计划**：`../../PROJECT_PLAN.md`
 
@@ -109,24 +111,40 @@
 
 ### G-005：AssetBundle 引擎解析器仍未完成
 
+状态：**部分完成**
+
 现象：
 
-- `crates/bat-assetbundle/src/parser.rs` 只有 `Parser::name`。
-- `types.rs` 只有 `AssetType::TextAsset`。
-- `adapters/src/unity/unity_2021_3.rs` 已能解析 UnityFS header、block info、directory，并校验 directory `offset+size` 不越界；这属于 adapter 层基础摘要能力，不等于 `bat-assetbundle` 引擎已完成。
-- 仍没有对象表、TypeTree、TextAsset、MonoBehaviour、ScriptableObject 或可扩展提取入口。
+- `crates/bat-assetbundle` 已接管 UnityFS 解析，提供 `UnityFsParser`、`UnityFsBundle`、header、block info、directory、压缩模式、block info at end、LZ4/LZMA block info 解压、数据 block 解压、directory 文件提取和边界诊断。
+- `crates/bat-assetbundle::serialized` 已提供 Unity serialized file header、type table、TypeTree node 元数据、object table 和 `TextAsset` bytes 提取。
+- `adapters/src/unity/unity_2021_3.rs` 已降为 Unity 版本选择薄层，复用 `bat-assetbundle`，不再维护第二套 UnityFS parser。
+- `ResourceImportService` 的 UnityFS 摘要已经能暴露解包文件数、serialized file 数、TextAsset 数量和名称。
+- 仍没有 `MonoBehaviour`、`ScriptableObject` 的 TypeTree 字段级反序列化和可编辑重打包入口。
 
 影响：
 
-- 可以对部分 UnityFS 样本做基础结构校验，但无法完成真实资源对象解析和文本提取。
-- 无法提取 TextAsset 或配置文本。
+- 可以对 UnityFS 容器做结构校验、解包 directory 文件，并提取 serialized file 中的 TextAsset 原始 bytes。
+- 对日语汉化最关键的 TextAsset 索引和 bytes 提取已有基础入口，但还不能直接解析 `MonoBehaviour`/`ScriptableObject` 自定义字段或完成修改后重打包。
 
-验收：
+当前验收证据：
 
 - `crates/bat-assetbundle` 能解析结构化测试样本和隔离真实样本。
-- 支持 UnityFS header、blocks、directory、metadata、object table。
+- 支持 UnityFS header、blocks、directory、metadata 摘要、directory 文件提取。
+- 支持 Unity serialized file object table、TypeTree node 元数据和 TextAsset 提取的合成 fixture。
 - 错误包含偏移和字段上下文。
 
+关闭前仍需：
+
+- 完成 TypeTree 字段 reader：bool、integer、float、string、bytes、array、map、PPtr 和 managed reference 诊断占位。
+- 支持 MonoBehaviour、ScriptableObject 字段级遍历，形成可扩展文本提取入口。
+- 输出可追溯文本定位：bundle path、archive entry、serialized file、path id、class id、field path。
+- 用真实资源 fixture 覆盖对象级解析、TextAsset 提取和字段级文本提取。
+- 将解析结果作为 Patch 输入；真正的重打包、Patch 生成和 `localized` 发布切换归 G-006/G-011D。
+
+解析补全路线图：
+
+- 见 `docs/architecture/assetbundle.md` 的 P2/P3/P5。
+
 ### G-006：Patch 引擎仍是占位
 
 现象：
@@ -153,8 +171,9 @@
 
 - `AddressablesCatalogDriver` 已能解析当前真实形态 JSON catalog fixture/golden。
 - 已输出 path、hash、size、resource_type、address、dependencies、metadata，并已提取 `m_Crc` 到 `crc` 字段。
+- compact catalog 解析已补充 hash/size/CRC 的非 0 回归、资源计数 metadata，以及 blob 解码失败时的明确错误；不再在 compact 字段损坏时静默退回低保真 `m_InternalIds`。
 - `bat-core` 已提供 `crc32_ieee` 和 `ResourceEntry::verify_downloaded_bytes`，SQLite `ResourceRepository` 已有 `crc` 列迁移。
-- 仍需覆盖更多官方 catalog 结构变体、二进制/压缩字段组合和更明确的失败诊断。
+- 仍需覆盖更多官方 catalog 结构变体、provider/bundle name 持久化字段，以及真实 Windows/Android catalog 样本集合。
 
 影响：
 
@@ -165,54 +184,53 @@
 - 能解析项目目标版本的真实 Catalog 样本集合。
 - 解析结果包含资源 key、provider、dependency、hash、size、path、CRC。
 - 对不支持的 catalog 结构返回明确错误，而不是静默丢字段。
+- 解析结果能反查 bundle 文件、依赖链和本地下载 manifest 条目。
+- Windows/Android 样本集合需要覆盖 JSON、compact JSON 和后续二进制 catalog 入口。
+
+解析补全路线图：
+
+- 见 `docs/architecture/assetbundle.md` 的 P1。
 
 ---
 
 ## 3. 应用层缺口
 
-### G-008：Go CLI 产品入口尚未完成
+### G-008：Go 同步/运维 CLI 产品入口
 
-状态：**未完成（此前“并入 G-009”只是短期跟踪调整，不代表能力完成）**
+状态：**已决策关闭（wontfix）**
 
-现象：
+决策（2026-07-24，见 `GO_STATUS.md`）：
 
-- 当前可用的用户同步/运维入口是 Rust `bat` binary。
-- `internal/backendrpc` 已提供 Go 到 Rust daemon 的 typed JSON-RPC client；`cmd/bat` 已存在，但仅有 `doctor`、`manifest inspect`、`sync plan` 试验能力；`doctor` 只输出固定 `ok`，`manifest`/`sync` 依赖可选 CGO/FFI helper。
-- Go 侧尚未实现通过 Rust `bat --json` 或 daemon RPC 包装官方同步命令、稳定 human/json 输出、真实 doctor 检查和端到端测试。
-- 如果项目决策改为“用户 CLI 永久由 Rust `bat` 承担，Go 只做 `bat-api`/服务层”，必须同步更新 `AGENTS.md`、`PROJECT_PLAN.md` 和 issue 跟踪；在完成该决策前，不能把 Go CLI 写成已完成。
+- **正式同步/运维命令行 = Rust `bat`**（近乎全自动：auto-discover + watch/daemon，无需持久手操维护）。
+- **不另做**产品级 Go 同步 CLI，避免与 Rust `bat` 双轨。
+- Go 试验入口 `cmd/bat` 可保留为 experimental，产物必须为 `bin/bat-go`，**禁止**再构建为 `bin/bat`。
+- Go 正式产品入口集中在 **`bat-api` 资源分发服务** + `internal/backendrpc`（G-009）。
 
-验收：
+原验收（真实 doctor / Go sync 包装）**不再作为当前里程碑**。
 
-- `cmd/bat doctor` 做真实环境诊断，而不是固定字符串。
-- `cmd/bat sync` 能通过 `internal/backendrpc` daemon RPC 或 Rust `bat --json` one-shot/fallback 触发/查询官方同步，不走 FFI 控制下载器或 daemon。
-- human/json 输出、退出码和错误码与 Rust `bat` 契约一致。
-- `go test ./...`、`go vet ./...` 覆盖命令解析、错误输出和至少一个 mocked Rust 边界。
+### G-009：API Server（`bat-api`，资源分发）部分完成
 
-### G-009：API Server（`bat-api`，仿官方 API）尚未实现
+状态：**资源 CDN MVP 已落地；非完整官方游戏 API**
 
-现象：
+目标（对应 issue #19，**按资源面收窄**）：
 
-- `api/` 只有目录结构，无 handler、service、路由。
-- Go 侧尚无对接 daemon RPC / `current/` 发布布局的服务端入口。
+- `cmd/bat-api`：只读分发 Rust `bat` 已发布 release（官方 CDN host/path 形态）。
+- **拉取归属 Rust `bat`**；`bat-api` 不做下载器。
+- 发现经 `bat.sock`：先 `daemon.status`，再 `daemon.doctor`，再 `catalog.status` / `resource.manifest`。
+- `.env` 配置端口 / public base / RPC socket；预留 database/redis。
+- launcher 全链、完整业务 API **非关闭条件**；USERGUIDE bat-api 专章延后。
 
-目标（对应 issue #19）：
+已完成：
 
-- 新建 `cmd/bat-api`：**完全仿照 BlueArchive 官方 API** 的 Go HTTP 服务，把 Rust `bat` 后端发布的 `current/` release 按官方接口形态对外提供，使真实客户端/工具可将其当作官方服务端。
-- 仿真面：资源 CDN 面（TableCatalog/MediaCatalog/BundlePackingInfo、bundle、seed `.hash`）、server-info 面、launcher API 面。
-- 鉴权/签名**完全仿照**官方实现，服务端做验签（对齐 `adapters/src/official/launcher.rs` 的签名逻辑）。
-- 版本/状态经 daemon RPC（`catalog.*` / `resource.manifest`）发现，资源字节从 `current/` 读取；不读写 daemon 状态文件内部。
+- `cmd/bat-api`、`internal/api`、fixture 单测、`make build-go-api` / `test-go-api`
+- 进度权威：`docs/reports/GO_STATUS.md`
 
-影响：
+验收（剩余）：
 
-- 客户端、工具和第三方集成无服务端入口。
+- 与全量 release / 服务器 daemon 联调（SSH 实勘可后置）
+- 文档与 GO_STATUS 持续一致
 
-验收：
-
-- Go 单测覆盖路由、签名验签、错误响应形态。
-- 真机 e2e：daemon 发布 fixture release → 启动 `bat-api` → 按官方 URL 与鉴权头请求 server-info / catalog / bundle / launcher 链，断言字节与形态正确、验签生效（缺签/错签被拒）。
-- 统一错误结构与官方响应 envelope 对齐；Makefile 增加 Go 构建/测试目标。
-
-排期：P2，排在 issue #17 验收收口以及 issue #2 / #3 的解析能力继续推进之后启动；可与 G-008 的 Go 产品入口边界收敛并行。
+排期：P2 主体可联调；持久化 API 层与 launcher 另议。
 
 ### G-010：Web 管理后台尚未实现
 
@@ -248,6 +266,11 @@
 - schema 和迁移可重复执行。
 - 可按版本、类型、hash、路径查询资源。
 - 官方同步后的资源可通过 CLI 查询并能追溯到 CAS 对象。
+- `official-parse-cache.json` 的 bundle、zip entry、TextAsset 摘要能进入 ResourceRepository 查询面。
+
+解析补全路线图：
+
+- 见 `docs/architecture/assetbundle.md` 的 P4。
 
 ### G-011A：资源导入链路基础能力不足
 
@@ -294,6 +317,30 @@
 - `cargo test -p bat-infrastructure version_state`
 - `cargo test -p bat-infrastructure --test official_game_main_config_bootstrap`
 
+### G-011D：汉化发布状态与 Patch 发布流程未完成
+
+状态：**新建，未关闭**
+
+当前已完成：
+
+- 官方原版资源发布根为 `./bat-resources`，汉化产物发布根为 `./bat-localized`。
+- CLI 支持 `--localized-output` / `BAT_LOCALIZED_OUTPUT`，并拒绝官方目录和汉化目录相同或互相嵌套。
+- 官方同步报告新增 `localized_release_status=not_localized`，明确表示原版资源已发布、汉化资源未发布。
+
+仍未完成：
+
+- Patch 发布阶段尚未生成 `localized-output/versions/<id>`。
+- 尚未维护 `localized-output/current` 原子指针和汉化版本状态文件。
+- 尚未实现 `localized` 状态切换、回滚和汉化产物完整性校验。
+- 尚未实现原版资源与汉化资源双发布后的查询、分发和清理策略。
+
+验收：
+
+- 原版资源同步成功后保持 `not_localized`，不发布半成品汉化资源。
+- Patch 构建和校验成功后，汉化产物按官方相对路径写入 `localized-output/versions/<id>`。
+- 汉化发布必须原子切换 `localized-output/current`，失败时不影响已发布原版资源。
+- `localized` 状态能证明原版和汉化两套资源都可发布，并能被 CLI/RPC/API 查询。
+
 ### G-011C：真实 fixture 与回归样本不足
 
 状态：**已关闭当前阶段**
@@ -470,13 +517,15 @@
 
 ## 6. 当前关闭顺序建议
 
-1. issue #24：失败 staging 复用已补离线回归；继续核对 issue 口径、状态与后续是否仍有真实场景无法复现的残余。
-2. issue #1：Rust daemon/backend API 边界收口；`resource.repair`、`resource.list`、`daemon.doctor`、`internal/backendrpc` Go client 和稳定 RPC reference 已补齐，剩余确认 `patch.*` / `unityfs.*`（待引擎）、`task.create`（暂不开放通用入口）以及 `daemon.restart` / `daemon.clean-stable`（CLI 生命周期入口）的 issue 验收口径。
-3. issue #17/#20/#21/#22：多线程下载入口已按最新决定移除，下载回归顺序执行并保留指数退避与单调进度上报；daemon 子进程不再透传并发参数，但 GitHub issue 仍 open。
-4. issue #2 / G-007：继续扩大 Addressables 可校验字段和结构变体覆盖。
-5. issue #3 / G-005：把 UnityFS 基础摘要推进到 `bat-assetbundle` 引擎级解析。
-6. G-011：官方同步结果接入 CAS + ResourceRepository 用户级工作流。
-7. G-008 / G-009：收敛 Go 产品入口边界，并实现 `bat-api`（issue #19）。
-8. G-012 / G-006：翻译系统、Patch 引擎。
+1. issue #24：失败 staging 复用回归已补；核对残余场景。
+2. issue #1：RPC 主体已落地；剩余 `patch.*` / `unityfs.*`、设计边界确认。
+3. issue #17 及子 issue：已按 wontfix 关闭多线程下载（顺序下载 + 指数退避）。
+4. **G-008：已决策关闭**（同步 CLI = Rust `bat`；见 `GO_STATUS.md`）。
+5. **G-009 / issue #19**：资源分发 MVP 已编码；优先服务器联调与索引实勘，非「从零实现」。
+6. issue #2 / G-007（P1）：Addressables 可校验字段。
+7. issue #3 / G-005（P1）：UnityFS 容器基础解析已落地；对象级引擎解析继续跟踪 G-005。
+8. G-011：官方同步结果接入 CAS + ResourceRepository 用户级工作流。
+9. G-011D / G-006：汉化发布状态持久化、Patch 发布和回滚。
+10. G-012 / G-006：翻译系统、Patch 引擎。
 
-这个顺序优先把 Rust `bat` 后端做扎实（解析能力 + 下载性能），再把官方同步结果进入可查询资源库，之后收敛 Go 入口和仿官方 API 服务端，最后推进翻译和补丁。G-018 已固化为可重复 smoke 命令并关闭；G-017 已按“不引入托管 CI”决策关闭。
+Go 进度以 `docs/reports/GO_STATUS.md` 为准。G-018 / G-017 已关闭。