dsh-origin-bridge 0.4.5 → 0.4.6

package/server.py

@@ -20,7 +20,7 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 import originlab  # noqa: E402
 
 SERVER_NAME = "origin-bridge"
-SERVER_VERSION = "0.4.5"
+SERVER_VERSION = "0.4.6"
 PROTOCOL = "2024-11-05"
 
 
@@ -192,13 +192,14 @@ TOOLS = [
     },
     {
         "name": "origin_export",
-        "description": "把图页导出为图片文件，并校验文件确实存在、够大、文件头正确（Origin 有静默失败的历史）。fmt: png/tif/jpg/svg/pdf/emf（tiff→tif、jpeg→jpg 会自动改写扩展名）。",
+        "description": "把图页导出为图片文件，并校验文件确实存在、够大、文件头正确（Origin 有静默失败的历史）。fmt: png/tif/jpg/svg/pdf/emf（tiff→tif、jpeg→jpg 会自动改写扩展名）。path 给绝对路径：中文、空格、长路径实测可用，未映射盘/UNC/把目录当文件名返回 bad_path，已存在但只读或被占用返回 target_locked（不覆盖）。文件名里的 # 会被 Origin 换成编号，桥认出后改名回你要的名字并在 warnings 里说明——那是成功，不是失败。",
         "inputSchema": {
             "type": "object",
             "properties": {
                 "graph": {"type": "string"},
                 "path": {"type": "string", "description": "输出文件绝对路径；省略则用图页名放到当前目录"},
-                "fmt": {"type": "string", "enum": ["png", "tif", "svg", "pdf", "emf"], "default": "png"},
+                "fmt": {"type": "string", "enum": ["png", "tif", "jpg", "jpeg", "svg", "pdf", "emf"],
+                        "default": "png"},
                 "width": {"type": "integer", "default": 1600},
             },
         },
@@ -207,7 +208,7 @@ TOOLS = [
     },
     {
         "name": "origin_save_project",
-        "description": "保存为可在 Origin 里继续编辑的 .opju 工程文件（不是图片快照）。省略 path 会自动命名。",
+        "description": "保存为可在 Origin 里继续编辑的 .opju 工程文件（不是图片快照）。省略 path 会自动命名。path 给绝对路径，中文/空格/长路径实测可用；未映射盘、UNC、把目录当文件名一律 bad_path，不会假装存好了。",
         "inputSchema": {
             "type": "object",
             "properties": {"path": {"type": "string"}},
@@ -235,7 +236,7 @@ TOOLS = [
     },
     {
         "name": "origin_figure",
-        "description": "主路径：一次调用完成 导入/写数 → 画图 → 轴标题 → 导出图片 → 保存可编辑 .opju。用户只想“把这份数据画成图并给我文件”时用它，不要拆成多步。返回里若有 warnings，说明图虽然画成了但可能不可读（例如线性横轴跨了几个数量级，点全挤在最左边）：把 next_actions 里的方案讲给用户让他选，不要自己擅自改轴。",
+        "description": "主路径：一次调用完成 导入/写数 → 画图 → 轴标题 → 导出图片 → 保存可编辑 .opju。用户只想“把这份数据画成图并给我文件”时用它，不要拆成多步。返回里若有 warnings，可能是两类：图不可读（例如线性横轴跨了几个数量级，点全挤在最左边）——把 next_actions 里的方案讲给用户让他选，不要自己擅自改轴；或是路径被代劳了（文件名里的 # 被 Origin 换成编号后改回、相对路径落到进程工作目录）——转达给用户即可，交付本身是成功的。",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -247,7 +248,8 @@ TOOLS = [
                 "title": {"type": "string"},
                 "x_title": {"type": "string"},
                 "y_title": {"type": "string"},
-                "fmt": {"type": "string", "enum": ["png", "tif", "svg", "pdf", "emf"], "default": "png"},
+                "fmt": {"type": "string", "enum": ["png", "tif", "jpg", "jpeg", "svg", "pdf", "emf"],
+                        "default": "png"},
                 "width": {"type": "integer", "default": 1600},
                 "output_dir": {"type": "string", "description": "交付目录：图片 + opju 都写到这。不给则只建图、不落盘"},
                 "export_path": {"type": "string"},
@@ -417,7 +419,8 @@ TOOLS = [
                 "title": {"type": "string"},
                 "plot_type": {"type": "string", "enum": ["line", "scatter", "line_symbol", "column"]},
                 "with_legend": {"type": "boolean", "default": True},
-                "fmt": {"type": "string", "enum": ["png", "tif", "svg", "pdf", "emf"], "default": "png"},
+                "fmt": {"type": "string", "enum": ["png", "tif", "jpg", "jpeg", "svg", "pdf", "emf"],
+                        "default": "png"},
                 "width": {"type": "integer", "default": 1600},
             },
             "required": ["name"],
@@ -604,7 +607,20 @@ def main():
                          "error": {"code": -32603, "message": "internal error: %s" % exc}}
         if reply is None:
             continue
-        stdout.write((json.dumps(reply, ensure_ascii=False, default=str) + "\n").encode("utf-8"))
+        # allow_nan=False is the last line of defence. A bare Infinity/NaN in a
+        # reply is not valid JSON, so a strict client (dsh) fails to parse the
+        # *entire* result rather than one field. If anything still slips through,
+        # answer with a clean JSON-RPC error instead of either killing the session
+        # or writing bytes no client can read.
+        try:
+            line = json.dumps(reply, ensure_ascii=False, default=str, allow_nan=False)
+        except ValueError as exc:
+            _log("reply was not strict JSON (%r) for id=%r" % (exc, reply.get("id")))
+            reply = {"jsonrpc": "2.0", "id": reply.get("id"),
+                     "error": {"code": -32603,
+                               "message": "internal error: 返回值含非 JSON 数值（%s）" % exc}}
+            line = json.dumps(reply, ensure_ascii=False, default=str)
+        stdout.write((line + "\n").encode("utf-8"))
         stdout.flush()
 
 

package/smoke_test.py

@@ -27,6 +27,21 @@ PY = sys.executable
 STARTED_AT = time.strftime("%Y-%m-%dT%H:%M:%S")
 
 
+class NonStrictJSON(ValueError):
+    """The server wrote bare Infinity/NaN/-Infinity.
+
+    Python's json accepts those, RFC 8259 does not: dsh's client would fail on the
+    whole response and the tool would look dead rather than slightly wrong. A test
+    harness that tolerates it hides a real protocol defect, so we reject it here.
+    """
+
+
+def strict_loads(text):
+    def _reject(const):
+        raise NonStrictJSON("非标准 JSON 常量: %s" % const)
+    return json.loads(text, parse_constant=_reject)
+
+
 class Rpc:
     def __init__(self, python, script):
         self.p = subprocess.Popen([python, "-u", script], cwd=HERE,
@@ -64,7 +79,11 @@ class Rpc:
             with self.lock:
                 for raw in self.lines:
                     try:
-                        msg = json.loads(raw)
+                        msg = strict_loads(raw)
+                    except NonStrictJSON:
+                        # A reply carrying bare Infinity/NaN parses in Python but not
+                        # in a strict client, so dsh would report the tool as dead.
+                        raise SystemExit("服务器写出了非法 JSON：%s" % raw[:160])
                     except ValueError:
                         continue
                     if msg.get("id") == mine:
@@ -82,7 +101,10 @@ class Rpc:
         blocks = res.get("content", [])
         text = "".join(c.get("text", "") for c in blocks if c.get("type") == "text")
         try:
-            payload = json.loads(text)
+            payload = strict_loads(text)
+        except NonStrictJSON as exc:
+            payload = {"ok": False, "code": "bad_payload",
+                       "message": "工具返回体不是合法 JSON（%s）：%s" % (exc, text[:300])}
         except ValueError:
             payload = {"ok": False, "code": "bad_payload", "message": text[:400]}
         payload["_isError"] = res.get("isError", False)

package/test_asciiio.py

@@ -82,6 +82,124 @@ d = load("i_bom_utf8.csv")
 check("BOM stripped from first name", d["columns"][0]["name"] == "波长", view(d))
 check("utf-8-sig reported", d["encoding"] == "utf-8-sig", d["encoding"])
 
+# ---------------------------------------------------------------- other encodings
+print()
+print("encodings a real instrument writes")
+
+d = load("j_utf16_bom.dat")
+check("utf-16 with BOM parses", [(c["name"], c["numeric_rows"]) for c in d["columns"]]
+      == [("X", 2), ("Y", 2)], view(d))
+check("utf-16 encoding named", d["encoding"] == "utf-16-le", d["encoding"])
+
+d = load("k_utf16_nobom.dat")
+check("utf-16 without BOM still parses", d["columns"][1]["values"] == [1.5, 2.5], d["columns"])
+check("the guess is admitted", "无 BOM" in d["encoding"], d["encoding"])
+
+d = load("l_cp1252_micro.dat")
+check("cp1252 µ survives", d["columns"][1]["units"] == "µs", view(d))
+check("not mojibaked into CJK", "祍" not in str(view(d)), view(d))
+check("cp1252 named", d["encoding"] == "cp1252", d["encoding"])
+
+d = load("m_cp1252_degree.dat")
+check("cp1252 ° survives", d["columns"][0]["units"] == "°C", view(d))
+check("° not read as 癈", "癈" not in str(view(d)), view(d))
+
+# the discriminator itself
+check("paired high bytes read as GBK",
+      all(r % 2 == 0 for r in asciiio.high_byte_runs("温度\t电导".encode("gbk"))),
+      asciiio.high_byte_runs("温度\t电导".encode("gbk")))
+check("single high bytes read as cp1252",
+      asciiio.high_byte_runs("T/°C".encode("cp1252")) == [1],
+      asciiio.high_byte_runs("T/°C".encode("cp1252")))
+check("gbk is not first when singles appear",
+      asciiio.candidate_encodings("T/°C".encode("cp1252")).index("cp1252")
+      < asciiio.candidate_encodings("T/°C".encode("cp1252")).index("gb18030"),
+      asciiio.candidate_encodings("T/°C".encode("cp1252")))
+
+# ------------------------------------------------------------ decorated numbers
+print()
+print("decorated numbers, unwrapped and reported")
+
+d = load("n_detection_limit.dat")
+check("detection limits become their bound", d["columns"][1]["values"] == [0.001, 0.5, 1e6],
+      d["columns"][1]["values"])
+check("and say so", any("检测限" in w for w in d["warnings"]), d["warnings"])
+
+d = load("o_plusminus.dat")
+check("mean±sd takes the mean", d["columns"][1]["values"] == [2.5, 3.5], d["columns"][1]["values"])
+check("both spellings of +/-", any("± 写法" in w for w in d["warnings"]), d["warnings"])
+
+d = load("p_unit_in_cell.dat")
+check("unit in the cell does not kill the column",
+      d["columns"][1]["values"] == [25.0, 30.0], d["columns"][1]["values"])
+check("and is reported", any("单位写在同一格" in w for w in d["warnings"]), d["warnings"])
+
+d = load("q_thousands.csv")
+check("quoted thousands stay one column", [c["name"] for c in d["columns"]] == ["time", "signal"],
+      view(d))
+check("and keep their value", d["columns"][1]["values"] == [1234.5, 2345.6],
+      d["columns"][1]["values"])
+check("thousands reported", any("千分位" in w for w in d["warnings"]), d["warnings"])
+
+d = load("r_decimal_comma.txt")
+check("European file sniffs ';'", d["delimiter"] == ";", d["delimiter"])
+check("header split on the right delimiter",
+      [c["name"] for c in d["columns"]] == ["Zeit", "Signal"], view(d))
+check("comma decimal parsed", d["columns"][1]["values"] == [1.5, 2.5], d["columns"][1]["values"])
+check("decimal comma reported", any("小数点" in w for w in d["warnings"]), d["warnings"])
+
+d = load("s_star_flag.dat")
+check("star-flagged points keep their number",
+      d["columns"][1]["values"] == [2.5, 3.5], d["columns"][1]["values"])
+check("flag reported", any("标记的值" in w for w in d["warnings"]), d["warnings"])
+
+d = load("t_paren_negative.dat")
+check("parenthesised negative goes negative",
+      d["columns"][1]["values"] == [-500.0, 250.0], d["columns"][1]["values"])
+check("paren reported", any("括号表示负数" in w for w in d["warnings"]), d["warnings"])
+
+d = load("u_overflow.dat")
+check("overflowed cell becomes missing", d["columns"][1]["values"] == [None, 1.2e308],
+      d["columns"][1]["values"])
+check("overflow reported", any("超出浮点范围" in w for w in d["warnings"]), d["warnings"])
+check("nothing infinite escapes the parser",
+      all(v is None or (v == v and abs(v) != float("inf"))
+          for c in d["columns"] for v in c["values"]), d["columns"])
+
+d = load("v_row_labels.dat")
+check("row-label column skipped", [c["name"] for c in d["columns"]] == ["V", "I"], view(d))
+check("and explained as text", any("文本" in w for w in d["warnings"]), d["warnings"])
+
+# cell_number on its own, so a regression in one shape is not hidden by a file
+print()
+print("cell_number shapes")
+for text, want, kind in (
+        ("1.5", 1.5, None), ("1.5D+03", 1500.0, None), (".5", 0.5, None),
+        ("NA", None, None), ("--", None, None), ("#N/A", None, None),
+        ("<0.001", 0.001, "检测限"), ("≥ 2.5", 2.5, "检测限"), (">1e6", 1e6, "检测限"),
+        ("2.5±0.1", 2.5, "不确定度"), ("2.5 +/- 0.1", 2.5, "不确定度"),
+        ("25 mV", 25.0, "带单位的数"), ("1,234.5", 1234.5, "千分位"),
+        ("2.5*", 2.5, "标记后缀"), ("(500)", -500.0, "括号负数"),
+        ("1e400", None, "溢出"), ("Infinity", None, "溢出"),
+        ("0,5", None, None), ("0,5;1,5", None, None), ("text", None, None)):
+    got, got_kind = asciiio.cell_number(text)
+    check("cell %r" % text, got == want and got_kind == kind, (got, got_kind))
+check("cell '0,5' with decimal_comma", asciiio.cell_number("0,5", decimal_comma=True) == (0.5, "小数逗号"),
+      asciiio.cell_number("0,5", decimal_comma=True))
+check("cell '\"2,5\"' quoted", asciiio.cell_number('"2,5"', decimal_comma=True) == (2.5, "小数逗号"),
+      asciiio.cell_number('"2,5"', decimal_comma=True))
+check("cell '2.5 3.5' is two numbers, not a unit",
+      asciiio.cell_number("2.5 3.5") == (2.5, "一格两个数"), asciiio.cell_number("2.5 3.5"))
+check("cell '25 mV' stays a unit",
+      asciiio.cell_number("25 mV") == (25.0, "带单位的数"), asciiio.cell_number("25 mV"))
+
+# a mis-split column has to say so instead of quietly dropping every second value
+d = load("w_two_numbers_cell.csv")
+check("two numbers in one cell are reported", any("挤了两个数" in w for w in d["warnings"]),
+      d["warnings"])
+check("the first number of each cell survives",
+      d["columns"][1]["values"] == [2.5, 4.0], d["columns"][1]["values"])
+
 print()
 if fails:
     print("FAILED (%d): %s" % (len(fails), ", ".join(fails)))

package/test_json_safety.py

@@ -0,0 +1,103 @@
+"""Offline checks that the bridge can never emit non-standard JSON.
+
+json.dumps writes a bare Infinity / NaN by default, which RFC 8259 does not allow:
+a strict client (dsh, JS JSON.parse) fails on the whole response, so one overflowed
+number looks like "the bridge is dead". Two guards, both checked here.
+"""
+
+import json
+import math
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import originlab as ol  # noqa: E402
+
+PASSED = 0
+FAILED = []
+
+
+def ok(label, cond, detail=""):
+    global PASSED
+    if cond:
+        PASSED += 1
+    else:
+        FAILED.append("%s %s" % (label, detail))
+    print("%s %s%s" % ("PASS" if cond else "FAIL", label, (" | " + str(detail)[:90]) if detail else ""))
+
+
+INF = float("inf")
+
+
+def strict(text):
+    """Parse the way a JS client would: no Infinity, no NaN."""
+    return json.loads(text, parse_constant=lambda c: (_ for _ in ()).throw(ValueError(c)))
+
+
+def main():
+    # ------------------------------------------------------- sanitize() mapping
+    ok("inf -> None", ol.sanitize(INF) is None, ol.sanitize(INF))
+    ok("-inf -> None", ol.sanitize(-INF) is None)
+    ok("nan -> None", ol.sanitize(float("nan")) is None)
+    ok("missing sentinel -> None", ol.sanitize(ol.MISSING_SENTINEL) is None)
+    ok("big finite stays", ol.sanitize(1.7976931348623157e308) == 1.7976931348623157e308)
+    ok("zero stays", ol.sanitize(0.0) == 0.0)
+    ok("int stays", ol.sanitize(42) == 42)
+    ok("string stays", ol.sanitize("ok") == "ok")
+    nested = ol.sanitize({"a": [1.0, INF, {"b": -INF, "c": float("nan")}], "d": "x"})
+    ok("nested cleaned",
+       json.dumps(nested, allow_nan=False) == '{"a": [1.0, null, {"b": null, "c": null}], "d": "x"}',
+       nested)
+    ok("tuple cleaned", ol.sanitize((INF, 1.0)) == [None, 1.0])
+
+    # ------------------------------------------------------- the reply guard
+    # Simulate a handler that forgot to sanitize. The child server must still never
+    # write bytes a strict parser rejects, and must not die on the way.
+    import subprocess
+
+    try:
+        json.dumps({"value": math.inf}, allow_nan=False)
+        raised = False
+    except ValueError:
+        raised = True
+    ok("allow_nan=False really rejects Infinity", raised)
+
+    child = (
+        "import io, json, math, os, sys\n"
+        "sys.path.insert(0, os.environ['BRIDGE_DIR'])\n"
+        "import server\n"
+        "server._handle = lambda msg: {'jsonrpc': '2.0', 'id': msg.get('id'),\n"
+        "                               'result': {'value': math.inf}}\n"
+        "req = json.dumps({'jsonrpc': '2.0', 'id': 7, 'method': 'tools/list'}) + '\\n'\n"
+        "sys.stdin = io.TextIOWrapper(io.BytesIO(req.encode('utf-8')), encoding='utf-8')\n"
+        "sys.exit(server.main() or 0)\n"
+    )
+    env = dict(os.environ, BRIDGE_DIR=os.path.dirname(os.path.abspath(__file__)),
+               PYTHONIOENCODING="utf-8")
+    proc = subprocess.run([sys.executable, "-c", child], capture_output=True, env=env, timeout=120)
+    written = proc.stdout.decode("utf-8", "replace")
+    ok("child exited cleanly", proc.returncode == 0,
+       (proc.stderr.decode("utf-8", "replace") or "")[:160])
+    ok("guard logged why it downgraded", b"not strict JSON" in proc.stderr,
+       proc.stderr.decode("utf-8", "replace")[-160:])
+    ok("poisoned reply produced exactly one line", written.count("\n") == 1, repr(written[:160]))
+    ok("no bare Infinity on the wire", "Infinity" not in written, written[:160])
+    payload = {}
+    try:
+        payload = strict(written)
+        ok("client still gets a parseable answer", True)
+    except ValueError as exc:
+        ok("client still gets a parseable answer", False, "%s | %s" % (exc, written[:160]))
+    ok("answered with a JSON-RPC error", payload.get("error", {}).get("code") == -32603, payload)
+    ok("error keeps the request id", payload.get("id") == 7, payload)
+
+    print("\n%d/%d json-safety checks passed" % (PASSED, PASSED + len(FAILED)))
+    if FAILED:
+        for f in FAILED:
+            print("  FAILED:", f)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/test_paths.py

@@ -0,0 +1,142 @@
+"""Offline checks for the export/save target-path helpers (no Origin needed).
+
+Everything here was measured against the live bridge first (2026-10-12): Origin's
+export filter rewrites '#' into a numbering digit, Win32 strips trailing spaces
+and dots out of path components, and a path with no real filename used to turn
+into a dotfile named ".png" inside the plugin's own install folder.
+"""
+
+import os
+import shutil
+import stat
+import sys
+
+import originlab as ol
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+BASE = os.path.join(os.environ.get("TEMP", HERE), "origin_bridge_path_checks")
+
+PASSED = 0
+FAILED = []
+
+
+def ok(label, cond, detail=""):
+    global PASSED
+    if cond:
+        PASSED += 1
+    else:
+        FAILED.append("%s %s" % (label, detail))
+    print("%s %s%s" % ("PASS" if cond else "FAIL", label, (" | " + str(detail)) if detail else ""))
+
+
+def code_of(fn):
+    try:
+        fn()
+    except ol.OriginError as exc:
+        return exc.code
+    except Exception as exc:  # noqa: BLE001 — an unwrapped crash is itself the failure
+        return "UNWRAPPED:" + type(exc).__name__
+    return "no-raise"
+
+
+def fresh_dir(rel=""):
+    path = os.path.join(BASE, rel) if rel else BASE
+    if os.path.isdir(path):
+        for root, dirs, files in os.walk(path):
+            for name in files + dirs:
+                try:
+                    os.chmod(os.path.join(root, name), stat.S_IWRITE)
+                except OSError:
+                    pass
+        shutil.rmtree(path, ignore_errors=True)
+    os.makedirs(path, exist_ok=True)
+    return path
+
+
+def main():
+    fresh_dir()
+
+    # ---------------------------------------------------------------- naming
+    ok("blank path means default", ol._norm_target("   ", "png") == "")
+    ok("dot is a directory", code_of(lambda: ol._norm_target(".", "png")) == "bad_path")
+    ok("bare repo dir rejected",
+       code_of(lambda: ol._norm_target(HERE, "png")) == "bad_path")
+    ok("dotfile name rejected",
+       code_of(lambda: ol._norm_target(os.path.join(BASE, "  .png  "), "png")) == "bad_path")
+    ok("drive root rejected", code_of(lambda: ol._norm_target("C:\\", "png")) == "bad_path")
+    ok("trailing space stripped from component",
+       os.path.basename(os.path.dirname(
+           ol._norm_target(os.path.join(BASE, "trailsp ", "y.png")))) == "trailsp")
+    ok("trailing dot stripped from file",
+       ol._norm_target(os.path.join(BASE, "a.png.")) == os.path.join(BASE, "a.png"))
+    ok("fmt wins over the extension",
+       ol._norm_target(os.path.join(BASE, "x.tiff"), "tif") == os.path.join(BASE, "x.tif"))
+    ok("no fmt keeps the name",
+       ol._norm_target(os.path.join(BASE, "x.opju")) == os.path.join(BASE, "x.opju"))
+    ok("chinese preserved",
+       ol._norm_target(os.path.join(BASE, "中文测试", "图谱.png"))
+       == os.path.join(BASE, "中文测试", "图谱.png"))
+    ok("tilde expanded", os.path.expanduser("~") in ol._norm_target("~/a.png"))
+
+    # ------------------------------------------------------------- writability
+    ok("unmapped drive is bad_path",
+       code_of(lambda: ol._prepare_write(ol._norm_target(r"Q:\nope\x.png"))) == "bad_path")
+    ok("dead UNC host is bad_path",
+       code_of(lambda: ol._prepare_write(ol._norm_target(r"\\nope-not-real\x.png"))) == "bad_path")
+    adir = fresh_dir("adir")
+    ok("directory target is bad_path", code_of(lambda: ol._prepare_write(adir)) == "bad_path")
+    ro = os.path.join(fresh_dir("ro"), "locked.png")
+    with open(ro, "wb") as fh:
+        fh.write(b"marker")
+    os.chmod(ro, 0o444)
+    ok("read-only target is target_locked",
+       code_of(lambda: ol._prepare_write(ro)) == "target_locked")
+    ok("read-only file untouched", open(ro, "rb").read() == b"marker")
+    os.chmod(ro, 0o666)
+    ok("writable existing passes", code_of(lambda: ol._prepare_write(ro)) == "no-raise")
+    deep = os.path.join(BASE, "made", "by", "us")
+    ol._prepare_write(os.path.join(deep, "x.png"))
+    ok("missing dirs get created", os.path.isdir(deep))
+
+    # -------------------------------------------------- Origin's '#' rewriting
+    real = os.path.join(BASE, "100%_a1b[1].png")
+    want = os.path.join(BASE, "100%_a#b[1].png")
+    with open(real, "wb") as fh:
+        fh.write(b"PNGDATA")
+    got, note = ol._written_or_mangled(want)
+    ok("# result renamed back to what was asked", got == want and os.path.isfile(want))
+    ok("mangled sibling is gone", not os.path.exists(real))
+    ok("warning explains the filter", bool(note) and "滤镜" in note, note)
+    two_real = os.path.join(BASE, "graph01final02.png")
+    two_want = os.path.join(BASE, "graph##final###.png")
+    with open(two_real, "wb") as fh:
+        fh.write(b"PNGDATA")
+    got2, _n2 = ol._written_or_mangled(two_want)
+    ok("multi-digit # runs handled", got2 == two_want and os.path.isfile(two_want))
+    amb = fresh_dir("amb")
+    for name in ("g1.png", "g2.png"):
+        with open(os.path.join(amb, name), "wb") as fh:
+            fh.write(b"x")
+    got3, _n3 = ol._written_or_mangled(os.path.join(amb, "g#.png"))
+    ok("ambiguous match is not guessed", got3 is None)
+    ok("plain missing file stays a failure",
+       ol._written_or_mangled(os.path.join(BASE, "never.png")) == (None, None))
+
+    # ------------------------------------------------------------ CWD litter
+    before = set(os.listdir(HERE))
+    ok("relative path warns", bool(ol._rel_note("out.png")))
+    ok("absolute path silent", ol._rel_note(os.path.join(BASE, "a.png")) is None)
+    ok("blank path silent", ol._rel_note("   ") is None)
+    ok("no file written into the package dir by these checks",
+       set(os.listdir(HERE)) == before, sorted(set(os.listdir(HERE)) - before))
+
+    print("\n%d/%d path checks passed" % (PASSED, PASSED + len(FAILED)))
+    if FAILED:
+        for f in FAILED:
+            print("  FAILED:", f)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())