@sanqianx/claude-ai-workbench 0.13.0 → 0.13.2-rc.1

package/README.md

@@ -12,6 +12,10 @@
 
 工作台是产品供应商与凭据的活动配置源。后台维护默认模型持久化，不随会话临时模型切换；解析后的凭据只交给鉴权本地服务，不进入浏览器消息。SDK 会话从当前项目登记的工作区恢复，也兼容旧登记文件。
 
+MiniMax 向量模型使用独立的 `/v1/embeddings` 接口，不复用聊天的 `/anthropic` 路由。官方域名的已知接口后缀在运行期规范化为服务根地址，现有配置文件不被迁移或改写；自定义网关路径保持原样。
+
+Windows 上 Claude Code 探测与实际启动使用同一解析结果：失效的 `CLAUDE_CODE_EXECPATH` 不遮住有效安装，npm/CMD/PowerShell 启动脚本解析成实际文件，JavaScript 入口用当前 Node 探测版本。`/system/doctor` 返回实际启动路径、被跳过的失效路径及版本探测错误。发现和会话失败使用 `log/v2`；受外壳守护时写入外壳统一诊断，独立运行保存在工作台数据目录的 `diagnostics.jsonl`，不记录凭据或原始提示词。
+
 ## 仓库结构
 
 - `packages/`：可发布的 SDK 源码。

package/docs/sdk/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Claude AI Workbench API
-  version: 0.13.0
+  version: 0.13.2-rc.1
   description: Versioned local API for AI Profile, credential and Claude Code session management.
 servers:
   - url: http://127.0.0.1:5760/api/claude-workbench/v1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanqianx/claude-ai-workbench",
-  "version": "0.13.0",
+  "version": "0.13.2-rc.1",
   "description": "Shared Claude Code terminal and Anthropic-compatible AI profile modules for local developer tools.",
   "type": "commonjs",
   "main": "src/index.js",

package/packages/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-ai-workbench/client",
-  "version": "0.13.0",
+  "version": "0.13.2-rc.1",
   "type": "commonjs",
   "main": "index.js",
   "browser": "index.js",
@@ -20,7 +20,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@claude-ai-workbench/contracts": "0.13.0"
+    "@claude-ai-workbench/contracts": "0.13.2-rc.1"
   },
   "engines": {
     "node": ">=18"

package/packages/contracts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-ai-workbench/contracts",
-  "version": "0.13.0",
+  "version": "0.13.2-rc.1",
   "type": "commonjs",
   "main": "index.js",
   "types": "index.d.ts",

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-ai-workbench/core",
-  "version": "0.13.0",
+  "version": "0.13.2-rc.1",
   "type": "commonjs",
   "main": "index.js",
   "browser": "index.js",
@@ -20,7 +20,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@claude-ai-workbench/contracts": "0.13.0"
+    "@claude-ai-workbench/contracts": "0.13.2-rc.1"
   },
   "engines": {
     "node": ">=18"

package/packages/server/index.js

@@ -15,7 +15,8 @@ const { AttachmentStore } = require('./lib/attachment-store');
 const { ProjectStore } = require('./lib/project-store');
 const { SessionArchiveStore } = require('./lib/session-archive-store');
 const { AgentRegistry } = require('./lib/agent-registry');
-const { createAgentDiscovery, probeExecutableVersion } = require('./lib/agent-discovery');
+const { createAgentDiscovery, probeExecutable } = require('./lib/agent-discovery');
+const { createDiagnostics } = require('./lib/diagnostics');
 const { createSystemDoctor } = require('./lib/system-doctor');
 const { createModelDetection } = require('./lib/model-detection');
 const { createCodexDriver } = require('./lib/drivers/codex-driver');
@@ -68,6 +69,7 @@ function createWorkbenchServer(options = {}) {
     },
   });
   const runner = registry.asRunner();
+  const diagnostics = options.logger || createDiagnostics({ dataDir, secrets: () => [...Object.values(profiles._credentials().credentials), process.env.ANTHROPIC_API_KEY, process.env.ANTHROPIC_AUTH_TOKEN] });
   const agentDiscovery = options.agentDiscovery || createAgentDiscovery({
     claudeProbe: () => {
       try {
@@ -77,11 +79,17 @@ function createWorkbenchServer(options = {}) {
         const cmd = typeof executable === 'string'
           ? executable
           : executable && executable.cmd;
-        if (!cmd) return { available: false, version: null };
+        if (!cmd) {
+          const reason = executable?.reason || '未发现可用的 Claude Code 启动文件。';
+          diagnostics.error('agent.discovery.failed', 'Claude Code 不可用。', { phase: 'discovery', error: { code: 'CLAUDE_EXECUTABLE_NOT_FOUND', message: reason }, context: { agent: 'claude-code', rejectedPaths: executable?.rejected || [] } });
+          return { available: false, version: null, reason };
+        }
         // Honest probe: spawn the resolved executable with --version. Same
         // contract as every other agent: no version, no availability claim.
-        const version = probeExecutableVersion(cmd);
-        return { available: version != null, version };
+        const probe = probeExecutable(cmd);
+        if (!probe.available) diagnostics.error('agent.discovery.failed', 'Claude Code 版本探测失败。', { phase: 'version-probe', error: { code: probe.code, message: probe.reason }, context: { agent: 'claude-code', executable: cmd, exitCode: probe.exitCode } });
+        else if (executable.rejected?.length) diagnostics.warn('agent.discovery.recovered', '已跳过失效的 Claude Code 启动路径，使用有效安装。', { phase: 'discovery', context: { executable: cmd, rejectedPaths: executable.rejected } });
+        return probe;
       } catch { return { available: false, version: null }; }
     },
   });
@@ -89,16 +97,22 @@ function createWorkbenchServer(options = {}) {
   const modelDetection = options.modelDetection || createModelDetection({
     contextLookup: modelContextWindows && modelContextWindows.lookupContextWindow,
   });
-  const doctor = options.doctor || createSystemDoctor({
+  const collectDoctor = options.doctor || createSystemDoctor({
     resolveClaudeExecutable: () => {
       try { return claudeDriver.findClaudeExecutableForSdk(); } catch { return { cmd: null }; }
     },
     discoverZCodeCli,
     probeZCodeVersion,
   });
+  const doctor = () => {
+    const report = collectDoctor();
+    const claude = report.agents?.['claude-code'];
+    if (claude && !claude.versionProbe?.ok) diagnostics.error('agent.doctor.failed', 'Claude Code 环境诊断失败。', { phase: 'doctor', error: { code: 'CLAUDE_PROBE_FAILED', message: claude.versionProbe?.error || claude.resolutionReason }, context: { agent: 'claude-code', executable: claude.resolvedExecutable, rejectedPaths: claude.rejectedPaths, exitCode: claude.versionProbe?.exitCode } });
+    return report;
+  };
   const service = options.service || new WorkbenchService({
     knowledge: options.knowledge || new (require('./lib/knowledge-context').KnowledgeContext)({ engineUrl: options.engineUrl || process.env.KB_KNOWLEDGE_ENGINE_URL, contextFile: path.join(dataDir, 'knowledge-contexts.v1.json') }),
-    runner, profiles, contexts, attachments, apiPrefix,
+    runner, profiles, contexts, attachments, apiPrefix, diagnostics,
     projects, sessionArchive, agentDiscovery, modelContextWindows, modelDetection,
     archiveRetentionDays: options.archiveRetentionDays,
     captureSettings, uiPreferences, onCaptureSettingsSaved: applyBridgeCapture,

package/packages/server/lib/agent-discovery.js

@@ -17,19 +17,22 @@ const CACHE_TTL_MS = 30000;
   // Spawns `<executable> --version` directly (no shell) and returns the first
   // version-looking token, or null when the probe fails. This is the only
   // version source: nothing here invents or hardcodes one.
-  function probeExecutableVersion(cmd) {
+  function probeExecutable(cmd) {
     try {
-      const result = spawnSync(cmd, ['--version'], {
+      const script = /\.(?:[cm]?js)$/i.test(cmd);
+      const result = spawnSync(script ? process.execPath : cmd, script ? [cmd, '--version'] : ['--version'], {
         timeout: PROBE_TIMEOUT_MS,
         windowsHide: true,
         encoding: 'utf8',
       });
-      if (result.error || result.status !== 0) return null;
-      return parseVersionToken(String(result.stdout || result.stderr || ''));
+      if (result.error || result.status !== 0) return { available: false, version: null, code: result.error?.code || 'CLI_PROBE_FAILED', reason: String(result.error?.message || result.stderr || result.stdout || `exit ${result.status}`).slice(0, 2000), exitCode: result.status };
+      const version = parseVersionToken(String(result.stdout || result.stderr || ''));
+      return { available: Boolean(version), version, reason: version ? '' : 'Claude Code 未返回版本号。' };
     } catch {
-      return null;
+      return { available: false, version: null, code: 'CLI_PROBE_FAILED', reason: 'Claude Code 版本探测失败。' };
     }
   }
+function probeExecutableVersion(cmd) { return probeExecutable(cmd).version; }
 function createAgentDiscovery(options = {}) {
   const claudeProbe = options.claudeProbe || null; // () => {available, version}
   let cache = null;
@@ -73,7 +76,7 @@ function createAgentDiscovery(options = {}) {
         const probed = claudeProbe ? claudeProbe() : { available: false, version: null };
         available = Boolean(probed.available);
         version = probed.version || null;
-        if (!available) reason = 'Claude Code executable was not found';
+        if (!available) reason = probed.reason || 'Claude Code executable was not found';
       } else if (id === 'zcode') {
         const install = probeZCodeInstall();
         available = install.installed;
@@ -109,4 +112,4 @@ function createAgentDiscovery(options = {}) {
   return discover;
 }
 
-module.exports = { createAgentDiscovery, probeExecutableVersion };
+module.exports = { createAgentDiscovery, probeExecutableVersion, probeExecutable };

package/packages/server/lib/diagnostics.js

@@ -0,0 +1,32 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+function createDiagnostics({ dataDir, secrets = () => [] } = {}) {
+  const sanitize = value => {
+    let text = String(value || '');
+    let values = []; try { values = secrets() || []; } catch {}
+    for (const secret of values) if (typeof secret === 'string' && secret.length >= 4) text = text.split(secret).join('[REDACTED]');
+    return text.replace(/(https?:\/\/)[^\s/@]+:[^\s/@]+@/gi, '$1[REDACTED]@').replace(/\b(Bearer|Basic)\s+[^\s]+/gi, '$1 [REDACTED]').replace(/((?:api[_-]?key|token|password|secret)\s*[=:]\s*)[^\s,;]+/gi, '$1[REDACTED]').slice(0, 8000);
+  };
+  const logger = { close: async () => {} };
+  for (const level of ['debug', 'info', 'warn', 'error']) logger[level] = async (event, message, input = {}) => {
+    const record = { schema: 'log/v2', id: `log-${crypto.randomUUID()}`, ts: new Date().toISOString(), component: 'claude-ai-workbench', level, event, message: sanitize(message) };
+    for (const key of ['projectId', 'runId', 'operationId', 'commitSha', 'phase']) if (input[key]) record[key] = sanitize(input[key]);
+    if (input.error) record.error = { name: input.error.name || 'Error', code: input.error.code || 'CLAUDE_RUNTIME_FAILED', message: sanitize(input.error.message || input.error), stack: sanitize(input.error.stack) };
+    if (input.context) record.context = JSON.parse(JSON.stringify(input.context, (key, value) => /key|token|password|secret|prompt|body/i.test(key) ? '[REDACTED]' : typeof value === 'string' ? sanitize(value) : value));
+    if (process.connected && process.send) {
+      const delivered = await new Promise(resolve => {
+        try { process.send({ type: 'kb:diagnostic', record }, error => resolve(!error)); } catch { resolve(false); }
+      });
+      if (delivered) return;
+    }
+    try {
+      fs.mkdirSync(dataDir, { recursive: true });
+      fs.appendFileSync(path.join(dataDir, 'diagnostics.jsonl'), JSON.stringify(record) + '\n', { encoding: 'utf8', mode: 0o600 });
+    } catch { process.stderr.write(JSON.stringify(record) + '\n'); }
+  };
+  return logger;
+}
+module.exports = { createDiagnostics };

package/packages/server/lib/profile-store.js

@@ -61,6 +61,7 @@ class ProfileStore {
     const saved = this._profiles().embedding;
     if (!saved) return { configured: false, config: null };
     const { credentialRef, ...config } = saved;
+    config.endpoint = normalizeEmbedding(saved).endpoint;
     let configured = false;
     try { configured = Boolean(this.embeddingRuntime()); } catch {}
     return { configured, config };
@@ -95,7 +96,7 @@ class ProfileStore {
     if (!saved) throw Object.assign(new Error('向量模型未配置。'), { status: 409 });
     const secret = saved.profileId ? this.runtimeProfile(saved.profileId).apiKey : this._credentials().credentials[saved.credentialRef];
     if (!secret) throw Object.assign(new Error('向量模型凭据未配置。'), { status: 409 });
-    return { provider: saved.provider, model: saved.model, endpoint: saved.endpoint, apiKey: secret };
+    return { provider: saved.provider, model: saved.model, endpoint: normalizeEmbedding(saved).endpoint, apiKey: secret };
   }
 
   importEmbedding({ migrationId, settings }) {
@@ -245,10 +246,13 @@ function normalizeEmbedding(input) {
   if (!['minimax', 'openai'].includes(input.provider)) throw Object.assign(new Error('请选择支持的向量协议。'), { status: 400 });
   const model = String(input.model || (input.provider === 'minimax' ? 'embo-01' : 'text-embedding-3-small')).trim();
   if (!model || model.length > 200 || /[\x00-\x1f]/.test(model)) throw Object.assign(new Error('无效的向量模型。'), { status: 400 });
-  const endpoint = String(input.endpoint || '').trim();
+  let endpoint = String(input.endpoint || '').trim();
   if (endpoint) {
     let url; try { url = new URL(endpoint); } catch {}
     if (!url || !['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw Object.assign(new Error('向量接口地址无效。'), { status: 400 });
+    // MiniMax appends /v1/embeddings itself. Only official, known route
+    // aliases are normalized; private gateways may require their path prefix.
+    if (input.provider === 'minimax' && ['api.minimaxi.com', 'api.minimax.io', 'api.minimax.cn', 'api.minimax.chat'].includes(url.hostname) && /^\/(?:anthropic|v1(?:\/embeddings)?)?\/?$/.test(url.pathname)) endpoint = url.origin;
   }
   return { provider: input.provider, model, endpoint, profileId: input.profileId ? cleanId(input.profileId, 'profileId') : null };
 }

package/packages/server/lib/system-doctor.js

@@ -18,11 +18,12 @@ function createSystemDoctor(deps = {}) {
 
   function probe(command, args) {
     try {
-      const result = doSpawnSync(command, args, {
+      const script = /\.[cm]?js$/i.test(command);
+      const result = doSpawnSync(script ? process.execPath : command, script ? [command, ...args] : args, {
         timeout: 10000,
         windowsHide: true,
         encoding: 'utf8',
-        shell: platform === 'win32',
+        shell: !script && platform === 'win32' && !require('path').isAbsolute(command),
         env,
       });
       if (result.error) {
@@ -100,6 +101,7 @@ function createSystemDoctor(deps = {}) {
         'claude-code': {
           resolvedExecutable: claude.cmd || null,
           resolutionReason: claude.cmd ? null : (claude.reason || 'not found'),
+          rejectedPaths: claude.rejected || [],
           versionProbe: claudeProbe,
           loginState: claudeLoginState(),
         },

package/packages/server/lib/workbench-service.js

@@ -13,6 +13,7 @@ const ACTIVE_STATES = new Set(['created', 'spawning', 'running', 'thinking', 'to
 class WorkbenchService {
   constructor(options) {
     this.runner = options.runner;
+    this.diagnostics = options.diagnostics || null;
     this.knowledge = options.knowledge || null;
     this.pendingInputs = new Map();
     this.knowledgeBySession = new Map();
@@ -69,7 +70,7 @@ class WorkbenchService {
     let executable = null;
     try { executable = this.runner.findClaudeExecutableForSdk(); } catch {}
     const command = executable && (executable.cmd || executable);
-    return { runtime: 'claude-code', available: Boolean(executable), executable: command ? path.basename(String(command)) : null, transport: 'agent-sdk' };
+    return { runtime: 'claude-code', available: Boolean(command), executable: command ? path.basename(String(command)) : null, transport: 'agent-sdk' };
   }
 
   // Live availability probing when a discovery provider is wired in,
@@ -79,7 +80,7 @@ class WorkbenchService {
       return { agents: Object.values(this.agentDiscovery()) };
     }
     let claudeAvailable = false;
-    try { claudeAvailable = Boolean(this.runner.findClaudeExecutableForSdk()); } catch {}
+    try { const executable = this.runner.findClaudeExecutableForSdk(); claudeAvailable = Boolean(typeof executable === 'string' ? executable : executable?.cmd); } catch {}
     return {
       agents: Object.keys(AGENTS).map(id => {
         const agent = AGENTS[id];
@@ -351,7 +352,7 @@ class WorkbenchService {
     }));
     const runtimeAttachments = attachments.map((item, index) => ({ ...displayAttachments[index], data: item.data }));
     try { await this.runner.sendInput(id, value, profile, { ...(options || {}), knowledgeContext: knowledge?.prompt || '', attachments: runtimeAttachments, displayAttachments }); }
-    catch (error) { if (captureTurn) this._capture(captureTurn, 'session_end', undefined, 'failed'); throw error; }
+    catch (error) { this._runtimeFailure(id, error); if (captureTurn) this._capture(captureTurn, 'session_end', undefined, 'failed'); throw error; }
     this._armTimeout(id, profile.timeoutMs);
     this._watchTurn(id, previousEventCount, captureTurn);
     this._audit('input', { sessionId: id, contextId: state.projectSlug, characters: value.length, attachments: attachments.length, attachmentBytes: attachments.reduce((sum, item) => sum + item.size, 0) });
@@ -630,6 +631,7 @@ class WorkbenchService {
       seen += 1;
       if (seen <= previousEventCount) return;
       if (['claude/result', 'claude/error', 'claude/aborted'].includes(event && event.type)) {
+        if (event.type === 'claude/error' || event.type === 'claude/result' && event.isError) this._runtimeFailure(sessionId, new Error(String(event.message || event.error || event.result || 'Agent 运行失败。')));
         if (captureTurn && !completed) {
           completed = true;
           if (event.type === 'claude/result' && !event.isError && typeof event.result === 'string' && event.result) this._capture(captureTurn, 'assistant_response', event.result);
@@ -647,6 +649,10 @@ class WorkbenchService {
     if (unsubscribe) try { unsubscribe(); } catch {}
     this.turnMonitors.delete(sessionId);
   }
+  _runtimeFailure(sessionId, error) {
+    const state = this.runner.getState(sessionId);
+    this.diagnostics?.error('agent.runtime.failed', 'Agent 会话运行失败。', { projectId: /^project-[A-Za-z0-9._-]+$/.test(state?.projectSlug || '') ? state.projectSlug : undefined, runId: sessionId, phase: 'runtime', error, context: { agent: this.runner.agentOf?.(sessionId) || state?.agentId || 'claude-code', sessionId } });
+  }
   _audit(action, detail) {
     if (!this.auditFile) return;
     fs.mkdirSync(path.dirname(this.auditFile), { recursive: true });

package/packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-ai-workbench/server",
-  "version": "0.13.0",
+  "version": "0.13.2-rc.1",
   "type": "commonjs",
   "main": "index.js",
   "types": "index.d.ts",
@@ -25,7 +25,7 @@
   ],
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.141",
-    "@claude-ai-workbench/contracts": "0.13.0"
+    "@claude-ai-workbench/contracts": "0.13.2-rc.1"
   },
   "engines": {
     "node": ">=18"

package/packages/ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-ai-workbench/ui",
-  "version": "0.13.0",
+  "version": "0.13.2-rc.1",
   "type": "commonjs",
   "main": "ai-profile-settings.js",
   "browser": "ai-profile-settings.js",
@@ -33,7 +33,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@claude-ai-workbench/core": "0.13.0"
+    "@claude-ai-workbench/core": "0.13.2-rc.1"
   },
   "engines": {
     "node": ">=18"

package/src/backend/lib/claude-cli-runner.js

@@ -1050,6 +1050,7 @@ function getSessionTokenUsage(sessionId) {
 
 const isShellShim = (file) => /\.(cmd|bat|ps1)$/i.test(String(file || ''));
 const sdkSpawnable = (file) => file && !isShellShim(file);
+const existingFile = file => { try { return fs.statSync(file).isFile(); } catch { return false; } };
 
 // Newer claude-code releases keep moving their entry file (cli.js ->
 // bin/claude.exe), so hardcoded layout guesses rot. The installed package's
@@ -1063,7 +1064,7 @@ function readClaudePackageEntry(packageDir) {
       : (bin && typeof bin === 'object' && typeof bin.claude === 'string' ? bin.claude : null);
     if (!rel) return null;
     const entry = path.join(packageDir, ...String(rel).split(/[\\/]+/).filter(Boolean));
-    return fs.existsSync(entry) ? entry : null;
+    return existingFile(entry) ? entry : null;
   } catch {
     return null;
   }
@@ -1077,7 +1078,7 @@ function resolveClaudeShimTarget(shimPath) {
   const dir = path.dirname(shimPath);
   const packageDir = path.join(dir, 'node_modules', '@anthropic-ai', 'claude-code');
   const direct = path.join(packageDir, 'bin', 'claude.exe');
-  if (fs.existsSync(direct)) return direct;
+  if (existingFile(direct)) return direct;
   const declared = readClaudePackageEntry(packageDir);
   if (declared) return declared;
   let content;
@@ -1086,14 +1087,14 @@ function resolveClaudeShimTarget(shimPath) {
   } catch {
     return null;
   }
-  const embedded = /["']([^"'\r\n]+claude\.exe)["']/gi;
+  const embedded = /["']([^"'\r\n]+(?:claude\.exe|cli\.(?:js|cjs|mjs)))["']/gi;
   for (const match of content.matchAll(embedded)) {
     const raw = match[1]
       .replace(/^\$basedir[\\/]*/i, '')
       .replace(/^%~dp0%?[\\/]*/i, '')
       .replace(/^%dp0%[\\/]*/i, '');
     const candidate = path.isAbsolute(raw) ? raw : path.resolve(dir, raw);
-    if (fs.existsSync(candidate)) return candidate;
+    if (existingFile(candidate)) return candidate;
   }
   return null;
 }
@@ -1119,8 +1120,12 @@ function listClaudePathHits() {
 }
 
 function findClaudeExecutableForSdk() {
-  if (process.env.CLAUDE_CODE_EXECPATH && sdkSpawnable(process.env.CLAUDE_CODE_EXECPATH)) {
-    return { cmd: process.env.CLAUDE_CODE_EXECPATH, shell: false };
+  const rejected = [];
+  if (process.env.CLAUDE_CODE_EXECPATH) {
+    const override = process.env.CLAUDE_CODE_EXECPATH;
+    const target = isShellShim(override) ? resolveClaudeShimTarget(override) : override;
+    if (target && existingFile(target) && sdkSpawnable(target)) return { cmd: target, shell: false, source: 'environment' };
+    rejected.push({ path: override, reason: '配置的启动路径不存在、不是文件，或启动脚本没有有效目标。' });
   }
   if (process.platform === 'win32') {
     const candidates = [];
@@ -1131,44 +1136,39 @@ function findClaudeExecutableForSdk() {
         candidates.push(file);
       }
     };
-    // npm global install: known layout first, then the entry the installed
-    // package itself declares, then the pre-2.x literal.
     const npmRoot = process.env.APPDATA && path.join(process.env.APPDATA, 'npm');
     const npmPackageDir = npmRoot && path.join(npmRoot, 'node_modules', '@anthropic-ai', 'claude-code');
-    if (npmPackageDir) {
-      push(path.join(npmPackageDir, 'bin', 'claude.exe'));
-      push(readClaudePackageEntry(npmPackageDir));
-      push(path.join(npmPackageDir, 'cli.js'));
-    }
     // Official native installer layout (PowerShell/CMD installers).
     if (process.env.USERPROFILE) {
       push(path.join(process.env.USERPROFILE, '.local', 'bin', 'claude.exe'));
     }
     if (process.env.LOCALAPPDATA) {
-      push(
-        path.join(process.env.LOCALAPPDATA, 'Programs', 'claude-code', 'claude.exe'),
-        path.join(process.env.LOCALAPPDATA, 'claude-code', 'claude.exe'),
-      );
+      push(path.join(process.env.LOCALAPPDATA, 'Programs', 'claude-code', 'claude.exe'));
+      push(path.join(process.env.LOCALAPPDATA, 'claude-code', 'claude.exe'));
     }
     // Any claude.exe reachable from PATH (covers custom install prefixes);
     // .cmd/.bat shims stay excluded — the SDK spawns with shell:false.
     for (const dir of String(process.env.PATH || '').split(path.delimiter)) {
-      if (dir) push(path.join(dir, 'claude.exe'));
+      if (dir) {
+        push(path.join(dir, 'claude.exe'));
+        for (const name of ['claude.cmd', 'claude.bat', 'claude.ps1']) push(resolveClaudeShimTarget(path.join(dir, name)));
+      }
     }
+    if (npmPackageDir) { push(readClaudePackageEntry(npmPackageDir)); push(path.join(npmPackageDir, 'bin', 'claude.exe')); push(path.join(npmPackageDir, 'cli.js')); }
     for (const candidate of candidates) {
-      if (fs.existsSync(candidate) && sdkSpawnable(candidate)) return { cmd: candidate, shell: false };
+      if (existingFile(candidate) && sdkSpawnable(candidate)) return { cmd: candidate, shell: false, source: 'installed', rejected };
     }
     // Nothing guessed panned out: fall back to the shims a shell would
     // actually run, resolving each to the binary it wraps.
     const pathHits = listClaudePathHits();
     for (const hit of pathHits) {
-      if (/\.exe$/i.test(hit) && fs.existsSync(hit) && sdkSpawnable(hit)) return { cmd: hit, shell: false };
+      if (/\.exe$/i.test(hit) && existingFile(hit) && sdkSpawnable(hit)) return { cmd: hit, shell: false, source: 'path', rejected };
     }
     for (const hit of pathHits) {
       const target = resolveClaudeShimTarget(hit);
-      if (target && fs.existsSync(target) && sdkSpawnable(target)) return { cmd: target, shell: false };
+      if (target && existingFile(target) && sdkSpawnable(target)) return { cmd: target, shell: false, source: 'shim', rejected };
     }
-    return { cmd: null, shell: false, reason: 'no SDK-compatible Claude Code executable found' };
+    return { cmd: null, shell: false, rejected, reason: rejected.length ? 'Claude Code 启动路径已失效，且未发现可用安装。' : '未找到可供 SDK 启动的 Claude Code 文件。' };
   }
   return { cmd: 'claude', shell: false };
 }