ben7am1n/dsh-telegram

dsh-telegram

DeepSeek Harness 的 Telegram 运行时适配器 —— 直接从 Telegram 与你的 dsh 智能体对话。每个被允许的聊天映射到一个智能体会话；消息通过 followup() 流入，已提交的助手文本会流式返回聊天。零运行时依赖（基于 Node 内置 fetch 的纯 HTTP）。

概述

dsh-telegram 将 DeepSeek Harness 智能体变成一个 Telegram 机器人。它是 dsh 扩展模型中的协议驱动：它将外部通信对端（Telegram）适配到 ctx.agents，与官方 ACP/JSON-RPC 桥接所扮演的角色相同——只不过面向的是人类聊天而非自动化。

它适合谁？

- 任何想从手机上查询自己的 DeepSeek 智能体、而不想打开 Web UI 的人。
- 希望在 harness 前面拥有一个共享、可审计的聊天界面的团队（Telegram 历史记录由 Telegram 保存）。
- 想要一个极简、可读的协议驱动插件编写参考的开发者。

它能做什么

- 长轮询 Telegram Bot API（getUpdates），无需服务器、无需 webhook、无需框架。
- 在收到第一条消息时，为每个被允许的聊天创建一个 dsh 智能体会话；后续消息通过 followup() 进入同一会话，从而保留对话历史。
- 将每条已提交的助手消息流式返回聊天；长回复会按 Telegram 的 4096 字符上限拆分。
- 支持 /start、/new（全新会话）、/status。
- 直接拒绝未授权用户（可配置允许列表）。

它（目前）不能做什么

- 没有 webhook 模式（需要公网 HTTPS 端点）。
- 没有内联键盘、媒体、语音或富文本消息——纯文本输入，纯文本输出。
- 聊天→会话映射没有跨重启持久化（见兼容性）。

兼容性

- 需要 Node.js ≥ 22.19（使用全局 fetch）。
- 基于 @deepseek-ai/dsh@0.1.0-rc.6 / @deepseek-ai/cordis@^4.0.1 构建并验证。
- 最后验证时间： 2026-08-13，针对当日主线提交（dsh 仓库 master）。
- dsh 处于开发者预览阶段，迭代迅速。请固定你的 dsh 版本，并在更新后重新验证；该插件的对等依赖（@deepseek-ai/dsh-agent、dsh-llm、dsh-session）在不同 RC 版本之间形态可能变化。
- 聊天→会话映射保存在内存中：重启 dsh 会丢失已打开的会话（使用 /new 开启新会话）。

安装 / 卸载

安装到 dsh profile（本地检出；无需构建权限）：

cd /path/to/deepseek-harness
pnpm dsh plugin --profile web add /path/to/dsh-telegram

从 GitHub 安装（源码安装——pnpm 会运行 prepare 脚本，因此需要允许一次）：

pnpm dsh plugin --profile web add github:/dsh-telegram
pnpm ≥10 会在首次安装时阻止构建脚本；将打印出的包键
复制到 /pnpm-workspace.yaml 的 allowBuilds 下，然后重新运行。

从 npm 安装（发布后）：

pnpm dsh plugin --profile web add dsh-telegram

卸载：

pnpm dsh plugin --profile web remove dsh-telegram

快速开始

1. 通过 @BotFather 创建一个机器人并复制 token。
2. 找到你的 Telegram 用户 id（例如给 @userinfobot 发消息）。
3. 在配置文件的 cordis.patch.yml 中设置 token 和你的用户 id（或导出 DSH_TELEGRAM_BOT_TOKEN）：

- id: dsh-telegram
name: dsh-telegram
config:
botToken: '123456:ABC-DEF...'
allowedUserIds: [123456789]
provider: deepseek-official
model: deepseek-v4-flash

4. 启动 dsh，在 Telegram 中打开你的机器人，发送 /start，然后发送任意消息。

配置

所有键都位于 dsh-telegram 行的 config 下（补丁层；后面的层按行覆盖前面的层）。

| 键 | 类型 | 默认值 | 含义 |
|---|---|---|---|
| botToken | string | 环境变量 DSH_TELEGRAM_BOT_TOKEN | 来自 @BotFather 的 Telegram 机器人 token。为空则禁用发送。 |
| allowedUserIds | number[] | [] | 允许聊天的 Telegram 用户 id。为空 = 拒绝所有人。 |
| provider | string | — | 创建的 agent 使用的 provider 路由（回退到配置文件默认值）。 |
| model | string | — | 创建的 agent 使用的模型（回退到配置文件默认值）。 |
| cwd | string | process.cwd() | 创建的 agent 会话的工作目录。 |
| pollTimeoutSeconds | number | 25 | getUpdates 的长轮询超时时间（Telegram 最大为 50）。 |

权限与数据

- 授权： 允许列表是唯一的关卡。未授权的用户会收到 ⛔ You are not authorized，并且永远不会获得 agent 会话。机器人 token 本身是让任何人能够调用你的机器人的密钥；允许列表决定谁可以获得会话。
- 网络： 该插件仅与 api.telegram.org（机器人 API）通信。Agent 模型调用通过 harness 的正常 LLM provider 路径进行。
- 文件系统： 该插件不读取或写入任何文件；agent 会话继承 harness 工作区策略。
- 密钥： 切勿将 botToken 提交到仓库。使用随附补丁中的环境变量形式（process.env.DSH_TELEGRAM_BOT_TOKEN ?? ''）。
- 对话记录： Telegram 在其服务器上保留聊天历史；dsh 会话还会根据 harness 会话持久化配置进行持久化。

故障排除

| 症状 | 原因 | 修复方法 |
|---|---|---|
| 机器人从不回复，出现 botToken is empty 警告 | 未配置 token | 设置 DSH_TELEGRAM_BOT_TOKEN 或 config.botToken；重启 dsh |
| ⛔ You are not authorized | 你的用户 id 不在 allowedUserIds 中 | 添加你的 id；重启 dsh |
| poll error: telegram getUpdates: 401 | token 无效/已撤销 | 在 @BotFather 中重新创建 token |
| 对话中途回复停止 | Agent 错误 | 检查 dsh 日志；错误会以 ⚠️ Agent error: 转发到聊天中 |
| 日志中大量长轮询 | 到 api.telegram.org 的网络被阻止/不稳定 | 确保机器可以访问 api.telegram.org（Node fetch 会遵循代理环境变量）；插件会自动退避 |
| cannot get property "agents" without inject | 插件在加载时缺少 inject 元数据（构建产物过期） | 重新构建：pnpm run build；确认安装的 lib/index.js 是最新的 |

开发

markdown
pnpm install
pnpm run typecheck     # tsc --noEmit
pnpm run build         # tsc → lib/

结构：

- src/index.ts — 插件入口（name/inject/Config/apply）、Telegram 客户端、长轮询循环、会话映射。
- cordis.patch.yml — 挂载插件行的 bundle 补丁层。

面向贡献者的设计说明：

- 零运行时依赖是一个目标：此处使用的 Bot API 接口刻意保持精简（getUpdates、sendMessage、sendChatAction）。在添加依赖之前，先问一问 Node 的内置模块能否覆盖它。
- 会话映射刻意保持简单（一个聊天 = 一个 agent，存于内存中）。未来版本可能会按 (chat, bot) 作为会话键，或将其持久化；参见兼容性。

许可证与安全

MIT。请通过仓库的安全公告私下报告安全问题（或在不包含机密信息的情况下提交 issue）。该插件使用操作者配置的 Telegram token 运行；它本身不执行任何模型代码——所有 agent 行为均由 harness 自身的权限与沙箱策略管控。