@seeed-studio/solution-cli 0.3.2 → 0.4.1

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%。

package/skills/solution-cli/references/hardware-bom.md

@@ -21,13 +21,15 @@ solution-cli product query <family_id> --json
 ```
 - 获取产品族名称、官方默认主 SKU、物理电气规格（电压、电流接口、M.2 槽位等）以及内置的 UTM 商城购买直达链接。
 
-### 动作二：查询经过验证的配件清单
+### 动作二：查询经过验证的配件清单与批量加购链接
 ```bash
-solution-cli product accessories <family_id> --json
+solution-cli product accessories <family_id> --compact --json
 ```
 - 输出严格由确定性代码计算物理兼容性的配件清单：
+  - `bundle_cart_url`：已自动将主机与必需配件打包的 Seeed 官方商城合并加购直达链接；
   - `REQUIRED` 列表：带必买技术原因（`reason`）、购买 SKU 与静默带 UTM 的直达链接；
-  - `OPTIONAL` 列表：带周边传感器、通信模块、固态硬盘与购买链接。
+  - `OPTIONAL` 列表：带周边传感器、通信模块、固态硬盘与购买链接；
+  - **建议务必加 `--compact`**：去除底层冗余兼容性树，Token 消耗降低 70%。
 
 ### 动作三：验证物理配件兼容性
 当用户提到已有某个第三方配件或自制电源/天线时：
@@ -78,6 +80,10 @@ Agent 严禁凭“常识”告知配件通用，必须遵循 CLI 评估结果并
 - **M.2 NVMe SSD 256GB** (SKU: `112990246`)：用于拉取 Docker 镜像与长期本地数据持久化。
 - **reSpeaker 4 麦克风阵列** (SKU: `107990193`)：若需补充语音呼叫或声音事件感知。
 
+#### 4. 🛒 一键批量合并采购 (Bundle Cart)
+- **官方商城直达**：`[点击此处将主机与必需配件一键加购结算](${bundle_cart_url})`
+  *(调用 `solution-cli product accessories <family> --json` 时直接提取 `bundle_cart_url` 输出给用户，点击即可一次性将主机及必需配件加入购物车，大幅缩短采购转化链路。国内用户提示通过天猫/淘宝 Seeed 官方店或代理商采购。)*
+
 ---
 > 📦 硬件采购并收到后，只要通电并插上网线，随时对我说“设备已连接，开始部署”，我将直接为您全自动化完成环境配置与方案运行！
 ```

package/skills/solution-cli/references/sales-feasibility.md

@@ -0,0 +1,65 @@
+# 销售方案可行性评估与需求匹配度指南 (Sales Feasibility & Matching Guide)
+
+> **定位**：供 AI Agent 在面对 **销售端询问团队技术能力边界（FEASIBILITY）**、**非标定制评估** 以及 **商机匹配度衡量（MATCHING_SCORE）** 时查阅。回答“我们能不能做”、“做这个需要多少周期”、“如何评估需求匹配度”。
+
+---
+
+## 1. 销售需求四级评估阶梯 (The 4-Tier Feasibility Matrix)
+
+当销售或商务询问“某某客户的需求我们能不能接/能不能做”时，严禁盲目回答“可以做”，必须按以下四级阶梯对齐技术成熟度：
+
+| 阶梯等级 | 判定特征与技术依据 | 推荐答复话术与研发周期 |
+|---|---|---|
+| **Tier 1: 开箱即用 (Turnkey)** | 官方方案库已有现成参考设计（`reference_design`），已有预编译 Docker 镜像与验证硬件（Orin/树莓派/瑞芯微）。 | **“完全支持，开箱即用”**。<br>周期：0 天（到货即部署）。直接提供官方方案落地页、BOM 清单与一键加购链接。 |
+| **Tier 2: 模型/协议适配 (Adaptation)** | 硬件算力与物理接口完全满足（如 Orin NX + 工业相机 + RS485），但需要更换目标检测模型（如把人脸换为特定零件缺陷），或需接入私有 Modbus 协议。 | **“技术可行，需轻量适配”**。<br>周期：1~2 周。支持通过开放的 Docker/Compose 与 ONNX/TensorRT 工具链接入，可由客户研发或我方技术支持协助跑通。 |
+| **Tier 3: 硬件拓展/研发立项 (Custom Engineering)** | 涉及非标工况（如户外防爆、-40℃ 超宽温、太阳能休眠超低功耗微安级），或需自研特殊算子与驱动（如高频毫米波雷达定制算法）。 | **“需研发评估与项目立项”**。<br>周期：4~8 周以上。需销售组织现场工况评审会，评估硬件选型打样成本与预期出货量。 |
+| **Tier 4: 物理超限 (Physically Infeasible)** | 违反物理规律或边缘算力严重倒挂（如要求 ESP32 跑 4K 30FPS 大模型全功能分割、无红外打光在全黑环境要求百米人脸抓拍）。 | **“物理上不可行，需调整方案设计”**。<br>明确解释物理原因（如算力/光学极限），并提供升阶改造建议（如增加外部补光或升级为 Jetson 工控机）。 |
+
+---
+
+## 2. 需求匹配度四维量化打分法 (Matching Score: 0~100%)
+
+当面对多个商业需求时，利用以下 4 项确定性工程维度进行加权评分，输出结构化匹配卡：
+
+$$Score = \text{算法成熟度}(35\%) + \text{硬件适配性}(30\%) + \text{现场工况条件}(20\%) + \text{交付闭环复杂度}(15\%)$$
+
+```markdown
+### 🎯 方案匹配度评估：85% (高匹配 · 推荐推进)
+
+- [x] **算法就绪度 (95%)**：官方已有成熟参考设计，已预置推理管线。
+- [x] **硬件适配性 (90%)**：推荐 reComputer J4012 (Orin NX)，算力满足并发路数。
+- [!] **现场工况条件 (70%)**：现场需工业防尘，建议选配 IP66 防护机箱与工业级电源。
+- [x] **交付周期 (90%)**：纯容器化部署，到货即可完成自动化交付。
+
+💡 **商务建议**：属于成熟方案，交付风险低，建议销售直接输出 BOM 报价并跟进采购。
+```
+
+---
+
+## 3. 双轨业务策略控制 (Business Policy Switching)
+
+根据团队当前交付负荷与销售阶段，Agent 可根据提示词自动切换或由用户指定策略：
+
+### 策略 A：`strict`（严格挑活 · 聚焦标准化规模交付）
+- **触发条件**：交付团队高负荷、大促期、或明确要求“只要现成标准方案”。
+- **规则**：
+  - **匹配度 $\ge 80\%$**：积极推进，提供 BOM 与自动化部署指南；
+  - **匹配度 $< 80\%$**：礼貌婉拒非标，守住研发成本底线：
+    > *“根据现场工况，目前官方方案库尚无开箱即用的标准套件。为确保您的交付稳定性与工程成本，建议优先考虑标准化场景，或参考 Seeed 开源硬件底座自行评估二次开发。”*
+
+### 策略 B：`flexible`（积极适配 · 扩大商机与生态定制）
+- **触发条件**：业务开拓期、新市场线索挖掘、战略大客户定制。
+- **规则**：
+  - **匹配度 $\ge 50\%$**：积极拆解定制路径：
+    > *“目前虽然没有 100% 对应的现成整机套件，但底层硬件平台（如 reComputer Jetson / SenseCAP）具备完全兼容的算力与工业接口，只需 1~2 周进行模型微调或协议适配即可跑通，我们可提供完整的二次开发技术 Wiki 与 GitHub 仓库。”*
+
+---
+
+## 4. 销售常用算力与并发速查卡 (Hardware Capability Benchmarks)
+
+| 主机平台 | AI 算力 (INT8) | 视频分析路数上限 (1080P 15FPS) | 典型适用场景 | 工业接口支持 |
+|---|---|---|---|---|
+| **reComputer J3011 (Orin Nano 8GB)** | 40 TOPS | 2 ~ 4 路 | 跌倒检测、客流统计、离线语音助手 | USB 3.2, GbE, M.2 Key-M, M.2 Key-E |
+| **reComputer J4012 (Orin NX 16GB)** | 100 TOPS | 6 ~ 8 路 | 多路车牌识别、流水线表面缺陷质检、多模态视觉 | USB 3.2, GbE, CAN 总线扩展, M.2 Key-M |
+| **reComputer RK3576 / RK3588** | 6 TOPS NPU | 1 ~ 3 路 | 高性价比人脸抓拍、低功耗边缘网关 | 双千兆网口, 隔离 RS485, 工业宽温 |
+| **reCamera (SG2002)** | 1 TOPS | 单路自摄抓拍 | 独立点位人员统计、门禁人脸识别、轻量姿态 | PoE 供电, 板载相机, 免拉长线 |

package/skills/solution-cli/references/secondary-development.md

@@ -13,14 +13,14 @@ Seeed SenseCraft 方案体系在 GitHub 上采用清晰的双层开源结构：
 graph LR
     subgraph Repo1["1. 方案编排层 (Solution Package)"]
         direction TB
-        R1_URL["github.com/Seeed-Studio/sensecraft-solutions"]
+        R1_URL["CLI 返回的方案编排仓库"]
         R1_Content["包含 solution.yaml, devices/*.yaml, docker-compose.yml, 启动脚本"]
         R1_Fit["适合：改端口、加环境变量、调整数据卷、增减联动微服务"]
     end
 
     subgraph Repo2["2. 核心算法与业务源码层 (Core App/Algorithm)"]
         direction TB
-        R2_URL["各场景独立开源代码仓 (ModelAssistant / warehouse_system 等)"]
+        R2_URL["CLI 返回的场景源码仓库"]
         R2_Content["包含 Python 推理主循环、Vue/React 前端看板、模型权重、后处理时序"]
         R2_Fit["适合：重训模型、改检测类别与阈值、重构业务 UI、对接私有云数据库"]
     end
@@ -34,17 +34,20 @@ graph LR
 使用 CLI 查询方案元数据：
 ```bash
 solution-cli hub search "<方案名称或关键词>" --json
+solution-cli hub get <reference-design-id> --section links --json
 ```
-- 输出中的 `repo_url` 提供了官方代码仓地址（例如 `https://github.com/Seeed-Studio/sensecraft-solutions/tree/main/solutions/fall_detection` 或核心项目地址）。
+- 只使用 `hub get --section links` 返回并标明角色为 repository/source 的
+  URL。不要根据 RD ID、落地页路径或 Wiki 路径自行拼接 GitHub、Wiki 或
+  CDN 地址；没有声明仓库时明确说明源码地址未提供。
 
 ### 步骤二：克隆方案到本地工程目录
 指导用户或在本地工作空间执行克隆：
 ```bash
-# 方案编排包开发
-git clone https://github.com/Seeed-Studio/sensecraft-solutions.git ./my-solutions
+# 方案编排包开发；将 CLI 返回的 repository/source URL 填入
+git clone <declared-repo-url> ./my-solutions
 
 # 或核心算法项目开发（以视觉推理为例）
-git clone https://github.com/Seeed-Studio/ModelAssistant.git ./my-model-assistant
+git clone <declared-repo-url> ./my-model-assistant
 ```
 
 ---
@@ -81,4 +84,4 @@ sensecraft-engine deploy <id> --solutions-dir ./my-solutions/solutions
 
 1. **主动提供溯源**：当用户明确表达“想要改底层逻辑”、“换自研模型”时，主动告诉用户代码所在，并给出克隆建议。
 2. **语气自然诚恳**：
-   - 示例：“*这套方案的源码完全开源在 [GitHub 仓库](https://github.com/suharvest/sensecraft-solutions/tree/main/solutions/<id>)。您可以克隆到本地，告诉我您具体想改哪部分（比如替换成自研的 Pose 模型或改告警通知格式），我可以直接帮您修改代码并用引擎本地联调。*”
+   - 示例：“*先执行 `solution-cli hub get <rd-id> --section links --json`，我会使用返回的已声明源码链接。确认仓库地址后，再克隆到本地并按方案文档联调。*”