前言¶

使用 DeepSeek Harness（dsh）跑代理任务时，常见的问题是：任务在后台继续执行，而开发者已经切走窗口，不知道顶层任务何时完成、何时出错，也不知道是否正在等待沙箱审批或代理提问。手动盯日志不是长久之计。

下面介绍一个 DSH 插件：dsh-win-notify。它在 Windows 上弹出带声音的 Toast 通知，并在点击通知时尽量把现有 DSH GUI 会话切到前台，而不是反复打开新的临时浏览器标签。

这是什么¶

dsh-win-notify 是一个 DeepSeek Harness（dsh）插件，由 MuziIsabel 维护，许可证为 MIT。

它解决的问题是：当代理任务完成、出错、等待审批或等待回复时，在 Windows 10/11 上给出带声音的通知；点击通知后，优先切换并显示已有的 GUI 标签。

插件显示应用名为 DeepSeek，并使用官方鲸鱼图标；通知能力仅依赖 Windows 自带的 PowerShell 5.1，不要求额外安装运行时。

核心功能¶

• 顶层代理回合完成时通知：会话代理状态由 running 变为 idle 时触发。
• 子代理回合保持静默，避免子任务过程频繁打扰。
• 通知正文显示最近一条用户提示词。
• 任务出错时可配置为通知。
• 等待沙箱 / 权限审批时可配置为通知。
• 代理通过 ask_user_question 提问并等待回复时可配置为通知。
• 聚焦感知：如果 GUI 页面处于前台，并且当前正显示触发事件的会话，则抑制该会话的通知。
• 手动停止的任务不算完成，不弹通知。
• 点击通知时优先切换并前台显示现有 GUI 标签；不产生临时浏览器标签；仅当没有存活 GUI 时才新开标签。
• 身份注册失败时，回退到 NotifyIcon 气泡。
• 仅依赖 Windows 自带的 PowerShell 5.1。

安装与启用¶

先在目标 profile 安装插件。以 web profile 为例：

dsh plugin --profile web add github:MuziIsabel/dsh-win-notify

执行后，dsh plugin 会在 profile 目录内转发给 pnpm，bundle 会把自身合并进该 profile 的 dsh.profile.bundles 列表。

安装完成后，重启 profile，或让该 profile 的 HMR 生效，即可激活插件。

如果你希望在其他 profile 收到通知，可以按同样方式安装到 headless 等 profile。

卸载命令：

dsh plugin --profile web remove dsh-win-notify

典型用法¶

插件会在 profile 中插入加载行 win-notify。你可以在 profile 的 cordis.patch.yml 中覆盖配置。

下面是 README 中给出的完整配置示例：

- id: win-notify
  config:
    enabled: true          # 启用插件（默认 true）
    sound: default         # default | reminder | sms | alarm | silent
    onError: true          # 任务出错时也通知（默认 true）
    openOnClick: true      # 点击通知打开/切换 GUI 会话（默认 true）
    directActivate: true   # 优先投递给存活的本机回环 GUI 标签；否则走浏览器深链
    baseUrl: ''            # 自定义 GUI 根地址（默认自动取 webServer 端口）
    approval: true         # 等待用户审批时通知（默认 true）
    approvalWaitMs: 3000   # 审批等待多久后弹通知
    question: true         # 等待用户回复时通知（默认 true）
    questionWaitMs: 3000   # 提问等待多久后弹通知
    suppressWhenVisible: true  # 正查看的会话抑制通知（默认 true）
    visibilityTtlMs: 25000      # 前台状态新鲜度窗口（客户端约每 10 秒心跳）
    title: 'DeepSeek Harness'
    body: '任务已完成'
    bodyError: '任务出错'
    maxPromptChars: 64

如果只是临时关闭通知，可以只覆盖 enabled：

- id: win-notify
  config:
    enabled: false

如果需要修改提示词长度或文案，可以覆盖：

- id: win-notify
  config:
    maxPromptChars: 80
    title: 'DeepSeek'
    body: '任务已完成'
    bodyError: '任务出错'

点击通知如何工作¶

对本机回环 GUI 地址，插件会注册 dsh-win-notify:// 协议。点击通知后，它启动本地微型 DeepSeek.exe 助手，而不是直接打开浏览器。

该助手请求本机 DSH 服务向最近聚焦的存活 GUI 标签投递 open-session 命令；对应标签在原地调用 sessions.open(id)。这样不会整页刷新，也不会新开浏览器标签。

如果成功确认，助手还会尽力用 Windows UI Automation 选中标题匹配的 Chrome / Edge 标签，方便你在其他标签浏览时把 DSH 标签带到前台。浏览器窗口最大化或普通大小时保持原状；仅最小化的窗口会被恢复。

需要注意：浏览器辅助功能、权限级别、虚拟桌面与焦点抢占策略仍可能阻止前台切换；此时会话也已在后台选中。

如果没有存活 GUI 及时确认，或协议注册不可用，助手会安全回退到常规 <gui>/?session=<id> 深链；该深链的 BroadcastChannel 交接作为第二重回退。

首次自定义协议点击可能需要一次性浏览器 / Windows 确认。非回环的自定义 baseUrl 出于安全考虑保持常规 HTTP 深链。

身份注册与诊断日志¶

Windows 只展示来自已注册身份的 toast。插件激活时会自动做一次性身份注册：

1. 向 %LOCALAPPDATA%\DeepSeek 编译一个微型 DeepSeek.exe 占位程序。
2. 创建指向它的开始菜单快捷方式 DeepSeek.lnk，图标为多尺寸 DeepSeek.ico。
3. 通过 IPropertyStore P/Invoke 把 AppUserModelID（DSH.WinNotify）写入快捷方式。

注册完成后，通知会以 DeepSeek 名称和鲸鱼图标显示。

DeepSeek.lnk 是通知身份载体，请勿删除。如果缺失，插件会自动重建。

插件会把每次注册尝试与通知追加记录到：

$DSH_HOME/dsh-win-notify.log

适用场景与注意¶

适合在 Windows 10/11 上使用 DSH 的开发者，尤其是以下情况：

• 代理任务经常运行较长时间，完成后需要被提醒。
• 任务出错时也需要及时收到通知。
• 任务等待沙箱审批或 ask_user_question 回复时，需要被提醒回来处理。
• 希望点击通知后回到现有 DSH GUI 会话，而不是不断打开新标签。

注意事项：

• 环境要求为 Windows 10/11，以及 dsh 的任意 profile（web、headless、tui）。
• 插件以当前 dsh 进程权限运行，因此安装前建议检查源码与许可证。
• 通知身份依赖开始菜单快捷方式 DeepSeek.lnk，缺失时插件会重建，但不要手动删除。
• 如果没有收到通知，先检查 Windows 通知设置中 DSH.WinNotify 是否启用，并确认 DeepSeek.lnk 是否存在。
• 图标源自 DeepSeek Harness favicon（@deepseek-ai/dsh-web-frontend，MIT © DeepSeek）。

链接¶

• GitHub：https://github.com/MuziIsabel/dsh-win-notify
• 可在 DSH 插件 / 社区目录中搜索插件名 dsh-win-notify。