前言¶
DeepSeek Harness (DSH) 的核心设计理念是“一切皆插件”。当需要在 Telegram Bot 中与 agent 交互时，手动编写桥接代码会涉及大量 Bot API 调用逻辑，且需要处理会话映射、长任务队列等细节。dsh-channel-telegram 提供了一个独立的解决方案，通过长轮询接收私聊消息，并将 Telegram 聊天映射为 DSH agent 会话，无需修改 DSH 源码即可启用。
插件定位¶
这是一个 Telegram 薄桥接插件。由 LosEcher 维护。它将 DSH 的 agent 通过 Telegram Bot 暴露出来，走与 ACP 桥完全相同的驱动模式（agents.create → agent.followup → agent.whenIdle），回复最终 assistant 文本。插件独立交付，DSH 的 Host loader 支持绝对路径插件 entry。
核心功能¶
根据已核实事实，该插件具备以下能力：
* 长轮询接收私聊消息。
* 按 chatId 映射 DSH agent 会话，会话 ID 为 telegram-<chatId>。
* 长任务串行队列：每个 chat 一个队列，长任务不阻塞轮询。
* 支持命令：/start、/help、/new、/status。
* 4096 分块消息回复。
* 409/401 错误自动处理。
安装与启用¶
该插件作为独立 bundle 提供，不涉及官方安装命令。启用流程如下：
-
获取 Bot Token
在 Telegram 中找到 @BotFather 创建 bot，并获取 Token。 -
配置环境变量
确保 DSH 进程环境变量中包含TELEGRAM_BOT_TOKEN（默认变量名，可通过tokenEnv修改）。如果通过绝对路径引入源码开发，需确保name为绝对路径。 -
获取 Chat ID
给 @userinfobot 发送任意消息，即可获取用于配置的chatId。 -
合并配置文件
将插件的cordis.telegram.yml内容合并进 DSH 的配置文件。通常合并进$DSH_HOME/cordis.patch.yml（全部 profile）或$DSH_HOME/profiles/<name>/cordis.patch.yml（单 profile）。配置中的allowlist填入你的私聊 ID（空数组表示全部拒绝）。 -
重启服务
重启dsh web。日志中应出现[dsh-channel-telegram] connected as @...。
- insert:
- id: channel-telegram
name: dsh-channel-telegram
config:
tokenEnv: TELEGRAM_BOT_TOKEN
allowlist: [123456789] # 你的私聊 id
# workspace: /abs/path # 可选，agent 会话 cwd（默认 ~/.dsh-telegram/workspace）
# provider: los-gateway # 可选：agent 走的 provider 路由
# model: deepseek # 可选：该路由上的模型
典型用法¶
配置完成后，可以通过私聊与 Bot 交互。
- 会话管理：每聊一会话对应一个
telegram-<chatId>，上下文连续。使用/new命令可销毁重建会话。 - 命令响应：
/start：启动会话。/help：查看帮助。/new：销毁当前会话并创建新的。/status：查看当前会话状态。
- 消息回复：Bot 会发送 typing 动作，并在整轮回复结束后发送 assistant 文本。如果 assistant 文本超过 4096 字符，会自动分块发送。
适用场景与注意¶
- 依赖要求：依赖
@deepseek-ai/cordis(>=4.0.0 <5.0.0)。 - 功能限制：
- 无流式输出：需要等待整轮任务完成才回复。
- 无媒体处理：目前仅支持文本消息接收。
- 内存会话：会话映射在内存中，重启 DSH 进程后
/new语义自然达成（即新进程需要重新配置 allowlist）。 - 消息去重：依赖 Bot API 的 offset 机制保证不重投，但 DSH 侧无额外去重逻辑。
- 安全机制：allowlist 是唯一的安全闸门。非 allowlist 的私聊首次收到“未授权”提示，非私聊消息会被忽略。Agent 继承宿主全局权限设置，建议在低权限 preset 或独立 profile 下运行。
结语¶
dsh-channel-telegram 通过长轮询和 thin bridge 的设计，为 DSH 提供了标准化的 Telegram 交互能力。它专注于私聊场景，通过命令和会话管理机制，在保持轻量级的同时提供了必要的功能覆盖。对于需要通过 Telegram 调用 DSH agent 的用户，这是一个可以直接集成的选择。
