@eogee-tech/eosearch 0.0.0-stage → 0.2.1

package/build-cli/cli.js

@@ -0,0 +1,691 @@
+#!/usr/bin/env node
+// cli/cli.ts — EoSearch 命令行客户端入口（npm 包 @eogee-tech/eosearch）
+// 薄客户端：本地只做参数解析与输出格式化，搜索与抓取全部在 eogee.com 服务端执行
+// 退出码：0 成功；1 业务空结果；2 用法错误；3 鉴权失败；4 配额限流；5 服务不可用/执行失败
+import { createRequire } from 'node:module';
+import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveConfig, configFilePath, DEFAULT_SERVER_URL } from './config.js';
+import { callTool, whoami } from './client.js';
+import { notifyIfUpdateAvailable, refreshUpdateCache } from './updateCheck.js';
+function readVersion() {
+    try {
+        const require = createRequire(import.meta.url);
+        return require('../package.json').version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+// ---------- 用法文本 ----------
+const MAIN_HELP = `eosearch — EoSearch 联网搜索命令行客户端（v${readVersion()}）
+
+本地只做参数解析与结果展示，搜索与抓取在服务端执行；需要 API 密钥。
+
+用法: eosearch <子命令> [参数] [选项]
+
+子命令:
+  search <query>       联网搜索：意图路由 + 多引擎融合评分
+  batch <q1> <q2> ...  并行执行 1-5 条独立搜索（配额计 1 次）
+  fetch <url>          抓取网页正文（自动适配 CSDN/掘金/知乎/GitHub）
+  deep <query>         深度调研：搜索 + 选源 + 抓正文 + 摘录
+  whoami               验证密钥与服务连接
+  skill install        安装技能文档到客户端技能目录（无需密钥）
+  help [子命令]        显示帮助
+
+通用选项:
+  --json               机器可读 JSON 输出（stdout，字段与 MCP 工具一致）
+  --server-url <url>   覆盖服务地址（默认 ${DEFAULT_SERVER_URL}）
+  --timeout <秒>       单次调用超时（默认 120）
+  --version, -V        显示 CLI 版本
+  --help, -h           显示帮助
+
+密钥配置（环境变量优先，二选一）:
+  环境变量  EOSEARCH_API_KEY=<你的API密钥>
+  配置文件  ${configFilePath()} 写入 {"apiKey":"你的API密钥","serverUrl":"可选服务地址"}
+
+安全约定：密钥只从环境变量或配置文件读取，不提供命令行参数入口，避免进入 Shell 历史与进程列表。
+
+更新提示：每日最多后台检查一次 npm 新版本，有更新时在 stderr 提示；
+          升级后执行 eosearch skill install 刷新技能文档；CI 或 NO_UPDATE_NOTIFIER=1 时关闭。
+
+示例:
+  eosearch search "llama.cpp 新版本" --json --limit 5
+  eosearch deep "2026 国产大模型对比" --top-n 3 --timeout 300
+  eosearch batch "量子计算现状" "相关ETF" --json
+  eosearch fetch https://github.com/ggml-org/llama.cpp
+  eosearch whoami`;
+function subcommandHelp(command) {
+    const shared = `通用选项: --json 机器可读输出 | --server-url <url> 覆盖服务地址 | --timeout <秒> 单次超时（默认 120）
+
+密钥: 环境变量 EOSEARCH_API_KEY，或配置文件 ${configFilePath()} 的 {"apiKey":"..."} 字段`;
+    switch (command) {
+        case 'search':
+            return `eosearch search — 联网搜索：意图路由 + 多引擎融合评分
+
+用法: eosearch search <query> [选项]
+
+选项:
+  --limit <1-50>            返回条数上限（默认 10）
+  --engines <a,b,...>       指定引擎列表，绕过意图路由（如 bing,baidu,bilibili）
+  --zone <auto|cn|intl>     路由偏好：cn 偏中文引擎，intl 偏国际引擎（默认 auto）
+  --search-mode <模式>      request|auto|playwright（Bing 异常时用 playwright 重试）
+  --freshness <窗口>        day|week|month|year，只保留该时间窗内发布的结果
+  --include-domains <a,b>   只保留这些域名（含子域）的结果
+  --exclude-domains <a,b>   丢弃这些域名（含子域）的结果
+  --json                    输出服务端 JSON（字段含 score/engines/reasons）
+
+${shared}
+
+示例: eosearch search "llama.cpp 新版本" --freshness month --json --limit 5`;
+        case 'batch':
+            return `eosearch batch — 并行执行 1-5 条独立搜索，配额计 1 次
+
+用法: eosearch batch <query1> <query2> ... [选项]
+
+选项:
+  --zone <auto|cn|intl>     共享路由偏好，应用到未单独指定的查询
+  --json                    输出服务端 JSON（results 数组 + failures 数组）
+
+${shared}
+
+示例: eosearch batch "量子计算现状" "相关ETF" "IBM 股价" --json`;
+        case 'fetch':
+            return `eosearch fetch — 抓取网页并返回清洗后的正文
+
+用法: eosearch fetch <url> [选项]
+
+选项:
+  --max-chars <500-200000>  返回正文长度上限（默认 20000）
+  --no-readability          关闭正文主内容抽取（默认开启）
+  --render-mode <模式>      request|auto|browser（auto 需服务端装有 Playwright）
+  --json                    输出 {"url":"...","content":"..."} 结构
+
+${shared}
+
+示例: eosearch fetch https://github.com/ggml-org/llama.cpp --max-chars 8000`;
+        case 'deep':
+            return `eosearch deep — 深度调研：搜索、选源、抓正文、按 token 预算输出摘录
+
+用法: eosearch deep <query> [选项]
+
+选项:
+  --top-n <1-10>            实际读取的来源数（默认 5）
+  --token-budget <数值>     摘录 token 预算，2000-120000（默认 24000）
+  --engines <a,b,...>       指定引擎列表
+  --zone <auto|cn|intl>     路由偏好
+  --freshness <窗口>        day|week|month|year
+  --include-domains <a,b>   只保留这些域名
+  --exclude-domains <a,b>   丢弃这些域名
+  --json                    额外返回结构化 sources 数组（url/score/adapter）
+
+${shared}
+
+示例: eosearch deep "2026 国产大模型对比" --top-n 3 --timeout 300`;
+        case 'whoami':
+            return `eosearch whoami — 验证密钥与服务连接（握手不计配额）
+
+用法: eosearch whoami [选项]
+
+输出密钥有效性、服务端名称与版本、密钥来源。
+退出码: 0 密钥有效；3 密钥被拒；4 限流；5 服务不可达。
+
+${shared}
+
+示例: eosearch whoami`;
+        case 'skill':
+            return `eosearch skill — 把随包分发的技能文档安装到客户端技能目录（纯本地操作，无需密钥）
+
+用法: eosearch skill install [选项]
+
+动作:
+  install                 复制技能文档 SKILL.md 到 <技能根目录>/eosearch/SKILL.md
+
+选项:
+  --dir <path>            技能根目录（默认 ~/.zcode/skills，即 ZCode 用户级技能目录）
+  --video                 同时安装 eosearch-video 视频技能（整目录复制）
+
+说明:
+  重复执行即把技能文档升级为当前 CLI 同版本（覆盖旧版）；重启客户端会话后生效。
+  其他客户端（Codex 等）把 --dir 指向其技能目录即可。
+
+示例: eosearch skill install --video`;
+        default:
+            return null;
+    }
+}
+const SPECS = {
+    search: {
+        valueFlags: ['limit', 'engines', 'zone', 'search-mode', 'freshness', 'include-domains', 'exclude-domains', 'server-url', 'timeout'],
+        boolFlags: ['json'],
+        minPos: 1,
+        maxPos: 1
+    },
+    batch: {
+        valueFlags: ['zone', 'server-url', 'timeout'],
+        boolFlags: ['json'],
+        minPos: 1,
+        maxPos: 5
+    },
+    fetch: {
+        valueFlags: ['max-chars', 'render-mode', 'server-url', 'timeout'],
+        boolFlags: ['json', 'no-readability'],
+        minPos: 1,
+        maxPos: 1
+    },
+    deep: {
+        valueFlags: ['top-n', 'token-budget', 'engines', 'zone', 'freshness', 'include-domains', 'exclude-domains', 'server-url', 'timeout'],
+        boolFlags: ['json'],
+        minPos: 1,
+        maxPos: 1
+    },
+    whoami: {
+        valueFlags: ['server-url', 'timeout'],
+        boolFlags: ['json'],
+        minPos: 0,
+        maxPos: 0
+    },
+    skill: {
+        valueFlags: ['dir'],
+        boolFlags: ['video'],
+        minPos: 0,
+        maxPos: 1
+    },
+    help: {
+        valueFlags: [],
+        boolFlags: [],
+        minPos: 0,
+        maxPos: 1
+    }
+};
+class UsageError extends Error {
+}
+function parseArgs(argv) {
+    if (argv.length === 0)
+        return { kind: 'ok', command: 'help', positional: [], flags: new Map() };
+    const first = argv[0];
+    if (first === 'help' || first === '--help' || first === '-h') {
+        return { kind: 'ok', command: 'help', positional: argv.slice(1), flags: new Map() };
+    }
+    if (first.startsWith('-')) {
+        return { kind: 'usage', message: `未知参数 "${first}"。先写子命令，如 eosearch search <query>；eosearch help 查看全部子命令` };
+    }
+    if (!(first in SPECS)) {
+        return { kind: 'usage', message: `未知子命令 "${first}"。eosearch help 查看全部子命令` };
+    }
+    const command = first;
+    const spec = SPECS[command];
+    const rest = argv.slice(1);
+    const flags = new Map();
+    const positional = [];
+    for (let i = 0; i < rest.length; i++) {
+        const tok = rest[i];
+        if (tok === '--') {
+            positional.push(...rest.slice(i + 1));
+            break;
+        }
+        if (tok.startsWith('--')) {
+            const eq = tok.indexOf('=');
+            if (eq >= 0) {
+                flags.set(tok.slice(2, eq), tok.slice(eq + 1));
+                continue;
+            }
+            const key = tok.slice(2);
+            const next = rest[i + 1];
+            if (spec.valueFlags.includes(key) && next !== undefined && !next.startsWith('--')) {
+                flags.set(key, next);
+                i++;
+            }
+            else {
+                flags.set(key, true);
+            }
+            continue;
+        }
+        if (tok.startsWith('-') && tok.length === 2) {
+            flags.set(tok.slice(1), true);
+            continue;
+        }
+        positional.push(tok);
+    }
+    for (const key of flags.keys()) {
+        if (!spec.valueFlags.includes(key) && !spec.boolFlags.includes(key) && !['help', 'h', 'version', 'V'].includes(key)) {
+            return {
+                kind: 'usage',
+                message: `子命令 ${command} 不支持选项 --${key}。eosearch ${command} --help 查看支持的选项`
+            };
+        }
+    }
+    // 带 --help/-h 时跳过位置参数数量校验，交给主入口显示该子命令的帮助
+    if (flags.get('help') === true || flags.get('h') === true) {
+        return { kind: 'ok', command, positional, flags };
+    }
+    if (positional.length < spec.minPos) {
+        return { kind: 'usage', message: `${command} 缺少必填参数。eosearch ${command} --help 查看用法` };
+    }
+    if (positional.length > spec.maxPos) {
+        const hint = command === 'batch' ? `batch 一次最多 ${spec.maxPos} 条查询` : `${command} 只接受 ${spec.maxPos} 个位置参数`;
+        return { kind: 'usage', message: `${hint}，收到 ${positional.length} 个。eosearch ${command} --help 查看用法` };
+    }
+    return { kind: 'ok', command, positional, flags };
+}
+// ---------- 选项读取与校验 ----------
+function rawFlag(flags, key) {
+    const value = flags.get(key);
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function intFlag(flags, key, min, max) {
+    const raw = rawFlag(flags, key);
+    if (raw === null)
+        return null;
+    if (!/^\d+$/.test(raw)) {
+        throw new UsageError(`--${key} 需要 ${min}-${max} 的整数，收到 "${raw}"`);
+    }
+    const n = parseInt(raw, 10);
+    if (n < min || n > max) {
+        throw new UsageError(`--${key} 需要在 ${min}-${max} 之间，收到 ${n}`);
+    }
+    return n;
+}
+function enumFlag(flags, key, allowed) {
+    const raw = rawFlag(flags, key);
+    if (raw === null)
+        return null;
+    if (!allowed.includes(raw)) {
+        throw new UsageError(`--${key} 只支持 ${allowed.join('|')}，收到 "${raw}"`);
+    }
+    return raw;
+}
+function commaList(flags, key) {
+    const raw = rawFlag(flags, key);
+    if (raw === null)
+        return null;
+    const list = raw.split(',').map((s) => s.trim()).filter(Boolean);
+    if (list.length === 0) {
+        throw new UsageError(`--${key} 需要逗号分隔的列表，如 a.com,b.com`);
+    }
+    return list;
+}
+function timeoutMsOf(flags) {
+    const seconds = intFlag(flags, 'timeout', 1, 600);
+    return (seconds ?? 120) * 1000;
+}
+// ---------- 输出与退出 ----------
+function emitFailure(f) {
+    console.error(`错误：${f.problem}`);
+    console.error(`原因：${f.cause}`);
+    console.error(`下一步：${f.next}`);
+}
+function emitUsage(message) {
+    console.error(`错误：${message}`);
+    process.exit(2);
+}
+function missingKeyFailure() {
+    return {
+        kind: 'failure',
+        exitCode: 3,
+        problem: '未找到 EoSearch API 密钥',
+        cause: `环境变量 EOSEARCH_API_KEY 未设置，配置文件 ${configFilePath()} 中也没有 apiKey 字段`,
+        next: '设置环境变量 export EOSEARCH_API_KEY=<你的API密钥>，或在 ~/.eosearchrc 写入 {"apiKey":"..."}；密钥在 eogee.com 个人中心获取'
+    };
+}
+async function callAndExit(opts) {
+    const outcome = await callTool({
+        serverUrl: opts.config.serverUrl,
+        apiKey: opts.config.apiKey,
+        clientVersion: readVersion(),
+        toolName: opts.toolName,
+        toolArgs: opts.toolArgs,
+        timeoutMs: opts.timeoutMs
+    });
+    if (outcome.kind === 'failure') {
+        emitFailure(outcome);
+        process.exit(outcome.exitCode);
+    }
+    if (opts.json) {
+        process.stdout.write(outcome.text + '\n');
+        let parsed = null;
+        try {
+            parsed = JSON.parse(outcome.text);
+        }
+        catch {
+            parsed = null;
+        }
+        if (parsed !== null) {
+            const empty = opts.emptyCheck(parsed);
+            if (empty) {
+                emitFailure(empty);
+                process.exit(empty.exitCode);
+            }
+        }
+        process.exit(0);
+    }
+    process.stdout.write(outcome.text + '\n');
+    process.exit(0);
+}
+// ---------- 子命令实现 ----------
+async function runSearch(config, positional, flags) {
+    const toolArgs = {
+        query: positional[0],
+        format: flags.get('json') === true ? 'json' : 'markdown'
+    };
+    const limit = intFlag(flags, 'limit', 1, 50);
+    if (limit !== null)
+        toolArgs.limit = limit;
+    const engines = commaList(flags, 'engines');
+    if (engines)
+        toolArgs.engines = engines;
+    const zone = enumFlag(flags, 'zone', ['auto', 'cn', 'intl']);
+    if (zone)
+        toolArgs.zone = zone;
+    const searchMode = enumFlag(flags, 'search-mode', ['request', 'auto', 'playwright']);
+    if (searchMode)
+        toolArgs.searchMode = searchMode;
+    const freshness = enumFlag(flags, 'freshness', ['day', 'week', 'month', 'year']);
+    if (freshness)
+        toolArgs.freshness = freshness;
+    const includeDomains = commaList(flags, 'include-domains');
+    if (includeDomains)
+        toolArgs.includeDomains = includeDomains;
+    const excludeDomains = commaList(flags, 'exclude-domains');
+    if (excludeDomains)
+        toolArgs.excludeDomains = excludeDomains;
+    return callAndExit({
+        config,
+        toolName: 'eosearch_search',
+        toolArgs,
+        timeoutMs: timeoutMsOf(flags),
+        json: flags.get('json') === true,
+        emptyCheck: (parsed) => {
+            const obj = parsed;
+            if (Array.isArray(obj.results) && obj.results.length === 0) {
+                return {
+                    kind: 'failure',
+                    exitCode: 1,
+                    problem: '搜索无结果',
+                    cause: '服务端多引擎融合后返回 0 条结果',
+                    next: '放宽 --freshness、更换更具体的关键词，或用 --engines 指定引擎重试'
+                };
+            }
+            return null;
+        }
+    });
+}
+async function runBatch(config, positional, flags) {
+    const toolArgs = {
+        queries: positional,
+        format: flags.get('json') === true ? 'json' : 'markdown'
+    };
+    const zone = enumFlag(flags, 'zone', ['auto', 'cn', 'intl']);
+    if (zone)
+        toolArgs.zone = zone;
+    return callAndExit({
+        config,
+        toolName: 'eosearch_batch_search',
+        toolArgs,
+        timeoutMs: timeoutMsOf(flags),
+        json: flags.get('json') === true,
+        emptyCheck: (parsed) => {
+            const obj = parsed;
+            if (typeof obj.failed === 'number' && obj.failed > 0 && obj.failed < (obj.totalQueries ?? 0)) {
+                console.error(`提示：${obj.failed} 条查询失败，详见输出中 failures 字段`);
+                return null;
+            }
+            if (typeof obj.totalQueries === 'number' && typeof obj.failed === 'number' && obj.totalQueries > 0 && obj.failed === obj.totalQueries) {
+                return {
+                    kind: 'failure',
+                    exitCode: 1,
+                    problem: `全部 ${obj.totalQueries} 条查询都失败`,
+                    cause: '服务端执行批量搜索时每条查询都未返回结果',
+                    next: '检查查询词是否过偏，减少条数或更换关键词后重试'
+                };
+            }
+            return null;
+        }
+    });
+}
+async function runFetch(config, positional, flags) {
+    const url = positional[0];
+    if (!/^https?:\/\//i.test(url)) {
+        emitUsage(`fetch 需要 http(s) 网址，收到 "${url}"`);
+    }
+    const toolArgs = { url };
+    const maxChars = intFlag(flags, 'max-chars', 500, 200000);
+    if (maxChars !== null)
+        toolArgs.maxChars = maxChars;
+    if (flags.get('no-readability') === true)
+        toolArgs.readability = false;
+    const renderMode = enumFlag(flags, 'render-mode', ['request', 'auto', 'browser']);
+    if (renderMode)
+        toolArgs.renderMode = renderMode;
+    const json = flags.get('json') === true;
+    if (!json) {
+        return callAndExit({
+            config,
+            toolName: 'eosearch_fetch',
+            toolArgs,
+            timeoutMs: timeoutMsOf(flags),
+            json: false,
+            emptyCheck: () => null
+        });
+    }
+    // fetch 的 --json：工具返回纯文本（首行元信息 + 正文），包装为结构化输出
+    const outcome = await callTool({
+        serverUrl: config.serverUrl,
+        apiKey: config.apiKey,
+        clientVersion: readVersion(),
+        toolName: 'eosearch_fetch',
+        toolArgs,
+        timeoutMs: timeoutMsOf(flags)
+    });
+    if (outcome.kind === 'failure') {
+        emitFailure(outcome);
+        process.exit(outcome.exitCode);
+    }
+    const firstLine = (outcome.text.split('\n', 1)[0] ?? '').trim();
+    const match = /^URL: (\S+)$/.exec(firstLine);
+    const payload = JSON.stringify({ url: match ? match[1] : url, content: outcome.text }, null, 2);
+    process.stdout.write(payload + '\n');
+    process.exit(0);
+}
+async function runDeep(config, positional, flags) {
+    const toolArgs = {
+        query: positional[0],
+        format: flags.get('json') === true ? 'json' : 'text'
+    };
+    const topN = intFlag(flags, 'top-n', 1, 10);
+    if (topN !== null)
+        toolArgs.topN = topN;
+    const tokenBudget = intFlag(flags, 'token-budget', 2000, 120000);
+    if (tokenBudget !== null)
+        toolArgs.tokenBudget = tokenBudget;
+    const engines = commaList(flags, 'engines');
+    if (engines)
+        toolArgs.engines = engines;
+    const zone = enumFlag(flags, 'zone', ['auto', 'cn', 'intl']);
+    if (zone)
+        toolArgs.zone = zone;
+    const freshness = enumFlag(flags, 'freshness', ['day', 'week', 'month', 'year']);
+    if (freshness)
+        toolArgs.freshness = freshness;
+    const includeDomains = commaList(flags, 'include-domains');
+    if (includeDomains)
+        toolArgs.includeDomains = includeDomains;
+    const excludeDomains = commaList(flags, 'exclude-domains');
+    if (excludeDomains)
+        toolArgs.excludeDomains = excludeDomains;
+    return callAndExit({
+        config,
+        toolName: 'eosearch_deep_search',
+        toolArgs,
+        timeoutMs: timeoutMsOf(flags),
+        json: flags.get('json') === true,
+        emptyCheck: () => null
+    });
+}
+async function runWhoami(flags) {
+    const config = resolveConfig({ serverUrl: rawFlag(flags, 'server-url') });
+    if (!config.apiKey) {
+        const f = missingKeyFailure();
+        emitFailure(f);
+        process.exit(f.exitCode);
+    }
+    const result = await whoami({
+        serverUrl: config.serverUrl,
+        apiKey: config.apiKey,
+        clientVersion: readVersion()
+    });
+    if ('kind' in result && result.kind === 'failure') {
+        const f = result;
+        emitFailure(f);
+        process.exit(f.exitCode);
+    }
+    const info = result;
+    if (flags.get('json') === true) {
+        process.stdout.write(JSON.stringify({
+            ok: true,
+            server: { name: info.serverName ?? null, version: info.serverVersion ?? null },
+            serverUrl: config.serverUrl,
+            apiKeySource: config.apiKeySource,
+            instructions: info.instructions ?? null
+        }, null, 2) + '\n');
+        process.exit(0);
+    }
+    console.log(`密钥有效，服务连接正常（密钥来自${config.apiKeySource === 'environment' ? '环境变量' : '配置文件 ~/.eosearchrc'}）`);
+    console.log(`服务端：${info.serverName ?? 'eosearch'} ${info.serverVersion ?? ''}`.trimEnd());
+    console.log(`地址：${config.serverUrl}`);
+    process.exit(0);
+}
+// ---------- skill 子命令（纯本地操作，无需密钥） ----------
+function skillPackError(src) {
+    console.error(`错误：安装包内缺少技能源文件（${src}）`);
+    console.error('原因：npm 包内容不完整，files 配置异常或包安装损坏');
+    console.error('下一步：重装 npm 包（npm install -g @eogee-tech/eosearch）后重试');
+    process.exit(5);
+}
+function runSkill(positional, flags) {
+    const action = positional[0];
+    if (action !== 'install') {
+        emitUsage(action === undefined
+            ? 'skill 缺少动作，用法：eosearch skill install [--dir <path>] [--video]。eosearch skill --help 查看用法'
+            : `未知 skill 动作 "${action}"，目前只支持 install。eosearch skill --help 查看用法`);
+    }
+    const targetRoot = resolvePath(rawFlag(flags, 'dir') ?? join(homedir(), '.zcode', 'skills'));
+    const installVideo = flags.get('video') === true;
+    const version = readVersion();
+    const lines = [];
+    // 主技能：单文件复制到 <技能根目录>/eosearch/SKILL.md（build-cli 与 skill 同在包根）
+    const mainSrc = fileURLToPath(new URL('../skill/SKILL.md', import.meta.url));
+    if (!existsSync(mainSrc))
+        skillPackError(mainSrc);
+    const mainDestDir = join(targetRoot, 'eosearch');
+    const mainDest = join(mainDestDir, 'SKILL.md');
+    const mainExisted = existsSync(mainDest);
+    mkdirSync(mainDestDir, { recursive: true });
+    copyFileSync(mainSrc, mainDest);
+    lines.push(`${mainDest}${mainExisted ? '（已覆盖旧版）' : ''}`);
+    // 视频技能：整目录复制到 <技能根目录>/eosearch-video/
+    if (installVideo) {
+        const videoSrc = fileURLToPath(new URL('../skill/eosearch-video', import.meta.url));
+        if (!existsSync(videoSrc))
+            skillPackError(videoSrc);
+        const videoDest = join(targetRoot, 'eosearch-video');
+        const videoExisted = existsSync(videoDest);
+        if (videoExisted && !existsSync(join(videoDest, 'SKILL.md'))) {
+            console.error(`错误：目标目录 ${videoDest} 已存在但不像已安装的 eosearch-video 技能`);
+            console.error('原因：为避免覆盖非技能内容，安装已中止');
+            console.error('下一步：确认该目录可删除后手动移除，再重新执行本命令');
+            process.exit(5);
+        }
+        cpSync(videoSrc, videoDest, { recursive: true });
+        if (process.platform !== 'win32') {
+            try {
+                chmodSync(join(videoDest, 'helpers', 'grab.sh'), 0o755);
+            }
+            catch { /* 执行权限设置失败不阻塞安装 */ }
+        }
+        lines.push(`${videoDest}${videoExisted ? '（已覆盖旧版）' : ''}`);
+    }
+    console.log(`EoSearch 技能安装完成（v${version}）：`);
+    for (const line of lines)
+        console.log(`  ${line}`);
+    console.log('提示：重启客户端会话后技能生效；目录不对时用 --dir <path> 指定技能根目录。');
+    process.exit(0);
+}
+// ---------- 主入口 ----------
+async function main() {
+    const argv = process.argv.slice(2);
+    // 后台子进程入口：只刷新版本缓存，不执行用户命令
+    if (argv[0] === '--update-check') {
+        await refreshUpdateCache();
+        process.exit(0);
+    }
+    if (argv.includes('--version') || argv.includes('-V')) {
+        console.log(readVersion());
+        process.exit(0);
+    }
+    const parsed = parseArgs(argv);
+    if (parsed.kind === 'usage')
+        emitUsage(parsed.message);
+    const { command, positional, flags } = parsed;
+    if (command === 'help' || flags.get('help') === true || flags.get('h') === true) {
+        if (command === 'help' && positional.length > 0) {
+            const sub = subcommandHelp(positional[0]);
+            if (sub === null)
+                emitUsage(`未知子命令 "${positional[0]}"。eosearch help 查看全部子命令`);
+            console.log(sub);
+        }
+        else if (command !== 'help') {
+            // eosearch <子命令> --help：显示该子命令的帮助
+            const sub = subcommandHelp(command);
+            if (sub === null)
+                emitUsage(`未知子命令 "${command}"。eosearch help 查看全部子命令`);
+            console.log(sub);
+        }
+        else {
+            console.log(MAIN_HELP);
+        }
+        process.exit(0);
+    }
+    notifyIfUpdateAvailable(readVersion(), { quiet: Boolean(flags.get('json')) });
+    const config = resolveConfig({ serverUrl: rawFlag(flags, 'server-url') });
+    const needsKey = command !== 'help' && command !== 'skill';
+    if (needsKey && !config.apiKey) {
+        const f = missingKeyFailure();
+        emitFailure(f);
+        process.exit(f.exitCode);
+    }
+    try {
+        switch (command) {
+            case 'search':
+                return await runSearch(config, positional, flags);
+            case 'batch':
+                return await runBatch(config, positional, flags);
+            case 'fetch':
+                return await runFetch(config, positional, flags);
+            case 'deep':
+                return await runDeep(config, positional, flags);
+            case 'whoami':
+                return await runWhoami(flags);
+            case 'skill':
+                return runSkill(positional, flags);
+            default:
+                emitUsage(`未知子命令 "${command}"。eosearch help 查看全部子命令`);
+        }
+    }
+    catch (error) {
+        if (error instanceof UsageError)
+            emitUsage(error.message);
+        console.error('错误：CLI 内部异常');
+        console.error(`原因：${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+        console.error('下一步：重试一次；持续出现请带上上面的堆栈反馈');
+        process.exit(5);
+    }
+}
+main().catch((error) => {
+    console.error('错误：CLI 未捕获异常');
+    console.error(`原因：${error instanceof Error ? error.message : String(error)}`);
+    console.error('下一步：重试一次；持续出现请带上该信息反馈');
+    process.exit(5);
+});