Qq LLM Bot

QQ LLM机器人（NapCat/OneBot）

中文说明

一个基于NapCat（OneBot）的实用QQ机器人，由OpenAI兼容的LLM提供支持。包括MCP工具、提醒和日常使用统计数据（愿景通过MCP提供）。

特性

• NapCatQQ（OneBot）接收/发送
• 分组路由模式：提及/关键字/全部
• 提及/关键字后的小组跟进窗口（继续回复几圈，不再提及）
• 提醒：在私人或群聊中创建/列出/取消提醒
• 可选MCP工具（外部工具服务器）
• 每日每个用户的使用统计数据（令牌/调用/工具调用）保存到CSV

项目布局

• src/ TypeScript源代码
• dist/ 构建输出(npm run build)
• data/ 运行时数据（笔记、提醒、统计数据）。被git忽略了。
• prompts/ 系统提示文件
• knowledge/ 知识示例/RAG资源
• .env 本地配置（被git忽略）和 .env.example 模板

需求

• Node.js 18+
• NapCatQQ在OneBot WebSocket事件+启用HTTP API的情况下运行

快速开始

npm install
cp .env.example .env
npm run doctor
npm run dev

配置

复制 .env.example 到 .env 只改变自己的价值观。

NapCat/QQ

• NAPCAT_HTTP_URL NapCat HTTP API基础URL
• NAPCAT_WS_URL NapCat WebSocket事件URL
• NAPCAT_HTTP_TOKEN / NAPCAT_WS_TOKEN 可选令牌

- 如果不在中设置令牌 .env，机器人可以从本地NapCat OneBot配置（如果可用）自动加载它们。

• BOT_QQ_ID 可选（自动检测自 self_id 如果未设置）
• BOT_NAME 机器人昵称（默认值： 小助手)

LLM

• LLM_BASE_URL OpenAI兼容网关基础URL
• LLM_API_KEY API密钥
• LLM_MODEL 型号名称
• LLM_TEMPERATURE 采样温度（默认值： 0.3)

脚本

npm run dev     # run bot in dev mode
npm run doctor  # check NapCat HTTP/WS connectivity
npm run build   # compile to dist/
npm run start   # run dist/ output
npm run test    # run tests

组回复模式

• GROUP_REPLY_MODE:

- mention （默认）：提及时回复；如果已配置，还可以回复昵称/关键字 - keyword：当出现任何关键字时回复 - all：回复所有群消息

• GROUP_KEYWORDS 关键字数组（JSON）或逗号分隔列表
• GROUP_FOLLOWUP_TURNS 触发后要处理的后续消息数（默认值： 4)
• GROUP_FOLLOWUP_TTL_MS 后续窗口TTL（毫秒）（默认值： 120000)

使用统计数据（每日CSV）

• 机器人记录每个用户的每日使用统计数据：

- 如果网关返回，LLM调用和令牌（提示/完成/总计） usage - 工具调用计数（包括MCP和内置工具）

• 文件写入到：

- STATS_DIR/YYYY-MM-DD.csv （推荐）或 DATA_DIR/stats/YYYY-MM-DD.csv 默认情况下

• 聊天中的查询：

- token统计 / 今日统计 / 我的统计 / 今日用量 / 我的用量

系统提示

选择一个：

• SYSTEM_PROMPT_FILE=prompts/system.txt （推荐）
• SYSTEM_PROMPT=...

MCP（可选外部工具）

此项目使用 mcp.servers.json 启动/连接MCP服务器。一台服务器可以暴露多个工具，机器人通过以下方式发现它们 listTools.

例子：

{
  "servers": [
    {
      "name": "tools",
      "command": "node",
      "args": ["dist/mcp/servers/tools.js"],
      "enabled": true,
      "tools": {
        "weather_query": true,
        "web_search": true
      }
    }
  ]
}

• enabled：启用/禁用整个服务器
• tools：可选。两种模式：

- 允许列表：如果有值 true，仅标记工具 true 已启用 - Denylist：如果没有 true，默认情况下启用所有工具；集 false 禁用特定工具

安全说明

• 永不承诺 .env 或任何真正的API密钥。此回购忽略 .env 和 .env.* 默认情况下，并保持 .env.example.
• 如果你不小心将一个密钥推送到GitHub，请立即旋转它，并在需要时重写历史记录。
• 本地NapCat捆绑包(NapCat.Shell.Windows.Node/)以及运行时数据(data/)被忽略以避免泄露令牌和聊天日志。

故障排除

• HTTP显示 403 token verify failed：set NAPCAT_HTTP_TOKEN 正确地。
• Bot收到消息但不回复：检查路由模式(GROUP_REPLY_MODE)以及该消息是否触发了提及/关键字逻辑。

学分

• NapCatQQ（OneBot/NTQQ协议端）：https://github.com/NapNeko/NapCatQQ