| name | video-competitor-analysis |
| description | 用于竞品视频、知识课程、短视频账号、视频 URL、本地视频、抖音主页、逐字稿、关键帧、镜头节奏和内容方法论拆解。Use when Codex needs to collect or analyze a creator/account/video series, transcribe or fully reconstruct a video, extract timestamped speech, recover slide/on-screen/visual information with Gemini and keyframes, or produce a reusable content playbook and 复刻策略。 |
视频竞品分析
核心原则
把外部 API 当作“分析素材生成器”，不要把它们当作对话代理。
- 转写任务默认交付逐字稿和起止时间码；分析稿、摘要和台本重构不能替代逐字稿。
- OpenAI API 负责音频逐字转写和时间轴，默认模型
gpt-4o-transcribe；需要说话人和精细时间戳时使用 gpt-4o-transcribe-diarize。
- 知识、课程、讲解、访谈和含幻灯片或屏幕文字的视频，默认调用 Gemini 做整片节点定位和视觉信息提取，默认模型
gemini-3.5-flash。
- 关键帧和 contact sheet 由 Codex app agent 直接读取本地图片，不调用 OpenAI 视觉 API。
- Gemini 提取、OpenAI 转写和关键帧读图必须交叉校验，不能互相冒充。
- 账号策略、复刻方法、脚本拆解、错字清洗和最终合成都在当前 Codex 对话中完成。
- 调用付费模型前先说明预计调用的模型和交付物；若不能交付用户要求的逐字稿，先停止并说明，不得消耗完 token 后才降级。
- 最终报告如实记录实际调用；没有调用 Gemini 时不得写成使用了 Gemini。
- 如果用户要求“最新模型”或“当前最强模型”，先查官方文档再更新模型路由。
工具工作区
在包含 pyproject.toml 和 tools/video_analysis 的工具仓库根目录运行命令。
安装依赖：
uv sync
uv run video-analysis-doctor
本仓库包含 uv.toml，默认把 uv 包索引指向清华 PyPI 镜像。若当前 uv 版本未读取配置，可显式设置：
$env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"
uv sync
OpenCLI 只在需要平台采集时使用。安装：
npm install -g @jackwener/opencli
opencli doctor
需要登录态的平台必须先在浏览器登录，安装 OpenCLI 浏览器扩展，并确保 opencli doctor 的浏览器桥接检查正常。
密钥只从 .env 或环境变量读取：
OPENAI_API_KEY
GEMINI_API_KEY
VIDEO_ANALYSIS_TRANSCRIBE_MODEL
VIDEO_ANALYSIS_DIARIZE_MODEL
VIDEO_ANALYSIS_GEMINI_VIDEO_MODEL
VIDEO_ANALYSIS_KEYFRAME_REVIEW_MODE
不要把真实密钥、Cookie、签名播放直链、用户信息、原片或生成的完整逐字稿写入 Skill 源码或提交到 Git。任务产物保存在被忽略的 analysis/ 中，只在用户授权范围内交付。
如果用户明确要求把本机视频分析相关 API key 同步到另一台机器，使用显式命令，不要在对话中展示密钥值：
uv run video-analysis-sync-env --dry-run
uv run video-analysis-sync-env --scp user@host:/path/to/video-analysis-skillkit/.env
需要手动传输文件时：
uv run video-analysis-sync-env --output .env.transfer --force
同步命令只包含白名单 key：OPENAI_API_KEY、GEMINI_API_KEY 和本工具链模型路由变量；额外变量必须由用户用 --key NAME 显式指定。
标准流程
- 采集：用
video-analysis-urls、OpenCLI 平台采集命令或手写 manifest，拿到视频路径、URL、作者信息、作品列表、标题、发布时间、互动数据、章节和可播放页面。
- 归档：按账号或项目 slug 写入
analysis/<slug>/，保留 metadata、下载状态、章节、转写、关键帧清单、contact sheet 和最终报告。
- 交付预检：确认用户要逐字稿、知识还原、内容分析还是全部；在 API 调用前说明模型路线和预计产物。若来源或权限使完整逐字交付不可行，先停下来说明。
- 时间轴转写：从视频中抽音频，用 OpenAI 生成原始 JSON 和可读逐字稿。保留说话人、起止时间、语气词和不确定词，不先改写成摘要。
- Gemini 整片提取：知识型视频默认让 Gemini 提取章节节点、口播主题、幻灯片文字、屏幕标签、图表关系、示例画面、视觉隐喻和建议复核的关键帧节点。
- 抽帧与读图：按 Gemini 节点、固定间隔、场景切换和高信息密度片段抽帧；由 Codex 读取 contact sheet，必要时打开单帧，校验 OCR、专名、图表和视觉例证。
- 清洗合并：以时间轴逐字稿为语言主线，用 Gemini 和关键帧修正错别字、专名及断句，并把所有只存在于画面中的信息写入对应时间点。
- 交付与审计：输出三份核心文本和可选插图版，检查时间覆盖、视觉信息覆盖、模型调用记录与证据标注。
命令入口
本地视频：
uv run video-analysis-local --manifest <manifest.json> --slug <analysis-slug>
需要说话人与模型级时间分段：
uv run video-analysis-local --manifest <manifest.json> --slug <analysis-slug> --diarize
知识视频整片提取：
uv run video-analysis-knowledge --video <video.mp4> --transcript <timestamped-transcript.md> --output <output-dir> --title <title> --source <url-or-path> --duration <seconds>
URL 下载并生成 manifest：
uv run video-analysis-urls --slug <analysis-slug> --url <video-url>
抖音主页采集：
uv run video-analysis-douyin-collect --sec-uid <sec_uid> --slug <analysis-slug> --limit 20
uv run video-analysis-douyin-manifest --slug <analysis-slug> --limit 20
uv run video-analysis-local --manifest manifests/<analysis-slug>.json --slug <analysis-slug>
同步本机 API key 到另一台机器：
uv run video-analysis-sync-env --scp user@host:/path/to/video-analysis-skillkit/.env
manifest 是 JSON 数组，每项包含 index、slug、title、source、path。
分析重点
拆解视频时同时覆盖以下层次：
- 选题钩子：人数、奖金、时间限制、场景、冲突、奇观承诺。
- 规则设计：挑战目标、淘汰机制、道具、阶段变化、反转。
- 台本结构：开场承诺、规则讲解、阶段推进、危机、高潮、结尾召回。
- 画面结构：封面、字幕、人物/群体调度、色彩、空间、AI 生成痕迹、镜头密度。
- 剪辑节奏：每 5-15 秒的信息变化、章节点、悬念续接、快慢切换。
- 账号方法论：系列化模板、可复制变量、成本结构、广告植入方式、风险点。
输出习惯
面向用户的最终输出优先使用中文，并保持可执行：
- 先说明能访问/已采集到什么。
- 单条知识视频默认交付：
gemini-extraction.md：章节节点、视觉内容、关键帧建议和整片结构。timestamped-transcript.md：保留完整口播、说话人和起止时间。complete-text.md：清洗错别字、合并口播与全部画面信息，脱离视频和截图也能完整阅读。
- 可选生成
complete-text-illustrated.md，在最终文本中插入关键截图；图片用于增强理解，不能承载纯文本版遗漏的信息。
- 幻灯片标题、项目符号、图表轴与箭头关系、屏幕文字、演示步骤、示例画面所表达的论点，都要转写成文字。
- 再给内容公式、画面拆解、节奏手法和可复刻模板。
- 对账号给“稳定母题 + 可变参数 + 选题库 + 制作流程”。
- 标明哪些内容来自 metadata、OpenAI 转写、Gemini、关键帧读图和 Codex 推断，并列出实际模型调用。
详细流程见 references/workflow.md；模型路由见 references/model-policy.md；报告结构见 references/report-format.md。
