@loserfox/telegram

Readme

# telegram

## 安装（DSH profile bundle）

```sh
# 从本仓库 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`](examples/telegram-agent/README.zh.md) 示例）。
- 卸载：`dsh plugin --profile web remove telegram`。
- 安装后需重启目标 profile 的 DSH 进程（组合层变更不参与 HMR 热更新）。

## 概述

`telegram` 插件通过 Bot API 长轮询把 Telegram 聊天桥接到 harness agent 会话，每个聊天一个 agent 会话。设计参照 [Hermes](https://github.com/NousResearch/hermes-agent) 的 telegram 平台适配器——每聊天会话、用户白名单、HTML 格式化、4096 字符分片、typing 指示——裁剪为 harness 的纯文本接缝。[`telegram-agent`](examples/telegram-agent/README.zh.md) 是可运行的 `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 风格的发送重试与投递账本留待后续。