@deepseek-ai/dsh-windows-notify

Readme

# dsh-windows-notify

> 为 **DeepSeek Harness**（`dsh`）提供 Windows 原生通知。

当 Agent **需要你的授权**、**需要你选择方案/分支**、或**处理完一轮任务**时，弹出一条 Windows 桌面通知；点击通知即可把已经打开的 DSH 浏览器窗口切到最前面。

本插件只负责**提醒**：授权卡片和选项列表仍然由网页端渲染，通知永远不会替你作答。

**平台：** 仅 Windows 10/11。其他平台上宿主端会直接失效（不加载）。

[English](README.en.md)

## 功能

| 时机 | 通知内容 | 开关 |
|---|---|---|
| 工具需要授权（`approval/request`） | `DSH 需要你的授权` + 工具名 + 理由 | `approval` |
| 需要选择分支/方案（`user-questions/request`） | `DSH <标题>` + 问题 + 最多 6 个选项文字 | `choice` |
| 一轮任务完成（`turn/end` 之后 `agent/status` 变为 idle） | `DSH 任务完成` | `completion` |
| 点击任意通知 | 把已打开的 DSH 窗口切到最前（没有时才新开） | `focusOnClick` |
| 每一轮 | 常驻系统提示规则：待办状态**逐条回写**，禁止批量补写 | `todoStatusPolicy` |
| — | 总开关，关闭后三种通知都不发 | `enabled` |

## 环境要求

- Windows 10/11
- 挂载了 Web 应用（`web`）的 `dsh` profile
- Windows PowerShell 5.1（Windows 自带）

## 安装

1. 克隆到你的树外插件目录：

   ```powershell
   git clone https://github.com/Exynos671/dsh-windows-notify.git "$env:USERPROFILE\.dsh\profiles\plugins\dsh-windows-notify"
   ```

2. 在 `profiles\node_modules` 下暴露这个包 —— dsh 的模块解析依赖这个目录联接（junction）：

   ```powershell
   New-Item -ItemType Junction `
     -Path   "$env:USERPROFILE\.dsh\profiles\node_modules\@deepseek-ai\dsh-windows-notify" `
     -Target "$env:USERPROFILE\.dsh\profiles\plugins\dsh-windows-notify"
   ```

3. 挂载插件。把下面这段追加到 `~\.dsh\profiles\web\cordis.patch.yml`（或追加到 home 级的 `~\.dsh\cordis.patch.yml`，对所有 profile 生效）：

   ```yaml
   - insert:
       - id: windows-notify
         name: '@deepseek-ai/dsh-windows-notify'
   ```

4. 重启 dsh（若为 `patchReload: live` 也会自动热重载）。此时 **设置 → 通用 → "Windows 通知"** 就会出现各个开关。

### 另一种方式：作为 bundle 安装

本包声明了 `dsh.bundle.patch`，也可以作为 bundle 层安装：

```powershell
dsh plugin --profile web add github:Exynos671/dsh-windows-notify
```

**不要两种方式同时使用**：手动挂载行加 bundle 安装会把这个包挂载两次，客户端模块系统会直接报错。

## 设置

设置位于 `dsh-notify` 命名空间，写入 `~\.dsh\settings.yaml`，改动立即生效。可在 **设置 → 通用 → "Windows 通知"** 中拨动开关，也可以手动编辑：

```yaml
dsh-notify:
  enabled: true
  approval: true
  choice: true
  completion: true
  focusOnClick: true
  todoStatusPolicy: true
```

`enabled: false` 只会让三种通知静音，插件仍然加载（常驻待办规则也仍然生效）。要彻底卸载，把挂载行删掉或禁用：

```yaml
- insert:
    - id: windows-notify
      name: '@deepseek-ai/dsh-windows-notify'
      disabled: true
```

## 工作原理

- **只读监听。** 所有监听器都会调用 `next()`，把请求交还给网页端应答者。如果有插件抢先返回结果，网页端就不会再渲染授权卡片/选项；本插件从不这样做。
- **根事件总线。** 由 profile patch 挂载的插件处于 agent preset 的作用域内，而 `approval/request`、`user-questions/request` 是在**根**事件服务上分发的，因此监听器挂在 `ctx.root.events` 上。另有一层 `internal/dispatch` 观察者作为不受作用域规则限制的兜底，并用去重集合保证每个请求只通知一次。
- **原生通知。** 宿主端调用同目录下纯 ASCII 的 PowerShell 脚本；面向用户的文字以 base64 传入，因为 Windows PowerShell 5.1 会把无 BOM 的 UTF-8 当 ANSI 读，中文会损坏。
- **AUMID + URI 协议。** `ensure-aumid.ps1` 创建一个带有 AppUserModelID（`DeepSeekHarness.Notify`）的开始菜单快捷方式，并注册 `dsh-notify:` 协议 —— 前者让 Windows 能投递通知，后者让点击通知能唤起窗口。
- **点击聚焦。** `focus-window.ps1` 枚举顶层窗口，优先匹配标题（`DeepSeek Harness`），还原并调用 `SetForegroundWindow`；只有找不到匹配窗口时才会新开标签页。

## 文件结构

```
index.mjs          宿主端（Cordis 插件）：事件、设置 schema、系统提示规则
client.js          浏览器端：设置 → 通用 的那一行及其 CSS
package.json       dsh bundle / client 清单
cordis.patch.yml   bundle patch（挂载行）
toast.ps1          弹出单条 Windows 通知
ensure-aumid.ps1   创建 AUMID 快捷方式 + URI 协议
focus-window.ps1   聚焦（或打开）DSH 浏览器窗口
test/              启动加载器与设置测试
```

## 开发

```powershell
node test/notify-settings.test.mjs
```

## 说明

- 包名 `@deepseek-ai/dsh-windows-notify` 是刻意保持原样的：浏览器端注册的就是这个精确 id，启动加载器会拒绝"没有注册自身行 id"的 bundle。

## 许可证

MIT