让 AstrBot 更懂什么时候开口：
- 智能插话：在群聊中结合模型判断、聊天活跃程度和机器人精力评分，适合参与时才接话。完美替换 AstrBot 框架的“主动回复”功能。
- 主动聊天：在指定群聊或私聊中，根据作息和每日额度随机安排聊天机会，由机器人决定是否自然发言。
- 日程管理：向机器人提供背景信息，让机器人知道当前和近期安排，可选在某项日程期间暂停插话或主动聊天。
插件负责把握时机，回复仍交给 原会话的 AstrBot 聊天助手，沿用该会话的人格、历史和可用工具。正常 @ 回复、唤醒和命令照常。
如果关闭智能插话、主动聊天，只使用日程管理功能，插件可等效作为日程管理插件使用。
快速开始 · 智能插话 · 主动聊天 · 日程 · 日程管理教程 · 会话组 · 控制台
首次安装插件，总开关默认是关闭的。
在 AstrBot 插件页面打开 主动会话控制台，从“会话组”添加一个测试组。
会话就是一个群聊或私聊，SID 是它的地址。管理员可在目标会话发送 /sid 或 /active_status，复制完整 SID 后填入组内；一个组可以放多个 SID。
不添加任何组时，插件会在自己已经记录到、且平台支持的群聊或私聊中运行。 它不会自动扫描机器人加入的全部群；想让一个新会话参与主动聊天，先开启插件总开关和主动聊天，再在这个会话中发一次消息，让插件记录它。这些会话会共用全局设置，分别安排聊天机会。
添加任意组后，就进入白名单模式，智能插话和主动聊天只在组内列出的会话中运行。空组虽然没有作用对象，也会开启白名单模式。
| 想做什么 | 设置位置 | 需要准备什么 |
|---|---|---|
| 让机器人适时接话 | 智能插话 | 配置判断模型，并关闭框架原版主动回复 |
| 让机器人主动找人聊天 | 主动聊天、作息与日程 | 开启功能，设置每日额度和活跃时段 |
| 让机器人知道安排 | 作息与日程 → 日程管理 | 开启日程功能，添加安排 |
使用智能插话前，请关闭 AstrBot 自带的 “主动回复”，避免两套功能同时决定插话。仅使用主动聊天或日程时不需要关闭它，也不需要配置判断模型。
请前往 AstrBot WebUI，在 配置文件 → 扩展功能 → 群聊上下文感知 中，开启 “持久化群聊消息记录” 和 “群聊消息记录注入上下文”。前者保存群消息，后者把群消息交给聊天助手，是两项不同的设置。
判断模型二选一：
- LLM：选择已经在 AstrBot 配置好的聊天模型。
- Jev：填写兼容 TypeSafe Jev 的服务地址和 API Key。默认地址为
https://api.typesafe.ai/v1/systemone，默认模型为jev-latest。自定义中转站必须兼容该协议，普通聊天模型接口不能直接替代。
判断模型只打分；真正写回复的是原会话的聊天模型。
打开顶部 “启用主动会话插件” 总开关和需要的功能，点击 “保存并生效”。
总开关关闭时，智能插话、主动聊天和日程功能都停止，会话组不能绕过它。配置修改需要保存；日程的添加、修改、删除会单独立即保存。
插件只处理普通群消息。群里短暂停顿后，先读取参考资料，再计算三个 0～1 的分数：
| 分数 | 看什么 |
|---|---|
| 模型判断 | 结合人格、当前话题和记录，判断此时是否适合参与 |
| 群活跃 | 最近其他账号发言多少、距最近一次发言多久 |
| 机器人精力 | 最近机器人发言多少；说得越少，精力越高 |
这三项按权重合成最终分，严格高于阈值才通过；等于阈值也不触发。通过后仍会检查作息、冷却和助手是否忙碌。
权重不必加起来等于 1，插件会自动归一化。正权重正常计分，负权重先把该项变成 1－原分，零权重不参与；至少一项必须非零。最终分等于各项加权贡献之和，除以权重绝对值之和。
例如，活跃分使用负权重，就会偏向安静时参与。0.7 是分数门槛，不是 70% 的随机概率；精力分为零也不等于禁言。 控制台提供本地试算，可以先看效果再调整参数，不会调用模型或发消息。
连续群消息会合并判断，避免每条消息都请求模型。判断耗时过久、会话分支已变化或进入冷却时，旧结果会被丢弃，避免根据过时话题接话。
每天把允许主动聊天的时段拼在一起，按“每日主动尝试额度（轮）”随机选出聊天时间。同一天的机会可能分布不均，但相邻机会至少隔开共享冷却时间，冷却不足一分钟时按一分钟安排；时段太短、额度太高时，只安排放得下的次数。到点后，机器人结合当前会话的人格和历史决定是否开口，也可以选择安静。触发主动聊天的流程复用了 AstrBot 框架“未来任务”功能的底层原理。
| 作息状态 | 智能插话 | 主动聊天 |
|---|---|---|
| 睡眠 | 暂停 | 暂停 |
| 正常 | 允许 | 暂停 |
| 活跃 | 允许 | 允许 |
睡眠和活跃时段重叠时，睡眠优先。支持跨午夜的时段，例如 23:00-07:00；多个时段用英文逗号分隔。时区用于作息、日程日期和每日额度，通常填写 Asia/Shanghai。
“每日主动尝试额度”按轮计算：发送成功，或正常完成但决定不发，均消耗一轮；一轮中的多段发送不重复计算。错过、前置跳过或失败的机会不会补发，次日重新安排，所以每天实际发言次数可能少于额度。
作息时间轴展示所选会话当天的实际预约。点击竖线可看时间和结果；“重新抽卡主动聊天”只重新安排当天未来尚未开始的机会，已经尝试的机会和已用额度保留。剩余时间排不下原来的次数时，会保留原安排。作息、时区、每日额度或共享冷却时间变化后，会重新安排尚未开始的机会。
主动聊天沿用框架原生未来任务的 Agent 流程，由聊天助手决定是否调用发送工具；未调用发送工具的内部结论不会发给用户。主动聊天按普通成员权限运行，当前支持框架内置的 local 聊天助手。
日程的原理是安全、无侵入性、不影响缓存命中率的提示词注入，只为 Agent 提供背景信息。它不创建定时提醒，不会保证机器人到点发消息。如果需要准时提醒，请使用 AstrBot 原生未来任务。
例如，添加“机器人午休”，设置每天 12:00–13:00，并勾选“期间暂停智能插话”和“期间暂停主动聊天”。机器人能知道这项安排，这段时间内插件也会保持安静；正常 @ 和命令不受影响。
支持一次性、每天、每周、每年和 Cron 重复，普通时段可以跨午夜。每周可选多天；不自动推断法定节假日和调休。参数含义及有效格式在编辑位置直接说明。
| 范围 | 谁能看到 |
|---|---|
| 共享全局 | 继承全局日程的适用会话；可在组内排除 |
| 会话组 | 该组的全部会话 |
| 指定 SID | 只对列出的会话提供 |
在控制台中可以管理这些范围，也可让聊天助手通过下面两个工具查询和管理日程。
开启插件总开关和当前会话的日程功能，并使用支持工具调用的聊天模型后，可以直接用日常语言提出要求，无需自己填写工具参数。
| 工具 | 能做什么 | 可以怎样说 |
|---|---|---|
查询日程 query_schedule |
查看当前会话可见的安排，可按日期范围、名称或说明中的关键词筛选，也能列出包括停用日程在内的全部规则 | “这周有哪些安排？”“查一下阅读日程，包括停用的。” |
管理日程 manage_schedule |
创建一条或多条日程，修改一条日程的部分内容，或删除一整条日程 | “从明天起，每天晚上八点到九点是我的阅读时间，期间不要打扰我。”“把这项阅读安排改到九点。”“删除这条阅读日程。” |
Agent 通过 manage_schedule 创建的新日程默认只属于当前会话；助手只能修改或删除这个会话独享的日程，包括在控制台中为这个 SID 单独创建的安排。继承的全局、会话组和多个 SID 共享的日程可以查询，但默认不能由助手改动。
想让机器人统一安排各群共用的作息、穿搭或行程，可在 作息与日程 顶部选择 全局设置，然后在 日程管理 中开启 “允许Agent管理全局日程”。开启后，两个 LLM 工具都会多出 “当前会话／全局” 选项，默认当前会话，由 Agent 自行选择。它可以查询完整的共享全局日程目录，包括被当前组排除的安排，也能创建、修改、删除这些全局日程；会话组日程和多个 SID 共享的专属日程仍只读。修改、删除时按原日程的范围操作，不会把日程搬到别处，组内排除规则也继续生效。
谁能使用工具，由 AstrBot 管理。 例如，可在 AstrBot WebUI 的 扩展 → 组件管理 → 函数工具 中找到 manage_schedule，可把权限设为“全部用户”或“管理员”。注意插件的主动聊天以普通成员权限运行，工具权限设为仅管理员后，主动聊天中的 Agent 将不能使用它。
日期和时间按所选范围理解：当前会话用该会话的时区，全局用插件全局时区。
修改或删除前，助手应先查询，使用结果中的日程编号和版本信息定位目标；如果你同时在控制台改过这条日程，旧版本的操作会被拒绝，助手需要重新查询。你不必记住这些编号，但有多个同名安排时，需要说清是哪一条。修改或删除重复日程作用于整条重复规则，不只影响某一天；只想临时停用时，可以让助手将该日程关闭，之后再开启。
默认自动向聊天助手提供当前和未来 7 天的日程背景。预览天数填 0 只关闭自动提示词注入，查询和管理工具、暂停规则仍可使用。
打开插件和日程功能，确认目标会话在生效范围内、使用支持工具调用的聊天模型、相关工具都可用。
- 打开控制台的 作息与日程，选择需要知道这个生日的全局范围或会话组，点击 “添加全局日程” 或 “添加本组日程”。
- 名称填“小明的生日”，日期选小明的生日，时间选 全天，重复选 每年。说明写清是谁，例如“小明是……，今天是他的生日”。
- 点击 “保存日程”。如果想马上体验，可以先把日期设为今天，测试后再改回真实生日。
- 生日当天正常与机器人聊天，观察它是否自然提起生日、送上祝福，或在主动聊天时选择相关话题。
日程让机器人知情，具体怎么说仍由聊天模型决定；不会保证它主动祝福，也不会在零点自动提醒。若查询工具能查到、聊天却不知道，检查日程预览天数是否为 0，或这条全局日程是否被当前组排除了。
- 在 AstrBot WebUI 的 未来任务 中，新建每天执行的 Agent 任务，例如每天早上
07:00，选好目标会话。可使用下面这段提示词：
使用日程管理工具按需新建日程。要求：
1.只新建今天的日程。数量1~5个，合理即可，持续时间按需可全天或精确到时段。
2.日程内容自然、不重复、有创意、拟人化。可直接生成，也推荐参考聊天历史与今日天气、节假日、新闻等外部真实信息。可以是你做的事、去的地点，也可以体现你的服饰妆容等细节。
3.日程管理不是定时未来任务。如果发现今日已有足够数量且满足上述要求的日程，或找不到日程相关的工具，放弃此任务。日程创建完毕或放弃此任务后不要向用户发送任何消息。
- 确认模型可以调用
query_schedule和manage_schedule。如果管理工具只允许管理员，使用 WebUI 创建任务，或由 AstrBot 管理员在聊天中创建。等任务执行后，回到本插件日历查看当天是否出现了新安排；也可先手动立即执行一次未来任务验证。 - 安装并配置 图片生成插件，先按它的教程设好自拍人设，确认可以正常生成自拍。然后在聊天中对机器人说：“来张自拍”。
- 对照日程中的安排，看自拍里的服装、颜色和场景是否相符。这里是用自然语言让 Agent 调用自拍工具，而不是通过命令手动输入提示词生图。
未来任务负责每天唤醒助手，日程工具负责保存安排，图片插件负责生成自拍。它们通过 Agent 配合联动，还有更多玩法，功能上限只取决于你的想象力。
全局是通用设置，会话组只填写需要不同的部分。组内 SID 共用设置，聊天历史、冷却、计数和每日预约仍分别计算。
- 功能开关可以“跟随全局”“开启”或“关闭”，始终受插件总开关限制。
- 普通参数留空通常表示跟随全局；页面会显示本组覆盖和实际生效值，可一键恢复继承。
- 本组日程天数、条数有专门的继承值；清空表示本组不限，以输入框旁说明为准。
- 同一 SID 应只放在一个组中。跨组重复或格式错误会在对应位置提示。
控制台与原生插件配置页共用配置，选一处保存即可；同时编辑时会检查冲突。实际日程及本组排除在控制台管理。
可以分别自定义判断提示词和主动聊天提示词。智能插话只负责判断是否开口，回复沿用原会话的人格和群聊上下文。主动聊天提示词支持多套随机轮换，与任务说明一起作为原生未来任务的任务描述；不要在判断提示词里要求生成聊天回复。
占位符像自动填空，例如 {routine_state} 填入当前作息状态，{ai_last_sent_time_ago} 填入距机器人上次发言多久，{proactive_remaining} 填入今日剩余主动尝试次数。作息状态不是心情，剩余尝试次数也不是保证还会发出的消息数。
点击控制台中的提示词输入框，即可用底部占位符助手搜索、查看示例并插入；助手只展示该输入框适用的项目。完整说明也在控制台，不必翻 README 查表。聊天记录由框架提供，日程作为临时背景补充，通常不需要再重复加入历史占位符。
| 页面 | 用途 |
|---|---|
| 运行总览 | 查看当前状态、每日额度，以及智能插话和主动聊天各自最近的结果 |
| 决策回放 | 查看一轮经过、模型响应、评分、工具和发送结果 |
| 会话组 | 管理生效范围和组内覆盖 |
| 智能插话／主动聊天 | 设置对应功能、提示词和评分规则 |
| 作息与日程 | 查看实际预约、设置作息和管理日程 |
| 上下文与诊断 | 调整参考资料、并发、超时及临时记录保留范围 |
左下角可切换 简体中文／English，页面语言按登录账号记住。日程工具的说明、参数提示和报错也跟随这里的语言，尚未选择时默认中文。工具在整个机器人中共用；多个管理员选择不同时，以最后一次打开或切换控制台的语言为准。插件原生配置页的显示语言跟随 AstrBot。
机器人没说话时，先看总览和决策回放。模型响应有独立标记和直达入口；相关提示会直接解释原因，并在适合时提供设置入口。一次模型或工具失败不一定是整轮失败；已经发送后再出错，也会保留“已发送”的事实。 选择步骤后，会直接显示保留的详情，也可复制这一整步的记录。
回放是有容量和保留期限的临时文字记录，重载会清空；它不等于完整网络报文或模型服务的计费记录。分享前请检查聊天内容。控制台无法打开时，可查看 AstrBot 中本插件的日志。
- 其他插件若用自己的方式发送消息，本插件可能无法完整统计，精力和冷却的计算也会受影响。
- 机器人保存的对话记录与群里的全部发言不一定相同；能参考多少内容，还取决于 AstrBot 的历史保存和长对话整理设置。
- 不同平台对“群号/用户号”和主动消息支持不同。完整 SID 是最可靠的配置方式。
下面用相对路径说明插件代码、配置和运行数据的职责。
插件代码目录（data/plugins/astrbot_plugin_active_message/）
├─ main.py # 插件入口、原生消息钩子和调度编排
├─ active_message/ # 功能模块
│ ├─ __init__.py # 模块入口
│ ├─ models.py # 分数与会话运行状态
│ ├─ config.py # 配置数据类型与读取
│ ├─ settings.py # 默认值、会话组继承、生效配置与分功能校验
│ ├─ i18n.py # 共用文案读取与配置说明翻译
│ ├─ agenda.py # 日程规则、查询／管理工具、日历与日程数据保存恢复
│ ├─ diagnostics.py # 运行解释、异常摘要、步骤历史与进行中的任务概要
│ ├─ web.py # 登录校验、页面数据及设置／日程保存接口
│ ├─ context_input.py # 原生历史与已有图片转述的只读读取
│ ├─ text_context.py # 文字投影、媒体编码清理和判断预算
│ ├─ scoring.py # 三项评分、正负权重归一化
│ ├─ decisions.py # LLM 和 TypeSafe Jev 判断接口
│ ├─ prompts.py # 提示词占位符校验与渲染
│ ├─ sessions.py # SID 补全、会话组和白名单
│ ├─ runtime.py # 会话活动、发言计数和状态恢复
│ ├─ storage.py # JSON 读取、原子保存和损坏保护
│ ├─ native.py # AstrBot 原生会话、人格与历史访问
│ ├─ proactive.py # 原生未来任务 Agent 适配、执行跟踪与取消清理
│ └─ schedule.py # 作息时段、每日随机预约与单闹钟调度
├─ pages/console/ # 主动会话控制台
│ ├─ _page.json # 原生 Pages 页面声明
│ ├─ index.html # 页面结构
│ ├─ app.js # 配置、分组排序、试算、回放、作息时间轴与引导
│ ├─ i18n.js # 页面文案读取与语言切换
│ ├─ changes.js # 与已保存配置对比，实时列出修改位置
│ ├─ agenda.js # 日程编辑、继承排除和只读日历
│ ├─ agenda-list.js # 日程卡片搜索、筛选、分页和批量操作
│ ├─ placeholders.js # 光标感知的底部临时占位符助手
│ ├─ ui.js # 沙箱兼容弹窗、教程聚光与复制
│ └─ style.css # 响应式布局与明暗主题
├─ .astrbot-plugin/i18n/ # 共用语言文案
│ ├─ zh-CN.json # 简体中文设置、控制台和运行说明
│ └─ en-US.json # 对应的英文文案
├─ _conf_schema.json # WebUI 配置项定义，不是用户配置文件
├─ metadata.yaml # 插件元数据
├─ logo.png # 插件展示图标
├─ requirements.txt # 依赖说明
├─ LICENSE # AGPL-3.0 开源许可证
└─ README.md # 使用说明
AstrBot 插件配置目录（data/config/）
└─ astrbot_plugin_active_message_config.json # WebUI 保存的开关、权重、会话组、提示词和 API 配置
AstrBot 分配给本插件的数据目录（通常位于 data/plugin_data/astrbot_plugin_active_message/，以运行时实际路径为准）
├─ runtime_state.json # 活动时间戳、每日尝试计数、冷却依据和聊天预约
└─ agenda.json # 日程记录、本组排除及未完成的配置保存事务
Copyright (c) 2026 singularity2000.
GNU Affero General Public License v3.0（AGPL-3.0-only）
使用过程中，欢迎通过 Issues 提出宝贵意见，此插件将根据用户建议持续改进。