@seeed-studio/solution-cli 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seeed-studio/solution-cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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",

package/skills/sensecraft/SKILL.md

@@ -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,28 @@ 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)**:
    ```bash
-   npx @seeed-studio/solution-cli install -y
+   npx -y @seeed-studio/solution-cli@latest install -y
    ```
 
+   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 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
+   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 +176,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/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/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/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`，秒级完成本地部署生效。