BlueArchiveToolkit/AGENTS.md

AGENTS.md

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

具体开发进度看 CURRENT_STATUS.md，开发计划看 PROJECT_PLAN.md，当前能力缺口看 docs/reports/CURRENT_GAPS.md，具体工程任务、优先级和依赖看根目录 TODO.md。这里不记录具体任务和阶段待办。

基本要求

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

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

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

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

工程修改原则

BlueArchiveToolkit 不以“最小修复”为工程目标。不要为了让单个 testcase 通过、暂时消除表面症状或缩小 diff，而留下已经能够确认的同根因问题。

处理问题时优先保证长期可维护性、可用性、安全性、明确契约、恢复能力和回归覆盖。进入一个工程边界后，应根据实际相关性检查正常路径、异常路径、并发、重试、恢复、兼容、持久化和资源限制，并把属于同一 root cause 或同一 contract 的问题完整收口。

这不意味着无边界重构。不要为了架构形式、代码行数或“以后也许会用”扩大修改范围；与当前 contract 无关的问题应记录到 TODO.md，留给后续独立处理。

跨模块问题必须沿真实状态所有权和调用链检查。例如 Rust 状态经 RPC 暴露给 Go，再由 HTTP 或 Web 消费时，不能只修改其中一层而让其他层继续保持矛盾语义。

持久化和状态机修改应考虑 schema/version、transaction、crash consistency、retry、recovery 与兼容读取；解析器、压缩包和其他外部输入应考虑 size/count/depth 等资源边界以及 malformed input 的确定性失败。

以什么为准

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

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

• 当前源码和测试；
• 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。

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

Dashboard 开发与设计

BlueArchiveToolkit 包含两个面向不同使用者的 Dashboard：用户 Dashboard 与运营 Dashboard。两者属于同一产品，应共享基础视觉语言、组件风格和交互一致性，但不得因为复用组件而混淆产品职责、信息层级或权限边界。

涉及 Dashboard、Web UI、页面布局、视觉样式、组件设计或交互体验的任务，在开始设计和修改前必须阅读仓库根目录的 DESIGN.md。

DESIGN.md 是 Dashboard 的主要视觉参考与设计灵感来源。应理解并延续其中的色彩关系、排版、空间、边框、层级、组件形态和交互气质，但不得机械复制其来源产品的页面结构、品牌内容或不适合 BlueArchiveToolkit 的设计。实际页面的信息架构始终由 BlueArchiveToolkit 当前功能、真实数据结构和使用场景决定。

用户 Dashboard

用户 Dashboard 面向普通 BlueArchiveToolkit 用户，目标是以尽可能低的认知负担完成与汉化相关的用户操作。

当前用户可控制的核心能力仅包括：

• 文字汉化是否启用；
• 图像汉化是否启用。

用户端可以展示与这些操作直接相关的必要信息，例如汉化状态、当前可用版本、更新状态、操作反馈或用户需要处理的异常，但不得暴露内部运维实现。

除非未来产品需求明确改变，否则用户 Dashboard 不应展示或要求用户理解：

• bat / bat-api 内部状态；
• RPC、daemon、worker；
• CAS；
• Provider / provider run；
• Translation Memory 内部记录；
• translation task；
• Parser；
• official/localized release 的内部实现细节；
• 服务端日志、内部错误栈和运维指标。

用户端优先保证清晰、简洁、可信和易操作。不要为了表现“Dashboard 感”堆积 KPI 卡片、图表、技术指标或无实际用途的信息。

运营 Dashboard

运营 Dashboard 面向项目运营和维护者，用于观察和管理 BlueArchiveToolkit 的真实运行状态。

运营端可以根据当前后端实际提供的 contract 展示和组织：

• bat 与 bat-api 运行状态；
• official resource / official release；
• localized resource / localized release；
• 资源同步与更新状态；
• Translation / Translation Memory；
• Provider 与 worker；
• task / job；
• daemon/runtime；
• CAS；
• 错误、诊断与日志；
• 配置和必要的运营操作。

运营 Dashboard 是高信息密度的 developer/operations interface。优先使用结构化列表、表格、紧凑状态信息、清晰的主次层级和按需 drill-down，而不是将所有数据做成大型 Card。

首页应帮助运营者快速回答“系统是否正常、哪里需要处理、最近发生了什么”，而不是简单罗列所有可获得的指标。

两个 Dashboard 的关系

两个 Dashboard 应共享：

• 基础 Design Token；
• Typography；
• Color System；
• Button、Input、Switch、Dialog 等基础组件；
• Loading、Empty、Error、Warning、Success 等状态语言；
• Motion 与交互反馈原则；
• 品牌识别。

但可以拥有不同的：

• Navigation；
• 页面结构；
• 信息密度；
• 内容层级；
• 默认组件尺寸；
• 数据展示方式。

不要把运营 Dashboard 简单裁剪几个菜单后作为用户 Dashboard，也不要为了用户端的简洁限制运营端所需的信息密度。

设计实现原则

Dashboard 设计必须以真实接口和真实状态为依据。不得为了视觉完整性伪造后端不存在的数据、指标、趋势、操作或状态。

如果设计需要当前 API/RPC 尚未提供的信息，应明确指出缺失 contract，而不是在前端维护第二份业务状态或通过猜测拼接数据。

优先复用项目现有前端组件和设计基础。引入新组件模式前先确认现有组件无法合理满足需求，避免同一项目逐步形成多套 Card、Table、Badge、Button 或状态展示体系。

DESIGN.md 是视觉方向，不高于项目稳定架构与产品事实。发生冲突时按以下优先级处理：

AGENTS.md 与稳定产品/接口契约 > 当前明确任务需求 > DESIGN.md > Agent 自身设计偏好。

代码修改

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

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

避免：

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

如果当前任务确实无法完成某一部分，应明确限制实现范围；具体后续工程任务记录到根目录 TODO.md，能力缺口同步到 CURRENT_GAPS.md，需要外部协作时再使用 Issue。

TODO 任务治理

根目录 TODO.md 是具体工程任务、优先级、依赖关系和完成条件的仓库内任务账本。开始具体开发前，应读取与当前工作相关的 TODO；完成任务或发现独立新问题后，应同步更新其状态和依赖。

TODO.md 不是当前实现事实来源。源码和测试、CURRENT_STATUS.md、专项 current-status 文档以及稳定 contract 的优先级高于 TODO 描述。若 TODO 与当前实现冲突，应先核对事实并更新过时 TODO，不要按照旧条目重新实现已经完成的能力。

属于当前任务同一 root cause 或同一 contract 的已确认问题，不得仅为了缩小 patch 而登记 TODO 后绕过；应在当前工程边界内一起收口。明显独立的问题应记录到 TODO.md，避免当前修改无限扩张。

docs/reports/CURRENT_GAPS.md 用于记录产品或工程能力层面的当前缺口；PROJECT_PLAN.md 用于长期路线；TODO.md 用于可执行任务追踪。不要把这些职责混在一起。

文件、网络和发布安全

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

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

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

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

测试

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

Rust 修改通常至少考虑：

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 门禁。

涉及文档状态时运行：

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；能力缺口进入 docs/reports/CURRENT_GAPS.md；具体工程任务、依赖和完成条件进入根目录 TODO.md；需要外部协作时再使用 Issue。

Dashboard 的视觉方向与设计灵感进入根目录 DESIGN.md；Dashboard 的产品职责、状态所有权和接口事实仍以本文件与稳定产品/接口契约为准。

工作方式

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

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

完成后检查三件事：

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