dsh-plugin-pscad-expert-vyma 1.0.13 → 1.0.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PSCAD Expert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # pscad-dsh-plugin — PSCAD 自动化建模与仿真控制专家插件
 
-> **版本**：1.0.13 ｜ **注册名**：`pscad-automation-expert`
+> **版本**：1.0.15 ｜ **注册名**：`pscad-automation-expert`
 > **来源**：PSCAD 知识资产固化项目（四阶段：技能文档 → 模板索引 → 工具库 → 插件打包）
 > 所有知识、工具、模板均来自真实仿真验证（L13~L19 认证轮 + R4 科研轮），**无伪造数据**。
 
@@ -76,32 +76,44 @@ Agent 维持运行 Loop。全函数 Type Hints + 中文 Docstring。
 
 ---
 
-## 三、在其他电脑的 DSH 中拉取与加载
+## 三、安装（Install）
 
-### 1. 前置环境（宿主机器必须已具备）
-- PSCAD 5.0.0 Pro（路径以实际安装为准）
-- Python 3.7+ 与 mhi.pscad 2.2.1（路径以实际安装为准；首次使用调用 init_pscad_environment 配置）
-- 路径不符时，修改 `tools/main.py` 顶部常量：`PSCAD_EXE` / `PSCAD_PORT` / `PYLIB_DIR` / `DEFAULT_FOLDER`
+以 DSH 组合包（bundle）方式从 npm 安装到目标 profile（正式使用请用 **desktop 激活 profile**，勿用已弃用的 demo）：
 
-### 2. Git 拉取
-```bash
-git clone <私有仓库地址>/pscad-dsh-plugin.git
-cd pscad-dsh-plugin
+```powershell
+# 首次安装（dsh 不在 PATH 时用宿主命令全路径调用）
+& "$env:APPDATA\DSH Desktop\host-commands\desktop\bin\dsh.cmd" plugin add dsh-plugin-pscad-expert-vyma@^1.0.14 --profile desktop
 ```
 
-### 3. DSH 挂载激活
-1. 将 `pscad-dsh-plugin/` 目录放入 DSH 插件目录；
-2. DSH 读取根目录 `plugin.yaml` 完成注册：
-   - `entry_points.tools.module = tools.main` → 挂载 11 个工具函数；
-   - `knowledge_base.preload` → 自动加载两份知识文档为系统提示词前置上下文；
-3. 首次调用前自检：
-   ```bash
-   python -c "import sys; sys.path.insert(0, 'tools'); import main; print(main.self_check())"
-   ```
-4. 激活后 Agent 可直接调用工具；工具会自动拉起/连接 PSCAD（端口 54329），
-   自动化服务崩溃时自动 `restart_pscad` 恢复。
-
-### 4. 快速上手示例
+安装会同时写入 profile 的 `dependencies` 与 `dsh.profile.bundles`（两者缺一 GUI 不加载）。重启 DSH Desktop 后，插件的 13 个 `pscad_*` 工具即注册为 Agent 可直接调用的 DSH 工具。
+
+> **前置环境**：仅需目标机安装 PSCAD 5.x 与 Python 3.7+。mhi.pscad 由插件自动发现（PSCAD 自带 `bin/win64/mhi.zip`，或 pip 版 `mhi-pscad`），**无需预置任何文件**。
+> **新机器一键安装**：可用随包脚本 `scripts/install_test_machine.ps1`（自动定位宿主命令、安装到 desktop profile、处理供应链策略、自动探测 Python）。
+
+## 四、配置（Configure）
+
+零配置开箱即用；仅以下场景需要配置：
+
+| 场景 | 方式 |
+|---|---|
+| 首次告知 PSCAD 安装路径 | 对话中调用 `pscad_init_environment(exe_path="...")`（pylib 可省略，自动发现） |
+| 覆盖默认 Python 解释器 | desktop profile 的 `cordis.patch.yml` 中为 `pscad-expert-bridge` 加 `config.pythonExecutable`（默认自动探测，通常无需） |
+| 调整工具超时 | 同上加 `config.timeoutMs`（默认 300000ms；须大于 PSCAD 冷启动等待 180s） |
+
+配置层序遵循 DSH 标准：**bundle patch → profile patch → 机器级 → CLI overlay**，后层按行覆盖（整 config 替换语义）。
+
+## 五、升级（Upgrade）
+
+```powershell
+# 关闭 DSH Desktop 后执行（官方标准通道：按 package.json 的 ^ 范围解析新版本）
+& "$env:APPDATA\DSH Desktop\host-commands\desktop\bin\dsh.cmd" plugin up dsh-plugin-pscad-expert-vyma --profile desktop
+# 或强制升到最新版：
+& "$env:APPDATA\DSH Desktop\host-commands\desktop\bin\dsh.cmd" plugin up dsh-plugin-pscad-expert-vyma --latest --profile desktop
+```
+
+> 无人值守/一键升级可用随包脚本 `scripts/self_heal_pscad_plugin.ps1`（自动查询 npm 最新版 → 退出 GUI → 更新依赖 → 核验）。误写 patch 配置后的修复见 `scripts/fix_cordis_patch.ps1`。
+
+## 六、快速上手示例（库级调用）
 ```python
 import sys
 sys.path.insert(0, r'<插件路径>\tools')
@@ -122,7 +134,7 @@ r = pat.read_output(channel='VrA', method='rms')
 
 ---
 
-## 四、使用建议（实战教训速查）
+## 七、使用建议（实战教训速查）
 
 - **模板优先**：复杂拓扑基于 `templates/` 二次开发，避免纯代码从零绘制（易坐标越界/悬空）。
 - **关键实验独立案例**：工程同名重建会残留旧 build 消息——每次用唯一案例名。
@@ -131,7 +143,7 @@ r = pat.read_output(channel='VrA', method='rms')
 - **DFT 口径**：.out 列 RMS = 相 RMS；基波提取须用系统实际频率（F0）。
 - 完整排错清单见 `knowledge/pscad_skill_core.md` 模块三。
 
-## 五、许可证与维护
+## 八、许可证与维护
 
 - 内部资产，仅供团队私有仓库使用。
 - 知识/工具/模板均来自真实仿真验证，故意异常实验保留真实诊断，禁止伪造/掩盖结果。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-pscad-expert-vyma",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "PSCAD 自动化建模与仿真控制专家插件（DSH Agent 工具库 + 基准模板 + 领域知识）",
   "type": "module",
   "main": "index.js",
@@ -23,6 +23,10 @@
   ],
   "author": "PSCAD Expert",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jionmark11-hub/PSCAD.git"
+  },
   "files": [
     "knowledge/",
     "tools/",
@@ -31,11 +35,22 @@
     "README.md",
     "index.js",
     "cordis.patch.yml",
+    "LICENSE",
+    "scripts/self_heal_pscad_plugin.ps1",
+    "scripts/install_test_machine.ps1",
+    "scripts/fix_cordis_patch.ps1",
     "!tools/__pycache__/",
     "!**/*.pyc",
     "!**/*.pyo"
   ],
+  "scripts": {
+    "verify:js": "node --check index.js",
+    "verify:py": "node scripts/verify-python.mjs",
+    "verify": "npm run verify:js && npm run verify:py",
+    "prepack": "npm run verify"
+  },
   "engines": {
+    "node": ">=18",
     "python": ">=3.7"
   }
 }

package/plugin.yaml

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

package/scripts/fix_cordis_patch.ps1

@@ -0,0 +1,59 @@
+# ============================================================
+# 修复 cordis.patch.yml（被一键安装脚本误追加导致 DSH Desktop 崩溃）
+# 用法：保存为 fix_cordis.ps1，PowerShell 中运行：
+#   powershell -ExecutionPolicy Bypass -File fix_cordis.ps1
+# ============================================================
+
+$ErrorActionPreference = 'Stop'
+try { chcp 65001 | Out-Null } catch {}
+
+$patchFile = "$env:USERPROFILE\.dsh\profiles\desktop\cordis.patch.yml"
+if (-not (Test-Path -LiteralPath $patchFile)) {
+    Write-Host "!! 未找到 $patchFile" -ForegroundColor Red
+    exit 1
+}
+
+# 1) 备份损坏文件
+$bak = "$patchFile.broken-$(Get-Date -Format yyyyMMdd-HHmmss)"
+Copy-Item -LiteralPath $patchFile -Destination $bak -Force
+Write-Host "已备份损坏文件 -> $bak" -ForegroundColor Cyan
+
+# 2) 从损坏文件里找回已写入的 pythonExecutable（若存在）
+$py = $null
+$broken = Get-Content -LiteralPath $patchFile -Raw
+if ($broken -match "pythonExecutable:\s*'([^']+)'") { $py = $matches[1] }
+if (-not $py) {
+    # 重新自动发现 Python 3.7+
+    try {
+        $pyOut = py -0p 2>$null
+        foreach ($line in $pyOut) {
+            if ($line -match '(\S+\\python\.exe)\s*$') {
+                $cand = $matches[1]
+                if (Test-Path -LiteralPath $cand) {
+                    $ver = (& $cand -c "import sys; print('%d.%d' % sys.version_info[:2])" 2>$null | Select-Object -First 1)
+                    if ($ver -and [version]$ver -ge [version]'3.7') { $py = $cand; break }
+                }
+            }
+        }
+    } catch {}
+}
+if (-not $py) {
+    $py = Read-Host "未自动找到 Python 3.7+，请手动输入其绝对路径（如 C:/Program Files/Python37/python.exe）"
+    if (-not $py) { Write-Host "!! 未提供路径，中止。" -ForegroundColor Red; exit 1 }
+}
+$py = $py.Replace('\', '/')
+
+# 3) 恢复为原始占位格式（注释 + []）。1.0.9 起插件自动探测 Python，无需任何覆盖配置
+$template = @'
+# Your patch layer for this dsh profile, applied after every bundle layer:
+# a top-level YAML array of loader patch entries (id-targeted config
+# overrides, disables, and insert lists; `!!js` expressions allowed).
+[]
+'@
+[System.IO.File]::WriteAllText($patchFile, $template, (New-Object System.Text.UTF8Encoding($true)))
+
+Write-Host ""
+Write-Host "已修复，新内容如下：" -ForegroundColor Green
+Get-Content -LiteralPath $patchFile
+Write-Host ""
+Write-Host "现在重新打开 DSH Desktop，应能正常启动。若仍报错，请把报错原文发回。" -ForegroundColor Yellow

package/scripts/install_test_machine.ps1

@@ -0,0 +1,133 @@
+# ============================================================
+# PSCAD 插件 dsh-plugin-pscad-expert-vyma@1.0.8 测试端一键安装脚本
+# 用途：安装到 desktop（正常激活）profile + 自动配置 pythonExecutable
+# 前提：本机已安装 DSH Desktop、PSCAD 5.x、Python 3.7+
+# 重要：请先关闭 DSH Desktop GUI，再运行本脚本
+# ============================================================
+
+$ErrorActionPreference = 'Continue'
+try { chcp 65001 | Out-Null } catch {}
+
+Write-Host ""
+Write-Host "================ PSCAD 插件 1.0.8 自动安装 ================" -ForegroundColor Cyan
+Write-Host "请确认：DSH Desktop GUI 已关闭？（本脚本会修改 profile 依赖目录）" -ForegroundColor Yellow
+$null = Read-Host "按回车继续，或 Ctrl+C 取消"
+
+# ---------- 第 1 步：定位 dsh 宿主命令 ----------
+Write-Host ""
+Write-Host "[1/4] 定位 dsh 宿主命令..." -ForegroundColor Cyan
+$dsh = "$env:APPDATA\DSH Desktop\host-commands\desktop\bin\dsh.cmd"
+if (-not (Test-Path -LiteralPath $dsh)) {
+    $found = Get-ChildItem "$env:APPDATA\DSH Desktop", "$env:LOCALAPPDATA", "C:\Program Files", "D:\" -Recurse -Filter 'dsh.cmd' -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ($found) { $dsh = $found.FullName } else {
+        Write-Host "!! 未找到 dsh.cmd：请确认 DSH Desktop 已正确安装。" -ForegroundColor Red
+        exit 1
+    }
+}
+Write-Host "dsh = $dsh"
+
+# ---------- 第 2 步：安装插件到 desktop profile ----------
+Write-Host ""
+Write-Host "[2/4] 安装 dsh-plugin-pscad-expert-vyma@1.0.8 到 desktop profile..." -ForegroundColor Cyan
+& $dsh plugin add "dsh-plugin-pscad-expert-vyma@^1.0.8" --profile desktop
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "安装失败(退出码 $LASTEXITCODE)，尝试处理 pnpm 供应链策略..." -ForegroundColor Yellow
+    $ws = "$env:USERPROFILE\.dsh\profiles\desktop\pnpm-workspace.yaml"
+    if (Test-Path -LiteralPath $ws) {
+        Copy-Item -LiteralPath $ws -Destination "$ws.bak-$(Get-Date -Format yyyyMMdd-HHmmss)" -Force
+        Add-Content -LiteralPath $ws -Value "`nminimumReleaseAge: 0"
+        Write-Host "已备份并追加 minimumReleaseAge: 0，重试..."
+        & $dsh plugin add "dsh-plugin-pscad-expert-vyma@^1.0.8" --profile desktop
+    } else {
+        Write-Host "!! 未找到 pnpm-workspace.yaml，无法自动处理，请把报错发回。" -ForegroundColor Red
+    }
+}
+
+# ---------- 第 3 步：自动发现 Python 并配置 pythonExecutable ----------
+Write-Host ""
+Write-Host "[3/4] 自动发现真实 Python 3.7+ 并写入 desktop profile 补丁..." -ForegroundColor Cyan
+$py = $null
+# 3a) 用 py 启动器枚举已安装版本
+try {
+    $pyOut = py -0p 2>$null
+    foreach ($line in $pyOut) {
+        if ($line -match '(\S+\\python\.exe)\s*$') {
+            $cand = $matches[1]
+            if (Test-Path -LiteralPath $cand) {
+                $ver = (& $cand -c "import sys; print('%d.%d' % sys.version_info[:2])" 2>$null | Select-Object -First 1)
+                if ($ver -and [version]$ver -ge [version]'3.7') { $py = $cand; break }
+            }
+        }
+    }
+} catch {}
+# 3b) 常见安装路径兜底
+if (-not $py) {
+    foreach ($c in @("C:\Program Files\Python37\python.exe",
+                     "$env:LOCALAPPDATA\Programs\Python\Python3*\python.exe",
+                     "C:\Python3*\python.exe")) {
+        $hit = Get-Item $c -ErrorAction SilentlyContinue | Select-Object -First 1
+        if ($hit) { $py = $hit.FullName; break }
+    }
+}
+if ($py) {
+    Write-Host "发现 Python: $py"
+    $patchFile = "$env:USERPROFILE\.dsh\profiles\desktop\cordis.patch.yml"
+    if (Test-Path -LiteralPath $patchFile) {
+        $pySlash = $py.Replace('\', '/')
+        $entry = @"
+- id: pscad-expert-bridge
+  config:
+    pythonExecutable: '$pySlash'
+"@
+        $raw = Get-Content -LiteralPath $patchFile -Raw
+        $hasEntry = $raw -match 'pscad-expert-bridge'
+        $bodyOnly = ($raw -replace '#[^\r\n]*', '').Trim()
+        if ($hasEntry) {
+            Write-Host "!! cordis.patch.yml 已有 pscad-expert-bridge 条目，请手动补充:" -ForegroundColor Yellow
+            Write-Host "  config:" -ForegroundColor Yellow
+            Write-Host "    pythonExecutable: '$pySlash'" -ForegroundColor Yellow
+        } elseif ($bodyOnly -in @('', '[]')) {
+            Copy-Item -LiteralPath $patchFile -Destination "$patchFile.bak-$(Get-Date -Format yyyyMMdd-HHmmss)" -Force
+            if ($bodyOnly -eq '[]') {
+                # 把 [] 占位行替换为条目（保持注释）
+                $new = [regex]::Replace($raw, '^\s*\[\]\s*$', $entry, 'Multiline')
+            } else {
+                # 文件为空或仅注释：直接写入条目
+                $new = $entry
+            }
+            [System.IO.File]::WriteAllText($patchFile, $new, (New-Object System.Text.UTF8Encoding($true)))
+            Write-Host "已备份并写入 pythonExecutable 配置 ✔"
+        } else {
+            Write-Host "!! cordis.patch.yml 含有其他内容且无 []，为安全起见请手动添加以下条目:" -ForegroundColor Yellow
+            Write-Host $entry -ForegroundColor Yellow
+        }
+    } else {
+        Write-Host "!! 未找到 $patchFile，请确认 desktop profile 存在。" -ForegroundColor Red
+    }
+} else {
+    Write-Host "!! 未自动找到 Python 3.7+：请先安装 Python，或在 cordis.patch.yml 手动配置 pythonExecutable。" -ForegroundColor Red
+}
+
+# ---------- 第 4 步：安装结果核验 ----------
+Write-Host ""
+Write-Host "[4/4] 核验安装结果..." -ForegroundColor Cyan
+$pkgJson = "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-plugin-pscad-expert-vyma\package.json"
+if (Test-Path -LiteralPath $pkgJson) {
+    $ver = (Get-Content -LiteralPath $pkgJson -Raw | ConvertFrom-Json).version
+    Write-Host "已安装插件版本: $ver"
+} else {
+    Write-Host "!! 未在 desktop profile 找到插件（node_modules 检查失败），请把上方输出发回排查。" -ForegroundColor Red
+}
+
+# ---------- 下一步（在 DSH 对话中完成） ----------
+Write-Host ""
+Write-Host "================ 完成，接下来（请照做） ================" -ForegroundColor Green
+Write-Host "1) 关闭本 PowerShell 窗口，重新打开 DSH Desktop（激活 profile 保持 desktop）"
+Write-Host "2) 打开 DSH 对话，粘贴执行下面两条指令（exe_path 换成你机器上 PSCAD 的实际路径）："
+Write-Host ""
+Write-Host '   pscad_init_environment(exe_path="D:/PSCAD/bin/win64/Pscad.exe")' -ForegroundColor White
+Write-Host '   pscad_self_check' -ForegroundColor White
+Write-Host ""
+Write-Host "预期结果：mhi_import: true、pylib_source: auto-discovered（或 config）、pscad_exe_exists: true"
+Write-Host "若哪一步报错，请把完整报错原文发回。" -ForegroundColor Yellow
+Write-Host ""

package/scripts/self_heal_pscad_plugin.ps1

@@ -0,0 +1,104 @@
+# ============================================================
+# PSCAD 插件自愈升级脚本：自动升到 npm 最新版
+# 用法：powershell -ExecutionPolicy Bypass -File self_heal_pscad_plugin.ps1
+# 流程：查 npm 最新版 → 比对已装版 → 彻底退出 DSH Desktop →
+#       自动改写 profile package.json 版本号并确保 bundles → 安装依赖 → 核验
+# 说明：脚本会关闭 DSH Desktop（必要时），运行完请重新打开。
+# ============================================================
+
+$ErrorActionPreference = 'Stop'
+try { chcp 65001 | Out-Null } catch {}
+
+$pkg = 'dsh-plugin-pscad-expert-vyma'
+$profileDir = "$env:USERPROFILE\.dsh\profiles\desktop"
+$pkgJson = "$profileDir\package.json"
+
+Write-Host ""
+Write-Host "======== PSCAD 插件自愈升级 ========" -ForegroundColor Cyan
+
+# [1/6] 查询 npm 最新版本
+Write-Host "[1/6] 查询 npm 最新版本..." -ForegroundColor Cyan
+$latest = (Invoke-RestMethod -Uri "https://registry.npmjs.org/$pkg/latest" -TimeoutSec 30).version
+Write-Host "最新版本: $latest"
+
+# [2/6] 检查已装版本
+Write-Host "[2/6] 检查已装版本..." -ForegroundColor Cyan
+$installed = $null
+if (Test-Path "$profileDir\node_modules\$pkg\package.json") {
+    $installed = (Get-Content "$profileDir\node_modules\$pkg\package.json" -Raw | ConvertFrom-Json).version
+}
+if ($null -eq $installed) { Write-Host "已装版本: 未安装" } else { Write-Host "已装版本: $installed" }
+
+if ($installed -eq $latest) {
+    Write-Host "已是最新版本，无需升级 ✔" -ForegroundColor Green
+    Write-Host "======================================"
+    exit 0
+}
+
+# [3/6] 彻底退出 DSH Desktop（Electron 关窗口只是隐藏，后台进程仍在）
+Write-Host "[3/6] 退出 DSH Desktop（若在运行）..." -ForegroundColor Cyan
+$procs = Get-Process -ErrorAction SilentlyContinue | Where-Object { $_.ProcessName -match '^DSH' }
+foreach ($p in $procs) {
+    Write-Host "  结束进程: $($p.ProcessName) (PID $($p.Id))"
+    Stop-Process -Id $p.Id -Force -ErrorAction SilentlyContinue
+}
+Start-Sleep -Seconds 2
+
+# [4/6] 备份并改写 profile package.json（版本号 + 确保 bundles）
+Write-Host "[4/6] 更新 profile package.json..." -ForegroundColor Cyan
+if (-not (Test-Path -LiteralPath $pkgJson)) {
+    Write-Host "!! 未找到 $pkgJson，请确认 DSH Desktop 已正确安装。" -ForegroundColor Red
+    exit 1
+}
+Copy-Item -LiteralPath $pkgJson -Destination "$pkgJson.bak-$(Get-Date -Format yyyyMMdd-HHmmss)" -Force
+$text = [System.IO.File]::ReadAllText($pkgJson, [System.Text.Encoding]::UTF8)
+
+# 4a) 依赖版本号：无论当前写的是什么，统一替换为 ^最新（^ 范围让后续 dsh plugin up 可解析新版本）
+$new = $text -replace '("dsh-plugin-pscad-expert-vyma"\s*:\s*")[^"]*(")', ('${1}^' + $latest + '${2}')
+if ($new -notmatch ('"' + $pkg + '"\s*:\s*"\^?' + [regex]::Escape($latest) + '"')) {
+    Write-Host "  !! 未在 dependencies 找到插件条目，无法自动改版本，请先把上方输出发回。" -ForegroundColor Red
+    exit 1
+}
+# 4b) 确保 dsh.profile.bundles 包含插件名（缺则补上）
+try {
+    $json = $new | ConvertFrom-Json
+    if ($null -ne $json.dsh.profile.bundles -and $json.dsh.profile.bundles -notcontains $pkg) {
+        $json.dsh.profile.bundles += $pkg
+        $new = $json | ConvertTo-Json -Depth 10
+        Write-Host "  bundles 缺少插件名，已补上 ✔"
+    } else {
+        Write-Host "  bundles 已包含插件名 ✔"
+    }
+} catch {
+    Write-Host "  !! JSON 解析失败：$($_.Exception.Message)" -ForegroundColor Red
+    exit 1
+}
+[System.IO.File]::WriteAllText($pkgJson, $new, (New-Object System.Text.UTF8Encoding($false)))
+Write-Host "  package.json 已更新（备份在 .bak-* 文件）✔"
+
+# [5/6] 安装依赖
+Write-Host "[5/6] 安装依赖..." -ForegroundColor Cyan
+Set-Location -LiteralPath $profileDir
+if (Get-Command pnpm -ErrorAction SilentlyContinue) {
+    pnpm install
+} elseif (Get-Command npm -ErrorAction SilentlyContinue) {
+    npm install
+} else {
+    Write-Host "!! 未找到 pnpm/npm，无法安装依赖。" -ForegroundColor Red
+    exit 1
+}
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "!! 安装失败（退出码 $LASTEXITCODE），请把上方输出发回。" -ForegroundColor Red
+    exit 1
+}
+
+# [6/6] 核验
+Write-Host "[6/6] 核验..." -ForegroundColor Cyan
+$now = (Get-Content "$profileDir\node_modules\$pkg\package.json" -Raw | ConvertFrom-Json).version
+if ($now -eq $latest) {
+    Write-Host "升级成功：$now ✔" -ForegroundColor Green
+} else {
+    Write-Host "!! 核验失败：实际为 $now（期望 $latest），请把上方输出发回。" -ForegroundColor Red
+}
+Write-Host "======================================"
+Write-Host "现在重新打开 DSH Desktop 即可使用最新版。"

package/tools/main.py

@@ -55,6 +55,7 @@ from __future__ import annotations
 import json
 import os
 import re
+import socket
 import sys
 import time
 import math
@@ -668,6 +669,21 @@ def connect_and_load_project(project_name: str,
         return _err(exc)
 
 
+def _port_ready(port: int, timeout_s: float = 1.0) -> bool:
+    """毫秒~秒级 TCP 端口探测：PSCAD 自动化端口是否已监听。
+
+    背景（P5 实测）：mhi-pscad 2.9.7 的 connect(timeout=5) 在 PSCAD 未运行时会
+    内部重试阻塞 ~16s，不尊重超时参数；轮询循环若直接调 connect，单次迭代
+    ≈18s，180s 名义上限实际只能尝试约 10 次。改用 socket 探测后单次迭代 ≈2s，
+    且 connect 只在端口就绪后才调用。
+    """
+    try:
+        with socket.create_connection(('127.0.0.1', port), timeout=timeout_s):
+            return True
+    except Exception:
+        return False
+
+
 def _ensure_connected() -> Tuple[bool, str]:
     """确保存在活的 mhi 连接（幂等；懒加载 mhi）。"""
     global _pscad
@@ -680,6 +696,9 @@ def _ensure_connected() -> Tuple[bool, str]:
                 return True, ''
         except Exception:
             _pscad = None
+    # 端口未监听时直接快速失败（避免 mhi connect 阻塞 ~16s）
+    if not _port_ready(PSCAD_PORT, 0.5):
+        return False, 'PSCAD 自动化端口 %d 未就绪（PSCAD 未运行？）' % PSCAD_PORT
     try:
         _pscad = mhi.pscad.connect(port=PSCAD_PORT, timeout=CONNECT_TIMEOUT_S)
         return True, ''
@@ -760,7 +779,13 @@ def _ensure_project() -> Optional[Dict[str, Any]]:
 
 
 def _launch_pscad() -> Tuple[bool, str]:
-    """拉起 PSCAD 进程并等待自动化端口就绪（崩溃恢复标准路径；懒加载 exe 路径）。"""
+    """拉起 PSCAD 进程并等待自动化端口就绪（崩溃恢复标准路径；懒加载 exe 路径）。
+
+    轮询用 socket 端口探测（毫秒级）而非直接 mhi.pscad.connect：P5 实测
+    mhi 2.9.7 的 connect(timeout=5) 在 PSCAD 未起时阻塞 ~16s（不尊重超时），
+    直接调用会让 180s 名义上限实际只能尝试约 10 次；socket 探测使单次迭代
+    ≈2s，端口就绪后才调用 connect 建立自动化连接。
+    """
     global _pscad
     exe = _cfg_exe()
     if not exe:
@@ -770,12 +795,14 @@ def _launch_pscad() -> Tuple[bool, str]:
                           '/port:%d' % PSCAD_PORT, '/splash:false'])
         deadline = time.time() + LAUNCH_WAIT_S
         while time.time() < deadline:
+            if _port_ready(PSCAD_PORT, 1.0):
+                try:
+                    _pscad = mhi.pscad.connect(port=PSCAD_PORT,
+                                               timeout=CONNECT_TIMEOUT_S)
+                    return True, ''
+                except Exception:
+                    continue
             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)