答题提醒 liujianqiao701/dsh-ask-notify

dsh-ask-notify — 「需要你回答」右下角提醒

DSH Web GUI 的客户端插件。当 agent 停下来等你作答时（ask_user_question、审批、计划确认），在页面右下角弹出提醒卡；如果你不在这个页面（切到了别的标签 / 别的窗口 / 别的程序），再补一条系统通知并让标签标题闪烁。

安装

首选：插件市场（不敲命令，同事都用这条）

DSH 界面里 设置 → 插件市场 → 搜 dsh-ask-notify → 安装。

装完看市场卡片上的状态词，它直接告诉你还差什么：

| 卡片状态 | 还要做什么 |
| 已生效 | 只差刷新页面：F5，不行再 Ctrl+F5 |
| 已安装，重启后生效 | 重启 dsh web，然后 Ctrl+F5 |
| 已安装，未生效 / 已停用 | 点卡片上的「为什么未生效？」看原因 —— 最常见是「有 agent 正在运行」，停掉再装一次 |

⚠️ 刷新这一步不能省：插件条目是随页面启动清单（window.__DSH_BOOT__）下发的，页面不重新加载，它就永远不知道有这个插件 —— 服务端再正常也没用。
“装了没效果”绝大多数就是这一条（这时市场卡片写的通常是「已生效」）。

备选：命令行 / 本包 install.ps1

dsh plugin --profile web add github:liujianqiao701/dsh-ask-notify

这条路必须重启 dsh web：登记写的是 bundle 层，而 bundle 层只在启动时读一次。
（install.ps1 是同样的机制，走 junction + link: 依赖，也要重启。）

名字与路由（别用错）

- 加载器里的行 id 是 ask-notify（本包 cordis.patch.yml 里的 - insert: - id: ask-notify）；
- 但浏览器半区的路由用的是「包名」：/plugins/dsh-ask-notify/client.js 对， /plugins/ask-notify/client.js（行 id）是 404。
- ⚠️ 别手敲这个 URL 来判活：新代 harness 把路由键改成了 /plugins//client.js?rev=，rev 是查表键的一部分 —— 不带 rev 手敲就是 404，哪怕服务端一切正常。判活请用 Ctrl+U 搜 boot payload，或控制台 __dshAskNotify.sources()。

环境要求

- Windows + dsh web。
- 任何 harness 版本都能用（1.0.4 起）。等待态“住哪”换过两次，插件按名字读三个源，优先级从新到旧：
- 0.1.7+ → uiSession.sessionStatus；
- 0.1.2 ~ 0.1.6 → uiSession.pendingInteractions（实测 0.1.5-rc.3 属这一代）；
- ≤ 0.1.1-rc.x → 会话列表行上的 pendingInteraction。
再换名字也不用改插件：三个源都读不到时，插件会扫描 uiSession / sessions 上所有 map 型成员，谁真的装着等待就自动认它 —— sources().discovered 会列出探测到的名字。这是“以后不必再改插件重传”的保证。
还能逐会话回落：某个会话在高优先级源里没值，就自动去下一个源找。
- 不再有任何“必须先存在”的依赖（1.0.4 起）：cordis 的 exports.inject 已清空（原为 ["sessions"]）， package.json 的 dsh.client.inject 也是空的。服务缺失时插件照样挂载、照样能被 selftest() 证明活着； 15 秒仍读不到任何数据就控制台报警 + 右下角弹一张提示卡（数据源恢复后自动撤掉）—— 不会“静默不生效”。
- 1.0.1 的 dsh.client.inject 里钉着 @deepseek-ai/dsh-client-runtime（新代 harness 已没有这个包）。
实测它不会挡住挂载 —— 加载器对“图里不存在的依赖”是静默跳过的；但它本来就是指向一个已不发布包的死引用，1.0.2 起已清空。
- 挂载面跨版本稳定：dsh-client-modules 从最早 0.0.1-rc.1 到最新 0.1.7-rc.1 都要求 dsh.client.platform（字符串）+ exports["./client"]，本包两个都有。
- 想确认自己在哪一代：跑 _verify\diag\check-ask-notify.cmd（E 段打印 harness 版本 + dsh-client-ui-session present / dsh-client-runtime present），或在页面控制台看 __dshAskNotify.sources()。

为什么需要它

内置的问题卡片会接管输入框——只有你正看着这个页面才知道 agent 停了。
你切去别的标签干别的活时，agent 就一直卡在等待里，而页面上没有任何东西能“喊”你。
本插件把“等你回答”这件事从页面里主动推出来。

三个提醒通道

| 通道 | 出现条件 | 解决什么 |
| 右下角提醒卡 | 只要有等待（不管你在不在页面） | 你回到页面时一眼看见还剩什么问题 |
| 系统通知（Windows 右下角气泡） | 页面不可见或未聚焦 + 已授权通知 | 你在别的标签/程序时也能被喊到 |
| 标题闪烁（❓ DeepSeek Harness） | 页面不可见 | 在标签栏上一眼看出“有个标签在等我” |

卡片上的按钮：去回答（自动切到那个会话并把输入区滚到眼前）、稍后提醒（本次不再弹，下一条等待还会弹）、桌面提醒 开/关、声音 开/关。

数据来源（不是 DOM 抓取）

旧代 ≤0.1.1-rc.x ：ctx.sessions.list.getSnapshot().byId[id].pendingInteraction （字符串）中代 0.1.2-0.1.6 ：ctx.get("uiSession").pendingInteractions.getSnapshot().get(id) （{key,kind,sessionId}）新代 0.1.7+ ：ctx.get("uiSession").sessionStatus.getSnapshot().get(id).pendingInteraction └─ ctx.sessions.binding(id).session.getSnapshot().pending[].payload → 问题原文

用的就是侧边栏「琥珀色小圆点」同一份运行时状态（kind ∈ question / approval / plan-review，新代是开放字符串），所以页面改版、DOM 结构变化都不会让它失效。1.0.4 起所有 harness 版本的数据源都读：新代读 uiSession.sessionStatus，中代读 uiSession.pendingInteractions，旧代读会话列表行上的 pendingInteraction —— 从新到旧依次取，某个会话在上一源没值就落到下一源；此外还会自动探测没见过的 map 型成员（sources().discovered 列出探测结果），所以下次 harness 再改名字，用户手里这一份自己就能认。
sources().used 报的是真正给出数据的那一个源（不是"第一个存在"的源）；一个都读不到就报警 + 弹提示卡。
订阅 + 2 秒轮询双保险。

生效与更新

"要不要重启"取决于激活点写在哪一层，不是凭经验：

| 你动的是什么 | 要重启 dsh web？ | 要刷新页面？ |
| 市场安装（卡片显示「已生效」） | 否 —— 市场会热挂载进正在跑的进程 | 要（必须） |
| 市场安装（卡片显示「重启后生效」） | 要 —— 市场自己判定这次没法热挂载 | 要 |
| 命令行 / install.ps1 安装 | 要 —— 登记的是 bundle 层，只在启动时读 | 要 |
| 改 lib\client.js（客户端半区的内容） | 否 | 否 —— 服务端按内容哈希经 /plugins/events（SSE）推 rebuilt，客户端 HMR 自动热换 |
| 改本包的 cordis.patch.yml（bundle 层） | 要 —— bundle 层只在启动时读一次 | 要 |
| 改 profile 的用户层 patch（~\.dsh\profiles\web\cordis.patch.yml、$DSH_HOME\cordis.patch.yml） | 否 —— 这两个文件被监听，热生效 | 否 |

容易记混的一点：热的是"用户层 patch 文件"和"客户端半区的内容"，不是 bundle 层。
本包走 bundle 层（自带 cordis.patch.yml），所以"改挂载条目"这类改动一律要重启。

⚠️ 市场点「更新」没反应？先看界面上有没有正在跑的会话。 市场自己会拦下来，并提示：「有 agent 正在运行，请等待其完成或将其取消后再更新 —— 更新会直接替换插件文件，运行中的 agent 可能中途报错或新旧版本混用」。这是市场的保护机制（实测 dsh-market v1.62.0），与插件无关；等那个会话跑完（或先取消）再点即可。注意：你和 agent 对话时它就在跑，这条闸门必然触发 —— 这是最容易被误判成"插件坏了"的一种情况。

✅ 市场日志里这两行都是正常的，别当失败看（2026-09-24 实测）： update-blocked … refused while agents are running = 上面那把闸门拦下的那次点击； a too-young release blocks pnpm's lockfile verification … retrying once with --config.minimum-release-age=0 = pnpm 的"新发布保护"（供应链防投毒）挡了一下，市场自动重试。
真正的结果看紧跟其后那行：update -> github:…# exit=0 = 成功。

自检（不用真等一个问题）

在页面控制台执行：

__dshAskNotify.version // 装的到底是哪一版（当前 1.0.4）
__dshAskNotify.selftest() // 右下角卡片保持 12 秒，看样式
__dshAskNotify.sources() // 取数源体检：used / carries / discovered
__dshAskNotify.state() // 当前等待 / 偏好 / 通知权限 / 是否在页面
__dshAskNotify.collect() // 实时等待列表（真实状态，空数组 = 现在没人等你）
__dshAskNotify.show('approval', '试试审批样式')
__dshAskNotify.hide()

sources() 里有三个字段最有用：used = 真正在给出数据的源；carries = 各源当前装着多少条；
discovered = 自动探测到、名字没见过的源（正常是空数组；非空就说明 harness 又换代了，而插件已经自己认出来了）。

selftest() 造的卡片背后没有真实等待，所以它有一个 12 秒的“保活窗口”——
窗口内实时轮询不会把它清掉（否则会被真实状态的 2 秒轮询立刻抹掉）。
提示卡（"提醒插件读不到数据"）正相反：它会一直留着，直到数据源恢复才自动撤掉。

不想开浏览器也能验：node _verify\diag\selfcheck-client.cjs —— 8 个场景全离线跑（三代已知形状 + 一个没见过的未来形状 + 假阳性诱饵 + 服务缺失/迟到），不联网、不开浏览器。

偏好（localStorage）

| key | 含义 |
| dsh-ask-notify:prefs | {question, approval, "plan-review", system, sound}，布尔；false 即该类等待不提醒 |
| dsh-ask-notify:autoasked | 首次用户手势自动申请通知权限的一次性标记 |
| dsh-ask-notify:lastshot | 多标签去重（同一条等待 20 秒内只由一个标签弹系统通知） |

通知权限：第一次点击/按键时会自动申请一次（只申请一次）。被拒绝过就点卡片上的 🔔 开启桌面提醒，或到地址栏左侧站点设置里允许；http://127.0.0.1 属安全上下文，允许即可用。

已知边界

- 右下角若已有鲸鱼吉祥物（dsh-whale-mascot），卡片会叠在它上方而不是压住它。
- 同一等待在多个标签页里会各显示一张卡片，但系统通知只弹一次（跨标签去重）。
- 声音用 WebAudio，浏览器未与页面交互过时会被静音策略挡掉——静默跳过，不报错。
- 问题原文从 payload 里容错提取（questions[0].question / question / detail / title…），取不到就显示「（在下方输入框或问题卡片里作答后我才能继续）」，不会因为字段改名而崩。

网络行为

本插件不发起任何网络请求。 数据全部来自宿主已经持有的会话运行时状态，偏好只写在 localStorage，系统通知走浏览器的 Notification API。
lib/client.js 里没有任何 fetch / XMLHttpRequest / WebSocket，也没有任何 URL 常量。

排障

先跑这两下，多数问题当场定位（都在浏览器里，不用粘贴）：

1. 页面按 Ctrl+F5；
2. F12 → Console，手敲 __dshAskNotify.selftest() —— 右下角弹卡 12 秒 = 好了；undefined = 没加载。

undefined 时按下面往下分：

| 现象 | 含义 / 处理 |
| 跑了命令行/脚本安装，没重启 | 必须重启 dsh web —— 登记在 bundle 层，只在启动时读 |
| 市场装完卡片写「已生效」，但没反应 | 只差刷新页面（条目随页面启动清单下发） |
| 市场卡片写「重启后生效」 | 市场判定这次热挂载没成功（入口不是简单 insert / 超时 / 加载器太旧 / 入口解析失败），重启即可 |
| 控制台 __dshAskNotify.sources().used = "uiSession.status" / "uiSession.pending" / "list"（或 discovered 里列出的名字） | 取数源正常；pending: 0 只是「当前没有等待」 |
| 控制台 used: "none" + 一条 [dsh-ask-notify] 读不到等待态数据源 警告 + 右下角一张提示卡 | 已知的源和自动探测都读不到 —— 把 sources() 的输出发给作者 |
| 想直接看服务端有没有下发 | 浏览器开 http://127.0.0.1:3080/ → Ctrl+U 看源码 → Ctrl+F 搜 ask-notify（别手敲 /plugins/.../client.js 判活：新代 harness 的该路由带 ?rev=...，手敲必 404；也别用 curl：前置鉴权插件会让脚本请求 401/404，浏览器带 cookie 才是通的） |
| 卡片不弹，但 __dshAskNotify.collect() 有内容 | 该类等待被偏好关掉了（卡片上的开关，存在 localStorage） |
| 系统通知不弹 | __dshAskNotify.state().permission 不是 granted → 点卡片上的 🔔，或在站点设置里允许；用局域网 IP 打开时浏览器会禁用通知 |
| 页面完全没反应且 collect() 是空数组 | 不是"没装上"：本插件只在真有等待时才有东西显示。用 selftest() 自证，别靠肉眼 |

最省事的一刀 —— 市场自己的日志（%USERPROFILE%\.dsh\profiles\web\.dsh-market\log.ndjson）：

| 日志里出现 | 结论 |
| install ... hot=true + hot-mount ... live | 服务端已热挂载，只差 F5 |
| install ... hot=false | 必须重启 dsh web |
| 完全没有 install 行 | 压根没装成（多半是「有 agent 正在运行」409，或构建脚本被 pnpm 拦） |
| hot-mount failed / restart required | 市场写明了回退原因，照它做 |

本仓库 _verify\diag\check-ask-notify.cmd（只读，双击即可）会自动把这些查一遍并出报告文件。

卸载

在 GUI 里 设置 → 插件管理 卸载（下次启动生效）。命令行等价写法：

dsh plugin --profile web remove dsh-ask-notify

用本仓库脚本装的，跑 uninstall.ps1（会撤掉 junction、link: 依赖、遗留的用户层 insert，以及 dsh.profile.bundles 里的条目）。

⚠️ 无论怎么卸，都要把 dsh.profile.bundles 里那条 "dsh-ask-notify" 一起撤掉。
启动时会解析清单里的每一个条目，解析不到就直接拒绝启动： cannot resolve profile bundle "dsh-ask-notify" ...。
只删 node_modules 里的目录（或只删依赖行）而留着清单条目，等于把"插件没生效"升级成"DSH 起不来"。

本地开发（可选）

想把源码挂进 profile 边改边调，用 link: 装法：

| 角色 | 说明 |
| 源码（唯一真源） | 你的克隆目录 |
| 挂进 profile | ~\.dsh\profiles\web\node_modules\dsh-ask-notify（junction 或 link: 依赖） |
| 激活点 | dsh.profile.bundles 里含 dsh-ask-notify —— 由本包自带的 cordis.patch.yml 负责挂载 |
⚠️ 不要在 profile 用户层（~\.dsh\profiles\web\cordis.patch.yml）里再手写一条
- id: ask-notify 的 insert。 本包的 bundle patch 已经负责挂载，两处都有会导致同一个 id 挂载两次，
dsh web 会直接起不来并报 duplicate loader entry id: ask-notify。

另外记清哪一层是热的：用户层 patch 文件（profile 的 cordis.patch.yml）热生效，而本包所在的 bundle 层只在启动时读 —— 改本包的 cordis.patch.yml 必须重启，改源码 lib\client.js 不用。

发版清单（维护者）—— 两处都要发，只推 GitHub 不够

⚠️ 市场的收录条目里写着 "npm": "dsh-ask-notify"，而 dshmarket/lib/sources.js 的
installTargetFor() 明确规定 npm 包优先（注释原文 "Repo-verified npm packages win"），
只有条目没有 npm 字段时才回落到 github:。所以 npm 不发布，从市场「发现 / 搜索」页安装的人拿到的就是 npm 上的旧版。2026-09-24 实测确认：npm 停在 1.0.0 期间，搜索页显示 v1.0.0，装下去的也正是那份"只认一个取数源、inject 还钉着死引用"的旧代码 ——这就是"装完没效果"。

| 步骤 | 命令 / 动作 | 为什么 |
| 1 | 改 package.json 的 version | 后面两处发布都认它 |
| 2 | npm publish（在包目录执行） | 市场的安装源优先取 npm；不发 npm = 搜索页装到旧版 |
| 3 | git push 到 main | github: 源（本机现在这条）按 HEAD 更新；市场也靠 git ref 判断"有没有新版" |
| 4 | 打 Release（可选） | 市场卡片的「更新内容」会读它 |
| 5 | 等收录库刷新 | 搜索页显示的是收录库的版本，收录库版本号取自 npm，异步刷新、不是瞬时 |

两个版本号别搞混：

| 界面 | 显示 | 来源 |
| 市场「发现 / 搜索」卡片 | v1.0.0 | 收录库的 version 字段 ← 取自 npm |
| 市场「已安装」卡片 | v1.0.4 | 实际装的包的 package.json |

已安装卡片上出现「换用 npm 版本」按钮，说明"装的源"与"收录源"不一致 ——在两边版本一致之前别点它，点了会降级到 npm 上的版本。

文件清单

dsh-ask-notify\
├── package.json 声明 dsh.bundle.patch 与 dsh.client.platform=web ├── cordis.patch.yml bundle 层挂载条目（- insert: - id: ask-notify） ├── lib\index.js host 侧空实现（本插件纯浏览器侧） ├── lib\client.js 全部逻辑：检测 / 卡片 / 系统通知 / 标题闪烁 / 声音 / 自检 ├── install.ps1 备选装法：junction + link: 依赖 + bundle 层登记（装完要重启） ├── uninstall.ps1 反向撤掉上面那几处登记 ├── 安装说明.md 给接收方的分步说明（市场 / 脚本两条路） ├── screenshots.json 市场截图清单 ├── assets\ 市场截图 └── _verify\diag\ 只读诊断：check-ask-notify.cmd（体检）/ 重启并验证.cmd（停→起→验证）

作者 / Author

liujianqiao701 — https://github.com/liujianqiao701

问题反馈、建议或想法请开 Issue： https://github.com/liujianqiao701/dsh-ask-notify/issues

许可 / License

MIT — 见 LICENSE