图形界面交接 xxszyh/dsh-gui-handoff

dsh-gui-handoff

一个 DeepSeek Harness 技能：把命令行验证过的操作，交接给你的图形界面。

把命令行验证过的操作，交接给你的图形界面。

English · 中文

问题所在

有一道没人点破的鸿沟：智能体在终端里能把一件事做得完美，用户却依然没法手动复现——因为没人走过图形界面那条路，也没人写下该点哪里。

告诉用户「直接跑这个脚本」不算解决。这只会留给他们一个黑盒：学不到东西，换台机器就崩，而且完全覆盖不了那些根本没有配置文件的图形界面操作。

这个技能做什么

两条路径，默认走路径 B：

| | 路径 B（默认） | 路径 A（兜底） |
| 做法 | 智能体真的把图形界面跑一遍 | 把步骤固化成配置文件 |
| 产出 | 带真实截图的教程 | 一个配置文件 + 一次按键 |
| 用户能学会 | 能 | 不能 |
| 换台新机器还能用 | 能 | 不能 |

路径 B 跑一条五阶段链路——驱动 → 观察 → 截图 → 重建 → 标注——并且死守两件容易被跳过的事：

- 要事实，不要感觉。 构建成没成功，看产物是否存在、时间戳是多少。程序有没有跑起来，看它的输出或调试器的退出码。截图是给人看的，永远不作为判定依据。
- 验证用户能复现。 「机器跑通了」不等于「用户跑通了」。教程必须列出自己的前置条件，用户必须自己走一遍，走完之后场景必须重置，这样用户才能分清哪些是自己的成果，哪些是原本就有的状态。

真正有价值的部分

skills/gui-handoff/SKILL.md 里写着 30 多条硬约束，几乎每一条都是拿真实的调试时间换来的：

- 链接器和调试器遇到中文 / UTF-8 路径就失败——以及那个陷阱：命令行能成功，图形界面却失败，因为 shell 会悄悄把参数重新编码成工具碰巧想要的那种编码
- 中文输入法会污染注入的按键（by → 不要）
- 为什么用标题子串匹配窗口很危险（出过三次独立事故），以及该怎么做
- 为什么 Chromium/Electron 需要扫描码，以及为什么焦点会悄悄留在另一个窗口上
- 为什么从截图里读细小文字，得先裁剪再放大
- 手写的 PNG 编码器怎么把每张截图都变成三份横向压扁的副本——以及为什么这让视觉模型看起来像在撒谎，而它说的其实是真话

外加 七条工作纪律，每一条都是先违反了才写下来的。最重要的一条：

接受一次验证之前，先检查判定标准本身。
有份教程曾写着「看到产物就说明成功了」。用户照着做，报告成功，智能体宣布验收测试通过——可那条标准只覆盖了构建，没覆盖运行。当标准本身是错的，通过毫无价值。

安装

dsh plugin --profile <your-profile> add dsh-gui-handoff

或者从本地检出安装：

dsh plugin --profile <your-profile> add /path/to/dsh-gui-handoff

插件注册一个技能（gui-handoff，rank 600 —— 最低优先级，所以你在项目或用户技能目录里本地改过的副本总是优先）。

包含什么

lib/index.js skill provider (no runtime dependencies)
cordis.patch.yml bundle manifest
skills/gui-handoff/SKILL.md the skill itself
tools/gui-control/server.py reference GUI-control MCP server (Windows)
tools/notify-takeover.ps1 countdown notice shown before taking the mouse

tools/ 目录是面向 Windows 的参考实现，不是必需项。可移植的是工作流和约束；Linux 和 macOS 需要各自的对等物。

依赖

- DeepSeek Harness >= 0.1.5-rc.1
- 路径 B 的驱动环节需要某种驱动目标系统图形界面的手段。本仓库提供一个 Windows 版本；没有它，技能会降级到 B2–B4（用户操作，智能体观察），而不是直接失败。

许可证

MIT。

它解决什么

有一个没人命名的落差：智能体能在终端里把事情做对，用户却无法用手复现 ——因为没人走过图形界面那条路，也没人写下来该点哪里。

告诉用户「你跑一下这个脚本」不是解法。它留下的是一个学不会的黑盒、换台机器就废，而且根本覆盖不了那些没有配置文件的图形界面操作。

这个技能做什么

两条路，默认走 B：

| | 路径 B（默认） | 路径 A（降级） |
| 做法 | 智能体真的操作 GUI 走一遍 | 把步骤固化成配置文件 |
| 产出 | 带真截图的教程 | 配置文件 + 一键操作 |
| 用户学到 | 是 | 否 |
| 换机器可用 | 是 | 否 |

路径 B 跑一条五环链 —— 驱动 → 观察 → 记录 → 还原 → 标注 —— 并坚持两件最容易被跳过的事：

- 用地面真值，不用感觉。 构建是否成功，看产物是否存在 + 时间戳；程序是否真的运行了，看程序输出或调试器退出码。截图是给人看的， 永远不作判据。
- 验证用户能复现。「机器跑通」不等于「用户跑通」。教程必须列出自己的前提，用户必须实走一遍，跑完还要重置现场 —— 否则用户分不清产物是自己跑出来的还是早就有的。

真正值钱的部分

skills/gui-handoff/SKILL.md 里是 30 多条硬约束，几乎每一条都是拿真实的调试时间换来的：

- 链接器与调试器的中文/UTF-8 路径失败 —— 以及那个陷阱： 命令行能过、图形界面却挂，因为 shell 会悄悄把参数重新编码成工具恰好想要的编码
- 中文输入法污染注入的按键（by → 不要）
- 为什么按标题子串匹配窗口极其危险（三次独立事故），以及该怎么做
- 为什么 Chromium/Electron 需要扫描码，为什么焦点可能悄悄留在另一个窗口
- 为什么从截图里读小字必须先裁剪放大
- 一个手写 PNG 编码器如何把每张截图变成三份横向压扁的副本 ——以及它如何让一个视觉模型背了「胡说」的黑锅，而它说的全是真的

外加七条工作纪律，每一条都是先违反、才写下的。最重要的那条：

验收之前，先检查判据本身。
有一份教程写着「看到产物就是成功」。用户照着做了、报告成功，智能体也据此宣布验收通过 —— 但那个判据只覆盖构建，不覆盖运行。
判据错了，通过就是假的。

安装

dsh plugin --profile <你的 profile> add dsh-gui-handoff

或从本地目录安装：

dsh plugin --profile <你的 profile> add /path/to/dsh-gui-handoff

插件注册一个技能（gui-handoff，rank 600 —— 最低优先级，因此你在项目或用户技能目录里本地改过的同名副本总是优先）。

目录

lib/index.js skill provider（无运行时依赖） cordis.patch.yml bundle 清单 skills/gui-handoff/SKILL.md 技能本体 tools/gui-control/server.py 参考用的 GUI 控制 MCP server（Windows） tools/notify-takeover.ps1 抢鼠标前的倒计时提示

tools/ 是面向 Windows 的参考实现，不是必需项。可移植的是流程与约束； Linux / macOS 需要各自的对等物。

依赖

- DeepSeek Harness >= 0.1.5-rc.1
- 路径 B 的驱动环节需要某种驱动目标系统图形界面的手段。本仓库提供一个 Windows 实现；没有它时，技能会降级到 B2–B4（用户操作、智能体观察），而不是直接失败。

许可

MIT。