@seeed-studio/solution-cli 0.3.2 → 0.4.0

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, 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,44 @@ 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]
+              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, and verified accessories
               Usage: solution-cli product query <family_id> [--locale zh|en] [--json]
-                     solution-cli product accessories <family_id> [--sku <sku>] [--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, 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 +81,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 +133,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 +149,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 +159,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 +189,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'],
+    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 +233,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 +323,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 +339,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 +387,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,6 +482,14 @@ 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;
       }
@@ -299,7 +528,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 +542,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 +553,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 +565,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 +573,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 +608,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 +667,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;
   }
 }
 

package/catalog/client-config.json

@@ -1,10 +1,10 @@
 {
   "$schema": "https://spec.seeedstudio.com/schemas/v2/client-config.json",
-  "baked_at": "2026-10-13T09:54:46.940Z",
+  "baked_at": "2026-10-13T11:34:09.048Z",
   "typesense": {
     "host": "https://rel-search.seeedstudio.com",
     "search_key_solution": "dNsKBp0Pepdz9tvyIY1O92EMOM00XCHv",
     "search_key_reference_design": "rEy4VhZnqEmrduFG2e8uvfWMz5ZzXhjb",
-    "search_key_purchase_profile": "YrowCXcDOGTt9KedslTEmeY0ZJEhlBml"
+    "search_key_purchase_profile": ""
   }
 }