心流插件 (Heartflow)

基于双LLM架构设计的简单心流模式智能群聊主动回复系统

🌟 功能特色

• 智能判断：使用小参数模型快速判断是否需要回复群聊消息
• 高质量回复：使用AstrBot配置的大型LLM生成自然流畅的回复
• 群聊隔离：每个群聊独立的状态管理和精力系统
• 频率控制：智能控制回复频率，避免过度活跃
• 配置灵活：支持多种参数调节，适应不同群聊环境

🏗️ 架构设计

判断小模型 (用户配置) → 快速决策 → 大型回复模型 (AstrBot现有配置) → 高质量回复

🏗️ 推荐使用模型

Gemma 27b，可在Google Aistudio获取密钥后使用，每天免费14400次，基本满足需求

判断维度

1. 内容相关度 (0-10)：消息是否有价值、有趣、适合回复
2. 回复意愿 (0-10)：基于当前精力状态的回复意愿
3. 社交适宜性 (0-10)：回复是否符合群聊氛围
4. 时机恰当性 (0-10)：考虑频率控制和时间间隔

⚙️ 配置说明

必要配置

1. 启用插件：enable_heartflow = true
2. 小参数判断模型配置：judge_provider_name：在AstrBot中配置的提供商名称

可选配置

• reply_threshold：回复阈值 (0-1，默认0.6)
• energy_decay_rate：精力衰减速度 (默认0.1)
• energy_recovery_rate：精力恢复速度 (默认0.02)
• context_messages_count：上下文消息数量 (默认5)

白名单配置

• whitelist_enabled：启用群聊白名单 (默认false)
• chat_whitelist：群聊白名单列表 (默认[])

白名单使用说明

当启用白名单模式时，只有在白名单中的群聊才会触发心流回复：

获取群聊ID的方法：

1. 在目标群聊中发送 /sid 命令
2. 查看返回的状态报告，复制显示的sid
3. 将完整的ID添加到白名单配置中

🚀 使用指南

1. 安装配置

1. 将插件放置在 packages/heartflow/ 目录
2. 重启AstrBot加载插件
3. 在插件配置中设置判断模型提供商名称
4. 启用插件：enable_heartflow = true
5. 可选：配置群聊白名单限制插件作用范围

2. 管理命令

• /heartflow：查看当前群聊的心流状态
• /heartflow_reset：重置当前群聊的心流状态

📊 状态说明

精力系统

• 精力值范围：0.1 - 1.0
• 消耗机制：每次主动回复后精力下降
• 恢复机制：不回复时精力缓慢恢复，每日重置时额外恢复

🔧 高级配置

权重调整

插件内置权重配置：

weights = {
    "relevance": 0.3,      # 内容相关度权重
    "willingness": 0.25,   # 回复意愿权重  
    "social": 0.25,        # 社交适宜性权重
    "timing": 0.2          # 时机恰当性权重
}

群聊个性化

可以通过修改代码实现不同群聊的个性化配置：

• 技术群：提高相关度权重
• 闲聊群：提高社交适宜性权重
• 工作群：提高时机恰当性权重

📈 监控建议

1. 观察回复质量：调整回复阈值
2. 监控回复频率：调整精力参数和时间间隔
3. 分析判断日志：优化判断提示词
4. 收集用户反馈：持续改进回复策略

🔍 故障排除

常见问题

1. 不回复任何消息

   • 检查判断模型提供商配置是否正确
   • 确认插件已启用
   • 检查是否启用了白名单但当前群聊不在白名单中
   • 查看日志中的错误信息

2. 回复过于频繁

   • 提高回复阈值
   • 减少每日最大回复数
   • 增加精力衰减速度

3. 回复质量不佳

   • 检查AstrBot的LLM配置
   • 优化判断提示词
   • 调整权重配置

4. 特定群聊不回复

   • 检查白名单配置是否正确
   • 确认群聊ID是否在白名单中
   • 查看debug日志确认过滤原因

日志信息

• 💖 心流主动回复：成功回复的日志
• 心流判断通过但被最终检查拦截：判断通过但被频率控制拦截
• 更新主动状态/被动状态：状态更新日志

🤝 贡献

欢迎提交Issue和Pull Request来改进这个插件！

📄 许可证

本插件遵循AstrBot的开源许可证。