@tacoreai/web-sdk 1.21.0 → 1.22.1-beta.0

package/README.md

@@ -17,52 +17,63 @@ npm install @tacoreai/web-sdk
 ### AppsClient (Data & AI)
 示例略（保持原有章节）
 
+### AppsClient (Events)
+
+应用自定义埋点应使用事件日志接口，不要把高频事件写入通用数据模型。
+应用代码不要直接请求 `/plat` 平台接口，也不要读取平台登录 token；写入和读取都应通过 `AppsClient.invoke(...)` 走 `/apps/events/*`。事件日志不新增 WebSDK 专用方法，apiName 直接和后端 path 对齐。
+
+```js
+const tracked = await client.invoke('events/track', {
+  eventName: 'signup_click',
+  properties: { plan: 'pro' },
+  visitorId: localStorage.getItem('visitor_id'),
+  sessionId: sessionStorage.getItem('session_id'),
+  path: window.location.pathname,
+});
+
+// 以下读取接口仅适用于已登录且具备 app owner/admin 角色的应用管理界面。
+const event = await client.invoke('events/read', {
+  eventId: tracked?.data?.eventId,
+});
+
+const page = await client.invoke('events/query', {
+  day: '2026-05-14',
+  eventName: 'signup_click',
+  limit: 50,
+});
+```
+
+可用接口包括 `events/track`、`events/batch-track`、`events/read`、`events/batch-read`、`events/query`。写入接口由后端校验应用部署域名或自定义域名来源；所有读取接口都要求 Apps 登录态且当前用户为应用 `owner/admin`。平台通用查看/搜索由平台工作视图承接。
+
 ---
 
-## 文件存储 API（CloudBase 通道）
+## 文件存储 API（R2 / GCS）
 
 先确保已通过 AppsAuthManager 登录，并使用 AppsClient 初始化时提供 appId。以下接口均作用于 /apps 路由，需携带 Authorization。
 
-1) 上传文件（<=20MB）
+1) 上传文件到 R2（公开访问 / 前端展示）
 
 import { AppsClient } from '@tacoreai/web-sdk'
 const client = new AppsClient('YOUR_APP_ID')
 
 const input = document.querySelector('#fileInput')
 const file = input.files[0]
-const result = await client.uploadFile(file, { expires: 3600 })
-// result.data => { fileID, url, path, mimeType, size, expiresIn }
-
-2) 获取临时下载 URL
+const result = await client.uploadFile(file)
+// result => { success: true, url, key }
 
-const { data } = await client.getFileUrl('<fileID>', 1800)
-// data.url 为可直接访问的签名地址（有效期30分钟）
+2) 下载 R2 文件
 
-3) 批量删除文件
+const response = await client.downloadFromR2('<key>')
+const blob = await response.blob()
 
-await client.deleteFiles(['<fileID1>', '<fileID2>'])
+3) 删除 R2 文件
 
-4) 下载文件为 Blob（用于预览或保存）
+await client.deleteFromR2('<key>')
 
-const blob = await client.downloadFile('<fileID>')
-// 例如：保存为本地文件
-const a = document.createElement('a')
-a.href = URL.createObjectURL(blob)
-a.download = 'download.bin'
-a.click()
-URL.revokeObjectURL(a.href)
+4) 上传文件到 GCS（Gemini / 多模态分析输入）
 
----
-
-## [新增] 文件上传与分析
-
-此接口用于上传文件（如 PDF、图片）以供 AI 进行深度分析或作为图片编辑的输入。
-
-### `uploadFileForAnalysis(file)`
-- **功能**: 将文件上传至 Google 的专用存储，并返回一个可供 AI 模型引用的 `fileUri`。
-- **参数**:
-  - `file` (File): 从文件输入框获取的 File 对象。
-- **返回值**: `Promise<{fileUri: string, mimeType: string, ...}>`
+const gcsResult = await client.uploadToGCS(file)
+// gcsResult.fileUri => gs://... ，供 Gemini 等模型使用
 
 ---
 
@@ -111,12 +122,12 @@ const imageUri = result.data.uri;
 - **返回**: `Promise<Object>` (后端响应对象，包含 `data.uri` 或 `data.images`)
 
 ### 核心流程
-1.  **上传图片**: 所有源图片（包括底图、叠加图、掩膜图）都**必须**先通过 `uploadFileForAnalysis(file)` 上传，获取 `fileUri` 和 `mimeType`。
+1.  **上传图片**: Google / Gemini 链路下，所有源图片（包括底图、叠加图、掩膜图）都应先通过 `uploadToGCS(file)` 获取 `gs://` 形式的 `fileUri`。
 2.  **调用编辑**: 使用获取到的 `fileUri` 和 `mimeType`，通过 `editImage` 方法并采用**简化的 `prompt + inputs` 模式**进行调用。
 
 ### 前置要求
 - **必须先登录** (AppsAuthManager)
-- `uploadFileForAnalysis`
+- `uploadToGCS`
 
 ### 1. 简化调用 (prompt + inputs 模式，推荐)
 SDK 会自动将 `prompt` 和 `inputs` 数组组合成标准的多模态 `messages`。
@@ -125,13 +136,13 @@ import { AppsClient } from '@tacoreai/web-sdk'
 const client = new AppsClient('YOUR_APP_ID')
 
 // 1. 上传源文件
-const baseFile = await client.uploadFileForAnalysis(file);
+const baseFile = await client.uploadToGCS(file);
 
 // 2. 调用编辑接口
 const result = await client.editImage({
   prompt: '仅移除图中叠加的文字，保持其他区域不变，输出高清。',
   inputs: [
-    { type: 'uploaded_file', fileUri: baseFile.fileUri, mimeType: baseFile.mimeType }
+    { type: 'uploaded_file', fileUri: baseFile.fileUri, mimeType: file.type }
   ]
 });
 // 获取图片 URI (兼容不同后端返回结构)
@@ -142,41 +153,41 @@ const editedBase64 = result.data.uri || (result.data.images && result.data.image
 
 - **场景 A：单图编辑（去字/去水印/局部替换）**
 
-const base = await client.uploadFileForAnalysis(file);
+const base = await client.uploadToGCS(file);
 const result = await client.editImage({
   prompt: '移除叠加文字，其他区域完全保持不变。',
   inputs: [
-    { type: 'uploaded_file', fileUri: base.fileUri, mimeType: base.mimeType }
+    { type: 'uploaded_file', fileUri: base.fileUri, mimeType: file.type }
   ]
 });
 const base64 = result.data.uri || result.data.images?.[0]?.uri;
 
 - **场景 B：双图融合（将服装穿到模特身上）**
 
-const garment = await client.uploadFileForAnalysis(garmentFile);
-const modelPhoto = await client.uploadFileForAnalysis(modelFile);
+const garment = await client.uploadToGCS(garmentFile);
+const modelPhoto = await client.uploadToGCS(modelFile);
 
 const result = await client.editImage({
   prompt: '将服装自然替换到模特身上，保持姿态与光照；去除服装图背景；保持背景不变；不改变面部和发型。',
   inputs: [
     // 建议顺序：底图（模特）放前，叠加/融合图（服装）放后
-    { type: 'uploaded_file', fileUri: modelPhoto.fileUri, mimeType: modelPhoto.mimeType },
-    { type: 'uploaded_file', fileUri: garment.fileUri, mimeType: garment.mimeType }
+    { type: 'uploaded_file', fileUri: modelPhoto.fileUri, mimeType: modelFile.type },
+    { type: 'uploaded_file', fileUri: garment.fileUri, mimeType: garmentFile.type }
   ]
 });
 const base64 = result.data.uri || result.data.images?.[0]?.uri;
 
 - **场景 C：掩膜修复/扩展（Inpainting / Outpainting）**
 
-const base = await client.uploadFileForAnalysis(baseFile);
-const mask = await client.uploadFileForAnalysis(maskFile); // 掩膜语义按后端约定
+const base = await client.uploadToGCS(baseFile);
+const mask = await client.uploadToGCS(maskFile); // 掩膜语义按后端约定
 
 const result = await client.editImage({
   prompt: '在掩膜区域进行修复，移除水印并保持纹理一致；不要改变未掩膜区域。',
   inputs: [
     // 建议顺序：底图 -> 掩膜
-    { type: 'uploaded_file', fileUri: base.fileUri, mimeType: base.mimeType },
-    { type: 'uploaded_file', fileUri: mask.fileUri, mimeType: mask.mimeType }
+    { type: 'uploaded_file', fileUri: base.fileUri, mimeType: baseFile.type },
+    { type: 'uploaded_file', fileUri: mask.fileUri, mimeType: maskFile.type }
   ]
 });
 const base64 = result.data.uri || result.data.images?.[0]?.uri;
@@ -184,7 +195,7 @@ const base64 = result.data.uri || result.data.images?.[0]?.uri;
 ### 3. 高级模式 (messages 透传)
 用于完全控制请求结构，不推荐常规使用。
 
-const base = await client.uploadFileForAnalysis(file)
+const base = await client.uploadToGCS(file)
 
 const result = await client.editImage({
   model: 'gemini-2.5-flash-image-preview',
@@ -193,7 +204,7 @@ const result = await client.editImage({
       role: 'user',
       content: [
         { type: 'text', text: '移除图中叠加的文字...' },
-        { type: 'uploaded_file', uploaded_file: { fileUri: base.fileUri, mimeType: base.mimeType } }
+        { type: 'uploaded_file', uploaded_file: { fileUri: base.fileUri, mimeType: file.type } }
       ]
     }
   ]
@@ -202,30 +213,46 @@ const base64 = result.data.uri || result.data.images?.[0]?.uri;
 
 ---
 
-## [新增] Sora 视频生成
+## [新增] 视频生成（Seedance 2.0）
 
-通过 AppsClient 调用 Sora 视频生成服务。计费将自动关联到应用所属的组织。
+通过 AppsClient 调用统一视频任务接口。当前云模式默认视频模型为 `agent:tacore-3.3`，后端会映射到火山引擎 `doubao-seedance-2-0-260128`。计费将自动关联到应用所属的组织。
 
 ### 定价
-- **sora-2**: 300 积分/次
-- **sora-2-pro**: 1500 积分/次
+- `agent:tacore-3.3`
+  - 输入价格：4
+  - 输出价格：10
 
 ### `createVideoJob(options)`
 - **功能**: 创建一个异步的视频生成任务。
 - **参数**:
   - `options` (object):
-    - `prompt` (string, 必填): 视频描述提示词。
-    - `model` (string, 必填): 模型名称, 'sora-2' 或 'sora-2-pro'。
-    - `size` (string, 可选): 视频尺寸, 默认为 '1920x1080'。
-    - `seconds` (number, 可选): 视频时长, 默认为 6。
+    - `prompt` (string, 推荐): 视频描述提示词。
+    - `content` (array, 推荐): 多模态输入数组，支持：
+      - `{ type: 'text', text: '...' }`
+      - `{ type: 'image_url', image_url: { url: 'https://...' }, role: 'reference_image' }`
+      - `{ type: 'video_url', video_url: { url: 'https://...' }, role: 'reference_video' }`
+      - `{ type: 'audio_url', audio_url: { url: 'https://...' }, role: 'reference_audio' }`
+    - `model` (string, 可选): 默认 `agent:tacore-3.3`。
+    - `generate_audio` (boolean, 可选): 是否生成音频。
+    - `ratio` (string, 可选): 画幅比例，例如 `16:9`。
+    - `duration` (number, 可选): 视频时长（秒）。
+    - `watermark` (boolean, 可选): 是否保留 provider 水印。
+    - `resolution` (string, 可选): 分辨率。
+    - `seed` (number, 可选): 随机种子。
+    - `return_last_frame` (boolean, 可选): 是否返回尾帧。
+    - `providerOptions` (object, 可选): 透传给 provider 的扩展字段。
 - **返回值**: `Promise<object>` - 包含任务初始状态的文档。
 
+### 参考素材上传
+- 图片、视频、音频参考素材必须先调用 `uploadToR2`，然后把返回的公网 `url` 填到 `content` 中。
+- 不要直接把本地 `File`/`Blob`/base64 传给 `createVideoJob`。
+
 ### `remixVideoJob(jobId, options)`
-- **功能**: 基于一个已完成的视频，创建一个新的 Remix 任务。
+- **功能**: 基于一个已完成的视频，创建一个新的 Remix 任务。后端会自动把原视频作为 `reference_video` 注入。
 - **参数**:
   - `jobId` (string, 必填): 原始视频任务的 `wyID`。
   - `options` (object):
-    - `prompt` (string, 必填): 用于修改视频的提示词。
+    - 兼容 `createVideoJob(options)` 的全部字段，至少需要 `prompt` 或 `content`。
 - **返回值**: `Promise<object>` - 包含新的 Remix 任务初始状态的文档。
 
 ### `getVideoJob(jobId)`
@@ -248,10 +275,29 @@ const client = new AppsClient('YOUR_APP_ID');
 
 async function generateAndPollVideo() {
   try {
+    const image = await client.uploadToR2(fileInput.files[0]);
+    const audio = await client.uploadToR2(audioInput.files[0]);
+
     // 1. 提交任务
     const jobResult = await client.createVideoJob({
-      prompt: 'A stylish woman walks down a Tokyo street filled with warm glowing neon and animated city signage.',
-      model: 'sora-2'
+      model: 'agent:tacore-3.3',
+      content: [
+        { type: 'text', text: '第一视角果茶广告短片' },
+        {
+          type: 'image_url',
+          image_url: { url: image.url },
+          role: 'reference_image',
+        },
+        {
+          type: 'audio_url',
+          audio_url: { url: audio.url },
+          role: 'reference_audio',
+        },
+      ],
+      generate_audio: true,
+      ratio: '16:9',
+      duration: 11,
+      watermark: false,
     });
     const jobId = jobResult.data.wyID;
     console.log('视频任务已创建, ID:', jobId);
@@ -401,4 +447,4 @@ Body:
   • 图像编辑：editImage({ messages }) 或 editImage({ prompt, inputs, ... })
   • 单个爬虫：scrapeUrl({ url, projectId? })
   • 批量爬虫：scrapeMultipleUrls({ urls, projectId?, maxConcurrent? })
-- 错误处理：注意处理 401 未登录、402 余额不足、404 组织不存在、500/503 外部服务异常等。
+- 错误处理：注意处理 401 未登录、402 余额不足、404 组织不存在、500/503 外部服务异常等。

package/database/core/apps/AppServerRuntime.js

@@ -31,12 +31,25 @@ const getRequestSource = (isPlatformProxyRequest, isSchedulerRequest) => {
 };
 
 const createRequestScopedAppsClient = (env, options = {}) => {
-  const { accessToken = null, previewAppServerApiKey = null } = options;
+  const {
+    accessToken = null,
+    previewAppServerApiKey = null,
+    enableAppServerServiceAuth = false,
+  } = options;
   const config = {
     ...env,
     accessToken: accessToken || null,
+    enableAppServerServiceAuth,
   };
 
+  if (enableAppServerServiceAuth) {
+    config.appServerOwnerAppId = env.appId;
+    config.tacoreAppServerServiceToken =
+      env.tacoreAppServerServiceToken ||
+      process.env.TACORE_APP_SERVER_SERVICE_TOKEN ||
+      null;
+  }
+
   if (previewAppServerApiKey) {
     config.previewAppServerApiKey = previewAppServerApiKey;
   }
@@ -274,6 +287,7 @@ export const createAppServerRuntime = async (options = {}) => {
     );
     const requestSource = getRequestSource(isPlatformProxyRequest, isSchedulerRequest);
     let previewAppServerApiKey = null;
+    let isExternalApiKeyRequest = false;
 
     console.log(`[AppServer] invoke api="${apiName}" source="${requestSource}"`);
 
@@ -318,6 +332,8 @@ export const createAppServerRuntime = async (options = {}) => {
         });
       }
 
+      isExternalApiKeyRequest = true;
+
       if (isPreviewMode() && !requestAccessToken) {
         previewAppServerApiKey = requestApiKey;
       }
@@ -330,17 +346,21 @@ export const createAppServerRuntime = async (options = {}) => {
         hasRequestApiKey: Boolean(requestApiKey),
         hasPlatformInteropHeader: Boolean(platformInteropHeader),
         hasSchedulerInteropHeader: Boolean(schedulerInteropHeader),
+        isExternalApiKeyRequest,
         willForwardPreviewAppServerApiKey: Boolean(previewAppServerApiKey),
       });
 
       const appsClient = createRequestScopedAppsClient(env, {
         accessToken: requestAccessToken || null,
         previewAppServerApiKey,
+        enableAppServerServiceAuth: Boolean((isSchedulerRequest || isExternalApiKeyRequest) && !requestAccessToken),
       });
       console.log(`[AppServer Debug] scoped AppsClient api="${apiName}"`, {
         hasAccessToken: Boolean(appsClient.getAccessToken()),
         hasPreviewAppServerApiKey: Boolean(appsClient.config.previewAppServerApiKey),
         hasInteropKey: Boolean(appsClient.config.tacoreServerInteropAppServerApiKey),
+        serviceAuthEnabled: appsClient.config.enableAppServerServiceAuth === true,
+        hasServiceToken: Boolean(appsClient.config.tacoreAppServerServiceToken),
       });
       const data = await appsClient.invokeAppServerAPI(apiName, payload, {
         appsClient,

package/database/core/apps/AppsClient.Tools.js

@@ -33,4 +33,23 @@ export const appsClientToolsMethods = {
     const result = await this._post("/apps/sensitive/detect", { content });
     return result.data;
   },
-};
+
+  // ==================== 外部工具 ====================
+
+  /**
+   * 执行 Google 搜索
+   * @param {object} options
+   * @param {string} options.query - 搜索关键词
+   * @param {number} [options.num=10] - 返回结果数量 (1-10)
+   * @returns {Promise<{success: boolean, data: Array<{title: string, link: string, snippet: string}>}>}
+   */
+  async googleSearch(options = {}) {
+    if (!options.query) {
+      throw new Error("query is required for googleSearch.");
+    }
+    return this._post("/apps/tools/google-search", {
+      appId: this.appId,
+      ...options,
+    });
+  },
+};

package/database/core/apps/AppsClient.VoiceVideo.js

@@ -46,19 +46,21 @@ export const appsClientVoiceVideoMethods = {
     return response; // 直接返回 Response 对象
   },
 
-  // ==================== 新增：Sora 视频生成 ====================
+  // ==================== 新增：视频生成 ====================
 
   /**
-   * 创建一个 Sora 视频生成任务
-   * @param {object} options - { prompt, model, size, seconds }
+   * 创建一个视频生成任务（默认走豆包 Seedance 2.0）
+   * @param {object} options - { prompt?, content?, model?, generate_audio?, ratio?, duration?, watermark?, resolution?, seed?, return_last_frame?, providerOptions? }
    * @returns {Promise<object>} 视频任务文档
    */
   async createVideoJob(options = {}) {
-    if (!options.prompt || !options.model) {
-      throw new Error("prompt and model are required for video generation.");
+    const hasPrompt = typeof options.prompt === "string" && options.prompt.trim();
+    const hasContent = Array.isArray(options.content) && options.content.length > 0;
+    if (!hasPrompt && !hasContent) {
+      throw new Error("prompt or content is required for video generation.");
     }
-    // The middleware uses appId from the body to find the organization
-    return this._post("/apps/sora/videos", {
+
+    return this._post("/apps/videos/tasks", {
       appId: this.appId,
       ...options,
     });
@@ -67,19 +69,23 @@ export const appsClientVoiceVideoMethods = {
   /**
    * 基于现有视频创建一个 Remix 任务
    * @param {string} jobId - 原始视频任务的 wyID
-   * @param {object} options - { prompt }
+   * @param {object} options - 兼容 createVideoJob 的请求体，后端会自动注入 reference_video
    * @returns {Promise<object>} 新的 Remix 任务初始状态的文档
    */
   async remixVideoJob(jobId, options = {}) {
     if (!jobId) {
       throw new Error("jobId of the original video is required for remixing.");
     }
-    if (!options.prompt) {
-      throw new Error("A new prompt is required for remixing.");
+
+    const hasPrompt = typeof options.prompt === "string" && options.prompt.trim();
+    const hasContent = Array.isArray(options.content) && options.content.length > 0;
+    if (!hasPrompt && !hasContent) {
+      throw new Error("prompt or content is required for remixing.");
     }
-    return this._post(`/apps/sora/videos/${jobId}/remix`, {
+
+    return this._post(`/apps/videos/tasks/${jobId}/remix`, {
       appId: this.appId,
-      prompt: options.prompt,
+      ...options,
     });
   },
 
@@ -92,7 +98,7 @@ export const appsClientVoiceVideoMethods = {
     if (!jobId) {
       throw new Error("jobId is required.");
     }
-    return this._get(`/apps/sora/videos/${jobId}`, { appId: this.appId });
+    return this._get(`/apps/videos/tasks/${jobId}`, { appId: this.appId });
   },
 
   /**
@@ -101,6 +107,6 @@ export const appsClientVoiceVideoMethods = {
    * @returns {Promise<object>} 任务列表和分页信息
    */
   async listVideoJobs(options = {}) {
-    return this._get("/apps/sora/videos", { appId: this.appId, ...options });
+    return this._get("/apps/videos/tasks", { appId: this.appId, ...options });
   },
 };

package/database/core/apps/BaseAppsClient.js

@@ -2,6 +2,8 @@ import { getAppsApiBaseUrl, isBrowser, isBackend, isSSR, getGlobalOptions } from
 
 const ACCESS_TOKEN_STORAGE_KEY = "tacoreai_apps_access_token";
 const PREVIEW_APPSERVER_API_KEY_HEADER = "x-tacore-preview-app-server-api-key";
+const APP_SERVER_SERVICE_TOKEN_HEADER = "x-tacore-app-server-service-token";
+const APP_SERVER_OWNER_APP_ID_HEADER = "x-tacore-app-server-owner-app-id";
 const INTEROP_APP_SERVER_API_KEY_REQUIRED_ERROR =
   "tacoreServerInteropAppServerApiKey is required for backend environment. Provide it in config or via TACORE_SERVER_INTEROP_APP_SERVER_API_KEY env var.";
 
@@ -85,6 +87,14 @@ export class BaseAppsClient {
     if (isBackend && !isSSR && !this.config.tacoreServerInteropAppServerApiKey) {
       this.config.tacoreServerInteropAppServerApiKey = process.env.TACORE_SERVER_INTEROP_APP_SERVER_API_KEY;
     }
+    if (
+      isBackend &&
+      !isSSR &&
+      this.config.enableAppServerServiceAuth === true &&
+      !this.config.tacoreAppServerServiceToken
+    ) {
+      this.config.tacoreAppServerServiceToken = process.env.TACORE_APP_SERVER_SERVICE_TOKEN;
+    }
 
     if (shouldRequireInteropAppServerApiKey() && !this.config.tacoreServerInteropAppServerApiKey) {
       throw new Error(INTEROP_APP_SERVER_API_KEY_REQUIRED_ERROR);
@@ -186,8 +196,17 @@ export class BaseAppsClient {
       headers["Authorization"] = `Bearer ${token}`;
     }
 
-    if (isBackend && !isSSR && this.config.tacoreServerInteropAppServerApiKey) {
+    if (
+      isBackend &&
+      !isSSR &&
+      !token &&
+      this.config.enableAppServerServiceAuth === true &&
+      this.config.tacoreServerInteropAppServerApiKey &&
+      this.config.tacoreAppServerServiceToken
+    ) {
       headers["x-tacore-server-interop-app-server-api-key"] = this.config.tacoreServerInteropAppServerApiKey;
+      headers[APP_SERVER_SERVICE_TOKEN_HEADER] = this.config.tacoreAppServerServiceToken;
+      headers[APP_SERVER_OWNER_APP_ID_HEADER] = this.config.appServerOwnerAppId || this.config.appId || process.env.APP_ID || this.appId;
     } else if (
       isBackendPreviewMode() &&
       !token &&

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tacoreai/web-sdk",
   "description": "This file is for app server package, not the real npm package",
-  "version": "1.21.0",
+  "version": "1.22.1-beta.0",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -13,6 +13,7 @@
     "./app-server-runtime": "./database/core/apps/AppServerRuntime.js"
   },
   "scripts": {
-    "release": "npm version minor && git commit -am \"web-sdk update version\" && npm publish"
+    "release": "npm version minor && git commit -am \"web-sdk update version\" && git push && npm publish",
+    "release:beta": "npm version prerelease --preid beta --no-git-tag-version && git commit -am \"web-sdk update beta version\" && npm publish --tag beta"
   }
 }