剪映編輯器技能 (JianYing Editor Skill) 是做什麼的?
當用戶想要自動化影片編輯、產生草稿或操作剪映 Pro 中的媒體素材時,使用此技能。
Agent 執行手冊:docs/agent-playbook.md
最小指令 SOP:docs/minimal-command-sop.md
自然語言使用指南:usage.md
草稿檢查器 CLI:
python <SKILL_ROOT>/scripts/draft_inspector.py list --limit 20
python <SKILL_ROOT>/scripts/draft_inspector.py summary --name "DraftName"
python <SKILL_ROOT>/scripts/draft_inspector.py show --name "DraftName" --kind content --json
對於一般編輯請求,請始終遵循該手冊中的「快速編輯執行範本」和「驗收檢查清單」。
🚨 重要開發原則 (CRITICAL DEVELOPER RULES)
- 腳本位置:禁止在 Skill 內部目錄建立剪輯腳本。所有的剪輯邏輯實作程式碼(
.py腳本)必須存放在使用者目前專案的根目錄(或子目錄,如scripts/),以保持 Skill 庫的純淨和可移植性。 - 版本與架構:
- 雙平台適配:已全面支援 MacOS (路徑探測/錄影) 與 Windows。
- Auto-healing:支援 v5.9+ (
draft_info.json)。若草稿損壞或版本衝突,使用overwrite=True初始化JyProject可觸發自動修復。
- 配樂選擇:
- 簡單示範使用預設音樂。實際專案,應優先檢索並推薦
data/cloud_music_library.csv中的相關曲目,或根據影片主題(如「科技」、「溫暖」)進行關鍵字過濾。 - 詢問使用者:「我發現了幾首符合主題的雲端音樂,要不要試試看?(如:
Illuminate- 科技感)」。
- 簡單示範使用預設音樂。實際專案,應優先檢索並推薦
📜 規則指南 (Rules)
請閱讀各個規則檔案以了解特定任務和限制:
- rules/setup.md - 強制性所有腳本的初始化程式碼。
- rules/core.md - 核心操作:儲存、匯出與草稿管理。
- rules/cli.md - CLI 合約與機器可讀輸出規範。
- rules/media.md - 匯入素材與 AI 影片分析最佳化 (30m/360p)。
- rules/text.md - 加入字幕、文字與標題。
- rules/keyframes.md - 進階:加入關鍵影格動畫。
- rules/effects.md - 搜尋與套用濾鏡、特效與轉場。
- rules/recording.md - 新增:螢幕錄製與智慧變焦自動化。
- rules/web-vfx.md - 進階:網頁轉影片生成。
- rules/generative.md - 生成式編輯的思考鏈。
- rules/audio-voice.md - 新增:TTS 旁白與背景音樂來源。
🎯 Agent 快速路由
- 雲端影片 + 雲端音樂:
rules/media.md+rules/audio-voice.md->examples/cloud_video_music_tts_demo.py - 智慧配音與字幕 (Script-to-Video):
rules/text.md+rules/audio-voice.md-> 核心 APIadd_narrated_subtitles - 旁白與字幕對齊:
rules/text.md+rules/audio-voice.md->examples/cloud_video_music_tts_demo.py - 錄影與智慧變焦:
rules/recording.md->tools/recording/recorder.py - 批次匯出/無頭匯出:
rules/core.md+rules/cli.md->examples/robust_auto_export.py - 影視解說生成:
rules/generative.md->scripts/movie_commentary_builder.py
📖 經典範例 (Examples)
參考以下範例以了解完整工作流程:
- examples/my_first_vlog.py - 一個完整的 vlog 建立示範,包含背景音樂與動畫文字。
- examples/simple_clip_demo.py - 關於基本剪輯與軌道管理的快速入門教學。
- examples/compound_clip_demo.py - 新增:專業巢狀專案(複合片段)自動化。
- examples/cloud_video_music_tts_demo.py - 雲端影片 + 雲端背景音樂 + TTS/字幕對齊。
- examples/web_to_video_intro_demo.py - 網頁轉影片示範(HTML 動畫 -> 時間軸片段)。
- examples/robust_auto_export.py - 穩定匯出工作流程與故障處理。
- examples/auto_exposure_align_demo.py - 電腦視覺輔助的曝光對齊工作流程。
- examples/video_transcribe_and_match.py - 進階:AI 驅動工作流程(影片轉錄 -> 透過 AI 語義匹配 B-Roll -> 組合草稿)。
🧠 提示詞與整合工具 (Prompts & Integrated Tools)
對於複雜任務,請使用這些範本與腳本:
- 素材搜尋:以中文/英文名稱尋找濾鏡、轉場與動畫:
python <SKILL_ROOT>/scripts/asset_search.py "復古" -c filters - 電影解說生成器:從分鏡 JSON 產生 60 秒解說影片:
python <SKILL_ROOT>/scripts/movie_commentary_builder.py --video "video.mp4" --json "storyboard.json" - 同步原生素材:從剪映 App 匯入您收藏/播放過的背景音樂/樣式到 Skill:
python <SKILL_ROOT>/scripts/sync_jy_assets.py # 從現有草稿索引雲端素材 python <SKILL_ROOT>/scripts/build_cloud_music_library.py python <SKILL_ROOT>/scripts/build_cloud_text_styles_library.py - README 轉教學影片:將專案的 README.md 轉換為完整的安裝教學影片腳本:
- 閱讀提示:
prompts/readme_to_tutorial.md - 將內容注入
{{README_CONTENT}}變數
- 閱讀提示:
- 螢幕錄製器與智慧變焦:錄製螢幕並自動套用變焦關鍵影格:
python <SKILL_ROOT>/tools/recording/recorder.py # 網頁預覽擷取 (高效能) python <SKILL_ROOT>/scripts/web_recorder.py --url "http://localhost:3000" --duration 5 # 或對現有影片套用變焦: python <SKILL_ROOT>/scripts/jy_wrapper.py apply-zoom --name "Project" --video "v.mp4" --json "e.json" - 草稿檢查器:檢查草稿結構與元資料(支援 v5.9+):
python <SKILL_ROOT>/scripts/draft_inspector.py list --limit 20 python <SKILL_ROOT>/scripts/draft_inspector.py summary --name "DraftName" - 自動匯出器:無頭匯出草稿為 MP4/SRT:
注意:MP4 自動匯出使用 Windows UI Automation。在 macOS 上,請產生草稿並從剪映手動匯出。python <SKILL_ROOT>/scripts/auto_exporter.py "DraftName" "output.mp4" --res 1080 --fps 60 # 僅匯出 SRT: python <SKILL_ROOT>/scripts/jy_wrapper.py export-srt --name "DraftName" - 範本複製與取代器:安全複製範本並批次取代素材(防止損壞原範本):
# 複製範本產生新專案 python <SKILL_ROOT>/scripts/jy_wrapper.py clone --template "飯店範本" --name "客戶A_副本" - API 驗證器:執行環境的快速診斷:
python <SKILL_ROOT>/scripts/api_validator.py
🚀 快速開始範例
import os
import sys
# 1. 環境初始化 (必須同步到腳本開頭,支援 Win/Mac)
current_dir = os.path.dirname(os.path.abspath(__file__))
env_root = os.getenv("JY_SKILL_ROOT", "").strip()
# 探測 Skill 路徑 (支援 Antigravity, Trae, Claude 等)
skill_root = next((p for p in [
env_root,
os.path.join(current_dir, ".agents", "skills", "jianying-editor"),
os.path.join(current_dir, ".agent", "skills", "jianying-editor"),
os.path.join(current_dir, ".trae", "skills", "jianying-editor"),
os.path.join(current_dir, ".claude", "skills", "jianying-editor"),
os.path.join(current_dir, "skills", "jianying-editor"),
os.path.abspath(".agents/skills/jianying-editor"),
os.path.abspath(".agent/skills/jianying-editor"),
os.path.abspath(".trae/skills/jianying-editor"),
os.path.abspath(".claude/skills/jianying-editor"),
os.path.abspath("skills/jianying-editor"),
os.path.dirname(current_dir)
] if p and os.path.exists(os.path.join(p, "scripts", "jy_wrapper.py"))), None)
if not skill_root: raise ImportError("Could not find jianying-editor skill root.")
sys.path.insert(0, os.path.join(skill_root, "scripts"))
from jy_wrapper import JyProject
if __name__ == "__main__":
# 2. 初始化專案 (支援 v5.9+ 及自修復)
project = JyProject("New AI Video", overwrite=True)
assets_dir = os.path.join(skill_root, "assets")
# 3. 智慧配音與字幕 (一鍵 Script-to-Video)
project.add_narrated_subtitles(
text="歡迎使用剪映自動化 Skill。這是一個全面適配 MacOS 的進階版本。",
speaker="zh_female_xiaopengyou"
)
# 4. 導入額外素材
project.add_media_safe(os.path.join(assets_dir, "video.mp4"), "0s")
project.add_media_safe(os.path.join(assets_dir, "audio.mp3"), "0s", track_name="Audio")
# 5. 添加帶動畫的標題
project.add_text_simple("剪映自動化開啟", start_time="1s", duration="3s", anim_in="復古打字機")
project.save()
🛠️ 初始化與專案規範 (Initialization & Project Rules)
在初始化 JyProject 時,請務必根據主影片素材的比例設定解析度。預設值為橫屏 (1920x1080)。
🚨 腳本存放位置規範
禁止在 Skill 安裝目錄下建立你的業務剪輯腳本。
- 正確做法:將你的剪輯 Python 腳本放在專案的根目錄。
- 原因:Skill 目錄應該只包含工具集原始碼,便於後續
git pull升級。業務程式碼混入會導致版本管理混亂。