前言¶

在 DSH（DeepSeek Harness）里做智能体时，常见需求是让会话能读写信道、回群聊或私聊，而不是只在本地面板里自言自语。Telegram 一侧若走 MTProto（例如 Telethon），通常要手机号登录，并往往还要常驻客户端进程。社区里同生态的 dsh-qq-tools 采用「每个工具一个组件」的拆法；dsh-tg-tools 把同一思路搬到 Telegram，但只走 Telegram Bot API：一个 bot token 即可收发消息，不必引入 MTProto。代价是能力边界受 Bot API 约束，本地「历史」也只是轮询缓存，不是服务端全量历史。

下面介绍插件定位、组件能力、安装配置与使用时的注意点。事实以维护者仓库 README 与 package.json 为准。

这是什么¶

• 名称：dsh-tg-tools（npm 包名）
• 维护者：dshbot-by-TingXia
• 分类：联网工具（社区目录 SkillHub）
• 版本（资料中明确）：1.0.1
• 许可证：MIT

插件给 DSH 会话提供一组独立的 cordis 组件：列 chat、查 chat、读本地缓存消息、发文字/图片/贴纸/GIF/骰子、reaction、转发/编辑/删除、查成员与 typing，以及可选的 getUpdates 收消息与唤醒目标会话。另有一个设置组件，用于选择挂载到哪条 DSH 会话并在 Web 侧改配置。

关掉「收消息」只影响轮询和缓存；只读类工具（列 chat、查 chat、看缓存、查成员、查贴纸包）不产生平台写副作用。

核心功能¶

每个工具对应插件页「包含的组件」里的一行开关，可按需启用。

已知限制（README 摘要）：tg_get_history 仅本地缓存；Bot API 无法列出群全部成员，只能列管理员；图片/贴纸/GIF 暂不支持直接上传本地文件（需 URL 或 file_id）；同一 bot token 不能同时有两个 getUpdates 轮询，否则 409 Conflict。

安装与启用¶

DSH 生态里插件通过 dsh plugin 挂到指定 profile，并合并包内 cordis.patch.yml；安装或升级后需重启 DSH。

从 GitHub 安装（命令来自官方 README）：

dsh plugin --profile <profile> add github:dshbot-by-TingXia/dsh-tg-tools

本地开发可用 link 路径；离线可用 pnpm pack 后的 tarball。卸载：

dsh plugin --profile <profile> remove dsh-tg-tools

运行环境：Node.js >=22；DSH 0.2.x（具体范围见包内 dsh.compatibility）；浏览器半侧依赖 DSH Web 的 locale / slots / plugins.row.config 能力。

在 BotFather 创建 bot 并取得 token。若要在群里收到非 @ 消息，需在 @BotFather 执行 /setprivacy 并 Disable，或依赖 @ bot / 回复 bot。

配置¶

首次启动会生成 ~/.dsh/tg-tools-config.json（权限 600）。典型字段如下：

{
  "apiBase": "https://api.telegram.org",
  "botToken": "",
  "targetSession": "",
  "chats": [],
  "historyLimit": 50,
  "maxHistoryLimit": 200,
  "pollEnabled": false,
  "pollTimeout": 25,
  "wakeOnPrivate": true,
  "wakeOnMention": true,
  "wakeAll": false,
  "wakeChats": [],
  "timeoutMs": 10000
}

简要含义：

1. botToken：可写在配置文件，也可留空并改用 TG_TOOLS_BOT_TOKEN / TELEGRAM_BOT_TOKEN 或 ~/.dsh/.env。
2. targetSession：工具挂载的 DSH 会话；设置页修改，或 POST /api/dsh-tg-tools/target-session。
3. chats：允许操作的 chat id 或 @username；为空时发消息不限制目标，但入站唤醒全部拒绝（fail-closed）。
4. pollEnabled：是否长轮询 getUpdates；默认 false。开启前确认没有其他程序用同一 token 轮询。
5. 唤醒：wakeOnPrivate / wakeOnMention / wakeAll / wakeChats 控制何种消息会把摘要投递给目标会话。

插件页「Telegram 设置」与左侧栏提供图形配置；读写接口为 /api/dsh-tg-tools/config（同源），保存后约 3 秒生效，无需重启。

收消息与典型用法¶

收消息与唤醒¶

将 pollEnabled 设为 true 后，插件会：

1. 把 bot 收到的消息写入 ~/.dsh/tg-tools-state.json（每 chat 最多 300 条），供 tg_get_history 读取；
2. 在私聊、群里 @/回复 bot（或 wakeAll 命中规则）时，向目标会话投递摘要，并提示可用回复工具。

chats 与 wakeChats 都为空时不会唤醒任何会话，消息只进缓存。正式使用建议把要操作的 chat 写进名单，避免公开 bot 被陌生人用来触发会话、消耗模型额度。

会话侧怎么用¶

启用对应组件后，在已挂载的 targetSession 里，模型按工具 schema 调用即可，例如：

• 先 tg_list_chats 或凭配置中的 chats 确定目标；
• 用 tg_get_history 看已缓存的近期消息（不是加入群之前的记录）；
• 用 tg_send_message 回复，需要时用 tg_send_photo / tg_send_sticker 等；
• 需要人类在 Telegram 侧主动找 bot 时，打开收消息组件并配置唤醒与白名单。

仓库提供离线冒烟测试 npm test（test/smoke.mjs），使用假 Bot API 与临时 DSH_HOME，不连接真实 Telegram。

适用场景与注意¶

适合：已在 DSH 里做自动化或助手，希望用 单一 bot token 完成 Telegram 出站与可选入站唤醒；愿意接受 Bot API 能力上限；需要像 dsh-qq-tools 那样按组件精细开关工具的场景。

不适合或需额外方案：要读 Telegram 全量服务端历史、要列全群成员、要直接上传本地媒体文件而不经过公开 URL——当前 README 标明这些不在范围内或需变通。

安全与权限：

• 插件以当前 DSH 进程的权限运行；安装前建议阅读源码与 SECURITY.md，确认 token 与 chat 白名单策略符合你的威胁模型。
• token 存于 ~/.dsh/tg-tools-config.json（600）或环境变量/credential store；诊断日志 ~/.dsh/tg-tools-diag.log 不含 token。
• 只把 bot 拉进允许它读写的群；chats 为空时出站目标不受限，更易误发，生产环境建议写死名单。
• 自动发消息存在平台风控风险，宜低频并在必要时人工确认。

DeepSeek Harness 社区插件目录由 SkillHub 等站点维护，与 DeepSeek / 幻方无官方从属关系；「一切皆插件」是 DSH 的使用方式，本文仅介绍该第三方联网工具包。

链接¶

• 社区目录页：https://www.skillhub.cn/plugins/dshbot-by-TingXia/dsh-tg-tools
• 源码与完整说明：https://github.com/dshbot-by-TingXia/dsh-tg-tools