feat(channels): add local media file sending support for QQ channel

[howyoungchen]

Description

Add local media file sending support for QQ channel. Previously, the QQ channel could only send remote HTTP image URLs; video, audio, and file types were unsupported, and local file paths were not accepted at all.

This PR extends the QQ rich media pipeline to:

• Accept both local file paths (file:// or absolute path) and remote HTTP URLs for all media types
• Support image (png/jpg), video (mp4), audio (silk/wav/mp3/flac), and file (any format) sending in C2C and group chat
• Auto-infer QQ file_type (1–4) from file extension; unsupported image formats (svg, gif, etc.) fall back to file type
• Upload local files via base64 with original filename preserved
• Fix base.py audio content part to include the data path in the [Audio: ...] tag so downstream channels can pick it up

Related Issue: Fixes #981

Security Considerations: Local file reads are limited to paths explicitly provided by the agent reply content. No path traversal beyond what the agent constructs.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• Refactoring

Component(s) Affected

• Core / Backend (app, agents, config, providers, utils, local_models)
• Console (frontend web UI)
• Channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.)
• Skills
• CLI
• Documentation (website)
• Tests
• CI/CD
• Scripts / Deploy

Checklist

• I ran pre-commit run --all-files locally and it passes
• If pre-commit auto-fixed files, I committed those changes and reran checks
• I ran tests locally (pytest or as relevant) and they pass
• Documentation updated (if needed)
• Ready for review

Testing

1. Configure a QQ bot with C2C / group chat permissions.
2. Ask the bot a question that triggers an agent reply containing a local image/audio/video/file path (e.g. a skill that generates or reads a local file).
3. Verify the file is received in the QQ chat.

Test matrix:

Scenario	Expected
Remote HTTP image URL	Sent as QQ image (type 1)
Local file:///path/to/img.png	Read, base64-uploaded, sent as image
Local /path/to/audio.mp3	Sent as audio (type 3)
Local /path/to/video.mp4	Sent as video (type 2)
Local /path/to/doc.pdf	Sent as file (type 4) with filename
SVG / GIF image URL	Falls back to file type (type 4)

Local Verification Evidence

pre-commit run --all-files
# All checks passed.

pytest
# All tests passed.

Additional Notes

Rich media sending is only available in C2C and group chat; guild messages are not supported by the QQ Rich Media API. Receiving video / audio / file attachments from users is not yet verified (🚧).

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the QQ channel's ability to handle rich media by allowing agents to send local files and a wider array of media types. Previously limited to remote image URLs, the channel can now process and transmit local images, videos, audio, and general files, improving the expressiveness and utility of agent communications within QQ C2C and group chats.

Highlights

• Local Media File Sending: Enabled the QQ channel to send local media files (images, videos, audio, and general files) in addition to remote HTTP URLs, significantly expanding its rich media capabilities.
• Expanded Media Type Support: Introduced support for various media types including PNG/JPG images, MP4 videos, SILK/WAV/MP3/FLAC audio, and any file format, with automatic inference of QQ's file_type based on file extensions.
• Base64 Upload for Local Files: Implemented base64 encoding for local file uploads, ensuring original filenames are preserved when sending to QQ.
• Audio Content Tag Fix: Corrected the base.py channel utility to include the data path within the [Audio: ...] tag, allowing downstream channels to properly process audio content.
• Documentation Updates: Updated both English and Chinese documentation to reflect the new rich media sending capabilities and supported formats for the QQ channel.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• src/copaw/app/channels/base.py
  • Updated audio content tag to include the data path.
• src/copaw/app/channels/qq/channel.py
  • Imported the base64 module for encoding local files.
  • Added new regex patterns for video, audio, and file tags, and generalized the image tag pattern.
  • Introduced utility functions _strip_file_scheme and _infer_media_type for path processing and media type detection.
  • Modified _upload_media_async to support both remote HTTP URLs and local file paths, handling base64 encoding for the latter.
  • Enhanced _send_media_message_async to accept an optional filename for display to recipients.
  • Refactored the _dispatch method to extract and process all supported media tags (image, video, audio, file).
  • Created _send_single_media helper method to streamline the media upload and sending process for different media types.
• website/public/docs/channels.en.md
  • Added a new section detailing rich media support for the QQ channel.
  • Updated the channel capabilities table to reflect new sending support for image, video, audio, and file.
  • Expanded the QQ channel notes to describe the new rich media sending features and limitations.
• website/public/docs/channels.zh.md
  • Added a new section detailing rich media support for the QQ channel in Chinese.
  • Updated the channel capabilities table to reflect new sending support for image, video, audio, and file in Chinese.
  • Expanded the QQ channel notes to describe the new rich media sending features and limitations in Chinese.

Activity

• The author, howyoungchen, created this pull request to introduce new features and fix an existing issue.
• The pull request includes changes to core channel logic and documentation, indicating a comprehensive update.
• Pre-commit checks and local tests were run and passed, as verified by the author.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Generative AI Prohibited Use Policy, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request is a significant feature enhancement, adding local media file sending support for the QQ channel. The implementation correctly handles various media types, infers them from file extensions, and supports both remote URLs and local file paths, with corresponding documentation updates. My review includes a high-severity security recommendation to prevent potential arbitrary file reads by sandboxing local file access, and a medium-severity suggestion to refactor the media type inference logic for better maintainability. Overall, this is a well-executed pull request.