openxiangda 1.0.134 → 1.0.136

package/lib/cli.js

@@ -37,6 +37,17 @@ const {
   renderResourceExplain,
 } = require('./design-gates');
 const { buildDesignReview, renderDesignReview } = require('./design-review');
+const {
+  appendBypassLog,
+  archiveSddChange,
+  approveSddChange,
+  buildSddGovernanceReport,
+  buildSddStatus,
+  initSddWorkspace,
+  proposeSddChange,
+  syncSddChange,
+  verifySddChange,
+} = require('./sdd');
 const {
   fail,
   formatFetchError,
@@ -71,7 +82,9 @@ async function main(argv) {
   if (command === 'auth') return auth(rest);
   if (command === 'platform') return platform(rest);
   if (command === 'doctor') return doctor(rest);
+  if (command === 'contract') return contract(rest);
   if (command === 'design') return design(rest);
+  if (command === 'sdd') return sdd(rest);
   if (command === 'workspace') return workspace(rest);
   if (command === 'app') return app(rest);
   if (command === 'form') return form(rest);
@@ -110,13 +123,16 @@ Usage:
   openxiangda platform list
   openxiangda platform use <name>
   openxiangda auth status|refresh|logout [--profile name]
-  openxiangda doctor [--profile name] [--app-type APP_XXX] [--json]
+  openxiangda doctor [--profile name] [--app-type APP_XXX] [--release] [--json]
+  openxiangda contract list|explain <contract-name> [--json]
   openxiangda design gates|template|review [--topic code] [--json]
+  openxiangda sdd init|propose|approve|status|context|verify|sync|archive [change] [--json]
   openxiangda env [--profile name]
   openxiangda workspace init [dir] [--name package-name] [--runtime legacy|react-spa] [--install] [--profile name --app-type APP_XXX]
   openxiangda workspace init [dir] --profile <name> --app-name <app-name> [--runtime legacy|react-spa] [--install]
   openxiangda workspace bind --profile <name> --app-type <APP_XXX>
-  openxiangda workspace publish --profile <name> [--changed [--since ref]|--form code|--page code|--only list] [--dry-run] [--force] [--resources|--skip-resources] [--prune]
+  openxiangda workspace plan|check [--changed] [--json]
+  openxiangda workspace publish --profile <name> [--changed [--since ref]|--form code|--page code|--only list] [--dry-run] [--force] [--resources|--skip-resources] [--prune] [--sdd-bypass --reason text]
   openxiangda app list [--profile name] [--json]
   openxiangda app create <name> [--profile name] [--runtime legacy|react-spa] [--description text]
   openxiangda app snapshot <APP_XXX> [--profile name] [--json]
@@ -125,6 +141,7 @@ Usage:
   openxiangda form bind <formCode> --form-uuid <FORM_XXX>
   openxiangda form pull <formCode|formUuid> [--json]
   openxiangda form publish <formCode|formUuid> --bundle-url <url>     # repair only
+  openxiangda form schema-plan <formCode|formUuid> --schema-json <file>|--components-json <file>
   openxiangda page list [--profile name] [--json]
   openxiangda page publish <pageCode> --entry-url <url> --version <v> --build-id <id>  # repair only
   openxiangda page bind <pageCode> --page-id <id>
@@ -156,8 +173,8 @@ Usage:
   openxiangda permission page-group-list|page-group-create|page-group-update|page-group-delete|page-group-bind
   openxiangda permission form-group-list|form-group-create|form-group-update|form-group-delete|form-group-bind
   openxiangda settings get|save|indexes|indexes-save|data-management|data-management-save|public-access
-  openxiangda resource validate|plan|publish|pull|typegen|explain [--profile name] [--json] [--dry-run]
-  openxiangda runtime deploy [--profile name] [--dist dist] [--build-id id] [--upload-mode auto|staged|oss-direct|legacy-json] [--upload-timeout-ms ms] [--no-build] [--no-activate] [--json]
+  openxiangda resource validate|plan|publish|pull|typegen|explain [--profile name] [--json] [--dry-run] [--sdd-bypass --reason text]
+  openxiangda runtime deploy [--profile name] [--dist dist] [--build-id id] [--upload-mode auto|staged|oss-direct|legacy-json] [--upload-timeout-ms ms] [--no-build] [--no-activate] [--json] [--sdd-bypass --reason text]
   openxiangda runtime releases [--profile name] [--json]
   openxiangda runtime activate <releaseId> [--profile name] [--json]
   openxiangda inspect app|form|workflow|automation|permissions
@@ -188,9 +205,11 @@ const SUBCOMMAND_BOOLEAN_FLAGS = new Set([
   '--publish',
   '--published',
   '--redact',
+  '--release',
   '--resources',
   '--skip-resources',
   '--strict',
+  '--sdd-bypass',
   '--summary',
   '--unpublish',
   '--write-manifest',
@@ -505,10 +524,213 @@ async function design(args) {
   fail('用法: openxiangda design gates|template|review [--topic code] [--json]');
 }
 
+async function sdd(args) {
+  const { subcommand, rest } = parseSubcommandArgs(args);
+  const { flags, positional } = parseArgs(rest);
+  if (wantsSubcommandHelp(subcommand, flags)) {
+    print([
+      '用法: openxiangda sdd init|propose|approve|status|context|verify|sync|archive [change] [--json]',
+      '常用流程:',
+      '  openxiangda sdd init',
+      '  openxiangda sdd propose add-customer-list --title "客户列表" --forms customer --pages customer_list',
+      '  openxiangda sdd approve add-customer-list --summary "用户确认设计"',
+      '  openxiangda sdd context --json',
+      '  openxiangda sdd verify add-customer-list --changed --json',
+      '  openxiangda sdd archive add-customer-list',
+      '说明:',
+      '  - SDD 记录保存在 openspec/，不依赖官方 OpenSpec CLI。',
+      '  - 高风险发布需要 approved change 覆盖本次 forms/pages/resources/runtime 目标。',
+    ].join('\n'));
+    return;
+  }
+
+  if (subcommand === 'init') {
+    const result = initSddWorkspace({
+      cwd: process.cwd(),
+      path: flags.path,
+      force: Boolean(flags.force),
+    });
+    if (flags.json) return writeJson(result);
+    printSddInitReport(result);
+    return;
+  }
+
+  if (subcommand === 'propose' || subcommand === 'new') {
+    const changeId = positional[0] || flags.change;
+    const result = proposeSddChange({
+      cwd: process.cwd(),
+      changeId,
+      title: flags.title || flags.name,
+      riskLevel: flags.risk || flags['risk-level'],
+      domain: flags.domain,
+      force: Boolean(flags.force),
+      affected: parseSddAffectedFlags(flags),
+    });
+    if (flags.json) return writeJson(result);
+    print(`已创建 SDD change: ${result.change.id}\n目录: ${result.dir}`);
+    return;
+  }
+
+  if (subcommand === 'approve') {
+    const changeId = positional[0] || flags.change;
+    const result = approveSddChange({
+      cwd: process.cwd(),
+      changeId,
+      summary: flags.summary || flags.note,
+    });
+    if (flags.json) return writeJson(result);
+    print(`SDD change 已确认: ${result.change.id} approvedAt=${result.change.approvedAt}`);
+    return;
+  }
+
+  if (subcommand === 'status' || subcommand === 'context') {
+    const status = buildSddStatus({ cwd: process.cwd(), configText: readWorkspaceConfigText() });
+    const releasePlan = buildWorkspaceReleasePlan({
+      changed: Boolean(flags.changed || flags['changed-only']),
+      since: flags.since,
+      profile: flags.profile || '<profile>',
+      skipSdd: true,
+    });
+    const result = {
+      ...status,
+      releasePlan,
+      contracts:
+        subcommand === 'context'
+          ? Object.fromEntries(
+              Object.entries(API_CONTRACTS).map(([name, contract]) => [
+                name,
+                {
+                  mode: contract.mode,
+                  endpoint: contract.endpoint,
+                  response: contract.response,
+                  guarantees: contract.guarantees,
+                },
+              ])
+            )
+          : undefined,
+    };
+    if (flags.json || subcommand === 'context') return writeJson(result);
+    printSddStatusReport(result);
+    return;
+  }
+
+  if (subcommand === 'verify') {
+    const changeId = positional[0] || flags.change;
+    const releasePlan = buildWorkspaceReleasePlan({
+      changed: flags.changed !== false,
+      since: flags.since,
+      profile: flags.profile || '<profile>',
+      skipSdd: true,
+    });
+    const result = verifySddChange({
+      cwd: process.cwd(),
+      changeId,
+      releasePlan,
+      writeMetadata: true,
+    });
+    if (flags.json) {
+      writeJson(result);
+      if (!result.passed) process.exitCode = 1;
+      return;
+    }
+    printSddVerifyReport(result);
+    if (!result.passed) fail(`SDD verify 失败: ${result.errors[0].message}`);
+    return;
+  }
+
+  if (subcommand === 'sync') {
+    const changeId = positional[0] || flags.change;
+    const result = syncSddChange({ cwd: process.cwd(), changeId });
+    if (flags.json) return writeJson(result);
+    print(`SDD specs 已同步: ${result.change.id}\n${result.synced.map(item => `- ${item}`).join('\n')}`);
+    return;
+  }
+
+  if (subcommand === 'archive') {
+    const changeId = positional[0] || flags.change;
+    const releasePlan = buildWorkspaceReleasePlan({
+      changed: flags.changed !== false,
+      since: flags.since,
+      profile: flags.profile || '<profile>',
+      skipSdd: true,
+    });
+    const result = archiveSddChange({
+      cwd: process.cwd(),
+      changeId,
+      releasePlan,
+      force: Boolean(flags.force),
+    });
+    if (flags.json) return writeJson(result);
+    print(`SDD change 已归档: ${result.change.id}\n目录: ${result.archiveDir}`);
+    return;
+  }
+
+  fail('用法: openxiangda sdd init|propose|approve|status|context|verify|sync|archive [change] [--json]');
+}
+
+function parseSddAffectedFlags(flags) {
+  const split = value =>
+    value === undefined || value === null || value === false
+      ? []
+      : String(value)
+          .split(',')
+          .map(item => item.trim())
+          .filter(Boolean);
+  return {
+    forms: split(flags.forms || flags.form),
+    pages: split(flags.pages || flags.page),
+    resources: Boolean(flags.resources),
+    runtime: Boolean(flags.runtime),
+    backend: Boolean(flags.backend),
+    contracts: Boolean(flags.contracts),
+  };
+}
+
+function printSddInitReport(result) {
+  const lines = [`OpenXiangda SDD initialized: ${result.path}`];
+  for (const op of result.operations) {
+    lines.push(`- ${op.action}: ${op.path}`);
+  }
+  print(lines.join('\n'));
+}
+
+function printSddStatusReport(result) {
+  const lines = [
+    `OpenXiangda SDD status: ${result.governance.initialized ? 'initialized' : 'not initialized'}`,
+    `path: ${result.governance.path}`,
+    `strictHighRisk: ${result.governance.strictHighRisk ? 'true' : 'false'}`,
+    `active changes: ${result.activeChanges.length}`,
+  ];
+  for (const change of result.activeChanges) {
+    lines.push(`- ${change.id}: ${change.status}${change.approvedAt ? ` approvedAt=${change.approvedAt}` : ''}`);
+  }
+  if (result.bypassLog) lines.push(`bypass log: ${result.bypassLog}`);
+  print(lines.join('\n'));
+}
+
+function printSddVerifyReport(result) {
+  const lines = [
+    `OpenXiangda SDD verify: ${result.passed ? 'passed' : 'failed'}`,
+    `change: ${result.change.id}`,
+  ];
+  if (result.errors.length > 0) {
+    lines.push('Errors:');
+    for (const error of result.errors) {
+      lines.push(`- ${error.name}: ${error.message}`);
+      for (const detail of error.details || []) lines.push(`  ${detail}`);
+    }
+  }
+  if (result.warnings.length > 0) {
+    lines.push('Warnings:');
+    for (const warning of result.warnings) lines.push(`- ${warning.name}: ${warning.message}`);
+  }
+  print(lines.join('\n'));
+}
+
 async function doctor(args) {
   const { flags } = parseArgs(args);
   if (flags.help || flags.h) {
-    print('用法: openxiangda doctor [--profile name] [--app-type APP_XXX] [--agent codex] [--json]');
+    print('用法: openxiangda doctor [--profile name] [--app-type APP_XXX] [--agent codex] [--release] [--json]');
     return;
   }
   const config = loadConfig();
@@ -537,6 +759,8 @@ async function doctor(args) {
       hasDirectory: fs.existsSync(path.join(process.cwd(), 'src', 'resources')),
       validation: null,
     },
+    sdd: null,
+    release: null,
     skills: null,
     checks: [],
   };
@@ -603,6 +827,23 @@ async function doctor(args) {
     message: outdatedSkills.length > 0 ? `${outdatedSkills.length} 个 skill 未安装或过期` : undefined,
   });
 
+  if (flags.release) {
+    result.release = buildWorkspaceReleasePlan({
+      changed: true,
+      profile: profileName || config.currentProfile || '<profile>',
+      check: true,
+    });
+    result.sdd = result.release.sdd || buildSddStatus({ cwd: process.cwd(), configText: readWorkspaceConfigText() });
+    result.checks.push({
+      name: 'workspace-release',
+      status: result.release.errors.length > 0 ? 'error' : 'ok',
+      message:
+        result.release.errors.length > 0
+          ? `${result.release.errors.length} 个发布前错误`
+          : undefined,
+    });
+  }
+
   if (flags.json) return writeJson(result);
   printDoctorReport(result);
 }
@@ -638,6 +879,17 @@ function printDoctorReport(result) {
       `resource validation: ${result.resources.validation.errors.length} errors, ${result.resources.validation.warnings.length} warnings`
     );
   }
+  if (result.release) {
+    lines.push(
+      `release plan: forms=${result.release.targets.forms.length}, pages=${result.release.targets.pages.length}, resources=${result.release.targets.resources ? 'yes' : 'no'}, runtime=${result.release.targets.runtime ? 'yes' : 'no'}`
+    );
+  }
+  if (result.sdd) {
+    const governance = result.sdd.governance || result.sdd.governanceConfig || {};
+    lines.push(
+      `sdd: ${governance.initialized ? 'initialized' : 'not initialized'} path=${governance.path || 'openspec'} strict=${governance.strictHighRisk ? 'true' : 'false'}`
+    );
+  }
   for (const check of result.checks) {
     const suffix = check.message ? ` - ${check.message}` : '';
     lines.push(`- ${check.name}: ${check.status}${suffix}`);
@@ -646,6 +898,131 @@ function printDoctorReport(result) {
   print(lines.join('\n'));
 }
 
+const API_CONTRACTS = {
+  'sdk.form.create': {
+    name: 'sdk.form.create',
+    mode: 'strict-by-default',
+    endpoint: '/:appType/v1/form/saveFormData.json',
+    method: 'POST',
+    request: {
+      formUuid: 'string',
+      formDataJson: 'JSON.stringify(data)',
+      saveAsDraft: 'boolean | undefined',
+      startProcess: 'boolean | undefined',
+      processStartMode: 'auto | manual | draft | delayed | none | string | undefined',
+    },
+    response: {
+      code: '200 | 0 | success code',
+      result: 'normalized FormCreateResult object containing formInstId/formInstanceId',
+      data: 'legacy payload containing formInstId/formInstanceId',
+      formInstId: 'string',
+      formInstanceId: 'string',
+      processInstanceId: 'string | undefined',
+      serialNumber: 'string | undefined, first generated SerialNumberField value when present',
+      serialNumbers: 'Record<fieldId, string> | undefined',
+    },
+    guarantees: [
+      '保存接口只承诺返回实例标识、流程标识，以及保存时已生成的流水号字段。',
+      '保存接口不返回完整业务数据、公式回填或其他服务端格式化后的行数据。',
+      '缺少 formInstId/formInstanceId 时 strict 模式报错。',
+    ],
+    followUp: '需要完整行数据、公式回填或非流水号服务端字段时，保存成功后调用 sdk.form.getDetail({ formUuid, formInstId })。',
+    forbidden: [
+      '不要从 response.data/response.result 猜完整行数据。',
+      '不要生成 inst_${Date.now()} 这类假实例 ID。',
+      '不要默认 lookupAfterCreate；仅旧项目显式启用。',
+    ],
+  },
+  'sdk.form.update': {
+    name: 'sdk.form.update',
+    endpoint: '/:appType/v1/form/updateFormData.json',
+    method: 'POST',
+    response: {
+      code: '200 | 0 | success code',
+      result: 'formInstId string',
+      formInstId: 'string',
+      formInstanceId: 'string',
+    },
+    guarantees: [
+      '更新接口只承诺返回被更新的实例标识。',
+      '更新接口不返回完整业务数据。',
+    ],
+  },
+  'sdk.form.getDetail': {
+    name: 'sdk.form.getDetail',
+    endpoint: '/:appType/v1/form/getFormDataById.json',
+    method: 'GET',
+    response: {
+      result: '完整表单实例详情，包含平台可返回的业务字段和系统字段',
+    },
+    guarantees: [
+      '需要读取保存后的流水号、服务端生成字段或完整行数据时使用该接口。',
+    ],
+  },
+  'sdk.form.advancedSearch': {
+    name: 'sdk.form.advancedSearch',
+    endpoint: '/:appType/v1/form/advancedSearch.json',
+    method: 'GET',
+    response: {
+      currentPage: 'number',
+      data: 'array',
+      totalCount: 'number',
+    },
+    guarantees: [
+      '列表页必须使用分页查询和服务端过滤。',
+      '不要拉取大页数据后在本地过滤。',
+    ],
+  },
+};
+
+async function contract(args) {
+  const [subcommand, ...rest] = args;
+  const { flags, positional } = parseArgs(rest);
+  if (wantsSubcommandHelp(subcommand, flags)) {
+    print('用法: openxiangda contract list|explain <contract-name> [--json]');
+    return;
+  }
+
+  if (subcommand === 'list') {
+    const result = Object.keys(API_CONTRACTS).sort();
+    if (flags.json) return writeJson({ contracts: result });
+    print(result.join('\n'));
+    return;
+  }
+
+  if (subcommand === 'explain') {
+    const name = positional[0];
+    if (!name) {
+      fail('用法: openxiangda contract explain <contract-name>');
+    }
+    const contractInfo = API_CONTRACTS[name];
+    if (!contractInfo) {
+      fail(`未知契约: ${name}。可用契约: ${Object.keys(API_CONTRACTS).sort().join(', ')}`);
+    }
+    if (flags.json) return writeJson(contractInfo);
+    const lines = [
+      `${contractInfo.name}`,
+      `${contractInfo.method || 'GET'} ${contractInfo.endpoint}`,
+      '',
+      'Response:',
+      JSON.stringify(contractInfo.response || {}, null, 2),
+    ];
+    if (contractInfo.guarantees?.length) {
+      lines.push('', 'Guarantees:', ...contractInfo.guarantees.map(item => `- ${item}`));
+    }
+    if (contractInfo.followUp) {
+      lines.push('', `Follow-up: ${contractInfo.followUp}`);
+    }
+    if (contractInfo.forbidden?.length) {
+      lines.push('', 'Forbidden:', ...contractInfo.forbidden.map(item => `- ${item}`));
+    }
+    print(lines.join('\n'));
+    return;
+  }
+
+  fail('用法: openxiangda contract list|explain <contract-name> [--json]');
+}
+
 async function platform(args) {
   const [subcommand, ...rest] = args;
   const { flags, positional } = parseArgs(rest);
@@ -1437,6 +1814,28 @@ async function workspace(args) {
     return;
   }
 
+  if (subcommand === 'plan' || subcommand === 'check') {
+    const changed = Boolean(flags.changed || flags['changed-only'] || flags.since);
+    const plan = buildWorkspaceReleasePlan({
+      changed,
+      since: flags.since,
+      profile: flags.profile || config.currentProfile || '<profile>',
+      check: subcommand === 'check',
+    });
+    if (flags.json) {
+      writeJson(plan);
+      if (subcommand === 'check' && plan.errors.length > 0) {
+        process.exitCode = 1;
+      }
+      return;
+    }
+    printWorkspaceReleasePlan(plan);
+    if (subcommand === 'check' && plan.errors.length > 0) {
+      fail(`workspace check 失败: ${plan.errors[0].message}`);
+    }
+    return;
+  }
+
   const { profileName, profile } = getProfile(config, flags.profile);
 
   if (subcommand === 'bind') {
@@ -1482,12 +1881,22 @@ async function workspace(args) {
         `profile ${profileName} 未绑定应用。先执行 openxiangda workspace bind --profile ${profileName} --app-type APP_XXX`
       );
     }
+    const reactSpaWorkspace = isReactSpaWorkspace();
+    const sddPlan = buildWorkspacePublishSddPlan(
+      publishOptions,
+      reactSpaWorkspace ? 'react-spa' : getWorkspaceRuntimeModeFromConfig(readWorkspaceConfigText()),
+      profileName
+    );
+    if (publishOptions.dryRun) {
+      printWorkspaceReleasePlan(sddPlan);
+    } else {
+      assertSddReleaseGate(sddPlan, flags, 'openxiangda workspace publish');
+    }
     await requestWithAuth(
       config,
       profileName,
       `/openxiangda-api/v1/apps/${encodeURIComponent(bound.appType)}/snapshot`
     );
-    const reactSpaWorkspace = isReactSpaWorkspace();
     if (reactSpaWorkspace && !publishOptions.legacyFormBundle) {
       if (publishOptions.targetForm && !publishOptions.targetPage && !publishOptions.only && !publishOptions.changed) {
         runReactSpaFormSchemaPublish(profileName, profile, bound.appType, publishOptions);
@@ -1528,7 +1937,7 @@ async function workspace(args) {
     return;
   }
 
-  fail('用法: openxiangda workspace init|bind|publish [--changed [--since ref]|--form code|--page code|--only list] [--dry-run] [--force] [--resources|--skip-resources]');
+  fail('用法: openxiangda workspace init|bind|plan|check|publish [--changed [--since ref]|--form code|--page code|--only list] [--dry-run] [--force] [--resources|--skip-resources]');
 }
 
 function printWorkspaceHelp() {
@@ -1539,7 +1948,9 @@ Usage:
   openxiangda workspace init [dir] --profile <name> --app-name <app-name> [--runtime legacy|react-spa] [--description text] [--install] [--force]
   openxiangda workspace init [dir] --profile <name> --app-type <APP_XXX> [--runtime legacy|react-spa] [--install] [--force]
   openxiangda workspace bind --profile <name> --app-type <APP_XXX>
-  openxiangda workspace publish --profile <name> [--changed [--since ref]|--form code|--page code|--only list] [--dry-run] [--force] [--resources|--skip-resources] [--prune]
+  openxiangda workspace plan [--changed] [--json]
+  openxiangda workspace check [--changed] [--json]
+  openxiangda workspace publish --profile <name> [--changed [--since ref]|--form code|--page code|--only list] [--dry-run] [--force] [--resources|--skip-resources] [--prune] [--sdd-bypass --reason text]
 
 React SPA:
   openxiangda workspace publish --profile <name> --form <formCode>   # sync form schema only
@@ -1556,7 +1967,8 @@ Options:
   --changed [--since ref]          Publish changed classic resources.
   --dry-run                        Show planned work without writing.
   --resources / --skip-resources   Include or skip src/resources publish.
-  --legacy-form-bundle             Force legacy workspace publish in React SPA workspaces.`);
+  --legacy-form-bundle             Force legacy workspace publish in React SPA workspaces.
+  plan/check                       Show release order and fail on risky AI fallback patterns.`);
 }
 
 async function app(args) {
@@ -1637,7 +2049,7 @@ async function form(args) {
   const [subcommand, ...rest] = args;
   const { flags, positional } = parseArgs(rest);
   if (wantsSubcommandHelp(subcommand, flags)) {
-    print('用法: openxiangda form list|create|bind|pull|publish [--profile name] [--json]');
+    print('用法: openxiangda form list|create|bind|pull|publish|schema-plan [--profile name] [--json]');
     return;
   }
   const config = loadConfig();
@@ -1742,7 +2154,30 @@ async function form(args) {
     return;
   }
 
-  fail('用法: openxiangda form list|create|bind|pull|publish');
+  if (subcommand === 'schema-plan') {
+    const [formKey] = positional;
+    if (!formKey) {
+      fail('用法: openxiangda form schema-plan <formCode|formUuid> --schema-json <file>|--components-json <file>');
+    }
+    const target = getWorkspaceTarget(config, profileName, flags);
+    const formUuid = resolveFormUuid(target.bound, formKey, flags);
+    const body = readFormSchemaPlanBody(flags);
+    const data = await requestWithAuth(
+      config,
+      target.profileName,
+      `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/forms/${encodeURIComponent(formUuid)}/schema-storage-plan`,
+      {
+        method: 'POST',
+        body,
+        strictEnvelope: true,
+      }
+    );
+    if (flags.json) return writeJson(data);
+    print(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  fail('用法: openxiangda form list|create|bind|pull|publish|schema-plan');
 }
 
 async function page(args) {
@@ -4046,9 +4481,12 @@ async function resource(args) {
     return;
   }
 
-  const target = getWorkspaceTarget(config, profileName, flags);
   const validation = validateWorkspaceResources(manifest);
-  validateWorkspaceResourceBindings(manifest, target.bound, validation);
+  let target = null;
+  if (!isManifestEmpty(manifest)) {
+    target = getWorkspaceTarget(config, profileName, flags);
+    validateWorkspaceResourceBindings(manifest, target.bound, validation);
+  }
   await validateCompiledWorkflowResources(manifest, validation);
   if (subcommand === 'validate') {
     if (flags.json) return writeJson(validation);
@@ -4063,6 +4501,7 @@ async function resource(args) {
   }
 
   const dryRun = subcommand === 'publish' && Boolean(flags['dry-run']);
+  target = target || getWorkspaceTarget(config, profileName, flags);
   if (subcommand === 'plan' || dryRun) {
     const plan = await buildResourcePlan(config, target, manifest);
     if (dryRun) {
@@ -4075,6 +4514,16 @@ async function resource(args) {
   }
 
   const publishPlan = await buildResourcePlan(config, target, manifest);
+  if ((publishPlan.summary.create || 0) + (publishPlan.summary.update || 0) + (publishPlan.summary.delete || 0) > 0) {
+    assertSddReleaseGate(
+      buildExplicitSddReleasePlan(
+        { forms: [], pages: [], resources: true, runtime: false, other: [] },
+        { files: getWorkspaceChangedFiles() }
+      ),
+      flags,
+      'openxiangda resource publish'
+    );
+  }
   const result = await publishResourceManifest(config, target, manifest, {
     planActions: publishPlan.actions,
     skipNoop: !Boolean(flags.force),
@@ -4133,6 +4582,14 @@ async function runtime(args) {
   }
 
   if (subcommand === 'deploy') {
+    assertSddReleaseGate(
+      buildExplicitSddReleasePlan(
+        { forms: [], pages: [], resources: false, runtime: true, other: [] },
+        { files: getWorkspaceChangedFiles() }
+      ),
+      flags,
+      'openxiangda runtime deploy'
+    );
     const buildId = normalizeRuntimeBuildId(flags['build-id'] || createRuntimeBuildId());
     const distDir = path.resolve(process.cwd(), flags.dist || 'dist');
     const uploadMode = normalizeRuntimeUploadMode(flags['upload-mode']);
@@ -4742,12 +5199,14 @@ async function commands(args) {
       'update check|install',
       'platform add|list|use|remove',
       'auth status|refresh|logout',
-      'doctor [--profile name] [--app-type APP_XXX]',
+      'doctor [--profile name] [--app-type APP_XXX] [--release]',
+      'contract list|explain <contract-name>',
       'design gates|template|review [--topic code]',
+      'sdd init|propose|approve|status|context|verify|sync|archive',
       'env',
-      'workspace init|bind|publish [--app-name] [--changed|--since|--form|--page|--only|--dry-run|--force|--resources|--skip-resources|--prune]',
+      '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|publish',
+      'form list|create|bind|pull|publish|schema-plan',
       'page list|publish|bind|releases|activate',
       'menu list|create|update|sort|bind|delete',
       'workflow compile|list|create|bind|pull|publish|delete|validate',
@@ -4777,6 +5236,7 @@ async function commands(args) {
       '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.',
+      'OpenXiangda native SDD uses openspec/ records; high-risk publishes require an approved change unless --sdd-bypass --reason is used.',
     ],
   };
   if (flags.json) return writeJson(manifest);
@@ -4794,6 +5254,9 @@ function printWorkspaceInitReport(result) {
   if (result.bound) {
     lines.push(`已绑定 ${result.bound.profile}: ${result.bound.appType}`);
   }
+  if (result.sdd?.initialized) {
+    lines.push(`SDD: ${result.sdd.path}`);
+  }
   if (result.installedDependencies) {
     lines.push('依赖已安装');
   }
@@ -5357,6 +5820,19 @@ function resolveFormUuid(bound, formKey, flags = {}) {
   return mapped || formKey;
 }
 
+function readFormSchemaPlanBody(flags = {}) {
+  if (flags['schema-json']) {
+    return { schema: readJsonArg(flags['schema-json'], 'schema-json') };
+  }
+  if (flags['components-json']) {
+    return { components: readJsonArg(flags['components-json'], 'components-json') };
+  }
+  if (flags['json-file'] || flags['body-json']) {
+    return readDirectJsonBody(flags, 'form schema-plan');
+  }
+  fail('form schema-plan 需要 --schema-json <file> 或 --components-json <file>');
+}
+
 function resolveOptionalFormUuid(bound, formCode) {
   if (!formCode) return undefined;
   return bound.resources?.forms?.[formCode]?.formUuid || formCode;
@@ -10926,6 +11402,459 @@ function unwrapStrictApi(payload) {
   return 'data' in payload ? payload.data : payload;
 }
 
+function listDirectoriesIfExists(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .map(entry => entry.name)
+    .sort();
+}
+
+function normalizeWorkspaceRelativePath(value) {
+  return String(value || '')
+    .trim()
+    .replace(/^"|"$/g, '')
+    .split(path.sep)
+    .join('/');
+}
+
+function parseGitStatusPath(line) {
+  const raw = line.slice(3).trim();
+  const renamed = raw.includes(' -> ') ? raw.split(' -> ').pop() : raw;
+  return normalizeWorkspaceRelativePath(renamed);
+}
+
+function readGitNameList(args, options = {}) {
+  const result = spawnSync('git', args, {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) {
+    if (options.required) {
+      fail(`git ${args.join(' ')} 失败: ${(result.stderr || result.stdout || '').trim()}`);
+    }
+    return [];
+  }
+  return result.stdout
+    .split(/\r?\n/)
+    .map(line => line.trimEnd())
+    .filter(Boolean)
+    .map(normalizeWorkspaceRelativePath)
+    .filter(Boolean);
+}
+
+function getWorkspaceChangedFiles(options = {}) {
+  const since = String(options.since || '').trim();
+  if (since) {
+    return unique([
+      ...readGitNameList(
+        ['diff', '--name-only', '--diff-filter=ACMRTUXB', `${since}...HEAD`],
+        { required: true }
+      ),
+      ...readGitNameList(['diff', '--name-only', '--diff-filter=ACMRTUXB']),
+      ...readGitNameList(['diff', '--name-only', '--cached', '--diff-filter=ACMRTUXB']),
+      ...readGitNameList(['ls-files', '--others', '--exclude-standard']),
+    ]).sort();
+  }
+
+  const result = spawnSync('git', ['status', '--short', '--untracked-files=all'], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) {
+    return [];
+  }
+  return result.stdout
+    .split(/\r?\n/)
+    .map(line => line.trimEnd())
+    .filter(Boolean)
+    .map(parseGitStatusPath)
+    .filter(Boolean);
+}
+
+function getAllWorkspaceSourceFiles() {
+  const files = [];
+  const visit = dir => {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (['node_modules', 'dist', '.vite', '.cache', 'coverage'].includes(entry.name)) continue;
+      const entryPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        visit(entryPath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      files.push(normalizeWorkspaceRelativePath(path.relative(process.cwd(), entryPath)));
+    }
+  };
+  ['src', 'app-workspace.config.ts', 'package.json', 'vite.config.ts'].forEach(item => {
+    const target = path.join(process.cwd(), item);
+    if (fs.existsSync(target) && fs.statSync(target).isDirectory()) {
+      visit(target);
+    } else if (fs.existsSync(target)) {
+      files.push(item);
+    }
+  });
+  return files.sort();
+}
+
+function classifyWorkspaceFiles(files, runtimeMode) {
+  const forms = new Set();
+  const pages = new Set();
+  let resources = false;
+  let runtime = false;
+  const other = [];
+
+  for (const file of files) {
+    const formMatch = file.match(/^src\/forms\/([^/]+)/);
+    if (formMatch) {
+      forms.add(formMatch[1]);
+      continue;
+    }
+    const pageMatch = file.match(/^src\/pages\/([^/]+)/);
+    if (pageMatch) {
+      if (runtimeMode === 'react-spa') {
+        runtime = true;
+      } else {
+        pages.add(pageMatch[1]);
+      }
+      continue;
+    }
+    if (file.startsWith('src/resources/')) {
+      resources = true;
+      continue;
+    }
+    if (
+      file === 'package.json' ||
+      file === 'vite.config.ts' ||
+      file === 'index.html' ||
+      file.startsWith('src/')
+    ) {
+      runtime = runtimeMode === 'react-spa' || runtime;
+      continue;
+    }
+    other.push(file);
+  }
+
+  return {
+    forms: Array.from(forms).sort(),
+    pages: Array.from(pages).sort(),
+    resources,
+    runtime,
+    other,
+  };
+}
+
+function readWorkspaceConfigText() {
+  const file = path.join(process.cwd(), 'app-workspace.config.ts');
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+}
+
+function getWorkspaceRuntimeModeFromConfig(configText) {
+  return /runtimeMode\s*:\s*['"]react-spa['"]/.test(configText) ? 'react-spa' : 'legacy';
+}
+
+function getWorkspaceCompatibilityFromConfig(configText) {
+  return {
+    apiContracts: /apiContracts\s*:\s*['"]legacy['"]/.test(configText) ? 'legacy' : 'strict',
+    legacyFallbacks: /legacyFallbacks\s*:\s*true/.test(configText),
+    requestTrace: /requestTrace\s*:\s*true/.test(configText),
+  };
+}
+
+const AI_RELIABILITY_RULES = [
+  {
+    id: 'fake-form-instance-id',
+    severity: 'error',
+    pattern: /inst_\$\{Date\.now\(\)\}|inst_['"]?\s*\+\s*Date\.now\(/,
+    message: '禁止生成假 formInstanceId；保存接口缺少实例 ID 必须报错。',
+  },
+  {
+    id: 'implicit-response-guessing',
+    severity: 'warn',
+    pattern: /response\??\.(data|result)\s*(\?\?|\|\|)\s*response\??\.(result|data)/,
+    message: '避免在业务代码中猜 data/result；应使用 SDK 契约或 endpoint normalizer。',
+  },
+  {
+    id: 'legacy-lookup-after-create',
+    severity: 'warn',
+    pattern: /lookupAfterCreate\s*:\s*true/,
+    message: 'lookupAfterCreate 只能用于旧项目兼容；新代码保存后应显式 getDetail。',
+  },
+  {
+    id: 'direct-openxiangda-api',
+    severity: 'error',
+    pattern: /fetch\s*\([^)]*openxiangda-api|axios\.[a-z]+\([^)]*openxiangda-api/,
+    message: '页面代码不要直接请求 openxiangda-api；使用 Page SDK、connector 或 App Function。',
+  },
+  {
+    id: 'mock-or-fallback-data',
+    severity: 'warn',
+    pattern: /\b(mockData|fallbackData|fallbackRows|demoRows)\b/,
+    message: '不要用 mock/fallback 数据掩盖真实接口失败；开发态应暴露错误。',
+  },
+];
+
+function scanWorkspaceReliabilityIssues(files) {
+  const issues = [];
+  for (const file of files) {
+    if (!file.startsWith('src/')) continue;
+    if (/\.(test|spec)\.(ts|tsx|js|jsx)$/.test(file)) continue;
+    if (!/\.(ts|tsx|js|jsx|mjs|cjs)$/.test(file)) continue;
+    const abs = path.join(process.cwd(), file);
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) continue;
+    const content = fs.readFileSync(abs, 'utf8');
+    const lines = content.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+      const line = lines[index];
+      for (const rule of AI_RELIABILITY_RULES) {
+        if (rule.pattern.test(line)) {
+          issues.push({
+            rule: rule.id,
+            severity: rule.severity,
+            file,
+            line: index + 1,
+            message: rule.message,
+          });
+        }
+      }
+    }
+  }
+  return issues;
+}
+
+function buildWorkspaceReleaseCommands(targets, runtimeMode, profile) {
+  const profileArg = profile || '<profile>';
+  const commands = [];
+  if (runtimeMode === 'react-spa') {
+    for (const formCode of targets.forms) {
+      commands.push(`openxiangda workspace publish --profile ${profileArg} --form ${formCode}`);
+    }
+    if (targets.resources) {
+      commands.push(`openxiangda resource publish --profile ${profileArg}`);
+    }
+    if (targets.runtime) {
+      commands.push(`openxiangda runtime deploy --profile ${profileArg}`);
+    }
+    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(',')}${
+        targets.resources ? ' --resources' : ''
+      }`
+    );
+  } else if (targets.resources) {
+    commands.push(`openxiangda resource publish --profile ${profileArg}`);
+  }
+  return commands;
+}
+
+function buildWorkspaceReleasePlan(options = {}) {
+  const configText = readWorkspaceConfigText();
+  const runtimeMode = getWorkspaceRuntimeModeFromConfig(configText);
+  const compatibility = getWorkspaceCompatibilityFromConfig(configText);
+  const files = options.changed
+    ? getWorkspaceChangedFiles({ since: options.since })
+    : getAllWorkspaceSourceFiles();
+  const targets = classifyWorkspaceFiles(files, runtimeMode);
+  const issues = scanWorkspaceReliabilityIssues(files);
+  const errors = issues
+    .filter(issue => issue.severity === 'error')
+    .map(issue => ({
+      name: issue.rule,
+      message: `${issue.file}:${issue.line} ${issue.message}`,
+    }));
+  const commands = buildWorkspaceReleaseCommands(targets, runtimeMode, options.profile);
+  const sdd = options.skipSdd
+    ? null
+    : buildSddGovernanceReport({
+        cwd: process.cwd(),
+        configText,
+        targets,
+        files,
+      });
+  const sddErrors = sdd ? sdd.errors.map(error => ({ name: error.name, message: error.message })) : [];
+  const checks = [
+    {
+      name: 'workspace-config',
+      status: configText ? 'ok' : 'warn',
+      message: configText ? undefined : '未发现 app-workspace.config.ts',
+    },
+    {
+      name: 'api-contracts',
+      status: compatibility.apiContracts === 'strict' ? 'ok' : 'warn',
+      message:
+        compatibility.apiContracts === 'strict'
+          ? undefined
+          : '当前工作区处于 legacy API 契约模式',
+    },
+    {
+      name: 'legacy-fallbacks',
+      status: compatibility.legacyFallbacks ? 'warn' : 'ok',
+      message: compatibility.legacyFallbacks ? 'legacyFallbacks 已开启，可能掩盖接口/schema 问题' : undefined,
+    },
+    {
+      name: 'ai-reliability',
+      status: errors.length > 0 ? 'error' : issues.length > 0 ? 'warn' : 'ok',
+      message: issues.length > 0 ? `${issues.length} 个风险项` : undefined,
+    },
+    ...(sdd ? sdd.checks : []),
+  ];
+
+  return {
+    workspace: {
+      cwd: process.cwd(),
+      runtimeMode,
+      configFile: path.join(process.cwd(), 'app-workspace.config.ts'),
+      compatibility,
+    },
+    mode: options.changed ? 'changed' : 'all',
+    since: options.changed ? options.since || undefined : undefined,
+    changedFiles: options.changed ? files : undefined,
+    targets,
+    publishOrder:
+      runtimeMode === 'react-spa'
+        ? ['forms', 'resources', 'runtime']
+        : ['forms/pages', 'resources'],
+    commands,
+    checks,
+    sdd,
+    issues,
+    errors: [...errors, ...sddErrors],
+  };
+}
+
+function printWorkspaceReleasePlan(plan) {
+  const lines = [
+    `OpenXiangda workspace ${plan.mode} plan`,
+    `runtime: ${plan.workspace.runtimeMode}`,
+    `compatibility: apiContracts=${plan.workspace.compatibility.apiContracts}, legacyFallbacks=${plan.workspace.compatibility.legacyFallbacks}`,
+    `forms: ${plan.targets.forms.length ? plan.targets.forms.join(', ') : '(none)'}`,
+    `pages: ${plan.targets.pages.length ? plan.targets.pages.join(', ') : '(none)'}`,
+    `resources: ${plan.targets.resources ? 'yes' : 'no'}`,
+    `runtime deploy: ${plan.targets.runtime ? 'yes' : 'no'}`,
+  ];
+  if (plan.commands.length > 0) {
+    lines.push('', 'Commands:', ...plan.commands.map(command => `  ${command}`));
+  }
+  if (plan.issues.length > 0) {
+    lines.push('', 'Reliability issues:');
+    for (const issue of plan.issues) {
+      lines.push(`- [${issue.severity}] ${issue.file}:${issue.line} ${issue.message}`);
+    }
+  }
+  if (plan.sdd) {
+    lines.push(
+      '',
+      `SDD: enabled=${plan.sdd.governance.enabled ? 'true' : 'false'}, initialized=${plan.sdd.governance.initialized ? 'true' : 'false'}, strictHighRisk=${plan.sdd.governance.strictHighRisk ? 'true' : 'false'}, activeChanges=${plan.sdd.activeChanges.length}`
+    );
+    if (plan.sdd.highRiskFiles.length > 0) {
+      lines.push(`high-risk files: ${plan.sdd.highRiskFiles.join(', ')}`);
+    }
+  }
+  for (const check of plan.checks) {
+    const suffix = check.message ? ` - ${check.message}` : '';
+    lines.push(`- ${check.name}: ${check.status}${suffix}`);
+  }
+  print(lines.join('\n'));
+}
+
+function buildExplicitSddReleasePlan(targets, options = {}) {
+  const configText = readWorkspaceConfigText();
+  const sdd = buildSddGovernanceReport({
+    cwd: process.cwd(),
+    configText,
+    targets,
+    files: options.files || [],
+  });
+  return {
+    targets,
+    sdd,
+    errors: sdd.errors.map(error => ({ name: error.name, message: error.message })),
+  };
+}
+
+function assertSddReleaseGate(plan, flags, command) {
+  if (!plan?.sdd || plan.sdd.errors.length === 0) return;
+  if (flags['sdd-bypass']) {
+    const bypass = appendBypassLog({
+      cwd: process.cwd(),
+      configText: readWorkspaceConfigText(),
+      command,
+      reason: flags.reason,
+      targets: plan.targets,
+    });
+    warn(`SDD gate 已通过 bypass 放行: ${bypass.file}`);
+    return;
+  }
+  const first = plan.sdd.errors[0];
+  fail(`${first.message}\n如为紧急修复，可使用 --sdd-bypass --reason "..." 并在发布后补齐 SDD 归档。`);
+}
+
+function buildWorkspacePublishSddPlan(publishOptions, runtimeMode, profile) {
+  if (publishOptions.changed || (!publishOptions.targetForm && !publishOptions.targetPage && !publishOptions.only)) {
+    const plan = buildWorkspaceReleasePlan({
+      changed: publishOptions.changed,
+      since: publishOptions.since,
+      profile,
+    });
+    if (publishOptions.includeResources) {
+      plan.targets.resources = true;
+    }
+    return plan;
+  }
+  const targets = {
+    forms: [],
+    pages: [],
+    resources: Boolean(publishOptions.includeResources),
+    runtime: false,
+    other: [],
+  };
+  if (publishOptions.targetForm) targets.forms.push(publishOptions.targetForm);
+  if (publishOptions.targetPage) {
+    if (runtimeMode === 'react-spa') targets.runtime = true;
+    else targets.pages.push(publishOptions.targetPage);
+  }
+  if (publishOptions.only) {
+    for (const item of publishOptions.only.split(',').map(value => value.trim()).filter(Boolean)) {
+      const formMatch = item.match(/^forms\/([^/]+)$/);
+      const pageMatch = item.match(/^pages\/([^/]+)$/);
+      if (formMatch) targets.forms.push(formMatch[1]);
+      else if (pageMatch) targets.pages.push(pageMatch[1]);
+    }
+  }
+  targets.forms = unique(targets.forms).sort();
+  targets.pages = unique(targets.pages).sort();
+  const commands = buildWorkspaceReleaseCommands(targets, runtimeMode, profile);
+  const sddPlan = buildExplicitSddReleasePlan(targets, { files: [] });
+  return {
+    workspace: {
+      cwd: process.cwd(),
+      runtimeMode,
+      configFile: path.join(process.cwd(), 'app-workspace.config.ts'),
+      compatibility: getWorkspaceCompatibilityFromConfig(readWorkspaceConfigText()),
+    },
+    mode: 'targeted',
+    targets,
+    publishOrder:
+      runtimeMode === 'react-spa'
+        ? ['forms', 'resources', 'runtime']
+        : ['forms/pages', 'resources'],
+    commands,
+    checks: sddPlan.sdd.checks,
+    sdd: sddPlan.sdd,
+    issues: [],
+    errors: sddPlan.errors,
+  };
+}
+
 function isUnauthorized(error) {
   return (
     Number(error?.apiCode) === 401 ||
@@ -11155,8 +12084,10 @@ function normalizeWorkspacePublishOptions(flags) {
     targetPage,
     only,
     changed,
+    since,
     legacyFormBundle: Boolean(flags['legacy-form-bundle']),
     includeResources,
+    prune,
     quietResourceSkip: !targeted || skipResources,
   };
 }