前言¶
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，详细信息请参考项目仓库。
