fix(telegram): handle caption for document and video messages (#7000)

[Yaohua-Leo]

Summary

Fixes #7000

Changes

• Add caption handling to document branch
• Add caption handling to video branch
• Handle caption_entities for mention support

Summary by Sourcery

Handle captions and mentions for Telegram document and video messages.

Bug Fixes:

• Parse and attach captions for incoming Telegram document messages.
• Parse and attach captions for incoming Telegram video messages.
• Convert caption mention entities into internal mention components when present in captions.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• The caption and caption_entities handling logic for document and video messages is duplicated; consider extracting this into a small helper function to keep the branches consistent and easier to maintain.
• If there is already shared logic elsewhere for handling entities (e.g., mentions) in regular message text, it may be cleaner to reuse that rather than reimplementing the mention extraction for captions here.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The caption and caption_entities handling logic for document and video messages is duplicated; consider extracting this into a small helper function to keep the branches consistent and easier to maintain.
- If there is already shared logic elsewhere for handling entities (e.g., mentions) in regular message text, it may be cleaner to reuse that rather than reimplementing the mention extraction for captions here.

## Individual Comments

### Comment 1
<location path="astrbot/core/platform/sources/telegram/tg_adapter.py" line_range="489" />
<code_context>
                 message.message.append(
                     Comp.File(file=file_path, name=file_name, url=file_path)
                 )
+            if update.message.caption:
+                message.message_str = update.message.caption
+                message.message.append(Comp.Plain(message.message_str))
</code_context>
<issue_to_address>
**issue (complexity):** Consider extracting the repeated caption and mention handling into a shared helper used by both the document and video branches to avoid duplication.

You can remove the duplicated caption logic in the `document` and `video` branches by extracting it into a small helper. That keeps media-specific handling localized and makes future changes to caption parsing one‑shot.

For example:

```python
def _append_caption_components(message: Message, tg_message: telegram.Message) -> None:
    if tg_message.caption:
        message.message_str = tg_message.caption
        message.message.append(Comp.Plain(message.message_str))

    if tg_message.caption_entities:
        for entity in tg_message.caption_entities:
            if entity.type == "mention":
                name = message.message_str[
                    entity.offset + 1 : entity.offset + entity.length
                ]
                message.message.append(Comp.At(qq=name, name=name))
```

Then use it in both branches:

```python
if update.message.document:
    # existing document/file handling...
    if file_path is not None:
        message.message.append(Comp.File(file=file_path, name=file_name, url=file_path))
    _append_caption_components(message, update.message)

elif update.message.video:
    # existing video handling...
    if file_path is not None:
        message.message.append(Comp.Video(file=file_path, path=file.file_path))
    _append_caption_components(message, update.message)
```

This keeps behavior identical but removes duplicated control flow and ensures any future change to caption/mention handling is implemented in a single place.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

issue (complexity): Consider extracting the repeated caption and mention handling into a shared helper used by both the document and video branches to avoid duplication.

You can remove the duplicated caption logic in the document and video branches by extracting it into a small helper. That keeps media-specific handling localized and makes future changes to caption parsing one‑shot.

For example:

def _append_caption_components(message: Message, tg_message: telegram.Message) -> None:
    if tg_message.caption:
        message.message_str = tg_message.caption
        message.message.append(Comp.Plain(message.message_str))

    if tg_message.caption_entities:
        for entity in tg_message.caption_entities:
            if entity.type == "mention":
                name = message.message_str[
                    entity.offset + 1 : entity.offset + entity.length
                ]
                message.message.append(Comp.At(qq=name, name=name))

Then use it in both branches:

if update.message.document:
    # existing document/file handling...
    if file_path is not None:
        message.message.append(Comp.File(file=file_path, name=file_name, url=file_path))
    _append_caption_components(message, update.message)

elif update.message.video:
    # existing video handling...
    if file_path is not None:
        message.message.append(Comp.Video(file=file_path, path=file.file_path))
    _append_caption_components(message, update.message)

This keeps behavior identical but removes duplicated control flow and ensures any future change to caption/mention handling is implemented in a single place.

[gemini-code-assist]

Code Review

This pull request updates the Telegram adapter in tg_adapter.py to support captions and mention entities for messages containing files or videos. The changes ensure that caption text is captured as plain text and mentions are correctly parsed into 'At' components. I have no feedback to provide.