@seeed-studio/solution-cli 0.2.0 → 0.3.1

package/skills/sensecraft/references/consult-and-select.md

@@ -27,30 +27,94 @@
 ```bash
 solution-cli hub search "<用户关键词>" --limit 5 --json
 ```
-- **输出结果解释**：
-  - 提取匹配的 `Scenario`（阐述业务场景、痛点、成效）；
-  - 提取推荐的 `Reference Design`（阐述技术路线、预设模式 presets、开发 wiki）；
-  - 提取 `family_ids`（推荐的主板/相机/网关产品族）。
-
-### 动作二：向用户呈现专业方案推荐模板
-在向用户回答时，遵循以下结构化呈现，**严禁一上来就输出 deploy 命令**：
-
-```markdown
-### 💡 方案匹配建议
-
-1. **业务场景**：[场景名称]（如：养老看护）
-   - **痛点与价值**：[简述核心业务价值，如：端侧跌倒检测，1.4s 本地快速判定，视频不出设备彻底保护隐私]
-2. **推荐参考设计**：[参考设计名称]（ID: `fall_detection`）
-   - **技术方案**：[骨骼姿态估计 / MQTT 告警联动]
-   - **预设模式**：[如 recamera, jetson, rk, hailo]
-   - **开发 Wiki**：[官方 Wiki 链接]
-3. **推荐主硬件**：[硬件族列表，如 reComputer J4012, reCamera Pro]
-   - 采购与配件明细可进一步通过硬件选型指引查询。
-```
+- **输出结果说明**：
+  - `Scenario`：业务场景、痛点、成效、官方场景落地页（`landing_url`）；
+  - `Reference Design`：技术路线、预设模式 presets、开发 wiki（`wiki_url`）、官方方案落地页（`landing_url`）、源码仓库（`repo_url`）；
+  - `family_ids`：推荐的主板/相机/网关产品族。
+
+---
+
+## 3. 现场工况诊断与场景提问知识库 (Domain Diagnostic Playbook)
+
+> [!IMPORTANT]
+> **拒绝自说自话！真正的方案专家不仅回答问题，更主动诊断现场工况。**
+> 当用户提出场景诉求时，调用 `solution-cli hub search "<关键词>" --json` 会在返回记录中直接携带该场景的 `diagnostic_playbook`。
+> Agent **必须结合工况诊断知识库，主动提出 2~3 个决定物理架构、通信链路与商务成本的关键问题**，并解释“为什么问这个问题”（如利旧省钱、避免停机、规避环境干扰）。
+
+### 3.1 四大底层工程决断杠杆 (The 4 Engineering Levers)
+
+无论面对何种行业场景，所有诊断追问均围绕以下 4 个决定硬件选型与系统拓扑的核心杠杆展开：
+
+| 工程决断杠杆 | 核心影响与决断依据 | 典型追问切入点 |
+|---|---|---|
+| **1. 物理拓扑分布**<br>(集中式 vs 分布式) | 决定是采用“1 台计算主机集中拉流/汇聚”（极度摊薄单点算力成本），还是“分布式独立一体化终端”（免拉长线、点位隔离）。 | “点位是在同一栋楼/同一车间集中分布，还是分散在多处？” |
+| **2. 存量资产利旧**<br>(绿地新建 vs 棕地利旧) | 决定是否能直接复用客户现有的监控摄像头（RTSP/ONVIF）、传感器（RS485/Modbus）或 PLC，为客户节省 50%~70% 硬件采购成本。 | “现场是否已经有现成的摄像头/传感器？支持什么协议？” |
+| **3. 供电与通信边界**<br>(市电 vs 电池 / 有线 vs 无线) | 决定供电配件（220V 电源适配器 vs 太阳能/电池休眠机制）以及网络介质（PoE 网线、Wi-Fi、4G 插卡、LoRaWAN 远距离低功耗）。 | “安装点是否有 220V 市电？是否方便布设网线（PoE）？” |
+| **4. 业务执行与闭环联动**<br>(被动看板 vs 主动控制) | 决定硬件接口规格（是否需要工业隔离数字量 I/O、继电器触点、CAN 总线）以及告警延迟容忍度。 | “判定异常后，是仅在大屏/手机告警，还是需直接联动 PLC/气缸/道闸执行控制？” |
+
+---
+
+### 3.2 各大行业场景工况诊断速查表 (Scenario Diagnostic Matrix)
+
+当用户询问特定领域时，Agent 查阅下表或提取 CLI 返回的 `diagnostic_playbook` 发起专业诊断：
+
+| 行业领域与场景 ID | 核心工况关注点 | 推荐诊断追问 (2~3 问) | 追问背后的技术与商务决断理由 (Rationale) |
+|---|---|---|---|
+| **智慧养老 / 监护**<br>`elderly-care-monitoring` | • 空间集中还是分散<br>• 存量摄像头利旧<br>• 卫生间/卧室隐私顾虑 | 1. 房间是在同一栋楼集中分布，还是分散在各栋楼？<br>2. 现场公共区域是否已有海康/大华等 RTSP 监控摄像头？<br>3. 卫生间、卧房等私密区域是否介意纯光学镜头，是否需毫米波雷达？ | 集中可用 1 台 reComputer 拉多路流摊薄成本；已有摄像头直接利旧节省采购预算；私密空间用 60GHz 毫米波雷达替代相机彻底规避隐私风险。 |
+| **智慧农业 / 微气象**<br>`environment-monitoring` | • 连栋温室 vs 广域农田<br>• 220V 市电 vs 太阳能/电池<br>• 空气微气象 vs 土壤剖面水肥 | 1. 监测区域是集中式温室大棚（百米级），还是大面积大田/果园（数公里级）？<br>2. 测点安装位置是否有市电，还是需野外太阳能/电池长续航？<br>3. 核心监测指标是什么（仅空气温湿度/光照，还是需土壤剖面水肥水分/EC/pH）？ | 大棚百米级可用 RS485 总线；广域农田必须用 LoRaWAN 远距低功耗网关（SenseCAP M2）；野外无电需选配超低功耗休眠传感器节点；水肥指标需搭配工业级土壤传感器。 |
+| **工业视觉质检 / 缺陷**<br>`industrial-visual-inspection` | • 流水线节拍与飞拍<br>• 工件表面反光与材质<br>• PLC 剔除信号闭环 | 1. 流水线节拍如何（每分钟过检多少件，工件是静止还是运动中飞拍）？<br>2. 工件表面是反光金属/镜面塑料还是漫反射纸盒？缺陷精度在什么毫米级？<br>3. 检测出不良品后，边缘设备是否需直接向 PLC/气缸发送数字量剔除信号？ | 运动飞拍必须选用全局快门相机与高 TOPS Jetson（Orin NX）；反光金属表面需定制偏光/同轴光源消除眩光；剔除联动需配置带工业隔离 I/O 的工控机型。 |
+| **智慧交通 / 园区道闸**<br>`parking-traffic-vision` | • 出入道闸 vs 主干道行驶<br>• 夜间强光抑制与补光<br>• 本地继电器开闸联动 | 1. 抓拍点是低速出入口道闸（1~2车道），还是园区主干道（中高速行驶中抓拍）？<br>2. 夜间或出入口逆光环境如何？是否有充足照明或需强光抑制补光？<br>3. 车牌识别后，是边缘主机直接短接继电器起杆，还是上报停车计费软件？ | 道闸场景普通高帧率相机即可，干道需全局快门与高速跟踪模型；大灯直射需强光抑制爆闪补光；本地开闸需硬件隔离继电器配件并支持离线脱机白名单。 |
+| **现场语音控制 / 助手**<br>`conversational-voice-ai` | • 声学噪声与拾音距离<br>• 100% 离线脱网 vs 云端大模型<br>• 下位机受控设备协议 | 1. 现场使用环境噪音如何（安静室内还是背景嘈杂机器轰鸣）？拾音距离多远？<br>2. 对网络和隐私是否有硬性要求？必须 100% 离线断网还是可以联网调用大模型？<br>3. 语音识别或大模型理解后，主要用来控制什么设备（Home Assistant、MQTT 还是串口继电器）？ | 嘈杂远场（3~5米）必须配置带硬件 DSP/AEC/波束成形的 ReSpeaker XVF3800；纯离线需 Orin NX 跑端到端小模型（Whisper+LLM+TTS），混合模式可用轻量机做拾音。 |
+| **旧建筑节能改造 / 暖通**<br>`building-energy-retrofit` | • 存量表计通信接口<br>• 配电室集中 vs 跨楼层分布<br>• 纯能耗抄表 vs 空调闭环控制 | 1. 现场电表/水表/空调是否自带 RS485（Modbus/DLT645）通信接口，还是老旧机械表？<br>2. 表计集中在配电机房，还是分散在各楼层强电井？楼层间有无预埋网线？<br>3. 仅做能耗数据上报与统计，还是需根据用电策略反向控制空调启停回路？ | 带 485 接口可直接低成本总线抄表；跨楼层分散无布线推荐 SenseCAP LoRaWAN 采集器无线回传免穿墙打洞；闭环控制需配置带工业继电器与模拟量输出的网关。 |
+| **室内外定位 / 资产人员**<br>`indoor-outdoor-positioning` | • 纯室内 vs 室内外混合<br>• 米级具体坐标 vs 区域货架级<br>• 佩戴工牌卡片 vs 货物免维护长续航 | 1. 定位场景是纯室内（厂房/展厅），还是室内外混合（仓库到室外堆场/物流转运）？<br>2. 对定位精度的期望是精确到米级的坐标，还是只需知道在哪个房间/货架区域？<br>3. 被追踪对象是人员佩戴工牌，还是贴在货物托盘上？期望续航时间是多久？ | 纯室内基于 BLE 信标定位；室内外混合推荐 SenseCAP T1000 追踪器（室内切蓝牙/Wi-Fi，室外切 GPS/北斗）；区域级可大幅精简基站数量，极节约成本。 |
+| **现场控制与自动化**<br>`industrial-control-automation` | • 工控总线协议种类<br>• 电控柜 DIN 导轨与直流供电<br>• 实时控制毫秒级 vs 数据采集分析 | 1. 现场下位机主要采用什么总线协议（Modbus TCP/RTU、CANopen、PROFINET、EtherNet/IP）？<br>2. 是否安装在标准工业电控柜导轨上？现场供电是 DC 24V 还是 AC 220V？<br>3. 是需毫秒级实时控制闭环，还是做秒级/分级的数据采集与边缘分析诊断？ | 决定网关物理接口（隔离 RS485、双网口、CAN）与中间件；导轨安装与宽压输入匹配电控柜标准；实时控制需带 PREEMPT_RT 补丁控制器，采集可用常规工控机。 |
+
+---
+
+## 4. 推荐应答呈现规范（自然专家与诊断对话风格）
+
+向用户作答时，采用流利、专业的对话口吻，涵盖以下要素：
+1. **方案业务价值与实现逻辑**（直接讲透）：解释为何能在端侧解决问题、响应时间、隐私优势；
+2. **两类硬件架构对比**：说明一体机与工控机/Jetson 的各自适用场景；
+3. **参数可调性预告**：告知常见参数（如 MQTT 地址、检测灵敏度）部署后支持在线热修改；
+4. **自然延伸出口**：随口附上“了解更多”落地页与技术 Wiki；若涉及二次开发提供 GitHub 源码；
+5. **主动诊断追问（结合理由）**：提出针对该领域的 2~3 个工况诊断关键问题，并简明说明“为什么这样问能帮您优化方案或降低成本”。
+
+#### 范例 1：智慧农业 / 环境监测咨询
+> 做农业温室大棚和农田监测，推荐采用 **`agri_env_monitor`（农业环境监测方案）**。
+>
+> 它的架构是在现场测点布设工业级气象与土壤传感器，通过无线或工业总线将数据汇聚到本地网关（如 SenseCAP M2 或 reComputer），本地部署 Home Assistant 或轻量时序看板进行温湿度曲线、土壤墒情实时显示与越限告警。**系统支持完全纯本地离网运行，也可以通过 MQTT / 4G 桥接上云**。
+>
+> - **硬件组合**：大棚内部通常采用 **SenseCAP S2100 采集器 + 工业级土壤三参数探头（水分/EC/温度）**；如果需要户外微气象，可搭配 **S700 七合一气象站**。
+> - **参数灵活性**：数据上报周期（如 5 分钟、15 分钟）、温度报警阈值、MQTT 上报服务器等，部署后均支持在线随时调整。
+>
+> 💡 *如果想了解更多具体参数与传感器配件，可以浏览 [官方方案主页](https://www.seeedstudio.com/solutions/reference-designs/agri_env_monitor?utm_source=sensecraft_agent&utm_medium=solution_consult&utm_campaign=agri_env_monitor)；方案的看板与协议转换配置代码也开源在 [GitHub 仓库](https://github.com/suharvest/sensecraft-solutions/tree/main/solutions/agri_env_monitor)。*
+>
+> ---
+> **为了帮您设计最合理、施工最方便的硬件选型与网络拓扑，我想先了解几个现场工况：**
+> 1. **空间覆盖范围**：监测区域是集中在几座相连的温室大棚内（百米级），还是大面积分布在户外大田或果园（数公里级）？（*集中大棚可用 RS485 有线总线节约成本；广域大田必须采用 LoRaWAN 远距离低功耗无线网关*）
+> 2. **现场供电条件**：各个监测点是否有 220V 市电接口，还是在野外需要依赖太阳能电池板或自带大容量锂电池长续航运行？
+> 3. **核心监测深度**：主要关注空气微气象（温湿度/光照/CO2），还是需要深入监测土壤剖面水肥墒情（如深层土壤水分/EC盐分/pH）？
+
+#### 范例 2：工业流水线视觉质检咨询
+> 做产线表面缺陷或装配防错质检，通常推荐采用 **`edge_inspection_surface`（工业表面缺陷边缘质检方案）**。
+>
+> 它的机制是在工位上方架设工业相机，通过硬件触发或光电开关触发抓拍，边缘算力机（如 reComputer Jetson Orin）在端侧执行毫秒级缺陷分割或分类模型推理，**平均单帧判定时间在 20~40 毫秒以内，判定结果本地直接输出 OK/NG**，视频流无需上传云端。
+>
+> - **硬件算力**：单工位常规线速可采用 **reComputer J3011 (Orin Nano 8GB)**；如果是高节拍复杂缺陷或多工位合并，推荐 **reComputer J4012 (Orin NX 16GB)**。
+> - **接口与参数**：置信度阈值、缺陷最小像素面积均支持热配置，无需重新编译镜像。
+>
+> 💡 *更多机械安装与光学镜头打光指导可参考 [方案落地页](https://www.seeedstudio.com/solutions/reference-designs/edge_inspection_surface?utm_source=sensecraft_agent&utm_medium=solution_consult&utm_campaign=edge_inspection_surface)；模型部署与 TensorRT 推理管线见 [GitHub 仓库](https://github.com/suharvest/sensecraft-solutions/tree/main/solutions/edge_inspection_surface)。*
+>
+> ---
+> **为了确定相机快门、打光方案与工控机选型，我先跟您确认三个关键细节：**
+> 1. **生产节拍与速度**：流水线每分钟过检多少件产品？工件经过工位时是短暂静止停顿拍照，还是在传送带上高速连续运动？（*运动中飞拍必须选用工业全局快门相机以避免拖影*）
+> 2. **工件材质与反光**：工件表面是什么材质（例如反光金属、高光塑料还是吸光纸盒）？想要检出的最小划痕/缺陷尺寸大概是多少毫米？（*反光工件需要配合特定偏光或同轴光源，否则会产生强烈眩光影响检测*）
+> 3. **下位机联动**：判定出 NG 不良品后，边缘机是只需声光报警/屏幕标记，还是需要直接向现场 PLC 发送数字量 IO 信号联动气缸剔除？
 
 ---
 
-## 3. 防幻觉与守则
+## 5. 防幻觉与守则
 
 1. **禁止编造方案**：如果 `solution-cli hub search` 返回为空，诚实告知用户官方方案库暂无现成参考设计，并基于通用 Jetson / 树莓派 Docker 能力提供定制建议。
-2. **严禁在咨询期直接执行部署**：用户此时通常未采购或未连接硬件。应引导用户进入下一步【硬件选型与配件推荐】（查阅 `references/hardware-bom.md`）。
+2. **严禁在咨询期直接执行部署**：用户此时通常未采购或未连接硬件。应引导用户确认现场工况并进入【硬件选型与配件推荐】（查阅 `references/hardware-bom.md`）。

package/skills/sensecraft/references/device-management.md

@@ -0,0 +1,126 @@
+# 设备管理与运行时参数热配手册 (Device Management & Reconfiguration Guide)
+
+> **定位**：供 AI Agent 在用户处于 **设备管理（MANAGE）** 或 **参数热配（RECONFIG）** 阶段查阅。
+> 当用户询问“改一下 MQTT 地址”、“修改运行参数”、“查看已安装应用”、“重启服务”、“停止某个方案”时加载本手册。
+
+---
+
+## 1. 参数可修改性的分层边界
+
+在修改方案配置前，Agent 必须明确参数所属的层级，切勿越界操作：
+
+| 层级 | 参数类别 | 判断依据 | 处理方式 |
+|---|---|---|---|
+| **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`）。 |
+
+---
+
+## 2. L1 声明式热配标准操作流
+
+当设备已经部署运行，用户希望修改 L1 参数（如更改 MQTT 目标服务器）时：
+
+### 步骤一：获取运行时信息与当前部署列表
+读取运行环境指针并校验服务健康（桌面端每次启动分配随机端口并写入 `~/.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 "$BASE_URL/api/device-management/active"
+```
+- 输出包含 `solution_id`、`device_id`、`status`（running/stopped）、`deployed_at` 及运行 URL。
+
+### 步骤二：读取可配参数及当前值（Get Config）
+```bash
+# 本地 Docker 部署实例
+curl -s "$BASE_URL/api/docker-devices/local/config/<solution_id>"
+
+# 远程设备实例（通过 SSH 提取运行态值）
+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`，如 `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 部署实例更新（使用从 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": "192.168.1.200",
+      "mqtt_port": 1883
+    }
+  }'
+
+# 远程设备实例更新
+curl -s -X PUT "$BASE_URL/api/docker-devices/config/<solution_id>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "values": { "mqtt_broker": "192.168.1.200" },
+    "connection": { "host": "<ip>", "username": "<user>", "password": "<pwd>" }
+  }'
+```
+- **后端自动执行**：根据 `field.id` 执行模板替换 ➔ 生成新的 env ➔ `docker compose up -d` 重新创建受影响容器 ➔ 更新部署 manifest 记录。
+- **无需整机重装**，数据卷与现有文件完全保留。
+
+---
+
+## 3. 运行态实例的生命周期管理
+
+当用户要求“重启服务”、“暂停运行”或“更新容器镜像”时：
+
+### 本地 Docker 部署实例（无凭据要求）
+```bash
+# 执行 start / stop / restart / update
+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 请求前必须准备好认证凭据。
+
+---
+
+## 4. 自然交互与应答守则
+
+1. **先查后改**：绝不要盲目猜测当前配置。先调用接口读取 `current_value`，并明确告知用户：“*当前配置的 MQTT 地址是 127.0.0.1，我将为您更新为 192.168.1.200*”。
+2. **越界平滑引导**：如果用户要改的参数不在 `reconfigurable` 列表中：
+   - 坦诚解释：“*该参数属于底层容器编排配置（或写在源码中），无法直接在线热改。但我可以帮您修改本地编排文件重新生效，或者获取源码进行深度定制*”。

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/hardware-bom.md

@@ -19,14 +19,14 @@
 ```bash
 solution-cli product query <family_id> --json
 ```
-- 获取产品族名称、官方默认主 SKU、物理电气规格（电压、电流接口、M.2 槽位等）。
+- 获取产品族名称、官方默认主 SKU、物理电气规格（电压、电流接口、M.2 槽位等）以及内置的 UTM 商城购买直达链接。
 
 ### 动作二：查询经过验证的配件清单
 ```bash
 solution-cli product accessories <family_id> --json
 ```
 - 输出严格由确定性代码计算物理兼容性的配件清单：
-  - `REQUIRED` 列表：带必买原因（`reason`）、购买 SKU 与直达链接；
+  - `REQUIRED` 列表：带必买技术原因（`reason`）、购买 SKU 与静默带 UTM 的直达链接；
   - `OPTIONAL` 列表：带周边传感器、通信模块、固态硬盘与购买链接。
 
 ### 动作三：验证物理配件兼容性
@@ -39,10 +39,10 @@ solution-cli product verify-compatibility --host <family_id> --accessory "<用
 
 ## 3. 六大物理兼容性硬红线（严禁大模型自行脑补）
 
-Agent 严禁凭“常识”告知配件通用，必须遵循 CLI 评估结果：
+Agent 严禁凭“常识”告知配件通用，必须遵循 CLI 评估结果并向用户讲透技术原因：
 
 1. **供电 (Power Supply)**：
-   - `recomputer_j40` / `j30` 必须满足 **19V 4.74A (90W)**，DC Jack 规格为 **5.5x2.5mm**（与普通 5.5x2.1mm 路由器插头不兼容）；
+   - `recomputer_j40` / `j30` 必须满足 **19V 4.74A (90W)**，DC Jack 规格为 **5.5x2.5mm**（与普通 5.5x2.1mm 路由器插头不兼容，插不进或接触不良）；
    - USB-C 供电的设备（如 `recamera_2002`、`sensecap_watcher`），必须核对 PD 协议档位与最低电流。
 2. **射频与天线 (RF Antenna)**：
    - 必须严格区分 **N 型（N-Type）** 与 **SMA**；
@@ -57,27 +57,27 @@ Agent 严禁凭“常识”告知配件通用，必须遵循 CLI 评估结果：
 
 ---
 
-## 4. 推荐呈现模板
+## 4. 推荐呈现模板（自然专业风格）
 
-向用户输出采购清单时，必须使用如下清晰结构：
+向用户输出采购清单时，Agent 先讲清技术理由，链接自然附在 SKU 之后（自带 UTM 归因），不喧宾夺主：
 
 ```markdown
 ### 🛒 硬件采购清单建议（BOM）
 
 #### 1. 主计算单元
 - **产品型号**：reComputer J4012（NVIDIA Jetson Orin NX 16GB）
-- **推荐 SKU**：`110110145`
-- **购买链接**：[Seeed 官方商城直达](https://www.seeedstudio.com/...)
+- **推荐 SKU**：`110110145` [Seeed 官方商城直达](https://www.seeedstudio.com/reComputer-J4012-p-5586.html?utm_source=sensecraft_agent&utm_medium=bom_recommendation&utm_campaign=recomputer_j40&utm_content=host_sku_110110145)
 
-#### 2. 必需配件 (REQUIRED - 缺少无法开机)
-- ⚠️ **19V 4.74A 电源适配器** (SKU: `313080684`)
-  - 原因：本主机出厂不配电源适配器，必须单独采购 5.5x2.5mm 19V 适配器。
-  - 购买链接：[购买电源](https://www.seeedstudio.com/...)
-- ⚠️ **国标/美标 AC 三脚电源线** (SKU: `106990470`)
+#### 2. 必需配件 (REQUIRED - 缺少系统无法物理通电开机)
+- ⚠️ **19V 4.74A 电源适配器 (5.5x2.5mm)** (SKU: `313080684`)
+  - 技术原因：本工控主机出厂裸机不带电源适配器，且接口为 5.5x2.5mm 大功率圆口，必须专门选配。
+  - [购买电源适配器](https://www.seeedstudio.com/...utm_params...)
+- ⚠️ **国标/美标 AC 三脚电源输入线** (SKU: `106990470`)
 
 #### 3. 推荐选配 (OPTIONAL - 按需选购)
-- **M.2 NVMe SSD 256GB** (SKU: `112990246`)：用于部署 Docker 容器及缓存模型权重。
-- **reSpeaker 4 麦克风阵列** (SKU: `107990193`)：若需额外实现语音呼救感知功能。
+- **M.2 NVMe SSD 256GB** (SKU: `112990246`)：用于拉取 Docker 镜像与长期本地数据持久化。
+- **reSpeaker 4 麦克风阵列** (SKU: `107990193`)：若需补充语音呼叫或声音事件感知。
 
-> 收到设备并连接网线/电源后，只需对我说“设备已连接，开始部署”，我将直接为您自动化部署落地！
+---
+> 📦 硬件采购并收到后，只要通电并插上网线，随时对我说“设备已连接，开始部署”，我将直接为您全自动化完成环境配置与方案运行！
 ```

package/skills/sensecraft/references/secondary-development.md

@@ -0,0 +1,84 @@
+# 深度定制与源码二次开发手册 (Secondary Development & Source Customization Guide)
+
+> **定位**：供 AI Agent 在用户处于 **深度定制（CUSTOMIZE）** 或 **源码二次开发（SECONDARY_DEV）** 阶段查阅。
+> 当用户提出“我想改源码”、“替换成我自研的 YOLO 模型”、“前端页面想重新定制”、“GitHub 代码在哪里”、“克隆到本地开发”时加载本手册。
+
+---
+
+## 1. 方案开源代码的双层架构体系
+
+Seeed SenseCraft 方案体系在 GitHub 上采用清晰的双层开源结构：
+
+```mermaid
+graph LR
+    subgraph Repo1["1. 方案编排层 (Solution Package)"]
+        direction TB
+        R1_URL["github.com/Seeed-Studio/sensecraft-solutions"]
+        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_Content["包含 Python 推理主循环、Vue/React 前端看板、模型权重、后处理时序"]
+        R2_Fit["适合：重训模型、改检测类别与阈值、重构业务 UI、对接私有云数据库"]
+    end
+```
+
+---
+
+## 2. 源码检索与克隆指引 (Source Discovery & Clone)
+
+### 动作一：获取方案官方仓库地址
+使用 CLI 查询方案元数据：
+```bash
+solution-cli hub search "<方案名称或关键词>" --json
+```
+- 输出中的 `repo_url` 提供了官方代码仓地址（例如 `https://github.com/Seeed-Studio/sensecraft-solutions/tree/main/solutions/fall_detection` 或核心项目地址）。
+
+### 步骤二：克隆方案到本地工程目录
+指导用户或在本地工作空间执行克隆：
+```bash
+# 方案编排包开发
+git clone https://github.com/Seeed-Studio/sensecraft-solutions.git ./my-solutions
+
+# 或核心算法项目开发（以视觉推理为例）
+git clone https://github.com/Seeed-Studio/ModelAssistant.git ./my-model-assistant
+```
+
+---
+
+## 3. Agent 协同开发与本地联调闭环 (Dev Loop)
+
+克隆到本地工程后，Agent 可以作为用户的协同编程伙伴（Pair Programmer）深入代码：
+
+### 阶段 1：代码与模型定制（Agent Coding）
+- **模型替换**：
+  - 用户训练好的私有权重（如 `custom_yolo11.onnx`），通过对应板卡工具链编译为目标格式（RKNN 板卡生成 `.rknn`，Jetson 生成 `.engine`，Hailo-8 生成 `.hef`）；
+  - 将模型文件放入方案对应目录或通过卷挂载映射到容器内。
+- **业务逻辑与看板调整**：
+  - 修改检测状态机阈值、报警触发条件、Webhook 发送格式；
+  - 修改 Web 监控界面组件。
+
+### 阶段 2：引擎本地热加载联调（Local Engine Dev Loop）
+修改完成后，无需打包推送到 CDN，直接利用 `sensecraft-engine` 的 `--solutions-dir` 特性在本地无缝验证：
+
+```bash
+# 从本地自定义工程目录加载方案并执行部署测试
+sensecraft-engine deploy <id> --solutions-dir ./my-solutions/solutions
+```
+- 引擎将直接读取本地工程中的 `solution.yaml`、`devices/*.yaml` 和 `docker-compose.yml`，秒级完成本地部署生效。
+
+### 阶段 3：代码固化与共享
+- 本地验证通过后，指导用户：
+  - 提交并推送到用户自己的私有 GitHub 仓库长期维护；
+  - 若为通用改进，欢迎向官方开源仓库提起 Pull Request。
+
+---
+
+## 4. 自然交互与应答守则
+
+1. **主动提供溯源**：当用户明确表达“想要改底层逻辑”、“换自研模型”时，主动告诉用户代码所在，并给出克隆建议。
+2. **语气自然诚恳**：
+   - 示例：“*这套方案的源码完全开源在 [GitHub 仓库](https://github.com/suharvest/sensecraft-solutions/tree/main/solutions/<id>)。您可以克隆到本地，告诉我您具体想改哪部分（比如替换成自研的 Pose 模型或改告警通知格式），我可以直接帮您修改代码并用引擎本地联调。*”