YuanBot

简体中文

English
日本語

简体中文

English
日本語

切换主题

🌸 缘·Bot 主动陪伴与自动化系统详细设计文档 (v1.4)

版本历史

版本日期修改内容
v1.02026-05-17初始详细设计，基于总体架构 v1.4
  1. 系统定位与目标

主动陪伴与自动化系统是 缘·Bot 的“生物钟与直觉”，它赋予 AI 角色主动发起交互的能力。与传统聊天机器人被动等待用户消息不同，本系统让缘·Bot 能够感知时间、事件和用户状态，在恰当的时机以自然、不打扰的方式主动接触用户，真正实现“陪伴”而非“应答”。

核心目标：

· 定时关怀：基于用户作息和重要日期，在恰当时刻主动发起问候与祝福。 · 事件驱动感知：监听外部事件（天气、节日）和内部状态（用户静默、情绪趋势），自动触发关心。 · 情境智能：结合记忆系统提供的用户画像和历史情绪模式，使主动交互高度个性化。 · 克制与尊重：提供精细的免打扰控制，确保主动行为不会演变为骚扰。 · 可靠调度：基于 Cron 和事件总线的混合架构，保证准时、高可用。

  1. 系统架构概览
┌────────────────────────────────────────────────────────────┐
│               主动陪伴与自动化系统                           │
├────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │               主动触发调度器 (Scheduler)               │  │
│  │  · Cron 解析  · 任务注册  · 下一次执行时间计算        │  │
│  └──────────┬───────────────────────────┬───────────────┘  │
│             │                           │                   │
│  ┌──────────▼──────────┐  ┌─────────────▼───────────────┐  │
│  │  定时任务引擎       │  │  事件监听引擎               │  │
│  │  Cron Engine        │  │  Event Engine               │  │
│  │ (早安/晚安/提醒)    │  │ (天气/静默/情绪)            │  │
│  └──────────┬──────────┘  └─────────────┬───────────────┘  │
│             │                           │                   │
│  ┌──────────▼───────────────────────────▼───────────────┐  │
│  │             主动交互策略决策器 (Strategy Decider)      │  │
│  │  · 优先级排序  · 冲突检测  · 克制过滤                │  │
│  └──────────────────────┬───────────────────────────────┘  │
│                         │                                    │
│  ┌──────────────────────▼───────────────────────────────┐  │
│  │              主动消息生成与发送                        │  │
│  │  · Prompt 构建  · 模型调用  · 通道适配器推送         │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │           统一主动服务 API (Proactive API)            │  │
│  │  · schedule()  · trigger_now()  · get_pending()      │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────┘

设计原则：

· 分离调度与决策：何时触发由调度器负责，触发后是否行动、说什么由策略决策器决定。 · 用户可控：所有主动行为均可通过用户配置文件精细调整，支持实时修改。 · 情境感知：每次触发前都会查询记忆系统，获取用户当前状态，避免不合时宜的打扰。 · 异步非阻塞：所有定时和事件处理在独立的后台线程/协程中运行，不影响正常对话。

  1. 核心模块设计

3.1 主动触发调度器

职责：管理系统内所有定时任务和事件监听器的注册、调度与生命周期。

核心组件：

· 任务注册表：内存中的任务列表，每个任务包含唯一 ID、Cron 表达式或事件类型、关联的用户列表、优先级。 · 调度循环：每秒检查一次，计算到期任务并提交给策略决策器。 · 热重载：当用户修改 configs/bot.yaml 中的主动交互设置时，无需重启即可更新调度。

任务数据结构：

python
@dataclass
class ScheduledTask:
    task_id: str
    task_type: str  # "cron" 或 "event"
    trigger: str    # Cron 表达式或事件类型
    target_users: List[str]  # 目标用户 ID 列表，空表示全局
    priority: int   # 1-10，数字越大越优先
    max_retries: int = 3
    enabled: bool = True

3.2 定时任务引擎

职责：管理与时间相关的主动交互，包括每日问候、重要日期提醒、定期关心。

支持的 Cron 触发类型：

任务类型 Cron 示例 说明 早安问候 0 7 30 * * * 根据用户本地时区的早晨时间 晚安问候 0 22 * * * 晚间入睡前 午餐/晚餐提醒 0 12,18 * * * 可选的用餐时间问候 重要日期提醒 0 9 17 5 * 每年 5 月 17 日（生日/纪念日） 定期情绪关心 0 10 * * 1 每周一上午，基于上周情绪趋势

动态时间调整：若用户配置了作息习惯（事实记忆中的 wake_up_time, sleep_time），系统会动态调整问候的 Cron 表达式，而非使用固定时间。

防止重复触发：每个任务执行后会在 Redis 中设置一个锁（如 proactive_lock:{task_id}:{user_id}:{date}），TTL 为 24 小时，确保同一天不会重复问候。

3.3 事件监听引擎

职责：监听外部和内部事件，在条件满足时触发主动交互。

事件类型：

事件类型 触发条件 数据来源 weather_change 用户所在地天气突变（降温>5°C、降雨概率>70%） 天气 API（通过 Tool 调用） user_silence 用户超过 N 小时未发送任何消息 接入系统提供的最后活跃时间 emotion_alert 记忆系统检测到用户连续 N 天情绪低落 记忆与情感系统的情绪趋势分析 festival 法定节假日或用户自定义节日 日历服务 system_event 系统启动、版本更新、维护通知 系统内部

事件监听流程：

  1. 引擎订阅内部事件总线（Redis Pub/Sub 或 RabbitMQ）。
  2. 当事件被发布时，引擎验证事件类型是否注册了主动交互任务。
  3. 若是，则封装为触发请求发给策略决策器。

天气事件特殊处理：事件引擎自身不直接查询天气，而是通过调用 get_weather Tool 定期（如每小时）获取所有活跃用户的所在地天气。若检测到异常，发布 weather_change 事件。

3.4 主动交互策略决策器

职责：这是系统的“大脑”，在收到触发信号后，综合各种因素决定是否行动、以何种方式行动。

决策流程：

  1. 检查用户在线状态：若用户当前正在活跃对话中，则推迟或取消问候。
  2. 克制策略过滤： · 检查当前时间是否在用户的 quiet_hours 内。 · 检查今日已对该用户发起的主动交互次数是否达上限。 · 检查全局主动交互频率设置。
  3. 优先级排序：若同时有多个任务针对同一用户，选择优先级最高的执行，其余排队。
  4. 情境查询：调用记忆系统获取该用户的当前情绪状态、最近对话摘要，用于个性化消息生成。
  5. 生成主动交互请求：构造 ProactiveTask 对象，提交给消息生成模块。

克制策略规则表：

策略项 配置参数 行为 免打扰时段 quiet_hours: ["23:00-07:00"] 此区间内所有非紧急消息延后到结束时刻 每日上限 max_proactive_per_day: 3 达到上限后，当日不再发送 频率控制 proactive_frequency: "medium" 高/中/低/仅事件驱动，影响问候密度 静默超时 silence_timeout_hours: 48 用户连续静默超过此时长才触发静默关心 事件开关 event_trigger_enabled: true 关闭后仅定时问候，不响应事件

3.5 主动消息生成与发送

职责：根据策略决策器的输出，生成个性化主动消息，并通过接入系统发送。

消息生成流程：

  1. 接收 ProactiveTask，其中包含任务类型、目标用户 ID、上下文提示。
  2. 构建特殊的 System Prompt，包含： · 角色人设（当前活跃人格）。 · 主动场景描述（如“现在是早上7:30，用户刚起床，请温柔地道早安”）。 · 从记忆系统获取的个性化信息（如“用户昨天提到今天有个重要会议，可以祝福他顺利”）。 · 克制提示（如“保持简短，不要连续追问”）。
  3. 调用 AIService.generate()，使用默认提供商和模型生成消息内容。
  4. 将生成的 BotResponse 通过接入系统的主动推送通道发送（发布到 yuanbot.outbound.{channel} 队列）。

消息生成模板（早安问候示例）：

[主动场景：早安问候]
当前时间：{current_time}
用户名称：{user_name}
今日天气：{weather_summary}
用户今日安排：{today_events_from_memory}

请以{persona_style}的风格，生成一条早安问候。
要求：简短温暖，提及天气或用户可能关心的事，但不要像任务报告。
如果用户最近情绪低落，可以额外给予鼓励。

失败重试机制：若消息发送失败（如通道不可用），记录日志并在 5 分钟后重试一次。若再次失败，则放弃本次主动交互，避免重复骚扰。

  1. 配置管理

4.1 用户级主动交互配置

每个用户拥有独立的主动交互偏好，存储在数据库的 user_proactive_settings 表中，可通过对话指令修改（如“以后早上不要给我发消息”）。

配置项：

json
{
  "user_id": "u_abc123",
  "proactive_greeting_enabled": true,
  "proactive_frequency": "medium",
  "quiet_hours": ["23:00-07:00"],
  "max_proactive_per_day": 5,
  "event_trigger_enabled": true,
  "custom_wake_up_time": "07:30",
  "custom_sleep_time": "23:00",
  "important_dates": [
    {"date": "05-17", "description": "生日"},
    {"date": "03-21", "description": "入职纪念日"}
  ]
}

4.2 全局配置

configs/bot.yaml 中的主动系统部分：

yaml
proactive:
  enabled: true
  scheduler:
    timezone: "Asia/Shanghai"
    check_interval_seconds: 30
  greeting:
    morning:
      enabled: true
      default_time: "08:00"
    evening:
      enabled: true
      default_time: "22:30"
  event_triggers:
    weather_change: true
    user_silence: true
    silence_timeout_hours: 48
    emotion_alert: true
    emotion_low_days: 3
  rate_limit:
    max_proactive_per_user_per_day: 5
    global_max_per_hour: 1000
  message_generation:
    max_tokens: 150
    temperature: 0.8
  1. 与外部系统的交互接口

5.1 与记忆系统交互

· 获取用户画像：MemoryAPI.get_user_profile(user_id) → 获取作息、偏好、重要日期。 · 获取情绪趋势：MemoryAPI.get_emotion_trend(user_id, days=7) → 判断是否需要情绪关心。 · 获取最近情景：MemoryAPI.retrieve_context(user_id, "最近生活") → 为消息提供个性化素材。

5.2 与接入与通信系统交互

· 主动推送：将生成的 BotResponse 通过 ChannelManager.push_to_user(user_id, response) 发送。 · 获取在线状态：Gateway.get_user_online_status(user_id) → 判断是否正在对话中。

5.3 与人格与行为决策系统交互

· 获取人设：PersonaLoader.get_active_persona(user_id) → 决定消息风格。 · 模型调用：直接使用 AIService.generate() 生成消息文本。

5.4 与能力系统交互（可选）

· 主动消息中可以附带工具调用建议（如“需要我给你设个提醒吗？”），但需克制使用。

  1. 关键流程详解

6.1 早安问候流程

1. 定时器触发 (08:00)
2. 调度器检索所有启用早安问候的用户列表
3. 对每个用户并发执行:
   a. 检查在线状态 → 若活跃，跳过
   b. 检查克制策略 → 若在免打扰时段或达上限，跳过
   c. 获取记忆: 用户作息、今日日期是否有特殊事件、昨日情绪
   d. 构建个性化 Prompt
   e. 调用模型生成问候
   f. 通过通道发送
   g. 记录发送日志，增加计数器

6.2 用户静默检测流程

1. 事件监听引擎每 10 分钟扫描一次所有用户的最后活跃时间
2. 若某用户距离最后活跃时间超过 silence_timeout_hours
3. 提交静默关心任务给策略决策器
4. 策略决策器:
   a. 检查是否已在静默期内发送过关心（防止频繁打扰）
   b. 检查用户是否设置了"免打扰"
   c. 通过记忆获取用户可能静默的原因（出差、考试？）
   d. 生成一条轻量、自然的问候（如"最近忙吗？想你了"）
   e. 发送
  1. 扩展性设计

7.1 自定义触发器插件

开发者可按 Y.E.S. 规范开发自定义触发器，存于 configs/Plugins/proactive_triggers/。

插件结构：

yuanbot-trigger-weather/
├── manifest.json
├── trigger.py       # 实现 ProactiveTrigger 接口
└── README.md

接口：

python
class ProactiveTrigger(ABC):
    @abstractmethod
    def get_event_type(self) -> str:
        pass

    @abstractmethod
    async def check(self, user_id: str) -> bool:
        """检查是否满足触发条件"""
        pass

    @abstractmethod
    def get_priority(self) -> int:
        pass

7.2 主动消息模板市场

社区可贡献针对不同人设、不同场景的主动消息模板（如“傲娇型早安”），在扩展市场分发。

  1. 性能与可靠性

· 调度精度：基础调度循环每秒轮询，Cron 任务延迟 < 2 秒。 · 并发处理：用户检查、消息生成均为异步并发，支持数万用户规模。 · 持久化队列：若消息发送失败，任务存入 Redis 延迟队列，5 分钟后重试，最多 3 次。 · 监控：上报主动消息发送量、成功率、用户反馈（如用户回复“别发了”可自动降低频率）。

本详细设计完整定义了主动陪伴与自动化系统的内部机制，确保缘·Bot 能够以温柔、克制且高度个性化的方式，主动融入用户的数字生活。

Made with 🌸 by Grabrun

Copyright © 2026 YuanBot Team