openxiangda 1.0.269 → 1.0.270

package/README.md

@@ -617,6 +617,8 @@ const PublicAccessError = ({ error }: { error: { message?: string } }) => (
 
 App Function 访问第三方凭据时使用 `app_function_secrets_v1`：manifest 顶层只声明 `secretRefs: [{ "name": "dingtalk_org_app_key", "required": true }]`，同时使用 `definitionJson.version="function_v2"`、`runtimeContractVersion="trusted_node_v2"`；源码通过 `await ctx.secrets.get(name)` 解析，并通过 `ctx.utils.http` 访问受控公网 HTTPS（该桥接不会携带平台 Runtime token）。值只能经 `openxiangda secret create|rotate --value-stdin --change <id> --profile <name>` 或隐藏 TTY 输入，禁止进入 Git、manifest、源码、构建产物、plan、日志或异常。带 `secretRefs` 的 Function 必须走 `backend_release_v2`；需要整应用原子发布时先执行 `resource publish function --only <code> --stage-only`，再把返回的真实 `stagedResource` 交给 `release app-finalize --staged-resources-json ...` 完成 `atomic_staged_children_v2`。默认直接激活的 Backend Release 只返回 `activeResource`，不会伪装成 staged；旧平台 capability 不完整时 CLI 会失败关闭，绝不忽略绑定。
 
+外部系统主动调用应用时，在 `src/resources/webhooks/<code>.json` 声明 Inbound Webhook 和固定 `targetFunctionCode`，用 `openxiangda resource validate|plan|publish webhook` 发布。平台返回的 `callbackPath` 是公开回调路径；不要用租户内的 `appType` 自行拼接入口。目标 Function 在顶层 `secretRefs` 声明供应商 Secret，并且必须先基于精确 `input.rawBody` 验签，再访问表单、数据视图、连接器、通知或外部 HTTP；投递是 at-least-once，业务写入还要用 `input.idempotencyKey` 做原子幂等。使用 `openxiangda webhook deliveries|delivery` 查看投递状态和原始请求审计，完整契约见 `openxiangda-skills/references/webhooks.md`。
+
 平台部门和账号管理走 app-scoped organization 能力。只读查询要求目标应用的 `app:organization:read` 或 `app:organization:manage`，创建、更新和密码操作要求 `app:organization:manage`；平台管理员天然可用，普通应用角色需要显式授权。Runtime service principal 不会直接放行，`ctx.organization` 会按真实操作人 / audit actor 校验权限。新接口不提供删除；`account-update` 不能携带 `password`，重置他人密码必须走 `account-reset-password`，当前用户改密用 SDK / `ctx.organization.accounts.changeMyPassword({ oldPassword, newPassword })`。
 
 CLI 写操作必须加 `--force`：

package/lib/cli.js

@@ -299,6 +299,7 @@ async function mainImpl(argv) {
   if (command === 'workflow') return workflow(rest);
   if (command === 'automation') return automation(rest);
   if (command === 'data-view') return dataView(rest);
+  if (command === 'webhook') return webhook(rest);
   if (command === 'scope') return scope(rest);
   if (command === 'route') return route(rest);
   if (command === 'public-access') return publicAccess(rest);
@@ -389,6 +390,7 @@ Usage:
   openxiangda automation diagnose <automationCode|automationId> [--redact] [--json]
   openxiangda automation publish|enable|disable <automationCode|automationId>
   openxiangda data-view list|get|create|update|upsert|delete|status|refresh|query|stats <dataViewCode> [--profile name] [--json]
+  openxiangda webhook list|get|create|update|upsert|disable|deliveries|delivery [webhookCode] [deliveryId] [--json-file file] [--json]
   openxiangda scope dimension-list|dimension-upsert|grant-source-list|grant-source-upsert|policy-list|policy-upsert|sync|explain [code] [--json-file file]
   openxiangda route list|get|create|update|upsert|delete [--json-file file] [--dry-run] [--write-manifest]
   openxiangda public-access list|get|create|update|upsert|delete|ticket-create|session-test|grant-check [--json-file file]
@@ -10357,6 +10359,7 @@ async function workspace(args) {
         connectors: {},
         dataViews: {},
         storageConfigs: {},
+        webhooks: {},
         scopeDimensions: {},
         scopeGrantSources: {},
         dataScopePolicies: {},
@@ -12543,6 +12546,93 @@ async function dataView(args) {
   fail('用法: openxiangda data-view list|get|create|update|upsert|delete|status|refresh|query|stats');
 }
 
+async function webhook(args) {
+  const { subcommand, rest } = parseSubcommandArgs(args);
+  const { flags, positional } = parseArgs(rest);
+  if (wantsSubcommandHelp(subcommand, flags)) {
+    print('用法: openxiangda webhook list|get|create|update|upsert|disable|deliveries|delivery [webhookCode] [deliveryId] [--json-file file] [--json]');
+    return;
+  }
+  const config = loadConfig();
+  const target = getWorkspaceTarget(
+    config,
+    flags.profile || config.currentProfile,
+    flags
+  );
+  const basePath = `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/webhooks`;
+
+  if (['list', 'get', 'create', 'update', 'upsert'].includes(subcommand)) {
+    return directResourceCrud(config, target, {
+      commandName: 'webhook',
+      subcommand,
+      flags,
+      positional,
+      resourceType: 'webhook',
+      basePath,
+      manifestDir: path.join('src', 'resources', 'webhooks'),
+      normalizeBody: normalizeWebhookManifest,
+      codeOf: body => body.code || body.resourceCode,
+      saveState: (code, data) => saveWebhookResource(target, code, data),
+    });
+  }
+
+  if (subcommand === 'disable') {
+    const code = positional[0] || flags.code;
+    if (!code) fail('用法: openxiangda webhook disable <webhookCode>');
+    const body = readDirectJsonBody(flags, 'webhook disable', {
+      optional: true,
+    });
+    if (flags['expected-revision'] !== undefined) {
+      body.expectedRevision = Number(flags['expected-revision']);
+    }
+    const data = await runDirectRequest(
+      config,
+      target,
+      flags,
+      {
+        method: 'POST',
+        path: apiPathWithPostDeleteAction(
+          `${basePath}/${encodeURIComponent(code)}`
+        ),
+        body,
+      },
+      { returnData: true }
+    );
+    if (!flags['dry-run']) saveWebhookResource(target, code, data);
+    return outputDirectResult({ action: 'disable', data }, flags);
+  }
+
+  if (subcommand === 'deliveries') {
+    const code = positional[0] || flags.code;
+    if (!code) fail('用法: openxiangda webhook deliveries <webhookCode>');
+    return runDirectRequest(config, target, flags, {
+      method: 'GET',
+      path: apiPathWithQuery(
+        `${basePath}/${encodeURIComponent(code)}/deliveries`,
+        {
+          page: flags.page,
+          pageSize: flags['page-size'] || flags.limit,
+          status: flags.status,
+        }
+      ),
+    });
+  }
+
+  if (subcommand === 'delivery') {
+    const code = positional[0] || flags.code;
+    const deliveryId = positional[1] || flags['delivery-id'];
+    if (!code || !deliveryId) {
+      fail('用法: openxiangda webhook delivery <webhookCode> <deliveryId>');
+    }
+    return runDirectRequest(config, target, flags, {
+      method: 'GET',
+      path: `${basePath}/${encodeURIComponent(code)}/deliveries/${encodeURIComponent(deliveryId)}`,
+    });
+  }
+
+  fail('用法: openxiangda webhook list|get|create|update|upsert|disable|deliveries|delivery');
+}
+
 async function scope(args) {
   const { subcommand, rest } = parseSubcommandArgs(args);
   const { flags, positional } = parseArgs(rest);
@@ -17097,6 +17187,7 @@ async function commands(args) {
       'workflow compile|list|create|bind|pull|publish|delete|validate',
       'automation list|create|bind|pull|publish|unpublish|enable|disable|delete|validate|cron-validate',
       'data-view list|get|create|update|upsert|delete|status|refresh|query|stats',
+      'webhook list|get|create|update|upsert|disable|deliveries|delivery',
       'route list|get|create|update|upsert|delete',
       'public-access list|get|create|update|upsert|delete|ticket-create|session-test|grant-check',
       'auth-config list|get|create|update|upsert|delete|methods',
@@ -17119,6 +17210,7 @@ async function commands(args) {
     resourceNotes: [
       'For formal multi-resource development, prefer src/resources/** + openxiangda resource validate|plan|publish.',
       'Use first-class route/public-access/auth-config/function/connector/notification/data-view/menu/permission commands for discovery, diagnosis, dry-run, and small live fixes.',
+      'Inbound Webhooks are declared in src/resources/webhooks and route only to a fixed App Function. Provider secrets belong in top-level Function secretRefs; signature verification must use input.rawBody before any data access.',
       'public-access is the new React SPA public policy resource for /view/:appType/public/* routes; page code should use PublicAccessGate, and Page SDK hooks must stay inside OpenXiangdaProvider + OpenXiangdaPageProvider.',
       'settings public-access is legacy form public-access compatibility/repair and should not be used for new React SPA apps.',
       'Direct live mutation commands should use --dry-run first and --write-manifest when the repository should remain source of truth.',
@@ -17513,6 +17605,7 @@ function directManifestDir(resourceType) {
     connector: path.join('src', 'resources', 'connectors'),
     notification: path.join('src', 'resources', 'notifications'),
     'data-view': path.join('src', 'resources', 'data-views'),
+    webhook: path.join('src', 'resources', 'webhooks'),
     menu: path.join('src', 'resources', 'menus'),
     role: path.join('src', 'resources', 'roles'),
     'page-permission-group': path.join('src', 'resources', 'permissions', 'page-groups'),
@@ -17532,6 +17625,7 @@ function removeDirectStateResource(target, resourceType, code) {
     function: 'functions',
     connector: 'connectors',
     'data-view': 'dataViews',
+    webhook: 'webhooks',
   };
   const bucket = buckets[resourceType];
   if (!bucket || !target.bound.resources?.[bucket]?.[code]) return;
@@ -17854,6 +17948,7 @@ function ensureResourceBuckets(bound) {
   bound.resources.connectors = bound.resources.connectors || {};
   bound.resources.dataViews = bound.resources.dataViews || {};
   bound.resources.storageConfigs = bound.resources.storageConfigs || {};
+  bound.resources.webhooks = bound.resources.webhooks || {};
   bound.resources.authConfigs = bound.resources.authConfigs || {};
   bound.resources.routes = bound.resources.routes || {};
   bound.resources.publicAccessPolicies = bound.resources.publicAccessPolicies || {};
@@ -18199,6 +18294,29 @@ function saveStorageConfigResource(target, storageCode, storageConfigId, extra =
   }, keys);
 }
 
+function saveWebhookResource(target, webhookCode, data = {}) {
+  const keys = [
+    'webhookId',
+    'endpointId',
+    'callbackPath',
+    'callbackUrl',
+    'targetFunctionCode',
+    'idempotencyQueryParam',
+    'maxBodyBytes',
+    'status',
+    'revision',
+  ];
+  const callbackPath = String(data?.callbackPath || '').trim();
+  const callbackUrl = callbackPath
+    ? `${String(target.profile?.baseUrl || '').replace(/\/+$/, '')}${callbackPath}`
+    : data?.callbackUrl;
+  saveStateResource(target, 'webhooks', webhookCode, {
+    ...pickStateFields(data, keys),
+    webhookId: data?.id || data?.webhookId,
+    callbackUrl,
+  }, keys);
+}
+
 function saveScopeResource(target, bucket, code, data = {}) {
   if (!bucket || !code) return;
   const keys = ['id', 'resourceCode', 'name', 'updatedAt'];
@@ -18347,6 +18465,7 @@ const RESOURCE_SPECS = [
   { key: 'functions', dir: 'functions', topFiles: ['functions.json'], pluralKeys: ['functions'] },
   { key: 'dataViews', dir: 'data-views', topFiles: ['data-views.json'], pluralKeys: ['dataViews', 'data-views'] },
   { key: 'storageConfigs', dir: 'storage', topFiles: ['storage.json'], pluralKeys: ['storageConfigs', 'storage'] },
+  { key: 'webhooks', dir: 'webhooks', topFiles: ['webhooks.json'], pluralKeys: ['webhooks'] },
   { key: 'authConfigs', dir: 'auth', topFiles: ['auth.json'], pluralKeys: ['authConfigs', 'auth'] },
   { key: 'routes', dir: 'routes', topFiles: ['routes.json'], pluralKeys: ['routes'] },
   {
@@ -18426,6 +18545,8 @@ const RESOURCE_TYPE_ALIASES = new Map([
   ['oss', 'storageConfigs'],
   ['oss-config', 'storageConfigs'],
   ['oss-configs', 'storageConfigs'],
+  ['webhook', 'webhooks'],
+  ['webhooks', 'webhooks'],
   ['auth', 'authConfigs'],
   ['auth-config', 'authConfigs'],
   ['auth-configs', 'authConfigs'],
@@ -19138,6 +19259,7 @@ function generateResourceTypes(manifest, outputFile) {
   const dataViewCodes = unique((manifest.dataViews || []).map(item => item.code).filter(Boolean));
   const functionCodes = unique((manifest.functions || []).map(item => item.code).filter(Boolean));
   const storageConfigCodes = unique((manifest.storageConfigs || []).map(item => item.code).filter(Boolean));
+  const webhookCodes = unique((manifest.webhooks || []).map(item => item.code).filter(Boolean));
   const authConfigCodes = unique((manifest.authConfigs || []).map(item => item.code).filter(Boolean));
   const publicAccessPolicyCodes = unique((manifest.publicAccessPolicies || []).map(item => item.code).filter(Boolean));
   const scopeDimensionCodes = unique((manifest.scopeDimensions || []).map(item => item.code).filter(Boolean));
@@ -19162,6 +19284,9 @@ function generateResourceTypes(manifest, outputFile) {
     `export const storageConfigCodes = ${JSON.stringify(storageConfigCodes, null, 2)} as const`,
     'export type StorageConfigCode = typeof storageConfigCodes[number]',
     '',
+    `export const webhookCodes = ${JSON.stringify(webhookCodes, null, 2)} as const`,
+    'export type WebhookCode = typeof webhookCodes[number]',
+    '',
     `export const functionCodes = ${JSON.stringify(functionCodes, null, 2)} as const`,
     'export type FunctionCode = typeof functionCodes[number]',
     '',
@@ -19196,6 +19321,7 @@ function generateResourceTypes(manifest, outputFile) {
     pagePermissionGroups: pagePermissionGroupCodes.length,
     dataViews: dataViewCodes.length,
     storageConfigs: storageConfigCodes.length,
+    webhooks: webhookCodes.length,
     functions: functionCodes.length,
     authConfigs: authConfigCodes.length,
     publicAccessPolicies: publicAccessPolicyCodes.length,
@@ -19273,6 +19399,50 @@ function validateResourceItem(kind, item, errors, warnings) {
     validateFunctionRuntimeInvoke(label, item, errors, warnings);
     validateFunctionPerformancePolicies(label, item, errors);
   }
+  if (kind === 'webhooks') {
+    const allowed = new Set([
+      'code',
+      'resourceCode',
+      'name',
+      'description',
+      'targetFunctionCode',
+      'idempotencyQueryParam',
+      'maxBodyBytes',
+      'status',
+    ]);
+    const unsupported = Object.keys(item).filter(
+      key => !key.startsWith('__') && !allowed.has(key)
+    );
+    if (unsupported.length > 0) {
+      errors.push(`${label}: 包含不支持的字段 ${unsupported.join(', ')}`);
+    }
+    if (!item.name) errors.push(`${label}: 缺少 name`);
+    if (!/^[A-Za-z][A-Za-z0-9_]{1,127}$/.test(String(item.targetFunctionCode || ''))) {
+      errors.push(`${label}: targetFunctionCode 格式不正确`);
+    }
+    if (
+      item.idempotencyQueryParam !== undefined &&
+      !/^[A-Za-z][A-Za-z0-9_.-]{0,127}$/.test(
+        String(item.idempotencyQueryParam)
+      )
+    ) {
+      errors.push(`${label}: idempotencyQueryParam 格式不正确`);
+    }
+    const maxBodyBytes = Number(item.maxBodyBytes || 262144);
+    if (
+      !Number.isInteger(maxBodyBytes) ||
+      maxBodyBytes < 1024 ||
+      maxBodyBytes > 1048576
+    ) {
+      errors.push(`${label}: maxBodyBytes 必须在 1024 到 1048576 之间`);
+    }
+    if (!['active', 'disabled'].includes(String(item.status || 'active'))) {
+      errors.push(`${label}: status 只能是 active 或 disabled`);
+    }
+    if (Object.keys(item).some(key => /secret|signature|hmac/i.test(key))) {
+      errors.push(`${label}: Webhook manifest 不能包含 Secret 或供应商验签配置`);
+    }
+  }
   if (kind === 'dataViews') {
     const definition = item.definition || item;
     const viewType = String(definition.viewType || 'row').toLowerCase();
@@ -20384,6 +20554,7 @@ async function buildResourcePlan(
   await addAutomationPlanActions(config, target, actions, manifest.automations, existing.automations);
   addPlanActions(actions, 'dataView', manifest.dataViews, existing.dataViews, (item, current) => dataViewEquals(target.bound, item, current));
   addPlanActions(actions, 'storageConfig', manifest.storageConfigs, existing.storageConfigs, (item, current) => storageConfigEquals(item, current));
+  addPlanActions(actions, 'webhook', manifest.webhooks, existing.webhooks, webhookEquals);
   addPlanActions(actions, 'scopeDimension', manifest.scopeDimensions, existing.scopeDimensions, (item, current) => scopeDimensionEquals(target.bound, item, current));
   addPlanActions(actions, 'scopeGrantSource', manifest.scopeGrantSources, existing.scopeGrantSources, (item, current) => scopeGrantSourceEquals(target.bound, item, current));
   addPlanActions(actions, 'dataScopePolicy', manifest.dataScopePolicies, existing.dataScopePolicies, dataScopePolicyEquals);
@@ -22244,6 +22415,7 @@ async function publishResourceManifest(config, target, manifest, options = {}) {
   await publishDataScopePolicyResources(config, target, manifest.dataScopePolicies || [], result, publishOptions);
   await publishDataViewResources(config, target, manifest.dataViews || [], result, publishOptions);
   await publishStorageConfigResources(config, target, manifest.storageConfigs || [], result, publishOptions);
+  await publishWebhookResources(config, target, manifest.webhooks || [], result, publishOptions);
   await publishPublicAccessPolicyResources(config, target, manifest.publicAccessPolicies || [], result, publishOptions);
   await publishPagePermissionGroupResources(config, target, manifest.pagePermissionGroups || [], result, publishOptions);
   await publishFormPermissionGroupResources(
@@ -22390,6 +22562,7 @@ const GENERIC_RESOURCE_KEY_BY_PLAN_KIND = Object.freeze({
   publicAccessPolicy: 'publicAccessPolicies',
   dataView: 'dataViews',
   storageConfig: 'storageConfigs',
+  webhook: 'webhooks',
   scopeDimension: 'scopeDimensions',
   scopeGrantSource: 'scopeGrantSources',
   dataScopePolicy: 'dataScopePolicies',
@@ -22898,6 +23071,7 @@ async function fetchExistingResourceMaps(config, target, manifest) {
     automations: new Map(),
     dataViews: new Map(),
     storageConfigs: new Map(),
+    webhooks: new Map(),
     scopeDimensions: new Map(),
     scopeGrantSources: new Map(),
     dataScopePolicies: new Map(),
@@ -23124,6 +23298,21 @@ async function fetchExistingResourceMaps(config, target, manifest) {
       });
     }
   }
+  if ((manifest.webhooks || []).length > 0) {
+    const data = await requestWithAuth(
+      config,
+      target.profileName,
+      apiPathWithQuery(
+        `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/webhooks`,
+        { page: 1, pageSize: 1000 }
+      )
+    );
+    indexByCode(
+      maps.webhooks,
+      normalizeItems(data),
+      item => item.code || item.resourceCode
+    );
+  }
   if ((manifest.scopeDimensions || []).length > 0) {
     const data = await requestWithAuth(
       config,
@@ -25115,6 +25304,45 @@ async function publishStorageConfigResources(config, target, storageConfigs, res
   }
 }
 
+async function publishWebhookResources(config, target, webhooks, result, options = {}) {
+  for (const webhookItem of webhooks) {
+    const code = webhookItem.code || webhookItem.resourceCode;
+    if (shouldSkipNoopResource(options, 'webhook', code)) {
+      recordNoopResource(result, 'webhook', code, options);
+      continue;
+    }
+    const existing = await findExistingWebhook(config, target, code);
+    const existingRevision = Number(existing?.revision);
+    const body = {
+      ...normalizeWebhookManifest(webhookItem),
+      expectedRevision:
+        existing && Number.isInteger(existingRevision) && existingRevision > 0
+          ? existingRevision
+          : existing
+            ? undefined
+            : 0,
+    };
+    const data = await requestWithAuth(
+      config,
+      target.profileName,
+      existing
+        ? `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/webhooks/${encodeURIComponent(code)}`
+        : `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/webhooks`,
+      { method: 'POST', body }
+    );
+    saveWebhookResource(target, code, data);
+    result.published.push({
+      kind: 'webhook',
+      code,
+      action: existing ? 'update' : 'create',
+      id: data?.id,
+      endpointId: data?.endpointId,
+      callbackPath: data?.callbackPath,
+      status: data?.status,
+    });
+  }
+}
+
 async function publishDataViewPermissionGroups(config, target, dataViewCode, permissionGroups) {
   await requestWithAuth(
     config,
@@ -25279,6 +25507,25 @@ async function findExistingStorageConfig(config, target, code) {
   return null;
 }
 
+async function findExistingWebhook(config, target, code) {
+  const state = target.bound.resources?.webhooks?.[code];
+  const byCode = await requestOptionalWithAuth(
+    config,
+    target.profileName,
+    `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/webhooks/${encodeURIComponent(code)}`
+  );
+  if (byCode?.id) return byCode;
+  if (state?.webhookId) {
+    return {
+      id: state.webhookId,
+      code,
+      revision: state.revision,
+      endpointId: state.endpointId,
+    };
+  }
+  return null;
+}
+
 async function findExistingAutomation(config, target, code) {
   const stateId = target.bound.resources?.automations?.[code]?.automationId;
   if (stateId) {
@@ -25557,6 +25804,22 @@ async function collectPruneResourceCandidates(config, target, manifest) {
         item => item.code || item.resourceCode
       );
     }
+    if (enabled('webhooks')) {
+      const data = await requestWithAuth(
+        config,
+        target.profileName,
+        apiPathWithQuery(`${appPath}/webhooks`, {
+          page: 1,
+          pageSize: 1000,
+        })
+      );
+      append(
+        'webhook',
+        desiredCodes(manifest.webhooks),
+        normalizeItems(data),
+        item => item.code || item.resourceCode
+      );
+    }
     if (enabled('publicAccessPolicies')) {
       const data = await requestWithAuth(
         config,
@@ -25747,6 +26010,21 @@ async function pruneFrozenResourceCandidate(config, target, result, candidate) {
     if (kind === 'storageConfig') {
       return postDelete(`${appPath}/storage-configs/${encodeURIComponent(code)}`);
     }
+    if (kind === 'webhook') {
+      return requestWithAuth(
+        config,
+        target.profileName,
+        apiPathWithPostDeleteAction(
+          `${appPath}/webhooks/${encodeURIComponent(code)}`
+        ),
+        {
+          method: 'POST',
+          body: candidate.frozenRevision
+            ? { expectedRevision: candidate.frozenRevision }
+            : {},
+        }
+      );
+    }
     if (kind === 'publicAccessPolicy') {
       return postDelete(`${appPath}/public-access/policies/${encodeURIComponent(code)}`);
     }
@@ -26147,6 +26425,7 @@ function removeStateResource(target, kind, code) {
     publicAccessPolicy: 'publicAccessPolicies',
     dataView: 'dataViews',
     storageConfig: 'storageConfigs',
+    webhook: 'webhooks',
     pagePermissionGroup: 'pagePermissionGroups',
     formPermissionGroup: 'formPermissionGroups',
   };
@@ -26449,6 +26728,22 @@ async function pullResources(config, target) {
     written.push(path.relative(process.cwd(), filePath));
   }
 
+  const webhooks = await requestWithAuth(
+    config,
+    target.profileName,
+    apiPathWithQuery(
+      `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/webhooks`,
+      { page: 1, pageSize: 1000 }
+    )
+  );
+  for (const webhookItem of normalizeItems(webhooks)) {
+    const code = webhookItem.code || webhookItem.resourceCode || webhookItem.id;
+    const filePath = path.join(baseDir, 'webhooks', `${code}.json`);
+    writeResourceJsonFile(filePath, toPulledWebhook(webhookItem));
+    written.push(path.relative(process.cwd(), filePath));
+    saveWebhookResource(target, code, webhookItem);
+  }
+
   const pageGroups = await requestWithAuth(
     config,
     target.profileName,
@@ -26722,6 +27017,18 @@ function toPulledStorageConfig(storageConfig) {
   });
 }
 
+function toPulledWebhook(webhookItem) {
+  return stripUndefinedValues({
+    code: webhookItem.code || webhookItem.resourceCode,
+    name: webhookItem.name,
+    description: webhookItem.description || '',
+    targetFunctionCode: webhookItem.targetFunctionCode,
+    idempotencyQueryParam: webhookItem.idempotencyQueryParam || 'nonce',
+    maxBodyBytes: webhookItem.maxBodyBytes || 262144,
+    status: webhookItem.status || 'active',
+  });
+}
+
 function rewriteDataViewDefinitionForManifest(definition, lookups) {
   rewriteDataViewSourceForManifest(definition.base, lookups);
   for (const join of definition.joins || []) {
@@ -27174,6 +27481,61 @@ function normalizeStorageConfigManifest(storageConfig) {
   });
 }
 
+function normalizeWebhookManifest(webhook) {
+  const code = String(webhook.code || webhook.resourceCode || '').trim();
+  const allowed = new Set([
+    'code',
+    'resourceCode',
+    'name',
+    'description',
+    'targetFunctionCode',
+    'idempotencyQueryParam',
+    'maxBodyBytes',
+    'status',
+  ]);
+  const unsupported = Object.keys(webhook).filter(
+    key => !key.startsWith('__') && !allowed.has(key)
+  );
+  if (unsupported.length > 0) {
+    fail(`webhook:${code || '<unknown>'} 包含不支持的字段 ${unsupported.join(', ')}`);
+  }
+  if (!/^[A-Za-z][A-Za-z0-9_]{1,127}$/.test(code)) {
+    fail('Webhook code 格式不正确');
+  }
+  const targetFunctionCode = String(webhook.targetFunctionCode || '').trim();
+  if (!/^[A-Za-z][A-Za-z0-9_]{1,127}$/.test(targetFunctionCode)) {
+    fail(`webhook:${code} targetFunctionCode 格式不正确`);
+  }
+  const idempotencyQueryParam = String(
+    webhook.idempotencyQueryParam || 'nonce'
+  ).trim();
+  if (!/^[A-Za-z][A-Za-z0-9_.-]{0,127}$/.test(idempotencyQueryParam)) {
+    fail(`webhook:${code} idempotencyQueryParam 格式不正确`);
+  }
+  const maxBodyBytes = Number(webhook.maxBodyBytes || 262144);
+  if (
+    !Number.isInteger(maxBodyBytes) ||
+    maxBodyBytes < 1024 ||
+    maxBodyBytes > 1048576
+  ) {
+    fail(`webhook:${code} maxBodyBytes 必须在 1024 到 1048576 之间`);
+  }
+  const status = String(webhook.status || 'active');
+  if (!['active', 'disabled'].includes(status)) {
+    fail(`webhook:${code} status 只能是 active 或 disabled`);
+  }
+  return stripUndefinedValues({
+    code,
+    name: String(webhook.name || code).trim(),
+    description:
+      webhook.description === undefined ? '' : String(webhook.description),
+    targetFunctionCode,
+    idempotencyQueryParam,
+    maxBodyBytes,
+    status,
+  });
+}
+
 function normalizeStorageCorsForPublish(cors) {
   if (cors === undefined || cors === null || cors === '') return undefined;
   const managed =
@@ -28321,6 +28683,21 @@ function storageConfigEquals(desired, existing) {
   );
 }
 
+function webhookEquals(desired, existing) {
+  if (!existing) return false;
+  const expected = normalizeWebhookManifest(desired);
+  return (
+    String(existing.code || existing.resourceCode || '') === expected.code &&
+    String(existing.name || '') === expected.name &&
+    String(existing.description || '') === expected.description &&
+    String(existing.targetFunctionCode || '') === expected.targetFunctionCode &&
+    String(existing.idempotencyQueryParam || 'nonce') ===
+      expected.idempotencyQueryParam &&
+    Number(existing.maxBodyBytes || 262144) === expected.maxBodyBytes &&
+    String(existing.status || 'active') === expected.status
+  );
+}
+
 function routeEquals(desired, existing) {
   if (!existing) return false;
   const expected = normalizeRouteManifest(desired);

package/lib/design-gates.js

@@ -540,6 +540,23 @@ const RESOURCE_EXPLAINS = {
       'openxiangda function invoke summarize_customer --body-json \'{"input":{}}\'',
     ],
   },
+  webhook: {
+    dir: 'src/resources/webhooks/*.json',
+    minimalManifest: {
+      code: 'yuquan_access',
+      name: '玉泉门禁开门事件',
+      targetFunctionCode: 'qfyy_access_event',
+      idempotencyQueryParam: 'nonce',
+      maxBodyBytes: 262144,
+      status: 'active',
+    },
+    commands: [
+      'openxiangda resource validate webhook --profile <name>',
+      'openxiangda resource plan webhook --only yuquan_access --profile <name> --json',
+      'openxiangda resource publish webhook --only yuquan_access --change <id> --profile <name>',
+      'openxiangda webhook deliveries yuquan_access --profile <name> --json',
+    ],
+  },
   connector: {
     dir: 'src/resources/connectors/*.json',
     minimalManifest: {
@@ -633,6 +650,7 @@ function getResourceExplain(type) {
     auth: 'auth-config',
     authconfigs: 'auth-config',
     functions: 'function',
+    webhooks: 'webhook',
     connectors: 'connector',
   };
   const key = aliases[rawKey] || rawKey;

package/lib/release-plan.js

@@ -102,6 +102,7 @@ const DIRECT_RESOURCE_TYPE_BY_KEY = Object.freeze({
   menus: 'menu',
   dataViews: 'data-view',
   storageConfigs: 'storage',
+  webhooks: 'webhook',
   authConfigs: 'auth-config',
   routes: 'route',
   publicAccessPolicies: 'public-access',
@@ -116,6 +117,7 @@ const DIRECT_RESOURCE_RELEASE_ORDER = Object.freeze([
   'roles',
   'connectors',
   'storageConfigs',
+  'webhooks',
   'authConfigs',
   'routes',
   'publicAccessPolicies',

package/openxiangda-skills/SKILL.md

@@ -189,6 +189,8 @@ Treat resource declarations as environment mapping and release-observability met
 
 An App Function may declare metadata-only top-level `secretRefs: [{ name, required }]` only with `function_v2` + `trusted_node_v2`; source resolves values with `await ctx.secrets.get(name)` and uses `ctx.utils.http` for controlled public HTTPS. Create/rotate values through hidden TTY or `openxiangda secret ... --value-stdin --change <change> --profile <name>`. Never put values in arguments, files, manifests, state, plans, logs, errors, or chat. Secret bindings require `backend_release_v2` and whole-app `atomic_staged_children_v2`; a missing capability is fail-closed and never uses the legacy source PATCH. For whole-app activation use exact-scope `resource publish <type> --only <code> --stage-only`, then pass the returned verified `stagedResource` to `release app-finalize`; an active Backend Release is never labeled staged.
 
+Inbound third-party callbacks use `src/resources/webhooks/<code>.json` and the public path returned after publish. A Webhook binds one fixed same-app Function; it never stores Secret values or provider signature rules. The Function reads the exact `input.rawBody`, verifies before any data/helper/network call, and protects business writes with `input.idempotencyKey`. Use `openxiangda webhook deliveries|delivery` for receipts and read `references/webhooks.md` through the workflow-automation skill for the full contract.
+
 The lease is app-level promotion ownership, while worktree ownership prevents two Codex tasks from editing through the same source directory. Different worktrees may keep developing and validating; only the clean synchronized main checkout publishes. Use full resource/runtime publish only when the approved bundle intentionally covers the whole dependency closure.
 
 ## Always

package/openxiangda-skills/references/openxiangda-api.md

@@ -969,3 +969,15 @@ Requires Bearer token. Creates a short-lived signed OSS upload URL for browser d
 ### POST `/apps/:appType/storage-configs/:code/objects/delete`
 
 Requires Bearer token. Deletes an OSS object under the configured `pathPrefix`.
+## Inbound Webhook
+
+- Management: `GET|POST /openxiangda-api/v1/apps/:appType/webhooks`
+- Detail/update/disable: `GET|POST|PUT|DELETE /openxiangda-api/v1/apps/:appType/webhooks/:code`
+- Delivery list/detail: `GET /openxiangda-api/v1/apps/:appType/webhooks/:code/deliveries[/:deliveryId]`
+- Public callback: `POST /openxiangda-webhooks/v1/:endpointId`
+
+The public `endpointId` resolves tenant/application ownership and is never
+replaced with `appType`. Management calls use normal profile authentication;
+the public callback is unauthenticated at the platform edge and the target
+Function must verify the provider signature from the exact raw body. See
+`webhooks.md` for the declaration and runtime envelope.

package/openxiangda-skills/references/resource-manifest-cheatsheet.md

@@ -683,7 +683,37 @@ const result = await sdk.function.invoke("reservation_reminder_summary", {
 
 适用边界：可复用后端业务逻辑、跨页面/自动化/流程共享的查询编排、连接器调用、通知编排、受控平台 API 调用。App Function 支持 `ctx.form.queryOne/queryMany/getById/createOne/updateOne/updateById`、`ctx.dataView`、`ctx.connector`、`ctx.notification`、`ctx.platform.roles`、`ctx.platform.api` 等受控 helper，当前 MVP 不暴露原始 SQL/Redis。应用角色查询和成员维护优先使用 `ctx.platform.roles.list/findByCode/addUsers/removeUser`；底层 `ctx.platform.api` 返回 HTTP 包装与平台 envelope，需要自行解包。已发布可信代码可以访问当前租户、当前应用内的资源；function manifest 的 `resources` 是可选映射、审计和影响分析信息，不再是逐函数权限白名单。页面用户仍不能直接提交内部表单，跨应用和跨租户访问仍被拒绝。运行时接口默认需要应用自动化管理权限；普通用户页面要调用时，用 `definitionJson.runtimeInvoke.audience` 声明 `authenticated`、`page_permission_group`、`app_roles`、`platform_roles` 或 `scope_policy`，使用 `roleCodes` 匹配应用角色、使用 `platformRoleCodes` 匹配同步身份 `SCHOOL_GUARDIAN`、`SCHOOL_STUDENT`、`SCHOOL_TEACHER`，不要把 `"*"`、`"all-app-roles"` 写进角色编码。若表单只能由函数/流程写入，在 `src/resources/settings/forms/<formCode>.json` 设置 `runtimeWrite.mode="function_only"` 关闭原始写入接口。
 
-## 5. Workflow — `src/resources/workflows/<code>/workflow.json`（manifest）+ `src/workflows/<code>/workflow.ts`（代码优先）
+## 5. Inbound Webhook — `src/resources/webhooks/<code>.json`
+
+```json
+{
+  "code": "yuquan_access",
+  "name": "玉泉门禁开门事件",
+  "targetFunctionCode": "qfyy_access_event",
+  "idempotencyQueryParam": "nonce",
+  "maxBodyBytes": 262144,
+  "status": "active"
+}
+```
+
+Webhook 只声明公开入口到固定 App Function 的映射，不包含 Secret 或验签规则。
+供应商 Secret 在目标 Function 顶层 `secretRefs` 声明，源码通过
+`await ctx.secrets.get(name)` 读取，并且必须在任何表单查询、写入、连接器或通知
+调用之前使用 `input.rawBody` 验签。平台保存原始 UTF-8 Body、Base64 Body、原始
+Query 字符串、重复参数数组、解析 JSON 和安全请求头；投递为 at-least-once，应用
+还必须用 `input.idempotencyKey` 对业务写入做幂等保护。
+
+```bash
+openxiangda resource validate webhook --profile <name>
+openxiangda resource plan webhook --only yuquan_access --profile <name> --json
+openxiangda resource publish webhook --only yuquan_access --change <id> --profile <name>
+openxiangda webhook deliveries yuquan_access --profile <name> --json
+```
+
+完整 Function 输入、HMAC-SHA1 常量时间比较、返回状态和玉泉门禁示例见
+[`webhooks.md`](webhooks.md)。
+
+## 6. Workflow — `src/resources/workflows/<code>/workflow.json`（manifest）+ `src/workflows/<code>/workflow.ts`（代码优先）
 
 ```jsonc
 // src/resources/workflows/customer_approval/workflow.json
@@ -713,7 +743,7 @@ export default defineWorkflow({
 
 CLI 编译为 `definition.v3.json` + `preview.json`，平台运行时仍走标准工作流引擎。完整规则见 [`workflow-v3.md`](workflow-v3.md)。
 
-## 6. Automation — `src/resources/automations/<code>/{definition.code.json,preview.json}` + `src/automations/<code>/index.ts`
+## 7. Automation — `src/resources/automations/<code>/{definition.code.json,preview.json}` + `src/automations/<code>/index.ts`
 
 ```jsonc
 // src/resources/automations/notify_on_submit/definition.code.json

package/openxiangda-skills/references/webhooks.md

@@ -0,0 +1,213 @@
+# OpenXiangda 1.x Inbound Webhooks
+
+Inbound Webhook 用于让门禁、支付、IoT 等外部系统主动调用 OpenXiangda
+应用。平台只负责通用接入：接收和保存原始请求、限制大小、按幂等键串行化、
+调用唯一绑定的 App Function，并把 Function 的处理结果映射为稳定 HTTP 状态。
+供应商签名规则、事件筛选和业务写入始终属于应用 Function。
+
+## 声明 Webhook
+
+在 `src/resources/webhooks/<code>.json` 创建 Manifest：
+
+```json
+{
+  "code": "yuquan_access",
+  "name": "玉泉门禁开门事件",
+  "description": "接收 REC_SUCCESS 事件并匹配琴房预约",
+  "targetFunctionCode": "qfyy_access_event",
+  "idempotencyQueryParam": "nonce",
+  "maxBodyBytes": 262144,
+  "status": "active"
+}
+```
+
+- `targetFunctionCode` 必须是同一租户、同一应用内已经启用的 Function。
+- `idempotencyQueryParam` 默认是 `nonce`。该参数为空时，平台使用请求摘要。
+- `maxBodyBytes` 默认 256 KiB，允许范围为 1 KiB 到 1 MiB。
+- 平台网关对公开入口统一限制 1 MiB，并按来源 IP 限制 100 请求/秒、突发
+  200；超限返回 429。该限制不代替验签和业务幂等。
+- Manifest 不得包含 Webhook Secret、签名算法或供应商凭据。
+- 发布后从 `.openxiangda/state.json` 的
+  `resources.webhooks.<code>.callbackUrl` 取得完整回调地址；`callbackPath` 是相对
+  当前 profile API base（通常为 `<origin>/service`）的路径。不要自行用 `appType`
+  拼接公开 URL。
+
+## 声明和配置 Secret
+
+Webhook Secret 使用现有 App Function Secret。Function 必须使用
+`function_v2 + trusted_node_v2`，并在 Manifest 顶层声明引用：
+
+```json
+{
+  "code": "qfyy_access_event",
+  "name": "处理玉泉门禁事件",
+  "secretRefs": [
+    { "name": "yuquan_webhook_secret", "required": true }
+  ],
+  "definitionJson": {
+    "version": "function_v2",
+    "runtimeMode": "trusted_node",
+    "runtimeContractVersion": "trusted_node_v2",
+    "timeoutMs": 30000,
+    "sourceFile": {
+      "localPath": "src/functions/qfyy_access_event/index.ts"
+    }
+  },
+  "status": "active"
+}
+```
+
+Webhook Function 的 `timeoutMs` 必须在 1 到 120000 毫秒之间。平台在配置和
+每次调用时都会重新校验运行时契约，Function 后续被禁用、降级为旧运行时或把
+超时调到上限之外时，Webhook 会返回可重试的非 2xx，而不会以宽权限身份执行。
+
+Secret 值只通过隐藏输入或标准输入写入平台：
+
+```bash
+openxiangda secret create yuquan_webhook_secret \
+  --value-stdin --change <change-id> --profile <name>
+```
+
+禁止把值写进 Webhook/Function Manifest、源码、`.env`、日志、异常或函数返回值。
+
+## Function 输入
+
+Function 的第二个参数和 `ctx.input` 都是以下对象：
+
+```ts
+interface WebhookInput {
+  deliveryId: string;
+  idempotencyKey: string;
+  webhookCode: string;
+  receivedAt: string;
+  rawBody: string;
+  rawBodyBase64: string;
+  rawQueryString: string;
+  query: Record<string, string[]>;
+  headers: Record<string, string[]>;
+  body: unknown;
+  request: { method: "POST"; path: string };
+}
+```
+
+`query` 保留重复参数及其顺序。`rawBody` 是签名使用的原始 UTF-8 文本；
+`body` 只用于验签成功后的业务解析。平台会从 `headers` 中移除 Authorization、
+Cookie、代理凭据和客户端证书头。
+
+## 验签顺序
+
+验签、时间窗和事件来源检查必须发生在任何 `ctx.form`、`ctx.dataView`、
+`ctx.connector`、`ctx.notification`、`ctx.platform` 或 `ctx.utils.http` 调用之前。
+永远不要对 `input.body` 再 `JSON.stringify` 后验签，空格、字段顺序或转义变化会
+使签名失真。
+
+下面展示 HMAC-SHA1 和常量时间比较。`buildCanonicalText` 只是结构示例；必须按
+供应商正式文档确认字段顺序、分隔符、URL 编码和 hex/base64 输出格式：
+
+```ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { AppFunctionContextV2 } from "openxiangda/runtime";
+
+type WebhookInput = {
+  deliveryId: string;
+  idempotencyKey: string;
+  rawBody: string;
+  query: Record<string, string[]>;
+  body: unknown;
+};
+
+function first(query: Record<string, string[]>, name: string) {
+  return String(query[name]?.[0] || "");
+}
+
+function equalEncodedSignature(actual: string, expected: string) {
+  const left = Buffer.from(actual.trim().toLowerCase(), "utf8");
+  const right = Buffer.from(expected.trim().toLowerCase(), "utf8");
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+function buildCanonicalText(input: WebhookInput) {
+  // Replace this illustrative order with the provider's exact contract.
+  return [
+    first(input.query, "nonce"),
+    first(input.query, "timestamp"),
+    first(input.query, "orgId"),
+    input.rawBody,
+  ].join("");
+}
+
+export default async function handleWebhook(
+  ctx: AppFunctionContextV2,
+  input: WebhookInput,
+) {
+  const secret = await ctx.secrets.get("yuquan_webhook_secret");
+  const expected = createHmac("sha1", secret)
+    .update(buildCanonicalText(input), "utf8")
+    .digest("hex");
+  const actual = first(input.query, "signature");
+  if (!actual || !equalEncodedSignature(actual, expected)) {
+    return { webhook: { outcome: "rejected", status: 401 } };
+  }
+
+  const timestamp = Number(first(input.query, "timestamp"));
+  if (!Number.isFinite(timestamp) || Math.abs(Date.now() - timestamp) > 5 * 60_000) {
+    return { webhook: { outcome: "rejected", status: 401 } };
+  }
+
+  const event = input.body as {
+    callbackTag?: string;
+    data?: {
+      isAuth?: boolean;
+      deviceSn?: string;
+      jobNum?: string;
+      recognizeTime?: string;
+      recognizeType?: number;
+      memberId?: string;
+      personType?: number;
+    };
+  };
+  if (event.callbackTag !== "REC_SUCCESS" || event.data?.isAuth !== true) {
+    return { webhook: { outcome: "ignored" } };
+  }
+
+  // The application must atomically claim input.idempotencyKey in its own
+  // business record before creating/updating reservation data.
+  await processAccessEventIdempotently(ctx, input.idempotencyKey, event.data);
+  return { webhook: { outcome: "accepted" } };
+}
+```
+
+`processAccessEventIdempotently` 是应用函数中的业务实现，不是平台内置 API。应把
+`idempotencyKey` 写入带唯一约束或等价原子保护的业务记录，然后再执行副作用。
+平台提供 at-least-once 投递；如果 Function 已产生副作用，但进程在成功回执落库前
+中断，同一事件会再次执行。
+
+## 返回契约
+
+- 普通返回，或 `{ webhook: { outcome: "accepted" } }`：HTTP 200。
+- `{ webhook: { outcome: "ignored" } }`：HTTP 200，适合已验签但无需处理的事件。
+- `{ webhook: { outcome: "rejected", status: 400|401|403|409|422 } }`：指定 4xx。
+- `{ webhook: { outcome: "retry" } }` 或抛出异常：HTTP 503，通知供应商重试。
+
+平台不会把 Function 返回值、日志、异常详情或 Secret 回显给外部调用方。
+投递原始请求和审计信息默认保留 180 天，由平台部署环境统一配置；应用不应把
+Webhook 投递表当作永久业务档案，需要长期保存的字段应在验签后写入自己的表单。
+
+## 校验、发布和诊断
+
+```bash
+openxiangda resource validate webhook --profile <name>
+openxiangda resource plan webhook --only yuquan_access --profile <name> --json
+openxiangda resource publish webhook --only yuquan_access \
+  --change <change-id> --profile <name>
+
+openxiangda webhook list --profile <name> --json
+openxiangda webhook get yuquan_access --profile <name> --json
+openxiangda webhook deliveries yuquan_access --profile <name> --json
+openxiangda webhook delivery yuquan_access <delivery-id> --profile <name> --json
+openxiangda webhook disable yuquan_access \
+  --change <change-id> --profile <name>
+```
+
+先发布并验证 Function，再启用 Webhook。新 Function 与 Webhook 同轮交付时，可以
+先以 `status: "disabled"` 发布 Webhook，验证 Function 后再把状态改为 `active`。

package/openxiangda-skills/skills/openxiangda-workflow-automation/SKILL.md

@@ -105,6 +105,8 @@ JS_CODE is the backend execution escape hatch for workflow and automation. Use i
 
 App Function is the reusable backend execution model. Use it when the logic should be called by custom pages, multiple automations, workflows, or the runtime API. Source lives in `src/functions/<functionCode>/index.ts`; manifest lives in `src/resources/functions/<functionCode>.json`. Call it from pages with `sdk.function.invoke(code, { input })`, from graph definitions with `function_call`, or from the runtime endpoint `/:appType/v1/functions/:code/invoke.json`. Direct runtime invocation defaults to app automation management permission; ordinary page callers must declare `definitionJson.runtimeInvoke.audience` (`authenticated`, `page_permission_group`, `app_roles`, or `scope_policy`). Prefer `export default async function(ctx, input) {}` for App Function source; the second argument is the invoke input and the same value is available as `ctx.input`. Current MVP exposes controlled helpers only and does not expose raw SQL or Redis. App Functions and trusted-node Automation scripts can call `ctx.files.readAsBase64` with an attachment from the current `ctx.formData`, or with a server-verified form record/field reference. This helper reads platform storage without a browser session, rejects arbitrary URLs and non-images, caps files at 10 MiB, and must be used without logging or persisting the Base64. App Functions can call `ctx.process.startFromExistingInstance`, `resolveCapabilities`, `resubmitTask`, `withdraw`, and `transferTask`; published trusted code may access resources in its current tenant/application, while workflow/task authorization, audit, event, replay, cross-app, and cross-tenant boundaries remain enforced. `resources` is optional mapping/audit metadata rather than an application-internal authorization list. Keep internal forms closed to direct user submit unless the business explicitly needs raw form submission; use `runtimeWrite.mode="function_only"` for function-only forms.
 
+For inbound third-party callbacks, declare `src/resources/webhooks/<code>.json` with a fixed `targetFunctionCode`; do not expose `appType` as a public routing identifier and do not put provider verification fields or Secret values in the Webhook manifest. The Function must use `input.rawBody` for signature verification before any data/helper/network call, read only top-level declared `secretRefs`, and use `input.idempotencyKey` to protect business writes because delivery is at-least-once. Read `references/webhooks.md` for the complete envelope, HMAC example, response directives, publish commands, and delivery diagnosis.
+
 For third-party credentials, use top-level metadata-only `secretRefs` plus `definitionJson.version="function_v2"` and `runtimeContractVersion="trusted_node_v2"`; read a declared value with `await ctx.secrets.get(name)` and call public business APIs through `ctx.utils.http`. Never use `process.env` for platform secrets. Values are managed with `openxiangda secret create|rotate --value-stdin --change <change> --profile <name>` and never appear in Git, build output, snapshots, plan diffs, logs, exceptions, or traces. Local tests may use `function test --secret-from-env logical=ENV` only; the value is passed to an isolated child over stdin and is never written to workspace/cache/state. For a Root App transaction, use exact-scope `resource publish function --only <code> --stage-only` and include its verified `stagedResource` in `release app-finalize`.
 
 For new AI-authored automations, prefer code-first `automation_code_ts` resources instead of visual v3 graph definitions. Put the source in `src/automations/<resourceCode>/index.ts`, define `definition.code.json` with `kind: "automation_code_ts"`, and provide `preview.json` for read-only frontend display. Use `ctx.logger.debug/info/warn/error(message, data?)` at every important step; OpenXiangda can inspect logs with `automation executions`, `automation logs`, and `automation diagnose`.
@@ -199,3 +201,4 @@ Use `automation disable` before risky edits. Published automations create a draf
 - Notification resources and runtime calls: `references/notifications.md`
 - API fields: `references/openxiangda-api.md`
 - Profile-isolated IDs: `references/workspace-state.md`
+- Inbound Webhook declaration, verification, idempotency, and delivery diagnosis: `references/webhooks.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openxiangda",
-  "version": "1.0.269",
+  "version": "1.0.270",
   "description": "OpenXiangda CLI, workspace build tools, runtime SDK, and form components.",
   "private": false,
   "bin": {
@@ -68,7 +68,7 @@
     "source:admin-list": "node scripts/sync-admin-list-source.mjs",
     "check": "node --check bin/openxiangda.js && node --check lib/*.js && node --check packages/sdk/src/build-source/src/cli.mjs && node --check packages/sdk/src/build-source/scripts/*.mjs && node --check packages/sdk/src/build-source/scripts/utils/*.mjs",
     "test": "npm run test:fast",
-    "test:fast": "npm run check && node scripts/delivery-v2-package-smoke.mjs && node scripts/delivery-v2-executor-smoke.mjs && node scripts/delivery-v2-release-conformance-smoke.mjs && node scripts/http-proxy-smoke.mjs && node scripts/form-export-cli-smoke.mjs && node scripts/open-api-cli-smoke.mjs && node scripts/release-plan-smoke.mjs && node scripts/typed-resource-plan-smoke.mjs && node scripts/integration-bundle-smoke.mjs && node scripts/content-cache-smoke.mjs && node scripts/dependency-capsule-smoke.mjs && node scripts/sdd-stages-smoke.mjs && node scripts/environment-swap-cli-smoke.mjs && node scripts/environment-policy-cli-smoke.mjs",
+    "test:fast": "npm run check && node scripts/delivery-v2-package-smoke.mjs && node scripts/delivery-v2-executor-smoke.mjs && node scripts/delivery-v2-release-conformance-smoke.mjs && node scripts/http-proxy-smoke.mjs && node scripts/form-export-cli-smoke.mjs && node scripts/open-api-cli-smoke.mjs && node scripts/release-plan-smoke.mjs && node scripts/typed-resource-plan-smoke.mjs && node scripts/webhook-resource-cli-smoke.mjs && node scripts/integration-bundle-smoke.mjs && node scripts/content-cache-smoke.mjs && node scripts/dependency-capsule-smoke.mjs && node scripts/sdd-stages-smoke.mjs && node scripts/environment-swap-cli-smoke.mjs && node scripts/environment-policy-cli-smoke.mjs",
     "test:changed": "npm run check && node scripts/run-test-suite.mjs --changed --evidence",
     "test:contract": "npm run check && node scripts/run-test-suite.mjs --contract --evidence",
     "test:release": "npm run check && node scripts/run-test-suite.mjs --release --evidence",
@@ -80,6 +80,7 @@
     "test:content-cache": "node scripts/content-cache-smoke.mjs",
     "test:dependency-capsule": "node scripts/dependency-capsule-smoke.mjs",
     "test:typed-resource-plan": "node scripts/typed-resource-plan-smoke.mjs",
+    "test:webhook-resource": "node scripts/webhook-resource-cli-smoke.mjs",
     "test:integration-bundle": "node scripts/integration-bundle-smoke.mjs",
     "prepublishOnly": "npm run release:evidence:verify && node scripts/release-mainline-guard.mjs",
     "prepack": "npm run source:admin-list && npm run build:sdk",
@@ -232,42 +233,43 @@
   },
   "openxiangdaRelease": {
     "schemaVersion": "openxiangda.release-notes/v1",
-    "version": "1.0.269",
-    "title": "OpenXiangda V1 工作区登录与 V2 升级建议",
+    "version": "1.0.270",
+    "title": "OpenXiangda V1 Inbound Webhook",
     "status": "reviewed",
-    "summary": "V1 平台登录态按工作区隔离，停止读取和合并全局 profiles；版本、升级与技能刷新入口展示 V2 采用建议。",
+    "summary": "V1 应用可以声明公开 Inbound Webhook，由平台可靠接入并转发给固定 App Function，供应商验签和业务处理仍由应用负责。",
     "newFeatures": [
-      "V1 人类可读命令展示 V2 推荐与迁移评估入口，JSON 结果提供结构化 migrationAdvice。",
-      "login、auth 和 platform 支持 --cwd 指定登录态所属工作区。"
+      "新增 src/resources/webhooks/*.json 资源声明、校验、计划、发布、拉取和停用能力。",
+      "新增 webhook list/get/create/update/upsert/disable/deliveries/delivery 命令，用于配置和投递诊断。",
+      "Webhook Function 获得原始 Body、原始 Query、重复参数数组、安全 Headers、投递 ID 和幂等键。"
     ],
     "fixes": [
-      "登录、刷新与退出读写工作区 .openxiangda/profiles.json，避免不同项目覆盖同一全局账号。",
-      "会话对象固定来源文件，切换目录后仍写回原工作区；登录文件原子保存、权限 0600 并自动忽略 Git 跟踪。",
-      "新建工作区可保留受管登录文件；Git 基线只读检查使用隔离的工作区凭据副本。"
+      "Function 资源在 Webhook 之前发布，prune 对遗失的 Webhook 执行停用而不是删除审计数据。",
+      "模板、Skill、命令发现和 API 参考统一说明 rawBody 验签、secretRefs 和业务幂等要求。"
     ],
     "affectedUsers": [
-      "维护 V1 应用、在多个工作区使用不同平台或账号的开发者。"
+      "需要接收门禁、支付、IoT 或其他第三方主动回调的 OpenXiangda V1 应用开发者。"
     ],
     "compatibility": {
       "node": ">=18；全局 V2 统一入口需要 >=24",
       "workspaceGenerations": [
         "v1"
       ],
-      "workspacePolicy": "原全局 profiles 保留但不再读取，升级后每个项目必须重新登录；已有工作区 profiles 可直接使用。",
-      "platformPolicy": "不改变平台身份、授权协议或生产应用。OSS 环境配置仍由原全局 .env 管理。"
+      "workspacePolicy": "现有 V1 资源保持兼容；只有声明 webhooks 的应用会创建公开回调端点。",
+      "platformPolicy": "必须部署包含 V1 Webhook 管理/公开入口、SQL 迁移和网关规则的平台版本。App Function Secret 必须按部署规范启用。"
     },
     "upgradeSteps": [
-      "将项目依赖锁定到 openxiangda@1.0.269 或运行同代 update install。",
-      "进入项目重新运行 openxiangda login <platform-url>；新项目先用 --cwd <directory> 指定目标目录登录。",
-      "执行 skill install --force 和 skill bootstrap --force 刷新技能与工作区指引，再运行项目检查。",
-      "使用 Node.js 24 的统一入口查看 V2 迁移建议并执行 migrate assess，按评估结果规划应用迁移。"
+      "将 V1 项目依赖锁定到 openxiangda@1.0.270 或运行同代 update install。",
+      "执行 skill install --force 和 skill bootstrap --force，阅读 references/webhooks.md。",
+      "先发布声明 secretRefs 的 trusted_node_v2 Function，再声明并发布 Webhook。",
+      "从 .openxiangda/state.json 读取 callbackUrl，配置到供应商并用投递查询命令完成验签、重试和幂等验收。"
     ],
     "knownLimitations": [
-      "不会自动复制全局或其他项目的令牌，也不会自动迁移 V1 应用到 V2。",
-      "同一工作区并发登录或刷新仍受平台令牌有效性约束。"
+      "首版公开入口只接受 application/json 的 HTTP POST，单端点 Body 上限不超过 1 MiB。",
+      "平台不内置供应商签名算法；Function 必须按照供应商正式协议使用 rawBody 验签。",
+      "投递语义为 at-least-once，应用必须用 input.idempotencyKey 原子保护业务副作用。"
     ],
     "issues": [],
-    "sha256": "112d003eb255dbdf9b221e6ec16c19fefe4a6e164bff22854e6128ad62df5d01",
-    "url": "https://github.com/1377385356/openxiangda-v1/releases/tag/v1.0.269"
+    "sha256": "7ec9e6eebb0b509833283274bde2fdfba48a099c76cea862f77a08441a4ef1dd",
+    "url": "https://github.com/1377385356/openxiangda-v1/releases/tag/v1.0.270"
   }
 }

package/templates/openxiangda-react-spa/.cursor/rules/openxiangda-resources.mdc

@@ -25,6 +25,7 @@ openxiangda resource typegen --profile <name>
 - Guest file upload requires a structured form grant such as `{code, actions: ["upload", "preview"], fields?: [...]}`; optional form `upload` or `grants.storage` constraints define bucket/MIME/extensions/size/visibility/path prefix.
 - Connector secrets and third-party credentials belong in the platform backend, never in manifests or page source.
 - App Function manifests may contain only metadata names in top-level `secretRefs`; values use the Secret CLI and runtime `ctx.secrets.get(name)` under `function_v2` / `trusted_node_v2`.
+- Inbound callbacks use `src/resources/webhooks/*.json` with one fixed `targetFunctionCode`. Keep Secret/signature rules out of that manifest; verify `input.rawBody` before any helper call and make business writes idempotent with `input.idempotencyKey`.
 - Formal changes should keep Git as the source of truth: edit manifests, validate, plan, then publish.
 - Exact selectors apply before manifest/source analysis and JS_CODE build: touch only selected targets plus transitive/shared/ambient dependencies; omit selectors only for intentional full-workspace work.
 - `resource plan` and publish dry-runs are GET/HEAD-only. On `READ_ONLY_AUTH_REQUIRED`, run `openxiangda auth refresh --profile <name>` or log in again before retrying; never refresh inside the plan.

package/templates/openxiangda-react-spa/.qoder/rules/openxiangda-resources.md

@@ -25,6 +25,7 @@ openxiangda resource typegen --profile <name>
 - Guest file upload requires a structured form grant such as `{code, actions: ["upload", "preview"], fields?: [...]}`; optional form `upload` or `grants.storage` constraints define bucket/MIME/extensions/size/visibility/path prefix.
 - Connector secrets and third-party credentials belong in the platform backend, never in manifests or page source.
 - App Function manifests may contain only metadata names in top-level `secretRefs`; values use the Secret CLI and runtime `ctx.secrets.get(name)` under `function_v2` / `trusted_node_v2`.
+- Inbound callbacks use `src/resources/webhooks/*.json` with one fixed `targetFunctionCode`. Keep Secret/signature rules out of that manifest; verify `input.rawBody` before any helper call and make business writes idempotent with `input.idempotencyKey`.
 - Formal changes should keep Git as the source of truth: edit manifests, validate, plan, then publish.
 - Exact selectors apply before manifest/source analysis and JS_CODE build: touch only selected targets plus transitive/shared/ambient dependencies; omit selectors only for intentional full-workspace work.
 - `resource plan` and publish dry-runs are GET/HEAD-only. On `READ_ONLY_AUTH_REQUIRED`, run `openxiangda auth refresh --profile <name>` or log in again before retrying; never refresh inside the plan.

package/templates/openxiangda-react-spa/AGENTS.md

@@ -104,6 +104,8 @@ openxiangda release ship --change <release-change> --profile <name> --confirm-pr
 
 App Function 第三方凭据只能在 Function manifest 顶层声明 `secretRefs: [{name, required}]`，并使用 `function_v2` + `runtimeContractVersion: "trusted_node_v2"`；源码通过 `await ctx.secrets.get(name)` 获取。值只能经 `openxiangda secret create|rotate --value-stdin --change <id> --profile <name>` 或隐藏 TTY 配置，禁止进入 Git、`.env`、manifest、源码、构建产物、plan、日志和异常。本地测试只使用 `openxiangda function test --secret-from-env logical=ENV` 的隔离子进程注入。
 
+外部系统主动回调使用 `src/resources/webhooks/<code>.json`，只声明固定的 `targetFunctionCode`、幂等 Query 参数、Body 上限和启停状态。Secret 仍由目标 Function 顶层 `secretRefs` 声明；Function 必须先基于 `input.rawBody` 验签，再调用任何表单、数据视图、连接器、通知或 HTTP helper，并用 `input.idempotencyKey` 保护业务写入。完整输入和返回契约见 `$openxiangda-workflow-automation` 的 `references/webhooks.md`。
+
 App Function 查询应用角色及维护角色成员必须使用正式的 `ctx.platform.roles`：`findByCode(roleCode)`、`list()`、`get(roleId)`、`listUsers(roleId)`、`addUsers(roleId, userIds)`、`removeUser(roleId, userId)`。该 API 固定到 `ctx.app.appType`，按真实 operator 校验 `app:role:manage` 并保留调用审计；不要依赖自定义的 `ctx.platform.roles` 声明，也不要用泛型 `ctx.platform.api` 绕过角色契约。
 
 `openxiangda runtime deploy --no-activate` 会构建并上传不可变预览版本；发布前先提交所有可能进入构建的源码/配置。所有 Runtime deploy（包括 `--no-activate`）都会先获取应用发布 lease，并在任何构建和上传前冻结 clean `HEAD` 与当前 active Runtime 父血缘；旧分支返回 `RUNTIME_SOURCE_BASE_DIVERGED`，不能先上传旧 preview 再激活。`openspec/` SDD 证据和生成/状态目录不算源码 dirty。仅审批的回退可使用 `--allow-runtime-rollback --reason "至少 8 个字符"`；`--no-build` 不会跳过守卫。不要手工修改 `dist/index.html`。

package/templates/sy-lowcode-app-workspace/.cursor/rules/openxiangda-resources.mdc

@@ -31,6 +31,8 @@ Exact `--only/--code` selectors apply before manifest/source analysis and JS_COD
 
 App Function manifests may contain only logical names in top-level `secretRefs`; use `function_v2` / `trusted_node_v2`, resolve values with `ctx.secrets.get(name)`, and manage values only with `openxiangda secret ... --value-stdin --change ... --profile ...`. Values never belong in Git, `.env`, manifests, source, builds, plans, logs, or errors.
 
+Inbound callbacks use `src/resources/webhooks/*.json` with one fixed `targetFunctionCode`. Keep Secret/signature rules out of that manifest; verify `input.rawBody` before any helper call and make business writes idempotent with `input.idempotencyKey`.
+
 When a Function/Automation enters scope only through source changes, publishing uses a server-side source-field PATCH and preserves online bindings, contracts, metadata, trigger/view configuration, and enabled/published state. A new source-free Automation with a complete `definitionJson.version="v3"` automatically uses manifest create; replacing an existing whole manifest requires `--replace-manifest --reason "..."`. Formal promotion freezes the clean publish HEAD separately from the change/remote baseline and preflights the whole set; `SOURCE_BASE_DIVERGED`, `RELEASE_SOURCE_BEHIND_MAIN`, and `RESOURCE_FIELD_CONFLICT` require reconciliation. After activation, merge/push the frozen SHA, verify `release integration-status`, then run normal `release end`.
 
 Before editing `roles`, `permissions/page-groups`, or `permissions/form-groups` for account/role/data-scope/RBAC/query-param authorization work, run `openxiangda design gates --topic permissions --json`, choose the permission mode, and write the permission matrix.

package/templates/sy-lowcode-app-workspace/.qoder/rules/openxiangda-resources.md

@@ -52,6 +52,7 @@ Function/Automation 仅因源码变化进入 scope 时，默认通过服务端
 - ❌ 把 `formUuid` / `pageId` / `workflowId` 等平台 ID 直接写进 manifest（CLI 解析逻辑 code）。
 - ❌ 把 API key / token / secret / password / authorization / headers / credential 写进 manifest（平台后台配置）。
 - ✅ App Function 只在 manifest 顶层写逻辑名 `secretRefs`，使用 `function_v2` / `trusted_node_v2` 和 `ctx.secrets.get(name)`；值仅由 `openxiangda secret ... --value-stdin --change ... --profile ...` 管理。
+- ✅ 外部回调在 `src/resources/webhooks/*.json` 只绑定固定 `targetFunctionCode`；验签必须先使用 `input.rawBody`，业务写入必须使用 `input.idempotencyKey` 幂等，Secret/签名规则不写进 Webhook manifest。
 - ❌ data view 用作单表 CRUD、`linkedForm` 下拉、写回、强实时数据源。
 - ❌ 只靠 query 参数、前端隐藏按钮、硬编码角色、mock 权限或 `PermissionBoundary` 作为敏感授权。
 - ❌ 管理型角色缺少 `app:role:manage`、`app:page-permission-group:manage`、`app:form-permission-group:manage` 或 `app:organization:manage`。

package/templates/sy-lowcode-app-workspace/AGENTS.md

@@ -118,6 +118,8 @@ Delivery V2 自动从期望状态按资源指纹计算精确范围，使用 CLI
 
 App Function 第三方凭据只能在 Function manifest 顶层声明 `secretRefs: [{name, required}]`，并使用 `function_v2` + `runtimeContractVersion: "trusted_node_v2"`；源码通过 `await ctx.secrets.get(name)` 获取。值只能用 `openxiangda secret create|rotate --value-stdin --change <id> --profile <name>` 或隐藏 TTY 配置，禁止写入 Git、`.env`、manifest、源码、构建产物、plan、日志和异常。本地联调只允许 `openxiangda function test --secret-from-env logical=ENV`，它不会把值写入 workspace/cache/state。
 
+外部系统主动回调使用 `src/resources/webhooks/<code>.json`，只声明固定的 `targetFunctionCode`、幂等 Query 参数、Body 上限和启停状态。Secret 仍由目标 Function 顶层 `secretRefs` 声明；Function 必须先基于 `input.rawBody` 验签，再调用任何表单、数据视图、连接器、通知或 HTTP helper，并用 `input.idempotencyKey` 保护业务写入。完整输入和返回契约见 `$openxiangda-workflow-automation` 的 `references/webhooks.md`。
+
 App Function 查询应用角色及维护角色成员必须使用正式的 `ctx.platform.roles`：`findByCode(roleCode)`、`list()`、`get(roleId)`、`listUsers(roleId)`、`addUsers(roleId, userIds)`、`removeUser(roleId, userId)`。该 API 固定到 `ctx.app.appType`，按真实 operator 校验 `app:role:manage` 并保留调用审计；不要依赖自定义的 `ctx.platform.roles` 声明，也不要用泛型 `ctx.platform.api` 绕过角色契约。
 
 ## 工作区结构速查