From d22f9258ad0a526bad3619f1d9f7a73f562e1875 Mon Sep 17 00:00:00 2001 From: Yuyi-Oak <1722157266@qq.com> Date: Fri, 17 Jul 2026 10:27:44 -0700 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=20RPC=20Backend=20API=20?= =?UTF-8?q?=E4=B8=8E=20Go/FFI=20=E8=BE=B9=E7=95=8C=E7=AB=A0=E8=8A=82?= =?UTF-8?q?=EF=BC=8C=E5=90=8C=E6=AD=A5=20issue=20#1=20=E8=BF=9B=E5=B1=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 架构文档新增 §7「RPC Backend API 与 Go 调用边界」：协议契约 （envelope、ApiError、任务模型、方法命名空间与实现状态，细节指向 USERGUIDE §6）、Go 层职责边界（HTTP/鉴权/分发 + RPC client，不嵌 FFI、不直接读 daemon 内部状态）、FFI 降级说明（bat-ffi 保留为可选 历史兼容边界，新能力一律先落 RPC）。对应 issue #1 文档要求第 8 项。 - CURRENT_STATUS：issue #1 条目由"待实现"改为"主体已实现 + 剩余清单"， 下一步清单同步。 Co-Authored-By: Claude Fable 5 --- CURRENT_STATUS.md | 4 +- .../architecture/official-resource-backend.md | 39 +++++++++++++++++++ 2 files changed, 41 insertions(+), 2 deletions(-) diff --git a/CURRENT_STATUS.md b/CURRENT_STATUS.md index 800d1ee..9dfca13 100644 --- a/CURRENT_STATUS.md +++ b/CURRENT_STATUS.md @@ -266,7 +266,7 @@ GitHub issue 状态：#4–#16 已全部关闭（#16 为 daemon status 版本失 下一阶段必须优先完成： -1. Issue #1（P1）：把 `bat` daemon 的 `bat.sock` Unix socket JSON-RPC 从运维控制通道扩展为面向 Go 服务层的本机 Rust Resource Backend API。方法按 `daemon.*`、`resource.*`、`catalog.*`、`patch.*`、`unityfs.*`、`task.*` 分层，统一响应 envelope（`ok`、`status`、`error`、`data`、`request_id`），长任务返回 `task_id` 可轮询；首批最小方法集为 `daemon.status`、`daemon.logs`、`resource.sync`、`resource.verify`、`resource.state`、`task.status`、`task.list`。Go 层通过 RPC 调用 Rust backend，不走 FFI；现有 CLI 保持可用并可作为 RPC client，daemon 不可用时保留兼容 fallback。 +1. Issue #1（P1，主体已实现）：`bat.sock` Unix socket JSON-RPC 已扩展为面向 Go 服务层的 Rust Resource Backend API。统一 envelope（`ok`、`status`、`error`、`data`、`request_id`）与 `BAT-ERR` 错误码模型已落地；`daemon.*`（status/logs/stop/reload/refresh）、`resource.*`（state/sync/verify/manifest）、`catalog.*`（status/refresh/diff/versions）、`task.*`（status/list/cancel/logs）已实现，长任务返回 `task_id` 可轮询（内存态任务执行器，单 worker FIFO，与 watch 循环互斥）；错误码已接入下载、launcher/metadata、server-info/marker 与配置校验路径。剩余：`patch.*` / `unityfs.*`（被引擎阻塞）、`resource.repair`（待引擎独立修复模式）、`task.create`（按设计由语义方法创建）、任务持久化（内存态，重启即失）。Go 层通过 RPC 调用 Rust backend，不走 FFI（FFI 降级说明见 `docs/architecture/official-resource-backend.md` §7）。 2. Go CLI 最小可用入口：`bat doctor`、稳定的 `bat --help` 命令结构，默认通过上述 RPC 或 `bat --json` 进程边界获取同步 report。 3. 官方同步结果接入 CAS + ResourceRepository 的用户级工作流（G-011 剩余部分：自动导入触发、schema 迁移、CLI 查询）。 4. Issue #3（P2）：AssetBundle UnityFS 基础解析校验。 @@ -281,7 +281,7 @@ GitHub issue 状态：#4–#16 已全部关闭（#16 为 daemon status 版本失 立即任务： -1. 按 issue #1 实现 daemon JSON-RPC 协议基础设施和首批最小方法集（`daemon.status`、`daemon.logs`、`resource.sync`、`resource.verify`、`resource.state`、`task.status`、`task.list`），并补齐 backend API 设计文档、任务模型、错误码和 RPC 测试。 +1. Issue #1 收尾：协议基础设施、最小方法集及 `catalog.*`/`task.*` 全量、错误码模型与文档（USERGUIDE §5/§6、架构文档 §7）均已完成；剩余 `patch.*`/`unityfs.*`（待引擎）与任务持久化按后续里程碑推进。 2. 实现 Go CLI 最小框架和 `doctor`，通过 RPC 或 `bat --json` 边界对接 Rust backend。 3. 跟进官方同步长期运行测试，收集并归档运行报告。 4. 开始 AssetBundle parser 的 UnityFS header/block/directory（issue #3），并继续扩展 Addressables catalog 可校验字段（issue #2）。 diff --git a/docs/architecture/official-resource-backend.md b/docs/architecture/official-resource-backend.md index 97f8558..485846a 100644 --- a/docs/architecture/official-resource-backend.md +++ b/docs/architecture/official-resource-backend.md @@ -275,3 +275,42 @@ Linux 生产路径： 4. 是否拒绝镜像域名和手工拼接样例。 5. 是否在下载前做了 URL 和路径安全校验。 6. 是否能在官方客户端变动时只改适配层。 + +## 7. RPC Backend API 与 Go 调用边界 + +daemon（`bat --daemon`）在 `/bat.sock` 上提供 Unix socket +JSON-RPC 2.0 服务，是面向上层服务（Go 层）的**主要跨语言边界**。 + +### 7.1 协议契约 + +- 应用层统一 envelope（装入 JSON-RPC `result`）：`ok` / `status` / + `data` / `error` / `request_id`；传输层解析失败走 JSON-RPC 顶层 + `error`（-32700）。 +- `error` 为统一 `ApiError`：`code`（`BAT-ERR-<6 位>`）、`kind`、 + `domain`、`location`、`message`、`retryable`。码表以 + `core/src/error_code.rs` 为准。 +- 长任务（`resource.sync` / `resource.verify` / `catalog.refresh`） + 入队即返回 `task_id`，经 `task.status` / `task.list` / `task.logs` + 轮询，`task.cancel` 协作式取消。任务执行器是单 worker FIFO，与 + watch 循环经进程内锁互斥。 +- 方法命名空间与实现状态、请求/响应示例见 `USERGUIDE.md` §6： + `daemon.*` / `resource.*` / `catalog.*` / `task.*` 已实现； + `patch.*` / `unityfs.*` 待引擎；`task.create` / `resource.repair` + 按设计暂缓。 + +### 7.2 Go 层职责边界 + +- Go 层负责：BlueArchive 客户端请求处理、HTTP API、鉴权、内容分发， + 以及作为 RPC client 调用本机 daemon（连接 `bat.sock`，每行一个 + JSON-RPC 请求/响应）。 +- Rust daemon 负责：官方资源自动拉取与校验、catalog 更新检查、 + 版本状态与发布、任务队列/日志/错误/进度管理等长期状态型工作。 +- Go 层**不**直接嵌入 Rust FFI，不直接读写 daemon 的状态文件与资源 + 目录内部结构；跨语言交互只经 RPC 契约。 + +### 7.3 FFI 的定位（降级说明） + +`bat-ffi` crate（cgo 头文件 + 静态/动态库链接，见 `Makefile` 的 +`build-ffi` / `build-go`）**降级为可选的历史兼容边界**：保留用于既有 +cgo 试验路径与本地工具，不再作为 Go 服务层的主要集成方式，也不会按 +RPC 契约的节奏扩展。新能力一律先落 RPC 方法。