openyida 2026.9.9 → 2026.9.10

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

@@ -143,8 +143,10 @@ function createParseArgs(dependencies) {
     if (args.includes('--help') || args.includes('-h')) {
       usage(t('create_form.usage_create_short'));
       hint(t('create_form.usage_update_short'));
+      hint('  batch: openyida create-form batch <appType> <plan.json> [--concurrency 1..4] [--json]');
       hint(t('create_form.example_create'));
       hint(t('create_form.example_update'));
+      hint('Example: openyida create-form batch "APP_XXX" .cache/openyida/forms/forms.json --json');
       return {
         mode: 'help',
         help: true,
@@ -347,8 +349,10 @@ function createParseArgs(dependencies) {
 
     usage(t('create_form.usage_create_short'));
     hint(t('create_form.usage_update_short'));
+    hint('  batch: openyida create-form batch <appType> <plan.json> [--concurrency 1..4] [--json]');
     hint(t('create_form.example_create'));
     hint(t('create_form.example_update'));
+    hint('Example: openyida create-form batch "APP_XXX" .cache/openyida/forms/forms.json --json');
     throwCreateFormError(t('create_form.usage_create_short'), 'CREATE_FORM_INVALID_ARGUMENTS');
   };
 }

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

@@ -6,12 +6,50 @@ const crypto = require('crypto');
 const { execFile } = require('child_process');
 const { CliError } = require('../../core/cli-error');
 const { t } = require('../../core/i18n');
+const { usage, hint } = require('../../core/chalk');
+const { assertNoEmojiInText, assertNoEmojiInValue } = require('../../core/no-emoji-guard');
+const { normalizeYidaLocale } = require('../../core/yida-i18n');
+const { FORM_NAV_ICONS, resolveFormNavIcon } = require('./nav-icon');
+
+const BATCH_USAGE = 'openyida create-form batch <appType> <plan.json> [--concurrency 1..4] [--check] [--json]';
+const BATCH_PLAN_EXAMPLE = '{"forms":[{"key":"customer","title":"客户","fieldsFile":"customer-fields.json"},{"key":"order","title":"订单","fieldsFile":"order-fields.json","dependsOn":["customer"]}]}';
 
 function invalid(reason) {
   throw new CliError(t('create_form.batch_invalid'), { code: 'FORM_BATCH_INVALID', details: { reason } });
 }
 
+function validateStaticDefinition(form, fields) {
+  try {
+    assertNoEmojiInText(form.title, { artifact: `forms.${form.key}.title` });
+    assertNoEmojiInValue(fields, { artifact: `forms.${form.key}.fields` });
+  } catch (error) {
+    invalid({
+      formKey: form.key,
+      errorCode: error?.code || 'OPENYIDA_ARTIFACT_EMOJI_FORBIDDEN',
+      errorMsg: error?.message || String(error),
+    });
+  }
+  if (form.icon !== undefined && !resolveFormNavIcon(form.icon, form.title, fields).icon) {
+    invalid({
+      formKey: form.key,
+      errorCode: 'CREATE_FORM_NAV_ICON_INVALID',
+      errorMsg: `Unsupported form navigation icon: ${form.icon}`,
+      icon: form.icon,
+      availableIconCount: FORM_NAV_ICONS.length,
+    });
+  }
+  if (form.locale !== undefined && !normalizeYidaLocale(form.locale)) {
+    invalid({
+      formKey: form.key,
+      errorCode: 'CREATE_FORM_INVALID_ARGUMENTS',
+      errorMsg: `Unsupported locale: ${form.locale}`,
+      locale: form.locale,
+    });
+  }
+}
+
 function parseArgs(args) {
+  if (args.includes('--help') || args.includes('-h')) { return { help: true }; }
   const options = { concurrency: 3, check: false };
   const positional = [];
   for (let i = 0; i < args.length; i++) {
@@ -25,11 +63,19 @@ function parseArgs(args) {
     }
   }
   if (positional.length !== 2 || !Number.isInteger(options.concurrency) || options.concurrency < 1 || options.concurrency > 4) {
-    invalid('create-form batch <appType> <plan.json> [--concurrency 1..4] [--check] [--json]');
+    invalid(BATCH_USAGE.replace(/^openyida /, ''));
   }
   return { ...options, appType: positional[0], file: path.resolve(positional[1]) };
 }
 
+function showHelp() {
+  usage(BATCH_USAGE);
+  hint('plan.json: ' + BATCH_PLAN_EXAMPLE);
+  hint('fieldsFile is resolved relative to plan.json; use dependsOn and {"$form":"key","field":"label"} for dependencies.');
+  hint('Run one authoritative batch. If it continues in background, do not stop it, delete its state, or fall back to create/update/resume.');
+  return { success: true, help: true, usage: BATCH_USAGE };
+}
+
 // References occupy a complete JSON value; ordinary text is preserved.
 function mapReferences(value, resolve) {
   if (Array.isArray(value)) { return value.map(item => mapReferences(item, resolve)); }
@@ -42,7 +88,38 @@ function mapReferences(value, resolve) {
   return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, mapReferences(item, resolve)]));
 }
 
-function loadPlan(file) {
+function normalizeAssociationReferences(value, appType) {
+  if (Array.isArray(value)) {
+    return value.map(item => normalizeAssociationReferences(item, appType));
+  }
+  if (!value || typeof value !== 'object') { return value; }
+  const normalized = Object.fromEntries(Object.entries(value).map(([key, item]) => [
+    key,
+    normalizeAssociationReferences(item, appType),
+  ]));
+  const association = value.associationForm;
+  if (
+    value.type === 'AssociationFormField' &&
+    association &&
+    typeof association === 'object' &&
+    !Array.isArray(association) &&
+    typeof association.$form === 'string'
+  ) {
+    const reference = { $form: association.$form };
+    normalized.associationForm = {
+      ...(appType ? { appType } : {}),
+      formUuid: reference,
+      ...(typeof association.field === 'string' && association.field.trim() ? {
+        mainFieldId: { ...reference, field: association.field },
+        mainFieldLabel: association.field,
+        mainComponentName: 'TextField',
+      } : {}),
+    };
+  }
+  return normalized;
+}
+
+function loadPlan(file, options = {}) {
   const input = JSON.parse(fs.readFileSync(file, 'utf8'));
   if (!Array.isArray(input.forms) || !input.forms.length) { invalid('forms'); }
   const forms = input.forms.map(form => {
@@ -52,7 +129,9 @@ function loadPlan(file) {
     if (Object.keys(form).some(key => !['key', 'title', 'fields', 'fieldsFile', 'dependsOn', 'formUuid', 'icon', 'locale'].includes(key))) { invalid(form.key); }
     if (form.formUuid !== undefined && (typeof form.formUuid !== 'string' || !form.formUuid.startsWith('FORM'))) { invalid(form.key); }
     for (const key of ['icon', 'locale']) { if (form[key] !== undefined && typeof form[key] !== 'string') { invalid(key); } }
-    const fields = form.fieldsFile === undefined ? form.fields : JSON.parse(fs.readFileSync(path.resolve(path.dirname(file), form.fieldsFile), 'utf8'));
+    const rawFields = form.fieldsFile === undefined ? form.fields : JSON.parse(fs.readFileSync(path.resolve(path.dirname(file), form.fieldsFile), 'utf8'));
+    const fields = normalizeAssociationReferences(rawFields, options.appType);
+    validateStaticDefinition(form, fields);
     const dependencies = new Set(form.dependsOn || []);
     mapReferences(fields, key => { dependencies.add(key); return 'FORM-PRECHECK'; });
     return { ...form, fields, dependsOn: [...dependencies] };
@@ -87,14 +166,75 @@ function parseOutput(stdout) {
   return output;
 }
 
-function execute(args) {
+function mergeCommandOutput(stdout, stderr, failed) {
+  const stdoutOutput = parseOutput(stdout);
+  const stderrOutput = parseOutput(stderr);
+  if (!failed) { return stdoutOutput || stderrOutput; }
+  if (!stdoutOutput) { return stderrOutput; }
+  if (!stderrOutput) { return stdoutOutput; }
+  return { ...stdoutOutput, ...stderrOutput };
+}
+
+function boundedDiagnostic(value) {
+  const text = String(value || '').trim();
+  return text.length > 4000 ? text.slice(-4000) : text;
+}
+
+function expectedReadbackFields(fields) {
+  const expected = [];
+  for (const field of Array.isArray(fields) ? fields : []) {
+    if (Array.isArray(field)) {
+      expected.push(...expectedReadbackFields(field));
+      continue;
+    }
+    if (!field || typeof field !== 'object') { continue; }
+    if (field.type === 'ColumnContainer') {
+      expected.push(...expectedReadbackFields(field.children));
+      continue;
+    }
+    if (['Divider', 'RichText', 'PageSection', 'GroupContainer'].includes(field.type)) { continue; }
+    if (typeof field.label === 'string' && field.label.trim()) {
+      expected.push({ label: field.label.trim(), componentName: field.type });
+    }
+  }
+  return expected;
+}
+
+function readbackMatchesExpectedFields(schema, fields) {
+  if (!schema || typeof schema.formUuid !== 'string' || !Array.isArray(schema.fields)) { return false; }
+  const actual = schema.fields.filter(field => field && typeof field === 'object');
+  return expectedReadbackFields(fields).every(expected => actual.some(field =>
+    field.label === expected.label && (!expected.componentName || field.componentName === expected.componentName)
+  ));
+}
+
+function readbackMismatch(formUuid, form, schema) {
+  const expected = expectedReadbackFields(form.fields);
+  const actual = Array.isArray(schema?.fields) ? schema.fields.map(field => ({
+    label: field?.label,
+    componentName: field?.componentName,
+  })) : [];
+  return Object.assign(new Error(`Form batch readback mismatch: ${form.key}`), {
+    output: {
+      success: false,
+      errorCode: 'FORM_BATCH_READBACK_MISMATCH',
+      errorMsg: `Created form ${form.key} did not contain all expected fields`,
+      formUuid,
+      details: { formKey: form.key, formUuid, expected, actual },
+    },
+  });
+}
+
+function execute(args, { execFile: execFileImpl = execFile } = {}) {
   return new Promise((resolve, reject) => {
-    execFile(process.execPath, [path.resolve(__dirname, '../../../bin/yida.js'), ...args, '--quiet'], {
+    execFileImpl(process.execPath, [path.resolve(__dirname, '../../../bin/yida.js'), ...args, '--quiet'], {
       env: { ...process.env, YIDA_QUIET: '1' }, timeout: 180000, maxBuffer: 8 * 1024 * 1024,
-    }, (error, stdout) => {
-      const output = parseOutput(stdout);
+    }, (error, stdout, stderr) => {
+      const output = mergeCommandOutput(stdout, stderr, Boolean(error));
       if (error || !output || typeof output !== 'object' || output.success === false) {
-        reject(Object.assign(new Error(output?.errorMsg || output?.error || error?.message || 'Missing command result'), { output }));
+        reject(Object.assign(new Error(
+          output?.errorMsg || output?.error || output?.message || boundedDiagnostic(stderr) || error?.message || 'Missing command result'
+        ), { output }));
       } else { resolve(output); }
     });
   });
@@ -140,7 +280,8 @@ async function schedule(forms, concurrency, results, worker, save) {
 
 async function run(args, dependencies = {}) {
   const options = parseArgs(args);
-  const { forms, groups } = loadPlan(options.file);
+  if (options.help) { return showHelp(); }
+  const { forms, groups } = loadPlan(options.file, { appType: options.appType });
   const call = dependencies.execute || execute;
   // Preflight all definitions before the first remote mutation.
   await schedule(forms.map(form => ({ ...form, dependsOn: [] })), options.concurrency, {}, async form => {
@@ -202,14 +343,28 @@ async function run(args, dependencies = {}) {
       }
       state.results[form.key].formUuid = formUuid;
       save(state);
+      let resumed = false;
       if (shouldResume) {
         await call(['create-form', 'resume', options.appType, formUuid, JSON.stringify(resolvedFields), '--json']);
+        resumed = true;
+      }
+      let schema = await call(['get-schema', options.appType, formUuid, '--field-map-json']);
+      if (!readbackMatchesExpectedFields(schema, resolvedFields) && !resumed && !form.formUuid) {
+        await call(['create-form', 'resume', options.appType, formUuid, JSON.stringify(resolvedFields), '--json']);
+        resumed = true;
+        schema = await call(['get-schema', options.appType, formUuid, '--field-map-json']);
+      }
+      if (schema.formUuid !== formUuid || !readbackMatchesExpectedFields(schema, resolvedFields)) {
+        throw readbackMismatch(formUuid, { ...form, fields: resolvedFields }, schema);
       }
-      const schema = await call(['get-schema', options.appType, formUuid, '--field-map-json']);
-      if (schema.formUuid !== formUuid || !Array.isArray(schema.fields)) { invalid(`schema: ${form.key}`); }
       return { formUuid, fields: schema.fields };
     }, () => save(state));
-    const output = { success: Object.values(state.results).every(item => item.status === 'success'), groups, stateFile, results: state.results };
+    const success = Object.values(state.results).every(item => item.status === 'success');
+    const output = { success, groups, stateFile, results: state.results };
+    if (!success) {
+      output.errorCode = 'FORM_BATCH_PARTIAL_FAILURE';
+      output.nextAction = 'Inspect the saved state and child error, then fix the batch input or recover known formUuid values. Do not fall back to create-form create.';
+    }
     console.log(JSON.stringify(output));
     if (!output.success) { process.exitCode = 1; }
     return output;
@@ -218,4 +373,17 @@ async function run(args, dependencies = {}) {
   }
 }
 
-module.exports = { run, parseArgs, loadPlan, mapReferences, schedule, parseOutput };
+module.exports = {
+  run,
+  parseArgs,
+  loadPlan,
+  mapReferences,
+  normalizeAssociationReferences,
+  schedule,
+  parseOutput,
+  mergeCommandOutput,
+  execute,
+  expectedReadbackFields,
+  readbackMatchesExpectedFields,
+  validateStaticDefinition,
+};

package/lib/app/create-form.js

@@ -123,6 +123,29 @@ function createCreateFormError(message, code, details) {
   });
 }
 
+function createFormPreflightError(errorObject, appType, formTitle) {
+  const error = errorObject && errorObject.isCliError
+    ? errorObject
+    : createCreateFormError(
+      errorObject?.message || String(errorObject || 'Create form preflight failed'),
+      'CREATE_FORM_PREFLIGHT_FAILED'
+    );
+  const existing = error.details && typeof error.details === 'object' && !Array.isArray(error.details)
+    ? error.details
+    : {};
+  error.details = {
+    ...existing,
+    stage: 'preflight',
+    retryable: true,
+    retrySafe: true,
+    sideEffectState: 'not_started',
+    mutationAccepted: false,
+    mutationPerformed: false,
+    target: { resource: 'form', appType, formTitle },
+  };
+  return error;
+}
+
 const parseArgs = createParseArgs({
   parseOpenOption,
   normalizeYidaLocale,
@@ -4902,20 +4925,28 @@ async function mainCreate(parsedArgs, authRef) {
   label('Fields:', fieldsJsonOrFile);
 
   step(2, t('create_form.step_read_fields', 2));
-  assertNoEmojiInDefinitionFileName(fieldsJsonOrFile);
-  const { fields, columns, validations } = readFieldsDefinition(fieldsJsonOrFile);
-  assertNoEmojiInFormDefinition(formTitle, fields, validations);
-  validateFormFieldDefinitions(fields);
-  const iconResolution = resolveFormNavIcon(parsedArgs.icon, formTitle, fields);
-  if (!iconResolution.icon) {
-    throwCreateFormError(
-      `Unsupported form navigation icon: ${parsedArgs.icon}. Run openyida create-form icons --json for the supported catalog.`,
-      'CREATE_FORM_NAV_ICON_INVALID',
-      {
-        icon: parsedArgs.icon,
-        availableIconCount: FORM_NAV_ICONS.length,
-      }
-    );
+  let fields;
+  let columns;
+  let validations;
+  let iconResolution;
+  try {
+    assertNoEmojiInDefinitionFileName(fieldsJsonOrFile);
+    ({ fields, columns, validations } = readFieldsDefinition(fieldsJsonOrFile));
+    assertNoEmojiInFormDefinition(formTitle, fields, validations);
+    validateFormFieldDefinitions(fields);
+    iconResolution = resolveFormNavIcon(parsedArgs.icon, formTitle, fields);
+    if (!iconResolution.icon) {
+      throwCreateFormError(
+        `Unsupported form navigation icon: ${parsedArgs.icon}. Run openyida create-form icons --json for the supported catalog.`,
+        'CREATE_FORM_NAV_ICON_INVALID',
+        {
+          icon: parsedArgs.icon,
+          availableIconCount: FORM_NAV_ICONS.length,
+        }
+      );
+    }
+  } catch (preflightError) {
+    throw createFormPreflightError(preflightError, appType, formTitle);
   }
   const formIcon = iconResolution.icon;
   const fieldCount = countDataFieldDefinitions(fields);

package/lib/core/cli-error.js

@@ -90,8 +90,17 @@ function shouldUseStructuredErrorOutput(error, args = []) {
     && details.retrySafe === false
     && details.sideEffectState === 'unknown'
   );
+  const deterministicPreflightFailure = !!(
+    details
+    && typeof details === 'object'
+    && !Array.isArray(details)
+    && details.stage === 'preflight'
+    && details.retrySafe === true
+    && details.sideEffectState === 'not_started'
+    && details.mutationPerformed === false
+  );
   const navigationOrderFailure = /^NAV_ORDER_/.test(error.code || '');
-  return ownedPartial || mutationOutcomeUnknown || navigationOrderFailure;
+  return ownedPartial || mutationOutcomeUnknown || deterministicPreflightFailure || navigationOrderFailure;
 }
 
 module.exports = {

package/lib/core/command-manifest.js

@@ -1556,7 +1556,7 @@ function summarizeLocalizedCommands(commands) {
         theme_command_ids: ['sample', 'create-app', 'update-app'],
         navigation_command_ids: { platform: ['update-app', 'nav-group'], custom: ['update-app', 'update-form-config', 'get-form-config'] },
         navigation_policy: 'Before PRD planning, reuse explicit navigation choices. During first-time intake, ask only when unknown: platform-l-shape, platform-top, platform-side, custom, with neutral descriptions and no preselection. For custom navigation also settle side/top/mixed/dock. Store type/source/reason/variant in the brief. Custom navigation requires app and per-page navigation hiding with readback; layout and navigation tone are separate choices.',
-        design_mode_policy: 'Analyze requirements first. First-time builds include new apps and existing apps without business pages. Reuse detailed supplied plans; if the mode is unspecified, ask whether to prepare a PRD for confirmation (Plan, more detailed and slower) or build from the supplied requirements (Fast). Without detailed requirements, offer Fast and Plan neutrally. Confirm unresolved navigation, custom navigation layout, visual style and page scope before planning or resource creation. Existing business apps only clarify the current change. Plan uses design-plan init parallelTasks for concurrent business and base visuals in separate files, then page visual bindings; publish settled modules with design-plan preview, then materialize --from-preview validates the complete draft and writes PRD, design, HTML and theme; the business-file/visual-file merge remains available; confirm the displayed revision before building.',
+        design_mode_policy: 'Analyze requirements first. First-time builds include new apps and existing apps without business pages. Reuse detailed supplied plans; if the mode is unspecified, ask whether to prepare a PRD for confirmation (Plan, more detailed and slower) or build from the supplied requirements (Fast). Without detailed requirements, offer Fast and Plan neutrally. Confirm unresolved navigation, custom navigation layout, visual style and page scope before planning or resource creation. Existing business apps only clarify the current change. A named resource-only request with explicitScope.allowInferredResources=false skips unrelated navigation and visual questions. Standard Plan uses design-plan init parallelTasks, then executes the returned materialize.command exactly once with business-file and visual-file; preview and --from-preview are only for explicitly incremental large plans. Confirm the displayed revision before building, and do not materialize or patch again after confirmation.',
         product_design_policy: 'yida-requirement-analysis owns shared facts and first-time intake. yida-prd owns business planning; yida-design owns visual design. Reuse the same confirmed brief and supplied details. Prepare business and base visuals concurrently, then bind visuals to settled page tasks. yida-app merges and checks the artifacts before creating resources. Plan uses the compact authoring contract and selected theme context; the CLI reads full templates and renders all artifacts.',
         ui_guidance_policy: 'Page implementation consumes yida-prd prd.md for positioning, information architecture, page prototype, native form entry policy, material strategy, business-specific checks, resource creation order, page implementation delivery order, navigation order, and acceptance criteria; it consumes yida-design design.md for app custom theme CSS delivery, themeColor/navTheme, visual states, visualScaffold, surface material, rounded rules, density rules, components, and state styling. prd.md and design.md are the only design sources of truth. Page implementation may extract page-spec.json as a derived implementation handoff from prd.md + design.md; conflicts are resolved by sending business conflicts to yida-prd and visual conflicts to yida-design before regenerating the spec. Core normal forms default to 1-3 business sample records before page implementation, followed by query readback. An explicit opt-out, configuration dictionary, sensitive data, or lack of safely constructible values requires a recorded skip reason. Screenshots, public sharing, data-source deep binding, and fine navigation grouping are optional after explicit user request or PRD acceptance criteria.',
         default_nav_order_policy: 'For custom navigation, implement PRD navigation order in the custom shell and verify app/page navigation hiding; skip platform nav-group ordering. For platform navigation: after the primary page is successfully published, perform exactly one navigation order operation. If the PRD names a navigation order, publish without --auto-nav-order and then call openyida nav-group order <appType> <items...>. If the PRD only gives broad groups or is missing navigation order, use openyida publish ... --auto-nav-order and do not call nav-group order or auto-order afterward. Explicit and automatic ordering are mutually exclusive; never generate per-item move loops. The fallback priority is portal/home/workbench entry > business handling > data management > business analytics > system configuration.',

package/lib/design-plan/init.js

@@ -8,14 +8,49 @@ const { planBase } = require('./parallel');
 
 const ROOT = path.resolve(__dirname, '../../yida-skills/skills/yida-design/sub_skill/yida-design-plan');
 
+function list(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function customScene(scene) {
+  return !['form', 'process-form', 'report'].includes(scene?.kind);
+}
+
+function resourceOnlyScope(brief) {
+  if (brief.explicitScope?.allowInferredResources === false) {return true;}
+  const scopedForms = list(brief.explicitScope?.forms);
+  const confirmedCustomPages = list(brief.pageScenes).filter(customScene);
+  return scopedForms.length > 0 && confirmedCustomPages.length === 0;
+}
+
+function scopeEntryMatchesScene(entry, scene) {
+  const candidate = typeof entry === 'string' ? entry : entry?.key || entry?.name;
+  return candidate && [scene?.key, scene?.name].includes(candidate);
+}
+
 function initialize(inputPath, options = {}) {
   const input = path.resolve(inputPath);
   const brief = readJson(input, 'requirement-brief.json');
   const project = brief.projectName;
+  if ((project === undefined || project === null || project === '')
+    && typeof brief.meta?.projectName === 'string'
+    && brief.meta.projectName.trim()) {
+    throw new CliError('projectName 必须位于 requirement-brief.json 根级；检测到 meta.projectName，请将该字段移动到根级后重试，不要更换项目名', {
+      code: 'DESIGN_PLAN_PROJECT_NAME_MISPLACED',
+      details: {
+        expectedPath: 'projectName',
+        actualPath: 'meta.projectName',
+        nextAction: 'move_project_name_to_root',
+        retryable: true,
+        retrySafe: true,
+      },
+    });
+  }
   if (typeof project !== 'string' || !project.trim() || /[/\\]/.test(project) || ['.', '..'].includes(project)) {
     throw new CliError('projectName 必须是单层项目目录名', { code: 'DESIGN_PLAN_INVALID_PROJECT' });
   }
-  if (brief.intake?.confirmed !== true || brief.openQuestions?.length) {
+  const resourceOnly = resourceOnlyScope(brief);
+  if ((!resourceOnly && brief.intake?.confirmed !== true) || brief.openQuestions?.length) {
     throw new CliError('请先完成需求确认并记录 intake.confirmed=true', { code: 'DESIGN_PLAN_INTAKE_REQUIRED' });
   }
   if (!['platform-l-shape', 'platform-top', 'platform-side', 'custom'].includes(brief.navigation?.type)
@@ -38,7 +73,10 @@ function initialize(inputPath, options = {}) {
   if ([output, guide, business, visual].some(file => fs.existsSync(file))) {
     throw new CliError('计划或编写上下文已存在，请继续补充现有文件', { code: 'DESIGN_PLAN_ALREADY_EXISTS' });
   }
-  const scenes = (brief.pageScenes || []).filter(scene => !['form', 'process-form', 'report'].includes(scene?.kind));
+  const scopedPages = list(brief.explicitScope?.pages);
+  const scenes = list(brief.pageScenes)
+    .filter(customScene)
+    .filter(scene => !resourceOnly || scopedPages.some(entry => scopeEntryMatchesScene(entry, scene)));
   const pages = scenes.map((scene, index) => {
     const source = typeof scene === 'string' ? { name: scene } : scene;
     const { key, ...facts } = source;
@@ -49,19 +87,49 @@ function initialize(inputPath, options = {}) {
       density: '', permissionSummary: '', dataBinding: '', dataSources: [], ...facts };
   });
   const choice = brief.visualSelection || {};
-  const app = brief.resourceContext?.app || {};
+  const app = brief.resourceContext?.app || brief.resourceContext || {};
   const appConfig = { navigationType: brief.navigation.type };
   for (const key of ['appType', 'corpId', 'baseUrl']) {if (app[key]) {appConfig[key] = app[key];}}
+  const businessGoals = Array.isArray(brief.businessGoals)
+    ? brief.businessGoals
+    : (typeof brief.businessGoals === 'string' && brief.businessGoals.trim() ? [brief.businessGoals] : []);
+  const modelInputs = (resourceOnly && list(brief.explicitScope?.forms).length > 0
+    ? list(brief.explicitScope.forms)
+    : list(brief.businessObjects)).map(item => {
+    if (typeof item !== 'string') {return item;}
+    return list(brief.businessObjects).find(candidate => candidate?.name === item) || item;
+  });
+  const normalizedScope = {
+    ...brief.explicitScope,
+    ...(resourceOnly ? {
+      allowInferredResources: false,
+      pages: scopedPages.filter(entry => scenes.some(scene => scopeEntryMatchesScene(entry, scene))),
+    } : {}),
+  };
+  const rolePermissionSummary = list(brief.targetUsers)
+    .map(user => typeof user === 'string' ? `${user}：使用本轮范围内已授权资源` : '')
+    .filter(Boolean);
+  if (resourceOnly && rolePermissionSummary.length === 0) {
+    rolePermissionSummary.push('应用成员：使用本轮范围内已授权资源');
+  }
   const plan = {
     schemaVersion: '2.0',
-    meta: { projectName: project, appName: brief.appName || project, revision: '1', status: 'draft', source: input,
+    meta: { projectName: project, appName: brief.appName || brief.projectDisplayName || brief.meta?.displayName || project, revision: '1', status: 'draft', source: input,
       businessDomain: brief.industry || '', experienceTopology: '',
       planState: { planConfirmed: false, presentedRevision: null, confirmedRevision: null } },
-    overview: { summary: (brief.businessGoals || []).join('；'), businessGraph: { relations: [] }, rolePermissionSummary: [] },
-    dataModels: (brief.businessObjects || []).map(item => {
+    overview: { summary: businessGoals.join('；'), businessGraph: { relations: [] }, rolePermissionSummary },
+    dataModels: modelInputs.map(item => {
       const model = typeof item === 'string' ? { name: item } : item;
       return { ...model, name: model.name, formType: model.formType || '宜搭表单', description: model.description || '', fields: Array.isArray(model.fields) ? model.fields : [] };
-    }), businessFlows: [], pages: { customPageDetails: pages }, execution: { appConfig, explicitScope: { ...brief.explicitScope, navigation: brief.navigation } },
+    }), businessFlows: [], pages: { customPageDetails: pages }, execution: {
+      appConfig,
+      explicitScope: { ...normalizedScope, navigation: brief.navigation },
+      ...(resourceOnly ? {
+        sampleDataPlan: modelInputs
+          .filter(item => !String(item?.formType || '').includes('流程'))
+          .map(item => ({ form: typeof item === 'string' ? item : item.name, skipReason: '本轮显式窄范围不包含示例数据' })),
+      } : {}),
+    },
     visualStyle: {
       ...(choice.tokens ? { tokens: choice.tokens } : {}),
       ...(choice.evidence ? { evidence: choice.evidence } : {}),
@@ -82,14 +150,23 @@ function initialize(inputPath, options = {}) {
   const patterns = readJson(path.join(ROOT, 'templates/page-patterns/index.json')).patterns;
   const context = [
     '# 计划编写上下文', '', `需求事实：${input}`, `计划目录：${outputDir}`, '',
-    '先读 build-plan-compact-schema.md；标准首版一次完成 business.json，复用已预填的 visual.json 后合并物化。只有视觉选择不完整或存在品牌稿、参考图、逐页特殊视觉要求时才补充视觉。保留各文件 base、页面 ID 与已有需求细节；普通首版不逐模块调用 preview。', '',
+    `先读 build-plan-compact-schema.md，再读 init 已创建的 business.json；保留 base 并一次补完 facts 后写回。business facts 只能包含 overview、dataModels、businessFlows、pages 和可选 execution，不得写 visualStyle。写完后只执行一次：openyida design-plan materialize ${output} --business-file ${business} --visual-file ${visual} --json。标准首版禁止先调用 --from-preview、preview、--check 或无参数 materialize，也不要用 Glob 或额外 Read 检查产物；成功结果已返回 HTML 路径和 revision。只有视觉选择不完整或存在品牌稿、参考图、逐页特殊视觉要求时才补充视觉。保留页面 ID 与已有需求细节。`, '',
     '## 页面模式', ...patterns.map(item => `- ${item.id}（${item.label}）：${item.mustKeep.join('；')}`), '',
     `## 已选风格：${theme.label}`, overview.trim(), '',
     '用户确认的配色优先于模板固定灰阶：surfaceTone=brand-tinted 将浅色页面、填充和边界与主色协调，正文保留中性层级；用户明确只改强调色、保持中性或忠实参考配色时设为 theme。深色表面保留原层级。不要为了模板的无彩限制撤掉用户要求的品牌氛围。', '',
     '完整主题的 token、组件、状态和响应式规则由 CLI 注入 design.md；调整具体组件时按需读取对应模板章节。', '',
   ].join('\n');
   const base = planBase(plan);
-  const businessPart = `${JSON.stringify({ base, ready: false, facts: {} }, null, 2)}\n`;
+  const businessFacts = Object.fromEntries(
+    ['overview', 'dataModels', 'businessFlows', 'pages', 'execution'].map(key => [key, plan[key]]),
+  );
+  const businessReady = resourceOnly
+    && businessGoals.length > 0
+    && rolePermissionSummary.length > 0
+    && plan.dataModels.length > 0
+    && plan.dataModels.every(model => model.name && list(model.fields).length > 0
+      && model.fields.every(field => field?.name && field?.type && typeof field.required === 'boolean'));
+  const businessPart = `${JSON.stringify({ base, ready: businessReady, facts: businessFacts }, null, 2)}\n`;
   // The intake already records an atomic visual selection. Seed it here so a
   // standard first Plan only needs one model planning pass for business facts.
   const selectedVisual = plan.visualStyle.forUser;
@@ -100,10 +177,11 @@ function initialize(inputPath, options = {}) {
   const visualPart = `${JSON.stringify({ base, ready: visualReady, facts: { visualStyle: plan.visualStyle } }, null, 2)}\n`;
   writeFiles([[output, `${JSON.stringify(plan, null, 2)}\n`], [guide, context], [business, businessPart], [visual, visualPart]]);
   return { success: true, input, output, context: guide, contract: path.join(ROOT, 'references/build-plan-compact-schema.md'), draft: true,
-    preview: { command: `openyida design-plan preview ${output} --part-file <module.json> --json`, modules: ['overview', 'dataModels', 'businessFlows', 'pages', 'visualStyle'], finalize: `openyida design-plan materialize ${output} --from-preview --json` },
-    parallelTasks: [{ id: 'business', skill: 'yida-prd', output: business, dependsOn: [] },
+    materialize: { mode: 'complete_files_once', maxCalls: 1,
+      command: `openyida design-plan materialize ${output} --business-file ${business} --visual-file ${visual} --json` },
+    parallelTasks: [...(!businessReady ? [{ id: 'business', skill: 'yida-prd', output: business, dependsOn: [] }] : []),
       ...(!visualReady ? [{ id: 'visual-selection', skill: 'yida-design', output: visual, dependsOn: [] }] : [])],
-    preparedInputs: { visual, visualReady },
+    preparedInputs: { business, businessReady, visual, visualReady },
     optionalTasks: [{ id: 'visual-refinement', skill: 'yida-design', input: business, output: visual, dependsOn: ['business'],
       when: 'brand material, reference images, or explicit page-specific visual differences require refinement' }],
   };

package/lib/design-plan/materialize.js

@@ -253,6 +253,7 @@ function buildExecution(plan) {
   const models = plan.dataModels || [];
   const { navigationStyle } = visualSelections(plan);
   const execution = plan.execution === undefined ? {} : plan.execution;
+  const resourceOnly = execution.explicitScope?.allowInferredResources === false;
   validateBusiness(plan, execution);
   const visualConfig = { navTheme: navigationStyle.tone, logoSource: 'appIcon' };
   const navigation = navigationConfig(plan);
@@ -272,16 +273,20 @@ function buildExecution(plan) {
   ];
   const handoff = {
     resourceBlueprint: resources,
-    resourceCreationOrder: ['应用与主题配置', ...models.map(model => model.name), '初始示例数据', ...pages.map(page => page.name), '发布与导航排序'],
+    resourceCreationOrder: resourceOnly
+      ? [...models.map(model => model.name), ...pages.map(page => page.name)]
+      : ['应用与主题配置', ...models.map(model => model.name), '初始示例数据', ...pages.map(page => page.name), '发布与导航排序'],
     pageImplementationOrder: pages.map(page => page.pageId || page.name),
     navigationOrder: [],
-    navigationFallback: '发布时使用 --auto-nav-order，不再重复执行排序',
+    navigationFallback: resourceOnly ? '本轮显式窄范围不执行导航排序' : '发布时使用 --auto-nav-order，不再重复执行排序',
     acceptanceCriteria: [
       ...models.map(model => `${model.name}的字段、必填规则与关系符合数据模型`),
       ...(plan.businessFlows || []).map(flow => `${flow.name}按触发条件和业务规则执行`),
       ...pages.map(page => `${page.name}支持${page.primaryTask || page.positioning}`),
-      '应用主题按 design.md 配置，页面消费同一组 token',
-      '核心普通表单示例数据写入并抽查，或说明跳过原因',
+      ...(!resourceOnly ? [
+        '应用主题按 design.md 配置，页面消费同一组 token',
+        '核心普通表单示例数据写入并抽查，或说明跳过原因',
+      ] : []),
     ],
     ...execution,
     interactionStates: { ...interactionStates, ...execution.interactionStates },
@@ -802,8 +807,9 @@ function prepareArtifacts(sourcePlan, outputDir, themeSeed) {
     } finally {timings[name] = Math.round((performance.now() - start) * 100) / 100;}
   };
   const plan = measure('validationAndNormalizationMs', () => {
-    authoringIssues = validateAuthoring(sourcePlan);
-    return normalizePlan(sourcePlan);
+    const normalized = normalizePlan(sourcePlan);
+    authoringIssues = validateAuthoring(normalized);
+    return normalized;
   });
   const execution = measure('businessValidationMs', () => buildExecution(plan));
   const prd = measure('prdMs', () => renderPrd(plan, execution));

package/lib/design-plan/normalize.js

@@ -28,6 +28,90 @@ function compactSchema(plan) {
   return /^2(?:\.|$)/.test(String(plan.schemaVersion || ''));
 }
 
+function normalizeEquivalentAuthoring(plan) {
+  const summary = plan.overview?.rolePermissionSummary;
+  if (Array.isArray(summary)) {
+    plan.overview.rolePermissionSummary = summary.map((entry) => {
+      if (typeof entry === 'string') {return entry;}
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {return entry;}
+      const role = entry.role || entry.name || '';
+      const permission = entry.permissions || entry.permission || entry.scope || entry.description || '';
+      return [role, permission].filter(Boolean).join('：');
+    });
+  }
+
+  for (const model of list(plan.dataModels)) {
+    const fields = list(model.fields);
+    for (const field of fields) {
+      if (!field?.type && typeof field?.fieldType === 'string') {field.type = field.fieldType;}
+      if (field && Object.prototype.hasOwnProperty.call(field, 'fieldType')) {delete field.fieldType;}
+    }
+    if (Array.isArray(model.sampleRecords)) {
+      model.sampleRecords = model.sampleRecords.map((record) => {
+        if (!record || typeof record !== 'object' || Array.isArray(record)) {return record;}
+        const values = record.fields && typeof record.fields === 'object' && !Array.isArray(record.fields)
+          ? record.fields
+          : record;
+        return Object.fromEntries(Object.entries(values).map(([key, value]) => {
+          const field = fields.find(item => item?.name === key || item?.key === key);
+          return [field?.name || key, value];
+        }));
+      });
+    } else if (
+      model.sampleRecords
+      && typeof model.sampleRecords === 'object'
+      && !Array.isArray(model.sampleRecords)
+      && typeof model.sampleRecords.skipReason === 'string'
+      && model.sampleRecords.skipReason.trim()
+    ) {
+      model.skipSampleReason = model.sampleRecords.skipReason.trim();
+      delete model.sampleRecords;
+    }
+  }
+
+  const execution = plan.execution = plan.execution || {};
+  const scope = execution.explicitScope;
+  if (scope?.allowInferredResources === false && scope.sampleData === undefined) {
+    execution.sampleDataPlan = list(plan.dataModels)
+      .filter(model => !String(model?.formType || '').includes('流程'))
+      .map(model => ({ form: model.name, skipReason: '本轮显式窄范围不包含示例数据' }));
+  }
+
+  if (typeof execution.appConfig?.hideAppNav === 'boolean') {
+    execution.appConfig.hideAppNav = execution.appConfig.hideAppNav ? 'y' : 'n';
+  }
+
+  const modelNames = list(plan.dataModels).map(model => model?.name).filter(Boolean);
+  for (const page of list(plan.pages?.customPageDetails)) {
+    if (page.dataBinding && typeof page.dataBinding === 'object' && !Array.isArray(page.dataBinding)) {
+      page.dataSources = list(page.dataSources).length > 0 ? page.dataSources : list(page.dataBinding.dataSources);
+      page.dataBinding = page.dataBinding.mode || page.dataBinding.type || '';
+    }
+    page.dataSources = list(page.dataSources).map(source => {
+      const candidate = typeof source === 'string' ? source : source?.source || source?.name;
+      if (typeof candidate !== 'string') {return candidate;}
+      const trimmed = candidate.trim();
+      return modelNames.find(name => trimmed === name || trimmed === `${name}表单`) || trimmed;
+    });
+    if (
+      !['form', 'report', 'connector', 'static-empty'].includes(page.dataBinding)
+      && page.dataSources.length > 0
+      && page.dataSources.every(source => modelNames.includes(source))
+    ) {
+      page.dataBinding = 'form';
+    }
+  }
+
+  const navigation = plan.visualStyle?.forUser?.navigationStyle;
+  if (navigation) {
+    navigation.structure = {
+      'platform-l-shape': 'side',
+      'platform-side': 'side',
+      'platform-top': 'top',
+    }[navigation.structure] || navigation.structure;
+  }
+}
+
 function pageType(formType) {
   if (String(formType || '').includes('流程')) {
     return '宜搭流程表单';
@@ -75,7 +159,9 @@ function ensureOverview(plan) {
   if (!list(overview.businessGraph.nodes).length) {
     overview.businessGraph.nodes = deriveGraphNodes(plan.dataModels);
   }
-  overview.businessGraph.relations = list(overview.businessGraph.relations);
+  const modelNames = new Set(list(plan.dataModels).map(model => model?.name).filter(Boolean));
+  overview.businessGraph.relations = list(overview.businessGraph.relations)
+    .filter(relation => relation && modelNames.has(relation.from) && modelNames.has(relation.to));
   if (!list(overview.dataModelSummary).length) {
     overview.dataModelSummary = list(plan.dataModels).map(model => `${model.name}：${model.description || '核心业务数据'}`);
   }
@@ -259,6 +345,7 @@ function normalizePlan(sourcePlan) {
     return sourcePlan;
   }
   const plan = clone(sourcePlan);
+  normalizeEquivalentAuthoring(plan);
   const themeIndex = readJson(THEME_INDEX_PATH, '主题索引');
   const pagePatternIndex = readJson(PAGE_PATTERN_INDEX_PATH, '页面模式索引');
   ensureOverview(plan);

package/package.json

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

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

@@ -7,6 +7,10 @@ description: 宜搭完整应用开发编排技能。对普通 OpenYida 应用做
 
 完整应用编排技能。它负责把一次“创建/搭建/补齐应用”的需求拆成资源解析、产品设计、资源落地、页面发布和结果输出。全局 CLI、ID、存储、发布和输出规则以主入口 `SKILL.md` 为准；按步骤执行该步骤所需 `use_skill(...)`。
 
+## 模式入口（先按这里路由）
+
+Plan 模式只读取 `workflow/step-1-resource-context.md`、`workflow/step-2-design.md` 和精确路径 `workflow/plan/workflow.md`；后者已经包含完整 Plan 入口。禁止用 Glob 查找 Plan 文件，也不要额外读取 `workflow/plan/step-1-understand.md` 或 `workflow/plan/step-2-confirm.md`。Plan 确认恢复后，若 `explicitScope.allowInferredResources=false`，直接读取 `workflow/step-4-forms-processes.md` 实施范围内资源，不再重读 Step 1、调用 list-forms 或做应用设置预检。
+
 ## 步骤模版（进行时展示给用户看的步骤）
 
 完整应用搭建时，直接使用对应模式的步骤名称。
@@ -36,6 +40,10 @@ description: 宜搭完整应用开发编排技能。对普通 OpenYida 应用做
 
 已有应用时，直接省略“创建应用”，不另列“复用现有应用”待办，后续步骤重新编号；无需示例数据时跳过对应步骤。步骤状态按真实进度更新，有独立输入的工作可同时进行。
 
+用户明确把本轮交付限定为一个或若干具体表单、流程、报表或页面时，按 `explicitScope` 只保留达到该交付所需的步骤；即使需求背景使用“应用/系统”，也不自动补示例数据、自定义工作台、主题设置、导航排序或其他资源。Plan 模式仍生成并确认方案，但确认后只执行该窄范围。
+
+若窄范围只要求创建一个普通表单并交付链接，成功的 `create-form create` 结果就是本轮资源回读证据：立即交付其中的真实链接并停止。不要再调用 `get-schema`、`list-forms`、数据管理技能、示例数据、主题或导航命令，除非创建结果明确缺少 ID/链接或用户另外要求这些内容。
+
 禁区：待办标题、说明和进度不出现技能名、命令、文件路径、登录账号、内部资源 ID；这些留在工具调用里。用户明确询问技术细节时再解释。
 
 ## 触发条件
@@ -60,7 +68,7 @@ description: 宜搭完整应用开发编排技能。对普通 OpenYida 应用做
 | 8 | [发布页面并排序导航](workflow/step-8-publish-navigation.md) | 执行 `use_skill("yida-publish-page")`，发布本轮源码到主页面并执行轻量导航排序 | 已发布主页面 URL |
 | 9 | [输出与收尾](workflow/step-9-output-finish.md) | 核对完成条件，按业务语言输出结果 | 2-3 句业务总结 + 一组应用访问入口 |
 
-独立工作按 [并行执行](workflow/parallel-work.md) 调度，任务分别产出，由主流程汇合。计划或主题确认后立即生成主题 CSS，appType 和 CSS 就绪就同步应用设置，不等待页面开发完成。
+独立工作按 [并行执行](workflow/parallel-work.md) 调度，任务分别产出，由主流程汇合。完整应用在计划或主题确认后生成主题 CSS，appType 和 CSS 就绪就同步应用设置；`explicitScope.allowInferredResources=false` 的资源级交付不生成或上传主题、不修改应用设置、不排序导航。
 
 ## 核心规则
 
@@ -68,11 +76,12 @@ description: 宜搭完整应用开发编排技能。对普通 OpenYida 应用做
 2. **显式目标优先**：本轮用户给出的 `appType`、`formUuid`、URL、页面名或流程标识，优先级高于绑定上下文和历史缓存；同级冲突或无法唯一识别时才问用户。
 3. **产品与视觉分工**：`yida-requirement-analysis` 先统一整理用户需求；业务目标、资源蓝图、页面结构、导航顺序和验收标准由 `yida-prd` 写入 `prd.md`；主题 token、布局、材质、圆角、密度、组件和状态规则由 `yida-design` 写入 `design.md`。两份文件校验通过前不得创建资源。
 4. **阶段技能按需加载**：进入应用壳、表单、流程、页面、发布、数据写入等阶段时，才执行对应 `use_skill(...)`。
-5. **真实 ID 和真实数据**：不编造 `appType`、`formUuid`、`fieldId`、`processCode`、`reportId`。完整应用默认给核心普通表单写入 1-3 条业务化 seed records 并 query 抽查；不适合造数时说明原因和空态方案。
+5. **真实 ID 和真实数据**：不编造 `appType`、`formUuid`、`fieldId`、`processCode`、`reportId`。无显式窄范围的完整应用默认给核心普通表单写入 1-3 条业务化 seed records 并 query 抽查；`explicitScope.allowInferredResources=false` 时不得增加未点名的 seed records 或页面。
 6. **自定义页面开发技能固定**：完整应用页面源码按 Step 7 执行。
 7. **删除必须确认**：用户要求删除应用时，先展示应用名称、应用 ID 和影响范围，等待明确“确认删除”后才能执行。
 8. **列表页选择**：默认使用普通表单的数据管理页；用户明确要求自定义列表页时才创建 display 页面。
 9. **交付物收口**：Step 2 的三个文件和 Step 9 的 build manifest 都是内部文件，不是用户交付物。表单、流程、报表和页面只在业务总结中概述，不逐项生成用户可见附件；宿主支持交付工具时，final 只交付一次“应用访问入口”组。
+10. **窄范围停止点**：完成 `explicitScope` 中的资源回读与真实链接交付后立即停止；不得为了满足完整应用默认完成条件继续进入被裁剪的 Step 5-8。
 
 ## 关键决策树
 

package/yida-skills/skills/yida-app/workflow/parallel-work.md

@@ -43,9 +43,11 @@
 
 标准 Plan 首版采用一次收齐：业务任务完成一个 `business.json`，视觉直接复用 init 根据已确认选择生成的 `visual.json`，随后合并物化。这样首版只等待一次模型规划。品牌稿、参考图、页面级特殊视觉或明确的视觉精修要求命中时，才由视觉任务更新 `visual.json`；超大需求需要展示中间进展时才使用 [按模块更新方案](incremental-preview.md)，全部完成后再用 `materialize --from-preview` 汇总校验。
 
+init 返回的 `materialize.command` 是标准首版唯一生成命令。执行成功后直接使用其 `outputs.html` 和 `revision` 展示确认，不通过 `--from-preview`、preview、Glob 或额外 Read 探测产物；确认后不再物化或 patch。`explicitScope.allowInferredResources=false` 时，完整主题仍可作为 Plan 展示的一部分，但不进入应用设置、导航或发布执行。
+
 `design-plan init` 返回 `parallelTasks` 和两个片段文件：
 
-- `business.json`：业务任务填写 facts 中的 overview、dataModels、businessFlows、pages 和可选 execution。可选 meta 仅填写 businessDomain、experienceTopology，完成后设 ready=true。
+- `business.json`：init 已预填业务骨架，业务任务必须先读后写，保留 base；facts 只能填写 overview、dataModels、businessFlows、pages 和可选 execution，禁止加入 visualStyle。一次补齐所有普通表单的 sampleDataPlan（不造数写 skipReason）和所有自定义页面的 permissionSummary，完成后设 ready=true。可选 meta 仅填写 businessDomain、experienceTopology。
 - `visual.json`：init 根据需求阶段原子保存的 `visualSelection` 写入 facts.visualStyle；主色、方向和导航明暗完整时设 `ready=true`，否则保持未就绪并返回 `visual-selection` 任务，只补充缺失选择。标准页面的完整主题和页面场景规则由 CLI 补齐。只有命中特殊视觉条件时，视觉任务才按业务页面更新项目差异与 `pageApplications`。
 
 两个文件的 base 由 CLI 生成，保留原值；任务读取同一份需求、草稿和主题上下文。业务片段完成后保持稳定，变更时通知视觉任务重新核对页面设计。

package/yida-skills/skills/yida-app/workflow/plan/step-4-deliver.md

@@ -24,6 +24,8 @@ openyida design-plan materialize prd/<项目名>/build-plan.json --from-preview
 
 CLI 完整校验后一起保存源计划、`prd.md`、`design.md`、`build-plan.html` 和 `app-theme.css`。HTML 使用预置模板，业务内容与 PRD 一致。
 
+标准首版必须直接执行 init 返回的 `materialize.command`；不得先试 `--from-preview`、`preview`、无参数 materialize 或 shell 重定向。成功 JSON 已包含 `outputs.html` 和 `revision`，直接用于下一步同一次结构化提问，不再 Glob 目录，也不额外 Read `prd.md`、`design.md` 或 `build-plan.json`。
+
 完整文件的职责与版本规则见 [完整文件合并](../parallel-work.md#plan-的-cli-交接)。直接维护源计划时先设 `meta.status=awaiting_confirmation`，再执行 `openyida design-plan materialize prd/<项目名>/build-plan.json --json`；仅做诊断时使用 `openyida design-plan materialize prd/<项目名>/build-plan.json --check --json`。正常生成已经包含完整校验，不先运行一次 --check 再重复生成。
 
 HTML 保留“需求总览、数据模型、业务流程、页面规划”四章，完整展示用户需要确认的业务、视觉、数据、顺序和验收内容；整体视觉放在需求总览，逐页视觉放在页面详情。展示范围见 [HTML 内容契约](../../../yida-design/sub_skill/yida-design-plan/assets/README.md#需求总览中的视觉信息)，Markdown 供 Agent 执行。
@@ -35,16 +37,16 @@ HTML 保留“需求总览、数据模型、业务流程、页面规划”四章
 按 [用户交互契约](../../../yida-design/references/ask-human-interaction-contract.md) 执行：
 
 1. 在会话中展示“当前这版方案”，并用 3–7 条业务摘要说明方案内容。
-2. 通过同一次结构化提问的 `attachments` 携带可打开的 `prd/<项目名>/build-plan.html`，并将 `revision` 设为当前 `meta.revision`；不得先发普通文本附件、再单独提问。
-3. 结构化交互成功创建后内部记录 `presentedRevision=meta.revision`。询问“确认并开始搭建”或“继续调整”，提交时由宿主原样回传 revision，将确认结果绑定到本次展示版本；收到确认或修改业务事实后再重新生成。用户可见版本称为“第 N 版方案”，展示序号与内部 revision 绑定。
+2. 必须实际调用 `ask_human` 创建结构化提问，并通过同一次调用的 `attachments` 携带可打开的 `prd/<项目名>/build-plan.html`；附件对象固定使用 `name: "build-plan.html"`，并将 `revision` 设为当前 `meta.revision`。只输出方案正文或普通 assistant 文本后结束本轮属于未完成，严禁用它替代 `ask_human`；也不得改成项目标题，或先发普通文本附件、再单独提问。
+3. 结构化交互成功创建后内部记录 `presentedRevision=meta.revision`。询问“确认并开始搭建”或“继续调整”，提交时由宿主原样回传 revision，将确认结果绑定到本次展示版本。用户可见版本称为“第 N 版方案”，展示序号与内部 revision 绑定。
 
-只有以下条件同时成立才交接：
+只有以下条件同时成立才交接；它们由本轮 ask_human 请求和回传在运行时判定，不要求把确认状态写回 workspace 文件：
 
 - `meta.status=confirmed`
 - `meta.planState.planConfirmed=true`
 - `meta.revision=presentedRevision=confirmedRevision`
 
-交接前运行不带 `--from-preview` 的生成命令同步确认状态，将同版本 `prd.md`、`design.md` 返回应用主流程 Step 3，执行 [公共主题 CSS 交接](../step-2-design.md#主题文件实现指令)。
+收到“确认并开始搭建”且回传 revision 等于展示 revision 后，直接进入同版本资源实施。确认之后严禁再次 materialize、patch、Edit 或 Read 计划来“同步确认状态”；不存在可写 `meta.planState.planConfirmed` 的确认命令。`explicitScope.allowInferredResources=false` 时也不执行主题 CSS、应用设置或导航交接，只创建范围内资源并回读、交付。
 
 ## 4. 处理调整
 

package/yida-skills/skills/yida-app/workflow/plan/workflow.md

@@ -13,16 +13,19 @@
 
 ## 执行顺序
 
-1. 复用 [已确认的需求](step-1-understand.md)，检查 [规划入口](step-2-confirm.md)。
+1. 直接复用已确认的 `requirement-brief.json`；本文件已经包含规划入口，不再额外读取 `step-1-understand.md` 或 `step-2-confirm.md`。
 2. 初始化计划草稿，CLI 返回编写契约与当前主题的精简上下文：
 
    ```bash
    openyida design-plan init .cache/openyida/<项目名>/requirement-brief.json --theme-id <已选主题> --json
    ```
+   `requirement-brief.json` 必须复用 `yida-requirement-analysis` 的输出结构，不要自行发明字段层级；`projectName` 位于 JSON 根级，`businessGoals` 等集合字段保持数组，命令第一次就传入 `visualSelection.themeId`。若 CLI 返回字段路径诊断，按 `expectedPath` 集中修正原文件后最多重试一次，不要通过反复更换项目名规避结构错误。
 
-3. 执行 init 返回的 `parallelTasks`：标准首版只有一个业务规划任务。视觉方向、主题色和导航样式已经在首次提问中确认，CLI 将其预填到 `preparedInputs.visual`，并从主题模板确定性补齐页面标准视觉，不再启动“基础视觉 → 等待页面 → 逐页视觉绑定”两段模型任务。
-4. 业务任务一次写完 `business.json` 后，直接使用预填的 `visual.json` 按 [完整文件合并](../parallel-work.md#plan-的-cli-交接) 物化 PRD、设计文档和 HTML。只有存在品牌稿、参考图、页面级特殊风格或用户明确要求精修时，才执行 `optionalTasks.visual-refinement` 后再物化。
-5. 按 [生成与确认](step-4-deliver.md) 校验、展示并确认当前方案。超大需求需要展示中间进展或用户明确要求边生成边查看时，才使用 [按模块更新方案](../incremental-preview.md)；普通首版不逐模块预览和重复渲染。
+3. 执行 init 返回的 `parallelTasks`：普通标准首版只有一个业务规划任务；显式窄范围且表单字段已完整时，CLI 返回 `preparedInputs.businessReady=true` 和空任务列表，直接进入第 4 步，不再 Read/Edit business 或补规划。视觉方向、主题色和导航样式已在需求阶段确定，CLI 将其预填到 `preparedInputs.visual`，并从主题模板确定性补齐页面标准视觉，不再启动“基础视觉 → 等待页面 → 逐页视觉绑定”两段模型任务。
+4. init 已创建并预填 `business.json` 骨架；先 Read 该文件，保留 `base`，一次补完后再 Write/Edit，避免覆盖保护失败。`facts` 只允许 overview、dataModels、businessFlows、pages 和可选 execution，绝不写 `visualStyle`。同一次补齐所有普通表单的 sampleDataPlan（窄范围不造数时写 skipReason）及所有自定义页面的 permissionSummary，然后直接执行 init 返回的 `materialize.command`，只物化一次。标准首版禁止先试 `--from-preview`、`preview`、`--check` 或无参数 materialize；成功 JSON 已返回 HTML 路径和 revision，不再用 Glob、Read 或帮助命令检查产物。只有存在品牌稿、参考图、页面级特殊风格或用户明确要求精修时，才执行 `optionalTasks.visual-refinement` 后再物化。
+5. 读取精确路径 `workflow/plan/step-4-deliver.md`，按其中契约直接展示并确认当前方案。超大需求需要展示中间进展或用户明确要求边生成边查看时，才使用 [按模块更新方案](../incremental-preview.md)；普通首版不逐模块预览和重复渲染。
+
+明确窄交付时，方案只描述 `explicitScope` 中的资源；确认后裁剪无关步骤，在这些资源回读并交付真实链接后停止。不得因用户使用“应用”一词自行增加 seed records、自定义页面、主题或导航工作。
 
 初次编写只读 CLI 返回的紧凑契约、当前主题上下文及共享需求；模板全文由 CLI 读取。具体组件定制、暗色浮层或复杂页面需要额外规则时，再读取对应章节。
 
@@ -42,4 +45,4 @@ build-plan.json（业务和视觉的源事实）
 
 草稿按已确定的模块更新，最终校验后统一保存三份文档和主题 CSS。调整由对应技能更新源事实，再由编排重新生成并确认，具体命令与版本条件见 [生成与确认](step-4-deliver.md)。
 
-用户交互按 [可见表达契约](../../../yida-design/references/ask-human-interaction-contract.md) 执行。当前展示版本确认后，将 `prd.md`、`design.md` 和已生成的 `outputs.theme` 立即交给应用主流程 Step 3；取得 appType 后马上同步主题设置，并行创建表单和开发页面，不重复生成 CSS，也不等页面完成。
+用户交互按 [可见表达契约](../../../yida-design/references/ask-human-interaction-contract.md) 执行。当前展示版本确认后，将 `prd.md`、`design.md` 和已生成的 `outputs.theme` 交给应用主流程 Step 3。仅完整应用同步主题设置；`explicitScope.allowInferredResources=false` 时忽略主题和导航交接，只创建范围内资源并交付，不重复物化计划。

package/yida-skills/skills/yida-app/workflow/step-2-design.md

@@ -12,6 +12,8 @@
 
 回答齐全后直接保存内部需求记录并进入 2.1；不把“生成需求简报”列为独立任务，不再扩写或展示简报请用户确认。已有确认记录且需求未变化时直接复用。记录粒度、保存和校验规则统一遵守上述需求分析流程。
 
+显式搭建方式属于本次任务的粘性输入。若用户在首次消息已选择 Plan，澄清业务模块、页面、导航或风格时不得再次询问模式，也不得在合并回答后改写为 Fast；进入 2.1 前必须以用户最后一次明确选择校验 `intake.designMode`。Fast 同理。
+
 执行规划前读取 `constraints.prohibitedActions`。PRD 与 design 必须把禁止项写成实现门禁：`theme-file` 禁止时沿用现有平台主题且不安排主题文件任务；`page-source` 禁止时只允许只读核查与非源码配置；`publish` 禁止时把发布明确标记为跳过。不得为了满足默认九步流程静默删除这些约束。
 
 ## 2.1 按已确认方式推进
@@ -21,6 +23,8 @@
 - Fast：继续 2.2–2.3；已有详细需求直接作为规划基础。
 - Plan：执行 [Plan 编排](plan/workflow.md)，用户确认当前方案后完成主题交接并进入 Step 3。
 
+Plan 分支从已加载 `yida-app` 的 Available Files 读取精确路径 `workflow/plan/workflow.md`；不要把当前文件名当目录拼成 `workflow/step-2-design/plan/workflow.md`，也不要用 Glob 猜路径。
+
 共享需求只整理一次。创建出的资源 ID 写入执行上下文；用户需求或范围实质变化时再更新需求与相关规划。需求文件与实施文档供内部执行，Plan 的 HTML 用于用户查看和确认方案。
 
 ## 2.2 同时生成 PRD 和视觉设计

package/yida-skills/skills/yida-app/workflow/step-4-forms-processes.md

@@ -1,6 +1,8 @@
 # Step 4：创建或更新表单/流程
 
-按 PRD 的依赖创建或复用表单和流程。同一轮需要新建两个及以上普通表单时，把独立表单和关联表单写入同一个 `forms.json`，通过 `dependsOn` / `$form` 表达依赖，并且只调用一次 `openyida create-form batch`；由 CLI 内部完成分组、真实 ID 回读和依赖调度，不逐个 create，也不由模型拆成多次 batch。某页所需表单、流程就绪后即可接入该页；不要因其他页面的资源未完成而阻塞无依赖页面开发。
+按 PRD 的依赖创建或复用表单和流程。同一轮需要新建两个及以上普通表单时，把独立表单和关联表单写入同一个 `forms.json`，通过 `dependsOn` / `$form` 表达依赖，并且只调用一次 `openyida create-form batch`；由 CLI 内部完成分组、真实 ID 回读和依赖调度，不逐个 create，也不由模型拆成多次 batch。调用前确认实际项目根，让 Write 的绝对路径与 Bash 从项目根使用的 `.cache/openyida/<项目名>/forms.json` 指向同一个物理文件，并用 Read 确认任务文件存在；不要用 batch 探测路径，收到 background pending 后也不要重试 batch。某页所需表单、流程就绪后即可接入该页；不要因其他页面的资源未完成而阻塞无依赖页面开发。
+
+`explicitScope.allowInferredResources=false` 且本轮只有一个普通表单时走最短路径：Write 一份字段文件后调用一次 `openyida create-form create`。Write 会创建父目录，禁止先用 `ls` 或 Bash 检查缓存目录。成功结果已包含真实 formUuid/链接时，直接交付并停止；不得继续 `get-schema`、写 schema evidence、加载数据管理技能、造示例数据、更新主题或排序导航。只有创建结果缺少本次明确验收所需字段时才做一次针对性回读。
 
 拿到真实 `appType` 和已确认的业务契约即可开始本步骤，不等待主题 CSS 上传或应用主题设置回读。主题分支与本步骤并行，按 [主题与业务资源的依赖](parallel-work.md#主题与业务资源的依赖) 汇合。
 

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

@@ -24,6 +24,7 @@ description: 表单页面创建与更新；支持 19 种业务字段和 Divider
 - 不要用此命令操作数据记录（增删改查），应使用 `yida-data-management`
 - 不要用 shell heredoc、`cat`/`echo`/`printf`/`tee` 或重定向生成字段、变更、补丁、规则、数据源 JSON 文件
 - OpenYida CLI 不要加 `2>/dev/null`；失败时保留 stdout/stderr 诊断，遇到 DENIED 或重复失败必须换策略
+- 多表单 batch 契约已在本技能给出时，不要再调用 `create-form batch --help`、`create-form batch --check`，也不要搜索 CLI 安装目录或源码来探测格式；这些调用同样占用本轮唯一一次 batch 调用名额
 - 已有目标表单且用户是改字段/联动/属性时，不要创建新表单；必须走 update/patch/rule/bind-datasource。
 - 不要用 `GroupContainer` / `PageSection` 承载普通业务分组；普通分组必须优先用 `Divider`
 - 严禁为原生表单或 `formDetail` 生成、注入 CSS、JS、HTML 或主题代码；详情页由平台渲染。
@@ -58,7 +59,57 @@ description: 表单页面创建与更新；支持 19 种业务字段和 Divider
 
 ## 多表单创建
 
-同一轮需要新建两个及以上普通表单时，必须按 [并行创建表单](references/batch-forms.md) 把全部表单写入同一个 `forms.json`，并且只调用一次 `openyida create-form batch <appType> <任务文件> --json`。独立表单和关联表单放在同一任务文件中，依赖通过 `dependsOn` / `$form` 表达，由 CLI 在一次 batch 内部完成分组、真实 `formUuid/fieldId` 回读和依赖调度；不要手工拆成多次 batch，也不要逐个调用 `create-form create`。只有修改已有表单、恢复已有 `formUuid`，或当前 batch 契约无法表达依赖时，才走明确的非 batch 路径并说明原因。
+同一轮需要新建两个及以上普通表单时，必须按 [并行创建表单](references/batch-forms.md) 把全部表单写入同一个 `forms.json`，并且只调用一次 `openyida create-form batch <appType> <任务文件> --json`。独立表单和关联表单放在同一任务文件中，依赖通过 `dependsOn` / `$form` 表达，由 CLI 在一次 batch 内部完成分组、真实 `formUuid/fieldId` 回读和依赖调度；不要手工拆成多次 batch，也不要逐个调用 `create-form create`。调用前先确认 CLI 的实际项目根目录，并让 Write 创建的绝对路径与 Bash 使用的任务文件指向同一个物理文件：常见 `<workspace>/project` 布局中应写入 `<workspace>/project/.cache/openyida/<项目名>/forms.json`，再从该项目根传 `.cache/openyida/<项目名>/forms.json`。先用 Read 确认任务文件存在，不要通过试跑 batch 探测路径。batch 返回 background pending 时等待运行时投递完成结果，不得再次调用 batch。只有修改已有表单、恢复已有 `formUuid`，或当前 batch 契约无法表达依赖时，才走明确的非 batch 路径并说明原因。
+
+主技能内的最小任务文件契约如下，执行普通批量创建无需再查 help、sample 或 CLI 源码：
+
+```json
+{
+  "forms": [
+    { "key": "customer", "title": "客户", "fields": [{ "type": "TextField", "label": "客户名称", "required": true }] },
+    { "key": "contact", "title": "联系人", "fields": [{ "type": "TextField", "label": "联系人姓名", "required": true }] },
+    {
+      "key": "relation",
+      "title": "客户联系人关系",
+      "dependsOn": ["customer", "contact"],
+      "fields": [{
+        "type": "AssociationFormField",
+        "label": "关联客户",
+        "associationForm": {
+          "appType": "APP_XXX",
+          "formUuid": { "$form": "customer" },
+          "formTitle": "客户",
+          "mainFieldId": { "$form": "customer", "field": "客户名称" },
+          "mainFieldLabel": "客户名称",
+          "mainComponentName": "TextField"
+        }
+      }]
+    }
+  ]
+}
+```
+
+`fieldsFile` 也可替代内联 `fields`，其路径相对 `forms.json` 所在目录；已有完整表单可提供 `formUuid` 回读复用。普通搭建的 batch 项必须省略 `icon`，由 CLI 按标题和字段语义自动选择；只有用户明确给出 `openyida create-form icons --json` 目录中的表单图标名时才设置，应用图标 `xian-*` 绝不是表单图标。`locale` 同样只在用户明确指定时设置。普通多表单创建的执行顺序固定为：确认 `projectRoot` → Write 一个任务文件 → Read 确认文件 → 唯一一次真实 batch → 使用 batch 结果和必要的 compact `get-schema` 回读。
+
+最小 `forms.json` 结构如下；`fieldsFile` 相对 `forms.json` 所在目录解析：
+
+```json
+{
+  "forms": [
+    { "key": "customer", "title": "客户", "fieldsFile": "customer-fields.json" },
+    {
+      "key": "order",
+      "title": "订单",
+      "fieldsFile": "order-fields.json",
+      "dependsOn": ["customer"]
+    }
+  ]
+}
+```
+
+关联字段必须把引用放在 `associationForm` 内。推荐使用紧凑写法 `"associationForm": { "$form": "customer", "field": "客户名称" }`；batch 会将其规范化为 `associationForm.formUuid` 和 `associationForm.mainFieldId`。完整写法则分别在 `formUuid` 使用 `{ "$form": "customer" }`、在 `mainFieldId` 使用 `{ "$form": "customer", "field": "客户名称" }`。不要把 `$form` 放在 `AssociationFormField` 顶层，也不要用 `batch --help`、空参数或临时计划探索格式；技能中的结构就是正式契约。
+
+批量命令超过前台时限进入后台属于正常行为。此时必须保留原任务和 `<forms.json>.state.json`，等待运行时自动回传结果；禁止调用 `ToolStop`，禁止删除 `.state.json`/`.lock`，禁止改变参数再次调用 batch。若最终返回 `FORM_BATCH_PARTIAL_FAILURE`，在本轮原样保留结构化错误并停止；禁止模型侧再调用 `create-form create`、`update` 或 `resume` 补洞。CLI 会在同一次 batch 内对已取得真实 `formUuid` 的空壳表单执行一次保守恢复。
 
 ## 官方表单示例范式
 

package/yida-skills/skills/yida-create-form-page/references/batch-forms.md

@@ -6,6 +6,8 @@
 openyida create-form batch <appType> .cache/openyida/<项目名>/forms.json --json
 ```
 
+这条相对路径以 CLI 的实际项目根目录为准。先确认项目根，再让文件工具的写入位置和 Bash 参数落到同一个物理文件；例如项目根是 `<workspace>/project` 时，Write 应创建 `<workspace>/project/.cache/openyida/<项目名>/forms.json`，Bash 从 `<workspace>/project` 执行并传 `.cache/openyida/<项目名>/forms.json`。调用前用 Read 确认文件存在，不要用 batch 试错路径。
+
 ## 任务文件
 
 ```json
@@ -18,7 +20,7 @@ openyida create-form batch <appType> .cache/openyida/<项目名>/forms.json --js
 }
 ```
 
-`fieldsFile` 相对任务文件所在目录，也可使用 `fields` 直接填写字段定义。每项可设置 `icon`、`locale`；已有完整表单填写 `formUuid`，CLI 回读并复用。
+`fieldsFile` 相对任务文件所在目录，也可使用 `fields` 直接填写字段定义。普通 batch 项省略 `icon`，由 CLI 自动选择；只有用户明确给出表单图标目录中的合法名称时才设置，禁止写应用图标 `xian-*`。`locale` 也只在用户明确指定时设置。已有完整表单填写 `formUuid`，CLI 回读并复用。
 
 客户和商品同时创建。订单的前置表单完成后开始创建；其他独立任务继续执行。依赖环、未知依赖、重复 key 和无效字段会在创建前报错。
 
@@ -26,6 +28,18 @@ openyida create-form batch <appType> .cache/openyida/<项目名>/forms.json --js
 
 在字段配置中，用以下对象引用同批次的真实 ID，CLI 自动补入依赖：
 
+紧凑写法（推荐）：
+
+```json
+{
+  "type": "AssociationFormField",
+  "label": "客户",
+  "associationForm": { "$form": "customer", "field": "客户名称" }
+}
+```
+
+batch 会在预校验前把紧凑写法规范化为下面的完整结构；前向依赖只做本地结构校验，不要求目标表单预先存在：
+
 ```json
 {
   "type": "AssociationFormField",
@@ -41,7 +55,7 @@ openyida create-form batch <appType> .cache/openyida/<项目名>/forms.json --js
 }
 ```
 
-`field` 按字段名称或 ID 精确匹配，重名时使用 ID。关联表单完成且字段回读成功后，才解析引用并创建当前表单。普通关联字段属性沿用 [关联表单配置](association-form-field.md)。
+`field` 按字段名称或 ID 精确匹配，重名时使用 ID。关联表单完成且字段回读成功后，才解析引用并创建当前表单。紧凑写法适用于同应用内关联；需要跨应用或更多 `associationForm` 属性时使用完整写法。普通关联字段属性沿用 [关联表单配置](association-form-field.md)。
 
 ## 检查与恢复
 
@@ -49,7 +63,9 @@ openyida create-form batch <appType> .cache/openyida/<项目名>/forms.json --js
 - `--concurrency 1..4` 设置并发上限，默认 3。
 - 结果保存在任务文件旁的 `.state.json`，包含每张表单的 ID、字段和状态。主流程从中汇总资源上下文，再配置导航。
 - 相同任务再次执行时，成功表单回读复用。失败及中断任务保留原状态，其依赖标记为 blocked；独立任务继续。
+- 当前批次返回 `success:false` 时，以返回的 `results`、子命令诊断和 `.state.json` 为准停止本轮创建；不得为补齐失败项改用单条 `create-form create`，也不得把剩余项拆成新的 batch。修正输入或为已知资源补入 `formUuid` 后，后续恢复仍使用原任务文件执行 batch。
 - 恢复失败任务前，核对已创建资源并修复。准备新任务文件时，用 `formUuid` 复用完整表单，仅为确认尚未创建的表单保留创建任务。
 - `.lock` 防止同一任务重复启动。进程异常退出遗留锁时，确认原进程已结束、核对已创建资源后再清理。
+- 首次 batch 返回 background pending 时等待运行时自动投递完成结果；pending 不是失败，也不是重试信号，不得再次调用 batch。
 
 已有表单的字段修改仍使用 update/patch 等命令；不同表单可分别更新，同一张表单由一个任务维护。流程审批按 `yida-create-process` 执行，等待其依赖的表单就绪后再配置。

package/yida-skills/skills/yida-design/references/design-mode.md

@@ -9,6 +9,6 @@
 
 用户同时要求先出计划和少提问时采用 Plan，复用已知信息。用户指定的详细计划作为规划基础，补齐实施所需的缺项。
 
-同一目标、同一次搭建复用已确认方式；切换目标时重新判断。已有应用的局部增改、单页美化和主题调整直接处理本次任务，遇到会改变范围的问题再澄清。
+同一目标、同一次搭建复用已确认方式；该选择在需求澄清、`ask_human` 恢复和 brief 合并中保持粘性，回答未重复提到模式不代表改选。只有用户明确要求改用另一方式时才更新 `intake.designMode`。切换目标时重新判断。已有应用的局部增改、单页美化和主题调整直接处理本次任务，遇到会改变范围的问题再澄清。
 
 两种方式共用业务和视觉契约；Plan 额外展示方案并绑定当前版本确认。面向用户的表达与宿主适配见 [用户交互契约](ask-human-interaction-contract.md)。

package/yida-skills/skills/yida-design/sub_skill/yida-design-plan/references/build-plan-compact-schema.md

@@ -4,6 +4,8 @@
 
 `design-plan init` 从已确认需求建立草稿、主题上下文和业务/视觉片段，返回必要任务与可选视觉精修。标准首版只编写业务事实，视觉片段复用已确认选择，由 CLI 补齐标准页面视觉；视觉选择不完整时返回补齐任务，有特殊视觉要求时执行可选精修。片段写入与合并见 [并行交接](../../../../yida-app/workflow/parallel-work.md#plan-的-cli-交接)。保留生成的项目目录名、页面 ID 与 sceneKey；业务名称使用 `meta.appName`。补齐业务与视觉片段后执行交接命令；直接维护单一计划时使用：
 
+init 已预填 `business.json` 结构，业务任务先读后写并保留 base。业务 facts 仅允许 overview、dataModels、businessFlows、pages、execution；visualStyle 只属于 `visual.json`。首次合并前一次补齐每个普通表单的 sampleDataPlan（跳过则写 skipReason）和每个自定义页面的 permissionSummary，避免用多轮 materialize 探测必填字段。
+
 ```bash
 openyida design-plan materialize prd/<项目名>/build-plan.json --json
 ```
@@ -108,7 +110,7 @@ CLI 校验源事实，使用预置模板整批生成 `prd.md`、`design.md` 和
 | 字段 | 格式 |
 | --- | --- |
 | `appConfig` | 已知真实 `appType/corpId/baseUrl`；`navigationType` 为 platform-l-shape/platform-top/platform-side/custom。hideAppNav/layoutDirection/navTheme/logoSource 由导航与视觉派生 |
-| `explicitScope` | 用户明确的页面、表单、流程和导航范围；自定义导航布局保留在 navigation.variant |
+| `explicitScope` | 用户明确的页面、表单、流程、报表、导航和交付范围；`allowInferredResources=false` 时不增加未点名的 seed records、自定义页面、主题或导航任务；自定义导航布局保留在 navigation.variant |
 | `resourceBlueprint` | `{name,type,purpose,pageId?}` 数组；type 为 normal-form/process-form/display-page/report，名称与模型、页面对应且唯一 |
 | `resourceCreationOrder` | 覆盖全部资源的有序名称数组，先应用，再被依赖模型，最后依赖它们的页面 |
 | `pageImplementationOrder` | 覆盖全部页面的 pageId 或名称数组 |

package/yida-skills/skills/yida-prd/workflow/plan-business.md

@@ -4,9 +4,11 @@
 
 1. 按“业务目标 → 对象与字段 → 流程与规则 → 用户任务 → 页面”规划。字段、关系、规则、权限和已确认页面范围保留完整。
 2. 维护 overview、dataModels、businessFlows、pages 和业务 execution。导航沿用需求选择；资源按依赖排列，页面任务、数据来源、主操作和验收要求明确。
-3. 标准首版一次完成全部业务 facts 并写入 init 返回的 `business.json`；视觉选择已由 CLI 预填，不等待另一个模型任务。只有命中品牌稿、参考图、页面级特殊视觉或用户明确要求精修时，才将页面任务、区块与 sceneKey 交给可选视觉任务。超大需求需要中间展示时才按 [按模块更新方案](../../yida-app/workflow/incremental-preview.md) 提交；普通首版使用 [完整文件合并](../../yida-app/workflow/parallel-work.md#plan-的-cli-交接)。
+3. init 已创建并预填 `business.json` 骨架。先读取它，保留 base；facts **只能**包含 overview、dataModels、businessFlows、pages 和可选 execution，禁止写 visualStyle。一次补齐全部业务事实并将 ready 设为 true：每个普通表单都有 sampleDataPlan（窄范围不造数写 skipReason），每个自定义页面都有非空 permissionSummary。视觉选择已由 CLI 预填，不等待另一个模型任务。只有命中品牌稿、参考图、页面级特殊视觉或用户明确要求精修时，才将页面任务、区块与 sceneKey 交给可选视觉任务。超大需求需要中间展示时才按 [按模块更新方案](../../yida-app/workflow/incremental-preview.md) 提交；普通首版使用 [完整文件合并](../../yida-app/workflow/parallel-work.md#plan-的-cli-交接)。
 4. CLI 生成完整 PRD 与交接，模板规则、摘要副本和默认设计引用由 CLI 补齐。校验问题按字段路径集中修正。
 
 首版只写紧凑契约要求的业务事实和用户指定的差异，不重复写 CLI 可派生的概要、资源顺序副本、通用交互状态与默认验收文案。普通表单先提供 1 条覆盖必填字段的有效示例记录；用户要求多条或业务验收确有需要时再增加。不要先生成完整 PRD Markdown，再将相同内容改写为 JSON。
 
+`explicitScope.allowInferredResources=false` 时只规划点名资源：不增加自定义工作台、列表页、seed records、主题设置或导航任务；普通表单的 sampleDataPlan 用 skipReason 明确“本轮窄范围不造数”。
+
 页面模式选项由 CLI 返回的 authoring-context 提供。遇到复杂跨页流程或特殊资源时，再按需读取 [业务内容检查](../references/plan-content.md) 与 [统一 PRD 格式](output-prd.md)。

package/yida-skills/skills/yida-requirement-analysis/SKILL.md

@@ -25,16 +25,16 @@ description: 识别并读取需求来源，理解和澄清用户需求，输出
 | `projectName` | 稳定的项目目录名 |
 | `appName` | 用户可见的应用名称候选 |
 | `industry` / `appType` | 业务领域和应用类型 |
-| `targetUsers` | 核心角色和使用场景 |
-| `businessGoals` | 要解决的问题和成功结果 |
-| `coreFunctions` | 核心功能与必要辅助功能 |
-| `businessObjects` | 客户、订单、项目、工单等核心对象 |
-| `pageScenes` | 已确认的页面与表单范围，记录稳定 key、name、kind、purpose 及已有细项 |
+| `targetUsers` | 核心角色和使用场景，字符串数组 |
+| `businessGoals` | 要解决的问题和成功结果，字符串数组；只有一个目标也写数组 |
+| `coreFunctions` | 核心功能与必要辅助功能，数组 |
+| `businessObjects` | 客户、订单、项目、工单等核心对象，数组 |
+| `pageScenes` | 已确认的页面与表单范围，数组；记录稳定 key、name、kind、purpose 及已有细项 |
 | `intake` | 首次搭建判断、来源详细程度、搭建方式和需求确认状态 |
-| `visualSelection` | 已确认风格及其主题、主色、导航明暗映射 |
-| `navigation` | 应用导航决策：`type`、`source`、`reason`，自定义导航增加 `variant`；类型遵守四类导航契约，未决时 type 为 null，规划前补齐 |
+| `visualSelection` | 已确认风格及其主题、主色、导航明暗映射；Plan 初始化前必须含非空 `themeId` |
+| `navigation` | 应用导航决策：`type` 只能是 `platform-l-shape/platform-top/platform-side/custom`，并记录 `source/reason`；自定义导航增加 `variant: side/top/mixed/dock`；未决时 type 为 null，规划前补齐 |
 | `resourceContext` | 已确认可复用的 app/page/form/process 业务上下文，不写猜测 ID |
-| `explicitScope` | 用户明确指定的页面、表单、流程、报表、导航项和本轮范围；没有时为 `null` |
+| `explicitScope` | 用户明确指定的页面、表单、流程、报表、导航项和本轮交付；明确窄范围时写对应数组及 `allowInferredResources:false`，没有时为 `null` |
 | `brandHints` / `colorHints` | 明确的品牌、参考页面、已有主题、偏好色与避用色 |
 | `constraints` | 组织、设备、权限、交付等约束；用户明确禁止的动作原文写入 `prohibitedActions`，作为后续写操作硬门禁 |
 | `assumptions` / `openQuestions` | 可安全默认的事项与会改变范围的未决问题 |
@@ -43,6 +43,7 @@ description: 识别并读取需求来源，理解和澄清用户需求，输出
 
 - brief 必须可解析，已知的项目名、目标、用户、对象、功能、场景及范围准确且无遗漏；不为填满字段补造需求。会改变资源范围、权限或业务对象的问题写入 `openQuestions`，由编排组织确认后再进入规划；不影响范围的待设计细节由 PRD 或视觉设计补齐。
 - 用户指定的资源和范围原样保留在 `explicitScope`；真实 ID 有证据时写入 `resourceContext`。
+- 用户用“应用/系统”描述背景、又明确要求本轮只完成某个表单、流程、报表或页面并交付链接时，后者是执行边界：`explicitScope` 只记录该资源与交付，设置 `allowInferredResources:false`，不得推导示例数据、自定义工作台或其他页面。
 - “不复制/不上传主题”“不修改页面源码”“不发布”等负向要求不得改写成偏好或建议；保留原文，并分别规范化为 `theme-file`、`page-source`、`publish` 等 `constraints.prohibitedActions`。明确的禁止项不因 Fast/Plan 默认流程而失效。
 - 需求文件校验通过后保持不变。后续创建出的真实 ID 写入 schema 或当前任务资源上下文。
 - 用户需求或已确认范围实质变化时，由本技能更新 brief，并交给 `yida-app` 同步业务与视觉规划。

package/yida-skills/skills/yida-requirement-analysis/workflow/prepare-brief.md

@@ -10,10 +10,14 @@
 
 首次搭建包括新应用，以及已有应用但尚无业务页面的情况；占位页面按空应用处理。已有业务应用的增改只确认本次变更中的疑问。
 
+用户已把本轮限定为一个或若干命名资源且交付条件明确时，这是“显式窄范围”，不是完整首次搭建问卷：只追问会改变这些资源本身或阻塞创建的事实。导航、主题、示例数据、工作台和额外页面不在交付范围时，不询问其偏好；为满足 Plan 输入可记录当前平台值或稳定默认值并标记 `source: "ai_default"`，但下游不得据此执行应用设置。用户已明确 Plan 时也不再询问搭建方式。此类请求中的 Plan 确认卡就是唯一必需的方案确认交互。特别是“随后完成一个表单并交付链接”只允许把该表单写入 `explicitScope.forms/delivery`，`explicitScope.pages` 必须为 `[]`，不得根据“查看、管理、统计”等普通表单能力臆造工作台或自定义列表。
+
 ## 2. 确认首次搭建的未决事项
 
 先分析再提问。用户已明确的信息直接采用；同一次搭建已回答的问题直接复用。首次提问必须在同一轮一次性收集所有尚未明确的搭建方式（Fast / Plan）、业务模块、页面与表单范围、导航归属（平台或自定义）、导航布局和设计风格。不要先问模块、导航和风格，收到回答后再另起一轮补问模式、导航位置或页面。
 
+先锁定用户已经明确的搭建方式：用户写明 `Plan`、先出 PRD/方案并确认后搭建时，立即把草稿的 `intake.designMode` 设为 `plan`；用户写明 `Fast` 或直接快速搭建时设为 `fast`。已锁定的搭建方式不再进入提问选项。后续 `ask_human` 只补齐其他未决事项，合并回答时必须保留已有 `intake.designMode`；不能因为回答里没有重复提到模式、结构化问题被合并、上下文压缩或重新生成 brief 而回退到 Fast。只有用户明确说“改用 Fast/Plan”时才能切换，并以最后一次明确选择为准。
+
 将整组问题放在一次结构化提问调用中。宿主限制问题数量时，合并为“搭建方式”“导航归属与布局”“业务模块、页面与风格”等复合问题；选项数量或多选能力不足时，用允许自由输入的同组问题列出完整选择。不得因为工具数量限制而拆成多轮。只有回答遗漏、互相冲突或产生新的关键业务疑问时才针对性追问。
 
 | 事项 | 何时询问 | 用户可见问题与选项 |
@@ -48,9 +52,12 @@
 
 写入 `.cache/openyida/<项目名>/requirement-brief.json`，遵守 [输出契约](../SKILL.md#输出)。
 
+`Write` 会创建所需父目录；不要为此先调用 Bash `mkdir`。
+
 本步骤是保存答案，不是重新撰写需求文档：
 
 - 合并已读取的需求、资源信息和本轮回答，完成必要确认后一次写入；中断恢复可保存未确认草稿，但不得把草稿当作已确认输入。
+- 合并采用保留式更新：未被本轮提问的已确认字段不得用默认值覆盖。尤其 `intake.designMode` 是同一次搭建的粘性选择；若本轮没有询问搭建方式，写回值必须与提问前一致。
 - 简短需求使用简短事实、列表和必要的页面标识，不扩写背景、价值分析、完整字段表、页面区块或验收标准；这些设计工作由后续 PRD 与视觉设计负责。用户已提供的字段、关系、流程和页面细项必须保留，不为精简而丢弃，也不重复改写成多份摘要。
 - 不另建 `brief.md`、简报 HTML 或简报附件，不为保存 JSON 单独安排一次模型扩写或用户确认。用户回答清楚后直接记录，不能再展示整份简报询问“是否确认需求”。
 - 已有确认记录且需求未变化时直接复用；后续只补充已确定的视觉映射或更新用户变更涉及的字段，不因阶段切换重写全文或重新生成页面 key。
@@ -58,11 +65,26 @@
 - `intake` 记录 `firstBuild`、`sourceDetail`（`detailed/brief`）、`designMode`（`fast/plan`）、`confirmed`。未决事项处理完毕后才将 confirmed 设为 true。
 - `navigation` 记录 `type/source/reason`；自定义导航的 `variant` 为 `side/top/mixed/dock`。顶部浮导使用 `top`，默认浮导或用户指定的通栏样式写入 `reason`，PRD 与视觉设计共同沿用；`dock` 表示底部悬浮胶囊。导航明暗由视觉选择记录。
 - 业务模块答案写入 `coreFunctions/businessObjects/explicitScope`；与页面范围合问时，分别保存模块事实与 `pageScenes`，不要只保留模块或页面数量。
+- `targetUsers/businessGoals/coreFunctions/businessObjects/pageScenes` 一律保持数组类型；单个目标也写成单元素数组。Plan 的 `visualSelection.themeId` 在保存 confirmed brief 前补齐；导航 type 使用 `platform-l-shape/platform-top/platform-side/custom` 精确枚举。
+- 用户先用“应用/系统”描述背景、后续又明确“只完成/随后完成一个”具体资源并交付时，以具体资源作为本轮执行边界。`explicitScope` 写对应的 forms/processes/reports/pages/delivery 数组并设置 `allowInferredResources:false`；不把“应用”自动扩展为示例数据、工作台、自定义列表或其他未点名资源。
 - `pageScenes` 使用 `{key,name,kind,purpose}`，key 是稳定场景标识，kind 为 `custom-page/form/process-form/report`。保留用户提供的细项；工作台通常排在首位。
 - `visualSelection` 保存已确认的风格要求；视觉技能将其映射为主题、主色和导航明暗，具体字段见计划编写契约。
 - `resourceContext` 记录已验证的复用资源，`explicitScope` 保留明确范围；来源中的完整业务细节保留在对应事实中。
 - `constraints.prohibitedActions` 贯穿 PRD、design 与实现，不得在下游被“默认主题”“默认发布”或“修复后重试”覆盖。
 
-全部必要回答写回后，直接进入已选 Fast / Plan 的规划流程；Plan 仍在方案生成后确认当前搭建方案。内部只检查 JSON 可解析、已确认选择完整、页面 key 唯一且稳定、没有影响搭建的未决问题，不另起简报评审。交互工具与面向用户的文案遵守 [用户交互契约](../../yida-design/references/ask-human-interaction-contract.md)。
+Plan 的视觉选择直接使用下面的对象结构，不另写 `styleDescription/primaryColor/navigationStyle` 等平级别名：
+
+```json
+{
+  "themeId": "airy-structured-clarity",
+  "visualDirection": {"label": "轻盈结构", "description": "清晰、简洁、适合持续业务操作", "source": "requirement"},
+  "colorStrategy": {"primaryColor": "#1677FF", "primaryColorName": "专业蓝", "source": "requirement", "usage": "主操作与选中态", "surfaceTone": "brand-tinted"},
+  "navigationStyle": {"structure": "side", "tone": "light", "source": "requirement", "selectionReason": "沿用平台侧边导航"}
+}
+```
+
+用户未指定色值但允许代为设计时，可按所选主题给出一个明确色值并标记 `source: "ai_default"`；不要留到 `design-plan init` 失败后再选择。
+
+全部必要回答写回后，直接进入已选 Fast / Plan 的规划流程；进入路由前再次核对 `intake.designMode` 与本轮最后一次明确选择一致。Plan 仍在方案生成后确认当前搭建方案。内部只检查 JSON 可解析、已确认选择完整、页面 key 唯一且稳定、没有影响搭建的未决问题，不另起简报评审。交互工具与面向用户的文案遵守 [用户交互契约](../../yida-design/references/ask-human-interaction-contract.md)。
 
 后续创建的资源 ID 写入执行上下文；用户需求发生变化时更新同一份 brief，并通知下游修改受影响的内容。