@seeed-studio/solution-cli 0.3.1 → 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'));
@@ -15,41 +16,52 @@ const command = args[0] || 'install';
 
 function printHelp() {
   console.log(`
-SenseCraft Solution CLI & Skill Toolset (${pkg.name})
+Solution CLI & Agent Skill Toolset (${pkg.name})
 
 Usage:
   npx @seeed-studio/solution-cli [command] [options]
   solution-cli [command] [options]
-  sensecraft-solution-cli [command] [options]
 
 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)
-  uninstall   Cleanly remove SenseCraft skills from specified agent(s)
+  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
@@ -58,84 +70,297 @@ Examples:
 `);
 }
 
+class CliArgumentError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CliArgumentError';
+  }
+}
+
 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,
     solution: null,
     version: '1.0.0',
     hardware: null,
+    positionals: [],
+    usedFlags,
   };
 
   for (let i = 0; i < rawArgs.length; i++) {
     const a = rawArgs[i];
-    if (a === '--agent' && rawArgs[i + 1]) {
-      flags.agent = rawArgs[++i];
-    } else if (a.startsWith('--agent=')) {
-      flags.agent = a.split('=')[1];
+    const valueFlag = (name, setter) => {
+      const inlinePrefix = `${name}=`;
+      if (a.startsWith(inlinePrefix)) {
+        const value = a.slice(inlinePrefix.length);
+        if (!value) throw new CliArgumentError(`${name} requires a value`);
+        usedFlags.add(name);
+        setter(value);
+        return true;
+      }
+      if (a === name) {
+        const value = rawArgs[i + 1];
+        if (!value || value.startsWith('-')) {
+          throw new CliArgumentError(`${name} requires a value`);
+        }
+        usedFlags.add(name);
+        setter(value);
+        i += 1;
+        return true;
+      }
+      return false;
+    };
+
+    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;
     } else if (a === '--dry-run') {
+      usedFlags.add('--dry-run');
       flags.dryRun = true;
     } else if (a === '--skip-content') {
+      usedFlags.add('--skip-content');
       flags.skipContent = true;
     } else if (a === '--force') {
+      usedFlags.add('--force');
       flags.force = true;
     } else if (a === '--json') {
+      usedFlags.add('--json');
       flags.json = true;
-    } else if (a === '--engine-path' && rawArgs[i + 1]) {
-      flags.enginePath = rawArgs[++i];
-    } else if (a === '--limit' && rawArgs[i + 1]) {
-      flags.limit = parseInt(rawArgs[++i], 10) || 5;
-    } else if (a === '--locale' && rawArgs[i + 1]) {
-      flags.locale = rawArgs[++i];
-    } else if (a === '--sku' && rawArgs[i + 1]) {
-      flags.sku = rawArgs[++i];
-    } else if (a === '--host' && rawArgs[i + 1]) {
-      flags.host = rawArgs[++i];
-    } else if (a === '--accessory' && rawArgs[i + 1]) {
-      flags.accessory = rawArgs[++i];
-    } else if (a === '--solution' && rawArgs[i + 1]) {
-      flags.solution = rawArgs[++i];
-    } else if (a === '--version' && rawArgs[i + 1]) {
-      flags.version = rawArgs[++i];
-    } else if (a === '--hardware' && rawArgs[i + 1]) {
-      flags.hardware = rawArgs[++i];
+    } 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');
+      const limit = Number(value);
+      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; })) {
+    } else if (valueFlag('--accessory', value => { flags.accessory = value; })) {
+    } else if (valueFlag('--solution', value => { flags.solution = value; })) {
+    } else if (valueFlag('--version', value => { flags.version = value; })) {
+    } else if (valueFlag('--hardware', value => { flags.hardware = value; })) {
+    } else if (a.startsWith('-')) {
+      throw new CliArgumentError(`Unknown option "${a}"`);
+    } else {
+      flags.positionals.push(a);
     }
   }
 
   return flags;
 }
 
-async function main() {
-  const flags = parseFlags(args.slice(1));
+function validatePositionals(command, positionals) {
+  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`);
+    }
+  }
+}
 
-  if (command === 'help' || command === '--help' || command === '-h') {
+function validateCommandFlags(command, flags) {
+  const allowed = {
+    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'],
+    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: [],
+  };
+  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)) {
+      throw new CliArgumentError(`${flag} is not supported for ${command}`);
+    }
+  }
+}
+
+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();
-    process.exit(0);
+    return;
   }
 
   if (command === '--version' || command === '-v') {
     console.log(pkg.version);
-    process.exit(0);
+    return;
   }
 
+  let flags = { json: args.includes('--json') };
   try {
+    flags = parseFlags(args.slice(1));
+    validatePositionals(command, flags.positionals);
+    validateCommandFlags(command, flags);
+
+    if (command === 'help') {
+      printHelp();
+      return;
+    }
+
     switch (command) {
       case 'install':
         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;
@@ -145,7 +370,7 @@ async function main() {
         if (flags.json) {
           console.log(JSON.stringify(report, null, 2));
         } else {
-          console.log('\n🩺 SenseCraft Doctor Environment Report:\n');
+          console.log('\n🩺 Solution CLI Doctor Environment Report:\n');
           report.checks.forEach(c => {
             const symbol = c.status === 'ok' ? '\x1b[32m✔\x1b[0m' : c.status === 'warn' ? '\x1b[33m⚠️\x1b[0m' : '\x1b[31m✖\x1b[0m';
             console.log(`  ${symbol} ${c.title}`);
@@ -161,33 +386,95 @@ async function main() {
         break;
 
       case 'hub': {
-        const sub = args[1] || 'search';
-        if (sub !== 'search') {
-          console.error(`Unknown hub action "${sub}". Supported: "solution-cli hub search <keyword>"`);
+        const sub = flags.positionals[0] || 'search';
+        if (!['search', 'list', 'get'].includes(sub)) {
+          console.error(`Unknown hub action "${sub}". Supported: search, list, get`);
           process.exit(1);
         }
-        const query = args.slice(2).filter((a) => !a.startsWith('-')).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('');
             });
@@ -195,13 +482,21 @@ 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 = args[1] || 'query';
-        const familyId = args.slice(2).find((a) => !a.startsWith('-')) || flags.host;
+        const sub = flags.positionals[0] || 'query';
+        const familyId = flags.positionals[1] || flags.host;
 
         if (sub === 'query') {
           if (!familyId) {
@@ -233,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 {
@@ -242,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;
@@ -250,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';
@@ -262,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';
@@ -270,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('');
             }
           }
@@ -295,8 +608,37 @@ 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 = args[1] || 'create';
+        const sub = flags.positionals[0] || 'create';
         if (sub !== 'create') {
           console.error(`Unknown lockfile action "${sub}". Supported: "solution-cli lockfile create"`);
           process.exit(1);
@@ -325,8 +667,18 @@ async function main() {
         process.exit(1);
     }
   } catch (err) {
-    console.error(`\n\x1b[31mError:\x1b[0m ${err.message}\n`);
-    process.exit(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;
   }
 }