@klingai/plugin-global 0.0.0-stage → 0.0.2-beta

package/lib/region-data.mjs

@@ -0,0 +1,48 @@
+export const PLUGIN_REGIONS = Object.freeze({
+  "cn": {
+    "id": "cn",
+    "packageName": "@klingai/plugin-cn",
+    "baseUrl": "https://klingai.com",
+    "mcpUrl": "https://klingai.com/mcp/plugin",
+    "marketplaceName": "kling-internal",
+    "displayName": "可灵 AI",
+    "description": "Kling AI image and video creation with Kling 4.0, reusable subjects, and motion control",
+    "manifestDescription": "使用可灵 AI 生成和编辑图片、创作可灵 4.0 视频，支持关键帧、全能参考、角色主体与动作控制。",
+    "hostDescription": "使用可灵 AI 生成和编辑图片、创作可灵 4.0 视频，支持关键帧、全能参考、角色主体与动作控制。",
+    "shortDescription": "一句话，让灵感从想法变成大片",
+    "longDescription": "使用可灵 AI 生成和编辑图片，以可灵 4.0、4.0 Flash 等可用模型创作视频，支持关键帧、全能参考、角色主体与动作控制，并管理素材、任务和灵感值。",
+    "defaultPrompts": [
+      "生成一张电影感图片：一只小萨摩耶在开满野花的草地上快乐奔跑，阳光逆光，毛发细节清晰",
+      "使用可灵 4.0 生成一段 5 秒电影感视频：机甲战士从空中落地，碎石与尘土飞散，镜头快速推进",
+      "查询我的可灵任务状态，只查询，不创建新的生成任务"
+    ],
+    "publishConfig": {
+      "access": "public",
+      "registry": "https://registry.npmjs.org/",
+      "tag": "latest"
+    }
+  },
+  "global": {
+    "id": "global",
+    "packageName": "@klingai/plugin-global",
+    "baseUrl": "https://kling.ai",
+    "mcpUrl": "https://kling.ai/mcp/plugin",
+    "marketplaceName": "kling-global",
+    "displayName": "Kling AI",
+    "description": "Kling AI image and video creation with Kling 4.0, reusable subjects, and motion control",
+    "manifestDescription": "Create and edit images and Kling 4.0 videos with keyframes, Omni-Ref, reusable subjects, and motion control.",
+    "hostDescription": "Create and edit images and Kling 4.0 videos with keyframes, Omni-Ref, reusable subjects, and motion control.",
+    "shortDescription": "Turn ideas into cinematic art",
+    "longDescription": "Create and edit images and videos with available Kling 4.0 and 4.0 Flash models, keyframes, Omni-Ref, reusable subjects, and motion control. Manage assets, tasks, and credits.",
+    "defaultPrompts": [
+      "Generate a cinematic image of a Samoyed running through a wildflower meadow in warm backlight with detailed fur",
+      "Use Kling 4.0 to generate a 5-second cinematic video of a mech warrior landing as rocks and dust scatter and the camera pushes in",
+      "Check the status of my Kling AI tasks without creating a new generation"
+    ],
+    "publishConfig": {
+      "access": "public",
+      "registry": "https://registry.npmjs.org/",
+      "tag": "latest"
+    }
+  }
+});

package/lib/region.mjs

@@ -0,0 +1,16 @@
+import { PLUGIN_REGIONS } from './region-data.mjs';
+
+export { PLUGIN_REGIONS };
+
+export function pluginRegion(id) {
+  const region = PLUGIN_REGIONS[id];
+  if (!region) throw new Error(`Unknown plugin region: ${id}`);
+  return region;
+}
+
+export function pluginRegionForPackage(packageName) {
+  if (packageName === '@klingai/plugin') return PLUGIN_REGIONS.cn;
+  const region = Object.values(PLUGIN_REGIONS).find((item) => item.packageName === packageName);
+  if (!region) throw new Error(`Unsupported plugin package name: ${packageName}`);
+  return region;
+}

package/lib/uninstall.mjs

@@ -0,0 +1,236 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync, readlinkSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import {
+  ALL_SKILL_HOST_PATHS, LEGACY_PLUGIN_NAME, LEGACY_SKILL_NAMES, PLUGIN_NAME,
+  SKILL_NAMES, isManagedSkill, readInstallState, removeExposedCommand, uninstallSkillDirectory,
+} from './install.mjs';
+import { PLUGIN_REGIONS } from './region.mjs';
+
+const PACKAGE_NAMES = ['@klingai/plugin', ...Object.values(PLUGIN_REGIONS).map((item) => item.packageName)];
+
+function readJsonFile(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    throw new Error(`Cannot read JSON configuration: ${path}`);
+  }
+}
+
+function manifest(path) {
+  const file = join(path, 'package.json');
+  return existsSync(file) ? readJsonFile(file) : undefined;
+}
+
+function npm(args, options) {
+  if (options.runNpm) return options.runNpm(args);
+  const cli = process.env.npm_execpath && join(dirname(process.env.npm_execpath), 'npm-cli.js');
+  return cli && existsSync(cli)
+    ? spawnSync(process.execPath, [cli, ...args], { encoding: 'utf8' })
+    : spawnSync('npm', args, { encoding: 'utf8' });
+}
+
+function nativeHomes(userHome, options) {
+  const env = options.userHome === undefined ? process.env : {};
+  return {
+    codex: resolve(options.codexHome ?? env.CODEX_HOME ?? join(userHome, '.codex')),
+    claude: resolve(options.claudeHome ?? env.CLAUDE_CONFIG_DIR ?? join(userHome, '.claude')),
+    pi: resolve(options.piHome ?? env.PI_CODING_AGENT_DIR ?? join(userHome, '.pi', 'agent')),
+  };
+}
+
+function nativeEnvironment(userHome, homes) {
+  return { ...process.env, HOME: userHome, CODEX_HOME: homes.codex, CLAUDE_CONFIG_DIR: homes.claude, PI_CODING_AGENT_DIR: homes.pi };
+}
+
+function nativeJson(command, args, userHome, homes, options) {
+  const result = options.captureNative
+    ? options.captureNative(command, args)
+    : spawnSync(command, args, { encoding: 'utf8', cwd: options.cwd, env: nativeEnvironment(userHome, homes) });
+  if (result.status !== 0) throw new Error(`Cannot inspect ${command} registrations; no shared files were removed`);
+  try { return JSON.parse(result.stdout); } catch { throw new Error(`Invalid registration response from ${command}`); }
+}
+
+function nativeActions(userHome, homes, pluginRoot, options, verify = false) {
+  const actions = [];
+  const marketplaces = Object.values(PLUGIN_REGIONS).map((item) => item.marketplaceName);
+  const ids = marketplaces.flatMap((marketplace) => [PLUGIN_NAME, LEGACY_PLUGIN_NAME].map((name) => `${name}@${marketplace}`));
+  const codexConfig = join(homes.codex, 'config.toml');
+  const codex = existsSync(codexConfig) ? readFileSync(codexConfig, 'utf8') : '';
+  const codexCache = marketplaces.some((marketplace) => [PLUGIN_NAME, LEGACY_PLUGIN_NAME].some((name) => existsSync(join(homes.codex, 'plugins', 'cache', marketplace, name))));
+  if (codexCache || marketplaces.some((name) => codex.includes(name))) {
+    const inventory = nativeJson('codex', ['plugin', 'list', '--json'], userHome, homes, options);
+    const sources = nativeJson('codex', ['plugin', 'marketplace', 'list', '--json'], userHome, homes, options);
+    if (!Array.isArray(inventory.installed) || !Array.isArray(sources.marketplaces)) throw new Error('Cannot verify Codex registration inventory');
+    const installed = new Set(inventory.installed.filter((item) => item.installed).map((item) => item.pluginId));
+    // Codex itself parses/removes TOML keys, including quoted and dotted forms.
+    for (const id of ids) {
+      if (installed.has(id) || (!verify && codex.includes(id))) actions.push({ command: 'codex', args: ['plugin', 'remove', id, '--json'] });
+    }
+    for (const item of sources.marketplaces) {
+      if (marketplaces.includes(item.name)) actions.push({ command: 'codex', args: ['plugin', 'marketplace', 'remove', item.name] });
+    }
+  }
+  const claudeSettings = join(homes.claude, 'settings.json');
+  const claude = existsSync(claudeSettings) ? readJsonFile(claudeSettings).enabledPlugins ?? {} : {};
+  const marketplaceFile = join(homes.claude, 'plugins', 'known_marketplaces.json');
+  const claudeMarketplaces = existsSync(marketplaceFile) ? readJsonFile(marketplaceFile) : {};
+  const installedFile = join(homes.claude, 'plugins', 'installed_plugins.json');
+  const claudeInstalled = existsSync(installedFile) ? readJsonFile(installedFile).plugins ?? {} : {};
+  if (ids.some((id) => Object.hasOwn(claude, id) || Object.hasOwn(claudeInstalled, id)) || marketplaces.some((name) => Object.hasOwn(claudeMarketplaces, name))) {
+    const inventory = nativeJson('claude', ['plugin', 'list', '--json'], userHome, homes, options);
+    if (!Array.isArray(inventory)) throw new Error('Cannot verify Claude registration inventory');
+    for (const item of inventory) {
+      if (ids.includes(item.id) && (item.scope ?? 'user') === 'user') actions.push({ command: 'claude', args: ['plugin', 'uninstall', item.id, '--scope', 'user'] });
+    }
+    for (const marketplace of marketplaces) {
+      if (Object.hasOwn(claudeMarketplaces, marketplace)) actions.push({ command: 'claude', args: ['plugin', 'marketplace', 'remove', marketplace] });
+    }
+  }
+  const piSettings = join(homes.pi, 'settings.json');
+  if (existsSync(piSettings)) {
+    const packages = readJsonFile(piSettings).packages ?? [];
+    for (const item of packages) {
+      const source = typeof item === 'string' ? item : item.source;
+      const npmSource = PACKAGE_NAMES.some((name) => source === `npm:${name}` || source?.startsWith(`npm:${name}@`));
+      const localSource = typeof source === 'string' && resolve(homes.pi, source.startsWith('~/') ? join(userHome, source.slice(2)) : source) === pluginRoot;
+      if (localSource || npmSource) {
+        actions.push({ command: 'pi', args: ['remove', localSource ? pluginRoot : source] });
+      }
+    }
+  }
+  return actions;
+}
+
+function npmLinks(item) {
+  const bin = item.global ? (process.platform === 'win32' ? item.prefix : join(item.prefix, 'bin')) : join(item.prefix, 'node_modules', '.bin');
+  const entries = [
+    [item.name.split('/').at(-1), 'bin/plugin.mjs'], ['kling-agent-plugin', 'bin/plugin.mjs'],
+    ['kling-ai-plugin', 'dist/cli.js'], ['kling', 'dist/cli.js'],
+  ];
+  return entries.flatMap(([name, target]) => {
+    const path = join(bin, name);
+    return lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink()
+      && resolve(dirname(path), readlinkSync(path)) === join(item.path, target) ? [path] : [];
+  });
+}
+
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'];
+function declared(prefix, name, options, cache = new Map()) {
+  if (!cache.has(prefix)) {
+    const project = manifest(prefix);
+    let projects = [project];
+    if (project?.workspaces) {
+      const result = npm(['pkg', 'get', ...DEPENDENCY_FIELDS, '--prefix', prefix, '--workspaces', '--include-workspace-root', '--json'], options);
+      if (result.status !== 0) throw new Error(`Cannot inspect workspace dependencies: ${prefix}`);
+      try { projects = Object.values(JSON.parse(result.stdout)); } catch { throw new Error(`Invalid workspace dependency response: ${prefix}`); }
+    }
+    cache.set(prefix, new Set(projects.flatMap((item) => DEPENDENCY_FIELDS.flatMap((field) => Object.keys(item?.[field] ?? {})))));
+  }
+  return cache.get(prefix).has(name);
+}
+
+export function createUninstallPlan(options = {}) {
+  const userHome = resolve(options.userHome ?? homedir());
+  const klingHome = resolve(options.klingHome ?? process.env.KLING_HOME ?? join(userHome, '.kling'));
+  const base = join(klingHome, 'plugins', PLUGIN_NAME);
+  const pluginRoot = join(base, 'current');
+  const state = readInstallState(klingHome);
+  if (existsSync(pluginRoot) && !PACKAGE_NAMES.includes(manifest(pluginRoot)?.name)) {
+    throw new Error(`Refusing to remove an unmanaged package: ${pluginRoot}`);
+  }
+  const homes = nativeHomes(userHome, options);
+  const skillsRoots = [...new Set([
+    ...Object.values(ALL_SKILL_HOST_PATHS).map((parts) => join(userHome, ...parts)),
+    join(homes.codex, 'skills'), join(homes.claude, 'skills'), join(homes.pi, 'skills'),
+    ...state.skills,
+  ])];
+  const npmPackages = new Map();
+  const declarations = new Map();
+  function add(path, global = false, prefix, recordedName) {
+    const data = manifest(path);
+    if (data && !PACKAGE_NAMES.includes(data.name)) return;
+    if (basename(dirname(dirname(path))) !== 'node_modules') return;
+    const parent = dirname(dirname(dirname(path)));
+    const expectedPrefix = global && basename(parent) === 'lib' ? dirname(parent) : parent;
+    if (prefix && resolve(prefix) !== expectedPrefix) throw new Error(`Invalid npm install prefix: ${path}`);
+    const name = data?.name ?? recordedName ?? PACKAGE_NAMES.find((name) => path.endsWith(join(...name.split('/'))));
+    if (!PACKAGE_NAMES.includes(name)) return;
+    const item = { name, path: resolve(path), prefix: expectedPrefix, global };
+    const cliName = name.replace('/plugin-', '/cli-');
+    const recordedCli = recordedName && !global && cliName !== name
+      && manifest(join(expectedPrefix, 'node_modules', ...cliName.split('/')))?.name === cliName;
+    if (!data && (global || !declared(expectedPrefix, name, options, declarations)) && npmLinks(item).length === 0 && !recordedCli) return;
+    npmPackages.set(resolve(path), item);
+  }
+  for (const item of state.npm) add(item.path, item.global, item.prefix, item.name);
+  // Existing releases did not record npm installs. Find the current project,
+  // its ancestors, and npm's active global prefix without scanning user files.
+  for (let cwd = resolve(options.cwd ?? process.cwd()); ; cwd = dirname(cwd)) {
+    for (const name of PACKAGE_NAMES) add(join(cwd, 'node_modules', ...name.split('/')));
+    if (dirname(cwd) === cwd) break;
+  }
+  const global = npm(['root', '--global'], options);
+  if (global.status !== 0 || !global.stdout.trim()) throw new Error('Cannot locate global npm packages; no files were removed');
+  for (const name of PACKAGE_NAMES) add(join(global.stdout.trim(), ...name.split('/')), true);
+  return {
+    userHome, klingHome, base, pluginRoot, skillsRoots, nativeHomes: homes,
+    npmPackages: [...npmPackages.values()], nativeActions: nativeActions(userHome, homes, pluginRoot, options),
+    preserved: [join(klingHome, '.credentials'), join(klingHome, 'logs')],
+  };
+}
+
+export function uninstallAll(options = {}) {
+  const plan = createUninstallPlan(options);
+  if (options.dryRun) return { dryRun: true, ...plan };
+  for (const action of plan.nativeActions) {
+    const result = options.runNative
+      ? options.runNative(action.command, action.args)
+      : spawnSync(action.command, action.args, { encoding: 'utf8', cwd: options.cwd, env: nativeEnvironment(plan.userHome, plan.nativeHomes) });
+    if (result.status !== 0) throw new Error(`Unable to unregister ${action.command}; shared CLI and Skills were preserved`);
+  }
+  if (plan.nativeActions.length > 0 && nativeActions(plan.userHome, plan.nativeHomes, plan.pluginRoot, options, true).length > 0) {
+    throw new Error('Native registrations remain after uninstall; shared CLI and Skills were preserved');
+  }
+  // npm failures leave the durable installer and all Skills available for retry.
+  for (const item of plan.npmPackages) {
+    const args = ['uninstall', item.name, '--prefix', item.prefix, '--ignore-scripts', '--no-audit', '--no-fund'];
+    args.push(item.global ? '--global' : '--no-global');
+    if (!item.global && manifest(item.prefix)?.workspaces) args.push('--workspaces', '--include-workspace-root');
+    if (npm(args, options).status !== 0 || PACKAGE_NAMES.includes(manifest(item.path)?.name) || (!item.global && declared(item.prefix, item.name, options))) {
+      throw new Error(`npm uninstall failed: ${item.name} at ${item.prefix}; shared CLI and Skills were preserved`);
+    }
+    for (const path of npmLinks(item)) rmSync(path);
+    // A manually deleted workspace Plugin can leave its hoisted CLI behind.
+    // Let npm retain shared dependencies; never remove a declared standalone CLI.
+    const cliName = item.name.replace('/plugin-', '/cli-');
+    const cliPath = join(item.prefix, 'node_modules', ...cliName.split('/'));
+    if (!item.global && cliName !== item.name && manifest(cliPath)?.name === cliName && !declared(item.prefix, cliName, options)) {
+      const result = npm(['uninstall', cliName, '--prefix', item.prefix, '--no-global', '--no-save', '--ignore-scripts', '--no-audit', '--no-fund'], options);
+      if (result.status !== 0) throw new Error(`npm CLI dependency cleanup failed at ${item.prefix}; shared CLI and Skills were preserved`);
+      if (!existsSync(cliPath)) for (const path of npmLinks({ ...item, name: cliName, path: cliPath })) rmSync(path);
+    }
+  }
+  for (const skillsRoot of plan.skillsRoots) {
+    uninstallSkillDirectory(skillsRoot, { userHome: plan.userHome, klingHome: plan.klingHome });
+  }
+  for (const skillsRoot of plan.skillsRoots) {
+    for (const name of [...SKILL_NAMES, ...LEGACY_SKILL_NAMES]) {
+      if (isManagedSkill(join(skillsRoot, name), plan.pluginRoot)) throw new Error(`Managed Skill remains: ${join(skillsRoot, name)}`);
+    }
+  }
+  const preservedExecutables = [];
+  for (const name of ['kling-plugin', 'kling-plugin.cmd', 'kling-ai-plugin', 'kling-ai-plugin.cmd', 'kling', 'kling.cmd']) {
+    const path = join(plan.klingHome, 'bin', name);
+    if (!existsSync(path)) continue;
+    if (/managed-by: @klingai\/plugin(?:-family)?/.test(readFileSync(path, 'utf8'))) rmSync(path);
+    else preservedExecutables.push(path);
+  }
+  removeExposedCommand(plan.klingHome, options);
+  rmSync(plan.base, { recursive: true, force: true });
+  return {
+    status: 'uninstalled', skillDirectories: plan.skillsRoots.length,
+    npmPackages: plan.npmPackages, preserved: plan.preserved, preservedExecutables,
+  };
+}

package/mcp.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "kling-ai": {
+      "type": "streamable-http",
+      "url": "https://kling.ai/mcp/plugin",
+      "extensions": {
+        "com.openai": {
+          "auth": {
+            "type": "oauth",
+            "client": {
+              "mode": "dcr"
+            },
+            "baseScopes": [
+              "generation.create",
+              "generation.read",
+              "account.credit.read"
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@klingai/plugin-global",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2-beta",
+  "private": false,
+  "description": "Kling AI image and video creation with Kling 4.0, reusable subjects, and motion control",
+  "type": "module",
+  "bin": {
+    "plugin-global": "bin/plugin.mjs"
+  },
+  "files": [
+    ".mcp.json",
+    ".claude-plugin",
+    ".codex-plugin",
+    ".workbuddy-plugin",
+    "archives",
+    "assets",
+    "bin",
+    "dist",
+    "lib",
+    "mcp.json",
+    "plugin.json",
+    "README.md",
+    "skills"
+  ],
+  "scripts": {
+    "postinstall": "node bin/postinstall.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
+  },
+  "license": "UNLICENSED",
+  "keywords": [
+    "agent-plugin",
+    "kling-ai",
+    "kling-universal",
+    "skill",
+    "cli",
+    "codex",
+    "claude-code",
+    "cursor",
+    "gemini-cli",
+    "github-copilot",
+    "opencode",
+    "qwen-code",
+    "cline",
+    "roo-code",
+    "windsurf",
+    "agent-skills",
+    "kiro",
+    "junie",
+    "factory-droid",
+    "trae",
+    "qoder",
+    "codebuddy",
+    "kimi-code",
+    "pi",
+    "workbuddy"
+  ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/plugin.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "kling-universal",
+  "version": "0.0.2-beta",
+  "description": "Create and edit images and Kling 4.0 videos with keyframes, Omni-Ref, reusable subjects, and motion control.",
+  "author": {
+    "name": "Kling AI"
+  },
+  "license": "Proprietary",
+  "homepage": "https://kling.ai",
+  "keywords": [
+    "kling",
+    "image generation",
+    "video generation",
+    "agent skill",
+    "cli"
+  ],
+  "extensions": {
+    "com.openai": {
+      "interface": {
+        "displayName": "Kling AI",
+        "shortDescription": "Turn ideas into cinematic art",
+        "longDescription": "Create and edit images and videos with available Kling 4.0 and 4.0 Flash models, keyframes, Omni-Ref, reusable subjects, and motion control. Manage assets, tasks, and credits.",
+        "developerName": "Kling AI",
+        "category": "Creativity",
+        "capabilities": [
+          "Interactive",
+          "Read",
+          "Write"
+        ],
+        "websiteURL": "https://kling.ai",
+        "defaultPrompt": [
+          "Generate a cinematic image of a Samoyed running through a wildflower meadow in warm backlight with detailed fur",
+          "Use Kling 4.0 to generate a 5-second cinematic video of a mech warrior landing as rocks and dust scatter and the camera pushes in",
+          "Check the status of my Kling AI tasks without creating a new generation"
+        ],
+        "brandColor": "#000000",
+        "logo": "./assets/kling-logo.png",
+        "logoDark": "./assets/kling-logo.png",
+        "composerIcon": "./assets/kling-logo.png"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,154 @@
+---
+name: kling-ai-plugin
+description: >-
+  使用可灵 AI 生成和编辑图片、创作视频、复用角色主体、控制动作，并管理素材、任务和灵感值。
+  支持可灵 4.0、4.0 Flash 等账号实时可用模型，涵盖文生图、图生图、文生视频、图生视频、关键帧和全能参考。
+---
+
+# Kling AI Plugin
+
+本安装包向原生插件 Host 注册当前账号区域的 `kling-ai` 远端 MCP，并为不支持原生 MCP 的 Host 提供同区域 Kling Plugin。安装包名称、网站和固定 MCP 端点见 [region.md](region.md)；该远端端点是工具、结果和 MCP App UI 的唯一运行时来源，npm 包不维护第二份 UI。业务调用必须通过 Host 暴露的 MCP 工具或 CLI 完成；不要自行请求网页接口、业务 HTTP API 或绕过 Host 直连远端 MCP 端点。
+
+## 单一展示所有者（所有 Host，优先级最高）
+
+同一次生成只能有一个“展示和刷新所有者”，否则会出现两张结果卡片或重复文字。
+
+**1. MCP App widget 已挂载时，widget 是唯一所有者。** 走 MCP 通道，生成工具结果带 `_meta.ui.resourceUri` 且 Host 实现 MCP Apps iframe（卡片实际显示）时视为已挂载。**ChatGPT 例外：一律按未挂载处理**（视频卡片曾出现空白，模型无法确认卡片是否真的显示），走第 2 条；宁可多一份文字链接，也不能让用户拿不到成品。其余已挂载情形：
+- 不为同一次提交调用 `query_tasks`、`query_result`，也不用 `--poll`；widget 在内部查询并原位刷新。
+- 不再追加第二张卡片、缩略图、重复预览或重复的结果链接；只补一句简短状态（已提交/处理中），并把 `generationId` 显示为任务编号。
+- 用户之后明确要求“查看结果/进度”时，才对已有任务查询一次，并按「成品交付」给出链接。
+
+**2. widget 未挂载时，才由文字结果承担展示。** CLI 通道、Host 不支持 MCP Apps、ChatGPT、卡片空白或加载失败时视为未挂载：按下文轮询原任务，并按「成品交付」提供链接，不因此重新生成或换通道。
+
+**3. 通道唯一。** 一次任务只用一条通道，不并行走 CLI 或其他连接器，避免重复生成与重复扣费。额度预检（`query_membership_and_credits` / `account`）是只读查询，不产生展示，可照常执行。
+
+## 选择执行通道
+
+- Host 已启用本插件的 `kling-ai` MCP Server：优先调用该 Server 暴露的 MCP 工具。若 Host 实现 MCP Apps iframe，则根据工具的 `_meta.ui.resourceUri` 读取 `resources/read` 返回的官方 MCP App；否则展示同一工具的文本或结构化结果。
+- Codex/ChatGPT 等 Host 安装或升级 MCP 清单后必须重启并新开会话；已有会话没有出现组件时，不要把 basic-host 截图当作 Host 验收。ChatGPT 云端 UI 还需要已注册的远端 MCP 插件/连接器，不能由本地 `npx` 安装替代。
+- 用户明确要求 CLI，或 Host 没有可用的 MCP 工具：使用下方的内置 CLI。缺少 MCP Apps UI 渲染能力不等于缺少 MCP 工具能力。
+- 运行时只保留一个 `kling-ai` MCP 身份；一次任务只选择一个通道，禁止对同一生成请求同时调用 CLI 和其他连接器（见「单一展示所有者」第 3 条）。
+
+## 选择 CLI
+
+插件自带对应区域的 CLI，持久化命令为 `kling-plugin`，固定使用 `/mcp/plugin`。必须选择下述插件持久化命令或 Skill 自带封装；PATH 中独立 CLI 的 `kling` 走 `/mcp`，不能代替插件封装。
+
+按以下顺序选择命令，找到第一个可执行项后在本次任务中保持一致：
+
+```bash
+test -x "${KLING_HOME:-$HOME/.kling}/bin/kling-plugin" && printf '%s\n' "${KLING_HOME:-$HOME/.kling}/bin/kling-plugin"
+```
+
+记住选中的可执行文件路径。下文和示例文档中的 `kling-plugin` 只是命令占位符；实际调用必须替换为该路径（优先 `~/.kling/bin/kling-plugin` 的实际展开路径），不要假设安装器已把它加入 `PATH`，也不要误用其他区域的同名 CLI。
+
+若持久化命令不可用（例如 Host 将技能复制到独立沙箱），使用本 Skill 自带的 [dist/cli.mjs](dist/cli.mjs)：`node "<当前 Skill 实际目录>/dist/cli.mjs" <命令与参数>`。该文件是与安装包相同的区域 CLI，已内置全部依赖，单个文件即可运行；无需重新下载。以 Host 加载技能时给出的实际目录为准，不使用桌面用户的绝对路径。
+
+若沙箱缺少 Node 或随 Skill 附带的 CLI 文件，停止并报告具体缺项。不要声称版本检查成功，也不要自动安装运行环境。普通本机安装损坏时，读取 [region.md](region.md) 并使用其中的 `Reinstall` 命令重新安装当前区域插件。不要把中国区 `@klingai/plugin-cn` 与海外区 `@klingai/plugin-global` 混装。
+
+不要自动改装其他区域的 Plugin 或 CLI，也不要在运行时覆盖端点。
+
+## 登录与能力发现
+
+首次使用或登录失效时运行：
+
+```bash
+kling-plugin login
+kling-plugin who_am_i
+```
+
+`login` 会打开浏览器完成 OAuth。不得读取浏览器 Cookie、让用户粘贴 token、请求 AK/SK，或打印凭据。
+
+每个新会话先用 `who_am_i` 获取当前可用模型和参数。服务端能力不清楚时用 `kling-plugin tool_list`；单个命令参数用 `kling-plugin <command> --help`。
+
+## 生成前检查
+
+- 生成前读取实时 `tools/list` 和 `who_am_i`（CLI 使用 `tool_list` 与 `who_am_i`）；同一会话已读取且没有不兼容迹象时可复用。`mcpVersion` 较新本身不阻断，也不要求新会话或重新登录；只有目标工具缺失、实时 schema 冲突或宿主明确提示工具列表过期时刷新声明，仍不兼容则报告并停止，保留当前需求与参数。
+- 紧邻每次收费生成（包括多步骤任务的每一步及用户授权的重试）前，调用 `query_membership_and_credits`，CLI 使用 `account`。查询失败、工具不可用、无法确认余额、明确零余额、已知额度不足或返回的会员/模型资格被拒绝时停止，不提交。
+- 资格仅按服务端明确返回的契约判断，不凭会员等级推断；未返回资格字段不等于无资格，也不证明权限。不得编造价格或把正余额当作足额保证，最终资格、额度和扣费由服务端校验。不得为绕过限制静默换模型、降低规格或重试，改变计费设置须先取得用户确认。
+- 只读查询、上传和素材管理无需生成额度预检；保持原有计费授权与单次提交规则。
+
+## 调用约束
+
+- 生成调用必须显式指定 `model`，CLI 使用 `--model <名称>`；模型名以 `who_am_i` 为准。
+- 生成会消耗灵感值；提交前确认 prompt、模型和素材，不要自行改参重投。
+- 生成命令返回 `generationId` 后：MCP widget 已挂载时遵循「单一展示所有者」，不轮询；否则用 `kling-plugin query_tasks <generationId>` 轮询，或提交时加 `--poll [秒数]`。
+- 完成后按下方「成品交付」展示预览和可点击的结果链接；需要无水印且响应提供时使用 `works[].urlWithoutWatermark`。
+- 本地图片可直接传给图生类命令，CLI 会负责上传。
+- 非交互环境缺少必填参数时应报错，不要等待 stdin。
+
+常用命令：
+
+```text
+who_am_i
+text_to_image
+image_to_image
+text_to_video
+image_to_video
+omni_ref_video
+motion_control
+motion_library_list
+element_create / element_list / element_get / element_update / element_delete
+query_tasks
+file_upload
+account
+feedback
+logout
+```
+
+完整参数和示例见 [reference.md](reference.md) 与 [api-examples.md](api-examples.md)。
+
+## 成品交付（所有 Host，包括 ChatGPT）
+
+本节适用于 widget 未挂载，或用户明确要求查看已有任务结果时；widget 已挂载的新提交以「单一展示所有者」为准，不重复追加链接或卡片。
+
+- 从原任务 `query_tasks` 的真实返回中提取每个已完成作品的 `works[].url`。最终回复必须逐项提供普通 Markdown 文字链接，例如 `[观看视频](实际返回的作品 URL)` 或 `[查看图片](实际返回的作品 URL)`；无论原生组件或内嵌预览是否显示，都保留这些链接，不能只说「已生成」、只给 generationId 或只显示预览卡片。多作品按序编号。
+- 图片可同时使用图片预览；视频优先使用 Host 支持的原生媒体展示或官方 MCP App 播放器。不要把视频 URL 写成以 `!` 开头的 Markdown 图片语法；封面只能标为封面，不能冒充可播放成品。普通文字链接不依赖 Host 的媒体预览能力。
+- ChatGPT 等 Host 不支持预览、出现空白卡片或用户反馈加载失败时，明确提示「可通过下方链接打开查看」，再次提供原作品链接。不因展示失败重新生成、切换执行通道或额外扣费。
+- 用户要求无水印且响应提供 `urlWithoutWatermark` 时链接该字段；否则使用 `url`。服务端若另有明确返回的可灵作品详情页/分享链接，可同时附上并标为「可灵作品页」；媒体直链标为「观看视频」或「查看图片」。不得根据 generationId、作品 ID、官网首页或区域域名猜测、拼接作品页地址，不把媒体直链称为作品页。
+- 成功状态但没有可用作品 URL 时，明确说明「任务已完成，但未返回可用成品链接」，保留 generationId 便于后续只读查询；不得编造链接或宣称成品已可查看。部分完成时只交付实际返回的可用作品，并说明其余作品的实际状态。
+
+## 图片生成与编辑
+
+- 新建图片用 `text_to_image`；素材需要控制主体、结构、构图或风格时用 `image_to_image`。
+- 使用 `who_am_i` 返回的实时能力指定 `model`（CLI 使用 `--model`）；不使用已移除的模型简写。
+- 参考图要明确各自的身份、结构、风格或构图作用，并保持重复 `--image` 参数的顺序。
+- 编辑请求要同时写明“改什么”和“保留什么”；保留人物身份、商品几何、Logo 和用户提供的准确文字。
+- 默认只生成一张，除非用户明确要求多张。提交前查询灵感值（MCP 使用 `query_membership_and_credits`，CLI 使用 `account`），付费请求最多提交一次，不得因质量问题自动重生成。
+- 拿到 `generationId` 后，在 widget 未挂载时用 `query_tasks` 或 `--poll` 等待原任务（widget 已挂载时不轮询，见「单一展示所有者」），不另起新任务。
+
+图片调用示例：
+
+```bash
+kling-plugin text_to_image --model <who_am_i 返回的模型> "提示词"
+kling-plugin image_to_image --model <who_am_i 返回的模型> --image ./reference.png "修改要求与保留项"
+```
+
+## 视频生成与动作控制
+
+- 无控制素材时用 `text_to_video`；动画化图片或使用首尾帧时用 `image_to_video`。
+- 混合图片、视频或 Element 主体参考时用 `omni_ref_video`；用视频或已保存动作驱动主体时用 `motion_control`。
+- 使用 `who_am_i` 返回的实时能力指定 `model`（CLI 使用 `--model`）；不使用 `--omni` 或 `--flash` 简写。
+- 提示词按时间写清开场状态、主体动作、镜头运动和结束状态。保留人物身份、服饰、商品几何和画面方向。
+- 只在模型实时声明支持时传递时长、比例、音频和多镜头参数；不复用其他模型的参数。
+- 提交前查询灵感值（MCP 使用 `query_membership_and_credits`，CLI 使用 `account`），付费请求最多提交一次，不自动换模型、改素材或重生成。
+- 拿到 `generationId` 后，在 widget 未挂载时用 `query_tasks` 或 `--poll` 等待原任务（widget 已挂载时不轮询，见「单一展示所有者」）；用户只要查状态时不创建生成。
+
+### 可灵 4.0 与 4.0 Flash
+
+- 先用 `who_am_i` 查询目标工具的模型清单；标准版为 `kling-video-v4_0`，Flash 为 `kling-video-v4_0_flash`。用户指定 4.0 时不自动换成 Flash；模型未出现在该工具清单时报告不可用，不换模型提交。
+- 纯文本创作走 `text_to_video`；首帧、尾帧和中间关键帧走 `image_to_video`；图、视频、音频及主体混合参考走 `omni_ref_video`，不要把混合参考塞进关键帧入口。
+- 标准版关键帧按实时声明使用 `first_image`、`tail_image`、`keyframe_*`。CLI 的中间帧使用 `--input <槽位名>=<url或路径>`，不可与 `--image` / `--tailImage` 混用。Flash 的 `image_to_video` 只接首帧，不接尾帧或主体；其全能参考能力以 `omni_ref_video` 的单独声明为准。
+- 时长、分辨率、素材数量及音频支持均读取目标模型声明。全能参考按秒计费，提交前告知用户参考视频时长也计入总计费时长；保留参考原声时，`keepOriginalSound=true` 与 `enable_audio=false` 配套使用。
+
+视频调用示例：
+
+```bash
+kling-plugin text_to_video --model <who_am_i 返回的模型> "提示词"
+kling-plugin image_to_video --model <who_am_i 返回的模型> --image ./first-frame.png "运动与镜头要求"
+```
+
+## MCP 与 UI 边界
+
+这个 npm 插件提供 **CLI + Skill + MCP Apps 原生远端注册**。插件清单让 Host 直接连接远端 MCP 并获取 `tools/list`、`tools/call`、`resources/list`、`resources/read` 与 UI 元数据。只有实现 MCP Apps iframe 的 Host 才会渲染原生 UI；其他 Host 使用同一工具调用的文本/结构化结果或 CLI。ChatGPT 云端对话内 UI 需要另外注册远端 MCP 插件/连接器。本地 `npx` 安装不能给 Host 补充 UI 渲染能力。
+
+技能目录名、frontmatter 和菜单名称统一为 `kling-ai-plugin`，不再为单个 Host 安装不同目录别名，避免 Cursor 等跨目录发现时产生两个同名入口。MCP Server 统一使用 `kling-ai`，正式环境不保留两套可灵 MCP。

package/skills/kling-ai-plugin/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Kling AI Plugin"
+  short_description: "Create images and Kling 4.0 videos; manage assets and tasks"
+  default_prompt: "Use Kling AI Plugin to check my Kling AI authorization and task status."
+policy:
+  allow_implicit_invocation: true