Upload folder using huggingface_hub

.gradio/certificate.pem

@@ -0,0 +1,31 @@
+-----BEGIN CERTIFICATE-----
+MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2OCiwAwDQYJKoZIhvcNAQELBQAw
+TzELMAkGA1UEBhMCVVMxKTAnBgNVBAoTIEludGVybmV0IFNlY3VyaXR5IFJlc2Vh
+cmNoIEdyb3VwMRUwEwYDVQQDEwxJU1JHIFJvb3QgWDEwHhcNMTUwNjA0MTEwNDM4
+WhcNMzUwNjA0MTEwNDM4WjBPMQswCQYDVQQGEwJVUzEpMCcGA1UEChMgSW50ZXJu
+ZXQgU2VjdXJpdHkgUmVzZWFyY2ggR3JvdXAxFTATBgNVBAMTDElTUkcgUm9vdCBY
+MTCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAK3oJHP0FDfzm54rVygc
+h77ct984kIxuPOZXoHj3dcKi/vVqbvYATyjb3miGbESTtrFj/RQSa78f0uoxmyF+
+0TM8ukj13Xnfs7j/EvEhmkvBioZxaUpmZmyPfjxwv60pIgbz5MDmgK7iS4+3mX6U
+A5/TR5d8mUgjU+g4rk8Kb4Mu0UlXjIB0ttov0DiNewNwIRt18jA8+o+u3dpjq+sW
+T8KOEUt+zwvo/7V3LvSye0rgTBIlDHCNAymg4VMk7BPZ7hm/ELNKjD+Jo2FR3qyH
+B5T0Y3HsLuJvW5iB4YlcNHlsdu87kGJ55tukmi8mxdAQ4Q7e2RCOFvu396j3x+UC
+B5iPNgiV5+I3lg02dZ77DnKxHZu8A/lJBdiB3QW0KtZB6awBdpUKD9jf1b0SHzUv
+KBds0pjBqAlkd25HN7rOrFleaJ1/ctaJxQZBKT5ZPt0m9STJEadao0xAH0ahmbWn
+OlFuhjuefXKnEgV4We0+UXgVCwOPjdAvBbI+e0ocS3MFEvzG6uBQE3xDk3SzynTn
+jh8BCNAw1FtxNrQHusEwMFxIt4I7mKZ9YIqioymCzLq9gwQbooMDQaHWBfEbwrbw
+qHyGO0aoSCqI3Haadr8faqU9GY/rOPNk3sgrDQoo//fb4hVC1CLQJ13hef4Y53CI
+rU7m2Ys6xt0nUW7/vGT1M0NPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNV
+HRMBAf8EBTADAQH/MB0GA1UdDgQWBBR5tFnme7bl5AFzgAiIyBpY9umbbjANBgkq
+hkiG9w0BAQsFAAOCAgEAVR9YqbyyqFDQDLHYGmkgJykIrGF1XIpu+ILlaS/V9lZL
+ubhzEFnTIZd+50xx+7LSYK05qAvqFyFWhfFQDlnrzuBZ6brJFe+GnY+EgPbk6ZGQ
+3BebYhtF8GaV0nxvwuo77x/Py9auJ/GpsMiu/X1+mvoiBOv/2X/qkSsisRcOj/KK
+NFtY2PwByVS5uCbMiogziUwthDyC3+6WVwW6LLv3xLfHTjuCvjHIInNzktHCgKQ5
+ORAzI4JMPJ+GslWYHb4phowim57iaztXOoJwTdwJx4nLCgdNbOhdjsnvzqvHu7Ur
+TkXWStAmzOVyyghqpZXjFaH3pO3JLF+l+/+sKAIuvtd7u+Nxe5AW0wdeRlN8NwdC
+jNPElpzVmbUq4JUagEiuTDkHzsxHpFKVK7q4+63SM1N95R1NbdWhscdCb+ZAJzVc
+oyi3B43njTOQ5yOf+1CceWxG1bQVs5ZufpsMljq4Ui0/1lvh+wjChP4kqKOJ2qxq
+4RgqsahDYVvTH9w7jXbyLeiNdd8XM2w9U/t7y0Ff/9yi0GE44Za4rF2LN9d11TPA
+mRGunUHBcnWEvgJBQl9nJEiU0Zsnvgc/ubhPgXRR4Xq37Z0j4r7g1SgEEzwxA57d
+emyPxgcYxn/eR44/KJ4EBs+lVDR3veyJm+kXQ99b21/+jh5Xos1AnX5iItreGCc=
+-----END CERTIFICATE-----

README.md

@@ -1,12 +1,40 @@
 ---
-title: GDL2IR V2
-emoji: 🦀
-colorFrom: indigo
-colorTo: green
+title: GDL2IR_V2
+app_file: app.py
 sdk: gradio
 sdk_version: 5.49.1
-app_file: app.py
-pinned: false
 ---
+# GDL2IR v2 — Gradio Web UI
+
+## 安装依赖
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## 运行 Web UI
+
+```bash
+python app.py
+```
+
+启动后访问 `http://127.0.0.1:7860`。
+
+## 使用说明
+- 上传 GDL 文本（.txt/.gdl）。
+- 可选：上传 `poker_gdl_ir.schema.v0.95.zh.json`（若不上传，将自动在当前目录下寻找）。
+- 点击“运行转换与校验”，下方可以预览与下载：
+  - IR JSON
+  - Issues JSON（Schema 校验结果）
+  - 自检报告 Markdown
+
+## 命令行用法（可选）
+仍可使用原命令行：
+
+```bash
+python cli_v2.py uno_gdl.txt
+```
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+会在同目录输出 `.ir.v0.95.json`、`.issues.json`、`.selfcheck.md`。

app.py

@@ -0,0 +1,188 @@
+# -*- coding: utf-8 -*-
+"""
+Gradio Web UI for GDL -> IR(v0.95) pipeline
+
+功能：
+- 上传 GDL 文本文件（.txt/.gdl）与可选 Schema（默认自动发现 poker_gdl_ir.schema.v0.95.zh.json）
+- 运行 parse -> normalize -> map_to_v095 -> validate -> report 全流程
+- 在线预览 IR(JSON)、Issues(JSON)、Report(Markdown)
+- 支持将结果作为文件下载
+"""
+from __future__ import annotations
+
+import io
+import json
+import pathlib
+from typing import Tuple, Any
+import tempfile
+
+import gradio as gr
+
+from gdl_parser_v2 import parse_gdl
+from normalizer_v2 import normalize_ir
+from mapper_v2 import map_to_v095
+from validator_v2 import validate_with_schema
+from gap_detector_v2 import make_report
+
+
+def _auto_discover_schema(cli_arg: str | None) -> pathlib.Path:
+    candidates = []
+    if cli_arg:
+        candidates.append(cli_arg)
+    here = pathlib.Path(__file__).resolve().parent
+    candidates.append(str(here / "poker_gdl_ir.schema.v0.95.zh.json"))
+    candidates.append("poker_gdl_ir.schema.v0.95.zh.json")
+    candidates.append("/mnt/data/poker_gdl_ir.schema.v0.95.zh.json")
+    for c in candidates:
+        try:
+            p = pathlib.Path(c)
+            if p.exists():
+                return p
+        except Exception:
+            pass
+    raise FileNotFoundError("未找到 Schema。请上传或将 poker_gdl_ir.schema.v0.95.zh.json 放在程序目录/当前目录。")
+
+
+def _read_as_bytes(maybe_file: Any) -> bytes:
+    # Gradio File with type="binary" returns bytes directly.
+    if maybe_file is None:
+        raise gr.Error("未提供文件")
+    if isinstance(maybe_file, (bytes, bytearray)):
+        return bytes(maybe_file)
+    if isinstance(maybe_file, str):  # filepath
+        return pathlib.Path(maybe_file).read_bytes()
+    if hasattr(maybe_file, "read") and callable(getattr(maybe_file, "read")):
+        return maybe_file.read()
+    if isinstance(maybe_file, dict):
+        data = maybe_file.get("data")
+        if isinstance(data, (bytes, bytearray)):
+            return bytes(data)
+    raise gr.Error("无法读取上传的文件内容")
+
+
+def run_pipeline(gdl_file: Any, schema_file: Any | None) -> Tuple[str, str, str, bytes, bytes, bytes]:
+    if gdl_file is None:
+        raise gr.Error("请先上传 GDL 文件")
+
+    # 读取 GDL 文本
+    gdl_bytes = _read_as_bytes(gdl_file)
+    try:
+        gdl_txt = gdl_bytes.decode("utf-8")
+    except Exception:
+        # 尝试 gbk / latin-1 以容错
+        for enc in ("utf-8-sig", "gbk", "latin-1"):
+            try:
+                gdl_txt = gdl_bytes.decode(enc)
+                break
+            except Exception:
+                continue
+        else:
+            raise gr.Error("无法解码 GDL 文本，请确认编码为 UTF-8")
+
+    # 解析 -> 规整 -> 映射
+    gdl_ast = parse_gdl(gdl_txt)
+    nz = normalize_ir(gdl_ast, gdl_txt)
+    ir = map_to_v095(nz, gdl_txt)
+
+    # Schema 路径：优先使用上传，其次自动发现
+    if schema_file is not None:
+        try:
+            schema_bytes = _read_as_bytes(schema_file)
+            tmp = tempfile.NamedTemporaryFile(suffix=".json", delete=False)
+            tmp.write(schema_bytes)
+            tmp.flush()
+            tmp.close()
+            schema_path = pathlib.Path(tmp.name)
+        except Exception:
+            raise gr.Error("读取 Schema 失败，请确认文件格式正确")
+    else:
+        try:
+            schema_path = _auto_discover_schema(None)
+        except FileNotFoundError as e:
+            raise gr.Error(str(e))
+
+    # 校验（兼容 2/3 元组）
+    ret = validate_with_schema(ir, str(schema_path))
+    if isinstance(ret, tuple) and len(ret) == 3:
+        ok, issues, schema_msg = ret
+    elif isinstance(ret, tuple) and len(ret) == 2:
+        ok, issues = ret
+        schema_msg = f"Schema: {'OK' if ok else 'FAIL'}; issues={len(issues)}"
+    else:
+        ok = bool(ret)
+        issues = []
+        schema_msg = f"Schema: {'OK' if ok else 'FAIL'}"
+
+    report_md = make_report(ir)
+
+    ir_json_str = json.dumps(ir, ensure_ascii=False, indent=2)
+    issues_json_str = json.dumps(issues, ensure_ascii=False, indent=2)
+
+    # 准备下载的文件内容
+    ir_bytes = ir_json_str.encode("utf-8")
+    issues_bytes = issues_json_str.encode("utf-8")
+    report_bytes = report_md.encode("utf-8")
+
+    return (
+        ir_json_str,
+        issues_json_str,
+        report_md,
+        ir_bytes,
+        issues_bytes,
+        report_bytes,
+    )
+
+
+def _save_temp(name_hint: str, data: bytes) -> str:
+    suffix = pathlib.Path(name_hint).suffix or ""
+    tmp = tempfile.NamedTemporaryFile(delete=False, suffix=suffix)
+    tmp.write(data)
+    tmp.flush()
+    tmp.close()
+    return tmp.name
+
+
+with gr.Blocks(title="GDL → IR(v0.95) Web UI") as demo:
+    gr.Markdown("""
+    **GDL → IR(v0.95) 一键转换与校验**  
+    - 上传 GDL 文本文件（.txt/.gdl）  
+    - 可选上传 Schema（若不上传，将自动发现同目录中的 `poker_gdl_ir.schema.v0.95.zh.json`）  
+    - 生成：IR(JSON)、Issues(JSON)、自检报告(Markdown)
+    """
+    )
+
+    with gr.Row():
+        gdl_in = gr.File(label="GDL 文件 (.txt/.gdl)", file_types=[".txt", ".gdl"], type="binary")
+        schema_in = gr.File(label="Schema 文件 (可选)", file_types=[".json"], type="binary")
+
+    run_btn = gr.Button("运行转换与校验")
+
+    with gr.Tab("IR 预览"):
+        ir_json = gr.Code(label="IR (v0.95)", language="json")
+        ir_dl = gr.File(label="下载 IR JSON", interactive=False)
+
+    with gr.Tab("Issues 预览"):
+        issues_json = gr.Code(label="Schema 校验问题", language="json")
+        issues_dl = gr.File(label="下载 Issues JSON", interactive=False)
+
+    with gr.Tab("自检报告"):
+        report_md = gr.Markdown()
+        report_dl = gr.File(label="下载 自检报告.md", interactive=False)
+
+    def _on_click(gdl_file, schema_file):
+        ir_str, issues_str, report_str, ir_b, issues_b, report_b = run_pipeline(gdl_file, schema_file)
+        ir_path = _save_temp("ir.v0.95.json", ir_b)
+        issues_path = _save_temp("issues.json", issues_b)
+        report_path = _save_temp("selfcheck.md", report_b)
+        return ir_str, ir_path, issues_str, issues_path, report_str, report_path
+
+    run_btn.click(
+        _on_click,
+        inputs=[gdl_in, schema_in],
+        outputs=[ir_json, ir_dl, issues_json, issues_dl, report_md, report_dl]
+    )
+
+if __name__ == "__main__":
+    demo.launch(share=True)
+
+

cli_v2.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+cli_v2.py — 一键执行 GDL→IR（v0.95）+ 校验 + 报告
+改动要点：
+1) policy 默认就是 merge（无需在命令行传参；也可用环境变量 GDL2IR_POLICY 覆盖）
+2) 内置 schema 校验 & 自动发现 schema
+   - 候选路径依次尝试：
+     a) 命令行 --schema
+     b) 脚本同目录的 poker_gdl_ir.schema.v0.95.zh.json
+     c) 当前工作目录的 poker_gdl_ir.schema.v0.95.zh.json
+     d) /mnt/data/poker_gdl_ir.schema.v0.95.zh.json
+3) 兼容 validator_v2.validate_with_schema() 返回 2 元组或 3 元组
+"""
+import argparse, json, pathlib, sys, os
+
+from gdl_parser_v2 import parse_gdl
+from normalizer_v2 import normalize_ir
+from mapper_v2 import map_to_v095
+from validator_v2 import validate_with_schema
+from gap_detector_v2 import make_report
+
+
+def _auto_discover_schema(cli_arg: str = None) -> pathlib.Path:
+    # 优先级：命令行 > 脚本同目录 > 当前目录 > /mnt/data
+    candidates = []
+    if cli_arg:
+        candidates.append(cli_arg)
+
+    here = pathlib.Path(__file__).resolve().parent
+    candidates.append(str(here / "poker_gdl_ir.schema.v0.95.zh.json"))
+    candidates.append("poker_gdl_ir.schema.v0.95.zh.json")
+    candidates.append("/mnt/data/poker_gdl_ir.schema.v0.95.zh.json")
+
+    for c in candidates:
+        try:
+            p = pathlib.Path(c)
+            if p.exists():
+                return p
+        except Exception:
+            pass
+
+    raise FileNotFoundError(
+        "未找到 Schema。请使用 --schema 指定，或将 poker_gdl_ir.schema.v0.95.zh.json 放在脚本同目录/当前目录。"
+    )
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("gdl_file", help="源 GDL 文件（.txt/.gdl）")
+    ap.add_argument("--schema", help="Schema 路径（可不填，将自动发现）")
+    # policy 默认 merge；允许用环境变量 GDL2IR_POLICY 覆盖（可选）
+    # ap.add_argument("--policy", choices=["minimal", "merge", "conservative"],
+    #                 default=os.getenv("GDL2IR_POLICY", "merge"),
+    #                 help="组合策略（默认 merge）："
+    #                      "minimal=仅保留用到的；merge=保留通用并禁用无关；conservative=全保留")
+    ap.add_argument("--out-ir", dest="out_ir", help="IR 输出 JSON 路径")
+    ap.add_argument("--out-issues", dest="out_issues", help="校验问题 JSON 路径")
+    ap.add_argument("--out-report", dest="out_report", help="自检报告 Markdown 路径")
+    args = ap.parse_args()
+
+    src_path = pathlib.Path(args.gdl_file)
+    if not src_path.exists():
+        print(f"[ERROR] 源文件不存在：{src_path}", file=sys.stderr)
+        sys.exit(2)
+
+    try:
+        schema_path = _auto_discover_schema(args.schema)
+    except FileNotFoundError as e:
+        print(f"[ERROR] {e}", file=sys.stderr)
+        sys.exit(2)
+
+    # 读取 & 解析 & 规整
+    gdl_txt = src_path.read_text(encoding="utf-8")
+    gdl_ast = parse_gdl(gdl_txt)
+    nz = normalize_ir(gdl_ast, gdl_txt)
+
+    # 映射为 v0.95 IR（policy 默认 merge）
+    ir = map_to_v095(nz, gdl_txt)
+
+    # ✅ Schema 校验（兼容 2/3 元组返回）
+    ret = validate_with_schema(ir, str(schema_path))
+    if isinstance(ret, tuple) and len(ret) == 3:
+        ok, issues, schema_msg = ret
+    elif isinstance(ret, tuple) and len(ret) == 2:
+        ok, issues = ret
+        schema_msg = f"Schema: {'OK' if ok else 'FAIL'}; issues={len(issues)}"
+    else:
+        # 极端兜底：未知返回类型
+        ok = bool(ret)
+        issues = []
+        schema_msg = f"Schema: {'OK' if ok else 'FAIL'}"
+
+    # 输出
+    out_ir = pathlib.Path(args.out_ir or str(src_path.with_suffix(".ir.v0.95.json")))
+    out_issues = pathlib.Path(args.out_issues or str(src_path.with_suffix(".issues.json")))
+    out_report = pathlib.Path(args.out_report or str(src_path.with_suffix(".selfcheck.md")))
+
+    out_ir.write_text(json.dumps(ir, ensure_ascii=False, indent=2), encoding="utf-8")
+    out_issues.write_text(json.dumps(issues, ensure_ascii=False, indent=2), encoding="utf-8")
+    out_report.write_text(make_report(ir), encoding="utf-8")
+
+    print(f"[OK] IR 写入：{out_ir}")
+    print(f"[OK] Schema 校验问题写入：{out_issues}")
+    print(f"[OK] 自检报告写入：{out_report}")
+    print(f"[SUMMARY] {schema_msg}")
+
+if __name__ == "__main__":
+    main()

gap_detector_v2.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+"""
+gap_detector_v2.py — 轻量自检报告：覆盖率/常见疏漏提示
+"""
+from __future__ import annotations
+from typing import Dict, List
+
+def make_report(ir: Dict) -> str:
+    notes: List[str] = []
+    if not ir.get("special_mechanics"):
+        notes.append("- 未声明 special_mechanics（如果玩法确有特殊牌/机制可忽略）")
+    if "hand:*" in (ir.get("zones") or []):
+        notes.append("- zones 含 hand:*；建议在 mapper 展开为 hand:<id>")
+    if not ir.get("actions",{}).get("play"):
+        notes.append("- actions.play 为空，实际引擎可能无法出牌")
+    return "# 自检报告\n\n" + ("\n".join(notes) if notes else "无明显问题。")

gdl_parser_v2.py

@@ -0,0 +1,164 @@
+# -*- coding: utf-8 -*-
+"""
+gdl_parser_v2.py — 宽容 S-Expr 解析器（支持 ()/[]/{}, 字符串, 数字, 标识符, 注释）
+把 S-Expr 转 Python，再做一层“键值折叠”：(k v1 (a b) c) -> {"k": {..., "_": [v1, c]}}
+兼容 Markdown 反引号围栏；支持 ; // # 行注释、#| |# 块注释。
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any, List, Dict
+
+class ParseError(Exception): ...
+
+@dataclass
+class Tok:
+    kind: str   # 'LP','RP','ATOM','STR','NUM'
+    val: Any
+    closer: str = ""
+
+_PAIR = {'(' : ')', '[':']', '{':'}'}
+
+def _is_ws(ch: str) -> bool: return ch.isspace()
+def _is_ident_char(ch: str)  -> bool:
+    return ch.isalnum() or ch in "_-+*/<>=!?&.|:$@~^%"
+
+def _lex(text: str) -> List[Tok]:
+    s = text; i = 0; n = len(s); toks: List[Tok] = []
+    def adv(k=1):
+        nonlocal i; i += k
+    def peek(): return s[i] if i<n else ''
+    def startsw(p): return s.startswith(p, i)
+    while i<n:
+        ch = peek()
+        if _is_ws(ch): adv(); continue
+        # 行注释
+        if ch==';' or startsw('//') or ch=='#':
+            while i<n and s[i] != '\n': adv()
+            continue
+        # 块注释 #| ... |#
+        if startsw('#|'):
+            adv(2)
+            while i<n and not startsw('|#'): adv()
+            if startsw('|#'): adv(2)
+            else: raise ParseError("Unterminated block comment")
+            continue
+        # markdown 反引号行
+        if ch=='`':
+            while i<n and s[i] != '\n': adv()
+            continue
+        if ch in _PAIR:
+            toks.append(Tok('LP', ch, _PAIR[ch])); adv(); continue
+        if ch in (')',']','}'):
+            toks.append(Tok('RP', ch)); adv(); continue
+        if ch == '"':
+            adv(); buf=[]
+            while i<n:
+                c=peek()
+                if c=='"': adv(); break
+                if c=='\\':
+                    adv(); esc=peek(); mp={'n':'\n','t':'\t','r':'\r','"':'"','\\':'\\'}
+                    buf.append(mp.get(esc, esc)); adv()
+                else:
+                    buf.append(c); adv()
+            toks.append(Tok('STR',''.join(buf))); continue
+        if ch.isdigit() or (ch in '+-' and i+1<n and s[i+1].isdigit()):
+            j=i+1
+            while j<n and (s[j].isdigit() or s[j] in '.eE+-'): j+=1
+            raw=s[i:j]
+            try: val=int(raw)
+            except:
+                try: val=float(raw)
+                except: val=raw
+            toks.append(Tok('NUM',val)); i=j; continue
+        if _is_ident_char(ch):
+            j=i
+            while j<n and _is_ident_char(s[j]): j+=1
+            toks.append(Tok('ATOM', s[i:j])); i=j; continue
+        raise ParseError(f"Unexpected char: {ch}")
+    return toks
+
+def _parse_list(toks: List[Tok], i: int, closer: str):
+    out=[]; n=len(toks)
+    while i<n:
+        tk=toks[i]
+        if tk.kind=='RP':
+            if tk.val!=closer: raise ParseError("Mismatched closer")
+            return out, i+1
+        if tk.kind=='LP':
+            sub,i=_parse_list(toks,i+1,tk.closer); out.append(sub); continue
+        if tk.kind in ('ATOM','STR','NUM'):
+            out.append(tk.val); i+=1; continue
+        raise ParseError("Unexpected token")
+    raise ParseError("Unbalanced s-expr: missing closer")
+
+def parse_sexpr(text: str):
+    # strip markdown codefences lines
+    lines = [ln for ln in text.splitlines() if ln.strip() not in ('```','````','``')]
+    text = "\n".join(lines)
+    toks=_lex(text); out=[]; i=0; n=len(toks)
+    while i<n:
+        tk=toks[i]
+        if tk.kind=='LP':
+            sub,i=_parse_list(toks,i+1,tk.closer); out.append(sub); continue
+        if tk.kind in ('ATOM','STR','NUM'): out.append(tk.val); i+=1; continue
+        if tk.kind=='RP': raise ParseError("Unmatched closer")
+    return out
+
+def _is_key_list(node): return isinstance(node,list) and node and isinstance(node[0],str)
+
+def _kv_collapse_from_positional(pos_list):
+    """将 ['from:', 'hand', 'to:', 'field'] 折叠为 {'from':'hand','to':'field'}"""
+    out={}; i=0; n=len(pos_list)
+    while i<n-1:
+        k = pos_list[i]; v = pos_list[i+1]
+        if isinstance(k,str) and k.endswith(':'):
+            out[k[:-1]] = v
+            i += 2
+        else:
+            i += 1
+    return out if out else None
+
+def _to_obj(node):
+    if not isinstance(node,list): return node
+    if not node: return []
+    if _is_key_list(node):
+        key=node[0]; payload=node[1:]
+        obj={}; pos=[]
+        for it in payload:
+            if isinstance(it,list) and _is_key_list(it):
+                k=it[0]; v=_to_obj(it[1:]) if len(it)>1 else None
+                obj[k]=v
+            else:
+                pos.append(_to_obj(it))
+        kv = _kv_collapse_from_positional(pos)
+        if kv is not None:
+            for k,v in kv.items(): obj[k]=v
+        else:
+            if pos: obj["_"]=pos
+        return {key: obj}
+    return [_to_obj(it) for it in node]
+
+def _merge_kv_list_to_dict(items) -> Dict[str, Any]:
+    out={}
+    for it in items:
+        if isinstance(it,dict) and len(it)==1:
+            k,v=next(iter(it.items()))
+            if k in out:
+                if not isinstance(out[k],list): out[k]=[out[k]]
+                out[k].append(v)
+            else:
+                out[k]=v
+    return out
+
+def parse_gdl(text: str) -> dict:
+    sexpr = parse_sexpr(text)
+    # 如果是单一顶层表 (game ...)
+    if len(sexpr)==1 and isinstance(sexpr[0], list):
+        node = _to_obj(sexpr[0])
+        if isinstance(node, dict):
+            return node
+        items = [_to_obj(e) for e in sexpr[0]]
+        return _merge_kv_list_to_dict(items)
+    # 多个顶层
+    items = [_to_obj(e) for e in sexpr]
+    return _merge_kv_list_to_dict(items)

mapper_v2.py

@@ -0,0 +1,865 @@
+# -*- coding: utf-8 -*-
+"""
+mapper_v2.py — 将 normalizer_v2 输出映射为 v0.95 IR（schema 友好；兼容 UNO/七夕）
+"""
+from __future__ import annotations
+from typing import Any, Dict, List
+from copy import deepcopy
+import re
+
+REQUIRED = ["meta","players","cards","zones","visibility","combinations","comparison","actions","phases","turns","ending","scoring"]
+ZONE_RE = re.compile(r"^(hand:[A-Za-z0-9_:-]+|field|main_deck|discard_pile|reserve_zone|public_pool|item_deck:[A-Za-z0-9_:-]+|history_deck)$")
+
+def _as_dict(x): return x if isinstance(x,dict) else {}
+def _as_list(x): return x if isinstance(x,list) else ([] if x is None else [x])
+
+def _scalar(x):
+    if isinstance(x,str): return x
+    if isinstance(x,(int,float)): return str(x)
+    if isinstance(x,dict):
+        if "_" in x and isinstance(x["_"], list) and x["_"]: return _scalar(x["_"][0])
+        if "name" in x and isinstance(x["name"], str): return x["name"]
+        if len(x)==1:
+            k,v = next(iter(x.items()))
+            if v in (None,{}) and isinstance(k,str): return k
+    if isinstance(x,list) and x: return _scalar(x[0])
+    return ""
+
+def _uniquify(seq: List[str]) -> List[str]:
+    seen={}; out=[]
+    for s in map(str, seq):
+        if s not in seen:
+            seen[s]=0; out.append(s)
+        else:
+            seen[s]+=1; out.append(f"{s}_{seen[s]}")
+    return out
+
+def _phase_to_schema(s: str) -> str:
+    # Mapping GDL phase names to schema phase names
+    mp={
+        "deal":"setup", # GDL 'deal' often maps to setup for initialization tasks, but can also be a separate 'deal' phase
+        "setup":"setup",
+        "bid":"bidding",
+        "bidding":"bidding",
+        "double":"doubling",
+        "doubling":"doubling",
+        "initiative":"setup", # Map GDL's initiative_phase to schema's setup
+        "grouping":"grouping",
+        "play":"playing",
+        "playing":"playing",
+        "playing_phase":"play", # Map GDL's playing_phase to schema's play
+        "settle":"settlement",
+        "settlement":"settlement",
+        "settlement_phase":"settlement"
+    }
+    return mp.get(s, s)
+
+def _derive_players(nz: Dict[str,Any]) -> Dict[str,Any]:
+    roles=_as_list(_as_dict(nz.get("game")).get("roles"))
+    order=_as_dict(nz.get("turns")).get("order") or []
+    ids = _uniquify([_scalar(x) for x in order]) if order else []
+    if not ids and roles:
+        tmp=[]
+        for r in roles:
+            rd=_as_dict(r)
+            name=_scalar(rd.get("name") or rd.get("role") or "Player")
+            cnt=int(rd.get("count",1) or 1)
+            tmp += [name]*max(1,cnt)
+        ids=_uniquify(tmp)
+    if not ids:
+        ids=["P0","P1","P2"]
+
+    # --- Modification: Create player instances based on roles and counts, and store in roles.players ---
+    # Schema v0.95 expects count and roles list with name, count, and optionally players.
+    out_roles = []
+    current_id_idx = 0
+    for r in roles:
+        rd = _as_dict(r)
+        role_name = _scalar(rd.get("name") or "Player")
+        role_count = int(rd.get("count", 1) or 1)
+
+        # Generate unique player IDs for this role
+        role_players = []
+        for i in range(role_count):
+            if current_id_idx < len(ids):
+                player_id = ids[current_id_idx]
+                role_players.append(player_id)
+                current_id_idx += 1
+            else:
+                # Fallback if ids list is shorter than expected
+                player_id = f"{role_name}_{i}" if i > 0 else role_name
+                role_players.append(player_id)
+
+        # Add the role definition (name, count, players) to the output roles list
+        out_roles.append({"name": role_name, "count": role_count, "players": role_players})
+        # The actual player IDs are used for turns.order and zone generation
+
+    return {"count": len(ids), "roles": out_roles, "_player_ids": ids} # Removed _role_definitions as not needed for schema
+
+def _expand_zones(zs: List[Dict[str, Any]], pids: List[str]) -> List[str]:
+    out=[]
+    zone_types_map = {
+        "hand": "hand:{pid}",
+        "field": "field",
+        "discard_pile": "discard_pile",
+        "main_deck": "main_deck",
+        "special_deck": "item_deck:{name}" # Map special_deck to item_deck:<name>
+    }
+    for z_def in zs or []:
+        z_type = z_def.get("type")
+        if z_type in zone_types_map:
+            template = zone_types_map[z_type]
+            if z_type == "hand":
+                # Expand hand for each player ID
+                for pid in pids:
+                    out.append(template.format(pid=pid))
+            elif z_type == "special_deck":
+                # Use the name from the definition
+                name = z_def.get("name", "Unknown")
+                out.append(template.format(name=name))
+            else:
+                # Use the template directly for other types
+                out.append(template)
+    # Add common base zones if not already present
+    base = ["field","discard_pile","main_deck"]
+    for b in base:
+        if b not in out: out.append(b)
+    # Remove duplicates while preserving order
+    seen=set(); uniq=[]
+    for z in out:
+        if z not in seen:
+            seen.add(z); uniq.append(z)
+    return uniq
+
+
+def _expand_vis_hand_star(vis: Dict[str,Any], pids: List[str]) -> Dict[str,Any]:
+    vis=_as_dict(vis); vis.setdefault("defaults", {}); by=_as_dict(vis.get("by_zone"))
+    if "hand:*" in by:
+        cfg=by.pop("hand:*")
+        for pid in pids: by[f"hand:{pid}"]=cfg
+    vis["by_zone"]=by; return vis
+
+def _ensure_cards(nz: Dict[str,Any]) -> Dict[str,Any]:
+    cards=_as_dict(nz.get("cards"))
+    ranks=_as_list(cards.get("ranks")); suits=_as_list(cards.get("suits"))
+    if not ranks or not suits:
+        # --- Modification: Derive from card_relations if available ---
+        card_rels = _as_dict(nz.get("card_relations"))
+        if card_rels:
+            # Derive from card_values
+            card_vals = _as_list(card_rels.get("card_values"))
+            # Map common symbols to integers
+            symbol_map = {
+                "J": 11, "Q": 12, "K": 13, "A": 14, "2": 15
+            }
+            ranks = []
+            for val in card_vals:
+                if isinstance(val, int):
+                    ranks.append(val)
+                elif isinstance(val, str) and val in symbol_map:
+                    ranks.append(symbol_map[val])
+                else:
+                    ranks.append(_scalar(val)) # Fallback
+
+            # Derive from suit_relations
+            suit_rels = _as_dict(card_rels.get("suit_relations"))
+            suit_order = _as_list(suit_rels.get("order"))
+            suits = [s for s in suit_order if isinstance(s, str)] or ["Spade","Heart","Club","Diamond"]
+
+            # Determine jokers and suitless_ranks
+            jokers = {}
+            suitless_ranks = []
+            # Standard54 implies 2 jokers
+            if "2" in card_vals or 15 in ranks: # Assuming '2' is always high and joker-like
+                # Standard54 has small joker 16, big joker 17
+                # In our mapping, if 2 is last, it might be 15. Let's check.
+                # Actually, Standard54 usually has fixed values for jokers regardless of card_values order.
+                # Let's assume standard mapping for Standard54 deck type.
+                deck_info = _as_dict(_as_dict(nz.get("game")).get("deck"))
+                if deck_info.get("type") == "Standard54":
+                    jokers = {"small": 16, "big": 17}
+                    suitless_ranks = [16, 17]
+                    # Add jokers to ranks if not already present
+                    if 16 not in ranks: ranks.append(16)
+                    if 17 not in ranks: ranks.append(17)
+
+            # --- Modification: Ensure suitless_ranks, copies_per_deck, num_decks are included ---
+            cards = {
+                "ranks": sorted(ranks),
+                "suits": suits,
+                "jokers": jokers,
+                "suitless_ranks": suitless_ranks,
+                "copies_per_deck": 1, # Assuming 1 copy for Standard54
+                "num_decks": 1 # Assuming 1 deck
+            }
+        else:
+            # Fallback to standard 54
+            ranks=list(range(3,18))   # 3..A(14), 小王16, 大王17
+            suits=["Spade","Heart","Club","Diamond"]
+            cards={"ranks":ranks, "suits":suits, "jokers":{"small":16,"big":17}}
+    else:
+        # If ranks and suits were already provided, ensure the missing fields are added if possible
+        # This path might be taken if the initial cards dict had some info but not all.
+        # We can infer suitless_ranks from jokers, and assume defaults for copies/num_decks if not present.
+        if "jokers" in cards and "suitless_ranks" not in cards:
+            jokers = cards.get("jokers", {})
+            small_j = jokers.get("small")
+            big_j = jokers.get("big")
+            suitless_ranks = [r for r in [small_j, big_j] if r is not None]
+            cards["suitless_ranks"] = suitless_ranks
+        if "copies_per_deck" not in cards:
+            cards["copies_per_deck"] = 1
+        if "num_decks" not in cards:
+            cards["num_decks"] = 1
+
+    return cards
+
+def _ensure_combinations(nz: Dict[str,Any]) -> Dict[str,Any]:
+    cmb=_as_dict(nz.get("combinations"))
+    out={"single":{}, "pair":{}, "triple":{}, "straight":{}, "pairs_chain":{}, "airplane":{},
+         "triple_with_single":{}, "triple_with_pair":{}, "four_with_twoSingles":{}, "four_with_twoPairs":{}, "bomb":{}, "rocket":{}, "custom":[]}
+
+    # --- Modification: Handle combinations from GDL ---
+    # Get raw combinations from normalizer
+    raw_combinations = _as_dict(nz.get("combinations", {}))
+    # Handle straight and bomb with parameters
+    if "straight" in nz.get("game", {}).get("combinations", {}):
+        # Look for the argument, e.g., (straight 5)
+        gdl_combinations = _as_dict(nz.get("game", {}).get("combinations", {}))
+        if isinstance(gdl_combinations.get("straight"), (int, list)):
+            val = gdl_combinations.get("straight")
+            if isinstance(val, list) and val:
+                val = val[0] # Get first argument if list
+            out["straight"] = {"min_len": int(val)}
+        else:
+            out["straight"] = {} # Fallback if no arg found in GDL
+
+    if "bomb" in nz.get("game", {}).get("combinations", {}):
+        gdl_combinations = _as_dict(nz.get("game", {}).get("combinations", {}))
+        if isinstance(gdl_combinations.get("bomb"), (int, list)):
+            val = gdl_combinations.get("bomb")
+            if isinstance(val, list) and val:
+                val = val[0]
+            out["bomb"] = {"len": int(val)}
+        else:
+            out["bomb"] = {} # Fallback if no arg found in GDL
+
+    # Handle custom combinations from normalizer
+    if "custom" in raw_combinations and isinstance(raw_combinations["custom"], list):
+        out["custom"] = raw_combinations["custom"]
+    else:
+        # Fallback if normalizer didn't capture them correctly
+        out["custom"] = []
+
+    # Merge with any explicitly set values in the input cmb dict (e.g., from extensions)
+    for k in list(out.keys()):
+        if k in cmb and isinstance(cmb[k], dict):
+            out[k].update(cmb[k]) # Update with input values if present
+
+    return out
+
+def _ensure_actions(nz: Dict[str,Any], pids: List[str] = None) -> Dict[str,Any]:
+    actions=_as_dict(nz.get("actions"))
+    pids = pids or []
+    
+    # 解析 play 动作
+    play_actions = []
+    if "play" in actions:
+        play_def = actions["play"]
+        if isinstance(play_def, list):
+            # 解析器把 play 分解成了多个字典，需要合并成一个完整的 play action
+            play_action = _merge_play_actions(play_def, nz)
+            if play_action:
+                # 修复transfer_path中的zone ID
+                if "transfer_path" in play_action:
+                    play_action["transfer_path"] = _fix_zone_ids_in_transfer_path(
+                        play_action["transfer_path"], pids)
+                play_actions.append(play_action)
+        elif isinstance(play_def, dict):
+            # 单个 play 定义
+            play_action = _parse_play_action(play_def)
+            if "transfer_path" in play_action:
+                play_action["transfer_path"] = _fix_zone_ids_in_transfer_path(
+                    play_action["transfer_path"], pids)
+            play_actions.append(play_action)
+    
+    # 解析 special 动作
+    special_actions = []
+    if "special" in actions:
+        special_def = actions["special"]
+        if isinstance(special_def, list):
+            special_actions = _merge_special_actions(special_def)
+        elif isinstance(special_def, dict):
+            special_actions.append(_parse_special_action(special_def))
+        
+        # 修复special动作中的transfer_path
+        for action in special_actions:
+            if "transfer_path" in action:
+                action["transfer_path"] = _fix_zone_ids_in_transfer_path(
+                    action["transfer_path"], pids)
+    
+    # 构建输出
+    output = {
+        "play": play_actions,
+        "pass": {"transfer_path": {"from": "field", "to": "field"}},
+        "cleanup_trick": [{"from": "field", "to": "discard_pile", "count": "all"}],
+        "other": {}
+    }
+    
+    # 如果有 special 动作，添加到 other 中
+    if special_actions:
+        # 将special动作转换为Transfer格式
+        special_transfers = []
+        for action in special_actions:
+            if "transfer_path" in action:
+                transfer = action["transfer_path"].copy()
+                if "visibility_change" in action:
+                    transfer["visibility_change"] = action["visibility_change"]
+                special_transfers.append(transfer)
+        if special_transfers:
+            output["other"]["special"] = special_transfers
+    
+    return output
+
+def _merge_play_actions(play_defs: List[Dict[str, Any]], gdl_actions: Dict[str, Any] = None) -> Dict[str, Any]:
+    """合并被解析器分解的 play 动作定义"""
+    merged = {}
+    raw_def = {}
+    
+    # 首先尝试从play_defs中提取牌型列表
+    type_list = []
+    for play_def in play_defs:
+        if isinstance(play_def, dict) and "type" in play_def:
+            type_val = play_def["type"]
+            if isinstance(type_val, dict):
+                type_list = _extract_one_of_values(type_val)
+                break
+    
+    if type_list:
+        # 过滤掉"one_of"和其他无效值
+        valid_types = [t for t in type_list if t not in ["one_of", "int?", "sequence?"]]
+        if valid_types:
+            # Schema期望type是单个字符串，不是数组，所以取第一个有效类型
+            merged["type"] = valid_types[0]
+    
+    for play_def in play_defs:
+        if isinstance(play_def, dict):
+            # 检查是否是特定字段
+            if "type" in play_def and "type" not in merged:
+                type_val = play_def["type"]
+                if isinstance(type_val, dict):
+                    if "one_of" in type_val:
+                        # 处理 one_of 结构，提取所有牌型
+                        type_list = _extract_one_of_values(type_val)
+                        merged["type"] = type_list
+                    else:
+                        merged["type"] = _scalar(type_val)
+                else:
+                    merged["type"] = _scalar(type_val)
+            
+            elif "len" in play_def:
+                # 处理 len 字段，提取简单值
+                len_val = _extract_simple_value(play_def["len"])
+                if len_val != "int?":
+                    merged["len"] = len_val
+            
+            elif "core" in play_def:
+                # 处理 core 字段，提取简单值
+                core_val = _extract_simple_value(play_def["core"])
+                if core_val != "sequence?":
+                    merged["core"] = core_val
+            
+            elif "wings" in play_def:
+                # 处理 wings 字段，提取简单值
+                wings_val = _extract_simple_value(play_def["wings"])
+                if wings_val != "int?":
+                    merged["wings"] = wings_val
+            
+            elif "transfer_path" in play_def:
+                tp = play_def["transfer_path"]
+                if isinstance(tp, dict):
+                    merged["transfer_path"] = tp
+                elif isinstance(tp, list):
+                    merged["transfer_path"] = _parse_transfer_path_list(tp)
+            
+            elif "visibility_change" in play_def:
+                vc = play_def["visibility_change"]
+                merged["visibility_change"] = _parse_visibility_change(vc)
+            
+            else:
+                # 其他字段保存到 raw_definition
+                raw_def.update(play_def)
+    
+    # 如果没有提取到type，设置默认值
+    if "type" not in merged:
+        merged["type"] = ["single", "pair", "triple", "straight", "bomb", "rocket"]
+    
+    # 确保visibility_change有state字段
+    if "visibility_change" in merged:
+        vc = merged["visibility_change"]
+        if "state" not in vc:
+            vc["state"] = "visible"
+    
+    # 保存原始定义
+    if raw_def:
+        merged["raw_definition"] = raw_def
+    
+    return merged
+
+def _extract_one_of_values(type_dict: Dict[str, Any]) -> List[str]:
+    """从 one_of 结构中提取值列表"""
+    values = []
+    
+    def extract_recursive(obj):
+        if isinstance(obj, dict):
+            if "_" in obj:
+                if isinstance(obj["_"], list):
+                    values.extend(obj["_"])
+            for k, v in obj.items():
+                if k != "_":
+                    # 如果key不是"_"，那么key本身就是一个值
+                    if isinstance(v, dict):
+                        if len(v) == 0:
+                            # 空字典，key就是值
+                            values.append(k)
+                        elif "_" in v:
+                            # 有"_"字段，key是值，然后递归处理"_"
+                            values.append(k)
+                            extract_recursive(v)
+                        else:
+                            # 没有"_"字段，递归处理
+                            extract_recursive(v)
+                    else:
+                        # v不是字典，k是值
+                        values.append(k)
+        elif isinstance(obj, list):
+            for item in obj:
+                extract_recursive(item)
+    
+    extract_recursive(type_dict)
+    return values
+
+def _extract_play_types_from_gdl(gdl_actions: Dict[str, Any]) -> List[str]:
+    """从GDL actions中提取play动作的牌型列表"""
+    if "play" not in gdl_actions:
+        return []
+    
+    play_def = gdl_actions["play"]
+    if isinstance(play_def, list):
+        # 查找type字段
+        for item in play_def:
+            if isinstance(item, dict) and "type" in item:
+                type_val = item["type"]
+                if isinstance(type_val, dict) and "one_of" in type_val:
+                    return _extract_one_of_values(type_val)
+    elif isinstance(play_def, dict) and "type" in play_def:
+        type_val = play_def["type"]
+        if isinstance(type_val, dict) and "one_of" in type_val:
+            return _extract_one_of_values(type_val)
+    
+    # 如果从actions中没找到，尝试从game.actions中查找
+    game_actions = _as_dict(_as_dict(gdl_actions.get("game", {})).get("actions", {}))
+    if "play" in game_actions:
+        play_def = game_actions["play"]
+        if isinstance(play_def, list):
+            for item in play_def:
+                if isinstance(item, dict) and "type" in item:
+                    type_val = item["type"]
+                    if isinstance(type_val, dict) and "one_of" in type_val:
+                        return _extract_one_of_values(type_val)
+        elif isinstance(play_def, dict) and "type" in play_def:
+            type_val = play_def["type"]
+            if isinstance(type_val, dict) and "one_of" in type_val:
+                return _extract_one_of_values(type_val)
+    
+    return []
+
+def _extract_simple_value(obj: Any) -> Any:
+    """提取简单值，处理嵌套的 {"_": [value]} 结构"""
+    if isinstance(obj, dict):
+        if "_" in obj and isinstance(obj["_"], list) and len(obj["_"]) == 1:
+            return obj["_"][0]
+        elif len(obj) == 1:
+            key, value = next(iter(obj.items()))
+            if isinstance(value, dict) and len(value) == 0:
+                return key
+            return _extract_simple_value(value)
+    return obj
+
+def _parse_visibility_change(vc: Dict[str, Any]) -> Dict[str, Any]:
+    """解析visibility_change字段"""
+    result = {}
+    
+    # 解析 to 字段
+    if "to" in vc:
+        to_val = vc["to"]
+        if isinstance(to_val, list):
+            # 提取所有受众
+            audiences = []
+            for item in to_val:
+                if isinstance(item, dict):
+                    # 处理 {"owner": {"_": ["teammates", "enemies"]}} 结构
+                    for key, value in item.items():
+                        if isinstance(value, dict) and "_" in value:
+                            audiences.extend(value["_"])
+                        else:
+                            audiences.append(key)
+                else:
+                    audiences.append(_scalar(item))
+            result["to"] = audiences
+        else:
+            result["to"] = [_scalar(to_val)]
+    
+    # 解析 state 字段
+    if "state" in vc:
+        state_val = _extract_simple_value(vc["state"])
+        if state_val != "visible":
+            result["state"] = state_val
+    
+    # 解析 on_target 字段
+    if "on_target" in vc:
+        on_target_val = _extract_simple_value(vc["on_target"])
+        if on_target_val != "true":
+            result["on_target"] = on_target_val
+    
+    return result
+
+def _parse_play_action(play_def: Dict[str, Any]) -> Dict[str, Any]:
+    """解析单个 play 动作定义"""
+    result = {}
+    
+    # 解析 type
+    if "type" in play_def:
+        type_val = play_def["type"]
+        if isinstance(type_val, dict) and "one_of" in type_val:
+            result["type"] = _as_list(type_val["one_of"])
+        else:
+            result["type"] = _scalar(type_val)
+    
+    # 解析其他字段
+    for key in ["len", "core", "wings"]:
+        if key in play_def:
+            result[key] = play_def[key]
+    
+    # 解析 transfer_path
+    if "transfer_path" in play_def:
+        tp = play_def["transfer_path"]
+        if isinstance(tp, dict):
+            result["transfer_path"] = tp
+        elif isinstance(tp, list):
+            # 处理 from: hand to: field 格式
+            result["transfer_path"] = _parse_transfer_path_list(tp)
+    
+    # 解析 visibility_change
+    if "visibility_change" in play_def:
+        result["visibility_change"] = play_def["visibility_change"]
+    
+    # 保存原始定义用于复杂情况
+    result["raw_definition"] = {k: v for k, v in play_def.items() 
+                               if k not in ["type", "len", "core", "wings", "transfer_path", "visibility_change"]}
+    
+    return result
+
+def _parse_special_action(special_def: Dict[str, Any]) -> Dict[str, Any]:
+    """解析 special 动作定义"""
+    result = {}
+    
+    # 解析 name
+    if "name" in special_def:
+        result["name"] = _scalar(special_def["name"])
+    
+    # 解析 params
+    if "params" in special_def:
+        result["params"] = special_def["params"]
+    
+    # 解析 transfer_path
+    if "transfer_path" in special_def:
+        tp = special_def["transfer_path"]
+        if isinstance(tp, dict):
+            result["transfer_path"] = tp
+        elif isinstance(tp, list):
+            result["transfer_path"] = _parse_transfer_path_list(tp)
+    
+    # 解析 visibility_change
+    if "visibility_change" in special_def:
+        result["visibility_change"] = _parse_visibility_change(special_def["visibility_change"])
+    
+    # 保存原始定义
+    result["raw_definition"] = {k: v for k, v in special_def.items() 
+                               if k not in ["name", "params", "transfer_path", "visibility_change"]}
+    
+    return result
+
+def _merge_special_actions(special_defs: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """合并被解析器分解的 special 动作定义"""
+    if not special_defs:
+        return []
+    
+    # 按name分组，合并相同name的动作
+    grouped = {}
+    for special_def in special_defs:
+        if isinstance(special_def, dict):
+            name = _scalar(special_def.get("name", ""))
+            if name:
+                if name not in grouped:
+                    grouped[name] = {}
+                # 合并字段
+                for key, value in special_def.items():
+                    if key != "name":
+                        grouped[name][key] = value
+            else:
+                # 没有name的，可能是参数或其他字段，需要与前面的动作合并
+                # 这里简化处理，直接作��独立动作
+                pass
+    
+    # 转换为列表
+    result = []
+    for name, fields in grouped.items():
+        action = {"name": name}
+        action.update(fields)
+        result.append(_parse_special_action(action))
+    
+    return result
+
+def _parse_transfer_path_list(tp_list: List[Any]) -> Dict[str, str]:
+    """解析 from: hand to: field 格式的 transfer_path"""
+    result = {}
+    i = 0
+    while i < len(tp_list) - 1:
+        if isinstance(tp_list[i], str) and tp_list[i].endswith(":"):
+            key = tp_list[i][:-1]  # 去掉冒号
+            result[key] = _scalar(tp_list[i + 1])
+            i += 2
+        else:
+            i += 1
+    return result
+
+def _fix_zone_ids_in_transfer_path(tp: Dict[str, str], pids: List[str]) -> Dict[str, str]:
+    """修复transfer_path中的zone ID，将hand转换为具体的hand:PlayerID"""
+    if not isinstance(tp, dict):
+        return tp
+    
+    result = tp.copy()
+    
+    # 如果from是"hand"，需要转换为具体的hand:PlayerID
+    if result.get("from") == "hand" and pids:
+        # 使用第一个玩家ID作为默认值
+        result["from"] = f"hand:{pids[0]}"
+    
+    # 如果to是"hand"，也需要转换
+    if result.get("to") == "hand" and pids:
+        result["to"] = f"hand:{pids[0]}"
+    
+    return result
+
+def _sanitize_mechanics(mechs: List[Dict[str,Any]]):
+    for m in mechs or []:
+        if not isinstance(m,dict): continue
+        # phase/timing/trigger_condition 缺省
+        m["phase"]=_phase_to_schema(_scalar(m.get("phase") or "playing"))
+        m.setdefault("timing", "during_action")
+        m.setdefault("enabled", True)
+        if str(m.get("timing") or "").strip() not in ("pre_action","post_action","during_action"):
+            m["timing"] = "during_action"
+        m.setdefault("trigger_condition", "always")
+        raw_def = m.get("raw_definition", {}).copy() # Work on a copy to avoid modifying original input
+        # --- Modification: Handle transfer_path for instantiation and Schema compliance ---
+        original_tp = raw_def.get("transfer_path")
+        if original_tp and isinstance(original_tp, dict):
+            from_val = original_tp.get("from")
+            to_val = original_tp.get("to")
+
+            # Check if 'from' or 'to' are templates (e.g., 'hand', 'hand:*') or invalid zone names
+            # If they are, keep the original transfer_path in raw_definition and do NOT create a top-level transfer_path
+            def _is_template(z):
+                return isinstance(z, str) and z in ("hand", "hand:*")
+
+            def _is_valid_zone(z):
+                return isinstance(z, str) and bool(ZONE_RE.match(z))
+
+            # If from or to is a template, or if from/to are not valid zones according to the schema's ZoneID pattern,
+            # then the transfer_path cannot be placed at the top level.
+            if _is_template(from_val) or _is_template(to_val) or not _is_valid_zone(from_val) or not _is_valid_zone(to_val):
+                # The raw_def already contains the original transfer_path, which is correct.
+                # Do not create a top-level transfer_path.
+                # Ensure raw_definition exists and contains the original
+                # --- Modification: Add note for instantiation ---
+                m["raw_definition"] = {"transfer_path_note": {"zone_style": "needs_instantiation"}}
+                # Remove transfer_path from top level if it was accidentally added (shouldn't happen here)
+                m.pop("transfer_path", None)
+            else:
+                # If 'from' and 'to' are concrete and valid zones, move transfer_path to top level
+                m["transfer_path"] = {"from": from_val, "to": to_val}
+                # Remove transfer_path from raw_definition if it's valid and concrete
+                raw_def.pop("transfer_path", None)
+                if raw_def: # Only keep raw_definition if it has other keys
+                    m["raw_definition"] = raw_def
+                else:
+                    m["raw_definition"] = {}
+        else:
+            # If no original transfer_path, or it's not a dict, just keep raw_def as is
+            m["raw_definition"] = raw_def
+
+        # 清掉 None 值，避免 schema 报错
+        for k in ("min_players","max_players","usage_limit","visibility_change"):
+            if m.get(k, "__absent__") is None:
+                m.pop(k, None)
+
+def _ensure_scoring(ir: Dict[str,Any]) -> Dict[str,Any]:
+    sc=_as_dict(ir.get("scoring"))
+    base=sc.get("base")
+    if not isinstance(base,int) or base<0: sc["base"]=1
+    return sc
+
+def map_to_v095(nz: Dict[str,Any], gdl_text: str = None) -> Dict[str,Any]:
+    # --- Modification: Dynamically set description based on game name ---
+    game_name = _scalar(_as_dict(nz.get("game")).get("name") or "UnnamedGame")
+    if "UNO" in game_name:
+        description = "由标准54张牌叠加UNO特殊牌机制的变体。"
+    elif "奇袭" in game_name:
+        description = "在传统斗地主基础上加入了【援手】和【换位】两个新机制，增加了农民间的协作和角色变换的可能性"
+    else:
+        description = f"由标准54张牌叠加特殊牌机制的变体。" # Generic fallback
+
+    # meta
+    meta={"name": game_name, "version":"v0.95", "origin": "Variant", "seeded": True, "description": description}
+
+    # players
+    players=_derive_players(nz); pids=players.pop("_player_ids", []) # Removed role_defs as not needed
+
+    # cards
+    cards=_ensure_cards(nz)
+
+    # zones - Modified to handle zone definitions from setup
+    zone_defs = _as_list(nz.get("zones", []))
+    zones=_expand_zones(zone_defs, pids)
+
+    # visibility
+    visibility=_expand_vis_hand_star(_as_dict(nz.get("visibility")), pids)
+
+    # combinations
+    combinations=_ensure_combinations(nz)
+
+    # comparison
+    comparison=_as_dict(nz.get("comparison")) or {"same_type": True, "same_len": True, "bomb_beats_all": True, "rocket_top": True, "tiebreaker": "none"}
+
+    # actions
+    actions=_ensure_actions(nz, pids)
+
+    # phases - Modified to handle GDL phase names and map to schema
+    ph=_as_list(nz.get("phases"))
+    allowed={"setup","deal","bid","double","initiative","play","settle","grouping"}
+    # Apply mapping logic using _phase_to_schema
+    cleaned=[]
+    for x in ph:
+        s=str(x).strip()
+        mapped_s = _phase_to_schema(s)
+        if mapped_s in allowed and mapped_s not in cleaned:
+            cleaned.append(mapped_s)
+    # Ensure 'setup' and 'settle' are present, with 'setup' first and 'settle' last
+    if "setup" not in cleaned: cleaned=["setup"]+[t for t in cleaned if t!="setup"]
+    if "settle" not in cleaned: cleaned=[t for t in cleaned if t!="settle"]+["settle"]
+    # Add 'deal' phase if not present, typically after 'setup'
+    if "deal" not in cleaned:
+        setup_idx = -1
+        for i, p in enumerate(cleaned):
+            if p == "setup":
+                setup_idx = i
+                break
+        if setup_idx != -1:
+            cleaned.insert(setup_idx + 1, "deal") # Insert 'deal' after 'setup'
+        else:
+            cleaned = ["deal"] + cleaned # If 'setup' is missing, add 'deal' at the beginning
+    # Add 'play' phase if not present, typically after 'deal'
+    if "play" not in cleaned:
+        deal_idx = -1
+        for i, p in enumerate(cleaned):
+            if p == "deal":
+                deal_idx = i
+                break
+        if deal_idx != -1:
+            cleaned.insert(deal_idx + 1, "play") # Insert 'play' after 'deal'
+        else:
+            # If 'deal' is also missing, try 'setup'
+            setup_idx = -1
+            for i, p in enumerate(cleaned):
+                if p == "setup":
+                    setup_idx = i
+                    break
+            if setup_idx != -1:
+                cleaned.insert(setup_idx + 1, "play") # Insert 'play' after 'setup'
+            else:
+                cleaned = ["play"] + cleaned # If neither 'setup' nor 'deal' is present, add 'play' at the beginning
+
+
+    # turns
+    turns=_as_dict(nz.get("turns")) or {}
+    # Use the uniquely generated player IDs from _derive_players for order
+    # If turns.order is empty or not provided, use pids
+    order=turns.get("order") or pids
+    # If turns.order was provided but is the original ["Landlord", "Peasant", "Peasant", "Peasant"],
+    # it should be replaced by the unique pids generated in _derive_players.
+    # The pids are ["Landlord", "Peasant", "Peasant_1", "Peasant_2"] which is the desired outcome.
+    # So, we prioritize the pids (which are unique) over the potentially non-unique turns.order.
+    # However, if turns.order is explicitly set *after* uniquification by normalizer, we should respect it.
+    # The safest way is to always use pids if they are available and represent the actual unique player turn order.
+    # Let's assume pids represents the final desired turn order.
+    # Use the unique player IDs generated by _derive_players
+    turns["order"]=pids
+    if not turns.get("leader") and pids: turns["leader"]=pids[0] # Use first unique ID as leader
+    turns.setdefault("trick_end_on", "two_pass")
+    # next_leader
+    ext=_as_dict(nz.get("extensions")); te=turns.get("trick_end_on","two_pass")
+    if te=="custom":
+        t_ext=_as_dict(ext.get("trick_end_on"))
+        next_leader = "last_non_pass" if t_ext.get("mode")=="consecutive_passes" else "fixed"
+    else:
+        next_leader = "last_non_pass"
+    turns.setdefault("next_leader", next_leader)
+
+    # ending & scoring
+    ending=_as_dict(nz.get("ending")) or {"when":"any_hand_empty"}
+    scoring=_ensure_scoring(nz)
+
+    # mechanics
+    mechs=_as_list(nz.get("special_mechanics")); _sanitize_mechanics(mechs)
+
+    # extensions - Add card mappings
+    extensions=_as_dict(nz.get("extensions"))
+    extensions["cards_mapping"] = {
+        "rank_name_to_int": {
+            "J": 11,
+            "Q": 12,
+            "K": 13,
+            "A": 14,
+            "2": 15
+        },
+        "suit_name_to_carrier": {
+            "Spade": "Spade",
+            "Heart": "Heart",
+            "Club": "Club",
+            "Diamond": "Diamond"
+        }
+    }
+
+
+    ir = {
+        "meta": meta,
+        "players": players,
+        "cards": cards,
+        "zones": zones,
+        "visibility": visibility,
+        "combinations": combinations,
+        "comparison": comparison,
+        "actions": actions,
+        "phases": cleaned,
+        "turns": turns,
+        "ending": ending,
+        "scoring": scoring,
+        "special_mechanics": mechs,
+        "extensions": extensions
+    }
+
+    missing=[k for k in REQUIRED if k not in ir]
+    if missing: raise ValueError(f"Missing required keys after mapping: {missing}")
+    return ir

normalizer_v2.py

@@ -0,0 +1,454 @@
+# -*- coding: utf-8 -*-
+"""
+normalizer_v2.py — 语义标准化（兼容多布局，提取 mechanics 名称/阶段/时机）
+"""
+from __future__ import annotations
+from typing import Any, Dict, List
+from copy import deepcopy
+
+def _as_list(x):
+    if x is None: return []
+    return x if isinstance(x, list) else [x]
+
+def _as_dict(x):
+    return x if isinstance(x, dict) else {}
+
+def _scalar(x: Any) -> str:
+    if isinstance(x, str): return x
+    if isinstance(x, (int, float)): return str(x)
+    if isinstance(x, dict):
+        if "_" in x and isinstance(x["_"], list) and x["_"] and isinstance(x["_"][0], (str,int,float)):
+            return _scalar(x["_"][0])
+        if "name" in x and isinstance(x["name"], str): return x["name"]
+        if len(x)==1:
+            k, v = next(iter(x.items()))
+            if v in (None, {}) and isinstance(k, str):
+                return k
+    if isinstance(x, list) and x:
+        return _scalar(x[0])
+    return ""
+
+def _is_standard_mechanic_structure(node: Any) -> bool:
+    """
+    检查一个节点是否是标准的 {"mechanic": {...}} 结构。
+    这是 GDL 中 (mechanic ...) 被 _to_obj 解析后的直接结果。
+    """
+    return isinstance(node, dict) and len(node) == 1 and 'mechanic' in node and isinstance(node['mechanic'], dict)
+
+def _extract_mechanics_from_sm(sm_node: Any) -> List[Dict[str, Any]]:
+    """
+    专门从 special_mechanics 的节点中提取 mechanic 定义。
+    sm_node 是 special_mechanics 键对应的值。
+    这个函数严格处理 special_mechanics 的内容，避免误判内部结构。
+    """
+    mechanics = []
+    # sm_node 应该是 {'mechanic': [...]} 或 {'mechanic': {...}} 或 [{'mechanic': {...}}, ...]
+    sm_dict = _as_dict(sm_node)
+
+    if 'mechanic' in sm_dict:
+        mech_content = sm_dict.get("mechanic")
+        if isinstance(mech_content, dict):
+            # Case 1: {"mechanic": {"mechanic_name": {...}, "mechanic_name2": {...}}}
+            # 这种情况发生在 _to_obj 合并了多个同名 mechanic 时
+            for name, definition in mech_content.items():
+                if isinstance(definition, dict):
+                    # 构造标准的 mechanic 结构
+                    mechanic_def = definition.copy()
+                    # 确保有 name 字段
+                    if 'name' not in mechanic_def:
+                        mechanic_def['name'] = name
+                    mechanics.append({"mechanic": mechanic_def})
+        elif isinstance(mech_content, list):
+            # Case 2: {"mechanic": [...]}
+            for item in mech_content:
+                # item 应该是 {"_": ["Name", ...], ...} 或 {"name": "Name", ...} 这样的结构 inside the mechanic
+                # Check if item itself is the content of a mechanic (i.e., has 'name' or '_')
+                if isinstance(item, dict) and ('name' in item or ('_' in item and isinstance(item.get('_'), list) and item['_'] and isinstance(item['_'][0], str))):
+                    # Wrap it in the standard {"mechanic": {...}} format
+                    mechanics.append({"mechanic": item})
+    elif isinstance(sm_node, list):
+        # Case 3: [{"mechanic": {...}}, ...] - A list of standard structures
+        for item in sm_node:
+            if _is_standard_mechanic_structure(item):
+                mechanics.append(item) # item is {"mechanic": {...}}
+    elif _is_standard_mechanic_structure(sm_node):
+        # Case 4: {"mechanic": {...}} - A single standard structure
+        mechanics.append(sm_node) # sm_node is {"mechanic": {...}}
+    # If sm_node is just a dict like {"_": ["Name", ...]}, it's likely an error or edge case from _merge_kv_list_to_dict
+    # We ignore this case as it shouldn't happen if special_mechanics is structured correctly in GDL.
+
+    return mechanics
+
+
+def _walk_collect_mechs(node, bucket, inside_special_mechanics=False):
+    """
+    递归收集 special_mechanics / actions.special
+    inside_special_mechanics 标志用于防止在 mechanic 内部结构中递归查找其他 mechanic。
+    """
+    if isinstance(node, dict):
+        # 专门处理 special_mechanics 键 - 这是主要的 mechanic 来源
+        if "special_mechanics" in node:
+            sm_node = node.get("special_mechanics")
+            # Extract mechanics only from this specific key using the dedicated function
+            extracted = _extract_mechanics_from_sm(sm_node)
+            bucket.extend(extracted)
+            # Mark that we are now processing inside special_mechanics context for recursion
+            # We don't pass this flag deeper here, as _extract_mechanics_from_sm handles the context.
+        # 处理 actions.special
+        elif "actions" in node and not inside_special_mechanics: # Only process actions if not already inside special_mechanics
+            a = _as_dict(node.get("actions"))
+            special_actions = _as_list(a.get("special"))
+            # 检查 special_actions 中是否包含 mechanic 定义 (This is less common than in special_mechanics)
+            for sa in special_actions:
+                 # sa 可能是 {"name": "...", ...} or {"_": ["Name", ...], ...}
+                 # Check if it matches a basic mechanic-like structure
+                 if isinstance(sa, dict) and ("name" in sa or ("_" in sa and isinstance(sa.get("_"), list) and sa["_"] and isinstance(sa["_"][0], str))):
+                     bucket.append({"mechanic": sa}) # Wrap in standard format
+        # Recurse into other keys, but avoid recursing into known internal structures of a mechanic
+        # like transfer_path, visibility_change, etc., which are unlikely to contain top-level mechanics.
+        # The main risk was from 'phases' -> 'mechanic_conditions', which we handled by using _extract_mechanics_from_sm.
+        # We can now recurse more safely, but mark if we are inside a mechanic's content.
+        for k, v in node.items():
+            if k in ("special_mechanics", "actions"): # Already handled these above
+                continue
+            # Do not recurse into known internal structures that are not top-level mechanic containers
+            if k in ("transfer_path", "visibility_change", "params"): # Add other known internal keys if needed
+                 continue
+            _walk_collect_mechs(v, bucket, inside_special_mechanics=inside_special_mechanics)
+
+    elif isinstance(node, list):
+        # If the top-level is a list containing special_mechanics, handle it
+        # Or if it's a list inside a mechanic, recurse carefully
+        for v in node:
+            _walk_collect_mechs(v, bucket, inside_special_mechanics)
+
+
+def _collect_mechanics(parsed: Dict[str, Any]) -> List[Dict[str, Any]]:
+    items: List[Any] = []
+    # Start the walk from the top-level game structure
+    _walk_collect_mechs(parsed, items, inside_special_mechanics=False)
+    mechs: List[Dict[str, Any]] = []
+    for i, raw in enumerate(items):
+        m = _as_dict(raw)
+        if not m: continue
+        # --- Process standard structure {"mechanic": {...}} ---
+        m_content = m
+        if len(m) == 1 and 'mechanic' in m and isinstance(m['mechanic'], dict):
+            m_content = m['mechanic']
+        else:
+            # If the raw item is not in the expected {"mechanic": {...}} format,
+            # it means the extraction logic failed or it was collected incorrectly.
+            # For safety, skip.
+            continue
+
+        # Now m_content holds the actual mechanic definition like {"_": ["Name", ...], ...} or {"name": "Name", ...}
+        name = _scalar(m_content.get("name") or (m_content.get("_") or [None])[0] or "")
+        if not name:
+             name = f"mechanic@{i}"
+        phase = _scalar(m_content.get("phase") or "playing_phase")  # 先拿原词
+        timing = _scalar(m_content.get("timing") or "")
+        # 修改：将 phase 映射为标准名称，例如 playing_phase -> playing
+        standard_phase = phase.replace("_phase", "")
+        mech = {
+            "name": name,
+            "enabled": True if _scalar(m_content.get("enabled")) in ("true","1","yes","True") else True,
+            "description": _scalar(m_content.get("description")),
+            "phase": standard_phase, # 使用标准名称
+            "timing": timing,
+            "trigger_condition": _scalar(m_content.get("trigger_condition")),
+            "raw_definition": {
+                k: v for k, v in m_content.items()
+                if k not in ("name","enabled","description","phase","timing","trigger_condition")
+            }
+        }
+        mechs.append(mech)
+    return mechs
+
+def _collect_mechanics_from_sexpr(parsed: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """
+    直接从 S-expression 中收集 mechanics，避免 _to_obj 的键合并问题
+    """
+    from gdl_parser_v2 import parse_sexpr
+    
+    mechanics = []
+    
+    def find_and_extract_mechanics(obj, path=''):
+        if isinstance(obj, dict):
+            for k, v in obj.items():
+                if k == 'special_mechanics':
+                    # 找到 special_mechanics，尝试提取其中的 mechanics
+                    if isinstance(v, dict) and 'mechanic' in v:
+                        mech_content = v['mechanic']
+                        if isinstance(mech_content, dict):
+                            # 处理合并后的情况：{"mechanic_name": {...}, "mechanic_name2": {...}}
+                            for name, definition in mech_content.items():
+                                if isinstance(definition, dict):
+                                    mechanics.append(_process_mechanic_definition(name, definition))
+                else:
+                    find_and_extract_mechanics(v, f'{path}.{k}' if path else k)
+        elif isinstance(obj, list):
+            for i, item in enumerate(obj):
+                find_and_extract_mechanics(item, f'{path}[{i}]')
+    
+    find_and_extract_mechanics(parsed)
+    return mechanics
+
+def _collect_mechanics_from_raw_sexpr(gdl_text: str) -> List[Dict[str, Any]]:
+    """
+    直接从原始 GDL 文本中收集 mechanics，避免解��器的键合并问题
+    """
+    from gdl_parser_v2 import parse_sexpr
+    
+    mechanics = []
+    
+    # 找到 special_mechanics 部分
+    lines = gdl_text.split('\n')
+    start_idx = -1
+    end_idx = -1
+    paren_count = 0
+    
+    for i, line in enumerate(lines):
+        if '(special_mechanics' in line:
+            start_idx = i
+            paren_count = line.count('(') - line.count(')')
+            break
+    
+    if start_idx != -1:
+        for i in range(start_idx + 1, len(lines)):
+            paren_count += lines[i].count('(') - lines[i].count(')')
+            if paren_count == 0:
+                end_idx = i
+                break
+    
+    if start_idx != -1 and end_idx != -1:
+        special_mechanics_lines = lines[start_idx:end_idx + 1]
+        special_mechanics_text = '\n'.join(special_mechanics_lines)
+        
+        try:
+            sexpr = parse_sexpr(special_mechanics_text)
+            if len(sexpr) > 0 and isinstance(sexpr[0], list):
+                for item in sexpr[0]:
+                    if isinstance(item, list) and len(item) > 0 and item[0] == 'mechanic':
+                        # 这是一个 mechanic 定义
+                        name = item[1] if len(item) > 1 else "unknown"
+                        
+                        # 解析 mechanic 的属性
+                        definition = {}
+                        for i in range(2, len(item)):
+                            if isinstance(item[i], list) and len(item[i]) >= 2:
+                                key = item[i][0]
+                                value = item[i][1] if len(item[i]) == 2 else item[i][1:]
+                                definition[key] = value
+                        
+                        mechanics.append(_process_mechanic_definition(name, definition))
+        except Exception as e:
+            print(f"Error parsing special_mechanics: {e}")
+    
+    return mechanics
+
+def _process_mechanic_definition(name: str, definition: Dict[str, Any]) -> Dict[str, Any]:
+    """处理单个 mechanic 定义"""
+    phase = _scalar(definition.get("phase") or "playing_phase")
+    timing = _scalar(definition.get("timing") or "")
+    standard_phase = phase.replace("_phase", "")
+    
+    return {
+        "name": name,
+        "enabled": True if _scalar(definition.get("enabled")) in ("true","1","yes","True") else True,
+        "description": _scalar(definition.get("description")),
+        "phase": standard_phase,
+        "timing": timing,
+        "trigger_condition": _scalar(definition.get("trigger_condition")),
+        "raw_definition": {
+            k: v for k, v in definition.items()
+            if k not in ("name","enabled","description","phase","timing","trigger_condition")
+        }
+    }
+
+def normalize_ir(parsed: Dict[str, Any], gdl_text: str = None) -> Dict[str, Any]:
+    p = _as_dict(parsed)
+    game = _as_dict(p.get("game") or p)
+
+    out: Dict[str, Any] = {"game": {}}
+
+    # ---- name ----
+    nm = _scalar(game.get("name") or game.get("_") or "")
+    out["game"]["name"] = nm or "UnnamedGame"
+
+    # ---- players count ----
+    players_count = game.get("players", 0)
+    out["game"]["players_count"] = players_count # 为 mapper_v2 提供原始玩家数量
+
+    # ---- roles ----
+    roles: List[Dict[str, Any]] = []
+    if "roles" in game:
+        flat = []
+        for r in _as_list(game["roles"]):
+            if isinstance(r, list): flat.extend(r)
+            else: flat.append(r)
+        for r in flat:
+            rd = _as_dict(r)
+            if "role" in rd and isinstance(rd["role"], dict):
+                u = rd["role"].get("_")
+                if isinstance(u, list) and u:
+                    name = _scalar(u[0]); cnt = 1
+                    if len(u) >= 2:
+                        try: cnt = int(u[1])
+                        except: cnt = 1
+                    roles.append({"name": name or "Player", "count": max(1, cnt)}); continue
+            name = _scalar(rd.get("name") or rd.get("role") or "Player")
+            cnt  = rd.get("count", 1)
+            try: cnt=int(cnt)
+            except: cnt=1
+            roles.append({"name": name, "count": max(1,cnt)})
+    out["game"]["roles"] = roles or [{"name":"Player","count": game.get("players") or 0}]
+
+    # ---- turns.order from turn_order ----
+    order = []
+    to = _as_list(game.get("turn_order"))
+    if to:
+        flat=[]
+        for elem in to:
+            if isinstance(elem, list): flat.extend(elem)
+            else: flat.append(elem)
+        # {"Landlord":{"_":[...]} }
+        if flat and isinstance(flat[0], dict) and len(flat[0])==1:
+            k, v = next(iter(flat[0].items()))
+            seq = [k]
+            if isinstance(v, dict) and isinstance(v.get("_"), list): seq.extend(v.get("_"))
+            order = [ _scalar(x) for x in seq ]
+        else:
+            order = [ _scalar(x) for x in flat ]
+    if order:
+        out["turns"] = {"order": order}
+
+    # ---- phases ---- 兼容 *_phase 键名
+    phases = _as_list(game.get("phases"))
+    phase_names: List[str] = []
+    if phases:
+        for sub in phases:
+            xs = _as_list(sub) if isinstance(sub, list) else [sub]
+            for x in xs:
+                s = _scalar(x)
+                if s:
+                    phase_names.append(s)
+                elif isinstance(x, dict) and len(x)==1:
+                    k = next(iter(x.keys()))
+                    if isinstance(k, str) and k.endswith("_phase"):
+                        # 修改：将 phase 映射为标准名称
+                        standard_name = k.replace("_phase", "")
+                        phase_names.append(standard_name)
+    out["phases"] = phase_names # Ensure 'phases' key is set in output
+
+    # ---- deck info ----
+    deck_info = _as_dict(game.get("deck"))
+    if deck_info:
+        # Extract deck type, shuffling, deal_pattern
+        deck_type = _scalar(deck_info.get("_") or deck_info.get("type") or "Standard54") # Default to Standard54
+        shuffling = _scalar(deck_info.get("shuffling"))
+        deal_pattern = _scalar(deck_info.get("deal_pattern"))
+        out["game"]["deck"] = {
+            "type": deck_type,
+            "shuffling": shuffling,
+            "deal_pattern": deal_pattern
+        }
+
+    # ---- setup details ----
+    setup_info = _as_dict(game.get("setup"))
+    if setup_info:
+        # Extract zones, card_relations, deal count
+        zones_info = _as_dict(setup_info.get("zones"))
+        card_relations_info = _as_dict(setup_info.get("card_relations"))
+        deal_count = setup_info.get("deal")
+
+        if zones_info:
+            zone_defs = []
+            if "hand" in zones_info:
+                zone_defs.append({"type": "hand", **_as_dict(zones_info.get("hand"))})
+            if "field" in zones_info:
+                zone_defs.append({"type": "field", **_as_dict(zones_info.get("field"))})
+            if "discard_pile" in zones_info:
+                zone_defs.append({"type": "discard_pile", **_as_dict(zones_info.get("discard_pile"))})
+            if "main_deck" in zones_info:
+                zone_defs.append({"type": "main_deck", **_as_dict(zones_info.get("main_deck"))})
+            if "special_deck" in zones_info:
+                # Handle special_deck which can be a list or dict
+                sd = zones_info.get("special_deck")
+                if isinstance(sd, dict):
+                    # If it's a dict like { (UNO_Cards) ... }
+                    # We need to extract the name and details
+                    # The structure is likely {"UNO_Cards": {details}}
+                    for name, details in sd.items():
+                        if isinstance(details, dict):
+                            zone_defs.append({"type": "special_deck", "name": name, **details})
+                        else:
+                            zone_defs.append({"type": "special_deck", "name": name, "initial_cards": details})
+                elif isinstance(sd, list):
+                    # If it's a list, handle each element
+                    for item in sd:
+                        if isinstance(item, dict) and len(item) == 1:
+                             name, details = next(iter(item.items()))
+                             zone_defs.append({"type": "special_deck", "name": name, **_as_dict(details)})
+            out["zones"] = zone_defs # Ensure 'zones' key is set in output
+
+        if card_relations_info:
+            out["card_relations"] = card_relations_info
+
+        if deal_count is not None:
+            out["setup"] = {"deal": deal_count}
+
+    # ---- combinations ----
+    combinations_info = _as_dict(game.get("combinations"))
+    if combinations_info:
+        # Extract custom_combinations
+        custom_combs = []
+        if "custom_combination" in combinations_info:
+            raw_customs = _as_list(combinations_info.get("custom_combination"))
+            for cc in raw_customs:
+                 cc_dict = _as_dict(cc)
+                 if "_" in cc_dict and isinstance(cc_dict["_"], list) and cc_dict["_"]:
+                     name = _scalar(cc_dict["_"][0])
+                     spec = {k: v for k, v in cc_dict.items() if k != "_"}
+                     custom_combs.append({"name": name, "spec": spec})
+                 elif "name" in cc_dict:
+                     name = _scalar(cc_dict.get("name"))
+                     spec = {k: v for k, v in cc_dict.items() if k != "name"}
+                     custom_combs.append({"name": name, "spec": spec})
+        out["combinations"] = {"custom": custom_combs} # Ensure 'combinations' key is set in output with custom part
+
+
+    # ---- mechanics ----
+    # 如果有原始 GDL 文本，尝试直接从文本中收集 mechanics
+    if gdl_text:
+        try:
+            out["special_mechanics"] = _collect_mechanics_from_raw_sexpr(gdl_text)
+            if not out["special_mechanics"]:
+                # 如果新方法没有找到，回退到旧方法
+                out["special_mechanics"] = _collect_mechanics({"game": game})
+        except:
+            # 如果新方法出错，回退到旧方法
+            out["special_mechanics"] = _collect_mechanics({"game": game})
+    else:
+        # 没有原始文本，使用旧方法
+        out["special_mechanics"] = _collect_mechanics({"game": game})
+
+    # ---- 提取 actions（可能在 setup 中）----
+    actions = None
+    if "actions" in game:
+        actions = deepcopy(game["actions"])
+    elif "setup" in game:
+        setup = _as_list(game["setup"])
+        for item in setup:
+            if isinstance(item, dict) and "actions" in item:
+                actions = deepcopy(item["actions"])
+                break
+    
+    if actions:
+        out["actions"] = actions
+
+    # ---- 保留原始信息（由 mapper 兜底）----
+    for k in ("visibility","invariants","scoring","extensions"):
+        if k in p: out[k] = deepcopy(p[k])
+        elif k in game: out[k] = deepcopy(game[k])
+
+    return out

poker_gdl_ir.schema.v0.95.zh.json

@@ -0,0 +1,1515 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema  ",
+  "$id": "https://example.com/schemas/poker_gdl_ir.schema.v0.95.zh.json  ",
+  "title": "Poker-GDL IR Schema v0.95（含中文注释）",
+  "description": "扑克类（牌型压制类）玩法的 GDL → IR 标准。v0.95 优化：采用策略一，引入 raw_definition 和 extensions 字段以增强 Schema 扩展性。",
+  "type": "object",
+  "required": [
+    "meta",
+    "players",
+    "cards",
+    "zones",
+    "visibility",
+    "combinations",
+    "comparison",
+    "actions",
+    "phases",
+    "turns",
+    "ending",
+    "scoring"
+  ],
+  "additionalProperties": false,
+  "$defs": {
+    "PID": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_:-]+$",
+      "description": "玩家/角色标识，如 L、P1、P2"
+    },
+    "ZoneID": {
+      "type": "string",
+      "pattern": "^(hand:[A-Za-z0-9_:-]+|field|main_deck|discard_pile|reserve_zone|public_pool|item_deck:[A-Za-z0-9_:-]+|history_deck)$",
+      "description": "区域标识；手牌需带所属者，如 hand:L；道具牌库需带名称，如 item_deck:BulletCards"
+    },
+    "Audience": {
+      "type": "string",
+      "enum": [
+        "owner",
+        "teammates",
+        "enemies",
+        "all",
+        "none"
+      ],
+      "description": "可见性受众"
+    },
+    "VisibilityState": {
+      "type": "string",
+      "enum": [
+        "visible",
+        "hidden",
+        "partial_suit",
+        "partial_rank"
+      ],
+      "description": "可见性枚举"
+    },
+    "Rank": {
+      "type": "integer",
+      "description": "推荐映射：3..15=3..A, 16=小王, 17=大王"
+    },
+    "Suit": {
+      "type": "string",
+      "enum": ["Spade", "Heart", "Club", "Diamond"],
+      "description": "花色，如 S/H/D/C (现在使用GDL中的标准名称)"
+    },
+    "ComboType": {
+      "type": "string",
+      "enum": [
+        "single",
+        "pair",
+        "triple",
+        "straight",
+        "pairs_chain",
+        "airplane",
+        "triple_with_single",
+        "triple_with_pair",
+        "four_with_twoSingles",
+        "four_with_twoPairs",
+        "bomb",
+        "rocket",
+        "double_chain_bomb",
+        "triple_chain_bomb",
+        "quad_chain_bomb",
+        "penta_chain_bomb",
+        "chain_triple",
+        "custom"
+      ],
+      "description": "牌型名"
+    },
+    "Transfer": {
+      "type": "object",
+      "required": [
+        "from",
+        "to"
+      ],
+      "additionalProperties": false,
+      "description": "原子转移：从某区域移动若干牌到另一区域；所有动作最终都可分解为 Transfer 序列。",
+      "properties": {
+        "from": {
+          "$ref": "#/$defs/ZoneID"
+        },
+        "to": {
+          "$ref": "#/$defs/ZoneID"
+        },
+        "count": {
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "const": "all"
+            }
+          ],
+          "description": "移动数量；all 表示全部"
+        },
+        "filter": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "筛选器：按点数/花色/标签选择牌",
+          "properties": {
+            "ranks": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/Rank"
+              }
+            },
+            "suits": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/Suit"
+              }
+            },
+            "tags": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "VisibilityChange": {
+      "type": "object",
+      "required": [
+        "to",
+        "state"
+      ],
+      "additionalProperties": false,
+      "description": "动作引发的可见性变更",
+      "properties": {
+        "to": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Audience"
+          }
+        },
+        "state": {
+          "$ref": "#/$defs/VisibilityState"
+        },
+        "on_target": {
+          "type": "boolean",
+          "default": true
+        }
+      }
+    },
+
+    "Mechanic": {
+      "type": "object",
+      "required": ["name", "enabled", "phase", "timing", "trigger_condition"],
+      "additionalProperties": false,
+      "description": "特殊机制的通用结构，对应 GDL 中 special_mechanics 的 mechanic 模板。支持 raw_definition 以应对无法精确映射的情况。",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "机制名称"
+        },
+        "enabled": {
+          "type": "boolean",
+          "description": "是否启用"
+        },
+        "description": {
+          "type": "string",
+          "description": "机制描述"
+        },
+        "phase": {
+          "type": "string",
+          "enum": ["setup", "bidding", "doubling", "initiative", "playing", "settlement", "grouping"],
+          "description": "所属阶段"
+        },
+        "timing": {
+          "type": "string",
+          "enum": ["pre_action", "post_action", "during_action"],
+          "description": "触发时机"
+        },
+        "trigger_condition": {
+          "type": "string",
+          "description": "触发条件表达式"
+        },
+        "usage_limit": {
+          "type": "string",
+          "description": "使用次数限制，如 'once_per_game', 'once_per_round', 'N_times'"
+        },
+        "min_players": {
+          "type": "integer",
+          "minimum": 2,
+          "description": "最小玩家数"
+        },
+        "max_players": {
+          "type": "integer",
+          "minimum": 2,
+          "description": "最大玩家数"
+        },
+        "required_conditions": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "前置条件列表"
+        },
+        "effect_description": {
+          "type": "string",
+          "description": "效果描述"
+        },
+        "transfer_path": {
+          "$ref": "#/$defs/Transfer"
+        },
+        "visibility_change": {
+          "$ref": "#/$defs/VisibilityChange"
+        },
+
+        "raw_definition": {
+          "type": "object",
+          "description": "当标准字段无法精确表示 GDL 中的 mechanic 时，存储其原始定义。"
+        }
+      }
+    }
+  },
+  "properties": {
+    "meta": {
+      "type": "object",
+      "required": [
+        "name",
+        "version"
+      ],
+      "additionalProperties": false,
+      "description": "玩法元信息",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        },
+        "origin": {
+          "type": "string",
+          "enum": [
+            "Traditional",
+            "Variant",
+            "Innovative"
+          ],
+          "default": "Variant"
+        },
+        "seeded": {
+          "type": "boolean",
+          "default": true
+        },
+        "description": {
+          "type": "string"
+        }
+      }
+    },
+    "players": {
+      "type": "object",
+      "required": [
+        "count"
+      ],
+      "additionalProperties": false,
+      "description": "玩家配置",
+      "properties": {
+        "count": {
+          "type": "integer",
+          "minimum": 2,
+          "maximum": 6
+        },
+        "roles": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "count"], 
+            "properties": {
+              "name": { "type": "string" },
+              "count": { "type": "integer", "minimum": 1 },
+              "players": { 
+                "type": "array",
+                "items": { "$ref": "#/$defs/PID" },
+                "description": "属于此角色的具体玩家ID列表，例如 ['Landlord', 'Peasant_1', 'Peasant_2']。此字段为可选扩展。"
+              },
+              "team": { "type": "string" },
+              "special_ability": { "type": "string" }
+            },
+            "additionalProperties": false 
+          }
+        },
+        "teams": {
+          "type": "array",
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/PID"
+            }
+          }
+        }
+      }
+    },
+    "cards": {
+      "type": "object",
+      "required": [
+        "ranks",
+        "suits"
+      ],
+      "additionalProperties": false,
+      "description": "牌组配置",
+      "properties": {
+        "ranks": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Rank"
+          },
+          "minItems": 1,
+          "description": "点数列表"
+        },
+        "suits": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Suit"
+          },
+          "description": "花色列表"
+        },
+        "jokers": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "大小王点数映射",
+          "properties": {
+            "small": {
+              "$ref": "#/$defs/Rank"
+            },
+            "big": {
+              "$ref": "#/$defs/Rank"
+            }
+          }
+        },
+        "copies_per_deck": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 1,
+          "description": "每副牌的复制份数"
+        },
+        "num_decks": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 1,
+          "description": "使用副数"
+        },
+        "straight_exclude": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Rank"
+          },
+          "description": "顺子禁入点数，如 2/王"
+        },
+        "per_rank_copies": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "description": "【v0.93】按点数单独指定张数，如 {\"16\":1,\"17\":1,\"18\":1}"
+        },
+        "suitless_ranks": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Rank"
+          },
+          "description": "【v0.93】无花色点数（王、龙等不随花色展开）"
+        }
+      }
+    },
+    "zones": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/ZoneID"
+      },
+      "minItems": 1,
+      "uniqueItems": true,
+      "description": "区域列表：hand:*, field, main_deck, discard_pile, reserve_zone, public_pool, item_deck:*, history_deck ..."
+    },
+    "visibility": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "区域可见性设定",
+      "properties": {
+        "defaults": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/VisibilityState"
+          },
+          "description": "全局默认"
+        },
+        "by_zone": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "state": {
+                "$ref": "#/$defs/VisibilityState"
+              },
+              "audience": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/Audience"
+                }
+              }
+            }
+          },
+          "description": "按区覆盖"
+        }
+      }
+    },
+    "invariants": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "不变量约束",
+      "properties": {
+        "physical_conservation": {
+          "type": "boolean",
+          "default": true,
+          "description": "物理守恒：总牌数不变"
+        },
+        "no_card_from_void": {
+          "type": "boolean",
+          "default": true,
+          "description": "禁止无源牌"
+        },
+        "max_hand_size": {
+          "type": "integer"
+        },
+        "max_public_pool": {
+          "type": "integer"
+        },
+        "same_rank_max": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "sequence_span_max": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "team_membership_consistent": {
+          "type": "boolean",
+          "default": true
+        },
+        "all_transfers_use_defined_zones": {
+          "type": "boolean",
+          "default": true
+        },
+        "no_card_appears_in_undefined_zone": {
+          "type": "boolean",
+          "default": true
+        }
+      }
+    },
+    "card_relations": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "牌值与关系定义",
+      "properties": {
+        "card_values": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Rank"
+          },
+          "description": "牌值大小顺序，从低到高"
+        },
+        "used_in": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "指定使用位置"
+        },
+        "continuous_relations": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": { "type": "string" },
+              "sequence": { "type": "array", "items": { "$ref": "#/$defs/Rank" } },
+              "used_in": { "type": "array", "items": { "type": "string" } }
+            }
+          },
+          "description": "连续关系定义"
+        },
+        "non_continuous_cards": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Rank"
+          },
+          "description": "非连续牌"
+        },
+        "same_value_relation": {
+          "type": "string",
+          "enum": ["same_number", "same_suit"],
+          "default": "same_number"
+        },
+        "ace_position": {
+          "type": "string",
+          "enum": ["first_last_second_last", "anywhere"],
+          "default": "anywhere"
+        },
+        "two_position": {
+          "type": "string",
+          "enum": ["first_second_first_last", "anywhere"],
+          "default": "anywhere"
+        },
+        "suit_relations": {
+          "type": "object",
+          "properties": {
+            "order": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/Suit"
+              }
+            },
+            "used_in": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "joker_rules": {
+          "type": "object",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": ["off", "wild_only", "power_only", "wild_and_power"],
+              "default": "off"
+            },
+            "exclusivity": {
+              "type": "string",
+              "enum": ["exclusive", "hybrid"]
+            },
+            "wildcard_scope": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/ComboType"
+              },
+              "description": "赖子作用域"
+            },
+            "wildcard_loses_rank": {
+              "type": "boolean",
+              "default": false,
+              "description": "赖子是否失去单牌牌力"
+            },
+            "power_single": {
+              "type": "object",
+              "properties": {
+                "enabled": { "type": "boolean" },
+                "beats": { "type": "string", "enum": ["all_singles", "rank_list"] },
+                "rank_list": { "type": "array", "items": { "type": "string" } }
+              }
+            },
+            "power_pair": {
+              "type": "object",
+              "properties": {
+                "enabled": { "type": "boolean" },
+                "beats": { "type": "string", "enum": ["all_pairs", "rank_list"] },
+                "rank_list": { "type": "array", "items": { "type": "string" } }
+              }
+            }
+          }
+        },
+        "unique_cards": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "唯一牌列表，如 Spade3"
+        }
+      }
+    },
+    "combinations": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "牌型族定义",
+      "properties": {
+        "single": {
+          "type": "object"
+        },
+        "pair": {
+          "type": "object"
+        },
+        "triple": {
+          "type": "object"
+        },
+        "straight": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "min_len": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "no_ranks": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/Rank"
+              }
+            }
+          },
+          "description": "顺子"
+        },
+        "pairs_chain": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "min_len": {
+              "type": "integer",
+              "minimum": 1
+            }
+          },
+          "description": "连对"
+        },
+        "airplane": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "min_len": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "wings": {
+              "type": "string",
+              "enum": [
+                "single",
+                "pair",
+                "none"
+              ],
+              "default": "none"
+            }
+          },
+          "description": "飞机（可带翅膀）"
+        },
+        "triple_with_single": {
+          "type": "object"
+        },
+        "triple_with_pair": {
+          "type": "object"
+        },
+        "four_with_twoSingles": {
+          "type": "object"
+        },
+        "four_with_twoPairs": {
+          "type": "object"
+        },
+        "bomb": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "len": {
+              "type": "integer",
+              "const": 4
+            }
+          },
+          "description": "四张炸"
+        },
+        "rocket": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "ranks": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/Rank"
+              }
+            }
+          },
+          "description": "王炸"
+        },
+        "custom": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "name"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "spec": {
+                "type": "object"
+              }
+            }
+          },
+          "description": "自定义牌型/特殊牌"
+        }
+      }
+    },
+    "comparison": {
+      "type": "object",
+      "required": [
+        "same_type",
+        "same_len"
+      ],
+      "additionalProperties": false,
+      "description": "比较总则",
+      "properties": {
+        "same_type": {
+          "type": "boolean",
+          "description": "是否强制同型比较"
+        },
+        "same_len": {
+          "type": "boolean",
+          "description": "是否强制相同长度"
+        },
+        "bomb_beats_all": {
+          "type": "boolean",
+          "default": true,
+          "description": "炸弹压制普通牌"
+        },
+        "rocket_top": {
+          "type": "boolean",
+          "default": true,
+          "description": "王炸最大"
+        },
+        "tiebreaker": {
+          "type": "string",
+          "enum": [
+            "suit",
+            "first_played",
+            "none"
+          ],
+          "default": "none",
+          "description": "平手裁决"
+        }
+      }
+    },
+    "comparison_ex": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "精细比较规则",
+      "properties": {
+        "per_combo": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "require_same_length": {
+                "type": "boolean",
+                "default": true
+              },
+              "compare_by": {
+                "type": "string",
+                "enum": [
+                  "sequence_start",
+                  "sequence_end",
+                  "highest_triple_value",
+                  "main_rank",
+                  "length_first_then_rank",
+                  "custom"
+                ],
+                "default": "main_rank"
+              },
+              "side_card_rule": {
+                "type": "string",
+                "enum": [
+                  "ignore",
+                  "must_match_shape",
+                  "custom"
+                ],
+                "default": "ignore"
+              }
+            }
+          },
+          "description": "按牌型的比较键设定"
+        },
+        "suit_order": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Suit"
+          },
+          "description": "花色序（用于平手裁决）"
+        },
+        "override_matrix": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "overrider",
+              "overrides"
+            ],
+            "properties": {
+              "overrider": {
+                "type": "string",
+                "description": "覆盖者（如 dragon_card）"
+              },
+              "overrides": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "被覆盖牌型，支持 \"*\""
+              },
+              "priority": {
+                "type": "integer",
+                "description": "覆盖优先级"
+              }
+            }
+          },
+          "description": "【v0.93】牌型/特殊牌对其它牌型的覆盖矩阵"
+        }
+      }
+    },
+    "actions": {
+      "type": "object",
+      "required": [
+        "play",
+        "pass"
+      ],
+      "additionalProperties": false,
+      "description": "动作定义（均归约为 Transfer）",
+      "properties": {
+        "play": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "transfer_path"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "type": {
+                "$ref": "#/$defs/ComboType"
+              },
+              "len": {
+                "type": "integer"
+              },
+              "core": {
+                "type": "array",
+                "items": { "$ref": "#/$defs/Rank" },
+                "description": "核心序列，如 [7,8,9,10,11]"
+              },
+              "wings": {
+                "type": "string",
+                "enum": [
+                  "single",
+                  "pair",
+                  "none"
+                ]
+              },
+              "wild_usage": {
+                "type": "string",
+                "enum": ["limited", "full", "none"]
+              },
+              "transfer_path": {
+                "$ref": "#/$defs/Transfer"
+              },
+              "visibility_change": {
+                "$ref": "#/$defs/VisibilityChange"
+              },
+
+              "raw_definition": {
+                "type": "object",
+                "description": "当标准字段无法精确表示 GDL 中的 play 动作时，存储其原始定义。"
+              }
+            }
+          },
+          "description": "出牌动作列表"
+        },
+        "pass": {
+          "type": "object",
+          "required": [
+            "transfer_path"
+          ],
+          "additionalProperties": false,
+          "description": "过牌（显式 no-op：field→field）",
+          "properties": {
+            "transfer_path": {
+              "type": "object",
+              "required": [
+                "from",
+                "to"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "from": {
+                  "const": "field"
+                },
+                "to": {
+                  "const": "field"
+                }
+              }
+            }
+          }
+        },
+        "reveal_bottom": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Transfer"
+          },
+          "description": "翻底"
+        },
+        "cleanup_trick": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Transfer"
+          },
+          "description": "清台/收墩"
+        },
+        "other": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/Transfer"
+            }
+          },
+          "description": "自定义动作名称 → Transfer 序列"
+        }
+      }
+    },
+    "phases": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "setup",
+          "deal",
+          "bid",
+          "double",
+          "initiative",
+          "play",
+          "settle",
+          "grouping"
+        ]
+      },
+      "uniqueItems": true,
+      "description": "阶段流转"
+    },
+    "turns": {
+      "type": "object",
+      "required": [
+        "order",
+        "trick_end_on",
+        "next_leader"
+      ],
+      "additionalProperties": false,
+      "description": "轮转/收墩",
+      "properties": {
+        "order": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/PID"
+          },
+          "minItems": 2,
+          "description": "回合顺序"
+        },
+        "leader": {
+          "$ref": "#/$defs/PID",
+          "description": "首个出牌者"
+        },
+        "trick_end_on": {
+          "type": "string",
+          "enum": [
+            "two_pass",
+            "all_pass_except_last",
+            "custom"
+          ],
+          "description": "一墩结束条件"
+        },
+        "next_leader": {
+          "type": "string",
+          "enum": [
+            "last_non_pass",
+            "winner",
+            "fixed",
+            "custom"
+          ],
+          "description": "下一轮领出者"
+        }
+      }
+    },
+    "ending": {
+      "type": "object",
+      "required": [
+        "when"
+      ],
+      "additionalProperties": false,
+      "description": "终局条件",
+      "properties": {
+        "when": {
+          "type": "string",
+          "enum": [
+            "any_hand_empty",
+            "stock_empty",
+            "rounds_exhausted",
+            "custom"
+          ]
+        }
+      }
+    },
+    "scoring": {
+      "type": "object",
+      "required": [
+        "base"
+      ],
+      "additionalProperties": false,
+      "description": "基础计分与倍率封顶",
+      "properties": {
+        "base": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 1
+        },
+        "multipliers": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "number"
+          },
+          "description": "事件→倍率 映射"
+        },
+        "cap": {
+          "type": "integer",
+          "description": "总封顶（简单场景）"
+        },
+        "spring_rule": {
+          "type": "string",
+          "enum": [
+            "strict",
+            "lenient",
+            "none"
+          ],
+          "default": "none",
+          "description": "春天/反春判定"
+        },
+        "expression": {
+          "type": "string",
+          "description": "可选：S-表达式形式的最终公式（实现自定）"
+        },
+        "capping": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "【v0.93】更细粒度封顶",
+          "properties": {
+            "winner_max_gain": {
+              "oneOf": [
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "string"
+                }
+              ]
+            },
+            "loser_max_loss": {
+              "oneOf": [
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "string"
+                }
+              ]
+            }
+          }
+        }
+      }
+    },
+    "initiative": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "先手机制",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": [
+            "spade3",
+            "random",
+            "max_card",
+            "min_card",
+            "custom"
+          ]
+        },
+        "params": {
+          "type": "object"
+        },
+        "deterministic": {
+          "type": "boolean",
+          "default": true
+        }
+      }
+    },
+    "setup_ex": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "扩展设置",
+      "properties": {
+        "special_dealing": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "chain_bomb_distribution": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "default": false
+                },
+                "counts": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "number"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "landlord_card_selection": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "地主底牌分配",
+          "properties": {
+            "timing": {
+              "type": "string",
+              "enum": [
+                "after_bomb_distribution",
+                "default",
+                "custom"
+              ],
+              "default": "default"
+            },
+            "method": {
+              "type": "string",
+              "enum": [
+                "strategic",
+                "random",
+                "custom"
+              ],
+              "default": "random"
+            },
+            "selection_process": {
+              "type": "string"
+            },
+            "criteria": {
+              "type": "object",
+              "properties": {
+                "can_form_bomb": { "type": "boolean" },
+                "can_form_triple": { "type": "boolean" },
+                "value_threshold": { "type": "string", "enum": ["high", "medium", "low"] }
+              }
+            },
+            "fallback_method": {
+              "type": "string",
+              "enum": ["last_n_cards", "random"]
+            },
+            "fallback_count": { "type": "integer" },
+            "distribution_pattern": { "type": "string" }
+          }
+        },
+        "grouping": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "【v0.93】分组设定",
+          "properties": {
+            "mode": {
+              "type": "string"
+            },
+            "groups": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "assign_rules": {
+              "type": "object"
+            },
+            "deal_bias": {
+              "type": "object"
+            },
+            "bonuses": {
+              "type": "object"
+            }
+          }
+        },
+        "replenishment_rules": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "cards_per_player_per_round": { "type": "integer", "minimum": 0 },
+            "source": { "$ref": "#/$defs/ZoneID" },
+            "termination_condition": { "type": "string" },
+            "special_cases": {
+              "type": "object",
+              "properties": {
+                "if_remaining_cards_less_than_n": { "type": "string" },
+                "if_player_cannot_take_all": { "type": "string" }
+              }
+            },
+            "excess_card_handling": { "type": "string" }
+          }
+        },
+        "guessing_rules": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "max_extra_cards": { "type": "integer", "minimum": 0 },
+            "success_reward_multiplier": { "type": "string" },
+            "success_reward_multiplier_for_only_extra": { "type": "string" },
+            "failure_penalty": { "type": "string" },
+            "failure_consequence": { "type": "string" },
+            "farmer_failure_continues_to_landlord": { "type": "boolean" },
+            "source": { "$ref": "#/$defs/ZoneID" }
+          }
+        }
+      }
+    },
+    "information_model": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "信息模型（观战、日志、窥视）",
+      "properties": {
+        "spectator_view": {
+          "type": "string",
+          "enum": [
+            "none",
+            "public",
+            "delayed"
+          ],
+          "default": "none"
+        },
+        "logs": {
+          "type": "string",
+          "enum": [
+            "redacted",
+            "full"
+          ],
+          "default": "redacted"
+        },
+        "peek_actions": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": false
+            },
+            "who": {
+              "type": "string"
+            },
+            "scope": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/ZoneID"
+              }
+            },
+            "limits": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "per_round": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "per_game": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+
+    "special_mechanics": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/Mechanic"
+      },
+      "description": "特殊机制定义，对应 GDL 中 special_mechanics 的通用 mechanic 模板。支持 raw_definition 以应对无法精确映射的情况。"
+    },
+    "illegal_action": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "非法动作策略",
+      "properties": {
+        "policy": {
+          "type": "string",
+          "enum": [
+            "skip_turn",
+            "forfeit",
+            "warn"
+          ],
+          "default": "warn"
+        },
+        "penalty": {
+          "type": "string"
+        }
+      }
+    },
+    "grouping_phase": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "分组阶段（对局内）",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "ace_grouping",
+            "custom"
+          ],
+          "default": "custom"
+        },
+        "dynamic_teams": {
+          "type": "boolean",
+          "default": false
+        },
+        "first_turn": {
+          "type": "string"
+        }
+      }
+    },
+    "rank_position_rules": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "顺子/连对的点数位置限制",
+      "properties": {
+        "A": {
+          "type": "string",
+          "enum": [
+            "first_last_second_last",
+            "anywhere"
+          ],
+          "default": "anywhere"
+        },
+        "2": {
+          "type": "string",
+          "enum": [
+            "first_second_first_last",
+            "anywhere"
+          ],
+          "default": "anywhere"
+        }
+      }
+    },
+    "scoring_ex": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "计分表达式与顺序",
+      "properties": {
+        "expr": {
+          "type": "object",
+          "description": "AST风格表达式",
+          "properties": {
+            "type": {
+              "type": "string"
+            },
+            "args": {
+              "type": "array",
+              "items": {
+                "$ref": "#/properties/scoring_ex/properties/expr"
+              }
+            },
+            "var": {
+              "type": "string"
+            }
+          }
+        },
+        "order_of_application": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "override_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "覆盖策略（谁覆盖谁）",
+      "properties": {
+        "turn_order": {
+          "type": "string",
+          "enum": [
+            "playing_phase_overrides_global",
+            "inherit"
+          ],
+          "default": "inherit"
+        },
+        "deal_method": {
+          "type": "string",
+          "enum": [
+            "setup_overrides_deck",
+            "inherit"
+          ],
+          "default": "inherit"
+        },
+        "unspecified": {
+          "type": "string",
+          "enum": [
+            "inherits",
+            "error"
+          ],
+          "default": "inherits"
+        },
+        "on_conflict": {
+          "type": "string",
+          "enum": [
+            "error",
+            "last_wins"
+          ],
+          "default": "error"
+        }
+      }
+    },
+    "history_deck": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "历史牌堆（记牌/回放）",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0
+        },
+        "replacement_policy": {
+          "type": "string",
+          "enum": [
+            "fifo",
+            "lru",
+            "none"
+          ],
+          "default": "fifo"
+        },
+        "max_size": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0
+        }
+      }
+    },
+    "bidding_model": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "【v0.93】竞价流程模型",
+      "properties": {
+        "mode": {
+          "type": "string"
+        },
+        "options": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "order": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/PID"
+          }
+        },
+        "multiplier_effect": {
+          "type": "object"
+        }
+      }
+    },
+    "doubling_model": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "【v0.93】加倍流程模型",
+      "properties": {
+        "options": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "scope": {
+          "type": "string",
+          "enum": [
+            "personal",
+            "team",
+            "global",
+            "custom"
+          ]
+        },
+        "stack_rule": {
+          "type": "string"
+        }
+      }
+    },
+
+    "extensions": {
+      "type": "object",
+      "description": "用于容纳当前 Schema 无法表示的 GDL 特性或未来扩展。实现时应谨慎处理其中的内容。",
+      "additionalProperties": true
+    }
+  }
+}

poker_gdl_ir.schema.v0.96.zh.json

@@ -0,0 +1,1746 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema  ",
+  "$id": "https://example.org/schemas/poker_gdl_ir.schema.v0.96.zh.json",
+  "title": "Poker-GDL IR Schema v0.96（含中文注释）",
+  "description": "扑克类（牌型压制类）玩法的 GDL → IR 标准。v0.95 优化：采用策略一，引入 raw_definition 和 extensions 字段以增强 Schema 扩展性。",
+  "type": "object",
+  "required": [
+    "meta",
+    "players",
+    "cards",
+    "zones",
+    "visibility",
+    "combinations",
+    "comparison",
+    "actions",
+    "phases",
+    "turns",
+    "ending",
+    "scoring"
+  ],
+  "additionalProperties": false,
+  "$defs": {
+    "PID": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_:-]+$",
+      "description": "玩家/角色标识，如 L、P1、P2"
+    },
+    "ZoneID": {
+      "type": "string",
+      "pattern": "^(hand:[A-Za-z0-9_:-]+|field|main_deck|discard_pile|reserve_zone|public_pool|item_deck:[A-Za-z0-9_:-]+|history_deck)$",
+      "description": "区域标识；手牌需带所属者，如 hand:L；道具牌库需带名称，如 item_deck:BulletCards"
+    },
+    "Audience": {
+      "type": "string",
+      "enum": [
+        "owner",
+        "teammates",
+        "enemies",
+        "all",
+        "none"
+      ],
+      "description": "可见性受众"
+    },
+    "VisibilityState": {
+      "type": "string",
+      "enum": [
+        "visible",
+        "hidden",
+        "partial_suit",
+        "partial_rank"
+      ],
+      "description": "可见性枚举"
+    },
+    "Rank": {
+      "type": "integer",
+      "description": "推荐映射：3..15=3..A, 16=小王, 17=大王"
+    },
+    "Suit": {
+      "type": "string",
+      "enum": [
+        "Spade",
+        "Heart",
+        "Club",
+        "Diamond"
+      ],
+      "description": "花色，如 S/H/D/C (现在使用GDL中的标准名称)"
+    },
+    "ComboType": {
+      "type": "string",
+      "enum": [
+        "single",
+        "pair",
+        "triple",
+        "straight",
+        "pairs_chain",
+        "airplane",
+        "triple_with_single",
+        "triple_with_pair",
+        "four_with_twoSingles",
+        "four_with_twoPairs",
+        "bomb",
+        "rocket",
+        "double_chain_bomb",
+        "triple_chain_bomb",
+        "quad_chain_bomb",
+        "penta_chain_bomb",
+        "chain_triple",
+        "custom"
+      ],
+      "description": "牌型名"
+    },
+    "Transfer": {
+      "type": "object",
+      "required": [
+        "from",
+        "to"
+      ],
+      "additionalProperties": false,
+      "description": "原子转移：从某区域移动若干牌到另一区域；所有动作最终都可分解为 Transfer 序列。",
+      "properties": {
+        "from": {
+          "$ref": "#/$defs/ZoneID"
+        },
+        "to": {
+          "$ref": "#/$defs/ZoneID"
+        },
+        "count": {
+          "oneOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "const": "all"
+            }
+          ],
+          "description": "移动数量；all 表示全部"
+        },
+        "filter": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "筛选器：按点数/花色/标签选择牌",
+          "properties": {
+            "ranks": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/Rank"
+              }
+            },
+            "suits": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/Suit"
+              }
+            },
+            "tags": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "VisibilityChange": {
+      "type": "object",
+      "required": [
+        "to",
+        "state"
+      ],
+      "additionalProperties": false,
+      "description": "动作引发的可见性变更",
+      "properties": {
+        "to": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Audience"
+          }
+        },
+        "state": {
+          "$ref": "#/$defs/VisibilityState"
+        },
+        "on_target": {
+          "type": "boolean",
+          "default": true
+        }
+      }
+    },
+    "Mechanic": {
+      "type": "object",
+      "required": [
+        "name",
+        "enabled",
+        "phase",
+        "timing",
+        "trigger_condition"
+      ],
+      "additionalProperties": false,
+      "description": "特殊机制的通用结构，对应 GDL 中 special_mechanics 的 mechanic 模板。支持 raw_definition 以应对无法精确映射的情况。",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "机制名称"
+        },
+        "enabled": {
+          "type": "boolean",
+          "description": "是否启用"
+        },
+        "description": {
+          "type": "string",
+          "description": "机制描述"
+        },
+        "phase": {
+          "type": "string",
+          "enum": [
+            "setup",
+            "bidding",
+            "doubling",
+            "initiative",
+            "playing",
+            "settlement",
+            "grouping"
+          ],
+          "description": "所属阶段"
+        },
+        "timing": {
+          "type": "string",
+          "enum": [
+            "pre_action",
+            "post_action",
+            "during_action"
+          ],
+          "description": "触发时机"
+        },
+        "trigger_condition": {
+          "type": "string",
+          "description": "触发条件表达式"
+        },
+        "usage_limit": {
+          "type": "string",
+          "description": "使用次数限制，如 'once_per_game', 'once_per_round', 'N_times'"
+        },
+        "min_players": {
+          "type": "integer",
+          "minimum": 2,
+          "description": "最小玩家数"
+        },
+        "max_players": {
+          "type": "integer",
+          "minimum": 2,
+          "description": "最大玩家数"
+        },
+        "required_conditions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "前置条件列表"
+        },
+        "effect_description": {
+          "type": "string",
+          "description": "效果描述"
+        },
+        "transfer_path": {
+          "$ref": "#/$defs/Transfer"
+        },
+        "visibility_change": {
+          "$ref": "#/$defs/VisibilityChange"
+        },
+        "raw_definition": {
+          "type": "object",
+          "description": "当标准字段无法精确表示 GDL 中的 mechanic 时，存储其原始定义。"
+        }
+      }
+    },
+    "turns_mutations": {
+      "type": "object",
+      "description": "回合顺序变更：反转、跳过或改定庄",
+      "properties": {
+        "reverse": {
+          "type": "boolean",
+          "description": "是否反转出牌顺序"
+        },
+        "skip_next": {
+          "type": "boolean",
+          "description": "是否跳过下一位"
+        },
+        "set_leader": {
+          "oneOf": [
+            {
+              "type": "string",
+              "enum": [
+                "winner",
+                "last_non_pass"
+              ],
+              "description": "根据结果设置下一墩先手"
+            },
+            {
+              "type": "string",
+              "pattern": "^fixed:P\\d+$",
+              "description": "固定设置先手为某 PID，如 fixed:P1"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "properties": {
+    "meta": {
+      "type": "object",
+      "required": [
+        "name",
+        "version"
+      ],
+      "additionalProperties": false,
+      "description": "玩法元信息",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        },
+        "origin": {
+          "type": "string",
+          "enum": [
+            "Traditional",
+            "Variant",
+            "Innovative"
+          ],
+          "default": "Variant"
+        },
+        "seeded": {
+          "type": "boolean",
+          "default": true
+        },
+        "description": {
+          "type": "string"
+        }
+      }
+    },
+    "players": {
+      "type": "object",
+      "required": [
+        "count"
+      ],
+      "additionalProperties": false,
+      "description": "玩家配置",
+      "properties": {
+        "count": {
+          "type": "integer",
+          "minimum": 2,
+          "maximum": 6
+        },
+        "roles": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "count"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "count": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "players": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/PID"
+                },
+                "description": "属于此角色的具体玩家ID列表，例如 ['Landlord', 'Peasant_1', 'Peasant_2']。此字段为可选扩展。"
+              },
+              "team": {
+                "type": "string"
+              },
+              "special_ability": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "teams": {
+          "type": "array",
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/PID"
+            }
+          }
+        }
+      }
+    },
+    "cards": {
+      "type": "object",
+      "required": [
+        "ranks",
+        "suits"
+      ],
+      "additionalProperties": false,
+      "description": "牌组配置",
+      "properties": {
+        "ranks": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Rank"
+          },
+          "minItems": 1,
+          "description": "点数列表"
+        },
+        "suits": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Suit"
+          },
+          "description": "花色列表"
+        },
+        "jokers": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "大小王点数映射",
+          "properties": {
+            "small": {
+              "$ref": "#/$defs/Rank"
+            },
+            "big": {
+              "$ref": "#/$defs/Rank"
+            }
+          }
+        },
+        "copies_per_deck": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 1,
+          "description": "每副牌的复制份数"
+        },
+        "num_decks": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 1,
+          "description": "使用副数"
+        },
+        "straight_exclude": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Rank"
+          },
+          "description": "顺子禁入点数，如 2/王"
+        },
+        "per_rank_copies": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "description": "【v0.93】按点数单独指定张数，如 {\"16\":1,\"17\":1,\"18\":1}"
+        },
+        "suitless_ranks": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Rank"
+          },
+          "description": "【v0.93】无花色点数（王、龙等不随花色展开）"
+        }
+      }
+    },
+    "zones": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/ZoneID"
+      },
+      "minItems": 1,
+      "uniqueItems": true,
+      "description": "区域列表：hand:*, field, main_deck, discard_pile, reserve_zone, public_pool, item_deck:*, history_deck ..."
+    },
+    "visibility": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "区域可见性设定",
+      "properties": {
+        "defaults": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/$defs/VisibilityState"
+          },
+          "description": "全局默认"
+        },
+        "by_zone": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "state": {
+                "$ref": "#/$defs/VisibilityState"
+              },
+              "audience": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/Audience"
+                }
+              }
+            }
+          },
+          "description": "按区覆盖"
+        }
+      }
+    },
+    "invariants": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "不变量约束",
+      "properties": {
+        "physical_conservation": {
+          "type": "boolean",
+          "default": true,
+          "description": "物理守恒：总牌数不变"
+        },
+        "no_card_from_void": {
+          "type": "boolean",
+          "default": true,
+          "description": "禁止无源牌"
+        },
+        "max_hand_size": {
+          "type": "integer"
+        },
+        "max_public_pool": {
+          "type": "integer"
+        },
+        "same_rank_max": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "sequence_span_max": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "team_membership_consistent": {
+          "type": "boolean",
+          "default": true
+        },
+        "all_transfers_use_defined_zones": {
+          "type": "boolean",
+          "default": true
+        },
+        "no_card_appears_in_undefined_zone": {
+          "type": "boolean",
+          "default": true
+        }
+      }
+    },
+    "card_relations": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "牌值与关系定义",
+      "properties": {
+        "card_values": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Rank"
+          },
+          "description": "牌值大小顺序，从低到高"
+        },
+        "used_in": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "指定使用位置"
+        },
+        "continuous_relations": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "sequence": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/Rank"
+                }
+              },
+              "used_in": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "description": "连续关系定义"
+        },
+        "non_continuous_cards": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Rank"
+          },
+          "description": "非连续牌"
+        },
+        "same_value_relation": {
+          "type": "string",
+          "enum": [
+            "same_number",
+            "same_suit"
+          ],
+          "default": "same_number"
+        },
+        "ace_position": {
+          "type": "string",
+          "enum": [
+            "first_last_second_last",
+            "anywhere"
+          ],
+          "default": "anywhere"
+        },
+        "two_position": {
+          "type": "string",
+          "enum": [
+            "first_second_first_last",
+            "anywhere"
+          ],
+          "default": "anywhere"
+        },
+        "suit_relations": {
+          "type": "object",
+          "properties": {
+            "order": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/Suit"
+              }
+            },
+            "used_in": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "joker_rules": {
+          "type": "object",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": [
+                "off",
+                "wild_only",
+                "power_only",
+                "wild_and_power"
+              ],
+              "default": "off"
+            },
+            "exclusivity": {
+              "type": "string",
+              "enum": [
+                "exclusive",
+                "hybrid"
+              ]
+            },
+            "wildcard_scope": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/ComboType"
+              },
+              "description": "赖子作用域"
+            },
+            "wildcard_loses_rank": {
+              "type": "boolean",
+              "default": false,
+              "description": "赖子是否失去单牌牌力"
+            },
+            "power_single": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                },
+                "beats": {
+                  "type": "string",
+                  "enum": [
+                    "all_singles",
+                    "rank_list"
+                  ]
+                },
+                "rank_list": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              }
+            },
+            "power_pair": {
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "type": "boolean"
+                },
+                "beats": {
+                  "type": "string",
+                  "enum": [
+                    "all_pairs",
+                    "rank_list"
+                  ]
+                },
+                "rank_list": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "unique_cards": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "唯一牌列表，如 Spade3"
+        }
+      }
+    },
+    "combinations": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "牌型族定义",
+      "properties": {
+        "single": {
+          "type": "object"
+        },
+        "pair": {
+          "type": "object"
+        },
+        "triple": {
+          "type": "object"
+        },
+        "straight": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "min_len": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "no_ranks": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/Rank"
+              }
+            }
+          },
+          "description": "顺子"
+        },
+        "pairs_chain": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "min_len": {
+              "type": "integer",
+              "minimum": 1
+            }
+          },
+          "description": "连对"
+        },
+        "airplane": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "min_len": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "wings": {
+              "type": "string",
+              "enum": [
+                "single",
+                "pair",
+                "none"
+              ],
+              "default": "none"
+            }
+          },
+          "description": "飞机（可带翅膀）"
+        },
+        "triple_with_single": {
+          "type": "object"
+        },
+        "triple_with_pair": {
+          "type": "object"
+        },
+        "four_with_twoSingles": {
+          "type": "object"
+        },
+        "four_with_twoPairs": {
+          "type": "object"
+        },
+        "bomb": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "len": {
+              "type": "integer",
+              "const": 4
+            }
+          },
+          "description": "四张炸"
+        },
+        "rocket": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "ranks": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/Rank"
+              }
+            }
+          },
+          "description": "王炸"
+        },
+        "custom": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "name"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "spec": {
+                "type": "object"
+              }
+            }
+          },
+          "description": "自定义牌型/特殊牌"
+        }
+      }
+    },
+    "comparison": {
+      "type": "object",
+      "required": [
+        "same_type",
+        "same_len"
+      ],
+      "additionalProperties": false,
+      "description": "比较总则",
+      "properties": {
+        "same_type": {
+          "type": "boolean",
+          "description": "是否强制同型比较"
+        },
+        "same_len": {
+          "type": "boolean",
+          "description": "是否强制相同长度"
+        },
+        "bomb_beats_all": {
+          "type": "boolean",
+          "default": true,
+          "description": "炸弹压制普通牌"
+        },
+        "rocket_top": {
+          "type": "boolean",
+          "default": true,
+          "description": "王炸最大"
+        },
+        "tiebreaker": {
+          "type": "string",
+          "enum": [
+            "suit",
+            "first_played",
+            "none"
+          ],
+          "default": "none",
+          "description": "平手裁决"
+        }
+      }
+    },
+    "comparison_ex": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "精细比较规则",
+      "properties": {
+        "per_combo": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "require_same_length": {
+                "type": "boolean",
+                "default": true
+              },
+              "compare_by": {
+                "type": "string",
+                "enum": [
+                  "sequence_start",
+                  "sequence_end",
+                  "highest_triple_value",
+                  "main_rank",
+                  "length_first_then_rank",
+                  "custom"
+                ],
+                "default": "main_rank"
+              },
+              "side_card_rule": {
+                "type": "string",
+                "enum": [
+                  "ignore",
+                  "must_match_shape",
+                  "custom"
+                ],
+                "default": "ignore"
+              }
+            }
+          },
+          "description": "按牌型的比较键设定"
+        },
+        "suit_order": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Suit"
+          },
+          "description": "花色序（用于平手裁决）"
+        },
+        "override_matrix": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "overrider",
+              "overrides"
+            ],
+            "properties": {
+              "overrider": {
+                "type": "string",
+                "description": "覆盖者（如 dragon_card）"
+              },
+              "overrides": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "被覆盖牌型，支持 \"*\""
+              },
+              "priority": {
+                "type": "integer",
+                "description": "覆盖优先级"
+              }
+            }
+          },
+          "description": "【v0.93】牌型/特殊牌对其它牌型的覆盖矩阵"
+        }
+      }
+    },
+    "actions": {
+      "type": "object",
+      "required": [
+        "play",
+        "pass"
+      ],
+      "additionalProperties": false,
+      "description": "动作定义（均归约为 Transfer）",
+      "properties": {
+        "play": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "transfer_path"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "type": {
+                "$ref": "#/$defs/ComboType"
+              },
+              "len": {
+                "type": "integer"
+              },
+              "core": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/Rank"
+                },
+                "description": "核心序列，如 [7,8,9,10,11]"
+              },
+              "wings": {
+                "type": "string",
+                "enum": [
+                  "single",
+                  "pair",
+                  "none"
+                ]
+              },
+              "wild_usage": {
+                "type": "string",
+                "enum": [
+                  "limited",
+                  "full",
+                  "none"
+                ]
+              },
+              "transfer_path": {
+                "$ref": "#/$defs/Transfer"
+              },
+              "visibility_change": {
+                "$ref": "#/$defs/VisibilityChange"
+              },
+              "raw_definition": {
+                "type": "object",
+                "description": "当标准字段无法精确表示 GDL 中的 play 动作时，存储其原始定义。"
+              }
+            }
+          },
+          "description": "出牌动作列表"
+        },
+        "pass": {
+          "type": "object",
+          "required": [
+            "transfer_path"
+          ],
+          "additionalProperties": false,
+          "description": "过牌（显式 no-op：field→field）",
+          "properties": {
+            "transfer_path": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "required": [
+                    "from",
+                    "to"
+                  ],
+                  "additionalProperties": false,
+                  "properties": {
+                    "from": {
+                      "const": "field"
+                    },
+                    "to": {
+                      "const": "field"
+                    }
+                  }
+                },
+                {
+                  "const": "none"
+                }
+              ]
+            }
+          }
+        },
+        "reveal_bottom": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Transfer"
+          },
+          "description": "翻底"
+        },
+        "cleanup_trick": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Transfer"
+          },
+          "description": "清台/收墩"
+        },
+        "other": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "oneOf": [
+                {
+                  "$ref": "#/$defs/Transfer"
+                },
+                {
+                  "type": "object",
+                  "required": [
+                    "turns_mutations"
+                  ],
+                  "properties": {
+                    "turns_mutations": {
+                      "$ref": "#/$defs/turns_mutations"
+                    }
+                  },
+                  "additionalProperties": false,
+                  "description": "顺序副作用（反转/跳过/改定庄）"
+                }
+              ]
+            }
+          },
+          "description": "自定义动作名称 → Transfer 序列"
+        }
+      }
+    },
+    "phases": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "setup",
+          "deal",
+          "bid",
+          "double",
+          "initiative",
+          "play",
+          "settle",
+          "grouping"
+        ]
+      },
+      "uniqueItems": true,
+      "description": "阶段流转"
+    },
+    "turns": {
+      "type": "object",
+      "required": [
+        "order",
+        "trick_end_on",
+        "next_leader"
+      ],
+      "additionalProperties": false,
+      "description": "轮转/收墩",
+      "properties": {
+        "order": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/PID"
+          },
+          "minItems": 2,
+          "description": "回合顺序"
+        },
+        "leader": {
+          "$ref": "#/$defs/PID",
+          "description": "首个出牌者"
+        },
+        "trick_end_on": {
+          "oneOf": [
+            {
+              "type": "string",
+              "enum": [
+                "two_pass",
+                "all_pass_except_last",
+                "custom"
+              ],
+              "description": "一墩结束条件"
+            },
+            {
+              "type": "object",
+              "title": "passes_n",
+              "required": [
+                "passes_n"
+              ],
+              "properties": {
+                "passes_n": {
+                  "type": "integer",
+                  "minimum": 2,
+                  "maximum": 10,
+                  "description": "连续 PASS 次数达到 N 则结束一墩"
+                }
+              },
+              "additionalProperties": false,
+              "description": "N 连续 PASS 结束一墩"
+            }
+          ]
+        },
+        "next_leader": {
+          "type": "string",
+          "enum": [
+            "last_non_pass",
+            "winner",
+            "fixed",
+            "custom"
+          ],
+          "description": "下一轮领出者"
+        }
+      }
+    },
+    "ending": {
+      "type": "object",
+      "required": [
+        "when"
+      ],
+      "additionalProperties": false,
+      "description": "终局条件",
+      "properties": {
+        "when": {
+          "type": "string",
+          "enum": [
+            "any_hand_empty",
+            "stock_empty",
+            "rounds_exhausted",
+            "custom"
+          ]
+        }
+      }
+    },
+    "scoring": {
+      "type": "object",
+      "required": [
+        "base"
+      ],
+      "additionalProperties": false,
+      "description": "基础计分与倍率封顶",
+      "properties": {
+        "base": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 1
+        },
+        "multipliers": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "number"
+          },
+          "description": "事件→倍率 映射"
+        },
+        "cap": {
+          "type": "integer",
+          "description": "总封顶（简单场景）"
+        },
+        "spring_rule": {
+          "type": "string",
+          "enum": [
+            "strict",
+            "lenient",
+            "none"
+          ],
+          "default": "none",
+          "description": "春天/反春判定"
+        },
+        "expression": {
+          "type": "string",
+          "description": "可选：S-表达式形式的最终公式（实现自定）"
+        },
+        "capping": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "【v0.93】更细粒度封顶",
+          "properties": {
+            "winner_max_gain": {
+              "oneOf": [
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "string"
+                }
+              ]
+            },
+            "loser_max_loss": {
+              "oneOf": [
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "string"
+                }
+              ]
+            }
+          }
+        }
+      }
+    },
+    "initiative": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "先手机制",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": [
+            "spade3",
+            "random",
+            "max_card",
+            "min_card",
+            "custom"
+          ]
+        },
+        "params": {
+          "type": "object"
+        },
+        "deterministic": {
+          "type": "boolean",
+          "default": true
+        }
+      }
+    },
+    "setup_ex": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "扩展设置",
+      "properties": {
+        "special_dealing": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "chain_bomb_distribution": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "enabled": {
+                  "type": "boolean",
+                  "default": false
+                },
+                "counts": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "number"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "landlord_card_selection": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "地主底牌分配",
+          "properties": {
+            "timing": {
+              "type": "string",
+              "enum": [
+                "after_bomb_distribution",
+                "default",
+                "custom"
+              ],
+              "default": "default"
+            },
+            "method": {
+              "type": "string",
+              "enum": [
+                "strategic",
+                "random",
+                "custom"
+              ],
+              "default": "random"
+            },
+            "selection_process": {
+              "type": "string"
+            },
+            "criteria": {
+              "type": "object",
+              "properties": {
+                "can_form_bomb": {
+                  "type": "boolean"
+                },
+                "can_form_triple": {
+                  "type": "boolean"
+                },
+                "value_threshold": {
+                  "type": "string",
+                  "enum": [
+                    "high",
+                    "medium",
+                    "low"
+                  ]
+                }
+              }
+            },
+            "fallback_method": {
+              "type": "string",
+              "enum": [
+                "last_n_cards",
+                "random"
+              ]
+            },
+            "fallback_count": {
+              "type": "integer"
+            },
+            "distribution_pattern": {
+              "type": "string"
+            }
+          }
+        },
+        "grouping": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "【v0.93】分组设定",
+          "properties": {
+            "mode": {
+              "type": "string"
+            },
+            "groups": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "assign_rules": {
+              "type": "object"
+            },
+            "deal_bias": {
+              "type": "object"
+            },
+            "bonuses": {
+              "type": "object"
+            }
+          }
+        },
+        "replenishment_rules": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "cards_per_player_per_round": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "source": {
+              "$ref": "#/$defs/ZoneID"
+            },
+            "termination_condition": {
+              "type": "string"
+            },
+            "special_cases": {
+              "type": "object",
+              "properties": {
+                "if_remaining_cards_less_than_n": {
+                  "type": "string"
+                },
+                "if_player_cannot_take_all": {
+                  "type": "string"
+                }
+              }
+            },
+            "excess_card_handling": {
+              "type": "string"
+            }
+          }
+        },
+        "guessing_rules": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "max_extra_cards": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "success_reward_multiplier": {
+              "type": "string"
+            },
+            "success_reward_multiplier_for_only_extra": {
+              "type": "string"
+            },
+            "failure_penalty": {
+              "type": "string"
+            },
+            "failure_consequence": {
+              "type": "string"
+            },
+            "farmer_failure_continues_to_landlord": {
+              "type": "boolean"
+            },
+            "source": {
+              "$ref": "#/$defs/ZoneID"
+            }
+          }
+        }
+      }
+    },
+    "information_model": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "信息模型（观战、日志、窥视）",
+      "properties": {
+        "spectator_view": {
+          "type": "string",
+          "enum": [
+            "none",
+            "public",
+            "delayed"
+          ],
+          "default": "none"
+        },
+        "logs": {
+          "type": "string",
+          "enum": [
+            "redacted",
+            "full"
+          ],
+          "default": "redacted"
+        },
+        "peek_actions": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": false
+            },
+            "who": {
+              "type": "string"
+            },
+            "scope": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/ZoneID"
+              }
+            },
+            "limits": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "per_round": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "per_game": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "special_mechanics": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/Mechanic"
+      },
+      "description": "特殊机制定义，对应 GDL 中 special_mechanics 的通用 mechanic 模板。支持 raw_definition 以应对无法精确映射的情况。"
+    },
+    "illegal_action": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "非法动作策略",
+      "properties": {
+        "policy": {
+          "type": "string",
+          "enum": [
+            "skip_turn",
+            "forfeit",
+            "warn"
+          ],
+          "default": "warn"
+        },
+        "penalty": {
+          "type": "string"
+        }
+      }
+    },
+    "grouping_phase": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "分组阶段（对局内）",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "ace_grouping",
+            "custom"
+          ],
+          "default": "custom"
+        },
+        "dynamic_teams": {
+          "type": "boolean",
+          "default": false
+        },
+        "first_turn": {
+          "type": "string"
+        }
+      }
+    },
+    "rank_position_rules": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "顺子/连对的点数位置限制",
+      "properties": {
+        "A": {
+          "type": "string",
+          "enum": [
+            "first_last_second_last",
+            "anywhere"
+          ],
+          "default": "anywhere"
+        },
+        "2": {
+          "type": "string",
+          "enum": [
+            "first_second_first_last",
+            "anywhere"
+          ],
+          "default": "anywhere"
+        }
+      }
+    },
+    "scoring_ex": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "计分表达式与顺序",
+      "properties": {
+        "expr": {
+          "type": "object",
+          "description": "AST风格表达式",
+          "properties": {
+            "type": {
+              "type": "string"
+            },
+            "args": {
+              "type": "array",
+              "items": {
+                "$ref": "#/properties/scoring_ex/properties/expr"
+              }
+            },
+            "var": {
+              "type": "string"
+            }
+          }
+        },
+        "order_of_application": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "override_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "覆盖策略（谁覆盖谁）",
+      "properties": {
+        "turn_order": {
+          "type": "string",
+          "enum": [
+            "playing_phase_overrides_global",
+            "inherit"
+          ],
+          "default": "inherit"
+        },
+        "deal_method": {
+          "type": "string",
+          "enum": [
+            "setup_overrides_deck",
+            "inherit"
+          ],
+          "default": "inherit"
+        },
+        "unspecified": {
+          "type": "string",
+          "enum": [
+            "inherits",
+            "error"
+          ],
+          "default": "inherits"
+        },
+        "on_conflict": {
+          "type": "string",
+          "enum": [
+            "error",
+            "last_wins"
+          ],
+          "default": "error"
+        }
+      }
+    },
+    "history_deck": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "历史牌堆（记牌/回放）",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0
+        },
+        "replacement_policy": {
+          "type": "string",
+          "enum": [
+            "fifo",
+            "lru",
+            "none"
+          ],
+          "default": "fifo"
+        },
+        "max_size": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0
+        }
+      }
+    },
+    "bidding_model": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "【v0.93】竞价流程模型",
+      "properties": {
+        "mode": {
+          "type": "string"
+        },
+        "options": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "order": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/PID"
+          }
+        },
+        "multiplier_effect": {
+          "type": "object"
+        }
+      }
+    },
+    "doubling_model": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "【v0.93】加倍流程模型",
+      "properties": {
+        "options": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "scope": {
+          "type": "string",
+          "enum": [
+            "personal",
+            "team",
+            "global",
+            "custom"
+          ]
+        },
+        "stack_rule": {
+          "type": "string"
+        }
+      }
+    },
+    "extensions": {
+      "type": "object",
+      "description": "用于容纳当前 Schema 无法表示的 GDL 特性或未来扩展。实现时应谨慎处理其中的内容。",
+      "additionalProperties": true
+    }
+  }
+}

qixi_gdl.txt

@@ -0,0 +1,388 @@
+(game "奇袭斗地主"
+  (types
+    (DeckType        one_of {"Standard54"})
+    (ShuffleMethod   one_of {"full"})
+    (DealMethod      one_of {"random"})
+    (TurnOrderType   one_of {"circular"})
+    (Visibility      one_of {"face_up" "face_down" "partial"})
+    (ComparisonRule  one_of {"same_type_only"})
+    (TieBreaker      one_of {"suit" "first_played" "none"})
+    (CapType         one_of {"N_times_coin" "fixed_amount" "percentage"})
+    (PlayerSelector  one_of {"with_Spade3"})
+    (InitiativeMode  one_of {"spade3"})
+    (ZoneName        one_of {"hand" "field" "main_deck" "discard_pile" "reserve_zone"})
+    (VisibilityAudience one_of {"owner" "teammates" "enemies" "all" "none"})
+    (TransferPath    (from ZoneName) (to ZoneName))
+  )
+
+  (authoring_constraints
+    (no_range_literals true)
+    (exact_counts_required true)
+    (no_open_ended_modifiers true)
+    (no_vague_terms true)
+    (numeric_values_must_be_exact true)
+    (all_cards_must_have_defined_zones true)
+    (all_actions_must_specify_transfer_path true)
+    (no_card_generation_from_void true)
+  )
+
+  (players 3) ; 固定3人
+
+  (deck "Standard54" ; 使用1副牌，含大小王
+    (shuffling "full") ; 完全洗牌
+    (deal_pattern "random") ; 随机发牌
+  )
+  
+  (roles { (role "Landlord" 1) (role "Peasant" 2) }) ; 1个地主，2个农民
+  
+  (turn_order { "Landlord" "Peasant" "Peasant" }) ; 地主先出，接着是农民
+
+  (override_policy
+    (turn_order precedence: playing_phase_overrides_global)
+    (deal_method precedence: setup_overrides_deck)
+    (unspecified inherits parent)
+    (on_conflict "error"))
+
+  (setup
+    (bidding true) ; 存在叫分环节
+    (deal 17) ; 每位玩家在初始发牌时获得17张牌
+    (reserve 3) ; 留作"底牌"的牌数
+    (reserve_cards "face_down") ; 底牌暗牌
+    (deal_method "random") ; 随机发牌
+    
+    (initial_score 0) ; 初始积分为0
+    (initial_multiplier 1) ; 初始倍率为1
+    
+    (zones
+      (hand
+        (default_visibility owner)
+        (initial_cards 0))
+      (field
+        (default_visibility all)
+        (initial_cards 0))
+      (discard_pile
+        (default_visibility all)
+        (initial_cards 0))
+      (main_deck
+        (default_visibility hidden)
+        (source "Standard54")
+        (initial_cards 54))
+      (reserve_zone
+        (default_visibility face_down)
+        (initial_cards 3))
+    )
+
+    (card_relations 
+      (card_values 3 4 5 6 7 8 9 10 J Q K A 2) ; 牌值大小顺序，从低到高
+      (used_in { "single_card" "pair" "triple" "bomb" }) ; 用于单牌、对子、三张、炸弹比较
+      (continuous_relations ; 连续关系定义
+        (Straight_3_to_10 3 4 5 6 7 8 9 10) ; 3到10连续
+        (Straight_10_to_A 10 J Q K A) ; 10到A连续
+        (Straight_A_to_5 A 5 6 7 8) ; A到5连续（特殊顺子）
+        (used_in { "straight" "double_straight" "triple_chain" "airplane" }) ; 用于顺子、连对、连三、飞机
+      )
+      (non_continuous_cards { 2 } (used_in { "exceptions_in_straight_rules" })) ; 2不参与连续关系
+      (suit_relations 
+        (order "Spade" "Heart" "Club" "Diamond") ; 花色大小顺序
+        (used_in { "tie_breaker" "spade3_first" }) ; 用于平局和黑桃3先出
+      )
+      (same_value_relation 
+        (type "same_number") ; 同点数
+        (used_in { "pair" "triple" "bomb" }) ; 用于对子、三张、炸弹
+    )
+  )
+
+  (information_model
+    (logs redacted)
+    (spectator_view none)
+    (peek_actions
+      (enabled false)
+      (who "role")
+      (cost "expr?")
+      (scope "hand")
+      (limits (per_round 0) (per_game 0)))
+  )
+
+  (randomness
+    (seed 42)
+    (sampling "uniform")
+    (deck_shuffle "full"))
+
+  (resource_bounds
+    (same_rank_max 4)
+    (sequence_span_max 12)
+    (wildcard_policy none)
+    (notes "无"))
+
+  (invariants
+    (= (+ (zone hand) (zone field) (zone discard_pile) (zone main_deck) (zone reserve_zone)) TotalCards)
+    (>= (zone main_deck) 0)
+    (>= (zone hand) 0) (>= (zone field) 0) (>= (zone discard_pile) 0)
+    (all_transfers_use_defined_zones true)
+    (no_card_appears_in_undefined_zone true)
+    (visibility_audience_validity true)
+    (no_unauthorized_peeking true)
+    (team_membership_consistent true)
+    (card_uniqueness (for {"Spade3"}))
+    (authoring_sanity (no_range_literals true) (exact_counts_required true))
+    (initiative_phase_defined true)
+    (initiative_phase_has_valid_mode true)
+    (initiative_phase_has_deterministic_outcome true)
+    (all_defined_relations_are_used true)
+    (no_unused_card_relations true)
+    (no_undefined_relations_used true)
+    (all_mechanisms_have_phase true)
+    (all_mechanisms_have_trigger_condition true)
+  )
+
+  (combinations
+    (single) ; 单牌
+    (pair) ; 对子
+    (triple) ; 三张
+    (straight 5) ; 顺子，至少5张
+    (double_straight 3) ; 连对，至少3对
+    (triple_with_single) ; 三带一
+    (triple_with_pair) ; 三带二
+    (airplane 2) ; 飞机，至少2个连续三张
+    (airplane_with_single 2) ; 飞机带单
+    (airplane_with_pair 2) ; 飞机带对
+    (bomb 4) ; 炸弹，4张同点
+    (bomb_with_single 1) ; 炸弹带单
+    (bomb_with_pair 1) ; 炸弹带对
+    (rocket) ; 王炸
+  )
+
+  (actions
+    (pass
+      (transfer_path none)
+      (visibility_change none))
+    (play (type one_of {single pair triple straight double_straight
+                        triple_with_single triple_with_pair
+                        airplane airplane_with_single airplane_with_pair
+                        bomb bomb_with_single bomb_with_pair rocket})
+          (len int?)
+          (core sequence?)
+          (wings int?)
+          (transfer_path from: hand to: field)
+          (visibility_change
+            (to {owner teammates enemies})
+            (state "visible")
+            (on_target true)))
+    (special (name "援手") 
+             (params { "TargetPlayer" })
+             (transfer_path from: hand to: field)
+             (visibility_change
+               (to {all})
+               (state "visible")
+               (on_target true)))
+    (special (name "换位") 
+             (params { "NewRole" })
+             (transfer_path from: hand to: field)
+             (visibility_change
+               (to {all})
+               (state "visible")
+               (on_target true)))
+  )
+
+  (illegal_action (policy "skip_turn") (penalty "0"))
+
+  (play_rules
+    (comparison_rule "same_type_only")
+    (bomb_power "override")
+    (rocket_power "highest")
+    (bomb_multiplier "doubling")
+    (comparison_basis "highest_card")
+    (trick_ending_rule "move_field_to_discard")
+  )
+
+  (comparison_rules
+    (single_card
+      (compare_by "card_value")
+      (source_relation "card_values")
+      (require_same_length false)
+      (tie_breaker "suit")
+    )
+    (pair
+      (compare_by "card_value")
+      (source_relation "card_values")
+      (require_same_length false)
+    )
+    (triple
+      (compare_by "card_value")
+      (source_relation "card_values")
+      (require_same_length false)
+    )
+    (straight
+      (require_same_length true)
+      (compare_by "highest_card_value")
+      (source_relation "continuous_relations")
+    )
+    (double_straight
+      (require_same_length true)
+      (compare_by "highest_pair_value")
+    )
+    (triple_with_single
+      (compare_by "triple_card_value")
+      (side_card_rule "ignore")
+    )
+    (triple_with_pair
+      (compare_by "triple_card_value")
+      (side_card_rule "ignore")
+    )
+    (airplane
+      (require_same_length true)
+      (compare_by "highest_triple_value")
+    )
+    (airplane_with_single
+      (require_same_length true)
+      (compare_by "highest_triple_value")
+      (side_card_rule "ignore")
+    )
+    (airplane_with_pair
+      (require_same_length true)
+      (compare_by "highest_triple_value")
+      (side_card_rule "ignore")
+    )
+    (bomb
+      (compare_by "card_value")
+      (require_same_length false)
+    )
+    (bomb_with_single
+      (compare_by "bomb_card_value")
+      (side_card_rule "ignore")
+    )
+    (bomb_with_pair
+      (compare_by "bomb_card_value")
+      (side_card_rule "ignore")
+    )
+    (rocket
+      (compare_by "highest")
+      (override_types { "all" })
+    )
+  )
+
+  (phases
+    (bidding_phase
+      (initial_player "with_Spade3")
+      (decision_order "sequential")
+      (decision_options { "pass" "1" "2" "3" })
+      (rules
+        (single_option_wins "immediate")
+        (multiple_options
+          (first_has_extra_choice true)
+          (on_first_option
+            (first_player_wins "immediate")
+            (last_player_wins "immediate")
+          )
+          (multiplier_on_each_option "doubling")
+        )
+        (special_rules
+          (霸王叫
+            (condition "has_chain_bomb_or_higher")
+            (effect
+              (immediate_landlord true)
+              (multiplier_increase 2)
+            )
+          )
+        )
+      )
+      (outcome
+        (assign_role "Landlord" to_winner)
+        (give_reserve_cards to "Landlord")
+        (special_effect "landlord_see_reserve_cards")
+        (landlord_privilege "view_reserve_cards")
+      )
+    )
+
+    (playing_phase
+      (first_player "with_Spade3")
+      (turn_order "circular")
+      (actions_ref actions)
+      (rules
+        (must_follow_suit_or_pass "same_type_only")
+        (bomb_increases_multiplier "doubling")
+        (chain_bomb_increases_multiplier "doubling")
+        (consecutive_pass_ends_trick 2)
+        (next_trick_starts_with_last_player true)
+        (last_hand_restrictions
+          (triple_with_single true)
+          (triple_with_two true)
+        )
+        (ace_placement_restriction true)
+        (two_placement_restriction true)
+        (replenish_cards_enabled false)
+        (active_mechanics { "援手" "换位" })
+        (mechanic_conditions
+          ("援手" "current_player.role == 'Peasant' and hand.size >= 1")
+          ("换位" "current_player.role == 'Landlord' and hand.size >= 2 or current_player.role == 'Peasant' and hand.size >= 2"))
+      )
+    )
+
+    (settlement_phase
+      (trigger_condition "first_to_empty_hand")
+      (win_condition
+        (team_with_empty_hand "wins")
+        (last_player_standing "loses")
+      )
+      (scoring
+        (winner_reward "base_mult * bombs * chains * landlord_bonus")
+        (loser_penalty "base_mult * bombs * chains * landlord_bonus")
+        (total_multiplier_calculation "base_mult * bombs * chains * landlord_bonus")
+      )
+      (capping
+        (winner_max_gain "N_times_coin")
+        (loser_max_loss "fixed_amount")
+      )
+    )
+
+    (initiative_phase
+      (mode "spade3")
+      (details
+        (spade3 (unique_card "Spade3") (must_include false)))
+      (constraints
+        (executed_after "deal")
+        (unique_card_required true)
+        (deterministic true)
+        (specified_first_player true))
+    )
+  )
+
+  (special_mechanics
+    (mechanic "援手"
+      (enabled true)
+      (description "当前农民玩家可以将牌权移交给另一名农民")
+      (phase "playing_phase")
+      (timing "pre_action")
+      (trigger_condition "current_player.role == 'Peasant' and hand.size >= 1")
+      (usage_limit "once_per_round")
+      (min_players 3)
+      (max_players 3)
+      (required_conditions { "opponent_has_at_least_1_card" })
+      (effect_description "当前农民玩家可以选择将牌权移交给另一名农民")
+      (transfer_path from: hand to: field)
+      (visibility_change to: {all} on_target: true))
+    (mechanic "换位"
+      (enabled true)
+      (description "当双方都选择过牌时，可以通过消耗特定牌型进行换位")
+      (phase "playing_phase")
+      (timing "post_action")
+      (trigger_condition "both_players_passed_and_has_required_cards")
+      (usage_limit "once_per_game")
+      (min_players 3)
+      (max_players 3)
+      (required_conditions { "opponent_has_at_least_1_card" })
+      (effect_description "当前玩家可以选择与对手进行换位，交换角色和手牌")
+      (transfer_path from: hand to: opponent_hand)
+      (visibility_change to: {all} on_target: true)))
+
+  (metadata
+    (author "AI")
+    (origin "Innovative")
+    (description "在传统斗地主基础上加入了【援手】和【换位】两个新机制，增加了农民间的协作和角色变换的可能性")
+    (strategy_depth 4)
+    (randomness_factor 0.3)
+    (game_duration "medium")
+    (player_interaction "hybrid")
+    (complexity_level 3)
+  )
+))

requirements.txt

@@ -0,0 +1,3 @@
+jsonschema==4.23.0
+gradio==4.44.0
+uvicorn==0.30.6

uno_gdl.txt

@@ -0,0 +1,116 @@
+(game "斗地UNO"
+  ;; 基础配置
+  (players 4)
+  (deck "Standard54"
+    (shuffling "full")
+    (deal_pattern "sequential"))
+  (roles { (role "Landlord" 1) (role "Peasant" 3) })
+  (turn_order { "Landlord" "Peasant" "Peasant" "Peasant" })
+  
+  ;; 游戏准备阶段
+  (setup
+    (bidding false)
+    (deal 10)
+    (reserve 0)
+    (initial_score 0)
+    (initial_multiplier 1)
+    
+    ;; 区域定义
+    (zones
+      (hand (default_visibility owner) (initial_cards 10))
+      (field (default_visibility all) (initial_cards 0))
+      (discard_pile (default_visibility all) (initial_cards 0))
+      (main_deck (default_visibility hidden) (initial_cards 88))
+      (special_deck (UNO_Cards) (default_visibility all) (initial_cards 24))
+    )
+    
+    ;; 牌值与关系定义
+    (card_relations 
+      (card_values 3 4 5 6 7 8 9 10 J Q K A 2)
+      (used_in { "single_card" "pair" "straight" "bomb" })
+      (continuous_relations
+        (PokerSequence 3 4 5 6 7 8 9 10 J Q K A))
+      (non_continuous_cards { 2 } (used_in { "exceptions_in_straight_rules" }))
+      (suit_relations 
+        (order "Spade" "Heart" "Club" "Diamond") 
+        (used_in { "tie_breaker" }))
+      (same_value_relation 
+        (type "same_number") 
+        (used_in { "pair" "triple" "bomb" }))
+    )
+  )
+  
+  ;; 牌型系统
+  (combinations
+    (single)
+    (pair)
+    (triple)
+    (straight 5)
+    (bomb 4)
+    (custom_combination "UNO_Reverse"
+      (pattern [special_card "UNO_Reverse"])
+      (power_level 5)
+      (override_types { "all" }))
+    (custom_combination "UNO_Skip"
+      (pattern [special_card "UNO_Skip"])
+      (power_level 5)
+      (override_types { "all" }))
+    (custom_combination "UNO_DrawTwo"
+      (pattern [special_card "UNO_DrawTwo"])
+      (power_level 5)
+      (override_types { "all" }))
+  )
+  
+  ;; 游戏阶段与流程
+  (phases
+    ;; 先手机制阶段
+    (initiative_phase
+      (mode "random")
+      (details
+        (random (seed auto) (tie_breaker "suit")))
+      (constraints
+        (executed_after "deal")
+        (deterministic true)))
+    
+    ;; 行牌阶段
+    (playing_phase
+      (first_player "random")
+      (turn_order "circular")
+      (actions_ref actions)
+      (rules
+        (must_follow_suit_or_pass "any_type")
+        (bomb_increases_multiplier "doubling")
+        (chain_bomb_increases_multiplier "none")
+        (consecutive_pass_ends_trick 3)))
+  )
+  
+  ;; 特殊机制
+  (special_mechanics
+    (mechanic "UNO_Reverse"
+      (enabled true)
+      (description "改变出牌顺序方向")
+      (phase "playing_phase")
+      (timing "during_action")
+      (trigger_condition "valid_play")
+      (transfer_path from: hand to: field)
+      (visibility_change to: {all} on_target: true))
+    
+    (mechanic "UNO_Skip"
+      (enabled true)
+      (description "跳过下一个玩家的回合")
+      (phase "playing_phase")
+      (timing "during_action")
+      (trigger_condition "valid_play")
+      (transfer_path from: hand to: field)
+      (visibility_change to: {all} on_target: true))
+    
+    (mechanic "UNO_DrawTwo"
+      (enabled true)
+      (description "迫使下一个玩家摸两张牌并跳过回合")
+      (phase "playing_phase")
+      (timing "during_action")
+      (trigger_condition "valid_play")
+      (transfer_path from: hand to: field)
+      (visibility_change to: {all} on_target: true))
+  )
+)

validator_v2.py

@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+"""
+validator_v2.py — 基于 jsonschema(draft2020-12) 的严格校验
+validate_with_schema(ir, schema_path) -> (ok, issues, summary_msg)
+"""
+from __future__ import annotations
+from typing import Any, List, Tuple
+import json
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import best_match
+
+def _format_path(err) -> str:
+    if not err.path: return ""
+    return "/".join(str(p) for p in err.path)
+
+def validate_with_schema(ir: dict, schema_path: str) -> Tuple[bool, List[dict], str]:
+    schema = json.loads(open(schema_path, "r", encoding="utf-8").read())
+    validator = Draft202012Validator(schema)
+    errors = sorted(validator.iter_errors(ir), key=lambda e: list(e.path))
+    issues=[]
+    for e in errors:
+        issues.append({
+            "severity": "ERROR",
+            "path": _format_path(e),
+            "message": e.message
+        })
+    ok = len(issues)==0
+    msg = f"Schema: {'OK' if ok else 'FAIL'}; issues={len(issues)}"
+    return ok, issues, msg