openxiangda 1.0.172 → 1.0.174

package/lib/cli.js

@@ -3,7 +3,7 @@ const path = require('path');
 const crypto = require('crypto');
 const os = require('os');
 const { builtinModules } = require('module');
-const { spawnSync } = require('child_process');
+const { spawn, spawnSync } = require('child_process');
 const { pathToFileURL } = require('url');
 const esbuild = require('esbuild');
 const {
@@ -20,6 +20,7 @@ const {
 } = require('./config');
 const { requestJson: rawRequestJson } = require('./http');
 const { runWorkspaceJsCodeBuildBatch } = require('./js-code-build');
+const { loadLocalFormSchema } = require('./form-schema-loader');
 const {
   buildGitBaseSourceArtifacts,
   canonicalJsonSha256,
@@ -63,6 +64,12 @@ const {
   inspectReleaseSourceIntegration,
   prepareReleaseSourceRevision,
 } = require('./release-mainline');
+const {
+  buildWorkspaceReleaseCommands,
+  buildWorkspaceReleaseSteps,
+  normalizeReleaseTargets,
+  releasePlanHash,
+} = require('./release-plan');
 const {
   analyzeManifestSourceDependencies,
   getImpactedResourceTargets,
@@ -221,7 +228,7 @@ Usage:
   openxiangda open-api credential list|get|create|update|rotate-secret [id] [--profile name] [--show-secret] [--yes] [--json]
   openxiangda design gates|template|review [--topic code] [--json]
   openxiangda sdd init|migrate|propose|quick|bundle|approve|status|context|verify|sync|archive [change] [--change id] [--json]
-  openxiangda release begin|status|integration-status|renew|end [--change id] [--profile name] [--json]
+  openxiangda release publish|begin|status|integration-status|renew|end [--change id] [--profile name] [--json]
   openxiangda release backend-head|backend-list|backend-detail|backend-diff|backend-rollback|backend-abort|backend-retry [releaseId] [--profile name] [--json]
   openxiangda release app-capture|app-head|app-list|app-detail|app-diff|app-prepare|app-verify|app-activate|app-finalize|app-rollback|app-abort [releaseId] [--staged-resources-json <JSON|file>] [--activate-staged-children] [--profile name] [--json]
   openxiangda env [--profile name]
@@ -729,9 +736,11 @@ async function sdd(args) {
     assertOrClaimWorktreeOwner({ cwd: process.cwd(), changeId });
     const result = createMainlineSddBundle({
       cwd: process.cwd(),
+      configText: readWorkspaceConfigText(),
       changeId,
       title: flags.title || flags.name,
       changes: flags.changes,
+      profile: flags.profile,
       force: Boolean(flags.force),
     });
     if (flags.json) return writeJson(result);
@@ -884,15 +893,639 @@ function parseSddAffectedFlags(flags) {
   };
 }
 
+function releaseExecutionDir(changeId) {
+  return path.join(
+    process.cwd(),
+    '.openxiangda',
+    'releases',
+    String(changeId || '').trim()
+  );
+}
+
+function releaseExecutionFile(changeId) {
+  return path.join(releaseExecutionDir(changeId), 'execution.json');
+}
+
+function writePrivateJsonAtomic(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tempFile = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tempFile, `${JSON.stringify(value, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  fs.renameSync(tempFile, file);
+}
+
+function readReleaseExecution(changeId) {
+  const file = releaseExecutionFile(changeId);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    fail(
+      `RELEASE_EXECUTION_INVALID: ${path.relative(process.cwd(), file)} 无法读取: ${error.message}`
+    );
+  }
+}
+
+function summarizeReleaseStepResult(result) {
+  const value =
+    result && typeof result === 'object' && !Array.isArray(result)
+      ? result
+      : {};
+  const findId = candidate =>
+    String(
+      candidate?.id ||
+        candidate?.releaseId ||
+        candidate?.activeAppReleaseId ||
+        ''
+    ).trim() || null;
+  return {
+    resultHash: canonicalJsonSha256(value),
+    releaseId:
+      findId(value.activated) ||
+      findId(value.verified) ||
+      findId(value.prepared) ||
+      findId(value),
+  };
+}
+
+function releaseExecutionContextFromBegin(result, target, changeId) {
+  const value =
+    result && typeof result === 'object' && !Array.isArray(result)
+      ? result
+      : {};
+  const releaseSourceRevision =
+    value.releaseSourceRevision &&
+    typeof value.releaseSourceRevision === 'object' &&
+    !Array.isArray(value.releaseSourceRevision)
+      ? value.releaseSourceRevision
+      : null;
+  if (
+    !value.leaseId ||
+    !value.clientSessionId ||
+    !releaseSourceRevision?.baseCommit
+  ) {
+    return null;
+  }
+  return {
+    appType: target.appType,
+    profile: target.profileName,
+    changeId,
+    leaseId: String(value.leaseId),
+    baselineId: value.baselineId ? String(value.baselineId) : null,
+    clientSessionId: String(value.clientSessionId),
+    releaseSourceRevision,
+    capturedAt: new Date().toISOString(),
+  };
+}
+
+function isDefinitelyPreWriteReleaseError(error) {
+  const code = String(error?.code || '');
+  if (new Set([
+    'RELEASE_PUBLISH_REVISION_CHANGED',
+    'RELEASE_SOURCE_DIRTY',
+    'RELEASE_SOURCE_BRANCH_REQUIRED',
+    'RELEASE_SOURCE_MAINLINE_REQUIRED',
+    'RELEASE_SOURCE_MAINLINE_NOT_PUSHED',
+    'RELEASE_SOURCE_BEHIND_MAIN',
+    'RELEASE_GIT_AUTH_REQUIRED',
+    'RELEASE_MAIN_BRANCH_UNRESOLVED',
+    'RELEASE_MAIN_REF_UNVERIFIED',
+    'SDD_PREPUBLISH_FAILED',
+    'PUBLISH_CONTEXT_REQUIRED',
+    'APP_RELEASE_STAGED_SCOPE_REQUIRED',
+    'APP_RELEASE_STAGED_SCOPE_MISMATCH',
+  ]).has(code)) {
+    return true;
+  }
+  return /^(?:SDD_|RELEASE_(?:SOURCE|GIT|MAINLINE|MAIN_BRANCH|MAIN_REF)|RUNTIME_(?:SOURCE|BUILD|PACKAGE|DEPENDENCY))/.test(
+    code
+  );
+}
+
+function parseChildJsonOutput(stdout) {
+  const text = String(stdout || '').trim();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    const lines = text.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+      const candidate = lines.slice(index).join('\n').trim();
+      if (!candidate.startsWith('{') && !candidate.startsWith('[')) continue;
+      try {
+        return JSON.parse(candidate);
+      } catch {
+        // Continue until the first complete JSON payload is found.
+      }
+    }
+    return { output: maskText(text).slice(-4000) };
+  }
+}
+
+function runOpenXiangdaChild(args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const bin = path.join(__dirname, '..', 'bin', 'openxiangda.js');
+    const child = spawn(process.execPath, [bin, ...args, '--json'], {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', chunk => {
+      stdout += String(chunk);
+    });
+    child.stderr.on('data', chunk => {
+      const text = String(chunk);
+      stderr += text;
+      if (!options.quiet) warn(maskText(text).trimEnd());
+    });
+    child.on('error', reject);
+    child.on('close', code => {
+      if (code === 0) {
+        resolve(parseChildJsonOutput(stdout));
+        return;
+      }
+      const message = maskText(
+        String(stderr || stdout || `openxiangda ${args.join(' ')} failed`)
+      ).trim();
+      const error = new Error(message);
+      error.code =
+        message.match(/\b([A-Z][A-Z0-9_]{3,})\b/)?.[1] ||
+        'RELEASE_STEP_FAILED';
+      error.exitCode = code;
+      reject(error);
+    });
+  });
+}
+
+function normalizeReleaseWaitSeconds(flags) {
+  const raw =
+    readStringFlag(flags, 'wait-seconds') ||
+    readStringFlag(flags, 'lease-wait-seconds');
+  if (raw === '') return 1800;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value < 0 || value > 86400) {
+    fail('--wait-seconds 必须是 0-86400 之间的秒数');
+  }
+  return Math.floor(value);
+}
+
+async function waitForPublishLeaseAvailability(config, target, flags = {}) {
+  if (getUsableStoredPublishLease(target)) return { waitedMs: 0 };
+  const waitSeconds = normalizeReleaseWaitSeconds(flags);
+  const startedAt = Date.now();
+  const deadline = startedAt + waitSeconds * 1000;
+  const clientSessionId = createPublishClientSessionId();
+  let attempts = 0;
+  while (true) {
+    const remote = await fetchPublishLeaseStatus(
+      config,
+      target,
+      clientSessionId
+    );
+    if (!remote?.active) {
+      return { waitedMs: Date.now() - startedAt, attempts, remote };
+    }
+    const remoteHolder =
+      (typeof remote?.holder === 'string' ? remote.holder : null) ||
+      remote?.holder?.changeId ||
+      remote?.changeId ||
+      remote?.holder?.clientSessionId ||
+      'another release';
+    if (Date.now() >= deadline) {
+      fail(
+        `PUBLISH_LEASE_WAIT_TIMEOUT: ${target.appType} 仍由 ${remoteHolder} 发布中；已等待 ${waitSeconds}s`
+      );
+    }
+    attempts += 1;
+    const suggestedSeconds = Number(
+      remote?.retryAfterSeconds || remote?.retryAfter || 5
+    );
+    const delayMs = Math.min(
+      Math.max(Number.isFinite(suggestedSeconds) ? suggestedSeconds * 1000 : 5000, 1000),
+      30000,
+      Math.max(1000, deadline - Date.now())
+    );
+    warn(
+      `发布队列等待中: app=${target.appType} holder=${remoteHolder} retry=${Math.ceil(delayMs / 1000)}s`
+    );
+    await sleep(delayMs);
+  }
+}
+
+function readReleaseRecoveryContext(target, changeId) {
+  if (!changeId) return null;
+  const execution = readReleaseExecution(changeId);
+  const context = execution?.releaseContext;
+  if (!context || typeof context !== 'object' || Array.isArray(context)) {
+    return null;
+  }
+  if (
+    context.appType !== target.appType ||
+    context.profile !== target.profileName ||
+    context.changeId !== changeId ||
+    !context.leaseId ||
+    !context.clientSessionId ||
+    !context.releaseSourceRevision
+  ) {
+    return null;
+  }
+  return { execution, context };
+}
+
+function remoteLeaseOwnedByRecovery(remote, recovery) {
+  if (!remote?.active || !recovery) return false;
+  const holder = remote.holder;
+  const holderIsSelf =
+    holder === 'self' ||
+    holder?.self === true ||
+    holder?.clientSessionId === recovery.clientSessionId;
+  return Boolean(
+    holderIsSelf &&
+      String(remote.leaseId || '') === String(recovery.leaseId) &&
+      String(remote.changeId || '') === String(recovery.changeId)
+  );
+}
+
+async function endReleaseWithoutLocalLease(
+  config,
+  target,
+  flags,
+  baseline
+) {
+  const changeId = readStringFlag(flags, 'change');
+  const recovered = readReleaseRecoveryContext(target, changeId);
+  const recovery = recovered?.context || null;
+  const clientSessionId =
+    recovery?.clientSessionId ||
+    baseline?.clientSessionId ||
+    createPublishClientSessionId();
+  const remote = await fetchPublishLeaseStatus(
+    config,
+    target,
+    clientSessionId
+  );
+  const sourceRevision =
+    baseline?.releaseSourceRevision ||
+    recovery?.releaseSourceRevision ||
+    null;
+
+  if (remote?.active) {
+    if (!recovery) {
+      fail(
+        `PUBLISH_LEASE_RECOVERY_REQUIRED: 远端仍有活动发布租约 ${remote.leaseId || '-'}；本地状态缺失，禁止误报 inactive。请使用原 change 的私有 execution.json 恢复，或等待租约过期后只读核对`
+      );
+    }
+    if (!remoteLeaseOwnedByRecovery(remote, recovery)) {
+      fail(
+        'PUBLISH_LEASE_RECOVERY_MISMATCH: 远端活动租约不属于当前 change/session；未释放任何租约'
+      );
+    }
+    const integration = assertReleaseSourceIntegrated(sourceRevision, {
+      cwd: process.cwd(),
+    });
+    const remoteResult = await requestWithAuth(
+      config,
+      target.profileName,
+      publishLeaseApiPath(
+        target,
+        `/${encodeURIComponent(recovery.leaseId)}/release`
+      ),
+      {
+        method: 'POST',
+        body: {
+          completion: 'mainline-integrated-recovered',
+          sourceCommit: integration.sourceCommit,
+          mainBranch: integration.mainBranch,
+          mainTipCommit: integration.mainTipCommit,
+        },
+      }
+    );
+    if (baseline) {
+      clearChangeBaseline(target, baseline.baselineId || baseline.id);
+    }
+    releaseWorktreeOwner({ cwd: process.cwd() });
+    recovered.execution.leaseReleasedAt = new Date().toISOString();
+    recovered.execution.leaseReleaseRecovered = true;
+    recovered.execution.updatedAt = recovered.execution.leaseReleasedAt;
+    writePrivateJsonAtomic(
+      releaseExecutionFile(changeId),
+      recovered.execution
+    );
+    return {
+      ...(remoteResult && typeof remoteResult === 'object'
+        ? remoteResult
+        : {}),
+      active: false,
+      appType: target.appType,
+      recovered: true,
+      integration,
+    };
+  }
+
+  const integration = sourceRevision
+    ? assertReleaseSourceIntegrated(sourceRevision, { cwd: process.cwd() })
+    : null;
+  if (baseline && !integration) {
+    fail(
+      'RELEASE_SOURCE_LINEAGE_REQUIRED: 本地仍有发布基线，但缺少可验证的 releaseSourceRevision；禁止无证据清理'
+    );
+  }
+  if (baseline) {
+    clearChangeBaseline(target, baseline.baselineId || baseline.id);
+  }
+  releaseWorktreeOwner({ cwd: process.cwd() });
+  return {
+    active: false,
+    appType: target.appType,
+    local: false,
+    remote,
+    recovered: false,
+    integration,
+  };
+}
+
+async function publishWorkspaceRelease(config, target, flags = {}) {
+  const changeId = readStringFlag(flags, 'change');
+  if (!changeId) {
+    fail('用法: openxiangda release publish --change <id> --profile <name>');
+  }
+  const plan = buildWorkspaceReleasePlan({
+    changed: true,
+    since: flags.since,
+    profile: target.profileName,
+    skipSdd: true,
+    changeId,
+    expandDependencies: Boolean(flags['expand-dependencies']),
+  });
+  if (plan.errors.length > 0) {
+    fail(
+      `RELEASE_PLAN_INVALID: ${plan.errors
+        .map(error => error.message || error.name)
+        .join('; ')}`
+    );
+  }
+  const steps = buildWorkspaceReleaseSteps(
+    plan.targets,
+    plan.workspace.runtimeMode,
+    target.profileName,
+    changeId
+  );
+  const planHash = releasePlanHash({
+    schemaVersion: 'openxiangda_release_execution_v1',
+    appType: target.appType,
+    profile: target.profileName,
+    changeId,
+    runtimeMode: plan.workspace.runtimeMode,
+    targets: plan.activationTargets,
+    commands: steps.map(step => step.command),
+  });
+  if (flags['dry-run']) {
+    return {
+      dryRun: true,
+      appType: target.appType,
+      profile: target.profileName,
+      changeId,
+      planHash,
+      targets: plan.targets,
+      activationTargets: plan.activationTargets,
+      steps,
+    };
+  }
+  const verification = verifySddChange({
+    cwd: process.cwd(),
+    changeId,
+    releasePlan: {
+      ...plan,
+      commands: steps.map(step => step.command),
+    },
+    writeMetadata: true,
+    stage: 'prepublish',
+  });
+  if (!verification.passed) {
+    fail(
+      `SDD_PREPUBLISH_FAILED: ${verification.errors
+        .map(error => error.message)
+        .join('; ')}`
+    );
+  }
+  if (steps.length === 0) {
+    return {
+      completed: true,
+      noOp: true,
+      appType: target.appType,
+      profile: target.profileName,
+      changeId,
+      planHash,
+      execution: null,
+    };
+  }
+  const existing = readReleaseExecution(changeId);
+  if (
+    existing &&
+    (existing.planHash !== planHash ||
+      existing.appType !== target.appType ||
+      existing.profile !== target.profileName)
+  ) {
+    fail(
+      'RELEASE_EXECUTION_PLAN_CHANGED: 已存在不同计划的执行日志；请先完成或人工核对旧发布，禁止静默覆盖'
+    );
+  }
+  if (
+    existing?.status === 'write-review-required' &&
+    !flags['resume-after-review']
+  ) {
+    fail(
+      'RELEASE_WRITE_REVIEW_REQUIRED: 上次写请求结果不确定；请先只读核对 staged release，确认可重试后追加 --resume-after-review'
+    );
+  }
+  const now = new Date().toISOString();
+  const execution = existing || {
+    schemaVersion: 'openxiangda_release_execution_v1',
+    appType: target.appType,
+    profile: target.profileName,
+    changeId,
+    planHash,
+    status: 'planned',
+    createdAt: now,
+    updatedAt: now,
+    stagedWriteOccurred: false,
+    writeAttempted: false,
+    steps: [
+      {
+        id: 'lease-and-capture',
+        command: `openxiangda release begin --change ${changeId} --profile ${target.profileName} --freeze-app-capture`,
+        status: 'pending',
+      },
+      ...steps.map(step => ({
+        id: step.id,
+        command: step.command,
+        stagedKind: step.stagedKind,
+        status: 'pending',
+      })),
+      {
+        id: 'release-lease',
+        command: `openxiangda release end --change ${changeId} --profile ${target.profileName}`,
+        status: 'pending',
+      },
+    ],
+  };
+  if (execution.status === 'completed') {
+    return {
+      completed: true,
+      resumed: true,
+      appType: target.appType,
+      profile: target.profileName,
+      changeId,
+      planHash,
+      executionFile: path
+        .relative(process.cwd(), releaseExecutionFile(changeId))
+        .replace(/\\/g, '/'),
+      execution,
+    };
+  }
+  execution.status = 'running';
+  execution.updatedAt = new Date().toISOString();
+  writePrivateJsonAtomic(releaseExecutionFile(changeId), execution);
+
+  const runnable = [
+    {
+      id: 'lease-and-capture',
+      args: [
+        'release',
+        'begin',
+        '--change',
+        changeId,
+        '--profile',
+        target.profileName,
+        '--freeze-app-capture',
+      ],
+    },
+    ...steps,
+    {
+      id: 'release-lease',
+      args: [
+        'release',
+        'end',
+        '--change',
+        changeId,
+        '--profile',
+        target.profileName,
+      ],
+    },
+  ];
+  try {
+    for (const step of runnable) {
+      const journalStep = execution.steps.find(item => item.id === step.id);
+      if (journalStep?.status === 'completed') continue;
+      if (step.id === 'lease-and-capture') {
+        await waitForPublishLeaseAvailability(config, target, flags);
+      }
+      journalStep.status = 'running';
+      journalStep.startedAt = new Date().toISOString();
+      execution.updatedAt = journalStep.startedAt;
+      writePrivateJsonAtomic(releaseExecutionFile(changeId), execution);
+      warn(`发布步骤开始: ${step.id}`);
+      const result = await runOpenXiangdaChild(step.args);
+      journalStep.status = 'completed';
+      journalStep.completedAt = new Date().toISOString();
+      journalStep.result = summarizeReleaseStepResult(result);
+      if (step.id === 'lease-and-capture') {
+        execution.releaseContext = releaseExecutionContextFromBegin(
+          result,
+          target,
+          changeId
+        );
+      }
+      if (
+        step.id !== 'lease-and-capture' &&
+        step.id !== 'release-lease' &&
+        step.writes !== false
+      ) {
+        execution.writeAttempted = true;
+      }
+      if (step.stagedKind) execution.stagedWriteOccurred = true;
+      execution.updatedAt = journalStep.completedAt;
+      writePrivateJsonAtomic(releaseExecutionFile(changeId), execution);
+    }
+    execution.status = 'completed';
+    execution.completedAt = new Date().toISOString();
+    execution.updatedAt = execution.completedAt;
+    writePrivateJsonAtomic(releaseExecutionFile(changeId), execution);
+    return {
+      completed: true,
+      resumed: Boolean(existing),
+      appType: target.appType,
+      profile: target.profileName,
+      changeId,
+      planHash,
+      executionFile: path
+        .relative(process.cwd(), releaseExecutionFile(changeId))
+        .replace(/\\/g, '/'),
+      execution,
+    };
+  } catch (error) {
+    const runningStep = execution.steps.find(step => step.status === 'running');
+    if (runningStep) {
+      runningStep.status = 'failed';
+      runningStep.failedAt = new Date().toISOString();
+      runningStep.error = {
+        code: error.code || 'RELEASE_STEP_FAILED',
+        message: maskText(error.message).slice(0, 1000),
+      };
+      const runningDefinition = runnable.find(
+        step => step.id === runningStep.id
+      );
+      if (
+        runningDefinition &&
+        runningDefinition.id !== 'lease-and-capture' &&
+        runningDefinition.id !== 'release-lease' &&
+        runningDefinition.writes !== false &&
+        !isDefinitelyPreWriteReleaseError(error)
+      ) {
+        execution.writeAttempted = true;
+      }
+    }
+    execution.status = execution.stagedWriteOccurred
+      ? 'staged-resumable'
+      : execution.writeAttempted
+        ? 'write-review-required'
+        : 'failed';
+    execution.updatedAt = new Date().toISOString();
+    writePrivateJsonAtomic(releaseExecutionFile(changeId), execution);
+    if (!execution.writeAttempted) {
+      try {
+        await runOpenXiangdaChild(
+          [
+            'release',
+            'end',
+            '--change',
+            changeId,
+            '--profile',
+            target.profileName,
+          ],
+          { quiet: true }
+        );
+      } catch {
+        // The original error remains authoritative; lease cleanup is best effort.
+      }
+    }
+    throw error;
+  }
+}
+
 async function release(args) {
   const { subcommand, rest } = parseSubcommandArgs(args);
   const { flags, positional } = parseArgs(rest);
   if (wantsSubcommandHelp(subcommand, flags)) {
     print([
-      '用法: openxiangda release begin|status|integration-status|renew|end [--change id] [--profile name] [--json]',
+      '用法: openxiangda release publish|begin|status|integration-status|renew|end [--change id] [--profile name] [--json]',
       '      openxiangda release backend-head|backend-list|backend-detail|backend-diff|backend-rollback|backend-abort|backend-retry [releaseId] [--profile name] [--json]',
       '      openxiangda release app-capture|app-head|app-list|app-detail|app-diff|app-prepare|app-verify|app-activate|app-finalize|app-rollback|app-abort [releaseId] [--staged-resources-json <JSON|file>] [--activate-staged-children] [--profile name] [--json]',
       '常用流程:',
+      '  openxiangda release publish --change <id> --profile <name>',
       '  openxiangda release begin --change <id> --profile <name>',
       '  openxiangda resource publish function --only <code> --change <id> --profile <name>',
       '  openxiangda runtime deploy --change <id> --profile <name>',
@@ -903,6 +1536,8 @@ async function release(args) {
       '  openxiangda release backend-rollback <releaseId> --change <id> --reason "..." --profile <name>',
       '  openxiangda release app-finalize --change <id> --staged-resources-json <JSON|file> --profile <name>',
       '说明:',
+      '  - publish 默认等待租约并按私有执行日志恢复；上次写结果不确定时必须只读核对后显式 --resume-after-review。',
+      '  - app-head 默认只输出紧凑 head 摘要；需要完整 manifest 时显式追加 --full。',
       '  - begin 获取应用级单写者 promotion lease；不同工作区仍可并行开发和验证。',
       '  - 带 --change 的 resource/runtime 写命令在没有本地 lease 时会自动 begin，并在后续命令复用。',
       '  - 子 Runtime/Page/Backend/Form Release 默认先 stage；app-finalize 用 --staged-resources-json 覆盖 capture 中的 changed children，并在同一事务中原子激活。',
@@ -941,6 +1576,16 @@ async function release(args) {
       flags
     );
   }
+  if (subcommand === 'publish') {
+    const result = await publishWorkspaceRelease(config, target, flags);
+    if (flags.json) return writeJson(result);
+    print(
+      result.dryRun
+        ? `发布计划已生成（未写入）: ${result.changeId} steps=${result.steps.length}`
+        : `应用原子发布完成: ${result.appType} change=${result.changeId}`
+    );
+    return;
+  }
   const leaseIdFromArgs = positional[0] || readStringFlag(flags, 'lease-id');
 
   if (subcommand === 'status') {
@@ -1040,15 +1685,56 @@ async function release(args) {
       throw error;
     }
     const finalizedBaseline = finalizeReleaseBaseline(target, baseline);
-    const stagedResourcesFile = newReleaseLifecycle
-      ? initializeStagedAppReleaseResources(target, changeId)
-      : null;
+    let frozenCapture = null;
+    let releaseSessionFile = null;
+    let stagedResourcesFile = null;
+    try {
+      if (flags['freeze-app-capture']) {
+        frozenCapture = await fetchAppReleaseCapture(config, target, flags);
+        releaseSessionFile = saveFrozenAppReleaseCapture(
+          target,
+          changeId,
+          finalizedBaseline,
+          lease,
+          frozenCapture
+        );
+      }
+      stagedResourcesFile = newReleaseLifecycle
+        ? initializeStagedAppReleaseResources(target, changeId)
+        : null;
+    } catch (error) {
+      if (newReleaseLifecycle) {
+        try {
+          await requestWithAuth(
+            config,
+            target.profileName,
+            publishLeaseApiPath(
+              target,
+              `/${encodeURIComponent(lease.leaseId)}/release`
+            ),
+            { method: 'POST', body: { completion: 'local-prepare-failed' } }
+          );
+        } catch {
+          // Preserve the local preparation failure as the primary error.
+        }
+        clearPublishLease(target, lease.leaseId);
+        clearChangeBaseline(target, finalizedBaseline?.baselineId);
+        releaseWorktreeOwner({ cwd: process.cwd() });
+      }
+      throw error;
+    }
     const result = {
       ...lease,
       baselineId: finalizedBaseline?.baselineId,
       baselineHeadDigest: finalizedBaseline?.headDigest,
       sourceBase: finalizedBaseline?.sourceBase,
       releaseSourceRevision: finalizedBaseline?.releaseSourceRevision,
+      ...(frozenCapture
+        ? {
+            captureHash: frozenCapture.captureHash,
+            releaseSessionFile,
+          }
+        : {}),
       ...(stagedResourcesFile ? { stagedResourcesFile } : {}),
     };
     if (flags.json) return writeJson(result);
@@ -1119,34 +1805,22 @@ async function release(args) {
       return;
     }
     if (!leaseIdFromArgs) assertLocalPublishLeaseOwnership(stored);
-    assertOrClaimWorktreeOwner({
-      cwd: process.cwd(),
-      changeId: stored?.changeId || readStringFlag(flags, 'change') || 'unscoped-publish',
-    });
     const leaseId = leaseIdFromArgs || stored?.leaseId;
     if (!leaseId) {
-      const integration = baseline?.releaseSourceRevision
-        ? assertReleaseSourceIntegrated(baseline.releaseSourceRevision, {
-            cwd: process.cwd(),
-          })
-        : null;
-      if (baseline && !integration) {
-        fail(
-          'RELEASE_SOURCE_LINEAGE_REQUIRED: 本地仍有发布基线，但缺少可验证的 releaseSourceRevision；禁止无证据清理'
-        );
-      }
-      const result = {
-        active: false,
-        appType: target.appType,
-        local: false,
-        integration,
-      };
-      if (baseline) clearChangeBaseline(target, baseline.baselineId);
-      releaseWorktreeOwner({ cwd: process.cwd() });
+      const result = await endReleaseWithoutLocalLease(
+        config,
+        target,
+        flags,
+        baseline
+      );
       if (flags.json) return writeJson(result);
       print(`当前工作区没有活动发布租约: ${target.appType}`);
       return;
     }
+    assertOrClaimWorktreeOwner({
+      cwd: process.cwd(),
+      changeId: stored?.changeId || readStringFlag(flags, 'change') || 'unscoped-publish',
+    });
     const integration = assertReleaseSourceIntegrated(
       baseline?.releaseSourceRevision,
       { cwd: process.cwd() }
@@ -1191,7 +1865,7 @@ async function release(args) {
     }
   }
 
-  fail('用法: openxiangda release begin|status|integration-status|renew|end|backend-*|app-* [--change id] [--profile name]');
+  fail('用法: openxiangda release publish|begin|status|integration-status|renew|end|backend-*|app-* [--change id] [--profile name]');
 }
 
 async function fetchPublishLeaseStatus(config, target, clientSessionId) {
@@ -1460,6 +2134,74 @@ async function fetchAppReleaseCapture(config, target, flags = {}) {
   return clonePlainJson(capture);
 }
 
+function releaseSessionFile(changeId) {
+  return path.join(releaseExecutionDir(changeId), 'release-session.json');
+}
+
+function saveFrozenAppReleaseCapture(
+  target,
+  changeId,
+  baseline,
+  lease,
+  capture
+) {
+  const file = releaseSessionFile(changeId);
+  writePrivateJsonAtomic(file, {
+    schemaVersion: 'openxiangda_release_session_v1',
+    appType: target.appType,
+    profile: target.profileName,
+    changeId,
+    baselineId: baseline?.baselineId || baseline?.id || null,
+    leaseId: lease?.leaseId || lease?.id || null,
+    sourceRevision: baseline?.releaseSourceRevision || null,
+    capturedAt: new Date().toISOString(),
+    capture,
+  });
+  return path.relative(process.cwd(), file).replace(/\\/g, '/');
+}
+
+function readFrozenAppReleaseCapture(target, flags = {}) {
+  const changeId = readStringFlag(flags, 'change');
+  if (!changeId) return null;
+  const file = releaseSessionFile(changeId);
+  if (!fs.existsSync(file)) return null;
+  let session;
+  try {
+    session = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    fail(`RELEASE_SESSION_INVALID: ${error.message}`);
+  }
+  if (
+    session?.schemaVersion !== 'openxiangda_release_session_v1' ||
+    session?.appType !== target.appType ||
+    session?.profile !== target.profileName ||
+    session?.changeId !== changeId
+  ) {
+    fail(
+      'RELEASE_SESSION_CONTEXT_MISMATCH: 冻结的 App capture 与当前 app/profile/change 不一致'
+    );
+  }
+  const capture = session.capture;
+  if (
+    !capture ||
+    !Array.isArray(capture.resources) ||
+    !/^[a-f0-9]{64}$/i.test(String(capture.captureHash || ''))
+  ) {
+    fail('RELEASE_SESSION_CAPTURE_INVALID: 冻结的 App capture 不完整');
+  }
+  const expectedCaptureHash = readStringFlag(flags, 'expected-capture-hash');
+  if (
+    expectedCaptureHash &&
+    expectedCaptureHash.toLowerCase() !==
+      String(capture.captureHash).toLowerCase()
+  ) {
+    fail(
+      `APP_RELEASE_CAPTURE_MOVED: 期望 capture ${expectedCaptureHash}，冻结为 ${capture.captureHash}`
+    );
+  }
+  return clonePlainJson(capture);
+}
+
 function appReleaseWriteBody(releaseContext, extra = {}) {
   return {
     ...releaseContext.control,
@@ -1790,7 +2532,13 @@ function assertStagedAppReleaseScope(target, flags, resources) {
     }
     throw error;
   }
-  const targets = scope.targets || {};
+  const runtimeMode = getWorkspaceRuntimeModeFromConfig(
+    readWorkspaceConfigText()
+  );
+  const { activationTargets: targets } = normalizeReleaseTargets(
+    scope.targets || {},
+    runtimeMode
+  );
   const normalized = normalizeStagedAppReleaseResources(resources);
   const byKind = kind => normalized.filter(resource => resource.kind === kind);
   const expectedBackendSelectors = [
@@ -1873,8 +2621,15 @@ function changedAppReleaseResources(detailResources, captureResources) {
 }
 
 function assertAppReleaseActualGate(target, flags, scope, command) {
+  const runtimeMode = getWorkspaceRuntimeModeFromConfig(
+    readWorkspaceConfigText()
+  );
+  const normalized = normalizeReleaseTargets(
+    scope.targets || {},
+    runtimeMode
+  );
   assertSddReleaseGate(
-    buildExplicitSddReleasePlan(scope.targets, {
+    buildExplicitSddReleasePlan(normalized.activationTargets, {
       files: scope.changedFiles || [],
       commands: [command],
       changeId: scope.changeId,
@@ -2042,6 +2797,70 @@ async function activateAppReleaseDetail(
   );
 }
 
+function summarizeAppReleaseHead(data) {
+  const value =
+    data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+  const release =
+    value.release &&
+    typeof value.release === 'object' &&
+    !Array.isArray(value.release)
+      ? value.release
+      : {};
+  const manifest =
+    release.manifestJson &&
+    typeof release.manifestJson === 'object'
+      ? release.manifestJson
+      : value.manifestJson &&
+          typeof value.manifestJson === 'object'
+        ? value.manifestJson
+        : {};
+  const resources = Array.isArray(manifest.resources)
+    ? manifest.resources
+    : Array.isArray(value.resources)
+      ? value.resources
+      : [];
+  const resourcesByKind = Object.fromEntries(
+    Array.from(
+      resources.reduce((counts, resource) => {
+        const kind = String(resource?.kind || 'Unknown');
+        counts.set(kind, (counts.get(kind) || 0) + 1);
+        return counts;
+      }, new Map())
+    ).sort(([left], [right]) => left.localeCompare(right))
+  );
+  const compactRelease = {};
+  for (const key of [
+    'id',
+    'status',
+    'parentReleaseId',
+    'manifestHash',
+    'verificationHash',
+    'protocolVersion',
+    'createdAt',
+    'updatedAt',
+    'activatedAt',
+  ]) {
+    if (release[key] !== undefined) compactRelease[key] = release[key];
+  }
+  return {
+    appType: value.appType,
+    activeAppReleaseId:
+      value.activeAppReleaseId || release.id || null,
+    ...(value.activeRuntimeReleaseId
+      ? { activeRuntimeReleaseId: value.activeRuntimeReleaseId }
+      : {}),
+    ...(value.activePageReleaseId
+      ? { activePageReleaseId: value.activePageReleaseId }
+      : {}),
+    ...(value.activeBackendReleaseId
+      ? { activeBackendReleaseId: value.activeBackendReleaseId }
+      : {}),
+    release: compactRelease,
+    resourceCount: resources.length,
+    resourcesByKind,
+  };
+}
+
 async function runAppReleaseCommand(
   config,
   target,
@@ -2059,6 +2878,7 @@ async function runAppReleaseCommand(
       target.profileName,
       appReleaseApiPath(target, '/head')
     );
+    if (!flags.full) data = summarizeAppReleaseHead(data);
   } else if (subcommand === 'app-list') {
     data = await requestWithAuth(
       config,
@@ -2236,7 +3056,9 @@ async function runAppReleaseCommand(
       flags,
       'App Release finalize'
     );
-    const capture = await fetchAppReleaseCapture(config, target, flags);
+    const capture =
+      readFrozenAppReleaseCapture(target, flags) ||
+      (await fetchAppReleaseCapture(config, target, flags));
     const frozenResources = overlayAppReleaseResources(
       capture.resources,
       stagedResources
@@ -8761,6 +9583,9 @@ async function resource(args) {
     fail('resource publish --only/--code 不能与 --prune 同时使用，避免删除未选中的资源');
   }
   const manifest = loadWorkspaceResources({ typeFilters, codeFilters });
+  if (subcommand !== 'typegen') {
+    await attachLocalFormSchemas(manifest);
+  }
   if (
     subcommand === 'plan' &&
     process.env.OPENXIANGDA_GIT_BASE_RESOURCE_PLAN === '1'
@@ -9560,12 +10385,23 @@ async function runtime(args) {
 }
 
 async function loadRuntimeHeadApp(config, target) {
-  const snapshot = await requestWithAuth(
-    config,
-    target.profileName,
-    `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/snapshot`
-  );
-  return snapshot?.app || snapshot?.application || snapshot || {};
+  try {
+    return (
+      (await requestWithAuth(
+        config,
+        target.profileName,
+        `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/runtime/releases/head`
+      )) || {}
+    );
+  } catch (error) {
+    if (!isHttpNotFound(error)) throw error;
+    const snapshot = await requestWithAuth(
+      config,
+      target.profileName,
+      `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/snapshot`
+    );
+    return snapshot?.app || snapshot?.application || snapshot || {};
+  }
 }
 
 function assertRuntimeSourceRevisionStable(beforeBuild, afterBuild) {
@@ -10180,7 +11016,7 @@ async function commands(args) {
       'open-api credential list|get|create|update|rotate-secret [id]',
       'design gates|template|review [--topic code]',
       'sdd init|migrate|propose|quick|bundle|approve|status|context|verify|sync|archive',
-      'release begin|status|integration-status|renew|end|backend-head|backend-list|backend-detail|backend-diff|backend-rollback|backend-abort|backend-retry|app-capture|app-head|app-list|app-detail|app-diff|app-prepare|app-verify|app-activate|app-finalize|app-rollback|app-abort',
+      'release publish|begin|status|integration-status|renew|end|backend-head|backend-list|backend-detail|backend-diff|backend-rollback|backend-abort|backend-retry|app-capture|app-head|app-list|app-detail|app-diff|app-prepare|app-verify|app-activate|app-finalize|app-rollback|app-abort',
       'env',
       'workspace init|bind|plan|check|publish [--app-name] [--changed|--since|--form|--page|--only|--dry-run|--force|--resources|--skip-resources|--prune]',
       'app list|create|snapshot',
@@ -11646,6 +12482,84 @@ function loadWorkspaceResources(options = {}) {
   return manifest;
 }
 
+async function attachLocalFormSchemas(manifest) {
+  if (
+    Array.isArray(manifest.resourceTypeFilters) &&
+    !manifest.resourceTypeFilters.includes('formSettings')
+  ) {
+    return manifest;
+  }
+  const selectors = Array.isArray(manifest.__resourceCodeSelectors)
+    ? manifest.__resourceCodeSelectors.filter(selector =>
+        resourceCodeSelectorAppliesToKey(selector, 'formSettings')
+      )
+    : [];
+  const candidateCodes = unique([
+    ...(manifest.formSettings || []).map(getResourceItemCode),
+    ...selectors.map(selector => selector.code),
+  ]).filter(Boolean);
+  if (candidateCodes.length === 0) return manifest;
+
+  const loadedCodes = new Set();
+  for (const code of candidateCodes) {
+    let localSchema;
+    try {
+      localSchema = await loadLocalFormSchema(process.cwd(), code);
+    } catch (error) {
+      const wrapped = new Error(
+        `FORM_SCHEMA_LOAD_FAILED: ${code}: ${error.message}`
+      );
+      wrapped.code = 'FORM_SCHEMA_LOAD_FAILED';
+      throw wrapped;
+    }
+    if (!localSchema) continue;
+    loadedCodes.add(code);
+    const existing = (manifest.formSettings || []).find(
+      item => getResourceItemCode(item) === code
+    );
+    const merged = {
+      ...(existing || {}),
+      code,
+      formCode: existing?.formCode || code,
+      name: existing?.name ?? localSchema.name,
+      schema: localSchema.schema,
+      packages: localSchema.packages,
+      formType: existing?.formType ?? localSchema.formType,
+      __source: existing?.__source || path.join(
+        process.cwd(),
+        localSchema.sourcePath
+      ),
+      __dir: existing?.__dir || path.dirname(
+        path.join(process.cwd(), localSchema.sourcePath)
+      ),
+      __localSchema: {
+        sourcePath: localSchema.sourcePath,
+        fieldCount: localSchema.fieldCount,
+      },
+    };
+    if (existing) {
+      Object.assign(existing, merged);
+    } else {
+      manifest.formSettings = manifest.formSettings || [];
+      manifest.formSettings.push(merged);
+    }
+  }
+  manifest.formSettings = (manifest.formSettings || []).sort((left, right) =>
+    getResourceItemCode(left).localeCompare(getResourceItemCode(right))
+  );
+  if (
+    loadedCodes.size > 0 &&
+    Array.isArray(manifest.unmatchedResourceCodeFilters)
+  ) {
+    manifest.unmatchedResourceCodeFilters =
+      manifest.unmatchedResourceCodeFilters.filter(raw => {
+        const code = String(raw || '').replace(/^.*[:/]/, '');
+        return !loadedCodes.has(code);
+      });
+  }
+  return manifest;
+}
+
 function readResourceItems(baseDir, spec, options = {}) {
   const items = [];
   const selectorEntries = options.selectorEntries || null;
@@ -20593,6 +21507,16 @@ function getWorkspaceImpactedResourceTargets(files) {
   return getImpactedResourceTargets(getWorkspaceSourceDependencyIndex(), files);
 }
 
+function scopeNeedsBackendDependencyAnalysis(scope) {
+  const targets = scope?.targets || {};
+  return (
+    Boolean(targets.resources) ||
+    ['functions', 'automations', 'workflows', 'jsCodeNodes'].some(
+      key => (targets[key] || []).length > 0
+    )
+  );
+}
+
 function addCodeResourceTargetFromPath(targets, file, prefix, key, options = {}) {
   if (!file.startsWith(prefix)) return false;
   const rest = file.slice(prefix.length);
@@ -20890,8 +21814,11 @@ function fileBelongsToChangeScope(file, scope, runtimeMode) {
 
 function getChangeScopedWorkspaceFiles(changeScope, runtimeMode, options = {}) {
   const dirtyFiles = getWorkspaceChangedFiles({ since: options.since });
-  const dependencyIndex = getWorkspaceSourceDependencyIndex();
+  const dependencyIndex = scopeNeedsBackendDependencyAnalysis(changeScope)
+    ? getWorkspaceSourceDependencyIndex()
+    : null;
   const dependencyBelongsToScope = file => {
+    if (!dependencyIndex) return false;
     const impacted = getImpactedResourceTargets(dependencyIndex, [file]);
     return ['functions', 'automations', 'workflows', 'jsCodeNodes'].some(key =>
       (impacted[key] || []).some(code => scopeIncludesCode(changeScope.targets?.[key], code))
@@ -20986,87 +21913,6 @@ function scanWorkspaceReliabilityIssues(files) {
   return issues;
 }
 
-function buildTargetedResourceReleaseCommands(targets, profileArg, changeId) {
-  const changeArg = changeId ? ` --change ${changeId}` : '';
-  const commands = [];
-  const functions = targets.functions || [];
-  const automations = targets.automations || [];
-  if (functions.length > 0 || automations.length > 0) {
-    const resourceTypes = [
-      ...(functions.length > 0 ? ['function'] : []),
-      ...(automations.length > 0 ? ['automation'] : []),
-    ];
-    const qualify = resourceTypes.length > 1;
-    const selectors = [
-      ...functions.map(code => (qualify ? `function:${code}` : code)),
-      ...automations.map(code => (qualify ? `automation:${code}` : code)),
-    ];
-    commands.push(
-      `openxiangda resource publish ${resourceTypes.join(',')} --only ${selectors.join(',')} --stage-only --profile ${profileArg}${changeArg}`
-    );
-  }
-  const workflows = targets.workflows || [];
-  if (workflows.length > 0) {
-    commands.push(
-      `openxiangda resource publish workflow --only ${workflows.join(',')} --profile ${profileArg}${changeArg}`
-    );
-  }
-  return commands;
-}
-
-function buildWorkspaceReleaseCommands(targets, runtimeMode, profile, changeId) {
-  const profileArg = profile || '<profile>';
-  const commands = [];
-  const hasResourceTargets =
-    Boolean(targets.resources) ||
-    (targets.functions || []).length > 0 ||
-    (targets.automations || []).length > 0 ||
-    (targets.workflows || []).length > 0 ||
-    (targets.jsCodeNodes || []).length > 0;
-  if (runtimeMode === 'react-spa') {
-    if (targets.forms.length > 0) {
-      commands.push(
-        `openxiangda resource publish form-setting --only ${targets.forms.join(',')} --profile ${profileArg}${changeId ? ` --change ${changeId}` : ''}`
-      );
-    }
-    if (hasResourceTargets) {
-      commands.push(...buildTargetedResourceReleaseCommands(targets, profileArg, changeId));
-    }
-    if (targets.runtime) {
-      commands.push(
-        `openxiangda runtime deploy --no-activate --profile ${profileArg}${changeId ? ` --change ${changeId}` : ''}`
-      );
-    }
-    if (
-      targets.forms.length > 0 ||
-      (targets.functions || []).length > 0 ||
-      (targets.automations || []).length > 0 ||
-      targets.runtime
-    ) {
-      commands.push(
-        `openxiangda release app-finalize --staged-resources-json .openxiangda/releases/${changeId || 'change'}/staged-resources.json --profile ${profileArg}${changeId ? ` --change ${changeId}` : ''}`
-      );
-    }
-    return commands;
-  }
-
-  const onlyTargets = [
-    ...targets.forms.map(code => `forms/${code}`),
-    ...targets.pages.map(code => `pages/${code}`),
-  ];
-  if (onlyTargets.length > 0) {
-    commands.push(
-      `openxiangda workspace publish --profile ${profileArg} --only ${onlyTargets.join(',')} --skip-resources${
-        changeId ? ` --change ${changeId}` : ''
-      }`
-    );
-  }
-  if (hasResourceTargets) {
-    commands.push(...buildTargetedResourceReleaseCommands(targets, profileArg, changeId));
-  }
-  return commands;
-}
-
 function buildWorkspaceReleasePlan(options = {}) {
   const configText = readWorkspaceConfigText();
   const runtimeMode = getWorkspaceRuntimeModeFromConfig(configText);
@@ -21095,7 +21941,7 @@ function buildWorkspaceReleasePlan(options = {}) {
         baseRef: options.since || 'HEAD',
       });
   let dependencyImpact = {};
-  if (changeScope) {
+  if (changeScope && scopeNeedsBackendDependencyAnalysis(changeScope)) {
     const dependencyTargets = getWorkspaceImpactedResourceTargets(files);
     dependencyImpact = Object.fromEntries(
       ['functions', 'automations', 'workflows', 'jsCodeNodes'].map(key => [
@@ -21110,9 +21956,17 @@ function buildWorkspaceReleasePlan(options = {}) {
     // dozens of unrelated resources. Callers may opt in when the intended
     // change genuinely requires the whole dependency closure.
     if (options.expandDependencies) {
-    for (const key of ['functions', 'automations', 'workflows', 'jsCodeNodes']) {
-      targets[key] = unique([...(targets[key] || []), ...(dependencyTargets[key] || [])]).sort();
-    }
+      for (const key of [
+        'functions',
+        'automations',
+        'workflows',
+        'jsCodeNodes',
+      ]) {
+        targets[key] = unique([
+          ...(targets[key] || []),
+          ...(dependencyTargets[key] || []),
+        ]).sort();
+      }
     }
   }
   if (options.includeResources) targets.resources = true;
@@ -21138,6 +21992,10 @@ function buildWorkspaceReleasePlan(options = {}) {
       name: issue.rule,
       message: `${issue.file}:${issue.line} ${issue.message}`,
     }));
+  const normalizedReleaseTargets = normalizeReleaseTargets(
+    targets,
+    runtimeMode
+  );
   const generatedCommands = buildWorkspaceReleaseCommands(
     targets,
     runtimeMode,
@@ -21226,6 +22084,7 @@ function buildWorkspaceReleasePlan(options = {}) {
     since: options.changed ? options.since || undefined : undefined,
     changedFiles: changeScope || options.changed ? files : undefined,
     targets,
+    activationTargets: normalizedReleaseTargets.activationTargets,
     publishOrder:
       runtimeMode === 'react-spa'
         ? ['forms', 'resources', 'runtime']