jonah791/dsh-agent-telegram

dsh-agent-telegram

一句话：把 agent 接到 Telegram 上——主人随时发消息（实时 steer，不必等整轮结束）、随时收直播与文件、随时回答 agent 的提问；发送失败的消息进 outbox 不丢。

为什么值得用：GUI 不是随时都在。这条通道让 agent 的存在与告警可达——agent 不在场时（例如冷启动自救失败、web 起来了但会话没被激活），告警需要一条比 DSH 自身更宽的外部路径才能送到人手里，Telegram 就是那条路径。同时它是可靠的：offset 至少一次语义 + pending 持久化保证重启窗口不丢消息与回复；outbox 持久化保证发送失败的消息不会蒸发；MarkdownV2 解析失败自动降级纯文本（内容必达优先于格式）。

能力（4 个工具）

| 工具 | 用途（描述取自源码，逐字） |
|------|--------------------------|
| telegram_send | 主动发送一条 Telegram 消息给主人（可靠 outbound：429 退避/重试/失败入 outbox 防丢失/4096 分片/MarkdownV2 自动降级）。plain=true 走纯文本（直播/进度播报推荐）；plain=false 走 MarkdownV2 渲染。参数：text（必需，>4096 自动分片）、plain、chat_id（缺省 = owner 白名单） |
| telegram_status | Telegram outbound 通道诊断：owner 绑定、outbox 待发队列、通道健康。发消息前可先查 |
| telegram_send_file | 发送一个本地文件给主人（可靠文件传输：自动按扩展名选 sendPhoto/sendAnimation/sendVideo/sendAudio/sendDocument；支持中文路径；单文件上限 50MB；429 退避重试）。用于把生图输出/截图/文档/音频等本地文件直发主人。参数：path（必需，本地文件绝对路径）、caption（≤1024 字符纯文本）、chat_id |
| telegram_ask | 通过 Telegram 向主人提问并等待回复（无需 GUI）。问题发到主人绑定的频道，主人回复后作为工具结果返回。questions 数组，每项含稳定 id/question/可选 header/options/multi_select；推荐项放 options 首位并标 (Recommended)。主人可回序号（单选一个/多选逗号分隔）或直接输入自定义答案；/cancel 取消。一次只应有一个活跃 telegram_ask（并发调用会报错） |

inbound（无工具面，被动工作）：

| 行为 | 说明 |
|------|------|
| 长轮询 | getUpdates（pollTimeoutMs），免公网端口/webhook；offset 处理成功才确认（至少一次语义） |
| 会话注入 | 主人消息注入主会话；主会话正在跑任务时走 steer——在下一个决策点实时插入，不用等整轮结束 |
| 等待期排队 | 会话不可用（重启窗口 / agent 未激活）期间消息入重试队列，每 2s 重试直至成功或超 retryMaxMs——不再直接丢弃 |
| 直播 | 工具调用的叙述与工具名实时推送（清洗 Markdown 符号防星号外露） |
| typing | 处理期间持续显示「正在输入…」 |
| 回复回传 | pending 持久化——哨兵重启后首个回复自动回传 |
| 命令 | /status 状态 · /ping 心跳 · /help（与 /start 同义）用法 · /sessions 会话列表 · /context 上下文压力 · /content [n] 最近消息 · /cancel 取消当前提问 |

coldstart 告警送达：本插件周期性检查 $DSH_HOME/life-core/coldstart-alert.json（coldstartWatchIntervalMs），把「我不在」的冷启动自救失败告警推给主人。判定逻辑是纯函数（src/cold-alert.ts，零 IO、时间由调用方注入），已成功推送的告警按 mtime 去重（不会重复轰炸）。

快速开始

1) 装依赖（自研插件家园 self-plugins/，在目标 profile 的 package.json 加 link 依赖）：

"dsh-agent-telegram": "link:/self-plugins/dsh-agent-telegram"

2) 构建：

cd self-plugins/dsh-agent-telegram && npm install && npm run build && npm test

3) 配置凭据与挂组合：

推荐：token 放凭据文件（不进 git），Config 留空
$DSH_HOME/.credentials.yaml:
refs:
TELEGRAM_BOT_TOKEN:

- id: agent-telegram
name: dsh-agent-telegram
config:
pollTimeoutMs: 25000
inboundEnabled: true
outboundEnabled: true
askEnabled: true

4) 30 秒验证：

① telegram_status
→ 期望：owner=未绑定 / owner=，outbox=0
② 向 bot 发任意一条消息（完成 owner 绑定；首条消息自动绑定）
③ telegram_status           → 期望：ownerBound=true
④ telegram_send { text: "readme 验证", plain: true }
→ 期望：已发送 (msg )；失败时渲染为「发送失败：已入 outbox 保底」

无需真实 bot token 的验证：npm test（10 例离线测试）——纯判定层不碰网络。

配置

（键名与 src/index.ts 的 Config schema 一致；默认值取自源码）

| 项 | 默认 | 说明 |
|----|------|------|
| botToken | ''（空则读 DSH_HOME/.credentials.yaml 的 refs.TELEGRAM_BOT_TOKEN） | Bot（@BotFather 创建）。单一来源：优先 config，其次凭据文件——不要写进 README/源码 |
| ownerChatId | 未设 | 主人 chat id（发放白名单）。未设时靠「首条消息自动绑定」，绑定结果落 telegram-owner.json |
| mainSessionId | 未设 | 主会话 id（可选；缺省时自动追踪最近真实 GUI 用户消息的会话） |
| pollTimeoutMs | 25000 | 长轮询 getUpdates 超时 |
| maxReplyChars | 3800 | 单条回复上限（与 4096 取小） |
| startDelayMs | 5000 | 启动延迟（让守护唤醒消息先处理） |
| maxRetries | 3 | 单次发送重试次数 |
| retryBackoffMs | 1500 | 重试退避基数 |
| flushIntervalMs | 60000 | outbox 冲刷间隔 |
| outboxPath | 未设（回退 $DSH_HOME/telegram-outbox.json） | outbox 文件路径 |
| inboundEnabled | true | 是否启用收消息 |
| outboundEnabled | true | 是否注册发送类工具 |
| askTimeoutMs | 600000 | telegram_ask 单次提问总超时 |
| retryMaxMs | 300000 | 会话不可用期消息排队最长时限 |
| askEnabled | true | 是否注册 telegram_ask |
| coldstartAlertPath | 未设（回退 $DSH_HOME/life-core/coldstart-alert.json） | coldstart 告警文件路径（只读输入） |
| coldstartWatchIntervalMs | 60000 | 告警文件检查间隔 |

落盘与自证（出问题时先看这里）

本插件不写 -trace.jsonl 阶段轨迹；它的自证是一组状态文件 + 两本日志（全部在 $DSH_HOME 下）：

| 文件 | 内容 |
|------|------|
| /telegram.log | 主事件链（append，纯文本行）：[ISO] [level] event detail——收到 / 注入 / 直播 / 回传 / API 异常 |
| /telegram-outbound.log | outbound 通道日志（发送、重试、降级、入 outbox） |
| /telegram-outbox.json | 未送达消息队列（持久化防丢失）；flushIntervalMs 周期冲刷 |
| /telegram-pending.json | 待回传的回复（重启窗口不丢回复） |
| /telegram-owner.json | owner 绑定结果（{ ownerChatId, boundAt }）——含 chat id，勿外传 |
| /telegram-offset.json | 长轮询 offset（{ offset, updatedAt }，至少一次语义的落点） |
| /life-core/coldstart-alert.json | 只读输入：dsh-life-core 写的冷启动自救失败告警（本插件负责送达） |
| /.credentials.yaml | 只读输入：refs.TELEGRAM_BOT_TOKEN（凭据文件不入 git） |

一条命令答五问：

tail -20 "$DSH_HOME/telegram.log"; echo ---; tail -5 "$DSH_HOME/telegram-outbound.log"
① 跑的是哪个构建 → 取不到（日志无 build 自报）；用「生效判据」节的 plugin_boot_status / lib mtime 判
② 谁发起 / 投给谁 → 收到消息与投递目标（owner 绑定后唯一）；发送日志含 chat 与长度
③ 断在哪一段    → 事件链即断点：有「收到」无「注入」= 会话注入失败（看是否在排队重试）；有「发送」无「送达」= API 侧失败（看 outbound 日志里的 429/降级）；有「入 outbox」= 已保底，等冲刷
④ 结果质量      → outbox 待发条数（telegram-status 也报）+ 是否发生 MarkdownV2 降级（降级 = 格式丢了但内容到了）
⑤ 耗时与预算    → 轮询 pollTimeoutMs(25s) / 重试 maxRetries(3)×retryBackoffMs(1500ms) / 排队上限 retryMaxMs(300s) / ask 超时 askTimeoutMs(600s) / outbox 冲刷 flushIntervalMs(60s)

隐私纪律（本插件的红线）：telegram.log / telegram-owner.json / telegram-outbox.json 里含 chat id 与消息正文。排障时只贴结构化的字段名与计数，不要把日志原文外传；token 永远只在 Config 或凭据文件里。

生效判据与回退

生效判据（三选一，按可靠性排序）：

1. 行为级（最直接）：telegram_status 返回 owner 绑定状态与 outbox 计数（工具在工具面上）⇒ 插件已装载；若 /telegram.log 的 mtime 在持续前进 ⇒ inbound 轮询在跑，不是假活；
2. 生态级：plugin_boot_status（dsh-plugin-bootreport）返回的 liveNow 含本插件 ⇒ 进程在跑它；
3. 构建级：lib/index.js 的 mtime 早于 web 进程启动时间 ⇒ 当前进程加载的是这个产物。

注意：重新构建 ≠ 生效——产物 mtime 新只证明「构建过」，进程启动时间晚于产物 mtime 才算「在跑它」。本插件也没有 hasUnverifiedBuilds() 类兜底，构建完必须重启 web 才生效。

网络维度的判据：进程内改代理/凭据不会生效——NODE_USE_ENV_PROXY=1 必须在进程启动时注入（由守护进程负责）。所以「改了代理配置但还连不上」通常不是代码问题，而是进程没重启。

回退（三档）：

- 源码级：git -C self-plugins/dsh-agent-telegram revert  → npm run build → npm test → 预检 → 重启；
- 组合级：给 profile 里 agent-telegram 行加 disabled: true（或精细化：outboundEnabled: false 停发送工具、askEnabled: false 停提问工具、inboundEnabled: false 停收消息）→ 重启；
- 运行期：消息队列即数据——telegram-outbox.json / telegram-pending.json 可手工备份后删除（副作用：待发消息与待回传回复一并丢失）。telegram-offset.json 删除会让轮询重新拉取（可能重复投递旧消息，至少一次语义，不是故障）。

测试

npm test        # = node --test "tests/.test.mjs"（跑 lib/ 产物，需先 npm run build）

10 例离线测试全部通过（# pass 10 / # fail 0）：

| 文件 | 覆盖 |
|------|------|
| tests/cold-alert.test.mjs | coldstart 告警送达的纯判定：owner 未绑定（不记状态，绑定后仍可补推）/ 告警文件不存在 / mtime 未前进（已推送过去重）/ 已推送 mtime 更新（新告警） / 告警内容解析失败（仍推送，带兜底文案）——冷路径样本（「web 起来了但 agent 不在」）逐条覆盖 |

覆盖范围的诚实说明：当前只有 coldstart 告警判定这一层有单测。inbound 轮询、message 注入/steer、outbox 冲刷、分片与 MarkdownV2 降级、文件发送等路径没有离线单测，回归靠真实使用观察。这是本仓库已知的测试缺口。

是否需要真实外部依赖：测试不需要（不联网、不需 token）。但功能本身必须有——真实 botToken + 可访问 api.telegram.org（走代理时需 NODE_USE_ENV_PROXY=1）+ 已绑定的 owner。

设计要点

- 「至少一次」优于「恰好一次」：offset 只在对消息处理成功之后才确认；重启窗口靠 pending 持久化补投。宁可重复一次，不可丢一次——丢的是主人的话，重复只是噪音。
- 内容必达优先于格式：MarkdownV2 转义出错会让整条消息被 Telegram 拒收，所以有降级链（MarkdownV2 → 纯文本）。telegram_send { plain: true } 是直播/进度播报的推荐姿势（内容简单，不需要渲染）。
- 分片不切开结构：超长消息按 4096 分片，但不把代码块/链接等结构从中间切断——否则每一片都是坏的 Markdown。
- outbox 是「不丢」的落点，不是「已送达」的证据：失败入 outbox 只保证消息还在队列里；判「真的送到了」要看 outbound 日志里的送达记录或主人确认。
- telegram_ask 是挂起语义，不是轮询：提问期间 owner 的普通文本消息被当作答案消费（不注入会话），命令仍优先处理；HMR 卸载会自动 reject 挂起调用（不留幽灵等待）。一次只允许一个活跃提问——并发会造成答案路由歧义。
- 告警通道不与告警源耦合：冷启动告警由 dsh-life-core 落盘、本插件负责送达，而非让 life-core 反向依赖通道。理由：告警场景正是「web 起来了但我（agent）不在」——此时 Telegram 插件必然在跑，这条降级路径真的更宽。
- owner 白名单是唯一准入：非 owner 消息静默忽略（不回、不注入、不报错）。静默是刻意的——回复非 owner 等于对外暴露「这里有 agent」。
- 凭据单一来源，且不进 git：botToken 优先 Config，其次 DSH_HOME/.credentials.yaml（凭据文件不入库）；组合 patch 会被 git 跟踪，所以更推荐凭据文件。

相关文档

| 文档 | 内容 |
|------|------|
| docs/semantic.md | 权威契约：定位与反定位、术语、概念模型与不变量、契约（含调用点清单）、边界与信任、可证伪验收清单、实践修订记录、未决问题 |
| alice-digital-life | 本插件所属生态的中心索引（全部自研插件） |
| 技能 telegram-markdown-v2 / preventive-lifecycle / plugin-maintainability | MarkdownV2 转义与降级链、预防性存活与告警证据链、可维护性五问 |

License

MIT © jonah791

本插件属于我的数字生命爱丽丝（alice-digital-life）的 DSH 自研插件生态——50 个插件按生命/认知/感知/行动/通信/治理/呈现七层组织。