openyida 2026.9.11 → 2026.9.13

package/lib/asset/asset-cmd.js

@@ -1,82 +1,104 @@
-
-/**
- * asset-cmd.js - `openyida asset` 素材能力命令
- *
- * 素材工具的统一入口，把「检测素材能力 / 解析回填 / 素材来源引导」
- * 暴露为可脚本化命令，供本地智能体在生成官网/落地页前调用，
- * 从而做到：无 CDN 不谎称已上传、无可用素材不交付「最终版」。
- *
- * 子命令：
- *   status                     检测当前素材能力（CDN / 生成 / 推荐策略）
- *   resolve --hero <..> [--product <..>] [--upload-assets]  解析并回填一组素材，输出 materialStatus/缺口
- *   generate                   输出素材来源引导（免费素材库清单 + 纪律）
- *
- * 所有子命令均支持 --json 便于智能体解析。
- */
-
 'use strict';
 
+const fs = require('fs');
+const path = require('path');
+const { readDesignAssetStrategy } = require('./asset-plan');
 const { getAssetStatus } = require('./asset-status');
-const { resolveAssets } = require('./asset-resolve');
-const {
-  detectImageGenerator,
-  getMaterialSourcingGuidance,
-} = require('./ai-image');
-const { throwCommandError, throwStatus } = require('../core/command-errors');
+const { resolveAssets, ASSET_SOURCES } = require('./asset-resolve');
+const { detectImageGenerator, getMaterialSourcingGuidance } = require('./ai-image');
+const { throwCommandError, throwStatus, throwUsage } = require('../core/command-errors');
+
+const RESOLVE_USAGE = '用法: openyida asset resolve (--input <manifest-draft.json> | --slot <slotId>=<路径或URL> ...) [--manifest <asset-manifest.json>] [--design <design.md>] [--source search|user|generated] [--app-type <appType>] [--upload-assets] [--offline] [--json]';
 
 function printHelp() {
   console.log(`
 用法:
   openyida asset status [--offline] [--json]
-  openyida asset resolve --hero <路径或URL> [--product <路径或URL> ...] [--require-hero] [--upload-assets] [--offline] [--json]
-  openyida asset generate [--json]
+  openyida asset resolve (--input <manifest-draft.json> | --slot <slotId>=<路径或URL> ...) [--manifest <asset-manifest.json>] [--design <design.md>] [--source search|user|generated] [--app-type <appType>] [--upload-assets] [--offline] [--json]
+  openyida asset sources [--json]
 
 子命令:
-  status       检测当前素材能力：是否配置 CDN、是否可生成、推荐素材策略
-  resolve      把本地/外链素材解析为稳定 URL 并回填，输出 materialStatus(final|draft|none) 与缺口
-  generate     输出素材来源引导（免费可商用素材库清单 + 使用纪律，供智能体检索真实图片）
+  status    检测素材能力
+  resolve   校验图片、默认上传宜搭图片附件并生成清单
 
-说明:
-  openyida 无内置文生图能力；图片应由智能体自行生成或到免费素材库检索，
-  再通过 resolve 解析，并在配置 CDN 时转存后回填 spec。
+图片不超过 20 MiB 时上传；超过限制的外链保留原地址。
+--app-type 指定目标应用，省略时读取项目 config.json。
+--upload-assets 仅兼容旧命令，默认已上传；--offline 不联网、不上传。
+  sources   输出 Unsplash/Pexels 使用规则
 `);
 }
 
+function parseSlot(value) {
+  const index = String(value || '').indexOf('=');
+  if (index <= 0 || index === String(value).length - 1) {return null;}
+  const slotId = String(value).slice(0, index).trim();
+  const input = String(value).slice(index + 1).trim();
+  if (!slotId || !input) {return null;}
+  return {
+    slotId,
+    input,
+    required: true,
+  };
+}
+
 function parseArgs(args) {
   const parsed = {
     subCommand: args[0],
-    hero: '',
-    products: [],
-    requireHero: false,
+    slots: [],
+    input: '',
+    manifest: '',
+    design: '',
     offline: false,
     uploadAssets: false,
+    appType: '',
+    source: 'search',
     timeout: 0,
     json: false,
     help: false,
+    errors: [],
+    usedOptions: [],
   };
-
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
     if (arg === '--help' || arg === '-h') {
       parsed.help = true;
     } else if (arg === '--json') {
+      parsed.usedOptions.push('--json');
       parsed.json = true;
     } else if (arg === '--offline') {
+      parsed.usedOptions.push('--offline');
       parsed.offline = true;
-    } else if (arg === '--require-hero') {
-      parsed.requireHero = true;
-    } else if (arg === '--upload-assets' || arg === '--mirror-external') {
+    } else if (arg === '--app-type') {
+      parsed.usedOptions.push('--app-type');
+      parsed.appType = args[++i] || '';
+      if (!parsed.appType || parsed.appType.startsWith('--')) {parsed.errors.push('ASSET_APP_TYPE_REQUIRED');}
+    } else if (arg === '--upload-assets') {
+      parsed.usedOptions.push('--upload-assets');
       parsed.uploadAssets = true;
-    } else if (arg === '--hero') {
-      parsed.hero = args[++i] || '';
-    } else if (arg === '--product') {
-      const v = args[++i];
-      if (v) {parsed.products.push(v);}
+    } else if (arg === '--source') {
+      parsed.usedOptions.push('--source');
+      parsed.source = args[++i] || '';
+    } else if (arg === '--input') {
+      parsed.usedOptions.push('--input');
+      parsed.input = args[++i] || '';
+    } else if (arg === '--design') {
+      parsed.usedOptions.push('--design');
+      parsed.design = args[++i] || '';
+      if (!parsed.design || parsed.design.startsWith('--')) {parsed.errors.push('ASSET_DESIGN_REQUIRED');}
+    } else if (arg === '--manifest') {
+      parsed.usedOptions.push('--manifest');
+      parsed.manifest = args[++i] || '';
+    } else if (arg === '--slot') {
+      parsed.usedOptions.push('--slot');
+      const slot = parseSlot(args[++i]);
+      if (slot) {parsed.slots.push(slot);} else {parsed.errors.push('--slot 格式应为 <slotId>=<路径或URL>');}
     } else if (arg === '--timeout') {
+      parsed.usedOptions.push('--timeout');
       parsed.timeout = parseInt(args[++i], 10) || 0;
+    } else {
+      parsed.errors.push(`未知参数：${arg}`);
     }
   }
-
   return parsed;
 }
 
@@ -87,74 +109,88 @@ function runStatus(options) {
     return;
   }
   console.log('素材能力检测');
-  console.log('  CDN 已配置    : ' + (status.cdnConfigured ? '是' : '否'));
-  console.log('  可上传转存    : ' + (status.canUpload ? '是' : '否'));
-  console.log('  可 AI 生成    : ' + (status.canGenerate ? '是' : '否（由智能体生成/检索素材）'));
-  console.log('  推荐素材策略  : ' + status.recommendedStrategy);
-  console.log('  CDN 配置文件  : ' + status.cdn.configPath);
-  if (status.cdn.missing.length) {
-    console.log('  缺失 CDN 字段 : ' + status.cdn.missing.join(', '));
+  console.log('  上传目标   : 宜搭图片附件（需要登录态和 appType）');
+  console.log('  上传条件   : ' + (status.canUpload ? '联网已启用；实际上传时验证登录态和应用权限' : '离线，不上传'));
+  console.log('  可生成图片 : ' + (status.canGenerate === true ? '是' : status.canGenerate === false ? '否' : '未确认'));
+  console.log('  建议策略   : ' + status.recommendedStrategy);
+  status.reasons.forEach(reason => console.log('  - ' + reason));
+}
+
+function readDraft(filePath) {
+  let draft;
+  try {
+    draft = JSON.parse(fs.readFileSync(path.resolve(filePath), 'utf8'));
+  } catch (error) {
+    throwCommandError(`无法读取素材草稿：${error.message}`, { code: 'ASSET_INPUT_INVALID' });
   }
-  console.log('原因/建议:');
-  status.reasons.forEach((r) => console.log('  - ' + r));
+  if (!draft || !Array.isArray(draft.assets)) {
+    throwCommandError('素材草稿必须包含 assets 数组', { code: 'ASSET_INPUT_INVALID' });
+  }
+  return draft;
+}
+
+function writeManifest(filePath, manifest) {
+  const target = path.resolve(filePath);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+  return target;
 }
 
 async function runResolve(options) {
-  const assets = {
-    heroImage: options.hero,
-    productImages: options.products,
-  };
+  if (options.errors.length > 0) {
+    throwUsage(options.errors.join('\n'), RESOLVE_USAGE, { code: 'ASSET_INVALID_ARGUMENTS' });
+  }
+  if (options.input && options.slots.length > 0) {
+    throwUsage('--input 与 --slot 不能同时使用', RESOLVE_USAGE, { code: 'ASSET_INPUT_CONFLICT' });
+  }
+  if (!ASSET_SOURCES.includes(options.source)) {
+    throwUsage('--source 仅支持 search、user 或 generated', RESOLVE_USAGE, { code: 'ASSET_INVALID_SOURCE' });
+  }
+  const draft = options.input ? readDraft(options.input) : {};
+  const assetStrategy = options.design ? readDesignAssetStrategy(path.resolve(options.design)) : draft.assetStrategy;
+  const assets = [
+    ...(draft.assets || []),
+    ...options.slots.map(slot => ({ ...slot, source: options.source })),
+  ];
+  if (assets.length === 0 && !options.input) {
+    throwUsage('至少提供一个 --slot 或 --input', RESOLVE_USAGE, { code: 'ASSET_INPUT_REQUIRED' });
+  }
+
   const result = await resolveAssets(assets, {
-    requireHero: options.requireHero,
+    assetStrategy,
     online: !options.offline,
-    mirrorExternal: !!options.uploadAssets,
+    appType: options.appType,
+    assetSource: options.source,
     timeout: options.timeout || undefined,
   });
-  if (options.json) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-  console.log('素材解析结果');
-  console.log('  materialStatus : ' + result.materialStatus +
-    (result.materialStatus === 'final' ? '（可交付最终版）'
-      : result.materialStatus === 'draft' ? '（仅可交付标注缺口的草稿）'
-        : '（无可用素材，只能低保真草稿）'));
-  console.log('  strategy       : ' + result.strategy);
-  console.log('  Hero           : ' + (result.assets.heroImage || '(无)'));
-  console.log('  产品图         : ' + (result.assets.productImages.length
-    ? result.assets.productImages.join(', ') : '(无)'));
-  if (result.materialGaps.length) {
-    console.log('素材缺口:');
-    result.materialGaps.forEach((g) => console.log('  - ' + g));
-  }
-  // 非 final 时以非零退出码提示调用方（生成链路可据此拦截「最终版」）
-  if (result.materialStatus !== 'final') {
+  const manifestPath = options.manifest ? writeManifest(options.manifest, result) : '';
+  if (result.materialStatus === 'draft') {
     throwStatus('素材未达到 final 状态', 2, {
       code: 'ASSET_MATERIAL_NOT_FINAL',
-      details: result,
+      details: { ...result, manifestPath },
     });
   }
+  if (options.json) {
+    console.log(JSON.stringify({ ...result, manifestPath }, null, 2));
+    return;
+  }
+  console.log('素材状态: ' + result.materialStatus);
+  console.log('素材数量: ' + result.assets.length);
+  if (manifestPath) {console.log('素材清单: ' + manifestPath);}
 }
 
-function runGenerate(options) {
-  const generator = detectImageGenerator();
-  const guidance = getMaterialSourcingGuidance();
+function runSources(options) {
+  const status = getAssetStatus();
+  const output = {
+    generator: detectImageGenerator({ hostCapabilities: status.hostCapabilities }),
+    guidance: getMaterialSourcingGuidance(),
+  };
   if (options.json) {
-    console.log(JSON.stringify({ generator, guidance }, null, 2));
+    console.log(JSON.stringify(output, null, 2));
     return;
   }
-  console.log('图片生成能力: ' + (generator.available ? '可用' : '不可用'));
-  console.log('  ' + generator.reason);
-  console.log('\n素材来源步骤:');
-  guidance.steps.forEach((s) => console.log('  ' + s));
-  console.log('\n免费可商用素材库:');
-  guidance.libraries.forEach((lib) => {
-    console.log('  · ' + lib.name + ' (' + lib.site + ')');
-    console.log('    授权: ' + lib.license);
-    console.log('    适合: ' + lib.bestFor);
-  });
-  console.log('\n纪律:');
-  guidance.rules.forEach((r) => console.log('  - ' + r));
+  console.log('图片来源: 用户素材、Unsplash、Pexels 或宿主生成');
+  output.guidance.rules.forEach(rule => console.log('  - ' + rule));
 }
 
 async function run(args) {
@@ -163,22 +199,27 @@ async function run(args) {
     printHelp();
     return;
   }
-  switch (options.subCommand) {
-    case 'status':
-      runStatus(options);
-      break;
-    case 'resolve':
-      await runResolve(options);
-      break;
-    case 'generate':
-      runGenerate(options);
-      break;
-    default:
-      printHelp();
-      throwCommandError('未知子命令: ' + options.subCommand, {
-        code: 'ASSET_UNKNOWN_SUBCOMMAND',
-      });
+  const allowedOptions = {
+    status: new Set(['--offline', '--json']),
+    sources: new Set(['--json']),
+  };
+  if (allowedOptions[options.subCommand]) {
+    const invalid = options.usedOptions.filter(option => !allowedOptions[options.subCommand].has(option));
+    const errors = [...options.errors, ...invalid.map(option => `参数不适用于 ${options.subCommand}：${option}`)];
+    if (errors.length > 0) {
+      throwCommandError(errors.join('\n'), { code: 'ASSET_INVALID_ARGUMENTS' });
+    }
   }
+  if (options.subCommand === 'status') {runStatus(options); return;}
+  if (options.subCommand === 'resolve') {await runResolve(options); return;}
+  if (options.subCommand === 'sources') {runSources(options); return;}
+  throwCommandError(`未知子命令：${options.subCommand}`, { code: 'ASSET_UNKNOWN_SUBCOMMAND' });
 }
 
-module.exports = { run, parseArgs };
+module.exports = {
+  run,
+  parseArgs,
+  parseSlot,
+  readDraft,
+  writeManifest,
+};

package/lib/asset/asset-plan.js

@@ -0,0 +1,105 @@
+'use strict';
+
+const fs = require('fs');
+const { CliError } = require('../core/cli-error');
+
+function invalid(code, details = {}) {
+  throw new CliError(code, { code, details });
+}
+
+function object(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function nonempty(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function minimumSize(asset) {
+  const match = typeof asset.minSize === 'string' && asset.minSize.match(/^(\d+)x(\d+)$/i);
+  if (asset.minSize !== undefined && !match) {
+    invalid('ASSET_INVALID_SIZE', { slotId: asset.slotId, minSize: asset.minSize });
+  }
+  const values = [asset.minWidth ?? 0, asset.minHeight ?? 0];
+  const declared = match ? [Number(match[1]), Number(match[2])] : [0, 0];
+  if ([...values, ...declared].some(value => !Number.isSafeInteger(value) || value < 0) || (match && declared.some(value => !value))) {
+    invalid('ASSET_INVALID_SIZE', { slotId: asset.slotId });
+  }
+  return { minWidth: Math.max(values[0], declared[0]), minHeight: Math.max(values[1], declared[1]) };
+}
+
+function readDesignAssetStrategy(file) {
+  let markdown;
+  try { markdown = fs.readFileSync(file, 'utf8'); } catch (error) {
+    invalid('ASSET_DESIGN_INVALID', { file, reason: error.message });
+  }
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(markdown);
+  const lines = frontmatter ? frontmatter[1].split(/\r?\n/).filter(line => /^assetStrategy:/.test(line)) : [];
+  if (lines.length !== 1) {invalid('ASSET_DESIGN_INVALID', { file, field: 'assetStrategy', format: 'single-line JSON in frontmatter' });}
+  try { return JSON.parse(lines[0].slice('assetStrategy:'.length).trim()); } catch {
+    invalid('ASSET_DESIGN_INVALID', { file, field: 'assetStrategy', format: 'single-line JSON in frontmatter' });
+  }
+}
+
+// The design owns page membership, required slots and minimum dimensions.
+function prepareAssetPlan(assets, assetStrategy) {
+  if (!Array.isArray(assets)) {invalid('ASSET_INPUT_INVALID', { field: 'assets' });}
+  const seen = new Set();
+  const entries = assets.map(asset => {
+    if (!object(asset) || !nonempty(asset.slotId)) {invalid('ASSET_INPUT_INVALID', { field: 'assets[].slotId' });}
+    const slotId = asset.slotId.trim();
+    if (seen.has(slotId)) {invalid('ASSET_DUPLICATE_SLOT', { slotId });}
+    seen.add(slotId);
+    minimumSize(asset);
+    return { ...asset, slotId };
+  });
+  if (assetStrategy === undefined) {return { entries, pages: [], assetStrategy: undefined };}
+  if (!object(assetStrategy) || !Array.isArray(assetStrategy.pages)) {
+    invalid('ASSET_DESIGN_INVALID', { field: 'assetStrategy.pages' });
+  }
+  const pageIds = new Set();
+  const slots = new Map();
+  const pages = assetStrategy.pages.map(page => {
+    if (!object(page) || !nonempty(page.pageId) || !['required', 'beneficial', 'none'].includes(page.imageNeed) || !Array.isArray(page.slots)) {
+      invalid('ASSET_DESIGN_INVALID', { field: 'assetStrategy.pages[]' });
+    }
+    const pageId = page.pageId.trim();
+    if (pageIds.has(pageId)) {invalid('ASSET_DUPLICATE_PAGE', { pageId });}
+    pageIds.add(pageId);
+    if (page.imageNeed === 'none' && page.slots.length) {invalid('ASSET_DESIGN_INVALID', { pageId, field: 'slots' });}
+    const slotIds = [];
+    page.slots.forEach(slot => {
+      if (!object(slot) || !nonempty(slot.slotId) || !nonempty(slot.usage)) {
+        invalid('ASSET_DESIGN_INVALID', { pageId, field: 'slots[].slotId/usage' });
+      }
+      const count = slot.count ?? 1;
+      if (!Number.isInteger(count) || count < 1 || count > 100) {invalid('ASSET_DESIGN_INVALID', { pageId, slotId: slot.slotId, field: 'count' });}
+      minimumSize(slot);
+      for (let index = 0; index < count; index++) {
+        const slotId = count === 1 ? slot.slotId.trim() : `${slot.slotId.trim()}[${index}]`;
+        if (slots.has(slotId)) {invalid('ASSET_DUPLICATE_SLOT', { slotId });}
+        slots.set(slotId, { ...slot, slotId, pageId, required: slot.required !== false });
+        slotIds.push(slotId);
+      }
+    });
+    return { pageId, imageNeed: page.imageNeed, slotIds };
+  });
+  for (const entry of entries) {
+    if (!slots.has(entry.slotId)) {invalid('ASSET_UNDECLARED_SLOT', { slotId: entry.slotId });}
+  }
+  const byId = new Map(entries.map(entry => [entry.slotId, entry]));
+  const planned = [...slots.values()].map(slot => {
+    const entry = byId.get(slot.slotId) || {};
+    const designSize = minimumSize(slot);
+    const inputSize = minimumSize(entry);
+    return {
+      ...entry,
+      ...slot,
+      minWidth: Math.max(designSize.minWidth, inputSize.minWidth),
+      minHeight: Math.max(designSize.minHeight, inputSize.minHeight),
+    };
+  });
+  return { entries: planned, pages, assetStrategy };
+}
+
+module.exports = { minimumSize, prepareAssetPlan, readDesignAssetStrategy };