openyida 2026.7.19 → 2026.7.21

package/README.md

@@ -174,6 +174,7 @@ openyida corp-efficiency
 openyida create-form create APP_XXX "Customer" .cache/openyida/forms/customer-fields.json
 openyida create-form update APP_XXX FORM_XXX .cache/openyida/forms/customer-changes.json
 openyida get-schema APP_XXX FORM_XXX
+openyida get-schema APP_XXX FORM_XXX --compact --resolve-fields "Customer Name,Status"
 openyida get-schema APP_XXX --all --output-dir .cache/schemas
 ```
 
@@ -240,6 +241,7 @@ Most checks should stay offline, but OpenYida also includes an explicit real-env
 OPENYIDA_E2E=1 npm run test:e2e:real
 OPENYIDA_E2E=1 npm run test:e2e:real:full
 OPENYIDA_E2E=1 OPENYIDA_E2E_FULL_STAGES=auth,app,form,process npm run test:e2e:real:full
+npm run test:e2e:real:schema-source
 npm run test:e2e:real:skills
 ```
 
@@ -249,6 +251,8 @@ The runner creates a disposable app, form, and custom page with an `OY_E2E_*` pr
 
 `test:e2e:real:skills` enforces coverage for every directory under `yida-skills/skills/`. Each skill must be classified as real E2E, offline/unit, opt-in, or deprecated with an explicit reason. This prevents new skills from quietly bypassing the real-environment test plan.
 
+`test:e2e:real:schema-source` is a local process-level Schema-as-Code E2E for agent/source checkout validation. It reads `yida-skills/` in place, creates a temporary `openyida` launcher that executes the current checkout `bin/yida.js`, and runs CRM app/form/page/process create, managed-update, and noop scenarios through `schema validate -> plan -> apply -> noop` against a mock Yida service, including customer field updates and approval-flow/page changes. Report and integration automation manifests remain compatibility-boundary scenarios and must return unsupported.
+
 Each successful full run leaves a human-inspectable result app in the target organization. The final step publishes a dedicated `Full E2E Dashboard` custom page, renames the app to `OY_E2E_*_PASSED` by default, and prints direct links for the app, form, dashboard page, and report; the same links are saved under `resultApp` in the registry JSON.
 
 Useful options:
@@ -354,6 +358,8 @@ openyida append-chart APP_XXX REPORT_XXX .cache/openyida/reports/chart.json
 
 Run `openyida --help` or `openyida <command> --help` for detailed usage.
 
+Schema-as-Code Phase 1 manages app, form, process, and native/default display page resources. Use the single [Phase 1 Manifest guide](yida-skills/references/schema-as-code-phase1.md): create any referenced page source first, run `validate`, run the read-only `plan`, review its current `planId`, then explicitly approve and run `apply`. Error `nextAction`/`ask_human` never grants the first write; `stale_replanned` only returns a replacement plan for another explicit review. State is the only persisted bindings authority; report, automation, and page config/delete/pull remain outside Phase 1.
+
 <!-- OPENYIDA_COMMANDS_START -->
 <!-- This section is generated by `npm run docs:commands`. Do not edit command rows by hand. -->
 
@@ -406,6 +412,14 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | `openyida update-form-config <appType> ...` | Update form configuration |
 | `openyida get-form-config <appType> <formUuid> [--json]` | Query form configuration |
 
+### Schema-as-Code
+
+| Command | Description |
+|---------|-------------|
+| `openyida schema validate <manifest> --json --quiet` | Validate Schema-as-Code manifest locally |
+| `openyida schema plan <manifest> --state <path> --json --quiet` | Plan Schema-as-Code changes with read-only remote observation |
+| `openyida schema apply <manifest> --state <path> --plan-id <planId> --json --quiet` | Apply a reviewed Schema-as-Code plan with checkpoints and recovery guards |
+
 ### Data & Permissions
 
 | Command | Description |

package/bin/yida.js

@@ -18,6 +18,7 @@ const { COMMAND_GROUPS, buildCommandManifest } = require('../lib/core/command-ma
 
 const command = process.argv[2];
 const args = process.argv.slice(3);
+const rawArgs = process.argv.slice(3);
 
 function isAgentEnvironment(env) {
   return !!(
@@ -55,6 +56,9 @@ function shouldRunUpdateCheck() {
   if (!command || command === '--help' || command === '-h' || command === '--version' || command === '-v') {
     return false;
   }
+  if (args.includes('--help') || args.includes('-h')) {
+    return false;
+  }
   if (command === 'commands' || command === 'agent-capabilities' || command === 'mcp') {
     return false;
   }
@@ -250,12 +254,15 @@ function printLoginResult(result) {
     return;
   }
 
-  const tokenUsable = result.can_auto_use !== false && !!result.access_token;
+  const tokenUsable = result.ok !== undefined
+    ? !!result.ok
+    : (result.can_auto_use !== false && !!result.access_token);
   const summary = {
     ok: tokenUsable,
     status: result.status || (tokenUsable ? 'ok' : 'token_not_issued'),
     auth_mode: 'token',
-    can_auto_use: tokenUsable,
+    auth_source: result.auth_source || result.authSource,
+    can_auto_use: result.can_auto_use !== undefined ? !!result.can_auto_use : tokenUsable,
     token_type: result.token_type || 'Bearer',
     access_token: maskSensitiveAuthOutput({ access_token: result.access_token }).access_token,
     expires_at: result.expires_at ? new Date(result.expires_at).toISOString() : undefined,
@@ -263,6 +270,7 @@ function printLoginResult(result) {
     corp_id: result.corp_id,
     user_id: result.user_id,
     user_name: result.user_name,
+    failure_reason: result.failure_reason,
     message: result.message,
     raw: tokenUsable ? undefined : result.raw,
   };
@@ -308,6 +316,30 @@ function getArgValue(cliArgs, name) {
   return cliArgs[index + 1];
 }
 
+const UNSUPPORTED_LEGACY_LOGIN_FLAGS = new Set([
+  '--qr',
+  '--qr-code',
+  '--agent-qr',
+  '--codex-qr',
+  '--agent-poll',
+  '--codex-poll',
+  '--browser',
+  '--codex',
+  '--qoder',
+  '--wukong',
+]);
+
+function findUnsupportedLegacyLoginFlag(...argLists) {
+  for (const argList of argLists) {
+    for (const arg of argList || []) {
+      if (UNSUPPORTED_LEGACY_LOGIN_FLAGS.has(arg)) {
+        return arg;
+      }
+    }
+  }
+  return null;
+}
+
 function parseLoginTargetArg(value) {
   const raw = String(value || '').trim();
   if (!raw) {return null;}
@@ -445,6 +477,34 @@ function throwCliUsage(...lines) {
   });
 }
 
+function hasHelpFlag(cliArgs = []) {
+  return cliArgs.includes('--help') || cliArgs.includes('-h');
+}
+
+function printCommandUsage(...lines) {
+  console.log(lines.filter(Boolean).join('\n'));
+}
+
+function printLoginHelp() {
+  printCommandUsage(t('cli.login_usage'), t('cli.login_example'));
+}
+
+function printAuthHelp() {
+  printCommandUsage(t('cli.auth_usage'), t('cli.auth_example'));
+}
+
+function assertNoUnsupportedLegacyLoginFlags(...argLists) {
+  const flag = findUnsupportedLegacyLoginFlag(...argLists);
+  if (!flag) {
+    return;
+  }
+  throwCliUsage(
+    t('cli.login_unsupported_option', flag),
+    t('cli.login_usage'),
+    t('cli.login_example')
+  );
+}
+
 async function main() {
   applyQuietFlag();
   applyGlobalEnvironmentFlags();
@@ -516,15 +576,23 @@ async function main() {
 
     case 'login': {
       const loginArgs = applyLoginEnvironmentFlags(args, { inferTargetUrl: true });
-      const { tokenLogin, tokenStatus } = require('../lib/auth/token-auth');
-      if (loginArgs.includes('--check-only')) {
-        console.log(JSON.stringify(tokenStatus(), null, 2));
+      const { getAuthStatus, isEnvAuthMode } = require('../lib/core/utils');
+      if (hasHelpFlag(loginArgs)) {
+        printLoginHelp();
       } else {
-        const result = await tokenLogin({
-          clientId: getArgValue(loginArgs, '--client-id'),
-          quiet: loginArgs.includes('--quiet'),
-        });
-        printLoginResult(result);
+        assertNoUnsupportedLegacyLoginFlags(rawArgs, loginArgs);
+        if (loginArgs.includes('--check-only')) {
+          console.log(JSON.stringify(getAuthStatus(), null, 2));
+        } else if (isEnvAuthMode()) {
+          printLoginResult(getAuthStatus());
+        } else {
+          const { tokenLogin } = require('../lib/auth/token-auth');
+          const result = await tokenLogin({
+            clientId: getArgValue(loginArgs, '--client-id'),
+            quiet: loginArgs.includes('--quiet'),
+          });
+          printLoginResult(result);
+        }
       }
       break;
     }
@@ -538,15 +606,25 @@ async function main() {
     case 'auth': {
       const subCommand = args[0];
       const authArgs = applyLoginEnvironmentFlags(args.slice(1), { inferTargetUrl: true });
-      const { tokenLogin, tokenLogout, tokenRefresh, tokenStatus } = require('../lib/auth/token-auth');
-      if (subCommand === 'status') {
-        console.log(JSON.stringify(tokenStatus(), null, 2));
+      const { getAuthStatus, isEnvAuthMode } = require('../lib/core/utils');
+      const { tokenLogin, tokenLogout, tokenRefresh } = require('../lib/auth/token-auth');
+      if (!subCommand || subCommand === '--help' || subCommand === '-h') {
+        printAuthHelp();
+      } else if (subCommand === 'status') {
+        console.log(JSON.stringify(getAuthStatus(), null, 2));
       } else if (subCommand === 'login') {
-        const result = await tokenLogin({
-          clientId: getArgValue(authArgs, '--client-id'),
-          quiet: authArgs.includes('--quiet'),
-        });
-        printLoginResult(result);
+        if (hasHelpFlag(authArgs)) {
+          printLoginHelp();
+        } else {
+          assertNoUnsupportedLegacyLoginFlags(rawArgs.slice(1), authArgs);
+          const result = isEnvAuthMode()
+            ? getAuthStatus()
+            : await tokenLogin({
+              clientId: getArgValue(authArgs, '--client-id'),
+              quiet: authArgs.includes('--quiet'),
+            });
+          printLoginResult(result);
+        }
       } else if (subCommand === 'refresh') {
         console.log(JSON.stringify(maskSensitiveAuthOutput(await tokenRefresh()), null, 2));
       } else if (subCommand === 'logout') {
@@ -624,6 +702,12 @@ async function main() {
       break;
     }
 
+    case 'schema': {
+      const { run } = require('../lib/schema/command');
+      await run(args);
+      break;
+    }
+
     case 'formula': {
       const subCommand = args[0];
       const subArgs = args.slice(1);
@@ -664,6 +748,11 @@ async function main() {
     }
 
     case 'publish': {
+      if (args.includes('--help') || args.includes('-h')) {
+        const publishMain = require('../lib/app/publish');
+        await publishMain(args);
+        break;
+      }
       const passThroughFlags = new Set(['--skip-lint', '--health-check', '--check', '--open', '--no-open', '--compat', '--modern', '--force', '--canvas']);
       const filteredArgs = args.filter(arg => !passThroughFlags.has(arg));
       if (filteredArgs.length < 3) {

package/lib/app/create-app.js

@@ -18,6 +18,10 @@ const { t } = require('../core/i18n');
 const { buildYidaI18n, normalizeYidaLocale, resolveContentLocale } = require('../core/yida-i18n');
 const { parseOpenOption, withBrowserHandoff } = require('../core/browser-handoff');
 const { throwCommandError } = require('../core/command-errors');
+const {
+  assertLegacyDirectWriteAllowed,
+  extractLegacyGuardArgs,
+} = require('../core/legacy-schema-guard');
 const { assertPresetThemeKey } = require('./theme-presets');
 
 const DEFAULT_APP_OPTIONS = {
@@ -281,7 +285,8 @@ function buildCreateAppPayload(params, auth, contentLocale, openExclusive, openP
 
 async function run(args) {
   const openOption = parseOpenOption(args);
-  args = openOption.args;
+  const guardSplit = extractLegacyGuardArgs(openOption.args);
+  args = guardSplit.args;
 
   if (hasHelpFlag(args)) {
     printUsage();
@@ -301,6 +306,12 @@ async function run(args) {
     chalkError(t('create_app.usage'), { hint: t('create_app.example') });
   }
 
+  assertLegacyDirectWriteAllowed({
+    command: 'create-app',
+    resourceType: 'app',
+    action: 'create',
+  }, { guardOptions: guardSplit.guardOptions });
+
   const { appName, description, icon, iconColor, colour, navTheme, layoutDirection } = params;
 
   const { c, banner, step, label, success: chalkSuccess, result: chalkResult } = require('../core/chalk');

package/lib/app/create-form/args.js

@@ -85,6 +85,7 @@ function createParseArgs(dependencies) {
       labelAlign: 'top',
       contentLocale: null,
       browserOpenMode: openOption.mode,
+      legacyGuardOptions: openOption.legacyGuardOptions || null,
     };
 
     const args = [...rawArgs];
@@ -118,6 +119,18 @@ function createParseArgs(dependencies) {
       }
     }
 
+    if (args.includes('--help') || args.includes('-h')) {
+      usage(t('create_form.usage_create_short'));
+      hint(t('create_form.usage_update_short'));
+      hint(t('create_form.example_create'));
+      hint(t('create_form.example_update'));
+      return {
+        mode: 'help',
+        help: true,
+        ...options
+      };
+    }
+
     const mode = args[0];
 
     if (mode === 'create') {

package/lib/app/create-form.js

@@ -59,13 +59,18 @@
 const fs = require('fs');
 const path = require('path');
 const querystring = require('querystring');
-const { loadAuthData, triggerLogin, resolveBaseUrl, httpPost, httpGet, requestWithAutoLogin } = require('../core/utils');
+const { httpPost, httpGet, requestWithAutoLogin } = require('../core/utils');
+const { createAuthRef } = require('../core/yida-client');
 const { CliError } = require('../core/cli-error');
 const { t } = require('../core/i18n');
 const { safeParseJson } = require('../core/safe-json');
 const { buildYidaI18n, normalizeYidaLocale, resolveContentLocale } = require('../core/yida-i18n');
 const { banner, step, label, success, fail, warn, info, error, result, usage, hint, listItem } = require('../core/chalk');
-const { parseOpenOption, withBrowserHandoff } = require('../core/browser-handoff');
+const { parseOpenOption: parseBrowserOpenOption, withBrowserHandoff } = require('../core/browser-handoff');
+const {
+  assertLegacyDirectWriteAllowed,
+  extractLegacyGuardArgs,
+} = require('../core/legacy-schema-guard');
 const { default: babelTransform } = require('../core/babel-transform');
 const { normalizeFormulaFieldRefs } = require('../formula/evaluate');
 const { createParseArgs } = require('./create-form/args');
@@ -77,6 +82,15 @@ const { FORM_RULES_BLOCK_END, FORM_RULES_BLOCK_START } = require('./create-form/
 const { SMART_VALIDATION_BLOCK_END, SMART_VALIDATION_BLOCK_START } = require('./create-form/validation-builder');
 const { createFieldNormalizers } = require('./create-form/field-normalizers');
 
+function parseOpenOption(inputArgs) {
+  const openOption = parseBrowserOpenOption(inputArgs);
+  const guardSplit = extractLegacyGuardArgs(openOption.args);
+  return Object.assign({}, openOption, {
+    args: guardSplit.args,
+    legacyGuardOptions: guardSplit.guardOptions,
+  });
+}
+
 // ── 选项类字段类型 ───────────────────────────────────
 const OPTION_FIELD_TYPES = ['RadioField', 'SelectField', 'CheckboxField', 'MultiSelectField'];
 
@@ -3982,27 +3996,30 @@ function applyChangesToSchema(schema, changes) {
 
 // ── 发送 POST 请求（支持 302 自动重登录） ────────────
 
-function sendPostRequest(baseUrl, requestPath, extraParams, formUuid) {
-  const postData = querystring.stringify(extraParams);
+function sendPostRequest(baseUrl, requestPath, extraParams, formUuid, authRef) {
+  const authParams = authRef && authRef.csrfToken ? { _csrf_token: authRef.csrfToken } : {};
+  const postData = querystring.stringify(Object.assign(authParams, extraParams));
   const referer = formUuid
     ? `${baseUrl}/alibaba/web/${extraParams.appType || ''}/design/pageDesigner?formUuid=${formUuid}`
     : baseUrl + '/';
-  return httpPost(baseUrl, requestPath, postData, { referer });
+  return httpPost(baseUrl, requestPath, postData, authRef && authRef.cookies, { referer });
 }
 
 // ── 发送 updateFormConfig 请求 ───────────────────────
 
-function sendUpdateConfigRequest(baseUrl, appType, formUuid, version, value) {
-  const postData = querystring.stringify({
+function sendUpdateConfigRequest(baseUrl, appType, formUuid, version, value, authRef) {
+  const authParams = authRef && authRef.csrfToken ? { _csrf_token: authRef.csrfToken } : {};
+  const postData = querystring.stringify(Object.assign(authParams, {
     formUuid: formUuid,
     version: version,
     configType: 'MINI_RESOURCE',
     value: value,
-  });
+  }));
   return httpPost(
     baseUrl,
     `/dingtalk/web/${appType}/query/formdesign/updateFormConfig.json`,
-    postData
+    postData,
+    authRef && authRef.cookies
   );
 }
 
@@ -4013,6 +4030,33 @@ function resolveCorpId(authData) {
   return '';
 }
 
+function extractSchemaServerRevision(schemaResult) {
+  const content = schemaResult && schemaResult.content && typeof schemaResult.content === 'object'
+    ? schemaResult.content
+    : null;
+  const candidates = [
+    schemaResult && schemaResult.gmtModified,
+    schemaResult && schemaResult.serverRevision,
+    content && content.gmtModified,
+    content && content.serverRevision,
+    content && content.version,
+    schemaResult && schemaResult.version,
+  ];
+  for (const candidate of candidates) {
+    if (candidate !== undefined && candidate !== null && String(candidate).trim() !== '') {
+      return candidate;
+    }
+  }
+  return undefined;
+}
+
+function requireSchemaServerRevision(serverRevision, details) {
+  if (serverRevision === undefined || serverRevision === null || String(serverRevision).trim() === '') {
+    throwCreateFormError('Missing form schema server revision from exact readback.', 'CREATE_FORM_SCHEMA_REVISION_INVALID', details);
+  }
+  return serverRevision;
+}
+
 // ── 保存 Schema 并更新表单配置（create/update 共用）──
 //
 // 封装了 saveFormSchema + updateFormConfig 两步，以及各自的 302 自动重登录重试。
@@ -4027,6 +4071,7 @@ async function saveSchemaAndUpdateConfig(authRef, appType, formUuid, schema, ver
     info(t('create_form.formula_prefix_fixed', fixedRefs));
   }
   ensureDividerThemeAction(schema);
+  const serverRevision = requireSchemaServerRevision(version, { appType, formUuid });
 
   step(saveStep, t('create_form.step_save_schema', saveStep));
   info(t('create_form.sending_save'));
@@ -4035,8 +4080,9 @@ async function saveSchemaAndUpdateConfig(authRef, appType, formUuid, schema, ver
     return sendPostRequest(
       auth.baseUrl,
       buildApiPath(appType, 'saveFormSchema', { prefix: '_view' }),
-      { appType: appType, formUuid: formUuid, content: JSON.stringify(schema), schemaVersion: 'V5', prefix: '_view' },
-      formUuid
+      { appType: appType, formUuid: formUuid, content: JSON.stringify(schema), schemaVersion: 'V5', prefix: '_view', gmtModified: serverRevision },
+      formUuid,
+      auth
     );
   }, authRef);
 
@@ -4063,7 +4109,7 @@ async function saveSchemaAndUpdateConfig(authRef, appType, formUuid, schema, ver
   info(t('create_form.sending_config'));
 
   const configResult = await requestWithAutoLogin(function (auth) {
-    return sendUpdateConfigRequest(auth.baseUrl, appType, formUuid, version || 1, 0);
+    return sendUpdateConfigRequest(auth.baseUrl, appType, formUuid, version || 1, 0, auth);
   }, authRef);
 
   return { saveResult: saveResult, configResult: configResult };
@@ -4094,7 +4140,9 @@ async function mainCreate(parsedArgs, authRef) {
     return sendPostRequest(
       auth.baseUrl,
       buildApiPath(appType, 'saveFormSchemaInfo'),
-      { formType: 'receipt', title: JSON.stringify(i18n(formTitle)) }
+      { formType: 'receipt', title: JSON.stringify(i18n(formTitle)) },
+      undefined,
+      auth
     );
   }, authRef);
 
@@ -4110,6 +4158,14 @@ async function mainCreate(parsedArgs, authRef) {
 
   const formUuid = createResult.content.formUuid || createResult.content;
   success(t('create_form.blank_created', formUuid));
+  const shellSchemaResult = await requestWithAutoLogin(function (auth) {
+    return sendGetRequest(
+      auth.baseUrl,
+      buildApiPath(appType, 'getFormSchema', { prefix: '_view', namespace: 'alibaba' }),
+      { formUuid: formUuid, schemaVersion: 'V5' }
+    );
+  }, authRef);
+  const serverRevision = extractSchemaServerRevision(shellSchemaResult);
 
   // Step 4 & 5: 生成 Schema 并保存，然后更新表单配置
   const corpId = resolveCorpId(authRef.authData);
@@ -4125,7 +4181,7 @@ async function mainCreate(parsedArgs, authRef) {
     const appliedValidations = applySmartValidations(schema, createValidationRules);
     info('已为创建表单写入 ' + appliedValidations.appliedRules.length + ' 条字段校验');
   }
-  const { configResult } = await saveSchemaAndUpdateConfig(authRef, appType, formUuid, schema, 1, 4);
+  const { configResult } = await saveSchemaAndUpdateConfig(authRef, appType, formUuid, schema, serverRevision, 4);
 
   // 输出结果
   const formUrl = authRef.baseUrl + '/' + appType + '/workbench/' + formUuid;
@@ -4156,6 +4212,70 @@ async function mainCreate(parsedArgs, authRef) {
   }
 }
 
+async function createFormForLegacyProcess(context, input) {
+  const authRef = context && context.authRef ? context.authRef : context;
+  const parsedArgs = {
+    mode: 'create',
+    appType: input.appType,
+    formTitle: input.formTitle,
+    fieldsJsonOrFile: input.fieldsJsonFile,
+    layout: input.layout || 'single',
+    theme: input.theme || 'default',
+    labelAlign: input.labelAlign || 'top',
+    contentLocale: input.contentLocale || null,
+    browserOpenMode: 'off',
+  };
+
+  const { appType, formTitle, fieldsJsonOrFile, layout, theme, labelAlign } = parsedArgs;
+  const { fields, validations } = readFieldsDefinition(fieldsJsonOrFile);
+  const fieldCount = countDataFieldDefinitions(fields);
+  const createResult = await requestWithAutoLogin(function (auth) {
+    return sendPostRequest(
+      auth.baseUrl,
+      buildApiPath(appType, 'saveFormSchemaInfo'),
+      { formType: 'receipt', title: JSON.stringify(i18n(formTitle)) },
+      undefined,
+      auth
+    );
+  }, authRef);
+
+  if (!createResult || !createResult.success || !createResult.content) {
+    const errorMsg = createResult ? createResult.errorMsg || t('common.unknown_error') : t('common.request_failed');
+    throwCreateFormError(errorMsg, 'CREATE_FORM_CREATE_BLANK_FAILED', {
+      appType,
+      result: createResult,
+    });
+  }
+
+  const formUuid = createResult.content.formUuid || createResult.content;
+  const shellSchemaResult = await requestWithAutoLogin(function (auth) {
+    return sendGetRequest(
+      auth.baseUrl,
+      buildApiPath(appType, 'getFormSchema', { prefix: '_view', namespace: 'alibaba' }),
+      { formUuid: formUuid, schemaVersion: 'V5' }
+    );
+  }, authRef);
+  const serverRevision = extractSchemaServerRevision(shellSchemaResult);
+  const corpId = resolveCorpId(authRef.authData || authRef.cookieData || authRef);
+  const schema = buildFormSchema(formTitle, fields, formUuid, corpId, appType, layout, theme, labelAlign);
+  const createValidationRules = collectSmartValidationRulesFromFields(fields).concat(validations || []);
+  if (createValidationRules.length > 0) {
+    applySmartValidations(schema, createValidationRules);
+  }
+  const { saveResult, configResult } = await saveSchemaAndUpdateConfig(authRef, appType, formUuid, schema, serverRevision, 4);
+  return {
+    success: true,
+    appType,
+    formUuid,
+    formTitle,
+    fieldCount,
+    createResult,
+    saveResult,
+    configResult,
+    url: authRef.baseUrl + '/' + appType + '/workbench/' + formUuid,
+  };
+}
+
 // ── 为 SerialNumberField 补全 formula（递归处理子表）──
 //
 // 遍历字段列表，对每个 SerialNumberField：
@@ -4232,12 +4352,7 @@ async function mainAddOption(parsedArgs, authRef) {
   }
 
   let schema;
-  let version = 1;
-  if (schemaResult.content && typeof schemaResult.content === 'object' && schemaResult.content.version !== undefined) {
-    version = schemaResult.content.version;
-  } else if (schemaResult.version !== undefined) {
-    version = schemaResult.version;
-  }
+  const version = extractSchemaServerRevision(schemaResult);
   if (schemaResult.content) {
     schema = typeof schemaResult.content === 'string' ? JSON.parse(schemaResult.content) : schemaResult.content;
   } else if (schemaResult.pages) {
@@ -4399,12 +4514,7 @@ async function mainBindDataSource(parsedArgs, authRef) {
   }
 
   let schema;
-  let version = 1;
-  if (schemaResult.content && typeof schemaResult.content === 'object' && schemaResult.content.version !== undefined) {
-    version = schemaResult.content.version;
-  } else if (schemaResult.version !== undefined) {
-    version = schemaResult.version;
-  }
+  const version = extractSchemaServerRevision(schemaResult);
   if (schemaResult.content) {
     schema = typeof schemaResult.content === 'string' ? JSON.parse(schemaResult.content) : schemaResult.content;
   } else if (schemaResult.pages) {
@@ -4545,12 +4655,7 @@ async function mainRule(parsedArgs, authRef) {
   }
 
   let schema;
-  let version = 1;
-  if (schemaResult.content && typeof schemaResult.content === 'object' && schemaResult.content.version !== undefined) {
-    version = schemaResult.content.version;
-  } else if (schemaResult.version !== undefined) {
-    version = schemaResult.version;
-  }
+  const version = extractSchemaServerRevision(schemaResult);
 
   if (schemaResult.content) {
     schema = typeof schemaResult.content === 'string' ? JSON.parse(schemaResult.content) : schemaResult.content;
@@ -4672,12 +4777,7 @@ async function mainPatch(parsedArgs, authRef) {
   }
 
   let schema;
-  let version = 1;
-  if (schemaResult.content && typeof schemaResult.content === 'object' && schemaResult.content.version !== undefined) {
-    version = schemaResult.content.version;
-  } else if (schemaResult.version !== undefined) {
-    version = schemaResult.version;
-  }
+  const version = extractSchemaServerRevision(schemaResult);
 
   if (schemaResult.content) {
     schema = typeof schemaResult.content === 'string' ? JSON.parse(schemaResult.content) : schemaResult.content;
@@ -4784,12 +4884,7 @@ async function mainValidation(parsedArgs, authRef) {
   }
 
   let schema;
-  let version = 1;
-  if (schemaResult.content && typeof schemaResult.content === 'object' && schemaResult.content.version !== undefined) {
-    version = schemaResult.content.version;
-  } else if (schemaResult.version !== undefined) {
-    version = schemaResult.version;
-  }
+  const version = extractSchemaServerRevision(schemaResult);
 
   if (schemaResult.content) {
     schema = typeof schemaResult.content === 'string' ? JSON.parse(schemaResult.content) : schemaResult.content;
@@ -4913,13 +5008,7 @@ async function mainUpdate(parsedArgs, authRef) {
 
   // 从返回结果中提取 schema 内容和版本号
   let schema;
-  let version = 1;
-
-  if (schemaResult.content && typeof schemaResult.content === 'object' && schemaResult.content.version !== undefined) {
-    version = schemaResult.content.version;
-  } else if (schemaResult.version !== undefined) {
-    version = schemaResult.version;
-  }
+  const version = extractSchemaServerRevision(schemaResult);
 
   if (schemaResult.content) {
     schema = typeof schemaResult.content === 'string' ? JSON.parse(schemaResult.content) : schemaResult.content;
@@ -5057,24 +5146,21 @@ async function mainUpdate(parsedArgs, authRef) {
 
 async function run(args) {
   const parsedArgs = parseArgs(args);
+  if (parsedArgs.help) {
+    return parsedArgs;
+  }
+  assertLegacyDirectWriteAllowed({
+    command: `create-form ${parsedArgs.mode}`,
+    resourceType: 'form',
+    action: parsedArgs.mode === 'create' ? 'create' : 'update',
+    appType: parsedArgs.appType,
+    formUuid: parsedArgs.formUuid,
+  }, { guardOptions: parsedArgs.legacyGuardOptions });
 
   step(1, t('common.step_login', 1));
-  let authData = loadAuthData();
-  if (!authData) {
-    warn(t('common.login_no_cache'));
-    authData = triggerLogin();
-  }
-  const baseUrl = resolveBaseUrl(authData);
-  const authRef = {
-    baseUrl,
-    authData,
-    authMode: authData.auth_mode || '',
-    authSource: authData.auth_source || '',
-    corpId: authData.corp_id || '',
-    userId: authData.user_id || '',
-  };
-  success(t('common.login_ready', baseUrl));
-  label('Locale:', resolveContentLocale({ locale: parsedArgs.contentLocale, baseUrl: baseUrl }));
+  const authRef = createAuthRef();
+  success(t('common.login_ready', authRef.baseUrl));
+  label('Locale:', resolveContentLocale({ locale: parsedArgs.contentLocale, baseUrl: authRef.baseUrl }));
 
   return dispatchCreateFormCommand(
     parsedArgs,
@@ -5099,6 +5185,7 @@ if (require.main === module) {
 }
 
 module.exports = {
+  createFormForLegacyProcess,
   run,
   parseArgs,
   _private: {