echopai 2.2.0 → 2.3.0

package/dist/verbs/sentiment.js

@@ -1,5 +1,14 @@
 /**
- * `echopai sentiment [--scope <universe>]` + MCP tool `sentiment`.
+ * `echopai sentiment ...` + MCP tools `sentiment` (overview alias, BC) /
+ * `sentiment_overview` / `sentiment_breadth` / `sentiment_turnover` /
+ * `sentiment_pct_distribution`.
+ *
+ * 四个子端点全部支持 `--scope` 切换股票池；`overview` / `breadth` /
+ * `turnover` 进一步支持 `--date YYYY-MM-DD` 取历史任意交易日的当日聚合
+ * （盘中实时为 Redis cache，历史走 ClickHouse `market_breadth_intraday` /
+ * `market_turnover_intraday`）。`turnover` 还支持 `--days 1-5` 拉同分钟同比。
+ *
+ * 顶层 `echopai sentiment` 无子命令时仍走 overview（保持 v2.2.0 兼容）。
  */
 import { Command, Option } from "commander";
 import { z } from "zod";
@@ -14,33 +23,209 @@ const SCOPE_VALUES = [
     "chinext",
     "bse",
 ];
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+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;
+}
+/**
+ * Legacy `sentiment` spec — kept as alias of overview for v2.2.0 backward
+ * compatibility (MCP clients that registered `sentiment` keep working).
+ */
 export const sentimentSpec = {
     name: "sentiment",
-    description: "Aggregate market sentiment indicators (limit-up/down counts, breadth, divergence index, top movers). Defaults to all_a_ex_st (all A-shares ex-ST).",
+    description: "Aggregate market sentiment indicators (limit-up/down counts, breadth, divergence index, top movers). Defaults to all_a_ex_st (all A-shares ex-ST). Pass `at_date` (YYYY-MM-DD) for any historical trading day; omit for today's latest snapshot. Backward-compat alias of `sentiment_overview` — prefer the latter in new agent code.",
     inputSchema: {
         scope: z
             .enum(SCOPE_VALUES)
             .default("all_a_ex_st")
             .describe("Universe filter"),
+        at_date: z
+            .string()
+            .regex(DATE_RE)
+            .optional()
+            .describe("Trade date YYYY-MM-DD; omit for today's realtime snapshot"),
     },
     handler: async (args, ctx) => {
         const op = OPERATIONS["sentiment.overview"];
         if (!op)
             throw new Error("sentiment.overview op missing");
-        return callOp(op, { scope: args.scope }, ctx);
+        const callArgs = { scope: args.scope };
+        if (args.at_date)
+            callArgs.trade_date = args.at_date;
+        return callOp(op, callArgs, ctx);
     },
     backingOps: ["sentiment.overview"],
 };
-export function buildSentimentCommand() {
-    const cmd = new Command(sentimentSpec.name).description(sentimentSpec.description);
+export const sentimentOverviewSpec = {
+    name: "sentiment_overview",
+    description: "Aggregate sentiment snapshot for one trading day's latest minute: up/down/flat counts, limit-up/down, gt3/lt3 breadth, divergence index + label, MA20/50/200 breadth, 52w new high/low. `at_date` omitted = today realtime (Redis); explicit YYYY-MM-DD = historical from ClickHouse `market_breadth_intraday` last minute.",
+    inputSchema: {
+        scope: z.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
+        at_date: z
+            .string()
+            .regex(DATE_RE)
+            .optional()
+            .describe("Trade date YYYY-MM-DD; omit for today realtime"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["sentiment.overview"];
+        if (!op)
+            throw new Error("sentiment.overview op missing");
+        const callArgs = { scope: args.scope };
+        if (args.at_date)
+            callArgs.trade_date = args.at_date;
+        return callOp(op, callArgs, ctx);
+    },
+    backingOps: ["sentiment.overview"],
+};
+export const sentimentBreadthSpec = {
+    name: "sentiment_breadth",
+    description: "Intraday breadth time series for one trading day (up to 241 minute bars; 13:00 excluded due to sparse Sina ticks). `at_date` omitted = today (pre-open returns empty); explicit YYYY-MM-DD = historical replay. Returns per-minute rows of up/down/flat/limit_up/limit_down/breadth/divergence fields — same shape as `sentiment_overview` per row.",
+    inputSchema: {
+        scope: z.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
+        at_date: z
+            .string()
+            .regex(DATE_RE)
+            .optional()
+            .describe("Trade date YYYY-MM-DD; omit for today"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["sentiment.breadth"];
+        if (!op)
+            throw new Error("sentiment.breadth op missing");
+        const callArgs = { scope: args.scope };
+        if (args.at_date)
+            callArgs.trade_date = args.at_date;
+        return callOp(op, callArgs, ctx);
+    },
+    backingOps: ["sentiment.breadth"],
+};
+export const sentimentTurnoverSpec = {
+    name: "sentiment_turnover",
+    description: "Intraday turnover time series with `current_turnover` / `predicted_total` / `delta_vs_yesterday` headline fields. `at_date` omitted = today (pre-open returns nulls); explicit YYYY-MM-DD = historical. `days` (1-5) pulls that day + N-1 prior trading days for same-minute YoY comparison.",
+    inputSchema: {
+        scope: z.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
+        at_date: z
+            .string()
+            .regex(DATE_RE)
+            .optional()
+            .describe("Trade date YYYY-MM-DD; omit for today"),
+        days: z
+            .number()
+            .int()
+            .min(1)
+            .max(5)
+            .default(1)
+            .describe("at_date 当日 + 之前 days-1 天（1-5，默认 1）"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["sentiment.turnover"];
+        if (!op)
+            throw new Error("sentiment.turnover op missing");
+        const callArgs = { scope: args.scope, days: args.days };
+        if (args.at_date)
+            callArgs.trade_date = args.at_date;
+        return callOp(op, callArgs, ctx);
+    },
+    backingOps: ["sentiment.turnover"],
+};
+export const sentimentPctDistributionSpec = {
+    name: "sentiment_pct_distribution",
+    description: "Real-time A-share market pct-change distribution: bucket counts at ≤-10% / -9% / ... / +10% / 涨停, plus universe total. Snapshot only — historical replay not yet exposed.",
+    inputSchema: {},
+    handler: async (_args, ctx) => {
+        const op = OPERATIONS["sentiment.pct-distribution"];
+        if (!op)
+            throw new Error("sentiment.pct-distribution op missing");
+        return callOp(op, {}, ctx);
+    },
+    backingOps: ["sentiment.pct-distribution"],
+};
+function addScope(cmd) {
     cmd.addOption(new Option("--scope <universe>", "Universe filter")
         .choices([...SCOPE_VALUES])
         .default("all_a_ex_st"));
-    cmd.action(async (opts) => {
+}
+function addDate(cmd) {
+    cmd.addOption(new Option("--date <YYYY-MM-DD>", "Trade date; omit for today's realtime"));
+}
+export function buildSentimentCommand() {
+    const cmd = new Command("sentiment").description("Market sentiment — overview / breadth / turnover / pct-distribution; supports any historical trade_date via --date.");
+    // No-subcommand path: `echopai sentiment [--scope X]` → overview (BC with
+    // v2.2.0 where sentiment was a single-shot verb). NOTE: `--date` is
+    // intentionally NOT declared at parent level — commander would consume
+    // it from `sentiment overview --date X` and never propagate to the
+    // subcommand. For historical date queries, always use the explicit
+    // subcommand form: `echopai sentiment overview --date 2026-05-20`.
+    addScope(cmd);
+    cmd.action(async (opts, command) => {
+        // commander invokes parent action even when a subcommand runs unless
+        // we guard. Skip if any argv token after the noun is a registered
+        // subcommand name.
+        const subNames = new Set(command.commands.map((c) => c.name()));
+        const argv = process.argv.slice(2);
+        if (argv.some((tok) => subNames.has(tok)))
+            return;
         if (!OPERATIONS["sentiment.overview"]) {
             emitVerbError("internal_error", "sentiment.overview missing", undefined, 2);
         }
         await executeVerb(async (ctx) => sentimentSpec.handler({ scope: opts.scope }, ctx));
     });
+    const overview = cmd.command("overview").description(sentimentOverviewSpec.description);
+    addScope(overview);
+    addDate(overview);
+    overview.action(async (opts) => {
+        if (!OPERATIONS["sentiment.overview"]) {
+            emitVerbError("internal_error", "sentiment.overview missing", undefined, 2);
+        }
+        const args = { scope: opts.scope };
+        if (opts.date)
+            args.at_date = opts.date;
+        await executeVerb(async (ctx) => sentimentOverviewSpec.handler(args, ctx));
+    });
+    const breadth = cmd.command("breadth").description(sentimentBreadthSpec.description);
+    addScope(breadth);
+    addDate(breadth);
+    breadth.action(async (opts) => {
+        if (!OPERATIONS["sentiment.breadth"]) {
+            emitVerbError("internal_error", "sentiment.breadth missing", undefined, 2);
+        }
+        const args = { scope: opts.scope };
+        if (opts.date)
+            args.at_date = opts.date;
+        await executeVerb(async (ctx) => sentimentBreadthSpec.handler(args, ctx));
+    });
+    const turnover = cmd.command("turnover").description(sentimentTurnoverSpec.description);
+    addScope(turnover);
+    addDate(turnover);
+    turnover.addOption(new Option("--days <n>", "at_date 当日 + 之前 days-1 天 (1-5)").default("1"));
+    turnover.action(async (opts) => {
+        if (!OPERATIONS["sentiment.turnover"]) {
+            emitVerbError("internal_error", "sentiment.turnover missing", undefined, 2);
+        }
+        const args = {
+            scope: opts.scope,
+            days: clampInt(opts.days, 1, 5, 1),
+        };
+        if (opts.date)
+            args.at_date = opts.date;
+        await executeVerb(async (ctx) => sentimentTurnoverSpec.handler(args, ctx));
+    });
+    const pctDist = cmd
+        .command("pct-distribution")
+        .description(sentimentPctDistributionSpec.description);
+    pctDist.action(async () => {
+        if (!OPERATIONS["sentiment.pct-distribution"]) {
+            emitVerbError("internal_error", "sentiment.pct-distribution missing", undefined, 2);
+        }
+        await executeVerb(async (ctx) => sentimentPctDistributionSpec.handler({}, ctx));
+    });
     return cmd;
 }

package/dist/verbs/views.js

@@ -10,13 +10,15 @@ import { executeVerb, emitVerbError } from "../runtime/verb_cmd.js";
 import { callOp } from "../runtime/verb_runner.js";
 export const viewsSpec = {
     name: "views",
-    description: "PRIMARY research source for stock judgement: analyst views / sell-side reports / long-form opinion stream, with research_entity_id attribution. Prefer this over `news` when forming an investment opinion.",
+    description: "PRIMARY research source for stock judgement: analyst views / sell-side reports / long-form opinion stream, with research_entity_id attribution. Prefer this over `news` when forming an investment opinion. AH dual-listing: for an A+H listed company pass the A-share canonical to get the consolidated coverage (most domestic analyst views attribute to the A-share security); use HK code only if the user explicitly asks for the HK perspective.",
     inputSchema: {
         code: z
             .string()
-            .regex(/^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$/)
+            // Any-market：与 openapi components.schemas.CanonicalCodeAny 一致
+            // 研究/观点类 endpoint 不限 A 股；HK:00700 / US:AAPL 也允许（PR #D 拉齐）
+            .regex(/^((SSE|SZSE|BSE):[0-9]{6}|HK:[0-9]{5}|US:[A-Z][A-Z0-9.\-]{0,5})$/)
             .optional()
-            .describe("Filter by security canonical_code (e.g. SSE:600519)"),
+            .describe("Filter by security canonical_code (e.g. SSE:600519, HK:00700, US:AAPL)"),
         analyst: z.string().optional().describe("Analyst Chinese name (exact / fuzzy)"),
         institution: z.string().optional().describe("Broker / institution Chinese name"),
         since_days: z

package/dist/version.js

@@ -2,4 +2,4 @@
  * Pinned at build time. Don't read package.json at runtime — adds startup latency
  * and breaks bundling.
  */
-export const CLI_VERSION = "2.2.0";
+export const CLI_VERSION = "2.3.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echopai",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Command-line interface for the EchoPai Open Platform: stock-market data, news, analyst views, sentiment, signals, backtests.",
   "license": "MIT",
   "homepage": "https://echopai.com",