dimine-python-sdk 0.2.6__py3-none-any.whl → 0.2.8__py3-none-any.whl

dimine_python_sdk/__init__.py

@@ -4,7 +4,7 @@ from pathlib import Path
 from typing import Any
 
 DOCS_PATH = Path(__file__).parent / "docs"
-__VERSION__ = "0.2.6"  # 由 build.bat 中的 generate_version.py 自动更新
+__VERSION__ = "0.2.8"  # 由 build.bat 中的 generate_version.py 自动更新
 
 
 _LAZY_IMPORTS: dict[str, Any] = {}

dimine_python_sdk/cli/__init__.py

@@ -36,19 +36,50 @@
     dimine datatable-set --file PATH --index INT --field NAME --value VAL
     dimine convert-file --source PATH --target PATH [--overwrite BOOL]
     dimine laneway-tunnel --type INT --width FLOAT [--center-lines x,y,z;x,y,z;...] [--height FLOAT] [--width-up FLOAT] [--close] [--connectivity] [--method INT] [--no-import]
+    dimine start [--home PATH] [--wait SECONDS]
 
 全局选项：
     --format [json|text]  输出格式（默认: json）
 """
 
 import argparse
+import gettext
 import sys
 
+# ---------------------------------------------------------------------------
+# 短路 gettext：argparse 在 ArgumentParser.__init__ 里固定做 3 次翻译
+# （positional arguments / options / show this help message and exit），
+# 每次 gettext.find() 都会遍历 locale 目录做 os.path.exists。本 CLI 会创建
+# ~37 个 parser，合计 110 次翻译、约 440 次 stat，在慢盘/杀软环境下可占
+# build_parser 总耗时的 90% 以上（实测 300ms+ → 8ms）。
+#
+# 本 CLI 没有随包分发 .mo 翻译目录，翻译结果恒等于原文；仅当确实存在
+# messages.mo 时才回退到真实实现，保证将来若补翻译文件不会静默失效。
+# ---------------------------------------------------------------------------
+if gettext.find("messages") is None:
+    _real_find = gettext.find
+    _find_cache: dict = {}
+
+    def _cached_find(*args, **kwargs):
+        """按参数缓存 gettext.find，避免重复探测文件系统。"""
+        key = (args, tuple(sorted(kwargs.items())))
+        if key not in _find_cache:
+            _find_cache[key] = _real_find(*args, **kwargs)
+        return _find_cache[key]
+
+    gettext.find = _cached_find
+    # argparse 模块级绑定了 `from gettext import gettext as _, ngettext`，
+    # 须直接替换其命名空间中的引用才生效。
+    argparse._ = lambda message: message
+    argparse.ngettext = lambda singular, plural, n: singular if n == 1 else plural
+
 # Windows 控制台默认使用 GBK，强制改为 UTF-8 避免中文乱码
 if sys.platform == "win32":
     sys.stdout.reconfigure(encoding="utf-8")
     sys.stderr.reconfigure(encoding="utf-8")
 
+from dimine_python_sdk.cli.commands.app import register_commands as register_app_commands
+from dimine_python_sdk.cli.commands.app import COMMAND_HANDLERS as APP_HANDLERS
 from dimine_python_sdk.cli.commands.camera import register_commands as register_camera_commands
 from dimine_python_sdk.cli.commands.camera import COMMAND_HANDLERS as CAMERA_HANDLERS
 from dimine_python_sdk.cli.commands.text import register_commands as register_text_commands
@@ -71,6 +102,7 @@ from dimine_python_sdk.cli.commands.layer import register_commands as register_l
 from dimine_python_sdk.cli.commands.layer import COMMAND_HANDLERS as LAYER_HANDLERS
 
 ALL_HANDLERS = {}
+ALL_HANDLERS.update(APP_HANDLERS)
 ALL_HANDLERS.update(ENTITY_HANDLERS)
 ALL_HANDLERS.update(FILE_HANDLERS)
 ALL_HANDLERS.update(LAYER_HANDLERS)
@@ -96,6 +128,7 @@ def build_parser() -> argparse.ArgumentParser:
     sub = parser.add_subparsers(dest="command", help="子命令")
 
     register_entity_commands(sub, format_parent)
+    register_app_commands(sub, format_parent)
     register_file_commands(sub, format_parent)
     register_layer_commands(sub, format_parent)
     register_feature_commands(sub, format_parent)

dimine_python_sdk/cli/commands/app.py

@@ -0,0 +1,318 @@
+"""Dimine 应用进程相关 CLI 命令（本地进程操作，无需 Dimine 已运行）。
+
+本命令从 DIMINE_HOME 定位 Dimine.exe 并在后台分离启动，用于在执行
+file-tree / file-open 等远程命令前先把 Dimine 桌面程序拉起来。
+"""
+
+import asyncio
+import csv
+import io
+import logging
+import os
+import subprocess
+import time
+
+from dimine_python_sdk.cli.utils._utils import output_error, output_result
+
+logger = logging.getLogger(__name__)
+
+_DIMINE_EXE = "Dimine.exe"
+# 与 conn_client.open_client() 默认地址保持一致（Dimine 内置 WebSocket 服务）
+_WS_URL = "ws://127.0.0.1:8000"
+
+
+# ==============================================================================
+# 进程辅助函数
+# ==============================================================================
+
+def _running_pids() -> list:
+    """返回当前正在运行的 Dimine.exe 进程 PID 列表（Windows）。"""
+    if os.name != "nt":
+        return []
+    try:
+        proc = subprocess.run(
+            ["tasklist", "/FI", f"IMAGENAME eq {_DIMINE_EXE}", "/FO", "CSV", "/NH"],
+            capture_output=True,
+            timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return []
+    text = proc.stdout.decode("utf-8", errors="replace")
+    pids = []
+    for row in csv.reader(io.StringIO(text)):
+        if len(row) >= 2 and row[0].strip().lower() == _DIMINE_EXE.lower():
+            try:
+                pids.append(int(row[1].strip()))
+            except ValueError:
+                pass
+    return pids
+
+
+def _launch(exe: str, home: str, uac_timeout: float | None = None) -> int | None:
+    """后台分离启动 Dimine.exe，返回 pid（提权路径未探测到 pid 时为 None）。
+
+    以 DIMINE_HOME 为工作目录，保证相对路径的 SysParameter / Parameter 等
+    资源能被正确找到；子进程独立于当前控制台运行，CLI 立即返回。
+
+    若 Dimine.exe 要求管理员权限（Popen 抛 WinError 740）而当前进程未提权，
+    自动改用 runas 动词触发一次 UAC 提权启动（见 _launch_elevated）。
+    uac_timeout：仅提权路径使用——等待用户在 UAC 上应答的最长秒数，超时抛
+    RuntimeError；None 表示不限时（可 Ctrl+C 中止）。
+    """
+    env = os.environ.copy()
+    env["DIMINE_HOME"] = home
+    kwargs = dict(
+        cwd=home,
+        env=env,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    if os.name == "nt":
+        kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.DETACHED_PROCESS
+    try:
+        proc = subprocess.Popen([exe], **kwargs)
+    except OSError as exc:
+        # WinError 740 = ERROR_ELEVATION_REQUIRED：目标 exe manifest 要求管理员权限。
+        if os.name == "nt" and getattr(exc, "winerror", None) == 740:
+            return _launch_elevated(exe, home, uac_timeout)
+        raise
+    logger.info("已后台启动 Dimine（pid=%s exe=%s）", proc.pid, exe)
+    return proc.pid
+
+
+def _launch_elevated(exe: str, home: str, timeout: float | None = None) -> int | None:
+    """通过 runas 动词触发 UAC 提权启动 Dimine.exe，返回探测到的 pid 或 None。
+
+    提权进程由系统（consent.exe 经 UAC 确认）独立创建，调用方拿不到其句柄，
+    故启动后轮询 tasklist 直至 Dimine.exe 出现以取得 pid。
+
+    ShellExecuteW(runas) 会同步阻塞到用户在 UAC 上应答，若主线程直接调用会
+    卡死在 C 函数里（Ctrl+C 无效）。因此改在守护线程中执行、主线程空闲轮询：
+    - Ctrl+C 随时可中止（进程退出会顺带取消那次未决的提权）；
+    - timeout>0 时，超过该秒数仍未获 UAC 应答则抛 RuntimeError；
+    - 用户点『否』/取消 UAC → RuntimeError（面向用户的中文提示）。
+
+    ShellExecute 子进程继承本进程环境变量，因此先把 DIMINE_HOME 临时写入
+    os.environ，确保目标进程能看到正确的资源目录。
+    """
+    if os.name != "nt":
+        raise RuntimeError("提权启动仅支持 Windows。")
+    import ctypes
+    import threading
+    from ctypes import wintypes
+
+    logger.warning(
+        "Dimine.exe 需要管理员权限，弹出 UAC 确认框以提权启动…"
+        + ("" if timeout is None else f"（请在 {timeout:g}s 内应答，超时自动中止）")
+    )
+
+    outcome: dict = {}
+
+    def _request() -> None:
+        """守护线程内调用 ShellExecuteW(runas)，结果写入 outcome。"""
+        had_home = "DIMINE_HOME" in os.environ
+        old_home = os.environ.get("DIMINE_HOME")
+        os.environ["DIMINE_HOME"] = home
+        try:
+            shell32 = ctypes.windll.shell32
+            shell_exec = shell32.ShellExecuteW
+            shell_exec.argtypes = [
+                wintypes.HWND,
+                wintypes.LPCWSTR,  # lpOperation = "runas"
+                wintypes.LPCWSTR,  # lpFile
+                wintypes.LPCWSTR,  # lpParameters
+                wintypes.LPCWSTR,  # lpDirectory
+                ctypes.c_int,      # nShowCmd
+            ]
+            shell_exec.restype = wintypes.HINSTANCE
+            # 第 6 参为工作目录（home），第 7 参 SW_SHOWNORMAL=1
+            outcome["ret"] = shell_exec(None, "runas", exe, "", home, 1)
+        except Exception as exc:  # noqa: BLE001 线程内兜底，避免调用悬空
+            outcome["exc"] = exc
+        finally:
+            if had_home:
+                os.environ["DIMINE_HOME"] = old_home
+            else:
+                os.environ.pop("DIMINE_HOME", None)
+
+    threading.Thread(target=_request, name="dimine-uac", daemon=True).start()
+
+    # 主线程空闲等待：Ctrl+C 可正常中断；timeout 内未应答则放弃（退出会取消提权）
+    start = time.monotonic()
+    while "ret" not in outcome and "exc" not in outcome:
+        if timeout is not None and time.monotonic() - start >= timeout:
+            raise RuntimeError(
+                f"在 {timeout:g}s 内未获 UAC 应答，{os.path.basename(exe)} 未启动。"
+                f"请重新运行本命令，并在弹出的 UAC 窗口选择『是』；"
+                f"或改为以管理员身份运行。"
+            )
+        time.sleep(0.2)
+    if "exc" in outcome:
+        raise outcome["exc"]
+
+    # ShellExecute 成功时返回 >32；失败返回 <=32 的 SE_ERR_*，UAC 被用户
+    # 拒绝时可能返回 ERROR_CANCELLED(1223)（数值 >32，需单独识别）。
+    SE_ERR_ACCESSDENIED = 5
+    ERROR_CANCELLED = 1223
+    ret = outcome.get("ret")
+    ret = int(ret) if ret else 0
+    if ret <= 32 or ret in (SE_ERR_ACCESSDENIED, ERROR_CANCELLED):
+        raise RuntimeError(
+            f"启动 {os.path.basename(exe)} 需要管理员权限，但 UAC 提权被取消或启动失败"
+            f"（ShellExecute 返回 {ret}）。请在弹出的 UAC 窗口选择『是』，"
+            f"或改为以管理员身份运行本命令。"
+        )
+
+    # 提权进程创建有一瞬延迟，轮询 tasklist 以取得新进程 pid
+    deadline = time.monotonic() + 10.0
+    while time.monotonic() < deadline:
+        pids = _running_pids()
+        if pids:
+            logger.info("已通过 UAC 提权启动 Dimine（pid=%s exe=%s）", pids[0], exe)
+            return pids[0]
+        time.sleep(0.2)
+    logger.info("已触发 UAC 提权启动 Dimine（exe=%s），暂未探测到 pid", exe)
+    return None
+
+
+# ==============================================================================
+# 远端就绪探测
+# ==============================================================================
+
+def _wait_ready(url: str, timeout: float) -> tuple:
+    """轮询 WebSocket 服务直至可连接或超时。
+
+    返回 (ready, waited_seconds)。握手成功即认为 Dimine 远端服务已就绪，
+    之后 file-tree / file-open 等远程命令即可直接使用。
+    """
+    start = time.monotonic()
+
+    async def _probe() -> bool:
+        import websockets
+        try:
+            ws = await asyncio.wait_for(
+                websockets.connect(url, close_timeout=1), timeout=2
+            )
+        except Exception:
+            return False
+        try:
+            await ws.close()
+        except Exception:
+            pass
+        return True
+
+    async def _poll() -> bool:
+        while True:
+            if await _probe():
+                return True
+            if time.monotonic() - start >= timeout:
+                return False
+            await asyncio.sleep(0.5)
+
+    ready = asyncio.run(_poll())
+    return ready, round(time.monotonic() - start, 1)
+
+
+# ==============================================================================
+# 命令实现
+# ==============================================================================
+
+def cmd_start(fmt: str, home: str | None = None, wait: float = 8.0) -> None:
+    """后台启动 Dimine（自动定位 DIMINE_HOME/Dimine.exe 并分离启动）。
+
+    - 已运行则跳过启动，仅报告当前实例，不结束任何旧进程。
+    - --wait N：整个启动阶段的总预算秒数（默认 8）——需要提权时等用户在 UAC
+      上应答、随后等远端 WebSocket 就绪，都计入这 N 秒。
+    - 提权场景下 N 秒内 UAC 一直未获应答视为启动失败，报错退出。
+    - --wait 0：不设预算也不等待就绪（启动后立即返回，旧行为）。
+    """
+    dimine_home = (home or os.environ.get("DIMINE_HOME") or "").strip()
+    if not dimine_home:
+        output_error("未检测到 DIMINE_HOME。请设置 DIMINE_HOME 环境变量指向 Dimine 安装目录，或传入 --home。", fmt)
+    dimine_home = os.path.abspath(dimine_home)
+    exe = os.path.join(dimine_home, _DIMINE_EXE)
+    if not os.path.isfile(exe):
+        output_error(f"在 DIMINE_HOME 下未找到 {_DIMINE_EXE}: {exe}", fmt)
+
+    budget = wait if (wait and wait > 0) else None
+    t0 = time.monotonic()
+
+    pids = _running_pids()
+    started_new, launched_pid = False, None
+    if pids:
+        logger.info("Dimine 已在运行（pid=%s），跳过启动", pids)
+    else:
+        try:
+            launched_pid = _launch(exe, dimine_home, uac_timeout=budget)
+        except OSError as exc:
+            # 非提权类的启动失败（权限/路径/占用等），转为友好报错而非原始 traceback
+            logger.error("启动 Dimine 失败: %s", exc)
+            output_error(f"启动 Dimine 失败: {exc}", fmt)
+        except RuntimeError as exc:
+            # 提权被取消 / UAC 超时等，_launch_elevated 已翻译为面向用户的文案
+            logger.error("启动 Dimine 失败: %s", exc)
+            output_error(str(exc), fmt)
+        started_new = True
+        pids = _running_pids() or ([launched_pid] if launched_pid else [])
+
+    remote_ready, waited = None, None
+    ready_budget = None
+    if budget is not None:
+        # 新启动的实例把启动耗时（含等待 UAC）计入预算；已运行的实例从新预算起算
+        ready_budget = wait if not started_new else max(0.0, wait - (time.monotonic() - t0))
+        if ready_budget > 0:
+            remote_ready, waited = _wait_ready(_WS_URL, ready_budget)
+
+    result = {
+        "success": True,
+        "started_new": started_new,
+        "pid": launched_pid if started_new else (pids[0] if pids else None),
+        "pids": pids,
+        "dimine_home": dimine_home,
+        "exe": exe,
+    }
+    if budget is not None:
+        result["wait_seconds"] = wait
+        if remote_ready is not None:
+            result["remote_ready"] = bool(remote_ready)
+            result["waited_seconds"] = waited
+
+    if started_new:
+        if launched_pid:
+            msg = f"已后台启动 Dimine: {exe}（pid={launched_pid}）"
+        else:
+            msg = f"已触发 UAC 提权启动 Dimine: {exe}（新进程 pid 暂未探测到）"
+    else:
+        msg = f"Dimine 已在运行（pid={pids}），跳过启动；本命令不会结束旧实例，如需重启请先在 Dimine 中退出"
+    if remote_ready is True:
+        msg += f"，远端服务 {_WS_URL} 已在 {waited}s 内就绪"
+    elif remote_ready is False:
+        msg += f"，远端服务在 {ready_budget:g}s 内未就绪，可能仍在启动或启动失败，可加大 --wait 重试"
+    result["message"] = msg
+
+    output_result(result, fmt)
+
+
+def register_commands(subparsers, format_parent) -> None:
+    """向 subparsers 注册 Dimine 应用进程相关子命令。"""
+    p = subparsers.add_parser(
+        "start",
+        parents=[format_parent],
+        help="后台启动 Dimine（自动定位 DIMINE_HOME/Dimine.exe）",
+    )
+    p.add_argument("--home", default=None, help="Dimine 安装目录（默认取 DIMINE_HOME 环境变量）")
+    p.add_argument(
+        "--wait",
+        type=float,
+        default=8.0,
+        help=(
+            "启动总预算秒数：提权启动时等 UAC 应答 + 之后等远端 WebSocket 就绪，"
+            "合计超过则报错/返回（默认 8；0=不等待就绪且不设预算）"
+        ),
+    )
+
+
+COMMAND_HANDLERS = {
+    "start": lambda args: cmd_start(args.format, args.home, args.wait),
+}

dimine_python_sdk/cli/commands/file.py

@@ -1,5 +1,8 @@
 """文件相关 CLI 命令。"""
 
+import logging
+import os
+
 from dimine_python_sdk.cli.utils._utils import (
     get_client,
     handle_sdk_error,
@@ -11,6 +14,8 @@ from dimine_python_sdk.cli.utils._utils import (
     run_cli_async,
 )
 
+logger = logging.getLogger(__name__)
+
 
 def cmd_file_tree(fmt: str) -> None:
     """获取当前场景中已打开的所有文件及每个文件的图层信息（需 Dimine 运行）。"""
@@ -81,7 +86,7 @@ def cmd_file_save(fmt: str, output_path: str, file_id: str | None) -> None:
 
 
 def cmd_file_open(fmt: str, path: str) -> None:
-    """在 Dimine 中打开文件（需 Dimine 运行）。如果文件已在 Dimine 中打开，先关闭再重新打开。"""
+    """在 Dimine 中打开文件（需 Dimine 运行）。同名文件已打开则先关闭再重开；打开 .dmo 前会把已打开的其它 .dmo 一并关闭。"""
     err = require_remote_sdk()
     if err:
         output_error(err, fmt)
@@ -91,13 +96,28 @@ def cmd_file_open(fmt: str, path: str) -> None:
     async def _run():
         client = await get_client()
 
+        # 先确认待打开的新文件存在，再考虑关闭已打开文件，避免误关旧文件后才发现打不开
+        if not os.path.isfile(file_path):
+            raise_or_exit(f"文件不存在: {file_path}", fmt)
+
+        # Dimine 同一时刻只能打开一个 .dmo（炮孔数据库）文件：打开 .dmo 前若已有
+        # .dmo 打开须先关闭，否则 open_file 会提示 "file already opened"。
+        is_dmo = str(file_path).lower().endswith(".dmo")
         # 检查是否有同名文件已打开，如果有则先关闭
         target_name = path
         opened_files = await client.get_files()
         for f in opened_files:
-            if f.name == target_name:
-                await client.close_file(f.id)
-                break
+            if is_dmo:
+                # DMO：关闭当前已打开的所有 .dmo 文件
+                if (f.name or "").lower().endswith(".dmo"):
+                    logger.info("file-open: 打开新 .dmo 前关闭已打开文件（id=%s name=%s）", f.id, f.name)
+                    await client.close_file(f.id)
+            else:
+                # 非 DMO：仅当同名文件已打开时先关闭再重新打开
+                if f.name == target_name:
+                    logger.info("file-open: 同名文件已打开，先关闭再重开（id=%s name=%s）", f.id, f.name)
+                    await client.close_file(f.id)
+                    break
 
         # 打开文件
         await client.open_file(file_path)

dimine_python_sdk/cli/commands/layer.py

@@ -70,8 +70,8 @@ def cmd_layer_create(fmt: str, name: str, file_id: str | None) -> None:
         handle_sdk_error(e, fmt, "创建图层失败")
 
 
-def cmd_layer_visibility(fmt: str, file_id: str, layer_name: str, action: str) -> None:
-    """设置图层显示/隐藏状态（需 Dimine 运行）。"""
+def cmd_layer_visibility(fmt: str, file_id: str, layer_names: list[str], action: str) -> None:
+    """设置图层显示/隐藏状态，支持一次操作多个图层（需 Dimine 运行）。"""
     err = require_remote_sdk()
     if err:
         output_error(err, fmt)
@@ -86,15 +86,15 @@ def cmd_layer_visibility(fmt: str, file_id: str, layer_name: str, action: str) -
 
     async def _run():
         client = await get_client()
-        await client.set_layer_visibility(
-            file_id=file_id,
-            layer_name=layer_name,
+        await client.set_layers_visibility(
+            layers=[{"file": file_id, "layer": name} for name in layer_names],
             action=valid_actions[action],
         )
         action_cn = {"show": "显示", "hide": "隐藏", "exclusive_show": "排他显示"}
         return {
             "success": True,
-            "message": f"已成功{action_cn.get(action, action)}图层 {layer_name}",
+            "layer_count": len(layer_names),
+            "message": f"已成功{action_cn.get(action, action)}图层 {'、'.join(layer_names)}",
         }
 
     try:
@@ -150,7 +150,8 @@ def register_commands(subparsers, format_parent) -> None:
 
     p = subparsers.add_parser("layer-visibility", parents=[format_parent], help="设置图层显示/隐藏状态")
     p.add_argument("--file-id", required=True, help="文件ID")
-    p.add_argument("--layer-name", required=True, help="图层名称")
+    p.add_argument("--layer-name", action="append", required=True, dest="layer_names",
+                   help="图层名称，可重复指定以批量操作")
     p.add_argument("--action", choices=["show", "hide", "exclusive_show"], default="show", help="操作类型（默认: show）")
 
 
@@ -158,5 +159,5 @@ COMMAND_HANDLERS = {
     "layers": lambda args: cmd_layers(args.format, args.file_id),
     "layer-create": lambda args: cmd_layer_create(args.format, args.name, args.file_id),
     "layer-delete": lambda args: cmd_layer_delete(args.format, args.name, args.file_id),
-    "layer-visibility": lambda args: cmd_layer_visibility(args.format, args.file_id, args.layer_name, args.action),
+    "layer-visibility": lambda args: cmd_layer_visibility(args.format, args.file_id, args.layer_names, args.action),
 }

dimine_python_sdk/conn/base_conn_client.py

@@ -14,6 +14,7 @@ from dimine_python_sdk.logger import logger
 from dimine_python_sdk.models.conn import ConnEvent, ConnRequest, ConnResponse,CommandType
 from dimine_python_sdk.models.errors import ResponseError
 
+
 @dataclass
 class BaseConnClient:
     model_config = {"arbitrary_types_allowed": True}
@@ -137,8 +138,7 @@ class BaseConnClient:
                 self.pending_requests.pop(request.request_id)
             raise e
         else:
-            result = await future
-            return result
+            return await future
         
     async def _send_command(self, command: CommandType, payload:Optional[Any]=None,  callback: Optional[Callable] = None)->ConnResponse:
         """发送请求并等待响应（内部方法，外部不应直接调用）"""

dimine_python_sdk/conn/conn_client.py

@@ -1,14 +1,15 @@
 
+from __future__ import annotations
+
 from contextlib import asynccontextmanager
 from pathlib import Path
 import shutil
 import tempfile
 from typing import Any, AsyncGenerator, Dict, List, Literal, Optional
-import numpy as np
 from dimine_python_sdk.conn.base_conn_client import BaseConnClient
 from dimine_python_sdk.models import FileInfo, ResponseStatus, CommandType,LayerInfo, FeatureInfo, SelectedItem, SelectedResult, SelectMode, VisibilityAction
 
-from dimine_python_sdk.models.types import GEOMETRY, Line, Point, Shell, TextInfo
+from dimine_python_sdk.models.types import TextInfo
 
 
 class ConnClient(BaseConnClient):
@@ -138,6 +139,12 @@ class ConnClient(BaseConnClient):
         threshold: int,
     ) -> bool:
         """判断单个几何体是否应走本地文件传输路径。"""
+        # 几何类型与 numpy 均为惰性导入：远程命令路径（file-tree/layers 等）不碰它们，
+        # 从而避免在导入期拉起 numpy。
+        import numpy as np
+
+        from dimine_python_sdk.models.geometry import Line, Point, Shell
+
         if file_transfer is True:
             return True
         if file_transfer is False:
@@ -181,6 +188,10 @@ class ConnClient(BaseConnClient):
 
     def _entity_type_for_file_transfer(self, geom: GEOMETRY) -> str:
         """为文件传输路径计算与 DMF 实体一致的 entity_type。"""
+        import numpy as np
+
+        from dimine_python_sdk.models.geometry import Line, Point, Shell
+
         if isinstance(geom, Point):
             return "point"
         if isinstance(geom, Line):
@@ -192,6 +203,10 @@ class ConnClient(BaseConnClient):
 
     def _insert_geometry_into_dmf(self, dmf, geom: GEOMETRY) -> None:
         """将几何体写入 DMF 内存模型（图层名为 ``"0"``）。"""
+        import numpy as np
+
+        from dimine_python_sdk.models.geometry import Line, Point, Shell
+
         name = geom.feature or "0"
         if isinstance(geom, Point):
             dmf.insert_point("0", geom.geometry, name=name)
@@ -264,6 +279,10 @@ class ConnClient(BaseConnClient):
             features: 获取哪些要素相关的模型
             with_geometry: 是否返回模型坐标信息，默认 False
         """
+        import numpy as np
+
+        from dimine_python_sdk.models.geometry import Line, Point, Shell
+
         # 先获取要素信息，
         all_features = await self.get_features(file_id)
 
@@ -409,6 +428,8 @@ class ConnClient(BaseConnClient):
         file_transfer_threshold: int = 10000,
     ) -> None:
         """创建或更新多个模型, 如果指定了file_id和layer_id, 则将模型添加到指定的文件及图层中"""
+        from dimine_python_sdk.models.geometry import Line, Point, Shell
+
         if isinstance(geometries, (Point, Line, Shell)):
             geometries = [geometries]
         update_geometries = [g for g in geometries if g.related]
@@ -604,27 +625,45 @@ class ConnClient(BaseConnClient):
         if response.status == ResponseStatus.FAIL:
             raise Exception(response.error)
 
-    async def set_layer_visibility(self, file_id: str, layer_name: str,
-                                    action: VisibilityAction | str = VisibilityAction.SHOW) -> None:
-        """设置图层显示/隐藏状态
+    async def set_layers_visibility(self, layers: List[Dict[str, str]],
+                                     action: VisibilityAction | str = VisibilityAction.SHOW) -> None:
+        """批量设置图层显示/隐藏状态
 
         Args:
-            file_id: 文件ID或文件名称
-            layer_name: 图层名称
+            layers: 要操作的图层列表，每个元素包含:
+                - file: 文件ID或文件名称
+                - layer: 图层名称
             action: 操作类型，可选 show(显示) | hide(隐藏) | exclusive_show(排他性显示)
 
         Raises:
             Exception: 操作失败时抛出异常
         """
+        if not layers:
+            return
         payload = {
-            "file": file_id,
-            "layer": layer_name,
+            "layers": layers,
             "action": str(action)
         }
         response = await self._send_command(CommandType.LAYER_VISIBILITY, payload)
         if response.status == ResponseStatus.FAIL:
             raise Exception(response.error)
 
+    async def set_layer_visibility(self, file_id: str, layer_name: str,
+                                    action: VisibilityAction | str = VisibilityAction.SHOW) -> None:
+        """设置单个图层的显示/隐藏状态
+
+        Args:
+            file_id: 文件ID或文件名称
+            layer_name: 图层名称
+            action: 操作类型，可选 show(显示) | hide(隐藏) | exclusive_show(排他性显示)
+
+        Raises:
+            Exception: 操作失败时抛出异常
+        """
+        await self.set_layers_visibility(
+            [{"file": file_id, "layer": layer_name}], action=action
+        )
+
     async def set_file_visibility(self, file_id: str,
                                    action: VisibilityAction | str = VisibilityAction.SHOW) -> None:
         """设置文件显示/隐藏状态

dimine_python_sdk/docs/examples/cli_usage.md

@@ -176,6 +176,7 @@ $ dimine geometry-create --geometries '[{"type":"line","file":"f-001","layer":"l
 $ dimine layer-visibility --file-id f-20240527-001 --layer-name 矿体 --action exclusive_show
 {
   "success": true,
+  "layer_count": 1,
   "message": "已成功排他显示图层 矿体"
 }
 ```
@@ -186,11 +187,25 @@ $ dimine layer-visibility --file-id f-20240527-001 --layer-name 矿体 --action
 $ dimine layer-visibility --file-id f-20240527-001 --layer-name 巷道 --action hide
 {
   "success": true,
+  "layer_count": 1,
   "message": "已成功隐藏图层 巷道"
 }
 ```
 
-### 3. 隐藏整个文件的所有图层
+### 3. 批量操作同一文件下的多个图层
+
+`--layer-name` 可重复指定，一次批量操作多个图层。
+
+```bash
+$ dimine layer-visibility --file-id f-20240527-001 --layer-name 矿体 --layer-name 巷道 --action exclusive_show
+{
+  "success": true,
+  "layer_count": 2,
+  "message": "已成功排他显示图层 矿体、巷道"
+}
+```
+
+### 4. 隐藏整个文件的所有图层
 
 ```bash
 $ dimine file-visibility --file-id f-20240527-001 --action hide