🐾 PetChat

一款智能桌面聊天应用 —— 拥有情绪感知宠物与 AI 记忆提炼功能

核心特性 • 快速开始 • 系统架构 • 项目结构 • 常见问题 • 贡献

---

✨ 核心特性

功能	描述
🌐 实时通信	Client-Server 架构，多用户同时在线，公共群聊 + 私人对话
🐱 情绪宠物	AI 分析对话氛围，宠物表情随情绪动态变化
🧠 智能记忆	自动提炼对话中的共同事件、约定和话题
💡 AI 建议	意图识别，智能生成行程和决策建议
🔒 隐私优先	数据本地存储，AI 请求透明可控
🎨 暗黑主题	现代化 UI 设计，支持主题定制

---

🚀 快速开始

1️⃣ 环境准备

系统要求：

组件	版本要求
Python	3.10+
操作系统	Windows 10/11, Linux, macOS

# 克隆仓库
git clone https://github.com/XenithMC/petchat.git
cd petchat

安装依赖：

# Windows
setup_venv.bat

# Linux/macOS
source setup_venv.sh

# 或手动安装依赖
pip install -r requirements.txt

2️⃣ 启动服务器

python server_cli.py

服务器默认在 0.0.0.0:8888 启动监听。

可选参数：

参数	说明	默认值
--port	指定服务器端口	8888
--log-level	日志级别 (DEBUG/INFO/WARNING/ERROR)	INFO

# 指定端口
python server_cli.py --port 9000

# 指定日志级别
python server_cli.py --log-level DEBUG

3️⃣ 启动客户端

python main.py

# 或指定服务器 IP
python main.py --server-ip 192.168.1.100

4️⃣ 配置 AI（可选）

通过菜单 设置 → AI 配置 或快捷键 Ctrl+K 配置 API Key。

支持的 AI Provider：

Provider	说明
OpenAI 兼容	支持 OpenAI API、LM Studio、Ollama 等
Google Gemini	Google 原生 Gemini API

---

🏗️ 系统架构

graph TB
    subgraph Client["🖥️ 客户端 (PyQt6)"]
        UI["MainWindow<br/>用户界面"]
        NM["NetworkManager<br/>网络通信"]
        DB_C[("SQLite<br/>本地存储")]
    end
    
    subgraph Server["🖧 服务器"]
        SC["ServerCore<br/>消息路由"]
        AI["AIService<br/>智能分析"]
        SM["SessionManager<br/>会话管理"]
    end
    
    subgraph Providers["🤖 AI Providers"]
        OP["OpenAI<br/>兼容协议"]
        GP["Gemini<br/>原生 API"]
    end
    
    UI --> NM
    NM <-->|"TCP Socket<br/>Protocol.pack/unpack"| SC
    SC --> AI
    AI --> SM
    AI --> OP
    AI --> GP
    UI --> DB_C
    
    style Client fill:#1a1a2e,stroke:#16213e,color:#fff
    style Server fill:#0f3460,stroke:#16213e,color:#fff
    style Providers fill:#533483,stroke:#16213e,color:#fff

Loading

通信协议

┌────────────────────────────────────────┐
│  Header (8 bytes)  │     Payload       │
├────────────────────┼───────────────────┤
│ Length (4B) │ CRC32 (4B) │   JSON      │
└────────────────────────────────────────┘

字段	大小	说明
Length	4 字节	Payload 数据长度
CRC32	4 字节	数据校验码
Payload	可变	UTF-8 编码的 JSON 数据

---

📁 项目结构

petchat/
├── server_cli.py          # 聊天服务器入口
├── main.py                # 客户端应用入口
├── setup_venv.bat         # Windows 虚拟环境脚本
├── setup_venv.sh          # Linux/macOS 虚拟环境脚本
├── requirements.txt       # Python 依赖
├── core/
│   ├── network.py         # TCP 网络通信
│   ├── protocol.py        # 消息协议 (Header + JSON)
│   ├── ai_service.py      # AI 服务封装
│   ├── ai_session_manager.py  # AI 会话管理
│   ├── database.py        # SQLite 数据库
│   ├── models.py          # 数据模型
│   ├── config_manager.py  # 配置管理
│   ├── server_core.py     # 服务器核心逻辑
│   ├── window_manager.py  # 窗口管理
│   ├── crash_reporter.py  # 崩溃报告
│   └── providers/         # AI Provider 实现
│       ├── base.py        # Provider 基类
│       ├── openai_provider.py
│       ├── gemini_provider.py
│       ├── retry.py       # 重试机制
│       └── factory.py     # Provider 工厂
├── ui/
│   ├── main_window.py     # 主窗口
│   ├── server_window.py   # 服务器窗口
│   ├── pet_widget.py      # 情绪宠物组件
│   ├── memory_viewer.py   # 记忆查看器
│   ├── suggestion_panel.py # 建议面板
│   ├── api_config_dialog.py # API 配置对话框
│   ├── user_profile_dialog.py # 用户配置
│   └── theme.py           # 暗黑主题
├── config/
│   └── settings.py        # 应用配置
├── tests/                 # 测试套件
│   ├── network_test.py
│   ├── test_ai_providers.py
│   ├── stress_test.py
│   └── verify_cs_server.py
└── .github/
    └── workflows/         # CI/CD 配置

---

🧪 测试

# 运行 AI Provider 测试
python -m pytest tests/test_ai_providers.py -v

# 网络通信测试
python tests/network_test.py

# 多进程启动测试
python tests/launch_multiprocess.py

# 压力测试
python tests/stress_test.py

---

📦 打包分发

# 客户端打包
python -m PyInstaller --name=pet-chat --onefile --windowed main.py

# 服务器打包
python -m PyInstaller --name=pet-chat-server --onefile server_cli.py

生成的可执行文件位于 dist/ 目录。

---

🔒 隐私与安全

特性	说明
数据本地化	对话内容与记忆仅存储于本地 petchat.db
透明 AI 请求	AI 仅在分析间隔发送必要的匿名上下文
可配置 Provider	支持本地 AI 服务（如 Ollama），数据不出内网

---

❓ 常见问题

Q: 为什么宠物没有显示情绪变化？

A: 请确保已配置 AI Provider 并在设置中启用了情绪分析功能。

Q: 如何连接远程服务器？

A: 启动客户端时使用 --server-ip 参数指定服务器 IP 地址。

Q: 支持哪些 AI 模型？

A: 支持所有 OpenAI 兼容协议的模型（如 GPT-4、Claude 通过代理等）以及 Google Gemini 系列模型。

Q: 数据存储在什么位置？

A: 数据存储在用户目录下的 petchat.db SQLite 数据库文件中。

---

📄 开源协议

本项目采用 GNU GPLv3 协议。

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

贡献流程

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

开发指南

• 阅读 BUILD.md 了解构建细节
• 阅读 SKILL.md 了解项目规范
• 查看 CHANGELOG.md 了解版本历史

---

📬 联系方式

• 作者: Xustalis
• 仓库: https://github.com/Xustalis/petchat

---

Made with ❤️ by the PetChat Team