CapCut / 剪映 Claude 技能

從 Claude 使用 CapCut / 剪映

CapCut MCP 是專為 Codex 設計的。此技能是其 Claude 適配版：官方素材保持不變，置於 official/ 目錄下（外掛 v0.2.6），而此文件說明如何在 Claude 中使用，以及已在真實環境中驗證過的事項（2026-10-26/27，Claude Desktop Code 分頁，Windows）。

以下路徑皆相對於此技能資料夾（~/.claude/skills/capcut/）。

若 official/ 目錄缺失（全新克隆），請先執行 python scripts/fetch_official.py——它會從 CapCut 的 CDN 下載其外掛套件（官方素材未在此儲存庫中重新散佈）。使用 --force 可重新整理至最新發佈版本。

0. 連線（如果工具缺失或失敗，請先執行此步驟）

唯一可行的連線方式是透過 Claude Desktop 設定中的本地 MCP 伺服器，並使用 mcp-remote。將 CapCut 作為 claude.ai 的自訂連接器是行不通的：CapCut 的 OAuth 伺服器會拒絕 Claude 的動態用戶端註冊（"無法在 CapCut 的登錄服務中註冊"），也無法提供用戶端 ID。

%LOCALAPPDATA%\Claude-Data\<profile>\claude_desktop_config.json（或 %APPDATA%\Claude\claude_desktop_config.json）→ mcpServers：

"capcut":          {"command": "cmd", "args": ["/c", "npx", "-y", "mcp-remote", "https://www.capcut.com/api/external_mcp"]},
"capcut_resource": {"command": "cmd", "args": ["/c", "npx", "-y", "mcp-remote", "https://www.capcut.com/api/external_mcp/resource"]}

• capcut = 帳號綁定工具（OAuth）。capcut_resource = 免登入的卡片工具（無需登入）。編輯前請先備份設定檔；使用者必須在編輯後完全關閉並重新開啟 Claude。

從頭設定（若會話中無 mcp__capcut__* 工具）：

1. 檢查先決條件：node --version（≥14）和 PATH 中的 npx。
2. 找到現有設定檔：先搜尋 %LOCALAPPDATA%\Claude-Data\*\claude_desktop_config.json，再搜尋 %APPDATA%\Claude\claude_desktop_config.json。讀取其內容，複製為 claude_desktop_config.json.bak-<日期>，在 mcpServers 下新增兩個條目（若無此鍵則建立），不更動其他部分，並重新解析檔案為 JSON 以確認有效。
3. 請使用者在其系統預設瀏覽器中登入希望草稿存放的 CapCut 帳號，然後完全關閉 Claude（工作列圖示 → 結束）並重新開啟。
4. 啟動時，mcp-remote 會在那個瀏覽器中開啟 CapCut 的授權頁面；使用者核准（若瞬間閃過並關閉，表示已自動核准——沒問題）。
5. 當前會話無法看到啟動後才新增的伺服器：請在一個新的 Code 分頁會話中繼續。使用 start_stdraft_session（應回傳 session_id）和 search_capcut_material（type: music）驗證。
6. 可選：將 Claude 內建瀏覽器登入同一個 CapCut 帳號，以便在該處檢查草稿。

• OAuth 權杖快取於 ~/.mcp-auth/mcp-remote-v1/<hash>_tokens.json 和 <hash>_client_info.json。
• 重新授權 / 切換帳號：先詢問使用者；刪除上述兩個檔案；使用者先在系統預設瀏覽器中登入所需的 CapCut 帳號（同一種登入方式——Google/Email/TikTok 是不同的帳號）再重新啟動；然後完全關閉並重新開啟 Claude；mcp-remote 會開啟 CapCut 授權頁面（若瀏覽器已登入，可能會閃過即關閉——這是成功的情況）。使用 start_stdraft_session 驗證。
• 若每次呼叫都出現 get user workspace failed: check login error 症狀 = 快取的授權已過期 → 依上述步驟重新授權。
• 重新授權會將同一帳號登出其他 CapCut 網頁工作階段（包括 Claude 的內建瀏覽器）；使用者必須在該處重新登入。
• 草稿會儲存在 MCP 被授權的帳號中。若使用者看不到草稿，請先比對帳號。

1. 可用的操作介面

介面	狀態
Claude Desktop Code 分頁會話	以下所有功能皆可正常運作。請使用此介面處理 CapCut 工作。
手機遠端控制 Code 分頁會話	與 Code 分頁相同（工具在 PC 上執行）。
Desktop Chat / 手機聊天連接到 PC 工具	草稿工具失敗，出現 "missing session_id"（橋接器似乎丟失了一個名為 session_id 的參數）；卡片可能無法顯示。請勿在此處進行草稿編輯。
手機獨立聊天	完全無 CapCut（伺服器僅在 PC 本地）。

卡片（capcut_resource：templates_preview_v2, editing_plan, video_preview, background_music, billing_confirmation）會被擷取但不會在 Code 分頁中渲染——結果以文字/JSON 形式返回。永遠不要等待卡片；請自行讀取資料並呈現。

2. 應閱讀的官方文件（僅限任務所需部分）

任何草稿工作的必讀項目：official/capcut-stdraft-builder/reference/application.md（功能合約）。僅在任務涉及時才閱讀其他部分。

任務	閱讀
粗剪交接或為現有影片加字幕	official/video-editing/references/post-editing.md
會話/版本/推送/衝突	official/web-collaborative-editing/SKILL.official.md（+ references/conflict-recovery.md）
欄位級協定問題	official/capcut-stdraft-builder/reference/STDraft_Protocol.md、validation.md
素材	official/video-editing/references/materials.md
字幕	official/video-editing/references/auto-captions.md
AI 粗剪	official/video-editing/references/ai-rough-cut.md
圖片/影片生成	official/generate-media/SKILL.official.md + references/
範本搜尋	official/search-templates/SKILL.official.md

忽略僅限 Codex 的部分：codex plugin 安裝/升級、codex app-server/capcut-login.mjs OAuth、「New-Task Handoff」/fork、require_escalated 沙箱標誌、TTY 票證輸入、「在卡片後靜默結束回合」。

3. 核心工作流程：建立/編輯雲端草稿

Shell：在 Bash 工具（Git Bash）中執行指令，不要用 PowerShell。使用正斜線 Windows 路徑（D:/proj/clip.mp4）或單引號路徑。在使用者的專案資料夾（例如 <project>/capcut_work/）中工作，以使上傳映射和草稿能跨會話留存。

1. 上傳本地媒體，僅使用官方上傳器（絕不使用自製 VOD 程式碼）：
   • 為整個批次使用 capcut_asset_upload_credential，參數為 version: 2 和 files: [{file_name, size_bytes}] → 取得 upload_ticket（一個短暫的單一批次能力；它必然在此對話中傳遞一次——切勿記錄到其他地方）。
   • 將 ticket 寫入檔案（注意結尾無換行問題），透過 stdin 傳遞（絕不在 argv 中），然後刪除該檔案：

     cd <project>/capcut_work && printf '%s\n' '<ticket>' > ticket.tmp
     node ~/.claude/skills/capcut/official/capcut-upload/scripts/capcut-upload.mjs \
       --files '[{"client_id":"c1","file":"D:/proj/a.mp4"},{"client_id":"c2","file":"D:/proj/b.mp3"}]' \
       --upload-ticket-stdin --json < ticket.tmp > upload_result.json 2> upload_stderr.txt; rm -f ticket.tmp
     

     （單一檔案：--file <path> --client-id c1；進度 → stderr，JSON → stdout。）
   • 成功 = 非空的 vid 且 setPublic.success:true。儲存一個 名稱 → {vid, duration} 映射（upload_map.json）；切勿重新上傳已有 vid 的項目。Ticket 約在 1 小時後過期。
2. 會話：每個草稿使用一次 start_stdraft_session；保留 session_id。每次編輯回合前呼叫 check_stdraft_state(session_id, local_package_id)：
   • 全新草稿：傳入 ""；預期 server_package_id:"" → 從頭建構並以 base_package_id:"" 推送；
   • 其他情況則遵循 official/web-collaborative-editing/SKILL.official.md 中的基準表（過期時 → 先使用 get_stdraft_snapshot）。
3. 本地建構，使用官方原子函數（Python ≥3.8，僅使用標準函式庫，以 python -B 執行，sys.path.insert(0, "C:/Users/<使用者>/.claude/skills/capcut/official/capcut-stdraft-builder/scripts")）：apply_video、apply_audio、apply_text、apply_text_template、apply_captions、apply_video_effect、apply_filter、apply_transition、update_material、update_placement、update_caption_text、remove_material、unset_attribute。鏈式呼叫 result["draft"]。新的草稿根節點：{"version":"0.1.0","segments":[{"id":"draft","type":"DRAFT","attributes":{"width":1920,"height":1080,"ratio_type":"16:9"}}]}。
   • 靜音片段：apply_video(..., volume=0.0)。時間單位為整數毫秒。
   • 每個 vid/sid 來源都會引發 SOURCE_RANGE_UNVERIFIED —— 這是預期行為。請自行檢查：source_start_ms + duration_ms × speed 不得超過來源長度（來自 upload_map.json，或音樂搜尋結果中的 duration_ms）。
   • 選擇搜尋結果：優先選擇 duration_ms 能涵蓋所需長度且標題/說明符合氛圍的項目；說明你選擇了哪一個。
4. 準備推送：python -B ~/.claude/skills/capcut/scripts/draft_tool.py slim draft.json draft_slim.json（縮短 ID，每行一個片段，重新驗證，若超過約 60k 字元則發出警告）。讀取 draft_slim.json 並將其完整文字逐字貼上作為 push_stdraft_snapshot 中的 stdraft_json（這會花費相當於其大小的兩倍 token——請保持草稿精簡）。
5. 推送後：若結果由 harness 儲存至檔案，執行 draft_tool.py summary <file> / urls <file>；若結果內聯返回，先儲存至 push_result.json（或透過 pipe：... summary -）。提供使用者 web_editor_url 作為 Markdown 連結，標籤使用 web_editor_text 的原文（伺服器本地化，可能例如 "Buksan sa CapCut"）。使用返回的 stdraft_json/server_package_id 作為下一個基準。
   • 正常的伺服器改寫（非錯誤）：vid:// → asset://<id>；DRAFT 會獲得隨機 ID 並失去 ratio_type；圖層會被重新編號；end.ms 會加諸各處；TEXT 會獲得 font_color/line_max_width 和一個 PATCH 子節點（"style copy"）；VIDEO 會獲得 crop/background.* 預設值；AUDIO 的 meta_type 會變成小寫。比對內容、時間、音量、速度、轉場和關鍵影格——而不是 ID 或圖層編號。
6. 可選地，在內建瀏覽器中開啟 embed_editor_url 以查看；這僅在該瀏覽器已登入同一個 CapCut 帳號時有效。大型專案可能需要 30–60 秒載入；文字可能僅在選取一個片段後才繪製。

推送陷阱（已驗證）

• **逾時 ≠ 失敗。**首次推送至新帳號時，會複製每個媒體檔案，可能超過用戶端逾時但仍成功。絕不要盲目重新推送：先使用 check_stdraft_state；若版本已存在，則使用 get_stdraft_snapshot（透過 draft_tool 摘要）並從該處繼續。盲目重新推送會回傳 STDRAFT_VERSION_CONFLICT。
• 因逾時推送而建立的草稿可能不會顯示在資料庫中，也不會回傳 URL；在其上再推送一次（相同內容，正確基準）即可取得編輯器 URL。
• 大小：約 55k 字元可可靠推送；約 90k 無法放入單一呼叫。保持推送精簡（刪除可選的關鍵影格/樣式，在網頁編輯器中新增）。

4. 已驗證的功能邊界

可正常運作並在雲端儲存後保留：影片片段（來源入點、持續時間、音量、速度）、轉場（新增/取代/移除；同一圖層、連續）、音樂與音效（來自搜尋的 sid:// 或自己的 vid://；音量；無自動循環）、附強度的濾鏡、純文字（字型、大小、顏色、位置、邊框）、字型切換、文字特效（flower）、文字範本（伺服器會新增一個 IN 動畫；插槽數量無法驗證）、附詞時間軸的字幕與 update_caption_text、移除/取消設定、位置/圖層/時間變更、在速度為 1 的片段上的 scale_*/alpha 關鍵影格。

儲存後遺失或損壞：

• VIDEO_EFFECT 片段（影片特效與臉部特效）會被完全捨棄——告知使用者在網頁編輯器中新增特效。
• 在 speed ≠ 1 的片段上的關鍵影格，其時間會被速度重新縮放，且大部分會被捨棄。
• 建構器未涵蓋的任何功能（遮罩、貼紙、曲線、調色）都必須在網頁編輯器中完成。
• 匯出/渲染無法透過 MCP 使用：使用者需在 CapCut 編輯器中匯出。

素材搜尋：music、sound_effect、video_effect 會遵循提示；font、text_effect、text_template、face_effect、transition、filter 會回傳一個固定的精選清單（最多 20 項），無論提示為何——沒有單純的交叉溶解；精選字型為拉丁字型（中文會回退到預設字型 vimo://7317175475195875841，可渲染 CJK）。無法搜尋影片素材/圖片——請上傳。

自動字幕（auto_caption_submit / auto_caption_query）：僅限語音辨識；需要 Pro 會員資格（免費帳號會獲得 PAYWALL_REQUIRED——顯示 benefit_check_label 連結原文）。對歌詞無用（整首歌只回傳一行垃圾內容）——對於歌詞時間軸，請改用本地 Whisper + 已知歌詞。

範本搜尋：capcut_template_search → 輪詢 capcut_template_search_poll_v2 直到終止 → templates_preview_v2(search_id) 回傳範本資料（卡片不渲染；顯示清單標題、持續時間、使用次數和 page_url 供使用者使用）。關聯性較鬆散；結果保留 15 天；最多 10 個。

AI 粗剪（AI Lab）：capcut_ailab_start_edit(assets=[{resource_id: <vid>, file_name}], query) → 輪詢 → 一個計畫事件到達，狀態為 loop_turn_completed；將計畫轉達給使用者，然後以使用者的確切選擇文字呼叫 capcut_ailab_submit_plan_response且不帶 card_id（計畫的事件 ID 會被拒絕為 plan_card_id_invalid）。音樂和最終影片事件隨後到達（對於 10 秒的剪輯約需 2 分鐘）。使用最終事件的 context/resources（不變）呼叫 video_preview 以取得結果的可編輯 STDraft（stdraft 欄位）——將其匯入草稿會話以繼續編輯。僅音訊的素材會被拒絕（unsupported_edit_file_name）。請勿將 AI Lab 用於僅需字幕的請求。

圖片/影片生成（Seedream / Seedance）：會消耗點數。卡片在此處不會渲染，因此：以 confirmed:false（無 unique_key）送出 → 收到 CONFIRMATION_REQUIRED 時告知使用者確切的 credits_amount → 僅在使用者在聊天中明確核准該數量後，才以 confirmed:true 和返回的 unique_key/相同的 generate_id 重試。絕不代使用者確認。輪詢 capcut_generation_poll 直到 next_action=none，然後使用 `generation_result(task_i