# Tone-Twin-Agent

**Repository Path**: yu-zi-wei/tone-twin-agent

## Basic Information

- **Project Name**: Tone-Twin-Agent
- **Description**: Tone-Twin-Agent：基于 LangChain4j + Spring Boot 3的工业级全栈 Agent 架构。原生集成 MCP 协议、Exa 联网搜索与动态抓取工具链；内置思维树 (ToT) 与 Step-Back 高阶逻辑引擎，内置多重人格切换机制。采用 JSON 强校验 SSE 流式渲染，是进阶 Agentic Workflow 与复杂提示词工程的实战级模版。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2025-12-28
- **Last Updated**: 2025-12-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Tone-Twin-Agent

`Tone-Twin-Agent` 是一个基于大模型的双重人格 AI 助手项目。它集成了流式对话、人格动态切换、MCP（Model Context Protocol）工具调用等核心功能，旨在提供一个兼具文学美感（桃子 - 天才作家）与硬核实战（老王 - 臭流氓）的独特 AI 交互体验。

## 项目结构

项目采用前后端分离架构：

- `tone-twin-agent-service`: 基于 Java/Spring Boot 的后端服务。
- `tone-twin-agent-ui`: 基于 Vue 3/Vite 的前端界面。

---

## 后端服务：tone-twin-agent-service

### 核心功能

- **双重人格系统**：支持动态切换“天才作家”与“臭流氓”人格，通过不同的系统提示词模板实现。
- **LangChain4j 集成**：使用 LangChain4j 框架进行大模型编排，支持同步与流式输出。
- **MCP 工具支持**：集成 Model Context Protocol，支持联网搜索（Exa/智谱）和网页抓取。
- **SSE 流式传输**：采用标准 Server-Sent Events (SSE) 协议，配合 JSON 封装确保输出格式 100% 还原。
- **工业级提示词**：内置多层级提示词模板，支持思维树 (ToT)、后退提炼 (Step-Back) 等高级推理策略。

### 技术栈

| 类别        | 技术方案                                     |
|:--------- |:---------------------------------------- |
| **语言**    | Java 17                                  |
| **框架**    | Spring Boot 3.5.3                        |
| **AI 框架** | LangChain4j 1.9.1-beta17                 |
| **大模型**   | 阿里通义千问 (Qwen-Max)                        |
| **核心组件**  | Lombok, Maven, Project Reactor (WebFlux) |

### 快速启动

1. **配置环境变量**：在 `src/main/resources/application.yml` 中配置你的 `api-key`。
2. **运行项目**：
   
   ```bash
   cd tone-twin-agent-service
   mvn spring-boot:run
   ```
3. **打包**：
   
   ```bash
   mvn clean package
   ```

---

## 前端界面：tone-twin-agent-ui

### 核心功能

- **流式对话解析**：严格遵循 SSE 规范，支持 JSON 块解析，实时呈现 AI 回复。
- **人格动态切换**：支持在界面侧边栏一键切换 AI 的性格偏好。
- **Markdown 渲染**：集成 `markdown-it` 和 `highlight.js`，支持标题、列表、代码块的高亮显示。
- **响应式设计**：适配 PC 与移动端展示。

### 技术栈

| 类别              | 技术方案                      |
|:--------------- |:------------------------- |
| **基础框架**        | Vue 3 (Composition API)   |
| **构建工具**        | Vite 7.x                  |
| **CSS 框架**      | Tailwind CSS 4.x          |
| **图标库**         | Lucide Vue Next           |
| **Markdown 渲染** | Markdown-it, Highlight.js |

### 快速启动

1. **安装依赖**：
   
   ```bash
   cd tone-twin-agent-ui
   npm install
   ```
2. **开发模式运行**：
   
   ```bash
   npm run dev
   ```
3. **构建打包**：
   
   ```bash
   npm run build
   ```

---

## 开发注意事项

- **Markdown 铁律**：后端输出必须严格遵守 `prompts/common/format-prompt.md` 中的规程。
- **API 验证**：前端请求需在侧边栏输入正确的 API Token 才能通过后端校验。