# @blue/dsh-telegram-bot

[English](README.md) · [简体中文](README.zh-CN.md)

一个极简、单一用途的 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）插件：通过 **long polling** 把 **Telegram 机器人**接入你的 dsh 智能体 —— 无需公网地址。

灵感来自 [dsh-im-hub](https://github.com/ThreeBody6666/dsh-im-hub)，但精简到只保留 Telegram：单适配器、无 Web 设置卡片、无 HTTP webhook。

- 每个聊天一个 agent（`telegram:<chatId>`），多轮上下文保留。
- **agent preset 挂载**：设置 `agent.preset` 后，机器人会话挂载该 preset，获得与 Web GUI 会话相同的工具（bash、fs、ssh、...）。
- 白名单访问控制（`allowedUserIds`）。
- 类 Slack 命令：`/help` `/reset` `/status` `/model`。
- 长回复按 Telegram 4096 字符上限拆分。
- 空闲会话在 `agent.idleTimeoutMs` 后释放。

## 安装

```bash
dsh plugin --profile web add @blue/dsh-telegram-bot
```

该行**默认禁用**。在 profile 的 `cordis.patch.yml` 中启用：

```yaml
- id: dsh-telegram-bot
  disabled: false
  config:
    telegram:
      token: '123456:ABC-DEF...'   # 从 @BotFather 获取
      allowedUserIds: [6354114195] # 你的数字 Telegram user id
    agent:
      preset: standard             # 挂载 standard preset 以获得完整工具集
```

然后重启 profile（`dsh web`）。

## 配置

| 键 | 默认值 | 说明 |
| :--- | :--- | :--- |
| `enabled` | `true` | 总开关。 |
| `telegram.token` | `''` | 机器人 token（来自 [@BotFather](https://t.me/BotFather)）。 |
| `telegram.allowedUserIds` | `[]` | 允许对话的数字 user id；空 = 任何人。**生产环境务必设置。** |
| `telegram.timeoutSeconds` | `50` | getUpdates 长轮询超时。 |
| `telegram.pollIntervalMs` | `500` | 轮询超时/出错后的间隔。 |
| `agent.cwd` | `''` | agent 会话工作目录（默认 dsh 进程 cwd）。 |
| `agent.provider` / `agent.model` | `''` | 覆盖模型；空 = 部署默认。 |
| `agent.preset` | `''` | 机器人会话挂载的 preset id（'' = 部署默认）。 |
| `agent.maxMessageLength` | `4000` | 单条外发消息最大字符数。 |
| `agent.idleTimeoutMs` | `1800000` | 聊天空闲多久后释放 agent（0 = 永不）。 |
| `agent.instructionPrefix` | `''` | 附加到每条用户消息前的前缀。 |

## 命令

| 命令 | 作用 |
| :--- | :--- |
| `/help` | 显示命令帮助。 |
| `/reset` | 清空当前会话上下文（重建 agent）。 |
| `/status` | 显示活跃会话 / 智能体。 |
| `/model` | 显示当前模型。 |

## 安全

- **务必设置白名单。** `allowedUserIds` 为空意味着任何拿到 token 的人都能驱动你的智能体 —— 而它可以执行主机上的工具。
- token 存放在 profile 的 `cordis.patch.yml` 中，请保持该文件私有（或通过 `!!js process.env.TG_BOT_TOKEN` 引用环境变量）。

## License

MIT