ai-world-sdk 1.0.12 → 1.0.13

package/README.md

@@ -10,6 +10,7 @@ TypeScript SDK for AI World Platform - 一个功能完整的 AI 应用开发 SDK
 - 🤖 **聊天模型**: 兼容 LangChain.js 接口（OpenAI、Gemini、Claude、Doubao）
 - 🎨 **图像生成**: 支持豆包 Seedream 和 Google Gemini
 - 🎬 **视频生成**: 支持豆包 Seedance
+- 📥 **下载代理**: 支持流式下载和普通下载任意 URL 的二进制文件
 - ⚙️ **全局配置**: 自动从浏览器环境获取配置，简化初始化
 - 🐛 **调试模式**: 支持详细的请求/响应日志
 
@@ -131,6 +132,38 @@ if (result.status === 'succeeded') {
 }
 ```
 
+### 5. 下载代理
+
+```typescript
+import { DownloadClient } from 'ai-world-sdk';
+
+const downloadClient = new DownloadClient({});
+
+// 普通下载（返回 Blob）
+const blob = await downloadClient.download({
+  url: 'https://example.com/file.zip',
+  filename: 'myfile.zip', // 可选
+});
+console.log('文件大小:', blob.size, '字节');
+
+// 下载并保存到本地
+await downloadClient.downloadAsFile({
+  url: 'https://example.com/file.zip',
+  filename: 'myfile.zip',
+});
+
+// 流式下载（使用 for await 迭代）
+let totalSize = 0;
+for await (const chunk of downloadClient.streamDownload({
+  url: 'https://example.com/large-file.zip',
+  filename: 'large-file.zip',
+})) {
+  totalSize += chunk.length;
+  console.log(`已下载: ${totalSize} 字节`);
+}
+console.log('下载完成，总大小:', totalSize, '字节');
+```
+
 ## API 参考
 
 ### 聊天模型
@@ -339,6 +372,158 @@ const result = await client.poll(task.id, {
 });
 ```
 
+### 下载代理
+
+#### DownloadClient
+
+```typescript
+const client = new DownloadClient({
+  baseUrl: 'https://your-api.com', // 可选，默认使用全局配置
+  token: 'your-token',              // 可选，默认使用全局配置
+  headers: {                        // 可选，自定义请求头
+    'X-Custom-Header': 'value',
+  },
+});
+```
+
+#### 方法
+
+##### `download(options: DownloadOptions): Promise<Blob>`
+
+普通下载文件，返回 Blob 对象。
+
+```typescript
+const blob = await client.download({
+  url: 'https://example.com/file.zip',
+  filename: 'myfile.zip', // 可选，下载时的文件名
+});
+
+// 使用 Blob
+const text = await blob.text();        // 读取为文本
+const arrayBuffer = await blob.arrayBuffer(); // 读取为 ArrayBuffer
+const url = URL.createObjectURL(blob); // 创建对象 URL
+```
+
+**参数:**
+- `url` (string, 必需): 要下载的文件 URL（必须是 http:// 或 https://）
+- `filename` (string, 可选): 下载时的文件名，不提供则从 URL 或响应头中提取
+
+**返回:** `Promise<Blob>` - 文件的 Blob 对象
+
+**错误处理:**
+```typescript
+try {
+  const blob = await client.download({
+    url: 'https://example.com/file.zip',
+  });
+  console.log('下载成功:', blob.size, '字节');
+} catch (error) {
+  if (error instanceof Error) {
+    console.error('下载失败:', error.message);
+    // 常见错误：
+    // - "URL is required" - URL 参数缺失
+    // - "Download failed: HTTP 404" - 文件不存在
+    // - "Download failed: HTTP 403" - 访问被拒绝
+    // - "下载超时，请稍后重试" - 下载超时
+  }
+}
+```
+
+##### `downloadAsFile(options: DownloadOptions, downloadFilename?: string): Promise<void>`
+
+下载文件并触发浏览器保存对话框。
+
+```typescript
+await client.downloadAsFile({
+  url: 'https://example.com/file.zip',
+  filename: 'myfile.zip',
+}, 'custom-filename.zip'); // 可选，覆盖 filename
+```
+
+**参数:**
+- `options`: 同 `download()` 方法
+- `downloadFilename` (string, 可选): 下载时的文件名，会覆盖 `options.filename`
+
+**返回:** `Promise<void>`
+
+##### `streamDownload(options: StreamDownloadOptions): AsyncGenerator<Uint8Array>`
+
+流式下载文件，返回异步迭代器，支持 `for await` 迭代。
+
+```typescript
+let totalSize = 0;
+for await (const chunk of client.streamDownload({
+  url: 'https://example.com/large-file.zip',
+  filename: 'large-file.zip',
+})) {
+  totalSize += chunk.length;
+  console.log(`已下载: ${totalSize} 字节`);
+  // 可以在这里处理每个数据块（例如：实时处理、显示进度等）
+}
+console.log('下载完成，总大小:', totalSize, '字节');
+```
+
+**参数:**
+- `url` (string, 必需): 要下载的文件 URL
+- `filename` (string, 可选): 下载时的文件名
+
+**返回:** `AsyncGenerator<Uint8Array>` - 异步迭代器，每次迭代返回一个 `Uint8Array` 数据块
+
+**使用场景:**
+- 下载大文件时显示实时进度（通过累计 chunk.length）
+- 需要处理数据流（例如：实时解析、转码等）
+- 需要监控下载状态
+- 需要流式处理文件内容
+
+**示例：带进度显示**
+
+```typescript
+// 如果服务器提供了 Content-Length，可以从响应头获取总大小
+let totalSize = 0;
+const total = 1024 * 1024 * 10; // 假设已知总大小（实际应从响应头获取）
+
+for await (const chunk of client.streamDownload({
+  url: 'https://example.com/large-file.zip',
+})) {
+  totalSize += chunk.length;
+  const percent = total ? Math.round((totalSize / total) * 100) : null;
+  console.log(`下载进度: ${totalSize}/${total || '未知'} (${percent || '?'}%)`);
+}
+```
+
+**示例：流式处理并保存**
+
+```typescript
+// 流式下载并实时保存到文件系统（Node.js 环境）
+import { createWriteStream } from 'fs';
+import { pipeline } from 'stream/promises';
+
+const chunks: Uint8Array[] = [];
+let totalSize = 0;
+
+for await (const chunk of client.streamDownload({
+  url: 'https://example.com/large-file.zip',
+  filename: 'large-file.zip',
+})) {
+  chunks.push(chunk);
+  totalSize += chunk.length;
+  console.log(`已接收: ${totalSize} 字节`);
+}
+
+// 合并所有块并保存
+const blob = new Blob(chunks);
+const buffer = Buffer.from(await blob.arrayBuffer());
+await fs.promises.writeFile('large-file.zip', buffer);
+console.log('文件保存完成');
+```
+
+**注意事项:**
+- 流式下载适合大文件，可以实时显示进度
+- 普通下载适合小文件，会一次性加载到内存
+- URL 必须是 `http://` 或 `https://` 协议
+- 文件名会自动从 URL 或响应头中提取（如果未提供）
+- 流式下载时，数据块大小由服务器决定，通常为 8KB-64KB
+
 ### 全局配置
 
 ```typescript
@@ -740,6 +925,94 @@ if (result.status === 'succeeded') {
 }
 ```
 
+### 下载代理工作流
+
+```typescript
+import { DownloadClient } from 'ai-world-sdk';
+
+const client = new DownloadClient({});
+
+// 1. 普通下载（小文件）
+const blob = await client.download({
+  url: 'https://example.com/small-file.json',
+  filename: 'data.json',
+});
+
+// 读取文件内容
+const text = await blob.text();
+const data = JSON.parse(text);
+console.log('下载的数据:', data);
+
+// 2. 下载并保存到本地
+await client.downloadAsFile({
+  url: 'https://example.com/document.pdf',
+  filename: 'document.pdf',
+});
+
+// 3. 流式下载大文件（带进度显示）
+let totalSize = 0;
+const total = 1024 * 1024 * 100; // 假设已知总大小（实际应从响应头获取）
+
+for await (const chunk of client.streamDownload({
+  url: 'https://example.com/large-video.mp4',
+  filename: 'video.mp4',
+})) {
+  totalSize += chunk.length;
+  
+  // 显示进度
+  if (total) {
+    const percent = Math.round((totalSize / total) * 100);
+    console.log(`下载进度: ${percent}% (${totalSize}/${total} 字节)`);
+  } else {
+    console.log(`已下载: ${totalSize} 字节`);
+  }
+  
+  // 可以在这里处理每个数据块
+  // 例如：实时验证、显示下载速度等
+}
+
+console.log(`下载完成！总大小: ${totalSize} 字节`);
+
+// 4. 批量下载多个文件
+const urls = [
+  'https://example.com/file1.zip',
+  'https://example.com/file2.zip',
+  'https://example.com/file3.zip',
+];
+
+for (const url of urls) {
+  try {
+    await client.downloadAsFile({
+      url,
+      filename: url.split('/').pop() || 'download',
+    });
+    console.log(`已下载: ${url}`);
+  } catch (error) {
+    console.error(`下载失败 ${url}:`, error);
+  }
+}
+
+// 5. 流式下载并实时处理（例如：解析 JSON 流）
+let buffer = '';
+for await (const chunk of client.streamDownload({
+  url: 'https://example.com/large-data.jsonl',
+})) {
+  // 将 Uint8Array 转换为字符串
+  buffer += new TextDecoder().decode(chunk);
+  
+  // 处理完整的行
+  const lines = buffer.split('\n');
+  buffer = lines.pop() || ''; // 保留不完整的行
+  
+  for (const line of lines) {
+    if (line.trim()) {
+      const data = JSON.parse(line);
+      console.log('处理数据:', data);
+    }
+  }
+}
+```
+
 ## 支持的模型
 
 ### 聊天模型

package/dist/download.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Download Client
+ * 下载客户端
+ * 支持流式下载和普通下载任意 URL 的二进制文件
+ */
+export interface DownloadConfig {
+    baseUrl?: string;
+    token?: string;
+    headers?: Record<string, string>;
+}
+export interface DownloadOptions {
+    url: string;
+    filename?: string;
+}
+export interface StreamDownloadOptions extends DownloadOptions {
+}
+/**
+ * Download Client
+ * 下载客户端类
+ */
+export declare class DownloadClient {
+    private baseUrl;
+    private headers;
+    constructor(config?: DownloadConfig);
+    /**
+     * Download a file from a URL (non-streaming)
+     * 从 URL 下载文件（非流式）
+     *
+     * @param options - Download options
+     * @returns Promise that resolves to a Blob
+     */
+    download(options: DownloadOptions): Promise<Blob>;
+    /**
+     * Stream download a file from a URL
+     * 流式下载文件，返回异步迭代器
+     *
+     * @param options - Stream download options
+     * @returns AsyncGenerator that yields data chunks
+     * @example
+     * ```typescript
+     * let totalSize = 0;
+     * for await (const chunk of client.streamDownload({ url: '...' })) {
+     *   totalSize += chunk.length;
+     *   // 处理每个数据块
+     *   console.log(`已下载: ${totalSize} 字节`);
+     * }
+     * console.log(`下载完成，总大小: ${totalSize} 字节`);
+     * ```
+     */
+    streamDownload(options: StreamDownloadOptions): AsyncGenerator<Uint8Array, void, unknown>;
+    /**
+     * Download a file and trigger browser download
+     * 下载文件并触发浏览器下载
+     *
+     * @param options - Download options
+     * @param downloadFilename - Optional filename for the download (overrides options.filename)
+     */
+    downloadAsFile(options: DownloadOptions, downloadFilename?: string): Promise<void>;
+    /**
+     * Extract filename from URL
+     * 从 URL 中提取文件名
+     */
+    private extractFilenameFromUrl;
+}

package/dist/download.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * Download Client
+ * 下载客户端
+ * 支持流式下载和普通下载任意 URL 的二进制文件
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DownloadClient = void 0;
+const config_1 = require("./config");
+const log_1 = require("./log");
+/**
+ * Download Client
+ * 下载客户端类
+ */
+class DownloadClient {
+    constructor(config = {}) {
+        // 使用配置的 baseUrl 或全局配置
+        this.baseUrl =
+            config.baseUrl ||
+                config_1.sdkConfig.getServerUrl() ||
+                (typeof window !== "undefined" ? window.location.origin : "");
+        // 合并 headers
+        const globalHeaders = config_1.sdkConfig.getHeaders();
+        const globalToken = config_1.sdkConfig.getToken() || config.token;
+        this.headers = {
+            "Content-Type": "application/json",
+            ...globalHeaders,
+            ...config.headers,
+        };
+        // 如果有 token，添加到 Authorization header
+        if (globalToken) {
+            this.headers["Authorization"] = `Bearer ${globalToken}`;
+        }
+        else if (config.token) {
+            this.headers["Authorization"] = `Bearer ${config.token}`;
+        }
+    }
+    /**
+     * Download a file from a URL (non-streaming)
+     * 从 URL 下载文件（非流式）
+     *
+     * @param options - Download options
+     * @returns Promise that resolves to a Blob
+     */
+    async download(options) {
+        const { url, filename } = options;
+        if (!url) {
+            throw new Error("URL is required");
+        }
+        // 构建请求 URL
+        const apiUrl = `${this.baseUrl}/api/download-proxy/download`;
+        const params = new URLSearchParams({ url });
+        if (filename) {
+            params.append("filename", filename);
+        }
+        const fullUrl = `${apiUrl}?${params.toString()}`;
+        (0, log_1.debugLog)("Download request:", { url, filename, fullUrl });
+        (0, log_1.logRequest)("GET", fullUrl, this.headers);
+        try {
+            const response = await fetch(fullUrl, {
+                method: "GET",
+                headers: this.headers,
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                let errorMessage = `Download failed: ${response.status} ${response.statusText}`;
+                try {
+                    const errorJson = JSON.parse(errorText);
+                    errorMessage = errorJson.detail || errorMessage;
+                }
+                catch {
+                    errorMessage = errorText || errorMessage;
+                }
+                throw new Error(errorMessage);
+            }
+            const blob = await response.blob();
+            (0, log_1.debugLog)("Download completed:", {
+                size: blob.size,
+                type: blob.type,
+            });
+            return blob;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            (0, log_1.debugLog)("Download error:", errorMessage);
+            throw error;
+        }
+    }
+    /**
+     * Stream download a file from a URL
+     * 流式下载文件，返回异步迭代器
+     *
+     * @param options - Stream download options
+     * @returns AsyncGenerator that yields data chunks
+     * @example
+     * ```typescript
+     * let totalSize = 0;
+     * for await (const chunk of client.streamDownload({ url: '...' })) {
+     *   totalSize += chunk.length;
+     *   // 处理每个数据块
+     *   console.log(`已下载: ${totalSize} 字节`);
+     * }
+     * console.log(`下载完成，总大小: ${totalSize} 字节`);
+     * ```
+     */
+    async *streamDownload(options) {
+        const { url, filename } = options;
+        if (!url) {
+            throw new Error("URL is required");
+        }
+        // 构建请求 URL
+        const apiUrl = `${this.baseUrl}/api/download-proxy/download`;
+        const params = new URLSearchParams({ url });
+        if (filename) {
+            params.append("filename", filename);
+        }
+        const fullUrl = `${apiUrl}?${params.toString()}`;
+        (0, log_1.debugLog)("Stream download request:", { url, filename, fullUrl });
+        (0, log_1.logRequest)("GET", fullUrl, this.headers);
+        let response;
+        try {
+            response = await fetch(fullUrl, {
+                method: "GET",
+                headers: this.headers,
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                let errorMessage = `Download failed: ${response.status} ${response.statusText}`;
+                try {
+                    const errorJson = JSON.parse(errorText);
+                    errorMessage = errorJson.detail || errorMessage;
+                }
+                catch {
+                    errorMessage = errorText || errorMessage;
+                }
+                throw new Error(errorMessage);
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            (0, log_1.debugLog)("Stream download error:", errorMessage);
+            throw error;
+        }
+        // // 获取内容长度（如果可用）
+        // const contentLength = response.headers.get("content-length");
+        // const total = contentLength ? parseInt(contentLength, 10) : undefined;
+        // 创建 ReadableStream 来处理流式数据
+        const reader = response.body?.getReader();
+        if (!reader) {
+            throw new Error("Response body is not readable");
+        }
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                if (value) {
+                    // yield 数据块，用户可以在迭代时累计大小
+                    yield value;
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    /**
+     * Download a file and trigger browser download
+     * 下载文件并触发浏览器下载
+     *
+     * @param options - Download options
+     * @param downloadFilename - Optional filename for the download (overrides options.filename)
+     */
+    async downloadAsFile(options, downloadFilename) {
+        const blob = await this.download(options);
+        // 确定下载文件名
+        const filename = downloadFilename ||
+            options.filename ||
+            this.extractFilenameFromUrl(options.url) ||
+            "download";
+        // 创建下载链接
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement("a");
+        a.href = url;
+        a.download = filename;
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+        // 清理 URL
+        setTimeout(() => URL.revokeObjectURL(url), 100);
+    }
+    /**
+     * Extract filename from URL
+     * 从 URL 中提取文件名
+     */
+    extractFilenameFromUrl(url) {
+        try {
+            const urlObj = new URL(url);
+            const pathname = urlObj.pathname;
+            const filename = pathname.split("/").pop();
+            if (filename && filename.includes(".")) {
+                return filename.split("?")[0]; // 移除查询参数
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.DownloadClient = DownloadClient;

package/dist/index.d.ts

@@ -8,6 +8,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 { DownloadClient, type DownloadConfig, type DownloadOptions, type StreamDownloadOptions } from "./download";
 import { sdkConfig } from "./config";
 export { BaseMessage, HumanMessage, AIMessage, SystemMessage, AIMessageChunk, type MessageContent, type AIMessageChunkData, } from "./messages";
 export { BaseChatModel, type BaseChatModelParams, type AIModelProvider, type ToolDefinition, type BindOptions, } from "./base";
@@ -22,6 +23,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 { DownloadClient, type DownloadConfig, type DownloadOptions, type StreamDownloadOptions, };
 export { sdkConfig };
 /**
  * Create a chat model instance based on model name

package/dist/index.js

@@ -6,7 +6,7 @@
  * @see https://github.com/langchain-ai/langchainjs
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sdkConfig = 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.sdkConfig = exports.DownloadClient = 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");
@@ -16,6 +16,8 @@ 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; } });
+const download_1 = require("./download");
+Object.defineProperty(exports, "DownloadClient", { enumerable: true, get: function () { return download_1.DownloadClient; } });
 const config_1 = require("./config");
 Object.defineProperty(exports, "sdkConfig", { enumerable: true, get: function () { return config_1.sdkConfig; } });
 // Re-export types and classes

package/dist/log.d.ts

@@ -11,7 +11,7 @@ export declare function debugLog(...args: any[]): void;
  * Log HTTP request
  * 记录 HTTP 请求
  */
-export declare function logRequest(method: string, url: string, headers: Record<string, string>, body?: any): void;
+export declare function logRequest(method: string, url: string, headers?: Record<string, string>, body?: any): void;
 /**
  * Log HTTP response
  * 记录 HTTP 响应

package/dist/log.js

@@ -27,7 +27,7 @@ function logRequest(method, url, headers, body) {
     debugLog("📤 HTTP Request");
     debugLog("  Method:", method);
     debugLog("  URL:", url);
-    debugLog("  Headers:", { ...headers, Authorization: headers.Authorization ? "Bearer ***" : undefined });
+    debugLog("  Headers:", { ...headers, Authorization: headers?.Authorization ? "Bearer ***" : undefined });
     if (body) {
         try {
             const bodyStr = typeof body === "string" ? body : JSON.stringify(body, null, 2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-world-sdk",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "TypeScript SDK for AI World Platform - Chat Models, Image Generation, and Video Generation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",