cawcut-generate

CawCut 生成

通过 CawCut 官方节点功能生成图像和视频。封装了 cawcut generate。生成前始终检查实时 App 目录中是否有类似的已发布 App；如果有合适的 App，则转交给 cawcut-app-run。

技能文件仅限英文。 SKILL.md 和 references/ 中不得包含中文或其他非英文文本（包括 YAML description 中的触发短语）。仅在实时回复中通过 reply_language 匹配用户的语言。

步骤 0 — 初始化

根据执行环境选择登录模式

根据命令实际运行的位置进行选择。在用户自己的计算机上，运行 cawcut auth login --browser --json；CLI 会打开浏览器并等待批准。在无法访问用户浏览器的远程环境、虚拟机或容器中，运行 cawcut auth login --device-auth --json，并将 authorization_url 发送给用户，让他们在自己的计算机上打开并批准。两种模式都支持 JSON；需要结构化输出并不是选择设备授权的理由。Agent 名称、非 TTY shell 和 localhost URL 本身都无法确定命令的运行位置。应使用已知的执行上下文和明确的模式标志覆盖 CLI 的自动检测。

对于设备登录，随后运行 cawcut auth login --complete --wait --timeout 60 --json。如果工具的执行超时时间较短，则改为单独调用 --complete --json，并遵循 next_poll_after_seconds。如果设备登录被中断或返回 wait_timeout，应恢复已保存的当前请求，而不是创建新链接。浏览器登录使用旧版 loopback 回调；如果被中断，应重新运行 cawcut auth login --browser --json，而不是使用 --complete。status=pending 不代表身份验证成功。只有在 status=authenticated 后，才重试原操作。拒绝或过期意味着此请求结束；不得悄悄创建无休止的授权链接。绝不要索要密码、令牌或从网页复制回来的代码。

将初始化作为静默的安全保障运行，而不是面向用户的阶段。

1. 每个 AI 会话最多执行一次。 如果此 AI 会话中已有任何 cawcut 命令成功执行，则跳过所有引导检查并继续。
2. 只使用一个显式检查命令： 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 clone，也不要运行仓库中的 ./setup）：

     npm install -g @ubnt/cawcut
     

     安装成功后，继续引导；认证将在下方步骤 4 中处理。
   • 如果因其他原因检查失败，继续操作；只有后续 CLI 命令失败时才提及警告。
3. 引导完成后不要输出“引导检查已通过”；直接进入步骤 1（若适用“直接调用例外”，则直接询问要生成什么）。
4. 让第一个实际命令（cawcut app list --json、cawcut capabilities list --models --json --capability <cap> 或 cawcut generate）验证认证。如果因令牌/认证错误（包括 Token expired）失败，请按上述登录步骤操作。使用适合执行环境的模式，并且只有在 status=authenticated 后才重试失败的命令，且仅重试一次。请自行运行 CLI 命令；用户只需在浏览器中批准。
5. 此技能的参考文件（references/troubleshooting.md、references/models.md）位于本技能正文顶部打印的基础目录下——直接通过 <base_dir>/references/<file>.md 读取。不要使用 find/grep 定位；该基础目录可能是符号链接，而普通的 find <dir> 可能无法遍历。
6. 结构化用户提问工具（每个会话都要检查）。 在 Claude Code 中，每个可枚举选项都使用 AskUserQuestion。在 Cursor 中，使用 AskQuestion。如果这两个工具中的任意一个出现在你的 allowed-tools 列表中，则此技能中的所有可枚举决策都必须使用它——包括 App 与官方生成方式、能力/模式、模型选择、Phase A/B 设置、枚举型 --param 值、媒体来源和上传恢复——除非选项过多，必须针对该批次使用带编号的文本表格（参见“交互式选择”）。只要 AskUserQuestion / AskQuestion 可用且选项数量符合要求，绝不要默认使用带编号的文本菜单。用户拒绝一次此类调用，并不意味着后续决策也不再使用它——如何解读拒绝消息，请参阅“交互式选择”开头的规则。

目录新鲜度（必须遵守）

事实来源： 仅限你在本条用户消息所在轮次中，针对当前主题/能力/风格运行的 cawcut app list … 命令输出。绝不要把先前消息中的 App 名称、ID、数量或 JSON 当作权威信息——对话记忆不是目录。先前用户消息中得出的“没有匹配的 App”结论绝不可重复使用。

每条用户消息规则（优先级最高）： 每收到一条新用户消息，在撰写任何回复或调用任何其他工具之前，先运行 cawcut app list --json——这是一个机械步骤，不是酌情判断；运行之前不要考虑该消息“是否可能涉及”App 匹配。自上次消息以来，服务端上的目录可能已经发生变化（例如，用户在网页上发布了新的 App）。下方的纯调用例外是唯一基于内容的例外——不要类推并自行构造其他例外。

纯调用例外（唯一基于内容的跳过情形）： 如果消息只有技能调用本身——消息中完全没有提及提示、主题、媒体或能力——那么还没有任何内容可与 App 的名称/描述进行匹配，因此本条消息跳过 app list，改为询问用户想生成什么（自由文本；参见工作流第 3 步中对纯调用的处理）。用户的回复一旦包含实际内容，就是一条新的用户消息——必须按上述规则先运行 app list --json，不得沿用此前结果。

出现以下任一情况时，也要重新运行第 1 步：

• 用户的工具调用（AskUserQuestion / AskQuestion / 菜单）被拒绝或中断，且用户的下一条消息更改了主题、能力或风格——即使是同一轮交流中的“后续消息”，也要完全按新用户消息处理，并从第 1 步重新开始
• 用户切换了账号、重新登录，或 cawcut auth login 刚刚成功
• 用户表示他们发布、分享或创建了新的 App
• 用户要求刷新或重新列出 App

仅当以下条件全部满足时，才可跳过第 1 步的目录检查（同一条用户消息所在轮次，且主题/能力/风格相同）：

• 你已在本条用户消息对应的轮次中运行 cawcut app list --json，并完成嗅探检查（或用户在出现合理匹配提示后选择了官方生成）
• 用户只是在调整当前计划的设置（比例、分辨率、质量、数量、时长、“再来一个”、“放大”）
• 或者，本轮从 cawcut-app-run 交接开始，且用户已在本条用户消息中选择“改用官方生成”（参见第 1 步中的“一次性决策”保护机制）

绝不要跨用户消息跳过每条用户消息都要执行的 app list——即使主题、能力、风格和措辞都没有变化。

硬性关卡： 工作流第 9 步会在调用 cawcut generate 前立即执行预检——详见该步骤。

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

一次性决策保护（仅限同一条用户消息） — 如果本轮是因为 cawcut-app-run 已在这条用户消息中运行了面向每条用户消息的 app list，并确定没有匹配的 App，或用户在其中选择了“改用官方生成”，则跳过整个步骤。直接进入下面的能力／模型发现；不要重新运行 app list，再次核对这条用户消息中已经作出的决定。

否则，请应用上方“目录时效性”中的每条用户消息规则、裸调用例外和跳过步骤 1检查清单。如果你尚未针对这条用户消息运行 cawcut app list --json，且不适用裸调用例外，则执行下面的步骤 1——不要复用之前消息中的列表或“没有匹配项”的结论。

1. 运行 cawcut app list --json，不要加 --schema（精简 JSON：name、description、credits、source——不含 input_schema；用于快速初筛，节省 token）。
2. 检查是否有任何 App 的 name／description 与用户的需求明显相关。这只是快速初筛，不是完整评分——cawcut-app-run 负责正式评分，并会在你移交后重新核查。
3. 没有合理的匹配项——继续下面的原始生成流程。不要向用户提及目录检查。
4. 有合理的匹配项——务必先调用 AskUserQuestion／AskQuestion（仅当工具不可用时才使用编号文本）：

   Found a published App that does this: <name> — <description> (N credits).
   1. Use <name>
   2. Continue with official generation
   

   • 用户选择 App → 将该 App 名称作为已确定选项，移交给 cawcut-app-run。它会跳过目录评分／菜单（其步骤 -1），直接进入 describe + 表格 + 输入菜单；如果该轮需要内部 app ID，它仍会实时获取 app list --json。
   • 用户选择官方生成 → 继续此技能下面的流程。本轮剩余时间内，不要再询问目录相关问题。

交互式选择（必需——先调用工具）

如果用户刚刚拒绝了一次 AskUserQuestion／AskQuestion 调用：工具结果会附带运行时自动添加的脚手架提示，要求你“停止当前操作，等待用户告知如何继续”。这句话会自动附加到每一次被拒绝的工具调用中——它不是用户发言，也不是要求你停止使用该工具。应将其理解为：停止当时正在进行的那一项具体操作（不要重试完全相同的问题；不要根据未经确认的选项继续调用 generate），并查看用户接下来的实际消息。单凭这句话，不能在下一个可枚举决策时改用编号文本；下一个决策仍必须先调用工具，就像用户从未拒绝过一样。只有用户明确以纯文本提出要求（“别再弹出菜单”“直接用文字问我”）时，才允许在整个会话中回退到文本方式。不要把 STOP 措辞的紧迫感误当成用户提出了这类要求，也不要让它凌驾于本规则之上。

默认行为：对于每一项可枚举的选择，务必先调用 AskUserQuestion（Claude Code）或 AskQuestion（Cursor），然后才能显示编号文本菜单，或让用户输入能力名称、模型 ID、宽高比或枚举值。纯文本菜单仅可作为后备方案。

只有一个选项不算选择。每次调用都需要至少两个可行选项。如果实际上只有一个可行选项——例如某项能力只公开了一个模型，或某个轴的实时架构只允许一个值——就用文字说明该选项并继续：绝不要弹出只有一个选项的窗口，也不要为了让它看起来像一道选择题而填入占位替代项。

按宿主确定工具名称：

宿主	工具名称
Claude Code	AskUserQuestion
Cursor	AskQuestion

下文所说的结构化用户询问工具，指当前会话中可用的这两个工具之一。不要仅凭能力来猜测——请检查你的 allowed-tools 列表。 会话检查清单（在本轮首次显示菜单前）： 0. **发送任何回复前先自检：**如果你即将发送的句子要求用户在固定选项中进行选择（图片或视频、能力、模型、比例……），即使它嵌在一个更友好的句子里，同时还询问了“主题是什么？”之类开放式问题，也要停下。这样的纯文本句子是禁止的。请拆开处理：现在就通过 AskUserQuestion/AskQuestion 询问可枚举选项；开放式问题只保留为单独的文字提问（可以在同一轮中，但不能合并为一句）。

1. 是否有 AskUserQuestion 或 AskQuestion 可用？如果有，对于下表中可在一次调用中完成的每一项，必须使用它。
2. 如果没有可用工具（仅限 CLI 的宿主环境），请使用 reply_language 中的编号文本。
3. 如果工具可用，但候选项数量超过一次调用的限制（模型列表溢出、较长的枚举列表），则仅为该批次使用编号文本表格；随后继续对下一个小型决策使用 AskUserQuestion / AskQuestion。

**工具可用时禁止：**使用编号文本菜单（1. … 2. …）、“回复数字或名称”，或要求用户凭记忆输入能力名称、模型 ID 或枚举值。

步骤	始终使用结构化用户提问工具询问
图片还是视频	输出类型
能力 / 输入模式	文本生成图片、图片生成图片、文本生成视频等
模型	每个计划中可见的模型（在标签中标明默认项）——候选项数量超过工具容量时，参见模型列表溢出（规则 10，阶段 A 选项 2）
设置入口	使用默认值 / 更改模型 / 自定义设置（阶段 A，单选）
设置——自定义	根据当前模型的实时架构，每个维度调用一次结构化用户提问工具——绝不可将多个维度合并成一个单选项
每个枚举型 --param	JSON 中的每个 options 值
媒体	与 cawcut-app-run 中的同一组三选项分支
有多张图片可用	在一次调用中合并为多参考输入，还是每张图片各生成一个输出——参见规则 19；在三选项媒体分支之前询问

仅限回退情形：仅当 AskUserQuestion / AskQuestion 不可用，或选项数量 / 结构超出该工具在本批次中的支持范围（模型列表溢出、较长的枚举列表）时，才使用 reply_language 中的编号文本菜单。为某个决策使用回退方式，不代表下一个小型决策也可以回退——请重新检查，并在适用时再次使用该工具。UX 规则 10 和工作流第 7 步中的文本示例仅用于展示回退格式——工具可用时，不得将其作为默认方式。只有在用户选择“自定义”/“URL”/“路径”分支后，才能询问自由文本的提示词内容或 URL / 路径。

UX 规则

1. 保持简洁。默认只输出 结果 URL。除非处于调试场景，否则不要输出原始 JSON。
2. 始终传入 --wait ——任务以异步方式运行，CLI 会阻塞等待，并在完成时打印 URL。
3. 生成图像和视频时始终传入 --download。CLI 会自动解析适用于平台的下载文件夹（macOS/Linux 上为 ~/Downloads，Windows 上为 %USERPROFILE%\Downloads）——不要硬编码路径，也不要自行下载结果。只有用户明确表示只想要 URL 时，才跳过 --download。
4. 回复语言：
   • 直接调用技能 → 英语。 如果用户只运行技能命令，没有实质性文本（例如 /cawcut-generate、cawcut-generate 或仅输入技能名称），则将 reply_language 设为 English，用于菜单、摘要和问题。
   • 之后跟随对话语言。 用户开始使用其他语言提出实际请求或后续问题后，后续整个会话都切换为该语言（除非用户明确要求使用英语）。
   • 所有说明文字、状态摘要、选项标签、问题和故障恢复指引都使用 reply_language。
   • CLI 命令/标志、模型 ID、应用 ID、JSON 键、URL 和原始错误代码保留英文。
   • 不要将原始英文 CLI 输出直接粘贴为面向用户的回答；应使用 reply_language 概述。
5. 不要使用 curl 调用 CawCut HTTP API ——CLI 会处理身份验证和媒体上传。凭据过期时，必须按步骤 0 执行登录步骤；不支持自动刷新令牌。
6. 先检查模板 ——请参阅上文步骤 1（先检查 App 目录）；此步骤适用于每个请求，不仅限于听起来像模板的请求。当用户选择所提供的 App 时，遵循 cawcut-app-run 的选择后披露 App 信息规则——说出 App 名称，展示元数据和输入项表格，然后通过菜单收集输入；不要只说“这个 App”而不提供详细信息。
7. 分阶段发现（必需） ——不要一次性获取所有功能及完整架构（不带 --capability 的 cawcut capabilities list --models --schema --json 会输出约 100 KB 内容，可能被截断）。请按以下顺序操作：
   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 命令）。
8. 优先让用户选择 ——如果用户没有提供足够信息，始终先调用 AskUserQuestion / AskQuestion（仅当工具不可用或选项超出上限时，才使用编号文本）。固定或可枚举的参数必须始终以可点击菜单呈现——由用户选择选项；不要让用户凭记忆输入参数名称、功能名称、模型 ID 或枚举值：
   • 图像或视频输出
   • 仅文本、图像输入、视频输入、音频输入或全模态输入
   • 从实时发现结果中列出的模型选项，并将 BE 默认模型置于首位
   • 所选模型参数中的枚举值/选项/范围
9. 不要询问无界的偏好问题 ——不要只问“对分辨率、宽高比、质量或图像数量有什么偏好吗？”。请始终通过 AskUserQuestion / AskQuestion 展示实时架构中的具体选项（遵循上文的交互式选择规则），并在可自定义时提供“使用默认值”和“自定义”。
10. 运行前先显示设置菜单 ——确定提示词/媒体/功能/模型后，分两个阶段处理设置。**图像和视频使用相同的形式。**优先级：只要工具可用，阶段 A（默认值 / 更改模型 / 自定义）必须调用一次 AskUserQuestion / AskQuestion，阶段 B 必须调用一次批量问题（每个维度一个问题）——不要合并成单个编号文本块。工作流步骤 7 中的组合文本示例仅作为备用呈现方式（工具不可用，或选项数量超出模型列表/长枚举上限时）。

• 阶段 A ——入口（调用一次 AskUserQuestion / AskQuestion）：
  • 选项 1：使用当前模型的架构默认值立即运行（显示默认值）。
  • 选项 2：更改模型 ——列出 cawcut capabilities list --simple --capability <cap> 中的所有模型（或精简版 JSON 对应结果）；标记 "default": true。模型列表超出上限时：AskUserQuestion / AskQuestion 通常每个问题最多支持约 2–4 个选项；如果该功能的模型数量超过上限，请改用编号文本表格（列：#、名称、默认标记、主要规格），并告知用户可回复编号或模型名称——这与 cawcut-app-run 的 App 选择器超出上限时的处理方式一致（交互式选择规则 7）。对超出上限的其他实时架构候选列表（模型、功能或较长的 --param 枚举）也使用相同的编号表格处理方式。用户选择后，重新获取新模型的架构（使用 --capability <cap> --model "<id>" --schema --json），然后针对新模型重新进入阶段 A。
  • 选项 3：自定义设置 ——进入阶段 B。
• 阶段 B ——自定义（调用一次批量 AskUserQuestion / AskQuestion，每个维度一个问题）：仅根据当前模型的实时架构（步骤 5）构建维度列表——不同模型提供的维度不同（例如，GPT Image 2 有 ratio/resolution/quality/num_images，而 Kling 3.0 Pro 提供 duration/aspect_ratio/generate_audio，没有 resolution）。对于每个会影响成本或视觉效果的维度（宽高比、分辨率/尺寸、质量、时长、图像数量、音频开关等），分别提出一个问题并附上相应选项；始终将“使用默认值（显示具体值）”设为首个选项。
• 不要把不同维度合并成一个单选项。 阶段 B 的目的是让用户可以分别设置任意维度，其余维度保持默认值；如果强迫用户在不同维度中单选（例如“自定义时长”或“自定义宽高比”二选一），就会导致未选中的维度从未展示给用户。
• AskUserQuestion / AskQuestion 每次调用最多支持 4 个问题。如果当前模型包含超过 4 个会影响成本或视觉效果的维度，先批量询问影响最大的 4 个；其余维度按规则 12 处理（高级/非关键参数保持默认值，不询问）。
• 自定义数值（例如 duration_range 范围内的时长）应作为该维度问题中的一个选项，而不是单独的顶层选项。

11. 对于常见设置（每项都应作为阶段 B 中单独的维度问题）：

• 宽高比：列出所有 aspect_ratios 值，或所选模型的 ratio/aspect_ratio 参数中的 options；标记默认值。如果架构没有宽高比字段，不要自行编造 --param。
• 分辨率/尺寸/质量/风格：列出匹配参数中的 options；标记默认值。对于最小值/最大值范围，显示默认值、最小值、最大值以及“在范围内自定义”。
• 图像数量：提供 1、2、3、4，并将 1 标记为默认值，除非架构另有说明。如果模型支持 num_images，使用 --param num_images=N；否则使用 --loop N。
• 视频时长：列出 durations；对于 duration_range，显示默认值、最小值、最大值以及范围内可自定义的秒数。
• 布尔开关（例如 generate_audio）：只要参数描述指出会影响成本/耗时，就在该维度的问题中提供“开启（默认）”/“关闭”两个选项（规则 14）。

12. 除非用户提及或参数是必需的，或明确会影响成本/视觉效果，否则不要询问高级参数。其余参数使用实时模型架构中的默认值。
13. 在会话中复用工作流 ——首次生成后，从 JSON 结果中获取 workflow_id。同一会话中后续的每一次 generate 都必须传入 --workflow-id <id> ——即使功能或模型发生变化（例如从 text-to-image 切换到 image-to-image，再切换到 text-to-video）。每次调用都会向该工作流追加新的生成节点（保留历史记录）。只有用户明确要求新项目，或请求显然与当前会话无关时，才省略 --workflow-id。
14. 多图/多候选项（--loop） ——loop 表示本次请求要并行添加的生成节点数量（最多 4），并非整个工作流的运行次数。如果用户想要超过 4 个候选项（例如“5 个候选项”），不要调用 CLI；应回复用户该模型/平台最多支持 4 个并行候选项。对于 N≤4：如果模型架构支持 num_images，且用户希望在一次 API 调用中生成多张图像，优先使用 --param num_images=N；否则使用 --loop N（图像和视频均适用）。设置 loop 后，积分消耗和耗时大致会按比例增加；如果还设置了 num_images，每个节点的消耗和耗时也会相应增加。本规则适用于从相同输入生成多个候选输出；如果用户提供了多个不同的参考图像，请参阅规则 19。
15. 不要根据训练数据假设模型或参数 ——可用模型取决于用户的套餐。始终先通过 CLI 进行发现。
16. 绝不要将示例媒体当作实际输入。 需要使用 --image、--video 或 --audio 时，SKILL.md、references/、模型架构或文档中的任何示例 URL 或路径（包括 cdn.example.com、@/path/to/file 等占位符）都只是提示，不可作为可用资源。除非用户在本次对话中明确提供了完全相同的文件或 URL，否则不要将其传给 CLI。
17. 媒体输入 ——通过菜单选择，不要虚构素材 ——始终按照上文的交互式选择规则，通过 AskUserQuestion / AskQuestion 提供三选一分支。以下编号列表仅作为文本备用格式，要求与 cawcut-app-run 相同。对于必需媒体，请提供：1）聊天中已有的文件；2）HTTPS URL；3）本地路径。由你将所选项映射到 --image / --video / --audio。如果缺少必需媒体，显示此菜单并等待用户回复——不要使用虚构示例或占位符运行。
18. 尝试 generate 前不要检查本地媒体 ——运行前不要通过 ls/file/sips -g pixelWidth/pixelHeight（或类似命令）检查本地文件的大小或尺寸。直接尝试 cawcut generate；如果上传前检查失败，CLI 的错误会报告具体大小/尺寸及其限制——根据该错误处理（参阅上文“上传限制”/下文“错误”），不要先手动检查。
19. 选择多个图像作为输入时，询问用户要合并还是分别处理，不要自行假设。 --image 可重复使用；image-to-image/image-to-video/omni-to-video 模型的 medias[].max（来自步骤 5 的架构）可能允许在一次生成调用中传入多个图像作为并行参考输入（例如，GPT Image 2 最多接受 16 张）。这与 --loop/num_images（规则 14）不同；后两者改变的是使用相同输入时的输出数量。规则 19 适用于需要输入多个不同候选图像的情况（例如交接中包含多个素材、聊天中分享了多个文件，或用户指定一个批次）。每当出现这种情况时，在构建命令前，始终调用 AskUserQuestion / AskQuestion，询问用户选择：
    • 合并为一次生成 ——将每张选中的图像作为重复的 --image 值传入（最多为 medias[].max），让模型将它们作为一组联合参考图像。
    • 每张图像分别生成一个结果 ——每张图像单独调用一次 generate，各自生成一个结果。 交接说明或仅列出要使用哪些图像的自由文本回答（例如“使用图像 A 和图像组 B 中的前 5 张”）并未充分解决这个问题——这种说法可能对应两种理解，因此仍然必须提供上述菜单。如果所选图像数量超过模型的 medias[].max，请告知用户，并让其缩短列表或改选“每张图像分别处理”；绝不要静默截断图像列表。

能力

--capability	功能	媒体输入
text-to-image	文本 → 图像	—
text-to-video	文本 → 视频	—
image-to-image	编辑 / 风格化图像	必须提供 --image，可重复使用 — 有多个候选图像时请参阅规则 19
image-to-video	为静态图像添加动画	必须提供 --image
omni-to-video	任意媒体 → 视频	必须至少提供 --image / --video / --audio 之一；可以组合媒体类型（例如，头像图像 + 音乐音频）

发现模型和参数（必需）

使用分阶段 CLI 发现方式 — 不要一次性加载全部五种能力的完整架构。

步骤 A — 选择能力（如果用户请求中还不明确）：

cawcut capabilities list

步骤 B — 仅列出该能力的模型（确定能力后）：

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

每行 --simple 的格式为 model_id: name，适用时会附带 (default)。只按第一个冒号拆分。

步骤 C — 仅加载所选模型的参数：

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

这会返回一段精简的 JSON 载荷（一种能力、一个模型），其中包含来自 BE 的元数据：

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

除非用户明确要求一次性浏览每种能力的完整架构，否则绝不要运行不带参数的 cawcut capabilities list --models --schema --json（所有能力）。

上传限制（平台）： 上传本地文件前，CLI 会加载 GET /developer/config 并验证大小/格式/尺寸。CLI 不会压缩文件。失败时，不要只打印错误然后停止，也绝不要建议改用 CawCut Web — 始终先调用 AskUserQuestion / AskQuestion，并提供以下选项：（1）现在通过 sips/ffmpeg 为其压缩/调整尺寸并自动重试；（2）由用户自行处理后重新上传；或（3）取消。只有工具不可用时，才能仅提供编号文本。如果用户选择（1），请自行运行修复命令，然后重试上传。各类失败对应的准确命令请参阅 references/troubleshooting.md。运行 cawcut config limits 可显示当前上限。

规则：

1. 只建议或传入所选能力 JSON 中出现的 --model 值。
2. 从该模型的 parameters（及相关字段）读取 --param 键和允许值。不要臆造参数名称。
3. 将 BE 的 "default": true 视为权威依据。每种能力应当且只能有一个默认模型；如果没有默认模型或存在多个默认模型，请用户从列出的模型中选择。
4. 对于默认模型，请省略 --model，或显式传入其 model_id。
5. 仅当无法进行实时发现且用户仍要求继续时，才使用回退默认值：图像/图像编辑 = gpt-image-2；视频/动画/全能 = Seedance 2.0。
6. 对包含空格或括号的 model_id 值加引号。

面向用户的可读摘要（仅名称，不含参数）：

cawcut capabilities list --models

包含参数的面向用户可读摘要（文本，非 JSON — 供快速查看，不用于构建下方表格）：

cawcut capabilities list --schema

简要字段指南请参阅 references/models.md — 这不是模型目录。

向用户展示参数（必需）

仅运行 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 | asset_id	本地路径、HTTPS 或 UUID asset_id	—	图像 / omni 能力必填	可重复；本地文件自动上传
--video	file | url | asset_id	本地路径、HTTPS 或 UUID asset_id	—	omni 可选	可重复
--audio	file | url | asset_id	本地路径、HTTPS 或 UUID asset_id	—	omni 可选	可重复
--loop	number	1–4	1	no	并行候选数量；不是工作流运行次数
--workflow-id	string	已存在的工作流 UUID	—	no	在整个会话的后续操作中复用同一项目
--wait	flag	—	off	建议使用	阻塞直至任务完成
--download	flag | path	省略时使用系统 Downloads	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 | asset_id	最多 16 张参考图像	—	yes	--image @/path、URL 或 asset_id

展示前务必重新获取 JSON — 方案和 BE 配置会发生变化。

工作流

0. 检查 App 目录 — 参见上面的步骤 1（每次请求都会执行，并应用一次性决定保护机制和直接调用例外）。只有在用户选择官方生成或没有匹配的 App 后，才继续下文。
1. 发现能力 — 根据用户请求推断，或提供图像与视频 + 输入模式选项。
2. 列出模型 — cawcut capabilities list --simple --capability <cap>（或精简形式 --models --json --capability <cap>）。在菜单中将默认模型放在首位。
3. 通过选项选择输出和输入模式（不明显时）：
   • 图像输出：text-to-image 或 image-to-image
   • 视频输出：text-to-video、image-to-video 或 omni-to-video 如果用户的提示词/媒体已能明确判断答案，就说明推断出的选项并继续。如果不能，始终先调用 AskUserQuestion / AskQuestion（按照上面的 交互式选择）；只有在工具不可用时，才使用 reply_language 编写编号菜单。 直接调用，没有任何线索： 在本轮调用 AskUserQuestion/AskQuestion 询问图像还是视频——不要为了同时用纯文本收集主题而推迟询问。主题/创意的提问（自由文本、不限范围）应与此并行进行，绝不能与图像/视频选项合并成一句话。
4. 选择模型 — 只能使用步骤 2 的输出。将 "default": true / (default) 模型放在首位并标记为推荐；在设置菜单中再次提供更换模型选项（UX 规则 10），图像和视频均适用。
5. 加载架构 — 在构建参数表或设置菜单之前，执行 cawcut capabilities list --models --schema --json --capability <cap> --model "<model_id>"。
6. 收集提示词/媒体 — 询问生成提示词以及任何必需的 --image、--video 或 --audio 输入。如果缺少必需媒体，显示三选一菜单（UX 规则 16–17），并等待用户提供真实文件或 URL——绝不能用文档或架构中的示例媒体或占位媒体代替。如果已有多个候选图像（来自其他技能的交接、聊天中的多个文件），在决定发起多少次 generate 调用之前，先解决合并还是分开处理的问题（规则 19）。
7. 生成前展示设置菜单，按照规则 10 的两个阶段执行。阶段 A 必须包含更换模型选项（图像和视频均适用）。不要提出开放式偏好问题。

备用示例（英文） — 当 AskUserQuestion / AskQuestion 不可用或发生选项溢出时（仅供参考格式——展示的每个值，包括哪个值标为“(default)”，都必须来自该模型的实时架构，不能来自此示例）：

阶段 A — 单选关卡（文本备用方案）：

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

如果用户选择 3，阶段 B（单个轴的文本备用方案格式——每个轴重复一次，或通过 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

当 AskUserQuestion / AskQuestion 可用时（必需路径）——同一 GPT Image 2 / text-to-image 场景，分步处理（标签使用 reply_language）：

1. 阶段 A 关卡 — 调用一次 AskUserQuestion / AskQuestion：
   • Use defaults — 使用当前模型的架构默认值运行（显示默认值）
   • Change model — 打开模型选择器（溢出时 → 如果模型数量超过上限，按照规则 10 显示编号文本表格）
   • Customize settings — 进入阶段 B
2. 阶段 B 自定义 — 批量调用一次 AskUserQuestion / AskQuestion，每个维度提一个问题（绝不能让用户在多个维度中只选一个）：
   • 宽高比 — 选项来自实时架构；第一个选项 = 使用默认值（显示值）
   • 分辨率 — 同样处理
   • 质量 — 同样处理
   • 数量 — 同样处理

视频示例 — 阶段 B 的维度应来自该模型自身的架构，而非 GPT Image 2（工具可用：同样采用每个维度一个问题的批量模式；文本备用方案格式）：

- 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

像 Kling 3.0 Pro 这样的模型不提供 resolution 维度，但有 generate_audio — 严格依据该模型的实时 parameters/aspect_ratios/duration_range 构建阶段 B；绝不能复用其他模型的维度列表或默认值标记。 如果用户之后改用其他语言书写，请使用 reply_language 展示相同的菜单。

只包含所选模型架构中存在的选项。如果架构使用不同的值（例如 square、portrait、landscape、1024x1024 或以秒为单位的数值），则显示这些确切值。 8. 根据所选模型的 parameters / durations / aspect_ratios 构建 --param 标志。使用所选值；如果用户选择默认选项，则使用架构默认值。 9. 使用 --wait --json 运行：

运行前检查（请在构建命令前立即执行）： 在当前主题／能力／风格的路由之前，是否已针对这条用户消息运行 cawcut app list --json？如果没有 → 立即停止并返回步骤 1。请勿先调用 cawcut generate。先前用户消息中的目录检查或“无匹配项”不算数。

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

数组／对象参数的值使用 JSON：

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

10. 为每次会话后续操作记录 workflow_id（适用于任何能力或模型）：

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

切换到媒体能力时（例如从文本生成图像切换到图生图），请将先前 result_urls 中的条目或用户提供的文件通过 --image / --video / --audio 传入——节点会并排追加；BE 不会自动连接先前的输出。

仅当请求明显无关，或用户要求新建项目时，才省略 --workflow-id。

11. 交付 — 解析 JSON；分享每个 result_urls / local_paths。使用精确的签名 URL（不要删除查询参数）。还必须始终从同一份 JSON 中报告 credits_used（若不存在，则报告 credits_estimate）和 credits_balance（或 credits_balance_error）——每次生成完成后都要报告，即使同一会话中连续生成也是如此。不要因为之前的任务已报告过就省略。

12. 移交给 VN 技能 — 交付结果后，无条件将每个 local_paths 条目（若只有一个，则使用 local_path）移交给 cawcut-vn。它负责处理整个 VN 决策流程——预览并导入、编辑流程或不采取操作——包括判断是否已安装 VN。不要在此处询问 VN 菜单，不要在此处运行 cawcut vn 命令，也不要重新判断接收技能负责的事项（只决策一次）。

异步任务

CLI 会在轮询前输出 Task: <task_id>。请记录该值，作为恢复句柄。

• 使用 --wait：CLI 会阻塞，成功后输出结果 URL。
• 不使用 --wait：cawcut task status <task_id> --wait
• 超时后：使用 cawcut task status <task_id> --wait 恢复

错误

症状	操作
Token expired	按照步骤 0 中的登录步骤操作；在 status=authenticated 后重试失败的命令一次
Unknown capability	cawcut capabilities list
Category: content_policy	重写提示词一次（删去整段可疑内容），然后切换提供方 — 参见 references/troubleshooting.md
无效的 --param / 未知模型	针对这条用户消息，重新运行 cawcut capabilities list --models --schema --json --capability <cap> --model "<id>"
找不到 CLI	npm install -g @ubnt/cawcut（步骤 0）；然后按照上述登录步骤操作

请参阅 references/troubleshooting.md 和 references/models.md（仅用于发现模型）。