AstrBot 主动回复插件 · 心念

一个为 AstrBot 打造的「聊天增强 + 时间感知 + 智能主动对话」插件。

让 AI 不只是被动应答，而是像朋友一样记得你、惦记你、主动找你。

快速上手：AstrBot「心念」插件使用指南

---

目录

• 这是什么
• 功能总览
• 核心功能详解
• 聊天附带用户信息
• 智能主动对话系统
• 时间感知增强
• 智能时间表（日历事项）
• AI 自主调度
• 消息分割（拟人化发送）
• 可视化管理面板（WebUI）
• 安装方法
• 配置说明
• 指令说明
• 快速开始
• 占位符大全
• 配置示例
• 测试与调试指南
• 与 AstrBot 的兼容性
• 文件与数据存储
• 常见问题
• 开发信息与反馈

---

这是什么

「心念」是一个 AstrBot 插件，围绕三件事展开：

1. 聊天增强 —— 在每次对话中自动为 AI 附带用户信息（昵称、平台、上次活跃时间等），让回复更贴合上下文。
2. 时间感知 —— 让 AI 真正「懂时间」：知道现在几点、上次聊天隔了多久、是否到了睡觉时间，并用自然口语表达。
3. 智能主动对话 —— 在合适的时机由 LLM 生成个性化问候并主动发送，而非套用预设模板；还能从对话中识别「时间约定」自动安排再次联系。

所有能力均使用 AstrBot 官方 API 实现，并配有一套独立的可视化管理面板用于配置与运维。

---

功能总览

模块	一句话说明	关键词
聊天附带用户信息	每次对话自动注入用户信息与时间，可自定义模板	模板 / 占位符 / 不污染缓存
智能主动对话	由 LLM 生成个性化主动消息，支持固定 / 随机间隔	人格协同 / 历史记录 / 多风格提示词
时间感知增强	引导 AI 自然表达时间，支持睡眠时段	时间指南 / 睡眠模式 / 唤醒发送
智能时间表	月历可视化管理节日/纪念日，并可 AI 一键生成整套日历	{calendar_today} / 重复规则 / AI 生成
AI 自主调度	从对话中识别「X 分钟后找你」并自动定时回访	关键词预检测 / 独立模型 / 去重
消息分割	把长回复拆成多条逐句发送，更拟人	8 种分割模式 / 可调延迟
可视化管理面板	概览 / 会话 / AI 约定 / 时间表 / 占位符 / 配置文件	中英双语 / 深浅色主题
时区与持久化	自定义时区、跟随 AstrBot 时区，YAML 持久化	跨重启不丢数据 / 可手动查看编辑

---

核心功能详解

聊天附带用户信息

• 功能开关：支持启用/禁用用户信息附加功能。
• 自动在 AI 对话中附带用户信息（用户名、用户 ID）与当前时间信息。
• 支持自定义时间格式与自定义信息模板。
• 智能注入：动态信息（用户信息模板内容、睡眠提示）追加到用户消息后，固定指导词（时间感知规则）追加到 system_prompt 末尾，避免动态时间污染系统提示词的前缀缓存。

智能主动对话系统

• 基于 LLM 的智能生成：通过 LLM 生成个性化主动消息，不使用预设模板。
• 人格系统兼容：自动检测并组合 AstrBot 人格设置与主动对话指令。
• 多样化对话风格：支持多个主动对话提示词，随机选择不同的对话风格。
• 上下文感知：基于用户信息和对话历史生成更自然的主动消息。
• 混合计时器模式：预计算下次发送时间 + 智能睡眠，精确控制发送时机。
• 可在 /proactive status 或 WebUI「会话」页查看各会话的下次发送时间。
• AI 发消息后自动刷新计时器，避免频繁打扰。
• 历史记录功能增强：支持基于对话历史的智能主动消息生成。
• 历史记录开关配置，可选择是否附带历史记录。
• 可配置历史记录条数（默认 10 条，建议 5–20 条）。
• AI 生成主动消息时会参考之前的对话历史，生成更拟人和连贯的内容。
• 使用 AstrBot 官方 API 安全地获取聊天记录。
• 对话历史回写：AI 主动发送的消息会自动添加到对话历史中，解决上下文断裂问题，支持三种保存模式：
• default：默认系统触发标记 <SYSTEM_TRIGGER: ...>。
• proactive_prompt：使用当次的主动对话提示词（已替换占位符）。
• custom：自定义内容（支持占位符）。
• 两种时间模式：
• 固定间隔模式：固定时间间隔，可选随机延迟。
• 随机间隔模式：每次在设定范围内随机选择等待时间（如 1 分钟到 1 小时随机）。
• 重复检测：当生成的主动消息与上次发送内容重复时，自动重新生成（最多重试 3 次）。
• 未回复计数：通过 {unreplied_count} 占位符追踪用户连续未回复的次数。
• 多会话管理：每个会话独立维护计时器、用户信息与统计。

时间感知增强

• 时间感知提示词：可配置指导 AI 正确处理时间表述的规则（真实性、自然回应、状态映射、上下文感知）。
• 睡眠时间功能：睡眠时段内不发送主动消息；用户在此时段发消息时，将睡眠提示追加到用户消息后，让 AI 表现出困倦/迷糊状态。
• 支持跨午夜时间段（如 22:00-8:00）。
• 支持「睡眠结束时发送消息」开关与两种唤醒发送模式：
  • immediate：立即发送（计时器过期则马上发送）。
  • delayed：延后发送（恢复睡眠前的剩余计时，保持自然间隔）。
• 无论哪种模式，睡眠期间累积的多次主动消息只会在睡眠结束后发送一次。
• 智能时间表达：引导 AI 使用自然口语描述时间，避免机械式报时。

智能时间表（日历事项）

• 日历样式日程表：在 WebUI「时间表」页签以月历视图为任意日期添加「节日」或「事项」（如春节、生日、纪念日）。
• 重复规则：每条事项可设置不重复（仅当年）、重复 1–4 年（基准年 + 之后 N 年，共 N+1 年生效）或每年重复（永久）。
• {calendar_today} 占位符：启用后将「当天」事项注入用户信息模板或主动对话提示词，让 AI 感知特殊日期；关闭时返回空字符串。
• 全局共享 + 本地存储：所有会话共享同一份时间表，数据保存在独立的 calendar_data.yaml，完全本地、不联网。
• 导入 / 导出：支持以 YAML 文件备份或分享时间表（合并 / 替换两种导入模式）。
• AI 生成时间表：在「时间表」页签输入主题或世界观（如「末世废土 / 幸存者据点的物资节、旧世界缅怀日」「蒸汽朋克都市 / 发明家庆典、齿轮节」），由 AI 一次性生成整套贴合主题的节日 / 纪念日。
• 生成结果以可编辑预览呈现：每条可改月 / 日 / 名称 / 重复规则、逐条删除、手动新增一行。
• 确认后可选择「追加到现有」或「清空并替换」（替换前二次确认）。
• 可在配置中指定生成所用的模型与系统提示词，也可在面板临时切换模型。

AI 自主调度

• 智能时间约定检测：AI 在对话中提到时间约定时（如「40 分钟后找你」），插件会自动分析并设置一次性定时任务。
• 关键词预检测：使用轻量级关键词匹配，避免不必要的 LLM 调用。
• 独立模型选择：支持为调度分析指定不同的模型提供商，可使用更便宜或更快的模型节省成本。
• 重复检测：自动注入已有待执行的约定，避免重复创建相同任务。
• 自定义分析提示词：可配置 AI 调度分析的系统提示词。
• 可视化管理：可在 WebUI「AI 约定」页查看倒计时、执行时间与触发提示词，并随时取消。

消息分割（拟人化发送）

把 LLM 生成的长消息按特定分隔符拆分成多条消息发送，模拟更自然的对话节奏。提供 8 种分割模式：

模式	分隔符	使用场景	示例
backslash（默认）	反斜线 \	LLM 生成时使用 \ 标记分段	早上好\今天天气不错 → 2 条消息
newline	换行符	按换行分割，适合长文本	第一段<换行>第二段 → 2 条消息
comma	逗号 ,	按逗号分割	你好,最近怎么样 → 2 条消息
semicolon	分号 ;	按分号分割	早上好;吃早餐了吗 → 2 条消息
punctuation	多种标点	按中英文标点分割	你好。最近好吗? → 2 条消息
custom	自定义正则	高级用户自定义	见 自定义正则填写指南
words	分段词列表	官方风格：用分段词作为分割标记	。？！~…
regex	官方风格正则	官方风格：re.findall + DOTALL/MULTILINE	.*?[。？！~…\n]+\|.+$

• 分割消息延迟：分割后的消息之间的发送延迟，单位毫秒（默认 500ms，建议 300–1000ms）。
• 安全保护：对管理员配置的复杂正则做长度与复杂度提示；超长文本（>10000 字符）跳过正则分割、整条发送，缓解灾难性回溯（ReDoS）风险。

---

可视化管理面板（WebUI）

插件内置一套独立的可视化管理面板（AstrBot Plugin Pages），无需手改 JSON 即可完成全部配置与运维。

打开方式：在 AstrBot WebUI 的「插件管理」中找到「心念」插件，点击其插件页面 / 管理入口即可打开。

面板特性：

• 深浅色主题：自动跟随系统偏好，可手动切换并记忆。
• 中英双语：内置 i18n（zh-CN / en-US），可随 AstrBot 语言切换。
• 响应式布局：侧边栏可折叠，适配窄屏。

面板包含 6 个页面：

页面	功能
概览	展示总会话数、计划任务数、记录用户数、已发送数、待回复数、运行状态等统计，以及最近活动记录与功能状态徽标。
会话	列表化管理主动对话目标会话：查看平台、用户、下次发送时间、最后发送、未回复数、运行状态；支持添加 / 移除会话、查看会话详情。
AI 约定	查看由「AI 自主调度」生成的一次性任务：倒计时、执行时间、触发提示词、创建时间，并可取消任意任务。
时间表	月历视图管理节日 / 事项（增删改、设置重复规则）、导入 / 导出 YAML、清空，以及 AI 生成时间表（主题输入 → 可编辑预览 → 追加 / 替换）。
占位符	占位符速查面板，按「用户信息」与「主动对话」分组列出所有可用占位符及说明。
配置文件	以可视化表单编辑插件的全部配置分组（基础设置、用户信息、时间感知、时间表、主动对话、消息分割、AI 调度），保存后即时生效。

---

安装方法

环境要求：AstrBot >=4.24.0，Python 3.10+。插件依赖 pyyaml（AstrBot 运行时通常已自带）。

方式一：通过 AstrBot 插件市场 / 管理面板安装（推荐）

1. 在 AstrBot 管理面板的「插件市场」搜索「心念 / proactive_reply」并安装，或填入仓库地址安装。
2. 安装后在「插件管理」中重载插件。
3. 在插件配置或 WebUI 管理面板中配置相关参数。

方式二：手动安装

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

---

配置说明

推荐通过 AstrBot 管理面板或插件 WebUI「配置文件」页进行配置，会自动生成和保存配置文件。配置修改后通常需要重载插件或使用 /proactive restart 才能完全生效。

基础设置

• 时区：IANA 时区名称（如 Asia/Shanghai、America/New_York）。留空使用系统本地时区。
• 跟随 AstrBot 时区：启用后自动使用 AstrBot 全局设置中的时区，无需重复填写；AstrBot 未配置时区时回退到上方时区字段。

用户信息附加设置

• 启用聊天附带用户信息：启用后在每次 LLM 请求前自动将动态用户信息追加到用户消息后。
• 时间格式：时间显示格式（Python datetime 格式，如 %Y-%m-%d %H:%M:%S）。
• 信息模板：用户信息的显示模板，支持占位符。会追加到用户消息后，不会覆盖人格设置。

智能主动对话设置

• 是否启用定时主动发送消息功能：总开关。
• 目标会话列表：需要发送消息的会话 ID 列表，支持单独添加 / 编辑 / 删除（格式 platform:type:id）。
• 时间模式：fixed_interval（固定间隔）或 random_interval（随机间隔）。
• 固定间隔模式：发送间隔（分钟）、是否启用随机延迟、随机延迟范围（最小 / 最大分钟）。
• 随机间隔模式：随机间隔最小 / 最大时间（分钟），每次在范围内随机选择。
• 主动对话备用人格：仅当 AstrBot 未返回可用人格时作为备用系统提示词。
• 主动对话提示词列表：多个提示词选项，系统随机选择一个指导 LLM 生成主动消息，支持单独增删改与占位符。
• 启用重复检测：与上次内容重复时自动重试（最多 3 次）。
• 历史记录功能：
• 是否附带历史记录：启用后生成主动消息时参考对话历史。
• 附带的历史记录条数：默认 10 条，建议 5–20 条。
• 历史记录保存模式：default / proactive_prompt / custom。
• 自定义历史记录提示词：仅 custom 模式生效，支持占位符。

时间感知设置

• 启用时间感知增强提示词：启用后将固定时间使用指南追加到 system_prompt 末尾。
• 时间感知增强提示词：可自定义 AI 如何理解与表达时间的规则（支持 \n 换行）。
• 睡眠时间功能：
• 启用睡眠时间功能：睡眠时段内不发送主动消息，并在用户发消息时追加睡眠提示。
• 睡眠时间段：格式 开始-结束（24 小时制），支持跨午夜，如 22:00-8:00。
• 睡眠时间提示内容：睡眠时段内追加到用户消息后的提示。
• 睡眠结束时发送消息：开关。
• 睡眠结束发送模式：immediate（立即发送）/ delayed（延后发送）。

时间表设置

• 启用时间表（日历事项）功能：启用后 {calendar_today} 占位符返回当天事项；关闭时即使配置了事项也不注入（返回空）。
• 时间表事项分隔符：当天有多条事项时用于拼接的分隔符（默认 、）。
• 时间表无事项时的默认文本：当天无事项时 {calendar_today} 返回的文本（留空表示空字符串）。
• AI 生成时间表使用的模型提供商：留空使用主模型，也可在面板临时切换。
• AI 生成时间表的系统提示词：指导 AI 按 JSON 数组（month / day / text / repeat）输出贴合主题的日历事项；插件会自动补充当前年份与数量上限等运行时约束。

消息分割设置

• 启用消息分割：默认启用。
• 分割模式：8 种模式见 消息分割。
• 自定义分割正则表达式：仅 custom 模式使用。
• 正则表达式（regex 模式）：仅 regex 模式使用，官方风格。
• 分段词列表（words 模式）：仅 words 模式使用。
• 分割消息延迟：单位毫秒，默认 500ms。

AI 自主调度设置

• 启用 AI 自主调度：启用后从对话中识别时间约定并自动设置一次性任务（额外消耗一次 LLM 调用，使用关键词预检测）。
• AI 调度分析使用的模型提供商：留空使用主模型，可选用更便宜 / 更快的模型。
• AI 调度分析提示词：自定义判断时间约定并提取信息的系统提示词，支持自动注入已有约定以去重。

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

仅当分割模式为 custom 时需要填写。常用示例：

需求	填写内容	说明
按中文句号分割	。	直接填写字符
按中英文逗号分割	[,，]	方括号表示「任选其一」
按多种中文标点分割	[。，！？；]	包含句号、逗号等
按反斜线分割	\\	两个反斜线
按换行符分割	\n	反斜线 + n
按空格分割	\s+	一个或多个空格
标点后可跟空格	[,;]\\s*	标点 + 可选空格

注意事项： - 填写错误的正则会导致插件自动降级到 backslash 模式。 - 查看日志可确认分割模式是否生效，或用 /proactive test basic 测试效果。 - 优先使用预设模式，仅在需要特殊规则时使用 custom / regex。

---

指令说明

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

权限说明：test、show、config、manage、restart 等涉及调试、配置、破坏性操作及隐私信息的指令仅管理员可用（基于 AstrBot 的 PermissionType.ADMIN 校验）。普通成员仅可使用 status、add_session、remove_session、help。

核心功能指令

/proactive help            # 显示帮助信息
/proactive status          # 查看插件状态和当前会话信息
/proactive add_session     # 将当前会话添加到主动对话列表
/proactive remove_session  # 将当前会话从主动对话列表移除
/proactive config          # [管理员] 显示完整的插件配置信息
/proactive restart         # [管理员] 重启定时任务（强制刷新计时器）

测试指令（8 种功能）[仅管理员]

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

显示指令（2 种功能）[仅管理员]

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

管理指令（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. 配置用户信息模板

2. 在管理面板或 WebUI「配置文件」页自定义信息模板，通过模板控制显示哪些信息（用户名、ID、时间等）。

3. 设置智能主动对话

4. 启用「定时主动发送消息功能」。
5. 配置主动对话备用人格（当无 AstrBot 人格时使用）与主动对话提示词列表。
6. 选择时间模式（固定间隔 / 随机间隔）并按需设置睡眠时间段。
7. 在目标会话中执行 /proactive add_session 添加会话，或在 WebUI「会话」页添加。

8. 用 /proactive status 查看当前会话状态。

9. 测试功能

10. /proactive manage debug_info 查看 AI 收到的用户信息。
11. /proactive test llm 实际测试用户信息附加功能。
12. /proactive test generation 测试 LLM 生成主动消息。
13. /proactive test basic 测试主动消息发送。

---

占位符大全

不想显示某项信息？直接从模板中删除对应的占位符即可。

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

占位符	说明
{username}	用户名 / 昵称
{user_id}	用户 ID
{time}	消息时间
{current_time}	当前时间
{weekday}	当前星期（如「星期一」）
{platform}	平台名（如 aiocqhttp、telegram）
{chat_type}	聊天类型（群聊 / 私聊）
{user_last_message_time}	用户上次发消息时间
{user_last_message_time_ago}	用户上次发消息相对时间（如「5 分钟前」）
{ai_last_sent_time}	AI 上次发送时间
{calendar_today}	今天的时间表事项（需启用「时间表」功能，关闭时为空）

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

占位符	说明
{user_context}	完整的用户上下文信息（含用户名、平台、时间等）
{unreplied_count}	用户连续未回复次数

主动对话提示词同样支持上表中的 {username}、{platform}、{chat_type}、{current_time}、{weekday}、{user_last_message_time}、{user_last_message_time_ago}、{ai_last_sent_time}、{calendar_today}。

---

配置示例

用户信息模板示例

内置默认模板：

[对话信息] 用户名称:{username},时间:{time},上次聊天时间:{user_last_message_time}

简洁模板（推荐）：

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

详细信息模板：

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

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

用户：{username}

主动对话提示词示例

基础提示词列表：

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

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

现在是 {current_time}，用户 {username} 上次发消息是在 {user_last_message_time}，请主动问候用户
{username} 在 {platform} 上已经有一段时间没有活跃了，上次发消息是 {user_last_message_time_ago}，请友好地询问近况
根据以下用户信息主动发起对话：{user_context}
现在是 {current_time}，已连续 {unreplied_count} 次未回复，请主动关心一下用户

时间模式配置示例

固定间隔模式：

{
  "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 分钟。

随机间隔模式：

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

• 每次在 600–1200 分钟（10–20 小时）之间随机选择等待时间，发送节奏更自然。

---

测试与调试指南

测试用户信息附加功能

1. /proactive manage debug_info —— 查看当前用户原始信息、配置状态与 AI 将收到的完整用户信息。
2. /proactive test llm —— 发送一条测试消息，自动附加用户信息，直接体验效果。
3. 查看 AstrBot 日志中的用户信息添加过程。

测试智能主动对话功能

1. /proactive status —— 查看当前会话是否在主动对话列表中。
2. /proactive add_session —— 添加当前会话。
3. /proactive test generation —— 测试 LLM 生成。
4. /proactive show prompt —— 预览主动对话提示词列表与组合话术。
5. /proactive test prompt —— 含历史记录处理的完整测试。
6. /proactive test basic —— 测试立即发送。
7. /proactive manage debug_send —— 调试发送过程。

---

与 AstrBot 的兼容性

人格系统深度集成

• 智能人格检测：自动检测当前会话使用的 AstrBot 人格设置。
• 人格协同机制：AstrBot 人格保留在 system_prompt，主动对话指令作为本轮用户提示词传递。
• 备用人格支持：当 AstrBot 未返回可用人格时，使用配置的主动对话备用人格。
• 用户信息注入：动态用户信息通过 extra_user_content_parts 追加到用户消息后；时间感