dsh-telegram-bridge：Telegram 與 DeepSeek Harness 的橋接插件

前言¶

DeepSeek Harness (DSH) 採用了插件化架構，旨在將 Agent 運行環境與交互界面解耦。dsh-telegram-bridge 是一個運行在 DSH Profile 內部的插件，它將 Telegram 私聊與 DSH Agent 會話連接起來。通過這個插件，你可以在 Telegram 中直接與 DSH Agent 進行消息交互、管理會話、控制模型參數以及查看運行狀態，無需切換到命令行或 Web UI 界面。

核心功能¶

該插件提供了從交互到呈現，再到穩定性的完整能力鏈路：

交互與消息管理：支持私聊橋接、實時狀態行（顯示當前活動或輪換中性文案，避免長任務假死感）、消息隊列與打斷、獨立失敗重試、以及重新生成功能。
會話與設置：支持輕量級多會話管理，保留最近 N 個會話並支持一鍵切換；支持動態切換模型、推理強度和 Agent preset；提供 dsh Web UI 設置面板。
回覆呈現：支持結構化渲染（如表格、列表、Callout 等）、富文本支持、以及智能切分長消息。
穩定性保障：包含隊列持久化（重啓恢復）、文件日誌與輪轉、狀態備份與回退、啓動自檢、健康檢查以及 Telegram 429 限流保護。

安裝與啓用¶

通過官方 CLI 安裝插件到 web profile：

dsh plugin --profile web add github:JxaMe/dsh-telegram-bridge

安裝完成後，驗證插件是否註冊成功：

dsh --profile web --dump-config | grep dsh-telegram-bridge

隨後需要重啓 dsh web 進程以加載插件。

配置¶

配置文件位於 ~/.dsh/dsh-telegram-bridge/config.json，首次啓動時會自動生成示例配置。

{
  "botToken": "123456:ABC-YOUR-REAL-BOT-TOKEN",
  "ownerId": 123456789,
  "projectRoot": "/home/you",
  "proxyEnabled": false,
  "proxyUrl": "http://127.0.0.1:7890",
  "defaultProvider": "",
  "defaultModel": "",
  "defaultReasoningEffort": "",
  "defaultAgentPreset": "",
  "errorDisplayMode": "raw",
  "htmlFormatting": true,
  "typingIndicator": true,
  "statusLine": true,
  "queueLimit": 20,
  "maxSessionsPerChat": 5,
  "debugLogging": false
}

配置說明與安全注意：
* 修改配置文件後，必須重啓 dsh-telegram-bridge 插件才能生效。
* 通過 Web UI 設置面板修改配置時，保存後同樣需要重啓。
* Web 設置端點僅監聽迴環地址，防止未授權訪問。
* Web 端點需要 CSRF token 保護，POST 請求需提供 x-csrf-token 請求頭或請求體中的 csrfToken 字段。

常用命令¶

在 Telegram 聊天中，你可以使用以下命令進行操作：

/start - 顯示主菜單
/new - 開始新對話
/interrupt - 打斷當前任務並清空隊列
/status - 查看會話、隊列、模型、Token 等狀態
/health - 查看運行時長、消息/回覆/錯誤計數
/sessions - 查看和切換最近會話
/menu - 打開設置面板
/commands - 打開聊天內命令菜單
/help - 顯示命令幫助

工作原理¶

該插件運行在 DSH profile 內部（通常是 web），直接調用 DSH 原生服務，無需額外部署服務器或 Webhook。

Telegram 端：使用 grammY 庫進行長輪詢，處理消息接收、命令解析和富文本渲染。
DSH 端：插件作爲 dsh 的擴展，利用 apiProxy 處理會話與模型調用，利用 agents 處理任務取消，利用 session 事件監聽 Agent 回覆與狀態變化。
數據流：Telegram Bot API -> dsh-telegram-bridge -> DSH API/Agents/Session -> Telegram 回覆。

適用場景與注意¶

該插件適合希望利用 Telegram 作爲移動端或即時通訊入口來控制本地或遠程 DSH Agent 的用戶。在使用前，請確保已擁有 Telegram Bot Token 和對應的 User ID。

由於插件運行在 DSH 進程的權限下，建議在安裝前檢查源代碼（項目使用 TypeScript 嚴格模式）及許可證（MIT）。