Metadata-Version: 2.4
Name: ErisPulse-QvQChat
Version: 2.0.0
Summary: ErisPulse QvQChat 智能对话模块 - 多AI协同智能体
Author-email: wsu2059q <wsu2059@qq.com>
License: MIT License
        
        Copyright (c) 2025 wsu2059q
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: homepage, https://github.com/wsu2059q/ErisPulse-AIChat
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Dynamic: license-file

# QvQChat 智能对话模块

## 简介

QvQChat 是一个基于多AI协同的智能对话模块，采用"普通群友模式"，让AI像真人一样自然参与聊天。

### 核心特性 ⭐

- **AI自主决策**：无需命令格式，直接用自然语言交互
- **记忆自然融合**：询问"你记得我的生日吗"，AI根据记忆自然回答
- **配置简化**：只需配置dialogue的API密钥，其他AI自动复用
- **窥屏模式**：群聊默默观察，适时回复（默认3%回复率）
- **多模态支持**：支持图片理解（需要gpt-4o等视觉模型）

### 与传统AI助手的区别

| 特性 | 传统AI助手 | QvQChat |
|------|-------------|----------|
| 回复方式 | 积极回复每条消息 | AI智能判断，适当回复 |
| 记忆方式 | 用户显式查询 | 记忆自然融入对话 |
| 对话风格 | 正式、格式化 | 随意、无格式 |
| 群聊行为 | 积极参与 | 窥屏模式，更像真人 |

## 快速开始

### 第一步：获取API密钥

访问 [OpenAI API Keys](https://platform.openai.com/api-keys) 创建API密钥。

### 第二步：配置文件

首次运行后会自动生成 `config.toml`，或者参考 `config.example.toml` 创建配置。

**最小配置（必需）**：
```toml
[QvQChat]
bot_nicknames = ["你的机器人名字"]
bot_ids = ["你的机器人ID"]

[QvQChat.dialogue]
base_url = "https://api.openai.com/v1"
api_key = "sk-your-actual-api-key-here"
model = "gpt-4o"  # 建议使用支持视觉的模型
```

### 第三步：安装

```bash
ep install AIChat
```

### 第四步：配置机器人识别

编辑 `config.toml`：
```toml
[QvQChat]
bot_nicknames = ["AI助手", "小B"]  # 文本匹配
bot_ids = ["123456789"]  # @匹配
```

## 功能说明

### 1. AI智能决策（普通群友模式）⭐

QvQChat 完全由AI进行所有决策，更像真正的群友：

#### 📊 两大决策
1. **是否回复** - AI根据对话上下文判断
2. **是否记忆** - AI自动判断什么值得记住

#### 🔍 AI回复判断标准

**会回复的情况**：
- ✅ 用户在向你提问（直接或间接）
- ✅ 用户提到你的名字，需要回应
- ✅ 对话正在讨论你感兴趣或了解的话题
- ✅ 适当的幽默回应可以活跃气氛
- ✅ 之前提到的事情有更新或结论

**不会回复的情况**：
- ❌ 普通打招呼（"在吗"、"大家好"）
- ❌ 表情符号、纯表情回复
- ❌ 简单的"好的"、"嗯"、"收到"
- ❌ 与你无关的话题讨论
- ❌ 连续短时间内多次回复（显得不自然）

#### 📝 AI记忆判断标准

**会记住的情况**：
- ✅ 对方的个人信息：生日、重要日期、工作、学校
- ✅ 对方的喜好：爱吃的、不爱吃的、兴趣爱好
- ✅ 对方的习惯：作息时间、运动习惯、特殊习惯
- ✅ 对方的重要关系：家人、伴侣、好朋友
- ✅ 对方最近的状态：生病、忙碌、考试、搬家
- ✅ 对方的目标和计划：要考试、要旅行、要找工作

**不会记住的情况**：
- ❌ 日常闲聊："在吗"、"大家好"、"哈哈哈"
- ❌ 简单回应："好的"、"嗯"、"收到"、"知道了"
- ❌ 表情包、纯表情消息
- ❌ 一次性话题："今天天气不错"、"这菜不错"
- ❌ 纯粹吐槽、发泄（无具体信息）
- ❌ 对你的评价（除非重要）
- ❌ 已经说过很多次的事情

### 2. 多AI协同

| AI类型 | 用途 | 必需 | 默认复用dialogue |
|--------|--------|--------|-----------------|
| dialogue | 对话AI | ✅ | - |
| intent | 意图识别 | ✅ | ✅ |
| intent_execution | 意图执行（系统操作） | ✅ | ✅ |
| memory | 记忆提取 | ❌ | ✅ |
| reply_judge | 回复判断（私聊） | ❌ | ✅ |
| vision | 图片分析 | ❌ | ✅ |

**说明**：未配置API密钥的AI会自动复用dialogue的配置。

### 3. 智能记忆管理

#### 工作原理
```
用户发送消息
    ↓
[dialogue AI] 对话回复
    ↓
[多AI协同] 判断是否值得记忆
    ├─ 使用 dialogue AI 分析对话价值
    └─ 评估是否影响后续对话
    ↓
[memory AI] 提取关键信息
    ├─ 严格提取标准（个人偏好、重要日期、任务等）
    ├─ 过滤无关信息（闲聊、问候、表情等）
    └─ 去重检查（避免重复记忆）
    ↓
保存到长期记忆
```

#### 记忆使用

**自然融入对话**（推荐）：
```
用户：你记得我的生日吗？
AI：是的，我记得你的生日是6月15日。
```

**用户主动要求记忆**：
```
用户：记住这件事，我下周五生日
AI：好的，我会记住你下周五生日。✅
```

**删除记忆**：
```
用户：忘记这件事
AI：我会帮你删除相关记忆。
```

#### 记忆存储

- **私聊**：只存用户个人记忆
- **群聊**：用户个人记忆 + 群记忆（混合模式）
- **群记忆模式**：
  - `mixed`：保存发送者记忆 + 群公共上下文（默认）
  - `sender_only`：只保存发送者的个人记忆

### 4. 意图执行（自然语言操作）

无需命令格式，直接用自然语言描述操作：

| 操作 | 示例 |
|------|--------|
| 添加记忆 | "记住这件事" |
| 删除记忆 | "忘记这件事"、"删掉这条记忆" |
| 修改群提示词 | "把群提示词改成XX" |
| 修改群记忆模式 | "群记忆模式改成混合模式" |
| 清除会话 | "清除会话"、"清空对话历史" |
| 导出记忆 | "导出我的记忆" |

### 5. 图片理解

- **直接传递**：dialogue AI支持视觉功能（如gpt-4o）时，图片直接传给AI
- **自动回退**：模型不支持视觉时，自动跳过图片，只处理文字
- **视觉AI备用**：如果配置了vision AI，先用vision分析再传给dialogue

### 6. 窥屏模式（群聊）

群聊默认启用窥屏模式，更像真人参与：

| 参数 | 默认值 | 说明 |
|------|----------|------|
| enabled | true | 启用窥屏模式 |
| default_probability | 0.03 | 默认回复概率（3%） |
| mention_probability | 0.8 | 被@时回复概率（80%） |
| keyword_probability | 0.5 | 匹配关键词时回复概率（50%） |
| question_probability | 0.4 | 提问时回复概率（40%） |
| min_messages_between_replies | 15 | 两次回复之间至少间隔多少条消息 |
| max_replies_per_hour | 8 | 每小时最多回复次数 |

## 配置说明

### 完整配置

```toml
[QvQChat]
# 基础配置
max_history_length = 20
min_reply_interval = 10
bot_nicknames = ["AI助手"]
bot_ids = ["123456789"]

# 窥屏模式配置
[QvQChat.stalker_mode]
enabled = true
default_probability = 0.03
mention_probability = 0.8
keyword_probability = 0.5
question_probability = 0.4
min_messages_between_replies = 15
max_replies_per_hour = 8

# 对话AI（必需）
[QvQChat.dialogue]
base_url = "https://api.openai.com/v1"
api_key = "sk-your-actual-api-key-here"
model = "gpt-4o"
temperature = 0.7
max_tokens = 500

# 意图识别AI（必需，会自动复用dialogue配置）
[QvQChat.intent]
api_key = ""  # 留空则使用dialogue配置
model = "gpt-3.5-turbo"
temperature = 0.1
max_tokens = 500

# 意图执行AI（必需，会自动复用dialogue配置）
[QvQChat.intent_execution]
api_key = ""
model = "gpt-3.5-turbo"
temperature = 0.3
max_tokens = 1000

# 记忆AI（可选，会自动复用dialogue配置）
[QvQChat.memory]
api_key = ""
model = "gpt-3.5-turbo"
temperature = 0.3
max_tokens = 1000

# 回复判断AI（可选，会自动复用dialogue配置）
[QvQChat.reply_judge]
api_key = ""
model = "gpt-3.5-turbo"
temperature = 0.1
max_tokens = 100

# 视觉AI（可选，会自动复用dialogue配置）
[QvQChat.vision]
api_key = ""
model = "gpt-4o"
temperature = 0.3
max_tokens = 300
```

### 运行时配置

运行时自动生成群和用户配置（无需手动配置）：

```toml
# 群配置
[QvQChat.groups."123456789"]
system_prompt = "这个群是技术交流群"
memory_mode = "mixed"  # mixed | sender_only
enable_memory = true
model_overrides = {}

# 用户配置
[QvQChat.users."user_id"]
style = "友好"
preferences = {}
```

## 使用示例

### 日常对话

```
用户：在吗？
AI：[不回复，保持安静]

用户：你觉得这个怎么样？
AI：我觉得挺好的。[偶尔回复，自然参与]

用户：@机器人 今天的天气怎么样？
AI：今天天气不错，适合出去玩。[被@时高概率回复]
```

### 记忆相关

```
用户：你记得我的生日吗？
AI：是的，我记得你的生日是6月15日。[记忆自然融入对话]

用户：记住这件事，我下周五要考试
AI：好的，我会记住你下周五要考试。[用户主动要求记忆]

用户：忘记这件事
AI：我会帮你删除相关记忆。
```

### 图片理解

```
用户：[发送图片] 这是什么？
AI：这是一张猫的照片，看起来很可爱。[dialogue AI直接理解图片]
```

### 系统操作

```
用户：清除会话
AI：好的，已清除当前会话历史。[intent_execution AI执行]

用户：把群提示词改成你是一个专业的技术顾问
AI：已将群提示词更新为：你是一个专业的技术顾问。

用户：群记忆模式改成sender_only
AI：已将群记忆模式更改为仅发送者模式。
```

## 故障排除

### 问题1：API错误 401 - Invalid token

**原因**: API密钥未配置或配置错误

**解决方法**:
1. 检查 `config.toml` 中 `[QvQChat.dialogue.api_key]` 是否已填入正确的API密钥
2. 确保API密钥格式为 `sk-...` 开头
3. 验证API密钥是否有效（访问 OpenAI 控制台检查）

### 问题2：所有AI均未配置API密钥

**原因**: 首次运行，未进行配置

**解决方法**:
1. 复制 `config.example.toml` 为 `config.toml`
2. 将其中的 `sk-your-api-key-here` 替换为实际API密钥
3. 配置 `bot_nicknames` 和 `bot_ids`
4. 重启程序

### 问题3：部分AI功能不可用

**原因**: 只配置了对话AI，其他AI未配置

**影响**:
- 仅对话AI配置: 基本对话功能正常，记忆会使用dialogue AI
- dialogue AI不支持视觉: 无法理解图片内容

**解决方法**: 为对应AI配置API密钥，或留空自动复用dialogue配置。

### 问题4：AI不回复任何消息

**可能原因**:
1. 窥屏模式概率过低（可调高 default_probability）
2. bot_ids/bot_nicknames 未正确配置
3. API密钥无效或过期

**检查方法**:
1. 查看日志中的AI判断结果
2. 确认机器人ID和昵称正确
3. 测试API连接

### 问题5：记忆不准确或过多

**解决方法**:
1. 调整记忆AI的temperature（降低会更严格）
2. 清理冗余记忆（通过意图执行删除）
3. 检查记忆提取标准（在handler._extract_and_save_memory中）

## 架构文档

详细的架构说明、组件设计和数据流请查看 [ARCHITECTURE.md](ARCHITECTURE.md)。

## 开发与贡献

欢迎参与 QvQChat 的开发！详细的贡献指南请查看 [ARCHITECTURE.md](ARCHITECTURE.md) 中的"贡献指南"章节。

### 快速开发设置

```bash
# 1. Fork 项目
git clone https://github.com/your-username/ErisPulse-AIChat.git
cd ErisPulse-AIChat

# 2. 安装依赖
pip install -e .

# 3. 运行测试
python -m ErisPulse-AIChat
```

### 核心组件

| 组件 | 文件 | 职责 |
|------|--------|------|
| Main | Core.py | 模块入口、事件处理、消息路由 |
| Config | config.py | 配置管理、配置继承 |
| AI Manager | ai_client.py | AI客户端管理、统一调用接口 |
| Intent | intent.py | 意图识别、意图路由 |
| Handler | handler.py | 意图处理、对话处理、记忆提取 |
| Memory | memory.py | 记忆管理、会话历史 |
| State | state.py | 状态管理、主题跟踪 |

## 依赖

- Python >= 3.9
- openai >= 1.0.0
- ErisPulse SDK

## 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 联系方式

- 作者：wsu2059q
- 邮箱：wsu2059@qq.com
- GitHub：https://github.com/wsu2059q/ErisPulse-AIChat
