标签页闪烁提醒 andreagosto/dsh-tab-watchdog

dsh-tab-watchdog

DeepSeek Harness Web 的常驻插件：当你的某个工作区/会话跑完一轮工作、报错，或者需要你输入时，浏览器标签页会给出提示——favicon 里的小鲸鱼（DeepSeek Harness 的 logo）会闪绿色或黄色，标签页标题显示待处理总数。

这是 Tab Watchdog 的「bundle」版本（常驻、可安装、可分享）。它最初是 Creator 模式下开发的动态插件。和动态插件不同，它能扛住 dsh 重启和浏览器刷新（F5）。

工作原理（架构）

和官方插件一样，一个 npm 包里装两半：

- 宿主半边（index.js）——profile 组合行（cordis.patch.yml + dsh.bundle.patch）。它让这个包成为 Loader 条目：正是这一行把浏览器半边拉进启动清单。这里没有业务逻辑。
- 浏览器半边（lib/client.js，通过 dsh.client + ./client 导出提供）——一个 window.__ModuleLoader__.load({ id, factory }) 格式的 bundle。它订阅转发到浏览器的宿主事件（ctx.remote.$on），其余全由它处理（状态、水位线、闪烁）。不给 harness 加任何 UI。

触发条件（什么会让它闪）

浏览器只能收到 dsh-api-remotes 白名单上的事件。watchdog 用到这些：

| 事件 | 级别 | 标签 |
| api-session/status(sessionId, running=false) | 🟢 绿鲸鱼 | 「跑完一轮工作」 |
| api-session/error(sessionId, message) | 🟡 黄鲸鱼 | 「出错了…」 |
| 待处理的 approval 交互 | 🟡 黄鲸鱼 | 「需要审批」 |
| 待处理的 question / plan-review 交互 | 🟡 黄鲸鱼 | 「在等你回复」 |

绿色/报错走转发过来的 emit 事件（ctx.remote.$on）。问题和审批的黄色不依赖 user-questions/request/approval/request 瀑布事件：这些事件是单消费者，官方 UI 的应答方按注册顺序抢占，而且转发过来的请求不带稳定的 session id。watchdog 改为轮询官方 UI 在等你时发布的状态：ctx.uiSession.pendingInteractions.getSnapshot()——一个 Map<sessionId, interaction>，kind ∈ approval | question | plan-review。轮询跑在现有的 1s tick 里；条目待处理期间会被反复重新 bump，交互清除后移除，所以你一回复，闪烁自己就停了。这样能覆盖应用里的每一个会话，不只是当前查看的那个。

注意：本版本的白名单里，workflow/end、agent/status、goal/changed 不转发到浏览器；要观察它们，得在宿主侧通过自定义通道做聚合（按设计不在范围内）。黄色路径依赖应用自己的待处理交互 UI（ui-approval/ui-user-questions）发布等待状态；如果第三方应答方抢占了请求、不走那个 UI，这个交互在浏览器里就看不到。

闪烁模型（水印）

- 事件只在页面打开时到达（即使页面在另一个浏览器标签页里也一样——这正是设计用途）。
- 新事件会保持「待处理」状态，直到你回到页面。
- 页面未获得焦点、且至少有一条待处理项时，favicon 鲸鱼会闪烁（与原始 favicon 交替显示），标题在 N · 和 之间交替，其中 N 是跨会话、跨层级的总待处理数。
- 鲸鱼颜色：只有已完成的轮次待处理时显示绿色；有任何错误/提问/审批时显示黄色；两类同时待处理时绿色↔黄色交替。
- 原始 favicon 在加载时捕获，回到页面时（或待处理清空时）总会恢复——不会永久改动任何东西。
- 你正聚焦时到达的事件会立即标记为已读（不会留下闪烁）。
- 会话重启时（running=true），它的待处理条目会被移除。
- 会话上的错误会把条目「冻结」为黄色：之后 running=false 也不会把它降级为绿色。

安装（本地 web 配置档）

在插件 checkout 目录下：

from the directory that contains dsh-tab-watchdog/
npx @deepseek-ai/dsh@latest plugin --profile web add ./dsh-tab-watchdog

然后重启 dsh web。浏览器端会在下次刷新/启动时生效。新增的行是配置档 cordis.yml 里的 tab-watchdog 条目。

移除：

npx @deepseek-ai/dsh@latest plugin --profile web remove dsh-tab-watchdog

dsh plugin 会在配置档内转发给 pnpm。如果没装 pnpm：corepack enable 或 npm i -g pnpm。

开发

浏览器端源码是 src/client.js（loader 工厂里的一个 CJS 片段）。lib/client.js 产物是提交进仓库的（git 安装时没有构建步骤）。

npm run build # regenerates lib/client.js from src/client.js
npm test # verify (bundle structure) + smoke (blink/watermark logic)

不需要 prepare/monorepo 工具链：树外插件用不了内部的 clientBundle 预设，所以 loader 格式是手工复刻的（scripts/build.mjs）。

与社区分享

包声明了 dsh.bundle.patch，所以会作为配置档 bundle 安装。因为 lib/client.js 和 index.js 是已提交的产物，git 安装无需 prepare：

npx @deepseek-ai/dsh@latest plugin --profile web add github:andreagosto/dsh-tab-watchdog

为了方便被发现，GitHub 仓库带了 dsh-plugin 话题（见官方 deepseek-harness README 的「Community and support」）。另一种方式：npm publish，然后 dsh plugin --profile web add dsh-tab-watchdog。

说明与限制

- 针对运行时 @deepseek-ai/dsh 0.1.2-rc.1 测试过（注意 rc 预发布版上的「breaking changes」提示）。
- 浏览器端这部分是照着已安装 bundle 里观察到的 API 手写的；结构由 npm test 校验，但请在你自己的配置档里实测确认。
- 没有设置命名空间：插件不会出现在 Settings → Plugins 里。要停用它，用 dsh plugin remove（或在配置档补丁里给对应行设 disabled: true）。

License

MIT