Telegram 远程控制 jackControls/dsh-telegram-control

dsh-telegram-control

DeepSeek Harness（dsh）的 Telegram 远程控制插件。
它在 harness 进程内部运行一个 Telegram bot：你在手机上和 bot 聊天，普通文本会作为 follow-up 消息发给所选 agent，agent 的回复（一轮里所有 step 的输出）会在回合结束后回传到 Telegram。

dsh 里一切都是插件——这是一个 Cordis 函数插件，用长轮询对接 Telegram Bot API，除了 harness
自身之外没有任何运行时依赖。

功能

- 远程控制 agent：普通文本消息作为 follow-up 发给当前 chat 选定的会话，并会以普通用户气泡的形式出现在桌面 Web UI 的对话记录里。agent 的回复——包括 💭 标记的思考内容——在它自己的回合（turn）结束时立刻回传（按 turn 追踪，不依赖 agent 进入 idle）。
- 命令面：/status、/agents、/agent <session id>、/jobs、/kill <job id>、 /cancel、/watch / /unwatch、/chatid、/help。
- 手机审批：harness 的权限请求（沙箱升级等 approval/request）会以带 ✅ 允许一次 / ❌ 拒绝 内联按钮的消息发到 Telegram；点击即生效并把结果回写原消息。Telegram 不可达时回退到 Web 对话框，不会 fail-closed。
- 提问也上手机：ask_user_question 类提问（计划评审、选项确认）会带选项按钮转发到 Telegram，Telegram 的回答与 Web 对话框竞争、先到先得。审批与提问提示都会无条件出现在 Telegram（无论桌面当前聚焦在哪）。
- 实时推送：/watch 开启后，所有 live session 的 assistant 消息都会转发到你的 chat。
- 白名单鉴权：未授权 chat 只会收到一条提示（里面带上它自己的 chat id），其余全部忽略。
- 输出安全：所有动态文本在发往 Telegram 前做 HTML 转义；超长回复自动分片。

环境要求

- dsh（npx @deepseek-ai/dsh 或仓库源码运行均可）。
- Node.js ≥ 18（fetch 全局可用；dsh 本身要求 ≥ 22）。
- 从 @BotFather 申请的 bot token。

安装

1. 找 @BotFather 发 /newbot 创建 bot，复制 token。
2. 把插件装进某个 profile。可以从本仓库装：

dsh plugin --profile web add github:jackControls/dsh-telegram-control

或从本地目录装：

dsh plugin --profile web add /path/to/dsh-telegram-control

（把 web 换成你实际使用的 profile。该包声明了 dsh.bundle，所以 dsh plugin add 会自动挂成 profile 的一个 layer，不需要手改 cordis.patch.yml。lib/ 已提交，git 安装无需构建步骤。）

3. 在运行 dsh 的同一个环境里配置：

export DSH_TELEGRAM_TOKEN='123456:ABC-DEF...'
export DSH_TELEGRAM_ALLOWED_CHATS='123456789,987654321' # 逗号分隔的 chat id

4. 重启 dsh。用你的 Telegram 账号私聊 bot：先发 /chatid 拿到自己的 chat id（如果还没加进白名单），再发 /help。

手动挂载（不用 dsh plugin add）

也可以直接在 profile 的 cordis.patch.yml（$DSH_HOME/profiles/<profile>/cordis.patch.yml）里加一行：

- insert:
- id: telegram-control
name: 'dsh-telegram-control'
config:
可选：在这里写死配置，而不是用环境变量 token: '123456:ABC-DEF...'
allowedChatIds: [123456789]

配置项

| 配置键 | 环境变量兜底 | 默认值 | 说明 |
| token | DSH_TELEGRAM_TOKEN | —（必填） | Telegram bot token。 |
| allowedChatIds | DSH_TELEGRAM_ALLOWED_CHATS | []（全部拒绝） | 授权 chat id。注意：schemastery 会把缺失的数组字段校验成 []，所以空/缺失白名单一律回退到环境变量。 |
| apiBase | — | https://api.telegram.org | Bot API 地址（代理或测试时覆盖）。 |
| defaultAgentId | — | 无 | 当 chat 没有 /agent 选择时，普通消息默认发往的 session id。 |
| pollTimeoutSec | — | 50 | getUpdates 长轮询超时（Telegram 上限 50）。 |
| replyTimeoutMs | — | 600000（10 分钟） | 等待 agent 回复的最长时间，超时后把已产生的输出带提示先发出去。 |
| showToolCalls | — | false | 回复等待期间是否逐条推送 🔧 <name> 工具调用提示。 |
| reasoningMaxChars | — | 300 | 思考以一行摘要回传（同 Web UI 折叠 Think 行的第一行），单行超过此字符数再截断（0 关闭）。 |
| approvalTimeoutMs | — | 600000 | 审批请求等待 Telegram 按钮答复的超时，超时按取消处理。 |
| maxMessageChars | — | 4000 | 单条消息长度上限，超出自动分片。 |

命令

| 命令 | 作用 |
| /help、/start | 命令列表。 |
| /status | 运行时长、会话数（live/总数）、后台 job 数。 |
| /agents | 列出全部会话——live agent 和 暂停的持久化会话（与 Web UI 侧边栏一致）：带编号，名字取 session 标题，每个带方括号工作目录（[~/path]）、状态（idle/running/paused）、模型，当前 chat 已选中的带 👈 标记。 |
| /agent <编号> | 按 /agents 列表里的编号选中会话。 |
| /agent <名字> | 按 agent 标题或 session id 的子串（不区分大小写）选中；多个匹配时列出候选。 |
| /agent <session id> | 按完整 session id 精确选中。/agent 不带参数显示当前选择。 |
| /jobs | 列出后台 job。 |
| /kill <job id> | 请求停止某个后台 job。 |
| /cancel | 取消所选 agent 当前回合。 |
| /watch / /unwatch | 开关 live agent 输出的转发。 |
| /chatid | 显示当前 chat 的 id（用于配置白名单）。 |

普通文本会作为 follow-up 发给所选会话。选择顺序：chat 里 /agent 的选择 → defaultAgentId → 若恰好只有一个会话则用它。暂停的（已持久化但未 live 的）会话会在第一条消息时自动恢复（和 Web UI 的恢复方式一致：重新挂载会话记录的 agent preset，历史在相同的组合下回放）。每个 chat 的选择会持久化到 $DSH_HOME/telegram-control-state.json，harness 重启后依然生效。会话名字来自 harness 的 session 标题（session/title 事件——自动总结或你手动改的名字，和 Web UI 显示一致）；方括号里是 session 的工作目录（cwd）。

工作原理

- apply(ctx, config) 在 harness 进程内跑一个基于 fetch 的 getUpdates 长轮询循环。
遇到 409（有别的 poller）会干净地停掉当前 poller；网络错误按指数退避重试（上限 30 s）。
- 普通消息通过 createUserMessage({ source: { kind: 'user' } }) 构造（与 Web UI 自己发消息使用完全相同的来源，所以会显示在桌面对话记录里），再调用 agent.followup(...) 入队。
- 插件订阅持久化事件流 session/event 和 live 事件 agent/inbox/claimed / agent/status / agent/error / agent/disposed：用消息 id 匹配 agent/inbox/claimed 拿到自己的回合号，该回合 turn/end 时把累积的回复（可见文本 + 💭 思考）发出——即使 agent 一直忙、从不报 idle 也能及时送达；idle 兜底和超时提示覆盖其余情况。工具调用与错误提示即时转发； agent 运行期间发送打字指示。
- 所有注册都是 Cordis effect，插件卸载（HMR、profile 重载）时 bot 会被干净地拆掉。

安全

- 每条入站消息在采取任何动作前都会先做授权校验：处理前把 chat id 与 allowedChatIds （或 DSH_TELEGRAM_ALLOWED_CHATS）比对——未列出的 chat 不会执行任何命令、不会向 agent 投递任何消息、也不会被接受任何审批答复。仅存储/记录 userId 不构成授权。
- 空白名单 = 拒绝所有人（fail closed）：没有配置任何 chat id 时，所有消息都被拒绝，未授权 chat 唯一能收到的回复是告诉它自己 chat id 的引导提示。
- 这个 bot 本质上是你的 harness 的远程遥控器：只有白名单内的 chat 能下命令或应答审批。
白名单务必收紧。
- token 是凭据：优先用环境变量，别写进提交到仓库的 patch 文件。
- 插件不会放大 harness 的任何能力——它只能做你的 harness 本身能做的事，harness 的 sandbox / 审批策略对 agent 执行的工作依然生效。

兼容性、权限与验证

- Node.js：>=22（在 engines 中声明）。
- DeepSeek Harness：>=0.1.0-rc.6（在 peerDependencies 中声明）。已对 dsh 0.1.0-rc.6（npm CLI）与 0.1.5-rc.2（DSH Desktop 内置版本）做端到端验证——插件同时兼容两代持久化 API
（inspect() 或 open(id,'read')）、两种会话历史访问器（events 或 snapshotEvents()）以及
两种 list() 返回结构。
- 运行时依赖：仅一个 @deepseek-ai/schemastery（配置校验）。其余都是 peerDependency，从宿主安装中解析；没有 postinstall 脚本，也没有内置二进制。
- 权限 / 外部服务：插件访问网络（Telegram Bot API over HTTPS）、使用凭据（来自 config.token 或 $DSH_TELEGRAM_TOKEN 的 bot token），并且只写一个状态文件（$DSH_HOME/telegram-control-state.json，记录每个 chat 选中的会话）。不读写其它本地文件。
- 失败边界：Telegram API 不可达时退避重试；遇到 409（有别的 poller）停掉当前 poller； Telegram 收不到审批时 Web 对话框仍可处理。插件卸载会中止轮询并清理所有待处理提示。
- 验证证据：npm test（24 项单元测试）+ node tests/smoke.mjs（两阶段端到端：在一次性 profile 中安装插件、启动真实 dsh web，断言 live agent 回传、暂停会话恢复、审批闭环、提问闭环，共 32 项检查）。用 DSH_CLI 可指定要验证的 harness 构建。

开发

npm install # 开发依赖（类型检查 + 构建）
npx tsc # 类型检查并产出 lib/
node --test 'tests/*.test.mjs' # 纯函数单元测试
node tests/smoke.mjs # 端到端冒烟：在隔离的 $DSH_HOME 里启动真实的 dsh web，
用假的 Telegram 服务和 mock LLM 验证完整的消息→agent→回传链路（需要时可设 DSH_CLI 指向你的 dsh bin）

已知限制

- 只支持长轮询，不支持 Telegram webhook（个人远程控制够用了）。
- 插件观察会话事件流；高频会话可能刷屏 watching 的 chat——用 /unwatch 关掉。
- 回复缓冲按 sessionId 组织，假设一个用户驱动一个 agent；两个 chat 驱动同一个 agent 时，每个回合会合并成一条回复发给每个 chat。

License

MIT