前言¶

DeepSeek Harness (DSH) 的核心設計理念是“一切皆插件”。當需要在 Telegram Bot 中與 agent 交互時，手動編寫橋接代碼會涉及大量 Bot API 調用邏輯，且需要處理會話映射、長任務隊列等細節。dsh-channel-telegram 提供了一個獨立的解決方案，通過長輪詢接收私聊消息，並將 Telegram 聊天映射爲 DSH agent 會話，無需修改 DSH 源碼即可啓用。

插件定位¶

這是一個 Telegram 薄橋接插件。由 LosEcher 維護。它將 DSH 的 agent 通過 Telegram Bot 暴露出來，走與 ACP 橋完全相同的驅動模式（agents.create → agent.followup → agent.whenIdle），回覆最終 assistant 文本。插件獨立交付，DSH 的 Host loader 支持絕對路徑插件 entry。

核心功能¶

根據已覈實事實，該插件具備以下能力：
* 長輪詢接收私聊消息。
* 按 chatId 映射 DSH agent 會話，會話 ID 爲 telegram-<chatId>。
* 長任務串行隊列：每個 chat 一個隊列，長任務不阻塞輪詢。
* 支持命令：/start、/help、/new、/status。
* 4096 分塊消息回覆。
* 409/401 錯誤自動處理。

安裝與啓用¶

該插件作爲獨立 bundle 提供，不涉及官方安裝命令。啓用流程如下：

1. 獲取 Bot Token
   在 Telegram 中找到 @BotFather 創建 bot，並獲取 Token。

2. 配置環境變量
   確保 DSH 進程環境變量中包含 TELEGRAM_BOT_TOKEN（默認變量名，可通過 tokenEnv 修改）。如果通過絕對路徑引入源碼開發，需確保 name 爲絕對路徑。

3. 獲取 Chat ID
   給 @userinfobot 發送任意消息，即可獲取用於配置的 chatId。

4. 合併配置文件
   將插件的 cordis.telegram.yml 內容合併進 DSH 的配置文件。通常合併進 $DSH_HOME/cordis.patch.yml（全部 profile）或 $DSH_HOME/profiles/<name>/cordis.patch.yml（單 profile）。配置中的 allowlist 填入你的私聊 ID（空數組表示全部拒絕）。

5. 重啓服務
   重啓 dsh web。日誌中應出現 [dsh-channel-telegram] connected as @...。

- insert:
    - id: channel-telegram
      name: dsh-channel-telegram
      config:
        tokenEnv: TELEGRAM_BOT_TOKEN
        allowlist: [123456789]            # 你的私聊 id
        # workspace: /abs/path            # 可選，agent 會話 cwd（默認 ~/.dsh-telegram/workspace）
        # provider: los-gateway           # 可選：agent 走的 provider 路由
        # model: deepseek                 # 可選：該路由上的模型

典型用法¶

配置完成後，可以通過私聊與 Bot 交互。

• 會話管理：每聊一會話對應一個 telegram-<chatId>，上下文連續。使用 /new 命令可銷燬重建會話。
• 命令響應：
  • /start：啓動會話。
  • /help：查看幫助。
  • /new：銷燬當前會話並創建新的。
  • /status：查看當前會話狀態。
• 消息回覆：Bot 會發送 typing 動作，並在整輪迴復結束後發送 assistant 文本。如果 assistant 文本超過 4096 字符，會自動分塊發送。

適用場景與注意¶

• 依賴要求：依賴 @deepseek-ai/cordis (>=4.0.0 <5.0.0)。
• 功能限制：
  • 無流式輸出：需要等待整輪任務完成纔回復。
  • 無媒體處理：目前僅支持文本消息接收。
  • 內存會話：會話映射在內存中，重啓 DSH 進程後 /new 語義自然達成（即新進程需要重新配置 allowlist）。
  • 消息去重：依賴 Bot API 的 offset 機制保證不重投，但 DSH 側無額外去重邏輯。
• 安全機制：allowlist 是唯一的安全閘門。非 allowlist 的私聊首次收到“未授權”提示，非私聊消息會被忽略。Agent 繼承宿主全局權限設置，建議在低權限 preset 或獨立 profile 下運行。

結語¶

dsh-channel-telegram 通過長輪詢和 thin bridge 的設計，爲 DSH 提供了標準化的 Telegram 交互能力。它專注於私聊場景，通過命令和會話管理機制，在保持輕量級的同時提供了必要的功能覆蓋。對於需要通過 Telegram 調用 DSH agent 的用戶，這是一個可以直接集成的選擇。

• 插件目錄
• GitHub 倉庫