coding-tool-x 3.3.6 → 3.3.7

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

@@ -107,6 +107,65 @@ function resolveWindowsSpawnCommand(command, env, cwd) {
   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
 // ============================================================================
@@ -356,19 +415,11 @@ class McpClient extends EventEmitter {
 
       this._child.on('error', (err) => {
         if (err.code === 'ENOENT') {
-          const pathKey = getPathEnvKey(mergedEnv);
-          const pathValue = typeof mergedEnv[pathKey] === 'string' ? mergedEnv[pathKey] : '';
-          const pathHint = pathValue
-            ? `\n  Current PATH: ${pathValue.split(path.delimiter).slice(0, 5).join(path.delimiter)}\n  (showing first 5 entries)`
-            : '\n  PATH is not set!';
-          const commandHint = resolvedCommand === command
-            ? command
-            : `${command} (resolved: ${resolvedCommand})`;
+          const hint = createMissingCommandHint(command, resolvedCommand, mergedEnv)
           settle(new McpClientError(
-            `Command "${commandHint}" not found. Please check:\n` +
-            `  1. Is "${command}" installed?\n` +
-            `  2. Try using absolute path${process.platform === 'win32' ? ' (e.g., C:\\\\Program Files\\\\nodejs\\\\npx.cmd)' : ` (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}`));
@@ -873,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');
 
@@ -501,6 +501,19 @@ function resolveWindowsSpawnCommand(command, env, cwd) {
   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 数据管理
 // ============================================================================
@@ -1301,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
     };
   }
 }
@@ -1370,10 +1385,11 @@ async function testStdioServer(spec) {
 
       child.on('error', (err) => {
         if (err.code === 'ENOENT') {
-          const commandLabel = resolvedCommand === command ? command : `${command} (resolved: ${resolvedCommand})`;
+          const hint = createMissingCommandHint(command, resolvedCommand, mergedEnv);
           done({
             success: false,
-            message: `命令 "${commandLabel}" 未找到，请确保已安装（Windows 可尝试 npx.cmd 或绝对路径）`,
+            message: buildMissingCommandMessage(command, resolvedCommand, mergedEnv),
+            hint,
             duration: Date.now() - startTime
           });
         } else {
@@ -1423,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
       });
     }
   });
@@ -1571,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
     };
   }
 }
@@ -1677,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
     };
   }
 }
@@ -1864,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
+  }
 };