前言¶
在 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
