@seeed-studio/solution-cli 0.3.1 → 0.4.0

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

@@ -0,0 +1,298 @@
+# 设备生命周期、分层更新与参数管理手册 (Device Lifecycle & Patch Management Guide)
+
+> **定位**：供 AI Agent 在用户处于 **设备管理（MANAGE）**、**系统更新与打补丁（UPDATE_PATCH）**、**切换系统语言/镜像** 或 **参数热配（RECONFIG）** 阶段查阅。
+> 当用户询问“怎么升级”、“打个补丁”、“切换语言”、“换应用镜像”、“改一下 MQTT 地址”、“插了新硬件怎么配”时加载本手册。
+
+---
+
+## 0. 核心架构：出发点与触发时机分化 (Trigger Paradigm & Architecture)
+
+设备更新与应用修改的**出发点与触发时机截然不同**，Agent 必须严格遵守以下时序分化原则：
+
+| 维度 | 设备级底层更新 (Device-Level / Firmware / BSP) | 应用层业务修改 (Application / Models / Reconfig) |
+|---|---|---|
+| **核心出发点** | **筑牢底层地基**：规避硬件死锁、驱动崩溃（如 VPSS FIFO overflow）与内核协议缺陷（如 Docker nftables 冲突） | **敏捷业务迭代**：满足模型换代、参数微调、业务流变更，保障系统连续运行零停机 |
+| **触发时机** | **尽早主动提醒 (Early & Proactive Trigger)**<br>👉 设备刚连接、环境初次自检、准备部署前 (`ONBOARDING / PRECHECK`) | **按需被动响应 (On-Demand / Just-In-Time)**<br>👉 设备正常运行中，仅在用户提出具体业务改动时 (`MANAGE / RECONFIG`) |
+| **交互行为** | **前置体检与拦截**：一旦发现底层固件版本过旧或存在已知驱动缺陷，主动打断并建议优先升级，避免部署中崩溃 | **零打扰按需加载**：平时静默，用户说“改一下 MQTT”、“换个检测模型”时才定向查阅对应章节，局部热更并秒级生效 |
+
+---
+
+### 0.1 设备检测与硬件指纹提取
+当用户接入设备、发起环境自检或询问“当前设备状态”时，Agent 首先通过以下命令采集设备特征指纹：
+```bash
+solution-cli doctor --json
+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 RK 系列（RK3588/RK3576）**：底层为稳定的 Linux 6.1.x 定制系统，目前无频繁大版本迭代。
+
+### 0.2 如何检测设备是否需要更新？
+Agent 执行**针对性校验模型**判定更新需求：
+
+```mermaid
+flowchart TD
+    Scan[设备探测与指纹采集] --> DevType{设备类别判断}
+    DevType -- "Class B: reCamera / Pro (核心更新对象)" --> C_reCamera{"三层版本与补丁检测"}
+    C_reCamera -- 固件/中间件有新版本 --> Notify1[提醒: 官方固件 / rkipc 升级]
+    C_reCamera -- 命中驱动Bug但官方未发版 --> Notify2[提醒: 应用 /userdata 本地热补丁]
+    C_reCamera -- 业务流/模型更新 --> Notify3[提醒: 替换模型 / 重载 Flow]
+
+    DevType -- "Class C: reComputer J / RK (出厂系统稳定)" --> C_reComputer{"应用与环境漂移检测"}
+    C_reComputer -- 容器镜像有新Tag --> Notify4[提醒: 更新 Docker 镜像并平滑重启]
+    C_reComputer -- 发现新插外设未绑定 --> Notify5[提醒: 映射新传感器端口]
+    C_reComputer -- 中文环境/国内源未配 --> Notify6[提醒: 切换 zh_CN.UTF-8 / 配置清华源]
+
+    DevType -- "Class A: Watcher" --> C_Watcher["免除日常更新检测 (无固定版本)"]
+```
+
+1. **针对 reCamera 与 reCamera Pro（更新与打补丁的核心对象）**：
+   - **L1 固件层**：读取 `/etc/version` 与官方固件包版本对比；
+   - **L2 中间件与服务层**：检查 `rkipc` / `sscma` 版本，以及是否受到已知驱动 Bug（如 VPSS FIFO overflow）影响；
+   - **L3 应用与模型层**：对比 `/userdata/models/` 或 Node-RED Flows 是否有最新优化版本；
+   - **本地热补丁需求**：若官方尚未发版但本地存在验证通过的修复（如 rkipc 优化版），主动提醒是否通过 `/userdata` 注入热补丁。
+2. **针对 reComputer 系列（Jetson 出厂默认 JP 6.2，RK 底层稳定）**：
+   - 底层系统不重装、不频繁刷机；
+   - 检测运行中 Docker 镜像 tag/hash vs 方案 Catalog 最新镜像，若有新版本则提醒更新应用镜像；
+   - 扫描当前外设列表，检查是否有新插入的传感器未绑定（如毫米波雷达串口）；
+   - 检查系统环境（是否未配置中文 locale，国内网络下是否未配置镜像加速）。
+3. **针对 Watcher**：
+   - 暂无固定版本线，免除自动版本对比提醒。仅在用户明确要求刷写固件或恢复出厂时提供烧录支持。
+
+### 0.3 主动提醒用户话术模板
+当检测到需要更新时，Agent **必须结构化输出提醒并征得用户授权**：
+> *“💡 设备状态与更新检测提醒：*
+> *- **识别设备**：Seeed Studio reComputer J4012 (Orin NX)*
+> *- **当前状态**：运行方案 `fall_detection` (v1.0.1)；检测到新插入硬件 `/dev/ttyUSB1` (毫米波雷达)*
+> *- **建议更新**：*
+> *  1. 官方已发布 `v1.1.0` 镜像，优化了暗光下人体姿态估计帧率并修复了内存泄漏；*
+> *  2. 建议将新增的毫米波雷达串口映射到容器中，以提升私密防跌倒感知精度；*
+> *  3. 建议将系统默认语言配置为 `zh_CN.UTF-8`。*
+> *预计耗时约 2 分钟，更新期间不会丢失历史录像数据。是否同意立即执行更新？[立即更新 / 稍后处理]”*
+
+### 0.4 Agent 在修改对应设备时如何查阅本 Skill？
+当用户确认更新后，Agent 按照**渐进式路由规约**查阅并执行操作：
+
+```mermaid
+sequenceDiagram
+    participant User as 用户
+    participant Agent as AI Agent
+    participant Skill as SKILL.md (顶层路由)
+    participant DevMgmt as references/device-management.md
+    participant Gotchas as references/edge-gotchas.md
+    participant Device as 目标设备 (Seeed 硬件)
+
+    User->>Agent: 确认执行更新 / 部署
+    Agent->>Skill: 查阅工作流路由表 (确定为 MANAGE / UPDATE_PATCH)
+    Skill-->>Agent: 指向 references/device-management.md
+    Agent->>DevMgmt: 查阅对应设备类别的操作规程
+    Note over Agent,DevMgmt: Class A -> §4 固件烧录<br/>Class B -> §3 分层热更与防死锁<br/>Class C -> §2 容器镜像拉取与环境变量
+    Agent->>Gotchas: 检索目标芯片的底层安全红线 (查阅 edge-gotchas.md)
+    Gotchas-->>Agent: 返回: 严禁 while true、kill 须 pgrep -f 且 sleep 3、切 iptables-legacy
+    Agent->>Device: 执行安全更新操作 (Zero-Plaintext-Password)
+    Device-->>Agent: 返回更新与重启状态
+    Agent->>User: 汇报更新结果与自检健康报告
+```
+
+1. **第 1 步：查阅 `SKILL.md` 顶层路由表**：
+   - 匹配 Intent：`MANAGE / RECONFIG` ➔ 明确加载 `references/device-management.md`；
+2. **第 2 步：按设备类别查阅具体操作章节**：
+   - 若目标设备是 **Class A (SenseCAP Watcher)** ➔ 查阅 `§4` 固件刷写指令；
+   - 若目标设备是 **Class B (reCamera 系列)** ➔ 查阅 `§3` 分层更新方案（区分 L1 固件、L2 中间件、L3 模型/Flow）；
+   - 若目标设备是 **Class C (reComputer 系列)** ➔ 查阅 `§2` 容器 Compose 更新与 locale 切换；
+3. **第 3 步：横向查阅排障红线 (`references/edge-gotchas.md`)**：
+   - 在执行重启或启动前，Agent 必须对照 `edge-gotchas.md` 中对应芯片的避坑卡（例如：操作 reCamera 时核对 Card 2/3，禁止死循环保活；操作 RK3576 时核对 Card 1，检查 iptables-legacy 是否配置）；
+4. **第 4 步：执行并在失败时调用自愈**：
+   - 若遇到部署与更新异常，查阅 `references/diagnose.md` 执行最多 3 轮最小改动本地修复；成功后生成脱敏 GitHub 建议回流。
+
+---
+
+## 1. 三类设备的生命周期与更新模型
+
+边缘硬件形态各异，更新与打补丁的机制必须严格按设备类别区分，切忌混淆：
+
+| 设备类别 | Seeed Studio 官方产品 & 代表硬件 | 系统架构特征 | 官方升级机制 | 本地小补丁 / 快速热替换 (Local Hotpatch) | 回滚与安全守护 |
+|---|---|---|---|---|---|
+| **Class A: MCU / 纯固件设备** | **Seeed Studio SenseCAP Watcher**、ESP32 系列、Himax WE2 | 裸机 / FreeRTOS，无独立用户态文件系统 | **全量固件刷写**<br>(USB-CDC / OTA Flash Binary) | **不支持分层热更**：必须在源码重编后重新烧录完整镜像 | 串口烧录校验 (CRC/MD5)；OTA A/B 分区回退 |
+| **Class B: 轻量嵌入式 Linux 多层设备** | **Seeed Studio reCamera** (SG2002)、**reCamera Pro** (RV1126B) | Buildroot/OpenWrt，只读 RootFS + 持久化分区 (`/userdata` 或 `/app`) | **分层 OTA 固件更新**<br>(Kernel + RootFS + 原厂 BSP) | **分层热更与局部覆盖**：<br>1. 底层驱动小补丁：`/userdata` 启动脚本 bind mount 覆盖；<br>2. 管道与服务热更：在 `/userdata` 替换自编译 rkipc/sscma；<br>3. 上层应用/模型更新：直接替换 `.cvimodel`/`.axmodel` 或 Node-RED Flow | **严禁死循环拉起进程**（防 Fork 风暴瘫痪用户态）；<br>杀进程一律用 `pgrep -f` 并在新起前 `sleep 3` 释放 VPSS 通道；<br>保留出厂 `.orig` 备份 |
+| **Class C: 通用单板计算机 (SBC)** | **Seeed Studio reComputer J 系列** (J4012/J2012/Jetson)、**reComputer RK 系列** (RK3588/RK3576)、**reComputer R 系列** (Raspberry Pi CM4) | 通用发行版 (Ubuntu/Debian)，大存储，OCI/Docker 容器化生态 | **底层 OS 基本保持不变**，仅必要时执行 `apt update` | **声明式环境配置与容器生命周期**：<br>1. 环境适配：一键配置语言 locale、时区、清华/国内镜像源；<br>2. 应用镜像升级：通过 Docker Compose 切换镜像 Tag；<br>3. 业务配置更新：通过挂载卷 (Bind Mount) 传入 `.env` 或配置文件 | 容器 Healthcheck 探针；镜像 Tag 快速回滚；`iptables-legacy` 与 udev 规则保底 |
+
+---
+
+## 2. Class C: 通用 SBC 的环境配置与容器更新操作流
+
+SBC 设备（RK3588 / RK3576 / Jetson / RPi）在出厂后系统基础镜像基本保持稳定，日常运维聚焦在**系统环境切换**与**应用容器升级**。
+
+### 2.1 系统环境与默认语言 (Locale) 切换
+当用户需要将系统语言切换为中文或英文，或校准时区与源时：
+```bash
+# 1. 切换/生成中文环境 (zh_CN.UTF-8)
+sudo apt-get install -y locales
+sudo locale-gen zh_CN.UTF-8 en_US.UTF-8
+sudo update-locale LANG=zh_CN.UTF-8 LC_ALL=zh_CN.UTF-8
+# 导出当前环境变量
+export LANG=zh_CN.UTF-8
+export LC_ALL=zh_CN.UTF-8
+
+# 2. 时区校准
+sudo timedatectl set-timezone Asia/Shanghai
+
+# 3. 基础镜像源快速换国内镜像 (如需)
+# pip
+export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
+# HuggingFace
+export HF_ENDPOINT=https://hf-mirror.com
+```
+
+### 2.2 应用容器镜像更新与切换 (Docker Compose)
+当官方发布了新的应用镜像，或用户需要切换为特定测试镜像：
+```bash
+# 1. 进入方案工作目录
+cd ~/.sensecraft/deployments/<solution_id>/
+
+# 2. 检查当前运行的镜像版本
+docker compose images
+
+# 3. 拉取新镜像并平滑更新（零停机重构）
+docker compose pull
+docker compose up -d --remove-orphans
+
+# 4. 验证容器健康状态
+docker compose ps
+docker compose logs --tail=50
+```
+
+---
+
+## 3. Class B: reCamera 系列多层嵌入式设备的补丁与应用更新
+
+reCamera 架构分为三层：**L1 固件与 OS 层**、**L2 中间件与流媒体层 (rkipc / sscma)**、**L3 应用与模型层**。
+
+### 3.1 L3 上层应用与 AI 模型热更新 (秒级生效)
+针对 Node-RED 业务流或目标检测模型文件的更新，不需要重启设备，也不动底层固件：
+1. **传输新模型到持久化数据区**：
+   ```bash
+   scp my_model.cvimodel admin@<device_ip>:/userdata/models/
+   ```
+2. **通知流媒体服务重载或重启轻量业务进程**：
+   ```bash
+   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 为例)
+当官方发布了中间件二进制修复补丁，或用户需要替换自编译版本：
+```bash
+# 1. 备份原厂二进制
+ssh admin@<device_ip> "cp /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"
+
+# 3. 严格遵循安全停止与重启规范（防 VPSS 崩溃）
+ssh admin@<device_ip> << '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
+```
+> [!CAUTION]
+> **严禁在脚本中使用 `while true; do ...; sleep 1; done` 监控拉起进程**！若新二进制存在参数缺陷快速闪退，会造成整机 **Fork 暴风**，耗尽内核 PID，导致 SSH/HTTP/ADB 全瘫痪，只能拔电源。
+
+### 3.3 L1 底层固件更新
+- 固件升级涉及内核、U-Boot 与根分区，必须通过官方 OTA 包或 `sysupgrade` 工具整体升级；
+- 若官方尚未发版，但需修补特定 kernel module（如驱动补丁），在 `/userdata/init.d/` 编写挂载脚本，系统启动时通过 `mount --bind` 将补丁 `.ko` 覆盖到 `/lib/modules/`。
+
+---
+
+## 4. Class A: MCU / 纯固件设备 (Watcher / ESP32) 更新
+
+Watcher 等设备属于单片机架构，无操作系统与文件系统抽象：
+1. **固件编译与生成**：在本地完成完整固件二进制构建（`.bin`）；
+2. **烧录接入**：通过 USB 连接，利用烧录工具全量刷写：
+   ```bash
+   esptool.py --chip esp32s3 -p /dev/ttyUSB0 -b 921600 write_flash 0x0 watcher_firmware_v1.2.0.bin
+   ```
+3. **固件重置**：遇到配置错乱时，先全量擦除再烧写：`esptool.py erase_flash`。
+
+---
+
+## 5. 运行时参数可修改性的分层边界
+
+| 层级 | 参数类别 | 判断依据 | 处理方式 |
+|---|---|---|---|
+| **L1: 声明式热配参数** | 业务高频参数（MQTT Broker 地址、API Key、告警 Webhook、Wi-Fi 凭证） | 方案中声明了 `user_inputs` 且标记为 `reconfigurable: true` | **在线热修改**：直接调用设备管理 API 更新，后台自动重载并重启容器，零停机重装。 |
+| **L2: 方案编排层参数** | 内部端口映射、Docker 数据卷挂载路径、未暴露的环境变量 | 仅存在于 `docker-compose.yml` 或 `devices/<id>.yaml` 中 | **方案级本地补丁**：走本地 auto-patch 流程，用 `--solutions-dir` 重新加载。 |
+| **L3: 业务源码与算法层** | 模型置信度硬编码、状态机转移逻辑、前端 UI 界面组件 | 代码直接写死在 Python/C++/Vue 源码中 | **源码二次开发**：走 GitHub 克隆与本地构建联调流（查阅 `references/secondary-development.md`）。 |
+
+---
+
+## 6. L1 声明式热配标准操作流
+
+当设备已经部署运行，用户希望修改 L1 参数（如更改 MQTT 目标服务器）时：
+
+### 步骤一：获取运行时信息与当前部署列表
+```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; }
+curl -s "$BASE_URL/api/device-management/active"
+```
+
+### 步骤二：读取可配参数及当前值（Get Config）
+```bash
+# 本地 Docker 部署实例
+curl -s "$BASE_URL/api/docker-devices/local/config/<solution_id>"
+```
+
+### 步骤三：验证并提交新参数（Update Config）
+```bash
+curl -s -X PUT "$BASE_URL/api/docker-devices/local/config/<solution_id>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "values": {
+      "mqtt_broker": "192.168.1.200",
+      "mqtt_port": 1883
+    }
+  }'
+```
+
+---
+
+## 7. 官方未发版时的“方案级本地热补丁 (Local Hotfix)”运维
+
+当官方方案库尚未发布新镜像/配置，但现场亟需修补方案编排：
+
+1. **提取官方运行态副本**：
+   ```bash
+   mkdir -p ./.sensecraft-work/solutions/<solution_id>
+   cp -r ~/.sensecraft/content/solutions/<solution_id>/* ./.sensecraft-work/solutions/<solution_id>/
+   ```
+2. **应用最小补丁**：
+   在 `./.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
+   ```
+4. **回流官方**：验证无误后，遵循 `references/diagnose.md` §7 自动生成脱敏 GitHub Issue/PR 建议草稿。
+
+---
+
+## 8. 新硬件热插拔与变动自动提醒 (Hardware Drift Detection)
+
+在设备运行期，用户常会给主机额外插上新配件（例如新接入了 USB 摄像头、毫米波雷达串口、4G 网卡模块、PCIe NPU 卡）：
+
+1. **变动识别时机**：
+   每当用户发起“设备自检”、“查看状态”或提到“我刚插上了新设备”时，Agent 执行探测：
+   ```bash
+   solution-cli doctor --json
+   sensecraft-engine device ports
+   ```
+2. **与当前方案配置对齐对比**：
+   - 检查已发现的硬件（例如新增的串口 `/dev/ttyUSB1` 或新增的视频节点 `/dev/video1`）；
+   - 对比当前运行方案（从 `/api/docker-devices/local/config/<id>` 或部署 Lockfile 中记录的绑定端口）。
+3. **主动提醒用户跟进绑定**：
+   若发现硬件列表多出了未经绑定的设备，Agent **必须主动发起提醒并给出跟进方案**：
+   > *“💡 硬件变动提醒：检测到主机新插入了设备 `/dev/ttyUSB1`（USB 串口外设）。当前运行中的方案未绑定该端口。*
+   > *如果您希望接入该硬件，请告诉我，我可以帮您在配置文件中追加串口映射并重新加载服务生效！”*

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

@@ -131,3 +131,18 @@ a link to open in the browser and submit with their own GitHub account.
    separately to paste into the form.
 3. Show the user the filled fields and the link, and say the report will be
    public.
+
+---
+
+## 7. 本地自动打补丁 (Auto-patching) 成功后的脱敏建议回流
+
+当通过 `./.sensecraft-work/solutions/<id>` 本地修复（如解决健康检查超时、 Compose 端口冲突或环境变量微调）并最终验证成功后，Agent **必须主动询问用户是否将脱敏修复 Diff 反馈给 Seeed 官方工程团队**，以实现官方方案库的持续演进：
+
+1. **主动交互询问**：
+   > *“💡 提示：本次部署通过本地热补丁修复了官方方案配置中的轻微缺陷，当前系统已稳定运行。是否同意将已脱敏的修复 Diff 生成建议提交给 Seeed 官方团队？[生成提交链接 / 忽略]”*
+2. **生成预填充建议链接**：
+   若用户同意，生成带脱敏 Diff 的官方 GitHub 方案优化建议链接（已去除所有局域网 IP、密码、密钥和私有路径）：
+   ```
+   https://github.com/suharvest/sensecraft-solutions/issues/new?template=solution-enhancement.yml&title=%5BPatch%5D+<solution_id>+configuration+fix&solution=<solution_id>&diff=<encoded_sanitized_diff>
+   ```
+   用户一键即可直达提交，完成从“端侧自愈”到“云端反哺”的商业与技术生态闭环。

package/skills/solution-cli/references/edge-gotchas.md

@@ -0,0 +1,205 @@
+# Seeed Studio 边缘计算硬件排障与通用排坑卡库 (Seeed Edge Gotchas & Troubleshooting Cards)
+
+> **定位**：供 AI Agent 在用户处于 **硬件/算法排障（GOTCHAS_DEBUG）**、**跨平台移植** 或 **边缘编译报错** 时查阅。
+> **官方产品归属声明**：
+> - **Seeed Studio reComputer 系列**：包含基于 NVIDIA Jetson 平台的 **reComputer J 系列**（J4012, J4011, J2012, J1010 等）、基于 Rockchip 芯片的 **reComputer RK 系列**（RK3588, RK3576）以及基于树莓派的 **reComputer R 系列**，均为 Seeed Studio 官方标准硬件产品与官方 SKU。
+> - **Seeed Studio reCamera 系列**：包含 **reCamera**（SG2002 RISC-V/ARM 双核）与 **reCamera Pro**（RV1126B 视觉 SoC），为 Seeed Studio 自研的模块化智能视觉相机产品线。
+> - **Seeed Studio SenseCAP 系列**：包含 **SenseCAP Watcher**、工业级环境感知节点及 LoRaWAN 网关，为 Seeed Studio 工业级 IoT 与实体 AI 产品线。
+>
+> **排卡原则**：
+> 1. **官方产品权威背书**：优先对齐 Seeed Studio 官方发布固件、BSP、载板接口与官方配件库（如 J 系列拓展板、CSI 摄像头转接板等）。
+> 2. **剥离外部第三方硬件噪音**：完全剔除非 Seeed 公司的外部第三方硬件品牌（如前期评测涉及的外部竞品板卡名称），将经验沉淀为 Seeed 产品体系与底层芯片级的通用排障指南。
+
+---
+
+## 目录索引
+- [Card 1: Seeed Studio reComputer RK 系列 / 通用 Rockchip SBC (RK3576 / RK3588) 排障卡](#card-1-seeed-studio-recomputer-rk-系列--通用-rockchip-sbc-rk3576--rk3588-排障卡)
+- [Card 2: Seeed Studio reCamera (SG2002 / RISC-V / ARM) 排障卡](#card-2-seeed-studio-recamera-sg2002--risc-v--arm-排障卡)
+- [Card 3: Seeed Studio reCamera Pro (RV1126B / Buildroot) 排障卡](#card-3-seeed-studio-recamera-pro-rv1126b--buildroot-排障卡)
+- [Card 4: Seeed Studio SenseCAP Watcher / MCU 设备 (ESP32) 排障卡](#card-4-seeed-studio-sensecap-watcher--mcu-设备-esp32-排障卡)
+
+---
+
+## Card 1: Seeed Studio reComputer RK 系列 / 通用 Rockchip SBC (RK3576 / RK3588) 排障卡
+
+适用于 Seeed Studio reComputer RK 系列主机及通用 Rockchip aarch64 Linux 系统（运行 Debian 12 / Ubuntu 22.04+ 内核 6.1.x）。
+
+### 1.1 Docker 启动失败 `iptables: Failed to initialize nft` ⚠️ CRITICAL
+- **症状**：
+  ```text
+  iptables: Failed to initialize nft: Protocol not supported
+  docker info 报错 Cannot connect to the Docker daemon
+  ```
+- **根因**：部分 Linux 6.1.x BSP 内核编译时未开启 `CONFIG_NFT_COMPAT`，不支持 nftables backend。而现代 Docker 默认使用 nftables 初始化网络桥接。
+- **修复**：在 Docker 启动前切换为 iptables-legacy：
+  ```bash
+  sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
+  sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
+  sudo systemctl reset-failed docker
+  sudo systemctl restart docker
+  ```
+
+### 1.2 网络镜像源国内阻断
+- **症状**：`docker compose pull`、`pip install`、`huggingface-cli download` 频繁超时。
+- **修复**：
+  - Docker：配置国内镜像或重写 compose 文件的 image 地址；
+  - Python：`export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple`；
+  - HuggingFace：`export HF_ENDPOINT=https://hf-mirror.com`；
+  - APT：使用清华/阿里源替换 `/etc/apt/sources.list`。
+
+### 1.3 RKNN WSL2/x86 仿真正常但真机推理异常 / FP16 数值溢出
+- **症状**：ONNX 转 RKNN 在主机端 simulator 能跑通，但在 RK3588/RK3576 真机推理时输出 NaN/Inf，或模型中间层计算溢出（特别是语音 ASR Paraformer 等包含深层 FFN 的模型）。
+- **根因**：
+  - RKNN NPU 硬件不支持标准的 IEEE 754 完整动态范围 FP32，全图 FP16 在后段高动态层可能越界溢出；
+  - Simulator 与真机 `librknnrt` 在动态 Shape、CPU fallback 算子支持度上存在差异。
+- **修复（Hybrid Split 混合切分）**：
+  - 将易溢出的前置主干网保留在 NPU 跑 FP16；
+  - 将后段易越界计算层（如 Block 30 之后或 Decoder 采样层）保留在 CPU 走 ONNX Runtime 运行；
+  - 务必上真机测试精度与各层输出张量的 L2 范数差距（`rel_l2 < 0.05`）。
+
+### 1.4 NPU 多核调度与设备节点权限
+- **RK3588（3 核 NPU，6 TOPS）**：
+  - 核心分配掩码 `rknn_core_mask`：
+    - `0x1`（Core 0）、`0x2`（Core 1）、`0x4`（Core 2）、`0x7`（Core 0+1+2 聚合运行大模型）；
+  - 多路视频流推理推荐各通道绑定单独立核心（`RKNN_NPU_CORE_0`、`1`、`2`），吞吐量远高于抢占单核。
+- **设备权限保底**：
+  ```bash
+  ls -l /dev/rknn*
+  # 若非 root 用户无权访问，添加 udev 规则：
+  echo 'KERNEL=="rknn*", MODE="0666", GROUP="users"' | sudo tee /etc/udev/rules.d/99-rknn.rules
+  sudo udevadm control --reload-rules && sudo udevadm trigger
+  ```
+
+### 1.5 板端多核编译防 OOM 崩溃
+- **症状**：在板端执行 `make -j8` 或 `ninja` 时，系统突然死机、卡死或报错 `c++: fatal error: Killed signal terminated program cc1plus`。
+- **根因**：编译 C++ 大型模板或神经网络库时单个编译线程耗费 1.5GB+ 内存，并发数超标直接触发 Linux 内核 OOM Killer 杀掉编译器甚至内核崩溃。
+- **修复**：
+  - 严格限制并发线程数：`MAX_JOBS = min(nproc, RAM_GB / 1.5)`；
+  - 创建 4GB+ 临时 Swap 避免爆内存：
+    ```bash
+    sudo fallocate -l 4G /swapfile
+    sudo chmod 600 /swapfile
+    sudo mkswap /swapfile
+    sudo swapon /swapfile
+    ```
+
+---
+
+## Card 2: reCamera (SG2002 / RISC-V / ARM) 通用排障卡
+
+适用于轻量多核视觉设备（运行定制 Linux/Buildroot，集成单核/多核 NPU 与 ISP）。
+
+### 2.1 内核 VPSS FIFO Overflow 崩溃 ⚠️ CRITICAL
+- **症状**：
+  - `dmesg` 报错：
+    ```text
+    isp_err_chk: CSIBDG_A fifo overflow
+    vpss_sbm_err_handle: img(1) grp(0) vi err
+    Unable to handle kernel paging request at virtual address ...
+    Oops [#1]
+    ```
+  - 网络 `ping` 能通，但 `ssh`、`http`、`mqtt` 全部无响应。
+- **根因**：内核底层 `cv181x_vpss` 驱动在处理高频抢占或未释放的 VI 视频通道时存在溢出 Bug。如果频繁启停摄像头服务或在自动化评测中无限循环 A/B 测试，极易耗尽 FIFO。
+- **处置与预防**：
+  1. 一旦发生，**必须拔掉电源进行物理断电重启**（纯软重启 `reboot` 无法复位挂死的硬件 ISP 寄存器）；
+  2. 严格限制切换频率：不同模型或方案切换必须保证前一进程已彻底退出，并 `sleep 3` 秒再开启新实例；
+  3. 同一时间只允许单实例占用相机节点。
+
+### 2.2 动态库 `libsns_*.so` 报错为非致命噪音（红鲱鱼）
+- **症状**：
+  ```text
+  Error loading shared library libsns_gc2053.so: No such file or directory
+  Error relocating ... g_aeGc2053_MirrorFip: symbol not found
+  ```
+- **根因**：视觉组件在初始化时会尝试枚举匹配所有可能支持的 Sensor（如 OV5647、GC2053 等）。固件中只包含实际配备的 Sensor 驱动，musl loader 会打印缺失警告，但随后会成功匹配实际存在的 Sensor。
+- **判别标准**：检查后续日志是否正常输出 `MQTT topic` 或 `Inference result`。若有，则此报错为纯日志噪音，切勿浪费时间到处寻找该 so。
+
+### 2.3 `sscma-micro` 子模块升级冲掉本地模型注册
+- **症状**：拉取或更新上游代码后，启动报 `ModelFactory::create returned nullptr - model format not recognized`。
+- **根因**：上游原厂库通常未包含本地扩展的单输出模型类（如 `YoloSingle`），直接拉取上游会导致本地派生类被覆盖删除。
+- **修复**：维护本地补丁分支，升级时显式保留 `ma_model_yolo_single.{cpp,h}` 并保证在 Factory 注册链中优先于通用宽泛的匹配项注册。
+
+### 2.4 SSH Host Key 频繁变动
+- **症状**：设备恢复出厂、重刷或多台设备共用同一调试 IP 时，报错 `REMOTE HOST IDENTIFICATION HAS CHANGED!`。
+- **修复**：
+  ```bash
+  ssh-keygen -R <device_ip>
+  ssh -o StrictHostKeyChecking=accept-new <user>@<device_ip>
+  ```
+  不要使用 `StrictHostKeyChecking=no` 彻底关闭安全保护，推荐使用 `accept-new` 自动接受新设备公钥。
+
+---
+
+## Card 3: reCamera Pro (RV1126B / Buildroot) 通用排障卡
+
+适用于高帧率视觉 SoC（Buildroot Linux + rkipc 管道框架 + 独立 NPU）。
+
+### 3.1 ⛔ 严禁 `while true` 死循环拉起进程（Fork 风暴致死）⚠️ CRITICAL
+- **症状**：
+  - 用 `while true; do rkipc; sleep 1; done` 做进程保活；
+  - 一旦应用遇到语法错误或参数不匹配快速闪退，循环会以极高频率不断尝试 fork 新进程；
+  - **严重后果**：整机进程 PID 资源耗尽。内核 ICMP 网络栈仍能极快响应 `ping`（<0.5ms），但 `ssh`、`adb`、`http` 全部由于无法 `fork()` 会话而瞬间拒绝连接。整机用户态瘫痪，**只能拔掉供电物理断电重启**。
+- **预防与守则**：
+  1. 调试阶段严禁使用死循环脚本拉起进程；
+  2. 守护必须使用系统自带的 SysVinit 或受控守护进程，配置最大重启失败次数阈值；
+  3. 热替换调试采用单次调试启动，前台监控日志。
+
+### 3.2 `killall` 漏杀与双实例抢相机触发内核崩溃
+- **症状**：`killall rkipc` 成功返回，但启动新版本时仍报 `Device or resource busy`，甚至导致内核 Oops。
+- **根因**：`killall` 仅匹配精确进程名。如果自编译版本名为 `rkipc.new` 或带有路径，`killall` 会静默漏杀旧进程，造成两个实例同时抢占 VI/VPSS 通道。
+- **修复规范**：
+  ```bash
+  # 必须使用 pgrep -f 匹配完整命令行
+  for p in $(pgrep -f rkipc); do kill -9 $p; done
+  sleep 3 # 关键：必须等待 3 秒释放视频通道硬件资源
+  ```
+
+### 3.3 adbd 退出时 Reap 掉 detach 子进程
+- **症状**：通过 `adb shell 'setsid rkipc &'` 后台拉起进程，断开 adb 终端后进程直接消失。
+- **根因**：adbd 会在会话断开时主动收割（reap）该会话树下的所有孤儿/子进程。
+- **修复**：
+  1. 将启动命令写入独立脚本文件（如 `/userdata/start.sh`），在脚本内部使用 `exec` 替换进程 PID，使其脱离 adbd 子树由 init 托管；
+  2. 或通过标准后台服务启动机制执行。
+
+### 3.4 OSD Overlay Layer 图层优先级与色彩倒置
+- **症状**：
+  - RGN API 显示创建成功、绑定成功，但在 RTSP/VENC 编码流画面中完全看不到标注框；
+  - 标注框颜色异常（例如指定红色变成了青色）。
+- **根因**：
+  1. 硬件 VENC 编码器通常仅合成特定的低图层（如 Layer 1/5 可见，Layer 3/7 属于不可见的旁路）；
+  2. OSD 颜色字节序为 ARGB 与 BGRA 的差异，若未显式翻转通道会导致颜色互补反转。
+- **排查顺位**：画框不显示时**优先检查 Layer 层级值**，而非怀疑坐标计算或画框失败。
+
+---
+
+## Card 4: MCU / 纯固件设备 (Watcher / ESP32) 通用排障卡
+
+适用于单片机与纯固件设备（FreeRTOS / 裸机）。
+
+### 4.1 串口权限与烧录模式
+- **症状**：`esptool` 或烧录工具报错 `Permission denied: /dev/ttyUSB0` 或 `Failed to connect to ESP32: Timed out waiting for packet header`。
+- **排障**：
+  - 检查权限：`sudo usermod -aG dialout $USER`；
+  - 检查 Flash 模式：高频板建议使用 `DIO` 模式（40MHz/80MHz），严禁在不支持的 Flash 上强开 `QIO`；
+  - 烧录前拉低 GPIO0（或按住 BOOT 键插入 USB）。
+
+### 4.2 NVS 空间损坏与出厂分区对齐
+- **症状**：固件烧录成功，但每次重启后配置丢失，报 `nvs_flash_init failed (ESP_ERR_NVS_NO_FREE_PAGES)`。
+- **修复**：
+  ```bash
+  esptool.py --chip <chip> erase_flash # 全量擦除坏块与残留 NVS
+  # 重新烧录完整分区表与固件
+  ```
+
+---
+
+## 快速自检对照表
+
+| 遇到此类症状 | 快速诊断命令 | 对应排障卡 |
+|---|---|---|
+| Docker 启动报 nft 协议错误 | `dmesg \| grep -i nft` | [Card 1 §1.1](#11-docker-启动失败-iptables-failed-to-initialize-nft--critical) |
+| 板端编译卡死 / OOM | `dmesg \| grep -i oom` / `free -h` | [Card 1 §1.5](#15-板端多核编译防-oom-崩溃) |
+| ping 通但 SSH/HTTP 全瘫痪 (Userspace 耗尽) | **停止重连，物理断电重启** | [Card 3 §3.1](#31--严禁-while-true-死循环拉起进程fork-风暴致死--critical) |
+| 摄像头启动报 FIFO overflow | `dmesg \| grep -i fifo` | [Card 2 §2.1](#21-内核-vpss-fifo-overflow-崩溃--critical) |
+| 模型画框不显示在视频流中 | 检查 RGN Layer 编号（使用低层如 1/5） | [Card 3 §3.4](#34-osd-overlay-layer-图层优先级与色彩倒置) |
+| `libsns_*.so` 缺失警告 | 若推理正常则属于正常 Sensor 枚举噪音 | [Card 2 §2.2](#22-动态库-libsns_so-报错为非致命噪音红鲱鱼) |

package/skills/solution-cli/references/generic-rk3588.md

@@ -0,0 +1,106 @@
+# Rockchip RK3588 开发、编译与故障排查指南 (RK3588 & Seeed reComputer RK Guide)
+
+> **定位**：供 AI Agent 在用户基于 **Seeed Studio reComputer RK 系列** 或通用 Rockchip RK3588 (aarch64 Linux) 主机进行 **模型编译、Docker 部署、NPU 驱动调试或二次开发** 时查阅。
+> **官方产品背书与原则**：
+> 1. **Seeed 官方产品**：Seeed Studio 官方提供基于 Rockchip 高算力平台的 **reComputer RK 系列**（如 RK3588、RK3576 等硬件 SKU），出厂配备官方标准 BSP、散热外壳与外设接口。
+> 2. **剥离外部第三方硬件噪音**：完全剔除前期技术验证中涉及的外部第三方竞品开发板名称，提炼为统一的 Seeed 硬件体系与芯片级通用工程排障指南。
+
+---
+
+## 1. RK3588 硬件与 NPU 基础架构
+
+Rockchip RK3588 是一颗八核 64 位处理器（4×Cortex-A76 + 4×Cortex-A55），内置 3 个独立的 NPU 核心（每个核心提供 2 TOPS 算力，峰值算力 6 TOPS INT8）。
+
+### 1.1 关键硬件节点与驱动文件
+在任何标准 RK3588 Linux 系统中，NPU 与多媒体加速依赖以下底层设备节点：
+- `/dev/rknn`（或 `/dev/rknpu*`）：NPU 驱动设备节点；
+- `/dev/mpp_service`：Rockchip 硬件多媒体编解码（MPP）设备节点；
+- `/dev/rga`：2D 图形与格式转换（RGA）硬件加速设备节点；
+- `/dev/dma_heap/`：用于 NPU 与 MPP 之间零拷贝（Zero-Copy）的连续物理内存管理。
+
+---
+
+## 2. 常见系统级故障与通用排查 (Common Gotchas)
+
+### 2.1 Docker 启动报错：Failed to initialize nft / Protocol not supported
+- **根因**：多数针对 RK3588 的 Linux 5.10 内核在编译时未开启 `CONFIG_NF_TABLES`，而较新版本的 iptables 默认采用 `nf_tables` 后端。
+- **通用修复命令**（板端执行一次即可）：
+  ```bash
+  sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
+  sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
+  sudo systemctl restart docker
+  ```
+
+### 2.2 容器内 NPU 访问被拒绝：cannot open /dev/rknn 或 Permission Denied
+- **根因 1：Docker 未挂载 NPU 设备节点**
+  在 `docker run` 或 `docker-compose.yml` 中必须显式透传设备：
+  ```yaml
+  services:
+    my-app:
+      devices:
+        - /dev/rknn:/dev/rknn
+        - /dev/mpp_service:/dev/mpp_service
+        - /dev/rga:/dev/rga
+        - /dev/dma_heap:/dev/dma_heap
+  ```
+- **根因 2：非 root 用户缺少 udev 访问权限**
+  在宿主机配置 udev 规则赋予权限：
+  ```bash
+  echo 'KERNEL=="rknn*", MODE="0666"' | sudo tee /etc/udev/rules.d/99-rknn.rules
+  echo 'KERNEL=="mpp_service*", MODE="0666"' | sudo tee -a /etc/udev/rules.d/99-rknn.rules
+  echo 'KERNEL=="rga*", MODE="0666"' | sudo tee -a /etc/udev/rules.d/99-rknn.rules
+  sudo udevadm control --reload-rules && sudo udevadm trigger
+  ```
+
+### 2.3 NPU 驱动版本与 Runtime 运行时不兼容 (RKNN Version Mismatch)
+- **排查命令**：
+  ```bash
+  # 检查宿主机内核 NPU 驱动版本
+  dmesg | grep -i rknpu
+  ```
+- **关键规则**：
+  - RK3588 必须使用 **RKNN-Toolkit2**（对应 `librknnrt.so` 版本通常为 v1.5.x, v1.6.x 或 v2.x），绝对不能使用针对上一代 RK1808/RV1109 的 RKNN-Toolkit1；
+  - 容器内的 `librknnrt.so` 版本必须 **大于或等于** 宿主机内核中的驱动驱动版本。若报错 `RKNN_ERR_DEVICE_UNMATCH`，需升级宿主机内核驱动固件或降级镜像内的 runtime。
+
+---
+
+## 3. 板端编译与构建最佳实践 (Building on Device)
+
+### 3.1 限制多线程并发编译，防止内存耗尽 (OOM Kill)
+- **痛点**：RK3588 具备 8 个核心，开发者习惯敲 `make -j8`，但在编译 OpenCV、ONNX Runtime 或 PyTorch 扩展时，每个编译进程会占用 1~1.5GB 内存，直接触发内核 OOM killer 杀死进程。
+- **推荐做法**：
+  ```bash
+  # 8GB 内存设备推荐最大并发为 4
+  make -j4
+  # 或者增加 8GB 虚拟内存 Swap 分区
+  sudo fallocate -l 8G /swapfile && sudo chmod 600 /swapfile
+  sudo mkswap /swapfile && sudo swapon /swapfile
+  ```
+
+### 3.2 CMake 关键参数标准配置
+在编写或修改 `CMakeLists.txt` 构建 C++ 推理应用时：
+```cmake
+# 显式启用 RKNPU2 目标后端
+set(CMAKE_CXX_STANDARD 14)
+target_include_directories(my_app PRIVATE ${RKNN_API_PATH}/include)
+target_link_libraries(my_app PRIVATE ${RKNN_API_PATH}/lib/librknnrt.so dl pthread)
+```
+
+---
+
+## 4. RK3588 算力调优：三核 NPU 调度与硬件零拷贝
+
+### 4.1 多核心分流调度 (Multi-core NPU Balancing)
+RK3588 的 3 个 NPU 核心可以通过 `rknn_core_mask` 手动绑定，避免多线程挤占同一核心导致上下文频繁切换：
+- `RKNN_NPU_CORE_0`：绑定核心 0（适合处理主视频流）；
+- `RKNN_NPU_CORE_1`：绑定核心 1（适合处理次级任务或特征比对）；
+- `RKNN_NPU_CORE_2`：绑定核心 2；
+- `RKNN_NPU_CORE_0_1_2` / `AUTO`：单模型跨核并发加速（大模型降低单帧延迟）。
+
+### 4.2 全链路硬件加速防 CPU 占满
+- **反模式**：使用纯 Python OpenCV `cv2.VideoCapture` 软解 RTSP H.264/H.265 流，CPU 占用率飙到 300%~500%，系统发热降频。
+- **推荐架构**：
+  `RTSP H.264/H.265` ➔ **Rockchip MPP 硬件解码** ➔ 输出 NV12 格式
+  NV12 ➔ **RGA 硬件缩放 & BGR 转换** ➔ 直接输入内存缓冲区
+  内存缓冲区 ➔ **NPU 执行推理**（Zero-Copy DMA 共享）
+  整个流水线 CPU 占用率通常不足 20%。