# QN-chat

**Repository Path**: YuYao-Gith/QN-chat

## Basic Information

- **Project Name**: QN-chat
- **Description**: AI API聊天工具
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-26
- **Last Updated**: 2026-08-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

```
  ╔═══════════════════════════════════════════╗
  ║   ██████╗ ███╗   ██╗                     ║
  ║  ██╔═══██╗████╗  ██║                     ║
  ║  ██║   ██║██╔██╗ ██║    QN-Chat v2.1    ║
  ║  ██║▄▄ ██║██║╚██╗██║    青年Chat         ║
  ║  ╚██████╔╝██║ ╚████║                     ║
  ║   ╚══▀▀═╝ ╚═╝  ╚═══╝                     ║
  ║        ██████╗██╗  ██╗ █████╗ ████████╗   ║
  ║       ██╔════╝██║  ██║██╔══██╗╚══██╔══╝   ║
  ║       ██║     ███████║███████║   ██║      ║
  ║       ██║     ██╔══██║██╔══██║   ██║      ║
  ║       ╚██████╗██║  ██║██║  ██║   ██║      ║
  ║        ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝      ║
  ╚═══════════════════════════════════════════╝
```

**QN-Chat (青年Chat) v2.1** — 多模型 AI 聊天应用

[四合一界面] Web · CLI · GUI · Admin

</div>

---

# QN-Chat · 青年Chat

> 一款轻量级的多模型 AI 聊天工具，支持流式对话、联网搜索、文件管理、加密 API Key 存储，提供 **四种操作界面**。

---

## 📋 目录

- [功能特性](#-功能特性)
- [支持的模型](#-支持的模型)
- [四种界面](#-四种界面)
- [安全架构](#-安全架构)
- [文件管理](#-文件管理)
- [快速开始](#-快速开始)
- [项目结构](#-项目结构)
- [配置说明](#-配置说明)
- [API 文档](#-api-文档)
- [本地模型配置](#-本地模型配置)
- [常见问题](#-常见问题)
- [开发指南](#-开发指南)
- [开源许可](#-开源许可)

---

## ✨ 功能特性

### 🤖 多模型支持
无缝切换六大 AI 模型提供方，全部使用 OpenAI 兼容 API：

| 提供方 | 说明 | API 地址 |
|--------|------|----------|
| **DeepSeek** | 深度求索 v4 系列 | `https://api.deepseek.com` |
| **通义千问** | 阿里云百炼平台 | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
| **智谱 GLM** | 智谱 AI 开放平台 | `https://open.bigmodel.cn/api/paas/v4` |
| **月之暗面 Kimi** | Moonshot AI | `https://api.moonshot.cn/v1` |
| **Ollama** | 本地开源模型 | `http://localhost:11434/v1` |
| **LM Studio** | 本地 Hugging Face 模型 | `http://localhost:1234/v1` |

### 🎨 四种操作界面

| 界面 | 技术栈 | 特点 |
|------|--------|------|
| **🌐 Web 网页版** | HTML + CSS + JS (原生) | 暗色主题、流式 SSE、拖拽上传、响应式设计 |
| **💻 终端 CLI** | Python Rich 库 | Markdown 渲染、彩色主题、快捷键、命令系统 |
| **🖥️ 桌面 GUI** | Python Tkinter | 原生窗口、侧边栏、菜单系统、对话框 |
| **🔧 管理后台** | 自包含 Web 应用 | 用户管理、API Key 管理、系统监控、日志审计 |

### 🔒 加密 API Key 存储
- **RSA-2048 + AES-256-CBC** 双层加密保护
- RSA 私钥使用 **PBKDF2**（480,000 次迭代）派生密钥加密
- 每次启动需输入用户名和密码解密，密钥永不存明文
- 每个模型提供方可独立配置 API Key

### 📁 文件管理
完整的本地文件 I/O 能力，三种权限级别：
- **📖 只读模式** — AI 仅可读取文件
- **❓ 需确认模式** — AI 操作文件前需用户批准
- **🔓 完全自主模式** — AI 可自主操作文件

支持代码文件、文档、PDF 等多种格式（可配置扩展名白名单）。

### 🌐 联网搜索
内置多引擎搜索功能，支持 **4 种搜索引擎**，AI 可结合实时搜索结果回答问题：

| 搜索引擎 | 说明 | 适用地区 | 是否需要 Key |
|---------|------|---------|-------------|
| **DuckDuckGo** | 默认搜索引擎，即时答案 API | 海外 | 否 |
| **Bing** | Microsoft Bing Web Search API | 国内/海外 | 需 Azure API Key |
| **SearXNG** | 自建隐私友好元搜索引擎 | 自建实例 | 否（自建） |
| **博查搜索 (Bocha)** | 国内 AI 搜索 API | 国内 | 需 API Key |

> 💡 **国内用户建议**：使用 Bing 搜索（需申请 Azure 免费 API Key）或自建 SearXNG 实例。可在管理后台「系统设置」中切换搜索引擎。

### 💬 对话管理
- 多会话管理（创建/切换/删除/重命名）
- 自动上下文裁剪（可配置最大消息数）
- 文件上下文注入
- 系统提示词自定义
- Token 用量统计

### ⚡ 流式对话
- Web 界面：Server-Sent Events (SSE) 实时流式输出
- CLI 界面：Rich 进度动画流式渲染
- GUI 界面：多线程流式更新

---

## 🧠 支持的模型

### DeepSeek
| 模型 | 说明 |
|------|------|
| `deepseek-v4-flash` | 快速推理模型（推荐） |
| `deepseek-v4-pro` | 高性能专业模型 |

### 通义千问（Qwen）
| 模型 | 说明 |
|------|------|
| `qwen-plus` | 增强版（推荐） |
| `qwen-max` | 最大能力版 |
| `qwen-turbo` | 快速版 |
| `qwen-long` | 长上下文版 |
| `qwen3.7-max-preview` | Qwen3.7 最大版预览 |
| `qwen3.7-max` | Qwen3.7 最大版 |
| `qwen3.7-plus` | Qwen3.7 增强版 |
| `qwen3.5-omni-plus` | Qwen3.5 多模态增强版 |

### 智谱 GLM
| 模型 | 说明 |
|------|------|
| `glm-4-flash` | 快速版（推荐） |
| `glm-4` | 标准版 |
| `glm-4-plus` | 增强版 |
| `glm-4-air` | 轻量版 |
| `glm-5.2-flash` | GLM-5.2 快速版 |
| `glm-5.2` | GLM-5.2 标准版 |
| `glm-5.2-plus` | GLM-5.2 增强版 |

### 月之暗面 Kimi
| 模型 | 说明 |
|------|------|
| `moonshot-v1-8k` | 8K 上下文（推荐） |
| `moonshot-v1-32k` | 32K 长上下文 |
| `moonshot-v1-128k` | 128K 超长上下文 |
| `kimi-k3` | Kimi K3 模型 |
| `kimi-k2.7-code` | K2.7 代码专用 |
| `kimi-k2.6` | K2.6 模型 |

### Ollama（本地）
| 模型 | 说明 |
|------|------|
| `llama3.1` / `llama3.2` | Meta LLaMA 系列 |
| `qwen2.5` / `qwen2.5-coder` | 千问 2.5 系列 |
| `mistral` / `mixtral` | Mistral AI 系列 |
| `codellama` | 代码专用 LLaMA |
| 以及更多社区模型 | 通过 Ollama 支持 |

### LM Studio（本地）
| 模型 | 说明 |
|------|------|
| `local-model` | LM Studio 中加载的任意 Hugging Face 模型 |

---

## 🖥️ 四种界面

### 🌐 Web 网页版
浏览器访问，功能最完整的界面。

```bash
python run.py web          # 默认 http://localhost:8888
python run.py web --port 9999  # 自定义端口
```

**功能特点：**
- 暗色主题现代化 UI，响应式设计
- 左侧面板：模型选择、API Key 配置、文件上传
- 联网搜索和上下文开关
- SSE 流式输出，实时显示生成内容
- Markdown 渲染（代码块、标题、列表等）
- 文件拖拽上传（支持多种格式）
- 多会话对话管理

---

### 💻 终端 CLI
适合服务器环境或无桌面场景。

```bash
python run.py cli
```

**功能特点：**
- Rich 库美化，支持 Markdown 渲染
- 彩色主题输出
- 命令系统（/model、/search、/files 等）
- 快捷键支持（Ctrl+C 取消、Ctrl+D 退出）
- 对话管理（/conv list|new|switch|delete）
- 内置状态栏显示模型和权限信息

**CLI 命令列表：**

| 命令 | 说明 |
|------|------|
| `/model [provider] [model]` | 切换模型 |
| `/apikey set\|list\|delete` | 管理 API Key |
| `/files mode <模式>` | 设置文件权限 |
| `/read <path>` | 读取文件 |
| `/ls [path]` | 列出目录 |
| `/clear` | 清除上下文 |
| `/conv list\|new\|switch\|delete` | 管理对话 |
| `/search on\|off` | 切换联网搜索 |
| `/status` | 显示系统状态 |
| `/help` | 显示帮助 |
| `/quit` | 退出程序 |

---

### 🖥️ 桌面 GUI
原生桌面应用，适合日常使用。

```bash
python run.py gui
```

**功能特点：**
- Tkinter 原生窗口，暗色主题
- 侧边栏对话列表
- 菜单栏（文件/模型/文件权限/帮助）
- 对话框式模型切换和 API Key 管理
- 首次设置向导
- 文件打开和读取

---

### 🔧 管理后台
全功能 Web 管理面板。

```bash
python run.py admin         # 默认 http://localhost:4444
python run.py admin --port 9998  # 自定义端口
```

**功能特点：**
- **管理员登录** — 会话认证，默认账户 root/root（超级管理员）、admin/admin（管理员）、user/user（普通用户）
- **系统状态仪表盘** — 运行时间、模型状态、API Key 状态
- **用户管理** — 创建/编辑/删除管理员账户
- **API Key 管理** — 加密存储各个提供方的 API Key
- **模型配置** — 切换默认模型和提供方
- **自定义提供方** — 添加任意 OpenAI 兼容 API
- **Ollama/LM Studio 管理** — 本地服务连通性检查
- **对话历史浏览** — 查看所有历史对话
- **访问日志审计** — 记录所有管理操作
- **多主题切换** — 极客风、春意盎然、夏日美好、秋日飘香、冬日飘雪

---

## 🔒 安全架构

### 加密流程

```
用户输入 (用户名 + 密码)
        ↓
  PBKDF2 (480,000 次迭代)
        ↓
  AES-256 密钥 ← 用于加密 RSA 私钥
        ↓
  RSA-2048 密钥对
    ├── 公钥 → 加密 API Key
    └── 私钥 → 解密 API Key（需登录解锁）
```

### 文件存储

```
~/.qchat/
├── config.json      # 运行时配置（明文）
├── keys.json        # 加密后的 RSA 私钥（AES-256-CBC）
├── secrets.dat      # 加密后的 API Key（RSA-2048 加密）
├── users.json       # 用户账户信息（密码 SHA-256 哈希）
└── custom_providers.json  # 自定义提供方配置
```

### 安全特性
- 私钥文件权限设置为 `600`（仅所有者可读写）
- API Key 在内存中解密，使用时才加载
- 每次启动必须重新输入密码解锁
- 支持所有提供方独立的 API Key

---

## 📁 文件管理

### 权限模式

| 模式 | AI 读取 | AI 写入 | AI 删除 |
|------|---------|---------|---------|
| **📖 只读** | ✅ | ❌ | ❌ |
| **❓ 需确认** | ✅ | ⏳ 需批准 | ⏳ 需批准 |
| **🔓 完全自主** | ✅ | ✅ | ✅ |

### 支持的文件类型
`.txt` `.md` `.py` `.js` `.ts` `.html` `.css` `.json` `.xml` `.yaml` `.yml` `.toml` `.ini` `.cfg` `.c` `.cpp` `.h` `.hpp` `.rs` `.go` `.java` `.kt` `.sh` `.bash` `.zsh` `.sql` `.r` `.rb` `.php` `.csv` `.log` `.pdf` `.docx` `.pptx`

---

## 🚀 快速开始

### 环境要求
- Python 3.9+
- pip

### 安装步骤

```bash
# 1. 克隆项目
git clone <仓库地址>
cd DeepSeekChat

# 2. 安装依赖
pip install -r requirements.txt

# 3. （可选）安装 PDF 解析支持
pip install pdfminer.six
```

### 启动使用

```bash
# 交互式菜单
python run.py

# 或直接指定模式
python run.py web          # Web 服务器 → http://localhost:8888
python run.py cli          # 终端 CLI
python run.py gui          # 桌面 GUI
python run.py admin        # 管理后台 → http://localhost:4444
python run.py all          # Web + Admin 同时启动

# 自定义端口
python run.py web --port 9999
python run.py admin --port 9998
python run.py all --port 9999 --admin-port 9998

# 或通过环境变量
QCHAT_PORT=9999 QCHAT_ADMIN_PORT=9998 python run.py web
```

### 首次使用

1. **启动任意界面**（如 `python run.py web`）
2. **创建管理员账户** — 首次启动会提示设置用户名和密码
3. **添加 API Key** — 至少配置一个模型提供方的 API Key
4. **开始对话** — 选择模型，输入消息

---

## 📁 项目结构

```
DeepSeekChat/
├── run.py              # 🚀 统一启动器（支持所有模式）
├── server.py           # 🌐 Web 服务器（单页应用，811 行）
├── _check.py           # ✅ 语法检查工具
├── requirements.txt    # 📦 Python 依赖清单
├── README.md           # 📖 中文文档
├── README_EN.md        # 📖 英文文档
│
├── core/               # ⚙️ 核心引擎
│   ├── __init__.py     # 模块导出
│   ├── auth.py         # 用户认证与会话管理
│   ├── config.py       # 运行时配置、提供方定义、模型列表
│   ├── crypto.py       # RSA-2048 + AES-256-CBC 双层加密
│   ├── models.py       # 多模型管理器（统一 OpenAI API 调用）
│   ├── files.py        # 文件管理器（含三级权限控制）
│   └── conversation.py # 多会话对话管理器
│
├── cli/                # 💻 终端界面
│   └── app.py          # Rich 增强的命令行聊天（627 行）
│
├── gui/                # 🖥️ 桌面界面
│   └── app.py          # Tkinter 原生桌面应用（846 行）
│
├── admin/              # 🔧 管理后台
│   └── __init__.py     # 全功能 Web 管理面板（1292 行）
│
└── static/             # 🌐 Web 前端
    └── index.html      # 单页应用（嵌入式 CSS/JS，816 行）
```

### 架构图

```
用户输入 → 界面层（Web/CLI/GUI） → 核心引擎 → OpenAI 兼容 API → AI 模型
                                          ↕
                                 加密层（RSA + AES）
                                          ↕
                                 本地配置与密钥存储（~/.qchat/）
```

所有界面共享相同的核心模块：
- **Config** — 从 `~/.qchat/config.json` 加载/保存配置
- **Crypto** — 管理加密的 API Key 存储
- **Models** — 统一的 `chat_stream()` / `chat()` / `chat_with_tools()` 接口
- **Files** — 带权限门控的本地文件操作
- **Conversation** — 多会话对话历史管理

---

## ⚙️ 配置说明

配置文件位于 `~/.qchat/config.json`，包含：

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `provider` | str | `deepseek` | 当前模型提供方 |
| `model` | str | `deepseek-v4-flash` | 当前模型 |
| `auto_send_context` | bool | `true` | 是否自动发送文件上下文 |
| `max_context_messages` | int | `50` | 最大上下文消息数 |
| `file_permission` | str | `ask_permission` | 文件权限模式 |
| `allowed_extensions` | list | (见上文) | 允许的文件扩展名 |
| `max_file_size` | int | `10485760` | 最大文件大小（10MB） |
| `enable_web_search` | bool | `false` | 是否启用联网搜索 |
| `search_provider` | str | `duckduckgo` | 搜索提供方（duckduckgo / bing / searxng / bocha） |
| `search_api_key` | str | `""` | 搜索 API Key（Bing/博查需要） |
| `search_api_base_url` | str | `""` | 自定义搜索 API 地址（SearXNG 自建实例等） |
| `web_port` | int | `8888` | Web 服务端口 |
| `admin_port` | int | `4444` | 管理后台端口 |
| `theme` | str | `geek` | UI 主题 |

---

## 📡 API 文档

### Web 服务器 API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | 提供聊天界面 |
| GET | `/api/context` | 获取当前对话上下文 |
| GET | `/api/models` | 列出可用模型 |
| GET | `/api/providers` | 列出模型提供方 |
| GET | `/api/config` | 获取运行时配置 |
| GET | `/api/conversations` | 获取对话列表 |
| GET | `/api/files/permission` | 获取文件权限设置 |
| GET | `/api/files/pending` | 获取待审批文件操作 |
| POST | `/api/chat` | 发送消息（SSE 流式返回） |
| POST | `/api/upload` | 上传文件 |
| POST | `/api/search` | 执行联网搜索 |
| POST | `/api/config` | 更新配置 |
| POST | `/api/unlock` | 解锁加密模块 |
| POST | `/api/conversations` | 创建新对话 |
| POST | `/api/files/read` | AI 读取文件 |
| POST | `/api/files/write` | AI 写入文件 |
| POST | `/api/files/list` | AI 列出目录 |
| POST | `/api/files/approve` | 批准文件操作 |
| POST | `/api/files/reject` | 拒绝文件操作 |
| DELETE | `/api/context` | 清除对话上下文 |
| DELETE | `/api/upload` | 清除上传文件 |
| DELETE | `/api/conversations/<id>` | 删除对话 |

### 管理后台 API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/admin/login` | 管理员登录 |
| POST | `/api/admin/logout` | 退出登录 |
| GET | `/api/admin/status` | 系统状态 |
| GET | `/api/admin/config` | 获取配置 |
| POST | `/api/admin/config` | 更新配置 |
| GET | `/api/admin/providers` | 列出提供方 |
| GET | `/api/admin/keys` | 列出 API Key |
| POST | `/api/admin/keys` | 设置 API Key |
| DELETE | `/api/admin/keys/<provider>` | 删除 API Key |
| GET | `/api/admin/users` | 列出用户 |
| POST | `/api/admin/users` | 创建用户 |
| POST | `/api/admin/users/update` | 更新用户 |
| POST | `/api/admin/users/delete` | 删除用户 |
| GET | `/api/admin/logs` | 获取访问日志 |
| GET | `/api/admin/conversations` | 获取对话列表 |
| GET | `/api/admin/custom-providers` | 列出自定义提供方 |
| POST | `/api/admin/custom-providers` | 添加自定义提供方 |

---

## 🦙 本地模型配置

### Ollama

1. 安装 [Ollama](https://ollama.com/)
2. 拉取模型：`ollama pull llama3.1`
3. 确保 Ollama 服务运行（默认 `http://localhost:11434`）
4. 在 QN-Chat 中选择 Ollama 提供方和对应模型

### LM Studio

1. 下载安装 [LM Studio](https://lmstudio.ai/)
2. 加载 Hugging Face 模型
3. 启动本地推理服务器（默认 `http://localhost:1234`）
4. 在 QN-Chat 中选择 LM Studio 提供方

---

## ❓ 常见问题

**Q: 如何获取 API Key？**
- DeepSeek: https://platform.deepseek.com/api_keys
- 通义千问: https://bailian.console.aliyun.com/
- 智谱 GLM: https://open.bigmodel.cn/usercenter/apikeys
- 月之暗面 Kimi: https://platform.moonshot.cn/console/api-keys

**Q: 忘记管理员密码怎么办？**
删除 `~/.qchat/users.json` 文件，重启后系统会重新创建三组默认账户。

**Q: 默认账户有哪些？**
系统首次启动自动创建三个账户：

| 用户名 | 密码 | 角色 | 说明 |
|--------|------|------|------|
| `root` | `root` | 超级管理员 | 拥有全部管理权限 |
| `admin` | `admin` | 管理员 | 用户和 API Key 管理 |
| `user` | `user` | 普通用户 | 仅查看权限 |

**Q: Crypto 解锁密码是什么？**
Crypto 加密模块的默认密码是 `qchat2024`（用户名: `admin`）。在管理后台的「API Key 管理」页面中使用此密码解锁加密存储。如果曾自行修改过密码但忘记了，删除 `~/.qchat/keys.json` 和 `~/.qchat/secrets.dat` 并重启即可恢复默认。

**Q: 如何更换模型？**
- Web 界面：左侧面板选择提供方和模型
- CLI 界面：输入 `/model <provider> [model]`
- GUI 界面：菜单 → 模型 → 切换模型
- 管理后台：系统设置页面

**Q: 如何设置联网搜索？**
- Web 界面：点击左侧"联网搜索"开关
- CLI 界面：输入 `/search on`
- 管理后台：系统设置页开启，并可选择搜索引擎

**Q: 国内无法访问 DuckDuckGo 怎么办？**
可在管理后台「系统设置」中将搜索引擎切换为：Bing（需申请 Azure API Key）、自建 SearXNG 实例，或博查搜索。

**Q: 配置文件在哪里？**
所有配置文件存储在 `~/.qchat/` 目录下。

**Q: 如何添加自定义模型提供方？**
在管理后台的"自定义提供方"页面添加 API Base URL 和模型列表。

**Q: 如何查看对话历史？**
在管理后台的"对话"页面可以浏览所有历史对话。

---

## 👨‍💻 开发指南

### 环境准备
```bash
git clone <仓库地址>
cd DeepSeekChat
pip install -r requirements.txt
pip install pdfminer.six  # 可选，PDF 支持
```

### 代码检查
```bash
python3 _check.py
```

### 添加新的模型提供方
1. 在 `core/config.py` 的 `PROVIDERS` 字典中添加新提供方信息
2. 在 `MODEL_CATALOG` 中添加对应模型列表
3. 在 `static/index.html` 的 `MODEL_MAP` 中添加前端映射

### 添加新的 API 端点
1. 在 `server.py` 或 `admin/__init__.py` 中添加路由和处理器
2. 遵循现有的 `send_json()` / `read_body()` 模式

---

## 📄 开源许可

本项目基于 **GNU General Public License v3 (GPLv3)** 开源。

完整许可证文本见 [LICENSE](./LICENSE) 文件，或访问 [GNU 官网](https://www.gnu.org/licenses/gpl-3.0.html)。

---

*Made with ❤️ by 青年 Chat Team*