Telegram 会话桥 Nergous/dsh-tg-bridge

DSH Telegram 桥接

一个 DeepSeek Harness（DSH）插件，为每个 DSH 会话在 Telegram 论坛群组里分配独立话题。你可以在 DSH 或 Telegram 里跟进并驱动会话，两边看到的是同一段对话。

- 一个会话，一个话题。 每个根会话都会获得一个话题，命名为 workspace · session title。DSH 给会话命名时话题会重命名，归档会话时话题关闭，恢复会话时话题重新打开。
- 双向同步。 你在 DSH 里输入的消息会出现在话题中。你在话题里发送的文字、照片、文件和语音消息会进入会话，效果与在 DSH 输入框里输入消息完全一致。
- 智能体输出。 回答会实时流式写入同一条消息，模型写作过程中不断编辑这条消息。工具调用会按每次工具运行折叠成一个可展开的块。智能体工作期间话题显示「typing…」；一轮结束时，会收到一条提醒用的 ✅ Done。
- 子代理。 子代理不会创建话题。每个子代理在父话题里显示为一行：「working, waiting for result ⏳」，随后变成「done ✅」（或失败 ❌ / 取消 ⏹）。
- 审批与提问。 审批请求和 ask_user_question 提示词会带内联按钮送达。Telegram 和 DSH 图形界面同时等待：谁先回答谁生效，另一侧的提示会被撤回。
- 命令。 会话话题里支持 /stop、/status、/diff、/compact、/model 等命令；General 里支持 /sessions、/workspaces 和 /new。其他 DSH 斜杠命令也能用。
- 置顶状态卡。 每个话题的第一条消息（工作区、路径、会话 id、模型）会被置顶。
- 设置页与输入框链接。 所有配置都在 DSH 的插件页面上完成。DSH 输入框会显示一个 Telegram 链接，点击打开当前会话的话题。

环境要求

- 带插件管理器的 DeepSeek Harness（桌面应用或 dsh web）。
- Node.js 22 或更高版本（DSH 运行所用的版本）。
- 从 @BotFather 获取的 Telegram 机器人。
- 启用了 Topics 的 Telegram 超级群组。
- 可选：ffmpeg，用于语音消息。

安装

1. 在 DSH 里打开 Plugins → Add plugin，输入以下之一：
- github:Nergous/dsh-tg-bridge（从 GitHub 获取最新版），或
- 本地克隆的绝对路径，例如 /home/me/projects/dsh-tg-bridge。
2. 选择 Enable now，然后打开 Plugins → Telegram bridge。

插件没有构建步骤，也没有依赖。改动宿主代码（index.js、lib/）后重启 DSH；client.js 会在打开的页面里重新加载。

配置

1. 机器人 token。 用 @BotFather 创建机器人（/newbot），在设置页粘贴 token，然后按 Save token。token 保存在 DSH 凭据（DSH_TELEGRAM_BOT_TOKEN）里，绝不写入配置文件。同名的环境变量同样有效。
2. 群组。 创建群组，打开群组设置并启用 Topics。添加把机器人拉进群，设为管理员，并授予 Manage topics 和 Pin messages 权限。
3. 绑定。 点 Get bind code，然后在 10 分钟内于群里发送 /bind 。群会被保存，你也会被加入允许用户列表。如果希望其他人也能向会话写入，在设置页添加更多 Telegram user id。其他人的消息、机器人消息和匿名管理员消息都会被忽略。
4. 点 Test connection。它会检查 token、群、Topics 以及机器人的权限。
5. 在任意 DSH 会话里写点东西。该会话的 topic 就会出现在群里。

一个机器人只能由一个进程轮询。如果 DSH desktop 和 dsh web 同时运行并加载此插件，Telegram 会返回 409 Conflict；请只使用其中一个，或者换第二个机器人。

使用方式

哪些会话会获得 topic

- 每个根会话，无论新旧。默认情况下，topic 在插件运行后该会话的第一条消息或第一轮对话时创建，因此旧会话会在你下次于 DSH 中继续它时获得 topic，或者直接从 General 里的 /sessions 立即创建。把 Create topic 设为「As soon as a session opens」，会话打开时就创建；设为「Never automatically」，则只用 General 里的 /new 和 /sessions 创建 topic（已有 topic 继续可用）。
- topic 以状态卡开头；更早的历史不会被复制。
- 如果在 Telegram 中删除了 topic，下一条消息会创建新 topic。会话需要时，已关闭的 topic 会重新打开。
- 子代理会话永远不会获得 topic。

与会话对话

在会话的 topic 里写消息，就是与该会话对话。消息会排在正在运行的那轮之后，与 DSH 中一致。以 ! 开头的消息改为引导正在运行的那轮。智能体等待问题答案时，你的下一条文本消息就是回答。

照片作为图片附加（模型接受图片时），文档作为文件附加（上限为 Max download, MB）。语音消息会转写为文本发送；转写内容会回显在 topic 中。没有转写器时，音频文件作为附件发送。

智能体用 present 工具呈现的文件会作为文档发送到 topic。

Topic 命令

| 命令 | 作用 |
| /stop | 停止正在运行的那轮（排队消息继续排队）。 |
| /status | 工作区、状态、模型、上下文用量、输出模式。 |
| /diff | 会话目录的 git diff --stat，完整补丁作为文件发送。 |
| /compact | 压缩对话（会话空闲时）。 |
| /model [name] | 以按钮形式显示模型，或按名称切换到某个模型。 |
| /permission [ro\|write\|full] | 以按钮形式显示访问权限（Read Only、Workspace Write、Full Access），或切换权限。别名 /access。新会话：/new --ro\|--write\|--full <workspace> [prompt]，或使用 /new 选择器中的按钮。 |
| /verbosity full\|tools\|final | 仅对此 topic 设置输出详细程度。超过一条消息的回答会以预览加 answer.md 的形式送达。 |
| /mute、/unmute | 暂停或恢复该话题里的智能体输出。审批和提问仍会送达。 |
| /steer <text> | 等同于 !text。 |
| /help | 命令列表。 |

其他 DSH 斜杠命令（例如 /goal）和输入框里一样，走 DSH 命令注册表。无法识别的斜杠文本会作为消息发给会话。

通用话题命令

| 命令 | 作用 |
| /sessions | 把最近的 DSH 会话列成按钮。🧵 打开会话对应的话题；➕ 创建（或重新打开）话题并发出链接，这样你就能从 Telegram 继续任意会话。 |
| /workspaces | 已知的 DSH 工作区。 |
| /new | 用按钮选一个工作区，然后发送第一条消息（文本、照片、文件或语音），也可以不发送直接开始。会话话题会带着你的消息打开。 |
| /new <workspace> [prompt] | 直接在某个工作区里开始（按名称或路径）。不带提示词时，机器人会要求你发第一条消息。 |
| /cancel | 停掉正在等待选择或消息的 /new。 |
| /help | 命令列表。 |

设置

所有设置都在插件的设置页里，改完不用重启即可生效。

输出

| 设置 | 默认值 | 含义 |
| 输出详细程度 | 折叠工具 | 展开工具显示全部、折叠工具，或只显示最终回答。/verbosity 可按话题覆盖。 |
| 实时流式回答 | 开 | 模型写作时持续编辑同一条消息。关闭后，回答完成才发送。 |
| 回合结束时通知 | 开 | 带声音的 ✅ Done 提示行。其余情况静默。 |
| 工作时显示「正在输入…」 | 开 | 回合进行中显示 Telegram 输入状态。 |
| 同步我的 DSH 消息 | 开 | 在话题里显示你在 DSH 中输入的消息。 |
| 每个话题固定状态卡片 | 开 | 固定话题的第一条消息。 |

话题

| 设置 | 默认值 | 含义 |
| 创建话题 | 收到第一条消息时 | 也可以会话一打开就创建，或从不自动创建。 |
| 会话归档时 | 关闭话题 | 关闭、删除或保持打开。恢复会话会重新打开已关闭的话题。 |

交互

| 设置 | 默认值 | 含义 |
| 用按钮审批 | 开 | 关闭后，审批请求只发到 DSH 图形界面。 |
| 用按钮回答智能体提问 | 开 | 关闭后，智能体提问只发到 DSH 图形界面。 |
| 发送智能体展示的文件 | 开 | 把 present 的文件作为文档转发。 |
| 引导前缀 | ! | 留空则禁用前缀。 |
| 转写语音消息 | 开 | 关闭后，语音消息作为音频文件附加。 |
| 转写命令 | 空 | Shell 命令（POSIX sh）；{file} 是 16 kHz 单声道 WAV。示例：whisper-cli -l ru -nt -f {file}。不填则使用已安装的 DSH 语音转文字。 |
| 语音语言（DSH STT） | 空 | DSH 语音转文字的语言提示。 |

高级

| 设置 | 默认值 | 含义 |
| 启用桥接 | 开 | 关闭后停止轮询和同步。 |
| 流式编辑间隔，毫秒 | 2500 | 流式消息两次编辑之间的最短时间。 |
| 每分钟消息数 | 20 | Telegram 对单个群组的限制；所有话题共用这一额度。 |
| 最大下载量，MB | 20 | 从 Telegram 取回的最大文件（Bot API 限制为 20）。 |
| ffmpeg 路径 | ffmpeg | 用来解码语音消息。 |
| Bot API URL | https://api.telegram.org | 用于自建 Bot API 服务器。必须是 https，或者回环地址上的 http。 |

DSH 语音转文字（@deepseek-ai/dsh-experimental-voice-input-bundle）是可选功能，且不识别俄语；要处理俄语语音消息，请设置转写命令，例如 whisper.cpp。

限制

- 话题不会回填：话题只显示它创建那一刻起的会话。
- /sessions 列出最近 15 个会话；更早的会话在你于 DSH 中继续它们时才会获得话题。
- /model 使用 DSH 的模型切换，这也会改变新会话的默认模型。
- DSH 没有会话删除事件，所以删除会话后它的话题仍会保留；归档会关闭话题。
- 在 Telegram 中已超时的问题，只能在 DSH 中回答。
- 每个运行中的 DSH 进程只能有一个 bot（见上文 409 Conflict）。

工作原理

插件运行在 DSH 宿主进程内。

- 它监听 DSH 会话事件（session/event、agent/assistant-stream、subagent/start、subagent/end），并通过每个群组一条限速队列发送 Telegram 消息。流式编辑会合并，因此繁忙的群组收到的是更少、更大的编辑，而不是积压。不适合重复发送的消息，只有在 Telegram 确定没有收到时才重试。
- 来自 Telegram 的输入走 sessionController.prompt，也就是 DSH 输入框所用的方法。冷会话会带着它的预设和模型恢复。
- 审批和问题会在 GUI 之前挂上 approval/request 和 user-questions/request 瀑布钩子，并让两边的回答竞速。DSH GUI 会立刻显示提示词；Telegram 从不会拖慢它。
- 根会话与子代理通过会话头（origin: 'subagent'）区分。子代理的审批显示在根话题里。
- 会话到话题的映射和轮询偏移量存放在 DSH 存储域（~/.dsh/storages/telegram_bridge.json）。

安全

- 只服务绑定的群组和允许的用户 id。其他一切都被忽略，包括按钮点击、bot 和匿名管理员。
- bot token 保存在 DSH 凭据中，绝不写入日志、错误、配置或存储域。设置路由无法更改凭据名称或 Bot API URL。
- 设置路由使用 DSH 自带的身份验证。
- 任何能以允许用户身份在群里发言的人，都能以会话的权限在你的会话中运行命令。请把群组设为私有。

报告漏洞请见 SECURITY.md。

开发

npm test # node --test, no dependencies
node scripts/check-repo.mjs # syntax, manifest consistency, full test suite

测试使用进程内的假 Telegram Bot API 和假 DSH 服务；它们绝不接触 Telegram，也不接触真实的 DSH 安装。CI 在 Linux（Node 22 和 24）和 Windows 上运行检查，另外还跑 npm audit。

Codex App Server 之前那个 Go 桥接保留在 v0.1.5 标签。

License

MIT