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 选择。
安装成功后检查三处：
$DSH_PROFILE_DIR/package.json 的 dependencies 出现该包，dsh.profile.bundles 出现 dsh-plugin-turn-notify；cordis_inspect_query 按 name: dsh-plugin-turn-notify 能查到已激活的行（id 为 turn-notify）；- 插件行 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/，不会把发布脚本打进安装包。
验证
-
离线自检：node scripts/selftest.js → 13 sections passed。
-
真实通知链路（不依赖事件）：
node scripts/test-turn-end.js # completed
node scripts/test-turn-end.js error "自定义摘要" zh # 失败文案 + 中文
成功输出 sent through windows-toast（或 osascript / notify-send）。
-
触发一次真实 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 首次通知需要用户在“系统设置 → 通知”里允许对应宿主应用。
