# xp_agent_java

**Repository Path**: arain1026/xp_agent_java

## Basic Information

- **Project Name**: xp_agent_java
- **Description**: XP Agent 是一个基于 Java 25、Spring Boot 和 LangChain4j 构建的开源 AI Agent。项目提供统一 Agent Runtime，并支持 TUI、JavaFX Desktop、Web、IM、定时任务和子 Agent 等运行入口。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-22
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# XP Agent

XP Agent 是一个基于 Java 25、Spring Boot 和 LangChain4j 构建的开源 AI Agent。项目提供统一 Agent Runtime，并支持 TUI、JavaFX Desktop、Web、IM、定时任务和子 Agent 等运行入口。

## 主要能力

- ReAct 多步推理与工具调用
- TUI、Desktop、Web 三种交互界面
- 会话持久化、上下文压缩与分层记忆
- Plan / Build 工作模式及危险操作权限确认
- 子 Agent 并行执行、进度查看和结果汇总
- 内置文件、Shell、Python、Git、Web、Todo、Cron、Memory 等工具
- Skills、MCP、Hook、插件和扩展 API
- SQLite 默认存储，以及 MySQL 和自定义存储扩展
- GraalVM Native Image 支持
- 钉钉、飞书等 IM 接入能力

## 架构

所有交互入口最终统一进入：

```text
Channel -> AgentRuntimeGateway -> XpEngine.run -> Context / Memory / Tools -> AgentResponse
```

项目模块：

| 模块 | 说明 |
| --- | --- |
| `xp-agent-entity` | 会话、消息、记忆和 Runtime DTO |
| `xp-agent-config` | 公共配置模型与路径管理 |
| `xp-agent-util` | 日志、终端和线程工具 |
| `xp-agent-tool` | 工具接口、注册中心和工具元数据 |
| `xp-agent-display` | 显示适配与显示事件 |
| `xp-agent-command` | Slash Command 抽象 |
| `xp-agent-context` | Token 估算、上下文窗口和结构化摘要 |
| `xp-agent-extension-api` | 工具、拦截器和存储扩展 SPI |
| `xp-agent-engine` | Agent Runtime、ReAct、记忆、工具、MCP、子 Agent |
| `xp-agent-cli` | Spring Boot、TUI、Desktop、Web、Native Image |
| `xp-agent-web` | Vue Web 前端源码 |

## 环境要求

- JDK 25
- Maven 3.9+
- Node.js 18+，仅修改 Web 前端时需要
- GraalVM JDK 25 和 Native Image，仅构建原生程序时需要
- Windows Native 构建还需要 Visual Studio 2022 C++ Build Tools

## 快速开始

### 1. 克隆和构建

```bash
git clone https://gitee.com/arain1026/xp_agent_java.git
cd xp_agent_java
mvn -DskipTests package
```

构建后的可执行 Jar：

```text
xp-agent-cli/target/xpagent.jar
```

### 2. 配置模型

首次启动会创建：

```text
~/.xp_agent/xp_agent.yml
```

默认配置使用 `OPENAI_API_KEY` 环境变量：

```yaml
agent:
  models:
    - name: openai
      provider: openai
      baseUrl: https://api.openai.com
      apiKey: ${OPENAI_API_KEY:}
      model: gpt-4o-mini
      temperature: 1
  activeModel: openai
```

设置环境变量：

```powershell
# PowerShell
$env:OPENAI_API_KEY = "your-api-key"
```

```bash
# Linux / macOS
export OPENAI_API_KEY="your-api-key"
```

也可以直接修改用户目录中的 `xp_agent.yml`，接入兼容 OpenAI API 的模型服务。不要把真实密钥写进仓库内的配置文件。

### 3. 启动

```bash
# TUI，默认模式
java -jar xp-agent-cli/target/xpagent.jar --tui

# JavaFX Desktop
java -jar xp-agent-cli/target/xpagent.jar --desktop

# Web Server
java -jar xp-agent-cli/target/xpagent.jar --server
```

Web 默认监听 `40088`。如果端口被占用，程序会自动选择其他可用端口。

常用启动参数：

```text
-m, --model <name>       指定模型
-s, --session <id>       恢复指定会话
--last                    恢复最近会话
-w, --workspace <path>   指定工作目录
--max-steps <number>     限制单轮工具步骤
--ui <mode>              tui、desktop 或 server
```

## Web 前端开发

```bash
cd xp-agent-web
npm install
npm run dev
```

构建前端：

```bash
npm run build
```

生产环境使用的静态资源位于 `xp-agent-cli/src/main/resources/static`。

## Native Image

Windows：

```bat
cd xp-agent-cli
build-native.bat dev
build-native.bat
```

也可以直接使用 Maven：

```bash
mvn -pl xp-agent-cli -am -Pnative -DskipTests package
```

Native Image 无法在运行时动态加载任意新类。自定义存储 Provider 或其他依赖反射的扩展，需要在构建 Native Image 时进入 classpath，并配置相应的 Native metadata。

## 存储

默认数据库：

```text
~/.xp_agent/db/xp.db
```

切换 MySQL：

```yaml
agent:
  storage:
    type: mysql
    url: jdbc:mysql://localhost:3306/xp_agent?useUnicode=true&characterEncoding=utf8&useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghai
    username: root
    password: ${XP_AGENT_STORAGE_PASSWORD:}
    initialize-schema: true
```

也可以使用环境变量：

```text
XP_AGENT_STORAGE_TYPE
XP_AGENT_STORAGE_URL
XP_AGENT_STORAGE_DRIVER
XP_AGENT_STORAGE_USERNAME
XP_AGENT_STORAGE_PASSWORD
XP_AGENT_STORAGE_DATABASE
XP_AGENT_STORAGE_INIT_SCHEMA
```

自定义存储需要实现：

```text
top.zhaoyuliu.agent.xp.storage.XpStorageProvider
```

并在扩展 JAR 中声明：

```text
META-INF/services/top.zhaoyuliu.agent.xp.storage.XpStorageProvider
```

JVM 模式会从 `~/.xp_agent/extensions` 加载扩展 JAR。

## 常用命令

| 命令 | 说明 |
| --- | --- |
| `/help` | 查看完整帮助 |
| `/mode plan`、`/mode build` | 切换工作模式 |
| `/model` | 查看或切换模型 |
| `/session list` | 查看会话 |
| `/compact llm` | 使用大模型压缩当前上下文 |
| `/decompact` | 恢复被压缩的消息 |
| `/tools`、`/skills` | 查看工具和技能 |
| `/subagent` | 查看子 Agent |
| `/stats` | 查看 Token 统计 |
| `/config`、`/info` | 查看当前配置和运行状态 |

## 数据目录

XP Agent 的用户数据默认保存在：

```text
~/.xp_agent/
```

其中可能包含：

- 用户模型配置和 API Key
- SQLite 数据库
- 会话和记忆
- 日志
- 扩展 JAR
- 下载的运行时组件

提交 Issue 时，请先检查日志和配置内容，避免上传 API Key、数据库密码、会话隐私或内部地址。

## 安全说明

Agent 可以执行命令并读写文件。建议：

- 在独立工作目录中运行
- 默认使用 Plan Mode 检查方案
- 谨慎开启自动批准
- 不要把生产凭据交给 Agent
- 对 Web Server 设置网络访问控制，不要直接暴露到公网
- 定期备份 `~/.xp_agent` 数据

如果发现安全漏洞，请不要公开披露密钥或可直接利用的细节，优先通过仓库维护者的私密联系方式报告。

## 开发与贡献

```bash
mvn -DskipTests compile
mvn test
```

提交 Pull Request 前请确保：

- 未提交真实凭据、个人配置、数据库和日志
- Java 构建通过
- Web 改动已执行 `npm run build`
- Native 相关改动说明 JVM 与 Native Image 的差异

## License

本项目采用 [MIT License](LICENSE)。仓库中捆绑的第三方 Skills、脚本和资源可能使用各自的许可证，请保留其原始许可证与声明。