BlueArchiveToolkit/docs/guides/bat-workflows.md

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 都会落到同一组已实现命令。

资源拉取

单次拉取：

bat res pull --auto-discover --output /tmp/bat-resources

同一进程内限定次数执行。第二轮及以后必须显式给出间隔：

bat res pull --auto-discover \
  --run-count 3 \
  --interval 1h \
  --output /tmp/bat-resources

无限周期执行使用 --watch：

bat res pull --auto-discover --watch --interval 1h \
  --output /tmp/bat-resources

资源下载默认使用 8 个独立 worker，允许范围为 1..=256。worker 完成当前 URL 后立即领取共享队列中的下一个任务，进度按完成顺序统计，最终报告仍按计划顺序输出。

解析与重打包

解析当前已发布 release：

bat parse run --output /tmp/bat-resources

也可以显式指定隔离的已发布 release 根目录：

bat parse run \
  --resource-root /tmp/bat-resources/versions/<release-id> \
  --force

解析结果会刷新 official-parse-cache.json、official-textunit-index.json 和翻译队列。--force 忽略已有解析缓存，但仍要求输入 release 已通过官方下载 manifest 校验。

清理当前 release 的可再生解析缓存和离线翻译队列：

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 操作：

bat parse repack --repack-spec /tmp/bat-repack.json

重打包写入独立的 target_bundle，逐个操作后由底层 UnityFS patch 实现重建并校验，不允许 source 和 target 相同。

翻译工作台与发布

导出可人工编辑的工作台：

bat i18n export \
  --output /tmp/bat-resources \
  --translation-file /tmp/bat-workbench.json

修改一个条目：

bat i18n set \
  --translation-file /tmp/bat-workbench.json \
  --translation-id <text-unit-id> \
  --translated-text '中文文本'

也可以使用 --translated-file 读取 UTF-8 文本。需要复核单条内容时：

bat i18n get \
  --translation-file /tmp/bat-workbench.json \
  --translation-id <text-unit-id> \
  --json

需要把某条译文恢复为未审核状态时：

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 目标。

发布前可只做工作台审计：

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：

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。

provider worker 消费 handoff 后，可以用 i18n task update 回写当前 release 的任务状态：

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 切到人工校对中时，可用：

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 的简写。

新增一个每天执行的资源拉取计划：

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

计划操作：

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 通过 POST /admin/control/translation-task-update 回写，请求字段为 task_id、status，以及可选的 failure_reason、provider_run_id； 该接口只转发 translation.task.update。

POST /admin/control/translation-proofread 会把当前汉化 workflow 标记为人工校对中； 该接口只转发 translation.proofread，不会改动已发布汉化 release 指针。

边界

解析器新增类型覆盖和新的解析格式仍受 docs/reports/PARSER_FREEZE.md 约束。本次 issue 43 的例外只开放已有解析输出的手动编排、缓存刷新、工作台编辑、既有 patch 实现的重打包和独立汉化发布，不扩展 UnityFS/AssetBundle/Addressables/TypeTree 的解析类型覆盖。