@seeed-studio/solution-cli 0.3.2 → 0.4.1

package/lib/knowledge.js

@@ -5,6 +5,7 @@ import https from 'node:https';
 import http from 'node:http';
 import { createCatalogDto } from './catalog-dto.js';
 import { assertCompatibility, COMPATIBILITY_STATUS } from './compatibility.js';
+import { getIntegrationContract } from './integration.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -122,6 +123,623 @@ export function loadClientConfig() {
   return null;
 }
 
+const SUPPORTED_LOCALES = new Set(['en', 'zh', 'ja']);
+const HUB_TYPES = new Set(['scenario', 'tech', 'reference_design']);
+const HUB_SECTIONS = new Set(['overview', 'links', 'description', 'architecture', 'products', 'deployment', 'playbook', 'integration']);
+
+function levenshteinDistance(s1, s2) {
+  const m = s1.length;
+  const n = s2.length;
+  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = s1[i - 1] === s2[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + cost
+      );
+    }
+  }
+  return dp[m][n];
+}
+
+export function findClosestSection(received, allowed = Array.from(HUB_SECTIONS)) {
+  const norm = String(received || '').toLowerCase().trim();
+  if (!norm) return null;
+
+  // 1. Prefix match (e.g. "arch" -> "architecture", "integrations" -> "integration")
+  const prefixMatch = allowed.find(s => s.startsWith(norm) || norm.startsWith(s));
+  if (prefixMatch) return prefixMatch;
+
+  // 2. Substring match
+  const substringMatch = allowed.find(s => s.includes(norm) || norm.includes(s));
+  if (substringMatch) return substringMatch;
+
+  // 3. Levenshtein edit distance
+  let best = null;
+  let minDistance = Infinity;
+  for (const s of allowed) {
+    const dist = levenshteinDistance(norm, s);
+    if (dist < minDistance) {
+      minDistance = dist;
+      best = s;
+    }
+  }
+  if (minDistance <= 3) {
+    return best;
+  }
+  return null;
+}
+
+export class HubSectionError extends Error {
+  constructor(section, allowed = Array.from(HUB_SECTIONS)) {
+    const suggestion = findClosestSection(section, allowed);
+    const msg = `Unsupported hub section "${section}". Supported: ${allowed.join(', ')}.${suggestion ? ` Did you mean "${suggestion}"?` : ''}`;
+    super(msg);
+    this.name = 'HubSectionError';
+    this.section = section;
+    this.suggestion = suggestion;
+    this.allowed_sections = allowed;
+  }
+}
+
+export function computeSectionCapabilities(record, rowType, core = null) {
+  if (!core) core = loadKnowledgeCore();
+  const available_sections = ['overview', 'links'];
+  const section_status = {
+    overview: 'documented',
+    links: 'documented',
+  };
+
+  const selected = selectedContent(record, 'zh');
+  const content = selected.value;
+  const deploy = record?.deployable_content || { deployable: false, solution_id: null };
+
+  const hasDescDoc = deploy.description_documents && Object.keys(deploy.description_documents).length > 0;
+  const hasDescBody = Boolean(content?.description_body || content?.description || record?.summary);
+  if (hasDescDoc || hasDescBody) {
+    available_sections.push('description');
+    section_status.description = 'documented';
+  }
+
+  const hasArchOverlay = deploy.architecture_overlay && Object.keys(deploy.architecture_overlay).length > 0;
+  const hasArchModules = Boolean(content?.architecture?.length);
+  const hasGallery = Boolean(deploy.architecture_and_gallery?.length);
+  if (hasArchOverlay || hasArchModules || hasGallery) {
+    available_sections.push('architecture');
+    section_status.architecture = 'documented';
+  }
+
+  const hasProducts = (deploy.products && Object.keys(deploy.products).length > 0) || Boolean(content?.products?.length);
+  if (hasProducts) {
+    available_sections.push('products');
+    section_status.products = 'documented';
+  }
+
+  const hasGuides = deploy.deployment_guides && Object.keys(deploy.deployment_guides).length > 0;
+  const hasPresets = Boolean(deploy.presets?.length);
+  const hasGuideDocs = deploy.deployment_guide_documents && Object.keys(deploy.deployment_guide_documents).length > 0;
+  if (hasGuides || hasPresets || hasGuideDocs) {
+    available_sections.push('deployment');
+    section_status.deployment = 'documented';
+  }
+
+  let pbStatus = null;
+  if (record?.diagnostic_playbook || core.diagnostic_playbooks?.[record?.id]) {
+    pbStatus = 'documented';
+  } else if (rowType === 'reference_design') {
+    for (const scId of (record?.scenario_ids || [])) {
+      const sc = (core.scenarios || []).find((s) => s.id === scId);
+      if (sc?.diagnostic_playbook) {
+        pbStatus = 'inherited';
+        break;
+      }
+    }
+  } else if (rowType === 'scenario') {
+    for (const rdId of (record?.reference_designs || [])) {
+      const rd = (core.reference_designs || []).find((r) => r.id === rdId);
+      if (rd?.diagnostic_playbook) {
+        pbStatus = 'inherited';
+        break;
+      }
+    }
+  }
+  if (!pbStatus && (rowType === 'scenario' || rowType === 'reference_design')) {
+    pbStatus = 'generic';
+  }
+  if (pbStatus) {
+    available_sections.push('playbook');
+    section_status.playbook = pbStatus;
+  }
+
+  const isCustomContract = ['recamera-gym-tracker', 'vision-ai-industrial-camera', 'smart-waste-sorting'].includes(deploy.solution_id || record?.id);
+  const hasIntegration = Boolean(deploy.deployable || deploy.solution_id || rowType === 'reference_design' || isCustomContract);
+  if (hasIntegration) {
+    available_sections.push('integration');
+    section_status.integration = isCustomContract ? 'documented' : 'inferred';
+  }
+
+  return { available_sections, section_status };
+}
+
+function normalizeLocale(locale = 'zh') {
+  const value = locale === 'zh-hans' ? 'zh' : String(locale || '').toLowerCase();
+  if (!SUPPORTED_LOCALES.has(value)) throw new Error(`Unsupported locale "${locale}". Use en, zh, or ja.`);
+  return value;
+}
+
+function visibilityAllows(record, locale, type) {
+  if (record?.published === false) return false;
+  if (type === 'reference_design') return record?.visibility !== 'staging' && record?.visibility !== 'draft';
+  const value = record?.[`visibility_${locale === 'zh' ? 'zh_hans' : locale}`] ?? record?.visibility;
+  return value !== 'staging' && value !== 'draft';
+}
+
+function recordType(record, fallback) {
+  if (fallback === 'reference_design') return fallback;
+  return record?.page_type === 'TECH' ? 'tech' : 'scenario';
+}
+
+function localizedValue(value, locale) {
+  if (!value || typeof value !== 'object') return value || '';
+  return value[locale] || value.zh || value.en || value.ja || '';
+}
+
+function localizedLanding(record, locale) {
+  return record?.landing_urls?.[locale] || record?.landing_url || null;
+}
+
+function selectedContent(record, locale) {
+  const requested = record.locale_content?.[locale];
+  if (requested) return { value: requested, locale };
+  for (const fallback of ['en', 'zh', 'ja']) {
+    if (record.locale_content?.[fallback]) return { value: record.locale_content[fallback], locale: fallback };
+  }
+  return { value: null, locale: null };
+}
+
+function selectedSummary(record, content, requestedLocale, selectedLocale) {
+  if (typeof content?.summary === 'string' && content.summary.trim()) {
+    return { value: content.summary, locale: selectedLocale };
+  }
+  if (record?.summary && typeof record.summary === 'object' && !Array.isArray(record.summary)) {
+    for (const locale of [requestedLocale, 'en', 'zh', 'ja']) {
+      if (typeof record.summary[locale] === 'string' && record.summary[locale].trim()) {
+        return { value: record.summary[locale], locale };
+      }
+    }
+    return { value: null, locale: null };
+  }
+  if (typeof record?.summary === 'string' && record.summary.trim()) {
+    return { value: record.summary, locale: null };
+  }
+  return { value: null, locale: null };
+}
+
+function compactRecord(record, type, locale) {
+  const resolvedType = recordType(record, type);
+  const visible = visibilityAllows(record, locale, type);
+  return {
+    id: record.id,
+    type: resolvedType,
+    title: localizedValue(record.title, locale) || record.name || record.id,
+    landing_url: visible ? localizedLanding(record, locale) : null,
+    scenario_ids: record.scenario_ids || [],
+    reference_designs: record.reference_designs || [],
+    technology_ids: record.technology_ids || [],
+    solution_id: record.deployable_content?.solution_id || null,
+    deployable: record.deployable_content?.deployable === true,
+  };
+}
+
+function compactSearchRecord(record) {
+  const { diagnostic_playbook: pb, ...compact } = record;
+  const hasPlaybook = Boolean(pb && (pb.questions?.length || pb.core_dimensions?.length));
+  const core = loadKnowledgeCore();
+  const bundled = (record.type === 'reference_design')
+    ? (core.reference_designs || []).find((r) => r.id === record.id)
+    : (core.scenarios || []).find((s) => s.id === record.id);
+  const targetRecord = bundled || record;
+  const caps = computeSectionCapabilities(targetRecord, record.type, core);
+
+  return {
+    ...compact,
+    summary: compact.summary || compact.subtitle?.zh || '',
+    available_sections: caps.available_sections,
+    section_status: caps.section_status,
+    ...(hasPlaybook ? {
+      has_playbook: true,
+      playbook_dimensions: pb.core_dimensions || [],
+    } : {}),
+  };
+}
+
+function localizedSearch(record, locale) {
+  const selected = selectedContent(record, locale);
+  const contentTitle = typeof selected.value?.title === 'string' && selected.value.title.trim() ? selected.value.title : '';
+  let titleLocale = null;
+  let title = '';
+  if (contentTitle && selected.locale === locale) {
+    titleLocale = selected.locale;
+    title = contentTitle;
+  } else {
+    titleLocale = [locale, 'en', 'zh', 'ja'].find((key) => typeof record?.title?.[key] === 'string' && record.title[key].trim()) || null;
+    title = titleLocale ? record.title[titleLocale] : contentTitle;
+    if (!titleLocale && contentTitle) titleLocale = selected.locale;
+  }
+  const summary = selectedSummary(record, selected.value, locale, selected.locale);
+  const contentLocale = summary.value ? summary.locale : titleLocale;
+  return {
+    title,
+    title_locale: titleLocale,
+    summary: summary.value || '',
+    content_locale: contentLocale,
+    fallback: contentLocale !== null && contentLocale !== locale,
+  };
+}
+
+function onlineLocalizedText(record, locale, fieldsByLocale) {
+  const fallbackLocales = locale === 'ja'
+    ? ['en', 'zh']
+    : locale === 'en'
+      ? ['zh', 'ja']
+      : ['en', 'ja'];
+  for (const candidateLocale of [locale, ...fallbackLocales]) {
+    for (const field of fieldsByLocale[candidateLocale] || []) {
+      const value = record?.[field];
+      if (typeof value === 'string' && value.trim()) return { value, locale: candidateLocale };
+    }
+  }
+  return { value: '', locale: null };
+}
+
+function extractArchitecturePreview(doc, bundled, locale, type) {
+  const locKey = locale === 'zh' ? 'zh_hans' : locale;
+  if (type === 'reference_design') {
+    const candidateIntro = doc?.[`architecture_intro_md_${locKey}`] ||
+      doc?.architecture_intro_md_zh_hans ||
+      doc?.architecture_intro_md_en ||
+      doc?.architecture_intro_md_ja;
+    if (typeof candidateIntro === 'string') {
+      const match = candidateIntro.match(/!\[(.*?)\]\(([^\)]+)\)/);
+      if (match) {
+        return {
+          image_url: match[2],
+          summary: match[1] || doc?.[`architecture_lead_${locKey}`] || '',
+        };
+      }
+    }
+    const overlay = bundled?.deployable_content?.architecture_overlay;
+    if (overlay) {
+      const o = overlay[locale] || overlay.zh || overlay.en || overlay.ja;
+      if (typeof o?.intro === 'string') {
+        const match = o.intro.match(/!\[(.*?)\]\(([^\)]+)\)/);
+        if (match) {
+          return {
+            image_url: match[2],
+            summary: match[1] || '',
+          };
+        }
+      }
+    }
+  } else if (type === 'scenario') {
+    const pageDataCandidate = doc?.[`page_data_${locKey}`] || doc?.page_data_zh_hans || doc?.page_data_en;
+    if (pageDataCandidate) {
+      try {
+        const pd = typeof pageDataCandidate === 'string' ? JSON.parse(pageDataCandidate) : pageDataCandidate;
+        const tabs = pd?.deployment?.tabs || [];
+        for (const tab of tabs) {
+          if (typeof tab.card_image === 'string' && tab.card_image.trim()) {
+            return {
+              image_url: tab.card_image.trim(),
+              summary: tab.label || tab.title || tab.id || '',
+            };
+          }
+        }
+      } catch (e) {}
+    }
+    const locContent = bundled?.locale_content?.[locale] || bundled?.locale_content?.zh || bundled?.locale_content?.en;
+    const archTabs = locContent?.architecture || [];
+    for (const tab of archTabs) {
+      if (typeof tab.card_image === 'string' && tab.card_image.trim()) {
+        return {
+          image_url: tab.card_image.trim(),
+          summary: tab.label || tab.id || '',
+        };
+      }
+    }
+  }
+  return null;
+}
+
+function bundledSearchProjection(record, type, locale, source = 'bundled_manifest') {
+  const text = localizedSearch(record, locale);
+  const archPreview = extractArchitecturePreview(null, record, locale, type);
+  return {
+    type,
+    id: record.id,
+    title: text.title,
+    title_locale: text.title_locale,
+    summary: text.summary,
+    content_locale: text.content_locale,
+    fallback: text.fallback,
+    ...(archPreview ? { architecture_preview: archPreview } : {}),
+    landing_url: appendUtm(localizedLanding(record, locale), {
+      source: 'sensecraft_agent', medium: 'solution_consult', campaign: record.id, content: 'solution_landing',
+    }),
+    scenario_ids: record.scenario_ids || [],
+    technology_ids: record.technology_ids || [],
+    reference_designs: record.reference_designs || [],
+    details_available: true,
+    next_action: `Use hub get ${record.id} --type ${type} for verified section content.`,
+    source,
+  };
+}
+
+function allHubRecords(locale, { includeHidden = false } = {}) {
+  const core = loadKnowledgeCore();
+  const scenarios = (core.scenarios || []).filter(r => includeHidden || visibilityAllows(r, locale, 'scenario'))
+    .map(r => ({ record: r, type: recordType(r, 'scenario') }));
+  const refs = (core.reference_designs || []).filter(r => includeHidden || visibilityAllows(r, locale, 'reference_design'))
+    .map(r => ({ record: r, type: 'reference_design' }));
+  return [...scenarios, ...refs].sort((a, b) => `${a.type}:${a.record.id}`.localeCompare(`${b.type}:${b.record.id}`));
+}
+
+/** List the complete bundled page snapshot, with compact rows only. */
+export function listHub({ type = null, locale = 'zh', page = 1, limit = 50 } = {}) {
+  const loc = normalizeLocale(locale);
+  if (type && !HUB_TYPES.has(type)) throw new Error(`Unsupported hub type "${type}".`);
+  if (!Number.isSafeInteger(page) || page < 1) throw new Error('Page must be a positive integer.');
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 200) throw new Error('Limit must be an integer from 1 to 200.');
+  const records = allHubRecords(loc).filter(({ type: rowType }) => !type || rowType === type);
+  const start = (page - 1) * limit;
+  const rows = records.slice(start, start + limit).map(({ record, type: rowType }) => compactRecord(record, rowType, loc));
+  const total = records.length;
+  return createCatalogDto({
+    source: 'bundled_manifest',
+    freshness: 'UNKNOWN',
+    datasetVersion: loadKnowledgeCore().dataset_version,
+    records: rows,
+    locale: loc,
+    scope: 'bundled_catalog_snapshot',
+    pagination: { page, limit, total, returned: rows.length, has_more: start + rows.length < total, next_page: start + rows.length < total ? page + 1 : null },
+    provenance: loadKnowledgeCore().provenance || null,
+    warnings: ['Snapshot completeness applies to the bundled catalog only; it is not a live website inventory.'],
+  });
+}
+
+function populateSectionData(row, section, record, rowType, loc, selected, content, summary, deploy, core, preset) {
+  if (section === 'links') {
+    row.links = { landing: row.landing_urls, wiki: record.wiki_url || null, repo: record.repo_url || null, declared_documents: deploy.source_files || [] };
+  } else if (section === 'description') {
+    const doc = deploy.description_documents?.[loc] || deploy.description_documents?.en || null;
+    const body = doc?.body || content?.description_body || content?.description || summary.value || '';
+    const descriptionLocale = doc?.content_locale || (body === summary.value ? summary.locale : selected.locale);
+    row.description = {
+      content_locale: descriptionLocale,
+      fallback: descriptionLocale !== null && descriptionLocale !== loc,
+      source_role: doc ? 'deployment_document' : (content?.description_source_role || 'summary'),
+      body,
+      source: doc?.source || content?.source || null,
+      sha256: doc?.sha256 || null,
+      file: deploy.description_files?.[loc] || deploy.description_files?.en || null,
+    };
+  } else if (section === 'architecture') {
+    const overlayLocales = deploy.architecture_overlay || {};
+    const architecture = overlayLocales[loc]
+      ? { value: overlayLocales[loc], locale: loc }
+      : (overlayLocales.en ? { value: overlayLocales.en, locale: 'en' }
+        : (overlayLocales.zh ? { value: overlayLocales.zh, locale: 'zh' }
+          : (overlayLocales.ja ? { value: overlayLocales.ja, locale: 'ja' } : { value: null, locale: null })));
+    const galleryLocale = (deploy.architecture_and_gallery || []).some((g) => g.src_i18n?.[loc]) ? loc : ((deploy.architecture_and_gallery || []).some((g) => g.src_i18n?.en) ? 'en' : null);
+    const overlay = architecture.value;
+    const archPreview = extractArchitecturePreview(null, record, loc, rowType);
+    row.architecture = {
+      content_locale: architecture.locale || (content?.content_locale ? selected.locale : galleryLocale),
+      fallback: Boolean(architecture.locale && architecture.locale !== loc),
+      source_role: overlay ? 'reference_design.overlay' : (content?.architecture?.length ? 'deployment.tabs' : 'solution.gallery'),
+      image_url: archPreview?.image_url || null,
+      summary: archPreview?.summary || null,
+      intro: overlay?.intro || '',
+      modules: overlay?.tabs || content?.architecture || [],
+      source: overlay?.source || null,
+      gallery: deploy.architecture_and_gallery || [],
+    };
+  } else if (section === 'products') {
+    row.products = deploy.products || content?.products || {};
+    row.bom = content?.bom || deploy.bom || {};
+    row.products_content_locale = content?.products?.length ? selected.locale : null;
+    row.products_source_role = content?.products?.length ? 'deployment.tabs' : 'solution.device_catalog';
+  } else if (section === 'deployment') {
+    const guide = deploy.deployment_guide_documents?.[loc] || deploy.deployment_guide_documents?.en || null;
+    let guideBody = guide ? guide.body : null;
+    let filteredByPreset = null;
+
+    if (guideBody && preset) {
+      const normPreset = String(preset).toLowerCase().trim();
+      const packagePattern = /(^|\n)##\s+套餐[^\n]*\{#([a-zA-Z0-9_\-]+)\}/g;
+      let match;
+      const sections = [];
+      while ((match = packagePattern.exec(guideBody)) !== null) {
+        sections.push({
+          id: match[2].toLowerCase(),
+          index: match.index,
+        });
+      }
+      if (sections.length > 0) {
+        const targetIdx = sections.findIndex((s) => s.id === normPreset || s.id.includes(normPreset) || normPreset.includes(s.id));
+        if (targetIdx !== -1) {
+          const start = sections[targetIdx].index;
+          const end = targetIdx + 1 < sections.length ? sections[targetIdx + 1].index : guideBody.length;
+          const header = guideBody.slice(0, sections[0].index).trim();
+          const bodyChunk = guideBody.slice(start, end).trim();
+          guideBody = `${header ? header + '\n\n---\n\n' : ''}${bodyChunk}`;
+          filteredByPreset = normPreset;
+        }
+      }
+    }
+
+    row.deployment = {
+      deployable: deploy.deployable === true,
+      solution_id: deploy.solution_id || null,
+      presets: deploy.presets || [],
+      guides: deploy.deployment_guides || {},
+      guide: guide ? { content_locale: guide.content_locale, body: guideBody, source: guide.source, sha256: guide.sha256 } : null,
+      source_files: deploy.source_files || [],
+      ...(filteredByPreset ? { filtered_by_preset: filteredByPreset } : {}),
+    };
+  } else if (section === 'playbook') {
+    let pb = record.diagnostic_playbook || core.diagnostic_playbooks?.[record.id];
+    if (!pb && rowType === 'reference_design') {
+      for (const scId of (record.scenario_ids || [])) {
+        const sc = (core.scenarios || []).find((s) => s.id === scId);
+        if (sc?.diagnostic_playbook) {
+          pb = sc.diagnostic_playbook;
+          break;
+        }
+      }
+    }
+    if (!pb && rowType === 'scenario') {
+      for (const rdId of (record.reference_designs || [])) {
+        const rd = (core.reference_designs || []).find((r) => r.id === rdId);
+        if (rd?.diagnostic_playbook) {
+          pb = rd.diagnostic_playbook;
+          break;
+        }
+      }
+    }
+    if (pb) {
+      row.playbook = {
+        domain: pb.domain || row.title,
+        core_dimensions: pb.core_dimensions || [],
+        questions: (pb.questions || []).map((q) => ({
+          dimension: q.dimension,
+          question: q.question,
+          rationale: q.rationale,
+        })),
+        source_role: 'diagnostic_playbook',
+      };
+    } else {
+      row.playbook = {
+        domain: row.title,
+        core_dimensions: [
+          '物理拓扑分布 (集中 vs 分布)',
+          '存量资产利旧 (摄像头/传感器)',
+          '供电与网络环境 (市电/电池/PoE)',
+          '业务执行与闭环联动 (看板/控制)',
+        ],
+        questions: [
+          { dimension: 'topology', question: '测点是在同一建筑/车间集中分布，还是分散在多个物理区域？', rationale: '决定采用单台高算力计算盒集中拉流，还是采用分布式独立一体化终端。' },
+          { dimension: 'asset_reuse', question: '现场是否已有现成的 IP 摄像头 (RTSP/ONVIF) 或传感器 (RS485/Modbus) 可以利旧？', rationale: '直接复用存量硬件可显著缩减项目落地成本与施工周期。' },
+          { dimension: 'power_network', question: '安装点是否有 220V 市电供电？现场网络是有线网 (PoE)、Wi-Fi 还是需 4G/LoRaWAN 远距无线？', rationale: '决定供电设备规格与通信选型。' },
+        ],
+        source_role: 'generic_diagnostic_playbook',
+      };
+    }
+  } else if (section === 'integration') {
+    const guideDoc = deploy.deployment_guide_documents?.[loc] || deploy.deployment_guide_documents?.en || null;
+    const contract = getIntegrationContract(deploy.solution_id || record.id, {
+      guideText: guideDoc?.body || '',
+    });
+    row.integration = contract;
+  } else if (section === 'overview') {
+    row.links = { landing: row.landing_urls, wiki: record.wiki_url || null, repo: record.repo_url || null };
+    row.description = { content_locale: summary.locale, fallback: summary.locale !== null && summary.locale !== loc, source_role: 'summary', summary: summary.value || '' };
+    row.relationships = { scenario_ids: record.scenario_ids || [], reference_designs: record.reference_designs || [], technology_ids: record.technology_ids || [] };
+    row.deployable_content = { deployable: deploy.deployable === true, solution_id: deploy.solution_id || null, presets: deploy.presets || [], guides: deploy.deployment_guides || {} };
+  }
+}
+
+/** Get one selected graph record and progressive content section(s). */
+export function getHubRecord(id, { type = null, locale = 'zh', section = null, sections = null, preset = null } = {}) {
+  const loc = normalizeLocale(locale);
+  if (!id) throw new Error('A hub record ID is required.');
+  if (type && !HUB_TYPES.has(type)) throw new Error(`Unsupported hub type "${type}".`);
+
+  let requestedSections = [];
+  if (sections) {
+    if (Array.isArray(sections)) {
+      requestedSections = sections.flatMap((s) => String(s).split(','));
+    } else if (typeof sections === 'string') {
+      requestedSections = sections.split(',');
+    }
+  } else if (section) {
+    requestedSections = String(section).split(',');
+  } else {
+    requestedSections = ['overview'];
+  }
+  requestedSections = requestedSections.map((s) => s.trim().toLowerCase()).filter(Boolean);
+  if (requestedSections.length === 0) requestedSections = ['overview'];
+
+  for (const sec of requestedSections) {
+    if (!HUB_SECTIONS.has(sec)) {
+      throw new HubSectionError(sec, Array.from(HUB_SECTIONS));
+    }
+  }
+
+  const matches = allHubRecords(loc, { includeHidden: true }).filter(({ record, type: rowType }) => record.id === id && (!type || rowType === type));
+  if (matches.length === 0) return null;
+  if (matches.length > 1 && !type) throw new Error(`ID "${id}" is ambiguous; specify --type scenario, tech, or reference_design.`);
+  const { record, type: rowType } = matches[0];
+  const row = compactRecord(record, rowType, loc);
+  row.visibility = record.visibility || record[`visibility_${loc === 'zh' ? 'zh_hans' : loc}`] || null;
+  row.landing_urls = Object.fromEntries(Object.entries(record.landing_urls || {})
+    .filter(([landingLocale]) => visibilityAllows(record, landingLocale, rowType)));
+  const selected = selectedContent(record, loc);
+  const content = selected.value;
+  const summary = selectedSummary(record, content, loc, selected.locale);
+  const deploy = record.deployable_content || { deployable: false, solution_id: null };
+  const core = loadKnowledgeCore();
+
+  const caps = computeSectionCapabilities(record, rowType, core);
+  row.available_sections = caps.available_sections;
+  row.section_status = caps.section_status;
+
+  if (requestedSections.length === 1) {
+    row.section = requestedSections[0];
+    populateSectionData(row, requestedSections[0], record, rowType, loc, selected, content, summary, deploy, core, preset);
+  } else {
+    row.sections = requestedSections;
+    for (const sec of requestedSections) {
+      populateSectionData(row, sec, record, rowType, loc, selected, content, summary, deploy, core, preset);
+    }
+  }
+
+  return row;
+}
+
+/**
+ * Detects if a search query matches known hardware product families, models, or SKUs.
+ *
+ * @param {string[]} tokens
+ * @param {string} query
+ * @param {Object} core
+ * @returns {string|null} Helpful redirect note if hardware is detected
+ */
+function detectHardwareIntent(tokens, query, core) {
+  if (!tokens || tokens.length === 0) return null;
+  const families = Object.values(core?.product_families || {});
+  const matchedHw = families.find((fam) => {
+    const fid = (fam.id || '').toLowerCase();
+    const zh = (fam.title?.zh || '').toLowerCase();
+    const en = (fam.title?.en || '').toLowerCase();
+    if (tokens.some((t) => fid.includes(t) || zh.includes(t) || en.includes(t))) return true;
+    return (fam.skus || []).some((s) => {
+      const sNum = String(s.sku || '').toLowerCase();
+      const sModel = String(s.model || '').toLowerCase();
+      const sName = String(s.name || '').toLowerCase();
+      return tokens.some((t) => sNum === t || (sModel && sModel.includes(t)) || sName.includes(t));
+    });
+  });
+  if (matchedHw) {
+    return `💡 提示: 检测到硬件设备/型号关键词 "${query}"。若需查询该硬件的物理接口、包装清单（是否带电源）或官方落地应用方案，请使用: solution-cli product search "${query}"`;
+  }
+  return null;
+}
+
 /**
  * Searches Seeed Solutions Hub scenarios and reference designs.
  *
@@ -132,7 +750,11 @@ export function loadClientConfig() {
  * @returns {Promise<Object>} Standardized Catalog DTO
  */
 export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
+  const normalizedLocale = normalizeLocale(locale);
+  locale = normalizedLocale;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 200) throw new Error('Limit must be an integer from 1 to 200.');
   const qLower = (query || '').toLowerCase().trim();
+  const tokens = qLower.split(/\s+/).filter(Boolean);
   const clientConfig = loadClientConfig();
   const host = process.env.TYPESENSE_HOST || clientConfig?.typesense?.host || 'https://rel-search.seeedstudio.com';
   const keySolution = process.env.TYPESENSE_SEARCH_KEY_SOLUTION || process.env.TYPESENSE_SEARCH_KEY || clientConfig?.typesense?.search_key_solution;
@@ -180,25 +802,41 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
             if (doc[`visibility_${locKey}`] === 'staging' || doc[`visibility_${locKey}`] === 'draft') continue;
 
             const docId = doc.id || doc.slug;
-            const docType = doc.doc_type || 'scenario';
-            const title = locale === 'en'
-              ? (doc.title_en || doc.title_zh_hans || docId)
-              : (doc.title_zh_hans || doc.title_en || docId);
-            const summary = locale === 'en'
-              ? (doc.excerpt_en || doc.seo_description_en || doc.excerpt_zh_hans || '')
-              : (doc.excerpt_zh_hans || doc.seo_description_zh_hans || doc.excerpt_en || '');
-            const tags = (locale === 'en' ? doc.display_tags_en : doc.display_tags_zh_hans) || doc.display_tags || [];
+            const docType = doc.doc_type || recordType((core.scenarios || []).find((s) => s.id === docId), 'scenario');
+            const titleText = onlineLocalizedText(doc, locale, {
+              en: ['title_en'], zh: ['title_zh_hans'], ja: ['title_ja'],
+            });
+            const summaryText = onlineLocalizedText(doc, locale, {
+              en: ['excerpt_en', 'seo_description_en'],
+              zh: ['excerpt_zh_hans', 'seo_description_zh_hans'],
+              ja: ['excerpt_ja', 'seo_description_ja'],
+            });
+            const title = titleText.value || docId;
+            const summary = summaryText.value;
+            const tags = (locale === 'en' ? doc.display_tags_en : locale === 'ja' ? (doc.display_tags_ja || doc.display_tags_en) : doc.display_tags_zh_hans) || doc.display_tags || [];
+            const bundledScenario = (core.scenarios || []).find((s) => s.id === docId);
+            const resolvedType = ['scenario', 'tech', 'reference_design'].includes(docType) ? docType : recordType(bundledScenario, 'scenario');
             const pb = core.diagnostic_playbooks?.[docId] || doc.diagnostic_playbook || null;
-            const rawLanding = doc.external_url || doc.landing_url || `https://www.seeedstudio.com/solutions/${docId}`;
+            const rawLanding = doc.external_url || doc.landing_url || localizedLanding(bundledScenario, locale) || null;
+            const archPreview = extractArchitecturePreview(doc, bundledScenario, locale, 'scenario');
 
             onlineScenarios.push({
-              type: docType,
+              type: resolvedType,
               id: docId,
               title,
               summary,
               tags,
               family_ids: doc.family_ids || [],
               reference_designs: doc.reference_designs || [],
+              technology_ids: doc.technology_ids || bundledScenario?.technology_ids || [],
+              scenario_ids: doc.scenario_ids || bundledScenario?.scenario_ids || [],
+              title_locale: titleText.locale,
+              summary_locale: summaryText.locale,
+              content_locale: summaryText.locale || titleText.locale,
+              fallback: (summaryText.locale || titleText.locale) !== null && (summaryText.locale || titleText.locale) !== locale,
+              ...(archPreview ? { architecture_preview: archPreview } : {}),
+              details_available: Boolean(bundledScenario),
+              next_action: bundledScenario ? `Use hub get ${docId} --type ${resolvedType} for verified section content.` : `Open the production landing page for ${docId}; bundled section content is unavailable.`,
               landing_url: appendUtm(rawLanding, {
                 source: 'sensecraft_agent',
                 medium: 'solution_consult',
@@ -218,12 +856,16 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
             const locKey = locale === 'zh' ? 'zh_hans' : locale;
             if (doc[`visibility_${locKey}`] === 'staging' || doc[`visibility_${locKey}`] === 'draft') continue;
             const docId = doc.id;
-            const title = locale === 'en'
-              ? (doc.name_en || doc.name_zh_hans || docId)
-              : (doc.name_zh_hans || doc.name_en || docId);
-            const summary = locale === 'en'
-              ? (doc.summary_en || doc.tagline_en || doc.summary_zh_hans || '')
-              : (doc.summary_zh_hans || doc.tagline_zh_hans || doc.summary_en || '');
+            const titleText = onlineLocalizedText(doc, locale, {
+              en: ['name_en'], zh: ['name_zh_hans'], ja: ['name_ja'],
+            });
+            const summaryText = onlineLocalizedText(doc, locale, {
+              en: ['summary_en', 'tagline_en'],
+              zh: ['summary_zh_hans', 'tagline_zh_hans'],
+              ja: ['summary_ja', 'tagline_ja'],
+            });
+            const title = titleText.value || docId;
+            const summary = summaryText.value;
 
             let pb = doc.diagnostic_playbook || core.diagnostic_playbooks?.[docId] || null;
             if (!pb) {
@@ -246,6 +888,7 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
 
             const bundledRd = (core.reference_designs || []).find((r) => r.id === docId);
             const repoUrl = doc.repo_url || bundledRd?.repo_url || '';
+            const archPreview = extractArchitecturePreview(doc, bundledRd, locale, 'reference_design');
 
             onlineRefDesigns.push({
               type: 'reference_design',
@@ -253,7 +896,7 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
               title,
               summary,
               presets,
-              landing_url: appendUtm(`https://www.seeedstudio.com/solutions/reference-designs/${docId}`, {
+              landing_url: appendUtm(doc.landing_url?.[locale] || doc.external_url?.[locale] || bundledRd?.landing_urls?.[locale] || null, {
                 source: 'sensecraft_agent',
                 medium: 'solution_consult',
                 campaign: docId,
@@ -265,6 +908,15 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
                 campaign: docId,
               }) : '',
               repo_url: repoUrl,
+              title_locale: titleText.locale,
+              summary_locale: summaryText.locale,
+              content_locale: summaryText.locale || titleText.locale,
+              fallback: (summaryText.locale || titleText.locale) !== null && (summaryText.locale || titleText.locale) !== locale,
+              ...(archPreview ? { architecture_preview: archPreview } : {}),
+              scenario_ids: bundledRd?.scenario_ids || [],
+              technology_ids: bundledRd?.technology_ids || [],
+              details_available: Boolean(bundledRd),
+              next_action: bundledRd ? `Use hub get ${docId} --type reference_design for verified section content.` : `Open the production landing page for ${docId}; bundled section content is unavailable.`,
               diagnostic_playbook: pb,
               source: 'typesense',
             });
@@ -274,34 +926,17 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
 
       // If one collection returned results but the other was unavailable/failed/empty, supplement from bundled catalog
       if ((onlineScenarios.length > 0 && onlineRefDesigns.length === 0) || (onlineRefDesigns.length > 0 && onlineScenarios.length === 0)) {
-        const tokens = qLower.split(/\s+/).filter(Boolean);
         if (onlineScenarios.length === 0) {
           for (const s of core.scenarios || []) {
             if (s.published === false || s.visibility === 'staging' || s.visibility === 'draft') continue;
             const locKey = locale === 'zh' ? 'zh_hans' : locale;
             if (s[`visibility_${locKey}`] === 'staging' || s[`visibility_${locKey}`] === 'draft') continue;
 
-            const haystack = [s.id, s.title?.zh, s.title?.en, s.subtitle?.zh, s.subtitle?.en, s.summary, ...(s.tags || [])].join(' ').toLowerCase();
+            const localizedFields = Object.values(s.locale_content || {}).flatMap((content) => [content?.title, content?.summary]);
+            const haystack = [s.id, s.title?.zh, s.title?.en, s.title?.ja, s.subtitle?.zh, s.subtitle?.en, s.subtitle?.ja, s.summary, ...localizedFields, ...(s.tags || [])].join(' ').toLowerCase();
             const score = tokens.reduce((acc, t) => (haystack.includes(t) ? acc + 1 : acc), 0);
             if (tokens.length === 0 || score > 0) {
-              onlineScenarios.push({
-                type: 'scenario',
-                id: s.id,
-                title: s.title?.[locale] || s.title?.zh || s.title?.en || s.id,
-                summary: s.subtitle?.[locale] || s.subtitle?.zh || s.summary || '',
-                tags: s.tags || [],
-                family_ids: s.family_ids || [],
-                reference_designs: s.reference_designs || [],
-                landing_url: appendUtm(s.landing_url || `https://www.seeedstudio.com/solutions/${s.id}`, {
-                  source: 'sensecraft_agent',
-                  medium: 'solution_consult',
-                  campaign: s.id,
-                  content: 'scenario_landing',
-                }),
-                repo_url: s.repo_url || '',
-                diagnostic_playbook: s.diagnostic_playbook || null,
-                source: 'bundled_manifest',
-              });
+              onlineScenarios.push({ ...bundledSearchProjection({ ...s, summary: s.subtitle || s.summary }, recordType(s, 'scenario'), locale), tags: s.tags || [], family_ids: s.family_ids || [], repo_url: s.repo_url || '', diagnostic_playbook: s.diagnostic_playbook || null });
             }
           }
         }
@@ -311,30 +946,11 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
             const locKey = locale === 'zh' ? 'zh_hans' : locale;
             if (rd[`visibility_${locKey}`] === 'staging' || rd[`visibility_${locKey}`] === 'draft') continue;
 
-            const haystack = [rd.id, rd.title?.zh, rd.title?.en, rd.summary?.zh, rd.summary?.en, ...(rd.presets || [])].join(' ').toLowerCase();
+            const localizedFields = Object.values(rd.locale_content || {}).flatMap((content) => [content?.title, content?.summary]);
+            const haystack = [rd.id, rd.title?.zh, rd.title?.en, rd.title?.ja, rd.summary?.zh, rd.summary?.en, rd.summary?.ja, ...localizedFields, ...(rd.presets || [])].join(' ').toLowerCase();
             const score = tokens.reduce((acc, t) => (haystack.includes(t) ? acc + 1 : acc), 0);
             if (tokens.length === 0 || score > 0) {
-              onlineRefDesigns.push({
-                type: 'reference_design',
-                id: rd.id,
-                title: rd.title?.[locale] || rd.title?.zh || rd.title?.en || rd.id,
-                summary: rd.summary?.[locale] || rd.summary?.zh || rd.summary?.en || '',
-                presets: rd.presets || [],
-                landing_url: appendUtm(rd.landing_url || `https://www.seeedstudio.com/solutions/reference-designs/${rd.id}`, {
-                  source: 'sensecraft_agent',
-                  medium: 'solution_consult',
-                  campaign: rd.id,
-                  content: 'solution_landing',
-                }),
-                wiki_url: rd.wiki_url ? appendUtm(rd.wiki_url, {
-                  source: 'sensecraft_agent',
-                  medium: 'tech_wiki',
-                  campaign: rd.id,
-                }) : '',
-                repo_url: rd.repo_url || '',
-                diagnostic_playbook: rd.diagnostic_playbook || null,
-                source: 'bundled_manifest',
-              });
+              onlineRefDesigns.push({ ...bundledSearchProjection(rd, 'reference_design', locale), presets: rd.presets || [], wiki_url: rd.wiki_url || '', repo_url: rd.repo_url || '', diagnostic_playbook: rd.diagnostic_playbook || null });
             }
           }
         }
@@ -352,10 +968,18 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
       }
 
       if (mergedRecords.length > 0) {
+        const onlineWarnings = ['Online search results are partial and do not replace the bundled catalog; use hub get for verified section content.'];
+        const hwHint = detectHardwareIntent(tokens, query, core);
+        if (hwHint) {
+          onlineWarnings.push(hwHint);
+        }
         return createCatalogDto({
           source: (onlineScenarios.some(r => r.source === 'typesense') || onlineRefDesigns.some(r => r.source === 'typesense')) ? 'typesense' : 'bundled_manifest',
-          freshness: 'FRESH',
-          records: mergedRecords,
+          freshness: 'UNKNOWN',
+          datasetVersion: core.dataset_version,
+          scope: 'online_partial_with_bundled_fallback',
+          warnings: onlineWarnings,
+          records: mergedRecords.map(compactSearchRecord),
         });
       }
     } catch {
@@ -368,39 +992,31 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
   const matchedScenarios = [];
   const matchedRefDesigns = [];
 
-  const tokens = qLower.split(/\s+/).filter(Boolean);
-
   for (const s of core.scenarios || []) {
     if (s.published === false || s.visibility === 'staging' || s.visibility === 'draft') continue;
     const locKey = locale === 'zh' ? 'zh_hans' : locale;
     if (s[`visibility_${locKey}`] === 'staging' || s[`visibility_${locKey}`] === 'draft') continue;
 
+    const localizedFields = Object.values(s.locale_content || {}).flatMap((content) => [content?.title, content?.summary]);
     const haystack = [
       s.id,
       s.title?.zh,
       s.title?.en,
+      s.title?.ja,
       s.subtitle?.zh,
       s.subtitle?.en,
+      s.subtitle?.ja,
       s.summary,
+      ...localizedFields,
       ...(s.tags || []),
     ].join(' ').toLowerCase();
 
     const score = tokens.reduce((acc, token) => (haystack.includes(token) ? acc + 1 : acc), 0);
     if (tokens.length === 0 || score > 0) {
       matchedScenarios.push({
-        type: 'scenario',
-        id: s.id,
-        title: s.title?.[locale] || s.title?.zh || s.title?.en || s.id,
-        summary: s.subtitle?.[locale] || s.subtitle?.zh || s.summary || '',
+        ...bundledSearchProjection({ ...s, summary: s.subtitle || s.summary }, recordType(s, 'scenario'), locale),
         tags: s.tags || [],
         family_ids: s.family_ids || [],
-        reference_designs: s.reference_designs || [],
-        landing_url: appendUtm(s.landing_url || `https://www.seeedstudio.com/solutions/${s.id}`, {
-          source: 'sensecraft_agent',
-          medium: 'solution_consult',
-          campaign: s.id,
-          content: 'scenario_landing',
-        }),
         repo_url: s.repo_url || '',
         diagnostic_playbook: s.diagnostic_playbook || null,
         score,
@@ -413,29 +1029,24 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
     const locKey = locale === 'zh' ? 'zh_hans' : locale;
     if (rd[`visibility_${locKey}`] === 'staging' || rd[`visibility_${locKey}`] === 'draft') continue;
 
+    const localizedFields = Object.values(rd.locale_content || {}).flatMap((content) => [content?.title, content?.summary]);
     const haystack = [
       rd.id,
       rd.title?.zh,
       rd.title?.en,
+      rd.title?.ja,
       rd.summary?.zh,
       rd.summary?.en,
+      rd.summary?.ja,
+      ...localizedFields,
       ...(rd.presets || []),
     ].join(' ').toLowerCase();
 
     const score = tokens.reduce((acc, token) => (haystack.includes(token) ? acc + 1 : acc), 0);
     if (tokens.length === 0 || score > 0) {
       matchedRefDesigns.push({
-        type: 'reference_design',
-        id: rd.id,
-        title: rd.title?.[locale] || rd.title?.zh || rd.title?.en || rd.id,
-        summary: rd.summary?.[locale] || rd.summary?.zh || rd.summary?.en || '',
+        ...bundledSearchProjection(rd, 'reference_design', locale),
         presets: rd.presets || [],
-        landing_url: appendUtm(rd.landing_url || `https://www.seeedstudio.com/solutions/reference-designs/${rd.id}`, {
-          source: 'sensecraft_agent',
-          medium: 'solution_consult',
-          campaign: rd.id,
-          content: 'solution_landing',
-        }),
         wiki_url: rd.wiki_url ? appendUtm(rd.wiki_url, {
           source: 'sensecraft_agent',
           medium: 'tech_wiki',
@@ -463,13 +1074,25 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
     }
   }
 
+  const warnings = process.env.SENSECRAFT_OFFLINE_ONLY
+    ? ['Offline-only mode: displaying the verified bundled catalog; no online request was attempted.']
+    : ((keySolution || keyRefDesign)
+      ? ['Online Typesense request timed out or returned no hits. Displaying verified local catalog.']
+      : ['No Typesense API key configured or baked. Displaying verified local catalog.']);
+
+  // Detect if query looks like a hardware device, model, or SKU keyword
+  const hwHint = detectHardwareIntent(tokens, query, core);
+  if (hwHint && (combined.length === 0 || (combined[0] && combined[0].score < 2))) {
+    warnings.push(hwHint);
+  }
+
   return createCatalogDto({
     source: 'bundled_manifest',
-    freshness: 'FRESH',
-    records: combined,
-    warnings: (keySolution || keyRefDesign)
-      ? ['Online Typesense request timed out or returned no hits. Displaying verified local catalog.']
-      : ['No Typesense API key configured or baked. Displaying verified local catalog.'],
+    freshness: 'UNKNOWN',
+    datasetVersion: core.dataset_version,
+    scope: 'bundled_catalog_snapshot',
+    records: combined.map(compactSearchRecord),
+    warnings,
   });
 }
 
@@ -500,8 +1123,12 @@ export function queryProductFamily(familyId, { locale = 'zh' } = {}) {
     records: [{
       family_id: family.id,
       title: family.title?.[locale] || family.title?.zh || family.title?.en || family.id,
+      summary: family.summary || null,
       default_sku: family.default_sku,
       regions: family.regions || [],
+      interfaces: family.interfaces || [],
+      protocols: family.protocols || [],
+      supported_scenarios: family.supported_scenarios || [],
       skus_count: (family.skus || []).length,
       skus: (family.skus || []).slice(0, 10).map((s) => ({
         ...s,
@@ -519,16 +1146,376 @@ export function queryProductFamily(familyId, { locale = 'zh' } = {}) {
   });
 }
 
+/**
+ * Searches product families and member SKUs by keywords, model name, interface, or SKU number.
+ *
+ * @param {Object} options
+ * @param {string} options.query - Free text query (e.g. "J4012 Super", "RS485", "114110314")
+ * @param {'zh' | 'en' | 'ja'} [options.locale='zh']
+ * @param {number} [options.limit=5]
+ * @returns {Object} Catalog DTO
+ */
+export function searchProducts({ query = '', locale = 'zh', limit = 5 } = {}) {
+  const core = loadKnowledgeCore();
+  const families = Object.values(core.product_families || {});
+  const qLower = (query || '').toLowerCase().trim();
+  const tokens = qLower.split(/\s+/).filter(Boolean);
+
+  if (tokens.length === 0) {
+    return createCatalogDto({
+      source: 'bundled_manifest',
+      freshness: 'FRESH',
+      records: [],
+      warnings: ['Query cannot be empty.'],
+    });
+  }
+
+  const matches = [];
+
+  for (const fam of families) {
+    let score = 0;
+    const titleZh = (fam.title?.zh || '').toLowerCase();
+    const titleEn = (fam.title?.en || '').toLowerCase();
+    const fid = (fam.id || '').toLowerCase();
+    const famHaystack = [fid, titleZh, titleEn].join(' ');
+
+    // Check SKU matching
+    const matchedSkus = [];
+    for (const sku of fam.skus || []) {
+      const sNum = String(sku.sku || '').toLowerCase();
+      const sModel = String(sku.model || '').toLowerCase();
+      const sName = String(sku.name || '').toLowerCase();
+      // Strip negative clauses like "（Super Mode NOT Supported)" from positive keyword matching
+      const sNameClean = sName
+        .replace(/[（\(][^）\)]*not\s+supported[^）\)]*[）\)]?/gi, '')
+        .replace(/super\s+mode\s+not\s+supported/gi, '')
+        .replace(/\b(?:not\s+supported|unsupported)\b/gi, '');
+      const sAttrs = Object.values(sku.attrs || {}).map((v) => String(v).toLowerCase());
+      const skuIfaces = (sku.specs?.connectivity?.interfaces || sku.interfaces || []).map((i) => String(i).toLowerCase());
+      const skuProtos = (sku.specs?.connectivity?.protocols || sku.protocols || []).map((p) => String(p).toLowerCase());
+      const skuIoPorts = (sku.specs?.io_ports || []).map((p) => String(p.type || '').toLowerCase());
+
+      const skuHaystack = [sNum, sModel, sNameClean, ...sAttrs, ...skuIfaces, ...skuProtos, ...skuIoPorts].join(' ');
+      const isSingleSkuLookup = tokens.length === 1 && (sNum === tokens[0] || sNum === qLower);
+      const skuMatchesAll = tokens.every((t) => skuHaystack.includes(t));
+      const singleTokenHit = tokens.length === 1 && ((sModel && sModel.includes(tokens[0])) || skuHaystack.includes(tokens[0]));
+
+      if (isSingleSkuLookup || skuMatchesAll) {
+        matchedSkus.push(sku);
+      } else if (tokens.length > 1) {
+        const combinedMatchesAll = tokens.every((t) => (famHaystack + ' ' + skuHaystack).includes(t));
+        const nonFamTokens = tokens.filter((t) => !famHaystack.includes(t));
+        if (combinedMatchesAll && (nonFamTokens.length === 0 || nonFamTokens.every((t) => skuHaystack.includes(t)))) {
+          matchedSkus.push(sku);
+        }
+      } else if (singleTokenHit) {
+        matchedSkus.push(sku);
+      }
+    }
+
+    // Require all query tokens to be satisfied either in the family or across member SKUs
+    const famMatchesAll = tokens.every((t) => famHaystack.includes(t));
+    const allTokensSatisfiedInFamily = tokens.every((t) => {
+      return famHaystack.includes(t) || (fam.skus || []).some((s) => {
+        const sNameClean = String(s.name || '')
+          .toLowerCase()
+          .replace(/[（\(][^）\)]*not\s+supported[^）\)]*[）\)]?/gi, '')
+          .replace(/super\s+mode\s+not\s+supported/gi, '');
+        const sIfaces = (s.specs?.connectivity?.interfaces || s.interfaces || []).map((i) => String(i).toLowerCase());
+        const sProtos = (s.specs?.connectivity?.protocols || s.protocols || []).map((p) => String(p).toLowerCase());
+        const sPorts = (s.specs?.io_ports || []).map((p) => String(p.type || '').toLowerCase());
+        return [s.sku, s.model, sNameClean, ...Object.values(s.attrs || {}), ...sIfaces, ...sProtos, ...sPorts].join(' ').toLowerCase().includes(t);
+      });
+    });
+
+    if (!allTokensSatisfiedInFamily) {
+      continue;
+    }
+
+    if (matchedSkus.length > 0 || famMatchesAll) {
+      score = matchedSkus.length * 10 + (famMatchesAll ? 5 : 0);
+      matches.push({
+        family: fam,
+        score,
+        matchedSkus: matchedSkus.length > 0 ? matchedSkus : (fam.skus || []).slice(0, 3),
+      });
+    }
+  }
+
+  matches.sort((a, b) => b.score - a.score);
+
+  const records = matches.slice(0, limit).map(({ family, matchedSkus }) => {
+    return {
+      family_id: family.id,
+      title: family.title?.[locale] || family.title?.zh || family.title?.en || family.id,
+      summary: family.summary || null,
+      default_sku: family.default_sku,
+      interfaces: family.interfaces || [],
+      protocols: family.protocols || [],
+      supported_scenarios: family.supported_scenarios || [],
+      matched_skus: matchedSkus.map((s) => {
+        const specs = s.specs || {};
+        const pwr = specs.power || {};
+        const pkg = specs.package_contents || [];
+        const pkgText = pkg.join(' ').toLowerCase();
+
+        // Require positive evidence of an included operational battery (not just battery_powered capability or RTC battery)
+        const hasIncludedBattery = pkg.some((item) => {
+          if (!/\bbattery\b/i.test(item)) return false;
+          if (/(?:not\s+included|sold\s+separately|cr1220|rtc|coin)/i.test(item)) return false;
+          if (/(?:without|w\/o|no|exclude[ds]?)\s+[^()]*\bbattery/i.test(item)) return false;
+          return true;
+        });
+
+        let adapterIncluded = pwr.adapter_included;
+        if (adapterIncluded === undefined || adapterIncluded === null) {
+          if (s.attrs?.power_adapter === 'not_included' || /w\/?o\s+power/i.test(s.name)) {
+            adapterIncluded = false;
+          } else if (s.attrs?.power_adapter === 'included' || /power\s+adapter/i.test(pkgText)) {
+            adapterIncluded = true;
+          } else {
+            adapterIncluded = hasIncludedBattery ? false : null;
+          }
+        }
+
+        const cordExplicitlyExcluded =
+          s.attrs?.power_adapter === 'included_no_cord' ||
+          s.attrs?.power_cord === 'not_included' ||
+          /without\s+power\s+cord/i.test(pkgText) ||
+          /no\s+power\s+cord/i.test(pkgText) ||
+          /w\/?o\s+power\s+cord/i.test(pkgText) ||
+          /power\s+cord\s+(?:sold\s+separately|not\s+included|optional|excluded)/i.test(pkgText) ||
+          /without\s+power\s+cord/i.test(pwr.adapter_spec || '') ||
+          /without\s+power\s+cord/i.test(s.name || '');
+
+        let powerCordIncluded = null;
+        if (cordExplicitlyExcluded) {
+          powerCordIncluded = false;
+        } else if (s.attrs?.power_cord === 'included') {
+          powerCordIncluded = true;
+        } else if (pkg.length > 0) {
+          const hasExplicitCord = pkg.some((item) => {
+            const itemLower = item.toLowerCase();
+            return /power\s+cord/i.test(itemLower) &&
+              !/(?:without|sold\s+separately|not\s+included|optional|no\s+|w\/o|separately)/i.test(itemLower);
+          });
+          if (hasExplicitCord) {
+            powerCordIncluded = true;
+          } else if (adapterIncluded === true) {
+            const isIntegratedPlug =
+              /universal|wall\s*mount|plug/i.test(pwr.adapter_spec || '') ||
+              /universal\s+power\s+supply/i.test(pkgText) ||
+              /(?:with\s+[^()]*|\b(?:interchangeable|multi-country|global)\s+)plugs?\b/i.test(pkgText);
+            if (isIntegratedPlug) {
+              powerCordIncluded = true;
+            } else {
+              powerCordIncluded = null;
+            }
+          }
+        }
+
+        let outOfTheBoxReady = false;
+        let readinessSummary = '';
+
+        const isDevBoard = /xiao|seeeduino|arduino/i.test(family.id) || /board|development\s+kit/i.test(s.name) || (pwr.input_voltage && /3\.7|5v/i.test(pwr.input_voltage));
+
+        if (hasIncludedBattery) {
+          outOfTheBoxReady = true;
+          readinessSummary = `随附配套电池供电（${pwr.input_connector ? '支持 ' + pwr.input_connector : '支持太阳能/USB充电'}），开箱即可直接上电运行。`;
+        } else if (adapterIncluded === false) {
+          outOfTheBoxReady = false;
+          if (isDevBoard) {
+            readinessSummary = `开发板/套件（仅含主板与配件），需通过 ${pwr.input_connector || 'USB-C'} 供电或自备外接电源/电池。`;
+          } else {
+            readinessSummary = `仅含主机，不随附电源适配器。用户买回去无法直接开机，必须加配 ${pwr.adapter_spec || '合适规格电源适配器'}。`;
+          }
+        } else if (adapterIncluded === true) {
+          if (powerCordIncluded === false) {
+            outOfTheBoxReady = false;
+            readinessSummary = `随附电源适配器（${pwr.adapter_spec || '标配'}），但不随附 AC 电源线，开箱前需自备或加配电源线。`;
+          } else if (powerCordIncluded === true) {
+            outOfTheBoxReady = true;
+            readinessSummary = `随附电源适配器与电源线（或一体式插头），开箱即用。`;
+          } else {
+            outOfTheBoxReady = false;
+            readinessSummary = `随附电源适配器（${pwr.adapter_spec || '标配'}），包装清单未明确电源线随附情况，请核对是否需自备电源线。`;
+          }
+        } else {
+          outOfTheBoxReady = false;
+          readinessSummary = pwr.input_voltage ? `供电规格: ${pwr.input_voltage} ${pwr.input_connector || ''}，请核对是否自备电源。` : '电源随附情况未声明。';
+        }
+
+        // Get matching required accessories
+        const requiredAccessories = (family.required_accessories || []).filter((acc) => {
+          if (!acc.applies_when) return true;
+          const attrVal = s.attrs?.[acc.applies_when.attr];
+          const target = acc.applies_when.value;
+          if (Array.isArray(target)) return target.includes(attrVal);
+          return attrVal === target;
+        }).map((acc) => ({
+          id: acc.id,
+          name: acc.name,
+          sku: acc.sku,
+          reason: acc.reason,
+          url: acc.url,
+        }));
+
+        return {
+          sku: s.sku,
+          model: s.model || null,
+          name: s.name,
+          url: appendUtm(s.url, {
+            source: 'sensecraft_agent',
+            medium: 'product_search',
+            campaign: family.id,
+            content: `sku_${s.sku}`,
+          }),
+          package_profile: {
+            power_adapter_included: adapterIncluded,
+            power_cord_included: powerCordIncluded,
+            out_of_the_box_ready: outOfTheBoxReady,
+            readiness_summary: readinessSummary,
+          },
+          required_accessories: requiredAccessories,
+          power: {
+            adapter_included: adapterIncluded,
+            adapter_spec: pwr.adapter_spec || null,
+            input_voltage: pwr.input_voltage || null,
+            input_connector: pwr.input_connector || null,
+          },
+          package_contents: pkg,
+          interfaces: specs.connectivity?.interfaces || family.interfaces || [],
+          io_ports: specs.io_ports || [],
+          expansion_slots: specs.expansion_slots || [],
+          ai_performance: specs.ai_performance || null,
+        };
+      }),
+    };
+  });
+
+  return createCatalogDto({
+    source: 'bundled_manifest',
+    freshness: 'FRESH',
+    records,
+    warnings: records.length === 0 ? [`未找到与 "${query}" 匹配的硬件产品或 SKU。`] : [],
+  });
+}
+
 /**
  * Queries and verifies accessories for a product family, running physical compatibility checks.
  *
  * @param {string} familyId
  * @param {Object} [options]
+/**
+ * Bazaar bulk-add-cart supports simple numeric SKUs.
+ *
+ * @param {string|null|undefined} sku
+ * @returns {boolean}
+ */
+export function isCartableSku(sku) {
+  if (!sku) return false;
+  return /^\d+$/.test(String(sku).trim());
+}
+
+/**
+ * Storefront domain per site locale (ja -> jp.seeedstudio.com, else www.seeedstudio.com).
+ *
+ * @param {string} [locale='en']
+ * @returns {string}
+ */
+export function storeBaseUrlForLocale(locale) {
+  return locale === 'ja'
+    ? 'https://jp.seeedstudio.com'
+    : 'https://www.seeedstudio.com';
+}
+
+/**
+ * Chinese locale does not check out on global store.
+ *
+ * @param {string} [locale]
+ * @returns {boolean}
+ */
+export function localeSupportsCart(locale) {
+  return locale !== 'zh-hans' && locale !== 'zh';
+}
+
+/**
+ * Builds Seeed Bazaar bulk-add-cart deep link with UTM attribution.
+ *
+ * @param {Array<{sku: string, qty: number}>} items
+ * @param {Object} [options]
+ * @param {string} [options.solutionSlug='solution']
+ * @param {string} [options.locale='en']
+ * @param {string} [options.requestId]
+ * @returns {string|null}
+ */
+export function buildBulkAddCartUrl(items, { solutionSlug = 'solution', locale = 'en', requestId = null } = {}) {
+  const validItems = (items || [])
+    .filter((it) => it && isCartableSku(it.sku) && Number.isInteger(it.qty) && it.qty > 0)
+    .map((it) => `${it.sku}:${it.qty}`);
+
+  if (validItems.length === 0) return null;
+  if (!localeSupportsCart(locale)) return null;
+
+  const reqId = requestId || `req-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  const medium = encodeURIComponent(`Seeed::Solution::${solutionSlug}::sample-purchase`);
+  const baseUrl = storeBaseUrlForLocale(locale);
+  const rawUrl = `${baseUrl}/bulk-add-cart?items=${validItems.join(',')}&requestId=${encodeURIComponent(reqId)}&c_event_medium=${medium}`;
+
+  return appendUtm(rawUrl, {
+    source: 'sensecraft_agent',
+    medium: 'solution_bom',
+    campaign: solutionSlug,
+    content: 'sample_purchase',
+  });
+}
+
+/**
+ * Evaluates whether an accessory with applies_when condition matches the selected host SKU.
+ *
+ * @param {Object} acc - Accessory definition
+ * @param {string} hostSku - Selected host SKU
+ * @param {Object} family - Product family object
+ * @returns {boolean}
+ */
+export function isAccessoryApplicable(acc, hostSku, family) {
+  if (!acc || !acc.applies_when) {
+    return true;
+  }
+  const { attr, value } = acc.applies_when;
+  if (!attr) return true;
+
+  const skuObj = (family?.skus || []).find((s) => s.sku === hostSku);
+  const actualValue = skuObj?.attrs?.[attr];
+
+  if (actualValue === undefined || actualValue === null) {
+    const fallbackValue = family?.[attr] ?? family?.physical_spec?.[attr];
+    if (fallbackValue !== undefined && fallbackValue !== null) {
+      return Array.isArray(value) ? value.includes(fallbackValue) : value === fallbackValue;
+    }
+    if (skuObj && skuObj.attrs) {
+      return false;
+    }
+    return true;
+  }
+
+  if (Array.isArray(value)) {
+    return value.includes(actualValue);
+  }
+  return value === actualValue;
+}
+
+/**
+ * Queries accessories for a given product family and evaluates compatibility.
+ *
+ * @param {string} familyId - Product family ID
+ * @param {Object} [options]
  * @param {string} [options.sku] - Specific host SKU
  * @param {string} [options.locale='zh']
+ * @param {boolean} [options.compact=false] - Return token-efficient compact payload
  * @returns {Object} Catalog DTO with structured, verified accessories
  */
-export function queryAccessories(familyId, { sku = null, locale = 'zh' } = {}) {
+export function queryAccessories(familyId, { sku = null, locale = 'zh', compact = false, category = null } = {}) {
   const core = loadKnowledgeCore();
   const family = core.product_families?.[familyId];
 
@@ -560,11 +1547,13 @@ export function queryAccessories(familyId, { sku = null, locale = 'zh' } = {}) {
       qty: acc.qty || 1,
       reason: acc.reason || 'Required for standard operation',
       applies_when: acc.applies_when || null,
-      compatibility: {
-        is_compatible: comp.isCompatible,
-        status: comp.status,
-        details: comp.dimensions,
-      },
+      compatibility: compact
+        ? { is_compatible: comp.isCompatible, status: comp.status }
+        : {
+            is_compatible: comp.isCompatible,
+            status: comp.status,
+            details: comp.dimensions,
+          },
     };
   });
 
@@ -583,25 +1572,73 @@ export function queryAccessories(familyId, { sku = null, locale = 'zh' } = {}) {
         content: `optional_${acc.id}`,
       }),
       type: acc.type || 'peripheral',
-      compatibility: {
-        is_compatible: comp.isCompatible,
-        status: comp.status,
-        details: comp.dimensions,
-      },
+      compatibility: compact
+        ? { is_compatible: comp.isCompatible, status: comp.status }
+        : {
+            is_compatible: comp.isCompatible,
+            status: comp.status,
+            details: comp.dimensions,
+          },
     };
   });
 
+  let filteredRequired = required;
+  let filteredOptional = optional;
+
+  if (category) {
+    const catTokens = String(category).toLowerCase().split(',').map((s) => s.trim()).filter(Boolean);
+    if (catTokens.length > 0) {
+      filteredRequired = required.filter((acc) => {
+        if (catTokens.includes('required')) return true;
+        if (catTokens.includes('optional')) return false;
+        const txt = [acc.id, acc.name, acc.sku, acc.category, acc.reason].join(' ').toLowerCase();
+        return catTokens.some((tok) => txt.includes(tok));
+      });
+      filteredOptional = optional.filter((acc) => {
+        if (catTokens.includes('optional')) return true;
+        if (catTokens.includes('required')) return false;
+        const txt = [acc.id, acc.name, acc.sku, acc.category, acc.type].join(' ').toLowerCase();
+        return catTokens.some((tok) => txt.includes(tok));
+      });
+    }
+  }
+
+  const hostSku = sku || family.default_sku;
+  const cartItems = [];
+  if (isCartableSku(hostSku)) {
+    cartItems.push({ sku: hostSku, qty: 1 });
+  }
+  for (const req of filteredRequired) {
+    const isApplicable = isAccessoryApplicable(req, hostSku, family);
+    req.applicable = isApplicable;
+    if (isApplicable && isCartableSku(req.sku)) {
+      cartItems.push({ sku: req.sku, qty: req.qty || 1 });
+    }
+  }
+
+  const bundleCartUrl = buildBulkAddCartUrl(cartItems, {
+    solutionSlug: family.id,
+    locale,
+  });
+
   return createCatalogDto({
     source: 'bundled_manifest',
     freshness: 'FRESH',
     records: [{
       family_id: family.id,
       host_title: family.title?.[locale] || family.title?.zh || family.title?.en,
-      host_sku: sku || family.default_sku,
+      host_sku: hostSku,
       physical_spec: hostPhysicalSpec,
+      bundle_cart_url: bundleCartUrl,
+      ...(bundleCartUrl ? {} : {
+        domestic_channel_note: locale === 'zh'
+          ? '国内采购建议通过 Seeed 官方直营店铺或授权分销商采购（非国际站美金结算）'
+          : null,
+      }),
+      ...(category ? { filtered_by_category: category } : {}),
       accessories: {
-        required,
-        optional,
+        required: filteredRequired,
+        optional: filteredOptional,
       },
     }],
   });