ai-world-sdk 1.2.5 → 1.2.6

package/dist/config.d.ts

@@ -9,7 +9,7 @@
  *
  * 注意: {VERSION} 占位符会在构建时被替换为实际版本号
  */
-export declare const SDK_SIGNATURE = "AI_WORLD_SDK_V:1.2.5";
+export declare const SDK_SIGNATURE = "AI_WORLD_SDK_V:1.2.6";
 /**
  * 版本兼容性错误
  */
@@ -34,8 +34,8 @@ declare class SDKConfig {
     private _authenticated;
     private _authCheckPromise;
     private _currentUser;
-    readonly sdkSignature = "AI_WORLD_SDK_V:1.2.5";
-    readonly sdkVersion = "1.2.5";
+    readonly sdkSignature = "AI_WORLD_SDK_V:1.2.6";
+    readonly sdkVersion = "1.2.6";
     constructor();
     /**
      * Set global base URL

package/dist/config.js

@@ -7,7 +7,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.sdkConfig = exports.VersionCompatibilityError = exports.SDK_SIGNATURE = void 0;
 // SDK 版本号（构建时自动从 package.json 更新）
 // 此版本号会在运行 npm run build 时自动从 package.json 读取并更新
-const SDK_VERSION = "1.2.5";
+const SDK_VERSION = "1.2.6";
 /**
  * SDK 特征码 - 用于在构建后的 JS 文件中识别 SDK 版本
  * 格式: AI_WORLD_SDK_V:版本号
@@ -15,7 +15,7 @@ const SDK_VERSION = "1.2.5";
  *
  * 注意: {VERSION} 占位符会在构建时被替换为实际版本号
  */
-exports.SDK_SIGNATURE = "AI_WORLD_SDK_V:1.2.5";
+exports.SDK_SIGNATURE = "AI_WORLD_SDK_V:1.2.6";
 /**
  * 版本兼容性错误
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-world-sdk",
-  "version": "1.2.5",
+  "version": "1.2.6",
   "description": "TypeScript SDK for AI World Platform - Chat Models, Image Generation, and Video Generation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -66,7 +66,8 @@
     "typescript": "^5.0.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "dependencies": {
     "@ai-sdk/anthropic": "^3.0.43",

package/skills/ai-world-sdk/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: ai-world-sdk
+description: Use when initializing ai-world-sdk or calling AI models in ai-world projects. Covers sdkConfig initialization, createProvider with Vercel AI SDK (generateText, streamText, generateImage), Doubao image/video generation, MinIO object storage (MinioStorageClient), and resource management with ACL (ResourceClient). Triggers on ai-world-sdk, createProvider, sdkConfig, generateText, streamText, generateImage, doubao, MinioStorageClient, minio, ResourceClient, resource management, access control, file sharing, or any AI model integration.
+---
+
+# AI World SDK
+
+ai-world-sdk 是 AI World 平台的 TypeScript SDK，通过 `createProvider` 创建 Vercel AI SDK Provider，所有请求经后端代理转发，无需管理 API Key。
+
+- Vercel AI SDK 官方文档: https://ai-sdk.dev/docs
+- AI SDK Core API: https://ai-sdk.dev/docs/reference/ai-sdk-core
+
+## When to Use
+
+- 在 ai-world 插件中调用 AI 模型（文本、图像、视频）
+- 需要初始化 ai-world-sdk 配置
+- 使用 `createProvider` 调用 Vercel AI SDK
+- 使用 Doubao 豆包图像/视频生成
+- 使用 MinIO 对象存储（文件上传/下载/管理）
+- 使用资源管理系统（权限控制: private/specific_users/public）
+
+## 安装
+
+```bash
+npm install ai-world-sdk ai
+```
+
+## SDK 初始化
+
+### 浏览器环境（ai-world 插件内）
+
+**自动初始化**，无需手动配置：
+- `baseUrl` — 自动从 `window.location.origin`
+- `token` — 自动从 cookie `auth_token`
+- `pluginId` — 自动从 `window.__INITIAL_DATA__.plugin_id`
+
+### Vite 开发模式（推荐：Vite Plugin 自动登录）
+
+在 `vite.config.ts` 中添加 `aiWorldPlugin()`，dev server 启动时自动完成以下所有配置：
+
+1. 检测 `.env.local` 中的 `DEBUG_TOKEN`，缺失或过期时通过后端 `/api/auth/login` 自动打开浏览器完成飞书登录
+2. 登录后将 `DEBUG=true`、`DEBUG_TOKEN`、`PLUGIN_ID` 写入 `.env.local`
+3. `PLUGIN_ID` 按优先级：`plugin.json` 的 `plugin_id` → `package.json` 的 `name` → 项目目录名
+4. 通过 `window.__AI_WORLD_CONFIG__` 将配置注入到浏览器页面，SDK 自动读取
+
+```typescript
+import { aiWorldPlugin } from 'ai-world-sdk/vite'
+
+export default defineConfig({
+  plugins: [
+    vue(), // 或 react() 等
+    aiWorldPlugin()  // baseUrl 默认 https://aiworld.local:8000
+  ]
+})
+```
+
+首次 `npm run dev` 时自动打开浏览器完成飞书登录，后续启动 token 有效则直接跳过。无需在代码中手动调用 `sdkConfig.setToken()` 或 `sdkConfig.setPluginId()`，一切自动完成。
+
+如需自定义后端地址：
+
+```typescript
+aiWorldPlugin({ baseUrl: 'https://your-server:8000' })
+```
+
+### 非浏览器环境（测试、脚本）
+
+```typescript
+import { sdkConfig } from 'ai-world-sdk';
+
+sdkConfig.setBaseUrl('https://aiworld.local:8000');
+sdkConfig.setToken('your-jwt-token');
+sdkConfig.setPluginId('my-plugin');
+```
+
+也可通过环境变量 `DEBUG_TOKEN`、`PLUGIN_ID`、`AI_WORLD_BASE_URL` 自动初始化。
+
+## 功能模块
+
+以下功能的详细用法和代码示例请查阅对应的子文档。
+
+### Provider 与模型 → `docs/provider-and-models.md`
+
+- `createProvider(provider, endpointType, pluginId)` 创建 Vercel AI SDK Provider
+- Provider 对照表：`api2img`(推荐) / `gemini` / `aihubmix` / `shubiaobiao`
+- 常用模型列表和 AI SDK 函数速查
+
+### 文本生成 → `docs/text-generation.md`
+
+- `generateText` / `streamText` / `generateObject` / `streamObject`
+
+### 图像生成 → `docs/image-generation.md`
+
+- AI SDK `generateImage`（DALL-E / GPT Image）
+- `DoubaoImageGenerationClient`（豆包 Seedream）
+- `GeminiImageGenerationClient`
+
+### 视频生成 → `docs/video-generation.md`
+
+- `VideoGenerationClient`（豆包 Seedance）
+- `OpenAIVideoGenerationClient`（Sora）
+
+### MinIO 对象存储 → `docs/minio-storage.md`
+
+- `MinioStorageClient` — 文件上传/下载/列表/删除/预签名 URL
+- 存储路径: `{pluginId}/{userId}/{path}`
+
+### 资源管理 → `docs/resource-management.md`
+
+- `ResourceClient` — 带 ACL 的资源管理
+- 三级权限: `private` / `specific_users` / `public`
+- 插件隔离与跨插件访问
+
+### 常见错误 → `docs/common-mistakes.md`
+
+- endpointType 匹配规则、AI SDK v6 用法变更、MinIO 路径规范等

package/skills/ai-world-sdk/docs/common-mistakes.md

@@ -0,0 +1,15 @@
+# 常见错误与正确做法
+
+| 错误 | 正确做法 |
+|------|---------|
+| endpointType 与 provider 不匹配 | `gemini`→`gemini`，其余→`openai` |
+| 手动传 API Key | 不需要，自动经后端代理鉴权 |
+| `result.usage.promptTokens` | AI SDK v6 改为 `inputTokens` / `outputTokens` |
+| `provider.image()` 类型报错 | 用 `(provider as any).image()` |
+| 忘装 `ai` 包 | 需同时装 `ai-world-sdk` 和 `ai` |
+| Vite dev 时调不通 | 在 `vite.config.ts` 中使用 `aiWorldPlugin()` 自动登录 |
+| 用 `createProvider` 调豆包 | 豆包用专用客户端 `DoubaoImageGenerationClient` / `VideoGenerationClient` |
+| MinIO 操作缺少 `X-Plugin-Id` | 先调 `sdkConfig.setPluginId('xxx')` 或在构造函数传入 `pluginId` |
+| MinIO 路径包含前导斜杠 | 路径不要以 `/` 开头，如 `docs/file.txt` 而非 `/docs/file.txt` |
+| 资源管理与 MinIO 混用 | `MinioStorageClient` 是原始存储（无权限控制），`ResourceClient` 带 ACL |
+| 资源管理忘记权限 | 上传默认 `private`，需显式设 `accessLevel: 'public'` 才能被他人访问 |

package/skills/ai-world-sdk/docs/image-generation.md

@@ -0,0 +1,69 @@
+# 图像生成
+
+## AI SDK 图像生成（DALL-E / GPT Image）
+
+```typescript
+import { createProvider } from 'ai-world-sdk';
+import { generateImage } from 'ai';
+
+const provider = createProvider('api2img', 'openai', 'my-plugin');
+const imageModel = (provider as any).image('dall-e-3'); // as any: ProviderV3 类型不含 .image()
+
+const { images } = await generateImage({
+  model: imageModel,
+  prompt: '可爱的小猫',
+  size: '1024x1024',
+  n: 1,
+});
+// images[0].base64, images[0].mediaType
+```
+
+## 豆包（Doubao）图像生成
+
+豆包不通过 `createProvider`，使用专用客户端 `DoubaoImageGenerationClient`。
+
+```typescript
+import { DoubaoImageGenerationClient } from 'ai-world-sdk';
+
+const client = new DoubaoImageGenerationClient({});
+
+const result = await client.generate({
+  prompt: '一只可爱的小猫',
+  model: 'doubao-seedream-4-5-251128',
+  size: '2K',       // '1K' | '2K' | '4K' | '2048x2048' | '2560x1440' 等
+  quality: 'hd',    // 'standard' | 'hd'
+  n: 1,             // 1-10
+});
+console.log(result.data[0]?.url);
+```
+
+### 图文生图（单图输入）
+
+```typescript
+await client.generate({
+  prompt: '转换为水彩画风格',
+  image: 'data:image/png;base64,...',
+  size: '2560x1440',
+});
+```
+
+### 多图融合
+
+```typescript
+await client.generate({
+  prompt: '合并这些图片',
+  image: ['data:image/png;base64,...', 'data:image/png;base64,...'],
+});
+```
+
+## Gemini 图像生成
+
+```typescript
+import { GeminiImageGenerationClient } from 'ai-world-sdk';
+
+const client = new GeminiImageGenerationClient({});
+const result = await client.generate({
+  prompt: '一只可爱的小猫',
+  provider: 'gemini',
+});
+```

package/skills/ai-world-sdk/docs/minio-storage.md

@@ -0,0 +1,55 @@
+# MinIO 对象存储
+
+通过 `MinioStorageClient` 操作后端 MinIO 对象存储。所有文件按 `{pluginId}/{userId}/{path}` 存储，需要设置 `pluginId`。
+
+## 基本用法
+
+```typescript
+import { MinioStorageClient, sdkConfig } from 'ai-world-sdk';
+
+// pluginId 在 ai-world 插件环境自动从 window.__INITIAL_DATA__ 获取
+// 手动设置: sdkConfig.setPluginId('my-plugin');
+
+const storage = new MinioStorageClient();
+
+// 上传文件
+const file = new File(['hello world'], 'hello.txt', { type: 'text/plain' });
+const result = await storage.upload('docs/hello.txt', file);
+console.log(result.path, result.size, result.etag);
+
+// 下载文件
+const blob = await storage.download('docs/hello.txt');
+const text = await blob.text();
+
+// 列出文件
+const files = await storage.list({ prefix: 'docs/' });
+
+// 获取文件信息
+const info = await storage.info('docs/hello.txt');
+
+// 获取预签名下载 URL（可直接访问，无需认证）
+const { url } = await storage.getPresignedUrl('docs/hello.txt', 3600);
+
+// 获取预签名上传 URL（客户端直传到 MinIO）
+const { url: uploadUrl } = await storage.getPresignedUploadUrl('docs/upload.txt', 3600);
+
+// 删除文件
+await storage.delete('docs/hello.txt');
+
+// 下载并触发浏览器保存
+await storage.downloadAsFile('docs/report.pdf', 'report.pdf');
+```
+
+## 后端 API 端点
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/minio/upload` | 上传文件（multipart/form-data） |
+| GET | `/api/minio/download/{path}` | 下载文件 |
+| GET | `/api/minio/list` | 列出文件（?prefix=xxx） |
+| DELETE | `/api/minio/delete/{path}` | 删除文件 |
+| GET | `/api/minio/presigned-url/{path}` | 预签名下载 URL |
+| POST | `/api/minio/presigned-upload` | 预签名上传 URL |
+| GET | `/api/minio/info/{path}` | 文件元信息 |
+
+所有请求需 `Authorization: Bearer <token>` 和 `X-Plugin-Id` 请求头。

package/skills/ai-world-sdk/docs/provider-and-models.md

@@ -0,0 +1,63 @@
+# Provider 与模型
+
+## Provider 对照表
+
+| Provider | EndpointType | 说明 |
+|----------|-------------|------|
+| `api2img` | `openai` | **推荐**，聚合所有模型（GPT、Gemini、Claude 等） |
+| `aihubmix` | `openai` | 多模型聚合 |
+| `shubiaobiao` | `openai` | 数标标 |
+| `gemini` | `gemini` | Google Gemini 原生 |
+
+规则：`gemini` provider 用 `gemini` endpoint，其余全部用 `openai`。
+
+> `doubao` 不通过 `createProvider` 使用，豆包有专用客户端（见 image-generation.md / video-generation.md）。
+
+## createProvider 用法
+
+```typescript
+import { createProvider } from 'ai-world-sdk';
+
+// createProvider(provider, endpointType, pluginId)
+const provider = createProvider('api2img', 'openai', 'my-plugin');
+const model = provider.languageModel('gpt-4o-mini');
+```
+
+### 不同供应商
+
+```typescript
+// Gemini
+createProvider('gemini', 'gemini', 'my-plugin').languageModel('gemini-2.5-flash');
+
+// api2img 聚合（推荐，一个 provider 访问所有模型）
+const p = createProvider('api2img', 'openai', 'my-plugin');
+p.languageModel('gpt-4o-mini');
+p.languageModel('gemini-2.5-flash');
+p.languageModel('claude-sonnet-4-5');
+```
+
+### 检测模型可用性
+
+```typescript
+import { checkModel } from 'ai-world-sdk';
+const ok = await checkModel('api2img', 'openai', 'gpt-4o-mini', 'my-plugin');
+```
+
+## 常用模型
+
+| 模型 | 类型 | Provider | EndpointType |
+|------|------|----------|-------------|
+| `gpt-4o-mini` / `gpt-4o` / `gpt-5.1` | 文本 | `api2img` | `openai` |
+| `gemini-2.5-flash` / `gemini-2.5-pro` | 文本 | `gemini` | `gemini` |
+| `dall-e-3` / `gpt-image-1` | 图像 | `api2img` | `openai` |
+| `doubao-seedream-4-5-251128` | 图像 | — | 专用客户端 |
+
+## AI SDK 函数速查
+
+| 函数 | 用途 | 文档 |
+|------|------|------|
+| `generateText` | 一次性文本 | https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text |
+| `streamText` | 流式文本 | https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text |
+| `generateObject` | 结构化数据 | https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-object |
+| `streamObject` | 流式结构化 | https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-object |
+| `generateImage` | 图像生成 | https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-image |

package/skills/ai-world-sdk/docs/resource-management.md

@@ -0,0 +1,71 @@
+# 资源管理系统（访问权限控制）
+
+在 MinIO 原始存储之上提供数据库驱动的访问权限控制，支持 private / specific_users / public 三级权限。
+资源文件存储在独立 bucket `ai-world-res`（配置: `MINIO_RESOURCE_BUCKET`），与普通 MinIO 存储（`ai-world`）隔离。
+
+## 基本用法
+
+```typescript
+import { ResourceClient, sdkConfig } from 'ai-world-sdk';
+
+sdkConfig.setPluginId('my-plugin');
+const resources = new ResourceClient();
+
+// 上传并设为公开
+const file = new File(['content'], 'doc.txt', { type: 'text/plain' });
+const res = await resources.upload('docs/doc.txt', file, {
+  accessLevel: 'public',
+  description: '公开文档',
+});
+
+// 列出我的资源
+const myFiles = await resources.listMy();
+
+// 列出公开资源
+const publicFiles = await resources.listPublic();
+
+// 查看某用户的可访问资源
+const userFiles = await resources.listByUser(42);
+
+// 通过 userId + path 下载
+const blob = await resources.downloadByUser(42, 'docs/doc.txt');
+
+// 修改权限
+await resources.updateAccess(res.id, 'specific_users');
+
+// 批量分享给指定用户（支持单个 number 或 number[]）
+await resources.addShare(res.id, [99, 100, 101]);
+
+// 批量移除分享
+await resources.removeShare(res.id, [99, 100]);
+
+// 列出被分享给我的资源
+const shared = await resources.listSharedWithMe();
+
+// 跨插件查看（默认按 plugin_id 隔离）
+const allPublic = await resources.listPublic({ crossPlugin: true });
+
+// 通过资源 ID 下载
+const data = await resources.download(res.id);
+
+// 删除资源（同时删除 MinIO 文件）
+await resources.delete(res.id);
+```
+
+## 权限模型
+
+| 级别 | 说明 |
+|------|------|
+| `private` | 仅上传者自己可访问（默认） |
+| `specific_users` | 上传者 + 被授权的指定用户 |
+| `public` | 所有已登录用户 |
+
+## 插件隔离
+
+资源默认按 `plugin_id` 隔离。所有列表查询接口默认只返回当前插件下的资源。
+传入 `{ crossPlugin: true }` 参数可查看所有插件的资源（仍受权限约束）。
+
+## 与 MinIO 存储的区别
+
+- `MinioStorageClient` — 原始对象存储，无权限控制
+- `ResourceClient` — 带 ACL 的资源管理，数据库驱动权限检查

package/skills/ai-world-sdk/docs/text-generation.md

@@ -0,0 +1,57 @@
+# 文本生成
+
+通过 Vercel AI SDK 的 `generateText` / `streamText` 调用文本模型。
+
+## 一次性生成
+
+```typescript
+import { createProvider } from 'ai-world-sdk';
+import { generateText } from 'ai';
+
+const provider = createProvider('api2img', 'openai', 'my-plugin');
+const model = provider.languageModel('gpt-4o-mini');
+
+const result = await generateText({ model, prompt: '你好' });
+console.log(result.text);
+// result.usage?.inputTokens / result.usage?.outputTokens
+```
+
+## 流式生成
+
+```typescript
+import { createProvider } from 'ai-world-sdk';
+import { streamText } from 'ai';
+
+const provider = createProvider('api2img', 'openai', 'my-plugin');
+const model = provider.languageModel('gpt-4o-mini');
+
+const stream = streamText({ model, prompt: '写故事' });
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+## 结构化数据生成
+
+```typescript
+import { createProvider } from 'ai-world-sdk';
+import { generateObject } from 'ai';
+import { z } from 'zod';
+
+const provider = createProvider('api2img', 'openai', 'my-plugin');
+const model = provider.languageModel('gpt-4o-mini');
+
+const { object } = await generateObject({
+  model,
+  schema: z.object({
+    name: z.string(),
+    age: z.number(),
+  }),
+  prompt: '生成一个虚拟用户',
+});
+```
+
+## 注意事项
+
+- AI SDK v6 中 usage 字段为 `inputTokens` / `outputTokens`（非 `promptTokens`）
+- 推荐使用 `api2img` + `openai` endpoint，一个 provider 可访问所有模型

package/skills/ai-world-sdk/docs/video-generation.md

@@ -0,0 +1,47 @@
+# 视频生成
+
+## 豆包视频生成（Seedance）
+
+```typescript
+import { VideoGenerationClient } from 'ai-world-sdk';
+
+const client = new VideoGenerationClient({});
+
+// 创建任务
+const task = await client.create({
+  prompt: '日落时分的海滩',
+  duration: 5,           // 1-10 秒
+  aspect_ratio: '16:9',  // '16:9' | '9:16' | '1:1'
+  resolution: '720p',
+});
+
+// 轮询直到完成
+const result = await client.poll(task.id, {
+  interval: 3000,
+  timeout: 300000,
+});
+
+if (result.status === 'succeeded') {
+  console.log(result.content?.video_url);
+}
+```
+
+## OpenAI 视频生成（Sora）
+
+```typescript
+import { OpenAIVideoGenerationClient } from 'ai-world-sdk';
+
+const client = new OpenAIVideoGenerationClient({});
+
+const task = await client.create({
+  prompt: '一只猫在弹钢琴',
+  duration: 5,
+  aspect_ratio: '16:9',
+  resolution: '720p',
+});
+
+const result = await client.poll(task.id, {
+  interval: 5000,
+  timeout: 600000,
+});
+```