前言¶

DSH 的核心理念是「一切皆插件」。在实际使用中，智能体会话经常需要等待用户操作，例如等待权限批准、回答问题或确认 Plan 方案。如果此时应用窗口被最小化或切换到了其他任务，用户往往无法及时感知到这些待处理事项。

@camusugar/dsh-notify 插件通过监听会话状态和窗口焦点变化，在应用窗口失焦时触发操作系统级的通知（Windows Toast / macOS 通知中心），从而解决这一问题。

插件简介¶

• 名称：@camusugar/dsh-notify
• 定位：DSH 用户级插件，用于在会话等待用户操作且应用窗口失焦时弹窗。
• 维护者：Camusugar
• 许可证：MIT

核心功能¶

该插件不修改 DSH 本体，完全通过插件机制实现，具体特性如下：

1. 纯事件驱动：通过订阅 uiSession.sessionStatus 和监听 DOM 事件（visibilitychange / blur / focus）来触发通知，没有任何定时器或轮询机制。
2. 零侵入安装：随 profile 安装，不改动 DSH 核心代码，应用升级后配置保留。
3. 容错设计：如果 uiSession 服务缺失或发生错误，插件会静默禁用，不会向系统抛出异常或导致应用崩溃。
4. 去重与限制：按 key 对通知进行去重，单个会话最多显示 16 条通知，超出部分会静默抑制。
5. 多会话并发：支持同时处理多个会话。每个会话有独立的状态快照和通知，不同会话的 key（如 approval:N / question:N）通过全局递增计数器保证跨会话唯一。各会话的通知独立弹出和关闭。
6. 自动语言切换：根据 navigator.language 自动选择中文或英文文案。

安装与启用¶

使用官方安装命令即可添加该插件：

dsh plugin add https://github.com/Camusugar/dsh-notify

插件安装后会自动加载，无需额外配置。

典型用法¶

当满足以下条件时，插件会自动触发系统通知：
* 会话处于等待权限批准状态。
* 会话处于等待用户回答问题（ask_user_question）的状态。
* Plan 模式下处于方案确认阶段。
* 应用窗口最小化、切换到别的窗口或失焦。

技术细节与注意事项¶

• 通知机制：使用标准 Web Notification API，理论上支持跨平台。
• 依赖要求：需要注入依赖 @deepseek-ai/dsh-client-ui-session。
• macOS 限制：macOS 平台要求应用必须为签名构建，否则通知中心可能无法正常工作。
• 卸载方式：
  1. 退出应用。
  2. 编辑配置文件（Windows 路径：C:\Users\<用户名>\.dsh\profiles\desktop\package.json）：从 dsh.profile.bundles 和 dependencies 中删除 @camusugar/dsh-notify。
  3. （可选）删除同目录下的 node_modules\@camusugar。
  4. 重启应用。

故障恢复¶

如果插件导致应用启动失败，可使用内置恢复功能：
1. 启动失败时，在错误对话框中选择「禁用全部插件并重启」。
2. 应用会将 cordis.patch.yml 备份为 cordis.patch.yml.bak-<时间戳>，并将 dsh.profile.bundles 重置为默认值。
3. 重启后可重新安装本插件。

如果需要手动恢复自定义配置，请按照上述卸载步骤操作。

总结¶

该插件通过轻量级的事件监听和系统通知机制，提升了 DSH 在多任务处理时的可用性。适合需要频繁处理多个会话或长时间运行 Agent 任务的用户。源码与文档见：GitHub。