napcat-java-agent：内置 AI Agent 的 Java QQ Bot 框架

> 分类：开源推荐 | 发布时间：2026-05-16 | 项目地址：[GitHub](https://github.com/cfwasd/napcat-java-agent)

![napcat-java-agent 架构图](https://mrdoc.wangziheng.vip/media/202605/2026-05-16_190020_5395680.9176747520871875.png)

## 一句话介绍

napcat-java-agent 是一个基于 NapCat OneBot11 协议的 **Java QQ Bot 开发框架**，最大亮点是内置了 AI Agent 引擎——你不需要额外对接 LLM，框架本身就支持 ReAct 推理循环、Function Calling、多模态理解和持久化记忆，开箱即用。

## 核心亮点

- **🤖 内置 AI Agent**：ReAct 轻量推理循环（默认最多 5 轮），支持 Function Calling / Tool Use，不需要你自己写 Agent 编排逻辑
- **📝 双编程模型**：注解式（`@OnGroupMessage`、`@Command`）与接口式（`EventHandler`、`CommandHandler`）并存，风格任选
- **🌐 全协议通信**：HTTP Server / Client、WebSocket Server / Client 四种方式，可混合使用
- **🧠 持久化长期记忆**：SQLite 存储用户关键信息，跨会话自动检索注入上下文，支持每日 LLM 自动归纳
- **⏰ 定时任务调度**：Agent 可通过 Tool 创建 Cron 定时任务，支持 AI 生成内容或固定文本推送
- **🖼️ 多模态支持**：`MessageChain.toAgentPrompt()` 保留图片、语音、视频标记；OpenAI Provider 自动提取为 `image_url`
- **🔄 LLM 备用模型**：主模型失败时自动切换备用，支持 OpenAI / Anthropic / Ollama / Custom
- **🔌 Spring Boot Starter**：自动配置，引入依赖就能开发

![双编程模型对比](https://mrdoc.wangziheng.vip/media/202605/2026-05-16_190021_1498750.5937131510407401.png)

## 快速上手

### 环境准备

- JDK 17+
- Maven 3.8+
- 已部署的 [NapCat](https://napneko.github.io/guide/start-install)

### 安装依赖

目前尚未发布到 Maven Central，需本地安装：

```bash
git clone https://github.com/cfwasd/napcat-java-agent.git
cd napcat-java-agent
mvn install -DskipTests
```

### 配置连接

编辑 `napcat-admin/src/main/resources/application.yml`：

```yaml
napcat:
  adapter:
    type: websocket-client
    websocket-client:
      url: ws://127.0.0.1:3001
      token: ""
  bot:
    self-id: 123456789
```

### 写第一个 Bot

```java
@Component
public class HelloBot {

// 注解式：命令路由
    @OnGroupMessage
    @Command("/hello")
    public void hello(GroupMessageEvent event) {
        event.reply("Hello NapCat!");
    }

// 注解式：关键词匹配
    @OnGroupMessage
    public void onGroup(GroupMessageEvent event) {
        if (event.getRawMessage().contains("在吗")) {
            event.reply("在的！");
        }
    }
}
```

运行 `napcat-admin` 的 main 方法即可启动。

### 在自己的项目中引入

```xml
<dependency>
    <groupId>com.napcat</groupId>
    <artifactId>napcat-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>
```

![AI Agent ReAct 循环](https://mrdoc.wangziheng.vip/media/202605/2026-05-16_190021_8876140.14390400133918946.png)

## AI Agent 深度解析

这是这个框架最硬核的部分。传统 QQ Bot 框架只负责收发消息，而 napcat-java-agent 内置了完整的 Agent 能力：

### ReAct 推理循环

框架实现了经典的 **ReAct（Reasoning + Acting）** 模式：

1. **用户消息** → 进入 LLM
2. **LLM 推理** → 决定是直接回复还是调用 Tool
3. **Tool 执行** → 结果作为 Observation 返回 LLM
4. **循环** → 最多 5 轮（可配置），直到 LLM 给出最终回复

这意味着你的 Bot 不只是"关键词 → 固定回复"，而是真正能**思考、调用工具、综合判断**。

### 多 LLM 后端

| Provider | 支持能力 | 适用场景 |
|----------|---------|---------|
| OpenAI | 文本 + 多模态(Vision) + reasoning_content | 生产环境 |
| Anthropic Claude | 文本 | 长上下文场景 |
| Ollama | 本地模型 | 隐私敏感 / 离线 |
| Custom | 自定义 OpenAI 兼容端点 | 私有部署 |

### 持久化记忆

Agent 的记忆不是临时的——它使用 SQLite 存储：
- **短期记忆**：当前会话上下文
- **长期记忆**：用户关键信息持久化存储，跨会话自动检索注入
- **每日归纳**：LLM 自动总结关键信息，避免上下文爆炸

### 定时任务

Agent 可以通过 Tool 动态创建 Cron 定时任务：
- AI 生成内容推送（如每日早报）
- 固定文本定时提醒
- 持久化到 SQLite，重启不丢失

## 模块架构

```
napcat-java/
├── napcat-parent            # BOM，统一版本
├── napcat-core              # OneBot11 协议、通信适配器、事件路由
├── napcat-agent             # LLM Agent 引擎、Tool 注册、ReAct 循环
├── napcat-llm-providers     # LLM 厂商实现
│   ├── napcat-llm-openai    # OpenAI 兼容（含多模态/Vision）
│   ├── napcat-llm-anthropic # Claude
│   └── napcat-llm-ollama    # Ollama 本地模型
├── napcat-spring-boot-starter # Spring Boot 自动配置
└── napcat-admin             # 示例机器人应用
```

核心模块职责：
- **napcat-core**：处理 OneBot11 协议的四种通信方式，事件路由和消息链解析
- **napcat-agent**：Agent 引擎核心，ReAct 循环、Tool 注册与调度、会话管理
- **napcat-llm-providers**：统一的 LLM 调用抽象，支持多后端无缝切换

## 适用场景

| 场景 | 推荐指数 | 说明 |
|------|---------|------|
| QQ 群智能助手 | ⭐⭐⭐⭐⭐ | 最核心场景，AI Agent + 群消息处理 |
| 知识问答 Bot | ⭐⭐⭐⭐⭐ | 持久化记忆 + 多轮推理 |
| 群管理机器人 | ⭐⭐⭐⭐ | 注解式路由 + 关键词触发 |
| 定时播报 Bot | ⭐⭐⭐⭐ | 内置 Cron + AI 生成内容 |
| 多模态识别 | ⭐⭐⭐ | 图片理解（依赖 Vision 模型） |
| 企业内部 IM 集成 | ⭐⭐⭐ | 需自行适配通信层 |

## 与同类项目对比

| 特性 | napcat-java-agent | NoneBot2 (Python) | Koishi (Node.js) |
|------|-------------------|-------------------|------------------|
| 语言 | Java | Python | TypeScript |
| 内置 AI Agent | ✅ ReAct + Tool | ❌ 需自建 | ❌ 需插件 |
| 持久化记忆 | ✅ SQLite + 归纳 | ❌ | 插件支持 |
| 定时任务 | ✅ Agent 可动态创建 | 插件 | 插件 |
| 多 LLM 后端 | ✅ 3+ | 需自建 | 插件 |
| 编程模型 | 注解 + 接口 | 装饰器 | 插件钩子 |
| Spring Boot | ✅ Starter | - | - |
| 多模态 | ✅ Vision | 需自建 | 插件 |

**核心差异**：napcat-java-agent 是目前唯一把 AI Agent 作为一等公民的 Java QQ Bot 框架。其他框架需要你自己拼装 LLM 调用、记忆管理、工具编排，而这里开箱即用。

## 相关链接

- 📦 [GitHub 仓库](https://github.com/cfwasd/napcat-java-agent)
- 📖 [在线文档站](https://cfwasd.github.io/napcat-java-agent/)
- 🔗 [NapCatQQ 官方文档](https://napneko.github.io/guide/start-install)
- 📡 [NapCat API 文档](https://napcat.apifox.cn/llms.txt)
- 📄 License: MIT

---

*本文由自动化工具辅助生成，项目信息来源于 GitHub README 和官方文档。*