为 AstrBot 开发的主动消息插件

Proactive Chat Plugin for AstrBot

让你的 Bot 拥有主动关怀的灵魂

简体中文 | English | 日本語

一个为 AstrBot 设计的、功能强大的主动消息插件。它能让你的 Bot 在特定的会话长时间没有新消息后，用一个随机的时间间隔，主动发起一次拥有上下文感知、符合人设且包含动态情绪的对话。

如果你对 AI 带来的情感陪伴有需求，或者想让 ta 更加拟人，非常欢迎你来体验这个插件！

Important

本插件基于较新版本的 AstrBot 进行开发，致力于打造一个高质量的，好用的主动消息插件。

一般情况下，推荐使用最新的 AstrBot 版本以获得最佳体验。

目前插件处于较为稳定的开发阶段，我也会持续维护本仓库与插件。

📑 快速导航

💡 提示：点击以下链接可快速跳转到对应章节

✨ 效果示例
🌟 功能特色
🚀 安装与使用
⚙️ 配置说明
📂 插件目录与结构
🏗️ 核心架构与开发者说明
⚠️ 历史版本说明
🚧 最新版本的已知限制
❓ 常见问题简答
🌐 平台适配情况
📈 未来开发路线
💖 友情链接与致谢

✨ 效果示例

开发者的话：

大家好，我是 DBJD-CR ，初来乍到，请多关照。

这是我在 GitHub 上的首个仓库，也是第一次以开发者的身份参与到开源社区中，如果存在做的不好的地方还请理解。

今年的早些时候，我第一次了解到了 AstrBot 这个项目，但当时限于个人能力的不足，没有去深入研究。

现在经过了大半年的学习，以及参与体验了一些社区里的其他开源项目（主要是 KouriChat 和 LingChat ），我觉得我有能力来学习这个项目了。

于是在前段时间，受到一位群友的启发后，我尝试并成功在本地部署了 AstrBot ，也为其高度成熟的开发生态和插件市场感到赞叹。

但我在插件市场逛了一圈后，发现偌大的市场里，竟然没有一个好用的 主动消息 的插件，只有类似 主动回复 的插件，但这不是我想要的。

此时，一个疯狂的想法在我的大脑里诞生了：我要去做那个填补空白的人。

如果我能写出一个主动消息的插件，那么我使用 AstrBot 的体验将完全不逊于 KouriChat ，也能让我那可怜的 2c2g 的云服务器少一点多线程任务压力（只需要部署一个 AstrBot 就行了）。抱着这样一点点"私心"，我踏上了我的插件开发之旅。

可我们面临一个严峻的问题

这个插件的开发者，他的编程能力为 0 ，写一行" Hello World "的代码都费劲，在大学计算机基础公共课的 Python 期末考试的编程题中，他运用的思想是"面向结果编程"，他甚至学的不是计算机或人工智能相关的专业，还是个文科生。

因此对我而言，想要从 0 开始，开发一个插件，还要完成与 AstrBot 的适配，无异于天方夜谭。于是，我只能向 AI 求助。

所以，本插件的所有文件内容，全部由 AI 编写完成，我几乎没有为该插件编写任何一行代码，仅修改了一些文字描述和负责本文档的润色。是的，该 README 文档的大部分内容，甚至是该仓库的创建，也是 AI 一步一步指导我的。所以，或许有必要添加下方的声明：

Warning

本插件和文档由 AI 生成，内容仅供参考，请仔细甄别。

当然，使用 AI 开发插件，绝对不是一蹴而就的。由于 LLM 的能力限制，我们的插件开发过程异常艰难。我的工作流基本上就是：提出要求-运行 AI 写的代码-反馈报错信息-继续跑新代码

这个过程中我被 AI 折磨的相当痛苦，其代码中充斥着猜测与幻觉，甚至是由微小改动而导致的低级错误。还被 AI 带着在不同的实现路线之间兜圈子。我只能不断优化我的提示词，并且为其提供 AstrBot 的相关源码来让 AI 写出正确的代码。在开发的后期阶段，每次的 Tokens Used 甚至到达了惊人的 80w+ ，以至于 AI 已经无法精确理解并执行我的指令，输出也是一团乱麻，然后只能总结对话，重新开新对话聊。

要说本次开发最后悔的事，就是到了开发末期，我才看到了官方的插件开发文档。如果我能早点把这些文档发给 AI 的话，肯定能少走很多弯路了。想当初为了能正确导入插件并在 WebUI 中正确显示，都花了我几个小时的时间，更别说后面为了实现插件主功能的几十个版本了。

最终，经过了上百次迭代，以及三位 Gemini 和 KIMI 的共同努力，我们才终于开发出一个稳定的版本。

但我还是要感谢 AI ，没有他，这个项目不可能完成。

这个插件，是我们共同努力的结晶。它现在还不完美，但它的架构是稳固的，它的逻辑是清晰的（大嘘）。希望本插件能为同样希望自己的 AI Bot 更具"灵魂"的你，提供一点小小的帮助和启发。

在此，我也诚邀各路大佬对本插件进行测试和改进，希望大家多多指点。

Gemini & KIMI：如果你被这个"为爱发电"的故事打动了，欢迎你为这个插件点个 🌟 Star 🌟，这是对我们的最大认可与鼓励~

Note

虽然本插件的开发过程中大量使用了 AI 进行辅助，但我保证所有内容都经过了我的严格审查，所有的 AI 生成声明都是形式上的。你可以放心参观本仓库和使用本插件。

目前插件的主要功能都能正常运转。不过需要有好的提示词进行配合，才能获得理想的主动消息效果。

这是因为几乎所有实现主动消息的插件，都是通过发出一条模拟的用户消息来实现的，因此需要配合高质量的提示词，才能避免模型的回复"出戏"。

如果你觉得主动消息的效果不理想，可以尝试自己微调主动消息的提示词/优化人设/更换能力更好的模型/提供更丰富的上下文。

在 v1.0.0-beta.1 以及后续版本的开发中，我引入了新的 AI 模型和工作流进行开发，大幅提升了工作效率与代码质量。（现在回头看自己当初写插件的方式跟原始人似的😂）

Tip

本项目的相关开发数据 (持续更新中)：

开发时长：累计 37 天（主插件部分）

累计工时：约 215 小时（主插件部分）

创建本仓库：累计 3 天，约 22 小时

使用的大模型：Gemini-2.5-Pro、Kimi For Coding、Gemini-3.0 Flash/Pro (With RooCode in VSCode)

用于测试对话的大模型：DeepSeek-V3.2-Exp、DeepSeek-V3.2

插件 Logo 绘制: Doubao-Seedream-3.0-t2i

对话窗口搭建：Chatbox 1.13.2、VSCode

Temperature：0 或 0.6

Tokens Used：422,324,753

🌟 功能特色

多会话支持:支持同时为多个私聊和群聊提供主动消息服务，每个会话完全独立管理。额外提供 5 个私聊 + 5 个群聊个性化配置槽位，可以设置专属的配置和备注名。
全局配置系统: 通过 session_list 管理更多会话，使用全局配置作为后备方案。
会话完全隔离: 每个会话拥有独立的状态、计数器、触发器，避免相互干扰。
定时触发: 基于用户沉默时间，在设定的随机时间范围内自动触发。
自动主动消息: 插件首次加载时可以按需求自动开始创建主动消息任务，不需要用户输入来激活。
上下文感知: 能够回顾历史对话，并根据你设定的提示词，生成与之前话题相关的回复，而不是生硬的问候。
完整人格支持: 加载并应用你为当前会话设置的专属人格，确保每一次主动消息都符合人设。
动态情绪: 内置一个"未回复计数器"，你可以利用它在 Prompt 中设计不同的情绪表达，并且支持设置未回复上限。
持久化会话: 无论您是"重启 AstrBot"还是"重载插件"，都能够从文件中恢复所有未执行的主动消息任务。
免打扰时段: 可以自由设定一个时间段，在此期间 Bot 不会主动打扰用户。
TTS 集成: 支持调用你配置的 TTS 服务生成语音。
分段回复: 支持将长文本回复切分为多条短消息发送，并模拟真实的打字间隔，让对话更自然。
高度兼容: 兼容其他需要对主动消息进行修饰的插件如表情包插件、模拟情感插件等。
高度可配置: 所有核心参数都可以在 AstrBot 的 WebUI 中轻松配置，快速上手。无需修改任何代码，也无需学习和记忆任何插件指令。

🚀 安装与使用

下载插件: 通过 AstrBot 的插件市场下载。或从本 GitHub 仓库的 Release 下载 astrbot_plugin_proactive_chat 的 .zip 文件，在 AstrBot WebUI 中的插件页面中选择 从文件安装 。
安装依赖: 本插件的核心依赖 APScheduler 和 aiofiles 已包含在 AstrBot 的默认依赖中，通常无需额外安装。如果你的环境中确实缺少，请通过以下命令安装：
```
pip install apscheduler
```
```
pip install aiofiles
```
重启 AstrBot (可选): 如果插件没有正常加载或生效，可以尝试重启你的 AstrBot 程序。
配置插件: 进入 WebUI，找到 astrbot_plugin_proactive_chat 插件，选择 插件配置 选项，填写相关 QQ 号和自定义的"动机"。
开始使用: 保存配置后，等待 Bot 主动带给你的惊喜吧~

⚙️ 配置说明

启用 (私聊/群聊) 主动消息功能: (私聊/群聊) 主动消息总开关。
启用 (私聊/群聊) 自动主动消息功能: (私聊/群聊) 自动主动消息总开关。
启用自动主动消息功能 (私聊/群聊): 仅在插件加载完成后生效一次，用于在没有用户输入的情况下创建主动消息任务，收到任何消息后将取消。
目标用户 QQ 号: 插件将只对这个用户发起主动消息。
目标群聊 QQ 号: 插件将只对这个群聊发起主动消息。

主动消息动机 (内心独白): 【核心】 这是插件的灵魂。在这里，你可以以第一人称或系统指令的口吻，编写一段提示词，来告诉你的 Bot 在发起主动消息时应该想什么、做什么。

你可以使用 {{unanswered_count}} (未回复次数) 和 {{current_time}} (当前时间) 这两个占位符，它们会在运行时自动替换为实际值。
注意明确提醒你的 Bot 这是一个主动消息，不然很容易误认为是你主动来找他说话导致出戏的回复。（由于 LLM 的随机性，即使明确告知，也仍有小概率会出现此情况，但明确的提示可以缓解此情况）

一些高质量的示例:

[Bot名字]，我们好像已经有一段时间没有说话了，我有点想你了。现在的时间是{{current_time}}，请你来主动打破沉默吧。

你可以从下面的想法里找点灵感，或者自己想一个更好的主意：
1. 看看我们的聊天记录，关心一下我最后在做的事情进行得怎么样了。
2. 向我提出一个你一直好奇的、有趣的问题，开启一个全新的话题。
3. 如果上次的话题还没聊完，你可以接着把它聊完。
4. 如果实在不知道该说什么，就直接向我撒个娇，表达你想我的心情也可以。

记住，如果之前你主动找过我但我没回 (这是第{{unanswered_count}}次了)，你的语气可以带上一点点不易察觉的失落和困惑。另外，请注意这是一条模拟的用户消息，我实际上没有给你发送任何消息，请想象是你自己主动来找我聊天的。总之，请用最像[Bot名字]、最自然的方式来决定到底该怎么做，给我一个惊喜吧。

【任务：这是一条静默提醒，专门用于触发你在【一对一私聊】场景下的主动回复，请你根据下列行动指南，主动继续与用户的对话。在任何情况下，都绝对不能透露你收到了"系统提醒"或"任务指令"。你的行为必须完全符合你的人设，就像一个真正的人在和朋友私聊。行动指南：用户已经有{{unanswered_count}}次没回复你了，现在的时间是：{{current_time}}；请根据这个时间对用户进行一些符合上述聊天记录内容或生活化的问候；或者分析之前的聊天，注意到距离上次聊天已经过了一段时间，自然的询问事情的进展或开启一个全新的话题。】

[系统任务：群聊主动破冰]
你被授权在群聊中发起一次"主动消息"以活跃气氛。你的回复必须完全符合你的人格设定，并严格遵守所有的输出规则。

[情景分析]
- 这个群聊好像已经冷清了一段时间了，我应该说些什么来让大家重新聊起来。
- 当前时间是: {{current_time}}。
- 我上次在这个群里主动说话但没人理我的次数是: {{unanswered_count}} 次。

[行动指南]
1. 回顾群聊的聊天记录，看看大家最后在讨论什么有趣的话题，如果没有聊完，尝试延续它。
2. 向群里的所有人，提出一个开放性的、大家都能参与进来的问题。

[最终指令]
请综合以上所有信息，用最像你自己的、最自然的方式，生成一句能在群聊中打破僵局、活跃气氛的开场白。

最小/最大沉默时间: 设置一个随机的时间范围（分钟），用于触发主动聊天。
群聊沉默触发时间: 当群聊中连续 X 分钟没有任何新消息时，才会开始计划一次主动消息。
免打扰时段: 设置一个 Bot 不会主动打扰的时间段（24小时制），例如 0-6 表示午夜 0 点到早上 6 点。
最大未回复次数上限: 当 Bot 连续发送 N 次主动消息你都未回复后，将暂停主动消息，直到收到下次回复。填 0 则不限制。
启用主动消息的 TTS 功能: 关闭后，即使全局 TTS 开启，主动消息也只会发送纯文本。
发送语音后是否附带原文: 推荐开启，以确保即使语音播放失败，你也能看到文本内容。
分段回复设置:
- 启用分段回复: 开启后，Bot回复的长文本将被切分为多条短消息发送。
- 不分段字数阈值: 如果回复内容字数超过此值，则视为长文回复，不进行分段（防止长文被打断影响阅读体验）。
- 分段模式: 支持正则表达式 (regex) 或分段词列表 (words)。
- 间隔计算方法: 支持随机间隔 (random) 或基于字数的对数计算 (log)，模拟真实打字速度。

📂 插件目录与结构

目录结构示例：

AstrBot/
└─ data/
   └─ plugins/
      └─ astrbot_plugin_proactive_chat/
         ├─ _conf_schema.json
         ├─ logo.png
         ├─ main.py
         ├─ metadata.yaml
         ├─ README.md
         └─ requirements.txt

插件会在 AstrBot/data/ 目录下创建自己的数据文件夹：

AstrBot/
└─ data/
   └─ plugin_data/
      └─ astrbot_plugin_proactive_chat/
         └─ session_data.json

🏗️ 核心架构与开发者说明

Tip

本段描述的最近更新时间：2026/01/07，适用于 v1.1.2

🛠️ 系统架构图

graph TD
    %% 样式定义
    classDef event fill:#e1f5fe,stroke:#01579b,stroke-width:2px,rx:5,ry:5;
    classDef core fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,rx:5,ry:5;
    classDef state fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,rx:5,ry:5;
    classDef ext fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,rx:5,ry:5;
    classDef flow stroke:#666,stroke-width:1px;

    %% 外部依赖
    subgraph External [外部依赖环境]
        direction TB
        AstrBot[AstrBot 核心框架]:::ext
        LLM[LLM 大语言模型]:::ext
        TTS[TTS 语音服务]:::ext
        FileSystem[本地文件系统]:::ext
    end

    %% 插件内部逻辑
    subgraph Plugin [AstrBot Proactive Chat Plugin]
        direction TB
        
        %% 事件监听层
        subgraph Listeners [事件监听层]
            direction LR
            OnPrivate[on_private_message<br>监听私聊消息]:::event
            OnGroup[on_group_message<br>监听群聊消息]:::event
            OnSent[on_after_message_sent<br>监听Bot发送]:::event
            Init[initialize<br>插件启动/初始化]:::event
        end

        %% 状态与调度层
        subgraph SchedulerState [调度与状态管理]
            direction TB
            SessionData[(Session Data<br>持久化会话数据)]:::state
            
            subgraph Schedulers [双模调度系统]
                direction TB
                GroupTimer[Asyncio Timer<br>群聊专用: 沉默倒计时]:::state
                APScheduler[APScheduler<br>核心调度器]:::state
                note_private[私聊: 连续循环调度]
                note_group[群聊: 沉默倒计时 + 定时任务调度]
            end
            
            ScheduleLogic[调度逻辑控制器<br>_schedule_next_chat_and_save]:::core
        end

        %% 执行核心层
        subgraph Execution [核心执行流]
                direction TB
                CheckChat{check_and_chat<br>主动消息主入口}:::core
                ContextPrep[上下文与人格准备]:::core
                PromptGen[Prompt 构建]:::core
                MsgSend[消息发送与TTS]:::core
                Hooks[触发装饰钩子<br>OnDecoratingResultEvent]:::core
                Finalize[收尾与状态更新]:::core
            end
        end
    
        %% 逻辑连接 - 初始化
    Init -->|"加载数据"| FileSystem
    FileSystem -.->|"恢复状态"| SessionData
    Init -->|"恢复私聊任务"| APScheduler
    Init -->|"自动触发检查"| ScheduleLogic

    %% 逻辑连接 - 事件驱动
    OnPrivate -->|"重置计数器 & 重新调度"| ScheduleLogic
    OnGroup -->|"重置沉默倒计时"| ScheduleLogic
    OnSent -->|"Bot发言视为活跃<br>重置沉默倒计时"| ScheduleLogic

    %% 逻辑连接 - 调度逻辑细节
    ScheduleLogic -- "私聊模式: 计算随机间隔" --> APScheduler
    ScheduleLogic -- "群聊模式: 设置/重置倒计时" --> GroupTimer
    
    %% 关键：群聊复用逻辑
    GroupTimer -->|"沉默超时<br>触发回调"| APScheduler
    note_private -.- APScheduler
    note_group -.- APScheduler

    %% 统一出口
    APScheduler -->|"触发时间到"| CheckChat

    %% 逻辑连接 - 执行流程
    CheckChat -->|"1. 检查免打扰 & 上限"| SessionData
    CheckChat -- "通过" --> ContextPrep
    ContextPrep -->|"2. 获取历史 & 人格"| AstrBot
    ContextPrep --> PromptGen
    PromptGen -->|"3. 生成回复"| LLM
    LLM --> MsgSend
    MsgSend -->|"4. 分段处理 (可选)"| MsgSend
    MsgSend -->|"5. 语音合成 (可选)"| TTS
    MsgSend -->|"6. 触发装饰链"| Hooks
    Hooks -->|"发送最终消息"| AstrBot
    MsgSend --> Finalize
    
    %% 逻辑连接 - 收尾
    Finalize -->|"5. 存档对话历史"| AstrBot
    Finalize -->|"增加未回复计数"| SessionData
    Finalize -->|"持久化保存"| FileSystem
    
    %% 循环闭环
    Finalize -->|"私聊: 立即规划下一次"| ScheduleLogic
    Finalize -->|"群聊: 任务结束<br>等待下一次沉默"| GroupTimer

    %% 布局辅助
    External ~~~ Plugin

🔍 架构图说明

插件采用 事件驱动 + 双模调度 的混合架构，针对私聊和群聊的不同特性设计了差异化的调度策略，同时复用了核心执行逻辑。

事件监听层 (Listeners):
- 插件实时监听私聊 (on_private_message) 和群聊 (on_group_message) 消息。
- 同时监听 Bot 自身发送的消息 (on_after_message_sent)，这在群聊中尤为重要，Bot 的发言也被视为群聊活跃，会重置沉默倒计时。
调度与状态管理 (Scheduler & State):
- 私聊调度 (Continuous APScheduler): 采用"连续循环调度"模式。
  - 每次私聊对话结束后，插件会立即计算下一个随机触发时间（在最小/最大间隔之间）。
  - 直接在 APScheduler 中创建一个持久化的定时任务。
  - 任务执行完毕后，会再次调用调度逻辑，形成无限循环，直到达到最大未回复次数上限。
- 群聊调度 (Silence Timer + APScheduler): 采用"沉默倒计时 + 逻辑复用"的组合模式。
  - 群聊中的任何活跃（用户或 Bot 发言）都会重置一个内存中的 Asyncio Timer（沉默倒计时）。
  - 只有当群聊真正沉默达到设定时间 (group_idle_trigger_minutes) 后，Timer 回调触发。
  - 关键点：回调函数并不直接发送消息，而是调用 _schedule_next_chat_and_save，在 APScheduler 中创建一个主动消息任务。
  - 这样设计既实现了沉默检测，又复用了 APScheduler 的任务管理和持久化能力。
核心执行流 (Execution):
- CheckChat: 无论是私聊的循环任务，还是群聊的一次性任务，最终都汇聚到这个函数执行。
- 上下文感知: 自动获取当前会话的历史记录和人格设定，确保回复符合人设。
- Prompt 构建: 动态注入当前时间和未回复次数，引导 LLM 生成符合情境的回复。
- 装饰钩子 (Decorating Hooks): 在消息最终发送前，主动触发 OnDecoratingResultEvent 事件，允许其他插件（如表情包插件、情绪插件等）对主动消息的内容进行二次加工或拦截，极大地提升了生态兼容性。
- 收尾工作: 消息发送后，会自动将生成的对话存档到历史记录中，并更新未回复计数器，形成闭环。

⚠️ 历史版本说明

📋 版本表格

版本	状态	基本说明	推荐AstrBot版本
v1.1.2	✅ 架构升级	新增装饰钩子支持，提升与其他插件的兼容性	v4.10.2+
v1.1.0	✅ 功能更新	新增分段回复功能，支持正则/词表分段与模拟打字间隔	v4.10.2+
v1.0.2	✅ 兼容版本	继续修复各平台与模型的兼容性问题	v4.9.0+
v1.0.1	✅ 热修复版本	修复 Satori 等平台兼容性问题 & 新会话初始化 Bug	v4.9.0+
v1.0.0	✅ 正式版	插件经过测试已经基本稳定，故发布正式版🚀	v4.9.0+
v1.0.0-beta.7	✅ 多会话版本	🎉 重大更新: 正式添加完整的多会话支持	v4.5.7+
v1.0.0-beta.6	✅ 稳定版本	进一步优化代码质量，多会话前最后一个版本	v4.5.7+
v1.0.0-beta.5	❌ 失败版本	尝试重构为模块化架构但失败，已分到其他开发分支	v4.5.7+
v1.0.0-beta.4	✅ 稳定版本	修复潜在的多并发场景下的竞态条件问题，优化日志过滤	v4.5.7+
v1.0.0-beta.3	✅ 基本稳定	热修复: 修复新会话无法创建主动消息的问题	v4.5.7+
v1.0.0-beta.2	⚠️ 存在问题	新增自动主动消息功能，但存在新会话初始化问题	v4.5.7+
v1.0.0-beta.1	⚠️ 需重新配置	大幅重构配置格式，无法继承旧配置	v4.5.7+
v0.9.97	✅ 稳定版本	单私聊版最后一个稳定版本	v4.5.2+
v0.9.9+	⚠️ 注意兼容	确保 AstrBot 版本 ≥ v4.5.2，否则无法导入	v4.5.2+
v0.9.8	⚠️ 需配置时区	必须正确配置系统时区，否则报错	v3.5.19+
v0.9.7	⚠️ 首个发行版	存在较多基础性问题，不推荐下载	v3.5.19+
v0.9.5-v0.9.6pre	❌ 存在错误	请不要使用这些版本	-

🔍 详细版本说明

Important

v1.0.0-beta.1+ 升级注意：由于配置格式大幅重构，无法继承旧配置，升级后需要重新配置。请务必保存好自定义的 Prompt 设置。

v1.0.0-beta.2-beta.6：存在自动触发计时器没有被正确清理的遗留bug，已在 v1.0.0-beta.7 中修复。

v0.9.97 及以下版本特性：

手机端"对方正在输入"状态会被识别为消息（可用来创建任务）。
v0.9.97 已修复由此导致的未回复计数器错误重置问题。

v0.9.8 特殊要求：

必须在 WebUI → 配置文件 → 系统配置 中正确设置时区，否则会出现 ValueError 报错。

v0.9.7 及更早版本问题：

持久化失效：插件重启后无法正确恢复未执行的主动消息任务。
潜在的并发数据竞争风险：高并发场景下可能导致数据损坏或状态错乱。
"记忆黑洞"问题：无法正确保存主动消息产生的对话历史记录。
在早期版本中，你可能会对 main.py 中的部分 TTS 处理逻辑感到困惑。这是我为适配我本地的一个只支持日语的 VITS 服务而要求 AI 写的。

v0.9.5 & v0.9.6-pre：

存在字段更新和多余功能问题的错误版本，造成了发布延迟和仓库临时封锁。现已修复，但请勿使用。

🚧 最新版本的已知限制

配置复杂度与限制: 初次进行多会话配置时略显繁琐，会话数量超出预设槽位后部分会话无法进行个性化配置，需要进行取舍。
Prompt 依赖: 主动消息的效果，高度依赖于用户在提示词中提供的创造力和引导。也依赖于私聊/群聊中是否有足够丰富的上下文和 LLM 本身的模型能力。
框架限制: 由于 AstrBot 本身的限制，部分消息平台可能无法正常使用本插件的功能。

❓ 常见问题简答

🔧 插件配置问题

Q: 配置完成后 Bot 不主动发消息？

A: 请检查以下几点：

确认已启用对应的私聊/群聊主动消息功能开关。

检查目标用户/群聊 ID 是否正确填写。

确认当前时间不在免打扰时段内。

查看日志是否有错误信息。

Q: 自动主动消息功能没有触发？

A: 自动触发需要满足以下条件：

插件启动后，在设定的时间内没有收到任何消息。

当前没有正在运行的主动消息任务。

会话配置已启用且有效。

收到任何消息后，自动触发会被取消（这是正常行为）。

Q: 报错信息 ApiNotAvailable？

A: 目前所有已知信息都指向 ApiNotAvailable 不是插件本身的 bug，而是底层 OneBot 适配器和物理机器人（NapCat/Lagrange 等）之间的连接异常。常见诱因包括：机器人掉线但平台未检测、心跳包间隔过长被路由器/防火墙掐断、后台有僵尸/未连接的平台配置项、甚至浏览器节能模式影响 WebSocket 页面（Edge 有案例，但不是唯一原因）。

这个问题在不同 AstrBot 版本、不同部署方式（Windows/Docker）、不同网络环境下表现不一，无法稳定复现。部分用户回滚版本后问题消失，部分则依然复现，说明环境因素占主导。建议重点排查：

OneBot 客户端日志，关注是否有频繁 Close/Reconnect 或掉线提示。

所有平台配置项，确保没有多余或未连接的“幽灵平台”。

心跳包设置，建议调短（如 30 秒），保持连接活跃。

网络环境，排查是否有防火墙、NAT、路由器节能等影响长连接的设置。

如用浏览器管理 WebSocket，关闭节能模式或换浏览器试试。

重启 AstrBot、NapCat 等服务，如果你的 Bot 部署在服务器上，必要时可以重启服务器。

如果能抓到出错时的 OneBot 客户端详细日志，或在不同网络环境/设备/浏览器下对比测试，可能有助于进一步定位。这个问题本质上属于“物理机器人与平台连接不稳定”，代码层面已做了轮询和容错，剩下的只能靠环境排查。

⏰ 时间与触发相关问题

Q: 主动消息触发时间不准确？

A: 请检查：

AstrBot 的系统时区配置是否正确（在 WebUI 的系统设置中）。

免打扰时段设置是否影响了触发时间。

最小/最大间隔时间设置是否合理。

Q: 为什么 Bot 突然停止主动发消息了？

A: 可能原因：

达到了最大未回复次数上限。

当前时间处于免打扰时段。

插件配置被意外修改或禁用。

检查控制台日志了解具体原因。

🎯 效果与质量相关问题

Q: 主动消息的效果不理想，很生硬？

A: 主动消息质量主要取决于 Prompt 设计，建议：

参考文档中的高质量 Prompt 示例。

根据你的 Bot 人设调整语气和风格。

使用 {{unanswered_count}} 和 {{current_time}} 占位符增加动态性。

在 Prompt 中明确告诉 Bot 应该扮演什么角色。

使用能力更强的模型。

Q: Bot 的主动消息会重复或说奇怪的话？

A: 这是因为 LLM 的随机性，可以尝试：

优化 Prompt，增加更具体的上下文指示。

和 Bot 多聊些其他的内容，提供更丰富的上下文。

调整 Temperature 参数（如果支持）。

提供更清晰的行为指导和输出格式要求。

🔍 日志与调试

Q: 如何查看插件的运行状态？

A: 在 AstrBot 控制台可以看到插件的详细运行日志，包括任务创建、触发、取消等信息。

Tip

由于 AstrBot 的 Bug#3903，AstrBot WebUI 控制台输出的日志在本插件的使用场景下可能会出现显示问题，丢失部分日志。如果要在控制台中查看完整的插件日志记录，请重新刷新 WebUI 控制台或直接查看 CMD 窗口。

该 Bug 已于 AstrBot v4.9.0 中修复，推荐使用大于等于该版本的 AstrBot 运行本插件。

Q: 日志中出现错误信息怎么办？

A: 将完整的错误日志复制下来，包括错误类型和堆栈信息，可以在 QQ 群（1033089808）中寻求帮助，或在 GitHub 提交 Issue。

⚠️ AstrBot 限流机制影响

Q: 插件突然无法监听群聊消息，缺失相关的任务日志？

A: 这可能是 AstrBot 的限流机制导致的。当群聊消息频率过高时，AstrBot 会暂停消息处理流水线，导致插件无法接收消息事件。

限流影响的典型表现：

缺少关键日志。

用户消息后沉默倒计时不会重置。

主动消息任务异常执行（在群聊活跃时误判为沉默）。

日志中出现"会话 XXX 被限流。根据限流策略，此会话处理将被暂停 XXXXX 秒"。

解决方案：

立即解决：重启 AstrBot 可以清除限流状态。

配置调整：修改 AstrBot 配置文件 cmd_config.json 中的限流设置 (也可以在 WebUI 中进行修改)：

"rate_limit": {
  "time": 60,
  "count": 60,      // 增加消息数量限额
  "strategy": "discard"  // 改为"discard"避免长时间暂停
}

监控预防：观察是否频繁出现限流日志，适当调整配置参数。

技术细节：限流机制使用 Fixed Window 算法，当会话在指定时间窗口内消息数量超过限额时，会暂停整个消息处理流水线，导致基于消息事件的插件功能失效。

Q: 如何确认是限流问题而不是插件bug？

A: 检查 AstrBot 主日志中是否有类似这样的信息：

[Core] [INFO] [rate_limit_check.stage:74]: 会话 123456789 被限流。根据限流策略，此会话处理将被暂停 86291.74 秒。

如果有这条日志，基本可以确定是限流问题。重启 AstrBot 后如果插件功能恢复正常，则可以确认诊断。

Q: 限流问题会重复出现吗？

A: 是的，如果群聊消息频率持续很高，可能会再次触发限流。建议：

适当增加 count 值。

将 strategy 从 "stall" 改为 "discard"，避免长时间暂停。

监控群聊消息频率，在活跃时段适当调整配置。

🔄 功能使用相关

Q: 可以同时使用私聊和群聊主动消息吗？

A: 可以，但需要分别配置，每个场景有独立的配置和触发逻辑。

Q: 修改配置后需要重启吗？

A: 不需要，配置修改并保存后，插件会自动热重载并实时生效。但如果遇到异常情况，可以尝试重启 AstrBot 来帮助恢复正常的运行状态。

Q: TTS 语音功能不正常？

A: 检查：

是否在插件配置中启用了 TTS 功能。

AstrBot 的全局 TTS 配置是否正确。

TTS 服务提供商是否正常工作。

网络连接是否正常。

🌐 平台适配情况

平台	支持情况	备注
QQ 个人号(aiocqhttp)	✅ 完美支持	所有功能（包括 TTS）都经过了测试。
其他平台	❓ 理论支持	理论上支持所有支持主动消息的平台，但未经测试。

PS: 由于我个人本地的测试环境有限，我们正在邀请用户来测试其他平台上的主动消息效果！

根据 AstrBot 官方的插件开发文档，支持主动消息的平台有"QQ 个人号(aiocqhttp)"、"Telegram"、"飞书"。

欢迎分享你在任何平台上的使用体验！

📈 未来开发路线

💖 友情链接与致谢

本项目的灵感，以及在无数个黑暗的调试夜晚中给予我希望的，是以下这些优秀的开源项目或个人，在此向它们致以最诚挚的敬意。

KouriChat: 本插件的灵感来源，旨在复刻其主动消息的功能与效果。也是我接触类似此类项目的"引路人"。
LingChat: 一个非常可爱的聊天陪伴助手，也是支撑我开发本插件的最大动力。想让灵灵接入更多的平台——我要给她完整的一生！
@Roooodney：带我入坑 AstrBot 的群u ~

📚 推荐阅读

我的其他插件：

灾害预警 (disaster_warning) - 它能让你的 Bot 提供实时的地震、海啸、气象预警信息推送服务。

其他优秀的 AstrBot 插件：

Conversa: 与本插件功能高度相似，且指令功能更丰富。

📞 联系我们

如果你对这个插件有任何疑问、建议或 bug 反馈，欢迎加入我的 QQ 交流群。

QQ 群: 1033089808
群二维码:

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个插件！经历了一百多个版本的迭代，它终于达到了一个稳定且能用的状态，但依然有很大的提升空间。

📄 许可证

GNU Affero General Public License v3.0 - 详见 LICENSE 文件。

本插件采用AGPL v3.0许可证，这意味着：

您可以自由使用、修改和分发本插件。
如果您在网络服务中使用本插件，必须公开源代码。
任何修改都必须使用相同的许可证。

Name		Name	Last commit message	Last commit date
Latest commit History 124 Commits
.devin		.devin
.github		.github
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
README_JP.md		README_JP.md
_conf_schema.json		_conf_schema.json
logo.png		logo.png
main.py		main.py
metadata.yaml		metadata.yaml
requirements.txt		requirements.txt

License

DBJD-CR/astrbot_plugin_proactive_chat

Folders and files

Latest commit

History

Repository files navigation

为 AstrBot 开发的主动消息插件

Proactive Chat Plugin for AstrBot

让你的 Bot 拥有主动关怀的灵魂

📑 快速导航

✨ 效果示例

🌟 功能特色

🚀 安装与使用

⚙️ 配置说明

📂 插件目录与结构

🏗️ 核心架构与开发者说明

🛠️ 系统架构图

🔍 架构图说明

⚠️ 历史版本说明

📋 版本表格

🔍 详细版本说明

🚧 最新版本的已知限制

❓ 常见问题简答

🔧 插件配置问题

⏰ 时间与触发相关问题

🎯 效果与质量相关问题

🔍 日志与调试

⚠️ AstrBot 限流机制影响

🔄 功能使用相关

🌐 平台适配情况

📈 未来开发路线

💖 友情链接与致谢

📚 推荐阅读

📞 联系我们

🤝 贡献

📄 许可证

📊 仓库状态

⭐️ 星星

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 18

Packages 0

Uh oh!

Contributors 6

Uh oh!

Languages

Packages