设备实时抓拍技能

用途

当用户询问设备实时抓拍相关信息时，直接调用技能目录下的 Python 脚本完成查询，由脚本统一返回实时抓拍记录及其对应的图片，并据此生成完整抓拍报告。

适用于以下场景：

• 获取指定设备的实时抓拍
• 获取全部设备的实时抓拍

安装依赖

pip install requests
pip install pycryptodome

执行规则

1. 统一通过命令行执行 scripts/picture_capture.py。
2. 先从用户问题中提取结构化查询条件，再把这些条件转换成命令行参数传给脚本。
3. 不要把用户原始问题直接传给脚本。
4. 将脚本标准输出作为结果返回给上层；不要基于内部实现自行补写或臆造结果。
5. 如果脚本执行失败，返回脚本给出的错误信息，并明确说明查询失败。
6. 针对脚本的查询结果，生成一份抓拍报告总结。
7. 默认把抓拍图片一并转发，并从 snapshots[].local_path 或 query_result.image_attachments 读取图片本地路径。
8. 直接输出最终答案。严禁在输出中包含任何思考过程、执行计划或中间推理标签。

入参格式

显式查询参数

上层应根据用户意图抽取并传入以下参数：

• --name：设备名称，字符串，支持模糊匹配

示例：

python scripts/picture_capture.py --name "设备A" --json

运行时配置参数

以下参数属于脚本运行时配置，只有在部署或调试时需要覆盖默认配置才传入；普通业务查询通常不需要上层显式指定：

• --base-url：接口服务基础地址
• --timeout：请求超时时间，单位秒
• --snapshot-dir：抓拍图片本地存储目录；不传时默认保存到 ~/.openclaw/workspace/tmp_files/

示例：

python scripts/picture_capture.py --base-url "http://127.0.0.1" --timeout 30 --json

输出控制参数

• --json：返回 JSON 格式结果；本技能在正常业务查询中应默认追加该参数
• --verbose 或 -v：输出更详细的调试信息

说明：为满足“基于查询结果生成抓拍报告总结”和“默认把抓拍图片一并转发”的执行规则，上层在正常业务查询中应默认使用 --json。脚本返回的 JSON 作为事实来源，上层再基于 snapshots、snapshot.local_path 和 query_result.image_attachments 整理最终文字报告并追加图片。未带 --json 的纯文本输出仅适用于人工调试或临时核对脚本文本结果，不应作为面向最终用户的默认返回路径。

当需要把抓拍图片连同文字报告一起发给飞书机器人或其他支持图片上传的渠道时，必须使用 --json。此时脚本会返回：

• snapshots[].local_path：该条抓拍的本地绝对路径
• query_result.image_attachments[]：适合上层逐条追加到报告后的图片附件数组，包含 title（设备+通道）、local_path、snapshot_id、snapshot_time 等字段

示例：

python scripts/picture_capture.py --json

参数提取规则

当用户用自然语言提问时，上层需要先把问题转换为脚本参数。可按以下规则提取：

• 设备名称模式：设备后紧跟名称，例如 设备A

提取后应转换为对应命令行参数，而不是把原句直接交给脚本。

参数优先级与默认行为

1. 上层先完成用户问题的参数提取。
2. 提取出的结构化条件直接映射为脚本显式参数。
3. 如果未提供设备名称，脚本会获取全部设备的实时抓拍。
4. 除非明确是在人工调试脚本，否则默认追加 --json，以便读取抓拍图片本地路径并组织最终答案。

因此，推荐策略如下：

• 普通查询：如果指定了设备名称，传 --name，并默认追加 --json；再基于返回的抓拍字段、snapshot.local_path 和 image_attachments 整理最终抓拍报告
• 需要结构化返回：在显式参数基础上使用 --json，并以上层整理后的抓拍报告和图片附件作为最终输出；不要把原始 JSON 直接当作最终答案抛给用户
• 需要通过飞书机器人发送抓拍图片：必须增加 --json，并在文字报告后按 image_attachments 顺序追加图片
• 仅人工调试脚本时：可省略 --json，直接查看脚本文本输出；该模式不是默认业务路径

标准调用方式

默认命令（获取全部设备的实时抓拍）：

python scripts/picture_capture.py --json

如果只是本地调试脚本文本输出，可使用：

python scripts/picture_capture.py

如果需要指定设备，追加对应参数，例如：

python scripts/picture_capture.py --name "设备A" --json

返回规则

• 脚本成功执行且以 JSON 形式输出时：以上层处理脚本标准输出中的字段为准，整理成最终抓拍报告；如果存在 query_result.image_attachments 或 snapshots[].local_path，应默认把对应抓拍图片一并追加到最终答案中。
• 脚本成功执行但调用方显式未传 --json 时：可直接使用脚本文本输出作为调试结果；该模式不应作为面向最终用户的默认返回路径。
• 脚本执行失败时：返回脚本错误输出，并说明本次抓拍查询未成功。
• 无论哪种成功路径，都不得补写脚本未返回的抓拍字段、图片信息或图片路径。

抓拍报告整理要求

• 每条抓拍至少整理抓拍ID、设备名称、通道、抓拍时间。
• 如果脚本返回了对应抓拍图片，报告中应整理抓拍时间、抓拍通道、抓拍地址或抓拍编码，以及 snapshot.local_path。
• 如果脚本明确返回某条抓拍获取失败，报告中应保留该状态，不要省略。
• 报告中的抓拍必须与对应记录一一对应，只能使用脚本已返回的结果。
• 如果脚本返回了 query_result.image_attachments，上层应先输出文字报告，再按数组顺序逐条追加图片。每张图片的标题使用 title 字段（设备+通道），图片内容从 local_path 读取并交给飞书机器人发送，不要只回显路径文字。
• 最终输出只保留整理后的抓拍报告和图片，不输出执行命令、参数提取过程、思考过程、执行计划或其他中间推理标签。

输出示例

查询到 2 条实时抓拍记录。

1. 抓拍ID：202512010001，设备名称：设备A，通道：1，抓拍时间：2025-12-01 10:23:11
   本地路径：C:\snapshots\snapshot_ch1_20251201102311.jpg

2. 抓拍ID：202512010002，设备名称：设备A，通道：1，抓拍时间：2025-12-01 11:05:42
   本地路径：C:\snapshots\snapshot_ch1_20251201110542.jpg

已按返回顺序附上抓拍图片：设备A-通道1。

用户输入：获取所有设备的实时抓拍

执行：

python scripts/picture_capture.py --json

用户输入：获取设备A的实时抓拍

执行：

python scripts/picture_capture.py --name "A" --json