video-content-analysis

视频内容分析

/analyze-video <path> 会根据单个视频文件生成一套以清单为主导的产物包。下游专家（qualitative-coding-specialist、intersectionality-analyst、gender-transformative-assessor、sbcc-campaign-mel-specialist）会直接使用该清单。

使用时机

当请求提及视频、录音、FGD、网络研讨会、培训课程或 SBCC 片段，并要求提供转录文本、摘要、说话人分析或下游编码时触发。当 Ane 直接输入 /analyze-video <path> 时触发。

实时音频采集不触发（v1 仅支持基于文件的处理），非视频媒体也不触发（纯音频文件不在 v1 范围内）。

所需输入

一次性询问。前三项为必填项。

1. 视频路径（必填）。本地文件。支持的容器格式：mp4、mkv、mov、webm。
2. 隐私等级（必填）。可选 sensitive、internal、public。默认值为 sensitive。敏感内容（FGD、访谈，以及任何受知情同意约束的内容）须保留在本地计算机上。对于内部/公开内容，可在有字幕时使用 Microsoft 365 Stream 字幕。
3. 同意状态（必填）。可选 not_applicable、consent_internal_use_only、consent_research_anonymised、consent_research_attributed、consent_publication_anonymised、consent_publication_attributed、consent_unclear。consent_unclear 会阻止下游分析。
4. 语言提示（可选）。Whisper 使用的两字母代码（例如 ro、en、fr）。省略时自动检测。
5. 运行说话人分离？（可选，默认否）。--diarize 会在转录后运行 pyannote.audio。分析听到了谁的声音时必须启用。运行时间约增加 50%。
6. 生成品牌模板 Word 摘要？（可选，默认否）。--brand-summary 会按照 IPPF Visual Identity 2025 生成 summary.docx，同时保留纯文本版 summary.md。
7. 输出目录（可选）。默认值为 <video-parent>/<video-stem>.video-analysis/。
8. Microsoft 365 字幕文件（可选，仅限内部/公开内容）。用户已通过 Microsoft 365 MCP 服务获取的本地 .vtt 路径。使用此选项会跳过 Whisper。

方法

步骤 1 — 收集输入

在一条消息中向 Ane 询问必填项 1–3。如果调用时已传入 --diarize、--brand-summary 或字幕路径，则无需再次询问。遵循明确提供的值。

步骤 2 — 补充缺失的同意元数据

如果同意元数据不完整（已设置状态，但缺少 documented_in / documented_date / responsible_person），则再集中询问 Ane 一次。将收集到的值传入协调器调用，以便写入清单。

步骤 3 — 调用协调器

使用 Bash 运行虚拟环境中的 Python，并通过单行 analyze_video(...) 调用执行。运行前强制扩展 ffmpeg PATH。传入已收集的关键字参数。

$env:PATH = "$env:LOCALAPPDATA\Microsoft\WinGet\Packages\Gyan.FFmpeg_Microsoft.Winget.Source_8wekyb3d8bbwe\ffmpeg-8.1.1-full_build\bin;$env:PATH"
& 'C:/Users/AGasser/OneDrive/GitHub/personal-skills/skills/video-content-analysis/venv/Scripts/python.exe' -c @'
from pathlib import Path
from ane_package.video.orchestrator import analyze_video
from ane_package.video.types import ConsentMetadata, ConsentStatus, PrivacyTier
result = analyze_video(
    Path(r"<VIDEO PATH>"),
    privacy_tier=PrivacyTier.<TIER>,
    consent=ConsentMetadata(
        status=ConsentStatus.<STATUS>,
        documented_in=r"<PATH OR NOTE>",
        documented_date="<ISO DATE OR EMPTY>",
        responsible_person="<NAME OR EMPTY>",
    ),
    language=<"ro" OR None>,
    diarize=<True OR False>,
    brand_summary=<True OR False>,
    output_dir=<PATH OR None>,
    m365_caption_path=<PATH OR None>,
)
print("MANIFEST:", result.manifest_path)
print("SUMMARY:", result.summary_path)
print("BRAND_SUMMARY:", result.brand_summary_path)
'@

步骤 4 — 在对话中输出 Tier 1 BLUF 摘要

从协调器的返回值中读取 summary.md，并在对话中输出。最后一行附上清单路径，方便 Ane 将其交给 /ann 或某位专家。

步骤 5 — 每次运行后提示反馈

返回前运行反馈提示词。使用虚拟环境中的 Python：

& 'C:/Users/AGasser/OneDrive/GitHub/personal-skills/skills/video-content-analysis/venv/Scripts/python.exe' -c @'
from ane_package.video.feedback import prompt_verdict
v, n = prompt_verdict()
print(f"VERDICT={v.value}")
print(f"NOTE={n or ''}")
'@

如果判定结果为 partial 或 failed，则将判定结果和备注追加到 ~/.claude/skills/video-content-analysis/telemetry.jsonl，以便下次回顾时查看。协调器已为本次运行写入一条遥测记录；这第二次写入是通过 source_hash 关联的判定结果更新。（提示时机调整后，Stage 6 会将这两次写入合并为一次协调器内部调用。）

保存回归测试夹具（判定：部分完成 / 失败）

当一次运行以 partial 或 failed 结束时，该技能会提供选项，将其保存为回归测试夹具，存放在 tests/video/fixtures/auto/<source_hash>/ 下。

按层级控制：

• privacy: public 且 consent: not_applicable | consent_publication_* → 完整保存（源文件 + 转录文本 + 帧 + 清单）
• 任何其他符合条件的判定 → 仅保存元数据（已删去敏感信息的清单，其中剔除了同意信息 + 说话人标签 + 转录文本 + 源文件路径）
• consent_unclear → 完全禁止保存（无论判定如何）

自动保存目录已加入 Git 忽略列表——自动保存的夹具仅保存在本地，直到你审核并选择性提交。

第 6 步 — 返回

向 Ane 返回清单路径、摘要路径，以及（如果有）品牌摘要路径。建议下一步操作：

• “运行 /ann analyse the focus group findings in <manifest>”——进行深入编码。
• “运行 /ann compute speaker time-share by gender across these 3 manifests”——进行批量交叉分析。
• “打开 summary.docx 查看幻灯片”——适用于传入了 --brand-summary 的情况。

运行回顾协议

/analyze-video --retrospective

读取 ~/.claude/skills/video-content-analysis/telemetry.jsonl，根据 mel_wiki/wiki/calibration/video-content-analysis.md 中的七项基准计算表现，识别反复出现的问题，并写入 ~/.claude/skills/video-content-analysis/retrospectives/retrospective-YYYY-MM-DD.md。

仅提供建议。 回顾流程绝不会修改技能、规范或任何代码。Ane 会先审核并批准，之后才会发布任何更改。

当任何一次成功运行 /analyze-video 结束时，如果 should_run_retrospective(state) 返回 True，也会自动触发回顾流程——也就是说，成功运行 10 次后，或距上次回顾已满 4 周后（以先到者为准）。

输出

• manifest.json — 下游专用工具使用的唯一可信数据源。
• summary.md — Tier 1 BLUF 摘要，纯 Markdown 格式。
• summary.docx — IPPF Visual Identity 2025 品牌模板（传入 --brand-summary 时）。
• transcript.json / transcript.txt / transcript.vtt — 由基础工具生成。
• frames/ — 按顺序编号的 PNG 帧。
• network.log — 单行审计记录。

校准基准

此技能的运行质量基准位于工作文件夹中的 mel_wiki/wiki/calibration/video-content-analysis.md。

七项基准：

• 架构有效性（100% 的清单均通过 manifest_v1.schema.json 校验）
• 转录质量——罗马尼亚语（合成罗马尼亚语 FGD 夹具上的 WER < 15%）
• 隐私执行（sensitive 层级下 network_egress != none 的情况为零）
• 同意执行（绝不发布来自 consent_unclear 材料的交付内容）
• 数据缺口检测（每个 audio_quality_flags[] 标记都对应一条 data_gaps[] 记录；基于置信度的扩展需经 Stage 4.5 批准）
• 性能（在此硬件上，带说话人分离的 60 分钟 FGD < 90 分钟墙钟时间）
• 用户满意度（最近 10 次运行中，判定属于 {useful, partial} 的比例 ≥ 80%）

回顾协议会使用这些基准。请参阅上文对应章节。

证据基础： Stage 5 实施计划，位于 docs/superpowers/plans/2026-05-09-stage-5-skill-orchestrator.md；设计规范，位于 docs/superpowers/specs/2026-05-08-video-content-analysis-design.md 第 5–8 节和第 10 节；IPPF Visual Identity 2025 品牌模板，位于 ane_package.reporting.brand.IPPF_FORMAT_TEMPLATE。