# 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 的解析类型覆盖。