# qwenpaw-java

**Repository Path**: yinchuanqi/qwenpaw-java

## Basic Information

- **Project Name**: qwenpaw-java
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QwenPaw Java Backend

> 基于 [AgentScope Java](https://github.com/agentscope-ai/agentscope-java) 重写的 QwenPaw 后端，前端沿用原项目 React 控制台，实现 Java 后端 + Python 前端的联调。

## 项目简介

[QwenPaw](https://github.com/agentscope-ai/QwenPaw) 是由 AgentScope 团队开源的个人 AI 助手，原版后端使用 Python (FastAPI + AgentScope Python)。本项目将其后端用 **Spring Boot + AgentScope Java SDK** 重写，方便 Java 开发者学习和参考。

### 核心变化

| 项目 | 原版 (Python) | 本项目 (Java) |
|------|--------------|--------------|
| 后端框架 | FastAPI | Spring Boot 3.4 |
| Agent SDK | agentscope (Python) | agentscope-harness 2.0 (Java) |
| 配置管理 | Pydantic v2 | Jackson + JsonStore |
| 响应式流 | asyncio | Reactor (WebFlux) |
| SSE 推送 | StreamingResponse | SseEmitter |
| 前端 | React + TypeScript | **完全沿用，未修改** |

## 项目结构

```
java-agent/
├── server/                          # Spring Boot 后端
│   ├── pom.xml
│   └── src/main/java/com/qwenpaw/
│       ├── QwenPawApplication.java  # 启动入口
│       ├── agent/                   # Agent 管理 & AgentScope 集成
│       │   ├── AgentScopeAgentService.java  # 核心：构建 Agent、流式对话
│       │   ├── AgentConfigService.java
│       │   └── AgentContextInterceptor.java
│       ├── chat/                    # 聊天会话管理
│       ├── config/                  # Spring 配置 & CORS
│       ├── controller/             # REST 控制器（对齐 Python 后端接口）
│       │   ├── ConsoleController.java   # SSE 聊天 /push-messages
│       │   ├── AgentController.java     # 多 Agent 管理
│       │   ├── ProviderController.java  # LLM Provider 管理
│       │   ├── ChatController.java      # 聊天历史 CRUD
│       │   ├── ConfigController.java    # 渠道/安全/时区配置
│       │   ├── ToolController.java      # 工具开关管理
│       │   ├── SkillController.java     # 技能管理
│       │   ├── McpController.java       # MCP 协议集成
│       │   ├── CronController.java      # 定时任务
│       │   └── ...
│       ├── model/dto/               # 数据传输对象
│       ├── provider/                # LLM Provider 管理
│       │   └── ProviderManager.java     # 内置/自定义 Provider 管理
│       ├── security/                # 认证 & 鉴权
│       ├── sse/                     # SSE 辅助工具
│       └── store/                   # JSON 文件持久化
├── console/                         # 前端（原版 React，未修改）
└── README.md
```

## 技术要点

### 1. AgentScope Runtime 协议

前端 `@agentscope-ai/chat` 组件期望特定的 SSE 事件协议。Java 后端需要按以下顺序发送事件：

```
response created → response in_progress → message in_progress
→ content deltas (流式文本) → content completed → message completed
→ response completed
```

每个事件必须包含 `object` 字段（`"response"` / `"message"` / `"content"`），参见 `AgentScopeAgentService.java`。

### 2. Provider 模型构建

自定义 Provider（如智谱 ChatGLM、DeepSeek）通过 `OpenAIChatModel.Builder` 直接传入 `baseUrl` + `apiKey`：

```java
OpenAIChatModel.builder()
    .modelName("glm-5.1")
    .baseUrl("https://open.bigmodel.cn/api/paas/v4")
    .apiKey("your-api-key")
    .stream(true)
    .build();
```

### 3. 前端联调

前端通过 Vite dev server 代理连接 Java 后端：

```typescript
// console/vite.config.ts
server: {
  proxy: {
    "/api": {
      target: "http://localhost:8088",
      changeOrigin: true,
    },
  },
}
```

### 4. JSON 序列化对齐

Jackson 配置 `SNAKE_CASE` + `NON_NULL` 与 Python 后端保持一致。但前端期望的数组/字符串字段需设置默认值（空数组 `[]`、空字符串 `""`），避免前端解构 `undefined` 报错。

## 快速开始

### 环境要求

- Java 17+
- Maven 3.8+
- Node.js 20+

### 1. 启动 Java 后端

```bash
cd java-agent/server
mvn spring-boot:run
```

后端默认运行在 `http://localhost:8088`。

### 2. 启动前端

```bash
cd console
npm ci
npm run dev
```

前端运行在 `http://localhost:5173`，API 请求自动代理到 Java 后端。

### 3. 配置 LLM Provider

访问 `http://localhost:5173/models` 页面，选择一个 Provider（如 DashScope、OpenAI、智谱等），配置 API Key。

或直接编辑 `~/.qwenpaw/config.json`：

```json
{
  "active_model": {
    "provider_id": "dashscope",
    "model": "qwen-plus"
  },
  "providers": {
    "dashscope": {
      "api_key": "your-api-key"
    }
  }
}
```

### 4. 开始对话

访问 `http://localhost:5173/chat`，开始与 AI 对话。

## API 覆盖

| 模块 | 路径 | 状态 |
|------|------|------|
| 认证 | `/api/auth` | ✅ |
| 多 Agent 管理 | `/api/agents` | ✅ |
| LLM Provider | `/api/models` | ✅ |
| 聊天 (SSE) | `/api/console/chat` | ✅ |
| 聊天历史 | `/api/chats` | ✅ |
| 工具管理 | `/api/tools` | ✅ |
| 渠道配置 | `/api/config/channels` | ✅ |
| 安全配置 | `/api/config/security` | ✅ |
| MCP 集成 | `/api/mcp` | ✅ |
| 定时任务 | `/api/cron` | ✅ |
| 备份 | `/api/backups` | ⚠️ 部分 |
| 技能管理 | `/api/skills` | ⚠️ 读取已实现 |
| 工作区 | `/api/workspace` | ⚠️ 部分 |
| Git 集成 | `/api/workspace/git` | 🔴 待实现 |
| 插件系统 | `/api/plugins` | 🔴 待实现 |
| 本地模型 | `/api/local-models` | 🔴 待实现 |

## 学习资源

- [AgentScope Java SDK](https://github.com/agentscope-ai/agentscope-java) — Java 版 Agent 框架
- [QwenPaw 原版](https://github.com/agentscope-ai/QwenPaw) — Python 后端参照实现
- [Spring Boot 文档](https://spring.io/projects/spring-boot)
- [Project Reactor](https://projectreactor.io/) — 响应式编程

## License

本项目遵循 [QwenPaw 原版 License](https://github.com/agentscope-ai/QwenPaw/blob/main/LICENSE)。