dsh-notify-tray

小鲸鱼通知站 · 使用说明

简体中文 | [English](README.en.md)

任务完成、失败或需要你处理时收到通知；在 macOS / Linux 状态栏查看任务进度、今日花费和套餐额度。

从这里开始

1. 安装并启用插件后，在 DSH 左侧栏点击「小鲸鱼通知站」（鲸鱼图标）。侧栏收起时，点图标也能打开设置。

2. 在「提醒我」中选择需要的通知类型，按需开启提示音。

3. macOS / Linux 用户可以开启「显示小鲸鱼」；macOS 还可选择鲸鱼旁边显示文字、数字或只显示图标。

4. 修改后会自动保存，连续输入停止约半秒后提交。保存成功时会出现「设置已保存」小横幅，无需点击保存按钮。

保存失败会保留修改，并显示「重试保存」。输入无效时请先修正；离开设置页不会丢弃尚在排队的修改。

「插件 → 小鲸鱼通知站」详情页只显示这份使用说明。通知、状态栏、花费和套餐的设置统一放在左侧栏入口里。

从旧版更新后，原有设置和花费记录会继续使用，无需重新填写。若没看到新入口，先重启 DSH；如果侧栏把入口收进了「更多」，可在那里找到并固定它。

通知怎么用

默认开启五类通知：做完了、翻车了、要我批准、要我选、要我写字。点击 DSH 窗口发出的通知，会打开对应会话。

• 你正在查看的会话默认不弹通知；切到别的应用后会正常提醒。需要始终提醒时，在「高级设置」关闭「正看着这个会话时不弹」。
• 同一个会话只保留一条通知；问题回答或批准完成后，「需要你」的通知会收回（系统通道是否支持取决于平台）。
• 多个任务在几秒内接连完成时，后续完成通知会合并。
• 手动停止任务不发完成或失败通知；子智能体不单独提醒。

「高级设置 → 通知从哪里弹」默认为自动：有具备通知权限的 DSH 窗口时由窗口弹，否则使用系统通知。通常保持默认即可。

状态栏小鲸鱼

| 样子 | 含义 |

|---|---|

| 安静待着 | 空闲 |

| 冒泡泡 | 有任务运行中 |

| 冒出 ! | 等你批准、选择或输入 |

| 冒出 × | 刚有任务失败，默认保持 10 分钟 |

点击状态栏鲸鱼，菜单里可查看运行中的任务、待处理事项、最近结束的任务、今日用量和套餐额度。点击任务可打开对应会话。

| 系统 | 本插件提供的功能 |

|---|---|

| macOS | 系统通知、菜单栏鲸鱼、鲸鱼旁的进度文字与可选花费 |

| Linux（UOS / Deepin / 麒麟 / KDE 等） | 系统通知、系统托盘鲸鱼，以颜色区分状态 |

| Windows | 系统通知；本插件不提供 Windows 托盘图标，设置页也不显示托盘选项 |

若从鲸鱼菜单隐藏了图标，可在左侧栏设置页点击「重新显示状态栏图标」，无需重启。GNOME 通常需要 AppIndicator 扩展才能显示托盘图标。

花费与套餐

设置页的「花费与套餐」可查看今日花费、当前模型和 API 单价。

• 花费：默认优先使用 DeepSeek 账户余额变化；余额更新有延迟时先显示估算，其他平台按 Token 用量与单价估算。此数字用于参考，实际账单以服务商为准。
• 价格：优先使用你填写的价格，其次使用 DSH 模型目录、插件内置价格或随插件发布的 models.dev 快照。自定义单价与汇率在「高级设置」里调整。
• 套餐：选择平台和套餐后，会填入预设信息；可以展开「手动改套餐信息」修改名称、价格、周期、余额和额度。
• 自动查额度：在「API Key 引用」填写 DSH「模型」页保存密钥时使用的名字，或环境变量名，点击「刷新」时会先保存当前设置，再查询额度。这里填的是引用名，不是密钥本身。没有额度接口的平台可手填，也可以留空。
• 查询失败：页面会显示失败原因及尝试过的密钥来源。检查引用名、密钥权限和所选平台后再刷新。

套餐预设和价格快照可能落后于服务商调整，都可以手动覆盖。套餐订阅价格不等于 API Token 花费，两者分别显示。

常见问题

没有收到通知？

先确认对应通知类型已开启且出现「设置已保存」，再检查系统是否允许 DeepSeek Harness 通知、是否开启勿扰模式。浏览器使用 DSH 时，需要允许网站通知权限。默认查看当前会话时不会弹通知。

点击通知没有跳到会话？

保持「通知从哪里弹」为「自动」，并让 DSH 窗口运行。macOS 的系统备用通知使用 osascript 时不能定位会话；安装 [terminal-notifier](https://github.com/julienXX/terminal-notifier) 后可支持跳转和撤回。Windows 系统备用通知受系统前台窗口限制，已最小化的窗口可恢复。

为什么 Windows 没有鲸鱼图标设置？

本插件在 Windows 上仅实现通知，状态栏功能仅用于 macOS / Linux；DSH 左侧栏的设置入口在三个平台都会显示。

花费或额度不准确？

检查当前模型的价格来源、显示币种、汇率，以及是否填写了覆盖自动查询的手动剩余额度。自动查询只在服务商提供可用接口且密钥具备权限时有效。

记录保存在什么地方？

花费账本默认位于 ~/.dsh/storages/dsh-notify-tray/ledger.json，保留 31 天；配置了 DSH_HOME 时使用该目录。设置由 DSH 的当前 profile 管理。

安装与更新

在 DSH「插件 → 添加插件」输入 dsh-notify-tray 安装。需要指定已发布版本时，输入 dsh-notify-tray@版本号，可在 [npm](https://www.npmjs.com/package/dsh-notify-tray) 查看已发布版本。

在线更新

侧栏设置页底部提供「版本更新」卡片：

• 打开设置页时自动检查，也可以点击「检查更新」。
• 发现兼容且未废弃的正式版时，显示新版本号和「立即更新」。点击后先保存设置，再交给 DSH 原生插件管理器更新。
• 安装不会自动开始；DSH 负责版本兼容性检查和失败时的恢复。页面会区分更新完成、需要重启、恢复旧版和结果尚未确认。
• 本地目录、Git 等非 npm 安装不支持这条在线更新流程，会显示原因。需等正式版发布到 npm 后，通过插件管理页改为 npm 安装。

也可以继续使用 DSH 插件管理页的原生更新功能。提示需要重启时，请重启 DSH。

开发或试用尚未发布的代码，可从本地仓库安装：

dsh plugin --profile desktop add /absolute/path/to/dsh-notify-tray

Web 用户将 desktop 换成 web。安装后重启对应 DSH 实例。

遇到问题可在 [GitHub Issues](https://github.com/ROYLeXJ/dsh-notify-tray/issues) 提交，附上 DSH 版本、插件版本、系统和复现步骤。