@eogee-tech/eosearch 0.2.0 → 0.2.1

package/build-cli/cli.js

@@ -3,8 +3,13 @@
 // 薄客户端：本地只做参数解析与输出格式化，搜索与抓取全部在 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);
@@ -15,117 +20,138 @@ function readVersion() {
     }
 }
 // ---------- 用法文本 ----------
-const MAIN_HELP = `eosearch — EoSearch 联网搜索命令行客户端（v${readVersion()}）
-
-本地只做参数解析与结果展示，搜索与抓取在服务端执行；需要极会员密钥。
-
-用法: eosearch <子命令> [参数] [选项]
-
-子命令:
-  search <query>       联网搜索：意图路由 + 多引擎融合评分
-  batch <q1> <q2> ...  并行执行 1-5 条独立搜索（配额计 1 次）
-  fetch <url>          抓取网页正文（自动适配 CSDN/掘金/知乎/GitHub）
-  deep <query>         深度调研：搜索 + 选源 + 抓正文 + 摘录
-  whoami               验证密钥与服务连接
-  help [子命令]        显示帮助
-
-通用选项:
-  --json               机器可读 JSON 输出（stdout，字段与 MCP 工具一致）
-  --server-url <url>   覆盖服务地址（默认 ${DEFAULT_SERVER_URL}）
-  --timeout <秒>       单次调用超时（默认 120）
-  --version, -V        显示 CLI 版本
-  --help, -h           显示帮助
-
-密钥配置（环境变量优先，二选一）:
-  环境变量  EOSEARCH_API_KEY=<你的极会员密钥>
-  配置文件  ${configFilePath()} 写入 {"apiKey":"你的极会员密钥","serverUrl":"可选服务地址"}
-
-安全约定：密钥只从环境变量或配置文件读取，不提供命令行参数入口，避免进入 Shell 历史与进程列表。
-
-示例:
-  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
+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）
-
+    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}
-
+            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}
-
+            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}
-
+            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}
-
+            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}
-
+            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;
     }
@@ -161,6 +187,12 @@ const SPECS = {
         minPos: 0,
         maxPos: 0
     },
+    skill: {
+        valueFlags: ['dir'],
+        boolFlags: ['video'],
+        minPos: 0,
+        maxPos: 1
+    },
     help: {
         valueFlags: [],
         boolFlags: [],
@@ -225,6 +257,10 @@ function parseArgs(argv) {
             };
         }
     }
+    // 带 --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 查看用法` };
     }
@@ -291,7 +327,7 @@ function missingKeyFailure() {
         exitCode: 3,
         problem: '未找到 EoSearch API 密钥',
         cause: `环境变量 EOSEARCH_API_KEY 未设置，配置文件 ${configFilePath()} 中也没有 apiKey 字段`,
-        next: '设置环境变量 export EOSEARCH_API_KEY=<你的极会员密钥>，或在 ~/.eosearchrc 写入 {"apiKey":"..."}；密钥在 eogee.com 个人中心获取'
+        next: '设置环境变量 export EOSEARCH_API_KEY=<你的API密钥>，或在 ~/.eosearchrc 写入 {"apiKey":"..."}；密钥在 eogee.com 个人中心获取'
     };
 }
 async function callAndExit(opts) {
@@ -521,9 +557,70 @@ async function runWhoami(flags) {
     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);
@@ -539,13 +636,21 @@ async function main() {
                 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';
+    const needsKey = command !== 'help' && command !== 'skill';
     if (needsKey && !config.apiKey) {
         const f = missingKeyFailure();
         emitFailure(f);
@@ -563,6 +668,8 @@ async function main() {
                 return await runDeep(config, positional, flags);
             case 'whoami':
                 return await runWhoami(flags);
+            case 'skill':
+                return runSkill(positional, flags);
             default:
                 emitUsage(`未知子命令 "${command}"。eosearch help 查看全部子命令`);
         }

package/build-cli/updateCheck.js

@@ -0,0 +1,140 @@
+// cli/updateCheck.ts — npm 版本发现与更新提示
+// 策略：每次启动读本地缓存并提示；缓存过期时由后台子进程刷新，不阻塞当前命令
+import { spawn } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const PACKAGE_NAME = '@eogee-tech/eosearch';
+export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 4000;
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+export function updateCachePath() {
+    return process.env.EOSEARCH_UPDATE_CACHE || join(homedir(), '.eosearch-update.json');
+}
+export function updateCheckDisabled(env = process.env) {
+    return Boolean(env.CI) || Boolean(env.NO_UPDATE_NOTIFIER) || Boolean(env.EOSEARCH_NO_UPDATE_CHECK);
+}
+function readCache() {
+    try {
+        const raw = JSON.parse(readFileSync(updateCachePath(), 'utf8'));
+        return {
+            checkedAt: typeof raw.checkedAt === 'number' && Number.isFinite(raw.checkedAt) ? raw.checkedAt : 0,
+            latest: typeof raw.latest === 'string' && raw.latest.trim() ? raw.latest.trim() : null
+        };
+    }
+    catch {
+        return { checkedAt: 0, latest: null };
+    }
+}
+function writeCache(cache) {
+    try {
+        writeFileSync(updateCachePath(), `${JSON.stringify(cache)}\n`, 'utf8');
+    }
+    catch {
+        // 缓存写入失败不影响命令
+    }
+}
+function parseVersion(value) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(value.trim());
+    if (!match)
+        return null;
+    return {
+        core: [Number(match[1]), Number(match[2]), Number(match[3])],
+        pre: match[4] ? match[4].split('.') : []
+    };
+}
+export function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    if (!pa || !pb)
+        return 0;
+    for (let i = 0; i < 3; i++) {
+        if (pa.core[i] !== pb.core[i])
+            return pa.core[i] > pb.core[i] ? 1 : -1;
+    }
+    if (pa.pre.length === 0 || pb.pre.length === 0) {
+        if (pa.pre.length === pb.pre.length)
+            return 0;
+        return pa.pre.length === 0 ? 1 : -1;
+    }
+    const length = Math.max(pa.pre.length, pb.pre.length);
+    for (let i = 0; i < length; i++) {
+        const x = pa.pre[i];
+        const y = pb.pre[i];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const nx = /^\d+$/.test(x) ? Number(x) : null;
+        const ny = /^\d+$/.test(y) ? Number(y) : null;
+        if (nx !== null && ny !== null) {
+            if (nx !== ny)
+                return nx > ny ? 1 : -1;
+        }
+        else if (x !== y) {
+            if (nx !== null)
+                return -1;
+            if (ny !== null)
+                return 1;
+            return x > y ? 1 : -1;
+        }
+    }
+    return 0;
+}
+export function isCheckDue(checkedAt, now = Date.now()) {
+    return now - checkedAt >= CHECK_INTERVAL_MS;
+}
+export function formatUpdateNotice(current, latest) {
+    return `提示：EoSearch CLI 有新版本 ${latest}（当前 ${current}）。升级：npm i -g ${PACKAGE_NAME}，再执行 eosearch skill install 刷新技能文档（装了视频技能再加 --video）`;
+}
+export async function refreshUpdateCache() {
+    const previous = readCache();
+    const registry = (process.env.EOSEARCH_UPDATE_REGISTRY || DEFAULT_REGISTRY).replace(/\/+$/, '');
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    let latest = previous.latest;
+    try {
+        const response = await fetch(`${registry}/${PACKAGE_NAME}/latest`, {
+            headers: { accept: 'application/json' },
+            signal: controller.signal
+        });
+        if (response.ok) {
+            const body = (await response.json());
+            if (typeof body.version === 'string' && body.version.trim())
+                latest = body.version.trim();
+        }
+    }
+    catch {
+        // 网络失败静默，保留上次结果
+    }
+    finally {
+        clearTimeout(timer);
+        writeCache({ checkedAt: Date.now(), latest });
+    }
+}
+function spawnBackgroundRefresh() {
+    try {
+        const cliPath = fileURLToPath(new URL('./cli.js', import.meta.url));
+        const child = spawn(process.execPath, [cliPath, '--update-check'], {
+            detached: true,
+            stdio: 'ignore',
+            windowsHide: true
+        });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        // 无法启动后台检查时静默
+    }
+}
+export function notifyIfUpdateAvailable(currentVersion, options = {}) {
+    if (updateCheckDisabled())
+        return;
+    const cache = readCache();
+    if (!options.quiet && cache.latest && compareVersions(cache.latest, currentVersion) > 0) {
+        console.error(formatUpdateNotice(currentVersion, cache.latest));
+    }
+    if (isCheckDue(cache.checkedAt))
+        spawnBackgroundRefresh();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eogee-tech/eosearch",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "EoSearch command-line client for AI agents — web search, page fetch and deep research via eogee.com (thin client; engines run server-side)",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "build-cli",
+    "skill",
     "NOTICE",
     "LICENSE"
   ],