dsh-plugin-telegram

dsh-plugin-telegram

DeepSeek Harness (DSH) plugin for Telegram Bot integration. Provides tools for sending and receiving Telegram messages, with optional long-polling for incoming messages.

Based on the Telegram channel implementation from QwenPaw, adapted for the DSH Cordis plugin framework.

Features

• Send messages with Markdown/HTML formatting
• Send photos, documents, audio, video and voice notes via file_id, URL or local path (voice text is synthesized by a local Qwen3-TTS service)
• Inbound voice transcription (🎧) — voice notes are transcribed by a local Whisper proxy and answered without a round-trip
• Edit and delete existing messages
• Long-polling for incoming messages (optional)
• Agent integration: Inject Telegram messages into DSH agent loop for AI-powered conversations
• Multi-bot: run several Telegram bots in one plugin instance (bots: config, per-bot tokens/routing, isolated state)
• Live subagent board: pinned real-time subagent status (🧩) per chat
• /autopilot: per-chat fully-autonomous mode (global write + auto-approve + auto-adopt)
• Access control via allowed chats/users lists
• Automatic reconnection with exponential backoff
• Rate limit handling with Telegram API compliance
• Message chunking for content exceeding Telegram's 4096-char limit

Tools Provided

Telegram 会话管理命令（直接发给 bot）

参考 QwenPaw 的命令风格实现：

普通消息路由到当前聊天的 active 会话；无显式路由时落到默认（第一个）会话。 /new 创建的会话继承默认会话的工作目录（cwd）、模型（provider/model， 来自 agent.options）和 agent preset（meta.agentPreset，setup 时 agentPresets.mount 挂载）——preset 决定工具目录（Read/Write/Edit/Bash 等）、 提示段和 skill 清单，随插件卸载一起销毁。

命令菜单在 poller 启动时通过 Bot API setMyCommands 注册，Telegram 客户端 输入 / 即可看到全部命令的自动补全。

Installation

1. 设置 Token（三种方式，优先级从高到低）

方式一：DSH Credentials 系统（推荐，最安全）

编辑 $DSH_HOME/.credentials.yaml（权限 0600，只有所有者可读）。 该文件是顶层 YAML mapping：key 为凭据引用名，value 为字符串（建议加引号）：

TELEGRAM_BOT_TOKEN: "你的token"

也可在 DSH Web UI 的 Credentials 设置页写入。插件启动时通过 ctx.credentials.resolve('TELEGRAM_BOT_TOKEN') 读取。

注：DSH 没有 dsh credential set 子命令。

方式二：环境变量

# 一次性传入
TELEGRAM_BOT_TOKEN='你的token' dsh web --patch ./cordis.yml

# 或写入 ~/.bashrc / ~/.zshrc
export TELEGRAM_BOT_TOKEN='你的token'

方式三：写在 cordis.yml 中（不推荐，会明文存储）

config:
  botToken: '你的token'  # 不推荐

多 bot：设置多个 token

配置 bots: 数组跑多个 bot 时，每个 bot 一个 token，互相隔离。隔离的关键是 让每个 bot 指向不同的来源键——否则两个 bot 都会默认读同一个 TELEGRAM_BOT_TOKEN，第二个 bot 会错误地拿到第一个 bot 的 token。

三种方式的多 bot 写法（优先级从高到低，与单 bot 一致： bots[].token（明文）→ 环境变量 process.env[envKey] → DSH credentials）：

方式一：DSH Credentials 系统（推荐） — 在 $DSH_HOME/.credentials.yaml 里为每个 bot 写一条独立的凭据（key 名自取），再让每个 bot 的 envKey 指向对应的 key：

# $DSH_HOME/.credentials.yaml
TELEGRAM_BOT_TOKEN: "alice的token"
TELEGRAM_BOT_TOKEN_BOB: "bob的token"

# cordis.yml
config:
  pollingEnabled: true
  bots:
    - id: alice
      envKey: 'TELEGRAM_BOT_TOKEN'        # 默认值，可省略
    - id: bob
      envKey: 'TELEGRAM_BOT_TOKEN_BOB'    # 指向自己的凭据 key

方式二：环境变量 — 同样每个 bot 一个变量，envKey 指向它：

export TELEGRAM_BOT_TOKEN='alice的token'
export TELEGRAM_BOT_TOKEN_BOB='bob的token'

config:
  bots:
    - id: alice        # envKey 默认 TELEGRAM_BOT_TOKEN
    - id: bob
      envKey: 'TELEGRAM_BOT_TOKEN_BOB'

方式三：明文写在 cordis.yml 的 bots[].token（不推荐）

config:
  bots:
    - id: alice
      token: '123456...:AA...'
    - id: bob
      token: '789012...:BB...'

要点：

• 不填 envKey 的 bot 一律读 TELEGRAM_BOT_TOKEN——多 bot 时除了第一个 bot，其余每个都必须给 envKey（或 credentialKey）指定不同的键。
• 某个 bot 的 token 三个来源（明文 / 环境变量 / credentials）都取不到时， 该 bot 跳过并打 warn 日志（不报错）；全部 bot 都取不到时插件降级为 tools-only（工具仍注册，调用时返回提示）。
• 每个 bot 的完整字段与回退规则见下方 "Multi-Bot Configuration"。

2. Configure in cordis.yml

- insert:
    - id: telegram
      name: '/path/to/dsh-plugin-telegram/lib/index.js'
      config:
        # botToken 可以不填，插件按以下优先级自动查找：
        # 1. config.botToken（明文，不推荐）
        # 2. 环境变量 TELEGRAM_BOT_TOKEN
        # 3. DSH Credentials 系统中的 TELEGRAM_BOT_TOKEN
        defaultChatId: '123456789'
        pollingEnabled: false

3. Start DSH with the plugin

dsh web --patch ./cordis.yml

Configuration

Multi-Bot Configuration

Run multiple Telegram bots in one plugin instance. Add a top-level bots: array; every item is one bot. This is a v0.6.0 feature — the legacy single-bot config (top-level fields, no bots) keeps working unchanged (see "Backward compatibility" below).

Each bots[] item supports the same per-bot fields as the top-level config. An item field left unset falls back to the top-level value of the same field, so you only spell out what differs per bot.

Other top-level fields (longPollTimeout, maxMessageLength, parseMode, pollingEnabled, replyPrefix, …) are also readable per item when set.

id auto-generation — when an item has no id:

• it has a resolvable token → id = "bot-" + token.slice(0, 8);
• otherwise (no token) → id = "default".
• The legacy single-bot fallback (no bots field) always yields id "default".

Backward compatibility — omit bots (or set bots: [] / a YAML-coerced {}): the plugin builds one bot, id "default", entirely from the top-level fields. Existing single-bot cordis.yml files need no change and behave bit-identically.

Missing-token degradation — a bot whose token resolves to nothing (config + envKey + credentialKey all empty) is skipped with a warn log; it never throws. It is still registered (so clientFor/meFor report a precise "skipped" error) but gets no client/poller/command-menu. If all bots are skipped the plugin runs tools-only (tools still register; their !client guards return a helpful error when called) — the same "missing token → tools-only" semantics as the legacy path.

Per-bot token resolution priority (per item, in order): token (plain) → process.env[envKey] → DSH credentials envKey → DSH credentials credentialKey (the last one only when it differs from envKey). Using a distinct envKey per bot is the recommended way to avoid a second bot accidentally picking up the first bot's token.

Sending tools & telegram_get_info under multi-bot

• Every send/edit/delete/media tool (telegram_send_message, telegram_send_photo, telegram_send_document, telegram_edit_message, telegram_delete_message, …) now accepts an optional bot parameter (a bot id). Resolution order: (1) explicit bot — must be a known, connected bot, else a clear tool error; (2) the owning bot of the target chat when exactly one bot routes that chatId (composite-key reverse lookup, the bot whose poller last routed a message for that chat); (3) when two bots share one chatId (e.g. both bots' private chats with the same owner), the calling agent decides (v0.6.5): sends go back out the bot that owns the agent running the tool call — not the first bot in the registry, which is what used to make bot B's photos arrive from bot A; (4) the first/legacy bot. A single-bot config is unaffected.
• telegram_get_info now returns an ARRAY — one entry per configured bot: { id, username, botId, name, connected, defaultChat }. A legacy single-bot config returns exactly one entry (id: "default"), so single-bot callers see one item as before.
• telegram_get_updates accepts a bot parameter; each bot keeps its own manual poll offset (independent per bot, and independent of that bot's background poller), so a manual poll on one bot never advances another's stream.

Two-bot example

- insert:
    - id: telegram
      name: '/path/to/dsh-plugin-telegram/lib/index.js'
      config:
        pollingEnabled: true
        longPollTimeout: 30
        # Top-level values act as the per-bot defaults (inherited when an item omits a field).
        requireMention: true
        agentResponseMode: 'direct'
        bots:
          - id: alice
            token: '123456...:AA...'        # or leave empty + envKey below
            defaultChatId: '100000000'
            allowedUsers: ['100000000']
          - id: bob
            envKey: 'TELEGRAM_BOT_TOKEN_BOB' # reads its own env var (no token on the item)
            defaultChatId: '200000000'
            allowedUsers: ['200000000']

Multi-bot caveats

• chatId is NOT globally unique across bots — the same numeric chatId can exist under two bots. So all per-chat state (dedup, board, indicator, agent routing) is keyed by the composite key k(botId, chatId) ("botId::chatId"), never by bare chatId. Messages are therefore not cross-deduped across bots: the same (chatId, messageId) delivered through two different bots is processed once per bot.
• Isolate tokens with envKey so a second bot does not inherit the first bot's TELEGRAM_BOT_TOKEN (the default envKey/credentialKey is the same TELEGRAM_BOT_TOKEN; point each extra bot at its own key).
• getUpdates offset is per-bot (Telegram maintains one update stream per bot) — the plugin tracks a separate manual offset per bot for the telegram_get_updates tool, and each background poller tracks its own cursor (offset file telegram-poller-offset-<botId>.json).

Inbound voice transcription (🎧)

When the user sends a voice note, the plugin transcribes it via the local Whisper service (sttEndpoint, default the same proxy transcribe_audio uses) and, in the same step:

1. Replies with the recognized text directly under the voice bubble — a reply to the voice message is the only way to show it "on the next line" (Telegram bots cannot edit another user's message). It is a quiet, plain-text message (🎧 …) so arbitrary recognized text can't trip the entity parser.
2. Reuses that transcript in the note injected to the agent, so the agent already has the spoken words and does not need to call transcribe_audio again (saves a round-trip and lets the agent answer immediately).

Requires forwardInboundMedia: true (the file must be downloaded to transcribe). The transcript is shown verbatim — no LLM re-phrase — so display is fast and cost-free. The whole feature is best-effort: if the service is down or the audio is silent, the voice note is still injected and answered normally (just no transcript line). Set voiceTranscribe: false to turn it off.

Live trajectory (tool calls + thinking)

While the agent works on a Telegram message, a single editable message shows a rolling trail of its recent activity (in both direct and tool modes), plus a continuous "typing…" chat action. Modelled on QwenPaw's Telegram channel edit-in-place streaming. Each recent item is one line:

• 💭 <reasoning 片段> — a chunk of the model's thinking (streamed as it happens);
• 🔧 <tool>：<参数预览> — a tool call (name + a compact argument preview).

The whole message is tail-truncated to progressMaxChars, so the newest items stay visible and the oldest scroll off (each line is separately capped at progressPerBlockChars). The final reply is not shown here — it is sent as its own message when the turn ends.

It is deleted the moment the turn ends (turn/end), self-cleans after progressTimeoutSec, and never shows for turns that finish before progressDelaySec. Set progressEnabled: false to turn it off. It is purely best-effort — a Telegram failure never affects the real reply.

Live subagent board (🧩)

When a session spawns subagents (via the subagent / subagent_fork tools), the plugin keeps a single pinned message per chat that shows, in real time, every subagent currently working — and each finished one, locked in place. Each subagent occupies at most two lines:

🧩 子代理看板 · 2 工作中 / 1 完成
🟢 重构认证模块 · 工作中
🔧 read src/auth/session.js
🟢 跑集成测试 · 工作中
正在启动…
✅ 整理依赖 · 已完成
已完成 · 用时 42s

• Line 1 — status emoji + a short task name + status word (工作中 / 已完成 / …). The task name comes from the child's subagent/descriptor label (or the subagent tool call's description), truncated to fit.
• Line 2 — what it is doing right now: the child's most recent tool call (🔧 name + args), else its latest reasoning, else 正在启动… until activity appears.
• Real-time — a ticker re-reads the live child sessions every subagentBoardRefreshMs (default 2 s) and edits the same message in place (edits are throttled to ~1.5 s so Telegram's edit rate limit is never hit).
• Pinned — the board message is pinned on first subagent (the "fixed" part) so it stays at the top of the chat; subagentBoardPin: false disables pinning.
• Locked on end — when a subagent finishes (subagent/end), its row freezes with the terminal state and elapsed time and is never re-read. A re-start (a continuable child waking for a new epoch) re-opens the row as working.

Lifecycle edges come from DSH's subagent/start / subagent/end events (a global listener, so the parent-scope filter is bypassed). A presence sweep of the live agents.list() runs on the same ticker as a backstop: it starts any child the event bus missed and locks any that vanished (after a short grace), so the board stays correct even on a host where the events never reach the plugin. Only direct children are shown by default; set subagentBoardIncludeDescendants: true to include nested subagents. The overflow beyond subagentBoardMaxRows collapses into a … 另有 K 个未显示 line to keep the message under Telegram's 4096-char limit.

/new (or /clear) tears down the chat's board (unpin + delete); the board is also torn down on plugin unload. Set subagentBoardEnabled: false to turn the feature off. Like the progress indicator it is purely best-effort — a Telegram hiccup never affects the real reply or the subagents themselves.

Tool-guard approval (permission prompts on the phone)

When the agent's permission policy is ask (the default) and a tool call needs a decision — for example a sandbox escalation like writing a file outside the workspace, or a guarded pre-execute check — DSH resolves it through an approval/request waterfall of answerers. If no answerer claims the request it fails closed: the user sees nothing and the action is denied.

Before this feature, the Telegram plugin registered no answerer, so a Telegram agent's ask was claimed by the web host (the browser UI, invisible on the phone) or failed closed — the reported "no permission prompt on the phone" bug. This