@qzsy/dsh-bridge 0.0.0-stage → 2.18.0

package/lib/telegram/index.js

@@ -0,0 +1,255 @@
+// dsh-bridge Telegram platform adapter
+// 编排 TelegramGateway（长轮询 + 代理支持）+ TelegramConversationNode（Telegram⇄DSH 会话桥）。
+// 作为 Platform 子类，注册进 PlatformManager 统一管理。
+
+import QRCode from 'qrcode'
+import { Platform } from '../platform/base.js'
+import { applySessionConfig, readSessionConfig } from '../platform/session-config.js'
+import { TelegramGateway } from './gateway.js'
+import { TelegramConversationNode } from './node.js'
+
+export class TelegramService extends Platform {
+  /**
+   * @param {object} opts
+   * @param {object} opts.ctx          Cordis 上下文
+   * @param {object} opts.logger       日志器
+   * @param {object} [opts.config]     已持久化的 telegram 配置（凭证 + allowFrom + 间隔）
+   * @param {(patch: object) => (void|Promise<void>)} opts.onPersist  主插件保存回调
+   */
+  constructor({ ctx, logger, config = {}, onPersist, instanceId, serviceName }) {
+    super({ ctx, logger, config, onPersist })
+    this.id = 'telegram'
+    // issue #78：同类型可并行多实例；缺省回退类型 id 保持单实例旧行为
+    this.instanceId = instanceId || this.id
+    this.displayName = null
+    this.name = 'Telegram'
+    this._botQrCache = { username: '', qr: '' }
+
+    this.gateway = new TelegramGateway(ctx, {
+      // issue #78：instanceId 用于事件隔离；serviceName 是唯一 cordis 服务名（D2）
+      instanceId: this.instanceId,
+      serviceName,
+      botToken: config.botToken ?? '',
+      proxy: config.proxy ?? '',
+    })
+
+    // 仅首个实例占用 ctx.telegram 槽位（兼容外部读取方）；节点已改为显式接收网关
+    try { if (!ctx.telegram) ctx.telegram = this.gateway } catch {}
+
+    this.node = new TelegramConversationNode(ctx, {
+      allowFrom: Array.isArray(config.allowFrom) ? config.allowFrom : [],
+      groupAutoApprove: config.groupAutoApprove,
+      changesDigest: config.changesDigest,
+      showActivity: config.showActivity,
+      steerMode: config.steerMode,
+      digestIntervalSec: config.digestIntervalSec,
+      approvalTimeoutSec: config.approvalTimeoutSec,
+      maxMessageChars: config.maxMessageChars || 4096,
+      sendChunkDelayMs: config.sendChunkDelayMs,
+      activeSessionId: config.activeSessionId,
+      // 会话级配置：工作区 / Agent 预设 / 模型路由（构造期来自 cordis 配置，运行期由设置页写入）
+      cwd: config.cwd,
+      agentPreset: config.agentPreset,
+      agentProvider: config.agentProvider,
+      agentModel: config.agentModel,
+    }, logger, {
+      onFirstSender: () => this.persist({ allowFrom: [...(this.node?.config?.allowFrom ?? [])] }),
+      onActiveSessionChange: (sessionId) => this.persist({ activeSessionId: sessionId }),
+      gateway: this.gateway,
+      instanceId: this.instanceId,
+    })
+    this.bridge = this.node
+
+    if (this.gateway.configured) {
+      void this.start().catch((err) => {
+        this.logger.error?.('[dsh-bridge telegram] start failed:', err?.message ?? err)
+      })
+    }
+  }
+
+  // ---- Platform 接口 ----
+
+  get configured() { return this.gateway.configured }
+  get accountId() { return this.gateway.accountId }
+
+  get capabilities() {
+    return {
+      group: true,
+      media: true,
+      approvals: true,
+      maxMessageChars: this.node.config.maxMessageChars || 4096,
+    }
+  }
+
+  async sendText(peerId, text, opts = {}) {
+    return this.gateway.sendText(peerId, text, opts)
+  }
+
+  async sendTyping(peerId, opts = {}) {
+    return this.gateway.sendTyping?.(peerId, opts)
+  }
+
+  // ---- 生命周期控制 ----
+
+  async start() {
+    if (!this.gateway.configured) {
+      this.setStatus('idle')
+      return { success: false, error: 'Telegram Bot Token 未配置' }
+    }
+    this.setStatus('starting')
+    const ok = await this.gateway.start()
+    if (ok) {
+      this.setStatus('connected')
+      return { success: true }
+    } else {
+      this.setStatus('error', '连接 Telegram API 失败，请检查 Bot Token 或网络代理')
+      return { success: false, error: '连接失败' }
+    }
+  }
+
+  async stop() {
+    await this.gateway.stop()
+    this.setStatus('offline')
+    return { success: true }
+  }
+
+  /**
+   * 配置或登录
+   * @param {object} creds - { botToken, proxy }
+   */
+  async login(creds = {}) {
+    const patch = {}
+    if (creds.botToken !== undefined) patch.botToken = String(creds.botToken).trim()
+    if (creds.proxy !== undefined) patch.proxy = String(creds.proxy).trim()
+
+    this.gateway.setCredentials(patch)
+    this.persist(patch)
+
+    if (!this.gateway.configured) {
+      await this.stop()
+      return { success: false, error: '请填写完整的 Telegram Bot Token' }
+    }
+
+    return this.start()
+  }
+
+  async unbind() {
+    await this.stop()
+    this.gateway.setCredentials({ botToken: '', proxy: '' })
+    this.persist({ botToken: '', proxy: '', allowFrom: [] })
+    if (this.node) this.node.config.allowFrom = []
+    return { success: true }
+  }
+
+  getStatus() {
+    const allowFrom = [...(this.node?.config?.allowFrom ?? [])]
+    const username = this.gateway.botInfo?.username || ''
+    const botLink = username ? `https://t.me/${encodeURIComponent(username)}` : null
+    if (botLink && this._botQrCache.username !== username) {
+      this._botQrCache.username = username
+      void QRCode.toDataURL(botLink, {
+        width: 260,
+        margin: 2,
+        color: { dark: '#1F2421', light: '#FFFFFF' },
+      }).then((qr) => {
+        this._botQrCache.qr = qr
+      }).catch(() => {})
+    }
+
+    return {
+      id: this.id,
+      // issue #78：实例标识（instanceId 为全局唯一键，platformId 为平台类型）
+      instanceId: this.instanceId,
+      platformId: this.id,
+      displayName: this.displayName ?? this.name,
+      name: this.name,
+      status: this.status === 'connected' ? 'connected' : this.gateway.status,
+      configured: this.gateway.configured,
+      accountId: this.gateway.accountId || (this.gateway.configured ? '已配置 Token' : ''),
+      allowFrom,
+      peerId: this.node?.peerId,
+      sessionId: this.node?.activeSessionId,
+      login: {
+        phase: this.status === 'connected' ? 'done' : this.status === 'error' ? 'error' : 'idle',
+      },
+      capabilities: { ...this.capabilities },
+      config: {
+        name: this.config.name ?? '',
+        digestIntervalSec: this.node?.config?.digestIntervalSec,
+        approvalTimeoutSec: this.node?.config?.approvalTimeoutSec,
+        maxMessageChars: this.node?.config?.maxMessageChars,
+        sendChunkDelayMs: this.node?.config?.sendChunkDelayMs,
+        // issue #77 ①：与飞书同缺陷——不回读这三个字段，设置页勾选会"回退"
+        groupAutoApprove: this.node?.config?.groupAutoApprove === true,
+        changesDigest: this.node?.config?.changesDigest !== false,
+        showActivity: this.node?.config?.showActivity === true,
+        steerMode: this.node?.config?.steerMode === true,
+        botToken: this.gateway.config.botToken ? '******' : '',
+        proxy: this.gateway.config.proxy || '',
+        ...readSessionConfig(this.node?.config),
+      },
+      botInfo: this.gateway.botInfo,
+      botLink,
+      botQr: this._botQrCache.qr,
+    }
+  }
+
+  setAllowFrom(allowFrom) {
+    const list = Array.isArray(allowFrom) ? allowFrom.map((s) => String(s).trim()).filter(Boolean) : []
+    if (this.node) this.node.config.allowFrom = list
+    this.persist({ allowFrom: list })
+    return { success: true, allowFrom: list }
+  }
+
+  async setConfig({ digestIntervalSec, approvalTimeoutSec, maxMessageChars, sendChunkDelayMs, groupAutoApprove, changesDigest, showActivity, steerMode, botToken, proxy, name, agentPreset, cwd, agentProvider, agentModel } = {}) {
+    if (digestIntervalSec != null)   this.node.config.digestIntervalSec   = Number(digestIntervalSec)
+    if (approvalTimeoutSec != null)  this.node.config.approvalTimeoutSec  = Number(approvalTimeoutSec)
+    if (maxMessageChars != null) {
+      const val = Number(maxMessageChars)
+      this.node.config.maxMessageChars = (val >= 200) ? val : 4096
+    }
+    if (sendChunkDelayMs != null)    this.node.config.sendChunkDelayMs    = Number(sendChunkDelayMs)
+    if (groupAutoApprove != null)    this.node.config.groupAutoApprove    = groupAutoApprove === true
+    if (changesDigest != null)       this.node.config.changesDigest       = changesDigest === true
+    if (showActivity != null)        this.node.config.showActivity        = showActivity === true
+    if (steerMode != null)           this.node.config.steerMode           = steerMode === true
+    applySessionConfig(this.node.config, { agentPreset, cwd, agentProvider, agentModel })
+    // issue #78：账号备注名（面板回显 + displayName 来源），随 setConfig 持久化
+    if (name !== undefined) this.config.name = String(name).trim()
+
+    if (botToken !== undefined || proxy !== undefined) {
+      const patch = {}
+      if (botToken !== undefined) patch.botToken = botToken.trim()
+      if (proxy !== undefined) patch.proxy = proxy.trim()
+      this.gateway.setCredentials(patch)
+    }
+
+    const patch = {
+      digestIntervalSec:  this.node.config.digestIntervalSec,
+      approvalTimeoutSec: this.node.config.approvalTimeoutSec,
+      maxMessageChars:    this.node.config.maxMessageChars,
+      sendChunkDelayMs:   this.node.config.sendChunkDelayMs,
+      groupAutoApprove:   this.node.config.groupAutoApprove === true,
+      changesDigest:      this.node.config.changesDigest !== false,
+      showActivity:       this.node.config.showActivity === true,
+      steerMode:          this.node.config.steerMode === true,
+      ...readSessionConfig(this.node.config),
+    }
+    if (botToken !== undefined) patch.botToken = this.gateway.config.botToken
+    if (proxy !== undefined) patch.proxy = this.gateway.config.proxy
+    if (name !== undefined) patch.name = this.config.name ?? ''
+    await this.persist(patch)
+
+    if (this.gateway.configured && (botToken !== undefined || proxy !== undefined)) {
+      await this.start().catch((err) => {
+        this.logger?.warn?.('[dsh-bridge telegram] auto-start failed: %s', err?.message ?? err)
+      })
+    }
+    return { success: true }
+  }
+
+  dispose() {
+    super.dispose()
+    this.gateway?.dispose?.()
+  }
+}

package/lib/telegram/node.js

@@ -0,0 +1,410 @@
+// dsh-bridge Telegram conversation node
+// 把 Telegram OpenAPI / 长轮询入站事件解析后交给平台无关的
+// ConversationBridge 处理，出站通过 TelegramGateway 发送文本 / Inline Keyboard 按钮 / 媒体。
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { ConversationBridge, conversationBridgeHelpers } from '../platform/conversation-bridge.js'
+import { cumulativeSlices } from '../platform/stream-slices.js'
+import { escapeMarkdown } from '../platform/activity.js'
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function splitIntoIncremental(text, maxChunkSize = 200) {
+  if (!text) return []
+  const chunks = conversationBridgeHelpers.splitForIM(text, maxChunkSize)
+  if (chunks.length <= 1) {
+    if (text.length <= maxChunkSize) return [text]
+    const mid = Math.ceil(text.length / 2)
+    return [text.slice(0, mid), text]
+  }
+  return cumulativeSlices(chunks)
+}
+
+/**
+ * 平台适配对象（桥通过 `this.platform` 调用各能力）。
+ *
+ * @param {object} gateway Telegram 网关
+ * @param {{ setActivityStatus?: Function }} [hooks] 会话桥需要的能力钩子。
+ *   **必须挂在 platform 上**（桥调的是 this.platform.xxx，不是节点自身）——
+ *   飞书侧曾因挂错对象导致状态永不显示，这里遵循同一约定。
+ */
+function makePlatform(gateway, hooks = {}) {
+  return {
+    id: 'telegram',
+    name: 'Telegram',
+    get accountId() { return gateway.accountId ?? '' },
+    get capabilities() { return gateway.capabilities },
+    get status() { return gateway?.status ?? 'idle' },
+    async sendText(peerId, text, opts = {}) {
+      return gateway?.sendText(peerId, text, opts)
+    },
+    async sendMediaFile(peerId, filePath, opts = {}) {
+      return gateway?.sendMediaFile(peerId, filePath, opts)
+    },
+    async sendTyping(peerId) {
+      return gateway?.sendTyping(peerId)
+    },
+    // 轮次中的"活动状态"：桥按鸭子类型探测（与飞书同一约定）
+    ...(typeof hooks.setActivityStatus === 'function'
+      ? { setActivityStatus: (line, opts, parts) => hooks.setActivityStatus(line, opts, parts) }
+      : {}),
+    dispose() {},
+  }
+}
+
+export class TelegramConversationNode extends ConversationBridge {
+  constructor(ctx, config = {}, logger = console, { onFirstSender, onActiveSessionChange, gateway: explicitGateway, instanceId } = {}) {
+    // issue #78：显式接收所属网关，不再依赖 ctx.telegram 槽位（多实例时槽位会被覆盖）
+    const gateway = explicitGateway ?? ctx.telegram
+    super({
+      ctx,
+      logger,
+      config: {
+        maxMessageChars: 4096,
+        ...config,
+      },
+      // 惰性转发：makePlatform 在 super() 参数里构造，此刻 this 尚不可用，
+      // 故转发函数运行时才取 this.setActivityStatus（定义在类上）。
+      platform: makePlatform(gateway, {
+        setActivityStatus: (line, opts, parts) => this.setActivityStatus(line, opts, parts),
+      }),
+      onFirstSender,
+      onActiveSessionChange,
+    })
+
+    this.gateway = gateway
+    // 事件过滤标识：只处理本实例网关发出的事件，避免同类型多账号串消息
+    this.instanceId = instanceId ?? gateway?.instanceId ?? 'telegram'
+    this._lastPeer = null
+    this._streamMsgId = null
+    this._streamContent = ''
+    this._inTurn = false
+    this._activityLine = '' // 轮次中的活动状态行（收尾时清空，避免残留"进行中"）
+
+    // 事件仅属于本实例（旧事件无 instanceId 时按单实例兼容放行）
+    const forThisInstance = (event) => !event?.instanceId || event.instanceId === this.instanceId
+
+    // 订阅网关入站消息事件
+    this.disposers.push(this.ctx.on('telegram/message', (event) => {
+      if (!forThisInstance(event)) return
+      return this._handleInbound(event)
+    }))
+
+    // 订阅 Inline 按钮点击交互事件（审批确认）
+    this.disposers.push(this.ctx.on('telegram/action', (event) => {
+      if (!forThisInstance(event)) return
+      return this._handleAction(event)
+    }))
+
+    // 监听轮次事件：turn/start 开启流式打字机，turn/end 最终刷新并重置
+    this.disposers.push(this.ctx.on('session/event', (session, event) => {
+      if (session.id !== this.activeSessionId) return
+      if (event.type === 'turn/start') {
+        this._inTurn = true
+        this._streamMsgId = null
+        this._streamContent = ''
+        this._activityLine = ''
+      } else if (event.type === 'turn/end') {
+        this._inTurn = false
+        // 清状态行并把**纯净正文**写回一次：否则消息会残留「正在运行命令…」，
+        // 让用户以为任务还在跑（飞书侧实测过该问题）。
+        this._activityLine = ''
+        if (this._streamMsgId && this._streamContent) {
+          const peerId = this._lastPeer?.chatId || this.peerId
+          if (peerId) {
+            void this.gateway?.editMessageText(peerId, this._streamMsgId, this._streamContent).catch(() => {})
+          }
+        }
+        this._streamMsgId = null
+        this._streamContent = ''
+      }
+    }))
+  }
+
+  async _handleInbound(event) {
+    if (this.gateway?._stopPolling) return
+    const { chatId, senderId, senderUsername, isGroup, text, messageId, raw } = event
+    this._lastPeer = { chatId, senderId, senderUsername, isGroup }
+    const authId = isGroup ? chatId : senderId
+
+    // 检查是否有富媒体附件（图片 / 文件 / 语音 / 音频）
+    let mediaFiles = []
+    if (raw) {
+      mediaFiles = await this._processInboundMedia(raw, this.config.cwd)
+    }
+
+    if (!text && mediaFiles.length === 0) {
+      this.logger.debug?.(`[dsh-bridge telegram] ignore empty message from ${chatId}`)
+      return
+    }
+
+    let fullText = text || ''
+    if (mediaFiles.length > 0) {
+      const mediaDesc = mediaFiles.map((f) => `[文件: ${f.path}]`).join('\n')
+      fullText = fullText ? `${fullText}\n\n${mediaDesc}` : mediaDesc
+    }
+
+    this.logger.debug?.(`[dsh-bridge telegram] handling inbound message from ${chatId} (group=${isGroup}): ${fullText}`)
+
+    // 如果还没有活动会话，且是首条消息，自动尝试选择最新已有会话
+    if (!this.activeSessionId) {
+      await this._pickDefaultSession().catch(() => {})
+    }
+
+    // 转交通用 ConversationBridge 路由
+    // outboundPeer：本轮出站事件流绑定回发起会话（chat 而非成员），替代此前被静默丢弃的 peerId 幽灵参数
+    return this.handleInbound({
+      senderId: authId,
+      isGroup,
+      text: fullText,
+      outboundPeer: { peerId: chatId, isGroup },
+    })
+  }
+
+  async _processInboundMedia(rawMsg, sessionCwd) {
+    if (!this.gateway) return []
+    const downloaded = []
+
+    try {
+      // 1. 照片（选择最高分辨率的一张）
+      if (Array.isArray(rawMsg.photo) && rawMsg.photo.length > 0) {
+        const bestPhoto = rawMsg.photo[rawMsg.photo.length - 1]
+        if (bestPhoto?.file_id) {
+          const res = await this.gateway.downloadFile(bestPhoto.file_id, sessionCwd)
+          if (res) downloaded.push(res)
+        }
+      }
+      // 2. 文档 / 文件
+      else if (rawMsg.document?.file_id) {
+        const res = await this.gateway.downloadFile(rawMsg.document.file_id, sessionCwd)
+        if (res) downloaded.push(res)
+      }
+      // 3. 语音 / 音频
+      else if (rawMsg.voice?.file_id) {
+        const res = await this.gateway.downloadFile(rawMsg.voice.file_id, sessionCwd)
+        if (res) downloaded.push(res)
+      } else if (rawMsg.audio?.file_id) {
+        const res = await this.gateway.downloadFile(rawMsg.audio.file_id, sessionCwd)
+        if (res) downloaded.push(res)
+      }
+    } catch (err) {
+      this.logger.warn?.(`[dsh-bridge telegram] process media error: ${err.message}`)
+    }
+
+    return downloaded
+  }
+
+  async _handleAction(event) {
+    const { queryId, chatId, operatorId, data } = event
+    if (!data || !this.gateway) return
+
+    // 1. 审批决议按钮 (approve:ID / reject:ID)
+    const match = /^([a-zA-Z]+):(\d+)$/.exec(data)
+    if (match) {
+      const [, action, approvalIdStr] = match
+      const approvalId = Number(approvalIdStr)
+      const outcome = action === 'approve' ? 'allowed-once' : 'rejected'
+      const pending = this.pending.get(approvalId)
+
+      if (pending) {
+        this.clearApproval(approvalId)
+        pending.resolve(outcome)
+        await this.gateway?.answerCallbackQuery(
+          queryId,
+          action === 'approve' ? '✓ 操作已批准' : '✕ 操作已拒绝',
+          false,
+        )
+      } else {
+        await this.gateway?.answerCallbackQuery(queryId, '⚠️ 该审批已处理或已过期', false)
+      }
+      return
+    }
+
+    // 2. 快捷指令交互按键 (cmd:xxx)
+    if (data.startsWith('cmd:')) {
+      const cmdBody = data.slice(4)
+      await this.gateway?.answerCallbackQuery(queryId, `⚡ 执行: /${cmdBody.replace(':', ' ')}`, false)
+      let text = `/${cmdBody.replace(':', ' ')}`
+      if (cmdBody.startsWith('use:')) {
+        text = `/use ${cmdBody.slice(4)}`
+      }
+      return this.handleInbound({
+        senderId: operatorId || chatId,
+        isGroup: false,
+        text,
+        outboundPeer: { peerId: chatId, isGroup: false },
+      })
+    }
+  }
+
+  async _sendTextNow(text, opts = {}) {
+    // T2.3：轮次绑定的 outboundPeer（chat 级目标）优先生效
+    const peerId = opts?.outboundPeer?.peerId || this._lastPeer?.chatId || this.peerId
+    if (!peerId || !this.gateway) return
+    const content = String(text || '').trim()
+    if (!content) return
+
+    // 如果处于 Agent 生成轮次中（turn 期间）：流式打字机逐段增量更新
+    if (this._inTurn) {
+      const maxChunk = 200
+      const slices = splitIntoIncremental(content, maxChunk)
+      const delayMs = Math.min(Math.max(this.config.sendChunkDelayMs ?? 800, 400), 2000)
+
+      if (!this._streamMsgId) {
+        // 首片：创建消息并记录 message_id
+        const firstSlice = slices[0] || content
+        try {
+          const res = await this.gateway.sendText(peerId, this._withStatus(firstSlice))
+          this._streamMsgId = res?.message_id || null
+          this._streamContent = firstSlice
+        } catch (err) {
+          this.logger.warn?.('[dsh-bridge telegram] sendText stream initial failed:', err?.message ?? err)
+          await this.gateway.sendText(peerId, content).catch(() => {})
+          return
+        }
+
+        // 后续片依次 editMessageText（间隔 delayMs，呈现平滑打字机流式效果）
+        for (let i = 1; i < slices.length; i++) {
+          await sleep(delayMs)
+          this._streamContent = slices[i]
+          if (this._streamMsgId) {
+            await this.gateway.editMessageText(peerId, this._streamMsgId, this._withStatus(this._streamContent)).catch(() => {})
+          }
+        }
+      } else {
+        // 消息已存在（同轮次后续输出）：必须**累积**而非覆盖。
+        // 宿主对每个 step 发一条独立的 `assistant/message`（该步的片段，不是整轮全文），
+        // 直接覆盖会让用户看到"输出一半消失、又重新输出"、最终只剩最后一段
+        // （2026-10-16 飞书侧真机复现，Telegram 同一实现同样受影响）。
+        const merged = this._streamContent ? `${this._streamContent}\n\n${content}` : content
+        if (merged.length <= 4000) {
+          this._streamContent = merged
+          await this.gateway.editMessageText(peerId, this._streamMsgId, this._withStatus(this._streamContent)).catch(() => {})
+        } else {
+          // 超出 4000 字符，另起一条新消息继续流式（保留已输出内容在前一条里）
+          const res = await this.gateway.sendText(peerId, content).catch(() => null)
+          this._streamMsgId = res?.message_id || null
+          this._streamContent = content
+        }
+      }
+      return
+    }
+
+    // 非 turn 期间（指令响应、系统提示、单条通知等）：
+    // 若命中帮助/状态/会话列表等特定系统命令响应，挂载原生快捷交互按钮
+    if (content.includes('命令帮助') || content.includes('/new <提示词>')) {
+      const buttons = [
+        [
+          { text: '📋 会话列表', callback_data: 'cmd:sessions' },
+          { text: '📁 工作区', callback_data: 'cmd:workspaces' },
+        ],
+        [
+          { text: '📊 运行状态', callback_data: 'cmd:status' },
+          { text: '⏹ 停止任务', callback_data: 'cmd:stop' },
+        ],
+      ]
+      return this.gateway.sendKeyboard(peerId, content, buttons)
+    }
+
+    if (content.includes('Agent 状态') || content.includes('无活动会话')) {
+      const buttons = [
+        [
+          { text: '🔄 刷新状态', callback_data: 'cmd:status' },
+          { text: '⏹ 停止任务', callback_data: 'cmd:stop' },
+        ],
+        [
+          { text: '📋 会话列表', callback_data: 'cmd:sessions' },
+          { text: '🚪 结束会话', callback_data: 'cmd:end' },
+        ],
+      ]
+      return this.gateway.sendKeyboard(peerId, content, buttons)
+    }
+
+    if (content.includes('会话列表') || content.includes('可用会话')) {
+      const buttons = [
+        [
+          { text: '📁 可用工作区', callback_data: 'cmd:workspaces' },
+          { text: '📊 查看状态', callback_data: 'cmd:status' },
+        ],
+      ]
+      return this.gateway.sendKeyboard(peerId, content, buttons)
+    }
+
+    if (content.length <= 4000) {
+      return this.gateway.sendText(peerId, content)
+    }
+    const chunks = conversationBridgeHelpers.splitForIM(content, 4000)
+    for (const chunk of chunks) {
+      await this.gateway.sendText(peerId, chunk)
+    }
+  }
+
+  /**
+   * 把"当前活动"状态行拼到正文前（与飞书同一呈现：引用块 + 斜体）。
+   *
+   * Telegram 侧由 gateway 的 HTML 格式化把 `> quote` 转成 `<blockquote>`、
+   * `_text_` 转成斜体（见 lib/telegram/gateway.js 的格式化步骤），因此语法可直接复用。
+   * detail 做 markdown 转义：命令原文里的 `*` `_` `` ` `` 会破坏样式。
+   */
+  _withStatus(text) {
+    const status = this._activityLine
+    if (!status) return text
+    const styled = `> _${status}_`
+    return text ? `${styled}\n\n${text}` : styled
+  }
+
+  /**
+   * 更新"当前活动"状态（由会话桥在 tool/call 时调用）。
+   *
+   * @param {string} line 纯文本状态行（老平台路径）
+   * @param {object} [_opts]
+   * @param {{icon:string,text:string,detail:string,suffix:string}} [parts] 结构化形式（detail 会被转义）
+   */
+  async setActivityStatus(line, _opts, parts) {
+    this._activityLine = parts ? this._styleActivityParts(parts) : (line || '')
+    // 已有流式消息时立即刷新（否则等下一片自然带上）
+    if (this._streamMsgId && this._streamContent !== undefined) {
+      const peerId = this._lastPeer?.chatId || this.peerId
+      if (peerId) {
+        try {
+          await this.gateway?.editMessageText(peerId, this._streamMsgId, this._withStatus(this._streamContent))
+        } catch {
+          // 此处是 debug 级的非关键失败（流式状态行刷新），日志里**不拼接任何动态值**：
+          // 错误对象源自 Telegram API 响应，静态分析会将其视为外部可控输入
+          // （js/log-injection）。固定文案即可，无需牺牲可诊断性——真正的失败会由
+          // 上层 turn/end / 发送失败路径以更完整的上下文记录。
+          this.logger?.debug?.('[dsh-bridge telegram] 状态行刷新失败（详见上层日志）')
+        }
+      }
+    }
+  }
+
+  /** 受控文案保持原样、detail 转义后组装（避免命令原文破坏样式）。 */
+  _styleActivityParts(parts) {
+    const icon = String(parts?.icon ?? '')
+    const text = String(parts?.text ?? '')
+    const suffix = String(parts?.suffix ?? '')
+    const detail = parts?.detail ? escapeMarkdown(parts.detail) : ''
+    const head = detail ? `${icon} ${text}（${detail}）` : `${icon} ${text}`
+    return `${head}${suffix}`
+  }
+
+  async sendTyping() {
+    const peerId = this._lastPeer?.chatId || this.peerId
+    if (!peerId || !this.gateway) return
+    return this.gateway.sendTyping(peerId)
+  }
+
+  dispose() {
+    this._inTurn = false
+    this._streamMsgId = null
+    this._streamContent = ''
+    this._lastPeer = null
+    super.dispose()
+  }
+}
+
+export const telegramNodeHelpers = { makePlatform }