frederico-kluser/dsh-goal-pause-guard

dsh-goal-pause-guard

用于 DeepSeek Harness 的插件：在暂停正在运行的活动前弹出确认模态框。

license
node
dsh
ci
topic: dsh-plugin

暂停一个 goal 可不是个小动作：它会立即中断当前轮次以及所有正在执行的子任务。本插件会在暂停前请求确认。

暂停 goal 前的确认模态框

为什么

在 harness 中，暂停一个已武装的 goal 会触发一连串反应（由
goal-round-driver、goal/changed → agent.cancel、keepInbox 驱动）：

1. 正在进行的轮次会被中止——agent 会在执行到一半时停止；
2. 正在执行的子任务也会随之停止（工具、命令、子 agent）；
3. 自动继续会被解除武装——在人工执行 resume 之前不会有新的轮次。

本插件正是把这一效果挡在一道关卡之后：一次误点暂停按钮，不能关掉一个正在运行的活动。

插件做了什么

点击 "Pause goal"（人类点击，trusted）
│
▼
┌──────────────┐   在 document 上捕获（capture phase，早于 React）
│ GUARD        │   isPauseButton? ── 否 ──► 点击放行（fail-open）
└──────┬───────┘
▼ 是
确认模态框  （pt-BR / en / zh，跟随宿主的明暗主题）
├── 取消 / Esc / 背景 ──► 什么也不发生
└── 确认 ──► 对当前暂停按钮重新发起 UNTRUSTED 点击
│  （经过 guard 但不会再次拦截）
▼
GoalBar → goals.pause（Remote RPC）
▼
host：goal 暂停 + 轮次中止 + 子任务停止

- 双通道检测——按钮通过本地化的 aria-label
（Pause goal / 暂停目标，即 goal 栏的两个词典）
或通过暂停图标的 SVG path（IconPauseOutline16）来识别，且始终位于
[data-goal-bar] 内（官方 e2e 自身使用的标记）。
- 按设计 fail-open——如果按钮无法识别，点击会放行，
暂停行为与没有插件时完全一致。确认关卡绝不能破坏它所保护的操作。
- 无循环、无陈旧引用——确认时会重新定位当前的暂停按钮
再重新点击（在打开与确认之间的重新渲染，绝不会把“确认”变成“点了别的东西”）；按钮被禁用或
在此期间移除 = 什么都不会发生。
- 一次只显示一个模态框 — Esc、背景和取消都会关闭它；焦点会转到
确认按钮，并在关闭时回到暂停按钮。
- 确定性 — 没有定时器、没有网络、没有存储。宿主那一半是一个
空的 apply（与 @deepseek-ai/dsh-client-ui-goal 相同的模式）：不会触碰
任何 harness 状态。

安装

作为 web profile 的 bundle — 包的 dsh.bundle.patch 会自行激活该层
（自己的 insert，不会与任何其他 id 冲突）：

dsh plugin --profile web add /caminho/para/dsh-goal-pause-guard
dsh web   # 重启实例；插件会在启动时加载

卸载：从 ~/.dsh/profiles/web/package.json 中移除 bundle 那一行
（dsh plugin --profile web remove dsh-goal-pause-guard）并重启。

验证

所有验证都隔离运行 — 没有任何测试会触碰真实的
DSH 实例（既不碰 3080 端口，也不碰 $DSH_HOME）：

pnpm install
pnpm run typecheck   # tsc 严格模式
pnpm run build       # dist/（宿主）+ lib/client.js（浏览器，closure-factory）
pnpm test            # 23 个测试：检测器 + 行为 + 产物 e2e

| 层 | 证明 |
| --- | --- |
| 检测器（单元，jsdom） | 两个识别通道；拒绝其他一切（resume/edit/clear、栏外按钮、外来图标、相似前缀） |
| 行为（jsdom） | 人类点击会打开模态框，且永远不会到达应用；确认会以 untrusted 方式重新点击一次；取消/Esc/背景不会暂停；第二次点击被吞掉；确认时按钮被移除/禁用不会触发；disposer 会移除一切 |
| 产物 E2E | 发送的 lib/client.js 会按照 harness 的加载方式被加载（window.__ModuleLoader__.load({id, factory})），并在其上驱动整个流程 |

上面的截图是真实的：在隔离启动（临时 $DSH_HOME + 独立端口）中
用无头 Chromium 捕获，点击真正的暂停按钮
（通过 CDP 的 trusted 事件）— guard 打开了模态框，取消没有发送任何暂停。

结构

dsh-goal-pause-guard/
├── package.json             # dsh.bundle.patch + dsh.client（platform web）+ exports["./client"]
├── cordis.patch.yml         # 第 1 层（bundle）：自己的 insert，没有 !!js，没有 config
├── src/index.ts             # 宿主那一半：空的 apply（Loader 入口）
├── client/
│   ├── guard-core.ts        # 全部逻辑：检测器、文本、模态框、install（0 imports）
│   ├── index.ts             # 插件主体：inject [] + 通过 ctx.effect 的 apply(ctx)
│   ├── guard.css            # 使用 --dsw-* token 的模态框（浅色/深色），gpg- 类
│   └── client.d.ts          # 子路径 ./client 的声明
├── scripts/build-client.mjs # esbuild → lib/client.js（closure-factory，内嵌 CSS）
├── test/                    # jsdom + node:test，按项目离线
└── dist/, lib/              # 构建产物（宿主那一半 / 浏览器 bundle）

兼容性

已针对 DSH 0.1.5-alpha.2 验证（已安装的活跃版本，从
源）。检测器锚定在表面上的两个稳定事实——data-goal-bar
以及 goal 字典中 action.pause 的 aria-label。如果测试框架同时更改
两者，守卫会变为 fail-open（无模态的暂停）——永远不会损坏。

许可证

MIT © Frederico Kluser