CutCraft 是做什麼的？
將原始素材和一段對話轉化為一個顯而易見的最終影片。將每個專案都保存在一個命名的 CutCraft 工作區中，在編輯前顯示視覺化的字幕選擇，一次問完所有創意問題，並讓逐字稿修正可以立即復原。
不可協商的契約
- 先執行就緒檢查。 在首次使用或環境變更後，執行
python3 helpers/check_environment.py。如果缺少必要或請求的有條件依賴項，請暫停編輯，向使用者顯示該腳本的官方 URL 和確切的設定說明，並僅要求提供缺少的批准或憑證。請參閱 references/onboarding.md 以了解金鑰處理和平台指南。 - 切勿在此套件或專案中儲存機密。 將 ElevenLabs 金鑰以權限
600儲存在~/.config/cutcraft/.env中，或使用本機 Whisper，這樣就不需要金鑰或上傳轉錄稿。切勿將金鑰放入命令參數、日誌、轉錄稿、螢幕截圖、儲存庫、插件快取或專案資料夾中。 - 在產生任何內容之前先建立工作區。 根據使用者的描述和檢查過的素材，推斷出一個簡短的專案名稱。僅在兩個名稱明顯不同且都合理時才進行確認。執行
helpers/project_workspace.py --name "<name>"並使用它回傳的路徑。 - 先檢查，一次問完，批准後再編輯。 清點並轉錄來源、檢查具代表性的畫面、建立真實的字幕預覽圖像，然後在一個統一的檢查點中，一次問完所有剩餘的創意問題。在使用者選擇或接受建議的預設值之前，不要開始剪輯。
- 視覺化地呈現選擇。 從素材中生成三種具代表性的字幕預覽圖像（推薦、簡潔/敘事、醒目/社交，除非素材需要不同的選擇）。在每張圖像下方說明字型、大小、位置、背景、語言和提示節奏。使用者可以回答選項編號或調整，例如「往下 4%」或「字大 15%」。
- 讓最終結果顯而易見。 僅將交付成品置於
成品/中。主要影片必須命名為<project>_final.mp4。將預覽、片段、轉錄稿、EDL、下載檔案、生成的資產和報告放在過程/中。 - 每次交付含字幕的成品時，同時匯出可編輯的文字。 在最終影片旁交付
<project>_逐字稿.md和<project>.srt。使用穩定的提示 ID 和時間戳，以便使用者可以說，例如，「第 18 句改成……」。 - 立即套用逐字稿修正。 解析請求的提示，針對
過程/master.srt執行helpers/apply_transcript_corrections.py，重新執行驗證，使用修正後的 SRT 重新渲染最終影片，重新產生逐字稿，並替換交付成品。除非使用者回報同步問題，否則保留時間安排。不要對未更改的來源媒體進行重新轉錄。 - 無需審查前端。 不要啟動伺服器或建立瀏覽器 UI 檔案。所有審查都透過交付的影片/圖像檔案和對話式修正來進行。
- 讓工作可恢復。 在每個檢查點更新
cutcraft.project.json。保留來源簽章、批准狀態、修訂版本、最終路徑和資產來源。僅使用代理檔案進行檢查；始終從原始檔案渲染。 - 交付前進行驗證。 執行確定性預檢和
quality_report.py，檢查剪輯邊界和代表性字幕時刻的渲染輸出，聆聽最終混音，並驗證輸出持續時間/串流。如果剪輯移除了口吃或虛假開頭，請重新轉錄該渲染部分以證明其已不存在。
專案佈局
預設根目錄：~/Documents/Codex/CutCraft/（可在 Finder 中看到；將可安裝的技能本身保留在 ~/.codex 下）。
CutCraft/
└── <project>/
├── cutcraft.project.json
├── 成品/
│ ├── <project>_final.mp4
│ ├── <project>_逐字稿.md
│ └── <project>.srt
└── 過程/
├── project.md
├── creative_brief.json
├── inventory.json
├── takes_packed.md
├── edl.json
├── master.srt
├── transcript_corrections.json
├── asset_registry.json
├── transcripts/
├── clips/ and clips_*/
├── assets/
├── animations/
├── proxies/
├── downloads/
└── verify/
除非使用者要求，否則不要將使用者的原始素材複製到專案中。在 edl.json 中記錄絕對來源路徑，並保持原始檔案不變。
一個統一的檢查點
檢查足夠的材料以提出建議，渲染字幕比較圖像，然後一次問完所有適用的項目：
- 目標、預期觀眾、平台、長寬比、解析度、目標長度、截止日期敏感的格式。
- 故事/順序、必須保留的台詞、必須剪掉的素材、ASR 必須精確拼寫的名稱/術語。
- 節奏、裁切/重新構圖、色彩氛圍、轉場、效果、疊加、B-roll、審查/隱私需求。
- 字幕：內嵌/旁白/兩者、語言或雙語模式、逐字/清理版、字型、大小、位置、背景、提示節奏、螢幕 UI 安全區域。
- 音訊：清理、響度、提供的音樂/SFX/旁白，或所需的氛圍和強度。
- 素材來源：使用者提供的檔案、生成的資產或特定的免費庫。如果請求免費素材，請在 references/free-assets.md 中提供合適的選擇，要求使用者選擇，並使用
asset_registry.py註冊項目、創作者、URL、許可證、歸屬和校驗和。 - 轉錄隱私：當隱私問題重要時，建議使用本機 Whisper；否則提供 ElevenLabs 進行管理的說話者辨識。在將媒體傳送到任何雲端提供者之前，解釋上傳行為。
- 編輯自主權和任何明確禁止的事項。
在此檢查點附加預覽圖像。為每個選擇提供一個建議的預設值，並包含「全部用建議值」作為一個有效的答案。將答案持久保存在 過程/creative_brief.json 中；不要在中途編輯時重新提出已解決的問題。
工作流程
- 執行就緒檢查並僅解決缺少的需求。
- 檢查檔案名稱和使用者的描述；推斷一個專案名稱並建立工作區。
- 執行
inventory.py --work-dir <過程> <sources_dir>。對於長時間或 4K 的來源，建立快取的代理檔案以供檢查。執行analyze_media.py以定位鏡頭變化、靜音、黑畫面以及凍結間隔。 - 使用已批准的雲端/本地提供者轉錄到
<過程>/transcripts/，然後打包轉錄稿。閱讀打包後的轉錄稿，取樣早期/中期/後期幀和模糊的編輯點，並注意 ASR 拼寫風險。 - 從代表性幀生成三種字幕樣式預覽。詢問統一的檢查點並儲存已批准的簡報。
- 建置
edl.json，來源化或生成已批准的資產，並在不零碎地詢問一般品味問題的情況下進行編輯。 - 建置字幕。對於中文，使用
build_cn_subtitles.py；對於其他語言，使用render.py --build-subtitles。請遵循 references/subtitles.md。 - 執行
validate_project.py，在過程/verify/中渲染一個可評估的預覽，並進行自我審查。在回報頑固問題之前，將修正/重新渲染循環限制在三次以內。 - 從原始來源渲染
<成品>/<project>_final.mp4，將最終的 SRT 複製到<成品>/<project>.srt，並使用export_transcript.py生成<成品>/<project>_逐字稿.md。 - 執行
quality_report.py，解決每個錯誤，視覺化和聽覺化地審查警告，然後使用project_state.py將清單標記為已交付。 - 交付三個明確的路徑、QC 報告、簡潔的編輯摘要和資產來源。切勿讓使用者在中間檔案中搜尋「final」。
製作正確性
- 最後再套用字幕，在所有疊加和裁切之後。
- 從詞彙邊界和靜音中推導出剪輯候選項；切勿在詞彙內部進行剪輯。使用適合節奏的 30–200 毫秒緩衝。
- 在片段邊界套用簡短的音訊淡入淡出以防止爆音。
- 在連接片段之前，正規化畫布、幀率、像素格式、色彩空間、取樣率和聲道佈局。
- 按來源路徑、大小和修改時間快取轉錄稿和代理檔案；僅在該簽章變更時才重新執行。
- 在輸出時間軸上計算字幕時間戳，而不是來源時間軸。
- 當批准單行時，保證像素安全的單行提示；根據實際字型和畫布進行驗證。
- 僅使用使用者提供、生成、公有領域或授權相容的資產。記錄標題、創作者、來源 URL、許可證、下載日期和所需的歸屬。
- 先混合對話。在語音下將音樂音訊降低；響度正規化無法挽救糟糕的混音。
- 讓主要代理成為創意簡報、EDL、字幕時間、最終時間軸、混音和 QC 的擁有者。僅可平行處理那些輸入不變且寫入唯一路徑的工作。
當專案需要多鏡頭選擇、轉場、調色、動畫、速度曲線或音樂主導的編輯時，請參閱 references/editorial-craft.md。在編寫或擴充 EDL 之前，請參閱 references/edl.md。
輔助腳本
check_environment.py— 必要/有條件的依賴項和憑證就緒檢查，附帶官方設定 URL。project_workspace.py— 建立或重複使用命名的成品/+過程/專案。project_state.py— 原子性地記錄可恢復的檢查點、批准、修訂和輸出路徑。inventory.py— 探查來源格式和正規化風險。analyze_media.py— 偵測場景變化、靜音、黑畫面和凍結幀。create_proxy.py— 快取的輕量級檢查代理檔案，對應到不變的原始檔案。transcribe.py,transcribe_batch.py— 快取的詞彙級別 ElevenLabs 或本機 Whisper 轉錄。pack_transcripts.py— 緊湊的短語級別編輯檢視。timeline_view.py— 底片條、波形、詞彙和剪輯點檢查。subtitle_style_preview.py— 在真實幀上進行精確的 libass 樣式/位置預覽。build_cn_subtitles.py— 中文感知的像素寬度提示建構。render.py— 正規化、剪輯、連接、疊加、混合，然後最後添加字幕。validate_project.py— 快速失敗的 EDL、資產、時間和字幕檢查。asset_registry.py— 失敗關閉的資產許可證、歸屬和校驗和註冊表。quality_report.py— 最終串流、持續時間、黑/凍結/靜音和 QC 證據報告。build_cut_report.py— 分類的剪輯摘要。apply_transcript_corrections.py— 失敗關閉的提示/文字修正，附帶稽核日誌和備份。export_transcript.py— 可讀、可透過提示定址的轉錄稿，用於交付。cleanup_session.py— 僅在使用者明確要求刪除過程檔案後才進行選擇性清理；切勿將「完成」解釋為刪除。
解析與包含此 SKILL.md 的目錄相關的每個輔助腳本和參考文件。
修訂行為
將使用者修正後的交付轉錄稿視為文字來源的事實標準。對於僅文字修正，保留提示時間和編輯決定，修補 SRT，驗證，並重新渲染。對於同步回報，檢查受影響的渲染窗口，並僅調整那些提示邊界。對於編輯性更改，更新 EDL 和剪輯報告，然後執行完整受影響的渲染/QC 路徑。
將每個工作階段附加到 過程/project.md，包含策略、已批准的決定、資產來源、修訂版本、QC 證據和待解決問題。預設保留 過程/，以便將來的修訂保持低成本且可追蹤。