solution-cli

solution-cli — 用 solutionctl 在命令行驱动引擎

solutionctl 是 packages/solutionctl/ 里的瘦客户端：它自己不含任何引擎代码，只负责定位 引擎二进制（provisioning-station）并通过子进程调用它。AI agent 加载本 skill 后，无需知道二进制 路径，就能在终端发现方案、部署、离线校验、查已部署 app。

何时用

• headless / CI / 脚本化部署：GitHub Actions、批量给多台设备部署、跑完即退。
• 没有桌面 App GUI 的环境（纯命令行机器、远程 SSH）。
• 想离线校验一个方案目录是否符合 spec 契约（这一项不需要引擎，见下）。

不适用：内容编辑（改文案 → 用桌面 App 的编辑模式）、引擎/插件开发（在闭源引擎仓库）。

前提

• 已安装 SenseCraft Solution App，或本机有 provisioning-station 引擎二进制。 solutionctl 按三级顺序自动定位，agent 不用关心路径：
  1. 环境变量 $SENSECRAFT_ENGINE_BIN
  2. ~/.sensecraft/engine.json 握手文件（App 首次启动写入）
  3. 平台原生查找（macOS mdfind / Windows 注册表 / Linux dpkg）
• 定位失败时 solutionctl 会给出清晰提示（装 App，或 export SENSECRAFT_ENGINE_BIN=<引擎绝对路径>）。
• 例外：solutionctl validate 是纯离线的，不需要引擎二进制。

命令速查

从仓库 clone 内跑命令即可，solutionctl 会自动把 PS_SOLUTIONS_DIR 指向这个 clone 的 solutions/（cwd 在 repo 根下任意位置都行），无需 --solutions-dir；同时 best-effort 把 PS_DEVICES_DIR 指向已装桌面 App 的 devices/ 目录（含 device_class 的方案需要）。 命令行不用加 uv run 前缀的话直接 solutionctl；在 clone 里用 uv run --package sensecraft-solutionctl solutionctl <...>。

# 看引擎能力 / 契约元数据（版本、支持的 deployer 类型等）
solutionctl meta

# 发现方案：列出所有方案 ID
solutionctl solution list

部署三步法（deploy-info → 填 → deploy）

别凭空猜 preset 名，也别啃 solution show 的原始 JSON。 走 deploy-info：

# 1. 看这个方案怎么部署：有哪些 preset、每步要填什么、local/remote 怎么选
solutionctl deploy-info <solution_id> [--preset <p>] [--lang en|zh]
#   → JSON 输出：
#     presets            : 每个 preset 的 id + name（按用户意图选一个，再 --preset 收窄）
#     steps              : 每步的 device_id / type / 必填参数；
#                          has_targets=true 的步骤（如 docker_deploy）提供 local vs remote 两种 target
#                            local  = 部署到本机 Docker（免 SSH）
#                            remote = SSH 部署到边缘设备
#     request_template   : 每个 device 预填好的连接骨架，<REQUIRED: ...> 是用户必须补的空

# 2. 从 request_template 拷出来，填好空，组成 --connection（嵌套 dict）
#    本机 Docker（免 SSH）：选 local target，零凭据
#      {"<device_id>":{"target":"<...>_local","target_type":"local"}}
#    远程 SSH：选 remote target，补 host/username/password/port
#      {"<device_id>":{"target":"<...>_remote","target_type":"remote","host":"...","username":"...","password":"<REDACTED>","port":22}}

# 3. 部署（一次性，跑完即退）—— 注意：不要自己加 --json！
solutionctl deploy <solution_id> \
    --preset <preset_id> \
    --device <device_id> \
    --connection '<填好的 JSON>' \
    --yes
#   device_id 必须和 deploy-info 里的一致；--device 省略 = 部署该 preset 的全部步骤（CI 场景）
#   --verbose 看完整事件流（docker 拉层 + 轮询）；默认只渲染生命周期骨架 + 错误日志
#   --replace-existing 同名容器已存在时自动停掉重建（默认会报错让用户确认）