安装
$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:congchuanling-dot/DSH-Telegram-Relay
DSH Telegram Relay
让 Telegram 成为 DeepSeek Harness 的移动端对话入口。
插件在本机通过 Telegram Bot API 长轮询接收私聊文本，将消息交给 DSH Agent 处理，并把最终回答发送回原会话。每个 Telegram chat_id 对应一个持久化 DSH Session，因此连续追问和进程重启后都能保留上下文。
效果展示
同一条对话由 DSH Session 持久化管理。Telegram 负责移动端收发，Web UI 可查看同一套 Agent 能力和执行过程。
Telegram 移动端
DeepSeek Harness Web
核心能力
| 能力 | 实现 |
|---|
| Telegram 私聊入口 | 使用 getUpdates 长轮询，无需公网 IP、域名或 Webhook |
| DSH 完整能力 | 消息进入真实 DSH Agent，可使用当前 profile 已启用的模型和工具 |
| 连续上下文 | String(chat_id) 直接作为 DSH Session ID |
| 重启恢复 | 从 DSH Session persistence 恢复历史对话 |
| 安全访问 | 只允许显式配置在 allowlist 中的私聊 |
| Update 去重 | 成功回复后原子持久化 Telegram offset |
| 长文本回复 | 按 Telegram 4096 字符限制进行 Unicode 安全分片 |
| 生命周期管理 | 插件卸载时中止 polling，并释放本插件持有的 Agent |
工作原理
Telegram 用户
│
│ 私聊文本
▼
Telegram Bot API
│ getUpdates 长轮询
▼
DSH Telegram Relay
│ allowlist 校验
│ chat_id -> Session ID
▼
DeepSeek Harness Agent
│ 模型推理 / 工具调用 / Session 持久化
▼
DSH Telegram Relay
│ sendMessage
▼
Telegram 用户
等待 getUpdates 返回时使用异步网络 I/O，不会通过 CPU 忙等持续轮询。
快速开始
1. 准备 Bot
- 在 Telegram 联系
@BotFather。
- 执行
/newbot 创建 Bot。
- 保存 Bot Token。
- 给新 Bot 发送一条消息，并通过
getUpdates 查询自己的私聊 chat_id。
node -e 'fetch(`https://api.telegram.org/bot${process.env.TELEGRAM_BOT_TOKEN}/getUpdates`).then(r => r.json()).then(x => console.dir(x, { depth: null }))'
结果中的 message.chat.id 就是 allowlist 所需的 chat_id。
2. 配置环境变量
Token 和 allowlist 只通过环境变量传入。不要将 Token 写入代码、YAML、README 或 Git。
export TELEGRAM_BOT_TOKEN=''
export TELEGRAM_ALLOWED_CHAT_IDS=''
export TELEGRAM_ALLOWED_CHAT_IDS='123456789,987654321'
export 只对当前终端会话及其启动的子进程生效。关闭终端或新开终端后，需要重新设置。Bot Token 通常保持不变，只有通过 BotFather 重新生成后才会变化；个人私聊 chat_id 通常也不会变化。
为了避免每次启动前重复设置，可以写入 deepseek-harness 根目录的 .env：
TELEGRAM_BOT_TOKEN=
TELEGRAM_ALLOWED_CHAT_IDS=
deepseek-harness/.gitignore 已忽略 .env，但仍需确认不要将该文件或其中的 Token 提交到 Git。插件卸载后可以保留这些配置，重新安装插件时会继续使用。
3. 安装依赖并构建
当前开发方式假设 DSH-Telegram-Relay 与 deepseek-harness 位于同一父目录：
myOwnProject/
├── deepseek-harness/
└── DSH-Telegram-Relay/
首次开发时安装依赖，并将 DSH peer dependencies 链接到本地 Harness：
cd DSH-Telegram-Relay
pnpm install --config.auto-install-peers=false
pnpm link \
../deepseek-harness/vendor/cordis \
../deepseek-harness/packages/core/agent \
../deepseek-harness/packages/core/agent-default-model \
../deepseek-harness/packages/llm/llm \
../deepseek-harness/packages/core/session \
../deepseek-harness/packages/session/session-persistence
pnpm run build
pnpm link 只用于本机开发，不要提交它写入的本机 link: 路径。
4. 安装到 DSH
pnpm --dir ../deepseek-harness \
dsh plugin --profile web add \
"$(pwd)"
pnpm --dir ../deepseek-harness \
dsh plugin --profile web list
dsh-telegram-relay@link:.../DSH-Telegram-Relay
5. 启动
cd ../deepseek-harness
pnpm dsh web
现在给 Bot 发送文本即可开始对话。首次消息会创建 Session，后续消息继续复用该 Session。
配置
- insert:
- id: telegram-relay
name: dsh-telegram-relay
config:
tokenEnv: TELEGRAM_BOT_TOKEN
allowedChatIds: !!js process.env.TELEGRAM_ALLOWED_CHAT_IDS?.split(',')
cwd: !!js process.cwd()
stateFile: !!js dshHomePath('telegram-relay/state.json')
| 字段 | 说明 | 默认值 |
|---|
tokenEnv | 保存 Bot Token 的环境变量名 | TELEGRAM_BOT_TOKEN |
allowedChatIds | 允许访问 DSH 的私聊 ID，不能为空 | 从 TELEGRAM_ALLOWED_CHAT_IDS 读取 |
cwd | 新建 Telegram Session 的工具工作目录 | 启动 DSH 时的当前目录 |
pollTimeoutSeconds | 单次长轮询等待时间 | 30 |
retryMinMilliseconds | 网络错误后的最短退避时间 | 1000 |
retryMaxMilliseconds | 网络错误后的最长退避时间 | 30000 |
stateFile | Telegram offset 状态文件 | $DSH_HOME/telegram-relay/state.json |
需要固定工具工作目录时，在 profile 的后置 patch 中将 cwd 覆盖为绝对路径。
安全边界
- Bot Token 仅从环境变量读取。
- allowlist 不能为空，且只接受 Telegram
private chat。
- 未授权 chat 不创建 Session，不触发模型，也不触发工具。
- 日志不记录 Token、完整 Telegram Update 或用户消息正文。
- offset 文件不保存 Token、聊天内容或 DSH Session 数据。
- DSH 处理失败时只向 Telegram 返回稳定错误文案，不暴露本机路径和调用栈。
Session 与状态
插件不维护额外的 chat-to-session 数据库：
DSH Session ID = String(Telegram chat_id)
对话历史、模型消息和工具调用记录全部由 DSH Session persistence 管理。插件只额外保存下一个 Telegram Update offset：
$DSH_HOME/telegram-relay/state.json
offset 只在 DSH turn 完成且 Telegram 回复成功后推进。正常运行时 Update 不会重复处理；进程在回复成功后、offset 落盘前崩溃时可能重复一次，因此 P0 提供至少一次交付，不承诺严格 exactly-once。
开发与验证
pnpm test
pnpm run typecheck:test
pnpm run typecheck
pnpm run build
- 配置与 allowlist 校验
- Telegram 错误分类和重试
- 长轮询与 Update 去重
- offset 原子持久化
- Session 创建、复用与恢复
- 当前 turn 的回答关联
- Telegram 长文本分片
- 未授权访问和失败回传
常见问题
启动时报 TELEGRAM_BOT_TOKEN is required
当前终端没有 Token。重新设置后，在同一个终端执行 pnpm dsh web：
export TELEGRAM_BOT_TOKEN=''
getUpdates 返回 result: []
当前没有未消费消息。停止其他 polling 进程，给 Bot 发送一条新消息后再次查询。
Telegram 返回 409 Conflict
同一个 Bot Token 正被另一个 polling 进程使用，或者 Bot 仍配置了 webhook。确保只运行一个 DSH 实例，并删除 webhook：
node -e 'fetch(`https://api.telegram.org/bot${process.env.TELEGRAM_BOT_TOKEN}/deleteWebhook`).then(r => r.json()).then(console.log)'
Bot 没有回复
- 确认 Web 插件列表中的
telegram-relay 已启用且没有加载错误。
- 确认
TELEGRAM_ALLOWED_CHAT_IDS 与 message.chat.id 完全一致。
- 确认 DSH Web 本身可以正常调用模型。
- 确认没有其他进程消费同一 Bot 的 Update。
P0 边界
当前版本只实现 Telegram 私聊文本对话。主动通知、Schedule 定时提醒、群聊、图片、文件、语音和 Webhook 将作为后续能力独立设计。