AstrBot 海龟汤推理游戏插件

一个为 AstrBot 开发的 AI 海龟汤推理游戏插件，通过调用 AstrBot 的 LLM 服务商实现自动生成谜题、接收用户提问、智能判断是否猜中故事等功能。

🌟 插件亮点

• ✅ 功能齐全：支持游戏创建、智能问答、完整推理验证、提示引导、题库管理等完整流程
• 🌐 网络题库支持：已爬取近 300 道高质量海龟汤题面，覆盖多种题材与风格
• 🧠 智能提示系统：结合全部提问记录生成方向提示，基于 allow_list 限制名词，引导玩家理清思路

🎮 功能特性

• 智能谜题来源 - 支持网络题库、本地存储库与 LLM 现场生成，可通过策略设置优先级
• 自动生成与存储 - 在指定时间段自动生成新故事并持久化存储备用题库
• 难度与提问/提示限制 - 简单/普通/困难/666开挂了四种难度，对应不同的提问次数与提示次数限制
• 智能问答系统 - 使用 LLM 判断用户提问并回复“是/否/是也不是/不重要”
• 验证系统 - 使用 LLM 验证用户提交的完整推理结果
• 提示系统 - 使用 LLM 根据问答历史生成方向性提示
• 题库使用记录 - 记录题目使用情况，可查看并重置
• 会话控制与超时机制 - 每个群一次仅允许一个游戏，且游戏超时自动结束
• 管理员功能 - 强制结束、备用故事管理与题库管理等实用指令
• 用户友好界面 - 清晰的状态显示、次数限制提示和操作指引

📋 使用指令

基础指令

• /汤 - 开始海龟汤游戏
• /查看 - 查看当前已提问的问题及回答
• /提示 - 获取方向性提示（参考当前所有提问与回答，有次数限制）
• /验证 <推理内容> - 验证用户对完整故事的推理，如果超过则结束游戏（有次数限制）
• /揭晓 - 查看完整故事并结束游戏
• /汤难度 <简单/普通/困难/666开挂了> - 设置游戏难度（默认普通）
• /汤状态 - 查看当前游戏状态
• /备用状态 - 查看备用故事存储库状态
• /汤配置 - 查看当前插件配置

管理员指令

• /强制结束 - 强制结束当前游戏（不会告知完整故事）
• /备用开始 - 手动开始生成备用故事
• /备用结束 - 停止生成备用故事
• /重置题库 - 重置网络题库和本地存储库的使用记录
• /题库详情 - 查看题库使用情况与已用索引

🎯 游戏流程

1. 开始游戏 - 用户发送 /汤
2. 获取谜题 - 按策略从网络题库、本地存储库或 LLM 生成
3. 公布题面 - 题面发布到群聊并启动会话控制
4. 用户互动
   • @机器人 + 任意陈述/问题（AI 回复：是、否、是也不是、不重要）
   • /验证 <推理内容> 验证完整推理过程
   • /提示 获取方向性提示（结合当前所有问答记录，有次数限制）
   • /查看 查看当前已提问的问题及回答
5. 游戏结束 - 用户输入 /揭晓 或验证成功时结束游戏

🔍 验证系统

用户可以通过 /验证 指令验证自己的完整推理过程：

除「简单」难度外，在提问次数用完前 /验证 指令最多可使用两次，用尽后会提示"已经没有验证次数了"。提问次数用完后仍可再次获得两次验证机会。提示功能也有相应的次数限制，不同难度对应不同的提示次数。

• 完全还原：推理与标准答案高度一致，包括核心逻辑与关键细节
• 核心推理正确：推理的大方向或关键反转已覆盖，但部分细节有出入
• 部分正确：理解了部分情节或动机，但因果链不完整
• 基本不符：推理与真相严重不符

在 简单 难度下，"完全还原"或"核心推理正确"均视为猜中；其他难度需要达到"完全还原"才算猜中。

💡 提示系统

用户可以通过 /提示 指令获取方向性提示：

不同难度对应不同的提示次数限制：

• 简单：10 次提示
• 普通：5 次提示
• 困难：1 次提示
• 666开挂了：无提示

提示系统会根据玩家此前的所有提问记录和已给出的提示，结合题面构建允许名词列表（allow_list），在此基础上生成不重复的方向性引导，帮助玩家调整思考方向。提示内容不会包含故事情节、动机、行为或结局的具体信息，仅围绕提问角度、方向、范围进行结构性引导，并以“关注【维度】：动词+对象/变量”的格式给出。提示次数用完后将无法继续使用。

🔧 技术特性

• LLM 集成 - 使用 AstrBot 的 Provider 接口调用大语言模型，支持生成、判断和提示功能
• 双 LLM 分离 - 支持分别配置生成谜题和判断问答/提示的 LLM 提供商
• 题库与存储 - 网络题库与本地存储库结合，支持自动生成、持久化和使用记录
• 会话管理 - 基于群聊的会话控制，支持多用户参与和指令处理
• 验证系统 - 智能验证用户推理的准确性和完整性
• 提示系统 - 基于问答历史生成方向性提示，帮助玩家调整思考方向
• 错误处理 - 完善的异常处理和边界情况处理
• 用户体验优化 - 智能提示、状态反馈和操作引导
• 状态持久化 - 游戏状态、题库使用记录和提示次数持久化保存

📦 依赖要求

• AstrBot >= v3.4.36
• 已配置 LLM 服务商（用于生成谜题、判断问答和生成提示）

🚀 安装使用

1. 将插件放置在 AstrBot/data/plugins/ 目录下
2. 在 AstrBot WebUI 的插件管理处启用插件
3. 在插件配置页面设置 LLM 提供商和其他参数
4. 确保已配置 LLM 服务商（推荐配置判断问答的 LLM 服务商以获得更好的提示效果）
5. 在群聊中使用 /汤 开始游戏

⚙️ 配置说明

插件支持以下配置项：

• 生成谜题的 LLM 服务商 - 选择用于生成海龟汤谜题的 LLM 服务商（留空使用默认）
• 判断问答的 LLM 服务商 - 选择用于判断用户问答和生成提示的 LLM 服务商
• 游戏超时时间 - 游戏超时时间（秒）
• 存储库最大容量 - 存储库最多保存多少个备用故事（默认 50）
• 自动生成开始时间 - 每天自动生成备用故事的开始时间（小时，24 小时制，默认 3）
• 自动生成结束时间 - 每天自动生成备用故事的结束时间（小时，24 小时制，默认 6）
• 谜题来源策略 - network_first（网络题库→本地存储库→LLM）、ai_first（本地存储库→网络题库→LLM）、random 随机选择

配置修改后需要重载插件生效。

📝 开发说明

本插件基于 AstrBot 插件开发框架构建，使用了以下核心功能：

• @register 装饰器注册插件
• @filter.command 注册指令处理器
• session_waiter 实现会话控制
• async def generate_hint(puzzle, true_answer, qa_history, hint_history, allow_list) 实现提示生成功能
• self.context.get_using_provider() 调用默认 LLM 服务
• self.context.get_provider_by_id() 调用指定的 LLM 服务商
• self.game_state.start_game() 支持提示次数初始化

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个插件！
作者是高中生，代码不完善，也可能没什么时间看issue，请多多包涵
或者加QQ群：1053727011，贡献你的海龟汤故事，一起玩海龟汤:D

TODO LIST

• 对于LLM生成的海龟汤进行评分，评分高的更新至网络题库中
• 记录足够的故事与评分，做成数据库上传至huggingface微调出专门的海龟汤LLM
• 修bug

📄 许可证

本项目采用 MIT 许可证。