echopai 2.1.0 → 2.3.0

package/dist/bin.js

@@ -14,26 +14,57 @@
  *
  * See docs/PLAN_CLI_V2_REWRITE.md for design details.
  */
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
 import { Command, Option } from "commander";
 import { buildCommandTree } from "./_generated/commands.js";
 import { invoke } from "./runtime/invoker.js";
 import { buildApiCommand } from "./tools/api.js";
 import { buildMcpCommand } from "./tools/mcp.js";
 import { buildRawCallCommand } from "./tools/raw.js";
-import { buildBarsBatchCommand, buildChartCommand, buildDigestCommand, buildHotCommand, buildLookupCommand, buildNewsCommand, buildQuoteCommand, buildResearchCommand, buildScanCommand, buildSearchCommand, buildSentimentCommand, buildViewsCommand, } from "./verbs/index.js";
+import { buildAnnouncementsCommand, buildBarsBatchCommand, buildChartCommand, buildConceptsCommand, buildDigestCommand, buildFinancialsCommand, buildHotCommand, buildLimitUpCommand, buildLookupCommand, buildMarketCommand, buildNewsCommand, buildQuoteCommand, buildScanCommand, buildSearchCommand, buildSentimentCommand, buildViewsCommand, } from "./verbs/index.js";
 import { buildCompletionCommand } from "./tools/completion.js";
 import { buildConfigCommand } from "./tools/config.js";
 import { buildLoginCommand, buildLogoutCommand, buildStatusCommand } from "./tools/login.js";
 import { buildDoctorCommand } from "./tools/doctor.js";
 import { buildSchemaCommand } from "./tools/schema.js";
 import { buildTraceCommand } from "./tools/trace.js";
+import { buildUpgradeCommand } from "./tools/upgrade.js";
+import { buildWelcomeCommand, printWelcome, shouldShowWelcome } from "./tools/welcome.js";
 import { buildWhoamiCommand } from "./tools/whoami.js";
 import { CLI_VERSION } from "./version.js";
+// ─── Background update check ────────────────────────────────────────────────
+// Spawn a detached child that hits npm registry and writes a 24h cache file.
+// Parent exits immediately (child.unref). Banner is emitted on next CLI run
+// from the cache (zero hot-path network cost). Skipped in CI / non-TTY /
+// opt-out env so AI agents and scripts pay nothing.
+try {
+    const optedOut = process.env.CI ||
+        process.env.ECHOPAI_DISABLE_UPDATE_CHECK ||
+        !process.stderr.isTTY;
+    // Don't recurse: the worker entry sets this env so we skip spawning again
+    // from inside the worker process itself.
+    if (!optedOut && !process.env._ECHOPAI_UPDATE_WORKER) {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const workerPath = path.join(here, "runtime", "update_worker.js");
+        const child = spawn(process.execPath, [workerPath, CLI_VERSION], {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+            env: { ...process.env, _ECHOPAI_UPDATE_WORKER: "1" },
+        });
+        child.unref();
+    }
+}
+catch {
+    // Worker spawn is best-effort; never let it break the CLI.
+}
 const program = new Command();
 program
     .name("echopai")
     .description("EchoPai CLI v1 — partner-grade access to stock-market data, news, sentiment,\n" +
-    "views, signals, backtest.\n\n" +
+    "and analyst views.\n\n" +
     "AI-First: JSON envelope on stdout, JSON errors on stderr, three-state exit\n" +
     "codes (0 success / 1 user error / 2 service error). Set ECHOPAI_KEY env\n" +
     "var or run `echopai login`.")
@@ -50,12 +81,19 @@ program
     .addOption(new Option("--max-bytes <n>", "Truncate serialized envelope to N bytes (sets meta.truncated)"))
     .addOption(new Option("--yes", "Confirm a write op in non-TTY mode (required for sideEffect=write in agents / CI)"))
     .addOption(new Option("--dry-run", "Send X-Dry-Run:1 on write ops where the server advertises dry-run support"))
-    .addHelpText("after", "\nAuthentication: ECHOPAI_KEY=<eps_live_<lookup>_<secret>> echopai <cmd>\n" +
-    "Raw mirror:     echopai raw <noun> <verb>   # all OpenAPI ops, e.g. raw news search\n" +
-    "Curated verbs:  echopai <verb>              # task-level entry (Phase 3.6+)\n" +
-    "Capability:     echopai whoami | echopai doctor\n" +
-    "Schema dump:    echopai schema export       # AI agents pipe this for command surface\n" +
-    "Profile:        echopai config profile add prod --base-url https://api.echopai.com\n");
+    .addHelpText("after", "\nAuthentication:  ECHOPAI_KEY=<eps_live_<lookup>_<secret>> echopai <cmd>\n" +
+    "Raw mirror:      echopai raw <noun> <verb>   # all OpenAPI ops, e.g. raw news search\n" +
+    "Curated verbs:   echopai <verb>              # task-level entry (Phase 3.6+)\n" +
+    "Market session:  echopai market status                          # pre-open/open/lunch/closed + next trading day\n" +
+    "Market movers:   echopai market movers --sort pct --top 20      # /market 行情榜（pct / pct_asc / speed / amount / turnover / total_mv）\n" +
+    "Announcements:   echopai announcements stock --code SSE:600519  # cninfo A-share disclosures\n" +
+    "Concepts:        echopai concepts alerts                        # 当前激活的概念异动（big_move / limit_up_cluster）\n" +
+    "Limit-up:        echopai limit-up summary                       # 涨停数 / 炸板数 / 连板梯队\n" +
+    "Fundamentals:    echopai financials quote-snapshot --code SSE:600519   # PE/PB/PS/换手率/股息率/量比 14-field snapshot\n" +
+    "Capability:      echopai whoami | echopai doctor\n" +
+    "Schema dump:     echopai schema export       # AI agents pipe this for command surface\n" +
+    "Profile:         echopai config profile add prod --base-url https://api.echopai.com\n" +
+    "Self-update:     echopai upgrade [--check] [--exec]   # check npm registry; --exec runs `npm i -g echopai@latest`\n");
 const dispatch = async (op, args) => {
     // commander stores global flags on the *root* command's opts in camelCase
     // (e.g. --max-bytes → maxBytes). Subcommand-level opts go through
@@ -100,7 +138,7 @@ function applyAiFirstHooks(cmd) {
 //
 // Phase 3.7+ — `raw` is now the only place to find spec-driven operations.
 // Top-level previously held spec mirrors but starting this PR the curated
-// verbs (`views` / `news` / `quote` / `sentiment` / `research` / `hot` /
+// verbs (`views` / `news` / `quote` / `sentiment` / `hot` /
 // `lookup` / `digest` etc.) take precedence at the top level. Use `echopai raw <noun>
 // <verb>` for the raw mirror (e.g. `raw views feed`, `raw quote`, etc.).
 const rawCmd = new Command("raw").description("Raw 1:1 mirror of OpenAPI operations (escape hatch for power users / scripts)");
@@ -108,7 +146,7 @@ buildCommandTree(rawCmd, dispatch);
 rawCmd.addCommand(buildRawCallCommand());
 program.addCommand(rawCmd);
 // Top-level spec commands kept ONLY for nouns that don't conflict with a
-// curated verb. Curated-verb nouns (views/news/quote/sentiment/research/hot
+// curated verb. Curated-verb nouns (views/news/quote/sentiment/hot
 // /lookup/digest) are NOT generated at top level — they go below in their canonical
 // curated form. Use `echopai raw <noun>` for the spec mirror.
 const CURATED_NOUNS = new Set([
@@ -116,11 +154,15 @@ const CURATED_NOUNS = new Set([
     "news",
     "quote",
     "sentiment",
-    "research",
     "hot",
     "lookup",
     "digest",
     "search",
+    "financials",
+    "announcements",
+    "market",
+    "concepts",
+    "limit-up",
 ]);
 const topLevelSpecDispatch = async (op, args) => {
     await dispatch(op, args);
@@ -135,19 +177,23 @@ for (const sub of topLevelStub.commands) {
 // Curated agent verbs (Phase 3.6+): task-level entries that wrap one or
 // more raw operations + map output for AI agents. Listed before tools so
 // `--help` shows them first.
-// Product priority (see feedback_views_over_news.md): views > research > news
+// Product priority (see feedback_views_over_news.md): views > news
 program.addCommand(buildLookupCommand());
 program.addCommand(buildDigestCommand()); // one-shot fan-out (Phase 5.1)
 program.addCommand(buildSearchCommand()); // hybrid semantic discovery (PLAN_SEARCH_SEMANTIC_UPGRADE)
 program.addCommand(buildQuoteCommand());
+program.addCommand(buildMarketCommand()); // session state (pre-open / open / lunch / closed)
 program.addCommand(buildViewsCommand()); // PRIMARY research source
-program.addCommand(buildResearchCommand()); // views quality signal layer
 program.addCommand(buildNewsCommand()); // supplementary breadth
+program.addCommand(buildAnnouncementsCommand()); // cninfo A-share disclosures (feed/stock/detail)
 program.addCommand(buildSentimentCommand());
 program.addCommand(buildHotCommand());
+program.addCommand(buildConceptsCommand()); // concept indices + alerts + bars + news/views
+program.addCommand(buildLimitUpCommand()); // 涨停股池 / 涨停统计 / 涨停趋势
 program.addCommand(buildChartCommand()); // single-code K-line
 program.addCommand(buildBarsBatchCommand()); // multi-code batch K-line (PR 3.2/3.3 server)
 program.addCommand(buildScanCommand()); // full-market scan (PR 3.4 server)
+program.addCommand(buildFinancialsCommand()); // fundamentals: quote-snapshot / pit / reports / series
 // hand-curated tools
 program.addCommand(buildLoginCommand());
 program.addCommand(buildLogoutCommand());
@@ -160,7 +206,15 @@ program.addCommand(buildWhoamiCommand());
 program.addCommand(buildDoctorCommand());
 program.addCommand(buildMcpCommand());
 program.addCommand(buildCompletionCommand());
+program.addCommand(buildWelcomeCommand());
+program.addCommand(buildUpgradeCommand());
 applyAiFirstHooks(program);
+// Bare `echopai` in a TTY → onboarding screen. Non-TTY / CI / piped output
+// falls through to commander's plain help (preserves AI-first invariant).
+if (shouldShowWelcome(process.argv)) {
+    printWelcome();
+    process.exit(0);
+}
 program.parseAsync(process.argv).catch((e) => {
     process.stderr.write(JSON.stringify({
         error: {

package/dist/runtime/invoker.js

@@ -23,6 +23,7 @@ import { generateIdempotencyKey, announceKey } from "./idempotency.js";
 import { writeStdout, writeStderr } from "./io.js";
 import { paginate, exitCodeForPaginateError } from "./paginator.js";
 import { renderError, isTtyHuman } from "./tty.js";
+import { maybeEmitUpdateBanner } from "./update_check.js";
 const Ajv = (AjvPkg.default ??
     AjvPkg);
 const addFormats = (addFormatsPkg.default ??
@@ -180,6 +181,7 @@ export async function invoke(op, args, ctx) {
             });
             await writeStderr(`[paginate] ${result.pages} pages, ${result.items} items\n`);
             trace(op, { exit_code: 0 });
+            maybeEmitUpdateBanner();
             process.exit(0);
         }
         catch (e) {
@@ -293,6 +295,7 @@ export async function invoke(op, args, ctx) {
     // 8. success path — render
     if (raw) {
         await writeStdout(bodyText + "\n");
+        maybeEmitUpdateBanner();
         process.exit(0);
     }
     const rawEnvelope = buildResponseEnvelope(bodyJson ?? bodyText, {
@@ -337,6 +340,7 @@ export async function invoke(op, args, ctx) {
         exit_code: 0,
         truncated: envelope.meta.truncated === true,
     });
+    maybeEmitUpdateBanner();
     process.exit(0);
 }
 function buildQueryString(params) {

package/dist/runtime/update_check.js

@@ -0,0 +1,120 @@
+/**
+ * Update-availability check — passive, AI-safe.
+ *
+ * 设计：
+ *   - 真正发网络的活儿在 detached child (`update_worker.ts`) 干，由 bin.ts
+ *     启动时 spawn + unref，父进程立刻继续。Worker 写 ~/.config/echopai/
+ *     update_cache.json，下次 CLI 启动时 sync 读 cache → 决定是否打 banner。
+ *   - 这里只做 sync reader + 比较 + emit banner。任何 IO / 解析失败都吞掉
+ *     当作"没有可用更新"——CLI 自更新链路任何环节都不该让正常命令失败。
+ *
+ * AI-safe / agent-safe 规则：
+ *   - 默认只在 stderr.isTTY 时 emit banner（agent 走 pipe 不 TTY，无污染）
+ *   - 环境变量 `ECHOPAI_DISABLE_UPDATE_CHECK=1` / `CI=1` 一律静默
+ *   - banner 是单行 dim ANSI，不破坏 NDJSON / JSON envelope（stdout 不动）
+ */
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { CLI_VERSION } from "../version.js";
+export const UPDATE_CACHE_PATH = path.join(os.homedir(), ".config", "echopai", "update_cache.json");
+/** Pure semver-lite comparator. Pre-release suffixes are best-effort sorted
+ *  lexicographically AFTER the numeric tuple, so `2.3.0-beta.1 < 2.3.0`. */
+export function compareSemver(a, b) {
+    const parse = (s) => {
+        const [core, pre = ""] = s.replace(/^v/, "").split("-", 2);
+        const nums = core.split(".").map((n) => Number.parseInt(n, 10) || 0);
+        return { nums, pre };
+    };
+    const pa = parse(a);
+    const pb = parse(b);
+    const len = Math.max(pa.nums.length, pb.nums.length);
+    for (let i = 0; i < len; i++) {
+        const d = (pa.nums[i] ?? 0) - (pb.nums[i] ?? 0);
+        if (d !== 0)
+            return d > 0 ? 1 : -1;
+    }
+    // pre-release: empty > non-empty (release > prerelease per semver)
+    if (pa.pre === pb.pre)
+        return 0;
+    if (pa.pre === "")
+        return 1;
+    if (pb.pre === "")
+        return -1;
+    return pa.pre < pb.pre ? -1 : 1;
+}
+export function isNewer(latest, current) {
+    try {
+        return compareSemver(latest, current) > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Sync read; returns null on any error (missing file / parse fail / etc.). */
+export function readCachedUpdate() {
+    try {
+        const raw = readFileSync(UPDATE_CACHE_PATH, "utf-8");
+        const obj = JSON.parse(raw);
+        if (typeof obj.checked_at === "string" &&
+            typeof obj.current === "string" &&
+            typeof obj.latest === "string") {
+            return obj;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Best-effort cache write (atomic via tmp + rename). Returns true on success. */
+export function writeCachedUpdate(info) {
+    try {
+        mkdirSync(path.dirname(UPDATE_CACHE_PATH), { recursive: true });
+        const tmp = UPDATE_CACHE_PATH + "." + process.pid + ".tmp";
+        writeFileSync(tmp, JSON.stringify(info) + "\n", { encoding: "utf-8" });
+        // Atomic rename within same dir
+        renameSync(tmp, UPDATE_CACHE_PATH);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Returns whether banner emission is currently allowed (TTY + no opt-out). */
+export function isUpdateBannerAllowed() {
+    if (process.env.ECHOPAI_DISABLE_UPDATE_CHECK)
+        return false;
+    if (process.env.CI)
+        return false;
+    // banner goes to stderr; only emit if user is at an interactive terminal
+    if (!process.stderr.isTTY)
+        return false;
+    return true;
+}
+/**
+ * Emit a single-line banner to stderr if cache shows a newer version.
+ * Idempotent within a single process: only emits once even if called many
+ * times (e.g. from both executeVerb and welcome screen).
+ */
+let bannerEmittedThisProcess = false;
+export function maybeEmitUpdateBanner(stream = process.stderr) {
+    if (bannerEmittedThisProcess)
+        return;
+    if (!isUpdateBannerAllowed())
+        return;
+    const info = readCachedUpdate();
+    if (!info)
+        return;
+    if (!isNewer(info.latest, CLI_VERSION))
+        return;
+    bannerEmittedThisProcess = true;
+    // dim cyan, single line, prefixed with sparkles
+    const dim = "\x1b[2m";
+    const reset = "\x1b[0m";
+    stream.write(`${dim}✨ echopai v${info.latest} available (you have v${CLI_VERSION}) — run \`echopai upgrade\`${reset}\n`);
+}
+/** Test hook: reset the once-per-process gate. */
+export function _resetBannerGateForTests() {
+    bannerEmittedThisProcess = false;
+}

package/dist/runtime/update_worker.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Detached update-check worker. Spawned by `bin.ts` at startup
+ * with `detached: true, stdio: 'ignore'` + `child.unref()` so the parent
+ * exits immediately while this process finishes the registry fetch in the
+ * background.
+ *
+ * Contract:
+ *   - argv[2] = current CLI version (informational, stored in cache)
+ *   - reads cache mtime; if < 24h old, exits 0 without network
+ *   - else GET https://registry.npmjs.org/echopai/latest with 5s timeout,
+ *     parses { version }, writes ~/.config/echopai/update_cache.json
+ *   - all errors swallowed (worker exit 0); next invocation retries
+ *
+ * Never writes to stdout/stderr. Never throws. Cap process time at ~6s
+ * via AbortController to avoid lingering processes on flaky networks.
+ */
+import { statSync } from "node:fs";
+import { fetch } from "undici";
+import { UPDATE_CACHE_PATH, writeCachedUpdate, } from "./update_check.js";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+const FETCH_TIMEOUT_MS = 5_000;
+const REGISTRY_URL = "https://registry.npmjs.org/echopai/latest";
+async function main() {
+    const current = process.argv[2] ?? "0.0.0";
+    // Skip if cache fresh
+    try {
+        const stat = statSync(UPDATE_CACHE_PATH);
+        if (Date.now() - stat.mtimeMs < CACHE_TTL_MS)
+            return;
+    }
+    catch {
+        // missing cache — proceed to fetch
+    }
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch(REGISTRY_URL, {
+            headers: { Accept: "application/json" },
+            signal: ac.signal,
+        });
+        if (!res.ok)
+            return;
+        const body = (await res.json());
+        const latest = body?.version;
+        if (!latest || typeof latest !== "string")
+            return;
+        const info = {
+            checked_at: new Date().toISOString(),
+            current,
+            latest,
+        };
+        writeCachedUpdate(info);
+    }
+    catch {
+        // network / abort / JSON parse — silent
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// Don't propagate errors; this worker is best-effort.
+main().catch(() => { });

package/dist/runtime/verb_cmd.js

@@ -12,6 +12,7 @@
 import { resolveCredentials, AuthMissingError } from "./auth.js";
 import { CallApiError } from "./errors.js";
 import { isTtyHuman, renderError } from "./tty.js";
+import { maybeEmitUpdateBanner } from "./update_check.js";
 import { CLI_VERSION } from "../version.js";
 /**
  * Run a verb handler end-to-end:
@@ -38,6 +39,7 @@ export async function executeVerb(handler) {
             cliVersion: CLI_VERSION,
         });
         process.stdout.write(JSON.stringify(env) + "\n");
+        maybeEmitUpdateBanner();
         process.exit(0);
     }
     catch (e) {

package/dist/tools/upgrade.js

@@ -0,0 +1,103 @@
+/**
+ * `echopai upgrade` — explicit "check for + show upgrade command" entry.
+ *
+ * Three flavors:
+ *   - `echopai upgrade`               → 用 cache（无网络）+ 打印 envelope
+ *                                       (current / latest / command)
+ *   - `echopai upgrade --check`       → 强制走 npm registry，刷新 cache
+ *   - `echopai upgrade --check --exec` → 刷新 cache 后真跑 `npm i -g echopai@latest`
+ *                                       （透传 stdio；非 0 退出码传递）
+ *
+ * AI-first envelope on stdout（带 meta.checked_at），错误走 stderr JSON。
+ * 永远不会 exec npm 除非显式 --exec。
+ */
+import { spawnSync } from "node:child_process";
+import { Command, Option } from "commander";
+import { fetch } from "undici";
+import { CLI_VERSION, } from "../version.js";
+import { isNewer, readCachedUpdate, writeCachedUpdate, } from "../runtime/update_check.js";
+const REGISTRY_URL = "https://registry.npmjs.org/echopai/latest";
+const FETCH_TIMEOUT_MS = 5_000;
+async function fetchLatest() {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch(REGISTRY_URL, {
+            headers: { Accept: "application/json" },
+            signal: ac.signal,
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body?.version === "string" ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function emitJson(data, meta = {}) {
+    process.stdout.write(JSON.stringify({ data, meta }) + "\n");
+}
+function emitErr(code, message, exit = 2) {
+    process.stderr.write(JSON.stringify({ error: { code, message } }) + "\n");
+    process.exit(exit);
+}
+export function buildUpgradeCommand() {
+    const cmd = new Command("upgrade").description("Check for + show install command for the latest echopai release (no auto-exec unless --exec).");
+    cmd.addOption(new Option("--check", "Force fresh registry fetch (skip 24h cache)"));
+    cmd.addOption(new Option("--exec", "Actually run `npm i -g echopai@latest` (default: print command only)"));
+    cmd.action(async (opts) => {
+        let info = opts.check ? null : readCachedUpdate();
+        if (!info || opts.check) {
+            const latest = await fetchLatest();
+            if (!latest) {
+                emitErr("network_error", "Failed to reach npm registry (timeout or non-200). Try again later.");
+            }
+            info = {
+                checked_at: new Date().toISOString(),
+                current: CLI_VERSION,
+                latest,
+            };
+            writeCachedUpdate(info);
+        }
+        const newer = isNewer(info.latest, CLI_VERSION);
+        const installCmd = "npm i -g echopai@latest";
+        if (!newer) {
+            emitJson({
+                current: CLI_VERSION,
+                latest: info.latest,
+                status: "up_to_date",
+                message: `Already on the latest version (v${CLI_VERSION}).`,
+            }, { checked_at: info.checked_at, source: opts.check ? "registry" : "cache" });
+            process.exit(0);
+        }
+        // Newer available
+        if (opts.exec) {
+            // Run npm i -g with inherited stdio so user sees real-time progress.
+            // Don't shell-out — use direct args to avoid quoting issues.
+            const r = spawnSync("npm", ["i", "-g", `echopai@${info.latest}`], { stdio: "inherit" });
+            if (r.status === 0) {
+                emitJson({
+                    current: CLI_VERSION,
+                    latest: info.latest,
+                    status: "upgraded",
+                    message: `Upgraded to v${info.latest}. Re-run any command to load the new version.`,
+                }, { checked_at: info.checked_at, exec: true });
+                process.exit(0);
+            }
+            emitErr("exec_failed", `npm i -g failed with exit ${r.status ?? "unknown"}. Run manually: ${installCmd}`);
+        }
+        emitJson({
+            current: CLI_VERSION,
+            latest: info.latest,
+            status: "update_available",
+            command: installCmd,
+            message: `v${info.latest} is available. Run: ${installCmd}  (or pass --exec to run it now)`,
+        }, { checked_at: info.checked_at, source: opts.check ? "registry" : "cache" });
+        process.exit(0);
+    });
+    return cmd;
+}