cawcut-app-run

CawCut App 运行

所有与 CawCut-App 相关操作的入口：发现（“这个应用能做什么”“有哪些应用”）、浏览目录以及运行 Apps。封装了 cawcut app list、cawcut app describe 和 cawcut app run。还会判断请求是否没有匹配的 App，并交由 cawcut-generate 处理。

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

步骤 -1 — 交接状态（首先检查）

如果本轮是因为 cawcut-generate 已完成自己的应用目录检查，且用户确认要使用某个特定 App（参见其中的“先检查应用目录”规则）而开始，则该 App 已确定。跳过步骤 1 的目录评分和应用选择菜单。直接执行 cawcut app describe "<app name>" + 表格 + 输入菜单。

必要时仍须实时获取： 在 cawcut app run 之前，本轮中运行一次全新的 cawcut app list --json，以解析内部应用 ID——只能使用该命令的输出，不得使用先前消息中的目录 JSON，也不得使用 cawcut-generate 在本轮较早时候调用所得的结果。describe 始终须实时执行；绝不能用对话记忆中的先前 describe 快照替代。

如果用户在此交接后更改了主题或目标（包括工具调用被拒绝或中断后），步骤 -1 不再适用——从步骤 1 重新开始并重新评估目录。

否则，继续执行步骤 0。

步骤 0 — 初始化

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

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

设备登录后，运行 cawcut auth login --complete --wait --timeout 60 --json。如果你的工具执行超时时间较短，则改用单次 --complete --json 调用，并遵循 next_poll_after_seconds。设备登录被中断或返回 wait_timeout 后，应继续完成已保存的当前请求，而不是创建新链接。浏览器登录使用旧版回环回调；如果被中断，应重新运行 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，无需升级，继续操作。不要要求用户降级或运行 cawcut upgrade。
   • 如果检查因缺少 cawcut 而失败，请让用户通过 npm 安装 CLI（外部用户——不要 git clone 或使用仓库中的 ./setup）：

     npm install -g @ubnt/cawcut
     

     安装成功后，继续引导；身份验证按下文步骤 4 处理。
   • 如果检查因其他原因失败，请继续操作；只有后续 CLI 命令失败时，才提及此警告。
3. 引导后不要输出“引导检查已通过”，也不要询问“你想运行什么？”。直接进入下文的 App 发现步骤。
4. 让第一个实际命令（cawcut app list --schema、cawcut app describe 或 cawcut app run）验证身份验证。如果命令因令牌或身份验证错误而失败（包括 Token expired），请按照上文的登录步骤操作。根据执行环境选择合适的模式，并且仅在 status=authenticated 后重试该失败命令一次。CLI 命令由你自行运行；用户只需在浏览器中批准。
5. 此技能的参考文件（references/troubleshooting.md、references/app-inputs.md、references/intent-matching.md、references/app-presentation.md）位于此技能正文顶部打印的基础目录下——直接读取 <base_dir>/references/<file>.md。不要使用 find/grep 查找；该基础目录可能是符号链接，而普通的 find <dir> 可能会在不报错的情况下无法遍历它。
6. 结构化用户提问工具（每个会话都要检查）。 在 Claude Code 中，每当需要提供可枚举选项时，都使用 AskUserQuestion。在 Cursor 中，使用 AskQuestion。如果其中任一工具位于你的 allowed-tools 列表中，则此技能中的所有可枚举决策——选择 App、选择同名项、枚举值／默认值分支、媒体来源、跳过／提供可选输入、上传恢复——都必须使用该工具，除非选项过多，导致必须仅对该批次使用带编号的文本表格（参见“交互式选择”）。只要 AskUserQuestion／AskQuestion 可用且选项数量合适，绝不要默认使用带编号的文本菜单。用户拒绝某次此类调用，不代表后续决策可以不再使用该工具——请参阅“交互式选择”开头的规则，了解如何解读拒绝消息。

目录新鲜度（强制）

唯一可信来源： 仅限你在本条用户消息所在轮次中，为当前主题/目标运行的 cawcut app list … 命令的输出。切勿将较早消息中的 App 名称、ID、数量或 JSON 视为权威信息——对话记忆不是目录。之前用户消息中得出的“未匹配到 App”结论不可复用。

每条用户消息规则（优先级最高）： 每收到一条新用户消息，在撰写任何回复或调用任何其他工具之前，先运行 cawcut app list --json——这是一个机械步骤，不由判断决定；在运行前，不要先推理该消息“是否可能涉及” App 发现、匹配、浏览、cawcut app run，或路由到 cawcut-generate。自上次消息以来，服务器上的目录可能已经发生变化（例如，用户在网页上发布了新的 App）。

另外，遇到以下任一情况时，重新运行步骤 1：

• 用户的工具调用（AskUserQuestion / AskQuestion / 菜单）被拒绝或中断，且其下一条消息更改了主题、目标或目标 App——将其视为新用户消息，并从步骤 1 重新开始，即使是在同一轮对话的“后续消息”中（包括输入收集过程中）
• 发现 / 浏览 / “有哪些 App” / 主动展示目录（如果尚未遵循上面的每条用户消息规则）
• 当前目标需要意图评分或 App 选择菜单
• 用户按名称选择 App 后解析 App ID（在本轮中重新运行 cawcut app list --json）
• “找不到 App”后的恢复流程
• 用户切换了账号、重新登录，或 cawcut auth login 刚刚成功
• 用户表示其发布、分享或创建了新的 App
• 用户要求刷新或重新列出 App
• 之前的列表带有范围限制（例如仅 Official），但用户现在要求查看 My Apps 或 Shared Apps
• app describe / app run 返回未找到或访问错误

仅当以下条件全部满足时，才可跳过步骤 1 的目录评分（同一条用户消息所在轮次、同一主题/目标）：

• 你已针对本条用户消息运行 cawcut app list --json，并完成目录评分或确认无匹配项
• 本条用户消息中，当前主题/目标所对应的 App 已经确定（用户已选择、该目标的强自动匹配度 ≥70，或 cawcut-generate 已针对该 App 名称执行步骤 -1 移交）
• 你只是在继续对该已命名 App 执行 describe 和输入收集，或在本轮中重新运行 cawcut app list --json 以解析其 ID，然后再运行 run
• 你不会在没有新用户消息的情况下再次展示 App 选择菜单
• 本条用户消息中，用户的主题/目标未发生变化（包括工具调用被拒绝/中断之后）

绝不可在不同用户消息之间跳过每条用户消息的 app list——即使主题、能力和措辞完全相同。

硬性门槛： 工作流 §3（使用输入运行）会在运行 cawcut app run 前立即执行预检——详见该部分。

步骤 1 — 意图分流（获取目录之前）

每次未转交的调用都从这里开始。在进行目录评分之前，先按照上文 Catalog freshness 中的 Per-user-message rule 和 Skip Step 1 检查清单操作——如果你尚未针对这条用户消息运行 cawcut app list --json，就获取实时目录并进行评分；不要复用之前消息中的列表、已选 App 或“无匹配项”的结论。

官方能力快速通道——根据用户的表述，识别简单的单步官方生成请求（无需 App）：

隐含的 --capability	用户可能会说
text-to-image	文本生成图像、text-to-image、生成图像、制作图像
text-to-video	文本生成视频、text-to-video、制作视频
image-to-image	图像到图像、image-to-image、编辑／风格化／重混这张图像
image-to-video	图像生成视频、image-to-video、让这张照片动起来
omni-to-video	omni 转视频、omni-to-video

在按要求针对每条用户消息运行 cawcut app list --json（参见上文 Catalog freshness）且未找到可能匹配的 App 后，如果请求提及或暗示上述某种能力，并且没有模板／营销活动／市场／多输入／指定 App 的线索，就将请求直接转交给 cawcut-generate，并使用隐含的 --capability。否则（表述含糊，或提到了品牌化／模板／多步骤工作流），继续进行下方的目录评分。

探索还是运行——如果用户在询问某个 App 的功能、生成内容、所需输入，或想浏览目录，请设置 intent = discovery（参见 references/app-presentation.md）。在用户确认之前，不要将此类请求视为运行请求。

目录评分——其他所有情况都应获取实时目录（见下方步骤），并按照 references/intent-matching.md 中的标准进行评分：

结果	操作
探索意图	按照 references/app-presentation.md 展示；除非用户要求运行，否则停止
强匹配（得分 ≥ 70）	视为已选中 — 执行 describe + 表格 + 输入选项菜单
弱匹配／并列（40–69，或前两名相差不超过 15 分）	始终调用 AskUserQuestion / AskQuestion，列出前 2–4 个 App +“改用官方生成”。仅当工具不可用或触发溢出规则时，才使用编号文本
无匹配（全部 < 40，目录为空）	如有隐含的 --capability，则将请求转交给 cawcut-generate

将请求转交给 cawcut-generate 后，本轮即视为结束——同一轮中不要再次检查目录。即使主题相似，新的用户消息（新一轮）也必须重新遵循上文的目录时效规则。

App 类别（图像／视频）

app list --json 中的每个 App 都包含由发布元数据推导出的 categories（image、video、text、audio）。根据输出类型，使用这些类别对 App 进行分组和筛选：

类别	CLI 筛选器	使用场景
image	--category image	贴纸、照片编辑、市场卡片、静态创作
video	--category video	广告、动态效果、动画、产品视频、演示者

探索布局（空参数调用／浏览时必须使用）：

1. 图像 Apps — categories 包含 image 的 Apps
2. 视频 Apps — categories 包含 video 的 Apps

每个部分内部都应保留 CLI 输出中现有的来源分组：Official Apps / My Apps / Shared Apps。当用户的目标明确仅涉及图像或视频时，使用 --category 获取结果以减少无关内容。

cawcut app list --schema              # grouped by category + source
cawcut app list --schema --category image
cawcut app list --schema --category video
cawcut app list --schema --json       # includes categories[] per app

交互式选择（必须 — 优先使用工具）

如果用户刚刚拒绝了 AskUserQuestion / AskQuestion 调用： 工具结果会附带一些运行环境的固定文本，告诉你“停止当前操作，等待用户告知如何继续”。这句话会由运行时自动附加到每一次被拒绝的工具调用中；它不是用户说的，也不是要求你停止使用该工具的指令。应将其理解为：停止你正在进行的这一个具体操作（不要重试完全相同的问题，也不要在选项未经确认时继续执行 run），并查看用户实际的下一条消息。这句话本身并不允许你在下一个需要枚举选项的决定中退回到编号文本；下一个决定仍必须像从未遭到拒绝一样，先调用工具。只有用户明确以纯文本提出请求（“别再弹出菜单了”“直接用文本问我”），才允许整个会话改用备用方式。STOP 措辞显得紧迫，并不能证明用户提出了这种请求——不要让它凌驾于本规则之上。

默认行为： 对于每一个需要枚举选项的选择，始终先调用 AskUserQuestion（Claude Code）或 AskQuestion（Cursor），再显示编号文本菜单或询问用户输入 1、2 或应用名称。纯文本菜单仅作为备用方式。

一个选项不构成选择。 每次调用都需要至少两个可行选项。如果实际上只有一个可行选项——例如只有一个 App 匹配，且没有其他值得提供的选项，或者枚举类型只有一个允许值——就用文字说明该选项并继续：绝不要弹出只有一个选项的窗口，也不要为了凑成选择而添加占位替代项。

不同宿主的工具名称：

宿主	工具名称
Claude Code	AskUserQuestion
Cursor	AskQuestion

下文中的结构化用户提问工具是指当前会话中可用的上述工具之一。不要仅凭功能推测——请检查你的 allowed-tools 列表。

会话检查清单（本轮首次显示菜单前）：

1. AskUserQuestion 或 AskQuestion 是否可用？如果可用，对于下表中能通过一次调用处理的每一行，都必须使用它。
2. 如果没有可用工具（仅 CLI 的宿主），则使用 reply_language 对应语言的编号文本。
3. 如果工具可用，但候选项数量超出一次调用的限制（App 选择器选项过多，见规则 7），则仅针对该批次使用编号文本表格；随后对下一个较小的选择继续使用 AskUserQuestion / AskQuestion。

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

步骤	始终使用结构化用户提问工具处理
App 选择器	app list --schema 中的每个应用（标签 = 名称 + 积分 + 简短描述；不包含应用 ID）——候选项数量超出工具容量时，参见 App 选择器选项过多（规则 7）
同名项	每个匹配项（标签 = 描述 + 来源；不包含应用 ID）
枚举 / 默认文本	每个允许值，以及适用时的“使用默认值”/“自定义”
媒体输入	Photo already in chat / Paste HTTPS URL / Local file path
可选输入	Skip / Provide

结构化用户提问工具规则：

1. 只要选项可枚举，就应在等待自由文本回复之前调用。
2. 尽可能在每个表单中只做一个决定（例如，先选 pick-app，再选 scene-photo-source）。
3. label 是用户看到的内容；id 应简短且稳定（photo-sticker、3d-model-zh、3d-model-en）。
4. 不要将应用 ID 放入标签中。用户选择后，在本轮中重新运行 cawcut app list --json，然后仅根据该输出解析 ID。
5. 如果用户选择自定义 / 本地文件路径 / 粘贴 URL，再追问一次以获取相应内容（文本或路径）——仍然不要让他们输入 input KEY 名称。
6. 仅作备用：只有在 AskUserQuestion / AskQuestion 不可用，或选项数量／结构超出工具对该批次的支持范围时，才使用 reply_language 中的编号文本菜单。某个决定需要回退，并不意味着下一个小型决定也可以跳过——如果符合条件，应重新检查并再次使用该工具。UX 规则 11 的组合文本块仅是备用格式——如果工具可用，它不是默认格式。
7. 应用选择器超出选项限制：该工具通常每个问题最多支持约 2–4 个选项（每次调用最多约 4 个问题）。当 app list --schema 返回的候选列表超出此范围时，应使用带编号的文本表格供用户浏览——首列为 # 序号，后接名称、来源、积分、描述——并告知用户可以回复序号或应用名称。此文本回退仅适用于超出限制的批次。用户缩小范围并选定某个 App 后，之后所有选项数量较少的决定（选择重复副本、枚举值、媒体来源、跳过／提供可选输入）都必须再次通过 AskUserQuestion / AskQuestion 进行——模式与 cawcut-generate 的 Phase A Choice 2 模型列表超出限制及 Phase B 轴分批相同（其规则适用于超过 4 个会影响成本／视觉效果的轴）。

UX 规则

1. 优先让用户选择 — 如果用户没有指定 App，先运行 cawcut app list --schema，然后只要候选数量未超出范围，始终调用 AskUserQuestion / AskQuestion 让用户选择 App（仅 App 选择器选项溢出时才使用编号文本，见规则 7）。不要显示 App ID — 只使用名称、来源、积分、描述和输入摘要。
2. 优先使用模板 — 执行步骤 1（意图判断）：按照 references/intent-matching.md 对实时目录评分，并优先推荐强匹配项。仅在步骤 1 得出以下结果时，才回退到 cawcut-generate：无匹配项、目录为空，或有明确的官方功能快速路径。
3. 选择后披露 App 信息（必需） — 每当选定一个 App——无论是用户选择、根据自然语言请求自动匹配，还是你给出的单一推荐——都必须在询问输入内容之前：
   1. 运行 cawcut app describe "<app name>"（如有需要，先消除歧义）。
   2. 使用 reply_language 展示 App 元数据表和输入项表（参见“向用户展示 App 输入项”）。
   3. 在正文中先介绍 App 名称和描述——绝不能只说“这个 App”，而不说出其名称。
   4. 然后展示输入收集菜单（UX 规则 11–12）。 **禁止：**使用“这个 App 可以帮你……”之类的含糊说法，不提供名称、来源、功能或输入摘要；不说明是哪一个 App 以及需要哪些输入，就直接说“请提供视频路径”。
4. 允许使用自然语言请求 — 按照步骤 1 的评分标准（references/intent-matching.md），根据 App 名称、描述、来源、积分和公开的输入要求，将用户目标转换为 App 推荐。当某个 App 的评分 ≥ 70 时，将其视为已选定——立即运行 describe 并披露完整 App 信息；不要等用户问“是什么 App？”。
5. 回复语言：
   • 仅调用技能 → 英语。 如果用户只运行技能命令，没有提供实质性文本（例如 /cawcut-app-run、cawcut-app-run 或仅技能名称），则将 reply_language 设为英语，用于菜单、摘要和问题。
   • 之后跟随对话语言。 用户之后用另一种语言提出实际请求或后续问题时，切换 reply_language，后续会话均使用该语言（除非用户明确要求使用英语）。
   • 所有正文、状态摘要、选项标签、问题和故障恢复说明均使用 reply_language。
   • CLI 命令/标志、模型 ID、输入键、JSON 键、URL 和原始错误代码保留英文。App ID 属于内部信息——需要时，在本轮中通过最新运行的 cawcut app list --json 获取；面向用户的 App 列表中绝不显示 ID。
   • 不要将原始英文 CLI 输出直接粘贴为面向用户的答复；请使用 reply_language 对其进行概述。
6. 主动发现 — 完成引导后，不要等用户要求查看列表。如果用户没有提供 App 名称，立即运行 cawcut app list --schema，按 图像 App 和 视频 App 分类概述 App（不含 ID），并请用户选择 App 或自由描述目标。
7. 运行前始终检查输入项 — 先调用 cawcut app describe "<app name>"（或在根据 --json 解析时调用 cawcut app describe <app_id>）。
8. 运行前消除重名歧义 — 如果名称匹配多个 App，且副本数量未超出范围，始终调用 AskUserQuestion / AskQuestion，为每个副本提供一个选项（标签中包含描述、来源和输入摘要）。等待用户点击/选择后再运行。仅当该工具不可用时，才使用编号文本作为 CLI 回退方案：cawcut app run "<name>" --pick <n>。
9. 所有固定值或可枚举值均优先让用户选择 — 标准与 cawcut-generate 相同。绝不要让用户凭记忆输入 App 名称、输入键、枚举值或标志。describe 之后，如果某个字段有默认值、options 或一组已知的有限选项，始终调用 AskUserQuestion / AskQuestion（适用时还要提供“使用默认值”选项）。仅当架构确实定义了无默认值的开放文本内容，且用户尚未提供时，才询问该内容。只要工具可用，就绝不要对数量少的可枚举选项默认使用编号文本。
10. 不得提出不受限的输入问题 — 禁止使用以下说法：

• “你想运行哪个 App？”
• “请提供必填输入项的值。”
• “请粘贴 Input - Scene Photo 的值。” 改为始终根据 app list --schema / app describe 显示具体的编号选项。

11. 运行前展示输入收集菜单 — describe 之后，先收集输入选项，再运行。优先顺序：只要工具可用，始终分解为多个 AskUserQuestion / AskQuestion 调用——字段多于一个时，先调用一次概述“如何填写输入项”（默认值与自定义值），然后为每个需要用户决定的字段分别调用一次（媒体来源 A/B/C、文本起始内容与自定义内容、枚举值列表）。下面的组合文本块仅作为回退呈现方式——只在 AskUserQuestion / AskQuestion 不可用，或子选项数量超出工具可容纳的范围时使用（App 选择器选项溢出，交互式选择规则 7）。工具可用时，不要将分开的决策合并成一个编号文本菜单。 回退示例（英文） — 当 AskUserQuestion / AskQuestion 不可用或触发溢出时：

Ready to run Photo to Sticker. Choose how to fill inputs:
1. Use defaults only (if any exist) and run — list which fields use defaults
2. Scene photo — pick one:
   A. Use a photo you already shared in this chat (I'll use that file/URL)
   B. Paste an HTTPS image URL
   C. Give a local file path (e.g. ~/Pictures/photo.jpg, or C:\Users\you\Pictures\photo.jpg)
3. Text fields (only when required and no default) — pick a starter or write custom:
   A. Use suggested prompt: "..."
   B. Custom (you describe; one short message)
4. Run now with choices above

当 AskUserQuestion / AskQuestion 可用时（必需路径） — 同一个「照片转贴纸」场景，拆分处理（每次调用只做一个决策；标签使用 reply_language）：

1. 场景照片来源 — 使用 AskUserQuestion / AskQuestion 并提供以下选项：
   • Photo already in chat — 使用你已在此聊天中分享的照片
   • Paste HTTPS URL — 粘贴 HTTPS 图片 URL
   • Local file path — 提供本地文件路径（例如 ~/Pictures/photo.jpg 或 C:\Users\you\Pictures\photo.jpg）
2. 文本字段（如果必填且没有默认值）— 使用 AskUserQuestion / AskQuestion 并提供以下选项：
   • Use default / Use suggested prompt — 显示默认值或建议值
   • Custom — 然后追问一次，获取用户输入的文本（遵循上面的规则 5） 根据实时架构调整条目 — 对于不存在的输入，请省略相关决策。绝不要将输入 KEY 名称显示为用户必须输入的内容；这些键仅供 CLI 使用。
3. 按输入类型提供菜单，而非自由填写参数 — 始终根据上文的交互式选择，通过 AskUserQuestion / AskQuestion 呈现每一行的选项。下面的编号菜单仅作为文本回退格式。

   类型	面向用户的菜单（绝不询问 KEY 名称）
   text + 有默认值	1) 使用默认值（显示具体值） 2) 自定义文本
   text + 无默认值	1) 根据应用描述推荐 2–3 个入门选项 2) 自定义（用户一次性撰写内容）
   text + 架构中有枚举/选项	为 describe --json 中的每个允许选项编号；仅当架构允许时才添加“其他”
   image / video / audio	1) 文件已在聊天中 2) HTTPS URL 3) 本地路径 — 用户选择 A/B/C，而不是原始的 --input 键
   可选输入	1) 跳过 2) 提供（然后显示该类型的子菜单）

4. 使用 describe 中的 KEY 列，将选定的菜单选项映射为 --input key=value。用户选择的是选项，而不是参数名称。
5. 对于媒体输入：用户选择菜单分支后，传入 HTTPS URL 或以 @ 为前缀的本地路径。为简洁起见，此文件中的路径采用 POSIX 格式；在 Windows 上，相同的输入为 --input "key=@C:\Users\you\Pictures\photo.jpg"，且无论 CLI 还是 PowerShell，都不会在带引号的参数中展开 ~。按用户提供的原样传入路径；如果路径包含空格，则加上引号；绝不要将一种平台的路径格式改写为另一种平台的格式。
6. 绝不要将示例媒体用作实际输入。 对于 image / video / audio 输入，describe 输出（sample:、x-cawcut-sample-url）、SKILL.md、references/ 或其他文档中的任何示例 URL、路径或资源都仅供参考，不可用作实际资源。除非用户在本次对话中明确提供了完全相同的文件或 URL，否则不要将其传入 --input。如果缺少必需的媒体，请显示媒体子菜单（规则 12）并等待 — 不要使用虚构或占位示例运行；不要只询问 URL/路径而不提供选项。
7. 传入 --wait，让长时间运行的任务阻塞直至完成；转达所有结果 URL。
8. 如果结果是图像、视频或音频文件，始终传入 --download。CLI 会自动解析适用于平台的下载文件夹（macOS/Linux 上为 ~/Downloads，Windows 上为 %USERPROFILE%\Downloads）— 不要硬编码路径，也不要自行下载结果。仅当用户明确表示只需要 URL 时，才跳过 --download。
9. 不要猜测键名 — 不同应用的键名各不相同。始终从 describe 输出中获取（仅供 Agent 端使用 — 绝不要向用户透露键名）。
10. 选择应用前，先了解应用来源：

• Official Apps：由 CawCut 官方账号拥有的精选应用。
• My Apps：由已认证用户拥有的应用。
• Shared Apps：其他用户分享给已认证用户的应用。 如果用户要求“官方”或“共享”应用，只能从 cawcut app list 的相应部分中选择。

20. 运行前不要预先检查本地媒体 — 运行前不要通过 shell 执行 ls、file、sips -g pixelWidth/pixelHeight（或类似命令）来检查本地文件的大小或尺寸。直接尝试运行 cawcut app run；如果上传前检查失败，CLI 错误会报告确切的大小/尺寸及其限制 — 根据该错误处理（见下文“错误”），不要先进行手动检查。

工作流

1. 列出可用应用

cawcut app list --schema
# optional: --category image | --category video

输出：先按输出类别（图像应用 / 视频应用）分组，再按来源（官方 / 我的 / 已共享）分组，并显示名称、描述、点数，以及可用时的输入架构行（cawcut app list 不会在面向用户的输出中打印应用 ID）。根据应用名称、描述、categories、来源、点数和必需的输入类型，确定可能的匹配项。需要应用 ID 以进行自动化时，请在内部使用 cawcut app list --json。

面向用户的输出示例：

Image Apps
  Official Apps
    Photo to Sticker  2 credits  description: Turn a scene photo into a sticker
  My Apps
    My still template  description: Custom image workflow

Video Apps
  Official Apps
    Product video generator  8 credits  description: Generate a product ad video

不要将官方应用、我的应用和已共享应用视为可以互换。如果同一个应用在多个来源中都可见，优先使用 CLI 显示的来源。reply_language 不是英语时，翻译应用名称和描述；输入键和来源分组名称保持原样。面向用户的应用列表中绝不显示应用 ID。

如果用户提供了自然语言请求，请按以下顺序排列可能的匹配项：

1. 最匹配的官方应用 / 模板（如果有）。
2. 最匹配的自有 / 已共享应用。
3. cawcut-generate 后备选项，仅当没有匹配的应用或用户选择原始生成时使用。

**单个明确匹配项：**将其视为已选中——运行 describe，然后提供元数据 + 输入表格 + 输入收集菜单（UX 规则 3）。不要只回复“这个应用可以……”。

**多个匹配项：**显示编号列表，每项包含名称、描述、来源、点数和输入摘要；用户选择后，运行 describe，并在收集输入前披露完整详情。

如果用户没有提供请求，也应立即提供有用的选项。不要只问一句空泛的“你想运行什么？”。

用 reply_language 提供选项。默认示例（直接调用技能 / 英语）：

Here are runnable CawCut Apps:
1. Product video generator — Generate a product ad video
   Source: Official Apps; est. 8 credits; needs: prompt(text), product_image(image)
2. Generate a product ad video — My marketing template
   Source: My Apps; needs: prompt(text)
3. Apply a shared style template — Shared by another user
   Source: Shared Apps; needs: image(image)

You can:
A. Run 1 / 2 / 3 (I'll list required inputs next)
B. Describe your goal and I'll recommend the best App
C. Skip templates and use cawcut-generate instead

如果用户之后改用其他语言，请使用 reply_language 中的相同结构。

如果用户选择了一个应用（或自动匹配到单个应用），请立即检查该应用：

cawcut app describe "Product video generator"

然后提供应用元数据表格、输入表格和输入收集菜单（UX 规则 3、11–12）。必需输入必须通过菜单选项确定，而不是通过自由格式的参数输入来确定；在此之前不要运行。

示例 — 用户要求截取视频的第一帧（运行 describe 后）：

Found a matching App: **First/Last Frame Extractor (qa test)**

| Field | Value |
|-------|-------|
| Name | First/Last Frame Extractor (qa test) |
| Source | Official Apps |
| Cost | … credits |
| Output | First frame + last frame images |

Extracts the first and last frame from a video and outputs them as images.

| Name | Type | Required | Notes |
|------|------|----------|-------|
| … | video | yes | The video to process (MP4, WebM, etc.) |

Provide the video:
A. Use a video already shared in this chat
B. Paste an HTTPS video URL
C. Provide a local file path

2. 检查输入

cawcut app describe "<app name>"

输出：一个输入表格，包含 KEY、KIND、必需 / 可选、DEFAULT 和 DESCRIPTION。示例：

App: Product video generator
Description: Generate a product ad video

Inputs — use the KEY column with --input KEY=value:

  KEY                   KIND    REQ   DEFAULT           DESCRIPTION
  prompt                text    yes   no                Ad script or product description
    requirements: Required text input.
  product_image         image   yes   no                Product photo
    requirements: Required image input. Provide an HTTPS URL, local file path, or {asset_id,url} object.

Run: cawcut app run "Product video generator" --input 'prompt=...' --input 'product_image=@/path/to/file'

原始 JSON 架构（工具 name 中包含内部应用 ID）：

cawcut app describe "<app name>" --json

消除重名应用的歧义（必需）

当 cawcut app describe 或 cawcut app run 返回 Multiple apps named "..." 时，请提供确认表格——仍然不要显示应用 ID：

#	名称	来源	描述	点数	输入

根据 CLI 消息填写各行（来源、描述、点数、输入架构行）。请用户按编号选择，或说明想要哪一个副本。然后运行：

cawcut app run "3D Model Generator" --pick 2 --input ... --wait --download --json

只有在用户确认后才能使用 --pick。名称唯一时，省略 --pick。

向用户展示 App 输入（必需）

CawCut App 的输入来自 cawcut app describe——一个 KEY/KIND 表格以及要求说明行。有些 CLI 会通过专用的 model get 类命令打印现成的参数表；CawCut 不会。说明 App 时，请呈现面向用户的 Markdown 表格；不要粘贴原始 CLI 输出，也不要使用含糊的文字描述。

展示规则：表格用于呈现信息；对于可枚举／固定值的交互，始终使用编号菜单（与 cawcut-generate 相同）。不要把表格变成“逐行填写”的自由输入。

使用以下列布局：

名称	类型	限制／格式	默认值	必填	备注

describe / --json 中的字段映射：

来源	表格列
KEY（JSON 中的 properties 键）	名称——准确的 --input 键；可以包含空格——在 shell 中加引号
x-cawcut-input-kind 或 KIND	类型：text / image / video / audio
oneOf / 要求说明文本	限制——HTTPS URL、@/local/path、{asset_id,url}
x-cawcut-has-default + 默认值	默认值——为 false 时填 none
x-cawcut-required	必填——yes / no
DESCRIPTION + 要求说明	备注——易懂的标签；x-cawcut-sample-url / sample: 行仅用于示例，绝不能作为 --input 传入

App 元数据表——放在输入表格上方：

字段	值
名称	来自 list/describe
来源	Official Apps / My Apps / Shared Apps
类别	来自 list JSON 中的 categories
费用	app list --schema 中的 credits
输出	image / video / audio / text（优先使用 categories）

**面向用户的表格中不要包含 App ID。**调用 CLI 时，在本轮中通过最新运行的 cawcut app list --json 获取 ID。

示例——照片转贴纸：

字段	值
名称	照片转贴纸
来源	Official Apps
费用	6.9 credits
输出	贴纸风格图像（金属描边 + 搪瓷边框）

名称	类型	限制／格式	默认值	必填	备注
Input - Scene Photo	image	HTTPS URL、@/local/path（自动上传）、{asset_id,url}	none	yes	场景／人物照片 → 贴纸效果

面向用户的菜单（表格之后）：

Scene photo for Photo to Sticker:
A. Use a photo already shared in this chat
B. Paste an HTTPS image URL
C. Provide a local file path

cawcut app run "Photo to Sticker" \
  --input "Input - Scene Photo=@/path/to/photo.jpg" \
  --wait --download --json

对于当前 App，始终运行 describe——不同 App 和环境中的键及 credits 各不相同。

cawcut app run 的 CLI 标志表：

名称	类型	限制／选项	默认值	必填	备注
<app_ref>	string	list 中的 App 名称或内部 ID	—	yes	名称包含空格时加引号；名称有歧义时添加 --pick <n>
--pick	number	消歧列表中的 1 起始索引	—	no	仅当多个 App 同名时使用
--input	key=value	来自 describe 的 KEY	—	按 schema 要求	可重复；键包含空格时加引号
--input-json	file	JSON 对象	—	no	不可与 --input 同时使用
--wait	flag	—	off	建议使用	阻塞直至完成
--download	flag | path	省略时使用系统 Downloads	off	建议使用	自动保存媒体结果
--json	flag	—	off	建议使用	结构化输出

3. 使用输入运行

运行前检查（请在构建命令前立即执行）： 在针对当前主题／目标进行路由／评分之前，是否已针对此用户消息运行 cawcut app list --json？如果没有，或者自上次目录检查以来，此用户消息中的主题／目标或目标 App 有所变更 → 立即停止并返回步骤 1。请勿先调用 cawcut app run。先前用户消息中的目录检查或“未匹配”不作数。运行前，如果本轮尚未为此 App 执行过目录查询，请通过新鲜运行的 cawcut app list --json 确定 App ID。

始终传入 --json，以便 CLI 输出结构化 JSON，而不是纯文本——这样可以防止 Agent 截断签名结果 URL。

cawcut app run "Product video generator" \
  --input prompt="summer sale, bright colors" \
  --input product_image="https://cdn.example.com/shoe.jpg" \
  --wait --download --json

本地文件（自动上传到 CawCut 资源）：

cawcut app run "Product video generator" \
  --input prompt="summer sale" \
  --input product_image="@./shoe.jpg" \
  --wait --download --json

多个输入：

cawcut app run "<app name>" \
  --input key1=value1 \
  --input key2=value2 \
  --wait --download --json

JSON 文件（适用于包含许多键或特殊字符值的情况）：

cawcut app run "<app name>" --input-json ./inputs.json --wait --download --json

inputs.json 格式：

{ "prompt": "...", "product_image": "https://cdn.example.com/img.jpg" }

请勿在同一次调用中同时使用 --input 和 --input-json。

媒体上传前检查失败（大小／尺寸）——本地 @ 路径会在运行继续之前触发上传验证。如果 CLI 输出纯文本限制提示（例如 Audio file size is 22.9 MB (limit 15 MB). Re-encode or trim…），且没有 Code: / Category: / Suggested actions: 标记，仍需进行处理——请勿只复述错误。务必先调用 AskUserQuestion / AskQuestion，询问用户是要你现在压缩／调整尺寸（使用 sips / ffmpeg）后重试、由他们自行处理，还是取消。只有在工具不可用时，才能使用编号文本。切勿建议使用 CawCut Web。不同失败类型的准确命令请参见 references/troubleshooting.md（MB 限制与最长边 px 限制需要采用不同的处理方式）。下方的错误表也适用同一规则。

4. 下载结果

上方的运行命令中已包含 --download。CLI 会自动确定正确的系统下载文件夹——无需指定路径。

5. 交付

使用 --json 时，CLI 会输出 JSON：

local_path 值是对应平台上的路径：macOS 上为 /Users/.../file.png， Windows 上为 C:\Users\...\Downloads\file.png。请按 CLI 输出的内容原样报告这些路径。

{
  "result_url": "https://cdn.cawcut.com/...?Expires=...&Signature=...&Key-Pair-Id=...",
  "result_urls": [
    "https://cdn.cawcut.com/...?Expires=...&Signature=...&Key-Pair-Id=...",
    "https://cdn.cawcut.com/...?Expires=...&Signature=...&Key-Pair-Id=..."
  ],
  "task_id": "...",
  "local_path": "/Users/.../file.png",
  "local_paths": ["/Users/.../file-1.png", "/Users/.../file-2.png"],
  "status": "done",
  "credits_used": 12.0,
  "credits_balance": 88.0
}

6. 移交给 VN 技能

交付结果后，无条件移交给 cawcut-vn，并提供每个已交付的本地路径（local_paths；如果只有一个，则提供 local_path）。VN 技能负责完整的 VN 决策——预览并导入、编辑流程或不采取操作——包括判断 VN 是否已安装。请勿在此处询问 VN 菜单，不要在此处运行 cawcut vn 命令，也不要为了满足接收技能的选择而重新运行 App（只决策一次）。

输入类型和格式

类型	--input 格式	说明
text	key=some text value	字符串；数字／布尔值会转换为字符串
image	key=https://… 或 key=@/local/path.jpg	本地文件会自动上传；URL 原样传递
video	key=https://… 或 key=@/local/path.mp4	上传行为与图像相同
audio	key=https://… 或 key=@/local/path.mp3	上传行为与图像相同

@ 前缀明确表示这是要上传的本地路径。即使没有此前缀，如果裸路径（例如 ./file.jpg）对应的文件存在，也会自动检测并上传。

异步任务

CLI 始终会在开始轮询之前向 stdout 打印 Task: <task_id>。请记录此值——它是用于恢复任务的句柄。

• 使用 --wait：CLI 会阻塞等待，然后在成功时打印所有结果 URL。
• 不使用 --wait：CLI 会打印 Check status with: cawcut task status <task_id> --wait。
• 如果 --wait 超时：CLI 会打印 Polling timed out. Resume with: cawcut task status <task_id> --wait——运行该命令以继续轮询。

错误

如果 CLI 输出 Code:、Category: 或 Suggested actions:，请先将这些编号操作告知用户，再重试。对于令牌、应用访问、缺少输入、输入无效、点数、内容政策和超时错误，请使用 references/troubleshooting.md 进行后备处理。

许多其他故障会以纯文本 CLI 消息的形式显示，不包含这些标记——请使用下方的“症状→操作”表（包括媒体上传前置检查的大小／尺寸限制）。

如果 JSON 中存在 result_urls，请提取并向用户提供其中的每个 URL。为保持向后兼容，result_url 是第一个 URL。如果存在 local_paths，也请提供其中的每个条目。请使用完整的签名 URL 值——不要截断或删除查询参数（?Expires=...&Signature=...&Key-Pair-Id=... 部分是访问所必需的）。

始终同时报告同一 JSON 中的 credits_used（若不存在则报告 credits_estimate）和 credits_balance（或 credits_balance_error）——每次运行完成后都要报告，即使同一会话中连续运行多次也不例外。即使之前的运行已报告过，也绝不能省略。

症状	操作
未找到应用	重新运行 cawcut app list；确认应用名称拼写正确
存在多个同名应用	显示消歧表（来源、描述、输入）；征求用户确认；使用 --pick <n> 重新运行
应用不属于 Official Apps	也检查 My Apps 和 Shared Apps；用户拥有或共享的应用均有效，但不得将其描述为官方应用。
unknown input key "..."	检查 cawcut app describe "<app name>"；修正键名拼写
Token expired	按照第 0 步中的登录步骤操作；在 status=authenticated 后重试一次失败的命令
媒体上传前置检查失败（大小／尺寸）	不要只显示错误——务必先调用 AskUserQuestion / AskQuestion，询问用户是要现在压缩／调整尺寸（使用 sips / ffmpeg）后重试、由用户自行处理，还是取消。仅当该工具不可用时，才使用编号文本。切勿建议使用 CawCut Web。请参阅 references/troubleshooting.md，了解不同失败类型对应的确切命令（MB 限制与最长边像素限制需要采用不同的处理方式）。
生成时模型限制导致运行失败	检查 cawcut capabilities list --models --schema --json → medias[].limit。

如需了解更深入的输入解析详情，请参阅 references/app-inputs.md。