前言¶
在 DeepSeek Harness（DSH）里跑长任务时，你往往不能一直盯着界面：回合结束、工具要审批、模型在等你回答，这些状态若没人提醒，就容易漏掉。邮件或自建 webhook 可以接，但配置和运维成本不低。若你已经在用 Telegram，dsh-telegram-notify 把 DSH 的关键会话事件推到指定聊天，且只发不收，不会和双向 Telegram 桥抢 getUpdates。
下面按安装、配置和事件开关说明用法；事实以 GitHub 仓库 README 为准。
这是什么¶
dsh-telegram-notify 是社区维护的 DSH 插件（维护者 RGarrido03，npm 包名 dsh-telegram-notify，当前 README 附带版本 0.2.3，MIT 许可证）。定位是 单向 Telegram 通知：离开 DSH UI 时，由 Bot 告知回合完成、失败、等待回答、计划待审或工具待审批等；插件 不读取 Telegram 更新，Bot 保持仅发送（只调用 sendMessage，不调用 getUpdates）。
插件自带 Settings → Telegram 页面：粘贴 Bot Token、填写 Chat ID、勾选要推送的事件，无需手改 YAML 即可完成常见配置。
核心功能¶
支持的通知事件¶
README 中列出的事件与对应配置开关如下（消息为纯文本，无 parse mode，正文会截断至 Telegram 4096 字符上限）：
| 场景 | 消息示意 | 配置项 | 默认 |
|---|---|---|---|
| 回合完成 | Turn complete | notifyTurnComplete |
开 |
| 回合失败、阻塞或触达 token 上限 | 错误/警告类 | notifyTurnError |
开 |
| 回合被取消 | Turn cancelled | notifyTurnAborted |
关 |
ask_user_question 等待回答 |
Waiting for your input | notifyQuestions |
开 |
计划待审批（exit_plan_mode / plan-review） |
Plan ready for approval | notifyPlanReviews |
开 |
| 工具审批等待人工 | Approval needed | notifyApprovals |
开 |
子 Agent 会话会被忽略。审批与提问类通知会等待约 400 ms，若在此之前已有对应决策或工具结果，则取消发送，避免「瞬间拒绝的审批」或「瞬间失败的工具调用」刷屏。
消息采用 fire-and-forget：Telegram 不可用时只记 warning，不会因此失败、阻塞或拖慢 Agent 回合。
设置页与凭证¶
Token 通过设置页保存后写入 DSH 凭证存储（默认引用名 TELEGRAM_BOT_TOKEN），不写在插件明文配置里。设置页字段为 schemastery volatile 配置，保存后对运行中的插件生效，一般不必重启。
Host 侧订阅 session/event，根据 turn/end、tool/call、approval/*、assistant/message 等格式化内容并用 fetch 发往 Telegram API；浏览器侧注册 settings.section，通过 ctx.configForms 读写 telegram-notify 命名空间。
安装与启用¶
Web 配置档下，安装命令为：
dsh plugin --profile web add dsh-telegram-notify
若使用 desktop 配置档，将 --profile web 换成 --profile desktop。
本地 checkout、尚未发布到 npm 时，README 给出：
dsh plugin --profile web add link:$PWD
安装后需在 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles 中加入 "dsh-telegram-notify"（也可在 DSH Plugin Manager 中启用）；bundle patch 会挂载 telegram-notify 行。
重启 DSH 后打开 Settings → Telegram，按顺序：
- 粘贴 Bot Token，点 Save token（页面会显示凭证引用名，默认
TELEGRAM_BOT_TOKEN）。 - 填写 Chat ID，点 Save settings。
- 勾选需要的事件并再次保存。
获取 Bot Token 与 Chat ID¶
通过 @BotFather 创建 Bot 并复制 Token。先给 Bot 发一条消息，再用 @userinfobot 等辅助 Bot 查询你的数字用户 ID。群组场景把 Bot 加入群后使用群的负数 ID（例如 -1001234567890）；公开频道也可填 @channelusername。
配置参考（可选 YAML）¶
设置页会写入 profile 中 telegram-notify 行的 patch；也可直接编辑 ~/.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；设置页不写此字段，优先 tokenRef |
apiBase |
https://api.telegram.org |
Bot API 基址；仅在使用本地 Bot API 服务时修改 |
silent |
false |
静默发送（无通知音） |
设置页绑定 loader 行 id telegram-notify；若用其他 id 挂载，页面会报告命名空间不可用。
适用场景与注意¶
适合：已在 Telegram 上收消息、希望 DSH 回合与交互节点有轻量提醒、且不需要通过同一 Bot 在 Telegram 里反向操控 DSH 的用户。
注意：
- 插件在 当前 DSH 进程权限 下运行，安装前请自行查看 源码 与 MIT 许可证，确认符合你的安全策略。
- 若同时运行双向 Telegram 桥（如 README 提到的
dsh-im），该桥处理的会话仍可能收到桥自身的回复，本插件还会额外发送回合类通知；觉得吵时可关闭桥或关掉对应 turn 开关。 - DSH 社区插件目录（如 SkillHub 条目）为独立生态站点，与 DeepSeek / 幻方无官方从属关系；安装命令以 README 为准，勿凭仓库名自行拼接
github:owner/repo形式。
结尾¶
dsh-telegram-notify 用单向 Telegram 把 DSH 回合完成、异常、提问、计划审批与工具审批等状态推到手机端，配置集中在 Settings → Telegram，Token 进凭证库而非明文配置。需要细节与更新时，可看目录页 SkillHub 与 GitHub：RGarrido03/dsh-telegram-notify。
