echopai 2.0.0 → 2.2.0

package/dist/bin.js

@@ -20,20 +20,21 @@ 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, buildSentimentCommand, buildViewsCommand, } from "./verbs/index.js";
+import { buildBarsBatchCommand, buildChartCommand, buildDigestCommand, buildFinancialsCommand, buildHotCommand, buildLookupCommand, 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 { buildWelcomeCommand, printWelcome, shouldShowWelcome } from "./tools/welcome.js";
 import { buildWhoamiCommand } from "./tools/whoami.js";
 import { CLI_VERSION } from "./version.js";
 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`.")
@@ -53,6 +54,7 @@ program
     .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");
@@ -100,7 +102,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 +110,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,10 +118,11 @@ const CURATED_NOUNS = new Set([
     "news",
     "quote",
     "sentiment",
-    "research",
     "hot",
     "lookup",
     "digest",
+    "search",
+    "financials",
 ]);
 const topLevelSpecDispatch = async (op, args) => {
     await dispatch(op, args);
@@ -134,18 +137,19 @@ 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(buildViewsCommand()); // PRIMARY research source
-program.addCommand(buildResearchCommand()); // views quality signal layer
 program.addCommand(buildNewsCommand()); // supplementary breadth
 program.addCommand(buildSentimentCommand());
 program.addCommand(buildHotCommand());
 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());
@@ -158,7 +162,14 @@ program.addCommand(buildWhoamiCommand());
 program.addCommand(buildDoctorCommand());
 program.addCommand(buildMcpCommand());
 program.addCommand(buildCompletionCommand());
+program.addCommand(buildWelcomeCommand());
 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/tools/welcome.js

@@ -0,0 +1,190 @@
+/**
+ * `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 { 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 sentiment", note: "市场情绪总览（涨跌停 / 宽度 / 分化）" },
+            { cmd: "echopai hot", note: "东方财富热门股榜（综合搜索 / 关注 / 评论）" },
+            { cmd: "echopai scan", note: "全市场快照（约 5800 只）" },
+        ],
+    },
+    {
+        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: "★主源★ 卖方研报 / 分析师观点（含 research_entity_id 归因）" },
+            { cmd: "echopai news search --query AI --since-hours 24", note: "辅源新闻 / 简讯（短时窗）" },
+        ],
+    },
+    {
+        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 + 鉴权状态" },
+];
+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://docs.echopai.com  ·  反馈: https://github.com/evanzhangx/EchoPulse/issues")}`);
+    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());
+}
+/**
+ * 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/digest.js

@@ -3,7 +3,7 @@
  *
  * Killer "one-shot research" verb:
  *
- *   one canonical_code  →  views + research + quote + sentiment + news
+ *   one canonical_code  →  views + quote + snapshot + sentiment + news
  *
  * Plan-doc §3.3 makes this the "agent's opening move": one call returns the
  * full picture of a security. Buckets stay separated (no ranking imposed) so
@@ -24,11 +24,13 @@
  *
  * Why these 5 ops in the fallback:
  *   - views.recent  : PRIMARY research signal (analyst opinions on this code)
- *   - research.entity-performance-list : quality layer for view authors
  *   - quote         : current price / change %
+ *   - financials.quote-snapshot : 14-field valuation (PE/PB/PS/换手/股息/量比) on this code
  *   - sentiment.overview : market regime context (not per-code; intentional —
  *     no per-code sentiment op exists)
- *   - news.search   : SUPPLEMENTARY breadth (event stream filter on code)
+ *   - news.list     : SUPPLEMENTARY breadth (canonical_code-exact news,
+ *                     via news_item_security mapping table — NOT keyword search,
+ *                     since article text never contains 'SSE:600519' literally)
  *
  * Windows differ on purpose: views=168h (7d), news=24h. Encodes the rule
  * that research time-horizon > news time-horizon.
@@ -40,11 +42,11 @@ import { CallApiError } from "../runtime/errors.js";
 import { executeVerb, emitVerbError } from "../runtime/verb_cmd.js";
 import { callOp } from "../runtime/verb_runner.js";
 /** Buckets in the order the description establishes (views first, news last). */
-const BUCKETS = ["views", "research", "quote", "sentiment", "news"];
+const BUCKETS = ["views", "quote", "snapshot", "sentiment", "news"];
 const CODE_REGEX = /^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$/;
 export const digestSpec = {
     name: "digest",
-    description: "One-shot research digest for a single security: fan-out across views (PRIMARY), research-entity performance, quote, market sentiment, and supplementary news. Returns separated buckets — does NOT rank views vs news for the agent. Partial failures surface in meta.partial_failures[] without poisoning successful buckets. Use as the agent's first call when asked 'what's going on with <stock>'.",
+    description: "One-shot research digest for a single security: fan-out across views (PRIMARY), quote, 14-field valuation snapshot (PE/PB/PS/turnover/dividend/volume-ratio), market sentiment, and supplementary news. Returns separated buckets — does NOT rank views vs news for the agent. Partial failures surface in meta.partial_failures[] without poisoning successful buckets. Use as the agent's first call when asked 'what's going on with <stock>'.",
     inputSchema: {
         code: z
             .string()
@@ -70,7 +72,7 @@ export const digestSpec = {
             .min(1)
             .max(50)
             .default(10)
-            .describe("Per-bucket item cap (views/news). Quote/sentiment/research aren't paginated here."),
+            .describe("Per-bucket item cap (views/news). Quote/snapshot/sentiment aren't paginated here."),
     },
     handler: async (args, ctx) => runDigest(args, ctx),
     // Backing ops are listed in two groups: digest.get is the primary
@@ -84,10 +86,10 @@ export const digestSpec = {
     backingOps: [
         "digest.get",
         "views.recent",
-        "research.entity-performance-list",
         "quote",
+        "financials.quote-snapshot",
         "sentiment.overview",
-        "news.search",
+        "news.list",
     ],
 };
 /**
@@ -153,10 +155,10 @@ function shouldFallbackToFanout(e) {
 function buildBucketCalls(args, ctx) {
     const opsRequired = {
         views: "views.recent",
-        research: "research.entity-performance-list",
         quote: "quote",
+        snapshot: "financials.quote-snapshot",
         sentiment: "sentiment.overview",
-        news: "news.search",
+        news: "news.list",
     };
     const calls = [];
     for (const bucket of BUCKETS) {
@@ -184,18 +186,18 @@ function buildBucketCalls(args, ctx) {
                     limit: args.limit_per_bucket,
                 };
                 break;
-            case "research":
-                opArgs = {};
-                break;
             case "quote":
                 opArgs = { codes: [args.code] };
                 break;
+            case "snapshot":
+                opArgs = { code: args.code };
+                break;
             case "sentiment":
                 opArgs = { scope: "all_a_ex_st" };
                 break;
             case "news":
                 opArgs = {
-                    query: args.code,
+                    security: args.code,
                     since_hours: args.news_hours,
                     limit: args.limit_per_bucket,
                 };

package/dist/verbs/financials.js

@@ -0,0 +1,212 @@
+/**
+ * `echopai financials ...` + MCP tools `financials_quote_snapshot` / `financials_pit`
+ * / `financials_reports` / `financials_series`.
+ *
+ * Headline endpoint is **quote-snapshot** — one-call 14-field valuation snapshot
+ * (PE / PB / PS / 换手率 / 股息率 / 量比 等), TDX + Sina 自算口径，对照过 Tushare。
+ *
+ * Three sibling endpoints surface deeper financials access for backtests /
+ * fundamentals research:
+ *   - pit     — point-in-time indicators at a given trade_date (anti-future-fn)
+ *   - reports — last N report-period snapshots (~25 fields each)
+ *   - series  — single-metric time series across periods
+ *
+ * MCP registers four discrete tools so an agent can pick the right granularity;
+ * CLI surfaces a single `financials` noun with four sub-commands (preserves
+ * the spec-driven shape from openapi.yaml).
+ */
+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 DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const REPORT_KINDS = ["Q1", "H1", "Q3", "annual", "preliminary"];
+export const financialsQuoteSnapshotSpec = {
+    name: "financials_quote_snapshot",
+    description: "One-call 14-field valuation snapshot for one A-share: PE / PE-TTM / PB / PS / PS-TTM, total/float/free share, total/circ market cap, turnover rate (raw & float), volume ratio, dividend yield (last-year & TTM). Computed from TDX + Sina real-time (no Tushare dependency), validated against Tushare daily_basic. Use `date` to fetch a historical snapshot; omit for real-time.",
+    inputSchema: {
+        code: z
+            .string()
+            .regex(CODE_RE)
+            .describe("Canonical A-share code (e.g. SSE:600519)"),
+        date: z
+            .string()
+            .regex(DATE_RE)
+            .optional()
+            .describe("Trade date YYYY-MM-DD; omit for real-time snapshot"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["financials.quote-snapshot"];
+        if (!op)
+            throw new Error("financials.quote-snapshot op missing from codegen");
+        const callArgs = { code: args.code };
+        if (args.date)
+            callArgs.date = args.date;
+        return callOp(op, callArgs, ctx);
+    },
+    backingOps: ["financials.quote-snapshot"],
+};
+export const financialsPitSpec = {
+    name: "financials_pit",
+    description: "Point-in-time financial indicators for one A-share at a given trade_date. Returns the latest report visible AS OF that date (announce_date ≤ date; conservative 90-day fallback when announce_date is missing). Designed for backtests / AI agents to avoid look-ahead bias. ~25 fields incl. EPS / BPS / ROE / margins / revenue / net-income / equity.",
+    inputSchema: {
+        code: z.string().regex(CODE_RE).describe("Canonical A-share code"),
+        date: z
+            .string()
+            .regex(DATE_RE)
+            .optional()
+            .describe("Trade date YYYY-MM-DD; defaults to today"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["financials.pit"];
+        if (!op)
+            throw new Error("financials.pit op missing from codegen");
+        const callArgs = { code: args.code };
+        if (args.date)
+            callArgs.date = args.date;
+        return callOp(op, callArgs, ctx);
+    },
+    backingOps: ["financials.pit"],
+};
+export const financialsReportsSpec = {
+    name: "financials_reports",
+    description: "Last N report-period snapshots for one A-share (~25 fields per period). Each item carries `announce_date` for visibility timing. Filter by `kind` to scope to Q1 / H1 / Q3 / annual / preliminary.",
+    inputSchema: {
+        code: z.string().regex(CODE_RE).describe("Canonical A-share code"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(12)
+            .describe("Max periods (1-100, default 12)"),
+        kind: z.enum(REPORT_KINDS).optional().describe("Filter by report kind"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["financials.reports"];
+        if (!op)
+            throw new Error("financials.reports op missing from codegen");
+        const callArgs = { code: args.code, limit: args.limit };
+        if (args.kind)
+            callArgs.kind = args.kind;
+        return callOp(op, callArgs, ctx);
+    },
+    backingOps: ["financials.reports"],
+};
+export const financialsSeriesSpec = {
+    name: "financials_series",
+    description: "Time series of a single financial metric for one A-share across reporting periods. `metric` is an indicators-table field name (roe_simple / revenue / ni_parent / debt_asset_ratio / gross_margin / eps_basic, ~150 supported).",
+    inputSchema: {
+        code: z.string().regex(CODE_RE).describe("Canonical A-share code"),
+        metric: z
+            .string()
+            .min(1)
+            .max(64)
+            .describe("Indicator field name (e.g. roe_simple, revenue, ni_parent)"),
+        from: z.string().regex(DATE_RE).optional().describe("Inclusive earliest report_date"),
+        to: z.string().regex(DATE_RE).optional().describe("Inclusive latest report_date"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .default(40)
+            .describe("Max points (1-200, default 40)"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["financials.series"];
+        if (!op)
+            throw new Error("financials.series op missing from codegen");
+        const callArgs = {
+            code: args.code,
+            metric: args.metric,
+            limit: args.limit,
+        };
+        if (args.from)
+            callArgs.from = args.from;
+        if (args.to)
+            callArgs.to = args.to;
+        return callOp(op, callArgs, ctx);
+    },
+    backingOps: ["financials.series"],
+};
+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 buildFinancialsCommand() {
+    const cmd = new Command("financials").description("Fundamentals — valuation snapshot, point-in-time indicators, recent reports, single-metric time series.");
+    const qs = cmd
+        .command("quote-snapshot")
+        .description(financialsQuoteSnapshotSpec.description);
+    qs.addOption(new Option("--code <canonical_code>", "Canonical A-share code (e.g. SSE:600519)")
+        .makeOptionMandatory(true));
+    qs.addOption(new Option("--date <YYYY-MM-DD>", "Trade date; omit for real-time"));
+    qs.action(async (opts) => {
+        if (!OPERATIONS["financials.quote-snapshot"]) {
+            emitVerbError("internal_error", "financials.quote-snapshot missing", undefined, 2);
+        }
+        const args = { code: opts.code };
+        if (opts.date)
+            args.date = opts.date;
+        await executeVerb(async (ctx) => financialsQuoteSnapshotSpec.handler(args, ctx));
+    });
+    const pit = cmd.command("pit").description(financialsPitSpec.description);
+    pit.addOption(new Option("--code <canonical_code>", "Canonical A-share code").makeOptionMandatory(true));
+    pit.addOption(new Option("--date <YYYY-MM-DD>", "Trade date; defaults to today"));
+    pit.action(async (opts) => {
+        if (!OPERATIONS["financials.pit"]) {
+            emitVerbError("internal_error", "financials.pit missing", undefined, 2);
+        }
+        const args = { code: opts.code };
+        if (opts.date)
+            args.date = opts.date;
+        await executeVerb(async (ctx) => financialsPitSpec.handler(args, ctx));
+    });
+    const reports = cmd.command("reports").description(financialsReportsSpec.description);
+    reports.addOption(new Option("--code <canonical_code>", "Canonical A-share code").makeOptionMandatory(true));
+    reports.addOption(new Option("--limit <n>", "Max periods (1-100)").default("12"));
+    reports.addOption(new Option("--kind <kind>", "Filter by report kind").choices([...REPORT_KINDS]));
+    reports.action(async (opts) => {
+        if (!OPERATIONS["financials.reports"]) {
+            emitVerbError("internal_error", "financials.reports missing", undefined, 2);
+        }
+        const args = {
+            code: opts.code,
+            limit: clampInt(opts.limit, 1, 100, 12),
+        };
+        if (opts.kind)
+            args.kind = opts.kind;
+        await executeVerb(async (ctx) => financialsReportsSpec.handler(args, ctx));
+    });
+    const series = cmd.command("series").description(financialsSeriesSpec.description);
+    series.addOption(new Option("--code <canonical_code>", "Canonical A-share code").makeOptionMandatory(true));
+    series.addOption(new Option("--metric <name>", "Indicator field name (e.g. roe_simple)").makeOptionMandatory(true));
+    series.addOption(new Option("--from <YYYY-MM-DD>", "Inclusive earliest report_date"));
+    series.addOption(new Option("--to <YYYY-MM-DD>", "Inclusive latest report_date"));
+    series.addOption(new Option("--limit <n>", "Max points (1-200)").default("40"));
+    series.action(async (opts) => {
+        if (!OPERATIONS["financials.series"]) {
+            emitVerbError("internal_error", "financials.series missing", undefined, 2);
+        }
+        const args = {
+            code: opts.code,
+            metric: opts.metric,
+            limit: clampInt(opts.limit, 1, 200, 40),
+        };
+        if (opts.from)
+            args.from = opts.from;
+        if (opts.to)
+            args.to = opts.to;
+        await executeVerb(async (ctx) => financialsSeriesSpec.handler(args, ctx));
+    });
+    return cmd;
+}

package/dist/verbs/index.js

@@ -8,42 +8,50 @@
 export { barsBatchSpec, buildBarsBatchCommand } from "./bars_batch.js";
 export { chartSpec, buildChartCommand } from "./chart.js";
 export { digestSpec, buildDigestCommand } from "./digest.js";
+export { financialsQuoteSnapshotSpec, financialsPitSpec, financialsReportsSpec, financialsSeriesSpec, buildFinancialsCommand, } from "./financials.js";
 export { hotSpec, buildHotCommand } from "./hot.js";
 export { lookupSpec, buildLookupCommand } from "./lookup.js";
 export { newsSpec, buildNewsCommand } from "./news.js";
 export { quoteSpec, buildQuoteCommand } from "./quote.js";
-export { researchSpec, buildResearchCommand } from "./research.js";
 export { scanSpec, buildScanCommand } from "./scan.js";
+export { searchSpec, buildSearchCommand } from "./search.js";
 export { sentimentSpec, buildSentimentCommand } from "./sentiment.js";
 export { viewsSpec, buildViewsCommand } from "./views.js";
 import { barsBatchSpec } from "./bars_batch.js";
 import { chartSpec } from "./chart.js";
 import { digestSpec } from "./digest.js";
+import { financialsQuoteSnapshotSpec, financialsPitSpec, financialsReportsSpec, financialsSeriesSpec, } from "./financials.js";
 import { hotSpec } from "./hot.js";
 import { lookupSpec } from "./lookup.js";
 import { newsSpec } from "./news.js";
 import { quoteSpec } from "./quote.js";
-import { researchSpec } from "./research.js";
 import { scanSpec } from "./scan.js";
+import { searchSpec } from "./search.js";
 import { sentimentSpec } from "./sentiment.js";
 import { viewsSpec } from "./views.js";
 /**
  * Ordering follows product priority (feedback_views_over_news.md):
  * lookup (universal first step) → digest (one-shot fan-out, agent's opening
- * move once it has a canonical_code) → quote → views/research (PRIMARY
- * research) → news (supplementary) → sentiment → hot → chart → bars_batch →
- * scan.
+ * move once it has a canonical_code) → search (hybrid semantic discovery
+ * for themes / concepts) → quote → views (PRIMARY research) → news
+ * (supplementary) → sentiment → hot → chart → bars_batch → scan →
+ * financials (valuation snapshot is the headline; pit / reports / series
+ * cover deeper fundamentals access).
  */
 export const ALL_VERB_SPECS = [
     lookupSpec,
     digestSpec,
+    searchSpec,
     quoteSpec,
     viewsSpec,
-    researchSpec,
     newsSpec,
     sentimentSpec,
     hotSpec,
     chartSpec,
     barsBatchSpec,
     scanSpec,
+    financialsQuoteSnapshotSpec,
+    financialsPitSpec,
+    financialsReportsSpec,
+    financialsSeriesSpec,
 ];