@tacoreai/web-sdk 1.22.0 → 1.22.1-beta.1

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 }
+const result = await client.uploadFile(file)
+// result => { success: true, url, key }
 
-2) 获取临时下载 URL
+2) 下载 R2 文件
 
-const { data } = await client.getFileUrl('<fileID>', 1800)
-// data.url 为可直接访问的签名地址（有效期30分钟）
+const response = await client.downloadFromR2('<key>')
+const blob = await response.blob()
 
-3) 批量删除文件
+3) 删除 R2 文件
 
-await client.deleteFiles(['<fileID1>', '<fileID2>'])
+await client.deleteFromR2('<key>')
 
-4) 下载文件为 Blob（用于预览或保存）
+4) 上传文件到 GCS（Gemini / 多模态分析输入）
 
-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)
-
----
-
-## [新增] 文件上传与分析
-
-此接口用于上传文件（如 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 } }
       ]
     }
   ]

package/database/core/apps/AppServerRuntime.js

@@ -31,17 +31,36 @@ const getRequestSource = (isPlatformProxyRequest, isSchedulerRequest) => {
 };
 
 const createRequestScopedAppsClient = (env, options = {}) => {
-  const { accessToken = null, previewAppServerApiKey = null } = options;
+  const {
+    accessToken = null,
+    appServerApiKey = null,
+    clientAppId = env.dataSourceId || env.appId,
+    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 (appServerApiKey) {
+    config.appServerApiKey = appServerApiKey;
+  }
+
   if (previewAppServerApiKey) {
     config.previewAppServerApiKey = previewAppServerApiKey;
   }
 
-  return new AppsClient(env.dataSourceId || env.appId, config);
+  return new AppsClient(clientAppId, config);
 };
 
 const isPreviewApiKeyShapeValid = (apiKey) => {
@@ -273,7 +292,9 @@ export const createAppServerRuntime = async (options = {}) => {
       process.env.CLOUDFLARE_WORKER_INTEROP_APP_SERVER_TOKEN
     );
     const requestSource = getRequestSource(isPlatformProxyRequest, isSchedulerRequest);
+    let appServerApiKey = null;
     let previewAppServerApiKey = null;
+    let isExternalApiKeyRequest = false;
 
     console.log(`[AppServer] invoke api="${apiName}" source="${requestSource}"`);
 
@@ -299,6 +320,7 @@ export const createAppServerRuntime = async (options = {}) => {
       try {
         const authClient = createRequestScopedAppsClient(env, {
           accessToken: requestAccessToken || null,
+          clientAppId: env.appId,
         });
         isValidApiKey = await validateExternalApiKey(authClient, env.appId, requestApiKey);
       } catch (error) {
@@ -318,6 +340,9 @@ export const createAppServerRuntime = async (options = {}) => {
         });
       }
 
+      isExternalApiKeyRequest = true;
+      appServerApiKey = requestApiKey;
+
       if (isPreviewMode() && !requestAccessToken) {
         previewAppServerApiKey = requestApiKey;
       }
@@ -330,17 +355,24 @@ export const createAppServerRuntime = async (options = {}) => {
         hasRequestApiKey: Boolean(requestApiKey),
         hasPlatformInteropHeader: Boolean(platformInteropHeader),
         hasSchedulerInteropHeader: Boolean(schedulerInteropHeader),
+        isExternalApiKeyRequest,
+        willForwardAppServerApiKey: Boolean(appServerApiKey && !requestAccessToken),
         willForwardPreviewAppServerApiKey: Boolean(previewAppServerApiKey),
       });
 
       const appsClient = createRequestScopedAppsClient(env, {
         accessToken: requestAccessToken || null,
+        appServerApiKey: requestAccessToken ? null : appServerApiKey,
         previewAppServerApiKey,
+        enableAppServerServiceAuth: Boolean((isSchedulerRequest || isExternalApiKeyRequest) && !requestAccessToken),
       });
       console.log(`[AppServer Debug] scoped AppsClient api="${apiName}"`, {
         hasAccessToken: Boolean(appsClient.getAccessToken()),
+        hasAppServerApiKey: Boolean(appsClient.config.appServerApiKey),
         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.Data.js

@@ -80,22 +80,11 @@ export const appsClientDataMethods = {
         modelName: modelName,
       };
 
-      if (typeof query === "string") {
-        params.wyID = query;
-      } else if (query && typeof query === "object") {
-        const { page = 1, pageSize = 20, fields, filter } = query;
-        params.page = Math.max(1, parseInt(page));
-        params.pageSize = parseInt(pageSize) || 1000;
-        console.log(params);
-        if (fields && Array.isArray(fields)) {
-          params.fields = fields;
-        }
-
-        if (filter && typeof filter === "object") {
-          params.filter = filter;
-        }
+      if (typeof query !== "string" || !query) {
+        throw new Error("readData only supports single-record reads by wyID. Use invoke('data/list', ...) or invoke('data/query', ...) for list/query reads.");
       }
 
+      params.wyID = query;
       const result = await this._get("/apps/data/read", params);
 
       if (result.data === null && params.wyID) {
@@ -152,7 +141,13 @@ export const appsClientDataMethods = {
   async hasData(modelName) {
     try {
       if (!modelName) throw new Error("modelName is required for hasData");
-      const result = await this.readData(modelName, { page: 1, pageSize: 1 });
+      const result = await this.invoke("data/list", {
+        modelName,
+        query: {
+          page: 1,
+          pageSize: 1,
+        },
+      });
       return result && result.data && result.data.length > 0;
     } catch (error) {
       console.error(`检查应用数据失败 (model: ${modelName}):`, error);

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

@@ -0,0 +1,77 @@
+export const appsClientIamMethods = {
+  async getIamContext(params = {}) {
+    return this._post("/apps/iam/me", params);
+  },
+
+  async bootstrapIam(params = {}) {
+    return this._post("/apps/iam/bootstrap", params);
+  },
+
+  async listIamOrgUnits(params = {}) {
+    return this._post("/apps/iam/org-units/list", params);
+  },
+
+  async createIamOrgUnit(params = {}) {
+    return this._post("/apps/iam/org-units", params);
+  },
+
+  async updateIamOrgUnit(params = {}) {
+    return this._post("/apps/iam/org-units/update", params);
+  },
+
+  async deleteIamOrgUnit(params = {}) {
+    return this._post("/apps/iam/org-units/delete", params);
+  },
+
+  async listIamRoles(params = {}) {
+    return this._post("/apps/iam/roles/list", params);
+  },
+
+  async createIamRole(params = {}) {
+    return this._post("/apps/iam/roles", params);
+  },
+
+  async updateIamRole(params = {}) {
+    return this._post("/apps/iam/roles/update", params);
+  },
+
+  async deleteIamRole(params = {}) {
+    return this._post("/apps/iam/roles/delete", params);
+  },
+
+  async listIamStaff(params = {}) {
+    return this._post("/apps/iam/staff/list", params);
+  },
+
+  async createIamStaff(params = {}) {
+    return this._post("/apps/iam/staff", params);
+  },
+
+  async updateIamStaff(params = {}) {
+    return this._post("/apps/iam/staff/update", params);
+  },
+
+  async deleteIamStaff(params = {}) {
+    return this._post("/apps/iam/staff/delete", params);
+  },
+
+  async listModelPolicies(params = {}) {
+    return this._post("/apps/data/model-policies/list", params);
+  },
+
+  async declareModelPolicy(params = {}) {
+    return this._post("/apps/data/model-policies/declare", params);
+  },
+
+  async writeAuditLog(params = {}) {
+    return this._post("/apps/audit/write", params);
+  },
+
+  async queryAuditLogs(params = {}) {
+    return this._post("/apps/audit/query", params);
+  },
+
+  async authorizeFileDownload(params = {}) {
+    return this._post("/apps/files/authorize-download", params);
+  },
+};

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

@@ -62,4 +62,34 @@ export const appsClientUserMethods = {
       password,
     });
   },
+
+  /**
+   * 从当前应用移除用户访问权限，保留 Auth 账号。
+   * @param {Object} params { userId: string }
+   * @returns {Promise<{success: boolean, data: {userId: string, appId: string}}>}
+   */
+  async removeAppUser({ userId }) {
+    if (!userId) {
+      throw new Error("userId is required.");
+    }
+    return this._post("/apps/users/remove", {
+      appId: this.appId,
+      targetUserId: userId,
+    });
+  },
+
+  /**
+   * 彻底删除当前应用中的用户账号，使该邮箱可重新注册。
+   * @param {Object} params { userId: string }
+   * @returns {Promise<{success: boolean, data: {userId: string, appId: string, deletionMode: string, authDeleted: boolean}}>}
+   */
+  async deleteAppUser({ userId }) {
+    if (!userId) {
+      throw new Error("userId is required.");
+    }
+    return this._post("/apps/users/delete", {
+      appId: this.appId,
+      targetUserId: userId,
+    });
+  },
 };

package/database/core/apps/AppsClient.js

@@ -18,6 +18,7 @@ import { appsClientToolsMethods } from "./AppsClient.Tools.js";
 import { appsClientDebugMethods } from "./AppsClient.Debug.js";
 import { appsClientCrawlerMethods } from "./AppsClient.Crawler.js";
 import { appsClientWechatMethods } from "./AppsClient.Wechat.js";
+import { appsClientIamMethods } from "./AppsClient.IAM.js";
 
 const instanceMap = new Map();
 /**
@@ -79,8 +80,7 @@ class AppsClient extends BaseAppsClient {
           return this.readData(modelName, rest.wyID);
         }
         
-        // 兼容旧版平铺参数
-        return this.readData(modelName, rest);
+        throw new Error("readData only supports single-record reads by wyID. Use invoke('data/list', ...) or invoke('data/query', ...) for list/query reads.");
       },
 
       "deleteData": ({ modelName, wyID, options }) =>
@@ -103,8 +103,31 @@ class AppsClient extends BaseAppsClient {
       "createRole": params => this.createRole(params),
       "updateUserRole": params => this.updateUserRole(params),
       "users/update-password": params => this.updateUserPassword(params),
+      "users/remove": params => this.removeAppUser(params),
+      "users/delete": params => this.deleteAppUser(params),
       "listAppUsers": params => this.listAppUsers(params),
 
+      // === 企业 IAM / 审计 / 文件鉴权 ===
+      "iam/me": params => this.getIamContext(params),
+      "iam/bootstrap": params => this.bootstrapIam(params),
+      "iam/org-units/list": params => this.listIamOrgUnits(params),
+      "iam/org-units": params => this.createIamOrgUnit(params),
+      "iam/org-units/update": params => this.updateIamOrgUnit(params),
+      "iam/org-units/delete": params => this.deleteIamOrgUnit(params),
+      "iam/roles/list": params => this.listIamRoles(params),
+      "iam/roles": params => this.createIamRole(params),
+      "iam/roles/update": params => this.updateIamRole(params),
+      "iam/roles/delete": params => this.deleteIamRole(params),
+      "iam/staff/list": params => this.listIamStaff(params),
+      "iam/staff": params => this.createIamStaff(params),
+      "iam/staff/update": params => this.updateIamStaff(params),
+      "iam/staff/delete": params => this.deleteIamStaff(params),
+      "data/model-policies/list": params => this.listModelPolicies(params),
+      "data/model-policies/declare": params => this.declareModelPolicy(params),
+      "audit/write": params => this.writeAuditLog(params),
+      "audit/query": params => this.queryAuditLogs(params),
+      "files/authorize-download": params => this.authorizeFileDownload(params),
+
       // === 文件存储 ===
       "uploadFile": ({ file }) => this.uploadFile(file),
       "uploadToR2": ({ file }) => this.uploadToR2(file),
@@ -213,7 +236,8 @@ Object.assign(
   appsClientToolsMethods,
   appsClientDebugMethods,
   appsClientCrawlerMethods,
-  appsClientWechatMethods
+  appsClientWechatMethods,
+  appsClientIamMethods
 );
 
 export { AppsClient };

package/database/core/apps/AppsPublicClient.js

@@ -4,8 +4,10 @@ import { BaseAppsClient } from "./BaseAppsClient.js";
  * AI应用公共数据客户端 - 无需认证
  *
  * 核心理念：
- * - 用于匿名读取被 `writeData` 设为公共的数据。
+ * - 通过继承的通用 invoke(path, params) 调用匿名公开接口。
+ * - 用于匿名读取模型策略 `publicRead` 明确开放的 CMS 数据。
  * - 用于匿名提交数据到指定的、允许公开写入的模型。
+ * - 保留 `readConfiguredPublicData` 兼容旧 publicConfig 公开读。
  * - 此客户端的所有操作都无需用户登录。
  */
 export class AppsPublicClient extends BaseAppsClient {

package/database/core/apps/BaseAppsClient.js

@@ -2,8 +2,11 @@ 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 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.";
+const APP_SERVER_API_KEY_HEADER = "x-tacore-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 APP_SERVER_SERVICE_CREDENTIAL_REQUIRED_ERROR =
+  "AppServer service credential is required for backend service auth. Provide TACORE_SERVER_INTEROP_APP_SERVER_API_KEY + TACORE_APP_SERVER_SERVICE_TOKEN, or forward a validated appServerApiKey.";
 
 const normalizeAccessToken = (value) => {
   if (typeof value !== "string") {
@@ -48,7 +51,17 @@ const writePersistedAccessToken = (token) => {
 };
 
 const isBackendPreviewMode = () => isBackend && process.env.TACORE_APPSERVER_PREVIEW_MODE === "true";
-const shouldRequireInteropAppServerApiKey = () => isBackend && !isSSR && !isBackendPreviewMode();
+const hasAppServerServiceCredential = (config = {}) => {
+  if (config.tacoreServerInteropAppServerApiKey && config.tacoreAppServerServiceToken) {
+    return true;
+  }
+  if (config.appServerApiKey) {
+    return true;
+  }
+  return isBackendPreviewMode() && Boolean(config.previewAppServerApiKey);
+};
+const shouldRequireAppServerServiceCredential = (config = {}) =>
+  isBackend && !isSSR && config.enableAppServerServiceAuth === true;
 
 /**
  * Apps SDK 基类
@@ -85,9 +98,17 @@ 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);
+    if (shouldRequireAppServerServiceCredential(this.config) && !hasAppServerServiceCredential(this.config)) {
+      throw new Error(APP_SERVER_SERVICE_CREDENTIAL_REQUIRED_ERROR);
     }
   }
 
@@ -157,10 +178,6 @@ export class BaseAppsClient {
       ...additionalHeaders,
     };
 
-    if (this.config.datasource) {
-      headers["x-datasource"] = this.config.datasource;
-    }
-
     if (this.config.supabaseBaseUrl) {
       headers["x-supabase-base-url"] = this.config.supabaseBaseUrl;
     }
@@ -186,8 +203,20 @@ export class BaseAppsClient {
       headers["Authorization"] = `Bearer ${token}`;
     }
 
-    if (isBackend && !isSSR && this.config.tacoreServerInteropAppServerApiKey) {
-      headers["x-tacore-server-interop-app-server-api-key"] = this.config.tacoreServerInteropAppServerApiKey;
+    if (isBackend && !isSSR && !token && this.config.enableAppServerServiceAuth === true) {
+      if (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 (this.config.appServerApiKey && !headers[APP_SERVER_API_KEY_HEADER]) {
+        headers[APP_SERVER_API_KEY_HEADER] = this.config.appServerApiKey;
+      } else if (
+        isBackendPreviewMode() &&
+        this.config.previewAppServerApiKey &&
+        !headers[PREVIEW_APPSERVER_API_KEY_HEADER]
+      ) {
+        headers[PREVIEW_APPSERVER_API_KEY_HEADER] = this.config.previewAppServerApiKey;
+      }
     } else if (
       isBackendPreviewMode() &&
       !token &&
@@ -304,6 +333,7 @@ export class BaseAppsClient {
   getConfig() {
     const config = { ...this.config };
     delete config.accessToken;
+    delete config.appServerApiKey;
     delete config.previewAppServerApiKey;
     return config;
   }

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.22.0",
+  "version": "1.22.1-beta.1",
   "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"
   }
 }

package/utils/index.js

@@ -54,11 +54,8 @@ export function getAppsApiBaseUrl() {
   }
   // 后端环境逻辑
   if (isBackend) {
-    // stone 手动： tacore server 内网地址
-    const baseUrl = process.env.TACORE_SERVER_INTRANET_BASE_URL;
-    if (!baseUrl) {
-      throw new Error("TACORE_SERVER_INTRANET_BASE_URL environment variable is not set in the backend environment.");
-    }
+    // stone 手动：tacore server 地址，优先使用内网地址，兜底走公网（比如平台外本地部署）
+    const baseUrl = process.env.TACORE_SERVER_INTRANET_BASE_URL || 'https://api.tacore.chat';
     return baseUrl;
   }