@seeed-studio/solution-cli 0.3.0 → 0.3.2

package/lib/knowledge.js

@@ -144,8 +144,12 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
       const core = loadKnowledgeCore();
       const onlinePromises = [];
 
+      const locKey = locale === 'zh' ? 'zh_hans' : locale;
+      const fetchLimit = Math.max(limit * 5, 30);
+
       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}`;
+        const solFilter = 'published:!=false';
+        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&filter_by=${encodeURIComponent(solFilter)}&per_page=${fetchLimit}`;
         onlinePromises.push(
           fetchJson(solUrl, { 'X-TYPESENSE-API-KEY': keySolution }, 2500)
             .then((data) => ({ type: 'scenario', hits: data?.hits || [] }))
@@ -154,7 +158,8 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
       }
 
       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}`;
+        const rdFilter = 'published:!=false';
+        const rdUrl = `${host}/collections/reference_design/documents/search?q=${encodeURIComponent(query)}&query_by=name_zh_hans,name_en,summary_zh_hans,summary_en,tags&filter_by=${encodeURIComponent(rdFilter)}&per_page=${fetchLimit}`;
         onlinePromises.push(
           fetchJson(rdUrl, { 'X-TYPESENSE-API-KEY': keyRefDesign }, 2500)
             .then((data) => ({ type: 'reference_design', hits: data?.hits || [] }))
@@ -163,13 +168,19 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
       }
 
       const results = await Promise.all(onlinePromises);
-      const onlineRecords = [];
+      const onlineScenarios = [];
+      const onlineRefDesigns = [];
 
       for (const res of results) {
         if (res.type === 'scenario') {
           for (const hit of res.hits) {
             const doc = hit.document || {};
+            // Filter unreleased or staging scenarios from production recommendations
+            if (doc.published === false || doc.visibility === 'staging' || doc.visibility === 'draft') continue;
+            if (doc[`visibility_${locKey}`] === 'staging' || doc[`visibility_${locKey}`] === 'draft') continue;
+
             const docId = doc.id || doc.slug;
+            const docType = doc.doc_type || 'scenario';
             const title = locale === 'en'
               ? (doc.title_en || doc.title_zh_hans || docId)
               : (doc.title_zh_hans || doc.title_en || docId);
@@ -178,22 +189,23 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
               : (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;
+            const rawLanding = doc.external_url || doc.landing_url || `https://www.seeedstudio.com/solutions/${docId}`;
 
-            onlineRecords.push({
-              type: 'scenario',
+            onlineScenarios.push({
+              type: docType,
               id: docId,
               title,
               summary,
               tags,
               family_ids: doc.family_ids || [],
               reference_designs: doc.reference_designs || [],
-              landing_url: appendUtm(`https://www.seeedstudio.com/solutions/${docId}`, {
+              landing_url: appendUtm(rawLanding, {
                 source: 'sensecraft_agent',
                 medium: 'solution_consult',
                 campaign: docId,
-                content: 'scenario_landing',
+                content: `${docType}_landing`,
               }),
-              repo_url: '',
+              repo_url: doc.repo_url || '',
               diagnostic_playbook: pb,
               source: 'typesense',
             });
@@ -201,6 +213,10 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
         } else if (res.type === 'reference_design') {
           for (const hit of res.hits) {
             const doc = hit.document || {};
+            // Filter unreleased or staging reference designs from production recommendations
+            if (doc.published === false || doc.visibility === 'staging' || doc.visibility === 'draft') continue;
+            const locKey = locale === 'zh' ? 'zh_hans' : locale;
+            if (doc[`visibility_${locKey}`] === 'staging' || doc[`visibility_${locKey}`] === 'draft') continue;
             const docId = doc.id;
             const title = locale === 'en'
               ? (doc.name_en || doc.name_zh_hans || docId)
@@ -209,7 +225,7 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
               ? (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;
+            let pb = doc.diagnostic_playbook || core.diagnostic_playbooks?.[docId] || null;
             if (!pb) {
               for (const sc of core.scenarios || []) {
                 if ((sc.reference_designs || []).includes(docId)) {
@@ -219,12 +235,24 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
               }
             }
 
-            onlineRecords.push({
+            const rawPresets = doc.presets || [];
+            const presets = rawPresets.map((p) => {
+              if (typeof p === 'string') return p;
+              if (p && typeof p === 'object') {
+                return (locale === 'en' ? (p.name_en || p.name || p.id) : (p.name_zh_hans || p.name || p.id)) || p.id || '';
+              }
+              return String(p || '');
+            }).filter(Boolean);
+
+            const bundledRd = (core.reference_designs || []).find((r) => r.id === docId);
+            const repoUrl = doc.repo_url || bundledRd?.repo_url || '';
+
+            onlineRefDesigns.push({
               type: 'reference_design',
               id: docId,
               title,
               summary,
-              presets: doc.presets || [],
+              presets,
               landing_url: appendUtm(`https://www.seeedstudio.com/solutions/reference-designs/${docId}`, {
                 source: 'sensecraft_agent',
                 medium: 'solution_consult',
@@ -236,7 +264,7 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
                 medium: 'tech_wiki',
                 campaign: docId,
               }) : '',
-              repo_url: doc.repo_url || `https://github.com/suharvest/sensecraft-solutions/tree/main/solutions/${docId}`,
+              repo_url: repoUrl,
               diagnostic_playbook: pb,
               source: 'typesense',
             });
@@ -244,11 +272,90 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
         }
       }
 
-      if (onlineRecords.length > 0) {
+      // 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;
+            const locKey = locale === 'zh' ? 'zh_hans' : locale;
+            if (s[`visibility_${locKey}`] === 'staging' || s[`visibility_${locKey}`] === 'draft') continue;
+
+            const haystack = [s.id, s.title?.zh, s.title?.en, s.subtitle?.zh, s.subtitle?.en, s.summary, ...(s.tags || [])].join(' ').toLowerCase();
+            const score = tokens.reduce((acc, t) => (haystack.includes(t) ? acc + 1 : acc), 0);
+            if (tokens.length === 0 || score > 0) {
+              onlineScenarios.push({
+                type: 'scenario',
+                id: s.id,
+                title: s.title?.[locale] || s.title?.zh || s.title?.en || s.id,
+                summary: s.subtitle?.[locale] || s.subtitle?.zh || s.summary || '',
+                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,
+                source: 'bundled_manifest',
+              });
+            }
+          }
+        }
+        if (onlineRefDesigns.length === 0) {
+          for (const rd of core.reference_designs || []) {
+            if (rd.published === false || rd.visibility === 'staging' || rd.visibility === 'draft') continue;
+            const locKey = locale === 'zh' ? 'zh_hans' : locale;
+            if (rd[`visibility_${locKey}`] === 'staging' || rd[`visibility_${locKey}`] === 'draft') continue;
+
+            const haystack = [rd.id, rd.title?.zh, rd.title?.en, rd.summary?.zh, rd.summary?.en, ...(rd.presets || [])].join(' ').toLowerCase();
+            const score = tokens.reduce((acc, t) => (haystack.includes(t) ? acc + 1 : acc), 0);
+            if (tokens.length === 0 || score > 0) {
+              onlineRefDesigns.push({
+                type: 'reference_design',
+                id: rd.id,
+                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 || [],
+                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 || '',
+                diagnostic_playbook: rd.diagnostic_playbook || null,
+                source: 'bundled_manifest',
+              });
+            }
+          }
+        }
+      }
+
+      const mergedRecords = [];
+      const maxOnline = Math.max(onlineScenarios.length, onlineRefDesigns.length);
+      for (let i = 0; i < maxOnline && mergedRecords.length < limit; i++) {
+        if (i < onlineScenarios.length && mergedRecords.length < limit) {
+          mergedRecords.push(onlineScenarios[i]);
+        }
+        if (i < onlineRefDesigns.length && mergedRecords.length < limit) {
+          mergedRecords.push(onlineRefDesigns[i]);
+        }
+      }
+
+      if (mergedRecords.length > 0) {
         return createCatalogDto({
-          source: 'typesense',
+          source: (onlineScenarios.some(r => r.source === 'typesense') || onlineRefDesigns.some(r => r.source === 'typesense')) ? 'typesense' : 'bundled_manifest',
           freshness: 'FRESH',
-          records: onlineRecords.slice(0, limit),
+          records: mergedRecords,
         });
       }
     } catch {
@@ -264,6 +371,10 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
   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;
+    if (s[`visibility_${locKey}`] === 'staging' || s[`visibility_${locKey}`] === 'draft') continue;
+
     const haystack = [
       s.id,
       s.title?.zh,
@@ -298,6 +409,10 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
   }
 
   for (const rd of core.reference_designs || []) {
+    if (rd.published === false || rd.visibility === 'staging' || rd.visibility === 'draft') continue;
+    const locKey = locale === 'zh' ? 'zh_hans' : locale;
+    if (rd[`visibility_${locKey}`] === 'staging' || rd[`visibility_${locKey}`] === 'draft') continue;
+
     const haystack = [
       rd.id,
       rd.title?.zh,
@@ -326,7 +441,7 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
           medium: 'tech_wiki',
           campaign: rd.id,
         }) : '',
-        repo_url: rd.repo_url || `https://github.com/suharvest/sensecraft-solutions/tree/main/solutions/${rd.id}`,
+        repo_url: rd.repo_url || '',
         diagnostic_playbook: rd.diagnostic_playbook || null,
         score,
       });
@@ -337,7 +452,16 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
   matchedScenarios.sort((a, b) => b.score - a.score);
   matchedRefDesigns.sort((a, b) => b.score - a.score);
 
-  const combined = [...matchedScenarios, ...matchedRefDesigns].slice(0, limit);
+  const combined = [];
+  const maxOffline = Math.max(matchedScenarios.length, matchedRefDesigns.length);
+  for (let i = 0; i < maxOffline && combined.length < limit; i++) {
+    if (i < matchedScenarios.length && combined.length < limit) {
+      combined.push(matchedScenarios[i]);
+    }
+    if (i < matchedRefDesigns.length && combined.length < limit) {
+      combined.push(matchedRefDesigns[i]);
+    }
+  }
 
   return createCatalogDto({
     source: 'bundled_manifest',

package/lib/ledger.js

@@ -246,7 +246,7 @@ export function removeInstallation(agentId, options = {}) {
   }
 
   // Remove marker file
-  const marker = path.join(targetDir, '.installed-by-sensecraft');
+  const marker = path.join(targetDir, '.installed-by-solution-cli');
   if (fs.existsSync(marker) && isSafePathInside(marker, targetDir)) {
     actions.push({ file: marker, action: 'delete_marker' });
     if (!dryRun) {

package/package.json

@@ -1,15 +1,12 @@
 {
   "name": "@seeed-studio/solution-cli",
-  "version": "0.3.0",
-  "description": "Zero-friction installer and CLI runner for SenseCraft Engine and AI Agent Skills (Work Buddy, Claude Code, Codex, CodeBuddy)",
+  "version": "0.3.2",
+  "description": "Installer for the Rust deployment engine and Solution CLI Agent skills (Work Buddy, Claude Code, Codex, CodeBuddy)",
   "type": "module",
   "main": "./lib/installer.js",
   "bin": {
     "solution-cli": "bin/cli.js",
-    "sensecraft-solution-cli": "bin/cli.js",
-    "sensecraft": "bin/cli.js",
-    "sensecraft-engine": "bin/runner.js",
-    "sensecraft-skill": "bin/cli.js"
+    "sensecraft-engine": "bin/runner.js"
   },
   "publishConfig": {
     "access": "public"

package/skills/{sensecraft → solution-cli}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: sensecraft
-description: Consult, select, deploy, manage, and troubleshoot SenseCraft / Seeed Studio edge IoT solutions (智慧农业, 摔倒检测, 边缘安全, 智慧仓库, 语音助手, people counting, face recognition 等) and hardware products (reComputer Jetson, reCamera, SenseCAP, Grove Vision AI, ESP32) using the `sensecraft-engine` and `solution-cli` toolset. Use whenever the user asks for edge IoT solutions, hardware recommendations, accessory compatibility, deployment, or troubleshooting.
+name: solution-cli
+description: 用于客户询盘、客户需求、方案选型、我们能提供什么、怎么回复客户等边缘/IoT 方案咨询，涵盖智慧农业、跌倒检测、楼宇温控、恒温器、传感器及相关硬件。Use for customer inquiries, requirements analysis, solution selection, proposal guidance, edge IoT deployments, hardware compatibility, deployment, and troubleshooting. First search the SenseCraft solution catalog with `solution-cli`; do not trigger for general business writing, generic proposal drafting, or unrelated coding.
 ---
 
-# SenseCraft Solution
+# Solution CLI
 
-This skill drives the `sensecraft-engine` execution engine and `solution-cli` toolset. It operates across the complete lifecycle: **Solution Consultation ➔ Hardware & Accessory BOM Selection ➔ Local Deployment ➔ Self-Healing Diagnostics**.
+This skill drives the `sensecraft-engine` execution engine and `solution-cli` toolset. It operates across the complete lifecycle: **Solution Consultation ➔ Hardware & Accessory BOM Selection ➔ Local Deployment ➔ Self-Healing Diagnostics**. For Engine-only operations, use the injected absolute Engine path. If the wrapper is not on `PATH`, invoke the CLI as `npx -y --package=@seeed-studio/solution-cli@latest solution-cli <args>`. Keep catalog queries such as `hub` and `product` on `solution-cli`; do not forward them to the Engine.
 
 ## Workflow Routing & Progressive Disclosure
 
@@ -16,7 +16,7 @@ Do NOT read all reference files at once. Determine the user's workflow state and
 | **DISCOVERY / CONSULT**<br>“我想做防跌倒监控”、“有智慧农场方案吗” | `references/consult-and-select.md` | `solution-cli hub search "<keyword>" --json` | **DO NOT run deploy**; user is exploring scenarios and has not confirmed hardware. |
 | **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. |
+| **DEPLOYING / APPLY**<br>“开始安装”、“部署 fall_detection” | `references/deploy.md` | `sensecraft-engine deploy <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. |
@@ -78,7 +78,7 @@ daemon is a host prerequisite, not evidence that a deployment has passed.
    you checked, what you changed). Transient registry or network errors follow
    the backoff rule in `references/deploy.md` §6 and do not use up a round.
 4. **Preserving official cache & Local auto-patching**: Never edit files directly under the official content cache directory (`~/.sensecraft/content/`). When fixing a solution-level bug (timeout too short, wrong port/env var, minor syntax/transfer glitch, broken health check):
-   - In CLI / Engine mode: copy the solution from `~/.sensecraft/content/solutions/<id>` into `./.sensecraft-work/solutions/<id>`, apply the minimal fix in that copy. **Crucial engine switch step**: Because an existing engine daemon instance retains its initial solution directory in memory, you MUST stop the running instance first: `sensecraft-engine daemon stop`. Then re-run deployment with `--solutions-dir ./.sensecraft-work/solutions` so the fresh engine instance picks up the patched files. Show the user the patch diff.
+   - In CLI / Engine mode: copy the solution from `~/.sensecraft/content/solutions/<id>` into `./.sensecraft-work/solutions/<id>`, apply the minimal fix in that copy. Then re-run deployment with `sensecraft-engine deploy <id> --solutions-dir ./.sensecraft-work/solutions` so the engine picks up the patched files. Show the user the patch diff.
    - If running with the Desktop App: use the app's edit copy mechanism (`references/app-only.md` §4).
 5. **Reading output:** read the CLI's JSON output directly; it is small. If a
    filter is needed, use `jq` only when it is already installed. Do not start
@@ -103,7 +103,7 @@ daemon is a host prerequisite, not evidence that a deployment has passed.
    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)
+## Step 0 — Install the engine and the solutions (when needed)
 
 1. Check whether it is installed: `sensecraft-engine --version`. If the command
    is not found, also try `~/.sensecraft/bin/sensecraft-engine --version`
@@ -121,14 +121,41 @@ daemon is a host prerequisite, not evidence that a deployment has passed.
    command and stop; do not install packages or start another interpreter.
    `minisign` is required to verify the signed release manifest; Unix `jq` is
    required by the shell installer to read it.
-3. Not installed → install it together with the solutions (ask the user first,
-   it downloads a program):
+3. If it is not installed, install it together with the solutions (ask the user
+   first, it downloads a program). If the user explicitly asks to upgrade or
+   reinstall, use the same solution-cli command; do not reinstall on every
+   deployment:
 
-   **Recommended (Zero-friction via solution-cli, auto-detects existing app & agents)**:
+   **Recommended (Zero-friction via solution-cli, target the current Agent explicitly)**:
    ```bash
-   npx @seeed-studio/solution-cli install -y
+   npx -y @seeed-studio/solution-cli@latest install --agent <current-agent-id> -y
    ```
 
+   Fill `<current-agent-id>` with the actual host ID: `workbuddy`, `claude`,
+   `codex`, `codebuddy`, or `antigravity`. The WorkBuddy example is:
+   ```bash
+   npx -y @seeed-studio/solution-cli@latest install --agent workbuddy -y
+   ```
+   An AI agent must use its current host ID; Codex must not hardcode WorkBuddy.
+   Use `npx -y @seeed-studio/solution-cli@latest install` for interactive
+   selection. When one or more Agents are detected, pressing Enter selects all
+   detected Agents; entering the matching number selects one host. In
+   non-interactive mode, `install -y` without `--agent` also selects all detected
+   Agents when any are detected. If none are detected, these defaults still use
+   the CLI's default target set; pass `--agent <agent-id>` to control the scope
+   explicitly.
+
+   The command checks the signed stable Engine on fresh and repeat runs, reuses
+   an equal or newer local version, and upgrades an older one. It preserves
+   modified/unregistered skills and protected symlinks. Add `--agent ...` for an
+   explicit agent selection or `--engine-path <path>` for a valid custom pin.
+   `--force` can re-download equal/older versions and overwrite existing skill
+   files, including user modifications; use it only when that overwrite is
+   intended. Protected external symlinks are not followed, and it never
+   downgrades a newer discovered Engine. Automatic reuse/upgrade rules start with
+   publicly published solution-cli 0.3.1. Latest/signature failure
+   stops before writes; offline use requires a valid explicit local Engine path.
+
    **Fallback (Standalone shell script when Node.js is not present)**:
    ```bash
    curl --compressed -fsSL https://sensecraft-statics.seeed.cc/solution-app/engine/install.sh | sh -s -- --with-content
@@ -162,9 +189,8 @@ daemon is a host prerequisite, not evidence that a deployment has passed.
    list` or `deploy-info` exits with code 3 when no usable resource/solution
    directory is available and tells you to run `content pull`. If a usable
    directory exists but the requested solution ID is unknown, the query exits
-   with code 2. After `content pull` / `update`, if an engine instance is
-   already running it keeps the solutions it loaded at start: run
-   `sensecraft-engine daemon stop` when no deployment is running.
+   with code 2. After `content pull` / `update`, newly downloaded or updated
+   solutions are available to subsequent deployment and query commands.
 5. Device pre-checks on this computer: `sensecraft-engine doctor --json`. Each
    check has `status` (`ok` / `warn` / `fail`) and a `fix` command. Show the
    user any `fail` and its `fix`; running a `fix` changes this computer and

package/skills/{sensecraft → solution-cli}/references/consult-and-select.md

@@ -18,6 +18,8 @@
 | **建筑能耗 / 暖通** | 楼宇能耗、电表、水表、空调节能、HVAC, energy retrofit | `building-energy-retrofit` | `building_energy_management` |
 | **室内外定位 / 资产** | 蓝牙信标、资产定位、人员卡片、防丢、GNSS, tracker, beacon, T1000 | `indoor-outdoor-positioning` | `indoor_positioning_ble_lorawan` |
 
+客户询盘、客户需求分析、方案选型、如何回复客户或“我们能提供什么”也属于咨询路由；涉及楼宇温控、恒温器、温度/湿度/空气质量传感器等需求时，先用客户原话和关键技术词搜索方案库。若搜不到匹配结果，明确说明官方方案库缺少现成能力，再给出需定制验证的边界；不要把通用 IoT 能力编造成已有的 thermostat 硬件或现成方案。
+
 ---
 
 ## 2. 工具调用标准动作
@@ -27,6 +29,8 @@
 ```bash
 solution-cli hub search "<用户关键词>" --limit 5 --json
 ```
+- **咨询顺序**：先用用户原话和同义技术词查询，再根据返回的场景与 `diagnostic_playbook` 拆解需求；向用户确认点位、协议、供电、通信、控制闭环和预算等关键参数后，给出可提供的方案、硬件方向和缺口说明。
+- **交付边界**：咨询阶段只做检索、需求澄清和方案建议，不自动执行 `deploy`；用户确认硬件和部署目标后，再转入硬件校验或部署流程。
 - **输出结果说明**：
   - `Scenario`：业务场景、痛点、成效、官方场景落地页（`landing_url`）；
   - `Reference Design`：技术路线、预设模式 presets、开发 wiki（`wiki_url`）、官方方案落地页（`landing_url`）、源码仓库（`repo_url`）；

package/skills/{sensecraft → solution-cli}/references/device-management.md

@@ -22,50 +22,57 @@
 当设备已经部署运行，用户希望修改 L1 参数（如更改 MQTT 目标服务器）时：
 
 ### 步骤一：获取运行时信息与当前部署列表
-读取运行环境指针（从 `~/.sensecraft/runtime.json` 获取 `base_url`，默认为 `http://127.0.0.1:3260`）：
+读取运行环境指针并校验服务健康（桌面端每次启动分配随机端口并写入 `~/.sensecraft/runtime.json`；源码开发环境固定为 `http://127.0.0.1:3260`）：
 ```bash
+# 解析运行时 BASE_URL 并校验连通性
+BASE_URL=$(jq -r '.base_url // "http://127.0.0.1:3260"' ~/.sensecraft/runtime.json 2>/dev/null || echo "http://127.0.0.1:3260")
+curl -sf "$BASE_URL/api/health" > /dev/null || { echo "SenseCraft 服务未在 $BASE_URL 就绪"; exit 1; }
+
 # 查询当前设备上活跃运行的方案实例
-curl -s "http://127.0.0.1:3260/api/device-management/active"
+curl -s "$BASE_URL/api/device-management/active"
 ```
 - 输出包含 `solution_id`、`device_id`、`status`（running/stopped）、`deployed_at` 及运行 URL。
 
 ### 步骤二：读取可配参数及当前值（Get Config）
 ```bash
 # 本地 Docker 部署实例
-curl -s "http://127.0.0.1:3260/api/docker-devices/local/config/<solution_id>"
+curl -s "$BASE_URL/api/docker-devices/local/config/<solution_id>"
 
 # 远程设备实例（通过 SSH 提取运行态值）
-curl -s -X POST "http://127.0.0.1:3260/api/docker-devices/config/<solution_id>" \
+curl -s -X POST "$BASE_URL/api/docker-devices/config/<solution_id>" \
   -H "Content-Type: application/json" \
   -d '{"connection": {"host": "<ip>", "username": "<user>", "password": "<pwd>"}}'
 ```
 - 检查返回的 `fields` 列表：
-  - 确认用户想要修改的参数是否存在（`field.id`）；
+  - 确认用户想要修改的参数是否存在（`field.id`，如 `mqtt_broker`、`mqtt_port`）；
   - 查看当前已生效的数值（`field.current_value`）；
   - 核对其校验规则（`field.validation`）。
 
 ### 步骤三：验证并提交新参数（Update Config）
+> [!IMPORTANT]
+> `values` 字典中的 key 必须使用步骤二返回的 `field.id`（例如 `mqtt_broker`、`mqtt_port`），严禁使用环境变量大写名（如 `MQTT_BROKER_HOST`），否则会被后端配置解析器静默忽略。
+
 向用户确认修改后，发起热更新请求：
 ```bash
-# 本地 Docker 部署实例更新
-curl -s -X PUT "http://127.0.0.1:3260/api/docker-devices/local/config/<solution_id>" \
+# 本地 Docker 部署实例更新（使用从 GET 返回查得的 field.id）
+curl -s -X PUT "$BASE_URL/api/docker-devices/local/config/<solution_id>" \
   -H "Content-Type: application/json" \
   -d '{
     "values": {
-      "MQTT_BROKER_HOST": "192.168.1.200",
-      "MQTT_BROKER_PORT": 1883
+      "mqtt_broker": "192.168.1.200",
+      "mqtt_port": 1883
     }
   }'
 
 # 远程设备实例更新
-curl -s -X PUT "http://127.0.0.1:3260/api/docker-devices/config/<solution_id>" \
+curl -s -X PUT "$BASE_URL/api/docker-devices/config/<solution_id>" \
   -H "Content-Type: application/json" \
   -d '{
-    "values": { "MQTT_BROKER_HOST": "192.168.1.200" },
+    "values": { "mqtt_broker": "192.168.1.200" },
     "connection": { "host": "<ip>", "username": "<user>", "password": "<pwd>" }
   }'
 ```
-- **后端自动执行**：模板替换 ➔ 生成新的 env ➔ `docker compose up -d` 重新创建受影响容器 ➔ 更新部署 manifest 记录。
+- **后端自动执行**：根据 `field.id` 执行模板替换 ➔ 生成新的 env ➔ `docker compose up -d` 重新创建受影响容器 ➔ 更新部署 manifest 记录。
 - **无需整机重装**，数据卷与现有文件完全保留。
 
 ---
@@ -74,16 +81,41 @@ curl -s -X PUT "http://127.0.0.1:3260/api/docker-devices/config/<solution_id>" \
 
 当用户要求“重启服务”、“暂停运行”或“更新容器镜像”时：
 
+### 本地 Docker 部署实例（无凭据要求）
 ```bash
 # 执行 start / stop / restart / update
-curl -s -X POST "http://127.0.0.1:3260/api/device-management/<deployment_id>/action" \
+curl -s -X POST "$BASE_URL/api/device-management/<deployment_id>/action" \
   -H "Content-Type: application/json" \
   -d '{
     "action": "restart",
     "device_id": "<step_id>"
   }'
 ```
+
+### 远程设备实例（必须显式携带 SSH 认证凭据）
+远程设备（Jetson / Raspberry Pi 等）通过 SSH 协议由底层执行容器编排动作。由于后端安全机制禁用了 SSH-agent 与自动公钥搜寻，且不持久化保存设备明文密码，因此远程操作**必须向用户获取并显式传入 `password` 或 `key_file`**：
+
+```bash
+# 远程实例 - 密码认证
+curl -s -X POST "$BASE_URL/api/device-management/<deployment_id>/action" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "action": "restart",
+    "device_id": "<step_id>",
+    "password": "<ssh_password>"
+  }'
+
+# 远程实例 - 私钥文件认证（支持 ~/.ssh/ 下的私钥路径）
+curl -s -X POST "$BASE_URL/api/device-management/<deployment_id>/action" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "action": "restart",
+    "device_id": "<step_id>",
+    "key_file": "~/.ssh/id_rsa"
+  }'
+```
 - `action` 支持：`start`（启动）、`stop`（停止）、`restart`（重启）、`update`（拉取最新镜像并重启）。
+- **判定规则**：从步骤一 `/api/device-management/active` 的返回值中检查目标实例的 `host` 字段。若 `host` 不为 `localhost` 或 `127.0.0.1`，即属于远程设备，发起 action 请求前必须准备好认证凭据。
 
 ---
 

package/skills/{sensecraft → solution-cli}/references/diagnose.md

@@ -81,7 +81,7 @@ three classes:
 | Class | Example | What you do |
 |---|---|---|
 | **Device / environment** | port taken, disk full, Docker missing, network blocked, wrong password, serial permission | Propose the exact fix commands → user OK → run them → retry |
-| **Solution configuration** | timeout too short, wrong port/env in compose, health check endpoint 404, minor syntax/transfer glitch | **CLI / Engine mode (Auto-healing patch)**: Copy the solution from `~/.sensecraft/content/solutions/<id>` to `./.sensecraft-work/solutions/<id>`, apply the minimal required fix. Stop the previous engine instance (`sensecraft-engine daemon stop`) so it reloads the new solution directory, and redeploy with `--solutions-dir ./.sensecraft-work/solutions` so the user succeeds immediately! Show the user the patch diff. Desktop app running: fix it in the edit copy (`app-only.md` §4) → validate → apply → retry. |
+| **Solution configuration** | timeout too short, wrong port/env in compose, health check endpoint 404, minor syntax/transfer glitch | **CLI / Engine mode (Auto-healing patch)**: Copy the solution from `~/.sensecraft/content/solutions/<id>` to `./.sensecraft-work/solutions/<id>`, apply the minimal required fix, and redeploy with `sensecraft-engine deploy <id> --solutions-dir ./.sensecraft-work/solutions` so the user succeeds immediately! Show the user the patch diff. Desktop app running: fix it in the edit copy (`app-only.md` §4) → validate → apply → retry. |
 | **Engine bug** | exit code 5, a panic in `engine.log`, a step that fails the same way on any device, behaviour contradicting the solution's own config | Stop. Prepare the issue report below |
 
 If the evidence does not fit any row, say so and show the user the first error

package/skills/{sensecraft → solution-cli}/references/secondary-development.md

@@ -65,11 +65,8 @@ git clone https://github.com/Seeed-Studio/ModelAssistant.git ./my-model-assistan
 修改完成后，无需打包推送到 CDN，直接利用 `sensecraft-engine` 的 `--solutions-dir` 特性在本地无缝验证：
 
 ```bash
-# 1. 如果已有守护进程正在运行，先停止释放端口与旧方案缓存
-sensecraft-engine daemon stop
-
-# 2. 从本地自定义工程目录加载方案并执行部署测试
-sensecraft-engine deploy --solutions-dir ./my-solutions/solutions --solution <id>
+# 从本地自定义工程目录加载方案并执行部署测试
+sensecraft-engine deploy <id> --solutions-dir ./my-solutions/solutions
 ```
 - 引擎将直接读取本地工程中的 `solution.yaml`、`devices/*.yaml` 和 `docker-compose.yml`，秒级完成本地部署生效。