BlueArchiveToolkit/docs/reference/rpc-backend-api.md

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 暴露到公网。

请求：

{"jsonrpc":"2.0","id":1,"method":"resource.repair","params":null}

成功响应的 JSON-RPC 顶层 result 一律是应用层 envelope：

{
  "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 中：

{
  "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	不开放通用任务入口；由语义方法创建任务。

任务记录：

{
  "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 作为常规调用路径。