mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 07:06:43 +08:00
nyaKazuha
b4b4f25cb3
将 bat-ffi 明确收敛为无状态 C ABI 兼容层，默认集成路径改为 bat --json 进程边界或未来稳定 SDK。 同步 README、当前状态、项目计划、架构文档、开发指南和缺口清单，移除 FFI 作为主集成边界的表述。 新增 AGENTS.md 和 CONTRIBUTING.md，压缩 CLAUDE.md 为兼容入口，并归档阶段性报告、同步 .gitignore 规则。
80 lines
3.1 KiB
Markdown
80 lines
3.1 KiB
Markdown
# ADR 0001: Rust 引擎与 Go 应用层边界
|
||
|
||
**状态**：已接受
|
||
**日期**：2026-06-28
|
||
**关联计划**：`../../../PROJECT_PLAN.md`
|
||
|
||
---
|
||
|
||
## 背景
|
||
|
||
BlueArchiveToolkit 的最终目标覆盖资源同步、CAS、AssetBundle 解析、文本提取、翻译、Patch、CLI、API Server、Web 和 SDK。项目天然包含二进制解析、文件完整性、网络同步、任务编排、数据库、用户界面等不同类型的问题。
|
||
|
||
如果所有能力都堆在一种语言或一个模块里，后续会出现以下问题：
|
||
|
||
1. 性能敏感和安全敏感代码难以隔离测试。
|
||
2. CLI/API/Web 编排逻辑容易污染底层解析器。
|
||
3. FFI 和 SDK 边界无法稳定。
|
||
4. 插件系统没有清晰接入点。
|
||
|
||
---
|
||
|
||
## 决策
|
||
|
||
采用明确的语言和层次边界：
|
||
|
||
1. **Rust 引擎层**
|
||
- 负责 CAS、AssetBundle、Patch、二进制格式解析、Hash、完整性校验。
|
||
- 只暴露粗粒度、可测试、稳定的 API。
|
||
- 不承担 CLI 命令解析、HTTP 路由、AI Provider 编排或 Web 状态管理。
|
||
|
||
2. **Rust 领域/适配层**
|
||
- `core` 保存领域模型、仓储接口和领域错误。
|
||
- `adapters` 保存 Unity、Manifest、Client 等适配器接口和注册机制。
|
||
- `infrastructure` 将引擎实现适配到领域仓储接口。
|
||
|
||
3. **Go 应用层**
|
||
- 负责 CLI、资源同步、下载器、API Server、任务调度、配置、日志、Provider 编排。
|
||
- 通过稳定 SDK 或进程边界调用 Rust 能力；FFI 只作为可选兼容层。
|
||
- 不重复实现 AssetBundle 解析、Patch 算法或 CAS 对象存储核心逻辑。
|
||
|
||
4. **Web 层**
|
||
- 通过 REST API 访问服务端能力。
|
||
- 不直接读取本地 CAS 或游戏资源文件。
|
||
|
||
---
|
||
|
||
## 约束
|
||
|
||
1. Rust 引擎 API 必须保持业务无关，不出现 CLI 命令、HTTP 状态码、Web 页面状态。
|
||
2. Go 应用层不得复制 Rust 引擎中的 Hash、Patch、AssetBundle 核心算法。
|
||
3. 跨边界优先级应是进程边界或稳定 SDK，其次才是 FFI；若使用 FFI，必须只暴露粗粒度、无状态、一次调用一次输入输出的兼容 API。
|
||
4. 所有跨边界错误必须能映射到统一错误码和可读诊断信息。
|
||
|
||
---
|
||
|
||
## 后果
|
||
|
||
正面影响：
|
||
|
||
1. 核心引擎可以独立测试和基准测试。
|
||
2. CLI/API/Web 可以复用同一套底层能力。
|
||
3. 后续新增 Provider、Parser、Storage backend 时边界更清晰。
|
||
|
||
代价：
|
||
|
||
1. 需要维护进程、SDK 和可选 FFI 兼容边界。
|
||
2. 错误类型、数据结构和版本兼容性需要更早设计。
|
||
3. 集成测试必须覆盖跨语言调用，而不能只看单 crate 单元测试。
|
||
|
||
---
|
||
|
||
## 当前执行要求
|
||
|
||
近期实现 CAS 时必须遵守：
|
||
|
||
1. `crates/bat-cas-engine` 是 CAS 核心实现位置。
|
||
2. `infrastructure` 不再复制 CAS 存储算法，只做 `bat-core::repositories::CasRepository` 适配。
|
||
3. Go CLI 后续默认通过 `bat --json` 进程边界或稳定 SDK 调用 Rust 能力，不直接操作 CAS 内部目录结构。
|
||
4. `bat-ffi` 只能保持为可选无状态兼容层，不能承担 daemon lifecycle、下载器状态、资源锁或 CAS handle。
|