前言¶

在 DeepSeek Harness（DSH）里用智能体驱动 GUI、对比截图或批量渲染时，人往往只能盯着屏幕等：当前跑到哪一步、这一步期望什么、是否已经失败、以及更实际的问题——现在能不能再动鼠标和键盘。终端日志可以事后查，但很难在运行中一眼回答「别打断测试」还是「可以接手了」。

下面介绍社区插件 dsh-testhud（维护者 yijiezhong）：在 macOS 上于被测应用之上绘制一块始终置顶、可穿透点击的进度面板，并通过 DSH 工具 test_hud 与同名 CLI 驱动更新。插件分类为客户端；npm 包版本 0.1.1，许可证 MIT。

这是什么¶

dsh-testhud 是 DSH 的客户端插件：自动化测试进行时，在屏幕角落（尽量避开被测窗口）显示标题、目标、开始时间与已用秒数，以及逐步的期望与实际结果（✓ / ✗ / ⏳ / •）。面板顶部有一条固定提示：运行中为「正在进行：先别动鼠标键盘，以免打断测试」（白字红底 #FF3B30），结束后为「✓ 已结束，可以收回鼠标键盘的控制权了」（黑字绿底 #34C759），用颜色直接表达是否安全操作输入设备。

面板不抢焦点：除顶部色带（可拖拽）和内容溢出需滚动时外，鼠标可穿透；不在 Dock 与 ⌘Tab 中列出；左上角 macOS 风格三键可关闭、折叠或扩至可用区域上限。智能体侧通过 test_hud 上报；Shell 与 CI 可用 testhud 子命令读写同一套进度逻辑。

核心功能¶

智能体工具 test_hud¶

面板按内容自适应宽高；仅步骤列表区域滚动，页眉固定。调用 done 后约 12 秒自动消失，便于阅读结论。

约定（README 中的 The rule）¶

若正在做验证，面板必须处于打开状态：不要「只跑命令」而不开 HUD；一系列运行之间，在上一次 done 之后、下一次操作之前应再次 start。测试结束后应 done，并正常退出为测试启动的应用（不要用 kill -9），再把浏览器或 DSH 窗口切回前台，避免被测应用一直占屏。

CLI testhud¶

与工具共用同一套进度文件，便于脚本与 CI：

testhud start "Movable toolbar layout" "Movable main window" [anchor]
testhud step  "toolbar is centred" "centre == window centre" "962pt, centred" ok
testhud note  "left to the user to decide"
testhud done  ok "3 of 3 checks passed"
testhud stop
testhud status

可选配置¶

在 profile 的 cordis.patch.yml 中可覆盖插件行（示例 id 为 testhud）：

- id: testhud
  config:
    announceToAgent: true     # 向每个会话注入「长测试应在屏幕上汇报」的短约定
    defaultAnchor: auto       # auto | center | left | right
    topInset: 155             # 顶边距屏幕顶部的距离（pt），默认避开浏览器标签栏等区域

定位优先级（资料原文顺序）：尽量不遮挡前台应用窗口 → 若无遮挡则居中 → 否则优先左侧再右侧。垂直方向默认距屏幕顶 155 pt（topInset）；CLI 可用环境变量 DSH_TESTHUD_TOP_INSET 覆盖。

安装与启用¶

插件须出现在 profile 的 dsh.profile.bundles 中（dsh plugin add 会写入）。可用 dsh --profile <profile> --dump-config 确认是否出现 # == dsh-testhud 层标记；该 profile 下每个会话应提供 test_hud 工具及相关提示约定。

官方 README 给出的安装方式：

dsh plugin --profile <profile> add github:yijiezhong/dsh-testhud   # straight from GitHub
dsh plugin --profile <profile> add link:/path/to/dsh-testhud       # from a local checkout
dsh plugin --profile <profile> add dsh-testhud                     # from npm (published as 0.1.1)

Desktop 应用可在插件设置中用同样方式安装；其插件管理器可热挂载新 bundle。通过 CLI 启动的 profile 在启动时组合 bundle 列表，一般需重启一次 profile，除非你的 profile 已支持 live reload。

包声明 @deepseek-ai/dsh-tools 为 peer dependency（约 ~0.2.0-rc.2）：由运行中的 DSH 解析宿主自带的 defineTool；若宿主版本不在声明范围内，整个 bundle 会拒绝加载而非半加载。

卸载示例（README）：

dsh plugin --profile web remove dsh-testhud

运行环境要求 Node.js >= 20（见 package.json 的 engines）。

典型用法¶

1、在目标 profile 安装插件并确认 dump-config 中有 dsh-testhud 层。

2、智能体在长时 GUI 验证开始时调用 test_hud 的 start，传入 title 与可选 target、anchor。

3、每完成或进行一步检查，调用 step，填写 name、expect、actual 与 state。

4、需要补充说明时用 note；全部结束时 done，并根据结果设置 failed 与 conclusion。

5、纯 Shell 流程可改用 testhud 子命令，参数与语义与上面对应。

适用场景与注意¶

适合：在 macOS 上用 DSH 智能体或脚本做 GUI 自动化、截图对比、批量渲染等需要「人在旁边等」的流程；需要屏幕级提示「勿动键鼠 / 可接手」而不遮挡操作被测应用本身。

注意：

• 插件关键词与行为描述均指向 macOS；在其他系统上是否可用，资料未说明，部署前请自行核对源码与运行环境。
• DSH 插件以当前 dsh 进程权限运行；安装前应阅读 GitHub 仓库 源码与 MIT 许可证，确认符合你的安全与合规要求。
• 社区目录 SkillHub 插件页 与 GitHub 为独立信息源；SkillHub 为社区插件目录，与 DeepSeek / 幻方无官方从属关系，不宜当作官方应用商店。

结尾¶

dsh-testhud 把「测什么、每一步怎样、能否动键鼠」放到被测应用上方的只读 HUD 里，并用 test_hud / testhud 统一驱动，减少长测试等待时的不确定性。进一步了解可访问目录页 https://www.skillhub.cn/plugins/yijiezhong/dsh-testhud 与仓库 https://github.com/yijiezhong/dsh-testhud。