@seeed-studio/solution-cli 0.4.0 → 0.4.1

package/README.md

@@ -4,22 +4,25 @@ Install the signed Rust deployment engine and the `solution-cli` AI Agent Skill
 
 ## 1. Quick Start: Install to Your Agent (快速安装与宿主配置)
 
-**按需安装到当前使用的 AI Agent**（避免全量污染）。直接复制对应命令发给你的 AI 助手，或在终端执行：
+**推荐方式：npm 全局安装并挂载到指定 Agent**
+（将 `solution-cli` 注册到系统全局 PATH，Agent 在对话中调用方案/硬件查询毫秒级响应，避免因 PATH 缺失导致的报错重试）：
 
-| 目标 AI 宿主 | 专属一键安装命令（直接复制发给 AI 或在终端运行） | 技能挂载路径 |
+| 目标 AI 宿主 | 专属安装命令（直接复制发给 AI 或在终端运行） | 技能挂载路径 |
 |---|---|---|
-| **豆包工作 (Doubao Work)** | `npx -y @seeed-studio/solution-cli install --agent doubao` | `~/.doubao/skills` |
-| **WorkBuddy** | `npx -y @seeed-studio/solution-cli install --agent workbuddy` | `~/.workbuddy/skills` |
-| **Claude Code** | `npx -y @seeed-studio/solution-cli install --agent claude` | `~/.claude/skills` |
-| **OpenAI Codex** | `npx -y @seeed-studio/solution-cli install --agent codex` | `~/.agents/skills` 或 `~/.codex/skills` |
-| **Google Antigravity** | `npx -y @seeed-studio/solution-cli install --agent antigravity` | `~/.gemini/config/skills` |
-| **CodeBuddy** | `npx -y @seeed-studio/solution-cli install --agent codebuddy` | `~/.codebuddy/skills` |
-| **全部 Agent (全量检测)** | `npx -y @seeed-studio/solution-cli install --agent all` | 上述全部已检测目录 |
-| **自定义路径 (如 Cursor)** | `npx -y @seeed-studio/solution-cli install --skills-dir <路径>` | `<自定义路径>/solution-cli` |
+| **豆包工作 (Doubao Work)** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent doubao` | `~/.doubao/skills` |
+| **Claude Code** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent claude` | `~/.claude/skills` |
+| **OpenAI Codex** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent codex` | `~/.agents/skills` 或 `~/.codex/skills` |
+| **Google Antigravity** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent antigravity` | `~/.gemini/config/skills` |
+| **WorkBuddy** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent workbuddy` | `~/.workbuddy/skills` |
+| **CodeBuddy** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent codebuddy` | `~/.codebuddy/skills` |
+| **Hermes Agent** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent hermes` | `$HERMES_HOME/skills` (默认 `~/.hermes/skills`) |
+| **全部 Agent (全量检测)** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent all` | 上述全部已检测目录 |
+| **自定义路径 (如 Cursor)** | `npm install -g @seeed-studio/solution-cli && solution-cli install --skills-dir <路径>` | `<自定义路径>/solution-cli` |
 
 > [!TIP]
-> - **发给 AI 助手**：直接复制上表中对应的专属命令发给你的 AI（例如对豆包说：*“请帮我运行：`npx -y @seeed-studio/solution-cli install --agent doubao`”*），AI 即可在后台全自动执行完成。
-> - **精准隔离**：指定 `--agent <id>` 时，安装器仅写入该 Agent 对应的目录，绝不修改或触碰其他 Agent 环境。
+> - **为什么使用 `npm install -g`？** 全局安装后，系统内已有 `solution-cli` 命令。AI Agent 在后续对话中调用方案与硬件查询无需每次通过网络重新下载包，避免产生 `command not found: solution-cli` 报错。
+> - **发给 AI 助手**：直接复制上表中对应的专属命令发给你的 AI 助手（例如对豆包说：*“请帮我运行：`npm install -g @seeed-studio/solution-cli && solution-cli install --agent doubao`”*）。
+> - **免全局安装（npx 备选）**：若无系统全局 npm 写入权限，仍可使用 npx 免全局安装：`npx -y @seeed-studio/solution-cli install --agent <id>`。
 > - **国内镜像延迟排查**：若遇 npm 同步延迟，可在命令末尾加上 `--registry=https://registry.npmjs.org/`。
 
 ### 开发者本地源码部署

package/bin/cli.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runInstall, runUpdate, listAgents, runStatus, runUninstall } from '../lib/installer.js';
 import { runDoctor } from '../lib/doctor.js';
-import { searchHub, listHub, getHubRecord, loadKnowledgeCore, 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';
 
@@ -34,8 +34,9 @@ Commands:
               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]
+  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)
@@ -45,7 +46,7 @@ Commands:
   help        Show this help message
 
 Options:
-  --agent <name|all>   Target agent(s): workbuddy, doubao, claude, codex, codebuddy, antigravity, 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
@@ -209,7 +210,7 @@ function validateCommandFlags(command, flags) {
     doctor: ['--json'],
     agent: ['--json'],
     hub: ['--json', '--compact', '--locale', '--limit', '--page', '--type', '--section', '--sections', '--preset'],
-    product: ['--json', '--compact', '--locale', '--sku', '--host', '--accessory', '--category'],
+    product: ['--json', '--compact', '--locale', '--sku', '--host', '--accessory', '--category', '--limit'],
     gotchas: ['--json', '--chip'],
     lockfile: ['--json', '--solution', '--version', '--hardware'],
     help: [],
@@ -495,10 +496,102 @@ async function main() {
       }
 
       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 (sub === 'query') {
+                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}`);
+
+                    // 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);
@@ -512,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 || ''}`);