sazzadurrahmaan/dsh-telegram

dsh-telegram

一个用于 DeepSeek Harness 的 Telegram 频道。给你的机器人发消息，智能体就会在聊天中回复——同一个智能体、同一套工具、与 Web UI 相同的会话日志。

它专为 OpenClaw 和 Hermes 已经服务、而 Harness 尚未覆盖的场景而构建：从手机访问你的智能体，无需在服务器上保持一个 shell 打开，而任何知道机器人用户名的人都能与之对话。

这一版的独特之处

一个连接到编码智能体的 Telegram 机器人，本质上是通过聊天应用进行的远程 shell 访问。大多数桥接方案把这当作一个细节。而这一版把它当作设计的核心：

- 默认拒绝。 空的允许列表不接纳任何人。访问权限通过数字 Telegram 用户 id 控制，在消息到达智能体之前进行检查。没有“允许所有人”的开关。
- 破坏性工具的聊天内审批。 bash、pwsh、terminal、write、edit 和 str_replace_editor 会在 tools/pre-execute 关卡处停下，并在聊天中询问，附带 Allow / Deny 按钮。只有显示该提示的聊天才能回答它，且回调令牌是随机 UUID。未回答的提示会在超时后拒绝。
- 每个聊天一个智能体，随插件一起销毁。用户之间不共享会话。
- 通信层零依赖。 Bot API 通过 fetch 和长轮询调用——没有 webhook、没有框架、没有需要审计的机器人库。整个客户端就是一个小文件。

安装

dsh plugin --profile web add github:sazzadurrahmaan/dsh-telegram

然后设置令牌和你的用户 id：

export DSH_TELEGRAM_TOKEN='123456:ABC...'          # 来自 @BotFather
export DSH_TELEGRAM_ALLOWED_USER_IDS='123456789'   # 你的；见下方 /whoami

或者在 ~/.dsh/cordis.patch.yml 中配置：

plugins:
dsh-telegram:
token: ${DSH_TELEGRAM_TOKEN}
allowedUserIds: [123456789]
cwd: /home/dsh/workspace

不知道你的数字 id？给机器人发 /whoami——这是唯一一条会回应任何人的命令，因为它只告诉你你自己的 id，而你需要它才能被加入允许列表。来自未列入允许列表的用户的所有其他消息都会被丢弃。

命令

| 命令 | 效果 |
|---|---|
| /start | 显示命令列表 |
| /new | 销毁此聊天的智能体并开始一个全新会话 |
| /stop | 取消正在运行的回合 |
| /status | 会话 id 和智能体状态 |
| /whoami | 你的 Telegram 用户 id——唯一一条无需加入允许列表即可回应的命令 |

其他任何内容都会作为后续回合发送给智能体。

配置

| 键 | 默认值 | 含义 |
|---|---|---|
| token | $DSH_TELEGRAM_TOKEN | 来自 @BotFather 的机器人令牌 |
| allowedUserIds | $DSH_TELEGRAM_ALLOWED_USER_IDS，否则为 [] | 允许与智能体对话的数字 id |
| cwd | harness 默认值 | Telegram 会话的工作目录 |
| showToolActivity | true | 工具运行时向聊天发送一行消息 |
| allowDestructiveTools | false | 完全跳过审批提示 |
| gatedTools | shell 和编辑工具 | 需要审批的工具 |
| approvalTimeoutSec | 120 | 未获答复的审批在此时间后被拒绝 |
| pollTimeoutSec | 30 | getUpdates 的长轮询超时时间 |

工作原理

该插件是一个普通的 Cordis 插件，基于三个扩展点：

- ctx.agents.create() 为每个聊天创建一个 agent；AgentHandle.dispose() 将其销毁。
- session/event 将 assistant/message 流式传回聊天，在 Telegram 的 4096 字符限制处拆分，若换行符位置合适则在换行处拆分。该拆分是无损的——重新拼接各部分可还原原始内容——因此代码块内的缩进得以保留。
- tools/pre-execute 对用户未批准的门控工具返回 { kind: 'deny' }。

每次注册都通过 ctx.effect() 进行，因此重新加载会解除轮询循环并销毁活跃的 agent。

安全注意事项

在将此插件指向你关心的机器之前，请先阅读以下内容。

1. 允许列表是陌生人与你的 shell 之间的唯一屏障。 任何人都可以通过用户名找到机器人并向其发送消息。请保持 allowedUserIds 准确，切勿从不受信任的输入中设置它。
2. allowDestructiveTools: true 会移除审批提示。 开启后，被允许的用户可以从手机上运行 harness 能运行的任何命令，且无需确认。
3. 不支持群聊。 将机器人添加到群组后，每个成员的消息都会到达；只有允许列表中的 id 会得到回复，但暴露面比预期更大。请使用直接聊天。
4. 令牌授予对机器人的控制权。 请将其保存在环境变量中，而不是提交到配置文件里。
5. 开发者预览版。 Harness 为 0.1.x，其 README 警告可能存在破坏兼容性的更改。请固定你的 Harness 版本，否则就要做好因接口变更而重新修复的准备。

项目

- CHANGELOG.md — 变更内容及时间
- CONTRIBUTING.md — 环境搭建，以及变更必须保持的不变量
- SECURITY.md — 威胁模型以及如何私下报告漏洞
- examples/cordis.patch.yml — 一份带注释的配置，可供复制

开发

npm install --legacy-peer-deps   # 已发布的 rc 包存在内部 peer 冲突
npm run build
npm test

需要 --legacy-peer-deps，因为 @deepseek-ai/dsh-agent@0.1.0-rc.6 要求 dsh-invariants ^0.1.0-rc.6，而 dsh-llm@0.0.1-rc.1 依赖链要求 ^0.0.1-rc.1。这些包在此处是 peer 依赖——运行时它们由宿主 harness 解析，因此这仅影响本地类型检查。

许可证

MIT