dsh-notify 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pasumao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# dsh-plugin-notify
+
+> ⚠️ **AI 生成项目声明**
+>
+> 本项目（代码、脚本、文档）**由 AI 辅助生成**，仅用于学习和参考。
+> 使用前请自行阅读、审查并充分测试代码，按需修改后再部署到你的环境。
+
+dsh Web GUI 的 Windows 通知插件：当 agent **不再运行**时（任务完成 / 被停止 / 出错 / 停下来等你选择 / 会话被关闭），弹一条 Windows 原生 Toast 提醒你回来看结果。适合发起绘画、生成等长任务后离开电脑的场景。
+
+- **纯 host 端插件**：零运行时依赖、零构建步骤，普通 ESM；
+- **通知常驻**：`scenario="reminder"`，直到你手动关闭；
+- **位置标注**：通知正文显示 `工作区「…」 · 会话「…」`，一眼看出是哪个工作区的哪个会话；
+- **系统托盘**：任务栏右下角常驻 dsh 鲸鱼图标，双击/右键「打开 dsh」、右键「关闭进程」终止 dsh 后台，dsh 退出后图标自动消失。
+
+## 目录
+
+- [触发条件](#触发条件)
+- [安装](#安装)
+- [配置](#配置config均有默认值)
+- [测试](#测试)
+- [排障](#排障)
+- [相关文档](#相关文档)
+
+## 触发条件
+
+| 场景 | 信号 | 通知 |
+|---|---|---|
+| 任务正常完成 | `agent/status` running→idle + `turn/end: completed` | 「dsh · 任务完成」 |
+| 你点了停止 / 被中止 | `turn/end: aborted` | 「dsh · 任务已停止」 |
+| 执行出错 | `turn/end: error` | 「dsh · 任务出错」 |
+| 达到输出上限 | `turn/end: max-tokens` | 「dsh · 达到输出上限」 |
+| agent 停下来让你选择 | 未配对的 `ask_user_question` 工具调用 | 「dsh · 在等你选择」 |
+| 运行中的会话被关闭 | `agent/disposed` | 「dsh · 会话已关闭」 |
+
+> **位置标注说明**：每条通知正文带一行 `工作区「…」 · 会话「…」`。
+> 工作区取 `workspaceRegistry` 中该会话的归属标题（兜底用会话 cwd 的目录名），
+> 会话取 sidebar 显示的会话标题（无标题时兜底用会话 id 短号，如 `#a1b2c3d4`）。
+> 两个服务都不可用时该行自动省略，不影响通知。
+
+## 安装
+
+本插件是标准的 DSH **bundle**（`package.json` 声明 `dsh.bundle.patch`，包内自带
+`cordis.patch.yml`），安装后会自动加入 profile 的 bundle 层，无需手动写补丁。
+
+### 方式一：npm（推荐）
+
+```powershell
+dsh plugin --profile web add dsh-notify
+```
+
+### 方式二：GitHub 直接安装（无需 npm）
+
+```powershell
+dsh plugin --profile web add github:Pasumao/dsh-plugin-notify
+```
+
+> git 源插件若带构建脚本，pnpm 会要求先在 `profiles\web\pnpm-workspace.yaml` 的
+> `allowBuilds` 里放行对应包名；本项目零构建（无 prepare 脚本），一般无需配置。
+
+### 方式三：本地路径（开发 / 私有测试）
+
+```powershell
+dsh plugin --profile web add C:/Users/18303/Desktop/dsh-plugin-notify
+```
+
+### 方式四：手动 link（可选，等同旧版流程）
+
+1. 在 `C:\Users\18303\.dsh\profiles\web\package.json` 的 dependencies 加：
+
+   ```jsonc
+   "dependencies": {
+     // ...已有依赖...
+     "dsh-notify": "link:C:/Users/18303/Desktop/dsh-plugin-notify"
+   }
+   ```
+
+2. profile 目录执行安装：
+
+   ```powershell
+   cd C:\Users\18303\.dsh\profiles\web
+   pnpm install
+   ```
+
+安装完成后 **重启 `dsh web`**：任务栏右下角出现 dsh 鲸鱼小图标即加载成功。
+如需调整通知行为，在 profile 的 `cordis.patch.yml` 按 id 覆盖 `config` 即可
+（例如 `- id: dsh-plugin-notify` + `config: { cooldownMs: 5000 }`）。
+
+## 配置（`config`，均有默认值）
+
+| key | 默认 | 说明 |
+|---|---|---|
+| `enabled` | `true` | 总开关 |
+| `tray` | `true` | 系统托盘图标开关（`false` 关闭） |
+| `rootsOnly` | `true` | 仅根会话通知；子代理不刷屏 |
+| `notifyFinished` / `notifyAborted` / `notifyError` / `notifyWaiting` / `notifyDisposed` | 全 `true` | 分类型开关 |
+| `cooldownMs` | `10000` | 同一会话、同一类型两次通知最小间隔（毫秒） |
+| `titlePrefix` | `'dsh'` | 通知标题前缀（形如 `dsh · 任务完成`） |
+| `iconPath` | 内置 `assets/dsh.png` | 通知 logo PNG 路径；设为空串 `''` 则不显示自定义图标 |
+| `webUrl` | `http://127.0.0.1:3080` | dsh 页面地址（点击通知/托盘「打开 dsh」跳转的地址） |
+| `aumid` | PowerShell 5.1 的 AUMID | Toast 归属的 AppUserModelID（一般无需改） |
+| `summaryMaxChars` | `40` | 任务摘要截断长度 |
+| `powershellPath` | 自动 | 覆盖 PowerShell 5.1 路径 |
+
+## 测试
+
+通知管道单测（英文 Toast）：
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/smoke-notice.ps1
+```
+
+插件逻辑端到端自测（无需 dsh、无需重启，弹「等待选择 / 任务完成 / 任务已停止」三条中文 Toast）：
+
+```powershell
+node scripts/test-harness.mjs
+```
+
+## 排障
+
+- **Toast 不出现**：确认 Windows「通知与操作」里允许 PowerShell 显示通知；首次加载 WinRT 模块稍慢属正常。
+- **图标不显示**：确认 `assets/dsh.png`（通知）与 `assets/dsh.ico`（托盘）随插件目录一起存在。
+- **中文乱码**：经环境变量（UTF-16）与 `-EncodedCommand`（UTF-16LE base64）传参，不应乱码。
+
+## 相关文档
+
+- `设计文稿.md`：设计思路、对 dsh 源码的调研结论、实现细节与边界情况。

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# dsh-notify bundle patch: the toast + system-tray notification plugin.
+#
+# Applied as ONE insert over the profile root, after dsh-base/dsh-web-app rows.
+# The user's own profile cordis.patch.yml (and any --patch overlays) is applied
+# afterwards and may override this row's whole `config` by id.
+#
+# `name` must equal the package.json `name` (the loader resolves the plugin
+# module from the profile's node_modules under that name).
+- insert:
+    - id: dsh-plugin-notify
+      name: dsh-notify

package/lib/index.js

@@ -0,0 +1,465 @@
+/**
+ * dsh-plugin-notify — 任务结束 Windows 通知插件（纯 host 端）
+ *
+ * 当 agent「不再运行」时（正常运行完成 / 被中止 / 出错 / 达到输出上限 /
+ * 停下来等待用户选择 / 会话被关闭），弹一条 Windows 原生 Toast 通知（纯提示，
+ * 常驻到手动关闭，点击无动作）。
+ *
+ * 通知正文除了任务摘要，还会标注「工作区 · 会话」位置行：工作区标题取自
+ * `ctx.workspaceRegistry`（按会话归属匹配，兜底用会话 cwd 的目录名），会话
+ * 显示名取自 `ctx.sessionTitle`（sidebar 标题，兜底用会话 id 短号）。两个服务
+ * 都不可用时自动省略，不影响通知本身。
+ *
+ * 触发信号（均为主机端 Cordis 事件）：
+ *   - `agent/status`（idle ⇄ running）：running→idle 即「不再运行」。
+ *   - `session/event`：读取 turn 结束原因、最近用户指令、ask_user_question 等待。
+ *   - `agent/disposed`：会话被关闭/清除的兜底。
+ *
+ * 通知实现：零依赖，spawn Windows PowerShell 5.1 的 ToastNotificationManager
+ * （原生 Toast，自定义 logo + 常驻）。标题/正文经环境变量（UTF-16）传入，
+ * 脚本经 -EncodedCommand（UTF-16LE base64）传入，规避代码页与引号转义问题。
+ *
+ * @module @dsh-external/dsh-plugin-notify
+ */
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const name = 'dsh-plugin-notify'
+export const inject = []
+
+/** 默认配置；patch 条目的 `config` 字段按对象合并覆盖。 */
+const DEFAULT_CONFIG = {
+  /** 总开关。 */
+  enabled: true,
+  /** 系统托盘图标：表示 dsh 后台运行中（任务栏右下角）。设为 false 关闭。 */
+  tray: true,
+  /** 仅根会话（用户自己的会话）通知；子代理默认不刷屏。 */
+  rootsOnly: true,
+  /** 分类型开关。 */
+  notifyFinished: true,
+  notifyAborted: true,
+  notifyError: true,
+  notifyWaiting: true,
+  notifyDisposed: true,
+  /** 同一会话、同一类型两次通知的最小间隔（毫秒，防连发）。 */
+  cooldownMs: 10000,
+  /** 通知标题前缀。 */
+  titlePrefix: 'dsh',
+  /** 自定义通知图标 PNG 路径；默认用插件自带的 dsh 鲸鱼 logo。设为空串则不显示自定义图标。 */
+  iconPath: undefined,
+  /** dsh Web 页面地址（托盘「打开 dsh」跳转的地址）。 */
+  webUrl: 'http://127.0.0.1:3080',
+  /** Toast 归属的 AppUserModelID；默认借用 Windows PowerShell 5.1 已注册的 AUMID。 */
+  aumid: '{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe',
+  /** 用户指令摘要截断长度（字符）。 */
+  summaryMaxChars: 40,
+  /** 覆盖 PowerShell 路径；默认探测 5.1 的绝对路径。 */
+  powershellPath: undefined,
+}
+
+function normalizeConfig(config) {
+  const cfg = { ...DEFAULT_CONFIG }
+  if (config && typeof config === 'object') Object.assign(cfg, config)
+  cfg.cooldownMs = Math.max(0, Math.floor(Number(cfg.cooldownMs) || 0))
+  cfg.summaryMaxChars = Math.max(1, Math.floor(Number(cfg.summaryMaxChars) || 40))
+  cfg.webUrl = (cfg.webUrl || 'http://127.0.0.1:3080').replace(/\/+$/, '')
+  return cfg
+}
+
+/** Windows PowerShell 5.1 绝对路径（保底探测）。 */
+function defaultPowershellPath() {
+  const windir = process.env.windir || process.env.WINDIR || 'C:\\Windows'
+  return join(windir, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
+}
+
+/** 插件自带的 dsh 鲸鱼 logo PNG（相对本模块定位，链接/拷贝部署均可用）。 */
+function defaultIconPath() {
+  return join(dirname(fileURLToPath(import.meta.url)), '..', 'assets', 'dsh.png')
+}
+
+/** 插件自带的 dsh 鲸鱼 logo ICO（托盘图标用）。 */
+function defaultTrayIconPath() {
+  return join(dirname(fileURLToPath(import.meta.url)), '..', 'assets', 'dsh.ico')
+}
+
+/** 当前托盘图标的子进程（模块级：进程内同一时刻至多一个托盘图标）。 */
+let trayChild = null
+
+/**
+ * 弹 Toast 的 PowerShell 脚本。全部参数从环境变量读取：
+ *   DSH_NOTICE_TITLE / DSH_NOTICE_BODY / DSH_NOTICE_LOCATION(「工作区 · 会话」行) /
+ *   DSH_NOTICE_ICON_PATH(logo PNG) / DSH_NOTICE_AUMID(Toast 归属)
+ * 用 ToastNotificationManager 发原生 Toast：自定义 logo + scenario="reminder"
+ * 常驻；activationType="background"（无后台任务 → 点击不触发任何动作，纯提示）。
+ * location 作为第三个 <text>（ToastGeneric 支持多行正文）。
+ */
+const TOAST_SCRIPT = `
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] | Out-Null
+function XmlEscape([string]$s) { return $s.Replace('&','&amp;').Replace('<','&lt;').Replace('>','&gt;').Replace('"','&quot;').Replace("'",'&apos;') }
+$title = [string]$env:DSH_NOTICE_TITLE
+$body = [string]$env:DSH_NOTICE_BODY
+$location = [string]$env:DSH_NOTICE_LOCATION
+$icon = [string]$env:DSH_NOTICE_ICON_PATH
+$aumid = [string]$env:DSH_NOTICE_AUMID
+$iconPart = ''
+if ($icon -and (Test-Path $icon)) {
+  $iconUri = 'file:///' + ($icon.Replace('\\','/'))
+  $iconPart = '<image placement="appLogoOverride" src="' + (XmlEscape $iconUri) + '" hint-crop="circle"/>'
+}
+$locationPart = ''
+if ($location) { $locationPart = '<text>' + (XmlEscape $location) + '</text>' }
+$xmlText = '<toast scenario="reminder" activationType="background"><visual><binding template="ToastGeneric">' + $iconPart + '<text>' + (XmlEscape $title) + '</text><text>' + (XmlEscape $body) + '</text>' + $locationPart + '</binding></visual></toast>'
+$xml = New-Object Windows.Data.Xml.Dom.XmlDocument
+$xml.LoadXml($xmlText)
+$toast = [Windows.UI.Notifications.ToastNotification]::new($xml)
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($aumid).Show($toast)
+`.trim()
+
+/** 派发一条通知（fire-and-forget；失败仅记日志，绝不影响 dsh）。 */
+function fireToast(ctx, cfg, { title, body, location = '' }) {
+  const ps = cfg.powershellPath || defaultPowershellPath()
+  const iconPath = cfg.iconPath === undefined ? defaultIconPath() : (cfg.iconPath ?? '')
+  // -EncodedCommand（UTF-16LE base64）：脚本里即便含双引号/换行也不受命令行转义影响。
+  const encoded = Buffer.from(TOAST_SCRIPT, 'utf16le').toString('base64')
+  let child
+  try {
+    child = spawn(
+      ps,
+      ['-NoProfile', '-STA', '-WindowStyle', 'Hidden', '-EncodedCommand', encoded],
+      {
+        env: {
+          ...process.env,
+          DSH_NOTICE_TITLE: title,
+          DSH_NOTICE_BODY: body,
+          DSH_NOTICE_LOCATION: location,
+          DSH_NOTICE_ICON_PATH: existsSync(iconPath) ? iconPath : '',
+          DSH_NOTICE_AUMID: cfg.aumid,
+        },
+        windowsHide: true,
+        stdio: 'ignore',
+      },
+    )
+  } catch (error) {
+    ctx.logger.warn(`dsh-plugin-notify: failed to launch notification: ${String(error)}`)
+    return
+  }
+  child.on('error', (error) => {
+    ctx.logger.warn(`dsh-plugin-notify: notification process error: ${String(error)}`)
+  })
+}
+
+function truncate(text, max) {
+  if (text.length <= max) return text
+  return `${text.slice(0, max)}…`
+}
+
+/** 取路径最后一段作为目录显示名（工作区标题的兜底）。 */
+function pathBasename(path) {
+  if (typeof path !== 'string' || !path) return ''
+  return path.replace(/[\\/]+$/, '').split(/[\\/]/).pop() ?? ''
+}
+
+/** 解析会话所属工作区的显示名：按归属匹配 workspaceRegistry，找不到则退回 cwd 目录名。 */
+function resolveWorkspaceLabel(ctx, session) {
+  const id = session?.id
+  try {
+    const registry = ctx.workspaceRegistry
+    if (registry && typeof registry.list === 'function') {
+      const workspaces = registry.list()
+      if (Array.isArray(workspaces)) {
+        const match = workspaces.find(
+          (ws) => ws && Array.isArray(ws.sessionIds) && id != null && ws.sessionIds.includes(id),
+        )
+        if (match) {
+          const label = (match.title || pathBasename(match.path) || '').trim()
+          if (label) return truncate(label, 40)
+        }
+      }
+    }
+  } catch {
+    // workspaceRegistry 服务不可用时忽略，走 cwd 兜底。
+  }
+  return truncate(pathBasename(session?.header?.cwd), 40)
+}
+
+/** 解析会话显示名：优先 sidebar 标题（sessionTitle），兜底用会话 id 短号。 */
+function resolveSessionLabel(ctx, session) {
+  try {
+    const snapshot = ctx.sessionTitle?.get?.(session)
+    const title = snapshot?.title
+    if (typeof title === 'string' && title.trim()) return truncate(title.trim(), 40)
+  } catch {
+    // sessionTitle 服务不可用 / 会话已关闭时忽略，走 id 兜底。
+  }
+  return typeof session?.id === 'string' && session.id ? `#${session.id.slice(0, 8)}` : ''
+}
+
+/** 组装「工作区 · 会话」位置行；任一为空则省略对应段。 */
+function composeLocation(workspace, sessionLabel) {
+  const parts = []
+  if (workspace) parts.push(`工作区「${workspace}」`)
+  if (sessionLabel) parts.push(`会话「${sessionLabel}」`)
+  return truncate(parts.join(' · '), 96)
+}
+
+/** 从一条 user/message 里取第一个文本块作为任务摘要。 */
+function summarizePrompt(message, maxChars) {
+  const blocks = message?.content
+  if (!Array.isArray(blocks)) return ''
+  for (const block of blocks) {
+    if (block?.type === 'text' && typeof block.text === 'string' && block.text.trim()) {
+      return truncate(block.text.replace(/\s+/g, ' ').trim(), maxChars)
+    }
+  }
+  return ''
+}
+
+/** 从 ask_user_question 的原始 arguments JSON 里取第一个问题的文本。 */
+function extractQuestion(rawArguments) {
+  try {
+    const parsed = JSON.parse(rawArguments)
+    const question = Array.isArray(parsed?.questions)
+      ? parsed.questions.find((item) => typeof item?.question === 'string' && item.question)
+      : null
+    return question ? truncate(question.question, 60) : ''
+  } catch {
+    return ''
+  }
+}
+
+/** turn/end 的 TurnEndReason.kind → 通知类别。 */
+const REASON_KIND = {
+  completed: 'finished',
+  aborted: 'aborted',
+  error: 'error',
+  interrupted: 'error',
+  'max-tokens': 'max-tokens',
+  blocked: 'blocked',
+}
+
+function createState() {
+  return {
+    running: false,
+    turnStarted: false,
+    lastReason: null,
+    lastPrompt: '',
+    waiting: false,
+    waitingCallId: null,
+    waitingText: '',
+    /** 最近一次可见的会话对象（通知时用于解析位置，随事件更新）。 */
+    session: null,
+    /** 「工作区 · 会话」标签缓存，通知时解析失败可回退。 */
+    workspaceLabel: '',
+    sessionLabel: '',
+    /** 各类型上次通知时间戳，按类型冷却。 */
+    lastToastAt: {},
+  }
+}
+
+export function apply(ctx, config = {}) {
+  const cfg = normalizeConfig(config)
+  if (!cfg.enabled) return
+
+  const states = new Map()
+
+  // 系统托盘图标：表示 dsh 后台运行中。同一进程内至多一个；卸载/重启 dsh 时清理。
+  if (cfg.tray !== false) {
+    if (trayChild) {
+      try { trayChild.kill() } catch {}
+      trayChild = null
+    }
+    try {
+      const root = dirname(fileURLToPath(import.meta.url))
+      const trayPath = join(root, '..', 'scripts', 'tray.ps1')
+      const child = spawn(
+        defaultPowershellPath(),
+        ['-NoProfile', '-STA', '-WindowStyle', 'Hidden', '-ExecutionPolicy', 'Bypass', '-File', trayPath, '-ParentPid', String(process.pid), '-IconPath', defaultTrayIconPath(), '-WebUrl', cfg.webUrl],
+        {
+          env: {
+            ...process.env,
+            DSH_TRAY_TOOLTIP: 'dsh 后台运行中',
+            DSH_TRAY_OPEN: '打开 dsh',
+            DSH_TRAY_EXIT: '关闭进程',
+          },
+          windowsHide: true,
+          stdio: 'ignore',
+        },
+      )
+      trayChild = child
+      child.on('exit', () => { if (trayChild === child) trayChild = null })
+      child.on('error', () => { if (trayChild === child) trayChild = null })
+    } catch (error) {
+      ctx.logger.warn(`dsh-plugin-notify: failed to start tray icon: ${String(error)}`)
+    }
+  }
+
+  const isRoot = (agent) => {
+    const depth = agent?.session?.header?.delegationDepth
+    return depth == null || depth === 0
+  }
+  const isTracked = (agent) => (cfg.rootsOnly ? isRoot(agent) : true)
+
+  const stateFor = (id) => {
+    let state = states.get(id)
+    if (!state) {
+      state = createState()
+      states.set(id, state)
+    }
+    return state
+  }
+
+  const notify = (id, state, kind, session) => {
+    const now = Date.now()
+    const last = state.lastToastAt[kind] ?? 0
+    if (now - last < cfg.cooldownMs) return
+    state.lastToastAt[kind] = now
+
+    const when = new Date().toLocaleTimeString('zh-CN', { hour12: false })
+    const prefix = cfg.titlePrefix
+    const prompt = state.lastPrompt ? `「${state.lastPrompt}」` : '任务'
+    const waitingText = state.waitingText ? `Agent 正在等你选择：${state.waitingText}` : `Agent 正在等你选择（${when}）`
+
+    // 「工作区 · 会话」位置行：优先现取，会话对象缺失时回退状态缓存。
+    const live = session ?? state.session
+    let workspace = live ? resolveWorkspaceLabel(ctx, live) : state.workspaceLabel
+    let sessionLabel = live ? resolveSessionLabel(ctx, live) : state.sessionLabel
+    if (!workspace) workspace = state.workspaceLabel
+    if (!sessionLabel) sessionLabel = state.sessionLabel
+    if (live) {
+      if (workspace) state.workspaceLabel = workspace
+      if (sessionLabel) state.sessionLabel = sessionLabel
+    }
+    const location = composeLocation(workspace, sessionLabel)
+
+    const messages = {
+      finished: { title: `${prefix} · 任务完成`, body: `${prompt} 已完成（${when}）` },
+      aborted: { title: `${prefix} · 任务已停止`, body: `${prompt} 已被中止（${when}）` },
+      error: { title: `${prefix} · 任务出错`, body: `${prompt} 执行出错（${when}）` },
+      'max-tokens': { title: `${prefix} · 达到输出上限`, body: `${prompt} 达到输出上限（${when}）` },
+      blocked: { title: `${prefix} · 回合被阻断`, body: `${prompt} 回合被阻断（${when}）` },
+      waiting: { title: `${prefix} · 在等你选择`, body: waitingText },
+      disposed: { title: `${prefix} · 会话已关闭`, body: `运行中的会话已关闭（${when}）` },
+    }
+    const message = messages[kind] ?? messages.finished
+    fireToast(ctx, cfg, { ...message, location })
+    ctx.logger.debug(`dsh-plugin-notify: ${kind} -> "${message.title}" (session ${id}${location ? `, ${location}` : ''})`)
+  }
+
+  const onStatus = ({ agent, status }) => {
+    if (!isTracked(agent)) return
+    const state = stateFor(agent.id)
+    state.session = agent.session ?? state.session
+
+    if (status === 'running') {
+      state.running = true
+      return
+    }
+
+    // running → idle：agent 不再运行。
+    if (!state.running) return
+    state.running = false
+
+    const active = state.turnStarted || state.waiting
+    const kind = REASON_KIND[state.lastReason] ?? 'finished'
+    state.turnStarted = false
+    state.lastReason = null
+
+    // 空转（唤醒后消息被清空、无实际回合）不通知。
+    if (!active) return
+
+    const gate = {
+      finished: cfg.notifyFinished,
+      aborted: cfg.notifyAborted,
+      error: cfg.notifyError,
+      'max-tokens': cfg.notifyFinished,
+      blocked: cfg.notifyAborted,
+    }[kind]
+    if (gate === false) return
+
+    notify(agent.id, state, kind, agent.session)
+  }
+
+  const onSessionEvent = (session, event) => {
+    const depth = session.header?.delegationDepth
+    if (cfg.rootsOnly && depth != null && depth !== 0) return
+    const state = stateFor(session.id)
+    state.session = session
+
+    switch (event.type) {
+      case 'turn/start':
+        state.turnStarted = true
+        break
+      case 'turn/end':
+        state.lastReason = event.data?.reason?.kind ?? null
+        break
+      case 'user/message':
+        state.lastPrompt = summarizePrompt(event.data?.message, cfg.summaryMaxChars)
+        break
+      case 'tool/call': {
+        const call = event.data
+        if (call?.name === 'ask_user_question') {
+          state.waiting = true
+          state.waitingCallId = call.callId
+          state.waitingText = extractQuestion(call.arguments)
+          // 此刻状态仍是 running：立即提醒用户回来做选择。
+          if (state.running && cfg.notifyWaiting) notify(session.id, state, 'waiting', session)
+        }
+        break
+      }
+      case 'tool/result': {
+        const result = event.data
+        if (state.waiting && result?.message?.callId === state.waitingCallId) {
+          state.waiting = false
+          state.waitingCallId = null
+          state.waitingText = ''
+        }
+        break
+      }
+      default:
+        break
+    }
+  }
+
+  const onDisposed = ({ agent }) => {
+    const state = states.get(agent.id)
+    if (!state) return
+    const wasRunning = state.running
+    states.delete(agent.id)
+    // agent/disposed 在会话分离前派发，agent.session 仍可读；异常时 notify 走状态缓存兜底。
+    if (wasRunning && cfg.notifyDisposed) notify(agent.id, state, 'disposed', agent.session)
+  }
+
+  // 激活时播种：已 running 的 agent 记为「有活动」，完成时照常通知；
+  // 空闲的 agent 不产生状态（避免历史会话刷屏）。
+  try {
+    const agents = ctx.agents?.list?.()
+    if (Array.isArray(agents)) {
+      for (const agent of agents) {
+        if (isTracked(agent) && agent.status === 'running') {
+          stateFor(agent.id).running = true
+          stateFor(agent.id).turnStarted = true
+        }
+      }
+    }
+  } catch {
+    // 无 agents 服务时不播种，仅依赖事件。
+  }
+
+  const offStatus = ctx.on('agent/status', onStatus)
+  const offSession = ctx.on('session/event', onSessionEvent)
+  const offDisposed = ctx.on('agent/disposed', onDisposed)
+
+  ctx.effect(() => () => {
+    offStatus()
+    offSession()
+    offDisposed()
+    states.clear()
+    if (trayChild) {
+      try { trayChild.kill() } catch {}
+      trayChild = null
+    }
+  })
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "dsh-notify",
+  "description": "DeepSeek Harness (dsh) Windows notification plugin: a native toast when the agent stops running (finished / aborted / error / waiting for your choice / session closed), plus a system-tray icon. Pure host-side, zero dependencies, zero build.",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "assets",
+    "scripts",
+    "cordis.patch.yml",
+    "README.md",
+    "设计文稿.md"
+  ],
+  "scripts": {
+    "smoke": "powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/smoke-notice.ps1",
+    "pack": "npm pack"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "engines": {
+    "node": ">=22.5"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek",
+    "harness",
+    "cordis",
+    "plugin",
+    "notify",
+    "notification",
+    "toast",
+    "windows"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pasumao/dsh-plugin-notify.git"
+  },
+  "homepage": "https://github.com/Pasumao/dsh-plugin-notify#readme",
+  "bugs": {
+    "url": "https://github.com/Pasumao/dsh-plugin-notify/issues"
+  },
+  "license": "MIT",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/scripts/smoke-notice.ps1

@@ -0,0 +1,25 @@
+# smoke-notice.ps1 - standalone Toast smoke test.
+#
+# ASCII-only on purpose: Windows PowerShell 5.1 reads .ps1 as the system
+# ANSI code page, so non-ASCII literals here would fail to parse on a
+# Chinese-locale machine. Chinese text is exercised by the plugin itself,
+# which passes title/body via UTF-16 environment variables (code-page safe).
+#
+# Usage: powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/smoke-notice.ps1
+param(
+  [string]$Title = "DSH notice test",
+  [string]$Body = "If you can read this toast, the notification pipeline works."
+)
+
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] | Out-Null
+
+$t = $Title.Replace('&', '&amp;').Replace('<', '&lt;').Replace('>', '&gt;')
+$b = $Body.Replace('&', '&amp;').Replace('<', '&lt;').Replace('>', '&gt;')
+$xmlText = '<toast><visual><binding template="ToastGeneric"><text>' + $t + '</text><text>' + $b + '</text></binding></visual></toast>'
+
+$xml = New-Object Windows.Data.Xml.Dom.XmlDocument
+$xml.LoadXml($xmlText)
+$toast = [Windows.UI.Notifications.ToastNotification]::new($xml)
+$appId = '{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\WindowsPowerShell\v1.0\powershell.exe'
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($appId).Show($toast)

package/scripts/test-harness.mjs

@@ -0,0 +1,101 @@
+/**
+ * test-harness.mjs — dsh-plugin-notify 端到端测试（无需 dsh、无需重启）。
+ *
+ * 用带事件记录的 mock ctx 直接驱动插件处理器，验证「等待选择 / 任务完成 /
+ * 任务被停止」三条链路都会真实弹出 Windows Toast（含中文渲染）。事件载荷
+ * 与 dsh 源码中 `agent/status`、`session/event` 的契约保持一致。
+ *
+ * 运行：node scripts/test-harness.mjs
+ */
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const mod = await import(pathToFileURL(join(here, '..', 'lib', 'index.js')).href)
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/** 记录 ctx.on 注册的处理器，便于手动派发事件。 */
+const handlers = new Map()
+const ctx = {
+  agents: { list: () => [] },
+  /** mock workspaceRegistry：test-session 归属「dsh-plugin-notify」工作区。 */
+  workspaceRegistry: {
+    list: () => [
+      {
+        id: 'ws-1',
+        path: 'C:\\Users\\18303\\Desktop\\dsh-plugin-notify',
+        title: 'dsh-plugin-notify',
+        sessionIds: ['test-session'],
+      },
+    ],
+  },
+  /** mock sessionTitle：返回 sidebar 标题。 */
+  sessionTitle: {
+    get: (s) => (s?.id === 'test-session' ? { title: '画一只赛博朋克猫' } : undefined),
+  },
+  on(name, cb) {
+    if (!handlers.has(name)) handlers.set(name, [])
+    handlers.get(name).push(cb)
+    return () => {}
+  },
+  effect(fn) {
+    return () => fn()
+  },
+  logger: {
+    debug: (...a) => console.log('[debug]', ...a),
+    warn: (...a) => console.log('[warn]', ...a),
+    info: (...a) => console.log('[info]', ...a),
+  },
+}
+
+// tray: false —— 测试只验证通知管道，不启动常驻托盘图标（否则 node 进程不会退出）。
+mod.apply(ctx, { cooldownMs: 0, summaryMaxChars: 40, tray: false })
+
+const emit = (name, ...args) => {
+  for (const cb of handlers.get(name) ?? []) cb(...args)
+}
+
+const session = {
+  id: 'test-session',
+  header: { cwd: 'C:\\Users\\18303\\Desktop\\dsh-plugin-notify' }, // 无 delegationDepth = 根会话
+}
+const agent = { id: 'test-session', status: 'running', session }
+
+function startTurn() {
+  emit('agent/status', { agent, status: 'running' })
+  emit('session/event', session, { type: 'turn/start', data: { turn: 1 } })
+}
+
+console.log('=== 场景 1：等你选择（ask_user_question）===')
+startTurn()
+emit('session/event', session, {
+  type: 'user/message',
+  data: { message: { content: [{ type: 'text', text: '画一只赛博朋克猫' }] } },
+})
+emit('session/event', session, {
+  type: 'tool/call',
+  data: {
+    callId: 'c1',
+    name: 'ask_user_question',
+    arguments: '{"questions":[{"id":"q1","question":"选方案A还是方案B？"}]}',
+  },
+})
+await sleep(6500)
+
+console.log('=== 场景 2：任务完成 ===')
+emit('session/event', session, { type: 'tool/result', data: { message: { callId: 'c1' } } })
+emit('session/event', session, { type: 'turn/end', data: { reason: { kind: 'completed' } } })
+emit('agent/status', { agent, status: 'idle' })
+await sleep(6500)
+
+console.log('=== 场景 3：任务被停止 ===')
+startTurn()
+emit('session/event', session, {
+  type: 'turn/end',
+  data: { reason: { kind: 'aborted', reason: { kind: 'user' } } },
+})
+emit('agent/status', { agent, status: 'idle' })
+await sleep(6500)
+
+console.log('done')

package/scripts/tray.ps1

@@ -0,0 +1,79 @@
+# tray.ps1 - dsh system-tray icon.
+#
+# Runs a NotifyIcon for as long as the parent dsh process is alive: it shows a
+# small dsh whale in the system tray (taskbar notification area), opens the dsh
+# page on double-click / "Open" menu item, and exits (icon disappears) when the
+# parent process is gone. The "Exit" menu item terminates the parent dsh
+# process (i.e. closes the dsh backend).
+#
+# ASCII-only on purpose: Windows PowerShell 5.1 reads .ps1 as ANSI, so all
+# user-visible Chinese labels come from UTF-16 environment variables set by the
+# plugin. Run with -STA (WinForms message pump requires it).
+param(
+  [int]$ParentPid = 0,
+  [string]$IconPath = '',
+  [string]$WebUrl = 'http://127.0.0.1:3080'
+)
+
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+
+$tooltip = [string]$env:DSH_TRAY_TOOLTIP
+if (-not $tooltip) { $tooltip = 'dsh running' }
+$openLabel = [string]$env:DSH_TRAY_OPEN
+if (-not $openLabel) { $openLabel = 'Open dsh' }
+$exitLabel = [string]$env:DSH_TRAY_EXIT
+if (-not $exitLabel) { $exitLabel = 'Exit' }
+
+$notify = New-Object System.Windows.Forms.NotifyIcon
+if ($IconPath -and (Test-Path $IconPath)) {
+  $notify.Icon = [System.Drawing.Icon]::new($IconPath)
+} else {
+  $notify.Icon = [System.Drawing.SystemIcons]::Application
+}
+$notify.Text = $tooltip
+$notify.Visible = $true
+
+$menu = New-Object System.Windows.Forms.ContextMenuStrip
+$openItem = New-Object System.Windows.Forms.ToolStripMenuItem
+$openItem.Text = $openLabel
+$openItem.Add_Click({ Start-Process $WebUrl })
+[void]$menu.Items.Add($openItem)
+[void]$menu.Items.Add((New-Object System.Windows.Forms.ToolStripSeparator))
+$hideItem = New-Object System.Windows.Forms.ToolStripMenuItem
+$hideItem.Text = $exitLabel
+$hideItem.Add_Click({
+  # Terminate the parent dsh process, then exit the tray.
+  if ($ParentPid -gt 0) {
+    try { Stop-Process -Id $ParentPid -Force -ErrorAction SilentlyContinue } catch {}
+  }
+  $notify.Visible = $false
+  $notify.Dispose()
+  [System.Windows.Forms.Application]::Exit()
+})
+[void]$menu.Items.Add($hideItem)
+$notify.ContextMenuStrip = $menu
+$notify.Add_DoubleClick({ Start-Process $WebUrl })
+
+# Exit (icon disappears) when the parent dsh process is gone.
+$timer = New-Object System.Windows.Forms.Timer
+$timer.Interval = 3000
+$timer.Add_Tick({
+  if ($ParentPid -gt 0) {
+    $gone = $false
+    try {
+      $p = [System.Diagnostics.Process]::GetProcessById($ParentPid)
+      if ($p.HasExited) { $gone = $true }
+    } catch {
+      $gone = $true
+    }
+    if ($gone) {
+      $notify.Visible = $false
+      $notify.Dispose()
+      [System.Windows.Forms.Application]::Exit()
+    }
+  }
+})
+$timer.Start()
+
+[System.Windows.Forms.Application]::Run()

package//350/256/276/350/256/241/346/226/207/347/250/277.md

@@ -0,0 +1,119 @@
+# dsh-plugin-notify 设计文稿
+
+> 需求：设计一个 dsh 插件——只要 agent「没在运行了」（完成了绘画/生成等任务、被停止、出错、或停下来让我选择），就在 Windows 上弹系统提示提醒我。
+
+## 1. 目标与范围
+
+| 项 | 内容 |
+|---|---|
+| 目标 | 用户用 DSH Web GUI 发起长任务后离开电脑；当 agent 不再运行时弹 Windows 通知，叫用户回来看结果。通知正文标注「工作区 · 会话」位置行，用户能直接知道是哪个工作区的哪个会话完成了。 |
+| 形态 | 纯 **host 端** Cordis 插件（`lib/index.js`，普通 ESM），零运行时依赖、零构建步骤。 |
+| 通知形式 | Windows 原生 Toast（`ToastNotificationManager`），`scenario="reminder"` 常驻直到手动关闭，带 dsh 鲸鱼 logo，点击打开 dsh 页面。 |
+| 后台指示 | 系统托盘（任务栏右下角）常驻 dsh 鲸鱼图标（`NotifyIcon`），双击/右键打开 dsh、右键关闭 dsh 后台，dsh 退出后自动消失。 |
+| 非目标 | 点击通知精确跳转到某个会话（web 端无 URL 深链，且借用 AUMID 的 toast 点击激活在本机不可靠，已放弃）。 |
+
+## 2. 关键结论（对 dsh 源码的调研）
+
+1. **插件注册（标准 bundle）**：依赖的 `package.json` 声明 `dsh.bundle.patch`（指向包内 `cordis.patch.yml`），`dsh plugin --profile <name> add <pkg>` 安装后自动把该包加入 `dsh.profile.bundles` 层（校准逻辑见 `dsh` 的 `plugin` 子命令：按已装依赖里声明了 `dsh.bundle` 的包追加）。包内补丁用 `- insert: [{ id, name, config? }]` 注册自身，用户层 `cordis.patch.yml` 后应用、按 id 覆盖 config。本插件发布名 `dsh-notify`，补丁 `name` 与 `package.json.name` 一致。
+2. **"不再运行"信号**：`@deepseek-ai/dsh-agent` 的 `agent/status`（`idle ⇄ running`），`running → idle` 即"不再运行"；scope 过滤下未打标签的根 ctx 监听者能收到所有 agent 事件。
+3. **结束原因**：`session/event` 的 `turn/end` 带 `TurnEndReason`：`completed / aborted / blocked / error / max-tokens / interrupted`。
+4. **"等你选择"信号**：`ask_user_question` 执行时阻塞、agent 保持 `running`，用日志里未配对的 `tool/call`（`name:'ask_user_question'`）检测，`tool/result.message.callId` 配对即结束。
+5. **配置传递**：cordis loader 调 `apply(ctx, config)`；patch 条目可带 `config:`。
+6. **Windows 通知**：`powershell.exe`(5.1) 恒在 `%WINDIR%\System32\WindowsPowerShell\v1.0\`；用 `ToastNotificationManager` 发原生 Toast，AUMID 借用 PowerShell 已注册的 `{1AC14E77-...}\WindowsPowerShell\v1.0\powershell.exe`；脚本经 `-EncodedCommand`（UTF-16LE base64）传入、数据经 `env`（UTF-16）传入，规避引号/代码页问题。
+7. **位置标注数据源**：`ctx.workspaceRegistry`（`dsh-web-app` 提供）`list()` 返回带 `title`/`path`/`sessionIds` 的工作区，按 `sessionIds.includes(id)` 同步匹配归属；`ctx.sessionTitle`（`dsh-base` 提供）`get(session)` 返回 sidebar 显示的会话标题。两者都是进程内同步读，通知时现取即可，异常/缺失时优雅降级。
+
+## 3. 架构
+
+```
+C:\Users\18303\Desktop\dsh-plugin-notify\
+├── package.json            # dsh-notify；main: lib/index.js；dsh.bundle.patch: ./cordis.patch.yml
+├── cordis.patch.yml        # bundle 补丁：- insert 注册 dsh-plugin-notify 行
+├── lib/index.js            # host 半区：事件订阅 + 状态机 + Toast 派发 + 托盘图标
+├── assets/
+│   ├── dsh.png             # Toast 图标（黑色鲸鱼 logo，256×256）
+│   └── dsh.ico             # 托盘图标（黑色鲸鱼 logo，32×32）
+├── 设计文稿.md              # 本文档
+├── README.md               # 安装/配置/排障
+└── scripts/
+    ├── tray.ps1            # 系统托盘图标（常驻，父进程退出后自动消失）
+    ├── smoke-notice.ps1    # 独立冒烟：直接弹一条 Toast
+    └── test-harness.mjs    # 端到端自测：驱动处理器弹三条真实 Toast
+```
+
+数据流：
+
+```
+agent 循环 ──agent/status──▶ 状态机(每会话) ──running→idle──▶ 组装文案 ──▶ spawn powershell ──▶ Toast（点击打开 dsh 页面）
+            ──session/event─▶ 状态机(记录 turn/reason/摘要/等待) ──等待/完成──▶ 同上
+            ──agent/disposed▶ 状态机(兜底"已关闭")
+宿主启动 ──▶ spawn tray.ps1 ──▶ 系统托盘常驻图标（父进程退出 → 图标消失）
+```
+
+## 4. 事件订阅与状态机
+
+每个被跟踪的会话维护一条状态记录（`Map<agentId, State>`）：`running`、`turnStarted`（区分空转与真实工作）、`lastReason`、`lastPrompt`、`waiting/waitingCallId/waitingText`、`session`（最近可见会话对象引用）、`workspaceLabel/sessionLabel`（「工作区 · 会话」标签缓存）、`lastToastAt[kind]`（按类型冷却）。
+
+| 事件 | 动作 |
+|---|---|
+| `agent/status` running | `running=true` |
+| `agent/status` idle | 若 `running=true` 且 `turnStarted||waiting` → 按 `lastReason` 选文案通知；空转不通知 |
+| `session/event` `turn/start` | `turnStarted=true` |
+| `session/event` `turn/end` | 记录 `lastReason` |
+| `session/event` `user/message` | 记录 `lastPrompt`（首个文本块摘要） |
+| `session/event` `tool/call`(`ask_user_question`) | 置 `waiting`，立即通知"等你选择" |
+| `session/event` `tool/result`(配对) | 清除 `waiting` |
+| `agent/disposed` | 若曾 running → 通知"会话已关闭"；删状态 |
+
+结束原因 → 标题：`completed`→任务完成、`aborted`→任务已停止、`error/interrupted`→任务出错、`max-tokens`→达到输出上限、`blocked`→回合被阻断。
+
+## 5. 关键实现细节
+
+### 5.1 Toast 派发（fire-and-forget）
+
+`TOAST_SCRIPT` 用 `ToastNotificationManager` 发 `<toast scenario="reminder" activationType="protocol" launch="<webUrl>">`（整条常驻且点击打开 dsh 页面），`<image placement="appLogoOverride" src="file:///…dsh.png">` 显示鲸鱼 logo。脚本经 `-EncodedCommand` 传入、数据经 `env` 传入；进程失败只 `ctx.logger.warn`，不影响 dsh。
+
+正文由三个 `<text>` 组成：标题、任务摘要/等待文案、位置行（`工作区「…」 · 会话「…」`，经 `DSH_NOTICE_LOCATION` 环境变量传入，为空则省略该元素）。位置行在 `notify()` 时现取：`resolveWorkspaceLabel` 先按 `workspaceRegistry.list()` 的 `sessionIds` 匹配归属标题、兜底 cwd 目录名；`resolveSessionLabel` 取 `sessionTitle.get(session).title`、兜底会话 id 短号；两者均含长度截断，服务缺失时自动降级（无服务 → 无位置行）。
+
+### 5.2 系统托盘图标
+
+host 半区 `apply` 时 `spawn(powershell.exe -STA -File scripts/tray.ps1 -ParentPid <pid> …)`，`tray.ps1` 用 `NotifyIcon` + `Application.Run()` 常驻；内置 `Timer` 每 3s 检查父进程 PID，父进程消失即退出；模块级 `trayChild` 保证进程内至多一个。双击/右键「打开 dsh」`Start-Process <webUrl>`，右键「关闭进程」`Stop-Process <父 PID>`。
+
+### 5.3 防抖与空转过滤
+
+激活时把已 `running` 的 agent 记为"有活动"（完成时照常通知），空闲 agent 不建状态（避免历史会话刷屏）；`idle→running→idle` 且无 `turn/start` 不通知；冷却按类型记录，`cooldownMs` 内同类型不重复。
+
+## 6. 配置文件
+
+patch 条目 `config`（全部有默认值，见 `README.md` 表格）。核心字段：`enabled`、`tray`、`rootsOnly`、`notifyFinished/Aborted/Error/Waiting/Disposed`、`cooldownMs`、`titlePrefix`（默认 `'dsh'`）、`iconPath`（默认 `assets/dsh.png`）、`webUrl`、`aumid`、`summaryMaxChars`、`powershellPath`。
+
+## 7. 安装步骤
+
+本项目是标准 DSH bundle：`package.json` 声明 `dsh.bundle.patch: ./cordis.patch.yml`，包内自带 `cordis.patch.yml`（`- insert: [{ id: dsh-plugin-notify, name: dsh-notify }]`）。`dsh plugin` 命令是 pnpm 转发器，安装成功后按「已装依赖中声明了 `dsh.bundle` 的包」自动校准 `dsh.profile.bundles`，无需手动写补丁。
+
+安装方式（任选其一）：
+
+1. **npm**（推荐）：`dsh plugin --profile web add dsh-notify`。
+2. **GitHub**：`dsh plugin --profile web add github:Pasumao/dsh-plugin-notify`（零构建，一般无需 allowBuilds）。
+3. **本地路径**：`dsh plugin --profile web add C:/Users/18303/Desktop/dsh-plugin-notify`。
+4. **手动 link**（旧版流程）：dependencies 加 `"dsh-notify": "link:C:/Users/18303/Desktop/dsh-plugin-notify"` 后 `pnpm install`。
+
+装完重启 `dsh web`（托盘图标出现即加载成功）。调整行为时在用户层 `cordis.patch.yml` 按 id 覆盖 config。
+
+## 8. 边界与备选
+
+| 情况 | 处理 |
+|---|---|
+| 重载时已空闲的历史会话 | 不建状态、不通知 |
+| 唤醒后被清空的空转 | 无 `turn/start`，不通知 |
+| 子代理大量完成 | `rootsOnly` 默认过滤（`delegationDepth`） |
+| 中文乱码 | `env`(UTF-16) + `-EncodedCommand`(UTF-16LE base64) |
+| PowerShell 缺失/失败 | 仅 warn，不崩溃 |
+| HMR 重复加载 | `ctx.effect` 清理监听/状态/托盘 |
+
+备选（记录）：点击精确跳会话需注册 dsh 自有 AUMID（`SHGetPropertyStoreFromParsingName` 在本机返回 `0x80070057` 未成功），或用 BurntToast 模块（`Install-Module BurntToast`）实现可点击 toast。
+
+## 9. 测试与验收
+
+1. `scripts/smoke-notice.ps1` 独立弹 Toast；`node scripts/test-harness.mjs` 驱动处理器弹三条真实 Toast（等待/完成/停止）。
+2. 端到端（重启后）：正常任务完成弹 Toast、点停止弹"任务已停止"、`ask_user_question` 等待期弹"在等你选择"、重载旧会话不弹、子代理不刷屏、关闭 running 会话弹"已关闭"；托盘图标常驻、父进程退出自动消失、点击打开 dsh。
+3. 日志：`ctx.logger` 记录每次通知的 kind/session/「工作区 · 会话」位置行与 spawn 错误。