前言¶
在 DSH 裏讓智能體操作 Godot 項目，常見做法是掛一個 godot-mcp MCP 服務：多一層協議、多一個 Python/Node 進程，還要單獨維護編輯器插件。遊戲側雖然已有 McpInteractionServer 在 127.0.0.1:9090 上監聽換行分隔的 JSON，但 harness 側仍要通過 MCP 中轉。
godot-bridge 把這條鏈路收進 DSH 宿主插件：不跑 MCP、不啓獨立 Python 服務、不改編輯器 addon。宿主直接 spawn Godot 進程，經短連接 TCP 與遊戲內 autoload 對話，工具以 godot_* 形式註冊進會話。下面介紹它的定位、能力與安裝方式。
這是什麼¶
godot-bridge 是維護者 Smalldy 發佈的 DeepSeek Harness 原生插件（GitHub：Smalldy/godot-bridge，當前包版本 0.1.5，MIT 許可證）。分類上屬於工作流類插件。
一句話定位：在 DSH 會話裏啓動並驅動正在運行的 Godot 4.x 遊戲，協議與 godot-mcp 使用的 in-game TCP 交互服務一致，用一等 agent 工具替代 MCP 服務。
工作原理¶
遊戲項目需具備 McpInteractionServer autoload（mcp_interaction_server.gd），默認監聽 127.0.0.1:9090，報文爲換行分隔 JSON。godot-bridge 在 harness 內：
godot_run_project以godot -d --path …拉起調試進程，等待 9090 就緒。godot_command、godot_screenshot、godot_ping等通過一次性node -ebridge 連 TCP，發一行命令、讀一行響應後退出（適配服務端單連接、單命令的_busy語義）。- 無頭編輯類操作走
godot --headless --script godot_operations.gd等腳本，無需遊戲進程在線。
spawn 走 harness 的 raw subprocess 服務（非沙箱 shell），以便 Godot 寫入 user:// 等路徑時不被 DSH 文件沙箱攔截。
若項目尚無 McpInteractionServer，godot_run_project 會自動把 vendored 文件拷到 autoload/ 並在 project.godot 註冊；非 Godot 項目不受影響。
核心工具¶
README 將各工具與 godot-mcp 對照列出；此處按用途歸納已覈實能力。
運行中的遊戲（TCP 9090）¶
| 工具 | 作用 |
|---|---|
godot_run_project |
調試模式啓動項目，等待端口 9090 |
godot_stop_project |
終止已啓動的遊戲進程（樹範圍 kill） |
godot_get_debug_output |
增量讀取子進程 stdout/stderr |
godot_command |
向交互服務發送任意命令（約 130 個 game_* 能力合一）：get_scene_tree、eval、get/set_property、call_method、click、key_press、screenshot、raycast、serialize_state、ui_* 等 |
godot_screenshot |
視口截圖，base64 PNG |
godot_ping |
探測 9090 是否響應；附帶已安裝/最新插件版本信息 |
無頭與項目靜態操作¶
| 工具 | 作用 |
|---|---|
godot_headless_op |
16 種無頭靜態操作（讀/改場景節點、掛腳本、建資源、保存場景等），無需運行遊戲 |
godot_validate_script |
無頭 GDScript 編譯檢查，返回 {valid, errors} |
godot_set_project_setting |
按類型寫入 project.godot 任意段鍵值 |
godot_manage_autoloads |
列出/增刪 autoload 單例 |
godot_manage_input_map |
列出/增刪輸入動作（Godot 4 鍵碼，修正 godot-mcp 的 Godot 3 基線問題） |
godot_manage_export_presets |
管理 export_presets.cfg |
godot_create_script |
生成 GDScript 模板 |
godot_create_project |
腳手架項目，可選 Godot .NET .csproj |
godot_export_project |
無頭導出（--export-release / --export-debug） |
配置¶
| 工具 | 作用 |
|---|---|
godot_set_engine_path |
將 Godot 可執行文件路徑寫入設置（godotPath / settings.yaml 的 godot-bridge: 段），熱加載 |
純文件讀寫由 DSH 原生文件工具覆蓋；帶 Godot 專有寫法的項（輸入映射、導出預設、project.godot 類型等）由上述專用工具處理。完整對照見倉庫 COVERAGE.md。
環境要求¶
- 已安裝 DeepSeek Harness（具備 host runtime 的會話）。
- Godot 4.x 可執行文件：優先級爲工具參數
godot_path→ 設置項godotPath→ PATH 上的godot命令。應使用真實 exe 全路徑，避免版本管理器 shim。 node在 PATH 上（bridge 一次性連接用）。- 目標 Godot 項目具備或可自動安裝
McpInteractionServerautoload。
安裝與啓用¶
插件須通過 DSH bundle 機制安裝，勿複製到 ~/.dsh/.agent-presets/...（無法解析 @deepseek-ai/dsh-tools）。
推薦一條命令（需 dsh CLI）：
dsh plugin --profile web add github:Smalldy/godot-bridge
dsh plugin 爲 pnpm 轉發：包裝入 profile 的 node_modules，並通過 cordis.patch.yml 把 tool-godot-bridge 寫入該 profile 的 dsh.profile.bundles。web 爲 Web 應用默認 profile，不新建 profile。重啓 DSH 後，該 profile 下會話可見十六個 godot_* 工具。
本地路徑或 tarball 同樣支持：
dsh plugin --profile web add ./path/to/godot-bridge
卸載：
dsh plugin --profile web remove godot-bridge
先 godot_stop_project 停遊戲；卸載並重啓後工具從會話移除，web profile 本身不變。
更新：
dsh plugin --profile web update godot-bridge
插件加載時會 best-effort 比對 GitHub main 上 package.json 版本；若有更新，系統提示會出現「godot-bridge update available: installed X, latest Y」。godot_ping 也會報告 plugin_version / latest_version。
社區登記見 awesome-dsh-plugin（topic：dsh-plugin）。
典型用法¶
1. 指定 Godot 路徑（PATH 無 godot 時）¶
由模型詢問用戶後調用 godot_set_engine_path，或配置 Web 插件頁 / settings.yaml 中 godot-bridge: 段的 godotPath。
2. 啓動項目並探活¶
godot_run_project # project_path 指向 Godot 項目根
godot_ping # 確認 9090 有響應
3. 查詢場景與交互¶
通過 godot_command 發送與 godot-mcp 相同的 JSON 行協議，例如：
{"command": "get_scene_tree", "params": {}, "id": "1"}
常用命令還包括 get_ui_elements、eval、click、key_press、serialize_state 等；具體參數以交互服務實現爲準。
4. 截圖¶
godot_screenshot 直接返回 base64 PNG，等價於 godot-mcp 的 game_screenshot。
5. 無頭改場景 / 校驗腳本¶
無需運行遊戲時：
godot_headless_op：場景與資源靜態編輯。godot_validate_script：編譯檢查 GDScript。godot_set_project_setting、godot_manage_autoloads、godot_manage_input_map：改project.godot與相關配置。
6. 查看調試輸出¶
godot_get_debug_output 按偏移增量拉取子進程日誌，配合 godot_run_project 排錯。
適用場景與注意¶
適合誰
- 已在 DSH 中用智能體開發或測試 Godot 4.x 遊戲/工具項目。
- 希望去掉
godot-mcpMCP 層，保留現有McpInteractionServer與 9090 協議的工作流。 - 需要無頭編輯
project.godot、輸入映射、導出預設，並與運行中游戲操控在同一套godot_*工具裏完成。
注意事項
- 插件以當前 DSH 進程權限運行子進程與文件操作；安裝前請閱讀源碼與 MIT 許可證，確認符合你的安全策略。
- Godot 路徑勿用版本管理 shim；否則 spawn 或
user://行爲可能異常。 - 交互服務單連接：依賴短連接 bridge 設計，勿長時間佔用同一 TCP 會話。
- SkillHub 目錄頁（
skillhub.cn）爲社區索引，與 DeepSeek / 幻方無官方從屬；安裝命令以 README 與dsh plugin爲準。
結尾¶
godot-bridge 把 Godot 4.x 的 in-game TCP 協議直接接到 DSH 宿主，用十六個原生工具覆蓋 godot-mcp 的主流程，並補上 Godot 4 輸入映射等專有寫能力。若你已在 harness 裏做 Godot 智能體工作流，可用官方 bundle 命令裝入 web profile 試用。
- 目錄頁：https://www.skillhub.cn/plugins/Smalldy/godot-bridge
- GitHub：https://github.com/Smalldy/godot-bridge
