@seeed-studio/solution-cli 0.3.2 → 0.4.1

package/docs/cli-guide.md

@@ -1,9 +1,7 @@
-# SenseCraft Solution CLI 使用与集成全景指南
-*(SenseCraft Solution CLI & AI Agent Skill Guide)*
+# Solution CLI 使用与集成指南
+*(Solution CLI & AI Agent Skill Guide)*
 
-> **定位**：本文档专门面向**方案架构师、现场应用工程师 (FAE)、嵌入式开发者以及 AI Agent (Claude Code / Codex / Antigravity / Work Buddy)**，系统性说明 `@seeed-studio/solution-cli` 的独特应用场景、安装流程、各功能指令的具体使用方式以及核心产出物。
-
----
+本文档面向方案架构师、现场工程师、开发者和 AI Agent。安装一次 `solution-cli` Skill 后，用户可以用自然语言完成方案咨询、硬件选型、部署前检查、本地/远程方案部署和部署后诊断。
 
 ## 目录
 
@@ -11,295 +9,265 @@
 2. [安装与 Agent 技能挂载](#2-安装与-agent-技能挂载)
 3. [核心功能、使用方法与具体产出](#3-核心功能使用方法与具体产出)
    - [场景一：方案探索与工况诊断 (Hub Search)](#场景一方案探索与工况诊断-hub-search)
-   - [场景二：硬件产品规格与配件防呆评估 (Product & BOM)](#场景二硬件产品规格与配件防呆评估-product--bom)
-   - [场景三：设备状态感知与参数热修改 (Device Management)](#场景三设备状态感知与参数热修改-device-management)
-   - [场景四：自研模型替换与本地二次开发 (Secondary Dev)](#场景四自研模型替换与本地二次开发-secondary-dev)
+   - [场景二：硬件配置与配件选型（“买这个设备需要配什么配件？会不会买错？”）](#场景二硬件配置与配件选型买这个设备需要配什么配件会不会买错)
+   - [场景三：方案一键部署与本地/远程运行 (Solution Deployment)](#场景三方案一键部署与本地远程运行-solution-deployment)
+   - [场景四：设备状态感知与参数热修改 (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` 提供三类能力：
 
-`@seeed-studio/solution-cli` 正是为解决这一系列问题而生，它具有三大独特角色：
-1. **方案专家的现场诊断仪**：内置各大行业工况诊断知识库，不仅能搜方案，还能直接指导工程师向客户提出决定成本与物理拓扑的“黄金追问”；
-2. **硬件采购防呆中枢**：内置物理规格匹配引擎，自动核算【必需配件】与【可选配件】，从源头阻断硬件返工；
-3. **AI Agent 的物理世界触手**：一键将 solution-cli Skill 注入到主流 AI Agent 宿主中，让 Agent 具备从方案咨询、BOM 选型到现场部署、参数热更的全生命周期驱动能力。
+- 根据客户工况搜索方案，并列出仍需确认的问题。
+- 查询硬件规格、配件和物理兼容性。
+- 通过签名 Rust Engine 预检查并在本地或远程部署已选方案，持续读取状态、日志和验证结果。
 
----
+Agent 的默认工作流是“先咨询，再选型，再检查，最后在用户确认后部署”。用户只需描述目标，例如“帮我给锅炉房的 10 个恒温器设计改造方案”，Agent 应先查询方案并询问网络、供电、设备、温度约束和部署位置，不应把客户询盘直接当作部署授权。
 
 ## 2. 安装与 Agent 技能挂载
 
-### 2.1 一键免安装即时调用 (推荐)
-无需全局安装，安装或按需升级 Engine 与 Agent Skill 使用同一条命令：
+### 2.1 按需精准安装（推荐：npm 全局安装并挂载，避免 PATH 缺失报错）
+
+你可以直接复制下表中对应的专属命令发给对应的 AI 助手，或在终端执行：
+
+| 目标 AI 宿主平台 | 专属安装命令（直接复制发给 AI 或在终端运行） | 技能默认配置路径 |
+|---|---|---|
+| **豆包工作 (Doubao Work)** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent doubao` | `~/.doubao/skills` |
+| **Claude Code** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent claude` | `~/.claude/skills` |
+| **OpenAI Codex** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent codex` | `~/.agents/skills` 或 `~/.codex/skills` |
+| **Google Antigravity** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent antigravity` | `~/.gemini/config/skills` |
+| **WorkBuddy** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent workbuddy` | `~/.workbuddy/skills` |
+| **CodeBuddy** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent codebuddy` | `~/.codebuddy/skills` |
+| **Hermes Agent** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent hermes` | `$HERMES_HOME/skills` (默认 `~/.hermes/skills`) |
+| **全部 Agent (全量覆盖)** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent all` | 上述全部已检测目录 |
+| **自定义目录 (如 Cursor)** | `npm install -g @seeed-studio/solution-cli && solution-cli install --skills-dir <路径>` | `<自定义路径>/solution-cli` |
+
+> [!TIP]
+> - **为什么推荐 npm 全局安装？** 将 `solution-cli` 加入全局 PATH，AI Agent 在后续对话中调用方案/硬件查询时直接本地毫秒级响应，避免因 PATH 缺失触发 `command not found`。
+> - **发给 AI 助手**：例如在豆包工作中直接发送：*“请帮我运行：`npm install -g @seeed-studio/solution-cli && solution-cli install --agent doubao`”*。
+> - **免全局安装（npx 备选）**：如无全局 npm 写入权限，可使用 npx：`npx -y @seeed-studio/solution-cli install --agent <id>`。
+
+### 2.2 本地源码部署与定制开发 (Local Deployment)
+
+如果你在本地仓库进行开发或调试，可以直接使用源码安装，无需经过 npm：
+
 ```bash
-npx -y @seeed-studio/solution-cli@latest install --agent workbuddy -y
+# 针对特定 Agent 安装
+node bin/cli.js install --agent <doubao|claude|codex|antigravity|codebuddy>
+
+# 挂载到自定义目录
+node bin/cli.js install --skills-dir ~/.cursor/skills
 ```
 
-上面的示例明确安装到 WorkBuddy。其他宿主将 `workbuddy` 替换为当前实际的
-Agent ID。需要交互选择时使用 `npx -y @seeed-studio/solution-cli@latest install`；
-检测到一个或多个 Agent 时，直接回车默认选择全部已检测的 Agent，输入对应序号
-选择指定宿主。非交互模式下，`install -y` 未提供 `--agent` 且检测到 Agent 时也会
-选择全部已检测的 Agent。未检测到 Agent 时，这些默认仍使用 CLI 的默认目标集合；
-需要明确控制范围时请提供 `--agent <agent-id>`。
-
-首次安装和重复执行都会检查签名稳定版 Engine：本机已有相同或更新版本
-时复用，版本较旧时升级。普通安装保留用户修改、未登记的 Skill 文件和受
-保护的符号链接。需要指定宿主时追加 `--agent claude,antigravity`；需要固
-定有效本地 Engine 时使用 `--engine-path <path>`。`--force` 可重新下载相同
-或较旧版本并覆盖已有 Skill 文件（包括用户修改），请只在有意覆盖时使用；
-受保护的外部符号链接不会追写，也不能降级更新的本机 Engine。
-
-自动复用/升级规则自 solution-cli 0.3.1 起生效；该版本已公开发布。latest 检查或签名校验失败会在
-修改 Engine、指针或 Skill 前停止；离线时请提供有效的 `--engine-path`。
-
-The same command handles a fresh install and a user-requested upgrade. It checks
-the signed stable Engine, reuses an equal/newer local version, preserves modified
-skills, and stops before writes on latest/signature failure. Automatic reuse and
-upgrade rules start with publicly published solution-cli 0.3.1. The example
-targets WorkBuddy with `--agent workbuddy`; replace it with the current Agent ID
-for another host. Use `npx -y @seeed-studio/solution-cli@latest install` for the
-interactive form: when one or more Agents are detected, pressing Enter selects
-all detected Agents, while entering a 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.
-
-### 2.2 全局安装
+省略 `--agent` 时，终端交互运行会进入选择器；非交互运行会安装到已检测的宿主，未检测到宿主时会选择全部宿主。建议始终明确指定当前 Agent。重复执行会复用相同或更新的签名 Engine、升级旧版本，并保留用户修改的 Skill。`--force` 会覆盖已有 Skill 修改，只在用户明确要求时使用。
+
+安装完成后刷新宿主的 Skill 列表或完全退出并重新打开 Agent 应用，确认宿主的实际 Skill 列表中已出现 `solution-cli`，再新建会话直接描述需求。若宿主未自动发现技能，发送：“请使用 solution-cli Skill，先查询方案，再告诉我缺哪些部署信息。”安装器只写入被选中的宿主。
+
+### 2.3 全局安装与 Profile
+
+需要长期使用 `solution-cli` 命令时可以全局安装：
+
 ```bash
-npm install -g @seeed-studio/solution-cli
-solution-cli install --agent workbuddy -y
+npm install -g --registry=https://registry.npmjs.org/ @seeed-studio/solution-cli@latest
+solution-cli status
 ```
 
-全局安装后的挂载规则相同：示例明确选择 WorkBuddy；其他宿主请将
-`workbuddy` 替换为当前实际 Agent ID。交互执行 `solution-cli install` 时，
-检测到一个或多个 Agent 后直接回车选择全部已检测的 Agent，输入对应序号选择指定
-宿主；非交互执行 `solution-cli install -y` 且未提供 `--agent` 时，检测到 Agent
-也会选择全部已检测的 Agent。未检测到 Agent 时，这些默认仍使用 CLI 的默认目标集合；
-需要明确控制范围时请提供 `--agent <agent-id>`。
-
-The global command targets WorkBuddy explicitly. Replace `workbuddy` with the
-current Agent ID for another host. Interactive `solution-cli install` selects all
-detected Agents on Enter when any are detected, or one host by number;
-non-interactive `solution-cli 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.
-
-### 2.3 跨 Agent 平台技能挂载
-执行 `solution-cli install` 时，工具会自动检测本机存在的 Agent 宿主环境，并将 `solution-cli` Skill 和全套参考手册安全复制到对应目录：
-
-| Agent 宿主平台 | 技能默认配置路径 | 支持能力 |
-|---|---|---|
-| **Claude Code** | `~/.claude/skills/solution-cli` | 完整方案咨询、工况诊断、BOM 生成、现场部署 |
-| **Codex (OpenAI)** | `~/.agents/skills/solution-cli` 或 `~/.codex/skills/solution-cli` | 代码审查、参数重构、二次开发自动化 |
-| **Google Antigravity (AGY)** | `~/.gemini/config/skills/solution-cli` | 端到端自主诊断、多 Agent 协同实施 |
-| **Work Buddy / Workbody** | `~/.workbuddy/skills/solution-cli` | 桌面端交互、方案展示、一键部署联动 |
-| **CodeBuddy** | `~/.codebuddy/skills/solution-cli` | 代码库配对开发与自研模型构建 |
+不想修改全局 npm 环境时，使用 `npx --package` 临时调用：
 
-**非交互式多选安装示例**：
 ```bash
-# 同时为 Claude Code 和 Google Antigravity 部署技能，不弹窗确认
-solution-cli install --agent claude,antigravity -y
+npx -y --registry=https://registry.npmjs.org/ --package=@seeed-studio/solution-cli@latest solution-cli hub search "农业" --json
 ```
 
----
+Hermes 的已配置 profile 可通过 `--agent hermes:<profile>` 选择（安装、更新、卸载通用）：具名 profile 使用 `<root>/profiles/<profile>/skills/solution-cli`，`hermes:default` 使用 `<root>/skills/solution-cli`；`<root>` 是 Hermes 安装根目录。Profile ID 为 1–64 位小写字母、数字、`_` 或 `-`，以字母或数字开头。安装器仅复制 Skill，不创建或切换 profile。
 
 ## 3. 核心功能、使用方法与具体产出
 
-### 场景一：方案探索与工况诊断 (Hub Search)
+安装后可直接在命令行运行 `solution-cli` 与 `sensecraft-engine`；若未执行安装，也可随时通过 `npx -y @seeed-studio/solution-cli <command>` 免安装即用。
 
-当工程师或客户提出模糊需求（如“想在农田做微气象监测”、“工厂产线想做划痕检测”）时使用。
+### 场景一：方案探索与工况诊断 (Hub Search)
 
 #### 1. 执行命令
-```bash
-# 人类工程师阅读模式 (格式化终端高亮)
-solution-cli hub search "农业"
 
-# AI Agent 消费模式 (标准 JSON 格式的 Catalog DTO)
-solution-cli hub search "跌倒检测" --json
+```bash
+solution-cli hub search "锅炉恒温器" --json
 ```
 
+*(免安装时可用：`npx -y @seeed-studio/solution-cli hub search "锅炉恒温器" --json`)*
+
 #### 2. 产出物内容 (What it Outputs)
-运行该命令可产出 4 项关键资产：
-1. **方案业务说明与技术架构**：解释为何适合在端侧运行、本地处理延迟、数据不出本地的隐私保障；
-2. **静默商业闭环出口**：自动为该方案生成带有安全追踪标记（`utm_source=sensecraft_agent`）的官方落地页与开发 Wiki；
-3. **官方开源仓库地址**：提供官方维护的 GitHub 源码仓库，为二次开发预留出口；
-4. **现场工况诊断提问指引 (Diagnostic Playbook)**：直接给出当前场景下**必须向客户确认的 2~3 个核心工况问题**及其背后的技术决断理由。
+
+Agent 根据结果解释匹配的方案、设备和限制，并追问客户现场信息。方案未确认前只查询，不运行部署。
 
 #### 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）？
-         (决断考量: 决定是配置多合一微气象站，还是选配工业级土壤三参数探头与变送器)
+
+输出应包含匹配方案、适用场景、设备要求和仍需确认的工况问题；具体内容以查询结果为准。
+
+#### 4. 页面关系、内容读取与生产链接
+
+方案目录按显式关系组织，不把页面名称混用：Scenario 是业务落地页，Tech 是独立技术归属页，Reference Design（RD）是具体方案设计。Scenario 会关联 Tech 和 RD；RD 可继续关联架构图、产品说明和部署文档。只有 RD 存在有效部署映射和 preset 时，才可进入一键部署流程。
+
+```bash
+# 全量目录：按页读取，直到 has_more=false
+solution-cli hub list --type reference_design --locale zh --page 1 --limit 50 --json
+# 选定记录：按需要读取关系、链接、架构、产品或部署内容
+solution-cli hub get <id> --locale zh --section overview --json
+solution-cli hub get <id> --locale zh --section links --json
+solution-cli hub get <id> --locale zh --section architecture --json
+solution-cli hub get <id> --locale zh --section products --json
+solution-cli hub get <id> --locale zh --section deployment --json
 ```
 
----
+三种生产语言使用不同域名：英文 `www.seeed.cc`、中文 `www.seeedstudio.com.cn`、日文 `www.seeed.co.jp`。实际链接必须使用 `hub get --section links` 返回的地址；不要从 slug 拼接 Wiki、图片 CDN 或其他语言 URL。Wiki 是单独的已发布文档链接，Tech 页面也不能被当成 Wiki。翻译正文缺失时，保留可用的生产页并说明返回的内容语言。
 
-### 场景二：硬件产品规格与配件防呆评估 (Product & BOM)
+返回链接或 metadata 不等于已经阅读页面内容。回答方案能力、架构或产品问题时，必须读取对应的 `description`、`architecture`、`products` section；确切落地页或架构图片影响答案时，打开 CLI 返回的确切地址并说明实际核验范围。相对图片路径只有在签名本地内容存在时才可读取，否则标为 source asset 未就绪。
 
-当确定了方案，需要进入商务采购阶段、给客户出具设备清单时使用。
+RD 的部署映射只是目录信息，执行前还要读取本机 Engine 的实际配置：
 
-#### 1. 执行命令
 ```bash
-# 1. 查询产品族详情与物理规格
-solution-cli product query recomputer_j40 --json
+sensecraft-engine deploy-info <solution-id> --lang zh
+```
+
+架构部分只引用来源明确标记为 architecture 的图；其余图片按 gallery 呈现。产品说明、BOM、架构来源和部署文档都要保留来源与内容语言。
+
+### 场景二：硬件配置与配件选型（“买这个设备需要配什么配件？会不会买错？”）
+
+#### 1. 适用场景（客户常问什么）
+
+- “这款硬件（如 reComputer J40、SenseCAP Watcher）是什么配置？有几个网口、多大算力？”
+- “我买了这台主机，还需要额外配什么配件？电源、天线、外壳带不带？”
+- “我想加装 4G 模块或 SSD 固态硬盘，哪些型号能兼容？会不会买错插不上？”
+
+#### 2. 执行命令
 
-# 2. 评估该产品族所需的官方配件与兼容性
-solution-cli product accessories recomputer_j40 --json
+```bash
+# 1. 查硬件配置参数（算力、电压、物理接口、外形尺寸）
+solution-cli product query <family-id> --json
+
+# 2. 查配件推荐与兼容性清单（区分必买配件、可选配件，防踩坑）
+solution-cli product accessories <family-id> --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..."
+#### 3. 它能为你产出什么（解决什么痛点）
+
+1. **查清硬件规格**：直接返回 CPU/GPU 算力、供电范围、物理接口（网口/串口/USB）、外形尺寸等真实参数，无需翻找繁琐的说明书。
+2. **分清“必须买”与“按需选配”**：
+   - **必需配件（必须购买）**：如匹配功率的电源适配器、国标/美标电源线，不买设备无法开机；
+   - **可选配件（扩展使用）**：如安装导轨、外置天线、防护外壳、摄像头模组、M.2 扩展卡等。
+3. **防止买错踩坑（兼容性校验）**：
+   - 自动对比接口规格（如 M.2 Key-M 还是 Key-E）、天线频段（4G/Wi-Fi/LoRa）、供电电压与功率；
+   - 明确标注 `VERIFIED`（官方实测兼容）、`REQUIRES_ADAPTER`（需搭配转接板）或 `INCOMPATIBLE`（不兼容，严禁搭配使用）。
+4. **一键生成采购清单**：
+   - 结果直接包含官方真实 SKU、数量建议与购买链接，方便直接采购下单。
+
+### 场景三：方案一键部署与本地/远程运行 (Solution Deployment)
+
+方案部署由签名 Rust Engine (`sensecraft-engine`) 驱动，支持**本地一键部署**与**远程边缘设备部署**。
+
+#### 1. 读取部署规范与预设
+
+```bash
+sensecraft-engine deploy-info <solution-id> --lang zh
+```
+
+根据返回的 `presets` 与 `device_connections` 准备参数文件 `./.sensecraft-work/body.json`。
+
+#### 2. 参数文件配置
+
+- **模式 A：本地快速部署（Local Docker，最简单、零密码配置）**
+  适用于在当前本地宿主机（Linux 工作站 / Jetson / 树莓派）上直接运行方案容器：
+  ```json
+  {
+    "solution_id": "<solution-id>",
+    "preset_id": "default",
+    "selected_devices": ["host_device"],
+    "device_connections": {
+      "host_device": {
+        "target": "local_host",
+        "target_type": "local"
       }
-    ],
-    "optional": [
-      {
-        "sku": "110991734",
-        "name": "M.2 2280 NVMe SSD 512GB",
-        "category": "OPTIONAL",
-        "compatibility": { "status": "VERIFIED" }
+    }
+  }
+  ```
+
+- **模式 B：远程边缘设备部署（Remote SSH 密钥认证）**
+  适用于部署到局域网内的远程边缘硬件。严禁使用明文密码，统一采用 SSH 私钥认证：
+  ```json
+  {
+    "solution_id": "<solution-id>",
+    "preset_id": "default",
+    "selected_devices": ["host_device"],
+    "device_connections": {
+      "host_device": {
+        "target": "remote_edge",
+        "target_type": "remote",
+        "host": "192.168.1.50",
+        "username": "seeed",
+        "key_file": "~/.ssh/id_ed25519"
       }
-    ]
+    }
   }
-}
-```
+  ```
 
----
+#### 3. 一行命令执行部署与状态追踪
 
-### 场景三：设备状态感知与参数热修改 (Device Management)
+```bash
+# 1. 验证参数并启动部署
+sensecraft-engine deploy --params ./.sensecraft-work/body.json --yes
+
+# 2. 查询部署进度与容器日志
+sensecraft-engine status <deployment-id> --json
+sensecraft-engine logs <deployment-id>
+```
 
-当方案已经在现场或测试架部署完毕，需要调整运行参数（如更换 MQTT Broker、调整告警置信度阈值）时使用。
+### 场景四：设备状态感知与参数热修改 (Device Management)
 
 #### 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)
+已部署设备的参数修改要先读取当前部署和可修改字段，确认目标和变更范围，再执行对应管理接口。能否热修改取决于方案返回的 `reconfigurable` 字段；不要假设所有参数都支持无重启修改。
 
-当官方自带的模型无法满足客户特殊工况（如需要自研模型、特殊缺陷检测、修改前端大屏 UI）时使用。
+### 场景五：自研模型替换与本地二次开发 (Secondary Dev)
 
 #### 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 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
-```
+从查询结果中的官方仓库获取源码，在本地修改后按方案文档使用 `--solutions-dir` 进行测试。部署前展示修改和影响范围；不要把本地开发目录直接当作已验证的生产方案。
 
-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% 正常可用。
+## 4. 双轨运行机制：在线直连与离线托底
 
----
+目录和产品查询优先使用在线资源；无法联网时使用已安装包中的本地内容和知识库。离线能力不代表所有在线方案或实时设备状态都可用。部署仍需目标设备可达、凭据有效、目标环境满足 `deploy-info` 和 `validate` 的要求。
 
 ## 5. 常见问题与环境自检 (Doctor)
 
 ### 1. 运行自检工具
-在部署前或遇到环境异常时，执行：
+
 ```bash
-solution-cli doctor
+solution-cli doctor --json
 ```
-工具将逐项检测并给出修复指引：
-- `OS Platform`: 确认宿主机操作系统及架构是否支持；
-- `Docker Daemon`: 确认 Docker 服务是否正常运行；
-- `Serial / Dialout Permissions`: 确认串口访问权限；
-- `SenseCraft Engine`: 确认底座引擎完整性与版本；
-- `Ledger Integrity`: 校验技能安装账本状态。
+
+重点查看操作系统、架构、Engine、PATH、串口权限、Docker 和 Skill ledger 的结果。远程设备的 SSH、sudo、Docker 安装和启动状态需按 `deploy-info`、`validate` 和设备返回信息单独确认；CLI 不会静默取得权限。
 
 ### 2. 状态查询
+
 ```bash
 solution-cli status
 ```
-实时查看当前 Engine 所在路径、安装版本、本地 Content 方案缓存数量以及各大 Agent 的配置状态。
 
-### 3. 干净卸载
-如需从某个 Agent 中移除 SenseCraft 技能：
+查看 Engine 路径、版本、内容缓存和 Skill 挂载状态。
+
+### 3. 网络与源排查
+
+若遇到 npm 下载或同步延迟，可在命令中显式指定官方源：
+```bash
+npx -y --registry=https://registry.npmjs.org/ @seeed-studio/solution-cli install -y
+```
+
+### 4. 干净卸载
+
+只卸载指定宿主，并先备份需要保留的用户修改：
+
 ```bash
-solution-cli uninstall --agent claude,antigravity
+solution-cli uninstall --agent workbuddy
 ```
-工具将依据安装账本（`~/.sensecraft/skills-ledger.json`）仅删除工具自身写入的文件，绝不误删用户自定义创建的技能。
+
+卸载依据 ledger 只删除 CLI 自己写入且未被修改的文件，不删除 Engine 或方案内容。旧的非 `solution-cli` Skill 目录需要用户自行备份和清理；不要使用 `rm -rf` 或 `--force` 代替确认。