@seeed-studio/solution-cli 0.3.1 → 0.4.0

package/docs/cli-guide.md

@@ -1,9 +1,7 @@
-# SenseCraft Solution CLI 使用与集成全景指南
-*(SenseCraft Solution CLI & AI Agent Skill Guide)*
+# Solution CLI 使用与集成指南
+*(Solution CLI & AI Agent Skill Guide)*
 
-> **定位**：本文档专门面向**方案架构师、现场应用工程师 (FAE)、嵌入式开发者以及 AI Agent (Claude Code / Codex / Antigravity / Work Buddy)**，系统性说明 `@seeed-studio/solution-cli` 的独特应用场景、安装流程、各功能指令的具体使用方式以及核心产出物。
-
----
+本文档面向方案架构师、现场工程师、开发者和 AI Agent。安装一次 `solution-cli` Skill 后，用户可以用自然语言完成方案咨询、硬件选型、部署前检查、本地/远程方案部署和部署后诊断。
 
 ## 目录
 
@@ -11,267 +9,242 @@
 2. [安装与 Agent 技能挂载](#2-安装与-agent-技能挂载)
 3. [核心功能、使用方法与具体产出](#3-核心功能使用方法与具体产出)
    - [场景一：方案探索与工况诊断 (Hub Search)](#场景一方案探索与工况诊断-hub-search)
-   - [场景二：硬件产品规格与配件防呆评估 (Product & BOM)](#场景二硬件产品规格与配件防呆评估-product--bom)
-   - [场景三：设备状态感知与参数热修改 (Device Management)](#场景三设备状态感知与参数热修改-device-management)
-   - [场景四：自研模型替换与本地二次开发 (Secondary Dev)](#场景四自研模型替换与本地二次开发-secondary-dev)
+   - [场景二：硬件配置与配件选型（“买这个设备需要配什么配件？会不会买错？”）](#场景二硬件配置与配件选型买这个设备需要配什么配件会不会买错)
+   - [场景三：方案一键部署与本地/远程运行 (Solution Deployment)](#场景三方案一键部署与本地远程运行-solution-deployment)
+   - [场景四：设备状态感知与参数热修改 (Device Management)](#场景四设备状态感知与参数热修改-device-management)
+   - [场景五：自研模型替换与本地二次开发 (Secondary Dev)](#场景五自研模型替换与本地二次开发-secondary-dev)
 4. [双轨运行机制：在线直连与离线托底](#4-双轨运行机制在线直连与离线托底)
 5. [常见问题与环境自检 (Doctor)](#5-常见问题与环境自检-doctor)
 
----
-
 ## 1. 独特使用场景与核心价值
 
-在传统边缘物联网与 AI 项目落地过程中，开发者通常面临以下痛点：
-- **方案选型盲目**：不清楚现场环境（集中还是分散、有无现有监控摄像头、有无市电）对硬件架构的致命影响；
-- **配件采购踩坑**：工控机买回后发现电源电压不符（如 12V 误插 19V 算力板）、DC 插头尺寸不对（5.5x2.1mm 插不进 5.5x2.5mm）、M.2 接口插槽类型搞混（Key-M 固态插不进 Key-E Wi-Fi 槽）；
-- **参数变更成本高**：改个 MQTT Broker 地址或算法置信度阈值就需要重新编译镜像或重装整套系统；
-- **AI Agent 缺乏边缘硬件感知**：纯大模型对话缺乏真实物理世界的接口约束，容易凭空编造不存在的硬件型号或非官方链接。
+`@seeed-studio/solution-cli` 提供三类能力：
 
-`@seeed-studio/solution-cli` 正是为解决这一系列问题而生，它具有三大独特角色：
-1. **方案专家的现场诊断仪**：内置各大行业工况诊断知识库，不仅能搜方案，还能直接指导工程师向客户提出决定成本与物理拓扑的“黄金追问”；
-2. **硬件采购防呆中枢**：内置物理规格匹配引擎，自动核算【必需配件】与【可选配件】，从源头阻断硬件返工；
-3. **AI Agent 的物理世界触手**：一键将 SenseCraft Skill 注入到主流 AI Agent 宿主中，让 Agent 具备从方案咨询、BOM 选型到现场部署、参数热更的全生命周期驱动能力。
+- 根据客户工况搜索方案，并列出仍需确认的问题。
+- 查询硬件规格、配件和物理兼容性。
+- 通过签名 Rust Engine 预检查并在本地或远程部署已选方案，持续读取状态、日志和验证结果。
 
----
+Agent 的默认工作流是“先咨询，再选型，再检查，最后在用户确认后部署”。用户只需描述目标，例如“帮我给锅炉房的 10 个恒温器设计改造方案”，Agent 应先查询方案并询问网络、供电、设备、温度约束和部署位置，不应把客户询盘直接当作部署授权。
 
 ## 2. 安装与 Agent 技能挂载
 
-### 2.1 一键免安装即时调用 (推荐)
-无需全局安装，安装或按需升级 Engine 与 Agent Skill 使用同一条命令：
+### 2.1 按需精准安装（推荐：只针对当前 Agent 安装，避免环境污染）
+
+你可以直接复制下表中对应的专属命令发给对应的 AI 助手，或在终端执行：
+
+| 目标 AI 宿主平台 | 专属安装命令（直接复制发给 AI 或在终端运行） | 技能默认配置路径 |
+|---|---|---|
+| **豆包工作 (Doubao Work)** | `npx -y @seeed-studio/solution-cli install --agent doubao` | `~/.doubao/skills` |
+| **WorkBuddy** | `npx -y @seeed-studio/solution-cli install --agent workbuddy` | `~/.workbuddy/skills` |
+| **Claude Code** | `npx -y @seeed-studio/solution-cli install --agent claude` | `~/.claude/skills` |
+| **OpenAI Codex** | `npx -y @seeed-studio/solution-cli install --agent codex` | `~/.agents/skills` 或 `~/.codex/skills` |
+| **Google Antigravity** | `npx -y @seeed-studio/solution-cli install --agent antigravity` | `~/.gemini/config/skills` |
+| **CodeBuddy** | `npx -y @seeed-studio/solution-cli install --agent codebuddy` | `~/.codebuddy/skills` |
+| **全部 Agent (全量覆盖)** | `npx -y @seeed-studio/solution-cli install --agent all` | 上述全部已检测目录 |
+| **自定义目录 (如 Cursor)** | `npx -y @seeed-studio/solution-cli install --skills-dir <路径>` | `<自定义路径>/solution-cli` |
+
+> [!TIP]
+> - **丢给 AI 极简执行**：例如在豆包工作中直接发送：*“请帮我运行：`npx -y @seeed-studio/solution-cli install --agent doubao`”*，AI 将直接在后台非交互执行并自动就绪。
+> - **严格隔离**：指定 `--agent <id>` 时，安装器依据 ledger 记录仅写入该 Agent 对应的目录，绝不修改其他 Agent 的技能或配置。
+
+### 2.2 本地源码部署与定制开发 (Local Deployment)
+
+如果你在本地仓库进行开发或调试，可以直接使用源码安装，无需经过 npm：
+
 ```bash
-npx -y @seeed-studio/solution-cli@latest install -y
+# 针对特定 Agent 安装
+node bin/cli.js install --agent <doubao|claude|codex|antigravity|codebuddy>
+
+# 挂载到自定义目录
+node bin/cli.js install --skills-dir ~/.cursor/skills
 ```
 
-首次安装和重复执行都会检查签名稳定版 Engine：本机已有相同或更新版本
-时复用，版本较旧时升级。普通安装保留用户修改、未登记的 Skill 文件和受
-保护的符号链接。需要指定宿主时追加 `--agent claude,antigravity`；需要固
-定有效本地 Engine 时使用 `--engine-path <path>`。`--force` 可重新下载相同
-或较旧版本并覆盖已有 Skill 文件（包括用户修改），请只在有意覆盖时使用；
-受保护的外部符号链接不会追写，也不能降级更新的本机 Engine。
+## 3. 核心功能、使用方法与具体产出
 
-自动复用/升级规则自 solution-cli 0.3.1 起生效；若 npm `latest` 仍为 0.3.0，
-这些规则尚未上线。本次验证时 0.3.1 待发布。latest 检查或签名校验失败会在
-修改 Engine、指针或 Skill 前停止；离线时请提供有效的 `--engine-path`。
+安装后可直接在命令行运行 `solution-cli` 与 `sensecraft-engine`；若未执行安装，也可随时通过 `npx -y @seeed-studio/solution-cli <command>` 免安装即用。
 
-The same command handles a fresh install and a user-requested upgrade. It checks
-the signed stable Engine, reuses an equal/newer local version, preserves modified
-skills, and stops before writes on latest/signature failure. Automatic reuse and
-upgrade rules start with solution-cli 0.3.1; if npm `latest` is still 0.3.0,
-those rules are not live. At this verification, 0.3.1 is pending publication.
+### 场景一：方案探索与工况诊断 (Hub Search)
+
+#### 1. 执行命令
 
-### 2.2 全局安装
 ```bash
-npm install -g @seeed-studio/solution-cli
+solution-cli hub search "锅炉恒温器" --json
 ```
 
-### 2.3 跨 Agent 平台技能挂载
-执行 `solution-cli install` 时，工具会自动检测本机存在的 Agent 宿主环境，并将 `sensecraft` Skill 和全套参考手册安全复制到对应目录：
+*(免安装时可用：`npx -y @seeed-studio/solution-cli hub search "锅炉恒温器" --json`)*
 
-| Agent 宿主平台 | 技能默认配置路径 | 支持能力 |
-|---|---|---|
-| **Claude Code** | `~/.claude/skills/sensecraft` | 完整方案咨询、工况诊断、BOM 生成、现场部署 |
-| **Codex (OpenAI)** | `~/.agents/skills/sensecraft` 或 `~/.codex/skills/sensecraft` | 代码审查、参数重构、二次开发自动化 |
-| **Google Antigravity (AGY)** | `~/.gemini/config/skills/sensecraft` | 端到端自主诊断、多 Agent 协同实施 |
-| **Work Buddy / Workbody** | `~/.workbuddy/skills/sensecraft` | 桌面端交互、方案展示、一键部署联动 |
-| **CodeBuddy** | `~/.codebuddy/skills/sensecraft` | 代码库配对开发与自研模型构建 |
+#### 2. 产出物内容 (What it Outputs)
+
+Agent 根据结果解释匹配的方案、设备和限制，并追问客户现场信息。方案未确认前只查询，不运行部署。
+
+#### 3. 产出示例 (以“农业”搜索为例)
+
+输出应包含匹配方案、适用场景、设备要求和仍需确认的工况问题；具体内容以查询结果为准。
+
+#### 4. 页面关系、内容读取与生产链接
+
+方案目录按显式关系组织，不把页面名称混用：Scenario 是业务落地页，Tech 是独立技术归属页，Reference Design（RD）是具体方案设计。Scenario 会关联 Tech 和 RD；RD 可继续关联架构图、产品说明和部署文档。只有 RD 存在有效部署映射和 preset 时，才可进入一键部署流程。
 
-**非交互式多选安装示例**：
 ```bash
-# 同时为 Claude Code 和 Google Antigravity 部署技能，不弹窗确认
-solution-cli install --agent claude,antigravity -y
+# 全量目录：按页读取，直到 has_more=false
+solution-cli hub list --type reference_design --locale zh --page 1 --limit 50 --json
+# 选定记录：按需要读取关系、链接、架构、产品或部署内容
+solution-cli hub get <id> --locale zh --section overview --json
+solution-cli hub get <id> --locale zh --section links --json
+solution-cli hub get <id> --locale zh --section architecture --json
+solution-cli hub get <id> --locale zh --section products --json
+solution-cli hub get <id> --locale zh --section deployment --json
 ```
 
----
+三种生产语言使用不同域名：英文 `www.seeed.cc`、中文 `www.seeedstudio.com.cn`、日文 `www.seeed.co.jp`。实际链接必须使用 `hub get --section links` 返回的地址；不要从 slug 拼接 Wiki、图片 CDN 或其他语言 URL。Wiki 是单独的已发布文档链接，Tech 页面也不能被当成 Wiki。翻译正文缺失时，保留可用的生产页并说明返回的内容语言。
 
-## 3. 核心功能、使用方法与具体产出
+返回链接或 metadata 不等于已经阅读页面内容。回答方案能力、架构或产品问题时，必须读取对应的 `description`、`architecture`、`products` section；确切落地页或架构图片影响答案时，打开 CLI 返回的确切地址并说明实际核验范围。相对图片路径只有在签名本地内容存在时才可读取，否则标为 source asset 未就绪。
 
-### 场景一：方案探索与工况诊断 (Hub Search)
+RD 的部署映射只是目录信息，执行前还要读取本机 Engine 的实际配置：
 
-当工程师或客户提出模糊需求（如“想在农田做微气象监测”、“工厂产线想做划痕检测”）时使用。
+```bash
+sensecraft-engine deploy-info <solution-id> --lang zh
+```
+
+架构部分只引用来源明确标记为 architecture 的图；其余图片按 gallery 呈现。产品说明、BOM、架构来源和部署文档都要保留来源与内容语言。
+
+### 场景二：硬件配置与配件选型（“买这个设备需要配什么配件？会不会买错？”）
+
+#### 1. 适用场景（客户常问什么）
+
+- “这款硬件（如 reComputer J40、SenseCAP Watcher）是什么配置？有几个网口、多大算力？”
+- “我买了这台主机，还需要额外配什么配件？电源、天线、外壳带不带？”
+- “我想加装 4G 模块或 SSD 固态硬盘，哪些型号能兼容？会不会买错插不上？”
+
+#### 2. 执行命令
 
-#### 1. 执行命令
 ```bash
-# 人类工程师阅读模式 (格式化终端高亮)
-solution-cli hub search "农业"
+# 1. 查硬件配置参数（算力、电压、物理接口、外形尺寸）
+solution-cli product query <family-id> --json
 
-# AI Agent 消费模式 (标准 JSON 格式的 Catalog DTO)
-solution-cli hub search "跌倒检测" --json
+# 2. 查配件推荐与兼容性清单（区分必买配件、可选配件，防踩坑）
+solution-cli product accessories <family-id> --json
 ```
 
-#### 2. 产出物内容 (What it Outputs)
-运行该命令可产出 4 项关键资产：
-1. **方案业务说明与技术架构**：解释为何适合在端侧运行、本地处理延迟、数据不出本地的隐私保障；
-2. **静默商业闭环出口**：自动为该方案生成带有安全追踪标记（`utm_source=sensecraft_agent`）的官方落地页与开发 Wiki；
-3. **官方开源仓库地址**：提供官方维护的 GitHub 源码仓库，为二次开发预留出口；
-4. **现场工况诊断提问指引 (Diagnostic Playbook)**：直接给出当前场景下**必须向客户确认的 2~3 个核心工况问题**及其背后的技术决断理由。
+#### 3. 它能为你产出什么（解决什么痛点）
 
-#### 3. 产出示例 (以“农业”搜索为例)
-```text
-🔍 Solutions Hub Search Results for "农业" (typesense):
-
-  1. [Reference Design] 农业环境监测可部署方案 | LoRaWAN 自建看板 (agri_env_monitor)
-     把 SenseCAP 土壤与空气传感器接到 Home Assistant 看板上，支持本地私有 ChirpStack 运行，断网可用。
-     预设模式: cloud, tts_local, chirpstack_local
-     现场工况诊断提问指引:
-       • 监测区域是集中式连栋温室大棚（百米级），还是大面积户外大田/果园（数公里级）？
-         (决断考量: 大棚内百米级可采用 RS485 总线；广域大田推荐 LoRaWAN 远距无线，配 SenseCAP M2 网关)
-       • 现场测点是否有 220V 市电供电，还是需要野外太阳能板/锂电池长续航供电？
-         (决断考量: 市电支持持续高频数据上报；无市电需选配支持休眠唤醒的超低功耗无线传感器)
-       • 需要监测哪些核心指标？仅空气温湿度，还是包括土壤剖面水肥墒情（水分/EC/pH）？
-         (决断考量: 决定是配置多合一微气象站，还是选配工业级土壤三参数探头与变送器)
-```
+1. **查清硬件规格**：直接返回 CPU/GPU 算力、供电范围、物理接口（网口/串口/USB）、外形尺寸等真实参数，无需翻找繁琐的说明书。
+2. **分清“必须买”与“按需选配”**：
+   - **必需配件（必须购买）**：如匹配功率的电源适配器、国标/美标电源线，不买设备无法开机；
+   - **可选配件（扩展使用）**：如安装导轨、外置天线、防护外壳、摄像头模组、M.2 扩展卡等。
+3. **防止买错踩坑（兼容性校验）**：
+   - 自动对比接口规格（如 M.2 Key-M 还是 Key-E）、天线频段（4G/Wi-Fi/LoRa）、供电电压与功率；
+   - 明确标注 `VERIFIED`（官方实测兼容）、`REQUIRES_ADAPTER`（需搭配转接板）或 `INCOMPATIBLE`（不兼容，严禁搭配使用）。
+4. **一键生成采购清单**：
+   - 结果直接包含官方真实 SKU、数量建议与购买链接，方便直接采购下单。
 
----
+### 场景三：方案一键部署与本地/远程运行 (Solution Deployment)
 
-### 场景二：硬件产品规格与配件防呆评估 (Product & BOM)
+方案部署由签名 Rust Engine (`sensecraft-engine`) 驱动，支持**本地一键部署**与**远程边缘设备部署**。
 
-当确定了方案，需要进入商务采购阶段、给客户出具设备清单时使用。
+#### 1. 读取部署规范与预设
 
-#### 1. 执行命令
 ```bash
-# 1. 查询产品族详情与物理规格
-solution-cli product query recomputer_j40 --json
-
-# 2. 评估该产品族所需的官方配件与兼容性
-solution-cli product accessories recomputer_j40 --json
+sensecraft-engine deploy-info <solution-id> --lang zh
 ```
 
-#### 2. 产出物内容 (What it Outputs)
-1. **精确分类的 BOM 清单**：
-   - **【必需配件 (REQUIRED)】**：没有该配件主机无法开机或无法运行（如专属电源适配器），附带选型理由；
-   - **【可选配件 (OPTIONAL)】**：根据工况选择的外设（如 NVMe 固态硬盘、Wi-Fi 模组、导轨安装卡扣、射频天线）；
-2. **物理兼容性安全评级**：
-   - `VERIFIED`（通过）：电压、引脚、尺寸完全匹配；
-   - `REQUIRES_ADAPTER`（需转接）：如 M.2 2242 规格装入 2280 卡槽需加铜柱；
-   - `INCOMPATIBLE`（不兼容/危险）：严禁搭配，防止烧毁板卡。
-
-#### 3. 产出示例 (以 reComputer J40 为例)
-```json
-{
-  "family_id": "recomputer_j40",
-  "physical_spec": {
-    "power_input": {
-      "connector": "dc_jack_5.5x2.5",
-      "voltage_v": 19.0,
-      "min_current_a": 4.74,
-      "polarity": "center_positive"
-    },
-    "m2_slots": [
-      {"key": "M", "size": "2280", "interface": "PCIe Gen4 x4 NVMe"},
-      {"key": "E", "size": "2230", "interface": "WiFi/BT"}
-    ]
-  },
-  "accessories": {
-    "required": [
-      {
-        "sku": "313080684",
-        "name": "19V 4.74A 电源适配器 (5.5x2.5mm)",
-        "category": "REQUIRED",
-        "compatibility": { "status": "VERIFIED" },
-        "url": "https://www.seeedstudio.com/Power-Adapter-19V-4-74A-p-5573.html?utm_source=sensecraft_agent..."
+根据返回的 `presets` 与 `device_connections` 准备参数文件 `./.sensecraft-work/body.json`。
+
+#### 2. 参数文件配置
+
+- **模式 A：本地快速部署（Local Docker，最简单、零密码配置）**
+  适用于在当前本地宿主机（Linux 工作站 / Jetson / 树莓派）上直接运行方案容器：
+  ```json
+  {
+    "solution_id": "<solution-id>",
+    "preset_id": "default",
+    "selected_devices": ["host_device"],
+    "device_connections": {
+      "host_device": {
+        "target": "local_host",
+        "target_type": "local"
       }
-    ],
-    "optional": [
-      {
-        "sku": "110991734",
-        "name": "M.2 2280 NVMe SSD 512GB",
-        "category": "OPTIONAL",
-        "compatibility": { "status": "VERIFIED" }
+    }
+  }
+  ```
+
+- **模式 B：远程边缘设备部署（Remote SSH 密钥认证）**
+  适用于部署到局域网内的远程边缘硬件。严禁使用明文密码，统一采用 SSH 私钥认证：
+  ```json
+  {
+    "solution_id": "<solution-id>",
+    "preset_id": "default",
+    "selected_devices": ["host_device"],
+    "device_connections": {
+      "host_device": {
+        "target": "remote_edge",
+        "target_type": "remote",
+        "host": "192.168.1.50",
+        "username": "seeed",
+        "key_file": "~/.ssh/id_ed25519"
       }
-    ]
+    }
   }
-}
-```
+  ```
 
----
+#### 3. 一行命令执行部署与状态追踪
 
-### 场景三：设备状态感知与参数热修改 (Device Management)
+```bash
+# 1. 验证参数并启动部署
+sensecraft-engine deploy --params ./.sensecraft-work/body.json --yes
 
-当方案已经在现场或测试架部署完毕，需要调整运行参数（如更换 MQTT Broker、调整告警置信度阈值）时使用。
+# 2. 查询部署进度与容器日志
+sensecraft-engine status <deployment-id> --json
+sensecraft-engine logs <deployment-id>
+```
 
-#### 1. 核心流程与接口
-系统支持**无需重新编译、无需重装整套系统**的零重启参数热修改：
-1. **查询当前设备活跃部署**：
-   `GET http://<host>:5823/api/device-management/active`
-2. **查询可修改参数**：
-   `GET http://<host>:5823/api/docker-devices/local/config/<solution_id>`
-   检查参数字段中的 `reconfigurable: true` 标记。
-3. **提交热更新**：
-   `PUT http://<host>:5823/api/docker-devices/local/config/<solution_id>`
-   传入目标键值，容器环境无感热加载生效。
+### 场景四：设备状态感知与参数热修改 (Device Management)
 
----
+#### 1. 核心流程与接口
 
-### 场景四：自研模型替换与本地二次开发 (Secondary Dev)
+已部署设备的参数修改要先读取当前部署和可修改字段，确认目标和变更范围，再执行对应管理接口。能否热修改取决于方案返回的 `reconfigurable` 字段；不要假设所有参数都支持无重启修改。
 
-当官方自带的模型无法满足客户特殊工况（如需要自研模型、特殊缺陷检测、修改前端大屏 UI）时使用。
+### 场景五：自研模型替换与本地二次开发 (Secondary Dev)
 
 #### 1. 开发闭环步骤
-1. **克隆源码**：
-   从 `solution-cli hub search` 返回的 `repo_url` 将源码克隆到本地用户工作区：
-   ```bash
-   git clone https://github.com/suharvest/sensecraft-solutions.git ./my-solutions
-   ```
-2. **端侧模型转换 (以 Jetson Orin 为例)**：
-   在设备上使用 TensorRT 将自定义 ONNX 导出为 Engine：
-   ```bash
-   /usr/src/tensorrt/bin/trtexec --onnx=my_model.onnx --saveEngine=my_model.engine --fp16
-   ```
-3. **覆盖挂载配置**：
-   在方案目录创建 `docker-compose.override.yml` 将本地自研模型映射进容器中。
-4. **驱动本地快速联调**：
-   使用 `--solutions-dir` 参数，强制底层引擎加载本地修改版方案，彻底不碰官方缓存：
-   ```bash
-   sensecraft-engine deploy fall_detection --solutions-dir ./my-solutions/solutions
-   ```
-
----
-
-## 4. 双轨运行机制：在线直连与离线托底
-
-为了保证在各类严苛现场环境下均能稳定运行，CLI 实现了智能双轨架构：
 
-```mermaid
-flowchart TD
-    RunCmd["用户 / Agent 触发 CLI 命令"] --> NetCheck{"检查网络与凭证"}
-    NetCheck -- "有外网且含烘焙配置" --> Typesense["直连 Seeed Typesense 云端搜索集群"]
-    Typesense -- "返回最新上线方案与配件" --> Done["输出 Catalog DTO"]
-    NetCheck -- "纯内网 / 无凭证 / 超时" --> LocalCore["无感降级: 读取 catalog/knowledge-core.json"]
-    LocalCore -- "331 KB 本地知识库 (18场景/39方案/119硬件)" --> Done
-```
+从查询结果中的官方仓库获取源码，在本地修改后按方案文档使用 `--solutions-dir` 进行测试。部署前展示修改和影响范围；不要把本地开发目录直接当作已验证的生产方案。
 
-1. **在线实时模式 (Online Live)**：
-   - 采用安全方案 B 在构建发布期烘焙了公开的只读 Search-Only 凭证；
-   - 自动直连 `https://rel-search.seeedstudio.com`，实时获取最新的方案、Wiki、案例及商城 SKU；
-2. **离线安全托底 (Offline Resilience)**：
-   - 打包了全量预生成的 `catalog/knowledge-core.json`（331 KB）；
-   - 在军工、内网、无公网或云端响应超过 2.5 秒时，**自动毫秒级无感降级到本地内核**，工况诊断、BOM 评估与离线部署 100% 正常可用。
+## 4. 双轨运行机制：在线直连与离线托底
 
----
+目录和产品查询优先使用在线资源；无法联网时使用已安装包中的本地内容和知识库。离线能力不代表所有在线方案或实时设备状态都可用。部署仍需目标设备可达、凭据有效、目标环境满足 `deploy-info` 和 `validate` 的要求。
 
 ## 5. 常见问题与环境自检 (Doctor)
 
 ### 1. 运行自检工具
-在部署前或遇到环境异常时，执行：
+
 ```bash
-solution-cli doctor
+solution-cli doctor --json
 ```
-工具将逐项检测并给出修复指引：
-- `OS Platform`: 确认宿主机操作系统及架构是否支持；
-- `Docker Daemon`: 确认 Docker 服务是否正常运行；
-- `Serial / Dialout Permissions`: 确认串口访问权限；
-- `SenseCraft Engine`: 确认底座引擎完整性与版本；
-- `Ledger Integrity`: 校验技能安装账本状态。
+
+重点查看操作系统、架构、Engine、PATH、串口权限、Docker 和 Skill ledger 的结果。远程设备的 SSH、sudo、Docker 安装和启动状态需按 `deploy-info`、`validate` 和设备返回信息单独确认；CLI 不会静默取得权限。
 
 ### 2. 状态查询
+
 ```bash
 solution-cli status
 ```
-实时查看当前 Engine 所在路径、安装版本、本地 Content 方案缓存数量以及各大 Agent 的配置状态。
 
-### 3. 干净卸载
-如需从某个 Agent 中移除 SenseCraft 技能：
+查看 Engine 路径、版本、内容缓存和 Skill 挂载状态。
+
+### 3. 网络与源排查
+
+若遇到 npm 下载或同步延迟，可在命令中显式指定官方源：
 ```bash
-solution-cli uninstall --agent claude,antigravity
+npx -y --registry=https://registry.npmjs.org/ @seeed-studio/solution-cli install -y
 ```
-工具将依据安装账本（`~/.sensecraft/skills-ledger.json`）仅删除工具自身写入的文件，绝不误删用户自定义创建的技能。
+
+### 4. 干净卸载
+
+只卸载指定宿主，并先备份需要保留的用户修改：
+
+```bash
+solution-cli uninstall --agent workbuddy
+```
+
+卸载依据 ledger 只删除 CLI 自己写入且未被修改的文件，不删除 Engine 或方案内容。旧的非 `solution-cli` Skill 目录需要用户自行备份和清理；不要使用 `rm -rf` 或 `--force` 代替确认。

package/lib/agent.js

@@ -2,21 +2,29 @@ import os from 'node:os';
 import path from 'node:path';
 import fs from 'node:fs';
 import readline from 'node:readline';
+import crypto from 'node:crypto';
+import { loadLedger } from './ledger.js';
 
 export function getKnownAgents() {
   const home = os.homedir();
 
   return [
+    {
+      id: 'doubao',
+      name: '豆包工作 (Doubao Work)',
+      homeDirs: [path.join(home, '.doubao')],
+      getSkillsDir: () => path.join(home, '.doubao', 'skills')
+    },
     {
       id: 'workbuddy',
-      name: 'Work Buddy / Workbody',
+      aliases: ['workbody'],
+      name: 'WorkBuddy / Workbody',
       homeDirs: [path.join(home, '.workbuddy'), path.join(home, '.workbody')],
       getSkillsDir: () => {
-        // Check where an existing installation might already be
         const p1 = path.join(home, '.workbuddy', 'skills');
         const p2 = path.join(home, '.workbody', 'skills');
-        if (fs.existsSync(path.join(p1, 'sensecraft', 'SKILL.md'))) return p1;
-        if (fs.existsSync(path.join(p2, 'sensecraft', 'SKILL.md'))) return p2;
+        if (fs.existsSync(path.join(p1, 'solution-cli', 'SKILL.md'))) return p1;
+        if (fs.existsSync(path.join(p2, 'solution-cli', 'SKILL.md'))) return p2;
         if (fs.existsSync(path.join(home, '.workbuddy'))) return p1;
         if (fs.existsSync(path.join(home, '.workbody'))) return p2;
         return p1;
@@ -36,8 +44,8 @@ export function getKnownAgents() {
         // Honor existing installation first to avoid path drift (Codex Medium 13)
         const pAgents = path.join(home, '.agents', 'skills');
         const pCodex = path.join(home, '.codex', 'skills');
-        if (fs.existsSync(path.join(pAgents, 'sensecraft', 'SKILL.md'))) return pAgents;
-        if (fs.existsSync(path.join(pCodex, 'sensecraft', 'SKILL.md'))) return pCodex;
+        if (fs.existsSync(path.join(pAgents, 'solution-cli', 'SKILL.md'))) return pAgents;
+        if (fs.existsSync(path.join(pCodex, 'solution-cli', 'SKILL.md'))) return pCodex;
         // Default to .agents/skills if .agents exists, otherwise .codex/skills if .codex exists
         if (fs.existsSync(path.join(home, '.agents'))) return pAgents;
         if (fs.existsSync(path.join(home, '.codex'))) return pCodex;
@@ -66,10 +74,28 @@ export function getKnownAgents() {
 
 export function scanLocalAgents() {
   const agents = getKnownAgents();
+
+  try {
+    const ledger = loadLedger();
+    for (const [targetId, inst] of Object.entries(ledger?.installations || {})) {
+      if (targetId.startsWith('custom_') && inst) {
+        const skillsDir = inst.skills_dir || (inst.target_dir ? path.dirname(inst.target_dir) : (inst.targetDir ? path.dirname(inst.targetDir) : null));
+        if (skillsDir && fs.existsSync(skillsDir) && !agents.some(a => a.id === targetId)) {
+          agents.push({
+            id: targetId,
+            name: `Custom Agent (${skillsDir})`,
+            homeDirs: [skillsDir],
+            getSkillsDir: () => skillsDir,
+          });
+        }
+      }
+    }
+  } catch {}
+
   return agents.map(a => {
     const skillsDir = a.getSkillsDir();
     const detected = a.homeDirs.some(dir => fs.existsSync(dir)) || fs.existsSync(skillsDir);
-    const installed = fs.existsSync(path.join(skillsDir, 'sensecraft', 'SKILL.md'));
+    const installed = fs.existsSync(path.join(skillsDir, 'solution-cli', 'SKILL.md'));
     return {
       ...a,
       detected,
@@ -79,29 +105,62 @@ export function scanLocalAgents() {
   });
 }
 
-export async function promptAgentSelection(scannedAgents, cliArg, autoYes = false) {
+export function formatAgentList(scannedAgents) {
+  return scannedAgents.map(a => ({
+    id: a.id,
+    name: a.name,
+    detected: a.detected,
+    installed: a.installed,
+    skillsDir: a.skillsDir,
+  }));
+}
+
+export async function promptAgentSelection(scannedAgents, cliArg, autoYes = false, skillsDir = null) {
+  // If custom skillsDir is specified, inject a custom target
+  if (skillsDir) {
+    const resolvedDir = path.resolve(skillsDir);
+    const dirHash = crypto.createHash('sha256').update(resolvedDir).digest('hex').slice(0, 8);
+    const customId = `custom_${dirHash}`;
+    const customTarget = {
+      id: customId,
+      name: `Custom Agent (${resolvedDir})`,
+      skillsDir: resolvedDir,
+      detected: true,
+      installed: fs.existsSync(path.join(resolvedDir, 'solution-cli', 'SKILL.md')),
+      homeDirs: [resolvedDir],
+      getSkillsDir: () => resolvedDir,
+    };
+    if (!cliArg) {
+      return [customTarget];
+    }
+    // Avoid duplicate if already scanned from ledger
+    const existingIdx = scannedAgents.findIndex(a => a.id === customId);
+    if (existingIdx >= 0) {
+      scannedAgents[existingIdx] = customTarget;
+    } else {
+      scannedAgents.push(customTarget);
+    }
+  }
+
   // If explicitly specified in CLI flags
   if (cliArg) {
     if (cliArg.toLowerCase() === 'all') {
       return scannedAgents;
     }
     const requested = cliArg.split(',').map(s => s.trim().toLowerCase());
-    const matched = scannedAgents.filter(a => requested.includes(a.id));
+    const matched = scannedAgents.filter(a => requested.includes(a.id) || (a.aliases && a.aliases.some(alias => requested.includes(alias))));
     if (matched.length === 0) {
       throw new Error(`No matching agents for: "${cliArg}". Available: ${scannedAgents.map(a => a.id).join(', ')}`);
     }
     return matched;
   }
 
-  // Non-interactive check (CI / piped / daemon)
+  // Non-interactive check (CI / piped / daemon / AI Agent subprocess)
   const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
 
   if (!isInteractive) {
-    if (autoYes) {
-      const detectedOnly = scannedAgents.filter(a => a.detected);
-      return detectedOnly.length > 0 ? detectedOnly : scannedAgents.slice(0, 1);
-    }
-    throw new Error('Non-interactive environment detected. Please specify --agent <workbuddy|claude|codex|codebuddy|all> or pass -y.');
+    const detectedOnly = scannedAgents.filter(a => a.detected);
+    return detectedOnly.length > 0 ? detectedOnly : scannedAgents;
   }
 
   if (autoYes) {

package/lib/catalog-dto.js

@@ -13,6 +13,10 @@ export const SCHEMA_URL = 'https://spec.seeedstudio.com/schemas/v2/catalog-dto.j
  * @param {'FRESH' | 'STALE' | 'UNKNOWN'} [options.freshness='FRESH']
  * @param {string} [options.datasetVersion='2026-10-13.1']
  * @param {Array} options.records
+ * @param {Object} [options.pagination]
+ * @param {string} [options.scope]
+ * @param {string} [options.locale]
+ * @param {Object} [options.provenance]
  * @param {Object} [options.fieldCompleteness]
  * @param {Array<string>} [options.warnings=[]]
  * @returns {Object} Validated Catalog DTO
@@ -22,10 +26,14 @@ export function createCatalogDto({
   freshness = 'FRESH',
   datasetVersion = '2026-10-13.1',
   records = [],
+  pagination = null,
+  scope = null,
+  locale = null,
+  provenance = null,
   fieldCompleteness = { spec: true, compatibility: true, offer: source === 'typesense' },
   warnings = [],
 }) {
-  return {
+  const dto = {
     $schema: SCHEMA_URL,
     schema_version: SCHEMA_VERSION,
     dataset_version: datasetVersion,
@@ -37,6 +45,11 @@ export function createCatalogDto({
     records: Array.isArray(records) ? records : [],
     warnings: Array.isArray(warnings) ? warnings : [],
   };
+  if (pagination) dto.pagination = pagination;
+  if (scope) dto.scope = scope;
+  if (locale) dto.locale = locale;
+  if (provenance) dto.provenance = provenance;
+  return dto;
 }
 
 /**