Telegram 桥接 qschen86/dsh-telegram-bridge

dsh-telegram-bridge

DSH host 插件：通过 Telegram 机器人推送通知，并支持在 Telegram 上回复继续推进会话。

功能

- 会话完成通知：agent 完成一轮（回到 idle）后，向 Telegram 发送通知。所有通知统一模板，按固定字段顺序：侧边栏 icon 名称（工作区标题，如「日历待办」）→ 会话 id → 会话名（session/title 事件）→ 通知类型（✅ 会话结束 / 🔐 需要授权 / ❓ 需要确认 / ⏰ 日程提醒 / ℹ️ 其他）→ 通知内容概要；回复该消息即可继续会话。
已通知的回合基线持久化在 state.json（宿主重启不丢失）；发送失败不推进基线，下次 idle 自动重试，避免静默丢通知。首次见到某会话 idle 时：若其最近活动晚于桥接启动时刻（新建会话、或重启后恢复的会话），直接推送并建立基线（新会话的第一轮完成也会通知）；仅当会话活动全部早于桥接启动（宿主重启加载的历史会话）时才只记基线不推送，避免补发旧回合的噪音。其他插件经 telegramBridge.sendAll(text, {type, sessionId}) 发送时可带类型前缀并让回复直达对应会话。
- 需要确认通知：
- ask_user_question（模型请求确认）→ 推送问题与选项，在 Telegram 回复选项编号 / 文字 / custom: 内容 即可回答，agent 自动继续。
- 权限审批（sandbox approval）→ 推送工具名与原因；可回复 /approve <编号> allow|deny 为会话设置自动审批策略（也可用环境变量设全局默认）。
- Telegram 消息路由（按优先级）：
1. 回复通知消息 → 直达对应会话（通知 message id → 会话 id 映射持久化在 state.json，宿主重启后依然有效；即使映射丢失，也会从被回复消息正文里的 #sess: 标签恢复）；
2. 消息正文带 #sess:<会话id> → 直达该会话；
3. 全局恰好只有一个待回答的确认问题 → 该消息视为对它的回答；
4. 应用路由（消息未携带任何 sessionId 时）：按关键词自动识别所属应用——
- 日历相关（日程/待办/提醒/会议/预约/安排/日历/todo/calendar/remind/meeting/appointment/schedule/event 等）→ 发送到日历应用的对话（dsh-calendar-todo；首次使用自动创建会话）；
- 其他消息 → 默认为对话应用（dsh-chat-app），并在其中新建一个对话（每次一条新会话）。
关键词表可扩展：DSH_TELEGRAM_CALENDAR_KEYWORDS 环境变量或 config.json calendarKeywords 数组（均与内置表合并）。

安装

dsh plugin --profile web add dsh-telegram-bridge
或使用 GitHub Release tarball：
dsh plugin --profile web add https://github.com/qschen86/dsh-telegram-bridge/releases/download/v0.1.0/dsh-telegram-bridge-0.1.0.tgz
dsh --profile web --dump-config # 验证条目已加入 bundles
重启 dsh web（host 半生效）

初始化（首次安装）

1. 在 Telegram 找 @BotFather 创建机器人，拿到 token（tg 前缀，如 123456:ABC...）。
2. 提供 token（二选一，config.json 优先）：
- 把 data/config.example.json 复制为 data/config.json，填入 botToken；或
- 设置环境变量 DSH_TELEGRAM_BOT_TOKEN（注意：环境变量需对 dsh web 进程可见—— launchd 托管时加进 plist 的 EnvironmentVariables，只写 ~/.zshrc 不生效）。
- 二者都不填时插件不激活（启动日志有警告）。
3. 重启 dsh web 后，在 Telegram 给机器人发 /start（未配置授权列表时自动注册当前 chat），再发 /status 确认桥接状态。
4. 可选环境变量：DSH_TELEGRAM_ALLOWED_CHATS（逗号分隔的 chat id，同 config.json allowedChats）、DSH_TELEGRAM_APPROVAL_DEFAULT（ask / allowed-once / rejected）、 DSH_TELEGRAM_PREFIX（命令前缀，默认 /）。

Telegram 命令

| 命令 | 说明 |
| /start | 注册当前 chat（未配置授权列表时） |
| /list | 列出会话（编号） |
| /s <编号|会话id> <内容> | 向指定会话发送消息 |
| /q <编号> <答案> | 回答指定会话的待确认问题 |
| /approve <编号> allow|deny|ask | 设置会话自动审批策略（与网页提权卡的「本会话都允许」同一个旋钮） |
| /status | 桥接状态 |
| /help | 帮助 |

回复通知消息本身即可：继续会话（完成通知）、回答问题（问题通知，支持选项编号 / 文字 / custom: 内容）、allow / deny 审批（审批通知）。如果回复的是问题通知但该确认已失效（已在网页回答，或会话被中断/取消），会收到明确提示而不会把答案当作普通消息发进会话。

说明

- 通过 Telegram Bot API getUpdates 长轮询收发，无需公网地址 / webhook。
- 数据（授权 chat、审批策略、通知消息 → 会话 id 映射）持久化在插件 data/state.json（映射最多保留最近 500 条）。其中审批策略只有经 /approve 设置的才落盘；网页提权卡「本会话都允许」记的那份只存活于 host 进程内存，重启即收回（回到逐次确认），读取顺序固定为 内存 → approvalPrefs → 默认策略。
- 自动放行的生效方式：在引擎把这张卡端给人之前，先把 approval/decided 写进会话日志 —— api-proxy 的应答器发现这条 ask 已有决定就让路，本插件的应答器再返回日志里那个结果，卡根本不会弹。这个 append 不能在 approval/asked 的观察者里就地做（dsh-session 拒绝同一次发布中的重入 append，异常还会被引擎吞成一行 warn），所以由 autoDecideApproval 推到微任务里落。v0.3.0 及更早这条是死代码：策略记上了、下一条照样问人，/approve … allow 从未真正放行过。
- 会话 id 以 #sess:<id> 标签内嵌在通知消息中；回复消息时会自动用它恢复路由，即使映射表因重启或清理而缺失。

配置

data/config.json（模板见 data/config.example.json）：

| 字段 | 默认 | 说明 |
| botToken | 空 | @BotFather 创建的 token；优先于环境变量 DSH_TELEGRAM_BOT_TOKEN |
| allowedChats | [] | 授权 chat id 列表。空 = 不限制：任何 chat 发 /start 即自动授权并持久化到 data/state.json；非空 = 仅列表内的 chat 可交互。想只给自己用就填自己的 chat id |
| calendarKeywords | 内置表 | 应用路由的日历关键词（与内置表合并；也可用环境变量 DSH_TELEGRAM_CALENDAR_KEYWORDS，逗号分隔） |

环境变量方式：DSH_TELEGRAM_BOT_TOKEN / DSH_TELEGRAM_ALLOWED_CHATS / DSH_TELEGRAM_APPROVAL_DEFAULT / DSH_TELEGRAM_PREFIX。二者都不填时插件不激活。