telegram
IntegrationsLoserFox/telegram
Telegram Bot API bridge plugin: long polling, per-chat sessions, HTML formatting.
- dsh-plugin
Verification and compatibility
This section shows evidence collected by the catalog. Undeclared information is labeled as unknown.
- Current-version compatibility
- Verified on the catalog Harness version
- Declared Harness range
- Not declared
- Declared platforms
- Not declared
- Profiles
- web
- Build approval
- Unknown
- Permissions
- Not declared
- External services
- Not declared
- Telemetry
- Unknown
This is not a security endorsement. Review source, permissions, and configuration before installing.
View evidence and scope
Verification covers only the named source, version, and Harness environment. It does not guarantee future compatibility.
github:LoserFox/telegram#a0a9ca11e427b62217250e2e561f6ad3c49d13f2- The manifest and static structure passed checks; a runtime load check has not completed.
README
telegram
安装（DSH profile bundle）
# 从本仓库 checkout 安装到 profile（web / headless 等），bundle 声明自动加入组合层
dsh plugin --profile web add <dir|git-url>
# 验证
dsh --profile web --dump-config | grep telegram
- 插入行 id：
telegram（cordis.patch.yml）；不声明模型面工具或技能——它是把 Telegram 聊天桥接到 agent 会话的后台服务插件。 - 加载即需要 token：缺少 bot token（配置
token或环境变量DSH_TELEGRAM_TOKEN）时apply直接报错；没有 token 不会惰性启动。 - 宿主前置条件：dsh 组合必须挂载
agents服务（@deepseek-ai/dsh-agent）；LLM 适配器、会话与工具来自外围cordis.yml（见telegram-agent示例）。 - 卸载：
dsh plugin --profile web remove telegram。 - 安装后需重启目标 profile 的 DSH 进程（组合层变更不参与 HMR 热更新）。
概述
telegram 插件通过 Bot API 长轮询把 Telegram 聊天桥接到 harness agent 会话，每个聊天一个 agent 会话。设计参照 Hermes 的 telegram 平台适配器——每聊天会话、用户白名单、HTML 格式化、4096 字符分片、typing 指示——裁剪为 harness 的纯文本接缝。telegram-agent 是可运行的 cordis.yml 应用。
接线
inject: ['agents']。每条已授权文本消息为每个聊天创建或复用 agent（ctx.agents.create），经 followup 以用户消息转发文本，并把每条 assistant/message 文本作为分片的 HTML 格式 Telegram 消息送回聊天。命令：/start（欢迎）、/new 与 /clear（新会话，旧 agent 释放）、/help。LLM 适配器、会话与工具来自外围 cordis.yml。
配置
| 键 | 默认 | 含义 |
|---|---|---|
token | '' | @BotFather 创建的 bot token；为空时回退到 DSH_TELEGRAM_TOKEN |
allowedUserIds | [] | 允许与 bot 对话的 Telegram 用户 id；空列表拒绝所有人 |
allowAllUsers | false | 允许任意用户（仅开发用） |
provider | deepseek-official | 传给每个创建 agent 的 LLM provider id |
model | deepseek-v4-flash | 传给每个创建 agent 的模型 id |
maxMessageLength | 4096 | 每条 Telegram 消息的长度上限 |
pollingTimeoutSec | 30 | 长轮询超时（秒） |
缺少 token 时加载即报错（fail loud）。未配置白名单时 bot 拒绝所有用户（fail closed）。TelegramConfig 还接受仅运行时使用的 client 与 sleep 接缝供测试使用；生产环境使用全局 fetch 与真实定时器。所有错误经 ctx.logger 记录且 bot token 被脱敏。
投递语义
- assistant 文本按保守的 Markdown 子集转换（围栏代码 →
<pre>、行内代码 →<code>、**粗体**→<b>，其余 HTML 转义），并按maxMessageLength分片，优先在换行、中文句号、句点+空格处断行。 - Telegram 拒绝 HTML 正文（分片后实体不完整）时，该片回退为纯文本发送。
turn/start发送typing聊天动作；投递为 fire-and-forget，逐片记录日志。- 单条长轮询循环服务所有聊天；空批次休眠 50ms 节奏下限，避免即时空传输让事件循环空转。
模型体验
Telegram 用户消息
模型看到什么
每条入站聊天消息，模型在该聊天会话中收到逐字的一条用户消息。本包不添加系统提示词或工具 schema；它们来自外围 cordis.yml 的插件。命令（/start、/new、/clear、/help）不会到达模型。
Token 影响
数据相关的用户消息 token 进入保留的会话历史，后续回合会重发，直到其它包压缩它们。轮询帧、聊天簿记与投递调用不增加模型上下文 token。
KV Cache 影响
仅追加；新可见内容跟在可复用请求前缀之后，不会使既有 KV-cache 条目失效。
已知限制与待办
- 仅文本消息——照片、文档、语音、贴纸与 caption 被忽略。
- 仅私聊——群聊 @ 提及与话题（topics）未处理。
- 每条 assistant 输出一条消息——工具中间进度不会作为独立可编辑 Telegram 消息流式发送。
- 仅长轮询——无 webhook 模式，主机需可出站访问 Telegram API。
- 除纯文本回退外无重试——投递失败记录日志后丢弃；Hermes 风格的发送重试与投递账本留待后续。
