dsh-away-notify

像 Codex 那样提醒你：只有当你没在看 dsh 页面时，任务完成 / 出错 / 等待审批 / agent 提问 /
goal 完成才弹桌面通知，点击通知能回到对应会话。

零运行时依赖、零构建，dsh plugin add 装完即用。

部署形态

> ⚠️ Windows 用户请先看 docs/windows.md。 插件检出与 $DSH_HOME 不在
> 同一盘符时，dsh plugin add 会静默装出一个永远不会加载的插件——退出码还是 0。仓库里带了
> 一键安装器替你兜住这件事，见 Windows 原生。

安装

Windows 原生

先读 docs/windows.md（跨盘符会把插件装坏，而且没有任何报错）。用仓库里的
安装器，它会跑正常命令、校验结果、并修好 pnpm 弄坏的东西：

cd <插件检出目录>
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install-windows.ps1

WSL / Linux

dsh plugin --profile web add github:s11phere/dsh-away-notify

直接从 GitHub 装（pnpm 会自己去 clone，不需要本地检出）。要装你改过的版本，就把最后的 spec
换成检出目录的绝对路径：dsh plugin --profile web add /path/to/dsh-away-notify。

装完之后

重启 dsh web，并刷新浏览器页面。

新增 bundle 只有启动时才会被读进 dsh.profile.bundles；浏览器半部（client.js）也需要刷新
页面才会加载。profile 的 cordis.patch.yml 是热监视的，改配置不用重启。

验证是否挂上（不启动服务）：

dsh --profile web --dump-config | grep -A2 dsh-away-notify

首次接线自检

先确认「通知通道」本身是通的，不必等真实的回合结束：

node scripts/selftest-notify.mjs "标题" "正文"

它会实际弹一条 Toast，并回读 Windows 通知中心来客观确认落地。再要看插件侧的日志（已加载 /
已抑制(<原因>) / 已撤回通知），在 profile 的 cordis.patch.yml 里临时打开 notifyOnLoad 与
debug，步骤与接线成功的标志见
docs/windows.md 的「通知通道自检」——确认通路后记得把这两项
关掉。

> 出问题了先看故障排查：不弹 / 点了回不去 / 提醒赖着不走都有对照表。

配置

在 profile 的 cordis.patch.yml 里按 id 覆盖（该文件被热监视，但新增 bundle 后首次仍需重启）：

- id: dsh-away-notify
config:
# 五类触发
onTurnComplete: true
onTurnError: true
onTurnAborted: true
onTurnMaxTokens: true
onApproval: true
onQuestion: true
onGoalComplete: true
# 行为
suppressGoalRounds: true   # /goal 中间轮次静默
rootsOnly: true            # 子代理会话不打扰
cooldownMs: 10000          # 同会话同类型最小间隔
presenceTtlMs: 45000       # 在场状态有效期
previewMaxChars: 140       # 正文摘要截断长度
sound: true                # 系统提示音
openOnClick: true          # Toast 可点击回跳
persistent: true           # 通知一直停留，直到点它或切回 dsh
dismissOnReturn: true      # 切到某会话时撤回它自己的通知（按会话比对，不误伤别的会话）
includeToken: true         # URL 带鉴权 token（取舍见 docs/security.md）
useProtocolHandler: true   # 注册 dshnotify: 协议，点击优先聚焦已有窗口
titleTag: true             # 给标题加 [dsh:]，多实例时精确聚焦对应窗口
spoolDir: ''               # 点击请求与焦点助手的工作目录；留空 = <插件目录>/.focus-spool
focusWindowMarker: 'DeepSeek Harness'  # 用窗口标题里的这个串识别 dsh 窗口
focusTtlMs: 90000          # 「待跳转会话」有效期
titlePrefix: 'DSH'
appName: 'DeepSeek Harness'
appId: 'DeepSeek Harness'  # Windows 通知来源名
webUrl: ''                 # 留空则自动探测
debug: false               # 写文件日志
notifyOnLoad: false        # 加载时发自检通知

> appName 目前没有接线（声明了但无处读取），改它不会有效果；要区分通知来源请改 appId。
> includeToken 的取舍（token 会进本机通知历史）见安全说明。

功能

• 五类触发（可分别开关）：回合完成、出错 / 中断 / 达到输出上限、等待审批、agent 提问、goal 完成
• 一直停留：通知用 Windows 的 scenario="reminder" 发出，不会被系统几秒后收走——它待在
  屏幕上，直到你点它、或切到它对应的那条会话。撤回是按会话的：待在 dsh 里看别的会话不会
  误撤后台会话的通知（早期版本会，已修）
• 两级前台抑制：见下方在场判定
• 不做静音黑洞：在场状态带 45 秒 TTL，标签页崩溃 / 浏览器被关掉后自动视为「离开」，不会永久静音
• 点击回跳：Toast 可点击，优先回到已有的那个 dsh 标签页，并自动切到出事的那条会话；
  浏览器窗口最小化时也回得去（最小化的 Chromium 窗口对 UI Automation 一个标签都不暴露，脚本
  会先把窗口还原、再选标签页）。点击后约 0.1-0.2 秒就把对应窗口提到前台，代价是多一个常驻的
  小助手进程。原理与实测见 docs/click-focus.md
• 多实例也认得准：同一台机器上并存 Windows 原生与 WSL 的 dsh 时，浏览器标题带按端口区分的
  [dsh:] 后缀，点击通知仍会聚焦到出事的那一个实例；细节与回退开关见
  docs/windows.md
• 防刷屏：同会话同类型通知有冷却时间；同一件事反复触发是替换而不是叠加（同 tag+group 的
  通知在 Windows 上是替换语义）；子代理会话默认不打扰；/goal 自动推进的中间轮次默认静默，只在
  目标完成 / 阻塞时提醒
• 原生 Toast 细节：正文标注会话标题与结果摘要，带系统提示音，并带一个可点的操作按钮
• 可以被别的插件接管：谁建的会话谁说了算——其它插件能声明「这条会话别打扰」以及「点它的通知
  时在右栏打开哪个 tab」，away-notify 不认识任何具体插件、也不做标题匹配，见
  给其他插件的接口

在场判定

状态按标签页记录（每个标签页一个 clientId，存在 sessionStorage），而不是按会话——所以同一
标签页从会话 A 切到会话 B 时，新上报会直接覆盖，A 立刻恢复提醒，不必等 TTL 过期。

换句话说：切到别的标签页（页面不可见）或切到别的应用（窗口失焦）→ 一律提醒。

> 打开浏览器 DevTools 会让页面失焦（document.hasFocus() 变 false），插件会判为「离开」——
> 这是预期行为，不是故障；此时在控制台查到的 mode 可能是 away。

上报字段、拿不到会话 id 时的自动升级、以及自查当前判定结果的控制台片段，见
docs/implementation-notes.md。

文档

开发

policy.js / presence.js / suppress.js / notifier.js 都不依赖 DSH 运行时，可以脱离 dsh 单测：

node --test

新增会触发通知或注册协议的用例时，请沿用 apply(ctx, config, deps) 的 spawn 注入通路——
不要再靠「写个假的 powershell.exe 让系统去执行」（Windows 只认 PE 映像，不认 shebang）；
假 ctx 的服务读取严格性、跨插件接口如何验证，见
测试约定。

改动后建议在真机跑一遍 node scripts/selftest-notify.mjs 确认通知通道，再重启 dsh 手动过一遍
「离开 → 收到通知 → 点击回跳」。

许可证

MIT