ai-world-sdk 1.3.0 → 1.3.3

package/dist/__tests__/example.test.js

@@ -40,6 +40,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const dotenv = __importStar(require("dotenv"));
 const index_1 = require("../index");
 const fs_1 = require("fs");
+const ai_1 = require("ai");
 // Load environment variables from .env file
 dotenv.config();
 index_1.sdkConfig.setBaseUrl("http://localhost:8000");
@@ -1187,6 +1188,32 @@ describe("Langchain SDK Tests", () => {
             console.log("响应内容:", content);
         }
     }, 30000);
+    // ========== OpenRouter 测试 ==========
+    test("ChatOpenAI - OpenRouter 基础测试", async () => {
+        const provider = (0, index_1.createProvider)("openrouter", "openai", "test");
+        const result = await (0, ai_1.generateText)({
+            model: provider.languageModel('openai/gpt-4o-mini'),
+            prompt: '你好',
+        });
+        console.log("result:", result);
+    }, 30000);
+    test("ChatOpenAI - OpenRouter 流式调用", async () => {
+        const provider = (0, index_1.createProvider)("openrouter", "openai", "test");
+        const stream = (0, ai_1.streamText)({
+            model: provider.languageModel('openai/gpt-4o-mini'),
+            prompt: '你好',
+        });
+        let fullText = "";
+        for await (const part of stream.fullStream) {
+            switch (part.type) {
+                case 'text-delta':
+                    fullText += part.text;
+                    break;
+            }
+        }
+        expect(fullText.length).toBeGreaterThan(0);
+        console.log("fullText:", fullText);
+    }, 30000);
     // ========== OpenAI 视频生成测试 ==========
     test("OpenAIVideoGenerationClient - 创建视频生成任务（文本）", async () => {
         const openaiVideoClient = new index_1.OpenAIVideoGenerationClient({});

package/dist/config.d.ts

@@ -9,7 +9,7 @@
  *
  * 注意: {VERSION} 占位符会在构建时被替换为实际版本号
  */
-export declare const SDK_SIGNATURE = "AI_WORLD_SDK_V:1.3.0";
+export declare const SDK_SIGNATURE = "AI_WORLD_SDK_V:1.3.3";
 /**
  * 版本兼容性错误
  */
@@ -34,8 +34,8 @@ declare class SDKConfig {
     private _authenticated;
     private _authCheckPromise;
     private _currentUser;
-    readonly sdkSignature = "AI_WORLD_SDK_V:1.3.0";
-    readonly sdkVersion = "1.3.0";
+    readonly sdkSignature = "AI_WORLD_SDK_V:1.3.3";
+    readonly sdkVersion = "1.3.3";
     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.3.0";
+const SDK_VERSION = "1.3.3";
 /**
  * SDK 特征码 - 用于在构建后的 JS 文件中识别 SDK 版本
  * 格式: AI_WORLD_SDK_V:版本号
@@ -15,7 +15,7 @@ const SDK_VERSION = "1.3.0";
  *
  * 注意: {VERSION} 占位符会在构建时被替换为实际版本号
  */
-exports.SDK_SIGNATURE = "AI_WORLD_SDK_V:1.3.0";
+exports.SDK_SIGNATURE = "AI_WORLD_SDK_V:1.3.3";
 /**
  * 版本兼容性错误
  */

package/dist/index.d.ts

@@ -7,7 +7,7 @@
 import { BaseChatModel, BaseChatModelParams } from "./base";
 import { DoubaoImageGenerationClient, DoubaoImageSize, type DoubaoImageGenerationConfig, type DoubaoImageGenerationRequest, type DoubaoImageGenerationResponse } from "./doubao-image-generation";
 import { GeminiImageGenerationClient, type GeminiImageGenerationConfig, type GeminiImageGenerationRequest, type GeminiImageGenerationResponse } from "./gemini-image-generation";
-import { VideoGenerationClient, type VideoGenerationConfig, type VideoGenerationRequest, type ContentGenerationTaskID, type ContentGenerationTask } from "./video_generation";
+import { VideoGenerationClient, type VideoGenerationConfig, type VideoGenerationRequest, type ContentGenerationTaskID, type ContentGenerationTask, VideoUnderstandingClient, type VideoUnderstandingConfig, type VideoUnderstandingRequest, type VideoUnderstandingResponse, type VideoUnderstandingStreamChunk, type VideoUnderstandingMessage, type VideoUnderstandingContent } from "./video_generation";
 import { OpenAIVideoGenerationClient, type OpenAIVideoGenerationConfig, type OpenAIVideoGenerationRequest, type OpenAIVideoTaskResponse } from "./openai_video_generation";
 import { DownloadClient, type DownloadConfig, type DownloadOptions, type StreamDownloadOptions } from "./download";
 import { AuthClient, getCurrentUserInfo, type AuthConfig, type UserInfo } from "./auth";
@@ -25,6 +25,7 @@ export interface LangchainClientConfig {
 export { DoubaoImageGenerationClient, type DoubaoImageGenerationConfig, type DoubaoImageGenerationRequest, type DoubaoImageGenerationResponse, type DoubaoImageSize, };
 export { GeminiImageGenerationClient, type GeminiImageGenerationConfig, type GeminiImageGenerationRequest, type GeminiImageGenerationResponse, };
 export { VideoGenerationClient, type VideoGenerationConfig, type VideoGenerationRequest, type ContentGenerationTaskID, type ContentGenerationTask, };
+export { VideoUnderstandingClient, type VideoUnderstandingConfig, type VideoUnderstandingRequest, type VideoUnderstandingResponse, type VideoUnderstandingStreamChunk, type VideoUnderstandingMessage, type VideoUnderstandingContent, };
 export { OpenAIVideoGenerationClient, type OpenAIVideoGenerationConfig, type OpenAIVideoGenerationRequest, type OpenAIVideoTaskResponse, };
 export { DownloadClient, type DownloadConfig, type DownloadOptions, type StreamDownloadOptions, };
 export { MinioStorageClient, type MinioStorageConfig, type UploadResponse, type ObjectInfo, type PresignedUrlResponse, type UploadOptions, type ListOptions, } from "./minio";

package/dist/index.js

@@ -20,7 +20,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SDK_SIGNATURE = exports.VersionCompatibilityError = exports.sdkConfig = exports.getCurrentUserInfo = exports.AuthClient = exports.AgentSkillClient = exports.DatabaseRequestClient = exports.ResourceClient = exports.MinioStorageClient = exports.DownloadClient = exports.OpenAIVideoGenerationClient = exports.VideoGenerationClient = exports.GeminiImageGenerationClient = exports.DoubaoImageGenerationClient = exports.ChatAnthropic = exports.ChatGoogleGenerativeAI = exports.ChatOpenAI = exports.BaseChatModel = exports.AIMessageChunk = exports.SystemMessage = exports.AIMessage = exports.HumanMessage = void 0;
+exports.SDK_SIGNATURE = exports.VersionCompatibilityError = exports.sdkConfig = exports.getCurrentUserInfo = exports.AuthClient = exports.AgentSkillClient = exports.DatabaseRequestClient = exports.ResourceClient = exports.MinioStorageClient = exports.DownloadClient = exports.OpenAIVideoGenerationClient = exports.VideoUnderstandingClient = exports.VideoGenerationClient = exports.GeminiImageGenerationClient = exports.DoubaoImageGenerationClient = exports.ChatAnthropic = exports.ChatGoogleGenerativeAI = exports.ChatOpenAI = exports.BaseChatModel = exports.AIMessageChunk = exports.SystemMessage = exports.AIMessage = exports.HumanMessage = void 0;
 exports.createChatModel = createChatModel;
 const openai_1 = require("./chat_models/openai");
 const google_1 = require("./chat_models/google");
@@ -30,6 +30,7 @@ const gemini_image_generation_1 = require("./gemini-image-generation");
 Object.defineProperty(exports, "GeminiImageGenerationClient", { enumerable: true, get: function () { return gemini_image_generation_1.GeminiImageGenerationClient; } });
 const video_generation_1 = require("./video_generation");
 Object.defineProperty(exports, "VideoGenerationClient", { enumerable: true, get: function () { return video_generation_1.VideoGenerationClient; } });
+Object.defineProperty(exports, "VideoUnderstandingClient", { enumerable: true, get: function () { return video_generation_1.VideoUnderstandingClient; } });
 const openai_video_generation_1 = require("./openai_video_generation");
 Object.defineProperty(exports, "OpenAIVideoGenerationClient", { enumerable: true, get: function () { return openai_video_generation_1.OpenAIVideoGenerationClient; } });
 const download_1 = require("./download");

package/dist/llm.js

@@ -7,6 +7,7 @@ const google_1 = require("@ai-sdk/google");
 const openai_1 = require("@ai-sdk/openai");
 const config_1 = require("./config");
 const ai_1 = require("ai");
+const ai_sdk_provider_1 = require("@openrouter/ai-sdk-provider");
 /**
  * 根据端点类型创建 ai-sdk ProviderV3
  * 所有请求会通过后端代理（/api/llm/{endpointType}）转发到实际 API
@@ -27,6 +28,10 @@ function createProvider(provider, endpointType, pluginId) {
             Authorization: `Bearer ${config_1.sdkConfig.getToken()}`,
         },
     };
+    if (provider === "openrouter") {
+        settings.baseURL = `${serverUrl}/api/llm/openrouter`;
+        return (0, ai_sdk_provider_1.createOpenRouter)(settings);
+    }
     switch (endpointType) {
         case "openai":
             return (0, openai_1.createOpenAI)(settings);

package/dist/openai_video_generation.d.ts

@@ -7,10 +7,11 @@ export interface OpenAIVideoGenerationConfig {
     token?: string;
     headers?: Record<string, string>;
 }
+export type OpenAIVideoGenerationProvider = "shubiaobiao" | "api2img" | "aiping";
 export interface OpenAIVideoGenerationRequest {
     prompt: string;
     model?: string;
-    provider?: "shubiaobiao" | "api2img";
+    provider?: OpenAIVideoGenerationProvider;
     seconds?: "4" | "8" | "12";
     size?: "720x1280" | "1280x720" | "1024x1792" | "1792x1024";
     input_reference?: string;
@@ -107,7 +108,7 @@ export declare class OpenAIVideoGenerationClient {
      * }
      * ```
      */
-    getTask(taskId: string, provider: "shubiaobiao" | "api2img"): Promise<OpenAIVideoTaskResponse>;
+    getTask(taskId: string, provider: OpenAIVideoGenerationProvider): Promise<OpenAIVideoTaskResponse>;
     /**
      * 轮询等待任务完成
      * Poll and wait for task completion
@@ -125,7 +126,7 @@ export declare class OpenAIVideoGenerationClient {
      * console.log('Video URL:', result.url);
      * ```
      */
-    waitForCompletion(taskId: string, provider?: "shubiaobiao" | "api2img", options?: {
+    waitForCompletion(taskId: string, provider?: OpenAIVideoGenerationProvider, options?: {
         maxAttempts?: number;
         interval?: number;
         onProgress?: (status: OpenAIVideoTaskResponse) => void;
@@ -184,5 +185,5 @@ export declare class OpenAIVideoGenerationClient {
      * const thumbnail = await client.downloadVideo('vid_abc123', 'api2img', 'thumbnail');
      * ```
      */
-    downloadVideo(taskId: string, provider?: "shubiaobiao" | "api2img", variant?: "video" | "thumbnail"): Promise<Blob>;
+    downloadVideo(taskId: string, provider?: OpenAIVideoGenerationProvider, variant?: "video" | "thumbnail"): Promise<Blob>;
 }

package/dist/provider_config.d.ts

@@ -1,7 +1,7 @@
 /**
  * 模型提供商
  */
-export type AIModelProvider = "api2img" | "aihubmix" | "doubao" | "gemini" | "shubiaobiao" | "anthropic";
+export type AIModelProvider = "api2img" | "aihubmix" | "doubao" | "gemini" | "shubiaobiao" | "anthropic" | "aiping" | "openrouter";
 /**
  * 模型端点类型
  * - openai: OpenAI 兼容 API（/v1/chat/completions 等）

package/dist/provider_config.js

@@ -5,10 +5,12 @@ exports.getProviderConfig = getProviderConfig;
 exports.PROVIDER_CONFIGS = {
     shubiaobiao: { provider: "shubiaobiao", modelType: "openai" },
     api2img: { provider: "api2img", modelType: "openai" },
+    aiping: { provider: "aiping", modelType: "openai" },
     aihubmix: { provider: "aihubmix", modelType: "openai" },
     doubao: { provider: "doubao", modelType: "openai" },
     gemini: { provider: "gemini", modelType: "gemini" },
     anthropic: { provider: "anthropic", modelType: "anthropic" },
+    openrouter: { provider: "openrouter", modelType: "openai" },
 };
 function getProviderConfig(provider) {
     return exports.PROVIDER_CONFIGS[provider];

package/dist/video_generation.d.ts

@@ -1,6 +1,6 @@
 /**
- * Video Generation Client
- * 视频生成客户端
+ * Video Generation & Understanding Client
+ * 视频生成 & 视频理解客户端
  */
 export interface VideoGenerationConfig {
     baseUrl?: string;
@@ -88,3 +88,150 @@ export declare class VideoGenerationClient {
         timeout?: number;
     }): Promise<ContentGenerationTask>;
 }
+export interface VideoUnderstandingConfig {
+    baseUrl?: string;
+    token?: string;
+    headers?: Record<string, string>;
+}
+export interface VideoUnderstandingVideoURL {
+    url: string;
+    fps?: number;
+}
+export interface VideoUnderstandingContentText {
+    type: "text";
+    text: string;
+}
+export interface VideoUnderstandingContentVideo {
+    type: "video_url";
+    video_url: VideoUnderstandingVideoURL;
+}
+export interface VideoUnderstandingContentImage {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+}
+export type VideoUnderstandingContent = VideoUnderstandingContentText | VideoUnderstandingContentVideo | VideoUnderstandingContentImage;
+export interface VideoUnderstandingMessage {
+    role: "system" | "user" | "assistant";
+    content: string | VideoUnderstandingContent[];
+}
+export interface VideoUnderstandingRequest {
+    model?: string;
+    /** 视频 URL（简化参数，与 messages 二选一） */
+    video_url?: string;
+    /** 文本提示词（配合 video_url 使用） */
+    prompt?: string;
+    /** 视频采样帧率 */
+    fps?: number;
+    /** 完整消息列表（高级用法）。提供时忽略 video_url/prompt/fps */
+    messages?: VideoUnderstandingMessage[];
+    /** 是否流式输出 */
+    stream?: boolean;
+    /** 最大输出 token 数 */
+    max_tokens?: number;
+    /** 采样温度 */
+    temperature?: number;
+    /** 核采样参数 */
+    top_p?: number;
+    /** 用户标识 */
+    user?: string;
+}
+/** 视频理解使用情况 */
+export interface VideoUnderstandingUsage {
+    /** 提示 token 数 */
+    prompt_tokens: number;
+    /** 完成 token 数 */
+    completion_tokens: number;
+    /** 总 token 数 */
+    total_tokens: number;
+}
+/** 视频理解选择 */
+export interface VideoUnderstandingChoice {
+    /** 索引 */
+    index: number;
+    /** 消息 */
+    message: {
+        /** 角色 */
+        role: string;
+        /** 内容 */
+        content: string;
+    };
+    /** 完成原因 */
+    finish_reason: string | null;
+}
+export interface VideoUnderstandingResponse {
+    /** 任务 ID */
+    id: string;
+    /** 对象 */
+    object: string;
+    /** 模型 */
+    model: string;
+    /** 选择 */
+    choices: VideoUnderstandingChoice[];
+    /** 使用情况 */
+    usage?: VideoUnderstandingUsage;
+}
+export interface VideoUnderstandingStreamDelta {
+    /** 角色 */
+    role?: string;
+    /** 内容 */
+    content?: string;
+}
+export interface VideoUnderstandingStreamChoice {
+    /** 索引 */
+    index: number;
+    /** 增量 */
+    delta: VideoUnderstandingStreamDelta;
+    /** 完成原因 */
+    finish_reason: string | null;
+}
+export interface VideoUnderstandingStreamChunk {
+    /** 任务 ID */
+    id: string;
+    /** 对象 */
+    object: string;
+    /** 模型 */
+    model: string;
+    /** 选择 */
+    choices: VideoUnderstandingStreamChoice[];
+}
+export declare class VideoUnderstandingClient {
+    private headers;
+    constructor(config?: VideoUnderstandingConfig);
+    /**
+     * Analyze a video (non-streaming)
+     * 视频理解（非流式）
+     */
+    understand(request: VideoUnderstandingRequest): Promise<VideoUnderstandingResponse>;
+    /**
+     * Analyze a video with streaming response
+     * 视频理解（流式）
+     *
+     * @returns AsyncGenerator yielding content chunks
+     */
+    understandStream(request: VideoUnderstandingRequest): AsyncGenerator<VideoUnderstandingStreamChunk, void, unknown>;
+    /**
+     * Convenience: analyze video and return full text content
+     * 便捷方法：分析视频并返回完整文本
+     */
+    analyzeVideo(videoUrl: string, options?: {
+        prompt?: string;
+        fps?: number;
+        model?: string;
+        max_tokens?: number;
+    }): Promise<string>;
+    /**
+     * Convenience: analyze video with streaming, collecting full text
+     * 便捷方法：流式分析视频，收集完整文本
+     *
+     * @param onChunk optional callback for each text chunk
+     */
+    analyzeVideoStream(videoUrl: string, options?: {
+        prompt?: string;
+        fps?: number;
+        model?: string;
+        max_tokens?: number;
+        onChunk?: (text: string) => void;
+    }): Promise<string>;
+}

package/dist/video_generation.js

@@ -1,10 +1,10 @@
 "use strict";
 /**
- * Video Generation Client
- * 视频生成客户端
+ * Video Generation & Understanding Client
+ * 视频生成 & 视频理解客户端
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VideoGenerationClient = void 0;
+exports.VideoUnderstandingClient = exports.VideoGenerationClient = void 0;
 const config_1 = require("./config");
 const log_1 = require("./log");
 class VideoGenerationClient {
@@ -92,3 +92,138 @@ class VideoGenerationClient {
     }
 }
 exports.VideoGenerationClient = VideoGenerationClient;
+class VideoUnderstandingClient {
+    constructor(config) {
+        // 合并全局 headers 和配置 headers
+        const globalHeaders = config_1.sdkConfig.getHeaders();
+        this.headers = {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${config_1.sdkConfig.getToken()}`,
+            "X-Base-Url": config?.baseUrl || "",
+            ...globalHeaders,
+            ...config?.headers,
+        };
+    }
+    /**
+     * Analyze a video (non-streaming)
+     * 视频理解（非流式）
+     */
+    async understand(request) {
+        config_1.sdkConfig.ensureVersionCompatible();
+        const url = `${config_1.sdkConfig.getServerUrl()}/api/video-proxy/understand`;
+        const body = { ...request, stream: false };
+        (0, log_1.logRequest)("POST", url, this.headers, body);
+        const response = await fetch(url, {
+            method: "POST",
+            headers: this.headers,
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            (0, log_1.logResponse)(response.status, response.statusText, response.headers, errorText);
+            throw new Error(`Video understanding API error: ${response.status} ${errorText}`);
+        }
+        const data = (await response.json());
+        (0, log_1.logResponse)(response.status, response.statusText, response.headers, data);
+        return data;
+    }
+    /**
+     * Analyze a video with streaming response
+     * 视频理解（流式）
+     *
+     * @returns AsyncGenerator yielding content chunks
+     */
+    async *understandStream(request) {
+        config_1.sdkConfig.ensureVersionCompatible();
+        const url = `${config_1.sdkConfig.getServerUrl()}/api/video-proxy/understand`;
+        const body = { ...request, stream: true };
+        (0, log_1.logRequest)("POST", url, this.headers, body);
+        const response = await fetch(url, {
+            method: "POST",
+            headers: this.headers,
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            (0, log_1.logResponse)(response.status, response.statusText, response.headers, errorText);
+            throw new Error(`Video understanding stream API error: ${response.status} ${errorText}`);
+        }
+        const reader = response.body?.getReader();
+        if (!reader) {
+            throw new Error("Response body is not readable");
+        }
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = lines.pop() || "";
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed || !trimmed.startsWith("data: "))
+                        continue;
+                    const data = trimmed.slice(6);
+                    if (data === "[DONE]")
+                        return;
+                    try {
+                        const chunk = JSON.parse(data);
+                        if (chunk.error) {
+                            throw new Error(chunk.error.message);
+                        }
+                        yield chunk;
+                    }
+                    catch (e) {
+                        if (e instanceof SyntaxError)
+                            continue;
+                        throw e;
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    /**
+     * Convenience: analyze video and return full text content
+     * 便捷方法：分析视频并返回完整文本
+     */
+    async analyzeVideo(videoUrl, options) {
+        const response = await this.understand({
+            video_url: videoUrl,
+            prompt: options?.prompt || "请详细描述这个视频的内容",
+            fps: options?.fps,
+            model: options?.model,
+            max_tokens: options?.max_tokens,
+        });
+        return response.choices?.[0]?.message?.content || "";
+    }
+    /**
+     * Convenience: analyze video with streaming, collecting full text
+     * 便捷方法：流式分析视频，收集完整文本
+     *
+     * @param onChunk optional callback for each text chunk
+     */
+    async analyzeVideoStream(videoUrl, options) {
+        let fullText = "";
+        for await (const chunk of this.understandStream({
+            video_url: videoUrl,
+            prompt: options?.prompt || "请详细描述这个视频的内容",
+            fps: options?.fps,
+            model: options?.model,
+            max_tokens: options?.max_tokens,
+        })) {
+            const content = chunk.choices?.[0]?.delta?.content;
+            if (content) {
+                fullText += content;
+                options?.onChunk?.(content);
+            }
+        }
+        return fullText;
+    }
+}
+exports.VideoUnderstandingClient = VideoUnderstandingClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-world-sdk",
-  "version": "1.3.0",
+  "version": "1.3.3",
   "description": "TypeScript SDK for AI World Platform - Chat Models, Image Generation, and Video Generation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -78,6 +78,7 @@
     "@ai-sdk/anthropic": "^3.0.43",
     "@ai-sdk/google": "^3.0.29",
     "@ai-sdk/openai": "^3.0.28",
+    "@openrouter/ai-sdk-provider": "^2.3.1",
     "ai": "^6.0.85"
   }
 }

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

@@ -1,6 +1,6 @@
 ---
 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), resource management with ACL (ResourceClient), database requests (DatabaseRequestClient), agent skills management (AgentSkillClient), and VSCode extension login (initAIWorld). Triggers on ai-world-sdk, createProvider, sdkConfig, generateText, streamText, generateImage, doubao, MinioStorageClient, minio, ResourceClient, resource management, access control, file sharing, DatabaseRequestClient, database request, table creation, AgentSkillClient, agent skill, vscode extension, initAIWorld, or any AI model integration.
+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/understanding, MinIO object storage (MinioStorageClient), resource management with ACL (ResourceClient), database requests (DatabaseRequestClient), agent skills management (AgentSkillClient), and VSCode extension login (initAIWorld). Triggers on ai-world-sdk, createProvider, sdkConfig, generateText, streamText, generateImage, doubao, video understanding, VideoUnderstandingClient, MinioStorageClient, minio, ResourceClient, resource management, access control, file sharing, DatabaseRequestClient, database request, table creation, AgentSkillClient, agent skill, vscode extension, initAIWorld, or any AI model integration.
 ---
 
 # AI World SDK
@@ -12,7 +12,7 @@ ai-world-sdk 是 AI World 平台的 TypeScript SDK，通过 `createProvider` 创
 
 ## When to Use
 
-- 在 ai-world 插件中调用 AI 模型（文本、图像、视频）
+- 在 ai-world 插件中调用 AI 模型（文本、图像、视频生成/理解）
 - 需要初始化 ai-world-sdk 配置
 - 使用 `createProvider` 调用 Vercel AI SDK
 - 使用 Doubao 豆包图像/视频生成
@@ -117,7 +117,10 @@ sdkConfig.setToken('your-jwt-token');
 sdkConfig.setPluginId('my-plugin');
 ```
 
-也可通过环境变量 `DEBUG_TOKEN`、`PLUGIN_ID`、`AI_WORLD_BASE_URL` 自动初始化。
+也可通过环境变量自动初始化：
+- `AI_WORLD_BASE_URL` — 服务端地址，插件 JS 后端启动时由平台自动注入
+- `PLUGIN_ID` — 插件 ID
+- `DEBUG_TOKEN` — 调试用 JWT Token
 
 ## 功能模块
 
@@ -126,9 +129,35 @@ sdkConfig.setPluginId('my-plugin');
 ### Provider 与模型 → `docs/provider-and-models.md`
 
 - `createProvider(provider, endpointType, pluginId)` 创建 Vercel AI SDK Provider
-- Provider 对照表：`api2img`(推荐) / `gemini` / `aihubmix` / `shubiaobiao`
+- Provider 对照表：`api2img`(推荐) / `gemini` / `aihubmix` / `shubiaobiao` / `aiping` / `openrouter`
+- **OpenRouter**：使用专用代理端点 `/api/llm/openrouter`，模型 ID 格式为 `provider/model`（如 `openai/gpt-4o-mini`、`anthropic/claude-sonnet-4-20250514`、`google/gemini-2.5-flash-preview`）
 - 常用模型列表和 AI SDK 函数速查
 
+#### OpenRouter 快速示例
+
+```typescript
+import { createProvider } from 'ai-world-sdk';
+import { generateText, streamText } from 'ai';
+
+// OpenRouter（endpointType 传 'openai'，SDK 内部自动使用 createOpenRouter）
+const provider = createProvider('openrouter', 'openai', 'my-plugin');
+
+// 非流式
+const result = await generateText({
+  model: provider.languageModel('openai/gpt-4o-mini'),
+  prompt: '你好',
+});
+
+// 流式
+const stream = streamText({
+  model: provider.languageModel('anthropic/claude-sonnet-4-20250514'),
+  prompt: '请介绍人工智能',
+});
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
 ### 文本生成 → `docs/text-generation.md`
 
 - `generateText` / `streamText` / `generateObject` / `streamObject`
@@ -139,9 +168,10 @@ sdkConfig.setPluginId('my-plugin');
 - `DoubaoImageGenerationClient`（豆包 Seedream）
 - `GeminiImageGenerationClient`
 
-### 视频生成 → `docs/video-generation.md`
+### 视频生成 & 视频理解 → `docs/video-generation.md`
 
 - `VideoGenerationClient`（豆包 Seedance）
+- `VideoUnderstandingClient`（豆包视频理解，基于 Chat Completions API）
 - `OpenAIVideoGenerationClient`（Sora）
 
 ### MinIO 对象存储 → `docs/minio-storage.md`

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

@@ -10,17 +10,22 @@
 | `shubiaobiao` | `openai` | 数标标 |
 | `shubiaobiao` | `gemini` | 数标标 Gemini |
 | `shubiaobiao` | `anthropic` | 数标标 Claude |
+| `aiping` | `openai` | 平音 |
+| `aiping` | `gemini` | 平音 Gemini |
+| `aiping` | `anthropic` | 平音 Claude |
 | `gemini` | `gemini` | Google 原生，仅限 Gemini 系列模型 |
+| `openrouter` | `openai` | OpenRouter 聚合服务，SDK 内部自动使用 `createOpenRouter` 和专用代理端点 `/api/llm/openrouter`。模型 ID 格式为 `provider/model`（如 `openai/gpt-4o-mini`、`anthropic/claude-sonnet-4-20250514`） |
 
 ## EndpointType 与模型对应关系
 
 | EndpointType | 适用模型 | 说明 |
 |--------------|----------|------|
 | `gemini` | Google Gemini | 必须使用 Google 的 Gemini 模型（如 `gemini-2.5-flash`、`gemini-2.5-pro`） |
-| `anthropic` | Claude | 必须使用 Anthropic 的 Claude 模型（如 `claude-sonnet-4-5`、`claude-3-5-sonnet`）；**仅 api2img、shubiaobiao 支持此 endpoint** |
+| `anthropic` | Claude | 必须使用 Anthropic 的 Claude 模型（如 `claude-sonnet-4-5`、`claude-3-5-sonnet`）；**仅 api2img、shubiaobiao、aiping 支持此 endpoint** |
 | `openai` | OpenAI 兼容 | 模型兼容 OpenAI 格式，可包括 GPT、以及经聚合的 Gemini/Claude 等（视 provider 能力） |
+| `openai` | OpenRouter 兼容 | 当 provider 为 `openrouter` 时，`endpointType` 传 `openai`，SDK 内部自动切换到 `createOpenRouter` 和专用代理端点 |
 
-规则：**anthropic 不是 provider**，仅 **api2img**、**shubiaobiao** 支持 EndpointType 为 `anthropic`（调用 Claude）；`gemini` provider 用 `gemini` endpoint，其余按上表组合。
+规则：**anthropic 不是 provider**，仅 **api2img**、**shubiaobiao**、**aiping** 支持 EndpointType 为 `anthropic`（调用 Claude）；`gemini` provider 用 `gemini` endpoint；`openrouter` provider 的 `endpointType` 传 `openai`，SDK 内部会自动使用 `@openrouter/ai-sdk-provider` 的 `createOpenRouter` 并路由到专用代理 `/api/llm/openrouter`，其余按上表组合。
 
 > `doubao` 不通过 `createProvider` 使用，豆包有专用客户端（见 image-generation.md / video-generation.md）。
 
@@ -40,7 +45,7 @@ const model = provider.languageModel('gpt-4o-mini');
 // Google Gemini（EndpointType = gemini，仅 Google 模型）
 createProvider('gemini', 'gemini', 'my-plugin').languageModel('gemini-2.5-flash');
 
-// Anthropic Claude（仅 api2img / shubiaobiao 支持 endpointType = anthropic，仅 Claude 模型）
+// Anthropic Claude（仅 api2img / shubiaobiao / aiping 支持 endpointType = anthropic，仅 Claude 模型）
 createProvider('api2img', 'anthropic', 'my-plugin').languageModel('claude-sonnet-4-5');
 
 // OpenAI 兼容（EndpointType = openai，模型兼容 OpenAI 格式；api2img 可聚合多模型）
@@ -48,6 +53,13 @@ const p = createProvider('api2img', 'openai', 'my-plugin');
 p.languageModel('gpt-4o-mini');
 p.languageModel('gemini-2.5-flash');
 p.languageModel('claude-sonnet-4-5');
+
+// OpenRouter（endpointType 传 'openai'，SDK 内部自动切换到 createOpenRouter + 专用代理）
+// 模型 ID 必须使用 provider/model 格式
+const or = createProvider('openrouter', 'openai', 'my-plugin');
+or.languageModel('openai/gpt-4o-mini');
+or.languageModel('anthropic/claude-sonnet-4-20250514');
+or.languageModel('google/gemini-2.5-flash-preview');
 ```
 
 ### 检测模型可用性
@@ -63,8 +75,11 @@ const ok = await checkModel('api2img', 'openai', 'gpt-4o-mini', 'my-plugin');
 |------|------|----------|-------------|
 | `gpt-4o-mini` / `gpt-4o` / `gpt-5.1` | 文本 | `api2img` | `openai`（OpenAI 兼容） |
 | `gemini-2.5-flash` / `gemini-2.5-pro` | 文本 | `gemini` | `gemini`（仅 Google） |
-| `claude-sonnet-4-5` / `claude-3-5-sonnet` | 文本 | `api2img` 或 `shubiaobiao` | `anthropic`（仅 Claude） |
-| `dall-e-3` / `gpt-image-1` | 图像 | `api2img` | `openai` |
+| `claude-sonnet-4-6` / `claude-opus-4-6` | 文本 | `api2img`、`shubiaobiao` 或 `aiping` | `anthropic`（仅 Claude） |
+| `dall-e-3` / `gpt-image-1` | 图像 | `api2img`、`shubiaobiao` 或 `aiping` | `openai` |
+| `openai/gpt-4o-mini` / `openai/gpt-4o` | 文本 | `openrouter` | `openai`（SDK 自动处理） |
+| `anthropic/claude-sonnet-4-20250514` | 文本 | `openrouter` | `openai`（SDK 自动处理） |
+| `google/gemini-2.5-flash-preview` | 文本 | `openrouter` | `openai`（SDK 自动处理） |
 | `doubao-seedream-4-5-251128` | 图像 | — | 专用客户端 |
 
 ## AI SDK 函数速查

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

@@ -1,4 +1,4 @@
-# 视频生成
+# 视频生成 & 视频理解
 
 ## 豆包视频生成（Seedance）
 
@@ -26,6 +26,109 @@ if (result.status === 'succeeded') {
 }
 ```
 
+## 豆包视频理解
+
+使用 `VideoUnderstandingClient` 分析视频内容。基于 Chat Completions API，支持传入视频 URL 进行理解分析。
+
+参考文档: https://www.volcengine.com/docs/82379/1895586
+
+### 支持的模型
+
+| 模型 | 说明 |
+|------|------|
+| `doubao-seed-2-0-pro-260215` | 专业级视频理解 |
+| `doubao-seed-2-0-lite-260215` | 轻量级视频理解 |
+| `doubao-seed-2-0-mini-260215` | mini级视频理解 |
+| `doubao-seed-2-0-code-preview-260215` | 代码预览视频理解 |
+
+### 简化用法（推荐）
+
+```typescript
+import { VideoUnderstandingClient } from 'ai-world-sdk';
+
+const client = new VideoUnderstandingClient({});
+
+// 一行代码分析视频
+const description = await client.analyzeVideo(
+  'https://example.com/video.mp4',
+  { prompt: '请详细描述这个视频的内容' }
+);
+console.log(description);
+```
+
+### 非流式请求
+
+```typescript
+const response = await client.understand({
+  video_url: 'https://example.com/video.mp4',
+  prompt: '这个视频讲了什么？',
+  model: 'doubao-seed-2-0-pro-260215',
+  fps: 1,         // 可选，视频采样帧率，默认为1秒，即每秒从视频中抽取一帧图像
+});
+
+console.log(response.choices[0].message.content);
+console.log(response.usage); // { prompt_tokens, completion_tokens, total_tokens }
+```
+
+### 流式请求
+
+```typescript
+// 方式1: 使用便捷方法
+const text = await client.analyzeVideoStream(
+  'https://example.com/video.mp4',
+  {
+    prompt: '描述视频内容',
+    onChunk: (chunk) => process.stdout.write(chunk),
+  }
+);
+
+// 方式2: 使用 AsyncGenerator
+for await (const chunk of client.understandStream({
+  video_url: 'https://example.com/video.mp4',
+  prompt: '描述视频内容',
+})) {
+  const content = chunk.choices?.[0]?.delta?.content;
+  if (content) process.stdout.write(content);
+}
+```
+
+### 高级用法（完整 messages）
+
+```typescript
+const response = await client.understand({
+  model: 'doubao-seed-2-0-pro-260215',
+  messages: [
+    { role: 'system', content: '你是一个专业的视频分析助手' },
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: '请分析这个视频中的关键事件' },
+        {
+          type: 'video_url',
+          video_url: {
+            url: 'https://example.com/video.mp4',
+          },
+        },
+      ],
+    },
+  ],
+});
+```
+
+### 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `video_url` | `string` | 与 messages 二选一 | 视频 URL |
+| `prompt` | `string` | 否 | 提示词（默认: "请详细描述这个视频的内容"） |
+| `fps` | `number` | 否 | 视频采样帧率，较高值提取更多帧但消耗更多 token |
+| `model` | `string` | 否 | 模型名称（默认: doubao-seed-2-0-pro-260215） |
+| `messages` | `VideoUnderstandingMessage[]` | 与 video_url 二选一 | 完整消息列表（高级用法） |
+| `stream` | `boolean` | 否 | 是否流式输出（默认: false） |
+| `max_tokens` | `number` | 否 | 最大输出 token 数（默认: 4096） |
+| `temperature` | `number` | 否 | 采样温度 0.0-2.0 |
+| `top_p` | `number` | 否 | 核采样参数 0.0-1.0 |
+
 ## OpenAI 视频生成（Sora）
 
 ```typescript

package/skills/ai-world-sdk/docs/vscode-login.md

@@ -9,7 +9,7 @@ VSCode 扩展的 `package.json`:
 ```json
 {
   "dependencies": {
-    "ai-world-sdk": "^1.2.7",
+    "ai-world-sdk": "latest",
     "ai": "^6.0.85"
   },
   "devDependencies": {