@seeed-studio/solution-cli 0.4.4 → 0.4.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seeed-studio/solution-cli",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "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",
@@ -17,12 +17,14 @@
     "catalog",
     "skills",
     "docs",
+    "CHANGELOG.md",
     "README.md"
   ],
   "scripts": {
     "build": "node scripts/bake-client-config.mjs",
     "prepack": "node scripts/bake-client-config.mjs",
-    "test": "node --test",
+    "test": "node --test --test-concurrency=1",
+    "benchmark": "node scripts/benchmark.mjs",
     "install:self": "node bin/cli.js install",
     "status": "node bin/cli.js status",
     "doctor": "node bin/cli.js doctor"

package/skills/solution-cli/SKILL.md

@@ -28,6 +28,7 @@ solution-cli hub get <id> --locale <en|zh|ja> --section architecture --json
 solution-cli hub get <id> --locale <en|zh|ja> --section products --json
 solution-cli hub get <id> --locale <en|zh|ja> --section playbook --json
 solution-cli hub get <id> --locale <en|zh|ja> --section integration --json
+solution-cli hub get <id> --locale <en|zh|ja> --section cases --json
 solution-cli hub get <id> --locale <en|zh|ja> --section deployment [--preset <id>] --json
 ```
 
@@ -83,8 +84,8 @@ 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`, then `hub get <id> --sections architecture,playbook --json` | **DO NOT run deploy**; search exposes `available_sections` and evidence status (`documented`/`generic`/`inferred`). 若返回 warning 提示包含硬件关键词，立即按提示切换至 `product search`。 |
 | **PROCUREMENT / VERIFY_BOM**<br>“买什么硬件？”、“J4012 需要配什么配件？”、“推荐镜头/天线” | `references/hardware-bom.md` | `solution-cli product accessories <id> [--category <power,camera>] --compact --json` | **DO NOT fabricate** third-party SKUs or prices. Always distinguish REQUIRED vs OPTIONAL accessories. Use `--compact` and `--category` to save tokens. |
 | **ONBOARDING / PRECHECK**<br>“设备到了，插上了网线/USB”、“环境自检”、“发现新设备” | `references/diagnose.md` & `references/device-management.md#0` | `solution-cli doctor` / `sensecraft-engine device scan` | **Early & Proactive**: Check device firmware & drivers early. Intercept and prompt for reCamera firmware/patch or SBC env fixes before deploy. |
-| **DEPLOYING / APPLY**<br>“开始安装”、“部署 fall_detection” | `references/deploy.md` | `solution-cli hub get <id> --section deployment --preset <id> --json` then `sensecraft-engine deploy <id>` | **DEPLOYMENT CRITICAL SECTION**: Zero external commercial queries allowed during apply. Filter guide with `--preset` to reduce token bloat. |
-| **INTEGRATION / INGESTION**<br>“怎么接到我们系统”、“MQTT主题是什么”、“Webhook格式”、“接入 Home Assistant” | `references/device-management.md#5` | `solution-cli hub get <id> --section integration --json` | **System Ingestion**: Provide exact MQTT topics, payload schemas, Webhook endpoints, and port mappings directly from verified integration contract. Batch with `--sections architecture,integration` if needed. |
+| **DEPLOYING / APPLY**<br>“开始安装”、“部署 fall_detection” | `references/deploy.md` | `solution-cli hub get <id> --section deployment --preset <id> --json` then `sensecraft-engine deploy <id> -i STEP.KEY=VAL` | **DEPLOYMENT CRITICAL SECTION**: Zero external commercial queries allowed during apply. Filter guide with `--preset` to reduce token bloat. Use `--input` / `--inputs-file` for parameters, `--replace-existing` to update containers. |
+| **INTEGRATION / INGESTION**<br>“怎么接到我们系统”、“MQTT主题是什么”、“Webhook格式”、“接入 Home Assistant”、“有哪些接口/怎么读数据” | `references/device-management.md#7` | `sensecraft-engine schema <id> --json` or `solution-cli hub get <id> --section integration --json` | **System Ingestion**: Inspect input schema and output data interfaces directly via `sensecraft-engine schema <id>`. Provide exact MQTT topics, payload schemas, Webhook endpoints, and port mappings directly from verified contract. |
 | **MANAGE / RECONFIG**<br>“改一下 MQTT 地址”、“换模型/业务流”、“重启服务”、“修改配置”、“打本地补丁”、“换应用镜像” | `references/device-management.md` | `curl BASE/api/docker-devices/local/config/<id>` / `solution-cli doctor` | **On-Demand (JIT)**: Only query when user requests application-layer modifications. Apply tiered hotpatches without touching underlying OS. |
 | **FEASIBILITY / SALES_EVAL**<br>“我们能不能做这个？”、“非标需求评估”、“需求匹配度如何”、“做这个要多久” | `references/sales-feasibility.md` | `solution-cli hub search "<keyword>" --json` / `product query <family>` | **DO NOT make blind promises**. Strictly follow the 4-tier feasibility matrix and scoring criteria. |
 | **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`. |
@@ -103,8 +104,18 @@ To retrieve single sections:
 - `products`: bill of materials (BOM), required vs optional hardware
 - `deployment`: deployment steps (use `--preset <id>` to filter and reduce token usage)
 - `playbook`: field diagnostic questions and engineering rationales
+- `cases`: customer case studies, deployed hardware list, region, and verified outcomes
 - `integration`: system ingestion contracts (MQTT topics, Webhooks, REST endpoints)
 
+### Case Deep Dive & Product Pruning
+When drilling down into specific case studies or hardware models:
+- **Case Full Story**: Use `solution-cli case get <id_or_slug> [--locale zh|en|ja] [--json]` to retrieve complete Markdown body (`body_md`), deployment field background, and customer metrics.
+- **Product Progressive Pruning**: When querying hardware with `product search` or `product query`, use `--section <overview|power|interfaces|specs|all>` to prune verbose JSON trees and save context tokens:
+  - `--section power`: only returns `package_profile`, `power`, `required_accessories`, and `package_contents` (ideal for power adapter and box contents audits).
+  - `--section interfaces`: only returns board interfaces, protocols, and I/O expansion ports.
+  - `--section overview`: lightweight overview of family and model names.
+  - `--section specs`: detailed hardware specifications and AI TOPS.
+
 Capabilities that need the **SenseCraft Solution desktop app** (editing a
 solution's configuration, the app's `/api/ai/context`, diagnosing through the
 app's logs) are in `references/app-only.md`. Use them only when the user has

package/skills/solution-cli/references/consult-and-select.md

@@ -33,6 +33,7 @@ solution-cli hub get <chosen-id> --locale <en|zh|ja> --section links --json
 ```
 - **咨询顺序**：先用用户原话和同义技术词查询，再对选中的 Scenario、Tech 或 RD 调用 `hub get`；只有需要回答架构、产品或部署问题时，才追加 `--section architecture|products|deployment`。根据返回的 `diagnostic_playbook` 拆解需求；向用户确认点位、协议、供电、通信、控制闭环和预算等关键参数后，给出可提供的方案、硬件方向和缺口说明。
 - **内容核验**：链接或 metadata 只用于定位，不代表已经阅读内容。用户问方案能力、架构或产品时，必须读取选中记录对应的 `description`、`architecture` 或 `products` section；确切生产页或架构图影响答案时，再打开 CLI 返回的确切 URL/图片并说明核验范围。相对资源路径只有在签名本地内容实际存在时才可读取，否则标为 source asset 未就绪。
+- **案例赋能与真实背书**：在向客户介绍或推荐选定的业务场景（Scenario）时，调用 `solution-cli hub get <scenario-id> --section cases --json`，读取并向客户展示官方真实落地案例（包含客户实践、具体采用的硬件、落地地区与成效），增强方案说服力与工程可信度。
 - **交付边界**：咨询阶段只做检索、需求澄清和方案建议，不自动执行 `deploy`；用户确认硬件和部署目标后，再转入硬件校验或部署流程。
 - **输出结果说明**：
   - `Scenario`：业务场景、痛点、所属 Tech/RD 关系、生产落地页链接；
@@ -157,6 +158,24 @@ sensecraft-engine deploy-info <solution-id> --lang <en|zh>
 > ---
 > **为了确定相机快门、打光方案与工控机选型，我先跟您确认三个关键细节：**
 > 1. **生产节拍与速度**：流水线每分钟过检多少件产品？工件经过工位时是短暂静止停顿拍照，还是在传送带上高速连续运动？（*运动中飞拍必须选用工业全局快门相机以避免拖影*）
+
+---
+
+## 5. 成功案例下钻与渐进式披露规范 (Case Deep-Dive & Progressive Disclosure)
+
+1. **场景关联成功案例**：
+   通过 `solution-cli hub get <id> --section cases --json` 获取落地案例列表（包含标题、摘要、使用硬件、区域和真实落地链接）。
+2. **单篇案例正文下钻**：
+   当客户希望深入了解某一具体落地案例的实施背景、挑战、合作伙伴与成效时，执行：
+   `solution-cli case get <id_or_slug> [--locale zh|en|ja] [--json]`
+   直接读取完整 Markdown 正文（`body_md`）与硬件组合。
+3. **硬件选型渐进式裁剪**：
+   在产品搜索与选型时，为避免长 JSON 造成上下文膨胀，根据分析维度执行字段裁剪：
+   `solution-cli product search <model> --section <overview|power|interfaces|specs>`
+   - 核验电源/开箱/必需配件：`--section power`
+   - 核验板载接口/总线/扩展槽：`--section interfaces`
+   - 快速型号一览与开箱判定：`--section overview`
+   - 详细硬件参数与算力规格：`--section specs`
 > 2. **工件材质与反光**：工件表面是什么材质（例如反光金属、高光塑料还是吸光纸盒）？想要检出的最小划痕/缺陷尺寸大概是多少毫米？（*反光工件需要配合特定偏光或同轴光源，否则会产生强烈眩光影响检测*）
 > 3. **下位机联动**：判定出 NG 不良品后，边缘机是只需声光报警/屏幕标记，还是需要直接向现场 PLC 发送数字量 IO 信号联动气缸剔除？
 

package/skills/solution-cli/references/deploy.md

@@ -17,16 +17,24 @@ solution. Then use the Engine's local list and `deploy-info` to confirm that
 the mapped `solution_id` and presets are actually installed. If several RDs
 fit, explain the difference and ask which one to use.
 
-## 2. Read what the deployment needs
+## 2. Read what the deployment needs & schema
 
 ```bash
+# 1. Inspect standard Draft-07 JSON Schema and external output data interfaces:
+sensecraft-engine schema <id> --json
+
+# 2. Or inspect deployment steps, hardware presets, and required parameters:
 sensecraft-engine deploy-info <id> --lang zh
 sensecraft-engine doctor --json
 sensecraft-engine device ports
 sensecraft-engine device scan --timeout 5
 ```
 
-Read `presets[]`, `steps[]`, `device_connections`, `selected_devices`, and `request_template` from `deploy-info`. A preset with more than one variant requires the user's choice. Fill every `<REQUIRED: ...>` value from the user or a read-only device check; never invent device IDs, connection keys, SSH credentials, serial ports, or Docker targets.
+The `schema` command returns:
+- `inputs`: Standard Draft-07 JSON Schema defining all accepted and required parameters per step, including target conditional requirements and parameter type definitions.
+- `output_interfaces`: Data ingestion specifications (MQTT topics, REST endpoints, TCP streams, and payload schemas) provided by the solution.
+
+Read `presets[]`, `steps[]`, `device_connections`, `selected_devices`, and `request_template` from `deploy-info` or `schema`. A preset with more than one variant requires the user's choice. Fill every `<REQUIRED: ...>` value from the user or a read-only device check; never invent device IDs, connection keys, SSH credentials, serial ports, or Docker targets.
 
 For a `docker_deploy` step, use the target listed by `deploy-info` and copy its `type` into `target_type` (`local` or `remote`). Linux local and remote targets may declare `auto_install_docker`; the engine can install Docker/Compose when that option is enabled, but offline installation requires matching packages to be obtainable and usable permissions to already exist. Windows native local Docker is unsupported; use a Linux Docker host over SSH. macOS local Docker requires the user to install and start Docker Desktop first. The CLI does not install Docker Desktop or silently obtain `sudo`.
 
@@ -43,6 +51,40 @@ For a `docker_deploy` step, use the target listed by `deploy-info` and copy its
 >   输入密码的交互在用户独立本地终端完成，密码绝不流经大模型上下文，亦不留在会话与历史中。
 > - **部署参数统一使用 `key_file`**：SenseCraft Engine 的部署请求格式要求远程目标通过 `key_file` 进行连接。严禁在聊天框索取明文密码。
 
+### Method A: Direct Input Flags / Inputs File (Recommended for Agents)
+
+Use `--input` (`-i`) to specify parameters directly without writing temporary files:
+
+```bash
+# Direct step-scoped parameters:
+sensecraft-engine deploy <id> \
+  -i <step_id>.host=192.168.1.50 \
+  -i <step_id>.username=root \
+  -i <step_id>.key_file=~/.ssh/id_ed25519 \
+  --replace-existing \
+  --yes
+```
+
+Or pass a YAML/JSON configuration file via `--inputs-file`:
+
+```bash
+sensecraft-engine deploy <id> --inputs-file ./inputs.yaml --replace-existing --yes
+```
+
+Where `inputs.yaml` has step-scoped values:
+```yaml
+<step_id>:
+  target: remote
+  host: 192.168.1.50
+  username: root
+  key_file: ~/.ssh/id_ed25519
+```
+
+> [!TIP]
+> **Updating Existing Deployments**: When modifying parameters of an already deployed solution, `--replace-existing` automatically stops and replaces conflicting containers with the updated parameters and restarts them.
+
+### Method B: Full Request Document (Legacy `--params`)
+
 Write the completed request to `./.sensecraft-work/body.json`, keeping credentials out of the command line:
 
 ```json
@@ -67,6 +109,10 @@ Remote SSH uses a regular key under `~/.ssh` or the Engine data directory (`id_e
 Before a remote deployment, run the no-change validation:
 
 ```bash
+# Validate direct input parameters:
+sensecraft-engine validate <id> -i <step_id>.host=192.168.1.50 -i <step_id>.key_file=~/.ssh/id_ed25519
+
+# Or validate request body:
 sensecraft-engine validate --params ./.sensecraft-work/body.json
 ```
 

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

@@ -323,3 +323,25 @@ curl -s -X PUT "$BASE_URL/api/docker-devices/local/config/<solution_id>" \
    若发现硬件列表多出了未经绑定的设备，Agent **必须主动发起提醒并给出跟进方案**：
    > *“💡 硬件变动提醒：检测到主机新插入了设备 `/dev/ttyUSB1`（USB 串口外设）。当前运行中的方案未绑定该端口。*
    > *如果您希望接入该硬件，请告诉我，我可以帮您在配置文件中追加串口映射并重新加载服务生效！”*
+
+---
+
+## 9. 数据接口自省与系统接入 (Data Ingestion & Interface Discovery)
+
+当用户询问“这个应用有哪些接口”、“怎么把数据接入我们系统/数据库”、“MQTT Topic 是什么”、“怎么读取数据”时，使用 `schema` 命令直接自省方案的输入与输出数据规格：
+
+```bash
+# 1. 查询方案所有外部数据输出接口 (MQTT, HTTP/REST, WebSocket, TCP):
+sensecraft-engine schema <solution_id> --outputs
+
+# 2. 查询完整规范 (包含 Draft-07 Inputs JSON Schema 与 Output Interfaces):
+sensecraft-engine schema <solution_id> --json
+
+# 3. 传入实际部署连接信息，自动解析占位符 (例如 host 与端口):
+sensecraft-engine schema <solution_id> --outputs --connection '{"<step_id>": {"host": "192.168.1.50"}}'
+```
+
+### 接入指引与协议对应
+- **MQTT 数据流**：输出中会给出确切的 `topic` 与 `payload_schema`，引导用户在其业务系统/Node-RED/EMQX 中订阅该 Topic 并按 Schema 解析；
+- **HTTP / REST API**：输出中包含 `endpoint`（如 `/api/v1/events`）、`method` 与请求/响应 Schema，便于用户编写 Webhook 或下游微服务对接；
+- **TCP / 原始套接字 / 音视频流**：输出中包含专用监听端口 `port` 与流格式说明（如 Wyoming 语音协议端口 10200/10300，RTSP 视频流端口 8554）。