zwcad-mcp 0.2.0 → 0.2.1

package/README.md

@@ -78,12 +78,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 +113,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 } = require('./errorlog');
 
 const PROTOCOL_VERSION = '2024-11-05';
 
@@ -109,6 +110,13 @@ function createProxy(opts) {
   let inputBuffer = '';
   /** 子进程 → 我们的待处理缓冲 */
   let childBuffer = '';
+  /**
+   * 子进程 stderr 的尾部。
+   *
+   * Python 崩溃时异常堆栈在这里，是事后定位问题的关键依据，
+   * 所以即使已经转发到自己的 stderr，也要留一份用于写错误日志。
+   */
+  let stderrTail = '';
 
   /** 子进程是否已就绪并接管 */
   let child = null;
@@ -196,6 +204,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 +232,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 +252,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);
     });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zwcad-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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": {