Telegram 桥接 sflaer/dsh-telegram-relay

dsh-telegram-relay

DeepSeek Harness 的 Telegram 桥接插件。DSH 加载这个插件运行期间，会启动一个回环控制面板，并把以下内容转发到 Telegram 机器人：

- 智能体提问（ask_user_question），带内联按钮，等待回答；
- 工具审批请求，带 Allow / Deny 按钮；
- 每轮结束后的回合摘要：状态、耗时、工具数量和最终文本；
- 子代理消息——完成摘要、提问和审批，默认全部开启，可在面板中切换。

回答可以在 Telegram 里给出，也可以在 DSH Web UI 里给出——先完整提交的回答生效，另一份会被标记为已处理。插件只运行在宿主侧：没有客户端 UI，也不会改动模型提示词。

截图

| 控制面板 | Telegram |

可视化指南用图示讲解架构、提问/审批的竞争处理以及启动流程。

语言

面板和所有面向机器人的消息都支持俄语、英语和中文。语言选择器位于面板头部；选择结果保存在 config.json 中，作用于新消息、命令菜单、面板和错误消息。已经发出的消息不会被改写。

在明确选择语言之前，插件跟随系统区域设置（LC_ALL / LANG / JS locale）。支持 ru、en 和 zh；其他系统语言（西班牙语、德语等）回退到英语。

环境要求

- DeepSeek Harness，且带有 sessions 服务（标准 Web 桌面配置档自带）。
- DSH 宿主能通过 HTTPS 出站访问 api.telegram.org（DSH 的全局代理设置生效）。
- 从 @BotFather 获取的机器人 token。

安装

桌面配置档

desktop 配置档由 Electron 应用管理，因此 dsh plugin --profile desktop add 会拒绝执行。请改用图形界面安装：

1. 打开 DSH → 侧边栏的 Plugins → Add plugin。
2. 填入 GitHub URL https://github.com/sflaer/dsh-telegram-relay 或本地检出的绝对路径。
3. 安装并重启 DSH。

管理器会自动把包加入 dsh.profile.bundles。

其他配置档

dsh plugin --profile web add github:sflaer/dsh-telegram-relay

或者，从本地检出安装：

dsh plugin --profile web add link:/absolute/path/to/dsh-telegram-relay

安装或更新链接包后，重启配置档。

面板

插件加载后，宿主日志中会出现：

[telegram-relay] control panel: http://127.0.0.1:7810

如果端口 7810 被占用，会改用操作系统分配的端口；实际 URL 保存在 $DSH_HOME/storages/telegram-relay/config.json 的 panelUrl 字段中。
1. 打开面板。
2. 粘贴 bot token，然后按 Save。
3. 给 bot 发送 /start，聊天会自动绑定。
4. 用 Send test 验证消息能否送达。

当凭据服务可用时，token 会写入 DSH 凭据存储（TELEGRAM_RELAY_BOT_TOKEN）；同时本地始终保留一份副本，位于 $DSH_HOME/storages/telegram-relay/config.json（权限 0600）。有了本地副本，重启就不再依赖服务的挂载顺序：如果凭据服务比插件晚挂载，中继会重试查询，并直接启动 bot，不会再向你要一次 token。这两份副本都不该写进 cordis.patch.yml。聊天 id、owner、白名单、语言和更新游标都存在同一个 config.json 里。

白名单下方，Subagent messages 是子代理来源通知的总开关。打开后，下面会出现 Completion messages 和 Questions；这三项默认都开启。Questions 也覆盖子代理的审批提示。

白名单

面板的 Whitelist 字段接受 @username、t.me/username、https://t.me/username、tg://user?id=… 或数字 id，用逗号、空格或换行分隔。

- 白名单为空：自动指定 owner，即第一个在私聊里发送 /start 的用户。只有 owner 能给 bot 发消息、按按钮。
- 白名单非空：只有名单内的用户能绑定聊天、发消息、按按钮。其他人一律拒绝，他们按的按钮会被忽略。
- owner 始终有访问权限，即使不在名单里。
- 如果你在面板里用聊天 id 绑定了群组，所有成员都能看到通知并回复。白名单只限制谁能发消息、按按钮。
- 用户名会变。想要稳定的规则，请用 tg://user?id=… 或数字 id。
- Unbind chat 会清除绑定和 owner，白名单保留。

为了防止别人抢先绑定 bot，请在发送 /start 之前填好白名单。

工作原理

架构图、完整时序和截图见可视化指南。

插件订阅三个接缝：

| 接缝 | 行为 |
| user-questions/request（waterfall，前置） | 把问题发到 Telegram 并等待回答，同时调用 next()，让 Web UI 的问题仍然可用。 |
| approval/request（waterfall，前置） | 发送 Allow / Deny 按钮，同时把请求交给 Web UI。 |
| session/event（turn/end） | 为结束的轮次生成摘要。 |

子代理会话（session.header.origin === 'subagent'）默认转发。面板的 Subagent messages 开关是总控；打开后，由 Completion messages 和 Questions 决定发送什么。Questions 复选框也覆盖子代理的审批提示，因为审批本身就是一种交互式子代理问题。这三项默认都开启。关掉总开关会保留下面两个子选项，供以后使用，不会清掉它们。
Telegram 传输采用长轮询（getUpdates），因此不需要公网 IP、webhook 或 TLS 证书。回环 HTTP 服务器只提供控制面板，并由每个进程独立的 CSRF token 保护。

助手最终文本中的 Markdown 会渲染成 Telegram HTML：粗体、斜体、删除线、行内代码、围栏代码块、链接、引用、标题和 ||剧透||。文件夹/时间/工具那一行始终放在最后。

配置

在配置档的 cordis.patch.yml 里覆盖字段——改已有的那一行，不要新增重复项：

- id: telegram-relay
config:
port: 7810
language: en
notifyTurnEnd: true
notifyQuestions: true
notifyApprovals: true
notifySubagents: true
notifySubagentTurnEnd: true
notifySubagentQuestions: true
summaryMaxChars: 1500
minTurnMs: 0

| 字段 | 默认值 | 含义 |
| port | 7810 | 面板端口；端口被占用时自动换一个空闲端口。 |
| language | 系统 | 面板和机器人语言：ru、en、zh；系统区域设置不受支持时回退到 en。 |
| notifyTurnEnd | true | 每轮结束后发送摘要。 |
| notifyQuestions | true | 转发 ask_user_question。 |
| notifyApprovals | true | 转发审批请求。 |
| notifySubagents | true | 子代理消息的总开关。 |
| notifySubagentTurnEnd | true | 转发子代理完成摘要。 |
| notifySubagentQuestions | true | 转发子代理的提问和审批。 |
| summaryMaxChars | 1500 | 摘要中最终文本的最大长度。 |
| minTurnMs | 0 | 短于该时长的轮次不发送摘要。 |
| apiBase | https://api.telegram.org | 备用 Bot API 端点（反向代理）。 |
| tokenEnv | TELEGRAM_RELAY_BOT_TOKEN | 凭据引用；config.json 里也会保留一份本地副本。 |

机器人命令

- /start —— 绑定会话并显示状态；
- /status —— 桥接状态、访问模式和待处理数量；
- /help —— 简短使用说明。

有提问待回答时，可以用按钮回答，用 Other answer，或直接回复提问消息的纯文本。多选题使用切换按钮加 Done。

安全须知

- 面板只绑定 127.0.0.1。本机任何进程仍能访问它；不要把端口暴露到网络。
- 机器人 token 拥有机器人的完全控制权。绝不外泄，也不要放进仓库。
- 只有绑定的会话能收到通知。在群里，每个成员都能看到。
- 提问和审批文本会发送到 Telegram 的服务器；附件和文件内容从不上传。

限制

- DSH 宿主关闭后通知就停了——插件运行在该进程内。
- Telegram 只接收文本：附件不会转发。
- 长轮询需要出站 HTTPS；未实现 webhook 模式。
- 群聊需要允许机器人发言；白名单仍然决定谁能回答。
同一个 bot token 只能由一个轮询器使用。启用这个插件前，先停掉其他桥接或 webhook。

开发

node --test tests/
node --check lib/index.js

测试不访问网络：Telegram 传输层已打补丁，测试覆盖格式化、Markdown 渲染、轮次跟踪器、控制面板、提问/审批流程、白名单和三种语言。

面板标题会显示构建标记（build 0.1.0+…），这是确认运行中的宿主实际加载了哪份代码最快的方式。

许可证

MIT — 见 LICENSE。