前言¶
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
