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

package/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "kling-universal",
+  "displayName": "Kling AI",
+  "version": "0.0.1-beta",
+  "description": "Create and edit images and Kling 4.0 videos with keyframes, Omni-Ref, reusable subjects, and motion control.",
+  "author": {
+    "name": "Kling AI"
+  },
+  "homepage": "https://kling.ai",
+  "license": "Proprietary",
+  "keywords": [
+    "kling",
+    "image-generation",
+    "video-generation",
+    "claude-code"
+  ],
+  "mcpServers": "./.mcp.json",
+  "skills": "./skills/"
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "name": "kling-universal",
+  "version": "0.0.1-beta",
+  "description": "Create and edit images and Kling 4.0 videos with keyframes, Omni-Ref, reusable subjects, and motion control.",
+  "author": {
+    "name": "Kling AI"
+  },
+  "homepage": "https://kling.ai",
+  "license": "Proprietary",
+  "keywords": [
+    "kling",
+    "image-generation",
+    "video-generation",
+    "codex"
+  ],
+  "mcpServers": "./.mcp.json",
+  "skills": "./skills/",
+  "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/.mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "kling-ai": {
+      "type": "http",
+      "url": "https://kling.ai/mcp/plugin",
+      "scopes": [
+        "generation.create",
+        "generation.read",
+        "account.credit.read"
+      ]
+    }
+  }
+}

package/.workbuddy-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "kling-universal",
+  "displayName": "Kling AI",
+  "version": "0.0.1-beta",
+  "description": "Create and edit images and Kling 4.0 videos with keyframes, Omni-Ref, reusable subjects, and motion control.",
+  "author": {
+    "name": "Kling AI"
+  },
+  "homepage": "https://kling.ai",
+  "license": "Proprietary",
+  "keywords": [
+    "kling",
+    "image-generation",
+    "video-generation",
+    "workbuddy"
+  ],
+  "mcpServers": "./.mcp.json",
+  "skills": "./skills/"
+}

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# Kling AI 通用安装包 / Universal Plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+可灵 AI Agent 安装包按账号区域发布为两个独立 npm 包，二者共享同一份源码，但端点在发布时固定，运行时不可切换：
+
+| 账号区域 | npm 包 | registry | 固定 MCP |
+| --- | --- | --- | --- |
+| 中国区 | `@klingai/plugin-cn` | `https://registry.npmjs.org` | `https://klingai.com/mcp/plugin` |
+| 海外区 | `@klingai/plugin-global` | `https://registry.npmjs.org` | `https://kling.ai/mcp/plugin` |
+
+支持可灵 4.0、4.0 Flash 等账号实时可用模型，覆盖图片生成与编辑、文生视频、图生视频、关键帧、全能参考、角色主体和动作控制。模型、参数和素材限制以 `who_am_i` 的实时声明为准。通用 Skill 的列表描述直接介绍创作用途，MCP 与 CLI 的执行通道由 Skill 正文选择。
+
+Skill 的目录和 frontmatter 内部名称统一为 `kling-ai-plugin`，`agents/openai.yaml` 中的显示名为 **Kling AI Plugin**。所有默认技能目录与 frontmatter 名称一致，不安装不同目录别名，避免跨目录发现产生重复菜单。复制和软连接均携带同一区域的 `dist/cli.mjs`，独立沙箱可用 Node 直接运行，无需访问桌面用户的 `~/.kling`。
+
+两个包都是分发和兼容层，不是第二个可灵产品或第二套 MCP App UI。每个包同时提供：
+
+- 与所选账号区域一致的预构建 `kling` CLI；
+- 原生 Host 使用的 `kling-ai` 远端 MCP 注册（域名带 `/mcp/plugin` 后缀）；
+- 可被 Agent 自动触发的一个 Skill：`kling-ai-plugin`，包含图片、视频和素材管理；
+- Agent Plugins 1.0、Codex、Claude Code、WorkBuddy 兼容清单；
+- 面向主流本地 Agent Host 与开放 Agent Skills 生态的 `npx` 安装器，并提供任意 Skill 目录兜底。
+
+## 云端应用导入
+
+Manus Studio 与 Grok Bot 的执行电脑不在桌面用户目录中，不能用本地 `--skills-dir` 自动安装到云端。当前 CN PRT 已实际导入并执行随 Skill 附带的 CLI，版本为 `0.4.13-beta.6`；不代表收费业务、Global 或 MCP App UI 已验收。
+
+内网正式端点构建同时输出两份可导入 ZIP，路径见构建结果 JSON：
+
+| 字段 | 导入目标 | ZIP 布局 |
+| --- | --- | --- |
+| `skillArchive` | Manus 等要求根目录技能文件的宿主 | 根目录包含 `SKILL.md`、对应区域 `dist/cli.mjs` 和版本元数据 |
+| `claudeSkillArchive` | Claude 主界面的 `Customize → Skills` | 顶层 `kling-ai-plugin/` 文件夹，完整运行时位于 `lib/kling-cli/`，封装使用相对导入，避免 Claude 拒绝含 `@` 的 npm 路径 |
+
+发布构建机需提供 `zip`；这是构建工具，不是安装包运行时依赖。已构建的 npm 包也可单独导出，Claude 无需再手动调整 ZIP：
+
+```bash
+node plugin/scripts/export-skill.mjs /绝对路径/已构建的plugin /绝对路径/新建的skill.zip
+node plugin/scripts/export-skill.mjs /绝对路径/已构建的plugin /绝对路径/新建的claude-skill.zip --format claude
+```
+
+普通 `pnpm build:plugin` 也会生成 `plugin/archives/claude-skill.zip`；发布的 npm 包携带同一路径 `archives/claude-skill.zip`，可直接上传到 Claude。该 ZIP 是构建时的区域 CLI 快照；重新执行本地安装器不会更新已导入 Claude 的账号侧副本，需要用新版 ZIP 替换。
+
+- Manus Studio：更多 → 技能 → 创建 → 上传技能。导入 ZIP 后在“我的技能”启用自动生效，再新建会话。实际菜单仅一项 `kling-ai-plugin`，加载 `/home/ubuntu/skills/kling-ai-plugin/SKILL.md`，便携 CLI 已在应用终端执行成功。仅导入但未挂载时，菜单可见不等于可调用。
+- Grok Bot：通过附件上传 ZIP，在 Bot 云端安装到其用户 Skill 目录；本次由应用确认目录为 `/home/box/agent-data/workflows/kling-ai-plugin`，frontmatter 保留 `kling-ai-plugin`。已检查正常目录索引加载及可见终端的版本/退出码；Grok 没有本地 slash 技能菜单，本轮不能宣称菜单名称验收通过。不要据此新增猜测的桌面目录。
+- TRAE CN：本机应用未成功启动出窗口；Antigravity：账号地区资格限制。两者尚未完成应用调用验收，不新增默认安装目标。
+
+## 安装
+
+插件自带对应区域的 CLI：构建时由 `kling-cli/src` 打包为 `dist/cli.js`，区域端点在构建时写死，不依赖 `@klingai/cli-*` 包，也不随它们的 `latest` 变化。持久化命令为 `~/.kling/bin/kling-plugin`（私有 wrapper，不是 npm bin），固定使用 `/mcp/plugin`；Skill 另带同一份单文件 CLI（`dist/cli.mjs`），无需 `node_modules`。升级会移除本插件托管的旧 `kling`、`kling-ai-plugin` wrapper。安装后安装器会把 `kling-plugin` 链接到 PATH 中一个已有且可写的目录（优先 `~/.local/bin`、`/opt/homebrew/bin`、`/usr/local/bin`），不改 shell 配置、不覆盖非本包托管的同名文件；没有合适目录时会提示把 `~/.kling/bin` 加入 PATH，卸载时移除该链接。Skill 只使用插件持久化封装或自带封装；PATH 中独立 `kling` 不作为插件回退，独立 CLI 也不会被插件覆盖。
+
+```bash
+npx --yes --registry=https://registry.npmjs.org @klingai/plugin-cn@beta doctor --host codex
+~/.kling/bin/kling-plugin --version
+```
+
+Codex 的 `doctor` 会额外报告旧版 Kling 插件、marketplace 和远端 MCP 注册。Codex、Claude Code 的 `doctor` 还会核对 Host 实际启用的插件版本，Pi 会核对包级注册；目录型 Host 则核对通用 Skill 的托管标记与版本。普通 `install --host codex` 会自动执行同一套有备份的迁移；也可以预先查看或单独执行。
+
+Claude Code 若启用了其他提供 `kling-ai` MCP 的插件，安装预检会阻止显式 `--host claude` 安装；批量安装会跳过 Claude 并继续其他 Host。`doctor` 也会报告该冲突，但不会擅自卸载不属于本包管理的插件。所有 Host 的 `doctor` 都不能证明账号已登录、当前会话已刷新或 AI 已调用 Skill。请在对应 Host 的技能列表中新开会话核对通用 Skill；无法登录的 Host 不能视为通过界面验收。
+
+Cursor 同时发现共享目录和 Claude 用户技能目录。不同目录标识可以显示为相同的技能名称，形成两个入口；本包现在统一目录名与 frontmatter 为 `kling-ai-plugin`，升级时移除托管的 `kling-universal` 与 `Kling AI Plugin` 旧标识。旧版跨 Host 的实测记录见验收文档；此次改名后的菜单和调用显示需要重新验收。独立旧插件与非托管副本不会被清理；其他重复项须先确认实际来源，`doctor` 不替代菜单唯一性验收。
+
+完整卸载使用一条命令，无需区分 npm 本地或全局安装：
+
+```bash
+npx --yes --registry=https://registry.npmjs.org @klingai/plugin-cn@beta uninstall
+```
+
+开发验收可运行 `node plugin/scripts/verify-uninstall.mjs /绝对路径/package.tgz`，在隔离目录验证多个项目、全局 prefix、保留用户数据和重复卸载。`verify-host-discovery.mjs` 还会检查真实 Host 在安装后能发现 Skill、完整卸载后不再发现 Skill；追加旧版压缩包路径作为第二个参数，可验证从三个入口升级为一个入口以及旧入口不再被 Host 发现。
+
+该命令移除本包托管的所有 Host Skill（含记录的自定义目录）、持久化 `kling` CLI、插件文件与找到的本地/全局 npm 包；凭据、日志、其他 Skill 和非本包的同名可执行文件保留。支持 npm workspace 的根项目与子项目依赖声明；即使 `node_modules` 或包目录已删除，也会清理声明及指向本包的失效 npm 命令链接。原生注册通过 Host 的插件清单核对，尊重 `CODEX_HOME`、`CLAUDE_CONFIG_DIR`、`PI_CODING_AGENT_DIR`，注销后再次检查。可先使用 `uninstall --dry-run` 查看计划。失败会非零退出并保留持久化安装器与记录，方便重试，不会报告“已完整卸载”。
+
+从 0.4.11 起，安装器记录 npm 包与 Skill 目录，支持清理多个项目或自定义全局 prefix 的安装。对于没有记录的旧版本，请在原 npm 安装项目目录执行；命令会检查当前目录的父级项目及 npm 当前全局位置，不扫描整块磁盘。npx 下载缓存由 npm 管理，不作为已安装插件清理。
+
+显式指定 Host 仍只卸载对应集成，不移除 npm 包；卸载不会删除 `~/.kling/.credentials` 或历史日志：
+
+```bash
+npx --yes --registry=https://registry.npmjs.org @klingai/plugin-cn@beta uninstall --host codex
+```
+
+## MCP 与 Skill
+
+每个区域包只做两件事：
+
+1. **原生远端 MCP 注册**：插件清单中的 `kling-ai` 直接连接该区域固定的、带 `plugin` 后缀的 Streamable HTTP MCP（中国区 `https://klingai.com/mcp/plugin`，海外区 `https://kling.ai/mcp/plugin`）。npm 包不复制、重写或发布 HTML，也不提供 stdio Bridge。
+2. **给各 Host 安装 Skill**：通用 Skill 的目录名和 frontmatter 统一为 `kling-ai-plugin`，用户显示名为 `Kling AI Plugin`；内部插件注册 ID 为 `kling-universal`。
+
+UI 是否出现由 Host 决定，npm/CLI 不能替 Host 增加 iframe 渲染能力。一次生成只能选择原生 MCP 或 CLI 其中一条通道，避免重复扣费。
+
+## 运行限制
+
+- `@klingai/plugin-cn` 固定连接中国区 `https://klingai.com`；`@klingai/plugin-global` 固定连接海外区 `https://kling.ai`。
+- 两个包不提供环境变量或配置文件切区；换区必须安装另一个包并重新完成对应账号授权。
+- Host 的网络或文件沙箱仍然生效；受限模式下可能需要用户批准访问网络与 `~/.kling`。
+- Node.js 18 或更高版本。

package/bin/plugin.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+import {
+  PACKAGE_NAME,
+  PLUGIN_BASE_URL,
+  PLUGIN_DISPLAY_NAME,
+  SUPPORTED_HOSTS,
+  DEFAULT_SKILL_HOSTS,
+  createInstallPlan,
+  displayPath,
+  doctor,
+  doctorSkillDirectory,
+  exposeCommand,
+  installHost,
+  installSkillDirectory,
+  parseArgs,
+  preflightInstallHosts,
+  resolveInstallHosts,
+  removeManagedObsoleteSkills,
+  stagePackage,
+  uninstallHost,
+  uninstallSkillDirectory,
+} from '../lib/install.mjs';
+import { uninstallAll } from '../lib/uninstall.mjs';
+
+function reportCommand(wrapper) {
+  console.log(`CLI: ${displayPath(wrapper)}`);
+  if (process.platform === 'win32') return;
+  const result = exposeCommand(wrapper);
+  if (result.status === 'linked') console.log(`Command: ${displayPath(result.path)} -> kling-plugin is available in new terminals`);
+  else if (result.status === 'conflict') console.log(`Command: kling-plugin was not linked (${result.reason}); run ${displayPath(wrapper)} directly or remove that file`);
+  else if (result.status === 'not-on-path') console.log(`Command: add ~/.kling/bin to PATH to run kling-plugin, e.g. echo 'export PATH="$HOME/.kling/bin:$PATH"' >> ~/.zshrc`);
+}
+
+function usage() {
+  const installerName = PACKAGE_NAME.split('/').at(-1);
+  return [
+    `${PLUGIN_DISPLAY_NAME} installer`,
+    '',
+    'Usage:',
+    `  ${installerName} install  # Install Skills for the checked Host set`,
+    `  ${installerName} install --host <${DEFAULT_SKILL_HOSTS.join('|')}|all>`,
+    `  ${installerName} install --skills-dir <path>`,
+    `  ${installerName} install --host <directory-host> --link-skills`,
+    `  ${installerName} install [--host <host>] --dry-run`,
+    `  ${installerName} doctor --host <host|all>`,
+    `  ${installerName} doctor --skills-dir <path>`,
+    `  ${installerName} uninstall [--dry-run]  # Remove all managed Skills, CLI and npm installs`,
+    `  ${installerName} uninstall --host <host> [--purge]`,
+    `  ${installerName} uninstall --skills-dir <path> [--purge]`,
+    '',
+    `${PACKAGE_NAME} has a fixed endpoint: ${PLUGIN_BASE_URL}.`,
+  ].join('\n');
+}
+
+try {
+  const { command, host, skillsDir, purge, dryRun, linkSkills } = parseArgs(process.argv.slice(2));
+  const installOptions = { skillsOnly: !host || host === 'all' };
+  if (command === 'help' || command === '--help' || command === '-h') {
+    console.log(usage());
+    process.exitCode = 0;
+  } else if (!host && !skillsDir && command !== 'install' && command !== 'uninstall') {
+    throw new Error(`--host or --skills-dir is required. Choose: ${SUPPORTED_HOSTS.join(', ')}, all`);
+  } else if (command === 'install') {
+    if (skillsDir) {
+      if (dryRun) {
+        console.log(JSON.stringify({
+          ...createInstallPlan([]),
+          customSkillsDir: displayPath(skillsDir),
+        }, null, 2));
+        process.exitCode = 0;
+      } else {
+        const staged = stagePackage();
+        const result = installSkillDirectory(skillsDir, staged, { linkSkills });
+        console.log(`[written] custom: ${displayPath(result.path)}`);
+        reportCommand(staged.wrapper);
+        console.log('Skill files written; Host discovery is not verified. Restart the Host or reload Skills, then start a new session.');
+      }
+    } else {
+      const hosts = resolveInstallHosts(host);
+      if (host && host !== 'all' && !DEFAULT_SKILL_HOSTS.includes(host) && host !== 'agents') {
+        console.error(`Unverified Host target: ${host}. This writes Skill files only; application discovery and invocation have not passed acceptance.`);
+      }
+      const preflight = preflightInstallHosts(hosts, { ...installOptions, linkSkills });
+      if (dryRun) {
+        console.log(JSON.stringify({ ...createInstallPlan(hosts, installOptions), preflight }, null, 2));
+        process.exitCode = 0;
+      } else {
+        const failedPreflight = preflight.filter((result) => result.status === 'failed');
+        const unavailable = preflight.filter((result) => result.status === 'unavailable');
+        const conflicts = preflight.filter((result) => result.status === 'conflict');
+        if (failedPreflight.length > 0 || (host !== 'all' && host !== undefined && (unavailable.length > 0 || conflicts.length > 0))) {
+          const reasons = [...failedPreflight, ...unavailable, ...conflicts]
+            .map((result) => `${result.host}: ${result.reason}`)
+            .join('; ');
+          throw new Error(`Install preflight failed: ${reasons}`);
+        }
+
+        const installableHosts = preflight
+          .filter((result) => result.status === 'ready')
+          .map((result) => result.host);
+        if (installableHosts.length === 0) {
+          throw new Error('No available Host remained after install preflight');
+        }
+
+        const staged = stagePackage();
+        const results = [...unavailable, ...conflicts].map((result) => ({
+          host: result.host,
+          status: 'skipped',
+          reason: result.reason,
+        }));
+        for (const item of installableHosts) {
+          try {
+            const result = installHost(item, staged, { ...installOptions, linkSkills });
+            results.push({ host: item, status: result.status, path: result.path });
+          } catch (error) {
+            results.push({ host: item, status: 'failed', reason: error.message });
+          }
+        }
+
+        console.log('Install summary:');
+        for (const result of results) {
+          const detail = result.path ? displayPath(result.path) : result.reason;
+          const status = result.status === 'installed' && (installOptions.skillsOnly || !['codex', 'claude', 'pi'].includes(result.host))
+            ? 'written' : result.status;
+          console.log(`  [${status}] ${result.host}: ${detail}`);
+        }
+        reportCommand(staged.wrapper);
+        console.log('Host discovery and invocation are not verified by installation. Restart the Host or reload Skills, then start a new session.');
+        if (results.some((result) => result.host === 'workbuddy' && result.status === 'installed')) {
+          console.log(`WorkBuddy: look for Kling AI Plugin under Installed Skills (user-defined); the plugin marketplace is separate.`);
+        }
+        if (!installOptions.skillsOnly && results.some((result) => result.host === 'codex' && result.status === 'installed')) {
+          console.log('Codex MCP OAuth is separate from kling login. Check: codex mcp list; if kling-ai is Not logged in, run: codex mcp login kling-ai. Then restart Codex and open a new session. UI rendering still depends on the Host.');
+        }
+
+        const failures = results.filter((result) => result.status === 'failed');
+        if (failures.length > 0) {
+          throw new Error(`${failures.length} Host installation${failures.length === 1 ? '' : 's'} failed`);
+        }
+        if (installOptions.skillsOnly) removeManagedObsoleteSkills(staged);
+      }
+    }
+  } else if (command === 'doctor') {
+    if (skillsDir) {
+      const result = doctorSkillDirectory(skillsDir);
+      console.log(JSON.stringify(result, null, 2));
+      if (!result.ok) process.exitCode = 1;
+    } else {
+      let result;
+      if (host === 'all') {
+        const plan = createInstallPlan(resolveInstallHosts('all'), { skillsOnly: true });
+        const results = plan.hosts.map(({ host: item, target }) => ({
+          host: item, path: target, ...doctor(item, { skillsOnly: true }),
+        }));
+        result = { ok: results.every((item) => item.ok), hosts: results };
+      } else {
+        result = doctor(host);
+      }
+      console.log(JSON.stringify(result, null, 2));
+      if (!result.ok) process.exitCode = 1;
+    }
+  } else if (command === 'uninstall') {
+    if (!host && !skillsDir) {
+      console.log(JSON.stringify(uninstallAll({ dryRun }), null, 2));
+    } else if (skillsDir) {
+      uninstallSkillDirectory(skillsDir, { purge });
+    } else {
+      const hosts = host === 'all' ? resolveInstallHosts('all', { includeUnverified: true }) : [host];
+      for (const item of hosts) uninstallHost(item, { skillsOnly: host === 'all', purge: purge && item === hosts.at(-1) });
+    }
+    if (host || skillsDir) console.log('Plugin registration removed. OAuth credentials and logs were preserved.');
+  } else {
+    throw new Error(`Unknown command: ${command}\n\n${usage()}`);
+  }
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+}

package/bin/postinstall.mjs

@@ -0,0 +1,16 @@
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { recordNpmInstallation } from '../lib/install.mjs';
+
+// npm exec / npx runs the user's installer arguments after fetching the package.
+// Installing here would turn --dry-run and single-Host operations into full installs.
+if (process.env.npm_command !== 'exec') {
+  const result = spawnSync(
+    process.execPath,
+    [fileURLToPath(new URL('./plugin.mjs', import.meta.url)), 'install'],
+    { stdio: 'inherit' },
+  );
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+  if (result.status === 0) recordNpmInstallation(fileURLToPath(new URL('..', import.meta.url)));
+}