Short-Form Idea Engine
从研究到脚本的流水线，将竞争对手的异常爆款视频转化为经过排序、符合品牌调性的短视频创意和完整脚本。
何时使用
当用户需要一个短视频创意流水线时使用此技能：发现某个利基中的爆款视频，理解其成功原因，生成重组创意，并获得可直接拍摄的脚本。
不要用于：
- 用户想要解码的单个已知视频：请转至
video-decoder技能。 - 用户已经拥有想法并希望编写脚本：请转至
script-writer技能。
依赖项
这是一个独立的插件。它捆绑了所有子技能和 Gemini 辅助脚本。不需要共享的技能环境。硬性外部需求是三个 API 密钥（见下一节）。
| 依赖项 | 在此技能中的角色 |
|---|---|
virlo 技能（已捆绑） | 阶段1 关键词模式：通过利基关键词在 Instagram、TikTok 和 YouTube 上发现异常爆款短视频 |
scrape 技能（已捆绑） | 阶段1 账号模式、阶段2 和阶段4 CDN URL 解析：通过 ScrapeCreators API 拉取最近的帖子、转录文本、封面帧和直接媒体 URL |
video-decoder 技能 | 阶段3 和阶段4：将每个异常视频解码为完整的解码记录（视觉钩子、文字钩子、口语钩子、根源、病毒向量、兴趣主题、格式） |
script-writer 技能 | 阶段7：为每个获批的创意编写一个可随时制作的脚本 |
brand-profiler 技能（已捆绑） | 阶段0：当没有品牌档案时，构建一个新的品牌档案，收集所有模式字段，包括 voice_tone |
scripts/gemini-video-analyze.js（已捆绑） | 阶段4 深度分析：通过 OpenRouter Gemini 进行视觉分析（节奏、剪辑韵律、视觉风格、留存技巧、屏幕文字节奏） |
API 密钥与优雅降级
所需密钥：VIRLO_API_KEY、SCRAPECREATORS_API_KEY、OPENROUTER_API_KEY。
在阶段0（任何开销之前）加载它们：
source .env
降级规则：
| 缺少的密钥 | 影响 |
|---|---|
VIRLO_API_KEY | 关键词模式被禁用。账号模式仍可工作。在阶段0明确报告此情况。 |
OPENROUTER_API_KEY | 阶段4（深度分析）被完全跳过。所有解码保持为 shallow。源自浅层解码的创意将在排序表中被标记为 "浅层解码"。 |
SCRAPECREATORS_API_KEY | 引擎无法运行。所有模式下都需要 ScrapeCreators 来获取转录文本和封面帧。在阶段0停止并明确告知用户。 |
流水线
阶段0：接收输入
询问用户：
- 模式：关键词模式（通过利基关键词发现视频）或账号模式（分析特定竞争对手账号）。
- 品牌档案路径：指向已填写的品牌档案的路径，该档案遵循
references/brand-profile-template.md。如果不存在，提供通过链式调用捆绑的brand-profiler技能来构建一个，该技能以交互方式或基于现有品牌文档收集所有模式字段（voice_tone、audience、positioning、content_pillars、anti_topics、forbidden_constructions、proof_credibility、format_preferences、on_camera_talent）。 - 运行标识符：此会话的简短小写标签（例如
ai-tools-keyword或techcreator-handles）。用于命名运行文件夹。 - 运行基础路径：运行文件夹应写入的位置。默认基础路径是相对于当前工作目录的
./shortform-runs/，生成./shortform-runs/YYYY-MM-DD-<slug>/。如果会话在具有自己研究或输出区域的结构化项目中运行，询问用户是否将运行放置在那里。在写入任何文件之前，与用户确认解析后的基础路径。
检查所有三个 API 密钥。在花费任何积分之前报告哪些模式可用。在确认的基础路径下创建运行文件夹（例如 <base>/YYYY-MM-DD-<slug>/），并写入 00-intake.md，包含模式、查询或账号列表、使用的品牌档案文件名、运行基础路径、可用的密钥以及任何覆盖设置。
阶段1：发现
关键词模式。 调用 virlo 技能以查找利基关键词的异常爆款短视频。在 video-decoder/references/decode-framework.md 中定义的三个竞争对手环中运行发现：
- 直接环：完全相同的利基关键词。
- 间接环：受众相邻的关键词短语（同一受众，不同话题角度）。
- 相邻环：格式相邻的关键词短语（相同格式或制作风格，不同话题）。
一次调用一个环的 virlo 技能，传递该环的环标签和关键词短语。不要并发调用 virlo 处理多个环。virlo 技能拥有所有轨道机制：它首先检查是否存在覆盖该环关键词的现有 Comet，并在可用时重用其累积数据（免费），仅当没有匹配的 Comet 时才会触发新的 Orbit（成本：$0.50）。编排器的职责是排序：等待 virlo 返回一个环的排序异常列表，然后再调用 virlo 处理下一个环。
在 virlo 返回环的结果后，计算每个视频的异常幅度。Virlo 的结果包括创作者级别的异常比率，但编排器需要每个视频的比率用于阶段4和阶段6的排序规则。对于环结果中出现的每个唯一创作者，调用 scrape 技能获取该创作者在相关平台上的最近帖子（大约最近20个）。使用返回的帖子计算该创作者的中位数观看次数基线。然后计算每个视频的异常比率为 video_views / creator_median_views。将原始 JSON 响应保存到每个环和每个基线获取的 raw/ 中。
账号模式。 调用 scrape 技能获取相关平台上每个账号的最近帖子（大约最近20个）。对于每个账号，计算返回帖子中的中位数观看次数。仅保留超过该创作者自身中位数2倍或更多的帖子（异常阈值）。将原始 JSON 保存到 raw/。
如果某个账号产生的帖子数低于2倍阈值（低方差创作者），则无论如何包含该创作者最近表现最好的单个帖子。在 00-intake.md 中注明该账号没有明显的异常，并且已包含最高帖子作为后备。
在两种模式下，阶段1的输出是一个去重的异常视频列表，包含其源 URL、平台、创作者账号和观看次数。
阶段2：数据收集
对于每个异常视频，调用 scrape 技能收集：
- 转录文本：对于 YouTube，调用
scrape技能通过视频 URL 获取转录文本。对于 TikTok 和 Instagram，尝试从阶段1已获取的帖子负载中提取转录文本。如果帖子负载不包含视频的转录文本，则在将视频传递到阶段3之前，调用scrape技能的转录函数作为后备。 - 封面帧：帖子负载中返回的缩略图 URL。对于 YouTube，派生封面帧为
https://img.youtube.com/vi/[VIDEO_ID]/hqdefault.jpg。
将所有原始响应保存到 raw/，按源和时间戳命名（例如 scrapecreators-transcript-[video_id]-[timestamp].json）。下游使用的每个观看次数和参与度数字必须可追溯到 raw/ 中的文件。
阶段3：解码
对每个异常视频运行 video-decoder 技能。传入：转录文本（如果有）、封面帧 URL（如果有）、创作者账号、平台、异常幅度（阶段1计算的比率）以及竞争对手环分配（根据 video-decoder/references/decode-framework.md 中的环定义，相对于品牌对每个视频的环进行分类）。
video-decoder 技能返回每个视频的一个完整解码记录，包括视觉钩子（从封面帧和任何可见的屏幕文字派生）、文字钩子和口语钩子。将每个记录写入 01-decodes/[video_id].md。此时所有解码都有 decode_depth: shallow。
缺少转录文本本身不是跳过视频的理由。许多最高异常视频是文本叠加或 POV 风格的视频，没有口语内容。如果视频有封面帧或标题，则以 spoken_hook: n/a 进行浅层解码。仅当确实没有任何内容可解码时，才跳过视频：没有转录文本、没有封面帧、没有标题，并且没有其他有意义的信号（例如硬获取失败且没有任何可检索的内容）。将任何跳过的视频记录为 decode-failed 在 00-intake.md 中，并附带视频 URL 和确切原因。继续处理剩余视频。
阶段4：深度分析
选择排名前5到8个异常值，按异常幅度排序（比率最高优先）。
在调用 Gemini 辅助脚本处理任何视频之前，使用 scrape 技能解析该视频的直接 CDN 媒体 URL。社交页面 URL（例如 TikTok 或 Instagram 页面 URL）会被 Gemini 拒绝。将 CDN 媒体 URL 传递给辅助脚本，而非社交页面 URL。解析方法因平台而异：请查阅 scrape/references/reading-scrape.md 中的“解析视频的直接媒体 URL”部分，以了解各平台的方法（TikTok 需要视频信息查找；Instagram 媒体 URL 已在之前获取的帖子负载中；YouTube 观看 URL 直接传递）。在运行期间及时解析和使用 CDN URL，因为 CDN URL 会过期。
对于每个选定的视频，调用 Gemini 辅助脚本，并将标准输出直接重定向到原始文件，使用一个命令。
辅助脚本路径必须解析为包含此 SKILL.md 的目录（已安装插件内的 shortform-idea-engine 技能目录）的绝对路径。在运行时确定该目录，并在其中构造 scripts/gemini-video-analyze.js 的绝对路径。输出重定向目标指向阶段0中确认的运行基础路径下的运行文件夹。这两个路径是独立解析的：辅助脚本来自技能目录，输出来自运行基础路径。
OPENROUTER_API_KEY=<key> node <skill-dir>/scripts/gemini-video-analyze.js <cdnMediaUrl> "分析此短视频：节奏（平均剪辑频率，显著的慢速或快速片段）、剪辑韵律（剪辑模式：按节拍剪辑、反应剪辑、B-roll 穿插）、视觉风格（色彩分级、背景、相机运动、屏幕上图形密度）、屏幕文字韵律（相对于口语内容，字幕或提示出现的频率）、留存技巧（视频中使用的特定钩子、模式中断、悬念或循环）。为每个维度返回结构化说明。" > <run-base>/YYYY-MM-DD-<slug>/raw/gemini-<video_id>-<timestamp>.json
其中 <skill-dir> 是 shortform-idea-engine 技能目录的绝对路径（包含此 SKILL.md 的目录），<run-base>/YYYY-MM-DD-<slug>/ 是阶段0中确认的运行文件夹。
重定向将原始 Gemini 响应保存到运行文件夹内的 raw/gemini-<video_id>-<timestamp>.json，以满足阶段8的可追溯性要求。
对每个此类视频重新运行 video-decoder 技能，将 Gemini 块作为可选的深度分析输入传递。重新运行返回一个更新的解码记录，其中 decode_depth: deep 且 deep_notes 已填充。用深度记录覆盖现有的 01-decodes/[video_id].md。
如果未设置 OPENROUTER_API_KEY，则完全跳过阶段4。所有解码保持 shallow，并且标志“浅层解码”在阶段6中被记录在每个创意上。
阶段5：创意生成
汇集来自 01-decodes/ 中每个解码记录的所有病毒向量、兴趣主题和格式。生成10到15个重组创意。每个创意必须：
- 命名其借用哪个病毒向量（来自解码记录的逐字标签）。
- 命名其借用或改编哪个兴趣主题。
- 命名其使用哪种格式。
- 说明品牌角度：借用的病毒向量、兴趣主题和格式如何重组以适应这个特定品牌（使用品牌档案的
content_pillars、audience和proof_credibility字段来锚定角度）。 - 记录每个借用元素的源谱系：提取该元素的解码记录中的
creator_handle、source_url和video_id。如果一个元素出现在多个解码记录中，则列出所有。此谱系随创意一起传递，通过排序并进入脚本。
按环的提取信号权重在此适用（来自 video-decoder/references/decode-framework.md）：病毒向量来自所有四个环均有效；兴趣主题来自间接竞争对手信号最强；格式来自相邻竞争对手信号最强。相应地加权重组，但不要仅因为环而机械地排除创意。
如果解码池太小，无法在不捏造池中不存在的病毒向量、兴趣主题或格式组合的情况下支持10个不同的创意，则只生成池支持的原创创意。在 02-ideas.md 顶部注明不足和实际数量。切勿发明未解码的可提取元素。
阶段6：排序
使用 references/ranking-rubric.md 对每个创意评分：
- 对照品牌档案的
anti_topics列表检查每个创意。任何匹配都是立即取消资格（DQ: anti-topic）。从排序表中移除取消资格的创意。在02-ideas.md底部的排序表下方添加一个明确标记的“已取消资格（反话题）”部分，列出创意及其触发的具体反话题。 - 对幸存创意在两个维度上评分：
viral_potential（五个子因素的平均值：病毒向量强度、异常幅度、格式可重复性、话题新鲜度、钩子强度）和brand_fit（四个子因素的平均值：语态匹配、受众匹配、内容支柱匹配、真实可信度）。两者均使用1到10的评分标准。 - 计算
combined = viral_potential * (brand_fit / 10)。四舍五入到一位小数。 - 按
combined降序排列。当两个创意并列时，viral_potential较高的排在前面。 - 将排序表写入
02-ideas.md，列顺序为：# | idea | root | borrowed VV/IT/Format | source video | viral | brand fit | combined | one-line rationale。source video单元格显示创意追溯到的源视频，格式为@creator_handle / video_id。如果创意从多个解码记录中借用了元素，则列出所有源视频。
输出规范
文件结构
<run-folder>/
├── 00-intake.md
├── 01-decodes/
│ ├── [video_id].md
│ └── ...
├── 02-ideas.md
└── raw/
├── virlo-[ring]-[timestamp].json
├── scrape-[handle]-[timestamp].json
├── scrape-[handle]-baseline-[timestamp].json
├── scrapecreators-transcript-[video_id]-[timestamp].json
└── gemini-[video_id]-[timestamp].json
阶段7：脚本撰写
对于 02-ideas.md 中按 combined 排名前3的创意，调用 script-writer 技能。传入创意名称、病毒向量、兴趣主题、格式、品牌角度、源谱系、品牌档案路径以及来自 02-ideas.md 的原始解码记录（简化为 [video_id].md 路径）。script-writer 返回一个完整的、可立即制作的脚本。将每个脚本写入 03-scripts/ 目录，命名为 script-[rank].md，其中 [rank] 是创意在排序表中的排名。
阶段8：总结
将包含以下内容的摘要写入 00-intake.md 末尾：
- 发现阶段的总成本：每个
virlo Orbit$0.50，乘以使用的环数。加上scrapeAPI 调用的任何成本（脚本应估计）。 - 处理的视频总数：解码 + 跳过 + 失败。
- 生成的创意数。
- 已编写的脚本数。
- 注释：任何降级（例如“未提供 OPENROUTER_API_KEY；所有解码保持浅层”）。
- 列出所做的任何覆盖或用户决策（例如“用户选择覆盖基础路径到 ./research/”）。