[feature] che-telegram-all-mcp — 補 download_file / get_message_media tool（目前只能讀 placeholder 不能取實檔）

[kiki830621]

Problem

Original context（使用者對話 2026-04-26 22:00 前後）：

我（Claude）在 kiki830621/collaboration_gukai#5（SNQ 申請 issue）想自動把 Roy 透過 Telegram 傳的附件抓下來上傳到 attachments release，但 che-telegram-all-mcp 沒有檔案下載工具。dump_chat_to_markdown 只把媒體寫成 [photo] / [document] placeholder，沒寫實檔；get_chat_history 回傳 message 含 file_name、type 等 metadata 但沒有 file_id 可下載的端點。

使用者觀察：

在 idd-issue 不會自動作嗎？我以為根據裡面的原則會自動作，因為要保留所有原本的資料

idd-issue spec Step 4「附加圖片（如果有）」要求自動把來源附件上傳到 attachments release。但 Telegram 來源的附件根本下不下來——這是 MCP server 的能力缺口。

Type

feature

Expected

至少其中一個 tool：

1. get_message_media —{chat_id, message_id, output_path} → 把該 message 的媒體（photo / document / video / audio / sticker）下載到 output_path
2. dump_chat_to_markdown 加 media 模式 — {include_media: true, media_dir: "..."} 把 [photo] / [document] 變成實際檔名連結並把檔下載到 media_dir

最小可行版本（MVP）建議從 get_message_media 開始：

{
  "name": "get_message_media",
  "description": "Download a message's media attachment to a local path",
  "input_schema": {
    "chat_id":     { "type": "integer", "required": true },
    "message_id":  { "type": "integer", "required": true },
    "output_path": { "type": "string",  "required": true,
                      "description": "Absolute path; existing file overwritten" }
  },
  "returns": {
    "path":      "string (saved local path)",
    "mime_type": "string (e.g. application/pdf)",
    "file_name": "string (original Telegram file_name if available)",
    "size":      "integer (bytes)"
  }
}

TDLib 對應 API：downloadFile（搭配 Message.content 內的 file.id / file.remote.id）。

Actual

grep -rli "download\|getFile" che-telegram-all-mcp/Sources/ → 0 matches

get_chat_history 回傳 photo / document message 時 schema 範例：

{
  "type": "document",
  "file_name": "113A272_申請計畫書.pdf",
  "id": 8173649920,
  ...
}

——拿不到 file_id，沒有任何 tool 接得到下載動作。

dump_chat_to_markdown 在文件流程也只寫成：

**21:49 RoyRogerRickson**：
[document]

對訊息脈絡保留 OK，但媒體實檔對下游（issue tracker、archive、search）沒有意義。

Impact

• idd-issue 自動附件流斷裂：所有以 Telegram 為 source 的 issue（含 kiki830621/collaboration_gukai#5）都得手動把附件搬到 macOS filesystem 才能繼續走 attach_images step
• Archive / audit trail：medical / academic collaboration 透過 Telegram 傳檔的場景（如顧凱鈞傳論文 PDF / SNQ 範例）若要長期保留，目前只能依靠 Telegram desktop client 手動 export
• 跟 che-word-mcp 不對等：che-word-mcp 已能讀取 docx 內嵌圖；che-telegram-all-mcp 連 chat 媒體都不能取，能力 mismatch

Priority

P2 — 不是 blocking（可手動繞過：使用者在 Telegram desktop 右鍵存檔到 /tmp/），但值得排程做掉

Dependent issue

• kiki830621/collaboration_gukai#5 — SNQ 申請，需要附 Roy 傳的 113A272_申請計畫書.pdf + 2 張參考照片

Suggested implementation notes

• TDLib downloadFile(file_id, priority=1, offset=0, limit=0, synchronous=true)
• 從 Message.content.{photo|document|video|...}.file.id 抽 file_id
• 處理 file.local.is_downloading_completed 邏輯（已下載 vs 需下載）
• 錯誤 path：file expired / chat not accessible / message_id invalid
• 測試：與 issue Test: handler glue integration (errorResult conversion + tdlib wiring) #14（handler glue integration）pattern 對齊

Reference

• TDLib API: https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1download_file.html
• 既有 handler pattern: parseGetChatHistoryArgs（issue Refactor dump_chat_to_markdown handler to use parseGetChatHistoryArgs pattern #13 提到的 refactor target）