前言¶

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，无需单独部署中转服务。

文档、机器人按钮文案、卡片与日志均为英文；正文这里用中文说明流程，配置字段与命令与仓库 README 一致。

核心功能¶

README 列出的能力均可归纳为以下几类（均以资料原文为准）：

1. 与智能体对话：发往某个 Telegram chat 的文本会作为该 chat 绑定会话的一轮输入；流式推理与工具调用会在同一条消息里原地编辑更新。
2. 从手机操作 Harness：会话（列表 / 恢复 / 分叉 / 重命名 / 归档）、模型与 reasoning effort、工作区与当前项目目录、goals、todos、agent inbox 队列、skills、subagents、agent presets、已装插件、credentials（仅描述）、host 设置、后台任务、host 文件浏览、会话历史等，通过持久按钮栏触达。
3. 回合收据与状态：每轮结束后有一行收据（轮次、步数、工具调用、token、缓存命中率等）；任务进行中状态卡片会刷新。
4. Agent 侧工具：智能体可通过同一桥接向你发消息和文件。
5. 媒体与附件、审批与提问、自动压缩与长任务通知：README 有专节说明，安装后可在 Bot 内按按钮栏与命令探索。

安全模型依赖 chat roster：只有配置里允许的 chat id 能与 Bot 交互（见下文配置）。

安装与启用¶

插件通过 DSH profile 加载。仓库 dist/ 已提交，一般不必本地构建；若你修改了源码，再在插件目录执行 npm ci && npm run build。

方式一：plugin_manager（README 推荐）¶

1. 将插件目录放在本机固定路径（例如从 GitHub 发布页或压缩包 取得源码树，路径记为绝对路径）。
2. 在 DSH 会话中安装 bundle：

plugin_manager(action: "install_bundle", target: "/abs/path/to/dsh-paean-telegram")

仓库内 cordis.patch.yml 会挂载插件 id telegram、名称 dsh-telegram。

3. 若 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 与工作区配置¶

1. Bot Token：为进程设置环境变量 TELEGRAM_BOT_TOKEN，或在插件包旁放置 chmod 600 的 .telegram-token 文件（README「Bot token」节）。
2. 允许聊天的用户：在工作区创建 <workspace>/.pi/telegram.json，写入你的 Telegram chat id，例如：

{ "security": { "allowedChatIds": [123456789] }, "watch": { "autoStart": true } }

3. 重启 Harness。Paean 受管启动器会自动拉起进程，Web UI 与 Bot 会短暂不可用。
4. 在 Telegram 向你的 Bot 发送 /start。

更完整的配置项、命令列表与按钮栏说明见仓库 README 的 Configuration、Commands、Button bar 等章节。

典型用法¶

安装并配置完成后，用法可以概括为：

1. 在允许的 chat 里直接发文字，即对当前绑定会话发起一轮对话。
2. 使用消息下方的持久按钮栏打开 Sessions、模型、工作区、Goals 等卡片，在手机上完成原本要在 Web UI 里点的操作。
3. 需要时通过 README 中的 Commands 与审批/提问流程处理 Host 侧弹出的确认。

每条消息对应一个 chat 绑定会话；切换会话、fork、归档等通过按钮栏或命令完成，无需另开桌面客户端。

适用场景与注意¶

适合谁

• 使用 Paean Harness、希望在手机上与 DSH 智能体对话并管理会话/工作区/目标的用户（插件的首要目标环境）。
• 已在其他 DSH profile 上运行 0.1.1-rc.2 至 0.2.x、愿意自行验证兼容性的用户（README 称非 Paean 专用，DSH 0.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