BlueArchiveToolkit/PROJECT_PLAN.md

BlueArchiveToolkit 完整开发计划

• 项目名称：BlueArchiveToolkit
• 文档版本：2026-07-20 状态收口版
• 权威状态：以本文档和 CURRENT_STATUS.md 为准，旧阶段报告仅作历史参考。
• 最终目标：构建一个可长期维护、可扩展、可审计的 Blue Archive 资源管理、文本提取、翻译和补丁平台。

---

1. 产品边界

BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付形态包含：

1. CLI 工具：面向本地用户和自动化任务，覆盖 doctor、sync、manifest、bundle、extract、translate、patch、verify、cache、serve 等命令。
2. Rust 核心引擎：负责 CAS、AssetBundle 解析、Patch、二进制安全处理和性能敏感逻辑。
3. Go 服务层：负责 CLI 编排、资源同步、下载器、API Server、任务调度和外部集成。
4. Web 管理后台：负责翻译审核、术语管理、全文搜索、历史版本、Diff 和 Dashboard。
5. SDK/API：提供稳定的 Go SDK、进程边界和 REST/OpenAPI 接口，方便其他工具复用；FFI 仅保留为可选兼容层。
6. 插件系统：允许新增解析器、翻译 Provider、存储后端、Patch 算法，而不修改核心代码。

---

2. 当前真实状态

本节来自 2026-07-20 的工作区盘点、本地验证和最新功能提交。

已具备

1. Rust workspace 已存在，包含 core、adapters、infrastructure、crates/bat-cas-engine、crates/bat-assetbundle、crates/bat-patch、crates/bat-ffi。
2. bat-core 已定义领域对象和仓储接口。
3. bat-adapters 已实现 Unity、Manifest、Client 集成的框架和注册表。
4. bat-cas-engine 已完成 CAS V1：原子写入、BLAKE3 Hash、SQLite 引用计数、GC、并发测试、损坏检测。
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 C ABI helper。
9. 文档已整理：根目录保留入口文档，历史报告进入 docs/reports/historical/，误嵌套的 docs/docs 已合并。

仍是骨架或占位

1. bat-assetbundle 仍是占位 crate；完整 UnityFS、压缩块、TypeTree 或对象表解析未完成。
2. bat-patch 的 Binary/JSON 模块仍返回明确的未实现错误，不具备真实补丁能力。
3. Go CLI/API/SDK 仍没有产品级入口；当前只有 cmd/bat 与 internal/ffi 的试验/兼容骨架。
4. Addressables parser 已覆盖当前真实形态 fixture/golden，但还不是完整 Unity Addressables/SBP catalog 兼容层。
5. 官方同步结果尚未作为用户级流程自动导入 CAS + ResourceRepository。
6. 真实官方网络全量下载 smoke 已固化为可重复脚本和 runbook（G-018 已关闭）；真实运行记录处于长期运行测试阶段，报告待后续提供。
7. Web、数据库迁移、OpenAPI、插件加载机制尚未实现。
8. 原 Git 历史未恢复；当前仓库以新初始化基线为准。

已验证

1. cargo test --workspace --quiet 通过。
2. cargo clippy --workspace --all-targets -- -D warnings 通过。
3. go test ./... 通过，但目前没有 Go 产品级测试覆盖。
4. go vet ./... 通过。
5. go build -o /tmp/bat-go-cli ./cmd/bat 通过。
6. target/debug/bat --help 可用。

---

3. 架构原则

3.1 分层边界

1. Domain/Core：只表达业务模型、领域服务、仓储接口和稳定错误类型，不依赖数据库、文件系统、网络或 UI。
2. Engine：Rust 实现性能敏感和安全敏感能力，包括 CAS、AssetBundle、Patch、二进制格式校验。
3. Infrastructure：实现数据库、文件系统、缓存、对象存储、HTTP 客户端、任务队列。
4. Application：编排用例，例如同步资源、提取文本、生成补丁、审核翻译。
5. Interface：CLI、REST API、Web UI、SDK，以及可选 FFI 兼容层。

3.2 技术决策

1. Rust：保留为核心引擎语言，用于 CAS、AssetBundle、Patch、完整资源拉取和更新检查核心逻辑；bat --json 进程边界是当前主集成路径，FFI 仅作为可选兼容层。
2. Go：用于最小稳定 CLI、服务编排、API Server、任务编排、Provider 集成；不强制要求 Rust 核心能力必须写成库供 Go 调用。
3. PostgreSQL：作为服务端主数据库，承载翻译记忆库、术语库、任务、审核和用户权限。
4. SQLite：仅作为本地 CLI 可选元数据后端，必须通过仓储抽象隔离，不能绑定业务逻辑。
5. Redis：用于服务端缓存、任务状态、限流和短期锁。
6. Vue 3 + TypeScript：用于 Web 管理后台。

3.3 质量门槛

每个生产模块必须满足：

1. 无占位返回、无静默吞错、无未说明的 TODO。
2. 公共接口具备文档、错误语义和兼容性说明。
3. 单元测试覆盖核心分支；跨模块能力补集成测试。
4. cargo fmt、cargo clippy --workspace --all-targets -- -D warnings、cargo test --workspace 通过。
5. Go 模块落地后，go test ./...、go vet ./... 通过。
6. 用户可见命令必须有 doctor 检查和失败恢复建议。

---

4. 总体里程碑

Milestone 0：工作区基线修复

目标：让项目状态可信、入口清晰、验证命令不会误报。

交付物：

1. 整理根目录报告和历史文档。
2. 建立 PROJECT_PLAN.md、CURRENT_STATUS.md、DOCS_INDEX.md 三个权威入口。
3. 显式列出 Rust workspace 成员。
4. 修复 Makefile 在 Go 空目录阶段的行为。
5. 恢复或重新初始化 Git 元数据。
6. 建立 ADR 和稳定基线指南。

验收标准：

1. 根目录不再堆放阶段报告。
2. cargo test --workspace 通过。
3. make test 在 Go 尚未实现时能清晰跳过 Go 测试。
4. git status 可用。
5. 架构边界和 CAS V1 边界有文档记录。

当前状态：已完成。

---

Milestone 1：核心模型和接口冻结

目标：冻结第一版稳定领域模型，为后续实现提供不反复摇摆的边界。

交付物：

1. 审查 bat-core 中的 GameClient、GameVersion、Resource、Translation。
2. 完成领域服务模块，不再保留空占位。
3. 固化仓储接口：CAS、Resource、Translation、Glossary、Provider、Patch、Manifest。
4. 统一错误模型和错误码映射策略。
5. 编写架构决策记录：Rust/Go 边界、SQLite/PostgreSQL 边界、插件边界。

验收标准：

1. 公共接口能支撑后续阶段，不暴露具体数据库和文件系统。
2. 领域层不依赖 tokio::fs、SQL、HTTP、UI。
3. 所有领域对象有序列化、校验和测试。

---

Milestone 2：生产级 CAS 与本地元数据

目标：完成可长期使用的 Content Addressable Storage。

当前状态：已完成 CAS V1。Go CLI 产品入口尚未完成，当前仅存在 cmd/bat 的试验骨架；Rust 继续承载完整资源拉取与更新检查核心逻辑；bat-ffi 仅保留为可选兼容层。

交付物：

1. 合并 infrastructure CAS 与 bat-cas-engine 的重复职责。
2. 实现对象写入的临时文件、fsync、原子 rename 和并发安全。
3. 实现引用计数、对象元数据、完整性校验、GC、统计信息。
4. 实现本地元数据后端：优先 SQLite，但必须隔离在 repository adapter 中。
5. 编写迁移、恢复、损坏检测和 doctor cas。
6. 提供稳定的 Go 调用边界，优先进程或 SDK；FFI 只保留为可选兼容层，不作为默认集成方案。

验收标准：

1. 重复写入相同内容只保存一个对象。
2. 对象损坏能被检测并返回明确错误。
3. GC 删除引用计数为 0 的对象。
4. 并发写入和并发读取测试通过。
5. CAS 测试覆盖正常路径、损坏路径、权限路径和并发路径。

---

Milestone 3：Manifest 与资源同步

目标：能够获取、解析和同步 Blue Archive 资源清单。

当前状态：部分完成。Rust 官方日服资源同步链路已经具备正式 one-shot 和 --watch 常驻入口；Go 产品入口、完整解析覆盖、CAS 导入编排和真实线上 smoke 仍待完成。

交付物：

1. Addressables Catalog 真实字段解析：部分完成。当前已覆盖 path、hash、size、address、dependencies、metadata 和真实形态 fixture/golden；仍需继续覆盖更多官方 catalog 结构变体。
2. 资源版本、区域、渠道、远端 URL、Hash、大小、依赖关系模型：部分完成。Resource 和官方 endpoint/snapshot 模型已扩展；仍需冻结 Go CLI/API 可见模型。
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 产品入口：未完成。当前 cmd/bat 仅有 doctor、manifest inspect、sync plan 试验能力，尚不构成产品级 CLI；若要继续由 Go 承担用户入口，需要单独收敛命令集和调用边界。
6. 用户级 sync、manifest inspect、cache status：未完成。Rust bat --json 是当前稳定进程边界；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：命令已固化（G-018 已关闭）。scripts/official-full-pull-smoke.sh / make official-smoke 已固化 dry-run、首次下载、二次 up-to-date 和本地损坏 repair 的可重复流程；真实运行处于长期运行测试阶段，报告待后续提供。

验收标准：

1. 可在无 Web 的情况下通过 CLI 同步指定版本资源。
2. 断点续传和失败重试有可重复测试。
3. Manifest 解析失败时给出可定位的字段和偏移信息。
4. 同一资源跨版本复用同一 CAS 对象。
5. 生产同步入口必须显式选择 --auto-discover 或显式提供官方 server-info URL、connection-group 和 app-version，不得安装或启动 launcher。
6. 自动更新入口必须做到无变化不下载，有变化下载成功后才写入新 snapshot。
7. --watch 模式必须在 Rust 内部保持持久检查能力，外部 supervisor 只负责进程守护。
8. 真实官方网络 smoke 必须记录输出目录、命令、结果摘要和未纳入仓库的大文件位置。

---

Milestone 4：Unity AssetBundle 解析

目标：建立可扩展 AssetBundle 解析框架，并首先支持文本相关资源。

交付物：

1. 解析 UnityFS header、blocks、directory、metadata、objects。
2. 支持 LZ4/LZMA 解压，记录压缩块校验。
3. 实现 TypeTree/ObjectInfo 读取。
4. 实现 TextAsset、MonoBehaviour、ScriptableObject 的可扩展解析入口。
5. 增加解析器注册表和版本适配器。
6. 编写 bundle inspect、bundle extract。

验收标准：

1. 能解析真实样本或明确结构化测试样本。
2. 错误报告包含 bundle 名称、偏移、字段和 Unity 版本。
3. 解析器和业务流程解耦。
4. 不支持的 Unity 版本返回明确错误，不做隐式猜测。

---

Milestone 5：文本提取与标准导出

目标：从资源中提取可翻译文本，并形成稳定中间格式。

交付物：

1. 定义 TextUnit、上下文、来源路径、资源 ID、语言、版本。
2. 实现剧情、UI、系统文本、配置文本的分类规则。
3. 支持 JSONL、CSV、XLIFF 或项目自定义标准格式导出。
4. 实现重复文本合并和上下文保留。
5. 编写 extract text、extract stats。

验收标准：

1. 提取过程不修改原始资源。
2. 同一文本在不同上下文中可区分。
3. 导出格式可往返导入，不丢失资源定位信息。
4. 大资源批量提取有性能基准。

---

Milestone 6：Translation Memory 与 Glossary

目标：建立翻译资产的核心数据库。

交付物：

1. PostgreSQL schema：source_text、translation、translation_memory、glossary、review、history。
2. 实现精确匹配、模糊匹配、上下文匹配。
3. 实现术语优先级、别名、分类、冲突检测和审核状态。
4. 实现导入导出和版本历史。
5. 实现 translate memory、glossary CLI 子命令。

验收标准：

1. 术语优先级高于 AI Provider。
2. 翻译记录保留 Provider、模型、时间、审核人和历史。
3. 模糊匹配阈值可配置且有测试。
4. 数据库迁移可重复执行。

---

Milestone 7：AI 翻译工作流

目标：实现可审计、可替换、可控成本的 AI 翻译流程。

交付物：

1. Provider 抽象：DeepL、OpenAI、Anthropic、Google、Azure、自定义 Provider。
2. 批处理、速率限制、重试、熔断、成本统计。
3. Prompt 模板、术语注入、上下文注入。
4. 自动质量检查：术语一致性、空翻译、占位符保留、长度异常。
5. 人工审核队列和状态流转。

验收标准：

1. Provider 可替换，不影响上层业务。
2. 失败任务可重试且不会重复扣账或覆盖人工审核结果。
3. 每条 AI 翻译可追溯到 Provider、模型和请求配置。
4. 质量检查失败的翻译不会直接进入可发布状态。

---

Milestone 8：Patch 与客户端集成

目标：生成、应用、验证和回滚翻译补丁。

交付物：

1. 实现 Binary Patch、JSON Patch、Text Patch。
2. 定义 Patch manifest：目标版本、文件列表、Hash、签名、回滚信息。
3. 实现客户端发现、路径校验、备份、应用、回滚。
4. 实现 patch build、patch apply、patch rollback、verify。
5. 实现 dry-run 和安全检查。

验收标准：

1. 应用补丁前后都能校验完整性。
2. 任一步失败都能回滚到补丁前状态。
3. 不直接覆盖未经备份的客户端文件。
4. Patch 生成与应用有端到端测试。

---

Milestone 9：CLI、SDK 与 API Server

目标：提供稳定可用的操作入口和集成入口。

交付物：

1. Go CLI 主入口和命令体系。
2. 配置系统：项目级、用户级、环境变量、密钥管理。
3. Go SDK：Manifest、Sync、CAS、Extract、Translate、Patch。
4. REST API Server：认证、权限、统一错误码、OpenAPI。
5. 后台任务系统：同步、提取、翻译、补丁构建。

验收标准：

1. CLI 命令风格统一，支持 JSON 输出和人类可读输出。
2. doctor 能检查依赖、目录权限、数据库连接、资源路径。
3. OpenAPI 与实际 Handler 同步。
4. SDK 不依赖 CLI，不把命令行行为泄漏到库接口。

---

Milestone 10：Web 管理后台

目标：为翻译协作和资源管理提供可用后台。

交付物：

1. 登录、权限、用户角色。
2. Dashboard：同步状态、翻译进度、质量问题、队列状态。
3. 翻译审核：列表、详情、Diff、批量操作。
4. 术语管理：搜索、冲突提示、审核。
5. 资源浏览：版本、资源、Bundle、文本定位。
6. 历史版本和回滚入口。

验收标准：

1. 常用审核流程不需要通过数据库手工操作。
2. 页面状态和 API 错误能被用户理解。
3. 权限隔离覆盖关键写操作。
4. Web 构建、类型检查、基础 E2E 通过。

---

Milestone 11：发布工程与 Alpha

目标：达到可分发、可升级、可诊断的 Alpha 版本。

交付物：

1. 发布验证：format、lint、test、build、security audit、release artifact 由本地可重复命令、自托管 Gitea linux-runner workflow 与脚本承担（决策：不引入 GitHub Workflows 等托管 CI，见 docs/reports/CURRENT_GAPS.md G-017）。
2. Docker Compose：本地开发、服务端部署。
3. 数据备份与恢复文档。
4. 用户文档、开发文档、故障排查文档。
5. 版本策略、迁移策略、兼容性策略。
6. Alpha 发布包。

验收标准：

1. 新环境能按文档完成安装、同步、提取、翻译、补丁流程。
2. 升级不会破坏已有数据。
3. 关键路径有端到端测试。
4. 发布物包含版本号、校验和、变更说明。

---

5. 推荐执行顺序

近期不要直接跳到 Web 或 AI Provider。项目当前的真实瓶颈是 Go 产品入口边界、资源解析、同步结果进入 CAS/ResourceRepository，以及真实端到端验证。

建议顺序：

1. 完成 Milestone 3 剩余项和 Milestone 4，让资源能被同步、索引和解析。
2. 完成 Milestone 5，再开始翻译系统。
3. 完成 Milestone 6 和 7，建立可审计翻译流程。
4. 完成 Milestone 8，形成可交付补丁。
5. 最后补齐 CLI/API/Web/发布工程。

---

6. 近期具体任务

优先完善 Rust bat 后端，并同步收敛 Go 产品入口边界。当前事实是 Rust bat 已承担可用的资源同步/运维入口，Go cmd/bat 仍只是试验骨架，bat-api 是独立的 Go HTTP 服务目标（issue #19 / G-009）：

1. 对 issue #17 做验收并关闭或更新范围：多线程下载与指数退避实现已合入，但 GitHub issue 仍 open。
2. 继续逆向 Addressables catalog，扩大 bundle hash/size/CRC 等可校验字段覆盖（issue #2）。
3. 对 AssetBundle/UnityFS 做引擎级解析：header/block/directory/metadata/object table（issue #3 / G-005）。
4. 将官方同步下载结果接入 CAS + SqliteResourceRepository 的用户级流程（G-011）。
5. 收敛 Go 产品入口：明确继续推进最小 Go CLI，或把用户 CLI 固化为 Rust bat 并把 Go 侧集中到 bat-api。
6. 实现 bat-api（仿官方 API 的 Go HTTP 服务，含鉴权/签名验签，issue #19 / G-009）。
7. 为 CAS 增加 doctor cas 诊断入口。

---

7. 风险与处理策略

SQLite 权限问题

旧 Week 3 报告提到 SQLite 文件权限导致测试失败。处理策略：

1. 本地元数据后端必须使用临时目录和明确权限测试。
2. SQLite 只作为 adapter，不进入领域层。
3. 服务端主库使用 PostgreSQL。
4. 任何数据库测试都必须覆盖路径不存在、只读目录、并发连接和迁移失败。

Blue Archive 资源格式变化

处理策略：

1. Manifest 和 AssetBundle 解析器版本化。
2. 新格式通过 adapter/plugin 增量接入。
3. 样本测试必须记录来源版本和 Unity 版本。

Rust/Go 边界膨胀

处理策略：

1. Rust 提供稳定引擎能力，并在当前阶段承担可生产运行的官方资源同步 CLI、watch 和 daemon。
2. Go 的长期职责包括用户命令、最小稳定 CLI、服务编排、网络和 Provider；当前 Go 产品入口尚未完成，不能把 cmd/bat 试验骨架视为完成。
3. 跨边界优先进程或 SDK，FFI 只作为可选的粗粒度、无状态、安全、可测试兼容 API。
4. Rust 不需要被强制写成 Go 调用库；当前 bat --watch / bat --daemon 是允许长期运行的 Rust 生产任务。

官方资源真实下载风险

处理策略：

1. 所有真实下载必须写入隔离输出目录。
2. 不允许把 /home/wanye/D/BlueArchive 或已安装客户端目录当作开发输出目录。
3. smoke test 只记录命令、状态和摘要，不把大体积官方资源纳入 Git。
4. 下载成功后必须通过 official-download-manifest.json audit 和官方 seed .hash 校验报告确认。

过早做 Web

处理策略：

1. Web 依赖可用 API 和数据库，不应早于核心同步、提取、翻译模型。
2. 先完成 CLI 和 API，再构建 Web。

---

8. 当前完成度评估

按最终目标计算，当前总体完成度不再固定写单一百分比，以模块状态和 issue 收敛情况为准。

已完成的是稳定基线、架构骨架、部分接口、CAS V1 和 Rust 官方资源同步闭环，不是完整产品能力。下一阶段的关键不是继续堆目录，而是把 Go 产品入口边界、官方同步端到端验证、CAS/ResourceRepository 编排和 AssetBundle 解析链路做实。

---

• 下一份应更新文档：真实官方网络 smoke 记录
• 下一项工程任务：收敛 Go 产品入口边界、执行官方同步端到端 smoke，并推进 CAS/ResourceRepository 与 AssetBundle 解析。