Topics

#low-memory #onebot11 #qq-bot #rag #wxbot

Language breakdown

Rust 96.2%

Shell 3.3%

Python 0.2%

HTML 0.2%

Makefile 0.1%

Batchfile 0.0%

▸ Files click to expand

README

小女仆机器人

一个会聊天、会记事、会调用工具，也会主动推送的轻量、自托管、多入口 AI Agent 机器人。

_{Rust 单进程 · 约 25 MiB 常驻内存 · 默认空闲时 3 个线程 · Provider 无关 Agent Loop · 多模态输入 · 主动推送 · 模型自动降级}

💡 仓库早期以 QQ 机器人为主，因此仍保留 qq-maid-bot 名称。当前项目正在从 QQ 官方机器人演进为多入口平台型小女仆机器人；OneBot 11 仍处于架构预留和规划阶段，尚未接入。

小女仆机器人使用 Rust 构建，当前主入口是 QQ 官方机器人接口，并提供可选微信服务号文本入口。它不是简单地把消息转发给大模型，而是把长期会话、受控记忆、Todo、RSS、知识检索、联网查询、QQ 图片理解、引用上下文、Agent Loop、工具调用和主动推送装进同一个可维护的 Agent 底座里。

当前稳定版本请查看 Releases 页面，完整版本变更见 CHANGELOG.md。默认配置当前以 OpenAI GPT-5.6 Luna 为主路线，同时支持 Gemini、MiMo、DeepSeek 和 OpenAI-compatible Provider 路由与降级。

核心能力

多轮聊天与上下文：会话可新建、恢复、重命名和压缩；支持图片理解和引用上下文追问。
Todo 与提醒：支持新增、修改、完成、恢复和删除；单次提醒、重复提醒和每日摘要。自然语言中的“取消”按删除处理，已完成的待办可恢复为未完成。
联网与查询：天气、火车时刻、RSS/Atom 订阅与主动推送，Web Search，翻译，AI 雷达摘要。
受控长期记忆：确认式流程，只有用户明确提交并确认后才写入；支持查看和修改。
本地知识库：自动索引本地 Markdown，按需注入相关片段到聊天上下文。
Provider 无关 Tool Agent Loop：私聊中的明确工具意图按白名单调用工具，Core 根据真实工具结果生成回复，不依赖模型文案判断操作是否成功。
多模型路线与自动降级：独立的 LLM 层支持 Provider 路由、候选链、流式协议和自动降级；主模型不可用时按配置尝试后备。
主动推送：RSS 更新和 Todo 提醒通过统一 Notification Outbox 后台投递，机器人不只是被动回答。

快速开始

路径一：一键脚本（Linux 推荐）

适合 Linux 服务器。脚本通过 curl 获取，不需要先 git clone 仓库。

curl -fsSL https://github.com/kuliantnt/qq-maid-bot/raw/refs/heads/master/qbot.sh -o /tmp/qbot.sh bash /tmp/qbot.sh deploy

qbot install qbot config bot qbot config ai qbot start qbot status

常用管理命令：

qbot log       # 查看并跟随日志
qbot health    # 健康检查
qbot update    # 更新到最新版本
qbot restart   # 重启服务

路径二：Release 包（Linux，无需安装 Rust）

从 Releases 下载与系统匹配的最新包：

tar -xzf qq-maid-bot-*.tar.gz
cd qq-maid-bot-*
cp config/.env.example config/.env
vim config/.env
./botctl.sh start
./botctl.sh status

最少需要填写：QQBOTAPPID、QQBOTAPPSECRET，以及至少一个 Provider 的 API Key。

路径三：源码构建（需要 Rust 工具链）

git clone https://github.com/kuliantnt/qq-maid-bot.git
cd qq-maid-bot
cp runtime/config/.env.example runtime/config/.env
vim runtime/config/.env
bash scripts/deploy-local.sh
runtime/botctl.sh status

遇到问题？

| 问题 | 答案 | | --- | --- | | 启动后立即退出 | 查看日志。通常是 config/.env 缺少必填项或 API Key 无效。 | | QQ 收不到消息 | 确认 QQ 开放平台已启用机器人事件权限；检查 Gateway WebSocket 连接状态。 | | 模型调用报错 | 确认 API Key 有效，模型前缀匹配。用 GLM/Qwen/Ollama 等兼容网关时需设 OPENAIAPIMODE=chat_only。 | | 群聊不回复 | 默认 mention 模式只响应 @ 和回复机器人。 | | 怎么诊断 | qbot health 确认服务存活；诊断网络：./diagnose-network.sh。 | | 升级后启动失败 | 对比新版 config/.env.example 是否新增必填项。 |

详细配置项和开机自启动见 runtime/README.md；开发调试见 docs/DEVELOPMENT.md。

使用示例

你：帮我新增待办：明天下午三点检查服务器日志机器人：已新增待办：检查服务器日志时间：明天 15:00 你：明天上午九点半提醒我检查证书过期时间机器人：已新增待办：检查证书过期时间提醒：明天 09:30 你：查看今天待办机器人：📅 今天待办 · 共 2 项 1. 检查服务器日志 2. 更新周报你：完成第一条机器人：已完成待办：检查服务器日志你：查看全部进行中待办机器人：🚧 进行中 · 共 12 项 1. ... 还有 7 项待办，可说"查看完整结果"。你：杭州明天要带伞吗机器人：小女仆正在查天气… 明天有雨，建议带伞。你：（发送一张服务器报错截图）这是什么问题机器人：这张图里主要错误是 ... 你：（引用刚才那张截图）那应该先改哪里机器人：建议先从 ... 你：/rss add https://example.com/feed.xml Rust News 机器人：已添加订阅：Rust News 你：/rader 机器人：🛰️ AI 雷达速览 Codex Radar：... Claude Code Radar：...

你：/memory 我习惯使用 Asia/Shanghai 时区机器人：已生成长期记忆草稿，请确认后保存。

配置说明

配置分两层：.env 管部署和密钥，agent.toml 管 Agent 行为策略。

| 文件 | 内容 | 不包含 | | --- | --- | --- | | runtime/config/.env | QQ AppID/AppSecret、Provider API Key、数据库路径、日志参数 | 私聊/群聊 profile、Tool Loop 轮数、工具白名单 | | runtime/config/agent.toml | 私聊/群聊策略、profile、Tool Loop 预算、工具白名单、Provider 元数据 | API Key、私有 Base URL、真实 prompt、用户数据 |

默认 agent.toml 的私聊、群聊和辅助任务都以 OpenAI GPT-5.6 Luna 为第一候选，并保留 Gemini、MiMo 和 DeepSeek 降级候选；搜索路线默认使用 Luna。具体候选列表、profile 和参数以 runtime/config/agent.toml 为准。

换 API Key、Base URL、默认模型或部署路径 → 改 .env
调整私聊/群聊用哪个 profile、是否允许 Tool Calling、允许哪些工具、最多几轮 → 改 agent.toml
完整配置项见 runtime/config/.env.example 和 runtime/README.md

平台支持状态

| 平台 | 状态 | 说明 | | --- | --- | --- | | QQ 官方机器人 | ✅ 主要入口 | C2C 和群聊，支持图片理解、流式回复、typing 状态 | | 微信服务号 | ⚡ 可选 text-only | 默认关闭；支持同步文本回复和慢请求客服补发，需反向代理 | | OneBot 11 | 📋 规划中 | 已保留平台模型和边界预留，尚未实现可用接入 |

架构概览

flowchart LR
    platform["QQ / 微信 / OneBot"] --> gateway["Gateway<br/>接入 / 过滤 / 去重 / 媒体取回"]
    gateway --> request["CoreRequest<br/>统一消息请求"]
agent["Agent Loop<br/>理解意图 / 调模型 / 调工具 / 汇总结果"]
request --> agent     agent --> llm["LLM Router<br/>多模型 / 降级 / 多模态"]     agent --> tools["Tool Registry<br/>待办 / RSS / 查询 / 记忆"]
tools --> db[(SQLite)]     agent --> db
agent --> outbound["OutboundMessage"]     outbound --> sender["Sender<br/>回复 / 主动推送"]     sender --> platform

项目通过根目录 Cargo Workspace 统一管理：

| Crate | 职责 | | --- | --- | | qq-maid-gateway-rs/ | QQ 事件接收、消息聚合、typing、流式与普通回复、图片下载；可选微信服务号文本回调 | | qq-maid-core/ | CoreService、会话、记忆、知识库、Todo、RSS、业务 Tool、可信结果编排 | | qq-maid-llm/ | 模型协议、Provider 路由、fallback、SSE、Agent Loop、Tool Loop 和健康观测 | | qq-maid-common/ | 时间、日期、时区等共享基础工具 |

依赖方向：gateway → core → llm → common。平台 ID 与业务隔离键的详细设计见 docs/design/scope-identity-boundary.md。

同一个架构，换个说法：

用户说话 → 女仆长接单 → 各部门互相甩锅 → 工具拿真实结果说话 → SQLite 留档 → 大模型继续背锅

安全边界

只有注册到 Tool Registry 的白名单工具可以被调用；群聊默认不进入 Tool Loop
Todo 高风险操作需要二次确认；恢复只能在已完成候选边界内进行
工具成功与否以真实执行结果为准，不以模型自述为准
QQ 图片会按体积上限下载到本地媒体缓存后交给模型；文件附件不解析正文
微信服务号入口默认关闭，日志不打印 Token、AppSecret、OpenID 或消息正文

开发与文档导航

二次开发前请先阅读 CONTRIBUTING.md 和 docs/DEVELOPMENT.md。

| 文档 | 说明 | | --- | --- | | runtime/README.md | 部署运行、配置项、微信服务号、开机自启动 | | runtime/config/.env.example | 环境变量模板 | | docs/DEVELOPMENT.md | 架构边界、开发命令、Tool Loop 边界 | | docs/development/custom-tools.md | 自定义 Tool 二开接入指南 | | docs/design/scope-identity-boundary.md | 平台 ID 与业务隔离键设计 | | qq-maid-core/README.md | Core 模块文档 | | qq-maid-llm/README.md | LLM 基础设施文档 | | qq-maid-gateway-rs/README.md | Gateway 文档 | | CHANGELOG.md | 完整版本变更记录 | | Makefile | 构建与测试命令 |