前言¶
DeepSeek Harness（DSH）把会话、模型、工作区、目标等能力收进可扩展的 Host 进程里。日常开发时，你多半坐在电脑前用 Web UI 或本地客户端；一旦离开键盘，就很难继续给智能体发指令、看工具调用进度，或切换会话与工作区。
Paean Harness（@paean-ai/harness）是社区里常见的一种 DSH 发行版，自带受管启动器和 web 等 profile，但不自带 Telegram 桥接。上游 dsh-telegram 在 Paean 捆绑的 @deepseek-ai/* 0.2.1-alpha.1 上会因 peer 与 Session API 差异而无法正常使用。维护者 SMMURDA 在 smmurda/dsh-paean-telegram 维护的 fork（npm 包名仍为 dsh-telegram，当前版本 0.4.0）面向这一缺口做了运行时兼容，并声明对其他 DSH profile 为 best effort。下面介绍它是什么、能做什么，以及如何装进 profile 并接上 Bot。
这是什么¶
dsh-paean-telegram 是挂在 DSH Harness Host 进程内的 原生 Telegram 桥接插件，通过 long polling 直接访问 Telegram Bot API，无需单独部署中转服务。
| 项 | 说明 |
|---|---|
| 包名 | dsh-telegram（profile 安装引用此名） |
| 版本 | 0.4.0 |
| 运行时依赖 | grammy |
| 环境要求 | Node.js >= 22；需已有 DSH profile（README 在 Harness 0.1.0-rc.21 与 @deepseek-ai/* 0.2.1-alpha.1 上验证） |
| 许可证 | MIT（fork 自 xqicxx/dsh-telegram，保留原许可与版权声明） |
文档、机器人按钮文案、卡片与日志均为英文；正文这里用中文说明流程，配置字段与命令与仓库 README 一致。
核心功能¶
README 列出的能力均可归纳为以下几类（均以资料原文为准）：
- 与智能体对话：发往某个 Telegram chat 的文本会作为该 chat 绑定会话的一轮输入；流式推理与工具调用会在同一条消息里原地编辑更新。
- 从手机操作 Harness：会话（列表 / 恢复 / 分叉 / 重命名 / 归档）、模型与 reasoning effort、工作区与当前项目目录、goals、todos、agent inbox 队列、skills、subagents、agent presets、已装插件、credentials（仅描述）、host 设置、后台任务、host 文件浏览、会话历史等，通过持久按钮栏触达。
- 回合收据与状态：每轮结束后有一行收据（轮次、步数、工具调用、token、缓存命中率等）；任务进行中状态卡片会刷新。
- Agent 侧工具：智能体可通过同一桥接向你发消息和文件。
- 媒体与附件、审批与提问、自动压缩与长任务通知：README 有专节说明，安装后可在 Bot 内按按钮栏与命令探索。
安全模型依赖 chat roster：只有配置里允许的 chat id 能与 Bot 交互（见下文配置）。
安装与启用¶
插件通过 DSH profile 加载。仓库 dist/ 已提交，一般不必本地构建；若你修改了源码，再在插件目录执行 npm ci && npm run build。
方式一：plugin_manager（README 推荐）¶
- 将插件目录放在本机固定路径（例如从 GitHub 发布页或压缩包 取得源码树，路径记为绝对路径）。
- 在 DSH 会话中安装 bundle：
plugin_manager(action: "install_bundle", target: "/abs/path/to/dsh-paean-telegram")
仓库内 cordis.patch.yml 会挂载插件 id telegram、名称 dsh-telegram。
- 若 profile 在启动时加载插件，重启 Harness 进程。
方式二：手动写入 profile 依赖¶
编辑 ~/.dsh/profiles/<profile>/package.json，用 link: 指向插件目录（改源码后重启 Harness 即可生效）：
{
"dependencies": {
"dsh-telegram": "link:/abs/path/to/dsh-paean-telegram"
}
}
当 peer 范围与当前运行的 dsh 版本不一致时，DSH 可能在 ~/.dsh/profiles/<profile>/compatibility.json 记录 exact-version 豁免；本 fork 的 peer 范围为 >=0.1.1-rc.2 <0.3.0，覆盖 0.1.x 与 0.2.x 两代 seam。本 fork 在 Paean 上主要验证组合为 Paean Harness 0.1.0-rc.21 与 @deepseek-ai/* 0.2.1-alpha.1。
Paean 默认场景：把插件装进实际跑 Paean Harness 的 profile（默认常为 web），再按下一节配置 workspace 与 token。
Bot token 与工作区配置¶
- Bot Token：为进程设置环境变量
TELEGRAM_BOT_TOKEN，或在插件包旁放置chmod 600的.telegram-token文件（README「Bot token」节）。 - 允许聊天的用户：在工作区创建
<workspace>/.pi/telegram.json，写入你的 Telegram chat id，例如：
{ "security": { "allowedChatIds": [123456789] }, "watch": { "autoStart": true } }
- 重启 Harness。Paean 受管启动器会自动拉起进程，Web UI 与 Bot 会短暂不可用。
- 在 Telegram 向你的 Bot 发送
/start。
更完整的配置项、命令列表与按钮栏说明见仓库 README 的 Configuration、Commands、Button bar 等章节。
典型用法¶
安装并配置完成后，用法可以概括为：
- 在允许的 chat 里直接发文字，即对当前绑定会话发起一轮对话。
- 使用消息下方的持久按钮栏打开 Sessions、模型、工作区、Goals 等卡片，在手机上完成原本要在 Web UI 里点的操作。
- 需要时通过 README 中的 Commands 与审批/提问流程处理 Host 侧弹出的确认。
每条消息对应一个 chat 绑定会话；切换会话、fork、归档等通过按钮栏或命令完成，无需另开桌面客户端。
适用场景与注意¶
适合谁
- 使用 Paean Harness、希望在手机上与 DSH 智能体对话并管理会话/工作区/目标的用户（插件的首要目标环境）。
- 已在其他 DSH profile 上运行
0.1.1-rc.2至0.2.x、愿意自行验证兼容性的用户（README 称非 Paean 专用，DSH0.3.x及以后未测试）。
务必注意
- 插件在 当前 DSH Harness 进程的权限与网络环境 下运行，并可代表该 Host 执行你通过 Bot 触发的操作；安装前应阅读源码与 MIT 许可证，并只把 Bot token 与
allowedChatIds交给可信环境。 - 社区插件目录 SkillHub 条目 与 GitHub 仓库由维护者发布，与 DeepSeek / 幻方无官方从属关系；星标与分类以目录页为准（客户端类插件）。
- 故障排查见仓库 Troubleshooting；Paean 与上游插件失败原因、本 build 的 seam 改动见 README「Paean Harness」「Runtime compatibility」「Local changes in this build」。
结尾¶
dsh-paean-telegram（包名 dsh-telegram 0.4.0）把 Telegram 长轮询桥接进 Harness Host，让 Paean 等发行版在缺省无 Telegram 的情况下，仍能从手机聊天并操作会话、模型、工作区与目标。获取说明与更新请以仓库为准：
- 目录页：https://www.skillhub.cn/plugins/SMMURDA/dsh-paean-telegram
- GitHub：https://github.com/SMMURDA/dsh-paean-telegram
