Upgrade controllable iteration: analyse mode + design log export

README.md

@@ -11,18 +11,79 @@ pinned: false
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 
-## 生成质量增强开关（可选）
+## 这是什么
 
-本项目默认会在对话中自动注入：
-- `m_prompt.txt`（系统提示词规范）
-- `麻将游戏mGDL通用语法_v1.3.txt`（mGDL v1.3 语法）
-- 与用户输入最相关的少量参考玩法（`.md` 主真理 + `_mGDL_v1.3.txt` 辅语法翻译）
-- `麻将机制说明.md`（机制词典）
+MahjongGameDesigner 是一个“麻将玩法生成与迭代”工具，输出三类交付物：
+- **自然语言规则说明**（可直接给策划/制作/评审）
+- **mGDL v1.3**（结构化规则描述，用于规范化与落地）
+- **思维日志（设计日志）**（创新机制的候选方案、取舍理由、推演摘要、落地映射）
 
-可通过环境变量控制：
-- `ENABLE_REFERENCE_RETRIEVAL=1|0`：是否启用“参考玩法检索注入”（默认 1）
+工具提供两种关键能力：
+- **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 模式不生成完整交付物）
+
+## 生成质量增强（默认开启）
+
+为提升“玩法理解”与“创新落地”，系统默认会自动注入：
+- `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；通常不建议，RAG语义参考以 .md 为主）
+- `INJECT_REFERENCE_MGDL=1|0`：是否注入参考玩法 mGDL（默认 0；通常不建议，语义参考以 .md 为主）
 - `INJECT_ALL_EXAMPLE_GDL=1|0`：是否额外注入全量示例 mGDL（默认 0，不推荐）
-- `ENABLE_OUTPUT_VALIDATION=1|0`：是否对输出做静态校验（默认 1）
+
+### 校验与修复
+- `ENABLE_OUTPUT_VALIDATION=1|0`：是否对生成结果做静态校验提示（默认 1）
 - `ENABLE_AUTO_REPAIR=1|0`：非流式路径下是否自动触发一次“最小修改修复”（默认 0）
+
+## 常见问题
+
+### 为什么 Analyse 模式不输出 mGDL？
+Analyse 模式的目标是“收敛需求”，每轮只问 1 个关键问题并更新 DesignState，避免边问边生成导致漂移。READY 后请用“一键生成”得到完整交付物。
+
+### 为什么会看到“静态校验”提示？
+生成模式下，系统会对输出做轻量检查（例如缺少 mGDL、缺少核心模块、缺少设计日志等）。这只是提示，不会阻断；你也可以在环境变量中关闭校验提示。