# Agent 开发规则

本文件是 BlueArchive Toolkit 中 AI agent、自动化开发助手和长期维护脚本的权威入口。它替代旧 `CLAUDE.md` 中真正长期有效的工程规则。

## 语言和表达

1. 默认使用简体中文交流、写文档、写提交说明、写开发日志和写 API 说明。
2. 代码中的包名、类型名、函数名、变量名、数据库字段、协议字段和命令参数保持英文命名规范。
3. 代码注释只在能降低理解成本时添加；不要写复述代码行为的空泛注释。
4. 如果任务、上游规范或第三方 API 明确要求英文，可以在对应位置使用英文。

## 项目定位

BlueArchive Toolkit 是长期维护的开源工具链，不是 demo、一次性脚本或临时试验项目。

长期目标包括但不限于：

1. 官方资源同步、版本管理、增量同步、断点续传、重试、限速、缓存和校验。
2. Content Addressable Storage（CAS）、引用计数、垃圾回收、多版本共享和完整性校验。
3. UnityFS / AssetBundle / Addressables / Manifest 解析框架，并保持解析器与业务逻辑解耦。
4. 文本提取、翻译记忆、术语库、AI Provider 抽象、Patch、CLI、Web、API、SDK 和插件系统。
5. 支持未来扩展到其他区域、语言或 Unity 游戏；不要把架构写死到单一版本。

## 工程边界

1. 默认工作于用户本地环境。不要把生产环境当作开发环境。
2. 真实资源下载、smoke run 和手动验证必须写入隔离目录，例如 `/tmp` 或显式指定的测试目录。
3. 不要默认读取、修改或污染现有客户端目录、生产资源目录或 `/home/wanye/D/BlueArchive` 这类本地资源目录。
4. 不要要求安装官方启动器作为生产运行前提。可以分析启动器资源或官方公开数据，但生产链路必须能在 Linux 环境中独立运行。
5. 涉及官方资源时，优先使用官方 `.hash`、catalog、manifest 和可复现 fixture 做校验依据。

## 架构原则

1. 仓库采用 monorepo；模块必须边界清晰、高内聚、低耦合。
2. 公共接口应稳定、可测试、可维护，并为未来扩展保留合理空间。
3. Rust 侧优先承担二进制解析、AssetBundle、Patch、CAS 和官方资源后端能力；Go 侧优先承担 CLI、运维入口和面向用户的命令编排。边界调整必须先说明理由。
4. Rust/Go 默认集成路径优先进程边界（当前为 `bat --json`）或未来稳定 SDK；`bat-ffi` 仅作为可选无状态 C ABI 兼容层，不能扩展成 daemon、下载器、CAS handle 或主控制面。
5. SDK 不得与 CLI 耦合；解析器不得与业务流程耦合；Provider、存储后端、Patch 算法和解析器应保留插件化扩展点。
6. 不引入 God Object、God Class、超长函数、超长文件、硬编码、魔法数字、重复代码、临时实现或只为当前测试通过的伪实现。
7. 不使用 `TODO`、`FIXME` 掩盖未完成设计。确实无法完成时，应在当前缺口文档中说明边界、风险和后续工作。

## 开发流程

1. 动手前先读相关文档和代码，确认当前真实状态。
2. 对跨模块、架构、数据格式或用户工作流有影响的改动，先给出设计判断或简短计划。
3. 实现后必须同步验证。验证范围要覆盖改动实际影响面，而不是只跑最窄的命令。
4. 涉及用户可见行为、运行方式、架构边界或缺口状态时，必须同步更新文档。
5. 保持改动范围和任务目标一致；不要顺手做无关重构或格式化 churn。
6. 如果需求、技术路线或设计存在明显风险，应直接指出并给出可执行替代方案。
7. 不确定的事实必须查证或询问；不要凭空调用不存在的接口、命令、路径或线上资源。

## 质量要求

1. 所有错误必须显式处理，并给出可诊断信息。
2. 日志应结构化或至少足够定位阶段、路径、版本、URL、重试、校验和失败原因。
3. 下载、写文件、状态切换和发布操作必须考虑原子性、断点续传、并发锁、失败恢复和清理策略。
4. 本地状态文件和索引必须有版本字段或兼容策略。
5. 新增 fixture、golden 或回归样本时，应说明它覆盖的真实风险。
6. 默认验证命令见 `docs/guides/development.md`；稳定工程基线见 `docs/guides/baseline.md`。

## 文档职责

长期规则的权威位置如下：

1. `AGENTS.md`：agent 行为、工程边界、架构原则和质量要求。
2. `CONTRIBUTING.md`：贡献者工作流、提交规范、验证和 PR 要求。
3. `docs/guides/development.md`：环境准备、开发命令、测试、调试和真实资源验证方式。
4. `PROJECT_PLAN.md`：产品目标、阶段路线图和长期能力规划。
5. `CURRENT_STATUS.md`：当前实现状态。
6. `docs/reports/CURRENT_GAPS.md`：当前缺口、优先级和关闭顺序。

`CLAUDE.md` 只保留兼容入口，不应继续新增长期规则。