@cicctencent/agent-core 1.0.32 → 1.0.34

package/dist/esm/utils/python-command.js

@@ -6,37 +6,51 @@
  *   没有 `python3`。此前该命令名散落在多处硬编码（local-sandbox、skill-resources、
  *   mcp-config.helper 等），导致「本机只有 python 没有 python3」时部分入口直接 ENOENT 失败。
  *
+ *   Windows 还存在「应用执行别名」陷阱：Microsoft Store 会在 PATH 中注入一个 0 字节的
+ *   `python3.exe` 占位壳（AppInstallerPythonRedirector.exe），`where`/`command -v` 能找到它，
+ *   但调用时并不执行脚本（静默退出码 49，无任何 stdout/stderr）。因此**探测必须以"实际试跑"为准**，
+ *   而非仅检查名字是否在 PATH 中可解析，否则会误判该假壳"可用"。
+ *
  *   本模块把「探测可用 Python 命令」内聚到唯一来源：
- *   - 优先尝试 `python3`，回退 `python`；
+ *   - 候选顺序 `python3` → `python` → `py -3`（py -3 指向 Windows Store / 系统已注册的 Python 3）；
+ *   - 每个候选均通过"实际运行一条验证语句"判定可用，过滤掉 Store 假壳；
  *   - 探测结果进程内缓存，避免每次 spawn 重复探测；
- *   - 跨平台兼容（Windows 用 where，POSIX 用 command -v）；
- *   - 若两者都不可用，返回默认 `python3` 并让上层 spawn 时暴露明确 ENOENT 错误。
+ *   - 若全部不可用，返回默认 `python3` 并让上层 spawn 时暴露明确 ENOENT 错误。
  */
 import { spawn, spawnSync } from 'child_process';
 /** 候选命令的优先级顺序（越靠前越优先） */
-const PYTHON_CANDIDATES = ['python3', 'python'];
-/** 探测时使用的最小命令：仅检查命令是否在 PATH 中可解析，能解析即视为可用 */
+const PYTHON_CANDIDATES = ['python3', 'python', 'py -3'];
+/**
+ * 通过"实际试跑"判定候选命令是否真的能执行 Python 代码。
+ * 仅用 `where`/`command -v` 会命中 Windows Store 的 0 字节占位壳，故必须以真实执行为准。
+ * 直接以 args 数组形式 spawn 解释器（不经由 cmd /c 包装），避免引号被 shell 二次解析导致
+ * 误判；store 占位壳被直接运行时退出非 0 或产出不了版本号，从而被过滤。
+ * @param candidate 候选命令（可能含空格，如 `py -3`）
+ */
 function probeCommand(candidate) {
     return new Promise((resolve) => {
-        const detacher = process.platform === 'win32'
-            ? spawn('cmd', ['/c', 'where', candidate], { windowsHide: true })
-            : spawn('sh', ['-c', `command -v ${candidate} 2>/dev/null`], { timeout: 5000 });
-        let found = false;
-        detacher.stdout?.on('data', (d) => {
-            if (d.toString().trim().length > 0)
-                found = true;
-        });
+        const parts = candidate.split(' ');
+        const bin = parts[0];
+        const args = [...parts.slice(1), '-c', 'import sys; print(sys.version.split()[0])'];
+        const detacher = spawn(bin, args, { windowsHide: true, timeout: 5000 });
+        let out = '';
+        detacher.stdout?.on('data', (d) => { out += d.toString(); });
         detacher.on('error', () => resolve(false));
-        detacher.on('close', (code) => resolve(code === 0 && found));
+        detacher.on('close', (code) => {
+            // 退出 0 且能产出预期的版本号字符串，才视为真实可用
+            resolve(code === 0 && /\d+\.\d+/.test(out.trim()));
+        });
     });
 }
 /** 同步探测版本（供无法使用 await 的同步上下文，如 buildMCPConfig 复用同一缓存与候选顺序） */
 function probeCommandSync(candidate) {
     try {
-        const result = process.platform === 'win32'
-            ? spawnSync('cmd', ['/c', 'where', candidate], { windowsHide: true })
-            : spawnSync('sh', ['-c', `command -v ${candidate} 2>/dev/null`], { timeout: 5000 });
-        return result.status === 0 && (result.stdout?.toString().trim().length ?? 0) > 0;
+        const parts = candidate.split(' ');
+        const bin = parts[0];
+        const args = [...parts.slice(1), '-c', 'import sys; print(sys.version.split()[0])'];
+        const result = spawnSync(bin, args, { windowsHide: true, timeout: 5000 });
+        const out = result.stdout?.toString() ?? '';
+        return result.status === 0 && /\d+\.\d+/.test(out.trim());
     }
     catch {
         return false;
@@ -45,7 +59,7 @@ function probeCommandSync(candidate) {
 let cachedCommand = null;
 /**
  * 解析当前环境可用的 Python 可执行命令名（带缓存）。
- * 优先 `python3`，回退 `python`，两者皆不可用时回退默认 `python3`。
+ * 优先 `python3`，回退 `python`，再回退 `py -3`，全部不可用则返回默认 `python3`。
  */
 export async function resolvePythonCommand() {
     if (cachedCommand)
@@ -56,7 +70,7 @@ export async function resolvePythonCommand() {
             return cachedCommand;
         }
     }
-    // 都不存在：返回常用默认名，由上层 spawn 暴露明确的「命令未找到」错误
+    // 都不存在（或全是 Store 假壳）：返回常用默认名，由上层 spawn 暴露明确的「命令未找到」错误
     cachedCommand = 'python3';
     return cachedCommand;
 }
@@ -80,4 +94,15 @@ export function resolvePythonCommandSync() {
     cachedCommand = 'python3';
     return cachedCommand;
 }
+/**
+ * 当所有候选均不可用时，给出的可操作排查建议（尤其针对 Windows 应用执行别名陷阱）。
+ */
+export const PYTHON_UNAVAILABLE_HINT = [
+    '未找到可用的 Python 解释器。排查建议：',
+    '  - Windows：若 `python3` 指向 Microsoft Store 的"应用执行别名"占位壳，请到',
+    '    设置 → 应用 → 应用执行别名 中关闭 python3/python 的别名开关，改从 python.org 安装并勾选 "Add to PATH"；',
+    '  - 或确保 `python` / `py -3` 命令可用（Python Launcher for Windows 默认提供 `py`）；',
+    '  - Linux/macOS：apt-get install -y python3 / brew install python3。',
+    '请运维在运行 agent-server 的主机上安装对应解释器后重试。',
+].join('\n');
 //# sourceMappingURL=python-command.js.map

package/dist/esm/utils/python-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"python-command.js","sourceRoot":"","sources":["../../../src/utils/python-command.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"python-command.js","sourceRoot":"","sources":["../../../src/utils/python-command.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cicctencent/agent-core",
-  "version": "1.0.32",
+  "version": "1.0.34",
   "description": "Core engine for AI agent — LLM orchestration, tool execution, MCP, skill routing, security, and memory pipeline.",
   "type": "module",
   "main": "./dist/cjs/index.js",