前言¶
DeepSeek Harness（命令名 dsh）把智能体运行时拆成可组合的插件：模型、工具、会话、沙箱和界面都可以在 Cordis 内核上增删。官方开发者预览页把这件事概括成 Everything is a plugin（一切皆插件）。日常入口通常是终端或 npx @deepseek-ai/dsh web 打开的网页界面。人一旦离开电脑，就没法继续给同一个 agent 发消息。
社区插件 telegram 做的是另一条通道：用 Telegram Bot API 的长轮询，把私聊文本桥接到 harness 里的 agent 会话。手机上给 bot 发一句话，当前 dsh 进程里对应聊天的 agent 接着跑；助手回复再按 HTML 格式分片送回同一条私聊。它不注册给模型用的工具或技能，只负责「聊天 ↔ 会话」这一层。
需要先说明：下文引用的目录页来自独立社区站点 DeepSeek Harness 插件库，About 页写明该站与 DeepSeek / 幻方没有官方从属关系，不能当成官方应用商店。官方仓库是 deepseek-ai/deepseek-harness。本文按目录详情页、GitHub README / package.json / cordis.patch.yml / src/，以及官方 Harness 说明交叉核对，核实日期为 2026-08-18。
这是什么¶
telegram 是一款通知与集成插件，由 LoserFox 维护，仓库为 LoserFox/telegram。目录页与 GitHub 仓库描述一致：Telegram Bot API 桥接，长轮询、per-chat 会话、HTML 格式化。
几个已核对的归属信息：
- npm 包名：
@loserfox/telegram，package.json版本 0.1.0 - 插件插入行 id：
telegram（见cordis.patch.yml） - 主要语言：TypeScript
- GitHub topic：
dsh-plugin - 星标：目录页与 GitHub API 均为 6
- 许可证：
package.json声明 BSD-3-Clause；仓库根目录没有独立LICENSE文件，GitHub 的 license 字段因此为空，安装前应自行核对 - 目录收录日期：2026-08-05；仓库最近推送：2026-08-13（当前
main顶端提交a0a9ca11e427b62217250e2e561f6ad3c49d13f2）
它声明 inject: ['agents']，依赖宿主组合里已经挂上 @deepseek-ai/dsh-agent。LLM 适配器、会话持久化和 bash / 读文件等工具都不在这个包里，而是由外围 cordis.yml（或当前 profile 的其它层）提供。README 写明设计参照 NousResearch/hermes-agent 的 telegram 平台适配器，再裁成 harness 的纯文本接缝。
核心功能¶
按 README 与 src/bridge.ts / src/index.ts，能力可以收成下面几条。
1、长轮询收消息。 插件用 Bot API 的 getUpdates 拉更新，默认超时 30 秒。没有 webhook 模式，也不要求公网 IP 或域名；运行 dsh 的主机需要能出站访问 Telegram API。单条轮询循环服务所有聊天；空批次会睡 50ms，避免事件循环空转。
2、每个聊天一个 agent 会话。 已授权的文本消息会按 chat 创建或复用 agent（ctx.agents.create），经 followup 把原文当成用户消息送进去。会话 id 形如 telegram:<chatId>；/new 与 /clear 会换新的 session 并释放旧 agent。
3、白名单默认关闭。 allowedUserIds 默认为空列表，空列表拒绝所有人（fail closed）。allowAllUsers 默认 false，README 标明仅开发用。未授权用户会收到 Access denied.。
4、Token 加载即校验。 token 为空时回退环境变量 DSH_TELEGRAM_TOKEN；两者都缺则 apply 直接抛错，不会惰性启动。
5、回复做 HTML 格式化并按 4096 分片。 助手文本按保守的 Markdown 子集转成 Telegram HTML（围栏代码、行内代码、**粗体**，其余转义），再按 maxMessageLength（默认 4096）切开，优先在换行、中文句号、句点加空格处断开。某一片 HTML 被 Telegram 拒绝时，该片回退为纯文本。turn/start 会发 typing 聊天动作。投递是 fire-and-forget，失败记日志后丢弃，没有发送重试账本。
6、斜杠命令不到达模型。 /start 欢迎，/new 与 /clear 开新会话，/help 列出命令。其它以 / 开头的文本按未知命令处理。普通用户消息则原样进入该聊天的会话历史。
安装与启用¶
社区目录页给出的安装命令如下，在 DeepSeek Harness 终端里运行：
dsh plugin add github:LoserFox/telegram
仓库 README 还写了挂到指定 profile（例如 web）的写法，以及装完后的核对与卸载：
# 安装到某个 profile，bundle 声明会进入组合层
dsh plugin --profile web add <dir|git-url>
# 验证插入行
dsh --profile web --dump-config | grep telegram
# 卸载
dsh plugin --profile web remove telegram
目录页提示：如需可复现安装，可固定 commit 哈希，形式为 dsh plugin add github:LoserFox/telegram#commit。以 2026-08-18 看到的 main 顶端为例：
dsh plugin add github:LoserFox/telegram#a0a9ca11e427b62217250e2e561f6ad3c49d13f2
几点安装约束：
- 组合层变更不参与 HMR，装完或卸完需要重启目标 profile 的 DSH 进程。
- 宿主必须已经挂载
agents服务。peerDependencies 里写的是@deepseek-ai/dsh-agent^0.1.0-rc.6，以及@deepseek-ai/dsh-llm、@deepseek-ai/dsh-session、@deepseek-ai/cordis、@deepseek-ai/schemastery等组合包。 - 目录页写明：插件以当前 dsh 进程的权限运行，安装时可能执行代码。安装前检查源代码仓库和许可证。
配置与典型用法¶
配置项¶
src/index.ts 里的 TelegramConfig 与 README 表格一致：
| 键 | 默认 | 含义 |
|---|---|---|
token |
'' |
@BotFather 创建的 bot token；空则读 DSH_TELEGRAM_TOKEN |
allowedUserIds |
[] |
允许对话的 Telegram 用户 id；空列表拒绝所有人 |
allowAllUsers |
false |
允许任意用户（仅开发用） |
provider |
deepseek-official |
创建 agent 时传入的 LLM provider id |
model |
deepseek-v4-flash |
创建 agent 时传入的模型 id |
maxMessageLength |
4096 |
单条 Telegram 消息长度上限 |
pollingTimeoutSec |
30 |
长轮询超时（秒） |
日志会经 ctx.logger 输出，bot token 会被脱敏。生产环境走全局 fetch 和真实定时器；client 与 sleep 只是测试接缝。
仓库自带的 telegram-agent 示例¶
仓库 examples/telegram-agent/ 是一份可运行的 cordis.yml：Telegram 桥接加上 DeepSeek 适配器、bash / 文件工具、subagent、todo、JSONL 会话持久化和自动压缩。它挂载的是本仓库构建产物 ../../lib/index.js，需要本机已有能解析 @deepseek-ai/* 的 DeepSeek Harness checkout，并且 dsh 在 PATH 上。
运行时环境变量（摘自该示例的中文 README）：
| 变量 | 用途 |
|---|---|
DSH_TELEGRAM_TOKEN |
bot token（必填） |
DSH_TELEGRAM_ALLOWED_USER_IDS |
允许的用户 id，逗号分隔 |
DSH_TELEGRAM_ALLOW_ALL_USERS |
true 时放开所有用户（仅开发） |
DEEPSEEK_API_KEY |
传给 OpenAI 兼容端点的凭据 |
DEEPSEEK_BASE_URL |
dsh-llm-deepseek 使用的主机端点 |
DSH_CWD |
bash 与文件工具的工作目录 |
DSH_SESSION_ROOT |
JSONL 轨迹目录 |
DSH_SYSTEM_PROMPT |
编码 persona |
示例启动命令：
cd examples/telegram-agent
DSH_TELEGRAM_TOKEN=<token> DSH_TELEGRAM_ALLOW_ALL_USERS=true \
DEEPSEEK_API_KEY=<key> dsh --config cordis.yml
allowAllUsers=true 只适合本机试跑。对外服务应改成显式的 DSH_TELEGRAM_ALLOWED_USER_IDS，不要开全员访问。token 和白名单都从环境变量读入，cordis.yml 里不落密钥。
在 Telegram 里怎么说话¶
先用 @BotFather 建 bot、拿到 token，再把 token 和自己的用户 id 配进插件。进程起来之后，私聊里可用：
/start：建立会话，回复欢迎词Hello! I am the DeepSeek Harness agent. Send me a message or /help for commands./help：列出/start、/new、/clear、/help/new或/clear：换新会话，旧 agent 释放，回复Started a fresh session.- 普通文本：进入该 chat 的 agent，助手最终文本分片发回
模型侧看不到轮询帧和投递调用；命令也不会进上下文。工具中间进度不会作为独立 Telegram 消息流式发出，用户看到的是每条 assistant 输出对应的一组分片。
适用场景与注意事项¶
适合已经在跑 DeepSeek Harness、希望用 Telegram 私聊当展示层的人：出差时追问当前 agent、给 bot 发一句让它在本机工作区里改文件或跑命令。模型可见的工具集合完全取决于外围组合——示例里是 bash、read / write / edit、subagent、todo_write；只把插件加进 web profile、却没有对应工具层，私聊里就只有会话，没有那些工具。
README 列出的已知限制，使用前要按字面理解：
- 仅文本。 照片、文档、语音、贴纸和 caption 会被忽略。
- 仅私聊。 群聊 @ 提及和话题（topics）未处理。
- 没有 webhook。 进程必须能出站访问 Telegram API；国内网络若访问不到，这个包本身没有代理配置项。
- 没有投递重试。 除 HTML 失败回退纯文本外，发送失败记日志后丢弃。
- 组合层不热更新。 改完插件要重启 dsh 进程。
安全方面再强调一次。插件以当前 dsh 进程权限运行，示例里的 bash 与文件工具作用在 DSH_CWD（默认当前工作目录）上。Bot token 等同登录凭证，不要写进可提交的配置文件。白名单为空时拒绝所有人，这是有意的 fail closed，不要为了「先通一下」就在生产环境打开 allowAllUsers。
小结¶
telegram 把 Telegram 私聊接到 DeepSeek Harness 的 agent 会话上：长轮询收文本、一聊天一会话、HTML 分片回写。它是社区维护的后台桥接插件，不是官方应用，也不代替 LLM、工具和会话层。目录页与源码仓库如下，装之前核对许可证和当前提交：
- 目录页：https://deepseek-harness-plugin.com/zh-CN/plugins/telegram/
- GitHub：https://github.com/LoserFox/telegram
- 官方 Harness：https://github.com/deepseek-ai/deepseek-harness
