mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-09-18 07:24:55 +08:00
272 lines
11 KiB
Markdown
272 lines
11 KiB
Markdown
# Rust bat 工作流命令
|
||
|
||
Rust `bat` 的工作流入口按三个一级命令组织：
|
||
|
||
- `res`：官方资源拉取、校验、修复和拉取计划。
|
||
- `parse`：当前官方 release 的解析和 UnityFS 重打包。
|
||
- `i18n`：离线翻译工作台、人工文本修改和汉化 release 发布。
|
||
|
||
`resource`、`resources`、`translation` 和 `translate` 仍作为长别名接受，但文档示例统一使用 `res` 和 `i18n`；例如 `resource status`、`resource schedule`、`translation tasks`、`translation handoff` 和 `translation status` 都会落到同一组已实现命令。
|
||
|
||
## 资源拉取
|
||
|
||
单次拉取：
|
||
|
||
```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 校验。
|
||
|
||
清理当前 release 的可再生解析缓存和离线翻译队列：
|
||
|
||
```bash
|
||
bat parse clear-cache \
|
||
--resource-root /tmp/bat-resources/versions/<release-id> \
|
||
--force
|
||
```
|
||
|
||
该命令不会删除 `translation-tasks.sqlite`；worker 状态必须通过任务接口单独维护。
|
||
|
||
批量 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 文本。需要复核单条内容时：
|
||
|
||
```bash
|
||
bat i18n get \
|
||
--translation-file /tmp/bat-workbench.json \
|
||
--translation-id <text-unit-id> \
|
||
--json
|
||
```
|
||
|
||
需要把某条译文恢复为未审核状态时：
|
||
|
||
```bash
|
||
bat i18n unset \
|
||
--translation-file /tmp/bat-workbench.json \
|
||
--translation-id <text-unit-id>
|
||
```
|
||
|
||
这些工作台操作也可以写成 `bat i18n workbench set|get|unset|validate ...`，
|
||
`--translation-file` 也可简写为 `--workbench`。
|
||
工作台会保存 source text、release ID、TextUnit 目标和人工译文；发布前会重新读取当前
|
||
TextUnit 索引，拒绝过期 release、source text 或 patch 目标。
|
||
|
||
发布前可只做工作台审计：
|
||
|
||
```bash
|
||
bat i18n validate \
|
||
--resource-root /tmp/bat-resources/versions/<release-id> \
|
||
--translation-file /tmp/bat-workbench.json
|
||
```
|
||
|
||
报告会区分未审核、原文未变化、可直接 `i18n publish` 的 TextAsset，以及必须使用
|
||
`parse repack` 的 TypeTree/嵌套 archive 条目。
|
||
|
||
发布汉化 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 由单独的 worker 命令消费 `translation-tasks.sqlite`。
|
||
|
||
运行一次 mock provider worker：
|
||
|
||
```bash
|
||
bat i18n worker run \
|
||
--output /tmp/bat-resources \
|
||
--provider mock \
|
||
--worker-concurrency 8
|
||
```
|
||
|
||
`--provider` 支持 `mock` 和 `crowdin`。`mock` 可通过 `--translation-fixture`
|
||
读取本地 JSON fixture；`crowdin` 从环境变量 `CROWDIN_PROJECT_ID`、
|
||
`CROWDIN_LANGUAGE_ID`、`CROWDIN_API_TOKEN` 读取配置。worker 默认并发为 8，
|
||
范围 `1..=256`；每个 worker 完成当前任务后立即从 SQLite 队列领取下一项，
|
||
不会等待当前一批 worker 全部结束后再重新分配。
|
||
|
||
可用参数包括 `--worker-max-attempts`、`--worker-lease-seconds`、
|
||
`--worker-retry-backoff` / `--worker-retry-backoff-seconds`、
|
||
`--worker-max-tasks` 和 `--worker-id`。worker 支持 `--run-count` 与
|
||
`--watch`，因此可以单次、限定次数或周期执行；`--run-count > 1` 时仍必须
|
||
显式指定 `--interval`。
|
||
|
||
外部 provider 或人工流程也可以用 `i18n task update` 回写当前 release 的任务状态：
|
||
|
||
```bash
|
||
bat i18n task update \
|
||
--state-dir /tmp/bat-state \
|
||
--task-id textunit/v-current/TextAssets/Scenario.json \
|
||
--task-status failed \
|
||
--failure-reason "provider rejected payload" \
|
||
--provider-run-id provider-run-1 \
|
||
--json
|
||
```
|
||
|
||
`--task-status` 支持 Rust contract 中的 `queued`、`running`、`failed`、
|
||
`completed` 和 `skipped`；命令只更新当前 release 的
|
||
`translation-tasks.sqlite`，不会创建任意翻译任务。
|
||
任务查询和交接查询可以用 `bat i18n tasks` / `bat i18n handoff`；
|
||
汉化发布状态可以用 `bat i18n status`。这些只读入口也可以写成
|
||
`bat translation tasks|handoff|status`，其中 `translation` / `translate`
|
||
是一级命令长别名。
|
||
|
||
需要把当前汉化 workflow 切到人工校对中时，可用：
|
||
|
||
```bash
|
||
bat i18n proofread \
|
||
--output /tmp/bat-resources \
|
||
--localized-output /tmp/bat-localized
|
||
```
|
||
|
||
该命令只改写 `localized-version-state.json` 中的工作流标记，不会改动已发布的
|
||
汉化 release 指针；如果自动汉化已经发布，后续仍可继续正常发布汉化资源。
|
||
|
||
## 持久化调度
|
||
|
||
每个一级工作流都可以管理自己的 schedule。调度计划保存在 `--state-dir/bat-schedules.json`，计划记录包含动作、参数、下一次执行时间、周期、剩余次数、启用状态和最近错误。
|
||
`parse schedule` 与 `res schedule` / `i18n schedule` 共用同一份计划库，
|
||
`--id` / `--action` 分别是 `--schedule-id` / `--schedule-action` 的简写。
|
||
|
||
新增一个每天执行的资源拉取计划：
|
||
|
||
```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
|
||
bat parse schedule list --state-dir /tmp/bat-schedule
|
||
```
|
||
|
||
`parse schedule add` 默认动作是 `run`，`i18n schedule add` 默认动作也是 `run`；可以用 `--schedule-action repack` 或 `--schedule-action publish` 选择对应动作。`--schedule-count` 限定执行次数，省略表示周期无限执行；没有 `--schedule-every` 的计划执行一次后自动停用。
|
||
|
||
`res/parse/i18n schedule list` 默认只显示对应一级命令的计划；也可以用
|
||
`--schedule-id`、`--schedule-enabled` 或 `--schedule-disabled` 过滤。计划删除和执行
|
||
会校验一级命令作用域，避免误操作其他工作流。`schedule update` 可以用
|
||
`--schedule-clear-every` 将周期计划改为单次计划；`schedule remove` 会删除计划。
|
||
`schedule run --force` 会忽略到期时间立即执行指定计划，`--schedule-max-runs N`
|
||
限制本轮最多执行 N 个到期计划。
|
||
|
||
## 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。列表接口支持 `id`、`group`、
|
||
`enabled` query 过滤；请求字段沿用 Rust
|
||
contract：`id`、`group`、`action`、`args`、`next_run_unix_seconds`、
|
||
`delay_seconds`、`every_seconds`、`count`、`clear_args`、`clear_every`、
|
||
`enabled`；`schedule.list` 额外接受 `id`、`group`、`enabled` 过滤，
|
||
`schedule.run` 额外接受 `group`、`force` 和 `max_runs`。
|
||
|
||
翻译任务状态可由已鉴权的 dashboard 通过 `GET /admin/translation/tasks`
|
||
查询，query 过滤项包括 `offset`、`limit`、`task_id`、`release_id`、
|
||
`destination`、`path_pattern`、`archive_entry`、`status`、`worker_status`、
|
||
`parse_status`、`format`、`has_reason` 和 `has_failure_reason`。完整 provider
|
||
run 交接视图通过 `GET /admin/translation/handoff` 查询。两个查询接口都只转发
|
||
Rust `translation.tasks` / `translation.handoff`，不在 Go 侧维护状态。
|
||
|
||
翻译任务状态也可由已鉴权的 dashboard 通过
|
||
`POST /admin/control/translation-task-update` 回写，请求字段为
|
||
`task_id`、`status`，以及可选的 `failure_reason`、`provider_run_id`；
|
||
该接口只转发 `translation.task.update`。
|
||
|
||
`POST /admin/control/translation-worker-run` 会触发 Rust 侧
|
||
`translation.worker.run`，请求字段为 `provider`、`fixture_path`、
|
||
`concurrency`、`max_attempts`、`lease_seconds`、`retry_backoff_seconds`、
|
||
`max_tasks` 和 `worker_id`。bat-api 只做鉴权、JSON 解码和基础范围校验；
|
||
任务状态、lease、重试和 provider 结果仍由 Rust 持久化。
|
||
|
||
`POST /admin/control/translation-proofread` 会把当前汉化 workflow 标记为人工校对中；
|
||
该接口只转发 `translation.proofread`，不会改动已发布汉化 release 指针。
|
||
|
||
## 边界
|
||
|
||
解析器新增类型覆盖和新的解析格式仍受 `docs/reports/PARSER_FREEZE.md` 约束。本次 issue 43 的例外只开放已有解析输出的手动编排、缓存刷新、工作台编辑、既有 patch 实现的重打包和独立汉化发布，不扩展 UnityFS/AssetBundle/Addressables/TypeTree 的解析类型覆盖。
|