dsh-plugin-pscad-expert-vyma 1.0.0

package/tools/main.py

@@ -0,0 +1,1195 @@
+# -*- coding: utf-8 -*-
+"""main.py -- PSCAD 自动化标准工具库（DSH 插件主入口，v1.2.0）
+
+为 AI Agent（克隆体）提供操作 PSCAD(mhi.pscad 2.2.1 / PSCAD 5.0.0 Pro) 的
+标准化执行工具。本库从多轮真实仿真测试脚本（L13~L19 认证轮、R4 科研轮）
+中提取**验证成功**的代码逻辑重构而来。
+
+工程规范：
+1. **Agent 友好返回值**：所有公开函数以 try-except 包裹核心逻辑，绝不直接抛异常。
+   成功返回 ``{"status": "success", "data": {...}}``；
+   失败返回 ``{"status": "error", "message": "<原因 + traceback 摘要>"}``。
+2. **完整 Type Hints 与 Docstring**：每个函数声明参数类型并说明用途/返回结构。
+3. **动态配置持久化（v1.2.0）**：不再强依赖系统环境变量。路径配置保存在**工作区
+   本地文件 ``.pscad_config.json``**（默认当前工作目录），由 ``init_pscad_environment``
+   工具写入、``load_config`` 读取。环境变量 ``PSCAD_EXE_PATH``/``MHI_PYLIB_PATH``
+   仅作**降级回退**（未配置时自动回退，不崩溃）。
+4. **依赖懒加载（v1.2.0）**：**模块顶部绝不 import mhi.pscad**。真正的
+   ``import mhi.pscad`` 只在需要连接 PSCAD 的工具函数内部执行；导入前先
+   ``load_config()`` 动态把 pylib 路径加入 ``sys.path``。若配置缺失，**不抛异常**，
+   返回标准 Agent 错误字典引导 AI：先调用 ``init_pscad_environment`` 向用户索要路径。
+5. **状态持久化（v1.1.0）**：废弃跨进程失效的整数 ID 句柄。所有元件创建时被强制
+   赋予唯一 ``Name`` 标签；后续一切操作（连线/改参/桥接）通过遍历画布匹配
+   ``Name`` 属性精准寻址——脚本重启/跨进程后依然有效。
+
+关键经验（已固化为实现细节）：
+- PSCAD 启动必须带 ``/port:<port>`` 否则自动化服务不监听；崩溃后 Stop-Process 重启。
+- 一切布线坐标取自 ``c.ports()``；wire 段经过任何非目标端口坐标会自动连接（短路）。
+- datalabel 与端口连接须**同坐标（0 距离）**；同名 datalabel 无线互连（信号链标准做法）。
+- source3 的 F 与 F0 必须成对设置（否则系统 60Hz 运行）。
+- 工程同名重建会残留旧 build 消息——关键实验用唯一案例名。
+
+首次使用引导::
+
+    import os
+    import main as pat
+    r = pat.init_pscad_environment(
+        exe_path=os.environ['PSCAD_EXE_PATH'],      # PSCAD 可执行文件绝对路径
+        pylib_path=os.environ['MHI_PYLIB_PATH'])    # mhi.pscad 库目录绝对路径
+    r = pat.connect_and_load_project('my_case', folder='./cases')
+
+用法示例::
+
+    import main as pat
+    r = pat.connect_and_load_project('my_case', folder='./cases')
+    r = pat.add_and_configure_component('master:resistor', 600, 150,
+                                        params={'R': '100.0 [ohm]'}, name='R_new')
+    r = pat.connect_ports_safely('R_new', 'A', 'VrA_bus', 'B', bend='auto')
+    r = pat.configure_simulation(time_duration=0.5)
+    r = pat.run_simulation_and_monitor()
+    r = pat.read_output(channel='VrA', method='rms')
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import time
+import math
+import subprocess
+import traceback
+from typing import Any, Dict, List, Optional, Tuple
+
+# ---------------------------------------------------------------------------
+# 环境常量（端口可被环境变量覆盖；路径一律走本地配置，见 load_config）
+# ---------------------------------------------------------------------------
+CONFIG_FILE_NAME: str = '.pscad_config.json'   # 工作区本地配置文件
+PSCAD_PORT: int = int(os.environ.get("PSCAD_PORT", "54329"))
+DEFAULT_FOLDER: str = os.environ.get("PSCAD_WORK_DIR", "")  # 无硬编码；空则回退当前工作目录
+LAUNCH_WAIT_S: int = 60
+CONNECT_TIMEOUT_S: int = 20
+
+MISSING_CONFIG_MSG = (
+    '未找到 PSCAD 路径配置。请先使用 init_pscad_environment 工具进行设置。'
+)
+
+# 元件默认参数（实测合法值；调用方 params 覆盖默认值）
+COMPONENT_DEFAULTS: Dict[str, Dict[str, Any]] = {
+    'master:source_1': {'Cntrl': 0, 'Grnd': 1, 'Vm': '132.8 [kV]',
+                        'f': '50.0 [Hz]', 'R': '0.001 [ohm]', 'Ph': 0.0},
+    'master:source3': {'Vm': '230.0', 'F': '50.0 [Hz]', 'F0': '50.0 [Hz]',
+                       'Es': '230.0', 'MVA': '1000.0', 'View': 'SINGLE_LINE',
+                       'R1s': '0.1', 'L1p': '0.000001', 'Tc': '0.0'},
+    'master:newpi': {'len': '5.0E4', 'PU': 'R_XL_XC_OHM_', 'F': 50.0,
+                     'Rp': '3.433E-5', 'Xp': '4.188E-4', 'Bp': '274.4'},
+    'master:resistor': {'R': '1.0 [ohm]'},
+    'master:inductor': {'L': '0.001 [H]'},
+    'master:breaker1': {'RON': '0.01', 'ROFF': '1.0E6'},
+    'master:tbreak': {'TC': '1.0 [s]', 'TO': '0.0 [s]', 'REP': 0},
+    'master:const': {'Value': 0.0, 'Dim': 1},
+    'master:realpole': {'T': 0.1, 'G': 1.0, 'YO': 0.0},
+    'master:sumjct': {'A': 'DISABLE', 'B': 'DISABLE', 'F': 'SUBTRACT',
+                      'Dim': 1, 'DPath': 'REAL'},
+    'master:ground': {},
+    'master:ammeter': {},
+    'master:voltmetergnd': {},
+}
+
+# Name 自动生成的类型提示前缀（仅影响可读性，不改变功能）
+_NAME_HINT: Dict[str, str] = {
+    'resistor': 'R', 'inductor': 'L', 'source_1': 'S', 'source3': 'S3',
+    'ground': 'G', 'ammeter': 'AM', 'voltmetergnd': 'VM', 'const': 'K',
+    'mult': 'M', 'realpole': 'RP', 'sumjct': 'SJ', 'breaker1': 'BRK',
+    'tbreak': 'TB', 'datalabel': 'DL', 'pgb': 'PGB', 'newpi': 'PI',
+}
+
+# ---------------------------------------------------------------------------
+# 本地配置持久化（工作区 .pscad_config.json）
+# ---------------------------------------------------------------------------
+_config_cache: Optional[Dict[str, Any]] = None
+
+
+def _config_path() -> str:
+    """配置文件绝对路径（默认当前工作目录；可被环境变量 PSCAD_CONFIG 覆盖）。"""
+    base = os.environ.get('PSCAD_CONFIG_DIR') or os.getcwd()
+    return os.path.join(base, CONFIG_FILE_NAME)
+
+
+def load_config() -> Dict[str, Any]:
+    """加载工作区本地配置 ``.pscad_config.json``。
+
+    配置键：``pscad_exe_path``（PSCAD 可执行文件）、``mhi_pylib_path``
+    （mhi.pscad 库目录）、``pscad_port``（自动化端口，可选）、``saved_at``。
+
+    Returns:
+        配置字典；文件不存在或损坏时返回 ``{}``（**绝不抛异常**）。
+        结果会缓存，供懒加载与连接逻辑读取。
+    """
+    global _config_cache
+    if _config_cache is not None:
+        return _config_cache
+    try:
+        path = _config_path()
+        if os.path.isfile(path):
+            with open(path, encoding='utf-8') as fh:
+                _config_cache = json.load(fh)
+        else:
+            _config_cache = {}
+    except Exception:
+        _config_cache = {}
+    return _config_cache
+
+
+def save_config(exe_path: str, pylib_path: str) -> Dict[str, Any]:
+    """将 PSCAD 路径配置持久化到工作区 ``.pscad_config.json``。
+
+    Args:
+        exe_path: PSCAD 可执行文件绝对路径（如 '<PSCAD_INSTALL_DIR>/bin/win64/Pscad.exe'）。
+        pylib_path: mhi.pscad 库目录绝对路径（如 '<MHI_PYLIB_DIR>'）。
+
+    Returns:
+        success: data 含 ``config_path``、``pscad_exe_path``、``mhi_pylib_path``。
+        error: 写入失败（权限/路径异常）。
+    """
+    global _config_cache
+    try:
+        cfg = {
+            'pscad_exe_path': str(exe_path),
+            'mhi_pylib_path': str(pylib_path),
+            'pscad_port': PSCAD_PORT,
+            'saved_at': time.strftime('%Y-%m-%d %H:%M:%S'),
+        }
+        path = _config_path()
+        with open(path, 'w', encoding='utf-8') as fh:
+            json.dump(cfg, fh, ensure_ascii=False, indent=2)
+        _config_cache = cfg
+        return _ok({'config_path': path, 'pscad_exe_path': cfg['pscad_exe_path'],
+                    'mhi_pylib_path': cfg['mhi_pylib_path'],
+                    'pscad_port': cfg['pscad_port']})
+    except Exception as exc:
+        return _err(exc)
+
+
+def init_pscad_environment(exe_path: str, pylib_path: str) -> Dict[str, Any]:
+    """**初始化工具**：配置 PSCAD 运行环境并持久化（AI 首个应调用的工具）。
+
+    接收用户提供的 PSCAD 可执行文件路径与 mhi.pscad 库目录路径，写入工作区
+    ``.pscad_config.json``。配置持久化后，连接/启动类工具（connect_and_load_project、
+    restart_pscad 等）将自动懒加载该配置，无需任何系统环境变量。
+
+    Args:
+        exe_path: PSCAD 可执行文件绝对路径。
+        pylib_path: mhi.pscad 库目录绝对路径。
+
+    Returns:
+        success: data 含 ``config_path``、``pscad_exe_path``、``mhi_pylib_path``
+            （与 save_config 一致，另附 ``message`` 引导语）。
+        error: 写入失败。
+    """
+    try:
+        r = save_config(exe_path, pylib_path)
+        if r['status'] == 'success':
+            r['data']['message'] = ('PSCAD 环境配置已保存。后续连接将自动使用该配置，'
+                                    '可开始调用 connect_and_load_project 加载工程。')
+        return r
+    except Exception as exc:
+        return _err(exc)
+
+
+def _cfg_exe() -> Optional[str]:
+    """解析 PSCAD 可执行文件路径：本地配置优先，环境变量降级回退。"""
+    cfg = load_config()
+    exe = cfg.get('pscad_exe_path')
+    if not exe:
+        exe = os.environ.get('PSCAD_EXE_PATH')
+    return exe or None
+
+
+def _cfg_pylib() -> Optional[str]:
+    """解析 mhi.pscad 库目录：本地配置优先，环境变量降级回退。"""
+    cfg = load_config()
+    pylib = cfg.get('mhi_pylib_path')
+    if not pylib:
+        pylib = os.environ.get('MHI_PYLIB_PATH')
+    return pylib or None
+
+
+# ---------------------------------------------------------------------------
+# 模块级会话状态（单例；组件寻址一律走 Name，无内存注册表）
+# ---------------------------------------------------------------------------
+_pscad: Any = None            # mhi.pscad.PSCAD 连接（懒加载后赋值）
+_prj: Any = None              # 当前工程对象
+_prj_name: str = ''           # 当前工程名（唯一案例名）
+_prj_folder: str = DEFAULT_FOLDER
+_main: Any = None             # 当前画布（Main）
+_name_seq: List[int] = [1]    # Name 自动生成计数器
+_pgb_slot: List[int] = [0]    # pgb 自动布点计数器
+
+
+def _ok(data: Any) -> Dict[str, Any]:
+    """构造成功返回。"""
+    return {"status": "success", "data": data}
+
+
+def _err(exc: Union[Exception, str]) -> Dict[str, Any]:
+    """构造失败返回：捕获 traceback 摘要，绝不抛出。"""
+    if isinstance(exc, Exception):
+        tb = traceback.format_exc(limit=6)
+        msg = '%s: %s' % (type(exc).__name__, exc)
+        return {"status": "error", "message": msg, "trace": tb}
+    return {"status": "error", "message": str(exc)}
+
+
+def _import_mhi() -> Tuple[bool, str]:
+    """懒加载 mhi.pscad（仅在实际需要连接 PSCAD 时调用）。
+
+    流程：``load_config()`` 取 pylib 路径 → 动态加入 ``sys.path`` → import。
+    **配置缺失时不抛异常**，返回引导消息：先调用 ``init_pscad_environment``。
+    """
+    pylib = _cfg_pylib()
+    if not pylib:
+        return False, MISSING_CONFIG_MSG
+    try:
+        if 'mhi.pscad' not in sys.modules:
+            if pylib not in sys.path:
+                sys.path.insert(0, pylib)
+            import mhi.pscad  # noqa: F401
+        return True, ''
+    except Exception as exc:
+        return False, ('import mhi.pscad 失败（mhi_pylib_path=%s）: %s'
+                       % (pylib, exc))
+
+
+# ---------------------------------------------------------------------------
+# 组件寻址：遍历画布按 Name 属性匹配（跨进程持久）
+# ---------------------------------------------------------------------------
+def _name_of(component: Any) -> str:
+    """读取组件 Name 参数（不同元件可能返回空字符串）。"""
+    try:
+        p = component.parameters()
+        if isinstance(p, dict):
+            v = p.get('Name')
+            if v is None:
+                v = p.get('name')
+            return '' if v is None else str(v)
+    except Exception:
+        pass
+    return ''
+
+
+def _iter_components() -> List[Any]:
+    """尽力遍历当前画布上的全部组件（多级 fallback，失败返回空列表）。"""
+    if _main is None:
+        return []
+    try:
+        items = _main.find_all()
+        if items:
+            return list(items)
+    except Exception:
+        pass
+    try:
+        items = _main.find_all(Name='*')
+        if items:
+            return list(items)
+    except Exception:
+        pass
+    return []
+
+
+def _find_by_name(name: str) -> Optional[Any]:
+    """按 Name 属性精准寻址组件（遍历画布匹配）。
+
+    查找顺序：find_first 精确命中（校验 Name 参数）→ find_all 过滤 →
+    全画布遍历比对 Name 参数。找不到返回 None。
+    """
+    if _main is None or not name:
+        return None
+    try:
+        c = _main.find_first(name)
+        if c is not None and _name_of(c) == name:
+            return c
+    except Exception:
+        pass
+    try:
+        items = _main.find_all(Name=name)
+        if items:
+            for c in items:
+                if _name_of(c) == name:
+                    return c
+            return items[0]
+    except Exception:
+        pass
+    for c in _iter_components():
+        try:
+            if _name_of(c) == name:
+                return c
+        except Exception:
+            continue
+    return None
+
+
+def _collect_all_ports(exclude_names: Optional[set] = None) -> List[Tuple[int, int]]:
+    """收集画布上全部组件的端口坐标（供穿线检测；exclude_names 内组件除外）。"""
+    ports: List[Tuple[int, int]] = []
+    exclude_names = exclude_names or set()
+    for c in _iter_components():
+        try:
+            if _name_of(c) in exclude_names:
+                continue
+            for _k, v in c.ports().items():
+                ports.append(tuple(v[:2]))
+        except Exception:
+            continue
+    return ports
+
+
+def _gen_name(comp_type: str) -> str:
+    """生成唯一 Name 标签（如 R_1、AM_2）；显式 name 优先。"""
+    short = comp_type.split(':')[-1]
+    hint = _NAME_HINT.get(short, short[:2].upper())
+    n = _name_seq[0]
+    _name_seq[0] += 1
+    return '%s_%d' % (hint, n)
+
+
+# ---------------------------------------------------------------------------
+# 工具集 1：连接与工程加载（懒加载 mhi）
+# ---------------------------------------------------------------------------
+def connect_and_load_project(project_name: str,
+                             folder: Optional[str] = None,
+                             create_if_missing: bool = False,
+                             auto_launch: bool = True) -> Dict[str, Any]:
+    """启动/连接 PSCAD 实例，并加载（或新建）指定的 .pscx 模板工程。
+
+    首次调用会自动 ``load_config()`` 并懒加载 mhi.pscad；若未配置路径，
+    返回引导错误（不崩溃），请先调用 ``init_pscad_environment``。
+
+    Args:
+        project_name: 工程名（不带 .pscx 后缀）；将作为唯一案例名。
+        folder: 工程所在目录；None 时用 PSCAD_WORK_DIR 环境变量（默认值兜底）。
+        create_if_missing: 工程不存在时是否用 ``create_case`` 新建空工程。
+        auto_launch: 连接失败时是否自动拉起 PSCAD 进程。
+
+    Returns:
+        success: data 含 ``project``、``canvas``('Main')。
+        error: 未配置路径（引导消息）/连接/加载失败原因。
+    """
+    global _pscad, _prj, _prj_name, _prj_folder, _main
+    try:
+        ok, msg = _ensure_connected()
+        if not ok and auto_launch:
+            launched, msg2 = _launch_pscad()
+            if not launched:
+                return _err('%s；自动启动失败: %s' % (msg, msg2))
+            ok, msg = _ensure_connected()
+        if not ok:
+            return _err(msg)
+
+        folder = folder or (DEFAULT_FOLDER or os.getcwd())
+        _prj_folder = folder
+
+        prj = None
+        try:
+            prj = _pscad.project(project_name)
+        except Exception:
+            prj = None
+
+        if prj is None:
+            pscx = os.path.join(folder, project_name + '.pscx')
+            if os.path.isfile(pscx):
+                try:
+                    _pscad.load(pscx.replace('\\', '/'))
+                    prj = _pscad.project(project_name)
+                except Exception as exc:
+                    return _err('加载 %s 失败: %s' % (pscx, exc))
+
+        if prj is None and create_if_missing:
+            try:
+                _pscad.create_case(project_name, folder=folder)
+                prj = _pscad.project(project_name)
+            except Exception as exc:
+                return _err('create_case 失败: %s' % exc)
+
+        if prj is None:
+            return _err('工程 "%s" 未找到（folder=%s，未创建）'
+                        % (project_name, folder))
+
+        _prj = prj
+        _prj_name = project_name
+        try:
+            _main = prj.canvas('Main')
+        except Exception as exc:
+            _main = None
+            return _err('打开 Main 画布失败: %s' % exc)
+        return _ok({'project': project_name, 'canvas': 'Main'})
+    except Exception as exc:
+        return _err(exc)
+
+
+def _ensure_connected() -> Tuple[bool, str]:
+    """确保存在活的 mhi 连接（幂等；懒加载 mhi）。"""
+    global _pscad
+    ok, msg = _import_mhi()
+    if not ok:
+        return False, msg
+    if _pscad is not None:
+        try:
+            if _pscad.is_alive():
+                return True, ''
+        except Exception:
+            _pscad = None
+    try:
+        _pscad = mhi.pscad.connect(port=PSCAD_PORT, timeout=CONNECT_TIMEOUT_S)
+        return True, ''
+    except Exception as exc:
+        return False, '连接 PSCAD 失败(port=%d): %s' % (PSCAD_PORT, exc)
+
+
+def _launch_pscad() -> Tuple[bool, str]:
+    """拉起 PSCAD 进程并等待自动化端口就绪（崩溃恢复标准路径；懒加载 exe 路径）。"""
+    global _pscad
+    exe = _cfg_exe()
+    if not exe:
+        return False, MISSING_CONFIG_MSG
+    try:
+        subprocess.Popen([exe, '/startup:au',
+                          '/port:%d' % PSCAD_PORT, '/splash:false'])
+        deadline = time.time() + LAUNCH_WAIT_S
+        while time.time() < deadline:
+            time.sleep(2)
+            try:
+                _pscad = mhi.pscad.connect(port=PSCAD_PORT, timeout=5)
+                return True, ''
+            except Exception:
+                continue
+        return False, 'PSCAD 启动后 %ds 内端口未就绪' % LAUNCH_WAIT_S
+    except Exception as exc:
+        return False, str(exc)
+
+
+def restart_pscad() -> Dict[str, Any]:
+    """强制重启 PSCAD（自动化服务卡死/10054 崩溃后的恢复）。
+
+    终止现有 PSCAD 进程、重新启动并重连，然后重新加载当前工程。
+    """
+    global _pscad, _prj, _main
+    try:
+        if _pscad is not None:
+            try:
+                _pscad.close_connection()
+            except Exception:
+                pass
+            _pscad = None
+        subprocess.run(['taskkill', '/F', '/IM', 'Pscad.exe'],
+                       capture_output=True, timeout=30)
+        time.sleep(5)
+        ok, msg = _launch_pscad()
+        if not ok:
+            return _err(msg)
+        if _prj_name:
+            return connect_and_load_project(_prj_name, folder=_prj_folder)
+        return _ok({'restarted': True, 'project': None})
+    except Exception as exc:
+        return _err(exc)
+
+
+def close_connection() -> Dict[str, Any]:
+    """礼貌关闭自动化连接（脚本收尾时调用，避免占用端口）。"""
+    global _pscad, _prj, _main
+    try:
+        if _pscad is not None:
+            try:
+                _pscad.close_connection()
+            except Exception:
+                pass
+        _pscad = None
+        _prj = None
+        _main = None
+        return _ok({'closed': True})
+    except Exception as exc:
+        return _err(exc)
+
+
+# ---------------------------------------------------------------------------
+# 工具集 2：组件放置与配置（Name 标签寻址）
+# ---------------------------------------------------------------------------
+def _require_canvas() -> Optional[Dict[str, Any]]:
+    """前置检查：已加载工程且 Main 画布可用。失败返回 error dict，否则 None。"""
+    if _main is None:
+        return _err('尚未加载工程画布，请先调用 connect_and_load_project()')
+    return None
+
+
+def add_and_configure_component(comp_type: str, x: int, y: int,
+                                params: Optional[Dict[str, Any]] = None,
+                                orient: int = 0,
+                                name: Optional[str] = None,
+                                use_defaults: bool = True) -> Dict[str, Any]:
+    """在当前画布指定坐标放置元件并应用参数字典；**强制赋予唯一 Name 标签**。
+
+    Args:
+        comp_type: 元件定义名，如 'master:resistor'、'resistor'（自动补 master:）、
+            自定义组件 '工程名:DEFN'（须先 create_definition）。
+        x, y: 放置锚点坐标（mhi 网格坐标）。
+        params: 参数键值对（带单位字符串如 '100.0 [ohm]'）。
+        orient: 旋转取模 4（0=0° 1=90° 2=180° 3=270°）。
+        name: 显式 Name 标签；None 时自动生成唯一 Name（'R_1' 风格）。
+             **注意**：ammeter/voltmetergnd 的 Name 即输出通道名；datalabel 的
+             Name 即信号名——显式命名可同时服务于寻址与信号语义。
+        use_defaults: 是否合并 COMPONENT_DEFAULTS 中的已验证默认参数。
+
+    Returns:
+        success: data 含 ``name``(唯一 Name 标签，后续寻址主键)、``component``、
+            ``defn``、``ports``({端口名: (x, y)})、``position``、``orient``。
+        error: 创建/配置失败。
+    """
+    try:
+        bad = _require_canvas()
+        if bad:
+            return bad
+        full = comp_type if ':' in comp_type else 'master:' + comp_type
+        final_name = name if name else _gen_name(full)
+        kw = dict(params or {})
+        kw['Name'] = final_name
+        if use_defaults and full in COMPONENT_DEFAULTS:
+            merged = dict(COMPONENT_DEFAULTS[full])
+            merged.update(kw)
+            kw = merged
+        comp = _main.create_component(full, x, y, orient=orient, **kw)
+        ports: Dict[str, Tuple[int, int]] = {}
+        try:
+            ports = {k: tuple(v[:2]) for k, v in comp.ports().items()}
+        except Exception:
+            pass
+        return _ok({'name': final_name, 'component': comp, 'defn': full,
+                    'ports': ports, 'position': (x, y), 'orient': orient})
+    except Exception as exc:
+        return _err(exc)
+
+
+def get_component(name: str) -> Dict[str, Any]:
+    """按 Name 标签寻址组件（遍历画布匹配，跨进程持久有效）。
+
+    Returns:
+        success: data 含 ``component``、``ports``、``name``。
+        error: 未找到。
+    """
+    try:
+        comp = _find_by_name(name)
+        if comp is None:
+            return _err('未找到 Name="%s" 的组件（当前画布已加载：%s）'
+                        % (name, _prj_name or '?'))
+        ports = {}
+        try:
+            ports = {k: tuple(v[:2]) for k, v in comp.ports().items()}
+        except Exception:
+            pass
+        return _ok({'component': comp, 'ports': ports, 'name': name})
+    except Exception as exc:
+        return _err(exc)
+
+
+def list_components() -> Dict[str, Any]:
+    """列出当前画布全部组件的 Name 标签与端口（遍历画布，寻址调试用）。
+
+    Returns:
+        success: data 含 ``components``([{name, ports}] 列表) 与 ``count``。
+    """
+    try:
+        items = []
+        for c in _iter_components():
+            nm = _name_of(c)
+            ports = {}
+            try:
+                ports = {k: tuple(v[:2]) for k, v in c.ports().items()}
+            except Exception:
+                pass
+            items.append({'name': nm, 'ports': ports})
+        return _ok({'components': items, 'count': len(items)})
+    except Exception as exc:
+        return _err(exc)
+
+
+def set_component_params(name: str,
+                         params: Dict[str, Any]) -> Dict[str, Any]:
+    """就地修改已放置组件的参数（如负荷电阻、下垂系数、tbreak 时序）。
+
+    Args:
+        name: 目标组件 Name 标签。
+        params: 参数键值对。
+
+    Returns:
+        success: data 含 ``applied``(实际生效参数)。
+    """
+    try:
+        r = get_component(name)
+        if r['status'] != 'success':
+            return r
+        comp = r['data']['component']
+        comp.parameters(parameters=dict(params))
+        return _ok({'applied': dict(params)})
+    except Exception as exc:
+        return _err(exc)
+
+
+# ---------------------------------------------------------------------------
+# 工具集 3：安全连线（拓扑黄金法则实现，Name 寻址）
+# ---------------------------------------------------------------------------
+def _seg_hits(p1: Tuple[int, int], p2: Tuple[int, int],
+              ports: List[Tuple[int, int]]) -> bool:
+    """检查水平/垂直线段是否经过 ports 中的任何坐标（端点本身除外）。"""
+    x1, y1 = p1
+    x2, y2 = p2
+    for px, py in ports:
+        if (px, py) == p1 or (px, py) == p2:
+            continue
+        if y1 == y2 and py == y1 and min(x1, x2) <= px <= max(x1, x2):
+            return True
+        if x1 == x2 and px == x1 and min(y1, y2) <= py <= max(y1, y2):
+            return True
+    return False
+
+
+def _route(p1: Tuple[int, int], p2: Tuple[int, int],
+           ports: List[Tuple[int, int]], bend: str,
+           clearance: int) -> Tuple[List[Tuple[int, int]], List[str]]:
+    """生成避开端口的安全正交路径（直连/L 型/U 型绕行）。
+
+    返回 (路径点列表, 警告列表)；无安全路径时返回第一条候选并附警告。
+    """
+    warnings: List[str] = []
+    x1, y1 = p1
+    x2, y2 = p2
+    candidates: List[List[Tuple[int, int]]] = []
+    if x1 == x2 or y1 == y2:
+        candidates.append([p1, p2])
+    else:
+        if bend in ('auto', 'hfirst'):
+            candidates.append([p1, (x2, y1), p2])
+        if bend in ('auto', 'vfirst'):
+            candidates.append([p1, (x1, y2), p2])
+        if bend in ('auto', 'top', 'bottom'):
+            dy = -clearance if bend == 'top' else clearance
+            candidates.append([p1, (x1, y1 + dy), (x2, y1 + dy), p2])
+            candidates.append([p1, (x1, y1 - clearance), (x2, y1 - clearance), p2])
+    for path in candidates:
+        clean = True
+        for a, b in zip(path, path[1:]):
+            if _seg_hits(a, b, ports):
+                clean = False
+                break
+        if clean:
+            return path, warnings
+    warnings.append('未找到完全避让端口的路径，采用候选路径（可能有穿线风险，'
+                    '请检查 build messages 或运行 check_component_overlaps）')
+    return candidates[0], warnings
+
+
+def connect_ports_safely(source_name: str, source_port: str,
+                         target_name: str, target_port: str,
+                         bend: str = 'auto',
+                         clearance: int = 20) -> Dict[str, Any]:
+    """精准连接两个组件的指定端口（按 Name 寻址；防悬空/穿线短路）。
+
+    内部逻辑（已验证的黄金法则）：
+      1. 按 Name 遍历画布寻址两端组件，从 ``ports()`` 动态取绝对坐标；
+      2. 校验端口名存在性；
+      3. 枚举画布其余组件端口，生成避让的正交折线（L 型/U 型绕行）；
+      4. ``create_wire`` 落线——wire 段不经过任何非目标端口坐标。
+
+    Args:
+        source_name: 源组件 Name 标签。
+        source_port: 源端口名（如 resistor 的 'A'、ammeter 的 'N2'）。
+        target_name: 目标组件 Name 标签。
+        target_port: 目标端口名。
+        bend: 'auto'(默认) / 'hfirst' / 'vfirst' / 'top' / 'bottom'。
+        clearance: U 型绕行的垂直间距（网格单位，默认 20）。
+
+    Returns:
+        success: data 含 ``wire_points``、``source_coord``、``target_coord``、
+            ``routed``、``warnings``。
+        error: 端口不存在/组件未找到/坐标重叠等。
+    """
+    try:
+        bad = _require_canvas()
+        if bad:
+            return bad
+        r1 = get_component(source_name)
+        r2 = get_component(target_name)
+        if r1['status'] != 'success':
+            return r1
+        if r2['status'] != 'success':
+            return r2
+        comp1 = r1['data']['component']
+        comp2 = r2['data']['component']
+        ps1 = comp1.ports()
+        ps2 = comp2.ports()
+        if source_port not in ps1:
+            return _err('端口 "%s" 不存在于组件 "%s"，可用: %s'
+                        % (source_port, source_name, sorted(ps1)))
+        if target_port not in ps2:
+            return _err('端口 "%s" 不存在于组件 "%s"，可用: %s'
+                        % (target_port, target_name, sorted(ps2)))
+        p1 = tuple(ps1[source_port][:2])
+        p2 = tuple(ps2[target_port][:2])
+        if p1 == p2:
+            return _err('源/目标端口坐标相同 %s——组件锚点重叠，请调整布局' % (p1,))
+        other_ports = _collect_all_ports(exclude_names={source_name, target_name})
+        path, warnings = _route(p1, p2, other_ports, bend, clearance)
+        _main.create_wire(*path)
+        return _ok({'wire_points': path, 'source_coord': p1,
+                    'target_coord': p2, 'routed': len(warnings) == 0,
+                    'warnings': warnings})
+    except Exception as exc:
+        return _err(exc)
+
+
+def connect_ports_chain(specs: List[Tuple[str, str, str, str]],
+                        bend: str = 'auto') -> Dict[str, Any]:
+    """批量链式连线：[(src_name, src_port, tgt_name, tgt_port), ...] 顺序执行。
+
+    Returns:
+        success: data 含 ``results``（每条 connect_ports_safely 的返回值）。
+    """
+    try:
+        results = []
+        for spec in specs:
+            results.append(connect_ports_safely(spec[0], spec[1],
+                                                spec[2], spec[3], bend=bend))
+        return _ok({'results': results})
+    except Exception as exc:
+        return _err(exc)
+
+
+def connect_signal_by_name(source_name: str, source_port: str,
+                           signal_name: str,
+                           target_name: str, target_port: str) -> Dict[str, Any]:
+    """用同名 datalabel 桥接数据/控制信号（信号链标准做法，无需 wire）。
+
+    机制（实测）：datalabel 端口 = 锚点；与组件端口**同坐标(0 距离)**放置即
+    吸附连接并重命名该端口信号；两个同名 datalabel 无线互连。适用于 const→
+    mult 输入、const→source Mag/freq 端口、控制器输出→端口等全部数据信号。
+
+    Args:
+        source_name: 源组件 Name（信号产生端，如 const）。
+        source_port: 源端口名（如 const 的 'OUT'）。
+        signal_name: 信号名（须唯一；多个同名即广播）。
+        target_name: 目标组件 Name（信号消费端）。
+        target_port: 目标端口名（如 source_1 的 'Mag' / 'freq'）。
+
+    Returns:
+        success: data 含 ``signal``、两端坐标、两端 datalabel 放置点。
+        error: 组件/端口不存在等。
+    """
+    try:
+        bad = _require_canvas()
+        if bad:
+            return bad
+        r1 = get_component(source_name)
+        r2 = get_component(target_name)
+        if r1['status'] != 'success':
+            return r1
+        if r2['status'] != 'success':
+            return r2
+        ps1 = r1['data']['component'].ports()
+        ps2 = r2['data']['component'].ports()
+        if source_port not in ps1:
+            return _err('端口 "%s" 不存在于组件 "%s"' % (source_port, source_name))
+        if target_port not in ps2:
+            return _err('端口 "%s" 不存在于组件 "%s"' % (target_port, target_name))
+        p1 = tuple(ps1[source_port][:2])
+        p2 = tuple(ps2[target_port][:2])
+        if p1 == p2:
+            return _err('源/目标端口坐标相同 %s——组件锚点重叠' % (p1,))
+        _main.create_component('master:datalabel', p1[0], p1[1], orient=0,
+                               Name=signal_name)
+        _main.create_component('master:datalabel', p2[0], p2[1], orient=0,
+                               Name=signal_name)
+        return _ok({'signal': signal_name, 'source_coord': p1,
+                    'target_coord': p2})
+    except Exception as exc:
+        return _err(exc)
+
+
+def register_pgb(channel_name: str, x: Optional[int] = None,
+                 y: Optional[int] = None) -> Dict[str, Any]:
+    """注册 PGB 输出通道（pgb + 同名 datalabel）。
+
+    Args:
+        channel_name: 输出通道名（与目标信号同名即记录该信号）。
+        x, y: pgb 锚点；None 时自动布点（x=900 起，每 40 递增）。
+
+    Returns:
+        success: data 含 ``channel``、``position``。
+    """
+    try:
+        bad = _require_canvas()
+        if bad:
+            return bad
+        if x is None or y is None:
+            slot = _pgb_slot[0]
+            _pgb_slot[0] += 1
+            x = 900 + (slot % 4) * 60
+            y = 100 + (slot // 4) * 40
+        _main.create_component('master:pgb', x, y, orient=0, Name=channel_name)
+        _main.create_component('master:datalabel', x, y, orient=0,
+                               Name=channel_name)
+        return _ok({'channel': channel_name, 'position': (x, y)})
+    except Exception as exc:
+        return _err(exc)
+
+
+def check_component_overlaps(min_gap: int = 2) -> Dict[str, Any]:
+    """诊断：遍历画布全部组件，检查锚点/端口重叠（build 前自检）。
+
+    Returns:
+        success: data 含 ``overlaps``（重叠对列表，空列表=安全）与 ``checked``。
+    """
+    try:
+        items = _iter_components()
+        overlaps = []
+        for i in range(len(items)):
+            for j in range(i + 1, len(items)):
+                c1, c2 = items[i], items[j]
+                try:
+                    ps1 = [tuple(v[:2]) for v in c1.ports().values()]
+                    ps2 = [tuple(v[:2]) for v in c2.ports().values()]
+                except Exception:
+                    continue
+                for a in ps1:
+                    for b in ps2:
+                        if abs(a[0] - b[0]) <= min_gap and abs(a[1] - b[1]) <= min_gap:
+                            overlaps.append({'name': _name_of(c1), 'port': a,
+                                             'vs': _name_of(c2), 'port': b})
+        return _ok({'overlaps': overlaps, 'checked': len(items)})
+    except Exception as exc:
+        return _err(exc)
+
+
+# ---------------------------------------------------------------------------
+# 工具集 4：仿真配置、运行与监控
+# ---------------------------------------------------------------------------
+def configure_simulation(time_duration: float = 0.5,
+                         time_step: float = 10.0,
+                         sample_step: float = 50.0,
+                         output_filename: Optional[str] = None) -> Dict[str, Any]:
+    """配置当前工程的仿真参数。
+
+    Args:
+        time_duration: 仿真时长（秒）。
+        time_step: EMTDC 步长（微秒）。短线路须 < 传播时间（1km≈3.415µs）。
+        sample_step: 输出采样步长（微秒）。
+        output_filename: 输出文件名（不含路径，写入 .gf46 目录）。
+
+    Returns:
+        success: data 含 ``parameters``（生效配置）。
+        error: 未加载工程。
+    """
+    try:
+        if _prj is None:
+            return _err('未加载工程，请先调用 connect_and_load_project()')
+        out = output_filename or ('%s.out' % _prj_name)
+        _prj.parameters(time_duration=time_duration, time_step=time_step,
+                        sample_step=sample_step, PlotType=1,
+                        output_filename=out)
+        return _ok({'parameters': {'time_duration': time_duration,
+                                   'time_step': time_step,
+                                   'sample_step': sample_step,
+                                   'output_filename': out}})
+    except Exception as exc:
+        return _err(exc)
+
+
+def run_simulation_and_monitor(timeout_loops: int = 60,
+                               poll_interval: float = 1.2) -> Dict[str, Any]:
+    """编译并运行 EMTDC 仿真，全程监控并返回底层消息。
+
+    流程：save → build → 收集 error/warning 消息 → run →
+    轮询 ``prj.output()`` 中的 'Status code = N' 直至出现或超时。
+
+    Args:
+        timeout_loops: 轮询次数上限（配合 poll_interval 即总等待上限）。
+        poll_interval: 轮询间隔（秒）。
+
+    Returns:
+        success: data 含 ``status``('success'/'build_failed'/'run_finished'/
+            'timeout')、``status_code``、``errors``、``warnings``。
+        error: 未加载工程/调用异常。
+    """
+    try:
+        if _prj is None:
+            return _err('未加载工程，请先调用 connect_and_load_project()')
+        _prj.save()
+        _prj.build()
+
+        def collect(level: str) -> List[Dict[str, str]]:
+            out = []
+            try:
+                for m in _prj.messages():
+                    if m.status == level:
+                        out.append({'text': m.text, 'name': m.name,
+                                    'label': m.label})
+            except Exception:
+                pass
+            return out
+
+        errors = collect('error')
+        warnings = collect('warning')
+        if errors:
+            return _ok({'status': 'build_failed', 'status_code': None,
+                        'errors': errors, 'warnings': warnings})
+
+        _prj.run()
+        status_code: Optional[int] = None
+        for _ in range(timeout_loops):
+            time.sleep(poll_interval)
+            try:
+                m = re.search(r'Status code = (\d+)', _prj.output())
+            except Exception:
+                m = None
+            if m:
+                status_code = int(m.group(1))
+                break
+
+        run_errors = collect('error')
+        if status_code is None:
+            return _ok({'status': 'timeout', 'status_code': None,
+                        'errors': run_errors, 'warnings': warnings})
+        state = 'success' if status_code == 0 else 'run_finished'
+        return _ok({'status': state, 'status_code': status_code,
+                    'errors': run_errors, 'warnings': warnings})
+    except Exception as exc:
+        return _err(exc)
+
+
+# ---------------------------------------------------------------------------
+# 工具集 5：结果读取与数值分析
+# ---------------------------------------------------------------------------
+def _gf_dir() -> Optional[str]:
+    """当前工程的 .gf46 输出目录（存在性检查）。"""
+    gf = os.path.join(_prj_folder, _prj_name + '.gf46')
+    return gf if os.path.isdir(gf) else None
+
+
+def read_output(channel: Optional[str] = None,
+                t0: float = 0.0,
+                t1: Optional[float] = None,
+                method: str = 'rms',
+                freq: float = 50.0) -> Dict[str, Any]:
+    """读取最新一次仿真的通道数据（.inf PGB 映射 + .out 列）。
+
+    格式定论：.out 每通道每相 1 列瞬时值（按 F0 频率旋转的相量投影），
+    **任意列 RMS = 相 RMS**；DFT 提取基波须用系统实际频率（F0）。
+
+    Args:
+        channel: 通道名（如 'VrA'）；None 返回全部通道。
+        t0, t1: 分析时间窗（秒）；t1=None 取到末尾。
+        method: 'rms'(列 RMS，默认) / 'mean'(直流均值，适合 Fset) /
+            'dft'(基波 RMS，freq 参数指定频率)。
+        freq: DFT 用频率（Hz）；必须等于系统实际频率，否则幅度≈0。
+
+    Returns:
+        success: data 含 ``channels``({通道: {cols: 每相值列表}})、
+            ``window``、``method``。
+        error: 无输出/通道不存在。
+    """
+    try:
+        gf = _gf_dir()
+        if gf is None:
+            return _err('未找到 .gf46 输出目录（工程: %s，folder: %s）——'
+                        '请先运行仿真' % (_prj_name, _prj_folder))
+        infs = [f for f in os.listdir(gf) if f.endswith('.inf')]
+        outs = [f for f in os.listdir(gf) if f.endswith('_01.out')]
+        if not infs or not outs:
+            return _err('输出文件缺失（inf=%d, out=%d）' % (len(infs), len(outs)))
+        cmap: Dict[int, str] = {}
+        with open(os.path.join(gf, infs[-1]), encoding='utf-8',
+                  errors='replace') as fh:
+            for ln in fh:
+                m = re.search(r'PGB\((\d+)\)\s+Output\s+Desc="([^"]+)"', ln)
+                if m:
+                    cmap[int(m.group(1))] = m.group(2)
+        rows: List[List[float]] = []
+        with open(os.path.join(gf, outs[-1]), encoding='utf-8',
+                  errors='replace') as fh:
+            for ln in fh:
+                parts = ln.split()
+                if len(parts) >= 2:
+                    try:
+                        rows.append([float(p) for p in parts])
+                    except ValueError:
+                        continue
+        if not rows:
+            return _err('.out 为空（仿真可能未产生数据）')
+        cols: Dict[str, List[List[float]]] = {}
+        for ci, cn in cmap.items():
+            if ci < len(rows[0]):
+                cols.setdefault(cn, []).append([r[ci] for r in rows])
+
+        if t1 is None:
+            t1 = rows[-1][0]
+
+        def window_vals(vals: List[float]) -> List[float]:
+            return [v for r, v in zip(rows, vals) if t0 <= r[0] <= t1]
+
+        result: Dict[str, Any] = {}
+        for cn, col_list in cols.items():
+            if channel is not None and cn != channel:
+                continue
+            per_phase = []
+            for col in col_list:
+                w = window_vals(col)
+                if not w:
+                    per_phase.append(None)
+                elif method == 'rms':
+                    per_phase.append(math.sqrt(sum(x * x for x in w) / len(w)))
+                elif method == 'mean':
+                    per_phase.append(sum(w) / len(w))
+                elif method == 'dft':
+                    re_, im = 0.0, 0.0
+                    n = len(w)
+                    for i, v in enumerate(w):
+                        a = 2 * math.pi * freq * (t0 + i * (t1 - t0) / max(n, 1) - t0)
+                        re_ += v * math.cos(a)
+                        im -= v * math.sin(a)
+                    ph = abs(complex(2 * re_ / n, 2 * im / n)) / math.sqrt(2)
+                    per_phase.append(round(ph, 6))
+                else:
+                    return _err('未知 method=%s' % method)
+            result[cn] = {'cols': per_phase}
+        if channel is not None and channel not in result:
+            return _err('通道 "%s" 不存在；可用: %s' % (channel, sorted(cols)))
+        return _ok({'channels': result, 'window': (t0, t1), 'method': method})
+    except Exception as exc:
+        return _err(exc)
+
+
+def compute_sequence(ia: float, ib: float, ic: float) -> Dict[str, Any]:
+    """Fortescue 对称分量换算（输入为基波相量幅值，输出 RMS 幅值）。
+
+    Args:
+        ia, ib, ic: 三相基波幅值（同单位；相位缺失时假定 a=0°、b=-120°、c=120°）。
+
+    Returns:
+        success: data 含 ``I1``/``I2``/``I0``(RMS) 与比值 ``I2/I1``、``I0/I1``。
+        注：严格版请用 read_output(method='dft') 取三相后再按相角合成。
+    """
+    try:
+        import cmath
+        a = cmath.exp(2j * math.pi / 3)
+        v1 = (ia + a * ib + a * a * ic) / 3
+        v2 = (ia + a * a * ib + a * ic) / 3
+        v0 = (ia + ib + ic) / 3
+        m1 = abs(v1) / math.sqrt(2)
+        m2 = abs(v2) / math.sqrt(2)
+        m0 = abs(v0) / math.sqrt(2)
+        return _ok({'I1': round(m1, 6), 'I2': round(m2, 6), 'I0': round(m0, 6),
+                    'I2/I1': round(m2 / m1, 4) if m1 > 1e-9 else None,
+                    'I0/I1': round(m0 / m1, 4) if m1 > 1e-9 else None})
+    except Exception as exc:
+        return _err(exc)
+
+
+# ---------------------------------------------------------------------------
+# 便捷构建块（高频组合逻辑，Name 寻址）
+# ---------------------------------------------------------------------------
+def build_droop_chain(gfm_name: str, m: float = 0.01, t_lp: float = 0.3,
+                      anchor_x: int = 300, anchor_y: int = 20,
+                      ph: str = 'A') -> Dict[str, Any]:
+    """搭建 P-f 下垂控制链（L15 精确布局）。
+
+    链：mult(Ig×Vg) → 一阶(realpole) → 下垂(realpole) → sumjct(50−mP) → Fset 信号。
+
+    Args:
+        gfm_name: 已存在的 source_1(EXTERNAL) 组件 Name（信号接到其 freq 端口）。
+        m: 下垂系数（Hz/MW）。**符号约定**：Pm=Ig×Vg 且 Ig 从 GFM 流出为正时
+            用 **+m**（本库约定）；若测量方向相反需取 -m。
+        t_lp: 一阶惯性时间常数（秒）。
+        anchor_x, anchor_y: 控制链锚点。
+        ph: 相位后缀（信号名后缀，避免三相同名冲突）。
+
+    Returns:
+        success: data 含 ``signal``(Fset 信号名)、``components``(链内组件 Name 列表)。
+    """
+    try:
+        bad = _require_canvas()
+        if bad:
+            return bad
+        sig_fk = 'Fk' + ph
+        sig_fs = 'Fset' + ph
+        r = get_component(gfm_name)
+        if r['status'] != 'success':
+            return r
+        ps = r['data']['component'].ports()
+        if 'freq' not in ps:
+            return _err('组件 "%s" 无 freq 端口（需 source_1 EXTERNAL）' % gfm_name)
+
+        names = []
+        r = add_and_configure_component('master:mult', anchor_x, anchor_y,
+                                        name='MUL' + ph)
+        names.append(r['data']['name'])
+        r = add_and_configure_component('master:realpole', anchor_x + 4, anchor_y,
+                                        params={'T': t_lp, 'G': 1.0, 'YO': 0.0},
+                                        name='LP' + ph)
+        names.append(r['data']['name'])
+        r = add_and_configure_component('master:realpole', anchor_x, anchor_y - 35,
+                                        params={'T': 0.001, 'G': m, 'YO': 0.0},
+                                        name='MG' + ph)
+        names.append(r['data']['name'])
+        r = add_and_configure_component('master:sumjct', anchor_x + 6, anchor_y - 35,
+                                        params={'A': 'DISABLE', 'B': 'DISABLE',
+                                                'F': 'SUBTRACT', 'Dim': 1,
+                                                'DPath': 'REAL'},
+                                        name='SJ' + ph)
+        names.append(r['data']['name'])
+        r = add_and_configure_component('master:const', anchor_x + 2, anchor_y - 35,
+                                        params={'Value': 50.0, 'Dim': 1},
+                                        name='C50' + ph)
+        names.append(r['data']['name'])
+        # 信号桥：Pm 由外部接入 mult；Fk/Fset 用 datalabel 双端
+        r = connect_signal_by_name(names[2], 'O', sig_fk, names[3], 'INF')
+        r = connect_signal_by_name(names[4], 'OUT', sig_fs, gfm_name, 'freq')
+        return _ok({'signal': sig_fs, 'components': names,
+                    'chain_anchor': (anchor_x, anchor_y)})
+    except Exception as exc:
+        return _err(exc)
+
+
+# ---------------------------------------------------------------------------
+# 模块自检（不连接 PSCAD，不触发懒加载）
+# ---------------------------------------------------------------------------
+def self_check() -> Dict[str, Any]:
+    """库自检：配置状态、导入可用性、路径存在性（不连接 PSCAD）。
+
+    Returns:
+        success: data 含 ``config``(当前配置)、``config_exists``、
+            ``mhi_import``(懒加载试导入结果)、``pscad_exe_exists``、
+            ``pylib_dir_exists``、``functions``(全部工具名)。
+    """
+    try:
+        cfg = load_config()
+        exe = _cfg_exe()
+        pylib = _cfg_pylib()
+        ok_import, msg = _import_mhi()
+        return _ok({
+            'config': cfg,
+            'config_exists': bool(cfg),
+            'config_path': _config_path(),
+            'resolved': {'pscad_exe_path': exe, 'mhi_pylib_path': pylib,
+                         'pscad_port': PSCAD_PORT},
+            'mhi_import': ok_import,
+            'mhi_error': '' if ok_import else msg,
+            'pscad_exe_exists': bool(exe) and os.path.isfile(exe),
+            'pylib_dir_exists': bool(pylib) and os.path.isdir(pylib),
+            'functions': ['init_pscad_environment', 'connect_and_load_project',
+                          'add_and_configure_component', 'connect_ports_safely',
+                          'connect_signal_by_name', 'register_pgb',
+                          'configure_simulation', 'run_simulation_and_monitor',
+                          'read_output', 'restart_pscad',
+                          'check_component_overlaps', 'list_components',
+                          'build_droop_chain'],
+        })
+    except Exception as exc:
+        return _err(exc)