echopai 2.1.0 → 2.3.0

package/dist/tools/welcome.js

@@ -0,0 +1,225 @@
+/**
+ * `echopai` (bare) / `echopai welcome` — onboarding screen.
+ *
+ * Goal: give a TTY user a Claude-Code-style landing page when they type
+ * `echopai` with no args. Banner → auth status → grouped command examples
+ * → pointers to deeper help. AI / CI / non-TTY callers fall back to
+ * commander's plain help (handled by the bin.ts dispatcher).
+ *
+ * No network calls. We probe credentials locally (env / config file) only —
+ * a live `whoami` would slow the screen and is the wrong default for the
+ * "user just typed `echopai`" path. `echopai status` / `echopai whoami`
+ * cover the live-check use case.
+ */
+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.
+    if (key.length <= 16)
+        return "***";
+    return key.slice(0, 13) + "***";
+}
+function snapshotAuth() {
+    try {
+        const creds = resolveCredentials({});
+        if (creds.profile) {
+            return {
+                state: "profile",
+                profile: creds.profile,
+                keyHint: maskKey(creds.key),
+                baseUrl: creds.baseUrl,
+            };
+        }
+        return { state: "env", keyHint: maskKey(creds.key), baseUrl: creds.baseUrl };
+    }
+    catch (e) {
+        if (e instanceof AuthMissingError)
+            return { state: "missing" };
+        throw e;
+    }
+}
+/** Right-pad a string to width `w`, ignoring ANSI escapes for length. */
+function padRight(s, w) {
+    // strip ANSI for length measurement
+    // eslint-disable-next-line no-control-regex
+    const visible = s.replace(/\x1b\[[0-9;]*m/g, "");
+    const pad = Math.max(0, w - visible.length);
+    return s + " ".repeat(pad);
+}
+const COMMAND_GROUPS = [
+    {
+        title: "🔍 快速检索",
+        items: [
+            { cmd: "echopai lookup --text 贵州茅台", note: "中文名 / 拼音首字母 → canonical_code" },
+            { cmd: "echopai digest --code SSE:600519", note: "一键研究摘要（5 桶 fan-out，容忍部分失败）" },
+            { cmd: "echopai search --query \"AI 算力\"", note: "题材 / 概念语义搜索" },
+        ],
+    },
+    {
+        title: "📈 实时行情",
+        items: [
+            { cmd: "echopai quote --codes \"SSE:600519,SZSE:000001\"", note: "1-200 只实时报价" },
+            { 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: "🚀 涨停板",
+        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 财务指标（回测防穿越）" },
+            { cmd: "echopai financials reports --code SSE:600519 --kind annual", note: "最近 N 期财务报告（~25 字段/期）" },
+            { cmd: "echopai financials series --code SSE:600519 --metric roe_simple", note: "单指标历史时间序列" },
+        ],
+    },
+    {
+        title: "📰 市场观点/研究/资讯",
+        items: [
+            { 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" },
+        ],
+    },
+    {
+        title: "📊 K 线",
+        items: [
+            { cmd: "echopai chart --code SSE:600519 --from 2026-01-01 --to 2026-05-01", note: "单只 K 线（日线 / 分钟线）" },
+            { cmd: "echopai bars-batch --codes A,B,C --from ... --to ...", note: "批量 K 线（≤100 只）" },
+        ],
+    },
+    {
+        title: "🤖 AI 集成",
+        items: [
+            { cmd: "echopai mcp serve", note: "启动 MCP stdio 服务（Claude Desktop / Cursor / Claude Code）" },
+            { cmd: "echopai schema export", note: "导出全部 operation schema 给 agent 喂养" },
+        ],
+    },
+];
+const POINTERS = [
+    { cmd: "echopai --help", note: "完整命令树" },
+    { cmd: "echopai <verb> --help", note: "查看单个命令的参数和示例" },
+    { 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 = [
+    "  ███████  ██████ ██   ██  ██████  ██████   █████  ██",
+    "  ██      ██      ██   ██ ██    ██ ██   ██ ██   ██ ██",
+    "  █████   ██      ███████ ██    ██ ██████  ███████ ██",
+    "  ██      ██      ██   ██ ██    ██ ██      ██   ██ ██",
+    "  ███████  ██████ ██   ██  ██████  ██      ██   ██ ██",
+];
+export function renderWelcome(now = () => new Date()) {
+    const lines = [];
+    const auth = snapshotAuth();
+    // Banner
+    lines.push("");
+    for (const row of BANNER_PLAIN)
+        lines.push(cyan(row));
+    lines.push("");
+    lines.push(`  ${bold("EchoPai CLI")} ${dim("v" + CLI_VERSION)}  ${dim("·")}  ${dim("面向 AI Agent 的 A 股数据接入终端")}`);
+    lines.push("");
+    // Auth status
+    if (auth.state === "missing") {
+        lines.push(`  ${yellow("●")} ${bold("未登录")} ${dim("—")} 运行 ${cyan("`echopai login --key eps_live_<lookup>_<secret>`")} 或设置环境变量 ${cyan("ECHOPAI_KEY")}`);
+    }
+    else if (auth.state === "env") {
+        lines.push(`  ${green("●")} ${bold("已登录")}（环境变量 ${cyan("ECHOPAI_KEY")}）${dim(`(${auth.keyHint})`)}  →  ${dim(auth.baseUrl)}`);
+    }
+    else {
+        lines.push(`  ${green("●")} ${bold("已登录")} profile ${cyan(auth.profile)} ${dim(`(${auth.keyHint})`)}  →  ${dim(auth.baseUrl)}`);
+    }
+    lines.push("");
+    // Command groups
+    lines.push(`  ${dim("── 常用命令 ─────────────────────────────────────────────────")}`);
+    lines.push("");
+    // Reserve column 1 for cmd, column 2 for note. Compute padding from the
+    // widest cmd across all groups to keep alignment stable.
+    const widest = Math.min(72, COMMAND_GROUPS.flatMap((g) => g.items)
+        .map((it) => it.cmd.length)
+        .reduce((a, b) => Math.max(a, b), 0));
+    for (const group of COMMAND_GROUPS) {
+        lines.push(`  ${bold(group.title)}`);
+        for (const it of group.items) {
+            const cmd = cyan(it.cmd);
+            lines.push(`    ${padRight(cmd, widest + 4)}  ${dim(it.note)}`);
+        }
+        lines.push("");
+    }
+    // Pointers
+    lines.push(`  ${dim("── 更多 ─────────────────────────────────────────────────────")}`);
+    lines.push("");
+    for (const it of POINTERS) {
+        lines.push(`    ${padRight(cyan(it.cmd), widest + 4)}  ${dim(it.note)}`);
+    }
+    lines.push("");
+    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);
+    lines.push(`  ${dim("生成于 " + ts + " UTC · Ctrl+C 退出")}`);
+    lines.push("");
+    return lines.join("\n");
+}
+/** 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
+ * screen. False for AI / CI / piped output — they get commander's plain help.
+ */
+export function shouldShowWelcome(argv) {
+    // node + script + (no extra args)
+    if (argv.length !== 2)
+        return false;
+    if (!isTtyHuman)
+        return false;
+    if (process.env.CI)
+        return false;
+    return true;
+}
+export function buildWelcomeCommand() {
+    return new Command("welcome")
+        .description("显示欢迎屏（banner + 常用命令 + 鉴权状态）")
+        .action(() => {
+        printWelcome();
+    });
+}

package/dist/verbs/announcements.js

@@ -0,0 +1,195 @@
+/**
+ * `echopai announcements ...` + MCP tools `announcements_feed` /
+ * `announcements_stock` / `announcements_detail`.
+ *
+ * A 股公告 (cninfo 主源)：
+ *   - feed    —— 全市场最近公告，按 published_at desc
+ *   - stock   —— 指定 canonical_code 的公告历史窗口（最长 5 年）
+ *   - detail  —— 单条公告完整正文（content_md + content_text + meta）
+ *
+ * 三个 op 共享 `announcements:read` scope，calling 协议参数与底层 OpenAPI
+ * 一致（type slug / since_days 等）。MCP 注册成三个 discrete tool，AI agent
+ * 可按 "我要看 X 的财报披露" / "今天市场公告" / "把这条公告全文给我" 各自取用。
+ */
+import { Command, Option } from "commander";
+import { z } from "zod";
+import { OPERATIONS } from "../_generated/operations.js";
+import { executeVerb, emitVerbError } from "../runtime/verb_cmd.js";
+import { callOp } from "../runtime/verb_runner.js";
+const CODE_RE = /^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$/;
+const ISO_DATETIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?$/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const announcementsFeedSpec = {
+    name: "announcements_feed",
+    description: "Recent A-share announcement feed (cninfo source, sorted by published_at desc). Filter by `type` slug (e.g. annual_report / equity_change / restructuring) or `since` lower bound. Use when surveying market-wide disclosures over a recent window — for a specific stock prefer `announcements_stock`.",
+    inputSchema: {
+        type: z
+            .string()
+            .max(64)
+            .optional()
+            .describe("分类 slug 过滤（如 annual_report / equity_change / restructuring）。"),
+        since: z
+            .string()
+            .regex(ISO_DATETIME_RE)
+            .optional()
+            .describe("ISO datetime 下限（published_at >= since）。"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .default(50)
+            .describe("Max items (1-200, default 50)"),
+        offset: z
+            .number()
+            .int()
+            .min(0)
+            .default(0)
+            .describe("Pagination offset"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["announcements.feed"];
+        if (!op)
+            throw new Error("announcements.feed op missing");
+        const callArgs = {
+            limit: args.limit,
+            offset: args.offset,
+        };
+        if (args.type)
+            callArgs.type = args.type;
+        if (args.since)
+            callArgs.since = args.since;
+        return callOp(op, callArgs, ctx);
+    },
+    backingOps: ["announcements.feed"],
+};
+export const announcementsStockSpec = {
+    name: "announcements_stock",
+    description: "Announcement history for a single A-share security (cninfo). Default lookback 30 days, max 5 years. AH dual-listing: pass the A-share canonical (announcements are A-share only — HK side has separate HKEX disclosures not covered here).",
+    inputSchema: {
+        code: z
+            .string()
+            .regex(CODE_RE)
+            .describe("A-share canonical code (e.g. SSE:600519)"),
+        since_days: z
+            .number()
+            .int()
+            .min(1)
+            .max(1825)
+            .default(30)
+            .describe("Lookback window in days (1-1825, default 30)"),
+        type: z
+            .string()
+            .max(64)
+            .optional()
+            .describe("分类 slug 过滤（与 feed 同集合）"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .default(50)
+            .describe("Max items (1-200, default 50)"),
+        offset: z
+            .number()
+            .int()
+            .min(0)
+            .default(0)
+            .describe("Pagination offset"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["announcements.stock"];
+        if (!op)
+            throw new Error("announcements.stock op missing");
+        const callArgs = {
+            code: args.code,
+            since_days: args.since_days,
+            limit: args.limit,
+            offset: args.offset,
+        };
+        if (args.type)
+            callArgs.type = args.type;
+        return callOp(op, callArgs, ctx);
+    },
+    backingOps: ["announcements.stock"],
+};
+export const announcementsDetailSpec = {
+    name: "announcements_detail",
+    description: "Fetch one announcement by id (UUID from feed/stock items[].id). Returns full content_md + content_text + cninfo meta + parse status. Use when the summary in feed/stock is not enough and you need the full document body for citation or NLP.",
+    inputSchema: {
+        announcement_id: z
+            .string()
+            .regex(UUID_RE)
+            .describe("UUID (feed / stock 返回的 items[].id)"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["announcements.detail"];
+        if (!op)
+            throw new Error("announcements.detail op missing");
+        return callOp(op, { announcement_id: args.announcement_id }, ctx);
+    },
+    backingOps: ["announcements.detail"],
+};
+function clampInt(raw, min, max, fallback) {
+    const n = Math.floor(Number(raw));
+    if (!Number.isFinite(n))
+        return fallback;
+    if (n < min)
+        return min;
+    if (n > max)
+        return max;
+    return n;
+}
+export function buildAnnouncementsCommand() {
+    const cmd = new Command("announcements").description("A-share announcements (cninfo) — recent feed, per-stock history, single-item detail.");
+    const feed = cmd.command("feed").description(announcementsFeedSpec.description);
+    feed.addOption(new Option("--type <slug>", "Filter by 分类 slug (annual_report, equity_change, ...)"));
+    feed.addOption(new Option("--since <ISO-datetime>", "Lower bound published_at (RFC3339)"));
+    feed.addOption(new Option("--limit <n>", "Max items (1-200)").default("50"));
+    feed.addOption(new Option("--offset <n>", "Pagination offset").default("0"));
+    feed.action(async (opts) => {
+        if (!OPERATIONS["announcements.feed"]) {
+            emitVerbError("internal_error", "announcements.feed missing", undefined, 2);
+        }
+        const args = {
+            limit: clampInt(opts.limit, 1, 200, 50),
+            offset: Math.max(0, Math.floor(Number(opts.offset)) || 0),
+        };
+        if (opts.type)
+            args.type = opts.type;
+        if (opts.since)
+            args.since = opts.since;
+        await executeVerb(async (ctx) => announcementsFeedSpec.handler(args, ctx));
+    });
+    const stock = cmd.command("stock").description(announcementsStockSpec.description);
+    stock.addOption(new Option("--code <canonical_code>", "A-share canonical (e.g. SSE:600519)")
+        .makeOptionMandatory(true));
+    stock.addOption(new Option("--since-days <n>", "Lookback window in days (1-1825)").default("30"));
+    stock.addOption(new Option("--type <slug>", "Filter by 分类 slug"));
+    stock.addOption(new Option("--limit <n>", "Max items (1-200)").default("50"));
+    stock.addOption(new Option("--offset <n>", "Pagination offset").default("0"));
+    stock.action(async (opts) => {
+        if (!OPERATIONS["announcements.stock"]) {
+            emitVerbError("internal_error", "announcements.stock missing", undefined, 2);
+        }
+        const args = {
+            code: opts.code,
+            since_days: clampInt(opts.sinceDays, 1, 1825, 30),
+            limit: clampInt(opts.limit, 1, 200, 50),
+            offset: Math.max(0, Math.floor(Number(opts.offset)) || 0),
+        };
+        if (opts.type)
+            args.type = opts.type;
+        await executeVerb(async (ctx) => announcementsStockSpec.handler(args, ctx));
+    });
+    const detail = cmd
+        .command("detail <announcement_id>")
+        .description(announcementsDetailSpec.description);
+    detail.action(async (announcementId) => {
+        if (!OPERATIONS["announcements.detail"]) {
+            emitVerbError("internal_error", "announcements.detail missing", undefined, 2);
+        }
+        await executeVerb(async (ctx) => announcementsDetailSpec.handler({ announcement_id: announcementId }, ctx));
+    });
+    return cmd;
+}