# 谐音梗插件

**Repository Path**: wind-trace-typ/xieyin-plugin

## Basic Information

- **Project Name**: 谐音梗插件
- **Description**: 官机专用谐音梗插件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-19
- **Last Updated**: 2026-07-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 谐音梗猜谜 (xieyin-plugin)

基于 [Yunzai-Bot](https://github.com/Le-niao/Yunzai-Bot) 的趣味群聊小游戏插件。

看图猜成语 / 词语：机器人发送两张谐音梗图片，群友根据画面猜出对应的词语或成语，答对即可为本群积分榜加分。

> ⚠️ **运行环境限制**：本插件仅在 **QQBot 官方机器人适配器（`adapter_id === 'QQBot'`）** 且 **群聊（`isGroup`）** 中生效，私聊与其他适配器不会响应。

## 玩法说明

1. 发送 `#谐音梗` 获取一题，机器人会同时下发两张图片与一条提示（题面类型、空白答案位）。
2. 题目有效期 **3 分钟**，超时后自动公布答案并刷新下一题。
3. 发送 `#猜 <你的答案>` 抢答，例如 `#猜好久不见`。原词或谐音后词正确均可。
4. 答对后自动加分并 **2 秒后** 自动出下一题；同一题仅首位答对者得分。
5. 可随时发送 `#谐音梗答案` 直接公布答案（视为放弃本题，也会刷新下一题）。
6. 发送 `#谐音梗排行` 查看本群 **TOP10 积分榜**。

## 命令一览

| 指令 | 功能 |
| --- | --- |
| `#谐音梗` | 开始新一题（带图片与提示） |
| `#猜 <答案>` / `#猜谐音梗 <答案>` | 提交猜测，抢答加分 |
| `#谐音梗答案` | 查看答案并刷新下一题 |
| `#谐音梗排行` | 查看本群积分排行 TOP10 |

## 功能特点

- **看图猜词**：每题由两张图片组成双格拼图，直观有趣。
- **群积分排行**：基于 Redis 的 `zset` 按群独立计分，支持 TOP10 群榜。
- **并发安全**：使用 Redis 分布式锁防止多人同时抢答时的重复加分。
- **防刷机制**：出题带 8 秒冷却（`#谐音梗` 频率限制）。
- **自动流转**：答对 / 查看答案后自动刷新，超时自动公布答案。
- **海量题库**：内置 1935 道题目，覆盖成语、词语、食物、地名、人物、品牌、节日等多个主题。

## 项目结构

```
xieyin-plugin/
├── index.js                  # 入口：构建图片映射、注册 app
├── apps/
│   └── xieyin.js            # 核心游戏逻辑（出题/抢答/排行）
├── lib/
│   └── data.js             # 数据加载、图片映射、随机选题
├── resources/
│   ├── data/                # 题库数据
│   │   ├── levels_answers.json   # 主题库（1935 道，含答案与谐音解析）
│   │   ├── category_*.json       # 各分类题目索引（如篮球/美食/春节等）
│   │   └── nobadpun_*.json       # 无谐音梗玩法专用数据
│   └── images/              # 图片资源（每题两张：w{id}-1.png / w{id}-2.png）
│       ├── 1-1000/ ... 7001-8000/   # 按 id 分桶存放
│       └── ColorBoost/             # 彩色增强图片
└── README.md
```

## 题目数据格式

主题库 `resources/data/levels_answers.json` 每道题目结构如下：

```json
{
  "id": 0,
  "original_phrase": "好久不见",   // 正确答案（原词）
  "pun_word": "酒",                // 谐音字
  "punned_phrase": "好酒不见",     // 谐音后的趣味表达
  "pinyin": ["hao3", "jiu3", "bu2", "jian4"],
  "category": "词语",              // 题面类型提示
  "category_code": "CiCi"
}
```

图片命名规则：`w{id}-1.png` 与 `w{id}-2.png` 共同构成一题的画面，按 `id` 落入对应分桶目录。

## 安装

在 Yunzai 根目录下执行：

```bash
git clone https://gitee.com/wind-trace-typ/xieyin-plugin.git ./plugins/xieyin-plugin
```

克隆后重启 Yunzai 即可在 QQBot 群聊中使用 `#谐音梗` 开始游戏。

## 依赖与存储

- 题目状态、锁、冷却、积分均存储在 **Redis** 中（Key 前缀 `Yz:xieyin`）。
- 请确保运行环境已配置可用的 Redis 实例。

## 交流群

欢迎加入 [@windtrace/qq-group-bot](https://qm.qq.com/q/kbnsSP7aSI) 与大家一起交流讨论！

## 致谢

感谢所有为项目提供题库资源与图片素材的贡献者！