Communitygithub.com

viralprinter

结构优先的短视频创作和评分工具。将主题、产品或粘贴的短视频URL转化为有证据支持的拍摄包;将声明式时间线通过ffmpeg组合成mp4;并基于病毒式结构规则对任意短视频(包括AI视频生成器的输出)进行评分。

viralprinter 是什么?

viralprinter 是一个结构优先的短视频创作与评分专业技能,专为AI代理(如 Claude Code、Cursor 等)设计。其核心在于代理负责推理和组合创作,而证据由外部源提供,绝不虚构。该技能包含两部分:本地可用的 CLI 工具(validate、compose、grade)和可选的 Shorti MCP 证据接口(提供真实短视频片段分析、演变谱系和借用手册)。用户可以通过四种主要流程工作:从主题或产品出发创建视频(Flow A/B)、分析已粘贴的 URL(Flow C)、获取拍摄现场指导(Flow D)或对任意短视频进行结构评分(Flow G,无需 Shorti 账号)。支持英文、韩文、日文等多语言环境,强调诚实报告、避免预测性数字,并严格遵守不发明媒体的原则。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ds4psb-ai/viralprinter/tree/main

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

viralprinter — 创作与评分短视频,带有结构证据

您驱动着两个部分。

  • 本地,始终可用。 本仓库中的 viralprinter CLI:validate、 compose(时间线 JSON → 通过 ffmpeg 生成 mp4)和 grade(根据病毒式结构规则对任意短视频评分)。无需账户、密钥或上传。
  • 证据,可选。 Shorti 的只读 MCP 接口:分析真实的短视频片段、它们的演变谱系(哪些元素传播了、哪些变异了、哪些消失了),以及每个片段的借用手册(保留/改变/永不触碰)及观众收据。

Shorti 不是视频生成器,您绝不能将其描述为视频生成器。您负责推理和组合创作。Shorti 提供证据,并在证据不足时诚实地弃权 —— 请如实传递其弃权信息;切勿自行填充。

如果用户只想对短视频进行评分,则完全跳过证据部分:进入流程 G。

设置

工具(compose 和 grade 必需)

git clone https://github.com/ds4psb-ai/viralprinter && cd viralprinter
uv pip install -e .          # 或:pip install -e .

Python ≥ 3.11。ffmpeg 和 ffprobe 必须在 PATH 环境变量中 —— compose 和视频模式下 grade 会调用它们。在承诺生成文件之前,请先用 viralprinter --help 确认。如果命令或二进制文件缺失,请说明情况并停止,而不是描述您未生成的输出。

Shorti 证据(可选)

claude mcp add --transport http shorti https://api.shorti.ai/mcp/public-read/mcp

任何支持 MCP 的代理客户端都可以用相同的方式使用该 URL。第一次调用会触发浏览器 OAuth 认证 —— 告诉用户完成认证,然后重试一次。此技能永不收集 API 密钥,从不要求用户将密钥粘贴到聊天中,并且永不上传用户的媒体:该挂载点根据合约是只读的(它永不发布、编辑、发布、删除或消费内容)。评分和组合无需 Shorti 账号;证据包是唯一需要账号的部分。

操作规则

  1. 最多一个组合问题。 如果缺少输入信息(主题 vs 产品 vs URL、目标宽高比、语言),请一次性询问。绝不在工具调用之间要求确认。
  2. 区域设置。 每次调用时传递与用户语言匹配的 locale(en、ko、ja),并完全使用用户的语言进行回答。
  3. 数字。 证据结果中的 observed_metrics 是来自语料库的事实统计 —— 将其作为证据引用。评分器数字是对您面前文件的测量值 —— 将其作为测量结果引用。绝不生成预测性数字:不预测观看次数、不提供“N×”倍数、不计算 ROI 百分比。只陈述结构声明,不承诺结果。
  4. 诚实的缺失。 证据薄弱或弃权是工具正常工作,同样,评分器分类报告 state: not_measured 并附带原因也是正常情况。按原样报告弃权信息;绝不猜测替代值或分数。
  5. 不要粘贴原始 JSON。 进行综合。用户阅读的是散文、包文件和评分卡 —— 而不是负载。
  6. 重试纪律。 每次失败调用最多重试一次。如果参数被拒绝,请重新阅读工具描述,而不是再次猜测。
  7. 绝不发明媒体。 时间线只能引用磁盘上实际存在的文件。如果片段缺失,请说明哪些缺失并在包文件处停止。

流程 A — “帮我做一个关于 [主题] 的短视频” / “이거로 쇼츠 만들어줘”

  1. 使用主题调用 search_trend_genealogy。带时间限制的查询传递 moved_within_days 参数(“本周”用 7,“最近”用 30)。
  2. 选择最强匹配(一句话说明您的选择和理由 —— 除非真正存在歧义,否则不要询问)。
  3. 恰好一次调用该匹配项的 get_trend_genealogy_card —— 这包含了借用手册:保留/改变/永不触碰、演变谱系、观众证据。
  4. 为所选片段调用 get_clone_kit_capsule —— 逐镜头的 콘티(分镜头脚本)。
  5. 编写包文件(见下文),然后如果用户有素材或希望生成渲染,则继续进入流程 F。

流程 B — “为我的产品做一个短视频”

  1. 调用 suggest_trends_for_product —— product_description= 参数无需任何注册即可使用;使用用户描述产品的原话。
  2. 然后执行流程 A 的第 2-5 步。如果用户拥有 Shorti 账号并注册了产品,list_my_products + get_my_product_truth 可以优化匹配。

流程 C — 用户粘贴了一个短视频 URL

粘贴的 URL 绝不是搜索。首先调用 preview_pasted_url,然后根据解析结果继续执行流程 A 的第 3-5 步。

流程 D — 拍摄中途指导

  • 下一个镜头:调用 get_next_shot_cue —— 每次调用返回一个提示,拍摄,重复。
  • “我做得怎么样?”:调用 get_shot_coaching_rubric,然后由您根据该评估标准对用户展示给您的片段进行评分。评估标准调用本身不包含文件或 URL 参数 —— 片段理解是您的工作,基于您已经看到的媒体。绝不将用户的素材发送到任何地方。如需对已完成文件进行结构性二次评估,请同时运行流程 G。

流程 E — “这周有什么新东西?”

调用一次 get_lifecycle_briefing;当用户询问 Shorti 能做什么时,get_started 是首次接触的引导说明。

包文件 — 您的第一个交付物

在工作目录中写入本地文件 shorti-packet-<slug>.md:

# <工作标题>

## 公式(借用自 <演变谱系引用>)
保留 / 改变 / 永不触碰 —— 直接复制自演变谱系卡片,并附上收据。

## 分镜头列表
来自克隆工具包的编号镜头:节拍、时长、景别、动作、音频提示。

## 逐镜头提示
您在拍摄现场会逐一给出的提示(流程 D 的顺序)。

## 评分标准
您将用于评估每日素材的评分标准。

## 证据
演变谱系引用和 observed_metrics —— 仅限事实,无预测。

用恰好一行机器可读的文本结束此步骤:

PACKET_FILE=<绝对路径>

流程 F — 包文件 → 时间线 → mp4(闭环)

包文件是计划;此步骤将其转化为文件。没有媒体素材请不要开始此流程。

  1. 定位媒体。 一次性询问用户片段目录,或使用已存在磁盘上的提供方输出。您编写的每个 src 都必须能够解析到实际文件。

  2. 自行编写时间线。 将包文件的分镜头列表翻译成一个 JSON 文件 —— 由您编写,无需任何工具生成。字段及唯一允许的字段如下:

    {
      "version": "0.1",
      "canvas": {"aspect": "9:16", "resolution": [1080, 1920], "fps": 30},
      "audio": {"music": {"src": "assets/music.mp3", "gain_db": -18}},
      "beats": [
        {
          "id": "hook",
          "role": "hook",
          "t": [0.0, 1.2],
          "shot": {"src": "clips/01.mp4", "in": 3.4, "framing": "close"},
          "text": {"content": "wait for it", "pos": "center"},
          "cue": "冷开场直接展示亮点,不要出现标志"
        }
      ],
      "subtitles": {"mode": "none"},
      "provenance": {"packet": "shorti-packet-<slug>.md"}
    }
    

    beats[].t 是绝对时间(秒),已排序,且不重叠。role 是 hook | development | payoff | cta | other 之一。必填字段:version、canvas、beats,以及每个节拍的 t + shot。其他所有字段均为可选 —— 不知道的就省略,不要发明。在 provenance 中包含包文件名。工作示例:examples/*.json。

  3. viralprinter validate <timeline.json> —— 修复时间线中的每个错误。绝不要绕过验证错误;它在告诉您该计划无法渲染。

  4. viralprinter compose <timeline.json> -o out.mp4 —— 如果渲染时间较长或媒体不熟悉,请先使用 --dry-run。

  5. 用自然语言报告您构建的内容,然后输出恰好一行机器可读的文本:

    VIDEO_FILE=<绝对路径>
    
  6. 提供评分,或者如果用户要求完成一个短视频,则直接运行评分:viralprinter grade out.mp4 --markdown,然后按照流程 G 的报告规则处理。

流程 G — “给这个短视频评分”(无需 Shorti 账号)

适用于用户指向的任何文件,包括任何 AI 视频生成器的原始输出,也适用于尚未渲染任何帧的时间线 JSON。

  1. viralprinter grade <file.mp4 | timeline.json> --markdown(当由机器消费时使用 --json)。
  2. 报告评分卡。没有总体分数 —— 评分卡本身就是结果。 不要计算平均值,不要发明分数,不要对视频进行排名。
  3. 读出 not_measured 行及其原因。一个视频无法暴露自身的节拍角色,因此某些分类仅在时间线模式下可测量;这个差距是诚实的答案,而非失败。
  4. 说明各个波段是什么:粗略、精炼、provenance: provisional。它们描述了在已分析片段中反复出现的结构。它们不承诺性能,并且 out_of_band 行是一个需要回答的问题,而非缺陷。
  5. 然后要发挥作用 —— 指出影响最大的一个结构变化,如果用户希望应用该变化,则进入流程 F。

失败处理协议

  • OAuth 未完成 → 用一句话告诉用户完成浏览器流程,然后重试一次。
  • 需要引用的工具在冷状态(缺少 trend_ref 等)下被调用 → 您跳过了某一步骤;回退一个调用步骤,而不是盲目重试。
  • 持续传输错误 → 逐字报告最后一个错误并停止。
  • viralprinter 或 ffmpeg 未找到 → 报告缺失的二进制文件及安装命令。切勿模拟渲染。
  • Compose 失败 → 错误信息包含 ffmpeg 的 stderr 尾部。直接引用它,然后修复时间线。不要手动运行 ffmpeg 来绕过 composer。
  • 验证错误 → 修复时间线并重新验证。绝不要将无效的时间线传递给 compose。

相关技能