vss-ask-video

通过 VSS Agent 使用 VLM 进行视频问答

当你需要了解视频详情，且需要 VLM 查看视频帧时，使用此技能——例如，Agent 没有可用的已有答案，需要对特定片段中的画面进行即时查看。

---

使用时机

• 用户询问视频中发生了什么、出现了哪些物体 / 人物 / 动作、颜色、时间点、安全性或其他需要观看片段才能获知的视觉事实。
• 用户询问的详情无法仅凭现有消息、摘要、Elasticsearch/MCP 结果或文件名回答——需要对视频进行模型推理。
• 在获得粗略摘要或生成报告后，用户继续询问内容详情。

如果数据库 / MCP / 先前的工具输出已经能回答问题，请勿使用此技能，除非用户明确要求对照视频进行验证。

---

部署前提

此技能需要一个提供 video_understanding 工具的 VSS 配置文件——通常为 base（推荐）或 lvs。处理任何请求前：

1. 探测 VSS Agent：

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

2. 如果探测失败，询问用户：

   "当前没有 VSS 配置文件在 $HOST_IP 上运行。是否使用 /vss-deploy-profile 技能部署 base（推荐用于单片段 VLM 问答）？如果你更倾向于 lvs，请告知。"

   • 如果同意 → 移交给 /vss-deploy-profile -p base（或用户偏好的 -p lvs）。部署成功后返回此处。
   • 如果不同意 → 停止。

3. 如果探测通过，继续。

---

传感器前提

在调用任何 /generate 之前，必须先列出 VST 传感器。 即使用户明确指定了传感器、声称视频已上传，或上一轮似乎使用了同一个视频，也必须执行此步骤。不要跳过。

1. 列出传感器：

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

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

3. 如果存在匹配的传感器 → 继续执行下方的 Agent 工作流。

4. 如果没有匹配的传感器——先上传视频，然后重新列出传感器，确认新传感器已出现：

   # 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——这正是设置此前提要避免的失败情形。

---

Agent 工作流

必须先满足上述传感器前提，确认 VST 上已存在（或已创建）该传感器。然后：

1. 片段——确定某个视频片段的传感器 ID、文件名或URL。如果不明确，请询问用户。
2. 调用 VSS Agent，传入传感器 ID，并要求其调用 video_understanding 工具回答用户的问题。
3. 将 VSS Agent 的回答返回给用户。

查询 VSS Agent（/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> 块后的文本。

此技能（及任何下游调用方）必须按以下要求处理：

1. 从 JSON 响应中读取 .value。
2. 删除所有位置出现的 <agent-think>...</agent-think> 部分。
3. 仅向用户返回剩余的最终答案文本。

提取示例：

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 — 通过 模式 A（直接 VLM）或模式 B（视频分析事件）生成带时间戳的报告；此技能使用 VSS Agent /generate 进行临时视频问答。