@seeed-studio/solution-cli 0.2.0 → 0.3.0

package/docs/cli-guide.md

@@ -0,0 +1,264 @@
+# SenseCraft Solution CLI 使用与集成全景指南
+*(SenseCraft Solution CLI & AI Agent Skill Guide)*
+
+> **定位**：本文档专门面向**方案架构师、现场应用工程师 (FAE)、嵌入式开发者以及 AI Agent (Claude Code / Codex / Antigravity / Work Buddy)**，系统性说明 `@seeed-studio/solution-cli` 的独特应用场景、安装流程、各功能指令的具体使用方式以及核心产出物。
+
+---
+
+## 目录
+
+1. [独特使用场景与核心价值](#1-独特使用场景与核心价值)
+2. [安装与 Agent 技能挂载](#2-安装与-agent-技能挂载)
+3. [核心功能、使用方法与具体产出](#3-核心功能使用方法与具体产出)
+   - [场景一：方案探索与工况诊断 (Hub Search)](#场景一方案探索与工况诊断-hub-search)
+   - [场景二：硬件产品规格与配件防呆评估 (Product & BOM)](#场景二硬件产品规格与配件防呆评估-product--bom)
+   - [场景三：设备状态感知与参数热修改 (Device Management)](#场景三设备状态感知与参数热修改-device-management)
+   - [场景四：自研模型替换与本地二次开发 (Secondary Dev)](#场景四自研模型替换与本地二次开发-secondary-dev)
+4. [双轨运行机制：在线直连与离线托底](#4-双轨运行机制在线直连与离线托底)
+5. [常见问题与环境自检 (Doctor)](#5-常见问题与环境自检-doctor)
+
+---
+
+## 1. 独特使用场景与核心价值
+
+在传统边缘物联网与 AI 项目落地过程中，开发者通常面临以下痛点：
+- **方案选型盲目**：不清楚现场环境（集中还是分散、有无现有监控摄像头、有无市电）对硬件架构的致命影响；
+- **配件采购踩坑**：工控机买回后发现电源电压不符（如 12V 误插 19V 算力板）、DC 插头尺寸不对（5.5x2.1mm 插不进 5.5x2.5mm）、M.2 接口插槽类型搞混（Key-M 固态插不进 Key-E Wi-Fi 槽）；
+- **参数变更成本高**：改个 MQTT Broker 地址或算法置信度阈值就需要重新编译镜像或重装整套系统；
+- **AI Agent 缺乏边缘硬件感知**：纯大模型对话缺乏真实物理世界的接口约束，容易凭空编造不存在的硬件型号或非官方链接。
+
+`@seeed-studio/solution-cli` 正是为解决这一系列问题而生，它具有三大独特角色：
+1. **方案专家的现场诊断仪**：内置各大行业工况诊断知识库，不仅能搜方案，还能直接指导工程师向客户提出决定成本与物理拓扑的“黄金追问”；
+2. **硬件采购防呆中枢**：内置物理规格匹配引擎，自动核算【必需配件】与【可选配件】，从源头阻断硬件返工；
+3. **AI Agent 的物理世界触手**：一键将 SenseCraft Skill 注入到主流 AI Agent 宿主中，让 Agent 具备从方案咨询、BOM 选型到现场部署、参数热更的全生命周期驱动能力。
+
+---
+
+## 2. 安装与 Agent 技能挂载
+
+### 2.1 一键免安装即时调用 (推荐)
+无需全局安装，利用 `npx` 即可随时调用：
+```bash
+# 查看帮助与版本
+npx @seeed-studio/solution-cli --help
+
+# 交互式扫描并为本机所有 Agent 安装技能
+npx @seeed-studio/solution-cli install
+```
+
+### 2.2 全局安装
+```bash
+npm install -g @seeed-studio/solution-cli
+```
+
+### 2.3 跨 Agent 平台技能挂载
+执行 `solution-cli install` 时，工具会自动检测本机存在的 Agent 宿主环境，并将 `sensecraft` Skill 和全套参考手册安全复制到对应目录：
+
+| Agent 宿主平台 | 技能默认配置路径 | 支持能力 |
+|---|---|---|
+| **Claude Code** | `~/.claude/skills/sensecraft` | 完整方案咨询、工况诊断、BOM 生成、现场部署 |
+| **Codex (OpenAI)** | `~/.agents/skills/sensecraft` 或 `~/.codex/skills/sensecraft` | 代码审查、参数重构、二次开发自动化 |
+| **Google Antigravity (AGY)** | `~/.gemini/config/skills/sensecraft` | 端到端自主诊断、多 Agent 协同实施 |
+| **Work Buddy / Workbody** | `~/.workbuddy/skills/sensecraft` | 桌面端交互、方案展示、一键部署联动 |
+| **CodeBuddy** | `~/.codebuddy/skills/sensecraft` | 代码库配对开发与自研模型构建 |
+
+**非交互式多选安装示例**：
+```bash
+# 同时为 Claude Code 和 Google Antigravity 部署技能，不弹窗确认
+solution-cli install --agent claude,antigravity -y
+```
+
+---
+
+## 3. 核心功能、使用方法与具体产出
+
+### 场景一：方案探索与工况诊断 (Hub Search)
+
+当工程师或客户提出模糊需求（如“想在农田做微气象监测”、“工厂产线想做划痕检测”）时使用。
+
+#### 1. 执行命令
+```bash
+# 人类工程师阅读模式 (格式化终端高亮)
+solution-cli hub search "农业"
+
+# AI Agent 消费模式 (标准 JSON 格式的 Catalog DTO)
+solution-cli hub search "跌倒检测" --json
+```
+
+#### 2. 产出物内容 (What it Outputs)
+运行该命令可产出 4 项关键资产：
+1. **方案业务说明与技术架构**：解释为何适合在端侧运行、本地处理延迟、数据不出本地的隐私保障；
+2. **静默商业闭环出口**：自动为该方案生成带有安全追踪标记（`utm_source=sensecraft_agent`）的官方落地页与开发 Wiki；
+3. **官方开源仓库地址**：提供官方维护的 GitHub 源码仓库，为二次开发预留出口；
+4. **现场工况诊断提问指引 (Diagnostic Playbook)**：直接给出当前场景下**必须向客户确认的 2~3 个核心工况问题**及其背后的技术决断理由。
+
+#### 3. 产出示例 (以“农业”搜索为例)
+```text
+🔍 Solutions Hub Search Results for "农业" (typesense):
+
+  1. [Reference Design] 农业环境监测可部署方案 | LoRaWAN 自建看板 (agri_env_monitor)
+     把 SenseCAP 土壤与空气传感器接到 Home Assistant 看板上，支持本地私有 ChirpStack 运行，断网可用。
+     预设模式: cloud, tts_local, chirpstack_local
+     现场工况诊断提问指引:
+       • 监测区域是集中式连栋温室大棚（百米级），还是大面积户外大田/果园（数公里级）？ 
+         (决断考量: 大棚内百米级可采用 RS485 总线；广域大田推荐 LoRaWAN 远距无线，配 SenseCAP M2 网关)
+       • 现场测点是否有 220V 市电供电，还是需要野外太阳能板/锂电池长续航供电？ 
+         (决断考量: 市电支持持续高频数据上报；无市电需选配支持休眠唤醒的超低功耗无线传感器)
+       • 需要监测哪些核心指标？仅空气温湿度，还是包括土壤剖面水肥墒情（水分/EC/pH）？ 
+         (决断考量: 决定是配置多合一微气象站，还是选配工业级土壤三参数探头与变送器)
+```
+
+---
+
+### 场景二：硬件产品规格与配件防呆评估 (Product & BOM)
+
+当确定了方案，需要进入商务采购阶段、给客户出具设备清单时使用。
+
+#### 1. 执行命令
+```bash
+# 1. 查询产品族详情与物理规格
+solution-cli product query recomputer_j40 --json
+
+# 2. 评估该产品族所需的官方配件与兼容性
+solution-cli product accessories recomputer_j40 --json
+```
+
+#### 2. 产出物内容 (What it Outputs)
+1. **精确分类的 BOM 清单**：
+   - **【必需配件 (REQUIRED)】**：没有该配件主机无法开机或无法运行（如专属电源适配器），附带选型理由；
+   - **【可选配件 (OPTIONAL)】**：根据工况选择的外设（如 NVMe 固态硬盘、Wi-Fi 模组、导轨安装卡扣、射频天线）；
+2. **物理兼容性安全评级**：
+   - `VERIFIED`（通过）：电压、引脚、尺寸完全匹配；
+   - `REQUIRES_ADAPTER`（需转接）：如 M.2 2242 规格装入 2280 卡槽需加铜柱；
+   - `INCOMPATIBLE`（不兼容/危险）：严禁搭配，防止烧毁板卡。
+
+#### 3. 产出示例 (以 reComputer J40 为例)
+```json
+{
+  "family_id": "recomputer_j40",
+  "physical_spec": {
+    "power_input": {
+      "connector": "dc_jack_5.5x2.5",
+      "voltage_v": 19.0,
+      "min_current_a": 4.74,
+      "polarity": "center_positive"
+    },
+    "m2_slots": [
+      {"key": "M", "size": "2280", "interface": "PCIe Gen4 x4 NVMe"},
+      {"key": "E", "size": "2230", "interface": "WiFi/BT"}
+    ]
+  },
+  "accessories": {
+    "required": [
+      {
+        "sku": "313080684",
+        "name": "19V 4.74A 电源适配器 (5.5x2.5mm)",
+        "category": "REQUIRED",
+        "compatibility": { "status": "VERIFIED" },
+        "url": "https://www.seeedstudio.com/Power-Adapter-19V-4-74A-p-5573.html?utm_source=sensecraft_agent..."
+      }
+    ],
+    "optional": [
+      {
+        "sku": "110991734",
+        "name": "M.2 2280 NVMe SSD 512GB",
+        "category": "OPTIONAL",
+        "compatibility": { "status": "VERIFIED" }
+      }
+    ]
+  }
+}
+```
+
+---
+
+### 场景三：设备状态感知与参数热修改 (Device Management)
+
+当方案已经在现场或测试架部署完毕，需要调整运行参数（如更换 MQTT Broker、调整告警置信度阈值）时使用。
+
+#### 1. 核心流程与接口
+系统支持**无需重新编译、无需重装整套系统**的零重启参数热修改：
+1. **查询当前设备活跃部署**：
+   `GET http://<host>:5823/api/device-management/active`
+2. **查询可修改参数**：
+   `GET http://<host>:5823/api/docker-devices/local/config/<solution_id>`
+   检查参数字段中的 `reconfigurable: true` 标记。
+3. **提交热更新**：
+   `PUT http://<host>:5823/api/docker-devices/local/config/<solution_id>`
+   传入目标键值，容器环境无感热加载生效。
+
+---
+
+### 场景四：自研模型替换与本地二次开发 (Secondary Dev)
+
+当官方自带的模型无法满足客户特殊工况（如需要自研模型、特殊缺陷检测、修改前端大屏 UI）时使用。
+
+#### 1. 开发闭环步骤
+1. **克隆源码**：
+   从 `solution-cli hub search` 返回的 `repo_url` 将源码克隆到本地用户工作区：
+   ```bash
+   git clone https://github.com/suharvest/sensecraft-solutions.git ./my-solutions
+   ```
+2. **端侧模型转换 (以 Jetson Orin 为例)**：
+   在设备上使用 TensorRT 将自定义 ONNX 导出为 Engine：
+   ```bash
+   /usr/src/tensorrt/bin/trtexec --onnx=my_model.onnx --saveEngine=my_model.engine --fp16
+   ```
+3. **覆盖挂载配置**：
+   在方案目录创建 `docker-compose.override.yml` 将本地自研模型映射进容器中。
+4. **驱动本地快速联调**：
+   使用 `--solutions-dir` 参数，强制底层引擎加载本地修改版方案，彻底不碰官方缓存：
+   ```bash
+   sensecraft-engine deploy --solution fall_detection --solutions-dir ./my-solutions/solutions
+   ```
+
+---
+
+## 4. 双轨运行机制：在线直连与离线托底
+
+为了保证在各类严苛现场环境下均能稳定运行，CLI 实现了智能双轨架构：
+
+```mermaid
+flowchart TD
+    RunCmd["用户 / Agent 触发 CLI 命令"] --> NetCheck{"检查网络与凭证"}
+    NetCheck -- "有外网且含烘焙配置" --> Typesense["直连 Seeed Typesense 云端搜索集群"]
+    Typesense -- "返回最新上线方案与配件" --> Done["输出 Catalog DTO"]
+    NetCheck -- "纯内网 / 无凭证 / 超时" --> LocalCore["无感降级: 读取 catalog/knowledge-core.json"]
+    LocalCore -- "331 KB 本地知识库 (18场景/39方案/119硬件)" --> Done
+```
+
+1. **在线实时模式 (Online Live)**：
+   - 采用安全方案 B 在构建发布期烘焙了公开的只读 Search-Only 凭证；
+   - 自动直连 `https://rel-search.seeedstudio.com`，实时获取最新的方案、Wiki、案例及商城 SKU；
+2. **离线安全托底 (Offline Resilience)**：
+   - 打包了全量预生成的 `catalog/knowledge-core.json`（331 KB）；
+   - 在军工、内网、无公网或云端响应超过 2.5 秒时，**自动毫秒级无感降级到本地内核**，工况诊断、BOM 评估与离线部署 100% 正常可用。
+
+---
+
+## 5. 常见问题与环境自检 (Doctor)
+
+### 1. 运行自检工具
+在部署前或遇到环境异常时，执行：
+```bash
+solution-cli doctor
+```
+工具将逐项检测并给出修复指引：
+- `OS Platform`: 确认宿主机操作系统及架构是否支持；
+- `Docker Daemon`: 确认 Docker 服务是否正常运行；
+- `Serial / Dialout Permissions`: 确认串口访问权限；
+- `SenseCraft Engine`: 确认底座引擎完整性与版本；
+- `Ledger Integrity`: 校验技能安装账本状态。
+
+### 2. 状态查询
+```bash
+solution-cli status
+```
+实时查看当前 Engine 所在路径、安装版本、本地 Content 方案缓存数量以及各大 Agent 的配置状态。
+
+### 3. 干净卸载
+如需从某个 Agent 中移除 SenseCraft 技能：
+```bash
+solution-cli uninstall --agent claude,antigravity
+```
+工具将依据安装账本（`~/.sensecraft/skills-ledger.json`）仅删除工具自身写入的文件，绝不误删用户自定义创建的技能。

package/lib/agent.js

@@ -54,6 +54,12 @@ export function getKnownAgents() {
         }
         return path.join(home, '.codebuddy', 'skills');
       }
+    },
+    {
+      id: 'antigravity',
+      name: 'Google Antigravity (AGY)',
+      homeDirs: [path.join(home, '.gemini', 'config'), path.join(home, '.gemini', 'antigravity-cli')],
+      getSkillsDir: () => path.join(home, '.gemini', 'config', 'skills')
     }
   ];
 }

package/lib/knowledge.js

@@ -12,6 +12,44 @@ const DATA_FILE = path.join(__dirname, '..', 'catalog', 'knowledge-core.json');
 
 let cachedKnowledgeCore = null;
 
+/**
+ * Appends UTM tracking parameters to a URL while preserving existing query parameters.
+ *
+ * @param {string} urlStr - Target URL
+ * @param {Object} utmParams
+ * @param {string} [utmParams.source='sensecraft_agent']
+ * @param {string} [utmParams.medium='solution_consult']
+ * @param {string} [utmParams.campaign='']
+ * @param {string} [utmParams.content='']
+ * @returns {string} URL with appended UTM parameters
+ */
+export function appendUtm(urlStr, {
+  source = 'sensecraft_agent',
+  medium = 'solution_consult',
+  campaign = '',
+  content = '',
+} = {}) {
+  if (!urlStr || typeof urlStr !== 'string') return urlStr || '';
+  try {
+    const url = new URL(urlStr);
+    if (!url.searchParams.has('utm_source') && source) {
+      url.searchParams.set('utm_source', source);
+    }
+    if (!url.searchParams.has('utm_medium') && medium) {
+      url.searchParams.set('utm_medium', medium);
+    }
+    if (!url.searchParams.has('utm_campaign') && campaign) {
+      url.searchParams.set('utm_campaign', campaign);
+    }
+    if (!url.searchParams.has('utm_content') && content) {
+      url.searchParams.set('utm_content', content);
+    }
+    return url.toString();
+  } catch {
+    return urlStr;
+  }
+}
+
 /**
  * Loads the bundled offline knowledge core file.
  *
@@ -62,6 +100,28 @@ function fetchJson(urlStr, headers = {}, timeoutMs = 2500) {
   });
 }
 
+const CONFIG_FILE = path.resolve(__dirname, '../catalog/client-config.json');
+let cachedClientConfig = null;
+
+/**
+ * Loads build-time baked client configuration if present.
+ *
+ * @returns {Object|null}
+ */
+export function loadClientConfig() {
+  if (cachedClientConfig) return cachedClientConfig;
+  try {
+    if (fs.existsSync(CONFIG_FILE)) {
+      const raw = fs.readFileSync(CONFIG_FILE, 'utf-8');
+      cachedClientConfig = JSON.parse(raw);
+      return cachedClientConfig;
+    }
+  } catch {
+    // Graceful fallback if missing or invalid
+  }
+  return null;
+}
+
 /**
  * Searches Seeed Solutions Hub scenarios and reference designs.
  *
@@ -73,34 +133,125 @@ function fetchJson(urlStr, headers = {}, timeoutMs = 2500) {
  */
 export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
   const qLower = (query || '').toLowerCase().trim();
-  const searchKey = process.env.SENSECRAFT_TYPESENSE_PURCHASE_SEARCH_KEY || process.env.TYPESENSE_SEARCH_KEY;
-  const host = process.env.TYPESENSE_HOST || 'https://rel-search.seeedstudio.com';
+  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;
+  const keyRefDesign = process.env.TYPESENSE_SEARCH_KEY_REFERENCE_DESIGN || process.env.TYPESENSE_SEARCH_KEY || clientConfig?.typesense?.search_key_reference_design;
 
-  // Attempt online Typesense search if key is provided and not explicitly running offline
-  if (searchKey && !process.env.SENSECRAFT_OFFLINE_ONLY) {
+  // Attempt online Typesense search if keys are provided and not explicitly running offline
+  if ((keySolution || keyRefDesign) && !process.env.SENSECRAFT_OFFLINE_ONLY) {
     try {
-      const searchUrl = `${host}/collections/Solution/documents/search?q=${encodeURIComponent(query)}&query_by=title,description,tags&per_page=${limit}`;
-      const data = await fetchJson(searchUrl, { 'X-TYPESENSE-API-KEY': searchKey }, 2500);
-      if (data && Array.isArray(data.hits)) {
-        const records = data.hits.map((hit) => {
-          const doc = hit.document || {};
-          return {
-            type: doc.doc_type || 'scenario',
-            id: doc.id || doc.slug,
-            title: doc.title,
-            summary: doc.summary || doc.description,
-            tags: doc.tags || [],
-            family_ids: doc.family_ids || [],
-            source: 'typesense',
-          };
-        });
+      const core = loadKnowledgeCore();
+      const onlinePromises = [];
+
+      if (keySolution) {
+        const solUrl = `${host}/collections/Solution/documents/search?q=${encodeURIComponent(query)}&query_by=title_zh_hans,title_en,excerpt_zh_hans,excerpt_en,display_tags_zh_hans&per_page=${limit}`;
+        onlinePromises.push(
+          fetchJson(solUrl, { 'X-TYPESENSE-API-KEY': keySolution }, 2500)
+            .then((data) => ({ type: 'scenario', hits: data?.hits || [] }))
+            .catch(() => ({ type: 'scenario', hits: [] }))
+        );
+      }
+
+      if (keyRefDesign) {
+        const rdUrl = `${host}/collections/reference_design/documents/search?q=${encodeURIComponent(query)}&query_by=name_zh_hans,name_en,summary_zh_hans,summary_en,tags&per_page=${limit}`;
+        onlinePromises.push(
+          fetchJson(rdUrl, { 'X-TYPESENSE-API-KEY': keyRefDesign }, 2500)
+            .then((data) => ({ type: 'reference_design', hits: data?.hits || [] }))
+            .catch(() => ({ type: 'reference_design', hits: [] }))
+        );
+      }
+
+      const results = await Promise.all(onlinePromises);
+      const onlineRecords = [];
+
+      for (const res of results) {
+        if (res.type === 'scenario') {
+          for (const hit of res.hits) {
+            const doc = hit.document || {};
+            const docId = doc.id || doc.slug;
+            const title = locale === 'en'
+              ? (doc.title_en || doc.title_zh_hans || docId)
+              : (doc.title_zh_hans || doc.title_en || docId);
+            const summary = locale === 'en'
+              ? (doc.excerpt_en || doc.seo_description_en || doc.excerpt_zh_hans || '')
+              : (doc.excerpt_zh_hans || doc.seo_description_zh_hans || doc.excerpt_en || '');
+            const tags = (locale === 'en' ? doc.display_tags_en : doc.display_tags_zh_hans) || doc.display_tags || [];
+            const pb = core.diagnostic_playbooks?.[docId] || doc.diagnostic_playbook || null;
+
+            onlineRecords.push({
+              type: 'scenario',
+              id: docId,
+              title,
+              summary,
+              tags,
+              family_ids: doc.family_ids || [],
+              reference_designs: doc.reference_designs || [],
+              landing_url: appendUtm(`https://www.seeedstudio.com/solutions/${docId}`, {
+                source: 'sensecraft_agent',
+                medium: 'solution_consult',
+                campaign: docId,
+                content: 'scenario_landing',
+              }),
+              repo_url: '',
+              diagnostic_playbook: pb,
+              source: 'typesense',
+            });
+          }
+        } else if (res.type === 'reference_design') {
+          for (const hit of res.hits) {
+            const doc = hit.document || {};
+            const docId = doc.id;
+            const title = locale === 'en'
+              ? (doc.name_en || doc.name_zh_hans || docId)
+              : (doc.name_zh_hans || doc.name_en || docId);
+            const summary = locale === 'en'
+              ? (doc.summary_en || doc.tagline_en || doc.summary_zh_hans || '')
+              : (doc.summary_zh_hans || doc.tagline_zh_hans || doc.summary_en || '');
+
+            let pb = doc.diagnostic_playbook || null;
+            if (!pb) {
+              for (const sc of core.scenarios || []) {
+                if ((sc.reference_designs || []).includes(docId)) {
+                  pb = sc.diagnostic_playbook || core.diagnostic_playbooks?.[sc.id] || null;
+                  break;
+                }
+              }
+            }
+
+            onlineRecords.push({
+              type: 'reference_design',
+              id: docId,
+              title,
+              summary,
+              presets: doc.presets || [],
+              landing_url: appendUtm(`https://www.seeedstudio.com/solutions/reference-designs/${docId}`, {
+                source: 'sensecraft_agent',
+                medium: 'solution_consult',
+                campaign: docId,
+                content: 'solution_landing',
+              }),
+              wiki_url: doc.wiki_url ? appendUtm(doc.wiki_url, {
+                source: 'sensecraft_agent',
+                medium: 'tech_wiki',
+                campaign: docId,
+              }) : '',
+              repo_url: doc.repo_url || `https://github.com/suharvest/sensecraft-solutions/tree/main/solutions/${docId}`,
+              diagnostic_playbook: pb,
+              source: 'typesense',
+            });
+          }
+        }
+      }
+
+      if (onlineRecords.length > 0) {
         return createCatalogDto({
           source: 'typesense',
           freshness: 'FRESH',
-          records: records.slice(0, limit),
+          records: onlineRecords.slice(0, limit),
         });
       }
-    } catch (err) {
+    } catch {
       // Graceful fallback to offline core with notice
     }
   }
@@ -133,6 +284,14 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
         tags: s.tags || [],
         family_ids: s.family_ids || [],
         reference_designs: s.reference_designs || [],
+        landing_url: appendUtm(s.landing_url || `https://www.seeedstudio.com/solutions/${s.id}`, {
+          source: 'sensecraft_agent',
+          medium: 'solution_consult',
+          campaign: s.id,
+          content: 'scenario_landing',
+        }),
+        repo_url: s.repo_url || '',
+        diagnostic_playbook: s.diagnostic_playbook || null,
         score,
       });
     }
@@ -156,7 +315,19 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
         title: rd.title?.[locale] || rd.title?.zh || rd.title?.en || rd.id,
         summary: rd.summary?.[locale] || rd.summary?.zh || rd.summary?.en || '',
         presets: rd.presets || [],
-        wiki_url: rd.wiki_url || '',
+        landing_url: appendUtm(rd.landing_url || `https://www.seeedstudio.com/solutions/reference-designs/${rd.id}`, {
+          source: 'sensecraft_agent',
+          medium: 'solution_consult',
+          campaign: rd.id,
+          content: 'solution_landing',
+        }),
+        wiki_url: rd.wiki_url ? appendUtm(rd.wiki_url, {
+          source: 'sensecraft_agent',
+          medium: 'tech_wiki',
+          campaign: rd.id,
+        }) : '',
+        repo_url: rd.repo_url || `https://github.com/suharvest/sensecraft-solutions/tree/main/solutions/${rd.id}`,
+        diagnostic_playbook: rd.diagnostic_playbook || null,
         score,
       });
     }
@@ -172,9 +343,9 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
     source: 'bundled_manifest',
     freshness: 'FRESH',
     records: combined,
-    warnings: searchKey
-      ? ['Online Typesense request timed out; fell back to local bundled manifest.']
-      : ['No Typesense API key configured. Displaying verified local catalog.'],
+    warnings: (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.'],
   });
 }
 
@@ -208,7 +379,15 @@ export function queryProductFamily(familyId, { locale = 'zh' } = {}) {
       default_sku: family.default_sku,
       regions: family.regions || [],
       skus_count: (family.skus || []).length,
-      skus: (family.skus || []).slice(0, 10),
+      skus: (family.skus || []).slice(0, 10).map((s) => ({
+        ...s,
+        url: appendUtm(s.url, {
+          source: 'sensecraft_agent',
+          medium: 'bom_recommendation',
+          campaign: family.id,
+          content: `sku_${s.sku}`,
+        }),
+      })),
       physical_spec: family.physical_spec || null,
       required_accessories_count: (family.required_accessories || []).length,
       optional_accessories_count: (family.optional_accessories || []).length,
@@ -248,7 +427,12 @@ export function queryAccessories(familyId, { sku = null, locale = 'zh' } = {}) {
       id: acc.id,
       name: acc.name,
       sku: acc.sku,
-      url: acc.url,
+      url: appendUtm(acc.url, {
+        source: 'sensecraft_agent',
+        medium: 'bom_recommendation',
+        campaign: family.id,
+        content: `required_${acc.id}`,
+      }),
       qty: acc.qty || 1,
       reason: acc.reason || 'Required for standard operation',
       applies_when: acc.applies_when || null,
@@ -268,7 +452,12 @@ export function queryAccessories(familyId, { sku = null, locale = 'zh' } = {}) {
       id: acc.id,
       name: acc.name,
       sku: acc.sku,
-      url: acc.url,
+      url: appendUtm(acc.url, {
+        source: 'sensecraft_agent',
+        medium: 'bom_recommendation',
+        campaign: family.id,
+        content: `optional_${acc.id}`,
+      }),
       type: acc.type || 'peripheral',
       compatibility: {
         is_compatible: comp.isCompatible,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seeed-studio/solution-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Zero-friction installer and CLI runner for SenseCraft Engine and AI Agent Skills (Work Buddy, Claude Code, Codex, CodeBuddy)",
   "type": "module",
   "main": "./lib/installer.js",
@@ -19,9 +19,12 @@
     "lib",
     "catalog",
     "skills",
+    "docs",
     "README.md"
   ],
   "scripts": {
+    "build": "node scripts/bake-client-config.mjs",
+    "prepack": "node scripts/bake-client-config.mjs",
     "test": "node --test tests/cli.test.mjs",
     "install:self": "node bin/cli.js install",
     "status": "node bin/cli.js status",

package/skills/sensecraft/SKILL.md

@@ -17,6 +17,8 @@ Do NOT read all reference files at once. Determine the user's workflow state and
 | **PROCUREMENT / VERIFY_BOM**<br>“买什么硬件？”、“J4012 需要配什么配件？” | `references/hardware-bom.md` | `solution-cli product accessories <id> --json` | **DO NOT fabricate** third-party SKUs or prices. Always distinguish REQUIRED vs OPTIONAL accessories. |
 | **ONBOARDING / PRECHECK**<br>“设备到了，插上了网线/USB”、“环境自检” | `references/diagnose.md` | `solution-cli doctor` / `sensecraft-engine device scan` | Freeze hardware requirements into DeploymentLockfile before proceeding to apply. |
 | **DEPLOYING / APPLY**<br>“开始安装”、“部署 fall_detection” | `references/deploy.md` | `sensecraft-engine deploy --solution <id>` | **DEPLOYMENT CRITICAL SECTION**: Zero external commercial queries allowed during apply. |
+| **MANAGE / RECONFIG**<br>“改一下 MQTT 地址”、“查看已安装应用”、“重启服务”、“修改配置” | `references/device-management.md` | `curl BASE/api/docker-devices/local/config/<id>` | **Check before write**: Only alter `reconfigurable: true` fields; check current value before modifying. |
+| **CUSTOMIZE / SECONDARY_DEV**<br>“我想改源码”、“换成自研模型”、“改前端看板”、“GitHub 仓库” | `references/secondary-development.md` | `git clone <repo_url>` / `sensecraft-engine --solutions-dir` | **Never edit cached content**: Clone to user workspace, pair-program, test locally with `--solutions-dir`. |
 | **TROUBLESHOOTING**<br>“部署报错”、“黑屏”、“无视频流” | `references/error-catalog.md` | `sensecraft-engine logs` / `solution-cli product verify-compatibility` | Max 3 fix-and-retry rounds. Follow local auto-patching rule. |
 
 Capabilities that need the **SenseCraft Solution desktop app** (editing a
@@ -86,6 +88,20 @@ daemon is a host prerequisite, not evidence that a deployment has passed.
 6. **Temp files:** keep request bodies and scratch files in the current
    working directory under `./.sensecraft-work/`, never in `/tmp`. Remove the
    directory when the task ends, also after a failure.
+7. **Conversational tone & soft referral:** Agent is an IoT domain expert and
+   answers technical, business, hardware, and configuration questions directly
+   and thoroughly using local knowledge and tools. Do NOT dump raw link lists
+   or write pushy sales pitches. External links (`landing_url`, `wiki_url`,
+   product purchase URLs, `repo_url`) must be smoothly integrated as
+   supplemental reading / procurement / code exploration. All URLs generated by
+   `solution-cli` automatically carry silent UTM parameters
+   (`utm_source=sensecraft_agent`) for analytics attribution.
+8. **Proactive diagnosis & domain-specific questioning:** During solution consultation,
+   Agent must avoid one-way monologues. Proactively inspect the `diagnostic_playbook`
+   returned by `solution-cli hub search` (or cross-reference `references/consult-and-select.md` §3).
+   Ask 2–3 targeted domain questions explaining the engineering rationale (topology,
+   asset reuse, power/cabling, inspection speed/materials) to help the user converge
+   on the optimal hardware architecture and budget.
 
 ## Step 0 — Install the engine and the solutions (every task)