docs: 校正文档分类与当前边界

AGENTS.md

@@ -1,79 +1,160 @@
-# Agent 开发规则
+# AGENTS.md
 
-本文件是 BlueArchive Toolkit 中 AI agent、自动化开发助手和长期维护脚本的权威入口。它替代旧 `CLAUDE.md` 中真正长期有效的工程规则。
+本文件用于约束在 BlueArchiveToolkit 中工作的 AI Agent。
 
-## 语言和表达
+具体开发进度看 `CURRENT_STATUS.md`，开发计划看 `PROJECT_PLAN.md`，当前缺口看 `docs/reports/CURRENT_GAPS.md`。这里不记录具体任务和阶段待办。
 
-1. 默认使用简体中文交流、写文档、写提交说明、写开发日志和写 API 说明。
-2. 代码中的包名、类型名、函数名、变量名、数据库字段、协议字段和命令参数保持英文命名规范。
-3. 代码注释只在能降低理解成本时添加；不要写复述代码行为的空泛注释。
-4. 如果任务、上游规范或第三方 API 明确要求英文，可以在对应位置使用英文。
+## 基本要求
 
-## 项目定位
+默认使用简体中文交流、写文档和提交说明。代码标识符、协议字段、数据库字段、命令参数等保持英文。
 
-BlueArchive Toolkit 是长期维护的开源工具链，不是 demo、一次性脚本或临时试验项目。
+BlueArchiveToolkit 是长期维护项目。不要为了尽快完成当前任务引入明显的临时实现，也不要把未来计划描述成已经存在的能力。
 
-长期目标包括但不限于：
+修改代码前先读相关实现。涉及跨模块改动时，至少确认当前状态、相关架构文档、测试和已有接口，不要只看一个文件就重新设计整个模块。
 
-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` 掩盖未完成设计。确实无法完成时，应在当前缺口文档中说明边界、风险和后续工作。
+* 当前源码和测试；
+* `CURRENT_STATUS.md`；
+* 对应模块的专项状态文档，例如 `docs/reports/GO_STATUS.md`；
+* 已冻结的 RPC、release、schema 等契约。
 
-## 当前冻结
+`PROJECT_PLAN.md` 和 `CURRENT_GAPS.md` 描述的是计划和缺口，不代表功能已经实现。
 
-1. UnityFS / AssetBundle / Addressables / TypeTree 解析模块当前处于维护冻结，细则见 `docs/reports/PARSER_FREEZE.md`。
-2. 冻结期不继续新增解析类型、字段族、catalog 结构覆盖、写入型解析 RPC/CLI 或合成 fixture 驱动的能力扩展。
-3. 冻结期允许且优先处理编译、测试、clippy、真实运行回归、错误诊断、状态一致性、缓存复用和文档一致性问题。
-4. 如果用户明确要求继续解析扩展，必须先指出冻结状态、说明风险，并获得明确解冻或例外授权。
+`docs/archive/` 和 `docs/reports/historical/` 只用于追溯历史，不应作为当前实现依据。
 
-## 开发流程
+如果文档之间冲突，先核对源码和测试，再判断哪份文档已经过时。修代码时顺手修正相关权威文档，不要让冲突继续留在仓库里。
 
-1. 动手前先读相关文档和代码，确认当前真实状态。
-2. 对跨模块、架构、数据格式或用户工作流有影响的改动，先给出设计判断或简短计划。
-3. 实现后必须同步验证。验证范围要覆盖改动实际影响面，而不是只跑最窄的命令。
-4. 涉及用户可见行为、运行方式、架构边界或缺口状态时，必须同步更新文档。
-5. 保持改动范围和任务目标一致；不要顺手做无关重构或格式化 churn。
-6. 如果需求、技术路线或设计存在明显风险，应直接指出并给出可执行替代方案。
-7. 不确定的事实必须查证或询问；不要凭空调用不存在的接口、命令、路径或线上资源。
+ADR 记录架构决策，但旧 ADR 中已经被后续实现明确替代的部分不能机械照搬。
 
-## 质量要求
+## 现有边界
 
-1. 所有错误必须显式处理，并给出可诊断信息。
-2. 日志应结构化或至少足够定位阶段、路径、版本、URL、重试、校验和失败原因。
-3. 下载、写文件、状态切换和发布操作必须考虑原子性、断点续传、并发锁、失败恢复和清理策略。
-4. 本地状态文件和索引必须有版本字段或兼容策略。
-5. 新增 fixture、golden 或回归样本时，应说明它覆盖的真实风险。
-6. 默认验证命令见 `docs/guides/development.md`；稳定工程基线见 `docs/guides/baseline.md`。
+当前正式的资源同步和运维入口是 Rust `bat`。
 
-## 文档职责
+官方资源发现、下载、校验、版本状态、staging、release 发布、watch/daemon、任务和相关长期状态都由 Rust 侧负责。不要在 Go、Web 或其他模块再实现一套相同状态机。
 
-长期规则的权威位置如下：
+Go `bat-api` 是资源 bootstrap、只读分发和管理入口。它通过 `bat.sock` RPC 消费 Rust 状态，并读取 Rust 已经发布的资源。不要让它直接管理官方同步状态，也不要在 Go 里重新实现 CAS、AssetBundle 解析或 Patch 核心算法。
 
-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`：当前缺口、优先级和关闭顺序。
+`bat-ffi` 只是兼容接口，不是主集成方式。不要把 daemon、下载器、CAS 长生命周期状态或新的主控制面塞进 FFI。
 
-`CLAUDE.md` 只保留兼容入口，不应继续新增长期规则。
+官方原版 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. 代码、测试和权威文档是否仍然一致。