cawcut-generate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CawCut Generate

Generate images and videos via CawCut official node capabilities. Wraps

cawcut generate

. Always checks the live App catalog for a similar published App before generating, and hands off to

cawcut-app-run

when one is a good fit.

Skill files are English-only.

SKILL.md

and

references/

must not contain Chinese or other non-English prose (including YAML

description

trigger phrases). Match the user's language only in live replies via

reply_language

通过CawCut官方节点功能生成图像和视频。封装

cawcut generate

命令。在生成前始终检查实时应用目录是否存在相似的已发布应用，若匹配度高则转交至

cawcut-app-run

处理。

技能文件仅支持英文。

SKILL.md

和

references/

目录下不得包含中文或其他非英文文本（包括YAML中的

description

触发短语）。仅通过

reply_language

在实时回复中匹配用户使用的语言。

Step 0 — Bootstrap

步骤0 — 初始化引导

Run bootstrap as a silent guardrail, not as a user-facing phase.

At most once per AI session. If any
```
cawcut
```
command has already succeeded in this AI session, skip all bootstrap checks and continue.
Use only one explicit check command:
```
cawcut upgrade check --json
```
.
- Do not also run
```
cawcut --version
```
  ,
```
command -v cawcut
```
  , or
```
cawcut auth status
```
  .
- If
```
"update_available": true
```
  , run
  cawcut upgrade
  yourself via Bash (do not ask the user to type it). It refreshes CLI + skills. After it succeeds, continue this skill from Step 1 — do not stop or ask the user to re-invoke.
- If
```
"ahead_of_registry": true
```
  (local
```
current
```
  is newer than npm
```
latest
```
  ), continue without upgrading. This usually means a local/dev build; do not ask the user to downgrade or run
```
cawcut upgrade
```
  .
- If the check fails because
```
cawcut
```
  is missing, ask the user to install the CLI via npm (external users — no git clone or repo
```
./setup
```
  ):
  bash
```
npm install -g @ubnt/cawcut
```
  After install succeeds, continue bootstrap; auth is handled in step 4 below.
- For other check failures, continue and mention the warning only if a later CLI command fails.
Do not print "bootstrap checks passed" after bootstrap — move directly to Step 1 (or, under the bare-invoke exception, straight to asking what to generate).
Let the first real command (
```
cawcut app list --json
```
,
```
cawcut capabilities list --models --json --capability <cap>
```
, or
```
cawcut generate
```
) validate auth. If it fails with token/auth errors (including
```
Token expired
```
), run
cawcut auth login
yourself via Bash — do not ask the user to type it. Briefly tell the user a browser tab will open for OAuth consent; wait for login to finish, then retry the command that failed once. Only escalate to the user if login fails (denied, timeout, port conflict).
This skill's references (
```
references/troubleshooting.md
```
,
```
references/models.md
```
) live under the base directory printed at the top of this skill body —
```
Read
```
them directly at
```
<base_dir>/references/<file>.md
```
. Do not
```
find
```
/
```
grep
```
to locate them; that base directory can be a symlink that a plain
```
find <dir>
```
silently fails to traverse.
Structured user-ask tool (check every session). In Claude Code, use AskUserQuestion
for every enumerable choice. In Cursor, use AskQuestion
. If either tool is in your allowed-tools list, you must use it for all enumerable decisions in this skill — App vs official generation, capability/mode, model pick, Phase A/B settings, enum
```
--param
```
values, media source, upload recovery — unless overflow forces a numbered text table for that batch only (see Interactive selection). Never default to a numbered text menu while
```
AskUserQuestion
```
/
```
AskQuestion
```
is available and the option count fits. A user declining one such call is not grounds to stop using it for the next decision — see Interactive selection's opening rule for how to read the decline message.

将初始化引导作为静默防护机制运行，而非面向用户的流程阶段。

每个AI会话最多执行一次。若本次AI会话中已有
```
cawcut
```
命令执行成功，则跳过所有初始化检查，直接继续后续流程。
仅使用一个明确的检查命令：
```
cawcut upgrade check --json
```
。
- 请勿同时运行
```
cawcut --version
```
  、
```
command -v cawcut
```
  或
```
cawcut auth status
```
  。
- 若返回
```
"update_available": true
```
  ，通过Bash自行运行
  cawcut upgrade
  （无需让用户手动输入）。该命令会刷新CLI及技能。执行成功后，从步骤1重新开始本技能流程，请勿中断或要求用户重新调用。
- 若返回
```
"ahead_of_registry": true
```
  （本地
```
current
```
  版本比npm
```
latest
```
  版本新），则无需升级，直接继续。这种情况通常意味着使用的是本地/开发版本，请勿要求用户降级或运行
```
cawcut upgrade
```
  。
- 若因
```
cawcut
```
  未安装导致检查失败，请要求用户通过npm安装CLI（外部用户请勿使用git克隆或仓库
```
./setup
```
  脚本）：
  bash
```
npm install -g @ubnt/cawcut
```
  安装成功后，继续初始化引导；认证将在下方步骤4处理。
- 若出现其他检查失败情况，可继续流程，仅当后续CLI命令失败时再向用户提示警告信息。
初始化引导完成后，请勿打印「初始化检查通过」，直接进入步骤1（或在裸调用例外场景下，直接询问用户需要生成的内容）。
让第一个实际命令（
```
cawcut app list --json
```
、
```
cawcut capabilities list --models --json --capability <cap>
```
或
```
cawcut generate
```
）验证认证状态。若因令牌/认证错误（包括
```
Token expired
```
）失败，通过Bash自行运行
cawcut auth login
——无需让用户手动输入。简要告知用户将打开浏览器标签页进行OAuth授权；等待登录完成后，重试一次失败的命令。仅当登录失败（授权拒绝、超时、端口冲突）时，再将问题提交给用户处理。
本技能的参考文档（
```
references/troubleshooting.md
```
、
```
references/models.md
```
）位于本技能正文顶部显示的基础目录下——直接通过
```
<base_dir>/references/<file>.md
```
读取这些文档。请勿使用
```
find
```
/
```
grep
```
命令查找它们；该基础目录可能是符号链接，普通
```
find <dir>
```
命令可能无法遍历。
结构化用户询问工具（每次会话必查）。在Claude Code中，对所有可枚举选项使用**
```
AskUserQuestion
```
工具。在Cursor中，使用
```
AskQuestion
```
工具。若你的可用工具列表中包含上述任一工具，则在本技能的所有可枚举决策中必须**使用该工具——包括应用与官方生成的选择、功能/模式、模型选择、A/B阶段设置、枚举
```
--param
```
值、媒体源、上传恢复等——除非选项数量过多，导致该批次只能使用编号文本表格（参见交互式选择规则）。当
AskUserQuestion
/
AskQuestion
可用且选项数量适配时，绝不要默认使用编号文本菜单。用户拒绝某次工具调用，并不意味着后续决策可以停止使用该工具——请参考交互式选择的开篇规则解读拒绝信息。

Catalog freshness (mandatory)

目录新鲜度（强制要求）

Source of truth: only the output of a

cawcut app list …

command you run in this user message's turn for the current subject/capability/style. Never treat app names, IDs, counts, or JSON from earlier messages as authoritative — conversation memory is not a catalog. A "no App match" conclusion from a prior user message is never reusable.

Per-user-message rule (highest priority): On every new user message, before writing any reply or calling any other tool, run

cawcut app list --json

first — this is a mechanical step, not a judgment call; do not reason about whether the message "could involve" App matching before running it. The catalog may have changed on the server since the last message (e.g. the user published a new App on the web). The bare-invoke case below is the only content-based exception — do not construct another one by analogy.

Bare-invoke exception (the only content-based skip): If the message is only the skill invocation itself — no prompt, subject, media, or capability mentioned anywhere in it — there is nothing yet to match against any App's name/description, so skip

app list

for this message and ask the user what they want to generate instead (free text; see Workflow step 3's bare-invoke handling). The moment their reply contains real content, it's a new user message — run

app list --json

per the rule above before anything else, no carry-over.

Also re-run Step 1 when any of these is true:

User's tool call (
```
AskUserQuestion
```
/
```
AskQuestion
```
/ menu) was rejected or interrupted and their next message changes subject, capability, or style — treat exactly like a new user message and restart from Step 1, even as a "follow-up" in the same exchange
User switched account, re-logged in, or
```
cawcut auth login
```
just succeeded
User says they published, shared, or created a new App
User asks to refresh or re-list Apps

Skip Step 1 catalog check only when all are true (same user message's turn, same subject/capability/style):

You already ran
```
cawcut app list --json
```
for this user message and completed the smell test (or the user chose official generation after a plausible-match prompt)
User is only tuning settings on the plan already in flight (ratio, resolution, quality, count, duration, "one more", "make it bigger")
Or this turn started from
```
cawcut-app-run
```
handoff where the user already picked "Official generation instead" in this user message (see Decide-once guard in Step 1)

Never skip the per-user-message

app list

across user messages — even if subject, capability, style, and wording are unchanged.

Hard gate: Workflow step 9 runs a pre-flight check immediately before

cawcut generate

— see there.

唯一可信来源：仅以你在本次用户消息回合中针对当前主题/功能/风格运行

cawcut app list …

命令的输出为准。绝不要将早期消息中的应用名称、ID、数量或JSON数据视为权威信息——对话记忆不能替代目录。之前用户消息回合得出的「无匹配应用」结论不可复用。

每条用户消息规则（最高优先级）：在每条新用户消息到来时，在撰写任何回复或调用其他工具之前，必须先运行

cawcut app list --json

——这是机械步骤，而非主观判断；请勿在运行前判断消息是否「可能涉及」应用匹配。自上次消息以来，服务器端的目录可能已发生变化（例如用户在网页端发布了新应用）。以下裸调用例外是唯一基于内容的例外情况——请勿类推其他例外。

裸调用例外（唯一可跳过的内容场景）：若消息仅包含技能调用本身——未提及任何提示语、主题、媒体或功能，则暂时没有可与应用名称/描述匹配的内容，因此可跳过本次消息的

app list

查询，直接询问用户需要生成的内容（自由文本；参见工作流步骤3的裸调用处理）。一旦用户的回复包含实际内容，即视为新用户消息——必须先运行

app list --json

，再进行其他操作，无例外。

当出现以下任一情况时，重新运行步骤1：

用户的工具调用（
```
AskUserQuestion
```
/
```
AskQuestion
```
/菜单）被拒绝或中断，且用户下一条消息更改了主题、功能或风格——完全视为新用户消息，从步骤1重新开始，即使是同一场对话中的「后续请求」
用户切换账户、重新登录，或
```
cawcut auth login
```
刚刚成功
用户表示已发布、共享或创建了新应用
用户要求刷新或重新列出应用

仅当以下所有条件满足时（同一条用户消息回合、同一主题/功能/风格），才可跳过步骤1的目录检查：

你已针对本次用户消息运行
```
cawcut app list --json
```
并完成初步匹配检查（或用户在匹配提示后选择了官方生成）
用户仅针对当前执行中的计划调整设置（比例、分辨率、质量、数量、时长、「再生成一个」「放大尺寸」等）
或本次回合是从
```
cawcut-app-run
```
转交而来，且用户在本次用户消息中已选择「改用官方生成」（参见步骤1中的「一次决策防护」）

绝不要跨用户消息跳过每条用户消息必做的

app list

查询——即使主题、功能、风格和措辞完全相同。

硬性检查：工作流步骤9在

cawcut generate

执行前会运行预检——详见该步骤说明。

Step 1 — Check the App catalog first (before every

cawcut generate

call)

步骤1 — 优先检查应用目录（在每次

cawcut generate

调用前）

Decide-once guard (same user message only) — skip this entire step if this turn started because

cawcut-app-run

already ran the per-user-message

app list

in this user message and decided there's no matching App, or the user picked "Official generation instead" there. Go straight to capability/model discovery below; do not re-run

app list

to double-check a decision already made in this user message.

Otherwise, apply the Per-user-message rule, Bare-invoke exception, and Skip Step 1 checklists in Catalog freshness above. If you have not yet run

cawcut app list --json

for this user message and the bare-invoke exception doesn't apply, execute Step 1 below — do not reuse a prior message's list or "no match" conclusion.

Run
```
cawcut app list --json
```
without
```
--schema
```
(lean JSON: name, description, credits, source — no
```
input_schema
```
; token-efficient smell test).
Check whether any App's
```
name
```
/
```
description
```
clearly overlaps with the user's ask. This is a quick smell test, not full scoring —
```
cawcut-app-run
```
owns the formal scoring rubric and re-checks properly once you hand off.
No plausible match — continue below with raw generation. Do not mention the catalog check to the user.
Plausible match — always call
```
AskUserQuestion
```
/
```
AskQuestion
```
first (numbered text only if the tool is unavailable):
```
Found a published App that does this: <name> — <description> (N credits).
1. Use <name>
2. Continue with official generation
```
- User picks the App → hand off to cawcut-app-run
  with that App name already decided. It skips catalog scoring/menus (its Step -1) and goes straight to
```
describe
```
  + tables + input menu; it still live-fetches
```
app list --json
```
  in that turn when it needs the internal app ID.
- User picks official generation → continue this skill's flow below. Do not ask about the catalog again for the rest of this turn.

一次决策防护（仅适用于同一条用户消息）——若本次回合是因

cawcut-app-run

已针对本次用户消息运行

app list

并判定无匹配应用，或用户已选择「改用官方生成」而启动，则跳过整个步骤1。直接进入下方的功能/模型发现流程；请勿重新运行

app list

以重复验证本次用户消息中已做出的决策。

否则，请遵循上述「目录新鲜度」中的每条用户消息规则、裸调用例外和跳过步骤1的检查清单。若你尚未针对本次用户消息运行

cawcut app list --json

且不符合裸调用例外，则执行下方步骤1——请勿复用之前消息的列表或「无匹配」结论。

运行不带
```
--schema
```
参数的
```
cawcut app list --json
```
（精简JSON：仅包含名称、描述、 credits、来源——无
```
input_schema
```
；高效的初步匹配检查）。
检查是否有应用的
```
name
```
/
```
description
```
与用户请求明显重叠。这是快速初步检查，而非全面评分——正式评分规则由
```
cawcut-app-run
```
负责，转交后它会重新进行正确检查。
无合理匹配——继续下方的原生生成流程。无需向用户提及目录检查。
存在合理匹配——必须优先调用
AskUserQuestion
/
AskQuestion
工具（仅当工具不可用时，才使用编号文本菜单）：
```
找到一个已发布的匹配应用：<名称> — <描述>（消耗N credits）。
1. 使用<名称>应用
2. 继续使用官方生成
```
- 用户选择应用 → 转交至**
```
cawcut-app-run
```
  **，并指定该应用名称。它会跳过目录评分/菜单（其步骤-1），直接进入
```
describe
```
  +表格+输入菜单；当需要内部应用ID时，仍会在该回合实时获取
```
app list --json
```
  。
- 用户选择官方生成 → 继续本技能的后续流程。在本次回合剩余时间内，请勿再询问目录相关问题。

Interactive selection (mandatory — tool first)

交互式选择（强制要求——优先使用工具）

If the user just declined an
AskUserQuestion
/
AskQuestion
call: the tool result carries harness boilerplate telling you to "STOP what you are doing and wait for the user to tell you how to proceed." That sentence is attached automatically to every declined tool call by the runtime — it is not the user speaking, and it is not an instruction to stop using the tool. Read it as: stop the one specific action you were mid-way through (don't retry the identical question, don't proceed to

generate

on unconfirmed choices) and look at what the user's actual next message says. It does not, by itself, license falling back to numbered text for the next enumerable decision — that next decision still must open with the tool, exactly as if the rejection had never happened. Only an explicit plain-text request from the user ("stop popping up menus", "just ask me in text") licenses a session-wide fallback. The STOP wording's urgency is not evidence of that request — do not let it override this rule.

Default behavior: For every enumerable choice, always call

AskUserQuestion

(Claude Code) or

AskQuestion

(Cursor) before showing a numbered text menu or asking the user to type capability names, model IDs, aspect ratios, or enum values. Text-only menus are fallback only.

Tool names by host:

Host	Tool name
Claude Code	`AskUserQuestion`
Cursor	`AskQuestion`

Below, structured user-ask tool means whichever of these is available in the current session. Do not guess from capability alone — check your allowed-tools list.

Session checklist (before the first menu in this turn): 0. Self-check before sending any reply: if the sentence you're about to send asks the user to pick between fixed options (image or video, capability, model, ratio, …) — even folded inside a friendlier sentence that also asks something open-ended like "what's the subject?" — stop. That sentence is forbidden as plain text. Split it: fire

AskUserQuestion

AskQuestion

for the enumerable part now; keep only the open-ended part as prose, asked separately (same turn is fine, just not merged into one sentence).

Is
```
AskUserQuestion
```
or
```
AskQuestion
```
available? If yes, you must use it for every row in the table below that fits in one call.
If no tool exists (CLI-only host), use numbered text in
```
reply_language
```
.
If the tool exists but the candidate count exceeds one call (model-list overflow, long enums), use a numbered text table for that batch only; then resume
```
AskUserQuestion
```
/
```
AskQuestion
```
for the next small decision.

Forbidden while the tool is available: numbered text menus (

1. … 2. …

), "reply with the number or name", or asking the user to type capability names, model IDs, or enum values from memory.

Step	Always use structured user-ask tool for
Image vs video	Output type
Capability / input mode	text-to-image, image-to-image, text-to-video, …
Model	Each plan-visible model (mark default in label) — see Model-list overflow (Rule 10, Phase A Choice 2) when the candidate count exceeds what the tool can hold
Settings gate	Defaults / change model / customize settings (Phase A, single-select)
Settings — customize	One structured user-ask tool call, one question per axis from the current model's live schema (Phase B) — never collapse multiple axes into one single-select pick
Each enum `--param`	Every `options` value from JSON
Media	Same three-way branch as `cawcut-app-run`

Fallback only: Use numbered text menus in

reply_language

only when

AskUserQuestion

AskQuestion

is unavailable, or when option count/structure exceeds what the tool supports for that batch (model-list overflow, long enum lists). Falling back for one decision does not exempt the next small decision — re-check and use the tool again when it fits. UX rule 10 and Workflow step 7 text examples are fallback shape only — not the default when the tool is present. Only ask for free-text prompt content or a URL/path after the user picks a Custom / URL / path branch.

若用户刚刚拒绝
AskUserQuestion
/
AskQuestion
调用：工具结果会包含运行时自动添加的 boilerplate 文本，提示你「立即停止当前操作，等待用户指示下一步」。这句话是运行时自动附加到所有被拒绝的工具调用中的——并非用户发言，也不是停止使用工具的指令。请将其解读为：停止你正在进行的某一项特定操作（不要重试相同问题，不要在未确认选项的情况下执行

generate

），查看用户实际的下一条消息内容。这绝不意味着后续可枚举决策可以退化为编号文本菜单——下一次决策仍必须优先使用工具，就像从未发生过拒绝一样。只有当用户明确以纯文本请求（如「不要再弹出菜单」「直接用文字问我」）时，才允许在整个会话中退化为文本菜单。STOP提示的紧急性不能作为用户请求的证据——请勿让它覆盖本规则。

默认行为：对于所有可枚举选项，必须优先调用
AskUserQuestion
（Claude Code）或
AskQuestion
（Cursor），再显示编号文本菜单或要求用户输入功能名称、模型ID、宽高比或枚举值。纯文本菜单仅作为备选方案。

各平台对应的工具名称：

平台	工具名称
Claude Code	`AskUserQuestion`
Cursor	`AskQuestion`

下文提到的结构化用户询问工具指当前会话中可用的上述工具之一。请勿仅根据功能猜测，请检查你的可用工具列表。

会话检查清单（本次回合第一个菜单前）： 0. 发送任何回复前自检：若你即将发送的句子要求用户在固定选项中选择（图像或视频、功能、模型、比例等）——即使嵌套在更友好的句子中，同时还包含开放式问题如「主题是什么？」——请立即停止。这种混合句子是禁止的。请拆分：立即针对可枚举部分调用

AskUserQuestion

AskQuestion

；仅保留开放式部分作为文字提问（可在同一回合发送，但请勿合并为一句话）。

```
AskUserQuestion
```
或
```
AskQuestion
```
是否可用？若是，则必须对下表中所有适合单次调用的选项使用该工具。
若无可用工具（仅CLI平台），则使用
```
reply_language
```
对应的编号文本菜单。
若工具可用但候选选项数量超出单次调用限制（模型列表过长、枚举值过多），则仅对该批次使用编号文本表格；之后恢复对下一个小型决策使用
```
AskUserQuestion
```
/
```
AskQuestion
```
。

工具可用时禁止操作：编号文本菜单（

1. … 2. …

）、「回复数字或名称」，或要求用户凭记忆输入功能名称、模型ID或枚举值。

步骤	必须使用结构化用户询问工具的场景
图像 vs 视频	输出类型选择
功能 / 输入模式	text-to-image、image-to-image、text-to-video等
模型	所有可见模型（在标签中标记默认值）——当候选数量超出工具限制时，参见「模型列表溢出」（规则10，阶段A选项2）
设置入口	默认设置 / 更换模型 / 自定义设置（阶段A，单选）
设置——自定义	一次结构化用户询问工具调用，针对当前模型实时 schema 的每个维度单独提问（阶段B）——绝不要将多个维度合并为一个单选选项
每个枚举 `--param`	JSON中的所有 `options` 值
媒体	与 `cawcut-app-run` 相同的三分支选项

仅作为备选方案：仅当

AskUserQuestion

AskQuestion

不可用，或选项数量/结构超出工具支持范围时，才使用

reply_language

对应的编号文本菜单。某一次决策使用备选方案，不免除下一次小型决策使用工具的要求——重新检查，当适用时再次使用工具。UX规则10和工作流步骤7的文本示例仅为备选展示形式——并非工具可用时的默认形式。仅当用户选择自定义/URL/路径分支后，才要求用户输入自由文本提示内容或URL/路径。

UX Rules

UX规则

Be concise. Default output is the result URL(s). Do not dump raw JSON unless debugging.
Always pass
```
--wait
```
— jobs are async, CLI blocks and prints the URL when done.
Always pass
```
--download
```
for image and video generations. The CLI resolves the platform-appropriate downloads folder automatically (
```
~/Downloads
```
on macOS/Linux,
```
%USERPROFILE%\Downloads
```
on Windows) — do not hardcode a path or download the result yourself. Only skip
```
--download
```
if the user explicitly says they only want the URL.
Reply language:
- Bare skill invoke → English. If the user only runs the skill command with no substantive text (e.g.
```
/cawcut-generate
```
  ,
```
cawcut-generate
```
  , or the skill name alone), set
```
reply_language
```
  to English for menus, summaries, and questions.
- Follow the conversation after that. Once the user adds a real request or follow-up in another language, switch
```
reply_language
```
  to match that language for the rest of the session (unless they explicitly ask for English).
- All prose, status summaries, option labels, questions, and recovery guidance use
```
reply_language
```
  .
- Keep CLI commands/flags, model IDs, app IDs, JSON keys, URLs, and raw error codes in English.
- Do not paste raw English CLI output as the user-facing answer; summarize it in
```
reply_language
```
  .
Do not call CawCut HTTP APIs with curl — the CLI handles auth, media upload, and token refresh.
Template first — see Step 1 (Check the App catalog first) above; it runs for every request, not just ones that sound template-like. When the user picks the offered App, follow
```
cawcut-app-run
```
's disclose app on selection rule — name the App, show metadata + inputs tables, then collect inputs via menus; never say only "this app" without details.
Staged discovery (required) — never fetch all capabilities with full schema in one shot (
```
cawcut capabilities list --models --schema --json
```
without
```
--capability
```
dumps ~100KB and may be truncated). Use this sequence instead:
1. After capability is known →
```
cawcut capabilities list --simple --capability <cap>
```
  (or
```
--models --json --capability <cap>
```
  ) to pick a model.
2. After model is chosen →
```
cawcut capabilities list --models --schema --json --capability <cap> --model "<model_id>"
```
  for that model's parameters only. Forbidden: writing Python/shell scripts to parse capabilities JSON; use CLI
```
--capability
```
  ,
```
--model
```
  , or
```
--simple
```
  filters (or a one-line
```
jq
```
  if the host already has it).
Choice-first — if the user did not specify enough information, always call
```
AskUserQuestion
```
/
```
AskQuestion
```
first (numbered text only when the tool is unavailable or overflow applies). Fixed or enumerable parameters must always be clickable menus — the user picks options; never types parameter names, capability names, model IDs, or enum values from memory:
- image or video output
- text-only, image input, video input, audio input, or omni input
- model options from live discovery, with the BE default first
- enum/options/ranges from the selected model's parameters
No unbounded preference questions — never ask only "Any preference on resolution, aspect ratio, quality, or number of images?". Always show concrete options from the live schema via
```
AskUserQuestion
```
/
```
AskQuestion
```
(per Interactive selection above), plus "use default" and "custom" when customization is possible.
Settings menu before running — once prompt/media/capability/model are known, resolve settings in two phases. Image and video use the same shape. Precedence: always use
```
AskUserQuestion
```
/
```
AskQuestion
```
for Phase A (one call: defaults / change model / customize) and Phase B (one batched call, one question per axis) when the tool is present — do not merge into a single numbered text block. Workflow step 7 combined text examples are fallback rendering only (tool unavailable, or overflow per model-list / long enum caps).

Phase A — gate (one
AskUserQuestion
/
AskQuestion
call):
- Choice 1: run now with schema defaults on the current model (show the default values).
- Choice 2: change model — list every model from
```
cawcut capabilities list --simple --capability <cap>
```
  (or the lean JSON equivalent); mark
```
"default": true
```
  . Model-list overflow:
```
AskUserQuestion
```
  /
```
AskQuestion
```
  typically caps at ~2–4 options per question; when the model count for this capability exceeds that, present a numbered text table (columns:
```
#
```
  , name, default marker, key specs) instead of an unnumbered list, and tell the user they can reply with either the number or the model name — this mirrors
```
cawcut-app-run
```
  's App-picker overflow (Interactive selection rule 7). Apply the same numbered-table treatment to any other live-schema-driven candidate list (models, capabilities, or a long
```
--param
```
  enum) that exceeds the cap. On pick, re-fetch schema for the new model (
```
--capability <cap> --model "<id>" --schema --json
```
  ), then re-enter Phase A for the new model.
- Choice 3: customize settings — proceed to Phase B.
Phase B — customize (one batched
AskUserQuestion
/
AskQuestion
call, one question per axis): build the axis list from the current model's live schema only (Step 5) — different models expose different axes (e.g. GPT Image 2 has
```
ratio
```
/
```
resolution
```
/
```
quality
```
/
```
num_images
```
; Kling 3.0 Pro has
```
duration
```
/
```
aspect_ratio
```
/
```
generate_audio
```
instead, no
```
resolution
```
). For every cost- or visual-impacting axis present (aspect ratio, resolution/size, quality, duration, image count, audio on/off, …), ask one question with its own options, first option always "use default (show value)".
Never fold two different axes into one single-select pick. The point of Phase B is that the user can independently touch any subset of axes while the rest silently default — forcing one exclusive choice among axes (e.g. "customize duration" vs. "customize ratio" as alternatives) drops the unpicked axes without ever showing them.
```
AskUserQuestion
```
/
```
AskQuestion
```
caps at 4 questions per call. If the current model exposes more than 4 cost/visual-impacting axes, batch the 4 most impactful first; the rest still fall under Rule 12 (advanced/non-impacting params stay defaulted without asking).
A custom numeric value (e.g. a duration inside
```
duration_range
```
) is an option within that axis's own question, not a separate top-level choice.

For common settings (each is its own Phase B question/axis):

Aspect ratio: list every
```
aspect_ratios
```
value or the selected model's ratio/aspect_ratio parameter
```
options
```
; mark the default. If the schema has no aspect-ratio field, do not invent a
```
--param
```
.
Resolution/size/quality/style: list
```
options
```
from the matching parameter; mark defaults. For min/max ranges, show default, min, max, and "custom within range".
Image count: offer
```
1
```
,
```
2
```
,
```
3
```
,
```
4
```
with
```
1
```
marked default unless the schema says otherwise. If the model has
```
num_images
```
, use
```
--param num_images=N
```
; otherwise use
```
--loop N
```
.
Video duration: list
```
durations
```
; for
```
duration_range
```
, show default, min, max, and custom seconds within range.
Boolean toggle (e.g.
```
generate_audio
```
): offer On (default) / Off as the two options for that axis's question whenever the parameter description flags a cost/time effect (Rule 14).

Do not ask for advanced params the user did not mention unless they are required or clearly cost/visual-impacting. Use defaults from the live model schema for the rest.
Session reuse — after the first generation, capture
```
workflow_id
```
from the JSON result. For every follow-up
```
generate
```
in the same session, pass
```
--workflow-id <id>
```
— including when capability or model changes (e.g. text-to-image → image-to-image → text-to-video). Each call appends new generation nodes to that workflow (history is preserved). Omit
```
--workflow-id
```
only when the user explicitly wants a new project or the request is clearly unrelated to this session.
Multi-image / multi-candidate (
--loop
) —
```
loop
```
is how many parallel generation nodes to add in this request (max 4). It is not how many times the workflow runs overall. If the user wants more than 4 candidates (e.g. "5 candidates"), do not call CLI; reply that the model/platform supports at most 4 parallel candidates. For
```
N≤4
```
: if the model schema has
```
num_images
```
and the user wants multiple images in one API call, prefer
```
--param num_images=N
```
; otherwise use
```
--loop N
```
(works for image and video). Credits and time scale roughly with
```
loop
```
(and with
```
num_images
```
per node when set).
Never assume models or params from training data — available models depend on the user's plan. Always discover via CLI first.
Never use illustrative media examples as actual inputs. When
```
--image
```
,
```
--video
```
, or
```
--audio
```
is required, any example URL or path in SKILL.md,
```
references/
```
, model schema, or docs (including
```
cdn.example.com
```
,
```
@/path/to/file
```
placeholders) is hint only — not a usable resource. Do not pass them to the CLI unless the user explicitly provided that exact file or URL in this conversation.
Media input — menu, not invented assets — always present the three-way branch via
```
AskUserQuestion
```
/
```
AskQuestion
```
per Interactive selection (above). The numbered list below is text fallback shape only. Same bar as
```
cawcut-app-run
```
. For required media, offer: 1) file already in chat 2) HTTPS URL 3) local path. Map the choice to
```
--image
```
/
```
--video
```
/
```
--audio
```
yourself. If required media is missing, show this menu and wait — do not run with fabricated or placeholder examples.
Don't pre-inspect local media before attempting
generate
— do not shell out to
```
ls
```
/
```
file
```
/
```
sips -g pixelWidth/pixelHeight
```
(or similar) to check a local file's size or dimensions before running. Attempt
```
cawcut generate
```
directly; if upload pre-flight fails, the CLI's error already reports the exact size/dimension and its limit — act on that error (see "Upload limits" above / Errors below), not on a manual inspection you ran first.

简洁明了。默认输出为结果URL。除调试场景外，请勿输出原始JSON。
始终传递
```
--wait
```
参数——任务为异步执行，CLI会阻塞直至任务完成并打印结果URL。
图像和视频生成时始终传递
```
--download
```
参数。CLI会自动适配平台对应的下载文件夹（macOS/Linux为
```
~/Downloads
```
，Windows为
```
%USERPROFILE%\Downloads
```
）——请勿硬编码路径或自行下载结果。仅当用户明确表示只需要URL时，才跳过
```
--download
```
参数。
回复语言：
- 裸技能调用→英文。若用户仅运行技能命令而无实质性文本（例如
```
/cawcut-generate
```
  、
```
cawcut-generate
```
  或仅技能名称），则将
```
reply_language
```
  设置为英文，用于菜单、摘要和提问。
- 后续跟随对话语言。一旦用户用其他语言添加了实际请求或后续内容，则将
```
reply_language
```
  切换为该语言，直至会话结束（除非用户明确要求使用英文）。
- 所有文字内容、状态摘要、选项标签、提问和恢复指导均使用
```
reply_language
```
  。
- CLI命令/参数、模型ID、应用ID、JSON键、URL和原始错误代码保持英文。
- 请勿将原始英文CLI输出直接作为面向用户的回复；请使用
```
reply_language
```
  进行总结。
请勿使用curl调用CawCut HTTP API——CLI会处理认证、媒体上传和令牌刷新。
优先匹配模板——参见上方步骤1（优先检查应用目录）；该步骤针对所有请求运行，不仅是听起来像模板的请求。当用户选择提供的应用时，请遵循
```
cawcut-app-run
```
的选择应用时披露信息规则——明确应用名称，展示元数据+输入表格，再通过菜单收集输入；绝不要只说「这个应用」而不提供详细信息。
分阶段发现（强制要求）——切勿一次性获取所有功能的完整schema（不带
```
--capability
```
参数的
```
cawcut capabilities list --models --schema --json
```
会输出约100KB数据，可能被截断）。请改用以下顺序：
1. 确定功能后 → 使用
```
cawcut capabilities list --simple --capability <cap>
```
  （或
```
--models --json --capability <cap>
```
  ）选择模型。
2. 选定模型后 → 使用
```
cawcut capabilities list --models --schema --json --capability <cap> --model "<model_id>"
```
  获取该模型的参数。 禁止操作：编写Python/Shell脚本解析功能JSON；请使用CLI的
```
--capability
```
  、
```
--model
```
  或
```
--simple
```
  过滤器（若平台已预装jq，可使用单行jq命令）。
优先选择——若用户未提供足够信息，必须优先调用
AskUserQuestion
/
AskQuestion
工具（仅当工具不可用或超出限制时，才使用编号文本菜单）。固定或可枚举参数必须始终为可点击菜单——用户选择选项；绝不要要求用户凭记忆输入参数名称、功能名称、模型ID或枚举值：
- 图像或视频输出类型
- 纯文本输入、图像输入、视频输入、音频输入或全媒输入
- 实时发现的模型选项，默认模型排在首位
- 选定模型参数中的枚举/选项/范围
禁止开放式偏好提问——绝不要只问「对分辨率、宽高比、质量或图像数量有偏好吗？」。必须通过
```
AskUserQuestion
```
/
```
AskQuestion
```
展示实时schema中的具体选项（参见上述「交互式选择」规则），并在支持自定义时提供「使用默认值」和「自定义」选项。
运行前设置菜单——确定提示语/媒体/功能/模型后，分两个阶段确认设置。图像和视频场景使用相同流程。优先级：工具可用时，必须对阶段A（单次调用：默认设置/更换模型/自定义）和阶段B（单次批量调用，每个维度一个问题）使用
```
AskUserQuestion
```
/
```
AskQuestion
```
——请勿合并为单个编号文本块。工作流步骤7的组合文本示例仅为备选展示形式（工具不可用，或因模型列表/长枚举超出限制）。
- 阶段A — 入口（单次
  AskUserQuestion
  /
  AskQuestion
  调用）：
  - 选项1：使用当前模型的schema默认值立即运行（展示默认值）。
  - 选项2：更换模型——列出
```
cawcut capabilities list --simple --capability <cap>
```
    （或等效精简JSON）中的所有模型；标记
```
"default": true
```
    的模型。模型列表溢出：
```
AskUserQuestion
```
    /
```
AskQuestion
```
    通常单次调用最多支持约2–4个选项；当该功能的模型数量超出此限制时，请使用编号文本表格（列：
```
#
```
    、名称、默认标记、关键规格）替代无序列表，并告知用户可回复编号或模型名称——这与
```
cawcut-app-run
```
    的应用选择器溢出处理一致（交互式选择规则7）。对任何其他实时schema驱动的候选列表（模型、功能或长
```
--param
```
    枚举）超出限制的情况，均使用相同的编号表格处理。用户选择后，重新获取新模型的schema（
```
--capability <cap> --model "<id>" --schema --json
```
    ），然后针对新模型重新进入阶段A。
  - 选项3：自定义设置——进入阶段B。
- 阶段B — 自定义（单次批量
  AskUserQuestion
  /
  AskQuestion
  调用，每个维度一个问题）：仅从当前模型的实时schema（步骤5）构建维度列表——不同模型暴露的维度不同（例如GPT Image 2包含
```
ratio
```
  /
```
resolution
```
  /
```
quality
```
  /
```
num_images
```
  ；Kling 3.0 Pro包含
```
duration
```
  /
```
aspect_ratio
```
  /
```
generate_audio
```
  ，无
```
resolution
```
  ）。对于所有存在的成本或视觉影响维度（宽高比、分辨率/尺寸、质量、时长、图像数量、音频开关等），每个维度单独提问，第一个选项始终为「使用默认值（展示值）」。
- 绝不要将两个不同维度合并为一个单选选项。阶段B的核心是用户可独立调整任意维度子集，其余维度自动默认——强制用户在维度间选择互斥选项（例如「自定义时长」vs「自定义比例」作为二选一）会导致未选中的维度被隐藏，用户无法知晓。
- ```
AskUserQuestion
```
  /
```
AskQuestion
```
  单次调用最多支持4个问题。若当前模型暴露的成本/视觉影响维度超过4个，则优先处理影响最大的4个；其余维度仍遵循规则12（高级/无影响参数保持默认，无需询问）。
- 自定义数值（例如
```
duration_range
```
  内的时长）是该维度问题中的一个选项，而非独立的顶级选项。
常见设置（每个设置对应阶段B的一个问题/维度）：
- 宽高比：列出所有
```
aspect_ratios
```
  值或选定模型的ratio/aspect_ratio参数
```
options
```
  ；标记默认值。若schema中无宽高比字段，则请勿自定义
```
--param
```
  参数。
- 分辨率/尺寸/质量/风格：列出对应参数的
```
options
```
  ；标记默认值。对于最小/最大范围，展示默认值、最小值、最大值和「范围内自定义」。
- 图像数量：提供
```
1
```
  、
```
2
```
  、
```
3
```
  、
```
4
```
  选项，默认
```
1
```
  ，除非schema另有规定。若模型支持
```
num_images
```
  参数，则使用
```
--param num_images=N
```
  ；否则使用
```
--loop N
```
  。
- 视频时长：列出
```
durations
```
  ；对于
```
duration_range
```
  ，展示默认值、最小值、最大值和范围内自定义秒数。
- 布尔开关（例如
```
generate_audio
```
  ）：当参数描述标注有成本/时间影响时（规则14），该维度问题提供开启（默认）/关闭两个选项。
除非用户明确提及，否则请勿询问高级参数，仅当参数为必填或明显影响成本/视觉效果时才需询问。其余参数使用实时模型schema的默认值。
会话复用——首次生成后，从JSON结果中捕获
```
workflow_id
```
。在同一会话中的每一次后续
```
generate
```
调用中，传递
```
--workflow-id <id>
```
——即使功能或模型发生变化（例如text-to-image→image-to-image→text-to-video）。每次调用都会追加新的生成节点到该工作流（保留历史记录）。仅当用户明确要求新项目或请求与当前会话明显无关时，才省略
```
--workflow-id
```
。
多图像/多候选（
--loop
）——
```
loop
```
表示本次请求中添加的并行生成节点数量（最大4个）。它不是工作流的总运行次数。若用户想要超过4个候选（例如「5个候选」），请勿调用CLI；回复用户模型/平台最多支持4个并行候选。当
```
N≤4
```
时：若模型schema支持
```
num_images
```
且用户希望单次API调用生成多张图像，则优先使用
```
--param num_images=N
```
；否则使用
```
--loop N
```
（适用于图像和视频场景）。Credits和时间大致与
```
loop
```
（以及每个节点设置的
```
num_images
```
）成正比。
绝不要从训练数据中假设模型或参数——可用模型取决于用户的套餐。始终通过CLI实时发现。
绝不要将示例媒体作为实际输入。当需要
```
--image
```
、
```
--video
```
或
```
--audio
```
参数时，SKILL.md、
```
references/
```
、模型schema或文档中的任何示例URL或路径（包括
```
cdn.example.com
```
、
```
@/path/to/file
```
占位符）仅作为提示——不可用资源。除非用户在本次对话中明确提供了该文件或URL，否则请勿将其传递给CLI。
媒体输入——菜单选择，而非虚构资源——必须通过
```
AskUserQuestion
```
/
```
AskQuestion
```
提供三分支选项（参见上述「交互式选择」规则）。下方编号列表仅为文本备选形式。与
```
cawcut-app-run
```
要求一致。对于必填媒体，提供：1）聊天中已有的文件 2）HTTPS URL 3）本地路径。自行将选择映射到
```
--image
```
/
```
--video
```
/
```
--audio
```
参数。若缺少必填媒体，请展示该菜单并等待——请勿使用虚构或占位符示例媒体运行命令。
运行
generate
前无需预检查本地媒体——请勿执行
```
ls
```
/
```
file
```
/
```
sips -g pixelWidth/pixelHeight
```
（或类似命令）检查本地文件的大小或尺寸。直接尝试
```
cawcut generate
```
；若上传预检失败，CLI错误会准确报告具体大小/尺寸及其限制——根据该错误采取行动（参见上方「上传限制」/下方「错误处理」），而非手动预检查。

Capabilities

功能列表

`--capability`	What it does	Media input
`text-to-image`	Text → image	—
`text-to-video`	Text → video	—
`image-to-image`	Edit / stylize image	`--image` required
`image-to-video`	Animate a still	`--image` required
`omni-to-video`	Any media → video	at least one of `--image` / `--video` / `--audio` required; types may be combined (e.g. avatar image + music audio)

`--capability` 参数	功能说明	媒体输入要求
`text-to-image`	文本转图像	—
`text-to-video`	文本转视频	—
`image-to-image`	编辑/风格化图像	必须提供 `--image`
`image-to-video`	静态图像动效化	必须提供 `--image`
`omni-to-video`	任意媒体转视频	必须提供至少一个 `--image` / `--video` / `--audio` ；可组合多种类型（例如头像图片+音乐音频）

Discover models and parameters (required)

发现模型和参数（强制要求）

Use staged CLI discovery — do not pull full schema for all five capabilities at once.

Step A — pick capability (if not already obvious from the user request):

bash

cawcut capabilities list

Step B — list models for that capability only (after capability is known):

bash

cawcut capabilities list --simple --capability text-to-video

使用分阶段CLI发现——请勿一次性获取所有五个功能的完整schema。

阶段A — 选择功能（若无法从用户请求中明确推断）：

bash

cawcut capabilities list

阶段B — 仅列出该功能的模型（确定功能后）：

bash

cawcut capabilities list --simple --capability text-to-video

or: cawcut capabilities list --models --json --capability text-to-image

或：cawcut capabilities list --models --json --capability text-to-image


Each `--simple` line is `model_id: name` with `(default)` when applicable. Split on the **first** colon only.

**Step C — load parameters for the chosen model only**:

```bash
cawcut capabilities list --models --schema --json --capability text-to-video --model "Seedance 2.0"

This returns a small JSON payload (one capability, one model) with BE-sourced metadata:

```
model_id
```
,
```
name
```
,
```
default
```
```
parameters
```
— names, types, defaults, options, min/max, descriptions
```
aspect_ratios
```
,
```
durations
```
,
```
duration_range
```
when applicable
```
medias
```
— input limits for image/video/audio capabilities (count, roles, and optional per-model
```
limit
```
)

Never run bare

cawcut capabilities list --models --schema --json

(all capabilities) unless the user explicitly asks to browse every capability's full schema at once.

Upload limits (platform): Before uploading local files, CLI loads

GET /developer/config

and validates size/format/dimensions. CLI does not compress. On failure, do not just print the error and stop, and never suggest CawCut Web as a workaround — always call

AskUserQuestion

AskQuestion

first with: (1) compress/resize it for you now via

sips

ffmpeg

and retry automatically, (2) they'll fix it and re-upload, or (3) cancel. Numbered text only if the tool is unavailable. If they pick (1), run the fix command yourself, then retry the upload. See

references/troubleshooting.md

for the exact commands per failure type. Run

cawcut config limits

to show current caps.

Rules:

Only suggest or pass
```
--model
```
values that appear in the JSON for the chosen capability.
Read
```
--param
```
keys and allowed values from that model's
```
parameters
```
(and related fields). Do not invent param names.
Treat BE's
```
"default": true
```
as the source of truth. Each capability should have exactly one default; if none or more than one is present, ask the user to choose from the listed models.
For the default model, omit
```
--model
```
, or pass its
```
model_id
```
explicitly.
Only when live discovery is unavailable and the user still asks to proceed, use fallback defaults: image/image edit =
```
gpt-image-2
```
; video/animate/omni =
```
Seedance 2.0
```
.
Quote
```
model_id
```
values that contain spaces or parentheses.

Human-readable summary (names only, no parameters):

bash

cawcut capabilities list --models

Human-readable summary with parameters (text, not JSON — for a quick look, not for building the table below):

bash

cawcut capabilities list --schema

See

references/models.md

for a short field guide — not a model catalog.


`--simple`输出的每一行格式为`model_id: name`，默认模型会标记`(default)`。仅按**第一个**冒号分割。

**阶段C — 仅加载选定模型的参数**：

```bash
cawcut capabilities list --models --schema --json --capability text-to-video --model "Seedance 2.0"

该命令返回一个小型JSON payload（仅包含一个功能、一个模型），包含后端提供的元数据：

```
model_id
```
、
```
name
```
、
```
default
```
```
parameters
```
——名称、类型、默认值、选项、最小/最大值、描述
适用时提供
```
aspect_ratios
```
、
```
durations
```
、
```
duration_range
```
```
medias
```
——图像/视频/音频功能的输入限制（数量、角色，以及可选的模型专属
```
limit
```
）

绝不要运行裸命令

cawcut capabilities list --models --schema --json

（获取所有功能），除非用户明确要求一次性浏览所有功能的完整schema。

平台上传限制：上传本地文件前，CLI会加载

GET /developer/config

并验证大小/格式/尺寸。CLI不会压缩文件。若上传失败，请勿仅打印错误并停止，也不要建议用户使用CawCut Web作为替代方案——必须优先调用
AskUserQuestion
/
AskQuestion
工具，提供以下选项：(1) 立即通过

sips

ffmpeg

为你压缩/调整大小并自动重试，(2) 用户自行修复后重新上传，(3) 取消。仅当工具不可用时，才使用编号文本菜单。若用户选择(1)，自行运行修复命令，然后重试上传。请参考

references/troubleshooting.md

获取针对不同失败类型的具体命令。运行

cawcut config limits

查看当前限制。

规则：

仅建议或传递选定功能JSON中存在的
```
--model
```
值。
从该模型的
```
parameters
```
（及相关字段）中读取
```
--param
```
键和允许值。请勿自定义参数名称。
将后端的
```
"default": true
```
视为唯一可信来源。每个功能应仅有一个默认模型；若没有或有多个默认模型，请让用户从列出的模型中选择。
对于默认模型，可省略
```
--model
```
参数，或显式传递其
```
model_id
```
。
仅当无法实时发现模型且用户仍要求继续时，使用备选默认值：图像/图像编辑 =
```
gpt-image-2
```
；视频/动效化/全媒 =
```
Seedance 2.0
```
。
若
```
model_id
```
包含空格或括号，请添加引号。

人类可读摘要（仅名称，无参数）：

bash

cawcut capabilities list --models

带参数的人类可读摘要（文本格式，非JSON——用于快速查看，而非构建下表）：

bash

cawcut capabilities list --schema

请参考

references/models.md

获取简短字段指南——并非模型目录。

Present parameters to users (required)

向用户展示参数（强制要求）

cawcut capabilities list --models

alone lists names only — no params.

cawcut capabilities list --schema

(implies

--models

) adds one dense line per parameter in plain text — useful for a quick look, but still render a markdown table for the user from the scoped

--json

form; do not paste raw CLI text/JSON or prose-only bullets when explaining models.

cawcut capabilities list --models --json --capability <cap>

is lean —

model_id

name

capability

default

only, for picking a model within one capability. Add

--schema

and

--model "<id>"

when you need

parameters

aspect_ratios

durations

duration_range

, or

medias

for a single model.

cawcut capabilities list --simple --capability <cap>

is the lightest human output for model menus (one line per model).

When the user asks what a model supports or which settings to pick, build a markdown table from live JSON for the selected capability + model:

Name	Type	Constraints / options	Default	Required	Notes

Row mapping from JSON
parameters[]
:

JSON field	Table column
`name`	Name — the `--param` key
`type`	Type ( `string` , `number` , `boolean` , `array` , …)
`options` or `min` / `max`	Constraints — comma-join `options` ; for ranges write `1–4`
`default`	Default — `—` when absent
`required`	Required — `yes` only when `required` is `required` ; else `no`
`description` + CLI hint	Notes — e.g. `--param ratio=16:9` ; arrays use JSON value

Also include non-

parameters

fields when present:

Source field	Present as
`aspect_ratios`	Extra row or note for ratio when no `ratio` param
`durations` / `duration_range`	Row for video length
`medias`	Separate media inputs table (below)
Top-level `prompt` (implicit)	Row: `prompt` / `string` / — / — / yes / CLI positional arg

CLI flags table — show once when explaining

cawcut generate

(not per model):

Name	Type	Constraints / options	Default	Required	Notes
`prompt`	string	—	—	yes	positional arg
`--capability`	enum	`text-to-image` , `text-to-video` , `image-to-image` , `image-to-video` , `omni-to-video`	—	yes	sets input/output mode
`--model`	string	`model_id` values from JSON only	capability default	no	quote if spaces
`--param`	key=value	from selected model `parameters`	per-field defaults	no	repeatable; arrays/objects as JSON string
`--image`	file \| url	local path or HTTPS	—	yes for image/omni caps	repeatable; local auto-upload
`--video`	file \| url	local path or HTTPS	—	omni optional	repeatable
`--audio`	file \| url	local path or HTTPS	—	omni optional	repeatable
`--loop`	number	1–4	1	no	parallel candidates; not workflow run count
`--workflow-id`	string	existing workflow UUID	—	no	reuse same project for all session follow-ups
`--wait`	flag	—	off	recommended	block until task completes
`--download`	flag \| path	omit = system Downloads	off	recommended	auto-save image/video
`--json`	flag	—	off	recommended	structured output; preserves signed URLs

Example — GPT Image 2 /
text-to-image
(shape reference; values must match live JSON):

Name	Type	Constraints / options	Default	Required	Notes
`prompt`	string	—	—	yes	text description
`ratio`	string	`16:9` , `9:16` , `1:1` , `21:9` , `3:2` , `4:3` , `5:4` , `2:3` , `3:4` , `4:5`	`16:9`	no	`--param ratio=16:9`
`resolution`	string	`1K` , `2K` , `4K`	`1K`	no	`--param resolution=2K`
`quality`	string	`low` , `medium` , `high`	`low`	no	`--param quality=high`
`num_images`	number	1–4	`1`	no	multiple images per API call; or use `--loop`

Example — GPT Image 2 /
image-to-image
— same params plus:

Name	Type	Constraints / options	Default	Required	Notes
`--image`	file \| url	up to 16 reference images	—	yes	`--image @/path` or URL

Always re-fetch JSON before presenting — plans and BE config change.

cawcut capabilities list --models

仅列出名称——无参数。

cawcut capabilities list --schema

（隐含

--models

）在纯文本中为每个参数添加一行密集信息——用于快速查看，但仍需从限定范围的

--json

输出中为用户构建markdown表格；解释模型时，请勿粘贴原始CLI文本/JSON或纯文字项目符号。

cawcut capabilities list --models --json --capability <cap>

为精简版——仅包含

model_id

name

capability

default

，用于在单个功能中选择模型。当需要单个模型的

parameters

、

aspect_ratios

、

durations

duration_range

或

medias

时，添加

--schema

和

--model "<id>"

参数。

cawcut capabilities list --simple --capability <cap>

是模型菜单最轻量化的人类可读输出（每行一个模型）。

当用户询问模型支持的功能或应选择哪些设置时，从实时JSON中为选定功能+模型构建markdown表格：

名称	类型	约束/选项	默认值	必填	说明

JSON
parameters[]
到表格行的映射：

JSON字段	表格列
`name`	名称—— `--param` 键
`type`	类型（ `string` 、 `number` 、 `boolean` 、 `array` 等）
`options` 或 `min` / `max`	约束——逗号分隔 `options` ；范围写为 `1–4`
`default`	默认值——无默认值时填 `—`
`required`	必填——仅当 `required` 为 `required` 时填 `yes` ；否则填 `no`
`description` +CLI提示	说明——例如 `--param ratio=16:9` ；数组使用JSON值

当存在非

parameters

字段时，也需包含：

来源字段	展示形式
`aspect_ratios`	无 `ratio` 参数时，添加额外行或说明
`durations` / `duration_range`	视频时长行
`medias`	单独的媒体输入表格（位于下方）
顶层 `prompt` （隐含）	行： `prompt` / `string` / — / — / yes / CLI位置参数

CLI参数表格——解释

cawcut generate

时展示一次（无需每个模型都展示）：

名称	类型	约束/选项	默认值	必填	说明
`prompt`	string	—	—	yes	位置参数
`--capability`	enum	`text-to-image` 、 `text-to-video` 、 `image-to-image` 、 `image-to-video` 、 `omni-to-video`	—	yes	设置输入/输出模式
`--model`	string	仅使用JSON中的 `model_id` 值	功能默认模型	no	含空格时需加引号
`--param`	key=value	来自选定模型的 `parameters`	各字段默认值	no	可重复使用；数组/对象使用JSON字符串
`--image`	file \| url	本地路径或HTTPS地址	—	图像/全媒功能必填	可重复使用；本地文件自动上传
`--video`	file \| url	本地路径或HTTPS地址	—	全媒功能可选	可重复使用
`--audio`	file \| url	本地路径或HTTPS地址	—	全媒功能可选	可重复使用
`--loop`	number	1–4	1	no	并行候选数；非工作流运行次数
`--workflow-id`	string	现有工作流UUID	—	no	会话后续请求复用同一项目
`--wait`	flag	—	off	推荐	阻塞直至任务完成
`--download`	flag \| path	省略则使用系统默认下载文件夹	off	推荐	自动保存图像/视频
`--json`	flag	—	off	推荐	结构化输出；保留签名URL

示例 — GPT Image 2 /
text-to-image
（格式参考；值必须与实时JSON匹配）：

名称	类型	约束/选项	默认值	必填	说明
`prompt`	string	—	—	yes	文本描述
`ratio`	string	`16:9` 、 `9:16` 、 `1:1` 、 `21:9` 、 `3:2` 、 `4:3` 、 `5:4` 、 `2:3` 、 `3:4` 、 `4:5`	`16:9`	no	`--param ratio=16:9`
`resolution`	string	`1K` 、 `2K` 、 `4K`	`1K`	no	`--param resolution=2K`
`quality`	string	`low` 、 `medium` 、 `high`	`low`	no	`--param quality=high`
`num_images`	number	1–4	`1`	no	单次API调用生成多张图像；或使用 `--loop`

示例 — GPT Image 2 /
image-to-image
——除上述参数外，额外添加：

名称	类型	约束/选项	默认值	必填	说明
`--image`	file \| url	最多16张参考图像	—	yes	`--image @/path` 或URL

展示前请重新获取JSON——套餐和后端配置可能发生变化。

Workflow

工作流

Check the App catalog — see Step 1 above (runs for every request, with the decide-once guard and the bare-invoke exception). Continue below only after the user chooses official generation or no App matches.
Discover capability — infer from the user request or offer image vs video + input mode choices.

List models —

cawcut capabilities list --simple --capability <cap>

(or lean

--models --json --capability <cap>

). Put the default model first in menus.

Pick output and input mode with choices (when not obvious):
- Image output:
```
text-to-image
```
  or
```
image-to-image
```
- Video output:
```
text-to-video
```
  ,
```
image-to-video
```
  , or
```
omni-to-video
```
  If the user's prompt/media makes the answer obvious, state the inferred choice and continue. If not, always call
```
AskUserQuestion
```
  /
```
AskQuestion
```
  first (per Interactive selection above); numbered menu in
```
reply_language
```
  only when the tool is unavailable. Bare invoke, zero signal: call
```
AskUserQuestion
```
  /
```
AskQuestion
```
  for Image vs Video in this same turn — do not defer it while waiting to also collect the subject in plain text. The subject/idea ask (free text, unbounded) runs alongside it, never merged into one sentence with the image/video choice.
Choose model — from Step 2 output only. Put the
```
"default": true
```
/
```
(default)
```
model first and mark it recommended; offer change model again in the settings menu (UX rule 10) for both image and video.

Load schema —

cawcut capabilities list --models --schema --json --capability <cap> --model "<model_id>"

before building param tables or the settings menu.

Collect prompt/media — ask for the generation prompt and any required
```
--image
```
,
```
--video
```
, or
```
--audio
```
input. If required media is missing, show the three-way menu (UX rules 16–17) and wait for the user's real file or URL — never substitute example or placeholder media from docs or schema.
Present the settings menu before generating, per Rule 10's two phases. Must include change model in Phase A (same for image and video). Do not ask an open-ended preference question.

Fallback example (English) — when

AskUserQuestion

AskQuestion

is unavailable or overflow applies (shape reference only — every value shown, including which one is "(default)", must come from that model's live schema, not from this example):

Phase A — single-select gate (text fallback):

Run with defaults, change model, or customize settings:
1. Use defaults (recommended) on GPT Image 2: ratio 16:9, resolution 1K, quality low, count 1
2. Change model: GPT Image 2 (default) / GPT Image 1 / …
3. Customize settings

If the user picks 3, Phase B (text fallback shape for one axis — repeat per axis, or batch via

AskUserQuestion

AskQuestion

- Aspect ratio: 16:9 (default) / 1:1 / 9:16 / 4:3 / 3:4 / custom
- Resolution: 1K (default) / 2K / 4K
- Quality: low (default) / medium / high
- Count: 1 (default) / 2 / 3 / 4

When
AskUserQuestion
/
AskQuestion
is available (required path) — same GPT Image 2 /

text-to-image

scenario, decomposed (labels in

reply_language

Phase A gate — one
```
AskUserQuestion
```
/
```
AskQuestion
```
call:
- ```
Use defaults
```
  — Run with schema defaults on current model (show default values)
- ```
Change model
```
  — Open model picker (overflow → numbered text table per Rule 10 if model count exceeds cap)
- ```
Customize settings
```
  — Proceed to Phase B
Phase B customize — one batched
```
AskUserQuestion
```
/
```
AskQuestion
```
call, one question per axis (never one pick across axes):
- Aspect ratio — options from live schema; first option = use default (show value)
- Resolution — same pattern
- Quality — same pattern
- Count — same pattern

Video example — Phase B axes come from that model's own schema, not GPT Image 2's (tool-available: same batched one-question-per-axis pattern; text fallback shape):

- Duration: 5s (default) / 10s / 15s / custom (4–15s)
- Aspect ratio: adaptive (default) / 16:9 / 9:16 / 1:1 / 21:9 / 4:3 / 3:4
- Resolution: 720p (default) / 480p / 1080p / 4k
- Audio: On (default) / Off

A model like Kling 3.0 Pro exposes no

resolution

axis but does have

generate_audio

— build Phase B strictly from that model's live

parameters

aspect_ratios

duration_range

; never reuse another model's axis list or default marker.

If the user later writes in another language, present the same menu in

reply_language

Only include options that exist in the selected model's schema. If a schema uses different values (for example

square

portrait

landscape

1024x1024

, or numeric seconds), display those exact values instead. 8. Build
--param
flags from the chosen model's

parameters

durations

aspect_ratios

. Use selected values, or schema defaults when the user chooses the default option. 9. Run with
--wait --json
:

Pre-flight check (do this immediately before building the command): Has

cawcut app list --json

been run for this user message before routing for the current subject/capability/style? If no → stop and go back to Step 1 now. Do not call

cawcut generate

first. A prior user message's catalog check or "no match" does not count.

bash

cawcut generate "<prompt>" \
  --capability <capability> \
  [--model "<model_id from JSON>"] \
  [--param key=value ...] \
  [--loop <1-4>] \
  [--image|--video|--audio <file|url>] \
  --wait --download --json

Array/object params use JSON in the value:

bash

--param 'colors=[]'
--param 'colors=["#004035","#008C65","#025940","#008C3E","#072621"]'

Capture
workflow_id
for every session follow-up (any capability or model):

bash

cawcut generate "<revised prompt>" \
  --capability <cap> \
  --workflow-id <id from prior JSON> \
  --wait --download --json

When switching to a media capability (e.g. image-to-image after text-to-image), pass

--image

--video

--audio

with the prior

result_urls

entry or user-provided file — nodes are appended side-by-side; BE does not auto-wire prior outputs.

Omit

--workflow-id

only for a clearly unrelated request or when the user asks for a new project.

Deliver — parse JSON; share every
```
result_urls
```
/
```
local_paths
```
. Use exact signed URLs (do not strip query parameters). Always also report
```
credits_used
```
(or
```
credits_estimate
```
if
```
credits_used
```
is absent) and
```
credits_balance
```
(or
```
credits_balance_error
```
) from the same JSON — every single completed generation, even back-to-back ones in the same session. Never omit this because it was already shown for a prior task.

检查应用目录——参见上方步骤1（针对所有请求运行，包含一次决策防护和裸调用例外）。仅当用户选择官方生成或无匹配应用时，才继续下方流程。
发现功能——从用户请求中推断，或提供图像/视频+输入模式选项供选择。

列出模型——使用

cawcut capabilities list --simple --capability <cap>

（或精简版

--models --json --capability <cap>

）。菜单中默认模型排在首位。

选择输出和输入模式（不明确时）：
- 图像输出：
```
text-to-image
```
  或
```
image-to-image
```
- 视频输出：
```
text-to-video
```
  、
```
image-to-video
```
  或
```
omni-to-video
```
  若用户的提示语/媒体明确指向某一选项，则说明推断结果并继续。否则，必须优先调用
  AskUserQuestion
  /
  AskQuestion
  工具（参见上述「交互式选择」规则）；仅当工具不可用时，才使用
```
reply_language
```
  对应的编号菜单。 裸调用、无任何信号：在同一回合调用
```
AskUserQuestion
```
  /
```
AskQuestion
```
  让用户选择图像或视频——请勿推迟该选择，同时等待用户以纯文本提供主题。主题/创意询问（自由文本、无限制）可与该选择并行进行，绝不要合并为一句话。
选择模型——仅从步骤2的输出中选择。将
```
"default": true
```
/
```
(default)
```
模型排在首位并标记为推荐；在设置菜单中（UX规则10）再次提供更换模型选项，图像和视频场景均适用。

加载schema——在构建参数表格或设置菜单前，运行

cawcut capabilities list --models --schema --json --capability <cap> --model "<model_id>"

。

收集提示语/媒体——询问生成提示语及任何必填的
```
--image
```
、
```
--video
```
或
```
--audio
```
输入。若缺少必填媒体，展示三分支菜单（UX规则16–17）并等待用户提供实际文件或URL——绝不要使用文档或schema中的示例或占位符媒体替代。
生成前展示设置菜单——遵循规则10的两个阶段。阶段A必须包含更换模型选项（图像和视频场景相同）。请勿询问开放式偏好问题。

备选示例（英文）——当

AskUserQuestion

AskQuestion

不可用或超出限制时（仅为格式参考——所有展示值，包括标记为「(default)」的选项，必须来自该模型的实时schema，而非本示例）：

阶段A — 单选入口（文本备选）：

选择使用默认设置、更换模型或自定义设置：
1. 使用GPT Image 2的默认设置（推荐）：比例16:9、分辨率1K、质量低、数量1
2. 更换模型：GPT Image 2（默认）/ GPT Image 1 / …
3. 自定义设置

若用户选择3，阶段B（单个维度的文本备选格式——每个维度重复此格式，或通过

AskUserQuestion

AskQuestion

批量处理）：

- 宽高比：16:9（默认）/ 1:1 / 9:16 / 4:3 / 3:4 / 自定义
- 分辨率：1K（默认）/ 2K / 4K
- 质量：低（默认）/ 中 / 高
- 数量：1（默认）/ 2 / 3 / 4

工具可用时（强制流程）——同一GPT Image 2 /

text-to-image

场景，拆解为以下步骤（标签使用

reply_language

）：

阶段A入口——单次
```
AskUserQuestion
```
/
```
AskQuestion
```
调用：
- ```
使用默认设置
```
  — 使用当前模型的schema默认值运行（展示默认值）
- ```
更换模型
```
  — 打开模型选择器（超出限制时，遵循规则10使用编号文本表格）
- ```
自定义设置
```
  — 进入阶段B
阶段B自定义——单次批量
```
AskUserQuestion
```
/
```
AskQuestion
```
调用，每个维度一个问题（绝不要跨维度合并为一个选项）：
- 宽高比 — 选项来自实时schema；第一个选项为「使用默认值（展示值）」
- 分辨率 — 相同格式
- 质量 — 相同格式
- 数量 — 相同格式

视频示例 — 阶段B维度来自该模型自身的schema，而非GPT Image 2的schema（工具可用时：相同的批量单维度问题格式；文本备选格式）：

- 时长：5秒（默认）/ 10秒 / 15秒 / 自定义（4–15秒）
- 宽高比：自适应（默认）/ 16:9 / 9:16 / 1:1 / 21:9 / 4:3 / 3:4
- 分辨率：720p（默认）/ 480p / 1080p / 4k
- 音频：开启（默认）/ 关闭

类似Kling 3.0 Pro的模型不暴露

resolution

维度，但包含

generate_audio

——严格根据该模型的实时

parameters

aspect_ratios

duration_range

构建阶段B；绝不要复用其他模型的维度列表或默认标记。

若用户后续使用其他语言，使用

reply_language

展示相同菜单。

仅包含选定模型schema中存在的选项。若schema使用不同值（例如

square

、

portrait

、

landscape

、

1024x1024

或数字秒数），则展示这些精确值。 8. 构建
--param
参数——从选定模型的

parameters

durations

aspect_ratios

中构建。使用用户选择的值，或当用户选择默认选项时使用schema默认值。 9. 使用
--wait --json
运行命令：

预检（运行命令前立即执行）：针对本次用户消息的当前主题/功能/风格，是否已运行

cawcut app list --json

？若否 → 立即停止，返回步骤1。请勿先调用

cawcut generate

。之前用户消息回合的目录检查或「无匹配」结论无效。

bash

cawcut generate "<prompt>" \
  --capability <capability> \
  [--model "<model_id from JSON>"] \
  [--param key=value ...] \
  [--loop <1-4>] \
  [--image|--video|--audio <file|url>] \
  --wait --download --json

数组/对象参数的值使用JSON格式：

bash

--param 'colors=[]'
--param 'colors=["#004035","#008C65","#025940","#008C3E","#072621"]'

**捕获
```
workflow_id
```
**用于会话后续所有请求（任何功能或模型）：

bash

cawcut generate "<revised prompt>" \
  --capability <cap> \
  --workflow-id <id from prior JSON> \
  --wait --download --json

切换到媒体功能时（例如text-to-image之后的image-to-image），传递

--image

--video

--audio

参数，值为之前的

result_urls

条目或用户提供的文件——节点会并排追加；后端不会自动连接之前的输出。

仅当请求与当前会话明显无关或用户要求新项目时，才省略

--workflow-id

。

交付结果——解析JSON；分享所有
```
result_urls
```
/
```
local_paths
```
。使用完整签名URL（请勿剥离查询参数）。必须同时报告同一JSON中的
```
credits_used
```
（若
```
credits_used
```
缺失则报告
```
credits_estimate
```
）和
```
credits_balance
```
（或
```
credits_balance_error
```
）——每一次完成的生成，即使是同一会话中的连续生成，都必须报告。绝不要因之前任务已展示过而省略。

Async tasks

异步任务

The CLI prints

Task: <task_id>

before polling. Capture it as a recovery handle.

With
```
--wait
```
: CLI blocks, then prints result URLs on success.

Without

--wait

cawcut task status <task_id> --wait

On timeout: resume with
```
cawcut task status <task_id> --wait
```

CLI在轮询前会打印

Task: <task_id>

。将其作为恢复句柄。

使用
```
--wait
```
：CLI会阻塞，成功后打印结果URL。

不使用

--wait

：

cawcut task status <task_id> --wait

超时：使用
```
cawcut task status <task_id> --wait
```
恢复

Errors

错误处理

Symptom	Action
`Token expired`	Run `cawcut auth login` via Bash, then retry the failed command
`Unknown capability`	`cawcut capabilities list`
Invalid `--param` / unknown model	Re-run `cawcut capabilities list --models --schema --json --capability <cap> --model "<id>"` for this user
CLI not found	`npm install -g @ubnt/cawcut` (Step 0); then `cawcut auth login` via Bash

See

references/troubleshooting.md

and

references/models.md

(discovery guide only).

症状	操作
`Token expired`	通过Bash运行 `cawcut auth login` ，然后重试失败的命令
`Unknown capability`	运行 `cawcut capabilities list`
无效 `--param` /未知模型	为用户重新运行 `cawcut capabilities list --models --schema --json --capability <cap> --model "<id>"`
CLI未找到	运行 `npm install -g @ubnt/cawcut` （步骤0）；然后通过Bash运行 `cawcut auth login`

请参考

references/troubleshooting.md

和

references/models.md

（仅为发现指南）。

cawcut-generate

Original

Translation

CawCut Generate

CawCut Generate

Step 0 — Bootstrap

步骤0 — 初始化引导

Catalog freshness (mandatory)

目录新鲜度（强制要求）

Step 1 — Check the App catalog first (before every
`cawcut generate`
call)

步骤1 — 优先检查应用目录（在每次
`cawcut generate`
调用前）

Interactive selection (mandatory — tool first)

交互式选择（强制要求——优先使用工具）

UX Rules

UX规则

Capabilities

功能列表

Discover models and parameters (required)

发现模型和参数（强制要求）

or: cawcut capabilities list --models --json --capability text-to-image

或：cawcut capabilities list --models --json --capability text-to-image

Present parameters to users (required)

向用户展示参数（强制要求）

Workflow

工作流

Async tasks

异步任务

Errors

错误处理

cawcut-generate

Original

Translation

CawCut Generate

CawCut Generate

Step 0 — Bootstrap

步骤0 — 初始化引导

Catalog freshness (mandatory)

目录新鲜度（强制要求）

Step 1 — Check the App catalog first (before every cawcut generate call)

步骤1 — 优先检查应用目录（在每次cawcut generate调用前）

Interactive selection (mandatory — tool first)

交互式选择（强制要求——优先使用工具）

UX Rules

UX规则

Capabilities

功能列表

Discover models and parameters (required)

发现模型和参数（强制要求）

or: cawcut capabilities list --models --json --capability text-to-image

或：cawcut capabilities list --models --json --capability text-to-image

Present parameters to users (required)

向用户展示参数（强制要求）

Workflow

工作流

Async tasks

异步任务

Errors

错误处理

Step 1 — Check the App catalog first (before every
`cawcut generate`
call)

步骤1 — 优先检查应用目录（在每次
`cawcut generate`
调用前）