@seeed-studio/solution-cli 0.3.2 → 0.4.0

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,
+  }));
+}

package/lib/integration.js

@@ -0,0 +1,265 @@
+/**
+ * @file integration.js
+ * Integration contracts and system ingestion specifications for Solution CLI.
+ */
+
+export const INTEGRATION_CONTRACTS = {
+  fall_detection: {
+    solution_id: 'fall_detection',
+    protocols: ['mqtt', 'http', 'webhook', 'rtsp'],
+    interfaces: [
+      {
+        protocol: 'mqtt',
+        port: 1883,
+        topic: '<device_name>/fall-detection/results/<stream_id>',
+        direction: 'publish',
+        description: '实时人体姿态与跌倒识别结果，一路摄像头对应一个子主题。',
+        payload_example: {
+          state: 'fallen',
+          fall_detected: true,
+          fall_event: true,
+          event_id: 7,
+          person_count: 1,
+          fallen_count: 1,
+          persons: [
+            {
+              track_id: 3,
+              state: 'fallen',
+              bbox: [0.51, 0.72, 0.34, 0.21],
+              confidence: 0.94
+            }
+          ],
+          timestamp: 1788581337000
+        }
+      },
+      {
+        protocol: 'mqtt',
+        port: 1883,
+        topic: 'homeassistant/',
+        direction: 'publish',
+        description: 'Home Assistant MQTT Discovery 自动发现协议，跌倒传感器、事件编号会自动出现。'
+      },
+      {
+        protocol: 'webhook',
+        port: 8080,
+        endpoint: '配置中的 ALARM_WEBHOOK_URL',
+        direction: 'outbound_post',
+        description: '跌倒告警确认后向外部系统发送 HTTP POST 通知，附带防重复通知的幂等键。',
+        payload_example: {
+          id: 'a-17',
+          kind: 'fall',
+          zone_id: 'bedroom',
+          stream_id: 'cam-01',
+          state: 'notified',
+          event_timestamp: 1788581337237,
+          operator: 'duty-nurse'
+        }
+      },
+      {
+        protocol: 'http',
+        port: 8080,
+        endpoint: '/api/alarms',
+        direction: 'inbound_rest',
+        description: '告警面板 REST API，支持查询当前告警列表、执行确认 (confirm) 与驳回 (dismiss)。'
+      },
+      {
+        protocol: 'rtsp',
+        port: 8554,
+        endpoint: '/live0',
+        direction: 'stream',
+        description: '设备实时处理叠加视频流，支持 NVR 录像或第三方视频播放器调阅。'
+      }
+    ],
+    input_requirements: [
+      {
+        type: 'rtsp',
+        description: '标准 RTSP 摄像头流输入（如 rtsp://admin:pass@192.168.1.100:554/live/ch0），支持海康、大华等 IP 摄像头。'
+      }
+    ],
+    system_ingestion_guide: [
+      '1. 接入自建 MQTT Broker：在方案配置中将 MQTT_BROKER 改为自建服务器地址，订阅 fall-detection/results/# 获取每帧 JSON。',
+      '2. 接入业务告警中心：在告警面板中配置 Webhook 地址，有人跌倒经确认后会自动向该地址 POST 结构化事件。',
+      '3. 接入 Home Assistant：保证同一局域网下 MQTT Broker 互通，HA 会自动发现跌倒感应实体。'
+    ]
+  },
+
+  'edge-anpr-plate-recognition': {
+    solution_id: 'edge-anpr-plate-recognition',
+    protocols: ['mqtt', 'http', 'webhook', 'rtsp'],
+    interfaces: [
+      {
+        protocol: 'mqtt',
+        port: 1883,
+        topic: 'edge/anpr/results',
+        direction: 'publish',
+        description: '抓拍过车车牌识别结果上报。',
+        payload_example: {
+          plate_number: '粤B12345',
+          confidence: 0.98,
+          direction: 'inbound',
+          lane_id: 1,
+          timestamp: 1788581350000,
+          vehicle_color: 'white',
+          vehicle_type: 'sedan'
+        }
+      },
+      {
+        protocol: 'webhook',
+        endpoint: '配置中的 ANPR_WEBHOOK_URL',
+        direction: 'outbound_post',
+        description: '过车事件向停车计费或园区管理系统推送。'
+      },
+      {
+        protocol: 'rtsp',
+        direction: 'input',
+        description: 'IP 监控摄像头 RTSP 视频流接入。'
+      }
+    ],
+    system_ingestion_guide: [
+      '1. 订阅 MQTT topic "edge/anpr/results" 获取结构化车牌及进出方向。',
+      '2. 可配置道闸联动继电器或向道闸系统发送 HTTP 开闸指令。'
+    ]
+  },
+
+  smart_agriculture_sensing: {
+    solution_id: 'smart-agriculture-sensing',
+    protocols: ['lorawan', 'mqtt', 'modbus'],
+    interfaces: [
+      {
+        protocol: 'mqtt',
+        port: 1883,
+        topic: 'sensecap/data/telemetry',
+        direction: 'publish',
+        description: '农田微气象与土壤墒情周期上报。',
+        payload_example: {
+          station_id: 's700-01',
+          air_temperature: 24.5,
+          air_humidity: 65.2,
+          soil_moisture: 38.1,
+          soil_temperature: 21.0,
+          soil_ec: 1.2,
+          light_lux: 45000,
+          battery_pct: 95
+        }
+      },
+      {
+        protocol: 'modbus',
+        port: 'RS485',
+        direction: 'bus',
+        description: '标准 Modbus RTU 工业总线控制水泵与电磁阀组。'
+      }
+    ],
+    system_ingestion_guide: [
+      '1. LoRaWAN 测点通过 SenseCAP M2 网关汇聚，通过 MQTT 集中推送到企业平台。',
+      '2. 边缘网关就地根据阈值自动执行 Modbus 继电器启停，保证断网时本地闭环运行。'
+    ]
+  },
+
+  edge_inspection_surface: {
+    solution_id: 'edge_inspection_surface',
+    protocols: ['mqtt', 'gpio', 'http'],
+    interfaces: [
+      {
+        protocol: 'mqtt',
+        port: 1883,
+        topic: 'inspection/defect/events',
+        direction: 'publish',
+        description: '流水线工业质检缺陷判别事件。',
+        payload_example: {
+          part_id: 'part-20261015-081',
+          is_defective: true,
+          defect_type: 'scratch',
+          confidence: 0.96,
+          bbox: [120, 340, 45, 12],
+          timestamp: 1788581360000
+        }
+      },
+      {
+        protocol: 'gpio',
+        direction: 'digital_out',
+        description: '隔离数字量输出 (DO)，发现次品时直接输出 24V 脉冲联动气缸执行剔除。'
+      }
+    ],
+    system_ingestion_guide: [
+      '1. 订阅缺陷事件 MQTT 用于车间看板展示不良率与缺陷类别分布。',
+      '2. 硬件 DO 端子直接接入产线 PLC 计数或剔除机构。'
+    ]
+  }
+};
+
+/**
+ * Extracts or generates system integration contract for a given solution or reference design.
+ *
+ * @param {string} solutionId
+ * @param {Object} [options]
+ * @param {string} [options.guideText] - Deployment guide text for fallback scanning
+ * @returns {Object} Integration contract specification
+ */
+export function getIntegrationContract(solutionId, { guideText = '' } = {}) {
+  const normId = String(solutionId || '').replace(/-/g, '_').toLowerCase();
+  for (const [key, contract] of Object.entries(INTEGRATION_CONTRACTS)) {
+    const normKey = key.replace(/-/g, '_').toLowerCase();
+    if (normId === normKey || normId.includes(normKey) || normKey.includes(normId)) {
+      return contract;
+    }
+  }
+
+  // Fallback: smart heuristic scan over deployment guide text
+  const protocols = [];
+  const interfaces = [];
+  const g = String(guideText || '');
+
+  if (/mqtt/i.test(g)) {
+    protocols.push('mqtt');
+    interfaces.push({
+      protocol: 'mqtt',
+      port: 1883,
+      topic: `${solutionId}/results`,
+      direction: 'publish',
+      description: 'MQTT 业务结果与状态发布总线'
+    });
+  }
+  if (/webhook/i.test(g)) {
+    protocols.push('webhook');
+    interfaces.push({
+      protocol: 'webhook',
+      endpoint: '配置中的 WEBHOOK_URL',
+      direction: 'outbound_post',
+      description: '事件触发向外部系统推送 HTTP POST 回调'
+    });
+  }
+  if (/rtsp/i.test(g)) {
+    protocols.push('rtsp');
+    interfaces.push({
+      protocol: 'rtsp',
+      port: 8554,
+      direction: 'stream',
+      description: '视频流接入或实时画面分发'
+    });
+  }
+  if (/http|dashboard|api/i.test(g)) {
+    protocols.push('http');
+    interfaces.push({
+      protocol: 'http',
+      port: 8080,
+      endpoint: '/api',
+      direction: 'inbound_rest',
+      description: 'REST API 或管理控制面板'
+    });
+  }
+
+  if (protocols.length === 0) {
+    protocols.push('mqtt', 'http');
+  }
+
+  return {
+    solution_id: solutionId,
+    protocols,
+    interfaces,
+    input_requirements: [],
+    system_ingestion_guide: [
+      '1. 详情请查阅该方案的具体部署指南与环境变量说明。',
+      '2. 通过标准网络协议（MQTT/HTTP）完成与自有业务系统的对接。'
+    ]
+  };
+}