agentquad 0.3.0

package/src/telegram-commands.js

@@ -0,0 +1,149 @@
+/**
+ * 构造给 Telegram 的 slash 菜单 —— Claude Code 命令 + 用户/项目/插件自定义命令。
+ *
+ * 来源（顺序优先）：
+ *   1. src/data/claude-code-commands.json —— 内置静态清单（curated）
+ *   2. ~/.claude/commands/<name>.md —— 用户全局自定义命令
+ *   3. <projectRoot>/.claude/commands/<name>.md —— 项目级自定义命令
+ *   4. ~/.claude/plugins/cache/<plugin>/<version>/commands/<name>.md —— 插件命令
+ *
+ * 后面的源会覆盖前面同名命令的 description。
+ *
+ * Telegram 限制（hard-fail 注册整批，否则只丢这条）：
+ *   - 命令名：^[a-z][a-z0-9_]{0,31}$（**不允许连字符**）
+ *   - description: 1-256 字符
+ *   - 最多 100 条
+ *
+ * 不符合的命令会被静默过滤（warn 一行）。Claude Code 里 `install-github-app`
+ * 这种带 `-` 的命令注册不进 Telegram，但用户在 PTY 直接打字仍可用。
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, basename, extname } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { dirname } from 'node:path'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const STATIC_JSON = join(__dirname, 'data', 'claude-code-commands.json')
+
+const TELEGRAM_NAME_RE = /^[a-z][a-z0-9_]{0,31}$/
+const MAX_DESCRIPTION = 256
+const MAX_COMMANDS = 100
+
+/** 解析 .md 文件 frontmatter 中的 description（YAML 风格 `description: ...`）。 */
+function parseDescription(filePath) {
+  try {
+    const text = readFileSync(filePath, 'utf8')
+    const m = text.match(/^---\s*\n([\s\S]*?)\n---/)
+    if (!m) return null
+    const fm = m[1]
+    // 简单 YAML 解析：找 description: <value>，支持引号
+    const dm = fm.match(/^description:\s*["']?(.+?)["']?\s*$/m)
+    return dm ? dm[1].trim() : null
+  } catch {
+    return null
+  }
+}
+
+/** 扫一个 commands 目录，返回 [{command, description, source}, ...]。 */
+function scanCommandDir(dirPath, source) {
+  if (!existsSync(dirPath) || !statSync(dirPath).isDirectory()) return []
+  const out = []
+  let entries
+  try { entries = readdirSync(dirPath) } catch { return [] }
+  for (const name of entries) {
+    if (!name.endsWith('.md')) continue
+    const cmd = basename(name, extname(name))
+    const description = parseDescription(join(dirPath, name)) || `Custom command (${source})`
+    out.push({ command: cmd, description, source })
+  }
+  return out
+}
+
+/** 找 ~/.claude/plugins/cache 里所有 plugin 的 commands/ 目录。 */
+function findPluginCommandDirs() {
+  const root = join(homedir(), '.claude', 'plugins', 'cache')
+  if (!existsSync(root)) return []
+  const dirs = []
+  try {
+    // 结构 cache/<owner>/<plugin>/<version>/commands
+    for (const owner of readdirSync(root)) {
+      const ownerDir = join(root, owner)
+      if (!statSync(ownerDir).isDirectory()) continue
+      for (const plugin of readdirSync(ownerDir)) {
+        const pluginDir = join(ownerDir, plugin)
+        if (!statSync(pluginDir).isDirectory()) continue
+        for (const ver of readdirSync(pluginDir)) {
+          const cmdsDir = join(pluginDir, ver, 'commands')
+          if (existsSync(cmdsDir)) dirs.push({ path: cmdsDir, source: `plugin:${plugin}` })
+        }
+      }
+    }
+  } catch {}
+  return dirs
+}
+
+/**
+ * 装载静态 JSON 清单。
+ * 容错：JSON 损坏 / 缺字段 → 返回空，让上游决定是否报错。
+ */
+function loadStatic() {
+  try {
+    const raw = readFileSync(STATIC_JSON, 'utf8')
+    const j = JSON.parse(raw)
+    if (Array.isArray(j?.commands)) {
+      return j.commands.map((c) => ({ ...c, source: 'builtin' }))
+    }
+  } catch {}
+  return []
+}
+
+/**
+ * 构造最终 Telegram-ready 命令列表。
+ * @param {object} opts
+ * @param {string} opts.projectRoot - 项目根目录（用于 .claude/commands）
+ * @param {object} [opts.logger]
+ * @returns {{commands: Array<{command:string,description:string}>, skipped: Array<{command:string,reason:string}>}}
+ */
+export function buildTelegramCommands({ projectRoot = process.cwd(), logger = console } = {}) {
+  const all = []
+  all.push(...loadStatic())
+  all.push(...scanCommandDir(join(homedir(), '.claude', 'commands'), 'user'))
+  all.push(...scanCommandDir(join(projectRoot, '.claude', 'commands'), 'project'))
+  for (const { path, source } of findPluginCommandDirs()) {
+    all.push(...scanCommandDir(path, source))
+  }
+
+  // dedupe by name; later entries (project / plugin) win over builtin
+  const map = new Map()
+  for (const c of all) {
+    if (!c?.command) continue
+    map.set(c.command, c)
+  }
+
+  const accepted = []
+  const skipped = []
+  for (const c of map.values()) {
+    if (!TELEGRAM_NAME_RE.test(c.command)) {
+      skipped.push({ command: c.command, reason: 'invalid_name (telegram requires [a-z0-9_])' })
+      continue
+    }
+    let desc = String(c.description || '').trim()
+    if (!desc) {
+      skipped.push({ command: c.command, reason: 'empty_description' })
+      continue
+    }
+    if (desc.length > MAX_DESCRIPTION) desc = desc.slice(0, MAX_DESCRIPTION - 1) + '…'
+    accepted.push({ command: c.command, description: desc })
+  }
+
+  if (accepted.length > MAX_COMMANDS) {
+    skipped.push(...accepted.slice(MAX_COMMANDS).map((c) => ({ command: c.command, reason: 'over_100_limit' })))
+    accepted.length = MAX_COMMANDS
+  }
+
+  if (skipped.length && logger?.warn) {
+    logger.warn(`[telegram-commands] skipped ${skipped.length} command(s): ${skipped.slice(0, 6).map((s) => `${s.command}(${s.reason})`).join(', ')}${skipped.length > 6 ? '…' : ''}`)
+  }
+  return { commands: accepted, skipped }
+}

package/src/telegram-config-service.js

@@ -0,0 +1,84 @@
+/**
+ * Telegram 配置辅助：
+ *  - maskBotToken / isMaskedToken：UI 上 token 的遮罩与回显检测
+ *
+ * 跟 telegram-bot.js 解耦，所有 IO 由 caller 注入。
+ */
+
+const MASK_PREFIX = 'tg_***'
+
+/**
+ * 把真实 token 转成展示串：tg_***末四位。null/空返回 null。
+ */
+export function maskBotToken(token) {
+  if (!token || typeof token !== 'string') return null
+  const tail = token.length >= 4 ? token.slice(-4) : token
+  return MASK_PREFIX + tail
+}
+
+/**
+ * 判断字符串是不是 mask 格式（用户在 UI 没改 token 时回传的就是 mask）。
+ */
+export function isMaskedToken(value) {
+  if (!value || typeof value !== 'string') return false
+  return value.startsWith(MASK_PREFIX)
+}
+
+/**
+ * Probe 状态机：startProbe(durationSec) 后，record(hit) 会写到 buffer 并通知订阅者。
+ * 同一时刻只能有一个活跃 probe（second startProbe 会失败）。
+ *
+ * 时间通过 now() 注入，便于测试。
+ *
+ * 返回：{ startProbe, stopProbe, record, subscribe, isActive, snapshot }
+ */
+export function createProbeRegistry({ now = () => Date.now() } = {}) {
+  let expiresAt = 0
+  let hits = []
+  const subscribers = new Set()
+
+  function isActive() {
+    return now() < expiresAt
+  }
+
+  function startProbe(durationSec) {
+    if (isActive()) return { ok: false, reason: 'already_active' }
+    const clamped = Math.min(120, Math.max(10, Number(durationSec) || 60))
+    expiresAt = now() + clamped * 1000
+    hits = []
+    return { ok: true, durationSec: clamped, expiresAt }
+  }
+
+  function stopProbe() {
+    expiresAt = 0
+    hits = []
+    for (const fn of subscribers) {
+      try { fn(null) } catch {}
+    }
+  }
+
+  function record(hit) {
+    if (!isActive()) return false
+    const entry = { ...hit, at: now() }
+    hits.push(entry)
+    for (const fn of subscribers) {
+      try { fn(entry) } catch {}
+    }
+    return true
+  }
+
+  function subscribe(fn) {
+    subscribers.add(fn)
+    return () => subscribers.delete(fn)
+  }
+
+  function snapshot() {
+    return {
+      active: isActive(),
+      expiresAt,
+      hits: [...hits],
+    }
+  }
+
+  return { startProbe, stopProbe, record, subscribe, isActive, snapshot }
+}

package/src/telegram-image.js

@@ -0,0 +1,95 @@
+/**
+ * 把 Telegram 入站图片下载到本地，让 PTY 写 `@<path>` 喂给 Claude Code 做 attach。
+ *
+ * 流程：
+ *   1) callApi('getFile', { file_id }) → 拿 file_path（telegram 服务器上的相对路径）
+ *   2) GET https://api.telegram.org/file/bot<TOKEN>/<file_path> → 下载二进制
+ *   3) 写到 destDir，返回 { localPath, fileSize }
+ *
+ * 默认存到 ~/.agentquad/tg-uploads/<ts>-<rand>.<ext>，不主动清理（量级小，磁盘占用可忽略）
+ */
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { Buffer } from 'node:buffer'
+import { DEFAULT_ROOT_DIR } from './config.js'
+
+const DEFAULT_DIR = join(DEFAULT_ROOT_DIR, 'tg-uploads')
+const DOWNLOAD_TIMEOUT_MS = 30_000
+const MAX_PHOTO_SIZE_MB = 20  // Telegram 限制 ~20MB
+
+/**
+ * Telegram message.photo 是 array of PhotoSize，按分辨率从小到大排
+ * 选最大那张（通常 width >= 1280 的原图）
+ */
+export function pickLargestPhoto(photos) {
+  if (!Array.isArray(photos) || photos.length === 0) return null
+  return photos.reduce((acc, p) =>
+    (p?.file_size || 0) > (acc?.file_size || 0) ? p : acc, photos[0])
+}
+
+/**
+ * @param {object} opts
+ * @param opts.token Telegram bot token
+ * @param opts.fetchFn (url, opts) => Response（默认全局 fetch；测试可注入）
+ * @param opts.fileId Telegram file_id
+ * @param opts.destDir 下载目标目录（默认 ~/.agentquad/tg-uploads）
+ * @param opts.fileSize 可选，预先校验 ≤ 20MB
+ * @returns {{ localPath: string, fileSize: number, ext: string }}
+ */
+export async function downloadTelegramFile({
+  token,
+  fetchFn,
+  fileId,
+  destDir = DEFAULT_DIR,
+  fileSize = null,
+} = {}) {
+  if (!token) throw new Error('token_required')
+  if (!fileId) throw new Error('fileId_required')
+  if (fileSize && fileSize > MAX_PHOTO_SIZE_MB * 1024 * 1024) {
+    throw new Error(`file_too_large: ${(fileSize / 1024 / 1024).toFixed(1)}MB > ${MAX_PHOTO_SIZE_MB}MB`)
+  }
+  const fetcher = fetchFn || fetch
+
+  // 1. getFile → file_path
+  const ctrl1 = new AbortController()
+  const t1 = setTimeout(() => ctrl1.abort(), DOWNLOAD_TIMEOUT_MS)
+  let filePath
+  try {
+    const resp = await fetcher(`https://api.telegram.org/bot${token}/getFile`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ file_id: fileId }),
+      signal: ctrl1.signal,
+    })
+    const data = await resp.json().catch(() => null)
+    if (!data?.ok || !data.result?.file_path) {
+      throw new Error(`getFile_failed: ${data?.description || resp.status}`)
+    }
+    filePath = data.result.file_path
+  } finally {
+    clearTimeout(t1)
+  }
+
+  // 2. download binary
+  const ctrl2 = new AbortController()
+  const t2 = setTimeout(() => ctrl2.abort(), DOWNLOAD_TIMEOUT_MS)
+  let buf
+  try {
+    const resp = await fetcher(`https://api.telegram.org/file/bot${token}/${filePath}`, {
+      signal: ctrl2.signal,
+    })
+    if (!resp.ok) throw new Error(`download_failed: HTTP ${resp.status}`)
+    const ab = await resp.arrayBuffer()
+    buf = Buffer.from(ab)
+  } finally {
+    clearTimeout(t2)
+  }
+
+  // 3. write to disk
+  mkdirSync(destDir, { recursive: true })
+  const ext = (filePath.split('.').pop() || 'bin').toLowerCase()
+  const localName = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}.${ext}`
+  const localPath = join(destDir, localName)
+  writeFileSync(localPath, buf)
+  return { localPath, fileSize: buf.length, ext }
+}

package/src/telegram-loading-status.js

@@ -0,0 +1,112 @@
+/**
+ * 只做一件事：在 PTY session **终态** 时改 telegram topic 标题前缀。
+ *
+ *   done     → ✅ <name>      （PTY exit 0）
+ *   failed   → ❌ <name>      （PTY exit ≠ 0）
+ *   stopped  → ⏹ <name>      （用户主动 stop）
+ *
+ * running / idle 状态由 src/telegram-reaction-tracker.js 通过给用户消息加/删
+ * ✍ reaction 表达 —— 那条路径粒度更细、节流压力更小，留这里只管终态。
+ *
+ * 限速防御：
+ *   - 全局 backoff（429）保留，但终态硬上，不受 backoff 影响 —— ✅/❌/⏹
+ *     是用户最在意的状态，必须显示。
+ *
+ * 为了向后兼容，markIdle / markRunning / start 接口保留但 running/idle 改为 no-op。
+ */
+
+const TITLE_PREFIX_BY_PHASE = {
+  done:    '✅ ',
+  failed:  '❌ ',
+  stopped: '⏹ ',
+}
+
+const TERMINAL_PHASES = new Set(['done', 'failed', 'stopped'])
+
+/**
+ * @param {object} opts
+ * @param opts.telegramBot { editForumTopic({chatId,threadId,name}) }
+ * @param opts.openclaw    { resolveRoute(sessionId) → {targetUserId, threadId, topicName} | null }
+ * @param opts.logger
+ * @param opts.now         可注入时钟（测试用）
+ */
+export function createLoadingTracker({
+  telegramBot,
+  openclaw,
+  logger = console,
+  now = () => Date.now(),
+  getConfig = null,
+} = {}) {
+  if (!telegramBot) throw new Error('telegramBot_required')
+  void now; void getConfig
+
+  // sessionId → { chatId, threadId, originalTopicName }
+  const sessions = new Map()
+
+  function parseRetryAfter(desc) {
+    const m = String(desc || '').match(/retry after (\d+)/i)
+    return m ? Number(m[1]) : 0
+  }
+
+  async function renameTerminal(state, phase) {
+    if (!telegramBot.editForumTopic || !state.originalTopicName) return
+    const prefix = TITLE_PREFIX_BY_PHASE[phase]
+    if (!prefix) return
+    const newName = (prefix + state.originalTopicName).slice(0, 128)
+    try {
+      await telegramBot.editForumTopic({
+        chatId: state.chatId,
+        threadId: state.threadId,
+        name: newName,
+      })
+    } catch (e) {
+      const desc = e?.description || e?.message || ''
+      const retryAfter = parseRetryAfter(desc) || (e?.parameters?.retry_after) || 0
+      if (/too many requests|429/i.test(desc) || retryAfter > 0) {
+        // 终态硬上：不再阻塞下一次终态 rename，仅 log
+        logger.warn?.(`[loading-status] terminal rename hit 429 sid=${state.sessionId} retry_after=${retryAfter || '?'}s`)
+        return
+      }
+      if (!/not[ _]modified/i.test(desc)) {
+        logger.warn?.(`[loading-status] editForumTopic phase=${phase} failed sid=${state.sessionId}: ${desc}`)
+      }
+    }
+  }
+
+  /**
+   * 注册 session（PTY native-session 时 server.js 调）。不再发任何 rename，
+   * 只把 originalTopicName 记下来给后续 stop 用。
+   * skipTitleRename 现在不影响行为（保留参数避免破坏 caller）。
+   */
+  async function start({ sessionId, skipTitleRename = false } = {}) {
+    if (!sessionId || sessions.has(sessionId)) return
+    void skipTitleRename
+    const route = openclaw?.resolveRoute?.(sessionId)
+    if (!route?.threadId) return
+    if (!route.topicName) return
+    sessions.set(sessionId, {
+      sessionId,
+      chatId: String(route.targetUserId),
+      threadId: route.threadId,
+      originalTopicName: route.topicName,
+    })
+  }
+
+  // running / idle 由 reaction-tracker 处理；这两个接口保留向后兼容，但改为 no-op
+  async function markIdle(_sessionId) { /* no-op */ }
+  async function markRunning(_sessionId) { /* no-op */ }
+
+  async function stop({ sessionId, finalStatus = 'done' } = {}) {
+    const state = sessions.get(sessionId)
+    if (!state) return
+    sessions.delete(sessionId)
+    if (TERMINAL_PHASES.has(finalStatus)) {
+      await renameTerminal(state, finalStatus)
+    }
+  }
+
+  function has(sessionId) { return sessions.has(sessionId) }
+  function size() { return sessions.size }
+
+  return { start, stop, markIdle, markRunning, has, size, __test__: { sessions } }
+}

package/src/telegram-markdown.js

@@ -0,0 +1,82 @@
+/**
+ * 把 LLM 风格的 Markdown（标题、粗体、列表、code block）转成 Telegram MarkdownV2。
+ *
+ * 为什么用 V2 而不是 legacy：
+ *   - legacy Markdown：标题 / 列表无渲染；`**bold**` 字面显示
+ *   - MarkdownV2：标题→粗体、`**`→`*`、`-`→`•`、code block 内不转义
+ * 但 V2 的副作用是正文里的 `_*[]()~`>#+-=|{}.!` 都要转义，错一个就 parse fail。
+ * 所以走 `telegramify-markdown` 这个专门给 LLM 输出做的转换器。
+ *
+ * 用法：在所有 sendMessage / sendDocument(caption) 入口的 text 上跑一遍。
+ * parseMode 同步切到 'MarkdownV2'。
+ */
+import telegramifyMarkdown from 'telegramify-markdown'
+
+/**
+ * 把 markdown 表格行（连续 ≥2 行 `|...|`）包进 ``` 代码块。
+ * 原因：Telegram MarkdownV2 没有 table 渲染，但 fenced code block 能用等宽字体保留对齐
+ * —— 所以我们把表格"伪装"成 code block 让 telegramify 后续按 pre 出。
+ */
+function wrapTablesAsCodeBlock(text) {
+  const lines = String(text).split('\n')
+  const out = []
+  let buf = []
+  const isTableLine = (l) => /^\s*\|.*\|\s*$/.test(l)
+  const flush = () => {
+    if (buf.length >= 2) {
+      out.push('```')
+      for (const l of buf) out.push(l)
+      out.push('```')
+    } else {
+      for (const l of buf) out.push(l)
+    }
+    buf = []
+  }
+  for (const line of lines) {
+    if (isTableLine(line)) {
+      buf.push(line)
+    } else {
+      if (buf.length) flush()
+      out.push(line)
+    }
+  }
+  if (buf.length) flush()
+  return out.join('\n')
+}
+
+/**
+ * 转成 V2-safe 文本。空/非字符串原样返回。库异常时也回退原文，
+ * 让上游 sendMessage 的 plain-text fallback 兜底。
+ *
+ * 表格预处理：先把 markdown 表格包进 ``` code block，让 Telegram 用等宽渲染保留对齐。
+ */
+export function toTelegramV2(text) {
+  if (!text || typeof text !== 'string') return text
+  try {
+    const tablesAsPre = wrapTablesAsCodeBlock(text)
+    // telegramify 会在末尾加一个 '\n' —— 去掉，免得每条消息多一个空行
+    return telegramifyMarkdown(tablesAsPre, 'escape').replace(/\n$/, '')
+  } catch {
+    return text
+  }
+}
+
+/**
+ * V2 解析失败的兜底用：把 markdown 标记**删掉**，正文保留。
+ * 比直接发 raw text（满屏 #### / ** / >）干净得多。
+ *
+ * telegramify 'remove' 只剥 HTML 这种 unsupported tag，markdown 标记会被转成 V2
+ * syntax（*..*、>..），在 plain-text 模式下还是字面字符 — 所以这里直接做正则清洗。
+ *
+ * 注意：inline code（`code`）的 backticks **保留**——plain text 模式下没法显示
+ * 高亮，但留着 backticks 用户至少能识别"这是代码"。比把 `code` 剥成 code 强。
+ */
+export function toPlainText(text) {
+  if (!text || typeof text !== 'string') return text
+  return String(text)
+    .replace(/^#{1,6}\s+/gm, '')             // # / ## / #### 等标题前缀
+    .replace(/\*\*(.+?)\*\*/g, '$1')          // **bold**
+    .replace(/(?<!\w)_([^_\n]+)_(?!\w)/g, '$1')  // _italic_
+    // inline code `code` 不剥 backticks（保留视觉提示）
+    .replace(/^>\s?/gm, '')                   // > blockquote 前缀
+}

package/src/telegram-reaction-tracker.js

@@ -0,0 +1,69 @@
+/**
+ * Telegram message reaction 跟踪器：
+ *   - 用户每发一条触发 PTY 的消息，加 ✍ reaction
+ *   - PTY Stop hook（一轮回复完成）→ 清掉这个 session 期间所有 ✍
+ *
+ * 跟 lark-bot.pendingReactions 对称；Telegram 这边 setMessageReaction 是覆盖式
+ * （传空数组 = 清除），不需要存 reaction_id，只记 (chatId, messageId)。
+ */
+
+const DEFAULT_RUNNING_EMOJI = '✍'
+
+export function createReactionTracker({
+  telegramBot,
+  getConfig = () => ({}),
+  logger = console,
+} = {}) {
+  if (!telegramBot) throw new Error('telegramBot_required')
+
+  // sessionId → [{ chatId, messageId }]
+  const sessions = new Map()
+
+  function getCfg() {
+    return getConfig()?.telegram || {}
+  }
+
+  function isEnabled() {
+    const v = getCfg().reactionEnabled
+    return v !== false
+  }
+
+  function runningEmoji() {
+    return getCfg().reactionRunningEmoji || DEFAULT_RUNNING_EMOJI
+  }
+
+  async function noteUserMessage({ sessionId, chatId, messageId } = {}) {
+    if (!sessionId || !chatId || !messageId) return
+    if (!isEnabled()) return
+    const list = sessions.get(sessionId) || []
+    list.push({ chatId: String(chatId), messageId })
+    sessions.set(sessionId, list)
+    try {
+      await telegramBot.setMessageReaction({ chatId, messageId, emoji: runningEmoji() })
+    } catch (e) {
+      logger.warn?.(`[reaction-tracker] note failed sid=${sessionId} msg=${messageId}: ${e.message}`)
+    }
+  }
+
+  async function clearReactionsForSession(sessionId) {
+    if (!sessionId) return { ok: true, removed: 0 }
+    const list = sessions.get(sessionId)
+    sessions.delete(sessionId)
+    if (!list || list.length === 0) return { ok: true, removed: 0 }
+    let removed = 0
+    for (const { chatId, messageId } of list) {
+      try {
+        await telegramBot.setMessageReaction({ chatId, messageId, emoji: null })
+        removed++
+      } catch (e) {
+        logger.warn?.(`[reaction-tracker] clear failed sid=${sessionId} msg=${messageId}: ${e.message}`)
+      }
+    }
+    return { ok: true, removed, total: list.length }
+  }
+
+  function has(sessionId) { return sessions.has(sessionId) }
+  function size() { return sessions.size }
+
+  return { noteUserMessage, clearReactionsForSession, has, size, __test__: { sessions } }
+}

package/src/telegram-video.js

@@ -0,0 +1,75 @@
+/**
+ * Telegram 视频入站：跟 telegram-image 走同一条 getFile + 下载流水线，
+ * 但兼容多种载体：
+ *   - msg.video         普通视频（mp4/mov…）
+ *   - msg.video_note    圆形短视频（≤1min）
+ *   - msg.animation     GIF / 静音 mp4
+ *   - msg.document      mime_type 以 video/ 开头的文件
+ *
+ * 所有文件统一过 Bot API 的 20MB 上限校验（复用 telegram-image 的下载函数）。
+ *
+ * 不处理：audio / voice / sticker / 非视频 document。
+ */
+import { downloadTelegramFile } from './telegram-image.js'
+
+/**
+ * 从 Telegram message 里挑出"视频载体"。返回 null 表示该消息没有视频。
+ * @returns {{ fileId: string, fileSize: number|null, fileName: string|null, kind: string } | null}
+ */
+export function extractTelegramVideo(msg = {}) {
+  if (!msg || typeof msg !== 'object') return null
+
+  // video 是单个对象（不是 photo 那样的数组）
+  if (msg.video?.file_id) {
+    return {
+      fileId: msg.video.file_id,
+      fileSize: msg.video.file_size || null,
+      fileName: msg.video.file_name || null,
+      kind: 'video',
+    }
+  }
+
+  if (msg.video_note?.file_id) {
+    return {
+      fileId: msg.video_note.file_id,
+      fileSize: msg.video_note.file_size || null,
+      fileName: null,  // video_note 没有 file_name
+      kind: 'video_note',
+    }
+  }
+
+  if (msg.animation?.file_id) {
+    return {
+      fileId: msg.animation.file_id,
+      fileSize: msg.animation.file_size || null,
+      fileName: msg.animation.file_name || null,
+      kind: 'animation',
+    }
+  }
+
+  // document 包了一层 mime_type；只在 video/* 时认领
+  if (msg.document?.file_id) {
+    const mime = String(msg.document.mime_type || '').toLowerCase()
+    if (mime.startsWith('video/')) {
+      return {
+        fileId: msg.document.file_id,
+        fileSize: msg.document.file_size || null,
+        fileName: msg.document.file_name || null,
+        kind: 'document_video',
+      }
+    }
+  }
+
+  return null
+}
+
+/**
+ * 复用 telegram-image 的下载函数。这里单独出一个 thin wrapper，
+ * 便于将来给视频独立调参（比如更大的超时、不同目录），现在保持一致。
+ *
+ * @param opts.token / opts.fetchFn / opts.fileId / opts.fileSize / opts.destDir 同 downloadTelegramFile
+ * @returns {Promise<{ localPath: string, fileSize: number, ext: string }>}
+ */
+export async function downloadTelegramVideo(opts = {}) {
+  return downloadTelegramFile(opts)
+}