yingclaw 2.5.0 → 2.5.2

package/README.md

@@ -47,8 +47,11 @@ claw code
 接入 Claude 桌面应用：
 ```bash
 claw desktop
+claw gateway
 ```
-将配置写入 Claude Desktop 第三方推理本地配置。macOS 会自动重启 Claude Desktop；Windows 需手动重新打开。
+`claw desktop` 会把 Claude Desktop 指向 yingclaw 本机 Gateway，并只暴露 `claude-sonnet-4-6`、`claude-opus-4-7`、`claude-haiku-4-5` 这类 Claude Desktop 可接受的模型名。真实第三方模型仍按 `claw config` 保存的主模型和快速模型转发。
+
+使用 Claude Desktop 时需要保持 `claw gateway` 运行。
 
 ## 支持的厂商
 
@@ -71,6 +74,8 @@ claw                 # 交互菜单（无参数时自动进入）
 claw config          # 配置 API 连接
 claw code            # 接入 Claude Code 终端
 claw desktop         # 接入 Claude 桌面应用
+claw gateway         # 启动 Claude 桌面应用本机 Gateway
+claw desktop --direct # 高级：直连写入厂商 Gateway URL
 claw switch          # 快速切换厂商或模型
 claw status          # 查看当前配置，验证 Key 是否有效
 claw update          # 检查并升级到最新版本
@@ -105,12 +110,14 @@ CLAUDE_CODE_SUBAGENT_MODEL
 CLAUDE_CODE_EFFORT_LEVEL
 ```
 
-**桌面接入**（`claw desktop`）写入 Claude Desktop 第三方推理配置：
+**桌面接入**（`claw desktop`）默认写入本机 Gateway：
 
-- macOS：`~/Library/Application Support/Claude-3p/configLibrary/`
-- Windows：`%APPDATA%\Claude-3p\configLibrary\`
+- macOS / Windows：写入 `Claude-3p/configLibrary/` 中的 yingclaw entry
+- Claude Desktop 访问 `http://127.0.0.1:18080/yingclaw`
+- Gateway 再转发到当前保存的 Anthropic 兼容接口
+- 终端接入仍直接使用 `ANTHROPIC_*` 环境变量，不受桌面 Gateway 影响
 
-使用 `inferenceProvider=gateway`、`inferenceGatewayAuthScheme=bearer`，将 Gateway Base URL 指向对应厂商的 Anthropic 兼容接口。桌面接入要求 Base URL 使用 HTTPS。
+使用 `inferenceProvider=gateway`、`inferenceGatewayAuthScheme=bearer`，将 Gateway Base URL 指向 yingclaw 本机 Gateway。高级用户可用 `claw desktop --direct` 保留旧式直连写入，但新版 Claude Desktop 可能拒绝非 Claude 模型名。
 
 **自定义接口**需支持 Anthropic `/v1/messages` 格式；工具会根据 Base URL 自动尝试获取模型列表，失败则手动输入。
 

package/bin/cli.js

@@ -21,8 +21,14 @@ const {
 const { execSync, spawn, spawnSync } = require('child_process');
 const pkg = require('../package.json');
 const { buildMenuStatusLines, buildStatusView } = require('../lib/panel');
-const { buildClaudeInstallCommand } = require('../lib/install');
+const { buildClaudeInstallCommand, checkNodeEnv, getNodeInstallGuide, getInstallFailureHints } = require('../lib/install');
 const { clearClaudeDesktopConfig, isDesktopConfigured, openClaudeDesktop, writeClaudeDesktopConfig } = require('../lib/desktop');
+const {
+  DEFAULT_DESKTOP_GATEWAY_PORT,
+  YINGCLAW_GATEWAY_PREFIX,
+  createGatewayServer,
+  ensureDesktopGatewayConfig,
+} = require('../lib/gateway');
 const { runDoctorChecks, summarize, STATUS_OK, STATUS_FAIL, STATUS_WARN, STATUS_INFO } = require('../lib/doctor');
 
 const program = new Command();
@@ -402,6 +408,31 @@ program
       if (!yes) return;
     } catch {}
 
+    // 检查 npm / Node.js 环境
+    const nodeEnv = checkNodeEnv();
+    if (!nodeEnv.npmOk) {
+      console.log(boxen(
+        chalk.bold.red('未检测到 npm，无法安装 Claude Code\n\n') +
+        chalk.dim('Claude Code 通过 npm 安装，需要先安装 Node.js（含 npm）。\n\n') +
+        chalk.bold('安装方式：\n') +
+        getNodeInstallGuide().map(l => chalk.cyan('  ' + l)).join('\n') +
+        '\n\n' + chalk.dim('安装完成后重新运行 claw install-claude'),
+        { padding: { top: 0, bottom: 0, left: 2, right: 2 }, borderStyle: 'round', borderColor: 'red', margin: { top: 1, bottom: 1 } }
+      ));
+      return;
+    }
+    if (!nodeEnv.nodeOk) {
+      console.log(boxen(
+        chalk.bold.yellow(`Node.js 版本过低（当前 v${nodeEnv.nodeVersion}，需要 ≥18）\n\n`) +
+        chalk.dim('Claude Code 要求 Node.js ≥18，当前版本可能导致安装或运行失败。\n\n') +
+        chalk.bold('升级方式：\n') +
+        getNodeInstallGuide().map(l => chalk.cyan('  ' + l)).join('\n'),
+        { padding: { top: 0, bottom: 0, left: 2, right: 2 }, borderStyle: 'round', borderColor: 'yellow', margin: { top: 1, bottom: 1 } }
+      ));
+      const proceed = await confirm({ message: '仍然尝试安装？', default: false });
+      if (!proceed) return;
+    }
+
     const network = await select({ loop: false,
       message: chalk.cyan('你的网络环境'),
       choices: [
@@ -423,10 +454,9 @@ program
       console.log(chalk.green('\n✔ Claude Code 安装成功！'));
     } else {
       console.log(chalk.red('\n✘ 安装失败'));
+      const hints = getInstallFailureHints(result, chalk);
       console.log(boxen(
-        chalk.bold('手动安装：\n\n') +
-        chalk.cyan('npm config set registry https://registry.npmmirror.com\n') +
-        chalk.cyan('npm install -g @anthropic-ai/claude-code'),
+        hints.join(''),
         { padding: { top: 0, bottom: 0, left: 2, right: 2 }, borderStyle: 'round', borderColor: 'yellow', margin: { top: 1, bottom: 1 } }
       ));
       return;
@@ -638,10 +668,54 @@ program
   .description('查看当前配置和 Key 有效性')
   .action(showStatus);
 
+program
+  .command('gateway')
+  .description('启动 Claude 桌面应用本机 Gateway')
+  .option('-p, --port <port>', '监听端口')
+  .action(async (options) => {
+    const chalk = (await import('chalk')).default;
+    const boxen = (await import('boxen')).default;
+
+    let config = loadConfig();
+    if (!config) {
+      console.log(chalk.red('\n未配置 API 连接，请先运行: claw config\n'));
+      return;
+    }
+    const configProblem = getConfigValidationMessage(config);
+    if (configProblem) {
+      console.log(chalk.red(`\n配置无效：${configProblem}`));
+      console.log(chalk.dim('请运行 claw config 重新配置。\n'));
+      return;
+    }
+
+    const ensuredConfig = ensureDesktopGatewayConfig(config);
+    if (ensuredConfig.desktopGatewayKey !== config.desktopGatewayKey || ensuredConfig.desktopGatewayPort !== config.desktopGatewayPort) {
+      saveConfig(ensuredConfig);
+      config = ensuredConfig;
+    }
+
+    const port = Number.parseInt(options.port || config.desktopGatewayPort || DEFAULT_DESKTOP_GATEWAY_PORT, 10);
+    const server = createGatewayServer();
+    server.listen(port, '127.0.0.1', () => {
+      console.log(boxen(
+        chalk.bold('yingclaw Desktop Gateway 已启动\n\n') +
+        chalk.dim('URL   ') + chalk.cyan(`http://127.0.0.1:${port}${YINGCLAW_GATEWAY_PREFIX}`) + '\n' +
+        chalk.dim('模型  ') + chalk.yellow(config.model) + '\n\n' +
+        chalk.dim('保持此终端打开，Claude Desktop 才能访问第三方模型。'),
+        { padding: { top: 0, bottom: 0, left: 2, right: 2 }, borderStyle: 'round', borderColor: 'green', margin: { top: 1, bottom: 1 } }
+      ));
+    });
+    server.on('error', (error) => {
+      console.error(chalk.red(`Gateway 启动失败: ${error.message}`));
+      process.exitCode = 1;
+    });
+  });
+
 program
   .command('desktop')
   .description('接入 Claude 桌面应用使用当前模型')
-  .action(async () => {
+  .option('--direct', '高级：直接写入当前厂商 Gateway URL，不启用本机模型映射')
+  .action(async (options) => {
     const chalk = (await import('chalk')).default;
     const ora = (await import('ora')).default;
     const boxen = (await import('boxen')).default;
@@ -665,10 +739,18 @@ program
       return;
     }
 
+    let desktopConfig = config;
+    if (!options.direct) {
+      desktopConfig = ensureDesktopGatewayConfig(config);
+      if (desktopConfig.desktopGatewayKey !== config.desktopGatewayKey || desktopConfig.desktopGatewayPort !== config.desktopGatewayPort) {
+        saveConfig(desktopConfig);
+      }
+    }
+
     const spinner = ora('写入 Claude 桌面应用配置...').start();
     let result;
     try {
-      result = writeClaudeDesktopConfig(config);
+      result = writeClaudeDesktopConfig(desktopConfig, { direct: options.direct });
       if (result.result === 'unsupported') {
         spinner.warn(chalk.yellow('当前系统暂不支持自动配置 Claude 桌面应用'));
         return;
@@ -679,13 +761,22 @@ program
       return;
     }
 
+    const gatewayUrl = `http://127.0.0.1:${desktopConfig.desktopGatewayPort}${YINGCLAW_GATEWAY_PREFIX}`;
+    const modeLines = options.direct
+      ? chalk.dim('Base URL  ') + chalk.cyan(desktopConfig.baseUrl) + '\n' +
+        chalk.dim('模型      ') + chalk.yellow(desktopConfig.model) + '\n' +
+        chalk.yellow('直连模式可能被新版 Claude Desktop 拒绝非 Claude 模型名。')
+      : chalk.dim('Gateway  ') + chalk.cyan(gatewayUrl) + '\n' +
+        chalk.dim('主模型    ') + chalk.yellow(desktopConfig.model) + '\n' +
+        chalk.dim('快速模型  ') + chalk.yellow(desktopConfig.fastModel || desktopConfig.model) + '\n\n' +
+        chalk.cyan('使用前请运行: claw gateway');
+
     console.log(boxen(
-      chalk.bold('Claude 桌面应用已配置为 Gateway 模式\n\n') +
-      chalk.dim('Base URL  ') + chalk.cyan(config.baseUrl) + '\n' +
-      chalk.dim('模型      ') + chalk.yellow(config.model) + '\n' +
+      chalk.bold(options.direct ? 'Claude 桌面应用已配置为直连 Gateway 模式\n\n' : 'Claude 桌面应用已配置为本机 Gateway 模式\n\n') +
+      modeLines + '\n' +
       chalk.dim('认证方式  ') + chalk.cyan('bearer') + '\n\n' +
       chalk.yellow(getDesktopOpenHint()) + '\n' +
-      chalk.dim('要求：网关必须支持 Anthropic POST /v1/messages，且 Base URL 必须是 HTTPS。'),
+      chalk.dim(options.direct ? '要求：网关必须支持 Anthropic POST /v1/messages，且 Base URL 必须是 HTTPS。' : '要求：保持 claw gateway 运行，Claude Desktop 才能访问第三方模型。'),
       { padding: { top: 0, bottom: 0, left: 2, right: 2 }, borderStyle: 'round', borderColor: 'cyan', margin: { top: 1, bottom: 1 } }
     ));
 

package/index.js

@@ -1,6 +1,7 @@
 module.exports = {
   ...require('./lib/config'),
   ...require('./lib/desktop'),
+  ...require('./lib/gateway'),
   ...require('./lib/install'),
   ...require('./lib/panel'),
 };

package/lib/desktop.js

@@ -4,6 +4,11 @@ const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { normalizeAnthropicBaseUrl } = require('./config');
+const {
+  YINGCLAW_GATEWAY_PREFIX,
+  buildDesktopGatewayRoutes,
+  ensureDesktopGatewayConfig,
+} = require('./gateway');
 
 const CLAUDE_DESKTOP_LABEL = 'Claude 桌面应用配置';
 const YINGCLAW_ENTRY_NAME = 'yingclaw';
@@ -60,16 +65,43 @@ function toDesktopModelId(model) {
   return model.startsWith('claude-') ? model : `claude-${model}`;
 }
 
-function collectModels(config) {
+function collectDirectModels(config) {
   const list = Array.isArray(config.availableModels) && config.availableModels.length > 0
     ? [config.model, config.fastModel, ...config.availableModels]
     : [config.model, config.fastModel];
   return [...new Set(list.filter(Boolean).map(toDesktopModelId))];
 }
 
-// 按官方 schema：所有值必须是字符串（包括布尔、数组都序列化）
+function buildGatewayBaseUrl(config) {
+  const port = config.desktopGatewayPort || 18080;
+  return `http://127.0.0.1:${port}${YINGCLAW_GATEWAY_PREFIX}`;
+}
+
+function serializeGatewayModels(config) {
+  return buildDesktopGatewayRoutes(config).map((route) => {
+    const item = { name: route.id, displayName: route.displayName };
+    if (route.supports1m) item.supports1m = true;
+    return item;
+  });
+}
+
 function buildClaudeDesktopEnterpriseConfig(config, options = {}) {
-  const models = collectModels(config);
+  const gatewayConfig = ensureDesktopGatewayConfig(config, options);
+  const models = serializeGatewayModels(gatewayConfig);
+  return {
+    inferenceProvider: 'gateway',
+    inferenceGatewayBaseUrl: buildGatewayBaseUrl(gatewayConfig),
+    inferenceGatewayApiKey: gatewayConfig.desktopGatewayKey,
+    inferenceGatewayAuthScheme: options.authScheme || 'bearer',
+    inferenceModels: JSON.stringify(models),
+    disableDeploymentModeChooser: 'true',
+    deploymentOrganizationUuid: options.uuid || crypto.randomUUID(),
+  };
+}
+
+// 兼容旧版直连模式：写入真实 provider Gateway URL 和真实 Key。
+function buildClaudeDesktopDirectEnterpriseConfig(config, options = {}) {
+  const models = collectDirectModels(config);
   const baseUrl = normalizeAnthropicBaseUrl(config.baseUrl);
   if (!baseUrl.startsWith('https://')) {
     throw new Error('Claude 桌面应用要求 Gateway Base URL 使用 HTTPS');
@@ -131,10 +163,9 @@ function clearClaudeDesktopConfigLibrary(options = {}) {
 
 // 写入 Claude-3p/configLibrary/ 下的 enterprise config 条目（主进程从此处读取）
 function writeClaudeDesktopConfig(config, options = {}) {
-  const baseUrl = normalizeAnthropicBaseUrl(config.baseUrl);
-  if (!baseUrl.startsWith('https://')) {
-    throw new Error('Claude 桌面应用要求 Gateway Base URL 使用 HTTPS');
-  }
+  const effectiveConfig = options.direct
+    ? config
+    : ensureDesktopGatewayConfig(config, options);
 
   const dataDir = options.dataDir || getClaudeDesktopDataDir(options);
   if (!dataDir) {
@@ -149,13 +180,18 @@ function writeClaudeDesktopConfig(config, options = {}) {
   const existingYingclaw = existingEntries.find((entry) => entry && entry.name === YINGCLAW_ENTRY_NAME);
   const uuid = existingYingclaw?.id || options.uuid || crypto.randomUUID();
 
-  const models = collectModels(config);
+  const models = options.direct
+    ? collectDirectModels(effectiveConfig)
+    : serializeGatewayModels(effectiveConfig);
+  const enterprise = options.direct
+    ? buildClaudeDesktopDirectEnterpriseConfig(effectiveConfig, { ...options, uuid })
+    : buildClaudeDesktopEnterpriseConfig(effectiveConfig, { ...options, uuid });
 
   const entry = {
-    inferenceProvider: 'gateway',
-    inferenceGatewayBaseUrl: baseUrl,
-    inferenceGatewayApiKey: config.apiKey,
-    inferenceGatewayAuthScheme: options.authScheme || 'bearer',
+    inferenceProvider: enterprise.inferenceProvider,
+    inferenceGatewayBaseUrl: enterprise.inferenceGatewayBaseUrl,
+    inferenceGatewayApiKey: enterprise.inferenceGatewayApiKey,
+    inferenceGatewayAuthScheme: enterprise.inferenceGatewayAuthScheme,
     inferenceModels: models,
     disableDeploymentModeChooser: true,
     deploymentOrganizationUuid: uuid,
@@ -184,7 +220,7 @@ function writeClaudeDesktopConfig(config, options = {}) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, JSON.stringify(next, null, 2) + '\n');
 
-  return { result: beforeEntry === entryBody ? 'unchanged' : 'updated', file };
+  return { result: beforeEntry === entryBody ? 'unchanged' : 'updated', file, config: effectiveConfig };
 }
 
 function clearClaudeDesktopConfig(options = {}) {
@@ -293,8 +329,10 @@ async function openClaudeDesktop(options = {}) {
 
 module.exports = {
   buildClaudeDesktopEnterpriseConfig,
+  buildClaudeDesktopDirectEnterpriseConfig,
   buildClaudeDesktopOpenCommands,
   clearClaudeDesktopConfig,
+  getClaudeDesktopConfigLibraryDir,
   getClaudeDesktopConfigPath,
   getClaudeDesktopDataDir,
   isDesktopConfigured,

package/lib/gateway.js

@@ -0,0 +1,198 @@
+const crypto = require('crypto');
+const http = require('http');
+const { loadConfig: defaultLoadConfig, normalizeAnthropicBaseUrl } = require('./config');
+
+const DEFAULT_DESKTOP_GATEWAY_PORT = 18080;
+const YINGCLAW_GATEWAY_PREFIX = '/yingclaw';
+const DESKTOP_ROUTE_SPECS = [
+  { id: 'claude-sonnet-4-6', displayName: 'Sonnet', upstreamKey: 'model' },
+  { id: 'claude-opus-4-7', displayName: 'Opus', upstreamKey: 'model' },
+  { id: 'claude-haiku-4-5', displayName: 'Haiku', upstreamKey: 'fastModel' },
+];
+
+function createGatewayKey() {
+  return `ygw-${crypto.randomUUID()}`;
+}
+
+function ensureDesktopGatewayConfig(config, options = {}) {
+  const keyFactory = options.keyFactory || createGatewayKey;
+  return {
+    ...config,
+    desktopGatewayPort: config.desktopGatewayPort || DEFAULT_DESKTOP_GATEWAY_PORT,
+    desktopGatewayKey: config.desktopGatewayKey || keyFactory(),
+  };
+}
+
+function modelSupports1m(model) {
+  return /\[1m\]/i.test(String(model || ''));
+}
+
+function buildDesktopGatewayRoutes(config) {
+  const fastModel = config.fastModel || config.model;
+  const source = { model: config.model, fastModel };
+  return DESKTOP_ROUTE_SPECS
+    .map((spec) => {
+      const upstreamModel = source[spec.upstreamKey];
+      return upstreamModel ? {
+        id: spec.id,
+        displayName: spec.displayName,
+        upstreamModel,
+        supports1m: modelSupports1m(upstreamModel),
+      } : null;
+    })
+    .filter(Boolean);
+}
+
+function mapDesktopRouteToUpstream(config, routeId) {
+  const route = buildDesktopGatewayRoutes(config).find((item) => item.id === routeId);
+  if (!route) {
+    throw new Error(`未配置的 Claude Desktop 模型路由: ${routeId}`);
+  }
+  return route.upstreamModel;
+}
+
+function buildGatewayModelsResponse(config) {
+  const data = buildDesktopGatewayRoutes(config).map((route) => {
+    const item = {
+      type: 'model',
+      id: route.id,
+      display_name: route.displayName,
+      created_at: '2024-01-01T00:00:00Z',
+    };
+    if (route.supports1m) item.supports1m = true;
+    return item;
+  });
+  return {
+    data,
+    has_more: false,
+    first_id: data[0]?.id || null,
+    last_id: data.at(-1)?.id || null,
+  };
+}
+
+function sendJson(res, status, body) {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+function readRequestBody(req) {
+  return new Promise((resolve, reject) => {
+    let raw = '';
+    req.setEncoding('utf8');
+    req.on('data', chunk => { raw += chunk; });
+    req.on('end', () => resolve(raw));
+    req.on('error', reject);
+  });
+}
+
+function isAuthorized(req, config) {
+  const key = config.desktopGatewayKey;
+  if (!key) return false;
+  const auth = String(req.headers.authorization || '');
+  const bearer = auth.replace(/^bearer\s+/i, '').trim();
+  const apiKey = String(req.headers['x-api-key'] || '').trim();
+  return bearer === key || apiKey === key;
+}
+
+function providerMessagesUrl(config) {
+  return `${normalizeAnthropicBaseUrl(config.baseUrl)}/v1/messages`;
+}
+
+async function proxyMessages(req, res, config) {
+  const raw = await readRequestBody(req);
+  let body;
+  try {
+    body = raw ? JSON.parse(raw) : {};
+  } catch {
+    sendJson(res, 400, { error: { message: '请求体不是有效 JSON' } });
+    return;
+  }
+
+  try {
+    body.model = mapDesktopRouteToUpstream(config, body.model);
+  } catch (error) {
+    sendJson(res, 400, { error: { message: error.message } });
+    return;
+  }
+
+  const upstream = await fetch(providerMessagesUrl(config), {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      accept: body.stream ? 'text/event-stream' : 'application/json',
+      authorization: `Bearer ${config.apiKey}`,
+      'x-api-key': config.apiKey,
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify(body),
+  });
+
+  res.writeHead(upstream.status, {
+    'content-type': upstream.headers.get('content-type') || (body.stream ? 'text/event-stream' : 'application/json'),
+    'cache-control': upstream.headers.get('cache-control') || 'no-cache',
+  });
+
+  if (!upstream.body) {
+    res.end();
+    return;
+  }
+  for await (const chunk of upstream.body) {
+    res.write(chunk);
+  }
+  res.end();
+}
+
+function createGatewayServer(options = {}) {
+  const loadConfig = options.loadConfig || defaultLoadConfig;
+  return http.createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url, 'http://127.0.0.1');
+      const config = loadConfig();
+
+      if (url.pathname === `${YINGCLAW_GATEWAY_PREFIX}/health`) {
+        sendJson(res, 200, { status: 'ok' });
+        return;
+      }
+
+      if (!config) {
+        sendJson(res, 503, { error: { message: 'yingclaw 尚未配置 API 连接' } });
+        return;
+      }
+
+      if (url.pathname === `${YINGCLAW_GATEWAY_PREFIX}/v1/models` && req.method === 'GET') {
+        if (!isAuthorized(req, config)) {
+          sendJson(res, 401, { error: { message: 'Invalid gateway API key' } });
+          return;
+        }
+        sendJson(res, 200, buildGatewayModelsResponse(config));
+        return;
+      }
+
+      if (url.pathname === `${YINGCLAW_GATEWAY_PREFIX}/v1/messages` && req.method === 'POST') {
+        if (!isAuthorized(req, config)) {
+          sendJson(res, 401, { error: { message: 'Invalid gateway API key' } });
+          return;
+        }
+        await proxyMessages(req, res, config);
+        return;
+      }
+
+      sendJson(res, 404, { error: { message: 'Not found' } });
+    } catch (error) {
+      sendJson(res, 500, { error: { message: error.message } });
+    }
+  });
+}
+
+module.exports = {
+  DEFAULT_DESKTOP_GATEWAY_PORT,
+  YINGCLAW_GATEWAY_PREFIX,
+  DESKTOP_ROUTE_SPECS,
+  createGatewayKey,
+  ensureDesktopGatewayConfig,
+  modelSupports1m,
+  buildDesktopGatewayRoutes,
+  mapDesktopRouteToUpstream,
+  buildGatewayModelsResponse,
+  createGatewayServer,
+};

package/lib/install.js

@@ -1,3 +1,5 @@
+const { execSync } = require('child_process');
+
 function buildClaudeInstallCommand(network) {
   const args = ['install', '-g', '@anthropic-ai/claude-code'];
   if (network === 'cn') {
@@ -6,4 +8,87 @@ function buildClaudeInstallCommand(network) {
   return { command: 'npm', args };
 }
 
-module.exports = { buildClaudeInstallCommand };
+function checkNodeEnv() {
+  const nodeVersion = process.versions.node;
+  const nodeMajor = parseInt(nodeVersion.split('.')[0], 10);
+
+  let npmVersion = null;
+  try {
+    // Windows 上 npm 是 .cmd 文件，必须加 shell: true 才能找到
+    npmVersion = execSync('npm --version', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      shell: process.platform === 'win32',
+    }).trim();
+  } catch {}
+
+  return {
+    nodeVersion,
+    nodeMajor,
+    nodeOk: nodeMajor >= 18,
+    npmVersion,
+    npmOk: !!npmVersion,
+  };
+}
+
+function getNodeInstallGuide() {
+  const platform = process.platform;
+  if (platform === 'darwin') {
+    return [
+      'Homebrew:   brew install node',
+      '官方安装包: https://nodejs.org  （选 LTS 版本）',
+    ];
+  }
+  if (platform === 'win32') {
+    return [
+      '官方安装包: https://nodejs.org  （选 LTS 版本）',
+      'winget:     winget install OpenJS.NodeJS.LTS',
+    ];
+  }
+  return [
+    'Ubuntu/Debian: sudo apt install nodejs npm',
+    'CentOS/RHEL:   sudo yum install nodejs npm',
+    'nvm（推荐）:   https://github.com/nvm-sh/nvm',
+  ];
+}
+
+/**
+ * 根据 spawnSync 结果判断失败原因，返回对应的提示内容（chalk 字符串数组）。
+ * @param {object} result spawnSync 返回值
+ * @param {Function} chalk chalk 实例
+ * @returns {string[]}
+ */
+function getInstallFailureHints(result, chalk) {
+  // spawnSync 找不到命令（npm 在执行时消失或环境问题）
+  if (result.status === null && result.error?.code === 'ENOENT') {
+    return [
+      chalk.bold.red('npm 命令未找到\n\n'),
+      chalk.dim('安装 Node.js 后重试：\n'),
+      ...getNodeInstallGuide().map(l => chalk.cyan('  ' + l)),
+    ];
+  }
+
+  // 尝试从 stderr 判断权限错误（stdio inherit 时 stderr 为 null，兜底靠文字提示）
+  const stderr = result.stderr ? result.stderr.toString() : '';
+  if (stderr.includes('EACCES') || stderr.includes('permission denied') || stderr.includes('Access is denied')) {
+    const fixes = process.platform === 'win32'
+      ? ['以管理员身份运行 PowerShell / CMD，然后重试']
+      : [
+          'sudo npm install -g @anthropic-ai/claude-code',
+          '或修复 npm 全局目录权限：https://docs.npmjs.com/resolving-eacces-permissions-errors',
+        ];
+    return [
+      chalk.bold.red('权限不足（EACCES）\n\n'),
+      ...fixes.map(l => chalk.cyan('  ' + l)),
+    ];
+  }
+
+  // 通用失败：显示手动安装命令
+  return [
+    chalk.bold('手动安装：\n\n'),
+    chalk.cyan('npm config set registry https://registry.npmmirror.com\n'),
+    chalk.cyan('npm install -g @anthropic-ai/claude-code'),
+  ];
+}
+
+module.exports = { buildClaudeInstallCommand, checkNodeEnv, getNodeInstallGuide, getInstallFailureHints };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yingclaw",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "description": "Claude Code × 国产大模型一键接入：DeepSeek、Kimi、Qwen、MiniMax、GLM、MiMo",
   "main": "index.js",
   "bin": {