scaffold-engine 0.1.0

package/tools/analyze-requirement.cjs

@@ -0,0 +1,950 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const YAML = require('yaml');
+const {
+  loadRuntimeConfig,
+  readJson,
+  resolveScaffoldPath,
+  snakeCase,
+  validateModelFile,
+} = require('./lib/model-toolkit.cjs');
+const { resolveCatalogPath, resolveRulePath } = require('./lib/runtime-config.cjs');
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const options = parseArgs(args);
+
+  try {
+    const requirementText = readRequirementText(options);
+    const result = analyzeRequirement(requirementText, { configPath: options.configPath });
+
+    if (options.writeSpec && result.suggestedModel) {
+      const specPath = writeSuggestedSpec(result.suggestedModel, options.writeSpec);
+      result.generatedSpecPath = specPath;
+    }
+
+    if (options.format === 'json') {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(renderMarkdown(result));
+    }
+
+    if (result.decision === 'not_extendable') {
+      process.exit(2);
+    }
+    if (result.decision === 'need_more_info') {
+      process.exit(3);
+    }
+  } catch (error) {
+    console.error(`\n❌ 需求分析失败: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+function parseArgs(argv) {
+  const options = {
+    file: '',
+    format: 'markdown',
+    writeSpec: '',
+    configPath: '',
+  };
+  const textParts = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (item === '--file') {
+      options.file = argv[index + 1] || '';
+      index += 1;
+      continue;
+    }
+    if (item === '--format') {
+      options.format = argv[index + 1] || 'markdown';
+      index += 1;
+      continue;
+    }
+    if (item === '--write-spec') {
+      options.writeSpec = argv[index + 1] || '';
+      index += 1;
+      continue;
+    }
+    if (item === '--config') {
+      options.configPath = argv[index + 1] || '';
+      index += 1;
+      continue;
+    }
+    textParts.push(item);
+  }
+
+  options.text = textParts.join(' ').trim();
+  return options;
+}
+
+function readRequirementText(options) {
+  if (options.file) {
+    return fs.readFileSync(path.resolve(options.file), 'utf8').trim();
+  }
+  if (options.text) {
+    return options.text;
+  }
+  throw new Error('请提供需求文本，例如: node ./tools/analyze-requirement.cjs "做一个线索管理，支持新建、编辑、列表、详情"');
+}
+
+function analyzeRequirement(requirementText, options = {}) {
+  const runtimeConfig = loadRuntimeConfig(options);
+  const boundaries = readJson(resolveRulePath(runtimeConfig, 'extensionBoundaries'));
+  const resources = loadCatalogResources(runtimeConfig);
+  const { objects: objectCatalog, patterns: patternCatalog } = resources;
+  const matchedObject = detectObject(requirementText, objectCatalog);
+  const matchedPattern = detectPattern(requirementText, patternCatalog);
+  const suggestedName = !matchedObject && matchedPattern
+    ? detectSuggestedObjectName(requirementText, resources.nameSuggestions, matchedPattern.id)
+    : null;
+  const requestedActions = detectActions(requirementText);
+  const missingInfo = [];
+  const reasons = [];
+
+  if (!matchedObject) {
+    const seedModel = matchedPattern ? buildPatternSeedModel(matchedPattern, requestedActions, resources, suggestedName) : null;
+    return finalizeAnalysisResult({
+      decision: 'need_more_info',
+      nextAction: 'clarify',
+      requirement: requirementText,
+      reason: [
+        matchedPattern
+          ? suggestedName
+            ? `已识别出结构模式 ${matchedPattern.label}(${matchedPattern.id})，并推断出候选对象 ${suggestedName.label}(${suggestedName.domain}/${suggestedName.object})`
+            : `已识别出结构模式 ${matchedPattern.label}(${matchedPattern.id})，但还缺少稳定的业务对象`
+          : '未识别出稳定的业务对象，当前工具需要至少明确一个对象名，例如“客户”“线索”“商机”',
+      ],
+      missingInfo: matchedPattern
+        ? suggestedName
+          ? ['对象的最小字段集']
+          : ['业务对象名称', '对象的最小字段集']
+        : ['业务对象名称', '对象的最小字段集'],
+      inferred: {
+        domain: suggestedName ? suggestedName.domain : undefined,
+        object: suggestedName ? suggestedName.object : undefined,
+        label: suggestedName ? suggestedName.label : undefined,
+        pattern: matchedPattern ? matchedPattern.id : undefined,
+        actions: requestedActions,
+      },
+      suggestedModel: seedModel || undefined,
+    });
+  }
+
+  const domain = matchedObject.domain;
+  const object = matchedObject.object;
+  const label = matchedObject.label;
+  const pattern = matchedObject.patternRef || '';
+  const table = `${snakeCase(domain)}_${snakeCase(object)}`;
+  const actions = requestedActions.length > 0
+    ? requestedActions
+    : Array.isArray(matchedObject.defaultActions) ? matchedObject.defaultActions : [];
+  const inferredAppTemplate = inferAppTemplateByActions(actions, resources.actionTemplates);
+  const statusFlow = alignStatusFlowActions(
+    matchedObject.defaultStatusFlow || inferredAppTemplate.statusFlow,
+    actions
+  );
+  const responseContract = matchedObject.defaultResponseContract || inferredAppTemplate.responseContract;
+  const permissionProfile = matchedObject.defaultPermissionProfile || inferredAppTemplate.permissionProfile;
+  const validationRules = Array.isArray(matchedObject.defaultValidationRules) && matchedObject.defaultValidationRules.length > 0
+    ? matchedObject.defaultValidationRules
+    : inferredAppTemplate.validationRules;
+  const errorCodes = Array.isArray(matchedObject.defaultErrorCodes) && matchedObject.defaultErrorCodes.length > 0
+    ? matchedObject.defaultErrorCodes
+    : inferredAppTemplate.errorCodes;
+
+  reasons.push(`识别对象为 ${label}(${domain}/${object})`);
+  if (matchedPattern && matchedPattern.id === pattern) {
+    reasons.push(`结构模式识别为 ${matchedPattern.label}(${matchedPattern.id})，与对象模板一致`);
+  } else if (matchedPattern && matchedPattern.id !== pattern) {
+    reasons.push(`结构模式初步识别为 ${matchedPattern.label}(${matchedPattern.id})，最终回退采用对象模板模式 ${pattern}`);
+  }
+
+  if (requestedActions.length === 0 && actions.length > 0) {
+    reasons.push(`未显式识别动作，已回退使用对象模板默认动作: ${actions.join(', ')}`);
+  }
+
+  if (actions.length === 0) {
+    missingInfo.push('至少一个业务动作，例如新建、编辑、列表、详情');
+  }
+
+  if ((boundaries.protectedDomains || []).map(toLower).includes(toLower(domain))) {
+    return finalizeAnalysisResult({
+      decision: 'not_extendable',
+      nextAction: 'reject',
+      requirement: requirementText,
+      reason: [`domain "${domain}" 属于受保护域，当前框架不允许把业务扩展直接落到系统域上`],
+      missingInfo: [],
+      inferred: {
+        domain,
+        object,
+        label,
+        pattern,
+        actions,
+      },
+    });
+  }
+
+  if ((boundaries.protectedMetaObjects || []).map(toLower).includes(toLower(object))) {
+    return finalizeAnalysisResult({
+      decision: 'not_extendable',
+      nextAction: 'reject',
+      requirement: requirementText,
+      reason: [`object "${object}" 属于受保护对象，当前框架不允许直接覆盖系统对象`],
+      missingInfo: [],
+      inferred: {
+        domain,
+        object,
+        label,
+        actions,
+      },
+    });
+  }
+
+  const model = buildSuggestedModel({
+    domain,
+    object,
+    label,
+    pattern,
+    table,
+    fields: matchedObject.fields,
+    actions,
+    statusFlow,
+    responseContract,
+    permissionProfile,
+    validationRules,
+    errorCodes,
+    detailSections: matchedObject.detailSections,
+    children: matchedObject.children,
+  });
+
+  const validation = validateInlineModel(model);
+  if (validation.boundaryErrors.length > 0) {
+    return finalizeAnalysisResult({
+      decision: 'not_extendable',
+      nextAction: 'reject',
+      requirement: requirementText,
+      reason: validation.boundaryErrors,
+      missingInfo,
+      inferred: {
+        domain,
+        object,
+        label,
+        pattern,
+        actions,
+      },
+      suggestedModel: model,
+    });
+  }
+
+  if (validation.schemaErrors.length > 0) {
+    return finalizeAnalysisResult({
+      decision: 'need_more_info',
+      nextAction: 'clarify',
+      requirement: requirementText,
+      reason: validation.schemaErrors,
+      missingInfo,
+      inferred: {
+        domain,
+        object,
+        label,
+        pattern,
+        actions,
+      },
+      suggestedModel: model,
+    });
+  }
+
+  if (missingInfo.length > 0) {
+    return finalizeAnalysisResult({
+      decision: 'need_more_info',
+      nextAction: 'clarify',
+      requirement: requirementText,
+      reason: reasons,
+      missingInfo,
+      inferred: {
+        domain,
+        object,
+        label,
+        pattern,
+        actions,
+      },
+      suggestedModel: model,
+      warnings: validation.warnings,
+    });
+  }
+
+  reasons.push('已能映射为当前 scaffold 业务模型规范');
+  reasons.push('未触碰系统保留 domain/object/table 边界');
+
+  return finalizeAnalysisResult({
+    decision: 'extendable',
+    nextAction: 'generate',
+    requirement: requirementText,
+    reason: reasons,
+    missingInfo: [],
+    inferred: {
+      domain,
+      object,
+      label,
+      pattern,
+      actions,
+    },
+    suggestedModel: model,
+    warnings: validation.warnings,
+  });
+}
+
+function buildAnalysisMeta(decision, nextAction, requirement) {
+  return {
+    contractVersion: '1.0.0',
+    stage: 'analyze',
+    status: decision === 'extendable' ? 'passed' : decision === 'need_more_info' ? 'incomplete' : 'failed',
+    nextAction,
+    requirement,
+  };
+}
+
+function finalizeAnalysisResult(result) {
+  const inferred = result.inferred || {};
+  const suggestedModel = result.suggestedModel;
+  return {
+    ...buildAnalysisMeta(result.decision, result.nextAction, result.requirement),
+    ...result,
+    candidate: {
+      domain: inferred.domain || '',
+      object: inferred.object || '',
+      label: inferred.label || '',
+      pattern: inferred.pattern || '',
+    },
+    draftSummary: suggestedModel ? buildDraftSummary(suggestedModel) : undefined,
+  };
+}
+
+function buildDraftSummary(model) {
+  const fields = Array.isArray(model?.data?.fields) ? model.data.fields : [];
+  const children = Array.isArray(model?.data?.children) ? model.data.children : [];
+  const actions = Array.isArray(model?.app?.actions) ? model.app.actions : [];
+  return {
+    rootFieldCount: fields.length,
+    childTableCount: children.length,
+    actionCount: actions.length,
+    hasStatusFlow: Boolean(model?.app?.statusFlow),
+    hasPermissionProfile: Boolean(model?.app?.permissionProfile),
+    hasValidationRules: Array.isArray(model?.app?.validationRules) && model.app.validationRules.length > 0,
+  };
+}
+
+function loadCatalogResources(runtimeConfig) {
+  const catalogPath = resolveCatalogPath(runtimeConfig, 'objectCatalog');
+  const patternPath = resolveCatalogPath(runtimeConfig, 'patternCatalog');
+  const fragmentPath = resolveCatalogPath(runtimeConfig, 'fieldFragments');
+  const templatePath = resolveCatalogPath(runtimeConfig, 'objectTemplates');
+  const suggestionPath = resolveCatalogPath(runtimeConfig, 'objectNameSuggestions');
+  const actionTemplatePath = resolveCatalogPath(runtimeConfig, 'actionTemplates');
+  const statusTemplatePath = resolveCatalogPath(runtimeConfig, 'statusTemplates');
+  const childTemplatePath = resolveCatalogPath(runtimeConfig, 'childTemplates');
+  const patternDoc = YAML.parse(fs.readFileSync(patternPath, 'utf8')) || {};
+  const catalog = YAML.parse(fs.readFileSync(catalogPath, 'utf8')) || {};
+  const fragmentDoc = YAML.parse(fs.readFileSync(fragmentPath, 'utf8')) || {};
+  const templateDoc = YAML.parse(fs.readFileSync(templatePath, 'utf8')) || {};
+  const suggestionDoc = YAML.parse(fs.readFileSync(suggestionPath, 'utf8')) || {};
+  const actionTemplateDoc = YAML.parse(fs.readFileSync(actionTemplatePath, 'utf8')) || {};
+  const statusTemplateDoc = YAML.parse(fs.readFileSync(statusTemplatePath, 'utf8')) || {};
+  const childTemplateDoc = YAML.parse(fs.readFileSync(childTemplatePath, 'utf8')) || {};
+  const patterns = patternDoc.patterns || {};
+  const fragments = fragmentDoc.fragments || {};
+  const templates = templateDoc.templates || {};
+  const suggestions = Array.isArray(suggestionDoc.suggestions) ? suggestionDoc.suggestions : [];
+  const actionTemplates = actionTemplateDoc.templates || {};
+  const statusTemplates = statusTemplateDoc.templates || {};
+  const childTemplates = childTemplateDoc.templates || {};
+  const objects = Array.isArray(catalog.objects) ? catalog.objects : [];
+  return {
+    patterns: Object.entries(patterns).map(([id, item]) => ({
+      id,
+      label: item.label || id,
+      keywords: Array.isArray(item.detectKeywords) ? item.detectKeywords : [],
+      defaultUi: item.defaultUi || {},
+      defaultActionTemplateRef: item.defaultActionTemplateRef || '',
+      defaultChildTemplateRefs: Array.isArray(item.defaultChildTemplateRefs) ? item.defaultChildTemplateRefs : [],
+      seedFieldRefs: Array.isArray(item.seedFieldRefs) ? item.seedFieldRefs : [],
+      seedChildTemplateRefs: Array.isArray(item.seedChildTemplateRefs) ? item.seedChildTemplateRefs : [],
+    })),
+    objects: objects.map((item) => resolveCatalogObject(item, patterns, templates, fragments, actionTemplates, statusTemplates, childTemplates)),
+    nameSuggestions: suggestions.map((item) => ({
+      keywords: Array.isArray(item.keywords) ? item.keywords : [],
+      patternRef: item.patternRef || '',
+      domain: item.domain || 'custom',
+      object: item.object || '',
+      label: item.label || '',
+    })),
+    fragments,
+    actionTemplates,
+    statusTemplates,
+    childTemplates,
+  };
+}
+
+function resolveCatalogObject(item, patterns, templates, fragments, actionTemplates, statusTemplates, childTemplates) {
+  const template = item.objectTemplateRef ? templates[item.objectTemplateRef] : null;
+  if (item.objectTemplateRef && !template) {
+    throw new Error(`对象词典 ${item.domain}/${item.object} 引用了不存在的对象模板: ${item.objectTemplateRef}`);
+  }
+
+  const patternRef = item.patternRef || template?.patternRef || '';
+  const pattern = patternRef ? patterns[patternRef] : null;
+  if (patternRef && !pattern) {
+    throw new Error(`对象词典 ${item.domain}/${item.object} 引用了不存在的模式模板: ${patternRef}`);
+  }
+
+  const merged = mergeCatalogPattern(pattern || {}, template || {}, item, patternRef);
+  const appTemplate = resolveDefaultAppTemplate(merged, actionTemplates);
+  const children = expandChildTemplates(merged, childTemplates);
+  return {
+    ...merged,
+    ...appTemplate,
+    children,
+    fields: expandCatalogFields(merged, fragments, statusTemplates),
+  };
+}
+
+function mergeCatalogPattern(pattern, template, item, patternRef) {
+  const patternUi = pattern.defaultUi || {};
+  return {
+    ...pattern,
+    ...template,
+    ...item,
+    patternRef,
+    detailSections: item.detailSections || template.detailSections || patternUi.detailSections || ['basicInfo'],
+    actionTemplateRef: item.actionTemplateRef || template.actionTemplateRef || pattern.defaultActionTemplateRef || '',
+    fieldRefs: uniqueList([...(template.fieldRefs || []), ...(item.fieldRefs || [])]),
+    fields: [...(template.fields || []), ...(item.fields || [])],
+    childTemplateRefs: uniqueList([
+      ...(pattern.defaultChildTemplateRefs || []),
+      ...(template.childTemplateRefs || []),
+      ...(item.childTemplateRefs || []),
+    ]),
+  };
+}
+
+function expandChildTemplates(item, childTemplates) {
+  const resolved = [];
+  for (const ref of item.childTemplateRefs || []) {
+    const template = childTemplates[ref];
+    if (!template) {
+      throw new Error(`对象词典 ${item.domain}/${item.object} 引用了不存在的子表模板: ${ref}`);
+    }
+    resolved.push(cloneField(template));
+  }
+  for (const child of item.children || []) {
+    resolved.push(cloneField(child));
+  }
+  return resolved;
+}
+
+function expandCatalogFields(item, fragments, statusTemplates) {
+  const resolved = [];
+
+  for (const ref of item.fieldRefs || []) {
+    const field = fragments[ref];
+    if (!field) {
+      throw new Error(`对象词典 ${item.domain}/${item.object} 引用了不存在的字段片段: ${ref}`);
+    }
+    resolved.push(resolveFieldFragment(field, statusTemplates));
+  }
+
+  for (const field of item.fields || []) {
+    if (field.fragmentRef) {
+      const base = fragments[field.fragmentRef];
+      if (!base) {
+        throw new Error(`对象词典 ${item.domain}/${item.object} 引用了不存在的字段片段: ${field.fragmentRef}`);
+      }
+      resolved.push({
+        ...resolveFieldFragment(base, statusTemplates),
+        ...omit(field, ['fragmentRef']),
+      });
+      continue;
+    }
+    resolved.push(resolveFieldFragment(field, statusTemplates));
+  }
+
+  return resolved;
+}
+
+function resolveFieldFragment(field, statusTemplates) {
+  const next = cloneField(field);
+  if (next.statusTemplateRef) {
+    const template = statusTemplates[next.statusTemplateRef];
+    if (!template) {
+      throw new Error(`字段片段 ${next.name || next.label || 'unknown'} 引用了不存在的状态模板: ${next.statusTemplateRef}`);
+    }
+    next.options = Array.isArray(template.options) ? [...template.options] : [];
+    next.default = template.default;
+    delete next.statusTemplateRef;
+  }
+  return next;
+}
+
+function resolveDefaultAppTemplate(item, actionTemplates) {
+  if (!item.actionTemplateRef) {
+    return {
+      defaultActions: [],
+      defaultStatusFlow: null,
+      defaultResponseContract: null,
+      defaultPermissionProfile: null,
+      defaultValidationRules: [],
+      defaultErrorCodes: [],
+    };
+  }
+  const template = actionTemplates[item.actionTemplateRef];
+  if (!template) {
+    throw new Error(`对象词典 ${item.domain}/${item.object} 引用了不存在的动作模板: ${item.actionTemplateRef}`);
+  }
+  return {
+    defaultActions: Array.isArray(template.actions) ? [...template.actions] : [],
+    defaultStatusFlow: template.statusFlow ? cloneField(template.statusFlow) : null,
+    defaultResponseContract: template.responseContract ? cloneField(template.responseContract) : null,
+    defaultPermissionProfile: template.permissionProfile ? cloneField(template.permissionProfile) : null,
+    defaultValidationRules: Array.isArray(template.validationRules) ? template.validationRules.map((item) => cloneField(item)) : [],
+    defaultErrorCodes: Array.isArray(template.errorCodes) ? template.errorCodes.map((item) => cloneField(item)) : [],
+  };
+}
+
+function cloneField(field) {
+  return JSON.parse(JSON.stringify(field));
+}
+
+function omit(object, keys) {
+  const next = { ...object };
+  for (const key of keys) {
+    delete next[key];
+  }
+  return next;
+}
+
+function uniqueList(items) {
+  return Array.from(new Set(items.filter(Boolean)));
+}
+
+function detectObject(text, catalog) {
+  const normalized = normalizeText(text);
+  let bestMatch = null;
+
+  for (const item of catalog) {
+    let score = 0;
+    for (const keyword of item.keywords) {
+      if (normalized.includes(normalizeText(keyword))) {
+        score += keyword.length;
+      }
+    }
+    if (!bestMatch || score > bestMatch.score) {
+      bestMatch = { score, item };
+    }
+  }
+
+  return bestMatch && bestMatch.score > 0 ? bestMatch.item : null;
+}
+
+function detectPattern(text, catalog) {
+  const normalized = normalizeText(text);
+  let bestMatch = null;
+
+  for (const item of catalog) {
+    let score = 0;
+    for (const keyword of item.keywords || []) {
+      if (normalized.includes(normalizeText(keyword))) {
+        score += keyword.length;
+      }
+    }
+    if (!bestMatch || score > bestMatch.score) {
+      bestMatch = { score, item };
+    }
+  }
+
+  return bestMatch && bestMatch.score > 0 ? bestMatch.item : null;
+}
+
+function detectSuggestedObjectName(text, suggestions, patternRef) {
+  const normalized = normalizeText(text);
+  let bestMatch = null;
+
+  for (const item of suggestions || []) {
+    if (item.patternRef && patternRef && item.patternRef !== patternRef) {
+      continue;
+    }
+    let score = 0;
+    for (const keyword of item.keywords || []) {
+      if (normalized.includes(normalizeText(keyword))) {
+        score += keyword.length;
+      }
+    }
+    if (!bestMatch || score > bestMatch.score) {
+      bestMatch = { score, item };
+    }
+  }
+
+  return bestMatch && bestMatch.score > 0 ? bestMatch.item : null;
+}
+
+function buildPatternSeedModel(pattern, requestedActions, resources, suggestedName) {
+  const fields = (pattern.seedFieldRefs || []).map((ref) => {
+    const field = resources.fragments[ref];
+    if (!field) {
+      throw new Error(`模式 ${pattern.id} 引用了不存在的种子字段片段: ${ref}`);
+    }
+    return resolveFieldFragment(field, resources.statusTemplates);
+  });
+
+  const children = (pattern.seedChildTemplateRefs || []).map((ref) => {
+    const child = resources.childTemplates[ref];
+    if (!child) {
+      throw new Error(`模式 ${pattern.id} 引用了不存在的种子子表模板: ${ref}`);
+    }
+    return cloneField(child);
+  });
+
+  const actions = requestedActions.length > 0
+    ? requestedActions
+    : resolveDefaultActionsFromPattern(pattern, resources.actionTemplates);
+  const inferredAppTemplate = inferAppTemplateByActions(actions, resources.actionTemplates);
+  const statusFlow = alignStatusFlowActions(
+    resolveDefaultStatusFlowFromPattern(pattern, resources.actionTemplates) || inferredAppTemplate.statusFlow,
+    actions
+  );
+  const responseContract = resolveDefaultResponseContractFromPattern(pattern, resources.actionTemplates) || inferredAppTemplate.responseContract;
+  const permissionProfile = resolveDefaultPermissionProfileFromPattern(pattern, resources.actionTemplates) || inferredAppTemplate.permissionProfile;
+  const validationRules = resolveDefaultValidationRulesFromPattern(pattern, resources.actionTemplates).length > 0
+    ? resolveDefaultValidationRulesFromPattern(pattern, resources.actionTemplates)
+    : inferredAppTemplate.validationRules;
+  const errorCodes = resolveDefaultErrorCodesFromPattern(pattern, resources.actionTemplates).length > 0
+    ? resolveDefaultErrorCodesFromPattern(pattern, resources.actionTemplates)
+    : inferredAppTemplate.errorCodes;
+
+  return buildSuggestedModel({
+    domain: suggestedName?.domain || 'custom',
+    object: suggestedName?.object || `${pattern.id}Sample`,
+    label: suggestedName?.label || `${pattern.label}示例`,
+    pattern: pattern.id,
+    table: suggestedName
+      ? `${snakeCase(suggestedName.domain)}_${snakeCase(suggestedName.object)}`
+      : `custom_${snakeCase(pattern.id)}_sample`,
+    fields,
+    actions,
+    statusFlow,
+    responseContract,
+    permissionProfile,
+    validationRules,
+    errorCodes,
+    detailSections: pattern.defaultUi?.detailSections || ['basicInfo'],
+    children,
+  });
+}
+
+function resolveDefaultActionsFromPattern(pattern, actionTemplates) {
+  const template = pattern.defaultActionTemplateRef ? actionTemplates[pattern.defaultActionTemplateRef] : null;
+  return Array.isArray(template?.actions) ? [...template.actions] : [];
+}
+
+function resolveDefaultStatusFlowFromPattern(pattern, actionTemplates) {
+  const template = pattern.defaultActionTemplateRef ? actionTemplates[pattern.defaultActionTemplateRef] : null;
+  return template?.statusFlow ? cloneField(template.statusFlow) : null;
+}
+
+function resolveDefaultErrorCodesFromPattern(pattern, actionTemplates) {
+  const template = pattern.defaultActionTemplateRef ? actionTemplates[pattern.defaultActionTemplateRef] : null;
+  return Array.isArray(template?.errorCodes) ? template.errorCodes.map((item) => cloneField(item)) : [];
+}
+
+function resolveDefaultResponseContractFromPattern(pattern, actionTemplates) {
+  const template = pattern.defaultActionTemplateRef ? actionTemplates[pattern.defaultActionTemplateRef] : null;
+  return template?.responseContract ? cloneField(template.responseContract) : null;
+}
+
+function resolveDefaultPermissionProfileFromPattern(pattern, actionTemplates) {
+  const template = pattern.defaultActionTemplateRef ? actionTemplates[pattern.defaultActionTemplateRef] : null;
+  return template?.permissionProfile ? cloneField(template.permissionProfile) : null;
+}
+
+function resolveDefaultValidationRulesFromPattern(pattern, actionTemplates) {
+  const template = pattern.defaultActionTemplateRef ? actionTemplates[pattern.defaultActionTemplateRef] : null;
+  return Array.isArray(template?.validationRules) ? template.validationRules.map((item) => cloneField(item)) : [];
+}
+
+function inferAppTemplateByActions(actions, actionTemplates) {
+  const set = new Set(actions || []);
+  if (set.has('submit') || set.has('approve') || set.has('reject')) {
+    return getActionTemplate('crudWithSubmitApprove', actionTemplates);
+  }
+  if (set.has('activate') || set.has('deactivate')) {
+    return getActionTemplate('crudWithToggle', actionTemplates);
+  }
+  return {
+    statusFlow: null,
+    responseContract: null,
+    permissionProfile: null,
+    validationRules: [],
+    errorCodes: [],
+  };
+}
+
+function getActionTemplate(templateRef, actionTemplates) {
+  const template = actionTemplates[templateRef];
+  if (!template) {
+    return {
+      statusFlow: null,
+      responseContract: null,
+      permissionProfile: null,
+      validationRules: [],
+      errorCodes: [],
+    };
+  }
+  return {
+    statusFlow: template.statusFlow ? cloneField(template.statusFlow) : null,
+    responseContract: template.responseContract ? cloneField(template.responseContract) : null,
+    permissionProfile: template.permissionProfile ? cloneField(template.permissionProfile) : null,
+    validationRules: Array.isArray(template.validationRules) ? template.validationRules.map((item) => cloneField(item)) : [],
+    errorCodes: Array.isArray(template.errorCodes) ? template.errorCodes.map((item) => cloneField(item)) : [],
+  };
+}
+
+function detectActions(text) {
+  const actionRules = [
+    { action: 'create', patterns: ['新建', '创建', '新增'] },
+    { action: 'update', patterns: ['编辑', '修改', '更新'] },
+    { action: 'list', patterns: ['列表', '查询', '搜索', '筛选'] },
+    { action: 'detail', patterns: ['详情', '查看'] },
+    { action: 'activate', patterns: ['启用'] },
+    { action: 'deactivate', patterns: ['停用', '禁用'] },
+    { action: 'submit', patterns: ['提交', '提交审批', '送审'] },
+    { action: 'approve', patterns: ['审批通过', '审核通过', '批准', '审批'] },
+    { action: 'reject', patterns: ['驳回', '拒绝', '退回'] },
+    { action: 'close', patterns: ['关闭', '关闭单据', '结束'] },
+    { action: 'archive', patterns: ['归档', '存档'] },
+    { action: 'convert', patterns: ['转化', '转换'] },
+  ];
+
+  const actions = [];
+  for (const rule of actionRules) {
+    if (rule.patterns.some((pattern) => text.includes(pattern))) {
+      actions.push(rule.action);
+    }
+  }
+  return actions;
+}
+
+function buildSuggestedModel({ domain, object, label, pattern, table, fields, actions, statusFlow, responseContract, permissionProfile, validationRules, errorCodes, detailSections, children }) {
+  return {
+    meta: {
+      domain,
+      object,
+      label,
+      ...(pattern ? { pattern } : {}),
+      version: '0.1.0',
+      description: `由 requirement:analyze 从自然语言需求推导出的候选业务模型。`,
+    },
+    data: {
+      table,
+      fields,
+      ...(children && children.length > 0 ? {
+        children: children.map((child) => ({
+          name: child.name,
+          label: child.label,
+          table: buildChildTableName(domain, object, child),
+          foreignKey: child.foreignKey,
+          fields: child.fields || [],
+        })),
+      } : {}),
+    },
+    app: {
+      actions,
+      defaultStatus: fields.some((item) => item.name === 'status') ? String(fields.find((item) => item.name === 'status').default || '') : undefined,
+      ...(statusFlow ? { statusFlow } : {}),
+      ...(responseContract ? { responseContract } : {}),
+      ...(permissionProfile ? { permissionProfile } : {}),
+      ...(validationRules && validationRules.length > 0 ? { validationRules } : {}),
+      ...(errorCodes && errorCodes.length > 0 ? { errorCodes } : {}),
+    },
+    ui: {
+      list: {
+        columns: buildListColumns(fields),
+        filters: buildListFilters(fields),
+      },
+      form: {
+        groups: [
+          {
+            title: '基本信息',
+            fields: fields.map((item) => item.name),
+          },
+          ...buildChildFormGroups(children),
+        ],
+      },
+      detail: {
+        sections: buildDetailSections(detailSections, children),
+      },
+    },
+  };
+}
+
+function alignStatusFlowActions(statusFlow, actions) {
+  if (!statusFlow) {
+    return null;
+  }
+  const allowed = new Set(actions || []);
+  return {
+    ...cloneField(statusFlow),
+    transitions: (statusFlow.transitions || []).filter((item) => allowed.has(item.action)),
+  };
+}
+
+function buildChildTableName(domain, object, child) {
+  if (child.table) {
+    return child.table;
+  }
+  const suffix = child.tableSuffix || snakeCase(child.name || 'detail');
+  return `${snakeCase(domain)}_${snakeCase(object)}_${snakeCase(suffix)}`;
+}
+
+function buildChildFormGroups(children) {
+  return (children || []).map((child) => ({
+    title: child.formGroupTitle || child.label || child.name,
+    childTable: child.name,
+  }));
+}
+
+function buildDetailSections(detailSections, children) {
+  const base = detailSections && detailSections.length > 0 ? [...detailSections] : ['basicInfo'];
+  for (const child of children || []) {
+    const section = child.detailSection || child.name;
+    if (!base.includes(section)) {
+      base.push(section);
+    }
+  }
+  return base;
+}
+
+function buildListColumns(fields) {
+  const preferred = fields
+    .filter((item) => ['leadCode', 'customerCode', 'opportunityCode', 'quoteCode', 'materialCode', 'documentNo', 'documentTitle', 'bizDate', 'categoryCode', 'leadName', 'customerName', 'opportunityName', 'quoteName', 'materialName', 'categoryName', 'parentName', 'source', 'stage', 'materialType', 'materialGroup', 'ownerName', 'sortOrder', 'status'].includes(item.name))
+    .map((item) => item.name);
+  const unique = Array.from(new Set([...preferred, 'createdAt']));
+  return unique;
+}
+
+function buildListFilters(fields) {
+  return fields
+    .filter((item) => ['leadCode', 'customerCode', 'opportunityCode', 'quoteCode', 'materialCode', 'documentNo', 'documentTitle', 'bizDate', 'categoryCode', 'leadName', 'customerName', 'opportunityName', 'quoteName', 'materialName', 'categoryName', 'parentName', 'source', 'stage', 'materialType', 'materialGroup', 'status'].includes(item.name))
+    .map((item) => item.name);
+}
+
+function validateInlineModel(model) {
+  const tempPath = path.join(
+    os.tmpdir(),
+    `scaffold-requirement-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.yaml`
+  );
+  fs.writeFileSync(tempPath, YAML.stringify(model), 'utf8');
+  try {
+    return validateModelFile(tempPath);
+  } finally {
+    if (fs.existsSync(tempPath)) {
+      fs.rmSync(tempPath, { force: true });
+    }
+  }
+}
+
+function renderMarkdown(result) {
+  const lines = [];
+  lines.push(`需求: ${result.requirement}`);
+  lines.push('');
+  lines.push(`decision: ${result.decision}`);
+  lines.push(`nextAction: ${result.nextAction}`);
+
+  if (result.inferred) {
+    lines.push('');
+    lines.push('识别结果:');
+    lines.push(`- domain: ${result.inferred.domain || '-'}`);
+    lines.push(`- object: ${result.inferred.object || '-'}`);
+    lines.push(`- label: ${result.inferred.label || '-'}`);
+    lines.push(`- pattern: ${result.inferred.pattern || '-'}`);
+    lines.push(`- actions: ${(result.inferred.actions || []).join(', ') || '-'}`);
+  }
+
+  if (result.reason && result.reason.length > 0) {
+    lines.push('');
+    lines.push('原因:');
+    for (const item of result.reason) {
+      lines.push(`- ${item}`);
+    }
+  }
+
+  if (result.missingInfo && result.missingInfo.length > 0) {
+    lines.push('');
+    lines.push('缺失信息:');
+    for (const item of result.missingInfo) {
+      lines.push(`- ${item}`);
+    }
+  }
+
+  if (result.warnings && result.warnings.length > 0) {
+    lines.push('');
+    lines.push('提示:');
+    for (const item of result.warnings) {
+      lines.push(`- ${item}`);
+    }
+  }
+
+  if (result.generatedSpecPath) {
+    lines.push('');
+    lines.push(`已写出候选模型: ${result.generatedSpecPath}`);
+  }
+
+  if (result.suggestedModel) {
+    lines.push('');
+    lines.push('候选模型:');
+    lines.push('```yaml');
+    lines.push(YAML.stringify(result.suggestedModel).trimEnd());
+    lines.push('```');
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+function normalizeText(value) {
+  return String(value).trim().toLowerCase().replace(/\s+/g, '');
+}
+
+function toLower(value) {
+  return String(value).toLowerCase();
+}
+
+function writeSuggestedSpec(model, filePath) {
+  const specPath = resolveOutputPath(filePath);
+  fs.mkdirSync(path.dirname(specPath), { recursive: true });
+  fs.writeFileSync(specPath, YAML.stringify(model), 'utf8');
+  return specPath;
+}
+
+function resolveOutputPath(filePath) {
+  if (path.isAbsolute(filePath)) {
+    return filePath;
+  }
+  const normalized = String(filePath).replace(/\\/g, '/');
+  if (normalized.startsWith('scaffold/')) {
+    return path.resolve(process.cwd(), normalized.slice('scaffold/'.length));
+  }
+  if (normalized.startsWith('specs/')) {
+    return resolveScaffoldPath(...normalized.split('/'));
+  }
+  return path.resolve(filePath);
+}
+
+module.exports = {
+  analyzeRequirement,
+  parseArgs,
+  readRequirementText,
+  renderMarkdown,
+  writeSuggestedSpec,
+};