echopai 2.1.0 → 2.3.0

package/dist/verbs/news.js

@@ -10,12 +10,17 @@ import { executeVerb } from "../runtime/verb_cmd.js";
 import { callOp } from "../runtime/verb_runner.js";
 export const newsSpec = {
     name: "news",
-    description: "SUPPLEMENTARY news / market briefs (short time-horizon event stream). Use ONLY to fill gaps not covered by `views`; prefer `views` as the primary research source. With `query` → full-text search; without `query` → time-window feed.",
+    description: "SUPPLEMENTARY news / market briefs (short time-horizon event stream). Use ONLY to fill gaps not covered by `views`; prefer `views` as the primary research source. Three modes: `code` (canonical) → news mentioning that security; `query` (free text) → full-text search; neither → recent time-window feed. AH dual-listing: when filtering by `code` for an A+H listed company, pass the A-share canonical (e.g. SSE:601398) for consolidated coverage; HK side only if the user explicitly asks. Note: `query` is matched against news text, so passing a canonical_code as `query` will not work — use `code` for security filtering.",
     inputSchema: {
+        code: z
+            .string()
+            .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, HK:00700). Takes precedence over `query`."),
         query: z
             .string()
             .optional()
-            .describe("Free-text query (Chinese or English); omit for time-window feed"),
+            .describe("Free-text query (Chinese or English) matched against news content; omit for time-window feed. Do NOT pass canonical_code here — use `code` instead."),
         hours: z
             .number()
             .int()
@@ -26,6 +31,12 @@ export const newsSpec = {
         limit: z.number().int().min(1).max(100).default(20).describe("Max items"),
     },
     handler: async (args, ctx) => {
+        if (args.code) {
+            const op = OPERATIONS["news.list"];
+            if (!op)
+                throw new Error("news.list op missing");
+            return callOp(op, { security: args.code, since_hours: args.hours, limit: args.limit }, ctx);
+        }
         if (args.query) {
             const op = OPERATIONS["news.search"];
             if (!op)
@@ -37,7 +48,7 @@ export const newsSpec = {
             throw new Error("news.feed op missing");
         return callOp(op, {}, ctx);
     },
-    backingOps: ["news.search", "news.feed"],
+    backingOps: ["news.list", "news.search", "news.feed"],
 };
 function clamp(raw, min, max, fallback) {
     const n = Math.floor(Number(raw));
@@ -51,6 +62,7 @@ function clamp(raw, min, max, fallback) {
 }
 export function buildNewsCommand() {
     const cmd = new Command(newsSpec.name).description(newsSpec.description);
+    cmd.addOption(new Option("--code <canonical_code>", "Filter by security canonical_code (e.g. SSE:600519); takes precedence over --query"));
     cmd.addOption(new Option("--query <text>", "Free-text query; omit for time-window feed"));
     cmd.addOption(new Option("--hours <n>", "Lookback window (1-168 hours)").default("24"));
     cmd.addOption(new Option("--limit <n>", "Max items").default("20"));
@@ -59,6 +71,8 @@ export function buildNewsCommand() {
             hours: clamp(opts.hours, 1, 168, 24),
             limit: clamp(opts.limit, 1, 100, 20),
         };
+        if (opts.code)
+            args.code = opts.code;
         if (opts.query)
             args.query = opts.query;
         await executeVerb(async (ctx) => newsSpec.handler(args, ctx));

package/dist/verbs/quote.js

@@ -9,7 +9,7 @@ import { executeVerb, emitVerbError } from "../runtime/verb_cmd.js";
 import { callOp } from "../runtime/verb_runner.js";
 export const quoteSpec = {
     name: "quote",
-    description: "Real-time quote for 1-200 A-share securities (last price, volume, change %, bid/ask). For >200 codes use `scan` instead.",
+    description: "Real-time quote for 1-200 A-share securities (last price, volume, change %, bid/ask). For >200 codes use `scan` instead. AH dual-listing: HK codes are not supported here; for an A+H listed company use the A-share canonical (e.g. SSE:601398 not HK:01398).",
     inputSchema: {
         codes: z
             .array(z.string().regex(/^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$/))

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 (use `research` verb to query hit-rate). 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.1.0";
+export const CLI_VERSION = "2.3.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echopai",
-  "version": "2.1.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",

package/dist/verbs/research.js

@@ -1,44 +0,0 @@
-/**
- * `echopai research [--entity <id>]` + MCP tool `research`.
- *
- * Views quality signal layer.
- */
-import { Command, Option } from "commander";
-import { z } from "zod";
-import { OPERATIONS } from "../_generated/operations.js";
-import { executeVerb } from "../runtime/verb_cmd.js";
-import { callOp } from "../runtime/verb_runner.js";
-export const researchSpec = {
-    name: "research",
-    description: "Research-entity performance — hit rate / coverage / avg excess return. Pair with `views` (which returns research_entity_id per row) to assess analyst quality. Omit entity_id for aggregate top-performers list.",
-    inputSchema: {
-        entity_id: z
-            .string()
-            .optional()
-            .describe("Specific research_entity_id; omit for aggregate top-performers list"),
-    },
-    handler: async (args, ctx) => {
-        if (args.entity_id) {
-            const op = OPERATIONS["research.entity-performance"];
-            if (!op)
-                throw new Error("research.entity-performance op missing");
-            return callOp(op, { entity_id: args.entity_id }, ctx);
-        }
-        const op = OPERATIONS["research.entity-performance-list"];
-        if (!op)
-            throw new Error("research.entity-performance-list op missing");
-        return callOp(op, {}, ctx);
-    },
-    backingOps: ["research.entity-performance-list", "research.entity-performance"],
-};
-export function buildResearchCommand() {
-    const cmd = new Command(researchSpec.name).description(researchSpec.description);
-    cmd.addOption(new Option("--entity <id>", "Specific research_entity_id; omit for aggregate list"));
-    cmd.action(async (opts) => {
-        const args = {};
-        if (opts.entity)
-            args.entity_id = opts.entity;
-        await executeVerb(async (ctx) => researchSpec.handler(args, ctx));
-    });
-    return cmd;
-}