dsh-completion-reminder 1.0.0 → 1.1.0

package/README.md

@@ -3,8 +3,15 @@
 为 DeepSeek Harness (DSH) Web GUI 增加 **Agent 完成提醒** 功能的插件。
 当 agent 停止生成（成功 / 主动停止 / 出错）时，弹一个通知给用户。
 
-默认走 **浏览器原生通知**（`window.Notification`，首次使用需要用户授权），
-并内置 **七种热门的第三方通知渠道** 供切换：
+- 🌐 默认走 **浏览器原生通知**（`window.Notification`，首次使用需要用户授权）
+- ⚙️ 右下角悬浮一个 **🔔 按钮**，点开是带 9 种通知渠道的图形化配置面板
+- 💾 配置保存在本浏览器 `localStorage`，不会上传任何服务器
+- 🧪 配置面板自带 **「发送测试通知」** 按钮，方便验证渠道是否通
+- 🪟 标签页可见时默认静默（不打断工作），可通过开关关闭
+- ⏱ 内置 5 秒冷却，避免连续 agent 完成时刷屏
+- 🎨 标题/正文可定制，匹配 `success` / `stopped` / `error` 三种状态
+
+## 9 种通知渠道
 
 | 渠道 | 适用人群 | 配置字段 |
 |------|----------|----------|
@@ -18,17 +25,20 @@
 | 🔗 **Webhook** | 自建服务 | `webhookUrl` |
 | 🛠 **Custom** | 完全自定义 | `customSend(payload)` |
 
-## 功能
+## 工作原理（v1.1）
+
+DSH 的 composer 卡片 `<div data-composer-card="true">` 内的主按钮 `aria-label` 会在
+`"Stop generating"` / `"Send message"`（中文 UI 下是 `"停止生成"` / `"发送消息"`）之间切换。
+插件用一个轻量 `MutationObserver` 监听这个属性变化：
 
-- 🛰 **完成即通知**：检测 DSH 输入工具栏的 send ↔ stop 按钮切换，并结合最后一条消息判断成功 / 主动停止 / 出错
-- 🔔 **浏览器原生通知**：`Notification` API，首次自动请求权限；未授权时回退为页面内 toast
-- 🌍 **七种第三方渠道**：Telegram、Bark、Pushover、Server酱、Discord、Slack、通用 Webhook，外加 Custom 钩子
-- 🪟 **智能抑制**：标签页可见且获得焦点时默认不响（避免打断），可通过 `suppressWhenFocused: false` 关闭
-- ⏱ **防刷屏**：连续完成之间默认 5 秒冷却，可调
-- 🎨 **标题/正文可定制**：`titleTemplate` / `bodyTemplate` 接收上下文返回字符串
-- 🪪 **可观测性**：`onNotify` / `onError` 钩子方便调试与对接
-- ⚡ **装了即用**：声明 `dsh.bundle.patch`，`dsh plugin add` 时由 DSH 自动加入 profile 层并激活
-- 📦 **npm 分发**：CI 自动构建、发布、创建 GitHub Release
+- 检测到 `Stop generating` → 记录开始时间
+- 检测到 `Send message` → 触发完成事件
+- 根据 `data-phase` (`active` / `settling` / `hero`) 和最后一条 `data-role="assistant"`
+  消息的文本/类名，判断 `success` / `stopped` / `error`
+- 派发到当前渠道，调用 `Notification` / `fetch` 发送
+
+所有匹配都用 **稳定属性**（`data-*`、`aria-label`、`type`），不依赖会被 CSS-modules
+哈希改变的 class 名（`uV2eYG_primary` 这类），跨 DSH 版本更稳。
 
 ## 快速开始
 
@@ -53,86 +63,45 @@ dsh plugin --profile web add -w dsh-completion-reminder
 dsh web
 ```
 
-打开任一会话并触发一次 agent 回复，应该会看到「请求通知权限」的浏览器弹窗。
-授权后，等任务结束即可看到通知。
+打开任一会话，右下角应该出现一个 **🔔** 浮动按钮。点击它打开设置面板：
+
+1. 选择通知渠道（如 `Telegram`）
+2. 填入对应的 token / id（一次即可，存到 `localStorage`）
+3. 点击 **「发送测试通知」** 验证渠道通不通
+4. 等一次 agent 完成，会自动收到通知 🎉
 
-## 配置
+## 程序化 API
 
 ```javascript
 DSHCompletionReminder.configure({
-  provider: 'telegram',                  // 'browser' (default) | 'telegram' | 'bark' | 'pushover'
-                                         //   | 'serverchan' | 'discord' | 'slack'
-                                         //   | 'webhook' | 'custom'
-  autoRequestPermission: true,           // 浏览器模式下自动请求 Notification 权限
-  notifyOnSuccess: true,                 // 成功完成时通知
-  notifyOnStopped: true,                 // 用户主动停止时通知
-  notifyOnError:   true,                 // agent 出错时通知
-  suppressWhenFocused: true,             // 标签页可见且有焦点时不响
-  cooldownMs: 5000,                      // 连续通知之间的最小间隔
-  titleTemplate: ({ status }) => 'DSH 已结束', // 自定义标题
-  bodyTemplate:  ({ model, durationMs }) => `${model} · 用时 ${durationMs}ms`,
-  iconUrl: '/favicon.ico',
-  clickUrl: location.href,
-
+  provider: 'telegram',
   providers: {
     telegramBotToken: '123456:ABC...',
     telegramChatId:   '987654321',
-
-    // barkKey / pushover* / serverchanSendKey / discordWebhookUrl /
-    // slackWebhookUrl / webhookUrl 只需按当前 provider 填写。
   },
-
+  suppressWhenFocused: false,
+  cooldownMs: 3000,
   onNotify: (payload, provider) => console.log('delivered via', provider, payload),
   onError:  (err, provider)      => console.warn('failed via', provider, err),
 });
 
 DSHCompletionReminder.activate();
 DSHCompletionReminder.deactivate();
-```
-
-### 只走「页面内 toast」？
-
-把 `provider` 设为 `'browser'` 即可。如果用户拒绝浏览器通知权限，插件会自动
-回退为页面内的浮动提示，不需要任何额外配置。
-
-### 切换到 Telegram？
-
-1. 在 Telegram 中 `@BotFather` 创建 bot，拿到 `telegramBotToken`
-2. 给自己发一条消息，访问 `https://api.telegram.org/bot<TOKEN>/getUpdates` 拿到 `chat.id`
-3. 配置：
-
-```javascript
-DSHCompletionReminder.configure({
-  provider: 'telegram',
-  providers: {
-    telegramBotToken: '<TOKEN>',
-    telegramChatId:   '<CHAT_ID>',
-  },
-});
-```
-
-## 公开 API
-
-```javascript
-DSHCompletionReminder.DEFAULTS                    // 默认配置
-DSHCompletionReminder.configure(opts)              // 合并配置（多次调用累加）
-DSHCompletionReminder.activate()                   // 启动 DOM 观察与通知
-DSHCompletionReminder.deactivate()                 // 停止一切
-DSHCompletionReminder.requestBrowserPermission()   // 手动触发 Notification 权限请求
+DSHCompletionReminder.requestBrowserPermission();
 ```
 
 `apply(ctx, opts)` 是 DSH Cordis Loader 调用的入口，等价于 `configure(opts); activate()`。
 
-## 工作原理
+## 公开 API
 
-- `src/index.ts` 是宿主侧（node）入口，导出空 `apply`，让 Loader 能挂载本包
-- `src/client.ts` 是浏览器侧真正的逻辑，被打包成 `window.__ModuleLoader__.load({ factory })` 格式
-- 一个 `MutationObserver` 监听 `document.body`：
-  - 关注工具栏按钮的 `aria-label` / `class` / `textContent` 变化
-  - 检测到「running」（如 `停止` / `Stop`）→ 记录开始时间
-  - 检测到「idle」→ 触发 `completeRun(status, durationMs)`
-  - 读最后一条 `data-role="assistant"` 消息粗略判断 success / stopped / error
-- 根据 `provider` 派发到不同的通知渠道，全部走 `fetch` / `Notification`
+| 方法 / 属性 | 说明 |
+|------|------|
+| `DSHCompletionReminder.configure(opts)` | 合并配置（与 localStorage 持久值叠加） |
+| `DSHCompletionReminder.activate()` | 启动 DOM 观察 + 注入浮动按钮 |
+| `DSHCompletionReminder.deactivate()` | 停止一切，移除 UI |
+| `DSHCompletionReminder.requestBrowserPermission()` | 手动触发浏览器通知权限请求 |
+| `DSHCompletionReminder.apply(ctx, opts)` | DSH Cordis Loader 入口 |
+| `DSHCompletionReminder.DEFAULTS` | 默认配置（只读） |
 
 ## 项目结构
 
@@ -143,7 +112,7 @@ dsh-completion-reminder/
 ├── tsconfig.json             # TypeScript 配置
 ├── src/
 │   ├── index.ts              # 服务端入口（桩）
-│   ├── client.ts             # 客户端插件 TypeScript 源码
+│   ├── client.ts             # 客户端插件 TypeScript 源码（DOM 检测 + 9 渠道 + 设置面板）
 │   └── types.ts              # 类型定义 & 默认值
 ├── lib/
 │   ├── index.js              # 编译后的服务端入口（纯载体）
@@ -153,9 +122,9 @@ dsh-completion-reminder/
 ├── scripts/
 │   ├── build-plugin.js       # 构建脚本（tsc 产物 → ModuleLoader 包装）
 │   └── clean.js              # 清理 lib/ 和 dist/
-├── .github/workflows/
-│   └── publish.yml           # tag 推送 → 构建 → npm 发布 → GitHub Release
-└── test.html                 # 测试页面（模拟 send ↔ stop 切换）
+├── probes/                   # 离线 smoke test（jsdom，模拟 DSH DOM）
+└── .github/workflows/
+    └── publish.yml           # tag 推送 → 构建 → npm 发布 → GitHub Release
 ```
 
 ## 发布流程
@@ -168,6 +137,15 @@ git push origin main --tags
 推送 `v*` tag 后 CI 自动完成构建、npm 发布和 GitHub Release。
 `NPM_TOKEN` 与 `GITHUB_TOKEN` 在仓库 Settings → Secrets 中配置。
 
+## 版本历史
+
+- **v1.1.0** — 真正的 v1：
+  - 改用真实 DSH DOM 锚点（`data-composer-card` + `aria-label`），不再依赖会被哈希的 class 名
+  - 新增右下角浮动 **🔔** 按钮 + 完整设置面板（9 渠道、11 凭证字段、4 个行为开关、测试按钮）
+  - 配置持久化到 `localStorage`
+  - jsdom 离线 smoke test 验证 3 种状态（success / stopped / error）+ 9 渠道派发
+- **v1.0.0** — 初始版本（class 名匹配，实际 DSH 上不可用）
+
 ## 许可
 
 MIT

package/dist/dsh-completion-reminder.js

@@ -29,6 +29,7 @@
     providers: {},
     clickUrl: '',
     iconUrl: '',
+    showSettingsPanel: true,
     onNotify: function () { return undefined; },
     onError: function (err) { try { console.warn('[dsh-completion-reminder]', err); } catch (_e) {} },
     titleTemplate: function (ctx) {

package/install.md

@@ -26,63 +26,53 @@ dsh plugin --profile web add dsh-completion-reminder
 dsh web
 ```
 
-启动后，浏览器地址栏左侧应该会出现「🔔 想显示通知吗？」的权限询问。
-点击「允许」即可启用浏览器原生通知。
+启动后，DSH 右下角会出现一个 **🔔** 浮动按钮。点击它打开设置面板。
 
-### 升级
+## 配置通知渠道
 
-```bash
-dsh plugin --profile web update dsh-completion-reminder
-dsh web   # 重启生效
-```
+打开设置面板：
 
-## 验证安装
+1. **选择通知渠道**（默认 `🌐 浏览器通知`）
+2. **填入对应凭证**（如 Telegram Bot Token / Chat ID）
+3. 调整 **行为选项**（成功 / 停止 / 出错 是否通知、是否在标签页可见时静默、冷却时长）
+4. 点击 **「发送测试通知」** 验证渠道
+5. 关闭面板 → 自动保存到 localStorage
 
-1. 打开或强制刷新 DSH Web GUI（http://127.0.0.1:3080，Ctrl+Shift+R）
-2. 给 agent 发任意一条消息
-3. 等任务结束 → 系统右下角（或顶部）出现通知：「✅ DSH Agent 已完成 · 用时 Xs」
+如果使用浏览器原生通知，第一次会弹权限询问；如果拒绝，插件会自动改用页面内浮动 toast，**不会**完全失效。
 
-如果浏览器拒绝了通知权限，插件会自动改用页面内浮动 toast，**不会**完全失效。
+## 切换渠道示例
 
-## 切换到第三方通知
+### Telegram
 
-在 DSH 页面打开 DevTools 控制台，运行：
+1. 在 Telegram 中 `@BotFather` 创建 bot，拿到 `telegramBotToken`
+2. 给自己发一条消息，访问 `https://api.telegram.org/bot<TOKEN>/getUpdates` 拿到 `chat.id`
+3. 在设置面板选 `Telegram` 并填入两项凭证
 
-```javascript
-DSHCompletionReminder.configure({
-  provider: 'telegram',
-  providers: {
-    telegramBotToken: '123456:ABC...',
-    telegramChatId:   '987654321',
-  },
-});
-```
+### Bark (iPhone)
 
-随后任意一次 agent 完成都会通过 Telegram 推送到你的手机。
+1. App Store 装 Bark（[apps.apple.com/cn/app/bark](https://apps.apple.com/cn/app/bark-customed-notifications/id1403753865)）
+2. 打开 Bark，记下你的设备 Key
+3. 面板里选 `Bark`，填入 `barkKey`
 
-可用的 provider：
+### Server酱 (微信)
 
-- `browser` — 浏览器原生通知（默认）
-- `telegram` — Telegram Bot
-- `bark` — iPhone Bark
-- `pushover` — Pushover
-- `serverchan` — Server酱 (sct.ftqq.com)
-- `discord` — Discord Webhook
-- `slack` — Slack Webhook
-- `webhook` — 通用 JSON POST Webhook
-- `custom` — 自定义 `customSend(payload)` 函数
+1. 微信扫码登录 [sct.ftqq.com](https://sct.ftqq.com)
+2. 拿到 SendKey（以 `SCT` 开头）
+3. 面板里选 `Server酱`，填入
 
 ## 故障排除
 
 | 问题 | 原因 | 解决方法 |
 |------|------|----------|
 | 安装报 `ERR_PNPM_ADDING_TO_ROOT` | profile 是 pnpm workspace root | 加 `-w` 标志重新执行 |
-| 装了但没有通知 | 未重启 `dsh web` | 重启后强刷页面 |
+| 装了但右下角没有 🔔 按钮 | 未重启 `dsh web` | 重启后强刷页面 |
 | 浏览器没弹权限询问 | 之前已「阻止」该网站 | 浏览器地址栏左侧锁形图标 → 通知 → 允许 |
 | Telegram 报 401/400 | `telegramBotToken` / `telegramChatId` 配错 | 用 `@BotFather` 重新获取 token；用 `getUpdates` 找 chat id |
-| 通知频率太高 | 多个 agent 接连完成 | 调大 `cooldownMs`（默认 5000） |
-| 切回浏览器通知 | 想撤销 Telegram 配置 | `DSHCompletionReminder.configure({ provider: 'browser' })` |
+| 测试按钮提示「Telegram provider requires…」 | 凭证未填 | 滚动到「渠道凭证」区填入对应字段 |
+| 通知频率太高 | 多个 agent 接连完成 | 调大「冷却（ms）」，默认 5000 |
+| 切回浏览器通知 | 想撤销 Telegram 配置 | 面板顶部下拉切回 `浏览器通知` |
 | 完全停用 | — | `DSHCompletionReminder.deactivate()` |
+| 重置所有配置 | — | 设置面板里点「重置」按钮 |
 
 ## 卸载
 

package/lib/client.d.ts

@@ -1,21 +1,19 @@
 /**
- * DSH Completion Reminder — client half.
+ * DSH Completion Reminder — client half (v1.1).
  *
- * A DOM-based DSH client plugin that fires a notification when the agent
- * stops generating. The plugin watches the input toolbar (send vs stop
- * button) and the conversation stream to detect three terminal states:
- * success, user-stopped, and error.
+ * Detects the agent-completion lifecycle by watching the DSH composer
+ * primary button's `aria-label` (which flips between "Stop generating" /
+ * "Stop 生成" / "Stop" while running and "Send message" / "发送消息" /
+ * "Send" when idle) and the conversation root's `data-phase` (which
+ * transitions through `active` / `settling` / `hero`).
  *
- * Delivery channels:
- *   - browser   : window.Notification (default; user-gated permission)
- *   - telegram  : Telegram Bot API
- *   - bark      : Apple Push (Bark) HTTP API
- *   - pushover  : Pushover REST API
- *   - serverchan: Server酱 (sct.ftqq.com) — popular in CN
- *   - discord   : Discord incoming webhook
- *   - slack     : Slack incoming webhook
- *   - webhook   : generic JSON POST webhook
- *   - custom    : user-supplied function
+ * The plugin:
+ *   - exposes `window.DSHCompletionReminder.configure({...})` for API users
+ *   - injects a floating 🔔 button in the bottom-right corner that opens
+ *     a settings panel (provider picker + per-provider credentials + test
+ *     button). Configuration is persisted to localStorage.
+ *   - delivers notifications via 9 channels: browser, Telegram, Bark,
+ *     Pushover, Server酱, Discord, Slack, generic Webhook, custom.
  *
  * The plugin is packaged as a DSH client plugin (`dsh.client` in
  * package.json) and loaded through `window.__ModuleLoader__`.

package/lib/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAEV,yBAAyB,EAK1B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EAGhB,MAAM,YAAY,CAAC;AA8EpB,iBAAS,SAAS,CAAC,IAAI,CAAC,EAAE,yBAAyB,GAAG,IAAI,CAUzD;AAED,iBAAS,QAAQ,IAAI,IAAI,CAcxB;AAED,iBAAS,UAAU,IAAI,IAAI,CAQ1B;AAWD,iBAAe,wBAAwB,IAAI,OAAO,CAAC,sBAAsB,GAAG,aAAa,CAAC,CAczF;AA2jBD;;GAEG;AACH,iBAAS,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,yBAAyB,GAAG,IAAI,CAGnE;AAED,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,wBAAwB,EAAE,eAAe,EAAE,CAAA"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAEV,yBAAyB,EAM1B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EAIhB,MAAM,YAAY,CAAC;AAiFpB,iBAAS,SAAS,CAAC,IAAI,CAAC,EAAE,yBAAyB,GAAG,IAAI,CAgBzD;AAED,iBAAS,QAAQ,IAAI,IAAI,CAiBxB;AAED,iBAAS,UAAU,IAAI,IAAI,CAS1B;AA6CD,iBAAe,wBAAwB,IAAI,OAAO,CAAC,sBAAsB,GAAG,aAAa,CAAC,CAczF;AA+8BD;;GAEG;AACH,iBAAS,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,yBAAyB,GAAG,IAAI,CAGnE;AAED,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,wBAAwB,EAAE,eAAe,EAAE,CAAA"}