@baomihuatop/popcorn-cli 0.1.0

package/README.md

@@ -0,0 +1,130 @@
+# popcorn-cli
+
+Popcorn 官方命令行客户端。通过本地配置的 API Key 调用 Popcorn 服务，用于查询可用模型、提交生图 / 生视频任务，以及查询任务状态和结果。
+
+## 安装
+
+需要 Node.js 18 或更高版本。
+
+```bash
+npm install -g @baomihuatop/popcorn-cli
+```
+
+安装后确认命令可用：
+
+```bash
+popcorn-cli --version
+popcorn-cli --help
+```
+
+## 配置 API Key
+
+```bash
+popcorn-cli config set-key <YOUR_API_KEY>
+```
+
+查看当前配置：
+
+```bash
+popcorn-cli config show
+```
+
+API Key 会保存在本机配置文件中：`~/.popcorn-cli/config.json`。
+
+## 查询可用模型
+
+提交任务前，先查询当前 API Key 可用的模型和参数 schema。
+
+```bash
+popcorn-cli image models
+popcorn-cli video models
+```
+
+返回内容包含模型信息、使用限制和提交任务所需的参数结构。
+
+## 提交任务
+
+生图任务：
+
+```bash
+popcorn-cli image submit -p '{"model":"sd-xl-v1","prompt":"a cat"}'
+```
+
+生视频任务：
+
+```bash
+popcorn-cli video submit -p '{"model":"video-model-id","prompt":"a cinematic cat"}'
+```
+
+关联会话 ID：
+
+```bash
+popcorn-cli image submit -s <SESSION_ID> -p '{"model":"sd-xl-v1","prompt":"a cat"}'
+```
+
+`-p, --params` 必须是 JSON 对象字符串。具体字段以 `image models` / `video models` 返回的 `params_schema` 为准。
+
+## 查询任务
+
+按任务 ID 查询单个任务：
+
+```bash
+popcorn-cli task list -t <TASK_ID>
+```
+
+按会话 ID 查询该会话下的任务：
+
+```bash
+popcorn-cli task list -s <SESSION_ID>
+```
+
+## 常用命令
+
+| 命令 | 说明 |
+|------|------|
+| `popcorn-cli config set-key <apiKey>` | 设置 API Key |
+| `popcorn-cli config show` | 查看当前配置 |
+| `popcorn-cli image models` | 查询可用生图模型 |
+| `popcorn-cli image submit -p <JSON>` | 提交生图任务 |
+| `popcorn-cli video models` | 查询可用生视频模型 |
+| `popcorn-cli video submit -p <JSON>` | 提交生视频任务 |
+| `popcorn-cli task list -t <TASK_ID>` | 按任务 ID 查询任务 |
+| `popcorn-cli task list -s <SESSION_ID>` | 按会话 ID 查询任务 |
+
+所有命令都支持 `--help`：
+
+```bash
+popcorn-cli --help
+popcorn-cli image --help
+popcorn-cli image submit --help
+```
+
+## 升级
+
+```bash
+npm install -g @baomihuatop/popcorn-cli@latest
+```
+
+## 卸载
+
+```bash
+npm uninstall -g @baomihuatop/popcorn-cli
+```
+
+## 常见问题
+
+`popcorn-cli: command not found`
+
+确认 npm 全局安装目录已加入 `PATH`，或重新打开终端后再试。
+
+`未设置 API Key`
+
+先执行：
+
+```bash
+popcorn-cli config set-key <YOUR_API_KEY>
+```
+
+`params 不是合法的 JSON`
+
+`-p` 参数必须传入合法 JSON 对象字符串，建议用单引号包裹完整 JSON。

package/agents/skills/popcorn-cli/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: popcorn-cli
+description: popcorn-cli 是爆米花系统（Popcorn）的官方 CLI。需要生图、生视频时即可使用本工具：通过本地 API Key 查询可用模型、异步提交任务、按会话/任务 ID 查询最终结果。当要在终端、脚本或 Agent 流程中完成生图/生视频相关能力时使用此 skill。
+version: 0.1.0
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - popcorn-cli
+      config:
+        - ~/.popcorn-cli/config.json
+    install:
+      - kind: node
+        package: "@baomihuatop/popcorn-cli"
+        bins:
+          - popcorn-cli
+    skillKey: popcorn-cli
+    emoji: "🎬"
+    homepage: https://mangaforge-qa-1255521909.cos.ap-shanghai.myqcloud.com/docs/popcorn-cli/popcorn-cli-installation-guide.html
+---
+
+# popcorn-cli
+
+**popcorn-cli 是爆米花（Popcorn）的命令行客户端；需要生图、生视频时，直接使用本 CLI 即可完成模型查询、任务提交与结果查询。** 按任务类型分组组织命令，面向脚本化、自动化和 Agent 场景。
+
+## 概念
+
+- **会话（session）**：一次业务上下文，`session_id` 由调用方生成（例如一次剧本推进、一次 Agent 会话）。同一 session 下可提交多个任务，便于统一追踪。
+- **任务（task）**：一次具体的生成请求。`submit` 为异步接口，提交后立刻返回 `task_id`（不含最终结果）；须再用 `task list` 按 `task_id` / `session_id` 查询状态与结果。
+- **模型（model）**：每个任务类型下有多个可用模型，模型自带使用限制（时长、分辨率等）。可用模型清单与 API Key 所属租户绑定，仅返回当前租户开通且启用中的模型。提交任务前建议先用 `<group> models` 查询目标场景的可用模型。
+
+## 能力概览
+
+**模型查询 / 任务提交**（按任务类型两级分组，当前均为 mock 实现，接口签名一致）：
+
+| 任务类型 | 查询模型 | 提交任务 |
+|----------|----------|----------|
+| 生图 | `popcorn-cli image models` | `popcorn-cli image submit` |
+| 生视频 | `popcorn-cli video models` | `popcorn-cli video submit` |
+
+所有 `models` / `submit` 子命令的参数与返回结构在各任务类型间完全一致，见下文「命令详情」小节。
+
+**任务查询**（跨任务类型统一入口；用于获取 `submit` 异步任务的最终结果）：
+
+| 命令 | 说明 |
+|------|------|
+| `popcorn-cli task list --sid <id>` | 查询某会话下的所有任务 |
+| `popcorn-cli task list --tid <id>` | 查询单个任务（含 status / result） |
+
+**配置管理**：
+
+| 命令 | 说明 |
+|------|------|
+| `popcorn-cli config show` | 查看当前生效的配置 |
+| `popcorn-cli config set-key <apiKey>` | 设置 API Key |
+
+## 认证与配置
+
+CLI 不接受在命令行显式传入 API Key，统一从本地配置读取。
+
+**配置文件位置**：`~/.popcorn-cli/config.json`
+
+**配置字段**：
+
+| 字段 | 说明 |
+|------|------|
+| `apiKey` | API Key，请求时通过 `X-API-Key` 头传给后端 |
+
+## 命令详情
+
+### 查询模型：`image models` / `video models`
+
+查询某任务类型下当前租户可用的模型（仅返回当前 API Key 所属租户 + 场景匹配 + 启用中 + 非历史版本）。提交任务前应先调用本命令。
+
+```bash
+popcorn-cli <image|video> models
+```
+
+无参数。返回结构：
+
+```jsonc
+{
+  "type": "image",
+  "total": 2,
+  "models": [
+    {
+      "model_id":    "...",   // 模型唯一标识
+      "name":        "...",   // 展示名
+      "description": "...",   // 简介
+      "model_limit": { ... }  // 单模型使用限制（不同模型可能不同）
+    }
+  ],
+  "params_schema": { ... }    // 该场景 submit 时 --params 的字段结构（同场景所有模型共用）
+}
+```
+
+`params_schema` 是 JSON Schema 风格描述，说明 `submit --params` 可用的字段、类型、默认值。同一场景（image / video）下所有模型共用一份。
+
+**推荐流程**：如果不清楚模型跟入参,先 `<group> models` 查看当前租户可用模型清单和 `params_schema`，据此选定 `model_id`，再结合 `params_schema` 的字段构造 `submit` 的 `--params`。
+
+### 提交任务：`image submit` / `video submit`
+
+两类任务的 `submit` 子命令签名一致，仅调用不同后端接口。
+
+> **异步接口**：`submit` 仅负责入队，立即返回 `task_id` 等受理信息，**不会等待生成完成，也不包含最终结果**。拿到 `task_id`（或传入的 `session_id`）后，须通过下方 `task list` 轮询任务状态，待 `status` 为终态后再读取 `result` / `error_message`。
+
+```bash
+popcorn-cli <image|video> submit -p <JSON> [-s <SESSION_ID>]
+```
+
+| 参数 | 缩写 | 必填 | 说明 |
+|------|------|------|------|
+| `--params` | `-p` | 是 | 任务参数，必须是 JSON 对象字符串 |
+| `--sid` | `-s` | 否 | 会话 ID，用于将同一会话下的任务关联；不传则该任务不归属任何会话 |
+
+使用示例：
+
+```bash
+popcorn-cli image submit -p '<按 params_schema 构造的 JSON>'
+popcorn-cli video submit -p '<按 params_schema 构造的 JSON>' -s <SESSION_ID>
+```
+
+`-p` 的字段结构由后端 `params_schema` 决定，同场景所有模型共用。使用前请先执行 `popcorn-cli <group> models` 查询当前租户可用的模型清单与 `params_schema`，再选定 `model_id` 并据 schema 构造 `--params`。
+
+返回结构（受理成功，任务已入队）：
+
+```jsonc
+{
+  "task_id":    "...",   // 任务唯一标识，用于后续 task list --tid 查询
+  "session_id": "...",   // 传入的会话 ID；未传则为 null
+  "task_type":  "image", // 任务类型：image / video
+  "created_at": "..."    // 任务创建时间（ISO 8601）
+}
+```
+
+### `task list` — 查询任务
+
+用于获取 `submit` 异步任务的最终状态与结果。提交成功后请用本命令轮询，不要假定 `submit` 返回里已有生成结果。
+
+```bash
+popcorn-cli task list -s <SESSION_ID>
+popcorn-cli task list -t <TASK_ID>
+```
+
+| 参数 | 缩写 | 必填 | 说明 |
+|------|------|------|------|
+| `--sid` | `-s` | 二选一 | 按会话 ID 查询该会话下的所有任务 |
+| `--tid` | `-t` | 二选一 | 按任务 ID 查询单个任务 |
+
+`--sid` 与 `--tid` 必须提供其中之一。
+
+返回结构：
+
+```jsonc
+{
+  "total": 1,
+  "tasks": [
+    {
+      "task_id":       "...",      // 任务唯一标识
+      "session_id":    "...",      // 会话 ID；未归属会话则为 null
+      "task_type":     "image",    // 任务类型：image / video
+      "created_at":    "...",      // 创建时间
+      "finished_at":   "...",      // 完成时间；未完成时可能为空
+      "status":        "succeed",  // 见下方状态说明
+      "result":        "...",      // 成功时的结果（如资源 URL 等）；未完成或失败可能为空字符串
+      "error_message": ""          // 失败时的错误信息；成功时通常为空字符串
+    }
+  ]
+}
+```
+
+`status` 取值：
+
+| 状态 | 说明 |
+|------|------|
+| `queued` | 已入队，等待执行 |
+| `running` | 执行中 |
+| `succeed` | 成功（终态，可读 `result`） |
+| `failed` | 失败（终态，可读 `error_message`） |
+
+## 使用场景示例
+
+- **CI/自动化脚本**：按 session 提交批量任务，再轮询 `task list` 直到终态
+- **Agent 编排**：Agent 用同一 `session_id` 异步提交生图 / 生视频任务，之后统一 `task list --sid`（或 `--tid`）获取最终结果
+
+## 帮助信息
+
+```bash
+popcorn-cli --help
+popcorn-cli <group> --help          # 如 popcorn-cli image --help / popcorn-cli task --help
+popcorn-cli <group> <action> --help
+```

package/agents/skills/popcorn-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Popcorn CLI"
+  short_description: "通过 popcorn-cli 命令行提交 Popcorn 任务并查询模型与任务状态"
+  default_prompt: "使用 $popcorn-cli 通过命令行提交 Popcorn 任务、查询可用模型或检查任务状态。"

package/bin/popcorn-cli.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { buildConfigCommand } from '../src/commands/config.js';
+import { buildImageCommand } from '../src/commands/image.js';
+import { buildVideoCommand } from '../src/commands/video.js';
+import { buildTaskCommand } from '../src/commands/task.js';
+
+program
+  .name('popcorn-cli')
+  .description('Popcorn CLI - 通过 API Key 调用 Popcorn 后端服务')
+  .version('0.1.0');
+
+program.addCommand(buildConfigCommand());
+program.addCommand(buildImageCommand());
+program.addCommand(buildVideoCommand());
+program.addCommand(buildTaskCommand());
+
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@baomihuatop/popcorn-cli",
+  "version": "0.1.0",
+  "description": "Popcorn CLI - 通过 API Key 提交生图任务",
+  "type": "module",
+  "bin": {
+    "popcorn-cli": "bin/popcorn-cli.js"
+  },
+  "scripts": {
+    "start": "node bin/popcorn-cli.js"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "node-fetch": "^3.3.2"
+  }
+}

package/popcorn-cli-installation-guide.md

@@ -0,0 +1,52 @@
+# popcorn-cli(爆米花) 安装指南
+
+## 前置条件
+
+- Node.js ≥ 18
+- npm ≥ 9
+
+先探测环境：
+
+```bash
+node -v && npm -v
+```
+
+任一命令缺失或版本不达标时，先安装 / 升级 Node.js（推荐 nvm）后再继续。
+
+## 安装
+
+```bash
+npm install -g @baomihuatop/popcorn-cli
+```
+
+`EACCES` 权限报错时：macOS/Linux 前加 `sudo`；Windows 使用管理员终端。或改用 nvm 管理的 Node（其全局目录一般在用户目录下，无需 sudo）。
+
+## 校验
+
+```bash
+popcorn-cli --version
+```
+
+预期输出为版本号（例如 `0.1.0`）。返回该输出即视为安装成功。
+
+`command not found` 时，检查 `npm bin -g` 输出的目录是否在 `PATH` 中。
+
+## 安装 Skill
+
+CLI 安装并校验通过后，继续安装对应的 Agent Skill，以便在对话中按规范调用 `popcorn-cli` 能力：
+
+```bash
+npx skills add https://clawhub.ai/zeyiy/skills/popcorn-cli
+```
+
+## 升级
+
+```bash
+npm install -g @baomihuatop/popcorn-cli@latest
+```
+
+## 卸载
+
+```bash
+npm uninstall -g @baomihuatop/popcorn-cli
+```

package/src/commands/_group.js

@@ -0,0 +1,75 @@
+import { Command } from 'commander';
+import { loadConfig, requireApiKey } from '../config.js';
+import { requestApi } from '../http.js';
+
+function parseParams(input) {
+  let value;
+  try {
+    value = JSON.parse(input);
+  } catch (err) {
+    throw new Error(`params 不是合法的 JSON: ${err.message}`);
+  }
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('params 必须是 JSON 对象');
+  }
+  return value;
+}
+
+/**
+ * 构建一个按任务类型组织的命令组，包含 submit / models 两个子命令
+ * @param {{
+ *   group: string,             // 命令名，例如 'image'
+ *   groupDescription: string,  // 命令描述
+ *   taskType: string,          // 后端识别用的任务类型，例如 'image'
+ *   submitPath: string,        // 提交任务的 API 路径
+ *   submitDescription: string, // submit 子命令描述
+ * }} options
+ */
+export function buildTaskGroup({
+  group,
+  groupDescription,
+  taskType,
+  submitPath,
+  submitDescription,
+}) {
+  const cmd = new Command(group).description(groupDescription);
+
+  cmd
+    .command('submit')
+    .description(submitDescription)
+    .option('-s, --sid <sessionId>', '会话 ID，用于关联同一会话下的任务')
+    .requiredOption('-p, --params <json>', '任务参数（JSON 对象字符串）')
+    .action(async (options) => {
+      const config = loadConfig();
+      requireApiKey(config);
+
+      const params = parseParams(options.params);
+
+      const body = await requestApi(config, submitPath, {
+        method: 'POST',
+        body: {
+          ...(options.sid ? { session_id: options.sid } : {}),
+          params,
+        },
+      });
+
+      console.log(JSON.stringify(body?.data ?? {}, null, 2));
+    });
+
+  cmd
+    .command('models')
+    .description('查询该任务类型下所有可用模型（含使用限制与入参 schema）')
+    .action(async () => {
+      const config = loadConfig();
+      requireApiKey(config);
+
+      const body = await requestApi(config, '/api/models', {
+        method: 'GET',
+        query: { type: taskType },
+      });
+
+      console.log(JSON.stringify(body?.data ?? {}, null, 2));
+    });
+
+  return cmd;
+}

package/src/commands/config.js

@@ -0,0 +1,37 @@
+import { Command } from 'commander';
+import { loadConfig, saveConfig, getConfigPath } from '../config.js';
+
+export function buildConfigCommand() {
+  const cmd = new Command('config').description('管理 CLI 配置（API Key、后端地址等）');
+
+  cmd
+    .command('show')
+    .description('查看当前生效的配置')
+    .action(() => {
+      const config = loadConfig();
+      const masked = config.apiKey
+        ? `${config.apiKey.slice(0, 5)}${'*'.repeat(Math.max(0, config.apiKey.length - 5))}`
+        : '(未设置)';
+      console.log(`配置文件: ${getConfigPath()}`);
+      console.log(`apiKey  : ${masked}`);
+      console.log(`baseUrl : ${config.baseUrl}`);
+    });
+
+  cmd
+    .command('set-key <apiKey>')
+    .description('设置 API Key')
+    .action((apiKey) => {
+      saveConfig({ apiKey });
+      console.log('✓ 已保存 API Key');
+    });
+
+  cmd
+    .command('set-url <baseUrl>')
+    .description('设置后端服务地址')
+    .action((baseUrl) => {
+      saveConfig({ baseUrl });
+      console.log(`✓ 已保存 baseUrl: ${baseUrl}`);
+    });
+
+  return cmd;
+}

package/src/commands/image.js

@@ -0,0 +1,11 @@
+import { buildTaskGroup } from './_group.js';
+
+export function buildImageCommand() {
+  return buildTaskGroup({
+    group: 'image',
+    groupDescription: '生图相关任务',
+    taskType: 'image',
+    submitPath: '/api/generate/image',
+    submitDescription: '提交一个生图任务',
+  });
+}

package/src/commands/task.js

@@ -0,0 +1,33 @@
+import { Command } from 'commander';
+import { loadConfig, requireApiKey } from '../config.js';
+import { requestApi } from '../http.js';
+
+export function buildTaskCommand() {
+  const cmd = new Command('task').description('任务查询相关命令');
+
+  cmd
+    .command('list')
+    .description('按 sid 或 tid 查询任务列表')
+    .option('-s, --sid <sessionId>', '按会话 ID 查询该会话下的所有任务')
+    .option('-t, --tid <taskId>', '按任务 ID 查询单个任务')
+    .action(async (options) => {
+      if (!options.sid && !options.tid) {
+        throw new Error('必须提供 --sid 或 --tid 中的一个');
+      }
+
+      const config = loadConfig();
+      requireApiKey(config);
+
+      const body = await requestApi(config, '/api/tasks', {
+        method: 'GET',
+        query: {
+          session_id: options.sid,
+          task_id: options.tid,
+        },
+      });
+
+      console.log(JSON.stringify(body?.data ?? {}, null, 2));
+    });
+
+  return cmd;
+}

package/src/commands/video.js

@@ -0,0 +1,11 @@
+import { buildTaskGroup } from './_group.js';
+
+export function buildVideoCommand() {
+  return buildTaskGroup({
+    group: 'video',
+    groupDescription: '生视频相关任务',
+    taskType: 'video',
+    submitPath: '/api/generate/video',
+    submitDescription: '提交一个生视频任务',
+  });
+}

package/src/config.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const CONFIG_DIR = path.join(os.homedir(), '.popcorn-cli');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+const DEFAULT_CONFIG = {
+  apiKey: '',
+  baseUrl: 'https://mangaforge.svcs.n1q.cn',
+};
+
+export function getConfigPath() {
+  return CONFIG_FILE;
+}
+
+export function loadConfig() {
+  let fileConfig = {};
+  if (fs.existsSync(CONFIG_FILE)) {
+    try {
+      fileConfig = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'));
+    } catch (err) {
+      throw new Error(`配置文件解析失败 (${CONFIG_FILE}): ${err.message}`);
+    }
+  }
+
+  return {
+    ...DEFAULT_CONFIG,
+    ...fileConfig,
+  };
+}
+
+export function saveConfig(patch) {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  }
+  const current = fs.existsSync(CONFIG_FILE)
+    ? JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8'))
+    : {};
+  const next = { ...current, ...patch };
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(next, null, 2), { mode: 0o600 });
+  return next;
+}
+
+export function requireApiKey(config) {
+  if (!config.apiKey) {
+    throw new Error('未配置 API Key。请先运行 `popcorn-cli config set-key <API_KEY>`。');
+  }
+}

package/src/http.js

@@ -0,0 +1,55 @@
+import fetch from 'node-fetch';
+
+/**
+ * 使用当前配置向后端发起请求
+ * @param {{ apiKey: string, baseUrl: string }} config
+ * @param {string} path 相对路径（以 / 开头）
+ * @param {object} [options] fetch 选项覆盖：method / body / query
+ */
+export async function requestApi(config, path, options = {}) {
+  const { method = 'GET', body, query, headers = {}, ...rest } = options;
+
+  let url = `${config.baseUrl.replace(/\/$/, '')}${path}`;
+  if (query && Object.keys(query).length > 0) {
+    const search = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== undefined && v !== null && v !== '') search.append(k, String(v));
+    }
+    const qs = search.toString();
+    if (qs) url += `?${qs}`;
+  }
+
+  const fetchOptions = {
+    method,
+    ...rest,
+    headers: {
+      'X-API-Key': config.apiKey,
+      ...(body ? { 'Content-Type': 'application/json' } : {}),
+      ...headers,
+    },
+  };
+  if (body !== undefined) {
+    fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+  }
+
+  let res;
+  try {
+    res = await fetch(url, fetchOptions);
+  } catch (err) {
+    throw new Error(`请求失败：${err.message}`);
+  }
+
+  const text = await res.text();
+  let payload;
+  try {
+    payload = text ? JSON.parse(text) : {};
+  } catch {
+    throw new Error(`解析响应失败（HTTP ${res.status}）：${text}`);
+  }
+
+  if (!res.ok) {
+    throw new Error(`请求失败（HTTP ${res.status}）：${payload?.message ?? JSON.stringify(payload)}`);
+  }
+
+  return payload;
+}