docs: 对齐 RPC 接口文档
bat-rust / Build and test Rust (push) Canceled after 0s
bat-rust / Build and test Go API (push) Canceled after 0s

This commit is contained in:
2026-08-03 11:47:51 +08:00
parent 7c863d10d1
commit a2e2ae8ac5
4 changed files with 64 additions and 48 deletions
+38 -5
View File
@@ -353,14 +353,47 @@ CLI 对应关系:
| `bat parse-status` | `parse.status` |
| `bat parse-text-units` | `parse.text_units` |
| `bat parse-errors` | `parse.errors` |
| `bat translation-tasks` | `translation.tasks` |
| `bat translation-handoff` | `translation.handoff` |
| `bat localized-status` | `localized.status` |
| `bat resource-index` | `resource.index` |
`bat resource-index` 支持 `--offset``--limit``--resource-type``--hash`
`--path-pattern``bat parse-text-units` / `bat parse-errors` 支持
`--offset``--limit``--destination``--archive-entry``--path-id`
`--class-id``--field-path``--format`;这些过滤参数不适用于
`parse-status``localized-status`
`bat resource-index` 支持 `--offset``--limit``--resource-type``--hash`
`--path-pattern``--release-id``--platform``--destination`
`--bundle-path``--archive-entry``--parse-status``--format`
`bat parse-text-units` / `bat parse-errors` 支持 `--offset``--limit`
`--destination``--path-pattern``--archive-entry``--path-id`
`--class-id``--field-path``--format``bat translation-tasks` 支持
`--offset``--limit``--task-id``--release-id``--destination`
`--path-pattern``--archive-entry``--task-status``--worker-status`
`--parse-status``--format``--has-reason``--has-failure-reason`。这些过滤参数不适用于
`parse-status``translation-handoff``localized-status`
### Go 客户端表面
`internal/backendrpc.Client` 是 Unix socket JSON-RPC 传输客户端:
- `Call` 可发送本文档中的任意已记录方法,并负责 JSON-RPC transport、
envelope 和 `ApiError` 解码;它不是 bat-api 的 HTTP 任意 RPC proxy。
- typed helper 已覆盖 daemon 已实现方法(`status/logs/stop/restart/reload/refresh/doctor`)、
`resource.state/sync/verify/repair/manifest/list``catalog.*``parse.*`
`localized.status``task.*` 和三个
`unityfs.patch_*` 方法。
- `resource.index``translation.tasks``translation.handoff`
`translation.task.update``patch.apply` 当前没有专用 typed helper
需要直接使用 `Call`,并仍须遵守本契约的参数和响应定义。
`internal/api` 对 bat-api 生产路径进一步收窄接口:
| Go 接口 | 允许调用的 RPC | 用途 |
|---|---|---|
| `Backend` | `daemon.status``daemon.doctor``resource.state``catalog.status``resource.manifest` | 启动发现、周期刷新和资源分发 |
| `ControlBackend` | `daemon.restart``daemon.reload``daemon.refresh``resource.sync``resource.verify``resource.repair``catalog.refresh` | 鉴权后的管理控制白名单 |
`daemon.stop``daemon.clean-stable` 和任意通用 RPC 不属于 bat-api 管理控制面。
Rust dispatch、Go transport 和 bat-api 接口的权威实现位置分别是
`infrastructure/src/bin/bat/app.rs``internal/backendrpc/client.go`
`internal/api/rpc_release.go`;修改方法、字段或 allowlist 时必须同步更新本文档。
Go mirror contract fixture 固化在 `internal/api/testdata/contract/`,覆盖
`catalog.status` available/unavailable、`resource.manifest` page0 和对应