jess

An AI girl friend in memory of my broken love

📋 项目概述

jess - 一个支持长期记忆的AI聊天应用，提供个性化的AI聊天角色（Profile）系统。

主要功能

• 🤖 多AI聊天角色支持（公开/私有）
• 💾 基于ChromaDB的长期记忆系统
• 👥 用户注册、登录、个人资料管理
• 💬 聊天历史记录
• 📨 用户间消息系统
• 🔗 聊天分享链接
• 🎨 积分系统

技术栈

• 后端: Flask + SQLAlchemy
• 数据库: MySQL (或SQLite)
• AI模型: OpenAI GPT / 百度文心大模型 (可选)
• 向量数据库: ChromaDB
• 数据库迁移: Alembic

---

🔧 环境配置

1. 创建虚拟环境

python -m venv .venv

2. 激活虚拟环境

Windows:

.venv\Scripts\activate

macOS/Linux:

source .venv/bin/activate

3. 安装依赖

pip install -r requirement.txt

---

⚙️ 数据库配置

配置文件设置

1. 复制配置模板：

cp utils/config.py.template utils/config.py

Windows PowerShell:

copy utils\config.py.template utils\config.py

2. 编辑 utils/config.py，配置以下内容：

import os

# OpenAI API密钥
openai.api_key = 'your-openai-api-key-here'

# 初始用户积分
initial_balance = 100

# Flask密钥（用于session）
secret_key = 'your-secret-key-here'

# 数据库连接字符串
# MySQL示例：
connection_str = "mysql+pymysql://用户名:密码@localhost:3306/数据库名"

# 或者使用SQLite（开发环境）：
# connection_str = "sqlite:///jess.db"

# ChromaDB缓存路径
cache_uri = './blob/'

MySQL数据库配置示例

方式一：使用MySQL（推荐生产环境）

1. 创建数据库：

CREATE DATABASE jess_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

2. 配置 utils/config.py:

connection_str = "mysql+pymysql://root:mypassword@localhost:3306/jess_db"

3. 配置 alembic.ini (第63行):

sqlalchemy.url = mysql+pymysql://root:mypassword@localhost:3306/jess_db

方式二：使用SQLite（开发环境）

配置 utils/config.py:

connection_str = "sqlite:///./jess.db"

配置 alembic.ini:

sqlalchemy.url = sqlite:///./jess.db

---

🗄️ 数据库初始化

1. 使用Alembic进行数据库迁移

项目已包含15个迁移文件，执行以下命令初始化数据库：

# 运行所有迁移，创建表结构
alembic upgrade head

2. 验证数据库表

成功执行后，将创建以下数据库表：

• user - 用户表
• profile - AI角色表
• chat_history - 聊天历史
• user_profile_rel - 用户与角色关系表
• balance - 积分余额表
• message - 用户消息表
• sharing_link - 分享链接表

3. 常用Alembic命令

# 查看当前数据库版本
alembic current

# 查看迁移历史
alembic history

# 回滚到上一个版本
alembic downgrade -1

# 创建新的迁移文件（修改模型后）
alembic revision --autogenerate -m "描述信息"

---

🚀 运行应用

1. 创建ChromaDB缓存目录

mkdir blob

Windows:

New-Item -ItemType Directory -Path blob -Force

2. 启动服务器

python server.py

服务器将在 http://localhost:8080 启动

3. 访问应用

打开浏览器访问：http://localhost:8080

---

📁 项目结构

jess/
├── bot/                    # AI机器人相关代码
│   ├── agent.py           # Agent代理
│   ├── chat.py            # 聊天处理
│   └── v1/                # 版本1实现
├── controllers/            # Flask路由控制器
│   ├── chat.py            # 聊天页面
│   ├── profile.py         # 角色管理
│   ├── register.py        # 用户注册
│   └── v1/                # API v1
├── ernie/                  # 百度文心大模型支持
├── migrations/             # Alembic数据库迁移文件
├── models/                 # 数据库模型定义
│   └── __init__.py        # 所有表模型
├── services/               # 业务逻辑层
│   ├── chat.py            # 聊天服务
│   ├── llm.py             # LLM调用封装
│   └── long_term_momory_service.py  # 长期记忆服务
├── static/                 # 静态资源（CSS/JS/图片）
├── templates/              # HTML模板
├── utils/                  # 工具函数
│   ├── config.py.template # 配置模板
│   ├── model_repos.py     # 数据访问层
│   └── decorators.py      # 装饰器
├── alembic.ini            # Alembic配置
├── context.py             # 应用上下文
├── requirement.txt        # 依赖列表
└── server.py             # 启动文件

---

🔑 环境变量配置（可选）

建议使用环境变量管理敏感信息：

Linux/macOS:

export OPENAI_API_KEY='your-api-key'
export SECRET_KEY='your-secret-key'
export DATABASE_URL='mysql+pymysql://user:pass@localhost/jess_db'

Windows PowerShell:

$env:OPENAI_API_KEY='your-api-key'
$env:SECRET_KEY='your-secret-key'
$env:DATABASE_URL='mysql+pymysql://user:pass@localhost/jess_db'

---

🐛 故障排查

问题1：数据库连接失败

• 检查MySQL服务是否运行
• 验证 utils/config.py 和 alembic.ini 中的连接字符串是否一致
• 确认数据库用户权限
• 确认数据库已创建

问题2：OpenAI API错误

• 确认API密钥已正确配置在 utils/config.py
• 检查网络连接
• 验证API配额

问题3：ChromaDB错误

• 确保 blob/ 目录存在且有写入权限
• 检查磁盘空间
• 如遇到sqlite3错误（Linux），项目会自动使用pysqlite3

问题4：依赖安装错误

• 确保Python版本 >= 3.8
• 尝试升级pip: pip install --upgrade pip
• 逐个安装依赖排查问题

---

📝 开发说明

创建新的数据库迁移

1. 修改 models/__init__.py 中的模型定义
2. 生成迁移文件：

alembic revision --autogenerate -m "描述变更"

3. 检查生成的迁移文件（在 migrations/versions/ 目录下）
4. 应用迁移：

alembic upgrade head

长期记忆功能说明

项目使用ChromaDB实现对话的长期记忆功能：

• 对话内容会被向量化存储
• 系统会根据当前对话检索相关历史记忆
• 支持语义搜索，提供更智能的上下文回复

---

📄 许可证

请查看 LICENSE 文件

---

🙏 致谢

An AI girl friend in memory of my broken love.