Skild Art CLI（skild-art-cli）
<!-- BUILD_INFO:START -->
> 本 skill 随附版本：version 0.3.4 · commit 0940e3e-dirty · built 2026-09-20T08:23:55Z
>
> 建议让所安装 CLI 与本 skill 的版本保持一致。运行 skild-art-cli version，若输出的
> commit 与上面不一致，说明 skill 与 CLI 可能来自不同版本，命令用法与实际行为可能对不上，
> 请重新安装匹配版本（见 scripts/install.md）。
<!-- BUILD_INFO:END -->
skild-art-cli 的使用指南。当前版本支持的子命令与选项以 skild-art-cli --help 和
skild-art-cli <子命令> --help 为准。
它是什么：Skild Art 平台官方 CLI，可通过命令行或自动化工具操作画布、生成图片。
输出使用 {ok:true,data} / {ok:false,error} JSON，便于脚本解析。
先做五件事：
1. 装 CLI：见 scripts/install.md（从官方 CDN 按平台安装到 ~/.skild-art/）。
2. 登录（两步）：skild-art-cli auth login 打印授权信息后立即返回 → 把输出里的 user_code 展示给用户去页面核对确认 → skild-art-cli auth login --resume 完成。流程与字段见 concepts/auth-and-domain.md。
3. 看积分余额与等级：skild-art-cli info 记下 user.score（积分余额）与 level（会员等级）——生成任务要花积分，余额不足任务会以 insufficient_credit 失败；等级决定能用哪些模型。见 commands/info.md。
4. pin 默认画布：skild-art-cli project use --project-id <projectId>，之后 canvas/生图命令省略画布参数即用它。见 commands/project.md。
5. 管理你要用的模型：先 skild-art-cli model list --type image 看可选模型（展示名 displayName + id/modelId）与等级门槛，再用 skild-art-cli model use --type <type> --model <model> 把常用类型（text-to-image / image-editing / text-to-video / image-to-video）pin 成默认（<model> 可用展示名/id/modelId/modelName 任一）。pin 之后生图/图片编辑/视频生成省略 --model 即自动用对应默认；用 skild-art-cli info（defaultModels 字段）查看已 pin 的默认。见 commands/model.md 与 examples/model/pick-model.md。
核心概念：
- project = 画布（一张无限画布），是 Skild Art 里的基本工作单位。project use 把它 pin 为当前默认。
- element / node = 画布节点（图片/视频/文本），生图作用在节点上。
- model 分 text-to-image/image-editing（supportedTypes 含 "text-to-image"/"image-editing"），有会员等级门槛（level）。用 model use --type <type> --model <model> pin 默认模型后，生图生视频可省略 --model；指定模型处均接受展示名/id/modelId/modelName 任一。
- 生图是异步任务：命令返回 taskIds，用 task wait 轮询到终态取产物。
- 连续改图复用节点：生图返回的 elementId 就是产图节点，出图后直接把它作为下一轮 canvas image generate --ref-element 的值即可链式迭代，不要下载到本地再上传建新节点（迭代时建议 --num 1）。见 commands/canvas-image-generate.md。
- 优先用 pin 的默认模型：做图/改图时省略 --model，让 CLI 按场景取对应类型的默认（无 --ref-element 取 text-to-image、有则取 image-editing），不要每次自己挑一个模型硬编码进命令。model use 在 pin 时已校验能力，"image-editing" 默认必然支持改图。遇到 no model specified and no default pinned for <type> 就按 hint 补一次 pin，而不是改成每次传 --model；显式 --model 留给用户点名模型或有意对比的场景。见 commands/canvas-image-generate.md。
文档地图
| 主题 | 文件 |
|---|---|
| 安装 / 更新 CLI | scripts/install.md |
输出契约（{ok,data}、错误 type/code、退出码、--log-level、时间与时区） |
concepts/output-contract.md |
| 登录与账号隔离（浏览器授权、不影响网页会话） | concepts/auth-and-domain.md |
模型积分定价（pricing 怎么读、生成消耗估算） |
concepts/model-pricing.md |
新建节点自动布局（数据流左→右、不重叠、--x/--y） |
concepts/node-layout.md |
图片处理命令的源图与结果节点（upscale / matting / retouch / bg-replace / expand / recolor / remove / text-extract / text-edit 共用：源二选一、--element-id 语义翻转、--wait 语义、取产物 URL、结果节点命名与 --name；同步的 crop / grid-split 只共用前两项）。异步任务的共用保证（taskIds 非空、--wait 参数前置校验、本地源图解码校验、失败回收空节点）对 image generate / video generate 同样适用；积分消耗（哪些命令扣积分、图片处理命令的硬编码单价、余额查看与对账、insufficient_credit 处置入口） |
concepts/image-op-source.md |
| 上传文件限制（asset upload / canvas element upload 的格式与大小校验） | concepts/upload-limits.md |
auth（login / logout / status） |
commands/auth.md |
info（用户信息 + 等级 + 积分余额与来源 + 默认项目；别名 whoami） |
commands/info.md |
project（create / list / get / use） |
commands/project.md |
canvas（资源树：element、connection、image、video） |
commands/canvas.md |
model（list / get / use：可选模型、参数与默认模型） |
commands/model.md |
canvas image generate（生图：校验 / 参考图 / prompt / 建节点 / 等级 / 默认模型） |
commands/canvas-image-generate.md |
canvas image upscale（高清放大：本地文件或画布图片节点放大到 2k/4k/8k） |
commands/canvas-image-upscale.md |
canvas image matting（智能抠图：本地文件或画布图片节点去背景） |
commands/canvas-image-matting.md |
canvas image retouch（AI 精修：整图画质/观感优化，不改尺寸） |
commands/canvas-image-retouch.md |
canvas image grid-split（宫格切分：同步裁图并创建宫格节点） |
commands/canvas-image-grid-split.md |
canvas image ecom-main（按平台规则生成电商主图） |
commands/canvas-image-ecom-main.md |
canvas image model-fit（服饰模特试穿：参考图或文字描述） |
commands/canvas-image-model-fit.md |
canvas image bg-replace（背景替换：参考图或文字描述） |
commands/canvas-image-bg-replace.md |
canvas image expand（AI 扩图：按目标比例或逐边边距向外补全画面） |
commands/canvas-image-expand.md |
canvas image crop（图片裁剪：同步按矩形或比例裁剪，直接返回产物地址） |
commands/canvas-image-crop.md |
canvas image recolor（产品换色：prompt 描述目标色，保持材质/构图） |
commands/canvas-image-recolor.md |
canvas image remove（AI 消除：快捷枚举 watermark/logo/text 或自然语言描述） |
commands/canvas-image-remove.md |
canvas image text-extract（提取文字：产出定位图，供 text-edit 消费） |
commands/canvas-image-text-extract.md |
canvas image text-edit（编辑文字：原图 + 定位图，替换或删除文字） |
commands/canvas-image-text-edit.md |
canvas element upload（上传图片/视频建节点） |
commands/canvas-element-upload.md |
asset（list / get / delete / folder create / folder list / folder delete / upload / download） |
commands/asset.md |
task（get / batch / wait + 状态枚举） |
commands/task.md |
| 常见场景（每 case 一文件，可直接复制执行） | examples/README.md |
全局选项
| 选项 | 说明 |
|---|---|
--log-level debug\|info\|warn\|error |
stderr 分级诊断日志，默认 error。排查失败时可临时使用 debug；也可设置 SKILD_ART_LOG_LEVEL。 |
--max-elements <N> |
画布元素数阈值，默认 100。当画布元素数 ≥ 该值时，project use / info / canvas element list 输出会包含 hint 软提醒。设为 0 关闭提醒；也可设置 SKILD_ART_MAX_ELEMENTS。 |
--min-score <N> |
积分余额阈值，默认 0 关闭（各模型积分单价不同，CLI 不预设阈值）。info 输出时若积分低于该值，hint 会追加低余额提醒（生成任务消耗积分，余额不足任务会以 insufficient_credit 失败）。比较的是扣费账户上的可用积分，取不到扣费账户时退回总积分 user.score。也可设置 SKILD_ART_MIN_SCORE。 |
配置与凭证默认存于 ~/.skild-art/；需要隔离多个账号时，可用 SKILD_ART_CONFIG_DIR 指定其它目录。
