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 示例）。 - 卸载：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 风格的发送重试与投递账本留待后续。