🎲 Yunzai-BGG-Plugin (TRSS-Yunzai 桌游查询插件)

June 9, 2026 · View on GitHub

🎲 Yunzai-BGG-Plugin (TRSS-Yunzai 桌游查询插件)

基于 TRSS-Yunzai 框架的桌游信息查询插件，支持通过中文名智能搜索桌游，获取 BGG / 集石 的详细数据，并支持 AI 智能翻译与多搜索引擎聚合。

本插件为 maibot-bgg-plugin 的 Yunzai 移植版，两个插件均由本人维护，但我会优先维护 maibot 版本，Yunzai 版本更新优先级较低。 当年椰奶插件（Yenai-Plugin）的桌游搜索功能亦为我编写，感谢 AI，现在我能自己长期维护该功能了。本插件已通过指令优先级“抢指令”的方式兼容椰奶的桌游搜索功能。 无论是当年的椰奶版本还是现在这个，全部由 AI 编写，如遇问题可随时找我，我会尽力修复。

✨ 功能特性

  • 🇨🇳 中文智能搜索：输入中文名即可查询，无需记忆复杂的英文原名。
  • 📚 多数据源融合：
    • 集石：优先获取中文评分、分类、语言依赖等本土化信息。
    • BGG API：获取最权威的排名、评分、机制、最佳人数等数据。
    • BGG 网页抓取：API 失败时的兜底方案，保证高可用。
    • 兼容锅巴：可使用锅巴插件进行配置修改，方便简洁。
  • 🔍 聚合搜索引擎：
    • 集成 DuckDuckGo 与 Tavily 双搜索引擎。
    • Tavily 的 AI 摘要能力极大提升了对生僻中文译名的英文名提取准确率。
  • 🤖 AI 智能翻译：接入大语言模型 (LLM)，自动将 BGG 的游戏类型、机制和简介翻译为准确的中文。
  • 🏷️ 自定义别名登记：支持用户自定义中英文映射，解决部分翻译差异问题。

📦 安装

在 TRSS-Yunzai 根目录下执行：

git clone https://github.com/your-repo/yunzai-bgg-plugin.git plugins/yunzai-bgg-plugin

进入插件目录安装依赖：

cd plugins/yunzai-bgg-plugin
pnpm install

依赖说明：本插件依赖 cheerio 和 fast-xml-parser。 环境要求：Node.js >= 18（使用了原生 fetch 和 AbortSignal.timeout）。

📂 插件文件结构

yunzai-bgg-plugin/
├── apps/
│   └── boardgame.js         # 🎮 指令处理层：接收用户消息、格式化输出结果、处理异常
├── lib/
│   ├── bgg_client.js        # 🧠 核心调度层：整合各数据源，执行搜索排序与详情获取的主流程
│   ├── ddg_client.js        # 🔍 聚合搜索层：并发调用 DDG 和 Tavily，合并去重后交由 LLM 提取
│   ├── tavily_client.js     # 🤖 搜索引擎：Tavily API 专用客户端（结构化搜索+AI摘要）
│   ├── jishi_client.js      # 🇨🇳 数据源：集石 爬虫客户端（绕过反爬处理）
│   ├── web_client.js        # 🌐 数据源：BGG 网页抓取客户端（API限流时的备用方案）
│   ├── llm_client.js        # 💬 AI 服务：调用 LLM 进行英文名提取和全文翻译
│   ├── utils.js             # 🔧 基础工具：常量定义、配置文件读取、公共函数
│   └── register.js          # 🏷️ 数据管理：用户自定义别名 (alias.json) 的读写与删减
├── config/
│   ├── default_config/
│   │   └── config.yaml      # 📄 默认配置模板（含详细注释，请勿直接修改）
│   └── config/              # 📁 实际配置目录（首次启动自动从上方模板复制生成）
│       └── config.yaml      # ⚙️ 用户配置文件（修改此文件生效）
├── data/                    # 📊 运行数据目录（自动生成）
│   ├── alias.json           # 🏷️ 别名数据库：保存 #桌游登记 指令写入的数据
│   └── terms.json           # 📖 术语词典：BGG机制/类型的本地中英对照翻译库
├── index.js                 # 🚀 Yunzai 插件标准入口文件
├── package.json             # 📦 Node.js 模块声明与依赖管理
└── README.md                # 📝 本说明文档

⚙️ 配置

首次运行后，会在 plugins/yunzai-bgg-plugin/config/config/ 目录下生成 config.yaml，请根据需要修改： 已兼容锅巴插件，推荐采用锅巴插件进行修改，不推荐自行修改

🎮 使用说明

因为技术力不够+本身加起来就两个指令，所以没整帮助图，推荐自行在锅巴插件通过修改猫猫帮助图来记下这个指令就算了

查询桌游

发送指令：

#桌游帮助

#桌游搜索 <桌游名称>

示例：

#桌游搜索 肥肠面
#桌游搜索 卡坦岛
#桌游搜索 Terraforming Mars

登记别名

当某些游戏的中文名搜索不准时，可以手动登记别名：

#桌游登记 <中文名>/<英文名>

示例：

#桌游登记 伯明翰/Brass: Birmingham

删除别名

#桌游登记 <中文名>/删除

清空所有别名

#桌游登记 清空

🛠️ 工作流程

当你输入 #桌游搜索 肥肠面 时，插件会经历以下智能流转：

  1. 查本地词典：如果用户登记过别名，直接使用别名。
  2. 查集石：使用集石搜索，若匹配到且带有 BGG ID，直接去 BGG 拿详情。
  3. 聚合搜索兜底：若集石无 BGG ID 或无结果，并发调用 DuckDuckGo 和 Tavily 搜索。
  4. AI 提取英文名：将搜索引擎返回的结果喂给 LLM，让 AI 精准提取出游戏的英文原名。
  5. BGG API 查询：用提取出的英文名去 BGG API (V2/V1) 查询详情。
  6. 网页抓取兜底：若 BGG API 挂了或限流，回退到爬取 BGG 网页。
  7. AI 翻译：最终拿到 BGG 数据后，调用 LLM 将类型、机制和简介翻译为中文并返回。

📜 许可证

本项目使用 MIT 许可证开源。