@seeed-studio/solution-cli 0.4.0 → 0.4.1

package/docs/cli-guide.md

@@ -28,24 +28,26 @@ Agent 的默认工作流是“先咨询，再选型，再检查，最后在用
 
 ## 2. 安装与 Agent 技能挂载
 
-### 2.1 按需精准安装（推荐：只针对当前 Agent 安装，避免环境污染）
+### 2.1 按需精准安装（推荐：npm 全局安装并挂载，避免 PATH 缺失报错）
 
 你可以直接复制下表中对应的专属命令发给对应的 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 极简执行**：例如在豆包工作中直接发送：*“请帮我运行：`npx -y @seeed-studio/solution-cli install --agent doubao`”*，AI 将直接在后台非交互执行并自动就绪。
-> - **严格隔离**：指定 `--agent <id>` 时，安装器依据 ledger 记录仅写入该 Agent 对应的目录，绝不修改其他 Agent 的技能或配置。
+> - **为什么推荐 npm 全局安装？** 将 `solution-cli` 加入全局 PATH，AI Agent 在后续对话中调用方案/硬件查询时直接本地毫秒级响应，避免因 PATH 缺失触发 `command not found`。
+> - **发给 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>`。
 
 ### 2.2 本地源码部署与定制开发 (Local Deployment)
 
@@ -59,6 +61,27 @@ node bin/cli.js install --agent <doubao|claude|codex|antigravity|codebuddy>
 node bin/cli.js install --skills-dir ~/.cursor/skills
 ```
 
+省略 `--agent` 时，终端交互运行会进入选择器；非交互运行会安装到已检测的宿主，未检测到宿主时会选择全部宿主。建议始终明确指定当前 Agent。重复执行会复用相同或更新的签名 Engine、升级旧版本，并保留用户修改的 Skill。`--force` 会覆盖已有 Skill 修改，只在用户明确要求时使用。
+
+安装完成后刷新宿主的 Skill 列表或完全退出并重新打开 Agent 应用，确认宿主的实际 Skill 列表中已出现 `solution-cli`，再新建会话直接描述需求。若宿主未自动发现技能，发送：“请使用 solution-cli Skill，先查询方案，再告诉我缺哪些部署信息。”安装器只写入被选中的宿主。
+
+### 2.3 全局安装与 Profile
+
+需要长期使用 `solution-cli` 命令时可以全局安装：
+
+```bash
+npm install -g --registry=https://registry.npmjs.org/ @seeed-studio/solution-cli@latest
+solution-cli status
+```
+
+不想修改全局 npm 环境时，使用 `npx --package` 临时调用：
+
+```bash
+npx -y --registry=https://registry.npmjs.org/ --package=@seeed-studio/solution-cli@latest solution-cli hub search "农业" --json
+```
+
+Hermes 的已配置 profile 可通过 `--agent hermes:<profile>` 选择（安装、更新、卸载通用）：具名 profile 使用 `<root>/profiles/<profile>/skills/solution-cli`，`hermes:default` 使用 `<root>/skills/solution-cli`；`<root>` 是 Hermes 安装根目录。Profile ID 为 1–64 位小写字母、数字、`_` 或 `-`，以字母或数字开头。安装器仅复制 Skill，不创建或切换 profile。
+
 ## 3. 核心功能、使用方法与具体产出
 
 安装后可直接在命令行运行 `solution-cli` 与 `sensecraft-engine`；若未执行安装，也可随时通过 `npx -y @seeed-studio/solution-cli <command>` 免安装即用。

package/lib/agent.js

@@ -5,6 +5,53 @@ import readline from 'node:readline';
 import crypto from 'node:crypto';
 import { loadLedger } from './ledger.js';
 
+// Match Hermes' native data home and get_default_hermes_root() semantics.
+function getHermesPaths() {
+  const home = os.homedir();
+  const suffix = process.env.HERMES_DATA_DIR_SUFFIX || '';
+  const nativeHome = process.platform === 'win32'
+    ? path.join(process.env.LOCALAPPDATA?.trim() || path.join(home, 'AppData', 'Local'), `hermes${suffix}`)
+    : path.join(home, `.hermes${suffix}`);
+  const expand = value => value.replace(/\$(\w+)|\$\{([^}]+)\}/g,
+    (match, bare, braced) => process.env[bare || braced] ?? match)
+    .replace(/^~(?=$|[\\/])/, () => home);
+  const activeHome = path.resolve(expand(process.env.HERMES_HOME?.trim() || nativeHome));
+  const real = value => fs.existsSync(value) ? fs.realpathSync(value) : path.resolve(value);
+  const relative = path.relative(real(nativeHome), real(activeHome));
+  const inNativeHome = relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+  const root = inNativeHome ? nativeHome
+    : path.basename(path.dirname(activeHome)) === 'profiles' ? path.dirname(path.dirname(activeHome)) : activeHome;
+  return { activeHome, root };
+}
+
+function hermesTarget(id = 'hermes') {
+  const { activeHome, root } = getHermesPaths();
+  let targetHome = activeHome;
+  if (id !== 'hermes') {
+    const profile = id.slice('hermes:'.length);
+    if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(profile)) {
+      throw new Error(`Invalid Hermes profile: "${profile}". Use 1-64 lowercase letters, numbers, '-' or '_', starting with a letter or number.`);
+    }
+    targetHome = profile === 'default' ? root : path.join(root, 'profiles', profile);
+  }
+  return {
+    id,
+    name: id === 'hermes' ? 'Hermes Agent' : `Hermes Agent (${id.slice(7)})`,
+    homeDirs: [targetHome],
+    getSkillsDir: () => path.join(targetHome, 'skills'),
+  };
+}
+
+function scanAgent(agent) {
+  const skillsDir = agent.getSkillsDir();
+  return {
+    ...agent,
+    detected: agent.homeDirs.some(dir => fs.existsSync(dir)) || fs.existsSync(skillsDir),
+    installed: fs.existsSync(path.join(skillsDir, 'solution-cli', 'SKILL.md')),
+    skillsDir,
+  };
+}
+
 export function getKnownAgents() {
   const home = os.homedir();
 
@@ -68,7 +115,8 @@ export function getKnownAgents() {
       name: 'Google Antigravity (AGY)',
       homeDirs: [path.join(home, '.gemini', 'config'), path.join(home, '.gemini', 'antigravity-cli')],
       getSkillsDir: () => path.join(home, '.gemini', 'config', 'skills')
-    }
+    },
+    hermesTarget()
   ];
 }
 
@@ -78,6 +126,10 @@ export function scanLocalAgents() {
   try {
     const ledger = loadLedger();
     for (const [targetId, inst] of Object.entries(ledger?.installations || {})) {
+      if (targetId.startsWith('hermes:') && inst && !agents.some(a => a.id === targetId)) {
+        const target = hermesTarget(targetId);
+        if (fs.existsSync(path.join(target.getSkillsDir(), 'solution-cli', 'SKILL.md'))) agents.push(target);
+      }
       if (targetId.startsWith('custom_') && inst) {
         const skillsDir = inst.skills_dir || (inst.target_dir ? path.dirname(inst.target_dir) : (inst.targetDir ? path.dirname(inst.targetDir) : null));
         if (skillsDir && fs.existsSync(skillsDir) && !agents.some(a => a.id === targetId)) {
@@ -92,17 +144,7 @@ export function scanLocalAgents() {
     }
   } catch {}
 
-  return agents.map(a => {
-    const skillsDir = a.getSkillsDir();
-    const detected = a.homeDirs.some(dir => fs.existsSync(dir)) || fs.existsSync(skillsDir);
-    const installed = fs.existsSync(path.join(skillsDir, 'solution-cli', 'SKILL.md'));
-    return {
-      ...a,
-      detected,
-      installed,
-      skillsDir
-    };
-  });
+  return agents.map(scanAgent);
 }
 
 export function formatAgentList(scannedAgents) {
@@ -147,8 +189,16 @@ export async function promptAgentSelection(scannedAgents, cliArg, autoYes = fals
     if (cliArg.toLowerCase() === 'all') {
       return scannedAgents;
     }
-    const requested = cliArg.split(',').map(s => s.trim().toLowerCase());
-    const matched = scannedAgents.filter(a => requested.includes(a.id) || (a.aliases && a.aliases.some(alias => requested.includes(alias))));
+    const requested = cliArg.split(',').map(s => s.trim());
+    // Validate profile IDs before normalizing other hosts or accepting a partial match.
+    for (const id of requested) {
+      if (id.toLowerCase().startsWith('hermes:')) {
+        const target = scanAgent(hermesTarget(`hermes:${id.slice(7)}`));
+        if (!scannedAgents.some(a => a.id === target.id)) scannedAgents.push(target);
+      }
+    }
+    const normalized = requested.map(id => id.toLowerCase());
+    const matched = scannedAgents.filter(a => normalized.includes(a.id) || a.aliases?.some(alias => normalized.includes(alias)));
     if (matched.length === 0) {
       throw new Error(`No matching agents for: "${cliArg}". Available: ${scannedAgents.map(a => a.id).join(', ')}`);
     }

package/lib/knowledge.js

@@ -711,6 +711,35 @@ export function getHubRecord(id, { type = null, locale = 'zh', section = null, s
   return row;
 }
 
+/**
+ * Detects if a search query matches known hardware product families, models, or SKUs.
+ *
+ * @param {string[]} tokens
+ * @param {string} query
+ * @param {Object} core
+ * @returns {string|null} Helpful redirect note if hardware is detected
+ */
+function detectHardwareIntent(tokens, query, core) {
+  if (!tokens || tokens.length === 0) return null;
+  const families = Object.values(core?.product_families || {});
+  const matchedHw = families.find((fam) => {
+    const fid = (fam.id || '').toLowerCase();
+    const zh = (fam.title?.zh || '').toLowerCase();
+    const en = (fam.title?.en || '').toLowerCase();
+    if (tokens.some((t) => fid.includes(t) || zh.includes(t) || en.includes(t))) return true;
+    return (fam.skus || []).some((s) => {
+      const sNum = String(s.sku || '').toLowerCase();
+      const sModel = String(s.model || '').toLowerCase();
+      const sName = String(s.name || '').toLowerCase();
+      return tokens.some((t) => sNum === t || (sModel && sModel.includes(t)) || sName.includes(t));
+    });
+  });
+  if (matchedHw) {
+    return `💡 提示: 检测到硬件设备/型号关键词 "${query}"。若需查询该硬件的物理接口、包装清单（是否带电源）或官方落地应用方案，请使用: solution-cli product search "${query}"`;
+  }
+  return null;
+}
+
 /**
  * Searches Seeed Solutions Hub scenarios and reference designs.
  *
@@ -725,6 +754,7 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
   locale = normalizedLocale;
   if (!Number.isSafeInteger(limit) || limit < 1 || limit > 200) throw new Error('Limit must be an integer from 1 to 200.');
   const qLower = (query || '').toLowerCase().trim();
+  const tokens = qLower.split(/\s+/).filter(Boolean);
   const clientConfig = loadClientConfig();
   const host = process.env.TYPESENSE_HOST || clientConfig?.typesense?.host || 'https://rel-search.seeedstudio.com';
   const keySolution = process.env.TYPESENSE_SEARCH_KEY_SOLUTION || process.env.TYPESENSE_SEARCH_KEY || clientConfig?.typesense?.search_key_solution;
@@ -896,7 +926,6 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
 
       // If one collection returned results but the other was unavailable/failed/empty, supplement from bundled catalog
       if ((onlineScenarios.length > 0 && onlineRefDesigns.length === 0) || (onlineRefDesigns.length > 0 && onlineScenarios.length === 0)) {
-        const tokens = qLower.split(/\s+/).filter(Boolean);
         if (onlineScenarios.length === 0) {
           for (const s of core.scenarios || []) {
             if (s.published === false || s.visibility === 'staging' || s.visibility === 'draft') continue;
@@ -939,12 +968,17 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
       }
 
       if (mergedRecords.length > 0) {
+        const onlineWarnings = ['Online search results are partial and do not replace the bundled catalog; use hub get for verified section content.'];
+        const hwHint = detectHardwareIntent(tokens, query, core);
+        if (hwHint) {
+          onlineWarnings.push(hwHint);
+        }
         return createCatalogDto({
           source: (onlineScenarios.some(r => r.source === 'typesense') || onlineRefDesigns.some(r => r.source === 'typesense')) ? 'typesense' : 'bundled_manifest',
           freshness: 'UNKNOWN',
           datasetVersion: core.dataset_version,
           scope: 'online_partial_with_bundled_fallback',
-          warnings: ['Online search results are partial and do not replace the bundled catalog; use hub get for verified section content.'],
+          warnings: onlineWarnings,
           records: mergedRecords.map(compactSearchRecord),
         });
       }
@@ -958,8 +992,6 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
   const matchedScenarios = [];
   const matchedRefDesigns = [];
 
-  const tokens = qLower.split(/\s+/).filter(Boolean);
-
   for (const s of core.scenarios || []) {
     if (s.published === false || s.visibility === 'staging' || s.visibility === 'draft') continue;
     const locKey = locale === 'zh' ? 'zh_hans' : locale;
@@ -1042,17 +1074,25 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
     }
   }
 
+  const warnings = process.env.SENSECRAFT_OFFLINE_ONLY
+    ? ['Offline-only mode: displaying the verified bundled catalog; no online request was attempted.']
+    : ((keySolution || keyRefDesign)
+      ? ['Online Typesense request timed out or returned no hits. Displaying verified local catalog.']
+      : ['No Typesense API key configured or baked. Displaying verified local catalog.']);
+
+  // Detect if query looks like a hardware device, model, or SKU keyword
+  const hwHint = detectHardwareIntent(tokens, query, core);
+  if (hwHint && (combined.length === 0 || (combined[0] && combined[0].score < 2))) {
+    warnings.push(hwHint);
+  }
+
   return createCatalogDto({
     source: 'bundled_manifest',
     freshness: 'UNKNOWN',
     datasetVersion: core.dataset_version,
     scope: 'bundled_catalog_snapshot',
     records: combined.map(compactSearchRecord),
-    warnings: process.env.SENSECRAFT_OFFLINE_ONLY
-      ? ['Offline-only mode: displaying the verified bundled catalog; no online request was attempted.']
-      : ((keySolution || keyRefDesign)
-        ? ['Online Typesense request timed out or returned no hits. Displaying verified local catalog.']
-        : ['No Typesense API key configured or baked. Displaying verified local catalog.']),
+    warnings,
   });
 }
 
@@ -1083,8 +1123,12 @@ export function queryProductFamily(familyId, { locale = 'zh' } = {}) {
     records: [{
       family_id: family.id,
       title: family.title?.[locale] || family.title?.zh || family.title?.en || family.id,
+      summary: family.summary || null,
       default_sku: family.default_sku,
       regions: family.regions || [],
+      interfaces: family.interfaces || [],
+      protocols: family.protocols || [],
+      supported_scenarios: family.supported_scenarios || [],
       skus_count: (family.skus || []).length,
       skus: (family.skus || []).slice(0, 10).map((s) => ({
         ...s,
@@ -1102,6 +1146,261 @@ export function queryProductFamily(familyId, { locale = 'zh' } = {}) {
   });
 }
 
+/**
+ * Searches product families and member SKUs by keywords, model name, interface, or SKU number.
+ *
+ * @param {Object} options
+ * @param {string} options.query - Free text query (e.g. "J4012 Super", "RS485", "114110314")
+ * @param {'zh' | 'en' | 'ja'} [options.locale='zh']
+ * @param {number} [options.limit=5]
+ * @returns {Object} Catalog DTO
+ */
+export function searchProducts({ query = '', locale = 'zh', limit = 5 } = {}) {
+  const core = loadKnowledgeCore();
+  const families = Object.values(core.product_families || {});
+  const qLower = (query || '').toLowerCase().trim();
+  const tokens = qLower.split(/\s+/).filter(Boolean);
+
+  if (tokens.length === 0) {
+    return createCatalogDto({
+      source: 'bundled_manifest',
+      freshness: 'FRESH',
+      records: [],
+      warnings: ['Query cannot be empty.'],
+    });
+  }
+
+  const matches = [];
+
+  for (const fam of families) {
+    let score = 0;
+    const titleZh = (fam.title?.zh || '').toLowerCase();
+    const titleEn = (fam.title?.en || '').toLowerCase();
+    const fid = (fam.id || '').toLowerCase();
+    const famHaystack = [fid, titleZh, titleEn].join(' ');
+
+    // Check SKU matching
+    const matchedSkus = [];
+    for (const sku of fam.skus || []) {
+      const sNum = String(sku.sku || '').toLowerCase();
+      const sModel = String(sku.model || '').toLowerCase();
+      const sName = String(sku.name || '').toLowerCase();
+      // Strip negative clauses like "（Super Mode NOT Supported)" from positive keyword matching
+      const sNameClean = sName
+        .replace(/[（\(][^）\)]*not\s+supported[^）\)]*[）\)]?/gi, '')
+        .replace(/super\s+mode\s+not\s+supported/gi, '')
+        .replace(/\b(?:not\s+supported|unsupported)\b/gi, '');
+      const sAttrs = Object.values(sku.attrs || {}).map((v) => String(v).toLowerCase());
+      const skuIfaces = (sku.specs?.connectivity?.interfaces || sku.interfaces || []).map((i) => String(i).toLowerCase());
+      const skuProtos = (sku.specs?.connectivity?.protocols || sku.protocols || []).map((p) => String(p).toLowerCase());
+      const skuIoPorts = (sku.specs?.io_ports || []).map((p) => String(p.type || '').toLowerCase());
+
+      const skuHaystack = [sNum, sModel, sNameClean, ...sAttrs, ...skuIfaces, ...skuProtos, ...skuIoPorts].join(' ');
+      const isSingleSkuLookup = tokens.length === 1 && (sNum === tokens[0] || sNum === qLower);
+      const skuMatchesAll = tokens.every((t) => skuHaystack.includes(t));
+      const singleTokenHit = tokens.length === 1 && ((sModel && sModel.includes(tokens[0])) || skuHaystack.includes(tokens[0]));
+
+      if (isSingleSkuLookup || skuMatchesAll) {
+        matchedSkus.push(sku);
+      } else if (tokens.length > 1) {
+        const combinedMatchesAll = tokens.every((t) => (famHaystack + ' ' + skuHaystack).includes(t));
+        const nonFamTokens = tokens.filter((t) => !famHaystack.includes(t));
+        if (combinedMatchesAll && (nonFamTokens.length === 0 || nonFamTokens.every((t) => skuHaystack.includes(t)))) {
+          matchedSkus.push(sku);
+        }
+      } else if (singleTokenHit) {
+        matchedSkus.push(sku);
+      }
+    }
+
+    // Require all query tokens to be satisfied either in the family or across member SKUs
+    const famMatchesAll = tokens.every((t) => famHaystack.includes(t));
+    const allTokensSatisfiedInFamily = tokens.every((t) => {
+      return famHaystack.includes(t) || (fam.skus || []).some((s) => {
+        const sNameClean = String(s.name || '')
+          .toLowerCase()
+          .replace(/[（\(][^）\)]*not\s+supported[^）\)]*[）\)]?/gi, '')
+          .replace(/super\s+mode\s+not\s+supported/gi, '');
+        const sIfaces = (s.specs?.connectivity?.interfaces || s.interfaces || []).map((i) => String(i).toLowerCase());
+        const sProtos = (s.specs?.connectivity?.protocols || s.protocols || []).map((p) => String(p).toLowerCase());
+        const sPorts = (s.specs?.io_ports || []).map((p) => String(p.type || '').toLowerCase());
+        return [s.sku, s.model, sNameClean, ...Object.values(s.attrs || {}), ...sIfaces, ...sProtos, ...sPorts].join(' ').toLowerCase().includes(t);
+      });
+    });
+
+    if (!allTokensSatisfiedInFamily) {
+      continue;
+    }
+
+    if (matchedSkus.length > 0 || famMatchesAll) {
+      score = matchedSkus.length * 10 + (famMatchesAll ? 5 : 0);
+      matches.push({
+        family: fam,
+        score,
+        matchedSkus: matchedSkus.length > 0 ? matchedSkus : (fam.skus || []).slice(0, 3),
+      });
+    }
+  }
+
+  matches.sort((a, b) => b.score - a.score);
+
+  const records = matches.slice(0, limit).map(({ family, matchedSkus }) => {
+    return {
+      family_id: family.id,
+      title: family.title?.[locale] || family.title?.zh || family.title?.en || family.id,
+      summary: family.summary || null,
+      default_sku: family.default_sku,
+      interfaces: family.interfaces || [],
+      protocols: family.protocols || [],
+      supported_scenarios: family.supported_scenarios || [],
+      matched_skus: matchedSkus.map((s) => {
+        const specs = s.specs || {};
+        const pwr = specs.power || {};
+        const pkg = specs.package_contents || [];
+        const pkgText = pkg.join(' ').toLowerCase();
+
+        // Require positive evidence of an included operational battery (not just battery_powered capability or RTC battery)
+        const hasIncludedBattery = pkg.some((item) => {
+          if (!/\bbattery\b/i.test(item)) return false;
+          if (/(?:not\s+included|sold\s+separately|cr1220|rtc|coin)/i.test(item)) return false;
+          if (/(?:without|w\/o|no|exclude[ds]?)\s+[^()]*\bbattery/i.test(item)) return false;
+          return true;
+        });
+
+        let adapterIncluded = pwr.adapter_included;
+        if (adapterIncluded === undefined || adapterIncluded === null) {
+          if (s.attrs?.power_adapter === 'not_included' || /w\/?o\s+power/i.test(s.name)) {
+            adapterIncluded = false;
+          } else if (s.attrs?.power_adapter === 'included' || /power\s+adapter/i.test(pkgText)) {
+            adapterIncluded = true;
+          } else {
+            adapterIncluded = hasIncludedBattery ? false : null;
+          }
+        }
+
+        const cordExplicitlyExcluded =
+          s.attrs?.power_adapter === 'included_no_cord' ||
+          s.attrs?.power_cord === 'not_included' ||
+          /without\s+power\s+cord/i.test(pkgText) ||
+          /no\s+power\s+cord/i.test(pkgText) ||
+          /w\/?o\s+power\s+cord/i.test(pkgText) ||
+          /power\s+cord\s+(?:sold\s+separately|not\s+included|optional|excluded)/i.test(pkgText) ||
+          /without\s+power\s+cord/i.test(pwr.adapter_spec || '') ||
+          /without\s+power\s+cord/i.test(s.name || '');
+
+        let powerCordIncluded = null;
+        if (cordExplicitlyExcluded) {
+          powerCordIncluded = false;
+        } else if (s.attrs?.power_cord === 'included') {
+          powerCordIncluded = true;
+        } else if (pkg.length > 0) {
+          const hasExplicitCord = pkg.some((item) => {
+            const itemLower = item.toLowerCase();
+            return /power\s+cord/i.test(itemLower) &&
+              !/(?:without|sold\s+separately|not\s+included|optional|no\s+|w\/o|separately)/i.test(itemLower);
+          });
+          if (hasExplicitCord) {
+            powerCordIncluded = true;
+          } else if (adapterIncluded === true) {
+            const isIntegratedPlug =
+              /universal|wall\s*mount|plug/i.test(pwr.adapter_spec || '') ||
+              /universal\s+power\s+supply/i.test(pkgText) ||
+              /(?:with\s+[^()]*|\b(?:interchangeable|multi-country|global)\s+)plugs?\b/i.test(pkgText);
+            if (isIntegratedPlug) {
+              powerCordIncluded = true;
+            } else {
+              powerCordIncluded = null;
+            }
+          }
+        }
+
+        let outOfTheBoxReady = false;
+        let readinessSummary = '';
+
+        const isDevBoard = /xiao|seeeduino|arduino/i.test(family.id) || /board|development\s+kit/i.test(s.name) || (pwr.input_voltage && /3\.7|5v/i.test(pwr.input_voltage));
+
+        if (hasIncludedBattery) {
+          outOfTheBoxReady = true;
+          readinessSummary = `随附配套电池供电（${pwr.input_connector ? '支持 ' + pwr.input_connector : '支持太阳能/USB充电'}），开箱即可直接上电运行。`;
+        } else if (adapterIncluded === false) {
+          outOfTheBoxReady = false;
+          if (isDevBoard) {
+            readinessSummary = `开发板/套件（仅含主板与配件），需通过 ${pwr.input_connector || 'USB-C'} 供电或自备外接电源/电池。`;
+          } else {
+            readinessSummary = `仅含主机，不随附电源适配器。用户买回去无法直接开机，必须加配 ${pwr.adapter_spec || '合适规格电源适配器'}。`;
+          }
+        } else if (adapterIncluded === true) {
+          if (powerCordIncluded === false) {
+            outOfTheBoxReady = false;
+            readinessSummary = `随附电源适配器（${pwr.adapter_spec || '标配'}），但不随附 AC 电源线，开箱前需自备或加配电源线。`;
+          } else if (powerCordIncluded === true) {
+            outOfTheBoxReady = true;
+            readinessSummary = `随附电源适配器与电源线（或一体式插头），开箱即用。`;
+          } else {
+            outOfTheBoxReady = false;
+            readinessSummary = `随附电源适配器（${pwr.adapter_spec || '标配'}），包装清单未明确电源线随附情况，请核对是否需自备电源线。`;
+          }
+        } else {
+          outOfTheBoxReady = false;
+          readinessSummary = pwr.input_voltage ? `供电规格: ${pwr.input_voltage} ${pwr.input_connector || ''}，请核对是否自备电源。` : '电源随附情况未声明。';
+        }
+
+        // Get matching required accessories
+        const requiredAccessories = (family.required_accessories || []).filter((acc) => {
+          if (!acc.applies_when) return true;
+          const attrVal = s.attrs?.[acc.applies_when.attr];
+          const target = acc.applies_when.value;
+          if (Array.isArray(target)) return target.includes(attrVal);
+          return attrVal === target;
+        }).map((acc) => ({
+          id: acc.id,
+          name: acc.name,
+          sku: acc.sku,
+          reason: acc.reason,
+          url: acc.url,
+        }));
+
+        return {
+          sku: s.sku,
+          model: s.model || null,
+          name: s.name,
+          url: appendUtm(s.url, {
+            source: 'sensecraft_agent',
+            medium: 'product_search',
+            campaign: family.id,
+            content: `sku_${s.sku}`,
+          }),
+          package_profile: {
+            power_adapter_included: adapterIncluded,
+            power_cord_included: powerCordIncluded,
+            out_of_the_box_ready: outOfTheBoxReady,
+            readiness_summary: readinessSummary,
+          },
+          required_accessories: requiredAccessories,
+          power: {
+            adapter_included: adapterIncluded,
+            adapter_spec: pwr.adapter_spec || null,
+            input_voltage: pwr.input_voltage || null,
+            input_connector: pwr.input_connector || null,
+          },
+          package_contents: pkg,
+          interfaces: specs.connectivity?.interfaces || family.interfaces || [],
+          io_ports: specs.io_ports || [],
+          expansion_slots: specs.expansion_slots || [],
+          ai_performance: specs.ai_performance || null,
+        };
+      }),
+    };
+  });
+
+  return createCatalogDto({
+    source: 'bundled_manifest',
+    freshness: 'FRESH',
+    records,
+    warnings: records.length === 0 ? [`未找到与 "${query}" 匹配的硬件产品或 SKU。`] : [],
+  });
+}
+
 /**
  * Queries and verifies accessories for a product family, running physical compatibility checks.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@seeed-studio/solution-cli",
-  "version": "0.4.0",
-  "description": "Installer for the Rust deployment engine and Solution CLI Agent skills (Work Buddy, Claude Code, Codex, CodeBuddy)",
+  "version": "0.4.1",
+  "description": "Installer for the Rust deployment engine and Solution CLI Agent skills (Doubao Work, WorkBuddy, Claude Code, Codex, CodeBuddy, Hermes)",
   "type": "module",
   "main": "./lib/installer.js",
   "bin": {
@@ -22,7 +22,7 @@
   "scripts": {
     "build": "node scripts/bake-client-config.mjs",
     "prepack": "node scripts/bake-client-config.mjs",
-    "test": "node --test tests/cli.test.mjs",
+    "test": "node --test",
     "install:self": "node bin/cli.js install",
     "status": "node bin/cli.js status",
     "doctor": "node bin/cli.js doctor"
@@ -36,6 +36,7 @@
     "claude-code",
     "codex",
     "codebuddy",
+    "hermes",
     "skills",
     "edge-ai",
     "jetson",

package/skills/solution-cli/SKILL.md

@@ -64,14 +64,24 @@ path is usable only when the matching signed local content is present; otherwise
 report the source asset as unavailable instead of treating the URL as an image that
 has been reviewed.
 
-## Workflow Routing & Progressive Disclosure
+## Workflow Routing & Intent Classification
+
+```mermaid
+flowchart TD
+  User["用户提问: 'J4012 Super 包含电源吗？买回去能直接用吗？'"] --> AgentIntent{"意图识别 (SKILL.md)"}
+  AgentIntent -- "问行业/业务方案 (跌倒/农业/质检/选型)" --> HubSearch["hub search '<方案关键词>'"]
+  AgentIntent -- "问硬件单品/型号/包装清单/电源/接口/能干嘛" --> ProdSearch["product search '<型号/SKU>'"]
+  HubSearch -- "误把硬件当方案搜" --> Fallback["Fallback: 检测到硬件型号，引导使用 product search"]
+  ProdSearch --> ClearOutput["直出: 电源随附情况 + 开箱即用判定 + 必选配件 + 接口 + 落地场景"]
+```
 
-Do NOT read all reference files at once. Determine the user's workflow state and intent, then load **at most ONE** reference file on demand:
+Do NOT read all reference files at once. Determine the user's workflow state and intent, then execute the corresponding command and load **at most ONE** reference file on demand:
 
 | User State & Intent | Reference to Load | Primary CLI Tool to Call | Guardrails & Forbidden Actions |
 |---|---|---|---|
-| **DISCOVERY / CONSULT**<br>“我想做防跌倒监控”、“有智慧农场方案吗” | `references/consult-and-select.md` | `solution-cli hub search "<keyword>" --json`, then `hub get <id> --sections architecture,playbook --json` | **DO NOT run deploy**; search exposes `available_sections` and evidence status (`documented`/`generic`/`inferred`). Batch fetch architecture and playbook in 1 roundtrip. |
-| **PROCUREMENT / VERIFY_BOM**<br>“买什么硬件？”、“J4012 需要配什么配件？” | `references/hardware-bom.md` | `solution-cli product accessories <id> [--category <power,camera>] --compact --json` | **DO NOT fabricate** third-party SKUs or prices. Always distinguish REQUIRED vs OPTIONAL accessories. Use `--compact` and `--category` to save tokens. |
+| **HARDWARE_SPEC / BOX_CONTENTS / POWER_READINESS**<br>“J4012 Super 包含电源吗？”、“盒子里有什么”、“带不带电源”、“买回去能否直接用/能否开箱即用”、“发货清单”、“有哪些接口”、“能干嘛” | `references/hardware-bom.md` | `solution-cli product search "<型号/SKU/关键词>" --json` | **STRICT HARD REDLINE**: 严禁凭常识臆测硬件包材（如擅自推测 Super 版本带电源）或谎称没有清单。包装随附情况、电源线适配器状态、开箱即用性必须严格以 `product search` 返回的 `package_profile`、`package_contents` 和 `interfaces` 为准！回答“设备能干嘛”直接使用返回的 `supported_scenarios`。 |
+| **DISCOVERY / CONSULT**<br>“我想做防跌倒监控”、“有智慧农场方案吗”、“怎么做园区安防” | `references/consult-and-select.md` | `solution-cli hub search "<keyword>" --json`, then `hub get <id> --sections architecture,playbook --json` | **DO NOT run deploy**; search exposes `available_sections` and evidence status (`documented`/`generic`/`inferred`). 若返回 warning 提示包含硬件关键词，立即按提示切换至 `product search`。 |
+| **PROCUREMENT / VERIFY_BOM**<br>“买什么硬件？”、“J4012 需要配什么配件？”、“推荐镜头/天线” | `references/hardware-bom.md` | `solution-cli product accessories <id> [--category <power,camera>] --compact --json` | **DO NOT fabricate** third-party SKUs or prices. Always distinguish REQUIRED vs OPTIONAL accessories. Use `--compact` and `--category` to save tokens. |
 | **ONBOARDING / PRECHECK**<br>“设备到了，插上了网线/USB”、“环境自检”、“发现新设备” | `references/diagnose.md` & `references/device-management.md#0` | `solution-cli doctor` / `sensecraft-engine device scan` | **Early & Proactive**: Check device firmware & drivers early. Intercept and prompt for reCamera firmware/patch or SBC env fixes before deploy. |
 | **DEPLOYING / APPLY**<br>“开始安装”、“部署 fall_detection” | `references/deploy.md` | `solution-cli hub get <id> --section deployment --preset <id> --json` then `sensecraft-engine deploy <id>` | **DEPLOYMENT CRITICAL SECTION**: Zero external commercial queries allowed during apply. Filter guide with `--preset` to reduce token bloat. |
 | **INTEGRATION / INGESTION**<br>“怎么接到我们系统”、“MQTT主题是什么”、“Webhook格式”、“接入 Home Assistant” | `references/device-management.md#5` | `solution-cli hub get <id> --section integration --json` | **System Ingestion**: Provide exact MQTT topics, payload schemas, Webhook endpoints, and port mappings directly from verified integration contract. Batch with `--sections architecture,integration` if needed. |