feat(rpc): 完成 issue #1 Go 调用边界

2026-09-18 06:34:54 +08:00 · 2026-07-24 17:58:34 +08:00
parent ecda08ed97
commit 102b49b666
20 changed files with 1011 additions and 34 deletions
@@ -189,7 +189,7 @@

 集成边界：

-1. 当前生产集成路径是运行 `bat --json` 并消费结构化 report；未来 Go CLI 若继续作为产品入口，也应优先使用该进程边界或 daemon RPC。
+1. 当前生产集成路径是 Rust `bat --watch` / `bat --daemon` 持久运行；Go `bat-api` 应优先通过 `internal/backendrpc` 调用 daemon RPC，one-shot/fallback 场景才运行 `bat --json` 并消费结构化 report。
 2. systemd、容器或上层 Go 进程只负责守护 `bat --watch` / `bat --daemon`，不直接接管下载器内部状态。
 3. `bat-ffi` 只允许作为可选无状态 C ABI 兼容层，用于 Manifest inspect 和 sync plan 这类一次性 JSON helper；它不是官方同步 daemon、下载器、资源锁、CAS handle 或主控制面的承载位置。

@@ -280,6 +280,7 @@ Linux 生产路径：

 daemon（`bat --daemon`）在 `<state-dir>/bat.sock` 上提供 Unix socket
 JSON-RPC 2.0 服务，是面向上层服务（Go 层）的**主要跨语言边界**。
+稳定方法、schema 和错误语义以 `docs/reference/rpc-backend-api.md` 为准。

 ### 7.1 协议契约

@@ -304,8 +305,9 @@ JSON-RPC 2.0 服务，是面向上层服务（Go 层）的**主要跨语言边
 ### 7.2 Go 层职责边界

 - Go 层负责：BlueArchive 客户端请求处理、HTTP API、鉴权、内容分发，
-  以及作为 RPC client 调用本机 daemon（连接 `bat.sock`，每行一个
-  JSON-RPC 请求/响应）。当前 Go 产品入口尚未完成，`cmd/bat` 仍是试验骨架。
+  以及通过 `internal/backendrpc` 作为 RPC client 调用本机 daemon
+  （连接 `bat.sock`，每行一个 JSON-RPC 请求/响应）。当前 Go 产品入口
+  尚未完成，`cmd/bat` 仍是试验骨架。
 - Rust daemon 负责：官方资源自动拉取与校验、catalog 更新检查、
  版本状态与发布、任务队列/日志/错误/进度管理等长期状态型工作。
 - Go 层**不**直接嵌入 Rust FFI，不直接读写 daemon 的状态文件与资源
@@ -43,8 +43,8 @@ go vet ./...

 说明：

-1. 当前已有 `cmd/bat` 和 `internal/ffi` 骨架，但没有 Go 产品级测试覆盖；`go test ./...` 出现 `[no test files]` 不代表 CLI/API 已完成。
-2. 如果后续新增 Go 产品 package，必须让 `go test ./...` 和 `go vet ./...` 纳入硬性验证。
+1. 当前已有 `internal/backendrpc` fake socket 单测、`cmd/bat` 试验骨架和 `internal/ffi` 兼容包装；这些不代表 CLI/API 产品入口已完成。
+2. 后续新增 Go 产品 package，必须让 `go test ./...` 和 `go vet ./...` 纳入硬性验证。
 3. 当前 `golangci-lint` 可选；当 Go 代码进入主要开发阶段后，应纳入本地门禁。
 4. 官方同步相关修改必须额外运行 `cargo test -p bat-infrastructure --bin bat -- --nocapture`。

@@ -145,7 +145,7 @@ go test ./...
 go vet ./...
 ```

-Go 产品入口尚未完成，但仓库已有 `cmd/bat` 与 `internal/ffi` 骨架。提交前应运行 `go test ./...` 和 `go vet ./...`；目前输出可能只有 `[no test files]`，这代表缺少 Go 产品测试覆盖，不代表 Go CLI 已完成。
+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 已完成。

 ### 常用聚焦命令

@@ -160,7 +160,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 产品入口和生产同步默认应通过 Rust `bat --json` 或 daemon RPC 进程边界集成。
+`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` 进程边界。

 ### 集成测试

@@ -0,0 +1,169 @@
+# Rust Resource Backend RPC API
+
+本文档冻结本机 Rust Resource Backend API 的稳定调用边界。Go 项目
+`bat-api`、Go 服务层、运维脚本和 `bat` CLI 都应以这里的 JSON-RPC
+contract 为准，不应绕过 daemon 状态文件或扩展 `bat-ffi` 作为主路径。
+
+## 传输
+
+- 传输：Unix domain socket。
+- 默认 socket：`/tmp/bat-pid/bat.sock`。
+- 协议：JSON-RPC 2.0，每行一个 request，每行一个 response。
+- 编码：UTF-8 JSON。
+- 访问控制：依赖本机文件权限和状态目录权限；不要把 socket 暴露到公网。
+
+请求：
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"resource.repair","params":null}
+```
+
+成功响应的 JSON-RPC 顶层 `result` 一律是应用层 envelope：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "ok": true,
+    "status": "accepted",
+    "data": {"task_id": "task-1234-1", "kind": "resource.repair"},
+    "request_id": "req-1234-1"
+  }
+}
+```
+
+应用层失败也放在 `result` 的 envelope 中：
+
+```json
+{
+  "ok": false,
+  "status": "error",
+  "error": {
+    "code": "BAT-ERR-700003",
+    "kind": "not_implemented",
+    "domain": "rpc",
+    "location": "rpc.dispatch",
+    "message": "方法尚未实现：daemon.clean-stable",
+    "retryable": false
+  },
+  "request_id": "req-1234-2"
+}
+```
+
+只有 JSON 解析失败等传输层错误使用 JSON-RPC 顶层 `error`。
+
+## Envelope
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `ok` | bool | 应用层是否成功。 |
+| `status` | string | `ok`、`accepted` 或 `error`。 |
+| `data` | object/null | 成功结果。失败时省略。 |
+| `error` | object/null | `ApiError`。成功时省略。 |
+| `request_id` | string | daemon 进程内请求 ID，用于日志关联。 |
+
+`ApiError` 结构以 `core/src/error_code.rs` 码表为准：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `code` | string | `BAT-ERR-<6位>`。 |
+| `kind` | string | 错误类别。 |
+| `domain` | string | 错误域。 |
+| `location` | string | Rust 侧出错位置。 |
+| `message` | string | 可诊断错误信息。 |
+| `retryable` | bool | 调用方是否可以按策略重试。 |
+
+## 方法
+
+### daemon
+
+| 方法 | 状态 | params | data |
+|---|---|---|---|
+| `daemon.status` | 已实现 | `null` | 后台状态报告。 |
+| `daemon.logs` | 已实现 | `{ "tail": 200 }` | 日志尾部报告。 |
+| `daemon.stop` | 已实现 | `null` | accepted ack。 |
+| `daemon.reload` | 已实现 | `null` | accepted ack。 |
+| `daemon.refresh` | 已实现 | `{ "force": false }` | accepted ack。 |
+| `daemon.doctor` | 已实现 | `null` | 只读诊断报告。 |
+| `daemon.restart` | 保留 | `null` | live RPC 不执行；由 CLI 生命周期入口处理。 |
+| `daemon.clean-stable` | 保留 | `null` | live RPC 不执行；由 CLI 离线清理入口处理。 |
+
+`bat.status`、`bat.stop`、`bat.reload`、`bat.refresh`、`bat.logs`、
+`bat.doctor`、`bat.clean-stable` 是兼容别名；新代码应使用 `daemon.*`。
+
+### resource
+
+| 方法 | 状态 | params | data |
+|---|---|---|---|
+| `resource.state` | 已实现 | `null` | 资源发布根、版本状态、上次同步结果。 |
+| `resource.sync` | 已实现 | `{ "force": false }` | `{ "task_id": "...", "kind": "resource.sync" }`。 |
+| `resource.verify` | 已实现 | `null` | `{ "task_id": "...", "kind": "resource.verify" }`。 |
+| `resource.repair` | 已实现 | `null` | `{ "task_id": "...", "kind": "resource.repair" }`。 |
+| `resource.manifest` | 已实现 | `{ "offset": 0, "limit": 100 }` | 当前 download manifest 分页。 |
+| `resource.list` | 已实现 | `{ "offset": 0, "limit": 100 }` | `resource.manifest` 的兼容别名。 |
+
+`resource.repair` 会开启本地 manifest audit + repair，不继承 `force`。
+`limit` 范围是 `1..=1000`，非法参数返回 `BAT-ERR-700002`。
+
+### catalog
+
+| 方法 | 状态 | params | data |
+|---|---|---|---|
+| `catalog.status` | 已实现 | `null` | 当前已发布 catalog 概览。 |
+| `catalog.versions` | 已实现 | `null` | current / in_progress / previous / failed。 |
+| `catalog.diff` | 已实现 | `null` | 当前 snapshot 相对上一可用版本的差异。 |
+| `catalog.refresh` | 已实现 | `{ "force": false }` | `{ "task_id": "...", "kind": "catalog.refresh" }`。 |
+
+只读查询在没有可用版本时返回 `ok=true` 且 `data.available=false`。
+
+### task
+
+| 方法 | 状态 | params | data |
+|---|---|---|---|
+| `task.status` | 已实现 | `{ "task_id": "..." }` | 单个任务记录。 |
+| `task.list` | 已实现 | `null` | `{ "tasks": [...] }`。 |
+| `task.cancel` | 已实现 | `{ "task_id": "..." }` | cancel ack。 |
+| `task.logs` | 已实现 | `{ "task_id": "..." }` | `{ "task_id": "...", "lines": [...] }`。 |
+| `task.create` | 保留 | object | 不开放通用任务入口；由语义方法创建任务。 |
+
+任务记录：
+
+```json
+{
+  "id": "task-1234-1",
+  "kind": "resource.repair",
+  "status": "queued",
+  "stage": null,
+  "message": null,
+  "created_at": 1780000000,
+  "updated_at": 1780000000,
+  "started_at": null,
+  "finished_at": null,
+  "error": null,
+  "result": null
+}
+```
+
+`status` 取值：`queued`、`running`、`succeeded`、`failed`、`cancelled`。
+daemon 重启后仍处于 `queued` 或 `running` 的历史任务会被标记为
+`failed`，错误码为 `BAT-ERR-700005`。
+
+### patch / unityfs
+
+`patch.*` 和 `unityfs.*` 是已规划命名空间，目前返回
+`BAT-ERR-700003`。它们依赖后续 `bat-patch`、`bat-assetbundle`
+引擎，不作为 issue #1 的关闭阻塞项。
+
+## Go 调用边界
+
+`bat-api` 应直接调用本 RPC contract，不通过 `exec` 调用 `bat` binary。
+`bat` binary 是人类 CLI 和进程生命周期工具；默认 `refresh` / `repair`
+在 daemon 可用时也会作为 RPC client 调用同一个 socket。
+
+禁止事项：
+
+- Go 服务层不直接读写 `bat-status.json`、`bat-tasks.json` 等 daemon 内部状态文件。
+- Go 服务层不扩展 `bat-ffi` 为主控制面。
+- Go 服务层不通过 stdout 解析 `bat status --json` 作为常规调用路径。
+
@@ -177,14 +177,14 @@
 现象：

 - 当前可用的用户同步/运维入口是 Rust `bat` binary。
- `cmd/bat` 已存在，但仅有 `doctor`、`manifest inspect`、`sync plan` 试验能力；`doctor` 只输出固定 `ok`，`manifest`/`sync` 依赖可选 CGO/FFI helper。
+- `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 写成已完成。

 验收：

 - `cmd/bat doctor` 做真实环境诊断，而不是固定字符串。
- `cmd/bat sync` 能通过 Rust `bat --json` 或 RPC 触发/查询官方同步，不走 FFI 控制下载器或 daemon。
+- `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 边界。

@@ -471,7 +471,7 @@
 ## 6. 当前关闭顺序建议

 1. issue #24：失败 staging 复用已补离线回归；继续核对 issue 口径、状态与后续是否仍有真实场景无法复现的残余。
-2. issue #1：Rust daemon/backend API 边界收口；`resource.repair`、`resource.list`、`daemon.doctor` 已补齐，剩余确认 `patch.*` / `unityfs.*`（待引擎）、`task.create`（暂不开放通用入口）以及 `daemon.restart` / `daemon.clean-stable`（CLI 生命周期入口）的 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` 引擎级解析。