AmyAlmond 是一个基于 LLM API 的智能聊天机器人，旨在无缝集成到 QQ 群聊、频道中。

通过利用LLM API，AmyAlmond 提供上下文感知的智能回复，增强用户互动体验，并支持长期记忆管理。无论是自动化回复还是提升用户参与度，她都能够轻松处理复杂的对话场景。

• 🌈 她使用LLM API，根据对话上下文生成类似人类的回复，且Prompt可定制。
• 💗 她使用QQ官方 Python SDK，再也不怕被封锁。
• 🔥 她会自动识别并记住用户姓名，提供个性化的互动体验。
• 🧠 她拥有长期和短期记忆能力，能够记录并引用重要信息，保障对话的延续性。
• 🐳 支持管理员通过特定命令控制机器人的行为。
• ⭐ 全配置支持热更新，减少重启次数，提高效率。
• 🪝 日志、代码注释详细，方便调试和监控。

• 🧠
• Python 3.8 及以上版本
• 任意一个大模型API的API地址和密钥
• Linux, macOS 或 Windows

1. 克隆仓库
   拉取项目代码:

   git clone https://github.com/shuakami/amyalmond_bot.git
   cd amyalmond_bot

   你也可以点击仓库的 Code 按钮，选择 Download ZIP 下载并解压项目。

2. 安装依赖
   安装所需的 Python 依赖：

   pip install -r requirements.txt

3. 配置文件
   在 configs/ 目录下创建 config.yaml 文件，并填写以下内容：

   appid: "你的QQ机器人开发AppID"
   secret: "你的QQ机器人开发AppSecret"
   openai_secret: "Openai API密钥（你也可以使用其他的服务商）"
   openai_model: "gpt-4o-mini"
   openai_api_url: "Openai API地址（你也可以使用其他的服务商）"
   admin_id: "你的识别码"

   如果不会配置，请查看配置教程

4. 启动机器人
   运行以下命令启动机器人：

   python main.py

启动后，AmyAlmond 会自动连接到指定的群聊并开始工作，你可以配置QQ开发平台的沙箱或是公开发布后拉入对应群聊。

用户可以通过@机器人来触发对话，并获得基于上下文的智能回复。

• @你的机器人 restart: 重启机器人，重新加载所有配置和数据（2-4s）。
• @你的机器人 reload: 热加载配置文件，无需重启即可应用最新的配置更改（1-2s）。

如果不生效，请先确保你配置了admin_id

• 用户识别
  当用户首次@机器人时，AmyAlmond 会提示用户输入昵称，并将其记录在data/user_names.json数据表中，确保在后续对话中能够识别并使用该昵称。

• 上下文管理
  机器人会自动保存对话上下文，并针对当前对话生成最合适的响应。也会自动压缩上下文组合发送，尽量减少token。

• 长期记忆处理
  机器人能够记录并在适当时机引用长期记忆中的信息。建议您在configs/system-prompt.txt中加入

  * 你拥有内置工具。可以使用 <get memory> 获取你之前的记忆，你必须在有你认为重要的记忆时使用 <memory>内容</memory> 存储记忆。
  

  以达到最佳效果。

所有日志记录在 logs 文件夹中，包含了机器人运行过程中的详细信息，便于调试和监控。

QQ 机器人需要通过 QQ 开发者平台进行注册和配置，以便获取 AppID 和 AppSecret。以下是详细步骤：

1. 注册 QQ 开发者账号

   • 访问 QQ 开发者平台，并使用您的 QQ 账号进行登录。
   • 若您没有开发者账号，请按照提示完成开发者认证。

2. 创建应用

   • 登录后，点击右上角的 “管理中心”，进入应用管理页面。
   • 点击 “创建应用” 按钮。
   • 选择 “QQ 机器人” 类型的应用，并填写必要的应用信息，如应用名称、应用描述等。
   • 创建成功后，系统将为您的应用生成一个唯一的 AppID 和 AppSecret。

3. 获取 AppID 和 AppSecret

   • 在应用管理页面，点击您刚刚创建的应用。
   • 在应用的 “基本信息” 页面下，您可以看到应用的 AppID 和 AppSecret。
   • 请将这两个值复制到 config.yaml 文件中的对应位置。

如果您选择使用 OpenAI 的 GPT 模型作为机器人的核心对话引擎，您需要获取 OpenAI 的 API 密钥和 API 地址。以下是详细步骤：

1. 注册 OpenAI 账号

   • 国内可以使用openai-hk，无需科学上网配置完全兼容。
   • 如果你的网络环境没问题，访问 OpenAI 官网并注册一个账号。
   • 如果您已经有账号，直接 登录OpenAI。

2. 创建 API 密钥

   • 登录后，访问 API 密钥页面。
   • 点击 “Create new secret key” 按钮，生成一个新的 API 密钥。
   • 将生成的密钥复制并妥善保存，因为它只会显示一次。

3. 获取 API 地址

   • OpenAI 的默认 API 地址为 https://api.openai.com/v1/chat/completions
   • 如果您使用其他服务商的 API，请根据服务商提供的文档找到相应的 API 地址。

4. 填写配置文件

   • 将生成的 API 密钥填入 config.yaml 文件中的 openai_secret 字段。
   • 将 API 地址填入 config.yaml 文件中的 openai_api_url 字段。

管理员识别码通常是您的的账号在PythonSDK的识别码，用于在机器人中执行管理员命令。

获取您的 QQ 识别码

• 确保你配置好的其他的内容。然后运行机器人。
• 在群组中，@机器人 并发送随意一条消息
• 查看控制台中你发送的消息对应的你的识别码（如484294135BF695D**************）

[INFO]	(main.py:155)on_group_at_message_create	Received message: ' HI' from user: 消息来自未知用户：(484294135BF695D**************) in group: 2D17A7F4842C08B33**********

• 把识别码填入 config.yaml 文件中的 admin_id 字段。

在 configs/ 目录下创建一个名为 config.yaml 的文件，并按照以下格式填写内容：

appid: "你的QQ机器人开发AppID"
secret: "你的QQ机器人开发AppSecret"
openai_secret: "Openai API密钥（你也可以使用其他的服务商）"
openai_model: "gpt-4o-mini"
openai_api_url: "Openai API地址（你也可以使用其他的服务商）"
admin_id: "你的识别码"

appid: "1234567890abcdef"
secret: "abcdef1234567890abcdef1234567890"
openai_secret: "sk-abcdef1234567890abcdef1234567890"
openai_model: "gpt-4o-mini"
openai_api_url: "https://api.openai.com/v1/chat/completions"
admin_id: "4842941B3A42C08B331CEB3DD464"

配置完成后，通过以下步骤验证配置是否正确：

1. 检查 YAML 语法

   • 确保 config.yaml 文件的格式和缩进正确。YAML 对缩进非常敏感，错误的缩进会导致配置文件解析失败。

2. 启动机器人

   • 使用以下命令启动机器人：

     python main.py

   • 启动过程中，机器人将尝试连接到 QQ 和 OpenAI API。如果配置正确，您将在控制台看到机器人成功启动的提示。

3. 检查日志

   • 启动机器人后，如果出现连接问题或其他错误，请检查 logs 文件夹中的日志文件。日志文件记录了详细的错误信息，帮助您定位问题。

• 配置后机器人无反应

  • 确保 appid 和 secret 填写正确，且您的应用在 QQ 开发者平台已启用。
  • 检查您在 QQ 开发者平台中是否为应用分配了正确的权限。

• 机器人无法连接到 OpenAI API

  • 检查 openai_secret 和 openai_api_url 是否填写正确。
  • 确保 API 密钥有效且没有超出使用限制。您可以在 OpenAI 控制台 查看使用情况。

• 管理员命令无效

  • 请先确保 admin_id 填写正确，并且您使用的 QQ 号码与配置中的管理员识别码一致。

• 如何切换到其他 LLM 供应商

  • 如果您不想使用 OpenAI，可以将 openai_api_url 和 openai_secret 替换为其他 LLM 供应商的 API 地址和密钥。具体的配置方法请参考对应供应商的文档。

graph TD;
    %% 用户与MyClient的交互
    A[用户] -->|发送消息| B[MyClient]

    %% MyClient的子模块
    B -->|解析消息| C[消息处理模块]
    C -->|检查管理员身份| D[管理员命令处理模块]
    C -->|用户管理| E[用户管理模块]
    C -->|生成回复| F[对话系统模块]
    F -->|获取记忆| G[记忆系统模块]
    F -->|调用API| H[OpenAI API模块]
    G -->|读取/写入| I[长期记忆文件long_term_memory_<X>.txt]
    G -->|读取/写入| J[短期记忆文件memory.json]
    H -->|返回回复| F
    F -->|生成回复| K[消息响应模块]
    K -->|发送回复| A

    %% 文件系统与配置
    subgraph 文件系统与配置
    E1[config.yaml]
    E2[system-prompt.txt]
    F1[botpy.log]
    G1[user_names.json]
    I
    J
    end

    %% 子模块与文件系统的交互
    E -->|加载/保存用户昵称| G1
    F -->|加载配置| E1
    F -->|加载系统提示词| E2
    K -->|记录日志| F1

    %% 详细说明
    classDef module fill:#f96,stroke:#333,stroke-width:2px;
    class B,C,D,E,F,G,H,K module;

+-------------------------------------------------------------------+
|                              用户                                 |
|                    (通过 QQ 群聊与机器人交互)                     |
+-------------------------------------------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|                            MyClient                               |
|                   (主程序，通过 botpy 框架与 QQ 平台交互)          |
|-------------------------------------------------------------------|
|  1. 消息处理: 解析用户消息，识别消息类型，并调用相应模块处理。      |
|  2. 用户管理: 记录和管理用户信息，如昵称映射。                    |
|  3. 对话系统: 生成基于上下文的智能回复，调用OpenAI API。          |
|  4. 记忆系统: 管理短期和长期记忆，保证对话的连续性和智能性。       |
|  5. 管理员命令处理: 识别和执行管理员命令，如重启、热加载配置等。   |
+-------------------------------------------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|                           消息处理模块                            |
|-------------------------------------------------------------------|
|  1. 接收和解析消息，判断是否为管理员命令或普通用户消息。          |
|  2. 调用相应模块处理消息（如管理员命令处理、对话系统等）。        |
+-------------------------------------------------------------------+
|       |                           |                             |
|       v                           v                             v
| +-------------------+   +--------------------+   +--------------------+|
| | 用户管理模块       |   | 对话系统模块       |   | 管理员命令处理模块  ||
| |-------------------|   |--------------------|   |--------------------||
| | 1. 加载用户昵称映射 |   | 1. 生成智能回复    |   | 1. 识别管理员身份  ||
| | 2. 保存新用户昵称   |   | 2. 调用OpenAI API  |   | 2. 执行管理员命令  ||
| | (使用user_names.json)|   | 3. 整合记忆系统   |   |                    ||
| +-------------------+   +--------------------+   +--------------------+|
|                                  |                             |
|                                  v                             v
| +-------------------+   +--------------------+   +--------------------+|
| | 记忆系统模块       |   | OpenAI API模块     |   | 配置管理模块         ||
| |-------------------|   |--------------------|   |--------------------||
| | 1. 管理短期记忆    |   | 1. 接收对话上下文  |   | 1. 加载配置文件     ||
| | 2. 管理长期记忆    |   | 2. 生成对话回复    |   | 2. 监控配置文件变化 ||
| | 3. 压缩记忆内容    |   | 3. 返回生成回复    |   | (使用watchdog监控)  ||
| | (使用memory.json,  |   +--------------------+   +--------------------+|
| | long_term_memory_<X>.txt)|                                        |
+-------------------------------------------------------------------+
                                  |
                                  v
+-------------------------------------------------------------------+
|                          消息响应模块                             |
|-------------------------------------------------------------------|
|  1. 组合生成的回复，发送回群聊。                                  |
|  2. 记录处理结果到日志文件 (botpy.log 中)。                         |
+-------------------------------------------------------------------+

amyalmond_bot/
├── main.py                    # 主程序
├── configs/                   # 配置文件目录
│   ├── config.yaml            # 主配置文件
│   ├── system-prompt.txt      # 系统提示词
├── data/                      # 数据存储目录
│   ├── memory.json            # 当前对话的短期记忆数据
│   ├── long_term_memory_<X>.txt # 每个群聊的长期记忆文件，<X>为群聊ID
│   ├── user_names.json        # 用户名映射表，记录用户识别码和昵称的关系
├── logs/                      # 日志目录
│   ├── botpy.log                # 机器人运行日志
├── requirements.txt           # Python依赖包列表
└── README.md                  # 项目说明文档

1. 用户 (A):

   • 用户通过 QQ 群聊发送消息，触发机器人的响应。

2. MyClient (B):

   • 功能: 主程序客户端，作为核心控制器，通过 botpy 库与 QQ 平台交互。它负责管理消息接收、处理和回复。
   • 子模块:
     • 消息处理模块 (C): 解析用户消息，并调用相应模块处理。
     • 管理员命令处理模块 (D): 识别并执行管理员的特定命令，如重启或热加载配置。
     • 用户管理模块 (E): 维护用户信息，如昵称映射，使用 user_names.json 文件。
     • 对话系统模块 (F): 根据上下文生成回复，调用 OpenAI API 并整合记忆系统。
     • 记忆系统模块 (G): 维护短期和长期记忆，使用 memory.json 和 long_term_memory_<X>.txt 文件。
     • OpenAI API模块 (H): 调用 OpenAI 的 GPT 模型生成对话回复。
     • 消息响应模块 (K): 组合生成的回复，并通过 QQ 平台发送回群聊。

3. 消息处理模块 (C):

   • 功能: 解析接收到的消息，判断消息的类型（如管理员命令或普通用户消息），并根据类型调用相应的处理模块。

4. 管理员命令处理模块 (D):

   • 功能: 识别管理员身份，并执行特定命令。
   • 常见命令:
     • restart: 重启机器人。
     • reload: 热加载配置文件。
   • 文件依赖: config.yaml 中的 admin_id。

5. 用户管理模块 (E):

   • 功能: 维护用户ID与昵称的映射，支持新用户的注册和记录。
   • 文件依赖: user_names.json。

6. 对话系统模块 (F):

   • 功能: 生成基于上下文的智能回复，调用OpenAI API。
   • 子功能:
     • 生成输入: 将用户输入与上下文结合。
     • 调用API: 通过OpenAI API生成回复。
     • 整合记忆: 调用记忆系统，引用或更新记忆内容。
   • 文件依赖:
     • 配置加载: 从 config.yaml 加载配置信息。
     • 系统提示词: 从 system-prompt.txt 加载系统提示词。

7. 记忆系统模块 (G):

   • 功能:
     • 短期记忆: 记录当前对话的上下文，保证连续性。
     • 长期记忆: 记录重要信息，长期保存。
     • 压缩记忆: 避免记忆占用过多资源。
   • 文件依赖: memory.json, long_term_memory_<X>.txt。

8. OpenAI API模块 (H):

   • 功能: 处理对话上下文，生成符合上下文的智能回复。

9. 消息响应模块 (K):

   • 功能: 组合生成的回复并发送回群聊，同时记录处理日志。
   • 文件依赖: botpy.log。

• config.yaml:

  • 功能: 定义机器人运行的关键配置参数，如API密钥、模型名称、管理员ID等。
  • 示例内容:

    appid: "你的QQ机器人开发AppID"
    secret: "你的QQ机器人开发AppSecret"
    openai_secret: "Openai API密钥"
    openai_model: "gpt-4o-mini"
    openai_api_url: "https://api.openai.com/v1/chat/completions"
    admin_id: "你的识别码"

• system-prompt.txt:

  • 功能: 定义系统提示词，用于初始化对话上下文。影响机器人对话的初始行为和回复风格。

• memory.json:

  • 功能: 存储当前对话的短期记忆。使用短期记忆维持对话连续性。

• long_term_memory_.txt:

  • 功能: 存储每个群聊的长期记忆。保持对群聊中重要信息的长期记忆，<X> 为群聊ID。

• user_names.json:

  • 功能: 记录用户ID与昵称的映射关系。用于识别用户，并在对话中使用用户昵称进行个性化回复。

• botpy.log:

  • 功能: 记录机器人运行时的日志信息，包括接收到的消息、处理结果、错误信息等。便于调试和监控机器人的运行状态。

我们非常欢迎您。无论是提供新功能、修复问题，还是改进文档，都可以~

我们采用 Git Flow 分支管理模型：

• main: 主分支，始终保持稳定可用的版本。
• develop: 开发分支，所有新功能在此分支上集成。
• feature/: 功能分支，从 develop 分支分出，开发完成后合并回 develop。
• hotfix/: 修复分支，用于修复紧急问题，完成后合并回 main 和 develop。

1. Fork 本仓库
   在您的 GitHub 账户中 fork 本项目。

2. 创建分支
   为您的改动创建一个新的功能分支：

   git checkout -b feature/AmazingFeature

3. 提交更改
   提交您的代码，并确保提交信息简洁明了：

   git commit -m 'Add some AmazingFeature'

4. 推送到分支
   推送分支到 GitHub：

   git push origin feature/AmazingFeature

5. 创建 Pull Request
   在 GitHub 上创建一个 Pull Request，描述您的更改内容及其影响。

• long_term_memory_X.txt存放位置错误（Patch_III_11）
• 指令性重启出现问题（Patch_II_12）

AmyAlmond 遵循 MPL2 许可证。您可以自由使用、修改和分发本项目，但在分发修改后的版本时，您需要开放源代码并保留原作者的版权声明。

本项目仅供学习和研究使用，开发者不对任何因使用本项目而导致的后果负责。在使用本项目时，请确保遵守相关法律法规，并尊重他人的知识产权。

我们正在积极开发和扩展 AmyAlmond 聊天机器人的功能。

以下是我们计划在未来版本中添加的一些功能。您也可以通过提交 issue 来建议新功能或改进现有功能。

[NEW] 重构分离，模块化设计

• 预期版本: v1.1.0
• 开始时间: 2024/8/16
• 预计结束时间: 2024/10/?
• 进度: 新建文件夹...
• 描述: 开始重构项目以支持模块化设计，提高可维护性。