@cloudbase/ai 3.3.14-alpha.2 → 3.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbase/ai",
-  "version": "3.3.14-alpha.2",
+  "version": "3.6.2",
   "description": "cloudbase js sdk ai module",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -30,8 +30,8 @@
   "author": "",
   "license": "Apache-2.0",
   "dependencies": {
-    "@cloudbase/types": "3.3.14-alpha.2",
-    "@cloudbase/utilities": "3.3.14-alpha.2",
+    "@cloudbase/types": "3.6.2",
+    "@cloudbase/utilities": "3.6.2",
     "@mattiasbuelens/web-streams-adapter": "^0.1.0",
     "text-encoding-shim": "^1.0.5",
     "web-streams-polyfill": "^4.0.0"
@@ -39,5 +39,5 @@
   "devDependencies": {
     "@cloudbase/adapter-interface": "^0.7.1"
   },
-  "gitHead": "1490b9b59961d394f8952c55335b7a1a63377789"
+  "gitHead": "859557576897d4778857c12fb8d7fe8ca1f3a052"
 }

package/src/AI.ts

@@ -11,19 +11,28 @@ import { langEvent } from '@cloudbase/utilities'
 const { MODELS } = models
 
 class AI {
-  public aiBaseUrl: string
-  public aiBotBaseUrl: string
   public bot: Bot
   public i18n: ICloudbaseConfig['i18n']
   defaultHeaders: { [x: string]: any }
+  private _getBaseUrl?: () => string
+
+  /** 动态获取 aiBaseUrl，支持 registerEndPointWithKey 后端点变更生效 */
+  get aiBaseUrl(): string {
+    return `${this._getBaseUrl ? this._getBaseUrl() : this.baseUrl}/ai`
+  }
+
+  /** 动态获取 aiBotBaseUrl，支持 registerEndPointWithKey 后端点变更生效 */
+  get aiBotBaseUrl(): string {
+    return `${this._getBaseUrl ? this._getBaseUrl() : this.baseUrl}/aibot`
+  }
 
   constructor(
     private req: SDKRequestInterface,
     public baseUrl: string,
     i18n: ICloudbaseConfig['i18n'],
+    getBaseUrl?: () => string,
   ) {
-    this.aiBaseUrl = `${baseUrl}/ai`
-    this.aiBotBaseUrl = `${baseUrl}/aibot`
+    this._getBaseUrl = getBaseUrl
     this.bot = new Bot(this.botRequest, this.aiBotBaseUrl)
     this.i18n = i18n
 
@@ -35,25 +44,42 @@ class AI {
   async handleResponseData(responseData: Promise<unknown> | ReadableStream<Uint8Array>, header?: Headers) {
     const GO_TO_AI_TEXT = `${this.i18n.t('请检查调用方式，或前往云开发 AI+ 首页查看文档')}：https://tcb.cloud.tencent.com/dev#/ai`
 
-    if (typeof responseData === 'object' && responseData && 'then' in responseData) {
-      // 非流式请求，直接返回 json 数据
-      const json = (await responseData) as Record<string, unknown>
-      if (typeof json === 'object' && json && 'code' in json && json.code !== 'NORMAL') {
-        throw new Error(`${this.i18n.t('AI+ 请求出错，错误码')}：${json.code}，${this.i18n.t('错误信息')}：${
-          json.message
+    const throwIfError = (json: unknown) => {
+      if (typeof json === 'object' && json && 'code' in json && (json as any).code !== 'NORMAL') {
+        throw new Error(`${this.i18n.t('AI+ 请求出错，错误码')}：${(json as any).code}，${this.i18n.t('错误信息')}：${
+          (json as any).message
         }\n${GO_TO_AI_TEXT}\n${JSON.stringify(json, null, 2)}`,)
       }
+    }
 
+    // 非流式请求：
+    // - 小程序/Web 适配器返回 Promise（has 'then'）
+    // - Node 适配器已将 body 解析为普通对象（无 'then'、无 getReader）
+    // 两种情况都按 JSON 校验错误码后原样返回
+    if (typeof responseData === 'object' && responseData && typeof (responseData as any).getReader !== 'function') {
+      const json = 'then' in responseData ? await responseData : responseData
+      throwIfError(json)
       return responseData
     }
-    // 流式请求，如果接口出错，会变成传 json 格式的响应，通过 header 判断格式
-    if (header?.get?.('content-type')?.includes('application/json')) {
-      const json = await readableStream2JsonObject(responseData as ReadableStream<Uint8Array>)
+
+    // 判断 responseData 是否是 ReadableStream 实例（兼容 Node.js 适配器非流式场景已解析为 JSON 对象的情况）
+    const isStream = typeof (responseData as any)?.getReader === 'function'
+
+    if (!isStream) {
+      // responseData 已经是解析后的 JSON 对象（如 Node.js 适配器非流式返回），直接检查错误码
+      const json = responseData as unknown as Record<string, unknown>
       if (typeof json === 'object' && json && 'code' in json && json.code !== 'NORMAL') {
         throw new Error(`${this.i18n.t('AI+ 请求出错，错误码')}：${json.code}，${this.i18n.t('错误信息')}：${
           json.message
         }\n${GO_TO_AI_TEXT}\n${JSON.stringify(json, null, 2)}`,)
       }
+      return responseData
+    }
+
+    // 流式请求，如果接口出错，会变成传 json 格式的响应，通过 header 判断格式
+    if (header?.get?.('content-type')?.includes('application/json')) {
+      const json = await readableStream2JsonObject(responseData as ReadableStream<Uint8Array>)
+      throwIfError(json)
     }
     return responseData
   }
@@ -102,7 +128,7 @@ class AI {
       method: 'post',
       headers: { [this.i18n?.LANG_HEADER_KEY]: this.i18n?.lang, ...fetchHeaders, ...headers },
       body: JSON.stringify(data),
-      url,
+      url: this.resolveUrl(url),
       stream,
       timeout,
     })) as { data: Promise<unknown> | ReadableStream<Uint8Array>; header?: Headers }
@@ -111,8 +137,9 @@ class AI {
   }
 
   botRequest: types.BotReq = async ({ method, url, data = {}, headers, stream, timeout }) => {
+    const resolvedUrl = this.resolveUrl(url)
     if (method === 'get') {
-      return this.handleResponseData((await this.req.fetch({ url: `${url}?${objectToParam(data)}`, method, headers, stream, timeout })).data,)
+      return this.handleResponseData((await this.req.fetch({ url: `${resolvedUrl}?${objectToParam(data)}`, method, headers, stream, timeout })).data,)
     }
 
     const fetchHeaders = {
@@ -122,7 +149,7 @@ class AI {
     stream && Object.assign(fetchHeaders, { Accept: 'text/event-stream' })
 
     const { data: responseData, header } = (await this.req.fetch({
-      url,
+      url: resolvedUrl,
       body: JSON.stringify(data),
       headers: {
         [this.i18n?.LANG_HEADER_KEY]: this.i18n?.lang,
@@ -149,6 +176,16 @@ class AI {
     }
     models.toolMap.set(functionTool.name, functionTool.fn)
   }
+
+  /** 动态替换 URL 中的 origin 部分，支持 registerEndPointWithKey 后生效 */
+  private resolveUrl(url: string): string {
+    if (!this._getBaseUrl) return url
+    const currentBase = this._getBaseUrl()
+    if (currentBase !== this.baseUrl && url.startsWith(this.baseUrl)) {
+      return url.replace(this.baseUrl, currentBase)
+    }
+    return url
+  }
 }
 
 export { AI }

package/src/errors.ts

@@ -0,0 +1,23 @@
+/**
+ * 参数校验错误类
+ * 用于统一参数校验错误的格式
+ */
+export class InvalidParamsError extends Error {
+  public code: string
+  public field?: string
+
+  constructor(message: string, field?: string) {
+    super(message)
+    this.name = 'InvalidParamsError'
+    this.code = 'INVALID_PARAMS'
+    this.field = field
+  }
+
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      field: this.field,
+    }
+  }
+}

package/src/index.ts

@@ -58,6 +58,8 @@ interface AIInitOption {
 interface ICreateAI {
   req: SDKRequestInterface
   baseUrl?: string
+  /** 动态获取 baseUrl 的函数，若提供则优先使用，支持端点变更后请求自动跟随 */
+  getBaseUrl?: () => string
   env?: string
   getAccessToken?: () => Promise<{ accessToken: string }>
   handleReqInstance?: HandleRequestInstanceFunc
@@ -74,8 +76,11 @@ interface ICreateAI {
  *
  * 其他参数可按需传入覆盖函数逻辑。
  */
-function createAI({ env, baseUrl, req, getAccessToken, handleReqInstance, i18n }: ICreateAI) {
+function createAI({ env, baseUrl, getBaseUrl: getBaseUrlFunc, req, getAccessToken, handleReqInstance, i18n }: ICreateAI) {
   const getBaseUrl = () => {
+    if (getBaseUrlFunc != null) {
+      return getBaseUrlFunc()
+    }
     if (baseUrl != null) {
       return baseUrl
     }
@@ -95,7 +100,7 @@ function createAI({ env, baseUrl, req, getAccessToken, handleReqInstance, i18n }
     return handleReqInstance({ req })
   }
 
-  return new AI(getReq(), getBaseUrl(), i18n)
+  return new AI(getReq(), getBaseUrl(), i18n, getBaseUrlFunc)
 }
 
 // 兼容
@@ -130,9 +135,12 @@ function ai(
     return `${PROTOCOL}${BASE_URL}`
   }
 
-  const baseUrl = options?.baseUrl ?? getUrlFromCloud()
+  // 若用户传了静态 baseUrl 则使用静态值，否则传入动态获取函数支持端点变更后生效
+  if (options?.baseUrl) {
+    return createAI({ req, baseUrl: options.baseUrl, handleReqInstance: ({ req }) => req, i18n: this.config.i18n })
+  }
 
-  return createAI({ req, baseUrl, handleReqInstance: ({ req }) => req, i18n: this.config.i18n })
+  return createAI({ req, baseUrl: getUrlFromCloud(), getBaseUrl: getUrlFromCloud, handleReqInstance: ({ req }) => req, i18n: this.config.i18n })
 }
 
 const component: ICloudbaseComponent = {
@@ -150,6 +158,7 @@ function registerAi(app: ICloudbase) {
 
 export { AI, Bot, createAi, createAI, restModels as models, registerAi, utils }
 export * from './type'
+export * from './errors'
 
 try {
   (window as any).registerAi = registerAi

package/src/models/image-model.ts

@@ -8,6 +8,7 @@ import type {
   // HunyuanEditImageInput,
   // HunyuanEditImageOutput,
 } from '../type'
+import { InvalidParamsError } from '../errors'
 
 interface HunyuanImageGenerateFn {
   (input: HunyuanARGenerateImageInput): Promise<HunyuanARGenerateImageOutput>
@@ -19,28 +20,53 @@ type GenerateImageFn<TProvider> = TProvider extends 'hunyuan-image'
   : (input: unknown) => Promise<unknown>
 
 export class DefaultImageModel<TProvider extends string> {
-  public defaultGenerateImageSubUrl = 'images/generations'
+  public defaultGenerateImageSubUrl = 'images/ar/generations'
 
-  public generateImageSubUrlConfig: Record<string, Record<string, string>> = {
-    'hunyuan-image': {
-      'hunyuan-image-v3.0-v1.0.4': 'images/ar/generations',
-      'hunyuan-image-v3.0-v1.0.1': 'images/ar/generations',
-    },
+  public generateImageSubUrlConfig: Record<string, Array<[RegExp, string]>> = {
+    'hunyuan-image': [
+      [/^hunyuan-image(-v[12](\..*)?)?$/, 'images/generations'],
+    ],
   }
 
   /** 生成图片 */
   public generateImage: GenerateImageFn<TProvider>
 
-  constructor(private req: ModelReq, public baseUrl: string, public provider: TProvider) {
+  constructor(
+    private req: ModelReq,
+    public baseUrl: string,
+    public provider: TProvider,
+  ) {
     this.generateImage = this.generateImageImpl.bind(this) as GenerateImageFn<TProvider>
   }
 
   /** generateImage 的实际实现 */
   private async generateImageImpl(input: HunyuanARGenerateImageInput | HunyuanGenerateImageInput,): Promise<HunyuanARGenerateImageOutput | HunyuanGenerateImageOutput> {
+    // 当模型为 HY-Image-v3.0-I2I-ToB-v1.0.1 且 provider 为空或为 hunyuan-image 时校验参数
+    if (
+      typeof input === 'object' && input && 'model' in input && input.model === 'HY-Image-v3.0-I2I-ToB-v1.0.1' && (this.provider === '' || this.provider === 'hunyuan-image')
+    ) {
+      const typedInput = input
+      const imageUrls = typedInput.image_urls as string[] | undefined
+      const images = typedInput.images as string[] | undefined
+
+      if (imageUrls && imageUrls.length > 1) {
+        throw new InvalidParamsError(
+          '当模型为 HY-Image-v3.0-I2I-ToB-v1.0.1 时，image_urls 最多只能有 1 个元素',
+          'image_urls',
+        )
+      }
+      if (images && images.length > 1) {
+        throw new InvalidParamsError(
+          '当模型为 HY-Image-v3.0-I2I-ToB-v1.0.1 时，images 最多只能有 1 个元素',
+          'images',
+        )
+      }
+    }
+
     let subUrl = this.defaultGenerateImageSubUrl
 
     if (typeof input === 'object' && input && 'model' in input && typeof input.model === 'string') {
-      const newSubUrl = this.generateImageSubUrlConfig[this.provider]?.[input.model]
+      const newSubUrl = this.getGenerateImageSubUrl(this.provider, input.model)
       if (newSubUrl) subUrl = newSubUrl
     }
 
@@ -56,4 +82,19 @@ export class DefaultImageModel<TProvider extends string> {
   private getGenerateUrl(subUrl: string) {
     return `${this.baseUrl}/${this.provider}/${subUrl}`
   }
+
+  /**
+   * 根据 provider 与 model 解析生成图片的子路径。
+   * 按配置顺序用 RegExp 匹配，命中即返回对应 subUrl。
+   */
+  private getGenerateImageSubUrl(provider: string, model: string): string | undefined {
+    const rules = this.generateImageSubUrlConfig[provider]
+    if (!rules) return undefined
+
+    for (const [pattern, subUrl] of rules) {
+      if (pattern.test(model)) return subUrl
+    }
+
+    return undefined
+  }
 }

package/src/type.ts

@@ -231,12 +231,17 @@ export interface HunyuanGenerateImageInput {
 
 export interface HunyuanARGenerateImageInput {
   /** 模型名称：hunyuan-image-v3.0-v1.0.4（推荐）或 hunyuan-image-v3.0-v1.0.1 */
-  model: 'hunyuan-image-v3.0-v1.0.4' | 'hunyuan-image-v3.0-v1.0.1'
+  model:
+  | 'HY-Image-3.0-Plus-4090-Tob-v1.0'
+  | 'HY-Image-v3.0-I2I-ToB-v1.0.1'
+  | 'hunyuan-image-v3.0-v1.0.4'
+  | 'hunyuan-image-v3.0-v1.0.1'
+  | 'hunyuan-image-v3.0-v1.0.5'
   /** 生成图片使用的文本，不超过 8192 字符 */
   prompt: string
   /**
    * 图片尺寸，格式 "${宽}x${高}"，默认 "1024x1024"
-   * hunyuan-image-v3.0-v1.0.4：宽高 [512, 2048]，面积不超过 1024x1024
+   * HY-Image-3.0-Plus-4090-Tob-v1.0 hunyuan-image-v3.0-v1.0.4：宽高 [512, 2048]，面积不超过 1024x1024
    * hunyuan-image-v3.0-v1.0.1：支持固定尺寸列表
    */
   size?: string
@@ -248,6 +253,14 @@ export interface HunyuanARGenerateImageInput {
   revise?: { value: boolean }
   /** 改写是否开启 thinking 模式，默认开启。开启后效果提升但耗时增加（最大 60s） */
   enable_thinking?: { value: boolean }
+  /**
+   * 垫图url列表，与image二选一，优先选image，大小不超过10MB，支持 jpg jpeg png 格式，最多3张图，image_urls和images必有一个非空
+   */
+  image_urls?: string[]
+  /**
+   * 垫图base64列表，与image_url二选一，优先选image，大小不超过10MB，支持 jpg jpeg png 格式，最多3张图
+   */
+  images?: string[]
 }
 
 export interface HunyuanARGenerateImageOutput {

package/src/utils.ts

@@ -10,7 +10,15 @@ import type {
 } from './type'
 import { TextDecoder } from 'text-encoding-shim'
 
-export const ReadableStream = _ReadableStream as {
+/**
+ * 检测当前环境是否原生支持完整的 Web Streams API（Node.js >= 18 或现代浏览器）
+ * 如果原生支持，则无需使用 polyfill，避免 web-streams-adapter 在高版本 Node.js 中的兼容问题
+ */
+const hasNativeStreams = typeof globalThis.ReadableStream === 'function'
+  && typeof globalThis.TransformStream === 'function'
+  && typeof globalThis.ReadableStream.prototype.pipeThrough === 'function'
+
+export const ReadableStream = (hasNativeStreams ? globalThis.ReadableStream : _ReadableStream) as {
   prototype: ReadableStream
 
   new (
@@ -23,7 +31,7 @@ export const ReadableStream = _ReadableStream as {
   new <R = any>(underlyingSource?: UnderlyingSource<R>, strategy?: QueuingStrategy<R>): ReadableStream<R>
 }
 
-export const TransformStream = _TransformStream as {
+export const TransformStream = (hasNativeStreams ? globalThis.TransformStream : _TransformStream) as {
   prototype: TransformStream
 
   new <I = any, O = any>(
@@ -50,7 +58,14 @@ export const createEventSourceParserTransformStream = () => {
   })
 }
 
-export const toPolyfillReadable = createReadableStreamWrapper(ReadableStream)
+/**
+ * 将任意 ReadableStream 转换为当前环境使用的 ReadableStream 实现
+ * - 在原生支持 Web Streams 的环境（Node.js >= 18、现代浏览器）中，直接返回原始 stream（无需转换）
+ * - 在不支持原生 Web Streams 的环境（旧浏览器、小程序）中，使用 web-streams-adapter 进行转换
+ */
+export const toPolyfillReadable: (readable: any) => any = hasNativeStreams
+  ? readable => readable
+  : createReadableStreamWrapper(ReadableStream)
 
 export class TextDecoderStream {
   private handle: TextDecoder