前言¶
DeepSeek Harness (DSH) 的核心理念是「一切皆插件」。在 AI 輔助開發遊戲或交互應用時，開發者需要頻繁驗證 Godot 4 項目的運行效果。傳統的流程往往需要手動在終端執行導出命令，或者打開獨立的編輯器窗口，打斷對話流的連貫性。dsh-godot-preview 插件旨在解決這一問題，它將 Godot 的預覽能力直接集成到 Harness 的會話視圖中，無需修改 Harness 核心代碼，通過獨立的客戶端模塊提供 Web 和 Native 兩種模式的實時預覽。
核心功能¶
該插件獨立安裝，不依賴 DSH 核心組件。它通過 Host 服務管理 Godot 進程的生命週期，並在 Client 端提供 UI 展示。主要能力包括：
- 環境驗證：自動檢查當前工作區的
project.godot文件，並驗證用戶指定的 Godot 4.x 可執行文件是否存在。 - Web 預覽：運行 Web Debug 導出，將預覽結果嵌入到 Harness 的界面中。爲了保證兼容性，推薦使用 GDScript 和 Compatibility 渲染器。
- Native 預覽：在插件內啓動受管的原生 Godot 窗口，支持啓動和停止操作。
- 文件監視與構建：監視項目文件變化，支持可配置的去抖動和單次飛行重建，在構建期間合併變更請求。
- 失敗回退：如果後續的導出失敗，會自動保留最後一次成功的 Web 預覽結果。
- 日誌與調試：顯示有界的 Host/Export/Runtime 日誌，並提供結構化的失敗位置定位。
- 持久化配置：將 Godot 路徑和預覽偏好設置保存在
DSH_HOME目錄下。
安裝與啓用¶
插件通過 DSH 的插件系統進行安裝。安裝後，需要在 Harness 的設置中配置 Godot 4.x 的路徑。
- 安裝插件：
在終端或命令行中執行以下命令，通過 GitHub 安裝插件：
dsh plugin --profile web add github:baiyuscc13724-max/dsh-godot-preview
*注：也可以通過 DSH 的設置頁面進入插件市場搜索並安裝。*
- 配置 Godot 路徑：
安裝完成後，刷新頁面。在 Harness 界面中進入Settings → Godot Preview，輸入已安裝的 Godot 4.x 可執行文件的絕對路徑。如果路徑留空，插件會嘗試在系統 PATH 中搜索。
使用方式¶
完成配置後，即可在對話視圖中使用預覽功能。
- 在 Godot 項目根目錄打開一個 Harness 會話。
- 打開 Godot Preview 對話視圖。
- 在設置中確認 Godot 4.x 可執行文件路徑，並選擇 Web 或 Native 模式。
- 點擊 Start 按鈕啓動預覽。
- Web 模式：僅展示最後一次成功的導出結果。
- Native 模式：會彈出一個受管的原生 Godot 窗口。
- 點擊 Stop 按鈕可以停止預覽，該操作具有冪等性。
適用場景與注意¶
該插件適合需要頻繁查看 Godot 項目運行狀態的開發者，尤其是利用 AI 進行腳本編寫和交互邏輯調試的場景。
重要注意事項：
- 不包含 Godot 本體：插件本身不會下載或安裝 Godot 引擎，也不會捆綁 Chromium、Android/Xcode 工具鏈、導出模板或小遊戲 SDK。用戶必須自行安裝 Godot 4.x。
- 網絡隔離：Web 預覽和本地 API 僅監聽
127.0.0.1（迴環地址），網絡訪問僅限於本地。插件不包含任何雲服務、賬戶、API 密鑰、遙測或遠程數據保留功能。 - 本地存儲：用戶數據持久化僅限於
DSH_HOME下的插件設置，生成的預覽輸出僅保存在項目根目錄下的.godot-harness子目錄中。 - 安全機制：插件使用
spawn(..., { shell: false })啓動子進程，並對請求頭、Host/Origin、路徑遍歷進行嚴格校驗，請求體和日誌輸出有大小限制。
短結尾¶
dsh-godot-preview 插件通過將 Godot 的預覽流程標準化和集成化，減少了開發者在終端與編輯器之間切換的頻率。它通過受控的子進程管理和本地化的網絡策略，在不增加系統複雜度的前提下，爲 Harness 用戶提供了可靠的 Godot 4 項目預覽能力。插件源碼與文檔託管在 GitHub，詳細信息請參考項目倉庫。
