# NexusTale

**Repository Path**: crisJiang/NexusTale

## Basic Information

- **Project Name**: NexusTale
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NexusTale

一个使用 React + Tailwind CSS + Zustand + Vite 构建的 AI 角色扮演聊天应用，灵感来自 SillyTavern。

## ✨ 功能特性

### 核心功能
- ✅ **角色系统** — 创建/编辑/删除 AI 角色，支持头像上传、性格设定、场景设定、第一条消息等
- ✅ **角色模板 / 自定义提示词** — 角色支持模板模式（描述+性格+场景）与自定义 System Prompt 两种模式
- ✅ **多会话管理** — 每个角色下可创建多个话题（Conversation），支持搜索、重命名、删除
- ✅ **AI 话题总结** — 调用 AI 自动为话题生成简短标题
- ✅ **流式响应** — 支持 SSE 流式输出，逐字显示 AI 回复
- ✅ **消息操作** — 消息编辑、重新生成、复制、删除
- ✅ **AI 生成用户回复** — 可让 AI 模拟生成用户端的回复建议
- ✅ **中止生成** — 发送消息和生成用户回复均支持中止操作
- ✅ **Markdown 渲染** — 支持 GFM 语法（表格、删除线、任务列表等）
- ✅ **虚拟滚动** — 消息超过 100 条时自动启用 react-virtuoso 虚拟列表，保证性能

### API 与配置
- ✅ **多 API 配置** — 支持管理多个模型提供商配置，可自由切换
- ✅ **OpenAI 兼容接口** — 兼容 OpenAI API 格式（支持 Ollama、LocalAI、ModelScope 等）
- ✅ **模型列表管理** — 每个 API 配置内可添加/删除/选择多个模型
- ✅ **思考模式 (enable_thinking)** — 支持 DeepSeek 等模型的思考模式
- ✅ **chat_template_kwargs 兼容** — 自动检测模型是否支持该参数，避免不兼容错误
- ✅ **API 连接测试** — 可一键测试 API 配置是否有效

### 数据管理
- ✅ **数据持久化** — 使用 Zustand persist + localStorage 自动保存所有数据
- ✅ **数据导出/导入** — 支持导出完整数据为 JSON 文件，也可从备份文件导入恢复

### UI 与体验
- ✅ **深色/浅色主题** — 支持一键切换
- ✅ **自定义字体** — 可调整字体大小（12-24px）和字体系列
- ✅ **头像显示开关** — 可选择是否在对话中显示头像
- ✅ **响应式布局** — 适配桌面端和移动端
- ✅ **Toast 通知** — 操作结果的即时反馈
- ✅ **滚动导航按钮** — 聊天区域可快速跳转到顶部/底部

## 🛠 技术栈

| 分类 | 技术 | 说明 |
|------|------|------|
| UI 框架 | **React 18** | 函数组件 + Hooks |
| 构建工具 | **Vite 5** | 快速热更新与构建 |
| 状态管理 | **Zustand 4** | 轻量状态管理，支持 persist 中间件 |
| 样式框架 | **Tailwind CSS 3** | 原子化 CSS |
| 组件库 | **Shadcn UI** (自定义) | 手写 UI 组件（Button、Card、Input 等） |
| Markdown | **react-markdown 9** + **remark-gfm** | GitHub 风格 Markdown 渲染 |
| 虚拟列表 | **react-virtuoso** | 大量消息时的性能优化 |
| 图标 | **Lucide React** | 简洁矢量图标 |

## 🚀 快速开始

### 安装依赖

```bash
npm install
```

### 启动开发服务器

```bash
npm run dev
```

访问 http://localhost:3000 查看应用。

### 构建生产版本

```bash
npm run build
```

### 预览生产构建

```bash
npm run preview
```

## 📁 项目结构

```
NexusTale/
├── public/
│   └── assets/               # 静态资源（角色头像等）
├── src/
│   ├── api/
│   │   └── index.js           # AI API 调用（OpenAI 兼容格式，支持流式）
│   ├── components/
│   │   ├── ui/                # 基础 UI 组件
│   │   │   ├── Button.jsx
│   │   │   ├── Card.jsx
│   │   │   ├── Input.jsx
│   │   │   ├── Label.jsx
│   │   │   ├── ScrollArea.jsx
│   │   │   ├── Separator.jsx
│   │   │   ├── Slider.jsx
│   │   │   ├── Switch.jsx
│   │   │   ├── Textarea.jsx
│   │   │   ├── Toast.jsx
│   │   │   └── Tooltip.jsx
│   │   ├── ChatArea.jsx       # 聊天区域（消息列表 + 输入框）
│   │   ├── MessageItem.jsx    # 单条消息组件（memo 优化）
│   │   ├── Sidebar.jsx        # 侧边栏（角色列表 + 话题列表）
│   │   ├── CharacterManager.jsx # 角色管理页面
│   │   ├── SettingsPanel.jsx  # 模型/API 配置页面
│   │   └── UISettingsPanel.jsx # 界面设置页面
│   ├── hooks/
│   │   └── useIsMobile.js     # 移动端检测 Hook
│   ├── lib/
│   │   └── utils.js           # 工具函数（cn 类名合并等）
│   ├── store/
│   │   ├── useChatStore.js    # Zustand 全局状态（会话、角色、配置等）
│   │   └── defaultConfig.js   # 默认配置数据
│   ├── App.jsx                # 主应用组件（路由/布局/主题切换）
│   ├── main.jsx               # 应用入口
│   └── index.css              # 全局样式 + Tailwind + 主题变量
├── index.html                 # HTML 入口
├── package.json
├── vite.config.js
├── tailwind.config.js
└── postcss.config.js
```

## 📋 应用页面说明

| 页面 | 入口 | 功能 |
|------|------|------|
| 💬 聊天 | 顶部导航 `MessageSquare` 图标 | 与选中角色的当前话题对话 |
| 👤 角色管理 | 顶部导航 `User` 图标 | 创建/编辑/删除角色卡片 |
| ⚙️ 模型设置 | 顶部导航 `Settings2` 图标 | 管理 API 配置、模型、参数 |
| 🎨 界面设置 | 顶部导航 `Settings` 图标 | 字体、主题、头像显示 |
| 📑 侧边栏 | 左侧可折叠 | 角色列表 / 话题列表切换 |

## ⚙️ 配置说明

### API 配置

在模型设置页面可以配置：
- **API Base URL** — 如 `https://api.openai.com/v1`
- **API Key** — 对应平台的密钥
- **模型名称** — 从模型列表中选择或手动添加
- **温度参数** — 0-2，控制生成随机性
- **最大 Token 数** — 控制单次回复长度
- **思考模式** — 启用后发送 `enable_thinking` 参数

### 状态持久化

应用使用 localStorage (`nexustale-storage`) 自动保存以下数据：
- 所有对话历史与消息
- 角色定义（名称、性格、提示词等）
- 多个 API 配置及当前选中配置
- UI 设置（主题、字体、头像显示等）
- 侧边栏状态