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）。