docs: 对齐全部文档状态

2026-09-18 06:34:54 +08:00 · 2026-08-03 12:19:06 +08:00
parent a2e2ae8ac5
commit 3b103be8a9
15 changed files with 100 additions and 45 deletions
@@ -9,7 +9,7 @@
 ### 新增
 - Addressables catalog 提取 `m_Crc`（bundle IEEE CRC-32）：`ResourceEntry` 新增 `crc` 字段（compact/expanded 两种形态均解析），SQLite 持久化并对旧库幂等迁移补列；core 新增 `crc32_ieee` 与 `ResourceEntry::verify_downloaded_bytes`（按声明的 size/CRC 校验字节）（issue #2）
 - UnityFS 解析新增目录条目越界校验：directory 的 `offset+size` 必须落在解压数据区内，截断/损坏 bundle 的越界目录条目不再被静默接受（issue #3）
- 官方资源下载回归顺序执行：manifest/quarantine 簿记与 seed `.hash` 校验保持串行，`fail-fast` 与「不发布不完整资源」不变量不变（issue #17，按 wontfix 关闭多线程下载目标）
+- 官方资源下载使用默认 8 个独立 worker；每个 worker 完成当前 URL 后立即从共享计划队列领取下一个任务，manifest/quarantine 簿记与 seed `.hash` 校验逐项保持一致，`fail-fast` 与「不发布不完整资源」不变量不变（issue #17 的历史决定不代表当前并发实现）
 - 新增 `cmd/bat-api` 资源 bootstrap/分发 HTTP 服务（issue #19 / G-009 资源面）：与 Rust `bat` 同环境运行，经 `bat.sock` RPC（`daemon.status` → `daemon.doctor` → catalog/manifest）发现已发布 release 和 `resource_root`，按官方 CDN host/path 只读提供资源；管理面 `/healthz` `/v1/release` `/v1/resources`；可选 server-info 仅改写 Addressables root；`.env` 配置监听端口/RPC socket/刷新周期/预留数据库键。资源自动拉取仍由 Rust `bat` 负责
 - `cmd/bat-api` 新增 `/v1/bootstrap`：把 Rust `bat` 的 RPC 健康、已发布 release 摘要、server-info URL、client-patch base 和改写后的 Addressables root 组织成启动前资源发现响应，固定 `bat` 是资源生产者、`bat-api` 是只读 bootstrap/分发层的关系
 - `bat-api` CDN 分发补齐 Range / HEAD / 条件请求语义：基于 manifest BLAKE3 生成 ETag，返回 Last-Modified、Accept-Ranges 和长期缓存头，`.hash` 以 `text/plain` 返回
@@ -26,12 +26,12 @@
 - 官方下载失败重试之间加入指数退避（网络类失败 200ms→400ms→800ms…，上限 5s）
 ### 计划
- [ ] `bat-api` 后续：全量 release 联调、Rust/Go snapshot contract fixture（用户审核后）、refresh mtime/size 增量缓存、完整 launcher 安装包更新链（若需要，新 issue）、API 持久化层接入预留 database/redis 配置
+- [ ] `bat-api` 后续：全量 release 联调、refresh mtime/size 增量缓存、完整 launcher 安装包更新链（若需要，新 issue）、API 持久化层接入预留 database/redis 配置；Rust/Go snapshot contract fixture 已落仓库
 - [ ] 官方同步结果接入 CAS + ResourceRepository 的用户级工作流
 - [ ] 官方下载/导入路径接入 CRC/size 校验（复用 `verify_downloaded_bytes`）
 - [ ] 汉化 Patch 发布：维护 `localized-output/current`、`localized-version-state`、`localized` 状态切换和回滚
 - [ ] 实现翻译系统
- [ ] 实现 Patch 引擎
+- [ ] 完成发布级 Patch build/rollback、复杂 AssetBundle 重打包和汉化发布统一
 - [ ] 实现 Web 管理后台
 ## [0.2.0] - 2026-07-17
@@ -1,6 +1,6 @@
 # BlueArchiveToolkit 当前工作区状态
- **更新时间**：2026-07-26
+- **更新时间**：2026-08-03
 - **状态来源**：本地工作区盘点、代码验证和最新提交
 - **状态分支**：`experiment`
 - **最新已推送功能提交**：以当前 `git log --oneline -1` 为准
@@ -145,7 +145,7 @@ job/unit/provider run 状态。当前下载实现使用默认 8 个独立 worker
 待完成：
- 将 `crowdin-textunit-queue.json` 接入真实 Crowdin worker、翻译记忆和 Patch 构建；继续扩展真实 worker 状态、失败原因写回和 CAS 诊断查询面。
+- 将 `crowdin-textunit-queue.json` 接入真实 Crowdin/provider worker、翻译记忆和 Patch 构建；围绕 `translation.task.update` 完成真实 worker 集成与失败原因落库验证，并继续扩展 CAS 诊断查询面。
 - 真实线上全量下载 smoke 已固化为 `scripts/official-full-pull-smoke.sh` 和 `make official-smoke`；实际运行报告由脚本写入隔离输出目录。
 - 增加更多权限和极端文件系统场景测试。
@@ -290,9 +290,9 @@ GitHub issue 状态：#1 已关闭；#17 的历史决定不代表当前下载实
 下一阶段必须优先完成：
-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）、`parse.*`（status/text_units/errors）、`translation.*`（tasks）、`localized.*`（status）、`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 与配置校验路径。剩余：发布级 `patch build` / `patch rollback`、复杂 `unityfs.*` 语义编辑、`task.create`（按设计由语义方法创建）、`daemon.clean-stable`（由 CLI 侧按进程生命周期显式执行，live RPC 内不做在线清理）、Redis 任务后端（`.env` 已预留配置键，接入时机另议）。Go 层通过 RPC 调用 Rust backend，不走 FFI（FFI 降级说明见 `docs/architecture/official-resource-backend.md` §7）。
+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）、`parse.*`（status/text_units/errors）、`translation.*`（tasks/handoff/task.update）、`localized.*`（status）、`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 与配置校验路径。剩余：发布级 `patch build` / `patch rollback`、复杂 `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、管理控制白名单、CDN Range/缓存头、RPC 周期刷新和 USERGUIDE 基础章节；剩余为远程服务器全量 release 联调、Rust/Go snapshot contract fixture（用户审核后）、refresh mtime/size 增量缓存和可选持久化。
+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、管理控制白名单、CDN Range/缓存头、RPC 周期刷新和 USERGUIDE 基础章节；仓库内 Rust/Go snapshot contract fixture 已落地，剩余为远程服务器全量 release 联调、refresh mtime/size 增量缓存和可选持久化。
-3. 文本提取 / 翻译队列 / Patch 输入：`official-textunit-index.json`、`official-textunit-tasks.json` 与 `crowdin-textunit-queue.json` 已生成；TextUnit 明细、解析错误和离线翻译任务状态/失败原因已可查询。剩余为真实 Crowdin worker、翻译记忆、Patch 构建和 worker 状态写回。
+3. 文本提取 / 翻译队列 / Patch 输入：`official-textunit-index.json`、`official-textunit-tasks.json` 与 `crowdin-textunit-queue.json` 已生成；TextUnit 明细、解析错误和离线翻译任务状态/失败原因已可查询，`translation.task.update` 已提供 worker 状态回写 contract。剩余为真实 Crowdin/provider worker、翻译记忆和 Patch 构建。
 4. Issue #3（P1）：AssetBundle UnityFS 基础解析校验已具备离线和隔离真实样本覆盖；对象级解析继续跟踪 G-005。
 5. Issue #2（P1）：继续逆向 Addressables catalog，提取 bundle hash/size/CRC 等可校验字段。
 6. 通用 Binary/JSON/Text Patch 基础已落地；复杂 AssetBundle 重打包和真实翻译系统仍应后置，UnityFS TextAsset patch 发布前置已具备回归测试。
@@ -314,4 +314,4 @@ GitHub issue 状态：#1 已关闭；#17 的历史决定不代表当前下载实
 - **当前总体完成度**：不再固定写单一百分比，以各模块状态、`GO_STATUS.md` 和 issue 为准。
 - **当前基线状态**：Rust `bat` 同步闭环可用；Go `bat-api` 资源 bootstrap/分发 MVP + 玩家-facing HTTP 控制面 + launcher 资源引导兼容 + RPC 周期刷新/诊断 + readiness + `backendrpc` 可用；CAS 用户级导入、TextUnit 明细索引/查询、增量 Crowdin 离线队列、通用 Binary/JSON/Text Patch 基础和 UnityFS TextAsset patch 发布前置可用；完整 AssetBundle 重打包未完成。
- **下一工程里程碑**：bat-api 联调、真实 Crowdin worker / 翻译记忆、worker 状态写回、复杂 AssetBundle 解析和重打包。
+- **下一工程里程碑**：bat-api 联调、真实 Crowdin/provider worker / 翻译记忆、复杂 AssetBundle 解析和重打包。
@@ -1,6 +1,6 @@
 # BlueArchiveToolkit 文档索引
- **更新时间**：2026-07-24
+- **更新时间**：2026-08-03
 - **说明**：本索引用于快速定位当前权威文档和历史资料。
 ---
@@ -29,6 +29,7 @@
 - `docs/architecture/README.md`：总体架构设计。
 - `docs/api/README.md`：API 设计入口。
 - `api/openapi/bat-api.yaml`：当前 `bat-api` 资源 bootstrap/分发 HTTP OpenAPI 静态规范。
 - `docs/reference/rpc-backend-api.md`：Rust Resource Backend JSON-RPC 稳定 contract。
 - `docs/guides/development.md`：开发指南。
 - `docs/guides/deployment.md`：部署指南。
@@ -1,7 +1,7 @@
 # BlueArchiveToolkit 完整开发计划
 - **项目名称**：BlueArchiveToolkit
- **文档版本**：2026-07-20 状态收口版
+- **文档版本**：2026-08-03 状态复核版
 - **权威状态**：以本文档和 `CURRENT_STATUS.md` 为准，旧阶段报告仅作历史参考。
 - **最终目标**：构建一个可长期维护、可扩展、可审计的 Blue Archive 资源管理、文本提取、翻译和补丁平台。
@@ -22,7 +22,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 ## 2. 当前真实状态
-本节来自 2026-07-20 的工作区盘点、本地验证和最新功能提交。
+本节来自 2026-08-03 的工作区盘点、本地验证和最新功能提交。
 ### 已具备
@@ -44,10 +44,10 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 2. `bat-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 与 UnityFS TextAsset / TypeTree string / TypeTree 语义字段写入入口已开放，当前发布级可用的是 `bat-assetbundle` + `LocalizedPatchService` 的 UnityFS TextAsset patch 前置链路。
 3. Go 侧边界已冻结（见 `docs/reports/GO_STATUS.md`）：同步/运维命令行 = Rust `bat`；资源分发 = `cmd/bat-api` MVP；`internal/backendrpc` 完成；`cmd/bat` 仅为试验（`bin/bat-go`）。完整游戏业务 API / Web / SDK 仍未完成。
 4. Addressables parser 已覆盖当前真实形态 fixture/golden，但还不是完整 Unity Addressables/SBP catalog 兼容层。
-5. 官方同步结果可配置为发布后自动导入 CAS + ResourceRepository，并通过 `resource.index` RPC/CLI 查询；Resource metadata 已保存 release、平台、bundle path、parse status、TextAsset 名称和 TextUnit 摘要，资源级查询已覆盖 release、平台、destination、archive entry、parse status 和 TextUnit format；单条 TextUnit 明细和解析错误已持久化到 `official-textunit-index.json`，可通过 `parse.text_units` / `parse.errors` 查询；离线 TextUnit 翻译任务状态和跳过/失败原因可通过 `translation.tasks` 查询，真实 worker 状态写回仍需继续推进。
+5. 官方同步结果可配置为发布后自动导入 CAS + ResourceRepository，并通过 `resource.index` RPC/CLI 查询；Resource metadata 已保存 release、平台、bundle path、parse status、TextAsset 名称和 TextUnit 摘要，资源级查询已覆盖 release、平台、destination、archive entry、parse status 和 TextUnit format；单条 TextUnit 明细和解析错误已持久化到 `official-textunit-index.json`，可通过 `parse.text_units` / `parse.errors` 查询；离线 TextUnit 翻译任务状态和跳过/失败原因可通过 `translation.tasks` 查询，`translation.task.update` 已提供 worker 状态回写 contract，真实 provider worker 集成仍需继续推进。
 6. 汉化 Patch 发布前置已具备 UnityFS TextAsset manifest/apply/diff/rollback/完整性校验和 `localized.status` 严格校验；真实 Crowdin worker、翻译记忆到完整汉化文件集合的构建仍未完成。
 7. 真实官方网络全量下载 smoke 已固化为可重复脚本和 runbook（G-018 已关闭）；真实运行记录处于长期运行测试阶段，报告待后续提供。
-8. Web、数据库迁移、OpenAPI、插件加载机制尚未实现。
+8. 完整 Web、数据库迁移、插件加载机制尚未实现；`bat-api` 资源 bootstrap/分发 OpenAPI 已通过 `/openapi.yaml` 提供，完整游戏业务 API 的 OpenAPI 仍未完成。
 9. 原 Git 历史未恢复；当前仓库以新初始化基线为准。
 ### 已验证
@@ -168,7 +168,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 **目标**：能够获取、解析和同步 Blue Archive 资源清单。
-**当前状态**：部分完成。Rust 官方日服资源同步链路已经具备正式 one-shot 和 `--watch` 常驻入口；Go 产品入口、完整解析覆盖、CAS 导入编排和真实线上 smoke 仍待完成。
+**当前状态**：部分完成。Rust 官方日服资源同步链路已经具备正式 one-shot 和 `--watch` 常驻入口；`bat-api` 资源 bootstrap/分发入口已落地，但完整解析覆盖、CAS 用户级编排和真实线上 smoke 仍待完成。
 交付物：
@@ -178,7 +178,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 4. Rust 自动更新入口：**已完成当前生产入口**。`bat` 支持 snapshot、marker diff、bootstrap cache、one-shot、`--watch`、`--daemon`、默认 1 小时间隔、北京时间固定强制刷新，以及 Unix socket JSON-RPC 后台运维命令返回。
 5. Go 入口边界：**已冻结**。同步命令行 = Rust `bat`（G-008 关闭）；资源分发 = `bat-api` MVP（G-009 部分完成）。详见 `docs/reports/GO_STATUS.md`。
 6. 用户级 `sync`、`manifest inspect`、`cache status`：**未完成**。Rust `bat --json` 是当前稳定进程边界；`bat-ffi` 只提供可选兼容用的 Manifest inspect 和 sync plan JSON helper。
-7. 下载结果写入 CAS + ResourceRepository：**部分完成**。CAS 和 SQLite ResourceRepository 已存在，官方同步入口可用 `--import-repository` / `BAT_IMPORT_REPOSITORY=1` 在已校验 release 发布后导入；`resource.index` 可按资源级 release、平台、destination、archive entry、parse status 和 TextUnit format 查询现有索引和资源 metadata；`parse.text_units` / `parse.errors` 可查询当前 release 的 TextUnit 明细与解析错误；`translation.tasks` 可查询离线 TextUnit 翻译任务状态和跳过/失败原因。剩余工作是真实 worker 状态写回、CAS 诊断入口和面向大索引的查询优化。
+7. 下载结果写入 CAS + ResourceRepository：**部分完成**。CAS 和 SQLite ResourceRepository 已存在，官方同步入口可用 `--import-repository` / `BAT_IMPORT_REPOSITORY=1` 在已校验 release 发布后导入；`resource.index` 可按资源级 release、平台、destination、archive entry、parse status 和 TextUnit format 查询现有索引和资源 metadata；`parse.text_units` / `parse.errors` 可查询当前 release 的 TextUnit 明细与解析错误；`translation.tasks` 可查询离线 TextUnit 翻译任务状态和跳过/失败原因。剩余工作是真实 provider worker 集成、CAS 诊断入口和面向大索引的查询优化。
 8. Linux 生产同步不依赖已安装官方启动器：**已完成当前 Rust 入口**。`--auto-discover` 只使用官方 HTTP metadata 和临时目录解析 `GameMainConfig`。
 9. 真实官方网络全量下载 smoke test：**命令已固化（G-018 已关闭）**。`scripts/official-full-pull-smoke.sh` / `make official-smoke` 已固化 dry-run、首次下载、二次 up-to-date 和本地损坏 repair 的可重复流程；真实运行处于长期运行测试阶段，报告待后续提供。
 10. 官方发布后的增量 handoff 与解析缓存：**已完成基础入口**。新 release 发布后先生成 `official-resource-changes.json` 和 `crowdin-translation-handoff.json`，新增+变更资源进入解析/翻译候选；`official-parse-cache.json` 基于下载 manifest 覆盖直接 UnityFS bundle、zip 内 UnityFS 条目和非候选资源记录；随后生成 `official-textunit-index.json`、`official-textunit-tasks.json` 与 `crowdin-textunit-queue.json`，本地文件未变化且缓存/索引有效时跳过重复解析。
@@ -404,7 +404,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
 3. G-009 / issue #19：`bat-api` 资源分发 MVP 已落地；优先服务器联调；拉取仍在 Rust `bat`。
 4. 继续 Addressables（issue #2）与 UnityFS（issue #3 / G-005）。
 5. 将 `crowdin-textunit-queue.json` 接入真实 Crowdin worker、翻译记忆和 Patch 构建。
-6. 继续扩展 G-011 剩余查询面：真实 worker 状态写回、`doctor cas` 诊断入口和面向大索引的查询优化。
+6. 继续扩展 G-011 剩余查询面：真实 provider worker 集成与状态落库验证、`doctor cas` 诊断入口和面向大索引的查询优化。
 ---
@@ -13,7 +13,7 @@
 - `bat-adapters` Unity、Manifest、Client 集成框架，以及当前真实形态 Addressables catalog 解析覆盖，含 `m_Crc` 提取和 UnityFS 解包/TextAsset 提取基础校验。
 - `bat-cas-engine` CAS V1：原子写入、BLAKE3 校验、引用计数、GC、并发写入测试、损坏检测。
 - `bat-infrastructure` CAS 适配层、SQLite Resource Repository、资源导入服务、官方资源 pull/update 服务。
- `bat`：官方资源自动发现、全量拉取、原子发布到 `current -> versions/<id>`、本地 manifest audit/repair、`.part` 断点续传、403/404/5xx 分类重试、指数退避、默认并发 8（可配置 `1..=256`，report 按 plan 顺序、进度按完成数单调上报）、下载 quarantine 诊断、ZIP 结构校验、官方 seed `.hash` 校验、snapshot/cache、版本化 `official-launcher-bootstrap.json`、`--watch` 常驻更新、`--daemon` 后台运行，以及 Unix socket JSON-RPC live control/backend 方法（`daemon.status/logs/stop/restart/reload/refresh/doctor`、`resource.sync/verify/repair/state/manifest/list/index`、`parse.status/text_units/errors`、`localized.status`、`catalog.*`、`task.*`）。
+- `bat`：官方资源自动发现、全量拉取、原子发布到 `current -> versions/<id>`、本地 manifest audit/repair、`.part` 断点续传、403/404/5xx 分类重试、指数退避、默认并发 8（可配置 `1..=256`，report 按 plan 顺序、进度按完成数单调上报）、下载 quarantine 诊断、ZIP 结构校验、官方 seed `.hash` 校验、snapshot/cache、版本化 `official-launcher-bootstrap.json`、`--watch` 常驻更新、`--daemon` 后台运行，以及 Unix socket JSON-RPC live control/backend 方法（`daemon.*`、`resource.*`、`parse.*`、`translation.tasks/handoff/task.update`、`localized.status`、`catalog.*`、`task.*`、`patch.apply`、`unityfs.patch_*`）。
 - `internal/backendrpc`：Go 侧 typed Unix socket JSON-RPC client，是 `bat-api` 调用 Rust daemon 的默认路径。
 - `cmd/bat-api`：资源 bootstrap + 分发 HTTP MVP（issue #19 / G-009）；`/v1/bootstrap` 和 `/v1/launcher/bootstrap` 组织 `bat` 已发布 release 的启动前资源入口，launcher 形状兼容端点仅输出资源 metadata / GameMainConfig 引导，`/healthz` 暴露 RPC refresh 诊断，`/readyz` 做 release readiness，CDN path 支持 `GET`/`HEAD`/`Range`、ETag、Last-Modified 和缓存头；玩家-facing 控制面已具备 token 鉴权、限流、访问日志、反代 IP 适配、动态 JSON no-store、OpenAPI 和管理控制白名单；`.env` 配置端口/RPC socket/刷新周期；生产资源根来自 RPC，不负责自动拉取。
 - Go 边界权威说明：[`docs/reports/GO_STATUS.md`](docs/reports/GO_STATUS.md)（G-008 已关闭：同步 CLI = Rust `bat`）。
@@ -27,7 +27,7 @@
 仍未完成：
- `bat-api` 完整游戏业务 API / launcher 安装包更新全链（资源 CDN、HTTP 控制面和 launcher 资源引导兼容已可用）。
+- `bat-api` 完整游戏业务 API / launcher 安装包更新全链仍未完成；资源 CDN、HTTP 控制面和 launcher 资源引导兼容已可用。
 - 完整 AssetBundle 对象级解析（UnityFS 解包、object table、TypeTree node 元数据、TextAsset bytes、MonoBehaviour/ScriptableObject 基础 TypeTree 字段级解析已起步；复杂字段覆盖、发布级重打包和 Patch 发布统一仍未完成）。
 - 复杂 AssetBundle 重打包和真实翻译构建 worker；当前通用 Binary/JSON/Text Patch 基础已在 crate 层可用，发布链路仍只开放 UnityFS TextAsset patch 前置能力。
 - Translation Memory、Glossary、AI Provider。
@@ -142,7 +142,7 @@ make official-smoke
 ## 技术栈
 - Rust：CAS、官方资源同步核心、AssetBundle/Patch 引擎；当前生产同步入口是 `bat` binary。
- Go：计划中的最小 CLI、服务编排、API Server、SDK；默认通过 `bat --json` 进程边界或未来 SDK 集成 Rust 能力。
+- Go：当前正式入口是 `bat-api` 资源 bootstrap/分发服务和 `internal/backendrpc`；完整游戏业务 API、SDK、Provider 编排仍按路线图推进，`cmd/bat` 仅为试验 CLI。
 - `bat-ffi`：可选兼容层，只暴露无状态粗粒度 JSON C ABI，不承载 daemon、下载器、CAS handle 或主控制面。
 - PostgreSQL：计划中的服务端主数据库。
 - Redis：计划中的缓存、队列状态、限流和短期锁。
@@ -167,7 +167,7 @@ BlueArchiveToolkit/
 ├── internal/ffi/          # 可选 CGO 兼容包装，不是 Go CLI 主路径
 ├── cmd/                   # Go CLI 试验骨架与后续产品入口
 ├── pkg/                   # Go SDK 包，尚未实现
-├── api/                   # API 定义，尚未实现
+├── api/                   # 预留 API 定义；bat-api OpenAPI 静态规范已提供，完整业务 API 尚未实现
 ├── web/                   # Web 管理后台，尚未实现
 ├── deployments/           # Docker 和部署配置
 ├── docs/                  # 文档、历史报告和分析资料
@@ -182,7 +182,7 @@ BlueArchiveToolkit/
 近期优先级：
-1. 收敛 Go CLI 产品入口的最终形态：当前 `cmd/bat` 仅有 `doctor`、`manifest inspect`、`sync plan` 试验能力，不应误写成完整 CLI。
+1. 维护并联调 Go `bat-api` 资源 bootstrap/分发入口；`cmd/bat` 仅有 `doctor`、`manifest inspect`、`sync plan` 试验能力，不应误写成完整产品 CLI。
 2. 补齐 AssetBundle UnityFS 引擎级解析。
 3. 扩展 Addressables catalog 解析覆盖，继续用真实形态 fixture/golden 锁定行为。
 4. 将 `official-textunit-tasks.json` / `crowdin-textunit-queue.json` 接入真实 Crowdin worker、翻译记忆和 Patch 构建。
@@ -382,6 +382,13 @@ curl -i -H 'Range: bytes=0-1023' \
 | `resource.verify` | ✅ | 触发校验任务（dry-run + audit），返回 `task_id` |
 | `resource.repair` | ✅ | 触发本地 manifest 审计 + 修复任务，返回 `task_id`；不继承 `force` |
 | `resource.manifest` / `resource.list` | ✅ | 当前版本下载 manifest 分页查询（`params.offset` 默认 0、`params.limit` 默认 100/上限 1000） |
 | `resource.index` | ✅ | 查询现有 SQLite ResourceRepository 索引，支持资源类型、hash、路径模式、release、平台、destination、bundle path、archive entry、parse status 和 TextUnit format 过滤 |
 | `parse.status` | ✅ | 查询当前 release 的解析缓存、TextUnit 索引和队列摘要 |
 | `parse.text_units` / `parse.errors` | ✅ | 查询当前 release 的 TextUnit 明细和解析错误 |
 | `translation.tasks` | ✅ | 查询离线 TextUnit 翻译任务及 worker 状态 |
 | `translation.handoff` | ✅ | 查询完整 job/unit/provider run 交接视图 |
 | `translation.task.update` | ✅ | 回写当前 release 的 provider worker 状态 |
 | `localized.status` | ✅ | 查询汉化 release 与当前官方 release 的匹配状态 |
 | `catalog.status` | ✅ | 当前已发布版本的 catalog 概览（app/bundle 版本、addressables 根、端点与 marker 计数、launcher 元数据） |
 | `catalog.versions` | ✅ | 版本历史：current / in_progress / previous / failed |
 | `catalog.diff` | ✅ | 当前 snapshot 相对上一个可用版本的差异（base_delta + extended_delta + 变更端点 URL） |
@@ -390,10 +397,15 @@ curl -i -H 'Range: bytes=0-1023' \
 | `task.list` | ✅ | 列出全部任务（最新在前） |
 | `task.cancel` | ✅ | 请求取消任务（`params.task_id`）；协作式，在同步检查点生效 |
 | `task.logs` | ✅ | 返回任务的进度日志（`params.task_id`，有界） |
-| `daemon.clean-stable` / 发布级 `patch.*` / 未开放 `unityfs.*` / `task.create` | ⏳ | 已规划，返回 `BAT-ERR-700003`（not implemented）；clean-stable 仍由 CLI 侧按进程生命周期显式执行，task.create 暂不开放通用任务入口 |
+| `patch.apply` | ✅ | 对显式 source/patch/target 文件同步执行 Binary/JSON/Text patch |
 | `unityfs.patch_text_asset` / `unityfs.patch_string_field` / `unityfs.patch_field` | ✅ | 对显式 UnityFS bundle 文件执行文件级写入并原子输出 |
 | `daemon.clean-stable` / 发布级 patch 方法 / 其他未开放 `unityfs.*` / `task.create` | ⏳ | 返回 `BAT-ERR-700003`（not implemented）；clean-stable 仍由 CLI 侧按进程生命周期显式执行，task.create 暂不开放通用任务入口 |
 | 未知方法 | — | `BAT-ERR-700001`（unknown method） |
-只读查询（`daemon.doctor` / `resource.state` / `resource.manifest` / `resource.list` / `catalog.status` / `catalog.versions` / `catalog.diff`）在尚无已发布版本或对应文件不存在时返回 `ok: true` 且 `data.available: false`（正常状态而非错误，便于调用方直接分支）。
+只读查询（`daemon.doctor` / `resource.state` / `resource.manifest` / `resource.list` /
 `resource.index` / `parse.*` / `translation.tasks` / `translation.handoff` /
 `localized.status` / `catalog.status` / `catalog.versions` / `catalog.diff`）在尚无已发布版本
 或对应文件不存在时返回 `ok: true` 且 `data.available: false`（正常状态而非错误，便于调用方直接分支）。
 ### 任务模型
@@ -401,7 +413,7 @@ curl -i -H 'Range: bytes=0-1023' \
 ```json
 { "id": "task-1234-1", "kind": "resource.sync",
-  "status": "queued|running|succeeded|failed",
+  "status": "queued|running|succeeded|failed|cancelled",
  "stage": "download", "message": "…",
  "created_at": …, "updated_at": …, "started_at": …, "finished_at": …,
  "error": { … }, "result": { … } }
@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
  title: BlueArchive Toolkit bat-api
  version: 0.1.0
-  description: Resource bootstrap and read-only distribution API.
+  description: Resource bootstrap, read-only distribution, and authenticated Rust bat control proxy.
 servers:
  - url: http://127.0.0.1:18080
 security:
@@ -104,10 +104,43 @@ paths:
          description: OpenAPI YAML.
  /admin/:
    get:
-      summary: Reserved admin panel entry
+      summary: Admin control entry
      responses:
        "200":
-          description: Admin panel placeholder and links.
+          description: Admin links and allowlisted control actions.
  /admin/control/{action}:
    post:
      summary: Forward an allowlisted control action to Rust bat
      parameters:
        - name: action
          in: path
          required: true
          schema:
            type: string
            enum: [reload, refresh, restart, sync, verify, repair, catalog-refresh]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                force:
                  type: boolean
      responses:
        "202":
          description: Rust bat accepted the control request.
        "400":
          description: Invalid action parameters.
        "401":
          description: Missing or invalid admin token.
        "403":
          description: Control is not exposed or no admin token is configured.
        "501":
          description: Rust bat does not implement the requested control action.
        "502":
          description: Rust bat rejected the control request.
  /prod-clientpatch.bluearchiveyostar.com/{path}:
    get:
      summary: CDN-shaped resource bytes
@@ -4,7 +4,7 @@
 BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建一个可持续维护十年以上的工业级开源项目。
-当前文档描述目标架构和已经落地的关键边界。它不是部署手册；当前可部署能力只有 Rust 官方资源同步任务。API Server、Web、Provider 编排和 Go 产品入口仍未完成，实际实现状态以根目录 `CURRENT_STATUS.md` 和 `PROJECT_PLAN.md` 为准。
+当前文档描述目标架构和已经落地的关键边界。它不是部署手册；当前可部署能力包括 Rust 官方资源同步任务和 Go `cmd/bat-api` 资源 bootstrap/分发服务。完整游戏业务 API、Web、Provider 编排和 SDK 仍未完成，实际实现状态以根目录 `CURRENT_STATUS.md` 和 `PROJECT_PLAN.md` 为准。
 当前已经可用的官方资源入口包括：
@@ -1,6 +1,6 @@
 # 稳定工程基线指南
- **更新时间**：2026-07-26
+- **更新时间**：2026-08-03
 - **目标**：让工作区处于可继续开发核心功能的可信状态。
 ---
@@ -13,7 +13,7 @@
 2. 根目录只保留入口文档和工程配置。
 3. 旧报告归档，且不再和当前状态混淆。
 4. Rust workspace 成员显式列出。
-5. Go 产品入口尚未完成时，Makefile 不把骨架包误报为完整产品。
+5. Go 正式入口为 `bat-api` 资源 bootstrap/分发服务；Makefile 不把实验性 CLI 骨架误报为完整产品。
 6. 当前缺口有集中清单和关闭顺序。
 7. 架构边界有 ADR 记录。
 8. 基础验证命令通过。
@@ -93,7 +93,7 @@ CAS V1 和 Rust 官方同步闭环完成后，下一阶段优先推进：
 1. 继续联调 Go `bat-api` 与 Rust daemon 的资源分发路径；Go 同步 CLI 不再作为产品目标。
 2. 按 `docs/guides/official-full-pull-smoke.md` 在隔离目录执行真实官方网络全量下载 smoke，并保留运行报告。
 3. 将 `crowdin-textunit-queue.json` 接入真实 Crowdin worker、翻译记忆和 Patch 构建。
-4. 扩展 ResourceRepository 查询面：真实 worker 状态写回、CAS 诊断入口和更丰富 TextUnit 查询。
+4. 扩展 ResourceRepository 查询面：真实 provider worker 集成与状态落库验证、CAS 诊断入口和更丰富 TextUnit 查询。
 5. 继续完善 AssetBundle 复杂对象解析、复杂对象重打包和 Patch 发布流程统一；通用 Binary/JSON/Text Patch 基础与 UnityFS TextAsset patch 发布前置链路已可用。
 优先阅读：
@@ -498,7 +498,9 @@ BAT_API_SKIP_ENV_FILE=1 go run ./cmd/bat-api \
 ## 模式 5：完整生产环境部署
-当前不可用。API Server、数据库迁移、Web 管理后台和发布编排尚未实现；不要按完整服务端产品部署本仓库。
+完整游戏业务生产环境当前不可用。`bat-api` 资源 bootstrap/分发服务和 Rust
 官方资源同步任务已经可以按模式 3/4 部署；数据库迁移、Web 管理后台、发布编排
 以及完整游戏业务 API 尚未实现，因此不要按完整服务端产品部署本仓库。
 ---
@@ -384,7 +384,9 @@ cargo fetch
 ### 3. FFI 兼容层问题
-`bat-ffi` 不是主集成边界，只用于需要 C ABI 的兼容场景。未来 Go 产品入口集成优先运行 Rust `bat --json` 或调用 daemon RPC。
+`bat-ffi` 不是主集成边界，只用于需要 C ABI 的兼容场景。当前 Go 正式产品入口是
 `bat-api` 资源 bootstrap/分发服务，默认通过 `internal/backendrpc` 调用 daemon RPC；
 `cmd/bat` 仍是试验 CLI。未来新增 Go 集成仍优先使用 Rust `bat --json` 进程边界或稳定 RPC/SDK。
 重新构建兼容库：
 ```bash
@@ -1,8 +1,9 @@
 # bat-api / Rust bat Contract Fixture Handoff
-更新时间：2026-07-31
+更新时间：2026-08-03
-本文用于两个 Codex 窗口之间间接联调 `bat-api` 与 Rust `bat` 的跨语言 contract fixture。它只定义协作协议和验收标准，不包含已审核 fixture。
+本文用于两个 Codex 窗口之间间接联调 `bat-api` 与 Rust `bat` 的跨语言 contract fixture。
 仓库内归一化 fixture 已交付；本文保留生成、审核和后续扩展的协作协议。
 2026-07-31 更新：已审核归一化 fixture 已落入
 `internal/api/testdata/contract/`，Go 侧通过
@@ -16,7 +17,9 @@
 - 本次联调对象是 Rust `bat` RPC / snapshot JSON 与 Go `bat-api` mirror struct 的 contract fixture。
 - 联调不要求本地运行全量长期服务端 `bat`；允许 Rust 侧使用 fixture root 或临时目录走真实代码路径导出 JSON。
 - fixture 审核前只能放在 `/tmp/bat-contract-fixture/`，不能直接提交到仓库。
- Go 侧已经实现 player-facing HTTP 鉴权、限流、访问日志、反代适配、OpenAPI 和 `/admin/` 预留；contract fixture 是剩余跨语言强契约工作。
+- Go 侧已经实现 player-facing HTTP 鉴权、限流、访问日志、反代适配、OpenAPI 和
  `/admin/` 控制入口；仓库内 contract fixture 已完成，剩余是 live daemon socket
  和完整 release 切换联调。
 - Go 侧当前相关代码入口：
  - `internal/api/rpc_release.go`
  - `internal/api/release_index.go`
@@ -1,6 +1,6 @@
 # 当前实现缺口清单
- **更新时间**：2026-07-24
+- **更新时间**：2026-08-03
 - **Go 进度权威**：`GO_STATUS.md`
 - **资源布局 / 逆向契约**：`../architecture/resource-release-layout.md`
 - **用途**：集中跟踪当前代码中的占位实现、设计缺口和下一步验收项。
@@ -230,8 +230,8 @@
 - `cmd/bat-api`：组织 Rust `bat` 已发布 release 的启动前资源入口，并只读分发官方 CDN host/path 形态资源。
 - **拉取归属 Rust `bat`**；`bat-api` 不做下载器。
 - 发现经 `bat.sock`：先 `daemon.status`，再 `daemon.doctor`，再 `catalog.status` / `resource.manifest`。
- `bat-api` 通过 RPC 读取的 `resource.state`、`catalog.status`、`parse.status` 和 `localized.status` 会获得短状态 `status` 与稳定生命周期状态码 `status_code`；错误原因仍以 `BAT-ERR-*` 为准。
+- Rust RPC 的 `resource.state`、`catalog.status`、`parse.status` 和 `localized.status` 会返回短状态 `status` 与稳定生命周期状态码 `status_code`；`backendrpc` 已提供对应 client 能力，当前 `bat-api` 发现流程只消费 `resource.state`、`catalog.status`、`resource.manifest`，parse/localized 不由 HTTP surface 暴露；错误原因仍以 `BAT-ERR-*` 为准。
- `bat-api` 可通过受限 Web 控制面转发 `reload` / `refresh` / `restart` / `sync` / `verify` / `repair` / `catalog-refresh`，其中 `restart`、`parse.*`、`localized.status` 和文件级 `unityfs.patch_*` 均走 Rust live RPC；`daemon.clean-stable` 等危险或离线生命周期命令不经 Web 转发。
+- `bat-api` 可通过受限 Web 控制面转发 `reload` / `refresh` / `restart` / `sync` / `verify` / `repair` / `catalog-refresh`，这些控制动作均走 Rust live RPC；`parse.*`、`localized.status` 和文件级 `unityfs.patch_*` 属于 `backendrpc` 能力，但当前不由 HTTP surface 暴露；`daemon.clean-stable` 等危险或离线生命周期命令不经 Web 转发。
 - 生产与 Rust `bat` 同环境运行，资源根来自 RPC 返回的 `resource_root`；`--resource-root` 仅用于 fixture 或应急只读诊断。
 - `.env` 配置端口 / public base / RPC socket / RPC 刷新周期；预留 database/redis。
 - `/v1/bootstrap` 返回 RPC 健康、release 摘要、server-info URL、client-patch base 和改写后的 Addressables root。
@@ -245,11 +245,12 @@
 - `cmd/bat-api`、`internal/api`、`/v1/bootstrap`、`/v1/launcher/bootstrap`、launcher 资源 metadata 兼容端点、HTTP token 鉴权、限流、访问日志、反代 IP 适配、动态 JSON `no-store`、`/v1/resources` 分页上限、OpenAPI、`/admin/` 管理控制白名单、RPC 周期刷新/诊断、`/readyz`、CDN Range/缓存头、fixture 单测、USERGUIDE 基础章节、systemd bat-api 模板、`make build-go-api` / `test-go-api`
 - 进度权威：`docs/reports/GO_STATUS.md`
 - Rust snapshot schema 与 Go mirror struct 的仓库内 contract fixture 已完成，文件位于
  `internal/api/testdata/contract/`；剩余是 live daemon socket 和完整 release 切换联调。
 验收（剩余）：
 - 与远程长期运行的 `bat` / 全量 release 联调（覆盖 bootstrap、server-info、CDN path；SSH 实勘可后置）
 - Rust snapshot schema 与 Go mirror struct 的跨语言 contract fixture（需要用户审核后落入 fixture）
 - refresh 中 manifest 磁盘校验的 mtime/size 增量缓存优化（真实全量 release 观测后决定）
 - 文档与 GO_STATUS 持续一致
@@ -1,6 +1,6 @@
 # Go 侧进度与边界（权威）
- **更新时间**：2026-07-27
+- **更新时间**：2026-08-03
 - **用途**：统一 Go module `bat-api` 的产品边界、既有约定和组件进度；其他文档与此冲突时以本文为准。
 - **关联**：issue #19 / G-009（资源 bootstrap/分发）、G-008（已决策关闭）、`docs/architecture/official-resource-backend.md` §7
@@ -1,9 +1,10 @@
 # bat-api Admin Panel
 This directory is reserved for the future player-facing `bat-api` management
-panel. The current backend exposes a protected placeholder at `GET /admin/`
+panel. The current backend exposes a non-mutating index at `GET /admin/` that
-that returns JSON links for health, readiness, bootstrap, release, resources,
+returns JSON links for health, readiness, bootstrap, release, resources, and
-and OpenAPI.
+OpenAPI. Mutating `/admin/control/{action}` routes are protected by the
 configured admin token and forward only the documented Rust `bat` allowlist.
 The production panel must reuse the same HTTP authentication, rate limiting,
 access logging, reverse-proxy handling, and no-store dynamic response policy as