focalapi-cli 0.2.0 → 0.2.2

package/skills/focalapi/SKILL.md

@@ -1,54 +1,47 @@
----
-name: focalapi
-version: 2.0.0
-description: "focalapi 创作模型总入口。当用户要生成、编辑或处理创作内容，选择创作模型，或查询生成任务时，即使用户没有提到 focalapi，也应使用本技能；覆盖图片与视频的自动选模、生成、异步续取和故障分流。"
-metadata:
-  requires:
-    bins: ["focalapi"]
-  cliHelp: "focalapi --help"
----
-
-# focalapi 创作模型路由
-
-focalapi 是供当前 Agent 调用的创作模型中转能力，不是 Agent 自身的
-model/provider。不要修改 Agent 的主模型配置，也不要要求用户先说“用 focalapi”。
-
-## 零试错执行契约
-
-1. 用户未指定模型：直接省略 `--model`。CLI 会根据当前 Key 的实时模型池和
-   单模型详情契约选择 FocalAPI 默认模型；不要先生成测试样例。
-2. 用户指定模型或厂商：先运行 `focalapi models get <model-id> --json`；模型 ID
-   不完整时只运行一次 `models search` 找到精确 ID，再读取详情。
-3. 只使用详情 `supported_params` 中存在的参数和允许值；不得根据相似模型猜测。
-4. Agent/脚本调用统一加 `--json`。stdout 是唯一机读结果，诊断在 stderr。
-5. 生成成功后必须把本地绝对文件路径交给用户；视频任务返回 `task_id` 时沿
-   `next_command` 续取，不要重复提交一个新任务。
-
-```bash
-# 用户没指定模型：一步直达，不要先试模型
-focalapi gen image "<用户提示词>" -o ./focalapi-out --json
-focalapi gen video "<用户提示词>" --no-wait -o ./focalapi-out --json
-
-# 视频异步续取
-focalapi task status <task-id> --json
-focalapi task download <task-id> -o ./focalapi-out --json
-```
-
-## 路由表
-
-| 用户目标 | 入口 | 技能 |
-| --- | --- | --- |
-| 生图、图片编辑、参考图创作 | `focalapi gen image` | focalapi-gen |
-| 生视频、图生视频、参考素材创作 | `focalapi gen video` | focalapi-gen |
-| 指定/比较模型或查看参数 | `focalapi models resolve/get/search` | focalapi-models |
-| 查询进度、失败原因、下载产物 | `focalapi task status/download` | focalapi-task |
-| Key、401、登录问题 | `focalapi auth status/login` | focalapi-auth |
-| 额度、用量、服务异常 | `focalapi usage/doctor` | focalapi-usage |
-| 用户明确要求文本辅助 | `focalapi chat` | focalapi-chat |
-
-当前已闭环验证的自动生成入口是图片与视频。未来出现音频、3D 或其他模态时，
-只有在 CLI 帮助和 `models get` 同时给出可执行契约后才能调用；不要仅凭模型列表或
-名称推断能力。
-
-若业务命令返回 `missing_api_key`，转 focalapi-auth 完成登录后立即回到原任务；
-其他错误只按 `{error.code, error.hint}` 修复一次，不要盲目轮换模型。
+---
+name: focalapi
+version: 2.0.0
+description: "Primary router for FocalAPI creative models. Use when the user wants to generate, edit, or process creative media, choose a creative model, or inspect a generation task, even when the user does not mention FocalAPI. Covers automatic image and video model selection, generation, asynchronous continuation, and error routing."
+metadata:
+  requires:
+    bins: ["focalapi"]
+  cliHelp: "focalapi --help"
+---
+
+# FocalAPI creative-model routing
+
+FocalAPI is a creative-model gateway for the current Agent to call. It is not the Agent's own model or provider. Do not change the Agent's primary model configuration or require the user to say “use FocalAPI” first.
+
+## Zero-guesswork execution contract
+
+1. If the user does not specify a model, omit `--model`. The CLI selects a FocalAPI default from the live model pool and detailed contracts available to the current key. Do not generate a test sample first.
+2. If the user specifies a model or provider, run `focalapi models get <model-id> --json` first. If the model ID is incomplete, run `models search` once to find the exact ID, then read its details.
+3. Use only parameters and values listed in the detailed `supported_params`. Never infer support from a similar model.
+4. Add `--json` for Agent and script calls. stdout is the only machine-readable result; diagnostics go to stderr.
+5. After successful generation, return local absolute file paths to the user. If a video response contains `task_id`, follow `next_command`; never submit the same task again.
+
+```bash
+# No model specified: run once without probing models first.
+focalapi gen image "<user prompt>" -o ./focalapi-out --json
+focalapi gen video "<user prompt>" --no-wait -o ./focalapi-out --json
+
+# Continue an asynchronous video task.
+focalapi task status <task-id> --json
+focalapi task download <task-id> -o ./focalapi-out --json
+```
+
+## Routing table
+
+| User goal | Entry point | Skill |
+| --- | --- | --- |
+| Generate or edit images; create from reference images | `focalapi gen image` | focalapi-gen |
+| Generate video; animate images or reference media | `focalapi gen video` | focalapi-gen |
+| Select, compare, or inspect model parameters | `focalapi models resolve/get/search` | focalapi-models |
+| Inspect progress or failures; download results | `focalapi task status/download` | focalapi-task |
+| Resolve key, sign-in, or 401 issues | `focalapi auth status/login` | focalapi-auth |
+| Inspect quota, usage, or service failures | `focalapi usage/doctor` | focalapi-usage |
+| Provide text assistance explicitly requested by the user | `focalapi chat` | focalapi-chat |
+
+The fully validated automatic generation paths currently cover images and video. Audio, 3D, or another modality may be used only after both CLI help and `models get` expose an executable contract. Never infer a capability from a model list or name alone.
+
+If a business command returns `missing_api_key`, route to focalapi-auth and return to the original task immediately after sign-in. For other errors, follow `{error.code, error.hint}` once; do not rotate models blindly.

package/skills/focalapi-auth/SKILL.md

@@ -1,30 +1,28 @@
----
-name: focalapi-auth
-version: 2.0.0
-description: "处理 focalapi-cli 安装、首次登录、Key 状态和 401/鉴权错误。仅在首次接入或业务命令明确返回 missing_api_key/invalid_api_key 时触发；认证完成后必须回到原创作任务。"
-metadata:
-  requires:
-    bins: ["focalapi"]
-  cliHelp: "focalapi auth --help"
----
-
-# focalapi 认证
-
-```bash
-npm i -g focalapi-cli
-focalapi auth login --key <sk-key>
-focalapi auth status --json
-focalapi connect
-```
-
-Key 在 `https://focalapi.com/console/token` 创建。不要在回复、日志或命令回显中展示
-完整 Key；CI/沙箱优先通过 `FOCALAPI_API_KEY` 注入。
-
-业务命令未报鉴权错误时，不要每次都运行 `auth status`。命中错误后按固定路径：
-
-- `missing_api_key`：登录或设置 `FOCALAPI_API_KEY`；
-- `invalid_api_key`：让用户在控制台确认/新建 Key 后重新登录；
-- `upstream_auth_failed`：本站 Key 可能正常，保留 request ID，转服务方排查；不要让
-  用户反复更换自己的 Key。
-
-认证成功后立即重试原业务命令，不要把登录本身当作任务终点。
+---
+name: focalapi-auth
+version: 2.0.0
+description: "Handle focalapi-cli installation, first sign-in, key status, and 401/authentication errors. Trigger only during initial setup or when a business command explicitly returns missing_api_key or invalid_api_key. Return to the original creative task after authentication succeeds."
+metadata:
+  requires:
+    bins: ["focalapi"]
+  cliHelp: "focalapi auth --help"
+---
+
+# FocalAPI authentication
+
+```bash
+npm i -g focalapi-cli
+focalapi auth login --key <sk-key>
+focalapi auth status --json
+focalapi connect
+```
+
+Create a key at `https://focalapi.com/console/token`. Never reveal the complete key in a response, log, or echoed command. Prefer `FOCALAPI_API_KEY` in CI and sandbox environments.
+
+Do not run `auth status` before every business command. After an authentication error, follow this fixed path:
+
+- `missing_api_key`: sign in or set `FOCALAPI_API_KEY`.
+- `invalid_api_key`: ask the user to verify or create a key in the console, then sign in again.
+- `upstream_auth_failed`: the FocalAPI key may be valid. Preserve the request ID and escalate to the service operator; do not repeatedly replace the user's key.
+
+Retry the original business command immediately after authentication succeeds. Signing in is not the end of the task.

package/skills/focalapi-chat/SKILL.md

@@ -1,32 +1,29 @@
----
-name: focalapi-chat
-version: 2.0.0
-description: "focalapi 的补充文本与音频命令。仅当用户明确要求通过 focalapi 做文本辅助，或实时模型契约明确存在可调用的音频模型时使用；图片/视频创作必须转 focalapi-gen。"
-metadata:
-  requires:
-    bins: ["focalapi"]
-  cliHelp: "focalapi chat --help"
----
-
-# focalapi 补充能力
-
-本技能不是创作请求的默认入口。图片、视频、改图、图生视频统一转
-`focalapi-gen`。
-
-用户明确要求文本辅助时，先从实时列表取得可用文本模型，再调用：
-
-```bash
-focalapi models list --json
-focalapi chat "<用户文本任务>" -m <列表中的文本模型> --json
-```
-
-音频命令只有在 `focalapi models get <model-id> --json` 与 `focalapi audio --help`
-共同确认可执行时才能使用：
-
-```bash
-focalapi audio transcribe <file> -m <model-id> --json
-focalapi audio speech "<text>" -m <model-id> -o <file> --json
-```
-
-模型列表里出现名称不等于 CLI 已支持调用。当前 Key 没有音频模型契约时应明确说明
-暂不可用，不要尝试相似模型或外部接口。
+---
+name: focalapi-chat
+version: 2.0.0
+description: "Supplementary FocalAPI text and audio commands. Use only when the user explicitly requests text assistance through FocalAPI or when the live model contract confirms an available audio model. Route image and video creation to focalapi-gen."
+metadata:
+  requires:
+    bins: ["focalapi"]
+  cliHelp: "focalapi chat --help"
+---
+
+# Supplementary FocalAPI capabilities
+
+This Skill is not the default route for creative requests. Route images, video, image editing, and image-to-video work to `focalapi-gen`.
+
+When the user explicitly requests text assistance, get an available text model from the live list before calling it:
+
+```bash
+focalapi models list --json
+focalapi chat "<user text task>" -m <text-model-from-list> --json
+```
+
+Use audio commands only when both `focalapi models get <model-id> --json` and `focalapi audio --help` confirm an executable contract:
+
+```bash
+focalapi audio transcribe <file> -m <model-id> --json
+focalapi audio speech "<text>" -m <model-id> -o <file> --json
+```
+
+A name appearing in the model list does not prove that the CLI supports calling it. If the current key has no audio model contract, state that audio is unavailable; do not try a similar model or an external API.

package/skills/focalapi-gen/SKILL.md

@@ -1,53 +1,50 @@
----
-name: focalapi-gen
-version: 2.0.0
-description: "用 focalapi 完成图片/视频生成、图片编辑、图生视频和参考素材创作。当用户表达画图、生图、改图、生成视频或让素材动起来时直接触发，即使未提 focalapi；默认自动选模，不先试模型。"
-metadata:
-  requires:
-    bins: ["focalapi"]
-  cliHelp: "focalapi gen --help"
----
-
-# focalapi 图片与视频生成
-
-## 默认：自动选模，一次执行
-
-用户没有指定模型时，直接运行：
-
-```bash
-focalapi gen image "<完整提示词>" -o ./focalapi-out --json
-focalapi gen video "<完整提示词>" --no-wait -o ./focalapi-out --json
-```
-
-CLI 会用当前 Key 的实时模型池与详情契约选择默认模型。不要先用低成本模型、
-测试提示词或多个模型各生成一次；这会产生不必要的费用和歧义。
-
-## 指定模型或高级参数
-
-用户点名模型时，先读一次实时契约：
-
-```bash
-focalapi models get <model-id> --json
-focalapi gen image "<prompt>" -m <model-id> [契约允许的参数] -o ./focalapi-out --json
-focalapi gen video "<prompt>" -m <model-id> [契约允许的参数] --no-wait -o ./focalapi-out --json
-```
-
-- 图片编辑/参考图使用 `--image <url...>`；mask 仅在契约列出时传 `--mask`。
-- 视频参考图使用 `--image <url...>`；时长、清晰度、画面比例和音频开关只按
-  `supported_params` 传递。
-- 不把一个模型的 `ratio`、`aspect_ratio`、`size` 或 `resolution` 复制给另一模型。
-- Gemini 原生图片仅在用户明确选中对应模型时使用 `gen gemini-image`；普通任务
-  继续使用自动入口 `gen image`。
-
-## 结果闭环
-
-图片同步结果的 `files` 是本地绝对路径，直接交付用户。异步结果按返回的
-`next_command` 执行：
-
-```bash
-focalapi task status <task-id> --json
-focalapi task download <task-id> -o ./focalapi-out --json
-```
-
-`pending` / `running` 不是失败；继续查询同一个 `task_id`，不得重新提交生成。
-失败时读取结构化 `error.code` 和 `hint`，只修复明确问题，不盲目换模型。
+---
+name: focalapi-gen
+version: 2.1.0
+description: "Use FocalAPI for image and video generation, image editing, image-to-video, and reference-media creation. Trigger directly when the user asks to draw, generate or edit an image, create video, or animate media, even without naming FocalAPI. Select a model automatically by default and do not probe models first."
+metadata:
+  requires:
+    bins: ["focalapi"]
+  cliHelp: "focalapi gen --help"
+---
+
+# FocalAPI image and video generation
+
+## Default: select automatically and run once
+
+When the user does not specify a model, run:
+
+```bash
+focalapi gen image "<complete prompt>" -o ./focalapi-out --json
+focalapi gen video "<complete prompt>" --no-wait -o ./focalapi-out --json
+```
+
+The CLI selects a default from the live model pool and detailed contracts available to the current key. Do not generate separate samples with a low-cost model, test prompt, or multiple models. Doing so creates unnecessary cost and ambiguity.
+
+## Explicit models and advanced parameters
+
+When the user names a model, read its live contract once:
+
+```bash
+focalapi models get <model-id> --json
+focalapi gen image "<prompt>" -m <model-id> [contract-supported options] -o ./focalapi-out --json
+focalapi gen video "<prompt>" -m <model-id> [contract-supported options] --no-wait -o ./focalapi-out --json
+```
+
+- Use `--image <url...>` for image editing and reference images. Pass `--mask` only when the contract lists it.
+- Use `--negative-prompt`, `--creativity`, `--prompt-extend`, `--style-references`, and `--moodboards` only when the image contract lists the corresponding field.
+- Use `--image <url...>` for video reference images. Pass duration, resolution, aspect ratio, and audio options only as allowed by `supported_params`.
+- Use `--content '<json-array>'` for models such as MiniMax H3, LTX 2.5, and FLUX 3 when the contract requires role-aware media content. LTX also exposes `--fps`; FLUX 3 exposes `--safety-tolerance`.
+- Never copy one model's `ratio`, `aspect_ratio`, `size`, or `resolution` to another model.
+- Use `gen gemini-image` only when the user explicitly selects a native Gemini image model. Continue to use the automatic `gen image` entry point for ordinary requests.
+
+## Complete the result workflow
+
+Synchronous image results contain local absolute paths in `files`; return them directly to the user. For asynchronous results, run the returned `next_command`:
+
+```bash
+focalapi task status <task-id> --json
+focalapi task download <task-id> -o ./focalapi-out --json
+```
+
+`pending` and `running` are not failures. Keep checking the same `task_id` and never resubmit generation. On failure, read the structured `error.code` and `hint`, and fix only the explicit problem instead of rotating models blindly.

package/skills/focalapi-models/SKILL.md

@@ -1,49 +1,55 @@
----
-name: focalapi-models
-version: 2.0.0
-description: "focalapi 创作模型选择与实时参数契约。当用户未指定模型、点名厂商/模型、比较模型，或生成参数报错时使用；默认用 resolve 直接得到可调用模型，禁止靠模型名猜能力或逐个试。"
-metadata:
-  requires:
-    bins: ["focalapi"]
-  cliHelp: "focalapi models --help"
----
-
-# focalapi 模型选择
-
-## 最短路径
-
-用户未指定模型时，不需要先列全量模型，也不需要 Agent 自己排序：
-
-```bash
-focalapi models resolve image --json
-focalapi models resolve video --json
-```
-
-`resolve` 会读取当前 Key 的实时列表，再读取候选模型的详情契约，返回：
-
-- `model.id`：可直接传给生成命令的精确 ID；
-- `endpoint_type`：已由详情确认的生成端点；
-- `model.supported_params`：本次可用参数、默认值、枚举和范围；
-- `next_command`：无需猜测的下一条命令。
-
-如果调用 `focalapi gen image/video` 时省略 `--model`，CLI 内部执行同一选择逻辑。
-
-## 用户指定模型
-
-```bash
-focalapi models get <完整模型-id> --json
-```
-
-只有用户给的是不完整厂商/系列名时，才先做一次搜索：
-
-```bash
-focalapi models search <keyword> --json
-focalapi models get <选中的完整-id> --json
-```
-
-规则：
-
-1. `models get` 是端点和参数的最终权威；列表摘要可能只展示协议族，不能据此猜模态。
-2. 不逐个模型发生成请求做可用性测试；模型发现与详情查询是只读预检。
-3. 指定模型不可用时，把可用候选交给用户或回到 `models resolve`，不要偷偷换模型。
-4. 查询完成后回到用户原始生成任务，不要停在模型清单。
+---
+name: focalapi-models
+version: 2.1.0
+description: "Select FocalAPI creative models and inspect live parameter contracts. Use when the user does not specify a model, names a model or provider, compares models, or encounters a generation-parameter error. Use resolve to obtain a callable default and never infer capabilities from names or probe models one by one."
+metadata:
+  requires:
+    bins: ["focalapi"]
+  cliHelp: "focalapi models --help"
+---
+
+# FocalAPI model selection
+
+## Shortest path
+
+When the user does not specify a model, do not list every model or rank them yourself:
+
+```bash
+focalapi models resolve image --json
+focalapi models resolve video --json
+```
+
+`resolve` reads the live list available to the current key, then reads detailed contracts for candidate models and returns:
+
+- `model.id`: the exact ID accepted by generation commands;
+- `endpoint_type`: the generation endpoint verified by model details;
+- `model.supported_params`: available parameters, defaults, enumerations, and ranges;
+- `next_command`: the next command with no guessing required.
+
+Omitting `--model` from `focalapi gen image/video` uses the same selection logic internally.
+
+## User-selected models
+
+```bash
+focalapi models get <complete-model-id> --json
+```
+
+Search once only when the user provides an incomplete provider or family name:
+
+```bash
+focalapi models search <keyword> --json
+focalapi models get <selected-complete-id> --json
+```
+
+Rules:
+
+1. `models get` is authoritative for endpoints and parameters. A list summary may show only a protocol family and cannot be used to infer modality.
+2. Do not send generation requests to models one by one as an availability test. Discovery and detail queries are read-only preflight checks.
+3. If an explicitly selected model is unavailable, present available candidates or return to `models resolve`; never replace it silently.
+4. Return to the user's original generation task after the query instead of stopping at the model list.
+
+## Current verified creative families
+
+The maintained defaults currently prefer Seedream 5.0, GPT Image 2, Gemini 3.1 Image, Grok Imagine Image 2.0, Kling Image 3.0, Qwen Image 3.0, and Krea 2 for images. Video selection currently covers Seedance 2.5, Kling 3.0, Vidu Q3, Gemini Omni Flash, Grok Imagine Video 1.5, LTX 2.5, FLUX 3, and MiniMax H3.
+
+These names are routing context, not permission to guess a model ID. Use the exact canonical ID returned by `models resolve` or `models get`. Removed IDs, including the former Veo 3.1 preview models, must not be retried.

package/skills/focalapi-task/SKILL.md

@@ -1,25 +1,25 @@
----
-name: focalapi-task
-version: 2.0.0
-description: "续取 focalapi 图片/视频异步任务并下载产物。当生成结果包含 task_id/next_command，或用户问进度、失败原因、结果文件时使用；必须复用原 task_id，不重复生成。"
-metadata:
-  requires:
-    bins: ["focalapi"]
-  cliHelp: "focalapi task --help"
----
-
-# focalapi 异步任务闭环
-
-生成命令返回 `task_id` 后，以响应里的 `next_command` 为第一选择：
-
-```bash
-focalapi task status <task-id> --json
-focalapi task download <task-id> -o ./focalapi-out --json
-```
-
-- `pending` / `running`：仍是同一个有效任务，稍后查询；不要重提生成请求。
-- `success`：执行 download，检查文件存在，并把绝对路径交给用户。
-- `failed`：展示上游错误摘要和 hint；只有参数/内容问题被明确指出时才重新生成。
-- `unknown`：保留原始响应并运行 `focalapi doctor --json`，不要伪造成功状态。
-
-轮询要有边界；用户没有要求阻塞等待时，汇报当前状态和 `task_id` 即可。
+---
+name: focalapi-task
+version: 2.0.0
+description: "Continue asynchronous FocalAPI image or video tasks and download their outputs. Use when a generation response contains task_id or next_command, or when the user asks about progress, failure reasons, or result files. Reuse the original task_id and never generate again."
+metadata:
+  requires:
+    bins: ["focalapi"]
+  cliHelp: "focalapi task --help"
+---
+
+# Complete asynchronous FocalAPI tasks
+
+After a generation command returns `task_id`, prefer the response's `next_command`:
+
+```bash
+focalapi task status <task-id> --json
+focalapi task download <task-id> -o ./focalapi-out --json
+```
+
+- `pending` or `running`: this is still the same valid task. Check it later and do not resubmit generation.
+- `success`: run download, verify that the file exists, and return its absolute path to the user.
+- `failed`: show the upstream error summary and hint. Generate again only when an explicit parameter or content issue requires it.
+- `unknown`: preserve the raw response and run `focalapi doctor --json`; never fabricate a success state.
+
+Polling must be bounded. When the user does not ask for blocking wait behavior, report the current status and `task_id`.

package/skills/focalapi-usage/SKILL.md

@@ -1,27 +1,26 @@
----
-name: focalapi-usage
-version: 2.0.0
-description: "查询 focalapi 额度、用量与账单，或诊断网络、鉴权和服务错误。当用户问消费/余额，或业务命令失败且需要按错误码闭环时使用；正常生成前不强制增加诊断步骤。"
-metadata:
-  requires:
-    bins: ["focalapi"]
-  cliHelp: "focalapi usage --help"
----
-
-# focalapi 用量与诊断
-
-```bash
-focalapi usage --json
-focalapi auth status --json
-focalapi doctor --json
-```
-
-- 用户问额度、余额、用量或账单：运行 `usage`。
-- `missing_api_key` / `invalid_api_key`：转 focalapi-auth。
-- `insufficient_quota`：运行 `usage`，说明缺口，不自动充值。
-- `network_error` / `timeout` / 5xx：运行一次 `doctor`，按 checks[].hint 处理。
-- `invalid_request`：回到 `models get` 的实时参数契约；不要重复发送同一请求。
-- `upstream_auth_failed`：保留 request ID 并反馈服务方，不要让用户更换本站 Key。
-
-正常业务命令没有报错时不要先跑 doctor 或免费演练；Agent 应直接完成用户的创作
-目标，减少无关调用。
+---
+name: focalapi-usage
+version: 2.0.0
+description: "Inspect FocalAPI quota, usage, and billing, or diagnose network, authentication, and service errors. Use when the user asks about spend or balance, or when a failed business command needs an error-code-driven resolution. Do not add mandatory diagnostics before normal generation."
+metadata:
+  requires:
+    bins: ["focalapi"]
+  cliHelp: "focalapi usage --help"
+---
+
+# FocalAPI usage and diagnostics
+
+```bash
+focalapi usage --json
+focalapi auth status --json
+focalapi doctor --json
+```
+
+- For quota, balance, usage, or billing questions, run `usage`.
+- For `missing_api_key` or `invalid_api_key`, route to focalapi-auth.
+- For `insufficient_quota`, run `usage`, explain the shortfall, and do not add funds automatically.
+- For `network_error`, `timeout`, or 5xx errors, run `doctor` once and follow `checks[].hint`.
+- For `invalid_request`, return to the live `models get` parameter contract and do not resend the same request.
+- For `upstream_auth_failed`, preserve the request ID and escalate to the service operator; do not ask the user to replace the FocalAPI key.
+
+Do not run `doctor` or a free rehearsal before a normal business command that has not failed. The Agent should complete the user's creative goal directly and avoid unrelated calls.