圖片轉可編輯 PPT（Claude Code 移植版）
使用內建的 editppt 執行環境來分解、重建、驗證並組裝視覺投影片為可編輯的 .pptx。輸入可以是一張或多張圖片、一個 PDF 檔案，或是一個圖片型的 PPT/PPTX 檔案。輸出始終是一個 .pptx 檔案，每個輸入頁面對應一張投影片，並按照輸入順序排列。
<skill-root> 在下方指的都是包含此 SKILL.md 的目錄。
此技能的組織方式
此檔案由你（協調者）閱讀。頁面層級的工作由頁面重建器（背景子代理，或對於單頁而言是你自己）根據產生的提示執行。每個規則都有一個權威的存放處——請遵循指標而非自行猜測：
prompts/page-worker.md— 頁面重建器模板：所有權邊界、讀取路徑、執行順序、所需輸出、回傳格式。由scripts/build-page-worker-prompt.py填入。references/cli-helper.md—editppt安裝檢查、指令樹、語法。選擇指令時閱讀。references/manifest-schema.md— 每個執行/頁面工件的 JSON 合約。撰寫或驗證執行/頁面檔案時閱讀。references/page-decision-tree.md— 什麼成為背景 vs. 圖片資產 vs. 原生文字/形狀/表格、文字提示的使用方式、最終自我檢查、修復 vs. 警告。頁面重建器會閱讀此檔案；你很少需要。
Claude Code 執行時映射
上游技能目標是 Codex。以下是使其在此運行的替代項目；它們在參考檔案中提及 Codex 對等項目時都適用。
| 上游 (Codex) 概念 | 在 Claude Code 中 |
|---|---|
內建 image_gen.imagegen + 圖片模型資產表 | 由 claude-native 後端取代。 Claude 可以看見但無法產生點陣圖，因此它將圖示/插圖追蹤為 SVG，將照片保留為矩形來源區域，並在本地修復乾淨的背景（references/page-decision-tree.md 第 2.4 節）。始終使用 --image-backend claude-native 執行 prepare；絕不使用 builtin-imagegen。 |
CLI 圖片 API (editppt image generate/edit) | 僅在選擇性升級時使用，當 editppt doctor --check-api 報告有一個準備好的後端且某個物件不適合任何原生來源時。絕非必要。 |
view_image | Read 圖片檔案路徑（source.png、text_hints.png、縮放和 .compare.png 圖片、preview.png、split_assets_contact.png）。 |
| 產生頁面工作者/子代理 | Agent 工具，subagent_type: "general-purpose"，run_in_background: true，name: "ppt-<page_id>"（例如 ppt-page_003）。 |
Worker id 用於 --agent-id | 你給代理的名稱（ppt-page_003）；對於單頁本地模式為 main。 |
| 等待工作者 | 背景代理完成時會通知你。不要以迴圈輪詢。 |
| 將修復送回給工作者 | SendMessage 給工作者的名稱，以便保留其上下文。 |
| 沙箱/網路核准 | Claude Code 權限提示。使用本地 RapidOCR 提示的 claude-native 執行完全不進行外部呼叫。PaddleOCR 僅在設定 token 時被呼叫（editppt prepare / editppt run hints）；如果使用了選擇性升級，editppt image generate/edit 也會進行外部呼叫。 |
進入合約
這些協調者層級的規則在此一次性說明。
- CLI 優先。
editppt是必要的執行環境。如果editppt --help失敗，請從<skill-root>/cli使用「參考檔案/cli-helper.md」中的預先執行檢查來安裝它（當uv存在時偏好uv tool install --force --editable <skill-root>/cli，然後是pipx，最後是pip --user），然後執行editppt doctor。 - 僅透過 CLI 管理狀態。 從
editppt prepare <input...>開始。之後，僅透過editppt指令推進每個狀態轉換；永遠不要手動撰寫執行/頁面狀態 JSON。這能保持執行可確定且可恢復。 - 誰重建頁面。 只有一個頁面的執行在
editppt run dispatch --local聲明後由你在本地模式中重建。多頁執行則由背景頁面工作者重建——每個頁面一個。不要自行重建多頁工件：每個頁面會消耗大量上下文（圖片、清單、修復迴圈），將其保留在單獨的工作者中可以讓你的協調上下文保持可用，並讓頁面並行運行。 - 工件所有權。 除非在單頁本地模式中且在
--local聲明之後，否則你不撰寫manifest.json、page.pptx、preview.png、split_assets_contact.png、validation.json或page_result.json。本地模式遵循與工作者相同的頁面提示、參考檔案、輸出和run record驗證。 - 圖片後端。 請參閱下方「Claude Code 中的圖片後端」。如果沒有允許的來源可以重現某個物件，則該頁面將無法通過驗證，而非替換為近似形狀或圖示裁剪（
references/page-decision-tree.md第 2 節）。 - 授權的外部呼叫。 將投影片轉換為可編輯 PPT 的請求授權了該轉換所需的 OCR 呼叫（以及（如果已設定）圖片 API 呼叫），除非使用者要求僅本地處理或將輸入標記為機密。僅傳送任務本地頁面圖片、提示、遮罩和參考圖片——絕不傳送無關檔案或憑證。僅在使用者設定或指定第三方端點時才允許呼叫。
- 自主權。 對於常規重建、已設定的備援方案和頁面本地修復，無需確認閘門即可執行。僅在遇到只有使用者才能提供的事項時（例如 OCR token 決策、缺少輸入）才停止請示使用者。報告具體障礙，而非要求使用者除錯。
- 物件決策遵循
references/page-decision-tree.md；確定性驗證是一個結構閘門，絕不豁免物件來源決策。 manifest.json是權威的頁面建置來源；run record會根據它驗證page.pptx，而run finalize會根據記錄的 manifest 重建簡報。
憑證衛生
機密（PaddleOCR token、選擇性圖片 API 金鑰）如果使用者將其貼到聊天中，會出現在對話記錄中。建議使用者自己使用 ! 前綴執行設定指令，以便值直接進入 CLI，例如：
! editppt config --paddle-ocr-token <token>
! editppt config --api-key sk-... --base-url https://api.openai.com/v1 # 選擇性圖片 API 升級
如果他們還是將金鑰貼到聊天中，請使用 editppt config 儲存它，且永遠不要將其回顯；CLI 會在輸出中遮罩它。絕不要將金鑰寫入專案、執行目錄或技能目錄。
Claude Code 中的圖片後端
Claude 有視覺能力但沒有圖片生成能力，因此每次執行都使用 claude-native 後端：editppt prepare <input...> --image-backend claude-native。然後頁面重建器根據 references/page-decision-tree.md 第 2.4 節為每個物件選擇來源：
- 圖示、標誌、徽章、手繪標記、平面插圖 — Claude 將其追溯為 SVG（
editppt image zoom，然後editppt image svg）。PPTX 嵌入了真正的 SVG，因此在 PowerPoint 中使用者可以重新著色或使用「轉換為圖案」來編輯其個別路徑。這使得這些物件比起上游技能的點陣圖資產更具可編輯性。 - 照片、螢幕截圖、紋理區塊 — 保留為矩形來源區域（
editppt image photo-region）。向量追溯會將它們變成卡通圖案。 - 重建文字背後的複雜背景 — 透過本地修復清理（
editppt image inpaint）。
不要向使用者詢問圖片 API。如果 editppt doctor --check-api 恰好顯示一個準備好的後端（Codex 登入或已設定的金鑰），工作者可以將 editppt image generate/edit 用作選擇性升級，用於那些不適合任何原生來源的物件，例如繁忙背景上的照片剪裁。頁面內的資產指令會序列執行。
工作流程
階段 1：準備
閱讀 references/cli-helper.md 中的準備範例以及 references/manifest-schema.md 中的執行/頁面檔案描述。
editppt prepare <input...> --image-backend claude-native
保留預設的 --out-root：它會在目前目錄下建立工作執行目錄 output/image-to-editable-ppt/<job-id>/。不要將其指向使用者想要結果的資料夾；該資料夾應僅接收最終簡報（階段 4）。之後必須有 deck_manifest.json、page_jobs.json、notes_manifest.json，並且每個頁面必須有 source.png 和 page_request.json。
Prepare 也會寫入每個頁面的文字提示（text_hints.json/text_hints.png）。在沒有 token 的情況下，它們來自本地 RapidOCR，它會在裝置上讀取文字而不上傳，因此無需詢問使用者任何事。僅當 prepare 報告僅幾何的 builtin-ink 後端（RapidOCR 不可用）時，你才應在分派任何頁面之前詢問使用者一次：來自 https://aistudio.baidu.com/account/accessToken 的免費 token，使用 editppt config --paddle-ocr-token <token> 儲存，可使提示內容感知（它讀取文字，而不僅僅是測量文字位置）並顯著提高文字保真度；然後 editppt run hints <run> 會原地重新產生當前執行的提示。免費個人配額對此技能來說綽綽有餘。等待他們的選擇；如果他們拒絕，則繼續使用離線提示，且不再詢問。
如果使用者要求 Indra OCR（或要求更快/替代的本地 OCR），請執行 editppt config --text-hints-backend indra 並使用 [indra] 額外功能重新安裝 CLI（references/cli-helper.md）。請一次提及 Indra 的模型權重帶有修改過的 OpenRAIL-M 許可證，限制某些商業用途。不要自行切換到它：在測試中，RapidOCR 更完整地讀取了投影片文字。
如果已設定 token 但 OCR 因權限提示或網路故障而回退，那並非理想的品質路徑：讓呼叫獲得許可並在頁面重建之前重新執行 editppt run hints <run>。僅在使用者拒絕 OCR、允許的 OCR 嘗試因實際服務原因失敗、或使用者要求僅本地處理時，才繼續使用離線模式。
階段 2：重建或分派頁面
重複呼叫並根據傳回的 stage 採取行動：
editppt run next <run> --json
stage=rebuild_page_locally（正好一個頁面）。聲明它，然後自行重建：
python3 <skill-root>/scripts/build-page-worker-prompt.py <run> --page <page_id> --out <abs-run-dir>/pages/<page_id>/worker-prompt.mdeditppt run dispatch <run> --page <page_id> --agent-id main --prompt-file <abs-run-dir>/pages/<page_id>/worker-prompt.md --localRead產生的提示並在該頁面目錄內遵循它，產生與工作者相同的輸出。
stage=dispatch_pages。對於每個建議的頁面，按此順序：
- 如上所述，使用腳本建立提示。
- 使用
Agent工具產生工作者 —subagent_type: "general-purpose"，run_in_background: true，name: "ppt-<page_id>"，description: "Rebuild <page_id> as editable PPT"，並將prompt設定為：You are a page reconstructor for the image-to-editable-ppt skill (Claude Code port). Read <abs-run-dir>/pages/<page_id>/worker-prompt.md and follow it exactly. Claude Code notes: view images with the Read tool; you cannot generate bitmaps, so non-text visuals come from page-decision-tree.md section 2.4 (SVG traces, photo regions, local inpaint); run shell commands with Bash. Do not touch files outside your page directory. - 僅在產生成功後：
editppt run dispatch <run> --page <page_id> --agent-id ppt-<page_id> --prompt-file <abs-run-dir>/pages/<page_id>/worker-prompt.md
在單一訊息中產生批次中所有建議的頁面，以便它們並發運行。--out 和 --prompt-file 必須是絕對路徑，這樣頁面目錄就不會被重複前置。並發槽位來自 page_jobs.json.max_concurrent_pages（預設值 6）。
stage=wait。已分派的頁面是活躍的租約，而非閒置的槽位。等待完成通知。不要因為工作者速度慢或安靜就停止、重置或替換它——複雜的頁面可能需要 10 分鐘以上。
stage=configure_backend。執行 editppt run backend <run> --mode claude-native，而非建議的 builtin-imagegen/CLI 合約。
階段 3：記錄
當工作者的完成通知到達時（或你完成本地頁面時）：
editppt run record <run> --page <page_id> --agent-id <id>
這會根據 manifest.json 驗證 page.pptx，如果定位的物件缺少來源畫素座標、manifest 無法獨立重建頁面、或 validation.json 缺少頂層的 passed: true，則拒絕該頁面。然後回到 editppt run next。
**修復。**如果 record 失敗，請閱讀失敗證據，讓頁面的擁有者僅修復受影響的工件，重新驗證（editppt page validate，請參閱 references/cli-helper.md），然後再次記錄。在多頁模式中，將證據 SendMessage 給現有的工作者（ppt-<page_id>），而非產生一個新的——它已經持有頁面上下文及其已驗證的資產。不要為了修復不相關的 manifest 或表格錯誤而重新產生合規的資產。
重置僅在頁面需要全新執行時進行：工作者終止於失敗狀態、使用者取消、或重複的可達性嘗試顯示沒有頁面本地進展。慢不等於遺失。在修復阻塞問題後：
editppt run reset <run> --page <page_id> --agent-id <id> --confirm-lost
Reset 會將頁面恢復為 pending 狀態；從階段 2 繼續，使用新的提示和工作者。現有工件保留以供溯源和選擇性重用。
僅在更改輸入或條件後重試——永遠不要重複相同的失敗呼叫。如果缺少真正的先決條件，請保留進度並報告具體障礙。一旦輸出通過其檢查，就繼續前進；不要重複未改變的視覺品質檢查。
階段 4：最終化
當 run next 回傳最終化階段時：
editppt run finalize <run>
Finalize 會根據每個記錄的 pages/page_NNN/manifest.json 按頁面順序重建簡報，複製 .pptx 的備註欄不變，並驗證結果：有效的套件、投影片數量等於輸入頁面數量、正確的 PDF/PPTX 頁面順序、以及備註欄內容正確傳遞。它會將最終的 .pptx 放置在執行目錄的根目錄。將最終的 .pptx 複製到使用者的原始輸入資料夾或他們指定的路徑，並讓它們知道簡報已準備好。
如果 run finalize 失敗，請檢查 references/cli-helper.md 中的錯誤代碼表格。最常見的原因是遺失的 manifest.json 或不一致的頁面順序。修復根本原因（通常是缺少記錄的頁面）並重新執行 run finalize，而不要手動組裝簡報。
協助使用者
通用轉換
使用者：「讓這張投影片可以編輯。」
你： 儲存圖片檔案，然後 editppt prepare <image> --image-backend claude-native。
使用者：「將這個 PDF 轉換為可編輯的 PPT。」
你： 確保檔案存在，然後 editppt prepare <pdf> --image-backend claude-native。
使用者：「這個 PPTX 中的文字無法選取。」
你： 執行 editppt prepare <pptx> --image-backend claude-native。它會將每個投影片渲染為圖片。
錯誤與診斷
使用者：「提示我缺少某個東西。」
你： 如果缺少的是 Python 套件，請參閱 references/cli-helper.md 中的安裝步驟。如果缺少的是 token，請引導他們建立一個。
使用者：「一個工作者失敗了。」
你： 檢查執行目錄中該頁面的 logs/。重新驗證資產，如果問題是暫時的則重置該頁面。
使用者：「最終 PPT 順序錯誤。」
你： 驗證 final 中的頁面順序。如果順序錯誤，報告為錯誤。不要手動修復。
使用者：「無法執行 editppt。」
你： 從 <skill-root>/cli 安裝它。偏好 uv tool install --force --editable <skill-root>/cli。然後 editppt doctor。
使用者：「padlleocr 安裝失敗。」
你： 確認他們安裝了正確的系統依賴項（libgl1-mesa-glx、libglib2.0-0）。如果他們使用的是 Conda，請確保 pillow 與系統庫連結。
使用者：「這個轉換需要太久了。」
你： 大型 PDF 可能需要時間。確認 page_jobs.json.max_concurrent_pages 設定為合理值（預設值 6）。如果只有一個頁面，本地模式是最快的。