mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-09-18 06:34:54 +08:00
feat(bat): 完善工作流调度与 dashboard RPC
补全资源拉取、解析、翻译、重打包和本地化发布命令，支持单次、限定次数与周期调度。移除 TUI 计划并通过 schedule.* RPC 暴露给 bat-api dashboard。 Closes #43
This commit is contained in:
@@ -0,0 +1,147 @@
|
||||
# Rust bat 工作流命令
|
||||
|
||||
Rust `bat` 的工作流入口按三个一级命令组织：
|
||||
|
||||
- `res`：官方资源拉取、校验、修复和拉取计划。
|
||||
- `parse`：当前官方 release 的解析和 UnityFS 重打包。
|
||||
- `i18n`：离线翻译工作台、人工文本修改和汉化 release 发布。
|
||||
|
||||
`resource`、`resources`、`translation` 和 `translate` 仍作为长别名接受，但文档示例统一使用 `res` 和 `i18n`。
|
||||
|
||||
## 资源拉取
|
||||
|
||||
单次拉取：
|
||||
|
||||
```bash
|
||||
bat res pull --auto-discover --output /tmp/bat-resources
|
||||
```
|
||||
|
||||
同一进程内限定次数执行。第二轮及以后必须显式给出间隔：
|
||||
|
||||
```bash
|
||||
bat res pull --auto-discover \
|
||||
--run-count 3 \
|
||||
--interval 1h \
|
||||
--output /tmp/bat-resources
|
||||
```
|
||||
|
||||
无限周期执行使用 `--watch`：
|
||||
|
||||
```bash
|
||||
bat res pull --auto-discover --watch --interval 1h \
|
||||
--output /tmp/bat-resources
|
||||
```
|
||||
|
||||
资源下载默认使用 8 个独立 worker，允许范围为 `1..=256`。worker 完成当前 URL 后立即领取共享队列中的下一个任务，进度按完成顺序统计，最终报告仍按计划顺序输出。
|
||||
|
||||
## 解析与重打包
|
||||
|
||||
解析当前已发布 release：
|
||||
|
||||
```bash
|
||||
bat parse run --output /tmp/bat-resources
|
||||
```
|
||||
|
||||
也可以显式指定隔离的已发布 release 根目录：
|
||||
|
||||
```bash
|
||||
bat parse run \
|
||||
--resource-root /tmp/bat-resources/versions/<release-id> \
|
||||
--force
|
||||
```
|
||||
|
||||
解析结果会刷新 `official-parse-cache.json`、`official-textunit-index.json` 和翻译队列。`--force` 忽略已有解析缓存，但仍要求输入 release 已通过官方下载 manifest 校验。
|
||||
|
||||
批量 UnityFS 重打包使用 JSON spec。spec 的 `schema_version` 当前为 `1`，支持 `text_asset`、`string_field` 和受支持的语义 `field` 操作：
|
||||
|
||||
```bash
|
||||
bat parse repack --repack-spec /tmp/bat-repack.json
|
||||
```
|
||||
|
||||
重打包写入独立的 `target_bundle`，逐个操作后由底层 UnityFS patch 实现重建并校验，不允许 source 和 target 相同。
|
||||
|
||||
## 翻译工作台与发布
|
||||
|
||||
导出可人工编辑的工作台：
|
||||
|
||||
```bash
|
||||
bat i18n export \
|
||||
--output /tmp/bat-resources \
|
||||
--translation-file /tmp/bat-workbench.json
|
||||
```
|
||||
|
||||
修改一个条目：
|
||||
|
||||
```bash
|
||||
bat i18n set \
|
||||
--translation-file /tmp/bat-workbench.json \
|
||||
--translation-id <text-unit-id> \
|
||||
--translated-text '中文文本'
|
||||
```
|
||||
|
||||
也可以使用 `--translated-file` 读取 UTF-8 文本。工作台会保存 source text、release ID、TextUnit 目标和人工译文；发布前会重新读取当前 TextUnit 索引，拒绝过期 release、source text 或 patch 目标。
|
||||
|
||||
发布汉化 release：
|
||||
|
||||
```bash
|
||||
bat i18n publish \
|
||||
--output /tmp/bat-resources \
|
||||
--localized-output /tmp/bat-localized \
|
||||
--translation-file /tmp/bat-workbench.json
|
||||
```
|
||||
|
||||
发布只接受当前实现支持的直接 TextAsset 条目；TypeTree 字段和 zip 内 bundle 使用 `parse repack` 的 spec 单独处理。`--force` 不覆盖已有目录，而是生成独立的 `<official-release>-manual-<unix-seconds>` 汉化 release ID；也可以用 `--localized-release-id` 显式指定新 ID。因此强制发布仍保留旧 release 和 rollback 信息。
|
||||
|
||||
当前 `i18n run` 是离线工作流：刷新 TextUnit 队列，并可用 `--translation-file` 导出工作台；不会假装调用未接入的外部 provider。
|
||||
|
||||
## 持久化调度
|
||||
|
||||
每个一级工作流都可以管理自己的 schedule。调度计划保存在 `--state-dir/bat-schedules.json`，计划记录包含动作、参数、下一次执行时间、周期、剩余次数、启用状态和最近错误。
|
||||
|
||||
新增一个每天执行的资源拉取计划：
|
||||
|
||||
```bash
|
||||
bat res schedule add \
|
||||
--state-dir /tmp/bat-schedule \
|
||||
--schedule-id daily-pull \
|
||||
--schedule-action pull \
|
||||
--schedule-delay 1s \
|
||||
--schedule-every 24h \
|
||||
--schedule-arg --auto-discover \
|
||||
--schedule-arg --output \
|
||||
--schedule-arg /tmp/bat-resources
|
||||
```
|
||||
|
||||
计划操作：
|
||||
|
||||
```bash
|
||||
bat res schedule list --state-dir /tmp/bat-schedule
|
||||
bat res schedule update --state-dir /tmp/bat-schedule --schedule-id daily-pull --schedule-every 12h
|
||||
bat res schedule remove --state-dir /tmp/bat-schedule --schedule-id daily-pull
|
||||
bat res schedule run --state-dir /tmp/bat-schedule
|
||||
```
|
||||
|
||||
`parse schedule add` 默认动作是 `run`，`i18n schedule add` 默认动作也是 `run`；可以用 `--schedule-action repack` 或 `--schedule-action publish` 选择对应动作。`--schedule-count` 限定执行次数，省略表示周期无限执行；没有 `--schedule-every` 的计划执行一次后自动停用。
|
||||
|
||||
`schedule update` 可以用 `--schedule-clear-every` 将周期计划改为单次计划；`schedule remove` 会删除计划。`schedule run --force` 会忽略到期时间立即执行指定计划。
|
||||
|
||||
## bat-api 调度接口
|
||||
|
||||
dashboard 通过 `bat-api` 转发到 Rust `bat.sock`，不维护第二份计划状态。Rust RPC 方法为：
|
||||
|
||||
- `schedule.list`
|
||||
- `schedule.add`
|
||||
- `schedule.update`
|
||||
- `schedule.remove`
|
||||
- `schedule.run`
|
||||
|
||||
`bat-api` 对应接口为 `GET /admin/schedules` 和
|
||||
`POST /admin/control/schedule-add|schedule-update|schedule-remove|schedule-run`，
|
||||
均要求配置 `BAT_API_AUTH_TOKEN` 并携带管理 token。请求字段沿用 Rust
|
||||
contract：`id`、`group`、`action`、`args`、`next_run_unix_seconds`、
|
||||
`delay_seconds`、`every_seconds`、`count`、`clear_args`、`clear_every`、
|
||||
`enabled`；`schedule.run` 额外接受 `force`。
|
||||
|
||||
## 边界
|
||||
|
||||
解析器新增类型覆盖和新的解析格式仍受 `docs/reports/PARSER_FREEZE.md` 约束。本次 issue 43 的例外只开放已有解析输出的手动编排、缓存刷新、工作台编辑、既有 patch 实现的重打包和独立汉化发布，不扩展 UnityFS/AssetBundle/Addressables/TypeTree 的解析类型覆盖。
|
||||
@@ -189,6 +189,8 @@ cargo clippy -p bat-core -p bat-adapters -p bat-infrastructure --all-targets --
|
||||
|
||||
`bat-ffi` 只是可选无状态 C ABI 兼容层。修改 FFI 时必须运行 `cargo test -p bat-ffi -- --nocapture`。Go 服务层默认经 `internal/backendrpc` 调 daemon；同步任务由 Rust `bat` 执行，不由 Go 试验 CLI 承担。
|
||||
|
||||
Rust `bat` 的资源拉取、解析、翻译工作流、重打包、汉化发布和持久化调度命令见 [`docs/guides/bat-workflows.md`](bat-workflows.md)。推荐使用 `res`、`parse`、`i18n` 三个一级命令；该工作流当前对应 issue `#43`。
|
||||
|
||||
### 集成测试
|
||||
|
||||
```bash
|
||||
|
||||
@@ -159,6 +159,40 @@ SQLite `ResourceRepository`，索引不存在时返回 `ok=true` 且
|
||||
|
||||
删除资源只进入 `official-resource-changes.json`，不进入 Crowdin handoff。
|
||||
|
||||
### schedule
|
||||
|
||||
调度计划由 Rust `bat` 持有，状态文件为 daemon `state_dir` 下的
|
||||
`bat-schedules.json`。CLI、RPC 和 `bat-api` dashboard 都调用同一组原子
|
||||
读改写逻辑，不在 Go 侧复制计划状态。
|
||||
|
||||
| 方法 | 状态 | params | data |
|
||||
|---|---|---|---|
|
||||
| `schedule.list` | 已实现 | `null` | `{ "command": "schedule-list", "schedules": [...] }`。 |
|
||||
| `schedule.add` | 已实现 | 调度 mutation | 新建 schedule report。 |
|
||||
| `schedule.update` | 已实现 | 调度 mutation，必须有 `id` | 更新后的 schedule report。 |
|
||||
| `schedule.remove` | 已实现 | `{ "id": "daily-pull" }` | 删除报告。 |
|
||||
| `schedule.run` | 已实现 | `{ "id": "daily-pull", "force": true }`，字段可省略 | 到期或强制执行报告；省略 `id` 执行所有到期计划。 |
|
||||
|
||||
调度 mutation 字段如下：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `id` | string | 计划 ID；add 必填，update/remove 用于定位。 |
|
||||
| `group` | string | `res`、`parse` 或 `i18n`；对应一级工作流。 |
|
||||
| `action` | string | `res` 的 `pull/refresh/verify/repair`、`parse` 的 `run/repack`、`i18n` 的 `run/export/publish`。 |
|
||||
| `args` | string[] | 目标工作流的 CLI 参数。 |
|
||||
| `next_run_unix_seconds` | uint64 | 指定下一次执行时间；不能和 `delay_seconds` 同时使用。 |
|
||||
| `delay_seconds` | uint64 | 从当前时间计算下一次执行时间。 |
|
||||
| `every_seconds` | uint64 | 周期秒数；必须大于 0。 |
|
||||
| `count` | uint64 | 最大执行次数；省略周期无限执行，非周期计划默认执行一次。 |
|
||||
| `clear_args` | bool | update 时清空工作流参数。 |
|
||||
| `clear_every` | bool | update 时清除周期并转为单次计划。 |
|
||||
| `enabled` | bool | 启用或停用计划。 |
|
||||
|
||||
`count > 1` 必须和周期同时存在；`schedule.run` 的 `force=true` 只忽略
|
||||
到期时间，不会绕过 `enabled=false`。每次执行前先持久化下一次状态，执行后
|
||||
再持久化成功/失败和错误信息，避免进程中断后重复领取同一计划。
|
||||
|
||||
### parse
|
||||
|
||||
| 方法 | 状态 | params | data |
|
||||
@@ -376,7 +410,8 @@ CLI 对应关系：
|
||||
- `Call` 可发送本文档中的任意已记录方法，并负责 JSON-RPC transport、
|
||||
envelope 和 `ApiError` 解码；它不是 bat-api 的 HTTP 任意 RPC proxy。
|
||||
- typed helper 已覆盖 daemon 已实现方法（`status/logs/stop/restart/reload/refresh/doctor`）、
|
||||
`resource.state/sync/verify/repair/manifest/list`、`catalog.*`、`parse.*`、
|
||||
`resource.state/sync/verify/repair/manifest/list`、`schedule.list/add/update/remove/run`、
|
||||
`catalog.*`、`parse.*`、
|
||||
`localized.status`、`task.*` 和三个
|
||||
`unityfs.patch_*` 方法。
|
||||
- `resource.index`、`translation.tasks`、`translation.handoff`、
|
||||
@@ -389,6 +424,7 @@ CLI 对应关系：
|
||||
|---|---|---|
|
||||
| `Backend` | `daemon.status`、`daemon.doctor`、`resource.state`、`catalog.status`、`resource.manifest` | 启动发现、周期刷新和资源分发 |
|
||||
| `ControlBackend` | `daemon.restart`、`daemon.reload`、`daemon.refresh`、`resource.sync`、`resource.verify`、`resource.repair`、`catalog.refresh` | 鉴权后的管理控制白名单 |
|
||||
| `ScheduleBackend` | `schedule.list`、`schedule.add`、`schedule.update`、`schedule.remove`、`schedule.run` | 鉴权后的 dashboard 调度计划控制 |
|
||||
|
||||
`daemon.stop`、`daemon.clean-stable` 和任意通用 RPC 不属于 bat-api 管理控制面。
|
||||
Rust dispatch、Go transport 和 bat-api 接口的权威实现位置分别是
|
||||
|
||||
@@ -123,6 +123,8 @@
|
||||
- `ResourceImportService` 的 UnityFS 摘要已经能暴露解包文件数、serialized file 数、TextAsset 名称、TextUnit 数量/格式和字段诊断。
|
||||
- `MonoBehaviour`、`ScriptableObject` 已有基础 TypeTree 字段级反序列化和字符串提取入口；array/vector/staticvector/`List<T>`/`HashSet<T>`/map 元素与 TypeTree-covered managed reference registry payload 已保留独立 field path、offset 和 byte size，enum `value__` backing field 会暴露为语义化 `{type_name, storage_type, value}`，`LayerMask` / `BitField` 的 `m_Bits` backing field 会暴露为语义化 `{type_name, storage_type, bits}`，managed-reference full typename 可拆为 assembly/namespace/class，常见 `m_ManagedReferences` / `RefIds` / `m_RefIds` / verbose type 字段命名、`managedReference*` / `serializedReference*` prefixed metadata、`SerializedReference` 节点 alias 和 `data` / `value` / `payload` / `object` / `managedReferencePayload` / `referencePayload` / `serializedReferencePayload` / `managedReferenceValue` / `referenceValue` / `serializedReferenceValue` / `managedReferenceObject` / `referenceObject` / `serializedReferenceObject` / `managedReferenceData` / `referenceData` / `serializedData` / `serializedReferenceData` payload 命名已有回归覆盖，多记录 registry 聚合已有单元回归，TextUnit 提取会跳过 registry 元数据字符串并把它们作为 payload 文本上下文，fallback 字段遍历也会跳过常见 managed-reference 元数据别名，并按 `RefIds[n]` 等记录前缀或子字段推导 metadata 写入 payload TextUnit context；当前可对 string、bool、integer、float raw bits、bytes、enum、bit_field、常见固定 Unity float/int/hash 值类型的 leaf/direct-child 形态、unknown fixed-size raw bytes 同长度替换、PPtr、object 字段组合和 TypeTree schema 支撑的 array/vector/List/HashSet/map 整体替换执行文件级 patch，map entry 的 `first/second` 与 `key/value` 字段命名已有 serialized 和 UnityFS 重建回归，ScriptableObject `key/value` map 解析、变长替换和 UnityFS 重建已有专门回归；真实版本差异、未见样本驱动的复杂 managed reference registry / map entry 变体、unknown 字段结构语义和发布级重打包入口仍未完成。
|
||||
|
||||
issue 43 例外说明：新增的 `parse repack` 只编排已有 TextAsset、TypeTree string 和受支持语义 field patch 实现；它不新增解析器类型、字段族或 catalog 覆盖。人工翻译工作台和有限 TextAsset 发布也只消费已有 TextUnit 输出。
|
||||
|
||||
影响：
|
||||
|
||||
- 可以对 UnityFS 容器做结构校验、解包 directory 文件，并提取 serialized file 中的 TextAsset 原始 bytes。
|
||||
@@ -165,7 +167,7 @@
|
||||
|
||||
- 通用 Binary/JSON/Text Patch crate 能力可作为后续发布流程输入。
|
||||
- 文件级写入入口可用于隔离测试和上层工具显式产物生成。
|
||||
- 发布级 `patch build` / `patch rollback`、复杂 AssetBundle 重打包和通用 manifest 在发布命令中的正式使用仍未完成。
|
||||
- 发布级通用 `patch build` / `patch rollback`、复杂 AssetBundle 重打包和完整翻译文件集合的正式使用仍未完成；issue 43 的 `parse repack` 与 `i18n publish` 仅覆盖已有 patch 实现支持的安全子集。
|
||||
|
||||
验收：
|
||||
|
||||
|
||||
@@ -134,7 +134,7 @@ make build-go-cli # 产出 bin/bat-go
|
||||
| 项 | 状态 |
|
||||
|---|---|
|
||||
| G-008 Go 同步 CLI | **已决策关闭**（正式同步 CLI = Rust `bat`） |
|
||||
| G-009 bat-api 资源 bootstrap/分发 | **部分完成**（MVP+生产控制面）；已含资源 bootstrap 关系面、launcher 资源 metadata 兼容、HTTP 鉴权/限流/日志/反代适配、RPC 周期刷新/诊断、readiness、OpenAPI、管理控制白名单和部署模板，后续远程服务器联调/可选持久化 |
|
||||
| G-009 bat-api 资源 bootstrap/分发 | **部分完成**（MVP+生产控制面）；已含资源 bootstrap 关系面、launcher 资源 metadata 兼容、HTTP 鉴权/限流/日志/反代适配、RPC 周期刷新/诊断、readiness、OpenAPI、管理控制白名单、Rust-owned `schedule.*` dashboard 代理和部署模板，后续远程服务器联调/可选持久化 |
|
||||
| issue #19 | 资源面 MVP 与 USERGUIDE 基础章节已编码；真机联调后继续补充实战样例；**未自动关 issue** |
|
||||
| G-010 Web | 未开始 |
|
||||
|
||||
|
||||
@@ -27,6 +27,16 @@
|
||||
- 修正文档、CLI 帮助、RPC 参考和状态文件中与当前实现不一致的解析能力声明。
|
||||
- 改善错误信息、日志字段、状态记录和失败恢复，但不得改变解析输出契约，除非是修复错误契约且同步迁移说明。
|
||||
|
||||
## issue 43 的明确例外
|
||||
|
||||
本次 issue 43 经用户明确授权，允许新增 `bat` 的工作流编排入口：
|
||||
|
||||
- `parse run` 只刷新已有解析输出、TextUnit 索引和翻译队列；
|
||||
- `parse repack` 只调用已有 TextAsset、TypeTree string 和受支持语义字段 patch 实现；
|
||||
- `i18n` 工作台和 `publish` 只消费已有 TextUnit 输出，并发布独立汉化 release。
|
||||
|
||||
该例外不解冻解析器，不新增 UnityFS/AssetBundle/Addressables/TypeTree 解析类型、字段覆盖、catalog 结构或合成 fixture 能力。后续任何扩大解析覆盖的变更仍需单独解冻授权。
|
||||
|
||||
## 禁止变更
|
||||
|
||||
冻结期禁止以下解析相关变更：
|
||||
|
||||
Reference in New Issue
Block a user