vss-manage-alerts

用途

运行 VSS 警报流水线（模式检测、Alert-Bridge 订阅、Slack 通知、查询、摄像头接入、验证器提示词自定义）。

前提条件

• 可通过 $HOST_IP 访问的活动 VSS 部署（参见 vss-deploy-profile 和 references/）。
• 如需拉取任何镜像，需在 $NGC_CLI_API_KEY 和 $NVIDIA_API_KEY 中配置 NGC 凭据。
• 调用方已安装 curl、jq 和 Docker。

说明

按照以下路由表和分步工作流操作。以 workflow、quick start 或 flow 结尾的各节均应从上到下执行。详细参考资料位于 references/，辅助脚本位于 scripts/；技能指示按名称调用脚本时，请通过 run_script 调用。

示例

可运行的端到端场景位于 evals/ 下（每个 *.json 清单一个场景）；各工作流中包含内联 curl 代码块。使用 nv-base validate <this-skill-dir> --agent-eval 重放。

限制

需要部署并可访问匹配的 VSS 配置文件/微服务。由 NGC 托管的模型/NIM 受速率限制、GPU 内存需求和许可条款约束；并发和存储限制取决于主机硬件及配置文件的 compose 文件。

故障排除

• 连接被拒绝 → 微服务未运行：探测 /docs 或 /health，或通过 vss-deploy-profile 重新部署。
• 拉取 NGC 时出现 HTTP 401/403 → 缺少或过期的 NGC_CLI_API_KEY：运行 docker login nvcr.io 并重新导出密钥。
• OOM / 模型加载失败 → GPU 内存不足：使用更小的变体，或运行 docker compose down 释放 GPU。

VSS 警报管理

alerts 配置文件以两种模式之一运行（通过 /vss-deploy-profile -p alerts -m {verification,real-time} 选择）——参见下方的两种模式表。本技能根据已部署模式 + 用户意图（监控、订阅 CRUD 或 Slack webhook）进行路由。

使用场景

• 在传感器上启动/停止实时警报（“在 warehouse_sample 上启动针对箱子掉落事件的实时警报”）
• 在 Alert Bridge 上创建/列出/停止实时订阅规则
• 设置或管理 Slack 事件通知
• 列出或查询已检测到的事件/警报；检查判定结果（已确认/已拒绝/未验证）
• 向警报流水线添加新摄像头；自定义 VLM 验证器提示词（CV 模式）

---

部署前提条件

需要在 $HOST_IP 上部署 VSS alerts 配置文件，模式为 verification（CV）或 real-time（VLM）。

# Either vss-rtvi-cv (CV mode) OR vss-rtvi-vlm (VLM mode) must be present.
curl -sf --max-time 5 "http://${HOST_IP}:8000/docs" >/dev/null \
  && docker ps --format '{{.Names}}' \
     | grep -qE '^(vss-rtvi-cv|vss-rtvi-vlm)$'

如果探测失败，询问要部署哪种模式，并交由 /vss-deploy-profile -p alerts -m <mode> 处理（若用户拒绝则停止；如果已预先授权自主部署，则直接运行，默认使用 verification）。如果探测成功，则按步骤 1 检测模式。

---

两种模式（部署时选择）

模式	部署标志	环境变量（.env）	运行内容	可用功能
CV（verification）	-m verification	MODE=2d_cv	RT-CV（Grounding DINO）+ 行为分析 + alert-bridge VLM 验证器 + rtvi-vlm	同时支持静态 CV 流水线（工作流 A）和动态 VLM 实时警报（工作流 B/D）
VLM（real-time）	-m real-time	MODE=2d_vlm	alert-bridge + rtvi-vlm	仅支持动态 VLM 实时警报（工作流 B/D）和 alert-bridge 后端。不含静态 CV 流水线。

切换模式时，需使用 vss-deploy-profile 执行卸载 + 部署流程，并指定另一个 -m 标志（VLM → CV 会添加 CV 流水线；CV → VLM 会卸载该流水线）。两种模式下均运行 rtvi-vlm。

---

步骤 1 — 检测当前部署的模式

运行任何告警工作流之前，请先检查当前启用的模式。使用仅 CV 容器作为判断信号——vss-rtvi-vlm 不是可靠的模式信号，因为它在两种模式下都会运行。

# CV verification mode (vss-behavior-analytics + vss-rtvi-cv are CV-only)
docker ps --format '{{.Names}}' | grep -qx vss-behavior-analytics && echo "mode=CV"

# VLM real-time mode (no CV pipeline; vss-rtvi-vlm still runs)
docker ps --format '{{.Names}}' | grep -qx vss-behavior-analytics || \
  docker ps --format '{{.Names}}' | grep -qx vss-rtvi-vlm && echo "mode=VLM"

如果存在 vss-behavior-analytics → CV 模式（该模式也会运行 vss-rtvi-vlm）。 如果只有 vss-rtvi-vlm（且没有 CV 管道）→ VLM 模式。 如果两种情况都不符合，则尚未部署 alerts 配置文件——请引导用户使用 vss-deploy-profile 技能。

替代信号（无法访问 docker ps 时优先使用）：检查配置文件的 generated.env：

grep -E '^MODE=' deploy/docker/developer-profiles/dev-profile-alerts/generated.env
# MODE=2d_cv   → CV mode (full superset)
# MODE=2d_vlm  → VLM real-time mode (vss-rtvi-vlm only; no vss-rtvi-cv)

---

步骤 2 — 根据已部署的模式进行路由

已部署模式	用户询问……	操作
VLM 实时模式	Slack webhook 的设置／状态／测试／停止	工作流 E — references/alert-notify.md
VLM 实时模式	规则的增删改查，或传感器上带检测条件的实时告警，或停止／删除指定告警（按 alert_type／条件或规则 ID）	工作流 D — references/alert-subscriptions.md（包括两步停止／确认）
CV 验证模式	订阅／规则的增删改查，或 Slack／通知设置	拒绝——参见下方的标准拒绝文本
CV 或 VLM	不带检测条件的通用监控启动／停止	工作流 B（VLM） — 调用 VSS Agent；rtvi-vlm 在两种模式下都会运行
CV 或 VLM	事件查询／发生了什么（近期告警、时间范围、随口询问“今天有告警吗？”）	工作流 C（查询） — 两种模式均可使用；始终运行查询，切勿凭记忆回答
CV	静态 CV 告警接入／判定提示词自定义	工作流 A（CV） — 通过 vss-manage-video-io-storage 接入 RTSP；管道会自动识别
VLM	需要静态 CV 管道的 CV／行为分析／PPE 规则告警	需要重新部署 — 先确认，然后运行 vss-deploy-profile -m verification

触发重新部署前务必确认。 切换模式会停止所有当前运行的监控并重启服务。

意图优先级（命中第一项即停止）

1. 工作流 E（Slack） — Slack 专属关键词（slack、webhook + slack、bot token、slack channel）。仅有 notify 不足以触发此工作流。
2. 工作流 D（订阅） — 传感器 加上检测条件、规则 CRUD 关键词（rule、subscription、规则 ID），或按类型/条件停止或删除已命名的告警（“stop the PPE alert”“delete the collision rule”）。已命名的 alert_type/条件 = 现有规则 → 使用工作流 D 的两步停止协议（GET /api/v1/realtime → 是/否确认 → 删除），绝不使用工作流 B。
3. 工作流 B（VLM 监控） — 对传感器执行常规启动/停止操作，没有检测条件，也没有告警类型限定词（“start/stop real-time alert for sensor X”）。按类型命名的停止操作（“stop the PPE alert”）是停止规则 → 工作流 D。
4. 工作流 C（查询） — 查询事件 / 发生了什么（“show/list incidents”“recent alerts”、时间范围查询，以及随意询问“any alerts…?” / “any alerts so far today?” / “what's been triggered?”）。单独出现的 alerts（没有 rule/subscription/active rules）表示事件 → 工作流 C，绝不使用工作流 D。
5. 工作流 A（CV） — 处理未匹配以上工作流的所有 CV 部署请求。

alerts 与 alert rules（C 与 D）——只能选择一个，绝不能同时选择： 发生了什么 / 触发了什么（事件）→ 工作流 C （POST /generate）。配置了哪些规则/订阅，或哪些处于活动状态 → 工作流 D（单独的 GET /api/v1/realtime，不带 /incidents）。单独的 alerts = 事件（C）；alert rules / subscriptions / active rules = 清单（D）。切勿凭记忆作答；运行唯一正确的调用——完整端点详情见下文的工作流 C。

**消除歧义（B 与 D）：**如果提到了传感器并使用了启动/监控措辞，但检测条件不明确，请询问：

“您是想 (a) 在 Alert Bridge 上创建一个持续运行、直到您删除为止的持久告警规则，还是 (b) 通过 VSS Agent 启动一次性监控会话？”

停止操作的路由（B 与 D）：“Stop the <type> alert”（指定了 PPE、collision、fire 等 alert_type/条件）= 停止订阅规则 → 工作流 D（通过 GET /api/v1/realtime 查找，然后遵循 references/alert-subscriptions.md 中的两步停止/确认协议；不要调用 POST /generate）。单独的“stop real-time alert / stop monitoring on <sensor>”，且没有类型限定词 = 工作流 B。

如果提示混合了多个工作流（“start monitoring and send to Slack”），请先提出一个澄清问题，以确定执行顺序。

CV 模式下对 D 和 E 意图的拒绝文本

当部署模式为 CV verification，而用户提出告警订阅或 Slack/通知相关意图时，请逐字使用以下消息拒绝：

"Alert subscriptions and Slack notifications are only supported in VLM real-time mode. Your current deployment is <CV verification | not deployed>. To use these features, redeploy with /vss-deploy-profile -p alerts -m real-time (note: switching tears down current CV monitoring)."

不自动重新部署。是否切换模式由用户决定。

---

任一模式的前置条件：传感器必须已添加到 VIOS

两种模式都要求先通过 vss-manage-video-io-storage 技能在 VIOS 中注册摄像头：

• RTSP URL / IP 摄像头 → 使用 POST /sensor/add 添加（该技能的第 6 节）；记录 sensorId / 名称。
• 已命名的现有传感器 → 继续操作前，确认它出现在 GET /sensor/list 的结果中。

在 CV 模式下，添加 RTSP 即完成整个接入步骤（管道会自动获取）。在 VLM 模式下，这是工作流 B 的前置条件。

---

Agent /generate 端点

所有 VLM-flow 操作和所有查询操作都通过 VSS Agent 的自然语言端点：

AGENT="http://<AGENT_ENDPOINT>"   # default http://localhost:8000 on the alerts profile

curl -s -X POST "$AGENT/generate" \
  -H "Content-Type: application/json" \
  -d '{"input_message": "<natural-language request>"}' | jq .

端点解析： 使用当前 VSS 部署上下文中的 Agent 端点。如果不可用，请询问用户。不要通过文件系统发现端点。

可用性检查： curl -sf --connect-timeout 5 "$AGENT/docs"。

不要直接调用 rtvi-vlm 微服务端点——始终通过 Agent 调用。Agent 内部会分发到 rtvi_vlm_alert、rtvi_prompt_gen 和 video_analytics_mcp.get_incidents。

---

工作流 A — CV 模式（-m verification / MODE=2d_cv）

CV 警报由部署驱动，而非请求驱动——无需调用 Agent 来“创建”警报。

1. 通过 vss-manage-video-io-storage 的 GET /sensor/list 检查传感器是否位于 VIOS 中（此操作是幂等的——不要不加判断地执行 POST /sensor/add）。
2. 如果缺少，则通过该技能的 POST /sensor/add 将其接入。注册并上线后，CV 流水线会自动接入该视频流。
3. 确认其在线：curl -s "http://<VST_ENDPOINT>/vst/api/v1/sensor/<sensorId>/status" | jq .
4. 警报会进入 Elasticsearch（Behavior Analytics → 根据 alert_type_config.json 验证 alert-bridge）。使用工作流 C进行查询。

在仅部署 VLM 的环境中请求静态 CV 流水线警报，属于模式不匹配——请参见上方的路由表。

---

工作流 B — VLM 实时监控（CV 或 VLM 模式）

对于指定传感器，在没有检测条件时，通过 VSS Agent 处理通用的启动／停止意图（如果存在检测条件，则路由到工作流 D）。rtvi-vlm 在两种模式下都会运行。

# start: input_message = "Start real-time alert for sensor <id>"
# stop:  input_message = "Stop real-time alert for sensor <id>"
curl -s -X POST "$AGENT/generate" -H "Content-Type: application/json" \
  -d '{"input_message": "<start|stop> real-time alert for sensor <id>"}' | jq .

底层流程：rtvi_prompt_gen → rtvi_vlm_alert action="start"。 系统会为每个片段生成说明；如果某个片段的 VLM 响应包含 yes／true（不区分大小写），就会向 mdx-vlm-incidents 发布事件。提示词必须要求回答 Yes／No。在仅部署 VLM 的环境中请求静态 CV 流水线，属于模式不匹配——请参见路由表。

---

工作流 D — 警报订阅（仅限 VLM 实时模式）

在 Alert Bridge 上创建／列出／删除持久化的实时警报规则。当提示词包含规则关键词（rule、subscription、规则 ID）或将特定传感器与特定检测条件配对时，路由到此处，例如：“为 warehouse-dock-1 设置 PPE 违规实时警报”、“监控传感器 entrance-1 是否有人尾随进入”、“停止规则 496aebd1-…”。

不适用于此处： 不带条件的通用启动／停止操作（→ 工作流 B）或 Slack 操作（→ 工作流 E）。

加载并遵循 references/alert-subscriptions.md，将其作为订阅 CRUD 的权威操作指南。仅限 VLM 实时模式；在 CV 模式下，使用标准拒绝文本拒绝请求。

---

工作流 E — Slack 通知（仅限 VLM 实时模式）

仅当用户明确提到 Slack 或 webhook relay 时使用（启动／停止 webhook 服务、检查状态／运行状况、发送测试消息、设置 Slack 频道／令牌）。仅出现 notify 一词并不足以触发此路由。

alert-notify（端口 9090）≠ vss-alert-bridge（/api/v1/realtime）。 Slack 操作不要触及 vss-alert-bridge。

路由到此处的请求：“设置 Slack 通知”、“检查 alert-notify 是否正在运行”、“向 Slack 发送测试警报”。不路由到此处的请求：“有人进入区域时通知我”（→ D/B）、“在我的手机上发出警报并通知我”（含义不明确——请询问）。

加载并遵循 references/alert-notify.md。代码位于 scripts/alert-notify/。仅限 VLM 实时模式。

工作流 C — 查询 / 列出告警（两种模式均适用）

CV 和 VLM 生成的告警都会写入 Elasticsearch，并可通过 Agent 的 video_analytics_mcp.get_incidents 工具查询。向 $AGENT/generate 发送自然语言请求，例如：“显示传感器 X 的近期告警”“列出过去一小时内已确认的告警”“显示 Camera_02 在 <ISO> 到 <ISO> 之间的碰撞事件”。

随意表述的问题也会路由到这里。 “今天到目前为止有告警吗？”“今天有告警吗？”“触发了什么？”或“最近检测到什么了吗？”这类问题都是事件查询——发送 POST /generate（例如 {"input_message": "List alerts from today"}），并总结结果。绝不要凭记忆回答，也绝不要不运行查询就回复“没有告警”。 单独询问“告警”时，始终表示查询事件（工作流 C），而不是列出订阅规则（工作流 D）。

不要为事件查询列出订阅规则。 不带 /incidents 的裸 GET /api/v1/realtime 会列出规则（工作流 D），不适用于“发生了什么”这类问题——对于事件查询，绝不要调用或探测它，也不要加载工作流 D 操作指南。

空结果也是有效答案。 如果没有匹配的事件（例如刚部署的系统尚无活动），请报告所请求时间段内未找到任何事件 / 数量为 0，然后停止——不要转而列出规则或查找其他端点。

如需更丰富的 / 非自然语言筛选（传感器级、时间序列、计数），请使用 vss-query-analytics 技能（端口 9901 上的 VA-MCP）。

判定结果解读与 CV 验证器提示词（仅 CV 模式）

CV 告警带有 VLM 验证判定（confirmed / rejected / unverified）；VLM 实时事件没有单独的判定结果（触发条件本身就是 VLM 的 Yes/No 答复）。CV 路径的验证器提示词可通过 alert_type_config.json 自定义（重启 alert-bridge 以应用更改）。判定表、字段含义和提示词自定义规则请参阅 references/cv-verifier-prompts.md。

---

跨技能链接

任务	技能
部署、重新部署或切换告警模式	vss-deploy-profile — -p alerts -m {verification,real-time}
添加 RTSP/IP 摄像头、列出传感器、快照、片段	vss-manage-video-io-storage（添加传感器请参阅第 6 节）
从 Elasticsearch 查询时间范围内的事件 / 占用 / PPE 指标	vss-query-analytics（VA-MCP :9901）
根据告警生成详细事件报告	vss-generate-video-report
订阅 / Slack 子工作流	references/alert-subscriptions.md、references/alert-notify.md（代码位于 scripts/alert-notify/）

---

注意事项

• alert-notify（端口 9090）≠ vss-alert-bridge。 Slack 运维 → 工作流 E（alert-notify）；绝不要将 Slack 路由到 vss-alert-bridge 的 /api/v1/realtime。
• 按模式划分工作流范围： A 仅适用于 CV；B 和 C 两种模式均适用；D 和 E 仅适用于 VLM 实时模式（CV 模式下应使用规范文本拒绝）。
• 不要用 vss-rtvi-vlm 判断模式——它在两种模式下都会运行。请使用 vss-behavior-analytics（仅 CV）或 MODE 环境变量。
• 切换模式会拆除当前部署——正在运行的 VLM 流以及未持久化的 CV 告警状态都会丢失。
• 始终通过 $AGENT/generate 操作——绝不要直接调用 rtvi-vlm。VLM 触发条件是匹配 "yes" / "true" 令牌（不区分大小写）；rtvi_prompt_gen 会强制执行 Yes/No 模式，因此不要手动编写会破坏该模式的提示词。
• 两种模式都要求传感器已存在于 VIOS 中（对于仅 RTSP 输入，请使用 vss-manage-video-io-storage）。

bump:1