feat(glossary): 实现 Rust Glossary V1

2026-09-18 06:34:54 +08:00 · 2026-09-07 22:38:53 +08:00
parent 8fc93b8f39
commit 94483ff14d
42 changed files with 4543 additions and 92 deletions
@@ -196,13 +196,14 @@ pub struct ParserRegistry {
 ### 4. 翻译系统（目标扩展，Go；当前 worker 由 Rust `bat` 承担）

 当前已实现的是 Rust `bat` 的离线 TextUnit 队列、mock/Crowdin provider worker、
-lease/retry、结果落库和项目级 Translation Memory V1。TM 位于独立 SQLite，按 raw
-source + 完整 context 做 trusted exact reuse，candidate 必须显式 confirm；Glossary、
-模糊匹配和完整 Provider 体系仍属后续缺口。
+lease/retry、结果落库、项目级 Translation Memory V1 和独立 Glossary V1。TM 位于独立
+SQLite，按 raw source + 完整 context 做 trusted exact reuse，candidate 必须显式 confirm；
+Glossary 只有 approved term 进入 provider/TM 自动流程，并在结果上执行确定性 QA；模糊
+匹配和完整 Provider 体系仍属后续缺口。

 **架构**：
 ```
-Text Extractor → TM exact query → AI Provider → Glossary (后续) → Output
+Text Extractor → Glossary constraints + TM exact query → AI Provider → Glossary QA → Output
                       ↓                          ↓
                   PostgreSQL                  审核队列
 ```
@@ -295,7 +296,7 @@ HTTP Request → Middleware (Auth, CORS, Logger) → Handler → Service → Rep

 ### 7. Web 后台 (Vue 3，目标设计)

-当前只有 `bat-api` 内嵌 dashboard MVP；登录、角色、术语管理和完整协作审核仍未实现。
+当前只有 `bat-api` 内嵌 dashboard MVP；Rust `bat` 的 Glossary V1 已实现，登录、角色、Web 术语管理和完整协作审核仍未实现。

 **技术栈**：
 - Vue 3 + Composition API
@@ -308,7 +309,7 @@ HTTP Request → Middleware (Auth, CORS, Logger) → Handler → Service → Rep
 **模块**：
 - Dashboard（统计概览）
 - 翻译审核（Translation Review）
- 术语管理（Glossary Manager）
+- Web 术语管理（Glossary Manager）
 - 资源浏览（Asset Browser）
 - 用户管理（User Management）

@@ -36,7 +36,7 @@
   - 新的跨语言控制和查询能力优先增加 Rust RPC contract，再由
     `internal/backendrpc` 消费。

-4. **完整游戏业务 API、完整 Web 协作后台、Glossary 和 Provider 扩展体系仍是后续目标**；
+4. **完整游戏业务 API、完整 Web 协作后台和 Provider 扩展体系仍是后续目标；Rust `bat` 已持有 Glossary V1，Web 术语协作视图仍待建设**；
   Translation Memory V1 已由 Rust `bat` 持有，不能从目标架构图推断 Go 侧拥有第二份状态。

 ---
@@ -89,7 +89,7 @@ git check-ignore -v Cargo.lock CLAUDE.md AGENTS.md CONTRIBUTING.md
 当前开发优先推进：

 1. 继续 AssetBundle 复杂对象解析、真实 fixture 和发布级重打包。
-2. 基于 `translation.worker.run` 扩展 TM/Glossary 和通用 manifest Patch 构建。
+2. 基于 `translation.worker.run` 继续扩展 TM/Glossary，并推进通用 manifest Patch 构建。
 3. 扩展 ResourceRepository 查询面：更丰富的 TextUnit/TM 查询和通用 Patch 发布所需资源视图。
 4. 按 `docs/guides/official-full-pull-smoke.md` 在隔离目录执行真实官方网络全量下载 smoke，并保留运行报告。
 5. 在资源和翻译契约稳定后推进完整 Web 协作后台和完整游戏业务 API。
@@ -161,6 +161,22 @@ bat i18n worker run \
 `--watch`，因此可以单次、限定次数或周期执行；`--run-count > 1` 时仍必须
 显式指定 `--interval`。

+Glossary V1 是 Rust `bat` 持有的独立项目级 SQLite 资产，默认位于
+`<output>/glossary.sqlite`；也可以用 `--glossary-path`、
+`BAT_GLOSSARY_PATH` 或 `[translation.worker].glossary_path` 指定。worker 只把
+`approved` term 转成 provider-neutral constraints，并在 TM 复用、provider 返回
+和人工工作台/任务回写时执行相同的确定性 QA。冲突或不符合推荐/允许译法的结果会
+阻止自动完成；必须提交带 reviewer、reason 和 provenance 的显式 override。
+
+常用 Glossary 操作：
+
+```bash
+bat i18n glossary summary --output /tmp/bat-resources
+bat i18n glossary query --glossary-source-text 'Sensei' --glossary-review-status approved
+bat i18n glossary diagnose --glossary-source-text 'Sensei' \
+  --glossary-context-json '{"destination":"Table.bytes"}'
+```
+
 外部 provider 或人工流程也可以用 `i18n task update` 回写当前 release 的任务状态：

 ```bash
@@ -8,7 +8,7 @@ BlueArchive Toolkit 的部署文档分为当前可用模式和目标模式：
   本地资源状态使用文件和 SQLite。
 2. **官方资源同步生产任务**：当前可用，运行 Rust `bat --watch` 或 RPC/daemon 模式。
 3. **bat-api 资源 bootstrap / 分发服务**：当前可用，和 Rust `bat` 在同一服务器/容器环境运行，经 `bat.sock` RPC 获取当前 `resource_root`。
-4. **可选数据库开发环境**：PostgreSQL/Redis 只服务于未来的 Go 服务层、Glossary 和完整
+4. **可选数据库开发环境**：PostgreSQL/Redis 只服务于未来的 Go 服务层、完整 Web 协作后台和
   Provider 扩展，不是当前 `bat` / `bat-api` 的生产运行依赖；当前 Translation Memory V1
   使用 `<output>/translation-memory.sqlite`。
 5. **完整单机/分布式部署**：尚未提供。完整游戏业务 API、数据库迁移和 Web 未实现前，不把它作为可执行部署方案。
@@ -39,7 +39,7 @@ docker compose -f deployments/docker-compose.dev.yml --profile local-db up -d
 ## 模式 2：可选数据库开发环境（目标能力）

 PostgreSQL 和 Redis 不是当前 `bat` / `bat-api` 的生产运行依赖。本模式只用于未来
-服务层、Glossary 或 Provider 扩展的开发验证，不能作为当前
+服务层、Web 协作视图或 Provider 扩展的开发验证，不能作为当前
 资源同步或资源分发的部署前置条件。

 ### 远程开发连接
@@ -164,6 +164,11 @@ SQLite `ResourceRepository`，索引不存在时返回 `ok=true` 且
  provenance。默认路径为 `<output>/translation-memory.sqlite`，可由
  `BAT_TRANSLATION_MEMORY_PATH`、`[translation.worker].translation_memory_path` 或 CLI
  覆盖。
+- `glossary.sqlite`：跨 release 的项目级 Glossary，不位于 `versions/<id>`，也不与
+  `translation-tasks.sqlite` 或 TM 共用；记录 term、alias、推荐/允许译法、scope、
+  priority、review 状态、source provenance 和完整 source/review history。默认路径为
+  `<output>/glossary.sqlite`，可由 `BAT_GLOSSARY_PATH`、`[translation.worker].glossary_path`
+  或 CLI 覆盖。

 删除资源只进入 `official-resource-changes.json`，不进入 Crowdin handoff。

@@ -218,6 +223,13 @@ SQLite `ResourceRepository`，索引不存在时返回 `ok=true` 且
 | `translation.memory.summary` | 已实现 | 可选 `{ "translation_memory_path": "..." }` | 返回 TM schema 版本、总记录数及 candidate/trusted/rejected/superseded 状态计数。 |
 | `translation.memory.query` | 已实现 | `{ "source_text": "...", "source_context": {...}, "limit": 100 }` | 按 raw source 查询记录，返回 match kind、trust、translation 和 provenance。 |
 | `translation.memory.confirm` | 已实现 | `{ "record_id": "...", "reviewer": "...", "reason": "..." }` | 显式确认一条 candidate 为 trusted；worker 之后才可自动复用。 |
+| `translation.glossary.summary` | 已实现 | 可选 `{ "glossary_path": "..." }` | 返回 Glossary schema 版本和 draft/approved/deprecated/rejected 计数；缺库只返回 `available=false`，不会创建空库。 |
+| `translation.glossary.query` | 已实现 | `{ "source_text": "...", "category": "...", "review_status": "approved", "limit": 100 }` | 查询 term、alias、scope、source provenance 和完整 source/review history。 |
+| `translation.glossary.diagnose` | 已实现 | `{ "source_text": "...", "context": {...} }` | 只对 approved term 生成 provider-neutral constraints，并返回冲突/覆盖诊断和 blocked 决策。 |
+| `translation.glossary.add` | 已实现 | Glossary term draft，包含 `term_id`、`source_term`、`recommended_translation`、`source` 等 | Rust 创建 draft/import term 并记录 source history。 |
+| `translation.glossary.update` | 已实现 | term draft + `reviewer`，可选 `reason` | Rust 替换 term definition，并记录 source/review history。 |
+| `translation.glossary.approve` | 已实现 | `{ "term_id": "...", "reviewer": "...", "reason": "..." }` | 将 term 明确置为 approved；只有 approved term 进入 worker/TM 自动流程。 |
+| `translation.glossary.deprecate` | 已实现 | `{ "term_id": "...", "reviewer": "...", "reason": "..." }` | 保留历史但停止自动应用。 |

 TM 的自动复用规则是 raw source 完全相同、完整 context 完全相同且状态为 `trusted`；
 context 缺失/不一致、normalized source 仅辅助查询、candidate 或 provider 成功都不会
@@ -299,6 +311,7 @@ provider worker 参数：
 | `max_tasks` | uint/null | `null` | 本轮最多 claim 的任务数，设置时必须大于 0。 |
 | `worker_id` | string | `bat-rpc-worker` | lease 诊断用 worker ID 前缀。 |
 | `translation_memory_path` | string/null | 按配置推导 | 覆盖 Rust worker 使用的项目级 TM 数据库路径；未指定时使用 worker 配置或 `<output>/translation-memory.sqlite`。 |
+| `glossary_path` | string/null | 按配置推导 | 覆盖 Rust worker 使用的项目级 Glossary 数据库路径；未指定时使用 worker 配置或 `<output>/glossary.sqlite`。存在 Glossary 但无法打开时 worker fail-closed，不自动绕过 QA。 |

 数字字段必须是 JSON number；字符串数字、负数和越界值会返回
 `BAT-ERR-700002`。`mock` provider 在没有 fixture 时把 source text 写成可诊断的
@@ -306,6 +319,12 @@ mock 译文；`crowdin` provider 从 `CROWDIN_PROJECT_ID`、`CROWDIN_LANGUAGE_ID
 `CROWDIN_API_TOKEN` 读取配置，可选 `CROWDIN_API_BASE_URL` 和 `BAT_CURL`。
 token 不会进入报告、任务记录或调试输出。

+Glossary 只把 `approved` term 发送为 provider constraints。worker 会在 trusted TM
+复用前、provider 返回后、人工 `translation.task.update` 和 workbench publish 前执行
+同一套确定性 QA；冲突或未使用推荐/允许译法的结果不会自动完成或发布。允许但非推荐译法
+产生 warning；blocking deviation 必须在对应结果中提交 `glossary_override`，并包含
+`reviewer`、`reason`、`provenance` 和确认时间。系统不会在译文生成后做静默字符串替换。
+
 ### localized

 | 方法 | 状态 | params | data |
@@ -449,6 +468,10 @@ CLI 对应关系：
 | `bat i18n proofread` | `translation.proofread` |
 | `bat i18n memory summary` / `bat i18n memory query` | `translation.memory.summary` / `translation.memory.query` |
 | `bat i18n memory confirm` | `translation.memory.confirm` |
+| `bat i18n glossary summary` / `bat i18n glossary query` | `translation.glossary.summary` / `translation.glossary.query` |
+| `bat i18n glossary diagnose` | `translation.glossary.diagnose` |
+| `bat i18n glossary add/update` | `translation.glossary.add` / `translation.glossary.update` |
+| `bat i18n glossary approve/deprecate` | `translation.glossary.approve` / `translation.glossary.deprecate` |
 | `bat localized-status` | `localized.status` |
 | `bat resource-index` | `resource.index` |

@@ -481,7 +504,9 @@ CLI 对应关系：
  `localized.status`、`localized.publish`、`localized.rollback`、
  `translation.tasks`、`translation.handoff`、`translation.task.update`、
  `translation.worker.run`、`translation.proofread`、`translation.memory.summary`、
-  `translation.memory.query`、`translation.memory.confirm`、
+  `translation.memory.query`、`translation.memory.confirm`、`translation.glossary.summary`、
+  `translation.glossary.query`、`translation.glossary.diagnose`、`translation.glossary.add`、
+  `translation.glossary.update`、`translation.glossary.approve`、`translation.glossary.deprecate`、
  `task.*` 和三个 `unityfs.patch_*` 方法。
 - `resource.index` 和 `patch.apply` 当前没有专用 typed helper；需要直接使用 `Call`，并仍须遵守
  本契约的参数和响应定义。
@@ -498,6 +523,7 @@ CLI 对应关系：
 | `ParseBackend` | `parse.status`、`parse.text_units`、`parse.errors` | 鉴权后的当前 release 解析状态、TextUnit 和解析错误只读查询 |
 | `TranslationBackend` | `translation.tasks`、`translation.handoff`、`translation.task.update`、`translation.worker.run`、`translation.proofread` | 鉴权后的 dashboard 翻译任务查询、交接视图、状态回写、provider worker 触发与人工校对标记 |
 | `TranslationMemoryBackend` | `translation.memory.summary`、`translation.memory.query`、`translation.memory.confirm` | 鉴权后的 TM 摘要、source/context 查询和显式 candidate 确认；Go 只转发，不持有 TM 状态 |
+| `GlossaryBackend` | `translation.glossary.summary/query/diagnose/add/update/approve/deprecate` | 鉴权后的 Glossary 摘要、term/history 查询、确定性诊断和审核 mutation；Go 只转发，不持有 Glossary 状态 |
 | `LocalizedBackend` | `localized.status`、`localized.publish`、`localized.rollback` | 鉴权后的汉化 release 状态、发布与显式回滚 |

 `daemon.stop`、`daemon.clean-stable` 和任意通用 RPC 不属于 bat-api 管理控制面。
@@ -507,7 +533,8 @@ Rust dispatch、Go transport 和 bat-api 接口的权威实现位置分别是

 Go mirror contract fixture 固化在 `internal/api/testdata/contract/`，覆盖
 `catalog.status` available/unavailable、`resource.manifest` page0、对应
-`official-sync-snapshot.json` 以及 Translation Memory query/缺库 mirror。
+`official-sync-snapshot.json`、Translation Memory query/缺库 mirror 和 Glossary
+query/source-history mirror。
 这些 fixture/mirror 由 Rust 输出形状归一化而来，只用于
 schema / mirror 回归；live daemon socket 和完整 fixture release 切换由
 `make bat-api-local-live-smoke` 在同机 `/tmp` 隔离环境中验证。该 smoke 不替代
@@ -50,11 +50,13 @@
    catalog-status.unavailable.raw.json
    resource-manifest.page0.raw.json
    official-sync-snapshot.raw.json
+    glossary-query.raw.json
  normalized/
    catalog-status.available.json
    catalog-status.unavailable.json
    resource-manifest.page0.json
    official-sync-snapshot.json
+    glossary-query.json
  notes.md
 ```

@@ -72,6 +74,8 @@ Rust 窗口请基于当前真实代码生成或导出以下 JSON：
 2. `catalog.status` available=false 响应。
 3. `resource.manifest` 第一页响应，至少包含 1 到 2 个 entries。
 4. 对应 release 的 `official-sync-snapshot.json`。
+5. Rust Glossary V1 的 `translation.glossary.query` 响应，至少包含 alias、approved
+   review、source provenance 和 created/approved history。

 输出应来自 Rust 代码路径，而不是手写 JSON。允许使用 fixture resource root 或临时目录，但不能依赖开发机真实资源目录。

@@ -115,9 +115,9 @@ rollback，`localized.status` 能校验当前官方 release 与 patch manifest

 Rust `bat` 已提供独立项目级 SQLite TM，记录 raw source/hash、完整 context、release/TextUnit/provider/run provenance，区分 candidate/trusted，只有显式 confirm 才能建立 trusted 记录；worker 只自动复用 trusted 的 raw source + 完整 context exact match。Go `bat-api` 已提供鉴权的 summary/query 只读接口和 confirm 转发，但 Go 不持有 TM 状态。仍缺少模糊匹配、Glossary 联动和更丰富的导入导出历史能力。

-### G-013：Glossary 未实现
+### G-013：Glossary V1 已实现，协作视图仍缺失

-需要支持术语优先级、别名、分类、冲突检测和审核。
+Rust `bat` 已提供独立项目级 `glossary.sqlite`：term/alias/recommended/allowed/category/priority、全局与 TextUnit scope、source history、approved review、冲突诊断、provider-neutral constraints 和确定性 QA 均由 Rust 持有。trusted TM 复用会先经过 Glossary QA；provider、TM、人工 task/workbench 结果都记录 QA，blocking deviation 必须显式提交 reviewer/reason/provenance。`translation.glossary.*` 已通过 `bat.sock` 暴露，Go 仅提供鉴权后的 typed forwarding。剩余缺口是完整 Web 术语协作视图和更丰富的导入/搜索能力。

 ### G-014：完整 Provider 扩展体系未实现

@@ -145,7 +145,7 @@ Rust `bat` 已提供独立项目级 SQLite TM，记录 raw source/hash、完整

 1. 继续 G-005：真实 AssetBundle 样本、复杂字段解析和发布级重打包。
 2. 继续 G-006/G-011D：通用 manifest Patch 和双 release 查询/清理策略。
-3. 继续 G-011/G-012/G-013/G-014：资源查询、TM 扩展、Glossary 和 Provider
+3. 继续 G-011/G-012/G-013/G-014：资源查询、TM/Glossary 扩展和 Provider
   扩展体系。
 4. 在隔离环境执行 `make official-smoke`，补充真实网络长期运行报告。
 5. 最后推进完整 Web 协作后台和完整游戏业务 API。
@@ -95,8 +95,8 @@
 | 组件 | 路径 | 状态 | 说明 |
 |---|---|---|---|
 | Module | `go.mod` → `bat-api` | 已用 | 服务层模块名 |
-| RPC client | `internal/backendrpc` | **完成** | Unix socket JSON-RPC transport + typed helper；typed helper 覆盖 daemon 已实现控制/查询、`resource.state/sync/verify/repair/manifest/list`、`catalog.*`、`parse.*`、`localized.status/publish/rollback`、`task.*`、`translation.tasks`、`translation.handoff`、`translation.task.update`、`translation.worker.run`、`translation.proofread`、`translation.memory.summary/query/confirm` 和文件级 UnityFS patch 调用；`resource.index`、`patch.apply` 仍通过通用 `Call` 走同一 contract；fake transport 单测和 `internal/api/testdata/contract/` mirror test 固化 Rust 输出字段 |
-| 资源 bootstrap/分发 | `cmd/bat-api` + `internal/api` | **MVP+生产控制面** | RPC 发现 + 周期刷新/诊断 + `/v1/bootstrap` + `/v1/launcher/bootstrap` + launcher 资源 metadata 兼容 + `/readyz` + CDN Range/缓存头 + 鉴权/限流/访问日志/反代适配 + OpenAPI + 管理控制白名单 + translation/TM admin forwarding + 内嵌 dashboard + `.env` |
+| RPC client | `internal/backendrpc` | **完成** | Unix socket JSON-RPC transport + typed helper；typed helper 覆盖 daemon 已实现控制/查询、`resource.state/sync/verify/repair/manifest/list`、`catalog.*`、`parse.*`、`localized.status/publish/rollback`、`task.*`、`translation.tasks`、`translation.handoff`、`translation.task.update`、`translation.worker.run`、`translation.proofread`、`translation.memory.summary/query/confirm`、`translation.glossary.summary/query/diagnose/add/update/approve/deprecate` 和文件级 UnityFS patch 调用；`resource.index`、`patch.apply` 仍通过通用 `Call` 走同一 contract；fake transport 单测和 `internal/api/testdata/contract/` mirror test 固化 Rust 输出字段 |
+| 资源 bootstrap/分发 | `cmd/bat-api` + `internal/api` | **MVP+生产控制面** | RPC 发现 + 周期刷新/诊断 + `/v1/bootstrap` + `/v1/launcher/bootstrap` + launcher 资源 metadata 兼容 + `/readyz` + CDN Range/缓存头 + 鉴权/限流/访问日志/反代适配 + OpenAPI + 管理控制白名单 + translation/TM/Glossary admin forwarding + 内嵌 dashboard + `.env` |
 | 试验 CLI | `cmd/bat` | **试验** | doctor 固定 ok；manifest/sync 走 FFI |
 | FFI | `internal/ffi` | **可选** | 需 `build-ffi` |
 | 空骨架 | `api/`、`pkg/*`、部分 `internal/*` | **空** | 见各目录 README |