@klingai/plugin-cn 0.0.0-stage → 0.0.1-beta

package/skills/kling-ai-plugin/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@klingai/plugin-cn",
+  "version": "0.0.1-beta",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
+  }
+}

package/skills/kling-ai-plugin/reference.md

@@ -0,0 +1,90 @@
+# MCP 工具响应字段速查
+
+完整协议与示例见同目录 **`api-examples.md`**。CLI 返回 `{ ok, status, body }`，`body` 为工具结果（已自动解析 JSON 文本块）。
+
+> 响应字段统一 **camelCase**（服务端契约）；旧版服务端可能仍返回 snake_case 同义字段（如 `generation_id`），CLI 两种都能解析，Agent 读取输出时按同一字段理解。
+
+`kling-plugin <command> --help` 对 MCP-backed 命令会尽量展示该工具的实时 `tools/list` 声明（工具说明 + inputSchema）；获取失败时回退本地静态用法。完整模型清单与参数规格见下方 `who_am_i`。
+
+## who_am_i（能力发现）
+
+- **`user.userId`**：当前用户 ID（来自 JWT）。
+- **`availableModels`**：工具名 → 模型能力清单；空 `{}` 表示服务端尚未配置。
+  - **`[].model`**：模型名（生成命令 `--model` 的合法取值）。
+  - **`[].alias`**：对外别名（可能不出现）。
+  - **`[].description`**：模型说明，**Agent 选型的主要依据**（适用场景、是否推荐等；可能不出现）。
+  - **`[].arguments[]`**：`{ name, required, default?, allowedValues?, description?, maxItems? }`；`maxItems` 为数组参数的项数上限，由服务端校验。
+  - **`[].inputs[]`**：`{ name, required, description? }`（参考资源声明）。
+- **模型项的 `combinedItemCap`**：`{ maxItems, arguments, inputPrefixes }`，合并统计匹配输入名前缀的素材，以及指定 JSON 数组参数（如 `elements`）的项数；CLI 在上传/提交前校验。V4 关键帧当前合计 10 张，Omni-Ref 素材/主体合计 15 个，不等于输入槽位数；音频是否支持并计数，以所选模型的 `inputs` / `inputPrefixes` 为准。
+- **`combinedItemCaps[]`**：额外的条件组合上限；`whenAnyInputPrefixes` 表示存在任一匹配输入时生效，`whenNoneInputPrefixes` 表示不存在匹配输入时生效。CLI 检查所有匹配的规则。O1 / O3 当前无视频时图片+主体 ≤7，有视频时 ≤4。
+- **`elementSupport`**：主体类型支持、总数/分类型数量上限以及声音一致性等结构化说明，help 原样保留，具体主体组合由服务端校验。
+- **`authMode`**：鉴权模式（OAuth 登录态下为 `oauth`）。
+
+## 生成工具提交成功后（text_to_image / image_to_image / text_to_video / image_to_video / omni_ref_video / motion_control）
+
+- **`generationId`**：不透明生成 ID，用于 `query_tasks` 轮询。
+- **`status`**：初始状态（下游透传，如 `submitted` / `QUEUING`）。
+- **`creditsConsumed`**：本次消耗的灵感值（可能不出现）。
+
+## query_tasks
+
+- **`generationId`**：回显查询 ID。
+- **`status`**：任务整体状态（下游透传字符串，**大小写不敏感处理**）：
+  - 中间态：`QUEUING` / `RUNNING` / `submitted` / `processing`
+  - 成功终态：`COMPLETED` / `PARTIAL_COMPLETED` / `succeed`
+  - 失败终态：`FAILED` / `CANCELLED` 等
+- **`createTime`** / **`finishTime`**：毫秒时间戳（未完成时 finishTime 为 0）。
+- **`works[]`**：产出列表：
+  - **`status`**：单个产出状态。
+  - **`contentType`**：`image` / `video`。
+  - **`url`**：资源 URL（带水印，默认展示）。
+  - **`urlWithoutWatermark`**：无水印资源 URL（用户要求时展示）。
+  - **`coverUrl`** / **`coverUrlWithoutWatermark`**：封面 URL。
+
+## file_upload（两步式）
+
+- 第一步（MCP 工具）返回：**`ticket`**（一次性票据）、**`uploadUrl`**（上传地址）、**`expireAt`**（过期时间戳）。
+- 第二步由 CLI 自动完成：multipart POST（`ticket` + `file`）到 `uploadUrl`，CLI 会把响应中的文件 URL 规整到 `body.url`。
+- 上传请求按文件大小计算总预算：120 秒基础时间 + 按 64 KiB/s 估算的传输时间（50 MiB 为 920 秒），覆盖传输及读取响应；手动上传和生成命令自动上传共用此逻辑，不自动重试。客户端超时不等于服务端拒绝文件大小，实际格式和体积限制仍以服务端声明及响应为准。
+- 上传成功必须返回可用的文件 URL；即使 HTTP 为 200，响应缺少文件 URL 也按失败处理，并保留服务端原始响应。
+
+## Element 工具
+
+- **`element_create`**：返回持久 Element `id`；图片资源为 `cover` + 1–3 个 `secondary[]`，视频资源为 `video`，两者可选 `voice`。
+- **`element_list`**：每项仅含 `id` / `name`；完整类型与资源需再调 `element_get`。
+- **`element_get`**：返回完整 `name` / `description` / `resource` / `tags`。
+- **`element_update`**：CLI 先读取现有 Element，再把用户提供的可选字段合并成完整 payload；图片 Element 强制回填原 `resource.cover`，不接受 `--cover`。
+- **`element_delete`**：按 `id` 删除持久 Element。
+
+## motion_library_list / motion_control
+
+- **`motion_library_list`**：每项含 `id`、`name`、动作 URL、可选封面、毫秒时长和是否含音频。
+- **`motion_control`**：返回与其他生成工具相同的 `generationId` / `status` / `creditsConsumed`，后续用 `query_tasks`。
+
+## feedback
+
+- 返回服务端确认信息；该工具只记录反馈，不会重试、退款或修复原任务。
+- `extra` 可回显关联的 `generationId[]` / `modelVersion[]` / `taskTraceId[]`。
+
+## account（query_membership_and_credits 直通）
+
+当前账号级查询不接受工作区选择。响应没有工作区 ID、角色或计费主体，`userId` 不能代替工作区 ID，`availableRemainCredits` 不能认定为团队余额或团队可消费权限。相关边界见 [SKILL.md](SKILL.md#个人--团队工作区权限与计费边界)。
+
+- **`userId`**：用户 ID。
+- **`membershipType`**：会员身份（`NORMAL` / `VIP` / `SVIP` / `SSVIP` / `SSSVIP`）。
+- **生成前检查**：紧邻每次收费生成前调用；查询失败、工具不可用、无法确认余额、零余额、已知不足或明确无资格时不提交。会员等级不能推导模型权限，正余额不能保证足额；未知价格不编造，最终资格与扣费由服务端校验。详见 [SKILL.md](SKILL.md#生成前检查)。
+- **`availableRemainCredits`**：可用灵感值（用户可见值，无需换算）。`0` 或过低时，按「余额不足与充值」引导用户充值。
+- **充值 / 会员链接**：不在响应 body 里，而在该工具的 **description（`tools/list` 元数据）** 中由服务端动态提供。需要引导充值时取用该链接，**勿在本地写死**（详见 SKILL「余额不足与充值」）。
+
+## tool_list（MCP tools/list）
+
+- **`body.tools[]`**：后端 MCP server 当前暴露的工具清单。
+- **`name`**：工具名；CLI 的 canonical 业务命令通常与后端 MCP 工具名 1:1。
+- **`description`**：服务端提供的工具说明；商业化链接等动态说明以这里为准，勿在本地写死。
+- **`inputSchema`**：该工具的 JSON Schema 输入声明，用于排障或确认服务端实际支持的参数。
+
+## CLI 轮询结果（--poll / query_tasks --poll）
+
+- **`body.polled`**：true 表示这是轮询聚合结果。
+- **`body.timedOut`**：是否超时（超时后可继续 `query_tasks <generationId>`）。
+- **`body.generations[]`**：`{ generationId, status, result }`，`result` 即最后一次 query_tasks 的返回体。

package/skills/kling-ai-plugin/region.md

@@ -0,0 +1,9 @@
+# Kling AI distribution region
+
+- Region: cn
+- npm package: `@klingai/plugin-cn`
+- Website: https://klingai.com
+- MCP endpoint: https://klingai.com/mcp/plugin
+- Reinstall: `npx --yes @klingai/plugin-cn@beta install --host <host>`
+
+This package has a fixed region. Do not switch endpoints at runtime.