前言¶
DeepSeek Harness（命令名 dsh）把智能體運行時拆成可組合的插件：模型、工具、會話、沙箱和界面都可以在 Cordis 內核上增刪。官方開發者預覽頁把這件事概括成 Everything is a plugin（一切皆插件）。日常入口通常是終端或 npx @deepseek-ai/dsh web 打開的網頁界面。人一旦離開電腦，就沒法繼續給同一個 agent 發消息。
社區插件 telegram 做的是另一條通道：用 Telegram Bot API 的長輪詢，把私聊文本橋接到 harness 裏的 agent 會話。手機上給 bot 發一句話，當前 dsh 進程裏對應聊天的 agent 接着跑；助手回覆再按 HTML 格式分片送回同一條私聊。它不註冊給模型用的工具或技能，只負責「聊天 ↔ 會話」這一層。
需要先說明：下文引用的目錄頁來自獨立社區站點 DeepSeek Harness 插件庫，About 頁寫明該站與 DeepSeek / 幻方沒有官方從屬關係，不能當成官方應用商店。官方倉庫是 deepseek-ai/deepseek-harness。本文按目錄詳情頁、GitHub README / package.json / cordis.patch.yml / src/，以及官方 Harness 說明交叉覈對，覈實日期爲 2026-08-18。
這是什麼¶
telegram 是一款通知與集成插件，由 LoserFox 維護，倉庫爲 LoserFox/telegram。目錄頁與 GitHub 倉庫描述一致：Telegram Bot API 橋接，長輪詢、per-chat 會話、HTML 格式化。
幾個已覈對的歸屬信息：
- npm 包名：
@loserfox/telegram，package.json版本 0.1.0 - 插件插入行 id：
telegram（見cordis.patch.yml） - 主要語言：TypeScript
- GitHub topic：
dsh-plugin - 星標：目錄頁與 GitHub API 均爲 6
- 許可證：
package.json聲明 BSD-3-Clause；倉庫根目錄沒有獨立LICENSE文件，GitHub 的 license 字段因此爲空，安裝前應自行覈對 - 目錄收錄日期：2026-08-05；倉庫最近推送：2026-08-13（當前
main頂端提交a0a9ca11e427b62217250e2e561f6ad3c49d13f2）
它聲明 inject: ['agents']，依賴宿主組合裏已經掛上 @deepseek-ai/dsh-agent。LLM 適配器、會話持久化和 bash / 讀文件等工具都不在這個包裏，而是由外圍 cordis.yml（或當前 profile 的其它層）提供。README 寫明設計參照 NousResearch/hermes-agent 的 telegram 平臺適配器，再裁成 harness 的純文本接縫。
核心功能¶
按 README 與 src/bridge.ts / src/index.ts，能力可以收成下面幾條。
1、長輪詢收消息。 插件用 Bot API 的 getUpdates 拉更新，默認超時 30 秒。沒有 webhook 模式，也不要求公網 IP 或域名；運行 dsh 的主機需要能出站訪問 Telegram API。單條輪詢循環服務所有聊天；空批次會睡 50ms，避免事件循環空轉。
2、每個聊天一個 agent 會話。 已授權的文本消息會按 chat 創建或複用 agent（ctx.agents.create），經 followup 把原文當成用戶消息送進去。會話 id 形如 telegram:<chatId>；/new 與 /clear 會換新的 session 並釋放舊 agent。
3、白名單默認關閉。 allowedUserIds 默認爲空列表，空列表拒絕所有人（fail closed）。allowAllUsers 默認 false，README 標明僅開發用。未授權用戶會收到 Access denied.。
4、Token 加載即校驗。 token 爲空時回退環境變量 DSH_TELEGRAM_TOKEN；兩者都缺則 apply 直接拋錯，不會惰性啓動。
5、回覆做 HTML 格式化並按 4096 分片。 助手文本按保守的 Markdown 子集轉成 Telegram HTML（圍欄代碼、行內代碼、**粗體**，其餘轉義），再按 maxMessageLength（默認 4096）切開，優先在換行、中文句號、句點加空格處斷開。某一片 HTML 被 Telegram 拒絕時，該片回退爲純文本。turn/start 會發 typing 聊天動作。投遞是 fire-and-forget，失敗記日誌後丟棄，沒有發送重試賬本。
6、斜槓命令不到達模型。 /start 歡迎，/new 與 /clear 開新會話，/help 列出命令。其它以 / 開頭的文本按未知命令處理。普通用戶消息則原樣進入該聊天的會話歷史。
安裝與啓用¶
社區目錄頁給出的安裝命令如下，在 DeepSeek Harness 終端裏運行：
dsh plugin add github:LoserFox/telegram
倉庫 README 還寫了掛到指定 profile（例如 web）的寫法，以及裝完後的核對與卸載：
# 安裝到某個 profile，bundle 聲明會進入組合層
dsh plugin --profile web add <dir|git-url>
# 驗證插入行
dsh --profile web --dump-config | grep telegram
# 卸載
dsh plugin --profile web remove telegram
目錄頁提示：如需可復現安裝，可固定 commit 哈希，形式爲 dsh plugin add github:LoserFox/telegram#commit。以 2026-08-18 看到的 main 頂端爲例：
dsh plugin add github:LoserFox/telegram#a0a9ca11e427b62217250e2e561f6ad3c49d13f2
幾點安裝約束：
- 組合層變更不參與 HMR，裝完或卸完需要重啓目標 profile 的 DSH 進程。
- 宿主必須已經掛載
agents服務。peerDependencies 裏寫的是@deepseek-ai/dsh-agent^0.1.0-rc.6，以及@deepseek-ai/dsh-llm、@deepseek-ai/dsh-session、@deepseek-ai/cordis、@deepseek-ai/schemastery等組合包。 - 目錄頁寫明：插件以當前 dsh 進程的權限運行，安裝時可能執行代碼。安裝前檢查源代碼倉庫和許可證。
配置與典型用法¶
配置項¶
src/index.ts 裏的 TelegramConfig 與 README 表格一致：
| 鍵 | 默認 | 含義 |
|---|---|---|
token |
'' |
@BotFather 創建的 bot token；空則讀 DSH_TELEGRAM_TOKEN |
allowedUserIds |
[] |
允許對話的 Telegram 用戶 id；空列表拒絕所有人 |
allowAllUsers |
false |
允許任意用戶（僅開發用） |
provider |
deepseek-official |
創建 agent 時傳入的 LLM provider id |
model |
deepseek-v4-flash |
創建 agent 時傳入的模型 id |
maxMessageLength |
4096 |
單條 Telegram 消息長度上限 |
pollingTimeoutSec |
30 |
長輪詢超時（秒） |
日誌會經 ctx.logger 輸出，bot token 會被脫敏。生產環境走全局 fetch 和真實定時器；client 與 sleep 只是測試接縫。
倉庫自帶的 telegram-agent 示例¶
倉庫 examples/telegram-agent/ 是一份可運行的 cordis.yml：Telegram 橋接加上 DeepSeek 適配器、bash / 文件工具、subagent、todo、JSONL 會話持久化和自動壓縮。它掛載的是本倉庫構建產物 ../../lib/index.js，需要本機已有能解析 @deepseek-ai/* 的 DeepSeek Harness checkout，並且 dsh 在 PATH 上。
運行時環境變量（摘自該示例的中文 README）：
| 變量 | 用途 |
|---|---|
DSH_TELEGRAM_TOKEN |
bot token（必填） |
DSH_TELEGRAM_ALLOWED_USER_IDS |
允許的用戶 id，逗號分隔 |
DSH_TELEGRAM_ALLOW_ALL_USERS |
true 時放開所有用戶（僅開發） |
DEEPSEEK_API_KEY |
傳給 OpenAI 兼容端點的憑據 |
DEEPSEEK_BASE_URL |
dsh-llm-deepseek 使用的主機端點 |
DSH_CWD |
bash 與文件工具的工作目錄 |
DSH_SESSION_ROOT |
JSONL 軌跡目錄 |
DSH_SYSTEM_PROMPT |
編碼 persona |
示例啓動命令：
cd examples/telegram-agent
DSH_TELEGRAM_TOKEN=<token> DSH_TELEGRAM_ALLOW_ALL_USERS=true \
DEEPSEEK_API_KEY=<key> dsh --config cordis.yml
allowAllUsers=true 只適合本機試跑。對外服務應改成顯式的 DSH_TELEGRAM_ALLOWED_USER_IDS，不要開全員訪問。token 和白名單都從環境變量讀入，cordis.yml 裏不落密鑰。
在 Telegram 裏怎麼說話¶
先用 @BotFather 建 bot、拿到 token，再把 token 和自己的用戶 id 配進插件。進程起來之後，私聊裏可用：
/start：建立會話，回覆歡迎詞Hello! I am the DeepSeek Harness agent. Send me a message or /help for commands./help：列出/start、/new、/clear、/help/new或/clear：換新會話，舊 agent 釋放，回覆Started a fresh session.- 普通文本：進入該 chat 的 agent，助手最終文本分片發回
模型側看不到輪詢幀和投遞調用；命令也不會進上下文。工具中間進度不會作爲獨立 Telegram 消息流式發出，用戶看到的是每條 assistant 輸出對應的一組分片。
適用場景與注意事項¶
適合已經在跑 DeepSeek Harness、希望用 Telegram 私聊當展示層的人：出差時追問當前 agent、給 bot 發一句讓它在本機工作區裏改文件或跑命令。模型可見的工具集合完全取決於外圍組合——示例裏是 bash、read / write / edit、subagent、todo_write；只把插件加進 web profile、卻沒有對應工具層，私聊裏就只有會話，沒有那些工具。
README 列出的已知限制，使用前要按字面理解：
- 僅文本。 照片、文檔、語音、貼紙和 caption 會被忽略。
- 僅私聊。 羣聊 @ 提及和話題（topics）未處理。
- 沒有 webhook。 進程必須能出站訪問 Telegram API；國內網絡若訪問不到，這個包本身沒有代理配置項。
- 沒有投遞重試。 除 HTML 失敗回退純文本外，發送失敗記日誌後丟棄。
- 組合層不熱更新。 改完插件要重啓 dsh 進程。
安全方面再強調一次。插件以當前 dsh 進程權限運行，示例裏的 bash 與文件工具作用在 DSH_CWD（默認當前工作目錄）上。Bot token 等同登錄憑證，不要寫進可提交的配置文件。白名單爲空時拒絕所有人，這是有意的 fail closed，不要爲了「先通一下」就在生產環境打開 allowAllUsers。
小結¶
telegram 把 Telegram 私聊接到 DeepSeek Harness 的 agent 會話上：長輪詢收文本、一聊天一會話、HTML 分片回寫。它是社區維護的後臺橋接插件，不是官方應用，也不代替 LLM、工具和會話層。目錄頁與源碼倉庫如下，裝之前核對許可證和當前提交：
- 目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/telegram/
- GitHub：https://github.com/LoserFox/telegram
- 官方 Harness：https://github.com/deepseek-ai/deepseek-harness
