README.md

metadata

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、缺少核心模块、缺少设计日志等）。这只是提示，不会阻断；你也可以在环境变量中关闭校验提示。