@seeed-studio/solution-cli 0.3.1 → 0.4.0

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.1",
-  "description": "Zero-friction installer and CLI runner for SenseCraft Engine and AI Agent Skills (Work Buddy, Claude Code, Codex, CodeBuddy)",
+  "version": "0.4.0",
+  "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,68 @@
 ---
-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
-
-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**.
+# 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**. For Engine-only operations, use the injected absolute Engine path. If the wrapper is not on `PATH`, invoke the CLI as `npx -y --registry=https://registry.npmjs.org/ --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.
+
+## Catalog model and production pages
+
+Treat the catalog as a graph with distinct content types. A **Scenario** is a
+business landing page. It owns links to one or more **Tech** pages and/or
+**Reference Designs (RDs)**. A Tech page is an independently published
+technology or ownership page; it is not a Wiki page and must not be inferred
+from an RD. An RD is the concrete design that can contain architecture,
+products, and a deployment mapping. A deployable RD maps to the executable
+deployment document and presets exposed by the Engine; a website RD without
+that mapping remains informative and is not deployable.
+
+Use the catalog commands progressively:
+
+```bash
+solution-cli hub list --type scenario --locale <en|zh|ja> --page 1 --limit 50 --json
+solution-cli hub get <id> --locale <en|zh|ja> --section overview --json
+solution-cli hub get <id> --locale <en|zh|ja> --section links --json
+solution-cli hub get <id> --locale <en|zh|ja> --section architecture --json
+solution-cli hub get <id> --locale <en|zh|ja> --section products --json
+solution-cli hub get <id> --locale <en|zh|ja> --section playbook --json
+solution-cli hub get <id> --locale <en|zh|ja> --section integration --json
+solution-cli hub get <id> --locale <en|zh|ja> --section deployment [--preset <id>] --json
+```
+
+For a catalog-wide request, page through `hub list` until `has_more` is
+false. For a specific request, search first, then use `hub get` on the chosen
+IDs. For links, call `hub get --section links`; do not scan manifests or write
+an ad-hoc parser. `hub get --section links` returns the production landing
+mapping for all three locales when published, plus separately declared Wiki,
+repository, and document links. The verified landing hosts are:
+
+| Locale | Production host |
+|---|---|
+| English (`en`) | `www.seeed.cc` |
+| Chinese (`zh`) | `www.seeedstudio.com.cn` |
+| Japanese (`ja`) | `www.seeed.co.jp` |
+
+The path and availability must come from the CLI record. Do not construct a
+Wiki route, CDN asset URL, or translated URL from an ID. A missing translation
+may still have a published production route; report the returned content
+locale/fallback separately. A catalog record is not proof that the local
+Engine has the matching content: before deployment, read the actual Engine
+`deploy-info` for the mapped solution ID.
+
+A metadata or links response is not evidence that the content was read. When
+the user asks what a solution does, how it is built, or which products it
+uses, call `hub get` for the chosen `description`, `architecture`, or
+`products` section and use that returned body. When a returned production page
+or architecture image is material to the answer, open that exact returned
+URL and state what was checked. When a solution includes an architecture diagram
+(from `architecture_preview` or `hub get --section architecture`), present the
+official architecture image to the user, render an editable Mermaid flowchart
+based on its topology summary, and offer to customize the topology. A relative asset
+path is usable only when the matching signed local content is present; otherwise
+report the source asset as unavailable instead of treating the URL as an image that
+has been reviewed.
 
 ## Workflow Routing & Progressive Disclosure
 
@@ -13,13 +70,30 @@ Do NOT read all reference files at once. Determine the user's workflow state and
 
 | User State & Intent | Reference to Load | Primary CLI Tool to Call | Guardrails & Forbidden Actions |
 |---|---|---|---|
-| **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 <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. |
+| **DISCOVERY / CONSULT**<br>“我想做防跌倒监控”、“有智慧农场方案吗” | `references/consult-and-select.md` | `solution-cli hub search "<keyword>" --json`, then `hub get <id> --sections architecture,playbook --json` | **DO NOT run deploy**; search exposes `available_sections` and evidence status (`documented`/`generic`/`inferred`). Batch fetch architecture and playbook in 1 roundtrip. |
+| **PROCUREMENT / VERIFY_BOM**<br>“买什么硬件？”、“J4012 需要配什么配件？” | `references/hardware-bom.md` | `solution-cli product accessories <id> [--category <power,camera>] --compact --json` | **DO NOT fabricate** third-party SKUs or prices. Always distinguish REQUIRED vs OPTIONAL accessories. Use `--compact` and `--category` to save tokens. |
+| **ONBOARDING / PRECHECK**<br>“设备到了，插上了网线/USB”、“环境自检”、“发现新设备” | `references/diagnose.md` & `references/device-management.md#0` | `solution-cli doctor` / `sensecraft-engine device scan` | **Early & Proactive**: Check device firmware & drivers early. Intercept and prompt for reCamera firmware/patch or SBC env fixes before deploy. |
+| **DEPLOYING / APPLY**<br>“开始安装”、“部署 fall_detection” | `references/deploy.md` | `solution-cli hub get <id> --section deployment --preset <id> --json` then `sensecraft-engine deploy <id>` | **DEPLOYMENT CRITICAL SECTION**: Zero external commercial queries allowed during apply. Filter guide with `--preset` to reduce token bloat. |
+| **INTEGRATION / INGESTION**<br>“怎么接到我们系统”、“MQTT主题是什么”、“Webhook格式”、“接入 Home Assistant” | `references/device-management.md#5` | `solution-cli hub get <id> --section integration --json` | **System Ingestion**: Provide exact MQTT topics, payload schemas, Webhook endpoints, and port mappings directly from verified integration contract. Batch with `--sections architecture,integration` if needed. |
+| **MANAGE / RECONFIG**<br>“改一下 MQTT 地址”、“换模型/业务流”、“重启服务”、“修改配置”、“打本地补丁”、“换应用镜像” | `references/device-management.md` | `curl BASE/api/docker-devices/local/config/<id>` / `solution-cli doctor` | **On-Demand (JIT)**: Only query when user requests application-layer modifications. Apply tiered hotpatches without touching underlying OS. |
+| **FEASIBILITY / SALES_EVAL**<br>“我们能不能做这个？”、“非标需求评估”、“需求匹配度如何”、“做这个要多久” | `references/sales-feasibility.md` | `solution-cli hub search "<keyword>" --json` / `product query <family>` | **DO NOT make blind promises**. Strictly follow the 4-tier feasibility matrix and scoring criteria. |
 | **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. |
+| **EDGE_GOTCHAS / HARDWARE_DEBUG**<br>“3576/3588编译报错”、“/dev/rknn打不开”、“recamera崩溃”、“VPSS overflow”、“fork风暴”、“高卡/踩坑” | `references/edge-gotchas.md` | `solution-cli gotchas "<keyword>" [--chip <chip>] --json` / `dmesg \| grep -i -E "rknpu\|vpss\|fifo\|oom"` | **Brand-agnostic**: Focus on generic 3576, 3588, reCamera, reCamera Pro, and MCU gotchas and hardware traps. |
+| **TROUBLESHOOTING**<br>“部署报错”、“黑屏”、“无视频流” | `references/error-catalog.md` | `sensecraft-engine logs` / `solution-cli gotchas "<symptom>" --json` | Max 3 fix-and-retry rounds. Follow local auto-patching rule. |
+
+### Progressive Disclosure & Multi-Section Fetch
+During discovery, `hub search` returns records with `available_sections` and their status (`section_status`: `documented`, `inherited`, `generic`, `inferred`).
+Instead of multiple roundtrips, retrieve multiple sections at once:
+`solution-cli hub get <id> --sections architecture,integration --json`
+To retrieve single sections:
+- `overview`: basic metadata, tags, and progressive directory navigation
+- `links`: landing pages, wiki, repo, and declared documents
+- `description`: deep solution background and functional breakdown
+- `architecture`: modules, block diagrams, topology, and gallery
+- `products`: bill of materials (BOM), required vs optional hardware
+- `deployment`: deployment steps (use `--preset <id>` to filter and reduce token usage)
+- `playbook`: field diagnostic questions and engineering rationales
+- `integration`: system ingestion contracts (MQTT topics, Webhooks, REST endpoints)
 
 Capabilities that need the **SenseCraft Solution desktop app** (editing a
 solution's configuration, the app's `/api/ai/context`, diagnosing through the
@@ -52,12 +126,7 @@ daemon is a host prerequisite, not evidence that a deployment has passed.
 
 ## Rules
 
-1. **Credentials and secrets:** never invent a host, username or password —
-   ask the user. Replace passwords, tokens, API keys and any other secret a
-   deployment prints (for example a gateway token) with `<REDACTED>` in
-   anything you show or log. Tell the user where to find the value (on the
-   device, in the solution's page, in the file that holds it) instead of
-   printing it.
+1. **Credentials and secrets (Zero-Plaintext-Password):** NEVER ask the user to send raw passwords, API keys, or private tokens into the chat context (this triggers LLM safety refusal guardrails and risks credential leakage). Always prefer SSH Key-based authentication (defaulting to `~/.ssh/id_ed25519` or `~/.ssh/id_rsa`). If the remote target lacks key-trust, guide the user to run `ssh-copy-id -i ~/.ssh/id_ed25519.pub <user>@<host>` in their local terminal. Replace any echoed secrets with `<REDACTED>`. Never invent hosts or usernames.
 2. **What you may do without asking, and what needs the user's OK:**
 
    | Action | Ask first? |
@@ -93,15 +162,16 @@ daemon is a host prerequisite, not evidence that a deployment has passed.
    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.
+   supplemental reading / procurement / code exploration. Search and product
+   results may include attribution parameters when the CLI adds them; links
+   returned by `hub get --section links` are declared URLs and must be used as
+   returned.
 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.
+   Agent must avoid one-way monologues. Use a returned `diagnostic_playbook` only
+   when the selected search result actually contains one; otherwise use the
+   domain matrix in `references/consult-and-select.md` §3 and label the questions
+   as general engineering checks. Ask 2–3 targeted questions explaining the
+   rationale (topology, asset reuse, power/cabling, inspection speed/materials).
 
 ## Step 0 — Install the engine and the solutions (when needed)
 
@@ -126,10 +196,36 @@ daemon is a host prerequisite, not evidence that a deployment has passed.
    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 -y --registry=https://registry.npmjs.org/ @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 --registry=https://registry.npmjs.org/ @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 --registry=https://registry.npmjs.org/ @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.
+
+   **Routine Update & Skill Synchronization**:
+   ```bash
+   solution-cli update -y
+   ```
+   (Automatically checks signed stable Engine, increments content definitions with `content update`, and synchronizes skills for all managed agents).
+
+   **Custom or Third-party Agent Extension**:
    ```bash
-   npx -y @seeed-studio/solution-cli@latest install -y
+   solution-cli install --skills-dir <path> -y
    ```
+   (Injects Solution CLI skills into any custom, internal, or proprietary AI Agent skill directory).
 
    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
@@ -138,9 +234,8 @@ daemon is a host prerequisite, not evidence that a deployment has passed.
    `--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 upgrade rules start with
-   solution-cli 0.3.1; if npm `latest` is still 0.3.0, those rules are not live.
-   At this verification, 0.3.1 is pending publication. Latest/signature failure
+   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)**:

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. 工具调用标准动作
@@ -26,20 +28,66 @@
 使用命令：
 ```bash
 solution-cli hub search "<用户关键词>" --limit 5 --json
+solution-cli hub get <chosen-id> --locale <en|zh|ja> --section overview --json
+solution-cli hub get <chosen-id> --locale <en|zh|ja> --section links --json
 ```
+- **咨询顺序**：先用用户原话和同义技术词查询，再对选中的 Scenario、Tech 或 RD 调用 `hub get`；只有需要回答架构、产品或部署问题时，才追加 `--section architecture|products|deployment`。根据返回的 `diagnostic_playbook` 拆解需求；向用户确认点位、协议、供电、通信、控制闭环和预算等关键参数后，给出可提供的方案、硬件方向和缺口说明。
+- **内容核验**：链接或 metadata 只用于定位，不代表已经阅读内容。用户问方案能力、架构或产品时，必须读取选中记录对应的 `description`、`architecture` 或 `products` section；确切生产页或架构图影响答案时，再打开 CLI 返回的确切 URL/图片并说明核验范围。相对资源路径只有在签名本地内容实际存在时才可读取，否则标为 source asset 未就绪。
+- **交付边界**：咨询阶段只做检索、需求澄清和方案建议，不自动执行 `deploy`；用户确认硬件和部署目标后，再转入硬件校验或部署流程。
 - **输出结果说明**：
-  - `Scenario`：业务场景、痛点、成效、官方场景落地页（`landing_url`）；
-  - `Reference Design`：技术路线、预设模式 presets、开发 wiki（`wiki_url`）、官方方案落地页（`landing_url`）、源码仓库（`repo_url`）；
+  - `Scenario`：业务场景、痛点、所属 Tech/RD 关系、生产落地页链接；
+  - `Tech`：独立技术/归属页及其明确关联的 Scenario/RD；不要把 Tech 当作 Wiki 或 RD；
+  - `Reference Design`：具体架构、产品说明、部署文档/预设、生产落地页和已声明的 Wiki/源码链接；只有存在部署映射时才称为可部署；
   - `family_ids`：推荐的主板/相机/网关产品族。
 
+### 动作二：识别页面归属与可部署映射
+
+页面关系按 `Scenario → Tech / Reference Design` 的显式关系读取。落地页
+是业务入口，技术页是独立内容归属，RD 是具体设计；不要根据标题、slug
+或同名关系补出边。每个 RD 的一键部署入口都对应一个部署文档和 preset
+映射。先读取：
+
+```bash
+solution-cli hub get <rd-id> --locale <en|zh|ja> --section architecture --json
+solution-cli hub get <rd-id> --locale <en|zh|ja> --section products --json
+solution-cli hub get <rd-id> --locale <en|zh|ja> --section deployment --json
+```
+
+架构内容只把明确标注为 architecture 的图或 tab 称为架构图；其他图片
+保留为 gallery。产品说明、BOM、架构图和部署文档要标明内容语言与来源。
+`deployment` 返回的是目录中的部署映射，不等于本机已经安装；实际执行
+前必须用 Engine 查询该映射的真实 `solution_id`：
+
+```bash
+sensecraft-engine deploy-info <solution-id> --lang <en|zh>
+```
+
+生产落地页按请求语言直接使用 CLI 返回的 URL。当前生产域名是英文
+`www.seeed.cc`、中文 `www.seeedstudio.com.cn`、日文 `www.seeed.co.jp`；
+不要把三者统一替换成另一个域名，也不要自行拼接 `/wiki` 或资产 CDN
+路径。Wiki 只有在返回的已发布/授权元数据中存在时才展示。
+
+### 动作三：呈现官方架构图与可编辑拓扑 (Architecture Presentation & Mermaid)
+
+当方案检索或通过 `hub get <id> --section architecture` 匹配到方案包含官方架构图时（数据中包含 `architecture_preview` 或 `architecture.image_url`/`architecture.intro`）：
+1. **推荐并呈现官方参考架构图**：在向用户回复方案介绍时，直接嵌入官方高清参考架构图的 Markdown 引用：
+   ```markdown
+   ![<方案名称>架构图](<image_url>)
+   ```
+   向用户说明这是经过官方实测验证的标准拓扑结构与设备选型。
+2. **生成可二次编辑的通用 Mermaid 拓扑**：基于架构图返回的拓扑摘要（`summary`）与连接关系，紧随其后生成一份结构清晰的 Mermaid 流程图（`flowchart LR`）：
+   - 按分层划分子图（`subgraph`）：采集现场（Sensor/Camera/Mic）、边缘算力与主机（Edge Host/Gateway）、平台管理与应用（Cloud/Platform/Web Console）；
+   - 在连线上准确标注通信介质与协议（如 USB、RTSP、MQTT、HTTP、BLE、LoRaWAN、Modbus）；
+3. **主动提示可修改定制**：说明“此拓扑为官方基准设计；若现场有特殊工况（如由云端改为纯局域网离线、更换通信总线、接入已有摄像头/传感器），可直接基于该 Mermaid 流程图调整修改”，方便用户或方案人员快速二次编辑。
+
 ---
 
 ## 3. 现场工况诊断与场景提问知识库 (Domain Diagnostic Playbook)
 
 > [!IMPORTANT]
 > **拒绝自说自话！真正的方案专家不仅回答问题，更主动诊断现场工况。**
-> 当用户提出场景诉求时，调用 `solution-cli hub search "<关键词>" --json` 会在返回记录中直接携带该场景的 `diagnostic_playbook`。
-> Agent **必须结合工况诊断知识库，主动提出 2~3 个决定物理架构、通信链路与商务成本的关键问题**，并解释“为什么问这个问题”（如利旧省钱、避免停机、规避环境干扰）。
+> 当用户提出场景诉求时，先调用 `solution-cli hub search "<关键词>" --json`。如果选中的返回记录带有 `diagnostic_playbook`，可以使用其中的问题；当前 CLI 的 compact search 结果可能不带该字段，此时使用本节矩阵，并明确这是通用工程核查。
+> Agent **必须结合可用的工况诊断信息，主动提出 2~3 个决定物理架构、通信链路与商务成本的关键问题**，并解释“为什么问这个问题”（如利旧省钱、避免停机、规避环境干扰）。
 
 ### 3.1 四大底层工程决断杠杆 (The 4 Engineering Levers)
 
@@ -48,7 +96,7 @@ solution-cli hub search "<用户关键词>" --limit 5 --json
 | 工程决断杠杆 | 核心影响与决断依据 | 典型追问切入点 |
 |---|---|---|
 | **1. 物理拓扑分布**<br>(集中式 vs 分布式) | 决定是采用“1 台计算主机集中拉流/汇聚”（极度摊薄单点算力成本），还是“分布式独立一体化终端”（免拉长线、点位隔离）。 | “点位是在同一栋楼/同一车间集中分布，还是分散在多处？” |
-| **2. 存量资产利旧**<br>(绿地新建 vs 棕地利旧) | 决定是否能直接复用客户现有的监控摄像头（RTSP/ONVIF）、传感器（RS485/Modbus）或 PLC，为客户节省 50%~70% 硬件采购成本。 | “现场是否已经有现成的摄像头/传感器？支持什么协议？” |
+| **2. 存量资产利旧**<br>(绿地新建 vs 棕地利旧) | 决定能否在协议、带宽、供电和性能满足时复用客户现有的监控摄像头（RTSP/ONVIF）、传感器（RS485/Modbus）或 PLC；具体节省量必须基于现场清单核算。 | “现场是否已经有现成的摄像头/传感器？支持什么协议？” |
 | **3. 供电与通信边界**<br>(市电 vs 电池 / 有线 vs 无线) | 决定供电配件（220V 电源适配器 vs 太阳能/电池休眠机制）以及网络介质（PoE 网线、Wi-Fi、4G 插卡、LoRaWAN 远距离低功耗）。 | “安装点是否有 220V 市电？是否方便布设网线（PoE）？” |
 | **4. 业务执行与闭环联动**<br>(被动看板 vs 主动控制) | 决定硬件接口规格（是否需要工业隔离数字量 I/O、继电器触点、CAN 总线）以及告警延迟容忍度。 | “判定异常后，是仅在大屏/手机告警，还是需直接联动 PLC/气缸/道闸执行控制？” |
 
@@ -74,21 +122,21 @@ solution-cli hub search "<用户关键词>" --limit 5 --json
 ## 4. 推荐应答呈现规范（自然专家与诊断对话风格）
 
 向用户作答时，采用流利、专业的对话口吻，涵盖以下要素：
-1. **方案业务价值与实现逻辑**（直接讲透）：解释为何能在端侧解决问题、响应时间、隐私优势；
+1. **方案业务价值与实现逻辑**（直接讲透）：解释返回内容能证实的端侧处理、响应和隐私边界；没有实测或来源的性能数字不得补充；
 2. **两类硬件架构对比**：说明一体机与工控机/Jetson 的各自适用场景；
-3. **参数可调性预告**：告知常见参数（如 MQTT 地址、检测灵敏度）部署后支持在线热修改；
+3. **参数可调性预告**：只有在部署内容或管理接口返回 `reconfigurable` 字段时，才说明 MQTT 地址、检测灵敏度等参数支持在线修改；
 4. **自然延伸出口**：随口附上“了解更多”落地页与技术 Wiki；若涉及二次开发提供 GitHub 源码；
 5. **主动诊断追问（结合理由）**：提出针对该领域的 2~3 个工况诊断关键问题，并简明说明“为什么这样问能帮您优化方案或降低成本”。
 
 #### 范例 1：智慧农业 / 环境监测咨询
 > 做农业温室大棚和农田监测，推荐采用 **`agri_env_monitor`（农业环境监测方案）**。
 >
-> 它的架构是在现场测点布设工业级气象与土壤传感器，通过无线或工业总线将数据汇聚到本地网关（如 SenseCAP M2 或 reComputer），本地部署 Home Assistant 或轻量时序看板进行温湿度曲线、土壤墒情实时显示与越限告警。**系统支持完全纯本地离网运行，也可以通过 MQTT / 4G 桥接上云**。
+> 当前目录中的 `agri_env_monitor` 可通过 `hub get --section deployment` 查看部署映射；实测返回 `cloud`、`tts_local`、`chirpstack_local` 三个 preset 和 `guide.md`/`guide_zh.md`，但其 RD 注册状态为 review，生产落地页链接为空。这表示可以继续读取目录中的部署内容进行诊断，不能把它当作已发布生产页面。架构和产品说明应分别读取 `--section architecture` 与 `--section products`。
 >
 > - **硬件组合**：大棚内部通常采用 **SenseCAP S2100 采集器 + 工业级土壤三参数探头（水分/EC/温度）**；如果需要户外微气象，可搭配 **S700 七合一气象站**。
-> - **参数灵活性**：数据上报周期（如 5 分钟、15 分钟）、温度报警阈值、MQTT 上报服务器等，部署后均支持在线随时调整。
+> - **参数灵活性**：是否可在线修改要以实际部署内容返回的 `reconfigurable` 字段和管理接口为准。
 >
-> 💡 *如果想了解更多具体参数与传感器配件，可以浏览 [官方方案主页](https://www.seeedstudio.com/solutions/reference-designs/agri_env_monitor?utm_source=sensecraft_agent&utm_medium=solution_consult&utm_campaign=agri_env_monitor)；方案的看板与协议转换配置代码也开源在 [GitHub 仓库](https://github.com/suharvest/sensecraft-solutions/tree/main/solutions/agri_env_monitor)。*
+> 💡 *如果想了解更多具体参数与传感器配件，先对选中的 RD 执行 `solution-cli hub get <rd-id> --locale <en|zh|ja> --section links --json`，使用返回的对应语言生产落地页和已声明的源码链接。不要从方案 ID 拼接网址。*
 >
 > ---
 > **为了帮您设计最合理、施工最方便的硬件选型与网络拓扑，我想先了解几个现场工况：**
@@ -99,12 +147,12 @@ solution-cli hub search "<用户关键词>" --limit 5 --json
 #### 范例 2：工业流水线视觉质检咨询
 > 做产线表面缺陷或装配防错质检，通常推荐采用 **`edge_inspection_surface`（工业表面缺陷边缘质检方案）**。
 >
-> 它的机制是在工位上方架设工业相机，通过硬件触发或光电开关触发抓拍，边缘算力机（如 reComputer Jetson Orin）在端侧执行毫秒级缺陷分割或分类模型推理，**平均单帧判定时间在 20~40 毫秒以内，判定结果本地直接输出 OK/NG**，视频流无需上传云端。
+> 具体架构和推理链路必须读取选中 RD 的 `architecture` section；实测 `acoustic-audio-ai` Tech 记录返回 4 个架构模块，并带有明确的 architecture 图片 URL。当前 CLI 只把来源明确标注的模块或架构图作为架构内容，不从方案名称推断响应时间或输出闭环。
 >
 > - **硬件算力**：单工位常规线速可采用 **reComputer J3011 (Orin Nano 8GB)**；如果是高节拍复杂缺陷或多工位合并，推荐 **reComputer J4012 (Orin NX 16GB)**。
-> - **接口与参数**：置信度阈值、缺陷最小像素面积均支持热配置，无需重新编译镜像。
+> - **接口与参数**：实测 `conversational_voice_ai` RD 的 `products` section 返回 6 个产品条目；是否支持热配置要以部署内容和管理接口的实际字段为准，不从示例文案推断。
 >
-> 💡 *更多机械安装与光学镜头打光指导可参考 [方案落地页](https://www.seeedstudio.com/solutions/reference-designs/edge_inspection_surface?utm_source=sensecraft_agent&utm_medium=solution_consult&utm_campaign=edge_inspection_surface)；模型部署与 TensorRT 推理管线见 [GitHub 仓库](https://github.com/suharvest/sensecraft-solutions/tree/main/solutions/edge_inspection_surface)。*
+> 💡 *更多机械安装与光学镜头打光指导，先对选中的 RD 执行 `solution-cli hub get <rd-id> --locale <en|zh|ja> --section links --json` 和 `--section architecture --json`，只使用返回的生产落地页、已发布 Wiki 和源码链接。*
 >
 > ---
 > **为了确定相机快门、打光方案与工控机选型，我先跟您确认三个关键细节：**

package/skills/solution-cli/references/deploy.md

@@ -0,0 +1,112 @@
+# Deploy a solution
+
+Run Step 0 in `SKILL.md` first. Use `--lang zh` for a Chinese user and `--lang en` for an English user. The examples below use the absolute Engine path injected into the installed Skill; keep that path in place of `sensecraft-engine` when required.
+
+## 1. Find the solution
+
+```bash
+solution-cli hub search "<user request>" --limit 5 --json
+solution-cli hub get <reference-design-id> --locale <en|zh|ja> --section deployment --json
+sensecraft-engine solution list --json
+```
+
+The Hub record identifies the business Scenario, its related Tech/RD records,
+the deployment-document mapping, and production links. Match the request to a
+Reference Design first; do not treat a Scenario or Tech page as an executable
+solution. Then use the Engine's local list and `deploy-info` to confirm that
+the mapped `solution_id` and presets are actually installed. If several RDs
+fit, explain the difference and ask which one to use.
+
+## 2. Read what the deployment needs
+
+```bash
+sensecraft-engine deploy-info <id> --lang zh
+sensecraft-engine doctor --json
+sensecraft-engine device ports
+sensecraft-engine device scan --timeout 5
+```
+
+Read `presets[]`, `steps[]`, `device_connections`, `selected_devices`, and `request_template` from `deploy-info`. A preset with more than one variant requires the user's choice. Fill every `<REQUIRED: ...>` value from the user or a read-only device check; never invent device IDs, connection keys, SSH credentials, serial ports, or Docker targets.
+
+For a `docker_deploy` step, use the target listed by `deploy-info` and copy its `type` into `target_type` (`local` or `remote`). Linux local and remote targets may declare `auto_install_docker`; the engine can install Docker/Compose when that option is enabled, but offline installation requires matching packages to be obtainable and usable permissions to already exist. Windows native local Docker is unsupported; use a Linux Docker host over SSH. macOS local Docker requires the user to install and start Docker Desktop first. The CLI does not install Docker Desktop or silently obtain `sudo`.
+
+## 3. Fill in and confirm (Zero-Plaintext-Password Protocol)
+
+> [!IMPORTANT]
+> **严禁在会话中索要、输出或接收用户的明文 SSH 密码！**（会触发主流大模型安全拒答拦截，且存在凭证泄露与历史污染风险）。
+> - **标准且唯一支持认证方式**：采用 SSH 密钥免密认证 (`key_file: "~/.ssh/id_ed25519"` 或 `~/.ssh/id_rsa`)。
+> - **若用户设备尚未配置免密公钥**：引导用户在其**本地终端**执行一次免密分发：
+>   ```bash
+>   ssh-copy-id -i ~/.ssh/id_ed25519.pub <user>@<device_ip>
+>   ```
+>   *(若本地尚无 Ed25519 密钥对，先执行 `ssh-keygen -t ed25519 -N ""` 一键创建)*。
+>   输入密码的交互在用户独立本地终端完成，密码绝不流经大模型上下文，亦不留在会话与历史中。
+> - **部署参数统一使用 `key_file`**：SenseCraft Engine 的部署请求格式要求远程目标通过 `key_file` 进行连接。严禁在聊天框索取明文密码。
+
+Write the completed request to `./.sensecraft-work/body.json`, keeping credentials out of the command line:
+
+```json
+{
+  "solution_id": "<id>",
+  "preset_id": "<preset>",
+  "selected_devices": ["<step_id>"],
+  "device_connections": {
+    "<step_id>": {
+      "target": "<target_id>",
+      "target_type": "remote",
+      "host": "192.168.1.50",
+      "username": "<user>",
+      "key_file": "~/.ssh/id_ed25519"
+    }
+  }
+}
+```
+
+Remote SSH uses a regular key under `~/.ssh` or the Engine data directory (`id_ed25519` / `id_rsa`). Serial steps need both `port` and `serial_port` when the template contains both. Add `auto_replace_containers: true` only after the user agrees to replace existing containers.
+
+Before a remote deployment, run the no-change validation:
+
+```bash
+sensecraft-engine validate --params ./.sensecraft-work/body.json
+```
+
+Read `side_effects` and report any `sudo`, Docker daemon configuration or restart, package install, system configuration, reboot, firmware flash, or local script operation. Stop for user approval if a listed effect is outside the agreed scope. Save `/etc/docker/daemon.json` before a remote deployment when it exists so a later restoration can be reviewed separately.
+
+## 4. Start and follow
+
+```bash
+sensecraft-engine deploy --params ./.sensecraft-work/body.json --yes --detach --lang zh
+sensecraft-engine status <deployment-id> --json
+sensecraft-engine logs <deployment-id> --since <N>
+```
+
+Keep the returned `deployment_id`. Poll `status` until it is `completed`, `failed`, `cancelled`, or `interrupted`; read `logs` with the last event sequence. `--follow` can stream logs when the command timeout allows it. A request error (exit 2) needs corrected fields; a busy device (exit 3/409) needs the other deployment resolved first.
+
+Without `--detach`, `deploy --json` waits for the final result. Interrupting the client only detaches from the running Engine deployment; continue with `status` and `logs`.
+
+## 5. Verify
+
+`completed` is not by itself service verification. Handle every `verify_required` event with `verify.md`, then check the target:
+
+- Docker services remain `running` and healthy. Use `sensecraft-engine docker ps --json` locally or the remote form documented by the Engine help.
+- Service endpoints return the expected 2xx/3xx response.
+- For services with a health check, check once more after about 60 seconds and inspect restart counts for a crash loop.
+
+Report the URL, device, deployed solution, and verification evidence. Do not report success when a container restarts, disappears, or its endpoint stops answering.
+
+## 6. If anything failed
+
+Go to `diagnose.md` with the `deployment_id`. Retry only after reading the error. Transient registry or network errors may be retried up to five times with increasing waits; deterministic credential, parameter, disk, port, or container errors require a fix before retry and at most three rounds.
+
+To retry a partial deployment, reuse the same request body and list only failed devices. Do not change the preset or target values while diagnosing a failure. Keep the body file private and remove `./.sensecraft-work/` after the deployment workflow completes.
+
+## Cancel
+
+Only after the user approves cancellation:
+
+```bash
+sensecraft-engine cancel <deployment-id>
+sensecraft-engine status <deployment-id> --json
+```
+
+Wait for `cancelled` and report which steps had already run; a cancelled deployment may leave a device partially configured.