dsh-plugin-turn-notify

每当一个 DSH 回合结束，弹出系统原生通知并播放提示音（类似 OpenCode / Claude Code 的完成提醒）。

纯 Host 端 ESM 插件，零运行时依赖；通知通过 Node 子进程调用平台命令实现。

事件从哪里来

DSH 没有独立的 turn/end cordis 事件。turn/end 是 agent loop 写入会话日志的会话事件 （session.append('turn/end', { turn, reason })，见 @deepseek-ai/dsh-agent-loop）， 每个持久化会话事件都会以 session/event(session, event) 的形式广播到全局总线， event 的信封与日志一致：{ type, seq, time, data }。

因此监听方式是：

ctx.on('session/event', onSessionEvent, { global: true })
// onSessionEvent 内只处理 event.type === 'turn/end'

global: true 保证监听器挂在 profile 级作用域，不会被发出事件的 session/agent 作用域回收， 任何会话的回合结束都能收到。

目录结构

dsh-plugin-turn-notify/
├── package.json          # dsh.bundle.patch + locale/icon 导出
├── cordis.patch.yml      # bundle 层：insert 插件行与默认 config
├── index.js              # apply(ctx, config)：事件监听、过滤、分发
├── lib/
│   ├── format.js         # 载荷逐字段校验、摘要/耗时/文案拼装
│   ├── notify.js         # Windows toast / macOS osascript / Linux notify-send
│   └── log.js            # 永不抛出的 console 日志
├── scripts/
│   ├── test-turn-end.js  # 手动触发一次通知（真实后端）
│   └── selftest.js       # 离线自检（含假 ctx 的接线测试）
├── locale/{en,zh}.json   # Plugin Manager / Settings 显示元数据
└── icon.svg

配置

bundle 层的 cordis.patch.yml 只负责 insert 插件行。要改默认值，请在 $DSH_PROFILE_DIR/cordis.patch.yml 里用相同 id 覆盖该行（匹配覆盖会替换整个 config， 所以要把需要保留的键一并写出）：

- id: turn-notify
  name: dsh-plugin-turn-notify
  config:
    enabled: true          # 总开关
    sound: true            # 附带系统提示音
    reasons:               # 触发提醒的 turn/end reason.kind
      - completed          # 成功
      - error              # 出错
      - blocked            # 受阻
      - max-tokens         # 输出被截断
    subagents: false       # false = 忽略子代理会话，只提醒主会话
    locale: auto           # auto | zh | en
    debounceMs: 800        # 同一会话 800ms 内不重复提醒
    minDurationMs: 0       # 短于该时长的回合一概不提醒
    includeSummary: true   # 附最后一段 assistant 文本
    summaryLength: 80      # 摘要字符数上限

可选 reason：completed error blocked max-tokens aborted interrupted forked。 未列出的原因一律不提醒。未识别的字段被忽略，非法值回落到默认值并打印一条 warn。

通知内容

标题：回合完成 · default-workspace      # <原因标题> · <workspace 目录名，缺失时取 session 短 id>
正文：已完成 · 12.4s · 最后一段 assistant 文本前 80 字符

• 成功用 done 提示音（Asterisk / Glass / complete），失败类原因用 alert（Hand / Basso / dialog-error）。
• 耗时来自同回合最新的 turn/start 事件的 time；取不到时不显示。
• subagents: true 时子代理回合只记录，不单独弹窗；随后主回合通知尾注 (subagent <label>)。

安装

dsh plugin 只是把 pnpm 转发到 profile 目录，并且会登记 bundle；只用 pnpm add 不会登记。

# 1) 本地目录（开发调试；以链接方式装入，改代码后重启即生效）
dsh plugin --profile desktop add "<PROJECT_ROOT>\dsh-plugin-turn-notify"

# 2) 发布到 npm 之后
dsh plugin --profile desktop add dsh-plugin-turn-notify

# 3) GitHub 仓库（打进主分支提交）
dsh plugin --profile desktop add "github:<user>/dsh-plugin-turn-notify"

# 卸载
dsh plugin --profile desktop remove dsh-plugin-turn-notify

Desktop 应用内也可以用 plugin_manager 的 install_bundle，target 传上面的 spec 或绝对目录； 它和 dsh plugin 走同一套 pnpm 实现，并负责 bundle 选择。

安装成功后检查三处：

1. $DSH_PROFILE_DIR/package.json 的 dependencies 出现该包，dsh.profile.bundles 出现 dsh-plugin-turn-notify；
2. cordis_inspect_query 按 name: dsh-plugin-turn-notify 能查到已激活的行（id 为 turn-notify）；
3. 插件行 config 的 JSON Schema 与本文「配置」一致。

必须开新会话：插件在会话创建时装载。已在运行的会话不会加载新插件，日志里也不会有 [turn-notify]。

发布到插件市场

DSH 桌面端装的「插件市场」是 dshmarket，它读的是 awesome-dsh-plugin.com/plugins.json 这份社区精选目录 （当前约 5900 条），不是 DSH 官方 @deepseek-ai/dsh-plugin-market 的 format-1 index。 所以“能在市场里搜到并一键安装”只有一条路：向 awesome-dsh-plugin/awesome-dsh-plugin 提 PR。

收录条件（逐条自查）

条件	本插件状态
package.json 声明 dsh.bundle.patch	✅ ./cordis.patch.yml
仓库根有 cordis.patch.yml，含 - insert: - id/name	✅
真实可用的代码，非占位/纯 README	✅ 2000+ 行含自检
仓库创建满 1 天（CI 自动检查）	⏳ 新建仓库需等一天
仓库加 dsh-plugin topic	需在 GitHub 设置里添加
描述准确、无营销词	见下方 YAML

提交内容

在 PR 中新增一个文件 data/plugins/laobinghongcha__dsh-plugin-turn-notify.yml：

url: https://github.com/laobinghongcha/dsh-plugin-turn-notify
name: laobinghongcha/dsh-plugin-turn-notify
category: notify
description:
  en: 'Desktop notification plus system sound when a DSH turn finishes, with distinct wording for completed, failed, blocked, and truncated turns.'
  zh: 'DSH 回合结束时弹出系统通知并播放提示音；成功、出错、受阻、截断的文案各不相同。'

含 : 的英文描述必须加引号，否则 YAML 会解析失败。category 取 notify（该目录支持的取值之一）。

在收录前先自己装上

市场收录不是安装的前提，三种方式都能立刻用：

# GitHub 直装（推荐，无需 npm）
dsh plugin --profile desktop add "github:laobinghongcha/dsh-plugin-turn-notify"

# 本地目录
dsh plugin --profile desktop add "<PROJECT_ROOT>\dsh-plugin-turn-notify"

# profile 的 cordis.patch.yml —— 改默认配置
- id: turn-notify
  name: dsh-plugin-turn-notify
  config:
    enabled: true
    sound: true
    subagents: false
    reasons: [completed, error, blocked, max-tokens]

发布到 npm（可选）

收录后市场会用 npm 或 GitHub 安装。想走 npm：

npm login
npm pack --dry-run     # 核对 files：index.js lib/ locale/ icon.svg cordis.patch.yml
npm publish

files 已排除 market/、scripts/，不会把发布脚本打进安装包。

验证

1. 离线自检：node scripts/selftest.js → 13 sections passed。

2. 真实通知链路（不依赖事件）：

   node scripts/test-turn-end.js                          # completed
   node scripts/test-turn-end.js error "自定义摘要" zh      # 失败文案 + 中文
   

   成功输出 sent through windows-toast（或 osascript / notify-send）。

3. 触发一次真实 turn/end：在装好插件的 profile 里开新会话（包被重新加载才会生效）， 发一句 你好 让 agent 跑完一个回合。回合结束时日志应出现 [turn-notify] notifying (completed): 回合完成 · <workspace> — ...，桌面弹出通知。 出错文案可以用 node scripts/test-turn-end.js max-tokens 预览。

失败处理与边界

• 通知失败只写 console（[turn-notify] notification failed via ...），不会 reject、不阻塞 agent loop； 监听器整体包在 try/catch 里，抛错也不会回到发事件的循环。
• 跨边界内容全部逐字段校验：reason.kind 必须在白名单内，turn 必须是非负整数， cwd / sessionId / 摘要都做长度截断，缺字段降级而不抛错。
• 用户/模型文本只通过子进程环境变量传给 PowerShell，从不拼进脚本；Windows 辅助脚本写在 %LOCALAPPDATA%\dsh-turn-notify（被沙箱拒绝时回落到 os.tmpdir()\dsh-turn-notify）。
• 沙箱限制：DSH 的 Windows 文件沙箱不允许 node 以管道方式捕获子进程输出 （spawn ... EPERM），因此本会话内运行测试脚本时 PowerShell 无法启动，日志会显示 notification failed via windows: ... spawn EPERM。这是测试环境的限制，不是插件缺陷： 已完成的部分是自检、脚本生成，以及把生成好的 launch.ps1 在沙箱外手动执行（返回 toast/balloon，退出码 0）。 由 DSH Host 进程直接拉起插件时不受该沙箱限制。

已知限制

• 无包身份（package identity）的进程不能使用 WinRT toast：脚本会写 HKCU\Software\Classes\AppUserModelId\DeepSeek Harness 注册项，但在某些宿主上 CreateToastNotifier 仍返回 0x80073D54，此时自动降级为托盘气泡（windows-balloon），再降级为消息框。
• Linux 依赖 notify-send（libnotify）与 canberra-gtk-play/paplay；缺失时提醒不可见但只记日志。
• macOS 首次通知需要用户在“系统设置 → 通知”里允许对应宿主应用。