galbook 0.0.0-stage → 1.2.4

package/galbook/engine.py

@@ -0,0 +1,325 @@
+"""运行时：把剧本往前推，遇到选项停下等 agent 选。
+
+状态（state，可 JSON 序列化，存档就是它的拷贝）：
+  scene, pc          当前位置
+  stack              call 的返回栈 [[scene, pc], ...]
+  f                  本局变量（随存档走）
+  vis                画面 {"bg", "cg", "sprites": {名字: {"img", "pos"}}, "bgm"}
+  pending            正在等的选项 {"scene", "pc", "id", "options": [{"i", "text", "k"}], "shown_at"}
+  ended              结束信息 {"kind", "name"} 或 None
+  turn               已经读过的台词句数（本局）
+  choices            本局做过的选择 [{"scene", "title", "id", "text", "i", "reason", "turn", "think_s"}]
+  log                最近 300 句回想 [{"who", "text", "scene"}]
+  rewind             最近 30 个选项点的快照（回溯用）
+  opts               {"h": "fold"|"full"|"skip", "mode": "normal"|"ironman", "hints": bool, "lang": "zh"|"en"}
+系统变量 s（通关标记等，跨周目）和已读记录 seen 不在 state 里，按 agent 存在档案中。
+"""
+import copy
+import re
+import time
+
+from .expr import evaluate, assign, ExprError
+from .ir import StoryError
+
+MAX_OPS_PER_CALL = 500000
+LOG_KEEP = 300
+REWIND_KEEP = 30
+H_FOLD_TEXT = "〔此处略（H 场景，new 时传 h=full 可展开）〕"
+H_FOLD_TEXT_EN = "〔Adult scene folded — start with h=full to show it〕"
+
+_RB = re.compile(r"\[rb,([^,\]]+),([^\]]*)\]")
+_TAG = re.compile(r"\[[A-Za-z]+(?:,[^\]]*)?\]")
+
+
+def plain(text):
+    """[rb,汉字,假名] → 汉字；其余 [xx,..] 标签去掉。"""
+    t = _RB.sub(lambda m: m.group(1), text or "")
+    return _TAG.sub("", t)
+
+
+class PlayError(ValueError):
+    pass
+
+
+H_MODES = ("fold", "full", "skip")
+MODES = ("normal", "ironman")
+
+
+def make_opts(h="fold", mode="normal", hints=False, lang="zh", **_):
+    """一局的玩法选项（new 时定，存进存档）。
+    h      H 场景：fold 折叠成一行（默认）/ full 照常 / skip 整段跳过不提示
+    mode   normal 可存读档回溯 / ironman 铁人：不能读档、不能回溯，选了就认
+    hints  选项旁标「选过」「新内容」（像很多游戏的已选标记）
+    lang   文本接口的语言 zh / en"""
+    return {"h": h if h in H_MODES else "fold", "mode": mode if mode in MODES else "normal",
+            "hints": str(hints).lower() in ("1", "true", "yes", "on"), "lang": lang if lang in ("zh", "en") else "zh"}
+
+
+def new_state(story, h="fold", **opts):
+    e = story.entry or {}
+    sid, pc = story.resolve(e.get("scene"), e.get("label"))
+    return {"scene": sid, "pc": pc, "stack": [], "f": {}, "vis": {"bg": None, "cg": None, "sprites": {}, "bgm": None},
+            "pending": None, "ended": None, "turn": 0, "choices": [], "log": [], "rewind": [],
+            "opts": make_opts(h=h, **opts), "started": time.time(), "h_shown": None}
+
+
+# ---------- 已读记录：每个场景一组区间 [[a,b],...]（闭区间，pc 编号） ----------
+def seen_has(seen, sid, pc):
+    for a, b in seen.get(sid, ()):
+        if a <= pc <= b:
+            return True
+        if a > pc:
+            return False
+    return False
+
+
+def seen_add(seen, sid, pc):
+    rs = seen.setdefault(sid, [])
+    for i, (a, b) in enumerate(rs):
+        if a <= pc <= b:
+            return False
+        if pc == b + 1:
+            rs[i][1] = pc
+            if i + 1 < len(rs) and rs[i + 1][0] == pc + 1:
+                rs[i][1] = rs[i + 1][1]
+                del rs[i + 1]
+            return True
+        if pc == a - 1:
+            rs[i][0] = pc
+            return True
+        if pc < a:
+            rs.insert(i, [pc, pc])
+            return True
+    rs.append([pc, pc])
+    return True
+
+
+def _snapshot(state):
+    snap = {k: copy.deepcopy(v) for k, v in state.items() if k not in ("rewind", "log")}
+    snap["log_len"] = len(state.get("log", []))
+    return snap
+
+
+def advance(story, state, sysv, seen, n=20, skip_read=False):
+    """往前推进，最多收 n 句「新」台词；遇到选项 / 结束就停。
+    skip_read=True：已读过的句子快进不计数（像游戏里的「跳过已读」），停在第一句没读过的或选项上。
+    返回 {"lines": [...], "skipped": 已读快进句数, "choice": ..., "ended": ..., "events": [...]}"""
+    out, events = [], []
+    skipped = 0
+    if state.get("pending"):
+        return _result(story, state, out, skipped, events)
+    if state.get("ended"):
+        return _result(story, state, out, skipped, events)
+    budget = MAX_OPS_PER_CALL
+    while budget > 0:
+        budget -= 1
+        sc = story.scene(state["scene"])
+        pc = state["pc"]
+        if pc >= len(sc.ops):
+            if state["stack"]:
+                state["scene"], state["pc"] = state["stack"].pop()
+                continue
+            state["ended"] = {"kind": "stop", "dead_end": True, "scene": sc.id,
+                              "name": "场景 %s「%s」走到底且没有跳转（这个场景缺出口）" % (sc.id, sc.title)}
+            break
+        op = sc.ops[pc]
+        state["pc"] = pc + 1
+        cond = op.get("if")
+        k = op.get("op")
+        if cond and k != "choice":
+            try:
+                if not evaluate(cond, state["f"], sysv):
+                    continue
+            except ExprError as e:
+                events.append({"warn": str(e)})
+                continue
+        if k == "say":
+            hm = state["opts"].get("h")
+            if "h" in sc.tags and hm != "full":
+                if hm != "skip" and state.get("h_shown") != sc.id:
+                    state["h_shown"] = sc.id
+                    line = {"who": "", "text": H_FOLD_TEXT_EN if state["opts"].get("lang") == "en" else H_FOLD_TEXT,
+                            "scene": sc.id, "pc": pc, "folded": True}
+                    out.append(line)
+                    _log(state, line)
+                seen_add(seen, sc.id, pc)
+                continue
+            was = seen_has(seen, sc.id, pc)
+            seen_add(seen, sc.id, pc)
+            state["turn"] += 1
+            line = {"who": op.get("who") or "", "text": op.get("text") or "", "scene": sc.id, "pc": pc}
+            if op.get("voice"):
+                line["voice"] = op["voice"]
+            _log(state, line)
+            if skip_read and was:
+                skipped += 1
+                continue
+            line["vis"] = _vis_brief(state["vis"])
+            out.append(line)
+            if len(out) >= n:
+                break
+        elif k == "bg":
+            state["vis"]["bg"] = op.get("img")
+            state["vis"]["cg"] = None
+        elif k == "cg":
+            state["vis"]["cg"] = op.get("img")
+            if op.get("img"):
+                events.append({"cg": op["img"]})
+        elif k == "sprite":
+            if op.get("img"):
+                state["vis"]["sprites"][op.get("name", "?")] = {"img": op["img"], "pos": op.get("pos") or "center"}
+            else:
+                state["vis"]["sprites"].pop(op.get("name", "?"), None)
+        elif k == "sprites_clear":
+            state["vis"]["sprites"] = {}
+        elif k == "bgm":
+            state["vis"]["bgm"] = op.get("name")
+        elif k == "label":
+            nm = op.get("name") or ""
+            if nm and not nm.startswith("__"):
+                state["label"] = nm
+        elif k == "set":
+            try:
+                for name in assign(op.get("expr", ""), state["f"], sysv):
+                    events.append({"set": name})
+            except ExprError as e:
+                events.append({"warn": str(e)})
+        elif k == "jump":
+            state["scene"], state["pc"] = story.resolve(op.get("scene"), op.get("label"), sc.id)
+        elif k == "call":
+            state["stack"].append([sc.id, state["pc"]])
+            state["scene"], state["pc"] = story.resolve(op.get("scene"), op.get("label"), sc.id)
+        elif k == "ret":
+            if state["stack"]:
+                state["scene"], state["pc"] = state["stack"].pop()
+        elif k == "event":
+            events.append({"event": op.get("name"), "arg": op.get("arg")})
+        elif k == "end":
+            state["ended"] = {"kind": op.get("kind") or "ending", "scene": sc.id,
+                              "name": op.get("name") or ("%s·%s" % (sc.title, state["label"]) if state.get("label") and state["label"] != sc.title else sc.title)}
+            if op.get("how"):
+                state["ended"]["how"] = op["how"]
+            break
+        elif k == "choice":
+            opts = []
+            for j, o in enumerate(op.get("options") or []):
+                try:
+                    ok = evaluate(o.get("if"), state["f"], sysv)
+                except ExprError as e:
+                    events.append({"warn": str(e)})
+                    ok = False
+                if ok:
+                    opts.append({"i": len(opts) + 1, "text": plain(o.get("text", "")), "k": j})
+            if not opts:
+                continue
+            if len(opts) == 1 and op.get("auto_single"):
+                state["pc"] = pc
+                _take(story, state, sysv, sc, op, opts[0], reason="（只有一个可选，自动）", auto=True)
+                continue
+            state["pc"] = pc
+            state["pending"] = {"scene": sc.id, "pc": pc, "id": op.get("id") or ("c%d" % pc),
+                                "prompt": op.get("prompt") or "", "options": opts, "shown_at": time.time()}
+            state["rewind"].append(_snapshot(state))
+            del state["rewind"][:-REWIND_KEEP]
+            break
+    else:
+        raise PlayError("一次推进执行了 %d 条指令还没停，剧本可能有死循环（%s#%d）"
+                        % (MAX_OPS_PER_CALL, state["scene"], state["pc"]))
+    return _result(story, state, out, skipped, events)
+
+
+def _take(story, state, sysv, sc, op, opt, reason="", auto=False):
+    o = op["options"][opt["k"]]
+    if o.get("set"):
+        assign(o["set"], state["f"], sysv)
+    g = o.get("goto") or {}
+    shown = (state.get("pending") or {}).get("shown_at")
+    state["choices"].append({"scene": sc.id, "title": sc.title, "id": op.get("id") or "", "text": opt["text"],
+                             "i": opt["i"], "of": None, "reason": (reason or "")[:500], "turn": state["turn"],
+                             "think_s": round(time.time() - shown, 1) if shown else None, "auto": auto})
+    state["pending"] = None
+    if g:
+        state["scene"], state["pc"] = story.resolve(g.get("scene"), g.get("label"), sc.id)
+    else:
+        state["pc"] = state["pc"] + 1
+
+
+def choose(story, state, sysv, i, reason=""):
+    p = state.get("pending")
+    if not p:
+        raise PlayError("现在没有选项可选")
+    try:
+        i = int(i)
+    except (TypeError, ValueError):
+        raise PlayError("i 要填选项编号（1 开始）")
+    opt = next((o for o in p["options"] if o["i"] == i), None)
+    if opt is None:
+        raise PlayError("没有第 %d 个选项（共 %d 个）" % (i, len(p["options"])))
+    sc = story.scene(p["scene"])
+    op = sc.ops[p["pc"]]
+    state["pc"] = p["pc"]
+    _take(story, state, sysv, sc, op, opt, reason)
+    state["choices"][-1]["of"] = len(p["options"])
+    return state["choices"][-1]
+
+
+def rewind(state, steps=1):
+    """回到第 steps 个之前的选项点（1 = 最近一次的选项，重新选）。"""
+    rw = state.get("rewind") or []
+    if not rw:
+        raise PlayError("还没有可回溯的选项点")
+    steps = max(1, min(int(steps), len(rw)))
+    snap = rw[-steps]
+    keep = rw[:-steps] + [snap]
+    log = state.get("log", [])[:snap.get("log_len", 0)]
+    new = copy.deepcopy({k: v for k, v in snap.items() if k != "log_len"})
+    new["rewind"] = keep
+    new["log"] = log
+    if new.get("pending"):
+        new["pending"]["shown_at"] = time.time()
+    return new
+
+
+def _log(state, line):
+    lg = state.setdefault("log", [])
+    lg.append({"who": line["who"], "text": line["text"], "scene": line["scene"]})
+    if len(lg) > LOG_KEEP + 50:
+        del lg[:-LOG_KEEP]
+
+
+def _vis_brief(vis):
+    return {"bg": vis.get("bg"), "cg": vis.get("cg"),
+            "sprites": [dict(name=k, **v) for k, v in (vis.get("sprites") or {}).items()]}
+
+
+def where(story, state):
+    sc = story.scenes.get(state.get("scene"))
+    return {"scene": state.get("scene"), "title": sc.title if sc else "", "route": sc.route if sc else "",
+            "turn": state.get("turn", 0)}
+
+
+def peek(story, state, recent=5):
+    """不推进，只看当前在哪、有没有待选的选项（旁观 / status 用）。"""
+    r = _result(story, state, [], 0, [])
+    r["recent"] = [{"who": x.get("who", ""), "text": x.get("text", "")} for x in (state.get("log") or [])[-recent:]]
+    return r
+
+
+def _result(story, state, lines, skipped, events):
+    r = {"lines": lines, "skipped": skipped, "where": where(story, state), "vis": _vis_brief(state["vis"])}
+    if state.get("pending"):
+        p = state["pending"]
+        r["choice"] = {"id": p["id"], "prompt": p.get("prompt", ""),
+                       "options": [{"i": o["i"], "text": o["text"]} for o in p["options"]]}
+    if state.get("ended"):
+        r["ended"] = state["ended"]
+    ev = [e for e in events if "warn" not in e and "cg" not in e]
+    cgs = [e["cg"] for e in events if "cg" in e]
+    if cgs:
+        r["cg_seen"] = cgs
+    warns = [e["warn"] for e in events if "warn" in e]
+    if ev:
+        r["events"] = ev[-20:]
+    if warns:
+        r["warnings"] = warns[:10]
+    return r

package/galbook/expr.py

@@ -0,0 +1,107 @@
+"""安全表达式：条件与赋值。
+
+语法（各引擎的条件写法都先翻成这一种）：
+  字面量   123  -4  "abc"  'abc'  true false
+  变量     f.name（本局变量，随存档走）  s.name（系统变量，跨周目，按 agent 存）
+  运算     + - * / %   == != < <= > >=   && || !   and or not   括号
+赋值语句：  f.x = 1 ；  s.clear_a = 1 ；  f.n += 2   （多条用 ; 分隔）
+未定义变量按 0 处理（和多数 ADV 引擎一致）。
+"""
+import ast
+import re
+
+_VAR = re.compile(r"\b([fs])\.([A-Za-z_\u0080-\uffff][\w\u0080-\uffff]*)")
+_ALLOWED = (ast.Expression, ast.BoolOp, ast.BinOp, ast.UnaryOp, ast.Compare, ast.Constant,
+            ast.Name, ast.Load, ast.And, ast.Or, ast.Not, ast.USub, ast.UAdd, ast.Add, ast.Sub,
+            ast.Mult, ast.Div, ast.FloorDiv, ast.Mod, ast.Eq, ast.NotEq, ast.Lt, ast.LtE, ast.Gt, ast.GtE,
+            ast.Subscript, ast.Index if hasattr(ast, "Index") else ast.Constant)
+_CACHE = {}
+
+
+class ExprError(ValueError):
+    pass
+
+
+_STR = re.compile(r"(\"(?:[^\"\\]|\\.)*\"|'(?:[^'\\]|\\.)*')")
+
+
+def _translate_code(s):
+    s = s.replace("&&", " and ").replace("||", " or ")
+    s = re.sub(r"!(?!=)", " not ", s)
+    s = re.sub(r"\btrue\b", "True", s)
+    s = re.sub(r"\bfalse\b", "False", s)
+    return _VAR.sub(lambda m: 'V["%s.%s"]' % (m.group(1), m.group(2)), s)
+
+
+def _translate(src):
+    parts = _STR.split(str(src))
+    # 偶数段是代码，奇数段是字符串字面量（原样保留）
+    return "".join(p if i % 2 else _translate_code(p) for i, p in enumerate(parts)).strip()
+
+
+def compile_expr(src):
+    if src in _CACHE:
+        return _CACHE[src]
+    py = _translate(src)
+    try:
+        tree = ast.parse(py, mode="eval")
+    except SyntaxError as e:
+        raise ExprError("表达式语法错误: %r (%s)" % (src, e))
+    for node in ast.walk(tree):
+        if not isinstance(node, _ALLOWED):
+            raise ExprError("表达式含不允许的成分 %s: %r" % (type(node).__name__, src))
+        if isinstance(node, ast.Name) and node.id not in ("V", "True", "False"):
+            raise ExprError("未知名字 %r（变量要写成 f.x 或 s.x）: %r" % (node.id, src))
+    code = compile(tree, "<expr>", "eval")
+    _CACHE[src] = code
+    return code
+
+
+class _Vars(dict):
+    def __missing__(self, k):
+        return 0
+
+
+def evaluate(src, f, s):
+    if src is None or src == "":
+        return True
+    v = _Vars()
+    for k, x in (f or {}).items():
+        v["f." + k] = x
+    for k, x in (s or {}).items():
+        v["s." + k] = x
+    try:
+        return eval(compile_expr(src), {"__builtins__": {}}, {"V": v})
+    except ExprError:
+        raise
+    except ZeroDivisionError:
+        return 0
+    except Exception as e:
+        raise ExprError("表达式求值失败 %r: %s" % (src, e))
+
+
+_ASSIGN = re.compile(r"^\s*([fs])\.([\w\u0080-\uffff]+)\s*(\+=|-=|\*=|=)\s*(.+?)\s*$")
+
+
+def assign(stmts, f, s):
+    """执行 'f.x = 1; s.y += 2'。返回改动过的变量名列表。"""
+    changed = []
+    for st in re.split(r";(?=(?:[^\"']|\"[^\"]*\"|'[^']*')*$)", str(stmts)):
+        if not st.strip():
+            continue
+        m = _ASSIGN.match(st)
+        if not m:
+            raise ExprError("赋值语句看不懂: %r" % st)
+        scope, name, op, rhs = m.groups()
+        val = evaluate(rhs, f, s)
+        tgt = f if scope == "f" else s
+        if op == "=":
+            tgt[name] = val
+        elif op == "+=":
+            tgt[name] = tgt.get(name, 0) + val
+        elif op == "-=":
+            tgt[name] = tgt.get(name, 0) - val
+        elif op == "*=":
+            tgt[name] = tgt.get(name, 0) * val
+        changed.append(scope + "." + name)
+    return changed

package/galbook/i18n.py

@@ -0,0 +1,85 @@
+"""文本接口的多语言（zh / en）。只管给 agent 看的框架文字；剧本台词保持原文。"""
+import re
+
+T = {
+    "zh": {
+        "line_hdr": "【{title}】第 {turn} 句", "skipped": "（跳过已读 {n} 句）", "choice_hdr": "—— 选项{prompt} ——",
+        "choose_hint": "选：{base}choose&i=编号&reason=一句理由{auto}", "auto_saved": "   （已自动存档 auto）",
+        "persona": "（你的人设：{p}）", "mark_picked": "选过", "mark_new": "新内容",
+        "ended": "—— 结束：{name}（{kind}）——", "kind_ending": "结局", "kind_title": "回到标题", "kind_stop": "停住",
+        "after_end": "再来一局：{base}new   回到上个选项：{base}rewind   看收集：{base}gallery",
+        "after_end_iron": "再来一局：{base}new   看收集：{base}gallery",
+        "cont": "继续：{base}next", "you_chose": "你选了：{text}（{i}/{of}）", "no_saves": "还没有存档。",
+        "save_row": "[{slot}] {title} 第{turn}句 {preview}{note}", "note": "  备注：", "log_choices": "—— 做过的选择 ——",
+        "reason": "（理由：{r}）", "read": "已读 {pct:.1f}%，看过 {n} 个场景",
+        "stats": "周目 {g}，读了 {l} 句，选择 {c} 次，存档 {s} / 读档 {ld} / 回溯 {rw}",
+        "endings_seen": "到过的结局：", "sysvars": "系统记录：", "humanlike": "像不像人：",
+        "not_started": "《{title}》还没开始。新游戏：{base}new（可加 &mode=ironman &hints=1 &h=skip &lang=en）",
+        "has_saves": "有存档：{s}（读档：{base}load&slot=…）", "recent": "（最近几句）", "recent_load": "（读档前最后几句）",
+        "vis_cg": "CG ", "vis_bg": "背景 ", "vis_on": "在场 ", "sep": "、",
+        "ev_eyecatch": "〔转场：{a}〕", "ev_endroll": "〔片尾〕", "ev_clear": "〔通关记录：{a}〕",
+        "persona_now": "当前人设：{p}", "persona_none": "还没设人设。设：{base}persona&text=一段描述你性格/口味的话",
+        "gallery": "结局 {e}/{et}：{names}\n路线 {rs}/{rt}：{routes}\nCG {c}/{ct}\n已读 {pct:.1f}%，周目 {g}",
+        "opts": "本局：H={h} 模式={mode} 提示={hints} 语言={lg}", "error": "错误：{e}\n（玩法：/play/t）",
+    },
+    "en": {
+        "line_hdr": "[{title}] line {turn}", "skipped": "(skipped {n} already-read lines)", "choice_hdr": "—— CHOICE{prompt} ——",
+        "choose_hint": "Pick: {base}choose&i=N&reason=one+sentence+why{auto}", "auto_saved": "   (auto-saved to slot auto)",
+        "persona": "(your persona: {p})", "mark_picked": "picked before", "mark_new": "new",
+        "ended": "—— END: {name} ({kind}) ——", "kind_ending": "ending", "kind_title": "back to title", "kind_stop": "stopped",
+        "after_end": "New game: {base}new   Back to last choice: {base}rewind   Collection: {base}gallery",
+        "after_end_iron": "New game: {base}new   Collection: {base}gallery",
+        "cont": "Continue: {base}next", "you_chose": "You chose: {text} ({i}/{of})", "no_saves": "No saves yet.",
+        "save_row": "[{slot}] {title} line {turn} {preview}{note}", "note": "  note: ", "log_choices": "—— Choices made ——",
+        "reason": " (why: {r})", "read": "Read {pct:.1f}%, {n} scenes visited",
+        "stats": "Playthroughs {g}, lines {l}, choices {c}, saves {s} / loads {ld} / rewinds {rw}",
+        "endings_seen": "Endings reached: ", "sysvars": "System flags: ", "humanlike": "Human-likeness: ",
+        "not_started": "\"{title}\" not started. New game: {base}new (options: &mode=ironman &hints=1 &h=skip &lang=en)",
+        "has_saves": "Saves: {s} (load: {base}load&slot=…)", "recent": "(last lines)", "recent_load": "(last lines before this save)",
+        "vis_cg": "CG ", "vis_bg": "BG ", "vis_on": "on stage: ", "sep": ", ",
+        "ev_eyecatch": "〔scene change: {a}〕", "ev_endroll": "〔credits〕", "ev_clear": "〔clear flag: {a}〕",
+        "persona_now": "Persona: {p}", "persona_none": "No persona yet. Set one: {base}persona&text=a+few+lines+about+your+character",
+        "gallery": "Endings {e}/{et}: {names}\nRoutes {rs}/{rt}: {routes}\nCG {c}/{ct}\nRead {pct:.1f}%, playthroughs {g}",
+        "opts": "This run: H={h} mode={mode} hints={hints} lang={lg}", "error": "Error: {e}\n(how to play: /play/t?lang=en)",
+    },
+}
+
+# 常见报错 / 提示的英文（引擎内部报错是中文，按前缀翻）
+_ERR = [
+    (r"^还没开始。.*", "Not started yet. Use new (new game) or load."),
+    (r"^现在没有选项可选", "There is no choice to make right now."),
+    (r"^没有第 (\d+) 个选项（共 (\d+) 个）", r"No option \1 (there are \2)."),
+    (r"^i 要填选项编号.*", "i must be the option number (from 1) or random."),
+    (r"^还没有可回溯的选项点", "No choice point to rewind to yet."),
+    (r"^存档位 (\S+) 是空的", r"Save slot \1 is empty."),
+    (r"^存档位只能是.*", "Slot must be auto / quick / 1-99."),
+    (r"^agent 名不合法.*", "Invalid agent name (1-40 letters/digits/CJK/_-.)."),
+    (r"^没有这本书: (.*)", r"No such book: \1"),
+    (r"^铁人模式这一局不能(.*?)（.*", r"Ironman run: \1 is disabled (choices are final; start a new game to retry)."),
+    (r"^不认识的操作 (.*?)（可用：(.*)）", r"Unknown action \1 (available: \2)"),
+    (r"^do 只能是：(.*)", r"do must be one of: \1"),
+    (r"^新游戏开始（第 (\d+) 周目）", r"New game started (playthrough #\1)"),
+    (r"^已存到 (.*)", r"Saved to \1"), (r"^读档 (.*)", r"Loaded \1"), (r"^回到选项点", "Back at the choice point"),
+    (r"^点了一下，什么也没发生。", "You click. Nothing happens."), (r"^点了一下。$", "Click."),
+    (r"^点击效果执行失败：(.*)", r"Click effect failed: \1"),
+    (r"^人设已记下", "Persona saved"), (r"^人设已清空", "Persona cleared"),
+    (r"^路径多了一段.*", "Too many path segments: /play/t/<book>/<name>?do=…"),
+]
+_KIND = {"读档": "loading", "手动存档": "manual saving", "回溯": "rewinding"}
+
+
+def t(lang, key, **kw):
+    d = T.get(lang) or T["zh"]
+    return (d.get(key) or T["zh"][key]).format(**kw)
+
+
+def msg(lang, s):
+    if lang != "en" or not s:
+        return s
+    for pat, rep in _ERR:
+        if re.match(pat, s):
+            out = re.sub(pat, rep, s)
+            for zh, en in _KIND.items():
+                out = out.replace(zh, en)
+            return out
+    return s

package/galbook/importers/__init__.py

@@ -0,0 +1,106 @@
+"""各引擎脚本 → galbook/1 中间格式。
+
+内置：qlie / kag（吉里吉里·Tyrano）/ renpy / nscripter / galscript（.gal 手写格式）/ textdump（VNTextPatch 等文本导出，线性）
+插件：环境变量 GALBOOK_PLUGINS（多个用 os.pathsep 分隔）指向 .py 文件或目录；或 build 时 --plugin x.py。
+      插件模块要有 NAME、build(src, assets=None, **opts) -> (meta, scenes)，可选 detect(src) -> (bool, 说明)。
+      详见 docs/IMPORTERS.md。
+"""
+import importlib
+import importlib.util
+import os
+
+NAMES = ("qlie", "kag", "renpy", "nscripter", "galscript", "textdump")
+_plugins = {}
+
+
+def load_plugin(path):
+    """加载一个插件文件，返回它的 NAME。"""
+    spec = importlib.util.spec_from_file_location("galbook_plugin_%d" % len(_plugins), path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    if not getattr(mod, "NAME", None) or not callable(getattr(mod, "build", None)):
+        raise ValueError("插件 %s 缺 NAME 或 build()" % path)
+    _plugins[mod.NAME] = mod
+    return mod.NAME
+
+
+def _env_plugins():
+    for p in filter(None, os.environ.get("GALBOOK_PLUGINS", "").split(os.pathsep)):
+        files = [os.path.join(p, f) for f in sorted(os.listdir(p)) if f.endswith(".py")] if os.path.isdir(p) else [p]
+        for f in files:
+            if not any(getattr(m, "__file__", None) == f for m in _plugins.values()):
+                load_plugin(f)
+
+
+def names():
+    _env_plugins()
+    return list(NAMES) + [n for n in _plugins if n not in NAMES]
+
+
+def get(name):
+    _env_plugins()
+    if name in _plugins:
+        return _plugins[name]
+    if name not in NAMES:
+        raise ValueError("没有这个导入器: %r（有：%s）" % (name, " ".join(names())))
+    return importlib.import_module("." + name, __name__)
+
+
+def detect(src):
+    """按文件特征认引擎。返回 (engine, 依据)；认不出返回 (None, 说明)。插件先认。"""
+    if not os.path.isdir(src):
+        return None, "目录不存在或不是目录: %s" % src
+    _env_plugins()
+    for n, m in _plugins.items():
+        if callable(getattr(m, "detect", None)):
+            ok, why = m.detect(src)
+            if ok:
+                return n, why
+    names_ = []
+    for dp, dn, fn in os.walk(src):
+        for f in fn:
+            names_.append(os.path.join(dp, f))
+        if len(names_) > 20000:
+            break
+    low = [n.lower() for n in names_]
+
+    def has(ext):
+        return [n for n in low if n.endswith(ext)]
+    if has(".gal"):
+        return "galscript", "有 galscript 剧本（.gal）"
+    if any(os.path.basename(n) in ("route.s", "select.s") for n in low) or (has(".s") and any("シナリオ" in n for n in names_)):
+        return "qlie", "有 QLIE 的 .s 剧本（route.s/select.s 或 シナリオ目录）"
+    if has(".pack") and not has(".s"):
+        return None, "QLIE .pack 封包：先用 GARbro 解包出 .s 再导入"
+    if has(".rpy"):
+        return "renpy", "有 Ren'Py 的 .rpy 源码"
+    if has(".rpyc") or has(".rpa"):
+        return None, "Ren'Py 编译过的 .rpyc/.rpa：先用 unrpa 解包、unrpyc 反编译成 .rpy 再导入"
+    if has(".ks"):
+        return "kag", "有吉里吉里 KAG / TyranoScript 的 .ks 剧本"
+    if has(".xp3"):
+        return None, "吉里吉里 .xp3 封包：先用 GARbro / KrkrExtract 解出 .ks 再导入"
+    if any(os.path.basename(n) in ("0.txt", "00.txt", "nscript.dat", "nscript.___") for n in low):
+        return "nscripter", "有 NScripter 的 0.txt / nscript.dat"
+    from . import textdump
+    ok, why = textdump.detect(src)
+    if ok:
+        return "textdump", why
+    hint = "（可以先用 VNTextPatch extractlocal 抽成 .json 再用 textdump 导入，能读但没有分支）"
+    if any(os.path.basename(n) in ("scene.pck", "gameexe.dat") for n in low):
+        return None, "SiglusEngine（Scene.pck）：字节码+按作品加密，见 docs/ENGINES.md"
+    if any(os.path.basename(n).startswith("seen") and n.endswith(".txt") for n in low):
+        return None, "RealLive（SEEN.TXT）：用 RLdev kprl 反编译，或 VNTextPatch --format=reallive 抽文本" + hint
+    if has(".pfs") or has(".ast") or has(".asb"):
+        return None, "Artemis（.pfs/.ast）：解包后可用 VNTextPatch 抽文本" + hint
+    if has(".mjo"):
+        return None, "Majiro（.mjo 字节码）" + hint
+    if has(".ws2"):
+        return None, "AdvHD（.ws2）" + hint
+    if has(".cst"):
+        return None, "CatSystem2（.cst）" + hint
+    if has(".ybn"):
+        return None, "YU-RIS（.ybn）" + hint
+    if has(".arc") and any("sysgrp" in n or "data0" in n for n in low):
+        return None, "像 BGI/Ethornell（.arc）：解包后 VNTextPatch --format=ethornell" + hint
+    return None, "认不出引擎（看了 %d 个文件）" % len(names_)