pugoing-smart

提供 common API calls to Pugoing centralized control platform，用于查询区域、主机、设备，以及通过自然语言控制设备。

Security Scan

The skill's code and SKILL.md align with its stated purpose (calling a Pugoing control platform), but the package metadata fails to declare required credentials and the client will send API keys/bearer tokens to arbitrary URLs — a potential credential-exfiltration risk.

Purpose & Capability

The skill is designed to call Pugoing platform APIs and the code implements that. However the registry metadata claims no required environment variables or primary credential, while SKILL.md and client.py require PUGOING_API_KEY (default auth mode 'agent') or PUGOING_BEARER_TOKEN. That metadata mismatch is misleading and should be corrected.

Instruction Scope

SKILL.md and client.py allow specifying a full 'url' in the request spec; when used the client will send whatever auth headers are built (X-API-Key or Authorization) to that URL. This means a malicious or mistaken request spec could send your API key/token to an arbitrary external endpoint. The instructions do not restrict or warn about this.

Install Mechanism

No install spec; the skill is instruction + a small Python client.py. Nothing is downloaded or installed, so there is low installation-time risk.

Credentials

Requesting an API key or bearer token is proportional to a platform API client. But the package metadata omits these requirements, and the client will unconditionally require PUGOING_API_KEY when auth='agent' (the default). Combined with the ability to call arbitrary URLs, this makes the requested credentials higher-risk than the metadata implies.

Persistence & Privilege

The skill is not forced-always, does not modify other skills, and does not request persistent elevated platform privileges.

What to consider before installing

This skill appears to be what it says (a simple HTTP client for a Pugoing platform), but exercise caution before providing credentials. The registry metadata incorrectly declares no required env vars, yet the client requires PUGOING_API_KEY (default) or PUGOING_BEARER_TOKEN. Important points and recommended actions: - Do not set PUGOING_API_KEY or PUGOING_BEARER_TOKEN in long-lived or global agent environments unless you trust the skill source and the platform. Consider using ephemeral credentials. - The client accepts a full 'url' in requests and will send auth headers to that URL — this can be used to exfiltrate keys. Only use trusted request specs and set PUGOING_BASE_URL to the known internal platform URL. - If you must run this skill, inspect client.py yourself (it is short and readable) and ensure network policies restrict outbound access so the client can only reach the intended platform host. - Ask the publisher to update registry metadata to list required environment variables and the primary credential, and to add a warning in SKILL.md about full-URL usage and auth header behavior. - If you cannot verify the source or enforce network restrictions, avoid supplying credentials or run the skill in an isolated environment.

这个目录给龙虾或其他 Agent 用，目标是用最少的上下文完成对蒲公英集控平台的常见调用。

鉴权方式

推荐使用环境变量传 API Key，这也是很多同类技能最常见的做法。

需要的环境变量：

export PUGOING_BASE_URL="http://127.0.0.1:8080"
export PUGOING_API_KEY="xq_agent_xxx"

可选环境变量：

export PUGOING_BEARER_TOKEN="..."
export PUGOING_TIMEOUT="30"

默认鉴权：

• auth=agent 时，脚本自动带 X-API-Key: $PUGOING_API_KEY
• auth=bearer 时，脚本自动带 Authorization: Bearer $PUGOING_BEARER_TOKEN
• auth=none 时，不带鉴权头

通用调用对象

推荐传一个 JSON 对象给 client.py：

{
  "path": "/api/xq_host/list",
  "method": "GET",
  "params": {},
  "data": {},
  "auth": "agent"
}

字段说明：

• path: 相对路径，推荐写法
• url: 也支持完整 URL；若同时给了 url，优先使用 url
• method: GET 或 POST
• params: 查询参数
• data: JSON body
• auth: agent / bearer / none
• headers: 额外请求头
• timeout: 单次请求超时秒数

常见能力

1. 查区域和主机

调用：

• /api/host_area/list

返回重点：

• data.tree: 区域树，区域下带 hosts
• data.unpartitioned: 未分区主机

示例：

python pugoing_smart/client.py pugoing_smart/examples/list_areas_and_hosts.json

2. 查主机

调用：

• /api/xq_host/list

返回重点：

• 主机列表
• 每个主机的 ip、name、area_name、is_online

示例：

python pugoing_smart/client.py pugoing_smart/examples/list_hosts.json

3. 查某个主机下的设备

调用：

• /api/device/sync?host_ip=...

说明：

• 优先从主机同步设备
• 主机不可达时会回退本地缓存

示例：

python pugoing_smart/client.py pugoing_smart/examples/list_host_devices.json

4. 用自然语言控制设备

调用：

• /api/device/control/voice

推荐只用：

• host_ip
• dvcm

示例：

python pugoing_smart/client.py pugoing_smart/examples/control_device_by_dvcm.json

请求体示例：

{
  "host_ip": "192.168.1.88",
  "dvcm": "打开客厅灯"
}

5. 万能兜底：调用内置 AI

调用：

• /api/ai/chat

建议：

• 平台级查询或跨主机场景时，host_ip 传 "global"
• 单主机设备控制或上下文理解时，host_ip 传实际主机 IP
• need_tts 对接龙虾时通常设为 false

client.py 会自动把这个 SSE 接口收集为普通 JSON 输出，所以可以当普通接口用。

示例：

python pugoing_smart/client.py pugoing_smart/examples/ai_fallback.json

建议的调用顺序

当需求明确时，优先直调平台 API：

1. 先查区域和主机
2. 再查主机设备
3. 能直接用 dvcm 控制就直接控制

当需求模糊或要兜底时，再走内置 AI：

1. /api/ai/chat
2. host_ip=global 适合问“平台里有什么”
3. host_ip=<实际主机IP> 适合问“帮我控制这个主机下的设备”

目录内容

• client.py: 通用调用脚本
• examples/list_areas_and_hosts.json: 查区域和主机
• examples/list_hosts.json: 查主机列表
• examples/list_host_devices.json: 查某台主机设备
• examples/control_device_by_dvcm.json: 用 dvcm 控制设备
• examples/ai_fallback.json: 调内置 AI 兜底