refactor(ffi): 降级 FFI 为可选兼容层并整理文档

将 bat-ffi 明确收敛为无状态 C ABI 兼容层，默认集成路径改为 bat --json 进程边界或未来稳定 SDK。

同步 README、当前状态、项目计划、架构文档、开发指南和缺口清单，移除 FFI 作为主集成边界的表述。

新增 AGENTS.md 和 CONTRIBUTING.md，压缩 CLAUDE.md 为兼容入口，并归档阶段性报告、同步 .gitignore 规则。

docs/reports/historical/README.md

@@ -0,0 +1,14 @@
+# 历史报告归档说明
+
+本目录只保存追溯资料，不代表当前项目状态。当前状态以根目录 `CURRENT_STATUS.md`、`PROJECT_PLAN.md`、`DOCS_INDEX.md` 和 `docs/reports/CURRENT_GAPS.md` 为准。
+
+归档分类：
+
+- `current-stage/`：曾用于阶段交接或推送前核查的临时 current report，已由当前状态文档和指南取代。
+- `root/`：早期位于仓库根目录的阶段报告。
+- `week2/`、`week3/`：早期周报、阶段报告和质量报告。
+- `quality/`：早期质量状态报告。
+- `build-logs/`：历史构建、测试和 Clippy 输出。
+- `nested-docs/`：从误嵌套 `docs/docs` 移出的历史报告。
+
+新增运行产物、smoke 输出、质量扫描输出和本地分析报告不要放入本目录；这些文件应写入 `/tmp`、显式的隔离输出目录，或被 `.gitignore` 覆盖的本地生成报告目录。

docs/reports/historical/current-stage/current-stage-prepush.md

@@ -0,0 +1,74 @@
+# 当前阶段说明
+
+- **更新时间**：2026-07-14
+- **状态分支**：`experiment`
+- **最新功能提交**：以当前 `git log --oneline -1` 为准
+- **用途**：当前阶段交付说明、推送前核查和下一步依据。
+
+## 1. 当前目标
+
+当前阶段的目标已经从“验证官方资源链路”推进到“让 Rust 官方资源同步具备可运行闭环，并为 Go CLI 最小入口做准备”。
+
+已完成的阶段目标：
+
+1. Rust 官方资源拉取入口不依赖已安装官方启动器。
+2. 自动发现官方 `app-version`、`connection-group`、`server-info`。
+3. 拉取 Windows + Android 官方资源集合。
+4. 保存 snapshot，按远端 marker 和本地 manifest 判断是否需要更新。
+5. 支持 `bat --watch` 常驻检查，默认每 1 小时运行一次。
+6. 通过文档明确生产目录不能指向已有客户端或开发资源目录。
+
+## 2. 当前实现状态
+
+已确认可用：
+
+- `bat-cas-engine` CAS V1。
+- `bat-adapters` 官方日服 URL 规则、server-info 解析、平台 discovery、inventory 枚举。
+- `AddressablesCatalogDriver` 对当前真实形态 fixture/golden 的解析。
+- `OfficialResourcePullService` 的官方 URL 拒绝、`.part` 续传、403/404/5xx 分类重试、下载 quarantine、本地 manifest、官方 seed `.hash` 校验。
+- 旧 launcher 包或 `resources.assets` 下载的官方 primary/backup CDN 切换。
+- `OfficialUpdateService` 的 auto-discover、bootstrap cache、v2 snapshot、remote marker diff、本地 audit/repair。
+- `bat` one-shot 和 `--watch`。
+- `bat` 运行时 progress log 覆盖总体下载进度、单文件进度和校验结果摘要。
+- 真实官方网络全量下载 smoke 已固化为 `scripts/official-full-pull-smoke.sh`、`make official-smoke` 和 `docs/guides/official-full-pull-smoke.md`。
+- `bat-ffi` 的 Manifest inspect 和 sync plan JSON API。
+- `SqliteResourceRepository`。
+
+仍未完成：
+
+- Go CLI 最小可用入口。
+- 官方同步下载结果自动触发 CAS + ResourceRepository 导入的用户级流程。
+- AssetBundle 对象表、TypeTree 和 TextAsset 提取。
+- Patch、翻译系统、API Server、Web。
+
+## 3. 当前核查结果
+
+已执行并通过：
+
+```bash
+cargo test -p bat-adapters -- --nocapture
+cargo test -p bat-ffi -- --nocapture
+cargo test -p bat-infrastructure -- --nocapture
+cargo test -p bat-infrastructure --bin bat -- --nocapture
+cargo run -p bat-infrastructure --bin bat -- --help
+git diff --cached --check
+```
+
+提交后确认：
+
+```bash
+git status --short
+```
+
+结果：工作区干净。
+
+## 4. 当前结论
+
+当前 Rust 官方资源同步链路已经具备可运行闭环，并已固化真实网络 smoke 的可重复命令；版本状态、资源导入基础链路和离线回归 fixture 已补齐。但仓库还不是完整产品。下一步不应继续只扩展 example，而应补齐 Go CLI 最小入口、官方同步后自动导入编排和 AssetBundle 对象级解析。
+
+## 5. 下一步
+
+1. 实现 Go CLI：`bat doctor`、`bat sync --help`、`bat official sync --help`。
+2. 按 `docs/guides/official-full-pull-smoke.md` 在具备网络和磁盘窗口的环境中执行真实官方网络 smoke，输出目录必须隔离。
+3. 将官方同步下载结果自动接入 CAS + `SqliteResourceRepository` 的用户级命令。
+4. 开始 AssetBundle 对象表、TypeTree 和 TextAsset 提取。

docs/reports/historical/current-stage/current-status-handoff.md

@@ -0,0 +1,68 @@
+# 当前进度交接
+
+- **更新时间**：2026-07-15
+- **状态分支**：`experiment`
+- **最新功能提交**：以当前 `git log --oneline -1` 为准
+- **用途**：给下一次对话快速恢复上下文，优先以当前工作区和已验证结果为准。
+
+## 1. 现在处在什么阶段
+
+项目已经完成基础整理、CAS V1、Rust 官方资源同步闭环，以及真实官方网络 smoke 的可重复命令固化。下一阶段重点是 Go CLI 最小可用、同步结果进入 CAS/ResourceRepository，以及 AssetBundle 解析起步。
+
+已确认的事实：
+
+- 当前分支为 `experiment`。
+- `bat-cas-engine` 的 CAS V1 已完成。
+- `bat` 是当前官方资源同步正式入口。
+- Linux 生产链路不安装、不启动、不依赖官方启动器。
+- `--auto-discover` 通过官方 HTTP metadata 和临时目录解析 `GameMainConfig`。
+- 默认平台是 `Windows + Android`。
+- 真实下载会维护 `official-download-manifest.json`，并使用 size + BLAKE3、本地 audit/repair 和官方 seed `.hash` 校验。
+- 下载失败会按 403/404/5xx/网络类型分类；最终失败写入 `official-download-quarantine.json` 并阻止发布不完整资源。
+- 旧 launcher 包或 `resources.assets` 下载使用官方 primary/backup CDN 切换。
+- `--watch` 是 Rust 内部常驻检查模式，正常检查默认 1 小时，失败重试默认 60 秒；外部 systemd/container 只负责守护进程。
+- `bat` progress log 会输出总体下载进度、单文件进度和校验结果摘要。
+- 真实官方网络 smoke 已固化为 `scripts/official-full-pull-smoke.sh`、`make official-smoke` 和 `docs/guides/official-full-pull-smoke.md`，默认写入 `/tmp` 隔离目录。
+- `official-version-state.json` 已持久化当前完成、正在拉取、上一个可用和失败版本，`bat status` 会显示版本状态摘要。
+- 资源导入链路已支持 CAS + `ResourceRepository` 写入，AssetBundle UnityFS 摘要，以及 TextAsset/Table/Media 分类索引。
+- 当前 catalog、上一个版本 catalog、结构变化 catalog、403、404、hash mismatch 已有离线回归 fixture。
+
+## 2. 现在不要误解的点
+
+- `cargo test` 不会自动开始真实全量下载。
+- 仓库里的本地实样本测试仍应显式启用，不应默认读取 `/home/wanye/D/BlueArchive`。
+- `bluearchive.cafe` 不是官方资源域名，不能当成官方链路使用。
+- 生产输出目录必须独立，不要指向已有客户端目录、官方启动器安装目录或开发资源目录。
+- Go CLI 尚未实现；当前可运行同步入口是 Rust binary。
+- `catalog_*.hash` 当前作为 Addressables marker，不按官方 seed `.hash` 的 `xxHash32(seed=0)` 规则做内容强校验。
+
+## 3. 当前还没做完什么
+
+仍待实现的主线工作：
+
+1. Go CLI 最小入口：`bat doctor`、`bat sync --help`、`bat official sync --help`。
+2. 按 smoke runbook 在具备网络和磁盘窗口的环境中执行真实官方网络 smoke，并保留隔离目录报告。
+3. 官方同步下载结果自动触发 CAS + `SqliteResourceRepository` 的用户级导入流程。
+4. Addressables parser 覆盖二进制/压缩字段组合和更细失败诊断。
+5. AssetBundle 对象表、TypeTree 和 TextAsset 提取链路继续推进。
+6. Patch、翻译库、API Server、Web。
+
+## 4. 下一次对话最合适的起点
+
+建议从 Go CLI 最小可用开始：
+
+1. 读取 `README.md`、`CURRENT_STATUS.md`、`PROJECT_PLAN.md`。
+2. 读取 `docs/guides/official-resource-test-pull.md` 和 `docs/architecture/official-resource-backend.md`。
+3. 实现 `cmd/bat` 和最小命令树。
+4. Go CLI 调用 `bat` 时显式传 `--json`，把该结构化 report 作为稳定机器输出来源。
+
+## 5. 相关入口
+
+- `README.md`
+- `PROJECT_PLAN.md`
+- `CURRENT_STATUS.md`
+- `DOCS_INDEX.md`
+- `docs/reports/CURRENT_GAPS.md`
+- `docs/guides/official-resource-test-pull.md`
+- `docs/guides/official-full-pull-smoke.md`
+- `docs/architecture/official-resource-backend.md`