focalapi-cli 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,10 +1,17 @@
 # Changelog
 
+## 0.2.1 - 2026-08-11
+
+- Prepared the public GitHub repository metadata and refreshed the project documentation for external contributors.
+- Rewrote bundled Agent Skills and source comments in English while preserving the existing CLI commands and runtime behavior.
+- Clarified that audio transcription and speech synthesis require an explicit model selected from the current key's live model list.
+- Added the CLI verification report and kept local benchmark artifacts out of the published repository.
+
 ## 0.2.0 - 2026-08-11
 
-- 新增基于实时模型列表与详情契约的 `models resolve image|video`，图片和视频生成可省略 `--model` 自动选择当前可用默认模型。
-- 重构 Agent 接入：覆盖 44 个 Agent 目标，支持共享 Skills 目录去重、自定义 `--path`、事务式安装、摘要校验、安全卸载与 `connect verify`。
-- npm 安装后 best-effort 自动同步已检测 Agent；`focalapi connect` 保持为不依赖 lifecycle script 的稳定接入入口。
-- 重写 7 个内置 Skills：未点名 focalapi 的创作任务也可自动路由，不再试生成模型或修改 Agent 主模型/provider。
-- 异步图片和视频结果增加模型信息与 `next_command`，Agent 可续取原任务而不重复提交。
-- 修正 CLI 进程退出码，使 `doctor` 与 `connect verify` 的失败状态可被 Agent 和脚本可靠检测。
+- Added `models resolve image|video`, backed by the live model list and detailed contracts, so image and video generation can omit `--model` and automatically select a currently available default.
+- Reworked Agent integration across 44 Agent targets with shared Skills-directory deduplication, custom `--path` support, transactional installation, digest verification, safe uninstall, and `connect verify`.
+- Added best-effort synchronization for detected Agents after npm installation while keeping `focalapi connect` as the stable entry point that does not depend on lifecycle scripts.
+- Rewrote all seven bundled Skills so creative requests route automatically even when the user does not name FocalAPI, without probing generation models or changing the Agent's primary model/provider.
+- Added model information and `next_command` to asynchronous image and video results so Agents can continue the original task without resubmitting it.
+- Fixed CLI process exit codes so Agents and scripts can reliably detect failures from `doctor` and `connect verify`.

package/README.md

@@ -2,7 +2,7 @@
 
 # focalapi-cli
 
-**让任意 AI Agent 直接调用 focalapi 创作模型**
+**Give any AI Agent direct access to FocalAPI creative models**
 
 [![npm](https://img.shields.io/npm/v/focalapi-cli?color=brightgreen&label=npm)](https://www.npmjs.com/package/focalapi-cli)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
@@ -14,127 +14,111 @@ npm i -g focalapi-cli
 
 </div>
 
-focalapi-cli 把 focalapi 的创作模型中转能力变成 Agent 可直接执行的命令和
-Skills。用户只需描述目标；Agent 不需要先试模型、猜参数、手写请求或切换平台。
+focalapi-cli turns FocalAPI's creative-model gateway into commands and Skills that an Agent can run directly. Users describe the outcome they want; the Agent does not need to probe models, guess parameters, handcraft requests, or switch platforms first.
 
-它不会把 focalapi 配成 Agent 自身的主模型/provider。Codex、Claude Code、
-Cursor 等 Agent 保持原来的推理模型，只在图片、视频等创作任务中调用 focalapi。
+It does not configure FocalAPI as the Agent's primary model or provider. Agents such as Codex, Claude Code, and Cursor keep their existing reasoning models and call FocalAPI only for creative tasks such as image and video generation.
 
-## 三步接入
+## Connect in three steps
 
 ```shell
-# 1. 安装；安装器允许 lifecycle script 时会自动同步 Skills
+# 1. Install. Skills are synchronized automatically when lifecycle scripts are allowed.
 npm i -g focalapi-cli
 
-# 2. 配置 focalapi Key
+# 2. Configure a FocalAPI key.
 focalapi auth login --key sk-xxxx
 
-# 3. 接入全部已检测 Agent（幂等，自动安装过也可重复执行）并验证
+# 3. Connect every detected Agent, then verify the installation. The operation is idempotent.
 focalapi connect
 focalapi connect verify --json
 ```
 
-Key 在 <https://focalapi.com/console/token> 创建。CI/沙箱可使用
-`FOCALAPI_API_KEY`，私有化部署可设置 `FOCALAPI_BASE_URL`。
+Create a key at <https://focalapi.com/console/token>. CI and sandbox environments can use `FOCALAPI_API_KEY`; self-hosted deployments can set `FOCALAPI_BASE_URL`.
 
-如 npm 的安全策略阻止 lifecycle script，显式执行上面的 `focalapi connect` 即可；
-这也是稳定的接入入口。如需主动跳过安装后的自动接入，设置
-`FOCALAPI_SKIP_POSTINSTALL=1`。
+If an npm security policy blocks lifecycle scripts, run `focalapi connect` explicitly. This is also the stable manual integration entry point. Set `FOCALAPI_SKIP_POSTINSTALL=1` to intentionally skip automatic post-install integration.
 
-## Agent 零试错调用
+## Zero-guesswork Agent workflows
 
-不指定模型时，CLI 会读取当前 Key 的实时模型池与单模型详情契约，选择
-focalapi 维护的默认模型；只产生一次真实生成请求。
+When no model is specified, the CLI reads the live model pool and detailed model contract available to the current key, selects the maintained FocalAPI default, and sends only one real generation request.
 
 ```shell
-# 自动选择当前可用的默认图像模型
-focalapi gen image "产品主视觉，工作室柔光" -o ./out --json
+# Automatically select the current default image model.
+focalapi gen image "Product hero image, soft studio lighting" -o ./out --json
 
-# 自动选择当前可用的默认视频模型，立即返回任务 ID
-focalapi gen video "海浪拍打礁石，电影感" --no-wait -o ./out --json
+# Automatically select the current default video model and return a task ID immediately.
+focalapi gen video "Ocean waves hitting rocks, cinematic" --no-wait -o ./out --json
 
-# 沿生成结果里的 next_command 续取，不重复提交
+# Continue from next_command in the generation response without resubmitting the task.
 focalapi task status <task-id> --json
 focalapi task download <task-id> -o ./out --json
 ```
 
-用户明确指定模型时，先读取权威契约：
+When the user specifies a model, read its authoritative contract first:
 
 ```shell
 focalapi models get <model-id> --json
-focalapi gen image "<prompt>" -m <model-id> [契约允许的参数] -o ./out --json
+focalapi gen image "<prompt>" -m <model-id> [contract-supported options] -o ./out --json
 ```
 
-也可以只让 CLI 选模、暂不生成：
+The CLI can also resolve a model without generating anything:
 
 ```shell
 focalapi models resolve image --json
 focalapi models resolve video --json
 ```
 
-`resolve` 返回精确 `model.id`、已确认的 `endpoint_type`、完整
-`supported_params`、候选模型与 `next_command`。模型列表摘要和详情不一致时，
-详情契约始终是权威。
+`resolve` returns the exact `model.id`, verified `endpoint_type`, complete `supported_params`, candidate models, and a `next_command`. When a list summary and detailed contract disagree, the detailed contract is authoritative.
 
-## Agent 接入
+## Agent integration
 
 ```shell
-focalapi connect                         # 安装/修复全部已检测 Agent
-focalapi connect list                    # 只读查看支持、检测与安装状态
-focalapi connect install codex cursor    # 指定 Agent
-focalapi connect install --path <dir>    # 未收录 Agent / 项目级 Skills 目录
-focalapi connect verify --json           # Skills 完整性 + 认证就绪状态
-focalapi connect uninstall               # 只移除未被用户修改的托管 Skills
+focalapi connect                         # Install or repair every detected Agent.
+focalapi connect list                    # Inspect supported, detected, and installed targets.
+focalapi connect install codex cursor    # Install for selected Agents.
+focalapi connect install --path <dir>    # Install to an unlisted or project-level Skills directory.
+focalapi connect verify --json           # Verify Skill integrity and authentication readiness.
+focalapi connect uninstall               # Remove only managed Skills that the user has not modified.
 ```
 
-当前内置 44 个 Agent 目标，覆盖 Claude Code、Codex、Cursor、Gemini CLI、
-GitHub Copilot、OpenCode、OpenClaw、Cline、Windsurf、Warp、Trae、Qwen Code、
-Kimi CLI、Hermes 等。Codex、Cline、Pi、Warp 等共享 `~/.agents/skills` 的目标
-会按路径自动去重，只安装一份。
+The built-in catalog currently covers 44 Agent targets, including Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, OpenClaw, Cline, Windsurf, Warp, Trae, Qwen Code, Kimi CLI, and Hermes. Targets such as Codex, Cline, Pi, and Warp that share `~/.agents/skills` are deduplicated by path, so the Skills are installed only once.
 
-安装采用事务式更新：当前 `focalapi-*` catalog 整体写入，任一步失败会回滚；
-manifest 记录每个 Skill 的 SHA-256 目录摘要。默认卸载仅删除摘要未变化的托管
-Skills，用户修改过的内容保留。
+Installation is transactional: the current `focalapi-*` catalog is written as one unit, and any failed step rolls back the operation. The manifest records a SHA-256 directory digest for each Skill. By default, uninstall removes only managed Skills whose digest has not changed and preserves user-modified content.
 
-Skills 的路由契约明确要求：
+The Skill routing contract requires Agents to:
 
-- 用户没点名 focalapi 也会在创作任务中自动触发；
-- 未指定模型时省略 `--model`，由 CLI 自动选择，不先生成测试样例；
-- 指定模型时只按 `models get` 的实时参数契约调用；
-- 异步任务复用原 `task_id`，不因 `pending` 重复扣费；
-- 业务命令报鉴权错误时完成登录后回到原任务，不停在排障步骤。
+- trigger FocalAPI for creative tasks even when the user does not name it;
+- omit `--model` when no model is specified, letting the CLI select one without generating test samples;
+- use only the live parameter contract returned by `models get` for an explicitly selected model;
+- reuse the original `task_id` for asynchronous work instead of charging for duplicate submissions while a task is `pending`;
+- return to the original task after resolving an authentication error rather than stopping at diagnostics.
 
-## 当前能力边界
+## Current capability boundary
 
-当前已闭环验证的自动生成入口是图片和视频，包括图片编辑、参考图创作、文生
-视频和图生视频。CLI 仍保留文本、音频等命令，但只有实时模型详情与 CLI 帮助
-共同给出可执行契约时 Agent 才会调用；不会根据模型名字猜测未来的音频、3D 或
-其他模态能力。
+The fully validated automatic generation paths currently cover images and video, including image editing, reference-image creation, text-to-video, and image-to-video. The CLI retains text and audio commands, but an Agent may use them only when both the live model details and CLI help expose an executable contract. It never infers future audio, 3D, or other modality support from model names alone.
 
-## 面向 Agent 的稳定输出
+## Stable output for Agents
 
-- 所有自动化命令支持 `--json`，stdout 只输出 JSON，进度与诊断走 stderr；
-- 错误统一为 `{ error: { code, message, hint, request_id? } }`；
-- API Key 始终脱敏；
-- 图片结果返回本地 `files`，视频异步结果返回 `task_id` 与 `next_command`；
-- 本地校验会在发请求前拒绝已知的非法计费乘数和模型参数。
+- All automation commands support `--json`; stdout contains JSON only, while progress and diagnostics go to stderr.
+- Errors use `{ error: { code, message, hint, request_id? } }`.
+- API keys are always redacted.
+- Image results return local `files`; asynchronous video results return `task_id` and `next_command`.
+- Local validation rejects known invalid billing multipliers and model parameters before sending a request.
 
-## 命令入口
+## Command map
 
-| 任务 | 命令 |
+| Task | Command |
 | --- | --- |
-| 自动/指定模型生成图片 | `focalapi gen image` |
-| 自动/指定模型生成视频 | `focalapi gen video` |
-| 自动选模与实时契约 | `focalapi models resolve/get/search/list` |
-| 异步任务查询与下载 | `focalapi task status/download` |
-| 登录与 Key 状态 | `focalapi auth login/status/logout` |
-| 额度、用量与诊断 | `focalapi usage`, `focalapi doctor` |
-| Agent Skills 接入 | `focalapi connect` |
-| 只读原始 API | `focalapi request get/head` |
+| Generate images with automatic or explicit model selection | `focalapi gen image` |
+| Generate video with automatic or explicit model selection | `focalapi gen video` |
+| Resolve models and inspect live contracts | `focalapi models resolve/get/search/list` |
+| Check and download asynchronous tasks | `focalapi task status/download` |
+| Sign in and inspect key status | `focalapi auth login/status/logout` |
+| Inspect quota, usage, and diagnostics | `focalapi usage`, `focalapi doctor` |
+| Connect Agent Skills | `focalapi connect` |
+| Make read-only raw API requests | `focalapi request get/head` |
 
-每个命令都有内置帮助：`focalapi <command> --help`。
+Every command includes built-in help: `focalapi <command> --help`.
 
-## 开发验证
+## Development validation
 
 ```shell
 npm install
@@ -143,12 +127,12 @@ npm run build
 npm test
 ```
 
-## 链接
+## Links
 
-- focalapi：<https://focalapi.com>
-- Gitee：<https://gitee.com/xnn-ai/focalapi-cli>
-- npm：<https://www.npmjs.com/package/focalapi-cli>
-- 内置 Skills：[`./skills`](./skills)
+- FocalAPI: <https://focalapi.com>
+- GitHub: <https://github.com/focalapi/focalapi-cli>
+- npm: <https://www.npmjs.com/package/focalapi-cli>
+- Bundled Skills: [`./skills`](./skills)
 
 ## License
 

package/dist/cli.js

@@ -8,11 +8,11 @@ var ApiError = class extends Error {
   code;
   status;
   hint;
-  /** 上游返回的稳定错误代码或类型；不包含密钥等敏感请求信息。 */
+  /** Stable upstream error code or type, without sensitive request data such as keys. */
   upstreamCode;
-  /** 可用于向服务方关联日志的请求 ID。 */
+  /** Request ID that the service operator can use to correlate logs. */
   requestId;
-  /** 上游原始响应体（已截断），仅调试用途，打印前需脱敏。 */
+  /** Truncated raw upstream response for debugging only; redact it before printing. */
   body;
   constructor(code, message, opts) {
     super(message);
@@ -155,7 +155,7 @@ function displayWidth(s) {
 }
 
 // src/lib/version.ts
-var VERSION = true ? "0.2.0" : "0.0.0-dev";
+var VERSION = true ? "0.2.1" : "0.0.0-dev";
 
 // src/commands/auth.ts
 import { createInterface } from "readline/promises";
@@ -1762,8 +1762,8 @@ function registerTask(program) {
 import { writeFile as writeFile2 } from "fs/promises";
 import { resolve as resolve3 } from "path";
 function registerAudio(program) {
-  const audio = program.command("audio").description("\u97F3\u9891\uFF1A\u8F6C\u5199\u4E0E\u5408\u6210");
-  audio.command("transcribe").description("\u8BED\u97F3\u8F6C\u6587\u5B57").argument("<file>", "\u97F3\u9891\u6587\u4EF6\u8DEF\u5F84").requiredOption("-m, --model <model>", "\u8F6C\u5199\u6A21\u578B ID").option("--language <lang>", "\u8BED\u8A00\u4EE3\u7801\uFF08\u5982 zh\u3001en\uFF09").action(async (file, opts, cmd) => {
+  const audio = program.command("audio").description("\u97F3\u9891\uFF1A\u8F6C\u5199\u4E0E\u5408\u6210\uFF08\u6CA1\u6709\u9ED8\u8BA4\u6A21\u578B\uFF1B\u5148\u8FD0\u884C focalapi models list \u67E5\u770B\u5F53\u524D Key \u53EF\u7528\u7684\u97F3\u9891\u6A21\u578B\uFF09");
+  audio.command("transcribe").description("\u8BED\u97F3\u8F6C\u6587\u5B57").argument("<file>", "\u97F3\u9891\u6587\u4EF6\u8DEF\u5F84").requiredOption("-m, --model <model>", "\u8F6C\u5199\u6A21\u578B ID\uFF08\u5FC5\u586B\u3001\u65E0\u9ED8\u8BA4\u503C\uFF1B\u8FD0\u884C focalapi models list \u67E5\u770B\uFF09").option("--language <lang>", "\u8BED\u8A00\u4EE3\u7801\uFF08\u5982 zh\u3001en\uFF09").action(async (file, opts, cmd) => {
     const g = cmd.optsWithGlobals();
     const auth = resolveAuth(g);
     const input = readInputFile(file);
@@ -1784,7 +1784,7 @@ function registerAudio(program) {
       process.stdout.write((res.text ?? JSON.stringify(res)) + "\n");
     }
   });
-  audio.command("speech").description("\u6587\u5B57\u8F6C\u8BED\u97F3\uFF0C\u4EA7\u7269\u4FDD\u5B58\u4E3A\u97F3\u9891\u6587\u4EF6").argument("<text...>", "\u8981\u5408\u6210\u7684\u6587\u672C").requiredOption("-m, --model <model>", "TTS \u6A21\u578B ID").option("--voice <voice>", "\u97F3\u8272", "alloy").option("--format <fmt>", "\u97F3\u9891\u683C\u5F0F\uFF08mp3/wav/...\uFF09", "mp3").option("-o, --out <file>", "\u8F93\u51FA\u6587\u4EF6\u8DEF\u5F84").action(async (textParts, opts, cmd) => {
+  audio.command("speech").description("\u6587\u5B57\u8F6C\u8BED\u97F3\uFF0C\u4EA7\u7269\u4FDD\u5B58\u4E3A\u97F3\u9891\u6587\u4EF6").argument("<text...>", "\u8981\u5408\u6210\u7684\u6587\u672C").requiredOption("-m, --model <model>", "TTS \u6A21\u578B ID\uFF08\u5FC5\u586B\u3001\u65E0\u9ED8\u8BA4\u503C\uFF1B\u8FD0\u884C focalapi models list \u67E5\u770B\uFF09").option("--voice <voice>", "\u97F3\u8272", "alloy").option("--format <fmt>", "\u97F3\u9891\u683C\u5F0F\uFF08mp3/wav/...\uFF09", "mp3").option("-o, --out <file>", "\u8F93\u51FA\u6587\u4EF6\u8DEF\u5F84").action(async (textParts, opts, cmd) => {
     const g = cmd.optsWithGlobals();
     const auth = resolveAuth(g);
     const res = await rawRequest({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "focalapi-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "让任意 AI Agent 直接调用 focalapi 创作模型的命令行工具",
   "type": "module",
   "bin": {
@@ -38,7 +38,11 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://gitee.com/xnn-ai/focalapi-cli.git"
+    "url": "git+https://github.com/focalapi/focalapi-cli.git"
+  },
+  "homepage": "https://github.com/focalapi/focalapi-cli#readme",
+  "bugs": {
+    "url": "https://github.com/focalapi/focalapi-cli/issues"
   },
   "dependencies": {
     "commander": "^12.1.0"

package/scripts/postinstall.cjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 /**
- * npm 全局安装后的 best-effort Agent 接入。
+ * Best-effort Agent integration after global npm installation.
  *
- * 只运行本地 connect：不联网、不读取 API Key、不改 Agent provider。没有检测到
- * Agent 或接入失败都不影响 CLI 安装；用户之后可运行 focalapi connect 修复。
+ * Run local connect only: do not access the network, read an API key, or change an Agent provider.
+ * Missing Agents or integration failures never fail CLI installation; users can run focalapi connect later.
  */
 
 const { existsSync } = require('node:fs');
@@ -30,7 +30,7 @@ if (result.status === 0) {
     const count = Array.isArray(output.installed) ? output.installed.length : 0;
     if (count > 0) console.log(`focalapi-cli: 已自动接入 ${count} 个 Agent Skills 目录；重启 Agent 后生效。`);
   } catch {
-    // connect 成功但输出不可解析不影响安装。
+    // Unparseable output after a successful connect must not fail installation.
   }
   process.exit(0);
 }

package/skills/focalapi/SKILL.md

@@ -1,54 +1,47 @@
 ---
 name: focalapi
 version: 2.0.0
-description: "focalapi 创作模型总入口。当用户要生成、编辑或处理创作内容，选择创作模型，或查询生成任务时，即使用户没有提到 focalapi，也应使用本技能；覆盖图片与视频的自动选模、生成、异步续取和故障分流。"
+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 创作模型路由
+# FocalAPI creative-model routing
 
-focalapi 是供当前 Agent 调用的创作模型中转能力，不是 Agent 自身的
-model/provider。不要修改 Agent 的主模型配置，也不要要求用户先说“用 focalapi”。
+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. 用户未指定模型：直接省略 `--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` 续取，不要重复提交一个新任务。
+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
-# 用户没指定模型：一步直达，不要先试模型
-focalapi gen image "<用户提示词>" -o ./focalapi-out --json
-focalapi gen video "<用户提示词>" --no-wait -o ./focalapi-out --json
+# 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 |
 | --- | --- | --- |
-| 生图、图片编辑、参考图创作 | `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}` 修复一次，不要盲目轮换模型。
+| 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,14 +1,14 @@
 ---
 name: focalapi-auth
 version: 2.0.0
-description: "处理 focalapi-cli 安装、首次登录、Key 状态和 401/鉴权错误。仅在首次接入或业务命令明确返回 missing_api_key/invalid_api_key 时触发；认证完成后必须回到原创作任务。"
+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 认证
+# FocalAPI authentication
 
 ```bash
 npm i -g focalapi-cli
@@ -17,14 +17,12 @@ focalapi auth status --json
 focalapi connect
 ```
 
-Key 在 `https://focalapi.com/console/token` 创建。不要在回复、日志或命令回显中展示
-完整 Key；CI/沙箱优先通过 `FOCALAPI_API_KEY` 注入。
+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.
 
-业务命令未报鉴权错误时，不要每次都运行 `auth status`。命中错误后按固定路径：
+Do not run `auth status` before every business command. After an authentication error, follow this fixed path:
 
-- `missing_api_key`：登录或设置 `FOCALAPI_API_KEY`；
-- `invalid_api_key`：让用户在控制台确认/新建 Key 后重新登录；
-- `upstream_auth_failed`：本站 Key 可能正常，保留 request ID，转服务方排查；不要让
-  用户反复更换自己的 Key。
+- `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。"
+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"
 ---
 
-# focalapi 补充能力
+# Supplementary FocalAPI capabilities
 
-本技能不是创作请求的默认入口。图片、视频、改图、图生视频统一转
-`focalapi-gen`。
+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 "<用户文本任务>" -m <列表中的文本模型> --json
+focalapi chat "<user text task>" -m <text-model-from-list> --json
 ```
 
-音频命令只有在 `focalapi models get <model-id> --json` 与 `focalapi audio --help`
-共同确认可执行时才能使用：
+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
 ```
 
-模型列表里出现名称不等于 CLI 已支持调用。当前 Key 没有音频模型契约时应明确说明
-暂不可用，不要尝试相似模型或外部接口。
+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,48 @@
 ---
 name: focalapi-gen
 version: 2.0.0
-description: "用 focalapi 完成图片/视频生成、图片编辑、图生视频和参考素材创作。当用户表达画图、生图、改图、生成视频或让素材动起来时直接触发，即使未提 focalapi；默认自动选模，不先试模型。"
+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 图片与视频生成
+# FocalAPI image and video generation
 
-## 默认：自动选模，一次执行
+## Default: select automatically and run once
 
-用户没有指定模型时，直接运行：
+When the user does not specify a model, run:
 
 ```bash
-focalapi gen image "<完整提示词>" -o ./focalapi-out --json
-focalapi gen video "<完整提示词>" --no-wait -o ./focalapi-out --json
+focalapi gen image "<complete prompt>" -o ./focalapi-out --json
+focalapi gen video "<complete prompt>" --no-wait -o ./focalapi-out --json
 ```
 
-CLI 会用当前 Key 的实时模型池与详情契约选择默认模型。不要先用低成本模型、
-测试提示词或多个模型各生成一次；这会产生不必要的费用和歧义。
+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> [契约允许的参数] -o ./focalapi-out --json
-focalapi gen video "<prompt>" -m <model-id> [契约允许的参数] --no-wait -o ./focalapi-out --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
 ```
 
-- 图片编辑/参考图使用 `--image <url...>`；mask 仅在契约列出时传 `--mask`。
-- 视频参考图使用 `--image <url...>`；时长、清晰度、画面比例和音频开关只按
-  `supported_params` 传递。
-- 不把一个模型的 `ratio`、`aspect_ratio`、`size` 或 `resolution` 复制给另一模型。
-- Gemini 原生图片仅在用户明确选中对应模型时使用 `gen gemini-image`；普通任务
-  继续使用自动入口 `gen image`。
+- Use `--image <url...>` for image editing and reference images. Pass `--mask` only when the contract lists it.
+- Use `--image <url...>` for video reference images. Pass duration, resolution, aspect ratio, and audio options only as allowed by `supported_params`.
+- 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
 
-图片同步结果的 `files` 是本地绝对路径，直接交付用户。异步结果按返回的
-`next_command` 执行：
+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` / `running` 不是失败；继续查询同一个 `task_id`，不得重新提交生成。
-失败时读取结构化 `error.code` 和 `hint`，只修复明确问题，不盲目换模型。
+`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,49 @@
 ---
 name: focalapi-models
 version: 2.0.0
-description: "focalapi 创作模型选择与实时参数契约。当用户未指定模型、点名厂商/模型、比较模型，或生成参数报错时使用；默认用 resolve 直接得到可调用模型，禁止靠模型名猜能力或逐个试。"
+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 模型选择
+# FocalAPI model selection
 
-## 最短路径
+## Shortest path
 
-用户未指定模型时，不需要先列全量模型，也不需要 Agent 自己排序：
+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` 会读取当前 Key 的实时列表，再读取候选模型的详情契约，返回：
+`resolve` reads the live list available to the current key, then reads detailed contracts for candidate models and returns:
 
-- `model.id`：可直接传给生成命令的精确 ID；
-- `endpoint_type`：已由详情确认的生成端点；
-- `model.supported_params`：本次可用参数、默认值、枚举和范围；
-- `next_command`：无需猜测的下一条命令。
+- `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.
 
-如果调用 `focalapi gen image/video` 时省略 `--model`，CLI 内部执行同一选择逻辑。
+Omitting `--model` from `focalapi gen image/video` uses the same selection logic internally.
 
-## 用户指定模型
+## User-selected models
 
 ```bash
-focalapi models get <完整模型-id> --json
+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 <选中的完整-id> --json
+focalapi models get <selected-complete-id> --json
 ```
 
-规则：
+Rules:
 
-1. `models get` 是端点和参数的最终权威；列表摘要可能只展示协议族，不能据此猜模态。
-2. 不逐个模型发生成请求做可用性测试；模型发现与详情查询是只读预检。
-3. 指定模型不可用时，把可用候选交给用户或回到 `models resolve`，不要偷偷换模型。
-4. 查询完成后回到用户原始生成任务，不要停在模型清单。
+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.

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，不重复生成。"
+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"
 ---
 
-# focalapi 异步任务闭环
+# Complete asynchronous FocalAPI tasks
 
-生成命令返回 `task_id` 后，以响应里的 `next_command` 为第一选择：
+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` / `running`：仍是同一个有效任务，稍后查询；不要重提生成请求。
-- `success`：执行 download，检查文件存在，并把绝对路径交给用户。
-- `failed`：展示上游错误摘要和 hint；只有参数/内容问题被明确指出时才重新生成。
-- `unknown`：保留原始响应并运行 `focalapi doctor --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.
 
-轮询要有边界；用户没有要求阻塞等待时，汇报当前状态和 `task_id` 即可。
+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,14 +1,14 @@
 ---
 name: focalapi-usage
 version: 2.0.0
-description: "查询 focalapi 额度、用量与账单，或诊断网络、鉴权和服务错误。当用户问消费/余额，或业务命令失败且需要按错误码闭环时使用；正常生成前不强制增加诊断步骤。"
+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 用量与诊断
+# FocalAPI usage and diagnostics
 
 ```bash
 focalapi usage --json
@@ -16,12 +16,11 @@ 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。
+- 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.
 
-正常业务命令没有报错时不要先跑 doctor 或免费演练；Agent 应直接完成用户的创作
-目标，减少无关调用。
+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.