echopai 2.2.0 → 2.3.0

package/dist/bin.js

@@ -14,22 +14,52 @@
  *
  * 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, buildFinancialsCommand, buildHotCommand, buildLookupCommand, buildNewsCommand, buildQuoteCommand, 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")
@@ -51,13 +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" +
-    "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");
+    .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
@@ -123,6 +159,10 @@ const CURATED_NOUNS = new Set([
     "digest",
     "search",
     "financials",
+    "announcements",
+    "market",
+    "concepts",
+    "limit-up",
 ]);
 const topLevelSpecDispatch = async (op, args) => {
     await dispatch(op, args);
@@ -142,10 +182,14 @@ 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(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)
@@ -163,6 +207,7 @@ 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).

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;
+}

package/dist/tools/welcome.js

@@ -14,6 +14,7 @@
 import { Command } from "commander";
 import { resolveCredentials, AuthMissingError } from "../runtime/auth.js";
 import { bold, cyan, dim, green, isTtyHuman, yellow } from "../runtime/tty.js";
+import { maybeEmitUpdateBanner } from "../runtime/update_check.js";
 import { CLI_VERSION } from "../version.js";
 function maskKey(key) {
     // eps_live_<lookup>_<secret> → keep prefix + first 4 of lookup + masked tail.
@@ -52,7 +53,7 @@ const COMMAND_GROUPS = [
     {
         title: "🔍 快速检索",
         items: [
-            { cmd: "echopai lookup --text 茅台", note: "中文名 / 拼音首字母 → canonical_code" },
+            { cmd: "echopai lookup --text 贵州茅台", note: "中文名 / 拼音首字母 → canonical_code" },
             { cmd: "echopai digest --code SSE:600519", note: "一键研究摘要（5 桶 fan-out，容忍部分失败）" },
             { cmd: "echopai search --query \"AI 算力\"", note: "题材 / 概念语义搜索" },
         ],
@@ -61,13 +62,40 @@ const COMMAND_GROUPS = [
         title: "📈 实时行情",
         items: [
             { cmd: "echopai quote --codes \"SSE:600519,SZSE:000001\"", note: "1-200 只实时报价" },
-            { cmd: "echopai sentiment", note: "市场情绪总览（涨跌停 / 宽度 / 分化）" },
-            { cmd: "echopai hot", note: "东方财富热门股榜（综合搜索 / 关注 / 评论）" },
+            { cmd: "echopai market status", note: "A 股会话状态（pre-open/open/lunch/closed）+ 节假日" },
+            { cmd: "echopai market movers --sort pct --top 20", note: "/market 涨幅榜 top 20（pct/pct_asc/speed/amount/turnover/total_mv）" },
+            { cmd: "echopai market movers --sort speed --top 30", note: "3 分钟涨速榜（短线脉冲）" },
+            { cmd: "echopai market movers --sort amount --exchange SSE", note: "上证成交额榜" },
+            { cmd: "echopai sentiment", note: "市场情绪总览（实时；涨跌停 / 宽度 / 分化）" },
+            { cmd: "echopai sentiment overview --date 2026-05-20", note: "任意历史日的情绪聚合（最后一分钟）" },
+            { cmd: "echopai sentiment breadth --date 2026-05-20", note: "全天 ~241 分钟时序（任意日）" },
+            { cmd: "echopai sentiment turnover --date 2026-05-20 --days 5", note: "成交额时序 + 5 日同分钟同比" },
+            { cmd: "echopai hot", note: "机构推荐热股榜" },
             { cmd: "echopai scan", note: "全市场快照（约 5800 只）" },
         ],
     },
     {
-        title: "💰 基本面 / 估值",
+        title: "🚀 涨停板",
+        items: [
+            { cmd: "echopai limit-up summary", note: "涨停数 / 炸板数 / 跌停数 / 连板梯队" },
+            { cmd: "echopai limit-up pool", note: "当日涨停股逐股明细（连板 / 封单 / 一字板）" },
+            { cmd: "echopai limit-up history --days 30", note: "近 N 日涨停 / 最高连板趋势" },
+        ],
+    },
+    {
+        title: "🧩 概念板块",
+        items: [
+            { cmd: "echopai concepts list --sort pct", note: "概念涨幅榜（pct/amount/limit_up/stock_count/speed）" },
+            { cmd: "echopai concepts list --sort speed", note: "概念 3 分钟涨速榜（客户端排序 speed_3min）" },
+            { cmd: "echopai concepts alerts", note: "当前激活概念异动（big_move / limit_up_cluster）" },
+            { cmd: "echopai concepts show <concept_id>", note: "单概念 meta + 成份股 + 最新行情" },
+            { cmd: "echopai concepts daily-bars <concept_id> --from ... --to ...", note: "概念指数 K 线（链式等权 base 1000）" },
+            { cmd: "echopai concepts news <concept_id>", note: "概念关联新闻（ILIKE）" },
+            { cmd: "echopai concepts views <concept_id>", note: "概念关联券商观点（主源研究）" },
+        ],
+    },
+    {
+        title: "💰 财务数据",
         items: [
             { cmd: "echopai financials quote-snapshot --code SSE:600519", note: "估值快照 14 字段（PE/PB/PS/换手率/股息率/量比）★头牌★" },
             { cmd: "echopai financials pit --code SSE:600519 --date 2024-11-01", note: "Point-in-time 财务指标（回测防穿越）" },
@@ -76,10 +104,13 @@ const COMMAND_GROUPS = [
         ],
     },
     {
-        title: "📰 研究 / 资讯",
+        title: "📰 市场观点/研究/资讯",
         items: [
-            { cmd: "echopai views --code SSE:600519", note: "★主源★ 卖方研报 / 分析师观点（含 research_entity_id 归因）" },
+            { cmd: "echopai views --code SSE:600519", note: "★主源★ 卖方研报 / 分析师观点" },
             { cmd: "echopai news search --query AI --since-hours 24", note: "辅源新闻 / 简讯（短时窗）" },
+            { cmd: "echopai announcements feed --type annual_report", note: "全市场公告 feed（cninfo，按 published_at desc）" },
+            { cmd: "echopai announcements stock --code SSE:600519 --since-days 30", note: "单股公告历史窗口（最长 5 年）" },
+            { cmd: "echopai announcements detail <uuid>", note: "单条公告完整正文 + meta" },
         ],
     },
     {
@@ -103,6 +134,7 @@ const POINTERS = [
     { cmd: "echopai whoami", note: "在线检查 token 能力 / scopes" },
     { cmd: "echopai doctor", note: "诊断鉴权 / 网络连通性" },
     { cmd: "echopai status", note: "查看本地 profile + 鉴权状态" },
+    { cmd: "echopai upgrade [--exec]", note: "检查新版（24h cache），--exec 直接 npm i -g 升级" },
 ];
 const BANNER_PLAIN = [
     "  ███████  ██████ ██   ██  ██████  ██████   █████  ██",
@@ -155,7 +187,7 @@ export function renderWelcome(now = () => new Date()) {
         lines.push(`    ${padRight(cyan(it.cmd), widest + 4)}  ${dim(it.note)}`);
     }
     lines.push("");
-    lines.push(`  ${dim("文档: https://docs.echopai.com  ·  反馈: https://github.com/evanzhangx/EchoPulse/issues")}`);
+    lines.push(`  ${dim("官网: https://www.echopai.com  ·  反馈: service@echopai.com")}`);
     lines.push("");
     // Timestamp footer so users know this isn't a stale cache
     const ts = now().toISOString().replace("T", " ").slice(0, 19);
@@ -166,6 +198,9 @@ export function renderWelcome(now = () => new Date()) {
 /** Print welcome screen to stdout (no exit — caller decides). */
 export function printWelcome() {
     process.stdout.write(renderWelcome());
+    // Surface available update from local cache (worker refreshes it in the
+    // background). No network call here — fast even when there's nothing to say.
+    maybeEmitUpdateBanner();
 }
 /**
  * Decide whether bare `echopai` (no args, no flags) should show the welcome