nonebot-plugin-ai-turtle-soup 1.0.7

AI驱动的海龟汤(情境猜谜)游戏

📖 介绍

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

什么是海龟汤？

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

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

特色功能

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

💿 安装

先决条件

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

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

安装方法

通过文件安装

1. 在您的 pyproject.toml 中配置一个插件目录

plugin_dirs = ["src/plugins"]

您需要确保此目录存在，下文将使用 插件目录 代指此目录。

2. 下载本仓库

3. 将 src 文件夹中的 nonebot_plugin_ai_turtle_soup 文件夹解压到插件目录

4. 安装依赖

进入 requirements.txt 同目录下执行

pip install -r requirements.txt

通过 PIP 安装

1. 使用 pip 安装插件

pip install nonebot-plugin-ai-turtle-soup

2. 修改 pyproject.toml 在 plugins 中添加 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	否	题目编号，可用于指定题目
title	是	题目标题
tags	否	标签列表，用于筛选题目
puzzle_setting	是	汤面(给玩家看的谜题描述)
supplementary_info	是	补充信息列表(主持人回答的事实依据，同时作为游戏内提示，建议 10-12 条)
solution	是	汤底(完整真相)

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

🎉 使用

基本命令

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

游玩技巧

• ✅ 好的问题：

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

• ❌ 不好的问题：

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

多人游戏

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

⚠️ 注意事项

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