CLI 命令与格式参考
本页用于查阅 CLI 语法、JSON 字段和限制。安装路径及适用版本见快速开始。下方语法使用 resprite-cli 简写；尖括号表示需替换的值，方括号表示可选参数，执行时不要输入括号。
命令语法
resprite-cli --help
resprite-cli --version
resprite-cli inspect <file.resprite>
resprite-cli export image <file.resprite> --output <file.png> [--frame N] [--overwrite] [--dry-run]
resprite-cli export frames <file.resprite> --output <directory> [--clip-id ID] [--split-layers] [--overwrite] [--dry-run]
resprite-cli export sheet <file.resprite> --output <directory> [--columns N] [--clip-id ID] [--split-layers] [--overwrite] [--dry-run]
resprite-cli export --config <file.json> [--dry-run]
resprite-cli batch --config <file.json> [--dry-run]
命令参数
| 参数 | 含义与默认值 |
|---|---|
--output PATH | 直接导出时必填的目标路径；父目录必须存在 |
--frame N | 仅 image；从 0 开始的非负整数，默认 0 |
--columns N | 仅 sheet；正整数，默认 8 |
--clip-id ID | 仅 frames / sheet；来自 inspect 的片段首帧 ID；省略时导出整个时间轴 |
--split-layers | 仅 frames / sheet；按编辑器分组规则拆分可见图层单元；省略时合成 |
--overwrite | 允许覆盖；省略时拒绝已有输出。动画目录必须是完整的 CLI 产物 |
--dry-run | 校验并返回计划，不发布产物；适用于直接导出、配置导出和批量任务 |
--config PATH | 读取 schema 1 JSON；export 只接受一个任务，batch 接受 1–100 个 |
--help / --version | 返回命令帮助 / CLI 实现版本，格式为文本 |
未知、重复或当前模式不适用的参数会被拒绝。使用 --config 时只能额外添加 --dry-run，其他导出选项应修改配置。命令行相对路径以当前工作目录为基准，含空格的路径需加引号。预演时，已有输出也需要明确允许覆盖。
配置格式
配置根对象只接受 schemaVersion 和 jobs，版本必须是整数 1。未知字段、错误类型和当前模式不适用的选项都会被拒绝；字符串不会自动转换成布尔值或数字。配置不执行脚本、不展开通配符，也不读取编辑器设置。
| 任务字段 | 适用与默认值 |
|---|---|
mode、source、output | 必填非空字符串；模式为 image / frames / sheet，输入为 .resprite |
overwrite | 所有模式；布尔值，默认 false |
frame | image；从 0 开始的非负整数，默认 0，输出必须为 .png |
columns | sheet；正整数，默认 8 |
clipId | frames / sheet；非空字符串，来自 inspect 的 clips[].id |
splitLayers | frames / sheet；布尔值，默认 false |
完整配置示例见配置与批量导出。JSON 中的相对路径以配置文件所在目录为基准。
检查工程
需要查看帧、图层或取得片段 ID 时，运行：
resprite-cli inspect hero.resprite
命令返回工程结构 JSON，不修改源工程或创建输出。它仍会加载工程图片，并要求可用的图形环境；缺失图片或损坏文档会返回输入错误。
例如，clips 中的一个条目可能如下。将其中的 id 传给 --clip-id，即可选择该片段；同名片段也通过 ID 区分：
{
"id": "frame-walk-start",
"name": "Walk",
"firstFrame": 0,
"lastFrame": 1,
"direction": "Forward",
"playbackFrames": [0, 1]
}
结果与退出码
通过进程 API 集成时，分别传入可执行文件路径和参数数组。stdout 使用 UTF-8：检查、导出、预演和正常完成的批量返回一个 JSON 对象；--help 与 --version 返回文本。诊断写入 stderr，可能混有引擎日志；不要合并两个流后解析 JSON，也不要要求 stderr 为空。
| 退出码 | 含义及处理 |
|---|---|
| 0 | 成功；读取 stdout 结果 |
| 2 | 参数、配置或输出计划错误；修正选项后重试 |
| 3 | 输入文件或文档错误；检查源工程及配置文件 |
| 4 | 输出路径、覆盖、占用或写入失败；检查目标和权限 |
| 5 | 渲染或编码失败；保留 stderr 诊断 |
| 6 | 批量中至少一项失败；读取 stdout 的逐项结果 |
| 70 | 内部错误、启动失败或超时；保留诊断并检查可能已生成的产物 |
单任务失败或批量开始前失败时，stdout 为空。正常完成的批量即使返回退出码 6，也会提供汇总。内部错误会立即中止；超时或强制结束可能留下产物，却没有最终报告。处理方法见批量失败处理。
所有成功结果均包含 schemaVersion: 1、status: ok 和 cliVersion。批量汇总也包含这些字段，但有失败项时 status 为 error。
| 结果类型 | 主要字段 |
|---|---|
| 单帧导出 | 绝对 source、output，以及 frame、width、height |
| 动画导出 | source、output、mode、manifest、imageCount、regionCount |
| 检查工程 | action: inspect、绝对 source、sourceSha256、canvas、frameRate、durationScale、frames、layers、clips、limits |
| 单帧预演 | action: plan、dryRun: true、mode: image，源和目标、帧号、尺寸、源摘要、totalPixels 及目标 files |
| 动画预演 | action: plan、dryRun: true，源和目标、模式、manifest 目标、图片/区域数量、totalPixels、warnings、imagePathPattern 和 plan |
| 批量汇总 | action: batch、dryRun、succeeded、failed、results；每项含 index、exitCode，以及导出/预演结果或失败信息 |
inspect 的 frames 提供 index、稳定 id、durationUnits 和 durationMs；layers 提供原顺序 index、id、name、parentId、kind、自身 visible / opacity、包含父组影响的 renderVisible 和分组不拆分标记 splitAsUnit。clips 包含上述示例字段，playbackFrames 已按播放方向展开。时长规则见动画 JSON 参考。
sourceSha256 是实际读取的源文件内容摘要。动画预演的源摘要位于 plan.source.sha256；plan 包含图片尺寸、区域、轨道和动画，可用 plan.tracks 查看实际拆分单元。正式图片路径为 builds/<buildId>/<image.path>；预演未渲染图片，不提供图片 SHA-256 或 buildId，不能将 plan 当作已发布清单使用。
动画清单
manifest.json 使用 schemaVersion: 1：
| 字段 | 含义 |
|---|---|
schemaVersion / cliVersion / mode | 清单格式版本、CLI 版本和导出模式（frames / sheet） |
kind / buildId | 固定标识 resprite-animation-export 和构建内容摘要；保留原值，不自行修改 |
source | 原工程文件名 name 和实际读取内容的 sha256，不含绝对源路径 |
canvas / frameRate / durationScale | 原画布尺寸、FPS、时长倍率尺度（1000） |
images | 图片 path（相对清单目录，使用 /）、尺寸和 sha256 |
regions | 图片索引、图层单元、源帧号、稳定帧 ID、区域坐标及尺寸、durationUnits 和 durationMs |
tracks | 图层单元及按源帧顺序排列的区域索引；layerIds: null 表示合成全部可见图层，数组列出参与该单元的图层 ID |
animations | 片段 ID、原名称、方向和各轨道的播放区域索引；无片段时提供 id: null、名称为 timeline 的动画 |
片段 ID 是其首帧 ID，也可用于 --clip-id；自动生成的 timeline 没有可供选择的片段 ID。未归属片段的帧仍在顶层 tracks 中。
精确时长为 durationUnits × 1000 / (durationScale × frameRate) 毫秒，当前等于 durationUnits / frameRate。跨平台导出不保证 PNG 字节摘要一致。
加载步骤及带解释的摘录见读取导出结果。清单包含完整性校验，不支持手工修改。
限制
| 项目 | 当前限制 |
|---|---|
| 输入 | 仅磁盘上已保存的 .resprite，不读取未保存的编辑内容 |
| 配置 | 文件最大 1 MiB，包含 1–100 个任务 |
| 输出尺寸 | 每张图片每边最多 16,384 像素，每个任务合计最多 16,777,216 输出像素；单帧模式也适用 |
| 输出数量 | 每个任务最多 100,000 张图片 |
| 执行时间 | 整次调用最多 120 秒，包括批量全部任务 |
超过输出预算会在渲染前返回退出码 2；检查工程不受输出像素预算限制。当前不支持裁切、缩放、任意帧范围、按名称筛选图层、紧密排列图集、增量构建或 watch。旧构建不会自动清理，注意输出目录维护。