Telegram 通知 RGarrido03/dsh-telegram-notify

dsh-telegram-notify

给 DeepSeek Harness 用的单向 Telegram 通知。
你不在 DSH 界面旁边时，机器人会告诉你：一轮对话结束了、失败了、正在等回答、有方案待审、或者需要批准某个工具。它从不读取 Telegram 更新，所以机器人只发不收。

插件自带 Settings → Telegram 页面：粘贴 bot token，填入 chat id，勾选要通知的事件。不用改 YAML。

事件

| 事件 | 消息 | 开关 |
| 一轮对话完成 | ✅ Turn complete | notifyTurnComplete |
| 一轮对话失败、被阻塞，或触到 token 上限 | ❌ / ⚠️ | notifyTurnError |
| 一轮对话被取消 | ⏹ Turn cancelled | notifyTurnAborted（默认关闭） |
| ask_user_question 等待回答 | ❓ Waiting for your input | notifyQuestions |
| 有方案提交审批（exit_plan_mode / 方案评审问题） | 📋 Plan ready for approval | notifyPlanReviews |
| 工具审批等待人工处理 | 🔐 Approval needed | notifyApprovals |

子代理会话会被忽略。审批和提问通知会等 400 ms，如果对应的决定或工具结果先到，通知就取消。所以秒拒的审批、秒失败的工具调用不会打扰你。

消息发出后不管结果。Telegram 出故障只记一条警告，绝不会让智能体的一轮对话失败、卡住或变慢。

安装

dsh plugin --profile web add dsh-telegram-notify

如果你的应用跑的是 desktop 配置档，改用 --profile desktop。从本地检出安装（npm 发布之前），用 dsh plugin --profile web add link:$PWD。

把 "dsh-telegram-notify" 加进 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles，即可启用这个 bundle（也可以在 DSH Plugin Manager 里启用）。bundle 补丁会挂载 telegram-notify 这一行。

重启 DSH，打开 Settings → Telegram，然后：

1. 粘贴 bot token，点 Save token。它存在 DSH 凭据库里，引用名见页面显示（默认 TELEGRAM_BOT_TOKEN），绝不写进插件配置。
2. 填入 chat id，点 Save settings。
3. 勾选想要的事件，再保存一次。

获取机器人和 chat id

用 @BotFather 创建机器人，复制它的 token。
先给机器人发条消息，再找 @userinfobot 这类辅助机器人要你的数字 id。群组的话，把机器人拉进群，用群的负数 id（例如 -1001234567890）；公开频道也可以用 @channelusername。

插件只调用 sendMessage，从不调用 getUpdates，所以它无法消费发给另一个 Telegram 集成的消息。

配置参考

Settings 页面会为 telegram-notify 这一行写入配置档补丁。同样的字段仍可在 ~/.dsh/profiles/web/cordis.patch.yml 中编辑：

- id: telegram-notify
config:
chatId: "123456789"
tokenRef: TELEGRAM_BOT_TOKEN
notifyTurnComplete: true
notifyTurnError: true
notifyTurnAborted: false
notifyQuestions: true
notifyPlanReviews: true
notifyApprovals: true
silent: false

| 字段 | 默认值 | 含义 |
| chatId | ""（禁用） | 目标聊天 id，或 @channelusername。 |
| tokenRef | TELEGRAM_BOT_TOKEN | 保存 bot token 的凭据引用。 |
| token | 未设置 | 用于无头运行或一次性运行的明文 token。Settings 页面从不写入该字段；优先用 tokenRef。 |
| apiBase | https://api.telegram.org | Bot API 基础 URL；只有改用本地 Bot API 服务器时才需要修改。 |
| silent | false | 发送时不带提示音。 |
| notifyTurnComplete | true | 已完成的轮次。 |
| notifyTurnError | true | 失败、被阻塞和达到 max-token 的轮次。 |
| notifyTurnAborted | false | 已取消的轮次。 |
| notifyQuestions | true | 待回答的用户问题。 |
| notifyPlanReviews | true | 等待批准的计划。 |
| notifyApprovals | true | 待处理的工具审批。 |

Settings 页面按加载器行 id telegram-notify 绑定；如果把插件挂到别的 id 下，页面会报告该命名空间不可用。页面上可编辑的字段是 schemastery 的 volatile 配置，因此保存后直接作用于运行中的插件，无需重启。消息是纯文本（不设 parse mode），所以模型输出不会破坏格式，也无法注入标记；文本会截断到 Telegram 的 4096 字符上限。

如果你还运行了双向 Telegram 桥接（例如 dsh-im），该桥接处理的会话会自己产生回复，本插件还会额外为它们发送轮次通知。如果觉得太吵，可以停用桥接，或关掉轮次相关的开关。

工作原理

Host 部分订阅 session/event。它从 turn/end、tool/call（ask_user_question、exit_plan_mode）、approval/asked/approval/decided、assistant/message、user/message 和 session/title 格式化消息，再用 fetch 发送。浏览器部分注册一个 settings.section 插槽，通过 ctx.configForms 读写 telegram-notify 命名空间；token 走凭据远程。Host 插件禁用了自动生成的配置表单，因此机密字段 token 不会通过通用页面暴露。

开发

pnpm install
pnpm check # typecheck, build, node:test

源码布局：src/index.ts（Host）、src/client.ts（浏览器设置页，编译为经典 module-loader 脚本）、test/（Host 事件管线、客户端注册、服务端渲染的设置页）。没有测试会访问 Telegram；传输层测试使用本地 HTTP 桩。
首次执行 npm publish 必须用 token 认证（只有包已经存在，才能配置 trusted publishing）：

npm login
npm publish --access public

然后到 npm 上，把本仓库添加为 dsh-telegram-notify 的 trusted publisher（包设置 → Trusted publishing → GitHub Actions，工作流选 publish.yml）。之后的版本在发布 GitHub release 时，会通过 .github/workflows/publish.yml 里的 OIDC 完成发布。

许可证

MIT