# 从本仓库 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 节奏下限，避免即时空传输让事件循环空转。
每条入站聊天消息，模型在该聊天会话中收到逐字的一条用户消息。本包不添加系统提示词或工具 schema；它们来自外围 cordis.yml 的插件。命令（/start、/new、/clear、/help）不会到达模型。
数据相关的用户消息 token 进入保留的会话历史，后续回合会重发，直到其它包压缩它们。轮询帧、聊天簿记与投递调用不增加模型上下文 token。
仅追加；新可见内容跟在可复用请求前缀之后，不会使既有 KV-cache 条目失效。
- 仅文本消息——照片、文档、语音、贴纸与 caption 被忽略。
- 仅私聊——群聊 @ 提及与话题（topics）未处理。
- 每条 assistant 输出一条消息——工具中间进度不会作为独立可编辑 Telegram 消息流式发送。
- 仅长轮询——无 webhook 模式，主机需可出站访问 Telegram API。
- 除纯文本回退外无重试——投递失败记录日志后丢弃；Hermes 风格的发送重试与投递账本留待后续。