README.md

metadata

title: MahjongGameDesigner
emoji: 🀄️
colorFrom: green
colorTo: yellow
sdk: gradio
sdk_version: 5.9.1
app_file: app.py
pinned: false

🀄️ 麻将玩法创意工坊

AI 驱动的麻将玩法设计与迭代工具

---

✨ 功能亮点

功能	说明
🎯 多阶段引导	Analyse 模式逐步收敛需求，避免一次性生成偏差
🔄 可控迭代	基于 DesignState 做最小修改，支持范围锁定
📊 差异可视化	每轮修改自动对比，清晰展示变更点
🕐 版本历史	支持回滚到任意历史版本
💡 方案发散	AI 给出多个候选方案供选择
✅ 输出校验	自动检测 mGDL 完整性和逻辑守恒

---

📖 完整使用指南

👉 点击查看完整使用指南 (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 给出更多不同方向的方案

---

⚙️ 环境变量配置

自部署时可通过环境变量调整：

# 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