前言¶
DeepSeek Harness (DSH) 的核心理念是“一切皆插件”。当需要在即时通讯渠道中访问智能体时，开发者通常需要搭建额外的 Web 服务或配置 HTTP Webhook。下面介绍的 @blue/dsh-telegram-bot 是一个单功能插件，它利用长轮询机制，直接将 Telegram 机器人连接到 DSH 智能体，省去了公开端点配置和外部服务的依赖。
插件信息¶
- 名称：
@blue/dsh-telegram-bot - 维护者：Blue-2571
- 许可证：MIT
- 定位：一个单功能的 DSH 插件，通过长轮询将 Telegram 机器人连接到你的 dsh 智能体。
核心功能¶
- 长轮询连接：不依赖 Webhook，使用长轮询保持连接。
- 会话管理：一个聊天对应一个智能体（标识为
telegram:<chatId>），支持多轮对话上下文。 - 工具挂载：支持将 Agent 预设挂载到机器人会话，使其具备与 Web 界面相同的工具（如 bash、fs、ssh）。
- 权限控制：通过
allowedUserIds实现白名单访问控制。 - 命令支持：支持
/help、/reset、/status、/model等 Slack 风格命令。 - 消息处理：长回复会自动分割（遵循 Telegram 4096 字符限制），空闲会话会根据超时配置自动清理。
安装与启用¶
安装插件：
dsh plugin --profile web add @blue/dsh-telegram-bot
安装后，插件默认处于禁用状态。需要在 cordis.patch.yml 中启用并配置：
- id: dsh-telegram-bot
disabled: false
config:
telegram:
token: '123456:ABC-DEF...' # 从 @BotFather 获取的 Token
allowedUserIds: [6354114195] # 你的数字 Telegram 用户 ID
agent:
preset: standard # 挂载标准预设以获取完整工具
保存文件后，重启 Web Profile (dsh web)。
配置项¶
| 配置项 | 默认值 | 说明 |
|---|---|---|
enabled |
true |
主开关。 |
telegram.token |
'' |
Bot Token，从 @BotFather 获取。 |
telegram.allowedUserIds |
[] |
允许交互的用户 ID 列表（数字）。如果为空数组，则任何持有 Token 的人均可操作。 |
telegram.timeoutSeconds |
50 |
getUpdates 长轮询的超时时间。 |
telegram.pollIntervalMs |
500 |
轮询超时或出错后的间隔时间。 |
agent.cwd |
'' |
智能体会话的工作目录（默认为 dsh 的 cwd）。 |
agent.provider / agent.model |
'' |
覆盖模型选择；留空则使用部署默认值。 |
agent.preset |
'' |
挂载的 Agent 预设 ID（留空则使用部署默认值）。 |
agent.maxMessageLength |
4000 |
单条输出消息的最大字符数。 |
agent.idleTimeoutMs |
1800000 |
会话空闲超时时间（毫秒），0 表示永不清理。 |
agent.instructionPrefix |
'' |
每条用户消息前缀。 |
可用命令¶
/help：显示命令帮助信息。/reset：清空当前聊天的上下文，重置智能体。/status：显示当前活跃的聊天/智能体状态。/model：显示当前选择的模型。
安全与注意事项¶
- 默认禁用：安装后必须手动在
cordis.patch.yml中启用。 - 白名单强制：如果
allowedUserIds为空数组，则任何持有 Token 的人都可以执行工具（包括 bash、fs 等），这在生产环境中存在风险。 - Token 保护：
cordis.patch.yml包含敏感的 Bot Token，请确保该文件权限私有，或通过环境变量引用（如!!js process.env.TG_BOT_TOKEN）。 - 长度限制：长回复会被 Telegram 的 4096 字符限制截断。
适用场景¶
- 需要在 Telegram 中通过命令行或文件系统工具操作 DSH 的开发者。
- 想要避免部署 Webhook 服务，直接利用现有 DSH 进程进行 IM 交互的场景。
