dsh-winbot

DSH WinBot

通过 GUI2API 操控 Windows 桌面的 DeepSeek Harness 插件，并提供可编辑人格、持久记忆和定时唤醒。

当前基线 0.5.0，注册 24 个工具。npm/DSH 包名继续使用 dsh-gui2api-bot，以兼容现有 bundle；仓库名为 dsh-winbot。本仓库不包含 GUI2API 后端、用户人格、记忆、profile 或模型凭据。

组成

• DSH 提供模型调用、对话、文件/终端工具、权限和会话持久化。
• GUI2API 提供控件发现、调用、恢复和增量登记。
• 本插件负责常驻 NDJSON 连接、按会话隔离引用、人格/记忆装配及周期唤醒。结果不明时不自动重放。

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

分别克隆两个仓库

mkdir C:\Projects\WinBot
cd C:\Projects\WinBot
git clone https://github.com/daoxiang0520/GUI2API.git
git clone https://github.com/daoxiang0520/dsh-winbot.git

推荐目录：

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 profile。
dsh plugin --profile gui2api-bot add $plugin
dsh --profile gui2api-bot

先确保目标 DSH profile 已存在。需要创建新 profile 时可使用 DSH 的 --from-default-profile web --dump-config；不要把已有 profile 当作初始化目标。

也可在已有插件配置中设置：

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

模型和 API Key 在 DSH 中配置。插件更新和后端更新是两件事；已有 Host 的模块缓存不会因为源码文件变化自动失效。

新 Windows VM：可选脚本

cd C:\Projects\WinBot\dsh-winbot
.\scripts\Setup-VM.ps1 -GuiRoot ..\GUI2API -BotHome ..\bot-data
.\scripts\Start-VM.ps1 -GuiRoot ..\GUI2API -BotHome ..\bot-data

Setup-VM.ps1 创建后端虚拟环境、安装依赖，并在指定 profile 中安装插件；只初始化尚不存在的 profile。可通过 -DshVersion、-DshProfile、-MessengerBridges 调整。Start-VM.ps1 默认新会话权限为 danger-full-access，可用 -PermissionMode workspace-write 或 read-only 修改，不提升 Windows 令牌。

需要登录后启动时，由操作者明确执行：

.\scripts\Install-Autostart.ps1 -GuiRoot C:\Projects\WinBot\GUI2API -BotHome C:\Projects\WinBot\bot-data

这会注册交互登录任务，不配置自动登录。插件不代替 DSH/Windows 的权限管理。

桌面工具

工具 · 用途 gui_schema / gui_apps / gui_targets · 协议、窗口和已有 CDP 页面 gui_attach / gui_detach / gui_reset · 来源和会话连接生命周期 gui_find / gui_scan / gui_describe / gui_invoke · 当前控件、方法及一次执行 gui_discover / gui_discovery_describe / gui_discovery_invoke / gui_discovery_events · 聚合目录、精确绑定和变化观察 gui_learning_graph / gui_rebind · 增量观察关系和当前引用解析 gui_learning_export / gui_learning_import · 只含哈希候选的导出/导入 gui_window_action · 恢复、前台、标准菜单取消、明确 ESC、建树请求及终端读取 bot_context / bot_memory · 人格文件位置、记忆和任务 bot_start / bot_stop / bot_status · 常驻唤醒和状态

默认流程：gui_apps → gui_attach → gui_find/gui_discover → gui_invoke/gui_discovery_invoke → 观察结果。分组目录的 controls[].id 需配合 method，也可直接选择某个 operations[].id。

invoke 的提供者效果可能不可靠，MSAA/Qt/legacy 默认动作在无后置条件时拦截。显式选择广告方法 click_input，或提供 GUI 后置条件：

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

后置校验只读取，不重复动作。outcome_unknown 时先核对实际状态；历史关系、哈希候选和标签均不授权自动执行。完整语义见 GUI2API 的 可靠性契约。

人格、记忆和持续运行

首次使用复制公开的 personas/小鲸鱼.md，后续不覆盖用户修改的人格。来源和许可见 personas/SOURCES.md 与 LICENSE.qq-bridge。这是公开角色卡，不能当作其他私人 Bot 人格的原版。

运行数据放在 dataDir / GUI2API_BOT_HOME，未指定时为当前用户的 .dsh-gui2api-bot：

人格.md          每轮装配时读取
记忆.md          已确认事实与约定
任务.md          责任和进度
bot-state.json   唤醒绑定与投递状态
versions/        bot_memory 修改前的历史

bot_start 明确绑定当前会话，周期范围 60–86400 秒；忙碌时不重复塞入唤醒。没有待办时应安静结束。重启后恢复同一持久会话，失败或上次结果未明时暂停。bot_stop 停止未来唤醒，DSH 停止按钮取消当前执行；数据目录中的 STOP 文件阻止未来桌面请求并停止唤醒。

测试

先克隆并准备相邻 GUI2API 仓库，在插件目录运行：

npm ci
npm test

测试使用临时数据目录和自建对象，不写用户人格/profile。test/owned-*.mjs 由拥有 fixture 进程的验证器显式调用；真实 QQ 验收脚本另需目标、报告路径与 --send，不属于自动测试。聚合验证见 docs/VALIDATION.md。