docs(repo):完善协作规则与任务账本

AGENTS.md

@@ -2,7 +2,7 @@
 
 本文件用于约束在 BlueArchiveToolkit 中工作的 AI Agent。
 
-具体开发进度看 `CURRENT_STATUS.md`，开发计划看 `PROJECT_PLAN.md`，当前缺口看 `docs/reports/CURRENT_GAPS.md`。这里不记录具体任务和阶段待办。
+具体开发进度看 `CURRENT_STATUS.md`，开发计划看 `PROJECT_PLAN.md`，当前能力缺口看 `docs/reports/CURRENT_GAPS.md`，具体工程任务、优先级和依赖看根目录 `TODO.md`。这里不记录具体任务和阶段待办。
 
 ## 基本要求
 
@@ -14,6 +14,18 @@ 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 的确定性失败。
+
 ## 以什么为准
 
 仓库里有不少历史文档，不能混着看。
@@ -71,6 +83,96 @@ Go `bat-api` 是资源 bootstrap、只读分发和管理入口。它通过 `bat.
 
 不要静默改变已有字段的含义。确实需要破坏性修改时，先考虑版本号、迁移或兼容读取。
 
+## 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 自身设计偏好。
+
 ## 代码修改
 
 先弄清楚代码为什么放在当前位置，再决定是继续修改还是拆模块。
@@ -86,9 +188,19 @@ Go `bat-api` 是资源 bootstrap、只读分发和管理入口。它通过 `bat.
 * 无说明的硬编码；
 * 魔法数字；
 * 假实现、空实现冒充完成功能；
-* 用 `TODO` / `FIXME` 代替正式的缺口记录。
+* 用代码内 `TODO` / `FIXME` 代替根目录 `TODO.md`、`CURRENT_GAPS.md` 或其他正式缺口记录。
 
-如果当前任务确实无法完成某一部分，应明确限制实现范围，并把剩余问题记录到对应的状态、缺口或 Issue 中。
+如果当前任务确实无法完成某一部分，应明确限制实现范围；具体后续工程任务记录到根目录 `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` 用于可执行任务追踪。不要把这些职责混在一起。
 
 ## 文件、网络和发布安全
 
@@ -145,7 +257,9 @@ make check-docs
 
 不要把具体任务、临时优先级或某次实现方案写进本文件。
 
-新的长期架构决策应该进入 ADR 或对应架构文档；开发路线进入 `PROJECT_PLAN.md`；实际进度进入 `CURRENT_STATUS.md`；未完成内容进入 `CURRENT_GAPS.md` 或 Issue。
+新的长期架构决策应该进入 ADR 或对应架构文档；开发路线进入 `PROJECT_PLAN.md`；实际进度进入 `CURRENT_STATUS.md`；能力缺口进入 `docs/reports/CURRENT_GAPS.md`；具体工程任务、依赖和完成条件进入根目录 `TODO.md`；需要外部协作时再使用 Issue。
+
+Dashboard 的视觉方向与设计灵感进入根目录 `DESIGN.md`；Dashboard 的产品职责、状态所有权和接口事实仍以本文件与稳定产品/接口契约为准。
 
 ## 工作方式