feat: remote-control live DSH Web sessions from Telegram

Attach via /sessions picker instead of creating parallel agents; mirror the same session trajectory to phone and Web (Codex-style remote). Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-14 17:11:13 +08:00
parent dd72f134fb
commit c2c0db7597
12 changed files with 518 additions and 666 deletions
@@ -2,9 +2,9 @@

 [English](#english) · [中文](#中文)

-**Keywords / 关键词：** Telegram · Bot · Mobile · Channel · Remove · Clear · Delete session · DeepSeek Harness · DSH · Cordis · dsh-plugin · Agent · Remote · Long polling · Allowlist · 手机 · 远程 · 机器人 · 渠道 · 会话 · 新对话 · 清除 · 删除 · 白名单 · 长轮询
+**Keywords / 关键词：** Telegram · Bot · Mobile · Remote · Channel · Sessions · Bind · Unbind · Remove · Clear · DeepSeek Harness · DSH · Cordis · dsh-plugin · Agent · Live session · 手机 · 远程 · 遥控器 · 会话列表 · 附着 · 解绑 · 白名单

-DeepSeek Harness（DSH）Telegram **Bot / Channel** Cordis 插件：用手机 Telegram 远程驱动本机 Agent。长轮询 Bot API，按聊天独立会话，助手回复 HTML 分片回传。`dsh plugin add` 安装，约 10 分钟连通。
+DeepSeek Harness **手机遥控器**：用 Telegram Bot **附着本机正在运行的 Web 会话**（与 Web **同轨迹、双向可见**）。对标 Codex phone remote——本机会话是真相源，手机不另开平行对话。

 ---

@@ -12,53 +12,36 @@ DeepSeek Harness（DSH）Telegram **Bot / Channel** Cordis 插件：用手机 Te

 ### 这是什么

-把 **Telegram Bot** 接到 **DeepSeek Harness**，让你可以在 **手机（mobile）** 上发消息，本机 DSH agent 执行并回复。适合远程 coding agent、远程运维对话、随身 Bot 入口。
+| | 旧「平行桥」 | **本插件（当前）** |
+|---|---|---|
+| 会话 | Telegram 专用新建 agent | 附着 `dsh web` 里 **live** agent |
+| Web | 不通 | 手机与 Web **同一条轨迹** |

-相关搜索词：`telegram bot`、`dsh telegram`、`deepseek harness mobile`、`telegram channel plugin`、`/new` `/clear` `/remove` 会话、白名单 bot。
-
-### 特性
-
- 标准 Cordis **dsh-plugin**（`inject: ['agents']`），`cordis.patch.yml` 挂入 profile
- Telegram **长轮询** `getUpdates`，无需公网 webhook
- 每 chat 一个 agent；`/new`、`/clear` **清除 / 删除**当前会话后重建
- **白名单**鉴权（fail-closed）；鉴权与命令默认中文
- Markdown 子集 → Telegram HTML，超长自动分片；HTML 失败降级纯文本
- 无 token 时软失败：打日志、不启轮询，不拖垮整个 profile
-
-### 前置条件
-
-| 项 | 要求 |
-|---|---|
-| Node.js | ≥ 22 |
-| DeepSeek Harness | 目标 profile（如 `dsh web`）可运行，API Key 等已按官方配置 |
-| Telegram Bot | [@BotFather](https://t.me/BotFather) 创建 bot，取得 token |
-| 用户 ID | [@userinfobot](https://t.me/userinfobot) 等获取 numeric user id |
+流程：电脑上先开对话 → 手机 `/sessions` 选择 → 发消息进入该会话 → Web 也能看到。

 ### 连接实操（约 10 分钟）

-按下面顺序做即可完成 **Telegram Bot ↔ DSH** 连通：
-
-1. 本机确认 `dsh web`（或你的 profile）能正常启动。
-2. BotFather 创建 bot，复制 **token**；userinfobot 记下自己的 **user id**。
-3. 安装插件（推荐 GitHub）：
+1. 本机 `dsh web` 能跑，并 **先打开至少一个对话**（保持运行）。
+2. [@BotFather](https://t.me/BotFather) 建 Bot，拿 token；[@userinfobot](https://t.me/userinfobot) 拿自己的 user id。
+3. 安装：

 ```powershell
 dsh plugin --profile web add github:hi-wenw/dsh-telegram-channel
 ```

-本地开发目录安装：
+或本地：

 ```powershell
 dsh plugin --profile web add D:\gitData\dsh-telegram-channel
 ```

-4. 设置 token（推荐环境变量，避免写进仓库）：
+4. Token（推荐环境变量）：

 ```powershell
 $env:DSH_TELEGRAM_TOKEN = '123456:ABC...'
 ```

-5. 在 profile 的 patch / 插件配置里设置白名单（把数字换成你的 id）：
+5. 白名单（换成你的 id）：

 ```yaml
 - insert:
@@ -67,69 +50,48 @@ $env:DSH_TELEGRAM_TOKEN = '123456:ABC...'
      config:
        token: ''
        allowedUserIds: [123456789]
-        provider: deepseek-official
-        model: deepseek-v4-flash
 ```

-也可参考 [`examples/telegram-agent/`](examples/telegram-agent/)。
+6. **重启 / 重载** profile。
+7. 手机 Telegram：
+   - `/start`
+   - `/sessions` → 点选本机会话
+   - 发一句话 → Web 与手机构应出现同一轮问答
+   - `/unbind` 仅断开手机绑定，不关本机会话

-6. **重新加载或重启** profile，使配置生效。
-7. 手机打开 Telegram，向该 **Bot** 发送：
-   - `/start` — 欢迎
-   - 任意一句话 — 应收到 agent 回复
-   - `/new` 或 `/clear` — **清除会话**后重新对话
-   - `/help` — 命令说明
-
-### 配置项
-
-| 键 | 默认 | 含义 |
-|---|---|---|
-| `token` | `''`（空则读 `DSH_TELEGRAM_TOKEN`） | BotFather bot token |
-| `allowedUserIds` | `[]` | 允许对话的 Telegram user id；**空且 `allowAllUsers: false` = 全拒** |
-| `allowAllUsers` | `false` | `true` 时忽略白名单（仅本地调试） |
-| `provider` | `deepseek-official` | agent 的 LLM provider |
-| `model` | `deepseek-v4-flash` | 模型 id |
-| `maxMessageLength` | `4096` | 单条消息长度上限 |
-| `pollingTimeoutSec` | `30` | 长轮询超时（秒） |
-| `cwd` | 进程 cwd | agent 工作目录 |
-
-### Bot 命令
+### 命令

 | 命令 | 行为 |
 |---|---|
-| `/start` | 欢迎与用法；不调模型 |
-| `/help` | 命令与白名单 / 会话说明 |
-| `/new` 或 `/clear` | **清除 / 删除**当前 chat 的 agent，下次消息重建（等同 reset / remove session） |
-| 未识别 `/...` | 提示可用命令 |
-| 普通文本 | `create` / `followup` → 回传助手文本 |
+| `/sessions` `/list` | 列出 live 会话，内联键盘选择附着 |
+| `/status` | 当前绑定 |
+| `/unbind` `/disconnect` | 解绑（不 dispose 本机 agent） |
+| `/help` `/start` | 帮助 / 欢迎 |
+| 普通文字 | 进入已绑定会话的 `followup` |
+
+### 配置
+
+| 键 | 默认 | 含义 |
+|---|---|---|
+| `token` | 空 → `DSH_TELEGRAM_TOKEN` | Bot token |
+| `allowedUserIds` | `[]` | 白名单；空 = 全拒 |
+| `allowAllUsers` | `false` | 调试用，生产勿开 |
+| `maxMessageLength` | `4096` | 分片长度 |
+| `pollingTimeoutSec` | `30` | 长轮询超时 |

 ### 故障排查

-| 现象 | 可能原因 | 处理 |
-|---|---|---|
-| 日志 `missing bot token`；Bot 无响应 | 未设 `token` / `DSH_TELEGRAM_TOKEN` | 设置后重载 profile |
-| 回复「无权限。」 | user id 不在白名单，或名单为空 | 核对 id，写入 `allowedUserIds` |
-| Telegram 401 | token 错误或已撤销 | BotFather 换新 token |
-| 有 typing 无文字 | profile 内 LLM / API Key | 查 DSH 日志；同 profile 先用 CLI 验证 agent |
-| 重启后对话「失忆」 | 会话仅内存（当前设计） | 直接发消息或 `/new` 重建 |
-| 贡献者 `npm install` peer 冲突 | 上游 DSH RC `dsh-invariants` 未对齐 | `npm install --legacy-peer-deps` |
-
-### 路线图
-
-1. 运维键盘：新对话 / 状态 / 停止 / 更多
-2. 同消息编辑流式、阶段摘要
-3. chat↔session 跨重启持久化
-4. cwd / 项目切换
-5. Telegram 侧切换 provider / model
-6. 媒体（图片等，依赖 profile 能力）
-7. 可选 webhook
+| 现象 | 处理 |
+|---|---|
+| `/sessions` 提示没有会话 | 先在 Web 打开对话并保持 profile 运行 |
+| 「尚未绑定」 | 先 `/sessions` 点选 |
+| 「会话已不在本机运行」 | Web 已关该会话；重新开再绑定 |
+| 「无权限」 | 检查 `allowedUserIds` |
+| missing bot token | 设 `DSH_TELEGRAM_TOKEN` 后重载 |

 ### 安全

- Fail-closed 白名单；空名单默认全拒
- Token 优先环境变量；日志脱敏
- `allowAllUsers: true` 勿用于生产
- 本插件不启 LLM；模型 / 工具 / 沙箱由 DSH profile 决定
+Fail-closed 白名单；token 走环境变量；日志脱敏；解绑不关闭本机 agent。

 ### 贡献者

@@ -141,15 +103,6 @@ npm test
 npm run build
 ```

-### 验证状态
-
-| 项 | 值 |
-|---|---|
-| 包版本 | `0.1.0` |
-| 日期 | 2026-08-14 |
-| 自动化 | `npm test` 25/25 · `npm run build` |
-| Peer | `@deepseek-ai/cordis` ^4.0.1 · `dsh-agent` ^0.1.0-rc.6 · `dsh-llm` ^0.0.1-rc.1 · `dsh-session` ^0.0.1-rc.1 |
-
 ### 许可证

 [MIT](LICENSE)
@@ -160,142 +113,32 @@ npm run build

 ### What this is

-A **DeepSeek Harness (DSH) Cordis channel plugin** that turns a **Telegram Bot** into a **mobile / remote** front-end for your local agent. Long-polling Bot API, one agent session per chat, HTML-split replies. Install with `dsh plugin add`; connect in about 10 minutes.
+A **DeepSeek Harness Cordis plugin** that turns Telegram into a **mobile remote** for **live** agents in the same `dsh web` process. The desktop/Web session is the source of truth (Codex-style remote). Telegram **attaches**; it does **not** spawn a parallel hidden agent.

-**Search keywords:** telegram bot, telegram channel, mobile agent, remote bot, deepseek harness, dsh-plugin, cordis plugin, remove session, clear chat, `/new`, `/clear`, allowlist, long polling.
+### Connect walkthrough

-### Features
-
- Standard **dsh-plugin** (`inject: ['agents']`) via `cordis.patch.yml`
- Telegram **long polling** (`getUpdates`) — no public webhook required
- Per-chat agent; `/new` and `/clear` **remove / reset / delete** the session
- Fail-closed **allowlist**; Chinese copy for auth/commands by default
- Markdown subset → Telegram HTML with chunking; plain-text fallback
- Missing token soft-fail: log and skip polling (does not crash the profile)
-
-### Prerequisites
-
-| Item | Requirement |
-|---|---|
-| Node.js | ≥ 22 |
-| DeepSeek Harness | Target profile (e.g. `dsh web`) runs with API keys configured |
-| Telegram Bot | Create via [@BotFather](https://t.me/BotFather), copy token |
-| User id | Numeric id from [@userinfobot](https://t.me/userinfobot) (etc.) |
-
-### Connect walkthrough (~10 minutes)
-
-1. Confirm `dsh web` (or your profile) starts on the machine.
-2. Create a **Telegram Bot**, copy **token**; note your **user id**.
-3. Install the plugin:
+1. Run `dsh web` and **open at least one conversation**.
+2. Create a Bot (BotFather) + note your user id.
+3. Install:

 ```powershell
 dsh plugin --profile web add github:hi-wenw/dsh-telegram-channel
 ```

-Local path:
+4. `$env:DSH_TELEGRAM_TOKEN = '...'`
+5. Set `allowedUserIds` in the plugin patch.
+6. Reload the profile.
+7. On your phone: `/sessions` → tap a live session → send text → same turn appears on Web and Telegram. `/unbind` detaches only.

-```powershell
-dsh plugin --profile web add D:\gitData\dsh-telegram-channel
-```
+### Commands

-4. Set the token (prefer env):
-
-```powershell
-$env:DSH_TELEGRAM_TOKEN = '123456:ABC...'
-```
-
-5. Allowlist your user id in the profile patch:
-
-```yaml
- insert:
-    - id: dsh-telegram-channel
-      name: dsh-telegram-channel
-      config:
-        token: ''
-        allowedUserIds: [123456789]
-        provider: deepseek-official
-        model: deepseek-v4-flash
-```
-
-See also [`examples/telegram-agent/`](examples/telegram-agent/).
-
-6. **Reload or restart** the profile.
-7. On your **phone**, open Telegram and message the **Bot**:
-   - `/start` — welcome
-   - any text — agent reply
-   - `/new` or `/clear` — **remove / clear** session, then chat again
-   - `/help` — commands
-
-### Configuration
-
-| Key | Default | Meaning |
-|---|---|---|
-| `token` | `''` (falls back to `DSH_TELEGRAM_TOKEN`) | BotFather token |
-| `allowedUserIds` | `[]` | Allowed Telegram user ids; **empty + `allowAllUsers: false` rejects all** |
-| `allowAllUsers` | `false` | Ignore allowlist (local debug only) |
-| `provider` | `deepseek-official` | LLM provider for created agents |
-| `model` | `deepseek-v4-flash` | Model id |
-| `maxMessageLength` | `4096` | Max Telegram message length |
-| `pollingTimeoutSec` | `30` | Long-poll timeout (seconds) |
-| `cwd` | process cwd | Agent working directory |
-
-### Bot commands
-
-| Command | Behavior |
+| Command | Action |
 |---|---|
-| `/start` | Welcome; no model call |
-| `/help` | Commands + allowlist / session notes |
-| `/new` or `/clear` | **Remove / clear / reset** this chat’s agent; next message creates a new session |
-| Unknown `/...` | Hint available commands |
-| Plain text | `create` / `followup` → assistant text |
-
-### Troubleshooting
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| Log `missing bot token`; silent Bot | No `token` / `DSH_TELEGRAM_TOKEN` | Set env or config, reload profile |
-| Reply「无权限。」 / Access denied | User not on allowlist or empty list | Fix `allowedUserIds` |
-| Telegram 401 | Bad/revoked token | New token from BotFather |
-| Typing but no text | LLM / API Key in profile | Check DSH logs; verify agent in same profile |
-| Amnesia after restart | In-memory sessions by design | Send a message or `/new` |
-| Contributor `npm install` peer conflict | Upstream DSH RC pins | `npm install --legacy-peer-deps` |
-
-### Roadmap
-
-1. Ops keyboard (new / status / stop / more)
-2. In-place streaming edits
-3. Persist chat↔session across restarts
-4. cwd / project switch
-5. Switch provider/model from Telegram
-6. Media (images) when profile supports it
-7. Optional webhook
-
-### Security
-
- Fail-closed allowlist
- Prefer env for token; logs redact secrets
- Never enable `allowAllUsers` in production
- Plugin does not start the LLM; profile owns models/tools/sandbox
-
-### Contributors
-
-```powershell
-git clone https://github.com/hi-wenw/dsh-telegram-channel.git
-cd dsh-telegram-channel
-npm install --legacy-peer-deps
-npm test
-npm run build
-```
-
-### Verification
-
-| Item | Value |
-|---|---|
-| Package | `0.1.0` |
-| Date | 2026-08-14 |
-| Automated | `npm test` 25/25 · `npm run build` |
-| Peers | `@deepseek-ai/cordis` ^4.0.1 · `dsh-agent` ^0.1.0-rc.6 · `dsh-llm` ^0.0.1-rc.1 · `dsh-session` ^0.0.1-rc.1 |
+| `/sessions` `/list` | List live agents; inline keyboard to bind |
+| `/status` | Show binding |
+| `/unbind` `/disconnect` | Unbind (does not dispose host agent) |
+| Plain text | `followup` into the bound live agent |

 ### License

-[MIT](LICENSE)
+MIT