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 方法。