VSS 视频摘要

通过管道管理器运行摘要管道。自行调用文档化的 API，仅报告观察到的响应。端点使用 nginx 的 /manager 前缀。当 vss_* MCP 工具连接时，vss_summarize_video 涵盖相同的工作；此技能提供 REST 路径。

设置 HOST=http://${HOST_IP:-localhost}:${APP_HOST_PORT:-12345}。

VSS 不可达时的回答约定

用户可能不在部署环境中，$HOST 可能拒绝连接，或者实时前置条件可能失败（例如摘要模式被禁用或指定的视频不存在）。在任何这些情况下，不要停滞不前，也不要凭空捏造响应。 报告观察到的阻塞原因，然后给出用户修复后可运行的完整精确调用序列：完整的端点路径、请求体/表单字段、每个步骤从上一个响应中携带的字段，以及指示步骤完成的条件。不要仅仅因为未能执行而缩写或省略请求的摘要流程。明确说明哪些命令未被执行。切勿以询问是否运行它们来结束回答。

环境设置（先运行）

此技能通过其真实源文件驱动视频搜索与摘要应用，因此 VSS 应用必须存在，并且你必须从其应用根目录运行命令。在执行任何其他操作之前执行此操作，无论 VSS 源码是否已存在于你的工作区，此操作均有效。

运行捆绑的引导脚本。它按以下顺序解析应用根目录，并将其作为 stdout 上的唯一一行打印：

从当前目录向上遍历，查找 VSS 应用根目录——一个包含全部三个标记 setup.sh、docker/ 和 pipeline-manager/ 的目录。
询问 git 获取外层仓库（git rev-parse --show-toplevel）并检查它是否包含 sample-applications/video-search-and-summarization，或者本身就是一个 VSS 应用根目录。这使得你自己的克隆（或分支）无需更改即可工作。
复用先前引导已放置的检出，位于 ${XDG_CACHE_HOME:-$HOME/.cache}/vss-src/edge-ai-libraries。

如果命中以上任何一项，该检出将被复用且不执行克隆。仅当三者均未命中时才会进行克隆——并且仅克隆 main 分支上 sample-applications/video-search-and-summarization 的浅层（--depth 1）、单分支、稀疏检出：

# SKILL_DIR 是此技能自己的目录（技能加载时显示给你）；
# 在仓库中为 .github/skills/vss-summarize-video。如果技能独立安装，效果相同。
SKILL_DIR=".github/skills/vss-summarize-video"
APP_ROOT="$(bash "$SKILL_DIR/scripts/vss-bootstrap.sh")"
cd "$APP_ROOT"

下面的每个命令都假定工作目录是此 APP_ROOT。要从分支/复刻拉取或复用特定的检出目录，请先覆盖 VSS_REPO_URL、VSS_REPO_BRANCH 或 VSS_CLONE_DIR。引导程序拒绝覆盖现有的非 VSS 克隆目标。

前置条件

后端健康且摘要已启用——先探测；如果没有，按名称使用已安装的 vss-troubleshoot 或 vss-deploy 技能：

curl -sf "$HOST/manager/health" >/dev/null && \
curl -s "$HOST/manager/app/features" | jq -e '(.summary // .) == "FEATURE_ON"'

一个待摘要的 videoId——使用 POST /manager/videos（multipart，字段 video）上传一个，返回 { "videoId": "…" }。或者列出已有的——注意响应是一个对象 { "videos": [...] }，不是裸数组，且 name 是生成的哈希（真实文件名位于 url / dataStore.fileName 中）：
```
curl -s -X POST "$HOST/manager/videos" -F "video=@/path/to/clip.mp4" | jq .
curl -s "$HOST/manager/videos" | jq '.videos[] | {videoId, file: .dataStore.fileName}'
```

1. 启动摘要管道

POST /manager/summary。请求体包含必需字段；缺少 title、sampling.* 或 evam.evamPipeline 中的任何一个将返回 400。有关完整 schema、提示覆盖和音频选项，请参阅 references/summary-request.md。

最小有效请求：

curl -s -X POST "$HOST/manager/summary" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "装货码头审核",
    "videoId": "<VIDEO_ID>",
    "sampling": { "chunkDuration": 20, "samplingFrame": 5, "frameOverlap": 0, "multiFrame": 5 },
    "evam": { "evamPipeline": "object_detection" },
    "produceFinalSummary": true
  }' | jq .
# → { "summaryPipelineId": "<STATE_ID>" }

采样约束： 管道管理器强制要求 multiFrame == frameOverlap + samplingFrame。当 frameOverlap: 0 时，设置 multiFrame == samplingFrame。不匹配 → 400 "Multi frame mismatch"。evamPipeline 可选值为 object_detection | video_ingestion。

要仅摘要剪辑的一部分，添加可选的 sampling.videoStart 和 sampling.videoEnd（秒）——例如，前十分钟为 "videoStart": 0, "videoEnd": 600。

2. 轮询直至完成

返回的 summaryPipelineId 即为 stateId。GET /manager/summary/{stateId} 没有顶层的 status/progress 字段（只有 /raw 有）——进度信息位于每个阶段的字段中：

STATE_ID=<STATE_ID>
curl -s "$HOST/manager/summary/$STATE_ID" | jq '{
  chunking: .chunkingStatus,         # 字符串，分块完成时为 "complete"
  frames:   .frameSummaryStatus,     # 计数的对象：{complete, inProgress, na, ready}
  video:    .videoSummaryStatus,     # 字符串："na" → "inProgress" → "complete"  ← 真正的完成信号
  audio:    .audioTranscriptSummaryStatus,
  summary_len: (.summary | length)
}'

⚠️ 完成标志是 videoSummaryStatus == "complete"，而不是 summary 非空。 最终的 summary 文本是在 videoSummaryStatus 仍为 "inProgress" 时增量流式传入的，因此基于“摘要长度 > 0”进行轮询会返回一个截断的、句子中间的结果。始终以 videoSummaryStatus 为准。当 produceFinalSummary: false 时，没有最终阶段——改为以 frameSummaryStatus.inProgress == 0 为准。

until curl -s "$HOST/manager/summary/$STATE_ID" \
       | jq -e '.videoSummaryStatus == "complete"' >/dev/null; do sleep 10; done

摘要速度较慢（每块 VLM + LLM map-reduce）——需要几分钟，而非几秒。

3. 获取摘要

curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.summary'   # 最终的 map-reduce 摘要
# 每块的说明位于 .frameSummaries[] 中（每个：frameKey, status, summary）。
# 不在 .chunks[] 中——那些仅包含 {chunkId, duration, audioTranscripts}：
curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.frameSummaries[] | "[\(.frameKey)] \(.summary)"'
curl -s "$HOST/manager/summary/$STATE_ID/raw" | jq .   # 所有数据（音频、帧、状态……）

展示最终的摘要文本；如果有用，提供逐块的详细信息。没有语音的音频会产生一个说明此情况的 audioTranscriptSummary——不是错误。

最终答案审计线索

工具参数可能对用户或评估者不可见。因此，最终答案必须报告引导结果：解析出的 APP_ROOT、是否在未克隆的情况下复用了现有检出，以及更改到该应用根目录后运行的命令。还需说明，如果所有引导步骤均失败，则回退为对 main 分支上仅 VSS 应用进行浅层（--depth 1）、单分支、稀疏检出。报告观察到的 /manager/health 和摘要功能值。

对于摘要工作流，需列出使用的每个公共 Manager 操作（方法和 /manager/... 路径）、重要的请求字段、观察到的响应，以及从 summaryPipelineId 到 STATE_ID 的传递。当前置条件阻止执行时，需清晰区分已执行的探测和未执行的命令，并仍然展示精确的有效请求、完成条件和检索步骤，不得虚构 ID 或摘要内容。

管理

curl -s "$HOST/manager/summary" | jq '.[] | {stateId, title}'   # 列出所有
curl -s -X DELETE "$HOST/manager/summary/$STATE_ID"             # 删除一个

VSS 视频摘要/总结

总结是什么？

在你喜欢的 AI 中提问

文档