@seeed-studio/solution-cli 0.4.0 → 0.4.2

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` (及 `~/.agents/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();
 
@@ -12,8 +59,19 @@ export function getKnownAgents() {
     {
       id: 'doubao',
       name: '豆包工作 (Doubao Work)',
-      homeDirs: [path.join(home, '.doubao')],
-      getSkillsDir: () => path.join(home, '.doubao', 'skills')
+      homeDirs: [path.join(home, 'Doubao'), path.join(home, '.doubao')],
+      getSkillsDir: () => {
+        const pDoubao = path.join(home, 'Doubao', 'skills');
+        const pAgents = path.join(home, '.agents', 'skills');
+        const pLegacy = path.join(home, '.doubao', 'skills');
+        if (fs.existsSync(path.join(pDoubao, 'solution-cli', 'SKILL.md'))) return pDoubao;
+        if (fs.existsSync(path.join(pAgents, 'solution-cli', 'SKILL.md'))) return pAgents;
+        if (fs.existsSync(path.join(pLegacy, 'solution-cli', 'SKILL.md'))) return pLegacy;
+        if (fs.existsSync(path.join(home, 'Doubao'))) return pDoubao;
+        if (fs.existsSync(path.join(home, '.agents'))) return pAgents;
+        if (fs.existsSync(path.join(home, '.doubao'))) return pLegacy;
+        return pDoubao;
+      }
     },
     {
       id: 'workbuddy',
@@ -68,7 +126,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 +137,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 +155,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 +200,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/installer.js

@@ -241,6 +241,20 @@ export async function runInstall(options = {}) {
       recordInstallation(a.id, a.skillsDir, destDir, engineVersion, filesWritten);
       logger(`  ✔ Skill successfully installed to: ${destDir}`);
       installedAgents.push({ id: a.id, name: a.name, path: destDir });
+
+      // For doubao agent, ensure secondary scanning directory ~/.agents/skills has symlink if possible
+      if (a.id === 'doubao') {
+        try {
+          const secondarySkills = path.join(os.homedir(), '.agents', 'skills');
+          const secondaryDest = path.join(secondarySkills, SKILL_DIR_NAME);
+          if (path.resolve(a.skillsDir) !== path.resolve(secondarySkills)) {
+            if (fs.existsSync(secondarySkills) && !fs.existsSync(secondaryDest)) {
+              fs.symlinkSync(destDir, secondaryDest, 'junction');
+              logger(`  ✔ Created compatibility link for Doubao: ${secondaryDest} -> ${destDir}`);
+            }
+          }
+        } catch {}
+      }
     }
   });
 

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.2",
+  "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",