AI Blackhole 導演
使用此技能協助使用者處理本機 AI Blackhole Studio 全景導演工作階段。
進入點
預設工作流程為本機:
- 使用
scripts/local_import.py將本地圖片複製到暫存的本機導演工作階段。 - 啟動本機靜態伺服器。
- 開啟產生的
http://127.0.0.1:<port>/panorama-viewer.html?image=...URL。
此技能包含位於 assets/panorama-director-deploy-v1.2.zip 的導演套件。若未提供 --web-dir,輔助工具會解壓縮並使用此內建套件。
請勿將 https://aiblackhole.net/panorama-viewer 作為此技能的預設路徑。公開網站仍可作為診斷或分享參考,但本機部署是主要模式。
核心工作流程
- 如果使用者提供本地圖片路徑,請閱讀
references/local-import.md並執行scripts/local_import.py。 - 當瀏覽器控制可用時,開啟輔助工具輸出的 URL;否則將 URL 提供給使用者。
- 當瀏覽器控制可用時,確認頁面已載入且
document.body包含panorama-loaded類別。 - 確定使用者的下一個任務:
- 使用導演功能
- 學習某項功能
- 自訂或包裝本機導演檔案
- 若需功能指引,請閱讀
references/feature-guide.md。 - 若遇本機伺服器、資產、圖片、路由或瀏覽器問題,請閱讀
references/troubleshooting.md。 - 保持指示實用且面向使用者。自動開啟圖片時,優先使用本機輔助工具。
本機圖片匯入
當使用者提供本地圖片路徑並希望自動開啟時,請使用:
python <skill-dir>/scripts/local_import.py "<image-path>" --open
當使用者僅希望部署/開啟本機導演而不指定圖片時,請使用:
python <skill-dir>/scripts/local_import.py --open
僅在使用者明確要求使用自訂導演網頁資料夾時,才傳遞 --web-dir。
使用輔助工具輸出的 URL 開啟本機工作階段。向使用者說明圖片會被複製到暫存的本機網頁工作階段中,不會上傳到任何公開網站。
瀏覽器檢查
當瀏覽器控制可用時,請驗證:
- 產生的本機 URL 可載入。
- 上傳/匯入的圖片名稱出現在檔案元資料區域。
- 載入後,空的上傳狀態已被隱藏。
document.body.dataset.viewMode對於全景圖片為panorama,對於一般圖片為flat。- 主要互動功能正常運作:新增角色、新增物件、新增遮蔽物、變換選取項目、隱藏/顯示側邊欄、儲存螢幕截圖。
可選的公開參考
歷史公開 URL 為:
https://aiblackhole.net/panorama-viewer
請勿用於自動匯入本地檔案。公開網頁無法讀取任意本地檔案路徑,請改用本機輔助工具。
故障排除順序
針對本機工作階段,請檢查:
- 本機伺服器程序正在執行。
- 產生的
imports/<image>URL 回傳 HTTP 200。 panorama-viewer.html與panorama-director.js存在於本機網頁資料夾中。- 連接埠未被舊工作階段佔用。
- 如果圖片仍無法載入,檢查瀏覽器主控台/網路錯誤。
禁止事項
- 請勿強制將本地檔案上傳至公開網站。
- 請勿將公開網站作為此技能的預設路徑。
- 未經使用者明確同意,請勿修改進行中的部署。
- 在檢查伺服器程序、連接埠、路由、資產路徑與瀏覽器主控台基本資訊之前,請勿假設載入錯誤是由應用程式本身造成。