A QQ AI Bot That Remembers, Listens, and Edits Feishu Docs: Full Deployment Walkthrough
Wiring chat, voice, and document tools into one agent means inheriting every layer's failure modes; this post names 17 of them with fixes, saving developers days of silent debugging.
On a single Ubuntu 24.04 server, the author stitches together four layers: NapCat handles the QQ protocol over OneBot v11, AstrBot orchestrates conversation and plugins, DeepSeek supplies the model and web search, and a custom DSH agent sub-process executes file and Feishu operations. Whisper locally transcribes voice, Edge TTS synthesizes a 'cute girl' reply, and a home-grown plugin gates who can wake the bot without @-mention. The result is a bot that remembers 700 group messages, recognizes voice even at -36 dB, and runs approval-gated agent tasks that can edit Feishu cloud docs via lark-cli.
The write-up is a troubleshooting log as much as a tutorial. The author documents 17 specific failures, from Docker Hub timeouts in China to a DeepSeek 422 caused by undeclared `modalities`, Whisper drifting to Swedish on low-volume audio, and the STT pipeline replacing voice segments with plain text so TTS never triggers. Each fix is concrete, with code snippets and configuration JSON. The final architecture binds all services to an internal IP, uses a dedicated QQ account to limit ban damage, and separates LLM keys for chat and agent work.
The hardest engineering problem in this build is not model choice but making the voice pipeline robust to the extreme variation in QQ audio (loudness, language drift); the same principle applies to any production voice agent.
The author treats the QQ account as disposable because Tencent's ToS risk is real, and this shapes operational decisions like never restarting NapCat to avoid a re-login.
Using a sub-process agent with a whitelist and approval flow is a conservative, controllable way to give an LLM real side-effecting tools; it's a pattern worth copying for non-critical automation.