dsh-completion-reminder 1.0.0

package/dist/dsh-completion-reminder.js

@@ -0,0 +1,590 @@
+/**
+ * DSH Completion Reminder — standalone bundle
+ *
+ * Load this file as a regular <script> tag in the DSH Web GUI page
+ * to receive a browser/system notification when the agent finishes.
+ *
+ * Usage:
+ *   <script src="dsh-completion-reminder.js"></script>
+ *   <script>
+ *     DSHCompletionReminder.configure({
+ *       provider: 'telegram',
+ *       providers: { telegramBotToken: '…', telegramChatId: '…' },
+ *     });
+ *     DSHCompletionReminder.activate();
+ *   </script>
+ */
+(function () {
+  'use strict';
+
+  // ── options ────────────────────────────────────────────────────────
+  var DEFAULTS = {
+    provider: 'browser',
+    autoRequestPermission: true,
+    notifyOnSuccess: true,
+    notifyOnStopped: true,
+    notifyOnError: true,
+    suppressWhenFocused: true,
+    cooldownMs: 5000,
+    providers: {},
+    clickUrl: '',
+    iconUrl: '',
+    onNotify: function () { return undefined; },
+    onError: function (err) { try { console.warn('[dsh-completion-reminder]', err); } catch (_e) {} },
+    titleTemplate: function (ctx) {
+      if (ctx.status === 'success') return '✅ DSH Agent 已完成';
+      if (ctx.status === 'stopped') return '⏹ DSH Agent 已停止';
+      return '⚠️ DSH Agent 出错';
+    },
+    bodyTemplate: function (ctx) {
+      var parts = [];
+      if (ctx.agent) parts.push('Agent: ' + ctx.agent);
+      if (ctx.model) parts.push('Model: ' + ctx.model);
+      if (typeof ctx.durationMs === 'number') {
+        if (ctx.durationMs < 1000) parts.push('用时: ' + Math.round(ctx.durationMs) + 'ms');
+        else {
+          var total = Math.round(ctx.durationMs / 1000);
+          if (total >= 3600) parts.push('用时: ' + Math.floor(total / 3600) + 'h ' + Math.floor((total % 3600) / 60) + 'm');
+          else if (total >= 60) parts.push('用时: ' + Math.floor(total / 60) + 'm ' + (total % 60) + 's');
+          else parts.push('用时: ' + total + 's');
+        }
+      }
+      if (!parts.length) return '代理任务已结束，点击查看详情。';
+      return parts.join(' · ');
+    },
+  };
+
+  var CSS_VARS = {
+    bgModule: 'var(--dsw-alias-bg-module-platform)',
+    borderL3: 'var(--dsw-alias-border-l3)',
+    labelPrimary: 'var(--dsw-alias-label-primary)',
+    labelSecondary: 'var(--dsw-alias-label-secondary)',
+    labelTertiary: 'var(--dsw-alias-label-tertiary)',
+    shadowLv3: 'var(--dsw-shadow-lv3)',
+  };
+
+  var TOOLBAR_BUTTON_SELECTORS = [
+    'button[aria-label*="send" i]',
+    'button[aria-label*="stop" i]',
+    'button[aria-label*="停止" i]',
+    'button[aria-label*="发送" i]',
+    'button[aria-label*="取消" i]',
+    'button[aria-label*="中止" i]',
+    'button[aria-label*="abort" i]',
+    'button[aria-label*="cancel" i]',
+    'form button[type="submit"]',
+    'textarea + * button',
+    'textarea ~ button',
+  ];
+
+  var RUNNING_TOKENS = ['stop', 'stop generating', '停止', '中止', '取消生成', 'abort', 'cancel', 'pause', '暂停', 'interrupt'];
+  var SUCCESS_TOKENS = ['send', '发送', 'submit', '提交'];
+
+  var CONVERSATION_SELECTORS = [
+    '[data-conversation-id]',
+    '[data-conversation]',
+    'main [class*="conversation"]',
+    'main [class*="chat"]',
+    'main [class*="message"]',
+  ];
+
+  var opts = Object.assign({}, DEFAULTS);
+  var state = {
+    observer: null,
+    runStartedAt: null,
+    lastModel: null,
+    lastAgent: null,
+    inFlight: false,
+    lastNotifiedAt: 0,
+    isActive: false,
+    permission: detectPermission(),
+    unbinder: [],
+  };
+
+  function detectPermission() {
+    if (typeof window === 'undefined' || !('Notification' in window)) return 'unsupported';
+    return Notification.permission;
+  }
+
+  function toError(value) {
+    if (value instanceof Error) return value;
+    return new Error(typeof value === 'string' ? value : JSON.stringify(value));
+  }
+
+  function safeText(res) {
+    return res.text().then(function (t) { return t.slice(0, 500); }).catch(function () { return ''; });
+  }
+
+  function postJson(url, body) {
+    return fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    }).then(function (res) {
+      if (!res.ok) return safeText(res).then(function (t) {
+        throw new Error('POST ' + url + ' → ' + res.status + ': ' + (t || res.statusText));
+      });
+      return res;
+    });
+  }
+
+  function postForm(url, fields) {
+    var form = new URLSearchParams();
+    for (var k in fields) if (Object.prototype.hasOwnProperty.call(fields, k)) form.set(k, fields[k]);
+    return fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: form.toString(),
+    }).then(function (res) {
+      if (!res.ok) return safeText(res).then(function (t) {
+        throw new Error('POST ' + url + ' → ' + res.status + ': ' + (t || res.statusText));
+      });
+      return res;
+    });
+  }
+
+  function escapeMd(s) {
+    return s.replace(/[_*[\]()~`>#+\-=|{}.!\\]/g, function (m) { return '\\' + m; });
+  }
+
+  function isInsideToolbar(el) {
+    return !!el.closest('form, [class*="composer" i], [class*="toolbar" i], [class*="input" i], [class*="chat-input" i]');
+  }
+
+  function matchesAny(btn, tokens) {
+    var text = (btn.textContent || '').trim().toLowerCase();
+    var aria = (btn.getAttribute('aria-label') || '').trim().toLowerCase();
+    var title = (btn.getAttribute('title') || '').trim().toLowerCase();
+    var cls = (btn.getAttribute('class') || '').toLowerCase();
+    var hay = text + ' ' + aria + ' ' + title + ' ' + cls;
+    return tokens.some(function (tok) { return hay.indexOf(tok) !== -1; });
+  }
+
+  function collectToolbarButtons() {
+    var out = [];
+    var forms = document.querySelectorAll('form, [class*="composer" i], [class*="toolbar" i]');
+    forms.forEach(function (f) {
+      f.querySelectorAll('button').forEach(function (b) {
+        if (b.offsetParent !== null || b.getClientRects().length) out.push(b);
+      });
+    });
+    TOOLBAR_BUTTON_SELECTORS.forEach(function (sel) {
+      document.querySelectorAll(sel).forEach(function (b) {
+        if ((b.offsetParent !== null || b.getClientRects().length) && out.indexOf(b) === -1) {
+          out.push(b);
+        }
+      });
+    });
+    return out;
+  }
+
+  function findLastAssistantMessage() {
+    for (var i = 0; i < CONVERSATION_SELECTORS.length; i++) {
+      var all = document.querySelectorAll(CONVERSATION_SELECTORS[i]);
+      for (var j = all.length - 1; j >= 0; j--) {
+        var el = all[j];
+        var role = (el.getAttribute('data-role') || el.getAttribute('data-author') || '').toLowerCase();
+        if (role.indexOf('assistant') !== -1 || role.indexOf('agent') !== -1 || role.indexOf('model') !== -1) {
+          return el;
+        }
+      }
+    }
+    var main = document.querySelector('main');
+    var last = main && main.lastElementChild;
+    return last || null;
+  }
+
+  function determineStatus() {
+    var last = findLastAssistantMessage();
+    if (!last) return 'success';
+    var text = (last.textContent || '').toLowerCase();
+    if (/(error|exception|failed|traceback|错误|失败|异常)/.test(text) &&
+        !/no error|没有错误|successfully|成功/.test(text)) {
+      return 'error';
+    }
+    if (/(stopped by user|user stopped|手动停止|已停止|已取消)/.test(text)) return 'stopped';
+    return 'success';
+  }
+
+  function readModelFromHeader() {
+    var candidates = document.querySelectorAll('[data-model], [data-testid*="model" i], [class*="model" i]');
+    for (var i = 0; i < candidates.length; i++) {
+      var t = (candidates[i].textContent || '').trim();
+      if (t && t.length < 80) return t;
+    }
+    return null;
+  }
+
+  function readAgentFromHeader() {
+    var candidates = document.querySelectorAll('[data-agent], [data-testid*="agent" i]');
+    for (var i = 0; i < candidates.length; i++) {
+      var t = (candidates[i].textContent || '').trim();
+      if (t && t.length < 80) return t;
+    }
+    return null;
+  }
+
+  function captureRunMetadata() {
+    var m = readModelFromHeader();
+    if (m) state.lastModel = m;
+    var a = readAgentFromHeader();
+    if (a) state.lastAgent = a;
+  }
+
+  function pageIsFocused() {
+    if (typeof document === 'undefined') return true;
+    if (document.visibilityState === 'hidden') return false;
+    if (document.hasFocus && !document.hasFocus()) return false;
+    return true;
+  }
+
+  function evaluateToolbar() {
+    var buttons = collectToolbarButtons();
+    if (!buttons.length) return;
+    var running = buttons.find(function (b) { return matchesAny(b, RUNNING_TOKENS); });
+    captureRunMetadata();
+    if (running && !state.inFlight) {
+      state.inFlight = true;
+      state.runStartedAt = Date.now();
+      return;
+    }
+    if (!running && state.inFlight) {
+      state.inFlight = false;
+      var startedAt = state.runStartedAt || Date.now();
+      var durationMs = Date.now() - startedAt;
+      state.runStartedAt = null;
+      completeRun(determineStatus(), durationMs);
+    }
+  }
+
+  function handleMutations(mutations) {
+    if (!state.isActive) return;
+    for (var i = 0; i < mutations.length; i++) {
+      var m = mutations[i];
+      if (m.type === 'attributes' || m.type === 'characterData') {
+        var target = m.target;
+        if (target && isInsideToolbar(target)) evaluateToolbar();
+      }
+      m.addedNodes.forEach(function (node) {
+        if (!(node instanceof HTMLElement)) return;
+        var selList = TOOLBAR_BUTTON_SELECTORS.join(',');
+        if (node.matches && node.matches(selList)) {
+          evaluateToolbar();
+        } else if (node.querySelector && node.querySelector(selList)) {
+          evaluateToolbar();
+        }
+      });
+    }
+  }
+
+  function startObserver() {
+    if (state.observer) state.observer.disconnect();
+    state.observer = new MutationObserver(handleMutations);
+    state.observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+      attributes: true,
+      attributeFilter: ['aria-label', 'aria-pressed', 'data-state', 'data-status', 'class', 'disabled'],
+    });
+    evaluateToolbar();
+  }
+
+  function stopObserver() {
+    if (state.observer) { state.observer.disconnect(); state.observer = null; }
+  }
+
+  function bindVisibilityEvents() {
+    if (typeof document === 'undefined') return;
+    var onVis = function () {};
+    document.addEventListener('visibilitychange', onVis);
+    state.unbinder.push(function () { document.removeEventListener('visibilitychange', onVis); });
+    var onFocus = function () {};
+    window.addEventListener('focus', onFocus);
+    state.unbinder.push(function () { window.removeEventListener('focus', onFocus); });
+  }
+
+  function requestBrowserPermission() {
+    if (state.permission === 'unsupported') return Promise.resolve('unsupported');
+    if (Notification.permission !== 'default') {
+      state.permission = Notification.permission;
+      return Promise.resolve(Notification.permission);
+    }
+    return Notification.requestPermission().then(function (result) {
+      state.permission = result;
+      return result;
+    }).catch(function (err) {
+      opts.onError(toError(err), 'browser');
+      return state.permission;
+    });
+  }
+
+  function shouldNotify(status) {
+    if (status === 'success') return opts.notifyOnSuccess;
+    if (status === 'stopped') return opts.notifyOnStopped;
+    if (status === 'error') return opts.notifyOnError;
+    return true;
+  }
+
+  function showInPageToast(payload, hint) {
+    if (typeof document === 'undefined') return;
+    var root = ensureToastRoot();
+    var card = document.createElement('div');
+    card.className = 'dsh-reminder-toast';
+    card.setAttribute('role', 'status');
+    card.innerHTML = '<div class="dsh-reminder-toast-title"></div><div class="dsh-reminder-toast-body"></div>' + (hint ? '<div class="dsh-reminder-toast-hint"></div>' : '');
+    card.querySelector('.dsh-reminder-toast-title').textContent = payload.title;
+    card.querySelector('.dsh-reminder-toast-body').textContent = payload.body;
+    if (hint) card.querySelector('.dsh-reminder-toast-hint').textContent = hint;
+    card.addEventListener('click', function () {
+      if (payload.url) { try { window.open(payload.url, '_self'); } catch (_e) {} }
+      card.remove();
+    });
+    root.appendChild(card);
+    setTimeout(function () { card.classList.add('dsh-reminder-toast-leave'); }, 4500);
+    setTimeout(function () { card.remove(); }, 5200);
+  }
+
+  var toastRoot = null;
+  function ensureToastRoot() {
+    if (toastRoot && document.body.contains(toastRoot)) return toastRoot;
+    if (document.getElementById('dsh-completion-reminder-toast-style')) {
+      // styles already injected
+    } else {
+      var style = document.createElement('style');
+      style.id = 'dsh-completion-reminder-toast-style';
+      style.textContent =
+        '.dsh-reminder-toast-root{position:fixed;top:20px;right:20px;z-index:2147483647;display:flex;flex-direction:column;gap:8px;pointer-events:none;max-width:360px;}' +
+        '.dsh-reminder-toast{pointer-events:auto;background:' + CSS_VARS.bgModule + ';color:' + CSS_VARS.labelPrimary + ';border:1px solid ' + CSS_VARS.borderL3 + ';border-radius:10px;box-shadow:' + CSS_VARS.shadowLv3 + ';padding:12px 14px;font-size:13px;line-height:1.4;cursor:pointer;transition:opacity .25s ease,transform .25s ease;}' +
+        '.dsh-reminder-toast-title{font-weight:600;margin-bottom:4px;}' +
+        '.dsh-reminder-toast-body{color:' + CSS_VARS.labelSecondary + ';white-space:pre-wrap;word-break:break-word;}' +
+        '.dsh-reminder-toast-hint{color:' + CSS_VARS.labelTertiary + ';font-size:12px;margin-top:6px;}' +
+        '.dsh-reminder-toast-leave{opacity:0;transform:translateY(-4px);}';
+      document.head.appendChild(style);
+    }
+    var root = document.createElement('div');
+    root.id = 'dsh-completion-reminder-toasts';
+    root.className = 'dsh-reminder-toast-root';
+    document.body.appendChild(root);
+    toastRoot = root;
+    return root;
+  }
+
+  function deliverBrowser(payload) {
+    return Promise.resolve().then(function () {
+      if (state.permission === 'unsupported') {
+        showInPageToast(payload);
+        return;
+      }
+      if (state.permission !== 'granted') {
+        if (opts.autoRequestPermission) {
+          return requestBrowserPermission().then(function (next) {
+            if (next !== 'granted') {
+              showInPageToast(payload, '未授予通知权限，已改为页面内提示。');
+              return;
+            }
+            fire();
+          });
+        }
+        showInPageToast(payload, '未授予通知权限，已改为页面内提示。');
+        return;
+      }
+      fire();
+
+      function fire() {
+        try {
+          var n = new Notification(payload.title, {
+            body: payload.body,
+            icon: payload.iconUrl,
+            tag: 'dsh-completion-reminder',
+            requireInteraction: false,
+          });
+          n.onclick = function () {
+            try {
+              if (typeof window !== 'undefined' && payload.url) {
+                window.focus();
+                window.open(payload.url, '_self');
+              }
+            } catch (_e) {}
+            n.close();
+          };
+        } catch (err) {
+          showInPageToast(payload, '系统通知失败，已改为页面内提示。');
+          opts.onError(toError(err), 'browser');
+        }
+      }
+    });
+  }
+
+  function deliverTelegram(payload) {
+    var p = opts.providers || {};
+    if (!p.telegramBotToken || !p.telegramChatId) {
+      return Promise.reject(new Error('Telegram provider requires telegramBotToken and telegramChatId'));
+    }
+    var url = 'https://api.telegram.org/bot' + encodeURIComponent(p.telegramBotToken) + '/sendMessage';
+    return postJson(url, {
+      chat_id: p.telegramChatId,
+      text: '*' + escapeMd(payload.title) + '*\n' + escapeMd(payload.body),
+      parse_mode: 'Markdown',
+      disable_web_page_preview: true,
+    });
+  }
+
+  function deliverBark(payload) {
+    var p = opts.providers || {};
+    if (!p.barkKey) return Promise.reject(new Error('Bark provider requires barkKey'));
+    var server = (p.barkServer || 'https://api.day.app').replace(/\/$/, '');
+    var url = server + '/' + encodeURIComponent(p.barkKey) + '/' +
+      encodeURIComponent(payload.title) + '/' + encodeURIComponent(payload.body) +
+      (payload.url ? '?url=' + encodeURIComponent(payload.url) : '') +
+      (payload.iconUrl ? (payload.url ? '&' : '?') + 'icon=' + encodeURIComponent(payload.iconUrl) : '');
+    return fetch(url, { method: 'GET' }).then(function (res) {
+      if (!res.ok) return safeText(res).then(function (t) {
+        throw new Error('Bark ' + res.status + ': ' + (t || res.statusText));
+      });
+      return res;
+    });
+  }
+
+  function deliverPushover(payload) {
+    var p = opts.providers || {};
+    if (!p.pushoverToken || !p.pushoverUserKey) {
+      return Promise.reject(new Error('Pushover provider requires pushoverToken and pushoverUserKey'));
+    }
+    var fields = {
+      token: p.pushoverToken,
+      user: p.pushoverUserKey,
+      title: payload.title,
+      message: payload.body,
+      url: payload.url,
+      url_title: 'Open DSH',
+    };
+    if (p.pushoverDevice) fields.device = p.pushoverDevice;
+    return postForm('https://api.pushover.net/1/messages.json', fields);
+  }
+
+  function deliverServerChan(payload) {
+    var p = opts.providers || {};
+    if (!p.serverchanSendKey) return Promise.reject(new Error('Server酱 provider requires serverchanSendKey'));
+    return postForm('https://sctapi.ftqq.com/' + encodeURIComponent(p.serverchanSendKey) + '.send', {
+      title: payload.title,
+      desp: payload.body + (payload.url ? '\n\n[打开 DSH](' + payload.url + ')' : ''),
+    });
+  }
+
+  function deliverDiscord(payload) {
+    var p = opts.providers || {};
+    if (!p.discordWebhookUrl) return Promise.reject(new Error('Discord provider requires discordWebhookUrl'));
+    return postJson(p.discordWebhookUrl, {
+      content: '**' + payload.title + '**\n' + payload.body + (payload.url ? '\n' + payload.url : ''),
+      username: 'DSH Reminder',
+    });
+  }
+
+  function deliverSlack(payload) {
+    var p = opts.providers || {};
+    if (!p.slackWebhookUrl) return Promise.reject(new Error('Slack provider requires slackWebhookUrl'));
+    return postJson(p.slackWebhookUrl, {
+      text: '*' + payload.title + '*\n' + payload.body + (payload.url ? '\n<' + payload.url + '|Open DSH>' : ''),
+    });
+  }
+
+  function deliverWebhook(payload) {
+    var p = opts.providers || {};
+    if (!p.webhookUrl) return Promise.reject(new Error('Webhook provider requires webhookUrl'));
+    var body = p.webhookPayload ? p.webhookPayload(payload) : payload;
+    return postJson(p.webhookUrl, body);
+  }
+
+  function deliverCustom(payload) {
+    var p = opts.providers || {};
+    if (!p.customSend) return Promise.reject(new Error('Custom provider requires providers.customSend'));
+    return Promise.resolve(p.customSend(payload));
+  }
+
+  function dispatch(payload) {
+    var provider = opts.provider;
+    if (provider === 'browser') return deliverBrowser(payload);
+    if (provider === 'telegram') return deliverTelegram(payload);
+    if (provider === 'bark') return deliverBark(payload);
+    if (provider === 'pushover') return deliverPushover(payload);
+    if (provider === 'serverchan') return deliverServerChan(payload);
+    if (provider === 'discord') return deliverDiscord(payload);
+    if (provider === 'slack') return deliverSlack(payload);
+    if (provider === 'webhook') return deliverWebhook(payload);
+    if (provider === 'custom') return deliverCustom(payload);
+    return Promise.reject(new Error('Unknown provider: ' + provider));
+  }
+
+  function completeRun(status, durationMs) {
+    if (!shouldNotify(status)) return Promise.resolve();
+    if (opts.suppressWhenFocused && pageIsFocused()) return Promise.resolve();
+    var now = Date.now();
+    if (now - state.lastNotifiedAt < opts.cooldownMs) return Promise.resolve();
+    state.lastNotifiedAt = now;
+    var ctx = {
+      status: status,
+      model: state.lastModel || undefined,
+      agent: state.lastAgent || undefined,
+      durationMs: durationMs,
+      completedAt: new Date().toISOString(),
+      url: opts.clickUrl || (typeof location !== 'undefined' ? location.href : ''),
+    };
+    var payload = {
+      title: opts.titleTemplate(ctx),
+      body: opts.bodyTemplate(ctx),
+      url: ctx.url,
+      iconUrl: opts.iconUrl || undefined,
+      status: status,
+      model: ctx.model,
+      agent: ctx.agent,
+      durationMs: durationMs,
+      completedAt: ctx.completedAt,
+    };
+    return dispatch(payload).then(function () {
+      opts.onNotify(payload, opts.provider);
+    }).catch(function (err) {
+      opts.onError(toError(err), opts.provider);
+    });
+  }
+
+  var api = {
+    DEFAULTS: DEFAULTS,
+    configure: function (options) {
+      if (options) {
+        for (var k in options) {
+          if (Object.prototype.hasOwnProperty.call(options, k) && Object.prototype.hasOwnProperty.call(DEFAULTS, k)) {
+            opts[k] = options[k];
+          }
+        }
+        if (options.providers) opts.providers = Object.assign({}, DEFAULTS.providers, options.providers);
+      }
+    },
+    activate: function () {
+      if (state.isActive) return;
+      state.isActive = true;
+      if (opts.provider === 'browser' && opts.autoRequestPermission && state.permission === 'default') {
+        requestBrowserPermission();
+      }
+      startObserver();
+      bindVisibilityEvents();
+    },
+    deactivate: function () {
+      state.isActive = false;
+      stopObserver();
+      for (var i = 0; i < state.unbinder.length; i++) {
+        try { state.unbinder[i](); } catch (_e) {}
+      }
+      state.unbinder = [];
+      state.runStartedAt = null;
+      state.inFlight = false;
+    },
+    requestBrowserPermission: requestBrowserPermission,
+    apply: function (ctx, options) {
+      if (options) api.configure(options);
+      api.activate();
+    },
+  };
+
+  window.DSHCompletionReminder = api;
+})();

package/install.md

@@ -0,0 +1,97 @@
+# DSH 完成提醒插件 - 安装指南
+
+## 前提条件
+
+- DeepSeek Harness (DSH) 已安装
+- 浏览器允许 `http://127.0.0.1:3080` 发送通知（首次使用时会弹权限请求）
+
+## 安装（npm，推荐）
+
+```bash
+dsh plugin --profile web add dsh-completion-reminder
+```
+
+> 如果报 `ERR_PNPM_ADDING_TO_ROOT`，说明 profile 目录是 pnpm workspace root，补一个 `-w`：
+>
+> ```bash
+> dsh plugin --profile web add -w dsh-completion-reminder
+> ```
+
+插件包内自带 `cordis.patch.yml` 并声明 `dsh.bundle.patch`，
+`dsh plugin add` 时 DSH 会**自动**把插件加入 profile 的 bundles 层——无需手动编辑任何配置文件。
+
+然后重启：
+
+```bash
+dsh web
+```
+
+启动后，浏览器地址栏左侧应该会出现「🔔 想显示通知吗？」的权限询问。
+点击「允许」即可启用浏览器原生通知。
+
+### 升级
+
+```bash
+dsh plugin --profile web update dsh-completion-reminder
+dsh web   # 重启生效
+```
+
+## 验证安装
+
+1. 打开或强制刷新 DSH Web GUI（http://127.0.0.1:3080，Ctrl+Shift+R）
+2. 给 agent 发任意一条消息
+3. 等任务结束 → 系统右下角（或顶部）出现通知：「✅ DSH Agent 已完成 · 用时 Xs」
+
+如果浏览器拒绝了通知权限，插件会自动改用页面内浮动 toast，**不会**完全失效。
+
+## 切换到第三方通知
+
+在 DSH 页面打开 DevTools 控制台，运行：
+
+```javascript
+DSHCompletionReminder.configure({
+  provider: 'telegram',
+  providers: {
+    telegramBotToken: '123456:ABC...',
+    telegramChatId:   '987654321',
+  },
+});
+```
+
+随后任意一次 agent 完成都会通过 Telegram 推送到你的手机。
+
+可用的 provider：
+
+- `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)` 函数
+
+## 故障排除
+
+| 问题 | 原因 | 解决方法 |
+|------|------|----------|
+| 安装报 `ERR_PNPM_ADDING_TO_ROOT` | profile 是 pnpm workspace root | 加 `-w` 标志重新执行 |
+| 装了但没有通知 | 未重启 `dsh web` | 重启后强刷页面 |
+| 浏览器没弹权限询问 | 之前已「阻止」该网站 | 浏览器地址栏左侧锁形图标 → 通知 → 允许 |
+| Telegram 报 401/400 | `telegramBotToken` / `telegramChatId` 配错 | 用 `@BotFather` 重新获取 token；用 `getUpdates` 找 chat id |
+| 通知频率太高 | 多个 agent 接连完成 | 调大 `cooldownMs`（默认 5000） |
+| 切回浏览器通知 | 想撤销 Telegram 配置 | `DSHCompletionReminder.configure({ provider: 'browser' })` |
+| 完全停用 | — | `DSHCompletionReminder.deactivate()` |
+
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-completion-reminder
+```
+
+然后重启：
+
+```bash
+dsh web
+```