BlueArchiveToolkit/DOCS_INDEX.md

BlueArchiveToolkit 文档索引

• 更新时间：2026-07-20
• 说明：本索引用于快速定位当前权威文档和历史资料。

---

1. 权威入口

• README.md：项目概览、当前可用能力和快速开始。
• PROJECT_PLAN.md：完整开发计划和最终目标路线图。
• CURRENT_STATUS.md：当前工作区真实状态。
• docs/reports/CURRENT_GAPS.md：当前实现缺口和关闭顺序。
• docs/guides/official-resource-test-pull.md：官方资源拉取与自动更新用户指南。
• docs/guides/official-full-pull-smoke.md：真实官方全量拉取 smoke runbook 和可重复命令。
• docs/architecture/official-resource-backend.md：官方资源后端职责、工作原理和审核说明。
• CHANGELOG.md：版本变更记录。
• AGENTS.md：AI agent 和自动化开发助手长期规则。
• CONTRIBUTING.md：贡献者协作、提交和验证要求。
• CLAUDE.md：Claude Code 等旧工具的兼容入口。

---

2. 架构与指南

• docs/architecture/README.md：总体架构设计。
• docs/api/README.md：API 设计入口。
• 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/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/architecture/cas.md：CAS 生产级设计。
• docs/architecture/assetbundle.md：AssetBundle 解析设计。
• docs/architecture/translation.md：翻译系统设计。

---

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：历史重构清单。

---

4. 历史报告

历史报告已按来源和主题归档，供追溯使用，不再代表当前状态。

• 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/quality/：历史质量报告。
• docs/reports/historical/nested-docs/：从误嵌套 docs/docs 移出的报告。

---

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/architecture/official-resource-backend.md
6. docs/reports/CURRENT_GAPS.md
7. docs/guides/baseline.md
8. docs/architecture/README.md
9. docs/guides/development.md
10. CONTRIBUTING.md
11. 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 校验。
• 真实官方网络全量拉取 smoke 已固化为 scripts/official-full-pull-smoke.sh 和 make official-smoke，默认写入 /tmp 隔离目录并输出本地运行报告。
• bat 运行时 progress log 已覆盖总体下载进度、单文件下载进度和校验结果摘要。
• Addressables 当前真实形态 fixture/golden 覆盖。
• SQLite Resource Repository 和可选无状态 bat-ffi JSON 兼容接口。

优先待办：

• 收敛 Go 产品入口的最终形态，避免把试验性 cmd/bat 误当作完成品。
• 将官方同步结果接入 CAS + ResourceRepository 的用户级流程。
• 推进 AssetBundle UnityFS 引擎级解析。