[Feature]Astrbot QQ adapter 未读取 asr_refer_text 字段导致无法解析语音消息.md
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 68/100
Research direction
Start by locating the QQ adapter's message parsing entry point and run the issue's grep for asr_refer_text to confirm the field is absent. Compare the relevant logic with the referenced Hermes QQ adapter, then verify that QQ voice messages use the pre-transcribed text when present and retain the existing fallback when it is absent.
Written by the indexing model from the issue text.
Description
Description / 描述
Issue：Astrbot QQ Adapter 未读取 asr_refer_text 字段
创建日期：2026-05-09
状态：待处理
优先级：中
问题描述
Astrbot 的 QQ 机器人收到语音消息时，无法自动解析语音内容（回复"听不懂"）。
对比 Hermes 的 QQ 机器人，相同条件下可以"听懂"用户发送的语音消息。
原因分析
当用户发送 QQ 语音消息时，腾讯已经自动完成了语音转文字（STT），并将结果存储在 asr_refer_text 字段中。
- Hermes：读取了
asr_refer_text字段，所以能获取文字内容 - Astrbot：未读取此字段，只处理原始语音文件，导致无法理解语音内容
Hermes 的实现方式
参考 Hermes QQ adapter 的代码逻辑：
# Hermes 读 asr_refer_text 的逻辑（你发语音时腾讯已转好）
if asr_refer_text:
logger.debug("STT: using QQ asr_refer_text: %r", asr_refer_text)
return asr_refer_text
这段代码简单直接：检查消息是否包含预转文字，有则直接使用，无需额外配置 ASR 模型。
建议解决方案
在 Astrbot 的 QQ adapter 中添加 asr_refer_text 字段的读取逻辑：
# 如果消息有预转文字，直接用
if asr_refer_text:
logger.debug("STT: using QQ asr_refer_text: %r", asr_refer_text)
return asr_refer_text
微信我没有测试，可能也有相似的预转文字机制。
优点
- 🚀 零成本：腾讯已自动完成 STT，无需额外配置 ASR 模型
- ⚡ 简单高效：只需几行代码即可实现
- ✅ 兼容性好：不影响现有其他消息类型处理逻辑
注意事项
- 需要确认
asr_refer_text字段在 QQ 消息数据结构中的实际字段名 - 建议添加日志记录，便于排查问题
- 考虑 fallback 机制：如果没有
asr_refer_text，再尝试其他方式
相关检索
grep -r "asr_refer_text" /AstrBot
# 返回：No matches found
确认 Astrbot 代码库中完全没有此字段的处理逻辑。
参考
- Hermes QQ adapter 实现
- QQ 消息数据结构文档
Use Case / 使用场景
No response
Willing to Submit PR? / 是否愿意提交PR？
- Yes, I am willing to submit a PR. / 是的，我愿意提交 PR。
Code of Conduct
- I have read and agree to abide by the project's Code of Conduct. /
- Dominant language
- Python
- Stars
- 40.7k
- Forks
- 2.9k
- Avg merge
- 1d 5h
- Merged PRs (30d)
- 112
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from AstrBotDevs/AstrBot
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
AstrBotDevs/AstrBot#10033 · 3 comments ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 86/100
AstrBotDevs/AstrBot#9999 ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
AstrBotDevs/AstrBot#9945 · 2 comments ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
AstrBotDevs/AstrBot#9938 · 1 comment ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
AstrBotDevs/AstrBot#9929 · 2 comments ·
All issues in AstrBotDevs/AstrBot
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100