Mr-funny/hbg-classical-poem-silk-video

Agent Skill for turning Chinese classical poems into vertical Chinese-art videos with ImageGen stills, Docker I2V, calligraphy captions, retained ambience, BGM and final MP4 QA.

是什麼

hbg‑classical‑poem‑silk‑video 是一個 Agent Skill（AI 編碼代理如 Codex 或 Claude Code 的外掛程式），可將中文古典詩轉換為垂直格式（1080 × 1920）的「絲絹影片」——一種短時、高品質的中國畫風格動畫。該技能解析詩歌，拆分成場景，使用內建 ImageGen 模型生成靜態中國畫幀，將這些幀輸入基於 Gemini 的 圖像→影片（I2V）Docker 容器，添加運動提示（水波紋、飛鳥、馬蹄聲等），疊加毛筆字幕，混合原始模型生成的環境音與可選背景音樂，並最終生成經過 QA 檢查的 MP4。

如何取得

倉儲內附帶一個 install.sh 腳本，可直接在命令列執行。該腳本會偵測使用者的代理（Codex 或 Claude Code），並將技能檔案複製到代理的全域 skills 目錄（預設 ~/.codex/skills/classical-poem-silk-video）。範例單行指令：

curl -fsSL https://raw.githubusercontent.com/Mr-funny/hbg-classical-poem-silk-video/main/install.sh | sh

您也可以手動克隆倉儲，並將 skill/classical-poem-silk-video 資料夾複製到相應位置。

如何執行該技能

安裝後，用自然語言與您的代理對話，例如：

使用 $classical-poem-silk-video 制作《楓橋夜泊》。
四句詩一行一景，畫面色調隨詩意變化；鏡頭固定，
讓月光、水紋、烏鴉、霜霧和漁火在畫中自然運動。
保留 AI 環境原聲，毛筆字逐字出現，場景之間自然交叉溶解。

代理將執行以下步驟：

解析詩歌（識別時代、季節、意象、情感弧線）。
分鏡 —— 短詩每行一景，長詩每兩行一景。
選擇中國畫風格（水墨、工筆、青綠、騎馬等），根據詩歌情緒決定。
生成靜態幀，使用內建 ImageGen 模型，並為垂直毛筆字幕預留安全區域。
呼叫 Gemini I2V Docker 容器（gemini-flow-suite）對幀進行動畫處理，使用精心設計的運動提示，固定鏡頭，僅移動目標物件。
添加字幕，使用 Ma Shan Zheng 毛筆字體（先右列後左列）。
混合音訊 —— 保留模型生成的環境音，可選疊加背景音樂。
交叉淡入淡出過渡（影片與音訊均適用），並執行最終 QA 腳本，檢查黑幀、音訊斷點、幀數是否正確、視覺一致性（如無多餘飛鳥、畸形馬腿等）。

最終結果為一個 1080 × 1920、30 fps、H.264 + AAC 的 MP4，可直接分享。

關鍵技術組件

組件	功能
詩歌解析器	提取時代、地點、季節、意象、動作和情感曲線。
分鏡引擎	分組詩句（≤4行 → 一行一景；更長 → 兩行一景）。
風格選擇器	在水墨、工筆、青綠、騎馬等風格間切換，保持統一的中國畫基因。
靜態幀生成器	呼叫代理內建的 `ImageGen` 模型；為垂直字幕預留安全區域。
Docker I2V	運行 Gemini Flow Suite 容器（`gemini-flow-suite`），將幀轉為帶可控局部運動的短影片片段。
運動提示模板	四段式提示（固定錨點、局部運動區、穩定結尾、防幻覺規則），防止畫作被意外「重寫」。
字幕渲染器	使用 SIL‑OFL Ma Shan Zheng 毛筆字體，垂直雙列佈局，逐字顯現。
音訊混音器	保留模型生成的環境音，可選疊加使用者提供的 BGM，並與交叉淡入淡出同步。
最終 QA 腳本	使用 `ffprobe`、`ffmpeg` 濾鏡（`blackdetect`、`silencedetect`、`volumedetect`）和可選時間戳 TSV，驗證運動一致性、幀完整性與編碼規格。

適合誰使用

希望生成 AI 生成、文化上真實可信的短影片用於社群媒體（微博、抖音、B站）的 內容創作者。
尋找古典詩歌動畫插圖的 教育工作者。
需要現成技能展示多模態生成（文字 → 圖像 → 影片 → 音訊）的 AI 代理開發者。
對可控圖像→影片生成提示工程感興趣的 研究人員。

許可與合規

所有腳本、技能定義和文件均在 MIT 許可證 下發布。
內建 Ma Shan Zheng 字型遵循 SIL 開放字型許可證 1.1。
該技能明確不處理任何密鑰、Cookie 或使用者提供的媒體；僅操作使用者提供的詩歌文字和可選 BGM。

快速入門檢查清單

使用上述單行命令安裝技能。
確保 Docker 正在執行，且 gemini-flow-suite 鏡像可用（請參考其 README）。
執行 skill/classical-poem-silk-video/scripts/check_prerequisites.sh 驗證環境。
讓您的代理為任意詩歌生成影片。
生成 MP4 後，可選執行 final_media_qa.sh 確認品質。

範例輸出

倉儲包含《錢塘湖春行》（8行 → 4場景）的完整範例。最終影片（約32秒，1080 × 1920）可在 Releases 頁面取得，並在 docs/article.md 中討論。