BlueArchiveToolkit/AGENTS.md

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 只保留兼容入口，不应继续新增长期规则。