galbook 1.2.4 → 1.2.5

package/galbook/cli.py

@@ -1,29 +1,31 @@
-"""命令行里玩（不用起服务）：
-  python3 -m galbook play <books目录> <存档目录> <书> <agent> <操作> [k=v ...]
-例：python3 -m galbook play books play-data lighthouse alice next n=30"""
-import sys
-
-from .play import Library
-from .web import render_text
-
-
-def main(argv=None):
-    a = list(argv if argv is not None else sys.argv[1:])
-    if len(a) < 5:
-        print(__doc__)
-        return 2
-    books, data, book, agent, do = a[:5]
-    kw = dict(x.split("=", 1) for x in a[5:])
-    if kw.pop("skip", "") in ("1", "true"):
-        kw["skip_read"] = True
-    img = kw.pop("img", "") in ("1", "true")
-    lang = kw.get("lang") if do == "new" else kw.pop("lang", None)
-    lib = Library(books, data)
-    r = lib.act(book, agent, do, **kw)
-    lang = lang or ((r.get("opts") or (lib.store.peek_run(book, agent) or {}).get("opts") or {}).get("lang")) or "zh"
-    sys.stdout.write(render_text(r, do, img, book, agent, lang))
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())
+"""命令行里玩（不用起服务）：
+  python3 -m galbook play <books目录> <存档目录> <书> <agent> <操作> [k=v ...]
+例：python3 -m galbook play books play-data lighthouse alice next n=30"""
+import sys
+
+from .play import Library
+from .web import render_text, want_vis
+
+
+def main(argv=None):
+    a = list(argv if argv is not None else sys.argv[1:])
+    if len(a) < 5:
+        print(__doc__)
+        return 2
+    books, data, book, agent, do = a[:5]
+    kw = dict(x.split("=", 1) for x in a[5:])
+    if kw.pop("skip", "") in ("1", "true"):
+        kw["skip_read"] = True
+    img = kw.pop("img", "") in ("1", "true")
+    lang = kw.get("lang") if do == "new" else kw.pop("lang", None)
+    vis = kw.pop("vis", None)
+    lib = Library(books, data)
+    vis = want_vis(lib, book, vis)
+    r = lib.act(book, agent, do, **kw)
+    lang = lang or ((r.get("opts") or (lib.store.peek_run(book, agent) or {}).get("opts") or {}).get("lang")) or "zh"
+    sys.stdout.write(render_text(r, do, img, book, agent, lang, vis=vis))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/galbook/imaging.py

@@ -0,0 +1,121 @@
+"""把书里的图变成能直接塞给多模态模型的格式（只用标准库）。
+
+  load_for_model(path, max_side=1280) -> (mime, bytes) 或 (None, 原因)
+PNG / JPEG / GIF / WebP 原样给；BMP（QLIE 等老引擎常见）转成 PNG，太大时按整数倍缩小；
+SVG 和其他格式不转（模型多半不认），返回原因，调用方改给路径。"""
+import struct
+import zlib
+
+PASS = ((b"\x89PNG\r\n\x1a\n", "image/png"), (b"\xff\xd8\xff", "image/jpeg"), (b"GIF87a", "image/gif"),
+        (b"GIF89a", "image/gif"))
+MAX_BYTES = 8 * 1024 * 1024
+
+
+def sniff(head):
+    for magic, mime in PASS:
+        if head.startswith(magic):
+            return mime
+    if head[:4] == b"RIFF" and head[8:12] == b"WEBP":
+        return "image/webp"
+    if head[:2] == b"BM":
+        return "image/bmp"
+    if b"<svg" in head[:512].lower():
+        return "image/svg+xml"
+    return None
+
+
+def load_for_model(path, max_side=1280):
+    try:
+        with open(path, "rb") as f:
+            data = f.read(MAX_BYTES + 1)
+    except OSError as e:
+        return None, "读不到图 / cannot read: %s" % e.__class__.__name__
+    if len(data) > MAX_BYTES:
+        return None, "图太大（>8MB）/ too large"
+    mime = sniff(data[:600])
+    if mime in ("image/png", "image/jpeg", "image/gif", "image/webp"):
+        return mime, data
+    if mime == "image/bmp":
+        try:
+            return "image/png", bmp_to_png(data, max_side)
+        except ValueError as e:
+            return None, "BMP 转不了 / unsupported BMP: %s" % e
+    if mime == "image/svg+xml":
+        return None, "SVG 不能直接当图片发 / SVG is not sent as an image"
+    return None, "不认识的图片格式 / unknown image format"
+
+
+def bmp_to_png(data, max_side=1280):
+    """未压缩 BMP（1/4/8 位调色板、16/24/32 位）→ PNG（RGB）。"""
+    if data[:2] != b"BM" or len(data) < 54:
+        raise ValueError("not a BMP")
+    off = struct.unpack_from("<I", data, 10)[0]
+    hsize = struct.unpack_from("<I", data, 14)[0]
+    if hsize == 12:
+        w, h, _, bpp = struct.unpack_from("<HHHH", data, 18)
+        comp, ncol, palsz = 0, 0, 3
+    else:
+        w, h, _, bpp, comp = struct.unpack_from("<iiHHI", data, 18)
+        ncol = struct.unpack_from("<I", data, 46)[0] if hsize >= 40 else 0
+        palsz = 4
+    if comp not in (0, 3) or (comp == 3 and bpp not in (16, 32)):
+        raise ValueError("compressed (%d)" % comp)
+    top_down = h < 0
+    h = abs(h)
+    if not (0 < w <= 10000 and 0 < h <= 10000):
+        raise ValueError("bad size")
+    stride = ((w * bpp + 31) // 32) * 4
+    if off + stride * h > len(data):
+        raise ValueError("truncated")
+    pal = None
+    if bpp <= 8:
+        n = ncol or (1 << bpp)
+        p0 = 14 + hsize
+        pal = [data[p0 + i * palsz:p0 + i * palsz + 3][::-1] for i in range(n)]   # BGR → RGB
+        pal += [b"\0\0\0"] * (256 - len(pal))
+    step = 1
+    while max(w, h) // step > max_side:
+        step += 1
+    ow, oh = (w + step - 1) // step, (h + step - 1) // step
+    rows = []
+    for oy in range(oh):
+        y = oy * step
+        src = y if top_down else h - 1 - y
+        row = data[off + src * stride: off + src * stride + stride]
+        if bpp == 24:
+            px = bytearray(w * 3)
+            px[0::3], px[1::3], px[2::3] = row[2:w * 3:3], row[1:w * 3:3], row[0:w * 3:3]
+        elif bpp == 32:
+            px = bytearray(w * 3)
+            px[0::3], px[1::3], px[2::3] = row[2:w * 4:4], row[1:w * 4:4], row[0:w * 4:4]
+        elif bpp == 16:
+            px = bytearray()
+            for x in range(w):
+                v = row[2 * x] | (row[2 * x + 1] << 8)
+                px += bytes(((v >> 10 & 31) * 255 // 31, (v >> 5 & 31) * 255 // 31, (v & 31) * 255 // 31))
+        elif bpp == 8:
+            px = b"".join(pal[b] for b in row[:w])
+        elif bpp in (4, 1):
+            per = 8 // bpp
+            mask = (1 << bpp) - 1
+            idx = [(row[x // per] >> (8 - bpp * (x % per + 1))) & mask for x in range(w)]
+            px = b"".join(pal[i] for i in idx)
+        else:
+            raise ValueError("%d bpp" % bpp)
+        if step > 1:
+            px = b"".join(bytes(px[x * 3:x * 3 + 3]) for x in range(0, w, step))
+        rows.append(b"\0" + bytes(px))
+    return _png(ow, oh, b"".join(rows))
+
+
+def _png(w, h, raw):
+    def chunk(t, d):
+        return struct.pack(">I", len(d)) + t + d + struct.pack(">I", zlib.crc32(t + d) & 0xffffffff)
+    return (b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", struct.pack(">IIBBBBB", w, h, 8, 2, 0, 0, 0))
+            + chunk(b"IDAT", zlib.compress(raw, 6)) + chunk(b"IEND", b""))
+
+
+def png_size(data):
+    if data[:8] == b"\x89PNG\r\n\x1a\n":
+        return struct.unpack(">II", data[16:24])
+    return None

package/galbook/mcp_server.py

@@ -8,6 +8,7 @@
 多个 agent 可以各起一个 MCP 进程（不同 --agent），共用同一个 --data 目录；存储层有文件锁，互不干扰。
 也可以不起进程：python3 -m galbook serve 自带 Streamable HTTP 的 MCP 端点 POST /mcp?book=…&agent=…（见 server.py）。"""
 import argparse
+import base64
 import os
 import json
 import sys
@@ -15,7 +16,7 @@ import traceback
 
 from . import VERSION
 from .play import Library
-from .tools import mcp_tools, call_tool
+from .tools import mcp_tools, call_tool, call_tool_rich
 from .i18n import msg
 
 PROTO = "2024-11-05"
@@ -46,8 +47,12 @@ def handle(lib, req, book=None, agent=None, lang="zh", force_agent=None):
                     if args.get("agent") not in (None, "", force_agent):
                         raise ValueError("这个令牌只能用名字 %s / this token can only play as %s" % (force_agent, force_agent))
                     args["agent"] = force_agent
-                text = call_tool(lib, params.get("name"), args, book, agent, lang)
-                res = {"content": [{"type": "text", "text": text}], "isError": False}
+                text, images = call_tool_rich(lib, params.get("name"), args, book, agent, lang)
+                content = [{"type": "text", "text": text}]
+                for lb, mime, data in images:          # 图和文在同一条消息里（MCP image content）
+                    content.append({"type": "text", "text": "〔图〕" + lb})
+                    content.append({"type": "image", "data": base64.b64encode(data).decode("ascii"), "mimeType": mime})
+                res = {"content": content, "isError": False}
             except (ValueError, KeyError) as e:
                 res = {"content": [{"type": "text", "text": msg(lang, str(e))}], "isError": True}
         else:

package/galbook/play.py

@@ -11,8 +11,8 @@ from .ir import load_story, StoryError
 from .importers import legacy
 from .store import Store, StoreError
 
-READONLY = ("status", "saves", "log", "profile", "gallery")
-ACTIONS = ("new", "next", "choose", "save", "load", "saves", "rewind", "log", "status", "profile", "persona", "gallery", "click")
+READONLY = ("status", "saves", "log", "profile", "gallery", "look")
+ACTIONS = ("new", "next", "choose", "save", "load", "saves", "rewind", "log", "status", "profile", "persona", "gallery", "click", "look")
 SLUG_OK = lambda s: bool(s) and "/" not in s and "\\" not in s and not s.startswith(".")
 
 
@@ -90,7 +90,7 @@ class Library(object):
         st = engine.new_state(story, h=h, mode=mode, hints=hints, lang=lang or S.profile.get("lang") or "zh")
         S.set_run(st)
         S.profile["stats"]["games"] = S.profile["stats"].get("games", 0) + 1
-        r = engine.advance(story, st, S.profile["s"], S.profile["seen"], n=0)
+        r = self._advance_clicks(story, S, st, 0, False)
         S.profile["stats"]["lines"] = S.profile["stats"].get("lines", 0) + len(r["lines"])
         self._decorate(story, S, st, r)
         return {"ok": True, "msg": "新游戏开始（第 %d 周目）" % S.profile["stats"]["games"], "state": r,
@@ -105,7 +105,9 @@ class Library(object):
         n = max(1, min(int(n or 20), 200))
         before_end = st.get("ended")
         st.pop("_click", None)          # 上一批的「可点」只在那一批有效（原作的点击也只在那一句上）
+        vis_before = engine._vis_brief(st["vis"])     # 读这一批之前画面是什么样（文本接口据此只在变化时报〔画面〕）
         r = self._advance_clicks(story, S, st, n, bool(skip_read))
+        r["vis_before"] = vis_before
         S.touch_run()
         S.profile["stats"]["lines"] = S.profile["stats"].get("lines", 0) + len(r["lines"])
         if r.get("choice") and not (st.get("_autosaved_at") == [st["scene"], st["pc"], st["turn"]]):
@@ -113,7 +115,10 @@ class Library(object):
             S.save_slot("auto", self._meta(story, st, "到选项自动存"))
         if r.get("cg_seen"):
             got = S.profile.setdefault("cg", [])
-            got.extend(c for c in dict.fromkeys(r["cg_seen"]) if c not in got)
+            new_cg = [c for c in dict.fromkeys(r["cg_seen"]) if c not in got]
+            if new_cg:
+                r["cg_new"] = new_cg                  # 这个 agent 第一次看到的 CG（img=1 时只给这些附图）
+            got.extend(new_cg)
         self._decorate(story, S, st, r)
         if st.get("ended") and not before_end:
             e = st["ended"]
@@ -200,6 +205,33 @@ class Library(object):
         S.profile["stats"]["clicks"] = S.profile["stats"].get("clicks", 0) + 1
         return {"ok": True, "msg": "点了一下。", "clicked": True, "where": engine.where(story, new)}
 
+    def _a_look(self, story, S, bg=None, **_):
+        """看一眼现在的画面（只读）：有 CG 就是 CG；否则是在场的立绘（每人一张，带位置和表情码）；
+        没人在场或 bg=1 时加上背景。返回要看的图的列表，文本接口给地址，MCP 直接给图。"""
+        st = self._need_run(S)
+        v = engine._vis_brief(st["vis"])
+        return {"ok": True, "vis": v, "look": screen_picks(v, with_bg=str(bg).lower() in ("1", "true", "yes")),
+                "where": engine.where(story, st)}
+
+    def image_path(self, slug, rel):
+        """书里的图的绝对路径；只认 assets/ 下面、真实存在、不越界的文件，否则 None。"""
+        if not rel or not SLUG_OK(slug) or not str(rel).startswith("assets/"):
+            return None
+        base = os.path.realpath(os.path.join(self.books_dir, slug, "assets"))
+        p = os.path.realpath(os.path.join(self.books_dir, slug, rel))
+        if not p.startswith(base + os.sep) or not os.path.isfile(p):
+            return None
+        return p
+
+    def has_images(self, slug):
+        """书里有没有图（决定〔画面〕行默认开不开）。"""
+        d = os.path.join(self.books_dir, slug, "assets")
+        try:
+            with os.scandir(d) as it:
+                return any(True for _ in it)
+        except OSError:
+            return False
+
     def _a_choose(self, story, S, i=None, reason="", **_):
         st = self._need_run(S)
         st.pop("_click", None)
@@ -244,7 +276,7 @@ class Library(object):
             st["pending"]["shown_at"] = time.time()
         S.set_run(st)
         S.profile["stats"]["loads"] = S.profile["stats"].get("loads", 0) + 1
-        r = engine.advance(story, st, S.profile["s"], S.profile["seen"], n=0)
+        r = self._advance_clicks(story, S, st, 0, False)
         self._decorate(story, S, st, r)
         return {"ok": True, "msg": "读档 %s" % slot, "meta": d.get("meta"), "state": r, "opts": st.get("opts"),
                 "recent": [dict(who=x["who"], text=x["text"]) for x in st.get("log", [])[-5:]]}
@@ -344,6 +376,28 @@ class Library(object):
                 "pending": bool(st.get("pending"))}
 
 
+def face_code(sp):
+    """立绘的表情码：文件名去掉角色名和扩展名（例 雫_中_02_01_01.png → 中_02_01_01）。
+    不是表情的名字，但同一个码就是同一张脸；配 look 看一眼就知道是什么表情。"""
+    b = os.path.splitext(os.path.basename(str(sp.get("img") or "")))[0]
+    nm = sp.get("name") or ""
+    if nm and b.startswith(nm):
+        b = b[len(nm):].lstrip("_- .")
+    return b
+
+
+def screen_picks(v, with_bg=False):
+    """一屏「值得看」的图：[(说明, 路径)]。CG 盖住立绘，所以有 CG 只给 CG。"""
+    v = v or {}
+    if v.get("cg"):
+        return [("CG", v["cg"])]
+    out = [("%s:%s(%s)" % (s.get("name", "?"), s.get("pos") or "center", face_code(s)), s["img"])
+           for s in v.get("sprites") or [] if s.get("img")]
+    if v.get("bg") and (with_bg or not out):
+        out.insert(0, ("bg", v["bg"]))
+    return out
+
+
 def has_clicks(story):
     """剧本里有没有可点的句子（say 上带 click 字段）；结果缓存在 story 上。"""
     v = getattr(story, "_gb_has_clicks", None)

package/galbook/tools.py

@@ -6,7 +6,7 @@
 import json
 
 from .play import Library  # noqa: F401  (类型提示用)
-from .web import render_text, restyle, HELP
+from .web import render_text, restyle, HELP, want_vis, image_picks
 from .i18n import msg
 from . import VERSION
 
@@ -25,7 +25,8 @@ TOOLS = [
     ("galbook_next", "next", "Read the next n lines; stops at a choice or ending. / 往下读", {
         "n": {"type": "integer", "minimum": 1, "maximum": 200, "description": "lines to read (default 20)"},
         "skip_read": {"type": "boolean", "description": "fast-forward lines you have already read"},
-        "img": {"type": "boolean", "description": "include background/sprite/CG names"}}),
+        "img": {"type": "boolean", "description": "attach images, but only for a CG you see for the first time and the ending screen / 只在第一次见到的 CG 和结局那屏附图"},
+        "vis": {"type": "boolean", "description": "one [screen] line when the picture changes (default: on if the book has images)"}}),
     ("galbook_choose", "choose", "Pick an option at a choice and say why. / 选选项并写理由", {
         "i": {"type": ["integer", "string"], "description": "option number from 1, or \"random\""},
         "reason": {"type": "string", "description": "one sentence: why your persona picks this"}}),
@@ -43,6 +44,8 @@ TOOLS = [
     ("galbook_gallery", "gallery", "Collection progress: endings, routes, CG, read ratio. / 收集进度", {}),
     ("galbook_profile", "profile", "Stats and human-likeness numbers. / 记录", {}),
     ("galbook_click", "click", "Click the screen. / 点一下画面", {}),
+    ("galbook_look", "look", "Look at the current screen: the CG, or each character on stage (position + face code), as images. / 看一眼现在的画面", {
+        "bg": {"type": "boolean", "description": "also include the background"}}),
 ]
 
 
@@ -63,19 +66,29 @@ def openai_tools():
 
 def call_tool(lib, name, args, default_book=None, default_agent=None, lang="zh", style="tool", lang_override=None):
     """执行一个工具，返回纯文本。style：提示里的下一步写成 tool（默认）/ cli / http 形式。"""
+    return call_tool_rich(lib, name, args, default_book, default_agent, lang, style, lang_override, with_images=False)[0]
+
+
+def call_tool_rich(lib, name, args, default_book=None, default_agent=None, lang="zh", style="tool", lang_override=None,
+                   with_images=True, max_side=1280):
+    """同 call_tool，另外返回要附的图：[(说明, mime, bytes)]（MCP 用 image content 直接发）。
+    只在 look、或 img=1 时「第一次见到的 CG / 结局那屏」才有图；转不了的图（SVG 等）在文本里给路径。"""
     spec = next((x for x in TOOLS if x[0] == name), None)
     if spec is None:
         raise ValueError("unknown tool %s" % name)
     args = dict(args or {})
     if name == "galbook_books":
-        return json.dumps(lib.books(), ensure_ascii=False, indent=1)
+        return json.dumps(lib.books(), ensure_ascii=False, indent=1), []
     if name == "galbook_help":
-        return HELP.get(lang, HELP["zh"]) % VERSION
+        return HELP.get(lang, HELP["zh"]) % VERSION, []
     book = args.pop("book", None) or default_book
     agent = args.pop("agent", None) or default_agent
     if not book or not agent:
         raise ValueError("需要 book 和 agent / book and agent are required")
-    img = bool(args.pop("img", False))
+    img = args.pop("img", False) in (True, 1, "1", "true")
+    vis = want_vis(lib, book, args.pop("vis", None))
+    if "bg" in args:
+        args["bg"] = "1" if args["bg"] in (True, "1", "true", 1) else "0"
     if "hints" in args:
         args["hints"] = "1" if args["hints"] in (True, "1", "true", 1) else "0"
     if args.pop("skip_read", False):
@@ -84,7 +97,21 @@ def call_tool(lib, name, args, default_book=None, default_agent=None, lang="zh",
     r = lib.act(book, agent, action, **args)
     run = lib.store.peek_run(book, agent) or {}
     lg = lang_override or ((r.get("opts") or run.get("opts") or {}).get("lang")) or lang
-    return restyle(render_text(r, action, img, book, agent, lg), book, agent, style)
+    text = restyle(render_text(r, action, img, book, agent, lg, vis=vis), book, agent, style)
+    images = []
+    if with_images and (img or action == "look"):
+        from .imaging import load_for_model
+        notes = []
+        for lb, rel in image_picks(r, action):
+            p = lib.image_path(book, rel)
+            mime, data = load_for_model(p, max_side) if p else (None, "找不到文件 / file not found")
+            if mime:
+                images.append((lb, mime, data))
+            else:
+                notes.append("（%s：%s → %s）" % (lb, data, rel))
+        if notes:
+            text += "\n".join(notes) + "\n"
+    return text, images
 
 
 def main(argv=None):
@@ -96,4 +123,4 @@ def main(argv=None):
     return 0
 
 
-__all__ = ["TOOLS", "mcp_tools", "openai_tools", "call_tool", "msg"]
+__all__ = ["TOOLS", "mcp_tools", "openai_tools", "call_tool", "call_tool_rich", "msg"]

package/galbook/web.py

@@ -12,17 +12,17 @@ import json
 import os
 import re
 import traceback
-from urllib.parse import parse_qs, unquote
+from urllib.parse import parse_qs, unquote, quote
 
 from . import engine, VERSION
 from .i18n import t, msg
-from .play import Library, ACTIONS
+from .play import Library, ACTIONS, face_code, screen_picks
 from .ir import StoryError
 from .store import StoreError
 
 HERE = os.path.dirname(os.path.abspath(__file__))
 ERRS = (engine.PlayError, StoryError, StoreError, ValueError)
-KW = ("n", "i", "steps", "slot", "note", "reason", "h", "mode", "hints", "lang", "text")
+KW = ("n", "i", "steps", "slot", "note", "reason", "h", "mode", "hints", "lang", "text", "bg")
 
 HELP = {"zh": """galbook —— 像人一样玩 galgame（%s）
 每个 agent 用自己的名字玩，各自的进度、存档、通关记录互不影响，可以很多个同时玩。
@@ -35,7 +35,10 @@ HELP = {"zh": """galbook —— 像人一样玩 galgame（%s）
         &mode=ironman        铁人模式：不能存读档和回溯，选了就认
         &hints=1             选项旁标「选过」「新内容」
         &lang=en             框架文字用英文
-  /play/t/<书>/<你的名字>?do=next&n=20              往下读 n 句（最多 200）；&skip=1 跳过读过的；&img=1 带画面
+  /play/t/<书>/<你的名字>?do=next&n=20              往下读 n 句（最多 200）；&skip=1 跳过读过的
+        画面一变就多一行〔画面〕bg=… | sp=名字:位置(表情码)（书里有图时默认开，&vis=0 关）；路径拼成 /b/<书>/<路径> 就是图
+        &img=1               只在「第一次见到的 CG」和「结局那一屏」附图（MCP 直接给图，这里给地址）
+  /play/t/<书>/<你的名字>?do=look                   看一眼现在的画面：CG，或在场每个人的立绘（&bg=1 连背景）
   /play/t/<书>/<你的名字>?do=choose&i=2&reason=…    选第 2 个，reason 写一句你为什么这么选（i=random 随机）
   /play/t/<书>/<你的名字>?do=save&slot=3&note=…     存档（quick 或 1-99；到选项时会自动存 auto）
   /play/t/<书>/<你的名字>?do=load&slot=3            读档（auto / quick / 1-99）
@@ -61,7 +64,11 @@ Plain-text API (GET, one action per request):
         &mode=ironman        no saving/loading/rewinding — choices are final
         &hints=1             mark options "picked before" / "new"
         &lang=en             English UI text
-  /play/t/<book>/<name>?do=next&n=20               read n lines (max 200); &skip=1 skip read lines; &img=1 show visuals
+  /play/t/<book>/<name>?do=next&n=20               read n lines (max 200); &skip=1 skip read lines
+        a [screen] bg=… | sp=name:pos(face code) line whenever the picture changes (on by default if the book has images; &vis=0 off);
+        an image URL is /b/<book>/<path>
+        &img=1               attach images only for a CG you see for the first time and for the ending screen
+  /play/t/<book>/<name>?do=look                    look at the current screen: the CG, or each character on stage (&bg=1 adds the background)
   /play/t/<book>/<name>?do=choose&i=2&reason=…     pick option 2 and say why (i=random for random)
   /play/t/<book>/<name>?do=save&slot=3&note=…      save (quick or 1-99; slot auto is written at every choice)
   /play/t/<book>/<name>?do=load&slot=3             load (auto / quick / 1-99)
@@ -142,12 +149,13 @@ class App(object):
         if do not in ACTIONS:
             raise engine.PlayError("do 只能是：" + " ".join(ACTIONS))
         img = str(q.get("img", "")) in ("1", "true")
+        vis = want_vis(self.lib, book, q.get("vis"))
         kw = self._kw(q)
         if do != "new":
             kw.pop("lang", None)
         r = self.lib.act(book, agent, do, **kw)
         lg = lang or ((r.get("opts") or {}).get("lang")) or self._run_lang(book, agent) or self.default_lang
-        return self._text(200, render_text(r, do, img, book, agent, lg))
+        return self._text(200, render_text(r, do, img, book, agent, lg, vis=vis))
 
     def _run_lang(self, book, agent):
         try:
@@ -170,20 +178,58 @@ class App(object):
             return 200, ct, f.read()
 
 
-def _img(p):
-    return os.path.splitext(os.path.basename(p))[0] if p else None
+def want_vis(lib, book, v):
+    """〔画面〕行开不开：显式 vis=1/0 优先；没说就看书里有没有图（没图的书不白占 token）。"""
+    if v not in (None, ""):
+        return str(v).lower() in ("1", "true", "yes", "on")
+    try:
+        return lib.has_images(book)
+    except Exception:  # noqa
+        return False
 
 
-def _vis_text(v, lang):
-    bits = []
+def _vsig(v):
+    v = v or {}
     if v.get("cg"):
-        bits.append(t(lang, "vis_cg") + _img(v["cg"]))
-    elif v.get("bg"):
-        bits.append(t(lang, "vis_bg") + _img(v["bg"]))
-    sp = [s.get("name", "") for s in v.get("sprites") or []]
+        return ("cg", v["cg"])
+    return ("bg", v.get("bg"), tuple((s.get("name"), s.get("img"), s.get("pos")) for s in v.get("sprites") or []))
+
+
+def vis_line(v, lang="zh"):
+    """〔画面〕bg=… | sp=雫:center(中_02_01_01),琥珀:right(…)；有 CG 时只写 cg（立绘被盖住）。路径拼 /b/<书>/<路径> 就是图。"""
+    v = v or {}
+    hd = "[screen] " if lang == "en" else "〔画面〕"
+    if v.get("cg"):
+        return hd + "cg=" + v["cg"]
+    bits = []
+    if v.get("bg"):
+        bits.append("bg=" + v["bg"])
+    sp = [s for s in v.get("sprites") or [] if s.get("img") or s.get("name")]
     if sp:
-        bits.append(t(lang, "vis_on") + t(lang, "sep").join(sp))
-    return "〔" + "｜".join(bits) + "〕" if bits else ""
+        bits.append("sp=" + ",".join("%s:%s(%s)" % (s.get("name", "?"), s.get("pos") or "center", face_code(s)) for s in sp))
+    return hd + (" | ".join(bits) if bits else ("(empty)" if lang == "en" else "（空）"))
+
+
+def img_url(book, path):
+    return "/b/%s/%s" % (quote(book, safe=""), quote(path, safe="/"))
+
+
+def image_picks(r, do, cap=4):
+    """这次该附哪些图：[(说明, 路径)]。do=look → 当前画面；img=1 时只在「第一次见到的 CG」和「结局那一屏」给。"""
+    if do == "look":
+        picks = list(r.get("look") or [])
+    else:
+        st = r.get("state") or {}
+        picks = [("CG（第一次）", c) for c in st.get("cg_new") or []]
+        e = st.get("ended") or {}
+        if e.get("kind") == "ending":
+            picks += [("结局：" + lb, p) for lb, p in screen_picks(st.get("vis"), with_bg=True)]
+    out, seen = [], set()
+    for lb, p in picks:
+        if p and p not in seen:
+            seen.add(p)
+            out.append((lb, p))
+    return out[:cap]
 
 
 def _say(x, lang="zh"):
@@ -208,8 +254,11 @@ def restyle(text, book, agent, style):
     return re.sub(r"(?<=[\s（(])&(\w+=)", r"\1", text)
 
 
-def render_text(r, do, img, book, agent, lang="zh"):
-    """把一次操作的结果写成给 agent 看的纯文本（一句一行，最省 token）。"""
+def render_text(r, do, img, book, agent, lang="zh", vis=None):
+    """把一次操作的结果写成给 agent 看的纯文本（一句一行，最省 token）。
+    vis：画面变了才加一行〔画面〕（None = 跟 img 走，兼容旧调用）；img：第一次见到的 CG / 结局那屏 / look 给图的地址。"""
+    if vis is None:
+        vis = bool(img)
     L = []
     base = "/play/t/%s/%s?do=" % (book, agent)
     st = r.get("state")
@@ -222,6 +271,11 @@ def render_text(r, do, img, book, agent, lang="zh"):
         L.append(t(lang, "you_chose", text=c["text"], i=c["i"], of=c.get("of") or "?"))
         L.append(t(lang, "cont", base=base))
         return "\n".join(L) + "\n"
+    if do == "look":
+        L.append(vis_line(r.get("vis"), lang))
+        for lb, p in image_picks(r, do):
+            L.append(("[image] %s %s" if lang == "en" else "〔图〕%s %s") % (lb, img_url(book, p)))
+        return "\n".join(L) + "\n"
     if do == "persona":
         p = r.get("persona") or ""
         L.append(t(lang, "persona_now", p=p) if p else t(lang, "persona_none", base=base))
@@ -275,18 +329,24 @@ def render_text(r, do, img, book, agent, lang="zh"):
     if st:
         w = st["where"]
         L.append(t(lang, "line_hdr", title=w.get("title", ""), turn=w.get("turn", 0)))
-        if img and not st["lines"]:
-            v = _vis_text(st.get("vis") or {}, lang)
-            if v:
-                L.append(v)
-        last_vis = None
+        prev = st.get("vis_before")
+        if vis and not st["lines"] and (prev is None or _vsig(st.get("vis")) != _vsig(prev)):
+            if prev is not None or _vsig(st.get("vis")) != _vsig({}):
+                L.append(vis_line(st.get("vis"), lang))
+            prev = st.get("vis")
         for ln in st["lines"]:
-            if img and ln.get("vis"):
-                v = _vis_text(ln["vis"], lang)
-                if v and v != last_vis:
-                    L.append(v)
-                    last_vis = v
+            v = ln.get("vis")
+            if vis and v is not None and (prev is None or _vsig(v) != _vsig(prev)):
+                if prev is not None or _vsig(v) != _vsig({}):
+                    L.append(vis_line(v, lang))
+                prev = v
             L.append(_say(ln, lang) + (" " + ln["mark"] if ln.get("mark") else ""))
+        if vis and st["lines"] and (st.get("ended") or st.get("choice")) and st.get("vis") is not None \
+                and _vsig(st["vis"]) != _vsig(prev):
+            L.append(vis_line(st["vis"], lang))              # 最后一句之后画面又变了（结局 CG 常这样）
+        if img:
+            for lb, p in image_picks(r, do):
+                L.append(("[image] %s %s" if lang == "en" else "〔图〕%s %s") % (lb, img_url(book, p)))
         if st.get("skipped"):
             L.append(t(lang, "skipped", n=st["skipped"]))
         for e in st.get("events") or []:

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "galbook · galgame",
-    "description": "Lets an agent read a visual novel and pick choices by itself. Adds 15 galbook_* tools."
+    "description": "Lets an agent read a visual novel and pick choices by itself. Adds 16 galbook_* tools."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "galbook · galgame",
-    "description": "让 agent 自己读剧本、点选项把 galgame 玩下去。装上之后会多出 15 个 galbook_* 工具。"
+    "description": "让 agent 自己读剧本、点选项把 galgame 玩下去。装上之后会多出 16 个 galbook_* 工具。"
   }
 }