Nature Image2PPT - 圖片轉可編輯簡報

Nature Image2PPT

將此目錄視為完整的執行環境。僅透過以下命令執行確定性動作：

python <image2ppt-root>/cli/image2ppt/cli.py <command> ...

請使用 Python 3.10 或更新版本，並已安裝 requirements.txt。如果存在專屬的虛擬環境，請在 macOS/Linux 上將每條 python 指令替換為 <image2ppt-root>/.venv/bin/python，在 Windows 上替換為 <image2ppt-root>/.venv/Scripts/python.exe。若 doctor 指令失敗，請勿繼續；僅安裝回報的缺失依賴，然後重新執行。

請勿發現或呼叫其他技能、CLI、提示詞、Schema、模組或狀態機。

逐步閱讀本地合約

請務必閱讀 references/workflow.md。僅在設定或 doctor 失敗時閱讀 references/runtime-dependencies.md，僅在選擇或排除 OCR 問題時閱讀 references/ocr-text-hints-contract.md。

在編寫頁面清單之前，請閱讀 references/page-decision-tree.md 和 references/manifest-schema.md。僅為該頁面所需的部分添加參考文件：

• 結構化或複合頁面：references/region-decomposition.md 和 references/object-routing.md；
• 箭頭：references/manifest-arrow-extension.md；
• 點陣圖資產或影像後端工作：references/assets-provenance-contract.md。

在接收或交付輸出之前，請閱讀 references/qa-contract.md。

維持單一事實來源

• 將 page_jobs.json 視為唯一的頁面狀態來源。
• 將每個 pages/page_NNN/manifest.json 視為唯一的頁面內容來源。
• 將 deck_manifest.json 視為最終組裝的來源。
• 僅使用本機 CLI 中的 prepare、run next/dispatch/record/reset/hints/finalize 及頁面指令來進行有狀態的生命週期操作。
• 將語意區域的證據保留在 manifest.json.image2ppt_region_decomposition 中。
• 切勿建立第二個任務檔案、重建計畫、OCR 正規化器、頁面控制器、打包程式或最終化路徑。
• 讓補充性 QA 報告失敗；切勿讓它改變生命週期狀態。

將所有寫入操作保留在其所屬目錄內

• 頁面的建置、驗證、提示與 QA 僅能讀取和寫入該頁面目錄。清單路徑、記錄的資產、公式、報告、預覽圖以及 --out 覆蓋參數不得使用 ..、符號連結或絕對路徑來逃逸該目錄。唯一的例外是明確的影像工具結果（提供給 image import 或做為 process-sheet --asset-sheet-source 使用）；該結果會在成為建置依賴項之前先複製到頁面中。
• 運行層級的清單和最終輸出必須保留在已準備好的運行目錄內。最終化會在相同目錄內重建到一個暫存檔案，並僅在成功建置後才以原子方式發布。
• 將任何越界拒絕視為嚴重失敗；請勿將被拒絕的檔案複製回範圍內並當作運行輸出。

保留遷移前的行為

• 將自我包容視為路徑/匯入/進入點的遷移，而非重建行為的重新設計。
• 根據完整的本地基礎層加上保留的 Image2PPT 設定檔層來產生每個工作提示。請勿濃縮、重新解釋或替換任何一層。
• 當多種路徑都能滿足合約時，優先選擇先前已驗證過的視覺策略。將簡單的可測量物件保留為原生格式，並在原生重繪會降低保真度時，保留有邊界的複雜資產。
• 切勿為了證明運行時獨立性而重新創作一個已通過驗證的基準頁面。

執行工作流程

影像後端選擇

當代理執行環境暴露了 image_gen.imagegen 時，請使用 builtin-imagegen；這是首選後端，因為工作人員可以檢查編輯輸入並匯入明確的本機結果。僅當內建工具不可用、發生錯誤、無法讀取輸入或未回傳有效本機輸出時，才使用 CLI 影像合約。缺少可選參數（如 model、mask、size、quality 或 output path）絕不會授權回退。請在 imagegen-jobs.json 中記錄實際的生產者及允許的回退原因。

CLI 影像合約在傳輸邊界上是供應商中立的。僅針對 GPT Image 模型 ID 選擇 codex-oauth。針對任何供應商特定的模型選擇 openai-compatible-api，只要該端點實作了 OpenAI Images 相容的 /images/generations 和/或 /images/edits 架構。請勿從任務的語言模型推斷影像後端。當來源明確時使用明確後端；auto 僅對相容的 GPT Image ID 使用 Codex OAuth，否則會選擇已設定的 API，而不會將 Codex OAuth 憑證發送給第三方。

1. 預檢與 OCR 選擇

python <image2ppt-root>/cli/image2ppt/cli.py doctor --json

當已設定時，使用百度 AI Studio PADDLE_OCR_TOKEN。如果缺少該環境變數，請告知使用者一次：本機的 builtin-ink 回退方案會測量文字幾何位置，但無法辨識字元；並提供 references/ocr-text-hints-contract.md 中的設定路徑。請尊重僅離線的選擇。

2. 準備一次運行

python <image2ppt-root>/cli/image2ppt/cli.py prepare <input...> \
  --out-root output/image2ppt --image-backend builtin-imagegen

若要為可稽核的來源固定一個已設定的第三方提供者/模型，請使用 --image-backend openai-compatible-api 來準備。運行合約會記錄來自活躍專案設定或環境的 IMAGE2PPT_IMAGE_MODEL 精確值；它不會僅僅因為沒有傳遞 --model 旗標就替換為 GPT Image 預設值。

僅在有意停用 OCR 處理時才使用 --no-text-hints。在需要時無需建立新運行即可重新產生提示：

python <image2ppt-root>/cli/image2ppt/cli.py run hints <run-dir>

3. 推進並認領頁面

python <image2ppt-root>/cli/image2ppt/cli.py run next <run-dir> --json
python <image2ppt-root>/scripts/build_page_worker_prompt.py \
  <run-dir> --page <page-id> --out <absolute-page-dir>/worker-prompt.md
python <image2ppt-root>/cli/image2ppt/cli.py run dispatch \
  <run-dir> --page <page-id> --agent-id <id> --prompt-file <absolute-prompt>

如果只有一個頁面，請使用 --local 認領它，並在當前代理中重建它。如果有多個頁面，請將獨立頁面工作分派到 page_jobs.json 中指定的容量。請勿僅僅因為某個活躍工作速度較慢就重置它。

4. 重建並把關每個頁面

將結構化頁面規劃為 3–5 個語意區域，並獨立處理每個區域。使用可測量的複合圖表：測量每個節點、關係和受保護的錨點。將可測量的圓形、卡片、直線/虛線關係及簡單連線器保留為原生格式。僅針對複雜的局部子元件使用有邊界的透明資產。

將細箭頭表示為一個連線器，其箭頭在同一物件上。將填滿的箭頭表示為一個箭頭自訂圖形，其置中標籤文字在同一物件內。切勿用一條線加上一個三角形來構造普通箭頭，也切勿將整個知識圖譜扁平化為一張圖片。

使用 schema_version: 2 編寫新的頁面清單。使用具有明確 kind 和 representation 值的結構化 visual_inventory 項目，並為每個必要的品質檢查撰寫具體的 quality_evidence 觀察記錄。公式渲染是一個硬性關卡：缺少引擎、轉換器或編譯失敗必須讓頁面保持失敗狀態，除非使用者明確批准該特定公式例外，且清單中同時記錄了 user_approved_exception: true 和具體的 approval_note。

工作提示會執行確定性序列。其最終關卡為：

python <image2ppt-root>/cli/image2ppt/cli.py page build <page-dir>
python <image2ppt-root>/scripts/run_image2ppt_qa.py <page-dir>
# 第一次執行會寫入 visual-review-evidence.template.json 並保持待處理狀態。
# 檢查 source.png 與 render/rendered.png，複製並完成該範本為 visual-review-evidence.json，必要時修復，然後：
python <image2ppt-root>/scripts/run_image2ppt_qa.py <page-dir> \
  --visual-review-status reviewed \
  --visual-review-evidence <page-dir>/visual-review-evidence.json
python <image2ppt-root>/cli/image2ppt/cli.py page contact-sheet <page-dir>

證據檔案必須涵蓋當前的來源/渲染哈希值以及每個必要檢查的具體觀察結果。--visual-review-notes 是選用上下文，不能替代證據檔案。

僅在標準驗證以及 Image2PPT 區域、箭頭和渲染關卡通過後才進行記錄：

python <image2ppt-root>/cli/image2ppt/cli.py run record \
  <run-dir> --page <page-id> --agent-id <id>

使用相同的 run reset → dispatch → record 生命週期來修復被拒絕的頁面。

5. 最終化並重新驗證重建的簡報

當 run next 回報 finalize 時，執行：

python <image2ppt-root>/cli/image2ppt/cli.py run finalize <run-dir>
python <image2ppt-root>/scripts/run_final_image2ppt_qa.py <run-dir>
# 第一次執行會寫入 final/visual-review-evidence.template.json 並保持待處理狀態。
# 檢查每個渲染的投影片，完成 final/visual-review-evidence.json，然後：
python <image2ppt-root>/scripts/run_final_image2ppt_qa.py <run-dir> \
  --visual-review-status reviewed \
  --visual-review-evidence <run-dir>/final/visual-review-evidence.json

最終化會從頁面清單重建、保留原始投影片備註、驗證封裝，並寫入由 deck_manifest.json 記錄的輸出。最終 QA 會重新應用清單中的箭頭、驗證箭頭的原子性與複合結構、渲染每個投影片、檢查投影片備註的完整性，並寫入 final/image2ppt_qa.json。

交付

回傳最終 PPTX 路徑、標準的最終驗證結果及 final/image2ppt_qa.json。報告哪些複雜視覺元素仍然是可替代的點陣圖資產。在任何頁面/最終關卡處於待處理或失敗狀態時，請勿將簡報標記為完成。