fix(qqbot): surface cached file attachments to agents

[LeonSGP43]

What does this PR do?

Fixes QQ Bot document attachments so Hermes keeps the original filename and passes the cached local file path into the agent event instead of dropping the file after download.

Related Issue

Fixes #26399

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• Update gateway/platforms/qqbot/adapter.py so non-image/non-voice attachments append their cached local path into the normal media_urls / media_types pipeline instead of only emitting a text marker.
• Pass QQ attachment metadata filename into _download_and_cache() and prefer it over the CDN URL basename when caching documents.
• Add regression tests in tests/gateway/test_qqbot.py covering both cached document surfacing and original-filename preservation.

How to Test

1. Run python3 -m pytest -o addopts='' tests/gateway/test_qqbot.py.
2. Verify document attachments now keep the original filename in cache and surface a local path through the QQ adapter attachment pipeline.
3. Optionally reproduce with a QQ document attachment and confirm the agent can see a local cached file path instead of only [Attachment: ...] text.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS 15.x

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

• python3 -m pytest -o addopts='' tests/gateway/test_qqbot.py → 146 passed, 1 warning in 4.19s
• python3 -m py_compile gateway/platforms/qqbot/adapter.py tests/gateway/test_qqbot.py
• git diff --check
• Attempted repo-wide gate via uv run --extra dev --extra acp python -m pytest tests/ -q --ignore=tests/integration --ignore=tests/e2e --tb=short -x, but the environment is missing optional test dependencies outside this change (fastapi on branch, aiohttp on clean origin/main).

[teknium1]

Thanks for the focused QQ attachment fix. The reported behavior is already implemented on current main; this is an automated hermes-sweeper review.

• gateway/platforms/qqbot/adapter.py:1734-1742 downloads non-image attachments and includes the cached local path in agent-visible [file: ... (path)] / [video: ... (path)] attachment text.
• gateway/platforms/qqbot/adapter.py:1258-1298 appends that attachment text to the inbound message before dispatching the MessageEvent, so the agent receives the cached path.
• gateway/platforms/qqbot/adapter.py:1754-1797 passes and prefers the original QQ attachment filename when caching documents.
• Equivalent regression coverage is present at tests/gateway/test_qqbot.py:1937-1957.
• These fixes landed in bbd77d165cd603759f183e620c1e626580e31135 and 0e7448d63abd6864fa7ed4c6b20030890abf813e, both shipped in v2026.5.28. The linked issue QQ Bot: File attachments cached but path not passed to agent, original filename lost #26399 was also closed as implemented on main.