coding-tool-x 3.3.5 → 3.3.7

package/src/server/services/mcp-client.js

@@ -14,6 +14,8 @@
  */
 
 const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
 const http = require('http');
 const https = require('https');
 const { EventEmitter } = require('events');
@@ -22,6 +24,148 @@ const DEFAULT_TIMEOUT = 10000; // 10 seconds
 const JSONRPC_VERSION = '2.0';
 const MCP_PROTOCOL_VERSION = '2024-11-05';
 
+function getPathEnvKey(envObj = {}) {
+  return Object.keys(envObj).find(key => key.toLowerCase() === 'path') || 'PATH';
+}
+
+function stripWrappingQuotes(value) {
+  const text = String(value || '').trim();
+  if (!text) return '';
+  if (
+    (text.startsWith('"') && text.endsWith('"')) ||
+    (text.startsWith("'") && text.endsWith("'"))
+  ) {
+    return text.slice(1, -1);
+  }
+  return text;
+}
+
+function mergeSpawnEnv(extraEnv = {}) {
+  const mergedEnv = { ...process.env, ...extraEnv };
+  const processPathKey = getPathEnvKey(process.env);
+  const extraPathKey = getPathEnvKey(extraEnv);
+  const mergedPathKey = getPathEnvKey(mergedEnv);
+
+  const extraPath = extraEnv && typeof extraEnv[extraPathKey] === 'string'
+    ? extraEnv[extraPathKey]
+    : '';
+  const processPath = process.env && typeof process.env[processPathKey] === 'string'
+    ? process.env[processPathKey]
+    : '';
+
+  if (extraPath && processPath) {
+    mergedEnv[mergedPathKey] = `${extraPath}${path.delimiter}${processPath}`;
+  }
+
+  return mergedEnv;
+}
+
+function resolveWindowsSpawnCommand(command, env, cwd) {
+  if (process.platform !== 'win32') {
+    return stripWrappingQuotes(command);
+  }
+
+  const normalizedCommand = stripWrappingQuotes(command);
+  if (!normalizedCommand) {
+    return normalizedCommand;
+  }
+
+  const hasPathSegment = /[\\/]/.test(normalizedCommand) || /^[a-zA-Z]:/.test(normalizedCommand);
+  const hasExtension = path.extname(normalizedCommand).length > 0;
+  const extensions = hasExtension ? [''] : ['.cmd', '.exe', '.bat', '.com'];
+  const resolveCandidate = (basePath) => {
+    for (const ext of extensions) {
+      const candidate = ext ? `${basePath}${ext}` : basePath;
+      if (fs.existsSync(candidate)) {
+        return candidate;
+      }
+    }
+    return null;
+  };
+
+  if (hasPathSegment) {
+    const absoluteBasePath = path.isAbsolute(normalizedCommand)
+      ? normalizedCommand
+      : path.resolve(cwd || process.cwd(), normalizedCommand);
+    return resolveCandidate(absoluteBasePath) || normalizedCommand;
+  }
+
+  const pathKey = getPathEnvKey(env || process.env);
+  const pathValue = env && typeof env[pathKey] === 'string' ? env[pathKey] : '';
+  if (!pathValue) {
+    return normalizedCommand;
+  }
+
+  const searchPaths = pathValue.split(path.delimiter).filter(Boolean);
+  for (const searchPath of searchPaths) {
+    const found = resolveCandidate(path.join(searchPath.trim(), normalizedCommand));
+    if (found) {
+      return found;
+    }
+  }
+
+  return normalizedCommand;
+}
+
+function getCommandInstallHint(command) {
+  const normalized = path.basename(stripWrappingQuotes(command)).toLowerCase()
+
+  if (['node', 'node.exe', 'npm', 'npm.cmd', 'npx', 'npx.cmd'].includes(normalized)) {
+    return '请先安装 Node.js，并确认 `node` / `npm` / `npx` 已加入 PATH。'
+  }
+
+  if (['uv', 'uv.exe', 'uvx', 'uvx.exe'].includes(normalized)) {
+    return '请先安装 `uv`，并确认 `uv` / `uvx` 可以在终端直接执行。'
+  }
+
+  if (['python', 'python.exe', 'python3', 'py'].includes(normalized)) {
+    return '请先安装 Python，并确认对应命令已加入 PATH。'
+  }
+
+  if (process.platform === 'win32' && ['netstat', 'taskkill'].includes(normalized)) {
+    return '请确认 Windows 自带命令可用，并检查 `C:\\Windows\\System32` 是否在 PATH 中。'
+  }
+
+  return `请确认已安装 "${command}"，或改用可执行文件的绝对路径。`
+}
+
+function createMissingCommandHint(command, resolvedCommand, env = {}) {
+  const pathKey = getPathEnvKey(env)
+  const pathValue = typeof env[pathKey] === 'string' ? env[pathKey] : ''
+  const pathPreview = pathValue
+    ? pathValue.split(path.delimiter).slice(0, 5).join(path.delimiter)
+    : ''
+  const commandHint = resolvedCommand === command
+    ? command
+    : `${command} (resolved: ${resolvedCommand})`
+
+  const details = [
+    getCommandInstallHint(command),
+    process.platform === 'win32'
+      ? 'Windows 可优先尝试 `.cmd` / `.exe` 文件，必要时直接填写绝对路径。'
+      : `可尝试填写绝对路径（例如 \`/usr/bin/node\` 或 \`$(which ${command})\`）。`
+  ]
+
+  if (pathPreview) {
+    details.push(`当前 PATH 前 5 项: ${pathPreview}`)
+  } else {
+    details.push('当前 PATH 为空，请检查环境变量配置。')
+  }
+
+  return {
+    type: 'missing-command',
+    command,
+    resolvedCommand,
+    title: `命令 "${commandHint}" 未找到`,
+    details
+  }
+}
+
+function buildMissingCommandMessage(command, resolvedCommand, env = {}) {
+  const hint = createMissingCommandHint(command, resolvedCommand, env)
+  return [hint.title, ...hint.details].join('\n')
+}
+
 // ============================================================================
 // McpClient
 // ============================================================================
@@ -237,22 +381,19 @@ class McpClient extends EventEmitter {
         reject(new McpClientError(`Connection timeout after ${this._timeout}ms`));
       }, this._timeout);
 
-      try {
-        // 确保 PATH 不被覆盖，优先使用用户提供的 env，但保留 PATH
-        const mergedEnv = { ...process.env, ...env };
-        // 如果用户提供的 env 中有 PATH，将其追加到系统 PATH 前面
-        if (env && env.PATH && process.env.PATH) {
-          mergedEnv.PATH = `${env.PATH}:${process.env.PATH}`;
-        }
+      const finalCwd = cwd || process.cwd();
+      const mergedEnv = mergeSpawnEnv(env || {});
+      const resolvedCommand = resolveWindowsSpawnCommand(command, mergedEnv, finalCwd);
 
-        this._child = spawn(command, args, {
+      try {
+        this._child = spawn(resolvedCommand, args, {
           env: mergedEnv,
           stdio: ['pipe', 'pipe', 'pipe'],
-          cwd: cwd || process.cwd()
+          cwd: finalCwd
         });
       } catch (err) {
         clearTimeout(timer);
-        throw new McpClientError(`Failed to spawn "${command}": ${err.message}`);
+        throw new McpClientError(`Failed to spawn "${resolvedCommand}": ${err.message}`);
       }
 
       // Once we get the spawn event (or first stdout), consider connected
@@ -274,14 +415,11 @@ class McpClient extends EventEmitter {
 
       this._child.on('error', (err) => {
         if (err.code === 'ENOENT') {
-          const pathHint = mergedEnv.PATH
-            ? `\n  Current PATH: ${mergedEnv.PATH.split(':').slice(0, 5).join(':')}\n  (showing first 5 entries)`
-            : '\n  PATH is not set!';
+          const hint = createMissingCommandHint(command, resolvedCommand, mergedEnv)
           settle(new McpClientError(
-            `Command "${command}" not found. Please check:\n` +
-            `  1. Is "${command}" installed?\n` +
-            `  2. Try using absolute path (e.g., /usr/bin/node or $(which ${command}))\n` +
-            `  3. Check your PATH environment variable${pathHint}`
+            buildMissingCommandMessage(command, resolvedCommand, mergedEnv),
+            undefined,
+            { hint }
           ));
         } else {
           settle(new McpClientError(`Failed to start process: ${err.message}`));
@@ -786,5 +924,11 @@ async function createClient(serverSpec, options = {}) {
 module.exports = {
   McpClient,
   McpClientError,
-  createClient
+  createClient,
+  buildMissingCommandMessage,
+  createMissingCommandHint,
+  _test: {
+    createMissingCommandHint,
+    buildMissingCommandMessage
+  }
 };

package/src/server/services/mcp-service.js

@@ -11,7 +11,7 @@ const toml = require('@iarna/toml');
 const { spawn } = require('child_process');
 const http = require('http');
 const https = require('https');
-const { McpClient } = require('./mcp-client');
+const { McpClient, buildMissingCommandMessage, createMissingCommandHint } = require('./mcp-client');
 const { NATIVE_PATHS } = require('../../config/paths');
 const { resolvePreferredHomeDir } = require('../../utils/home-dir');
 
@@ -418,6 +418,102 @@ function writeOpenCodeConfig(filePath, data) {
   fs.renameSync(tempPath, filePath);
 }
 
+function getPathEnvKey(envObj = {}) {
+  return Object.keys(envObj).find(key => key.toLowerCase() === 'path') || 'PATH';
+}
+
+function stripWrappingQuotes(value) {
+  const text = String(value || '').trim();
+  if (!text) return '';
+  if (
+    (text.startsWith('"') && text.endsWith('"')) ||
+    (text.startsWith("'") && text.endsWith("'"))
+  ) {
+    return text.slice(1, -1);
+  }
+  return text;
+}
+
+function mergeSpawnEnv(extraEnv = {}) {
+  const mergedEnv = { ...process.env, ...extraEnv };
+  const processPathKey = getPathEnvKey(process.env);
+  const extraPathKey = getPathEnvKey(extraEnv);
+  const mergedPathKey = getPathEnvKey(mergedEnv);
+
+  const extraPath = extraEnv && typeof extraEnv[extraPathKey] === 'string'
+    ? extraEnv[extraPathKey]
+    : '';
+  const processPath = process.env && typeof process.env[processPathKey] === 'string'
+    ? process.env[processPathKey]
+    : '';
+
+  if (extraPath && processPath) {
+    mergedEnv[mergedPathKey] = `${extraPath}${path.delimiter}${processPath}`;
+  }
+
+  return mergedEnv;
+}
+
+function resolveWindowsSpawnCommand(command, env, cwd) {
+  if (process.platform !== 'win32') {
+    return stripWrappingQuotes(command);
+  }
+
+  const normalizedCommand = stripWrappingQuotes(command);
+  if (!normalizedCommand) {
+    return normalizedCommand;
+  }
+
+  const hasPathSegment = /[\\/]/.test(normalizedCommand) || /^[a-zA-Z]:/.test(normalizedCommand);
+  const hasExtension = path.extname(normalizedCommand).length > 0;
+  const extensions = hasExtension ? [''] : ['.cmd', '.exe', '.bat', '.com'];
+  const resolveCandidate = (basePath) => {
+    for (const ext of extensions) {
+      const candidate = ext ? `${basePath}${ext}` : basePath;
+      if (fs.existsSync(candidate)) {
+        return candidate;
+      }
+    }
+    return null;
+  };
+
+  if (hasPathSegment) {
+    const absoluteBasePath = path.isAbsolute(normalizedCommand)
+      ? normalizedCommand
+      : path.resolve(cwd || process.cwd(), normalizedCommand);
+    return resolveCandidate(absoluteBasePath) || normalizedCommand;
+  }
+
+  const pathKey = getPathEnvKey(env || process.env);
+  const pathValue = env && typeof env[pathKey] === 'string' ? env[pathKey] : '';
+  if (!pathValue) {
+    return normalizedCommand;
+  }
+
+  const searchPaths = pathValue.split(path.delimiter).filter(Boolean);
+  for (const searchPath of searchPaths) {
+    const found = resolveCandidate(path.join(searchPath.trim(), normalizedCommand));
+    if (found) {
+      return found;
+    }
+  }
+
+  return normalizedCommand;
+}
+
+function extractMcpHint(error) {
+  return error?.data?.hint || error?.hint || null;
+}
+
+function buildMcpFailureResult(error, fallbackMessage, duration) {
+  const hint = extractMcpHint(error);
+  return {
+    message: hint?.title || fallbackMessage || error?.message || '操作失败',
+    hint,
+    duration
+  };
+}
+
 // ============================================================================
 // MCP 数据管理
 // ============================================================================
@@ -1218,10 +1314,12 @@ async function testServer(serverId) {
       return { success: false, message: `不支持的服务器类型: ${type}` };
     }
   } catch (err) {
+    const failure = buildMcpFailureResult(err, err.message, Date.now() - startTime);
     return {
       success: false,
-      message: err.message,
-      duration: Date.now() - startTime
+      message: failure.message,
+      hint: failure.hint,
+      duration: failure.duration
     };
   }
 }
@@ -1237,6 +1335,9 @@ async function testStdioServer(spec) {
     // 检查命令是否存在
     const command = spec.command;
     const args = spec.args || [];
+    const cwd = spec.cwd || process.cwd();
+    const mergedEnv = mergeSpawnEnv(spec.env || {});
+    const resolvedCommand = resolveWindowsSpawnCommand(command, mergedEnv, cwd);
 
     let child;
     let resolved = false;
@@ -1260,10 +1361,10 @@ async function testStdioServer(spec) {
     };
 
     try {
-      child = spawn(command, args, {
-        env: { ...process.env, ...spec.env },
+      child = spawn(resolvedCommand, args, {
+        env: mergedEnv,
         stdio: ['pipe', 'pipe', 'pipe'],
-        cwd: spec.cwd || process.cwd()
+        cwd
       });
 
       child.stdout.on('data', (data) => {
@@ -1284,9 +1385,11 @@ async function testStdioServer(spec) {
 
       child.on('error', (err) => {
         if (err.code === 'ENOENT') {
+          const hint = createMissingCommandHint(command, resolvedCommand, mergedEnv);
           done({
             success: false,
-            message: `命令 "${command}" 未找到，请确保已安装`,
+            message: buildMissingCommandMessage(command, resolvedCommand, mergedEnv),
+            hint,
             duration: Date.now() - startTime
           });
         } else {
@@ -1336,10 +1439,12 @@ async function testStdioServer(spec) {
       }, timeout);
 
     } catch (err) {
+      const failure = buildMcpFailureResult(err, `测试失败: ${err.message}`, Date.now() - startTime);
       done({
         success: false,
-        message: `测试失败: ${err.message}`,
-        duration: Date.now() - startTime
+        message: failure.message,
+        hint: failure.hint,
+        duration: failure.duration
       });
     }
   });
@@ -1484,11 +1589,14 @@ async function getServerTools(serverId) {
       mcpClientPool.delete(serverId);
     }
 
+    const failure = buildMcpFailureResult(err, err.message, Date.now() - startTime);
     return {
       tools: [],
-      duration: Date.now() - startTime,
+      duration: failure.duration,
       status: 'error',
-      error: err.message
+      error: failure.message,
+      message: failure.message,
+      hint: failure.hint
     };
   }
 }
@@ -1590,14 +1698,17 @@ async function callServerTool(serverId, toolName, arguments = {}) {
       mcpClientPool.delete(serverId);
     }
 
+    const failure = buildMcpFailureResult(err, err.message, Date.now() - startTime);
     return {
       result: {
-        error: err.message,
+        error: failure.message,
         code: err.code,
         data: err.data
       },
-      duration: Date.now() - startTime,
-      isError: true
+      duration: failure.duration,
+      isError: true,
+      message: failure.message,
+      hint: failure.hint
     };
   }
 }
@@ -1777,5 +1888,9 @@ module.exports = {
   callServerTool,
   updateServerStatus,
   updateServerOrder,
-  exportServers
+  exportServers,
+  _test: {
+    extractMcpHint,
+    buildMcpFailureResult
+  }
 };

package/src/server/services/model-detector.js

@@ -23,6 +23,7 @@ const MODEL_PRIORITY = {
     'claude-haiku-4-5-20251001'
   ],
   codex: [
+    'gpt-5.4',
     'gpt-5.2-codex',
     'gpt-5.1-codex-max',
     'gpt-5.1-codex',

package/src/utils/port-helper.js

@@ -2,10 +2,74 @@ const { execSync } = require('child_process');
 const net = require('net');
 const { isWindowsLikePlatform } = require('./home-dir');
 
+let lastPortToolIssue = null;
+
 function isWindowsLikeRuntime(platform = process.platform, env = process.env) {
   return isWindowsLikePlatform(platform, env);
 }
 
+function clearPortToolIssue() {
+  lastPortToolIssue = null;
+}
+
+function rememberPortToolIssue(issue) {
+  if (!lastPortToolIssue) {
+    lastPortToolIssue = issue;
+  }
+  return lastPortToolIssue;
+}
+
+function getPortToolIssue() {
+  return lastPortToolIssue;
+}
+
+function isMissingCommandError(error) {
+  const message = [
+    error && typeof error.message === 'string' ? error.message : '',
+    error && typeof error.stderr === 'string'
+      ? error.stderr
+      : Buffer.isBuffer(error?.stderr)
+        ? error.stderr.toString('utf-8')
+        : ''
+  ].join('\n');
+
+  return error?.code === 'ENOENT' || /not found|not recognized as an internal or external command/i.test(message);
+}
+
+function createPortToolIssue(command, phase, isWindows) {
+  if (isWindows) {
+    return {
+      command,
+      phase,
+      platform: 'windows',
+      summary: `未找到系统命令 ${command}，无法${phase === 'kill' ? '关闭' : '检测'}占用端口的进程。`,
+      hints: [
+        '请确认已安装或启用 Windows 自带网络工具。',
+        '请将 `C:\\Windows\\System32` 加入 PATH 后重试。'
+      ]
+    };
+  }
+
+  return {
+    command,
+    phase,
+    platform: 'unix',
+    summary: `未找到 ${command}，无法${phase === 'kill' ? '关闭' : '检测'}占用端口的进程。`,
+    hints: [
+      '请安装 `lsof`，或安装提供 `fuser` 的系统工具后重试。',
+      '如果暂时不想安装，也可以改用其他端口。'
+    ]
+  };
+}
+
+function formatPortToolIssue(issue = lastPortToolIssue) {
+  if (!issue) {
+    return [];
+  }
+
+  return [issue.summary, ...issue.hints];
+}
+
 function parsePidsFromNetstatOutput(output, port) {
   const target = `:${port}`;
   const pids = new Set();
@@ -69,6 +133,7 @@ function isPortInUse(port, host = '127.0.0.1') {
  * 查找占用端口的进程PID（跨平台）
  */
 function findProcessByPort(port) {
+  clearPortToolIssue();
   const isWindows = isWindowsLikeRuntime();
   if (isWindows) {
     try {
@@ -76,20 +141,28 @@ function findProcessByPort(port) {
       const result = execSync('netstat -ano', { encoding: 'utf-8' });
       return parsePidsFromNetstatOutput(result, port);
     } catch (e) {
+      if (isMissingCommandError(e)) {
+        rememberPortToolIssue(createPortToolIssue('netstat', 'lookup', true));
+      }
       return [];
     }
   }
 
+  let lsofMissing = false;
   try {
     // macOS/Linux 使用 lsof
     const result = execSync(`lsof -ti :${port}`, { encoding: 'utf-8' }).trim();
     return result.split('\n').filter(pid => pid);
   } catch (err) {
+    lsofMissing = isMissingCommandError(err);
     // 如果 lsof 失败，尝试使用 fuser（某些 Linux 系统）
     try {
       const result = execSync(`fuser ${port}/tcp 2>/dev/null`, { encoding: 'utf-8' }).trim();
       return result.split(/\s+/).filter(pid => pid);
     } catch (e) {
+      if (lsofMissing && isMissingCommandError(e)) {
+        rememberPortToolIssue(createPortToolIssue('lsof / fuser', 'lookup', false));
+      }
       return [];
     }
   }
@@ -106,6 +179,7 @@ function killProcessByPort(port) {
     }
 
     const isWindows = isWindowsLikeRuntime();
+    let killedAny = false;
     pids.forEach(pid => {
       try {
         if (isWindows) {
@@ -113,12 +187,16 @@ function killProcessByPort(port) {
         } else {
           execSync(`kill -9 ${pid}`, { stdio: 'ignore' });
         }
+        killedAny = true;
       } catch (err) {
+        if (isWindows && isMissingCommandError(err)) {
+          rememberPortToolIssue(createPortToolIssue('taskkill', 'kill', true));
+        }
         // 忽略单个进程杀掉失败的错误
       }
     });
 
-    return true;
+    return killedAny;
   } catch (err) {
     return false;
   }
@@ -146,6 +224,13 @@ module.exports = {
   findProcessByPort,
   killProcessByPort,
   waitForPortRelease,
+  getPortToolIssue,
+  formatPortToolIssue,
   isWindowsLikeRuntime,
-  parsePidsFromNetstatOutput
+  parsePidsFromNetstatOutput,
+  _test: {
+    isMissingCommandError,
+    createPortToolIssue,
+    formatPortToolIssue
+  }
 };