Gum97/dsh-telegram

dsh-telegram

npm

一个用于 DeepSeek Harness 的 Telegram 频道。

编写此插件是为了修复通用频道桥接的四个具体故障：

| 问题 | 原因 | 修复 |
|---|---|---|
| 粗体、链接和表格被渲染为字面 markdown | 从未设置 parse_mode | Markdown 被编译为 Telegram 的富文本块——真正的表格和列表——背后还有一条 HTML 路径 |
| 智能体无法发送图片 | 回复路径始终只传递 { text } | 回复中的文件引用会变成真正的 sendPhoto / sendDocument 上传 |
| 问题没有答案按钮 | 未注册 UserQuestionProvider | 问题会渲染为内联键盘，支持多选和自由文本答案 |
| 无法从聊天中更改模型 | 只有 /new 存在 | /model、/preset、/mode、/status、/stop、/compact |

状态：早期。 已在 DSH 0.1.0-rc.7 上针对一个实时机器人进行了端到端验证，
但尚未经过其他人测试，也未针对其他 DSH 版本测试。请预期 0.1.0 版本的
粗糙边缘。

安装

dsh plugin --profile web add dsh-telegram

dsh plugin 会转发到配置文件目录中的 pnpm，因此上述已发布的包、
git URL（github:Gum97/dsh-telegram）或本地路径
（file:../dsh-telegram）都可以使用。

然后将该 bundle 添加到配置文件的 package.json 中：

{
"dsh": {
"profile": {
"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-telegram"]
}
}
}

存储机器人令牌——它永远不会从插件配置中读取：

$DSH_HOME/.credentials.yaml
TELEGRAM_BOT_TOKEN: "123456:ABC-DEF..."

或者在配置文件运行后，将其粘贴到 Settings → Plugins → Telegram 中。

设置页面

该插件注册了 telegram 设置命名空间，并附带一个以它为键的浏览器卡片，
因此机器人令牌、允许用户列表、工作目录和显示开关都可以在
Settings → Plugins 中编辑，而无需触碰文件。

有两个行为值得了解：

- 令牌不会存储在设置文档中。 机密会从每个网络响应中剥离，
因此卡片只能报告是否配置了令牌，而永远无法显示令牌。它通过凭据域写入，
空白字段会保留已存储的令牌不变。
- 并非每项更改都会实时生效。 允许用户列表和显示开关会在下一条消息时生效。
令牌引用、工作目录和开/关开关在频道启动时读取，因此它们会在 DSH 重启后生效——
卡片会在你保存前说明这一点，日志会在保存后重复说明。

在配置文件的 cordis.patch.yml 中固定的值会成为该命名空间的 base
层，因此部署时的选择会一直保留，直到用户有意覆盖它，
并且字段上的 Reset 会将其恢复为该值。

从源码构建
Host 那一半是纯 ESM JavaScript，按原样运行。浏览器那一半是唯一的构建步骤，因为 DSH 的页面加载器接收的是注册的 CJS 工厂，而不是 ES 模块：

npm install
npm run build:client   # emits lib/client.js
npm test

prepublishOnly 会同时运行这两者，因此发布的 tarball 始终携带与其源码匹配的 bundle。React 和 DSH 客户端包保持为外部 require 调用，由页面解析——打包 React 会让卡片拥有第二个 React 实例，并在运行时破坏其 hooks。

上游的 clientBundle 构建预设未发布，因此这里的 tsdown.client.ts 复现了它的契约。这是仓库外插件故事中的一个已知缺口，记录在 dsh-client-ui-settings-plugins 自己的 README 中。

命令

| 命令 | 效果 |
|---|---|
| /start | 认领一个未被认领的 bot（见下文） |
| /new | 为此聊天启动一个新会话 |
| /model | 从按钮中选择提供商/模型，或使用 /model provider/model |
| /preset | 选择下一个会话使用的 agent 预设 |
| /mode | 设置沙箱模式（read-only、workspace-write、danger-full-access） |
| /status | 会话 id、模型、预设、沙箱模式、工作目录 |
| /stop | 取消正在运行的回合 |
| /compact | 压缩对话历史 |
| /help | 列出命令 |

谁可以使用该 bot

由 allowedUsers 决定，空列表意味着该 bot 处于未被认领状态，而不是对所有人开放。

第一个向未被认领的 bot 发送 /start 的人会被记录为其所有者，门随后在其身后关闭——就像首次运行的设备设置那样。之后每一个陌生人都会被拒绝，并显示其自己的用户 id 以供转达，所有者则从 Settings → Plugins → Telegram 扩大访问权限。

这一点很重要，因为 bot 的用户名是可被发现的。一个接受任何人的 bot，会把一个在所有者机器上运行 shell 命令的 agent 交给任何发现它的人。

语言

该频道使用越南语或英语，由 language 设置选择，并可从设置卡片切换。它同时管理两个方面——bot 的消息和卡片自身的标签——因为一个用越南语回答、却来自英文标签卡片的 bot，是一个对用户说着两种语言的产品。

这是频道设置而非宿主 locale，是有意为之：DSH 只提供 zh 和 en，其 locale schema 正是这两者的联合，因此 vi 偏好会被直接拒绝。跟随宿主就意味着把越南语藏在中文选项后面。

配置

| 键 | 默认值 | 含义 |
|---|---|---|
| enabled | true | 在不移除频道的情况下将其关闭 |
| tokenRef | TELEGRAM_BOT_TOKEN | 保存 bot token 的凭据名称 |
| allowedUsers | [] | 允许与 bot 对话的 Telegram 用户 id；为空表示未被认领 |
| language | vi | vi 或 en，用于 bot 消息和设置卡片 |
| workspaceRoot | process.cwd() | 频道会话的工作目录 |
| routeQuestions | true | 在 Telegram 中回答 Telegram 会话的问题，而不是在浏览器中 |
| streaming | true | 在答案流式传输时就地编辑同一条消息 |
| showToolActivity | true | 在预览中显示正在运行的工具 |
| rich | true | 使用真正的表格和列表（sendRichMessage） |
| preset | — | 新频道会话的 agent 预设 |
| bindingFile | $DSH_HOME/dsh-telegram/bindings.json | 聊天→会话映射的存放位置 |

除 preset 和 bindingFile 外，以上所有内容也可在设置页面中由用户编辑；这两项仍属于部署层面的关注点，因为将频道指向一个不可写的绑定文件会使其损坏且无法恢复。

设计说明

转义只发生一次。 原始文本会预先进行 HTML 转义；随后内联模式针对转义后的文本运行。由于转义会移除所有 ，任何用户内容都无法伪造标签。代码片段和围栏会在转义前被提取出来，并在转义后恢复，因此其内容永远不会经历强调处理。

分块拆分的是源文本，而不是 HTML。 按 4096 字节切分已渲染的 HTML 会把消息从标签中间截断，Telegram 会拒绝整个发送。拆分 markdown 并分别渲染每一块可保证标签平衡，跨越边界的围栏会被关闭并重新打开。

媒体永远不会逃出工作区。 引用的路径会相对于会话的工作区根目录进行解析，如果落在外部则会被拒绝；该引用会保留为文本，而不是上传任意文件。

HTML 失败会降级，但绝不会丢弃。 如果 Telegram 拒绝已渲染的负载，客户端会以纯文本重试一次。格式错误只会损失格式，而不会损失消息。

只有频道拥有的轮次才会被投递。 会话也可以从 Web UI 驱动。回复路由器会跟踪它开启了哪些轮次，这样这些回复就不会被重复发送到聊天中。

Web 配置文件中的问题

宿主在整个进程范围内只允许一个用户问题提供程序，而在 Web 配置文件中，Web 桥接（dsh-host-apiproxy）会先注册。如果不加处理，这意味着在 Telegram 轮次中提出的问题会在浏览器中被回答，而机器人看起来会在轮次中途停止——对于手持手机的人来说，这是最糟糕的结果。

因此，该频道会在持有该槽位的任何提供程序之上安装一个路由器：绑定到 Telegram 聊天的会话会获得内联键盘，而其他所有会话都像以前一样到达浏览器。设置 routeQuestions: false 可将其关闭并恢复普通行为。

这共享了一个宿主建模为独占的槽位，因此其编写方式确保安全失败：在触碰任何内容之前，它会检查该字段是否可写以及现有提供程序是否可识别，将每个它无法解析的会话交给现有提供程序，原样传递该提供程序的拒绝，并在处置时恢复它。未来的 DSH 如果将该字段设为私有，代价是失去此功能，而不是启动失败。

测试

node --test 'test/*.test.js'
涵盖渲染器（转义、强调、表格、分块平衡、注入尝试）和媒体提取（分类、工作区限制、去重、相册分组），且不接触 Telegram。