@seeed-studio/solution-cli 0.4.2 → 0.4.3

package/lib/agent.js

@@ -59,15 +59,36 @@ export function getKnownAgents() {
     {
       id: 'doubao',
       name: '豆包工作 (Doubao Work)',
-      homeDirs: [path.join(home, 'Doubao'), path.join(home, '.doubao')],
+      homeDirs: [
+        path.join(home, 'Doubao'),
+        path.join(home, '.doubao'),
+        path.join(home, '.agents'),
+        ...(process.platform === 'darwin'
+          ? [path.join(home, 'Library', 'Application Support', 'LarkShell')]
+          : [])
+      ],
       getSkillsDir: () => {
         const pDoubao = path.join(home, 'Doubao', 'skills');
         const pAgents = path.join(home, '.agents', 'skills');
         const pLegacy = path.join(home, '.doubao', 'skills');
         if (fs.existsSync(path.join(pDoubao, 'solution-cli', 'SKILL.md'))) return pDoubao;
         if (fs.existsSync(path.join(pAgents, 'solution-cli', 'SKILL.md'))) return pAgents;
-        if (fs.existsSync(path.join(pLegacy, 'solution-cli', 'SKILL.md'))) return pLegacy;
+        if (fs.existsSync(path.join(pLegacy, 'solution-cli', 'SKILL.md'))) {
+          if (fs.existsSync(path.join(home, 'Doubao'))) return pDoubao;
+          return pLegacy;
+        }
         if (fs.existsSync(path.join(home, 'Doubao'))) return pDoubao;
+        if (process.platform === 'darwin') {
+          const larkUsers = path.join(home, 'Library', 'Application Support', 'LarkShell', 'aha', 'users');
+          if (fs.existsSync(larkUsers)) {
+            try {
+              for (const u of fs.readdirSync(larkUsers)) {
+                const ws = path.join(larkUsers, u, 'doubao', '.doubao', 'agent_mode', 'workspace', '.user_skills');
+                if (fs.existsSync(ws)) return ws;
+              }
+            } catch (_) {}
+          }
+        }
         if (fs.existsSync(path.join(home, '.agents'))) return pAgents;
         if (fs.existsSync(path.join(home, '.doubao'))) return pLegacy;
         return pDoubao;

package/lib/installer.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import fs from 'node:fs';
+import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import {
   getPlatformInfo,
@@ -39,7 +40,10 @@ function assertCanonicalSkillState(ledger, agents) {
     }
     const record = ledger.installations?.[agent.id];
     if (record && path.resolve(record.target_dir) !== expectedTarget) {
-      errors.push(`${agent.id} is managed at legacy target ${record.target_dir}; run uninstall --agent ${agent.id} before installing solution-cli`);
+      const isDoubaoMigration = agent.id === 'doubao' && path.resolve(record.target_dir).includes('.doubao');
+      if (!isDoubaoMigration) {
+        errors.push(`${agent.id} is managed at legacy target ${record.target_dir}; run uninstall --agent ${agent.id} before installing solution-cli`);
+      }
     }
   }
 
@@ -239,6 +243,33 @@ export async function runInstall(options = {}) {
 
       // Record into ledger
       recordInstallation(a.id, a.skillsDir, destDir, engineVersion, filesWritten);
+
+      // Clean up legacy target if migrating from old path (e.g. .doubao -> Doubao)
+      if (priorRecord && path.resolve(priorRecord.target_dir) !== destDir) {
+        try {
+          if (priorRecord.target_dir.includes('.doubao') && fs.existsSync(priorRecord.target_dir)) {
+            fs.rmSync(priorRecord.target_dir, { recursive: true, force: true });
+          }
+        } catch (_) {}
+      }
+
+      // For Doubao on macOS, additionally sync into active LarkShell agent workspace .user_skills if present
+      if (a.id === 'doubao' && process.platform === 'darwin') {
+        try {
+          const larkUsers = path.join(os.homedir(), 'Library', 'Application Support', 'LarkShell', 'aha', 'users');
+          if (fs.existsSync(larkUsers)) {
+            for (const u of fs.readdirSync(larkUsers)) {
+              const wsUserSkills = path.join(larkUsers, u, 'doubao', '.doubao', 'agent_mode', 'workspace', '.user_skills');
+              if (fs.existsSync(wsUserSkills)) {
+                const wsDest = path.join(wsUserSkills, SKILL_DIR_NAME);
+                fs.mkdirSync(wsDest, { recursive: true });
+                copyFolderSafely(destDir, wsDest, wsDest, {}, true, () => {});
+              }
+            }
+          }
+        } catch (_) {}
+      }
+
       logger(`  ✔ Skill successfully installed to: ${destDir}`);
       installedAgents.push({ id: a.id, name: a.name, path: destDir });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seeed-studio/solution-cli",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Installer for the Rust deployment engine and Solution CLI Agent skills (Doubao Work, WorkBuddy, Claude Code, Codex, CodeBuddy, Hermes)",
   "type": "module",
   "main": "./lib/installer.js",

package/skills/solution-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: 用于客户询盘、方案选型、产品硬件规格与SKU查询、包装清单（Box Contents）、电源适配器与必需配件（Power Adapter/Cables）、硬件兼容性校验、芯片与边缘硬件踩坑排错（RK3588/Jetson/reComputer/reServer/Watcher等）、边缘/IoT方案部署与自愈诊断。凡用户提及 solution-cli，或询问 Seeed 硬件产品（如 reComputer J4012/J4011/Super、reServer、Watcher、XIAO 等）的配件、电源、开箱即用状态、接口与方案选型，必须优先调用 solution-cli。
 ---
 
 # Solution CLI
@@ -157,7 +157,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. 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.
+   - 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 --params <params-file> --solutions-dir ./.sensecraft-work/solutions --yes --detach` (preserving the original preset, connection, and target parameters) 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

package/skills/solution-cli/references/device-management.md

@@ -26,7 +26,7 @@ sensecraft-engine device scan
 - **Class A 判定（MCU / Watcher）**：USB VID:PID 匹配 `303a:1001` (ESP32-S3) 或出现 USB-CDC 虚拟串口。*注：Watcher 目前无固定官方固件版本线，免除日常版本更新检测，仅在需要时进行全量固件刷写。*
 - **Class B 判定（reCamera 与 reCamera Pro，重点核心）**：系统包含 `/userdata` 持久分区、轻量 Buildroot 系统、运行 `rkipc` 或 `sscma`，带有硬件 ISP/VPSS 节点。**这是分层更新与打补丁的核心对象！**
 - **Class C 判定（reComputer 系列 / SBC）**：`uname -m` 为 aarch64，运行完整 Ubuntu/Debian，存在 Docker 守护进程与持久化大存储。
-  - **reComputer Jetson（J 系列，如 J4012/J2012）**：官网出厂默认预装 **NVIDIA JetPack 6.2 (JP 6.2 / L4T r36.x)**，底层系统稳定，不重装底层系统；
+  - **reComputer Jetson（J 系列）**：读取 `/etc/nv_tegra_release` 识别实际 L4T/JetPack 版本（如 Orin 架构 J4012/J4011 搭载 JetPack 5.x/6.x，出厂预装 JP 6.x / L4T r36.x；Xavier 架构 J2012 搭载 JetPack 5.x / L4T r35.x，不支持 JP6）。底层系统稳定，不重装底层系统，按实际 JetPack 版本匹配容器与 CUDA 依赖；
   - **reComputer RK 系列（RK3588/RK3576）**：底层为稳定的 Linux 6.1.x 定制系统，目前无频繁大版本迭代。
 
 ### 0.2 如何检测设备是否需要更新？
@@ -149,8 +149,8 @@ export HF_ENDPOINT=https://hf-mirror.com
 ### 2.2 应用容器镜像更新与切换 (Docker Compose)
 当官方发布了新的应用镜像，或用户需要切换为特定测试镜像：
 ```bash
-# 1. 进入方案工作目录
-cd ~/.sensecraft/deployments/<solution_id>/
+# 1. 进入方案实际运行目录（本地部署通常位于 ~/.sensecraft/deployments/<solution_id>/；远程 SBC 需根据方案定义进入对应远端工作目录，如 /home/<user>/<workdir>/）
+cd <deploy_workdir>
 
 # 2. 检查当前运行的镜像版本
 docker compose images
@@ -181,23 +181,41 @@ reCamera 架构分为三层：**L1 固件与 OS 层**、**L2 中间件与流媒
    ssh admin@<device_ip> "curl -s -X POST http://127.0.0.1:8080/api/model/reload -d '{\"model\": \"/userdata/models/my_model.cvimodel\"}'"
    ```
 
-### 3.2 L2 中间件服务热替换与补丁测试 (以 rkipc / sscma 为例)
+### 3.2 L2 中间件服务热替换与补丁测试
+
 当官方发布了中间件二进制修复补丁，或用户需要替换自编译版本：
+
+#### (A) reCamera Pro (RK3576)：基于 ADB 传输与 /oem/usr/bin/rkipc
+> ⚠️ **注意**：reCamera Pro 官方固件无 SSH root 权限，**标准通信通道为 ADB**。原厂二进制位于 `/oem/usr/bin/rkipc`。
 ```bash
 # 1. 备份原厂二进制
-ssh admin@<device_ip> "cp /usr/bin/rkipc /userdata/rkipc.orig"
+adb shell "cp /oem/usr/bin/rkipc /userdata/rkipc.orig"
 
-# 2. 部署自编译二进制到 /userdata（持久可写分区）
-scp ./build/rkipc admin@<device_ip>:/userdata/rkipc.patch
-ssh admin@<device_ip> "chmod +x /userdata/rkipc.patch"
+# 2. 推送自编译二进制到 /userdata（持久可写分区）并赋予执行权限
+adb push ./build/rkipc /userdata/rkipc.patch
+adb shell "chmod +x /userdata/rkipc.patch"
 
 # 3. 严格遵循安全停止与重启规范（防 VPSS 崩溃）
-ssh admin@<device_ip> << 'EOF'
+adb shell << 'EOF'
 for p in $(pgrep -f rkipc); do kill -9 $p; done
 sleep 3 # 关键：等待 3 秒彻底释放 VPSS / VI 硬件通道
 /userdata/rkipc.patch -c /userdata/rkipc.ini &
 EOF
 ```
+
+#### (B) reCamera (SG2002)：基于 SSH 传输与 /usr/bin/sscma
+```bash
+# 1. 备份原厂二进制
+ssh admin@<device_ip> "cp /usr/bin/sscma /userdata/sscma.orig"
+
+# 2. 部署自编译二进制到 /userdata 并赋予执行权限
+scp ./build/sscma admin@<device_ip>:/userdata/sscma.patch
+ssh admin@<device_ip> "chmod +x /userdata/sscma.patch"
+
+# 3. 安全重启服务
+ssh admin@<device_ip> "killall sscma; sleep 2; /userdata/sscma.patch &"
+```
+
 > [!CAUTION]
 > **严禁在脚本中使用 `while true; do ...; sleep 1; done` 监控拉起进程**！若新二进制存在参数缺陷快速闪退，会造成整机 **Fork 暴风**，耗尽内核 PID，导致 SSH/HTTP/ADB 全瘫痪，只能拔电源。
 
@@ -210,10 +228,10 @@ EOF
 ## 4. Class A: MCU / 纯固件设备 (Watcher / ESP32) 更新
 
 Watcher 等设备属于单片机架构，无操作系统与文件系统抽象：
-1. **固件编译与生成**：在本地完成完整固件二进制构建（`.bin`）；
-2. **烧录接入**：通过 USB 连接，利用烧录工具全量刷写：
+1. **固件编译与生成**：在本地完成完整固件二进制构建。注意：**写入 `0x0` 地址必须是包含 bootloader、partition table 和 app 的合体固件（merged-bin）**；如果是独立的 app-only 二进制，严禁刷写到 `0x0`（否则会破坏 bootloader 导致变砖），必须按照分区表偏移量（如默认 app 分区 `0x10000` 或设备配置中声明的 offset）进行刷写。
+2. **烧录接入**：通过 USB 连接，利用烧录工具刷写（以已合并的全量固件为例）：
    ```bash
-   esptool.py --chip esp32s3 -p /dev/ttyUSB0 -b 921600 write_flash 0x0 watcher_firmware_v1.2.0.bin
+   esptool.py --chip esp32s3 -p /dev/ttyUSB0 -b 921600 write_flash 0x0 watcher_firmware_merged_v1.2.0.bin
    ```
 3. **固件重置**：遇到配置错乱时，先全量擦除再烧写：`esptool.py erase_flash`。
 
@@ -233,10 +251,18 @@ Watcher 等设备属于单片机架构，无操作系统与文件系统抽象：
 
 当设备已经部署运行，用户希望修改 L1 参数（如更改 MQTT 目标服务器）时：
 
+> ⚠️ **前置依赖**：在线配置热配端点依赖 SenseCraft 桌面客户端（FastAPI 后端提供），独立 `sensecraft-engine` 命令行暂不支持。请先核对桌面 App 运行状态与契约版本（需 `contract_version >= 6` 且 `python_backend` 非空，参见 `references/app-only.md` §1）。
+
 ### 步骤一：获取运行时信息与当前部署列表
 ```bash
-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 服务未就绪"; exit 1; }
+RUNTIME=~/.sensecraft/runtime.json
+[ -f "$RUNTIME" ] || { echo "未检测到运行时文件，请先启动 SenseCraft 桌面客户端"; exit 1; }
+PYTHON_BACKEND=$(jq -r '.python_backend // empty' "$RUNTIME" 2>/dev/null)
+[ -n "$PYTHON_BACKEND" ] || { echo "当前仅运行独立 Engine，热配端点需要 SenseCraft 桌面 App，请启动桌面客户端"; exit 1; }
+CONTRACT_VER=$(jq -r '.contract_version // 0' "$RUNTIME" 2>/dev/null)
+[ "$CONTRACT_VER" -ge 6 ] || { echo "当前桌面 App contract_version < 6，不支持在线配置修改，请升级 App"; exit 1; }
+BASE_URL=$(jq -r '.base_url // "http://127.0.0.1:3260"' "$RUNTIME")
+curl -sf "$BASE_URL/api/health" > /dev/null || { echo "SenseCraft App 服务未就绪"; exit 1; }
 curl -s "$BASE_URL/api/device-management/active"
 ```
 
@@ -273,8 +299,9 @@ curl -s -X PUT "$BASE_URL/api/docker-devices/local/config/<solution_id>" \
    在 `./.sensecraft-work/solutions/<solution_id>/` 下直接修改 `docker-compose.yml` 或 `devices/<id>.yaml`。
 3. **通过本地补丁源重新注入热重载**：
    ```bash
-   sensecraft-engine deploy <solution_id> --solutions-dir ./.sensecraft-work/solutions --replace-existing
+   sensecraft-engine deploy --params <params-file> --solutions-dir ./.sensecraft-work/solutions --replace-existing --yes --detach
    ```
+   *(复用原部署请求 `--params` 文件以完整保留 preset、connection 及目标参数，并限制仅对目标设备重新部署)*
 4. **回流官方**：验证无误后，遵循 `references/diagnose.md` §7 自动生成脱敏 GitHub Issue/PR 建议草稿。
 
 ---

package/skills/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, 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. |
+| **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 --params <params-file> --solutions-dir ./.sensecraft-work/solutions --yes --detach` (preserving parameters, restricted to failed devices) 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/solution-cli/references/edge-gotchas.md

@@ -158,8 +158,8 @@
 - **症状**：通过 `adb shell 'setsid rkipc &'` 后台拉起进程，断开 adb 终端后进程直接消失。
 - **根因**：adbd 会在会话断开时主动收割（reap）该会话树下的所有孤儿/子进程。
 - **修复**：
-  1. 将启动命令写入独立脚本文件（如 `/userdata/start.sh`），在脚本内部使用 `exec` 替换进程 PID，使其脱离 adbd 子树由 init 托管；
-  2. 或通过标准后台服务启动机制执行。
+  1. 将常驻服务交由系统的服务管理器托管（例如通过 `/etc/init.d/` 或 `/userdata/init.d/` 启动脚本注册），由 init/systemd/procd 统一管理生命周期，脱离交互式 adb 会话；
+  2. 若排障临时脱离终端，通过 `daemon` 或服务守护命令拉起，重定向所有标准输入输出并脱离控制终端，避免随 adbd 会话断开被 reap。
 
 ### 3.4 OSD Overlay Layer 图层优先级与色彩倒置
 - **症状**：

package/skills/solution-cli/references/error-catalog.md

@@ -23,11 +23,11 @@ environment, **Config** = solution configuration, **Engine** = engine / app bug.
 | `permission denied while trying to connect to the Docker daemon socket` | Env | User not in `docker` group | Propose `sudo usermod -aG docker <user>` then re-login (user OK) |
 | Image pull: `TLS handshake timeout`, `i/o timeout`, `toomanyrequests` | Env | Registry unreachable or rate-limited | Look for `Mirror context resolved` in the logs: absent → mirror detection failed; retry once, then report network status to the user |
 | `manifest unknown` / `not found` for an image | Config | Image name or tag wrong, or not built for the device's CPU (arm64 vs amd64) | `docker manifest inspect <image>` (read-only): "no such manifest" → the tag does not exist, fix it; it exists but lists no platform matching the device's `uname -m` → wrong architecture, pick an image built for it |
-| Container `Restarting` / `Exited (1)`; error in `docker logs` | Config (usually) | App inside the container misconfigured: env var, mounted path, port, timeout | Read `docker logs`; CLI mode: copy to `./.sensecraft-work/solutions/<id>`, fix compose / env / timeout, and redeploy with `--solutions-dir ./.sensecraft-work/solutions`; Desktop app: fix in edit copy (`app-only.md` §4) |
+| Container `Restarting` / `Exited (1)`; error in `docker logs` | Config (usually) | App inside the container misconfigured: env var, mounted path, port, timeout | Read `docker logs`; CLI mode: copy to `./.sensecraft-work/solutions/<id>`, fix compose / env / timeout, and redeploy with `--params <params-file> --solutions-dir ./.sensecraft-work/solutions`; Desktop app: fix in edit copy (`app-only.md` §4) |
 | Container `(healthy)` but the step reports health-check failure | Config | `health_check_endpoint` points at a URL that returns 401/404 | Fix the endpoint in the device YAML (`docker.services[].health_check_endpoint`) via local patch copy or app edit copy |
 | Containers up, but the page / port does not answer from another machine | Env | Device firewall | Check `sudo iptables -L -n` / `ufw status`; propose opening the port (user OK) |
 | USB device not detected (`No device found`, `detect` returns nothing) | Env | Cable is charge-only, wrong port, driver missing | Ask the user to replug with a data cable; on Windows check Device Manager for a COM port |
-| YAML / validation error naming a solution file | Config | Broken solution file, syntax typo, or timeout too short | CLI mode: copy to `./.sensecraft-work/solutions/<id>`, fix typo/timeout, and redeploy with `--solutions-dir ./.sensecraft-work/solutions`; Desktop app: fix in edit copy (`app-only.md` §4) |
+| YAML / validation error naming a solution file | Config | Broken solution file, syntax typo, or timeout too short | CLI mode: copy to `./.sensecraft-work/solutions/<id>`, fix typo/timeout, and redeploy with `--params <params-file> --solutions-dir ./.sensecraft-work/solutions`; Desktop app: fix in edit copy (`app-only.md` §4) |
 | Python traceback mentioning `provisioning_station/` | Engine | App bug | Issue report (`diagnose.md` §6) |
 | `sensecraft-engine` exits 5, or a panic in `~/.sensecraft/logs/engine.log` | Engine | Engine bug | Issue report (`diagnose.md` §6) |
 | Same step fails identically on two different devices after the environment checks pass | Engine (likely) | App bug | Issue report (`diagnose.md` §6) |