zwcad-mcp 0.2.0 → 0.2.2

package/README.md

@@ -2,7 +2,10 @@
 
 中望CAD（ZWCAD）MCP 服务，让大模型通过 [MCP 协议](https://modelcontextprotocol.io)直接操控中望CAD 平台与中望机械CAD，完成绘图、标注、图层/块/样式管理，以及图框、标题栏、明细表（BOM）等机械操作。
 
-**共计 39 个工具**：平台 26 个（不依赖机械环境）+ 机械 11 个（需中望机械CAD）+ 诊断 2 个。
+**共计 41 个工具**：平台 26 个（不依赖机械环境）+ 机械 11 个（需中望机械CAD）+ 诊断 2 个 + 启动器侧 2 个。
+
+> 启动器侧的两个工具（`zwcad_wait_ready`、`zwcad_launcher_diagnose`）在 Python 运行时尚未就绪时也可用，
+> 用于等待初始化完成、以及在首次安装失败时自助排查。
 
 ## 为什么需要 Node 启动器
 
@@ -78,12 +81,27 @@ npx -y zwcad-mcp --prepare     # 只准备运行时后退出
 
 | 现象 | 处理 |
 |---|---|
-| 首次启动等待 30~60 秒 | **正常**，正在安装依赖，之后约 2 秒启动 |
+| 首次使用提示「正在首次初始化」 | **正常**，正在后台安装依赖（约 40 秒），握手本身只需约 120 ms |
 | 报「未找到可用的 Python」 | 装 Python 3.10+，或设 `ZWCAD_MCP_PYTHON` 指向已有解释器 |
 | 装依赖失败（网络） | 设 `ZWCAD_MCP_PIP_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple` |
 | 运行时损坏 | 删 `%USERPROFILE%\.workbuddy\zwcad-mcp-runtime\` 后重连，自动重建 |
 | 机械工具报 `TYPELIB_NOT_LOADED` | 需中望机械CAD 已启动；平台工具不受影响 |
 
+### 错误日志
+
+启动器会把**失败事件**写入本地文件，便于排查与反馈：
+
+```
+%USERPROFILE%\.workbuddy\zwcad-mcp-runtime\logs\error.log
+```
+
+- 每行一条 JSON：时间、事件名、Node 版本、诊断细节
+- **只记失败**，不记成功的工具调用，不含图纸内容
+- 单文件上限 1 MB，自动轮转为 `.1`~`.3`，总量 ≤ 4 MB
+- `--doctor` 末尾会直接打印最近 10 条摘要，多数情况无需打开文件
+
+可用 `ZWCAD_MCP_LOG_DIR` 改变存放位置。
+
 ### 关于 `-2147312566`（加载类型库/DLL 时出错）
 
 这是机械类型库的已知情况，**不是文件缺失或权限问题**。实测根因：`ZwmToolKit.tlb` 内部引用了另一个仅在 ZWCAD 进程运行时才可解析的类型库。
@@ -98,6 +116,7 @@ npx -y zwcad-mcp --prepare     # 只准备运行时后退出
 |---|---|
 | `ZWCAD_MCP_PYTHON` | 指定 Python 解释器路径，跳过自动探测（无效时报错而非静默回退） |
 | `ZWCAD_MCP_PIP_INDEX` | 指定 pip 镜像源 |
+| `ZWCAD_MCP_LOG_DIR` | 指定错误日志目录，默认在 `zwcad-mcp-runtime/logs` |
 
 ## 仓库结构
 

package/bridge.js

@@ -79,9 +79,13 @@ function log(...parts) {
   process.stderr.write('[zwcad-mcp] ' + parts.join(' ') + '\n');
 }
 
+/** 错误日志（落盘），失败不影响主流程 */
+const { logError, logFilePath } = require('./lib/errorlog');
+
 function fatal(err) {
   const msg = err && err.stack ? err.stack : String(err);
   log('启动失败：' + msg);
+  logError('launcher.fatal', { error: err });
   process.exit(1);
 }
 
@@ -260,6 +264,12 @@ function resolvePython() {
     log('使用 Python ' + ver.join('.') + '：' + exe);
     return { exe, version: ver };
   }
+  logError('runtime.python.not_found', {
+    candidates: pythonCandidates(),
+    tried,
+    minVersion: MIN_PYTHON.join('.'),
+    envOverride: process.env.ZWCAD_MCP_PYTHON || null,
+  });
   throw new Error(
     '未找到可用的 Python（需要 >= ' +
       MIN_PYTHON.join('.') +
@@ -384,7 +394,20 @@ async function installDeps(venvPython) {
   args.push(...requiredPackages());
 
   log('首次运行，安装依赖（约 30~60 秒，请稍候）…');
-  await runStreaming(venvPython, args, '安装依赖');
+  const startedAt = Date.now();
+  try {
+    await runStreaming(venvPython, args, '安装依赖');
+  } catch (e) {
+    logError('runtime.install.failed', {
+      error: e,
+      packageCount: requiredPackages().length,
+      packages: requiredPackages(),
+      pipIndex: index || null,
+      elapsedMs: Date.now() - startedAt,
+      venvPython,
+    });
+    throw e;
+  }
 }
 
 /**
@@ -490,6 +513,31 @@ function doctor() {
   } else {
     log('--- 虚拟环境 --- 尚未创建（首次启动时会自动创建）');
   }
+
+  log('--- 错误日志 ---');
+  const lp = logFilePath();
+  if (fs.existsSync(lp)) {
+    const st = fs.statSync(lp);
+    log('  路径：' + lp);
+    log('  大小：' + (st.size / 1024).toFixed(1) + ' KB，最近写入 ' + st.mtime.toISOString());
+    log('  查看最近 10 条：');
+    try {
+      const lines = fs.readFileSync(lp, 'utf8').trim().split('\n').slice(-10);
+      for (const line of lines) {
+        try {
+          const r = JSON.parse(line);
+          log('    [' + r.time + '] ' + r.event);
+        } catch {
+          log('    ' + line.slice(0, 120));
+        }
+      }
+    } catch {
+      log('    （读取失败）');
+    }
+  } else {
+    log('  暂无错误记录（这是好事）');
+    log('  路径：' + lp + '（首次出错时自动创建）');
+  }
 }
 
 /* ------------------------------------------------------------------ *

package/lib/errorlog.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * 错误日志：把启动器与 Python 侧的失败事件写到本地文件，便于事后排查。
+ *
+ * 设计取舍
+ * --------
+ * 1. **只记失败**，不记成功。成功事件写日志只会淹没真正有用的信息，
+ *    而且调用量上来后文件会迅速膨胀。
+ * 2. **只记本地，不联网**。图纸内容、文件路径都可能涉密，
+ *    用户遇到问题时可以把文件发给我们，由人工判断是否适合上报。
+ * 3. **写入绝不抛异常**。日志本身出问题不能影响 MCP 服务运行——
+ *    这是日志系统最常见的自伤方式。
+ * 4. **自动轮转**。单文件上限 1 MB，超过后转成 `.1`，最多保留 3 个历史文件，
+ *    总量控制在 4 MB 以内，不会占满用户磁盘。
+ *
+ * 存放位置
+ * --------
+ *   %USERPROFILE%\.workbuddy\zwcad-mcp-runtime\logs\
+ *
+ * 放在 runtime 目录下，用户执行「删掉 runtime 目录重置」时会一并清理，
+ * 不会留下孤儿文件。
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/** 单文件上限：1 MB */
+const MAX_BYTES = 1024 * 1024;
+/** 保留的历史文件数 */
+const MAX_BACKUPS = 3;
+
+/**
+ * 解析日志目录。
+ *
+ * 允许用环境变量覆盖，便于排查时把日志指到更方便的位置。
+ */
+function resolveLogDir() {
+  if (process.env.ZWCAD_MCP_LOG_DIR) {
+    return process.env.ZWCAD_MCP_LOG_DIR;
+  }
+  return path.join(os.homedir(), '.workbuddy', 'zwcad-mcp-runtime', 'logs');
+}
+
+/**
+ * 轮转：当前文件超过上限时，依次改名 .1 / .2 / .3，最老的被丢弃。
+ *
+ * 用 rename 而不是复制，避免大文件复制带来的 IO 抖动。
+ */
+function rotateIfNeeded(file) {
+  let size;
+  try {
+    size = fs.statSync(file).size;
+  } catch {
+    return; // 文件不存在，无需轮转
+  }
+  if (size < MAX_BYTES) return;
+
+  // 从最老的开始往后挪，腾出 .1 的位置
+  for (let i = MAX_BACKUPS; i >= 1; i--) {
+    const src = i === 1 ? file : file + '.' + (i - 1);
+    const dst = file + '.' + i;
+    try {
+      if (fs.existsSync(src)) fs.renameSync(src, dst);
+    } catch {
+      /* 轮转失败不影响主流程 */
+    }
+  }
+}
+
+/** 把值安全地转成可 JSON 序列化的形式 */
+function sanitize(value, depth = 0) {
+  if (value === null || value === undefined) return value;
+  if (depth > 4) return '[深度超限]';
+
+  const t = typeof value;
+  if (t === 'string') {
+    // 抑制超长字符串（例如整段 Python 堆栈）
+    return value.length > 4000 ? value.slice(0, 4000) + '…[截断]' : value;
+  }
+  if (t === 'number' || t === 'boolean') return value;
+  if (t === 'function') return '[Function]';
+
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: value.message,
+      stack: value.stack ? value.stack.slice(0, 4000) : undefined,
+    };
+  }
+
+  if (Array.isArray(value)) {
+    return value.slice(0, 50).map((v) => sanitize(v, depth + 1));
+  }
+
+  if (t === 'object') {
+    const out = {};
+    let n = 0;
+    for (const k of Object.keys(value)) {
+      if (n++ >= 50) {
+        out['…'] = '[字段过多，已截断]';
+        break;
+      }
+      try {
+        out[k] = sanitize(value[k], depth + 1);
+      } catch {
+        out[k] = '[无法序列化]';
+      }
+    }
+    return out;
+  }
+
+  return String(value);
+}
+
+/** 进程级上下文，每条日志都会带上 */
+const baseContext = {
+  pid: process.pid,
+  node: process.version,
+  platform: process.platform + '/' + process.arch,
+};
+
+/**
+ * 记录一条错误事件。
+ *
+ * @param {string} event   事件名，用点号分层，如 `runtime.install.failed`
+ * @param {object} detail  事件细节，任意可序列化对象
+ */
+function logError(event, detail) {
+  try {
+    const dir = resolveLogDir();
+    fs.mkdirSync(dir, { recursive: true });
+
+    const file = path.join(dir, 'error.log');
+    rotateIfNeeded(file);
+
+    const record = {
+      time: new Date().toISOString(),
+      event: String(event),
+      ...baseContext,
+      detail: sanitize(detail || {}),
+    };
+
+    fs.appendFileSync(file, JSON.stringify(record) + '\n', 'utf8');
+
+    // 同时打印一行到 stderr，让开发者在终端也能立刻看到
+    process.stderr.write(`[zwcad-mcp][错误] ${record.event}\n`);
+  } catch {
+    // 日志失败绝不能影响主流程
+  }
+}
+
+/** 返回当前日志文件路径，供 --doctor 展示 */
+function logFilePath() {
+  return path.join(resolveLogDir(), 'error.log');
+}
+
+module.exports = { logError, logFilePath, resolveLogDir };

package/lib/proxy.js

@@ -30,6 +30,7 @@
 const fs = require('fs');
 const path = require('path');
 const { spawn } = require('child_process');
+const { logError, logFilePath } = require('./errorlog');
 
 const PROTOCOL_VERSION = '2024-11-05';
 
@@ -71,6 +72,26 @@ const PROXY_TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'zwcad_launcher_diagnose',
+    description:
+      '诊断启动器与 Python 运行时的状态，并返回最近的错误记录。\n\n' +
+      '与 zwcad_diagnose 的区别：本工具由 JS 启动器实现，**在 Python 尚未就绪时也可用**，' +
+      '因此是排查「首次安装失败 / 一直停在初始化」的首选；' +
+      'zwcad_diagnose 依赖 Python 侧，只能在其就绪后调用。\n\n' +
+      '返回内容包括：运行时状态、Python 解释器路径与版本、虚拟环境状态、' +
+      '最近若干条错误日志（含事件名与诊断细节）。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: {
+          type: 'number',
+          description: '返回最近多少条错误日志，默认 10，上限 50。',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
 ];
 
 /**
@@ -109,6 +130,13 @@ function createProxy(opts) {
   let inputBuffer = '';
   /** 子进程 → 我们的待处理缓冲 */
   let childBuffer = '';
+  /**
+   * 子进程 stderr 的尾部。
+   *
+   * Python 崩溃时异常堆栈在这里，是事后定位问题的关键依据，
+   * 所以即使已经转发到自己的 stderr，也要留一份用于写错误日志。
+   */
+  let stderrTail = '';
 
   /** 子进程是否已就绪并接管 */
   let child = null;
@@ -196,6 +224,7 @@ function createProxy(opts) {
         runtimeState = 'failed';
         runtimeError = e && e.message ? e.message : String(e);
         log('运行时准备失败：' + runtimeError);
+        logError('runtime.ready.failed', { error: e });
         throw e;
       }
     })();
@@ -223,7 +252,11 @@ function createProxy(opts) {
     log('启动 MCP Server…');
     child = spawn(py, opts.childArgs, { stdio: ['pipe', 'pipe', 'pipe'], env, windowsHide: true });
 
-    child.stderr.pipe(process.stderr);
+    // 保留 stderr 尾部：Python 若崩溃，异常堆栈在这里，是定位问题的关键
+    child.stderr.on('data', (d) => {
+      stderrTail = (stderrTail + d.toString('utf8')).slice(-8000);
+      process.stderr.write(d);
+    });
 
     child.stdout.on('data', (chunk) => {
       childBuffer += chunk.toString('utf8');
@@ -239,10 +272,19 @@ function createProxy(opts) {
       log('子进程启动失败：' + e.message);
       runtimeState = 'failed';
       runtimeError = e.message;
+      logError('python.spawn.failed', { error: e, python: py, args: opts.childArgs });
     });
 
     child.on('close', (code) => {
       log('MCP Server 退出，code=' + code);
+      // 非 0 退出往往是 Python 侧崩了，值得留痕；0 是正常结束
+      if (code !== 0) {
+        logError('python.exited', {
+          code,
+          initialized: childInitialized,
+          stderrTail: stderrTail.slice(-3000),
+        });
+      }
       process.exit(code == null ? 1 : code);
     });
 
@@ -472,13 +514,14 @@ function createProxy(opts) {
       } else if (r.state === 'failed') {
         text =
           `服务初始化失败：${r.error}\n\n` +
-          `请让用户执行以下命令查看诊断：\n  npx -y zwcad-mcp --doctor\n\n` +
+          `下一步：调用 zwcad_launcher_diagnose 获取完整的错误记录与运行环境信息，` +
+          `据此判断原因并告知用户具体怎么修。\n\n` +
           `常见原因：未安装 Python 3.10+、网络无法访问 PyPI、磁盘空间不足。`;
       } else {
         text =
           `已等待 ${seconds} 秒，初始化仍未完成，仍在安装依赖。\n\n` +
-          `可以再调用一次本工具继续等待，或告知用户首次安装耗时较长、请稍候。\n` +
-          `若累计超过 2 分钟仍无进展，让用户执行：\n  npx -y zwcad-mcp --doctor`;
+          `下一步：可再调用一次本工具继续等待；若累计超过 2 分钟仍无进展，` +
+          `调用 zwcad_launcher_diagnose 查看错误记录。`;
       }
 
       writeJson({
@@ -492,6 +535,19 @@ function createProxy(opts) {
       return;
     }
 
+    if (name === 'zwcad_launcher_diagnose') {
+      let limit = Number(args.limit);
+      if (!Number.isFinite(limit) || limit <= 0) limit = 10;
+      limit = Math.min(limit, 50);
+
+      writeJson({
+        jsonrpc: '2.0',
+        id: msg.id,
+        result: { content: [{ type: 'text', text: buildDiagnosisReport(limit) }] },
+      });
+      return;
+    }
+
     writeJson({
       jsonrpc: '2.0',
       id: msg.id,
@@ -502,6 +558,103 @@ function createProxy(opts) {
     });
   }
 
+  /**
+   * 生成诊断报告。
+   *
+   * 目标是让 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.0",
+  "version": "0.2.2",
   "description": "中望CAD（ZWCAD）MCP 服务：用自然语言驱动 ZWCAD 二维平台与中望机械 CAD，完成绘图、标注、图层管理与机械图框/BOM 操作",
   "license": "MIT",
   "type": "commonjs",
@@ -23,6 +23,9 @@
     "prepare-runtime": "node bridge.js --prepare",
     "build:connector": "node scripts/build-connector.js",
     "check:connector": "node scripts/build-connector.js --check",
+    "test:errorlog": "node scripts/test-errorlog.js",
+    "test:rotation": "node scripts/test-rotation.js",
+    "test": "node scripts/test-errorlog.js && node scripts/test-rotation.js",
     "prepack": "node scripts/build-connector.js --check"
   },
   "engines": {