openxiangda 1.0.197 → 1.0.199

package/lib/cli.js

@@ -130,6 +130,7 @@ const { buildDesignReview, renderDesignReview } = require('./design-review');
 const {
   bindEnvironmentTarget,
   buildCandidateBundle,
+  buildSideEffectPolicyDiff,
   isRecoverablePostActivationDeploymentError,
   normalizeEnvironmentKind,
   normalizeManagedChangeSourceBase,
@@ -299,9 +300,9 @@ 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 environment init|attach|bind|swap|list|status|diff|use [preproduction|production] [--logical-app code] [--environment target] [--json]
+  openxiangda environment init|attach|bind|swap|policy update|list|status|diff|use [preproduction|production] [--logical-app code] [--environment target] [--json]
   openxiangda release publish|begin|status|integration-status|renew|end [--change id] [--profile name] [--watch] [--json]
-  openxiangda release candidate|deploy|test|promote|rollback [--candidate id] [--environment target] [--json]
+  openxiangda release ship|candidate|deploy|test|promote|rollback [--candidate id] [--environment target] [--json]
   openxiangda task status --change <id> [--profile name] [--watch] [--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]
@@ -384,6 +385,7 @@ const SUBCOMMAND_BOOLEAN_FLAGS = new Set([
   '--dry-run',
   '--enabled',
   '--force',
+  '--full-replace',
   '--help',
   '--include-sourcemaps',
   '--json',
@@ -1065,6 +1067,41 @@ function directPublishReceiptFile(changeId) {
   return path.join(releaseExecutionDir(changeId), 'direct-publish.json');
 }
 
+function managedShipFile(changeId) {
+  return path.join(releaseExecutionDir(changeId), 'ship.json');
+}
+
+function readManagedShip(changeId) {
+  const file = managedShipFile(changeId);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    fail(
+      `MANAGED_SHIP_INVALID: ${path.relative(process.cwd(), file)} 无法读取: ${error.message}`
+    );
+  }
+}
+
+function writeManagedShip(changeId, value) {
+  const existing = readManagedShip(changeId);
+  const now = new Date().toISOString();
+  const record = {
+    schemaVersion: 'openxiangda_managed_ship_v1',
+    changeId,
+    createdAt: existing?.createdAt || now,
+    ...(existing || {}),
+    ...value,
+    updatedAt: now,
+  };
+  const file = managedShipFile(changeId);
+  writePrivateJsonAtomic(file, record);
+  return {
+    record,
+    file: path.relative(process.cwd(), file).replace(/\\/g, '/'),
+  };
+}
+
 function writePrivateJsonAtomic(file, value) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const tempFile = `${file}.${process.pid}.${Date.now()}.tmp`;
@@ -1542,22 +1579,30 @@ async function publishWorkspaceRelease(config, target, flags = {}) {
       cwd: process.cwd(),
     });
   }
-  const verification = verifySddChange({
-    cwd: process.cwd(),
-    changeId,
-    releasePlan: {
-      ...plan,
-      commands: steps.map(step => step.command),
-    },
-    writeMetadata: false,
-    stage: 'prepublish',
-  });
-  if (!verification.passed) {
-    fail(
-      `SDD_PREPUBLISH_FAILED: ${verification.errors
-        .map(error => error.message)
-        .join('; ')}`
+  const verifiedByCandidate =
+    flags.__verifiedCandidate &&
+    assertCandidatePrepublishVerification(
+      flags.__verifiedCandidate,
+      plan
     );
+  if (!verifiedByCandidate) {
+    const verification = verifySddChange({
+      cwd: process.cwd(),
+      changeId,
+      releasePlan: {
+        ...plan,
+        commands: steps.map(step => step.command),
+      },
+      writeMetadata: false,
+      stage: 'prepublish',
+    });
+    if (!verification.passed) {
+      fail(
+        `SDD_PREPUBLISH_FAILED: ${verification.errors
+          .map(error => error.message)
+          .join('; ')}`
+      );
+    }
   }
   if (steps.length === 0) {
     return {
@@ -1877,6 +1922,7 @@ function saveEnvironmentWorkspaceState(state, setDetail, environmentDetail, inpu
     displayName: environmentDetail.displayName,
     publicOrigin: environmentDetail.publicOrigin,
     sideEffectPolicy: environmentDetail.sideEffectPolicy,
+    revision: environmentDetail.revision,
     seedResources,
     replaceResources: input.replaceResources,
     seedAppScopedState: input.seedAppScopedState,
@@ -1896,6 +1942,7 @@ async function environment(args) {
       '      openxiangda environment attach --logical-app <code> [--preproduction-target name] [--production-target name] [--profile name]',
       '      openxiangda environment bind preproduction|production --app-type APP_XXX [--target name] [--profile name]',
       '      openxiangda environment swap --reason <text> --confirm-production [--preproduction-side-effect-policy-json <JSON|file>] [--production-side-effect-policy-json <JSON|file>] [--profile name]',
+      '      openxiangda environment policy update preproduction|production --side-effect-policy-json <JSON|file> --reason <text> [--dry-run] [--full-replace] [--confirm-production] [--profile name]',
       '      openxiangda environment list|status|diff [--logical-app code] [--profile name] [--json]',
       '      openxiangda environment use <target|preproduction|production>',
     ].join('\n'));
@@ -2056,6 +2103,133 @@ async function environment(args) {
     Object.values(state.targets || {})[0]?.profile ||
     config.currentProfile;
 
+  if (subcommand === 'policy') {
+    if (positional[0] !== 'update') {
+      fail(
+        '用法: openxiangda environment policy update preproduction|production --side-effect-policy-json <JSON|file> --reason <text> [--dry-run]',
+      );
+    }
+    const selector = positional[1] || flags.environment || flags.target;
+    if (!selector) {
+      fail('environment policy update 必须指定环境 kind、id 或本地 target');
+    }
+    const reason = readStringFlag(flags, 'reason');
+    if (!reason || reason.length < 10) {
+      fail('environment policy update 必须提供至少 10 个字符的 --reason');
+    }
+    const policySource = readStringFlag(flags, 'side-effect-policy-json');
+    if (!policySource) {
+      fail('environment policy update 必须提供 --side-effect-policy-json');
+    }
+    const profile = getProfile(config, selectedProfile);
+    const setDetail = await requestWithAuth(
+      config,
+      profile.profileName,
+      environmentSetApiPath(code),
+    );
+    const localTarget = state.targets?.[selector];
+    const environmentSelector = localTarget?.environmentId || selector;
+    const matches = (setDetail.environments || []).filter(
+      item =>
+        item.id === environmentSelector || item.kind === environmentSelector,
+    );
+    if (matches.length !== 1) {
+      fail(`应用环境不存在或不唯一: ${selector}`);
+    }
+    const environmentDetail = matches[0];
+    const explicitExpectedRevision = readStringFlag(
+      flags,
+      'expected-revision',
+    );
+    const expectedRevision = explicitExpectedRevision
+      ? Number(explicitExpectedRevision)
+      : Number(environmentDetail.revision);
+    if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 1) {
+      fail('environment policy update 缺少有效的环境 revision');
+    }
+    const policyUpdate = readJsonInput(
+      policySource,
+      'side-effect-policy-json',
+    );
+    const diff = buildSideEffectPolicyDiff(
+      environmentDetail.sideEffectPolicy || {},
+      policyUpdate,
+      { fullReplace: Boolean(flags['full-replace']) },
+    );
+    const preview = {
+      logicalApp: {
+        id: setDetail.id,
+        code: setDetail.code,
+      },
+      environment: {
+        id: environmentDetail.id,
+        kind: environmentDetail.kind,
+        appType: environmentDetail.appType,
+        revision: environmentDetail.revision,
+      },
+      expectedRevision,
+      reason,
+      dryRun: Boolean(flags['dry-run']),
+      ...diff,
+    };
+    if (flags['dry-run'] || !diff.changed) {
+      if (flags.json) return writeJson(preview);
+      print(JSON.stringify(preview, null, 2));
+      return;
+    }
+    if (
+      environmentDetail.kind === 'production' &&
+      !flags['confirm-production']
+    ) {
+      fail(
+        'environment policy update 正式环境写入必须提供 --confirm-production；--dry-run 不需要',
+      );
+    }
+    const data = await requestWithAuth(
+      config,
+      profile.profileName,
+      environmentSetApiPath(
+        code,
+        `/environments/${encodeURIComponent(environmentDetail.id)}/policy`,
+      ),
+      {
+        method: 'POST',
+        body: {
+          expectedRevision,
+          sideEffectPolicy: policyUpdate,
+          reason,
+          fullReplace: Boolean(flags['full-replace']),
+          confirmProduction: Boolean(flags['confirm-production']),
+        },
+      },
+    );
+    const previousTarget = Object.values(state.targets || {}).find(
+      target => target.environmentId === environmentDetail.id,
+    );
+    const updatedTarget = saveEnvironmentWorkspaceState(
+      state,
+      setDetail,
+      data.environment,
+      {
+        targetName:
+          previousTarget?.targetName ||
+          localTarget?.targetName ||
+          data.environment.kind,
+        profile: previousTarget?.profile || profile.profileName,
+      },
+    );
+    const result = {
+      ...preview,
+      dryRun: false,
+      environment: data.environment,
+      audit: data.audit,
+      target: updatedTarget,
+    };
+    if (flags.json) return writeJson(result);
+    print(JSON.stringify(result, null, 2));
+    return;
+  }
+
   if (subcommand === 'swap') {
     if (!flags['confirm-production']) {
       fail(
@@ -2197,7 +2371,7 @@ async function environment(args) {
     return;
   }
 
-  fail('用法: openxiangda environment init|attach|bind|swap|list|status|diff|use');
+  fail('用法: openxiangda environment init|attach|bind|swap|policy update|list|status|diff|use');
 }
 
 function buildEnvironmentStatusDiff(status) {
@@ -2564,6 +2738,65 @@ function assertLocalCandidate(candidate) {
   return candidate;
 }
 
+function candidateReleasePlanFingerprint(plan) {
+  return sha256Canonical({
+    schemaVersion: 'openxiangda_candidate_release_plan_v1',
+    runtimeMode: plan.workspace.runtimeMode,
+    targets: plan.activationTargets,
+    files: unique(plan.changedFiles || []).sort(),
+    commands: plan.commands || [],
+  });
+}
+
+function buildCandidatePrepublishVerification(
+  changeId,
+  sourceRevision,
+  plan
+) {
+  const payload = {
+    schemaVersion: 'openxiangda_candidate_prepublish_v1',
+    stage: 'prepublish',
+    passed: true,
+    changeId,
+    sourceRevisionHash: sha256Canonical(sourceRevision),
+    releasePlanFingerprint: candidateReleasePlanFingerprint(plan),
+  };
+  return {
+    ...payload,
+    verificationHash: sha256Canonical(payload),
+  };
+}
+
+function assertCandidatePrepublishVerification(candidate, plan) {
+  const attestation = candidate?.prepublishVerification;
+  if (
+    !attestation ||
+    attestation.schemaVersion !==
+      'openxiangda_candidate_prepublish_v1' ||
+    attestation.stage !== 'prepublish' ||
+    attestation.passed !== true
+  ) {
+    return false;
+  }
+  const { verificationHash, ...payload } = attestation;
+  if (
+    !verificationHash ||
+    sha256Canonical(payload) !== verificationHash ||
+    candidate.sourceBundleManifest?.prepublishVerificationHash !==
+      verificationHash ||
+    payload.changeId !== candidate.changeId ||
+    payload.sourceRevisionHash !==
+      sha256Canonical(candidate.sourceRevision) ||
+    payload.releasePlanFingerprint !==
+      candidateReleasePlanFingerprint(plan)
+  ) {
+    fail(
+      'CANDIDATE_PREPUBLISH_ATTESTATION_INVALID: candidate 的预发布校验凭证与当前主线计划不一致'
+    );
+  }
+  return true;
+}
+
 async function createApplicationCandidate(config, target, flags, positional) {
   const logicalApp = requireLogicalApplication(target);
   const changeId =
@@ -2605,6 +2838,12 @@ async function createApplicationCandidate(config, target, flags, positional) {
         .join('; ')}`
     );
   }
+  const prepublishVerification =
+    buildCandidatePrepublishVerification(
+      changeId,
+      sourceRevision,
+      plan
+    );
   const testPlan = flags['test-plan-json']
     ? readJsonInput(flags['test-plan-json'], 'test-plan-json')
     : undefined;
@@ -2617,6 +2856,8 @@ async function createApplicationCandidate(config, target, flags, positional) {
     targets: plan.activationTargets,
     files: plan.changedFiles,
     testPlan,
+    prepublishVerificationHash:
+      prepublishVerification.verificationHash,
     openxiangdaVersion: CURRENT_VERSION,
   });
   const data = await requestWithAuth(
@@ -2645,6 +2886,7 @@ async function createApplicationCandidate(config, target, flags, positional) {
     sourceBundleManifest: bundle.sourceBundleManifest,
     testPlan: bundle.testPlan,
     releasePlan: plan,
+    prepublishVerification,
     savedAt: new Date().toISOString(),
   };
   const file = saveCandidate(localCandidate);
@@ -2722,6 +2964,7 @@ async function deployApplicationCandidate(
       environment: target.targetName,
       'candidate-id': candidate.id,
       'deployment-id': deployment.id,
+      __verifiedCandidate: candidate,
     });
     const detail = await requestWithAuth(
       config,
@@ -2797,6 +3040,299 @@ function buildBoundDeploymentEvidence(input, target, deployment, candidate) {
   };
 }
 
+function managedShipTestPlan() {
+  return {
+    schemaVersion: 1,
+    requiredGates: [
+      'preproductionDeployment',
+      'cleanup',
+    ],
+    maximumEvidenceAgeHours: 24,
+    policy: 'fast_explicit_confirmation_v1',
+  };
+}
+
+function managedEnvironmentTarget(config, state, kind) {
+  const selected = resolveEnvironmentTarget(state, kind);
+  return getWorkspaceTarget(
+    config,
+    selected.binding.profile,
+    { environment: selected.targetName }
+  );
+}
+
+async function readManagedDeployment(
+  config,
+  target,
+  logicalAppCode,
+  deploymentId
+) {
+  const deployment = await requestWithAuth(
+    config,
+    target.profileName,
+    applicationDeploymentApiPath(
+      logicalAppCode,
+      deploymentId
+    )
+  );
+  rememberTargetDeployment(target, deployment);
+  return deployment;
+}
+
+async function runApplicationShipCommand(
+  config,
+  initialTarget,
+  positional,
+  flags
+) {
+  const changeId =
+    readStringFlag(flags, 'change') || positional[0];
+  if (!changeId) {
+    fail(
+      '用法: openxiangda release ship --change <id> [--confirm-production] [--acceptance-note "..."]'
+    );
+  }
+  const logicalApp = requireLogicalApplication(initialTarget);
+  const preproduction = managedEnvironmentTarget(
+    config,
+    initialTarget.state,
+    'preproduction'
+  );
+  const production = managedEnvironmentTarget(
+    config,
+    initialTarget.state,
+    'production'
+  );
+  const existingShip = readManagedShip(changeId);
+  const confirmProduction = Boolean(flags['confirm-production']);
+
+  if (confirmProduction && !existingShip?.preproductionDeploymentId) {
+    fail(
+      'PREPRODUCTION_PHASE_REQUIRED: 必须先单独执行 release ship 完成预发部署；确认预发结果后再携带 --confirm-production'
+    );
+  }
+
+  if (!confirmProduction) {
+    let candidate = existingShip?.candidateId
+      ? readCandidate(existingShip.candidateId)
+      : null;
+    if (!candidate) {
+      const created = await createApplicationCandidate(
+        config,
+        preproduction,
+        {
+          ...flags,
+          change: changeId,
+          'test-plan-json': JSON.stringify(
+            managedShipTestPlan()
+          ),
+        },
+        [changeId]
+      );
+      candidate = created.candidate;
+      writeManagedShip(changeId, {
+        status: 'candidate_created',
+        candidateId: candidate.id,
+        candidateHash: candidate.candidateHash,
+        sourceRevision: candidate.sourceRevision,
+        candidateFile: created.candidateFile,
+      });
+    } else {
+      assertLocalCandidate(candidate);
+    }
+
+    let deployment = null;
+    if (existingShip?.preproductionDeploymentId) {
+      deployment = await readManagedDeployment(
+        config,
+        preproduction,
+        logicalApp.code,
+        existingShip.preproductionDeploymentId
+      );
+    }
+    if (
+      !deployment ||
+      !['deployed', 'succeeded'].includes(deployment.status)
+    ) {
+      const deployed = await deployApplicationCandidate(
+        config,
+        preproduction,
+        candidate,
+        { kind: 'deploy', flags }
+      );
+      deployment = deployed.deployment;
+    }
+    const saved = writeManagedShip(changeId, {
+      status: 'awaiting_production_confirmation',
+      candidateId: candidate.id,
+      candidateHash: candidate.candidateHash,
+      sourceRevision: candidate.sourceRevision,
+      preproductionEnvironment: preproduction.targetName,
+      preproductionDeploymentId: deployment.id,
+      preproductionAppReleaseId:
+        deployment.targetAppReleaseId || null,
+      preproductionStatus: deployment.status,
+      preparedAt:
+        existingShip?.preparedAt ||
+        new Date().toISOString(),
+      nextCommand:
+        `openxiangda release ship --change ${changeId} ` +
+        '--confirm-production',
+    });
+    return {
+      phase: 'preproduction',
+      status: 'awaiting_production_confirmation',
+      candidate,
+      deployment,
+      automaticPromotion: false,
+      manualAcceptanceRecommended: true,
+      manualAcceptanceRequired: false,
+      shipFile: saved.file,
+      nextCommand: saved.record.nextCommand,
+    };
+  }
+
+  const acceptanceNote = readStringFlag(
+    flags,
+    'acceptance-note'
+  );
+  const candidate = readCandidate(existingShip.candidateId);
+  assertLocalCandidate(candidate);
+  let preproductionDeployment = await readManagedDeployment(
+    config,
+    preproduction,
+    logicalApp.code,
+    existingShip.preproductionDeploymentId
+  );
+  if (
+    !['deployed', 'succeeded'].includes(
+      preproductionDeployment.status
+    ) ||
+    !preproductionDeployment.targetAppReleaseId
+  ) {
+    fail(
+      `PREPRODUCTION_NOT_READY_FOR_ACCEPTANCE: 预发 deployment ${preproductionDeployment.id} 当前状态为 ${preproductionDeployment.status}`
+    );
+  }
+
+  const confirmedAt = new Date().toISOString();
+  const manualAcceptance = acceptanceNote
+    ? {
+        status: 'passed',
+        note: acceptanceNote,
+        acceptedAt: confirmedAt,
+      }
+    : null;
+  if (preproductionDeployment.status !== 'succeeded') {
+    const suppliedEvidence = flags['evidence-json']
+      ? readJsonInput(flags['evidence-json'], 'evidence-json')
+      : {};
+    const requiredGates =
+      candidate.testPlan?.requiredGates ||
+      managedShipTestPlan().requiredGates;
+    const evidence = buildBoundDeploymentEvidence(
+      {
+        ...suppliedEvidence,
+        requiredGates,
+        results: {
+          ...(suppliedEvidence.results || {}),
+          preproductionDeployment: {
+            status: 'passed',
+            appReleaseId:
+              preproductionDeployment.targetAppReleaseId,
+          },
+          productionConfirmation: {
+            status: 'passed',
+            confirmedAt,
+            note: acceptanceNote || null,
+          },
+          cleanup: {
+            status: 'passed',
+            residueCount: 0,
+            reason:
+              'release ship does not create test business data',
+          },
+        },
+        cleanup: {
+          passed: true,
+          residueCount: 0,
+          reason:
+            'release ship does not create test business data',
+        },
+        ...(manualAcceptance
+          ? { manualAcceptance }
+          : {}),
+      },
+      preproduction,
+      preproductionDeployment,
+      candidate
+    );
+    preproductionDeployment = await requestWithAuth(
+      config,
+      preproduction.profileName,
+      applicationDeploymentApiPath(
+        logicalApp.code,
+        preproductionDeployment.id,
+        'complete'
+      ),
+      {
+        method: 'POST',
+        body: {
+          evidenceSummary: evidence,
+          evidenceHash: sha256Canonical(evidence),
+        },
+      }
+    );
+    rememberTargetDeployment(
+      preproduction,
+      preproductionDeployment
+    );
+  }
+
+  writeManagedShip(changeId, {
+    status: 'confirmed_for_production',
+    productionConfirmation: {
+      confirmedAt,
+      profile: preproduction.profileName,
+      acceptanceNote: acceptanceNote || null,
+    },
+    manualAcceptance,
+    preproductionStatus: preproductionDeployment.status,
+  });
+  const promoted = await deployApplicationCandidate(
+    config,
+    production,
+    candidate,
+    {
+      kind: 'promotion',
+      sourceEnvironmentId:
+        preproduction.environmentId,
+      flags,
+    }
+  );
+  const saved = writeManagedShip(changeId, {
+    status: 'completed',
+    productionEnvironment: production.targetName,
+    productionDeploymentId: promoted.deployment.id,
+    productionAppReleaseId:
+      promoted.deployment.targetAppReleaseId || null,
+    productionStatus: promoted.deployment.status,
+    completedAt: new Date().toISOString(),
+  });
+  return {
+    phase: 'production',
+    status: 'completed',
+    candidate,
+    preproductionDeployment,
+    productionDeployment: promoted.deployment,
+    productionConfirmation:
+      saved.record.productionConfirmation,
+    manualAcceptance: saved.record.manualAcceptance,
+    sameCandidate: true,
+    shipFile: saved.file,
+  };
+}
+
 async function runApplicationEnvironmentReleaseCommand(
   config,
   target,
@@ -2805,6 +3341,14 @@ async function runApplicationEnvironmentReleaseCommand(
   flags
 ) {
   const logicalApp = requireLogicalApplication(target);
+  if (subcommand === 'ship') {
+    return await runApplicationShipCommand(
+      config,
+      target,
+      positional,
+      flags
+    );
+  }
   if (subcommand === 'candidate') {
     return await createApplicationCandidate(
       config,
@@ -2976,10 +3520,13 @@ async function release(args) {
   if (wantsSubcommandHelp(subcommand, flags)) {
     print([
       '用法: openxiangda release publish|begin|status|explain|integration-status|renew|end [--change id] [--profile name] [--json]',
-      '      openxiangda release candidate|deploy|reconcile|test|promote|rollback [--candidate id] [--environment target] [--confirm-production] [--json]',
+      '      openxiangda release ship|candidate|deploy|reconcile|test|promote|rollback [--candidate id] [--environment target] [--confirm-production] [--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-post-commit|app-retry|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 ship --change <id> --profile <name>',
+      '  # 确认预发结果后；可选 --acceptance-note 留下人工验收记录：',
+      '  openxiangda release ship --change <id> --profile <name> --confirm-production',
       '  openxiangda release publish --change <id> --profile <name>',
       '  openxiangda release begin --change <id> --profile <name>',
       '  openxiangda resource publish function --only <code> --change <id> --profile <name>',
@@ -2991,6 +3538,7 @@ 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>',
       '说明:',
+      '  - ship 是环境托管应用的两段式快车道：首次只部署预发并停止；确认预发结果后，第二次以同一 candidate 晋级正式。人工验收备注可选。',
       '  - publish 默认等待租约并按私有执行日志恢复；上次写结果不确定时必须只读核对后显式 --resume-after-review。',
       '  - app-head 默认只输出紧凑 head 摘要；需要完整 manifest 时显式追加 --full。',
       '  - begin 获取应用级单写者 promotion lease；不同工作区仍可并行开发和验证。',
@@ -3014,7 +3562,7 @@ async function release(args) {
     flags
   );
   if (
-    ['candidate', 'deploy', 'reconcile', 'test', 'promote', 'rollback'].includes(
+    ['ship', 'candidate', 'deploy', 'reconcile', 'test', 'promote', 'rollback'].includes(
       subcommand
     )
   ) {
@@ -4349,7 +4897,7 @@ function recordSatisfiedAppReleaseSelectors(changeId, selectors, target) {
     changeId,
     target.deploymentId
   );
-  const context = assertStagedResourcesContext(target, changeId);
+  assertStagedResourcesContext(target, changeId);
   const satisfiedSelectors = normalizeSatisfiedAppReleaseSelectors([
     ...(context.satisfiedSelectors || []),
     ...incoming,
@@ -7702,7 +8250,7 @@ async function form(args) {
   const { flags, positional } = parseArgs(rest);
   if (wantsSubcommandHelp(subcommand, flags)) {
     print([
-      '用法: openxiangda form list|create|bind|pull|export|publish|schema-plan [--profile name] [--json]',
+      '用法: openxiangda form list|create|ensure|bind|pull|export|publish|schema-plan [--profile name] [--json]',
       'Form Release: release-head|release-list|release-detail|release-diff|release-activate|release-rollback|release-abort',
       '配置写会先冻结 snapshot，并携带 If-Match、expectedRevision、expectedParent；冲突后不会自动重放。',
     ].join('\n'));
@@ -7735,6 +8283,108 @@ async function form(args) {
     return;
   }
 
+  if (subcommand === 'ensure') {
+    const requested = unique(
+      [
+        flags.only,
+        flags.code,
+        flags.codes,
+        ...positional,
+      ]
+        .filter(Boolean)
+        .flatMap(value => String(value).split(','))
+        .map(value => value.trim())
+        .filter(Boolean)
+    ).sort();
+    if (requested.length === 0) {
+      fail('用法: openxiangda form ensure --only <formCode1,formCode2>');
+    }
+    const target = getWorkspaceTarget(config, profileName, flags);
+    await ensureDirectMutationPublishContext(
+      config,
+      target,
+      flags,
+      'form ensure'
+    );
+    const results = [];
+    for (const formCode of requested) {
+      const existing = [
+        target.bound.resources?.forms?.[formCode],
+        target.bound.resources?.formSettings?.[formCode],
+      ].find(entry => String(entry?.formUuid || '').trim());
+      if (existing?.formUuid) {
+        results.push({
+          code: formCode,
+          formUuid: existing.formUuid,
+          action: 'noop',
+        });
+        continue;
+      }
+      const localSchema = await loadLocalFormSchema(
+        process.cwd(),
+        formCode
+      );
+      if (!localSchema) {
+        fail(
+          `FORM_ENSURE_SCHEMA_REQUIRED: ${formCode} 缺少 src/forms/${formCode}/schema.ts`
+        );
+      }
+      const formUuid = managedFormUuidForCode(
+        target.appType,
+        formCode
+      );
+      let existingRemote = null;
+      try {
+        existingRemote = await requestWithAuth(
+          config,
+          target.profileName,
+          `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/forms/${encodeURIComponent(formUuid)}`
+        );
+      } catch (error) {
+        if (!isHttpNotFound(error)) throw error;
+      }
+      if (!existingRemote) {
+        await requestWithAuth(
+          config,
+          target.profileName,
+          `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/forms`,
+          {
+            method: 'POST',
+            headers: { 'if-match': '0' },
+            body: {
+              name: localSchema.name || formCode,
+              formType: localSchema.formType || 'receipt',
+              formUuid,
+              createMenu: false,
+              expectedRevision: 0,
+            },
+          }
+        );
+      }
+      saveFormResource(target, formCode, formUuid, {
+        name: localSchema.name || formCode,
+      });
+      results.push({
+        code: formCode,
+        formUuid,
+        action: existingRemote ? 'bind' : 'create',
+      });
+    }
+    const result = {
+      appType: target.appType,
+      profile: target.profileName,
+      forms: results,
+      summary: {
+        create: results.filter(item => item.action === 'create').length,
+        bind: results.filter(item => item.action === 'bind').length,
+        noop: results.filter(item => item.action === 'noop').length,
+      },
+    };
+    if (flags.json) return writeJson(result);
+    print(JSON.stringify(result, null, 2));
+    return;
+  }
+
   if (subcommand === 'create') {
     const [formCode] = positional;
     const name = flags.name || positional.slice(1).join(' ') || formCode;
@@ -7978,7 +8628,28 @@ async function form(args) {
     return outputFormResult(data, flags);
   }
 
-  fail('用法: openxiangda form list|create|bind|pull|export|publish|schema-plan|release-head|release-list|release-detail|release-diff|release-activate|release-rollback|release-abort');
+  fail('用法: openxiangda form list|create|ensure|bind|pull|export|publish|schema-plan|release-head|release-list|release-detail|release-diff|release-activate|release-rollback|release-abort');
+}
+
+function managedFormUuidForCode(appType, formCode) {
+  const hex = crypto
+    .createHash('sha256')
+    .update(`openxiangda-managed-form-v1\0${appType}\0${formCode}`)
+    .digest('hex')
+    .slice(0, 32)
+    .split('');
+  hex[12] = '5';
+  hex[16] = ['8', '9', 'a', 'b'][
+    Number.parseInt(hex[16], 16) % 4
+  ];
+  const value = hex.join('');
+  return [
+    value.slice(0, 8),
+    value.slice(8, 12),
+    value.slice(12, 16),
+    value.slice(16, 20),
+    value.slice(20),
+  ].join('-');
 }
 
 function pageApiPath(target, suffix = '') {
@@ -11842,7 +12513,7 @@ async function resource(args) {
     );
     try {
       const plan = await telemetry.runPhase('plan', async () =>
-        buildResourcePlan(config, target, manifest)
+        buildResourcePlan(config, target, manifest, { flags })
       );
       if (dryRun) {
         plan.dryRun = true;
@@ -11860,7 +12531,7 @@ async function resource(args) {
   const telemetry = createCliReleaseTelemetry('resource publish');
   try {
     const publishPlan = await telemetry.runPhase('plan', async () =>
-      buildResourcePlan(config, target, manifest)
+      buildResourcePlan(config, target, manifest, { flags })
     );
     if (publishPlan.functionSecretRefs?.valid === false) {
       const missing = publishPlan.functionSecretRefs.functions
@@ -13407,13 +14078,13 @@ 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',
-      'environment init|attach|bind|swap|list|status|diff|use',
-      'release candidate|deploy|test|promote|rollback|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',
+      'environment init|attach|bind|swap|policy update|list|status|diff|use',
+      'release ship|candidate|deploy|test|promote|rollback|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',
       'studio [--no-open] [--port 0]',
       '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',
-      'form list|create|bind|pull|export|publish|schema-plan|release-head|release-list|release-detail|release-diff|release-activate|release-rollback|release-abort',
+      'form list|create|ensure|bind|pull|export|publish|schema-plan|release-head|release-list|release-detail|release-diff|release-activate|release-rollback|release-abort',
       'page list|publish|bind|head|releases|detail|diff|activate|rollback',
       'menu list|create|update|sort|bind|delete',
       'workflow compile|list|create|bind|pull|publish|delete|validate',
@@ -16523,7 +17194,12 @@ async function publishResourcesForWorkspace(config, profileName, options = {}) {
   return result;
 }
 
-async function buildResourcePlan(config, target, manifest) {
+async function buildResourcePlan(
+  config,
+  target,
+  manifest,
+  options = {}
+) {
   return await withReadOnlyHttpGuard('resource plan', async () => {
   const secretCapabilities = await assertManifestAppFunctionSecretCapabilities(
     config,
@@ -16531,9 +17207,16 @@ async function buildResourcePlan(config, target, manifest) {
     manifest
   );
   await prepareManifestJsCodeBundlesForPlan(manifest);
+  const stagedLocalFormSnapshots =
+    await resolveStagedLocalFormContractSnapshots(
+      target,
+      options.flags || {}
+    );
   const [existing, formFieldContracts] = await Promise.all([
     fetchExistingResourceMaps(config, target, manifest),
-    buildFormFieldContractPlan(config, target, manifest),
+    buildFormFieldContractPlan(config, target, manifest, {
+      stagedLocalFormSnapshots,
+    }),
   ]);
   const actions = [];
   addPlanActions(actions, 'role', manifest.roles, existing.roles, roleEquals);
@@ -24482,15 +25165,23 @@ function changedResourceCodesForFile(file, spec, baseRef = 'HEAD') {
   const codes = unique([...current.keys(), ...base.keys()]).filter(
     code => current.get(code) !== base.get(code)
   );
-  if (codes.length > 0) return codes.sort();
+  if (codes.length > 0) {
+    return {
+      codes: codes.sort(),
+      deletedCodes: codes
+        .filter(code => base.has(code) && !current.has(code))
+        .sort(),
+    };
+  }
   if (currentItems.some(item => item?.__invalid) || baseItems.some(item => item?.__invalid)) {
-    return ['*'];
+    return { codes: ['*'], deletedCodes: [] };
   }
-  return [];
+  return { codes: [], deletedCodes: [] };
 }
 
 function classifyGenericResourceFiles(files, baseRef = 'HEAD') {
   const resourceSelectors = {};
+  const resourceDeletes = {};
   const formSettings = new Set();
   const unknown = new Set();
   const codeResourceKeys = new Set([
@@ -24506,7 +25197,8 @@ function classifyGenericResourceFiles(files, baseRef = 'HEAD') {
       continue;
     }
     if (codeResourceKeys.has(spec.key)) continue;
-    const codes = changedResourceCodesForFile(file, spec, baseRef);
+    const diff = changedResourceCodesForFile(file, spec, baseRef);
+    const codes = diff.codes;
     if (spec.key === 'formSettings') {
       for (const code of codes) formSettings.add(code);
       continue;
@@ -24516,6 +25208,12 @@ function classifyGenericResourceFiles(files, baseRef = 'HEAD') {
       ...(resourceSelectors[spec.key] || []),
       ...codes,
     ]).sort();
+    if (diff.deletedCodes.length > 0) {
+      resourceDeletes[spec.key] = unique([
+        ...(resourceDeletes[spec.key] || []),
+        ...diff.deletedCodes,
+      ]).sort();
+    }
   }
   if (unknown.size > 0) {
     resourceSelectors.unknown = Array.from(unknown).sort();
@@ -24523,6 +25221,7 @@ function classifyGenericResourceFiles(files, baseRef = 'HEAD') {
   return {
     formSettings: Array.from(formSettings).sort(),
     resourceSelectors,
+    resourceDeletes,
   };
 }
 
@@ -24617,6 +25316,7 @@ function classifyWorkspaceFiles(files, runtimeMode, options = {}) {
     jsCodeNodes: Array.from(jsCodeNodes).sort(),
     resources,
     resourceSelectors: genericTargets.resourceSelectors,
+    resourceDeletes: genericTargets.resourceDeletes,
     runtime,
     other,
   };
@@ -24825,6 +25525,11 @@ function buildWorkspaceReleasePlan(options = {}) {
             ]).sort(),
           ])
         ),
+        resourceDeletes: Object.fromEntries(
+          Object.entries(inferred.resourceDeletes || {}).map(
+            ([key, codes]) => [key, unique(codes || []).sort()]
+          )
+        ),
         runtime: Boolean(changeScope.targets.runtime),
         other: [...(changeScope.targets.other || [])],
         };
@@ -25798,7 +26503,74 @@ async function runWorkspaceChildCommand(command, args, options = {}) {
   });
 }
 
-async function buildFormFieldContractPlan(config, target, manifest) {
+async function resolveStagedLocalFormContractSnapshots(
+  target,
+  flags = {}
+) {
+  const formCodes = unique(
+    String(flags['staged-form-contracts'] || '')
+      .split(',')
+      .map(value => value.trim())
+      .filter(Boolean)
+  ).sort();
+  if (formCodes.length === 0) return new Map();
+  const changeId = readStringFlag(flags, 'change');
+  if (!changeId) {
+    fail(
+      'FORM_FIELD_STAGED_CONTRACT_CHANGE_REQUIRED: --staged-form-contracts 必须与 --change 一起使用'
+    );
+  }
+  const context = assertStagedResourcesContext(target, changeId);
+  const file = stagedResourcesFileForChange(
+    changeId,
+    target.deploymentId
+  );
+  const resources = fs.existsSync(file)
+    ? normalizeStagedAppReleaseResources(
+        JSON.parse(fs.readFileSync(file, 'utf8'))
+      )
+    : [];
+  const snapshots = new Map();
+  for (const formCode of formCodes) {
+    const formUuid = resolveManifestFormUuid(
+      target.bound,
+      { formCode },
+      { fallbackToCode: false }
+    );
+    const staged = resources.find(
+      resource =>
+        resource.kind === 'FormRelease' &&
+        String(resource.identity?.formUuid || '').trim() === formUuid
+    );
+    if (!staged) {
+      fail(
+        `FORM_FIELD_STAGED_CONTRACT_REQUIRED: ${formCode} 尚未在 change ${changeId} 的当前 deployment 中获得 verified FormRelease`
+      );
+    }
+    const localSchema = await loadLocalFormSchema(
+      process.cwd(),
+      formCode
+    );
+    if (!localSchema) {
+      fail(
+        `FORM_FIELD_STAGED_CONTRACT_SCHEMA_MISSING: ${formCode} 缺少本地 schema`
+      );
+    }
+    const schema = JSON.parse(localSchema.schema);
+    snapshots.set(
+      formUuid,
+      collectFormSnapshotFieldIds({ form: { schema } })
+    );
+  }
+  return snapshots;
+}
+
+async function buildFormFieldContractPlan(
+  config,
+  target,
+  manifest,
+  options = {}
+) {
   const targets = [];
   for (const [manifestKey, kind] of [
     ['functions', 'Function'],
@@ -25842,12 +26614,15 @@ async function buildFormFieldContractPlan(config, target, manifest) {
       errors: [],
     };
   }
-  const snapshots = new Map();
+  const snapshots = new Map(
+    options.stagedLocalFormSnapshots || []
+  );
   const formTargets = unique(
     targets.map(item => item.formUuid).filter(Boolean)
   ).sort();
   await Promise.all(
     formTargets.map(async formUuid => {
+      if (snapshots.has(formUuid)) return;
       const frozen = await fetchFrozenFormConfig(
         config,
         target,