BlueArchiveToolkit/DOCS_INDEX.md

# BlueArchiveToolkit 文档索引

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

---

## 1. 权威入口

- `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` 调度接口。
- `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 等旧工具的兼容入口。

---

## 2. 架构与指南

- `docs/architecture/README.md`：总体架构设计。
- `docs/api/README.md`：API 设计入口。
- `api/openapi/bat-api.yaml`：当前 `bat-api` 资源 bootstrap/分发 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/architecture/cas.md`：CAS 生产级设计。
- `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/guides/bat-api-local-live-smoke.md`
6. `docs/guides/bat-workflows.md`
7. `docs/architecture/official-resource-backend.md`
8. `docs/reference/rpc-backend-api.md`
9. `docs/reports/CURRENT_GAPS.md`
10. `docs/guides/baseline.md`
11. `docs/architecture/README.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` 校验。
- 官方原版资源与汉化产物目录分离：`./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（进度见 `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 已覆盖下载已完成计数、单文件下载进度和校验结果摘要。
- 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 的用户级流程。
- 推进 AssetBundle UnityFS 引擎级解析。