dsh-telegram-duty（中文说明）

把 DeepSeek Harness（DSH）变成随身值班室：手机 Telegram 发消息 → 值班智能体干活 → 结果回复到手机。空闲时零 token（长轮询 getUpdates，消息到达才唤醒智能体）。

English

版本要求

要求 DeepSeek Harness ≥ 0.1.2-rc.1。 v0.5.0 起插件通过 session.snapshotEvents() 读取会话历史，该接口在 0.1.1-rc.2 及更早版本中不存在（于 dsh-v0.1.2-rc.1 引入）。如果您仍在使用 0.1.1-rc.2 或更早版本，请继续使用 npm 0.4.0——最新版在那上面无法加载。

快速开始（约 10 分钟）

1. 创建机器人：在 Telegram 里找 @BotFather，发送 /newbot，按提示取名，拿到 token（形如 123456:ABC...）。

2. 查自己的 chat id：给 @userinfobot（或你刚建的机器人）发任意消息，它会回复你的数字 id。

3. 安装插件：在 DeepSeek Harness checkout 目录里执行：

   dsh plugin --profile web add @luzhengyangtx/dsh-telegram-duty

4. 填写配置：在 C:\Users\<你>\.dsh\profiles\web\cordis.patch.yml 中加上：

   - id: telegram-duty
     config:
       token: '123456:你的机器人token'   # 第 1 步
       chatId: 123456789                # 第 2 步（白名单）
       language: zh                     # 或 en

5. 重启 dsh web，用手机给你的机器人发条消息——搞定，值班智能体开始回话。

进入值守后，网页顶部会出现横幅提示"审批已转到手机"，点一下即可切回本地。

功能

• 📱 任务闭环：Telegram 消息 → 专属"值班会话"（带标准工具集）→ 最终回复回传手机；长回复自动分段。
• ⏳ 即时反馈：任务消息立即收到"📨 收到，正在生成…"，处理期间手机持续显示"正在输入…"动画，出结果自动消失；出错补发"⚠️ 处理出错"。
• 🎯 定向会话：/sessions 列出你工作区的会话（在线 + 离线，与网页侧边栏一致，空壳草稿不显示）并带编号按钮——点编号后后续消息都发给该会话；消息前加 #编号 只单发这一条；/duty 回默认值班路由；离线会话在第一条定向消息时自动唤醒。
• 🔐 白名单：只服务你自己的 chat id，其他人仅记日志。
• ✅ 全局审批转发：值守模式下，所有会话的审批都发到手机，带 [✅ 同意] [⛔ 拒绝] 按钮（点按钮即答，打字 3 同意 / 3 拒绝 仍兼容）；超时（默认 10 分钟）按拒绝处理（保守安全）。/away 会提醒网页上还挂着的审批，/unblock 可取消被审批卡住的回合。
• ❓ telegram_ask 提问工具：智能体需要您选择方案、确认事项或补充信息时，把问题推送到手机（每个选项一个按钮，点选即答）；值班智能体已被提示优先使用它。
• 📣 telegram_notify 推送工具：任何会话的智能体都能主动把消息推到你手机（汇报、提醒、通知），不用你发消息。
• 🔀 值守/本地切换：手机发任意消息或 /away 进入值守；网页任意会话发消息或 /back 回到本地（本地模式审批走网页弹窗）。
• 🚩 值守横幅：值守期间网页顶部显示"审批已转到手机"横幅，一键切回本地（v0.4.0 起加大一档）。
• 📱 侧边栏"值班"按钮：网页左下角 Settings 旁一键打开值班会话（不存在时自动创建/唤醒），并带实时状态点（值守=橙色，本地=灰色）。
• 🗂 持久化：消息游标与值守状态跨重启保持；仅首次运行跳过历史积压。
• 🌐 中英双语：所有手机消息跟随 language 配置（zh | en，默认 en）。
• 🌍 直连友好：默认直连 Telegram；仅当网络封锁 Telegram（如中国大陆）时才需配置 proxy。

配置（telegram-duty 命名空间）

网页设置页可见可改，也可写在补丁行的 config: 下。

| 字段 | 默认 | 说明 | |------|------|------| | token | — | 机器人 token（secret，界面不展示）；也可用 credentialsFile 提供 | | chatId | — | 白名单 chat id | | proxy | （空） | Bot API 代理地址。⚠ Telegram 可直连的网络请保持留空（默认直连）；仅当网络封锁 Telegram（如中国大陆）时才填本地代理（如 Clash 的 http://127.0.0.1:7890），并保持代理软件开着 | | sessionId | telegram-duty | 值班会话 id，首次消息自动创建 | | dutyCwd | 进程 cwd | 值班会话工作目录 | | approvalTimeoutMinutes | 10 | 审批超时（分钟），超时按拒绝 | | watchMode | local | local / duty | | language | en | 手机消息语言：en / zh | | dataDir | <DSH_HOME>/storages/telegram-duty | 游标持久化目录 | | credentialsFile | — | 可选凭据 JSON 文件 {token, chat_id, proxy} | | replyChunkChars | 3800 | 长回复分段阈值 |

手机命令

• /help — 使用说明
• /sessions — 列出工作区会话（在线 + 离线）带编号按钮，点编号后消息定向到该会话
• #编号 消息 — 只把这一条消息发给指定会话（编号以最近一次 /sessions 为准，30 分钟有效）
• /duty — 回到默认值班会话路由
• /away — 进入值守模式（审批转到手机）；若网页还挂着未处理审批会提醒你
• /unblock — 取消被审批卡住的回合（之后重发任务即可，审批会正确推到手机）
• /back — 回到本地模式
• 3 同意 / 3 拒绝 — 回答第 3 条审批；仅一条待批时直接回"同意/拒绝"；提问点选项按钮或直接回复选项文字。

常见问题（FAQ）

• 机器人不回消息？ 按顺序排查：① token、chatId 是否填对；② 是否给机器人发过 /start（机器人不能主动发起对话）；③ DSH 日志里有没有 telegram-duty 报错；④ 消息是否被当作命令（/away 等不产生回复）。
• chat id 怎么查？ 给 @userinfobot 发任意消息，它会回复你的数字 id。
• 需要代理吗？ 默认不需要，直连 Telegram。国内网络才填 proxy（如 Clash 的 http://127.0.0.1:7890），并且 DSH 运行期间代理软件要一直开着。
• 空闲时耗 token 吗？ 不耗。插件只做长轮询，消息到达才唤醒智能体。
• 电脑关机还能用吗？ 不能，插件随 DSH 一起运行；但重启不丢消息（游标持久化到磁盘）。
• 手机上能收到什么？ 任务结果（含即时"收到"提示与输入中动画）、任意会话的审批请求（值守模式下）、智能体的提问（telegram_ask）、智能体主动推送的消息（telegram_notify）。
• 为什么 /sessions 没列出我所有会话？ 它只列你工作区的会话（和网页侧边栏一致）：空壳草稿隐藏；在线显示空闲/忙碌，离线显示"💤 离线"（首条定向消息自动唤醒）。内部值班会话永不出现——默认路由本来就是它。
• 机器人在群里会回话吗？ 不会，白名单只服务你自己的 chat id，群消息一律忽略。
• 怎么更新插件？ 执行 dsh plugin --profile web add @luzhengyangtx/dsh-telegram-duty@<版本号>，或在 profile 的 package.json 里改依赖版本。

路线图（Roadmap）

| 状态 | 内容 | 版本性质 | |------|------|---------| | ✅ 已发布（v0.4.0） | 定向会话（/sessions、#编号、/duty）· 即时收到提示 + 输入中动画 · telegram_notify 主动推送 · /unblock 审批自救 · 侧边栏值班按钮 · 横幅加大 · 中英双语 | 免费 | | 🚧 计划中（v1.x） | 语音消息笔记、更多实用小功能 | 免费 | | 🔭 仅预告 | 多平台接入（飞书/WhatsApp 等）、团队/多用户模式、云托管、优先支持 | 专业版（未来） |

永远免费：Telegram 值班、全局审批转发、值守/本地切换、网页横幅、中英双语。专业版一行只是预告，目前没有任何专业版代码——它标记的是未来商业版的方向。

定制服务

需要接入帮助、配置指导、接入其它平台或定制功能？发邮件到 [email protected]。常规接入起步价 500 元/单（接入 + 配置 + 答疑），复杂功能按工作量单独报价；开工前会先明确交付范围（跑通 + 文档 + 基础答疑）。

社区与支持

• 💬 Telegram 用户群：https://t.me/+w8w7kAnGniRhZTJk
• 💝 Ko-fi 打赏：https://ko-fi.com/luzhengyangtx
• 💝 爱发电打赏：https://afdian.com/a/luzhengyangtx
• ⭐ GitHub 仓库：https://github.com/luzhengyangtx/dsh-telegram-duty

开发

pnpm --filter "@luzhengyangtx/dsh-telegram-duty" run typecheck
node_modules\.bin\vitest.cmd run packages/interaction/telegram-duty/tests
# 通道自检：$env:TG_CREDS='配置文件路径'; node --import tsx/esm packages/interaction/telegram-duty/scripts/check-telegram.ts

许可证

MIT。会话驱动模式（resume/create + summarize）参考 @kriskwok/dsh-feishu-gateway（MIT），见 LICENSE。