# 背景
文件名：2025-11-20_1_ai_chat_plugin.md
创建于：2025-11-20_11:06:10
创建者：admin
主分支：main
任务分支：无（不创建分支）
Yolo模式：Off

# 任务描述
创建一个 AI 对话插件，支持多用户、多群聊的会话隔离，具备短期记忆功能（内存存储，无需持久化）。

## 核心需求
1. 基于 LlamaIndex + Ollama 的 AI 对话功能
2. **维护一个全局的会话历史**（不按用户/群聊分隔）
3. AI 能同时在不同群聊和不同用户对话
4. 历史消息包含时间戳、群聊ID、用户ID信息，AI 能分辨消息来源
5. 最大历史消息数量可配置（默认20条）
6. 不需要持久化，重启后会话清空
7. 提供清空全局历史会话的指令
8. **AI 能够 @ 用户**：使用 `<at user_id="{user_id}"></at>` 格式，禁止直接输出 user_id

## 指令入口
- `ai_chat`: 对话指令
- `ai_chat_clear`: 清空当前用户的会话历史

## 技术要点
- 参考 NewsReport.py 的架构模式
- 使用内存字典存储会话历史
- 模型使用 qwen3:0.6b
- 消息格式包含上下文信息（时间、群聊、用户）

# 项目概览
这是一个基于 PWF 框架的 WPS 机器人项目，使用插件化架构。
- 插件基类：WPSAPI → BasicWPSInterface → PluginInterface
- 每个插件通过 callback(message, chat_id, user_id) 处理消息
- 支持数据库、定时任务、路由等功能
- 已有多个游戏系统插件（菜园、战斗、炼金等）

# 分析
## 现有架构分析
1. **插件系统**：
   - 插件通过继承 WPSAPI 实现
   - callback 方法接收 message（已去除 command）、chat_id、user_id
   - 通过 register_plugin(command) 注册指令入口
   - 通过 dependencies() 声明依赖关系

2. **NewsReport.py 架构**：
   - NewsAIAgent 类：封装 AI 逻辑（LlamaIndex + Ollama）
   - NewsAIPlugin 类：继承 WPSAPI，作为插件入口
   - 使用 ProjectConfig().GetFile() 进行文件缓存

3. **会话管理需求**：
   - **全局单一会话历史**，不按用户/群聊分隔
   - 每条消息标记 chat_id（群聊ID）和 user_id（用户ID）
   - AI 能看到所有群聊、所有用户的对话历史
   - 使用 List[Dict] 存储全局消息列表
   - 内存存储，无需持久化

4. **配置系统**：
   - 使用 ProjectConfig.FindItem(key, default) 读取配置
   - 使用 ProjectConfig.SaveProperties() 保存配置
   - 配置存储在 Assets/config.json

## 技术选型
- **AI 框架**：LlamaIndex + Ollama
- **模型**：qwen3:0.6b
- **存储方式**：内存列表（List[Dict]）- 全局单一历史
- **消息格式**：包含 timestamp, chat_id, user_id, role, content

# 提议的解决方案
## 整体架构
```
ChatAI.py
├── ChatAIAgent (AI 智能体)
│   ├── 会话字典管理
│   ├── 消息历史维护
│   └── LLM 对话调用
├── ChatAIPlugin (对话插件)
│   ├── 注册 ai_chat 指令
│   └── 处理用户对话
└── ChatAIClearPlugin (清空历史插件)
    ├── 注册 ai_chat_clear 指令
    └── 清空会话历史
```

## 核心类设计
### 1. ChatAIAgent
- 单例模式，通过 Architecture 注册
- 维护 **全局消息历史**: List[Dict]
- 每条消息格式：
  ```python
  {
      "timestamp": "2025-11-20 11:06:10",
      "chat_id": 12345,
      "user_id": 67890,
      "role": "user" | "assistant",
      "content": "消息内容"
  }
  ```
- AI 能够看到所有群聊、所有用户的完整对话历史

### 2. ChatAIPlugin
- 继承 WPSAPI
- 依赖 WPSAPI
- 初始化时创建/获取 ChatAIAgent
- callback 处理用户消息，调用 Agent.chat()

### 3. ChatAIClearPlugin
- 继承 WPSAPI
- 依赖 ChatAIPlugin（确保 Agent 已初始化）
- callback 调用 Agent.clear_history() 清空全局历史

## 系统提示词设计
AI 需要理解的关键信息：
1. **多群聊、多用户环境**：能看到所有群聊和用户的对话历史
2. **消息格式**：每条消息包含 [时间] [群聊ID] [用户ID] 标记
3. **@ 用户格式**：AI 回复时，当需要特指或回复某个用户时，使用 `<at user_id="{user_id}"></at>`
4. **禁止行为**：禁止直接输出裸露的 user_id 数字

示例提示词：
```
你是一个友好的AI助手，能够同时在多个群聊中与不同用户对话。

重要规则：
- 你能看到所有群聊的对话历史，每条消息都标注了时间、群聊ID和用户ID
- 当你需要特指某个用户或专门回复某个用户时，必须在回复中使用以下格式：<at user_id="用户ID"></at>
- 禁止直接输出用户ID数字，始终使用 <at> 标签包裹
- 注意区分不同群聊和不同用户的对话上下文

示例对话：
[2025-11-20 10:00:00] [群聊#12345] [用户#67890]: 你好
AI回复: <at user_id="67890"></at> 你好！有什么可以帮助你的吗？

[2025-11-20 10:01:00] [群聊#12345] [用户#11111]: 今天天气怎么样？
AI回复: <at user_id="11111"></at> 抱歉，我无法获取实时天气信息。

[2025-11-20 10:02:00] [群聊#67890] [用户#22222]: 刚才12345群的用户说了什么？
AI回复: <at user_id="22222"></at> 刚才群聊12345中，用户67890问候了我，用户11111询问了天气。
```

## 消息流程
```
用户消息 (chat_id, user_id) → ChatAIPlugin.callback()
    ↓
获取当前时间
    ↓
添加用户消息到全局历史（带时间戳、chat_id、user_id）
    ↓
格式化全局历史消息为 LLM 输入
    ├─ 包含所有群聊、所有用户的历史
    ├─ 每条消息标注来源（群聊、用户、时间）
    └─ AI 能理解跨群聊、跨用户的上下文
    ↓
调用 Ollama LLM（使用包含 @ 格式说明的系统提示词）
    ↓
添加 AI 回复到全局历史（标注当前 chat_id, user_id）
    ↓
返回格式化的回复
```

# 当前执行步骤："1. 创建任务文件"

# 任务进度
[2025-11-20_11:06:10]
- 已创建：.tasks/2025-11-20_1_ai_chat_plugin.md
- 更改：创建任务文件，记录任务背景和设计方案
- 原因：按照 RIPER-5 协议要求，在进入 EXECUTE 模式前创建任务文件
- 阻碍因素：无
- 状态：成功

[2025-11-20_11:13:25]
- 已修改：.tasks/2025-11-20_1_ai_chat_plugin.md
- 更改：
  1. 更新核心需求，明确全局单一会话历史设计
  2. 添加系统提示词设计章节
  3. 说明 @ 用户格式：<at user_id="{user_id}"></at>
  4. 禁止直接输出 user_id
- 原因：根据用户反馈，澄清架构设计（全局历史 vs 分用户历史）
- 阻碍因素：无
- 状态：成功

[2025-11-20_11:16:49]
- 已修改：.tasks/2025-11-20_1_ai_chat_plugin.md
- 更改：修正系统提示词设计，明确用户消息是普通文本，只有 AI 回复时才使用 <at> 格式
- 原因：用户澄清 @ 用户格式只用于 AI 回复，不用于用户消息
- 阻碍因素：无
- 状态：成功

[2025-11-20_11:22:38]
- 已创建：Plugins/Others/ChatAI.py
- 更改：完整实现 AI 对话插件系统
  1. ChatAIAgent 类：全局会话管理、消息历史维护、LLM 对话
  2. ChatAIPlugin 类：注册 ai_chat 指令，处理用户对话
  3. ChatAIClearPlugin 类：注册 ai_chat_clear 指令，清空历史
  4. 使用 qwen3:0.6b 模型
  5. 最大历史消息数量可配置（默认20）
  6. 系统提示词包含 @ 用户格式说明
  7. 全局单一会话历史设计
- 原因：实施 EXECUTE 模式清单项 1-28
- 阻碍因素：无
- 状态：成功

[2025-11-20_11:29:24]
- 已修改：Plugins/Others/ChatAI.py
- 更改：修复 AI 重复用户消息的问题
  1. 从 acomplete（文本补全）改为 achat（对话）方法
  2. 使用 ChatMessage 结构化消息格式
  3. 分离系统提示词和对话历史
  4. 优化提示词结构，更清晰地指示 AI 回复
  5. 添加 llama_index.core.llms.ChatMessage 导入
- 原因：用户反馈 AI 一直重复用户说的话
- 阻碍因素：无
- 状态：未确认

# 最终审查
待完成