BlueArchiveToolkit/DOCS_INDEX.md

BlueArchive Toolkit 文档分类索引

• 更新时间：2026-09-04
• 用途：按用途、时效性和权威级别定位文档。
• 原则：目录是物理归档方式，不能单独代表文档权威性；当前源码、测试和下列当前文档优先于历史报告。

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 对外接口规范

• docs/reference/rpc-backend-api.md：Rust Resource Backend JSON-RPC 稳定 contract。
• api/openapi/bat-api.yaml：bat-api HTTP OpenAPI 静态规范。
• docs/api/README.md：API 文档入口及规范索引。

契约文档涉及字段、状态码、错误码、release layout 或路径语义时，必须与源码测试和 internal/api/testdata/contract/ 一起复核。

4. 用户、开发与运维指南

这些文件描述如何使用或验证已经存在的能力：

• 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 本地链接门禁。

deployments/ 下的 systemd、Docker、环境文件和数据库配置是部署材料，不作为独立架构文档；其行为说明以本节指南和当前源码为准。

5. 分析资料和机器产物

以下资料用于分析或测试，不是当前能力声明：

• 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 仍需单独标注。

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/：已被当前状态和指南取代的阶段交接报告。
• 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/：从旧目录结构迁移出来的历史报告。

8. 推荐阅读顺序

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/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

阅读顺序中的状态和契约结论必须回到当前源码、测试和实际命令验证；历史报告只用于解释演进过程。