dsh-agentone 0.5.28 → 0.5.29

package/lib/index.js

@@ -34,7 +34,7 @@ import { applyPlatformSkillhub, removePlatformSkillhub } from './skillhub.js';
 import { beginCliAuth, cliAuthQrcode, completeCliAuth, parseCliAuthBeginOutput } from './cliauth.mjs';
 import { platformFetch } from './http.js';
 import { donePageHtml, statusPageHtml } from './page.js';
-import { compareSemver, dshPluginCli, firstErrorLines, installCliTool, isUnexpectedStoreError, probeCliDetail, probePythonEnv, pnpmViewLatest, runCliTool, unexpectedStoreGuidance, upgradeCliTool } from './proc.js';
+import { compareSemver, dshPluginCli, firstErrorLines, hasChineseText, installCliTool, isTerminalCliAuthFailure, isUnexpectedStoreError, probeCliDetail, probePythonEnv, pnpmViewLatest, runCliTool, unexpectedStoreGuidance, upgradeCliTool } from './proc.js';
 
 import { clearCredentials, loadCredentials, resolveDshHome, saveCredentials, updateCredentials } from './store.js';
 
@@ -1302,9 +1302,17 @@ export function apply(ctx, config) {
           sendJson(response, 400, { error: '不支持的 CLI 工具' });
           return;
         }
-        const detail = await probeCliDetail(tool).then(withCliUpgradeGuard).catch(() => null);
+        // 只需要三态：跳过 latest 查询（registry 两轮 curl 最坏 ~40s）
+        const detail = await probeCliDetail(tool, { withLatest: false })
+          .then(withCliUpgradeGuard).catch(() => null);
         if (detail?.state === 'missing') {
-          sendJson(response, 400, { error: 'CLI 未安装，请先安装或联系管理员' });
+          sendJson(response, 400, {
+            error: detail.reason === 'broken_install'
+              ? 'CLI 安装不完整，请先点击「修复安装」后再授权'
+              : detail.reason === 'unavailable'
+                ? 'CLI 暂时无法访问（可能被安全软件占用或响应超时），请稍后重试；若持续失败请重新安装'
+                : 'CLI 未安装，请先安装或联系管理员',
+          });
           return;
         }
         const raw = await beginCliAuth(tool);
@@ -1322,7 +1330,10 @@ export function apply(ctx, config) {
           expires_in: parsed.expiresIn,
         });
       } catch (error) {
-        sendJson(response, 502, { error: error?.message || '发起授权失败，请稍后重试' });
+        const message = String(error?.message || '');
+        sendJson(response, 502, {
+          error: hasChineseText(message) ? message : '发起授权失败，请稍后重试',
+        });
       }
     });
 
@@ -1354,20 +1365,23 @@ export function apply(ctx, config) {
           await completeCliAuth(tool, deviceCode, { timeoutMs: 25_000 });
           log.info(`cli auth complete ok: tool=${tool} elapsed=${Date.now() - startedAt}ms`);
           pendingCliAuth.delete(tool);
-          const detail = await probeCliDetail(tool).then(withCliUpgradeGuard).catch(() => null);
+          const detail = await probeCliDetail(tool, { withLatest: false })
+            .then(withCliUpgradeGuard).catch(() => null);
           sendJson(response, 200, { ok: true, tool: detail });
         } catch (error) {
           // 超时=我们主动掐断轮询（用户还没在授权页同意）：保留会话，202
-          // 让前端继续等；只有终态（设备码失效/被拒）才删会话，否则用户
-          // 慢一点授权就会因会话被删而 400「重新发起」。
+          // 让前端继续等；终态（设备码失效/被拒、以及安装损坏/命令缺失
+          // 这类不会因重试自愈的本地故障）才删会话——否则每 3s 重发
+          // complete、每轮再起一个子进程，直到设备码过期。
           const message = String(error?.message || '');
-          const terminal = /expired|invalid|denied|拒绝|失效|过期/i.test(message);
+          const terminal = isTerminalCliAuthFailure(error);
           // 快速失败 ≠ 还在等：真实用户机实测，lark-cli 在部分宿主环境拒绝
           // 阻塞轮询（打印 [AI agent] 提示后退出），且设备码被同意消费后
           // 重放会快速报 JSON 错——这两种情况用户其实已完成授权，纯 202
           // 会让弹窗永远停在「正在等待」。用 auth status 实测兜底：已授权
           // 直接按成功返回，弹窗关闭、状态刷新。
-          const detail = await probeCliDetail(tool).then(withCliUpgradeGuard).catch(() => null);
+          const detail = await probeCliDetail(tool, { withLatest: false })
+            .then(withCliUpgradeGuard).catch(() => null);
           if (detail?.state === 'authorized') {
             pendingCliAuth.delete(tool);
             log.info(`cli auth complete ok (via status probe): tool=${tool}`);
@@ -1378,7 +1392,7 @@ export function apply(ctx, config) {
           log.warn(`cli auth complete ${terminal ? 'terminal' : 'timeout'}: tool=${tool} message=${message.slice(0, 160)}`);
           sendJson(response, terminal ? 502 : 202, {
             pending: !terminal,
-            error: message,
+            error: hasChineseText(message) ? message : '授权确认失败，请稍后重试',
           });
         }
       } catch (error) {

package/lib/page.js

@@ -484,6 +484,10 @@ const renderCli = async (s) => {
     body.innerHTML = '<div class="skill-sub">平台未开启 CLI 功能。</div>';
     return;
   }
+  // 请求代际：安装/授权成功会直接写缓存重绘，慢的旧 status 响应回来时
+  // 若已有更新的一轮在途（或已完成），丢弃——否则旧响应会把新状态覆盖回
+  // 未安装/未授权
+  const seq = (renderCli._seq = (renderCli._seq || 0) + 1);
   // 真实探测本机安装与授权态（数秒）。有旧数据（renderCli._tools）时先用
   // 缓存渲染再后台刷新——不清屏闪「检测中…」，内容回来后整块替换一次。
   if (renderCli._tools && Object.keys(renderCli._tools).length) {
@@ -497,11 +501,12 @@ const renderCli = async (s) => {
     const resp = await fetch('api/cli/status');
     const data = await resp.json().catch(() => ({}));
     if (!resp.ok) throw new Error(data.error || '检测失败');
+    if (seq !== renderCli._seq) return;
     tools = data.tools || {};
     python = data.python || null;
   } catch {
     // 探测失败：已有内容保持不动，首载才显示错误
-    if (!renderCli._tools || !Object.keys(renderCli._tools).length) {
+    if (seq === renderCli._seq && (!renderCli._tools || !Object.keys(renderCli._tools).length)) {
       body.innerHTML = '<div class="skill-sub" style="color:var(--err)">CLI 状态检测失败，请稍后重试。</div>';
     }
     return;
@@ -533,20 +538,24 @@ const renderCliData = (s, tools, python) => {
       ? '<span class="pill ok" style="font-size:11px">已授权</span>'
       : state === 'unauthorized'
         ? '<span class="pill warn" style="font-size:11px">未授权</span>'
-        : '<span class="pill warn" style="font-size:11px">未安装</span>';
+        : info.reason === 'broken_install'
+          ? '<span class="pill warn" style="font-size:11px">安装损坏</span>'
+          : '<span class="pill warn" style="font-size:11px">未安装</span>';
     const versionLine = meta.desc + ' · ' + meta.label
+      + (info.reason === 'broken_install' ? ' · 检测到文件不完整，请修复安装' : '')
       + (info.version ? ' · v' + esc(info.version) : '')
       + (info.latest && info.latest !== info.version
         ? ' → <b>v' + esc(info.latest) + '</b>'
         : '');
     const upgradable = info.latest && info.latest !== info.version;
-    // 已装未授权 → 「去授权」：发起官方 Device Flow（扫码/链接 + 轮询确认）
+    // 已装未授权 → 「去授权」；残缺安装 → 「修复安装」
     const actions = [
       state === 'unauthorized'
         ? '<button class="btn small primary" data-cli-auth="' + esc(name) + '">去授权</button>'
         : '',
       state === 'missing'
-        ? '<button class="btn small primary" data-cli-install="' + esc(name) + '">安装</button>'
+        ? '<button class="btn small primary" data-cli-install="' + esc(name) + '">'
+          + (info.reason === 'broken_install' ? '修复安装' : '安装') + '</button>'
         : '',
       upgradable
         ? '<button class="btn small ghost" data-cli-upgrade="' + esc(name) + '">升级</button>'
@@ -706,6 +715,7 @@ const cliAuthDialog = async (tool) => {
  * ccpg/python 走官方安装器，耗时可达数分钟。响应自带安装后立即探测的
  * 详情，直接合进缓存刷新界面。 */
 const cliInstall = async (tool, btn) => {
+  const originalText = btn.textContent;
   btn.disabled = true;
   btn.textContent = '安装中，可能需要 3–5 分钟…';
   try {
@@ -730,7 +740,7 @@ const cliInstall = async (tool, btn) => {
   } catch (error) {
     alert(error.message || 'CLI 安装失败，请稍后重试');
     btn.disabled = false;
-    btn.textContent = '安装';
+    btn.textContent = originalText;
   }
 };
 

package/lib/proc.js

@@ -12,6 +12,7 @@ import { join, dirname, isAbsolute, delimiter as pathDelimiter } from 'node:path
 import { promisify } from 'node:util';
 
 const execFileAsync = promisify(execFile);
+const preferredCommandCache = new Map();
 
 /** 常见安装目录兑底（环境 PATH 之外的补充）：GUI 启动的 DSH Desktop 继承
  * launchd 的 PATH（/usr/bin:/bin/…），不含 nvm/homebrew/.local —— 实测
@@ -187,6 +188,7 @@ export function childPathWithExtras(originalPath, extras, shimDirs) {
 export function resetExtraBinDirsCache() {
   extraBinDirsCache = null;
   desktopShimDirsCache = null;
+  preferredCommandCache.clear();
 }
 
 /** 候选扩展名顺序（纯函数，供测试）：win32 下 CreateProcess 只认可执行
@@ -265,6 +267,9 @@ export function resolveCommandCandidates(tool) {
 
 /** 兼容旧签名：找不到时返回原名（后续 ENOENT 走既有 missing/降级语义）。 */
 export function resolveCommand(tool) {
+  const preferred = preferredCommandCache.get(tool);
+  if (preferred && existsSync(preferred)) return preferred;
+  if (preferred) preferredCommandCache.delete(tool);
   return resolveCommandOrNull(tool) || tool;
 }
 
@@ -291,8 +296,7 @@ export function decodeOutput(buf) {
  * cmd.exe /d /s /c 路由，cmd.exe 在第三个兑底目录（System32）。只前置
  * 解析到的那个目录会让 shim 内部找不到依赖，必须整组前置。输出按
  * encoding:buffer 收回后 decodeOutput（GBK 容错）。opts.env 只传增量变量。 */
-function execResolved(tool, args, { timeoutMs, cwd, env } = {}) {
-  const resolved = resolveCommand(tool);
+function execResolvedPath(resolved, args, { timeoutMs, cwd, env } = {}) {
   const childEnv = { ...process.env, ...desktopShimEnvDefaults(), ...(env || {}) };
   const key = pathEnvKey(childEnv, process.platform);
   const extras = extraBinDirs().filter((dir) => existsSync(dir));
@@ -319,6 +323,35 @@ function execResolved(tool, args, { timeoutMs, cwd, env } = {}) {
   );
 }
 
+function execResolved(tool, args, options = {}) {
+  return execResolvedPath(resolveCommand(tool), args, options);
+}
+
+export function isBrokenCliOutput(message) {
+  return /MODULE_NOT_FOUND|ERR_MODULE_NOT_FOUND|Cannot find (?:module|package)/i.test(String(message || ''));
+}
+
+/** 中文错误契约的兜底判定：消息含中文才直接透传给用户，否则包一层
+ * 中文说明（技术详情进日志）。 */
+export function hasChineseText(text) {
+  return /[\u4e00-\u9fff]/.test(String(text || ''));
+}
+
+export function isWindowsFileAccessError(message, platform = process.platform) {
+  if (platform !== 'win32') return false;
+  const raw = String(message || '');
+  // EBUSY：Windows「文件正被另一进程使用」（npm 安装被占用的另一种形态）
+  return /(?:EPERM|EACCES|EBUSY|errno\s*:?\s*-4048|operation not permitted)/i.test(raw)
+    && /(?:npm|@larksuite[\\/]cli|node_modules|cleanup)/i.test(raw);
+}
+
+function cliFailure(kind, message, raw = '') {
+  const error = new Error(message);
+  error.kind = kind;
+  error.raw = raw;
+  return error;
+}
+
 /** 从 pnpm 冗长输出里提取对用户有意义的错误行。 */
 export function firstErrorLines(raw) {
   const lines = String(raw).split('\n').map((line) => line.trim()).filter(Boolean);
@@ -350,6 +383,11 @@ export function unexpectedStoreGuidance() {
  * async 函数；execFile 不经过 shell，参数数组中的每个元素都是独立参数，
  * 不存在拼接解释执行。
  */
+function isLarkCliTool(tool) {
+  const name = String(tool || '').replace(/\\/g, '/').split('/').pop().toLowerCase();
+  return ['lark-cli', 'lark-cli.cmd', 'lark-cli.exe'].includes(name);
+}
+
 export async function runCliTool(tool, args, { timeoutMs = 300000, cwd, env } = {}) {
   try {
     const { stdout, stderr } = await execResolved(tool, args, {
@@ -360,17 +398,39 @@ export async function runCliTool(tool, args, { timeoutMs = 300000, cwd, env } =
     return { stdout, stderr };
   } catch (error) {
     if (error.code === 'ENOENT') {
-      throw new Error(missingCommandGuidance(tool));
+      throw cliFailure('missing_command', missingCommandGuidance(tool));
     }
     if (error.killed) {
-      throw new Error('命令执行超时，请稍后重试');
+      throw cliFailure('timeout', '命令执行超时，请稍后重试');
     }
     const raw = `${error.stderr || ''}\n${error.stdout || ''}`;
     if (isUnexpectedStoreError(raw)) {
-      throw new Error(unexpectedStoreGuidance());
+      throw cliFailure('pnpm_store_conflict', unexpectedStoreGuidance(), raw);
+    }
+    const isLarkNpmInstall = String(tool).toLowerCase().includes('npm')
+      && args.includes('@larksuite/cli@latest');
+    // spawn 级失败（杀软拦截执行等）没有 stdout/stderr：错误码与 message
+    // 里带命令路径，单独送检
+    const spawnText = `${error.code || ''}\n${error.message || ''}`;
+    if (isLarkNpmInstall && (isWindowsFileAccessError(raw) || isWindowsFileAccessError(spawnText))) {
+      throw cliFailure(
+        'windows_file_access',
+        'Windows 无法更新 lark-cli 文件，可能有程序或安全软件正在占用安装目录。请关闭正在运行的 lark-cli 或相关终端后重试；仍失败时请重启 Windows 后再次安装。',
+        raw,
+      );
+    }
+    if (isLarkCliTool(tool) && isBrokenCliOutput(raw)) {
+      throw cliFailure('broken_install', 'lark-cli 安装不完整，请先点击「修复安装」后再授权。', raw);
     }
     const message = firstErrorLines(raw);
-    throw new Error(message || `命令执行失败（退出码 ${error.code ?? '未知'}）`);
+    // 英文技术行不直接弹给用户：中文前缀 + 技术详情尾随（与 ccpg 下载
+    // 失败的处理同口径），完整原文保留在 error.raw 供日志诊断
+    const userMessage = hasChineseText(message)
+      ? message
+      : message
+        ? `命令执行失败。技术详情：${message}`
+        : `命令执行失败（退出码 ${error.code ?? '未知'}）`;
+    throw cliFailure('command_failed', userMessage, raw);
   }
 }
 
@@ -492,37 +552,134 @@ export function parseCliVersion(stdout) {
   return match ? match[1] : null;
 }
 
+export async function selectWorkingCliCandidate(candidates, probe) {
+  let sawBrokenInstall = false;
+  for (const candidate of candidates) {
+    try {
+      const result = await probe(candidate);
+      const output = `${result?.stdout || ''}\n${result?.stderr || ''}`;
+      // 损坏判定必须先于版本解析：cmd 包装未传播退出码时 Node 的
+      // MODULE_NOT_FOUND 堆栈会走 resolve 路径，尾行「Node.js v24.18.0」
+      // 能被 parseCliVersion 解析出版本号——先收版本会把损坏 shim 当成
+      // 可用候选缓存起来，恰好废掉「跳过损坏 shim」的核心目标
+      if (isBrokenCliOutput(output)) {
+        sawBrokenInstall = true;
+        continue;
+      }
+      const version = parseCliVersion(output);
+      if (version) return { command: candidate, version, reason: null };
+    } catch (error) {
+      const raw = `${error?.stderr || ''}\n${error?.stdout || ''}\n${error?.message || ''}`;
+      if (isBrokenCliOutput(raw)) sawBrokenInstall = true;
+    }
+  }
+  return {
+    command: null,
+    version: null,
+    reason: sawBrokenInstall ? 'broken_install' : 'unavailable',
+  };
+}
+
+export function shouldFallbackToPnpm(error, { platform = process.platform, pnpmAvailable = false } = {}) {
+  return platform === 'win32'
+    && pnpmAvailable
+    && ['windows_file_access', 'broken_install'].includes(error?.kind);
+}
+
+/** complete 轮询的终态判定：设备码过期/被拒之外，本地确定性故障（安装
+ * 损坏、命令缺失）不会因重试自愈——按终态返回，避免前端每 3s 重发、
+ * 每轮再起一个子进程直到设备码过期。timeout 是我们主动掐断的等待，
+ * 非终态。 */
+export function isTerminalCliAuthFailure(error) {
+  if (['broken_install', 'missing_command'].includes(error?.kind)) return true;
+  return /expired|invalid|denied|拒绝|失效|过期/i.test(String(error?.message || ''));
+}
+
+/** 从 pnpm -g 前置校验报错里解析全局 bin 目录。pnpm 12 起输出会把
+ * "is not in PATH" 折行并加竖线装饰（单行正则取不到），且 runCliTool
+ * 的摘要只保留 ERR_ 行（路径被丢弃）——必须对 error.raw 完整输出跑。 */
+export function extractPnpmGlobalBinDir(text) {
+  return /global bin directory\s+"(.+?)"\s+is not(?:\s*\n[^\n]*)?\s+in PATH/i
+    .exec(String(text || ''))?.[1] || null;
+}
+
+async function resolveWorkingCliCommand(tool, timeoutMs = 10_000) {
+  const preferred = preferredCommandCache.get(tool);
+  const candidates = [preferred, ...resolveCommandCandidates(tool)]
+    .filter(Boolean)
+    .filter((candidate, index, all) => all.indexOf(candidate) === index);
+  const selected = await selectWorkingCliCandidate(candidates, (candidate) => execResolvedPath(
+    candidate,
+    ['--version'],
+    { timeoutMs },
+  ));
+  if (selected.command) {
+    preferredCommandCache.set(tool, selected.command);
+  } else {
+    preferredCommandCache.delete(tool);
+  }
+  return selected;
+}
+
 /**
- * 三态探测 + 版本 + 最新版（任一失败降级为 null，不阻塞三态）：
- *   version: `tool --version`
- *   latest:  ccpg-cli 走官方 `update --check --json`（结构化，为 agent
- *            设计）；lark-cli 无 check 子命令，用 `npm view @larksuite/cli
- *            version`（版本号全局一致，对 npm/pnpm/手动安装都成立）。
- * npm view 需要 npm 在 PATH（node 环境下成立）；查询超时/失败返回 null，
- * 前端只显示当前版本不显示升级按钮。
+ * 三态探测 + 版本 + 最新版（任一失败降级为 null）：先验证所有同名 CLI
+ * 候选的 --version，跳过 Windows 上 npm 回滚留下的损坏 shim，再读取授权状态。
+ * withLatest=false 跳过 latest 查询（两轮 registry curl 最坏 ~40s）——
+ * 授权 begin/complete 只需要三态，别让用户在弹窗里等版本号查询。
  */
-export async function probeCliDetail(tool, { timeoutMs = 15000 } = {}) {
-  let stdout;
-  let state = 'unauthorized';
+export async function probeCliDetail(tool, { timeoutMs = 15000, withLatest = true } = {}) {
+  const selected = await resolveWorkingCliCommand(tool, Math.min(timeoutMs, 10_000));
+  if (!selected.command) {
+    return {
+      state: 'missing',
+      reason: selected.reason,
+      version: null,
+      latest: null,
+    };
+  }
+
+  let stdout = '';
   try {
-    ({ stdout } = await execResolved(tool, ['auth', 'status'], {
+    ({ stdout } = await execResolvedPath(selected.command, ['auth', 'status'], {
       timeoutMs,
       env: tool === 'ccpg-cli' ? { CCPG_FULL_CLI: '1' } : undefined,
     }));
   } catch (error) {
-    if (error.code === 'ENOENT') return { state: 'missing', version: null, latest: null };
-    // 探测失败不区分超时/非零退出：统一按已装但状态未知处理
-    stdout = `${error.stdout || ''}`;
+    const raw = `${error.stdout || ''}\n${error.stderr || ''}`;
+    if (isBrokenCliOutput(raw)) {
+      return {
+        state: 'missing',
+        reason: 'broken_install',
+        version: selected.version,
+        latest: null,
+      };
+    }
+    stdout = raw;
   }
-  if (larkStyleAuthorized(stdout) || ccpgStyleAuthorized(stdout)) state = 'authorized';
+  const state = larkStyleAuthorized(stdout) || ccpgStyleAuthorized(stdout)
+    ? 'authorized'
+    : 'unauthorized';
+  const latest = withLatest
+    ? await cliLatestVersion(tool, timeoutMs).catch(() => null)
+    : null;
+  return { state, version: selected.version, latest };
+}
 
-  const [version, latest] = await Promise.all([
-    execResolved(tool, ['--version'], { timeoutMs: 10_000 })
-      .then((r) => parseCliVersion(r.stdout))
-      .catch(() => null),
-    cliLatestVersion(tool, timeoutMs).catch(() => null),
-  ]);
-  return { state, version, latest };
+/** npm registry 的包 latest 版本（curl 直查 JSON，与机器上有无 node/
+ * npm/pnpm 完全解耦——工具链兜底链不可靠：npm 全局装的 pnpm.cmd 内部
+ * 仍要调 npm，barren 环境实测 pnpm view 报「'npm' 不是内部或外部命令」）。
+ * npmmirror 优先（国内），npmjs 兜底。 */
+async function registryLatestVersion(name, timeoutMs = 25_000) {
+  for (const url of [`https://registry.npmmirror.com/${name}/latest`, `https://registry.npmjs.org/${name}/latest`]) {
+    try {
+      const { stdout } = await runCliTool('curl', ['-fsSL', '--max-time', '15', url], { timeoutMs });
+      const version = JSON.parse(String(stdout))?.version;
+      if (typeof version === 'string' && version) return version;
+    } catch {
+      // 换下一个源
+    }
+  }
+  return null;
 }
 
 /** 最新版查询：ccpg-cli 官方 check 接口；lark-cli 查 npm 包 dist-tag。 */
@@ -536,15 +693,15 @@ async function cliLatestVersion(tool, timeoutMs) {
     return typeof data?.latest_version === 'string' ? data.latest_version : null;
   }
   if (tool === 'lark-cli') {
-    // npm 机器查 npm view；无 npm 的机器（仅独立 pnpm / DSH Desktop 自带
-    // shim）退化 pnpm view——否则升级检测在整类机器上都悄悄失效，升级
-    // 按钮永远不出现（与安装走 pnpm 分支是同一环境类）
+    // curl 直查 registry（系统自带，零工具链依赖）；失败再退 npm view。
+    // 升级检测不该依赖机器上恰好有哪套 node 工具链
+    const registry = await registryLatestVersion('@larksuite/cli', timeoutMs).catch(() => null);
+    if (registry) return registry;
     try {
       const { stdout } = await runCliTool('npm', ['view', '@larksuite/cli', 'version'], { timeoutMs });
       return parseCliVersion(stdout);
     } catch {
-      const version = await pnpmViewLatest('@larksuite/cli').catch(() => null);
-      return version || null;
+      return null;
     }
   }
   return null;
@@ -609,6 +766,66 @@ async function installLarkSkills({ timeoutMs = 180_000 } = {}) {
   return 'lark-cli 已安装。默认技能包暂跳过（本机暂无 npm/npx，不影响 CLI 功能；如需技能可安装 Node.js 后重新点「安装」）';
 }
 
+function rememberGlobalBinDir(dir) {
+  const value = String(dir || '').trim();
+  if (!value) return;
+  const existing = extraBinDirs();
+  extraBinDirsCache = [value, ...existing.filter((item) => item.toLowerCase() !== value.toLowerCase())];
+}
+
+async function installLarkCliWithPnpm(timeoutMs) {
+  const pnpmHome = process.env.PNPM_HOME
+    || join(process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local'), 'pnpm');
+  const pnpmEnv = { PNPM_HOME: pnpmHome };
+  const pnpmInstall = () => runCliTool(
+    'pnpm',
+    ['add', '-g', '@larksuite/cli@latest'],
+    { timeoutMs, env: pnpmEnv },
+  );
+  let stdout;
+  try {
+    ({ stdout } = await pnpmInstall());
+  } catch (error) {
+    // pnpm -g 前置校验要求全局 bin 目录在 PATH 中；自定义安装位不在
+    // GUI PATH 时，从错误中取出目录并重试一次。路径只在完整输出（raw）
+    // 里且被折行——见 extractPnpmGlobalBinDir。
+    const dir = extractPnpmGlobalBinDir(`${error?.raw || ''}\n${error?.message || ''}`);
+    if (!dir) throw error;
+    rememberGlobalBinDir(dir);
+    ({ stdout } = await pnpmInstall());
+  }
+  try {
+    const { stdout: binOut } = await runCliTool('pnpm', ['bin', '-g'], {
+      timeoutMs: 20_000,
+      env: pnpmEnv,
+    });
+    const dir = String(binOut || '').split('\n').map((line) => line.trim()).filter(Boolean).pop();
+    if (dir) {
+      rememberGlobalBinDir(dir);
+      const candidate = candidateSuffixes(process.platform)
+        .map((suffix) => join(dir, `lark-cli${suffix}`))
+        .find((item) => existsSync(item));
+      if (candidate) preferredCommandCache.set('lark-cli', candidate);
+    }
+  } catch {
+    // 静态兑底目录仍可供后续候选探测使用。
+  }
+  return stdout;
+}
+
+async function verifyLarkCliInstall(timeoutMs) {
+  const selected = await resolveWorkingCliCommand('lark-cli', Math.min(timeoutMs, 30_000));
+  if (!selected.command) {
+    if (selected.reason === 'broken_install') {
+      throw cliFailure('broken_install', 'lark-cli 安装不完整，请点击「修复安装」重试。');
+    }
+    // 不点名按钮：unavailable 时页面按钮文案随上次状态是「安装」或
+    // 「修复安装」，点名反而对不上
+    throw cliFailure('install_verify_failed', 'lark-cli 安装未完成，请稍后重试；若持续失败请重启 DSH Desktop 后再试。');
+  }
+  return selected;
+}
+
 /**
  * 触发 CLI 官方安装（工具缺失时用户自助安装）：
  *   lark-cli  npm 全局装最新版（包名 @larksuite/cli，npm/pnpm 环境均可；
@@ -621,47 +838,37 @@ async function installLarkSkills({ timeoutMs = 180_000 } = {}) {
 export async function installCliTool(tool, { timeoutMs = 600_000 } = {}) {
   let stdout;
   if (tool === 'lark-cli') {
-    // 预检+降级链：优先独立 npm；没有 npm 但有 pnpm（含 DSH Desktop 自带
-    // shim）时用 pnpm 全局装；两者都没有时 Windows 先一键补装 Node.js
-    // （用户目录免管理员，npmmirror 镜像），再用其自带 npm 装 lark-cli。
-    // lark-cli 官方支持 pnpm 安装方式，装出来的二进制与 npm 路径一致，
-    // 后续 lark-cli update 也能自升级。
+    // 优先 npm；Windows 上 npm 文件被占用或安装后仍是残缺 shim 时，
+    // 仅在 pnpm 可用的情况下切换到 pnpm，避免用另一套安装器掩盖网络错误。
     if (resolveCommandOrNull('npm')) {
-      ({ stdout } = await runCliTool('npm', ['install', '-g', '@larksuite/cli@latest'], { timeoutMs }));
-    } else if (resolveCommandOrNull('pnpm')) {
-      const pnpmInstall = () => runCliTool('pnpm', ['add', '-g', '@larksuite/cli@latest'], { timeoutMs });
+      let npmError = null;
       try {
-        ({ stdout } = await pnpmInstall());
+        ({ stdout } = await runCliTool('npm', ['install', '-g', '@larksuite/cli@latest'], { timeoutMs }));
+        await verifyLarkCliInstall(timeoutMs);
       } catch (error) {
-        // pnpm -g 前置校验：自己配置的全局 bin 目录必须在 PATH 里（真实
-        // 用户机报 The configured global bin directory "C:\Users\<u>\
-        // AppData\Local\pnpm\bin" is not in PATH）。自定义安装位不在兑底
-        // 目录里时，从报错原文解析出该目录补进 PATH 重试一次
-        const dir = /global bin directory "(.+?)" is not in PATH/i.exec(String(error?.message || ''))?.[1];
-        if (!dir) throw error;
-        extraBinDirsCache = [...extraBinDirs(), dir];
-        ({ stdout } = await pnpmInstall());
+        npmError = error;
       }
-      // pnpm 全局 bin 的真实落点随版本/配置漂移（v10 是 %LOCALAPPDATA%\
-      // pnpm\bin，PNPM_HOME 自定义更随意，v11 又不同）——装完问 pnpm 本尊
-      // 要实际目录并常驻兑底缓存：否则状态页探测不到刚装的 lark-cli，
-      // 明明装成功却显示「未安装」（真实用户机 0.5.27 实测）
-      try {
-        const { stdout: binOut } = await runCliTool('pnpm', ['bin', '-g'], { timeoutMs: 20_000 });
-        const dir = String(binOut || '').split('\n').map((l) => l.trim()).filter(Boolean).pop();
-        if (dir && !extraBinDirs().includes(dir)) {
-          extraBinDirsCache = [...extraBinDirs(), dir];
-        }
-      } catch {
-        // 问不到不阻断：静态兑底目录仍兜底
+      const canFallback = shouldFallbackToPnpm(npmError, {
+        pnpmAvailable: Boolean(resolveCommandOrNull('pnpm')),
+      });
+      if (npmError && !canFallback) throw npmError;
+      if (canFallback) {
+        const pnpmOutput = await installLarkCliWithPnpm(timeoutMs);
+        stdout = `${stdout || ''}\n${pnpmOutput || ''}`;
+        await verifyLarkCliInstall(timeoutMs);
       }
+    } else if (resolveCommandOrNull('pnpm')) {
+      stdout = await installLarkCliWithPnpm(timeoutMs);
+      await verifyLarkCliInstall(timeoutMs);
     } else if (process.platform === 'win32') {
       const nodeNote = await installNodeWindows(timeoutMs);
       ({ stdout } = await runCliTool('npm', ['install', '-g', '@larksuite/cli@latest'], { timeoutMs }));
       stdout = `${nodeNote}\n${stdout}`;
+      await verifyLarkCliInstall(timeoutMs);
     } else {
       throw new Error(missingCommandGuidance('npm'));
     }
+
     const skillsNote = await installLarkSkills().catch((error) => {
       // 软失败：技能装不上不影响 CLI 本体已装成功（如 GitHub 不可达）
       return `lark-cli skills install soft-failed: ${error?.message || error}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-agentone",
-  "version": "0.5.28",
+  "version": "0.5.29",
   "description": "AgentOne 平台集成插件：飞书登录、平台模型（同步失败自愈重试）、SkillHub 技能（升级检测一键升级、装后即时刷新、套餐技能自动同步）、套餐申请、插件管理与自助升级、lark-cli / ccpg-cli 探测与一键安装（请求超时与错误码透传、令牌轮换 single-flight、凭据损坏容错与并发安全写入、状态页 UX 增强）",
   "type": "module",
   "scripts": {