foxden-app/dsh-telegram-bridge

dsh-telegram-bridge

中文 ｜ English

把 DeepSeek Harness 接入 Telegram 的桥接插件：在 DSH 宿主进程里跑一个 Telegram 长轮询机器人，私聊即 DSH 会话。手机上下发任务，Agent 在电脑上干活；工具活动实时回传，最终回复送达聊天，同一个会话在 web GUI 里同步可见——浏览器和手机双端同源。

Telegram 私聊 ⇄ 本插件（DSH 进程内）⇄ ctx.agents（真实 agent 会话）⇄ web GUI 同一会话

特性

- 🔁 长轮询：getUpdates 长轮询，无需公网回调 / webhook / 域名
- 💬 私聊 ↔ 会话映射：每个允许的私聊绑定一个持久化 DSH 会话，DSH 重启后自动恢复
- 🧹 整洁聊天：每回合只发一条进度消息（节流编辑、带最近工具提示），回合结束自动删除；/help /status /threads 等命令面板 5 分钟后自动撤回
- 📨 富文本回复：模型 Markdown 渲染为 Telegram HTML（围栏代码块/标题/引用/行内代码/加粗/链接），HTML 被拒时自动回退纯文本
- 👀 确认反应：收到消息立即给消息加 reaction，避免"发出去石沉大海"
- 🧩 原生体验：模型、agent preset、权限策略全部走 DSH 自身配置；会话出现在 GUI 侧栏
- 🪶 零依赖、零构建：单个纯 JS ESM 文件，直接挂载；渲染器带单元测试（npm test）

命令

| 命令 | 作用 |
| --- | --- |
| /help /start | 用法说明（面板，自动撤回） |
| /new [目录] | 新建会话，可指定工作目录（支持 ~ 展开） |
| /threads | 列出本聊天最近的历史会话（面板） |
| /open 序号 | 切换到 /threads 列表中的某个会话 |
| /stop | 中断当前回合 |
| /status | 当前绑定会话、状态、模型（面板） |
| 其他任意文本 | 作为普通用户消息提交给当前会话 |

显示与聚合策略

- 实时阶段：每个回合只有一条进度消息，按 progressIntervalMs 节流原地编辑，显示工具调用次数和最近 3 条工具摘要
- 回合结束：进度消息默认删除（deleteProgressOnFinal: true），只保留最终回答——答案本身就是聚合视图；设为 false 则改为保留一行"✅ 完成 · N 次工具调用"摘要
- 最终回答：Markdown → Telegram HTML 富文本渲染；超 4096 字符自动分片
- 命令面板：所有命令回复都是"面板"，panelTtlMs（默认 5 分钟）后自动删除，聊天框里长期留存的只有你的提问和 Agent 的回答

安装

方式 A：profile 用户层（推荐，重启后常驻）

web profile 有一个专属用户层文件 ~/.dsh/profiles/web/cordis.patch.yml（默认内容是 []）。把下面的内容写进去即可，之后每次 dsh web 启动都会自动挂载：

- insert:
- id: telegram-bridge
name: /home/me/dsh-telegram-bridge/src/index.js
config:
botToken: "123456:ABC-your-token"
botUsername: my_bot
allowedUserIds: [123456789]
defaultCwd: /home/me/project

建议顺手 chmod 600 该文件（里面有 token）。可用下面命令验证组合结果（不会启动服务）：

dsh --profile web --dump-config | grep -A8 telegram-bridge

方式 B：--patch 临时叠加

写一个 patch 文件 ~/dsh-telegram-bridge.patch.yml（内容同上），启动时显式叠加：

dsh web --patch ~/dsh-telegram-bridge.patch.yml

验证

给 bot 发一句"你好"，收到回复即接入成功。

也可以用 dsh plugin add 把仓库安装进 profile 目录后以包名挂载，或发布到 npm 后写 name: dsh-telegram-bridge。

配置项

| 键 | 必填 | 默认 | 说明 |
| --- | --- | --- | --- |
| botToken | ✅ | — | @BotFather 发的 bot token |
| allowedUserIds | ✅ | — | 允许使用的 Telegram 数字用户 id 白名单（强烈建议只写自己） |
| defaultCwd | ✅ | — | 新会话的工作目录（绝对路径） |
| apiBase |  | https://api.telegram.org | Bot API 地址 |
| titlePrefix |  | Telegram | 会话标题前缀（GUI 识别 + 重启恢复依据） |
| longPollSec |  | 25 | getUpdates 长轮询秒数 |
| httpTimeoutMs |  | 40000 | 单次 HTTP 超时 |
| progressIntervalMs |  | 5000 | 进度消息节流间隔 |
| panelTtlMs |  | 300000 | 命令面板自动撤回延迟（毫秒，0 关闭） |
| deleteProgressOnFinal |  | true | 回合结束时删除进度消息（false 改为保留摘要行） |
| threadsLimit |  | 8 | /threads 列出的会话条数 |
| indexPath |  | 插件目录内 | 会话索引文件（默认写在插件目录，规避沙箱写限制） |
| proxy |  | 继承环境 | 钉死所有 Telegram 流量的 HTTP(S) 代理，如 http://127.0.0.1:7897 |
| modelChoices |  | deepseek 两档 | /setup 按钮面板的模型候选（provider/model 数组） |
| announceOnStart |  | true | 启动后向白名单用户发上线通知 |
| debugLog |  | 无 | 追加式调试日志文件路径 |

工作原理

插件代码运行在 DSH 的受限宿主环境里（没有原生网络 API），因此：

- 出站 HTTP：通过 shell 服务执行 curl（stdin 传 JSON body，规避 shell 转义）
- 创建会话：ctx.agents.create({ sessionId, meta: { cwd } }) 拿到 owned handle；插件卸载时会话随之收尾
- 提交消息：构造普通 user message 后 agent.followup(...)，排队进入下一回合
- 观察输出：监听全局 session/event 流，按 sessionId 过滤；tool/call 驱动进度消息，assistant/message 收集文本，turn/end 结算回复
- 重启恢复：会话标题写成 Telegram · ，启动时经 sessionQuery 找到最新匹配会话并 ctx.agents.resume

安全须知

- 这个 bot 等于你的 DSH 远程入口：能给它发消息的人 = 能在你电脑上跑 agent 的人。务必把 allowedUserIds 限制为本人数字 id。
- 若你的 DSH 权限 preset 是免审批模式，Telegram 下发的任务将以同等权限直接执行，请自行评估。
- token 泄露 = 别人冒充你操作；建议定期在 @BotFather 里 revoke。

已知限制（欢迎 PR）

- 暂只支持文本消息（图片/语音/文件未接）
- 群组与话题未支持（仅私聊）
- 审批请求仍走 web GUI，未映射成 Telegram 按钮
- 无 Markdown 渲染（纯文本发送）

License

MIT