193 lines
7.6 KiB
Markdown
193 lines
7.6 KiB
Markdown
# dsh-telegram-channel
|
||
|
||
[English](#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](https://t.me/BotFather) 创建 bot 并取得 token |
|
||
| 用户 ID | 通过 [@userinfobot](https://t.me/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（发布后）
|
||
|
||
```powershell
|
||
dsh plugin --profile web add github:<owner>/dsh-telegram-channel
|
||
```
|
||
|
||
将 `<owner>` 替换为实际 GitHub 用户名或组织名。
|
||
|
||
### 从本地目录（开发 / 未发布）
|
||
|
||
```powershell
|
||
dsh plugin --profile web add D:\path\to\dsh-telegram-channel
|
||
```
|
||
|
||
`dsh plugin add` 会读取包内 `cordis.patch.yml` 并合并进 profile。也可参考 [`examples/telegram-agent/`](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 片段：
|
||
|
||
```yaml
|
||
- insert:
|
||
- id: dsh-telegram-channel
|
||
name: dsh-telegram-channel
|
||
config:
|
||
token: ''
|
||
allowedUserIds: [123456789]
|
||
provider: deepseek-official
|
||
model: deepseek-v4-flash
|
||
```
|
||
|
||
设置 token（PowerShell）：
|
||
|
||
```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 决定。
|
||
|
||
## 贡献者：开发与测试
|
||
|
||
```powershell
|
||
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](LICENSE)
|
||
|
||
---
|
||
|
||
## English
|
||
|
||
**dsh-telegram-channel** is a Cordis plugin for [DeepSeek Harness](https://github.com/deepseek-ai) that bridges Telegram (long polling) to `ctx.agents`: per-chat sessions, Chinese auth/command copy, HTML message splitting.
|
||
|
||
Install:
|
||
|
||
```powershell
|
||
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
|
||
|
||
仅在需要公开发布时执行：
|
||
|
||
```powershell
|
||
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
|
||
```
|