@seeed-studio/solution-cli 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+本文件记录 `@seeed-studio/solution-cli` 的所有重要更新与版本演进。
+
+---
+
+## [0.4.5] - 2026-10-19
+
+### 新增功能 (Added)
+- **方案数据接口与参数自省 (`schema`)**：
+  - 新增 `schema` 命令，支持一键查询应用对外提供的数据接口（MQTT Topic、REST API 端点、TCP 语音/流媒体端口及数据格式），方便快速接入自有系统或数据库。
+  - 支持直接导出部署参数的标准 Draft-07 JSON Schema，包含默认值和条件依赖。
+- **命令行直接传参部署 (`--input` / `--inputs-file`)**：
+  - 支持在部署时通过 `-i 参数名=值`（或 `-i 步骤.参数名=值`）直接传递参数，无需再手写多层 JSON 文件。
+  - 支持通过 `--inputs-file` 读取 YAML/JSON 配置文件批量传参。
+- **已部署应用自动更新 (`--replace-existing`)**：
+  - 修改参数重新部署时，自动停止并替换已有冲突容器，快速应用新配置并重启服务。
+
+### 体验与文档优化 (Documentation)
+- **Agent Skill 技能升级**：同步更新内置 AI 助手技能（支持 Claude Code, Codex, 豆包等），增加数据接入自省与无头入参推荐范式。
+
+---
+
+## [0.4.4] - 2026-10-15
+
+### 问题修复 (Fixed)
+- 修复 Windows 与 macOS 环境下软链接创建异常，完善跨平台目录同步回退。
+- 修复豆包工作（Doubao Work）技能路径协同问题。
+
+### 体验与文档优化 (Documentation)
+- 补充各支持 Agent 的 CLI 指令集与硬件排错踩坑库（gotchas）参考。
+
+---
+
+## [0.4.3] - 2026-10-14
+
+### 问题修复 (Fixed)
+- 修复 Agent 环境识别中的路径加载与语法异常。
+
+---
+
+## [0.4.2] - 2026-10-14
+
+### 体验与优化 (Improved)
+- 规范并增强豆包工作（Doubao Work）技能的本地扫描发现路径。
+
+---
+
+## [0.4.1] - 2026-10-13
+
+### 体验与优化 (Improved)
+- 增强硬件与配件匹配规则：优化电源线、电池及多国适配插头的识别过滤，准确识别开箱即用状态。
+
+---
+
+## [0.4.0] - 2026-10-13
+
+### 新增功能 (Added)
+- **硬件开箱即用与包装清单查询**：支持精准查询硬件是否随附电源、盒内清单、外设接口与支持的落地场景。
+- **Hermes Agent 支持**：新增对 Hermes Agent 的环境检测与技能自动安装支持。
+- **Agent 架构解耦**：将豆包工作与 WorkBuddy 解耦为独立配置管理。

package/README.md

@@ -9,7 +9,7 @@ Install the signed Rust deployment engine and the `solution-cli` AI Agent Skill
 
 | 目标 AI 宿主 | 专属安装命令（直接复制发给 AI 或在终端运行） | 技能挂载路径 |
 |---|---|---|
-| **豆包工作 (Doubao Work)** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent doubao` | `~/Doubao/skills` (及 `~/.agents/skills`) |
+| **豆包工作 (Doubao Work)** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent doubao` | `~/Doubao/skills` (Windows: `%USERPROFILE%\Doubao\skills`；及 `~/.agents/skills`) |
 | **Claude Code** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent claude` | `~/.claude/skills` |
 | **OpenAI Codex** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent codex` | `~/.agents/skills` 或 `~/.codex/skills` |
 | **Google Antigravity** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent antigravity` | `~/.gemini/config/skills` |
@@ -103,6 +103,9 @@ npx -y @seeed-studio/solution-cli product query recomputer_j40 --json
 | Command | Purpose |
 |---|---|
 | `solution-cli install --agent <agent-id> -y` | Install or update the signed Engine and Skill |
+| `solution-cli update` | Check for Engine/content updates and sync installed AI Agent skills |
+| `solution-cli agent list [--json]` | List supported AI agent hosts and their skill directories |
+| `solution-cli gotchas [keyword] [--chip <chip>]` | Query edge hardware, chip troubleshooting & caveats |
 | `solution-cli hub search "<query>" --json` | Find solution scenarios and reference designs |
 | `solution-cli product query <family-id> --json` | Read hardware family specifications |
 | `solution-cli product accessories <family-id> --json` | Check required and compatible accessories |

package/docs/cli-guide.md

@@ -34,7 +34,7 @@ Agent 的默认工作流是“先咨询，再选型，再检查，最后在用
 
 | 目标 AI 宿主平台 | 专属安装命令（直接复制发给 AI 或在终端运行） | 技能默认配置路径 |
 |---|---|---|
-| **豆包工作 (Doubao Work)** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent doubao` | `~/Doubao/skills` (及 `~/.agents/skills`) |
+| **豆包工作 (Doubao Work)** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent doubao` | `~/Doubao/skills` (Windows: `%USERPROFILE%\Doubao\skills`；及 `~/.agents/skills`) |
 | **Claude Code** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent claude` | `~/.claude/skills` |
 | **OpenAI Codex** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent codex` | `~/.agents/skills` 或 `~/.codex/skills` |
 | **Google Antigravity** | `npm install -g @seeed-studio/solution-cli && solution-cli install --agent antigravity` | `~/.gemini/config/skills` |
@@ -255,14 +255,26 @@ solution-cli status
 
 查看 Engine 路径、版本、内容缓存和 Skill 挂载状态。
 
-### 3. 网络与源排查
+### 3. 日常更新同步（solution-cli update）
+
+当官方发布了新的硬件知识库、避坑指南或部署契约更新时，运行以下命令即可增量同步所有已配置的 Agent 技能与本地 Engine：
+
+```bash
+solution-cli update
+```
+
+该命令会自动：
+1. 检查并拉取最新稳定的 `sensecraft-engine` 核心二进制与云端方案目录。
+2. 扫描已安装的全部 AI 宿主（如豆包、Claude、Codex 等），安全增量同步最新的 Skill 文件（保留用户的自定义修改）。
+
+### 4. 网络与源排查
 
 若遇到 npm 下载或同步延迟，可在命令中显式指定官方源：
 ```bash
 npx -y --registry=https://registry.npmjs.org/ @seeed-studio/solution-cli install -y
 ```
 
-### 4. 干净卸载
+### 5. 干净卸载
 
 只卸载指定宿主，并先备份需要保留的用户修改：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seeed-studio/solution-cli",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "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,6 +17,7 @@
     "catalog",
     "skills",
     "docs",
+    "CHANGELOG.md",
     "README.md"
   ],
   "scripts": {

package/skills/solution-cli/SKILL.md

@@ -83,8 +83,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`. |

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