# Device Integration Guide

> Device Integration Guide is an Agent Skill for apps & automation published in the AgentFlocks/flocks repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

指导 Flocks 新建、添加和接入安全设备。Use when the user asks to create, add, onboard, or connect a new security device.

- Skill name: `device-integration-guide`
- Category: [Apps & Automation](https://www.openparable.com/skill/apps-automation/1)
- Source: https://github.com/AgentFlocks/flocks/blob/HEAD/.flocks/plugins/skills/device-integration-guide/SKILL.md
- Repository: AgentFlocks/flocks (415 GitHub stars when collected)

## SKILL.md

# Device Integration Guide

用于处理 Flocks 设备接入相关对话。目标是把用户带到正确路径：设备创建、配置写入和敏感凭证走设备接入页面。

## 适用场景

当用户提到以下意图时使用本 skill：

- 新建设备实例。
- 添加安全设备到 Flocks。
- 接入一个还没有出现在设备列表里的安全设备。
- 用户想把一个没有现成模板的安全设备做成 Flocks 可用设备。

## 核心原则

- 先确认用户是在**新建设备实例**、**整理配置草稿**，还是**测试连通性**。
- 不要要求用户在聊天里粘贴密码、Token、Cookie、API Key 等敏感凭证。
- 不要在 skill 中优先引导通过工具写入设备配置；设备接入页面表单和 JSON 草稿是配置写入的主路径。
- 每次修改后，优先用标准连通性测试验证结果。
- 保持回答简短，给出当前动作、结果和下一步。

## 决策流程

1. 用户已经在设备列表里有目标设备，并提供了 `device_id`：

- 如果是配置变更，回到设备接入页面表单或输出页面可回填 JSON 草稿。
- 如果是测试或排障，先走 `device_manage(action="connectivity_test")`。

2. 用户说“添加设备”“接入设备”“新建设备”，但还没有设备实例：

- 如果有已安装模板，引导用户在设备接入页面填写表单。
- 如果没有合适模板，进入自定义设备接入路径。
- 如果涉及密钥、密码、Token、Cookie 或浏览器登录态，只说明应该填到页面表单，不要在聊天中收集真实值。

3. 用户只描述产品、厂商、控制台地址或 API 文档：

- 先判断已有模板是否可用。
- 未安装模板需要先去 FlockHub 安装。
- 没有合适模板时，按“自定义接入路由”选择 API、浏览器或 Workflow。

## 设备列表与目标确认

如果用户没有给出 `device_id`，先调用：

```python
device_manage(action="list")
```

从返回结果里确认目标设备、机房、工具集和 `device_id`。

如果设备不存在，提醒用户前往「设备接入」页面添加设备；不要伪造 `device_id` 或直接调用业务工具。

## 新建设备与页面回填

用户在设备接入页面创建或配置设备时，目标是帮助页面得到清晰的表单信息。

需要收集的信息：

- 设备名称。
- 已安装模板的 `storage_key`。
- Base URL、Host、端口、协议、租户或区域等非敏感字段。
- SSL 证书验证偏好：`verify_ssl=true/false`。
- 需要填写哪些敏感字段，但不收集真实值。

当信息足够，并且当前任务是在设备接入页面生成配置草稿时，在回复末尾输出 JSON 代码块供页面一键回填：

```json
{"storage_key":"<storage_key>","device_name":"<设备名称>","fields":{"base_url":"https://example.local"},"verify_ssl":false}
```

JSON 草稿规则：

- 只包含非敏感字段。
- 不写真实 API Key、Secret、Token、Cookie、密码。
- 敏感字段留空或省略，并提示用户稍后在页面表单中填写。
- 如果没有合适模板，不要输出设备配置 JSON，先进入自定义接入路径。

## 自定义接入路由

没有合适已安装模板时，按用户描述选择路径：

- 设备提供 API 文档或开放接口：选择「API 接入」。需要创建 device 插件时，先使用 `tool-builder`，目标是设备插件，不是普通 API 服务。
- 设备主要通过 Web 控制台操作，没有开放 API：选择「浏览器接入」。需要捕获页面能力时，先使用 `web2cli`，生成可维护的设备能力。
- 数据通过 Syslog、Kafka 或 Webhook 上报：选择「Workflow 接入」。不要创建 device 插件，引导用户走工作流发布/接入配置。

如果用户已经明确选择 API、浏览器或 Workflow，不要重复询问接入方式。只有无法判断时，才用一句话澄清。

## 配置草稿与表单更新

如果用户要写入或更新设备配置，应根据当前页面上下文整理表单草稿，让设备接入页面负责落库。

可以整理的非敏感字段包括：

- `base_url`
- `host`
- `port`
- `scheme`
- `timeout`
- `tenant`
- `region`

不要在 JSON 草稿或聊天中写入敏感字段：

- `api_key`
- `secret`
- `password`
- `token`
- `cookie`
- `auth_state`

如果用户的目标是补填密钥、修改密码、刷新 Token 或重新登录，只说明应该在设备接入页面对应字段中处理。

当需要给页面回填时，使用“新建设备与页面回填”中的 JSON 草稿格式。对于已有设备编辑，也只输出非敏感字段和 `verify_ssl`，并说明敏感字段在页面表单内填写。

## 连通性与冒烟验证

配置在设备接入页面保存后，除非用户明确不需要，继续调用：

```python
device_manage(action="connectivity_test", device_id="<device_id>")
```

连通性测试成功后，再选择少量只读、低风险的设备工具做基础冒烟验证。必须继续使用同一个 `device_id`。不要为了验证而执行写操作或高风险操作。

完成后汇报：

- 目标设备和 `device_id`。
- 页面中已整理或保存的字段名，不回显敏感值。
- 标准连通性测试结果。
- 只读冒烟验证结果。

## 失败排查顺序

连通性或冒烟失败时，按最小排查顺序给建议：

1. 地址或端口是否正确，Base URL 是否包含协议。
2. 设备侧网络、代理、防火墙或白名单是否允许 Flocks 访问。
3. `verify_ssl` 是否与设备证书状态匹配。
4. 页面里的凭证字段是否已填写且权限足够。
5. 设备版本、模板版本或工具集是否匹配。
6. 如果是浏览器接入，登录态是否过期，是否需要用户重新完成验证码、MFA 或人工确认。

## 不要做

- 不要在聊天中索要、保存或复述真实密钥。
- 不要把自定义设备误做成普通 API 服务。
- 不要对未安装模板输出可回填 JSON。
- 不要跳过 `device_manage(action="connectivity_test")` 就声称设备已可用。
- 不要把卡片状态建立在普通业务工具结果上；卡片状态以标准连通性测试写入结果为准。

---

Source: https://www.openparable.com/skill/apps-automation/device-integration-guide (OpenParable). Cite the canonical URL above.
