dsh-plugin-pscad-expert-vyma 1.0.2 → 1.0.4

package/cordis.patch.yml

@@ -1,2 +1,3 @@
-id: pscad-expert-bridge
-name: PSCAD Expert Agent Loader
+- insert:
+    - id: pscad-expert-bridge
+      name: dsh-plugin-pscad-expert-vyma

package/index.js

@@ -1,24 +1,190 @@
-const fs = require('fs');
-const path = require('path');
-
-exports.name = 'pscad-expert-bridge';
-
-exports.apply = function (ctx) {
-    ctx.on('ready', () => {
-        try {
-            const baseDir = ctx.baseDir || process.cwd();
-            const targetDir = path.join(baseDir, 'plugins', 'dsh-plugin-pscad-expert-vyma');
-            
-            if (!fs.existsSync(targetDir)) {
-                fs.mkdirSync(targetDir, { recursive: true });
-                fs.cpSync(__dirname, targetDir, { 
-                    recursive: true,
-                    filter: (src) => !src.includes('node_modules') && !src.includes('.git')
-                });
-                ctx.logger('pscad-bridge').info('PSCAD Agent 资产已成功跨层释放！');
-            }
-        } catch (err) {
-            ctx.logger('pscad-bridge').error('释放资产失败:', err);
-        }
-    });
-};
+// ============================================================
+// pscad-expert-bridge — DSH 官方插件（Cordis bundle 形态）
+//
+// 将 PSCAD 自动化技能（tools/main.py Python 工具库）以标准
+// defineTool 工具集暴露给 DSH Agent：
+//   Node 激活层（本文件）→ 子进程调用 tools/cli.py → Python 工具库
+//
+// 规范要点（dsh-plugin-dev-skill）：
+//  - ESM 模块 + `name` / `inject` / `Config` / `apply(ctx, config)`
+//  - 全部注册经 ctx.tools.register（卸载自动清理，不手动 removeListener）
+//  - 所有可调参数进 Config（Schemastery 校验，加载时响亮失败）
+//  - execute 返回规范 JSON 值；output.render 为纯函数
+//  - 响应 exec.signal 取消（终止 Python 子进程）
+// ============================================================
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import Schema from '@deepseek-ai/schemastery'
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+export const name = 'pscad-expert-bridge'
+export const inject = ['tools']
+
+// ---------------- 插件配置（Schemastery，无硬编码） ----------------
+export const Config = Schema.object({
+  pythonExecutable: Schema.string().default('python'),
+  toolsCli: Schema.string().default('./tools/cli.py'),
+  defaultFolder: Schema.string().default(''),
+  timeoutMs: Schema.number().default(120000),
+})
+
+// ---------------- Python 桥接（子进程 JSON-RPC，支持取消） ----------------
+function runPy(tool, args, config, signal) {
+  const cliPath = fileURLToPath(new URL(config.toolsCli, import.meta.url))
+  return new Promise((resolve, reject) => {
+    let settled = false
+    const done = (fn, v) => { if (!settled) { settled = true; fn(v) } }
+    const proc = spawn(config.pythonExecutable, [cliPath, tool, JSON.stringify(args)], {
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    let stdout = ''
+    let stderr = ''
+    const timer = setTimeout(() => {
+      proc.kill('SIGKILL')
+      done(reject, new Error(`PSCAD 工具 ${tool} 执行超时（>${config.timeoutMs}ms）`))
+    }, config.timeoutMs)
+
+    const onAbort = () => {
+      proc.kill('SIGKILL')
+      done(reject, new Error(`工具 ${tool} 已被取消（exec.signal）`))
+    }
+    if (signal) {
+      if (signal.aborted) { onAbort(); return }
+      signal.addEventListener('abort', onAbort, { once: true })
+    }
+
+    proc.stdout.on('data', (d) => { stdout += d })
+    proc.stderr.on('data', (d) => { stderr += d })
+    proc.on('close', (code) => {
+      clearTimeout(timer)
+      if (signal) signal.removeEventListener('abort', onAbort)
+      if (code !== 0) {
+        done(reject, new Error(`Python 桥接退出码 ${code}: ${stderr.slice(0, 500)}`))
+        return
+      }
+      try {
+        done(resolve, JSON.parse(stdout.trim()))
+      } catch (err) {
+        done(reject, new Error(`Python 桥接返回非 JSON: ${err.message} (stdout: ${stdout.slice(0, 300)})`))
+      }
+    })
+    proc.on('error', (err) => {
+      clearTimeout(timer)
+      if (signal) signal.removeEventListener('abort', onAbort)
+      done(reject, new Error(`无法启动 Python 子进程: ${err.message}`))
+    })
+  })
+}
+
+// ---------------- 工具渲染（纯函数：不做 I/O） ----------------
+function renderJson(value) {
+  if (value && typeof value === 'object' && value.error === 'ConfigMissing') {
+    // 配置缺失：引导 Agent 立即停止当前任务并询问用户路径
+    return [{ type: 'text', text: `【配置缺失】${value.instruction}` }]
+  }
+  if (value && value.status === 'error') {
+    return [{ type: 'text', text: `[error] ${value.message}` }]
+  }
+  return [{ type: 'text', text: JSON.stringify(value, null, 2) }]
+}
+
+// ---------------- 工具定义 ----------------
+const toolDefs = [
+  {
+    name: 'pscad_init_environment',
+    description: '首次配置 PSCAD 运行环境：将 PSCAD 可执行文件路径与 mhi.pscad 库目录保存到工作区 .pscad_config.json。任何工具返回 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 库目录绝对路径' },
+    },
+  },
+  {
+    name: 'pscad_connect_load_project',
+    description: '启动/连接 PSCAD 实例并加载 .pscx 模板工程（或新建）。连接前自动检查配置，缺失时返回 ConfigMissing 引导。',
+    parameters: {
+      project_name: { type: 'string', required: true, description: '工程名（不带 .pscx 后缀）' },
+      folder: { type: 'string', description: '工程所在目录；缺省用配置默认' },
+      create_if_missing: { type: 'boolean', description: '不存在时是否新建（默认 false）' },
+    },
+  },
+  {
+    name: 'pscad_add_component',
+    description: '在当前画布放置 PSCAD 元件并配置参数，强制赋予唯一 Name 标签（后续寻址主键）。返回端口坐标表。',
+    parameters: {
+      comp_type: { type: 'string', required: true, description: "元件定义名，如 'master:resistor' 或 'resistor'" },
+      x: { type: 'integer', required: true, description: '放置锚点 X（网格坐标）' },
+      y: { type: 'integer', required: true, description: '放置锚点 Y（网格坐标）' },
+      params: { type: 'object', additionalProperties: true, description: '参数键值对（带单位字符串如 100.0 [ohm]）' },
+      orient: { type: 'integer', description: '旋转取模 4（0/1/2/3）' },
+      name: { type: 'string', description: '显式 Name 标签；缺省自动生成唯一名' },
+    },
+  },
+  {
+    name: 'pscad_connect_ports',
+    description: '安全连线：按 Name 寻址两个组件端口，动态取坐标并自动绕行避让（防穿线短路）。返回折线顶点与警告。',
+    parameters: {
+      source_name: { type: 'string', required: true, description: '源组件 Name 标签' },
+      source_port: { type: 'string', required: true, description: '源端口名（如 A、N1、OUT）' },
+      target_name: { type: 'string', required: true, description: '目标组件 Name 标签' },
+      target_port: { type: 'string', required: true, description: '目标端口名' },
+      bend: { type: 'string', description: '绕行策略：auto/hfirst/vfirst/top/bottom（默认 auto）' },
+    },
+  },
+  {
+    name: 'pscad_connect_signal',
+    description: '用同名 datalabel 桥接数据/控制信号（信号链标准做法，无需导线）：const→控制端口、表计通道→控制链等。',
+    parameters: {
+      source_name: { type: 'string', required: true, description: '信号源组件 Name（如 const）' },
+      source_port: { type: 'string', required: true, description: '源端口名（如 OUT）' },
+      signal_name: { type: 'string', required: true, description: '信号名（唯一，同名即广播）' },
+      target_name: { type: 'string', required: true, description: '目标组件 Name（如 source_1）' },
+      target_port: { type: 'string', required: true, description: '目标端口名（如 Mag/freq）' },
+    },
+  },
+  {
+    name: 'pscad_run_simulation',
+    description: '配置仿真参数并编译运行 EMTDC，返回完整 build error/warning 消息与 Status code。',
+    parameters: {
+      time_duration: { type: 'number', description: '仿真时长（秒，默认 0.5）' },
+      time_step: { type: 'number', description: 'EMTDC 步长（微秒，默认 10）' },
+      sample_step: { type: 'number', description: '采样步长（微秒，默认 50）' },
+      timeout_loops: { type: 'integer', description: '等待轮询上限（默认 60）' },
+    },
+  },
+  {
+    name: 'pscad_read_output',
+    description: '读取最近一次仿真通道数据（.inf PGB 映射 + .out 列）。列 RMS=相 RMS；DFT 须用系统实际频率（F0）。',
+    parameters: {
+      channel: { type: 'string', description: '通道名（如 VrA）；缺省返回全部' },
+      t0: { type: 'number', description: '分析窗起点（秒，默认 0）' },
+      t1: { type: 'number', description: '分析窗终点（缺省取末尾）' },
+      method: { type: 'string', description: 'rms（默认）/mean/dft' },
+      freq: { type: 'number', description: 'DFT 频率 Hz（默认 50，须等于系统实际频率）' },
+    },
+  },
+  {
+    name: 'pscad_self_check',
+    description: 'PSCAD 插件环境自检：配置状态、路径存在性、工具清单。诊断用。',
+    parameters: {},
+  },
+]
+
+// ---------------- 插件主体 ----------------
+export function apply(ctx, config) {
+  for (const def of toolDefs) {
+    ctx.tools.register(defineTool({
+      name: def.name,
+      description: def.description,
+      parameters: def.parameters,
+      output: {
+        schema: { type: 'object' },
+        render: renderJson,
+      },
+      execute: (args, exec) => runPy(def.name, args, config, exec.signal),
+    }))
+  }
+  ctx.logger('pscad-bridge').info(
+    `PSCAD Expert 插件已加载：${toolDefs.length} 个工具已注册（Python 桥接: ${config.pythonExecutable} ${config.toolsCli}）`)
+}

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "dsh-plugin-pscad-expert-vyma",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "PSCAD 自动化建模与仿真控制专家插件（DSH Agent 工具库 + 基准模板 + 领域知识）",
+  "type": "module",
   "main": "index.js",
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
     }
   },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-tools": "*",
+    "@deepseek-ai/schemastery": "*"
+  },
   "keywords": [
     "dsh",
     "pscad",

package/plugin.yaml

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

package/tools/cli.py

@@ -0,0 +1,103 @@
+# -*- coding: utf-8 -*-
+"""cli.py -- PSCAD 工具库 JSON 桥接入口（Node.js ↔ Python 层）
+
+DSH 插件（index.js）通过子进程调用本脚本执行 tools/main.py 中的任意工具函数：
+
+    python cli.py <tool_name> '<json_args>'
+
+- 参数以 JSON 字符串传入（kwargs 匹配函数签名；失败回退位置参数）。
+- 结果以单行 JSON 打印到 stdout（含 status/data 或 error/ConfigMissing 结构）。
+- 本脚本**永不抛异常**：任何错误均转为 JSON 错误字典，保证 Node 侧解析不崩溃。
+
+示例::
+
+    python cli.py init_pscad_environment '{"exe_path": "...", "pylib_path": "..."}'
+    python cli.py connect_and_load_project '{"project_name": "my_case"}'
+    python cli.py read_output '{"channel": "VrA", "method": "rms"}'
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import traceback
+from typing import Any, Dict, List
+
+# 将本文件所在目录加入 sys.path，以便 import main（tools/main.py）
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import main as pat  # noqa: E402
+
+# 白名单：仅暴露经过审核的工具函数（防止任意 Python 代码执行）
+TOOL_WHITELIST: Dict[str, Any] = {
+    'init_pscad_environment': pat.init_pscad_environment,
+    'connect_and_load_project': pat.connect_and_load_project,
+    'add_and_configure_component': pat.add_and_configure_component,
+    'set_component_params': pat.set_component_params,
+    'get_component': pat.get_component,
+    'list_components': pat.list_components,
+    'connect_ports_safely': pat.connect_ports_safely,
+    'connect_ports_chain': pat.connect_ports_chain,
+    'connect_signal_by_name': pat.connect_signal_by_name,
+    'register_pgb': pat.register_pgb,
+    'check_component_overlaps': pat.check_component_overlaps,
+    'configure_simulation': pat.configure_simulation,
+    'run_simulation_and_monitor': pat.run_simulation_and_monitor,
+    'read_output': pat.read_output,
+    'compute_sequence': pat.compute_sequence,
+    'restart_pscad': pat.restart_pscad,
+    'close_connection': pat.close_connection,
+    'build_droop_chain': pat.build_droop_chain,
+    'self_check': pat.self_check,
+}
+
+
+def main(argv: List[str]) -> int:
+    """CLI 入口：python cli.py <tool_name> [json_args]。"""
+    if len(argv) < 2:
+        print(json.dumps({'status': 'error',
+                          'message': '用法: python cli.py <tool_name> [json_args]'},
+                         ensure_ascii=False))
+        return 2
+
+    tool = argv[1]
+    fn = TOOL_WHITELIST.get(tool)
+    if fn is None:
+        print(json.dumps({'status': 'error',
+                          'message': '未知工具: %s（白名单可用: %s）'
+                                     % (tool, sorted(TOOL_WHITELIST))},
+                         ensure_ascii=False))
+        return 2
+
+    args: Dict[str, Any] = {}
+    if len(argv) >= 3:
+        try:
+            args = json.loads(argv[2])
+            if not isinstance(args, dict):
+                raise ValueError('args 必须是 JSON 对象')
+        except Exception as exc:
+            print(json.dumps({'status': 'error',
+                              'message': '参数 JSON 解析失败: %s' % exc},
+                             ensure_ascii=False))
+            return 2
+
+    try:
+        result = fn(**args)
+    except TypeError:
+        # kwargs 不匹配时回退位置参数（保持参数顺序）
+        try:
+            result = fn(*args.values())
+        except Exception:
+            result = {'status': 'error',
+                      'message': traceback.format_exc(limit=6)}
+    except Exception:
+        result = {'status': 'error', 'message': traceback.format_exc(limit=6)}
+
+    # 统一序列化（Component 对象等不可 JSON 序列化的字段降级为字符串）
+    print(json.dumps(result, ensure_ascii=False, default=str))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv))