Dock 提醒 ihodorchenko/dsh-dock-attention

dsh-dock-attention

DeepSeek Harness 的 Host 插件：智能体需要你、而 Harness 窗口不在最前面时，让 Dock 图标跳动。

icon

插件监听持久化的会话事件流——审批、智能体提问、回合结束——只有这些时刻才去碰 Dock。你已经在看 Harness 就什么都不发生：提醒是给你不在的时候用的，不是用来打断你正待着的窗口。

为什么要在 Dock 里单独放一个信标

桌面应用的 Dock 图标归它的 Electron 主进程所有，app.dock.bounce() 是主进程 API。Host 插件跑在独立的 Node 子进程里（私有的 Desktop Host），调不到它；而且除非调用方持有私有 entitlement，Dock 会拒绝跨进程「让别的应用的图标跳动」这类请求。所以对普通插件来说，不管用哪个钩子，「让 DSH 图标跳动」都做不到。

于是这个插件给出最诚实的最小替代方案：一个原生辅助应用 DSH Attention。需要提醒时，Host 插件写一个请求文件，在后台启动辅助应用（open -n -g），辅助应用会：

1. 以后台代理身份启动，绝不抢焦点；
2. 把自己提升为普通应用，从而获得 Dock 图标；
3. 向 AppKit 请求用户注意，让那个图标跳动；
4. 一旦 Harness 窗口来到最前面、自己的图标被点击，或者时间预算用完，就退出——图标也随之消失。

点击跳动的图标会激活 Harness（没在运行就启动它）。辅助应用不需要辅助功能、自动化、屏幕录制或通知权限：焦点检测通过 JXA 调用 NSWorkspace，跳动用的是 AppKit 自带的 requestUserAttention。

触发时机

| 时刻 | 事件 | 默认 |
| 智能体等待审批决定 | approval/asked | 开 |
| 智能体提问（ask_user_question、exit_plan_mode） | tool/call | 开 |
| 回合结束、失败、被阻塞，或触及 token 上限 | turn/end | 开 |

静默的情况：用户取消的回合（aborted）、分叉或中断的回合，以及子代理会话（除非 includeSubagents: true）。另外，activeBundleIds 中某个应用在最前面、已经有信标在跳动，或者事件距上一个事件不足 minIntervalSeconds 时，也会跳过。

安装

插件管理器 / 命令行：

sh
dsh plugin --profile desktop add "github:ihodorchenko/dsh-dock-attention"

Plugin Manager 也接受 git URL git+https://github.com/ihodorchenko/dsh-dock-attention.git。每个 release 都附带源码归档。

从本地检出安装： sh
dsh plugin --profile desktop add "link:/absolute/path/to/dsh-dock-attention"

不用 Plugin Manager —— 直接把配置档补丁行指向包（Loader 会监视配置档，新行无需重启即可生效）： yaml
- insert:
- id: dock-attention
name: 'file:///absolute/path/to/dsh-dock-attention/index.js'
config:
mode: critical

插件只在 macOS 上运行。其他平台上它只挂载，不做任何事。

配置

每个字段都可选；行里的 config 映射会覆盖这些默认值。

| 字段 | 默认值 | 含义 |
| enabled | true | 总开关。 |
| targetBundleId | com.deepseek.dsh | 信标激活并监视的应用。在浏览器里运行 dsh web 时，把它指向你的浏览器 bundle id。 |
| activeBundleIds | ['com.deepseek.dsh'] | 算作「已经在看 Harness」的前台应用。 |
| skipWhenActive | true | activeBundleIds 之一在最前时，绝不弹跳。 |
| bounceOnApproval | true | 请求审批时弹跳。 |
| bounceOnQuestion | true | 智能体提问时弹跳。 |
| bounceOnTurnEnd | true | 一轮结束时弹跳（完成、失败、阻塞、token 上限）。 |
| includeSubagents | false | 子代理会话也弹跳。 |
| mode | critical | critical 一直弹跳，直到你回来（或超时）；informational 弹跳 repeatCount 次。 |
| repeatCount | 3 | informational 模式下单次弹跳的次数（1–20）。 |
| timeoutSeconds | 30 | 信标图标在 Dock 里最多停留多久（3–300）。 |
| minIntervalSeconds | 3 | 两次弹跳之间的防抖窗口（0–120）。 |
| sound | null | macOS 系统声音名（Glass、Ping 等）或绝对音频路径；null 表示静音。 |
| openUrl | dsh://open | targetBundleId 未安装时，信标打开的兜底地址。 |
yaml
- id: dock-attention
name: dsh-dock-attention
config:
mode: critical
timeoutSeconds: 45
bounceOnTurnEnd: false # only "needs you" moments
sound: Glass

在 Safari 里运行 dsh web？用： yaml config: targetBundleId: com.apple.Safari
activeBundleIds: ['com.apple.Safari']

验证是否生效 sh
node tools/self-check.mjs

自检不编译任何东西；它启动随附的信标，通过 NSWorkspace 监视它，等它退出，然后打印辅助进程日志的末尾。运行时盯着 Dock：应该出现一个弹跳的 DSH Attention 图标，大约八秒后消失。

限制

- 仅限 macOS。 整套机制都是 macOS 专属的。
- beacon 是独立的 Dock 图标，不是 Harness 图标本身（见上文「Why a separate beacon」）。只有需要关注时它才出现在 Dock 里；点击它就回到 Harness。
- beacon 激活期间是普通应用，所以那几秒内它会在 Dock 里可见，也可能出现在 Cmd-Tab 中。启动时它从不抢焦点。
- 默认不发通知、不响声音 —— 那些是另外的插件。想要的不只是动效，就设置 sound，或者搭配 dsh-macos-notifications。
- macOS 的「减弱动态效果」和第三方 Dock 动画调整可能压掉弹跳动画；插件检测不到这一点。图标仍然会出现。
- macOS 会限制超长的 critical 请求；想要更短、不被限流的爆发，就调低 timeoutSeconds（10–15 s）。
- helper 是 ad-hoc 签名，没有公证。从本地 checkout 或 git 依赖安装的插件不带隔离属性，能正常启动；如果 zip 下载确实加上了隔离属性，执行一次 xattr -dr com.apple.quarantine "bin/DSH Attention.app"。
- 如果 Harness 窗口在前台，按设计不会有任何弹跳。

故障排查

- 完全不出现图标 —— 运行 node tools/self-check.mjs；它会报告 helper 到底有没有启动，并打印 runtime/helper.log 的末尾。
- 图标出现但从不弹跳 —— 检查系统设置 → 辅助功能里的「减弱动态效果」，以及 Dock 动画调整。beacon 日志仍会显示
requestUserAttention(...) -> id=0，说明请求已被接受（返回值 0 是合法的首个请求 id —— -1 才表示应用处于活跃状态）。
- 你正看着 Harness 时 beacon 却出现了 —— 设置 skipWhenActive: true（默认值），并确认 activeBundleIds 写的是正确的应用；浏览器用户必须加上自己浏览器的 bundle id。

文件

| 文件 | 作用 |
| index.js | 宿主插件：会话事件监听与关注分发 |
| lib/attention.js | 配置归一化、事件映射、焦点探测、beacon 启动 |
| bin/DSH Attention.app | 原生 beacon 应用（通用二进制，ad-hoc 签名） |
| src/helper/main.swift | beacon 源码；tools/build-helper.sh 重新构建 bundle |
| runtime/request.json、runtime/helper.log | 运行时写入；已被 git 忽略 |
| cordis.patch.yml | 插入 dock-attention 行的 bundle 补丁 |
| locale/en.json、locale/ru.json | 插件管理器显示元数据 |
| icon.svg、docs/icon-1024.png | 插件图标与应用图标源文件 |

开发 sh
node --test # 18 unit tests (config, event mapping, wiring)
bash tools/build-helper.sh # rebuild bin/DSH Attention.app (needs Xcode CLT)
python3 tools/render-icon.py # optional: re-render AppIcon.icns (needs Pillow)

helper 源码小到可以审计：requestAttention、单实例守卫、前台应用轮询、点击与激活转发，全都在 src/helper/main.swift。

许可证

MIT — 见 LICENSE。beacon 采用 ad-hoc 签名（没有 Apple Developer 身份），因此不带公证；它从本地包目录启动，不需要绕过隔离机制。