@skillmaster/sdk-next

Node.js SDK for SkillMaster Open API - AI-powered image/video generation, media analysis, text generation, and more.

每个 SDK 调用会自动：

• 创建本地任务文件夹（时间戳 + uuid，含 attachments/ 与 logs/）
• 上传本地文件附件（自动走主站 /api/upload）
• 提交 Open API action（默认异步 ?async=true，自动轮询 GET /openapi/v1/tasks/{task_id}，也可同步 ?async=false）
• 下载结果附件到任务文件夹（避免链接过期）
• 记录执行日志（logs/execution.log、request.json、response.json、summary.json）

Installation

npm install @skillmaster/sdk-next

CLI Login（OAuth）

无需手工申请 API Key，直接用飞书账号登录授权（复用 FieldShortcut 已有的 OAuth 授权页面）：

npx skillmaster-sdk login        # 打开浏览器完成授权，API Key 自动写入 ~/.skillmaster/config.json
npx skillmaster-sdk whoami       # 查看当前登录状态
npx skillmaster-sdk logout       # 移除已保存的 API Key
npx skillmaster-sdk config list  # 查看配置

login 流程：自动读取 OAuth 受保护资源元数据 → 本地随机端口回调 → PKCE (S256) → 浏览器打开 OAuth 授权页（未登录会先走飞书登录）→ 授权后自动换出 API Key 并保存。SDK 会使用元数据中声明的 MCP resource、授权端点与令牌端点，因此 Open API 主站与 OAuth 服务不在同一域名时也无需传入 --host。

Quick Start

import { SkillMasterClient } from '@skillmaster/sdk-next';

// 依次读取 config 参数 > SKILLMASTER_API_KEY 环境变量 > ~/.skillmaster/config.json
const client = new SkillMasterClient();

// 生视频（默认异步提交 + 轮询，完成后自动下载视频到任务文件夹）
const videoResult = await client.video.wan3({
  prompt: '一只橘猫在洒满阳光的窗台上打盹',
  resolution: '1080P',
  ratio: '16:9',
  duration: 5,
});
console.log('视频地址:', videoResult.response.data?.videos?.[0]?.url);
console.log('本地文件:', videoResult.response.data?.videos?.[0]?.localPath);
console.log('任务文件夹:', videoResult.taskFolder);

// Seedance 系列
await client.video.seedance2({ prompt: '...', duration: -1 });
await client.video.seedance2Mini({ prompt: '...', attachments: [{ url: 'https://...' }] });
await client.video.seedance25({ prompt: '...' });
await client.video.seedance2Real({ prompt: '...' });
await client.video.happyhorse({ prompt: '...', image_urls: ['https://...'] });

// 生图
const imageResult = await client.image.jimengV5({ prompt: '一只可爱的猫咪', size: '2048x2048' });
await client.image.geminiV2({ prompt: '...', image_urls: ['https://...'] });
await client.image.gpt({ prompt: '...', n: 2 });

// 文本
await client.text.glm5({ prompt: '总结一下', attachments: [{ url: 'https://.../doc.pdf' }] });
await client.text.kimi3({ prompt: '...' });

// 同步模式（短任务，?async=false）
const syncClient = new SkillMasterClient({ sync: true });
// 或单次调用
await client.video.wan3({ /* ... */ }, { sync: true });

Configuration

优先级：构造参数 > 环境变量 > ~/.skillmaster/config.json > 默认值。

| 参数 | 环境变量 | 默认值 | 说明 | | --- | --- | --- | --- | | apiKey | SKILLMASTER_API_KEY | -（login 自动写入） | API Key | | host | SKILLMASTER_HOST | https://skillmaster.fieldshortcut.com | Open API（/openapi/v1 前缀）与文件上传（/api/upload）地址；登录时会通过元数据自动发现 OAuth 服务 | | taskDir | - | ~/Documents/tasks | 任务文件夹根目录 | | timeout | - | 900000（15 分钟） | 请求/轮询总超时 | | sync | - | false | 默认执行模式 | | pollInterval | - | 5000 | 异步轮询间隔 |

配置也可用 CLI 管理：skillmaster-sdk config set host https://...（旧配置里的 baseUrl 键会自动迁移为 host）

API Reference

video

| 方法 | Open API action | | --- | --- | | video.wan3() | POST /openapi/v1/wan3/video | | video.seedance2() | POST /openapi/v1/seedance2_official/run | | video.seedance2Mini() | POST /openapi/v1/seedance2_mini/video | | video.seedance25() | POST /openapi/v1/seedance2_5/video | | video.seedance2Real() | POST /openapi/v1/seedance2_real/video | | video.happyhorse() | POST /openapi/v1/happyhorse/video |

image

| 方法 | Open API action | | --- | --- | | image.jimengV5() | POST /openapi/v1/jimeng/image/v5 | | image.geminiV2() | POST /openapi/v1/gemini/image/v2 | | image.geminiPro() | POST /openapi/v1/gemini/image/pro | | image.gpt() | POST /openapi/v1/gpt/image | | image.imageToUrl() | POST /openapi/v1/image2url |

text

| 方法 | Open API action | | --- | --- | | text.glm5() / glm5Doc / glm5Image / glm5Video | POST /openapi/v1/glm5[...] | | text.kimi3() / kimi3Doc / kimi3Image / kimi3Video | POST /openapi/v1/kimi3[...] |

media / toolkit / idp / document

media.analyze()、media.mediaSearch()、media.mediaComments()、media.textToSpeech()、toolkit.expressQuery()、toolkit.emailSend() 等方法对应的服务端 action 已在 Open API 暴露，可直接使用。部分保留方法尚未被当前 OpenAPI 规范收录，其服务可用性未验证，不能据此认定调用会返回 404。本次契约测试仅保障规范已收录的已封装接口。

契约修正与迁移说明

• 媒体接口使用字符串 url；评论数量、语音数值和邮件端口使用数字，邮件收件人使用字符串数组。
• 文字接口返回 { text, truncated? }，语音返回 { audios }，邮件返回 { sent, message }；任务结果可能为 null。
• media.analyzeVideo({ file, prompt }) 现转发至 /video_analysis，保留提示词并返回文字结果；需要 { summary, subtitle? } 时请使用 media.analyze({ url })。
• 旧输入仅保留部分运行时兼容，不保证所有旧表格字段或本地文件输入；以方法当前类型为准。
• npm run test:skill-apis 执行构建和离线回归测试，包含 31 条业务路径的同步与异步契约测试；不会请求真实业务接口。规范快照位于 tests/fixtures/openapi.json，断言不是完整的规范验证器。

通用请求

// endpoint 自动归一化：/api/xxx、/xxx、/openapi/v1/xxx 均可
await client.request('/wan3/video', { prompt: '...', attachments: [] });

// 附件支持：URL 字符串、{url}、旧版 {tmp_url}、本地路径 {path: './local.png'}（自动上传）

Task Folders

~/Documents/tasks/20260214_103012_a1b2c3d4/
├── attachments/          # 下载的结果附件
└── logs/
    ├── execution.log     # 执行日志（info/warn/error）
    ├── request.json      # 请求记录
    ├── response.json     # 响应记录
    └── summary.json      # 汇总（耗时、成功与否）

Development

npm install
npm run build          # tsup 构建 cjs + esm + d.ts
npm run typecheck      # tsc --noEmit
node --test tests/login.test.mjs tests/skill-api-wrappers.test.mjs   # 单元测试（含 mock OAuth 全流程）
TEST_ONLY=wan3 node tests/direct-api-smoke.mjs   # 需要 API key 的在线冒烟

License

MIT