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

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

## 这是什么

MahjongGameDesigner 是一个“麻将玩法生成与迭代”工具，输出三类交付物：
- **自然语言规则说明**（可直接给策划/制作/评审）
- **mGDL v1.3**（结构化规则描述，用于规范化与落地）
- **思维日志（设计日志）**（融合清单、冲突桥接、推演摘要、落地映射，便于人工复核）

工具提供两种关键能力：
- **Analyse 模式（单问题迭代）**：通过多轮问答把需求场景收敛到可生成状态（不生成 mGDL）
- **可控迭代（DesignState 驱动）**：基于上轮 DesignState 做最小修改，并限制本轮允许修改范围，减少漂移

## 快速开始（推荐流程）

### 1) 先用 Analyse 模式把需求收敛
1. 勾选：`Analyse 模式：单问题迭代完善需求（不生成mGDL）`
2. 在聊天框描述你的目标（例：想做“血战类 + 扎鸟机制 + 更强互动”的新玩法）
3. 模型每轮只会问你 1 个最关键问题，并输出：
   - 本轮增量思维日志（≤200字）
   - DesignState(JSON)
   - `READY_TO_GENERATE: true/false`
4. 当 READY 为 true（或你认为信息已经足够），进入第2步

### 2) 一键生成完整玩法交付物
点击按钮：`基于当前 DesignState 生成完整玩法`

生成完成后可下载：
- `gdl_output.txt`（mGDL）
- `narrative_output.txt`（自然语言规则）
- `design_log_output.txt`（思维日志 / 设计日志）

### 3) 继续可控迭代（局部优化而不重写）
1. 取消勾选 Analyse 模式
2. 勾选：`启用可控迭代：基于上轮 DesignState 做最小修改`
3. 选择“本轮允许修改范围”（例如：仅优化创新机制）
4. 输入你的改动诉求（例：把主机制触发从“胡牌后”改成“听牌后”，并降低随机性）

系统会在输出后做一次“范围越界”提示（软提示，不会中断生成），帮助你保持“最小修改、低漂移”的多轮迭代。

## 输出与导出

- 自然语言与 mGDL 会自动从模型输出中提取并保存到 `exports/` 下
- 思维日志会从 `### 设计日志（创新推演摘要）` 段落提取并保存到 `exports/design_log_output.txt`
- 在 Analyse 模式下不会导出上述文件（因为 Analyse 模式不生成完整交付物）

## 当前阶段的规则准确性重点（必读）

现阶段主要聚焦“既有机制组合”，但必须保证麻将底层物理逻辑准确（手牌守恒、吃碰杠轮次、牌墙转移等）。因此生成模式下请重点检查输出是否包含并一致：
- 《动作—手牌变化—轮次影响表》
- 3段《最小回合推演》（普通/碰/杠，每行标注手牌张数变化）
- mGDL 的 `(invariants ...)` 中包含牌数守恒与“回合结束手牌恒为13”的约束

## 生成质量增强（默认开启）

为提升“玩法理解”与“创新落地”，系统默认会自动注入：
- `m_prompt.txt`：系统提示词规范（含自检、最小修复、输出格式）
- `麻将游戏mGDL通用语法_v1.3.txt`：mGDL v1.3 语法约束（用于保证输出形式）
- 与用户输入最相关的少量参考玩法 `.md`（规则真理，RAG 语义参考）
- `麻将机制说明.md`：机制词典（用于创新机制选型）

## 环境变量（可选）

### API / 模型
- `DEEPSEEK_API_KEY`：API Key
- `DEEPSEEK_BASE_URL`：OpenAI 兼容 Base URL
- `MODEL_NAME`：模型名

### RAG / 参考注入
- `ENABLE_REFERENCE_RETRIEVAL=1|0`：是否启用参考玩法检索注入（默认 1）
- `REFERENCE_MAX_VARIANTS=3`：最多注入多少个参考玩法（默认 3）
- `INJECT_REFERENCE_MGDL=1|0`：是否注入参考玩法 mGDL（默认 0；通常不建议，语义参考以 .md 为主）
- `INJECT_ALL_EXAMPLE_GDL=1|0`：是否额外注入全量示例 mGDL（默认 0，不推荐）

### 校验与修复
- `ENABLE_OUTPUT_VALIDATION=1|0`：是否对生成结果做静态校验提示（默认 1）
- `ENABLE_AUTO_REPAIR=1|0`：非流式路径下是否自动触发一次“最小修改修复”（默认 0）

## 常见问题

### 为什么 Analyse 模式不输出 mGDL？
Analyse 模式的目标是“收敛需求”，每轮只问 1 个关键问题并更新 DesignState，避免边问边生成导致漂移。READY 后请用“一键生成”得到完整交付物。

### 为什么会看到“静态校验”提示？
生成模式下，系统会对输出做轻量检查（例如缺少 mGDL、缺少核心模块、缺少设计日志等）。这只是提示，不会阻断；你也可以在环境变量中关闭校验提示。