前言¶
在 DSH 里跑 agent 时，一个回合往往要等模型推理、工具调用全部结束才知道结果。窗口切到别处或盯着日志刷，既费眼也容易漏掉「已经跑完」或「中途出错」的瞬间。OpenCode、Claude Code 等环境常见做法是回合结束时弹系统通知并带一声提示音；DSH 本身不内置同类提醒，需要靠 Host 端插件接上会话事件再调用各平台通知 API。
下面介绍社区插件 dsh-plugin-turn-notify（维护者 laobinghongcha）：在 DSH 回合结束时弹出系统原生通知、可选系统提示音，并按成功、出错、受阻、截断等原因使用不同文案。插件归类为客户端能力，当前 GitHub 星标为 0；许可证 MIT，版本 0.1.0（以仓库 package.json 为准）。
这是什么¶
dsh-plugin-turn-notify 是纯 Host 端 ESM 插件，零运行时依赖。它不改 agent loop，只监听会话日志里广播出来的 turn/end 事件，校验载荷后调用 Windows toast、macOS osascript 或 Linux notify-send 发通知。
DSH 没有单独的 turn/end cordis 事件名；turn/end 由 agent loop 写入会话（session.append('turn/end', { turn, reason })），每个持久化会话事件会以 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 作用域回收，任意会话的回合结束都能收到。
核心功能¶
可配置的触发条件¶
默认在 completed、error、blocked、max-tokens 四种 reason.kind 下提醒；还可选 aborted、interrupted、forked。未列入 reasons 的原因不会弹窗。同一会话可用 debounceMs（默认 800ms）去重；minDurationMs 可过滤过短的回合。
通知内容与声音¶
标题形如「回合完成 · default-workspace」（原因标题 + 工作区目录名，缺失时用 session 短 id）。正文可含耗时（来自同回合最新 turn/start 的 time）以及最后一段 assistant 文本摘要（includeSummary、summaryLength 默认 80 字符）。
成功类原因用 done 系提示音（如 Windows Asterisk、macOS Glass）；失败类用 alert 系（如 Hand、Basso）。subagents: false（默认）时忽略子代理会话，只提醒主会话；设为 true 时子代理回合不单独弹窗，主回合通知尾注 (subagent <label>)。
失败不拖垮主流程¶
通知失败只写 console（[turn-notify] notification failed via ...），不 reject、不阻塞 agent loop；监听器包在 try/catch 内。跨边界字段逐项校验，缺字段降级而不抛错。
安装与启用¶
dsh plugin 会把 pnpm 转发到 profile 目录并登记 bundle；仅用 pnpm add 不会登记插件行。
# GitHub 仓库（打进主分支提交）
dsh plugin --profile desktop add "github:laobinghongcha/dsh-plugin-turn-notify"
# 发布到 npm 之后
dsh plugin --profile desktop add dsh-plugin-turn-notify
# 本地目录（开发调试，链接安装）
dsh plugin --profile desktop add "<PROJECT_ROOT>\dsh-plugin-turn-notify"
# 卸载
dsh plugin --profile desktop remove dsh-plugin-turn-notify
Desktop 应用内也可通过 plugin_manager 的 install_bundle，target 传上述 spec 或绝对路径，与 CLI 走同一套实现。
安装成功后建议核对三处：$DSH_PROFILE_DIR/package.json 的 dependencies 与 dsh.profile.bundles；cordis_inspect_query 能查到 name: dsh-plugin-turn-notify（id 为 turn-notify）；插件 config 的 JSON Schema 与文档一致。
必须开新会话：插件在会话创建时装载；已在运行的会话不会加载新插件，日志里也不会出现 [turn-notify]。
覆盖默认配置¶
bundle 层 cordis.patch.yml 只负责 insert 插件行。改默认值请在 $DSH_PROFILE_DIR/cordis.patch.yml 用相同 id 覆盖整行 config（匹配覆盖会替换整个 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
minDurationMs: 0
includeSummary: true
summaryLength: 80
典型用法与验证¶
离线自检与模拟通知¶
在插件仓库根目录：
node scripts/selftest.js
预期输出 13 sections passed。不依赖真实 turn/end 事件时，可手动走通知后端：
node scripts/test-turn-end.js # completed
node scripts/test-turn-end.js error "自定义摘要" zh # 失败文案 + 中文
成功时控制台会标明 sent through windows-toast（或 osascript / notify-send）。
真实回合¶
在已安装插件的 profile 里新开会话，发一句简单指令让 agent 跑完一个回合。回合结束时日志应出现 [turn-notify] notifying (completed): 回合完成 · <workspace> — ...，桌面同时弹出通知。可用 node scripts/test-turn-end.js max-tokens 预览截断类文案。
适用场景与注意¶
适合长期在 DSH Desktop 或多会话下调 agent、需要「离开窗口也能知道回合结束」的开发者。插件以当前 DSH Host 进程权限运行，安装前应自行查看 源码 与 MIT 许可证，确认通知内容与子进程调用方式符合你的环境策略。
平台差异与限制（摘自 README）：
- Windows：无包身份时 WinRT toast 可能失败，会降级托盘气泡或消息框；DSH Windows 文件沙箱下在本会话内跑测试脚本可能出现
spawn EPERM，由 Host 直接加载插件时通常不受此限。 - Linux：依赖
notify-send与canberra-gtk-play/paplay；缺失时可能只记日志。 - macOS：首次通知需在系统设置里允许对应宿主应用。
社区插件目录站 skillhub.cn 与 awesome-dsh-plugin 收录体系独立于 DeepSeek 官方插件市场索引；「市场里一键安装」需向 awesome-dsh-plugin 提 PR，与本地 dsh plugin add 无先后依赖。
结尾¶
dsh-plugin-turn-notify 把 DSH 会话里的 turn/end 事件转成桌面通知和可选提示音，并按回合结果区分文案与声音，配置集中在 profile 的 cordis.patch.yml。需要进一步了解实现细节或提 issue，见 GitHub 仓库：https://github.com/laobinghongcha/dsh-plugin-turn-notify；插件目录页：https://www.skillhub.cn/plugins/laobinghongcha/dsh-plugin-turn-notify。
