Javascript Sdk Tool Free

JavaScript AI 应用 SDK 入门工具，支持模型调用、文件上传与基础代理配置。

Install

openclaw skills install @thcjp/javascript-sdk-tool-free

JavaScript SDK 工具（免费版）

概述

本工具为个人开发者提供 JavaScript/TypeScript AI 应用 SDK 的基础使用指引，覆盖 SDK 安装、认证配置、应用调用、文件上传等核心场景。通过自然语言指令驱动，帮助开发者快速集成 AI 应用调用能力到 JavaScript 项目中。免费版聚焦个人开发者的基础调用场景，提供简洁的 API 示例与错误处理模板。

核心能力

能力模块	描述	典型用法
SDK 安装	npm/yarn/pnpm 安装	`npm install @ai/sdk`
认证配置	API Key 与环境变量	直接配置或环境变量
应用调用	运行 AI 应用并获取结果	`client.run({ app, input })`
文件上传	自动或手动上传文件	`client.uploadFile(path)`
错误处理	基础异常捕获	try/catch + 类型判断
技术实现要点：核心能力基于`input_params`参数与`output_format`配置实现,支持创建/查询/修改/删除等操作模式,通过`config_options`进行运行时配置。

核心功能执行

用input_params参数进行配置。

输入: 用户提供核心功能执行所需的指令和必要参数。处理: 按照skill规范执行核心功能执行操作,遵循单一意图原则。输出: 返回核心功能执行的执行结果,包含操作状态和输出数据。

执行此能力时使用input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置。

输入: 用户提供参数配置与调用所需的指令和必要参数。处理: 按照skill规范执行参数配置与调用操作,遵循单一意图原则。输出: 返回参数配置与调用的执行结果,包含操作状态和输出数据。

执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置。

输入: 用户提供结果处理与输出所需的指令和必要参数。处理: 按照skill规范执行结果处理与输出操作,遵循单一意图原则。输出: 返回结果处理与输出的执行结果,包含操作状态和输出数据。

执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：JavaScript、入门工具、支持模型调用、文件上传与基础代、理配置、面向个人开发者的、提供基础的模型调、用与文件处理能力、应用调用与结果获、文件自动上传与手、环境变量认证配置、基础错误处理、CommonJS、Module、双支持等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景一：快速调用 AI 应用

开发者需要在 JavaScript 项目中调用 AI 模型。

text

用户：帮我在 Node.js 项目中调用 AI 模型生成图片

助手：
1. 安装 SDK
   npm install @ai/sdk

2. 配置认证
   // 直接配置
   import { createClient } from '@ai/sdk';
   const client = createClient({ apiKey: 'your_api_key' });
   
   // 或使用环境变量（推荐）
   // .env 文件
   AI_API_KEY=your_api_key
   
   const client = createClient({ apiKey: process.env.AI_API_KEY });

3. 调用应用
   const result = await client.run({
       app: 'image-generator',
       input: { prompt: '山间日落' }
   });
   
   console.log(result.status);  // "completed"
   console.log(result.output);  // 输出数据

4. 错误处理
   try {
       const result = await client.run({...});
   } catch (e) {
       if (e.name === 'RequirementsNotMet') {
           console.log('缺少必要参数:', e.errors);
       } else {
           console.log('API 错误:', e.message);
       }
   }

场景二：文件上传与处理

开发者需要上传文件并交给 AI 应用处理。

typescript

import { createClient } from '@ai/sdk';

const client = createClient({ apiKey: process.env.AI_API_KEY });

// 方式一：自动上传（路径作为输入）
const result1 = await client.run({
    app: 'image-processor',
    input: {
        image: '/path/to/image.png'  // 自动上传
    }
});

// 方式二：手动上传
const file = await client.uploadFile('/path/to/image.png', {
    filename: 'custom_name.png',
    contentType: 'image/png',
    public: true
});

const result2 = await client.run({
    app: 'image-processor',
    input: { image: file.uri }
});

// 方式三：浏览器文件上传
const input = document.querySelector('input[type="file"]');
const file = await client.uploadFile(input.files[0]);
const result3 = await client.run({
    app: 'image-processor',
    input: { image: file.uri }
});

场景三：异步任务处理

开发者需要处理耗时较长的 AI 任务。

typescript

// 异步执行（不等待完成）
const task = await client.run({
    app: 'video-generator',
    input: { prompt: '无人机飞越山脉' }
}, { wait: false });

console.log(`任务 ID: ${task.id}`);

// 后续查询任务状态
const status = await client.getTask(task.id);
console.log(`状态: ${status.status}`);

if (status.status === 'completed') {
    console.log('结果:', status.output);
} else if (status.status === 'failed') {
    console.log('失败:', status.error);
}

不适用场景

以下场景JS SDK工具免费版不适合处理：

逆向工程闭源API
API安全渗透测试
非标准协议集成

触发条件

需要API集成、接口对接、Webhook配置、系统连接时使用。不适用于非本工具能力范围的需求。

快速开始

阅读## 核心能力章节了解skill功能
按## 依赖说明配置环境
执行所需能力对应的命令
参考## 错误处理章节处理异常
查看## FAQ解答常见疑问

安装

bash

# npm
npm install @ai/sdk

# yarn
yarn add @ai/sdk

# pnpm
pnpm add @ai/sdk

环境要求：Node.js 18.0.0+（或支持 fetch 的现代浏览器）

认证配置

typescript

import { createClient } from '@ai/sdk';

// 方式一：直接配置 API Key
const client = createClient({ apiKey: 'your_api_key' });

// 方式二：环境变量（推荐）
const client = createClient({ apiKey: process.env.AI_API_KEY });

// 方式三：前端代理（不暴露 Key）
const client = createClient({ proxyUrl: '/api/proxy' });

基础调用模板

typescript

import { createClient } from '@ai/sdk';

const client = createClient({ apiKey: process.env.AI_API_KEY });

async function main() {
    try {
        const result = await client.run({
            app: 'text-generator',
            input: {
                prompt: '用一句话介绍 JavaScript',
                max_tokens: 100
            }
        });
        
        console.log('状态:', result.status);
        console.log('输出:', result.output);
    } catch (error) {
        console.error('调用失败:', error.message);
    }
}

main();

示例

运行参数说明

参数	类型	说明
`app`	string	应用 ID
`input`	object	匹配应用 schema 的输入
`setup`	object	隐藏的配置参数
`infra`	string	`cloud` 或 `private`
`wait`	boolean	是否等待完成（默认 true）

CommonJS 支持

javascript

const { createClient } = require('@ai/sdk');

const client = createClient({ apiKey: 'your_api_key' });

async function run() {
    const result = await client.run({
        app: 'text-generator',
        input: { prompt: '你好' }
    });
    console.log(result);
}

run();

环境变量配置

bash

# .env 文件
AI_API_KEY=your_api_key_here

# 加载环境变量（Node.js）
# npm install dotenv
import 'dotenv/config';

const client = createClient({ apiKey: process.env.AI_API_KEY });

最佳实践

API Key 用环境变量：不要硬编码在代码中

typescript

const client = createClient({ apiKey: process.env.AI_API_KEY });

始终做错误处理：网络和 API 调用可能失败

typescript

try {
    const result = await client.run({...});
} catch (e) {
    console.error(e);
}

长任务用异步模式：避免请求超时

typescript

const task = await client.run({...}, { wait: false });

文件上传指定类型：确保正确处理

typescript

await client.uploadFile(path, { contentType: 'image/png' });

前端用代理模式：不暴露 API Key

typescript

const client = createClient({ proxyUrl: '/api/proxy' });

常见问题

Q1：如何获取 API Key？

text

在 AI 平台的设置页面：
Settings → API Keys → Create API Key
复制生成的 Key 并保存到环境变量

Q2：调用超时怎么办？

typescript

// 长耗时任务使用异步模式
const task = await client.run({
    app: 'video-generator',
    input: { prompt: '...' }
}, { wait: false });

// 轮询任务状态
async function waitForTask(taskId, interval = 5000) {
    while (true) {
        const status = await client.getTask(taskId);
        if (status.status === 'completed') return status;
        if (status.status === 'failed') throw new Error(status.error);
        await new Promise(r => setTimeout(r, interval));
    }
}

const result = await waitForTask(task.id);

Q3：如何在浏览器中使用？

typescript

// 不要在浏览器中暴露 API Key
// 使用代理模式
const client = createClient({ proxyUrl: '/api/proxy' });

// 浏览器文件上传
const input = document.querySelector('input[type="file"]');
const file = await client.uploadFile(input.files[0]);

Q4：如何处理 API 错误？

typescript

import { RequirementsNotMetError, APIError } from '@ai/sdk';

try {
    const result = await client.run({...});
} catch (e) {
    if (e instanceof RequirementsNotMetError) {
        // 缺少必要参数
        for (const err of e.errors) {
            console.log(`  - ${err.type}: ${err.key}`);
        }
    } else if (e instanceof APIError) {
        // API 调用错误
        console.log('API 错误:', e.message);
        console.log('状态码:', e.statusCode);
    } else {
        // 网络或其他错误
        console.log('未知错误:', e);
    }
}

Q5：支持哪些 Node.js 版本？

text

需要 Node.js 18.0.0 或以上版本
因为 SDK 使用了原生 fetch API
Node.js 18 以下需要安装 node-fetch polyfill

Q6：如何批量调用？

typescript

// 并行调用（注意速率限制）
const prompts = ['问题1', '问题2', '问题3'];

const results = await Promise.all(
    prompts.map(prompt => 
        client.run({
            app: 'text-generator',
            input: { prompt }
        })
    )
);

// 串行调用（避免速率限制）
const results = [];
for (const prompt of prompts) {
    const result = await client.run({
        app: 'text-generator',
        input: { prompt }
    });
    results.push(result);
}

依赖说明

运行环境

Agent 平台: 支持读取 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
操作系统: Windows / macOS / Linux
Node.js 版本: 18.0.0+（或支持 fetch 的现代浏览器）
包管理器: npm / yarn / pnpm

依赖详情

依赖项	类型	是否必需	获取方式
Node.js	运行时	必需	nodejs.org 下载
@ai/sdk	npm 包	必需	`npm install @ai/sdk`
dotenv	环境变量	推荐	`npm install dotenv`
LLM API	API	必需	由 Agent 内置 LLM 提供

API Key 配置

需要 AI 平台的 API Key，通过环境变量配置
前端应用使用代理模式，不暴露 Key
环境变量名称建议：AI_API_KEY

可用性分类

分类: MD+EXEC（Markdown 指令 + 命令行执行）
说明: 通过自然语言指令驱动 Agent 提供 SDK 集成建议，代码运行需要 Node.js 和 npm 执行能力

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

已知限制

需要API Key，无Key环境无法使用
当前为免费版本,如需完整功能请升级到付费版获取全部能力