openxiangda 1.0.268 → 1.0.270

package/lib/cli.js

@@ -7,7 +7,7 @@ const { spawn, spawnSync } = require('child_process');
 const { pathToFileURL } = require('url');
 const esbuild = require('esbuild');
 const {
-  CONFIG_FILE,
+  getConfigFile,
   GLOBAL_ENV_FILE,
   PROJECT_STATE_FILE,
   getProfile,
@@ -115,6 +115,7 @@ const {
 } = require('./resource-binding-contract');
 const { getSkillStatusReport, installSkills } = require('./skills');
 const { resolveUpdateTarget, buildGenerationUpdateCommand } = require('./generation-update');
+const { migrationAdvice, printMigrationAdvice } = require('./migration-advice');
 const {
   assertOrClaimWorktreeOwner,
   claimWorktreeOwner,
@@ -233,7 +234,12 @@ const genericGitBasePlanCache = new Map();
 async function main(argv) {
   let commandError = null;
   try {
-    return await mainImpl(argv);
+    const result = await mainImpl(argv);
+    const [command, action] = argv;
+    if (!argv.some(value => value === '--json' || value.startsWith('--json=')) && (!command || ['version', '--version', '-v', 'help', '--help', '-h', 'update'].includes(command) || command === 'skill' && ['install', 'bootstrap'].includes(action))) {
+      printMigrationAdvice();
+    }
+    return result;
   } catch (error) {
     commandError = error;
     throw error;
@@ -293,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);
@@ -319,12 +326,12 @@ function printHelp() {
 
 Usage:
   openxiangda version [--json]
-  openxiangda login <platform-url> [--profile name]
-  openxiangda update check|install [--json] [--registry https://registry.npmjs.org]
+  openxiangda login <platform-url> [--profile name] [--cwd directory]
+  openxiangda update check|install [--target workspace|launcher] [--json] [--registry https://registry.npmjs.org]
   openxiangda platform add <name> <platform-url>
   openxiangda platform list
   openxiangda platform use <name>
-  openxiangda auth status|refresh|logout [--profile name]
+  openxiangda auth status|refresh|logout [--profile name] [--cwd directory]
   openxiangda doctor [--profile name] [--app-type APP_XXX] [--release] [--json]
   openxiangda contract list|explain <contract-name> [--json]
   openxiangda policy show|check|render [--json]
@@ -383,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]
@@ -519,6 +527,7 @@ async function version(args) {
       atomicActivation: APP_FUNCTION_SECRET_CAPABILITIES.atomicActivation,
     },
     updateCheckCommand: 'openxiangda update check --json',
+    migrationAdvice: migrationAdvice(),
   };
   if (flags.json) return writeJson(result);
   print(CURRENT_VERSION);
@@ -529,7 +538,7 @@ async function update(args) {
   const parsedArgs = requestedSubcommand === args[0] ? args.slice(1) : args;
   const { flags } = parseArgs(parsedArgs);
   if (wantsSubcommandHelp(requestedSubcommand, flags)) {
-    print('用法: openxiangda update check|install [--json] [--registry https://registry.npmjs.org] [--timeout-seconds 300] [--no-skills]');
+    print('用法: openxiangda update check|install [--target workspace|launcher] [--json] [--registry https://registry.npmjs.org] [--timeout-seconds 300] [--no-skills]');
     return;
   }
   const registry = normalizeNpmRegistry(flags.registry || OFFICIAL_NPM_REGISTRY);
@@ -557,7 +566,7 @@ async function update(args) {
     return;
   }
 
-  fail('用法: openxiangda update check|install [--json] [--registry https://registry.npmjs.org] [--timeout-seconds 300] [--no-skills]');
+  fail('用法: openxiangda update check|install [--target workspace|launcher] [--json] [--registry https://registry.npmjs.org] [--timeout-seconds 300] [--no-skills]');
 }
 
 function normalizeNpmRegistry(value) {
@@ -586,6 +595,7 @@ function checkOpenXiangdaUpdate(registry, selection = resolveUpdateTarget()) {
     skillInstallCommand: 'openxiangda skill install',
     compatibilityCheckCommand: 'openxiangda commands --json',
     checkedAt: new Date().toISOString(),
+    migrationAdvice: migrationAdvice(),
     notes: [
       'Use the official npm registry for OpenXiangda updates; domestic mirrors may lag.',
       'After updating the package, refresh OpenXiangda skills so AI guidance matches the CLI version.',
@@ -766,6 +776,7 @@ async function installOpenXiangdaUpdate(registry, options = {}) {
     registry: plan.registry,
     installCommand: `npm ${npmArgs.join(' ')}`,
     installed: true,
+    migrationAdvice: migrationAdvice(),
     durationMs: installResult.durationMs,
     cacheMode: 'prefer-offline',
     timeoutSeconds: plan.timeoutSeconds,
@@ -9444,7 +9455,7 @@ async function platform(args) {
     print('用法: openxiangda platform add|list|use|remove');
     return;
   }
-  const config = loadConfig();
+  const config = loadConfig(flags.cwd || process.cwd(), { exact: Boolean(flags.cwd) });
 
   if (subcommand === 'prepare') {
     const result = prepareDependencyCapsule({
@@ -9549,10 +9560,10 @@ async function login(args) {
     positional[0] === '--help' ||
     positional[0] === '-h'
   ) {
-    print('用法: openxiangda login <platform-url> [--profile name] [--no-open] [--json]');
+    print('用法: openxiangda login <platform-url> [--profile name] [--cwd directory] [--no-open] [--json]');
     return;
   }
-  const config = loadConfig();
+  const config = loadConfig(flags.cwd || process.cwd(), { exact: Boolean(flags.cwd) });
   const rawUrl = positional[0];
   const profileName = flags.profile || config.currentProfile || 'default';
   let profile = config.profiles[profileName] || { name: profileName };
@@ -9567,7 +9578,7 @@ async function login(args) {
   }
 
   if (!profile.baseUrl) {
-    fail('缺少平台地址。用法: openxiangda login <platform-url> [--profile name]');
+    fail('缺少平台地址。用法: openxiangda login <platform-url> [--profile name] [--cwd directory]');
   }
 
   const sessionPayload = await requestJson(
@@ -9666,12 +9677,12 @@ async function auth(args) {
   const [subcommand, ...rest] = args;
   const { flags } = parseArgs(rest);
   if (wantsSubcommandHelp(subcommand, flags)) {
-    print('用法: openxiangda auth status|refresh|logout [--profile name] [--json]');
+    print('用法: openxiangda auth status|refresh|logout [--profile name] [--cwd directory] [--json]');
     return;
   }
 
   if (subcommand === 'status') {
-    const config = loadConfig();
+    const config = loadConfig(flags.cwd || process.cwd(), { exact: Boolean(flags.cwd) });
     const { profileName, profile } = getProfile(config, flags.profile);
     if (!profile.token?.accessToken) {
       print(`未登录: ${profileName} (${profile.baseUrl})`);
@@ -9689,7 +9700,7 @@ async function auth(args) {
   }
 
   if (subcommand === 'refresh') {
-    const config = loadConfig();
+    const config = loadConfig(flags.cwd || process.cwd(), { exact: Boolean(flags.cwd) });
     const profileName = flags.profile || config.currentProfile;
     if (!profileName) fail('未选择平台 profile');
     const data = await refreshProfile(config, profileName);
@@ -9700,7 +9711,7 @@ async function auth(args) {
   }
 
   if (subcommand === 'logout') {
-    const config = loadConfig();
+    const config = loadConfig(flags.cwd || process.cwd(), { exact: Boolean(flags.cwd) });
     const { profileName, profile } = getProfile(config, flags.profile);
     if (profile.token?.accessToken) {
       try {
@@ -9718,7 +9729,7 @@ async function auth(args) {
     return;
   }
 
-  fail('用法: openxiangda auth status|refresh|logout [--profile name]');
+  fail('用法: openxiangda auth status|refresh|logout [--profile name] [--cwd directory]');
 }
 
 async function env(args) {
@@ -9735,7 +9746,8 @@ async function env(args) {
   const currentState = profileName ? state.profiles?.[profileName] : null;
   const oss = summarizeOssEnv(globalEnv);
   const data = {
-    configFile: CONFIG_FILE,
+    configFile: getConfigFile(config),
+    sessionScope: 'workspace',
     globalEnvFile: GLOBAL_ENV_FILE,
     globalEnvExists: fs.existsSync(GLOBAL_ENV_FILE),
     projectStateFile: path.join(process.cwd(), PROJECT_STATE_FILE),
@@ -10198,7 +10210,9 @@ async function workspace(args) {
     printWorkspaceHelp();
     return;
   }
-  const config = loadConfig();
+  const config = subcommand === 'init'
+    ? loadConfig(path.resolve(positional[0] || process.cwd()), { exact: true })
+    : loadConfig();
 
   if (subcommand === 'ownership' || subcommand === 'owner') {
     const action = positional[0] || 'status';
@@ -10345,6 +10359,7 @@ async function workspace(args) {
         connectors: {},
         dataViews: {},
         storageConfigs: {},
+        webhooks: {},
         scopeDimensions: {},
         scopeGrantSources: {},
         dataScopePolicies: {},
@@ -12531,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);
@@ -17064,7 +17166,7 @@ async function commands(args) {
     commands: [
       'version [--json]',
       'login <platform-url> [--profile name]',
-      'update check|install',
+      'update check|install [--target workspace|launcher] [--json]',
       'platform add|list|use|remove',
       'auth status|refresh|logout',
       'doctor [--profile name] [--app-type APP_XXX] [--release]',
@@ -17085,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',
@@ -17107,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.',
@@ -17160,6 +17264,7 @@ async function skill(args) {
 
   if (subcommand === 'install') {
     const result = installSkills(options);
+    result.migrationAdvice = migrationAdvice();
     if (flags.json) return writeJson(result);
     printSkillInstallReport(result);
     return;
@@ -17178,6 +17283,7 @@ async function skill(args) {
       force: Boolean(flags.force),
       dryRun: Boolean(flags['dry-run']),
     });
+    result.migrationAdvice = migrationAdvice();
     if (flags.json) return writeJson(result);
     printSkillBootstrapReport(result);
     return;
@@ -17499,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'),
@@ -17518,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;
@@ -17840,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 || {};
@@ -18185,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'];
@@ -18333,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'] },
   {
@@ -18412,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'],
@@ -19124,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));
@@ -19148,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]',
     '',
@@ -19182,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,
@@ -19259,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();
@@ -20370,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);
@@ -22230,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(
@@ -22376,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',
@@ -22492,7 +22679,7 @@ function runGenericResourceGitBasePreflight({
         copyProjectState: true,
       },
       ({ buildRoot, buildEnv, tempRoot }) => {
-        const isolatedHome = prepareReadonlyGitBasePlanHome(tempRoot);
+        const isolatedHome = prepareReadonlyGitBasePlanHome(tempRoot, buildRoot);
         const childEnv = {
           ...buildEnv,
           HOME: isolatedHome,
@@ -22628,8 +22815,9 @@ function runGenericResourceGitBasePreflight({
   };
 }
 
-function prepareReadonlyGitBasePlanHome(tempRoot) {
-  if (!fs.existsSync(CONFIG_FILE)) {
+function prepareReadonlyGitBasePlanHome(tempRoot, buildRoot) {
+  const configSource = getConfigFile();
+  if (!fs.existsSync(configSource)) {
     const error = new Error(
       'SOURCE_BASE_PLAN_FAILED: 当前 profile 配置不存在，无法执行隔离 Git 基线 plan'
     );
@@ -22637,10 +22825,11 @@ function prepareReadonlyGitBasePlanHome(tempRoot) {
     throw error;
   }
   const home = path.join(tempRoot, 'plan-home');
-  const configDir = path.join(home, '.openxiangda');
+  const configDir = path.join(buildRoot, '.openxiangda');
+  fs.mkdirSync(home, { recursive: true, mode: 0o700 });
   const configFile = path.join(configDir, 'profiles.json');
   fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
-  fs.copyFileSync(CONFIG_FILE, configFile);
+  fs.copyFileSync(configSource, configFile);
   try {
     fs.chmodSync(configFile, 0o400);
   } catch {
@@ -22882,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(),
@@ -23108,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,
@@ -25099,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,
@@ -25263,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) {
@@ -25541,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,
@@ -25731,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)}`);
     }
@@ -26131,6 +26425,7 @@ function removeStateResource(target, kind, code) {
     publicAccessPolicy: 'publicAccessPolicies',
     dataView: 'dataViews',
     storageConfig: 'storageConfigs',
+    webhook: 'webhooks',
     pagePermissionGroup: 'pagePermissionGroups',
     formPermissionGroup: 'formPermissionGroups',
   };
@@ -26433,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,
@@ -26706,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 || []) {
@@ -27158,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 =
@@ -28305,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);