dsh-messager 0.1.4 → 0.2.0

package/README.md

@@ -1,165 +1,165 @@
 # dsh-messager
 
-[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
-[![npm version](https://img.shields.io/npm/v/dsh-messager)](https://www.npmjs.com/package/dsh-messager)
-[![Node](https://img.shields.io/badge/node-%3E%3D20-blue.svg)](package.json)
+DeepSeek Harness（DSH）**任务状态通知插件**：会话需要交互、任务完成、任务出错时，通过
+**系统通知**（OS toast）、**浏览器通知**、**飞书 / 企业微信 / Discord / 钉钉 / Telegram** 推送提醒，
+不再依赖盯着会话列表的圆点。
 
-> **DeepSeek Harness（DSH）任务状态通知插件** / *Task-status notification plugin for DeepSeek Harness (DSH)*
->
-> 会话需要交互、任务完成、任务出错时，通过**系统通知**（OS toast）、**浏览器通知**、**飞书机器人（webhook）**推送提醒——不再依赖盯着会话列表的圆点。
-> *Get notified via system notifications, browser notifications, and a Feishu (Lark) bot whenever a session needs attention, a task completes, or a task errors.*
-
-单包双运行端（dual-runtime）结构：**host 端**（Node）负责系统通知与飞书 webhook，**client 端**（浏览器）负责 Web Notification。两者配置同源（命名空间 `messager`），设置页「通知&信使」分区可编辑、实时生效——配置经插件自身的 webServer 路由（`/dsh-messager/config`），**不受 DSH 设置白名单限制，发行版（npx/npm 安装）同样可用**。
-
----
-
-## 目录 / Table of Contents
-
-- [特性 / Features](#特性--features)
-- [安装 / Installation](#安装--installation)
-- [配置 / Configuration](#配置--configuration)
-- [设置分区 / Settings section](#设置分区通知信使--settings-section)
-- [触发信号 / Trigger signals](#触发信号--trigger-signals)
-- [通道扩展 / Channel extension](#通道扩展--channel-extension)
-- [项目结构 / Project structure](#项目结构--project-structure)
-- [开发与测试 / Development](#开发与测试--development)
-- [已知边界 / Known limitations](#已知边界--known-limitations)
-- [许可 / License](#许可--license)
+单包双运行端（dual-runtime）结构：**host 端**（Node，服务端）负责系统通知与全部第三方通道，
+**client 端**（浏览器）负责 Web Notification；两者配置同源（settings 命名空间 `messager`），
+设置页「通知&信使」分区可编辑、实时生效 —— 配置通道经插件自身的 webServer 路由
+（`/dsh-messager/config`），**不受 DSH 设置白名单限制，发行版（npx 安装）同样可用**。
 
----
+## 能力一览
 
-## 特性 / Features
-
-| 特性 | 说明 |
+| 需求 | 实现 |
 | --- | --- |
-| **触发时机** | 需要交互（审批 / 提问 / 计划待审）、任务完成、任务出错，见[触发信号](#触发信号--trigger-signals) |
-| **推送路径** | 系统通知（node-notifier toast）、浏览器通知（Notification API）、飞书机器人（webhook：interactive 卡片 + HMAC-SHA256 签名） |
-| **可配置** | 各通道启停 / 内容繁复度 / icon、触发开关、去重冷却、标题前缀等 |
-| **国际化** | 设置分区菜单与表单随 DSH 语言切换（中文 / English），经 `ctx.locale` 注册 zh/en 字典 |
-| **快捷入口** | 浏览器可经快捷键 `Ctrl+Shift+M` 打开设置面板（不依赖 apiproxy 白名单） |
-| **易接入** | `NotifyChannel` 接口可扩展第三方通道（钉钉 / 企业微信 / Telegram 等） |
-
-触发语义与 Web UI 状态圆点完全对齐：**橙点 = 需要交互**（`pendingInteraction`），**绿点 = 任务完成**（`running→idle` 且非当前会话），**蓝点 = 运行中**（不通知）。
-
----
+| 触发时机 | 需要交互（审批 `approval/asked`、提问/计划待审 `ask_user_question`、客户端 pendingInteraction）、任务完成（`agent/status` running→idle 且仅根会话 + `turn/end` 原因）、任务出错（`agent/error`） |
+| 推送路径 | 系统通知（node-notifier toast）、浏览器通知（Notification API）、飞书（interactive 卡片 + HMAC-SHA256 签名）、企业微信（markdown + 可选加签）、Discord（embed 卡片）、钉钉（actionCard + 可选加签）、Telegram（Bot API HTML 消息）；`NotifyChannel` 接口可扩展 |
+| 可配置 | 触发开关、各通道启停/verbosity/icon、去重冷却、标题前缀等，见[配置](#配置) |
 
-## 安装 / Installation
+触发语义与 Web UI 状态圆点完全对齐：**橙点 = 需要交互**（`pendingInteraction`），**绿点 = 任务完成**
+（`running→idle` 且非当前会话），**蓝点 = 运行中**（不通知）。
 
-> 支持 **npm / npx / git / 源码**四种安装方式。推荐的正式安装只需一步（host + client 都会生效）。
+## 安装
 
-### 方式一：npm（推荐）<sup>已发布 npm</sup> / *Via npm (recommended, published)*
+> 📖 面向**使用方**的完整分步指南见 [doc/用户安装指南.md](doc/用户安装指南.md) —— 覆盖
+> **源码方式**（clone + 本地构建）与 **pnpm 方式**（本地 checkout / tarball / git / npm）两类安装。
 
-已发布到 npm（`dsh-messager`）。DSH 环境已装的用户直接执行：
+**正式安装只需一步**（host 端 + 浏览器 client 端都会生效，之后直接 `dsh web` 启动即可，
+**不需要** `--patch`）：
 
 ```sh
-dsh plugin --profile web add dsh-messager
-dsh web     # 或 dsh --profile web
-```
-
-> 尚未预装 `dsh` CLI 时，用 npx 现拉官方发行版执行（无需先全局装 dsh）：
-> ```sh
-> npx -p @deepseek-ai/dsh dsh plugin --profile web add dsh-messager
-> npx -p @deepseek-ai/dsh dsh web
-> ```
-> npm 包已含构建产物 `lib/`，安装无需构建授权。
-> *The npm package ships prebuilt `lib/`, so no build-approval is needed.*
-
-### 方式二：源码（开发 / 修改代码）/ *From source*
-
-```sh
-git clone https://github.com/ly6170/dsh-messager.git
-cd dsh-messager
-
+# 在插件仓库构建产物
 pnpm install
 pnpm build
 
-npx -p @deepseek-ai/dsh dsh plugin --profile web add ./
-npx -p @deepseek-ai/dsh dsh web
-```
-
-> 使用方分步指南（源码 / pnpm 方式）见 [doc/用户安装指南.md](doc/用户安装指南.md)。
-> *Step-by-step guide: [doc/用户安装指南.md](doc/用户安装指南.md).*
-
-### 方式三：从 git 直接安装 / *Directly from git (needs build approval)*
-
-```sh
-npx -p @deepseek-ai/dsh dsh plugin --profile web add github:ly6170/dsh-messager
+dsh plugin --profile web add <插件路径>
+dsh web   # 或 dsh --profile web
 ```
 
-> ⚠️ git 安装拉取的是源码，需跑 `prepare` 构建。pnpm ≥ 10 默认拒绝 git 依赖的构建脚本，首次 `add` 会提示把确切的包键加入该 profile `pnpm-workspace.yaml` 的 `allowBuilds`，然后重新 `add`：
-> ```yaml
-> allowBuilds:
->   dsh-messager: true
-> ```
-
-### 验证 / Verify
-
-打开 `http://127.0.0.1:3080`，设置 → 侧边菜单出现「通知&信使」分区即安装成功；首次加载会请求浏览器通知权限。
-
----
-
-## 配置 / Configuration
-
-配置优先级：**schema 默认值 → base（该插件行的 `config:`）→ 用户层（Web 设置页/分区）**。
-
-用户层入口（同源不冲突、任一变更实时生效）：
-
-1. **设置页「通知&信使」分区**：完整字段表单，所有环境（含发行版）可用；
-2. **设置文档**：编辑 `$DSH_HOME/settings.yaml` 的 `messager:` 段（完整字段，含 dedup 节流等）；
-3. **RPC**：`settings.describe` / `settings.mutate`（host 侧可用）。
+> `pnpm install` 与 `pnpm build` 在你的插件仓库目录内执行；`<插件路径>` 替换为该目录
+> （绝对或相对路径均可）。完整的分步安装指南见 [doc/用户安装指南.md](doc/用户安装指南.md)。
+
+> - `--patch` 不是安装步骤，而是可选的**开发调试**手段（见下节「本地开发」）：
+>   它只加载 host 端、不写 profile、仅对本次启动生效。装了 bundle 之后**请勿再同时
+>   带 `--patch` 启动同一插件**（host 端会加载两份，settings 命名空间重复注册报错）。
+> - 以**源码方式运行 DSH**（从 deepseek-harness 仓库根目录）时，把上述 `dsh` 换成
+>   `pnpm dsh` 即可，命令与行为完全一致：`pnpm dsh plugin --profile web add …`、
+>   `pnpm dsh web`。profile 目录仍为 `$DSH_HOME/profiles/web`（`dsh web` 即
+>   `--profile web` 别名）。
+> - 从 git 安装时 pnpm ≥ 10 需要放行构建脚本：把 pnpm 提示的包名加入 profile 的
+>   `pnpm-workspace.yaml` 的 `allowBuilds`（见 DSH 官方 publish 教程）。
+
+### 设置分区「通知&信使」（所有环境可用）
+
+安装后 DSH 设置页左侧菜单会出现 **「通知&信使」** 分区（排在「Agent预设」下方，位置
+随已有分区动态计算，不写死）。分区内是完整的配置表单，读写经插件自身的
+webServer 路由（`/dsh-messager/config`，同源校验 + 脱敏视图）直达 host 端
+`settings` 服务 —— **不依赖 DSH 的设置白名单，发行版（npx 安装）开箱即用**，
+无需任何补丁。
+
+> 配置与 `settings.yaml` 同源（同一命名空间）：任一处变更均实时生效。
+
+## 本地开发
+
+- **host 端（快速）**：从 DSH 仓库根目录运行
+  `pnpm dsh web --patch <插件路径>/cordis.yml`，直接加载 TS 源码（HMR 生效）。
+  源码模式下的 host 经 tsx 运行，该路径无需构建即可加载。
+- **完整双运行端**：浏览器（client）端要求插件以包身份进入 Loader 才会被 clientModules
+  扫描编入 Web bundle（`--patch` 的文件路径入口不会被扫描），因此完整开发请安装到 profile：
+  ```sh
+  dsh plugin --profile web add <插件路径>   # 源码模式：pnpm dsh plugin ...
+  pnpm dsh web   # 从 DSH 源码仓库运行
+  ```
+  `plugin add` 后需要**重启** `pnpm dsh web`（clientModules 启动时扫描，运行中的实例
+  不会热加入新 bundle）。修改 client 端代码后在自己的仓库重新 `pnpm run build:client`
+  并刷新页面即可（bundle 带 rev hash 会重新拉取；DSH 仓库的 `dev:web` watcher 只盯
+  workspace 内的 client 插件，不盯外部插件）。
+
+浏览器通知需要用户授予权限：首次加载插件时若权限为 `default` 会自动请求一次；
+被拒绝时浏览器通道静默降级（其余通道不受影响），可在浏览器站点设置中重新授权。
+
+## 配置
+
+配置优先级：**schema 默认值 → base（该插件行的 `config:`）→ 用户层（Web 设置页）**。
+host 端把 Loader config 注册为 settings 命名空间 `messager` 的 base 层，因此：
+- base 的写法按使用方式不同：dev 调试写在 `cordis.yml`（patch 覆盖层）里该行的
+  `config:`；正式安装写在 **profile 的 `cordis.patch.yml`** 里按 `id: messager`
+  覆盖该行，或直接改 bundle 包内的 `cordis.patch.yml`；
+- 用户层三处入口，**同源不冲突、任一处变更均实时生效**（host 端 `watch` 重建通道；
+  client 端经 `settings/document-updated` 失效重拉）：
+  1. **设置页分区**：设置 →「通知&信使」分区（完整字段表单，所有环境可用）；
+  2. **设置文档**：直接编辑 `$DSH_HOME/settings.yaml` 的 `messager:` 段（完整字段，
+     含 dedup 节流等表单未展示的项）；
+  3. **RPC**：settings.describe / settings.mutate（host 侧可用；Web 端白名单不影响本插件
+     的分区，因为分区走插件自己的配置路由）。
+
+> 配置读写链路：设置分区 → `GET/POST /dsh-messager/config`（webServer 路由，同源校验）
+> → host 端 `settings` 服务（describe 脱敏视图 / mutate 逐字段 ops）→ settings.yaml。
+> 写后 `settings/document-updated` 事件（DSH 内置转发）驱动前端刷新。
+>
+> 🌐 **国际化**：分区菜单与表单文案随 DSH 设置的语言切换（中文 / English），
+> 字典注册在 `ctx.locale`（zh/en 键集一致，缺失键 fail loud 显示键名）。
 
 | 字段 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
-| `triggers.interaction` | boolean | `true` | 需要交互时通知 |
+| `triggers.interaction` | boolean | `true` | 需要交互时通知（审批/提问/计划待审） |
 | `triggers.completed` | boolean | `true` | 任务完成时通知 |
 | `triggers.error` | boolean | `true` | 任务出错时通知 |
 | `system.enabled` | boolean | `true` | 系统通知通道 |
-| `system.icon` | string | - | 图标绝对路径（node-notifier 需要文件路径，且该文件必须存在） |
+| `system.icon` | string | - | 图标绝对路径（node-notifier 需要文件路径，**且该文件必须存在**） |
 | `system.verbosity` | `minimal\|normal\|detailed` | `normal` | 系统通知内容繁复度 |
 | `browser.enabled` | boolean | `true` | 浏览器通知通道 |
-| `browser.onlyWhenHidden` | boolean | `true` | 仅页面隐藏/未聚焦时弹 |
+| `browser.icon` | string | - | 图标 URL 或 data URL |
+| `browser.onlyWhenHidden` | boolean | `true` | 仅页面隐藏/未聚焦时弹（看着界面不打扰） |
 | `browser.verbosity` | `minimal\|normal\|detailed` | `normal` | 浏览器通知内容繁复度 |
 | `feishu.enabled` | boolean | `false` | 飞书机器人（webhook）通道 |
 | `feishu.webhookUrl` | string | - | 自定义机器人 webhook 地址 |
 | `feishu.secret` | string（secret） | - | 签名密钥（机器人「安全设置-签名校验」） |
 | `feishu.timeoutMs` | number | `5000` | 单次请求超时 |
 | `feishu.verbosity` | `minimal\|normal\|detailed` | `normal` | 卡片内容繁复度 |
-| `dedup.interactionCooldownMs` | number | `10000` | 同会话同触发冷却 |
-| `dedup.completedDebounceMs` | number | `1000` | 完成通知防抖 |
-| `dedup.perChannelPerMinute` | number | `20` | 每通道每分钟上限 |
-| `message.titlePrefix` | string | - | 标题前缀 |
+| `wecom.enabled` | boolean | `false` | 企业微信群机器人（webhook）通道 |
+| `wecom.webhookUrl` | string | - | 群机器人 webhook 地址（含 `?key=`） |
+| `wecom.secret` | string（secret） | - | 加签密钥（「安全设置-加签」，HMAC-SHA256，无需 URL 编码） |
+| `wecom.timeoutMs` | number | `5000` | 单次请求超时 |
+| `wecom.verbosity` | `minimal\|normal\|detailed` | `normal` | 消息内容繁复度 |
+| `discord.enabled` | boolean | `false` | Discord 通道（webhook） |
+| `discord.webhookUrl` | string | - | Discord webhook 地址（`.../api/webhooks/<id>/<token>`） |
+| `discord.timeoutMs` | number | `5000` | 单次请求超时 |
+| `discord.verbosity` | `minimal\|normal\|detailed` | `normal` | embed 内容繁复度 |
+| `dingtalk.enabled` | boolean | `false` | 钉钉自定义机器人（webhook）通道 |
+| `dingtalk.webhookUrl` | string | - | 自定义机器人 webhook 地址（含 `?access_token=`） |
+| `dingtalk.secret` | string（secret） | - | 加签密钥（「安全设置-加签」，HMAC-SHA256 + URL 编码） |
+| `dingtalk.timeoutMs` | number | `5000` | 单次请求超时 |
+| `dingtalk.verbosity` | `minimal\|normal\|detailed` | `normal` | 卡片内容繁复度 |
+| `telegram.enabled` | boolean | `false` | Telegram 通道（Bot API） |
+| `telegram.botToken` | string（secret） | - | Bot Token（@BotFather 获取） |
+| `telegram.chatId` | string | - | 接收 chat_id（数字 ID 或 `@频道用户名`） |
+| `telegram.timeoutMs` | number | `5000` | 单次请求超时 |
+| `telegram.verbosity` | `minimal\|normal\|detailed` | `normal` | 消息内容繁复度 |
+| `dedup.interactionCooldownMs` | number | `10000` | 同会话同触发冷却（也用于跨标签去重窗口） |
+| `dedup.completedDebounceMs` | number | `1000` | 完成通知防抖（等待 turn/end 原因、合并边界） |
+| `dedup.perChannelPerMinute` | number | `20` | 每通道每分钟上限（防第三方限流/刷屏） |
+| `message.titlePrefix` | string | - | 标题前缀，如 `[DSH]` |
 | `message.includeSessionTitle` | boolean | `true` | 正文附带会话标题 |
-| `message.guiUrl` | string | `http://127.0.0.1:3080` | 通知「打开」链接目标 |
-
-内容繁复度：`minimal` 只有标题；`normal` 增加会话标题 / 工具名 / 结束原因 / 错误摘要；`detailed` 再增加 turn/step、审批原因与 GUI 链接。
-
----
+| `message.guiUrl` | string | `http://127.0.0.1:3080` | 通知「打开」链接/按钮目标 |
 
-## 设置分区「通知&信使」/ *Settings section*
+内容繁复度：`minimal` 只有标题；`normal` 增加会话标题/工具名/结束原因/错误摘要；
+`detailed` 再增加 turn/step、审批原因与 GUI 链接。
 
-安装后 DSH 设置页左侧菜单出现 **「通知&信使」** 分区，内含完整配置表单。读写经插件自身的 webServer 路由（`/dsh-messager/config`，同源校验 + 脱敏视图）直达 host 端 `settings` 服务——**不依赖 DSH 设置白名单，发行版（npx/npm 安装）开箱即用，无需任何补丁**。
+## 触发信号（事件 → 通知映射）
 
-> 配置与 `settings.yaml` 同源（同一命名空间），任一处变更均实时生效。
-> *Internationalized: the section menu and form follow the DSH display language (简体中文 / English).*
-
----
-
-## 触发信号 / Trigger signals
-
-| 触发 | host 端（system/feishu） | client 端（browser） |
+| 触发 | host 端（system/feishu/wecom/discord/dingtalk/telegram） | client 端（browser） |
 | --- | --- | --- |
 | 审批 | `session/event` `approval/asked` | 摘要 `pendingInteraction==='approval'` 出现 |
 | 提问/计划待审 | `session/event` `tool/call`（`ask_user_question`） | `pendingInteraction==='question'/'plan-review'` 出现 |
 | 任务完成 | `agent/status` running→idle（仅根会话）＋`turn/end` 原因 | 摘要 `running:true→false` 且非当前会话 |
 | 任务出错 | `agent/error` | -（host 端覆盖） |
 
-> **分叉会话（fork）处理**：完成通知只对真正的子代理（`origin === 'subagent'`）排除，分叉会话（`sessions.fork`，其 `parentSession` 指向源会话但 `origin` 为空）视为顶层会话，照常通知。
-
----
-
-## 通道扩展 / Channel extension
+## 通道扩展
 
-实现 `NotifyChannel` 接口并在 `src/index.ts` 的 `buildChannels()` 注册即可接入新通道：
+新增第三方通道（钉钉/企业微信/Telegram…）实现 `NotifyChannel` 接口并在
+`src/index.ts` 的 `buildChannels()` 注册即可：
 
 ```ts
 export interface NotifyChannel {
@@ -168,13 +168,11 @@ export interface NotifyChannel {
 }
 ```
 
----
-
-## 项目结构 / Project structure
+## 项目结构
 
 ```
 dsh-messager/
-├── package.json          # dsh.bundle + dsh.client 双声明；exports["./client"]；publishConfig/prepublishOnly
+├── package.json          # dsh.bundle + dsh.client 双声明；exports["./client"]
 ├── tsconfig.json         # host 端（Node）
 ├── tsconfig.client.json  # client 端声明输出（lib/types/client）
 ├── tsdown.config.ts      # client bundle（__ModuleLoader__.load 契约）
@@ -190,7 +188,7 @@ dsh-messager/
 │   ├── notify.ts         # 调度：过滤/冷却/防抖/限流 + NotifyChannel 接口
 │   ├── templates.ts      # verbosity 模板渲染（纯函数）
 │   ├── settings.ts       # settings 命名空间注册（base = Loader config）
-│   ├── channels/         # system（node-notifier）、feishu（webhook+签名）
+│   ├── channels/         # system（node-notifier）、feishu/wecom/discord/dingtalk/telegram（webhook/Bot API+签名）
 │   └── client/           # 浏览器端：sessions diff、Notification、设置分区、配置同步
 │       ├── index.ts      # 分区注册（动态 order）+ 浏览器通知 + 配置路由访问器
 │       ├── section.tsx   # 设置页「通知&信使」分区组件
@@ -200,42 +198,43 @@ dsh-messager/
 │       ├── locales.ts    # zh/en 字典（ctx.locale 注册）
 │       ├── config.ts     # 浏览器通知的配置句柄（走配置路由）
 │       └── diff.ts       # 会话摘要 diff（纯函数）
-└── tests/                # vitest 单元测试
+└── tests/                # vitest 单元测试（126 个）
 ```
 
----
-
-## 开发与测试 / Development
+## 测试
 
 ```sh
-pnpm install
-pnpm test       # 单元测试：信号/模板/调度/飞书签名/配置解析/client diff/配置路由/fetch scope/字典一致性
-pnpm typecheck  # host 端类型检查
+pnpm test       # 126 个单元测试：信号提取/模板/调度/各通道签名与载荷/配置解析/client diff/配置路由/fetch scope/字典一致性/表单门控
+pnpm typecheck  # host 端
 pnpm build      # host tsc + client 声明 + client bundle（lib/）
 ```
 
----
-
-## 已知边界 / Known limitations
+## 已知边界
 
-- 浏览器通知需站点权限；`onlyWhenHidden=false` 时页面可见也会弹；
-- 多标签页经 localStorage 冷却去重，不同浏览器各自通知；
-- 子代理结束不触发完成通知（仅根会话）——分叉会话视为顶层且会通知；
-- 通道失败（webhook 超时、toast 不可用）只记日志，不影响其他通道与插件运行；
-- 完成/交互去重状态为内存态，DSH 重启后重置。
+- 浏览器通知需站点权限；`onlyWhenHidden=false` 时页面可见也会弹。
+- 多标签页经 localStorage 冷却去重；不同浏览器各自通知。
+- 子代理结束不触发完成通知（仅根会话），避免噪音。
+- 通道失败（webhook 超时、toast 不可用）只记日志，不影响其他通道与插件运行。
+- 完成/交互的去重状态为内存态，DSH 重启后重置（可接受）。
 
 ### 系统通知（node-notifier）跨平台前提
 
-`node-notifier` 在三个平台调用完全不同的底层程序：
+`node-notifier` 在三个平台调用**完全不同的底层程序**，平台差异如下：
 
 | 平台 | 底层 | 前提条件 / 差异 |
 | --- | --- | --- |
 | Windows | PowerShell ToastNotification | 内建，无需额外安装；`sound` 仅在 Windows 有可靠映射 |
-| macOS | terminal-notifier | 首次使用需联网下载第三方二进制，且需登录图形会话（Dock 存在）；`sound` 不生效 |
-| Linux | notify-send（libnotify） | 需安装 `libnotify-bin`，并有运行中的通知守护进程（GNOME Shell / Plasma / mako / dunst 等）；`sound` 不生效 |
+| macOS | terminal-notifier | 首次使用需**联网下载**第三方二进制，且需登录图形会话（Dock 存在）；`sound` 不生效 |
+| Linux | notify-send（libnotify） | 需安装 `libnotify-bin`，并有一个**运行中的通知守护进程**（GNOME Shell / Plasma / mako / dunst 等）；`sound` 不生效 |
 
----
+- **图标**：`system.icon` 需是**存在的文件路径**。Windows 对缺失路径多会静默降级，但
+  Linux/macOS 可能直接报错，故通道层已做存在性校验，无效时降级为不带图标。
+- **环境差异不是插件 bug**：Linux 若缺通知守护进程、macOS 若无法联网下载
+  terminal-notifier 或不在图形会话中，通知可能不弹出或静默失败——此时请先排查上述前提，
+  而非插件；失败时调度层会 `logWarn` 记录具体错误。
 
-## 许可 / License
+## 后续规划
 
-[MIT](LICENSE) © [ly6170](https://github.com/ly6170)
+- 第三方通道扩展：邮件
+- 触发扩展：后台 job 完成、goal 轮次完成
+- 通知历史、按会话静音、勿扰时段

package/cordis.patch.yml

@@ -9,3 +9,16 @@
       #   feishu:
       #     enabled: true
       #     webhookUrl: 'https://open.feishu.cn/open-apis/bot/v2/hook/<token>'
+      #   wecom:
+      #     enabled: false
+      #     webhookUrl: 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=<key>'
+      #   discord:
+      #     enabled: false
+      #     webhookUrl: 'https://discord.com/api/webhooks/<id>/<token>'
+      #   dingtalk:
+      #     enabled: false
+      #     webhookUrl: 'https://oapi.dingtalk.com/robot/send?access_token=<token>'
+      #   telegram:
+      #     enabled: false
+      #     botToken: ''
+      #     chatId: ''

package/lib/channels/dingtalk.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 钉钉自定义机器人通道（webhook）：actionCard 卡片（标题 + markdown 正文 + 打开按钮），host 端投递。
+ *
+ * 可选加签（机器人「安全设置-加签」）：
+ *   string_to_sign = `${timestamp}\n${secret}`
+ *   sign = urlEncode(base64(HmacSHA256(string_to_sign, key=secret)))   // 必须 URL 编码
+ * 追加为查询参数 &timestamp=<ts>&sign=<sign>（与企微不同：企微不需要 urlEncode）。
+ * 成功判定：HTTP 2xx 且响应 errcode === 0。
+ * 注意：actionCard 的 title 限 20 字符，超出会被平台拒绝，需截断。
+ */
+import type { NotifyChannel, NotificationPayload } from '../notify.js';
+export interface DingtalkChannelOptions {
+    webhookUrl: string;
+    /** 加签密钥（机器人「安全设置-加签」），配置后按钉钉规范签名。 */
+    secret?: string;
+    timeoutMs: number;
+}
+/** 钉钉 actionCard 载荷。 */
+export interface DingtalkActionCardPayload {
+    msgtype: 'actionCard';
+    actionCard: {
+        title: string;
+        text: string;
+        btnOrientation: '0';
+        singleTitle: string;
+        singleURL: string;
+    };
+}
+/** 构建钉钉 actionCard 载荷（纯函数；title 限 20 字符；正文空时退化为链接）。 */
+export declare function buildDingtalkPayload(payload: NotificationPayload): DingtalkActionCardPayload;
+/**
+ * 钉钉加签：
+ *   sign = urlEncode(base64(HmacSHA256(key=secret, msg=`${timestamp}\n${secret}`)))
+ * @returns 追加了 timestamp/sign（URL 编码后）查询参数的完整 URL。
+ */
+export declare function signDingtalkUrl(webhookUrl: string, secret: string, timestamp: string): string;
+export declare function createDingtalkChannel(options: DingtalkChannelOptions): NotifyChannel;
+//# sourceMappingURL=dingtalk.d.ts.map

package/lib/channels/dingtalk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dingtalk.d.ts","sourceRoot":"","sources":["../../src/channels/dingtalk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAEtE,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAA;IAClB,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,wBAAwB;AACxB,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,YAAY,CAAA;IACrB,UAAU,EAAE;QACV,KAAK,EAAE,MAAM,CAAA;QACb,IAAI,EAAE,MAAM,CAAA;QACZ,cAAc,EAAE,GAAG,CAAA;QACnB,WAAW,EAAE,MAAM,CAAA;QACnB,SAAS,EAAE,MAAM,CAAA;KAClB,CAAA;CACF;AAED,uDAAuD;AACvD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,yBAAyB,CAY5F;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAM7F;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,aAAa,CAoBpF"}

package/lib/channels/dingtalk.js

@@ -0,0 +1,60 @@
+/**
+ * 钉钉自定义机器人通道（webhook）：actionCard 卡片（标题 + markdown 正文 + 打开按钮），host 端投递。
+ *
+ * 可选加签（机器人「安全设置-加签」）：
+ *   string_to_sign = `${timestamp}\n${secret}`
+ *   sign = urlEncode(base64(HmacSHA256(string_to_sign, key=secret)))   // 必须 URL 编码
+ * 追加为查询参数 &timestamp=<ts>&sign=<sign>（与企微不同：企微不需要 urlEncode）。
+ * 成功判定：HTTP 2xx 且响应 errcode === 0。
+ * 注意：actionCard 的 title 限 20 字符，超出会被平台拒绝，需截断。
+ */
+import { createHmac } from 'node:crypto';
+/** 构建钉钉 actionCard 载荷（纯函数；title 限 20 字符；正文空时退化为链接）。 */
+export function buildDingtalkPayload(payload) {
+    const link = `[打开 DSH](${payload.url})`;
+    return {
+        msgtype: 'actionCard',
+        actionCard: {
+            title: payload.title.slice(0, 20),
+            text: payload.body === '' ? link : `${payload.body}\n\n${link}`,
+            btnOrientation: '0',
+            singleTitle: '打开 DSH',
+            singleURL: payload.url,
+        },
+    };
+}
+/**
+ * 钉钉加签：
+ *   sign = urlEncode(base64(HmacSHA256(key=secret, msg=`${timestamp}\n${secret}`)))
+ * @returns 追加了 timestamp/sign（URL 编码后）查询参数的完整 URL。
+ */
+export function signDingtalkUrl(webhookUrl, secret, timestamp) {
+    const stringToSign = `${timestamp}\n${secret}`;
+    const sign = createHmac('sha256', secret).update(stringToSign).digest('base64');
+    const encoded = encodeURIComponent(sign);
+    const separator = webhookUrl.includes('?') ? '&' : '?';
+    return `${webhookUrl}${separator}timestamp=${timestamp}&sign=${encoded}`;
+}
+export function createDingtalkChannel(options) {
+    return {
+        id: 'dingtalk',
+        async send(payload) {
+            const url = options.secret === undefined
+                ? options.webhookUrl
+                : signDingtalkUrl(options.webhookUrl, options.secret, String(Math.floor(Date.now() / 1000)));
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(buildDingtalkPayload(payload)),
+                signal: AbortSignal.timeout(options.timeoutMs),
+            });
+            if (!response.ok)
+                throw new Error(`dingtalk webhook responded ${response.status}`);
+            const result = (await response.json().catch(() => undefined));
+            if (result !== undefined && result.errcode !== 0) {
+                throw new Error(`dingtalk webhook rejected: errcode=${String(result.errcode)} errmsg=${String(result.errmsg)}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=dingtalk.js.map

package/lib/channels/dingtalk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dingtalk.js","sourceRoot":"","sources":["../../src/channels/dingtalk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAsBxC,uDAAuD;AACvD,MAAM,UAAU,oBAAoB,CAAC,OAA4B;IAC/D,MAAM,IAAI,GAAG,YAAY,OAAO,CAAC,GAAG,GAAG,CAAA;IACvC,OAAO;QACL,OAAO,EAAE,YAAY;QACrB,UAAU,EAAE;YACV,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;YACjC,IAAI,EAAE,OAAO,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,OAAO,IAAI,EAAE;YAC/D,cAAc,EAAE,GAAG;YACnB,WAAW,EAAE,QAAQ;YACrB,SAAS,EAAE,OAAO,CAAC,GAAG;SACvB;KACF,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkB,EAAE,MAAc,EAAE,SAAiB;IACnF,MAAM,YAAY,GAAG,GAAG,SAAS,KAAK,MAAM,EAAE,CAAA;IAC9C,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IAC/E,MAAM,OAAO,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAA;IACxC,MAAM,SAAS,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAA;IACtD,OAAO,GAAG,UAAU,GAAG,SAAS,aAAa,SAAS,SAAS,OAAO,EAAE,CAAA;AAC1E,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,OAA+B;IACnE,OAAO;QACL,EAAE,EAAE,UAAU;QACd,KAAK,CAAC,IAAI,CAAC,OAA4B;YACrC,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,KAAK,SAAS;gBACtC,CAAC,CAAC,OAAO,CAAC,UAAU;gBACpB,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;YAC9F,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAChC,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;gBACnD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;aAC/C,CAAC,CAAA;YACF,IAAI,CAAC,QAAQ,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;YAClF,MAAM,MAAM,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAsD,CAAA;YAClH,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;gBACjD,MAAM,IAAI,KAAK,CAAC,sCAAsC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;YACjH,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/lib/channels/discord.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Discord 通道（webhook）：embed 卡片（标题/正文/链接 + kind 颜色），host 端投递。
+ *
+ * 成功判定：任意 2xx（Discord 通常返回 204 No Content，无 body 可解析，
+ * 因此与飞书/企微/钉钉的 errcode 判定不同，不解析响应 JSON）。
+ * 限制守卫：title ≤ 256、description ≤ 4096（超限会被 Discord 400 拒绝）。
+ */
+import type { NotifyChannel, NotificationPayload } from '../notify.js';
+export interface DiscordChannelOptions {
+    webhookUrl: string;
+    timeoutMs: number;
+}
+/** kind → embed 颜色（interaction 橙 / completed 绿 / error 红）。 */
+export declare function embedColorOf(kind: NotificationPayload['kind']): number;
+/** Discord webhook 载荷（embed 单卡片）。 */
+export interface DiscordEmbedPayload {
+    username: string;
+    embeds: Array<{
+        title: string;
+        description?: string;
+        url: string;
+        color: number;
+    }>;
+}
+/** 构建 Discord embed 载荷（纯函数；title ≤ 256、description ≤ 4096）。 */
+export declare function buildDiscordPayload(payload: NotificationPayload): DiscordEmbedPayload;
+export declare function createDiscordChannel(options: DiscordChannelOptions): NotifyChannel;
+//# sourceMappingURL=discord.d.ts.map

package/lib/channels/discord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discord.d.ts","sourceRoot":"","sources":["../../src/channels/discord.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAEtE,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAAG,MAAM,CAMtE;AAED,qCAAqC;AACrC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,KAAK,CAAC;QACZ,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,MAAM,CAAA;KACd,CAAC,CAAA;CACH;AAED,+DAA+D;AAC/D,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,mBAAmB,GAAG,mBAAmB,CAUrF;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,aAAa,CAclF"}

package/lib/channels/discord.js

@@ -0,0 +1,44 @@
+/**
+ * Discord 通道（webhook）：embed 卡片（标题/正文/链接 + kind 颜色），host 端投递。
+ *
+ * 成功判定：任意 2xx（Discord 通常返回 204 No Content，无 body 可解析，
+ * 因此与飞书/企微/钉钉的 errcode 判定不同，不解析响应 JSON）。
+ * 限制守卫：title ≤ 256、description ≤ 4096（超限会被 Discord 400 拒绝）。
+ */
+/** kind → embed 颜色（interaction 橙 / completed 绿 / error 红）。 */
+export function embedColorOf(kind) {
+    switch (kind) {
+        case 'interaction': return 0xE67E22;
+        case 'completed': return 0x2ECC71;
+        case 'error': return 0xE74C3C;
+    }
+}
+/** 构建 Discord embed 载荷（纯函数；title ≤ 256、description ≤ 4096）。 */
+export function buildDiscordPayload(payload) {
+    return {
+        username: 'DSH',
+        embeds: [{
+                title: payload.title.slice(0, 256),
+                ...(payload.body === '' ? {} : { description: payload.body.slice(0, 4096) }),
+                url: payload.url,
+                color: embedColorOf(payload.kind),
+            }],
+    };
+}
+export function createDiscordChannel(options) {
+    return {
+        id: 'discord',
+        async send(payload) {
+            const response = await fetch(options.webhookUrl, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(buildDiscordPayload(payload)),
+                signal: AbortSignal.timeout(options.timeoutMs),
+            });
+            if (!response.ok)
+                throw new Error(`discord webhook responded ${response.status}`);
+            // 204 No Content：成功即返回，不读取 body
+        },
+    };
+}
+//# sourceMappingURL=discord.js.map

package/lib/channels/discord.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discord.js","sourceRoot":"","sources":["../../src/channels/discord.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,8DAA8D;AAC9D,MAAM,UAAU,YAAY,CAAC,IAAiC;IAC5D,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,aAAa,CAAC,CAAC,OAAO,QAAQ,CAAA;QACnC,KAAK,WAAW,CAAC,CAAC,OAAO,QAAQ,CAAA;QACjC,KAAK,OAAO,CAAC,CAAC,OAAO,QAAQ,CAAA;IAC/B,CAAC;AACH,CAAC;AAaD,+DAA+D;AAC/D,MAAM,UAAU,mBAAmB,CAAC,OAA4B;IAC9D,OAAO;QACL,QAAQ,EAAE,KAAK;QACf,MAAM,EAAE,CAAC;gBACP,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;gBAClC,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC;gBAC5E,GAAG,EAAE,OAAO,CAAC,GAAG;gBAChB,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC;aAClC,CAAC;KACH,CAAA;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAA8B;IACjE,OAAO;QACL,EAAE,EAAE,SAAS;QACb,KAAK,CAAC,IAAI,CAAC,OAA4B;YACrC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE;gBAC/C,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;gBAClD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;aAC/C,CAAC,CAAA;YACF,IAAI,CAAC,QAAQ,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;YACjF,gCAAgC;QAClC,CAAC;KACF,CAAA;AACH,CAAC"}

package/lib/channels/telegram.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Telegram 通道（Bot API）：sendMessage（HTML parse_mode），host 端投递。
+ *
+ * 端点 = https://api.telegram.org/bot<token>/sendMessage（token 即凭证，走 URL 路径）。
+ * 成功判定：HTTP 2xx 且响应 ok === true。
+ * HTML parse_mode 必须转义 & < > " '，否则非法标签会导致 API 400。
+ * 限制守卫：text ≤ 4096 字符。
+ */
+import type { NotifyChannel, NotificationPayload } from '../notify.js';
+export interface TelegramChannelOptions {
+    botToken: string;
+    /** 接收 chat_id（数字 ID 或 @频道用户名）。 */
+    chatId: string;
+    timeoutMs: number;
+}
+export declare const TELEGRAM_API_BASE = "https://api.telegram.org";
+/** HTML 转义（纯函数）：& < > " '。 */
+export declare function escapeHtml(text: string): string;
+/** sendMessage 载荷。 */
+export interface TelegramSendPayload {
+    chat_id: string;
+    text: string;
+    parse_mode: 'HTML';
+    link_preview_options: {
+        is_disabled: boolean;
+    };
+}
+/** 构建 sendMessage 载荷（纯函数；text ≤ 4096 兜底）。 */
+export declare function buildTelegramPayload(payload: NotificationPayload, chatId: string): TelegramSendPayload;
+export declare function createTelegramChannel(options: TelegramChannelOptions): NotifyChannel;
+//# sourceMappingURL=telegram.d.ts.map

package/lib/channels/telegram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.d.ts","sourceRoot":"","sources":["../../src/channels/telegram.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAEtE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAA;IAChB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,eAAO,MAAM,iBAAiB,6BAA6B,CAAA;AAE3D,8BAA8B;AAC9B,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO/C;AAED,sBAAsB;AACtB,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,oBAAoB,EAAE;QAAE,WAAW,EAAE,OAAO,CAAA;KAAE,CAAA;CAC/C;AAED,6CAA6C;AAC7C,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,GAAG,mBAAmB,CAUtG;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,aAAa,CAkBpF"}