dsh-agentone 0.5.22 → 0.5.24

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, pnpmViewLatest, runCliTool, unexpectedStoreGuidance, 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';
 
@@ -370,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
@@ -1211,26 +1226,12 @@ export function apply(ctx, config) {
       // 真实探测本机 CLI：三态与平台 cli-deployd 判定口径一致，附带版本
       // 与最新版（查询失败降级 null，不阻塞三态）。并发探测，单个失败不影
       // 响另一个。附带 Python 环境探测（技能脚本标准依赖，Windows GUI 启动
-      // 时 PATH 常缺 python，缺失时前端给安装指引）。
-      const pythonCandidates = process.platform === 'win32'
-        ? ['python', 'python3', 'py']
-        : ['python3', 'python'];
-      const probePython = async () => {
-        for (const name of pythonCandidates) {
-          try {
-            const result = await runCliTool(name, ['--version'], { timeoutMs: 10_000 });
-            const match = /(\d+\.\d+(?:\.\d+)?)/.exec(`${result.stdout || ''}${result.stderr || ''}`);
-            if (match) return { available: true, command: name, version: match[1] };
-          } catch {
-            // 未安装或 Store 假别名：试下一个候选
-          }
-        }
-        return { available: false, command: null, version: null };
-      };
+      // 时 PATH 常缺 python 或前段是 Store 假别名，probePythonEnv 逐个候选
+      // 穿透重试），缺失时前端给安装按钮/指引。
       const [lark, ccpg, python] = await Promise.all([
-        probeCliDetail('lark-cli').catch(() => ({ state: 'missing', version: null, latest: null })),
-        probeCliDetail('ccpg-cli').catch(() => ({ state: 'missing', version: null, latest: null })),
-        probePython().catch(() => ({ available: false, command: null, version: null })),
+        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 }, python });
     });
@@ -1244,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 安装失败，请稍后重试' });
       }
@@ -1274,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 升级失败，请稍后重试' });
@@ -1298,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;
@@ -1348,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

@@ -526,7 +526,8 @@ const renderCliData = (s, tools, python) => {
       + esc(name) + status + '</div><div class="skill-sub">'
       + versionLine + '</div></div><div style="display:flex;gap:6px">' + actions + '</div></div>';
   });
-  // Python 环境行：技能脚本的标准依赖，缺失时按平台给安装指引
+  // Python 环境行：技能脚本的标准依赖。Windows 未装时可一键安装
+  // （python.org 官方安装器静默装用户目录），其他平台给包管理器指引。
   const py = renderCli._python;
   const isWin = navigator.platform && /win/i.test(navigator.platform);
   const pythonRow = py
@@ -538,13 +539,17 @@ const renderCliData = (s, tools, python) => {
       + (py.available
         ? '技能脚本运行环境 · ' + esc(py.command) + ' · v' + esc(py.version)
         : isWin
-          ? '技能脚本运行环境 · 未检测到 Python，从 python.org 下载安装（勾选 Add to PATH）后重启 DSH Desktop'
+          ? '技能脚本运行环境 · 未检测到 Python（技能脚本需要 Python 3），点右侧「安装」自动装官方版本（python.org）'
           : '技能脚本运行环境 · 未检测到 Python，可用系统包管理器安装（如 brew install python）后重启 dsh')
-      + '</div></div></div>'
+      + '</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);
   });
@@ -667,11 +672,12 @@ const cliAuthDialog = async (tool) => {
   }
 };
 
-/** CLI 一键安装：lark 走 npm 全局安装、ccpg 走官方安装脚本，耗时可达
- * 分钟级。响应自带安装后立即探测的单工具详情，直接合进缓存刷新界面。 */
+/** CLI 一键安装：lark 走 npm 全局安装（机器无 Node.js 时先自动补装）、
+ * ccpg/python 走官方安装器，耗时可达数分钟。响应自带安装后立即探测的
+ * 详情，直接合进缓存刷新界面。 */
 const cliInstall = async (tool, btn) => {
   btn.disabled = true;
-  btn.textContent = '安装中，可能需要 1–3 分钟…';
+  btn.textContent = '安装中，可能需要 3–5 分钟…';
   try {
     const resp = await fetch('api/cli/install', {
       method: 'POST',
@@ -681,7 +687,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);

package/lib/proc.js

@@ -2,12 +2,13 @@
 //
 // 官方 `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, rmSync } 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);
@@ -26,9 +27,57 @@ function extraBinDirs() {
   if (process.platform === 'win32') {
     const appData = process.env.APPDATA || join(home, 'AppData', 'Roaming');
     const localAppData = process.env.LOCALAPPDATA || join(home, 'AppData', 'Local');
-    // npm -g 默认 prefix 与 pnpm 默认 PNPM_HOME；nodejs.org 安装器的
-    // 系统级安装不在这，但那种环境 PATH 里有 node，不需要兑底。
-    dirs.push(join(appData, 'npm'), join(localAppData, 'pnpm'));
+    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）+ 本插件一键补装的
+    // 用户级安装位（%LOCALAPPDATA%\Programs\nodejs，免管理员）。
+    dirs.push(
+      join(programFiles, 'nodejs'),
+      join(programFilesX86, 'nodejs'),
+      join(localAppData, 'Programs', '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
@@ -44,25 +93,29 @@ function extraBinDirs() {
   }
   // DSH Desktop 自带的 node/pnpm/dsh shim（Electron 当 node 用）：宿主只把
   // 这目录注入桌面终端的 PATH，插件子进程看不到——不兑底的话 dsh 自身有
-  // node 环境但 lark-cli 安装仍报「未找到 npm」。目录名是 profile 的 hash，
-  // 扫一层取含 bin 的子目录。Windows 桌面版把 shim 放在
-  // %LOCALAPPDATA%\\DSH Desktop\\shims（按官方约定），一并覆盖。
-  try {
-    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 {
-    // 非 macOS / 未生成终端 shim：跳过
-  }
-  if (process.platform === 'win32') {
+  // node 环境但 lark-cli 安装仍报「未找到 npm」。macOS 位
+  // ~/Library/Application Support/DSH Desktop/cli/<profile hash>/bin；
+  // Windows 实测在 Roaming 下（真实用户机报错的命令路径前缀就是
+  // C:\Users\<user>\AppData\Roaming\DSH…），Local 也一并扫。两种布局都
+  // 兼容：shims/ 直挂、cli/<hash>/bin。
+  const desktopRoots = process.platform === 'win32'
+    ? [
+      join(process.env.APPDATA || join(home, 'AppData', 'Roaming'), 'DSH Desktop'),
+      join(process.env.LOCALAPPDATA || join(home, 'AppData', 'Local'), 'DSH Desktop'),
+    ]
+    : [join(home, 'Library', 'Application Support', 'DSH Desktop')];
+  for (const root of desktopRoots) {
     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);
+      const shimDir = join(root, 'shims');
+      if (existsSync(join(shimDir, 'node')) || existsSync(join(shimDir, 'node.exe')) || existsSync(join(shimDir, 'node.cmd'))) {
+        dirs.push(shimDir);
+      }
+      for (const entry of readdirSync(join(root, 'cli'))) {
+        const shimBin = join(root, 'cli', entry, 'bin');
+        if (existsSync(join(shimBin, 'node')) || existsSync(join(shimBin, 'node.exe')) || existsSync(join(shimBin, 'node.cmd'))) {
+          dirs.push(shimBin);
+        }
+      }
     } catch {
       // 目录不存在：跳过
     }
@@ -71,17 +124,82 @@ function extraBinDirs() {
   return dirs;
 }
 
+/** 安装完成后清空兑底目录缓存：一键安装 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 解释。
+ * 形态必须整行单参数 + 外层引号 + windowsVerbatimArguments（与 Node
+ * shell:true 的内部构造一致）：逐参数传数组时，含空格路径（如
+ * "C:\Users\x\AppData\Roaming\DSH Desktop\shims\npm.cmd"）会被 cmd /s 的
+ * 引号剥离规则在空格处拆断，报「不是内部或外部命令」（真实用户机实测）。
+ * 参数不拼接用户输入（白名单 tool + 固定 flag + 校验过的设备码/URL）。 */
+export function cmdShimInvocation(platform, resolved, args) {
+  if (platform !== 'win32') return null;
+  if (!/\.(cmd|bat)$/i.test(resolved)) return null;
+  const quote = (s) => (/[\s"]/.test(s) ? `"${String(s).replace(/"/g, '""')}"` : String(s));
+  const line = [resolved, ...args].map(quote).join(' ');
+  return { file: 'cmd.exe', args: ['/d', '/s', '/c', `"${line}"`], verbatim: true };
+}
+
+/** 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 suffixes = candidateSuffixes(process.platform);
+  for (const dir of [...pathDirs, ...extraBinDirs()]) {
+    for (const suffix of suffixes) {
+      const candidate = join(dir, tool + suffix);
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+/** 与 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 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) && !seen.has(candidate)) {
+        seen.add(candidate);
+        out.push(candidate);
+      }
+    }
   }
-  return candidates.find((p) => existsSync(p)) || null;
+  return out;
 }
 
 /** 兼容旧签名：找不到时返回原名（后续 ENOENT 走既有 missing/降级语义）。 */
@@ -89,21 +207,55 @@ export function resolveCommand(tool) {
   return resolveCommandOrNull(tool) || tool;
 }
 
-/** 统一的子进程执行：解析命令路径，并把解析到的目录前置进子进程 PATH
- * （pnpm/lark-cli 等是 `#!/usr/bin/env node` 脚本，宿主 PATH 贫瘠时
- * 找得到脚本也找不到 node，必须连带注入）。opts.env 只传增量变量。 */
+/** 子进程输出解码（纯函数，供测试）：Windows 中文系统的 cmd/批处理内部
+ * 错误是 GBK 编码（如「'xx' 不是内部或外部命令」），而 npm/node 自身输出
+ * 是 UTF-8——先按 UTF-8 严格解码，失败退化 GBK，乱码（♦/锟斤拷）不进
+ * 用户可见的错误提示。 */
+export function decodeOutput(buf) {
+  const bytes = Buffer.isBuffer(buf) ? buf : Buffer.from(String(buf ?? ''));
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    try {
+      return new TextDecoder('gbk').decode(bytes);
+    } catch {
+      return bytes.toString('utf-8');
+    }
+  }
+}
+
+/** 统一的子进程执行：解析命令路径，并把**所有兑底目录**前置进子进程
+ * PATH——win32 下 npm/lark-cli 是 .cmd shim（`%~dp0\node.exe` 找 node），
+ * node 可能在另一个兑底目录（nodejs.org 系统安装位）；.cmd 又经
+ * 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);
   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,
     env: childEnv,
-  });
+    encoding: 'buffer',
+    windowsVerbatimArguments: shim?.verbatim === true,
+  }).then(
+    ({ stdout, stderr }) => ({ stdout: decodeOutput(stdout), stderr: decodeOutput(stderr) }),
+    (error) => {
+      if (error && (error.stdout !== undefined || error.stderr !== undefined)) {
+        error.stdout = decodeOutput(error.stdout);
+        error.stderr = decodeOutput(error.stderr);
+      }
+      throw error;
+    },
+  );
 }
 
 /** 从 pnpm 冗长输出里提取对用户有意义的错误行。 */
@@ -174,6 +326,11 @@ function missingCommandGuidance(tool) {
   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} 命令，请确认已安装`;
 }
 
@@ -326,6 +483,31 @@ async function cliLatestVersion(tool, timeoutMs) {
   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';
@@ -360,17 +542,22 @@ 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') {
     // 预检+降级链：优先独立 npm；没有 npm 但有 pnpm（含 DSH Desktop 自带
-    // shim）时用 pnpm 全局装——lark-cli 官方支持 pnpm 安装方式，装出来的
-    // 二进制与 npm 路径一致，后续 lark-cli update 也能自升级。
-    // 两者都没有才报「装 Node.js」指引。
+    // shim）时用 pnpm 全局装；两者都没有时 Windows 先一键补装 Node.js
+    // （用户目录免管理员，npmmirror 镜像），再用其自带 npm 装 lark-cli。
+    // lark-cli 官方支持 pnpm 安装方式，装出来的二进制与 npm 路径一致，
+    // 后续 lark-cli update 也能自升级。
     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 if (process.platform === 'win32') {
+      const nodeNote = await installNodeWindows(timeoutMs);
+      ({ stdout } = await runCliTool('npm', ['install', '-g', '@larksuite/cli@latest'], { timeoutMs }));
+      stdout = `${nodeNote}\n${stdout}`;
     } else {
       throw new Error(missingCommandGuidance('npm'));
     }
@@ -399,6 +586,12 @@ export async function installCliTool(tool, { timeoutMs = 300_000 } = {}) {
         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 工具');
   }
@@ -406,44 +599,206 @@ export async function installCliTool(tool, { timeoutMs = 300_000 } = {}) {
   return lines.slice(-6).join('\n');
 }
 
-/** ccpg-cli Windows 安装（官方教程口径，202607151817）：
- * 1) Windows 10 1803+ 自带 curl.exe 下载官方自安装 exe
- *    （https://bms.einwin.com/media/ccpg-cli/202607151817/ccpg-cli-windows-amd64.exe）
- * 2) 静默运行安装（/S 安静模式，装到用户目录并注册 PATH）
- * 3) 教程要求装完必须 ccpg-cli update（拉最新功能）——自动补上。
+/** 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_WINDOWS_INSTALLER_URL = 'https://bms.einwin.com/media/ccpg-cli/202607151817/ccpg-cli-windows-amd64.exe';
+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 tempDir = join(homedir(), 'AppData', 'Local', 'Temp');
-  const installer = join(tempDir, 'ccpg-cli-setup.exe');
+  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', '300',
-    '-o', installer, CCPG_CLI_WINDOWS_INSTALLER_URL,
+    '-fsSL', '--retry', '3', '--retry-delay', '5', '--max-time', '600',
+    '--speed-limit', '65536', '--speed-time', '30',
+    '-o', staging, url,
   ], { timeoutMs });
-  // NSIS 风格安装器：/S 静默安装；退出码非 0 视为失败
-  await runCliTool(installer, ['/S'], { timeoutMs });
-  // 官方教程的必做步骤：安装完成后立即自升级到最新版（软失败不阻断）
-  const updateNote = await runCliTool('ccpg-cli', ['update'], { timeoutMs: 120_000 })
+  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 安装完成\n${updateNote}\n如命令不可用，请重启 DSH Desktop 后点「重新检测」`,
+    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 后点「重新检测」`,
   };
 }
 
+/** Node.js Windows 一键补装（lark-cli 的运行时依赖：机器无 node/npm/pnpm
+ * 时自动补，用户不再被要求「先自行安装 Node.js」）：
+ * 1) npmmirror 二进制镜像优先（官网 nodejs.org 国内慢/不稳），失败退官网；
+ *    zip 包绿色解压，不走 MSI（免管理员/UAC）
+ * 2) 解压到 %LOCALAPPDATA%\Programs\nodejs（与 python.org 每用户安装同
+ *    级的标准位置），写用户 PATH（注册表 User 作用域）
+ * 3) npm 全局 prefix 即该目录，后续装的 lark-cli 也落这里——兑底目录已
+ *    覆盖，装完本进程内即可探测
+ * 全程 execFile 参数数组，不经 shell。 */
+const NODE_WINDOWS_VERSION = 'v22.17.0';
+const NODE_WINDOWS_ZIP_URLS = [
+  `https://registry.npmmirror.com/-/binary/node/${NODE_WINDOWS_VERSION}/node-${NODE_WINDOWS_VERSION}-win-x64.zip`,
+  `https://nodejs.org/dist/${NODE_WINDOWS_VERSION}/node-${NODE_WINDOWS_VERSION}-win-x64.zip`,
+];
+
+async function installNodeWindows(timeoutMs) {
+  const localAppData = process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local');
+  const programsDir = join(localAppData, 'Programs');
+  const nodeHome = join(programsDir, 'nodejs');
+  const zip = join(tmpdir(), 'node-setup.zip');
+  let downloaded = false;
+  let lastError = null;
+  for (const url of NODE_WINDOWS_ZIP_URLS) {
+    try {
+      await runCliTool('curl', [
+        '-fsSL', '--retry', '2', '--retry-delay', '3', '--max-time', '600',
+        '--speed-limit', '65536', '--speed-time', '30',
+        '-o', zip, url,
+      ], { timeoutMs });
+      downloaded = true;
+      break;
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  if (!downloaded) throw lastError || new Error('Node.js 安装包下载失败，请检查网络后重试');
+  mkdirSync(programsDir, { recursive: true });
+  // PowerShell Expand-Archive（Win10+ 自带）。路径单引号内嵌转义防空格/引号
+  const psQuote = (p) => `'${p.replace(/'/g, "''")}'`;
+  await runCliTool('powershell', [
+    '-NoProfile', '-Command',
+    `Expand-Archive -LiteralPath ${psQuote(zip)} -DestinationPath ${psQuote(programsDir)} -Force`,
+  ], { timeoutMs });
+  // zip 内层目录名 node-vX.Y.Z-win-x64 → 平铺为 nodejs（重装时先清旧目录）
+  rmSync(nodeHome, { recursive: true, force: true });
+  renameSync(join(programsDir, `node-${NODE_WINDOWS_VERSION}-win-x64`), nodeHome);
+  rmSync(zip, { force: true });
+  await ensureUserPathContains(nodeHome).catch(() => {});
+  resetExtraBinDirsCache();
+  return `Node.js ${NODE_WINDOWS_VERSION} 安装完成（${nodeHome}）`;
+}
+
 /**
  * 触发 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.22",
+  "version": "0.5.24",
   "description": "AgentOne 平台集成插件：飞书登录、平台模型（同步失败自愈重试）、SkillHub 技能（升级检测一键升级、装后即时刷新、套餐技能自动同步）、套餐申请、插件管理与自助升级、lark-cli / ccpg-cli 探测与一键安装（请求超时与错误码透传、令牌轮换 single-flight、凭据损坏容错与并发安全写入、状态页 UX 增强）",
   "type": "module",
   "main": "lib/index.js",