BlueArchiveToolkit/AGENTS.md

# AGENTS.md

本文件用于约束在 BlueArchiveToolkit 中工作的 AI Agent。

具体开发进度看 `CURRENT_STATUS.md`，开发计划看 `PROJECT_PLAN.md`，当前缺口看 `docs/reports/CURRENT_GAPS.md`。这里不记录具体任务和阶段待办。

## 基本要求

默认使用简体中文交流、写文档和提交说明。代码标识符、协议字段、数据库字段、命令参数等保持英文。

BlueArchiveToolkit 是长期维护项目。不要为了尽快完成当前任务引入明显的临时实现，也不要把未来计划描述成已经存在的能力。

修改代码前先读相关实现。涉及跨模块改动时，至少确认当前状态、相关架构文档、测试和已有接口，不要只看一个文件就重新设计整个模块。

如果发现用户提出的方案、现有代码或文档本身有问题，直接指出。不要为了迎合要求保留明显不合理的设计。

## 以什么为准

仓库里有不少历史文档，不能混着看。

判断**当前实现**时，优先参考：

* 当前源码和测试；
* `CURRENT_STATUS.md`；
* 对应模块的专项状态文档，例如 `docs/reports/GO_STATUS.md`；
* 已冻结的 RPC、release、schema 等契约。

`PROJECT_PLAN.md` 和 `CURRENT_GAPS.md` 描述的是计划和缺口，不代表功能已经实现。

`docs/archive/` 和 `docs/reports/historical/` 只用于追溯历史，不应作为当前实现依据。

如果文档之间冲突，先核对源码和测试，再判断哪份文档已经过时。修代码时顺手修正相关权威文档，不要让冲突继续留在仓库里。

ADR 记录架构决策，但旧 ADR 中已经被后续实现明确替代的部分不能机械照搬。

## 现有边界

当前正式的资源同步和运维入口是 Rust `bat`。

官方资源发现、下载、校验、版本状态、staging、release 发布、watch/daemon、任务和相关长期状态都由 Rust 侧负责。不要在 Go、Web 或其他模块再实现一套相同状态机。

Go `bat-api` 是资源 bootstrap、只读分发和管理入口。它通过 `bat.sock` RPC 消费 Rust 状态，并读取 Rust 已经发布的资源。不要让它直接管理官方同步状态，也不要在 Go 里重新实现 CAS、AssetBundle 解析或 Patch 核心算法。

`bat-ffi` 只是兼容接口，不是主集成方式。不要把 daemon、下载器、CAS 长生命周期状态或新的主控制面塞进 FFI。

官方原版 release 和 localized release 是两套独立生命周期。已经发布的官方 release 应当视为不可变输入，汉化和 Patch 必须走独立 staging、校验、发布和 rollback 流程。

前端、API 和 CLI 不应维护第二套业务状态。状态以真正拥有它的后端模块为准。

## 模块和接口

优先使用仓库已经存在的抽象，例如 Repository、Adapter、Driver、Registry、Provider、RPC 和现有状态模型。

不要因为新增一个功能就平行实现第二套下载、存储、解析、Patch、翻译任务或 release 系统。

容易随着 Blue Archive、Unity、Addressables 或外部服务变化的逻辑应尽量留在 adapter/driver/provider 一侧，不要散进整个业务代码。

同时不要为了“以后可能会扩展”提前创建大量无实际用途的接口。只有已经存在多实现需求，或确定属于高变化边界的部分，才值得进一步抽象。

公共或持久化接口修改时要考虑兼容性。特别注意：

* RPC method 和 schema；
* `status` / `status_code`；
* `BAT-ERR-*` 错误码；
* CLI JSON 输出；
* release layout；
* manifest/state 文件；
* SQLite/PostgreSQL schema；
* Patch manifest；
* HTTP API。

不要静默改变已有字段的含义。确实需要破坏性修改时，先考虑版本号、迁移或兼容读取。

## 代码修改

先弄清楚代码为什么放在当前位置，再决定是继续修改还是拆模块。

仓库里已经存在一些较大的文件。不要因为“文件太长”机械拆分，但也不要继续往一个已经承担过多职责的文件里塞新的独立功能。按职责拆，不按行数拆。

避免：

* 重复实现已有能力；
* 大范围无关重构；
* 为测试专门加入生产逻辑；
* 静默吞错；
* 无说明的硬编码；
* 魔法数字；
* 假实现、空实现冒充完成功能；
* 用 `TODO` / `FIXME` 代替正式的缺口记录。

如果当前任务确实无法完成某一部分，应明确限制实现范围，并把剩余问题记录到对应的状态、缺口或 Issue 中。

## 文件、网络和发布安全

资源处理代码不能绕过现有的路径和完整性检查。

涉及文件写入、下载、CAS、Patch、release 或客户端文件时，应继续遵守仓库现有做法，包括路径归属检查、symlink 防护、临时文件、原子写入、hash/size 校验、失败不发布不完整结果等。

官方资源链路只使用项目当前允许的官方来源。不要为了绕过失败偷偷加入镜像或来源不明的 fallback。

密钥、Token、代理凭据等不能进入 Git，也不能无必要地出现在日志、状态文件或进程参数中。

## 测试

根据改动范围运行仓库已有的测试和检查，不要自己发明另一套质量流程。

Rust 修改通常至少考虑：

```bash
cargo fmt --all -- --check
cargo check --workspace
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
```

Go / bat-api 修改使用仓库现有 Makefile 和对应 `go test` / `go vet` 门禁。

涉及文档状态时运行：

```bash
make check-docs
```

涉及真实资源格式、RPC contract、release 或网络流程时，优先补已有 fixture、contract test、integration test 或 smoke，而不是只写一个理想化单元测试。

不能只根据合成样本宣称支持新的官方格式。

不方便运行某项重要测试时，在结果里说明没有运行什么以及原因。

## 文档

改动如果影响用户或其他模块能够观察到的行为，就同步对应文档。

尤其是：

* CLI；
* RPC；
* HTTP API；
* 配置项；
* release 布局；
* schema；
* 错误码和状态码；
* 模块职责；
* 当前实现状态。

不要把具体任务、临时优先级或某次实现方案写进本文件。

新的长期架构决策应该进入 ADR 或对应架构文档；开发路线进入 `PROJECT_PLAN.md`；实际进度进入 `CURRENT_STATUS.md`；未完成内容进入 `CURRENT_GAPS.md` 或 Issue。

## 工作方式

局部且模式明确的修改可以直接做。

涉及公共契约、新子系统、持久化格式、跨语言边界、大范围重构或安全边界时，先把现有实现和影响范围弄清楚，再动代码。

完成后检查三件事：

1. 有没有重复仓库已经存在的能力；
2. 有没有无意改变稳定接口或状态所有权；
3. 代码、测试和权威文档是否仍然一致。