# astrbot-plugin-proactive-guard

**Repository Path**: seasmall/astrbot-plugin-proactive-guard

## Basic Information

- **Project Name**: astrbot-plugin-proactive-guard
- **Description**: AstrBot 主动消息门禁：拦截非本插件的 AI 主动发言 + 每日后台生成随机时间点人格消息自动发送
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-29
- **Last Updated**: 2026-08-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AstrBot 主动消息门禁 + 每日定时人格消息（proactive_guard）

一个 [AstrBot](https://github.com/AstrBotDevs/AstrBot)（4.x）插件，做两件事：

1. **🚪 主动消息门禁**：阻止「本插件之外」的 AI 主动发言。只要用户没有发消息，任何 AI 对话的**生成与发送都会被拦截**——包括 AstrBot 内置「主动型 Agent」、定时主动任务、陪伴类插件等。用户正常发消息聊天完全不受影响。
2. **💬 每日定时人格消息**：每天在**后台静默**预生成「**明天**」的 5~10 条消息，随机分配到 **07:00~23:00** 之间的不重复时间点，由 AI 根据**人格设定**和每个时间点的场景撰写各不相同的内容，存入内部存储；**到点自动发送该条并删除**，跨天自动把预生成的「明天」计划提升为「今天」，日复一日。全程不向用户发送任何报备/确认消息。

> 灵感来源：机器人"突然冒出一句话"（如 QQ 官方适配器日志里的 `Agent 使用工具: ['send_message_to_user']`）——那是 AstrBot 的主动型 Agent/定时任务在主动聊天。本插件把这类行为统一收编：**只有本插件允许的人格消息能在用户没说话时发出去**。

## 🧩 工作原理

### 门禁（拦截层）

插件激活时，在 `Context.send_message`（AstrBot 唯一的**主动发送**入口）上安装一层拦截：

- 非本插件的主动发送 → **直接丢弃**，并在日志记录（`[proactive_guard] 已拦截非白名单主动消息 -> ...（来源模块: ...）`），不打扰用户；
- 以下情况放行：
  - **本插件自己**发送（每日人格消息，带内部标记）；
  - **白名单插件**（配置 `allow_senders`，如 `daily_digest`）；
  - **用户最近活跃的会话**（默认 30 分钟内用户发过消息 → 视为正常对话回复，可配 `active_window_minutes`）；
- 可选 `strict_mode`：只放行本插件，其余一律拦截。

同时插件会**自动暂停** AstrBot 内置的「主动型 Agent」定时任务（`cron_manager` 中的 `active_agent` 任务，**可逆**，不会删除；在面板可恢复）。用户正常消息的回复走的是另一条发送链路，**不受影响**。

### 每日计划（生成层）

1. **预生成「明天」**：计划以「明天」为目标日期提前生成（`gen_time` 默认每天 06:00 触发；若计划缺失，**任意时刻**都会自动补种，20 分钟节流）；
2. 在 `window_start ~ window_end`（默认 07:00~23:00）内随机抽取 5~10 个**互不相同**的时间点（`msg_count_min/max` 可配）；
3. 调用 AstrBot 当前 LLM，按**当前人格设定**（自动读取 AstrBot 的「人格」设置，无需单独配置）和每个时间点的场景写一条消息，输出 JSON；
4. 存入插件 KV 存储（**双槽位**：`daily_plan` = 今天的计划、`daily_plan_next` = 明天的预生成，含日期，重启不丢）；
5. **跨天提升**：0 点后自动把 `daily_plan_next`（date 已变为今天）提升为 `daily_plan`，并预生成新的「明天」；
6. 每**分钟**检查一次：只从 `daily_plan`（date == 今天）派发——到点 → 发送 → **删除该时间点**；错过未发（设备休眠）→ 30 分钟补偿窗口内补发，超窗丢弃；过期计划静默丢弃；
7. **记忆写入**：发送的同时把消息写入该会话的 LLM 对话历史（assistant 角色，可配置 `record_to_history`），模型后续回复时知道机器人主动说过什么，不会出现「被动输出与主动输出」记忆断层。

> 💡 因此：手动清理掉「明天」的定时消息后，重载插件会**立即重新生成「明天」**，绝不会生成「后天」。

## 📦 安装

1. AstrBot WebUI →「插件」→「安装插件」→「通过 Git 地址安装」
2. 输入：`https://github.com/SeaSmall/astrbot-plugin-proactive-guard`
3. 启用插件，在配置面板按需修改（时间窗口、目标会话等）

> 要求 **AstrBot 4.x**。

## ⚙️ 配置说明

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `enabled` | bool | `true` | 总开关 |
| `block_proactive` | bool | `true` | 门禁开关：拦截非本插件的 AI 主动发言 |
| `strict_mode` | bool | `false` | 严格模式：只放行本插件，连"用户最近活跃会话"也拦截 |
| `active_window_minutes` | int | `30` | 活跃窗口（分钟）：用户此窗口内发过消息的会话放行（视为正常对话） |
| `allow_senders` | text | `daily_digest` | 主动发送白名单：插件模块名关键词，每行一个（**默认放行 `daily_digest` 日报**，可增删；改其它非空值即完全覆盖默认） |
| `pause_active_agent_jobs` | bool | `true` | 启用时自动暂停 AstrBot 内置主动型 Agent 任务（可恢复） |
| `gen_time` | string | `0 6 * * *` | 每日计划生成时间（cron，默认每天 06:00）：确保「明天」计划已预生成；计划缺失时任意时刻自动补种（20 分钟节流） |
| `timezone` | string | `Asia/Shanghai` | 定时任务时区（IANA 时区名）。**必须与部署机器实际时区一致**，否则 cron 会在错误时间触发（如默认 UTC 时 `0 6 * * *` 会按 UTC 6 点跑） |
| `message_prompt` | text | 见默认值 | 写消息提示词模板（`{persona}` 自动替换为 **AstrBot 当前人格设定**，`{date} {time_list} {count}` 自动替换） |
| `msg_count_min` / `msg_count_max` | int | `5` / `10` | 每日消息条数范围 |
| `window_start` / `window_end` | string | `07:00` / `23:00` | 消息时间窗口 |
| `missed_grace_minutes` | int | `30` | 错过补发窗口（分钟），超窗丢弃 |
| `record_to_history` | bool | `true` | 把主动发送的人格消息写入该会话的 LLM 对话历史（assistant 角色），让模型后续回复时知道机器人主动说过什么（避免记忆断层）；关闭则不写入 |
| `target_sessions` | text | 空 | 发送目标会话（unified_msg_origin，每行一个）；留空自动选择 |
| `only_private` | bool | `true` | 未指定目标时：仅发私聊会话，不打扰群聊 |

## 🎮 指令（用户主动触发，可选）

| 指令 | 说明 |
| --- | --- |
| `/今日计划` | 查看今日待发送的消息计划 + 明日预生成摘要 |
| `/重建今日计划` | 立即在后台重新生成明天的计划（今天窗口未结束且今天计划缺失时也补一份今天的） |

## 📝 效果示例

日志（后台，不发给用户）：

```
[proactive_guard] 主动消息门禁已安装（仅放行本插件/白名单/活跃会话回复）
[proactive_guard] 已拦截非白名单主动消息 -> aiocqhttp:Friend:12345（来源模块: astrbot.core.tools.message_tools）
[proactive_guard] 计划已生成（2026-08-27）：8 条消息 @ 07:35、09:20、12:10、15:00、18:00、20:30、22:05、22:45（后台静默）
[proactive_guard] 已发送 07:35 的消息并移除该时间点
```

用户在 07:35 收到（示例，内容由 AI 按人格生成）：

```
早上好呀，今天也要元气满满哦 ☀️
```

## ❓ 常见问题

**Q：装上门禁后，之前的"突然冒话"还会出现吗？**
不会。主动型 Agent 任务会被自动暂停，且即使任何插件/AI 尝试主动发送，也会被门禁拦截（日志可见）。

**Q：写消息用的人格是哪来的？**
无需单独配置——插件自动读取 **AstrBot 当前默认人格**（`服务提供商 → 人格` 里设置的默认人格）的设定文本；如果 AstrBot 未设置任何人格，则使用内置的温和默认人设兜底。

**Q：会不会误伤正常聊天？**
不会。用户发消息→机器人回复走的是正常链路，不经过门禁；只有"用户没发消息时的主动发送"才被拦截。同一会话 30 分钟内有用户消息时，AI 的回复/发送也正常放行。

**Q：机器人错过到点的消息怎么办？**
30 分钟（`missed_grace_minutes`）内自动补发，超过则丢弃该条，不堆积。

**Q：手动清理了明天的计划，重载后为什么重新生成的是「明天」而不是「后天」？**
v1.0.1 起计划以「明天」为目标日期提前预生成（`daily_plan_next`），清理后任意时刻重载都会立即重新生成**明天**，绝不生成后天。

**Q：想恢复 AstrBot 自带的主动型能力？**
在 AstrBot 面板恢复被暂停的主动任务，并关闭本插件的 `pause_active_agent_jobs` 或直接禁用本插件门禁（`block_proactive`）。

## 📦 更新日志

- [CHANGELOG.md](CHANGELOG.md)

## ⚠️ 免责声明

- 本插件仅拦截/发送行为，不存储用户隐私数据；消息内容由 AI 生成，请按需使用。
- 请合理设置人格与频率，避免对用户造成打扰。