dsh-plugin-pscad-expert-vyma 1.0.9 → 1.0.11

package/README.md

@@ -1,6 +1,6 @@
 # pscad-dsh-plugin — PSCAD 自动化建模与仿真控制专家插件
 
-> **版本**：1.0.9 ｜ **注册名**：`pscad-automation-expert`
+> **版本**：1.0.11 ｜ **注册名**：`pscad-automation-expert`
 > **来源**：PSCAD 知识资产固化项目（四阶段：技能文档 → 模板索引 → 工具库 → 插件打包）
 > 所有知识、工具、模板均来自真实仿真验证（L13~L19 认证轮 + R4 科研轮），**无伪造数据**。
 
@@ -25,8 +25,8 @@ pscad-dsh-plugin/
 └── templates/                   # 已验证成功运行的基准 .pscx 拓扑（6 个）
     ├── grid_gfm_support.pscx            # 并网 GFM 支撑基准（容量/位置扫描）
     ├── fault_study.pscx           # 故障研究基准（3LG/1LG/2LG 可控故障支路）
-    ├── island_droop_controller_DROOPC.pscx           # 孤岛下垂 + Fortran 自定义控制器基准
-    ├── line_model_pi_100km_BergeronPI.pscx  # source3 单线图 + newpi 线路（Ferranti 对照）
+    ├── island_droop_controller.pscx           # 孤岛下垂 + Fortran 自定义控制器基准
+    ├── line_model_pi_100km.pscx  # source3 单线图 + newpi 线路（Ferranti 对照）
     ├── gfm_island_droop_nose.pscx # 双 GFM 孤岛下垂 + 鼻点扫描（历史经典）
     └── three_phase_cable_fault.pscx    # 三相电缆故障（Cable_Coax 专项）
 ```
@@ -59,7 +59,7 @@ Agent 维持运行 Loop。全函数 Type Hints + 中文 Docstring。
   含中段母线 Vmid 与受端母线 Vr 双接入点。
 - **fault_study**：在上述架构上加可控故障支路（breaker1+Rf+tbreak，TC=0.3/TO=0.4），
   3LG/1LG/2LG 只需改 tbreak 参数（每类独立案例）；短路电流已与解析公式 <1% 对照。
-- **island_droop_controller_DROOPC**：孤岛 GFM + 工程内嵌 Fortran 自定义组件 DROOPC（饱和下垂+虚拟惯量），
+- **island_droop_controller**：孤岛 GFM + 工程内嵌 Fortran 自定义组件 DROOPC（饱和下垂+虚拟惯量），
   研究变量集中在 DROOPC 参数（M/F0/T/FMAX/FMIN）。
 - **line_model_pi_100km**：source3 单线图 + newpi 线路空载（Ferranti 效应/线路充电对照）。
 - **gfm_island_droop_nose**：双 GFM 孤岛下垂 + 鼻点族判稳（经典同步稳定性验证）。

package/index.js

@@ -29,7 +29,8 @@ export const Config = Schema.object({
     .description('Python 解释器路径；默认自动探测（PATH→py 启动器→常见安装位置），无需手动配置'),
   toolsCli: Schema.string().default('./tools/cli.py'),
   defaultFolder: Schema.string().default(''),
-  timeoutMs: Schema.number().default(120000),
+  timeoutMs: Schema.number().default(300000)
+    .description('单次工具调用总超时（毫秒）；PSCAD 冷启动等待上限 180s，需留余量'),
 })
 
 // ---------------- Python 解释器自动探测（免 profile YAML 配置） ----------------
@@ -47,13 +48,15 @@ function pyVersionOk(exe) {
 }
 
 function findPythonInDir(parent, prefix) {
-  // 升序取最旧版本（越接近 3.7 越稳妥：mhi.pscad 2.2.1 面向 Python 3.7）
+  // 从目录名解析次版本号（Python3xx），升序优先旧版：
+  // 越接近 3.7 越稳妥（mhi.zip 2.2.1 面向 Python 3.7，且依赖 3.12 已移除的 distutils）
   try {
     const dirs = fs.readdirSync(parent, { withFileTypes: true })
       .filter(e => e.isDirectory() && e.name.startsWith(prefix))
-      .map(e => e.name).sort()
+      .map(e => ({ name: e.name, minor: parseInt(e.name.slice(prefix.length), 10) || 999 }))
+      .sort((a, b) => a.minor - b.minor)
     for (const d of dirs) {
-      const exe = path.join(parent, d, 'python.exe')
+      const exe = path.join(parent, d.name, 'python.exe')
       if (fs.existsSync(exe)) return exe
     }
   } catch {}
@@ -83,8 +86,11 @@ function resolvePython(config) {
         }
       }
       if (picks.length) {
-        picks.sort((a, b) => a.v - b.v)
-        _resolvedPython = picks[0].exe
+        // 优先 Python 3.7–3.11（mhi.zip 2.2.1 依赖 distutils，3.12+ 不可导入）；
+        // 若机器只有 3.12+，退而用之（配合 pip 安装的 mhi-pscad 新版仍可用）
+        const le311 = picks.filter(p => p.v <= 311).sort((a, b) => a.v - b.v)
+        const gt311 = picks.filter(p => p.v > 311).sort((a, b) => a.v - b.v)
+        _resolvedPython = (le311.length ? le311[0] : gt311[0]).exe
         return _resolvedPython
       }
     }
@@ -243,6 +249,46 @@ const toolDefs = [
     description: 'PSCAD 插件环境自检：配置状态、路径存在性、工具清单。诊断用。',
     parameters: {},
   },
+  {
+    name: 'pscad_register_pgb',
+    description: '注册 PGB 输出通道（放置 pgb + 同名 datalabel；通道名与目标信号同名即记录该信号）。',
+    parameters: {
+      channel_name: { type: 'string', required: true, description: '输出通道名（与目标信号同名）' },
+      x: { type: 'integer', description: 'pgb 锚点 X；缺省自动布点' },
+      y: { type: 'integer', description: 'pgb 锚点 Y；缺省自动布点' },
+    },
+  },
+  {
+    name: 'pscad_configure_simulation',
+    description: '配置当前工程仿真参数（时长/EMTDC 步长/采样步长/输出文件名）。短线路 time_step 须 < 传播时间/10。',
+    parameters: {
+      time_duration: { type: 'number', description: '仿真时长（秒，默认 0.5）' },
+      time_step: { type: 'number', description: 'EMTDC 步长（微秒，默认 10）' },
+      sample_step: { type: 'number', description: '输出采样步长（微秒，默认 50）' },
+      output_filename: { type: 'string', description: '输出文件名（不含路径，写入 .gf46 目录）' },
+    },
+  },
+  {
+    name: 'pscad_compute_sequence',
+    description: 'Fortescue 对称分量换算：由三相电流幅值/相角计算正负零序分量。',
+    parameters: {
+      ia: { type: 'number', required: true, description: 'A 相电流（相量）' },
+      ib: { type: 'number', required: true, description: 'B 相电流（相量）' },
+      ic: { type: 'number', required: true, description: 'C 相电流（相量）' },
+    },
+  },
+  {
+    name: 'pscad_restart_pscad',
+    description: '强制重启 PSCAD 自动化服务（卡死/10054 崩溃恢复）：终止进程、重新启动并重连、重载当前工程。',
+    parameters: {},
+  },
+  {
+    name: 'pscad_check_component_overlaps',
+    description: '布局自检：遍历画布全部组件检查锚点/端口重叠（build 前诊断）。',
+    parameters: {
+      min_gap: { type: 'integer', description: '最小间距（默认 2）' },
+    },
+  },
 ]
 
 // ---------------- 插件主体 ----------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-pscad-expert-vyma",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "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.9
+version: 1.0.11
 description: PSCAD 自动化建模与仿真控制专家插件
 
 # ---- 系统提示词（加载到 Agent 上下文最前置位置）----

package/tools/cli.py

@@ -83,6 +83,11 @@ TOOL_WHITELIST: Dict[str, Any] = {
     'pscad_run_simulation': _run_simulation_configure,
     'pscad_read_output': pat.read_output,
     'pscad_self_check': pat.self_check,
+    'pscad_register_pgb': pat.register_pgb,
+    'pscad_configure_simulation': pat.configure_simulation,
+    'pscad_compute_sequence': pat.compute_sequence,
+    'pscad_restart_pscad': pat.restart_pscad,
+    'pscad_check_component_overlaps': pat.check_component_overlaps,
 }
 
 

package/tools/main.py

@@ -68,7 +68,7 @@ from typing import Any, Dict, List, Optional, Tuple
 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
+LAUNCH_WAIT_S: int = 180  # PSCAD 冷启动（拉起→自动化端口就绪）实测可能 >60s，放宽到 180s
 CONNECT_TIMEOUT_S: int = 20
 
 # 配置缺失时的标准 Agent 返回（裸字典，供大模型识别并触发对话式引导）
@@ -228,15 +228,31 @@ def init_pscad_environment(exe_path: str, pylib_path: str = '') -> Dict[str, Any
     """
     try:
         if not pylib_path:
-            discovered = _discover_pylib(exe_path)
-            if discovered:
-                pylib_path = discovered
+            # ① site-packages 已有 pip 版 mhi-pscad（Python 3.12+ 机器常见）：
+            #    直接使用（空 pylib 表示不记录路径，运行时优先直导），无需发现
+            ok_sp, _ = _trial_import_mhi('')
+            if ok_sp:
+                pylib_path = ''
             else:
+                discovered = _discover_pylib(exe_path)
+                if discovered:
+                    pylib_path = discovered
+                else:
+                    return {'error': 'ConfigMissing',
+                            'instruction': ('未能在 PSCAD 安装目录自动发现 mhi.pscad，'
+                                            'site-packages 也无可用版本。请确认 PSCAD 5.x '
+                                            '安装完整（应有 bin/win64/mhi.zip），或 '
+                                            'pip install mhi-pscad 后重试，或手动提供 '
+                                            'mhi.pscad 库路径后再调用 init_pscad_environment。')}
+        # 保存前试导入验证：防止自动发现/指定路径在当前 Python 下不可导入
+        # （如 mhi.zip 2.2.1 依赖 Python 3.12 已移除的 distutils）时，把原本
+        # 可用的配置覆盖成坏配置。导入失败一律不保存，返回引导。
+        if pylib_path:
+            ok_imp, imp_msg = _trial_import_mhi(pylib_path)
+            if not ok_imp:
                 return {'error': 'ConfigMissing',
-                        'instruction': ('未能在 PSCAD 安装目录自动发现 mhi.pscad。'
-                                        '请确认 PSCAD 5.x 安装完整（应有 '
-                                        'bin/win64/mhi.zip），或手动提供 mhi.pscad '
-                                        '库路径后再调用 init_pscad_environment。')}
+                        'instruction': ('mhi.pscad 无法在当前 Python 下导入，配置未保存：%s'
+                                        % imp_msg)}
         r = save_config(exe_path, pylib_path)
         if r['status'] == 'success':
             r['data']['message'] = ('PSCAD 环境配置已保存。后续连接将自动使用该配置，'
@@ -246,6 +262,20 @@ def init_pscad_environment(exe_path: str, pylib_path: str = '') -> Dict[str, Any
         return _err(exc)
 
 
+def _trial_import_mhi(pylib: str) -> Tuple[bool, str]:
+    """试导入验证：确认 pylib（目录或 zip；空串=仅 site-packages 直导）可导入 mhi.pscad。
+
+    不抛异常；失败返回带指引的消息（Python ≥3.12 的 distutils 问题等）。
+    """
+    try:
+        if pylib and pylib not in sys.path:
+            sys.path.insert(0, pylib)
+        import mhi.pscad  # noqa: F401
+        return True, ''
+    except Exception as exc:
+        return False, _mhi_import_error(exc, pylib or '<site-packages>')
+
+
 def _cfg_exe() -> Optional[str]:
     """解析 PSCAD 可执行文件路径：本地配置优先，环境变量降级回退。"""
     cfg = load_config()
@@ -352,26 +382,49 @@ def _require_config() -> Optional[Dict[str, Any]]:
     return CONFIG_MISSING_RESPONSE
 
 
+def _mhi_import_error(exc: Exception, pylib: str) -> str:
+    """构造 mhi 导入失败消息；针对 Python ≥3.12 + distutils 给出明确降级指引。"""
+    ver = '%d.%d' % sys.version_info[:2]
+    hint = ''
+    if sys.version_info >= (3, 12) and 'distutils' in str(exc):
+        hint = ('。PSCAD 自带 mhi.zip 为 mhi.pscad 2.2.1，依赖 Python 3.12 已移除的 '
+                'distutils，仅支持 Python ≤3.11：请改用 ≤3.11 的 Python 作为桥接解释器，'
+                '或执行 pip install mhi-pscad 安装新版（无此依赖）')
+    return ('import mhi.pscad 失败（Python %s，pylib=%s）: %s%s'
+            % (ver, pylib, exc, hint))
+
+
 def _import_mhi() -> Tuple[bool, str]:
-    """懒加载 mhi.pscad（仅在实际需要连接 PSCAD 时调用）。
+    """懒加载 mhi.pscad：多候选导入，**绝不抛异常**。
 
-    流程：``load_config()`` 取 pylib 路径 → 动态加入 ``sys.path`` → import。
-    **配置缺失时不抛异常**，返回引导消息：先调用 ``init_pscad_environment``。
+    顺序：① 已加载则直接绑定返回；② site-packages 直接导入（pip 安装的
+    mhi-pscad 新版天然可导入）；③ 将配置/自动发现的 pylib（目录或 mhi.zip）
+    加入 sys.path 后导入。全部失败返回带指引的消息（Python ≥3.12 时提示
+    distutils 兼容问题与降级方案）。
     """
     global mhi  # 必须绑定到模块级：连接代码（_ensure_connected/_launch_pscad）
     # 依赖 mhi.pscad.connect(...)，函数内 import 只会绑定局部名导致 NameError
-    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  幂等：已加载时仅查 sys.modules 并绑定名字
+        if 'mhi.pscad' in sys.modules:
+            import mhi.pscad  # noqa: F401  幂等绑定模块级名字
+            return True, ''
+        # ② 先试 site-packages / 已有 sys.path（pip 版 mhi-pscad）
+        try:
+            import mhi.pscad  # noqa: F401
+            return True, ''
+        except Exception:
+            pass
+        # ③ 候选 pylib（配置优先，_cfg_pylib 内部已含自动发现回退）
+        pylib = _cfg_pylib()
+        if not pylib:
+            return False, MISSING_CONFIG_MSG
+        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))
+        pylib = _cfg_pylib() or ''
+        return False, _mhi_import_error(exc, pylib)
 
 
 # ---------------------------------------------------------------------------
@@ -525,6 +578,12 @@ def connect_and_load_project(project_name: str,
             try:
                 _pscad.create_case(project_name, folder=folder)
                 prj = _pscad.project(project_name)
+                # mhi 2.9.7 的 create_case 可能只在 PSCAD 会话内存建工程、不落盘
+                # （与 2.2.1 语义差异）；显式 save() 保证 folder 下生成 .pscx
+                try:
+                    prj.save()
+                except Exception:
+                    pass
             except Exception as exc:
                 return _err('create_case 失败: %s' % exc)