nonebot-plugin-ai-turtle-soup 1.0.9

📖 介绍

一个由 AI 驱动的海龟汤(情境猜谜)游戏插件，为 NoneBot2 机器人提供互动式推理游戏体验。

什么是海龟汤？

海龟汤(Situation Puzzle / Lateral Thinking Puzzle)是一种情境猜谜游戏：

• 🧩 系统给出一个离奇的情境描述(汤面)
• 🤔 玩家通过提出封闭式问题来推理
• 💡 AI 只能回答"是"、"否"或"不重要"
• 🎯 最终推理出完整的故事真相(汤底)

特色功能

• 🤖 AI 生成谜题 - 每次都能获得全新的创意谜题
• 📚 本地题库 - 支持从本地题库选题，人为保证题目质量并减少 token 消耗
• 🎮 智能主持 - AI 自动判断问题并给出合理答案
• 📊 进度跟踪 - 实时显示游戏进度百分比
• 💡 提示系统 - 卡关时可请求提示
• 🎨 主题定制 - 可指定主题生成特定类型的谜题
• 🔄 进度重算 - 支持重新评估当前进度

💿 安装

先决条件

在安装之前，请确保您的环境符合以下条件：

1. 拥有一个能够运行的 Python，版本在 3.9 及以上
2. 已经安装并配置好 pip 等任意一款 Python3 包管理器
3. 已经创建或拥有了一个 NoneBot2 机器人项目
4. 拥有可用的 OpenRouter API 或兼容的 API 服务

安装方法

plugin_dirs = ["src/plugins"]

pip install -r requirements.txt

pip install nonebot-plugin-ai-turtle-soup

⚙️ 配置

请在机器人目录中创建一个 .env 文件(或编辑对应 .env 文件，可能为 .env.dev 或 .env.prod)，然后将下方的配置内容复制进去并修改。

配置项说明

# OpenAI API Configuration - 生成谜题
ATS_OPENAI_GENERATE_API_KEY=
ATS_OPENAI_GENERATE_BASE_URL=https://api-inference.modelscope.cn/v1
ATS_OPENAI_GENERATE_MODEL=ZhipuAI/GLM-4.5 # 推荐使用 GLM-4.5 / GLM-4.6

# OpenAI API Configuration - 评判问题、刷新进度、谜题打分
ATS_OPENAI_JUDGE_API_KEY=
ATS_OPENAI_JUDGE_BASE_URL=https://openrouter.ai/api/v1
ATS_OPENAI_JUDGE_MODEL=x-ai/grok-4-fast # 推荐使用 grok-4-fast，最好是带 reasoning 的模型

# 出题方式配置
ATS_PUZZLE_SOURCE=ai        # 出题方式: ai - AI 生成谜题 / local - 从本地题库选题
ATS_LOCAL_PUZZLES_PATH=     # 本地题库路径，可以是单个 json 文件或包含多个 json 文件的目录

# 游戏配置
ATS_MAX_QUESTIONS=50  # 每局游戏最大提问次数
ATS_TIMEOUT=7200      # 游戏超时时间(秒)，默认2小时

配置说明

• 双 API 配置：插件使用两套 API 配置

  • GENERATE: 用于生成新谜题(需要较高创造力)
  • JUDGE: 用于游戏主持、回答问题、计算进度(需要较高准确性)
  • 可以配置为相同或不同的 API 服务

• API 兼容性：支持 OpenRouter API 以及任何兼容 OpenAI 格式的 API 服务

• 本地题库模式：将 ATS_PUZZLE_SOURCE 设置为 local 后，开始游戏时会从本地题库随机选题，不再调用 AI 出题(游戏主持仍由 JUDGE API 负责)。此模式可以人为保证题目质量，同时减少 token 消耗

  • 需要配置 ATS_LOCAL_PUZZLES_PATH 指向题库文件或目录
  • 使用本地题库模式时可以不配置 GENERATE API

本地题库格式

题库为 JSON 文件，格式请参考 docs/puzzles_template.json。每个题目包含以下字段：

本地题库模式下，/开始海龟汤 [关键词] 中的关键词会按题目 id、标题、标签进行匹配筛选；不带关键词则全库随机。

🎉 使用

基本命令

• /开始海龟汤 - 开始一局随机主题的新游戏
• /开始海龟汤 [主题] - 开始指定主题的新游戏(如: /开始海龟汤 密室)。本地题库模式下主题作为关键词，按题目 id、标题、标签筛选题目
• @bot <问题> - 向 AI 提问(需要是封闭式问题)
• @bot 查看进度 - 查看当前游戏进度和历史记录
• @bot 提示 - 获取一条提示信息
• @bot 重新计算进度 - 重新评估当前游戏进度
• @bot 放弃 - 放弃游戏并查看完整答案
• /海龟汤帮助 - 查看详细帮助信息

游玩技巧

• ✅ 好的问题：

  • "这是故意的吗？"
  • "他的身体有什么特殊情况吗？"
  • "这件事发生在室内吗？"
  • "时间因素重要吗？"

• ❌ 不好的问题：

  • "发生了什么？"(太开放)
  • "他为什么这么做？"(无法用是/否回答)
  • "是不是A或者B？"(无法用单个是/否回答)

多人游戏

• 支持群组和频道内多人协作
• 每个群组/频道独立维护游戏状态
• 所有成员都可以提问
• 建议协作讨论，共同推理

⚠️ 注意事项

• 本插件需要调用 LLM API，可能会产生相应的 API 费用
• 建议设置合理的 ATS_MAX_QUESTIONS 以控制单局游戏的 API 调用次数
• 游戏会话会在超时时间(ATS_TIMEOUT)后自动清除