ming-xwolf/create-template-video-zh

建立模板影片（中文版）

把一條中文內容做成豎屏（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 裡補一行。