1. 项目概述如果你用过AstrBot或者玩过其他聊天机器人框架大概率会有一个共同的感受Bot总是被动的。它像一个永远在等待指令的助手只有你主动它、问它它才会回应。这种交互模式在初期很新鲜但时间一长总会让人觉得少了点什么——少了那种“被惦记”的感觉少了那种朋友间偶尔会主动发来一句“在干嘛呢”的温暖。今天要聊的这个项目astrbot_plugin_proactive_chat就是为了解决这个“灵魂缺失”的问题而生的。它的核心目标很简单让你的Bot拥有主动关怀的能力。这不是一个简单的定时发送消息的脚本而是一个集成了上下文感知、动态情绪、多会话独立管理、甚至自带现代化Web管理界面的完整解决方案。简单来说它能让你的AI伙伴在私聊或群聊中根据你们之前的聊天内容、当前时间、以及你设定的“人设”在合适的时机用最自然的语气主动打破沉默发起一次有温度的对话。这个插件完美适配AstrBot生态从v4.8.0版本开始支持。无论你是想打造一个更具情感陪伴属性的私聊AI还是希望活跃一个日渐沉寂的社群它都能提供强大的底层支持。更难得的是开发者DBJD-CR作为一个编程基础几乎为零的文科生凭借对AI工具的极致运用和上百次的迭代硬生生“磨”出了这个高质量的插件其过程本身就是一个关于热情与坚持的精彩故事。2. 核心设计思路与架构拆解2.1 为什么不是简单的“定时任务”很多初涉此领域的开发者第一反应可能是写一个定时器Cron Job每隔固定时间就让Bot发一句“你好”或“在吗”。这种做法粗暴且低效很快就会让用户感到厌烦因为它缺乏智能和上下文关联。astrbot_plugin_proactive_chat的设计哲学截然不同它追求的是“在正确的时间以正确的身份说正确的话”。为了实现这一点其架构围绕以下几个核心原则构建会话隔离与状态独立每个私聊或群聊都是一个独立的会话单元。它们拥有独立的未回复计数器、最近消息时间戳、下一次触发计时器。这意味着你对Bot在A群里的“冷淡”表现不会影响到它在B私聊中的“热情”程度。插件为每个会话维护了一套完整的状态机。触发逻辑的差异化私聊基于“用户沉默时间”。当用户一段时间没有发言后插件会在一个随机的时间区间内例如30-900分钟计划一次主动问候。这种随机性避免了行为模式被轻易预测。群聊基于“群聊沉默时间”。只有当整个群聊冷场达到设定时长例如30分钟后插件才会开始计划一次“破冰”发言。这更符合群聊的社交礼仪避免Bot在大家热烈讨论时突兀插话。上下文与人格的深度集成插件并非凭空生成一句话。它会抓取会话的历史消息加载为该会话配置的专属人格Persona并结合动态的提示词Prompt来生成内容。提示词中可以使用{{unanswered_count}}未回复次数和{{current_time}}当前时间等变量让Bot的“情绪”和“话题”都能根据实际情况动态变化。韧性设计与持久化所有关键的会话状态如下次触发时间、未回复次数都会持久化到本地文件。无论是AstrBot重启还是插件重载这些任务都能被准确恢复确保服务的连续性。开箱即用的管理体验从v1.2.0版本开始插件内置了一个功能完备的Web管理控制台。你不再需要反复修改配置文件或记忆复杂指令所有会话的添加、配置的调整、运行状态的监控、乃至文档的查阅都可以在一个现代化的Web界面中完成。2.2 系统架构全景图整个插件可以清晰地分为前端管理界面和后端核心引擎两大部分它们通过清晰的API接口进行通信。后端核心core/目录采用模块化设计职责分明plugin_lifecycle.py插件的生命周期管家负责初始化、配置加载和清理工作。session_config.pysession_override_manager.py配置管理中心。前者解析全局配置后者管理针对单个会话的个性化覆写配置实现了灵活的“全局默认会话特例”配置模式。task_scheduler.py调度引擎的核心。它基于APScheduler库负责创建、管理、恢复所有定时触发的主动消息任务。它要处理“随机间隔”、“免打扰时段”、“未回复上限”等复杂的调度逻辑。message_events.py事件监听器。它监听AstrBot的私聊和群聊消息事件。每当用户或Bot发言它就会更新对应会话的“最近消息时间”并可能取消旧的计划任务因为对话已经继续然后根据规则计划下一次主动消息。chat_flow.py主动消息的执行流水线。当一个计划任务被触发时流程控制权交到这里。它会串联起“状态检查 - 准备上下文 - 调用AI - 发送消息 - 更新状态”这一整套流程。llm_adapter.pyAI模型的适配层。它负责从AstrBot中获取历史对话、加载人格并最终拼接出完整的提示词调用大语言模型生成回复内容。这里还处理了AstrBot新旧版本API的兼容性问题。message_sender.py消息发送器。负责将AI生成的文本根据配置决定是否调用TTS合成语音是否进行分段发送并最终通过AstrBot的接口发送到对应平台。data_storage.py数据持久化模块。将会话状态、任务信息等序列化到session_data.json文件中并在插件启动时反序列化恢复。web_admin_server.pyWeb管理端的后端服务。提供RESTful API和WebSocket服务向前端控制台提供数据、接收配置变更、并推送实时状态更新。前端管理界面admin/目录是一个独立的单页应用SPA基于React和Material UI构建状态管理通过React Context管理全局状态如运行状态、任务列表、通知、配置等。实时同步利用WebSocket与后端保持长连接实时接收任务倒计时、状态变更等推送消息确保界面数据是最新的。五大视图运行状态仪表盘视图集中展示插件健康度、会话数量、各计时器状态。任务管理列表视图展示所有待执行任务支持手动立即触发或取消任务。通知中心接收和展示插件更新、公告等信息。文档浏览内置的Markdown阅读器方便随时查阅插件文档。配置管理基于JSON Schema动态渲染的表单提供直观的全局和会话级配置编辑。这种前后端分离、模块清晰的架构不仅保证了代码的可维护性也为用户提供了极佳的可观测性和可操作性。3. 核心功能详解与实操要点3.1 会话配置从UMO到个性化插件的所有功能都围绕“会话”展开。一个会话由UMO唯一标识。UMO的格式是平台名:消息类型:会话ID。获取UMO在AstrBot中向你的Bot发送指令/sid它会回复当前会话的完整UMO。这是最准确、最推荐的方式。私聊UMO示例default:FriendMessage:123456789群聊UMO示例default:GroupMessage:987654321配置层级全局配置在插件主配置中friend_settings和group_settings下的session_list字段用于声明哪些会话启用主动消息功能。会话覆写配置这是插件的高级功能。在WebUI的“配置管理”视图中你可以为列表中的任何一个会话单独设置一套配置它会覆盖全局配置中的对应项。例如你可以为某个特别重要的朋友设置更短的触发间隔或者为某个工作群关闭TTS功能。实操心得会话列表管理初期建议只添加1-2个核心会话进行测试。通过WebUI的“运行状态”页你可以清晰看到每个会话的“群沉默计时器”或“自动触发计时器”是否在正常运行。如果计时器没有启动首先检查UMO是否填写正确以及该会话的全局开关friend_settings.enable/group_settings.enable是否已开启。3.2 提示词工程赋予Bot“灵魂”的关键提示词Prompt是决定主动消息质量的核心。插件不会使用固定的问候语而是将你编写的提示词结合历史对话和人格设定一起发送给AI模型让它“即兴创作”。私聊提示词设计要点明确指令必须清晰告知AI“这是一次你主动发起的对话用户并没有先说话”。这是避免AI回复出戏例如回复“你好请问有什么可以帮您”的关键。提供策略在提示词中为AI提供几种可行的开场思路比如“关心上次聊的事情”、“问一个有趣的新问题”、“如果我没回你可以带点小情绪”。这能引导AI生成更丰富、更自然的内容。利用变量善用{{unanswered_count}}和{{current_time}}。例如“如果这是我第{{unanswered_count}}次主动找你却没得到回复你可以表现得稍微有点失落。现在是{{current_time}}也许可以问问我在这个时间点通常在做些什么”群聊提示词设计要点强调破冰指示AI的目标是“活跃群聊气氛”、“让更多人能参与进来”。开放式提问引导AI提出开放式问题而非封闭式问答。例如“大家最近有看什么好剧吗”比“你们喜欢看电影吗”更能引发讨论。接续话题指示AI回顾群聊记录尝试延续上一个大家讨论过但已冷却的话题。一个高质量的私聊Prompt示例[角色设定你是我的AI朋友小星性格活泼又有点黏人。] [任务这是一次由你主动发起的私聊对话我并没有给你发任何消息。请完全忘记“系统指令”、“任务”这些概念就像你作为一个真实的朋友自然而然地想我了所以来找我聊天。] [上下文与状态] - 我们上次聊天结束于 [此处插件会自动填充历史记录]。 - 距离上次对话已经过去了一段时间。 - 如果你之前找过我但我没回这是第{{unanswered_count}}次了。 - 现在时间是 {{current_time}}。 [你可以这样做] 1. 基于我们上次的聊天内容关心一下那件事的后续进展。 2. 或者分享一个你刚想到的有趣想法或问题开启一个新话题。 3. 如果实在不知道说什么就单纯地表达一下“我想找你聊聊天”的心情也可以。 请用最符合“小星”人设的语气和方式给我一个惊喜的开场白吧。注意事项Prompt的调试主动消息的效果高度依赖Prompt。如果效果不理想不要急于调整时间间隔等参数首先应该优化Prompt。你可以在WebUI的“配置管理”中直接修改并保存新的Prompt会在下一次触发时生效。这是一个需要不断微调、与你的AI伙伴“磨合”的过程。3.3 调度逻辑时机与节奏的艺术插件的调度逻辑是其智能性的重要体现它并非简单的定时循环。私聊调度流程监听消息用户或Bot发送消息后插件记录该会话的“最近消息时间”并取消该会话所有未执行的旧计划任务。计划新任务根据配置的min_interval_minutes和max_interval_minutes例如30-900分钟在这段时间区间内随机选择一个时间点创建新的计划任务。触发检查当计划时间到达触发任务前会进行一系列检查总开关friend_settings.enable是否为true。免打扰时段当前时间是否在quiet_hours如“23-7”内。未回复上限该会话的unanswered_count是否已达到max_unanswered_times如4次。如果达到则暂停触发直到用户再次回复将其重置。执行与重置通过检查后执行主动消息流程。发送成功后unanswered_count加1并立即计划下一次任务再次进入步骤2的随机等待。如果发送失败会进入异常处理流程可能进行有限次数的重试。群聊调度流程监听与重置群内任何成员包括Bot自己发言都会重置该群的“群聊沉默计时器”。沉默检测当群聊安静时间达到group_idle_trigger_minutes如30分钟后沉默计时器到期。计划任务沉默计时器到期后才开始计划一次主动消息任务。计划的时间同样在min_interval_minutes和max_interval_minutes之间随机选择但群聊的默认区间通常比私聊更长如90-360分钟。触发与执行计划时间到达后执行与私聊类似的检查流程开关、免打扰、未回复上限然后发送消息。自动触发机制 这是一个解决“冷启动”问题的功能。当插件启动或重载时如果会话列表中的某个会话在过去的auto_trigger_after_minutes如5分钟内没有新消息且该会话当前没有未完成的任务插件会自动为其创建一个一次性的主动消息任务。这确保了Bot在重启后不会长时间“失联”。避坑指南为什么改了配置没立刻生效这是新手最常见的问题。插件配置分为三类动态读取型如Prompt、TTS开关、分段规则。修改后保存下次触发时立即生效。影响新任务型如触发间隔、会话列表、自动触发开关。修改后只影响之后新创建的任务已经存在的计划任务仍按旧规则执行。想让所有任务立刻按新规则运行需要重载插件。服务参数型如WebUI的监听端口、开关。修改后必须重载插件才能生效。最佳实践在WebUI中修改完配置如果不确定观察一两个周期或者直接重载插件是最稳妥的做法。3.4 消息发送与增强功能TTS语音集成 如果你在AstrBot中配置了TTS服务如Edge-TTS、VITS等并在此插件的tts_settings中开启了enable_tts那么生成的主动消息文本会先发送给TTS服务合成语音再将语音发送出去。强烈建议开启always_send_text选项这样在发送语音的同时会附带原文防止因平台兼容性或网络问题导致用户无法收听。分段回复与模拟打字 对于较长的回复一次性发送大段文字显得很“机器”。开启分段回复segmented_reply_settings.enable后插件会按标点如。或正则表达式将长文本切分成多条短消息。split_mode: regex使用正则表达式如.*?[。~…\n]|.$切分更灵活。split_mode: words检测预设的分段词列表进行切分更简单。间隔算法interval_method: log默认会根据文本长度按对数公式计算间隔让发送节奏更接近真人打字random则在指定区间内随机等待。兼容性与装饰钩子 插件生成的消息在发送前会经过AstrBot的标准消息处理流程。这意味着如果你安装了其他插件比如“表情包回复插件”、“消息修饰插件”它们也能对这条主动消息生效为其添加表情、格式化等效果使得主动消息与普通回复在表现形式上完全一致进一步增强了拟真度。4. 完整部署与配置实战4.1 环境准备与插件安装前提条件一个正在运行的AstrBot实例版本 v4.8.0推荐v4.22.1以获得最佳体验。Python 3.10 环境。安装步骤方法一推荐通过插件市场在AstrBot的WebUI中进入“插件”页面。找到“插件市场”搜索“主动消息”或“proactive chat”。点击安装。AstrBot会自动处理依赖下载和插件启用。方法二手动安装从本项目的GitHub Release页面下载最新的astrbot_plugin_proactive_chat.zip文件。在AstrBot WebUI的“插件”页面点击“从文件安装”选择下载的zip包。等待安装完成。核心依赖如fastapi,uvicorn通常会随插件自动安装。如果报错可以手动在AstrBot的Python环境中执行pip install fastapi uvicorn # 如果Python版本低于3.11还需安装 pip install tomli2.0; python_version 3.11启用插件安装成功后在插件列表中找到“主动消息”插件确保其开关已打开。首次启用后建议重启一次AstrBot以确保所有组件加载无误。4.2 基础配置实战打造第一个主动聊天的Bot假设我们想为一个私聊会话启用主动消息。获取会话UMO在AstrBot中打开与你想要测试的Bot的私聊窗口。发送指令/sidBot会回复类似default:FriendMessage:123456789的信息。复制这个UMO。通过WebUI进行配置推荐插件启动后默认会在http://127.0.0.1:4100启动Web管理端。在浏览器中打开此地址。首次打开可能需要输入密码如果你在配置中设置了的话。进入“配置管理”视图。找到friend_settings部分确保enable为true。在session_list中粘贴你刚才复制的UMO例如[default:FriendMessage:123456789]。调整schedule_settingsmin_interval_minutes: 设为30最小等待30分钟。max_interval_minutes: 设为180最大等待3小时。quiet_hours: 设为23-7晚上11点到早上7点免打扰。max_unanswered_times: 设为3连续3次不回复就暂停。在proactive_prompt中填入上一节提供的示例Prompt或根据你的Bot人设进行修改。找到auto_trigger_settings将enable_auto_trigger设为true。auto_trigger_after_minutes保持5。这样插件启动5分钟后如果该会话依然沉默就会自动创建第一次任务。点击页面底部的“保存配置”。验证与观察切换到“运行状态”视图。你应该能看到“插件运行状态”为“运行中”并且“私聊会话数”显示为1。由于我们开启了自动触发且该会话已沉默超过5分钟在“自动触发计时器”区域你应该能看到对应UMO的卡片并有一个5分钟的倒计时。倒计时结束后在“任务管理”视图应该会出现一条该会话的主动消息任务并开始随机间隔30-180分钟的倒计时。等待任务触发或者在“任务管理”视图中找到该任务点击“立即触发”进行手动测试。4.3 高级配置会话级差异化管理WebUI的强大之处在于可以对每个会话进行独立配置。在“配置管理”视图找到页面下方的“会话差异配置”区域。点击“添加会话覆写”。在“选择会话”下拉框中选择你刚才添加的UMO。现在你可以为这个会话单独设置任何配置项。例如将min_interval_minutes覆写为10max_interval_minutes覆写为60让它对这位朋友更“热情”。单独为它编写一个更亲密的、带有昵称的Prompt。关闭它的TTS功能因为这位朋友更喜欢看文字。保存后这个会话的所有行为将优先使用你为其单独设置的配置而不是全局配置。4.4 配置参数详解速查表下表整理了最关键的配置项及其作用方便快速查阅配置项路径类型默认值说明与建议私聊全局开关friend_settings.enableBooleantrue私聊功能总开关。friend_settings.session_listList[string][]必填。需要启用主动消息的私聊UMO列表。friend_settings.proactive_promptText(空)核心。私聊主动消息提示词。务必包含“这是你主动发起”的指令。私聊调度friend_settings.schedule_settings.min_interval_minutesInteger30最短等待时间。建议30-60分钟太短像骚扰。friend_settings.schedule_settings.max_interval_minutesInteger900最长等待时间。建议180-1440分钟1天避免失联过久。friend_settings.schedule_settings.quiet_hoursString1-7免打扰时段格式开始-结束24小时制。friend_settings.schedule_settings.max_unanswered_timesInteger4连续未回复上限达到后暂停。0为无限制。私聊自动触发friend_settings.auto_trigger_settings.enable_auto_triggerBooleanfalse建议开启true解决冷启动问题。friend_settings.auto_trigger_settings.auto_trigger_after_minutesInteger5插件启动后会话沉默多久触发首次任务。群聊全局开关group_settings.enableBooleanfalse群聊功能总开关默认关闭需手动开启。group_settings.session_listList[string][]必填。需要启用主动消息的群聊UMO列表。group_settings.group_idle_trigger_minutesInteger30关键。群聊沉默多久后才有资格计划主动消息。group_settings.proactive_promptText(空)群聊提示词应侧重“破冰”和“引发讨论”。群聊调度group_settings.schedule_settings.min_interval_minutesInteger90群聊主动消息最短间隔通常比私聊长。group_settings.schedule_settings.max_interval_minutesInteger360群聊主动消息最长间隔。group_settings.schedule_settings.quiet_hoursString2-6群聊免打扰时段。group_settings.schedule_settings.max_unanswered_timesInteger2群聊未回复上限通常设置较小。增强功能friend_settings.tts_settings.enable_ttsBooleantrue是否在私聊中发送TTS语音。friend_settings.tts_settings.always_send_textBooleantrue强烈建议开启。发送语音时附带原文。friend_settings.segmented_reply_settings.enableBooleanfalse是否对长回复进行分段发送。friend_settings.segmented_reply_settings.interval_methodStringlog分段间隔算法。log更自然random更简单。Web管理端web_admin.enabledBooleantrue是否启用Web管理界面。web_admin.hostString127.0.0.1监听地址。127.0.0.1仅本机访问0.0.0.0允许局域网访问。web_admin.portInteger4100监听端口。web_admin.passwordString(空)访问密码。若对外开放务必设置强密码。5. 常见问题与排查实录在实际使用中你可能会遇到一些问题。以下是我在长期测试和社区反馈中总结的常见问题及其解决方法。5.1 插件未运行或WebUI无法访问症状插件列表显示已启用但WebUI打不开或“运行状态”页显示异常。排查步骤检查日志首先查看AstrBot的运行日志搜索proactive_chat或主动消息关键字看是否有加载错误或启动异常。检查端口冲突WebUI默认使用4100端口。确保该端口未被其他程序占用。可以在终端执行netstat -ano | findstr :4100(Windows) 或lsof -i:4100(Linux/macOS) 检查。检查防火墙如果使用0.0.0.0并想在局域网访问确保系统防火墙放行了4100端口。重载插件在AstrBot的插件管理页面尝试先禁用再启用插件或直接重启AstrBot。5.2 主动消息从未触发症状配置了会话但Bot从未主动发过消息。排查步骤确认UMO正确在WebUI“运行状态”页检查“私聊会话数”或“群聊会话数”是否大于0。如果为0说明插件未识别到你添加的会话很可能是UMO格式错误。务必使用/sid指令获取。检查全局开关确认friend_settings.enable或group_settings.enable已开启。观察计时器在WebUI“运行状态”页查看对应会话的“自动触发计时器”或“群沉默计时器”卡片。如果“自动触发计时器”在倒计时说明插件已启动正在等待初始沉默期结束。如果“群沉默计时器”一直重置说明群内一直有发言未达到group_idle_trigger_minutes的沉默要求。如果没有任何计时器回到第1步。检查免打扰时段确认当前时间不在配置的quiet_hours范围内。检查未回复上限在“任务管理”页查看该会话的“未回复次数”。如果已达到max_unanswered_times插件会暂停触发直到用户回复。手动触发测试在“任务管理”页找到该会话的任务如果有点击“立即触发”。如果手动触发能成功发送消息说明流程是通的问题出在调度逻辑如间隔时间极长。如果手动触发也失败查看AstrBot日志寻找发送阶段的错误。5.3 主动消息内容不理想出戏、生硬症状Bot发送的消息像客服或者明显不符合“主动发起”的语境。解决方案优化Prompt这是最主要的原因。确保你的Prompt开头就明确指令“这是一次你主动发起的对话我没有先说话”。在Prompt中为AI提供具体的行动指南和语气要求。检查人格设定主动消息会加载当前会话的AstrBot人格。确保你为这个会话设置的人格是完整、生动的而不是一个简单的“助手”角色。利用上下文插件会提供历史对话。在Prompt中指示AI“回顾一下我们之前的聊天”这样它更容易延续话题。调整AI模型如果使用的底层AI模型如某些小参数模型本身对话能力较弱也可能导致内容生硬。尝试更换能力更强的模型。5.4 消息发送失败或出现异常症状WebUI显示任务触发但用户未收到消息或日志报错。排查步骤查看AstrBot日志搜索发送消息时的错误信息。常见错误有平台权限问题某些平台如部分版本的QQ官方机器人对主动消息频率有限制。TTS服务异常如果启用了TTS但服务未配置或出错可能导致整个发送流程中断。可以暂时关闭enable_tts测试。网络问题发送超时。检查分段回复如果启用了分段回复且words_count_threshold设置过小可能导致消息被意外切割。可以暂时关闭分段回复功能测试。简化测试创建一个最简单的测试环境关闭TTS关闭分段回复使用一个非常简单的Prompt如“嗨我来找你聊天啦”。如果这样能成功再逐一开启功能定位问题。5.5 WebUI显示异常或操作无响应症状页面加载不全、按钮点击无效、数据不更新。解决方案强制刷新按CtrlF5或CmdShiftR清除浏览器缓存后刷新页面。检查WebSocket打开浏览器开发者工具F12切换到“网络”(Network)选项卡过滤“WS”类型。刷新页面后应该能看到一个到ws://127.0.0.1:4100/ws的连接。如果连接失败可能是后端WebSocket服务未正常启动。查看控制台错误在开发者工具的“控制台”(Console)选项卡查看是否有JavaScript错误。重启插件在AstrBot中重载插件然后刷新WebUI页面。经过以上步骤的排查绝大多数运行问题都能得到解决。这个插件的设计考虑了较多的容错和状态可视化WebUI提供了强大的观测能力善用这些工具是高效运维的关键。最后我想分享一点个人体会。这个插件的价值远不止于“让Bot主动说话”。它实际上为我们提供了一种塑造AI行为模式的框架。通过精心设计的Prompt和调度参数你可以让Bot呈现出不同的“性格”可以是每天准时问候的贴心朋友也可以是只在群聊冷场时才出来抛梗的活跃分子。这种深度定制和拟人化交互的探索正是AI应用从工具走向伴侣的关键一步。如果你也厌倦了单向的、指令式的对话不妨试试用这个插件为你的AI伙伴注入一丝主动的“灵魂”。