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

dsh-tab-watchdog

一个用于 DeepSeek Harness Web 的持久化插件：当你的某个工作区/会话完成一轮工作、出错或需要你输入时，浏览器标签页会发出信号——favicon 中一只小鲸鱼（DeepSeek Harness 标志）会闪烁绿色或黄色，标签页标题会显示总的待处理计数。

这是最初在 Creator 模式下开发的 Tab Watchdog 动态插件的“bundle”版本（持久化、可安装、可分享）。与动态插件不同，它能在 dsh 重启和浏览器刷新（F5）后继续存在。

工作原理（架构）

与官方插件一样，一个 npm 包中包含两半：

- Host 半部分（index.js）——profile 组合行（cordis.patch.yml + dsh.bundle.patch）。它使该包成为一个 Loader 条目：正是这一行将浏览器半部分拉入启动清单。这里没有业务逻辑。
- Browser 半部分（lib/client.js，通过 dsh.client + ./client 导出提供服务）——一个采用 window.__ModuleLoader__.load({ id, factory }) 格式的 bundle。它订阅转发到浏览器的 Host 事件（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 应答者按注册顺序认领，而且转发的请求不携带稳定的会话 id。相反，watchdog 轮询官方 UI 在等待你时发布的状态：ctx.uiSession.pendingInteractions.getSnapshot()——一个 Map，其中 kind ∈ approval | question | plan-review。轮询在现有的 1 秒 tick 中运行；条目在待处理期间会被反复重新触发，并在交互清除时移除，因此回答本身就会停止闪烁。这覆盖了应用中的每一个会话，而不仅仅是当前查看的那个。

注意：在此版本的允许列表中，workflow/end、agent/status 和 goal/changed 不会转发到浏览器；要观察它们，需要在 host 侧通过自定义通道进行聚合（按设计不在范围内）。黄色路径依赖于应用自身的待处理交互 UI（ui-approval/ui-user-questions）发布其等待状态；如果第三方应答者认领了某个请求而没有经过该 UI，那么该交互就无法从浏览器中看到。
Blink 模型（水印）

- 事件仅在页面打开时到达（即使在其他浏览器标签页中——这正是预期的使用场景）。
- 新事件会保持“待处理”状态，直到你回到该页面。
- 当页面未获得焦点且至少有一个待处理项时，favicon 鲸鱼会闪烁（与原始 favicon 交替显示），标题会在 N ·  和  之间交替，其中 N 是跨会话和层级的总体待处理数量。
- 鲸鱼颜色：当只有已完成的轮次待处理时为绿色，当有任何错误/问题/审批时为黄色，当两种类型同时待处理时会在绿色↔黄色之间交替。
- 原始 favicon 在加载时被捕获，并在你回来时（或待处理项清空时）始终恢复——不会有任何内容被永久更改。
- 在你处于焦点状态时到达的事件会立即被标记为已读（不会留下闪烁）。
- 当会话重启（running=true）时，其待处理条目会被移除。
- 会话上的错误会将其条目“冻结”为黄色：之后的 running=false 不会将其降级为绿色。

安装（本地 web 配置文件）

从插件检出目录：

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 预发布版本上的“破坏性变更”通知）。
- 浏览器端部分是根据已安装包中观察到的 API 手写的；其结构由 npm test 验证，但请在你自己的配置文件中进行实际验证。
- 没有设置命名空间：该插件不会出现在“设置 → 插件”中。要禁用它，请使用 dsh plugin remove（或在配置文件补丁中为该行设置 disabled: true）。

许可证

MIT