dsh-plugin-pscad-expert-vyma 1.0.0

package/README.md

@@ -0,0 +1,137 @@
+# pscad-dsh-plugin — PSCAD 自动化建模与仿真控制专家插件
+
+> **版本**：1.0.0 ｜ **注册名**：`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_DROOPC.pscx           # 孤岛下垂 + Fortran 自定义控制器基准
+    ├── line_model_pi_100km_BergeronPI.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_DROOPC**：孤岛 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`：模板选型速查表与二次开发指南。
+
+---
+
+## 三、在其他电脑的 DSH 中拉取与加载
+
+### 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`
+
+### 2. Git 拉取
+```bash
+git clone <私有仓库地址>/pscad-dsh-plugin.git
+cd pscad-dsh-plugin
+```
+
+### 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. 快速上手示例
+```python
+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` 模块三。
+
+## 五、许可证与维护
+
+- 内部资产，仅供团队私有仓库使用。
+- 知识/工具/模板均来自真实仿真验证，故意异常实验保留真实诊断，禁止伪造/掩盖结果。

package/knowledge/pscad_skill_core.md

@@ -0,0 +1,202 @@
+# PSCAD 自动化操作核心知识库（pscad_skill_core）
+
+> **定位**：未来 AI 操作 PSCAD（mhi.pscad 2.2.1 + PSCAD 5.0.0 Pro + GFortran）的"大脑"。
+> 全部条目来自真实执行成功的自动化脚本（L13~L19 认证轮 + R4 科研轮）与失败诊断记录。
+> **铁律**：一切参数名/端口名/单位语义均经实测验证；未验证的语义标注 UNKNOWN，禁止臆测。
+
+---
+
+## 模块一：核心元件 API 字典（Component Dictionary）
+
+**通用创建语法**（所有元件）：
+```python
+c = main.create_component('master:<defn>', x, y, orient=N, **params)
+ports = c.ports()          # dict: 端口名 -> Port(x, y, dim, type, ...)
+params = c.parameters()    # 当前参数值
+```
+- `orient`：0=0° / 1=90° / 2=180° / 3=270°（步进取模 4）。**端口绝对坐标随 orient 变化，必须用 `c.ports()` 取，严禁手写坐标**。
+- 带单位参数写法：`'100.0 [kV]'`、`'0.05 [s]'`、`'10.0 [ohm]'`、`'50.0 [Hz]'`、`'0.2314 [H]'`。
+- **实例名参数 `Name=` 与组件参数重名时以组件参数为准**（如 ammeter 的 Name 即输出信号名，直接传入 `Name='IsA'` 即可）。
+
+### 1.1 电源类
+
+| 元件 | 库名 | 关键参数（实测） | 端口（orient=1 示例） | 备注 |
+|---|---|---|---|---|
+| 单相受控源 | `master:source_1` | `Cntrl`(0=INTERNAL/'EXTERNAL')、`Grnd`(1)、`Vm`(相电压 **RMS kV**)、`f`(Hz)、`R`(源内阻 ohm)、`Ph`(相位 deg) | `NA`/`NB`；EXTERNAL 时追加 `Mag`、`freq` | **Mag 端口单位=峰值 kV**（132.8kV 相RMS → 187.8）；freq 端口=Hz，**直接驱动源频率**（并网下垂陷阱见模块三） |
+| 三相源（单线图） | `master:source3` | `Vm`(基准电压 L-L RMS)、**`F`(源频率) 与 `F0`(额定/参考频率) 必须成对设置**、`Es`(输出 L-L kV)、`MVA`、`View`('SINGLE_LINE')、`R1s`(pu, on Vbase²/MVA)、`L1p`、`Tc`、`Ctrl`('FIXED'/'EXTERNAL') | 单线图：`N`(dim1)、`N3`(dim3)；EXTERNAL：`EV`(V)、`EF`(Hz)、`EP`(相位)、`Loop`(Integer) | **F0 默认 60.0——不设则系统 60Hz 运行**（模块三 TOP1）。EXTERNAL 的 EV/EF/EP/Loop 在单线图下为 dim3（除 Loop dim1） |
+
+### 1.2 线路 / 电缆
+
+| 元件 | 库名 | 关键参数（实测） | 端口 | 备注 |
+|---|---|---|---|---|
+| 集中参数 π 线路 | `master:newpi` | `len`(m)、`PU`('R_XL_XC_OHM_')、`F`(50.0)、`Rp`(Ω/m)、`Xp`(Ω/m)、`Bp`(每单位长度 µS，实证 B∝len) | `N1`/`N2`(三相端子)、`G`(屏蔽，**须独立接地**) | **三相组件**：单相链穿越报维度不匹配，须在 source3 单线图下使用。实证换算：R_total=Rp×len、X_total=Xp×len、B_eff(mS)=Bp×len(m)×2.668e-8（8/3 因子来源 UNKNOWN） |
+| 同轴电缆 | `master:Cable_Coax` | `CABNUM`、`Y`/`X`(坐标)、`LL`/`LC`、`CONNAM1..3`、`R1..R9`、`RHOC/RHOS/RHOA/RHOO`、`PERMC/PERMS/PERMA/PERMO`、`EPS1..4`、`CROSSBOND`、`GROUPNO`、`FLT`、`T3..T9`、`OHC` | 经 `master:cable_interface` 接入（`Name` 配对 + `NCAB=3`） | 同轴 Z0≈Z1；电缆故障公式见模块三 |
+| 三相电缆接口 | `master:cable_interface` | `Name`(跨端同名匹配)、`NCAB`(3) | `C1/C2/C3`(相)、`G` | 接口 G 端口须接 ground（否则 GND 1!=3） |
+
+### 1.3 负荷
+
+| 元件 | 库名 | 关键参数（实测） | 端口 | 备注 |
+|---|---|---|---|---|
+| 电阻 | `master:resistor` | `R`('242.6 [ohm]') | `A`/`B` | 单线图下=每相电阻；A 端口=锚点，B=锚点+2（**手写坐标易错，用 ports()**） |
+| 电感 | `master:inductor` | `L`('0.2314 [H]') | `A`/`B` | 50Hz 仿真下 X=2π×50×L 实测精确（与 60Hz 标定无关） |
+| 三相固定负荷 | `master:fixed_load` | `PQdef`(choice '0'/'1')、`Parts`('1'/'2'/'3') | 三相 | PQdef 取值 0=Rated Voltage / 1=Initial Terminal Voltage（'2' 非法，报 cannot be assigned） |
+| 恒阻抗三相负荷 | `master:resistive_load` | `PQdef`、`Parts`、R/P 值 | A/G | G=星点；SD 不影响线电流 |
+
+### 1.4 开关 / 故障
+
+| 元件 | 库名 | 关键参数（实测） | 端口 | 备注 |
+|---|---|---|---|---|
+| 单相断路器 | `master:breaker1` | `RON`('0.01')、`ROFF`('1.0E6')、`NAME`(控制信号名)、`IBR`(电流输出名) | `A`=(x+2,y)、`B`=(x-2,y)（**同行！水平直连必穿另一端口，须绕行**） | 控制：同名 datalabel → tbreak Sig |
+| 定时开关 | `master:tbreak` | **`TC`=合闸时刻（TC 后闭合）、`TO`=分闸时刻（TO 后断开）、`REP`=0** | `Sig`(Integer 0/1) | 故障投入：TC=0.3/TO=0.4；不投入：TC=1.0/TO=0.0；TC=TO 非法。**tbreak 状态跨案例残留——故障矩阵必须独立案例** |
+| 故障选相器 | `master:tpflt` | `TC`/`TO`/`REP`；G=YES 时 NN 悬空（接 external ground 报 GND 1!=3） | 三相端子+信号 | 单相故障抽取用 A/B/C 相选择；**禁三相故障元件冒充单相** |
+
+### 1.5 测量 / 信号
+
+| 元件 | 库名 | 关键参数 | 端口 | 备注 |
+|---|---|---|---|---|
+| 电流表 | `master:ammeter` | `Name`(=输出信号名) | `N1`(锚点)/`N2`(+2) | 串联；**方向约定决定功率符号**（N1→N2 为标称方向） |
+| 对地电压表 | `master:voltmetergnd` | `Name` | `N1`(锚点，测量 tap 点) | 并联 tap；自身带地参考，无需额外接地 |
+| 常量 | `master:const` | `Value`、`Dim`(1/2/3) | `OUT`(锚点+2) | **输出信号名为空**——必须用 datalabel 同名占住 OUT 才能命名（模块二） |
+| 乘法器 | `master:mult` | 无 | `IN1`(x-2,y)、`IN2`(x,y+2)、`OUT`(x+2,y) | 瞬时功率 Ig×Vg |
+| 一阶惯性 | `master:realpole` | `T`(s)、`G`(增益，下垂用 **+m** 见符号约定)、`YO`(初值) | `I`(x-2,y)、`O`(x+2,y) | 可带限幅（Limit/Max/Min 参数） |
+| 求和/差分 | `master:sumjct` | `A`~`G`(1=加/0=禁用/-1=减)、`F`('SUBTRACT')、`Dim`、`DPath`('REAL') | `IND`(x-2,y)、`INF`(x,y+2)、`OUT`(x+2,y) | Fset=IND−INF |
+| 数据标签 | `master:datalabel` | `Name`(=信号名) | `A`(**=锚点本身**) | 同名互连（无线）；**与端口连接须同坐标（0 距离）** |
+| 绘图块 | `master:pgb` | `Name`(=输出通道名) | `Signl` 输入 | 通道写入 *.out；**锚点不能与断路器/电容等元件锚点重叠**（否则通道丢弃） |
+| 接地 | `master:ground` | 无 | `A`(锚点) | 端口名是 'A' 不是 'G' |
+
+### 1.6 自定义组件（Fortran）
+
+| 元件 | 库名 | 关键参数 | 端口 | 备注 |
+|---|---|---|---|---|
+| 自定义组件 | `工程名:DEFN`（如 `mycase:DROOPC`） | `M`(Hz/MW)、`F0`、`T`、`FMAX`/`FMIN`（按 form 定义） | 按 svg 定义（如 `I`/`O` 于 x=±36） | 创建：`prj.create_definition(xml)`（UserCmpDefn，见模块三崩溃规避）；Fortran 段注释**必须 ASCII** |
+
+**已实现自定义组件参考（DROOPC，饱和下垂+虚拟惯量）**：
+```xml
+<Definition classid="UserCmpDefn" name="DROOPC" ...>
+  <form>... 每个 category 末尾必须 <cond><![CDATA[true]]></cond> ...</form>
+  <svg viewBox="-200 -200 200 200">
+    <port model="Transfer" name="I" x="-36" y="0" dim="1" mode="Input" type="Real"/>
+    <port model="Transfer" name="O" x="36" y="0" dim="1" mode="Output" type="Real"/>
+  </svg>
+  <script>
+    <segment name="Fortran"><![CDATA[#STORAGE REAL:5
+#FUNCTION REAL DROOPC
+      $O = REALPOLE(0, 1, 1, 1.0, $T, $F0 - $M * $I, 0.0, $FMIN, $FMAX)]]></segment>
+    <segment name="Computations"><![CDATA[INTEGER NREAL = 5
+INTEGER NINTEGER = 2]]></segment>
+  </script>
+</Definition>
+```
+（REALPOLE 签名：`REALPOLE(reset, 1, limit, G, T, I, YO, Min, Max)`，稳态初始化=输入值）
+
+---
+
+## 模块二：拓扑与连线黄金法则（Wiring & Topology SOP）
+
+### 2.1 端口识别与连接逻辑
+1. **一切坐标来自 `c.ports()`**——端口绝对坐标 = 锚点 + orient 方向偏移。`resistor.A` 在锚点、`resistor.B` 在锚点+2；`breaker1.A`=x+2、`B`=x-2。**手写假定坐标是悬空/穿线短路的第一来源**。
+2. **wire 段经过任何端口坐标 = 自动连接**。因此布线黄金律：**wire 段不得经过任何非目标端口坐标**（含组件图形内部端口）。斜线会自动补拐点，补出的路径可能穿过端口——**所有 wire 必须显式给出水平/垂直拐点**。
+3. 端口同坐标 = 自动连接（无需 wire）。L15 布局依赖此特性：`mult.OUT=(x+2,y)` 与 `realpole.I=(x+2,y)` 同点即连通。
+4. 同名 datalabel 之间无线连接（信号广播）。datalabel 与端口**同坐标（0 距离）**放置 = 吸附连接并**把该端口信号重命名为 datalabel 的 Name**。
+
+### 2.2 电气信号 vs 数据信号
+| 类别 | 元件 | 操作差异 |
+|---|---|---|
+| 电气（Electrical） | source_1.NA、resistor.A/B、ammeter.N1/N2、newpi.N1/N2、ground.A | 用 `create_wire` 显式连线；**必须形成完整回路并有接地路径**，否则 "No branches to ground"/"Unresolved current path" |
+| 数据/控制（Signal） | const.OUT、realpole.O/I、sumjct.IND/INF/OUT、mult.IN1/IN2/OUT、source Mag/freq、datalabel.A | **优先用同名 datalabel 桥接**（L15 模式）：源端口侧放 datalabel 'X'（同坐标占住），目标端口侧放同名 datalabel 'X'（同坐标占住），同名互连。信号链无需 wire |
+| 表计通道 | ammeter.Name / voltmetergnd.Name | 通道即信号名：任何 datalabel 与其同名即可取用该测量值（如 mult 输入） |
+
+**信号链标准模式（GFM 下垂链，逐元件端口相对偏移）**：
+```
+Ig×Vg → mult(x,y)[IN1=(x-2,y) 'IgA', IN2=(x,y+2) 'VgA', OUT=(x+2,y)]
+→ realpole(x+4,y)[I=(x+2,y)=mult.OUT 同点, O=(x+6,y) 'PmA']
+→ realpole(x,y-35)[I=(x-2,y-35) 'PmA', O=(x+2,y-35) 'FkA']
+→ sumjct(x+6,y-35)[IND=(x+4,y-35)←const50.OUT 同点, INF=(x+6,y-33) 'FkA', OUT=(x+8,y-35) 'FsetA']
+→ datalabel 'FsetA' 占住 source_1.freq 端口
+```
+**下垂符号约定**：ammeter N1→N2 为标称方向；Ig 从 GFM 流出（正向）时 Pm=Ig×Vg>0 → 用 **G=+m** 得 Fset=50−mP（等效 L15 的 G=−m@Pm<0；物理链相同，符号随测量约定，先测后定）。
+
+### 2.3 坐标布局防重叠/防悬空
+1. **组件图形尺寸不可忽略**：source_1 图形高 >60 格、realpole 高约 30 格。**同 x 列垂直间距须 ≥35；相间布局间距 ≥300**（否则图形重叠 → 端口信号被污染，报 type mismatch，如 'MagB type mismatch at connection Mag'）。
+2. **breaker1 的 A/B 端口同行**（y 相同）：任何"水平线接 A"都会穿过 B 端口造成 A-B 短路。**必须绕行**：A 侧绕行上方（如 ammeter.N2 → (x, y-80) → (A.x+2, y-80) → (A.x+2, A.y) → (A.x, A.y)），B 侧绕行下方（B → (B.x, y-20) → (RfA.x, y-20) → RfA）。**上下分层绕行且各层 y 不同，避免绕行线互相交叉**（wire 交叉=连接）。
+3. **pgb/datalabel 锚点不得与任何元件锚点重叠**（否则通道被丢弃或 type mismatch）；pgb 输出区（x≈850+）与电路区隔离。
+4. **datalabel 间距**：端口间距 ≤2 时 datalabel 会串扰相邻端口（同列 3 个 datalabel 垂直间距须 >2）。
+5. **tap 抽头**：从节点水平引出 → 垂直 → 水平到达目标端口，全程避开其他端口行；tap 起点用 `ports()` 动态取。
+6. **故障支路标准布局**（L19 验证）：受端节点 tap → ammeter(N1) → breaker1 → Rf(0.001Ω) → ground；tbreak.Sig 放 datalabel 'BRKx'，breaker1 NAME='BRKx' 同名控制。**故障矩阵每类独立案例**（tbreak 状态残留）。
+
+### 2.4 仿真运行 SOP
+```python
+pscad.create_case(name, folder=...)   # 独立案例（防残留）
+prj = pscad.project(name)
+prj.parameters(time_duration=0.5, time_step=10.0, sample_step=50.0,
+               PlotType=1, output_filename='%s.out' % name)
+prj.save(); prj.build()
+errs = [m for m in prj.messages() if m.status == 'error']   # build 检查
+prj.run()
+# 等待: 轮询 prj.output() 出现 r'Status code = \d+'
+# 输出: <name>.gf46/*.inf (PGB 通道映射) + *_01.out (每列=每相瞬时值, 列 RMS=相 RMS)
+```
+- **PGB 输出格式**：每通道每相 1 列瞬时值（按 F0 频率旋转的相量投影），**任意列 RMS = 相 RMS**；DFT 提取基波必须用**系统实际频率（F0）**，否则幅度≈0。
+- **output_filename 只写文件名**；工作目录自动为 case 目录。
+- `messages()` 按工程 scope 累积——**同名工程重建会残留旧错误**，改参/重跑必须新建唯一案例名。
+
+---
+
+## 模块三：血泪排错清单（Troubleshooting Memory）
+
+### TOP 1：系统在 60Hz 运行（source3 F0 陷阱）——最隐蔽、污染面最大
+- **报错表现**：无任何报错！但 ① 电流与 50Hz 理论差 2.7%；② I-V 相角 19.79°=atan(2π×60×L/R)（60Hz 理论精确匹配）；③ 对表计通道 DFT@60Hz 幅度=√2×RMS、@50Hz≈0。
+- **根因**：`master:source3` 参数表含 **F（源频率）与 F0（内部额定/参考频率，默认 60.0）**。只设 `F='50.0'` 时源看似 50Hz，但表计相量旋转与元件标定仍按 F0=60Hz；实测 FFT 主频就是 60Hz。`source_1` 无此问题（f 参数直接生效）。
+- **修复**：`F='50.0 [Hz]'` 与 `F0='50.0 [Hz]'` **成对设置**（或 `F='$(f)'`+全局替换 `gs['']['f']='50.0 [Hz]'`，但 F0 仍要显式设）。
+- **教训**：频率相关元件（source3/newpi 的 F）的参数必须显式核对；"无报错但数值对不上"优先查频率与单位语义。
+
+### TOP 2：信号连接失败（"Signal '' type contention" / "Input port 'X' is floating"）——最常见
+- **报错表现（Python 层无异常，build 层）**：
+  - `Signal '' type contention: Another signal of a different type, but bearing the same name, already exists.`（空名信号冲突）
+  - `Input port 'EV'/'A' is floating. A signal source must be provided.`（信号悬空）
+  - `Signal 'EFsig' type contention` / `dimension mismatch -> 1 != 3`（端口类型/维度错配）
+- **根因**（四类，按出现频率）：
+  1. **const 输出信号名为空**：多个 const 直接 wire 到端口 → 多个空名信号同名冲突。**datalabel 必须同坐标（0 距离）占住 const.OUT 才能命名**；偏移 1-2 格不吸附。
+  2. **datalabel 只放一端**：同名互连需要**双端 datalabel**（源端口侧 + 目标端口侧各一）。
+  3. **datalabel 放组件图形内**：吸附到组件内部空名信号 → 空名/类型冲突（端口侧 datalabel 放端口坐标上，勿放锚点/图形区）。
+  4. **维度错配**：source3 单线图下 EV/EF/EP 端口是 dim3（Loop 是 dim1）；const 用 `Dim=3` 匹配。pslx 里 `dim="1"` 是显示语义，实测报错为准。
+- **修复**：按模块二 2.2 的"双 datalabel 同坐标桥接"重做信号链；维度按报错 `1 != 3` 提示调整 `Dim`。
+- **教训**：信号连接问题先查"datalabel 是否同坐标占住端口"，再查维度；build 错误按 `[元件名]` 归属定位。
+
+### TOP 3：PSCAD 自动化服务崩溃（ConnectionResetError 10054）与 Fortran 编译失败
+- **报错表现**：
+  - Python 层：`ConnectionResetError: [WinError 10054] 远程主机强迫关闭了一个现有的连接`（后续所有 mhi 调用失败，须重启 PSCAD）。
+  - build 层：`Error: Unexpected end of file in 'Main.f'` / `make: *** [Main.o] Error 1`。
+- **根因**：
+  1. **create_definition 传入的 UserCmpDefn XML 的 form 段格式不完整**——**每个 `<category>` 末尾缺 `<cond><![CDATA[true]]></cond>`** → PSCAD 解析定义时崩溃（10054）。
+  2. **组件定义访问**（`c.definition.script/xml/ports()` 大对象）也会触发 10054——避免访问 definition 大对象。
+  3. **Fortran 段注释含中文**：GBK 编码损坏生成的 Main.f（注释行变成乱码截断）→ "Unexpected end of file"。
+- **修复**：① form 每个 category 补 `<cond>`；崩溃后 `Stop-Process Pscad` + 重启（带 `/startup:au /port:54329 /splash:false`）+ 等 25-30s 重连；② Fortran 注释**全部 ASCII**；③ 用 `prj.messages()` 的 build 错误 + 检查 `.gf46/Main.f` 定位生成代码。
+- **教训**：自定义组件 XML 逐段对照 master.pslx 提取的模板（realpole/sumjct 定义）；Fortran 段零中文。
+
+---
+
+## 附：高频数值/语义速查（实测定论）
+
+| 项 | 值 |
+|---|---|
+| source_1.Vm | 相电压 RMS（kV）；Mag 端口=峰值 kV（×√2） |
+| source3.Vm/Es | L-L RMS kV；R1s 单位 pu（on Vbase²/MVA，230kV/1000MVA→52.9Ω 基准，0.1pu=5.29Ω） |
+| newpi 换算 | R=Rp×len；X=Xp×len；B_eff(mS)=Bp×len(m)×2.668e-8（实测，8/3 因子 UNKNOWN） |
+| tbreak | TC=合闸时刻、TO=分闸时刻；TC=TO 非法；状态跨案例残留 |
+| 故障公式 | 3LG: I=E/Z1；1LG: I=3E/(2Z1+Z0)；2LG: I=√3E√(Z2²+Z2Z0+Z0²)/(Z1Z2+Z1Z0+Z2Z0)；同轴 Z0≈Z1 |
+| 短线路 | time_step < 传播时间（1km≈3.415µs），与 linc 无关 |
+| 下垂 | Fset=50−m·P；并网必须锁相（freq 固定），孤岛才用下垂；m·P 超限需 FMIN/FMAX |
+| .out 列 | 每通道每相 1 列，列 RMS=相 RMS；DFT 用 F0 频率 |
+| datalabel | 端口=锚点；与端口同坐标连接；双端同名互连 |
+| source_1 图形 | 高 >60 格——同列垂直间距 ≥35、相间距 ≥300 |
+
+## 附：环境与启动（验证过的最小可靠路径）
+```powershell
+# 启动（必须带 /port:54329，否则自动化不监听）
+Start-Process <PSCAD_INSTALL_DIR>\bin\win64\Pscad.exe -ArgumentList "/startup:au","/port:54329","/splash:false"
+# 连接
+pscad = mhi.pscad.connect(port=54329, timeout=20)
+```
+- Python 3.7.8 + mhi.pscad 2.2.1（`sys.path.insert(0, r'<MHI_PYLIB_DIR>')` 路径含 em-dash 字面量）。
+- 崩溃恢复：Stop-Process → 重启 → 等 25-30s → 重连。

package/knowledge/templates_index.md

@@ -0,0 +1,104 @@
+# PSCAD 基准模板索引（templates_index.md）
+
+> **定位**：供未来 AI 克隆体"从成熟 .pscx 二次开发"而非纯代码从零绘制的模板底座。
+> **筛选标准**（严格）：① 真实存在于磁盘；② 完整构建成功（同目录 `.gf46/` 内含 `<case>.exe`）；③ 成功运行 EMTDC（`.gf46/` 内含 `*_01.out` 输出文件，数据可解析）。
+> **坐标约定**：下文所有坐标为 **mhi 网格坐标**（`c.ports()` 同坐标系）；`.pscx` 文件内部坐标 = 网格坐标 ×18（解析时除以 18 还原）。主画布为工程自带的 `Main` 页面。
+
+---
+
+## 1. [grid_gfm_support.pscx]
+
+- **文件位置**：`templates/grid_gfm_support.pscx`（仓库内副本；源工程含 `.gf46` 编译产物，已验证成功运行）
+- **功能摘要**：**三相并网受端系统 + 构网型（GFM）支撑基准**——230kV 送端（3×source_1）经**两段 12.5km R-L 线路**（共 50km）供电至受端母线，负荷为恒阻抗 200MW+j60MVar；GFM（3×source_1 EXTERNAL 固定 V/f=187.8kV 峰值/50Hz）经 Xg=0.0421H（S_GFM=600MVA，0.15pu）接入受端母线。用于容量/位置扫描与电压支撑研究（R4-P5 系列的成功母版，S0~S600、P1/P2 共 7 个变体均由同一脚本生成）。
+- **已固化的核心拓扑**（Main 画布，三相各占一行）：
+  | 元件（Name） | 类型 | 位置（网格） |
+  |---|---|---|
+  | SrcA/B/C | source_1，Vm=132.8kV，Ph=0/-120/+120，f=50Hz | (60, 150/450/750) |
+  | IsA/B/C | ammeter（送端电流） | (130, 150/450/750) |
+  | R1A/B/C + L1A/B/C | 线路段1（R=0.858Ω + L=0.0334H） | (190, 230, 150/450/750) |
+  | **VmidA/B/C** | voltmetergnd（**馈线中段母线**，P2 接入点） | (280, 110/410/710) |
+  | R2A/B/C + L2A/B/C | 线路段2 | (330, 370, 150/450/750) |
+  | **VrA/B/C** | voltmetergnd（**受端母线**，P1 接入点） | (420, 110/410/710) |
+  | RLA/B/C + LLA/B/C | 负荷（R=242.6Ω + L=0.2314H） | (480, 530, 150/450/750) |
+  | GfmA/B/C | source_1 **Cntrl=1(EXTERNAL)** | (60, 60/360/660) |
+  | XgA/B/C | 电感（并网电抗，0.0421H@600MVA） | (130, 60/360/660) |
+  | IgA/B/C | ammeter（GFM 输出电流） | (100, 60/360/660) |
+  | CMA/B/C + CFA/B/C | const（Mag=187.8 峰值 kV、freq=50） | (200, 230, 0/300/600) |
+  | MagA/B/C、freqA/B/C | datalabel 双端桥（const→GFM 端口） | (58~232, 0~662) |
+  | IsA/VmidA/VrA/IgA… | pgb 输出通道（12 通道） | (900~1000, 100~190) |
+- **二次开发与扩展指南**：
+  - **坐标安全区**：新增元件建议 x∈[600, 850]（主链右侧、pgb 区左侧的空带）、y 与所在相行对齐（150/450/750）；GFM 控制链扩展放 x∈[250, 450]、y∈[0, 60]（每相上方空带）；**禁止** x∈[850, 1050]（pgb 区）与各元件锚点 20 格内。
+  - **修改切入点**：
+    - **受端母线抓取**：`main.find_first('VrA')`（voltmetergnd，其 N1 端口即母线节点坐标）；**中段母线**：`find_first('VmidA')`。
+    - **GFM 控制入口**：Mag 信号 `datalabel 'MagA'`（双端：const 侧 (202,0) + GFM 端口侧 (58,60)）——改 `find_first('CMA')` 的 Value 即改电压幅值；freq 同理（`CFA`）。
+    - **负荷/线路改参**：`find_first('RLA').parameters(R='... [ohm]')`、`find_first('L1A')`。
+    - **容量扩展（换 S_GFM）**：改 `XgA/B/C` 的 L（0.15pu 换算：L=0.15×132.8²/(2π·50·S_ph)、S_ph=S/3）。
+    - **Component ID**：pscx 内 `<User classid="UserCmp" id="...">` 为实例 id（如 SrcA=1204363254），**重新打开工程后 id 可能变化**——稳定做法是 `find_first('Name')` 或 `find_all(defn=...)` 按定义名+Name 过滤，勿硬编码 id。
+
+---
+
+## 2. [fault_study.pscx]
+
+- **文件位置**：`templates/fault_study.pscx`（仓库内副本；`.gf46` 含 exe + `*_01.out`，故障数据完整）
+- **功能摘要**：**三相并网受端系统 + GFM + 受端母线可控故障支路**——在模板 1 架构（S_GFM=300MVA，Xg=0.0843H）之上，每相受端母线挂接 **ammeter→breaker1→Rf(0.001Ω)→ground** 故障支路，由 **tbreak（TC=0.3s 投入 / TO=0.4s 切除）** 控制；故障相选择（3LG/1LG/2LG）由 tbreak 参数裁剪实现。R4-P6 六案例（S0/S300 × 3LG/1LG/2LG）的成功母版，短路电流与 L19 定论公式 <1% 对照。
+- **已固化的核心拓扑**（在模板 1 基础上新增/差异项）：
+  | 元件（Name） | 类型 | 位置（网格） |
+  |---|---|---|
+  | IfltA/B/C | ammeter（故障支路电流，tap 自受端母线 Vr 节点） | (1116/18≈62→ **网格 (620, 130/370/730)**) |
+  | breaker1（NAME=BRKA/B/C） | 故障投入开关（RON=0.01/ROFF=1E6） | (1260/18=70→ **网格 (700, 90/330/690)**) |
+  | RfA/B/C | 故障电阻 0.001Ω | (760, 90/330/690) |
+  | tbreak（TC=0.3/TO=0.4） | 定时控制 → datalabel `BRKA/B/C` → breaker1.NAME | (820, 90/330/690) |
+  | GfmA/B/C | source_1 EXTERNAL（**Cntrl=1**）| (60, 60/360/660) |
+  | XgA/B/C | 0.0843H（300MVA 档） | (130, 60/360/660) |
+  | VrA/B/C | 受端母线 | (390, 110/410/710) |
+- **二次开发与扩展指南**：
+  - **坐标安全区**：故障支路区 x∈[600, 860]、y∈[70, 130]（A 相，B/C 相 +300/+600）已占；新故障类支路（如附加 Rf 档位）放 x∈[860, 1000]；控制信号区 x∈[250, 450]。
+  - **修改切入点**：
+    - **故障时序/类型**：改 `find_first('tbreak')`（按 NAME 或用 `find_all('master:tbreak')` 按 TC/TO 过滤）的 `TC/TO`；**1LG=只留 A 相 TC=0.3、2LG=B/C、3LG=三相**（非故障相设 TC=1.0/TO=0.0）。**每个故障类型必须独立案例**（tbreak 状态残留）。
+    - **故障电阻**：`find_first('RfA').parameters(R=...)`。
+    - **故障电流通道**：`find_first('IfltA')`（ammeter，Name 即输出通道）。
+    - **恢复时间测量**：VrA/B/C 通道在 .out 中按 PGB 映射取列（列 RMS=相 RMS）。
+  - **布线警示（已踩坑固化）**：breaker1 的 A/B 端口同行——接 A 端口必须绕行上方（y-60 行），接 B 端口绕行下方（y-20 行），且上下层绕行线 y 必须不同避免交叉；此模板的绕行路径即标准答案，二次开发照抄其 Wire 拓扑即可。
+
+---
+
+## 3. [island_droop_controller.pscx]
+
+- **文件位置**：`templates/island_droop_controller.pscx`（仓库内副本；`.gf46` 含 exe + `*_01.out`，Fset 序列完整）
+- **功能摘要**：**孤岛（频率自由）构网型系统 + Fortran 自定义控制器（DROOPC）**——GFM（3×source_1 EXTERNAL）经 Xg 单独带恒阻抗负荷；频率控制由**工程内自定义组件 `island_droop_controller:DROOPC`（饱和下垂+虚拟惯量）**实现：P 测量（Ig×Vg→mult）→ DROOPC（Fset=clamp[一阶(T)·(F0−M·P)]）→ freq 端口；Mag 固定 187.8kV。R4-P4 三案例（静态/限幅/闭环）的成功母版，Fset=50−mP 三档验证 0.2% 精度。
+- **已固化的核心拓扑**（Main 画布，三相）：
+  | 元件（Name） | 类型 | 位置（网格） |
+  |---|---|---|
+  | GfmA/B/C | source_1 EXTERNAL | (60, 60/360/660) |
+  | XgA/B/C | 0.0843H | (130, 60/360/660) |
+  | IgA/B/C | ammeter（GFM 电流） | (100, 60/360/660) |
+  | VgA/B/C | voltmetergnd（GFM 端电压，tap 于 Xg 出口） | (170, 20/320/620) |
+  | mult（Ig×Vg） | 瞬时功率 → Pm 信号 | (300, 20/320/620) |
+  | **DC A/B/C（DROOPC 实例）** | `island_droop_controller:DROOPC`（M/F0/T/FMAX/FMIN） | (340, 20/320/620) |
+  | FsetA/B/C | datalabel 双端（DROOPC.O → GFM.freq 端口） | (348/58, 20/320/620) |
+  | CMA/B/C | const（Mag=187.8） | (300, -40/260/560) |
+  | VrA/B/C + RLA/B/C + LLA/B/C | 受端母线 + 负荷 | (390, 480, 530, 150/450/750) |
+  | pgb 通道（Vr/Ig/Vg/Fset ×3） | 12 通道 | (900~1040, 100~220) |
+- **二次开发与扩展指南**：
+  - **坐标安全区**：控制链区 x∈[290, 420]、y∈[-40, 40]（A 相，+300/+600 为 B/C）已占；新控制器（限流/惯量增强）建议 x∈[420, 600] 或复用 DROOPC 参数。
+  - **修改切入点**：
+    - **控制器调参（最常用）**：`find_all('island_droop_controller:DROOPC')` 或 `find_first('DCA')` → `parameters(M=0.01, F0=50.0, T=0.3, FMAX=52.0, FMIN=47.0)`——**m 与限幅即研究变量**。
+    - **P 测量链**：mult 输入信号 `IgA`/`VgA`（表计 Name 即通道，datalabel 双端桥接）。
+    - **频率输出**：FsetA datalabel 对——改 DROOPC 参数即可，无需动线。
+    - **组件定义再生成**：DROOPC 的 XML 定义在脚本 `r4_p4_v1.py` 的 `droopc_xml()` 中；如需新增端口/参数，改 XML 后重新 `prj.create_definition(...)`（**form 每个 category 末尾必须保留 `<cond><![CDATA[true]]></cond>`，Fortran 注释禁中文**——否则 PSCAD 服务崩溃/编译失败）。
+  - **扩展为孤岛频率动态研究**：在 Vr 母线加负荷阶跃（tbreak+电阻支路），观察 Fset 一阶过渡（T=0.3 生效）——模板的 Fset 通道已就绪。
+
+---
+
+## 备选池（同样验证成功，未入选原因）
+- `line_model_pi_100km.pscx`（source3 单线图 + newpi 空载充电/Ferranti）——结构简单（4 元件），作为"最小线路模板"备用。
+- `gfm_island_droop_nose.pscx`（双 GFM 孤岛下垂+鼻点）——历史经典，但坐标体系为旧布局（y 间距小），易与新代码冲突。
+- `three_phase_cable_fault.pscx`（三相电缆故障，Cable_Coax+cable_interface）——电缆专项模板，无 GFM/控制链。
+- 本仓库 `templates/` 收录 6 个验证通过的模板；PSCAD 主库（master.pslx）为安装自带资产，不入库。
+
+## 选型速查
+| 需求 | 用哪个模板 |
+|---|---|
+| 并网电压/容量/位置扫描 | **grid_gfm_support**（改 Xg 三处 + RLA 负荷） |
+| 故障/短路/序分量研究 | **fault_study**（改 tbreak TC/TO 选相，独立案例） |
+| 孤岛频率/下垂/自定义控制器 | **island_droop_controller**（改 DROOPC 参数） |

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "dsh-plugin-pscad-expert-vyma",
+  "version": "1.0.0",
+  "description": "PSCAD 自动化建模与仿真控制专家插件（DSH Agent 工具库 + 基准模板 + 领域知识）",
+  "main": "plugin.yaml",
+  "keywords": [
+    "dsh",
+    "pscad",
+    "agent",
+    "deepseek",
+    "automation"
+  ],
+  "author": "PSCAD Expert",
+  "license": "MIT",
+  "files": [
+    "knowledge/",
+    "tools/",
+    "templates/",
+    "plugin.yaml",
+    "README.md"
+  ],
+  "engines": {
+    "python": ">=3.7"
+  }
+}

package/plugin.yaml

@@ -0,0 +1,50 @@
+# ============================================================
+# DSH 插件注册清单 — pscad-automation-expert
+# 由知识资产固化项目自动生成（2026-08-25）· 部署至 Git 仓库
+# ============================================================
+name: pscad-automation-expert
+version: 1.0.0
+description: PSCAD 自动化建模与仿真控制专家插件
+
+# ---- 工具入口注册（tools/main.py 中的核心函数）----
+entry_points:
+  tools:
+    module: tools.main
+    functions:
+      - init_pscad_environment        # 初始化工具：配置并持久化 PSCAD 路径（首个调用）
+      - connect_and_load_project      # 连接/启动 PSCAD 并加载 .pscx 模板工程
+      - add_and_configure_component   # 放置元件 + 参数配置，强制唯一 Name 标签
+      - connect_ports_safely          # 安全连线（动态端口坐标 + 穿线避让绕行）
+      - connect_signal_by_name        # 同名 datalabel 信号桥（数据/控制信号标准做法）
+      - register_pgb                  # PGB 输出通道注册
+      - configure_simulation          # 仿真参数配置（步长/时长/输出文件）
+      - run_simulation_and_monitor    # 编译+运行+监控（返回完整 build 消息）
+      - read_output                   # 结果读取（.inf/.out 解析：RMS/均值/DFT）
+      - compute_sequence              # Fortescue 对称分量换算
+      - restart_pscad                 # 自动化服务崩溃恢复（10054 处理）
+      - check_component_overlaps      # 布局重叠自检（build 前诊断）
+
+# ---- 知识库声明（系统提示词前置上下文）----
+knowledge_base:
+  preload:
+    - knowledge/pscad_skill_core.md   # 核心技能库：元件 API/布线 SOP/TOP3 排错
+    - knowledge/templates_index.md    # 基准模板索引与二次开发指南
+
+# ---- 模板资产 ----
+templates:
+  directory: templates/
+  files:
+    - 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 专项）
+
+# ---- 运行环境（无硬编码：路径由 init_pscad_environment 动态配置于运行时）----
+runtime:
+  automation_port: 54329
+  python: ">=3.7"
+  mhi_version: 2.2.1
+  # 注意：PSCAD 可执行文件路径与 mhi.pscad 库目录不在此声明，
+  # 由 tools/main.py 的 init_pscad_environment 工具写入工作区 .pscad_config.json。