nyaKazuha/BlueArchiveToolkit
1
0
Fork 0
mirror of https://github.com/Yuyi-Oak/BlueArchiveToolkit.git synced 2026-07-22 01:15:14 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

refactor(ffi): 降级 FFI 为可选兼容层并整理文档

Browse Source 
将 bat-ffi 明确收敛为无状态 C ABI 兼容层，默认集成路径改为 bat --json 进程边界或未来稳定 SDK。

同步 README、当前状态、项目计划、架构文档、开发指南和缺口清单，移除 FFI 作为主集成边界的表述。

新增 AGENTS.md 和 CONTRIBUTING.md，压缩 CLAUDE.md 为兼容入口，并归档阶段性报告、同步 .gitignore 规则。
This commit is contained in:
nyaKazuha
2026-07-15 21:12:17 +08:00
parent 90307a3243
commit b4b4f25cb3
22 changed files with 420 additions and 772 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PROJECT_PLAN.md
+10 -10
View File
@@ -15,7 +15,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
2. **Rust 核心引擎**：负责 CAS、AssetBundle 解析、Patch、二进制安全处理和性能敏感逻辑。
3. **Go 服务层**：负责 CLI 编排、资源同步、下载器、API Server、任务调度和外部集成。
4. **Web 管理后台**：负责翻译审核、术语管理、全文搜索、历史版本、Diff 和 Dashboard。
5. **SDK/API**：提供稳定的 Go SDK、进程边界或必要时的 FFI 边界和 REST/OpenAPI 接口，方便其他工具复用。
5. **SDK/API**：提供稳定的 Go SDK、进程边界和 REST/OpenAPI 接口，方便其他工具复用；FFI 仅保留为可选兼容层。
6. **插件系统**：允许新增解析器、翻译 Provider、存储后端、Patch 算法，而不修改核心代码。
---
@@ -33,14 +33,14 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
5. `bat-infrastructure` 已改为 CAS 仓储适配层，不再重复实现对象存储。
6. `bat-infrastructure` 已提供官方资源 pull/update 服务，正式入口是 Rust binary `bat`。
7. `bat` 支持 `--auto-discover`、`--watch`、`--daemon`、默认 1 小时间隔、本地 manifest audit/repair、官方 seed `.hash` 校验、snapshot/cache，以及基于 Unix socket JSON-RPC 的 `status/stop/restart/reload/refresh/logs/verify/repair/doctor/clean-stable` 运维命令。
8. `bat-ffi` 已提供 Manifest inspect 和官方 sync plan 的粗粒度 JSON API。
8. `bat-ffi` 已提供 Manifest inspect 和官方 sync plan 的可选无状态粗粒度 JSON C ABI helper。
9. 文档已整理：根目录保留入口文档，历史报告进入 `docs/reports/historical/`，误嵌套的 `docs/docs` 已合并。
### 仍是骨架或占位
1. AssetBundle 解析器仍是占位 trait，未解析 UnityFS、压缩块、TypeTree 或对象表。
2. Patch 的 Binary/JSON 模块仍返回空结果，不具备真实补丁能力。
3. Go CLI/API/SDK 仍没有产品级入口；只有 `internal/ffi` 的早期包装。
3. Go CLI/API/SDK 仍没有产品级入口；只有 `internal/ffi` 的可选兼容包装骨架。
4. Addressables parser 已覆盖当前真实形态 fixture/golden，但还不是完整 Unity Addressables/SBP catalog 兼容层。
5. 官方同步结果尚未作为用户级流程自动导入 CAS + ResourceRepository。
6. 真实官方网络全量下载 smoke test 尚未记录。
@@ -66,11 +66,11 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
2. **Engine**：Rust 实现性能敏感和安全敏感能力，包括 CAS、AssetBundle、Patch、二进制格式校验。
3. **Infrastructure**：实现数据库、文件系统、缓存、对象存储、HTTP 客户端、任务队列。
4. **Application**：编排用例，例如同步资源、提取文本、生成补丁、审核翻译。
5. **Interface**：CLI、REST API、Web UI、SDK、FFI。
5. **Interface**：CLI、REST API、Web UI、SDK，以及可选 FFI 兼容层。
### 3.2 技术决策
1. **Rust**：保留为核心引擎语言，用于 CAS、AssetBundle、Patch、完整资源拉取和更新检查核心逻辑，FFI 仅作为可选边界。
1. **Rust**：保留为核心引擎语言，用于 CAS、AssetBundle、Patch、完整资源拉取和更新检查核心逻辑；`bat --json` 进程边界是当前主集成路径，FFI 仅作为可选兼容层。
2. **Go**：用于最小稳定 CLI、服务编排、API Server、任务编排、Provider 集成；不强制要求 Rust 核心能力必须写成库供 Go 调用。
3. **PostgreSQL**：作为服务端主数据库，承载翻译记忆库、术语库、任务、审核和用户权限。
4. **SQLite**：仅作为本地 CLI 可选元数据后端，必须通过仓储抽象隔离，不能绑定业务逻辑。
@@ -141,7 +141,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
**目标**：完成可长期使用的 Content Addressable Storage。
**当前状态**：已完成 CAS V1。Go CLI 以最小稳定入口优先，Rust 继续承载完整资源拉取与更新检查核心逻辑；FFI 边界保持可选。
**当前状态**：已完成 CAS V1。Go CLI 以最小稳定入口优先，Rust 继续承载完整资源拉取与更新检查核心逻辑；`bat-ffi` 仅保留为可选兼容层。
交付物：
@@ -150,7 +150,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
3. 实现引用计数、对象元数据、完整性校验、GC、统计信息。
4. 实现本地元数据后端：优先 SQLite，但必须隔离在 repository adapter 中。
5. 编写迁移、恢复、损坏检测和 `doctor cas`。
6. 提供稳定的 Go 调用边界，优先进程或 SDK，必要时再补 FFI。
6. 提供稳定的 Go 调用边界，优先进程或 SDK；FFI 只保留为可选兼容层，不作为默认集成方案。
验收标准：
@@ -175,7 +175,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
3. Rust 官方下载器：**已完成当前生产入口需要的核心能力**。包含官方 URL 校验、`.part` 续传、重试、本地 manifest size+BLAKE3 校验、官方 seed `.hash` 校验和 repair。
4. Rust 自动更新入口：**已完成当前生产入口**。`bat` 支持 snapshot、marker diff、bootstrap cache、one-shot、`--watch`、`--daemon`、默认 1 小时间隔、北京时间固定强制刷新，以及 Unix socket JSON-RPC 后台运维命令返回。
5. Go CLI：**未完成**。需要实现 `bat doctor`、`bat sync --help`、Rust 官方同步命令包装和 JSON/human 输出。
6. 用户级 `sync`、`manifest inspect`、`cache status`：**未完成**。Rust FFI 已提供 Manifest inspect 和 sync plan JSON 边界，但 Go CLI 尚未串联。
6. 用户级 `sync`、`manifest inspect`、`cache status`：**未完成**。Rust `bat --json` 是 Go CLI 默认进程边界；`bat-ffi` 只提供可选兼容用的 Manifest inspect 和 sync plan JSON helper。
7. 下载结果写入 CAS + ResourceRepository：**部分完成**。CAS 和 SQLite ResourceRepository 已存在，官方同步入口尚未把完整下载结果作为用户级流程自动导入。
8. Linux 生产同步不依赖已安装官方启动器：**已完成当前 Rust 入口**。`--auto-discover` 只使用官方 HTTP metadata 和临时目录解析 `GameMainConfig`。
9. 真实官方网络全量下载 smoke test：**未完成记录**。需要在隔离目录执行并记录 dry-run、首次下载、二次 up-to-date 和本地损坏 repair。
@@ -381,7 +381,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
## 6. 近期 10 个具体任务
1. 落地 Go CLI 的最小生产入口：`bat doctor`、`bat sync --help`、`bat official sync --help`。
2. 让 Go CLI 能调用 Rust `bat --json` 官方同步入口或 FFI/进程边界，并稳定转发结构化 report。
2. 让 Go CLI 默认调用 Rust `bat --json` 官方同步入口，并稳定转发结构化 report；除非有明确兼容需求，不走 FFI。
3. 记录一次真实官方网络 smoke：dry-run、首次下载、二次 up-to-date、本地损坏 repair。
4. 将官方同步下载结果接入 CAS + `SqliteResourceRepository` 的用户级流程。
5. 继续扩展 Addressables parser 的真实 catalog 变体覆盖和错误诊断。
@@ -416,7 +416,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付
1. Rust 提供稳定引擎能力，不承担 CLI 编排，但负责完整资源拉取和更新检查的核心逻辑。
2. Go 负责用户命令、最小稳定 CLI、服务编排、网络和 Provider。
3. 跨边界优先进程或 SDK，FFI 只作为可选的粗粒度、安全、可测试 API。
3. 跨边界优先进程或 SDK，FFI 只作为可选的粗粒度、无状态、安全、可测试兼容 API。
4. Rust 不需要被强制写成 Go 调用库；当前 `bat --watch` / `bat --daemon` 是允许长期运行的 Rust 生产任务。
### 官方资源真实下载风险