npm - dsh-notify-windows - Versions diffs - 0.6.0 → 0.7.3 - Mend

dsh-notify-windows 0.6.0 → 0.7.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -2,6 +2,64 @@
 本项目遵循 [Semantic Versioning](https://semver.org/)。
+## [0.7.3] - 2026-08-28
+### 修复：重启后主会话被误判为子代理，通知全部失效
+- **根因**：DSH 持久化会话记录时写入 `delegationDepth ?? 0`，重启恢复后主会话的
+  header 也带 `delegationDepth: 0`；旧过滤逻辑 `delegationDepth !== undefined`
+  把「带该字段」当作子代理，导致每次 `dsh web` 重启后所有主会话的通知被静默过滤。
+- **修复**：子代理判定改为 `(delegationDepth ?? 0) > 0`（主会话为 0，子代理 ≥ 1），
+  重启后通知恢复正常。
+- 冒烟测试新增回归用例：`delegationDepth: 0` 的恢复主会话必须弹通知，深度 ≥ 1 仍过滤。
+## [0.7.2] - 2026-08-28
+### 修复：WSL 下通知失败被静默吞掉 + 通知通道自检
+- **静默失败检测**：PowerShell 5.1 在 `-File` 无法加载脚本时仍以退出码 0 退出（例如路径
+  未转换成功时），旧版只检查退出码，失败完全无痕。现在捕获 stdout/stderr，以
+  notify.ps1 输出的 `toast shown` 作为成功标记，失败时记录详细输出并告警。
+- **powershell.exe 解析不再只依赖 PATH**：WSL 下若 DSH 由 systemd / cron / ssh 等
+  最小 PATH 环境启动，`spawn("powershell.exe")` 会 ENOENT 失败。现在优先使用
+  `/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe`（WSL 标准位置），
+  原生 Windows 回退到 PATH 查找，行为不变。
+- **启动自检**：插件启动时校验 notify.ps1 与 powershell.exe 是否可达，通道不可用时
+  立即告警，不再等任务结束才发现通知发不出去。
+- `wslpath` 转换结果缓存（NOTIFY_SCRIPT 恒定，不再每次 toast 同步转换）。
+## [0.7.1] - 2026-08-27
+### 修复：支持 DSH 部署在 WSL 中时发送通知
+- 之前通知通道唯一依赖 `powershell.exe -File <notify.ps1>`，而 DSH 跑在 WSL 里时该脚本路径为
+  Linux 形式（如 `/home/.../notify.ps1`），Windows 侧 PowerShell 无法识别，导致通知静默失败。
+- **修复**：新增 `winPath()`，在 WSL 下用 `wslpath -w` 将脚本路径转为 Windows 可读的
+  `\\wsl.localhost\...` UNC 路径后传给 `-File`。
+- **原生 Windows 不受影响**：`wslpath` 在原生 Windows 上不存在，`winPath()` 会原样返回
+  原始路径，行为与旧版完全一致。
+## [0.7.0] - 2026-08-20
+### 新增「点击通知跳转」功能
+- 任务完成 / 审批 / 提问的 toast 变为**可点击**：点击后打开 DSH Web GUI。优先聚焦已打开的
+  DSH 浏览器标签或 Chrome Application 窗口；无已开窗口则在默认浏览器新开标签。
+  目标 URL 携带 `?session=<id>`（rc.8 前端暂不消费，为未来深链预留）。
+- **实现**：
+  - `lib/notify.ps1` 使用 `activationType="protocol"` + `launch`（协议 `dshnotify://` 或原始
+    URL），使 toast 点击可触发跳转；
+  - `lib/launcher.ps1` 处理聚焦 / 跳转：CDP 尽力 → Win32 聚焦 → `Start-Process` 兜底；
+  - `lib/index.js` 新增配置 `openOnClick` / `preferExisting` / `webUrl`，并自动发现 web
+    基地址（`ctx.webServer.port`，默认 `http://127.0.0.1:3080`）。
+- **配置表补三行**：`openOnClick`(bool, true)、`preferExisting`(bool, true)、
+  `webUrl`(string, '' 自动发现)。
+### 已知限制
+- DSH 0.1.0-rc.8 前端暂无会话深链：点击后打开 GUI 首页 / 会话列表并聚焦已有窗口；真正的
+  「一键直达某会话」需前端侧支持。
 ## [0.6.0] - 2026-08-20
 ### 变更（dsh.bundle 安装 + 对齐 dsh 0.1.0-rc.8）

package/LICENSE CHANGED Viewed

@@ -1,21 +1,21 @@
-MIT License
-Copyright (c) 2026 SeverusZh
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+Copyright (c) 2026 SeverusZh
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md CHANGED Viewed

@@ -1,110 +1,132 @@
-# dsh-notify-windows
-> A DeepSeek Harness (DSH) plugin that sends Windows toast notifications whenever the agent needs your attention.
-<p align="center">
-  <img src="https://img.shields.io/npm/v/dsh-notify-windows" alt="npm">
-  <img src="https://img.shields.io/github/license/SeverusZh/dsh-notify-windows" alt="license">
-  <img src="https://img.shields.io/badge/platform-Windows%2010%2F11-blue" alt="platform">
-  <img src="https://img.shields.io/github/stars/SeverusZh/dsh-notify-windows?style=social" alt="stars">
-</p>
-**Task finished** ✅ ｜ **Approval pending** 🔐 ｜ **Question pending** ❓ — never miss anything that needs you, even away from the screen.
-## ✨ Features
-- **Task completion** — listens to `turn/end` session events; toasts on completed / errored / max-tokens turns, with the session title and reason;
-- **Approval pending** — listens to `approval/asked`; toasts the moment a permission decision is waiting, and skips sessions whose approval policy is `never` (nothing is waiting there);
-- **Question pending** — toasts when the agent calls `ask_user_question`; in this deployment every tool call goes through `run_code`, so the plugin also scans `run_code` source for `tools.ask_user_question(` calls and extracts the question text;
-- **Quiet by default** — subagent sessions are ignored unless `includeSubagents` is set;
-- **Zero dependencies** — toasts are sent through Windows PowerShell 5.1's WinRT toast API, with the AppUserModelId registered under HKCU on first use (no admin required);
-- **Diagnosable** — optional log (`%TEMP%\dsh-notify\notify.log`) and a debug event log.
-## 🚀 Install
-The plugin installs through the **`dsh.bundle`** mechanism: the npm package ships its own
-`cordis.patch.yml`, and after `dsh plugin add` it auto-mounts the `dsh-notify` entry — no
-manual `- insert:` needed.
-```powershell
-dsh plugin --profile web add dsh-notify-windows
-```
-Restart DSH and refresh the browser:
-```powershell
-dsh --profile web
-```
-> Note: don't hand-add `- insert:` with `dsh-notify` anymore — DSH would fail to boot with
-> `duplicate loader entry id: dsh-notify`. To tweak settings, override the entry by id in the
-> profile's `cordis.patch.yml` (see below).
-### Update / Remove
-```powershell
-dsh plugin --profile web update dsh-notify-windows
-dsh plugin --profile web remove dsh-notify-windows
-```
-Restart the DSH host after updating (a newly added bundle layer needs a boot).
-## ⚙️ Configuration
-All `config` keys are optional and default in the plugin. To override, target the entry by id
-in `$DSH_HOME/profiles/web/cordis.patch.yml` (hot-applied by the running host — no restart):
-```yaml
-- id: dsh-notify
-  name: dsh-notify-windows
-  config:
-    enabled: true
-    reasons: [completed, error, max-tokens]
-    notifyOnStart: true
-    notifyOnApproval: true
-    log: true
-```
-| Key | Default | Meaning |
-| --- | --- | --- |
-| `enabled` | `true` | master switch |
-| `reasons` | `[completed, error, max-tokens]` | turn-end reasons to notify (`aborted` / `interrupted` / `blocked` also available) |
-| `includeSubagents` | `false` | also notify subagent sessions |
-| `notifyOnStart` | `false` | toast when the plugin loads |
-| `notifyOnApproval` | `true` | toast on `approval/asked` (skipped under policy `never`) |
-| `notifyOnAskUser` | `true` | toast when the agent asks you a question |
-| `notifyOnGoalRounds` | `false` | stay quiet on /goal auto-continuation rounds (except the final complete/block round) |
-| `excerpt` | `true` | append an excerpt of the agent's final reply to the toast |
-| `excerptMaxChars` | `80` | max characters of the excerpt |
-| `appName` | `DeepSeek Harness` | toast source display name and fallback title |
-| `aumid` | `DeepSeekHarness.Notify` | toast AppUserModelId |
-| `log` | `true` | write `%TEMP%\dsh-notify\notify.log` |
-| `debug` | `false` | log every session event (diagnostics, heavy) |
-## 🔔 Triggers
-| Scenario | Session event | Sample toast |
-| --- | --- | --- |
-| Task finished | `turn/end` | Task completed (turn N) |
-| Task errored / capped | `turn/end` | Task errored / Output hit token cap |
-| Approval waiting | `approval/asked` | DeepSeek Harness · Needs approval / tool pwsh: … |
-| Question waiting | `tool/call` (incl. run_code detection) | DeepSeek Harness · Needs your answer / Continue? |
-## 🧪 Verify
-```powershell
-node scripts\smoke-test.mjs
-```
-Runs the plugin on a bare cordis Context with synthetic events: three test toasts fire (completion, approval, question) and the log assertions verify the filtering (subagent, `never`-policy, unrelated calls).
-## ❓ FAQ
-- **No toast?** Check Windows notification settings for this app and Focus Assist; the AUMID registers itself on first use.
-- **Do /goal rounds toast?** Not by default: auto-continuation rounds stay quiet and only the final round that completes (or blocks) the goal toasts. Set `notifyOnGoalRounds` to `true` to hear every round.
-- **Approval toasts missing?** Sessions whose approval policy is `never` auto-reject — nothing waits, so the plugin stays quiet. Only `ask`-policy sessions notify.
-- **Hot-update after code changes?** Run `dsh plugin --profile web update dsh-notify-windows`, then restart the DSH host.
-## 📄 License
+# dsh-notify-windows
+> A DeepSeek Harness (DSH) plugin that sends Windows toast notifications whenever the agent needs your attention.
+<p align="center">
+  <img src="https://img.shields.io/npm/v/dsh-notify-windows" alt="npm">
+  <img src="https://img.shields.io/github/license/SeverusZh/dsh-notify-windows" alt="license">
+  <img src="https://img.shields.io/badge/platform-Windows%2010%2F11-blue" alt="platform">
+  <img src="https://img.shields.io/github/stars/SeverusZh/dsh-notify-windows?style=social" alt="stars">
+</p>
+**Task finished** ✅ ｜ **Approval pending** 🔐 ｜ **Question pending** ❓ — never miss anything that needs you, even away from the screen.
+## ✨ Features
+- **Task completion** — listens to `turn/end` session events; toasts on completed / errored / max-tokens turns, with the session title and reason;
+- **Approval pending** — listens to `approval/asked`; toasts the moment a permission decision is waiting, and skips sessions whose approval policy is `never` (nothing is waiting there);
+- **Question pending** — toasts when the agent calls `ask_user_question`; in this deployment every tool call goes through `run_code`, so the plugin also scans `run_code` source for `tools.ask_user_question(` calls and extracts the question text;
+- **Quiet by default** — subagent sessions are ignored unless `includeSubagents` is set;
+- **Zero dependencies** — toasts are sent through Windows PowerShell 5.1's WinRT toast API, with the AppUserModelId registered under HKCU on first use (no admin required);
+- **Diagnosable** — optional log (`%TEMP%\dsh-notify\notify.log`) and a debug event log.
+## 🚀 Install
+The plugin installs through the **`dsh.bundle`** mechanism: the npm package ships its own
+`cordis.patch.yml`, and after `dsh plugin add` it auto-mounts the `dsh-notify` entry — no
+manual `- insert:` needed.
+```powershell
+dsh plugin --profile web add dsh-notify-windows
+```
+Restart DSH and refresh the browser:
+```powershell
+dsh --profile web
+```
+> Note: don't hand-add `- insert:` with `dsh-notify` anymore — DSH would fail to boot with
+> `duplicate loader entry id: dsh-notify`. To tweak settings, override the entry by id in the
+> profile's `cordis.patch.yml` (see below).
+### Update / Remove
+```powershell
+dsh plugin --profile web update dsh-notify-windows
+dsh plugin --profile web remove dsh-notify-windows
+```
+Restart the DSH host after updating (a newly added bundle layer needs a boot).
+## ⚙️ Configuration
+All `config` keys are optional and default in the plugin. To override, target the entry by id
+in `$DSH_HOME/profiles/web/cordis.patch.yml` (hot-applied by the running host — no restart):
+```yaml
+- id: dsh-notify
+  name: dsh-notify-windows
+  config:
+    enabled: true
+    reasons: [completed, error, max-tokens]
+    notifyOnStart: true
+    notifyOnApproval: true
+    log: true
+```
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | master switch |
+| `reasons` | `[completed, error, max-tokens]` | turn-end reasons to notify (`aborted` / `interrupted` / `blocked` also available) |
+| `includeSubagents` | `false` | also notify subagent sessions |
+| `notifyOnStart` | `false` | toast when the plugin loads |
+| `notifyOnApproval` | `true` | toast on `approval/asked` (skipped under policy `never`) |
+| `notifyOnAskUser` | `true` | toast when the agent asks you a question |
+| `notifyOnGoalRounds` | `false` | stay quiet on /goal auto-continuation rounds (except the final complete/block round) |
+| `excerpt` | `true` | append an excerpt of the agent's final reply to the toast |
+| `excerptMaxChars` | `80` | max characters of the excerpt |
+| `appName` | `DeepSeek Harness` | toast source display name and fallback title |
+| `aumid` | `DeepSeekHarness.Notify` | toast AppUserModelId |
+| `log` | `true` | write `%TEMP%\dsh-notify\notify.log` |
+| `debug` | `false` | log every session event (diagnostics, heavy) |
+| `openOnClick` | `true` | make completion / approval / question toasts clickable (false falls back to the old non-clickable toast) |
+| `preferExisting` | `true` | when true, launcher prefers focusing an open DSH window; when false, just open the URL in the default browser |
+| `webUrl` | `''` | override the auto-discovered base URL (e.g. `http://192.168.1.5:4000`); leave empty to auto-discover (defaults to `http://127.0.0.1:3080`) |
+## 🔔 Triggers
+| Scenario | Session event | Sample toast |
+| --- | --- | --- |
+| Task finished | `turn/end` | Task completed (turn N) |
+| Task errored / capped | `turn/end` | Task errored / Output hit token cap |
+| Approval waiting | `approval/asked` | DeepSeek Harness · Needs approval / tool pwsh: … |
+| Question waiting | `tool/call` (incl. run_code detection) | DeepSeek Harness · Needs your answer / Continue? |
+## 🔗 Click to open
+Toasts for task completion / approval pending / question pending are clickable → they open the
+DSH Web GUI. The plugin prefers to focus an already-open DSH browser tab or Chrome Application
+window; if none is open, it opens a new tab in the default browser and loads the GUI. The target
+URL carries a `?session=<id>` parameter (not yet consumed by the rc.8 frontend — reserved for
+future deep links).
+**Configuration:**
+- `openOnClick` (default `true`; `false` disables clickability and falls back to the old non-clickable toast);
+- `preferExisting` (default `true`; when true the launcher prefers reusing an existing window; when false it opens the URL directly in the default browser);
+- `webUrl` (optional, overrides the auto-discovered base URL, e.g. `http://192.168.1.5:4000`; leave empty to auto-discover / default `http://127.0.0.1:3080`).
+**Notes:** the first click auto-registers the `dshnotify://` protocol handler (HKCU, no admin
+needed); on failure it silently degrades to "open in default browser".
+> Note: DSH 0.1.0-rc.8 does not yet support deep-linking to a single session by URL; clicking opens the DSH interface (home / session list) and focuses the existing window, and you pick the target session from the list. Once the DSH frontend supports deep links, `?session=<id>` will jump straight to it.
+## 🧪 Verify
+```powershell
+node scripts\smoke-test.mjs
+```
+Runs the plugin on a bare cordis Context with synthetic events: three test toasts fire (completion, approval, question) and the log assertions verify the filtering (subagent, `never`-policy, unrelated calls).
+## ❓ FAQ
+- **No toast?** Check Windows notification settings for this app and Focus Assist; the AUMID registers itself on first use.
+- **Do /goal rounds toast?** Not by default: auto-continuation rounds stay quiet and only the final round that completes (or blocks) the goal toasts. Set `notifyOnGoalRounds` to `true` to hear every round.
+- **Approval toasts missing?** Sessions whose approval policy is `never` auto-reject — nothing waits, so the plugin stays quiet. Only `ask`-policy sessions notify.
+- **Hot-update after code changes?** Run `dsh plugin --profile web update dsh-notify-windows`, then restart the DSH host.
+## 📄 License
 [MIT](./LICENSE) © 2026 SeverusZh

package/README.md CHANGED Viewed

@@ -1,110 +1,130 @@
-# dsh-notify-windows
-> DeepSeek Harness（DSH）插件：当 Agent 需要你关注时，向 Windows 发送系统桌面通知。
-<p align="center">
-  <img src="https://img.shields.io/npm/v/dsh-notify-windows" alt="npm">
-  <img src="https://img.shields.io/github/license/SeverusZh/dsh-notify-windows" alt="license">
-  <img src="https://img.shields.io/badge/platform-Windows%2010%2F11-blue" alt="platform">
-  <img src="https://img.shields.io/github/stars/SeverusZh/dsh-notify-windows?style=social" alt="stars">
-</p>
-**任务完成** ✅ ｜ **等待审批** 🔐 ｜ **等待回答** ❓ —— 离开屏幕也不错过任何需要你处理的事。
-## ✨ 功能
-- **任务完成提醒**：监听会话 `turn/end` 事件，任务完成 / 出错 / 输出超限时立即弹窗，标题自动使用会话标题，正文显示原因与轮次；
-- **权限审批提醒**：监听 `approval/asked` 事件，有操作等待你的审批时立即提醒；会话审批策略为 `never` 时自动跳过（此时没有东西在等你）；
-- **提问确认提醒**：Agent 调用 `ask_user_question` 向你提问时提醒；本部署下所有工具都经 `run_code` 调用，插件会扫描 `run_code` 程序源码中的 `tools.ask_user_question(` 调用并提取问题文本；
-- **防打扰**：默认忽略子代理（subagent）会话，只提醒主会话；
-- **零依赖**：通知通过 Windows PowerShell 5.1 的 WinRT Toast API 发送，自动注册 HKCU 的 AppUserModelId（无需管理员权限）；
-- **可诊断**：可选日志（`%TEMP%\dsh-notify\notify.log`）与 debug 事件日志。
-## 🚀 安装
-项目通过 **`dsh.bundle`** 机制安装：npm 包自带的 `cordis.patch.yml` 会在
-`dsh plugin add` 后自动挂载 `dsh-notify` 入口，**不需要**再手动 `- insert:`。
-```powershell
-dsh plugin --profile web add dsh-notify-windows
-```
-重启 DSH 并刷新浏览器后生效：
-```powershell
-dsh --profile web
-```
-> 注意：不要再用 `- insert:` 手动添加 `dsh-notify`，否则启动会报
-> `duplicate loader entry id: dsh-notify`。想调整配置，在 profile 的
-> `cordis.patch.yml` 里按 id 覆盖即可（见下节）。
-### 更新 / 卸载
-```powershell
-dsh plugin --profile web update dsh-notify-windows
-dsh plugin --profile web remove dsh-notify-windows
-```
-更新后需重启 DSH 宿主（新增 bundle 层需要重新启动）。
-## ⚙️ 配置项
-插件行 `config` 全字段可选，未填按默认值。需要调整时，在
-`$DSH_HOME/profiles/web/cordis.patch.yml` 里按 id 覆盖主条目即可
-（该文件被运行中的 DSH 热监视，改动立即生效，无需重启）：
-```yaml
-- id: dsh-notify
-  name: dsh-notify-windows
-  config:
-    enabled: true
-    reasons: [completed, error, max-tokens]
-    notifyOnStart: true
-    notifyOnApproval: true
-    log: true
-```
-| 配置 | 默认值 | 说明 |
-| --- | --- | --- |
-| `enabled` | `true` | 总开关 |
-| `reasons` | `[completed, error, max-tokens]` | 需要提醒的回合结束原因（可选 `aborted` / `interrupted` / `blocked`） |
-| `includeSubagents` | `false` | 是否也提醒子代理会话 |
-| `notifyOnStart` | `false` | 插件加载时发一条「已激活」通知 |
-| `notifyOnApproval` | `true` | 审批请求提醒（策略 `never` 时自动跳过） |
-| `notifyOnAskUser` | `true` | Agent 提问等待回答时提醒 |
-| `notifyOnGoalRounds` | `false` | /goal 自动推进回合不提醒（目标完成/阻塞的最终回合除外） |
-| `excerpt` | `true` | 通知正文附带 Agent 最后回复的摘要 |
-| `excerptMaxChars` | `80` | 摘要最大字符数 |
-| `appName` | `DeepSeek Harness` | 通知来源显示名与兜底标题 |
-| `aumid` | `DeepSeekHarness.Notify` | 通知 AppUserModelId |
-| `log` | `true` | 写日志到 `%TEMP%\dsh-notify\notify.log` |
-| `debug` | `false` | 把所有会话事件写入日志（排查用，量大） |
-## 🔔 触发场景
-| 场景 | 会话事件 | 通知示例 |
-| --- | --- | --- |
-| 任务完成 | `turn/end` | 「任务已完成（第 N 轮）」 |
-| 任务出错 / 超限 | `turn/end` | 「任务出错」/「输出达到 token 上限」 |
-| 等待审批 | `approval/asked` | 「DeepSeek Harness · 需要审批 / 工具 pwsh：…」 |
-| 等待回答 | `tool/call`（含 run_code 检测） | 「DeepSeek Harness · 需要回答 / 是否继续？」 |
-## 🧪 验证
-```powershell
-node scripts\smoke-test.mjs
-```
-独立进程内用 cordis Context 模拟会话事件：应弹出任务完成 / 审批 / 提问三条测试通知，并断言日志记录与过滤行为（子代理、`never` 策略、无关调用均被过滤）。
-## ❓ 常见问题
-- **收不到通知？** 检查 Windows「通知与操作」设置是否允许该应用显示通知，以及「专注助手」是否开启；首次发送会自动注册 AUMID。
-- **/goal 模式会提醒吗？** 默认不会：自动推进的中间回合保持静默，只有目标完成（或阻塞）的最终回合才提醒；如需每个回合都提醒，把 `notifyOnGoalRounds` 设为 `true`。
-- **为什么审批提醒有时不弹？** 会话审批策略为 `never` 时审批会被自动拒绝、不会等待，插件会跳过提醒；策略为 `ask` 时才提醒。
-- **更新插件代码后如何生效？** 执行 `dsh plugin --profile web update dsh-notify-windows` 后重启 DSH 宿主。
-## 📄 许可证
+# dsh-notify-windows
+> DeepSeek Harness（DSH）插件：当 Agent 需要你关注时，向 Windows 发送系统桌面通知。
+<p align="center">
+  <img src="https://img.shields.io/npm/v/dsh-notify-windows" alt="npm">
+  <img src="https://img.shields.io/github/license/SeverusZh/dsh-notify-windows" alt="license">
+  <img src="https://img.shields.io/badge/platform-Windows%2010%2F11-blue" alt="platform">
+  <img src="https://img.shields.io/github/stars/SeverusZh/dsh-notify-windows?style=social" alt="stars">
+</p>
+**任务完成** ✅ ｜ **等待审批** 🔐 ｜ **等待回答** ❓ —— 离开屏幕也不错过任何需要你处理的事。
+## ✨ 功能
+- **任务完成提醒**：监听会话 `turn/end` 事件，任务完成 / 出错 / 输出超限时立即弹窗，标题自动使用会话标题，正文显示原因与轮次；
+- **权限审批提醒**：监听 `approval/asked` 事件，有操作等待你的审批时立即提醒；会话审批策略为 `never` 时自动跳过（此时没有东西在等你）；
+- **提问确认提醒**：Agent 调用 `ask_user_question` 向你提问时提醒；本部署下所有工具都经 `run_code` 调用，插件会扫描 `run_code` 程序源码中的 `tools.ask_user_question(` 调用并提取问题文本；
+- **防打扰**：默认忽略子代理（subagent）会话，只提醒主会话；
+- **零依赖**：通知通过 Windows PowerShell 5.1 的 WinRT Toast API 发送，自动注册 HKCU 的 AppUserModelId（无需管理员权限）；
+- **可诊断**：可选日志（`%TEMP%\dsh-notify\notify.log`）与 debug 事件日志。
+## 🚀 安装
+项目通过 **`dsh.bundle`** 机制安装：npm 包自带的 `cordis.patch.yml` 会在
+`dsh plugin add` 后自动挂载 `dsh-notify` 入口，**不需要**再手动 `- insert:`。
+```powershell
+dsh plugin --profile web add dsh-notify-windows
+```
+重启 DSH 并刷新浏览器后生效：
+```powershell
+dsh --profile web
+```
+> 注意：不要再用 `- insert:` 手动添加 `dsh-notify`，否则启动会报
+> `duplicate loader entry id: dsh-notify`。想调整配置，在 profile 的
+> `cordis.patch.yml` 里按 id 覆盖即可（见下节）。
+### 更新 / 卸载
+```powershell
+dsh plugin --profile web update dsh-notify-windows
+dsh plugin --profile web remove dsh-notify-windows
+```
+更新后需重启 DSH 宿主（新增 bundle 层需要重新启动）。
+## ⚙️ 配置项
+插件行 `config` 全字段可选，未填按默认值。需要调整时，在
+`$DSH_HOME/profiles/web/cordis.patch.yml` 里按 id 覆盖主条目即可
+（该文件被运行中的 DSH 热监视，改动立即生效，无需重启）：
+```yaml
+- id: dsh-notify
+  name: dsh-notify-windows
+  config:
+    enabled: true
+    reasons: [completed, error, max-tokens]
+    notifyOnStart: true
+    notifyOnApproval: true
+    log: true
+```
+| 配置 | 默认值 | 说明 |
+| --- | --- | --- |
+| `enabled` | `true` | 总开关 |
+| `reasons` | `[completed, error, max-tokens]` | 需要提醒的回合结束原因（可选 `aborted` / `interrupted` / `blocked`） |
+| `includeSubagents` | `false` | 是否也提醒子代理会话 |
+| `notifyOnStart` | `false` | 插件加载时发一条「已激活」通知 |
+| `notifyOnApproval` | `true` | 审批请求提醒（策略 `never` 时自动跳过） |
+| `notifyOnAskUser` | `true` | Agent 提问等待回答时提醒 |
+| `notifyOnGoalRounds` | `false` | /goal 自动推进回合不提醒（目标完成/阻塞的最终回合除外） |
+| `excerpt` | `true` | 通知正文附带 Agent 最后回复的摘要 |
+| `excerptMaxChars` | `80` | 摘要最大字符数 |
+| `appName` | `DeepSeek Harness` | 通知来源显示名与兜底标题 |
+| `aumid` | `DeepSeekHarness.Notify` | 通知 AppUserModelId |
+| `log` | `true` | 写日志到 `%TEMP%\dsh-notify\notify.log` |
+| `debug` | `false` | 把所有会话事件写入日志（排查用，量大） |
+| `openOnClick` | `true` | 任务完成 / 审批 / 提问 toast 是否可点击（false 回退为旧的无点击 toast） |
+| `preferExisting` | `true` | true 走 launcher 优先聚焦已开 DSH 窗口；false 直接用默认浏览器打开 URL |
+| `webUrl` | `''` | 覆盖自动发现的基地址（如 `http://192.168.1.5:4000`），留空自动发现（默认 `http://127.0.0.1:3080`） |
+## 🔔 触发场景
+| 场景 | 会话事件 | 通知示例 |
+| --- | --- | --- |
+| 任务完成 | `turn/end` | 「任务已完成（第 N 轮）」 |
+| 任务出错 / 超限 | `turn/end` | 「任务出错」/「输出达到 token 上限」 |
+| 等待审批 | `approval/asked` | 「DeepSeek Harness · 需要审批 / 工具 pwsh：…」 |
+| 等待回答 | `tool/call`（含 run_code 检测） | 「DeepSeek Harness · 需要回答 / 是否继续？」 |
+## 🔗 点击通知跳转
+任务完成 / 等待审批 / 等待回答的 toast 可点击 → 打开 DSH Web GUI。优先聚焦已打开的
+DSH 浏览器标签或 Chrome Application 窗口；没有已开窗口时在默认浏览器新开标签并打开 GUI。
+目标 URL 带 `?session=<id>` 参数（rc.8 前端暂不消费，为未来深链预留）。
+**配置：**
+- `openOnClick`（默认 `true`，`false` 则关闭可点击，回退为旧的无点击 toast）；
+- `preferExisting`（默认 `true`，`true` 走 launcher 优先复用已开窗口；`false` 直接用默认浏览器打开 URL）；
+- `webUrl`（可选，覆盖自动发现的基地址，如 `http://192.168.1.5:4000`，留空自动发现 / 默认 `http://127.0.0.1:3080`）。
+**注意事项：** 首次点击会自动注册 `dshnotify://` 协议处理器（HKCU，无需管理员）；故障会静默降级为「默认浏览器打开」。
+> 说明：DSH 0.1.0-rc.8 前端暂不支持按 URL 直达单个会话；点击后打开的是 DSH 界面（首页/会话列表）并聚焦已有窗口，目标会话需在列表中选择。未来 DSH 前端支持深链后 `?session=<id>` 将直接定位。
+## 🧪 验证
+```powershell
+node scripts\smoke-test.mjs
+```
+独立进程内用 cordis Context 模拟会话事件：应弹出任务完成 / 审批 / 提问三条测试通知，并断言日志记录与过滤行为（子代理、`never` 策略、无关调用均被过滤）。
+## ❓ 常见问题
+- **收不到通知？** 检查 Windows「通知与操作」设置是否允许该应用显示通知，以及「专注助手」是否开启；首次发送会自动注册 AUMID。插件启动时会自检通知通道（`powershell.exe` 与 `notify.ps1` 是否可达），通道不可用会在 DSH 日志中立即告警；每次发送失败也会记录详细原因到 `%TEMP%\dsh-notify\notify.log`。
+- **WSL 下收不到通知？** 插件会自动用 `wslpath -w` 把脚本路径转成 `\\wsl.localhost\...` UNC 路径，并优先通过 `/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe` 调用 PowerShell（不依赖 PATH，systemd / cron 等最小环境也能工作）。若仍失败，查看 `%TEMP%\dsh-notify\notify.log` 中的 `error` 条目。
+- **/goal 模式会提醒吗？** 默认不会：自动推进的中间回合保持静默，只有目标完成（或阻塞）的最终回合才提醒；如需每个回合都提醒，把 `notifyOnGoalRounds` 设为 `true`。
+- **为什么审批提醒有时不弹？** 会话审批策略为 `never` 时审批会被自动拒绝、不会等待，插件会跳过提醒；策略为 `ask` 时才提醒。
+- **更新插件代码后如何生效？** 执行 `dsh plugin --profile web update dsh-notify-windows` 后重启 DSH 宿主。
+## 📄 许可证
 [MIT](./LICENSE) © 2026 SeverusZh