BlueArchiveToolkit/TODO.md

BlueArchiveToolkit TODO Roadmap

基线：experiment

当前已知基线提交：37d49c9793d25288fd2fcc60b95c1ba55bdf7623

工程原则：不以“最小修复”为目标。所有修复与新功能优先考虑长期可维护性、可用性、安全性、明确契约、回归测试和后续扩展成本；避免无关重构，但一旦处理一个问题，应完整收口其工程边界。

---

文件定位与权威边界

TODO.md 是仓库内的具体工程任务账本，用于记录可执行任务、优先级、依赖关系、验收条件和当前任务状态。它不定义当前实现事实，也不取代状态、架构或稳定契约文档。

判断当前实现时遵循 AGENTS.md 的权威规则：

1. 当前源码和 tests；
2. CURRENT_STATUS.md；
3. 对应模块的专项 current-status 文档；
4. 已冻结的 RPC、release、schema 等稳定 contract。

docs/reports/CURRENT_GAPS.md 描述当前能力缺口，PROJECT_PLAN.md 描述长期路线，TODO.md 负责把需要执行的工作组织成具体任务。若 TODO 条目与当前源码、tests 或权威状态文档冲突，应先核对事实并更新过时条目，不得按照旧 TODO 重新实现已经完成的能力。

任务维护规则

• 开始任务前检查其依赖是否满足，并重新核对相关源码、tests 与 contract；TODO 中的实现建议不能替代对当前代码的确认。
• 不做只针对当前 testcase 的最小补丁。同一 root cause / contract 内已经确认的问题应在当前工程边界内一起收口。
• 明显独立的问题新增或更新 TODO，不因“顺手”无限扩大当前任务。
• 每项任务应尽量保持问题、风险、目标状态、依赖、验收条件和必要非目标完整；需要长期架构决策时写入 ADR 或架构文档，而不是仅留在 TODO。
• 完成任务后及时同步状态、依赖和验收结果；已经完成的能力不得继续保留为 Active/Ready 待办。
• 如果任务执行过程中发现原假设不成立，应根据当前事实修订 TODO，而不是机械执行过时方案。
• TODO.md 不记录凭据、Token、密码、个人环境秘密或其他敏感信息。

---

状态约定

• P1：优先处理，会影响当前生产语义或核心正确性。
• P2：重要工程债务，应在相关功能继续扩展前完成。
• Feature：正式功能开发。
• Continuous：持续验证或长期运行任务。
• Hard Blocker：前置任务完成前，不应开始后续任务。
• Recommended Before：技术上可并行，但建议先完成。
• Ready：依赖已满足，可以开始。
• In Progress：当前正在实施。
• Blocked：存在未满足的 Hard Blocker 或明确外部阻塞。
• Planned / Later：已记录但尚未进入近期执行队列。
• Done：目标 contract、验收与必要文档同步均已完成；不能仅因代码已写入就标记完成。

---

T01 — bat-api 发布完整性与分发健康契约

类型： P1 状态： Done 优先级： 最高

问题

当前 Go bat-api 的 release readiness 和 CDN 分发主要依赖：

• manifest entry 是否存在；
• 文件 size 是否匹配。

虽然 Rust 已有完整的发布状态、BLAKE3 校验与 release integrity 语义，但 Go 当前需要继承 一个轻量、带代际绑定和 freshness 的 current official health proof，而不是触发重型历史扫描。

因此可能出现：

• release 中 B 文件缺失，但 A 文件仍可通过 CDN 返回；
• 文件内容发生同大小损坏，但 Go index 仍认为其 size 正常；
• manifest 中的 BLAKE3 仍可能被用于生成强 ETag，而实际文件内容已发生变化；
• /readyz 与实际 CDN 分发行为出现不一致。

目标状态

建立统一的：

Rust current release attestation
        ↓
Go ReleaseIndex（保留 release/publication/manifest identity）
        ↓
readiness / bootstrap
        ↓
CDN distribution gate

生产 RPC 模式下，Go 不自行重新实现完整 release verifier，而是消费 Rust 已确认的发布健康事实。

完整 release 不健康时：

• /readyz 不应报告 ready；
• bootstrap 不应报告 distributable；
• CDN 不应继续从该 release 分发任意文件。

release.attestation 必须由 Rust 维护 canonical resource root、publication anchor、 mapping/manifest identity、verification generation、verified_at、integrity/status code 和 diagnostics；轻量读取 只检查 current、anchor、manifest 元数据和 freshness，不遍历历史 release，不计算资源 文件 BLAKE3。resource.manifest 请求必须绑定 attested release_id、 publication_identity、manifest_identity、expected_verification_generation，每页返回相同 代际信息；Go 逐页验证 release/root/identity/version/total/offset/limit，任何混页都丢弃候选快照。

保持现有：

• GET
• HEAD
• Range
• Content-Length
• ETag
• immutable cache
• single-entry release distribution

等协议行为。

验收

至少覆盖：

B 缺失，GET A
→ release 不应继续正常分发

B size mismatch，GET A
→ release 不应继续正常分发

B 同大小内容损坏，Rust health=false
→ Go refresh 后 ready=false
→ A/B 均不再作为健康 release 分发

完整健康 release
→ GET / HEAD / Range / ETag 行为保持

非目标

• 不复制 Rust release verifier 到 Go。
• 不在每个 CDN GET 时全量重新计算所有文件 hash。
• 不重新设计 Release/CAS 生命周期。

依赖

无。

关系

后续关系：

• T11 正式长期运行验证使用本任务建立的 health/readiness evidence。
• Production-ready 判定仍需结合长期运行证据，不由本任务单独宣告。

完成记录

已收口 Rust current official attestation 到 canonical versions/<id> root：publication 在 staging 写入但 JSON root 绑定最终 versions path，rename 不增加 verification generation；full audit、显式 verify/repair、watch current audit 的 verified/invalid 均写入 新 generation。resource.manifest 请求和响应按 release/publication/mapping/manifest/ generation 严格绑定，Go 分页逐页及最终 entry count 校验；freshness 按 2 * verification_interval + error_retry 计算，默认 7260 秒，max_age_seconds=0 fail closed。readyz、bootstrap 和普通 current CDN 共用 Rust attestation、完整分页及 安全本地快照 gate；失败 verification 会立即失效旧 ready generation。已增加 staging transition、generation race、过期和失败失效回归，并验证现有 CDN/历史分发路径未改语义。

---

T02 — ResourceRepository 查询契约统一

类型： P2 状态： Ready

问题

当前 ResourceRepository 的 glob contract 与实际实现存在差异。

预期：

*   不跨 /
**  可以跨 /
?   匹配一个字符

当前 Rust matcher、SQLite LIKE 转换以及 list() / count() 的实际过滤语义并不完全一致。

可能产生：

list(query).len() != count(query)

以及 /、Unicode、大小写等边界行为不一致。

目标状态

建立单一、稳定、经过测试的 ResourceQuery pattern contract。

要求：

• Rust 与 SQLite 查询语义一致；
• list() 与 count() 使用同一过滤逻辑；
• * / ** / ? 行为明确；
• Unicode 行为明确；
• path separator 行为明确；
• 不依赖模糊的 SQL LIKE 近似语义。

验收

建立针对：

• *
• **
• ?
• /
• Unicode
• 空结果
• count/list equality

的系统回归测试。

依赖

无。

关系

Hard Blocker：

T02 → T13

---

T03 — SQLite Schema Migration 体系化

类型： P2 状态： Ready

问题

当前 Translation Memory、Glossary、Translation Tasks 等 SQLite 数据库的初始化流程存在：

CREATE / ALTER / ensure_column
↓
读取 schema_migrations
↓
检查 future schema

的问题。

旧版本程序可能先修改未来版本数据库，再判断“不支持该 schema”。

此外部分 schema 已发生实际变化，但版本号仍未同步提升。

目标状态

建立统一 SQLite schema migration contract：

读取 schema/version
↓
future schema → 零修改失败
↓
开始 transaction
↓
按版本执行明确 migration
↓
更新 schema version
↓
commit

所有长期 SQLite 状态统一遵循该规则。

至少覆盖：

• Translation Tasks
• Translation Memory
• Glossary

要求

• future schema fail without mutation；
• migration transaction；
• migration idempotency；
• crash/retry 行为明确；
• schema version 与实际结构一致；
• 不再依赖散落的 ensure_column 隐式升级。

依赖

无。

关系

Hard Blocker：

T03 → T04
T03 → T14

Recommended Before：

T03 → T15
T03 → T16

---

T04 — Translation Memory Trusted 唯一性与 Supersede 治理

类型： P2 状态： Blocked by T03

问题

当前 TM 可以对相同：

raw source
+ exact context

产生多个不同译文的 Trusted entry。

worker 会通过排序选择其中一个，行为虽然确定，但没有明确的人工治理语义。

目标状态

对于相同 source + exact context：

同一时间只能存在一个 current Trusted translation。

确认一个与现有 Trusted 内容不同的新译文时：

• 必须显式 supersede；
• 记录 reviewer；
• 记录 reason；
• 更新 provenance；
• 保留历史记录；
• 历史 Trusted 变为 Superseded；
• worker 只自动复用 current Trusted。

利用现有：

supersedes_record_id
superseded_by_record_id

建立正式治理模型。

非目标

• 不实现 fuzzy TM。
• 不实现 embedding/vector。
• 不引入 AI 自动信任。

依赖

Hard Blocker：T03

关系

T03 → T04 → T14

---

T05 — bat.sock 本地 IPC 安全与资源边界

类型： P2 状态： Ready

目标

强化 Unix socket RPC 边界，包括：

• socket 显式权限；
• state directory 权限契约；
• peer identity / same-user policy；
• RPC request size limit；
• RPC response size limit；
• oversized line/request 拒绝；
• malformed JSON diagnostics；
• connection lifetime 行为；
• 对应测试。

设计原则

bat.sock 是同机 IPC，不应为此重新设计网络鉴权体系。

优先考虑：

filesystem permission
+ peer credentials
+ bounded protocol

而不是额外 token。

依赖

无。

关系

Recommended Before：

T05 → Production-ready

---

T06 — AssetBundle / ZIP Parser Resource Budget

类型： P2 状态： Ready

问题

UnityFS 与 ZIP 解析当前主要依赖文件内部声明的大小。

在复杂真实样本继续扩展前，需要先建立资源消耗边界。

目标

建立统一 parser budget，包括但不限于：

• 最大输入文件大小；
• 最大解压后大小；
• 最大 UnityFS block 数；
• 最大 directory 数；
• 最大 serialized object 数；
• 最大 TypeTree 深度；
• 最大 array/map 元素数；
• 最大 string/blob 长度；
• 最大 ZIP entry 数；
• 单 ZIP entry 最大输出；
• 总解析内存预算。

超限时返回结构化错误，而不是 OOM 或异常长时间运行。

依赖

无。

关系

Hard Blocker：

T06 → T09

Recommended Before：

T06 → T12

---

T07 — Durable Atomic State Write

类型： P2 状态： Ready

问题

当前 atomic writer 主要保证：

temp write
→ flush
→ rename

能较好处理进程中断，但不能完整保证掉电后的 durable persistence。

目标

为关键状态提供 durable atomic writer：

write temp
→ flush
→ sync_all(temp)
→ rename
→ sync parent directory

只用于需要强 durability 的状态。

重点包括：

• version-state；
• publication anchor；
• release transaction journal；
• CAS ownership scope；
• cleanup ownership/progress；
• 其他关键状态机文件。

普通日志、cache 等不要求同步升级为强 fsync。

依赖

无。

关系

Recommended Before：

T07 → Production-ready

---

T08 — CI Gate 与质量门禁整理

类型： Engineering Baseline 状态： Done

问题

原 make ci 曾存在：

• format target 会直接修改文件；
• 部分 lint tool 缺失时可能 skip；
• 最终 PASS 文案可能不能完整代表所有建议门禁实际执行。

目标

区分：

make format

和：

make ci-check

CI 检查必须：

• read-only；
• 不修改源码；
• 明确报告每项 gate；
• required tool 缺失时不应伪装成全部通过；
• required tool 缺失或版本不匹配必须失败；
• 与实际 Gitea CI 尽量保持一致。

完成记录

make format / make fmt 保留为显式写入命令，make ci-check 和兼容的 make ci 只执行 read-only required gates；共享 scripts/check-go-format.sh 由 make check-go-format、本地 scripts/ci-check.sh 和 Gitea workflow 共用。golangci-lint 2.12.2 由 scripts/ci-versions.sh 固定，缺失或版本不匹配失败；OpenAPI、RPC contract 和文档一致性由 make check-docs 纳入。Gitea self-hosted runner 执行相同的 required Rust/Go/docs 语义，不添加 GitHub Actions。最终 workspace gates、make test-go-api、 make check-docs 和 make ci-check 均已通过。

建议统一覆盖：

cargo fmt --all -- --check
cargo check --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

go test
go vet
Go lint

OpenAPI / RPC contract checks
make check-docs

依赖

无。

关系

Recommended Before：

T08 → T09
T08 → T10
T08 → T12
T08 → T13
T08 → T14
T08 → T15
T08 → T16

T08 不应成为所有开发工作的绝对阻塞点，但应尽早完成。

---

T09 — G-005 真实 AssetBundle 样本驱动兼容扩展

类型： Feature 状态： Blocked by T06

目标

以真实 Blue Archive 官方 AssetBundle 样本驱动扩展兼容性。

开发方式：

发现真实未支持结构
↓
保存最小可复现 fixture
↓
解析
↓
建立 semantic invariant
↓
修改
↓
rebuild
↓
reparse
↓
验证 byte / semantic invariant

重点覆盖：

• 更多真实 Unity 2021.3 变体；
• serialized file 结构差异；
• TypeTree 变体；
• managed reference；
• container/map/list/array；
• alignment；
• multiple serialized files；
• block layout；
• compression variants。

原则

不追求“一次实现万能 Unity parser”。

只扩展真实样本证明确有需求的结构，但每个新增结构必须完整支持：

parse
→ inspect
→ modify
→ rebuild
→ verify

依赖

Hard Blocker：T06

Recommended Before：T08

关系

T06 → T09 → T10

---

T10 — G-006 复杂 AssetBundle Patch / Rebuild

类型： Feature 状态： Blocked by T09

目标

将 T09 已确认可稳定解析和重建的结构纳入 Generic Patch / localized publication。

重点：

• 复杂 TypeTree field patch；
• nested structures；
• managed reference structures；
• map/list/array；
• 多 object 修改；
• 多 serialized file bundle；
• ZIP-inner UnityFS；
• provenance；
• rollback；
• replay verification。

原则

只有 AssetBundle engine 已经验证支持的结构才能进入正式 Patch contract。

Patch 层不能自行“猜”未知 Unity 结构。

依赖

Hard Blocker：T09

---

T11 — Official Smoke / 长期运行证据

类型： Continuous 状态： 可立即开始，T01 后数据作为正式证据

目标

长期保存真实官方资源运行证据。

不是一次 smoke 即完成，而是跨多个官方更新周期持续执行。

建议记录：

• 时间；
• Git SHA；
• app version；
• bundle version；
• connection group；
• official release ID；
• publication identity；
• manifest entry 数；
• downloaded / resumed / release-reused / CAS-reused 数量；
• transfer bytes；
• verify result；
• repair result；
• daemon/watch 行为；
• elapsed time；
• failure / retry 情况。

建议覆盖：

fresh full pull
→ up-to-date poll
→ daemon/watch
→ official version update
→ historical reuse
→ CAS reuse
→ local corruption
→ verify
→ repair
→ publication
→ bat-api distribution

依赖

可立即开始。

但：

T01 完成后的记录才作为新的正式 distribution-integrity production evidence。

关系

T01 ─────→ T11 正式 evidence
T09/T10 ─→ T11 增加 AssetBundle/Patch 真实验证

---

T12 — G-007 独立二进制 Addressables Catalog

类型： Feature 状态： Planned

目标

扩展当前 JSON/compact Addressables 支持，处理真实官方独立 binary catalog。

要求继续保持：

• official resource discovery contract；
• deterministic parsing；
• fixture tests；
• malformed input handling；
• resource budget；
• 不影响当前已支持 JSON/compact 路径。

依赖

Recommended Before：

• T06
• T08

可与 T09 后半段并行。

---

T13 — G-011 ResourceRepository 查询扩展

类型： Feature 状态： Blocked by T02

目标

在稳定查询 contract 上扩展：

• richer filters；
• pagination；
• sorting；
• inspection；
• corruption reporting；
• recovery support；
• 上层 RPC/API 查询。

依赖

Hard Blocker：T02

---

T14 — G-012 Translation Memory 后续扩展

类型： Feature 状态： Blocked

前置

T03 schema migration
↓
T04 Trusted governance
↓
T14

可能范围

之后再考虑：

• fuzzy matching；
• normalized similarity；
• import/export；
• statistics；
• richer query；
• review workflow。

Embedding/vector 不应默认进入第一阶段。

---

T15 — G-013 Glossary 协作、导入与搜索

类型： Feature 状态： Planned

目标

在现有 Glossary V1 基础上逐步增加：

• bulk import/export；
• richer search；
• conflict review；
• provenance inspection；
• history；
• collaboration-ready APIs。

仍保持：

• Rust owns glossary semantics；
• Go 只做代理；
• Glossary QA 不直接修改翻译文本；
• approved terms 才自动参与；
• ambiguity 输出 diagnostic。

依赖

Recommended Before：T03

---

T16 — G-014 Translation Provider 扩展体系

类型： Feature 状态： Planned

当前基础

现有真实 provider：

• Mock
• Crowdin

已经存在 Rust TranslationProvider trait。

目标

只有出现第二、第三种真实 provider 需求时，再抽象真正稳定的 provider extension contract。

应处理：

• capability declaration；
• structured glossary constraints；
• retry/error classification；
• rate-limit；
• batching；
• provenance；
• provider-neutral result；
• cancellation；
• observability。

非目标

不要为了“插件架构完整”提前制作万能 provider framework。

依赖

Recommended Before：T03

---

T17 — Dashboard 产品化与完整 Web 协作后台

类型： Feature / Late Stage 状态： Later

产品边界

BlueArchiveToolkit 的 Web 产品明确区分用户 Dashboard 与运营 Dashboard，两者共享基础视觉语言、Design Token、组件风格和状态语言，但不得混淆信息架构、权限和使用场景。涉及具体视觉、布局、组件或交互设计时遵循 AGENTS.md 并先阅读根目录 DESIGN.md。

用户 Dashboard 面向普通用户，当前核心控制能力仅包括文字汉化与图像汉化的启用/停用，以及与这些操作直接相关的状态、版本、更新反馈和必要异常提示。不得把运营端内部实现直接暴露给用户，也不得通过裁剪运营菜单来生成用户 Dashboard。

运营 Dashboard 面向项目运营和维护者，继续承担高信息密度的资源、release、Translation/TM、Provider/worker、task/job、daemon/runtime、CAS、诊断、日志、配置和必要运营操作。其页面应优先回答“系统是否正常、哪里需要处理、最近发生了什么”。

所有 Dashboard 必须以真实 API/RPC contract 和真实状态为依据，不得为了视觉完整性伪造后端不存在的数据或在前端维护第二份业务状态。

前置能力

完整协作能力建议至少等：

T13 Resource query
T14 TM
T15 Glossary
T16 Provider

达到相对稳定状态。用户 Dashboard 的基础产品壳和共享设计系统可以按真实用户 contract 独立推进，但不得绕过后端能力或提前虚构状态。

可能范围

• 用户 Dashboard 的文字/图像汉化控制与必要状态反馈；
• 运营 Dashboard 的运行观察与运营操作；
• 共享 Design Token 与基础组件体系；
• user / role；
• translation review；
• glossary workflow；
• task assignment；
• conflict handling；
• TM review；
• release observation；
• audit trail；
• collaboration。

当前 embedded dashboard 可继续作为运营入口并逐步演进。

不要为了 Web 提前迁移 Rust-owned 状态到 Go/PostgreSQL，也不要让前端复制后端状态机。

---

T18 — 完整游戏业务 API

类型： Feature / Late Stage 状态： Later

当前 bat-api 明确是：

resource bootstrap
+ distribution
+ management forwarding

不是完整 Blue Archive game backend emulator。

如未来确实需要完整游戏业务 API，应单独立项。

前置

核心资源与 release 生命周期长期稳定后再开始。

---

依赖关系总图

                                ┌─────────────────────────────┐
                                │ T08 CI / Quality Baseline   │
                                └──────────────┬──────────────┘
                                               │ Recommended
                  ┌────────────────────────────┼────────────────────────────┐
                  │                            │                            │
                  ▼                            ▼                            ▼

T02 ResourceRepository ──Hard──→ T13 G-011

T03 SQLite Migration ──Hard──→ T04 TM Trust ──Hard──→ T14 G-012
          │
          ├────Recommended────→ T15 G-013
          └────Recommended────→ T16 G-014


T06 Parser Budget ──Hard──→ T09 G-005 ──Hard──→ T10 G-006
        │
        └────Recommended──────→ T12 G-007


T01 bat-api Distribution Integrity ───────────→ T11 Official Long-running Evidence

T05 bat.sock Hardening ─────┐
                            ├──────────────→ Production-ready
T07 Durable State Write ────┘


T13 ─────┐
T14 ─────┤
T15 ─────┼──────────────→ T17 Full Web Collaboration
T16 ─────┘


Stable Resource / Release / AssetBundle Platform
                     │
                     └────────────────────→ T18 Full Game Business API

---

推荐执行队列

In Progress

建议当前只放：

T01 — bat-api 发布完整性与分发健康契约
T08 — CI Gate 与质量门禁整理

T01 是当前唯一 P1。

T08 可以与其并行，不涉及核心业务状态机。

---

Ready

T02 — ResourceRepository 查询契约统一
T03 — SQLite Schema Migration 体系化
T05 — bat.sock 本地 IPC 安全与资源边界
T06 — AssetBundle / ZIP Parser Resource Budget
T07 — Durable Atomic State Write
T11 — Official Smoke / 长期运行证据

T11 可以现在就开始采集，但 T01 后的数据才作为新的正式 distribution integrity evidence。

---

Blocked / Planned

T04 ← T03

T09 ← T06
T10 ← T09

T12 ← 推荐 T06/T08

T13 ← T02

T14 ← T03 + T04
T15 ← 推荐 T03
T16 ← 推荐 T03

T17 ← T13/T14/T15/T16
T18 ← 核心平台长期稳定

---

当前明确封板的边界

以下内容不建立“继续优化”型 TODO。

Release / CAS V1

当前已完成：

• official/localized 独立 release 生命周期；
• staging / versions / current；
• verified publication phase；
• rollback；
• cleanup plan / plan_id；
• official/localized cleanup locks；
• CAS operation lock；
• refcount；
• durable release ledger；
• ownership ID；
• output-root scope；
• generation-aware ownership；
• legacy basename compatibility protection；
• independent official distribution publication identity；
• single-entry distribution hot path。

除非：

• 真实运行发现问题；
• 新功能暴露新边界；
• 新审计找到具体 defect；

否则不要继续进行纯粹的 Release/CAS “架构优化”。

---

长期工程原则

处理上述任何 TODO 时统一遵守：

1. 不做只针对当前 testcase 的最小补丁。
2. 先定义稳定 contract，再实现。
3. 修复一个边界时同时考虑正常路径、异常路径、并发、重试、恢复和兼容。
4. 所有状态修改考虑 crash consistency。
5. 所有外部输入考虑 resource limit。
6. Rust/Go 状态所有权不得模糊。
7. 不为了架构美观进行无业务收益的大重构。
8. 不提前抽象没有真实使用者的通用平台。
9. 修复必须有 regression tests。
10. 文档只描述真实实现，计划与现实必须明确区分。
11. CI 未实际运行的 gate 不得宣称通过。
12. Production-ready 必须依赖真实长期运行证据，而不是只依赖 unit tests。