@tacoreai/web-sdk 1.8.0 → 1.9.0

package/database/core/apps/AppServerRuntime.js

@@ -0,0 +1,351 @@
+import { AppsClient } from "./AppsClient.js";
+
+export const APPSERVER_REQUEST_DATA_FIELD = "requestData";
+
+const DEFAULT_JSON_LIMIT = "50mb";
+const DEFAULT_FILE_SIZE_LIMIT = 100 * 1024 * 1024;
+const DEFAULT_MAX_FILES = 20;
+
+const isPreviewMode = () => process.env.TACORE_APPSERVER_PREVIEW_MODE === "true";
+
+const isValidInternalToken = (incomingValue, expectedValue) => {
+  return Boolean(expectedValue) && Boolean(incomingValue) && incomingValue === expectedValue;
+};
+
+const decodeUploadedFileName = (value) => {
+  if (typeof value !== "string" || !value) {
+    return "";
+  }
+
+  try {
+    return Buffer.from(value, "latin1").toString("utf8");
+  } catch {
+    return value;
+  }
+};
+
+const getRequestSource = (isPlatformProxyRequest, isSchedulerRequest) => {
+  if (isPlatformProxyRequest) return "platform-proxy";
+  if (isSchedulerRequest) return "scheduler";
+  return isPreviewMode() ? "preview-direct" : "external-direct";
+};
+
+const isPreviewApiKeyShapeValid = (apiKey) => {
+  if (typeof apiKey !== "string") return false;
+  const value = apiKey.trim();
+  if (value.length < 8 || value.length > 128) return false;
+  return /^[A-Za-z0-9._-]+$/.test(value);
+};
+
+const validateExternalApiKey = async (appsClient, appId, apiKey) => {
+  const result = await appsClient._post("/apps/application/validate-app-server-api-key", {
+    appId,
+    apiKey,
+  });
+  return Boolean(result?.success && result?.data?.valid);
+};
+
+const getPreviewGuidePayload = (req) => {
+  const baseUrl = `${req.protocol}://${req.get("host")}`;
+  const invokeUrl = `${baseUrl}/invokeAppServerAPI?apiName=YOUR_API_NAME`;
+
+  return {
+    success: true,
+    code: "SUCCESS",
+    data: {
+      previewMode: isPreviewMode(),
+      notes: [
+        "浏览器内的开发预览会通过 CLI 预览桥自动转发到本地应用服务，无需前端手动配置 X-API-Key。",
+        "无文件请求建议继续使用 application/json；需要同时上传文件与 JSON 时，请改用 multipart/form-data，并把 JSON 放在 requestData 字段中。",
+      ],
+      examples: {
+        curlJson: `curl -X POST '${invokeUrl}' -H 'Content-Type: application/json' -H 'X-API-Key: YOUR_APP_SERVER_API_KEY' -d '{\"hello\":\"world\"}'`,
+        curlMultipart: `curl -X POST '${invokeUrl}' -H 'X-API-Key: YOUR_APP_SERVER_API_KEY' -F '${APPSERVER_REQUEST_DATA_FIELD}={\"hello\":\"world\"}' -F 'file=@/path/to/file.pdf'`,
+      },
+    },
+  };
+};
+
+const createPreviewCorsMiddleware = () => {
+  return (req, res, next) => {
+    if (isPreviewMode()) {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Methods", "GET,POST,PUT,PATCH,DELETE,OPTIONS");
+      res.setHeader(
+        "Access-Control-Allow-Headers",
+        "Authorization, Content-Type, X-API-Key, X-Tacore-Server-Interop-App-Server-API-Key, X-Cloudflare-Worker-Interop-App-Server-Token"
+      );
+      if (req.method === "OPTIONS") {
+        return res.status(204).end();
+      }
+    }
+    next();
+  };
+};
+
+const normalizeUploadedFiles = (files = []) => {
+  return files.map((file) => {
+    const fileName = decodeUploadedFileName(file.originalname || "");
+    return {
+      fieldName: file.fieldname,
+      fileName: fileName || file.originalname || "file",
+      mimeType: file.mimetype || "application/octet-stream",
+      size: Number(file.size) || 0,
+      buffer: file.buffer,
+      encoding: file.encoding || "7bit",
+    };
+  });
+};
+
+const isMultipartRequest = (req) => {
+  const contentType = req.get("content-type") || "";
+  return contentType.includes("multipart/form-data");
+};
+
+const parseRequestPayload = (req) => {
+  if (!isMultipartRequest(req)) {
+    return typeof req.body === "undefined" ? {} : req.body;
+  }
+
+  const rawRequestData = typeof req.body?.[APPSERVER_REQUEST_DATA_FIELD] === "string"
+    ? req.body[APPSERVER_REQUEST_DATA_FIELD]
+    : "";
+
+  if (!rawRequestData.trim()) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(rawRequestData);
+  } catch (error) {
+    const parseError = new Error(`${APPSERVER_REQUEST_DATA_FIELD} must be valid JSON`);
+    parseError.statusCode = 400;
+    parseError.code = "INVALID_REQUEST_DATA";
+    throw parseError;
+  }
+};
+
+const createMultipartMiddleware = async (options = {}) => {
+  const multerModule = await import("multer");
+  const multer = multerModule.default || multerModule;
+  const upload = multer({
+    storage: multer.memoryStorage(),
+    limits: {
+      fileSize: Number(options.fileSizeLimit) > 0 ? Number(options.fileSizeLimit) : DEFAULT_FILE_SIZE_LIMIT,
+      files: Number(options.maxFiles) > 0 ? Number(options.maxFiles) : DEFAULT_MAX_FILES,
+    },
+  });
+
+  return (req, res, next) => {
+    if (!isMultipartRequest(req)) {
+      next();
+      return;
+    }
+
+    upload.any()(req, res, (error) => {
+      if (!error) {
+        next();
+        return;
+      }
+
+      if (error.code === "LIMIT_FILE_SIZE") {
+        res.status(413).json({
+          success: false,
+          code: "FILE_TOO_LARGE",
+          error: `File too large (max ${Number(options.fileSizeLimit) > 0 ? Number(options.fileSizeLimit) : DEFAULT_FILE_SIZE_LIMIT} bytes)`,
+        });
+        return;
+      }
+
+      if (error.code === "LIMIT_FILE_COUNT") {
+        res.status(413).json({
+          success: false,
+          code: "TOO_MANY_FILES",
+          error: `Too many files (max ${Number(options.maxFiles) > 0 ? Number(options.maxFiles) : DEFAULT_MAX_FILES})`,
+        });
+        return;
+      }
+
+      res.status(400).json({
+        success: false,
+        code: "INVALID_MULTIPART_REQUEST",
+        error: error.message,
+      });
+    });
+  };
+};
+
+export const createAppServerRuntime = async (options = {}) => {
+  const expressModule = await import("express");
+  const express = expressModule.default || expressModule;
+  const {
+    env,
+    jsonLimit = DEFAULT_JSON_LIMIT,
+    fileSizeLimit = DEFAULT_FILE_SIZE_LIMIT,
+    maxFiles = DEFAULT_MAX_FILES,
+  } = options;
+
+  if (!env || typeof env !== "object") {
+    throw new Error("env is required for createAppServerRuntime");
+  }
+
+  const app = express();
+  const multipartMiddleware = await createMultipartMiddleware({ fileSizeLimit, maxFiles });
+
+  app.use(express.json({ limit: jsonLimit }));
+  app.use(express.urlencoded({ extended: true, limit: jsonLimit }));
+  if (isPreviewMode()) {
+    app.use(createPreviewCorsMiddleware());
+
+    app.get("/__preview/health", (req, res) => {
+      res.json({
+        success: true,
+        code: "SUCCESS",
+        data: {
+          status: "ok",
+          previewMode: true,
+          timestamp: Date.now(),
+        },
+      });
+    });
+
+    app.get("/__preview/guide", (req, res) => {
+      res.json(getPreviewGuidePayload(req));
+    });
+  }
+
+  app.post("/invokeAppServerAPI", multipartMiddleware, async (req, res) => {
+    const apiName = req.query.apiName;
+    const platformInteropHeader = req.get("x-tacore-server-interop-app-server-api-key");
+    const schedulerInteropHeader = req.get("x-cloudflare-worker-interop-app-server-token");
+    const requestApiKey = req.get("x-api-key");
+    const requestAccessToken = req.get("authorization") || "";
+
+    if (!apiName) {
+      return res.status(400).json({
+        success: false,
+        code: "INVALID_API_NAME",
+        error: "apiName is required",
+      });
+    }
+    if (!env.appId) {
+      return res.status(400).json({
+        success: false,
+        code: "MISSING_APP_ID",
+        error: "env.appId is required",
+      });
+    }
+
+    let payload = {};
+    try {
+      payload = parseRequestPayload(req);
+    } catch (error) {
+      return res.status(Number(error.statusCode) || 400).json({
+        success: false,
+        code: error.code || "INVALID_REQUEST_PAYLOAD",
+        error: error.message,
+      });
+    }
+
+    const appsClient = AppsClient.getInstance(env.appId, { ...env, accessToken: requestAccessToken || null });
+    const previewBridgeInteropToken =
+      process.env.TACORE_APPSERVER_PREVIEW_BRIDGE_INTEROP_TOKEN ||
+      process.env.TACORE_SERVER_INTEROP_APP_SERVER_API_KEY;
+    const isPlatformProxyRequest = isValidInternalToken(
+      platformInteropHeader,
+      previewBridgeInteropToken
+    );
+    const isSchedulerRequest = isValidInternalToken(
+      schedulerInteropHeader,
+      process.env.CLOUDFLARE_WORKER_INTEROP_APP_SERVER_TOKEN
+    );
+    const requestSource = getRequestSource(isPlatformProxyRequest, isSchedulerRequest);
+
+    console.log(`[AppServer] invoke api="${apiName}" source="${requestSource}"`);
+
+    if (!isPlatformProxyRequest && !isSchedulerRequest) {
+      if (!requestApiKey) {
+        console.warn("[AppServer Auth] Missing X-API-Key. This request is treated as external call.");
+        return res.status(401).json({
+          success: false,
+          code: "MISSING_API_KEY",
+          error: "X-API-Key header is required",
+        });
+      }
+
+      if (!isPreviewApiKeyShapeValid(requestApiKey)) {
+        return res.status(400).json({
+          success: false,
+          code: "INVALID_API_KEY_FORMAT",
+          error: "X-API-Key format is invalid. Expected 8-128 chars: [A-Za-z0-9._-]",
+        });
+      }
+
+      let isValidApiKey = false;
+      try {
+        isValidApiKey = await validateExternalApiKey(appsClient, env.appId, requestApiKey);
+      } catch (error) {
+        console.error("[AppServer] Failed to validate external API key:", error);
+        return res.status(500).json({
+          success: false,
+          code: "API_KEY_VALIDATION_FAILED",
+          error: error.message,
+        });
+      }
+
+      if (!isValidApiKey) {
+        return res.status(401).json({
+          success: false,
+          code: "INVALID_API_KEY",
+          error: "Invalid X-API-Key",
+        });
+      }
+    }
+
+    try {
+      const data = await appsClient.invokeAppServerAPI(apiName, payload, {
+        appsClient,
+        req,
+        res,
+        files: normalizeUploadedFiles(req.files || []),
+        requestSource,
+      });
+
+      if (data && typeof data === "object" && !Buffer.isBuffer(data)) {
+        return res.json({ success: true, code: "SUCCESS", data });
+      }
+      return res.send(data);
+    } catch (error) {
+      console.error(`[AppServer] invoke failed api="${apiName}" source="${requestSource}"`, error);
+      return res.status(500).json({
+        success: false,
+        code: "INVOKE_APP_SERVER_API_FAILED",
+        error: error.message,
+      });
+    }
+  });
+
+  const listen = (listenOptions = {}) => {
+    const port = listenOptions.port || process.env.PORT || 9000;
+    const host = listenOptions.host;
+    const callback = typeof listenOptions.onListen === "function"
+      ? listenOptions.onListen
+      : () => {
+        console.log(`[AppServer] listening on http://localhost:${port} (previewMode=${isPreviewMode()})`);
+      };
+
+    if (host) {
+      return app.listen(port, host, callback);
+    }
+    return app.listen(port, callback);
+  };
+
+  return {
+    app,
+    env,
+    listen,
+    constants: {
+      requestDataField: APPSERVER_REQUEST_DATA_FIELD,
+    },
+  };
+};

package/database/core/apps/AppsAuthManager.js

@@ -1,30 +1,6 @@
 import { isBrowser, isBackend } from "../../../utils/index.js";
 import { BaseAppsClient } from "./BaseAppsClient.js";
 
-/**
- * AI应用 Token 管理工具类
- */
-class AppsTokenManager {
-  static setAccessToken(token) {
-    if (isBrowser) {
-      localStorage.setItem("tacoreai_apps_access_token", token);
-    }
-  }
-
-  static getAccessToken() {
-    if (isBrowser) {
-      return localStorage.getItem("tacoreai_apps_access_token");
-    }
-    return null;
-  }
-
-  static clearAccessToken() {
-    if (isBrowser) {
-      localStorage.removeItem("tacoreai_apps_access_token");
-    }
-  }
-}
-
 /**
  * AI应用认证管理器
  * 负责AI应用的用户认证、会话管理
@@ -75,7 +51,7 @@ export class AppsAuthManager extends BaseAppsClient {
       
       if (token) {
         console.log('[AppsAuthManager] Found token in URL, performing silent login...');
-        AppsTokenManager.setAccessToken(token);
+        this.setAccessToken(token);
         
         // 清除 URL 中的 token 参数，避免分享泄露
         const newUrl = window.location.protocol + "//" + window.location.host + window.location.pathname;
@@ -95,7 +71,7 @@ export class AppsAuthManager extends BaseAppsClient {
    * 重写基类方法，提供 Token
    */
   _getAccessToken() {
-    return AppsTokenManager.getAccessToken();
+    return this.getAccessToken({ fallbackToStorage: isBrowser });
   }
 
   /**
@@ -129,7 +105,7 @@ export class AppsAuthManager extends BaseAppsClient {
 
     // 成功验证后，后端会返回会话信息
     if (result.accessToken) {
-      AppsTokenManager.setAccessToken(result.accessToken);
+      this.setAccessToken(result.accessToken);
     }
 
     return result;
@@ -149,7 +125,7 @@ export class AppsAuthManager extends BaseAppsClient {
     });
 
     if (result.accessToken) {
-      AppsTokenManager.setAccessToken(result.accessToken);
+      this.setAccessToken(result.accessToken);
     }
 
     return result;
@@ -168,7 +144,7 @@ export class AppsAuthManager extends BaseAppsClient {
     });
 
     if (result.accessToken) {
-      AppsTokenManager.setAccessToken(result.accessToken);
+      this.setAccessToken(result.accessToken);
     }
 
     return result;
@@ -216,7 +192,7 @@ export class AppsAuthManager extends BaseAppsClient {
         method: "POST",
       });
     } finally {
-      AppsTokenManager.clearAccessToken();
+      this.clearAccessToken();
     }
   }
 
@@ -238,7 +214,7 @@ export class AppsAuthManager extends BaseAppsClient {
    * @returns {Promise<Object|null>}
    */
   async getSession() {
-    const token = AppsTokenManager.getAccessToken();
+    const token = this.getAccessToken({ fallbackToStorage: isBrowser });
     if (!token) {
       return null;
     }
@@ -259,14 +235,14 @@ export class AppsAuthManager extends BaseAppsClient {
    * @returns {Promise<boolean>}
    */
   async isAuthenticated() {
-    const token = AppsTokenManager.getAccessToken();
+    const token = this.getAccessToken({ fallbackToStorage: isBrowser });
     if (!token) return false;
 
     try {
       await this.getCurrentUser();
       return true;
     } catch (error) {
-      AppsTokenManager.clearAccessToken();
+      this.clearAccessToken();
       return false;
     }
   }
@@ -280,7 +256,7 @@ export class AppsAuthManager extends BaseAppsClient {
     // 简化版本：立即检查当前状态
     this.isAuthenticated().then((isAuth) => {
       callback(isAuth ? "SIGNED_IN" : "SIGNED_OUT", {
-        access_token: AppsTokenManager.getAccessToken(),
+        access_token: this.getAccessToken({ fallbackToStorage: isBrowser }),
       });
     });
 
@@ -324,14 +300,17 @@ export class AppsAuthManager extends BaseAppsClient {
    * 获取访问令牌
    * @returns {string|null}
    */
-  getAccessToken() {
-    return AppsTokenManager.getAccessToken();
+  getAccessToken(options = {}) {
+    return super.getAccessToken({
+      fallbackToStorage: isBrowser,
+      ...options,
+    });
   }
 
   /**
    * 清除访问令牌
    */
-  clearAccessToken() {
-    AppsTokenManager.clearAccessToken();
+  clearAccessToken(options = {}) {
+    super.clearAccessToken(options);
   }
 }

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

@@ -36,8 +36,21 @@ export const appsClientAiMethods = {
       });
 
       if (!response.ok) {
-        const errorData = await response.json().catch(() => ({ error: "Network error" }));
-        throw new Error(errorData.error || `HTTP ${response.status}: ${response.statusText}`);
+        const errorText = await response.text().catch(() => "");
+        let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+
+        if (errorText) {
+          try {
+            const errorData = JSON.parse(errorText);
+            errorMessage = [errorData?.error, errorData?.message]
+              .filter((item) => typeof item === "string" && item.trim())
+              .join(": ") || errorText;
+          } catch {
+            errorMessage = errorText;
+          }
+        }
+
+        throw new Error(errorMessage);
       }
 
       const reader = response.body?.getReader();
@@ -226,4 +239,4 @@ export const appsClientAiMethods = {
       throw error;
     }
   },
-};
+};

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

@@ -1,146 +1,424 @@
 import { env, isDevelopmentBrowser, isProductionBrowser, isBackend } from "../../../utils/index.js";
 
 const appServerAPIMap = new Map();
+const previewSessionTokenCache = new Map();
+const previewSessionPromiseCache = new Map();
+
+const PREVIEW_TOKEN_HEADER = "X-Tacore-AppServer-Preview-Token";
+const APPSERVER_REQUEST_DATA_FIELD = "requestData";
+const DEFAULT_FILE_FIELD_NAME = "file";
 
 const isBrowserPreviewRuntime = () => {
   if (typeof window === "undefined") {
     return false;
   }
 
-  const explicitFlag = window.__TACORE_PREVIEW_MODE__;
-  if (explicitFlag === true || explicitFlag === "true") {
+  const pathname = typeof window.location?.pathname === "string" ? window.location.pathname : "";
+  return pathname.startsWith("/app-run/");
+};
+
+const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+
+const isPlainObject = (value) => Object.prototype.toString.call(value) === "[object Object]";
+
+const isFileLike = (value) => typeof File !== "undefined" && value instanceof File;
+
+const isBlobLike = (value) => typeof Blob !== "undefined" && value instanceof Blob;
+
+const isBufferLike = (value) => typeof Buffer !== "undefined" && Buffer.isBuffer(value);
+
+const isBinaryLike = (value) => {
+  if (!value) {
+    return false;
+  }
+
+  if (isFileLike(value) || isBlobLike(value) || isBufferLike(value)) {
     return true;
   }
 
-  const pathname = typeof window.location?.pathname === "string" ? window.location.pathname : "";
-  return pathname.startsWith("/app-run/");
+  if (value instanceof ArrayBuffer) {
+    return true;
+  }
+
+  return ArrayBuffer.isView(value);
+};
+
+const decodeBase64Binary = (value) => {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(value, "base64");
+  }
+
+  if (typeof atob === "function") {
+    const decoded = atob(value);
+    const bytes = new Uint8Array(decoded.length);
+    for (let i = 0; i < decoded.length; i += 1) {
+      bytes[i] = decoded.charCodeAt(i);
+    }
+    return bytes;
+  }
+
+  throw new Error("Base64 appServer file input is not supported in the current runtime");
+};
+
+const buildAuthorizationHeaderValue = (token) => {
+  if (typeof token !== "string") {
+    return "";
+  }
+
+  const trimmed = token.trim();
+  if (!trimmed) {
+    return "";
+  }
+
+  return /^Bearer\s+/i.test(trimmed) ? trimmed : `Bearer ${trimmed}`;
+};
+
+const getAccessTokenHeaderValue = function() {
+  return buildAuthorizationHeaderValue(typeof this._getAccessToken === "function" ? this._getAccessToken() : "");
 };
 
 /**
  * 注册一个 App Server API。
- * - 在开发态浏览器中：有效，用于本地调用。
- * - 在生产态浏览器中：无效，为空操作。
- * - 在后端云函数中：有效，用于加载服务。
- * @param {string} appServerAPIName - API名称。
- * @param {Function} appServerAPIHandler - 服务的处理函数，接收一个 payload 参数。
+ * - 开发态浏览器：用于兼容旧的本地执行模式。
+ * - 后端环境：用于实际注册 AppServer API。
+ * - 生产态浏览器：无效，为空操作。
  */
 const registerAppServerAPI = (appServerAPIName, appServerAPIHandler) => {
   if (isDevelopmentBrowser || isBackend) {
     appServerAPIMap.set(appServerAPIName, appServerAPIHandler);
   }
-  // 在生产态浏览器中，这是一个空操作。
 };
 
-const invokeByPlatformProxy = async function(appServerAPIName, payload) {
-  const endpoint = `/apps/invokeAppServerAPI?appId=${encodeURIComponent(this.appId)}&apiName=${encodeURIComponent(appServerAPIName)}`;
-  const res = await this._post(endpoint, payload);
-  if (res.success) {
-    return res.data;
-  }
-  throw new Error(res.error || res.message || `AppServer invocation failed: ${res.code || "UNKNOWN_ERROR"}`);
+const clearPreviewSessionToken = (appId) => {
+  previewSessionTokenCache.delete(appId);
+  previewSessionPromiseCache.delete(appId);
 };
 
-const invokeByPreviewProxy = async function(appServerAPIName, payload) {
-  const endpoint = `/appserver-preview/invokeAppServerAPI?appId=${encodeURIComponent(this.appId)}&apiName=${encodeURIComponent(appServerAPIName)}`;
+const getPreviewSessionToken = async function(options = {}) {
+  const { forceRefresh = false } = options;
+  if (forceRefresh) {
+    clearPreviewSessionToken(this.appId);
+  }
 
-  const response = await fetch(endpoint, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(payload || {}),
-  });
+  const cachedToken = previewSessionTokenCache.get(this.appId);
+  if (cachedToken) {
+    return cachedToken;
+  }
+
+  const pendingRequest = previewSessionPromiseCache.get(this.appId);
+  if (pendingRequest) {
+    return pendingRequest;
+  }
+
+  const requestPromise = (async () => {
+    const endpoint = `/appserver-preview/session?appId=${encodeURIComponent(this.appId)}`;
+    const response = await fetch(endpoint, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+      },
+      cache: "no-store",
+    });
+
+    const responseData = await parseAppServerResponsePayload(response);
+
+    if (!response.ok) {
+      throw createAppServerError("[AppServer-PreviewSession]", response, responseData);
+    }
+
+    const previewToken = typeof responseData?.data?.previewToken === "string"
+      ? responseData.data.previewToken.trim()
+      : "";
+
+    if (!previewToken) {
+      throw new Error("[AppServer-PreviewSession] Missing preview token in session response.");
+    }
+
+    previewSessionTokenCache.set(this.appId, previewToken);
+    return previewToken;
+  })();
 
+  previewSessionPromiseCache.set(this.appId, requestPromise);
+  try {
+    return await requestPromise;
+  } finally {
+    previewSessionPromiseCache.delete(this.appId);
+  }
+};
+
+const isInvalidPreviewTokenError = (error) => {
+  const response = error?.response;
+  const responseData = error?.responseData;
+  return response?.status === 401 && responseData?.code === "INVALID_PREVIEW_TOKEN";
+};
+
+const parseAppServerResponsePayload = async (response) => {
   const contentType = response.headers.get("content-type") || "";
-  const responseData = contentType.includes("application/json")
-    ? await response.json()
-    : await response.text();
+  if (contentType.includes("application/json")) {
+    return await response.json();
+  }
+  return await response.text();
+};
+
+const createAppServerError = (label, response, responseData) => {
+  const message = typeof responseData === "object"
+    ? (responseData?.error || responseData?.message || JSON.stringify(responseData))
+    : String(responseData || response.statusText || "");
+
+  const error = new Error(`${label} status: ${response.status}, message: ${message}`);
+  error.response = response;
+  error.responseData = responseData;
+  error.statusCode = response.status;
+  if (typeof responseData === "object" && responseData?.code) {
+    error.code = responseData.code;
+  }
+  return error;
+};
+
+const unwrapAppServerResponse = async (response, label) => {
+  const responseData = await parseAppServerResponsePayload(response);
 
   if (!response.ok) {
-    const errorMessage = typeof responseData === "object"
-      ? (responseData?.error || responseData?.message || JSON.stringify(responseData))
-      : String(responseData || "");
-    throw new Error(`[AppServer-DevBridge] status: ${response.status}, message: ${errorMessage}`);
+    throw createAppServerError(label, response, responseData);
   }
 
-  if (responseData && typeof responseData === "object" && Object.prototype.hasOwnProperty.call(responseData, "success")) {
+  if (responseData && typeof responseData === "object" && hasOwn(responseData, "success")) {
     if (responseData.success) {
       return responseData.data;
     }
-    throw new Error(responseData.error || "AppServer invocation failed in dev bridge");
+
+    const error = new Error(responseData.error || responseData.message || `${label} invocation failed`);
+    error.response = response;
+    error.responseData = responseData;
+    error.statusCode = response.status;
+    error.code = responseData.code;
+    throw error;
   }
 
   return responseData;
 };
 
+const toBlob = (rawValue, contentType = "application/octet-stream") => {
+  if (isBlobLike(rawValue)) {
+    return rawValue;
+  }
+
+  if (isBufferLike(rawValue)) {
+    return new Blob([rawValue], { type: contentType });
+  }
+
+  if (rawValue instanceof ArrayBuffer) {
+    return new Blob([rawValue], { type: contentType });
+  }
+
+  if (ArrayBuffer.isView(rawValue)) {
+    return new Blob([rawValue], { type: contentType });
+  }
+
+  throw new Error("Unsupported binary payload for appServer file upload");
+};
+
+const normalizeSingleFileInput = (value, defaultFieldName) => {
+  if (!value) {
+    return [];
+  }
+
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => normalizeSingleFileInput(item, defaultFieldName));
+  }
+
+  if (isFileLike(value) || isBlobLike(value) || isBinaryLike(value)) {
+    return [{
+      fieldName: defaultFieldName,
+      rawValue: value,
+      fileName: value?.name || "file",
+      contentType: value?.type || "application/octet-stream",
+    }];
+  }
+
+  if (isPlainObject(value) && hasOwn(value, "file")) {
+    const rawValue = value.file;
+    return [{
+      fieldName: value.fieldName || defaultFieldName,
+      rawValue,
+      fileName: value.fileName || value.name || rawValue?.name || "file",
+      contentType: value.contentType || value.mimeType || value.type || rawValue?.type || "application/octet-stream",
+    }];
+  }
+
+  if (isPlainObject(value) && isBinaryLike(value.buffer)) {
+    return [{
+      fieldName: value.fieldName || defaultFieldName,
+      rawValue: value.buffer,
+      fileName: value.fileName || value.name || "file",
+      contentType: value.contentType || value.mimeType || value.type || "application/octet-stream",
+    }];
+  }
+
+  if (
+    isPlainObject(value) &&
+    typeof value.data === "string" &&
+    typeof value.encoding === "string" &&
+    value.encoding.toLowerCase() === "base64"
+  ) {
+    return [{
+      fieldName: value.fieldName || defaultFieldName,
+      rawValue: decodeBase64Binary(value.data),
+      fileName: value.fileName || value.name || "file",
+      contentType: value.contentType || value.mimeType || value.type || "application/octet-stream",
+    }];
+  }
+
+  if (isPlainObject(value) && isBlobLike(value.blob)) {
+    return [{
+      fieldName: value.fieldName || defaultFieldName,
+      rawValue: value.blob,
+      fileName: value.fileName || value.name || value.blob?.name || "file",
+      contentType: value.contentType || value.mimeType || value.type || value.blob?.type || "application/octet-stream",
+    }];
+  }
+
+  throw new Error(`Unsupported appServer file input for field "${defaultFieldName}"`);
+};
+
+const normalizeAppServerFiles = (files) => {
+  if (!files) {
+    return [];
+  }
+
+  if (Array.isArray(files)) {
+    return files.flatMap((item) => normalizeSingleFileInput(item, item?.fieldName || DEFAULT_FILE_FIELD_NAME));
+  }
+
+  if (isPlainObject(files) && !hasOwn(files, "file") && !hasOwn(files, "buffer") && !hasOwn(files, "data")) {
+    return Object.entries(files).flatMap(([fieldName, value]) => normalizeSingleFileInput(value, fieldName));
+  }
+
+  return normalizeSingleFileInput(files, DEFAULT_FILE_FIELD_NAME);
+};
+
+const buildRemoteRequestInit = function(payload, options = {}, extraHeaders = {}) {
+  const requestPayload = typeof payload === "undefined" ? {} : payload;
+  const normalizedFiles = normalizeAppServerFiles(options.files);
+  const headers = { ...extraHeaders };
+  const authorizationHeader = getAccessTokenHeaderValue.call(this);
+  if (authorizationHeader && !headers.Authorization && !headers.authorization) {
+    headers.Authorization = authorizationHeader;
+  }
+
+  if (normalizedFiles.length === 0) {
+    headers["Content-Type"] = "application/json";
+    return {
+      method: "POST",
+      headers,
+      body: JSON.stringify(requestPayload),
+      signal: options.signal,
+    };
+  }
+
+  delete headers["Content-Type"];
+  delete headers["content-type"];
+
+  const formData = new FormData();
+  formData.append(APPSERVER_REQUEST_DATA_FIELD, JSON.stringify(requestPayload));
+  for (const fileDescriptor of normalizedFiles) {
+    const fileValue = isFileLike(fileDescriptor.rawValue)
+      ? fileDescriptor.rawValue
+      : toBlob(fileDescriptor.rawValue, fileDescriptor.contentType);
+    formData.append(fileDescriptor.fieldName, fileValue, fileDescriptor.fileName || "file");
+  }
+
+  return {
+    method: "POST",
+    headers,
+    body: formData,
+    signal: options.signal,
+  };
+};
+
+const invokeByPlatformProxy = async function(appServerAPIName, payload, options = {}) {
+  const endpoint = `/apps/invokeAppServerAPI?appId=${encodeURIComponent(this.appId)}&apiName=${encodeURIComponent(appServerAPIName)}`;
+  const response = await fetch(`${this.config.apiBaseUrl}${endpoint}`, buildRemoteRequestInit.call(this, payload, options));
+  return await unwrapAppServerResponse(response, "[AppServer-PlatformProxy]");
+};
+
+const invokeByPreviewProxyOnce = async function(appServerAPIName, payload, options = {}, previewToken) {
+  const endpoint = `/appserver-preview/invokeAppServerAPI?appId=${encodeURIComponent(this.appId)}&apiName=${encodeURIComponent(appServerAPIName)}`;
+  const response = await fetch(
+    endpoint,
+    buildRemoteRequestInit.call(this, payload, options, {
+      [PREVIEW_TOKEN_HEADER]: previewToken,
+    })
+  );
+
+  return await unwrapAppServerResponse(response, "[AppServer-DevBridge]");
+};
+
+const invokeByPreviewProxy = async function(appServerAPIName, payload, options = {}) {
+  let previewToken = await getPreviewSessionToken.call(this);
+  try {
+    return await invokeByPreviewProxyOnce.call(this, appServerAPIName, payload, options, previewToken);
+  } catch (error) {
+    if (!isInvalidPreviewTokenError(error)) {
+      throw error;
+    }
+
+    clearPreviewSessionToken(this.appId);
+    previewToken = await getPreviewSessionToken.call(this, { forceRefresh: true });
+    return await invokeByPreviewProxyOnce.call(this, appServerAPIName, payload, options, previewToken);
+  }
+};
+
+const invokeByCrossAppDirect = async function(appServerAPIName, payload, options = {}) {
+  const endpoint = `${this.config.appServerBaseUrl}/invokeAppServerAPI?apiName=${encodeURIComponent(appServerAPIName)}`;
+  const requestInit = buildRemoteRequestInit.call(this, payload, options, {
+    "X-API-Key": this.config.appServerApiKey,
+  });
+  const response = await fetch(endpoint, requestInit);
+  return await unwrapAppServerResponse(response, "[AppServer-CrossApp]");
+};
+
 /**
  * 调用一个 App Server API。
- * - 在开发态浏览器中：预览页（/app-run/*）走本地预览代理，其余开发页直接走平台转发。
- * - 在生产态浏览器中：统一走平台转发（/apps/invokeAppServerAPI）。
- * - 在后端云函数中：本地执行 (由云函数入口调用)。
- * - 跨应用调用：仅后端场景可直连目标 AppServer（需 appServerBaseUrl + appServerApiKey）。
- * @param {string} appServerAPIName - 要调用的服务名称。
- * @param {Object} payload - 传递给服务的负载数据。
- * @returns {Promise<any>} 服务处理后的结果。
+ * - 开发态浏览器：预览页走 CLI preview bridge，其他页面走平台转发。
+ * - 生产态浏览器：统一走平台转发。
+ * - 后端跨应用：允许使用 appServerBaseUrl + appServerApiKey 直连目标 AppServer。
+ * - 后端当前应用：从本地注册表执行。
+ *
+ * @param {string} appServerAPIName
+ * @param {any} payload
+ * @param {Object} options
+ * @param {Object|Array} [options.files] 仅在存在文件时传入，SDK 会自动切换到 multipart/form-data，并将 JSON 放到 requestData 字段。
  */
-const invokeAppServerAPI = async function(appServerAPIName, payload) {
-  console.log(`[AppServer][${this.appId}] Invoking "${appServerAPIName}" with payload:`, payload);
-  // 场景零：跨应用调用，在源应用的 appserver 云函数调用目标应用的 appserver 云函数
+const invokeAppServerAPI = async function(appServerAPIName, payload, options = {}) {
+  if (!appServerAPIName || typeof appServerAPIName !== "string") {
+    throw new Error("appServerAPIName is required");
+  }
+
   if (isBackend && this.config.appServerBaseUrl && this.config.appServerApiKey) {
-    const endpoint = `${this.config.appServerBaseUrl}/invokeAppServerAPI?apiName=${appServerAPIName}`;
-    try {
-      const response = await fetch(endpoint, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'X-API-Key': this.config.appServerApiKey,
-        },
-        body: JSON.stringify(payload),
-      });
-
-      console.log(`App server request id: ${response.headers.get('x-scf-request-id')}`)
-
-      const res = await response.json();
-      if (!response.ok) {
-        // 抛出网络层面的错误
-        throw new Error(`[AppServer-CrossApp] error! status: ${response.status}, statusText: ${response.statusText}, requestId: ${response.headers.get('x-scf-request-id')}, body: ${JSON.stringify(res)}`);
-      }
-
-      if (res.success) {
-        return res.data;
-      }
-      // 抛出业务层面的错误
-      throw new Error(res.error || 'Cross-application server invocation failed at the business level.');
-    } catch (error) {
-      console.error(`[AppServer-CrossApp] Failed to invoke "${appServerAPIName}" via cross-app call:`, error);
-      throw error;
-    }
+    return await invokeByCrossAppDirect.call(this, appServerAPIName, payload, options);
   }
 
-  // 场景一：开发环境浏览器
   if (isDevelopmentBrowser) {
     if (isBrowserPreviewRuntime()) {
-      return await invokeByPreviewProxy.call(this, appServerAPIName, payload);
+      return await invokeByPreviewProxy.call(this, appServerAPIName, payload, options);
     }
-    return await invokeByPlatformProxy.call(this, appServerAPIName, payload);
+    return await invokeByPlatformProxy.call(this, appServerAPIName, payload, options);
   }
 
-  // 场景二：生产环境的浏览器，统一走平台转发
   if (isProductionBrowser) {
-    try {
-      return await invokeByPlatformProxy.call(this, appServerAPIName, payload);
-    } catch (error) {
-      console.error(`[AppServer-Prod] Failed to invoke "${appServerAPIName}" via appsClient:`, error);
-      throw error;
-    }
+    return await invokeByPlatformProxy.call(this, appServerAPIName, payload, options);
   }
 
-  // 场景三：后端云函数环境，从本地 Map 执行
   const appServerAPIHandler = appServerAPIMap.get(appServerAPIName);
   if (!appServerAPIHandler) {
     throw new Error(`[AppServer-${env}] AppServer "${appServerAPIName}" not found or not registered.`);
   }
-  return await appServerAPIHandler(payload, { appsClient: this });
+
+  return await appServerAPIHandler(payload, {
+    appsClient: this,
+    ...options,
+  });
 };
 
 export const appsClientAppServerMethods = {

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

@@ -1,14 +1,27 @@
-import { isBrowser } from "../../../utils/index.js";
-
 export const appsClientDebugMethods = {
   // ==================== 便捷方法 ====================
 
   updateConfig(newConfig) {
-    this.config = { ...this.config, ...newConfig };
+    const nextConfig = { ...newConfig };
+    const hasAccessToken = Object.prototype.hasOwnProperty.call(nextConfig, "accessToken");
+
+    if (hasAccessToken && typeof this.setAccessToken === "function") {
+      this.setAccessToken(nextConfig.accessToken, {
+        persist: false,
+        syncConfig: false,
+      });
+    }
+
+    this.config = { ...this.config, ...nextConfig };
+    if (hasAccessToken) {
+      this.config.accessToken = this.accessToken;
+    }
   },
 
   getConfig() {
-    return { ...this.config };
+    const config = { ...this.config };
+    delete config.accessToken;
+    return config;
   },
 
   // ==================== 调试和监控 ====================
@@ -20,9 +33,7 @@ export const appsClientDebugMethods = {
         config: this.getConfig(),
         clientType: "AppsClient (Multi-Model with AI)",
       };
-      if (isBrowser) {
-        status.hasAccessToken = !!localStorage.getItem("tacoreai_apps_access_token");
-      }
+      status.hasAccessToken = !!this.getAccessToken();
       return status;
     } catch (error) {
       console.error("获取AI应用客户端状态失败:", error);
@@ -32,9 +43,7 @@ export const appsClientDebugMethods = {
         error: error.message,
         clientType: "AppsClient (Multi-Model with AI)",
       };
-      if (isBrowser) {
-        status.hasAccessToken = !!localStorage.getItem("tacoreai_apps_access_token");
-      }
+      status.hasAccessToken = !!this.getAccessToken();
       return status;
     }
   },

package/database/core/apps/AppsClient.js

@@ -31,6 +31,9 @@ class AppsClient extends BaseAppsClient {
   static getInstance(tagetAppId, config = {}) {
     const instance = instanceMap.get(tagetAppId);
     if (instance) {
+      if (config && Object.keys(config).length > 0) {
+        instance.updateConfig(config);
+      }
       return instance;
     }
     return new AppsClient(tagetAppId, config);
@@ -176,10 +179,7 @@ class AppsClient extends BaseAppsClient {
    * 重写基类方法，提供 Token
    */
   _getAccessToken() {
-    if (isBrowser) {
-      return localStorage.getItem("tacoreai_apps_access_token");
-    }
-    return null;
+    return this.getAccessToken({ fallbackToStorage: isBrowser });
   }
 
   /**

package/database/core/apps/BaseAppsClient.js

@@ -1,5 +1,49 @@
 import { getAppsApiBaseUrl, isBrowser, isBackend, getGlobalOptions } from "../../../utils/index.js";
 
+const ACCESS_TOKEN_STORAGE_KEY = "tacoreai_apps_access_token";
+
+const normalizeAccessToken = (value) => {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  return trimmed.replace(/^Bearer\s+/i, "").trim() || null;
+};
+
+const readPersistedAccessToken = () => {
+  if (!isBrowser) {
+    return null;
+  }
+
+  try {
+    return normalizeAccessToken(localStorage.getItem(ACCESS_TOKEN_STORAGE_KEY));
+  } catch (error) {
+    console.error("[BaseAppsClient] Failed to read access token from localStorage:", error);
+    return null;
+  }
+};
+
+const writePersistedAccessToken = (token) => {
+  if (!isBrowser) {
+    return;
+  }
+
+  try {
+    if (token) {
+      localStorage.setItem(ACCESS_TOKEN_STORAGE_KEY, token);
+      return;
+    }
+    localStorage.removeItem(ACCESS_TOKEN_STORAGE_KEY);
+  } catch (error) {
+    console.error("[BaseAppsClient] Failed to persist access token:", error);
+  }
+};
+
 /**
  * Apps SDK 基类
  * 封装通用的配置管理、Header构建、HTTP请求逻辑
@@ -22,6 +66,14 @@ export class BaseAppsClient {
       ...defaultConfig,
       ...config,
     };
+    this.accessToken = null;
+
+    if (Object.prototype.hasOwnProperty.call(this.config, "accessToken")) {
+      this.setAccessToken(this.config.accessToken, {
+        persist: false,
+        syncConfig: true,
+      });
+    }
 
     // 后端环境通用逻辑：尝试从环境变量加载 API Key
     if (isBackend && !this.config.tacoreServerInteropAppServerApiKey) {
@@ -73,7 +125,7 @@ export class BaseAppsClient {
    * @returns {string|null}
    */
   _getAccessToken() {
-    return null;
+    return this.getAccessToken();
   }
 
   /**
@@ -119,15 +171,13 @@ export class BaseAppsClient {
       headers["x-app-id"] = this.appId;
     }
 
-    if (isBrowser) {
-      const token = this._getAccessToken();
-      if (token) {
-        headers["Authorization"] = `Bearer ${token}`;
-      }
-    } else { // isBackend
-      if (this.config.tacoreServerInteropAppServerApiKey) {
-        headers["x-tacore-server-interop-app-server-api-key"] = this.config.tacoreServerInteropAppServerApiKey;
-      }
+    const token = this._getAccessToken();
+    if (token) {
+      headers["Authorization"] = `Bearer ${token}`;
+    }
+
+    if (isBackend && this.config.tacoreServerInteropAppServerApiKey) {
+      headers["x-tacore-server-interop-app-server-api-key"] = this.config.tacoreServerInteropAppServerApiKey;
     }
 
     return headers;
@@ -204,13 +254,71 @@ export class BaseAppsClient {
    * 更新配置
    */
   updateConfig(newConfig) {
-    this.config = { ...this.config, ...newConfig };
+    const nextConfig = { ...newConfig };
+    const hasAccessToken = Object.prototype.hasOwnProperty.call(nextConfig, "accessToken");
+
+    if (hasAccessToken) {
+      this.setAccessToken(nextConfig.accessToken, {
+        persist: false,
+        syncConfig: false,
+      });
+    }
+
+    this.config = { ...this.config, ...nextConfig };
+    if (hasAccessToken) {
+      this.config.accessToken = this.accessToken;
+    }
   }
 
   /**
    * 获取当前配置
    */
   getConfig() {
-    return { ...this.config };
+    const config = { ...this.config };
+    delete config.accessToken;
+    return config;
+  }
+
+  setAccessToken(token, options = {}) {
+    const { persist = isBrowser, syncConfig = true } = options;
+    const normalizedToken = normalizeAccessToken(token);
+
+    this.accessToken = normalizedToken;
+
+    if (syncConfig) {
+      this.config.accessToken = normalizedToken;
+    }
+
+    if (persist) {
+      writePersistedAccessToken(normalizedToken);
+    }
+
+    return normalizedToken;
+  }
+
+  getAccessToken(options = {}) {
+    const { fallbackToStorage = isBrowser } = options;
+    if (this.accessToken) {
+      return this.accessToken;
+    }
+
+    if (!fallbackToStorage) {
+      return null;
+    }
+
+    return readPersistedAccessToken();
+  }
+
+  clearAccessToken(options = {}) {
+    const { persist = isBrowser, syncConfig = true } = options;
+    this.accessToken = null;
+
+    if (syncConfig) {
+      this.config.accessToken = null;
+    }
+
+    if (persist) {
+      writePersistedAccessToken(null);
+    }
   }
 }

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.8.0",
+  "version": "1.9.0",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -9,7 +9,8 @@
   },
   "exports": {
     ".": "./index.js",
-    "./utils": "./utils/index.js"
+    "./utils": "./utils/index.js",
+    "./app-server-runtime": "./database/core/apps/AppServerRuntime.js"
   },
   "scripts": {
     "release": "npm version minor && git commit -am \"web-sdk update version\" && npm publish"