dsh-plugin-pscad-expert-vyma

v1.0.17

Published

24 days ago

PSCAD 自动化建模与仿真控制专家插件（DSH Agent 工具库 + 基准模板 + 领域知识）

0High
0Medium
0Low

jionmark11

dsh pscad agent deepseek automation

pscad-dsh-plugin — PSCAD 自动化建模与仿真控制专家插件

版本：1.0.17 ｜ 注册名：pscad-automation-expert 来源：PSCAD 知识资产固化项目（四阶段：技能文档 → 模板索引 → 工具库 → 插件打包）所有知识、工具、模板均来自真实仿真验证（L13~L19 认证轮 + R4 科研轮），无伪造数据。

本插件让 DSH（以及未来任何 AI Agent 克隆体）具备完整操作 PSCAD 5.0.0 Pro （mhi.pscad 2.2.1 自动化接口）的能力：加载成熟模板 → 二次开发布线 → 编译运行 → 结果解析，全链路可编程、可复现、可诊断。

一、目录结构

pscad-dsh-plugin/
├── plugin.yaml                  # DSH 插件注册清单（入口/知识库/模板/运行环境声明）
├── README.md                    # 本文件
├── .gitignore                   # 忽略 PSCAD 运行时产物（*.f/*.out/*.inf/*.mak 等）
├── knowledge/                   # 系统提示词前置上下文与领域知识
│   ├── pscad_skill_core.md      #   核心技能库：元件 API 字典 / 布线黄金法则 / TOP3 排错
│   └── templates_index.md       #   基准模板索引：功能摘要 / 坐标安全区 / 修改切入点
├── tools/
│   └── main.py                  # Agent 工具库主入口（11 个工具，全部返回 status/data 字典）
└── templates/                   # 已验证成功运行的基准 .pscx 拓扑（6 个）
    ├── grid_gfm_support.pscx            # 并网 GFM 支撑基准（容量/位置扫描）
    ├── fault_study.pscx           # 故障研究基准（3LG/1LG/2LG 可控故障支路）
    ├── 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 专项）

二、核心能力

工具集（tools/main.py，11 个注册函数）

| 工具 | 作用 | |---|---| | connect_and_load_project | 启动/连接 PSCAD（端口 54329）并加载 .pscx 模板工程或新建 | | add_and_configure_component | 放置元件 + 参数配置，返回 component_id 句柄（含 9 类元件默认参数模板） | | connect_ports_safely | 安全连线：动态端口坐标 + 全注册表穿线检测 + L/U 型绕行，防悬空/短路 | | connect_signal_by_name | 同名 datalabel 信号桥（数据/控制信号标准接法，零 wire） | | register_pgb | PGB 输出通道注册（写入 .out 供结果解析） | | configure_simulation | 仿真参数配置（时长/步长/采样/输出文件） | | run_simulation_and_monitor | 编译+运行+监控，完整返回 build error/warning 与 Status code | | read_output | 结果解析（.inf 通道映射 + .out 列 RMS/均值/DFT@指定频率） | | compute_sequence | Fortescue 对称分量（正/负/零序 + 比值） | | restart_pscad | 自动化服务崩溃恢复（ConnectionResetError 10054 处理） | | check_component_overlaps | 布局重叠自检（build 前诊断） |

工程标准：所有函数 try-except 包裹，成功返回 {"status":"success","data":...}，失败返回 {"status":"error","message":...,"trace":...}，绝不直接抛异常——保证 Agent 维持运行 Loop。全函数 Type Hints + 中文 Docstring。

模板资产（templates/，6 个）

grid_gfm_support：三相并网受端系统 + GFM（固定 V/f）支撑——电压/容量/位置扫描母版；含中段母线 Vmid 与受端母线 Vr 双接入点。
fault_study：在上述架构上加可控故障支路（breaker1+Rf+tbreak，TC=0.3/TO=0.4）， 3LG/1LG/2LG 只需改 tbreak 参数（每类独立案例）；短路电流已与解析公式 <1% 对照。
island_droop_controller：孤岛 GFM + 工程内嵌 Fortran 自定义组件 DROOPC（饱和下垂+虚拟惯量），研究变量集中在 DROOPC 参数（M/F0/T/FMAX/FMIN）。
line_model_pi_100km：source3 单线图 + newpi 线路空载（Ferranti 效应/线路充电对照）。
gfm_island_droop_nose：双 GFM 孤岛下垂 + 鼻点族判稳（经典同步稳定性验证）。
three_phase_cable_fault：三相同轴电缆故障（Cable_Coax + cable_interface 用法）。

每个模板的坐标安全区、修改切入点（按 Name 而非硬编码 Component ID 抓取）、以及 .pscx 内部坐标 = 网格×18 的换算规则，详见 knowledge/templates_index.md。

知识库（knowledge/）

pscad_skill_core.md：约 20 个实测元件 API 字典（含必填参数与端口）、电气/数据信号连线 SOP、坐标布局防坑规则、TOP3 血泪排错（source3 F0=60Hz 陷阱、Signal type contention、create_definition 崩溃与 Fortran 中文注释）。
templates_index.md：模板选型速查表与二次开发指南。

三、安装（Install）

以 DSH 组合包（bundle）方式从 npm 安装到目标 profile（正式使用请用 desktop 激活 profile，勿用已弃用的 demo）：

# 首次安装（dsh 不在 PATH 时用宿主命令全路径调用）
& "$env:APPDATA\DSH Desktop\host-commands\desktop\bin\dsh.cmd" plugin add dsh-plugin-pscad-expert-vyma@^1.0.14 --profile desktop

安装会同时写入 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）

# 关闭 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。

六、快速上手示例（库级调用）

import sys
sys.path.insert(0, r'<插件路径>\tools')
import main as pat

# 加载故障研究模板
r = pat.connect_and_load_project('fault_study', folder=r'<插件路径>\templates')
# 新增一个负荷电阻并连线
r = pat.add_and_configure_component('master:resistor', 600, 150,
                                    params={'R': '100.0 [ohm]'})
cid = r['data']['component_id']
r = pat.connect_ports_safely(cid, 'A', <目标id>, 'B')
# 运行并读结果
pat.configure_simulation(time_duration=0.5)
r = pat.run_simulation_and_monitor()
r = pat.read_output(channel='VrA', method='rms')

七、使用建议（实战教训速查）

模板优先：复杂拓扑基于 templates/ 二次开发，避免纯代码从零绘制（易坐标越界/悬空）。
关键实验独立案例：工程同名重建会残留旧 build 消息——每次用唯一案例名。
频率陷阱：source3 的 F 与 F0 必须成对设置，否则系统按 60Hz 运行。
下垂符号：与功率测量方向一致（本库约定 Pm>0 用 G=+m）。
DFT 口径：.out 列 RMS = 相 RMS；基波提取须用系统实际频率（F0）。
完整排错清单见 knowledge/pscad_skill_core.md 模块三。

八、许可证与维护

内部资产，仅供团队私有仓库使用。
知识/工具/模板均来自真实仿真验证，故意异常实验保留真实诊断，禁止伪造/掩盖结果。