dsh-agentone 0.5.21 → 0.5.23

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, probeCliDetail, pnpmViewLatest, upgradeCliTool } from './proc.js';
+import { compareSemver, dshPluginCli, firstErrorLines, installCliTool, isUnexpectedStoreError, probeCliDetail, probePythonEnv, pnpmViewLatest, runCliTool, unexpectedStoreGuidance, upgradeCliTool } from './proc.js';
 
 import { clearCredentials, loadCredentials, resolveDshHome, saveCredentials, updateCredentials } from './store.js';
 
@@ -300,6 +300,11 @@ export function desktopRunPlugin(service, invokingDir) {
             await sleep(2000 * attempt);
             continue;
           }
+          // pnpm store 主版本冲突（Windows 桌面版高发：用户全局 pnpm 与
+          // 受管 pnpm 版本不同）：给可操作指引，不裸抛英文堆栈
+          if (isUnexpectedStoreError(`${stderr}\n${stdout}`)) {
+            throw new Error(unexpectedStoreGuidance());
+          }
           // ERR_PNPM_IGNORED_BUILDS 等非零退出在这里抛出，由调用侧
           // install/upgrade 的「以落盘版本为准」兜底接管
           throw new Error(message || `命令执行失败（退出码 ${outcome.exitCode ?? '未知'}）`);
@@ -365,6 +370,21 @@ function specLabel(spec) {
 
 /** dsh 插件与 CLI 操作白名单：用户输入不得进入 execFile 的 tool 位。 */
 const CLI_TOOLS = new Set(['lark-cli', 'ccpg-cli']);
+/** 除 CLI 外可通过 /agentone/api/cli/install 自助安装的工具（python 无
+ * 授权/升级概念，仅安装）。 */
+const CLI_INSTALL_TOOLS = new Set(['python']);
+
+/** CLI 详情防降级：latest 不高于已装版本时置 null，前端不出「升级」
+ * 按钮（ccpg 媒体通道可能比 update 通道发得更新，实测装到 1.2.16 时
+ * update --check 的 latest 还是 1.2.15；与插件列表 1123/1200 行同口径）。 */
+function withCliUpgradeGuard(detail) {
+  if (!detail || typeof detail !== 'object') return detail;
+  const { version, latest } = detail;
+  return {
+    ...detail,
+    latest: latest && version && compareSemver(latest, version) > 0 ? latest : null,
+  };
+}
 
 /**
  * 插件自身是否由平台托管镜像管理：镜像 Dockerfile 固有 ENV
@@ -807,8 +827,22 @@ export function apply(ctx, config) {
           // 失败自愈：模型同步残留错误时由轮询驱动后台重试（成功即清，
           // 下次轮询状态页恢复）；错误已被登录/手动同步清除时取消待定
           // 重试并复位退避计数。
-          if (credentials.model_error) scheduleModelRetry(config, log);
-          else {
+          if (credentials.model_error) {
+            // 套餐已生效（active）却残留 model_error：多半是审批前同步失败
+            // 的旧错误（plan_required），此时重试必然成功——立即同步一次，
+            // 不走首轮 60s 的指数退避。常量幂等：同步成功清掉错误后不再进。
+            const planActive = capabilities?.plan_state === 'active';
+            if (planActive) {
+              syncPlatformModel(config, log)
+                .then(() => {
+                  clearModelRetry();
+                  modelRetryAttempts = 0;
+                })
+                .catch(() => scheduleModelRetry(config, log));
+            } else {
+              scheduleModelRetry(config, log);
+            }
+          } else {
             clearModelRetry();
             modelRetryAttempts = 0;
           }
@@ -1191,12 +1225,15 @@ export function apply(ctx, config) {
       }
       // 真实探测本机 CLI：三态与平台 cli-deployd 判定口径一致，附带版本
       // 与最新版（查询失败降级 null，不阻塞三态）。并发探测，单个失败不影
-      // 响另一个。
-      const [lark, ccpg] = await Promise.all([
-        probeCliDetail('lark-cli').catch(() => ({ state: 'missing', version: null, latest: null })),
-        probeCliDetail('ccpg-cli').catch(() => ({ state: 'missing', version: null, latest: null })),
+      // 响另一个。附带 Python 环境探测（技能脚本标准依赖，Windows GUI 启动
+      // 时 PATH 常缺 python 或前段是 Store 假别名，probePythonEnv 逐个候选
+      // 穿透重试），缺失时前端给安装按钮/指引。
+      const [lark, ccpg, python] = await Promise.all([
+        probeCliDetail('lark-cli').then(withCliUpgradeGuard).catch(() => ({ state: 'missing', version: null, latest: null })),
+        probeCliDetail('ccpg-cli').then(withCliUpgradeGuard).catch(() => ({ state: 'missing', version: null, latest: null })),
+        probePythonEnv().catch(() => ({ available: false, command: null, version: null })),
       ]);
-      sendJson(response, 200, { tools: { 'lark-cli': lark, 'ccpg-cli': ccpg } });
+      sendJson(response, 200, { tools: { 'lark-cli': lark, 'ccpg-cli': ccpg }, python });
     });
 
     register('/agentone/api/cli/install', async (request, response) => {
@@ -1208,15 +1245,18 @@ export function apply(ctx, config) {
       try {
         const body = await readJsonBody(request);
         const tool = String(body.tool || '');
-        if (!CLI_TOOLS.has(tool)) {
+        if (!CLI_TOOLS.has(tool) && !CLI_INSTALL_TOOLS.has(tool)) {
           sendJson(response, 400, { error: '不支持的 CLI 工具' });
           return;
         }
-        // 自助安装（lark 走 npm、ccpg 走官方 auto-install.sh），与升级一样
-        // 分钟级耗时：输出尾部透传给前端展示失败原因
+        // 自助安装（lark 走 npm、ccpg 走官方安装器、python 走 python.org
+        // 官方安装器静默装），与升级一样分钟级耗时：输出尾部透传给前端展示
         const output = await installCliTool(tool);
-        const detail = await probeCliDetail(tool).catch(() => null);
-        sendJson(response, 200, { ok: true, output, tool: detail });
+        // python 无三态概念，回传探测详情供前端就地刷新
+        const detail = tool === 'python'
+          ? await probePythonEnv().catch(() => null)
+          : await probeCliDetail(tool).then(withCliUpgradeGuard).catch(() => null);
+        sendJson(response, 200, { ok: true, output, tool: detail, python: tool === 'python' ? detail : undefined });
       } catch (error) {
         sendJson(response, 502, { error: error?.message || 'CLI 安装失败，请稍后重试' });
       }
@@ -1238,7 +1278,7 @@ export function apply(ctx, config) {
         // 官方自升级（ccpg 下载二进制可达分钟级），输出尾部透传给前端
         // （lark-cli 手动安装时含 GitHub 下载地址）
         const output = await upgradeCliTool(tool);
-        const detail = await probeCliDetail(tool).catch(() => null);
+        const detail = await probeCliDetail(tool).then(withCliUpgradeGuard).catch(() => null);
         sendJson(response, 200, { ok: true, output, tool: detail });
       } catch (error) {
         sendJson(response, 502, { error: error?.message || 'CLI 升级失败，请稍后重试' });
@@ -1262,7 +1302,7 @@ export function apply(ctx, config) {
           sendJson(response, 400, { error: '不支持的 CLI 工具' });
           return;
         }
-        const detail = await probeCliDetail(tool).catch(() => null);
+        const detail = await probeCliDetail(tool).then(withCliUpgradeGuard).catch(() => null);
         if (detail?.state === 'missing') {
           sendJson(response, 400, { error: 'CLI 未安装，请先安装或联系管理员' });
           return;
@@ -1312,7 +1352,7 @@ export function apply(ctx, config) {
           // lark-cli 同时轮同一码。这里 25s 一掐，前端串行重试（见 page.js）。
           await completeCliAuth(tool, deviceCode, { timeoutMs: 25_000 });
           pendingCliAuth.delete(tool);
-          const detail = await probeCliDetail(tool).catch(() => null);
+          const detail = await probeCliDetail(tool).then(withCliUpgradeGuard).catch(() => null);
           sendJson(response, 200, { ok: true, tool: detail });
         } catch (error) {
           // 超时=我们主动掐断轮询（用户还没在授权页同意）：保留会话，202

package/lib/page.js

@@ -465,22 +465,26 @@ const renderCli = async (s) => {
   // 真实探测本机安装与授权态（数秒），期间先展示读取中
   body.innerHTML = '<div class="skill-sub">检测中…</div>';
   let tools;
+  let python;
   try {
     const resp = await fetch('api/cli/status');
     const data = await resp.json().catch(() => ({}));
     if (!resp.ok) throw new Error(data.error || '检测失败');
     tools = data.tools || {};
+    python = data.python || null;
   } catch {
     body.innerHTML = '<div class="skill-sub" style="color:var(--err)">CLI 状态检测失败，请稍后重试。</div>';
     return;
   }
-  renderCliData(s, tools);
+  renderCliData(s, tools, python);
 };
-// 纯渲染：tools 形如 { 'lark-cli': {state,version,latest}, ... }。
+// 纯渲染：tools 形如 { 'lark-cli': {state,version,latest}, ... }，
+// python 形如 { available, command, version }（null 表示未探测到数据）。
 // 升级成功后端会带回升级后立即探测的单工具详情，直接合进缓存同步刷新，
 // 不再整页二次探测（否则要再等一轮「检测中…」，用户以为没生效）。
-const renderCliData = (s, tools) => {
+const renderCliData = (s, tools, python) => {
   renderCli._tools = { ...(renderCli._tools || {}), ...tools };
+  if (python !== undefined && python !== null) renderCli._python = python;
   const allTools = renderCli._tools;
   const cliEnabled = s.capabilities?.cli_deployd_enabled !== false;
   const body = $('cli-body');
@@ -500,7 +504,6 @@ const renderCliData = (s, tools) => {
       : state === 'unauthorized'
         ? '<span class="pill warn" style="font-size:11px">未授权</span>'
         : '<span class="pill warn" style="font-size:11px">未安装</span>';
-    // 版本展示：当前版 · 有新版时「v旧 → v新」+ 升级按钮（查询失败静默退化）
     const versionLine = meta.desc + ' · ' + meta.label
       + (info.version ? ' · v' + esc(info.version) : '')
       + (info.latest && info.latest !== info.version
@@ -523,9 +526,30 @@ const renderCliData = (s, tools) => {
       + esc(name) + status + '</div><div class="skill-sub">'
       + versionLine + '</div></div><div style="display:flex;gap:6px">' + actions + '</div></div>';
   });
-  body.innerHTML = rows.join('')
+  // Python 环境行：技能脚本的标准依赖。Windows 未装时可一键安装
+  // （python.org 官方安装器静默装用户目录），其他平台给包管理器指引。
+  const py = renderCli._python;
+  const isWin = navigator.platform && /win/i.test(navigator.platform);
+  const pythonRow = py
+    ? '<div class="skill-item"><div class="skill-info"><div class="skill-name">Python '
+      + (py.available
+        ? '<span class="pill ok" style="font-size:11px">可用</span>'
+        : '<span class="pill warn" style="font-size:11px">未安装</span>')
+      + '</div><div class="skill-sub">'
+      + (py.available
+        ? '技能脚本运行环境 · ' + esc(py.command) + ' · v' + esc(py.version)
+        : isWin
+          ? '技能脚本运行环境 · 未检测到 Python（技能脚本需要 Python 3），点右侧「安装」自动装官方版本（python.org）'
+          : '技能脚本运行环境 · 未检测到 Python，可用系统包管理器安装（如 brew install python）后重启 dsh')
+      + '</div></div>'
+      + (!py.available && isWin
+        ? '<div style="display:flex;gap:6px"><button class="btn small primary" data-cli-install="python">安装</button></div>'
+        : '')
+      + '</div>'
+    : '';
+  body.innerHTML = rows.join('') + pythonRow
     + '<div class="hint">在对话中直接使用（如 /lark 帮助），由 dsh 自动调用。</div>'
-    + '<div class="hint">未安装时点「安装」自助安装；已安装未授权时点「去授权」用飞书扫码完成即可。</div>';
+    + '<div class="hint">未安装时点「安装」自助安装（Python 同样支持）；已安装未授权时点「去授权」用飞书扫码完成即可。</div>';
   body.querySelectorAll('[data-cli-upgrade]').forEach((btn) => {
     btn.onclick = () => cliUpgrade(btn.dataset.cliUpgrade, btn);
   });
@@ -648,8 +672,8 @@ const cliAuthDialog = async (tool) => {
   }
 };
 
-/** CLI 一键安装：lark 走 npm 全局安装、ccpg 走官方安装脚本，耗时可达
- * 分钟级。响应自带安装后立即探测的单工具详情，直接合进缓存刷新界面。 */
+/** CLI 一键安装：lark 走 npm 全局安装、ccpg/python 走官方安装器，耗时
+ * 可达分钟级。响应自带安装后立即探测的详情，直接合进缓存刷新界面。 */
 const cliInstall = async (tool, btn) => {
   btn.disabled = true;
   btn.textContent = '安装中，可能需要 1–3 分钟…';
@@ -662,7 +686,11 @@ const cliInstall = async (tool, btn) => {
     const data = await resp.json().catch(() => ({}));
     if (!resp.ok) throw new Error(data.error || 'CLI 安装失败');
     renderCli._probedAt = 0;
-    if (data.tool) {
+    if (tool === 'python') {
+      // python 无三态：回传 {available,command,version}，重绘 Python 行
+      if (data.python) renderCliData(lastStatus, {}, data.python);
+      else renderCli(lastStatus);
+    } else if (data.tool) {
       renderCliData(lastStatus, { [tool]: data.tool });
     } else {
       renderCli(lastStatus);
@@ -957,11 +985,21 @@ const refresh = async () => {
     }
     $('model-body').innerHTML = lines.join('')
       + (planBlocked
-        ? '<div class="row" style="margin-top:10px"><button id="goto-plan-btn" class="btn primary small">去申请套餐</button></div>'
+        ? '<div class="row" style="margin-top:10px">'
+          + '<button id="retry-model-btn" class="btn ghost small" data-loading="同步中…">重新同步模型</button>'
+          + '<button id="goto-plan-btn" class="btn primary small">去申请套餐</button></div>'
         : '');
     $('sync-btn').hidden = !modelEnabled || planBlocked;
     const gotoPlan = $('goto-plan-btn');
     if (gotoPlan) gotoPlan.onclick = () => activateTab('plan');
+    // planBlocked 兜底手动出口：旧错误残留时（套餐已批但本地还挂着
+    // plan_required）可立即重同步，不等后端自愈的退避周期
+    const retryModel = $('retry-model-btn');
+    if (retryModel) retryModel.onclick = () => withLoading(
+      retryModel,
+      () => fetch('api/model/sync', { method: 'POST' }),
+      '平台模型已同步',
+    );
   }
   if (s.logged_in && s.skillhub) {
     const sh = s.skillhub;

package/lib/proc.js

@@ -2,62 +2,212 @@
 //
 // 官方 `dsh plugin --profile web <args>` 内部就是 pnpm 转发 + profile
 // 初始化 + dsh.profile.bundles reconcile，全部复用。这里只封装进程执行
-// （execFile 参数数组、绝不经过 shell）与错误翻译；包名/版本白名单在
-// index.js 的调用侧执行。
+// （execFile 参数数组，不经 shell 拼接；win32 的 .cmd/.bat shim 是唯一
+// 例外——按 CVE-2024-27980 后的 Node 约定经 cmd.exe /d /s /c 执行，
+// 参数仍是数组形态）与错误翻译；包名/版本白名单在 index.js 的调用侧执行。
 import { execFile } from 'node:child_process';
-import { existsSync, readdirSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join, dirname, delimiter as pathDelimiter } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, renameSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join, isAbsolute, delimiter as pathDelimiter } from 'node:path';
 import { promisify } from 'node:util';
 
 const execFileAsync = promisify(execFile);
 
 /** 常见安装目录兑底（环境 PATH 之外的补充）：GUI 启动的 DSH Desktop 继承
- * launchd 的 PATH（/usr/bin:/bin:…），不含 nvm/homebrew/.local —— 实测
+ * launchd 的 PATH（/usr/bin:/bin/…），不含 nvm/homebrew/.local —— 实测
  * 从 Dock 启动时 pnpm/lark-cli 全部 ENOENT，插件页 latest 查不到、CLI
- * 全显示未安装。nvm 取最高 node 版本的 bin；结果进程内缓存。 */
+ * 全显示未安装。Windows 同理：GUI 启动继承系统 PATH，常缺 %APPDATA%\npm
+ * （npm 全局 bin）与 %LOCALAPPDATA%\pnpm（pnpm 默认 home）。nvm 取最高
+ * node 版本的 bin；结果进程内缓存。 */
 let extraBinDirsCache = null;
 function extraBinDirs() {
   if (extraBinDirsCache !== null) return extraBinDirsCache;
   const dirs = [];
   const home = homedir();
+  if (process.platform === 'win32') {
+    const appData = process.env.APPDATA || join(home, 'AppData', 'Roaming');
+    const localAppData = process.env.LOCALAPPDATA || join(home, 'AppData', 'Local');
+    const systemRoot = process.env.SystemRoot || 'C:\\Windows';
+    const programFiles = process.env.ProgramFiles || 'C:\\Program Files';
+    const programFilesX86 = process.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)';
+    // Windows 系统目录：cmd.exe / curl.exe / powershell 等系统自带命令的
+    // 落地位——GUI 宿主 PATH 贫瘠时连 cmd.exe 都 resolve 不到，.cmd shim
+    // 的路由与 curl 下载全部瘫痪，必须兑底。
+    dirs.push(
+      join(systemRoot, 'System32'),
+      systemRoot,
+      join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0'),
+    );
+    // nodejs.org 官方安装器默认系统级安装位（机器级 Program Files；
+    // 机器上没有 node.exe 时不会注入 PATH，但兑底目录里如果找到了，
+    // 就能解析出 node/npm，不用再要求用户装 Node）。
+    dirs.push(join(programFiles, 'nodejs'), join(programFilesX86, 'nodejs'));
+    // npm -g 默认 prefix、pnpm 默认 PNPM_HOME，以及 ccpg-cli Windows 官方
+    // 安装器的落点 %USERPROFILE%\bin（本机实测 C:\Users\<user>\bin\
+    // ccpg-cli.exe；装完不重启也能立即探测/自升级）。nodejs.org 安装器的
+    // 系统级安装不在这些目录，但那种环境 PATH 里有 node，不需要兑底。
+    dirs.push(join(appData, 'npm'), join(localAppData, 'pnpm'), join(home, 'bin'));
+    // Python 常见安装位（python 探测兑底）：python.org 每用户安装位
+    // %LOCALAPPDATA%\Programs\Python\Python3xx、机器级 Program Files\
+    // Python3xx、Miniconda/Anaconda 默认位。自定义安装位（如
+    // E:\VScode\miniconda3）在 PATH 里，不受影响。
+    try {
+      const pyRoot = join(localAppData, 'Programs', 'Python');
+      for (const entry of readdirSync(pyRoot)) {
+        if (existsSync(join(pyRoot, entry, 'python.exe'))) dirs.push(join(pyRoot, entry));
+      }
+    } catch {
+      // 未装 python.org 版：跳过
+    }
+    try {
+      for (const entry of readdirSync(programFiles)) {
+        if (/^Python\d+/.test(entry) && existsSync(join(programFiles, entry, 'python.exe'))) {
+          dirs.push(join(programFiles, entry));
+        }
+      }
+    } catch {
+      // 未装机器级 python.org 版：跳过
+    }
+    // Miniconda/Anaconda 常见默认位：用户目录与 ProgramData（机器级共享）
+    dirs.push(
+      join(home, 'miniconda3'), join(home, 'anaconda3'),
+      join('C:\\', 'ProgramData', 'miniconda3'), join('C:\\', 'ProgramData', 'Anaconda3'),
+    );
+  } else {
+    try {
+      // nvm 目录名形如 v24.18.0，用 compareSemver 取最高版（compareSemver
+      // 在本文件后文定义，函数提升可用）
+      const versions = readdirSync(join(home, '.nvm/versions/node'))
+        .filter((v) => /^v?\d/.test(v))
+        .sort((a, b) => compareSemver(a.replace(/^v/, ''), b.replace(/^v/, '')));
+      if (versions.length) dirs.push(join(home, '.nvm/versions/node', versions[versions.length - 1], 'bin'));
+    } catch {
+      // 无 nvm：跳过，走后面的通用目录
+    }
+    dirs.push(join(home, '.local/bin'), '/opt/homebrew/bin', '/usr/local/bin');
+  }
+  // DSH Desktop 自带的 node/pnpm/dsh shim（Electron 当 node 用）：宿主只把
+  // 这目录注入桌面终端的 PATH，插件子进程看不到——不兑底的话 dsh 自身有
+  // node 环境但 lark-cli 安装仍报「未找到 npm」。目录名是 profile 的 hash，
+  // 扫一层取含 bin 的子目录。Windows 桌面版把 shim 放在
+  // %LOCALAPPDATA%\\DSH Desktop\\shims（按官方约定），一并覆盖。
   try {
-    // nvm 目录名形如 v24.18.0，用 compareSemver 取最高版（compareSemver
-    // 在本文件后文定义，函数提升可用）
-    const versions = readdirSync(join(home, '.nvm/versions/node'))
-      .filter((v) => /^v?\d/.test(v))
-      .sort((a, b) => compareSemver(a.replace(/^v/, ''), b.replace(/^v/, '')));
-    if (versions.length) dirs.push(join(home, '.nvm/versions/node', versions[versions.length - 1], 'bin'));
+    const cliRoot = join(home, 'Library', 'Application Support', 'DSH Desktop', 'cli');
+    for (const entry of readdirSync(cliRoot)) {
+      const shimBin = join(cliRoot, entry, 'bin');
+      if (existsSync(join(shimBin, 'node'))) dirs.push(shimBin);
+    }
   } catch {
-    // 无 nvm（Windows/其他包管理器）：跳过，走后面的通用目录
+    // 非 macOS / 未生成终端 shim：跳过
+  }
+  if (process.platform === 'win32') {
+    try {
+      const shimDir = join(
+        process.env.LOCALAPPDATA || join(home, 'AppData', 'Local'),
+        'DSH Desktop', 'shims',
+      );
+      if (existsSync(join(shimDir, 'node.exe')) || existsSync(join(shimDir, 'node.cmd'))) dirs.push(shimDir);
+    } catch {
+      // 目录不存在：跳过
+    }
   }
-  dirs.push(join(home, '.local/bin'), '/opt/homebrew/bin', '/usr/local/bin');
   extraBinDirsCache = dirs;
   return dirs;
 }
 
-/** 命令解析：PATH 里找不到时从兑底目录解析绝对路径（找不到返回原名，
- * 后续 ENOENT 走既有 missing/降级语义）。所有 execFile 调用统一过这里。 */
-export function resolveCommand(tool) {
+/** 安装完成后清空兑底目录缓存：一键安装 python/ccpg 后新目录要立即可
+ * 探测（python.org 装到 %LOCALAPPDATA%\Programs\Python\Python3xx），不
+ * 能等 DSH Desktop 重启。 */
+export function resetExtraBinDirsCache() {
+  extraBinDirsCache = null;
+}
+
+/** 候选扩展名顺序（纯函数，供测试）：win32 下 CreateProcess 只认可执行
+ * 映像，npm/pnpm/lark-cli 的安装目录同时存在同名的无扩展名 sh 脚本
+ * （给 Git Bash 用）与 .cmd shim——无扩展名必须排最后，否则解析命中 sh
+ * 脚本，execFile 直接失败。 */
+export function candidateSuffixes(platform) {
+  return platform === 'win32' ? ['.exe', '.cmd', ''] : [''];
+}
+
+/** win32 下 .cmd/.bat shim 的 execFile 等价调用形态（纯函数，供测试）：
+ * Node ≥ 18.20/20.12（CVE-2024-27980 修复，DSH Desktop 内置 Node 同样
+ * 受影响）起 execFile 直接执行 .cmd/.bat 会同步抛 spawn EINVAL，必须经
+ * cmd.exe /d /s /c 解释。参数仍走数组、由 Node 按 Windows 规则引号转义，
+ * 不拼接用户输入。非 win32 或非 shim 返回 null。 */
+export function cmdShimInvocation(platform, resolved, args) {
+  if (platform !== 'win32') return null;
+  if (!/\.(cmd|bat)$/i.test(resolved)) return null;
+  return { file: 'cmd.exe', args: ['/d', '/s', '/c', resolved, ...args] };
+}
+
+/** PATH 环境变量键名（纯函数，供测试）：win32 下实际键通常是 Path，注入
+ * 时必须复用已有键，否则 env 里出现 Path+PATH 两个重复键，子进程读到
+ * 哪个取决于实现。 */
+export function pathEnvKey(env, platform) {
+  if (platform !== 'win32') return 'PATH';
+  return Object.keys(env).find((key) => /^path$/i.test(key)) || 'PATH';
+}
+
+/** 命令解析：PATH 里找不到时从兑底目录解析绝对路径（找不到返回 null）。
+ * 所有 execFile 调用统一过这里；返回 null 时调用方走「未找到命令」的
+ * 中文指引分支。绝对路径原样返回（ccpg 安装器等）。 */
+export function resolveCommandOrNull(tool) {
+  if (isAbsolute(tool)) return existsSync(tool) ? tool : null;
   const pathDirs = String(process.env.PATH || '').split(pathDelimiter).filter(Boolean);
-  const candidates = [];
+  const suffixes = candidateSuffixes(process.platform);
   for (const dir of [...pathDirs, ...extraBinDirs()]) {
-    candidates.push(join(dir, tool));
-    if (process.platform === 'win32') candidates.push(join(dir, `${tool}.exe`), join(dir, `${tool}.cmd`));
+    for (const suffix of suffixes) {
+      const candidate = join(dir, tool + suffix);
+      if (existsSync(candidate)) return candidate;
+    }
   }
-  return candidates.find((p) => existsSync(p)) || tool;
+  return null;
 }
 
-/** 统一的子进程执行：解析命令路径，并把解析到的目录前置进子进程 PATH
- * （pnpm/lark-cli 等是 `#!/usr/bin/env node` 脚本，宿主 PATH 贫瘠时
- * 找得到脚本也找不到 node，必须连带注入）。opts.env 只传增量变量。 */
+/** 与 resolveCommandOrNull 同口径，但返回全部按序去重候选。python 这类
+ * 探测必须逐个候选试：Windows PATH 前段常是 Microsoft Store 的假别名
+ * （0 字节重解析点，执行退出码 9009），真正的解释器（miniconda /
+ * python.org）排在更后面——只试首个命中会误报未安装。 */
+export function resolveCommandCandidates(tool) {
+  if (isAbsolute(tool)) return existsSync(tool) ? [tool] : [];
+  const seen = new Set();
+  const out = [];
+  const pathDirs = String(process.env.PATH || '').split(pathDelimiter).filter(Boolean);
+  const suffixes = candidateSuffixes(process.platform);
+  for (const dir of [...pathDirs, ...extraBinDirs()]) {
+    for (const suffix of suffixes) {
+      const candidate = join(dir, tool + suffix);
+      if (existsSync(candidate) && !seen.has(candidate)) {
+        seen.add(candidate);
+        out.push(candidate);
+      }
+    }
+  }
+  return out;
+}
+
+/** 兼容旧签名：找不到时返回原名（后续 ENOENT 走既有 missing/降级语义）。 */
+export function resolveCommand(tool) {
+  return resolveCommandOrNull(tool) || tool;
+}
+
+/** 统一的子进程执行：解析命令路径，并把**所有兑底目录**前置进子进程
+ * PATH——win32 下 npm/lark-cli 是 .cmd shim（`%~dp0\node.exe` 找 node），
+ * node 可能在另一个兑底目录（nodejs.org 系统安装位）；.cmd 又经
+ * cmd.exe /d /s /c 路由，cmd.exe 在第三个兑底目录（System32）。只前置
+ * 解析到的那个目录会让 shim 内部找不到依赖，必须整组前置。opts.env 只
+ * 传增量变量。 */
 function execResolved(tool, args, { timeoutMs, cwd, env } = {}) {
   const resolved = resolveCommand(tool);
   const childEnv = { ...process.env, ...(env || {}) };
-  if (resolved !== tool) {
-    childEnv.PATH = [dirname(resolved), childEnv.PATH || ''].filter(Boolean).join(pathDelimiter);
+  const key = pathEnvKey(childEnv, process.platform);
+  const extras = extraBinDirs().filter((dir) => existsSync(dir));
+  if (extras.length) {
+    childEnv[key] = [...extras, childEnv[key] || ''].filter(Boolean).join(pathDelimiter);
   }
-  return execFileAsync(resolved, args, {
+  const shim = cmdShimInvocation(process.platform, resolved, args);
+  return execFileAsync(shim ? shim.file : resolved, shim ? shim.args : args, {
     timeout: timeoutMs,
     killSignal: 'SIGKILL',
     cwd,
@@ -76,6 +226,21 @@ export function firstErrorLines(raw) {
   return picked.slice(0, 300);
 }
 
+/** pnpm store 版本冲突（受管 pnpm 与用户全局 pnpm 主版本不同，store 目录
+ * 格式不兼容）。Windows 桌面版高发：用户装了独立 pnpm 且主版本与 DSH
+ * Desktop 内置的不同。识别后给可操作指引而非裸抛英文堆栈。 */
+export function isUnexpectedStoreError(message) {
+  return /ERR_PNPM_UNEXPECTED_STORE/i.test(String(message || ''));
+}
+
+/** 翻译 pnpm store 冲突为人话 + 自愈指引。 */
+export function unexpectedStoreGuidance() {
+  return '检测到 pnpm 存储版本冲突（DSH Desktop 内置的 pnpm 与你电脑上安装的 pnpm 主版本不一致）。'
+    + '请在 DSH Desktop 外自行执行一次插件安装即可自动重建存储：关闭本窗口后运行 '
+    + (process.platform === 'win32' ? 'dsh plugin --profile desktop add dsh-agentone' : 'dsh plugin --profile web add dsh-agentone')
+    + '，或删除 profile 目录下的 node_modules 后重试。';
+}
+
 /**
  * 运行一次性命令。webServer 注册的处理器是同步 Node handler 场景下的
  * async 函数；execFile 不经过 shell，参数数组中的每个元素都是独立参数，
@@ -91,16 +256,41 @@ export async function runCliTool(tool, args, { timeoutMs = 300000, cwd, env } =
     return { stdout, stderr };
   } catch (error) {
     if (error.code === 'ENOENT') {
-      throw new Error(`未找到 ${tool} 命令，请确认已安装`);
+      throw new Error(missingCommandGuidance(tool));
     }
     if (error.killed) {
       throw new Error('命令执行超时，请稍后重试');
     }
-    const message = firstErrorLines(`${error.stderr || ''}\n${error.stdout || ''}`);
+    const raw = `${error.stderr || ''}\n${error.stdout || ''}`;
+    if (isUnexpectedStoreError(raw)) {
+      throw new Error(unexpectedStoreGuidance());
+    }
+    const message = firstErrorLines(raw);
     throw new Error(message || `命令执行失败（退出码 ${error.code ?? '未知'}）`);
   }
 }
 
+/** 工具缺失时的中文指引：不同工具有不同的安装出路。 */
+function missingCommandGuidance(tool) {
+  if (tool === 'npm' || tool === 'npx') {
+    return process.platform === 'win32'
+      ? '未找到 npm/npx 命令：lark-cli 依赖 Node.js 环境，请先从 https://nodejs.org 下载安装 Node.js（LTS 版，安装时保持默认选项），安装完成后重启 DSH Desktop 再点「安装」'
+      : '未找到 npm/npx 命令：lark-cli 依赖 Node.js 环境，请先安装 Node.js（推荐 nvm：nvm install --lts），安装完成后重启 DSH Desktop 再点「安装」';
+  }
+  if (tool === 'pnpm') {
+    return '未找到 pnpm 命令，无法查询插件最新版本。可安装 pnpm（npm install -g pnpm）后重启 DSH Desktop；不影响插件正常使用，仅影响升级提示。';
+  }
+  if (tool === 'dsh') {
+    return '未找到 dsh 命令，请确认已安装 dsh 并在终端可用';
+  }
+  if (tool === 'python' || tool === 'python3' || tool === 'py') {
+    return process.platform === 'win32'
+      ? '未检测到 Python：技能脚本需要 Python 3 运行环境，点「安装」自动装官方版本（python.org），或自行从 https://www.python.org 下载安装（勾选 Add to PATH）后重启 DSH Desktop'
+      : '未检测到 Python：技能脚本需要 Python 3 运行环境，请用系统包管理器安装（如 brew install python / apt install python3）后重启 dsh';
+  }
+  return `未找到 ${tool} 命令，请确认已安装`;
+}
+
 /** dsh plugin 子命令：转发给官方 CLI（profile 由调用方给出）。 */
 export function dshPluginCli(args, profile = 'web') {
   return runCliTool('dsh', ['plugin', '--profile', profile, ...args]);
@@ -157,16 +347,25 @@ export function compareSemver(a, b) {
 }
 
 /**
- * 查询包在 registry 的最新版本（`pnpm view <name>@latest version`）。
- * 为什么不用 `pnpm outdated` / `update -L` / `add pkg@latest`：实测 pnpm 11
- * 里 outdated 受 dist-tag 元数据缓存与 minimumReleaseAge 冷却期影响（新版
- * 发布后一段时间查不到），update -L 对精确 pin 的依赖是 no-op，add@latest
- * 会解析到缓存旧版；只有显式版本号可用。view 单字段查询每次真实打
- * registry，是这里唯一的实时数据源。查询失败返回 null（前端按钮不出现）。
+ * 查询包在 registry 的最新版本。优先 `pnpm view`；pnpm 不可用（Windows
+ * 桌面版常见——受管 pnpm 不在 PATH）时退化 `npm view`（输出同为版本行，
+ * parseLatestVersionLine 通吃）。为什么不用 `pnpm outdated` /
+ * `update -L` / `add pkg@latest`：实测 pnpm 11 里 outdated 受 dist-tag
+ * 元数据缓存与 minimumReleaseAge 冷却期影响（新版发布后一段时间查不到），
+ * update -L 对精确 pin 的依赖是 no-op，add@latest 会解析到缓存旧版；只有
+ * 显式版本号可用。view 单字段查询每次真实打 registry，是这里唯一的实时
+ * 数据源。查询失败返回 null（前端按钮不出现）。
  */
 export async function pnpmViewLatest(name, cwd) {
-  const { stdout } = await pnpmCli(['view', `${name}@latest`, 'version'], 30000, cwd);
-  return parseLatestVersionLine(stdout);
+  try {
+    const { stdout } = await pnpmCli(['view', `${name}@latest`, 'version'], 30000, cwd);
+    return parseLatestVersionLine(stdout);
+  } catch (error) {
+    // pnpm 缺失（含 store 冲突指引类可操作错误）不影响升级检测本身：
+    // npm view 同样实时打 registry，版本号全局一致
+    const { stdout } = await runCliTool('npm', ['view', `${name}@latest`, 'version'], { timeoutMs: 30_000, cwd });
+    return parseLatestVersionLine(stdout);
+  }
 }
 
 /**
@@ -233,12 +432,39 @@ async function cliLatestVersion(tool, timeoutMs) {
     return typeof data?.latest_version === 'string' ? data.latest_version : null;
   }
   if (tool === 'lark-cli') {
-    const { stdout } = await execResolved('npm', ['view', '@larksuite/cli', 'version'], { timeoutMs });
+    // runCliTool 而非裸 execResolved：走 Windows 兑底目录解析 npm，
+    // ENOENT 时抛中文指引由上层 catch 降级（按钮不出现）而非静默挂死
+    const { stdout } = await runCliTool('npm', ['view', '@larksuite/cli', 'version'], { timeoutMs });
     return parseCliVersion(stdout);
   }
   return null;
 }
 
+/**
+ * Python 环境探测（技能脚本的标准依赖）。win32 优先官方 py 启动器，再
+ * python / python3；每个名字按 resolveCommandCandidates 逐个候选试
+ * `--version`（穿透 Store 假别名）。Python 2.x 不算可用——技能脚本需要
+ * 3.x，继续找下一个候选。与平台 instance_service 的口径一致：探测失败
+ * 不抛错，返回 available:false 由前端给安装指引/按钮。
+ */
+export async function probePythonEnv({ timeoutMs = 15_000 } = {}) {
+  const names = process.platform === 'win32' ? ['py', 'python', 'python3'] : ['python3', 'python'];
+  for (const name of names) {
+    for (const candidate of resolveCommandCandidates(name)) {
+      try {
+        const { stdout, stderr } = await runCliTool(candidate, ['--version'], { timeoutMs });
+        const match = /(\d+)\.(\d+)(?:\.(\d+))?/.exec(`${stdout || ''}${stderr || ''}`);
+        if (match && Number(match[1]) >= 3) {
+          return { available: true, command: name, version: match[0] };
+        }
+      } catch {
+        // Store 假别名（9009）/ 不可执行 / 超时：试下一个候选
+      }
+    }
+  }
+  return { available: false, command: null, version: null };
+}
+
 /** ccpg-cli 官方安装脚本地址（与平台侧 cli-deployd-go InstallCCPGCLI 同源，
  * 保持两端口径一致；auto-install.sh 自带二进制下载与 PATH 写入）。 */
 const CCPG_CLI_INSTALL_URL_PREFIX = 'http://bms.einwin.com/media/ccpg-cli/202605091513';
@@ -273,29 +499,51 @@ async function installLarkSkills({ timeoutMs = 180_000 } = {}) {
  *             cli-deployd-go 的 install 口径一致。
  * 返回输出尾部给前端展示。只接受 CLI_TOOLS 白名单内的 tool。
  */
-export async function installCliTool(tool, { timeoutMs = 300_000 } = {}) {
+export async function installCliTool(tool, { timeoutMs = 600_000 } = {}) {
   let stdout;
   if (tool === 'lark-cli') {
-    ({ stdout } = await runCliTool('npm', ['install', '-g', '@larksuite/cli@latest'], { timeoutMs }));
+    // 预检+降级链：优先独立 npm；没有 npm 但有 pnpm（含 DSH Desktop 自带
+    // shim）时用 pnpm 全局装——lark-cli 官方支持 pnpm 安装方式，装出来的
+    // 二进制与 npm 路径一致，后续 lark-cli update 也能自升级。
+    // 两者都没有才报「装 Node.js」指引。
+    if (resolveCommandOrNull('npm')) {
+      ({ stdout } = await runCliTool('npm', ['install', '-g', '@larksuite/cli@latest'], { timeoutMs }));
+    } else if (resolveCommandOrNull('pnpm')) {
+      ({ stdout } = await runCliTool('pnpm', ['add', '-g', '@larksuite/cli@latest'], { 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}`;
     });
     stdout = `${stdout}\n${skillsNote}`;
   } else if (tool === 'ccpg-cli') {
-    // 下载 auto-install.sh（curl 失败退化 wget）后交 bash 执行；execFile 不经
-    // 外层 shell，脚本文本作为 bash -c 的单一参数，与平台侧 `| bash` 等价。
-    const fetchScript = () => runCliTool('curl', [
-      '-fsSL', '--retry', '3', '--retry-delay', '5', '--max-time', '120',
-      `${CCPG_CLI_INSTALL_URL_PREFIX}/auto-install.sh`,
-    ], { timeoutMs: 120_000 })
-      .catch(() => runCliTool('wget', ['-qO-', `${CCPG_CLI_INSTALL_URL_PREFIX}/auto-install.sh`], { timeoutMs: 120_000 }));
-    const fetched = (await fetchScript()).stdout.trim();
-    if (!fetched) throw new Error('安装脚本下载失败，请检查网络后重试');
-    ({ stdout } = await runCliTool('bash', ['-c', fetched], {
-      timeoutMs,
-      env: { CCPG_CLI_URL_PREFIX: CCPG_CLI_INSTALL_URL_PREFIX },
-    }));
+    if (process.platform === 'win32') {
+      ({ stdout } = await installCcpgCliWindows(timeoutMs));
+    } else {
+      // 下载 auto-install.sh（curl 失败退化 wget）后交 bash 执行；脚本文本
+      // 来自固定公司 URL（非用户输入），作为 bash -c 的单一参数，与平台
+      // 侧 `| bash` 等价。
+      const scriptUrl = `${CCPG_CLI_INSTALL_URL_PREFIX}/auto-install.sh`;
+      const fetchScript = () => runCliTool('curl', [
+        '-fsSL', '--retry', '3', '--retry-delay', '5', '--max-time', '120',
+        scriptUrl,
+      ], { timeoutMs: 120_000 })
+        .catch(() => runCliTool('wget', ['-qO-', scriptUrl], { timeoutMs: 120_000 }));
+      const fetched = (await fetchScript()).stdout.trim();
+      if (!fetched) throw new Error('安装脚本下载失败，请检查网络后重试');
+      ({ stdout } = await runCliTool('bash', ['-c', fetched], {
+        timeoutMs,
+        env: { CCPG_CLI_URL_PREFIX: CCPG_CLI_INSTALL_URL_PREFIX },
+      }));
+    }
+    resetExtraBinDirsCache();
+  } else if (tool === 'python') {
+    if (process.platform !== 'win32') {
+      throw new Error('请用系统包管理器安装 Python（如 brew install python / apt install python3）后重启 dsh');
+    }
+    ({ stdout } = await installPythonWindows(timeoutMs));
   } else {
     throw new Error('不支持的 CLI 工具');
   }
@@ -303,18 +551,154 @@ export async function installCliTool(tool, { timeoutMs = 300_000 } = {}) {
   return lines.slice(-6).join('\n');
 }
 
+/** ccpg-cli Windows 安装（与 mac/Linux auto-install.sh 同构：裸二进制落地）：
+ * 1) 动态查询官方更新接口拿当前二进制地址——媒体目录按日期滚动，pin 死
+ *    的旧地址会被服务器清理（实测教程里的 202607151817 已 404）；接口与
+ *    ccpg-cli 自身 updater 同源，永远指向当前有效版本。接口返回的 URL
+ *    必须落在 bms.einwin.com/media/ccpg-cli/ 前缀下才接受（防接口被篡
+ *    改指向恶意地址），接口异常时兜底最近一次验证过的 pin 值。
+ *    注意：接口给的是**裸二进制本体**（实测与 update 落地文件逐字节一
+ *    致），不是安装器——落地即用，无 /S 静默安装一说。
+ * 2) curl 下载到 %USERPROFILE%\bin\ccpg-cli.exe（先下暂存再改名，原子）
+ * 3) 校验 --version 可执行（PE 完整、架构匹配）
+ * 4) %USERPROFILE%\bin 写入用户 PATH（注册表 User 作用域，免管理员）
+ * 5) 教程必做步骤 ccpg-cli update（刚下的就是 latest，通常 no-op，软失败）
+ * 全程 execFile 参数数组，不经 shell。 */
+const CCPG_CLI_UPDATE_ENDPOINT = 'https://bms.einwin.com/mdm-third-party/ccpg-cli/latest?os=windows&arch=amd64';
+const CCPG_CLI_WINDOWS_URL_PREFIX = 'https://bms.einwin.com/media/ccpg-cli/';
+const CCPG_CLI_WINDOWS_FALLBACK_URL = `${CCPG_CLI_WINDOWS_URL_PREFIX}202608271055/ccpg-cli-windows-amd64.exe`;
+
+async function resolveCcpgWindowsDownloadUrl() {
+  try {
+    const { stdout } = await runCliTool('curl', [
+      '-fsSL', '--max-time', '30', CCPG_CLI_UPDATE_ENDPOINT,
+    ], { timeoutMs: 40_000 });
+    const url = JSON.parse(String(stdout).trim())?.value?.url;
+    if (typeof url === 'string' && url.startsWith(CCPG_CLI_WINDOWS_URL_PREFIX)) return url;
+  } catch {
+    // 更新接口异常：走兜底 pin 值
+  }
+  return CCPG_CLI_WINDOWS_FALLBACK_URL;
+}
+
+/** 把目录追加进用户 PATH（注册表 User 作用域，新开终端生效）。已存在则
+ * 跳过。用 powershell [Environment] API——setx 会静默截断超过 1024 字符
+ * 的 PATH，不用。 */
+async function ensureUserPathContains(dir) {
+  const safeDir = dir.replace(/'/g, "''");
+  const script = [
+    "$p=[Environment]::GetEnvironmentVariable('Path','User')",
+    `if(($p -split ';') -notcontains '${safeDir}'){[Environment]::SetEnvironmentVariable('Path',($p.TrimEnd(';')+';${safeDir}'),'User');'added'}else{'exists'}`,
+  ].join(';');
+  const { stdout } = await runCliTool('powershell', ['-NoProfile', '-Command', script], { timeoutMs: 30_000 });
+  return String(stdout).includes('added')
+    ? '已把 %USERPROFILE%\\bin 写入用户 PATH（新开的终端生效）'
+    : '%USERPROFILE%\\bin 已在用户 PATH 中';
+}
+
+async function installCcpgCliWindows(timeoutMs) {
+  const binDir = join(homedir(), 'bin');
+  const target = join(binDir, 'ccpg-cli.exe');
+  mkdirSync(binDir, { recursive: true });
+  const url = await resolveCcpgWindowsDownloadUrl();
+  const staging = join(binDir, 'ccpg-cli.exe.download');
+  await runCliTool('curl', [
+    '-fsSL', '--retry', '3', '--retry-delay', '5', '--max-time', '600',
+    '--speed-limit', '65536', '--speed-time', '30',
+    '-o', staging, url,
+  ], { timeoutMs });
+  renameSync(staging, target);
+  // 校验二进制可执行（PE 完整、架构匹配）
+  const { stdout: versionOut } = await runCliTool(target, ['--version'], { timeoutMs: 30_000 });
+  resetExtraBinDirsCache();
+  const pathNote = await ensureUserPathContains(binDir)
+    .catch(() => 'PATH 写入失败，请手动把 %USERPROFILE%\\bin 加入用户 PATH');
+  // 官方教程的必做步骤：装完立即自升级（刚下的就是 latest，通常 no-op；
+  // 软失败不阻断）
+  const updateNote = await runCliTool('ccpg-cli', ['update'], {
+    timeoutMs: 120_000,
+    env: { CCPG_FULL_CLI: '1' },
+  })
+    .then((r) => String(r.stdout || '').trim().split('\n').slice(-2).join('\n'))
+    .catch(() => 'ccpg-cli update 未完成，安装后请手动执行 ccpg-cli update');
+  return {
+    stdout: `ccpg-cli 安装完成（${String(versionOut).trim()}）\n${updateNote}\n${pathNote}\n如状态页仍显示未安装，请重启 DSH Desktop 后点「重新检测」`,
+  };
+}
+
+/** Python Windows 一键安装（python.org 官方安装器口径）：
+ * 1) Windows 10 1803+ 自带 curl.exe 下载官方安装器——**国内镜像优先**
+ *    （python.org 官网源在国内动辄超时，实测华为云镜像 2MB/s、官网源
+ *    300s 拉不完 45MB），镜像目录结构与官网一致、按版本号直链；
+ *    镜像不可用时退化官网源（海外用户/镜像异常）
+ * 2) 静默每用户安装：InstallAllUsers=0（无需 UAC/管理员）、
+ *    PrependPath=1（安装器直接写入用户 PATH——不勾选的话 GUI 宿主
+ *    要等重启才能看到 python.exe）
+ * 3) 装完清兑底目录缓存，本进程内即可探测到新解释器
+ * 全程 execFile 参数数组，不经 shell。 */
+const PYTHON_WINDOWS_INSTALLER_VERSION = '3.13.6';
+const PYTHON_WINDOWS_INSTALLER_URLS = [
+  `https://mirrors.huaweicloud.com/python/${PYTHON_WINDOWS_INSTALLER_VERSION}/python-${PYTHON_WINDOWS_INSTALLER_VERSION}-amd64.exe`,
+  `https://www.python.org/ftp/python/${PYTHON_WINDOWS_INSTALLER_VERSION}/python-${PYTHON_WINDOWS_INSTALLER_VERSION}-amd64.exe`,
+];
+
+async function installPythonWindows(timeoutMs) {
+  const installer = join(tmpdir(), 'python-setup.exe');
+  // 逐个源下载：curl 失败（非 2xx/超时/低速假死）换下一个源。
+  // --speed-limit/--speed-time：30 秒内速度低于 64KB/s 视为假死换源
+  // （官网源在国内常见形态不是断连而是 kb 级慢速拖死）。
+  let downloaded = false;
+  let lastError = null;
+  for (const url of PYTHON_WINDOWS_INSTALLER_URLS) {
+    try {
+      await runCliTool('curl', [
+        '-fsSL', '--retry', '2', '--retry-delay', '3', '--max-time', '600',
+        '--speed-limit', '65536', '--speed-time', '30',
+        '-o', installer, url,
+      ], { timeoutMs });
+      downloaded = true;
+      break;
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  if (!downloaded) throw lastError || new Error('安装包下载失败，请检查网络后重试');
+  // python.org 安装器静默模式：/quiet + 每用户安装 + 写入用户 PATH
+  await runCliTool(installer, [
+    '/quiet', 'InstallAllUsers=0', 'PrependPath=1', 'Include_test=0',
+  ], { timeoutMs });
+  resetExtraBinDirsCache();
+  // 立即复探（本进程内兑底目录已含 python.org 每用户安装位）
+  const probe = await probePythonEnv().catch(() => ({ available: false }));
+  return {
+    stdout: probe.available
+      ? `Python ${probe.version} 安装完成（${probe.command}）。如技能页仍提示未安装，请重启 DSH Desktop 后点「重新检测」`
+      : `Python ${PYTHON_WINDOWS_INSTALLER_VERSION} 安装完成。安装器已写入用户 PATH，请重启 DSH Desktop 后点「重新检测」`,
+  };
+}
+
 /**
  * 触发 CLI 官方自升级（`tool update`）：ccpg-cli 从更新服务器下载二进制
- * （~17MB），lark-cli 自动探测 npm/pnpm/手动安装方式（手动时只打印
+ * （~17MB），新版 lark-cli 自动探测 npm/pnpm/手动安装方式（手动时只打印
  * GitHub 下载地址）。返回输出尾部给前端展示（含手动安装的下载链接）。
+ * 兜底：老版本 lark-cli 没有 update 子命令（实测 1.0.0 报 unknown
+ * command），此时「重装即升级」——走 installCliTool 的 npm/pnpm 全局装
+ * 最新版链路，覆盖旧版。
  */
 export async function upgradeCliTool(tool, { timeoutMs = 300_000 } = {}) {
-  const { stdout } = await runCliTool(tool, ['update'], {
-    timeoutMs,
-    env: tool === 'ccpg-cli' ? { CCPG_FULL_CLI: '1' } : undefined,
-  });
-  const lines = String(stdout).split('\n').map((l) => l.trim()).filter(Boolean);
-  return lines.slice(-6).join('\n');
+  try {
+    const { stdout } = await runCliTool(tool, ['update'], {
+      timeoutMs,
+      env: tool === 'ccpg-cli' ? { CCPG_FULL_CLI: '1' } : undefined,
+    });
+    const lines = String(stdout).split('\n').map((l) => l.trim()).filter(Boolean);
+    return lines.slice(-6).join('\n');
+  } catch (error) {
+    if (tool === 'lark-cli' && /unknown command/i.test(String(error?.message || ''))) {
+      return installCliTool('lark-cli', { timeoutMs });
+    }
+    throw error;
+  }
 }
 
 /** lark-cli 形态：identities 下的 tokenStatus 或新版 status/available 组合。 */

package/package.json

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