diff --git a/AGENTS.md b/AGENTS.md index 0286b3b..aa34a37 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,79 +1,160 @@ -# Agent 开发规则 +# AGENTS.md -本文件是 BlueArchive Toolkit 中 AI agent、自动化开发助手和长期维护脚本的权威入口。它替代旧 `CLAUDE.md` 中真正长期有效的工程规则。 +本文件用于约束在 BlueArchiveToolkit 中工作的 AI Agent。 -## 语言和表达 +具体开发进度看 `CURRENT_STATUS.md`，开发计划看 `PROJECT_PLAN.md`，当前缺口看 `docs/reports/CURRENT_GAPS.md`。这里不记录具体任务和阶段待办。 -1. 默认使用简体中文交流、写文档、写提交说明、写开发日志和写 API 说明。 -2. 代码中的包名、类型名、函数名、变量名、数据库字段、协议字段和命令参数保持英文命名规范。 -3. 代码注释只在能降低理解成本时添加；不要写复述代码行为的空泛注释。 -4. 如果任务、上游规范或第三方 API 明确要求英文，可以在对应位置使用英文。 +## 基本要求 -## 项目定位 +默认使用简体中文交流、写文档和提交说明。代码标识符、协议字段、数据库字段、命令参数等保持英文。 -BlueArchive Toolkit 是长期维护的开源工具链，不是 demo、一次性脚本或临时试验项目。 +BlueArchiveToolkit 是长期维护项目。不要为了尽快完成当前任务引入明显的临时实现，也不要把未来计划描述成已经存在的能力。 -长期目标包括但不限于： +修改代码前先读相关实现。涉及跨模块改动时，至少确认当前状态、相关架构文档、测试和已有接口，不要只看一个文件就重新设计整个模块。 -1. 官方资源同步、版本管理、增量同步、断点续传、重试、限速、缓存和校验。 -2. Content Addressable Storage（CAS）、引用计数、垃圾回收、多版本共享和完整性校验。 -3. UnityFS / AssetBundle / Addressables / Manifest 解析框架，并保持解析器与业务逻辑解耦。 -4. 文本提取、翻译记忆、术语库、AI Provider 抽象、Patch、CLI、Web、API、SDK 和插件系统。 -5. 支持未来扩展到其他区域、语言或 Unity 游戏；不要把架构写死到单一版本。 +如果发现用户提出的方案、现有代码或文档本身有问题，直接指出。不要为了迎合要求保留明显不合理的设计。 -## 工程边界 +## 以什么为准 -1. 默认工作于用户本地环境。不要把生产环境当作开发环境。 -2. 真实资源下载、smoke run 和手动验证必须写入隔离目录，例如 `/tmp` 或显式指定的测试目录。 -3. 不要默认读取、修改或污染现有客户端目录、生产资源目录或 `/home/wanye/D/BlueArchive` 这类本地资源目录。 -4. 不要要求安装官方启动器作为生产运行前提。可以分析启动器资源或官方公开数据，但生产链路必须能在 Linux 环境中独立运行。 -5. 涉及官方资源时，优先使用官方 `.hash`、catalog、manifest 和可复现 fixture 做校验依据。 +仓库里有不少历史文档，不能混着看。 -## 架构原则 +判断**当前实现**时，优先参考： -1. 仓库采用 monorepo；模块必须边界清晰、高内聚、低耦合。 -2. 公共接口应稳定、可测试、可维护，并为未来扩展保留合理空间。 -3. Rust 侧优先承担二进制解析、AssetBundle、Patch、CAS 和官方资源后端能力；Go 侧优先承担 CLI、运维入口和面向用户的命令编排。边界调整必须先说明理由。 -4. Rust/Go 默认集成路径优先进程边界（当前为 `bat --json`）或未来稳定 SDK；`bat-ffi` 仅作为可选无状态 C ABI 兼容层，不能扩展成 daemon、下载器、CAS handle 或主控制面。 -5. SDK 不得与 CLI 耦合；解析器不得与业务流程耦合；Provider、存储后端、Patch 算法和解析器应保留插件化扩展点。 -6. 不引入 God Object、God Class、超长函数、超长文件、硬编码、魔法数字、重复代码、临时实现或只为当前测试通过的伪实现。 -7. 不使用 `TODO`、`FIXME` 掩盖未完成设计。确实无法完成时，应在当前缺口文档中说明边界、风险和后续工作。 +* 当前源码和测试； +* `CURRENT_STATUS.md`； +* 对应模块的专项状态文档，例如 `docs/reports/GO_STATUS.md`； +* 已冻结的 RPC、release、schema 等契约。 -## 当前冻结 +`PROJECT_PLAN.md` 和 `CURRENT_GAPS.md` 描述的是计划和缺口，不代表功能已经实现。 -1. UnityFS / AssetBundle / Addressables / TypeTree 解析模块当前处于维护冻结，细则见 `docs/reports/PARSER_FREEZE.md`。 -2. 冻结期不继续新增解析类型、字段族、catalog 结构覆盖、写入型解析 RPC/CLI 或合成 fixture 驱动的能力扩展。 -3. 冻结期允许且优先处理编译、测试、clippy、真实运行回归、错误诊断、状态一致性、缓存复用和文档一致性问题。 -4. 如果用户明确要求继续解析扩展，必须先指出冻结状态、说明风险，并获得明确解冻或例外授权。 +`docs/archive/` 和 `docs/reports/historical/` 只用于追溯历史，不应作为当前实现依据。 -## 开发流程 +如果文档之间冲突，先核对源码和测试，再判断哪份文档已经过时。修代码时顺手修正相关权威文档，不要让冲突继续留在仓库里。 -1. 动手前先读相关文档和代码，确认当前真实状态。 -2. 对跨模块、架构、数据格式或用户工作流有影响的改动，先给出设计判断或简短计划。 -3. 实现后必须同步验证。验证范围要覆盖改动实际影响面，而不是只跑最窄的命令。 -4. 涉及用户可见行为、运行方式、架构边界或缺口状态时，必须同步更新文档。 -5. 保持改动范围和任务目标一致；不要顺手做无关重构或格式化 churn。 -6. 如果需求、技术路线或设计存在明显风险，应直接指出并给出可执行替代方案。 -7. 不确定的事实必须查证或询问；不要凭空调用不存在的接口、命令、路径或线上资源。 +ADR 记录架构决策，但旧 ADR 中已经被后续实现明确替代的部分不能机械照搬。 -## 质量要求 +## 现有边界 -1. 所有错误必须显式处理，并给出可诊断信息。 -2. 日志应结构化或至少足够定位阶段、路径、版本、URL、重试、校验和失败原因。 -3. 下载、写文件、状态切换和发布操作必须考虑原子性、断点续传、并发锁、失败恢复和清理策略。 -4. 本地状态文件和索引必须有版本字段或兼容策略。 -5. 新增 fixture、golden 或回归样本时，应说明它覆盖的真实风险。 -6. 默认验证命令见 `docs/guides/development.md`；稳定工程基线见 `docs/guides/baseline.md`。 +当前正式的资源同步和运维入口是 Rust `bat`。 -## 文档职责 +官方资源发现、下载、校验、版本状态、staging、release 发布、watch/daemon、任务和相关长期状态都由 Rust 侧负责。不要在 Go、Web 或其他模块再实现一套相同状态机。 -长期规则的权威位置如下： +Go `bat-api` 是资源 bootstrap、只读分发和管理入口。它通过 `bat.sock` RPC 消费 Rust 状态，并读取 Rust 已经发布的资源。不要让它直接管理官方同步状态，也不要在 Go 里重新实现 CAS、AssetBundle 解析或 Patch 核心算法。 -1. `AGENTS.md`：agent 行为、工程边界、架构原则和质量要求。 -2. `CONTRIBUTING.md`：贡献者工作流、提交规范、验证和 PR 要求。 -3. `docs/guides/development.md`：环境准备、开发命令、测试、调试和真实资源验证方式。 -4. `PROJECT_PLAN.md`：产品目标、阶段路线图和长期能力规划。 -5. `CURRENT_STATUS.md`：当前实现状态。 -6. `docs/reports/CURRENT_GAPS.md`：当前缺口、优先级和关闭顺序。 +`bat-ffi` 只是兼容接口，不是主集成方式。不要把 daemon、下载器、CAS 长生命周期状态或新的主控制面塞进 FFI。 -`CLAUDE.md` 只保留兼容入口，不应继续新增长期规则。 +官方原版 release 和 localized release 是两套独立生命周期。已经发布的官方 release 应当视为不可变输入，汉化和 Patch 必须走独立 staging、校验、发布和 rollback 流程。 + +前端、API 和 CLI 不应维护第二套业务状态。状态以真正拥有它的后端模块为准。 + +## 模块和接口 + +优先使用仓库已经存在的抽象，例如 Repository、Adapter、Driver、Registry、Provider、RPC 和现有状态模型。 + +不要因为新增一个功能就平行实现第二套下载、存储、解析、Patch、翻译任务或 release 系统。 + +容易随着 Blue Archive、Unity、Addressables 或外部服务变化的逻辑应尽量留在 adapter/driver/provider 一侧，不要散进整个业务代码。 + +同时不要为了“以后可能会扩展”提前创建大量无实际用途的接口。只有已经存在多实现需求，或确定属于高变化边界的部分，才值得进一步抽象。 + +公共或持久化接口修改时要考虑兼容性。特别注意： + +* RPC method 和 schema； +* `status` / `status_code`； +* `BAT-ERR-*` 错误码； +* CLI JSON 输出； +* release layout； +* manifest/state 文件； +* SQLite/PostgreSQL schema； +* Patch manifest； +* HTTP API。 + +不要静默改变已有字段的含义。确实需要破坏性修改时，先考虑版本号、迁移或兼容读取。 + +## 代码修改 + +先弄清楚代码为什么放在当前位置，再决定是继续修改还是拆模块。 + +仓库里已经存在一些较大的文件。不要因为“文件太长”机械拆分，但也不要继续往一个已经承担过多职责的文件里塞新的独立功能。按职责拆，不按行数拆。 + +避免： + +* 重复实现已有能力； +* 大范围无关重构； +* 为测试专门加入生产逻辑； +* 静默吞错； +* 无说明的硬编码； +* 魔法数字； +* 假实现、空实现冒充完成功能； +* 用 `TODO` / `FIXME` 代替正式的缺口记录。 + +如果当前任务确实无法完成某一部分，应明确限制实现范围，并把剩余问题记录到对应的状态、缺口或 Issue 中。 + +## 文件、网络和发布安全 + +资源处理代码不能绕过现有的路径和完整性检查。 + +涉及文件写入、下载、CAS、Patch、release 或客户端文件时，应继续遵守仓库现有做法，包括路径归属检查、symlink 防护、临时文件、原子写入、hash/size 校验、失败不发布不完整结果等。 + +官方资源链路只使用项目当前允许的官方来源。不要为了绕过失败偷偷加入镜像或来源不明的 fallback。 + +密钥、Token、代理凭据等不能进入 Git，也不能无必要地出现在日志、状态文件或进程参数中。 + +## 测试 + +根据改动范围运行仓库已有的测试和检查，不要自己发明另一套质量流程。 + +Rust 修改通常至少考虑： + +```bash +cargo fmt --all -- --check +cargo check --workspace +cargo test --workspace +cargo clippy --workspace --all-targets -- -D warnings +``` + +Go / bat-api 修改使用仓库现有 Makefile 和对应 `go test` / `go vet` 门禁。 + +涉及文档状态时运行： + +```bash +make check-docs +``` + +涉及真实资源格式、RPC contract、release 或网络流程时，优先补已有 fixture、contract test、integration test 或 smoke，而不是只写一个理想化单元测试。 + +不能只根据合成样本宣称支持新的官方格式。 + +不方便运行某项重要测试时，在结果里说明没有运行什么以及原因。 + +## 文档 + +改动如果影响用户或其他模块能够观察到的行为，就同步对应文档。 + +尤其是： + +* CLI； +* RPC； +* HTTP API； +* 配置项； +* release 布局； +* schema； +* 错误码和状态码； +* 模块职责； +* 当前实现状态。 + +不要把具体任务、临时优先级或某次实现方案写进本文件。 + +新的长期架构决策应该进入 ADR 或对应架构文档；开发路线进入 `PROJECT_PLAN.md`；实际进度进入 `CURRENT_STATUS.md`；未完成内容进入 `CURRENT_GAPS.md` 或 Issue。 + +## 工作方式 + +局部且模式明确的修改可以直接做。 + +涉及公共契约、新子系统、持久化格式、跨语言边界、大范围重构或安全边界时，先把现有实现和影响范围弄清楚，再动代码。 + +完成后检查三件事： + +1. 有没有重复仓库已经存在的能力； +2. 有没有无意改变稳定接口或状态所有权； +3. 代码、测试和权威文档是否仍然一致。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 89dd62e..3fc1f79 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,9 +37,14 @@ 基础验证命令见 `docs/guides/development.md`。常用最低门禁： ```bash -cargo fmt --check +cargo fmt --all -- --check +cargo check --workspace cargo test --workspace cargo clippy --workspace --all-targets -- -D warnings +make test-go-api +make build-go-api +go vet ./... +make check-docs ``` 如果改动只影响部分 crate，可以先跑更窄的测试，但合并前必须确保影响面被覆盖。官方资源同步、下载、daemon、status、verify 或 repair 相关改动还应运行： diff --git a/CURRENT_STATUS.md b/CURRENT_STATUS.md index 7129055..19944b8 100644 --- a/CURRENT_STATUS.md +++ b/CURRENT_STATUS.md @@ -1,6 +1,6 @@ # BlueArchiveToolkit 当前工作区状态 -- **更新时间**：2026-09-02 +- **更新时间**：2026-09-04 - **状态来源**：本地工作区盘点、代码验证和最新提交 - **状态分支**：`experiment` - **最新已推送功能提交**：以当前 `git log --oneline -1` 为准 @@ -30,7 +30,7 @@ Rust 侧官方日服资源链路已经从实验验证推进到正式入口： 13. 资源导入链路已支持 CAS + `ResourceRepository` 索引写入，官方同步可用 `--import-repository` / `BAT_IMPORT_REPOSITORY=1` 在已校验 release 发布后触发导入，默认 CAS 路径为 `/.cas`、SQLite 索引为 `/resources.sqlite`，也可通过 `--import-cas-root`、`--import-resource-db`、`BAT_IMPORT_CAS_ROOT`、`BAT_IMPORT_RESOURCE_DB` 覆盖；`resource.index` RPC/CLI 可按类型、hash、路径模式、官方 release ID、平台、destination、bundle path、archive entry、parse status 和 TextUnit format 分页查询现有索引，release、平台、bundle path 和常用数组 metadata 过滤已下推到 SQLite，数据库不存在时返回 `available=false` 且不会创建空库；`bat doctor cas` 可只读检查既有 CAS 根目录、对象目录、元数据库文件和对象统计，不会因诊断创建空库。`Resource` metadata 已通过 `metadata_json` 兼容迁移保存 release、平台、bundle path、parse status、TextAsset 名称和 TextUnit 数量/格式；当前/上一个/结构变化 catalog、失败 staging 复用、403/404、hash mismatch、CRC、metadata 迁移与 UnityFS 边界校验均有离线回归 fixture 或单测覆盖。 14. 非 dry-run 官方同步在校验完成并发布后，会先对比上一完整 release 与当前 release 的 `official-download-manifest.json`，在当前 release 下写入 `official-resource-changes.json` 和 `crowdin-translation-handoff.json`；同一 destination 只有 size 或 BLAKE3 改变才算 modified，仅 URL/CDN 根变化但内容相同不会触发解析/翻译候选。随后刷新 `official-parse-cache.json` 和 `official-textunit-index.json`，并从 Added/Modified 资源、parse cache 与 TextUnit 明细索引派生 `official-textunit-tasks.json` 和 `crowdin-textunit-queue.json`；删除资源只进入差异记录，不进入 TextUnit/Crowdin 队列。`parse.text_units` 和 `parse.errors` RPC/CLI 可按 destination、archive entry、path id、class id、field path 和 format 查询当前 release 的 TextUnit 明细与解析错误；`translation.tasks` RPC/CLI 可按 release、destination、archive entry、任务状态、parse status、TextUnit format 和 reason presence 查询离线 TextUnit 翻译任务状态与跳过/失败原因；`translation.task.update` 可回写 provider worker 状态，`translation.worker.run` 可触发 Rust provider worker 独立 claim/lease/retry 并落库 TextUnit 级译文结果，`translation.proofread` 可把汉化 workflow 标记为人工校对中；TextUnit 已包含 class id、field path、字段 offset/byte size 等可追溯定位。Crowdin provider 通过 `CROWDIN_*` 环境变量接入，mock provider 支持本地 fixture；up-to-date 轮询在已有有效解析缓存、TextUnit 明细索引和 TextUnit 队列时只读取摘要，不重复解析。官方同步报告默认 `localized_release_status=not_localized`，含义是原版资源已经发布、汉化资源未发布；受支持的 UnityFS TextAsset、TypeTree string field 和 managed-reference string field 发布成功后会写带 trace 的 `localized-patch-manifest.json`，校验 hash/size/diff/rollback 后才允许 `localized.status` 返回 `status=published`、`status_code=localized.published` 和 `localized_release_status=localized`，并可用 `localized.rollback` 显式恢复上一 release。`bat` 首次启动会在二进制所在目录释放 `.env` 配置模板（`0600`），之后每次启动自动加载（不覆盖已存在的环境变量），支持 `BAT_OUTPUT`/`BAT_LOCALIZED_OUTPUT`/`BAT_IMPORT_REPOSITORY`/`BAT_IMPORT_CAS_ROOT`/`BAT_IMPORT_RESOURCE_DB`/`BAT_STATE_DIR`/`BAT_AUTO_DISCOVER`/`BAT_WATCH`/`BAT_DAEMON`/`BAT_PROXY` 和 `BAT_TRANSLATION_*` 等键，实现编辑 `.env` 后无参启动；优先级为命令行参数 > 进程环境变量 > `.env` > 内置默认值，`BAT_SKIP_ENV_FILE=1` 可整体禁用；Redis 键为预留。daemon 任务历史持久化在 `/bat-tasks.json`（版本化、`0600` 原子写），重启后任务经 `task.*` 仍可查，中断任务标记 `task_interrupted`（`BAT-ERR-700005`）。官方同步报告还分别统计当前 manifest 复用、历史 release 复用、CAS 复用、网络传输字节和复用回退诊断，下载事件状态使用 `release_reused`、`cas_reused`、`downloaded` 等稳定值。 -15. issue 43 已补齐 Rust `bat` 的 `res` / `parse` / `i18n` 工作流入口：支持资源拉取、解析刷新、可再生解析缓存清理、离线翻译工作台、人工文本查看/修改/清空、工作台发布前校验、有限 TextAsset 汉化发布、人工校对状态标记、既有 patch 能力的批量重打包、单次/限定次数/周期执行和版本化 schedule CRUD。issue 44 已接入 `translation.worker.run` provider worker：默认并发 8、范围 `1..=256`，每个 worker 独立 claim 下一项任务并落库 lease、失败分类、重试计划和 TextUnit 译文结果。schedule 查询现在按一级工作流过滤，删除/执行会校验作用域，单轮执行可限制计划数；schedule CRUD、翻译任务查询/交接视图、翻译任务状态回写、provider worker 触发和 `translation.proofread` 状态标记已通过 `bat.sock` 的 RPC 以及 `bat-api` 的鉴权管理接口暴露，dashboard 不维护第二套状态。issue 46 已提供 `bat-api` 内嵌 dashboard MVP，静态资产由 Go embed 暴露在 `/admin/dashboard/`，页面直接调用已有鉴权接口控制资源、调度、翻译、任务、日志、parse TextUnit 查询和 localized 发布/回滚。该例外只编排已有解析和 patch 能力，不扩大解析器覆盖；完整 AssetBundle 重打包和完整 Web 协作后台仍是后续工作。G-008（产品级 Go 同步 CLI）已决策关闭。真实官方网络全量拉取 smoke 已固化（G-018 已关闭）；真实大文件与运行报告默认在 `/tmp` 隔离目录，不纳入 Git。Go 细节见 `docs/reports/GO_STATUS.md`。 +15. Rust `bat` 已提供 `res` / `parse` / `i18n` 工作流入口：支持资源拉取、解析刷新、可再生解析缓存清理、离线翻译工作台、人工文本查看/修改/清空、工作台发布前校验、有限 TextAsset 汉化发布、人工校对状态标记、既有 patch 能力的批量重打包、单次/限定次数/周期执行和版本化 schedule CRUD。`translation.worker.run` 已接入 provider worker：默认并发 8、范围 `1..=256`，每个 worker 独立 claim 下一项任务并落库 lease、失败分类、重试计划和 TextUnit 译文结果。schedule 查询现在按一级工作流过滤，删除/执行会校验作用域，单轮执行可限制计划数；schedule CRUD、翻译任务查询/交接视图、翻译任务状态回写、provider worker 触发和 `translation.proofread` 状态标记已通过 `bat.sock` 的 RPC 以及 `bat-api` 的鉴权管理接口暴露，dashboard 不维护第二套状态。`bat-api` 已提供内嵌 dashboard MVP，静态资产由 Go embed 暴露在 `/admin/dashboard/`，页面直接调用已有鉴权接口控制资源、调度、翻译、任务、日志、parse TextUnit 查询和 localized 发布/回滚。该工作流只编排已有解析和 patch 能力，不扩大解析器覆盖；完整 AssetBundle 重打包和完整 Web 协作后台仍是后续工作。真实官方网络全量拉取 smoke 已固化，真实大文件与运行报告默认在 `/tmp` 隔离目录，不纳入 Git。Go 细节见 `docs/reports/GO_STATUS.md`。 当前翻译交接还包括 `translation-tasks.sqlite` 和版本化 `translation-handoff.json`； `translation.tasks` 查询单项 worker 状态，`translation.handoff` 查询完整 @@ -153,9 +153,9 @@ job/unit/provider run 状态。当前下载实现使用默认 8 个独立 worker ### `bat-assetbundle` -状态：**UnityFS 解包、TypeTree 字段读取、TextUnit 提取和受支持 localized patch 发布已可用；复杂结构覆盖与整体 AssetBundle 重打包仍冻结** +状态：**UnityFS 解包、TypeTree 字段读取、TextUnit 提取和受支持 localized patch 发布已可用；复杂结构覆盖与整体 AssetBundle 重打包仍待继续补齐** -冻结说明：自 2026-07-30 起，解析模块进入维护冻结。冻结期只允许修复编译、测试、clippy、崩溃、错误诊断、真实运行回归和文档不一致；不新增 TypeTree 语义类型、不扩大 UnityFS / AssetBundle / Addressables 解析覆盖、不开放新的写入型解析 RPC/CLI，也不以合成 fixture 宣称新增解析能力。冻结细则见 `docs/reports/PARSER_FREEZE.md`。 +解析扩展当前按路线图和真实 fixture 验收推进。 当前已有： @@ -172,7 +172,7 @@ job/unit/provider run 状态。当前下载实现使用默认 8 个独立 worker 待完成： - 真实 MonoBehaviour、ScriptableObject 版本差异、复杂容器结构调整、unknown 字段结构语义和未见样本驱动的完整 managed reference registry / map entry 变体覆盖；TypeTree-covered managed reference 字段与 registry 记录已可结构化解码，常见 full typename 可拆解为 assembly/namespace/class，不做低保真猜测。 -- 复杂对象整体结构修改后的发布级 AssetBundle 重打包；UnityFS TextAsset、TypeTree string 字段、managed-reference registry payload 字符串、基础语义字段、enum、bit_field、object 字段组合和 TypeTree schema 支撑的 array/vector/map 整体替换的文件级链路已具备重建后校验，受支持 localized patch 已有独立 staging、manifest、current、状态校验和显式 rollback；整体 AssetBundle 发布仍不在冻结范围内。 +- 复杂对象整体结构修改后的发布级 AssetBundle 重打包；UnityFS TextAsset、TypeTree string 字段、managed-reference registry payload 字符串、基础语义字段、enum、bit_field、object 字段组合和 TypeTree schema 支撑的 array/vector/map 整体替换的文件级链路已具备重建后校验，受支持 localized patch 已有独立 staging、manifest、current、状态校验和显式 rollback；整体 AssetBundle 发布仍未完成。 - 真实资源 fixture 覆盖对象级解析和文本提取。 - 详细补全顺序见 `docs/architecture/assetbundle.md`。 @@ -203,7 +203,8 @@ job/unit/provider run 状态。当前下载实现使用默认 8 个独立 worker - `bat-ffi` 只暴露粗粒度、无状态、一次调用一次 JSON 输入输出的 C ABI helper。 - 它不持有 downloader、daemon、CAS handle、资源目录锁或长生命周期状态。 -- 未来 Go 产品入口和生产运维默认应调用 `bat --json` 进程边界；未来稳定 SDK 也优先于 FFI。 +- 新的 Go 集成和生产运维读侧默认应调用 `bat.sock` RPC；`bat --json` 仅是 + Rust CLI 的机器输出形态，`bat-ffi` 仍是可选兼容层。 - FFI 仅用于需要嵌入 C ABI 的兼容场景，不能作为官方同步控制面或主集成边界。 待完成： @@ -213,7 +214,7 @@ job/unit/provider run 状态。当前下载实现使用默认 8 个独立 worker ### Go / API / Web -状态：**边界已冻结；资源分发 MVP 已落地。权威细节见 `docs/reports/GO_STATUS.md`。** +状态：**边界已确定；资源分发 MVP 已落地。权威细节见 `docs/reports/GO_STATUS.md`。** | 角色 | 所有者 | 状态 | |---|---|---| @@ -223,7 +224,7 @@ job/unit/provider run 状态。当前下载实现使用默认 8 个独立 worker | 试验 CLI | `cmd/bat` → `bin/bat-go` | 非产品 | | FFI | `internal/ffi` | 可选 | | 空目录 `api/` `pkg/` 等 | 占位 | 无实现 | -| Web | `web/` | 内嵌 dashboard MVP（issue #46）；完整协作后台仍未完成 | +| Web | `web/` | 内嵌 dashboard MVP；完整协作后台仍未完成 | 默认 Go/docs 门禁：`make test-go-api`、`make build-go-api`、`make check-docs`（无 FFI）。 @@ -231,33 +232,30 @@ job/unit/provider run 状态。当前下载实现使用默认 8 个独立 worker ## 4. 已验证结果 -近期 Rust 侧复核已运行并通过： +以下命令已于 2026-09-04 在本地工作区执行并通过： ```bash -cargo fmt --check -cargo test --offline --workspace --quiet -cargo clippy --offline --workspace --all-targets -- -D warnings -cargo test --offline -p bat-patch --quiet -cargo test --offline -p bat-assetbundle --quiet -cargo test --offline -p bat-infrastructure official_parse --quiet -cargo test --offline -p bat-infrastructure dispatch_parse --quiet -cargo test --offline -p bat-infrastructure localized_patch --quiet +cargo fmt --all -- --check +cargo check --workspace --locked +cargo test --workspace --locked +cargo clippy --workspace --all-targets --locked -- -D warnings ``` -本次 bat-api 侧复核已运行并通过： +Go 与文档门禁： ```bash -env GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache make test-go-api -env GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache make build-go-api -env GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache go vet ./internal/api/... ./internal/backendrpc/... ./cmd/bat-api/... +GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache make test-go-api +GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache make build-go-api +GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache go test ./... +GOCACHE=/tmp/bat-go-cache GOMODCACHE=/tmp/bat-go-modcache go vet ./... make check-docs ``` -未执行 / 后置： +当前仍未作为本地事实确认的项目包括： -- 真实官方全量 smoke 长期运行报告（G-018 命令已固化）。 +- 真实官方全量 smoke 长期运行报告；命令已固化为 `make official-smoke`。 - `bat-api` 同机 live 联调：已由 `make bat-api-local-live-smoke` 在 `/tmp` 隔离目录完成；真实官方网络全量下载仍由 `make official-smoke` 独立跟踪。 -- 完整 Web 协作后台（G-010 剩余部分）。 +- 完整 Web 协作后台。 --- @@ -272,7 +270,7 @@ cargo run -p bat-infrastructure --bin bat -- \ --watch ``` -资源 HTTP bootstrap / 只读分发入口是 Go `cmd/bat-api`。生产拓扑下它与 Rust `bat` 同环境运行，经 `bat.sock` RPC 获取当前 `resource_root`，不在配置里写死资源目录；本地开发不能全量跑 `bat` 时用 fixture 和 Go 门禁验证。`internal/api/testdata/contract/` 已固化来自 Rust 输出并经归一化的 `catalog.status`、`resource.manifest` 和 `official-sync-snapshot.json` contract fixture，Go mirror 测试会防止字段名、null 语义和 `game_main_config_bootstrap` 再次漂移。`bat-api` 已补 launcher 资源引导兼容端点、玩家-facing HTTP 控制面和鉴权调度/translation 管理接口（token 鉴权、限流、访问日志、反代 IP 适配、动态 JSON no-store、OpenAPI、管理控制白名单；`reload` / `refresh` / `restart` / `sync` / `verify` / `repair` / `catalog-refresh`、`schedule.*`、`task.*` 查询/取消、`daemon.logs`、`parse.*` 查询、`translation.tasks` / `translation.handoff` 查询、`translation.task.update`、`translation.worker.run`、`translation.proofread`、`localized.publish` 和 `localized.rollback` 可经 dashboard 转发），响应只来自已发布 snapshot/RPC，不提供登录、网关、鉴权或完整 package update manifest。 +资源 HTTP bootstrap / 只读分发入口是 Go `cmd/bat-api`。生产拓扑下它与 Rust `bat` 同环境运行，经 `bat.sock` RPC 获取当前 `resource_root`，不在配置里写死资源目录；本地开发不能全量跑 `bat` 时用 fixture 和 Go 门禁验证。`internal/api/testdata/contract/` 已固化来自 Rust 输出并经归一化的 `catalog.status`、`resource.manifest` 和 `official-sync-snapshot.json` contract fixture，Go mirror 测试会防止字段名、null 语义和 `game_main_config_bootstrap` 再次漂移。`bat-api` 已补 launcher 资源引导兼容端点、玩家-facing HTTP 控制面和鉴权调度/translation 管理接口（token 鉴权、限流、访问日志、反代 IP 适配、动态 JSON no-store、OpenAPI、管理控制白名单；`reload` / `refresh` / `restart` / `sync` / `verify` / `repair` / `catalog-refresh`、`schedule.*`、`task.*` 查询/取消、`daemon.logs`、`parse.*` 查询、`translation.tasks` / `translation.handoff` 查询、`translation.task.update`、`translation.worker.run`、`translation.proofread`、`localized.publish` 和 `localized.rollback` 可经 dashboard 转发），响应只来自已发布 snapshot/RPC，不提供官方账号登录、游戏网关协议或完整 package update manifest。 生产要求： @@ -286,34 +284,30 @@ cargo run -p bat-infrastructure --bin bat -- \ --- -## 6. 当前阻塞项 +## 6. 当前开发基础与后续工作 -GitHub issue 状态：#1 已关闭；#17 的历史决定不代表当前下载实现，现行默认并发为 8，范围 `1..=256`，每个独立 worker 完成后立即领取下一个任务，进度按完成事件即时统计并保持 report 计划顺序；子 issue #20–#23 均已关闭。其他 open issue 的实时标签以 GitHub 为准。 +Issue 状态不作为本地实现状态的权威来源；本次复核未把远端 Issue 列表作为已验证事实。 +当前实现以源码、测试、稳定契约和本文件的模块状态为准。 -下一阶段必须优先完成： +当前非阻塞验证跟踪： -1. Issue #1（P0，主体已实现）：`bat.sock` Unix socket JSON-RPC 已扩展为面向 Go 服务层的 Rust Resource Backend API。统一 envelope（`ok`、`status`、`error`、`data`、`request_id`）与 `BAT-ERR` 错误码模型已落地；`daemon.*`（status/logs/stop/restart/reload/refresh/doctor）、`resource.*`（state/sync/verify/repair/manifest/list/index）、`schedule.*`（list/add/update/remove/run）、`parse.*`（status/text_units/errors）、`translation.*`（tasks/handoff/task.update/proofread/worker.run）、`localized.*`（status/publish/rollback）、`catalog.*`（status/refresh/diff/versions）、`task.*`（status/list/cancel/logs）、文件级 `patch.apply` 与 `unityfs.patch_text_asset` / `unityfs.patch_string_field` / `unityfs.patch_field` 已实现，长任务返回 `task_id` 可轮询（任务执行器单 worker FIFO，与 watch 循环互斥；任务历史持久化于 `/bat-tasks.json`，daemon 重启后仍可查，中断任务标记 `task_interrupted`）；错误码已接入下载、launcher/metadata、server-info/marker 与配置校验路径。剩余：通用 manifest 驱动发布、复杂 `unityfs.*` 语义编辑、`task.create`（按设计由语义方法创建）、`daemon.clean-stable`（由 CLI 侧按进程生命周期显式执行，live RPC 内不做在线清理）、Redis 任务后端（`.env` 已预留配置键，接入时机另议）。Go 层通过 RPC 调用 Rust backend，不走 FFI（FFI 降级说明见 `docs/architecture/official-resource-backend.md` §7）。 -2. Go 侧：进度见 `docs/reports/GO_STATUS.md`。G-008 已关闭；`bat-api` 资源 bootstrap/分发 MVP 已落地，已含 `/v1/bootstrap`、`/v1/launcher/bootstrap`、launcher 资源 metadata 兼容、HTTP 鉴权/限流/日志/反代适配、动态 JSON no-store、OpenAPI、管理控制白名单、task/log/parse/translation admin 查询控制、内嵌 dashboard、CDN Range/缓存头、RPC 周期刷新和 USERGUIDE 基础章节；仓库内 Rust/Go snapshot contract fixture 与同机 live smoke 已落地。失效 `resource_root` 或 manifest 不完整时会清空旧索引并使 `/readyz` 返回 `503`；编码 dot-segment 会在路由规范化前拒绝。refresh mtime/size 增量缓存和可选持久化另议。 -3. 文本提取 / 翻译队列 / Patch 输入：`official-textunit-index.json`、`official-textunit-tasks.json` 与 `crowdin-textunit-queue.json` 已生成；TextUnit 明细、解析错误和离线翻译任务状态/失败原因已可查询，`translation.tasks` / `translation.handoff` 已提供 Go typed helper 和 bat-api dashboard 查询入口，`translation.task.update` 已提供 Rust CLI、Go typed helper 和 bat-api dashboard 状态回写入口，且支持人工校对从当前 TextUnit 索引提交 `translation_results`；`translation.worker.run` 已提供 mock/Crowdin provider worker、lease、重试和 TextUnit 译文结果落库，`translation.proofread` 已提供人工校对状态标记入口。受支持 TextAsset、TypeTree string field 和 managed-reference string field 已可从 workbench/worker 结果生成 localized patch，在独立 staging 校验后发布并显式 rollback，相关 status/publish/rollback RPC 与 bat-api 控制入口已暴露。剩余为翻译记忆、通用 manifest 发布和复杂重打包。 -4. Issue #3（已完成当前目标）：AssetBundle UnityFS 基础解析校验已覆盖 header、block、directory、LZ4/LZMA、alignment、总大小、计数、路径安全、重复 directory、边界和隔离 UnityPy 真实样本；复杂对象解析与发布级重打包继续跟踪 G-005。 -5. Issue #2（已完成当前目标）：Addressables JSON/compact catalog 已提取 bundle provider、name、hash/size/CRC、资源类型和依赖关系，并贯通 ResourceEntry、SQLite 与 resource.index 输出；独立二进制格式仍明确拒绝。 -6. 通用 Binary/JSON/Text Patch 基础已落地；受支持 localized patch 发布/rollback 已具备回归测试，复杂 AssetBundle 重打包、通用 manifest 发布和真实翻译记忆仍后置。 +- 使用 `make official-smoke` 执行真实官方网络长期运行测试，并将报告留在隔离目录。 -非阻塞跟踪项：官方同步长期运行测试正在进行，运行报告将在后续提供。 +后续工程顺序： + +1. 继续复杂 AssetBundle：真实样本、复杂字段解析和发布级重打包。 +2. 继续通用 Patch：manifest 驱动、双 release 查询和清理策略。 +3. 继续资源查询和翻译基础设施：更丰富的查询、Translation Memory、Glossary 和 Provider + 扩展体系。 +4. 在资源和翻译契约稳定后推进完整 Web 协作后台和完整游戏业务 API。 --- -## 7. 下一步建议 - -立即任务： - -1. Issue #1 收尾：协议基础设施、最小方法集、`catalog.*`、`parse.*`、`localized.*`、`task.*`、`resource.repair`、`daemon.restart`、文件级 `patch.apply` / `unityfs.patch_text_asset` / `unityfs.patch_string_field` / `unityfs.patch_field`、任务持久化、错误码模型与文档均已完成；剩余通用 manifest 发布、复杂 `unityfs.*` 语义编辑以及 `task.create`、`daemon.clean-stable` 的设计边界确认。 -2. 真实官方网络全量下载长期运行报告（`make official-smoke`）；issue #19 的同机 live 联调已完成。 -3. 跟进官方同步长期运行测试报告。 -4. AssetBundle / Addressables（issue #3 / #2）的后续结构变体；G-011 剩余的 TextUnit 查询、翻译记忆和通用 Patch 发布资源视图。 - ---- - -- **当前总体完成度**：不再固定写单一百分比，以各模块状态、`GO_STATUS.md` 和 issue 为准。 -- **当前基线状态**：Rust `bat` 同步闭环可用；Go `bat-api` 资源 bootstrap/分发 MVP + 玩家-facing HTTP 控制面 + launcher 资源引导兼容 + RPC 周期刷新/诊断 + readiness + 内嵌 dashboard + `backendrpc` 可用；CAS 用户级导入、TextUnit 明细索引/查询、增量 Crowdin 离线队列、通用 Binary/JSON/Text Patch 基础和受支持 localized patch 发布/rollback 可用；完整 AssetBundle 重打包、完整 Web 协作后台与通用 manifest 发布未完成。 -- **下一工程里程碑**：翻译记忆、通用 manifest Patch 构建、复杂 AssetBundle 解析和重打包；`bat-api` 同机 live 联调已完成。 +- **当前总体完成度**：不固定写单一百分比，以各模块状态、源码、测试和契约为准。 +- **当前基线状态**：Rust `bat` 同步闭环可用；Go `bat-api` 资源 bootstrap/分发 MVP、 + HTTP 控制面、launcher 资源引导兼容、RPC 周期刷新/诊断、readiness、内嵌 dashboard + 和 `backendrpc` 可用；CAS 用户级导入、TextUnit 明细索引/查询、增量离线队列、 + 通用 Binary/JSON/Text Patch 基础和受支持 localized patch 发布/rollback 可用； + 完整 AssetBundle 重打包、完整 Web 协作后台、翻译记忆和通用 manifest 发布未完成。 +- **下一工程里程碑**：复杂 AssetBundle 解析和重打包、翻译记忆、通用 manifest Patch + 构建，以及真实官方资源长期运行验证。 diff --git a/DOCS_INDEX.md b/DOCS_INDEX.md index b62d8e0..824d5a3 100644 --- a/DOCS_INDEX.md +++ b/DOCS_INDEX.md @@ -1,129 +1,135 @@ -# BlueArchiveToolkit 文档索引 +# BlueArchive Toolkit 文档分类索引 -- **更新时间**：2026-09-02 -- **说明**：本索引用于快速定位当前权威文档和历史资料。 +- **更新时间**：2026-09-04 +- **用途**：按用途、时效性和权威级别定位文档。 +- **原则**：目录是物理归档方式，不能单独代表文档权威性；当前源码、测试和下列当前文档优先于历史报告。 ---- +## 1. 项目入口与协作规则 -## 1. 权威入口 +这些文件位于仓库根目录，是项目级入口或协作规则： + +- `README.md`：项目概览、当前能力和快速开始。 +- `USERGUIDE.md`：`bat` 用户指南、命令、配置、错误码和常用 RPC 说明。 +- `CURRENT_STATUS.md`：当前实现状态，使用源码和测试复核后维护。 +- `PROJECT_PLAN.md`：长期目标、里程碑和后续路线图。 +- `CONTRIBUTING.md`：贡献流程、提交规范和验证要求。 +- `CHANGELOG.md`：版本变更记录，不作为当前实现的唯一依据。 +- `CLAUDE.md`：旧工具兼容入口，不承载独立规则。 +- `AGENTS.md`：AI agent 长期协作规则。 + +## 2. 当前状态、计划与缺口 + +这些文件描述当前项目，不应写入未经源码或测试证明的完成状态： + +- `CURRENT_STATUS.md`：全项目当前状态总览。 +- `docs/reports/GO_STATUS.md`：Go `bat-api` 边界和组件进度的权威文档。 +- `docs/reports/CURRENT_GAPS.md`：当前缺口、影响和推进顺序。 +- `PROJECT_PLAN.md`：目标和路线图；其中的计划项不等于已实现。 +- `docs/reports/BAT_API_CONTRACT_FIXTURE_HANDOFF.md`：Rust 输出、Go contract fixture 和联调的当前交接说明。 + +## 3. 架构、决策与稳定契约 + +### 3.1 架构总览和专题 + +- `docs/architecture/README.md`：总体架构和目标边界；当前实现以 `CURRENT_STATUS.md` 为准。 +- `docs/architecture/official-resource-backend.md`：官方资源发现、清单、下载、发布和导入边界。 +- `docs/architecture/resource-release-layout.md`：release 目录、URL 映射、seed 和 `bat-api` 分发契约。 +- `docs/architecture/assetbundle.md`：Addressables、UnityFS、Serialized File、TextUnit、CAS 和 Patch 的解析路线图。 + +### 3.2 架构决策记录 + +- `docs/architecture/adr/0001-engine-and-application-boundaries.md`：Rust 引擎与 Go 应用层边界。 +- `docs/architecture/adr/0002-cas-v1-design-boundary.md`：CAS V1 设计边界。 +- `docs/architecture/adr/0003-cas-core-interface-and-error-boundary.md`：CAS 核心接口和错误边界。 +- `docs/architecture/adr/0004-rust-bat-go-bat-api-resource-boundary.md`：当前 Rust `bat` 与 Go `bat-api` 资源控制面边界。 + +### 3.3 对外接口规范 -- `README.md`：项目概览、当前可用能力和快速开始。 -- `PROJECT_PLAN.md`：完整开发计划和最终目标路线图。 -- `CURRENT_STATUS.md`：当前工作区真实状态。 -- `docs/reports/CURRENT_GAPS.md`：当前实现缺口和关闭顺序。 -- `docs/reports/GO_STATUS.md`：Go 侧边界、约定与组件进度（权威）。 -- `docs/guides/official-resource-test-pull.md`：官方资源拉取与自动更新用户指南。 -- `docs/guides/official-full-pull-smoke.md`：真实官方全量拉取 smoke runbook 和可重复命令。 -- `docs/guides/bat-api-local-live-smoke.md`：同机 Rust `bat` / Go `bat-api` live socket 联调 runbook。 -- `docs/guides/bat-workflows.md`：Rust `bat` 的 `res` / `parse` / `i18n` 工作流、调度计划和 `bat-api` dashboard 接口。 -- `docs/architecture/official-resource-backend.md`：官方资源后端职责、工作原理和审核说明。 -- `docs/architecture/resource-release-layout.md`：release 布局、URL 映射、seed 规则、bat-api 分发契约（资源侧逆向权威）。 -- `docs/architecture/assetbundle.md`：AssetBundle、Addressables、Serialized File、文本提取和 Patch 前置解析路线图。 - `docs/reference/rpc-backend-api.md`：Rust Resource Backend JSON-RPC 稳定 contract。 -- `CHANGELOG.md`：版本变更记录。 -- `AGENTS.md`：AI agent 和自动化开发助手长期规则。 -- `CONTRIBUTING.md`：贡献者协作、提交和验证要求。 -- `CLAUDE.md`：Claude Code 等旧工具的兼容入口。 +- `api/openapi/bat-api.yaml`：`bat-api` HTTP OpenAPI 静态规范。 +- `docs/api/README.md`：API 文档入口及规范索引。 ---- +契约文档涉及字段、状态码、错误码、release layout 或路径语义时，必须与源码测试和 `internal/api/testdata/contract/` 一起复核。 -## 2. 架构与指南 +## 4. 用户、开发与运维指南 -- `docs/architecture/README.md`：总体架构设计。 -- `docs/api/README.md`：API 设计入口。 -- `api/openapi/bat-api.yaml`：当前 `bat-api` 资源 bootstrap/分发、内嵌 dashboard 和管理控制面 HTTP OpenAPI 静态规范。 -- `docs/reference/rpc-backend-api.md`：Rust Resource Backend JSON-RPC 稳定 contract。 -- `docs/guides/development.md`：开发指南。 -- `docs/guides/deployment.md`：部署指南。 -- `deployments/systemd/`：官方资源同步生产 systemd unit 和环境文件示例。 -- `docs/guides/official-resource-test-pull.md`：官方资源拉取与自动更新用户指南。 -- `docs/guides/official-full-pull-smoke.md`：真实官方全量拉取 smoke runbook 和可重复命令。 -- `docs/guides/bat-api-local-live-smoke.md`：同机 Rust `bat` / Go `bat-api` live socket 联调。 -- `docs/guides/baseline.md`：稳定工程基线指南。 -- `docs/architecture/adr/0001-engine-and-application-boundaries.md`：Rust/Go 边界决策。 -- `docs/architecture/adr/0002-cas-v1-design-boundary.md`：CAS V1 边界决策。 -- `docs/architecture/adr/0003-cas-core-interface-and-error-boundary.md`：CAS 核心接口和错误边界冻结。 +这些文件描述如何使用或验证已经存在的能力： -后续建议新增： +- `docs/guides/development.md`：本地开发、测试、调试和代码质量流程。 +- `docs/guides/deployment.md`：部署、systemd、Docker 和运维说明。 +- `docs/guides/official-resource-test-pull.md`：官方资源拉取与自动更新运行指南。 +- `docs/guides/official-full-pull-smoke.md`：真实官方全量拉取 smoke runbook。 +- `docs/guides/bat-api-local-live-smoke.md`：Rust `bat` 与 Go `bat-api` 同机 live 联调。 +- `docs/guides/bat-workflows.md`：`res`、`parse`、`i18n` 工作流和调度接口。 +- `docs/guides/baseline.md`：稳定工程基线和合并前检查。 +- `scripts/check-doc-status.sh`：当前状态、占位目录和关键契约文字门禁。 +- `scripts/check-doc-links.sh`：全仓库 Markdown 本地链接门禁。 -- `docs/architecture/cas.md`：CAS 生产级设计。 -- `docs/architecture/translation.md`：翻译系统设计。 +`deployments/` 下的 systemd、Docker、环境文件和数据库配置是部署材料，不作为独立架构文档；其行为说明以本节指南和当前源码为准。 ---- +## 5. 分析资料和机器产物 -## 3. 分析资料 +以下资料用于分析或测试，不是当前能力声明： -- `docs/assetbundle_analysis.json`：AssetBundle 分析资料。 -- `docs/textassets_analysis.json`：TextAsset 分析资料。 -- `docs/archive/BLUE_ARCHIVE_TECHNICAL_ANALYSIS.md`：历史技术分析。 -- `docs/archive/ARCHITECTURE_REVIEW.md`：历史架构审查。 -- `docs/archive/ARCHITECTURE_REVIEW_SUMMARY.md`：历史架构审查摘要。 -- `docs/archive/READY_FOR_PHASE_1.md`：历史 Phase 1 准备文档。 -- `docs/archive/REFACTOR_CHECKLIST.md`：历史重构清单。 +- `docs/assetbundle_analysis.json`：AssetBundle 分析数据。 +- `docs/textassets_analysis.json`：TextAsset 分析数据。 +- `adapters/tests/fixtures/`、`adapters/tests/golden/`：Manifest / Addressables fixture 和 golden。 +- `infrastructure/tests/fixtures/`、`infrastructure/tests/golden/`：官方同步和导入 fixture。 +- `internal/api/testdata/contract/`：Rust-Go contract mirror 和 Go contract tests 输入。 +- `internal/api/testdata/release/`：`bat-api` 本地 release fixture。 ---- +测试 fixture 可以证明特定行为，但不能单独证明对所有真实官方格式的完整支持；真实样本和运行 smoke 仍需单独标注。 -## 4. 历史报告 +## 6. 模块状态说明 -历史报告已按来源和主题归档，供追溯使用，不再代表当前状态。 +以下 README 是模块占位或边界说明，不是完整实现文档： +- `api/README.md` +- `api/proto/README.md` +- `api/openapi/README.md` +- `internal/config/README.md` +- `internal/downloader/README.md` +- `internal/extractor/README.md` +- `internal/manifest/README.md` +- `internal/storage/README.md` +- `pkg/README.md` +- `pkg/cas/README.md` +- `pkg/translator/README.md` +- `pkg/types/README.md` +- `web/README.md` +- `web/admin/README.md` +- `web/shared/README.md` + +这些目录的实现状态以 `docs/reports/GO_STATUS.md`、对应源码和测试为准；不能因为目录或 README 存在就视为模块已完成。 + +## 7. 历史归档 + +以下内容只用于追溯，不能作为当前实现、当前优先级或当前测试结果的证据： + +- `docs/archive/`：早期架构审查、技术分析、重构清单和 Phase 1 准备材料。 - `docs/reports/historical/root/`：原根目录阶段报告。 -- `docs/reports/historical/current-stage/`：已被 `CURRENT_STATUS.md` 和当前指南取代的阶段交接、推送前核查报告。 -- `docs/reports/historical/week2/`：Week 2 相关报告。 -- `docs/reports/historical/week3/`：Week 3 相关报告。注意：这些报告中存在“完成”和“回滚”的冲突描述。 -- `docs/reports/historical/build-logs/`：历史构建、测试、Clippy 输出。 +- `docs/reports/historical/current-stage/`：已被当前状态和指南取代的阶段交接报告。 +- `docs/reports/historical/week2/`：Week 2 报告和当时的构建/测试输出。 +- `docs/reports/historical/week3/`：Week 3 报告；其中存在互相冲突的完成描述。 +- `docs/reports/historical/build-logs/`：历史构建、测试和 Clippy 输出。 - `docs/reports/historical/quality/`：历史质量报告。 -- `docs/reports/historical/nested-docs/`：从误嵌套 `docs/docs` 移出的报告。 +- `docs/reports/historical/nested-docs/`：从旧目录结构迁移出来的历史报告。 ---- +## 8. 推荐阅读顺序 -## 5. 当前阅读顺序 - -新开发者或新会话建议按以下顺序阅读： - -1. `CURRENT_STATUS.md` -2. `PROJECT_PLAN.md` -3. `docs/guides/official-resource-test-pull.md` -4. `docs/guides/official-full-pull-smoke.md` -5. `docs/guides/bat-api-local-live-smoke.md` -6. `docs/guides/bat-workflows.md` -7. `docs/architecture/official-resource-backend.md` +1. `README.md` +2. `CURRENT_STATUS.md` +3. `PROJECT_PLAN.md` +4. `docs/reports/CURRENT_GAPS.md` +5. `docs/reports/GO_STATUS.md` +6. `docs/architecture/official-resource-backend.md` +7. `docs/architecture/resource-release-layout.md` 8. `docs/reference/rpc-backend-api.md` -9. `docs/reports/CURRENT_GAPS.md` -10. `docs/guides/baseline.md` -11. `docs/architecture/README.md` +9. `docs/architecture/assetbundle.md` +10. `docs/guides/official-resource-test-pull.md` +11. `docs/guides/bat-workflows.md` 12. `docs/guides/development.md` 13. `CONTRIBUTING.md` 14. `AGENTS.md` ---- - -## 6. 状态摘要 - -当前总体完成度不再固定写单一百分比，以 `CURRENT_STATUS.md` 和 `CURRENT_GAPS.md` 的模块状态为准。 - -已完成： - -- Rust 领域模型和仓储接口骨架。 -- Unity/Manifest/Client 适配器框架。 -- CAS V1：原子写入、BLAKE3 校验、引用计数、GC、并发测试和损坏检测。 -- 文档整理和路线图重制。 -- Rust 官方资源同步闭环：`bat`、`--auto-discover`、`--watch`、`--daemon`、Unix socket JSON-RPC 后台控制、`status`、`stop`、`restart`、`reload`、`refresh`、`logs`、`verify`、`repair`、`doctor`、`clean-stable`、北京时间固定强制刷新、snapshot、manifest audit/repair、官方 seed `.hash` 校验。 -- 官方 release 历史文件与 CAS 对象复用：复用前执行 size、BLAKE3 和 ZIP 结构校验，失败回退网络，引用写入版本化清单并由清理流程回收。 -- 官方原版资源与汉化产物目录分离：`./bat-resources` 只承载原版 release，`./bat-localized` 承载后续汉化 release；当前官方同步报告 `not_localized`，Patch 发布完成后才进入 `localized`。 -- 官方 release 会维护 `official-parse-cache.json`，用于跳过未变化资源的重复解析。 -- `bat-api/internal/backendrpc` typed Unix socket JSON-RPC client。 -- `cmd/bat-api` 资源分发 HTTP MVP 与内嵌 dashboard（进度见 `docs/reports/GO_STATUS.md`）。 -- 真实官方网络全量拉取 smoke 已固化为 `scripts/official-full-pull-smoke.sh` 和 `make official-smoke`，默认写入 `/tmp` 隔离目录并输出本地运行报告。 -- `bat-api` 同机 live smoke 已固化为 `scripts/bat-api-local-live-smoke.sh` 和 `make bat-api-local-live-smoke`，覆盖真实 `bat.sock`、release 切换、未 ready、恢复和 CDN 读路径。 -- `bat` 运行时 progress log 已覆盖下载已完成计数、单文件下载进度和校验结果摘要。 -- `bat` 前台结果渲染与终端诊断输出已分别收敛到 `report_output.rs` 和 `terminal_output.rs`，CLI 流程模块只负责编排。 -- Addressables 当前真实形态 fixture/golden 覆盖。 -- 解析补全路线图已固化到 `docs/architecture/assetbundle.md`：解析缓存、Addressables、UnityFS、Serialized 字段级解析、文本提取、CAS 接入和 Patch 发布前置。 -- SQLite Resource Repository 和可选无状态 `bat-ffi` JSON 兼容接口。 - -优先待办： - -- `bat-api` 与完整官方网络长期运行（独立于 issue #19 的 `make official-smoke` 跟踪）。 -- 扩展 CAS + ResourceRepository 的用户级查询、翻译记忆和通用 Patch 发布资源视图。 -- 推进 AssetBundle UnityFS 引擎级解析。 +阅读顺序中的状态和契约结论必须回到当前源码、测试和实际命令验证；历史报告只用于解释演进过程。 diff --git a/Makefile b/Makefile index 16a6815..55103b7 100644 --- a/Makefile +++ b/Makefile @@ -72,11 +72,7 @@ test-go-all: test-go-api test-go-ffi ## 全部 Go 测试 bench: ## 运行性能基准测试 @echo "$(BLUE)Running benchmarks...$(NC)" cargo bench --workspace - @if [ -n "$$(go list ./... 2>/dev/null)" ]; then \ - go test -bench=. -benchmem ./...; \ - else \ - echo "$(YELLOW)No Go packages yet, skipping Go benchmarks...$(NC)"; \ - fi + go test -bench=. -benchmem ./... official-smoke: ## 运行真实官方全量拉取 smoke（默认写入 /tmp 隔离目录） @echo "$(BLUE)Running official full pull smoke...$(NC)" @@ -98,11 +94,7 @@ check-rust: ## 检查 Rust 代码 check-go: ## 检查 Go 代码 @echo "$(BLUE)Checking Go code...$(NC)" - @if [ -n "$$(go list ./... 2>/dev/null)" ]; then \ - go vet ./...; \ - else \ - echo "$(YELLOW)No Go packages yet, skipping...$(NC)"; \ - fi + go vet ./... check-docs: ## 检查权威状态文档与占位目录声明 @echo "$(BLUE)Checking documentation status claims...$(NC)" @@ -116,17 +108,13 @@ fmt-rust: ## 格式化 Rust 代码 fmt-go: ## 格式化 Go 代码 @echo "$(BLUE)Formatting Go code...$(NC)" - @if [ -n "$$(go list ./... 2>/dev/null)" ]; then \ - go fmt ./...; \ - else \ - echo "$(YELLOW)No Go packages yet, skipping...$(NC)"; \ - fi + go fmt ./... lint: lint-rust lint-go ## 运行所有 Linter lint-rust: ## Rust Clippy 检查 @echo "$(BLUE)Running Clippy...$(NC)" - cargo clippy --workspace -- -D warnings + cargo clippy --workspace --all-targets -- -D warnings lint-go: ## Go Linter 检查 @echo "$(BLUE)Running golangci-lint...$(NC)" diff --git a/PROJECT_PLAN.md b/PROJECT_PLAN.md index 0be29d9..49f92e7 100644 --- a/PROJECT_PLAN.md +++ b/PROJECT_PLAN.md @@ -1,8 +1,8 @@ # BlueArchiveToolkit 完整开发计划 - **项目名称**：BlueArchiveToolkit -- **文档版本**：2026-09-02 状态复核版 -- **权威状态**：以本文档和 `CURRENT_STATUS.md` 为准，旧阶段报告仅作历史参考。 +- **文档版本**：2026-09-04 状态复核版 +- **文档角色**：长期目标、里程碑和路线图；当前实现以源码、测试、稳定契约和 `CURRENT_STATUS.md` 为准，旧阶段报告仅作历史参考。 - **最终目标**：构建一个可长期维护、可扩展、可审计的 Blue Archive 资源管理、文本提取、翻译和补丁平台。 --- @@ -22,7 +22,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付 ## 2. 当前真实状态 -本节来自 2026-09-02 的工作区盘点、本地验证和最新功能提交。 +本节来自 2026-09-04 的工作区盘点、本地验证和最新功能提交。 ### 已具备 @@ -36,18 +36,18 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付 8. `bat-ffi` 已提供 Manifest inspect 和官方 sync plan 的可选无状态粗粒度 JSON C ABI helper。 9. 官方原版资源默认发布到 `./bat-resources`，汉化产物默认发布到独立的 `./bat-localized`；当前官方同步报告会标记 `localized_release_status=not_localized`，表示原版资源已发布、汉化资源未发布；`translation.proofread` 可把汉化 workflow 标记为人工校对中，但不会覆盖已发布的汉化 release。 10. 官方同步校验完成并发布新 release 后会生成 `official-resource-changes.json`、`crowdin-translation-handoff.json`、`official-parse-cache.json`、`official-textunit-index.json`、`official-textunit-tasks.json` 和 `crowdin-textunit-queue.json`，用 Added/Modified 资源驱动后续解析/翻译增量；up-to-date 轮询在已有有效缓存、TextUnit 明细索引和队列时只读取摘要，不重复解析。 -11. issue 43 已补齐 Rust `bat` 的 `res` / `parse` / `i18n` 工作流：单次/限定次数/周期执行、版本化 schedule CRUD 与作用域过滤、解析缓存清理、翻译工作台校验、离线翻译工作台、人工文本查看/修改/清空、翻译任务状态回写、人工校对状态标记、既有 patch 能力的批量重打包和独立汉化 release 发布；issue 44 已接入 `translation.worker.run` provider worker，默认并发 8、范围 `1..=256`，每个 worker 独立 claim 下一项任务并落库 lease、失败分类、重试计划和 TextUnit 译文结果；issue 46 已提供 `bat-api` 内嵌 dashboard MVP，直接调用已有鉴权接口控制资源、调度、任务、日志、parse、翻译和 localized 发布/回滚；schedule CRUD、`translation.tasks` / `translation.handoff`、`translation.task.update`、`translation.worker.run` 和 `translation.proofread` 已经通过 `bat.sock` 和 `bat-api` 管理接口暴露，dashboard 不维护第二套状态；该能力不扩大冻结期解析器覆盖。 +11. Rust `bat` 已提供 `res` / `parse` / `i18n` 工作流：单次/限定次数/周期执行、版本化 schedule CRUD 与作用域过滤、解析缓存清理、翻译工作台校验、离线翻译工作台、人工文本查看/修改/清空、翻译任务状态回写、人工校对状态标记、既有 patch 能力的批量重打包和独立汉化 release 发布；`translation.worker.run` 已接入 provider worker，默认并发 8、范围 `1..=256`，每个 worker 独立 claim 下一项任务并落库 lease、失败分类、重试计划和 TextUnit 译文结果；`bat-api` 已提供内嵌 dashboard MVP，直接调用已有鉴权接口控制资源、调度、任务、日志、parse、翻译和 localized 发布/回滚；schedule CRUD、`translation.tasks` / `translation.handoff`、`translation.task.update`、`translation.worker.run` 和 `translation.proofread` 已经通过 `bat.sock` 和 `bat-api` 管理接口暴露，dashboard 不维护第二套状态；新解析覆盖仍需真实 fixture 和回归验收。 12. 文档已整理：根目录保留入口文档，历史报告进入 `docs/reports/historical/`，误嵌套的 `docs/docs` 已合并。 ### 仍是骨架或占位 1. `bat-assetbundle` 已具备 UnityFS 解包和 TextAsset 提取基础能力（header/block info/directory、LZ4/LZMA block info 与数据 block、directory 文件提取、serialized file object table、TypeTree node 元数据、TextAsset bytes、TypeTree-covered managed reference payload TextUnit 上下文），并已有受支持 localized patch 发布能力；MonoBehaviour/ScriptableObject 复杂字段级解析、整体重打包和通用 Patch 仍未完成。 2. `bat-patch` 已具备确定性 Binary hunk diff/apply、RFC 6902 JSON Patch apply、UTF-8 Text Patch、通用 Patch manifest、BLAKE3/size 完整性校验和 rollback 元数据；文件级 `patch.apply` RPC / `patch-apply` CLI 与 UnityFS TextAsset / TypeTree string / TypeTree 语义字段写入入口已开放，`bat-assetbundle` + `LocalizedPatchService` 已完成受支持 TextUnit 到 localized patch manifest、独立 staging、发布和 rollback 闭环，通用 manifest 发布与整体 AssetBundle 重打包仍后置。 -3. Go 侧边界已冻结（见 `docs/reports/GO_STATUS.md`）：同步/运维命令行 = Rust `bat`；资源分发和内嵌 dashboard = `cmd/bat-api` MVP；`internal/backendrpc` 完成；`cmd/bat` 仅为试验（`bin/bat-go`）。完整游戏业务 API / 完整 Web 协作后台 / SDK 仍未完成。 +3. Go 侧边界已确定（见 `docs/reports/GO_STATUS.md`）：同步/运维命令行 = Rust `bat`；资源分发和内嵌 dashboard = `cmd/bat-api` MVP；`internal/backendrpc` 完成；`cmd/bat` 仅为试验（`bin/bat-go`）。完整游戏业务 API / 完整 Web 协作后台 / SDK 仍未完成。 4. Addressables parser 已覆盖当前真实形态 fixture/golden，但还不是完整 Unity Addressables/SBP catalog 兼容层。 5. 官方同步结果可配置为发布后自动导入 CAS + ResourceRepository，并通过 `resource.index` RPC/CLI 查询；Resource metadata 已保存 release、平台、bundle path、parse status、TextAsset 名称和 TextUnit 摘要，资源级查询已覆盖 release、平台、destination、archive entry、parse status 和 TextUnit format；单条 TextUnit 明细和解析错误已持久化到 `official-textunit-index.json`，可通过 `parse.text_units` / `parse.errors` 查询；离线 TextUnit 翻译任务状态和跳过/失败原因可通过 `translation.tasks` 查询，`translation.task.update` 已提供 worker 状态回写 contract，`translation.worker.run` 已提供真实 provider worker 触发、lease/retry 和结果落库 contract，`translation.proofread` 已提供汉化 workflow 人工校对标记 contract。 6. 受支持汉化 Patch 发布已具备 UnityFS TextAsset、TypeTree string field 和 managed-reference string field 的 manifest/apply/rollback/完整性校验和 `localized.status` 严格校验；真实 provider worker 已接入，翻译记忆到完整汉化文件集合的构建仍未完成。 -7. 真实官方网络全量下载 smoke 已固化为可重复脚本和 runbook（G-018 已关闭）；真实运行记录处于长期运行测试阶段，报告待后续提供。 +7. 真实官方网络全量下载 smoke 已固化为可重复脚本和 runbook；真实运行记录处于长期运行测试阶段，报告待后续提供。 8. 内嵌 dashboard MVP 已实现；完整 Web 协作后台、数据库迁移、插件加载机制尚未实现；`bat-api` 资源 bootstrap/分发/OpenAPI/管理控制面已通过 `/openapi.yaml` 提供，完整游戏业务 API 的 OpenAPI 仍未完成。 9. 原 Git 历史未恢复；当前仓库以新初始化基线为准。 @@ -73,8 +73,8 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付 ### 3.2 技术决策 -1. **Rust**：保留为核心引擎语言，用于 CAS、AssetBundle、Patch、完整资源拉取和更新检查核心逻辑；`bat --json` 进程边界是当前主集成路径，FFI 仅作为可选兼容层。 -2. **Go**：用于最小稳定 CLI、服务编排、API Server、任务编排、Provider 集成；不强制要求 Rust 核心能力必须写成库供 Go 调用。 +1. **Rust**：保留为核心引擎语言，用于 CAS、AssetBundle、Patch、完整资源拉取和更新检查核心逻辑；`bat.sock` RPC 是 Go `bat-api` 的当前主集成边界，`bat --json` 是 Rust CLI 的机器输出形态，FFI 仅作为可选兼容层。 +2. **Go**：当前用于 `bat-api` 资源 bootstrap/分发和 Rust RPC 管理入口；完整服务编排、API Server、任务编排和 Provider 集成仍是目标能力，不强制要求 Rust 核心能力必须写成库供 Go 调用。 3. **PostgreSQL**：作为服务端主数据库，承载翻译记忆库、术语库、任务、审核和用户权限。 4. **SQLite**：仅作为本地 CLI 可选元数据后端，必须通过仓储抽象隔离，不能绑定业务逻辑。 5. **Redis**：用于服务端缓存、任务状态、限流和短期锁。 @@ -88,7 +88,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付 2. 公共接口具备文档、错误语义和兼容性说明。 3. 单元测试覆盖核心分支；跨模块能力补集成测试。 4. `cargo fmt`、`cargo clippy --workspace --all-targets -- -D warnings`、`cargo test --workspace` 通过。 -5. Go 模块落地后，`go test ./...`、`go vet ./...` 通过。 +5. Go 当前门禁通过 `make test-go-api`、`make build-go-api` 和 `go vet ./...`。 6. 用户可见命令必须有 `doctor` 检查和失败恢复建议。 --- @@ -174,14 +174,16 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付 交付物： 1. Addressables Catalog 目标字段解析：**当前目标完成**。JSON/compact 已覆盖 path、hash、size、address、dependencies、provider ID、bundle name、CRC、metadata，并通过 fixture/golden 与 SQLite 迁移回归；独立二进制 catalog 仍明确拒绝。 -2. 资源版本、区域、渠道、远端 URL、Hash、大小、依赖关系模型：**部分完成**。`Resource` 和官方 endpoint/snapshot 模型已扩展；仍需冻结 Go CLI/API 可见模型。 +2. 资源版本、区域、渠道、远端 URL、Hash、大小、依赖关系模型：**部分完成**。`Resource` 和官方 endpoint/snapshot 模型已扩展；Go CLI/API 可见模型仍需在稳定 contract 中继续收敛。 3. Rust 官方下载器：**已完成当前生产入口需要的核心能力**。包含官方 URL 校验、`.part` 续传、重试、本地 manifest size+BLAKE3 校验、官方 seed `.hash` 校验、repair、已发布历史 release/CAS 复用，以及默认 8、范围 `1..=256` 的有界并发 scheduler；worker 动态领取任务，进度按完成数单调上报，report 保持 plan 顺序，复用和网络传输分别统计。 4. Rust 自动更新入口：**已完成当前生产入口**。`bat` 支持 snapshot、marker diff、bootstrap cache、one-shot、`--watch`、`--daemon`、默认 1 小时间隔、北京时间固定强制刷新，以及 Unix socket JSON-RPC 后台运维命令返回。 -5. Go 入口边界：**已冻结**。同步命令行 = Rust `bat`（G-008 关闭）；资源分发 = `bat-api` MVP（G-009 部分完成）。详见 `docs/reports/GO_STATUS.md`。 -6. 用户级 `sync`、`manifest inspect`、`cache status`：**未完成**。Rust `bat --json` 是当前稳定进程边界；`bat-ffi` 只提供可选兼容用的 Manifest inspect 和 sync plan JSON helper。 +5. Go 入口边界：**已确定**。同步命令行 = Rust `bat`；资源分发 = `bat-api` MVP。详见 `docs/reports/GO_STATUS.md`。 +6. Go 用户级 `sync`、`manifest inspect`、`cache status`：**未完成**。Rust `bat` + 是当前正式资源同步 CLI，`bat --json` 是其机器输出形态；`bat-ffi` 只提供可选 + 兼容用的 Manifest inspect 和 sync plan JSON helper。 7. 下载结果写入 CAS + ResourceRepository：**基础能力可用，查询面仍部分完成**。CAS 和 SQLite ResourceRepository 已存在，官方同步入口可用 `--import-repository` / `BAT_IMPORT_REPOSITORY=1` 在已校验 release 发布后导入；`resource.index` 可按资源级 release、平台、destination、bundle path、archive entry、parse status 和 TextUnit format 查询现有索引和资源 metadata，常用 metadata 过滤已下推到 SQLite；`bat doctor cas` 可只读诊断既有 CAS 根目录、对象目录、元数据库文件和对象统计；`parse.text_units` / `parse.errors` 可查询当前 release 的 TextUnit 明细与解析错误；`translation.tasks` 可查询离线 TextUnit 翻译任务状态、跳过/失败原因和 worker 结果。剩余工作是更丰富的 TextUnit 查询、翻译记忆查询和通用 Patch 发布所需资源视图。 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 的可重复流程；真实运行处于长期运行测试阶段，报告待后续提供。 +9. 真实官方网络全量下载 smoke test：**命令已固化**。`scripts/official-full-pull-smoke.sh` / `make official-smoke` 已固化 dry-run、首次下载、二次 up-to-date 和本地损坏 repair 的可重复流程；真实运行处于长期运行测试阶段，报告待后续提供。 10. 官方发布后的增量 handoff 与解析缓存：**已完成基础入口**。新 release 发布后先生成 `official-resource-changes.json` 和 `crowdin-translation-handoff.json`，新增+变更资源进入解析/翻译候选；`official-parse-cache.json` 基于下载 manifest 覆盖直接 UnityFS bundle、zip 内 UnityFS 条目和非候选资源记录；随后生成 `official-textunit-index.json`、`official-textunit-tasks.json` 与 `crowdin-textunit-queue.json`，本地文件未变化且缓存/索引有效时跳过重复解析。 11. 汉化发布状态：**受支持范围已完成闭环**。官方同步默认报告 `not_localized`，表示只发布原版资源；TextAsset、TypeTree string field 和 managed-reference string field patch 发布成功并通过 `localized-patch-manifest.json`、current symlink、release ID 和 rollback 校验后才切换为 `localized`，可通过 `localized.publish` / `localized.rollback` 与 bat-api 管理接口控制。 @@ -203,7 +205,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付 ### Milestone 4：Unity AssetBundle 解析 -维护冻结细则见 [`docs/reports/PARSER_FREEZE.md`](docs/reports/PARSER_FREEZE.md)；冻结期只接受稳定性、诊断、真实回归和文档一致性修复。 +当前解析扩展按路线图和真实回归继续推进。 **目标**：建立可扩展 AssetBundle 解析框架，并首先支持文本相关资源。 @@ -213,7 +215,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付 2. **Addressables 完整化**：覆盖 Windows/Android JSON、compact JSON 和后续二进制 catalog 入口，解析 provider、internal id、primary key、dependency、bundle name、hash、size、CRC 和资源类型。 3. **UnityFS 容器层**：基础目标已完成 header、block info、directory、data block、LZ4/LZMA、alignment、总大小/计数/路径/边界错误、directory 文件提取和 UnityPy 真实样本回归；复杂版本差异和发布级重打包另行推进。 4. **Serialized file 层**：稳定 Unity serialized file header、type table、TypeTree node、object table、path id、class id 和 raw object bytes 表示。 -5. **字段级解析层**：实现 TypeTree 字段 reader，支持 bool、integer、float、string、bytes、array、vector/staticvector 嵌套 `Array`、`List` / `HashSet` 集合 alias、map、PPtr、enum `value__` backing field、`LayerMask` / `BitField` 的 `m_Bits` backing field、常见固定 Unity float/int/hash 值类型的 leaf/direct-child 形态、unknown fixed-size raw bytes 保留和同长度替换、TypeTree-covered managed reference / `SerializedReference` alias 和 TypeTree-covered managed reference registry 记录；managed-reference full typename 可拆为 assembly/namespace/class，常见 `m_ManagedReferences` / `RefIds` / verbose type 字段命名、`managedReference*` / `serializedReference*` metadata 和 `data` / `value` / `payload` / `object` / `managedReferencePayload` / `referencePayload` / `serializedReferencePayload` / `managedReferenceValue` / `referenceValue` / `serializedReferenceValue` / `managedReferenceObject` / `referenceObject` / `serializedReferenceObject` / `managedReferenceData` / `referenceData` / `serializedData` / `serializedReferenceData` payload 命名已有回归覆盖，TextUnit 只提取 payload 字符串并按结构化 record、`RefIds[n]` 等记录前缀或子字段保留类型上下文；array/vector/List/HashSet/map 元素与 registry payload 字段保留独立 field path、offset 和 byte size，可支撑字符串元素、managed-reference registry payload 字段、基础语义字段 patch、enum/bit_field 语义 patch、固定值类型 patch、unknown fixed-size bytes patch、object 字段组合和 TypeTree schema 支撑的 array/vector/List/HashSet/map 整体变长替换，`first/second` 与 `key/value` map entry schema 已有回归覆盖；解析模块当前处于维护冻结，未见样本驱动的完整 managed reference registry / map entry 变体和 unknown 字段结构语义暂不继续扩展，除非属于冻结规则允许的稳定性修复。 +5. **字段级解析层**：实现 TypeTree 字段 reader，支持 bool、integer、float、string、bytes、array、vector/staticvector 嵌套 `Array`、`List` / `HashSet` 集合 alias、map、PPtr、enum `value__` backing field、`LayerMask` / `BitField` 的 `m_Bits` backing field、常见固定 Unity float/int/hash 值类型的 leaf/direct-child 形态、unknown fixed-size raw bytes 保留和同长度替换、TypeTree-covered managed reference / `SerializedReference` alias 和 TypeTree-covered managed reference registry 记录；managed-reference full typename 可拆为 assembly/namespace/class，常见 `m_ManagedReferences` / `RefIds` / verbose type 字段命名、`managedReference*` / `serializedReference*` metadata 和 `data` / `value` / `payload` / `object` / `managedReferencePayload` / `referencePayload` / `serializedReferencePayload` / `managedReferenceValue` / `referenceValue` / `serializedReferenceValue` / `managedReferenceObject` / `referenceObject` / `serializedReferenceObject` / `managedReferenceData` / `referenceData` / `serializedData` / `serializedReferenceData` payload 命名已有回归覆盖，TextUnit 只提取 payload 字符串并按结构化 record、`RefIds[n]` 等记录前缀或子字段保留类型上下文；array/vector/List/HashSet/map 元素与 registry payload 字段保留独立 field path、offset 和 byte size，可支撑字符串元素、managed-reference registry payload 字段、基础语义字段 patch、enum/bit_field 语义 patch、固定值类型 patch、unknown fixed-size bytes patch、object 字段组合和 TypeTree schema 支撑的 array/vector/List/HashSet/map 整体变长替换，`first/second` 与 `key/value` map entry schema 已有回归覆盖；解析模块当前仍有真实版本差异、未见样本驱动的完整 managed reference registry / map entry 变体和 unknown 字段结构语义需要继续推进。 6. **文本对象入口**：实现 TextAsset、MonoBehaviour、ScriptableObject 的可扩展提取入口，输出可追溯到 bundle、serialized file、path id 和 field path 的文本定位。 7. **工具与接口**：编写 `bundle inspect`、`bundle extract`、`text extract` 的最小稳定入口；CLI/RPC/API 使用解析器输出，不直接耦合解析内部结构。 8. **汉化发布前置**：解析结果必须能作为 Patch 输入；Patch 发布阶段才写入 `--localized-output` / `BAT_LOCALIZED_OUTPUT` 配置的汉化输出目录并切换 `localized` 状态。 @@ -366,7 +368,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付 交付物： -1. 发布验证：format、lint、test、build、security audit、release artifact 由本地可重复命令、自托管 Gitea linux-runner workflow 与脚本承担（决策：不引入 GitHub Workflows 等托管 CI，见 `docs/reports/CURRENT_GAPS.md` G-017）。 +1. 发布验证：format、lint、test、build、security audit、release artifact 由本地可重复命令、自托管 Gitea linux-runner workflow 与脚本承担；当前不引入托管 CI。 2. Docker Compose：本地开发、服务端部署。 3. 数据备份与恢复文档。 4. 用户文档、开发文档、故障排查文档。 @@ -396,16 +398,15 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付 --- -## 6. 近期具体任务 +## 6. 当前开发入口 -优先完善 Rust 解析与资源库接入，并联调 Go 资源分发。边界见 `docs/reports/GO_STATUS.md`： +当前优先推进 Rust 解析、资源库查询和翻译发布能力。边界见 +`docs/reports/GO_STATUS.md`： -1. issue #17 已关闭（顺序下载 + 指数退避）。 -2. G-008 已决策关闭：同步/运维命令行 = 近乎全自动的 Rust `bat`。 -3. G-009 / issue #19：`bat-api` 资源分发和同机 `bat.sock` live 联调已完成；拉取仍在 Rust `bat`。 -4. 继续 Addressables 结构变体与 UnityFS 复杂对象能力（issue #3 / G-005 的后续阶段）。 -5. 基于 `translation.worker.run` 继续推进翻译记忆和 Patch 构建。 -6. 继续扩展 G-011 剩余查询面：更丰富的 TextUnit 查询、翻译记忆查询和通用 Patch 发布所需资源视图。 +1. 继续 Addressables 结构变体与 UnityFS 复杂对象能力。 +2. 基于 `translation.worker.run` 继续推进翻译记忆和 Patch 构建。 +3. 继续扩展资源库剩余查询面：更丰富的 TextUnit 查询、翻译记忆查询和通用 Patch 发布所需资源视图。 +4. 在隔离环境执行真实官方网络长期运行 smoke，并保留运行报告。 --- @@ -413,7 +414,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付 ### SQLite 权限问题 -旧 Week 3 报告提到 SQLite 文件权限导致测试失败。处理策略： +本地 SQLite 元数据后端的权限和恢复风险需要通过显式测试覆盖。处理策略： 1. 本地元数据后端必须使用临时目录和明确权限测试。 2. SQLite 只作为 adapter，不进入领域层。 @@ -433,7 +434,7 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付 处理策略： 1. Rust 提供稳定引擎能力，并在当前阶段承担可生产运行的官方资源同步 CLI、watch 和 daemon。 -2. Go 的长期职责包括资源分发 HTTP（`bat-api`）、服务编排、网络和 Provider；同步/运维命令行由近乎全自动的 Rust `bat` 承担。不能把试验性 `cmd/bat` 视为产品 CLI。 +2. Go 的目标职责包括资源分发 HTTP（当前为 `bat-api`）、服务编排、网络和 Provider；同步/运维命令行由近乎全自动的 Rust `bat` 承担。不能把试验性 `cmd/bat` 视为产品 CLI。 3. 跨边界优先进程或 SDK，FFI 只作为可选的粗粒度、无状态、安全、可测试兼容 API。 4. Rust 不需要被强制写成 Go 调用库；当前 `bat --watch` / `bat --daemon` 是允许长期运行的 Rust 生产任务。 @@ -446,22 +447,22 @@ BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付 3. smoke test 只记录命令、状态和摘要，不把大体积官方资源纳入 Git。 4. 下载成功后必须通过 `official-download-manifest.json` audit 和官方 seed `.hash` 校验报告确认。 -### 过早做 Web +### Web 范围控制 处理策略： -1. Web 依赖可用 API 和数据库，不应早于核心同步、提取、翻译模型。 -2. 先完成 CLI 和 API，再构建 Web。 +1. 当前内嵌 dashboard 只编排已有 API，不维护第二套业务状态。 +2. 完整协作后台应在权限、翻译模型和持久化 API 明确后继续建设。 --- ## 8. 当前完成度评估 -按最终目标计算，当前总体完成度不再固定写单一百分比，以模块状态和 issue 收敛情况为准。 +按最终目标计算，当前总体完成度不固定写单一百分比，以模块状态、源码、测试和契约为准。 已完成的是稳定基线、架构骨架、部分接口、CAS V1、Rust 官方资源同步闭环、可配置 CAS/ResourceRepository 导入、TextUnit 明细索引/查询、增量 Crowdin 离线队列、provider worker、通用 Binary/JSON/Text Patch 基础、受支持 localized patch 发布/rollback，以及 Go `bat-api` 资源分发、内嵌 dashboard 和同机 live 联调。下一阶段的关键是翻译记忆、通用 manifest 发布、复杂 AssetBundle 解析/重打包和官方资源长期运行报告。 --- -- **下一份应更新文档**：真实官方网络 smoke 记录 +- **下一份应补充的验证材料**：真实官方网络 smoke 运行记录 - **下一项工程任务**：推进翻译记忆、通用 manifest Patch 构建、复杂 AssetBundle 解析，并持续执行官方资源长期运行 smoke。 diff --git a/README.md b/README.md index 14505e7..4599531 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,8 @@ - `bat-infrastructure` CAS 适配层、SQLite Resource Repository、资源导入服务、官方资源 pull/update 服务。 - `bat`：官方资源自动发现、全量拉取、原子发布到 `current -> versions/`、本地 manifest audit/repair、`.part` 断点续传、403/404/5xx 分类重试、指数退避、默认并发 8（可配置 `1..=256`，report 按 plan 顺序、进度按完成数单调上报）、已发布历史 release 与 CAS 复用、下载 quarantine 诊断、ZIP 结构校验、官方 seed `.hash` 校验、snapshot/cache、版本化 `official-launcher-bootstrap.json`、`--watch` 常驻更新、`--daemon` 后台运行，以及 Unix socket JSON-RPC live control/backend 方法（`daemon.*`、`resource.*`、`parse.*`、`translation.tasks/handoff/task.update`、`localized.status`、`catalog.*`、`task.*`、`patch.apply`、`unityfs.patch_*`）。 - `internal/backendrpc`：Go 侧 typed Unix socket JSON-RPC client，是 `bat-api` 调用 Rust daemon 的默认路径。 -- `cmd/bat-api`：资源 bootstrap + 分发 HTTP MVP（issue #19 / G-009）；`/v1/bootstrap` 和 `/v1/launcher/bootstrap` 组织 `bat` 已发布 release 的启动前资源入口，launcher 形状兼容端点仅输出资源 metadata / GameMainConfig 引导，`/healthz` 暴露 RPC refresh 诊断，`/readyz` 做 release readiness，CDN path 支持 `GET`/`HEAD`/`Range`、ETag、Last-Modified 和缓存头；玩家-facing 控制面已具备 token 鉴权、限流、访问日志、反代 IP 适配、动态 JSON no-store、OpenAPI、管理控制白名单、task/log/parse/translation admin 查询控制入口和无构建内嵌 dashboard；`.env` 配置端口/RPC socket/刷新周期；生产资源根和长期状态来自 RPC，不负责自动拉取。 -- Go 边界权威说明：[`docs/reports/GO_STATUS.md`](docs/reports/GO_STATUS.md)（G-008 已关闭：同步 CLI = Rust `bat`）。 +- `cmd/bat-api`：资源 bootstrap + 分发 HTTP MVP（G-009）；`/v1/bootstrap` 和 `/v1/launcher/bootstrap` 组织 `bat` 已发布 release 的启动前资源入口，launcher 形状兼容端点仅输出资源 metadata / GameMainConfig 引导，`/healthz` 暴露 RPC refresh 诊断，`/readyz` 做 release readiness，CDN path 支持 `GET`/`HEAD`/`Range`、ETag、Last-Modified 和缓存头；玩家-facing 控制面已具备 token 鉴权、限流、访问日志、反代 IP 适配、动态 JSON no-store、OpenAPI、管理控制白名单、task/log/parse/translation admin 查询控制入口和无构建内嵌 dashboard；`.env` 配置端口/RPC socket/刷新周期；生产资源根和长期状态来自 RPC，不负责自动拉取。 +- Go 边界权威说明：[`docs/reports/GO_STATUS.md`](docs/reports/GO_STATUS.md)（同步 CLI = Rust `bat`）。 - 官方同步会维护 `/official-version-state.json`，明确记录当前已完成版本、正在拉取版本、上一个可用版本和失败版本。 - 资源导入链路可配置为在官方 release 发布后写入 CAS + `ResourceRepository`，资源 metadata 会记录 release、平台、bundle path、parse status、TextAsset 名称和 TextUnit 数量/格式，TextAsset/Table/Media 会按类型分类索引；`resource.index` RPC/CLI 可按类型、hash、路径模式、官方 release ID、平台、destination、bundle path、archive entry、parse status 和 TextUnit format 分页查询索引，常用 metadata 过滤会下推到 SQLite；历史 release 复用会重新校验 size、BLAKE3 和 ZIP 结构，失败时按历史 release、CAS、网络顺序回退，CAS 引用记录在 `official-cas-reuse-references.json` 中；`bat doctor cas` 可只读诊断既有 CAS 目录、对象数、对象字节数和元数据库文件状态。 - 新 release 发布后会生成 `official-resource-changes.json`、`official-parse-cache.json`、`official-textunit-index.json`、`official-textunit-tasks.json`、`crowdin-translation-handoff.json`、`crowdin-textunit-queue.json`、`translation-tasks.sqlite` 和 `translation-handoff.json`；其中 TextUnit/Crowdin 队列只使用 Added/Modified 资源，不调用 Crowdin 网络 API，离线 TextUnit 翻译任务可通过 `translation.tasks` / `translation.handoff` RPC 或 CLI 查询状态、跳过/失败原因和 provider run 交接。 @@ -52,17 +52,21 @@ 前置要求： - Rust 1.75+ -- Go 1.22+ +- Go 1.26.4+ - `curl` - `unzip`，仅旧版 launcher manifest 指向整包 ZIP 且 `--auto-discover` 需要从 ZIP 解析 `GameMainConfig` 时使用；当前目录型 manifest 会直接下载 `resources.assets` 运行当前通用验证： ```bash +cargo fmt --all -- --check +cargo check --workspace cargo test --workspace cargo clippy --workspace --all-targets -- -D warnings -go test ./... +make test-go-api +make build-go-api go vet ./... +make check-docs ``` 查看官方同步命令： diff --git a/docs/architecture/README.md b/docs/architecture/README.md index eb698c484..7e4a2e8 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -4,7 +4,7 @@ BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建一个可持续维护十年以上的工业级开源项目。 -当前文档描述目标架构和已经落地的关键边界。它不是部署手册；当前可部署能力包括 Rust 官方资源同步任务和 Go `cmd/bat-api` 资源 bootstrap/分发服务。完整游戏业务 API、Web、Provider 编排和 SDK 仍未完成，实际实现状态以根目录 `CURRENT_STATUS.md` 和 `PROJECT_PLAN.md` 为准。 +当前文档描述目标架构和已经落地的关键边界。它不是部署手册；当前可部署能力包括 Rust 官方资源同步任务和 Go `cmd/bat-api` 资源 bootstrap/分发服务。完整游戏业务 API、Web、Provider 编排和 SDK 仍未完成，实际实现状态以源码、测试和根目录 `CURRENT_STATUS.md` 为准；`PROJECT_PLAN.md` 只描述目标和路线图。 当前已经可用的官方资源入口包括： @@ -25,9 +25,11 @@ BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建 已接受的架构决策： -- `adr/0001-engine-and-application-boundaries.md`：Rust 引擎与 Go 应用层边界。 +- `adr/0001-engine-and-application-boundaries.md`：历史语言/层次边界决策；资源同步职责已由 ADR 0004 取代。 - `adr/0002-cas-v1-design-boundary.md`：CAS V1 设计边界。 - `adr/0003-cas-core-interface-and-error-boundary.md`：CAS 核心接口与错误边界冻结。 +- `adr/0004-rust-bat-go-bat-api-resource-boundary.md`：当前 Rust `bat` 与 Go `bat-api` + 的资源控制面边界。 --- @@ -41,16 +43,30 @@ BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建 ### 2. 语言选型 -| 模块 | 语言 | 理由 | +| 模块 | 语言 | 当前定位 | |------|------|------| -| CLI、API Server、服务编排 | Go | 并发模型优秀、部署简单、生态成熟 | -| 官方资源同步核心、AssetBundle 解析、Patch 引擎、CAS 引擎 | Rust | 零成本抽象、内存安全、性能和二进制处理更可靠 | -| Web 管理后台 | Vue 3 + TypeScript | 渐进式、类型安全、生态完善 | +| 官方资源同步与运维 CLI、同步核心 | Rust | **当前实现**；`bat` 负责生产资源和长期状态 | +| 资源 bootstrap、只读分发和 Rust 管理入口 | Go | **当前实现**；`cmd/bat-api` 通过 `bat.sock` RPC 工作 | +| AssetBundle 解析、Patch 引擎、CAS 引擎 | Rust | **当前已有基础，复杂覆盖仍按路线图推进** | +| 完整 API、服务编排和 Provider | Go | **目标设计，尚未完整实现** | +| 完整 Web 协作后台 | Vue 3 + TypeScript | **目标设计**；当前只有内嵌 dashboard MVP | ### 3. 数据流设计 +当前已落地的数据流： + ``` -用户请求 → CLI/API → Go 业务层 → bat --json / SDK → Rust 核心/同步层 → CAS 存储 → 数据库 +官方 metadata → Rust bat / daemon → release + current + manifest + ↓ + bat.sock JSON-RPC + ↓ + Go bat-api → bootstrap / CDN / dashboard +``` + +目标扩展数据流（其中 Go 业务层、SDK、数据库和 Redis 尚未全部实现）： + +``` +用户请求 → CLI/API → Go 业务层 → bat.sock RPC / SDK → Rust 核心/同步层 → CAS 存储 → 数据库 ↓ ↓ Web UI 缓存层 (Redis) ``` @@ -99,7 +115,7 @@ cas/ --- -### 2. 官方资源同步器 (Rust 当前实现，Go 侧读取与编排) +### 2. 官方资源同步器 (Rust 当前实现，Go 侧读取) **职责**：从官方日服 HTTP metadata 自动发现资源入口，下载 Windows + Android 官方资源，增量检查，完整性校验，保持本地状态。 @@ -133,20 +149,24 @@ current symlink → official-sync-snapshot.json + official-download-manifest.jso - 本地文件损坏时 repair。 - 官方 seed `.hash` 强校验；Addressables `catalog_*.hash` 作为变更 marker。 -**后续 Go 职责**： +**Go 当前职责**： -- 提供最小稳定 CLI。 -- 默认通过 `bat --json` 进程边界包装 Rust 同步入口，并转发结构化 report。 -- `bat-ffi` 仅作为可选无状态 C ABI 兼容层，不承载官方同步 daemon、下载器或 CAS handle。 -- 编排 API Server、任务队列、Provider 和用户配置。 +- `bat-api` 通过 `bat.sock` RPC 读取 Rust 已发布 release、manifest、snapshot 和状态。 +- 提供资源 bootstrap、server-info 改写、只读 CDN path、readiness、OpenAPI 和白名单管理转发。 +- 不运行另一套同步器，不直接管理官方下载、staging、version-state、CAS 或解析状态。 + +完整 API、服务编排、Provider 和用户配置属于目标扩展，不能从本节推断为当前已实现。 --- -### 3. AssetBundle 解析器 (Rust) +### 3. AssetBundle 解析器 (Rust，当前基础与目标扩展) **职责**：解析 Unity AssetBundle，提取资源 -**插件化架构**： +以下插件注册和动态加载是目标扩展；当前实现以 `crates/bat-assetbundle`、 +`bat-adapters` 和真实 fixture 覆盖为准。 + +**目标插件化架构**： ```rust pub trait AssetParser { fn name(&self) -> &str; @@ -172,7 +192,11 @@ pub struct ParserRegistry { --- -### 4. 翻译系统 (Go) +### 4. 翻译系统 (目标设计，Go) + +当前已实现的是 Rust `bat` 的离线 TextUnit 队列、mock/Crowdin provider worker、 +lease/retry 和结果落库；Translation Memory、Glossary 和完整 Provider 体系仍属 +后续缺口。 **架构**： ``` @@ -204,7 +228,7 @@ type TranslationProvider interface { --- -### 5. Patch 引擎 (Rust) +### 5. Patch 引擎 (Rust，当前基础与目标扩展) **职责**：生成和应用补丁 @@ -232,7 +256,10 @@ patch/ --- -### 6. API Server (Go) +### 6. API Server (Go，目标设计) + +当前可用的 Go HTTP 服务是 `cmd/bat-api` 的资源 bootstrap、只读分发和 Rust 管理 +入口，不是下列完整游戏业务 API。 **框架**：Gin 或 Echo @@ -259,7 +286,9 @@ HTTP Request → Middleware (Auth, CORS, Logger) → Handler → Service → Rep --- -### 7. Web 后台 (Vue 3) +### 7. Web 后台 (Vue 3，目标设计) + +当前只有 `bat-api` 内嵌 dashboard MVP；登录、角色、术语管理和完整协作审核仍未实现。 **技术栈**： - Vue 3 + Composition API @@ -278,7 +307,10 @@ HTTP Request → Middleware (Auth, CORS, Logger) → Handler → Service → Rep --- -## 数据库设计 +## 数据库设计（目标设计） + +当前 Rust 资源链路使用 SQLite 维护本地 CAS、ResourceRepository 和翻译任务状态； +PostgreSQL/Redis 业务服务端方案尚未完整落地。 ### PostgreSQL Schema @@ -322,7 +354,11 @@ CREATE TABLE resource_versions ( --- -## 部署架构 +## 部署架构（目标设计） + +当前可部署形态是 Rust `bat` 官方资源同步任务和同机/共享文件系统的 Go +`bat-api` 资源 bootstrap/分发服务。以下多实例 API、PostgreSQL 主从和 Redis +集群属于目标部署形态。 ### 本地开发模式 @@ -350,7 +386,7 @@ API Server (多实例) --- -## 安全设计 +## 安全设计（目标设计） 1. **认证**：JWT Token 2. **授权**：RBAC (Role-Based Access Control) @@ -361,7 +397,7 @@ API Server (多实例) --- -## 性能优化 +## 性能优化（目标设计） 1. **缓存策略**： - Redis 缓存热点数据 @@ -380,7 +416,7 @@ API Server (多实例) --- -## 监控与日志 +## 监控与日志（目标设计） - **日志**：结构化日志（JSON 格式） - **指标**：Prometheus + Grafana @@ -401,10 +437,6 @@ API Server (多实例) 更多详细设计文档： - [官方资源后端说明](./official-resource-backend.md) +- [资源 release 布局与分发契约](./resource-release-layout.md) +- [AssetBundle 解析与发布路线图](./assetbundle.md) - [API 设计](../api/README.md) - -待创建的详细设计文档： - -- `docs/architecture/cas.md` -- `docs/architecture/assetbundle.md` -- `docs/architecture/translation.md` diff --git a/docs/architecture/adr/0001-engine-and-application-boundaries.md b/docs/architecture/adr/0001-engine-and-application-boundaries.md index 30bde1c..9cb8b02 100644 --- a/docs/architecture/adr/0001-engine-and-application-boundaries.md +++ b/docs/architecture/adr/0001-engine-and-application-boundaries.md @@ -1,11 +1,17 @@ # ADR 0001: Rust 引擎与 Go 应用层边界 -**状态**：已接受 +**状态**：已接受（历史决策；资源同步职责已由 ADR 0004 取代） **日期**：2026-06-28 **关联计划**：`../../../PROJECT_PLAN.md` --- +> 历史说明：本文保留 2026-06-28 的原始语言和层次决策。其关于 Go 负责资源同步、 +> 下载器和任务调度的职责描述已被当前实现和 ADR 0004 取代；阅读当前资源边界时， +> 以 ADR 0004、`CURRENT_STATUS.md` 和 `docs/reports/GO_STATUS.md` 为准。 + +--- + ## 背景 BlueArchiveToolkit 的最终目标覆盖资源同步、CAS、AssetBundle 解析、文本提取、翻译、Patch、CLI、API Server、Web 和 SDK。项目天然包含二进制解析、文件完整性、网络同步、任务编排、数据库、用户界面等不同类型的问题。 diff --git a/docs/architecture/adr/0004-rust-bat-go-bat-api-resource-boundary.md b/docs/architecture/adr/0004-rust-bat-go-bat-api-resource-boundary.md new file mode 100644 index 0000000..0d3b9ac --- /dev/null +++ b/docs/architecture/adr/0004-rust-bat-go-bat-api-resource-boundary.md @@ -0,0 +1,60 @@ +# ADR 0004: Rust bat 与 Go bat-api 当前资源控制面边界 + +**状态**：已接受 +**日期**：2026-09-04 +**关联文档**：`../../../CURRENT_STATUS.md`、`../../../docs/reports/GO_STATUS.md` + +--- + +## 背景 + +项目同时包含 Rust 资源引擎和 Go HTTP 服务。历史设计曾把资源同步、下载器 +和任务调度归入 Go 应用层，但当前实现已经由 Rust `bat` 统一持有这些长期状态。 +如果继续沿用旧职责描述，会让 Go、Web 或其他入口重复实现资源状态机。 + +--- + +## 决策 + +1. **Rust `bat` 是官方资源生产者和状态拥有者**： + - 负责官方 metadata 发现、下载、校验、staging、release 发布和 `current` 切换； + - 负责 watch/daemon、`bat.sock` JSON-RPC、任务、日志、版本状态、解析、 + 翻译 worker 和 localized release 状态； + - 负责 CAS、AssetBundle 解析、Patch 核心算法及其文件安全边界。 + +2. **Go `bat-api` 是资源读侧和管理入口**： + - 通过 `bat.sock` RPC 发现 Rust 已发布的 `resource_root`、snapshot、manifest + 和状态； + - 提供资源 bootstrap、server-info 改写、只读 CDN path、readiness、OpenAPI + 以及鉴权后的白名单管理转发； + - 不下载官方资源、不写 staging、不维护 version-state，不复制 CAS、解析器、 + Patch 核心算法或同步状态机。 + +3. **Go `cmd/bat` 和 `bat-ffi` 不是主集成边界**： + - `cmd/bat` 只保留试验 CLI； + - `bat-ffi` 只保留无状态、粗粒度、一次调用一次输入输出的兼容 helper； + - 新的跨语言控制和查询能力优先增加 Rust RPC contract，再由 + `internal/backendrpc` 消费。 + +4. **完整游戏业务 API、完整 Web 协作后台、Translation Memory、Glossary 和 + Provider 扩展体系仍是后续目标**，不能从目标架构图推断为当前已实现。 + +--- + +## 后果 + +- 资源同步只有一个长期状态拥有者，`bat-api` 可以安全地横向扩展为只读服务。 +- Rust RPC、release layout、manifest 和 `status/status_code` 成为跨语言稳定契约。 +- Go 侧新增控制接口必须经过白名单和 RPC schema 复核。 +- 完整业务 API 和协作后台未来落地时，仍需遵守 Rust `bat` 对资源状态的所有权。 + +--- + +## 当前验证依据 + +- `infrastructure/src/bin/bat/` +- `infrastructure/src/official_update.rs` +- `internal/backendrpc/` +- `cmd/bat-api/` +- `docs/reference/rpc-backend-api.md` +- `internal/api/testdata/contract/` diff --git a/docs/architecture/assetbundle.md b/docs/architecture/assetbundle.md index 205d29e..6580ffc 100644 --- a/docs/architecture/assetbundle.md +++ b/docs/architecture/assetbundle.md @@ -1,9 +1,9 @@ # AssetBundle 与资源解析路线图 -- **更新时间**：2026-09-02 +- **更新时间**：2026-09-04 - **适用范围**：Rust 解析引擎、官方同步后的解析缓存、CAS/ResourceRepository 接入、后续文本提取和 Patch 发布。 - **权威关联**：`PROJECT_PLAN.md` Milestone 3/4/5/8，`docs/reports/CURRENT_GAPS.md` G-005/G-007/G-011/G-011D。 -- **维护冻结**：解析扩展遵循 [`docs/reports/PARSER_FREEZE.md`](../reports/PARSER_FREEZE.md)，冻结期只接受稳定性、诊断、真实回归和文档一致性修复。 +- **开发状态**：解析扩展当前按路线图和真实回归继续推进。 --- @@ -32,7 +32,7 @@ | UnityFS container | `.bundle`、zip 内 bundle | header、block、directory、解压文件、基础摘要 | 已支持基础解包、LZ4/LZMA、alignment、大小/计数/路径/边界校验 | | Serialized file | UnityFS directory 文件 | header、type table、TypeTree node、object table、TextAsset bytes | 已支持基础表结构和 TextAsset bytes | | Unity 对象字段 | TextAsset、MonoBehaviour、ScriptableObject | 可翻译文本单元、上下文、资源定位 | TypeTree 基础字段读取、`SerializedReference` / prefixed managed-reference metadata alias、payload 提取和字符串提取已落地，真实结构覆盖继续扩大 | -| Patch 发布 | 已翻译 TextUnit、中间格式、原版资源 | 可验证 localized patch manifest、汉化 release 目录、current/state | TextAsset、TypeTree string field 和 managed-reference string field 的 localized publish/rollback 已落地；整体 AssetBundle 重打包与通用 manifest 发布仍冻结 | +| Patch 发布 | 已翻译 TextUnit、中间格式、原版资源 | 可验证 localized patch manifest、汉化 release 目录、current/state | TextAsset、TypeTree string field 和 managed-reference string field 的 localized publish/rollback 已落地；整体 AssetBundle 重打包与通用 manifest 发布仍未完成 | --- @@ -54,7 +54,7 @@ 当前还不能宣称完整： -1. TypeTree-covered managed reference 字段和 registry 记录已可结构化解码并参与文本提取，常见 registry 命名别名（含 `m_ManagedReferences`、`RefIds`、`m_RefIds`、verbose type 字段）、metadata 命名别名（含 `id`、`typeInfo`）、payload 命名别名（含 `data`、`value`、`payload`、`object`、`managedReferencePayload`、`referencePayload`、`serializedReferencePayload`、`managedReferenceValue`、`referenceValue`、`serializedReferenceValue`、`managedReferenceObject`、`referenceObject`、`serializedReferenceObject`、`managedReferenceData`、`referenceData`、`serializedData`）、full typename 拆解和 payload-only TextUnit 提取已有回归覆盖，多记录 registry 聚合也已有单元回归；fallback 字段遍历会跳过常见 registry 元数据字符串，避免误入翻译队列，并按记录前缀或子字段可推导 metadata 保留 managed-reference TextUnit context。enum `value__` backing field 和 `LayerMask` / `BitField` 的 `m_Bits` backing field 已可语义化解码和替换；`Vector2f/3f/4f`、`Quaternionf`、`ColorRGBA`、`Rectf`、`AABB/Bounds/Ray`、`Matrix4x4f`、`Vector2Int/Vector3Int`、`RectInt`、`BoundsInt`、`RangeInt`、`GUID`、`Hash128` 等固定 Unity 值类型的 leaf 和 direct child TypeTree 形态已可结构化解码和语义替换；array/vector/staticvector/List/HashSet/map 元素与 registry payload 字段已保留独立 field path、offset 和 byte size，可用于字符串元素 patch，managed-reference registry payload 字符串、enum、bit_field、unknown fixed-size raw bytes、object 字段组合和 TypeTree schema 支撑的 array/vector/List/HashSet/map 已可整体变长替换，`first/second` 与 `key/value` map entry schema 已有 serialized 和 UnityFS 重建回归，ScriptableObject `key/value` map 解析、变长替换和 UnityFS 重建已有专门回归，且嵌套 vector `Array`、`List` / `HashSet` 集合 alias、enum、bit_field、unknown fixed-size raw bytes 与 managed-reference payload 字段已有重建回归覆盖；解析模块当前处于维护冻结，未见样本驱动的完整 managed reference registry / map entry 变体、unknown 字段结构语义和版本差异冻结后再推进。 +1. TypeTree-covered managed reference 字段和 registry 记录已可结构化解码并参与文本提取，常见 registry 命名别名（含 `m_ManagedReferences`、`RefIds`、`m_RefIds`、verbose type 字段）、metadata 命名别名（含 `id`、`typeInfo`）、payload 命名别名（含 `data`、`value`、`payload`、`object`、`managedReferencePayload`、`referencePayload`、`serializedReferencePayload`、`managedReferenceValue`、`referenceValue`、`serializedReferenceValue`、`managedReferenceObject`、`referenceObject`、`serializedReferenceObject`、`managedReferenceData`、`referenceData`、`serializedData`）、full typename 拆解和 payload-only TextUnit 提取已有回归覆盖，多记录 registry 聚合也已有单元回归；fallback 字段遍历会跳过常见 registry 元数据字符串，避免误入翻译队列，并按记录前缀或子字段可推导 metadata 保留 managed-reference TextUnit context。enum `value__` backing field 和 `LayerMask` / `BitField` 的 `m_Bits` backing field 已可语义化解码和替换；`Vector2f/3f/4f`、`Quaternionf`、`ColorRGBA`、`Rectf`、`AABB/Bounds/Ray`、`Matrix4x4f`、`Vector2Int/Vector3Int`、`RectInt`、`BoundsInt`、`RangeInt`、`GUID`、`Hash128` 等固定 Unity 值类型的 leaf 和 direct child TypeTree 形态已可结构化解码和语义替换；array/vector/staticvector/List/HashSet/map 元素与 registry payload 字段已保留独立 field path、offset 和 byte size，可用于字符串元素 patch，managed-reference registry payload 字符串、enum、bit_field、unknown fixed-size raw bytes、object 字段组合和 TypeTree schema 支撑的 array/vector/List/HashSet/map 已可整体变长替换，`first/second` 与 `key/value` map entry schema 已有 serialized 和 UnityFS 重建回归，ScriptableObject `key/value` map 解析、变长替换和 UnityFS 重建已有专门回归，且嵌套 vector `Array`、`List` / `HashSet` 集合 alias、enum、bit_field、unknown fixed-size raw bytes 与 managed-reference payload 字段已有重建回归覆盖；后续仍需继续补齐真实样本驱动的完整 managed reference registry / map entry 变体、unknown 字段结构语义和版本差异。 2. Addressables 当前目标 JSON/compact 字段链已补齐；未识别的独立二进制格式仍返回明确错误，不静默降级。 3. 官方 release 已可配置导入 CAS + ResourceRepository，并可通过 `resource.index` 查询现有资源索引；Resource metadata 已记录 release、平台、bundle path、parse status、TextAsset 名称和 TextUnit 摘要。 4. 不能完成复杂对象字段重打包，也不能从真实 Crowdin 结果自动生成完整汉化文件集合。 @@ -99,7 +99,7 @@ 4. 将 Windows/Android catalog 样本拆成可复现 fixture，不把大文件纳入 Git。 5. 对未知结构返回明确错误或保真 raw metadata，不静默丢字段。 -本次 issue #2 交付已完成上述 JSON/compact 字段链：provider ID、bundle name、 +当前 JSON/compact 字段链已完成：provider ID、bundle name、 primary/dependency key、resource type、hash、size 和 CRC 会进入 `ResourceEntry`， 并通过 SQLite `ResourceRepository` 持久化；旧索引会按列迁移继续可读。独立二进制 catalog 仍按“明确不支持”处理，不把低保真路径伪装成完整解析。 @@ -202,12 +202,13 @@ catalog 仍按“明确不支持”处理，不把低保真路径伪装成完整 --- -## 7. 近期关闭路径 +## 7. 后续推进路径 优先顺序： -1. 完成 Addressables Windows/Android 当前版本 catalog 样本集合，关闭 G-007 当前阶段。 -2. 完成 TypeTree 字段 reader 和 MonoBehaviour/ScriptableObject 遍历，推进 G-005。 +1. 继续补充 Addressables Windows/Android 真实 catalog 样本和独立二进制格式诊断。 +2. 继续补充 TypeTree 字段 reader、MonoBehaviour/ScriptableObject 遍历和真实版本差异。 3. 基于 `translation.worker.run` 推进翻译记忆和通用 manifest Patch 构建。 -4. 扩展翻译任务结果在 CAS/ResourceRepository 查询面的索引，推进 G-011。 -5. 在通用 Binary/JSON/Text Patch 基础上继续扩展复杂 AssetBundle 重打包和通用 Patch 发布流程统一，保留当前受支持 localized patch 发布/rollback 链路。 +4. 扩展翻译任务结果在 CAS/ResourceRepository 查询面的索引。 +5. 在通用 Binary/JSON/Text Patch 基础上继续扩展复杂 AssetBundle 重打包和通用 + Patch 发布流程统一，保留当前受支持 localized patch 发布/rollback 链路。 diff --git a/docs/architecture/official-resource-backend.md b/docs/architecture/official-resource-backend.md index 9b75980..3ccec16 100644 --- a/docs/architecture/official-resource-backend.md +++ b/docs/architecture/official-resource-backend.md @@ -219,7 +219,9 @@ release 根目录写入 `translation-tasks.sqlite`，由版本化 `schema_migrat 集成边界： -1. 当前生产集成路径是 Rust `bat --watch` / `bat --daemon` 持久运行；Go `bat-api` 应优先通过 `internal/backendrpc` 调用 daemon RPC，one-shot/fallback 场景才运行 `bat --json` 并消费结构化 report。 +1. 当前生产集成路径是 Rust `bat --watch` / `bat --daemon` 持久运行；Go `bat-api` + 通过 `internal/backendrpc` 调用 daemon RPC，读取已发布 release 和状态，不运行 + 另一套同步器。`bat --json` 只表示 Rust CLI 的机器输出形态。 2. systemd、容器或上层 Go 进程只负责守护 `bat --watch` / `bat --daemon`，不直接接管下载器内部状态。 3. `bat-ffi` 只允许作为可选无状态 C ABI 兼容层，用于 Manifest inspect 和 sync plan 这类一次性 JSON helper；它不是官方同步 daemon、下载器、资源锁、CAS handle 或主控制面的承载位置。 @@ -356,7 +358,7 @@ JSON-RPC 2.0 服务，是面向上层服务（Go 层）的**主要跨语言边 - Go 层负责：资源 bootstrap、资源内容分发（`cmd/bat-api`）、HTTP API 进程配置、 以及通过 `internal/backendrpc` 作为 RPC client 调用本机 daemon（连接 `bat.sock`，每行一个 JSON-RPC 请求/响应）。`cmd/bat` 仍是试验骨架，不是产品级用户 CLI。 -- **`bat-api`（资源分发，issue #19）**： +- **`bat-api`（资源分发）**： - 提供 `/v1/bootstrap`，把 `bat` 的 RPC 健康、release 摘要、server-info URL、 client-patch base 和改写后的 Addressables root 组织成启动前资源发现响应。 - 提供 `/healthz` 作为 liveness + 最近一次 RPC refresh 诊断，提供 `/readyz` diff --git a/docs/architecture/resource-release-layout.md b/docs/architecture/resource-release-layout.md index dc1d3e1..88d4d5a 100644 --- a/docs/architecture/resource-release-layout.md +++ b/docs/architecture/resource-release-layout.md @@ -1,6 +1,6 @@ # 官方资源 Release 布局与资源侧契约 -- **更新时间**：2026-09-02 +- **更新时间**：2026-09-04 - **用途**：冻结日服官方资源在本地发布根上的布局、URL 映射、seed 规则、`bat`/`bat-api` 关系，以及 `bat-api` 分发 path 的 1:1 对应关系。 - **范围**：资源发现 / 清单 / 落盘 / 只读分发（**不是**完整游戏业务 API）。 - **权威代码**： @@ -319,18 +319,18 @@ Addressables 改写后客户端拼接： --- -## 9. issue #2 / #3 样本索引（R4/R5 预置） +## 9. 真实资源样本索引 在服务器 release 上优先采集到 `/tmp` 隔离目录（**不入库大文件**）： | 用途 | 建议路径模式 | |---|---| -| Addressables（#2） | `{PatchDir}/catalog_*.zip` 解压后的 JSON/bin + 旁路 `.hash` | -| UnityFS（#3） | `FullPatch_*.zip` 内抽样 `.bundle`，或已解包 bundle | +| Addressables | `{PatchDir}/catalog_*.zip` 解压后的 JSON/bin + 旁路 `.hash` | +| UnityFS | `FullPatch_*.zip` 内抽样 `.bundle`，或已解包 bundle | | seed 加固（R2） | 各平台 `TableCatalog` / `BundlePackingInfo` / `MediaCatalog` 的 `.bytes`+`.hash` | -字段目标（#2，已有 `m_Crc` 部分）：继续扩大 hash/size/CRC/依赖等可校验字段覆盖。 -结构目标（#3）：header / block / directory / metadata / object table 引擎级解析。 +字段目标（已有 `m_Crc` 部分）：继续扩大 hash/size/CRC/依赖等可校验字段覆盖。 +结构目标：header / block / directory / metadata / object table 引擎级解析。 --- @@ -360,7 +360,7 @@ bat.sock 或 state-dir: ... - `docs/architecture/official-resource-backend.md` — 拉取后端总览 - `docs/reference/rpc-backend-api.md` — RPC 契约 - `docs/guides/official-resource-test-pull.md` — 用户向运行说明 -- `docs/reports/CURRENT_GAPS.md` — G-009 / #2 / #3 +- `docs/reports/CURRENT_GAPS.md` — G-005 / G-007 / G-009 --- diff --git a/docs/guides/baseline.md b/docs/guides/baseline.md index a42a9ed..fc36012 100644 --- a/docs/guides/baseline.md +++ b/docs/guides/baseline.md @@ -1,6 +1,6 @@ # 稳定工程基线指南 -- **更新时间**：2026-08-03 +- **更新时间**：2026-09-04 - **目标**：让工作区处于可继续开发核心功能的可信状态。 --- @@ -37,28 +37,26 @@ make lint cargo test --workspace cargo check --workspace cargo clippy --workspace --all-targets -- -D warnings -go test ./... +go test ./internal/api/... ./internal/backendrpc/... go vet ./... ``` 说明： -1. 当前已有 `internal/backendrpc` fake socket 单测、`cmd/bat` 试验骨架和 `internal/ffi` 兼容包装；这些不代表 CLI/API 产品入口已完成。 -2. 后续新增 Go 产品 package，必须让 `go test ./...` 和 `go vet ./...` 纳入硬性验证。 -3. 当前 `golangci-lint` 可选；当 Go 代码进入主要开发阶段后，应纳入本地门禁。 +1. 默认 Go 测试只覆盖正式 `bat-api` 依赖的纯 Go 包：`internal/api` 和 `internal/backendrpc`；`make test-go-ffi` / `make test-go-all` 才会包含 FFI 和试验 CLI。 +2. `make check` 当前直接执行 `go vet ./...`，因此会检查所有已存在的 Go 包；新增 Go 产品 package 后，必须同时纳入默认测试门禁。 +3. `golangci-lint` 当前仍是可选补充门禁；Go 的硬性验证是默认 API 测试、全量 `go vet` 和 `bat-api` 构建。 4. 官方同步相关修改必须额外运行 `cargo test -p bat-infrastructure --bin bat -- --nocapture`。 +如果构建环境的默认 Go cache 不可写，可将 `GOCACHE` 指向工作区外的临时目录，例如 +`GOCACHE=/tmp/bat-go-cache`。 + --- ## 3. Git 基线 -当前工作区原 `.git/` 是空目录，无法恢复原历史。本基线采用新初始化仓库，并以首次提交作为后续开发起点。 - -首次提交信息： - -```text -chore: establish development baseline -``` +当前工作区以现有 Git 分支和提交为基线；原项目历史未恢复。提交前应确认工作区 +只包含本次有意修改，并核对文档、源码和测试状态。 提交前检查： @@ -86,15 +84,15 @@ git check-ignore -v Cargo.lock CLAUDE.md AGENTS.md CONTRIBUTING.md --- -## 5. 下一阶段入口 +## 5. 当前开发入口 -CAS V1 和 Rust 官方同步闭环完成后，下一阶段优先推进： +当前开发优先推进： -1. 继续联调 Go `bat-api` 与 Rust daemon 的资源分发路径；Go 同步 CLI 不再作为产品目标。 -2. 按 `docs/guides/official-full-pull-smoke.md` 在隔离目录执行真实官方网络全量下载 smoke，并保留运行报告。 -3. 基于 `translation.worker.run` 推进翻译记忆和通用 manifest Patch 构建。 -4. 扩展 ResourceRepository 查询面：更丰富的 TextUnit 查询、翻译记忆查询和通用 Patch 发布所需资源视图。 -5. 继续完善 AssetBundle 复杂对象解析、复杂对象重打包和通用 Patch 发布流程统一；通用 Binary/JSON/Text Patch 基础与受支持 localized patch 发布/rollback 链路已可用。 +1. 继续 AssetBundle 复杂对象解析、真实 fixture 和发布级重打包。 +2. 基于 `translation.worker.run` 推进翻译记忆和通用 manifest Patch 构建。 +3. 扩展 ResourceRepository 查询面：更丰富的 TextUnit 查询、翻译记忆查询和通用 Patch 发布所需资源视图。 +4. 按 `docs/guides/official-full-pull-smoke.md` 在隔离目录执行真实官方网络全量下载 smoke，并保留运行报告。 +5. 在资源和翻译契约稳定后推进完整 Web 协作后台和完整游戏业务 API。 优先阅读： diff --git a/docs/guides/bat-workflows.md b/docs/guides/bat-workflows.md index a5a9e4b..88a7626 100644 --- a/docs/guides/bat-workflows.md +++ b/docs/guides/bat-workflows.md @@ -339,4 +339,4 @@ release。Go 只做鉴权、参数校验和转发，状态与产物仍由 Rust ## 边界 -解析器新增类型覆盖和新的解析格式仍受 `docs/reports/PARSER_FREEZE.md` 约束。本次 issue 43 的例外只开放已有解析输出的手动编排、缓存刷新、工作台编辑、既有 patch 实现的重打包和独立汉化发布，不扩展 UnityFS/AssetBundle/Addressables/TypeTree 的解析类型覆盖。 +解析器新增类型覆盖和新的解析格式当前按路线图推进；新增覆盖仍需通过真实 fixture、回归测试和文档同步验收，不要只靠合成样本宣称能力。 diff --git a/docs/guides/development.md b/docs/guides/development.md index 89f3825..3acc575 100644 --- a/docs/guides/development.md +++ b/docs/guides/development.md @@ -8,7 +8,7 @@ #### Go ```bash -# 安装 Go 1.22+ +# 安装 Go 1.26.4+ # 参考：https://golang.org/doc/install go version # 验证安装 @@ -118,9 +118,9 @@ git push origin feature/your-feature-name 禁止使用 demo、临时实现、硬编码路径或只为当前测试通过的伪实现。确实未完成的能力应写入当前缺口文档，而不是用 `TODO` 或 `FIXME` 隐藏。 -### 解析模块冻结 +### 解析模块状态 -UnityFS / AssetBundle / Addressables / TypeTree 解析当前处于维护冻结。冻结期不得新增解析类型、扩大解析覆盖、开放新的写入型解析 RPC/CLI，或用合成 fixture 宣称新增能力。允许变更仅限编译、测试、clippy、真实运行回归、诊断和文档一致性修复。细则见 `docs/reports/PARSER_FREEZE.md`。 +UnityFS / AssetBundle / Addressables / TypeTree 解析当前按路线图继续推进。新增解析类型、扩大解析覆盖和写入型解析 RPC/CLI 仍需遵守现有接口边界、真实 fixture 和回归验收要求。 ### Go - 遵循 [Effective Go](https://golang.org/doc/effective_go) @@ -143,7 +143,7 @@ UnityFS / AssetBundle / Addressables / TypeTree 解析当前处于维护冻结 ### 合并前通用门禁 ```bash -cargo fmt --check +cargo fmt --all -- --check cargo test --workspace cargo clippy --workspace --all-targets -- -D warnings make test-go-api @@ -192,7 +192,7 @@ cargo clippy -p bat-core -p bat-adapters -p bat-infrastructure --all-targets -- `bat-ffi` 只是可选无状态 C ABI 兼容层。修改 FFI 时必须运行 `cargo test -p bat-ffi -- --nocapture`。Go 服务层默认经 `internal/backendrpc` 调 daemon；同步任务由 Rust `bat` 执行，不由 Go 试验 CLI 承担。 -Rust `bat` 的资源拉取、解析、翻译工作流、重打包、汉化发布和持久化调度命令见 [`docs/guides/bat-workflows.md`](bat-workflows.md)。推荐使用 `res`、`parse`、`i18n` 三个一级命令；该工作流当前对应 issue `#43`。 +Rust `bat` 的资源拉取、解析、翻译工作流、重打包、汉化发布和持久化调度命令见 [`docs/guides/bat-workflows.md`](bat-workflows.md)。推荐使用 `res`、`parse`、`i18n` 三个一级命令。 ### 集成测试 @@ -273,7 +273,7 @@ cargo run -p bat-infrastructure --bin bat -- resource-index --limit 50 cargo run -p bat-infrastructure --bin bat -- resource-index --release-id --platform windows --archive-entry --format json --limit 50 ``` -issue 47 的隔离回归测试： +历史 release/CAS 复用的隔离回归测试： ```bash cargo test -p bat-infrastructure official_download::tests::reuses_verified_historical_release_when_cdn_root_changes -- --nocapture @@ -416,7 +416,8 @@ cargo fetch `bat-ffi` 不是主集成边界，只用于需要 C ABI 的兼容场景。当前 Go 正式产品入口是 `bat-api` 资源 bootstrap/分发服务，默认通过 `internal/backendrpc` 调用 daemon RPC； -`cmd/bat` 仍是试验 CLI。未来新增 Go 集成仍优先使用 Rust `bat --json` 进程边界或稳定 RPC/SDK。 +`cmd/bat` 仍是试验 CLI。新的 Go 集成优先使用 Rust `bat.sock` RPC 或稳定 SDK； +`bat --json` 仅是 Rust CLI 的机器输出形态。 重新构建兼容库： ```bash diff --git a/docs/guides/official-resource-test-pull.md b/docs/guides/official-resource-test-pull.md index 4b7af3a..ebc8ef1 100644 --- a/docs/guides/official-resource-test-pull.md +++ b/docs/guides/official-resource-test-pull.md @@ -343,7 +343,7 @@ make official-smoke 默认输出在 `/tmp/bat-official-smoke-/`，脚本会执行 dry-run plan、首次全量拉取、二次 `up_to_date`、本地文件破坏后的 `repair`、repair 后 `verify`，并检查 stderr progress log 中存在下载已完成计数、单文件进度和校验结果摘要。完整说明见 `docs/guides/official-full-pull-smoke.md`。 -## 7. 例外输入 +## 7. 输入模式 可接受的 `server-info` 输入是： diff --git a/docs/reports/BAT_API_CONTRACT_FIXTURE_HANDOFF.md b/docs/reports/BAT_API_CONTRACT_FIXTURE_HANDOFF.md index a7eca7e..9595a56 100644 --- a/docs/reports/BAT_API_CONTRACT_FIXTURE_HANDOFF.md +++ b/docs/reports/BAT_API_CONTRACT_FIXTURE_HANDOFF.md @@ -1,6 +1,6 @@ # bat-api / Rust bat Contract Fixture Handoff -更新时间：2026-09-02 +更新时间：2026-09-04 本文用于两个 Codex 窗口之间间接联调 `bat-api` 与 Rust `bat` 的跨语言 contract fixture。 仓库内归一化 fixture 已交付；本文保留生成、审核和后续扩展的协作协议。 diff --git a/docs/reports/CURRENT_GAPS.md b/docs/reports/CURRENT_GAPS.md index 457cbc8..252bf6f 100644 --- a/docs/reports/CURRENT_GAPS.md +++ b/docs/reports/CURRENT_GAPS.md @@ -1,585 +1,150 @@ # 当前实现缺口清单 -- **更新时间**：2026-09-02 -- **Go 进度权威**：`GO_STATUS.md` -- **资源布局 / 逆向契约**：`../architecture/resource-release-layout.md` -- **用途**：集中跟踪当前代码中的占位实现、设计缺口和下一步验收项。 +- **更新时间**：2026-09-04 +- **文档角色**：只记录尚未完成、仍需验证或仍需设计的工作，不重复维护完整实现状态。 +- **当前事实**：以源码、测试、稳定契约和 `CURRENT_STATUS.md` 为准。 +- **Go 进度**：`GO_STATUS.md` +- **资源布局契约**：`../architecture/resource-release-layout.md` - **权威计划**：`../../PROJECT_PLAN.md` +- **历史资料**：`docs/archive/` 和 `docs/reports/historical/` 只用于追溯。 ---- +## 1. 当前工程缺口 -## 1. 基线缺口 +### G-005：AssetBundle 复杂解析仍未完成 -### G-001：Git 元数据不可用 +状态：**部分完成，继续推进** -状态：**已关闭，采用新初始化基线** +当前已具备 UnityFS 容器校验、directory 文件提取、serialized file +object/type table/TypeTree 元数据、TextAsset、基础 MonoBehaviour 和 +ScriptableObject 字段读取、TextUnit 提取，以及受支持字段的文件级重建。 -原现象： +仍需完成： -- `.git/` 是空目录。 -- `git status` 报 `not a git repository`。 +- 用真实资源 fixture 覆盖更多 MonoBehaviour、ScriptableObject、Unity 版本差异、 + 复杂容器和 managed reference registry/map entry 变体。 +- 为未知字段补充结构语义；不能把低保真猜测当作已支持格式。 +- 完成发布级复杂对象重打包，并把 bundle、serialized file、path id、class id、 + field path、offset 和 byte size 的定位信息贯通到稳定发布流程。 -处理结果： +现有证据：`crates/bat-assetbundle` 的单元/重建测试、隔离真实 UnityFS 回归和 +`bat-infrastructure` 的解析缓存测试。新增格式覆盖必须同时补真实 fixture、回归测试 +和文档。 -- 已执行 `git init`。 -- 已将初始分支调整为 `main`。 -- 已配置当前路径为 Git safe directory。 -- `git status --short --branch` 已可用。 -- 本轮创建首次基线提交。 +### G-006：通用 Patch 发布仍未完成 -限制： +状态：**基础完成，发布流程部分完成** -- 原项目历史未恢复。 -- 后续历史从当前基线提交开始。 +`bat-patch` 已提供 Binary/JSON/Text Patch、manifest、BLAKE3/size 校验和 +rollback 元数据；文件级 `patch.apply` 与受支持的 UnityFS TextAsset、TypeTree +string field、managed-reference string field 写入及 localized publish/rollback +已可用。 -验收： +仍需完成： -- `git log --oneline -1` 能看到基线提交。 +- 通用 manifest 驱动的跨类型 patch build/apply/publish/rollback。 +- 复杂 AssetBundle 重打包和完整翻译文件集合构建。 +- 原版 release 与 localized release 双发布后的查询、分发和清理策略。 -### G-002：CAS 有两套实现边界 +所有发布产物必须先进入独立 staging，通过完整性校验后再原子发布；失败不得改变 +已发布的 `bat-resources/current` 或 `bat-localized/current`。 -状态：**已关闭** +### G-007：Addressables 完整兼容仍未完成 -原现象： +状态：**当前 JSON/compact 目标字段完成，独立二进制格式待后续** -- `crates/bat-cas-engine/src/storage.rs` 有文件系统存储。 -- `infrastructure/src/cas/filesystem.rs` 也实现了文件系统 CAS repository。 +当前 JSON/compact catalog 已覆盖 path、hash、size、address、dependencies、 +provider、bundle name、resource type 和 CRC，并有 fixture/golden 回归。 -处理结果： +仍需完成： -- `crates/bat-cas-engine` 新增 `repository` 组合层，成为 CAS 核心实现。 -- `infrastructure/src/cas/filesystem.rs` 已改为 `bat-core::CasRepository` 适配层。 -- infrastructure 不再直接写对象文件，不再维护自己的引用计数逻辑。 +- 更多 Windows/Android 真实 catalog 形态和失败诊断。 +- 独立二进制 catalog 入口；在未支持前必须明确拒绝，不得静默丢字段。 -验收证据： +### G-009：`bat-api` 仍是资源服务，不是完整官方游戏 API -- `bat-cas-engine::repository::FileSystemCasRepository` -- `bat_infrastructure::FileSystemCasRepository` -- `cargo test --workspace` +状态：**资源 bootstrap/分发和管理控制面已可用，业务 API 未完成** -### G-003：CAS 引用计数和 GC 未实现 +当前 `cmd/bat-api` 通过 `bat.sock` 读取 Rust 已发布 release，提供 bootstrap、 +launcher 资源引导兼容、只读 CDN path、readiness、OpenAPI、鉴权管理入口和内嵌 +dashboard。Rust `bat` 继续拥有资源发现、下载、校验、staging、发布、任务和长期状态。 -状态：**已关闭** +仍需完成： -原现象： +- 完整游戏业务 API、账号/登录/网关链和完整 launcher 安装包更新链。 +- 更丰富的 Resource/TextUnit/翻译记忆查询面。 +- 真实官方网络长期运行报告；运行使用 `make official-smoke`，产物留在隔离目录。 -- `FileSystemCasRepository::add_reference` 返回固定 `1`。 -- `remove_reference` 返回固定 `0`。 -- `get_reference_count` 返回固定 `1`。 -- `gc` 返回固定 `0`。 -- `crates/bat-cas-engine/src/refcount.rs` 是占位。 +`bat-api` 不得复制 Rust 下载器、CAS、AssetBundle 解析、Patch 核心算法或同步状态机。 -处理结果： +### G-010：完整 Web 协作后台仍未完成 -- `crates/bat-cas-engine/src/refcount.rs` 使用 SQLite 保存对象元数据和引用计数。 -- `store()` 会存储对象并增加引用计数。 -- `add_reference()`、`remove_reference()`、`get_reference_count()` 已持久化。 -- `gc()` 删除引用计数为 0 的对象和元数据。 -- `gc_candidates()` 提供 dry-run 能力。 +状态：**内嵌 dashboard MVP 已完成，完整后台未开始** -验收证据： +当前页面可以调用已有资源、调度、任务、解析、翻译和 localized 控制接口。 -- 引用计数增减有持久化测试。 -- GC 不删除仍被引用对象。 -- 并发引用更新测试通过。 +仍需完成： ---- +- 独立登录、角色权限和协作式翻译审核。 +- Glossary/术语管理、批量审核、搜索和完整历史版本视图。 +- 构建型前端工程、浏览器 E2E 和完整错误态交互门禁。 -## 2. 核心功能缺口 +### G-011：ResourceRepository 查询面仍不完整 -### G-004：CAS 写入不是生产级原子流程 +状态：**部分完成** -状态：**已关闭** +当前已支持 CAS + SQLite 导入、资源类型/release/平台/path/parse status/TextUnit +format 等资源级过滤，`parse.text_units` / `parse.errors` 和翻译任务查询也已可用。 -原现象： +仍需完成： -- 当前写入直接写目标路径。 -- 缺少临时文件、fsync、原子 rename、并发冲突处理。 +- 更丰富的 TextUnit、翻译记忆和 Patch 发布资源视图。 +- 从同一 manifest fingerprint 追溯资源、解析缓存、翻译任务和发布产物。 +- 更多 schema 迁移、权限、并发和损坏恢复场景验证。 -处理结果： +### G-011D：双 release 的完整查询与发布策略仍未完成 -- `FileSystemStorage::put()` 使用临时文件写入、文件 sync、原子 rename、目录 sync。 -- 读取对象时强制 Hash 校验。 -- 并发写入相同内容只保留一个对象，引用计数按调用次数递增。 -- 损坏对象读取返回 `HashMismatch`。 +状态：**受支持范围完成，通用范围部分完成** -验收证据： +官方原版和 localized release 已分离，受支持 patch 可独立 staging、校验、发布和 +rollback，`localized.status` 能校验当前官方 release 与 patch manifest 的一致性。 -- 写入失败不会留下可见半成品对象。 -- 并发写入相同内容只产生一个对象。 -- 读取时 Hash 不匹配会返回明确错误。 - -### G-005：AssetBundle 引擎解析器仍未完成 - -状态：**UnityFS 基础容器校验目标完成，复杂对象能力仍部分完成** - -冻结状态：自 2026-07-30 起，G-005 不再作为默认推进项。解析层只接受维护冻结规则允许的稳定性修复、诊断修复、真实回归修复和文档校正；新增 TypeTree 语义类型、扩大解析覆盖和新增写入型解析入口全部暂停。冻结细则见 `docs/reports/PARSER_FREEZE.md`。 - -现象： - -- `crates/bat-assetbundle` 已接管 UnityFS 解析，提供 `UnityFsParser`、`UnityFsBundle`、header、block info、directory、压缩模式、block info at end、LZ4/LZMA block info 解压、数据 block 解压、alignment、总大小/计数/路径/目录边界诊断、directory 文件提取。 -- `crates/bat-assetbundle::serialized` 已提供 Unity serialized file header、type table、TypeTree node 元数据、object table、TextAsset bytes 和基础 TypeTree field reader。 -- `adapters/src/unity/unity_2021_3.rs` 已降为 Unity 版本选择薄层，复用 `bat-assetbundle`，不再维护第二套 UnityFS parser。 -- `ResourceImportService` 的 UnityFS 摘要已经能暴露解包文件数、serialized file 数、TextAsset 名称、TextUnit 数量/格式和字段诊断。 -- `MonoBehaviour`、`ScriptableObject` 已有基础 TypeTree 字段级反序列化和字符串提取入口；array/vector/staticvector/`List`/`HashSet`/map 元素与 TypeTree-covered managed reference registry payload 已保留独立 field path、offset 和 byte size，enum `value__` backing field 会暴露为语义化 `{type_name, storage_type, value}`，`LayerMask` / `BitField` 的 `m_Bits` backing field 会暴露为语义化 `{type_name, storage_type, bits}`，managed-reference full typename 可拆为 assembly/namespace/class，常见 `m_ManagedReferences` / `RefIds` / `m_RefIds` / verbose type 字段命名、`managedReference*` / `serializedReference*` prefixed metadata、`SerializedReference` 节点 alias 和 `data` / `value` / `payload` / `object` / `managedReferencePayload` / `referencePayload` / `serializedReferencePayload` / `managedReferenceValue` / `referenceValue` / `serializedReferenceValue` / `managedReferenceObject` / `referenceObject` / `serializedReferenceObject` / `managedReferenceData` / `referenceData` / `serializedData` / `serializedReferenceData` payload 命名已有回归覆盖，多记录 registry 聚合已有单元回归，TextUnit 提取会跳过 registry 元数据字符串并把它们作为 payload 文本上下文，fallback 字段遍历也会跳过常见 managed-reference 元数据别名，并按 `RefIds[n]` 等记录前缀或子字段推导 metadata 写入 payload TextUnit context；当前可对 string、bool、integer、float raw bits、bytes、enum、bit_field、常见固定 Unity float/int/hash 值类型的 leaf/direct-child 形态、unknown fixed-size raw bytes 同长度替换、PPtr、object 字段组合和 TypeTree schema 支撑的 array/vector/List/HashSet/map 整体替换执行文件级 patch，map entry 的 `first/second` 与 `key/value` 字段命名已有 serialized 和 UnityFS 重建回归，ScriptableObject `key/value` map 解析、变长替换和 UnityFS 重建已有专门回归；真实版本差异、未见样本驱动的复杂 managed reference registry / map entry 变体、unknown 字段结构语义和发布级重打包入口仍未完成。 - -issue 43 例外说明：新增的 `parse repack` 只编排已有 TextAsset、TypeTree string 和受支持语义 field patch 实现；它不新增解析器类型、字段族或 catalog 覆盖。人工翻译工作台和 localized publish 只消费已有 TextUnit 输出，当前 publish 支持 TextAsset、TypeTree string field 和 managed-reference string field。 - -影响： - -- 可以对 UnityFS 容器做结构校验、解包 directory 文件，并提取 serialized file 中的 TextAsset 原始 bytes。 -- 对日语汉化最关键的 TextAsset 索引、bytes、JSONL TextUnit、MonoBehaviour/ScriptableObject 基础字符串字段、array/vector/List/HashSet/map 字符串元素和 TypeTree-covered managed reference payload 提取已有入口；managed-reference 类型元数据作为上下文保留，不进入翻译文本队列，fallback registry 字段遍历也会过滤常见元数据别名，并按记录前缀或子字段保留可推导 metadata。文件级 UnityFS 重建可覆盖 TextAsset、TypeTree string 字段、managed-reference registry payload 字符串、基础语义字段、enum、bit_field、unknown fixed-size raw bytes、object 字段组合和 TypeTree schema 支撑的 array/vector/List/HashSet/map 整体替换，但还不能完成发布级复杂对象重打包。 - -当前验收证据： - -- `crates/bat-assetbundle` 能解析结构化测试样本和隔离真实样本；新增 UnityPy `char_118_yuki.ab` 真实 bundle 回归入口，样本只下载到 `/tmp`，不入库。 -- 支持 UnityFS header、blocks、directory、metadata 摘要、directory 文件提取，并拒绝声明总大小不符、计数越界、重复/不安全路径和目录数据越界。 -- 支持 Unity serialized file object table、TypeTree node 元数据和 TextAsset 提取的合成 fixture。 -- 错误包含偏移和字段上下文。 - -关闭前仍需： - -- 冻结解除前不继续扩大 TypeTree 字段 reader 覆盖。当前 TypeTree-covered managed reference 字段与 registry 记录已可结构化解码，`m_ManagedReferences`、`RefIds` / `m_RefIds`、verbose type 字段、`managedReference*` / `serializedReference*` metadata、payload/value/object 家族、`managedReferenceData` / `referenceData` / `serializedData` / `serializedReferenceData` payload、多记录 registry 聚合、enum `value__` backing field、`LayerMask` / `BitField` 的 `m_Bits` backing field、固定 Unity float/int/hash 值类型 leaf/direct-child 形态、unknown fixed-size raw bytes 同长度替换、嵌套 vector `Array` 形态、`List` / `HashSet` 集合 alias、`first/second` 与 `key/value` map entry schema、空 array/vector/List/HashSet/map 扩容已有合成 fixture 覆盖；剩余真实版本差异、unknown 字段结构语义、更多 nested collection、managed reference registry / map entry 变体只记录为冻结后的工作。 -- 用真实 fixture 继续覆盖 MonoBehaviour、ScriptableObject 字段级遍历和字符串策略。 -- 输出可追溯文本定位：bundle path、archive entry、serialized file、path id、class id、field path、字段 offset/byte size。 -- 用真实资源 fixture 覆盖对象级解析、TextAsset 提取和字段级文本提取。 -- 将解析结果作为 Patch 输入；真正的重打包、Patch 生成和 `localized` 发布切换归 G-006/G-011D。 - -解析补全路线图： - -- 见 `docs/architecture/assetbundle.md` 的 P2/P3/P5。 - -### G-006：Patch 引擎基础已落地，通用发布入口仍未完成 - -状态：**部分关闭** - -已完成： - -- `bat-patch::binary` 已提供确定性 Binary hunk diff/apply，应用前校验 source size/BLAKE3，应用后校验 target size/BLAKE3。 -- `bat-patch::json` 已提供 RFC 6902 JSON Patch apply，覆盖 add/remove/replace/move/copy/test 和 JSON Pointer escape。 -- `bat-patch::text` 已提供 UTF-8 Text Patch，按 source-relative byte range 替换，支持 expected 文本校验、UTF-8 边界校验、source/target BLAKE3 和 size 校验。 -- `bat-patch::manifest` 已定义通用 Patch manifest、文件级 patch kind、source/target BLAKE3、size、rollback 元数据和 manifest 文件完整性校验。 -- `LocalizedPatchManifest` 可转换为通用 `bat_patch::PatchManifest`，UnityFS TextAsset 发布链路和通用 Patch manifest 已有类型对齐点。 -- `infrastructure::patch_ops`、`patch.apply` RPC 和 `patch-apply` CLI 已开放文件级 Binary/JSON/Text patch apply；输入/输出为显式文件路径，输出原子写入并返回 size/BLAKE3。 -- `unityfs.patch_text_asset` / `unityfs.patch_string_field` / `unityfs.patch_field` RPC 和 `unityfs-patch-text-asset` / `unityfs-patch-string-field` / `unityfs-patch-field` CLI 已开放显式 UnityFS bundle 文件写入；TextAsset、TypeTree string 字段、managed-reference registry `data` / `managedReferenceData` payload 字符串、基础语义字段、enum、bit_field、固定 Unity 值类型 leaf/direct-child 形态、unknown fixed-size raw bytes、object 字段组合和 TypeTree schema 支撑的 array/vector/List/HashSet/map 整体替换会在重建后重新解析校验。 - -影响： - -- 通用 Binary/JSON/Text Patch crate 能力可作为后续发布流程输入。 -- 文件级写入入口可用于隔离测试和上层工具显式产物生成。 -- 发布级通用 `patch build` / `patch rollback`、复杂 AssetBundle 重打包和完整翻译文件集合的正式使用仍未完成；issue 43 的 `parse repack`、`parse clear-cache`、`i18n validate` 与 `i18n publish` 仅覆盖已有 patch 实现支持的安全子集。 - -验收： - -- Binary patch 能完成 diff/apply 往返。 -- JSON patch 能应用 RFC 6902 patch。 -- Patch manifest 包含 hash、版本和回滚信息。 -- Patch 构建/应用必须写 staging，完整性校验通过后才能发布。 -- `patch.apply` / `patch-apply` 对显式文件执行 apply 时必须原子写目标文件，并返回 source/patch/target hash 与 size。 -- 失败时不得影响 `bat-resources/current` 或已发布 `bat-localized/current`。 - -### G-007：Addressables Catalog 解析不完整 - -状态：**当前目标字段已关闭，独立二进制格式待后续** - -现象： - -- `AddressablesCatalogDriver` 已能解析当前真实形态 JSON catalog fixture/golden。 -- 已输出 path、hash、size、resource_type、address、dependencies、provider ID、bundle name、metadata，并已提取 `m_Crc` 到 `crc` 字段。 -- compact catalog 解析已补充 hash/size/CRC 的非 0 回归、资源计数 metadata，以及 blob 解码失败时的明确错误；不再在 compact 字段损坏时静默退回低保真 `m_InternalIds`。 -- `bat-core` 已提供 `crc32_ieee` 和 `ResourceEntry::verify_downloaded_bytes`，SQLite `ResourceRepository` 已有 `crc`、provider_id、bundle_name 兼容迁移。 -- 当前 JSON/compact 目标字段已通过 expanded、alias、compact 和真实形态 golden 回归；独立二进制 catalog 仍明确拒绝，不静默丢字段。 - -影响： - -- 当前解析能力可以服务 Manifest inspect 和部分资源索引，但还不能宣称完整兼容所有 Unity Addressables/SBP catalog 形态。 - -验收： - -- 能解析项目目标版本的真实 Catalog 样本集合。 -- 解析结果包含资源 key、provider、dependency、hash、size、path、bundle name、CRC。 -- 对不支持的 catalog 结构返回明确错误，而不是静默丢字段。 -- 解析结果能反查 bundle 文件、依赖链和本地下载 manifest 条目。 -- Windows/Android 样本集合需要覆盖 JSON、compact JSON 和后续二进制 catalog 入口。 - -解析补全路线图： - -- 见 `docs/architecture/assetbundle.md` 的 P1。 - ---- - -## 3. 应用层缺口 - -### G-008：Go 同步/运维 CLI 产品入口 - -状态：**已决策关闭（wontfix）** - -决策（2026-07-24，见 `GO_STATUS.md`）： - -- **正式同步/运维命令行 = Rust `bat`**（近乎全自动：auto-discover + watch/daemon，无需持久手操维护）。 -- **不另做**产品级 Go 同步 CLI，避免与 Rust `bat` 双轨。 -- Go 试验入口 `cmd/bat` 可保留为 experimental，产物必须为 `bin/bat-go`，**禁止**再构建为 `bin/bat`。 -- Go 正式产品入口集中在 **`bat-api` 资源 bootstrap/分发服务** + `internal/backendrpc`（G-009）。 - -原验收（真实 doctor / Go sync 包装）**不再作为当前里程碑**。 - -### G-009：API Server（`bat-api`，资源 bootstrap/分发）部分完成 - -状态：**资源 bootstrap + CDN MVP 已落地；非完整官方游戏 API** - -目标（对应 issue #19，**按资源面收窄**）： - -- `cmd/bat-api`：组织 Rust `bat` 已发布 release 的启动前资源入口，并只读分发官方 CDN host/path 形态资源。 -- **拉取归属 Rust `bat`**；`bat-api` 不做下载器。 -- 发现经 `bat.sock`：先 `daemon.status`，再 `daemon.doctor`，再 `catalog.status` / `resource.manifest`。 -- Rust RPC 的 `resource.state`、`catalog.status`、`parse.status` 和 `localized.status` 会返回短状态 `status` 与稳定生命周期状态码 `status_code`；`backendrpc` 已提供对应 client 能力，当前 `bat-api` 发现流程只消费 `resource.state`、`catalog.status`、`resource.manifest`，translation task/handoff 通过受鉴权的 admin 查询端点暴露，parse/localized 不由 HTTP surface 暴露；错误原因仍以 `BAT-ERR-*` 为准。 -- `bat-api` 可通过受限 Web 控制面转发 `reload` / `refresh` / `restart` / `sync` / `verify` / `repair` / `catalog-refresh`，并通过 translation admin 端点查询/回写任务、触发 provider worker 和标记人工校对；这些动作均走 Rust live RPC；`parse.*`、`localized.status` 和文件级 `unityfs.patch_*` 属于 `backendrpc` 能力，但当前不由 HTTP surface 暴露；`daemon.clean-stable` 等危险或离线生命周期命令不经 Web 转发。 -- 生产与 Rust `bat` 同环境运行，资源根来自 RPC 返回的 `resource_root`；`--resource-root` 仅用于 fixture 或应急只读诊断。 -- `.env` 配置端口 / public base / RPC socket / RPC 刷新周期；预留 database/redis。 -- `/v1/bootstrap` 返回 RPC 健康、release 摘要、server-info URL、client-patch base 和改写后的 Addressables root。 -- `/v1/launcher/bootstrap` 和 `/api/launcher/...` 形状端点返回资源引导兼容信息，当前来源是 Rust `bat` 已发布 snapshot/RPC 中的 launcher metadata 与 GameMainConfig 摘要；Rust 侧已新增 release 内 `official-launcher-bootstrap.json` 版本化产物，后续 bat-api 字段统一和联调应以该产物加 RPC contract fixture 为准。 -- `/healthz` 暴露最近一次 RPC refresh 诊断；`/readyz` 在无可分发 release 时返回 `503`。 -- 玩家-facing HTTP 控制面必须支持 token 鉴权、限流、访问日志、反代 IP 适配、动态 JSON `no-store` 和 `/v1/resources` 分页上限。 -- CDN path 支持 `GET` / `HEAD` / `Range`、ETag、Last-Modified、Accept-Ranges 和长期缓存头。 -- launcher 完整安装包更新链、账号、登录、网关、游戏业务 API 和鉴权全链 **非关闭条件**；USERGUIDE 已补基础章节，联调后补生产排障样例。 - -已完成： - -- `cmd/bat-api`、`internal/api`、`/v1/bootstrap`、`/v1/launcher/bootstrap`、launcher 资源 metadata 兼容端点、HTTP token 鉴权、限流、访问日志、反代 IP 适配、动态 JSON `no-store`、`/v1/resources` 分页上限、OpenAPI、`/admin/` 管理控制白名单、RPC 周期刷新/诊断、`/readyz`、CDN Range/缓存头、fixture 单测、USERGUIDE 基础章节、systemd bat-api 模板、`make build-go-api` / `test-go-api` -- 进度权威：`docs/reports/GO_STATUS.md` -- Rust snapshot schema 与 Go mirror struct 的仓库内 contract fixture 已完成，文件位于 - `internal/api/testdata/contract/`；同机 live daemon socket 和完整 fixture release 切换已由 - `make bat-api-local-live-smoke` 验证。 - -后续跟踪（不影响 issue #19 关闭）： - -- 同机 live 联调已完成（覆盖 bootstrap、server-info、CDN path、release 切换、无 release、RPC 断线/恢复）；真实官方网络全量下载由 `make official-smoke` 独立跟踪 -- refresh 中 manifest 磁盘校验的 mtime/size 增量缓存优化（真实全量 release 观测后决定） -- 文档与 GO_STATUS 持续一致 - -排期：P2 主体可联调；持久化 API 层与完整 launcher/业务链另议。 - -### G-010：完整 Web 管理后台仍未实现 - -现象： - -- `web/` 已提供无构建内嵌 dashboard MVP，作为 `bat-api` 静态资产服务于 - `/admin/dashboard/`。 -- 当前页面可调用已鉴权的资源、调度、任务、日志、parse、翻译和 localized 发布/回滚 - 接口，但不提供独立登录、角色权限、术语管理、批量审核工作流或构建型前端工程。 - -影响： - -- 基础资源/调度/翻译控制可以在 dashboard 上完成。 -- 协作式翻译审核、术语管理和权限隔离仍缺少完整 UI。 - -验收： - -- 登录、权限、翻译审核、术语管理基础流程可用。 -- Dashboard E2E、静态资产构建/发布策略和错误态交互纳入常规门禁。 - ---- - -## 4. 数据与翻译缺口 - -### G-011：Resource Repository 查询面仍不完整 - -状态：**部分关闭** - -影响： - -- `SqliteResourceRepository` 已存在，可按领域 repository 接口保存资源元数据。 -- `ResourceImportService` 已能把 manifest 中有数据的资源写入 CAS + `ResourceRepository`，AssetBundle 会记录 UnityFS 摘要，TextAsset/Table/Media 会分类索引。 -- 官方同步下载结果可用 `--import-repository` / `BAT_IMPORT_REPOSITORY=1` 在已校验 release 发布后自动导入 CAS + ResourceRepository；默认 CAS 为 `/.cas`，默认 SQLite 索引为 `/resources.sqlite`，也可通过 `--import-cas-root`、`--import-resource-db`、`BAT_IMPORT_CAS_ROOT`、`BAT_IMPORT_RESOURCE_DB` 覆盖。 -- `resource.index` RPC/CLI 已能按资源类型、hash、路径模式、官方 release ID、平台、destination、bundle path、archive entry、parse status 和 TextUnit format 分页查询现有 SQLite 索引；release、平台、bundle path 和常用数组 metadata 过滤已下推到 SQLite；数据库不存在时返回 `available=false`，不会因查询创建空库。 -- `bat doctor cas` 可按 `/.cas` 或 `--import-cas-root` 只读诊断既有 CAS 根目录、对象目录、元数据库文件和对象统计，缺失路径会报告为不健康，不会创建空库。 -- 官方 release 发布后会写出 `official-resource-changes.json` 和 `crowdin-translation-handoff.json`，新增+变更资源进入解析/翻译 handoff，删除资源只进入差异记录。 -- `Resource` metadata 已通过 SQLite `metadata_json` 兼容迁移保存 release、平台、bundle path、parse status、TextAsset 名称和 TextUnit 数量/格式；`resource.index` 会返回这些 metadata。 -- 官方 release 发布后会持久化 `official-textunit-index.json`，记录单条 TextUnit 和解析错误；`parse.text_units` / `parse.errors` RPC 和 `parse-text-units` / `parse-errors` CLI 可按 destination、archive entry、path id、class id、field path 和 format 分页过滤。 -- 官方 release 发布后会从 Added/Modified 资源、parse cache 和 TextUnit 明细索引派生 `official-textunit-tasks.json`、`crowdin-textunit-queue.json` 和 `translation-tasks.sqlite`；删除资源不会进入队列。 -- 官方 release 发布后还会写入版本化 `translation-handoff.json`；`translation.handoff` RPC/CLI 动态合并该快照与 SQLite worker 状态，暴露 job、unit、provider run、attempt 和 failure reason。 -- `translation-tasks.sqlite` 由 `schema_migrations` 管理 durable task state、attempt count、provider run ID 和 failure reason；重复同步会保留已有 worker 状态。 -- `translation.tasks` RPC/CLI 优先查询 `translation-tasks.sqlite`，旧 release 没有状态库时回退到 `official-textunit-tasks.json`；返回队列 `status`、worker `task_status`、failure reason 和时间/尝试次数。 -- `translation.tasks` / `translation.handoff` 已提供 Go typed helper 和 bat-api 鉴权查询端点；`translation.task.update` 已提供 queued/running/failed/completed/skipped 状态回写契约，并已通过 `bat i18n task update`、Go typed helper 和 bat-api 鉴权控制面暴露；`translation.worker.run` 已提供 Rust provider worker，支持 mock/Crowdin、独立 claim、lease、失败分类、重试和 TextUnit 级译文结果落库；`translation.proofread` 已提供人工校对状态标记契约。 -- issue #47 已补齐官方资源同步的历史 release 与 CAS 前置复用：按计划顺序生成结果、按共享队列动态领取任务、对复用源执行 size/BLAKE3/ZIP 校验，失败时保留诊断并回退网络；CAS release 引用写入版本化清单，staging GC 会先释放引用再删除目录。更丰富的 Resource 查询、翻译记忆和通用 Patch 发布仍属于后续缺口。 -- `i18n get/set/unset` 可查看、修改或清空单条工作台译文，`i18n validate` 可在发布前校验工作台 release、source text、重复 patch 目标，并区分可直接发布的 TextAsset 与必须进入 `parse repack` 的条目；`i18n proofread` 可把当前汉化 workflow 标记为人工校对中，且不会遮蔽已发布汉化 release；`parse clear-cache` 只删除可再生解析/队列 JSON，保留 `translation-tasks.sqlite` 的 worker 状态。 -- 翻译记忆和完整 localized repack 仍属于后续翻译系统工作，不在当前 provider worker 状态闭环范围内。 - -验收： - -- schema 和迁移可重复执行。 -- 可按版本、平台、类型、hash、路径、destination、archive entry、parse status 和 TextUnit format 查询资源，且能明确区分索引缺失、版本缺失和空结果。 -- 官方同步后的资源可通过 CLI/RPC 查询并能追溯到 CAS 对象。 -- `official-parse-cache.json` 的 bundle、zip entry、TextAsset 和 TextUnit 摘要能进入 ResourceRepository 查询面。 -- `parse.status` 能报告 TextUnit 索引、TextUnit 队列路径与摘要。 -- `parse.text_units` / `parse.errors` 能分页查询当前 release 的 TextUnit 明细和解析错误。 -- 离线 TextUnit 翻译任务状态和跳过/失败 reason 可反查到对应官方 release、资源 destination 和 archive entry。 -- Crowdin handoff 被后续翻译 worker 消费后，worker 状态、远端失败原因和完成结果能反查到对应官方 release 与资源 destination。 - -解析补全路线图： - -- 见 `docs/architecture/assetbundle.md` 的 P4。 - -### G-011A：资源导入链路基础能力不足 - -状态：**已关闭** - -历史现象： - -- 资源导入链路只导入 AssetBundle。 -- 非 AssetBundle manifest 条目只会被跳过。 -- 导入报告只包含 UnityFS 基础摘要，不包含稳定分类统计。 - -处理结果： - -- `ResourceImportService` 会把有数据的 manifest 条目导入 CAS 并写入 `ResourceRepository`。 -- AssetBundle 仍执行 UnityFS header/block/directory 摘要解析。 -- TextAsset、TableBundle、Media 会按资源类型分类，缺少数据时记录为 skipped，便于渐进导入。 -- `ResourceImportReport` 增加 `category_counts`，`ImportedResource` 增加 `resource_type`、`category` 和可选 UnityFS 摘要。 - -验收： - -- `cargo test -p bat-infrastructure import::tests::` -- `cargo test -p bat-infrastructure --test synthetic_phase2_import` - -### G-011B：官方版本状态管理不明确 - -状态：**已关闭** - -历史现象： - -- 当前可用版本主要靠 `current` symlink 和 release 内 snapshot 推断。 -- 未显式保存“正在拉取版本”和“失败版本”。 -- 上一个可用版本需要从目录状态间接判断。 - -处理结果： - -- 新增 `/official-version-state.json`。 -- 开始下载后写入 `in_progress_version`。 -- 发布成功后写入 `current_completed_version` 和 `previous_available_version`。 -- 失败或中断后写入 `failed_versions` 并清空 in-progress。 -- `bat status` 会读取并展示版本状态摘要。 - -验收： - -- `cargo test -p bat-infrastructure version_state` -- `cargo test -p bat-infrastructure --test official_game_main_config_bootstrap` - -### G-011D：受支持汉化发布已完成，通用 Patch 发布流程仍未完成 - -状态：**部分关闭** - -当前已完成： - -- 官方原版资源发布根为 `./bat-resources`，汉化产物发布根为 `./bat-localized`。 -- CLI 支持 `--localized-output` / `BAT_LOCALIZED_OUTPUT`，并拒绝官方目录和汉化目录相同或互相嵌套。 -- 官方同步报告新增 `localized_release_status=not_localized`，明确表示原版资源已发布、汉化资源未发布；`translation.proofread` 只写 workflow 标记，不会把 `localized_release_status` 从 `localized` 回退成 `not_localized`。 -- `LocalizedPatchService` 已具备将给定汉化文件按官方相对路径发布到 `--localized-output` / `BAT_LOCALIZED_OUTPUT` 指定目录下的 `.staging/`、校验后移动到 `versions/`、原子切换 `current` 并写入 `localized-version-state.json` 的基础能力。 -- `LocalizedPatchService` 已写入结构化 `localized-patch-manifest.json`，记录 TextAsset、TypeTree string field 和 managed-reference string field 操作、原始/汉化 hash、size、byte delta、TextUnit/provider/review 和 rollback 信息；发布前后会校验 manifest hash/size 与 current symlink，失败时清理 staging / 未完成 version。 -- 已完成从 workbench 或 completed provider worker 结果生成受支持 patch operation 的流程；`localized.publish` / `localized.rollback` RPC、`i18n publish` / `i18n rollback` CLI，以及 bat-api 的鉴权 status/publish/rollback 接口已落地。 -- `localized.status` RPC 会读取 `.env` / daemon 配置中的汉化输出目录，校验汉化状态是否匹配当前官方 release，且要求 patch manifest 存在并匹配 release，避免写死 `./bat-localized` 或误报手工状态；其中 `status` / `status_code` 返回生命周期状态，`localized_release_status` 保留 `localized` / `not_localized` 发布标签，`translation_workflow_status=manual_proofreading` 仅描述人工校对流程，不影响已发布汉化资源继续正常发布。 - -仍未完成： - -- 真实 Patch/翻译构建阶段尚未从 `crowdin-textunit-queue.json`、翻译记忆和 Crowdin 结果生成完整汉化文件集合。 -- 通用 Binary/JSON/Text Patch crate 基础和文件级 `patch.apply` / UnityFS 写入入口已经实现；通用 manifest 驱动的跨类型发布、复杂 AssetBundle 重打包和双发布后的清理策略仍未完成。 -- 尚未实现原版资源与汉化资源双发布后的查询、分发和清理策略。 - -验收： - -- 原版资源同步成功后保持 `not_localized`，不发布半成品汉化资源。 -- Patch 构建和校验成功后，汉化产物按官方相对路径写入配置化汉化发布根下的 `versions/`。 -- 汉化发布必须原子切换配置化汉化发布根下的 `current`，失败时不影响已发布原版资源。 -- `localized` 状态能证明原版和汉化两套资源都可发布，并能被 CLI/RPC/API 查询；缺 patch manifest 或 release 不匹配时不得返回 `localized`。 - -### G-011C：真实 fixture 与回归样本不足 - -状态：**已关闭当前阶段** - -历史现象： - -- 已有 Addressables real-shape fixture/golden，但缺少按问题类型命名的当前/上一版本/结构变化样本。 -- 403/404 和 hash mismatch 主要依赖单测内联构造，不便于后续回归扩展。 - -处理结果： - -- 新增 `adapters/tests/fixtures/addressables_regression/current_catalog.json`。 -- 新增 `adapters/tests/fixtures/addressables_regression/previous_catalog.json`。 -- 新增 `adapters/tests/fixtures/addressables_regression/structure_changed_catalog.json`。 -- 新增 `infrastructure/tests/fixtures/official_regression/http_403.json`。 -- 新增 `infrastructure/tests/fixtures/official_regression/http_404.json`。 -- 新增 `infrastructure/tests/fixtures/official_regression/hash_mismatch_catalog.json`。 -- 对应测试会解析这些 fixture，防止样本只存在但不参与验证。 - -验收： - -- `cargo test -p bat-adapters --test addressables_regression` -- `cargo test -p bat-infrastructure regression_fixture` +仍需完成通用 patch 发布、复杂重打包、双 release 查询/分发视图和清理策略。 ### G-012：Translation Memory 未实现 -影响： - -- 无法复用人工翻译和 AI 翻译历史。 - -验收： - -- 精确匹配、模糊匹配、上下文匹配可用。 -- 记录 Provider、模型、审核状态和历史版本。 +需要支持精确、模糊和上下文匹配，并保留 provider、模型、审核状态和历史版本。 ### G-013：Glossary 未实现 -影响： +需要支持术语优先级、别名、分类、冲突检测和审核。 -- 无法保证术语一致性。 -- AI 翻译无法强制遵守术语。 +### G-014：完整 Provider 扩展体系未实现 -验收： +当前已有 mock/Crowdin provider worker、lease、重试和 TextUnit 结果落库；仍需建立 +可替换的 Provider 扩展体系，以及批处理、限流、成本统计和质量检查。 -- 术语优先级高于 AI。 -- 支持别名、分类、冲突检测、审核。 +## 2. 已确定的架构边界 -### G-014：AI Provider 抽象未实现 +以下内容不是待实现的重复任务： -影响： +1. 正式资源同步和运维命令行是 Rust `bat`；不另做产品级 Go 同步 CLI。 +2. Rust `bat` / daemon 是资源生产者和状态拥有者；Go `bat-api` 只读取已发布资源， + 通过 `bat.sock` 提供 bootstrap、分发和受限管理入口。 +3. `bat-api` 是资源 bootstrap/分发服务，**不是完整官方游戏 API**。 +4. `bat-ffi` 只保留无状态兼容 helper，不承载 daemon、下载器、CAS handle 或主控制面。 +5. 官方原版 release 和 localized release 使用独立目录、staging、manifest、current + 和 rollback 生命周期。 +6. `daemon.clean-stable` 是 CLI 生命周期清理入口，不在 live RPC 内执行在线清理； + `task.create` 也不作为通用 RPC 入口开放。 +7. `status` / `status_code` 描述生命周期，`BAT-ERR-*` 描述错误；两者不混用。 -- 无法接入 DeepL/OpenAI/Anthropic/Google/Azure。 +详细阶段报告仍保留在 `docs/reports/historical/`，不作为当前实现依据。 -验收： +## 3. 后续推进顺序 -- Provider 可替换。 -- 支持批处理、限流、重试、成本统计和质量检查。 - ---- - -## 5. 文档与发布缺口 - -### G-015：README 与当前真实状态不完全一致 - -状态：**已关闭** - -现象： - -- 旧 README 描述了最终架构，但部分功能尚未实现。 - -验收： - -- README 明确区分已实现、开发中、规划中。 - -处理结果： - -- README 已明确区分当前可用能力、未完成模块、官方同步运行命令和近期优先级。 - -### G-016：架构文档需要更新为当前路线图 - -状态：**已关闭当前阶段** - -现象： - -- 旧 `docs/architecture/README.md` 偏目标架构，容易让读者误以为 Go 同步器和 API/Web 已经可用。 - -验收： - -- 增加 ADR 或架构决策记录。 -- 明确 Rust/Go/DB/Plugin 边界。 - -处理结果： - -- 架构 README 已明确当前 Rust 官方同步入口、Go 计划边界和目标架构差异。 -- 官方资源后端说明由 `docs/architecture/official-resource-backend.md` 承载。 -- `bat-ffi` 已降级为可选无状态兼容层，主集成边界明确为 `bat --json` 进程边界或未来稳定 SDK。 - -### G-017：CI 未落地 - -状态：**已关闭（决策：不引入托管 CI）** - -原现象： - -- 仓库没有 GitHub Workflows 或等价托管 CI，质量门槛无自动远端执行。 - -处理结果： - -- 明确决策：本项目不加入 GitHub Workflows，也不引入其他托管 CI。 -- 目前补充了自托管 Gitea linux-runner workflow（`.gitea/workflows/bat.yml`），覆盖 Rust workspace 构建/测试、Go API 门禁和文档状态门禁，不改变“不引入托管 CI”的决策。 -- workflow 不使用外部 GitHub Action；它通过 runner 环境变量手动 `git fetch` 当前提交，并要求 runner 预装 `git`、Rust stable、rustfmt、clippy 和 Go，避免准备阶段因第三方 action 仓库代理或网络限制失败。 -- 质量门禁由本地默认验证命令和自托管 workflow 共同承担：提交前执行 `cargo fmt` / `cargo clippy --workspace --all-targets -- -D warnings` / `cargo test --workspace`、Go API 门禁和 `make check-docs`（见 `docs/guides/development.md` 与 `docs/guides/baseline.md`）。 -- 发布类检查（build、smoke）由 `Makefile` 与 `scripts/` 下的可重复脚本承担（如 `make official-smoke`）。 - -限制： - -- 门禁执行依赖提交者本地自觉，无远端强制拦截；若未来出现多人协作或外部贡献需求，可重新评估本决策。 - -### G-018：真实官方网络全量下载 smoke test 已固化为可重复命令 - -状态：**已关闭（已固化可重复 smoke 命令；真实下载产物不纳入 Git）** - -历史现象： - -- 本地测试覆盖 mock、fixture、synthetic import 和 CLI 参数。 -- 曾缺少真实官方网络全量下载的固定 runbook 和可重复命令。 - -处理结果： - -- 新增 `scripts/official-full-pull-smoke.sh`，默认在 `/tmp/bat-official-smoke-/` 下创建隔离资源目录、状态目录和报告目录。 -- 新增 `make official-smoke` 统一入口。 -- 新增 `docs/guides/official-full-pull-smoke.md`，记录目标、命令、输出结构、环境变量、安全边界和成功判定。 -- smoke 流程覆盖 dry-run plan、首次全量拉取、二次 `up_to_date`、人工破坏 active release 文件后的 `repair`、repair 后 `verify`。 -- 脚本会检查二次 `up_to_date`、repair 完成、verify `healthy=true`，并检查首次拉取和 repair 的 stderr log 中存在下载已完成计数、单文件进度和校验结果日志。 -- 运行报告 `SMOKE_REPORT.md` 记录实际输出目录、active release、文件数量、release 大小和被破坏文件；大型官方资源文件保留在隔离输出目录，不纳入 Git。 - -验收： - -- 使用 `scripts/official-full-pull-smoke.sh` 或 `make official-smoke`。 -- 默认输出目录必须是独立 `/tmp` 目录；非 `/tmp` 路径需要显式设置 `BAT_SMOKE_ALLOW_NON_TMP=1`，且输出目录必须为空。 -- 脚本退出码为 0 即表示 runbook 验收通过。 -- 真实网络执行需要外部网络和足够磁盘空间；本仓库只保存 runbook、脚本和测试，不保存官方大文件。 - -后续跟踪（非阻塞）： - -- 官方同步长期运行测试正在进行，运行报告将在后续提供。 - -### G-019：下载失败重试策略不够精细 - -状态：**已关闭** - -历史现象： - -- curl 失败只按固定次数重试，错误信息主要保留最后一次 stderr。 -- 403/404 和 5xx 没有不同处理。 -- 单个 URL 长期失败时缺少可查询的 quarantine 诊断状态。 -- 旧 launcher 包下载虽然有 primary/backup CDN 路径，但失败信息没有统一分类。 - -处理结果： - -- 新增统一 curl 失败分类：`http_forbidden`、`http_not_found`、`http_client_error`、`http_too_many_requests`、`http_server_error`、`dns`、`connect`、`timeout`、`tls`、`interrupted`、`network` 等。 -- 403/404/普通 4xx 视为不可重试并提前停止；5xx、429、DNS、连接、超时、中断和网络类错误按尝试次数重试。 -- 单个资源 URL 最终失败会写入 `official-download-quarantine.json`，记录失败类型、HTTP 状态、是否可重试、尝试次数和最后错误。 -- 失败 URL 会发出 Failed progress，daemon status 和 `bat-events.jsonl` 暴露失败类型、HTTP 状态、重试属性和 quarantine 状态。 -- quarantine 会中断同步并阻止发布不完整 staging；下一轮成功下载或复用后清理对应 quarantine 条目。 -- 旧 launcher 包或 `resources.assets` 下载在 primary CDN 失败后会切换官方 backup CDN。 - -验收： - -- HTTP 404 不重试，写入 quarantine，manifest 不写失败项。 -- HTTP 5xx 重试到上限后写入 quarantine。 -- launcher primary CDN 失败后会尝试官方 backup CDN。 - ---- - -## 6. 当前关闭顺序建议 - -1. issue #24：失败 staging 复用回归已补；核对残余场景。 -2. issue #1：RPC 主体、文件级 `patch.apply` / `unityfs.patch_text_asset` / `unityfs.patch_string_field` / `unityfs.patch_field` 已落地；剩余发布级 patch build/rollback、复杂 UnityFS 语义编辑与设计边界确认。 -3. issue #17 的历史顺序/重试契约仍保留；当前 issue #33/#35 已补有界 downloader - scheduler 和默认并发 8，范围 `1..=256`，worker 完成后立即领取下一个任务， - 进度即时按完成数上报，最终 report 保持 plan 顺序。 -4. **issue #47：官方资源历史 release/CAS 复用已完成**；后续只跟踪真实官方长期运行和更丰富的版本清理策略。 -5. **G-008：已决策关闭**（同步 CLI = Rust `bat`；见 `GO_STATUS.md`）。 -6. **G-009 / issue #19**：资源 bootstrap/分发和同机 live 联调已完成；非「从零实现」。后续真实官方网络长期运行、持久化和完整 launcher/业务链不属于本 issue 关闭条件。 -7. issue #2 / G-007（P1）：Addressables 可校验字段。 -8. issue #3 / G-005（P1）：UnityFS 容器基础解析已落地；对象级引擎解析继续跟踪 G-005。 -9. G-011：更丰富的 TextUnit 查询、翻译记忆查询和通用 Patch 发布所需资源视图。 -10. G-012 / G-006：Crowdin/翻译系统、复杂 AssetBundle 重打包和 Patch 发布流程统一。 -11. G-011D：原版/汉化双发布后的查询、分发和清理策略。 - -Go 进度以 `docs/reports/GO_STATUS.md` 为准。G-018 / G-017 已关闭。 +1. 继续 G-005：真实 AssetBundle 样本、复杂字段解析和发布级重打包。 +2. 继续 G-006/G-011D：通用 manifest Patch 和双 release 查询/清理策略。 +3. 继续 G-011/G-012/G-013/G-014：资源查询、Translation Memory、Glossary 和 Provider + 扩展体系。 +4. 在隔离环境执行 `make official-smoke`，补充真实网络长期运行报告。 +5. 最后推进完整 Web 协作后台和完整游戏业务 API。 diff --git a/docs/reports/GO_STATUS.md b/docs/reports/GO_STATUS.md index 59d5d9c..0cc722f 100644 --- a/docs/reports/GO_STATUS.md +++ b/docs/reports/GO_STATUS.md @@ -1,8 +1,8 @@ # Go 侧进度与边界（权威） -- **更新时间**：2026-09-02 +- **更新时间**：2026-09-04 - **用途**：统一 Go module `bat-api` 的产品边界、既有约定和组件进度；其他文档与此冲突时以本文为准。 -- **关联**：issue #19 / G-009（资源 bootstrap/分发）、G-008（已决策关闭）、`docs/architecture/official-resource-backend.md` §7、`docs/guides/bat-api-local-live-smoke.md` +- **关联缺口**：G-009（资源 bootstrap/分发）；相关契约见 `docs/architecture/official-resource-backend.md` §7 和 `docs/guides/bat-api-local-live-smoke.md` --- @@ -38,7 +38,7 @@ ### 1.3 决策（已核验） -1. **G-008 决策关闭（wontfix）**：不另做产品级 Go 同步/运维 CLI。 +1. **Go 同步 CLI 边界已确定**：不另做产品级 Go 同步/运维 CLI，正式入口是 Rust `bat`。 2. **G-009**：资源 bootstrap/分发 MVP 部分完成；非完整游戏业务 API。 3. **USERGUIDE 的 bat-api 基础章节已补**；同机 live 联调 runbook 和内嵌 dashboard MVP 已补，真实官方网络下载仍由独立 smoke 负责。 @@ -100,7 +100,7 @@ | 试验 CLI | `cmd/bat` | **试验** | doctor 固定 ok；manifest/sync 走 FFI | | FFI | `internal/ffi` | **可选** | 需 `build-ffi` | | 空骨架 | `api/`、`pkg/*`、部分 `internal/*` | **空** | 见各目录 README | -| Web | `web/` | **内嵌 dashboard MVP** | issue #46；完整协作后台、登录/角色和术语管理仍属 G-010 剩余 | +| Web | `web/` | **内嵌 dashboard MVP** | 完整协作后台、登录/角色和术语管理仍属 G-010 剩余 | `go list ./...` 当前包： @@ -129,13 +129,12 @@ make build-go-cli # 产出 bin/bat-go --- -## 5. 与缺口 / issue 对应 +## 5. 与缺口对应 | 项 | 状态 | |---|---| -| G-008 Go 同步 CLI | **已决策关闭**（正式同步 CLI = Rust `bat`） | +| Go 同步 CLI | **边界已确定**（正式同步 CLI = Rust `bat`） | | G-009 bat-api 资源 bootstrap/分发 | **资源面完成（非完整官方游戏 API）**；已含资源 bootstrap、launcher resource metadata 兼容、HTTP 鉴权/限流/日志/反代适配、RPC 周期刷新/诊断、readiness、OpenAPI、管理控制白名单、Rust-owned `schedule.*`、`task.*`、`parse.*`、翻译状态回写代理、内嵌 dashboard、同机 live smoke 和部署模板；持久化仍另议 | -| issue #19 | **验收完成，本提交关闭**；`make bat-api-local-live-smoke` 已在同机隔离环境覆盖 live RPC、release 切换、清单不完整、未 ready、server-info 和 CDN path | | G-010 Web | 内嵌 dashboard MVP 已完成；完整协作后台、登录/角色、术语管理和构建型前端未开始 | --- @@ -143,10 +142,10 @@ make build-go-cli # 产出 bin/bat-go ## 6. 资源布局与逆向 - **Release / URL / 分发契约（权威）**：`docs/architecture/resource-release-layout.md` -- 真机全量实勘、seed inventory diff、issue #2/#3 样本采集按该文档 §9–§10 执行 +- 真机全量实勘、seed inventory diff 和样本采集按该文档 §9–§10 执行 ## 7. 后续（不在进度统一范围内） 1. 预留 database/redis 的接入时机另议 -2. 真实官方网络全量下载长期运行报告（使用 `make official-smoke`，与 issue #19 同机 live 联调独立） -3. launcher 完整安装包更新链 / 登录网关链（若需要，新 issue） +2. 真实官方网络全量下载长期运行报告（使用 `make official-smoke`，与同机 live 联调独立） +3. launcher 完整安装包更新链 / 登录网关链（如需推进，应另立范围明确的后续需求） diff --git a/docs/reports/PARSER_FREEZE.md b/docs/reports/PARSER_FREEZE.md deleted file mode 100644 index 27fe61d..0000000 --- a/docs/reports/PARSER_FREEZE.md +++ /dev/null @@ -1,81 +0,0 @@ -# 解析模块维护冻结 - -状态：**生效中** - -生效时间：2026-07-30 - -冻结目标：停止继续扩大 UnityFS / AssetBundle / Addressables / TypeTree 解析能力，把当前工作重心切换到运行稳定性、代码审核问题、文档一致性和发布链路可靠性。 - -## 冻结范围 - -冻结覆盖以下 Rust 解析相关模块和对外入口： - -- `crates/bat-assetbundle` -- `adapters/src/unity*` -- `infrastructure/src/official_parse.rs` -- `infrastructure/src/resources.rs` 中解析缓存、TextUnit 索引和解析状态相关逻辑 -- `unityfs.*`、`parse.*`、`text.*` 相关 RPC / CLI 契约 -- Addressables catalog、UnityFS、serialized file、TypeTree、TextUnit、AssetBundle patch 相关文档声明 - -## 允许变更 - -冻结期只允许以下解析相关变更： - -- 修复编译失败、格式化失败、clippy 报错和测试失败。 -- 修复真实运行中已经复现的 panic、错误状态污染、重复解析、缓存失效、状态不一致或诊断误导。 -- 补充回归测试，前提是测试覆盖的是已存在能力的稳定性问题，不宣称新增解析能力。 -- 修正文档、CLI 帮助、RPC 参考和状态文件中与当前实现不一致的解析能力声明。 -- 改善错误信息、日志字段、状态记录和失败恢复，但不得改变解析输出契约，除非是修复错误契约且同步迁移说明。 - -## issue 43 的明确例外 - -本次 issue 43 经用户明确授权，允许新增 `bat` 的工作流编排入口： - -- `parse run` 只刷新已有解析输出、TextUnit 索引和翻译队列； -- `parse repack` 只调用已有 TextAsset、TypeTree string 和受支持语义字段 patch 实现； -- `i18n` 工作台和 `publish` 只消费已有 TextUnit 输出，并发布独立汉化 release。 - -该例外不解冻解析器，不新增 UnityFS/AssetBundle/Addressables/TypeTree 解析类型、字段覆盖、catalog 结构或合成 fixture 能力。后续任何扩大解析覆盖的变更仍需单独解冻授权。 - -## issue 2/3 的开发例外 - -授权时间：2026-08-19 - -用户明确授权将 issue #2/#3 作为解析开发进展继续推进。本次例外允许： - -- Addressables JSON/compact catalog 的 provider、bundle name、hash、size、CRC、资源类型和依赖关系字段补全，以及对应 SQLite/fixture 回归； -- UnityFS 已有 header、block、directory、压缩和 alignment 能力的校验加固，以及隔离真实 bundle 回归； -- 更新解析路线图、状态和 RPC/CLI 资源索引字段说明。 - -本次例外不包含发布级复杂对象重打包、完整 Unity 版本兼容承诺或新的汉化发布控制面；这些仍按后续 Patch/发布路线单独验收。 - -## 禁止变更 - -冻结期禁止以下解析相关变更： - -- 新增 TypeTree 语义类型、字段族、managed reference 变体、Unity 内建结构体覆盖或 Addressables catalog 结构覆盖。 -- 用纯合成 fixture 推进“完整解析”并把它记录为已支持能力。 -- 开放新的写入型 `unityfs.*` / `patch.*` RPC 或 CLI。 -- 修改解析结果 schema、TextUnit schema、patch field JSON 语义或缓存状态格式，除非它是阻断级 bug 修复并附带兼容策略。 -- 将解析器和官方同步、汉化发布、Go API、Crowdin 或客户端流程进一步耦合。 - -## 解冻条件 - -解析扩展重新启动前必须同时满足： - -- Rust `bat` 官方同步、daemon、status、校验、断点续传、增量更新和解析缓存链路稳定。 -- 当前 P0/P1 维护 issue 已关闭或被明确降级。 -- `bat-api` 与 Rust RPC / CLI 契约完成字段统一和联调验证。 -- 真实资源 fixture、验证命令和验收标准已写入文档，不能只依赖合成样本。 - -## 冻结期验证 - -解析相关维护变更至少运行： - -```bash -cargo fmt --check -cargo test -p bat-assetbundle --locked -cargo clippy -p bat-assetbundle --all-targets --locked -- -D warnings -``` - -如果变更影响 `bat` CLI、RPC、官方解析缓存或 TextUnit 索引，还必须补充对应 `bat-infrastructure` 测试或说明未运行原因。 diff --git a/docs/reports/historical/root/FINAL_STATUS.md b/docs/reports/historical/root/FINAL_STATUS.md index 5ab8617..6e457f5 100644 --- a/docs/reports/historical/root/FINAL_STATUS.md +++ b/docs/reports/historical/root/FINAL_STATUS.md @@ -70,12 +70,12 @@ ## 📚 重要文档索引 ### 架构和设计 -- `docs/ARCHITECTURE_REVIEW.md` - 完整架构审查（1903行） -- `docs/BLUE_ARCHIVE_TECHNICAL_ANALYSIS.md` - 技术分析 -- `docs/CODE_QUALITY_IMPROVEMENT.md` - 代码质量优化详情 +- `docs/archive/ARCHITECTURE_REVIEW.md` - 完整架构审查（1903行） +- `docs/archive/BLUE_ARCHIVE_TECHNICAL_ANALYSIS.md` - 技术分析 +- `docs/reports/historical/nested-docs/CODE_QUALITY_IMPROVEMENT.md` - 代码质量优化详情 ### 进度报告 -- `docs/PHASE_1_WEEK_1_COMPLETE.md` - Week 1 详细报告 +- `docs/reports/historical/nested-docs/PHASE_1_WEEK_1_COMPLETE.md` - Week 1 详细报告 - `PHASE_1_WEEK_1_FINAL_REPORT.md` - Week 1 最终报告 ### 代码质量 diff --git a/docs/reports/historical/root/PHASE_1_WEEK_1_FINAL_REPORT.md b/docs/reports/historical/root/PHASE_1_WEEK_1_FINAL_REPORT.md index 5fe4270..8fe458d 100644 --- a/docs/reports/historical/root/PHASE_1_WEEK_1_FINAL_REPORT.md +++ b/docs/reports/historical/root/PHASE_1_WEEK_1_FINAL_REPORT.md @@ -109,11 +109,11 @@ BlueArchiveToolkit/ ## 📚 创建的文档 -1. ✅ [ARCHITECTURE_REVIEW.md](./docs/ARCHITECTURE_REVIEW.md) - 完整架构审查（1903 行） -2. ✅ [BLUE_ARCHIVE_TECHNICAL_ANALYSIS.md](./docs/BLUE_ARCHIVE_TECHNICAL_ANALYSIS.md) - 技术分析报告 -3. ✅ [PHASE_0.5_REPORT.md](./docs/PHASE_0.5_REPORT.md) - 深度验证报告 -4. ✅ [PHASE_1_WEEK_1_COMPLETE.md](./docs/PHASE_1_WEEK_1_COMPLETE.md) - Week 1 详细报告 -5. ✅ [WEEK_1_VERIFIED.md](./WEEK_1_VERIFIED.md) - 最终验证报告 +1. ✅ [ARCHITECTURE_REVIEW.md](../../../archive/ARCHITECTURE_REVIEW.md) - 完整架构审查（1903 行） +2. ✅ [BLUE_ARCHIVE_TECHNICAL_ANALYSIS.md](../../../archive/BLUE_ARCHIVE_TECHNICAL_ANALYSIS.md) - 技术分析报告 +3. ✅ [PHASE_0.5_REPORT.md](../nested-docs/PHASE_0.5_REPORT.md) - 深度验证报告 +4. ✅ [PHASE_1_WEEK_1_COMPLETE.md](../nested-docs/PHASE_1_WEEK_1_COMPLETE.md) - Week 1 详细报告 +5. `WEEK_1_VERIFIED.md` - 原报告未纳入当前归档。 --- diff --git a/scripts/check-doc-links.sh b/scripts/check-doc-links.sh new file mode 100644 index 0000000..f33e94c --- /dev/null +++ b/scripts/check-doc-links.sh @@ -0,0 +1,42 @@ +#!/usr/bin/env bash +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "${repo_root}" + +missing=0 + +while IFS= read -r -d '' file; do + while IFS= read -r link; do + target="${link#*](}" + target="${target%)}" + target="${target%%#*}" + target="${target%% *}" + target="${target#<}" + target="${target%>}" + + case "${target}" in + ''|\#|http://*|https://*|mailto:*) + continue + ;; + esac + + resolved="$(dirname "${file}")/${target}" + if [[ ! -e "${resolved}" ]]; then + printf 'missing Markdown link: %s: %s -> %s\n' \ + "${file}" "${target}" "${resolved}" >&2 + missing=1 + fi + done < <(rg -o '\]\([^)]*\)' "${file}" || true) +done < <( + find . -type f \( -name '*.md' -o -name '*.markdown' \) \ + -not -path './.git/*' \ + -not -path './target/*' \ + -print0 +) + +if [[ "${missing}" -ne 0 ]]; then + exit 1 +fi + +printf 'markdown local link check ok\n' diff --git a/scripts/check-doc-status.sh b/scripts/check-doc-status.sh index 615c63f..dddb7df 100644 --- a/scripts/check-doc-status.sh +++ b/scripts/check-doc-status.sh @@ -27,15 +27,25 @@ require_regex() { } required_docs=( + "README.md" + "CONTRIBUTING.md" + "AGENTS.md" + "DOCS_INDEX.md" "CURRENT_STATUS.md" "USERGUIDE.md" "PROJECT_PLAN.md" + "docs/architecture/README.md" + "docs/architecture/adr/0004-rust-bat-go-bat-api-resource-boundary.md" "docs/architecture/assetbundle.md" + "docs/architecture/resource-release-layout.md" "docs/guides/development.md" + "docs/guides/deployment.md" "docs/reference/rpc-backend-api.md" "docs/reports/CURRENT_GAPS.md" "docs/reports/GO_STATUS.md" - "docs/reports/PARSER_FREEZE.md" + "docs/reports/BAT_API_CONTRACT_FIXTURE_HANDOFF.md" + "api/openapi/bat-api.yaml" + "internal/api/openapi.go" "internal/api/testdata/contract/README.md" ) @@ -43,6 +53,24 @@ for file in "${required_docs[@]}"; do require_file "${file}" done +[[ ! -e "Agents.md" ]] || fail "stale agent document path exists: Agents.md" +[[ ! -e "CHECK.md" ]] || fail "obsolete CHECK.md still exists" +[[ ! -e "docs/reports/PARSER_FREEZE.md" ]] || + fail "obsolete parser freeze document still exists" + +go_version="$(sed -n 's/^go[[:space:]]\{1,\}//p' go.mod | head -n 1)" +[[ -n "${go_version}" ]] || fail "go.mod is missing a Go version" +require_contains "README.md" "Go ${go_version}+" +require_contains "docs/guides/development.md" "Go ${go_version}+" +require_contains "DOCS_INDEX.md" "## 1. 项目入口与协作规则" +require_contains "DOCS_INDEX.md" "## 3. 架构、决策与稳定契约" +require_contains "DOCS_INDEX.md" "## 7. 历史归档" +require_contains "DOCS_INDEX.md" "docs/reports/historical/" +require_contains "docs/architecture/README.md" "目标设计" +require_contains "docs/architecture/README.md" "实际实现状态以源码、测试和根目录 \`CURRENT_STATUS.md\` 为准；\`PROJECT_PLAN.md\` 只描述目标和路线图" +require_contains "docs/architecture/adr/0004-rust-bat-go-bat-api-resource-boundary.md" 'Rust `bat` 是官方资源生产者和状态拥有者' +require_contains "docs/architecture/adr/0001-engine-and-application-boundaries.md" "资源同步职责已由 ADR 0004 取代" + placeholder_readmes=( "api/README.md" "api/proto/README.md" @@ -64,25 +92,17 @@ for file in "${placeholder_readmes[@]}"; do require_contains "${file}" "docs/reports/GO_STATUS.md" done -parser_freeze_docs=( - "CURRENT_STATUS.md" - "PROJECT_PLAN.md" - "docs/architecture/assetbundle.md" - "docs/guides/development.md" - "docs/reports/CURRENT_GAPS.md" -) - -for file in "${parser_freeze_docs[@]}"; do - require_contains "${file}" "docs/reports/PARSER_FREEZE.md" -done - require_contains "USERGUIDE.md" "scope=resource_bootstrap_only" require_contains "USERGUIDE.md" "package_update_manifest=false" require_contains "docs/reports/GO_STATUS.md" "resource bootstrap + CDN path" require_contains "docs/reports/GO_STATUS.md" "internal/api/testdata/contract/" require_contains "CURRENT_STATUS.md" "cmd/bat-api" require_contains "CURRENT_STATUS.md" "internal/api/testdata/contract/" -require_contains "docs/reports/CURRENT_GAPS.md" "非完整官方游戏 API" +require_contains "CURRENT_STATUS.md" "不提供官方账号登录、游戏网关协议或完整 package update manifest" +if grep -Fq "响应只来自已发布 snapshot/RPC，不提供登录、网关、鉴权" CURRENT_STATUS.md; then + fail "CURRENT_STATUS.md contradicts its documented bat-api token authentication" +fi +require_contains "docs/reports/CURRENT_GAPS.md" "不是完整官方游戏 API" require_contains "docs/reports/CURRENT_GAPS.md" "daemon.clean-stable" require_contains "docs/reference/rpc-backend-api.md" "daemon.restart" require_contains "docs/reference/rpc-backend-api.md" "daemon.clean-stable" @@ -93,5 +113,23 @@ require_contains ".gitea/workflows/bat.yml" "make check-docs" require_contains ".gitea/workflows/bat.yml" "make test-go-api" require_contains ".gitea/workflows/bat.yml" "go vet ./internal/api/... ./internal/backendrpc/... ./cmd/bat-api/..." require_contains ".gitea/workflows/bat.yml" "go build -o /tmp/bat-api ./cmd/bat-api" +require_contains "Makefile" "cargo clippy --workspace --all-targets -- -D warnings" + +openapi_tmp="$(mktemp)" +trap 'rm -f "${openapi_tmp}"' EXIT +awk ' + /^const openAPISpecYAML = `/ { + started = 1 + sub(/^const openAPISpecYAML = `/, "") + print + next + } + started && /^`$/ { exit } + started { print } +' internal/api/openapi.go > "${openapi_tmp}" +cmp -s "api/openapi/bat-api.yaml" "${openapi_tmp}" || + fail "static OpenAPI document differs from internal/api/openapi.go" + +bash scripts/check-doc-links.sh printf 'doc status check ok\n'