Qq Bot

基于 qq-botpy + MCP 的 QQ 机器人桥接服务。通过 MCP 工具协议暴露 QQ 消息收发能力，让外部项目无需依赖 QQ SDK 即可接入 QQ 消息流。

架构说明

• qq_bot_mcp/config.py：配置加载（QQ 凭据）
• qq_bot_mcp/models.py：数据模型（事件、回复结果）
• qq_bot_mcp/adapters/qq_client.py：QQ 平台适配层（接收 AT/私信/C2C/群聊消息）
• qq_bot_mcp/services/message_hub.py：协程消息总线（待处理事件队列、历史记录、回复分发）
• qq_bot_mcp/mcp/server.py：MCP 工具层（暴露给 MCP 客户端调用）
• qq_bot_mcp/runtime.py：运行时装配（QQ Bot 生命周期管理）
• qq_bot_mcp/cli.py：CLI 入口

默认行为：只收消息不自动回复，由 MCP 客户端决定如何处理并回包。

依赖安装

uv sync

或：

pip install -e .

环境变量

在根目录创建 .env：

qq_bot_id=你的BotAppID
qq_bot_appsecret=你的BotSecret

运行方式

一体化（QQ Bot + MCP Server）

uv run qq-bot-mcp --mode all

仅 QQ Bot Runtime

uv run qq-bot-mcp --mode bot

仅 MCP Server（不启动 QQ Bot）

uv run qq-bot-mcp --mode mcp

MCP 工具清单

工具名	说明
qqbot_status	运行状态、待处理数量、累计消息数
qqbot_list_pending(limit)	拉取待处理事件
qqbot_wait_event(timeout_seconds)	阻塞等待一条新事件
qqbot_reply_event(event_id, ...)	按事件回复到 QQ（支持文本/图片/Markdown/Ark/Embed/Media）
qqbot_discard_event(event_id)	丢弃事件，不做回复
qqbot_list_history(limit)	查看最近历史消息
qqbot_capabilities	返回场景能力说明

MCP 客户端接入流程

1. 以 stdio 方式启动本服务作为 MCP server
2. 调用 qqbot_wait_event 或 qqbot_list_pending 获取消息
3. 根据业务逻辑生成回复
4. 调用 qqbot_reply_event(event_id, content=...) 回消息到 QQ

客户端实现由使用方自行完成。

测试

uv run pytest test/ -v

AI 客户端 Demo（DeepSeek）

已提供最小客户端示例：test/ai_chat_client_demo.py。

先在 .env 增加：

LLM_API_KEY=你的DeepSeekKey
LLM_MODEL=deepseek-chat
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_TIMEOUT=30

运行：

uv run python test/ai_chat_client_demo.py