dsh-telegram-channel

English · 中文

DeepSeek Harness（DSH）的 Telegram 渠道 Cordis 插件：长轮询接入 Bot API，按聊天创建独立 agent，将助手回复以 HTML 分片回传。开箱路径是 dsh plugin add，目标约 10 分钟内完成安装到首条 agent 回复。

特性

• 标准 Cordis 插件（inject: ['agents']），通过 cordis.patch.yml 挂入 profile
• 长轮询 getUpdates，无需公网 webhook
• 按 chat 内存会话映射；/new 可重置对话
• 白名单鉴权（fail-closed）；鉴权与命令文案默认中文
• Markdown 子集 → Telegram HTML，超长自动分片；HTML 被拒时降级纯文本
• 无 token 时软失败：打日志、不启轮询，不拖垮整个 profile

前置条件

项	要求
Node.js	≥ 22
DeepSeek Harness	已能运行目标 profile（如 dsh web），并完成官方要求的 API Key 等配置
Telegram	通过 @BotFather 创建 bot 并取得 token
用户 ID	通过 @userinfobot 等获取自己的 Telegram numeric user id

快速开始（≤10 分钟）

1. 确认本机 dsh web（或你的目标 profile）可正常启动。
2. 取得 bot token 与自己的 user id。
3. 安装本插件（见下方「安装」）。
4. 设置 DSH_TELEGRAM_TOKEN，并在插件配置中填写 allowedUserIds（推荐 env 存 token，避免误提交）。
5. 重新加载或启动 profile。
6. 在 Telegram 向 bot 发送 /start，再发一条普通消息，应收到 agent 回复；发送 /new 应提示已开启新会话。

安装

从 GitHub（发布后）

dsh plugin --profile web add github:<owner>/dsh-telegram-channel

将 <owner> 替换为实际 GitHub 用户名或组织名。

从本地目录（开发 / 未发布）

dsh plugin --profile web add D:\path\to\dsh-telegram-channel

dsh plugin add 会读取包内 cordis.patch.yml 并合并进 profile。也可参考 examples/telegram-agent/ 中的示例 patch。

环境变量与配置

推荐：token 走环境变量，白名单写在 patch / 插件配置中。

键	默认	含义
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	创建 agent 时的模型 id
maxMessageLength	4096	单条 Telegram 消息长度上限
pollingTimeoutSec	30	getUpdates 长轮询超时（秒）
cwd	未设置时用进程 cwd	传给 agent 的工作目录

示例 patch 片段：

- insert:
    - id: dsh-telegram-channel
      name: dsh-telegram-channel
      config:
        token: ''
        allowedUserIds: [123456789]
        provider: deepseek-official
        model: deepseek-v4-flash

设置 token（PowerShell）：

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

修改配置后需重新加载或重启 profile 才会生效。

命令

命令	行为
/start	欢迎与简短用法；不调用模型
/help	命令列表与白名单 / 会话说明
/new 或 /clear	释放该 chat 的 agent，下次普通消息重建会话
未识别的 /...	提示可用命令
普通文本	create / followup → 回传助手文本

故障排查

现象	可能原因	处理
日志出现 missing bot token；bot 无响应	未设置 config.token 且未设置 DSH_TELEGRAM_TOKEN	设置 env 或 patch 中的 token，然后重载 profile
收到「无权限。」	user id 不在 allowedUserIds，或白名单为空	用 @userinfobot 核对 id，写入 allowedUserIds
Telegram 401 / token 无效	token 错误或已撤销	在 BotFather 重新生成 token 并更新 env
有 typing 但无文字回复	profile 内 LLM / agent 配置或 API Key 问题	查看 DSH 日志；先在同一 profile 用 CLI 验证 agent
重启 Harness 后对话「失忆」	MVP 会话仅内存，设计如此	直接发消息或 /new 重建；跨重启持久化见 Phase 2
npm install 报 peer 冲突	上游 DSH RC 包 dsh-invariants 版本未对齐	贡献者使用 npm install --legacy-peer-deps（见下文）

Phase 2 路线图（不进 MVP）

1. 运维键盘：新对话 / 状态 / 停止 / 更多
2. 进度体验：同消息编辑流式、阶段摘要
3. 会话持久化：chat↔session 跨重启
4. cwd / 项目切换：对接 harness workspace 策略
5. Telegram 侧切换 provider / model
6. 媒体：图片接入视觉类工具（若 profile 具备）
7. 可选 webhook（需公网 HTTPS）

安全说明

• Fail-closed 白名单：allowedUserIds 为空且 allowAllUsers: false 时，所有人被拒绝。
• Token 优先走环境变量，避免写入版本库；日志中对 token 做脱敏。
• allowAllUsers: true 仅用于本地调试，不要在生产 profile 开启。
• 本插件不自行启动 LLM；模型、工具与沙箱由所在 DSH profile 决定。

贡献者：开发与测试

git clone <repo-url> D:\gitData\dsh-telegram-channel
cd D:\gitData\dsh-telegram-channel
npm install --legacy-peer-deps
npm test
npm run build

说明：当前 DSH RC 系列包的 @deepseek-ai/dsh-invariants peer 版本尚未完全对齐，直接 npm install 可能 ERESOLVE。使用 --legacy-peer-deps 可正常安装 devDependencies 并完成构建与单测；运行时由宿主 profile 提供 peer 包。

手工冒烟（需真实 bot）

在单元测试与构建通过后，可用以下步骤验收（本仓库发布前未在此环境执行 live Telegram 冒烟）：

1. npm run build
2. dsh plugin --profile web add <本仓库路径>
3. 设置 DSH_TELEGRAM_TOKEN 与 allowedUserIds
4. 启动 / 重载 profile
5. Telegram：/start → 发消息 → 收到回复；/new 仍可用

Last verified（最后验证）

项	值
包版本	0.1.0
验证日期	2026-08-14
验证方式	npm test（25/25 通过）+ npm run build
DSH peer（package.json）	@deepseek-ai/cordis ^4.0.1 · @deepseek-ai/dsh-agent ^0.1.0-rc.6 · @deepseek-ai/dsh-llm ^0.0.1-rc.1 · @deepseek-ai/dsh-session ^0.0.1-rc.1
Live Telegram 冒烟	未执行（见上方操作清单）

许可证

MIT

---

English

dsh-telegram-channel is a Cordis plugin for DeepSeek Harness that bridges Telegram (long polling) to ctx.agents: per-chat sessions, Chinese auth/command copy, HTML message splitting.

Install:

dsh plugin --profile web add github:<owner>/dsh-telegram-channel
# or local: dsh plugin --profile web add D:\path\to\dsh-telegram-channel

Set DSH_TELEGRAM_TOKEN and allowedUserIds in plugin config. Empty allowlist rejects everyone (fail-closed). Missing token: logs error, does not start polling (soft-fail).

Contributors: npm install --legacy-peer-deps due to upstream DSH peer alignment.

Last verified: package 0.1.0, 2026-08-14 — unit tests + build pass; live bot smoke not run in CI.

License: MIT.

Optional: publish to GitHub

仅在需要公开发布时执行：

gh repo create dsh-telegram-channel --public --source=D:\gitData\dsh-telegram-channel --remote=origin --push
gh repo edit --add-topic dsh-plugin
git tag v0.1.0
git push origin v0.1.0