AutoCliper.AI — Agent 技能
將一部長篇 YouTube 影片轉換為 5 到 15 個帶有繁體中文包裝和硬字幕的短剪輯。
本文件是任何執行 AutoCliper 管道的 AI Agent 的單一事實來源。請依序遵循每個編號步驟。不要跳過步驟。不要猜測檔案名稱 — 每次寫入操作後檢查檔案系統。
0. 前置檢查
在進行任何其他操作之前,請驗證環境。如果任何檢查失敗,請報告確切的阻礙因素並停止。
| 檢查項目 | 指令 | 通過條件 |
|---|---|---|
| 已安裝 yt-dlp | which yt-dlp | 回傳路徑 |
| 已安裝 ffmpeg | which ffmpeg | 回傳路徑;若缺少,請嘗試 python3 -c "import imageio_ffmpeg; print(imageio_ffmpeg.get_ffmpeg_exe())" |
| Python 3.9+ | python3 --version | 大於等於 3.9 |
| 技能儲存庫可用 | 檢查相對於技能根目錄是否存在 corekit/ 目錄 | 存在 corekit/__init__.py |
為後續所有指令設定環境變數:
export PYTHONPATH="<AutoCliper.AI-repo 的路徑>"
下面所有的 python3 -m corekit.* 指令都假設已設定此 PYTHONPATH。
1. 建立工作區
為此影片建立輸出目錄結構。從影片標題或 ID 衍生出 <slug> — 使用小寫、連字號、無空格、無特殊字元。
mkdir -p "studio/<slug>/intake"
mkdir -p "studio/<slug>/intel"
mkdir -p "studio/<slug>/exports"
預期結果:
studio/<slug>/
├── intake/ ← 原始影片與字幕存放於此
├── intel/ ← 分析產出檔案存放於此
└── exports/ ← 每個剪輯的資料夾存放於此
2. 取得來源素材
從 YouTube 下載影片和字幕:
python3 -m corekit.fetch_source "<YouTube_URL>" "studio/<slug>/intake"
內部運作方式:下載器會先嘗試英文字幕(en、en-US、en-orig),若無則改為嘗試中文(zh-Hans、zh-CN、zh)。它使用 --cookies-from-browser chrome 來進行已驗證的存取。
指令完成後,列出 intake 資料夾的內容並識別:
.mp4影片檔案(檔名中可能包含影片標題和 ID).srt字幕檔案(可能帶有語言標籤,如.en.srt或.zh-Hans.srt)- 任何附帶檔案(
.ytdl、.jpg等)— 記錄它們但不需要使用
如果下載失敗:
- Cookie 錯誤 → 告訴使用者重新整理他們的 Chrome YouTube 登入狀態,然後重試
- 找不到字幕 → 回報「此影片無可用字幕」並停止
- 影片下載錯誤 → 使用不同格式重試一次;如果仍然失敗,請回報錯誤
記錄下一步驟的準確檔案名稱。不要猜測或硬編碼名稱。
3. 將字幕解析為 JSON
將 SRT 字幕檔案轉換為結構化 JSON,以便於分析:
python3 -m corekit.subtitle_to_json \
"studio/<slug>/intake/<精確的-srt-檔名>" \
"studio/<slug>/intel/transcript.json"
驗證輸出檔案存在且包含一個 cue 物件陣列。每個 cue 具有:
{
"index": 1,
"start": "00:00:01,234",
"end": "00:00:03,456",
"start_seconds": 1.234,
"end_seconds": 3.456,
"text": "說出的內容"
}
如果逐字稿為空或少於 10 個 cues,則回報「逐字稿太短或已損毀」並停止。
4. 分析逐字稿並提出候選片段
這是最重要的智慧步驟。在開始分析之前,請先閱讀以下檔案:
- playbooks/clip-contract.md — 定義了
selected_clips.json的準確 JSON 結構 - playbooks/content-analysis-playbook.md — 定義了多階段分析方法、評分標準和審查格式
4a. 多階段分析
不要嘗試一次就選出剪輯。請依序進行以下階段:
Pass 1 — 瀏覽和標記:閱讀 transcript.json,尋找包含令人難忘、資訊密集、有觀點、反直覺或情緒尖銳的內容片段。廣泛標記 — 寧可標記太多也不要太少。
Pass 2 — 邊界精煉:對於每個標記的片段,重新閱讀周圍的 cues(前後 5–10 個 cues)。選擇一個乾淨的開始和結束:
- 開始必須落在一個能在剪輯開始 3 秒內吸引觀眾的台詞上
- 結束必須落在講者完成該想法之後 — 絕不能斷在句子中間
- 如果有前景的時刻需要幾秒鐘的上下文,請將開始點往前延伸
- 如果一個想法逐漸消失,請將結束點延伸到它解決為止
Pass 3 — 完整性檢查:對於每個候選片段,驗證:
- 長度為 20–180 秒(若回報價值足夠,可延長至 3 分鐘)
- 它只包含一個清晰的想法
- 開場白是一個鉤子,而不是廢話
- 結束語解決了這個想法
- 在不觀看影片其他部分的情況下也能理解
- 它不是問候語、贊助商介紹、問答開場白或冗長的離題內容
Pass 4 — 評分和排名:根據四個維度(1–5 分)對每個候選片段進行評分:
hook— 開頭 3 秒的吸引力有多強?clarity— 是否為一個低歧義的清晰想法?standalone— 它是否能在沒有前後文的情況下獨立存在?payoff— 結尾是否有用、令人難忘或值得分享?
根據加權總分進行排名:hook × 0.35 + clarity × 0.25 + standalone × 0.2 + payoff × 0.2
4b. 候選片段數量指引
| 原始影片長度 | 目標候選片段數 |
|---|---|
| < 20 分鐘 | 5 – 8 |
| 20 – 60 分鐘 | 8 – 12 |
| > 60 分鐘 | 10 – 15 |
預設的失敗模式應該是「候選片段太少」,而不是「太多」。 如有疑問,請包含更多。使用者會進行刪減。
4c. 處理自動產生的(有雜訊的)字幕
YouTube 自動字幕通常包含:
- 重複的片段(相同片語出現在連續的 cues 中)
- 缺少標點符號和大寫
- 聽錯的詞彙(特別是名字、技術術語)
當來源字幕是自動產生時:
- 保守地推斷預期含義 — 不要憑空發明主張
- 在判斷剪輯邊界時忽略重複的片段
- 使用周圍的上下文來確定句子的實際結尾位置
- 如果來源品質較低,請在候選摘要中註明
4d. 寫入輸出
寫入兩個檔案:
-
studio/<slug>/intel/selected_clips.json— 機器可讀的剪輯決策。必須完全遵循playbooks/clip-contract.md中的結構。 -
studio/<slug>/intel/candidate-board.md— 人類可讀的審查表格。
5. 呈現候選片段供使用者審查
以對審查友善的格式顯示候選清單。對於每個候選片段,顯示:
| 欄位 | 格式 | 範例 |
|---|---|---|
| ID | clip-XX | clip-01 |
| 時間範圍 | HH:MM:SS → HH:MM:SS | 00:12:03 → 00:13:22 |
| 時長 | 人類可讀 | 1分19秒 |
| 標題 | 一個挑動人心的中文標題,≤12 字 | AI终将取代一切? |
| 摘要 | 恰好兩句中文 | 句1: 在讲什么。句2: 为什么值得看。 |
以編號表格呈現,以便使用者可以用 ID 回覆。
如果使用者說「繼續」或「自動挑選」:自行選擇排名最高的候選片段。對於一個 1 小時的影片,至少匯出 8 個。
如果使用者選擇了特定的 ID:只匯出那些。
6. 匯出每個選定的剪輯
對於 每個 使用者選擇(或您自動挑選)的剪輯,依序執行 6a 到 6f 步驟。在進入下一個剪輯之前,完成一個剪輯的所有子步驟。
6a. 裁切影片片段
python3 -m corekit.cut_video \
"studio/<slug>/intake/<精確的-mp4-檔名>" \
<開始時間秒數> <結束時間秒數> \
"studio/<slug>/exports/<剪輯資料夾>/clip.mp4"
<剪輯資料夾> 的命名慣例是 XX-<標題-slug>,例如 01-ai-will-replace。
驗證輸出檔案存在且大小不為零。
6b. 提取視窗化來源字幕
python3 -m corekit.window_subtitles \
"studio/<slug>/intake/<精確的-srt-檔名>" \
<開始時間秒數> <結束時間秒數> \
"studio/<slug>/exports/<剪輯資料夾>/clip.src.srt"
這只會提取與剪輯視窗重疊的 cue,並移動所有時間戳記,使剪輯從 00:00:00,000 開始。
驗證輸出 SRT 檔案至少有一個 cue。
6c. 翻譯為繁體中文字幕
讀取 clip.src.srt 並將其翻譯為繁體中文。將結果寫入同一資料夾中的 clip.zh.srt。
翻譯規則(嚴格遵循):
- 自然的口語中文 — 不是書面/正式的中文。觀看者正在觀看短影片,而不是閱讀文件。
- 精確保留時間戳記 — 除非為了可讀性而需要合併兩個 cue。切勿隨意改變時間。
- 準確保留命名實體 — 人名、公司名、產品名、數字和引用的片語必須忠實保留。
- 簡潔的台詞 — 偏好適合短影片節奏的簡短中文片語。過長的滾動字幕會毀掉留存率。
- 必要時在 cue 之間重新平衡 — 如果一個英文句子被分割在 3 個 cue 中,您可以將中文文字重新分配到相同的 3 個 cue 中。保留 cue 的順序。
- 不要合併 cues — 一個包含 40 個 cues 的密集英文 SRT 應產生大約 35–45 個中文 cues,而不是 10 個。預設的失敗模式是 cues 稍微太多,而不是太少。
- 只刪除真正的重複項 — 自動字幕通常會在連續的 cues 中重複相同的片段。您可以刪除重複項,但保留第一次出現的。
- 如果來源已經是中文 — 不要翻譯。只清理明顯的自動字幕雜訊(重複片段、損壞字元)。
6d. 產生標題和描述
為每個剪輯建立:
標題(用於前幾秒的覆蓋):
- 尖銳、可點擊、有觀點
- 目標 ≤ 12 個中文字元,以便在字體大小為 48 時能整齊地顯示在螢幕上
- 可能具有挑釁性或逆向思維,但必須忠於講者的意思
- 應創造好奇心、緊張感或繼續觀看的欲望
描述(用於平台發布):
- ≤ 140 個中文字元
- 必須提及:誰在說話、這是來自哪個節目/訪談、討論了什麼主題、關鍵主張或要點是什麼
將兩者寫入 studio/<slug>/exports/<剪輯資料夾>/metadata.txt:
标题:AI终将取代一切?
描述:Sam Altman 在 Lex Fridman 播客中谈到 AGI 的时间表——他认为大多数人严重低估了 AI 的发展速度,未来三年将改变一切。
6e. 將中文字幕 + 標題燒錄到影片中
python3 -m corekit.render_hardsubs \
"studio/<slug>/exports/<剪輯資料夾>/clip.mp4" \
"studio/<slug>/exports/<剪輯資料夾>/clip.zh.srt" \
"studio/<slug>/exports/<剪輯資料夾>/clip.hardsub.mp4" \
--title "<來自 6d 的標題>"
關鍵:傳遞中文 clip.zh.srt 檔案,而非 clip.src.srt。這是 Agent 最常見的錯誤 — 傳遞來源語言字幕而不是翻譯後的字幕。
燒錄步驟將:
- 自動偵測 libass;如果不可用,則回退到 drawtext 渲染(您無需採取任何動作)
- 自動為當前機器選擇最佳的 H.264 編碼器
- 在第一秒內以字體大小 48 和 3px 黑色外框居中渲染標題
- 在剪輯的其餘時間於畫面底部渲染字幕 cue
驗證輸出 clip.hardsub.mp4 存在且檔案大小大於 clip.mp4(濾波器鏈增加了視覺資料)。
6f. 附加到包裝文案
每個剪輯匯出後,將其標題和描述附加到組合包裝檔案中:
studio/<slug>/intel/packaging-copy.md
格式:
## clip-01: AI终将取代一切?
**标题**: AI终将取代一切?
**描述**: Sam Altman 在 Lex Fridman 播客中谈到 AGI 的时间表...
**文件**: studio/<slug>/exports/01-ai-will-replace/clip.hardsub.mp4
**时长**: 1分19秒
---
7. 最終輸出
在所有剪輯匯出後,回傳給使用者:
- 來源素材資料夾:
studio/<slug>/intake/ - 候選清單:步驟 5 的完整表格(時間戳、時長、標題、摘要)
- 包裝檔案:
studio/<slug>/intel/packaging-copy.md - 匯出的剪輯:列出每個
clip.hardsub.mp4的路徑
工作區佈局參考
studio/<video-slug>/
├── intake/ # 來自 YouTube 的原始素材
│ ├── <title> [<id>].mp4 # 來源影片(來自 yt-dlp 的檔名)
│ └── <title> [<id>].<lang>.srt # 來源字幕
├── intel/ # 分析產出檔案
│ ├── transcript.json # 結構化字幕 cues(來自步驟 3)
│ ├── selected_clips.json # 剪輯決策(來自步驟 4)
│ ├── candidate-board.md # 審查表格(來自步驟 4)
│ └── packaging-copy.md # 所有標題與描述(來自步驟 6f)
└── exports/ # 每個匯出剪輯一個資料夾
└── 01-<slug>/
├── clip.mp4 # 原始裁切(無字幕)
├── clip.src.srt # 視窗化來源語言字幕
├── clip.zh.srt # 翻譯後的繁體中文字幕
├── clip.hardsub.mp4 # 最終交付物(已燒錄字幕+標題)
└── metadata.txt # 此剪輯的標題與描述
模組參考
| 模組 | 呼叫方式 | 參數 |
|---|---|---|
corekit.fetch_source | python3 -m corekit.fetch_source <網址> <輸出目錄> | YouTube 網址,輸出目錄 |
corekit.subtitle_to_json | python3 -m corekit.subtitle_to_json <輸入.srt> <輸出.json> | SRT 檔案路徑,JSON 輸出路徑 |
corekit.cut_video | python3 -m corekit.cut_video <輸入.mp4> <開始秒數> <結束秒數> <輸出.mp4> | 來源影片,開始秒數(浮點數),結束秒數(浮點數),輸出路徑 |
corekit.window_subtitles | python3 -m corekit.window_subtitles <輸入.srt> <開始秒數> <結束秒數> <輸出.srt> | 來源 SRT,開始秒數(浮點數),結束秒數(浮點數),輸出路徑 |
corekit.render_hardsubs | python3 -m corekit.render_hardsubs <輸入.mp4> <輸入.srt> <輸出.mp4> --title "..." | 剪輯影片,中文 SRT,輸出路徑,選擇性標題文字 |