dsh-plugin-pscad-expert-vyma 1.0.7 → 1.0.8

package/README.md

@@ -1,6 +1,6 @@
 # pscad-dsh-plugin — PSCAD 自动化建模与仿真控制专家插件
 
-> **版本**：1.0.7 ｜ **注册名**：`pscad-automation-expert`
+> **版本**：1.0.8 ｜ **注册名**：`pscad-automation-expert`
 > **来源**：PSCAD 知识资产固化项目（四阶段：技能文档 → 模板索引 → 工具库 → 插件打包）
 > 所有知识、工具、模板均来自真实仿真验证（L13~L19 认证轮 + R4 科研轮），**无伪造数据**。
 

package/index.js

@@ -96,10 +96,10 @@ function renderJson(_args, value) {
 const toolDefs = [
   {
     name: 'pscad_init_environment',
-    description: '首次配置 PSCAD 运行环境：将 PSCAD 可执行文件路径与 mhi.pscad 库目录保存到工作区 .pscad_config.json。任何工具返回 ConfigMissing 时，必须先调用本工具获取用户提供的路径。',
+    description: '首次配置 PSCAD 运行环境：保存 PSCAD 可执行文件路径（必填）与 mhi.pscad 库位置（可选）到用户级 .pscad_config.json。pylib 缺省时自动从 PSCAD 安装目录发现（PSCAD 5.x 自带 bin/win64/mhi.zip），只有 PSCAD + Python 的机器无需额外文件。任何工具返回 ConfigMissing 时，必须先调用本工具获取用户提供的路径。',
     parameters: {
       exe_path: { type: 'string', required: true, description: 'PSCAD 可执行文件绝对路径（如 C:/PSCAD/bin/win64/Pscad.exe）' },
-      pylib_path: { type: 'string', required: true, description: 'mhi.pscad 库目录绝对路径' },
+      pylib_path: { type: 'string', description: 'mhi.pscad 库目录/zip 绝对路径（可选；缺省自动从 PSCAD 安装目录发现）' },
     },
   },
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-pscad-expert-vyma",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "PSCAD 自动化建模与仿真控制专家插件（DSH Agent 工具库 + 基准模板 + 领域知识）",
   "type": "module",
   "main": "index.js",

package/plugin.yaml

@@ -3,7 +3,7 @@
 # 由知识资产固化项目自动生成（2026-08-25）· 部署至 Git 仓库
 # ============================================================
 name: pscad-automation-expert
-version: 1.0.7
+version: 1.0.8
 description: PSCAD 自动化建模与仿真控制专家插件
 
 # ---- 系统提示词（加载到 Agent 上下文最前置位置）----

package/tools/main.py

@@ -194,6 +194,9 @@ def save_config(exe_path: str, pylib_path: str) -> Dict[str, Any]:
             'saved_at': time.strftime('%Y-%m-%d %H:%M:%S'),
         }
         path = _config_path()
+        parent = os.path.dirname(path)
+        if parent and not os.path.isdir(parent):
+            os.makedirs(parent, exist_ok=True)
         with open(path, 'w', encoding='utf-8') as fh:
             json.dump(cfg, fh, ensure_ascii=False, indent=2)
         _config_cache = cfg
@@ -204,16 +207,19 @@ def save_config(exe_path: str, pylib_path: str) -> Dict[str, Any]:
         return _err(exc)
 
 
-def init_pscad_environment(exe_path: str, pylib_path: str) -> Dict[str, Any]:
+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 等）将自动懒加载该配置，无需任何系统环境变量。
+    接收用户提供的 PSCAD 可执行文件路径（**必填**）与 mhi.pscad 库位置（可选）。
+    写入用户级 ``.pscad_config.json``。配置持久化后，连接/启动类工具
+    （connect_and_load_project、restart_pscad 等）将自动懒加载该配置，
+    无需任何系统环境变量。
 
     Args:
-        exe_path: PSCAD 可执行文件绝对路径。
-        pylib_path: mhi.pscad 库目录绝对路径。
+        exe_path: PSCAD 可执行文件绝对路径（必填）。
+        pylib_path: mhi.pscad 库目录/zip 绝对路径（可选）。**留空时自动从
+            PSCAD 安装目录发现**（PSCAD 5.x 自带 ``bin/win64/mhi.zip``），
+            因此只有 PSCAD + Python 的机器无需准备任何额外文件。
 
     Returns:
         success: data 含 ``config_path``、``pscad_exe_path``、``mhi_pylib_path``
@@ -221,6 +227,16 @@ def init_pscad_environment(exe_path: str, pylib_path: str) -> Dict[str, Any]:
         error: 写入失败。
     """
     try:
+        if not pylib_path:
+            discovered = _discover_pylib(exe_path)
+            if discovered:
+                pylib_path = discovered
+            else:
+                return {'error': 'ConfigMissing',
+                        'instruction': ('未能在 PSCAD 安装目录自动发现 mhi.pscad。'
+                                        '请确认 PSCAD 5.x 安装完整（应有 '
+                                        'bin/win64/mhi.zip），或手动提供 mhi.pscad '
+                                        '库路径后再调用 init_pscad_environment。')}
         r = save_config(exe_path, pylib_path)
         if r['status'] == 'success':
             r['data']['message'] = ('PSCAD 环境配置已保存。后续连接将自动使用该配置，'
@@ -239,12 +255,54 @@ def _cfg_exe() -> Optional[str]:
     return exe or None
 
 
+def _discover_pylib(exe: Optional[str]) -> Optional[str]:
+    """从 PSCAD 安装目录**自动发现** mhi.pscad，无需用户准备任何文件。
+
+    PSCAD 5.x 内嵌 Python API：mhi 包以 ``<PSCAD>/bin/win64/mhi.zip`` 形式随
+    安装分发（zip 可直接加入 sys.path 被 ``import mhi.pscad`` 解析）。依次尝试：
+    exe 同目录 ``mhi.zip`` / ``mhi`` / ``pylib`` → 安装根 ``pylib`` →
+    安装根 ``Lib/site-packages``。返回候选路径（目录或 zip 文件），找不到 None。
+    """
+    if not exe:
+        return None
+    try:
+        exe_dir = os.path.dirname(os.path.abspath(exe))
+        root = os.path.dirname(exe_dir)
+        candidates = [
+            os.path.join(exe_dir, 'mhi.zip'),
+            os.path.join(exe_dir, 'mhi'),
+            os.path.join(exe_dir, 'pylib'),
+            os.path.join(root, 'pylib'),
+            os.path.join(root, 'Lib', 'site-packages'),
+        ]
+        import zipfile
+        for cand in candidates:
+            try:
+                if os.path.isfile(cand) and cand.lower().endswith('.zip'):
+                    with zipfile.ZipFile(cand) as zf:
+                        if 'mhi/__init__.py' in set(zf.namelist()):
+                            return cand
+                elif (os.path.isdir(cand) and os.path.isfile(
+                        os.path.join(cand, 'mhi', '__init__.py'))):
+                    return cand
+            except Exception:
+                continue
+    except Exception:
+        pass
+    return None
+
+
 def _cfg_pylib() -> Optional[str]:
-    """解析 mhi.pscad 库目录：本地配置优先，环境变量降级回退。"""
+    """解析 mhi.pscad 库位置：配置优先 → 环境变量 → **PSCAD 安装自动发现**。
+
+    自动发现使插件在**只有 PSCAD + Python** 的机器上即可使用，无需预置 pylib。
+    """
     cfg = load_config()
     pylib = cfg.get('mhi_pylib_path')
     if not pylib:
         pylib = os.environ.get('MHI_PYLIB_PATH')
+    if not pylib:
+        pylib = _discover_pylib(_cfg_exe())
     return pylib or None
 
 
@@ -300,6 +358,8 @@ def _import_mhi() -> Tuple[bool, str]:
     流程：``load_config()`` 取 pylib 路径 → 动态加入 ``sys.path`` → import。
     **配置缺失时不抛异常**，返回引导消息：先调用 ``init_pscad_environment``。
     """
+    global mhi  # 必须绑定到模块级：连接代码（_ensure_connected/_launch_pscad）
+    # 依赖 mhi.pscad.connect(...)，函数内 import 只会绑定局部名导致 NameError
     pylib = _cfg_pylib()
     if not pylib:
         return False, MISSING_CONFIG_MSG
@@ -307,7 +367,7 @@ def _import_mhi() -> Tuple[bool, str]:
         if 'mhi.pscad' not in sys.modules:
             if pylib not in sys.path:
                 sys.path.insert(0, pylib)
-            import mhi.pscad  # noqa: F401
+        import mhi.pscad  # noqa: F401  幂等：已加载时仅查 sys.modules 并绑定名字
         return True, ''
     except Exception as exc:
         return False, ('import mhi.pscad 失败（mhi_pylib_path=%s）: %s'
@@ -474,6 +534,7 @@ def connect_and_load_project(project_name: str,
 
         _prj = prj
         _prj_name = project_name
+        _save_session()  # 落盘会话，供后续子进程自愈重连
         try:
             _main = prj.canvas('Main')
         except Exception as exc:
@@ -503,6 +564,78 @@ def _ensure_connected() -> Tuple[bool, str]:
         return False, '连接 PSCAD 失败(port=%d): %s' % (PSCAD_PORT, exc)
 
 
+# ---------------------------------------------------------------------------
+# 会话状态持久化 + 自愈重连
+# 每次工具调用都是独立 cli.py 子进程，main.py 内存句柄（_pscad/_prj/_main）
+# 跨调用即丢失；connect_and_load_project 成功后落盘会话，状态工具启动时
+# 用 _ensure_project() 从 PSCAD 实例重取工程句柄，实现多步工作流无缝衔接。
+# ---------------------------------------------------------------------------
+def _session_path() -> str:
+    """会话状态文件：与配置同目录（随 DSH_HOME 环境一致）。"""
+    return os.path.join(os.path.dirname(_config_path()), 'pscad_session.json')
+
+
+def _save_session() -> None:
+    """落盘当前工程会话（project_name + folder）。失败静默（非关键路径）。"""
+    try:
+        with open(_session_path(), 'w', encoding='utf-8') as fh:
+            json.dump({'project_name': _prj_name, 'folder': _prj_folder}, fh)
+    except Exception:
+        pass
+
+
+def _load_session() -> Tuple[Optional[str], Optional[str]]:
+    """读取会话状态；无/损坏返回 (None, None)。"""
+    try:
+        with open(_session_path(), encoding='utf-8') as fh:
+            d = json.load(fh)
+        return d.get('project_name'), d.get('folder')
+    except Exception:
+        return None, None
+
+
+def _ensure_project() -> Optional[Dict[str, Any]]:
+    """自愈：若本进程未持有工程句柄，按会话状态重连 PSCAD 并重新获取。
+
+    成功返回 None；失败返回 error 字典（含引导消息）。所有状态型工具
+    （configure/run/read/canvas 类）入口都应先调用本函数。
+    """
+    global _pscad, _prj, _prj_name, _prj_folder, _main
+    if _prj is not None and _main is not None:
+        return None
+    name, folder = _load_session()
+    if not name or not folder:
+        return _err('未加载工程且无会话状态，请先调用 connect_and_load_project()')
+    missing = _require_config()
+    if missing is not None:
+        return missing
+    ok, msg = _ensure_connected()
+    if not ok:
+        return _err(msg)
+    _prj_folder = folder
+    try:
+        prj = _pscad.project(name)
+    except Exception:
+        prj = None
+    if prj is None:
+        pscx = os.path.join(folder, name + '.pscx')
+        if os.path.isfile(pscx):
+            try:
+                _pscad.load(pscx.replace('\\', '/'))
+                prj = _pscad.project(name)
+            except Exception as exc:
+                return _err('会话工程重载失败（%s）: %s' % (pscx, exc))
+    if prj is None:
+        return _err('会话工程 "%s" 不可用（folder=%s）' % (name, folder))
+    _prj = prj
+    _prj_name = name
+    try:
+        _main = prj.canvas('Main')
+    except Exception:
+        _main = None
+    return None
+
+
 def _launch_pscad() -> Tuple[bool, str]:
     """拉起 PSCAD 进程并等待自动化端口就绪（崩溃恢复标准路径；懒加载 exe 路径）。"""
     global _pscad
@@ -577,6 +710,10 @@ def close_connection() -> Dict[str, Any]:
 # ---------------------------------------------------------------------------
 def _require_canvas() -> Optional[Dict[str, Any]]:
     """前置检查：已加载工程且 Main 画布可用。失败返回 error dict，否则 None。"""
+    if _main is None:
+        err = _ensure_project()  # 跨进程自愈：按会话状态重连取回画布
+        if err is not None:
+            return err
     if _main is None:
         return _err('尚未加载工程画布，请先调用 connect_and_load_project()')
     return None
@@ -948,8 +1085,9 @@ def configure_simulation(time_duration: float = 0.5,
         error: 未加载工程。
     """
     try:
-        if _prj is None:
-            return _err('未加载工程，请先调用 connect_and_load_project()')
+        err = _ensure_project()
+        if err is not None:
+            return err
         out = output_filename or ('%s.out' % _prj_name)
         _prj.parameters(time_duration=time_duration, time_step=time_step,
                         sample_step=sample_step, PlotType=1,
@@ -979,8 +1117,9 @@ def run_simulation_and_monitor(timeout_loops: int = 60,
         error: 未加载工程/调用异常。
     """
     try:
-        if _prj is None:
-            return _err('未加载工程，请先调用 connect_and_load_project()')
+        err = _ensure_project()
+        if err is not None:
+            return err
         _prj.save()
         _prj.build()
 
@@ -1056,6 +1195,9 @@ def read_output(channel: Optional[str] = None,
         error: 无输出/通道不存在。
     """
     try:
+        err = _ensure_project()
+        if err is not None:
+            return err
         gf = _gf_dir()
         if gf is None:
             return _err('未找到 .gf46 输出目录（工程: %s，folder: %s）——'
@@ -1231,6 +1373,7 @@ def self_check() -> Dict[str, Any]:
     try:
         cfg = load_config()
         exe = _cfg_exe()
+        cfg_pylib = cfg.get('mhi_pylib_path') or os.environ.get('MHI_PYLIB_PATH')
         pylib = _cfg_pylib()
         ok_import, msg = _import_mhi()
         return _ok({
@@ -1239,6 +1382,9 @@ def self_check() -> Dict[str, Any]:
             'config_path': _config_path(),
             'resolved': {'pscad_exe_path': exe, 'mhi_pylib_path': pylib,
                          'pscad_port': PSCAD_PORT},
+            'pylib_source': ('config' if cfg_pylib else
+                             ('env' if os.environ.get('MHI_PYLIB_PATH') else
+                              ('auto-discovered' if pylib else 'missing'))),
             'mhi_import': ok_import,
             'mhi_error': '' if ok_import else msg,
             'pscad_exe_exists': bool(exe) and os.path.isfile(exe),