@tacoreai/web-sdk 1.24.0 → 1.26.0

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

@@ -1,4 +1,5 @@
 import { AppsClient } from "./AppsClient.js";
+import { AppsAuthManager } from "./AppsAuthManager.js";
 
 export const APPSERVER_REQUEST_DATA_FIELD = "requestData";
 
@@ -30,6 +31,43 @@ const getRequestSource = (isPlatformProxyRequest, isSchedulerRequest) => {
   return isPreviewMode() ? "preview-direct" : "external-direct";
 };
 
+const getAppServerServiceToken = (env) => (
+  env.tacoreAppServerServiceToken ||
+  process.env.TACORE_APP_SERVER_SERVICE_TOKEN ||
+  null
+);
+
+const getTacoreServerInteropAppServerApiKey = (env) => (
+  env.tacoreServerInteropAppServerApiKey ||
+  process.env.TACORE_SERVER_INTEROP_APP_SERVER_API_KEY ||
+  null
+);
+
+const hasAppServerServiceAuthCredential = (env) => (
+  Boolean(getTacoreServerInteropAppServerApiKey(env)) &&
+  Boolean(getAppServerServiceToken(env))
+);
+
+const shouldUseAppServerMachineAuth = ({
+  env,
+  isPlatformProxyRequest,
+  isSchedulerRequest,
+  isExternalApiKeyRequest,
+  accessToken,
+  appServerApiKey,
+  previewAppServerApiKey,
+}) => {
+  if (isExternalApiKeyRequest && accessToken) {
+    return false;
+  }
+
+  if (isPlatformProxyRequest || isSchedulerRequest) {
+    return hasAppServerServiceAuthCredential(env);
+  }
+
+  return Boolean(appServerApiKey) || Boolean(previewAppServerApiKey);
+};
+
 const createRequestScopedAppsClient = (env, options = {}) => {
   const {
     accessToken = null,
@@ -63,6 +101,35 @@ const createRequestScopedAppsClient = (env, options = {}) => {
   return new AppsClient(clientAppId, config);
 };
 
+const resolveCallerUser = async (env, accessToken) => {
+  if (!accessToken) {
+    return null;
+  }
+
+  try {
+    const authManager = new AppsAuthManager(env.dataSourceId || env.appId, {
+      ...env,
+      accessToken,
+    });
+    return await authManager.getCurrentUser();
+  } catch (error) {
+    console.warn("[AppServer] Failed to resolve caller user:", error?.message || error);
+    return null;
+  }
+};
+
+const createCallerAppsClient = (env, accessToken) => {
+  if (!accessToken) {
+    return null;
+  }
+
+  return createRequestScopedAppsClient(env, {
+    accessToken,
+    clientAppId: env.dataSourceId || env.appId,
+    enableAppServerServiceAuth: false,
+  });
+};
+
 const isPreviewApiKeyShapeValid = (apiKey) => {
   if (typeof apiKey !== "string") return false;
   const value = apiKey.trim();
@@ -360,12 +427,23 @@ export const createAppServerRuntime = async (options = {}) => {
         willForwardPreviewAppServerApiKey: Boolean(previewAppServerApiKey),
       });
 
+      const useAppServerMachineAuth = shouldUseAppServerMachineAuth({
+        env,
+        isPlatformProxyRequest,
+        isSchedulerRequest,
+        isExternalApiKeyRequest,
+        accessToken: requestAccessToken,
+        appServerApiKey,
+        previewAppServerApiKey,
+      });
       const appsClient = createRequestScopedAppsClient(env, {
-        accessToken: requestAccessToken || null,
-        appServerApiKey: requestAccessToken ? null : appServerApiKey,
+        accessToken: useAppServerMachineAuth ? null : requestAccessToken || null,
+        appServerApiKey: useAppServerMachineAuth ? appServerApiKey : requestAccessToken ? null : appServerApiKey,
         previewAppServerApiKey,
-        enableAppServerServiceAuth: Boolean((isSchedulerRequest || isExternalApiKeyRequest) && !requestAccessToken),
+        enableAppServerServiceAuth: useAppServerMachineAuth,
       });
+      const callerUser = await resolveCallerUser(env, requestAccessToken);
+      const callerAppsClient = createCallerAppsClient(env, requestAccessToken);
       console.log(`[AppServer Debug] scoped AppsClient api="${apiName}"`, {
         hasAccessToken: Boolean(appsClient.getAccessToken()),
         hasAppServerApiKey: Boolean(appsClient.config.appServerApiKey),
@@ -373,13 +451,19 @@ export const createAppServerRuntime = async (options = {}) => {
         hasInteropKey: Boolean(appsClient.config.tacoreServerInteropAppServerApiKey),
         serviceAuthEnabled: appsClient.config.enableAppServerServiceAuth === true,
         hasServiceToken: Boolean(appsClient.config.tacoreAppServerServiceToken),
+        usesAppServerMachineAuth: useAppServerMachineAuth,
+        hasCallerUser: Boolean(callerUser?.id),
+        hasCallerAppsClient: Boolean(callerAppsClient),
       });
       const data = await appsClient.invokeAppServerAPI(apiName, payload, {
         appsClient,
+        callerAppsClient,
         req,
         res,
         files: normalizeUploadedFiles(req.files || []),
         requestSource,
+        callerAccessToken: requestAccessToken || null,
+        callerUser,
       });
 
       if (data && typeof data === "object" && !Buffer.isBuffer(data)) {

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.26.0",
   "type": "module",
   "publishConfig": {
     "access": "public",