WeChat Article Video

把微信公众号图文文章(或任何图文素材)转换为高质量短视频初稿——解析文章结构、重构为分镜脚本、生成配音、用 HyperFrames 渲染成片。当用户提到"公众号转视频"、 "图文转视频"、"生成短视频初稿"、"HyperFrames"、"批量出片"等场景时使用。本 skill 不依赖任何单一 agent 运行时的专有插件机制(不使用 Claude Code 的 skill 自动加载协议),而是一套可被任意具备"读写文件 + 执行 shell/Python/Node 命令"能力的 agent 直接调用的脚本与说明文档——Claude Code、Codex、Hermes Agent、 OpenClaw 均可按本文档逐步执行。

ToBeWin@tobewin

Install

openclaw skills install @tobewin/wechat-article-video

公众号图文 → 视频流水线

给执行者(任意 agent)的第一句话

你不是在"用某个 IDE 的插件",你是在按顺序运行几个独立脚本。每一步的输入输出都是普通文件(json / html / mp3 / mp4),上一步产物是下一步的输入。无论你是 Claude Code、Codex、Hermes 编排的子任务,还是 OpenClaw 触发的定时流水线,执行方式完全一样:读这份文档 → 依次跑 scripts/ 下的命令 → 检查产物 → 进入下一步。

重要边界声明:这套流水线产出的是"高质量视频初稿"(信息准确、节奏合理、可直接发布或需要极少量微调),不承诺"爆款"——是否爆款还取决于选题、封面、标题、发布时机等流水线控制不了的变量。不要在成片质量不达预期时怀疑流水线本身,而是回到第 2 步(脚本重构)检查分镜设计是否合理。

整体流程(4 步)

text

source bundle / 公众号原文(md/html/粘贴文本)
   │  [Step 1] parse_article.py
   ▼
structured.json  (标题/段落/图片/数据点,保留原始引用)
   │  [Step 2] 见 references/script_planning.md —— 这是决定成片质量的核心环节,
   │           必须先读那份文档再动手写 storyboard.json,不要跳过
   ▼
storyboard.json  (分镜脚本:每个 scene 的类型/旁白/画面提示)
   │  [Step 2.2] plan_creative_direction.py（按文章主题自动选视觉与 TTS）
   ▼
storyboard.directed.json
   │  [Step 3a] tts_generate.py (edge-tts)
   ▼
storyboard.timed.json + audio/*.mp3  (每个 scene 精确时长)
   │  [Step 3b] build_scenes.py
   ▼
scenes/*.html + composition.html  (HyperFrames 场景代码)
   │  [Step 4] render.sh  (npx hyperframes render)
   ▼
output.mp4

Step 1 — 解析原文

bash

python scripts/parse_article.py --input article.md --output structured.json

公众号链接常受平台访问限制，因此链接不是必需输入，也不应作为唯一输入。推荐建立本地 source_bundle/，让用户直接粘贴正文或把手工保存的素材放入目录：

text

source_bundle/
├── article.md | article.html | pasted.md | pasted.txt
├── images/                 # 原文配图、截图
├── assets/                 # 图表、补充素材
├── manifest.json           # 可选：素材用途/图注/关联段落
└── notes.md                # 可选：选题重点、禁用内容

bash

python scripts/parse_article.py --input source_bundle/ --output structured.json

解析结果会保留目录中的图片素材清单和可选 manifest.json，不猜测素材归属；在 Step 2 由分镜明确选择 image_path，避免自动错配。

对于 images/ 与 assets/，由具备视觉能力的 Agent 逐张看图并补全 manifest.json 的素材视觉索引，而不是额外运行 OCR。字段规范与选图规则见 references/asset_planning.md；完成视觉索引后再进入分镜设计。

输入:公众号导出的 Markdown 或 HTML(用户直接粘贴/上传即可,支持两种格式)
输出 structured.json 结构:

json

{
  "title": "文章标题",
  "sections": [
    {"id": "sec01", "heading": "小节标题或null", "text": "正文", "images": ["path/or/url"], "data_points": ["可提炼的具体数字/事实,如有"]}
  ]
}

关键原则:只做结构化提取,不做取舍判断。哪些内容重要、哪些可以砍,是 Step 2 的工作,不要在这一步预先丢信息。

Step 2 — 脚本重构(核心环节,必读 references/script_planning.md)

这一步没有确定性脚本,因为它需要判断力——由执行的 agent(你)基于 references/script_planning.md 里的方法论,把 structured.json 改写为 storyboard.json。方法论文档里有完整的原则、分镜类型定义、JSON schema、以及一份自检清单,写完 storyboard.json 后务必对照清单自查一遍。

产出文件:storyboard.json,schema 见方法论文档。

Step 3a — 生成配音

scripts/tts_generate.py 支持 4 个 provider,通过 --provider 切换,接口约定统一 (输入文本→输出 mp3+真实时长),不影响下游 Step 3b/4:

Provider	定位	情感/风格控制	成本
`mimo`(小米 MiMo-V2.5-TTS)	通用中文,内置精品音色	自然语言风格指令 + 音频标签	限时免费(小米 MiMo 开放平台当前促销,后续可能调整)
`doubao`(字节豆包 Seed-TTS 2.0)	中文情感表现力目前公认最强,能理解"用撒娇的语气"这类指令	自然语言情感描述(`context_texts`)	按量付费(有开通即送的免费额度)
`qwen`(阿里 Qwen3-TTS)	中文+方言(粤语/四川话/河南话等)覆盖最广,指令跟随稳定	`qwen3-tts-instruct-flash` 模型支持自然语言指令	按量付费
`elevenlabs`	英文/多语种效果最强,中文是多语种模型里的一个选项,不专门优化	voice_settings 数值滑块	商业按量付费,免费额度很少
`edge`	严肃、标准的中文信息播报	标准音色与语速控制	免费（依赖 edge-tts）

bash

# 以 mimo 为例(免费,建议先用它跑通整条流水线)
export MIMO_API_KEY=xxx
export MIMO_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1  # Token Plan 专属地址；普通 API 可按控制台替换
python scripts/tts_generate.py --input storyboard.json --output storyboard.timed.json \
  --provider mimo --voice Moli --audio-dir audio/

推荐在生成配音前，让创意方向规划器自动写入主题、布局和 TTS 默认值：

```bash
python scripts/plan_creative_direction.py --structured structured.json \
  --storyboard storyboard.json --output storyboard.directed.json

python scripts/tts_generate.py --input storyboard.directed.json \
  --output storyboard.timed.json --provider auto --audio-dir audio/

当前内置规则：医疗/医药→暖白蓝绿医疗编辑布局 + Edge 正式新闻男声；财经→深蓝金色数据简报 + Edge 正式新闻男声；科技→信号卡片布局 + MiMo 理性解说；生活方式→暖色图片叙事 + MiMo 自然表达。规划器输出是普通 JSON，Agent 可根据真实素材覆盖它的决定。

医药、政务、财经等需要正式播报感的内容

python scripts/tts_generate.py --input storyboard.json --output storyboard.timed.json
--provider edge --voice zh-CN-YunyangNeural --audio-dir audio/

中文情感要求高的正式发布用 doubao 或 qwen

export DASHSCOPE_API_KEY=xxx python scripts/tts_generate.py --input storyboard.json --output storyboard.timed.json
--provider qwen --voice Cherry --audio-dir audio/

text


- **选型建议**:日常/测试用 `mimo`(限时免费,效果够用);正式发布、对情感表现力
  要求高(比如需要"急切""调侃"这种细腻语气)用 `doubao` 或 `qwen`;内容主要面向
  海外/多语种受众才考虑 `elevenlabs`。
- 推荐每个 scene 添加 `voice_direction`，把“怎么说”作为分镜的一部分。`emotion_hint`
  只作为旧格式兼容字段。`voice_direction` 会编译为 mimo/qwen/doubao 的自然语言导演
  提示；Eleven v3 则使用 `audio_tags` 写进台词。Qwen 会自动开启
  `optimize_instructions`。
- 如实告知:除 `mimo` 限时免费外,其余都是按字符/按量计费的商业 API,"完全免费出片"
  这个目标在配音环节要打折扣。想保留零成本路径,把 provider 换成本地部署方案
  (CosyVoice2 / edge-tts 等),接口约定不变。
- 脚本会用 `ffprobe` 读取每段 mp3 的真实时长,写回 `duration_sec` 字段——**这是
  Step 3b 排时间轴的唯一依据**,不要用估算值。
- 各 provider 的具体接口字段(尤其是豆包)迭代较快,`scripts/tts_generate.py` 里
  的实现是按当前公开文档整理的最小可用版本,调用报错时先对照对应厂商的最新 API
  文档核实字段名。

## Step 3b — 生成 HyperFrames 场景

```bash
node scripts/build_scenes.js --input storyboard.timed.json --templates templates/ --output scenes/

Step 2.5 — 离线校验分镜

在调用任何付费 TTS 前先运行：

bash

python scripts/validate_storyboard.py --input storyboard.json --structured structured.json

它会检查重复 ID、未知 scene 类型、无法回查的来源段落、缺少图表数据、文字停留时间及缺失导演提示等问题。

按 storyboard.timed.json 里每个 scene 的类型,套用 templates/ 下对应的 HyperFrames HTML 模板,把 data-start / data-duration 按累积时长自动计算填入, 旁白文本、画面文案、图片路径也一并注入。
输出:scenes/composition.html(HyperFrames 会读取的主文件)+ 各 scene 片段。

Step 4 — 渲染

bash

npx hyperframes render scenes/composition.html --output output.mp4

渲染完成后做一次 QA(见下方 checklist),不要直接交付。

Step 4.5 — 交付前 QA checklist

字幕/旁白与音频是否对轨(抽查开头、中间、结尾各一处)
每个 text card 停留时长是否够读完(中文按约 4–5 字/秒估算阅读速度, 停留时间应略长于"读完所需时间",不要卡着最低值)
总时长是否符合目标平台调性(抖音/视频号短videos 建议 60–90 秒内)
片头 3 秒 hook 是否真的抓人,还是只是"标题重复"(参考方法论文档的自检清单)
数据类内容的数字是否与原文一致(防止 TTS/转写引入错误)

一键生产与交付物

精品模式：Codex 多模态创意导演（必须执行）

在精品任务中，Codex 必须逐张查看将进入成片的图片，然后在 source bundle 内创建 visual_brief.json。这是模型的原生视觉理解，不使用 OCR：只描述实际可见的主体、构图、留白、品牌色、信息密度和适合的镜头重点；不从看不清的图片猜测文字或疗效信息。

每个素材使用 examples/visual_brief.example.json 的结构，至少提供：

path：与 storyboard 的 image_path 一致；
observation：Codex 的可验证视觉观察；
grammar、motion、focus、reason：该图在成片中的视觉任务。

随后 produce_video.py 会把这份视觉简报交给 plan_shots.py，优先采用 Codex 的看图结论；没有该文件才退化为规则。visual-qa-report.json 会明确标记任何未使用视觉简报的镜头。

短视频优先策略（默认、强制）

本 Skill 的产品不是“公众号朗读器”，而是把文章压缩成让人愿意看完的短视频。默认使用 --format short：成片 12–15 秒、2–4 个 scene、总旁白不超过 70 个汉字。

Codex 写分镜时先回答：用户看完后最应该做的一个动作是什么？再只选择能促成该动作的两条信息。长资格清单、完整产品参数、附件目录和背景介绍只在画面或结尾提示“详见原文/附件”，不能逐条念出。只有用户明确要求专题解读时才使用 --format long。

当分镜已准备好时，可用一条命令生成结构化文章、创意方向、镜头语言、真实配音、字幕、MP4 和机器可读 QA 报告：

bash

python scripts/produce_video.py --bundle source_bundle/ --storyboard storyboard.json \
  --output-dir release/ --provider auto --music auto --format short

release/ 会包含 subtitles.srt、subtitles.ass、output.mp4、qa-report.json 和 visual-qa-report.json。 subtitles.ass 使用卡拉 OK 逐字高亮，适用于支持 ASS 的剪辑软件或播放器；成片渲染器还会为图片镜头增加克制的推近、淡入和淡出。若本机 FFmpeg 启用了 libass，ASS 会自动烧录到 output.mp4；否则会保留两个字幕交付文件并正常导出，不会阻断生产。

无论是否安装 libass，一键生产都会额外以原生 PNG 叠加方式把 SRT 烧录为移动端友好字幕：白字、深色半透明圆角底板、固定安全区，不遮挡标题与行动入口。因此最终 output.mp4 始终可直接发布，SRT/ASS 仍保留给平台或后期编辑使用。

背景音乐只混入用户明确有权使用的素材。把主题音乐放到 source_bundle/assets/music/<category>.mp3（例如 medical.mp3）或 default.mp3， --music auto 会按创意分类挑选并以低音量混音；没有素材时自动跳过。也可传 --music none 明确关闭，或传入一个具体音乐文件。

QA 会检查音视频流、1080×1920 竖版规格、时间轴一致性、素材路径与字幕文件；视觉 QA 会额外检查首屏主视觉、文案密度、素材清晰度、短镜头风险，并输出需要人工做最终判断的审美清单。

依赖清单

工具	用途	安装
Python 3.10+	解析/TTS 脚本	系统自带或 pyenv
requests	调用 mimo/doubao/elevenlabs HTTP 接口	`pip install requests --break-system-packages`
dashscope(可选)	provider=qwen 时需要	`pip install dashscope --break-system-packages`
ffmpeg / ffprobe	音频时长探测、后续可能的转码	`apt install ffmpeg`
Node.js 22+	运行 build_scenes.js、驱动 hyperframes	nvm 或系统包管理器
hyperframes	HTML→MP4 渲染引擎	`npx hyperframes`(免安装,首次运行自动拉取)

TTS 至少需要以下之一的 API Key:MIMO_API_KEY(小米 MiMo,限时免费)/ DASHSCOPE_API_KEY(阿里 Qwen)/ DOUBAO_TTS_APP_ID+DOUBAO_TTS_ACCESS_KEY(火山引擎)/ ELEVENLABS_API_KEY(ElevenLabs)。

目录结构

text

wechat2video-skill/
├── SKILL.md                      # 本文件
├── references/
│   └── script_planning.md        # Step 2 方法论(核心,必读)
├── scripts/
│   ├── parse_article.py
│   ├── tts_generate.py
│   └── build_scenes.js
├── templates/
│   ├── scene_hook.html
│   ├── scene_textcard.html
│   ├── scene_chart.html
│   ├── scene_quote.html
│   └── scene_outro.html
└── examples/
    └── sample_run.md             # 一次端到端示例

WeChat Article Video

Install

公众号图文 → 视频 流水线

给执行者(任意 agent)的第一句话

整体流程(4 步)

Step 1 — 解析原文

Step 2 — 脚本重构(核心环节,必读 references/script_planning.md)

Step 3a — 生成配音

医药、政务、财经等需要正式播报感的内容

中文情感要求高的正式发布用 doubao 或 qwen

Step 2.5 — 离线校验分镜

Step 4 — 渲染

Step 4.5 — 交付前 QA checklist

一键生产与交付物

精品模式：Codex 多模态创意导演（必须执行）

短视频优先策略（默认、强制）

依赖清单

目录结构

公众号图文 → 视频流水线