# Telegram 机器人接入指南

> 通过官方 Telegram Bot API，将本地 DeepSeek Harness 接入 Telegram，支持单聊与群聊、原生快捷指令菜单、交互卡片按键、增量打字机流式输出与权限审批。

---

## 🌟 核心优势

- **100% 免公网 IP / 免 Webhook**：基于 Telegram 官方 Long Polling（长轮询）机制，本地电脑或内网服务器即可直连 Telegram Bot API。
- **零依赖原生代理支持**：内置极简 HTTP/HTTPS CONNECT 隧道代理客户端，国内网络环境下仅需填入代理地址（如 `http://127.0.0.1:7890`）即可极速通信。
- **增量打字机流式输出**：接入轮次实时生命周期，通过 `editMessageText` 实现平滑打字机流式输出，单条气泡原地更新，告别刷屏。
- **原生快捷指令菜单 (`Menu` 按键)**：自动通过 `setMyCommands` 与 `setChatMenuButton` 注册全范围指令，输入 `/` 或点击左下角菜单即可一键直达。
- **原生交互卡片与审批按键**：审批请求下发 Inline Keyboard 按键 `[✓ 批准执行]` / `[✕ 拒绝执行]`，一键点击即时响应。
- **多工作区与会话持久化**：支持 `/sessions` 查看会话列表、`/use <序号>` 切换、`/workspaces` 调度工作区，重启 DSH 后白名单与会话不丢失。

---

## 🛠️ 第一步：在 Telegram 中创建机器人并获取 Token

1. 打开 Telegram，搜索官方机器人管理号 [@BotFather](https://t.me/BotFather)；
2. 点击底部 `Start` 或发送 `/newbot` 指令；
3. 根据提示依次输入：
   - **机器人昵称**（如 `My DSH Agent`）；
   - **机器人用户名**（必须以 `bot` 结尾，如 `my_dsh_agent_bot`）；
4. 创建成功后，@BotFather 会返回一行 **HTTP API Token**（格式如 `123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ`）。

> 💡 **（可选）在 BotFather 中固化快捷指令**：
> 向 @BotFather 发送 `/setcommands`，选择你的机器人，直接复制并粘贴下方内容发送：
> ```text
> new - 新建会话并开始执行 (/new <提示词>)
> sessions - 列出所有会话列表与切换
> use - 切换活动会话 (/use <N>)
> workspaces - 列出本地所有可用工作区
> status - 查看 Agent 状态与会话摘要
> stop - 停止当前正在运行的任务
> end - 结束当前活动会话
> help - 显示快捷按键与完整帮助
> ```

---

## ⚙️ 第二步：在 DSH Bridge 中配置与连接

1. 打开 DSH Web 设置页「**远程访问**」→「**IM 机器人**」；
2. 在平台选择栏中点击「**Telegram**」卡片；
3. 填入刚才获取的 **Bot Token**；
4. **网络代理（可选）**：
   - 若在中国大陆地区服务器或个人电脑上运行，填入本地代理地址，如 `http://127.0.0.1:7890`（支持 Clash / v2ray / Squid 等 HTTP/HTTPS 代理）；
   - 亦可直接在系统环境变量中设置 `HTTPS_PROXY=http://127.0.0.1:7890`；
5. 点击「**保存并连接**」。

![Telegram Bot 配置](screenshots/telegram-bot-config.jpg)

---

## 📱 第三步：扫码与自动白名单授权

1. 连接成功后，面板将展示当前机器人的二维码与 `https://t.me/<username>` 直达链接；
2. 用手机 Telegram 扫描二维码或点击链接打开与机器人的对话；
3. 发送第一条消息（如 `/help` 或 `你好`），系统将**自动将你的 Telegram 账号加入白名单**并持久化；
4. 之后即可在 Telegram 里随时随地向 Agent 下达任务指令。

---

## 💬 常用指令与卡片交互

| 指令 | 说明 | 交互支持 |
| :--- | :--- | :--- |
| *(普通文本)* | 发送给当前活动 Agent 执行任务 | 实时打字机流式输出 |
| `/new <提示词>` | 在当前工作区新建会话并立即执行 | 启动全新轮次 |
| `/new <提示词> @N` | 在指定工作区序号新建会话 | 多工作区调度 |
| `/rename <新标题>` | 重命名当前活动会话标题 | 修改会话名称 |
| `/sessions`（或 `/list`） | 查看所有会话列表 | 附带一键切换按键 |
| `/use N`（或 `/resume N`） | 切换活动会话至序号 N | 快速切换上下文 |
| `/workspaces` | 列出本地所有可用项目工作区 | 查看工作区路径 |
| `/addworkspace <路径>` | 注册添加新的电脑工作区目录 | 自动绑定并生成快捷序号 |
| `/status` | 查看当前 Agent 运行状态看板 | 附带刷新/停止/结束按键 |
| `/stop` | 强制停止当前正在运行的 Agent 任务 | 即刻中断执行 |
| `/end` | 结束当前活动会话 | 挂载快捷开始按键 |
| `/yes` `/no`（或 `1`/`2`） | 响应权限审批请求 | 支持直接点击卡片按钮 |
| `/help` | 查看快捷按键与完整使用帮助 | 挂载全套功能导航按键 |

---

## 🛡️ 多模态与安全说明

1. **图片与文件双向传输**：
   - 直接向 Telegram 机器人发送图片或文档，系统自动保存到本地并注入提示词供 Agent 解析；
   - Agent 任务执行中生成的图片、文档等产物，在轮次结束时会自动推送回 Telegram 聊天。
2. **安全白名单拦截**：
   - 仅白名单内的用户消息会被放行给 Agent；非白名单用户发送的消息会被直接忽略，绝不消耗 Token 或喂给模型。
3. **敏感操作审批**：
   - 当 Agent 尝试执行系统命令或敏感文件读写时，Telegram 会自动下发 `[✓ 批准执行]` / `[✕ 拒绝执行]` 交互按键，10 分钟未处理自动超时拒绝。