桌面通知点击回窗baobaolaodie/cc-dsh-notifier

cc-dsh-notifier

为 Claude Code 和 DeepSeek Harness 会话提供 Windows 桌面通知

权限请求 · 提问 · 等待输入 · 点击返回

English · 中文

当智能体需要你关注、而你并未注视其窗口时，cc-dsh-notifier 会弹出带有声音的 Windows 原生通知。它通过钩子系统为 Claude Code 服务，并通过一个小型 bundle 插件为 DeepSeek Harness 服务，二者共享同一条守护进程流水线。点击通知即可返回会话窗口。零第三方 npm 依赖。

功能特性

| 功能 | 描述 |
|---|---|
| 中断事件 | 在权限请求、提问和等待输入时发出通知 |
| 焦点感知 | 当会话窗口处于焦点时抑制通知；仅在未聚焦时通知 |
| 点击返回 | SetForegroundWindow 定位到会话窗口；浏览器标签页通过 CDP 激活，并以 UIA 作为回退方案 |
| 多会话 | 每个会话绑定各自的窗口句柄；通知携带会话身份 |
| 本地化通知 | 通知文本遵循 Windows 显示语言（auto）或 language 设置（zh/en） |
| DeepSeek Harness | dsh-notifier 插件通过一次安装即可覆盖 web 和 tui 配置文件 |

快速开始

前置条件

- Windows 10 或 11
- Node.js 18 或更高版本
- 安装了 winrt 包的 Python 3：pip install winrt-runtime winrt-Windows.UI.Notifications winrt-Windows.Data.Xml.Dom

安装（Claude Code）

node scripts/install.mjs

安装程序会备份 ~/.claude/settings.json，注入五个钩子，注册 cc-notifier AppUserModelID，并写入默认配置。之后请打开一个新的 Claude Code 会话。

安装（DeepSeek Harness）
推荐 — 从最新发布下载 tarball 并安装（无需克隆仓库，无需凭据）：

dsh plugin --profile web add ./baobaolaodie-cc-dsh-notifier-0.1.5.tgz
dsh plugin --profile dsh-tui add ./baobaolaodie-cc-dsh-notifier-0.1.5.tgz

版本说明 / Version note: 顶部徽章 0.1.2 是 root 包版本;上方 tarball 名 0.1.5 是 dsh 插件包版本,两者是两个独立的发布单元(en: top badge = root package, tarball = dsh plugin; independent release units).
备选方案 — git 安装（克隆整个仓库，零配置）：

dsh plugin --profile web add github:baobaolaodie/cc-dsh-notifier
dsh plugin --profile dsh-tui add github:baobaolaodie/cc-dsh-notifier

GitHub Packages（@baobaolaodie/cc-dsh-notifier）仅作为维护者便利渠道存在：GitHub Packages 的 npm registry 下载时始终需要 read:packages token，即使是公开包也是如此（已验证）。请改用 tarball 或 git 安装。

已在 Windows 11 上针对 dsh 0.1.0-rc.6 验证（2026-08-16）：web 和 tui 配置文件、权限/提问/等待输入通知、焦点感知静默、点击返回，以及 tarball 安装流程。

dsh-TUI · dsh-TUI 生态系统中的 Windows toast 通知插件。

验证

npm test

用法

Claude Code

启动一个会话并切换到其他窗口。当 Claude 请求权限、提出问题或完成一轮对话时，系统会发出通知。

claude
switch to another window; toasts appear when Claude needs you

DeepSeek Harness

该插件将 dsh 会话事件转发到同一管道中。Web 会话绑定到浏览器窗口；tui 会话绑定到终端窗口：

dsh web          # or: dsh --profile web
dsh-tui          # or: dsh --profile dsh-tui

手动触发（测试）

node scripts/test.mjs permission-request   # permission-request | ask-user-question | stop | session-start

当目标窗口处于焦点状态时，toast 会被抑制，因此请切换到其他窗口以观察它们。

配置

编辑 ~/.cc-notifier/config.json（安装时创建）：

| 键 | 默认值 | 描述 |
|---|---|---|
| enabled | true | 设为 false 以全局禁用通知 |
| dedupWindowMs | 0 | 去重窗口（毫秒）；0 = 不去重；>0 按会话+类型合并 |
| pythonPath | 空 | toast 解释器的绝对路径（由安装程序写入）；空 = 使用 PATH 中的 python |
| pollIntervalMs | 10000 | 守护进程窗口轮询周期（毫秒） |
| windowWhitelist | [] | 用于 dsh web 绑定/焦点的浏览器进程白名单（例如 chrome.exe/msedge.exe） |
| sound | true | 设为 false 以静音 toast 声音 |
| language | auto | Toast 语言：auto（系统显示语言，zh-→zh，en-→en，其他/失败→en）、zh 或 en |

架构
事件驱动管道仅在会话活跃时运行。Claude Code hooks 和 dsh 插件都会产生相同的规范化载荷；常驻守护进程决定是否通知，Python 代理负责显示 toast：

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px'}}}%%
flowchart LR
CC["Claude Codehooks"] --> NA["notify-agent.mjsforwarder"]
DSH["dsh-notifierplugin · web/tui"] --> NA
NA -->|"HTTP · localhost"| DM["daemon.mjssessions · focus · lifecycle"]
DM --> TA["toast-agent.pywinrt toast"]
TA -->|"click"| WIN["session windowSetForegroundWindow · CDP/UIA tab"]
DM --> ST[("state · logs%LOCALAPPDATA%")]

classDef client fill:#3B82F6,stroke:#2563EB,color:#fff,stroke-width:2px
classDef service fill:#10B981,stroke:#059669,color:#fff,stroke-width:2px
classDef data fill:#8B5CF6,stroke:#7C3AED,color:#fff,stroke-width:2px

class CC,DSH,WIN client
class NA,DM,TA service
class ST data

守护进程为单实例：按需唤醒，在无会话 60 秒后退出，并在其代码变更时自动重启。会话会在守护进程重启后自动重新注册。

项目结构

├── scripts/               # Runtime pipeline
│   ├── notify-agent.mjs   # Hook forwarder (Claude Code)
│   ├── daemon.mjs         # Resident process: sessions, focus, dedup
│   ├── toast-agent.py     # Python winrt toast + click handling
│   └── lib/               # Shared modules, win32 bridge, CDP/UIA helpers
├── plugins/
│   └── dsh-notifier/      # dsh bundle plugin (web + tui profiles)
├── test/                  # node:test suite (explicit file list)
├── docs/                  # Installation, usage, troubleshooting (bilingual)
├── dsh-plugin.json        # dsh-ecosystem-spec Community v0.15 declaration manifest
└── package.json           # Zero runtime dependencies

技术栈

| 层级 | 技术 | 用途 |
|---|---|---|
| 运行时 | Node.js 18+ (ESM) | 转发器、守护进程、插件 |
| 通知 | Python 3 + winrt | Windows toast 渲染与激活 |
| 窗口桥接 | PowerShell 5.1 + C# 辅助程序 | 窗口枚举、前台查询、CDP/UIA 标签页激活 |
| 测试 | node:test | 单元 + 集成测试 |

部署

CI 在 GitHub Actions 上运行（test × 6 矩阵，覆盖 Ubuntu 和 Windows 上的 Node 18/20/22，外加 quality、pr-policy、docs-links 和一个汇总任务）。参见 .github/workflows/ci.yml。

贡献

1. Fork 仓库
2. 创建功能分支（git checkout -b feature/your-change）
3. 使用 Conventional Commits 提交（feat:、fix:、docs:……）
4. 发起 Pull Request

PR 必须通过完整的 CI 套件，包括双语文档镜像检查和版本一致性检查。参见 CONTRIBUTING.md。

许可证

MIT