dsh-notice-center

dsh plugin --profile web add dsh-notice-center

dsh-notice-center 🔔🐋

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



<img src="docs/images/banner.jpg" alt="dsh-notice-center 会话通知 —— 让每一条消息，都不错过" width="100%">

一句话：DeepSeek Harness 的通知中心——把标签页上的鲸鱼图标变成状态灯，并在你不在看的时候主动提醒你。

包名 · dsh-notice-center

插件实例 id · notice-center

设置命名空间 · notice-center

安装形态 · npm 包 / GitHub 仓库 / tarball / 本地 link，四种都支持

目录

使用

• [为什么需要它](#为什么需要它)
• [功能特性](#功能特性)
• [安装](#安装)
• [上手三步](#上手三步)
• [设置项详解](#设置项详解)
• [常见问题](#常见问题)
• [已知限制](#已知限制)

开发

• [架构总览](#架构总览)
• [目录结构](#目录结构)
• [一条通知的生命周期](#一条通知的生命周期)
• [本地开发](#本地开发)
• [测试](#测试)
• [发版](#发版)
• [更新记录](./CHANGELOG.md)
• [设计约束](#设计约束)

为什么需要它

在 Harness 里，「会话跑完了」和「有事等你拍板」这两个信号，只出现在侧边栏的小圆点和会话本身上。你一旦切到别的标签页、别的应用，就看不见了。

长任务尤其难受：你去干别的，回来才发现早就跑完；或者一个审批请求已经晾了十分钟。

这个插件把这两个信号搬到你能看到的地方：

你不在 DSH 页面时 · 你会看到

会话跑完了 · 标签页鲸鱼变绿，并弹出系统通知（单独一条时附本轮总用时）

有事等你处理 · 标签页鲸鱼变琥珀，并弹出系统通知（写明是审批 / 提问 / 计划审核）

功能特性

1. 鲸鱼状态灯

三种颜色直接编码在标签页图标上，和侧边栏的绿点、琥珀点用的是同一份官方信号，永远同步：

鲸鱼颜色 · 含义 · 什么时候恢复

<img src="docs/images/whale-green.svg" width="20" alt="绿色"> 绿色 · 有会话在你没看它的时候跑完了 · 该会话点开后自动恢复；全部点开过一遍即回到默认状态

<img src="docs/images/whale-amber.svg" width="20" alt="琥珀色"> 琥珀色 · 有会话有事等你处理：提问 / 审批 / 计划审核 · 处理完后自动消失

<img src="docs/images/whale-black.svg" width="20" alt="黑色"> 黑色 · 一切正常（官方原版图标） · 默认状态

• 只统计主会话，子代理不计入
• 绿色与琥珀同时存在时琥珀优先——待处理是首要状态，有会话卡住等你时，不会因为别的会话刚跑完而被掩盖
• 三种颜色都能改（含「默认色」：不配置就沿用官方原版图标）

2. 系统通知

两种事件会触发通知，默认只在你不在看的时候弹：

事件 · 触发时机 · 通知长什么样

完成通知 · 会话跑完 · 标题＝会话名；正文＝会话已完成，单独一条时附本轮总用时（如 会话已完成 · 本轮总用时 2分13秒）

待处理通知 · 出现新的待处理交互 · 标题＝会话名；正文＝交互类型：待审批 · <工具名> / 请你选择（多选则 请你多选、无选项则 请你填写、多问题则 向你提问（N 个））/ 计划待审核；认不出的类型回退为 有交互等待处理

完成通知（绿） · 待处理通知（琥珀）

 · 

通知由浏览器发出（本机是 Chrome），所以卡片上显示浏览器与站点 127.0.0.1:3080——这是正常的。

其余行为：

• 点击通知 = 聚焦窗口并打开对应会话
• 只在你不看的时候弹——「前台」＝标签页可见且窗口有焦点；切到别的标签页、最小化、被别的应用压在后面时都会提醒。想在前台也提醒（人还停在会话里、却已离开屏幕，例如在刷手机），打开设置里的「前台提醒」
• 多条聚合：300ms 内的事件合并为一条，标题补 +N
• 可常驻：关掉「自动隐藏」后，通知会一直留在屏幕上，直到你点掉它
• 通知图标跟随你配置的状态灯颜色

3. 提示音

完成与待处理各有独立下拉，共 47 个条目：2 个插件内置合成音 + 45 个取自 opencode 内置音效库的 mp3。

音效包 · 条目

内置（合成音） · Chime Up（完成默认，上行双音）、Chime Down（待处理默认，下行双音）

Alert · Alert 01–10

Bip-bop · Bip-bop 01–10

Staplebops · Staplebops 01–07

Nope · Nope 01–12

Yup · Yup 01–06

• 悬浮即试听：鼠标划过下拉条目就播该音效（120ms 防抖，扫过整列不会连成一片）
• 调完音量即试听：拖动音量条松手后，会按新音量播一次完成提示音
• 开启提示音后，系统默认提示音会被静音，改播插件音效
• 宿主半通过 /notice-center-sounds/<id>.mp3 提供音频；路由不可用时自动回退内置合成音，不会变哑
• 老配置无需迁移：没配过音效时仍用 Chime Up / Chime Down

安装

前置要求

• 官方版本的 DeepSeek Harness：1.4.0 起要求 0.1.7-rc.2+；1.3.x 支持 0.1.2-rc.1+
• 兼容范围写在 engines.dsh 与 @deepseek-ai/dsh-* peer 上，由 test/compat-range.smoke.mjs 守护。两条线按宿主版本自动分流：插件市场不会把 1.4.0 推给旧宿主，DSH 核心在加载前也会拒绝它——旧宿主原地留在 1.3.x，不会收到更新提示。
• 版本闸门只比版本号，查不出 API 被删（0.1.7 删掉了 settings.register，旧声明在那上面照样 PASS），所以别只靠它当兼容性保障。
• 系统通知需要安全上下文——http://127.0.0.1:3080 或 localhost 可用；用局域网 IP 访问时浏览器的 Notification API 不可用（这是浏览器限制，不是插件问题）

方式一：从 npm 安装（推荐）

dsh plugin --profile web add dsh-notice-center

包页：<https://www.npmjs.com/package/dsh-notice-center>（latest 为稳定版，预发布版在 next 通道，用 dsh-notice-center@next 装）

方式二：直接从 GitHub 安装

dsh plugin --profile web add github:SCP-QQ/dsh-notice-center
# 或走 SSH（本机 HTTPS 受代理影响时）
dsh plugin --profile web add git+ssh://git@github.com/SCP-QQ/dsh-notice-center.git

方式三：从 tarball 安装（离线 / 内网分发）

npm pack                                        # 生成 dsh-notice-center-<版本>.tgz
dsh plugin --profile web add ./dsh-notice-center-<版本>.tgz

方式四：本地 link（改代码时用）

在 profile 的 package.json 里：dependencies 加 "dsh-notice-center": "link:<项目目录>"，dsh.profile.bundles 加 "dsh-notice-center"，然后在 profile 目录跑 pnpm install。

四种方式装完都要重启 Harness 才生效。

从 npm / GitHub 安装时不需要额外提供任何 @deepseek-ai/* 包——宿主半的运行时依赖只有 @deepseek-ai/schemastery（npm 上有）。

卸载

dsh plugin --profile web remove dsh-notice-center

移除依赖与 dsh.profile.bundles 条目后重启，即无残留。

上手三步

1. 打开设置页 —— 设置 → 通知中心（侧栏导航项）

2. 授权系统通知 —— 总开关默认就是开的：打开页面后，你第一次点击或按键时，插件会自动向浏览器请求一次通知授权（浏览器不允许没有用户手势的请求，页面自己弹不出来，所以只能借你的一次交互），选「允许」，同时会收到一条「通知已开启」的确认。频率规则：

• 每次打开页面最多问一次（同一次会话里点多少下都只问一次，不会连环弹）；
• 你在授权窗上选了「允许」或「阻止」→ 不会再问（权限有定论了）；
• 你只是点了 × / Esc（既没允许也没阻止）→ 不算做出选择，下次刷新页面会再问一次，直到你选为止；
• 想彻底不被打扰：把「系统通知」开关关掉，或在授权窗里选「阻止」。

之后想补授权，用开关正下方那枚状态 chip（短状态常驻、鼠标悬浮或键盘聚焦问号/叹号看完整说明）：

状态 · chip 长什么样 · 怎么办

未授权（自动请求被你关掉了，或从没问过） · 「未授权 · 授权」可点 · 点它，浏览器会重新弹授权窗

已被拒绝 · 叹号 +「已被拒绝」 · 浏览器不会二次弹窗（网页也无权打开站点设置页）：悬浮看恢复路径 —— 点地址栏左侧的图标 → 通知 → 允许，或打开 chrome://settings/content/notifications

当前浏览器不支持 · 一行小字 · 多半是安全上下文问题（见「安装 → 前置要求」），用 http://127.0.0.1:3080 访问即可

已授权 · 不显示（行保持干净） · —

开关本身始终可切（未授权时也能把通知关掉，关掉后就不会再自动请求）；你在站点设置里改完权限回到页面，chip 会立刻跟上。

3. 按需微调 —— 展开两个分组：调颜色、选音效、调音量、开关「前台提醒」/「自动隐藏」

<img src="docs/images/settings.png" width="440" alt="通知中心设置页">

之后你切走或最小化时，会话跑完 / 有事等你都会收到通知，点通知直接跳回那个会话。

设置项详解

分组 · 设置项 · 配置键 · 默认值 · 说明

鲸鱼状态灯 · 总开关 · colorsEnabled · 开 · 关闭后保持官方原版图标

· 完成 · green · #22C55E · 完成状态灯颜色（官方侧边栏色）

· 待处理 · amber · #F59E0B · 待处理状态灯颜色（官方侧边栏色）

· 默认色 · black · 未设置 · 不设置＝沿用官方原版 /favicon.svg

系统通知 · 总开关 · notifyEnabled · 开 · 默认开启；首次交互自动请求浏览器授权，未授权时开关下方给状态 chip

· 自动隐藏 · notifyAutoHide · 开 · 关＝通知常驻屏幕，需手动关闭

· 前台提醒 · `notify

…(truncated)