create-template-video-zh

Create Template Video（中文版）

把一条中文内容做成竖屏（9:16）或横屏（16:9）短视频。设计/动效全部由 templates/ 里的 HyperFrames 模板负责，你只负责写文字槽位和 script.json。

本机安装信息（DSH 环境，务必先读）

• PROJECT_DIR = /Users/ming/.agents/skills/create-template-video-zh （skill 本体 + 流水线 + 模板；node_modules 软链到越南语版，依赖共用）

• 目录结构：SKILL.md、templates/（17 个模板 + CATALOG.md）、 src/（CLI/流水线）、package.json、.env（中文 TTS 端点）。

• 工具映射：原文用 Claude Code 工具名，这里对应 DSH： WebFetch → web_fetch，Read → read，Write → write，Bash → bash。

• 环境依赖：ffmpeg/ffprobe ✓、Chrome ✓、Node ✓。

• 中文 TTS 已本机部署：OmniVoice（MPS）+ 普通话克隆音色 voice-zh.pt， 跑在 8124 端口（越南语版固定用 8123，两版互不干扰）：

  bash "$HOME/.agents/skills/create-template-video-zh/scripts/start-tts-zh.sh"
  

  脚本会检查 /health、后台拉起服务并等到就绪（约 4 s），日志在 /tmp/omnivoice-zh.log。起来后先用中文探针确认：

  curl -s -X POST http://127.0.0.1:8124/tts -H 'Content-Type: application/json' \
    -d '{"text":"大家好，这是中文配音测试。"}' -o /tmp/zh-probe.mp3 && ls -l /tmp/zh-probe.mp3
  

  000/连不上 = 没启动；起不来就停下告诉用户，不要伪造音频。 服务目录与部署笔记：/Users/ming/Documents/dsh_workspace/omnivoice（SETUP.md）。

• 首次渲染会由 npx -y [email protected] 下载 HyperFrames（需联网， 每个 scene 约 15–20s；8–10 个 scene 合计 3–5 分钟）。

• 语言：全片中文。屏幕文案可中英混排（AI、GPT、Apple 保留原文）， 但 voiceText 必须是中文，数字按下面的规则写成汉字。

Input

1 个参数：新闻 URL（http:///https://）或 .txt 文件路径。

Workflow（严格按顺序）

Step 1–3：取内容 + 建输出目录

• URL → web_fetch 抓正文，抽出 title、content（正文 800–2000 字）、 ogImage（og:image 或 null）、domain。 失败（付费墙/纯 JS/4xx）→ 让用户把正文存成 .txt 再跑，然后停止。
• .txt → read 读取；title = 第一行（≤40 字），content = 余下正文， ogImage = null，domain = "local"。
• slug：优先用英文或拼音关键词（≤40 字符，[a-z0-9-]），例如 xiaomi-17-price、ai-coding-jobs。纯中文标题无法直接转 ASCII 时由你写拼音； 实在没有就用 zh-video（代码里也有同名回退）。 timestamp = YYYYMMDD-HHmm； outputDir = <当前工作区>/videos/<slug>-<timestamp>/ —— 放工作区内： 交付方便，也不会污染技能目录（DSH 沙箱通常只允许写工作区）。mkdir -p。 音效库位置由 .env 的 SFX_DIR 指向技能内 assets/sfx，与输出目录解耦； 音效库为空时该层自动跳过，不影响主流程。

Step 4：读模板目录

读 PROJECT_DIR/templates/CATALOG.md，确认模板与槽位。 只能使用 CATALOG 里的 templateId。 现有：

HOOK（只用这一个）： frame-liquid-bg-hero —— aurora 光斑 + 大标题 + CTA。

BODY（按内容自选，见 Step 5）：

• frame-vignelli —— 1 个数字，暗炭底 + 红。
• frame-pentagram-stat —— 1 个数字/基准，暗底霓虹（瑞士网格、橙色发光数字 + 青色点缀 + 柱状图）。
• frame-bold-poster —— 多行强声明 + 大字数字。
• frame-build-minimal —— 短促金句，暗底 + 一个超大加粗词（橙色 glow，逐字出现）。
• frame-creative-voltage —— 创意标语，电光蓝分割 + 手写体。
• frame-glitch-title —— cyberpunk RGB 错位故障（噪点底），适合突发/科技。
• frame-aicoding-list —— 清单 2–5 条（每条 icon + 等级标签），暗色渐变底。
• frame-aicoding-comparison —— A vs B 对比（两个渐变卡片 + WIN 徽章 + 数据）。
• vfx-text-cursor —— 故障字 + 闪烁光标，适合一句强观点/引言（可高亮一个词）。
• frame-light-leak-cinema —— 电影光晕 + 胶片噪点 + 衬线标题，适合情绪化片头/章节卡。
• frame-bold-signal —— 章节/段位卡，暗底 + 橙色大卡 + 大号章节号 + 面包屑导航。
• frame-data-chart-nyt —— 折线图，纸底 NYT 风，用 data[{label,value}] 实时画曲线，末段可用红虚线标拐点。
• frame-decision-tree —— 判断树，一个问题 + 两条分支 + 两张结论卡，讲「要不要/选哪个」最好用。
• frame-swiss-grid —— 瑞士网格，纸底 + 大标题 + 三条数字，适合「一个判断 + 三个数」的结论页。

OUTRO： frame-logo-outro（默认：logo glow + 品牌 + tagline + url）； frame-statement-outro（替代：纸底红卡）。

17 个模板内置的示例值（data-composition-variables）已全部换成中文样例， 可以直接在预览里看到成片效果，也可以照抄进 script.json 改。 但渲染时请显式传 inputs：不传参时运行时拿不到变量，文字会是空的。

17 个模板都有 9:16 与 16:9 两版（compositions/portrait.html 与 index.html）， 由 script.json 顶层的 aspect 决定全片用哪一版；方图（1:1）暂未提供。

Step 5：生成 script.json

{
    "version": "1.0",
    "renderer": "hyperframes",
    "aspect": "9:16",   /* 或 "16:9"；两种比例各模板都有对应版式 */
    "metadata": {
        "title": "...",
        "source": { "url": "...", "domain": "...", "image": null },
        "channel": "中文频道名"
    },
    "voice": { "provider": "omnivoice", "speed": 1.0 },
    "scenes": [
        /* 8–12 个 scene：1 hook + 6–10 body + 1 outro */
    ]
}

• provider 固定 omnivoice（本地 TTS，无需 voiceId/API key）。
• 每个 scene：{ id, type, voiceText, templateId, inputs }；inputs 必须覆盖 CATALOG 中该模板的必填槽位。
• scenes[0].type = "hook"；scenes[-1].type = "outro"（frame-logo-outro）。
• 8–12 个 scene；voiceText 合计约 350–450 字（≈90–120s，中文语速约 4.5 字/秒；最终时长以配音为准，流水线按配音对齐）。每个 body scene 30–45 字、只讲一个点；一个段落有两个点就拆成两个 scene。 目标：每个 scene 停留 6–10s。

内容 → 模板映射：

• hook → 固定 frame-liquid-bg-hero（槽位：kicker, headline, subheadline, cta, brand）。headline 默认黄→紫渐变，可用 headline_from/headline_to （两个 hex）改色调。
• body → 由你按内容挑最合适的模板，并且尽量多样，不要所有 body 用同一个：
  • frame-vignelli：场景有 1 个要强调的数字（kicker, number, label, note, brand）。
  • frame-pentagram-stat：有 1 个基准/百分比数字 + 柱状图感 （label, headline=数字, subtitle, anchor, footer_left, footer_right）。
  • frame-build-minimal：短金句/一个关键词（eyebrow, hero=单个词, desc, side_left, side_right）。
  • frame-bold-poster：多行强声明 + 大数字（kicker, date, figure, headline[], standfirst, footer_left, footer_right）。headline 第 2 行自动变红。
  • frame-creative-voltage：创意口号（meta, display_lines, accent_index, script, caption）。
  • frame-glitch-title：突发/科技/惊悚感（title, subtitle）。
  • frame-aicoding-list：清单/对比 2–5 条（title, accent, accent_from, accent_to, subtitle, items[]）。每条 {icon, title, desc, tag, level}：icon 由你挑 emoji （🚫 ⚠️ ✅ ❌ 📈 💡 🔒 🚀 …）；level ∈ danger|warn|good|info 决定颜色； tag 用中文短标签（高危 / 注意 / 利好 / 稳健）；accent_from/accent_to 由你挑两个 hex。
  • frame-aicoding-comparison：正好对比两样（badge, pre, vs, post, left{}, right{}）。 每边 {label, from, to, icon?, bullets[], stat?, stat_label?, win?}； from/to 是渐变两色 hex（两边冷暖对照更好）；win: true 标出胜者。
  • vfx-text-cursor：一句强观点/引言，故障字 + 光标（line1, line2, line3, accent, byline, header_* , footer_*）。accent 是 line2 里要高亮的词。
  • frame-light-leak-cinema：情绪化片头/章节卡，电影光晕 + 衬线标题 （kicker, title_line1, title_line2, subtitle, header_, footer_）。
  • frame-bold-signal：章节分隔/强声明（section, nav[], card_label, title, footer）。
  • frame-data-chart-nyt：讲趋势/增长时用，折线图（kicker, title, highlight, subtitle, data[{label,value}], unit, accent_tail, source_*）。
  • frame-decision-tree：讲「要不要/选哪个」（kicker, question, yes{label,tag,title,desc}, no{...}, footer_*）。分支只有两条。
  • frame-swiss-grid：结论页，一个判断 + 三个数（label, title, subtitle, stats[{value,label}], accent_index, footer_*）。
  • 节奏建议：数字场景多时，frame-vignelli（炭黑+红/黄）与 frame-pentagram-stat（暗霓虹橙/青）交替；非数字场景用 frame-build-minimal。
• outro → frame-logo-outro（brand_name, tagline, primary_url）。

画幅（aspect，全片一致）：

• "9:16"（默认，抖音/视频号/Shorts）→ 每个模板渲染 compositions/portrait.html。
• "16:9"（B 站/YouTube/横屏内嵌）→ 渲染 index.html（模板的横屏版）。
• "1:1"（信息流方图）→ 需要 compositions/square.html；目前 17 个模板都还没有方版， 选 1:1 会回退到 16:9 并打 WARN，画面比例会不对——要方图就先补 square.html。
• 两种比例共用同一套槽位名，文案可以原样复用；差别只在行宽： 16:9 一行可以放到 20–24 字，9:16 仍是 10–14 字。
• 配音、时长、拼接逻辑与比例无关。

中文排版规则（屏幕文案 inputs）

• 中文比英文/越南语更"占地"：一行控制在 10–14 个汉字（16:9 横屏可放宽到 20–24 字），超过就换行或砍字； headline 最多 3 行。宁可少两个字，不要挤成两行半。
• 模板字体是 Inter Tight + system-ui，中文会回退到苹方（PingFang SC）， 一般正常；若渲染出来是方块/豆腐块，在该模板的 compositions/portrait.html 的 font-family 最前面插入 "PingFang SC", "Noto Sans SC", 再重渲染。
• 中文不需要词间空格；不要在中文里手动加 letter-spacing 负值，模板自带的 -3px 对汉字会粘连，遇到标题发挤就在该类上覆盖 letter-spacing: -1px。
• 屏幕文字允许 emoji，但每个字段 0–1 个，别塞进逐字弹出的字段 （如 frame-build-minimal 的 hero），否则动画会碎。
• 数字在屏幕上保留好看格式（4499 元、82.7%、17），只有在 voiceText 里才转汉字。

中文 TTS 规则（voiceText 强制遵守）

OmniVoice 逐字朗读，阿拉伯数字、小数点、货币符号经常读错或读成英文。 因此 voiceText 里把所有数字写成汉字；inputs（屏幕文字）保留数字。

形式	错误示范	正确写法
小数	82.7%	百分之八十二点七
版本号	iOS 18.2	iOS 十八点二
产品型号	小米 17	小米十七
像素	200MP	两百万像素
电量	5000mAh	五千毫安时
数量级	1M tokens	一百万 token
人民币	¥4499	四千四百九十九元
美元	$5	五美元
倍数	2x	两倍
百分比	30%	百分之三十
时长	60s	六十秒
比率	3:1	三比一
年份	2026 年	二零二六年
万亿	21 万亿	二十一万亿
排名	Top 3	前三名

• 英文缩写先探针再决定：AI、GPT、API、5G、GPU 在中文 TTS 里 有时被逐字母读出（"A-I"），有时读英文词。写进全片前，先用探针同时念两句对比： AI 很强大 vs 人工智能很强大，选听感自然的写法，全篇统一。
• 品牌名保留原文（Apple、OpenAI、小米），中文品牌直接写中文。
• voiceText 绝对禁止：emoji/图标、URL、以及 & % $ # + = / 等符号； 句末用 。 或 ？ 让停顿自然；逗号用 ，。
• 数字统一用"两"还是"二"：口语量词用"两"（两千、两万、两倍）， 序数/年份用"二"（二零二六年、第二季度）。

Step 6：自检

• scenes[0] 是 hook，最后一个是 outro；每个 templateId 都在 CATALOG 内； 每个 inputs 覆盖必填槽位；
• 中文行宽 ≤14 字、headline ≤3 行；voiceText 里没有阿拉伯数字/符号/emoji； emoji 只出现在 inputs；全片用词与缩写读法一致；
• voiceText 合计 350–450 字。静默修正最多 2 轮。

Step 7：写 script.json

用 write 工具写到 <outputDir>/script.json（先 mkdir -p 输出目录）。

Step 8：跑流水线

先启动中文 TTS（见开头）并确认探针有音频，然后前台执行：

cd "$HOME/.agents/skills/create-template-video-zh" && npm run pipeline -- "<outputDir>/script.json"

CLI 按 renderer: "hyperframes" 走模板流水线：TTS → 逐模板渲染 → 按配音时长 对齐 → 拼接 + 混音。失败要明确报错并给出 outputDir 路径（已渲染的 voice/scene-*.mp3、clips/scene-*.mp4 会被复用，删掉即可重渲染）。

改中文文案后重跑时，先删对应的 voice/scene-*.mp3，否则会复用旧配音。

Step 9：交付

把三个成品复制到会话工作区，方便用户直接打开：

mkdir -p "<cwd>/videos/<slug>" && cp "<outputDir>"/{video.mp4,voice.mp3,script.txt} "<cwd>/videos/<slug>/"

然后报告（用可点击链接）：

✓ Video: videos/<slug>/video.mp4
✓ Audio: videos/<slug>/voice.mp3 — 给剪映（自动字幕/对口型）
✓ Script: videos/<slug>/script.txt — 分镜文本，方便手改
总时长: XX.Xs

备注

• 每个 scene 渲染约 15–20s（Chromium）；8–10 scene 约 3–5 分钟。
• TTS 幂等（保留 voice/scene-*.mp3），切片也幂等（保留 clips/scene-*.mp4）。
• 中文 TTS 在 M2 Max 上 RTF（实时率）约 2.8：1 分钟成片约 3 分钟纯 TTS。 想快就把服务端 OMNIVOICE_STEPS 设成 16（质量略降、耗时减半）再重启。
• assets/sfx 为空时音效为 0 层、不影响主流程；需要音效跑 npm run sfx:download（需联网）后再生成（默认下到技能内 assets/sfx/， 即 .env 里 SFX_DIR 指向的位置）。语义关键词已加中文 （警告/失败/纪录/首次/倒计时/史诗/悬念…）。
• 与越南语版 create-template-video 的差异：TTS 端口 8124 + 中文音色、 中文数字读法表、中文排版约束、中文 SFX 关键词、zh-video slug 回退。 代码是独立副本（只有 node_modules 软链到越南语版）；改模板/流水线 只影响本目录。若删掉越南语版，记得 npm ci 重建依赖。
• 新增模板：按 templates/CATALOG.md 末节说明做，然后在 CATALOG 里补一行。