前言¶
DeepSeek Harness (DSH) 是一个基于插件的系统，旨在提供灵活的智能体控制能力。在本地开发或部署场景中，通常需要通过 Web UI 来管理会话和查看输出。kevin66z0/dsh-telegram 插件为 DSH 提供了一个 Telegram 远程控制入口，允许用户通过移动端直接与 Agent 交互，实现会话绑定、实时查看流式回复以及快捷操作。
插件简介¶
该插件由 Kevin66Z0 维护，开源协议为 MIT。它将 Telegram 作为一个统一的控制台，通过白名单机制管理访问权限，确保会话安全。
核心功能¶
- 完整会话控制台：支持绑定会话、查看会话详情、发送文本提示，并在单条消息中实时编辑显示回复。
- 实时流式回复：助手输出以流式方式在消息中编辑呈现，包含思考过程和工具调用步骤，最终以 HTML 格式定稿。
- 交互式问题按钮：当智能体调用交互式问题时，界面会生成可点击的 Inline Keyboards，用户无需输入文本即可回答。
- 一键键盘：提供快捷操作行，如
/create（创建）、/archive（归档）、/attach（绑定）和/stop（停止）。 - 安全默认：采用白名单机制，只有被授权的聊天 ID 可以与机器人通信，其他访问会被拒绝并返回无权访问提示。
- 密钥永不落地磁盘：机器人令牌通过环境变量引用（
!!js process.env.TELEGRAM_BOT_TOKEN），不直接写入配置文件。 - 冷会话恢复：通过 Host 的 apiProxy 通信，支持冷会话恢复和队列消息语义。
安装与启用¶
环境要求¶
- Node.js >= 22.19
- 已安装 DeepSeek Harness 源码目录（推荐）或已运行的 DSH 部署
- 从 @BotFather 获取的 Bot Token
- 允许出站访问 api.telegram.org
安装步骤¶
- 克隆或下载插件代码。
- 运行安装脚本，将插件挂载到 DSH 目录：
./install.sh /path/to/deepseek-harness
配置步骤¶
- 设置环境变量：在
DSH_HOME/.env中注入令牌，并设置 600 权限：
echo 'TELEGRAM_BOT_TOKEN=<token-from-@BotFather>' >> "$DSH_HOME/.env"
chmod 600 "$DSH_HOME/.env"
- 配置白名单：在
$DSH_HOME/settings.yaml中配置允许访问的聊天 ID：
telegram:
allowChatIds: [123456789]
- 重启服务：重启 DSH 服务使配置生效。
典型用法¶
插件通过 Telegram 机器人命令进行操作。以下是主要命令列表：
/attach [scope|n|id|none|arc]：绑定当前聊天到指定会话。/create：打开创建子菜单。/operate：打开操作子菜单。/new [path|n|none]：创建一个新会话。/fork [n|id]：从上一个完成的回合分叉创建会话。/archive [n|id]：归档指定会话。/status [n|id]：查看会话详情。/model [name]：设置全局默认模型。/rename [title]：重命名当前绑定的会话。/preset [name|n]：选择预设的 Agent 配置。
安全与注意事项¶
- 白名单限制：插件默认拒绝所有访问，必须在配置中指定
allowChatIds。 - 无入站监听：插件不监听任何入站端口，仅通过 Telegram 的出站长轮询通信，适合在 NAT 后运行。
- 令牌管理：令牌存储在环境变量中，若泄露可通过 @BotFather 快速撤销并重新生成。
- 依赖要求：必须满足 Node.js >= 22.19 的版本要求。
总结¶
dsh-telegram 为 DeepSeek Harness 提供了一个安全、轻量的移动端控制方案。通过 Telegram，开发者可以在任何设备上管理 Agent 会话，无需依赖 Web UI。所有敏感操作（如令牌存储、会话绑定）均遵循安全最佳实践。
