前言¶

把 DSH 接到即时通讯里，常见做法是再起 Web 服务、SessionController 或上传端点，还要处理配对、审批回调和流式输出。若目标只是「一个已授权用户的私聊窗口里跑 Agent」，能力边界可以收得更紧：Host 侧插件、固定 slash 命令、凭证与状态落在 profile 外目录，且不通过 Telegram 做审批。

下面介绍社区插件 dsh-telegram-bridge（维护者 yoggu，分类：联网工具）。它是 Host-only 的 Cordis bundle，面向 单个预先授权 的 Telegram 私聊；依赖 DSH 的 headless Agent/Session 服务，持久化 offset、session 与 schedule 状态，并 拒绝 基于 Telegram 的审批流程。

这是什么¶

• 定位：Host-only DSH 插件，用于已授权私聊场景（README 与 package.json 描述一致）。
• 仓库：https://github.com/yoggu/dsh-telegram-bridge
• 当前版本（package.json）：0.1.2，许可证 MIT。
• 运行环境：Node >=22.19.0；DSH 0.1.7-rc.2 或 ^0.2.0-rc.1；需 Cordis Agent、Session、SessionQuery、preset registry 等 peer 依赖。

插件不包含应用专属 persona 或工作区路径；消费该 bundle 的 DSH profile 自行定义 agentPreset、工具、模型适配器、沙箱与审批策略。

核心功能¶

README 中明确的能力与限制如下。

消息与命令

• 支持纯文本，以及 /start、/help、/status、/new、/compact、/stop。
• 不支持：配对、附件、callback 审批、流式输出。
• 授权用户的交互式提示期间，会尽力展示 Telegram「正在输入」指示，直至完成、取消或超时。

Session 与模型

• /new 会立即持久化创建新 session。
• /compact 仅在当前 空闲 session 上运行，不会对部分已提交的操作盲目重试；自动 compaction 由消费 profile 的 agent preset 提供，而非 bridge 自带。
• /status 只报告当前 session 是否 ready/working 及配置的 model，不暴露 chat/session 标识。
• 启动时通过 Telegram setMyCommands 为授权私聊注册 slash 菜单（与文本命令处理器分离）。

调度（可选）

• 在配置中开启 enableSchedules、IANA timeZone 与 jobs 后，由适配器 内部 调度（不是 DSH reminder 插件）。
• 迟到超过两分钟的槽位会跳过，不补跑；每个槽位在模型工作前 pin 住，生成最多一次。
• 完成文本或失败通知写入 durable outbox；Telegram 发送会分块重试，传输错误可能导致某块重复。

与其他 Host 的关系

• 若 Web GUI 共用同一 session 存储，README 建议仅通过 Web Host 用可选的 workspace-reconciliation.js 分组外部 Telegram session，且 不要 在同一 JSON 存储上挂载两个 workspace registry。

语言

• 命令菜单、帮助、状态、错误与定时失败通知默认 英文；在本 Host 的插件配置中设 language: de 可保留德文措辞。公开 schema 接受 en 与 de；模型回答与操作者提供的 prompt/job 标签不翻译。

安装与启用¶

官方推荐从 GitHub 带版本 tag 安装到 拥有 Telegram bot 的 DSH profile（示例 profile 名为 telegram；请改用你实际运行的 profile）。bridge 应使用 Dedicated DSH process/profile，不要与无关 Agent 共用。

dsh plugin --profile telegram add 'https://github.com/yoggu/dsh-telegram-bridge.git#v0.1.2'

本地 checkout 链接方式（需保持链接目录存在；同样指定 v0.1.2）：

git clone --branch v0.1.2 --depth 1 https://github.com/yoggu/dsh-telegram-bridge.git
cd dsh-telegram-bridge
pnpm install
dsh plugin --profile telegram add "link:$(pwd)"

卸载：

dsh plugin --profile telegram remove dsh-telegram-bridge

安装前请自行查看仓库源码与 MIT 许可证；插件以当前 DSH 进程的权限与沙箱策略运行，部署侧应配置 sandbox/permission preset 禁止权限升级（bridge 无法阻止其他 Host 集成中的 direct mode 切换）。

配置要点¶

安装 bundle 后，在 消费 profile 中提供 overlay，例如：

- id: telegram-bridge
  config:
    cwd: /absolute/agent/workspace
    dataDir: /absolute/private/telegram/data
    agentPreset: existing-agent-preset
    permissionPreset: workspace-write
    provider: existing-local-provider
    model: exact-model-id
    reasoningEffort: low
    timeZone: Europe/Zurich
    enableSchedules: false
    jobs: []

凭证（勿写入 YAML）

在 dataDir 内预先放置 credentials.json，目录权限 0700，文件权限 0600：

{ "botToken": "<token>", "allowedUserId": <numeric-id> }

Host 不会 自动配对。该 bot token 只能由 这一个 bot 与其 DSH profile 轮询；DSH 状态、schedule outbox 与独占 poller socket 也位于该 data 目录。

权限与 cwd

• 本进程内创建的 Agent 均 pinned 到配置的 cwd 与 workspace-write。
• 所有 LLM 流（含辅助调用与 resumed session）限制为配置的 exact provider/model。
• workspace-write 还允许临时写 /tmp、全局读与网络访问；可信 Host 在 agent workspace 外写自身状态。

定时任务示例

    enableSchedules: true
    timeZone: Europe/Zurich
    jobs:
      - id: daily-report
        label: Daily report
        hour: 7
        minute: 0
        prompt: /daily-report
        permissionPreset: read-only

jobs 条目需唯一 id，以及 label、hour（0–23）、minute（0–59）、可选 weekday（Mon…Sun）、prompt、permissionPreset（read-only 或 workspace-write）。配置为 read-only 的 job 在 prompt 前会显式切换 permission preset。

典型用法¶

1. 单独起一个 DSH profile/process，安装 v0.1.2 bundle。
2. 在 overlay 中指定 cwd、dataDir、agentPreset、provider、model 等；在 dataDir 写入 credentials.json。
3. 在 Telegram 与 bot 的 已授权私聊 中发送文本或 slash 命令驱动 Agent；用 /new 开新会话，/compact 整理当前空闲会话，/status 查看就绪状态与模型。
4. 若需要定时 skill prompt，打开 enableSchedules 并配置 jobs；首次定时运行建议人工观察（README 说明非 exactly-once，崩溃可能丢 inbound update，Transport 异常可能导致分块重复）。

与 Web GUI 共用存储时，按 README 仅用 Web Host 侧 reconciliation 插件整理 session，避免双 registry。

适用场景与注意¶

适合

• 只要 一个 预先知道 Telegram user id 的私聊入口、希望用 DSH headless 跑 Agent、且不需要 Telegram 审批/附件/流式的部署。
• 愿意给 bridge 独占 profile、独占 bot token 轮询，并把凭证与运行时状态放在仓库外的 private 目录。

务必注意

• 交互 inbound 在执行业务前即 ack；崩溃可能丢失 update，不是 exactly-once。
• 拒绝 Telegram-based approvals；敏感操作仍依赖 DSH 侧 sandbox 与 permission preset，安装前检查源码与策略。
• 社区目录 SkillHub 插件页 与 GitHub 为独立信息源，与 DeepSeek / 幻方无官方从属关系；星标与版本以仓库为准。

结尾¶

dsh-telegram-bridge 把 DSH Agent/Session 收到 Host-only、单用户私聊 Telegram 通道里：命令面清晰、凭证外置、可选内部调度。若你的需求是轻量私聊运维而非全功能 IM 网关，可按 README 的安装命令与 profile overlay 落地。

• 目录页：https://www.skillhub.cn/plugins/yoggu/dsh-telegram-bridge
• GitHub：https://github.com/yoggu/dsh-telegram-bridge