@seeed-studio/solution-cli 0.3.2 → 0.4.1

package/lib/agent.js

@@ -2,17 +2,72 @@ import os from 'node:os';
 import path from 'node:path';
 import fs from 'node:fs';
 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();
 
   return [
+    {
+      id: 'doubao',
+      name: '豆包工作 (Doubao Work)',
+      homeDirs: [path.join(home, '.doubao')],
+      getSkillsDir: () => path.join(home, '.doubao', 'skills')
+    },
     {
       id: 'workbuddy',
-      name: 'Work Buddy / Workbody',
+      aliases: ['workbody'],
+      name: 'WorkBuddy / Workbody',
       homeDirs: [path.join(home, '.workbuddy'), path.join(home, '.workbody')],
       getSkillsDir: () => {
-        // Check where an existing installation might already be
         const p1 = path.join(home, '.workbuddy', 'skills');
         const p2 = path.join(home, '.workbody', 'skills');
         if (fs.existsSync(path.join(p1, 'solution-cli', 'SKILL.md'))) return p1;
@@ -60,48 +115,102 @@ 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()
   ];
 }
 
 export function scanLocalAgents() {
   const agents = getKnownAgents();
-  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
-    };
-  });
+
+  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)) {
+          agents.push({
+            id: targetId,
+            name: `Custom Agent (${skillsDir})`,
+            homeDirs: [skillsDir],
+            getSkillsDir: () => skillsDir,
+          });
+        }
+      }
+    }
+  } catch {}
+
+  return agents.map(scanAgent);
 }
 
-export async function promptAgentSelection(scannedAgents, cliArg, autoYes = false) {
+export function formatAgentList(scannedAgents) {
+  return scannedAgents.map(a => ({
+    id: a.id,
+    name: a.name,
+    detected: a.detected,
+    installed: a.installed,
+    skillsDir: a.skillsDir,
+  }));
+}
+
+export async function promptAgentSelection(scannedAgents, cliArg, autoYes = false, skillsDir = null) {
+  // If custom skillsDir is specified, inject a custom target
+  if (skillsDir) {
+    const resolvedDir = path.resolve(skillsDir);
+    const dirHash = crypto.createHash('sha256').update(resolvedDir).digest('hex').slice(0, 8);
+    const customId = `custom_${dirHash}`;
+    const customTarget = {
+      id: customId,
+      name: `Custom Agent (${resolvedDir})`,
+      skillsDir: resolvedDir,
+      detected: true,
+      installed: fs.existsSync(path.join(resolvedDir, 'solution-cli', 'SKILL.md')),
+      homeDirs: [resolvedDir],
+      getSkillsDir: () => resolvedDir,
+    };
+    if (!cliArg) {
+      return [customTarget];
+    }
+    // Avoid duplicate if already scanned from ledger
+    const existingIdx = scannedAgents.findIndex(a => a.id === customId);
+    if (existingIdx >= 0) {
+      scannedAgents[existingIdx] = customTarget;
+    } else {
+      scannedAgents.push(customTarget);
+    }
+  }
+
   // If explicitly specified in CLI flags
   if (cliArg) {
     if (cliArg.toLowerCase() === 'all') {
       return scannedAgents;
     }
-    const requested = cliArg.split(',').map(s => s.trim().toLowerCase());
-    const matched = scannedAgents.filter(a => requested.includes(a.id));
+    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(', ')}`);
     }
     return matched;
   }
 
-  // Non-interactive check (CI / piped / daemon)
+  // Non-interactive check (CI / piped / daemon / AI Agent subprocess)
   const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
 
   if (!isInteractive) {
-    if (autoYes) {
-      const detectedOnly = scannedAgents.filter(a => a.detected);
-      return detectedOnly.length > 0 ? detectedOnly : scannedAgents.slice(0, 1);
-    }
-    throw new Error('Non-interactive environment detected. Please specify --agent <workbuddy|claude|codex|codebuddy|all> or pass -y.');
+    const detectedOnly = scannedAgents.filter(a => a.detected);
+    return detectedOnly.length > 0 ? detectedOnly : scannedAgents;
   }
 
   if (autoYes) {

package/lib/catalog-dto.js

@@ -13,6 +13,10 @@ export const SCHEMA_URL = 'https://spec.seeedstudio.com/schemas/v2/catalog-dto.j
  * @param {'FRESH' | 'STALE' | 'UNKNOWN'} [options.freshness='FRESH']
  * @param {string} [options.datasetVersion='2026-10-13.1']
  * @param {Array} options.records
+ * @param {Object} [options.pagination]
+ * @param {string} [options.scope]
+ * @param {string} [options.locale]
+ * @param {Object} [options.provenance]
  * @param {Object} [options.fieldCompleteness]
  * @param {Array<string>} [options.warnings=[]]
  * @returns {Object} Validated Catalog DTO
@@ -22,10 +26,14 @@ export function createCatalogDto({
   freshness = 'FRESH',
   datasetVersion = '2026-10-13.1',
   records = [],
+  pagination = null,
+  scope = null,
+  locale = null,
+  provenance = null,
   fieldCompleteness = { spec: true, compatibility: true, offer: source === 'typesense' },
   warnings = [],
 }) {
-  return {
+  const dto = {
     $schema: SCHEMA_URL,
     schema_version: SCHEMA_VERSION,
     dataset_version: datasetVersion,
@@ -37,6 +45,11 @@ export function createCatalogDto({
     records: Array.isArray(records) ? records : [],
     warnings: Array.isArray(warnings) ? warnings : [],
   };
+  if (pagination) dto.pagination = pagination;
+  if (scope) dto.scope = scope;
+  if (locale) dto.locale = locale;
+  if (provenance) dto.provenance = provenance;
+  return dto;
 }
 
 /**

package/lib/doctor.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { getPlatformInfo, getEngineBinDir, getEngineBinaryPath, getConfiguredEnginePath, getContentDir } from './platform.js';
-import { verifyEngineBinary } from './detector.js';
+import { verifyEngineBinary, detectDesktopApp } from './detector.js';
 import { loadLedger, computeFileHash } from './ledger.js';
 
 export function runDoctor() {
@@ -166,6 +166,24 @@ export function runDoctor() {
     });
   }
 
+  // Check 8: Desktop App (GUI)
+  const app = detectDesktopApp();
+  if (app.detected) {
+    checks.push({
+      id: 'desktop_app',
+      status: 'ok',
+      title: 'SenseCraft Solution Desktop App (GUI)',
+      detail: `Detected at ${app.appPath || app.binPath} (v${app.version || 'installed'})`
+    });
+  } else {
+    checks.push({
+      id: 'desktop_app',
+      status: 'ok',
+      title: 'SenseCraft Solution Desktop App (GUI)',
+      detail: 'Not detected (optional). For visual dashboard & GUI workflows, download at https://sensecraft.seeed.cc/download'
+    });
+  }
+
   const overall = checks.some(c => c.status === 'fail')
     ? 'fail'
     : checks.some(c => c.status === 'warn')

package/lib/downloader.js

@@ -281,3 +281,27 @@ export function pullSolutionContent(binPath, onProgress = () => {}) {
     return { success: false, warning: msg };
   }
 }
+
+export function updateSolutionContent(binPath, onProgress = () => {}) {
+  const contentDir = path.join(getScHome(), 'content', 'solutions');
+  const isEmptyStore = !fs.existsSync(contentDir) || fs.readdirSync(contentDir).filter(f => !f.startsWith('.')).length === 0;
+
+  if (isEmptyStore) {
+    onProgress('Initial solution content store is empty; performing full initial pull...');
+    return pullSolutionContent(binPath, onProgress);
+  }
+
+  onProgress('Updating official solution definitions from CDN (sensecraft-engine content update)...');
+  try {
+    execFileSync(binPath, ['content', 'update'], {
+      encoding: 'utf8',
+      timeout: 120000,
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    onProgress('Solution content successfully updated to latest.');
+    return { success: true };
+  } catch (err) {
+    onProgress('Notice: incremental update fell back to full pull.');
+    return pullSolutionContent(binPath, onProgress);
+  }
+}

package/lib/gotchas.js

@@ -0,0 +1,126 @@
+/**
+ * @file gotchas.js
+ * Edge hardware & chip troubleshooting knowledge base for Solution CLI.
+ */
+
+export const GOTCHAS_DATABASE = [
+  {
+    id: 'rk3588_npu_device_missing',
+    chip: 'rk3588',
+    title: 'RK3588/RK3576 NPU 设备节点缺失或无权访问 (/dev/rknn)',
+    keywords: ['rk3588', 'rk3576', 'rknn', '/dev/rknn', 'npu', 'permission denied', 'no such file'],
+    symptoms: '容器内运行推理时报错 "cannot open /dev/rknn" 或 "Permission denied"',
+    root_cause: '宿主机未加载 rknpu 内核模块，或者 Docker 容器启动时未正确挂载 /dev/rknn 设备节点及配置 udev 权限。',
+    solution: [
+      '1. 检查宿主机内核节点：ls -l /dev/rknn (若不存在，执行 sudo modprobe rknpu)',
+      '2. 赋予设备访问权限：sudo chmod 666 /dev/rknn',
+      '3. Docker 启动或 Compose 配置中必须显式透传设备：',
+      '   devices:\n     - /dev/rknn:/dev/rknn\n     - /dev/dma_heap:/dev/dma_heap',
+      '4. 检查驱动日志：dmesg | grep -i rknpu'
+    ],
+    forbidden: '不要在容器内尝试执行 apt install 重新安装原厂内核 BSP，底层驱动必须依赖宿主机内核。'
+  },
+  {
+    id: 'rk3588_docker_nftables_conflict',
+    chip: 'rk3588',
+    title: 'Rockchip Ubuntu Docker 网络互通死锁 (iptables-legacy 冲突)',
+    keywords: ['rk3588', 'rk3576', 'docker', 'iptables', 'nftables', 'network', 'bridge'],
+    symptoms: 'Docker 服务启动失败，或容器内无法通过桥接网关访问外部网络与外设流。',
+    root_cause: 'Rockchip 定制 Linux 6.1 内核对 nftables 的支持不完备，而较新版 Docker 默认尝试使用 iptables-nft。',
+    solution: [
+      '1. 切换系统默认 iptables 为 legacy 模式：',
+      '   sudo update-alternatives --set iptables /usr/sbin/iptables-legacy',
+      '   sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy',
+      '2. 重启 Docker 守护进程：sudo systemctl restart docker'
+    ],
+    forbidden: '切勿卸载 iptables 软件包或随意清空 iptables -F，这会导致 Docker 默认 NAT 转发链彻底损坏。'
+  },
+  {
+    id: 'recamera_vpss_overflow',
+    chip: 'recamera',
+    title: 'reCamera (SG2002 / RV1126B) 图像管道溢出 (VPSS FIFO overflow)',
+    keywords: ['recamera', 'vpss', 'fifo', 'overflow', 'sg2002', 'rv1126b', 'isp', 'vi'],
+    symptoms: '视频流卡死、黑屏，dmesg 频繁刷新 "VPSS FIFO overflow" 或 "VI drop frame"',
+    root_cause: '推理进程处理帧率低于摄像头输入帧率，导致硬件 ISP/VPSS 环形缓冲区被填满并阻塞硬件通道。',
+    solution: [
+      '1. 在 rkipc.ini 或流媒体配置中适当降低码流分辨率（从 1440P 降至 1080P 或 720P）',
+      '2. 限制推理帧率（如设置 skip_frames: 2，每秒处理 10~15 帧）',
+      '3. 检查模型加载是否启用了硬件 NPU 加速（.cvimodel / .rknn），避免 CPU 软解码'
+    ],
+    forbidden: '不要在视频流已卡死时直接硬重启机器，应先优雅杀掉流媒体服务以释放 VI/VPSS 通道。'
+  },
+  {
+    id: 'recamera_process_kill_safety',
+    chip: 'recamera',
+    title: 'reCamera 服务热重启安全规约：严禁 while true 且必须 sleep 3',
+    keywords: ['recamera', 'restart', 'fork bomb', 'sleep 3', 'pgrep', 'kill', 'watchdog'],
+    symptoms: '修改二进制或配置后设备网络全断，SSH/HTTP 无法连接，只能拔电硬重启。',
+    root_cause: '1. 硬件 VPSS/VI 资源被旧进程锁定未完全释放即启动新进程；2. 监控脚本使用死循环在二进制闪退时触发 Fork 风暴耗尽内核 PID。',
+    solution: [
+      '1. 优雅停止进程：for p in $(pgrep -f rkipc); do kill -9 $p; done',
+      '2. 关键安全延迟：必须等待 3 秒释放硬件通道：sleep 3',
+      '3. 安全拉起新服务：/userdata/rkipc.patch -c /userdata/rkipc.ini &'
+    ],
+    forbidden: '严禁在脚本中使用 while true; do /path/app; sleep 1; done 守护！一旦二进制参数错误快速退出，会导致系统瘫痪。'
+  },
+  {
+    id: 'jetson_nvidia_runtime_missing',
+    chip: 'jetson',
+    title: 'Jetson Orin (J4012/J2012) 容器缺失 NVIDIA Container Runtime',
+    keywords: ['jetson', 'orin', 'j4012', 'j4011', 'j2012', 'cuda', 'tensorrt', 'nvidia runtime'],
+    symptoms: 'Docker 容器启动报 "CUDA driver version is insufficient" 或无法找到 /dev/nvhost-* 设备',
+    root_cause: 'Docker 守护进程未配置默认 nvidia runtime，或运行 docker compose 时未指定 runtime: nvidia。',
+    solution: [
+      '1. 检查 /etc/docker/daemon.json 是否包含 "default-runtime": "nvidia"',
+      '2. 运行单个容器时添加参数：docker run --runtime nvidia ...',
+      '3. Compose 配置中加入：\n   runtime: nvidia\n   environment:\n     - NVIDIA_VISIBLE_DEVICES=all\n     - NVIDIA_DRIVER_CAPABILITIES=all'
+    ],
+    forbidden: '不要在 Jetson 容器内盲目安装标准 x86 的 NVIDIA 官方显卡驱动，Jetson 采用系统级统一内存 L4T BSP。'
+  },
+  {
+    id: 'hailo_driver_version_mismatch',
+    chip: 'hailo',
+    title: 'reComputer R2000 / RPi Hailo-8 驱动与运行库版本不匹配',
+    keywords: ['hailo', 'hailo8', 'libhailort', 'hailortcli', 'version mismatch', 'r2000'],
+    symptoms: '容器或应用启动报 "libhailort.so.4.21.0 not found" 或 "Driver version mismatch"',
+    root_cause: 'HailoRT 的内核驱动 (PCIe Driver)、用户态动态库 (libhailort) 和 GStreamer 插件版本必须严格完全一致（如均为 4.21.0）。',
+    solution: [
+      '1. 检查当前内核驱动状态：hailortcli fw-control identify',
+      '2. 检查动态库版本：ls -l /usr/lib/libhailort.so*',
+      '3. 确保宿主机与容器内镜像使用的 HailoRT 版本一致（官方套件均已固定为 4.21.0）'
+    ],
+    forbidden: '不要在已有应用正在占用 /dev/hailo0 时启动第二个推理容器，Hailo-8 默认排他独占访问。'
+  }
+];
+
+/**
+ * Searches the gotchas troubleshooting database.
+ *
+ * @param {Object} options
+ * @param {string} [options.query] - Search term
+ * @param {string} [options.chip] - Target chip/platform (rk3588, recamera, jetson, hailo)
+ * @returns {Array<Object>} Matched gotchas records
+ */
+export function searchGotchas({ query = '', chip = '' } = {}) {
+  const q = String(query || '').trim().toLowerCase();
+  const c = String(chip || '').trim().toLowerCase();
+
+  return GOTCHAS_DATABASE.filter((item) => {
+    if (c && !item.chip.toLowerCase().includes(c)) {
+      return false;
+    }
+    if (!q) return true;
+    const tokens = q.split(/\s+/).filter(Boolean);
+    const haystack = [
+      item.id,
+      item.chip,
+      item.title,
+      item.symptoms,
+      item.root_cause,
+      ...(item.keywords || []),
+      ...(Array.isArray(item.solution) ? item.solution : [item.solution]),
+    ].join(' ').toLowerCase();
+
+    return tokens.every((t) => haystack.includes(t));
+  });
+}

package/lib/installer.js

@@ -9,7 +9,7 @@ import {
   getConfiguredEnginePath
 } from './platform.js';
 import { detectExistingEngine, detectDesktopApp, verifyEngineBinary, compareSemver } from './detector.js';
-import { downloadEngine, fetchManifest, validateReleaseManifest, pullSolutionContent } from './downloader.js';
+import { downloadEngine, fetchManifest, validateReleaseManifest, pullSolutionContent, updateSolutionContent } from './downloader.js';
 import { getKnownAgents, scanLocalAgents, promptAgentSelection } from './agent.js';
 import {
   recordInstallation,
@@ -51,16 +51,18 @@ function assertCanonicalSkillState(ledger, agents) {
 export async function runInstall(options = {}) {
   const {
     agent = null,
+    skillsDir = null,
     yes = false,
     dryRun = false,
     skipContent = false,
     force = false,
     enginePath = null,
+    isUpdate = false,
     logger = console.log
   } = options;
 
   logger('\x1b[1m\x1b[34m====================================================\x1b[0m');
-  logger('\x1b[1m\x1b[34m  Solution CLI Installer                         \x1b[0m');
+  logger(`\x1b[1m\x1b[34m  Solution CLI ${isUpdate ? 'Updater' : 'Installer'}                         \x1b[0m`);
   logger('\x1b[1m\x1b[34m====================================================\x1b[0m\n');
 
   const platform = getPlatformInfo();
@@ -70,10 +72,10 @@ export async function runInstall(options = {}) {
 
   // --- Step 0: Pre-validate agent targets before ANY download/side-effects (Codex Medium 11) ---
   const scanned = scanLocalAgents();
-  const selectedAgents = await promptAgentSelection(scanned, agent, yes);
+  const selectedAgents = await promptAgentSelection(scanned, agent, yes, skillsDir);
 
   if (selectedAgents.length === 0) {
-    logger('\nNo agents selected. Installation halted with no filesystem modifications.');
+    logger('\nNo agents selected. Operation halted with no filesystem modifications.');
     return { success: true, engineBin: null, installedAgents: [] };
   }
 
@@ -147,8 +149,13 @@ export async function runInstall(options = {}) {
 
   // --- Step 2: Content Cache ---
   if (!skipContent && !dryRun) {
-    logger('\n🔄 Phase 2: Ensuring IoT solutions catalog is populated...');
-    pullSolutionContent(engineBin, msg => logger(`  ${msg}`));
+    if (isUpdate) {
+      logger('\n🔄 Phase 2: Updating IoT solutions catalog to latest...');
+      updateSolutionContent(engineBin, msg => logger(`  ${msg}`));
+    } else {
+      logger('\n🔄 Phase 2: Ensuring IoT solutions catalog is populated...');
+      pullSolutionContent(engineBin, msg => logger(`  ${msg}`));
+    }
   } else if (skipContent) {
     logger('\n🔄 Phase 2: Skipped solution pull (--skip-content).');
   }
@@ -243,9 +250,12 @@ export async function runInstall(options = {}) {
   logger(`\n🔧 Engine Binary: ${engineBin}`);
   logger(`🤖 Configured Agents:`);
   installedAgents.forEach(a => logger(`   - ${a.name}: ${a.path}`));
-  logger('\n👉 You can now open Work Buddy or your chosen Agent and ask:');
-  logger('   "帮我把边缘安全方案 (edge_security) 部署到 Jetson (192.168.1.100)"');
-  logger('   "查看当前有哪些可部署的物联网方案"');
+  logger('\n👉 [Instructions for AI Agent / 助手后续操作]:');
+  logger('   Solution CLI skill is now installed and activated.');
+  logger('   - Search IoT solutions: solution-cli hub search "<query>" --json');
+  logger('   - Check deployment specs: sensecraft-engine deploy-info <solution-id> --lang zh');
+  logger('   - Deploy (Local/Remote): sensecraft-engine deploy --params ./.sensecraft-work/body.json --yes');
+  logger('   Please inform the user that the skill is ready for solution selection and deployment.');
   logger('----------------------------------------------------\n');
 
   return {
@@ -262,6 +272,7 @@ export function runStatus(options = {}) {
   const engineCheck = verifyEngineBinary(binPath);
   const ledger = loadLedger();
   const scannedAgents = scanLocalAgents();
+  const app = detectDesktopApp();
 
   const statusObj = {
     engine: {
@@ -271,6 +282,12 @@ export function runStatus(options = {}) {
       valid: engineCheck.valid,
       deployersCount: engineCheck.deployers?.length || 0
     },
+    desktop_app: {
+      detected: Boolean(app.detected),
+      compatible: Boolean(app.compatible),
+      appPath: app.appPath || null,
+      version: app.version || null
+    },
     content: {
       dir: getContentDir(),
       manifestExists: fs.existsSync(path.join(getContentDir(), 'manifest.json'))
@@ -294,6 +311,12 @@ export function runStatus(options = {}) {
   logger(`  Engine Binary: ${binPath}`);
   logger(`  Engine Version: ${engineCheck.version || 'Not installed'} (${engineCheck.valid ? 'Valid' : 'Invalid'})`);
   logger(`  Deployers Available: ${engineCheck.deployers?.length || 0}`);
+  if (app.detected) {
+    logger(`  Desktop App (GUI): Detected at ${app.appPath || app.binPath} (v${app.version || 'installed'})`);
+  } else {
+    logger('  Desktop App (GUI): \x1b[90mNot detected\x1b[0m');
+    logger('    💡 可视化看板与桌面客户端下载: https://sensecraft.seeed.cc/download');
+  }
   logger(`  Content Directory: ${getContentDir()} (${statusObj.content.manifestExists ? 'Ready' : 'Not cached'})`);
   logger('\n  Configured Agent Skills:');
 
@@ -408,3 +431,46 @@ function copyFolderSafely(srcDir, destDir, baseDestDir, priorFiles, force, logge
 
   return { filesWritten, updatedFiles, preservedFiles };
 }
+
+/**
+ * Runs update on existing installed agents and synchronizes solution content and engine.
+ *
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+export async function runUpdate(options = {}) {
+  const logger = options.logger || console.log;
+
+  let targetAgent = options.agent;
+  if (!targetAgent && !options.skillsDir) {
+    const scanned = scanLocalAgents();
+    const installed = scanned.filter(a => a.installed);
+    if (installed.length > 0) {
+      targetAgent = installed.map(a => a.id).join(',');
+    }
+  }
+
+  return runInstall({
+    ...options,
+    agent: targetAgent,
+    yes: options.yes !== undefined ? options.yes : true,
+    isUpdate: true,
+    logger,
+  });
+}
+
+/**
+ * Returns formatted scan of local AI agents.
+ *
+ * @returns {Array<Object>}
+ */
+export function listAgents() {
+  const scanned = scanLocalAgents();
+  return scanned.map(a => ({
+    id: a.id,
+    name: a.name,
+    detected: a.detected,
+    installed: a.installed,
+    skillsDir: a.skillsDir,
+  }));
+}