openyida 2026.7.21 → 2026.7.23-1

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/publish.js

@@ -126,6 +126,28 @@ function parseArgs(argv = process.argv.slice(2)) {
   };
 }
 
+function normalizeSourcePathForHint(sourceFile) {
+  return String(sourceFile || '')
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '');
+}
+
+function buildMissingSourceHints(sourceFile, cwd = process.cwd()) {
+  const normalized = normalizeSourcePathForHint(sourceFile);
+  const candidates = [];
+
+  if (normalized.startsWith('project/pages/src/')) {
+    candidates.push(normalized.slice('project/'.length));
+  }
+
+  if (normalized.startsWith('pages/src/')) {
+    candidates.push(`project/${normalized}`);
+  }
+
+  return Array.from(new Set(candidates))
+    .filter(candidate => fs.existsSync(path.resolve(cwd, candidate)));
+}
+
 // ── 2. 读取并构建 Schema ────────────────────────────
 
 async function fetchExistingSchemaContent(appType, formUuid, authRef) {
@@ -618,6 +640,10 @@ async function main(argv) {
   let sourcePath = path.resolve(sourceFile);
   if (!fs.existsSync(sourcePath)) {
     error(t('publish.source_not_found', sourcePath));
+    buildMissingSourceHints(sourceFile).forEach((candidate) => {
+      hint(t('publish.source_path_hint', candidate));
+    });
+    process.exit(1);
   }
 
   // 路由：默认 native；.canvas.jsx / .canvas.tsx 源文件自动走 Code Canvas 链路，
@@ -799,6 +825,7 @@ if (require.main === module) {
   module.exports = main;
   module.exports.parseArgs = parseArgs;
   module.exports.normalizePublishArgs = normalizePublishArgs;
+  module.exports.buildMissingSourceHints = buildMissingSourceHints;
   module.exports.findDuplicateSourceMismatches = findDuplicateSourceMismatches;
   module.exports.sendHealthCheckRequest = sendHealthCheckRequest;
   module.exports.normalizeFormType = normalizeFormType;