---
title: MahjongGameDesigner
emoji: 🀄️
colorFrom: green
colorTo: yellow
sdk: gradio
sdk_version: 5.9.1
app_file: app.py
pinned: false
---
# 🀄️ 麻将玩法创意工坊
> AI 驱动的麻将玩法设计与迭代工具
[](https://huggingface.co/spaces/Estazz/MahjongGameDesigner_work_v1)
---
## ✨ 功能亮点
| 功能 | 说明 |
|------|------|
| 🎯 **多阶段引导** | Analyse 模式逐步收敛需求，避免一次性生成偏差 |
| 🔄 **可控迭代** | 基于 DesignState 做最小修改，支持范围锁定 |
| 📊 **差异可视化** | 每轮修改自动对比，清晰展示变更点 |
| 🕐 **版本历史** | 支持回滚到任意历史版本 |
| 💡 **方案发散** | AI 给出多个候选方案供选择 |
| ✅ **输出校验** | 自动检测 mGDL 完整性和逻辑守恒 |
---
## 📖 完整使用指南
👉 **[点击查看完整使用指南 (USER_GUIDE.md)](./USER_GUIDE.md)**
指南包含：
- 界面各部分详细说明
- 每个选项的作用和使用场景
- 推荐工作流程
- 高级功能教程
- 系统架构说明
- 常见问题解答
---
## 🚀 30秒快速开始
### 方式一：需求明确时
直接在输入框描述你的想法：
```
设计一个"血战+扎鸟"的麻将玩法，底座是四川血战，
融入贵州捉鸡的扎鸟机制，胡牌后扎鸟独立计分
```
点击发送，等待 AI 生成完整玩法。
### 方式二：需求不明确时
1. ☑️ 勾选 **Analyse 模式**
2. 输入初步想法："想做一个有扎鸟的血战麻将"
3. AI 会逐轮问你关键问题，帮你收敛需求
4. 当显示 `READY_TO_GENERATE: true` 时
5. 点击 **"基于当前 DesignState 生成完整玩法"**
---
## 📦 输出物
| 文件 | 内容 | 用途 |
|------|------|------|
| `gdl_output.txt` | mGDL v1.3 结构化描述 | 程序落地、规则引擎 |
| `narrative_output.txt` | 自然语言规则说明 | 策划评审、人工阅读 |
| `design_log_output.txt` | 设计日志 | 复核融合决策、追溯推演 |
---
## 🎮 核心控制选项说明
### 可控迭代控制区
| 选项 | 说明 |
|------|------|
| **启用可控迭代** | 基于上轮 DesignState 做最小修改（推荐开启） |
| **Analyse 模式** | 单问题迭代收敛需求，不生成 mGDL |
| **修改范围** | 限制 AI 本轮可修改的内容范围 |
### 细粒度范围控制
| 选项 | 说明 |
|------|------|
| **预设模式** | 使用预设的修改范围 |
| **自定义模式** | 手动锁定特定字段或机制 |
| **软约束** | 越界时提示但不阻断 |
| **硬约束** | 越界时阻断生成 |
### 版本与方案
| 功能 | 说明 |
|------|------|
| **版本历史** | 查看和回滚到历史版本 |
| **方案选择** | 从 AI 给出的多个方案中选择 |
| **重新发散** | 让 AI 给出更多不同方向的方案 |
---
## ⚙️ 环境变量配置
自部署时可通过环境变量调整：
```bash
# API 配置
DEEPSEEK_API_KEY=your-api-key
DEEPSEEK_BASE_URL=https://api.deepseek.com
MODEL_NAME=deepseek-chat
# 功能开关
ENABLE_REFERENCE_RETRIEVAL=1 # 参考玩法检索
REFERENCE_MAX_VARIANTS=3 # 最多注入几个参考
ENABLE_OUTPUT_VALIDATION=1 # 输出校验
```
---
## 🤔 常见问题
为什么 Analyse 模式不输出 mGDL？
Analyse 模式专注于"收敛需求"，通过逐轮问答明确设计方向。当 `READY_TO_GENERATE: true` 时，使用"一键生成"按钮获取完整输出。
为什么 AI 修改了我没要求改的部分？
1. 确保开启"可控迭代"
2. 选择更严格的"修改范围"
3. 使用"细粒度范围控制"锁定关键字段
4. 必要时回滚到之前的版本
如何保证规则逻辑正确？
1. 检查输出中的"动作—手牌变化表"
2. 验证"最小回合推演"是否闭环
3. 确认 mGDL 的 invariants 包含守恒约束
4. 参考设计日志中的推演记录
---
## 📚 内置参考资源
工具已预加载以下资源：
- **mGDL v1.3 语法规范**
- **麻将机制说明词典**（50+ 常见机制）
- **参考玩法库**：
- 四川血战/血流
- 红中麻将
- 长沙麻将
- 贵州捉鸡
- 广东100张/鸡平胡
- 武汉麻将
- 卡五星
- 等等...
系统会根据你的输入自动检索最相关的参考玩法。
---
## 🛠️ 技术栈
- **前端**：Gradio 5.x
- **AI**：DeepSeek V3 / OpenAI 兼容 API
- **语言**：Python 3.10+
---
## 📝 License
MIT License
---
*Made with ❤️ for Mahjong enthusiasts*