vss-ask-video

用途

vss-ask-video 用于对已录制的视频片段发起全新的视觉提问，借助 VSS 智能体的 video_understanding 工具调用 VLM 查看视频帧来回答。当智能体没有可用的既有答案、需要对某个片段的像素做一次全新观察时使用该技能。

何时使用

用户询问视频中发生了什么，出现哪些物体、人物、动作、颜色、时间点、安全性，或其他需要观看片段才能回答的视觉事实。
用户询问无法从已有消息、摘要、Elasticsearch/MCP 结果或文件名单独得出的细节——需要模型对视频做推理。
在粗略摘要或报告生成之后，对内容细节的追问。

当数据库、MCP 或先前的工具输出已经能回答问题时不使用本技能，除非用户明确希望对照视频核验。

部署前置条件

本技能需要提供 video_understanding 工具的 VSS profile——通常为 base（推荐）或 lvs。任何请求之前：

探测 VSS 智能体：

curl -sf --max-time 5 "http://${HOST_IP}:8000/docs" >/dev/null

若探测失败，询问用户：

"No VSS profile is running on $HOST_IP. Shall I deploy base (recommended for per-clip VLM QnA) using the /vss-deploy-profile skill? If you prefer lvs, say so."

若同意 → 转交 /vss-deploy-profile -p base（若用户偏好则 -p lvs）。成功后回到本技能。

若不同意 → 停止。

若探测通过 → 继续。

传感器前置条件

在调用任何 /generate 之前，必须先列出 VST 传感器。即使用户明确指出了传感器名称、即使用户声称视频已上传、即使上一轮看似使用了同一视频，这一步都是必需的。不得跳过。

列出传感器：

curl -sf --max-time 5 "http://${HOST_IP}:30888/vst/api/v1/sensor/list" | jq '.[].name'

将返回的 name 值与用户提供的 <sensor-id>（或文件名主干，例如 warehouse_safety_0001）比对。

若存在匹配的传感器 → 进入下方的智能体工作流。
若不存在匹配的传感器 → 先上传视频，然后重新列出以确认新传感器出现：

# filename: must not contain whitespace
# timestamp: ISO 8601 UTC — default 2025-01-01T00:00:00.000Z if user did not specify
curl -s -X PUT "http://${HOST_IP}:30888/vst/api/v1/storage/file/<filename>?timestamp=<timestamp>" \
  -H "Content-Type: application/octet-stream" \
  -H "Content-Length: <file_size_in_bytes>" \
  --upload-file /path/to/<filename> | jq .

完整上传语义（v1 与 v2、冲突处理、删除流程）见 /vss-manage-video-io-storage。在交互式运行中，上传前需与用户确认。切勿在未先执行上述传感器列表检查的情况下无条件发出 PUT——这正是该前置条件旨在防止的失败模式。

智能体工作流

上述传感器前置条件必须已确认（或已使）传感器存在于 VST 上。然后：

片段——确定某个视频片段的传感器 id、文件名或 URL。若有歧义，询问用户。
以该传感器 id 调用 vss 智能体，并要求它调用 video_understanding 工具来回答用户的问题。
将 vss 智能体的答案返回给用户。

查询 VSS 智能体（/generate）：

# Set from deployment (compose / .env / host where vss-agent listens)
export VSS_AGENT_BASE_URL="http://localhost:8000"

curl -s -X POST "${VSS_AGENT_BASE_URL}/generate" \
  -H "Content-Type: application/json" \
  -d '{"input_message": "Call video_understanding tool to answer the following question about <sensor-id>: <user query>"}' | jq .

响应约定与提取

/generate 返回 JSON 对象，助手输出位于 value 中，例如：

{"value":"<agent-think><agent-think-step ...>...</agent-think-step></agent-think>\n\n<final answer>\n\n"}

没有单独的干净答案字段。可用的答案是从 .value 中移除任何 <agent-think>...</agent-think> 块后的文本。

本技能（及任何下游调用方）所需的处理：

从 JSON 响应中读取 .value。
剥离任意位置出现的 <agent-think>...</agent-think> 部分。
仅将剩余的最终答案文本返回给用户。

提取示例：

curl -s -X POST "${VSS_AGENT_BASE_URL}/generate" \
  -H "Content-Type: application/json" \
  -d '{"input_message":"Call video_understanding tool to answer the following question about <sensor-id>: <user query>"}' \
| jq -r '.value' \
| python3 -c 'import re,sys; t=sys.stdin.read(); t=re.sub(r"<agent-think>.*?</agent-think>\s*", "", t, flags=re.S); print(t.strip())'

交叉参考

vss-manage-video-io-storage——VST 存储/回放 URL，使 VIDEO_URL 对 VLM 有效。
vss-generate-video-report——通过 Mode A（直接 VLM）或 Mode B（视频分析事件）生成带时间戳的报告；本技能是用于临时视频问答的 VSS 智能体 /generate。

限制

本技能的文档未提供关于收费、价格、平台支持范围、效果指标或使用时长限制等信息，此类事实暂未提供。