@tacoreai/web-sdk 1.24.0 → 1.24.1-beta.3

package/README.md

@@ -17,6 +17,45 @@ npm install @tacoreai/web-sdk
 ### AppsClient (Data & AI)
 示例略（保持原有章节）
 
+### TacoreActionSDK (Headless Capability)
+
+组织通用 Agent、外部 Agent 或 CLI 壳应通过 `TacoreActionSDK` 调用云应用暴露的 `/.tacore/capabilities.json`，而不是依赖应用 UI、DOM、按钮或页面路径。应用 GUI 只是 capability 的一个使用者，必须和 SDK 执行共享同一 Action Registry / service 层。
+
+```js
+import { TacoreActionSDK } from '@tacoreai/web-sdk'
+
+const actionSdk = new TacoreActionSDK({
+  accessToken: 'PLATFORM_ACCESS_TOKEN',
+  organizationId: 'org_xxx',
+  appId: 'crm_app_xxx',
+})
+
+const manifest = await actionSdk.listCapabilities()
+const schema = await actionSdk.getCapabilitySchema('crm.lead.create')
+const draft = await actionSdk.draft('crm.lead.create', {
+  name: 'Acme',
+  phone: '13800000000',
+})
+
+// 写入类能力应先展示 preview/dry-run，再经用户确认后执行。
+await actionSdk.execute('crm.lead.create', {
+  draftId: draft.draftId,
+  action: {
+    name: 'crm.lead.create',
+    idempotencyKey: 'lead:13800000000',
+    steps: [
+      {
+        op: 'create',
+        modelName: 'lead',
+        data: { name: 'Acme', phone: '13800000000' },
+      },
+    ],
+  },
+})
+```
+
+SDK 封装平台 `/plat/agent/capabilities` 的发现、dry-run 与 execute 请求；核心执行仍落到 manifest 声明的 `actions/run` 事务契约，CLI 只是同一接口的一层命令行包装。
+
 ### AppsClient (Events)
 
 应用自定义埋点应使用事件日志接口，不要把高频事件写入通用数据模型。

package/TacoreActionSDK.js

@@ -0,0 +1,206 @@
+import { getAppsApiBaseUrl, getGlobalOptions, isBrowser } from "./utils/index.js";
+
+const PLATFORM_ACCESS_TOKEN_STORAGE_KEY = "tacoreai_access_token";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeAccessToken(value) {
+  const token = normalizeString(value);
+  return token.replace(/^Bearer\s+/i, "").trim();
+}
+
+function readPlatformAccessToken() {
+  if (!isBrowser) {
+    return "";
+  }
+  try {
+    return normalizeAccessToken(localStorage.getItem(PLATFORM_ACCESS_TOKEN_STORAGE_KEY));
+  } catch (error) {
+    console.error("[TacoreActionSDK] Failed to read platform access token:", error);
+    return "";
+  }
+}
+
+function buildQuery(params = {}) {
+  const searchParams = new URLSearchParams();
+  Object.entries(params).forEach(([key, value]) => {
+    if (value === undefined || value === null || value === "") {
+      return;
+    }
+    searchParams.append(key, typeof value === "object" ? JSON.stringify(value) : String(value));
+  });
+  const query = searchParams.toString();
+  return query ? `?${query}` : "";
+}
+
+function resolveDraftCapabilityId(draft) {
+  return normalizeString(draft?.capabilityId || draft?.capability?.capabilityId);
+}
+
+export class TacoreActionSDK {
+  constructor(config = {}) {
+    const globalOptions = getGlobalOptions();
+    this.config = {
+      ...globalOptions.clientDefaultConfig,
+      apiBaseUrl: getAppsApiBaseUrl(),
+      organizationId: "",
+      projectId: "",
+      appId: "",
+      ...config,
+    };
+    this.accessToken = normalizeAccessToken(config.accessToken || "");
+  }
+
+  updateConfig(nextConfig = {}) {
+    if (Object.prototype.hasOwnProperty.call(nextConfig, "accessToken")) {
+      this.setAccessToken(nextConfig.accessToken);
+    }
+    this.config = {
+      ...this.config,
+      ...nextConfig,
+      accessToken: this.accessToken,
+    };
+  }
+
+  setAccessToken(token) {
+    this.accessToken = normalizeAccessToken(token);
+    this.config.accessToken = this.accessToken;
+    return this.accessToken;
+  }
+
+  getAccessToken() {
+    return this.accessToken || readPlatformAccessToken();
+  }
+
+  getHeaders(options = {}) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...(options.headers || {}),
+    };
+    const organizationId = normalizeString(options.organizationId || this.config.organizationId);
+    const projectId = normalizeString(options.projectId || this.config.projectId);
+    const appId = normalizeString(options.appId || this.config.appId);
+    const token = this.getAccessToken();
+
+    if (organizationId) {
+      headers["x-org-id"] = organizationId;
+    }
+    if (projectId) {
+      headers["x-project-id"] = projectId;
+    }
+    if (appId) {
+      headers["x-app-id"] = appId;
+    }
+    if (token) {
+      headers.Authorization = `Bearer ${token}`;
+    }
+    return headers;
+  }
+
+  async request(endpoint, options = {}) {
+    const response = await fetch(`${this.config.apiBaseUrl}${endpoint}`, {
+      ...options,
+      headers: this.getHeaders(options),
+    });
+    const result = await response.json().catch(() => ({}));
+    if (!response.ok || result?.success === false) {
+      const error = new Error(result?.message || result?.error || `HTTP ${response.status}: ${response.statusText}`);
+      error.status = response.status;
+      error.code = result?.code;
+      error.details = result?.details;
+      error.responseData = result;
+      throw error;
+    }
+    return result?.data ?? result;
+  }
+
+  get(endpoint, params = {}, options = {}) {
+    return this.request(`${endpoint}${buildQuery(params)}`, {
+      ...options,
+      method: "GET",
+    });
+  }
+
+  post(endpoint, body = {}, options = {}) {
+    return this.request(endpoint, {
+      ...options,
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+  }
+
+  listCapabilities(options = {}) {
+    const appId = normalizeString(options.appId || this.config.appId);
+    return this.get("/plat/agent/capabilities", { appId }, { appId, ...options });
+  }
+
+  getCapabilitySchema(capabilityId, options = {}) {
+    const appId = normalizeString(options.appId || this.config.appId);
+    const normalizedCapabilityId = encodeURIComponent(normalizeString(capabilityId));
+    return this.get(`/plat/agent/capabilities/${normalizedCapabilityId}`, { appId }, { appId, ...options });
+  }
+
+  dryRun(capabilityId, options = {}) {
+    const appId = normalizeString(options.appId || this.config.appId);
+    return this.post("/plat/agent/capabilities/dry-run", {
+      appId,
+      capabilityId: normalizeString(capabilityId),
+      input: options.input || {},
+      action: options.action || null,
+      options: options.options || {},
+    }, { appId, ...options });
+  }
+
+  draft(capabilityId, inputOrOptions = {}, maybeOptions = {}) {
+    const isOptionsObject = inputOrOptions && typeof inputOrOptions === "object" && (
+      Object.prototype.hasOwnProperty.call(inputOrOptions, "input") ||
+      Object.prototype.hasOwnProperty.call(inputOrOptions, "appId") ||
+      Object.prototype.hasOwnProperty.call(inputOrOptions, "options")
+    );
+    const options = isOptionsObject
+      ? inputOrOptions
+      : {
+          ...maybeOptions,
+          input: inputOrOptions || {},
+        };
+    return this.dryRun(capabilityId, options);
+  }
+
+  preview(draftOrCapabilityId, options = {}) {
+    if (draftOrCapabilityId && typeof draftOrCapabilityId === "object") {
+      if (draftOrCapabilityId.dryRun === true) {
+        return Promise.resolve(draftOrCapabilityId);
+      }
+      return this.dryRun(resolveDraftCapabilityId(draftOrCapabilityId), {
+        ...draftOrCapabilityId,
+        ...options,
+      });
+    }
+    return this.dryRun(draftOrCapabilityId, options);
+  }
+
+  execute(draftOrCapabilityId, options = {}) {
+    const draft = draftOrCapabilityId && typeof draftOrCapabilityId === "object" ? draftOrCapabilityId : null;
+    const capabilityId = draft ? resolveDraftCapabilityId(draft) : normalizeString(draftOrCapabilityId);
+    const appId = normalizeString(options.appId || draft?.appId || this.config.appId);
+    return this.post("/plat/agent/capabilities/execute", {
+      appId,
+      capabilityId,
+      draftId: normalizeString(options.draftId || draft?.draftId),
+      input: options.input || draft?.input || {},
+      action: options.action || draft?.action || null,
+      options: options.options || {},
+    }, { appId, ...options });
+  }
+
+  runTransactionAction({ appId, capabilityId, input = {}, action, options = {} } = {}) {
+    return this.execute(capabilityId, {
+      appId,
+      input,
+      action,
+      options,
+    });
+  }
+}

package/database/core/apps/AppServerRuntime.js

@@ -7,6 +7,11 @@ const DEFAULT_FILE_SIZE_LIMIT = 100 * 1024 * 1024;
 const DEFAULT_MAX_FILES = 20;
 
 const isPreviewMode = () => process.env.TACORE_APPSERVER_PREVIEW_MODE === "true";
+const isLocalDeploymentMode = (env = {}) =>
+  env.localDeployment === true ||
+  env.localAppServer === true ||
+  env.appServerDeploymentMode === "local" ||
+  process.env.TACORE_APPSERVER_LOCAL_DEPLOYMENT_MODE === "true";
 
 const isValidInternalToken = (incomingValue, expectedValue) => {
   return Boolean(expectedValue) && Boolean(incomingValue) && incomingValue === expectedValue;
@@ -78,6 +83,15 @@ const validateExternalApiKey = async (appsClient, appId, apiKey) => {
   return Boolean(result?.success && result?.data?.valid);
 };
 
+const validateLocalDeploymentAccessToken = async (env, accessToken) => {
+  const authClient = createRequestScopedAppsClient(env, {
+    accessToken,
+    clientAppId: env.appId,
+  });
+  const result = await authClient.getIamContext({});
+  return Boolean(result?.success);
+};
+
 const getPreviewGuidePayload = (req) => {
   const baseUrl = `${req.protocol}://${req.get("host")}`;
   const invokeUrl = `${baseUrl}/invokeAppServerAPI?apiName=YOUR_API_NAME`;
@@ -300,51 +314,71 @@ export const createAppServerRuntime = async (options = {}) => {
 
     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 {
-        const authClient = createRequestScopedAppsClient(env, {
-          accessToken: requestAccessToken || null,
-          clientAppId: env.appId,
-        });
-        isValidApiKey = await validateExternalApiKey(authClient, 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",
-        });
-      }
-
-      isExternalApiKeyRequest = true;
-      appServerApiKey = requestApiKey;
-
-      if (isPreviewMode() && !requestAccessToken) {
-        previewAppServerApiKey = requestApiKey;
+        if (isLocalDeploymentMode(env) && requestAccessToken) {
+          try {
+            const isValidAccessToken = await validateLocalDeploymentAccessToken(env, requestAccessToken);
+            if (!isValidAccessToken) {
+              return res.status(401).json({
+                success: false,
+                code: "INVALID_ACCESS_TOKEN",
+                error: "Invalid Authorization token",
+              });
+            }
+          } catch (error) {
+            console.error("[AppServer] Failed to validate local deployment access token:", error);
+            return res.status(error.status || 401).json({
+              success: false,
+              code: "ACCESS_TOKEN_VALIDATION_FAILED",
+              error: error.message,
+            });
+          }
+        } else {
+          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",
+          });
+        }
+      } else {
+        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 {
+          const authClient = createRequestScopedAppsClient(env, {
+            accessToken: requestAccessToken || null,
+            clientAppId: env.appId,
+          });
+          isValidApiKey = await validateExternalApiKey(authClient, 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",
+          });
+        }
+
+        isExternalApiKeyRequest = true;
+        appServerApiKey = requestApiKey;
+
+        if (isPreviewMode() && !requestAccessToken) {
+          previewAppServerApiKey = requestApiKey;
+        }
       }
     }
 
@@ -398,7 +432,7 @@ export const createAppServerRuntime = async (options = {}) => {
 
   const listen = (listenOptions = {}) => {
     const port = listenOptions.port || process.env.PORT || 9000;
-    const host = listenOptions.host;
+    const host = listenOptions.host || process.env.HOST || "";
     const callback = typeof listenOptions.onListen === "function"
       ? listenOptions.onListen
       : () => {

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

@@ -121,6 +121,27 @@ const clearPreviewSessionToken = (appId) => {
   previewSessionPromiseCache.delete(appId);
 };
 
+const getBrowserPreviewBridgeBaseUrl = () => {
+  if (typeof window === "undefined") {
+    return "";
+  }
+  return String(window.__TACORE_APPSERVER_PREVIEW_BRIDGE_BASE_URL__ || "").trim().replace(/\/$/, "");
+};
+
+const getBrowserPreviewBridgeInvokeUrl = () => {
+  if (typeof window === "undefined") {
+    return "";
+  }
+  return String(window.__TACORE_APPSERVER_PREVIEW_BRIDGE_URL__ || "").trim();
+};
+
+const appendPreviewInvokeParams = (rawUrl, appId, apiName) => {
+  const url = new URL(rawUrl, typeof window !== "undefined" ? window.location.origin : "http://localhost");
+  url.searchParams.set("appId", appId);
+  url.searchParams.set("apiName", apiName);
+  return url.toString();
+};
+
 const getPreviewSessionToken = async function(options = {}) {
   const { forceRefresh = false } = options;
   const appServerOwnerAppId = getAppServerOwnerAppId.call(this);
@@ -139,7 +160,10 @@ const getPreviewSessionToken = async function(options = {}) {
   }
 
   const requestPromise = (async () => {
-    const endpoint = `/appserver-preview/session?appId=${encodeURIComponent(appServerOwnerAppId)}`;
+    const bridgeBaseUrl = getBrowserPreviewBridgeBaseUrl();
+    const endpoint = bridgeBaseUrl
+      ? `${bridgeBaseUrl}/appserver-preview/session?appId=${encodeURIComponent(appServerOwnerAppId)}`
+      : `/appserver-preview/session?appId=${encodeURIComponent(appServerOwnerAppId)}`;
     const response = await fetch(endpoint, {
       method: "GET",
       headers: {
@@ -404,7 +428,13 @@ const invokeByPlatformProxy = async function(appServerAPIName, payload, options
 
 const invokeByPreviewProxyOnce = async function(appServerAPIName, payload, options = {}, previewToken) {
   const appServerOwnerAppId = getAppServerOwnerAppId.call(this);
-  const endpoint = `/appserver-preview/invokeAppServerAPI?appId=${encodeURIComponent(appServerOwnerAppId)}&apiName=${encodeURIComponent(appServerAPIName)}`;
+  const bridgeInvokeUrl = getBrowserPreviewBridgeInvokeUrl();
+  const bridgeBaseUrl = getBrowserPreviewBridgeBaseUrl();
+  const endpoint = bridgeInvokeUrl
+    ? appendPreviewInvokeParams(bridgeInvokeUrl, appServerOwnerAppId, appServerAPIName)
+    : bridgeBaseUrl
+      ? `${bridgeBaseUrl}/appserver-preview/invokeAppServerAPI?appId=${encodeURIComponent(appServerOwnerAppId)}&apiName=${encodeURIComponent(appServerAPIName)}`
+      : `/appserver-preview/invokeAppServerAPI?appId=${encodeURIComponent(appServerOwnerAppId)}&apiName=${encodeURIComponent(appServerAPIName)}`;
   const response = await fetch(
     endpoint,
     buildRemoteRequestInit.call(this, payload, options, {
@@ -432,17 +462,26 @@ const invokeByPreviewProxy = async function(appServerAPIName, payload, options =
 
 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 extraHeaders = this.config.appServerApiKey
+    ? { "X-API-Key": this.config.appServerApiKey }
+    : {};
+  const requestInit = buildRemoteRequestInit.call(this, payload, options, extraHeaders);
   const response = await fetch(endpoint, requestInit);
   return await unwrapAppServerResponse(response, "[AppServer-CrossApp]");
 };
 
+const canUseBackendDirectAppServer = function() {
+  return Boolean(this.config.appServerBaseUrl && this.config.appServerApiKey);
+};
+
+const canUseProductionBrowserDirectAppServer = function() {
+  return Boolean(this.config.appServerBaseUrl);
+};
+
 /**
  * 调用一个 App Server API。
  * - 开发态浏览器：预览页走 CLI preview bridge，其他页面走平台转发。
- * - 生产态浏览器：统一走平台转发。
+ * - 生产态浏览器：配置了 appServerBaseUrl 时直连，使用当前用户 Authorization 鉴权。
  * - 后端跨应用：允许使用 appServerBaseUrl + appServerApiKey 直连目标 AppServer。
  * - 后端当前应用：从本地注册表执行。
  *
@@ -456,7 +495,10 @@ const invokeAppServerAPI = async function(appServerAPIName, payload, options = {
     throw new Error("appServerAPIName is required");
   }
 
-  if (isBackend && this.config.appServerBaseUrl && this.config.appServerApiKey) {
+  if (
+    (isBackend && canUseBackendDirectAppServer.call(this)) ||
+    (isProductionBrowser && canUseProductionBrowserDirectAppServer.call(this))
+  ) {
     return await invokeByCrossAppDirect.call(this, appServerAPIName, payload, options);
   }
 

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

@@ -7,22 +7,6 @@ export const appsClientIamMethods = {
     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);
   },
@@ -39,22 +23,6 @@ export const appsClientIamMethods = {
     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);
   },

package/database/core/apps/AppsClient.js

@@ -56,6 +56,7 @@ class AppsClient extends BaseAppsClient {
   /**
    * 定义策略适配器映射
    * 将 invoke 的对象参数转换为老方法的位置参数
+   * stone手动: 注意!!! 无需前端特殊逻辑的新方法，仅需直接在后端新增 xxx/yyy 这种接口即可，websdk 不需要发版，应用层直接 client.invoke('xxx/yyy', params) 即可调用；需要前端特殊逻辑适配的方法，才需要在这里新增适配器
    */
   get adapters() {
     return {
@@ -113,18 +114,10 @@ class AppsClient extends BaseAppsClient {
       // === 企业 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),

package/index.js

@@ -4,6 +4,7 @@ import * as utils from "./utils/index.js"
 export { AppsClient } from "./database/core/apps/AppsClient.js"
 export { AppsAuthManager } from "./database/core/apps/AppsAuthManager.js"
 export { AppsPublicClient } from "./database/core/apps/AppsPublicClient.js"
+export { TacoreActionSDK } from "./TacoreActionSDK.js"
 
 // 导出工具函数
 export { utils }

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.24.0",
+  "version": "1.24.1-beta.3",
   "type": "module",
   "publishConfig": {
     "access": "public",