VSS Summarize 影片摘要是做什麼的？

透過 Pipeline Manager 執行摘要管道。請自行呼叫文件中說明的 API 並僅回報觀察到的回應。端點使用 nginx 的 /manager 前綴。當 vss_* MCP 工具連線時，vss_summarize_video 會涵蓋相同的工作；此技能是 REST 路由。

設定 HOST=http://${HOST_IP:-localhost}:${APP_HOST_PORT:-12345}。

當 VSS 無法連線時的回答合約

使用者可能已離開部署環境，$HOST 可能拒絕連線，或即時前置條件可能失敗（例如，摘要模式已停用或指定的影片不存在）。在任何這些情況下，請勿停滯不前，也請勿憑空編造回應。 請回報觀察到的障礙，然後回答使用者可在修正問題後執行的完整確切呼叫序列：完整的端點路徑、請求內文/表單欄位、每個步驟從前一個回應攜帶過來的欄位，以及指示步驟完成的條件。請勿因為摘要流程無法執行而簡化或省略所要求的摘要流程。清楚說明哪些指令未被執行。回答結尾請勿詢問使用者是否要執行這些指令。

環境設定（優先執行）

此技能透過實際的原始碼檔案驅動影片搜尋與摘要應用程式，因此 VSS 應用程式必須存在，且您必須從其應用程式根目錄執行指令。請在任何其他操作之前執行此步驟，無論 VSS 原始碼是否已存在於您的工作區中，此步驟都能正常運作。

執行隨附的引導腳本。它會依序解析應用程式根目錄，並將其作為 stdout 的唯一一行輸出：

從目前目錄向上遍歷，尋找帶有 setup.sh、docker/ 和 pipeline-manager/ 三個標記的 VSS 應用程式根目錄。
向 git 詢問所在的儲存庫（git rev-parse --show-toplevel），並檢查它是否包含 sample-applications/video-search-and-summarization，或者它本身就是 VSS 應用程式根目錄。這可讓您自己的複本（或分支）無需修改即可直接使用。
重複使用先前引導腳本已放置的檢出，位於 ${XDG_CACHE_HOME:-$HOME/.cache}/vss-src/edge-ai-libraries。

如果任何一項命中，該檢出將被重複使用，且不會執行複製。僅在所有三項都未命中時，腳本才會執行複製——而且只會進行淺層（--depth 1）、單一分支、稀疏的檢出，只從 main 分支擷取 sample-applications/video-search-and-summarization：

# 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。請參閱 references/summary-request.md 以了解完整綱要、提示覆寫及音訊選項。

最小有效請求：

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

取樣限制： Pipeline Manager 強制要求 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,     # COUNTS 物件：{complete, inProgress, na, ready}
  video:    .videoSummaryStatus,     # 字串："na" → "inProgress" → "complete"  ← 真正的完成訊號
  audio:    .audioTranscriptSummaryStatus,
  summary_len: (.summary | length)
}'

⚠️ 完成條件是 videoSummaryStatus == "complete"，而非 summary 非空。 最終的 summary 文字在 videoSummaryStatus 仍為 "inProgress" 時會逐步串流傳入，因此輪詢「summary 長度 > 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 映射歸納）—— 需要數分鐘而非數秒。

3. 取回摘要

curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.summary'   # 最終的映射歸納摘要
# 每個片段的字幕存在於 .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、是否重複使用現有檢出而未進行複製，以及指令是在切換到該應用程式根目錄後執行的。同時也必須說明，若引導完全失敗，則會退回進行淺層（--depth 1）、單一分支、稀疏的檢出，只從 main 分支擷取 VSS 應用程式。報告觀察到的 /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 Summarize 影片摘要