zwcad-mcp 0.2.1 → 0.2.3

package/README.md

@@ -2,7 +2,11 @@
 
 中望CAD（ZWCAD）MCP 服务，让大模型通过 [MCP 协议](https://modelcontextprotocol.io)直接操控中望CAD 平台与中望机械CAD，完成绘图、标注、图层/块/样式管理，以及图框、标题栏、明细表（BOM）等机械操作。
 
-**共计 39 个工具**：平台 26 个（不依赖机械环境）+ 机械 11 个（需中望机械CAD）+ 诊断 2 个。
+**共计 40 个工具**：平台 26 个（不依赖机械环境）+ 机械 11 个（需中望机械CAD）+ 诊断 2 个 + 启动器侧 1 个。
+
+> 启动器侧的 `zwcad_wait_ready` 在 Python 运行时尚未就绪时也可用，用于等待初始化完成。
+> 诊断统一走 `zwcad_diagnose`：Python 已就绪时返回完整诊断，
+> 未就绪时自动降级为启动器视角（含错误日志与环境信息）并标注未检测项。
 
 ## 为什么需要 Node 启动器
 

package/lib/proxy.js

@@ -30,7 +30,7 @@
 const fs = require('fs');
 const path = require('path');
 const { spawn } = require('child_process');
-const { logError } = require('./errorlog');
+const { logError, logFilePath } = require('./errorlog');
 
 const PROTOCOL_VERSION = '2024-11-05';
 
@@ -386,6 +386,15 @@ function createProxy(opts) {
         handleProxyTool(msg);
         return;
       }
+
+      // zwcad_diagnose 是 Python 侧的主诊断工具，但它本身跑在 Python 里。
+      // Python 未就绪时它必然报「正在初始化」，而这恰恰是最需要诊断的时刻。
+      // 所以这里做一次兜底：未就绪时直接由代理层给出启动器视角的诊断，
+      // 让 AI 只需认准「一个诊断入口」。
+      if (toolName === 'zwcad_diagnose' && !childReady) {
+        handleDiagnoseFallback(msg);
+        return;
+      }
     }
 
     // tools/list 永远由本地静态清单应答，不受 childReady 影响。
@@ -494,13 +503,14 @@ function createProxy(opts) {
       } else if (r.state === 'failed') {
         text =
           `服务初始化失败：${r.error}\n\n` +
-          `请让用户执行以下命令查看诊断：\n  npx -y zwcad-mcp --doctor\n\n` +
+          `下一步：调用 zwcad_diagnose 获取完整的错误记录与运行环境信息，` +
+          `据此判断原因并告知用户具体怎么修。\n\n` +
           `常见原因：未安装 Python 3.10+、网络无法访问 PyPI、磁盘空间不足。`;
       } else {
         text =
           `已等待 ${seconds} 秒，初始化仍未完成，仍在安装依赖。\n\n` +
-          `可以再调用一次本工具继续等待，或告知用户首次安装耗时较长、请稍候。\n` +
-          `若累计超过 2 分钟仍无进展，让用户执行：\n  npx -y zwcad-mcp --doctor`;
+          `下一步：可再调用一次本工具继续等待；若累计超过 2 分钟仍无进展，` +
+          `调用 zwcad_diagnose 查看错误记录。`;
       }
 
       writeJson({
@@ -524,6 +534,139 @@ function createProxy(opts) {
     });
   }
 
+  /**
+   * Python 未就绪时，zwcad_diagnose 的兜底应答。
+   *
+   * 设计要点：对 AI 来说诊断入口始终是 zwcad_diagnose，不必记两个工具名。
+   * 这里返回启动器视角的诊断，并**明确标注哪些项目因 Python 未就绪而无法检测**，
+   * 避免 AI 把「未检测」误读成「正常」或「故障」。
+   */
+  function handleDiagnoseFallback(msg) {
+    const report = buildDiagnosisReport(10);
+
+    const header =
+      '## 诊断来源\n' +
+      'Python 运行时尚未就绪，本次为**启动器视角**的诊断，' +
+      '无法检测 ZWCAD 连接状态、机械类型库等 Python 侧项目。\n' +
+      '待初始化完成后再次调用本工具，可获得完整诊断。\n\n';
+
+    const footer =
+      '\n\n## 本次未检测的项目\n' +
+      '- ZWCAD 是否已启动、是否打开了 DWG\n' +
+      '- 机械扩展（ZwmToolKit）类型库加载状态\n' +
+      '- 平台/机械 COM 连接可用性\n\n' +
+      '这些需要 Python 运行时就绪后才能探测。在此之前，' +
+      '如需了解 ZWCAD 侧的情况，请直接查看用户屏幕上是否打开了图纸。';
+
+    writeJson({
+      jsonrpc: '2.0',
+      id: msg.id,
+      result: {
+        content: [{ type: 'text', text: header + report + footer }],
+        // 这不是工具失败，而是「部分信息暂时不可得」，用 isError 会让 AI
+        // 误判为故障，所以按正常结果返回，把局限性写在正文里。
+        isError: false,
+      },
+    });
+  }
+
+  /**
+   * 生成诊断报告。
+   *
+   * 目标是让 AI 读完就能判断问题出在哪，并把结论用自然语言转述给用户，
+   * 而不是把一坨技术细节甩给用户让他自己去跑命令。
+   */
+  function buildDiagnosisReport(limit) {
+    const lines = [];
+    const stateText =
+      runtimeState === 'ready' && childReady
+        ? '已就绪'
+        : runtimeState === 'failed'
+          ? '失败'
+          : '正在准备';
+
+    lines.push('## 运行时状态');
+    lines.push(`状态：${stateText}`);
+    if (runtimeState === 'failed' && runtimeError) {
+      lines.push(`错误：${runtimeError}`);
+    }
+    if (childReady) {
+      lines.push('Python 侧已完成握手，可以正常接受请求。');
+    }
+
+    lines.push('');
+    lines.push('## 运行环境');
+    lines.push(`Node：${process.version}（${process.platform}/${process.arch}）`);
+    lines.push(`启动器版本：${opts.version || '未知'}`);
+    lines.push(`工作目录：${cwd}`);
+    lines.push(
+      `环境变量：ZWCAD_MCP_PYTHON=${process.env.ZWCAD_MCP_PYTHON || '（未设置）'}，` +
+        `ZWCAD_MCP_PIP_INDEX=${process.env.ZWCAD_MCP_PIP_INDEX || '（未设置）'}`
+    );
+
+    lines.push('');
+    lines.push('## 错误记录');
+    const entries = readRecentErrors(limit);
+    if (entries.length === 0) {
+      lines.push('无错误记录。若问题仍存在，可能是尚在安装中，或故障未落到日志点。');
+    } else {
+      lines.push(`日志文件：${logFilePath()}`);
+      lines.push('');
+      for (const e of entries) {
+        lines.push(`- [${e.time}] **${e.event}**`);
+        if (e.detail) {
+          lines.push('  ' + e.detail.replace(/\n/g, '\n  '));
+        }
+      }
+    }
+
+    lines.push('');
+    lines.push('## 如何判读');
+    lines.push('- `runtime.python.not_found`：本机没有 3.10+ 的 Python。');
+    lines.push('  让用户装 Python（建议 3.13），或设 `ZWCAD_MCP_PYTHON` 指向已有解释器。');
+    lines.push('- `runtime.install.failed`：装依赖失败。看 detail 里的 `pipIndex` 与 `error`，');
+    lines.push('  多为网络问题，让用户设 `ZWCAD_MCP_PIP_INDEX` 为国内镜像后重连。');
+    lines.push('- `python.spawn.failed` / `python.exited`：Python 进程起不来或崩溃，');
+    lines.push('  看 detail 里的 `stderrTail`（Python 自身的异常堆栈）。');
+    lines.push('- 无任何错误记录但仍不可用：多半仍在安装，让其再等或重连。');
+
+    return lines.join('\n');
+  }
+
+  /**
+   * 读取最近 N 条错误日志，转成易读文本。
+   *
+   * 读取失败一律返回空数组——诊断工具自己不能因为读不到日志而报错。
+   */
+  function readRecentErrors(limit) {
+    let raw;
+    try {
+      raw = fs.readFileSync(logFilePath(), 'utf8');
+    } catch {
+      return [];
+    }
+
+    const out = [];
+    const all = raw.trim().split('\n').slice(-limit);
+    for (const line of all) {
+      try {
+        const r = JSON.parse(line);
+        let detail = '';
+        if (r.detail && Object.keys(r.detail).length > 0) {
+          try {
+            detail = JSON.stringify(r.detail, null, 1);
+          } catch {
+            detail = '[无法序列化]';
+          }
+        }
+        out.push({ time: r.time, event: r.event, detail });
+      } catch {
+        /* 跳过损坏行 */
+      }
+    }
+    return out;
+  }
+
   /**
    * 未就绪时的工具调用：返回结构化错误，让 AI 知道该等还是该修环境。
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zwcad-mcp",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "中望CAD（ZWCAD）MCP 服务：用自然语言驱动 ZWCAD 二维平台与中望机械 CAD，完成绘图、标注、图层管理与机械图框/BOM 操作",
   "license": "MIT",
   "type": "commonjs",

package/tools.json

@@ -1300,7 +1300,7 @@
  },
  {
   "name": "zwcad_diagnose",
-  "description": "诊断平台和机械后端，并给出不修改系统的排障建议。",
+  "description": "诊断 MCP 服务的运行状态，并按需给出修复建议。\n\n分两种情形，工具名不变：\n- Python 运行时已就绪：返回完整诊断（平台 COM 可用性、活动图纸、机械扩展与 ZwmToolKit 类型库状态）。\n- Python 运行时未就绪：自动降级为启动器视角，返回运行时状态、Python 解释器路径与版本、最近错误记录（含 pip 镜像源、依赖清单、耗时），并明确标注哪些项目本次未检测。\n\n因此排查任何问题都从这里开始，无需另找工具。",
   "inputSchema": {
    "properties": {
     "probe_cad": {
@@ -1320,4 +1320,4 @@
    }
   }
  }
-]
+]