worsoft-frontend-codegen-local-mcp 0.1.20 → 0.1.21

package/mcp_server.js

@@ -5,12 +5,11 @@ const fs = require('fs');
 const path = require('path');
 
 const SERVER_NAME = 'worsoft-codegen-local';
-const SERVER_VERSION = '0.1.20';
+const SERVER_VERSION = '0.1.21';
 const PROTOCOL_VERSION = '2024-11-05';
 const TOOL_NAME = 'worsoft_codegen_local_generate_frontend';
 const TEMPLATE_LIBRARY_ROOT = path.resolve(__dirname, '..', 'template');
 const STYLE_CATALOG_PATH = path.join(__dirname, 'assets', 'style-catalog.json');
-const DEFAULT_DESIGN_FILE = path.resolve(__dirname, '..', 'sql', 'SQL 闁荤姳鐒﹀畷姗€顢橀崫銉﹀珰閻庢稒蓱椤?md');
 const STYLE_CATALOG = loadStyleCatalog();
 const DEFAULT_DICT_REGISTRY_KEYS = {
   add_start_stop: 'COMMON_STATUS',
@@ -124,41 +123,87 @@ export function createCrudSchema(
 }
 `;
 
-const TOOL_SCHEMA = {
-  type: 'object',
-  properties: {
-    designFile: { type: 'string', description: 'Absolute or relative Markdown design file path. Defaults to ../sql/SQL 设计说明.md when omitted.' },
-    tableName: { type: 'string', description: 'Target main table name from the design file.' },
-    style: { type: 'string', enum: Object.keys(STYLE_CATALOG), description: 'Style id from assets/style-catalog.json.' },
+const TOOL_SCHEMA = {
+  type: 'object',
+  properties: {
+    featureTitle: { type: 'string', description: 'Feature title from the API document or requirement document.' },
+    tableName: { type: 'string', description: 'Target main table name from the structured feature metadata.' },
+    tableComment: { type: 'string', description: 'Main table comment or feature label for menu/title generation.' },
+    apiPath: { type: 'string', description: 'Backend API base path from the API document, for example iwmEmpOutsourcePerson.' },
+    style: { type: 'string', enum: Object.keys(STYLE_CATALOG), description: 'Style id from assets/style-catalog.json.' },
+    fields: {
+      type: 'array',
+      description: 'Structured main-table field metadata parsed from the API document and requirement document.',
+      items: {
+        type: 'object',
+        properties: {
+          fieldName: { type: 'string', description: 'Backend field name.' },
+          label: { type: 'string', description: 'Display label.' },
+          type: { type: 'string', description: 'Normalized or source field type, for example String, Long, Integer, LocalDate, LocalDateTime, DECIMAL, VARCHAR.' },
+          length: { type: ['string', 'number'], description: 'Field length or precision string, for example 30 or 10,2.' },
+          scale: { type: ['string', 'number'], description: 'Optional decimal scale.' },
+          required: { type: ['boolean', 'string'], description: 'Whether the field is required.' },
+          readonly: { type: ['boolean', 'string'], description: 'Whether the field is readonly on the page.' },
+          show: { type: ['boolean', 'string'], description: 'Whether the field is shown on the page.' },
+          dictType: { type: 'string', description: 'Dictionary type code from the API document.' },
+          defaultValue: { type: ['string', 'number', 'boolean'], description: 'Optional default value.' },
+          description: { type: 'string', description: 'Field description or notes.' },
+          sourceKind: { type: 'string', enum: ['entity', 'display', 'virtual', 'common'], description: 'Field source kind.' },
+          primary: { type: ['boolean', 'string'], description: 'Whether the field is the primary key.' },
+        },
+        required: ['fieldName', 'label', 'type'],
+        additionalProperties: false,
+      },
+    },
     children: {
       type: 'array',
-      description: 'Optional direct child-table relations for master_child_jump. When provided, MCP renders all listed direct child tables on the same main form.',
+      description: 'Optional direct child-table structures for master_child_jump. When provided, MCP renders all listed direct child tables on the same main form.',
       items: {
         type: 'object',
         properties: {
           childTableName: { type: 'string', description: 'Child table name.' },
+          childTableComment: { type: 'string', description: 'Child table comment or display label.' },
           mainField: { type: 'string', description: 'Main table relation field.' },
           childField: { type: 'string', description: 'Child table relation field.' },
-          payloadField: { type: 'string', description: 'Optional backend payload list field name from the API document, for example certificateList.' },
+          payloadField: { type: 'string', description: 'Backend payload list field name from the API document, for example certificateList.' },
           relationType: { type: 'string', description: 'Optional relation type label, for example 1:N.' },
+          fields: {
+            type: 'array',
+            description: 'Structured child-table field metadata.',
+            items: {
+              type: 'object',
+              properties: {
+                fieldName: { type: 'string', description: 'Backend field name.' },
+                label: { type: 'string', description: 'Display label.' },
+                type: { type: 'string', description: 'Normalized or source field type.' },
+                length: { type: ['string', 'number'], description: 'Field length or precision string.' },
+                scale: { type: ['string', 'number'], description: 'Optional decimal scale.' },
+                required: { type: ['boolean', 'string'], description: 'Whether the field is required.' },
+                readonly: { type: ['boolean', 'string'], description: 'Whether the field is readonly on the page.' },
+                show: { type: ['boolean', 'string'], description: 'Whether the field is shown on the page.' },
+                dictType: { type: 'string', description: 'Dictionary type code from the API document.' },
+                defaultValue: { type: ['string', 'number', 'boolean'], description: 'Optional default value.' },
+                description: { type: 'string', description: 'Field description or notes.' },
+                sourceKind: { type: 'string', enum: ['entity', 'display', 'virtual', 'common'], description: 'Field source kind.' },
+                primary: { type: ['boolean', 'string'], description: 'Whether the field is the primary key.' },
+              },
+              required: ['fieldName', 'label', 'type'],
+              additionalProperties: false,
+            },
+          },
         },
-        required: ['childTableName', 'mainField', 'childField'],
+        required: ['childTableName', 'mainField', 'childField', 'payloadField', 'fields'],
         additionalProperties: false,
       },
     },
-    childTableName: { type: 'string', description: 'Child table name. Required when style=master_child_jump.' },
-    mainField: { type: 'string', description: 'Main table relation field. Required when style=master_child_jump.' },
-    childField: { type: 'string', description: 'Child table relation field. Required when style=master_child_jump.' },
-    childPayloadField: { type: 'string', description: 'Optional backend payload list field name for the legacy single-child mode, for example certificateList.' },
-    relationType: { type: 'string', description: 'Optional relation type label, for example 1:N.' },
-    frontendPath: { type: 'string', description: 'Absolute frontend output root path.' },
-    moduleName: { type: 'string', description: 'Relative frontend module path, for example admin/test.' },
-    writeToDisk: { type: 'boolean', default: true, description: 'Whether to write generated files.' },
-    overwrite: { type: 'boolean', default: true, description: 'Whether to overwrite existing files. If false, existing files are skipped.' },
-  },
-  required: ['tableName', 'style', 'frontendPath'],
-  additionalProperties: false,
-};
+    frontendPath: { type: 'string', description: 'Absolute frontend output root path.' },
+    moduleName: { type: 'string', description: 'Relative frontend module path, for example admin/test.' },
+    writeToDisk: { type: 'boolean', default: true, description: 'Whether to write generated files.' },
+    overwrite: { type: 'boolean', default: true, description: 'Whether to overwrite existing files. If false, existing files are skipped.' },
+  },
+  required: ['tableName', 'style', 'frontendPath', 'fields'],
+  additionalProperties: false,
+};
 
 function loadStyleCatalog() {
   return JSON.parse(fs.readFileSync(STYLE_CATALOG_PATH, 'utf8'));
@@ -613,244 +658,124 @@ function splitLength(value) {
   return { length: parts[0] || '', scale: parts[1] || '' };
 }
 
-function normalizeDefaultValue(value) {
-  const normalized = String(value || '').trim();
-  if (!normalized || normalized === '-' || normalized === '/') {
-    return '';
-  }
-  return normalized;
-}
-
-function parseRequiredFlag(value) {
-  const normalized = String(value || '').trim().toLowerCase();
-  return ['y', 'yes', '1', 'true', 'required'].includes(normalized);
-}
-
-function parseMarkdownRow(line) {
-  const trimmed = line.trim();
-  if (!trimmed.startsWith('|')) return [];
-  return trimmed
-    .slice(1, trimmed.endsWith('|') ? -1 : undefined)
-    .split('|')
-    .map((cell) => cell.trim());
-}
-
-function isMarkdownSeparatorRow(cells) {
-  return cells.length > 0 && cells.every((cell) => /^:?-{3,}:?$/.test(cell.replace(/\s+/g, '')));
-}
-
-function findHeaderIndex(headers, patterns) {
-  return headers.findIndex((header) => patterns.some((pattern) => pattern.test(header)));
-}
-
-function findPrimaryKeyFromText(text, fields) {
-  const quotedMatch = text.match(/PRIMARY\s+KEY\s*\(\s*`?([a-zA-Z0-9_]+)`?\s*\)/i);
-  if (quotedMatch) {
-    return quotedMatch[1];
-  }
-
-  const commentPk = fields.find((field) => /主键|primary\s+key|\bpk\b/i.test(field.comment));
-  if (commentPk) {
-    return commentPk.fieldName;
-  }
-
-  const idField = fields.find((field) => field.fieldName === 'id');
-  if (idField) {
-    return idField.fieldName;
-  }
-
-  return fields[0] ? fields[0].fieldName : null;
-}
-
-function parseMarkdownTableSection(tableName, tableComment, sectionLines) {
-  const firstTableLineIndex = sectionLines.findIndex((line) => line.trim().startsWith('|'));
-  if (firstTableLineIndex < 0) {
-    throw new Error('Could not find markdown field table for ' + tableName);
-  }
-
-  const tableLines = [];
-  for (let index = firstTableLineIndex; index < sectionLines.length; index += 1) {
-    const line = sectionLines[index].trim();
-    if (!line.startsWith('|')) break;
-    tableLines.push(line);
-  }
-
-  const rows = tableLines.map(parseMarkdownRow).filter((cells) => cells.length > 0);
-  if (rows.length < 3) {
-    throw new Error('Markdown field table is incomplete for ' + tableName);
-  }
-
-  const headers = rows[0];
-  const dataRows = rows.slice(1).filter((cells) => !isMarkdownSeparatorRow(cells));
-  const fieldNameIndex = findHeaderIndex(headers, [/field/i, /\u5B57\u6BB5/i, /\u5B57\u6BB5\u540D/i, /\u5217\u540D/i]);
-  const sqlTypeIndex = findHeaderIndex(headers, [/type/i, /\u7C7B\u578B/i, /\u5B57\u6BB5\u7C7B\u578B/i, /\u6570\u636E\u7C7B\u578B/i]);
-  const lengthIndex = findHeaderIndex(headers, [/length/i, /\u957F\u5EA6/i, /\u5B57\u6BB5\u957F\u5EA6/i]);
-  const requiredIndex = findHeaderIndex(headers, [/required/i, /\u5FC5\u586B/i, /\u662F\u5426\u5FC5\u586B/i, /\u4E0D\u80FD\u4E3A\u7A7A/i]);
-  const defaultIndex = findHeaderIndex(headers, [/default/i, /\u9ED8\u8BA4/i, /\u9ED8\u8BA4\u503C/i]);
-  const commentIndex = findHeaderIndex(headers, [/comment/i, /\u5907\u6CE8/i, /\u8BF4\u660E/i, /\u5B57\u6BB5\u8BF4\u660E/i]);
-
-  const dictTypeIndex = findHeaderIndex(headers, [/dict/i, /dict_?type/i, /\u5B57\u5178/i, /\u5B57\u5178\u7C7B\u578B/i]);
-
-  if (fieldNameIndex < 0 || sqlTypeIndex < 0) {
-    throw new Error('Markdown field table headers are missing required columns for ' + tableName);
-  }
-
-  const fields = [];
-  for (const row of dataRows) {
-    const fieldName = String(row[fieldNameIndex] || '').trim();
-    if (!fieldName || fieldName === '-') continue;
-
-    const sqlType = String(row[sqlTypeIndex] || '').trim().toUpperCase();
-    if (!sqlType) continue;
-
-    const lengthRaw = lengthIndex >= 0 ? row[lengthIndex] : '';
-    const comment = String(commentIndex >= 0 ? row[commentIndex] : '').trim() || fieldName;
-    const explicitDictType = dictTypeIndex >= 0 ? row[dictTypeIndex] : '';
-    const { length, scale } = splitLength(lengthRaw);
-
-    fields.push({
-      fieldName,
-      attrName: toCamelCase(fieldName),
-      sqlType,
-      length,
-      scale,
-      comment,
-      dictType: resolveDictType(comment, explicitDictType),
-      notNull: requiredIndex >= 0 ? parseRequiredFlag(row[requiredIndex]) : false,
-      defaultValue: defaultIndex >= 0 ? normalizeDefaultValue(row[defaultIndex]) : '',
-    });
-  }
-
-  if (!fields.length) {
-    throw new Error('No fields were parsed from markdown table ' + tableName);
-  }
-
-  const sectionText = sectionLines.join('\n');
-  const pkName = findPrimaryKeyFromText(sectionText, fields);
-  const pkField = fields.find((field) => field.fieldName === pkName) || fields[0];
-  return { pkField, fields, tableComment };
-}
-
-function parseMarkdownDesignTables(markdownText) {
-  const lines = stripBom(markdownText).replace(/\r\n?/g, '\n').split('\n');
-  const tables = new Map();
-
-  for (let index = 0; index < lines.length; index += 1) {
-    const heading = lines[index].trim();
-    const headingMatch = heading.match(/^###\s+\S+\s+([a-zA-Z0-9_]+)\s*[\(\uFF08]([^)\n\uFF09]+)[\)\uFF09]/);
-    if (!headingMatch) continue;
-
-    const tableName = headingMatch[1];
-    const tableComment = headingMatch[2].trim();
-    const sectionLines = [];
-    let nextIndex = index + 1;
-    while (nextIndex < lines.length && !/^(##|###)\s+/.test(lines[nextIndex])) {
-      sectionLines.push(lines[nextIndex]);
-      nextIndex += 1;
-    }
-
-    tables.set(tableName, parseMarkdownTableSection(tableName, tableComment, sectionLines));
-    index = nextIndex - 1;
-  }
-
-  return tables;
-}
-
-function extractIdentifiersFromLine(line) {
-  return [...String(line || '').matchAll(/`?([a-zA-Z][a-zA-Z0-9_]*)`?/g)].map((match) => match[1]);
-}
-
-function stripMarkdownSyntax(text) {
-  return String(text || '')
-    .replace(/\*\*/g, '')
-    .replace(/`/g, '')
-    .replace(/\r\n?/g, '\n');
-}
-
-function parseMarkdownRelations(markdownText) {
-  void markdownText;
-  return [];
+function normalizeDefaultValue(value) {
+  const normalized = String(value || '').trim();
+  if (!normalized || normalized === '-' || normalized === '/') {
+    return '';
+  }
+  return normalized;
 }
 
-function parseDesignFeatureTitle(markdownText) {
-  const lines = stripBom(String(markdownText || '')).replace(/\r\n?/g, '\n').split('\n');
-  const titleLine = lines.find((line) => /^#\s+/.test(line.trim()));
-  if (!titleLine) {
-    return '';
+function parseBooleanLike(value, defaultValue = false) {
+  if (value === undefined || value === null || value === '') {
+    return defaultValue;
   }
-  const rawTitle = titleLine.trim().replace(/^#\s+/, '').trim();
-  return rawTitle.replace(/\s*-\s*SQL\s*设计说明\s*$/i, '').trim();
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  const normalized = String(value).trim().toLowerCase();
+  if (['true', '1', 'yes', 'y', 'required', '是', '显示'].includes(normalized)) {
+    return true;
+  }
+  if (['false', '0', 'no', 'n', '否', '不显示'].includes(normalized)) {
+    return false;
+  }
+  return defaultValue;
 }
 
-function parseMarkdownDesignFile(markdownText) {
+function normalizeStructuredSourceKind(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (['entity', 'display', 'virtual', 'common'].includes(normalized)) {
+    return normalized;
+  }
+  return 'entity';
+}
+
+function normalizeApiPath(value) {
+  return String(value || '')
+    .trim()
+    .replace(/^\/+/, '')
+    .replace(/\/+$/, '');
+}
+
+function normalizeStructuredSqlType(value) {
+  const normalized = String(value || '').trim();
+  const upper = normalized.replace(/\s+/g, '').toUpperCase();
+
+  if (!upper) return 'VARCHAR';
+  if (['STRING', 'TEXT', 'VARCHAR', 'CHAR'].includes(upper) || ['文本', '字符', '字符串'].includes(normalized)) return 'VARCHAR';
+  if (['LONG', 'BIGINT', 'LONGINTEGER'].includes(upper) || ['长整数', '长整型'].includes(normalized)) return 'BIGINT';
+  if (['INT', 'INTEGER', 'SHORT', 'SMALLINT'].includes(upper) || ['整数', '整型'].includes(normalized)) return 'INT';
+  if (['DECIMAL', 'NUMERIC', 'BIGDECIMAL', 'DOUBLE', 'FLOAT'].includes(upper) || ['小数', '金额'].includes(normalized)) return 'DECIMAL';
+  if (['LOCALDATE', 'DATE'].includes(upper) || normalized === '日期') return 'DATE';
+  if (['LOCALDATETIME', 'DATETIME', 'TIMESTAMP'].includes(upper) || ['日期时间', '时间'].includes(normalized)) return 'DATETIME';
+  if (['TEXTAREA', 'LONGTEXT', 'TEXT'].includes(upper) || ['长文本', '多行文本'].includes(normalized)) return 'TEXT';
+  return upper;
+}
+
+function normalizeStructuredLengthAndScale(lengthValue, scaleValue) {
+  const parsed = splitLength(lengthValue);
+  const normalizedScale = scaleValue === undefined || scaleValue === null || scaleValue === '' ? parsed.scale : String(scaleValue).trim();
   return {
-    featureTitle: parseDesignFeatureTitle(markdownText),
-    tables: parseMarkdownDesignTables(markdownText),
-    relations: [],
+    length: parsed.length,
+    scale: normalizedScale || '',
   };
 }
+
+function normalizeStructuredField(inputField, index, contextLabel) {
+  if (!inputField || typeof inputField !== 'object') {
+    throw new Error(contextLabel + '[' + index + '] must be an object');
+  }
+
+  const fieldName = String(inputField.fieldName || '').trim();
+  const label = String(inputField.label || inputField.description || fieldName).trim();
+  const type = normalizeStructuredSqlType(inputField.type);
+
+  if (!fieldName) {
+    throw new Error(contextLabel + '[' + index + '] is missing required field: fieldName');
+  }
+  if (!label) {
+    throw new Error(contextLabel + '[' + index + '] is missing required field: label');
+  }
+  if (!String(inputField.type || '').trim()) {
+    throw new Error(contextLabel + '[' + index + '] is missing required field: type');
+  }
+
+  const { length, scale } = normalizeStructuredLengthAndScale(inputField.length, inputField.scale);
+
+  return {
+    fieldName,
+    attrName: toCamelCase(fieldName),
+    sqlType: type,
+    length,
+    scale,
+    comment: label,
+    label,
+    description: String(inputField.description || '').trim(),
+    dictType: normalizeDictType(inputField.dictType),
+    notNull: parseBooleanLike(inputField.required, false),
+    defaultValue: normalizeDefaultValue(inputField.defaultValue),
+    readonly: parseBooleanLike(inputField.readonly, false),
+    show: parseBooleanLike(inputField.show, true),
+    sourceKind: normalizeStructuredSourceKind(inputField.sourceKind),
+    primary: parseBooleanLike(inputField.primary, fieldName === 'id'),
+  };
+}
+
+function normalizeStructuredFieldArray(inputFields, contextLabel) {
+  if (!Array.isArray(inputFields) || !inputFields.length) {
+    throw new Error(contextLabel + ' must be a non-empty array');
+  }
+  return inputFields.map((field, index) => normalizeStructuredField(field, index, contextLabel));
+}
+
+function findPrimaryKeyFromStructuredFields(fields) {
+  return fields.find((field) => field.primary) || fields.find((field) => field.fieldName === 'id') || fields[0];
+}
 
-function parseTableFromMarkdownDesign(designDoc, tableName) {
-  const parsed = designDoc.tables.get(tableName);
-  if (!parsed) {
-    throw new Error('Could not find table definition for ' + tableName + ' in Markdown design file');
-  }
-  return parsed;
-}
-
-function buildQuestionMarkSegmentRegex(segment) {
-  return new RegExp('^' + escapeForRegex(segment).replace(/\\\?/g, '.') + '$', 'i');
-}
-
-function tryResolveGarbledPath(resolvedPath) {
-  if (!resolvedPath.includes('?')) {
-    return null;
-  }
-
-  const parsed = path.parse(resolvedPath);
-  const segments = resolvedPath.slice(parsed.root.length).split(path.sep).filter(Boolean);
-  let currentPath = parsed.root;
-
-  for (const segment of segments) {
-    const exactPath = path.join(currentPath, segment);
-    if (fs.existsSync(exactPath)) {
-      currentPath = exactPath;
-      continue;
-    }
-
-    if (!segment.includes('?') || !fs.existsSync(currentPath) || !fs.statSync(currentPath).isDirectory()) {
-      return null;
-    }
-
-    const matcher = buildQuestionMarkSegmentRegex(segment);
-    const matches = fs.readdirSync(currentPath).filter((name) => matcher.test(name));
-    if (matches.length !== 1) {
-      throw new Error(
-        'Source file path could not be resolved uniquely from garbled input: ' +
-          resolvedPath +
-          '. Matched entries: ' +
-          (matches.length ? matches.join(', ') : 'none')
-      );
-    }
-
-    currentPath = path.join(currentPath, matches[0]);
-  }
-
-  return fs.existsSync(currentPath) ? currentPath : null;
-}
-
-function resolveSourcePath(inputPath) {
-  const resolvedPath = path.resolve(inputPath);
-  if (fs.existsSync(resolvedPath)) {
-    return resolvedPath;
-  }
-
-  const recoveredPath = tryResolveGarbledPath(resolvedPath);
-  if (recoveredPath) {
-    return recoveredPath;
-  }
-
-  throw new Error('Source file does not exist: ' + resolvedPath);
+function parseRequiredFlag(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  return ['y', 'yes', '1', 'true', 'required'].includes(normalized);
 }
 
 function formatRelationCandidate(relation) {
@@ -866,107 +791,31 @@ function formatRelationCandidate(relation) {
   return candidate;
 }
 
-function getRelationCandidates(designDoc, tableName) {
-  return designDoc.relations
-    .filter((relation) => relation.mainTableName === tableName)
-    .map(formatRelationCandidate);
-}
-
-function buildRetryArguments(safeArgs, sourceFile, childTableName) {
-  const retryArguments = {
-    tableName: safeArgs.tableName,
-    style: safeArgs.style,
-    frontendPath: safeArgs.frontendPath,
-    moduleName: safeArgs.moduleName,
-    writeToDisk: safeArgs.writeToDisk,
-    overwrite: safeArgs.overwrite,
-  };
-
-  if (sourceFile) {
-    retryArguments.designFile = sourceFile;
-  }
-
+function buildRetryArguments(safeArgs) {
+  const retryArguments = {
+    ...(safeArgs.featureTitle ? { featureTitle: safeArgs.featureTitle } : {}),
+    tableName: safeArgs.tableName,
+    ...(safeArgs.tableComment ? { tableComment: safeArgs.tableComment } : {}),
+    style: safeArgs.style,
+    frontendPath: safeArgs.frontendPath,
+    moduleName: safeArgs.moduleName,
+    writeToDisk: safeArgs.writeToDisk,
+    overwrite: safeArgs.overwrite,
+    fields: safeArgs.fields,
+  };
+
   if (safeArgs.children && safeArgs.children.length) {
-    retryArguments.children = safeArgs.children.map((relation) => ({
-      childTableName: relation.childTableName,
-      mainField: relation.mainField,
-      childField: relation.childField,
-      ...(relation.payloadField ? { payloadField: relation.payloadField } : {}),
-      relationType: relation.relationType || '',
-    }));
-  }
-
-  if (childTableName) {
-    retryArguments.childTableName = childTableName;
-  }
-
-  if (safeArgs.mainField) {
-    retryArguments.mainField = safeArgs.mainField;
-  }
-
-  if (safeArgs.childField) {
-    retryArguments.childField = safeArgs.childField;
+    retryArguments.children = safeArgs.children;
   }
 
-  if (safeArgs.childPayloadField) {
-    retryArguments.childPayloadField = safeArgs.childPayloadField;
-  }
-
-  if (safeArgs.relationType) {
-    retryArguments.relationType = safeArgs.relationType;
-  }
-
-  return retryArguments;
-}
-
-function buildRelationCorrectionEntry(safeArgs, sourceFile, candidates, selectedChildTableName) {
-  return {
-    field: 'childTableName',
-    title: '请选择子表',
-    tableName: safeArgs.tableName,
-    style: safeArgs.style,
-    designFile: sourceFile,
-    description: candidates.length
-      ? 'If the current child relation is not the one you want, pass childTableName to choose a candidate from the design file.'
-      : 'No child relation was found. Check the child relation section in the design file.',
-    currentValue: selectedChildTableName || '',
-    options: candidates.map((item) => item.childTableName),
-    candidates,
-    example: candidates.length ? buildRetryArguments(safeArgs, sourceFile, candidates[0].childTableName) : buildRetryArguments(safeArgs, sourceFile, selectedChildTableName),
-    retryArguments: candidates.map((item) => buildRetryArguments(safeArgs, sourceFile, item.childTableName)),
-  };
-}
-
-function createRelationResolutionError(message, safeArgs, sourceFile, candidates, selectedChildTableName, status) {
-  const error = new Error(message);
-  error.details = {
-    type: 'relation_resolution',
-    status,
-    tableName: safeArgs.tableName,
-    designFile: sourceFile,
-    message,
-    candidates,
-    correctionEntry: buildRelationCorrectionEntry(safeArgs, sourceFile, candidates, selectedChildTableName),
-  };
-  return error;
-}
-
-function loadSourceDocument(safeArgs) {
-  const inputPath = safeArgs.designFile || DEFAULT_DESIGN_FILE;
-  const sourcePath = resolveSourcePath(inputPath);
-  const text = readUtf8File(sourcePath);
-  return {
-    path: sourcePath,
-    text,
-    designDoc: parseMarkdownDesignFile(text),
-  };
-}
+  return retryArguments;
+}
 
 function normalizeChildrenInput(inputChildren) {
-  if (inputChildren === undefined || inputChildren === null) {
-    return [];
-  }
-  if (!Array.isArray(inputChildren)) {
+  if (inputChildren === undefined || inputChildren === null) {
+    return [];
+  }
+  if (!Array.isArray(inputChildren)) {
     throw new Error('children must be an array');
   }
   return inputChildren.map((item, index) => {
@@ -974,79 +823,26 @@ function normalizeChildrenInput(inputChildren) {
       throw new Error('children[' + index + '] must be an object');
     }
     const childTableName = item.childTableName ? String(item.childTableName) : '';
+    const childTableComment = item.childTableComment ? String(item.childTableComment) : '';
     const mainField = item.mainField ? String(item.mainField) : '';
     const childField = item.childField ? String(item.childField) : '';
     const payloadField = item.payloadField ? String(item.payloadField) : '';
     const relationType = item.relationType ? String(item.relationType) : '';
-    const missingFields = ['childTableName', 'mainField', 'childField'].filter((field) => !({ childTableName, mainField, childField })[field]);
+    const fields = normalizeStructuredFieldArray(item.fields, 'children[' + index + '].fields');
+    const missingFields = ['childTableName', 'mainField', 'childField', 'payloadField'].filter(
+      (field) => !({ childTableName, mainField, childField, payloadField })[field]
+    );
     if (missingFields.length) {
       throw new Error('children[' + index + '] is missing required fields: ' + missingFields.join(', '));
     }
-    return { childTableName, mainField, childField, payloadField, relationType };
+    return { childTableName, childTableComment, mainField, childField, payloadField, relationType, fields };
   });
 }
-
-function resolveMarkdownChildRelations(sourceDocument, safeArgs) {
-  if (safeArgs.children && safeArgs.children.length) {
-    return safeArgs.children.map((relation) => ({
-      mainTableName: safeArgs.tableName,
-      childTableName: relation.childTableName,
-      mainField: relation.mainField,
-      childField: relation.childField,
-      payloadField: relation.payloadField || '',
-      relationType: relation.relationType || '',
-    }));
-  }
-
-  const missingFields = ['childTableName', 'mainField', 'childField'].filter((field) => !safeArgs[field]);
-  if (missingFields.length) {
-    const message = 'master_child_jump requires either children[] or legacy relation fields. Missing: ' + missingFields.join(', ') + '.';
-    const error = new Error(message);
-    error.details = {
-      type: 'relation_input_required',
-      status: 'missing_required_relation_input',
-      tableName: safeArgs.tableName,
-      designFile: sourceDocument.path,
-      message,
-      requiredFields: ['children[] or childTableName/mainField/childField'],
-      correctionEntry: {
-        fields: ['children', 'childTableName', 'mainField', 'childField'],
-        example: {
-          ...buildRetryArguments(safeArgs, sourceDocument.path, safeArgs.childTableName || '<child_table_name>'),
-          children: [
-            {
-              childTableName: safeArgs.childTableName || '<child_table_name>',
-              mainField: safeArgs.mainField || '<main_field>',
-              childField: safeArgs.childField || '<child_field>',
-              ...(safeArgs.childPayloadField ? { payloadField: safeArgs.childPayloadField } : {}),
-              relationType: safeArgs.relationType || '1:N',
-            },
-          ],
-          mainField: safeArgs.mainField || '<main_field>',
-          childField: safeArgs.childField || '<child_field>',
-          ...(safeArgs.childPayloadField ? { childPayloadField: safeArgs.childPayloadField } : {}),
-        },
-      },
-    };
-    throw error;
-  }
-
-  return [
-    {
-      mainTableName: safeArgs.tableName,
-      childTableName: safeArgs.childTableName,
-      mainField: safeArgs.mainField,
-      childField: safeArgs.childField,
-      payloadField: safeArgs.childPayloadField || '',
-      relationType: safeArgs.relationType || '',
-    },
-  ];
-}
-
-function getStylePreset(styleId) {
-  const preset = STYLE_CATALOG[styleId];
-  if (!preset) throw new Error('Unsupported style: ' + styleId);
-  return preset;
+
+function getStylePreset(styleId) {
+  const preset = STYLE_CATALOG[styleId];
+  if (!preset) throw new Error('Unsupported style: ' + styleId);
+  return preset;
 }
 
 function resolveSharedTemplates(stylePreset) {
@@ -1066,70 +862,74 @@ function normalizeFields(parsed) {
   return parsed.fields.map((field) => ({ ...field, formType: mapFieldType(field), isAudit: isAuditField(field.fieldName) }));
 }
 
-function ensureFieldExists(fields, fieldName, tableName, role) {
-  const field = fields.find((item) => item.fieldName === fieldName);
-  if (!field) throw new Error(role + ' field "' + fieldName + '" was not found on table ' + tableName);
-  return field;
-}
-
-function buildChildModels(sourceDocument, safeArgs, mainParsed) {
+function ensureFieldExists(fields, fieldName, tableName, role) {
+  const field = fields.find((item) => item.fieldName === fieldName);
+  if (!field) throw new Error(role + ' field "' + fieldName + '" was not found on table ' + tableName);
+  return field;
+}
+
+function buildChildModels(safeArgs, mainFields, mainPk) {
   if (safeArgs.style !== 'master_child_jump') return [];
 
-  const relations = resolveMarkdownChildRelations(sourceDocument, safeArgs);
-  return relations.map((relation) => {
-    const childParsed = parseTableFromMarkdownDesign(sourceDocument.designDoc, relation.childTableName);
-    const childFields = normalizeFields(childParsed);
-    const mainRelationField = ensureFieldExists(mainParsed.fields, relation.mainField, safeArgs.tableName, 'Main relation');
-    const childRelationField = ensureFieldExists(childParsed.fields, relation.childField, relation.childTableName, 'Child relation');
+  if (!safeArgs.children.length) {
+    throw new Error('master_child_jump requires children[] with structured child table metadata');
+  }
+
+  return safeArgs.children.map((relation) => {
+    const childPk = findPrimaryKeyFromStructuredFields(relation.fields);
+    const childFields = normalizeFields({
+      fields: relation.fields,
+    });
+    const mainRelationField = ensureFieldExists(mainFields, relation.mainField, safeArgs.tableName, 'Main relation');
+    const childRelationField = ensureFieldExists(childFields, relation.childField, relation.childTableName, 'Child relation');
     const childVisibleFields = childFields.filter(
-      (field) => field.fieldName !== childParsed.pkField.fieldName && !field.isAudit && field.fieldName !== relation.childField
+      (field) => field.fieldName !== childPk.fieldName && !field.isAudit && field.fieldName !== relation.childField && field.show !== false
     );
-    const payloadField =
-      relation.payloadField || (relations.length === 1 && safeArgs.childPayloadField ? safeArgs.childPayloadField : '') || '';
-    const listName = payloadField || toCamelCase(relation.childTableName) + 'List';
+    const payloadField = relation.payloadField;
+    const listName = payloadField;
 
     return {
       tableName: relation.childTableName,
-      tableComment: childParsed.tableComment,
+      tableComment: relation.childTableComment || relation.childTableName,
       className: toPascalCase(relation.childTableName),
       functionName: toCamelCase(relation.childTableName),
       listName,
       payloadField,
-      payloadFieldSource: payloadField ? 'arguments' : 'derived',
-      pk: childParsed.pkField,
+      payloadFieldSource: 'arguments',
+      pk: childPk,
       fields: childFields,
       visibleFields: childVisibleFields,
-      mainField: mainRelationField,
-      childField: childRelationField,
-      relationType: relation.relationType,
+      mainField: mainRelationField,
+      childField: childRelationField,
+      relationType: relation.relationType,
     };
   });
-}
-
-function buildModel(safeArgs) {
-  const sourceDocument = loadSourceDocument(safeArgs);
-  const mainParsed = parseTableFromMarkdownDesign(sourceDocument.designDoc, safeArgs.tableName);
-  const fields = normalizeFields(mainParsed);
-  const visibleFields = fields.filter((field) => field.fieldName !== mainParsed.pkField.fieldName && !field.isAudit);
-  const gridFields = visibleFields.slice(0, 8);
-  const children = buildChildModels(sourceDocument, safeArgs, mainParsed);
-  const childDictTypes = children.flatMap((child) => child.visibleFields.map((field) => field.dictType).filter(Boolean));
-  const dictTypes = [...new Set([...visibleFields.map((field) => field.dictType).filter(Boolean), ...childDictTypes])];
-
+}
+
+function buildModel(safeArgs) {
+  const pkField = findPrimaryKeyFromStructuredFields(safeArgs.fields);
+  const fields = normalizeFields({
+    fields: safeArgs.fields,
+  });
+  const visibleFields = fields.filter((field) => field.fieldName !== pkField.fieldName && !field.isAudit && field.show !== false);
+  const gridFields = visibleFields.slice(0, 8);
+  const children = buildChildModels(safeArgs, fields, pkField);
+  const childDictTypes = children.flatMap((child) => child.visibleFields.map((field) => field.dictType).filter(Boolean));
+  const dictTypes = [...new Set([...visibleFields.map((field) => field.dictType).filter(Boolean), ...childDictTypes])];
+
   return {
-    sourceFile: sourceDocument.path,
-    designFile: sourceDocument.path,
-    featureTitle: sourceDocument.designDoc.featureTitle || mainParsed.tableComment,
+    featureTitle: safeArgs.featureTitle || safeArgs.tableComment || safeArgs.tableName,
     tableName: safeArgs.tableName,
-    tableComment: mainParsed.tableComment,
-    className: toPascalCase(safeArgs.tableName),
-    functionName: toCamelCase(safeArgs.tableName),
-    moduleName: normalizeModuleName(safeArgs.moduleName),
-    pk: mainParsed.pkField,
-    fields,
-    visibleFields,
-    gridFields,
-    dictTypes,
+    tableComment: safeArgs.tableComment || safeArgs.featureTitle || safeArgs.tableName,
+    apiPath: safeArgs.apiPath || toCamelCase(safeArgs.tableName),
+    className: toPascalCase(safeArgs.tableName),
+    functionName: toCamelCase(safeArgs.tableName),
+    moduleName: normalizeModuleName(safeArgs.moduleName),
+    pk: pkField,
+    fields,
+    visibleFields,
+    gridFields,
+    dictTypes,
     frontendPath: path.resolve(safeArgs.frontendPath),
     style: safeArgs.style,
     children,
@@ -1264,11 +1064,11 @@ function renderDefaultLine(field) {
   return `  ${field.attrName}: '',`;
 }
 
-function renderFormDefaults(model) {
-  const lines = [`  ${model.pk.attrName}: '',`];
-  for (const field of model.visibleFields) lines.push(renderDefaultLine(field));
-  return lines.join('\n');
-}
+function renderFormDefaults(model) {
+  const lines = [`  ${model.pk.attrName}: '',`];
+  for (const field of model.fields.filter((item) => item.fieldName !== model.pk.fieldName && !item.isAudit)) lines.push(renderDefaultLine(field));
+  return lines.join('\n');
+}
 
 function renderChildTempDefaults(childModel) {
   if (!childModel) return '';
@@ -1571,10 +1371,10 @@ function renderFormRulesV2(visibleFields) {
   return lines.join('\n');
 }
 
-function buildReplacements(model, sharedSupport) {
-  const menuBaseId = Date.now();
-  const apiModulePath = `${model.moduleName}/${model.functionName}`;
-  const routePath = `${model.moduleName}/${model.functionName}`;
+function buildReplacements(model, sharedSupport) {
+  const menuBaseId = Date.now();
+  const apiModulePath = model.apiPath || `${model.moduleName}/${model.functionName}`;
+  const routePath = `${model.moduleName}/${model.functionName}`;
   const permissionPrefix = `${model.moduleName}/${model.functionName}`.replace(/\//g, '_');
   const dictRegistryRefs = sharedSupport.dictRegistry.keyByValue;
   const i18nNamespace = buildI18nNamespace(model);
@@ -1649,30 +1449,29 @@ function renderFiles(model, stylePreset, sharedSupport, localeZhSupport) {
   return files;
 }
 
-function ensureArguments(input) {
-  if (!input || typeof input !== 'object') throw new Error('Arguments must be an object');
-  for (const key of TOOL_SCHEMA.required) {
-    if (!input[key]) throw new Error(key + ' is required');
-  }
-
-  const style = String(input.style);
-  getStylePreset(style);
-
-  return {
-    designFile: input.designFile ? String(input.designFile) : null,
-    tableName: String(input.tableName),
-    style,
+function ensureArguments(input) {
+  if (!input || typeof input !== 'object') throw new Error('Arguments must be an object');
+  for (const key of TOOL_SCHEMA.required) {
+    if (input[key] === undefined || input[key] === null || input[key] === '') throw new Error(key + ' is required');
+  }
+
+  const style = String(input.style);
+  getStylePreset(style);
+  const fields = normalizeStructuredFieldArray(input.fields, 'fields');
+
+  return {
+    featureTitle: input.featureTitle ? String(input.featureTitle) : '',
+    tableName: String(input.tableName),
+    tableComment: input.tableComment ? String(input.tableComment) : '',
+    apiPath: normalizeApiPath(input.apiPath),
+    style,
+    fields,
     children: normalizeChildrenInput(input.children),
-    childTableName: input.childTableName ? String(input.childTableName) : null,
-    mainField: input.mainField ? String(input.mainField) : null,
-    childField: input.childField ? String(input.childField) : null,
-    childPayloadField: input.childPayloadField ? String(input.childPayloadField) : null,
-    relationType: input.relationType ? String(input.relationType) : '',
-    frontendPath: String(input.frontendPath),
-    moduleName: input.moduleName ? String(input.moduleName) : 'admin/test',
-    writeToDisk: input.writeToDisk === undefined ? true : Boolean(input.writeToDisk),
-    overwrite: input.overwrite === undefined ? true : Boolean(input.overwrite),
-  };
+    frontendPath: String(input.frontendPath),
+    moduleName: input.moduleName ? String(input.moduleName) : 'admin/test',
+    writeToDisk: input.writeToDisk === undefined ? true : Boolean(input.writeToDisk),
+    overwrite: input.overwrite === undefined ? true : Boolean(input.overwrite),
+  };
 }
 
 function maybeWriteFiles(files, writeToDisk, overwrite) {
@@ -1696,7 +1495,7 @@ function maybeWriteFiles(files, writeToDisk, overwrite) {
   }
 }
 
-function buildManifest(model, safeArgs, stylePreset, sharedTemplates, files, note) {
+function buildManifest(model, safeArgs, stylePreset, sharedTemplates, files, note) {
   const relations = model.children.map((childModel) => ({
     childTableName: childModel.tableName,
     childTableComment: childModel.tableComment,
@@ -1709,39 +1508,37 @@ function buildManifest(model, safeArgs, stylePreset, sharedTemplates, files, not
   }));
   const selectedList = relations.map((relation) => formatRelationCandidate(relation));
 
-  return {
-    mode: 'local-template',
-    style: safeArgs.style,
-    styleLabel: stylePreset.label,
-    runtimeSupported: hasRuntimeSupport(stylePreset),
-    sourceFile: model.sourceFile,
-    designFile: model.designFile,
-    tableName: model.tableName,
-    tableComment: model.tableComment,
-    moduleName: model.moduleName,
-    writeToDisk: safeArgs.writeToDisk,
+  return {
+    mode: 'local-template',
+    style: safeArgs.style,
+    styleLabel: stylePreset.label,
+    runtimeSupported: hasRuntimeSupport(stylePreset),
+    tableName: model.tableName,
+    tableComment: model.tableComment,
+    apiPath: model.apiPath,
+    moduleName: model.moduleName,
+    writeToDisk: safeArgs.writeToDisk,
     selectedTemplates: sharedTemplates,
-    files: files.map((file) => ({ type: file.type, path: file.path, bytes: Buffer.byteLength(file.content, 'utf8'), status: file.status || (safeArgs.writeToDisk ? 'success' : 'rendered') })),
-    relation: relations.length === 1 ? relations[0] : null,
-    relations,
-    relationResolution: model.children.length
-      ? {
-          status: 'provided',
-          tableName: safeArgs.tableName,
-          designFile: model.designFile,
-          source: 'arguments',
-          message:
-            model.children.length > 1
-              ? 'Direct child relations were provided by the caller. MCP skipped design-doc relation inference and generated a single main form with multiple child tables.'
-              : 'The relation was provided by the caller. MCP skipped design-doc relation inference and generated files directly.',
-          selected: selectedList.length === 1 ? selectedList[0] : null,
-          selectedList,
-          correctionEntry: {
-            fields: ['children', 'childTableName', 'mainField', 'childField'],
-            example: buildRetryArguments(safeArgs, model.designFile, model.children[0].tableName),
-          },
-        }
-      : null,
+    files: files.map((file) => ({ type: file.type, path: file.path, bytes: Buffer.byteLength(file.content, 'utf8'), status: file.status || (safeArgs.writeToDisk ? 'success' : 'rendered') })),
+    relation: relations.length === 1 ? relations[0] : null,
+    relations,
+    relationResolution: model.children.length
+      ? {
+          status: 'structured_input',
+          tableName: safeArgs.tableName,
+          source: 'arguments',
+          message:
+            model.children.length > 1
+              ? 'Direct child relations were provided by the caller as structured API-first metadata. MCP generated a single main form with multiple child tables.'
+              : 'The relation was provided by the caller as structured API-first metadata. MCP generated files directly.',
+          selected: selectedList.length === 1 ? selectedList[0] : null,
+          selectedList,
+          correctionEntry: {
+            fields: ['children'],
+            example: buildRetryArguments(safeArgs),
+          },
+        }
+      : null,
     summary: {
       totalFields: model.fields.length,
       visibleFields: model.visibleFields.length,
@@ -1808,7 +1605,18 @@ async function onMessage(message) {
   }
 
   if (method === 'tools/list') {
-    writeMessage(successResponse(id, { tools: [{ name: TOOL_NAME, description: 'Generate Worsoft frontend files and menu SQL from a local Markdown design file with style-based local templates. In master_child_jump mode, the caller must provide either children[] or childTableName/mainField/childField.', inputSchema: TOOL_SCHEMA }] }));
+    writeMessage(
+      successResponse(id, {
+        tools: [
+          {
+            name: TOOL_NAME,
+            description:
+              'Generate Worsoft frontend files and menu SQL from API-first structured feature metadata. In master_child_jump mode, the caller must provide children[] with explicit payloadField and child field metadata.',
+            inputSchema: TOOL_SCHEMA,
+          },
+        ],
+      })
+    );
     return;
   }