@seeed-studio/solution-cli 0.3.2 → 0.4.1

package/bin/cli.js

@@ -2,10 +2,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { runInstall, runStatus, runUninstall } from '../lib/installer.js';
+import { runInstall, runUpdate, listAgents, runStatus, runUninstall } from '../lib/installer.js';
 import { runDoctor } from '../lib/doctor.js';
-import { searchHub, queryProductFamily, queryAccessories, createDeploymentLockfile } from '../lib/knowledge.js';
+import { searchHub, listHub, getHubRecord, loadKnowledgeCore, queryProductFamily, searchProducts, queryAccessories, createDeploymentLockfile } from '../lib/knowledge.js';
 import { assertCompatibility } from '../lib/compatibility.js';
+import { searchGotchas } from '../lib/gotchas.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../package.json'), 'utf8'));
@@ -23,32 +24,45 @@ Usage:
 
 Commands:
   install     Inspect environment, verify/download engine, and configure AI Agent skills (default)
+  update      Check for Engine/catalog updates and synchronize all installed AI Agent skills
   status      Display current engine, solution content, and agent skills status
   doctor      Diagnose environment (platform, permissions, docker, PATH, ledger)
+  agent       Manage and list supported AI Agent skill destinations
+              Usage: solution-cli agent list [--json]
   uninstall   Cleanly remove Solution CLI skills from specified agent(s)
   hub         Search scenarios and reference designs from Seeed Solution Hub
-              Usage: solution-cli hub search <keyword> [--limit 5] [--locale zh|en] [--json]
-  product     Query product families, SKUs, and verified accessories
-              Usage: solution-cli product query <family_id> [--locale zh|en] [--json]
-                     solution-cli product accessories <family_id> [--sku <sku>] [--json]
+              Usage: solution-cli hub search <keyword> [--limit 5] [--locale zh|en|ja] [--json]
+                     solution-cli hub list [--type scenario|tech|reference_design] [--page N] [--limit 50] [--locale zh|en|ja] [--json]
+                     solution-cli hub get <id> [--type ...] [--section overview|links|description|architecture|products|deployment|playbook|integration] [--preset <id>] [--locale zh|en|ja] [--json]
+  product     Query product families, SKUs, physical interfaces, box contents, and verified accessories
+              Usage: solution-cli product search <keyword|model|sku> [--limit 5] [--locale zh|en|ja] [--json]
+                     solution-cli product query <family_id> [--locale zh|en|ja] [--json]
+                     solution-cli product accessories <family_id> [--sku <sku>] [--category <cats>] [--compact] [--json]
                      solution-cli product verify-compatibility --host <family_id> [--json]
+  gotchas     Search edge hardware and chip troubleshooting knowledge (RK3588, reCamera, Jetson, Hailo)
+              Usage: solution-cli gotchas [keyword] [--chip rk3588|recamera|jetson|hailo] [--json]
   lockfile    Create an immutable DeploymentLockfile to isolate deployment execution
               Usage: solution-cli lockfile create --solution <id> [--version <v>] [--hardware <fams>] [--json]
   help        Show this help message
 
 Options:
-  --agent <name|all>   Target agent(s): workbuddy, claude, codex, codebuddy, or all
+  --agent <name|all>   Target agent(s): workbuddy, doubao, claude, codex, codebuddy, antigravity, hermes, hermes:<profile>, or all
+  --skills-dir <path>  Install skill directly to custom directory (supports any third-party or proprietary Agent)
   -y, --yes            Accept default detected selections non-interactively
   --dry-run            Simulate operations without making changes to filesystem
   --skip-content       Skip pulling IoT solution packages from CDN
   --force              Re-download equal/older stable Engine and overwrite existing skill files, including local modifications; never downgrade a newer local Engine
   --json               Output machine-readable JSON (supported by all query/diagnostic commands)
-  --locale <zh|en>     Language for hub and product results (default: zh)
+  --compact            Output token-efficient minified response (omits verbose compatibility dimension trees)
+  --locale <zh|en|ja>  Language for hub and product results (default: zh)
   --limit <num>        Maximum results for search (default: 5)
   --engine-path <path> Use custom engine executable path
 
 Examples:
   npx @seeed-studio/solution-cli install
+  solution-cli update
+  solution-cli agent list
+  solution-cli install --skills-dir ~/.cursor/skills -y
   solution-cli hub search "跌倒"
   solution-cli product accessories recomputer_j40
   solution-cli product query sensecap_watcher --json
@@ -68,14 +82,23 @@ function parseFlags(rawArgs) {
   const usedFlags = new Set();
   const flags = {
     agent: null,
+    skillsDir: null,
     yes: false,
     dryRun: false,
     skipContent: false,
     force: false,
     json: false,
+    compact: false,
     enginePath: null,
     limit: 5,
+    page: 1,
+    type: null,
+    section: 'overview',
+    sections: null,
     locale: 'zh',
+    preset: null,
+    category: null,
+    chip: null,
     sku: null,
     host: null,
     accessory: null,
@@ -111,6 +134,7 @@ function parseFlags(rawArgs) {
     };
 
     if (valueFlag('--agent', value => { flags.agent = value; })) {
+    } else if (valueFlag('--skills-dir', value => { flags.skillsDir = value; })) {
     } else if (a === '-y' || a === '--yes') {
       usedFlags.add('--yes');
       flags.yes = true;
@@ -126,6 +150,9 @@ function parseFlags(rawArgs) {
     } else if (a === '--json') {
       usedFlags.add('--json');
       flags.json = true;
+    } else if (a === '--compact') {
+      usedFlags.add('--compact');
+      flags.compact = true;
     } else if (valueFlag('--engine-path', value => { flags.enginePath = value; })) {
     } else if (valueFlag('--limit', value => {
       if (!/^[1-9]\d*$/.test(value)) throw new CliArgumentError('--limit requires a positive integer');
@@ -133,6 +160,18 @@ function parseFlags(rawArgs) {
       if (!Number.isSafeInteger(limit)) throw new CliArgumentError('--limit is too large');
       flags.limit = limit;
     })) {
+    } else if (valueFlag('--page', value => {
+      if (!/^[1-9]\d*$/.test(value)) throw new CliArgumentError('--page requires a positive integer');
+      const page = Number(value);
+      if (!Number.isSafeInteger(page)) throw new CliArgumentError('--page is too large');
+      flags.page = page;
+    })) {
+    } else if (valueFlag('--type', value => { flags.type = value; })) {
+    } else if (valueFlag('--section', value => { flags.section = value; })) {
+    } else if (valueFlag('--sections', value => { flags.sections = value; })) {
+    } else if (valueFlag('--preset', value => { flags.preset = value; })) {
+    } else if (valueFlag('--category', value => { flags.category = value; })) {
+    } else if (valueFlag('--chip', value => { flags.chip = value; })) {
     } else if (valueFlag('--locale', value => { flags.locale = value; })) {
     } else if (valueFlag('--sku', value => { flags.sku = value; })) {
     } else if (valueFlag('--host', value => { flags.host = value; })) {
@@ -151,23 +190,42 @@ function parseFlags(rawArgs) {
 }
 
 function validatePositionals(command, positionals) {
-  if (['install', 'uninstall', 'status', 'doctor'].includes(command) && positionals.length > 0) {
+  if (['install', 'update', 'uninstall', 'status', 'doctor'].includes(command) && positionals.length > 0) {
     throw new CliArgumentError(`${command} does not accept positional arguments`);
   }
+  if (command === 'agent') {
+    const sub = positionals[0] || 'list';
+    if (sub !== 'list') {
+      throw new CliArgumentError(`Unknown agent action "${sub}". Supported: list`);
+    }
+  }
 }
 
 function validateCommandFlags(command, flags) {
   const allowed = {
-    install: ['--agent', '--yes', '--dry-run', '--skip-content', '--force', '--engine-path'],
+    install: ['--agent', '--skills-dir', '--yes', '--dry-run', '--skip-content', '--force', '--engine-path'],
+    update: ['--agent', '--skills-dir', '--yes', '--dry-run', '--skip-content', '--force', '--engine-path'],
     uninstall: ['--agent', '--dry-run', '--force'],
     status: ['--json'],
     doctor: ['--json'],
-    hub: ['--json', '--locale', '--limit'],
-    product: ['--json', '--locale', '--sku', '--host', '--accessory'],
+    agent: ['--json'],
+    hub: ['--json', '--compact', '--locale', '--limit', '--page', '--type', '--section', '--sections', '--preset'],
+    product: ['--json', '--compact', '--locale', '--sku', '--host', '--accessory', '--category', '--limit'],
+    gotchas: ['--json', '--chip'],
     lockfile: ['--json', '--solution', '--version', '--hardware'],
     help: [],
   };
-  const supported = allowed[command];
+  let supported = allowed[command];
+  if (command === 'hub') {
+    const sub = flags.positionals[0] || 'search';
+    const perSubcommand = {
+      search: ['--json', '--compact', '--locale', '--limit'],
+      list: ['--json', '--compact', '--locale', '--limit', '--page', '--type'],
+      get: ['--json', '--compact', '--locale', '--type', '--section', '--sections', '--preset'],
+    };
+    if (!perSubcommand[sub]) throw new CliArgumentError(`Unknown hub action "${sub}". Supported: search, list, get`);
+    supported = perSubcommand[sub];
+  }
   if (!supported) return;
   for (const flag of flags.usedFlags) {
     if (!supported.includes(flag)) {
@@ -176,6 +234,85 @@ function validateCommandFlags(command, flags) {
   }
 }
 
+function renderSectionOutput(r, section) {
+  if (section === 'links') {
+    const landingEntries = Object.entries(r.links?.landing || {});
+    if (landingEntries.length) landingEntries.forEach(([locale, url]) => console.log(`     Landing (${locale}): ${url}`));
+    else console.log('     Landing: unavailable');
+    console.log(`     Wiki: ${r.links?.wiki || 'unavailable'}`);
+    console.log(`     Repo: ${r.links?.repo || 'unavailable'}`);
+    console.log(`     Declared documents: ${r.links?.declared_documents?.length ? r.links.declared_documents.join(', ') : 'unavailable'}`);
+  } else if (section === 'description') {
+    console.log(`     Content locale: ${r.description?.content_locale || 'unknown'}`);
+    console.log(`     Source role: ${r.description?.source_role || 'unavailable'}`);
+    console.log(`     Source: ${r.description?.source || 'unavailable'}`);
+    if (r.description?.body) console.log(`\n${r.description.body}`);
+    else console.log('     Content: unavailable (the selected section has no body)');
+  } else if (section === 'architecture') {
+    console.log(`     Content locale: ${r.architecture?.content_locale || 'unknown'}`);
+    console.log(`     Fallback: ${r.architecture?.fallback ? 'yes' : 'no'}`);
+    console.log(`     Source role: ${r.architecture?.source_role || 'unavailable'}`);
+    if (r.architecture?.source) console.log(`     Source: ${r.architecture.source}`);
+    if (r.architecture?.intro) console.log(`\n${r.architecture.intro}`);
+    (r.architecture?.modules || []).forEach((m) => {
+      console.log(`     ${m.label || m.id || 'Architecture'}:`);
+      if (m.card_image) console.log(`       Image: ${m.card_image}`);
+      if (m.description) console.log(`       ${m.description}`);
+      if (m.body) console.log(`\n${m.body}`);
+    });
+    (r.architecture?.gallery || []).forEach((g) => console.log(`     ${g.role || 'Gallery'}: ${g.src}`));
+    if (!(r.architecture?.modules?.length || r.architecture?.gallery?.length)) console.log('     Content: unavailable (no architecture modules or gallery items)');
+  } else if (section === 'products') {
+    console.log(`     Content locale: ${r.products_content_locale || 'unknown'}`);
+    console.log(`     Source role: ${r.products_source_role || 'unavailable'}`);
+    if (!Object.keys(r.products || {}).length && !Object.keys(r.bom || {}).length) console.log('     Content: unavailable (no product or BOM entries)');
+    console.log(JSON.stringify({ products: r.products || {}, bom: r.bom || {} }, null, 2));
+  } else if (section === 'deployment') {
+    console.log(`     Content locale: ${r.deployment?.content_locale || 'unknown'}`);
+    console.log(`     Source role: ${r.deployment?.source_role || 'unavailable'}`);
+    console.log(`     Deployable: ${r.deployment?.deployable ? 'yes' : 'no'}`);
+    console.log(`     Solution: ${r.deployment?.solution_id || 'unavailable'}`);
+    if (r.deployment?.filtered_by_preset) {
+      console.log(`     \x1b[32mFiltered by Preset:\x1b[0m ${r.deployment.filtered_by_preset}`);
+    }
+    console.log(`     Presets: ${r.deployment?.presets?.length ? r.deployment.presets.map((p) => p.id || p.name || p).join(', ') : 'unavailable'}`);
+    console.log(`     Guides: ${Object.keys(r.deployment?.guides || {}).length ? JSON.stringify(r.deployment.guides) : 'unavailable'}`);
+    console.log(`     Source files: ${r.deployment?.source_files?.length ? r.deployment.source_files.join(', ') : 'unavailable'}`);
+    if (r.deployment?.guide?.body) {
+      console.log(`     Guide locale: ${r.deployment.guide.content_locale}`);
+      console.log(`\n${r.deployment.guide.body}`);
+    } else console.log('     Content: unavailable (no deployment guide body returned)');
+  } else if (section === 'playbook') {
+    console.log(`     \x1b[36m[现场工况诊断手册 (Diagnostic Playbook)]\x1b[0m`);
+    console.log(`     领域: ${r.playbook?.domain || r.title}`);
+    console.log(`     核心决断维度: ${(r.playbook?.core_dimensions || []).join(' | ')}`);
+    console.log('\n     \x1b[33m[专家工况诊断追问 (2~3问)]\x1b[0m');
+    (r.playbook?.questions || []).forEach((q, qIdx) => {
+      console.log(`     ${qIdx + 1}. \x1b[1m${q.question}\x1b[0m`);
+      if (q.rationale) console.log(`        💡 技术/商务决断理由: ${q.rationale}`);
+    });
+  } else if (section === 'integration') {
+    console.log(`     \x1b[36m[系统集成与对接规范 (Integration Contract)]\x1b[0m`);
+    console.log(`     支持协议: ${(r.integration?.protocols || []).join(', ').toUpperCase()}`);
+    console.log('\n     \x1b[33m[输入流与环境要求 (Inputs)]\x1b[0m');
+    if ((r.integration?.input_requirements || []).length === 0) {
+      console.log('       (根据具体选型接入标准 RTSP/传感器数据流)');
+    } else {
+      r.integration.input_requirements.forEach((inp) => console.log(`     - [${inp.type?.toUpperCase()}] ${inp.description}`));
+    }
+    console.log('\n     \x1b[32m[输出与数据总线 (Outputs)]\x1b[0m');
+    (r.integration?.interfaces || []).forEach((iface) => {
+      console.log(`     - \x1b[1m[${iface.protocol?.toUpperCase()}]\x1b[0m ${iface.topic || iface.endpoint || ''} ${iface.port ? `(Port: ${iface.port})` : ''}`);
+      if (iface.description) console.log(`       说明: ${iface.description}`);
+      if (iface.payload_example) console.log(`       载荷示例: ${typeof iface.payload_example === 'string' ? iface.payload_example : JSON.stringify(iface.payload_example)}`);
+    });
+    if (r.integration?.system_ingestion_guide?.length) {
+      console.log('\n     \x1b[35m[系统快速对接指引]\x1b[0m');
+      r.integration.system_ingestion_guide.forEach((g) => console.log(`     ${g}`));
+    }
+  }
+}
+
 async function main() {
   if (args.some(a => a === '--help' || a === '-h')) {
     printHelp();
@@ -187,8 +324,9 @@ async function main() {
     return;
   }
 
+  let flags = { json: args.includes('--json') };
   try {
-    const flags = parseFlags(args.slice(1));
+    flags = parseFlags(args.slice(1));
     validatePositionals(command, flags.positionals);
     validateCommandFlags(command, flags);
 
@@ -202,6 +340,28 @@ async function main() {
         await runInstall(flags);
         break;
 
+      case 'update':
+        await runUpdate({ ...flags, yes: flags.usedFlags.has('--yes') ? flags.yes : true });
+        break;
+
+      case 'agent': {
+        const list = listAgents();
+        if (flags.json) {
+          console.log(JSON.stringify({ agents: list }, null, 2));
+        } else {
+          console.log('\n🤖 Supported AI Agent Targets:\n');
+          list.forEach((a, idx) => {
+            const detectedTag = a.detected ? '\x1b[32m[Detected]\x1b[0m' : '\x1b[90m[Not Detected]\x1b[0m';
+            const installTag = a.installed ? '\x1b[36m(Installed)\x1b[0m' : '\x1b[90m(Not Installed)\x1b[0m';
+            console.log(`  ${idx + 1}. \x1b[1m${a.name}\x1b[0m (ID: ${a.id}) ${detectedTag} ${installTag}`);
+            console.log(`     Skills Dir: ${a.skillsDir}`);
+          });
+          console.log('\n💡 Tip: To install into any custom or proprietary Agent, use:');
+          console.log('   solution-cli install --skills-dir <path> -y\n');
+        }
+        break;
+      }
+
       case 'status':
         runStatus(flags);
         break;
@@ -228,32 +388,94 @@ async function main() {
 
       case 'hub': {
         const sub = flags.positionals[0] || 'search';
-        if (sub !== 'search') {
-          console.error(`Unknown hub action "${sub}". Supported: "solution-cli hub search <keyword>"`);
+        if (!['search', 'list', 'get'].includes(sub)) {
+          console.error(`Unknown hub action "${sub}". Supported: search, list, get`);
           process.exit(1);
         }
-        const query = flags.positionals.slice(1).join(' ');
-        const dto = await searchHub({ query, locale: flags.locale, limit: flags.limit });
+        if (sub === 'list' && flags.positionals.length > 1) {
+          throw new CliArgumentError('hub list does not accept positional IDs; use --type, --page, and --limit');
+        }
+        if (sub === 'get' && (flags.positionals.length !== 2 || !flags.positionals[1])) {
+          throw new CliArgumentError('hub get requires exactly one record ID');
+        }
+        let dto;
+        if (sub === 'list') {
+          const listLimit = flags.usedFlags.has('--limit') ? flags.limit : 50;
+          dto = listHub({ type: flags.type, locale: flags.locale, page: flags.page, limit: listLimit });
+        } else if (sub === 'get') {
+          const row = getHubRecord(flags.positionals[1], {
+            type: flags.type,
+            locale: flags.locale,
+            section: flags.section,
+            sections: flags.sections,
+            preset: flags.preset,
+          });
+          if (!row) {
+            console.error(`Hub record "${flags.positionals[1]}" not found in the bundled catalog.`);
+            process.exit(1);
+          }
+          const core = loadKnowledgeCore();
+          dto = {
+            records: [row],
+            source: 'bundled_manifest',
+            freshness: 'UNKNOWN',
+            dataset_version: core.dataset_version || null,
+            build_time: core.build_time || null,
+            provenance: core.provenance || null,
+            scope: 'bundled_catalog_snapshot',
+            locale: flags.locale,
+            warnings: [],
+          };
+        } else {
+          const query = flags.positionals.slice(1).join(' ');
+          dto = await searchHub({ query, locale: flags.locale, limit: flags.limit });
+        }
         if (flags.json) {
           console.log(JSON.stringify(dto, null, 2));
         } else {
-          console.log(`\n🔍 Solutions Hub Search Results for "${query}" (${dto.source}):\n`);
+          console.log(`\n🔍 Solutions Hub ${sub} (${dto.source}):\n`);
           if (dto.records.length === 0) {
             console.log('  No matching scenarios or reference designs found.');
           } else {
             dto.records.forEach((r, idx) => {
-              const tag = r.type === 'scenario' ? '\x1b[36m[Scenario]\x1b[0m' : '\x1b[35m[Reference Design]\x1b[0m';
+              const tag = r.type === 'tech' ? '\x1b[34m[Tech]\x1b[0m' : r.type === 'scenario' ? '\x1b[36m[Scenario]\x1b[0m' : '\x1b[35m[Reference Design]\x1b[0m';
               console.log(`  ${idx + 1}. ${tag} \x1b[1m${r.title}\x1b[0m (${r.id})`);
+              if (sub === 'get') {
+                const activeSections = r.sections || (r.section ? [r.section] : ['overview']);
+                activeSections.forEach((sec) => {
+                  renderSectionOutput(r, sec);
+                });
+                if (activeSections.includes('overview') && r.available_sections?.length) {
+                  console.log('\n     \x1b[36m[Available Sections & Status 渐进式目录]:\x1b[0m');
+                  r.available_sections.forEach((sec) => {
+                    const status = r.section_status?.[sec] || 'documented';
+                    const isCurrent = sec === 'overview' ? ' \x1b[32m[Current]\x1b[0m' : '';
+                    const cmd = sec === 'overview' ? `hub get ${r.id}` : `hub get ${r.id} --section ${sec}${sec === 'deployment' ? ' [--preset <id>]' : ''}`;
+                    console.log(`     - \x1b[1m${sec}\x1b[0m (${status}): ${cmd}${isCurrent}`);
+                  });
+                  console.log('     💡 批量拉取: hub get ' + r.id + ' --sections architecture,integration');
+                }
+              }
               if (r.summary) console.log(`     ${r.summary}`);
-              if (r.reference_designs?.length) console.log(`     对应参考设计: ${r.reference_designs.join(', ')}`);
+              if (r.architecture_preview?.image_url) {
+                console.log(`     官方架构图: ${r.architecture_preview.image_url}`);
+                if (r.architecture_preview.summary) console.log(`     架构拓扑: ${r.architecture_preview.summary}`);
+              }
+              if (r.landing_url) console.log(`     Landing: ${r.landing_url}`);
+              console.log(`     Scenario IDs: ${r.scenario_ids?.length ? r.scenario_ids.join(', ') : 'none'}`);
+              console.log(`     Tech IDs: ${r.technology_ids?.length ? r.technology_ids.join(', ') : 'none'}`);
+              console.log(`     Reference Design IDs: ${r.reference_designs?.length ? r.reference_designs.join(', ') : 'none'}`);
+              if (r.solution_id) console.log(`     可部署内容: ${r.solution_id}`);
               if (r.family_ids?.length) console.log(`     推荐硬件族: ${r.family_ids.join(', ')}`);
               if (r.presets?.length) console.log(`     预设模式: ${r.presets.join(', ')}`);
               if (r.wiki_url) console.log(`     开发 Wiki: ${r.wiki_url}`);
-              if (r.diagnostic_playbook?.questions?.length) {
-                console.log('     现场工况诊断提问指引:');
-                r.diagnostic_playbook.questions.forEach((q) => {
-                  console.log(`       • ${q.question} \x1b[90m(决断考量: ${q.rationale})\x1b[0m`);
-                });
+              if (r.has_playbook) console.log('     \x1b[32m现场工况诊断:\x1b[0m 可用 (使用 hub get ' + r.id + ' --section playbook 查看专业追问)');
+              if (r.available_sections?.length) {
+                const sectionSummary = r.available_sections.map((s) => {
+                  const st = r.section_status?.[s];
+                  return st && st !== 'documented' ? `${s}(${st})` : s;
+                }).join(', ');
+                console.log(`     Available Sections: ${sectionSummary}`);
               }
               console.log('');
             });
@@ -261,15 +483,115 @@ async function main() {
           if (dto.warnings.length) {
             dto.warnings.forEach((w) => console.log(`\x1b[33mNote:\x1b[0m ${w}`));
           }
+          if (sub === 'list' && dto.pagination) {
+            const next = dto.pagination.next_page;
+            console.log(`\nCatalog snapshot: total=${dto.pagination.total} returned=${dto.pagination.returned} has_more=${dto.pagination.has_more} next_page=${next ?? 'none'}`);
+            if (dto.pagination.has_more && next) {
+              const typeArg = flags.type ? ` --type ${flags.type}` : '';
+              console.log(`Next page: solution-cli hub list --locale ${flags.locale} --page ${next} --limit ${dto.pagination.limit}${typeArg}`);
+            }
+          }
         }
         break;
       }
 
       case 'product': {
-        const sub = flags.positionals[0] || 'query';
-        const familyId = flags.positionals[1] || flags.host;
+        const rawFirst = flags.positionals[0];
+        const core = loadKnowledgeCore();
+        let sub = rawFirst;
+        let queryTarget = flags.positionals[1] || flags.host;
+
+        // Auto routing: if first argument is not a known subcommand keyword
+        if (rawFirst !== 'search' && rawFirst !== 'query' && rawFirst !== 'accessories' && rawFirst !== 'verify-compatibility') {
+          if (rawFirst && core.product_families?.[rawFirst]) {
+            sub = 'query';
+            queryTarget = rawFirst;
+          } else if (rawFirst) {
+            sub = 'search';
+            queryTarget = flags.positionals.join(' ');
+          } else {
+            sub = 'query';
+          }
+        }
+        const familyId = queryTarget;
+
+        if (sub === 'search') {
+          const q = (rawFirst === 'search' ? flags.positionals.slice(1).join(' ') : queryTarget) || '';
+          if (!q.trim()) {
+            console.error('Please specify a search query (e.g. "solution-cli product search J4012 Super")');
+            process.exit(1);
+          }
+          const dto = searchProducts({ query: q, locale: flags.locale, limit: flags.limit ? parseInt(flags.limit, 10) : 5 });
+          if (flags.json) {
+            console.log(JSON.stringify(dto, null, 2));
+          } else {
+            if (dto.records.length === 0) {
+              console.log(`未找到与 "${q}" 匹配的硬件产品。`);
+            } else {
+              console.log(`\n🔍 找到 ${dto.records.length} 个匹配的硬件产品族:`);
+              dto.records.forEach((fam) => {
+                console.log(`\n======================================================================`);
+                console.log(`📦 \x1b[1m${fam.title}\x1b[0m (Family ID: \x1b[36m${fam.family_id}\x1b[0m)`);
+                if (fam.summary) console.log(`   💡 简介: ${fam.summary}`);
+                if (fam.interfaces?.length) console.log(`   🔌 板载接口 (Interfaces): ${fam.interfaces.join(', ')}`);
+                if (fam.protocols?.length) console.log(`   📡 通信协议 (Protocols): ${fam.protocols.join(', ')}`);
+
+                if (fam.supported_scenarios?.length) {
+                  console.log(`   🚀 官方落地方案 (该设备可以干嘛):`);
+                  fam.supported_scenarios.slice(0, 5).forEach((sc) => {
+                    const scTitle = sc.title?.[flags.locale] || sc.title?.zh || sc.title?.en || sc.id;
+                    console.log(`      - \x1b[32m${scTitle}\x1b[0m (ID: ${sc.id})`);
+                  });
+                }
+
+                if (fam.matched_skus?.length) {
+                  console.log(`   🎯 具体型号 (SKU) & 开箱配置:`);
+                  fam.matched_skus.forEach((s) => {
+                    console.log(`      --------------------------------------------------`);
+                    console.log(`      SKU: \x1b[1m${s.sku}\x1b[0m | 型号: ${s.model || '标准款'} | 名称: ${s.name}`);
+                    if (s.ai_performance) console.log(`      ⚡ 算力: ${s.ai_performance}`);
 
-        if (sub === 'query') {
+                    // Power & Readiness summary
+                    if (s.package_profile?.readiness_summary) {
+                      const icon = s.package_profile.out_of_the_box_ready ? '\x1b[32m✔ 开箱即用\x1b[0m' : '\x1b[33m⚠️ 无法直接开机/需配件\x1b[0m';
+                      console.log(`      ⚡ 开箱状态: ${icon}`);
+                      console.log(`         ${s.package_profile.readiness_summary}`);
+                    } else if (s.power.adapter_included === true) {
+                      console.log(`      🔌 电源适配器: \x1b[32m✔ 随附\x1b[0m (${s.power.adapter_spec || s.power.input_voltage || '标配适配器'})`);
+                    } else if (s.power.adapter_included === false) {
+                      console.log(`      🔌 电源适配器: \x1b[31m✖ 不随附\x1b[0m (需要自备或加配: ${s.power.adapter_spec || s.power.input_voltage || '需外接电源'})`);
+                    } else if (s.power.input_voltage) {
+                      console.log(`      🔌 供电要求: ${s.power.input_voltage} ${s.power.input_connector || ''}`);
+                    }
+
+                    // Required accessories if any
+                    if (s.required_accessories?.length) {
+                      console.log(`      🔌 必需加配配件:`);
+                      s.required_accessories.forEach((acc) => {
+                        console.log(`         • \x1b[1m${acc.name}\x1b[0m (SKU: ${acc.sku || 'N/A'})${acc.reason ? ` - ${acc.reason}` : ''}`);
+                      });
+                    }
+
+                    // Package contents
+                    if (s.package_contents?.length) {
+                      console.log(`      📦 包装清单 (Box Contents):`);
+                      s.package_contents.forEach((item) => console.log(`         • ${item}`));
+                    }
+
+                    // I/O ports
+                    if (s.io_ports?.length) {
+                      const portSummary = s.io_ports.map((p) => `${p.count}x ${p.type}${p.notes ? ` (${p.notes})` : ''}`).join(', ');
+                      console.log(`      🖥️ 外设端口 (I/O Ports): ${portSummary}`);
+                    }
+
+                    if (s.url) console.log(`      🔗 购买链接: ${s.url}`);
+                  });
+                }
+              });
+              console.log(`\n💡 提示: 查看该设备必需与推荐配件请使用: solution-cli product accessories <family_id>`);
+            }
+          }
+        } else if (sub === 'query') {
           if (!familyId) {
             console.error('Please specify a product family ID (e.g. "solution-cli product query recomputer_j40")');
             process.exit(1);
@@ -283,9 +605,23 @@ async function main() {
               console.log(`Product family "${familyId}" not found.`);
             } else {
               console.log(`\n📦 Product Family: \x1b[1m${fam.title}\x1b[0m (${fam.family_id})`);
+              if (fam.summary) console.log(`  Summary: ${fam.summary}`);
               console.log(`  Default SKU: ${fam.default_sku || 'N/A'}`);
               console.log(`  Regions: ${(fam.regions || []).join(', ') || 'Global'}`);
               console.log(`  SKUs Available: ${fam.skus_count}`);
+              if (fam.interfaces?.length) {
+                console.log(`  Interfaces: ${fam.interfaces.join(', ')}`);
+              }
+              if (fam.protocols?.length) {
+                console.log(`  Protocols: ${fam.protocols.join(', ')}`);
+              }
+              if (fam.supported_scenarios?.length) {
+                console.log(`  Supported Scenarios:`);
+                fam.supported_scenarios.slice(0, 5).forEach((sc) => {
+                  const scTitle = sc.title?.[flags.locale] || sc.title?.zh || sc.title?.en || sc.id;
+                  console.log(`    - ${scTitle} (${sc.id})`);
+                });
+              }
               if (fam.physical_spec?.power_input) {
                 const p = fam.physical_spec.power_input;
                 console.log(`  Power Spec: ${p.voltage_v || ''}V ${p.min_current_a || ''}A (${p.connector}) ${p.polarity || ''}`);
@@ -299,7 +635,12 @@ async function main() {
             console.error('Please specify a product family ID (e.g. "solution-cli product accessories recomputer_j40")');
             process.exit(1);
           }
-          const dto = queryAccessories(familyId, { sku: flags.sku, locale: flags.locale });
+          const dto = queryAccessories(familyId, {
+            sku: flags.sku,
+            locale: flags.locale,
+            compact: flags.compact,
+            category: flags.category,
+          });
           if (flags.json) {
             console.log(JSON.stringify(dto, null, 2));
           } else {
@@ -308,6 +649,9 @@ async function main() {
               console.log(`Product family "${familyId}" not found.`);
             } else {
               console.log(`\n📦 Verified Accessories for \x1b[1m${record.host_title}\x1b[0m (${record.family_id}):`);
+              if (record.filtered_by_category) {
+                console.log(`  \x1b[32m[Filtered by category]:\x1b[0m ${record.filtered_by_category}`);
+              }
               console.log(`  Host Default SKU: ${record.host_sku}`);
               if (record.physical_spec?.power_input) {
                 const p = record.physical_spec.power_input;
@@ -316,7 +660,7 @@ async function main() {
 
               console.log('\n  \x1b[33m[REQUIRED (必需配件)]\x1b[0m');
               if (record.accessories.required.length === 0) {
-                console.log('    (无强制单独采购的配件)');
+                console.log('    (无符合条件的必需配件)');
               } else {
                 record.accessories.required.forEach((acc) => {
                   const stat = acc.compatibility.is_compatible ? '\x1b[32m✔\x1b[0m' : '\x1b[31m✖\x1b[0m';
@@ -328,7 +672,7 @@ async function main() {
 
               console.log('\n  \x1b[36m[OPTIONAL (推荐选配)]\x1b[0m');
               if (record.accessories.optional.length === 0) {
-                console.log('    (无选配项)');
+                console.log('    (无符合条件的选配项)');
               } else {
                 record.accessories.optional.slice(0, 10).forEach((acc) => {
                   const stat = acc.compatibility.is_compatible ? '\x1b[32m✔\x1b[0m' : '\x1b[31m✖\x1b[0m';
@@ -336,6 +680,16 @@ async function main() {
                   if (acc.url) console.log(`      购买链接: ${acc.url}`);
                 });
               }
+
+              if (record.bundle_cart_url) {
+                console.log('\n  \x1b[35m[一键批量加购 (Bundle Cart)]\x1b[0m');
+                console.log(`    主机与必需配件已打包，点击直达购物车一键结算:`);
+                console.log(`    \x1b[4m${record.bundle_cart_url}\x1b[0m`);
+              } else if (record.domestic_channel_note) {
+                console.log('\n  \x1b[35m[国内采购渠道说明]\x1b[0m');
+                console.log(`    ${record.domestic_channel_note}`);
+              }
+
               console.log('');
             }
           }
@@ -361,6 +715,35 @@ async function main() {
         break;
       }
 
+      case 'gotchas': {
+        const query = flags.positionals.join(' ');
+        const results = searchGotchas({ query, chip: flags.chip });
+        if (flags.json) {
+          console.log(JSON.stringify({
+            total: results.length,
+            query: query || null,
+            chip: flags.chip || null,
+            records: results,
+          }, null, 2));
+        } else {
+          console.log(`\n🩺 Edge Hardware Gotchas & Troubleshooting (${results.length} found):\n`);
+          if (results.length === 0) {
+            console.log('  No matching troubleshooting cards found.');
+          } else {
+            results.forEach((rec, idx) => {
+              console.log(`  ${idx + 1}. \x1b[1m[${rec.chip.toUpperCase()}] ${rec.title}\x1b[0m`);
+              console.log(`     现象 (Symptom): ${rec.symptoms}`);
+              console.log(`     根因 (Root Cause): ${rec.root_cause}`);
+              console.log('     \x1b[32m解决方案:\x1b[0m');
+              rec.solution.forEach((s) => console.log(`       ${s}`));
+              if (rec.forbidden) console.log(`     \x1b[31m⚠️ 严禁行为:\x1b[0m ${rec.forbidden}`);
+              console.log('');
+            });
+          }
+        }
+        break;
+      }
+
       case 'lockfile': {
         const sub = flags.positionals[0] || 'create';
         if (sub !== 'create') {
@@ -391,8 +774,18 @@ async function main() {
         process.exit(1);
     }
   } catch (err) {
-    console.error(`\n\x1b[31mError:\x1b[0m ${err.message}\n`);
-    process.exitCode = err instanceof CliArgumentError ? 2 : 1;
+    const isSectionError = err?.name === 'HubSectionError';
+    const isArgError = err instanceof CliArgumentError || isSectionError;
+    if (flags?.json) {
+      console.log(JSON.stringify({
+        error: err.message,
+        ...(err.suggestion ? { suggestion: err.suggestion } : {}),
+        ...(err.allowed_sections ? { allowed_sections: err.allowed_sections } : {}),
+      }, null, 2));
+    } else {
+      console.error(`\n\x1b[31mError:\x1b[0m ${err.message}\n`);
+    }
+    process.exitCode = isArgError ? 2 : 1;
   }
 }