openyida 2026.7.22 → 2026.7.23-1

package/lib/app/create-form/definition-reader.js

@@ -17,6 +17,26 @@ function readJsonInput(value, options) {
   return fs.readFileSync(resolvedPath, 'utf-8');
 }
 
+function normalizeCreateFields(fields) {
+  if (
+    !Array.isArray(fields)
+    || fields.length === 0
+    || !fields.every((item) => (
+      item
+      && typeof item === 'object'
+      && !Array.isArray(item)
+      && String(item.action || '').toLowerCase() === 'add'
+      && item.field
+      && typeof item.field === 'object'
+      && !Array.isArray(item.field)
+    ))
+  ) {
+    return fields;
+  }
+
+  return fields.map((item) => item.field);
+}
+
 function createDefinitionReaders(dependencies) {
   const {
     fs,
@@ -43,9 +63,9 @@ function createDefinitionReaders(dependencies) {
       let columns = 1;
 
       if (Array.isArray(parsed)) {
-        fields = parsed;
+        fields = normalizeCreateFields(parsed);
       } else if (typeof parsed === 'object' && parsed !== null) {
-        fields = parsed.fields || [];
+        fields = normalizeCreateFields(parsed.fields || []);
         columns = parsed.columns !== undefined ? parsed.columns : 1;
         if (Array.isArray(parsed.validations)) {
           validations = parsed.validations;

package/lib/app/create-form.js

@@ -95,7 +95,11 @@ function parseOpenOption(inputArgs) {
 const OPTION_FIELD_TYPES = ['RadioField', 'SelectField', 'CheckboxField', 'MultiSelectField'];
 
 function throwCreateFormError(message, code, details) {
-  throw new CliError(message, {
+  throw createCreateFormError(message, code, details);
+}
+
+function createCreateFormError(message, code, details) {
+  return new CliError(message, {
     code: code || 'CREATE_FORM_FAILED',
     details,
   });
@@ -210,6 +214,28 @@ const FIELD_TYPE_ALIAS = {
   serialnumberfield: 'SerialNumberField',
 };
 
+const SUPPORTED_BUSINESS_FIELD_TYPES = [
+  'TextField',
+  'TextareaField',
+  'RadioField',
+  'SelectField',
+  'CheckboxField',
+  'MultiSelectField',
+  'NumberField',
+  'RateField',
+  'DateField',
+  'CascadeDateField',
+  'EmployeeField',
+  'DepartmentSelectField',
+  'CountrySelectField',
+  'AddressField',
+  'AttachmentField',
+  'ImageField',
+  'TableField',
+  'AssociationFormField',
+  'SerialNumberField',
+];
+
 const FORM_PRESENTATION_TYPE_ALIAS = {
   Divider: 'Divider',
   divider: 'Divider',
@@ -262,11 +288,28 @@ function normalizeComponentAlias(field) {
   return String(rawAlias).trim();
 }
 
+function readFormDefinitionType(field) {
+  if (!field || typeof field !== 'object' || Array.isArray(field)) {
+    return '';
+  }
+  if (field.type !== undefined && field.type !== null && field.type !== '') {
+    return String(field.type).trim();
+  }
+  if (field.componentName !== undefined && field.componentName !== null && field.componentName !== '') {
+    return String(field.componentName).trim();
+  }
+  if (field.componentType !== undefined && field.componentType !== null && field.componentType !== '') {
+    return String(field.componentType).trim();
+  }
+  return '';
+}
+
 function normalizeFormDefinitionType(field) {
-  if (!field || !field.type) {
+  const rawType = readFormDefinitionType(field);
+  if (!rawType) {
     return '';
   }
-  return FORM_PRESENTATION_TYPE_ALIAS[field.type] || FIELD_TYPE_ALIAS[field.type] || field.type;
+  return FORM_PRESENTATION_TYPE_ALIAS[rawType] || FIELD_TYPE_ALIAS[rawType] || rawType;
 }
 
 function isFormPresentationComponent(componentName) {
@@ -277,6 +320,194 @@ function isFormPresentationDefinition(field) {
   return isFormPresentationComponent(normalizeFormDefinitionType(field));
 }
 
+function isSupportedBusinessFieldType(componentName) {
+  return SUPPORTED_BUSINESS_FIELD_TYPES.indexOf(componentName) !== -1;
+}
+
+function getDefinitionDisplayName(field) {
+  if (!field || typeof field !== 'object') {
+    return '';
+  }
+  return field.label || field.title || readFormDefinitionType(field) || '';
+}
+
+function buildInvalidFieldDefinitionDetails(field, fieldPath, extra) {
+  const details = Object.assign({
+    path: fieldPath || 'fields',
+    label: field && typeof field === 'object' ? field.label : undefined,
+    title: field && typeof field === 'object' ? field.title : undefined,
+    type: readFormDefinitionType(field),
+  }, extra || {});
+  Object.keys(details).forEach(function (key) {
+    if (details[key] === undefined || details[key] === '') {
+      delete details[key];
+    }
+  });
+  return details;
+}
+
+function throwInvalidFieldDefinition(message, code, field, fieldPath, extra) {
+  throwCreateFormError(
+    message,
+    code || 'CREATE_FORM_INVALID_FIELD_DEFINITION',
+    buildInvalidFieldDefinitionDetails(field, fieldPath, extra)
+  );
+}
+
+function validatePlainFieldObject(field, fieldPath) {
+  if (!field || typeof field !== 'object' || Array.isArray(field)) {
+    throwInvalidFieldDefinition(
+      '字段定义必须是对象: ' + fieldPath,
+      'CREATE_FORM_INVALID_FIELD_DEFINITION',
+      field,
+      fieldPath
+    );
+  }
+}
+
+function validateContainerChildrenArray(field, fieldPath, componentName) {
+  if (field.children === undefined || field.children === null) {
+    return [];
+  }
+  if (!Array.isArray(field.children)) {
+    throwInvalidFieldDefinition(
+      componentName + '.children 必须是数组: ' + fieldPath,
+      'CREATE_FORM_INVALID_CONTAINER_CHILDREN',
+      field,
+      fieldPath,
+      { componentName }
+    );
+  }
+  return field.children;
+}
+
+function validateFieldDefinition(field, fieldPath, options) {
+  const validationOptions = options || {};
+  validatePlainFieldObject(field, fieldPath);
+
+  const componentName = normalizeFormDefinitionType(field);
+  if (!componentName) {
+    throwInvalidFieldDefinition(
+      '字段定义缺少 type/componentName/componentType: ' + fieldPath,
+      'CREATE_FORM_FIELD_TYPE_MISSING',
+      field,
+      fieldPath
+    );
+  }
+
+  if (isFormPresentationComponent(componentName)) {
+    if (validationOptions.disallowPresentation) {
+      throwInvalidFieldDefinition(
+        'TableField.children 不支持展示布局组件: ' + componentName,
+        'CREATE_FORM_TABLE_CHILD_PRESENTATION_UNSUPPORTED',
+        field,
+        fieldPath,
+        { componentName }
+      );
+    }
+    if (componentName === 'Column' && !validationOptions.allowColumn) {
+      throwInvalidFieldDefinition(
+        'Column 只能作为 ColumnContainer.children 的 Column 对象使用: ' + fieldPath,
+        'CREATE_FORM_COLUMN_OUTSIDE_COLUMNS_LAYOUT',
+        field,
+        fieldPath,
+        { componentName }
+      );
+    }
+    if (componentName === 'ColumnsLayout') {
+      validateColumnsLayoutDefinition(field, fieldPath);
+    } else if (componentName === 'PageSection') {
+      validateContainerChildrenArray(field, fieldPath, componentName).forEach(function (child, childIndex) {
+        validateFieldDefinition(child, fieldPath + '.children[' + childIndex + ']');
+      });
+    } else if (componentName === 'Column') {
+      validateContainerChildrenArray(field, fieldPath, componentName).forEach(function (child, childIndex) {
+        validateFieldDefinition(child, fieldPath + '.children[' + childIndex + ']');
+      });
+    }
+    return componentName;
+  }
+
+  if (!isSupportedBusinessFieldType(componentName)) {
+    throwInvalidFieldDefinition(
+      '不支持的字段类型: ' + componentName,
+      'CREATE_FORM_UNSUPPORTED_FIELD_TYPE',
+      field,
+      fieldPath,
+      { componentName }
+    );
+  }
+
+  if (componentName === 'TableField') {
+    validateTableFieldChildren(field, fieldPath, validationOptions);
+  }
+
+  return componentName;
+}
+
+function validateColumnsLayoutDefinition(field, fieldPath) {
+  const columns = validateContainerChildrenArray(field, fieldPath, 'ColumnsLayout');
+  columns.forEach(function (columnDefinition, columnIndex) {
+    const columnPath = fieldPath + '.children[' + columnIndex + ']';
+    if (Array.isArray(columnDefinition)) {
+      columnDefinition.forEach(function (child, childIndex) {
+        validateFieldDefinition(child, columnPath + '[' + childIndex + ']');
+      });
+      return;
+    }
+    if (
+      columnDefinition &&
+      typeof columnDefinition === 'object' &&
+      !Array.isArray(columnDefinition) &&
+      normalizeFormDefinitionType(columnDefinition) === 'Column'
+    ) {
+      validateFieldDefinition(columnDefinition, columnPath, { allowColumn: true });
+      return;
+    }
+    throwInvalidFieldDefinition(
+      'ColumnContainer.children 只能包含二维字段数组或 Column 对象: ' + columnPath,
+      'CREATE_FORM_INVALID_COLUMNS_LAYOUT_CHILDREN',
+      columnDefinition,
+      columnPath,
+      { componentName: normalizeFormDefinitionType(columnDefinition) || readFormDefinitionType(columnDefinition) }
+    );
+  });
+}
+
+function validateTableFieldChildren(field, fieldPath, options) {
+  if (field.children === undefined || field.children === null) {
+    return;
+  }
+  if (!Array.isArray(field.children)) {
+    throwInvalidFieldDefinition(
+      'TableField.children 必须是字段数组: ' + fieldPath,
+      'CREATE_FORM_INVALID_TABLE_CHILDREN',
+      field,
+      fieldPath,
+      { componentName: 'TableField' }
+    );
+  }
+  field.children.forEach(function (child, childIndex) {
+    validateFieldDefinition(child, fieldPath + '.children[' + childIndex + ']', Object.assign({}, options, {
+      disallowPresentation: true,
+    }));
+  });
+}
+
+function validateFormFieldDefinitions(fields, rootPath) {
+  if (!Array.isArray(fields)) {
+    throwInvalidFieldDefinition(
+      '字段定义必须是数组',
+      'CREATE_FORM_INVALID_FIELD_DEFINITION',
+      null,
+      rootPath || 'fields'
+    );
+  }
+  fields.forEach(function (field, index) {
+    validateFieldDefinition(field, (rootPath || 'fields') + '[' + index + ']');
+  });
+}
+
 function normalizeI18nValue(value, fallback) {
   if (value && typeof value === 'object') {
     return value;
@@ -465,7 +696,16 @@ function buildFormNodeComponents(fields) {
 // ── 生成字段组件 ─────────────────────────────────────
 
 function buildFieldComponent(field) {
-  const componentName = FIELD_TYPE_ALIAS[field.type] || field.type;
+  const componentName = normalizeFormDefinitionType(field);
+  if (!isSupportedBusinessFieldType(componentName)) {
+    throwInvalidFieldDefinition(
+      componentName ? '不支持的字段类型: ' + componentName : '字段定义缺少 type/componentName/componentType',
+      componentName ? 'CREATE_FORM_UNSUPPORTED_FIELD_TYPE' : 'CREATE_FORM_FIELD_TYPE_MISSING',
+      field,
+      'field',
+      { componentName }
+    );
+  }
   const fieldId = generateFieldId(componentName);
   const nodeId = nextNodeId();
 
@@ -3836,20 +4076,14 @@ function ensureComponentsMapForComponent(schema, component) {
   }
 }
 
-function getDefinitionDisplayName(field) {
-  if (!field || typeof field !== 'object') {
-    return '';
-  }
-  return field.label || field.title || field.type || '';
-}
-
 function countDataFieldDefinitions(fields) {
   let count = 0;
   (fields || []).forEach(function (field) {
     if (!field || typeof field !== 'object' || Array.isArray(field)) {
       return;
     }
-    if (!isFormPresentationDefinition(field)) {
+    const componentName = normalizeFormDefinitionType(field);
+    if (isSupportedBusinessFieldType(componentName)) {
       count++;
     }
     if (Array.isArray(field.children)) {
@@ -3881,11 +4115,12 @@ function applyChangesToSchema(schema, changes) {
     const actionDesc = t('create_form.action_label', changeIndex + 1, change.action);
 
     if (change.action === 'add') {
-      if (!change.field || !change.field.type || (!change.field.label && !change.field.title && !isFormPresentationDefinition(change.field))) {
+      if (!change.field || !normalizeFormDefinitionType(change.field) || (!change.field.label && !change.field.title && !isFormPresentationDefinition(change.field))) {
         warn(actionDesc + t('create_form.add_missing_field'));
         return;
       }
 
+      validateFormFieldDefinitions([change.field], 'changes[' + changeIndex + '].field');
       const newComponent = buildFormNodeComponent(change.field);
       ensureComponentsMapForComponent(schema, newComponent);
       const displayName = getDefinitionDisplayName(change.field);
@@ -4057,12 +4292,54 @@ function requireSchemaServerRevision(serverRevision, details) {
   return serverRevision;
 }
 
+function sanitizeFailureResult(result) {
+  if (!result || typeof result !== 'object') {
+    return result || null;
+  }
+  const sanitized = {};
+  ['success', 'errorMsg', 'errorCode', 'code', 'message', '__httpStatus', '__needLogin', '__csrfExpired'].forEach(function (key) {
+    if (Object.prototype.hasOwnProperty.call(result, key)) {
+      sanitized[key] = result[key];
+    }
+  });
+  return sanitized;
+}
+
+function buildCreateFormPostCreateFailurePayload(context) {
+  const errorObject = context && context.error;
+  const payload = {
+    success: false,
+    appType: context.appType,
+    formTitle: context.formTitle,
+    formUuid: context.formUuid,
+    stage: context.stage || 'postCreate',
+    error: errorObject && errorObject.message ? errorObject.message : String(errorObject || 'request failed'),
+    errorCode: errorObject && errorObject.code ? errorObject.code : (context.errorCode || 'CREATE_FORM_POST_CREATE_FAILED'),
+    retryAdvice: t('create_form.create_post_failure_retry_advice', context.appType, context.formTitle),
+  };
+  if (context.fieldCount !== undefined) {
+    payload.fieldCount = context.fieldCount;
+  }
+  return payload;
+}
+
+function emitCreateFormPostCreateFailure(context) {
+  const errorObject = context && context.error;
+  if (errorObject && errorObject.__openyidaPostCreateFailureEmitted) {
+    return;
+  }
+  console.log(JSON.stringify(buildCreateFormPostCreateFailurePayload(context)));
+  if (errorObject && typeof errorObject === 'object') {
+    errorObject.__openyidaPostCreateFailureEmitted = true;
+  }
+}
+
 // ── 保存 Schema 并更新表单配置（create/update 共用）──
 //
 // 封装了 saveFormSchema + updateFormConfig 两步，以及各自的 302 自动重登录重试。
 // 返回 { saveResult, configResult }。
 
-async function saveSchemaAndUpdateConfig(authRef, appType, formUuid, schema, version, stepOffset) {
+async function saveSchemaAndUpdateConfig(authRef, appType, formUuid, schema, version, stepOffset, failureContext) {
   const saveStep = stepOffset || 4;
   const configStep = saveStep + 1;
 
@@ -4092,12 +4369,20 @@ async function saveSchemaAndUpdateConfig(authRef, appType, formUuid, schema, ver
     if (saveResult && !saveResult.__needLogin) {
       hint(t('common.response_detail', JSON.stringify(saveResult, null, 2)));
     }
-    console.log(JSON.stringify({ success: false, formUuid: formUuid, error: saveErrorMsg }));
-    throwCreateFormError(saveErrorMsg, 'CREATE_FORM_SAVE_SCHEMA_FAILED', {
+    const saveError = createCreateFormError(saveErrorMsg, 'CREATE_FORM_SAVE_SCHEMA_FAILED', {
       appType,
       formUuid,
-      result: saveResult,
+      result: sanitizeFailureResult(saveResult),
     });
+    if (failureContext) {
+      emitCreateFormPostCreateFailure(Object.assign({}, failureContext, {
+        stage: 'saveFormSchema',
+        error: saveError,
+      }));
+    } else {
+      console.log(JSON.stringify({ success: false, formUuid: formUuid, error: saveErrorMsg }));
+    }
+    throw saveError;
   }
 
   success(t('create_form.schema_saved'));
@@ -4127,6 +4412,7 @@ async function mainCreate(parsedArgs, authRef) {
 
   step(2, t('create_form.step_read_fields', 2));
   const { fields, columns, validations } = readFieldsDefinition(fieldsJsonOrFile);
+  validateFormFieldDefinitions(fields);
   const fieldCount = countDataFieldDefinitions(fields);
   success(t('create_form.fields_loaded', fieldCount));
   label('Columns:', String(columns));
@@ -4158,30 +4444,62 @@ 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);
+  let configResult;
+  let postCreateStage = 'getFormSchema';
+  try {
+    const shellSchemaResult = await requestWithAutoLogin(function (auth) {
+      return sendGetRequest(
+        auth.baseUrl,
+        buildApiPath(appType, 'getFormSchema', { prefix: '_view', namespace: 'alibaba' }),
+        { formUuid: formUuid, schemaVersion: 'V5' }
+      );
+    }, authRef);
+    if (!shellSchemaResult || shellSchemaResult.success === false || shellSchemaResult.__needLogin || shellSchemaResult.__csrfExpired) {
+      const schemaErrorMsg = shellSchemaResult
+        ? shellSchemaResult.errorMsg || shellSchemaResult.message || t('common.unknown_error')
+        : t('common.request_failed');
+      throwCreateFormError(schemaErrorMsg, 'CREATE_FORM_GET_SCHEMA_FAILED', {
+        appType,
+        formUuid,
+        result: sanitizeFailureResult(shellSchemaResult),
+      });
+    }
+    const serverRevision = extractSchemaServerRevision(shellSchemaResult);
 
-  // Step 4 & 5: 生成 Schema 并保存，然后更新表单配置
-  const corpId = resolveCorpId(authRef.authData);
-  if (!corpId) {
-    warn(t('create_form.no_corp_id_warning'));
-  } else {
-    info(t('create_form.corp_id_ok', corpId));
-  }
+    // Step 4 & 5: 生成 Schema 并保存，然后更新表单配置
+    const corpId = resolveCorpId(authRef.authData);
+    if (!corpId) {
+      warn(t('create_form.no_corp_id_warning'));
+    } else {
+      info(t('create_form.corp_id_ok', corpId));
+    }
 
-  const schema = buildFormSchema(formTitle, fields, formUuid, corpId, appType, layout, theme, labelAlign);
-  const createValidationRules = collectSmartValidationRulesFromFields(fields).concat(validations || []);
-  if (createValidationRules.length > 0) {
-    const appliedValidations = applySmartValidations(schema, createValidationRules);
-    info('已为创建表单写入 ' + appliedValidations.appliedRules.length + ' 条字段校验');
+    postCreateStage = 'buildFormSchema';
+    const schema = buildFormSchema(formTitle, fields, formUuid, corpId, appType, layout, theme, labelAlign);
+    const createValidationRules = collectSmartValidationRulesFromFields(fields).concat(validations || []);
+    if (createValidationRules.length > 0) {
+      const appliedValidations = applySmartValidations(schema, createValidationRules);
+      info('已为创建表单写入 ' + appliedValidations.appliedRules.length + ' 条字段校验');
+    }
+    postCreateStage = 'saveSchemaAndUpdateConfig';
+    const saveAndConfigResult = await saveSchemaAndUpdateConfig(authRef, appType, formUuid, schema, serverRevision, 4, {
+      appType,
+      formTitle,
+      formUuid,
+      fieldCount,
+    });
+    configResult = saveAndConfigResult.configResult;
+  } catch (err) {
+    emitCreateFormPostCreateFailure({
+      appType,
+      formTitle,
+      formUuid,
+      fieldCount,
+      stage: postCreateStage,
+      error: err,
+    });
+    throw err;
   }
-  const { configResult } = await saveSchemaAndUpdateConfig(authRef, appType, formUuid, schema, serverRevision, 4);
 
   // 输出结果
   const formUrl = authRef.baseUrl + '/' + appType + '/workbench/' + formUuid;
@@ -4203,11 +4521,25 @@ async function mainCreate(parsedArgs, authRef) {
       ['URL', formUrl],
     ]);
     hint(t('create_form.schema_ok_config_failed'));
-    console.log(JSON.stringify(withBrowserHandoff(
-      { success: true, formUuid, formTitle, appType, fieldCount, url: formUrl, configWarning: configErrorMsg },
-      formUrl,
-      { stage: 'create_form_success', title: formTitle },
-      parsedArgs.browserOpenMode
+    const configError = createCreateFormError(configErrorMsg, 'CREATE_FORM_UPDATE_CONFIG_FAILED', {
+      appType,
+      formUuid,
+      result: sanitizeFailureResult(configResult),
+    });
+    console.log(JSON.stringify(Object.assign(
+      buildCreateFormPostCreateFailurePayload({
+        appType,
+        formTitle,
+        formUuid,
+        fieldCount,
+        stage: 'updateFormConfig',
+        error: configError,
+      }),
+      {
+        url: formUrl,
+        schemaSaved: true,
+        configWarning: configErrorMsg,
+      }
     )));
   }
 }
@@ -4228,6 +4560,7 @@ async function createFormForLegacyProcess(context, input) {
 
   const { appType, formTitle, fieldsJsonOrFile, layout, theme, labelAlign } = parsedArgs;
   const { fields, validations } = readFieldsDefinition(fieldsJsonOrFile);
+  validateFormFieldDefinitions(fields);
   const fieldCount = countDataFieldDefinitions(fields);
   const createResult = await requestWithAutoLogin(function (auth) {
     return sendPostRequest(
@@ -5193,6 +5526,8 @@ module.exports = {
     buildFormNodeComponent,
     countDataFieldDefinitions,
     collectComponentNames,
+    normalizeFormDefinitionType,
+    validateFormFieldDefinitions,
     ensureDividerThemeAction,
     applyChangesToSchema,
   },

package/lib/app/generate-page.js

@@ -514,6 +514,40 @@ function getCanvasDistPath(outputPath) {
   return path.posix.join(distDir, distName);
 }
 
+function isOpenYidaProjectCwd(cwd) {
+  const currentDir = cwd || process.cwd();
+  return path.basename(currentDir) === 'project' && (
+    fs.existsSync(path.join(currentDir, 'config.json')) ||
+    fs.existsSync(path.join(currentDir, 'pages'))
+  );
+}
+
+function normalizeOutputPathForProjectCwd(output, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const rawOutput = String(output || '');
+  if (!rawOutput || path.isAbsolute(rawOutput)) {
+    return {
+      outputPath: path.resolve(cwd, rawOutput),
+      strippedProjectPrefix: false,
+      requestedOutput: rawOutput,
+      normalizedOutput: rawOutput,
+    };
+  }
+
+  const slashOutput = rawOutput.replace(/\\/g, '/').replace(/^\.\//, '');
+  const shouldStrip = isOpenYidaProjectCwd(cwd) && (
+    slashOutput.startsWith('project/pages/') ||
+    slashOutput.startsWith('project/.cache/')
+  );
+  const normalizedOutput = shouldStrip ? slashOutput.slice('project/'.length) : rawOutput;
+  return {
+    outputPath: path.resolve(cwd, normalizedOutput),
+    strippedProjectPrefix: shouldStrip,
+    requestedOutput: rawOutput,
+    normalizedOutput,
+  };
+}
+
 async function run(args) {
   const options = parseArgs(args || []);
   const spec = loadSpec(options.spec);
@@ -533,7 +567,10 @@ async function run(args) {
     error(t('generate_page.template_not_found', templateFile));
   }
 
-  const outputPath = path.resolve(options.output || spec.output || (mode === 'canvas' ? templateConfig.defaultCanvasOutput : templateConfig.defaultNativeOutput));
+  const outputResolution = normalizeOutputPathForProjectCwd(
+    options.output || spec.output || (mode === 'canvas' ? templateConfig.defaultCanvasOutput : templateConfig.defaultNativeOutput)
+  );
+  const outputPath = outputResolution.outputPath;
   const manifestPath = getManifestPath(outputPath);
   const templateSource = fs.readFileSync(templateFile, 'utf-8');
   const ir = normalizePageSpec(spec, {
@@ -561,6 +598,9 @@ async function run(args) {
   fs.writeFileSync(outputPath, outputSource, 'utf-8');
   fs.writeFileSync(manifestPath, `${JSON.stringify(ir, null, 2)}\n`, 'utf-8');
 
+  if (outputResolution.strippedProjectPrefix) {
+    warn(t('generate_page.output_project_prefix_stripped', outputResolution.requestedOutput, outputResolution.normalizedOutput));
+  }
   success(t('generate_page.done', outputPath));
   hint(t('generate_page.hint'));
   reportMaterialStatus(materialPrecheck);
@@ -641,6 +681,7 @@ module.exports = {
   escapeJsStringValue,
   getManifestPath,
   getCanvasDistPath,
+  normalizeOutputPathForProjectCwd,
   inferMode,
   inferTemplateName,
 };

package/lib/app/services/form-compiler.js

@@ -509,6 +509,9 @@ const SUPPORTED_FIELD_TYPES = Object.freeze([
 ]);
 
 function normalizeFieldType(fieldType) {
+  if (fieldType === undefined || fieldType === null || fieldType === '') {
+    return '';
+  }
   return FIELD_TYPE_ALIAS[fieldType] || fieldType;
 }
 
@@ -520,6 +523,57 @@ function isOptionFieldType(fieldType) {
   return OPTION_FIELD_TYPES.indexOf(normalizeFieldType(fieldType)) !== -1;
 }
 
+function readFieldDefinitionType(field) {
+  if (!field || typeof field !== 'object' || Array.isArray(field)) {
+    return '';
+  }
+  if (field.type !== undefined && field.type !== null && field.type !== '') {
+    return String(field.type).trim();
+  }
+  if (field.componentType !== undefined && field.componentType !== null && field.componentType !== '') {
+    return String(field.componentType).trim();
+  }
+  if (field.componentName !== undefined && field.componentName !== null && field.componentName !== '') {
+    return String(field.componentName).trim();
+  }
+  return '';
+}
+
+function assertSupportedFieldDefinition(field, details) {
+  if (!field || typeof field !== 'object' || Array.isArray(field)) {
+    throw createFormCompilerError(
+      '字段定义必须是对象',
+      'FORM_COMPILER_INVALID_DEFINITION',
+      details
+    );
+  }
+  const rawType = readFieldDefinitionType(field);
+  const componentName = normalizeFieldType(rawType);
+  if (!componentName) {
+    throw createFormCompilerError(
+      '字段定义缺少 type/componentType/componentName',
+      'FORM_COMPILER_FIELD_TYPE_MISSING',
+      Object.assign({
+        label: field.label,
+        title: field.title,
+      }, details)
+    );
+  }
+  if (!isSupportedFieldType(componentName)) {
+    throw createFormCompilerError(
+      '不支持的字段类型: ' + componentName,
+      'FORM_COMPILER_UNSUPPORTED_FIELD_TYPE',
+      Object.assign({
+        label: field.label,
+        title: field.title,
+        type: rawType,
+        componentName,
+      }, details)
+    );
+  }
+  return componentName;
+}
+
 const COMPONENT_ALIAS_META = Symbol('openyida.componentAlias');
 
 function normalizeComponentAlias(field) {
@@ -544,7 +598,9 @@ function normalizeComponentAlias(field) {
 
 function buildFieldComponent(field, options) {
   const compilerOptions = createCompilerOptions(options);
-  const componentName = normalizeFieldType(field.type);
+  const componentName = assertSupportedFieldDefinition(field, {
+    semanticPath: compilerOptions.semanticPath,
+  });
   const semanticKey = normalizeSemanticKey(field);
   if (semanticKey && compilerOptions.requireParentSemanticPath && !compilerOptions.semanticPath) {
     throw createFormCompilerError(
@@ -1139,10 +1195,16 @@ function buildFieldComponent(field, options) {
 function collectComponentNames(fields) {
   const names = new Set(['Page', 'RootHeader', 'RootContent', 'RootFooter', 'FooterYida', 'FormContainer']);
   fields.forEach(function (field) {
-    names.add(field.type);
-    if (field.type === 'TableField' && field.children) {
+    const componentName = normalizeFieldType(readFieldDefinitionType(field));
+    if (componentName) {
+      names.add(componentName);
+    }
+    if (componentName === 'TableField' && field.children) {
       field.children.forEach(function (child) {
-        names.add(child.type);
+        const childComponentName = normalizeFieldType(readFieldDefinitionType(child));
+        if (childComponentName) {
+          names.add(childComponentName);
+        }
       });
     }
   });

package/lib/core/locales/en.js

@@ -721,6 +721,7 @@ Examples:
     config_failed: '  ⚠️  Config update failed: {0}',
     schema_ok_config_failed: '  Schema saved, but config update failed',
     schema_saved_config_failed: '  Schema saved, but config update failed',
+    create_post_failure_retry_advice: 'Do not repeat create directly. First run openyida list-forms {0} --keyword "{1}" to check for an existing same-title form; if this run already created a blank/existing form, prefer create-form update or a future --resume-form-uuid flow.',
     error: '\n❌ Error: {0}',
     usage_create: 'Usage: openyida create-form create <appType> <formTitle> <fieldsJsonFile>',
     example_create: 'Example: openyida create-form create "APP_XXX" "Employee Info" .cache/openyida/forms/employee-fields.json',
@@ -1073,6 +1074,7 @@ Examples:
     unknown_template: 'Unknown page template: {0}',
     available_templates: 'Available templates: {0}',
     template_not_found: 'Template file not found: {0}',
+    output_project_prefix_stripped: 'Current directory is already an OpenYida project; output path was adjusted from {0} to {1} to avoid project/project.',
     done: 'Page generated: {0}',
     hint: 'Next run openyida compile <file>, or pass --compile to compile immediately.',
     success: 'Page generation complete',

package/lib/core/locales/zh.js

@@ -693,6 +693,7 @@ openyida - 宜搭命令行工具
     config_failed: '  ⚠️  配置更新失败: {0}',
     schema_ok_config_failed: '  Schema 已保存，但配置更新失败',
     schema_saved_config_failed: '  Schema 已保存，但配置更新失败',
+    create_post_failure_retry_advice: '不要直接重复 create。先运行 openyida list-forms {0} --keyword "{1}" 确认同名表单；若是本轮创建的空白/已有表单，优先使用 create-form update 或后续 --resume-form-uuid 复用。',
     error: '\n❌ 错误: {0}',
     usage_create: '用法: openyida create-form create <appType> <formTitle> <fieldsJsonFile>',
     example_create: '示例：openyida create-form create "APP_XXX" "员工信息登记" .cache/openyida/forms/employee-fields.json',
@@ -1067,6 +1068,7 @@ openyida - 宜搭命令行工具
     unknown_template: '未知页面模板：{0}',
     available_templates: '可用模板：{0}',
     template_not_found: '模板文件不存在：{0}',
+    output_project_prefix_stripped: '检测到当前目录已是 OpenYida project，已将输出路径从 {0} 调整为 {1}，避免生成 project/project。',
     done: '页面已生成：{0}',
     hint: '建议继续运行 openyida compile <file> 或使用 --compile 直接编译校验。',
     success: '页面生成完成',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openyida",
-  "version": "2026.7.22",
+  "version": "2026.7.23-1",
   "description": "OpenYida CLI - 宜搭低代码 AI 开发工具（安装即用，零配置）",
   "bin": {
     "openyida": "bin/yida.js",

package/scripts/postinstall.js

@@ -259,6 +259,10 @@ openyida copy
 
 fast_build 页面源码默认不得使用 \`this.dataSourceMap.*\`，除非本轮已经明确创建并绑定设计器数据源；默认使用入口型页面或 \`this.utils.yida.*\` 查询已创建表单。
 
+fast_build 创建/解析多个表单后，页面阶段需要字段映射时，对每个目标表单默认只执行一次 \`openyida get-schema <appType> <formUuid> --field-map-json\`，读取完整 JSON 并写入/复用 \`.cache/<项目名>-schema.json\`；不要用 \`head\` / \`tail\` / \`grep\` 截断 schema stdout 后重复拉取。
+
+Canvas 页面实现二选一：走模板路径时先写业务化 \`page-spec.json\` 再 \`openyida generate-page ... --spec ... --compile\`，之后只做必要小范围 Edit/patch；如果已经明确最终页面结构，跳过 \`generate-page\`，直接 Write 最终 \`.canvas.jsx\`。不要 generate-page 后马上 Read 大段源码并全量 Write 覆盖同一路径。
+
 不要默认加载 \`yida-page-uiux\`、\`yida-data-source-connectors\`、\`yida-data-management\`、\`yida-nav-group\`、\`yida-dashboard\`，也不要默认做示例数据、导航整理、截图验收、公开访问、长 PRD 或深读 references；这些只在用户明确要求或 \`full_demo\` / \`deep_design\` 时执行。
 
 ## 子技能目录

package/yida-skills/SKILL.md

@@ -149,6 +149,10 @@ schema-managed create/update 必须等待用户对当前 `planId` 显式批准
 
 **Canvas 数据边界**：完整应用/真实交付页如果展示列表、看板或详情记录，必须优先把本轮真实 `appType/formUuid/fieldId` 写入 `page-spec.json` 的 `dataBinding.mode=form`；需要演示记录时先写入真实表单再读取。未接真实表单且未写入 demo records 时，页面展示空态/入口，不用前端 seedRows 冒充业务数据。
 
+**Schema 获取去重**：完整应用创建/解析多个表单后，页面阶段需要字段映射时，对每个目标表单默认只执行一次 `openyida get-schema <appType> <formUuid> --field-map-json`，读取完整 JSON 并合并到 `.cache/<项目名>-schema.json` 复用。不要用 `head`/`tail`/`grep` 截断 get-schema stdout 作为字段证据，也不要因此对同一表单重复拉取多轮 schema。
+
+**Canvas 生成路径二选一**：走模板路径时，先写业务化 `page-spec.json` 再 `openyida generate-page ... --spec ... --compile`，后续只读 manifest/摘要并小范围 Edit；不要立即 Read 大段源码再全量 Write 覆盖同一路径。若已经明确最终页面结构，跳过 `generate-page` 直接 Write 最终 `.canvas.jsx`。
+
 **doneWhen**：`yida-app` 发布主页面成功并输出可访问 URL。到这里默认完成；不要发布后继续 TaskCreate、重复读技能或继续规划。
 
 **optionalAfterDone**：导航整理、示例数据、公开访问、截图验证、深度视觉方向、数据源/连接器深度接入、报表/大屏，只在用户明确要求或 `yida-app` 模式为 `full_demo` / `deep_design` 时执行。
@@ -227,12 +231,13 @@ schema-managed create/update 必须等待用户对当前 `planId` 显式批准
 4. **页面源码修改必须发布闭环**：只要本轮 Write/Edit/Create 了页面源码 `project/pages/src/*.{canvas.jsx,canvas.tsx,oyd.jsx,jsx,tsx}`（含完整搭建、补齐、已有页面 update path、单点优化），final 前必须看到成功的 `openyida publish <source> <appType> <displayPageFormUuid>` 命令结果；本地文件编辑、diff、本地校验或编译只证明源码可发布，不等于远端页面已更新。若没有 publish 成功证据，final 只能说“源码已修改，尚未发布”，禁止说“页面已更新 / 已重新发布 / 已上线”。
 5. **命令输入文件禁止 shell 写入**：当 OpenYida 命令需要 JSON/YAML/CSV/config/script 文件参数时，先使用当前 agent 运行时提供的结构化文件写入工具（如 create_file / Write / file edit tool）创建文件，再把路径传给命令；禁止用 shell heredoc、`cat`/`echo`/`printf`/`tee` 加输出重定向，或把命令 stdout 重定向成业务文件。
 6. **读文件少用 Bash 噪声**：读取或定位 workspace 文件优先用宿主的 Read / Glob / Grep；OpenYida CLI 已返回成功 JSON、URL 或 `formUuid/appType` 时，不要再用 Bash `cat`/`ls` 做无意义复核。
+7. **OpenYida CLI 不吞诊断**：不要给 `openyida` 命令加 `2>/dev/null`；失败时保留 stdout/stderr（必要时用 `2>&1` 合并诊断）。遇到 DENIED 或同一命令重复失败，先换策略、改输入或重做只读确认，不要盲目微调后重跑。
 
 ### 重要规则（IMPORTANT，影响质量/性能/可维护性）
 
 1. **按阶段加载必要技能**：按意图选 1 个主技能；完整应用按阶段加载当下唯一需要的子技能，禁止并发批量读取多个 `SKILL.md` 或预读未来阶段技能。
 2. **Resource-First**：任何 legacy 写操作前先解析本轮显式资源、agent bound context、workspace cache/config、历史上下文；已有目标资源时默认修改/补齐/发布，只有目标缺失且意图允许创建时才加载 create 类技能。
-3. **优先复用 direct 映射**：仅对 direct/standalone 资源，已有 `.cache/<项目名>-schema.json` 中可确认新鲜的 `appType`/`formUuid`/`fieldId` 可复用；该文件不是 Schema-as-Code state，也不是远端真相。字段缺失、重名或结构变化时执行 `get-schema --compact --resolve-fields`，不得猜测。
+3. **优先复用 direct 映射**：仅对 direct/standalone 资源，已有 `.cache/<项目名>-schema.json` 中可确认新鲜的 `appType`/`formUuid`/`fieldId` 可复用；该文件不是 Schema-as-Code state，也不是远端真相。字段缺失、重名或结构变化时执行 `get-schema --compact --resolve-fields`；完整应用页面需要多字段/多表单映射时每表单一次性执行 `get-schema --field-map-json` 并缓存完整字段摘要。不得猜测字段 ID，也不要用 `head`/`tail`/`grep` 截断 schema stdout 当证据。
 4. **模板优先**：复杂产物先用 `openyida sample` 或现有示例生成骨架，再做最小改动。
 5. **配置承载优先于代码**：字段/公式/联动/报表/审批/集成交给对应技能，自定义页面只做展示与胶水。
 6. **数据性能优先**：统计聚合用 `yida-report` 服务端聚合，不在前端拉全量后自行聚合。

package/yida-skills/skills/yida-app/SKILL.md

@@ -36,6 +36,7 @@ description: 宜搭完整应用开发编排技能。对普通 OpenYida 应用做
 - 只有用户只给应用名称、存在多个候选、resource context 冲突，或需要诊断目标 app 访问失败时，才运行 `openyida app-list [--size N]`。
 - 已知 `appType` 后，查询该应用下表单/页面用 `openyida list-forms <appType> [--keyword <text>]`；选择页面发布目标时只用 `formType=display`。
 - 查询表单/页面 Schema、字段 ID 或批量字段摘要用 `openyida get-schema <appType> <formUuid|--all> ...`。
+- 完整应用页面阶段如果需要多个表单的字段映射，默认对每个目标业务表单执行一次 `openyida get-schema <appType> <formUuid> --field-map-json`，读取完整 JSON 并合并到 `.cache/<项目名>-schema.json`；不要对同一表单用 `tail/head/grep` 截断 stdout 后再重复拉取。
 - 阶段 0 禁止编造 `list-apps` / `get-app`；也不要把 `--app-type` / `--form-uuid` 当成 `list-forms` 或 `get-schema` 的参数。按目的在 `app-list`、`list-forms`、`get-schema` 三者中选择。
 
 该阶段只决定普通 OpenYida resource context；schema-managed 路径仍以 schema CLI 的 validate/plan/apply 结果为准。schema-managed create/update 必须停在当前 `planId`，等待用户显式批准后才可执行 `apply`；`nextAction`、错误恢复或本技能判断都不能授予 `mixed/write`。Phase 1 中 report、automation、page config、delete、pull 不从 Manifest fallback 到本技能的 legacy workflow。
@@ -91,6 +92,7 @@ description: 宜搭完整应用开发编排技能。对普通 OpenYida 应用做
               ↓
 [Step 6] 编写自定义页面代码 → 默认 use_skill("yida-canvas-custom-page", "生成 Code Canvas 主页面")
               ↓      先写业务化 page-spec.json，再 openyida generate-page <模板> --theme-profile yida-app-theme --theme-scope page --spec <page-spec.json> --compile
+              ↓      字段映射来自 `.cache/<项目名>-schema.json`；同一表单不要重复 get-schema，除非刚修改字段或缓存不完整
               ↓      本轮已创建/解析业务表单且页面需要列表/看板/详情数据时，必须在 spec.dataBinding 写 mode=form + 真实 appType/formUuid/fieldId；深度接入再加载 yida-canvas-data-binding
               ↓      明确要求普通自定义页面 JSX/Jsx 组件链路，或强依赖 this.$ / this.utils.yida.* / this.dataSourceMap 等实例桥时选择 yida-custom-page
               ↓
@@ -154,11 +156,16 @@ UI 不是独立替代主流程的步骤，而是按模式插入到页面生成
 | `yida-data-management` | `openyida sample yida-data-management form-field-template` | 表单字段定义和数据插入 |
 | `yida-create-app` | `openyida sample yida-create-app ipd-app-template` | 完整应用创建示例 |
 
-代码生成前必须：
+页面实现必须二选一：
+
+- **模板路径**：先写业务化 `page-spec.json`，再执行 `openyida generate-page ... --spec <page-spec.json> --compile`。生成后只读取 `.openyida-page.json` / CLI 摘要判断 `domainFidelity` 和 dataBinding 状态；若需要补业务语义或样式，基于生成文件做小范围 Edit/patch。禁止在 `generate-page` 后立即 Read 500+ 行源码再全量 Write 覆盖同一路径。
+- **手写路径**：如果已经明确最终页面结构、数据桥和视觉细节，跳过 `generate-page`，直接 Write 最终 `.canvas.jsx`，再做本地快检和 publish。不要先生成模板再把模板完全覆盖。
+
+选择模板路径时必须：
 
 1. 先从 PRD 提炼当前业务自己的 page spec；
 2. 再执行对应的 `openyida generate-page` 命令生成 Code Canvas 骨架；
-3. 读取 manifest 的 `domainFidelity`，若仍是 sample-reference / draft，则补 spec 或改源码；
+3. 读取 manifest / CLI 摘要的 `domainFidelity`，若仍是 sample-reference / draft，则补 spec 或小范围改源码；
 4. 以模板为基础扩展交互和真实数据；
 5. 验证所有参数名称与 CLI 一致。
 
@@ -171,7 +178,7 @@ UI 不是独立替代主流程的步骤，而是按模式插入到页面生成
 | 0. 解析资源上下文 | 无 | 合并本轮显式资源、agent bound context、workspace config/cache、会话历史；本轮显式目标覆盖 bound context；判定 app/page/form/process 的 `source` 和 `allowCreate` | 明确复用、创建缺口或需要 ask_human |
 | 1. resolve app + app name | `yida-create-app` 仅在 app 缺失且允许创建时加载；`openyida update-app` 仅用于预创建占位 app 改名 | 已有 `appType`/应用 URL/bound app 时直接复用；若 bound/precreated app 仍是占位名，在语义名稳定后执行 `openyida update-app <appType> --name "<语义应用名>"`；否则创建应用并提取真实 `appType` | 拿到真实目标 `appType`，预创建占位 app 已改成语义名或明确跳过，且不会重复创建同类 app |
 | 2. 记录最小需求 | 无 | 写 `prd/<项目名>.md`：只记录 MVP 假设、核心表单/页面、完成标准；写/更新 `.cache/<项目名>-schema.json` standalone 映射；不要写长 PRD | 业务语义和 ID 存储位置明确 |
-| 3. resolve forms | `yida-create-form-page` | 已有目标表单时 update/patch/rule/bind-datasource；缺少支撑 MVP 的核心表单且允许创建时才 create；字段配置文件写入 `.cache/openyida/<项目名>/` | 拿到或确认表单 `formUuid` 和真实 `fieldId` |
+| 3. resolve forms | `yida-create-form-page` | 已有目标表单时 update/patch/rule/bind-datasource；缺少支撑 MVP 的核心表单且允许创建时才 create；字段配置文件写入 `.cache/openyida/<项目名>/`；创建/解析多个表单后，对每个目标表单最多一次性获取完整 `--field-map-json` 并合并写回 `.cache/<项目名>-schema.json` | 拿到或确认表单 `formUuid` 和真实 `fieldId` |
 | 4. resolve main page | `yida-create-page` 仅在主页面缺失且允许创建时加载 | 已有页面 URL / `formUuid` / bound page 时直接作为主页面；否则创建一个用户主入口 display page | 拿到真实目标页面 `formUuid`，且不会重复创建页面 |
 | 5. 编写/更新页面 | 默认 `yida-canvas-custom-page`；明确要求 JSX/Jsx 组件链路或实例桥强依赖时选择 `yida-custom-page` | 生成或修改主页面源码；只实现 MVP 首屏和核心操作。可用已解析表单链接、真实空态、表单入口和轻量指标口径完成主页面；若展示业务列表/看板/详情记录，必须接本轮真实表单 `dataBinding.mode=form`，或先写入 demo records 后再读取；不要加载视觉/密度/报表/数据源等额外技能 | 本地源码通过对应页面技能的基础校验；未执行 publish 时仍是“源码已修改，尚未发布” |
 | 6. 发布页面 | `yida-publish-page` | 按页面链路校验后发布到已解析主页面：Canvas `.canvas.jsx` 使用 `openyida publish` 的 Canvas 编译阶段或 `compileCanvasLocal` 快检；普通自定义页面 `.oyd.jsx` / `.jsx` 跑 `check-page` / `compile`；再执行 `openyida publish <source> <appType> <displayPageFormUuid>` 发布主页面 | 发布成功并获得可访问 URL |
@@ -272,6 +279,7 @@ UI 不是独立替代主流程的步骤，而是按模式插入到页面生成
 ## 错误处理
 
 - 不编造 `appType`、`formUuid`、`fieldId`、`reportId`。
+- OpenYida CLI 不要加 `2>/dev/null`；失败时保留 stdout/stderr 诊断。遇到 DENIED 或同一命令重复失败，先换策略、修改输入文件/参数/登录态/组织或重新只读取证，再重试。
 - 同一命令失败后，必须改变登录态、组织、参数、输入文件或字段 ID 后才能重试；禁止无修改连续重试。
 - corpId 与目标组织不一致时先停下，让用户选择重新登录或在当前组织继续。
 - 已有目标 app/page/form/process 时默认复用；只有用户明确要求新建另一个同类资源，或目标缺失且本次意图允许创建时，才加载 create 类子技能。

package/yida-skills/skills/yida-canvas-custom-page/SKILL.md

@@ -105,6 +105,7 @@ openyida sample yida-canvas-custom-page portal-native-components --output projec
 8. **门户运行态组件要补必需 props 和局部降级**：`QuickAccessCard` / `RecentlyUsedCard` 必须传 `theme="row-white"` 等必需 props，避免运行态读取 `theme.includes(...)` 报错；所有门户/字段/上传增强组件外层加局部 ErrorBoundary，单个组件不兼容时只降级该块，不让整页进入 Canvas 错误态。
 9. **自定义主题必须页面内注入**：`--theme` 只接受平台预置 key；如果页面设计使用非预置主题（例如活力橙、深玫红、自定义暗黑金），Canvas 页面必须在自身源码中注入 `style#yida-global-theme` 或等价 scoped CSS vars，并在根节点设置 `data-theme-scope="page"`。官方 sample 每个页面都要做，避免宿主应用 `black` 主题把页面染成黑灰。
 10. **真实交付不使用前端 seed 冒充业务数据**：`openyida sample` 原样发布可以保留 sample/seed 数据，但必须在页面上标注为 sample/seed。完整应用或真实交付页只要需要列表、看板、详情记录，并且本轮已经创建/解析业务表单，就必须在 `page-spec.json` 写入 `dataBinding.mode=form`、真实 `appType/formUuid` 和字段映射，让页面从表单读取。若需要演示数据，先通过表单数据写入链路创建 demo/mock records，再由 Canvas 读取这些真实表单记录；未写入 demo records 且没有真实数据时展示空态、表单入口、刷新/登记按钮。
+11. **页面生成二选一**：选择模板路径时，`openyida generate-page ... --spec ... --compile` 之后只读取 CLI 摘要或 `.openyida-page.json` 判断 `domainFidelity` / dataBinding，并对生成源码做小范围 Edit/patch；禁止立刻 Read 大段源码后全量 Write 覆盖同一路径。选择手写路径时，直接 Write 最终 `.canvas.jsx` 并快检/发布，不要先跑 `generate-page` 再完全覆盖。
 
 ## 数据真实性边界
 
@@ -165,12 +166,14 @@ openyida login --check-only --json
 # 2. 如需新页面，先创建空白自定义页拿 formUuid
 openyida create-page <appType> "<页面名>"
 
-# 3. 生成或复制 Canvas 源码
+# 3. 生成或编写 Canvas 源码
+# 模板路径：生成后基于 manifest/摘要和小范围 patch 演进，不全量覆盖生成文件。
 openyida generate-page workbench-home --theme-profile yida-app-theme --theme-scope page --output project/pages/src/workbench-home.canvas.jsx --compile
 openyida generate-page dashboard-overview --theme-profile yida-app-theme --theme-scope page --output project/pages/src/dashboard-overview.canvas.jsx --compile
 openyida generate-page portal-shell-home --theme-profile yida-app-theme --theme-scope page --output project/pages/src/portal-shell-home.canvas.jsx --compile
 openyida sample yida-canvas-custom-page native-components-smoke --output project/pages/src/native-components-smoke.canvas.jsx
 openyida sample yida-canvas-custom-page portal-native-components --output project/pages/src/portal-native-components.canvas.jsx
+# 手写路径：已明确最终页面结构时，跳过 generate-page，直接 Write 最终 .canvas.jsx。
 
 # 4. 本地 Canvas 快检
 node -e "const fs=require('fs'); const {compileCanvasLocal}=require('./lib/app/canvas-compile'); const src=fs.readFileSync('project/pages/src/<页面名>.canvas.jsx','utf8'); console.log(compileCanvasLocal(src).importedModules)"
@@ -178,8 +181,8 @@ node -e "const fs=require('fs'); const {compileCanvasLocal}=require('./lib/app/c
 # 5. 发布（本轮修改源码后的远端完成证据）
 openyida publish project/pages/src/<页面名>.canvas.jsx <appType> <formUuid>
 
-# 6. 发布后回读 Schema 验收
-openyida get-schema <appType> <formUuid> > .cache/openyida/<页面名>-schema.json
+# 6. 发布后回读字段摘要验收；如需留证，用结构化文件写入工具保存 stdout，不用 shell 重定向
+openyida get-schema <appType> <formUuid> --field-map-json
 ```
 
 `openyida check-page` / `openyida compile` 当前面向普通自定义页面 `.oyd.jsx` / `.jsx`；Canvas 以 `compileCanvasLocal` 和 `openyida publish .canvas.jsx` 的 Canvas 编译阶段为准。`compileCanvasLocal` 是发布前快检，不能替代 `openyida publish` 的远端写入证据。

package/yida-skills/skills/yida-canvas-custom-page/references/page-generation-guide.md

@@ -8,6 +8,8 @@
 
 `generate-page` 的模板只用于选定运行时契约、数据桥、主题变量和首版 primitives；它不是最终视觉稿。生成真实页面时，必须结合 `yida-page-uiux` 的视觉方向决策块重写区块顺序、信息层级、局部构图、文案和样式节奏。可以保留模板的编译安全结构和必要 primitive class，但不要照搬默认 Hero、卡片网格、三段式卖点或库存文案。
 
+页面生成路径必须二选一：走模板路径时，先写业务化 `page-spec.json` 并执行 `openyida generate-page ... --spec ... --compile`，之后只读取 CLI 摘要或 `.openyida-page.json`，再对生成源码做小范围 Edit/patch；不要立刻 Read 大段源码后全量 Write 覆盖同一路径。若已经明确最终页面结构、数据桥和视觉细节，走手写路径，跳过 `generate-page`，直接 Write 最终 `.canvas.jsx`。
+
 生成器会在 `.openyida-page.json` 中写入 `domainFidelity`，并在 CLI 输出中提示当前页面是否还依赖 sample fallback：
 
 - `domain-ready`：主要业务语义已覆盖，sample 只剩编译骨架。

package/yida-skills/skills/yida-create-form-page/SKILL.md

@@ -24,6 +24,7 @@ description: 表单页面创建与更新，支持 19 种业务字段和 Divider
 - 不要在 update / patch / rule / validation / bind-datasource 模式中使用猜测的 fieldId，必须先用 `yida-get-schema` 获取
 - 不要用此命令操作数据记录（增删改查），应使用 `yida-data-management`
 - 不要用 shell heredoc、`cat`/`echo`/`printf`/`tee` 或重定向生成字段、变更、补丁、规则、数据源 JSON 文件
+- OpenYida CLI 不要加 `2>/dev/null`；失败时保留 stdout/stderr 诊断，遇到 DENIED 或重复失败必须换策略
 - 已有目标表单且用户是改字段/联动/属性时，不要创建新表单；必须走 update/patch/rule/bind-datasource。
 - 不要用 `GroupContainer` / `PageSection` 承载普通业务分组；普通分组必须优先用 `Divider`
 
@@ -120,6 +121,15 @@ openyida create-form create <appType> <formTitle> <fieldsJsonOrFile> [--layout d
 {"success":true,"formUuid":"FORM-XXX","formTitle":"用户信息表","appType":"APP_xxx","fieldCount":4,"url":"{base_url}/APP_xxx/workbench/FORM-XXX"}
 ```
 
+### create 失败恢复决策树
+
+create 命令失败后，不要立刻重复同一条 create：
+
+1. 先确认字段 JSON 文件存在，且内容是结构化写入后的最终字段数组/对象，不是半截 JSON、update changes 或 shell 拼接残留。
+2. 运行 `openyida list-forms <appType> --keyword "<表单名>"` 查同名表单；若本轮刚创建过空白表单或已有同名目标表单，优先走 `create-form update` / `patch` / 后续显式 resume 能力复用，不再 create。
+3. 只有确认远端没有同名目标表单，并且已经修改输入文件、参数、登录态或组织后，才重试 create。
+4. 同一 create 命令最多重试 2 次；仍失败时停止并带上完整 stdout/stderr、字段文件路径、appType、表单名和已发现的 formUuid 给用户。
+
 ## update 模式
 
 已有 `formUuid` / 表单 URL / bound form 时优先使用本模式；修改字段前必须用 `openyida get-schema` 确认字段 ID 和当前结构。

package/yida-skills/skills/yida-get-schema/SKILL.md

@@ -15,12 +15,16 @@ description: 确定性解析表单字段 ID（fieldId）和子表路径；agent
 - 不要缓存过期的 Schema 信息，表单结构变更后必须重新获取
 - 不要把进程内状态或 CLI 自动派生索引当作跨调用缓存；查询新字段时允许重新拉取完整 Schema
 - 不要把 `openyida get-schema` 的 stdout 通过 shell 重定向保存成 JSON，也不要用 heredoc、`cat`/`echo`/`printf`/`tee` 生成 Schema 文件
+- 不要把 `openyida get-schema` 的 stdout 再接 `head`、`tail`、`grep`、`sed`、`awk` 等截断/筛选命令作为 Schema 证据；这会丢字段、选项或子表路径，导致后续重复拉取
+- 不要在同一阶段对同一个 `formUuid` 连续执行 `--compact`、`--field-map-json`、完整 Schema 等多轮“探一段 stdout”式查询；除非表单刚被修改、上次命令失败/不完整，或排障需要完整组件 props
 
 ## 严格要求 (MUST DO)
 
 - **凡是需要用到字段 ID（fieldId）的操作，必须先执行此命令**，不得跳过
 - 页面开发、数据查询、报表配置或流程规则只需要字段身份时，先执行 `openyida get-schema <appType> <formUuid> --compact --resolve-fields "<字段1,字段2>"`，不要拉取完整 Schema
 - 页面开发默认使用 compact 输出，只读取必要字段契约，不内联完整 Schema
+- 完整应用页面、看板、列表或详情页需要一个表单的大部分字段，或需要跨多个表单建立 `dataBinding` 时，优先对每个表单执行一次 `openyida get-schema <appType> <formUuid> --field-map-json`，消费完整 JSON 后解析所需字段，不用 shell 截断 stdout
+- 多表单场景同一阶段同一 `formUuid` 默认最多拉取一次字段映射；把 `appType`、`formUuid`、`fieldId`、`label`、`componentName`、`options` 等合并写入 `<projectRoot>/.cache/<项目名>-schema.json`，后续页面 spec 和源码复用该 standalone ID 映射
 - 执行 compact 查询后，只消费唯一命中的 `fields[]`；`missingFields` 或 `ambiguousFields` 非空时停止，不得猜测或继续写操作
 - 只有用户明确需要完整组件 props、布局结构、字段数据源配置，或 compact/summary 无法排障时，才执行不带 `--compact`/`--summary-json` 的完整 Schema 输出；拿到完整 Schema 后只读取必要片段，不内联完整 Schema
 - 已有 `<projectRoot>/.cache/<项目名>-schema.json` 等 standalone ID 映射文件可显式复用；目标字段缺失、重名、结构已变或无法确认新鲜度时，必须重新执行 compact 查询
@@ -74,13 +78,15 @@ openyida get-schema <appType> --all [--summary-json] [--output-dir <dir>] [--key
 
 ```bash
 openyida get-schema APP_XXX FORM-XXX --compact --resolve-fields "访客姓名,状态"
-openyida get-schema APP_XXX FORM-XXX --summary-json
+openyida get-schema APP_XXX FORM-XXX --field-map-json
 ```
 
 Agent 只需要少量字段 ID 时，默认使用 `--compact --resolve-fields`，读取 `fields[].label`、`fields[].fieldId`、`fields[].componentType`、`fields[].valueType`、`fields[].path`、`fields[].labelPath` 和 `fields[].parentFieldId`。`path` 是稳定的 fieldId 数组，`labelPath` 是可读路径；所有可用语言的 label 都参与精确匹配。同名字段会进入 `ambiguousFields[].matches`，必须使用完整 `labelPath`、稳定 `path` 或已返回的 fieldId 重新精确选择，禁止取第一个。
 
 需要全量字段摘要和选项时继续使用 `--summary-json`。只有需要组件完整 props、布局结构、字段数据源配置或排障时，才执行不带 compact/summary 参数的完整 Schema 输出。
 
+消费输出时读取完整 JSON，再由 agent / 脚本解析字段；不要用 `tail -20`、`head -30` 或 `grep` 只看局部 stdout。局部查看可以作为人工调试，但不能作为后续写页面、写数据或配置流程的字段证据。
+
 如需复用输出，使用 agent 的结构化文件写入工具创建：
 
 ```text
@@ -167,7 +173,7 @@ Agent compact 模式输出共享 contract，不包含完整 Schema 或 props：
 |---------|----------|
 | 命令返回失败 | 确认 appType 和 formUuid 正确，检查登录态 |
 | 输出被终端截断 | 优先改用 `--summary-json`；确需完整 Schema 时，再将 stdout 通过结构化文件写入工具保存到 `<projectRoot>/.cache/openyida/<项目名或任务名>/<表单名>-schema.json`；不要使用 shell 重定向 |
-| 需要多个表单字段 ID | 使用批量 compact 模式：`openyida get-schema <appType> --all --summary-json --output-dir .cache/openyida/<项目名或任务名>/schemas`，默认只读 `index.json` 字段摘要 |
+| 需要多个表单字段 ID | 使用批量摘要或每表单完整字段映射：`openyida get-schema <appType> --all --summary-json --output-dir .cache/openyida/<项目名或任务名>/schemas`，或对目标表单逐个执行一次 `--field-map-json`；默认只读完整 JSON / `index.json` 字段摘要，不用 `head`/`tail`/`grep` 截断 |
 | 批量部分失败 | 查看 stdout 的 `failedCount` 和 `forms[].errorMsg`，必要时提高 `--retries` 或缩小 `--keyword` 范围 |
 | 找不到目标字段 | 查看 `missingFields`，确认字段已创建后重新查询；不能手写猜测 fieldId |
 | 同名字段无法唯一确定 | 查看 `ambiguousFields[].matches[].labelPath` 和稳定 `path`，使用完整路径或 fieldId 重新查询；不得默认取第一个 |