# AI 助手项目

这是一个基于 Google Gemini API 构建的 AI 助手项目，旨在提供一个交互式的聊天界面，支持多轮对话、记忆管理和可配置的系统指令。

## 项目结构

```
.
├── app.py                  # 主应用程序入口，处理后端逻辑和API路由
├── config.ini              # 配置文件，用于存储API密钥、模型设置、文件路径等
├── config.py               # 配置加载和管理模块
├── file_manager.py         # 文件操作工具，用于读写JSON、管理目录等
├── gemini_client.py        # Gemini API 客户端，处理与Google Gemini API的交互
├── memory_manager.py       # 记忆管理模块，处理短期和长期记忆的存储与检索
├── README.md               # 项目说明文件
├── requirements.txt        # Python依赖列表
├── utils.py                # 常用工具函数，如日志配置、时间处理等
├── data/
│   ├── chat_logs/          # 存储聊天记录
│   ├── features/           # 存储角色特性（例如：default_role/features.json）
│   └── memories/           # 存储记忆数据（例如：default_memory/memory.json）
└── static/
    ├── index.html          # 前端主页面
    ├── css/
    │   ├── modern-style.css # 现代风格CSS
    │   └── style.css       # 主要CSS样式
    ├── js/
    │   ├── api.js          # 前端API调用逻辑
    │   ├── app.js          # 前端主应用逻辑
    │   ├── ui_manager.js   # 前端UI管理逻辑
    │   └── lib/            # 前端第三方库
    │       ├── marked.min.js # Markdown解析库
    │       └── purify.min.js # HTML净化库
```

## 功能特性

*   多轮对话: 支持与AI进行连续的多轮对话，保持上下文。
*   记忆管理:
    *   短期记忆: 存储最近的对话轮次，用于维持当前对话的连贯性。
    *   长期记忆: 通过摘要和嵌入技术，将关键信息存储为长期记忆，以便在后续对话中检索和利用。
*   可配置性:
    *   通过 `config.ini` 文件轻松配置 Gemini API 密钥、默认模型、上下文窗口大小、记忆保留轮次等。
    *   支持从环境变量加载 `GEMINI_API_KEY`。
*   流式响应: 支持 Gemini API 的流式响应，提供更流畅的用户体验。
*   前端界面: 提供一个简洁的Web界面，方便用户与AI助手交互。
*   日志记录: 详细的日志记录，便于调试和问题追踪。

## 安装与运行

### 1. 克隆仓库

```bash
git clone https://github.com/your-username/your-repo-name.git
cd your-repo-name
```
(请将 `your-username/your-repo-name.git` 替换为实际的仓库地址)

### 2. 创建并激活虚拟环境 (推荐)

```bash
python -m venv venv
# Windows
.\venv\Scripts\activate
# macOS/Linux
source venv/bin/activate
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 配置 API 密钥

在项目根目录下找到 `config.ini` 文件。
将 `[API]` 部分的 `GEMINI_API_KEY` 替换为你的 Google Gemini API 密钥。

```ini
[API]
GEMINI_API_KEY = YOUR_GEMINI_API_KEY_HERE
```
或者，你可以设置环境变量 `GEMINI_API_KEY`。环境变量的优先级高于 `config.ini` 文件中的配置。

### 5. 运行应用程序

```bash
python app.py
```

应用程序将在本地启动一个Web服务。通常，你可以在浏览器中访问 `http://127.0.0.1:5000` 来使用AI助手。

## 配置说明

项目的主要配置通过 `config.ini` 文件管理。以下是各个配置项的详细说明：

### [API] 部分

*   `gemini_api_base_url`: Gemini API 的基础 URL。如果使用代理或自定义端点，请修改此项。
*   `gemini_api_key`: 你的 Google Gemini API 密钥。建议通过环境变量 `GEMINI_API_KEY` 设置，优先级更高。
*   `default_gemini_model`: 默认使用的 Gemini 模型，例如 `models/gemini-2.0-flash`。
*   `memory_update_model`: 用于记忆更新（摘要和嵌入）的 Gemini 模型。

### [Application] 部分

*   `context_window_size`: 短期记忆中保留的对话轮次数量，用于维持当前对话的上下文。
*   `memory_retention_turns`: 长期记忆更新的频率，每隔多少轮对话进行一次记忆摘要和存储。
*   `max_short_term_events`: 短期记忆中最大事件（消息）数量。
*   `features_dir`: 存储角色特性配置文件的目录路径。
*   `memories_dir`: 存储长期记忆数据文件的目录路径。
*   `chat_logs_dir`: 存储聊天记录文件的目录路径。
*   `app_log_file_path`: 应用程序日志文件的路径。

### [Session] 部分

*   `current_role_id`: 当前会话使用的角色ID。
*   `current_memory_id`: 当前会话使用的记忆ID。
*   `current_chat_log_id`: 当前会话的聊天记录ID。

## 使用说明

在Web界面中输入你的问题或指令，AI助手将根据你的输入和历史对话进行回复。

## 贡献

欢迎贡献！如果你有任何改进建议或发现bug，请提交Issue或Pull Request。

## 许可证

本项目采用 MIT 许可证。详见 `LICENSE` 文件 (如果存在)。