AstrBot 主动回复插件(心念)

一个支持聊天增强、时间感知和智能主动对话的 AstrBot 插件。

功能特性

聊天附带用户信息

• 自动在 AI 对话中附加用户信息（用户名、用户ID）
• 自动附加当前时间信息
• 支持自定义时间格式
• 支持自定义信息模板
• 智能追加：不会覆盖现有人格设置，而是追加到系统提示末尾

智能主动对话系统

• 基于LLM的智能生成：通过LLM生成个性化主动消息，不使用预设模板
• 人格系统兼容：自动检测并组合AstrBot人格设置与主动对话指令
• 多样化对话风格：支持多个主动对话提示词，随机选择不同的对话风格
• 上下文感知：基于用户信息和对话历史生成更自然的主动消息
• 混合计时器模式：预计算下次发送时间 + 智能睡眠，精确控制发送时机
  • 可在 /proactive status 中查看各会话的下次发送时间
  • AI 发消息后自动刷新计时器，避免频繁打扰
• 历史记录功能增强：支持基于对话历史的智能主动消息生成
  • 历史记录开关配置，可选择是否附带历史记录
  • 可配置历史记录条数（默认10条，建议5-20条）
  • AI生成主动消息时会参考之前的对话历史，生成更加拟人和连贯的主动消息
  • 使用AstrBot官方API安全地获取聊天记录
  • 添加简洁的上下文说明，不干扰主动对话提示词的主导作用
• 对话历史记录：AI主动发送的消息会自动添加到对话历史中
  • 解决了上下文断裂问题，用户下次发消息时AI能看到完整对话
  • 支持多种保存方式，确保历史记录的可靠性
• 支持两种时间模式：
  • 固定间隔模式：固定时间间隔，可选随机延迟
  • 随机间隔模式：每次在设定范围内随机选择等待时间（如1分钟到1小时随机）
• 睡眠时间设置：睡眠时间内不发送主动消息，且附加睡眠提示到系统提示词
  • 支持三种睡眠结束处理模式：跳过、立即发送、延后发送
  • 延后发送模式会恢复睡眠前的剩余计时，保持自然间隔
• 支持多会话管理
• 可视化配置管理：提示词和会话列表支持单独添加、编辑、删除

时间感知增强

• 时间感知提示词：可配置指导AI正确处理时间表述的规则
• 睡眠时间感知：睡眠时间内用户发消息时，附加睡眠提示到系统提示词
• 智能时间表达：引导AI使用自然口语描述时间，避免机械式报时

安装方法

1. 将插件文件放置到 AstrBot 的 data/plugins/astrbot_proactive_reply/ 目录下
2. 重启 AstrBot 或在管理面板中重载插件
3. 在管理面板的插件管理中配置相关参数

配置文件位置

• 插件配置文件：data/config/astrbot_proactive_reply_config.json
• 配置模式文件：data/plugins/astrbot_proactive_reply/_conf_schema.json
• 持久化数据文件：data/astrbot_proactive_reply/persistent_data.json

提示：

• 推荐通过 AstrBot 管理面板进行配置，会自动生成和保存配置文件
• 如需手动编辑配置，请参考 _conf_schema.json 中的配置结构
• 配置修改后需要重载插件才能生效

配置说明

用户信息附加设置

• 时间格式：时间显示格式（Python datetime 格式）
• 信息模板：用户信息的显示模板，支持占位符。会追加到现有系统提示末尾，不会覆盖人格设置
  • 支持的占位符：{username}, {user_id}, {time}, {current_time}, {platform}, {chat_type}, {user_last_message_time}, {user_last_message_time_ago}, {ai_last_sent_time}

智能主动对话设置

• 启用功能：是否启用智能主动对话功能
• 主动对话默认人格：当没有AstrBot人格时使用的默认人格设定
• 主动对话提示词列表：多个提示词选项，系统会随机选择一个来指导LLM生成主动消息
  • 支持可视化列表管理，每个提示词可单独添加、编辑、删除
  • 支持 {user_context} 占位符来插入用户信息
• 历史记录功能：
  • 是否附带历史记录：启用后，AI生成主动消息时会参考之前的对话历史
  • 附带的历史记录条数：控制获取最近多少条对话记录作为上下文（默认10条，建议5-20条）
• 时间模式：选择时间模式
  • fixed_interval：固定间隔模式（传统模式）
  • random_interval：随机间隔模式（新增）
• 固定间隔模式设置：
  • 发送间隔：每隔多少分钟发送一次消息
  • 随机延迟：在基础间隔上增加随机延迟时间
  • 延迟范围：随机延迟的最小和最大值
• 随机间隔模式设置：
  • 最小间隔：随机间隔的最小时间（分钟）
  • 最大间隔：随机间隔的最大时间（分钟）
• 目标会话列表：需要发送消息的会话ID列表
  • 支持可视化列表管理，每个会话ID可单独添加、编辑、删除

时间感知设置

• 时间感知增强提示词：启用后，会在系统提示中添加时间信息使用指南，指导AI正确处理时间相关的表述
  • 自定义提示词：可配置指导AI如何理解和表达时间的规则（模糊化表达、状态映射、间隔感知等）
• 睡眠时间功能：
  • 启用开关：启用后在睡眠时间段内不发送主动消息
  • 睡眠时间段：在指定时间段内不发送消息，支持跨午夜（如 22:00-8:00）
  • 睡眠提示内容：在睡眠时间段内附加到系统提示词，让AI感知当前处于睡眠时间
  • 睡眠结束时发送消息：启用后可选择睡眠结束时的处理方式
  • 睡眠结束发送模式：
    • immediate：立即发送（计时器过期则马上发送）
    • delayed：延后发送（恢复睡眠前的剩余计时，保持自然间隔）

消息分割设置

插件支持将LLM生成的长消息按特定分隔符分割成多条消息发送,模拟更自然的对话节奏。

基础配置

• 启用消息分割：是否启用消息分割功能(默认启用)
• 分割模式：选择消息分割的方式,提供6种模式
• 自定义分割正则表达式：仅当分割模式为custom时使用
• 分割消息延迟：分割后的消息之间的发送延迟,单位毫秒(默认500ms)

分割模式说明

Web界面配置方法

1. 使用预设模式(推荐):

   • 在"分割模式"下拉菜单中选择一个预设模式
   • 无需填写"自定义分割正则表达式"
   • 点击保存并重启插件

2. 使用自定义正则表达式:

   • 将"分割模式"设置为 custom
   • 在"自定义分割正则表达式"输入框填写正则表达式
   • 参考下方填写指南

自定义正则表达式填写指南

常用示例(在Web界面中):

转义规则:

• 反斜线字符: 填写 \\ (两个反斜线)
• 换行符: 填写 \n
• 特殊字符 [, ], (, ) 等在正则中有特殊含义,如需按字面意思使用需要转义

推荐做法:

1. 优先使用预设模式,无需了解正则表达式
2. 只在需要特殊分割规则时使用custom模式
3. 从简单的表达式开始测试,如 。 或 [,;]

注意事项:

• 填写错误的正则表达式会导致插件自动降级到backslash模式
• 查看日志可以确认分割模式是否生效
• 使用 /proactive test basic 命令测试分割效果

使用指南

指令说明

插件提供了9个主要指令，按功能分组：

核心功能指令（6个）

/proactive help            # 显示帮助信息
/proactive status          # 查看插件状态和当前会话信息
/proactive config          # 显示完整的插件配置信息
/proactive add_session     # 将当前会话添加到主动对话列表
/proactive remove_session  # 将当前会话从主动对话列表移除
/proactive restart         # 重启定时任务（配置更改后必须使用）

测试功能指令（1个指令，7种功能）

/proactive test [type]     # 统一测试指令（不带参数显示帮助）
  • test basic             # 基础测试发送
  • test llm               # 测试LLM请求，体验用户信息附加功能
  • test generation        # 测试LLM生成主动消息功能
  • test prompt            # 测试系统提示词构建过程（包含历史记录）
  • test placeholders      # 测试占位符替换功能
  • test history           # 测试对话历史记录功能
  • test save              # 测试对话保存功能

显示功能指令（1个指令，2种功能）

/proactive show [type]     # 统一显示指令
  • show prompt            # 显示当前配置下会输入给LLM的组合话术
  • show users             # 显示记录的用户信息

管理功能指令（1个指令，8种操作）

/proactive manage [action] # 统一管理指令
  基础管理操作：
  • manage clear           # 清除记录的用户信息和发送时间
  • manage task_status     # 检查定时任务状态
  • manage force_stop      # 强制停止所有定时任务
  • manage force_start     # 强制启动定时任务
  • manage save_config     # 强制保存配置文件

  故障排查操作：
  • manage debug_info      # 调试用户信息（查看AI收到的信息）
  • manage debug_send      # 调试发送功能（检查LLM生成过程）
  • manage debug_times     # 调试时间记录（查看发送时间记录）

快速开始

1. 配置用户信息模板：

   • 用户信息功能始终启用
   • 在管理面板中自定义信息模板
   • 通过模板控制显示哪些信息（用户名、ID、时间等）

2. 设置智能主动对话：

   • 在管理面板中启用"智能主动对话功能"
   • 配置主动对话默认人格（当无AstrBot人格时使用）
   • 配置主动对话提示词列表（可添加多个不同风格的提示词）
   • 选择时间模式：
     • 固定间隔模式：设置固定间隔时间，可选随机延迟
     • 随机间隔模式：设置最小和最大间隔时间，每次随机选择
   • 设置睡眠时间段（如 22:00-8:00，支持跨午夜）
   • 使用 /proactive status 查看当前会话状态
   • 使用 /proactive add_session 添加当前会话到主动对话列表

3. 测试功能：

   • 使用 /proactive manage debug_info 查看AI收到的用户信息
   • 使用 /proactive test llm 实际测试用户信息附加功能
   • 使用 /proactive test generation 测试LLM生成主动消息
   • 使用 /proactive test prompt 查看系统提示词构建过程（包含历史记录）
   • 使用 /proactive test basic 测试主动消息发送
   • 使用 /proactive status 查看插件状态

配置示例

用户信息模板示例

默认模板（推荐）：

[对话信息] 用户：{username}，时间：{time}

详细信息模板：

[对话信息] 用户：{username}（ID：{user_id}），时间：{time}，平台：{platform}（{chat_type}）

最简模板（只显示用户名）：

用户：{username}

重要提示：

• 用户信息会追加到现有系统提示的末尾，不会覆盖您设置的人格
• 建议保持模板简洁，避免与人格设置产生冲突
• 不想显示某项信息？直接从模板中删除对应的占位符即可！

主动对话提示词示例

基础提示词列表：

主动问候用户，询问近况
分享有趣话题，发起轻松对话
关心用户情况，温暖问候
友好交流，分享今日想法
轻松聊天，询问用户心情

详细提示词示例：

现在你要主动向用户发起对话，就像一个朋友在问候一样。请生成一条简短（1-2句话）、自然、有趣的主动问候消息
请主动和用户聊天，询问他们的近况或分享一些有趣的话题，保持轻松友好的语调
作为朋友，请主动关心一下用户最近的情况，发起一个温暖的对话
请以轻松友好的方式主动和用户交流，可以分享一些有趣的内容或询问用户的想法

使用占位符的提示词示例：

现在是 {current_time}，用户 {username} 上次发消息是在 {user_last_message_time}，请主动问候用户
{username} 在 {platform} 上已经有一段时间没有活跃了，上次发消息是 {user_last_message_time_ago}，请友好地询问近况
用户 {username} 在 {chat_type} 中，{user_last_message_time_ago} 发过消息，请生成一条温暖的问候消息
根据以下用户信息主动发起对话：{user_context}
用户 {username} {user_last_message_time_ago} 活跃过，现在是 {current_time}，请主动关心一下

主动对话提示词支持的占位符：

• {user_context} - 完整的用户上下文信息（包含用户名、平台、时间等）
• {user_last_message_time} - 用户上次主动发送消息的时间
• {user_last_message_time_ago} - 用户上次主动发送消息的相对时间（如"5分钟前"、"1小时前"）
• {username} - 用户昵称
• {platform} - 平台名称（如：aiocqhttp、telegram等）
• {chat_type} - 聊天类型（群聊/私聊）
• {ai_last_sent_time} - AI上次发送消息的时间
• {current_time} - 当前时间

用户信息模板支持的占位符：

• {username} - 用户名
• {user_id} - 用户ID
• {time} - 消息时间
• {current_time} - 当前时间
• {platform} - 平台名
• {chat_type} - 聊天类型（群聊/私聊）
• {user_last_message_time} - 用户上次发消息时间
• {user_last_message_time_ago} - 相对时间（如"5分钟前"）
• {ai_last_sent_time} - AI上次发送时间

时间模式配置示例

固定间隔模式：

{
  "timing_mode": "fixed_interval",
  "interval_minutes": 600,
  "random_delay_enabled": true,
  "min_random_minutes": 0,
  "max_random_minutes": 30
}

• 每600分钟（10小时）发送一次，额外随机延迟0-30分钟
• 实际间隔：600-630分钟（10-10.5小时）

随机间隔模式：

{
  "timing_mode": "random_interval",
  "random_min_minutes": 600,
  "random_max_minutes": 1200
}

• 每次在600-1200分钟（10-20小时）之间随机选择等待时间
• 更自然的发送节奏，模拟真实用户行为

测试指南

如何测试用户信息附加功能

1. 查看调试信息：

   /proactive manage debug_info
   

   这个指令会显示：

   • 当前用户的原始信息（昵称、ID等）
   • 插件配置状态
   • AI将收到的完整用户信息

2. 实际测试LLM请求：

   /proactive test llm
   

   这个指令会：

   • 发送一个测试消息给AI
   • 自动附加用户信息
   • 让您直接体验功能效果

3. 查看日志：
   在AstrBot日志中查看详细的用户信息添加过程

如何测试智能主动对话功能

1. 查看当前会话状态：

   /proactive status
   

   会显示当前会话是否在主动对话列表中

2. 添加当前会话：

   /proactive add_session
   

3. 测试LLM生成：

   /proactive test generation
   

4. 预览主动对话提示词列表：

   /proactive show prompt
   

   这个指令会显示已配置的主动对话提示词列表

5. 测试系统提示词构建：

   /proactive test prompt
   

   包含历史记录处理的完整测试

6. 测试立即发送：

   /proactive test basic
   

7. 调试发送过程：

   /proactive manage debug_send
   

8. 查看状态：

   /proactive status
   

   现在会显示历史记录功能的启用状态和配置信息

与 AstrBot 系统的兼容性

人格系统深度集成

• 智能人格检测：自动检测当前会话使用的AstrBot人格设置
• 人格组合机制：将AstrBot人格提示词与主动对话指令智能组合
• 默认人格支持：当无AstrBot人格时，使用配置的主动对话默认人格
• 用户信息追加：用户信息追加到系统提示末尾，保持现有人格完整性
• 支持所有人格：无论使用默认人格还是自定义人格，都能正常工作

对话管理兼容

• 保持对话连续性：不影响 AstrBot 的对话管理功能
• 支持多会话：每个会话的用户信息独立处理
• 历史记录完整：不影响对话历史的存储和检索

技术特性

• 完全符合 AstrBot 插件开发规范
• 使用官方 API，无任何非标准功能
• 支持异步处理和错误恢复
• 完整的日志记录和调试功能
• 优雅的资源清理
• 人格系统深度集成：自动检测并组合AstrBot人格与主动对话指令
• 智能LLM调用：使用底层LLM API生成个性化主动消息
• 多格式配置解析：支持列表、JSON、传统换行格式的自动识别
• 可视化配置管理：支持现代化的列表配置界面

开发信息

• 作者：AstraSolis
• 许可证：LICENSE
• 项目地址：https://github.com/AstraSolis/astrbot_proactive_reply

常见问题

Q: 为什么重启AstrBot后主动发送功能停止了？

A: 插件会在启动时自动根据配置启动定时任务。如果功能未正常启动，请检查：

1. 配置中的"启用功能"是否为 true
2. 使用 /proactive status 查看当前状态
3. 如仍有问题，使用 /proactive restart 手动重启定时任务

Q: 为什么重启后用户信息丢失了？

A: 插件使用双重持久化机制保存用户信息：

1. 配置文件保存：保存到AstrBot的配置文件中
2. 独立持久化文件：保存到 data/astrbot_proactive_reply/persistent_data.json，避免配置重置影响

如果重启后信息仍然丢失，请：

1. 使用 /proactive config 检查配置文件状态
2. 使用 /proactive manage save_config 强制保存配置
3. 查看日志中的持久化保存状态

Q: 为什么没有收到主动消息？

A: 请检查：

1. 是否启用了主动发送功能
2. 如果启用了睡眠时间功能，检查当前时间是否在睡眠时间段内
3. 是否已添加当前会话到主动对话列表
4. LLM服务是否正常工作
5. 使用 /proactive status 查看定时任务状态

Q: 插件会影响AstrBot的性能吗？

A: 插件经过性能优化，对系统影响很小：

1. 内存占用：仅保存必要的用户信息和时间记录，内存占用极低
2. CPU使用：定时任务采用异步处理，不会阻塞主线程
3. 网络请求：仅在发送主动消息时调用LLM，频率可控
4. 数据存储：历史记录功能优先使用AstrBot框架接口，安全高效，影响微乎其微
5. 建议配置：历史记录条数建议设置为5-20条，平衡功能与性能

Q: 历史记录功能会消耗很多Token吗？

A: 历史记录功能的Token消耗是可控的：

1. 默认设置：默认获取10条历史记录，通常消耗200-500个Token
2. 可配置数量：可以根据需要调整历史记录条数，建议设置为 5-20 条
3. 智能筛选：只获取最近的对话记录，避免无关内容
4. 开关控制：可以完全关闭历史记录功能，不消耗额外Token

Q: 如何优化主动消息的质量？

A: 可以通过以下方式优化：

1. 完善提示词：在主动对话提示词列表中添加更具体、个性化的提示词
2. 启用历史记录：让AI参考对话历史，生成更连贯的消息
3. 调整人格设置：配置合适的主动对话默认人格
4. 使用占位符：在提示词中使用 {username}, {user_last_message_time_ago} 等占位符
5. 测试和调试：使用 /proactive test generation 和 /proactive show prompt 测试效果

Q: 插件支持哪些消息平台？

A: 插件支持所有AstrBot支持的消息平台：

• QQ个人号测试通过(原理上全部支持)

提示：

1. 请根据 AstrBot 官方文档 正确配置对应的平台适配器
2. 每个平台的会话是独立的，需要在对应平台上执行命令才能添加该平台的会话
3. 例如：想添加 Misskey 的会话，必须在 Misskey 上发送 /proactive add_session，不能从其他平台跨平台调用

Q: 如何调试插件问题？

A: 使用以下调试指令：

• /proactive status - 查看整体状态
• /proactive config - 显示完整配置信息
• /proactive manage debug_info - 查看用户信息处理
• /proactive manage debug_send - 调试LLM发送功能
• /proactive manage debug_times - 查看时间记录
• /proactive test generation - 测试LLM生成功能
• /proactive test placeholders - 测试占位符替换功能
• /proactive test history - 测试对话历史记录功能
• /proactive test save - 测试对话保存功能
• /proactive manage task_status - 检查定时任务状态

Q: 插件的安全性如何？

A: 插件严格遵循AstrBot安全规范：

1. 官方API：仅使用AstrBot官方提供的API，无任何非标准操作
2. 权限控制：不会访问系统敏感信息，仅处理聊天相关数据
3. 数据隔离：用户数据仅在插件内部使用，不会泄露给第三方
4. 错误处理：完善的异常处理机制，避免因错误导致系统崩溃
5. 代码审查：代码开源，可供社区审查和验证

问题反馈

如果您在使用过程中遇到问题，请在 GitHub Issues 中反馈。

贡献

欢迎提交 Pull Request 来改进这个插件！