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

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

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

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

docs/architecture/README.md

@@ -42,7 +42,7 @@ BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建
 ### 3. 数据流设计
 
 ```
-用户请求 → CLI/API → Go 业务层 → Rust 核心/同步层 → CAS 存储 → 数据库
+用户请求 → CLI/API → Go 业务层 → bat --json / SDK → Rust 核心/同步层 → CAS 存储 → 数据库
          ↓                    ↓
       Web UI              缓存层 (Redis)
 ```
@@ -128,7 +128,8 @@ current symlink → official-sync-snapshot.json + official-download-manifest.jso
 **后续 Go 职责**：
 
 - 提供最小稳定 CLI。
-- 包装或调用 Rust 同步入口，需要机器输出时使用 `--json` 并转发结构化 report。
+- 默认通过 `bat --json` 进程边界包装 Rust 同步入口，并转发结构化 report。
+- `bat-ffi` 仅作为可选无状态 C ABI 兼容层，不承载官方同步 daemon、下载器或 CAS handle。
 - 编排 API Server、任务队列、Provider 和用户配置。
 
 ---
@@ -320,7 +321,8 @@ CREATE TABLE resource_versions (
 ```
 开发机器 (本地)
 ├── CLI (Go)
-├── Rust 库
+├── Rust bat 进程 / 未来 SDK
+├── 可选 bat-ffi 兼容层
 └── 连接 → 远程数据库服务器 (裸金属)
             ├── PostgreSQL
             └── Redis

docs/architecture/adr/0001-engine-and-application-boundaries.md

@@ -35,7 +35,7 @@ BlueArchiveToolkit 的最终目标覆盖资源同步、CAS、AssetBundle 解析
 
 3. **Go 应用层**
    - 负责 CLI、资源同步、下载器、API Server、任务调度、配置、日志、Provider 编排。
-   - 通过稳定 SDK、进程边界，必要时再通过 FFI 调用 Rust 引擎能力。
+   - 通过稳定 SDK 或进程边界调用 Rust 能力；FFI 只作为可选兼容层。
    - 不重复实现 AssetBundle 解析、Patch 算法或 CAS 对象存储核心逻辑。
 
 4. **Web 层**
@@ -48,7 +48,7 @@ BlueArchiveToolkit 的最终目标覆盖资源同步、CAS、AssetBundle 解析
 
 1. Rust 引擎 API 必须保持业务无关，不出现 CLI 命令、HTTP 状态码、Web 页面状态。
 2. Go 应用层不得复制 Rust 引擎中的 Hash、Patch、AssetBundle 核心算法。
-3. 跨边界优先级应是进程边界或稳定 SDK，其次才是 FFI；若使用 FFI，必须只暴露粗粒度批量和事务语义。
+3. 跨边界优先级应是进程边界或稳定 SDK，其次才是 FFI；若使用 FFI，必须只暴露粗粒度、无状态、一次调用一次输入输出的兼容 API。
 4. 所有跨边界错误必须能映射到统一错误码和可读诊断信息。
 
 ---
@@ -63,7 +63,7 @@ BlueArchiveToolkit 的最终目标覆盖资源同步、CAS、AssetBundle 解析
 
 代价：
 
-1. 需要维护 FFI 或 SDK 边界。
+1. 需要维护进程、SDK 和可选 FFI 兼容边界。
 2. 错误类型、数据结构和版本兼容性需要更早设计。
 3. 集成测试必须覆盖跨语言调用，而不能只看单 crate 单元测试。
 
@@ -75,4 +75,5 @@ BlueArchiveToolkit 的最终目标覆盖资源同步、CAS、AssetBundle 解析
 
 1. `crates/bat-cas-engine` 是 CAS 核心实现位置。
 2. `infrastructure` 不再复制 CAS 存储算法，只做 `bat-core::repositories::CasRepository` 适配。
-3. Go CLI 后续通过稳定边界调用 CAS，不直接操作 CAS 内部目录结构。
+3. Go CLI 后续默认通过 `bat --json` 进程边界或稳定 SDK 调用 Rust 能力，不直接操作 CAS 内部目录结构。
+4. `bat-ffi` 只能保持为可选无状态兼容层，不能承担 daemon lifecycle、下载器状态、资源锁或 CAS handle。

docs/architecture/official-resource-backend.md

@@ -183,6 +183,12 @@
 
 `OfficialUpdateService` 是当前 Rust 侧的自动更新核心，正式命令入口是 `bat`。
 
+集成边界：
+
+1. 当前生产和 Go CLI 默认集成路径是运行 `bat --json` 并消费结构化 report。
+2. systemd、容器或上层 Go 进程只负责守护 `bat --watch` / `bat --daemon`，不直接接管下载器内部状态。
+3. `bat-ffi` 只允许作为可选无状态 C ABI 兼容层，用于 Manifest inspect 和 sync plan 这类一次性 JSON helper；它不是官方同步 daemon、下载器、资源锁、CAS handle 或主控制面的承载位置。
+
 流程是：
 
 1. 显式执行 `--auto-discover` 或读取已审计 `server-info` 输入。

docs/archive/ARCHITECTURE_REVIEW_SUMMARY.md

@@ -288,8 +288,9 @@ BlueArchiveToolkit/
 ## 📚 相关文档
 
 - [完整架构审查报告](./ARCHITECTURE_REVIEW.md)（1900+ 行）
-- [当前架构文档](./architecture/README.md)
-- [CLAUDE.md](../CLAUDE.md) - 项目开发指南
+- [当前架构文档](../architecture/README.md)
+- [开发指南](../guides/development.md) - 当前开发流程
+- [Agent 开发规则](../../AGENTS.md) - AI agent 长期规则
 
 ---
 

docs/guides/baseline.md

@@ -62,10 +62,10 @@ chore: establish development baseline
 
 ```bash
 git status --short --branch
-git check-ignore -v Cargo.lock CLAUDE.md
+git check-ignore -v Cargo.lock CLAUDE.md AGENTS.md CONTRIBUTING.md
 ```
 
-`Cargo.lock` 和 `CLAUDE.md` 必须纳入版本控制。
+`Cargo.lock`、`CLAUDE.md`、`AGENTS.md` 和 `CONTRIBUTING.md` 必须纳入版本控制。
 
 ---
 

docs/guides/development.md

@@ -1,5 +1,7 @@
 # 开发指南
 
+本指南是本地开发流程的权威入口。贡献协作规则见 `../../CONTRIBUTING.md`，AI agent 长期规则见 `../../AGENTS.md`。
+
 ## 环境准备
 
 ### 安装依赖
@@ -59,6 +61,14 @@ make test
 make fmt
 ```
 
+开发约束：
+
+1. 先阅读相关文档和代码，再判断实现方式。
+2. 跨模块、架构、数据格式或用户工作流变更必须先说明设计取舍。
+3. 保持改动聚焦，不做无关重构、批量格式化或元数据 churn。
+4. 公共接口、状态文件、manifest、catalog、patch 和下载流程变更必须补充测试或 fixture。
+5. 用户可见命令、运行路径、配置、状态文件、日志或缺口状态变化时，同步更新 README、指南、架构文档或 `docs/reports/CURRENT_GAPS.md`。
+
 ### 3. 提交
 
 ```bash
@@ -86,6 +96,10 @@ git push origin feature/your-feature-name
 
 ## 代码规范
 
+默认使用简体中文写文档、提交说明、开发日志和面向用户的说明。代码标识符、协议字段、数据库字段、包名和命令参数保持英文命名规范。
+
+禁止使用 demo、临时实现、硬编码路径或只为当前测试通过的伪实现。确实未完成的能力应写入当前缺口文档，而不是用 `TODO` 或 `FIXME` 隐藏。
+
 ### Go
 - 遵循 [Effective Go](https://golang.org/doc/effective_go)
 - 使用 `gofmt` 格式化
@@ -104,16 +118,30 @@ git push origin feature/your-feature-name
 
 ## 测试
 
-### 当前必跑测试
+### 合并前通用门禁
 
 ```bash
+cargo fmt --check
+cargo test --workspace
+cargo clippy --workspace --all-targets -- -D warnings
+```
+
+Go CLI 尚未实现时，`go test ./...` 可能没有产品级 package 可运行；Makefile 会在空 Go 阶段清晰跳过。
+
+### 常用聚焦命令
+
+```bash
+cargo test -p bat-core -- --nocapture
 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 clippy -p bat-core -p bat-adapters -p bat-infrastructure --all-targets -- -D warnings
 ```
 
-Go CLI 尚未实现时，`go test ./...` 可能没有产品级 package 可运行；Makefile 会在空 Go 阶段清晰跳过。
+官方资源同步、下载、daemon、status、verify 或 repair 相关改动必须至少覆盖 `bat-infrastructure` 和 `bat` 二进制测试。
+
+`bat-ffi` 只是可选无状态 C ABI 兼容层。修改 FFI 导出、JSON schema、错误返回或 `internal/ffi` CGO 包装时必须运行 `cargo test -p bat-ffi -- --nocapture`；Go CLI 和生产同步默认应通过 `bat --json` 进程边界集成。
 
 ### 集成测试
 
@@ -141,6 +169,8 @@ cargo run -p bat-infrastructure --bin bat -- \
 
 开发环境真实下载默认写入 `./bat-resources`；如果要覆盖，必须使用 `/tmp` 或其他隔离目录，不要写入现有资源目录。
 
+生产或 CI 环境不得依赖安装官方启动器。需要启动器信息时，只能分析启动器资源、官方 manifest 或公开更新数据，并将解析结果固化为可验证流程。
+
 ### 基准测试
 
 ```bash
@@ -180,9 +210,11 @@ cargo fetch
 
 先确认失败是否来自真实网络或本地资源路径。默认测试应使用 fixture/mock，不应依赖官方线上资源或开发机已有资源目录。
 
-### 3. FFI 绑定问题
+### 3. FFI 兼容层问题
 
-重新生成绑定：
+`bat-ffi` 不是主集成边界，只用于需要 C ABI 的兼容场景。默认 Go CLI 集成优先运行 Rust `bat --json`。
+
+重新构建兼容库：
 ```bash
 cd crates/bat-ffi
 cargo build

docs/reports/CURRENT_GAPS.md

@@ -172,7 +172,7 @@
 现象：
 
 - `cmd/bat` 目录存在，但无 `main.go`。
-- `internal/ffi/ffi.go` 已存在，但还不是用户可运行 CLI。
+- `internal/ffi/ffi.go` 已存在，但只是可选 CGO 兼容包装，不是用户可运行 CLI，也不是默认 Go/Rust 集成边界。
 - `go test ./...` 当前没有产品级 Go package 覆盖。
 
 影响：
@@ -185,6 +185,7 @@
 - `bat doctor` 可运行。
 - `bat --help` 命令结构稳定。
 - 命令支持默认人类可读输出和 `--json` 机器输出。
+- Go CLI 默认通过 Rust `bat --json` 进程边界获取同步 report；除非明确兼容需求，不依赖 FFI。
 
 ### G-009：API Server 和 OpenAPI 尚未实现
 
@@ -378,6 +379,7 @@
 
 - 架构 README 已明确当前 Rust 官方同步入口、Go 计划边界和目标架构差异。
 - 官方资源后端说明由 `docs/architecture/official-resource-backend.md` 承载。
+- `bat-ffi` 已降级为可选无状态兼容层，主集成边界明确为 `bat --json` 进程边界或未来稳定 SDK。
 
 ### G-017：CI 未落地
 

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` 覆盖的本地生成报告目录。