Spaces:
Sleeping
Sleeping
| 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 # 输出校验 | |
| ``` | |
| --- | |
| ## 🤔 常见问题 | |
| <details> | |
| <summary><b>为什么 Analyse 模式不输出 mGDL？</b></summary> | |
| Analyse 模式专注于"收敛需求"，通过逐轮问答明确设计方向。当 `READY_TO_GENERATE: true` 时，使用"一键生成"按钮获取完整输出。 | |
| </details> | |
| <details> | |
| <summary><b>为什么 AI 修改了我没要求改的部分？</b></summary> | |
| 1. 确保开启"可控迭代" | |
| 2. 选择更严格的"修改范围" | |
| 3. 使用"细粒度范围控制"锁定关键字段 | |
| 4. 必要时回滚到之前的版本 | |
| </details> | |
| <details> | |
| <summary><b>如何保证规则逻辑正确？</b></summary> | |
| 1. 检查输出中的"动作—手牌变化表" | |
| 2. 验证"最小回合推演"是否闭环 | |
| 3. 确认 mGDL 的 invariants 包含守恒约束 | |
| 4. 参考设计日志中的推演记录 | |
| </details> | |
| --- | |
| ## 📚 内置参考资源 | |
| 工具已预加载以下资源： | |
| - **mGDL v1.3 语法规范** | |
| - **麻将机制说明词典**（50+ 常见机制） | |
| - **参考玩法库**： | |
| - 四川血战/血流 | |
| - 红中麻将 | |
| - 长沙麻将 | |
| - 贵州捉鸡 | |
| - 广东100张/鸡平胡 | |
| - 武汉麻将 | |
| - 卡五星 | |
| - 等等... | |
| 系统会根据你的输入自动检索最相关的参考玩法。 | |
| --- | |
| ## 🛠️ 技术栈 | |
| - **前端**：Gradio 5.x | |
| - **AI**：DeepSeek V3 / OpenAI 兼容 API | |
| - **语言**：Python 3.10+ | |
| --- | |
| ## 📝 License | |
| MIT License | |
| --- | |
| *Made with ❤️ for Mahjong enthusiasts* | |