前言¶

在 Windows 上让 DeepSeek Harness（DSH）不只读写文件和跑终端，还要点按钮、读窗口、跟进控件变化，通常需要单独接一套桌面自动化后端，再在 DSH 里挂工具、管会话和权限。自己拼 NDJSON 连接、引用隔离和唤醒逻辑，工作量大，也容易和模型侧配置搅在一起。

下面介绍社区插件 dsh-winbot（npm/DSH 包名仍为 dsh-gui2api-bot，以兼容现有 bundle）。它通过 GUI2API 操控 Windows 桌面，并在 DSH 侧提供可编辑人格、持久记忆和定时唤醒。维护者为 daoxiang0520，SkillHub 分类为「客户端」。当前基线版本 0.5.0，注册 28 个工具。本仓库不包含 GUI2API 后端、用户人格、记忆、profile 或模型凭据。

这是什么¶

dsh-winbot 是运行在 Windows 10/11 上的 DSH 插件：DSH 负责模型调用、对话、文件/终端工具、权限和会话持久化；GUI2API 负责控件发现、调用、恢复和增量登记；插件负责常驻 NDJSON 连接、按会话隔离引用、人格/记忆装配及周期唤醒。结果不明时不自动重放。

运行还需要 Python 3.11+、Node.js >=22.13，以及兼容的 DSH >=0.2.1-rc.2 <0.3.0。VM 安装/启动脚本另需 PowerShell 7。桌面必须登录并解锁；实际权限由 Windows 账户与 DSH 设置决定。

核心功能¶

桌面 GUI 工具链¶

插件向模型暴露一组以 gui_ 和 bot_ 为前缀的工具，覆盖 attach、发现、调用、窗口动作，以及 bot 上下文与唤醒。默认流程为：gui_apps → gui_attach → gui_find/gui_discover → gui_invoke/gui_discovery_invoke → 观察结果。

分组目录的 controls[].id 需配合 method，也可直接选择某个 operations[].id。MSAA/Qt/legacy 默认动作在无后置条件时可能被拦截；可显式选择 click_input，或通过 postcondition 做只读后置校验。outcome_unknown 时应先核对实际状态，历史关系与标签不授权自动执行。完整语义见 GUI2API 的 可靠性契约。

多模态资源¶

gui_resources → gui_resource_describe/gui_resource_read → gui_resource_release 用于发现、读取及清理控件关联的资源。发现不下载；source 取源字节，rendered 是显式读取渲染内容，不承诺原文件。默认只返回文件引用、MIME 和 SHA256。delivery:native 在宿主提供附件服务时导入正式图片附件；配置的模型和适配器仍需支持图像输入。需要与 GUI2API 后端同步更新，接口说明见 RESOURCES.md。

缓存与会话内引用¶

配套 GUI2API 后端支持会话内绑定缓存、定点读取与失效后的重新观察。插件提示会优先复用 ref/operation ID；明确目标的后置条件优先传 ref，需要重判唯一性时用 selector。不要每步强制 refresh。详见 CACHE.md。

人格、记忆与持续运行¶

首次使用可复制公开的 personas/小鲸鱼.md，后续不覆盖用户修改。运行数据放在 dataDir 或环境变量 GUI2API_BOT_HOME 指向的目录；未指定时为当前用户的 .dsh-gui2api-bot，其中包括 人格.md、记忆.md、任务.md、bot-state.json 等。

bot_start 明确绑定当前会话，周期范围 60–86400 秒；忙碌时不重复塞入唤醒。bot_stop 停止未来唤醒；数据目录中的 STOP 文件会阻止未来桌面请求并停止唤醒。重启后尝试恢复同一持久会话，失败或上次结果未明时暂停。

安装与启用¶

插件不会自动下载 GUI2API 后端。推荐将两个仓库放在同一父目录下，例如：

WinBot/
  GUI2API/       guictl.py、native/、bridges/
  dsh-winbot/    index.mjs、lib/、scripts/、personas/

插件会优先使用配置 guiRoot，其次环境变量 GUI2API_ROOT，再探测相邻的 GUI2API 目录。

已有 DSH：手工接入¶

先安装 GUI2API 的依赖，再在用于启动 DSH 的同一个 PowerShell 中设置路径：

$gui = 'C:\Projects\WinBot\GUI2API'
$plugin = 'C:\Projects\WinBot\dsh-winbot'
python -m venv "$gui\.venv"
& "$gui\.venv\Scripts\python.exe" -m pip install -r "$gui\requirements-gui.txt"

$env:GUI2API_ROOT = $gui
$env:GUI2API_PYTHON = "$gui\.venv\Scripts\python.exe"
$env:GUI2API_BOT_HOME = 'C:\Projects\WinBot\bot-data'

dsh plugin --profile gui2api-bot add $plugin
dsh --profile gui2api-bot

先确保目标 DSH profile 已存在。模型和 API Key 在 DSH 中配置；插件更新与 GUI2API 后端更新是两件事。

也可在插件配置中写入路径与超时等字段：

config:
  guiRoot: C:/Projects/WinBot/GUI2API
  python: C:/Projects/WinBot/GUI2API/.venv/Scripts/python.exe
  dataDir: C:/Projects/WinBot/bot-data
  requestTimeoutMs: 60000
  maxSessions: 4

新 Windows VM：可选脚本¶

在插件目录下可使用 Setup-VM.ps1 与 Start-VM.ps1 初始化虚拟环境、安装依赖并在指定 profile 中注册插件。Start-VM.ps1 默认新会话权限为 danger-full-access，可通过 -PermissionMode 改为 workspace-write 或 read-only。需要登录后自启动时，由操作者执行 Install-Autostart.ps1；脚本注册交互登录任务，不配置自动登录。

典型用法¶

带后置条件的 invoke¶

当默认 invoke 效果不可靠时，可显式指定方法与只读后置条件，例如：

{
  "ref": "当前按钮引用",
  "method": "invoke",
  "postcondition": {
    "selector": {"name": "实际观察到的面板", "role": "Pane", "exact": true},
    "field": "exists", "equals": true, "timeout_ms": 1500
  }
}

后置校验只读取，不重复动作。

启动周期唤醒¶

在 DSH 会话中通过 bot_start 绑定当前会话并设置 60–86400 秒范围内的唤醒间隔；无待办时应安静结束。查看状态用 bot_status，停止用 bot_stop。

适用场景与注意¶

适合需要在 已登录、已解锁的 Windows 桌面 上，用 DSH 驱动 GUI 自动化，并希望人格、记忆与定时任务与 GUI 工具在同一插件内装配的开发者。插件以当前 DSH 进程及 Windows 账户权限运行，不代替 DSH/Windows 的权限管理；安装前应阅读仓库源码与许可证（含 LICENSE.qq-bridge 等）。

本插件依赖外部 GUI2API 仓库与 Python 虚拟环境；DSH 的音频、视频、文档类资源当前仍以文件引用为主，尚未在插件侧加入转写或文档解析。已有 Host 的模块缓存不会因源码文件变化自动失效，更新后需按 DSH 与 Node 的惯例重启或重新加载。

社区目录 SkillHub 插件页 与 GitHub 仓库相互独立，与 DeepSeek / 幻方无官方从属关系；以仓库 README 与 GUI2API 文档为准做版本对齐。

结尾¶

dsh-winbot 把 GUI2API 的 Windows 桌面能力与 DSH 的模型、会话和工具体系接在一起，并用 28 个注册工具覆盖发现、调用、资源、学习与 bot 唤醒。若你在 Windows 上搭建 Harness 智能体并需要可控的桌面操作与人格持久化，可从官方 README 的路径与 profile 步骤起步。

• 目录页：https://www.skillhub.cn/plugins/daoxiang0520/dsh-winbot
• GitHub：https://github.com/daoxiang0520/dsh-winbot