evolcore 0.0.1 → 0.0.2

package/dist/utils/logger.js

@@ -0,0 +1,89 @@
+import fs from 'fs';
+import { resolvePaths } from '../paths.js';
+import { LogWriter } from './log-writer.js';
+let currentLevel = process.env.LOG_LEVEL || 'INFO';
+const LEVELS = { DEBUG: 0, INFO: 1, WARN: 2, ERROR: 3 };
+const config = {
+    messageLog: process.env.MESSAGE_LOG === 'true',
+    eventLog: process.env.EVENT_LOG === 'true'
+};
+let writers = null;
+fs.mkdirSync(resolvePaths().logs, { recursive: true });
+function closeWriters(current) {
+    current.main.close();
+    current.message?.close();
+    current.event?.close();
+    current.channelIn.close();
+    current.channelOut.close();
+}
+function getWriters() {
+    const logDir = resolvePaths().logs;
+    if (writers?.logDir === logDir)
+        return writers;
+    if (writers)
+        closeWriters(writers);
+    writers = {
+        logDir,
+        main: new LogWriter({ baseName: 'daemon', logDir, rotation: 'hourly', retention: { hours: 24 } }),
+        message: config.messageLog
+            ? new LogWriter({ baseName: 'messages', logDir, rotation: 'hourly', retention: { hours: 24 } })
+            : null,
+        event: config.eventLog
+            ? new LogWriter({ baseName: 'events', logDir, rotation: 'hourly', retention: { hours: 24 } })
+            : null,
+        channelIn: new LogWriter({ baseName: 'channel-in', logDir, rotation: 'hourly', retention: { hours: 24 } }),
+        channelOut: new LogWriter({ baseName: 'channel-out', logDir, rotation: 'hourly', retention: { hours: 24 } }),
+    };
+    return writers;
+}
+function shouldLog(level) {
+    return (LEVELS[level] ?? 1) >= (LEVELS[currentLevel] ?? 1);
+}
+export function localTimestamp() {
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${String(d.getMilliseconds()).padStart(3, '0')}`;
+}
+function log(level, ...args) {
+    if (!shouldLog(level))
+        return;
+    const msg = `[${localTimestamp()}] [${level}] ${args.join(' ')}`;
+    getWriters().main.write(msg);
+}
+/**
+ * 设置日志级别（config 加载后调用，覆盖环境变量默认值）
+ * 优先级：config.debug.logLevel → LOG_LEVEL 环境变量 → 'INFO'
+ */
+export function setLogLevel(level) {
+    const upper = level.toUpperCase();
+    if (upper in LEVELS) {
+        currentLevel = upper;
+    }
+}
+export function getLogLevel() {
+    return currentLevel;
+}
+export const logger = {
+    debug: (...args) => log('DEBUG', ...args),
+    info: (...args) => log('INFO', ...args),
+    warn: (...args) => log('WARN', ...args),
+    error: (...args) => log('ERROR', ...args),
+    message: (data) => {
+        const writer = getWriters().message;
+        if (!writer)
+            return;
+        writer.write(JSON.stringify({ ts: localTimestamp(), ...data }));
+    },
+    event: (data) => {
+        const writer = getWriters().event;
+        if (!writer)
+            return;
+        writer.write(JSON.stringify({ ts: localTimestamp(), ...data }));
+    },
+    channelIn: (data) => {
+        getWriters().channelIn.write(JSON.stringify({ ts: localTimestamp(), ...data }));
+    },
+    channelOut: (data) => {
+        getWriters().channelOut.write(JSON.stringify({ ts: localTimestamp(), ...data }));
+    }
+};

package/dist/utils/markdown-to-plain-text.js

@@ -0,0 +1,20 @@
+export function markdownToPlainText(text) {
+    let result = text;
+    result = result.replace(/```[^\n]*\n?([\s\S]*?)```/g, (_, code) => code.trim());
+    result = result.replace(/!\[[^\]]*\]\([^)]*\)/g, '');
+    result = result.replace(/\[([^\]]+)\]\([^)]*\)/g, '$1');
+    result = result.replace(/^\|[\s:|-]+\|$/gm, '');
+    result = result.replace(/^\|(.+)\|$/gm, (_, inner) => inner.split('|').map(cell => cell.trim()).join('  '));
+    result = result.replace(/\*\*(.+?)\*\*/g, '$1');
+    result = result.replace(/\*(.+?)\*/g, '$1');
+    result = result.replace(/__(.+?)__/g, '$1');
+    result = result.replace(/_(.+?)_/g, '$1');
+    result = result.replace(/~~(.+?)~~/g, '$1');
+    result = result.replace(/`([^`]+)`/g, '$1');
+    result = result.replace(/^#{1,6}\s+/gm, '');
+    result = result.replace(/^>\s?/gm, '');
+    result = result.replace(/^[-*_]{3,}$/gm, '');
+    result = result.replace(/^(\s*)[-*+]\s/gm, '$1');
+    result = result.replace(/^(\s*)\d+\.\s/gm, '$1');
+    return result.trim();
+}

package/dist/utils/media-cache.js

@@ -0,0 +1,271 @@
+/**
+ * 统一媒体下载/缓存/SSRF防护框架
+ *
+ * 提供跨通道复用的文件处理能力：
+ * - 文件保存到 uploads 目录（自动去重、文件名清洗）
+ * - 图片类型白名单 + 大小限制
+ * - URL SSRF 防护（域名白名单 + 私有 IP 拦截）
+ * - 下载缓存（相同 key 不重复下载）
+ */
+import path from 'path';
+import fs from 'fs';
+import crypto from 'crypto';
+import { logger } from './logger.js';
+// ── 常量 ──────────────────────────────────────────────────────────────────────
+const DEFAULT_MAX_IMAGE_SIZE = 10 * 1024 * 1024; // 10 MB
+const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024; // 100 MB
+const ALLOWED_IMAGE_MIMES = new Set([
+    'image/png', 'image/jpeg', 'image/gif', 'image/webp',
+]);
+const UPLOADS_SUBDIR = '.evolcore/uploads';
+// ── SSRF 防护 ─────────────────────────────────────────────────────────────────
+/** 已知安全的 CDN 域名白名单 */
+const ALLOWED_CDN_HOSTS = new Set([
+    'novac2c.cdn.weixin.qq.com',
+    'open.feishu.cn',
+    'internal-api-lark-file.feishu.cn',
+    'oapi.dingtalk.com',
+    'api.dingtalk.com',
+]);
+/** 私有 IP 段正则（IPv4） */
+const PRIVATE_IP_RE = /^(10\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.|127\.|0\.|169\.254\.|::1|fc|fd|fe80)/;
+/**
+ * 检查 URL 是否安全（非 SSRF）
+ * - 拒绝私有 IP
+ * - 仅允许 https（或白名单域名的 http）
+ * - 可选：域名白名单模式
+ */
+export function validateUrl(url, opts) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { ok: false, reason: `Invalid URL: ${url}` };
+    }
+    // 协议检查
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        return { ok: false, reason: `Blocked protocol: ${parsed.protocol}` };
+    }
+    // 私有 IP 检查
+    const host = parsed.hostname;
+    if (PRIVATE_IP_RE.test(host)) {
+        return { ok: false, reason: `Blocked private IP: ${host}` };
+    }
+    // 域名白名单（如果提供）
+    const allowed = opts?.allowedHosts ?? ALLOWED_CDN_HOSTS;
+    if (allowed.size > 0 && !allowed.has(host)) {
+        return { ok: false, reason: `Host not in allowlist: ${host}` };
+    }
+    return { ok: true };
+}
+// ── 文件名清洗 ────────────────────────────────────────────────────────────────
+/**
+ * 清洗文件名：
+ * - 移除路径穿越字符（只保留 basename）
+ * - 替换非法字符
+ * - 空结果兜底
+ */
+export function sanitizeFileName(name) {
+    return path.basename(name).replace(/[<>:"|?*\x00-\x1f]/g, '_') || `file_${Date.now()}`;
+}
+// ── 图片验证 ──────────────────────────────────────────────────────────────────
+/**
+ * 验证图片 Buffer：类型白名单 + 大小限制
+ * 返回检测到的 MIME 类型，验证失败返回 null + reason
+ */
+export async function validateImage(buffer, opts) {
+    const maxSize = opts?.maxSize ?? DEFAULT_MAX_IMAGE_SIZE;
+    const allowed = opts?.allowedMimes ?? ALLOWED_IMAGE_MIMES;
+    if (buffer.length === 0) {
+        return { mime: null, reason: 'Empty buffer' };
+    }
+    if (buffer.length > maxSize) {
+        return { mime: null, reason: `Image too large: ${buffer.length} bytes (max ${maxSize})` };
+    }
+    // 动态导入 image-type（ESM only）
+    const { default: imageType } = await import('image-type');
+    // image-type 对极短/截断的 buffer 会抛 EndOfStreamError，捕获后按「无法识别」处理。
+    let type;
+    try {
+        type = await imageType(buffer);
+    }
+    catch (e) {
+        return { mime: null, reason: `Image type detection error: ${e.message}` };
+    }
+    if (!type) {
+        return { mime: null, reason: 'Unable to detect image type' };
+    }
+    if (!allowed.has(type.mime)) {
+        return { mime: null, reason: `Unsupported image type: ${type.mime}` };
+    }
+    return { mime: type.mime };
+}
+/**
+ * 把已下载的附件 Buffer 转成入站图片条目（供 baseagent 视觉通道）。
+ *
+ * 适用于所有「需要先下载再注入」的通道（AUN ticket 下载、未来其它 CDN 下载等）。
+ * 飞书/微信已有各自的 SDK 下载路径，可按需复用本函数统一 MIME 判定。
+ *
+ * 判定优先级：
+ *   1. magic bytes（image-type 库，最可靠，同时做大小/白名单校验）
+ *   2. 元数据 MIME 字段（att.content_type / mime_type / mimeType）
+ *   3. 文件名后缀
+ *
+ * @returns 是图片返回 InboundImage；非图片或校验失败返回 null。
+ */
+export async function bufferToInboundImage(buffer, hints) {
+    // 1. magic bytes（含大小 + 白名单校验；validateImage 已吞掉 image-type 的异常）
+    const validated = await validateImage(buffer);
+    if (validated.mime) {
+        return { data: buffer.toString('base64'), mimeType: validated.mime };
+    }
+    // 2/3. magic bytes 未识别时，回退到元数据字段 / 文件名后缀
+    //      （仍受 image 白名单约束，避免把任意文件当图片注入）
+    const metaCt = hints?.contentType || hints?.mimeType || '';
+    const byMeta = typeof metaCt === 'string' && ALLOWED_IMAGE_MIMES.has(metaCt) ? metaCt : '';
+    const byExt = hints?.filename
+        ? (ALLOWED_IMAGE_MIMES.has(guessMime(hints.filename)) ? guessMime(hints.filename) : '')
+        : '';
+    const fallback = byMeta || byExt;
+    if (fallback && buffer.length > 0 && buffer.length <= DEFAULT_MAX_IMAGE_SIZE) {
+        return { data: buffer.toString('base64'), mimeType: fallback };
+    }
+    return null;
+}
+/**
+ * 保存 Buffer 到 uploads 目录
+ * - 自动创建目录
+ * - 文件名清洗
+ * - 同名文件自动添加时间戳后缀
+ */
+export function saveToUploads(buffer, rawFileName, projectPath, opts) {
+    const fileName = sanitizeFileName(rawFileName);
+    const uploadsDir = path.join(projectPath, UPLOADS_SUBDIR);
+    fs.mkdirSync(uploadsDir, { recursive: true });
+    let targetName = fileName;
+    const targetPath = path.join(uploadsDir, targetName);
+    // 去重：内容相同则复用
+    if (opts?.dedup !== false && fs.existsSync(targetPath)) {
+        const existingHash = hashFile(targetPath);
+        const newHash = crypto.createHash('md5').update(buffer).digest('hex');
+        if (existingHash === newHash) {
+            logger.debug(`[MediaCache] Dedup hit: ${targetName}`);
+            return { filePath: targetPath, fileName: targetName, size: buffer.length };
+        }
+        // 不同内容同名 → 加时间戳
+        const ext = path.extname(fileName);
+        const base = path.basename(fileName, ext);
+        targetName = `${base}_${Date.now()}${ext}`;
+    }
+    const finalPath = path.join(uploadsDir, targetName);
+    fs.writeFileSync(finalPath, buffer);
+    logger.info(`[MediaCache] Saved: ${finalPath} (${buffer.length} bytes)`);
+    return { filePath: finalPath, fileName: targetName, size: buffer.length };
+}
+function hashFile(filePath) {
+    const content = fs.readFileSync(filePath);
+    return crypto.createHash('md5').update(content).digest('hex');
+}
+/**
+ * 安全下载 URL 内容，带 SSRF 防护
+ */
+export async function safeFetch(url, opts) {
+    const maxSize = opts?.maxSize ?? DEFAULT_MAX_FILE_SIZE;
+    const timeout = opts?.timeout ?? 30_000;
+    // SSRF 检查
+    if (!opts?.skipSsrfCheck) {
+        const check = validateUrl(url, { allowedHosts: opts?.allowedHosts });
+        if (!check.ok) {
+            throw new Error(`SSRF blocked: ${check.reason}`);
+        }
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+        const res = await fetch(url, { signal: controller.signal });
+        if (!res.ok)
+            throw new Error(`Download failed: ${res.status} ${res.statusText}`);
+        // 检查 Content-Length（如果可用）
+        const contentLength = res.headers.get('content-length');
+        if (contentLength && parseInt(contentLength) > maxSize) {
+            throw new Error(`File too large: ${contentLength} bytes (max ${maxSize})`);
+        }
+        const buffer = Buffer.from(await res.arrayBuffer());
+        if (buffer.length > maxSize) {
+            throw new Error(`File too large: ${buffer.length} bytes (max ${maxSize})`);
+        }
+        return buffer;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * 内存级下载缓存
+ * - 相同 key 不重复下载
+ * - TTL 过期自动清理
+ * - 最大条目限制防止内存泄漏
+ */
+export class DownloadCache {
+    cache = new Map();
+    ttlMs;
+    maxEntries;
+    constructor(opts) {
+        this.ttlMs = opts?.ttlMs ?? 5 * 60 * 1000; // 5 min
+        this.maxEntries = opts?.maxEntries ?? 100;
+    }
+    /**
+     * 获取或下载：缓存命中直接返回，否则执行 fetcher 并缓存结果
+     */
+    async getOrFetch(key, fetcher) {
+        this.evict();
+        const cached = this.cache.get(key);
+        if (cached) {
+            logger.debug(`[DownloadCache] Hit: ${key}`);
+            return cached.buffer;
+        }
+        const buffer = await fetcher();
+        this.cache.set(key, { buffer, createdAt: Date.now() });
+        // 超过 maxEntries 时删最旧
+        if (this.cache.size > this.maxEntries) {
+            const oldest = this.cache.keys().next().value;
+            this.cache.delete(oldest);
+        }
+        return buffer;
+    }
+    evict() {
+        const now = Date.now();
+        for (const [key, entry] of this.cache) {
+            if (now - entry.createdAt > this.ttlMs) {
+                this.cache.delete(key);
+            }
+        }
+    }
+    clear() {
+        this.cache.clear();
+    }
+}
+// ── MIME / Size helpers ──────────────────────────────────────────────────────
+const MIME_MAP = {
+    '.txt': 'text/plain', '.md': 'text/markdown', '.json': 'application/json',
+    '.js': 'text/javascript', '.ts': 'text/typescript', '.py': 'text/x-python',
+    '.html': 'text/html', '.css': 'text/css', '.csv': 'text/csv',
+    '.pdf': 'application/pdf', '.zip': 'application/zip', '.gz': 'application/gzip',
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml',
+    '.xml': 'application/xml', '.yaml': 'application/x-yaml', '.yml': 'application/x-yaml',
+    '.mp4': 'video/mp4', '.mov': 'video/quicktime', '.webm': 'video/webm', '.avi': 'video/x-msvideo',
+    '.opus': 'audio/ogg', '.mp3': 'audio/mpeg', '.aac': 'audio/aac', '.m4a': 'audio/mp4', '.wav': 'audio/wav',
+};
+export function guessMime(filename) {
+    const ext = path.extname(filename).toLowerCase();
+    return MIME_MAP[ext] || 'application/octet-stream';
+}
+export function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1048576)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / 1048576).toFixed(1)} MB`;
+}

package/dist/utils/model-prices.jsonl

@@ -0,0 +1,17 @@
+{"model":"claude-opus-4-8","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":15,"price_output":75,"price_cache_creation":18.75,"price_cache_read":1.5}
+{"model":"claude-opus-4-7","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":15,"price_output":75,"price_cache_creation":18.75,"price_cache_read":1.5}
+{"model":"claude-opus-4-6","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":15,"price_output":75,"price_cache_creation":18.75,"price_cache_read":1.5}
+{"model":"claude-sonnet-4-6","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":3,"price_output":15,"price_cache_creation":3.75,"price_cache_read":0.3}
+{"model":"claude-haiku-4-5-20251001","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":0.8,"price_output":4,"price_cache_creation":1,"price_cache_read":0.08}
+{"model":"gpt-5.5","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":2,"price_output":10,"price_cache_creation":0,"price_cache_read":0}
+{"model":"gpt-5.4","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":2,"price_output":10,"price_cache_creation":0,"price_cache_read":0}
+{"model":"gpt-5.3-codex","effective_from":0,"billing_fn":"per_token_v1","currency":"USD","price_input":2,"price_output":10,"price_cache_creation":0,"price_cache_read":0}
+{"model":"deepseek-v4-pro","effective_from":0,"billing_fn":"per_token_deepseek_v1","currency":"CNY","price_cache_hit":0.5,"price_cache_miss":2,"price_output":8}
+{"model":"deepseek-v4-flash","effective_from":0,"billing_fn":"per_token_deepseek_v1","currency":"CNY","price_cache_hit":0.1,"price_cache_miss":0.5,"price_output":2}
+{"model":"deepseek-v3.2","effective_from":0,"billing_fn":"per_token_deepseek_v1","currency":"CNY","price_cache_hit":0.5,"price_cache_miss":2,"price_output":8}
+{"model":"kimi-k2.6","effective_from":0,"billing_fn":"per_token_v1","currency":"CNY","price_input":2,"price_output":8,"price_cache_creation":0,"price_cache_read":0}
+{"model":"kimi-k2.5","effective_from":0,"billing_fn":"per_token_v1","currency":"CNY","price_input":2,"price_output":8,"price_cache_creation":0,"price_cache_read":0}
+{"model":"glm-5.1","effective_from":0,"billing_fn":"per_token_v1","currency":"CNY","price_input":5,"price_output":20,"price_cache_creation":0,"price_cache_read":0}
+{"model":"glm-5","effective_from":0,"billing_fn":"per_token_v1","currency":"CNY","price_input":5,"price_output":20,"price_cache_creation":0,"price_cache_read":0}
+{"model":"glm-4.7","effective_from":0,"billing_fn":"per_token_v1","currency":"CNY","price_input":1,"price_output":5,"price_cache_creation":0,"price_cache_read":0}
+{"model":"MiniMax-M2.7","effective_from":0,"billing_fn":"per_token_v1","currency":"CNY","price_input":1,"price_output":5,"price_cache_creation":0,"price_cache_read":0}

package/dist/utils/npm-ops.js

@@ -0,0 +1,210 @@
+/**
+ * npm operations
+ *
+ * 集中管理本仓库所有 `npm install -g` / `npm view` 相关的子进程调用：
+ *  - tryUpgrade()       — evolcore 自我升级
+ *  - requireOptional()  — 可选依赖动态加载 + 自动安装
+ *  - npmInstallGlobal() — 全局安装（含 EACCES → sudo 回退、Windows npm.cmd）
+ */
+import fs from 'fs';
+import path from 'path';
+import { execFile, execSync } from 'child_process';
+import { promisify } from 'util';
+import { getPackageRoot } from '../paths.js';
+import { isWindows } from './cross-platform.js';
+const execFileAsync = promisify(execFile);
+// ── npm install -g (shared) ────────────────────────────────────────────────
+export async function npmInstallGlobal(pkg) {
+    let cmd;
+    let args;
+    // Windows: run via cmd /c to avoid shell:true deprecation warning on Node 22.
+    // Unix: npm directly, no shell needed.
+    if (isWindows) {
+        cmd = 'cmd';
+        args = ['/c', 'npm', 'install', '-g', pkg];
+    }
+    else {
+        cmd = 'npm';
+        args = ['install', '-g', pkg];
+    }
+    try {
+        await execFileAsync(cmd, args, { timeout: 180000 });
+    }
+    catch (e) {
+        if (e.stderr?.includes('EACCES') || e.message?.includes('EACCES')) {
+            if (isWindows) {
+                throw new Error('权限不足。请以管理员身份运行 PowerShell 或 CMD，然后重试');
+            }
+            await execFileAsync('sudo', ['npm', 'install', '-g', pkg], { timeout: 180000 });
+        }
+        else {
+            throw e;
+        }
+    }
+}
+/** Dynamic import with auto-install fallback for optional dependencies */
+export async function requireOptional(pkg, autoInstall = true) {
+    try {
+        return await import(pkg);
+    }
+    catch (e) {
+        if (e.code !== 'ERR_MODULE_NOT_FOUND' && e.code !== 'MODULE_NOT_FOUND')
+            throw e;
+        if (!autoInstall)
+            throw new Error(`依赖 ${pkg} 未安装。请运行: npm install -g ${pkg}`);
+        const { logger } = await import('./logger.js');
+        logger.info(`正在安装可选依赖 ${pkg}...`);
+        await npmInstallGlobal(pkg);
+        return await import(pkg);
+    }
+}
+/**
+ * 比较两个 semver 版本号 (a.b.c 格式)
+ * 返回 -1 (a < b), 0 (a == b), 1 (a > b)
+ * 自动剥离 pre-release 标签 (e.g. 2.6.0-beta.1 → 2.6.0)
+ */
+export function compareVersions(a, b) {
+    const pa = a.split('-')[0].split('.').map(Number);
+    const pb = b.split('-')[0].split('.').map(Number);
+    const len = Math.max(pa.length, pb.length);
+    for (let i = 0; i < len; i++) {
+        const na = pa[i] ?? 0;
+        const nb = pb[i] ?? 0;
+        if (na < nb)
+            return -1;
+        if (na > nb)
+            return 1;
+    }
+    return 0;
+}
+/**
+ * 检查当前安装是否为 npm link 开发模式。
+ * 正式全局安装的路径结构为 .../node_modules/evolcore，
+ * 而 npm link 指向项目源码目录，其父目录不是 node_modules。
+ */
+export function isLinkedInstall() {
+    const pkgRoot = getPackageRoot();
+    return path.basename(path.dirname(pkgRoot)) !== 'node_modules';
+}
+/** 获取本地 package.json 中的版本号 */
+export function getLocalVersion() {
+    const pkgPath = path.join(getPackageRoot(), 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    return pkg.version;
+}
+/**
+ * 解析全局安装包的已装版本（通过 `npm root -g` 定位全局 node_modules）。
+ * 用于 EC Web 这类独立全局命令包——它们不在主包的依赖树里。
+ * 未安装或查询失败返回 null。
+ */
+export function resolveGlobalPkg(pkgName) {
+    try {
+        // 命令完全静态（npm root -g，无用户输入），用 execSync 传完整命令字符串，
+        // 避免 "args 数组 + shell:true" 组合触发 Node DeprecationWarning，且无注入风险。
+        const npmCmd = isWindows ? 'npm.cmd' : 'npm';
+        const globalRoot = execSync(`${npmCmd} root -g`, {
+            encoding: 'utf-8', timeout: 10000,
+        }).trim();
+        const pkgPath = path.join(globalRoot, ...pkgName.split('/'), 'package.json');
+        if (fs.existsSync(pkgPath)) {
+            const data = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            return { version: data.version, path: pkgPath };
+        }
+    }
+    catch { /* not found */ }
+    return null;
+}
+/**
+ * 查询 npm registry 上指定包的最新版本。
+ * 使用 HTTP fetch 直接查 registry API，不依赖 npm CLI。
+ * 超时 10 秒，失败返回 null。
+ */
+export async function checkLatestVersion(pkg = 'evolcore') {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 10000);
+        const res = await fetch(`https://registry.npmjs.org/${pkg}/latest`, {
+            signal: controller.signal,
+            headers: { 'Accept': 'application/json' },
+        });
+        clearTimeout(timer);
+        if (!res.ok)
+            return null;
+        const data = await res.json();
+        return data.version || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 完整升级流程：检查 → 比较 → 安装（失败重试一次）
+ */
+export async function tryUpgrade() {
+    // 开发模式跳过
+    if (isLinkedInstall()) {
+        return { status: 'skipped' };
+    }
+    const localVer = getLocalVersion();
+    // 查询 registry
+    const remoteVer = await checkLatestVersion();
+    if (!remoteVer) {
+        return { status: 'skipped', error: 'Failed to check remote version' };
+    }
+    // 版本比较
+    if (compareVersions(localVer, remoteVer) >= 0) {
+        return { status: 'no-update', from: localVer };
+    }
+    // 有新版本，执行升级（失败重试一次）
+    let lastError;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            await npmInstallGlobal('evolcore@latest');
+            return { status: 'upgraded', from: localVer, to: remoteVer };
+        }
+        catch (e) {
+            lastError = e.stderr || e.message || String(e);
+        }
+    }
+    return { status: 'failed', from: localVer, to: remoteVer, error: lastError };
+}
+/**
+ * 通用全局包升级流程：检查 → 比较 → 安装（失败重试一次）。
+ * 仅在包已安装时检查升级，未安装则跳过（resolveFn 返回 null）。
+ * fastaun / EC Web 等独立全局包共用此逻辑。
+ */
+export async function tryUpgradeGlobalPkg(resolveInstalled, pkgName) {
+    if (isLinkedInstall()) {
+        return { status: 'skipped' };
+    }
+    const installed = resolveInstalled();
+    if (!installed) {
+        return { status: 'skipped' }; // not installed, skip
+    }
+    const localVer = installed.version;
+    const remoteVer = await checkLatestVersion(pkgName);
+    if (!remoteVer) {
+        return { status: 'skipped', error: 'Failed to check remote version' };
+    }
+    if (compareVersions(localVer, remoteVer) >= 0) {
+        return { status: 'no-update', from: localVer };
+    }
+    let lastError;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            await npmInstallGlobal(`${pkgName}@latest`);
+            return { status: 'upgraded', from: localVer, to: remoteVer };
+        }
+        catch (e) {
+            lastError = e.stderr || e.message || String(e);
+        }
+    }
+    return { status: 'failed', from: localVer, to: remoteVer, error: lastError };
+}
+/**
+ * AUN SDK 升级流程：检查 → 比较 → 安装
+ * 仅在 SDK 已安装时检查升级，未安装则跳过。
+ */
+export async function tryUpgradeAunSdk(resolveAunCoreSdkPkg, AUN_CORE_SDK_PKG) {
+    return tryUpgradeGlobalPkg(resolveAunCoreSdkPkg, AUN_CORE_SDK_PKG);
+}