前言¶
DSH 的会话默认驻留在 web UI 里。想在手机 Telegram 上继续同一个 workspace、同一个 session，常见做法是自己写 bot 轮询 Bot API，再自己映射会话、附件和流式输出，维护成本很高。
dsh-telegram-connector 把这件事做成了一个普通 DSH bundle：一个 Telegram 群对应一个 workspace，一个 forum topic 对应一个 session。它由 vladtsvirko 维护，当前版本 0.13.1，许可证 MIT。插件本身不做任何会话存储，Telegram 只是 harness 的一个投影。
一、它解决什么问题¶
1、会话双端连续。浏览器里开的 session 用 /sync 认领成 topic 并回放历史，手机上开的 session 在浏览器里也能看到。
2、命令与附件协议。媒体走 Bot API 下载后交给 DSH 的 attachment 服务，过程行、反应、转发消息都有明确映射。
3、免开终端的运维。/dashboard、/plugins、/system update connector 让大部分维护动作在聊天里完成。
二、核心能力（来自 README 与 docs/COMMANDS.md）¶
Topic 即 session。 手工建 topic 直接开聊，或用 /new 让 bot 每会话建一个。topic 不会被静默改绑。
Web ↔ 手机连续。 /sync 认领 web UI 里创建的 session，各自建 topic 并回放对话尾部；重命名双向同步；关闭 topic 会归档 session。注意：在 web UI 里做的归档不会镜像过来，需要用 /close。
流式回复。 每轮一条消息，边生成边原地编辑。标题和列表按 Telegram 富文本渲染；表格会先改写，能放进等宽代码块就放，放不下就降级成项目符号列表，因为并非所有 Telegram 客户端都渲染 GFM 表格。富文本被 API 拒绝时依次回退到 HTML 子集、纯文本；切分对代码栅栏和表格是感知的。
阅读与流式反应。 读到 prompt 时加 👀，回复正在编辑时加 ✍，轮次结束撤掉；无说明文字的媒体会暂存并标记 🙉。可用 /reactions 在线改 emoji，Telegram 的固定反应集会被校验。
附件与回复复用。 图片、视频、视频笔记、音频、语音、动画都走 Bot API 下载。相册会去抖后整批附带；无说明文字的上传会等下一个 prompt，而不是每个文件开一轮。回复引用早先的图片/文件/视频/音频消息即可附带，引用会以引用上下文块进入 prompt。
消息映射。 转发消息变成 Forwarded from … 上下文轮；回复一条转发消息会一并记录来源。
过程行。 processMode: live（默认）在一轮运行中编辑一张卡，结束后折叠成摘要；summary 只发摘要；off 隐藏过程行。web UI 会话遵循同一模式。
Host 命令与技能。 /commands、/skills 读取运行时注册表；/<name> 直接加载用户可调用技能，所以新装插件的命令和技能无需等 connector 发版即可用。/run 绕开名称冲突，/skill 强制走技能。
斜杠规则。 只有前导（可跨前导空白）的斜杠才触发命令；消息中间的斜杠按字面处理。/commands@bot 可用，//text 发送以 / 开头的 prompt。命令不带附件，带命令发来的媒体会暂存给下一个 prompt。
Telegram 原生排版。 每个 Telegram session 的 system prompt 会注入一节，指示模型使用 Telegram 富文本 Markdown；完整速查是运行时技能 telegram-rich-text。标题、列表、details、数学、脚注和 <tg-time> 原生渲染。
从聊天管插件。 /plugins 列 profile 的 bundle，/plugin add 先检查 spec（registry 名、github:owner/repo、绝对路径、tarball URL）再要求确认；enable/disable/remove 无需开终端。每次已确认的插件变更都会先进入 trial，HMR 下热切换带回滚窗口，否则重启进入。connector 不允许禁用或移除自身。
通道感知。 Telegram prompt 到达 agent 时带有 [via Telegram] 标记，回答可以走聊天步骤而不是 host 命令；web UI 的 prompt 不带标记。
Dashboard 卡片。 /dashboard 把常用动作做成 inline buttons；群内是 new session、sync、status、sessions，bot 私聊是 status、web link、update、restart、plugins、components。部署类按钮仅 admin 可用。
安装后免 shell 与持久性。 需要 supervisor 才能享受 rollback 窗口与 /system update connector。绑定跨重启保留，session 是恢复而非重建。只有 allowlist 里的 Telegram user id 能驱动 bot。
三、安装与启用¶
先看需求：一个带 web profile 和 agents service 的 DSH 运行时（可选组件——workspace registry、session query/title、plugin manager、container supervisor——运行时检测，缺了就明说而不会崩）；一个来自 @BotFather 的 bot token；一个开启了 Topics 的群，bot 为管理员并有 Manage Topics 权限（要同步群名再加 Change Info）；bot 关闭 privacy mode（BotFather → /setprivacy → Disable）。宿主需要 Node 22 与 pnpm。
DSH 版本要落在 peer 依赖范围内：@deepseek-ai/dsh-agent、dsh-llm、dsh-session 都是 >=0.1.0-rc.6 <0.3.0-0，仓库在 0.2.1-rc.5 上构建测试通过。
发布包安装，tarball 里已含 lib/，不需要 build 脚本：
dsh plugin --profile web add dsh-telegram-connector@0.13.0
从源码仓库安装，先允许构建脚本：
cat >> "$DSH_HOME/profiles/web/pnpm-workspace.yaml" <<'YAML'
allowBuilds:
dsh-telegram-connector@https://github.com/vladtsvirko/dsh-telegram-connector.git: true
YAML
dsh plugin --profile web add github:vladtsvirko/dsh-telegram-connector#v0.13.0
bundle patch 会挂载 dsh-telegram-connector 这一行并从环境读部署值，启动：
export DSH_TELEGRAM_BOT_TOKEN='123456:ABC…'
export ALLOWED_USER_IDS='142283532,987654321' # comma or space separated
export DSH_ADMIN_USER_ID='142283532' # optional; control-chat owner otherwise
dsh --profile web
provider/model 默认是 deepseek-official/deepseek-v4-flash，可用 DSH_PROVIDER/DSH_MODEL 改。adminUserId 可留空，此时私聊的控制聊天所有者成为 admin；allowedUserIds 里其他人可与 agent 对话，只有 admin 能跑 /system、/plugin 变更和 /workspace//bind。allowedUserIds 为空时拒绝所有人。
配置也可以写进 profile override，前提是值放进 cordis.patch.yml：
- id: dsh-telegram-connector
config:
allowedUserIds: [142283532]
adminUserId: 142283532
安装后先给 bot 发 /status，它会回报 connector 版本、运行时版本、模型路由和 poller 状态。组件缺失时 /system status 会明确点名缺少的 supervisor 或 updater，而不是直接失败。
四、典型用法¶
认领 web UI 里的历史会话。 在群里发 /sync，bot 为每个 web session 建 topic 并回放对话尾部。这是把浏览器会话迁到手机的唯一入口。
新开一个会话。 在群的 dashboard topic（或 General）里发 /new，bot 建 session 与对应 topic，之后在该 topic 里直接发文本即一轮。
从聊天装一个新插件。 在 bot 私聊里发 /plugin add <spec>，bot 先检查 spec，展示信息并请求确认；你确认后才会执行安装。安装脚本被 pnpm 拦下时用 /plugin approve 放行并重试。已确认的动作十分钟内有效且绑定发起人，同一时间内只允许一个待确认动作。
更新 connector 自身。 有 supervisor 时发 /system update connector，它会解析兼容的最新版本，拒绝 DSH 范围不覆盖当前运行时的版本；安装失败或启动不健康会自动恢复旧状态。trial 有 Commit 与 Roll back 按钮，超时自动回滚。
无 supervisor 的独立部署。 独立 profile 上没有 rollback 与 /system update connector，更新要手动做：
dsh plugin --profile web remove dsh-telegram-connector
dsh plugin --profile web add dsh-telegram-connector@<new>
插件管理器不允许在已装包上覆盖 git 包，所以必须先移除；装完重启运行时，因为 connector 就是服务聊天的进程，无法原地替换自己。
五、适用场景与注意¶
适合已经有一个正常安装的 DSH web profile 运行时、希望从手机继续会话和做日常运维的人；也适合需要把附件、表格、流式输出处理交给现成实现的团队。独立部署同样可用，只是少了 supervisor 带来的 trial 与自动回滚。
几点务必注意：
1、插件以当前 dsh 进程权限运行。它能触达运行时的 agents、sessions、插件管理器和可选组件。安装前应先检查源码与 MIT 许可证（仓库内 LICENSE），不要直接在不可信主机上装来历不明的 bundle。
2、命令面有固定的归属与权限边界。每个命令只在它所属的面（bot 私聊 / 群 dashboard / session topic）可用，跑到别的面 bot 会告诉你它在哪；/system 变更、/plugin 变更、/workspace//bind 仅 admin 可用。
3、web UI 的归档不镜像、web UI 的 /sync 之外的行为不会自动同步。用 /close 关闭 topic 才归档 session。
4、社区目录是独立站点，与 DeepSeek / 幻方没有官方从属关系。
5、自动化面尚未实现，/schedules 目前是 stub。
6、这个包没有 git clone 之外的安装路径；git 安装需要 pnpm 放行 build 脚本，否则插件不会被构建。
六、结尾¶
这个插件的价值在于不引入影子对话存储：Telegram 只是 harness 的投影，绑定跨重启保留，会话是恢复而非重来。文档方面，命令全表在 docs/COMMANDS.md（bot 的 /man 输出同一段文本，每个命令也接受 --help），映射理由在 docs/DESIGN.md，受支持的 DSH 版本在 COMPATIBILITY.md。
- 目录页：https://www.skillhub.cn/plugins/vladtsvirko/dsh-telegram-connector
- 源码：https://github.com/vladtsvirko/dsh-telegram-connector
