echopai 2.1.0 → 2.2.0

package/README.md

@@ -125,13 +125,16 @@ Available MCP tools (subset shown to LLM depends on token scopes):
 | `digest` | One-shot research digest: 5 buckets in one call | `digest.get` + fan-out fallback |
 | `quote` | Real-time quote for 1-200 codes | `quote` |
 | `views` | **PRIMARY** research source (analyst views w/ entity attribution) | `views.recent` |
-| `research` | Research-entity performance (hit rate / coverage) | `research.entity-performance-list` |
 | `news` | **SUPPLEMENTARY** news / market briefs | `news.search` / `news.feed` |
 | `sentiment` | Aggregate market sentiment | `sentiment.overview` |
 | `hot` | Today's hot-stock leaderboard | `stocks.hot` |
 | `chart` | Single-security K-line (daily / minute) | `bars.daily` / `bars.minute` |
 | `bars_batch` | Batch K-line (≤100 codes × 1yr daily; ≤20 × 7d minute) | `bars.daily-batch` / `bars.minute-batch` |
 | `scan` | Full-market quote snapshot (~5800 securities) | `quote.scan` |
+| `financials_quote_snapshot` | **Headline** valuation snapshot (PE / PB / PS / 换手率 / 股息率 / 量比 14 fields, TDX + Sina 自算) | `financials.quote-snapshot` |
+| `financials_pit` | Point-in-time financial indicators at a given trade_date (anti-future-fn for backtests) | `financials.pit` |
+| `financials_reports` | Last N report-period snapshots (~25 fields × period, filter by Q1/H1/Q3/annual) | `financials.reports` |
+| `financials_series` | Time series of a single financial metric across report periods | `financials.series` |
 
 The agent should prefer `views` over `news` when forming an investment
 opinion (views carries research-entity attribution; news is breadth-only).
@@ -159,6 +162,15 @@ echopai raw views feed --since-days 7 --all | jq '.title'
 
 # One-shot research digest (server-side composite, 5 buckets, partial-failure tolerant)
 echopai digest --code SSE:600519
+
+# Headline valuation snapshot: 14 fields (PE / PB / PS / 换手率 / 股息率 / 量比 ...)
+echopai financials quote-snapshot --code SSE:600519
+echopai financials quote-snapshot --code SSE:600519 --date 2026-05-13  # historical
+
+# Deeper fundamentals
+echopai financials pit     --code SSE:600519 --date 2024-11-01
+echopai financials reports --code SSE:600519 --kind annual --limit 5
+echopai financials series  --code SSE:600519 --metric roe_simple
 ```
 
 ## Output formats

package/dist/_generated/commands.js

@@ -83,22 +83,6 @@ export function buildCommandTree(program, dispatch) {
             attachOperation(cmd, OPERATIONS["auth.whoami"], dispatch);
         }
     }
-    {
-        const noun = program.command("backtest");
-        noun.description("backtest commands");
-        {
-            const cmd = noun.command("excess-distribution");
-            attachOperation(cmd, OPERATIONS["backtest.excess-distribution"], dispatch);
-        }
-        {
-            const cmd = noun.command("rolling-win-rate");
-            attachOperation(cmd, OPERATIONS["backtest.rolling-win-rate"], dispatch);
-        }
-        {
-            const cmd = noun.command("summary");
-            attachOperation(cmd, OPERATIONS["backtest.summary"], dispatch);
-        }
-    }
     {
         const noun = program.command("bars");
         noun.description("bars commands");
@@ -134,6 +118,10 @@ export function buildCommandTree(program, dispatch) {
             const cmd = noun.command("pit");
             attachOperation(cmd, OPERATIONS["financials.pit"], dispatch);
         }
+        {
+            const cmd = noun.command("quote-snapshot");
+            attachOperation(cmd, OPERATIONS["financials.quote-snapshot"], dispatch);
+        }
         {
             const cmd = noun.command("reports");
             attachOperation(cmd, OPERATIONS["financials.reports"], dispatch);
@@ -186,10 +174,6 @@ export function buildCommandTree(program, dispatch) {
             const cmd = noun.command("search");
             attachOperation(cmd, OPERATIONS["news.search"], dispatch);
         }
-        {
-            const cmd = noun.command("sources");
-            attachOperation(cmd, OPERATIONS["news.sources"], dispatch);
-        }
     }
     {
         const noun = program.command("payment");
@@ -211,18 +195,6 @@ export function buildCommandTree(program, dispatch) {
             attachOperation(cmd, OPERATIONS["quote.scan"], dispatch);
         }
     }
-    {
-        const noun = program.command("research");
-        noun.description("research commands");
-        {
-            const cmd = noun.command("entity-performance");
-            attachOperation(cmd, OPERATIONS["research.entity-performance"], dispatch);
-        }
-        {
-            const cmd = noun.command("entity-performance-list");
-            attachOperation(cmd, OPERATIONS["research.entity-performance-list"], dispatch);
-        }
-    }
     {
         const noun = program.command("search");
         noun.description("search commands");
@@ -267,18 +239,6 @@ export function buildCommandTree(program, dispatch) {
             attachOperation(cmd, OPERATIONS["sentiment.turnover"], dispatch);
         }
     }
-    {
-        const noun = program.command("signals");
-        noun.description("signals commands");
-        {
-            const cmd = noun.command("outcome");
-            attachOperation(cmd, OPERATIONS["signals.outcome"], dispatch);
-        }
-        {
-            const cmd = noun.command("outcomes");
-            attachOperation(cmd, OPERATIONS["signals.outcomes"], dispatch);
-        }
-    }
     {
         const noun = program.command("squawk");
         noun.description("squawk commands");

package/dist/_generated/help.js

@@ -22,21 +22,6 @@ export const HELP = {
         "description": "Returns the calling token's kind, scopes, audience, app metadata,\nrate_limit, allowed_clients, agent_budget (if kind=agent), api_version,\nfeature_flags. Any valid JWT can call — no specific scope required.\n\nCLI/MCP call this once at startup, cache 5 minutes in-process, and use\nthe response to derive `verbs.available` (intersection of curated verb\nscopes with token scopes) and to populate `echopai doctor` checks.\n\nSee `docs/PLAN_CLI_V2_AGENT_SURFACE.md` §5.1.\n",
         "example": "echopai auth whoami"
     },
-    "backtest.excess-distribution": {
-        "summary": "Excess-return distribution over a benchmark",
-        "description": "信号相对基准（沪深 300 / 中证 1000 等）持有期超额收益的直方分布。",
-        "example": "echopai backtest excess-distribution"
-    },
-    "backtest.rolling-win-rate": {
-        "summary": "Rolling win rate of a signal series",
-        "description": "信号在滚动窗口（默认 60 个交易日）内的胜率时间序列。",
-        "example": "echopai backtest rolling-win-rate"
-    },
-    "backtest.summary": {
-        "summary": "Backtest summary metrics for a signal series",
-        "description": "信号回测汇总：胜率、平均超额收益、Sharpe-like 评分、最大回撤等。",
-        "example": "echopai backtest summary"
-    },
     "bars.daily": {
         "summary": "Daily OHLC bars for one A-share security",
         "description": "Daily OHLC bars for one A-share security over a date range. Returns open / high / low / close / volume / turnover per trading day. Requires `bars:30d` (last 30 trading days) or `bars:full` (full history) scope.",
@@ -59,7 +44,7 @@ export const HELP = {
     },
     "digest.get": {
         "summary": "One-shot research digest for a single security (composite)",
-        "description": "Composite endpoint: in one HTTP call returns views (PRIMARY research),\nresearch-entity performance (quality layer), real-time quote, market\nsentiment context, and supplementary news. Partial-failure tolerant:\neach bucket is independently fetched and per-bucket failures surface\nin `meta.partial_failures[]` rather than poisoning the response. If\nevery sub-bucket fails the endpoint returns 502.\n\nBucket scopes are checked *per bucket* (not at gateway level): a\ntoken with only `views:read` gets the views bucket populated and the\nrest reported as `scope_insufficient` partial failures. This mirrors\nthe CLI fan-out contract exactly so `echopai digest` can either call\nthis endpoint (preferred, single round-trip) or fall back to local\nfan-out without behavior drift.\n\nSee `docs/PLAN_CLI_V2_AGENT_SURFACE.md` §3.3 (digest spec) and §11\nPhase 5.2 (server endpoint).\n",
+        "description": "Composite endpoint: in one HTTP call returns views (PRIMARY research),\nreal-time quote, valuation snapshot (PE/PB/PS/换手率/股息率/量比 等 14 字段),\nmarket sentiment context, and supplementary news.\nPartial-failure tolerant:\neach bucket is independently fetched and per-bucket failures surface\nin `meta.partial_failures[]` rather than poisoning the response. If\nevery sub-bucket fails the endpoint returns 502.\n\nBucket scopes are checked *per bucket* (not at gateway level): a\ntoken with only `views:read` gets the views bucket populated and the\nrest reported as `scope_insufficient` partial failures. This mirrors\nthe CLI fan-out contract exactly so `echopai digest` can either call\nthis endpoint (preferred, single round-trip) or fall back to local\nfan-out without behavior drift.\n\nSee `docs/PLAN_CLI_V2_AGENT_SURFACE.md` §3.3 (digest spec) and §11\nPhase 5.2 (server endpoint).\n",
         "example": "echopai digest get VALUE"
     },
     "financials.pit": {
@@ -67,6 +52,11 @@ export const HELP = {
         "description": "基于 TDX 财务数据的 Point-in-time 查询。给定 `code` 和 `date`，返回该\n`trade_date` 当时市场上可见的最新一期财务报告（`announce_date <= date`，\n无公告日时保守延迟 90 天）。专为回测、AI agent、量化策略防未来函数泄漏。\n\n返回字段包括：EPS（基本/扣非/稀释）、BPS、ROE、毛利率、营收/净利润/总资产/\n归母权益等核心 ~25 字段。\n",
         "example": "echopai financials pit --code SSE:600519 --date 2024-11-01"
     },
+    "financials.quote-snapshot": {
+        "summary": "Real-time valuation / share / turnover snapshot for one A-share",
+        "description": "一站式估值快照 —— 一次返回 14 个字段，**全部基于 TDX 原始数据 + Sina 实时\n价自算，不依赖 Tushare**：\n\n- 估值: `pe` / `pe_ttm` / `pb` / `ps` / `ps_ttm`\n- 股本（万股）: `total_share` / `float_share` / `free_share`\n- 市值（万元）: `total_mv` / `circ_mv`\n- 流动性: `turnover_rate` / `turnover_rate_f`（%）/ `volume_ratio`（倍）\n- 分红: `dv_ratio` / `dv_ttm`（%）\n\n计算口径：\n- PE-TTM = 当前总市值 / 近 4 季度滚动净利润（PIT 表 `ni_parent_ttm`）\n- PE     = 当前总市值 / 上年报净利润（`ni_parent_last1y`）\n- PB     = 当前总市值 / 归母净资产（`equity_parent`，PIT 防穿越）\n- 换手率 = 当日累计成交量 / 流通股本 × 100\n- 量比   = 当日累计 / 近 5 日同时段累计平均（实时模式）\n          / 近 5 日全日成交量平均（指定历史日期模式）\n- 股息率 = Σ(去年 / 近12月内派息事件 派现/10) / 现价 × 100\n\n默认 `date` 留空 → 实时（Sina 5s 快照价 + 当日累计成交量）；\n给 `date=YYYY-MM-DD` 则按当日 close 取值（用于历史回测 / 校验）。\n\n财报数据走 `security_financial_indicators_pit` PIT 视图：保证 `visible_date`\n≤ trade_date，避免未来函数。\n\n准确性已对照 Tushare `daily_basic` 校验（见 `scripts/validation/validate_quote_snapshot_vs_tushare.py`）。\n",
+        "example": "echopai financials quote-snapshot --code SSE:600519 --date 2026-05-13"
+    },
     "financials.reports": {
         "summary": "Recent financial reports for one A-share security",
         "description": "返回该股票最近 N 期财务报告的核心指标（EPS/BPS/ROE/毛利率/营收/净利润/总\n资产/归母权益/经营现金流/总股本 等 ~25 字段）。可按 `kind` 过滤季报/半年报/\n年报。每期 `announce_date` 字段告知何时市场可见，建议结合回测时使用。\n",
@@ -79,18 +69,18 @@ export const HELP = {
     },
     "index.daily-bars": {
         "summary": "Daily OHLC bars for one A-share index",
-        "description": "指数日线 OHLC。覆盖 v2 表中的指数（上证综指 000001.SH / 深证成指\n399001.SZ / 沪深300 000300.SH / 北证50 899050.BJ / 中证系列 000922.CSI 等）。\n与 `/v1/bars/daily` 同语义，但 index 没有 `turnover_rate` / `paused` 等股票特有字段。\n",
-        "example": "echopai index daily-bars --code 000001.SH --from 2024-01-01 --to 2024-12-31"
+        "description": "指数日线 OHLC。覆盖 v2 表中的指数（上证综指 `SSE:000001` / 深证成指\n`SZSE:399001` / 沪深300 `SSE:000300` / 北证50 `BSE:899050` / 中证系列 `CSI:000922` 等）。\n与 `/v1/bars/daily` 同语义，但 index 没有 `turnover_rate` / `paused` 等股票特有字段。\n",
+        "example": "echopai index daily-bars --code SSE:000001 --from 2024-01-01 --to 2024-12-31"
     },
     "index.minute-bars": {
         "summary": "Minute OHLC bars for one A-share index",
         "description": "指数 1min OHLC。日期范围 ≤ 7 天（与 `/v1/bars/minute-batch` 对齐）。\n返回 `bar_time` / `trade_date` / OHLC / volume / amount / pct_change。\n",
-        "example": "echopai index minute-bars --code 000001.SH"
+        "example": "echopai index minute-bars --code SSE:000001"
     },
     "index.snapshot": {
         "summary": "Real-time snapshot of all Sina-OK A-share indices (172 indices)",
-        "description": "Returns the latest real-time snapshot for the 172 indices that Sina\nexposes a quote for (SSE / SZSE / BSE — includes 北证50 `899050.BJ`\nand 专精特新 `899601.BJ`). Source is the Redis hash\n`stockpulse:index_snapshots:latest` which the Rust collector refreshes\nevery ~15 seconds during market hours; outside trading hours the last\nintraday snapshot is returned.\n\nUse `codes` to narrow to a subset (canonical format like `000001.SH`).\nOmit to receive all 172.\n\nNote: CSI-series indices (e.g. `000922.CSI`) are not available here —\nSina has no quote feed for them. Daily/minute history for those still\nlives behind `/api/internal/index/{daily-bars,minute-bars-range}`.\n\nRequires `quote:l1`, `quote:l2`, or `quote:delayed` scope.\n",
-        "example": "echopai index snapshot --codes 000001.SH,399001.SZ,899050.BJ"
+        "description": "Returns the latest real-time snapshot for the 172 indices that Sina\nexposes a quote for (SSE / SZSE / BSE — includes 北证50 `BSE:899050`\nand 专精特新 `899601.BJ`). Source is the Redis hash\n`stockpulse:index_snapshots:latest` which the Rust collector refreshes\nevery ~15 seconds during market hours; outside trading hours the last\nintraday snapshot is returned.\n\nUse `codes` to narrow to a subset (canonical format `SSE:000001` (exchange-prefix; legacy `000001.SH` is also accepted but discouraged)).\nOmit to receive all 172.\n\nNote: CSI-series indices (e.g. `CSI:000922`) are not available here —\nSina has no quote feed for them. Daily/minute history for those still\nlives behind `/api/internal/index/{daily-bars,minute-bars-range}`.\n\nRequires `quote:l1`, `quote:l2`, or `quote:delayed` scope.\n",
+        "example": "echopai index snapshot --codes SSE:000001,SZSE:399001,BSE:899050"
     },
     "market.status": {
         "summary": "Current A-share market session state",
@@ -117,11 +107,6 @@ export const HELP = {
         "description": "Full-text search recent news / market briefs. Returns title, published_at, snippet, tagged securities. (Internal collector identifiers — `source`/`source_id`/`source_url` — are NOT exposed publicly; admin tools see them via /v1/admin/*.) Requires `news:read` scope. Note: news fields are user-generated; meta.untrusted_text_fields lists fields that need sanitization before passing to an LLM.",
         "example": "echopai news search --query 光伏龙头"
     },
-    "news.sources": {
-        "summary": "List canonical news source identifiers",
-        "description": "返回新闻 source 标识列表（如 `cls`、`jin10`、`twitter`、`wallstreetcn`），可用于 list/search 的 source 过滤。",
-        "example": "echopai news sources"
-    },
     "payment.plans": {
         "summary": "List subscription plans",
         "description": "返回订阅计划清单（plan_id + 价格 + 时长 + 描述）。",
@@ -137,16 +122,6 @@ export const HELP = {
         "description": "Dumps the entire Redis snapshot of A-share real-time quotes in a single\nround-trip. Use for \"全市场扫描\" / agent universe-of-interest discovery\nwhen you don't yet know which codes to query.\n\nFiltering:\n- `exchange=SSE|SZSE|BSE` narrows to one exchange (canonical_code prefix)\n- `app.allowed_securities` is ALWAYS applied; codes outside drop silently\n\nResponse size: ~3 MB unfiltered (~5800 items). CLI users should pair\nwith `--max-bytes` / `--fields` / `--query` from Phase 1.4.\n\n9:00–9:14 集合竞价时段返回空 items + `note` 字段说明。\n\nRequires `quote:l1`, `quote:l2`, or `quote:delayed` scope.\n",
         "example": "echopai quote scan"
     },
-    "research.entity-performance": {
-        "summary": "Performance of one research entity",
-        "description": "单个研究实体的细化绩效指标，对照 `/v1/research-entities/performance`。",
-        "example": "echopai research entity-performance VALUE"
-    },
-    "research.entity-performance-list": {
-        "summary": "Aggregate performance of research entities",
-        "description": "全体研究实体（analyst / team / institution）的命中率、平均目标价达成率、覆盖股票数等汇总。需要 `research:read` scope。",
-        "example": "echopai research entity-performance-list"
-    },
     "search.semantic": {
         "summary": "Hybrid semantic search across news + analyst views",
         "description": "语义 + 模糊泛化搜索。结合 entity 精确匹配（公司代码/分析师）、向量召回（pgvector\n+ DashScope embedding）、trigram 模糊、ILIKE 精确四路召回，RRF 融合后用 reranker\n精排，叠时间衰减 + views 加权（views 主源优先）。\n\n- 搜\"锂电池\"会带出新能源产业链（正极/负极/碳酸锂/宁德时代…）\n- 搜\"芯片\"会带出存储芯片/洁净室/晶圆代工…\n- mode=exact 兼容老 ILIKE 行为，仅在精确关键词命中时返回。\n",
@@ -182,16 +157,6 @@ export const HELP = {
         "description": "Intraday turnover time series. Requires `sentiment:read` scope.",
         "example": "echopai sentiment turnover"
     },
-    "signals.outcome": {
-        "summary": "Outcome trace for a single signal",
-        "description": "单条 signal 的细化结果追踪。",
-        "example": "echopai signals outcome VALUE"
-    },
-    "signals.outcomes": {
-        "summary": "Outcomes of analyst-view-derived signals",
-        "description": "返回分析师 views 派生信号的实际结果（目标价命中 / 止损 / 到期），含命中时长、最大回撤等。",
-        "example": "echopai signals outcomes"
-    },
     "squawk.audio": {
         "summary": "Stream squawk TTS audio",
         "description": "返回 squawk 项的 TTS 音频（MP3）。直接 stream，可作为 `<audio>` src 用。",

package/dist/_generated/operations.js

@@ -165,72 +165,6 @@ export const OPERATIONS = {
             "additionalProperties": false
         }
     },
-    "backtest.excess-distribution": {
-        "cliKey": "backtest.excess-distribution",
-        "cliName": "backtest excess-distribution",
-        "method": "GET",
-        "path": "/v1/backtest/excess-distribution",
-        "description": "信号相对基准（沪深 300 / 中证 1000 等）持有期超额收益的直方分布。",
-        "summary": "Excess-return distribution over a benchmark",
-        "positional": [],
-        "outputDefault": "json",
-        "pagination": "none",
-        "stream": false,
-        "billable": false,
-        "idempotencyRequired": false,
-        "scopesAny": [],
-        "sideEffect": "read",
-        "dryRunSupported": false,
-        "inputSchema": {
-            "type": "object",
-            "properties": {},
-            "additionalProperties": false
-        }
-    },
-    "backtest.rolling-win-rate": {
-        "cliKey": "backtest.rolling-win-rate",
-        "cliName": "backtest rolling-win-rate",
-        "method": "GET",
-        "path": "/v1/backtest/rolling-win-rate",
-        "description": "信号在滚动窗口（默认 60 个交易日）内的胜率时间序列。",
-        "summary": "Rolling win rate of a signal series",
-        "positional": [],
-        "outputDefault": "json",
-        "pagination": "none",
-        "stream": false,
-        "billable": false,
-        "idempotencyRequired": false,
-        "scopesAny": [],
-        "sideEffect": "read",
-        "dryRunSupported": false,
-        "inputSchema": {
-            "type": "object",
-            "properties": {},
-            "additionalProperties": false
-        }
-    },
-    "backtest.summary": {
-        "cliKey": "backtest.summary",
-        "cliName": "backtest summary",
-        "method": "GET",
-        "path": "/v1/backtest/summary",
-        "description": "信号回测汇总：胜率、平均超额收益、Sharpe-like 评分、最大回撤等。",
-        "summary": "Backtest summary metrics for a signal series",
-        "positional": [],
-        "outputDefault": "json",
-        "pagination": "none",
-        "stream": false,
-        "billable": false,
-        "idempotencyRequired": false,
-        "scopesAny": [],
-        "sideEffect": "read",
-        "dryRunSupported": false,
-        "inputSchema": {
-            "type": "object",
-            "properties": {},
-            "additionalProperties": false
-        }
-    },
     "bars.daily": {
         "cliKey": "bars.daily",
         "cliName": "bars daily",
@@ -437,7 +371,7 @@ export const OPERATIONS = {
         "cliName": "digest get",
         "method": "GET",
         "path": "/v1/digest/{code}",
-        "description": "Composite endpoint: in one HTTP call returns views (PRIMARY research),\nresearch-entity performance (quality layer), real-time quote, market\nsentiment context, and supplementary news. Partial-failure tolerant:\neach bucket is independently fetched and per-bucket failures surface\nin `meta.partial_failures[]` rather than poisoning the response. If\nevery sub-bucket fails the endpoint returns 502.\n\nBucket scopes are checked *per bucket* (not at gateway level): a\ntoken with only `views:read` gets the views bucket populated and the\nrest reported as `scope_insufficient` partial failures. This mirrors\nthe CLI fan-out contract exactly so `echopai digest` can either call\nthis endpoint (preferred, single round-trip) or fall back to local\nfan-out without behavior drift.\n\nSee `docs/PLAN_CLI_V2_AGENT_SURFACE.md` §3.3 (digest spec) and §11\nPhase 5.2 (server endpoint).\n",
+        "description": "Composite endpoint: in one HTTP call returns views (PRIMARY research),\nreal-time quote, valuation snapshot (PE/PB/PS/换手率/股息率/量比 等 14 字段),\nmarket sentiment context, and supplementary news.\nPartial-failure tolerant:\neach bucket is independently fetched and per-bucket failures surface\nin `meta.partial_failures[]` rather than poisoning the response. If\nevery sub-bucket fails the endpoint returns 502.\n\nBucket scopes are checked *per bucket* (not at gateway level): a\ntoken with only `views:read` gets the views bucket populated and the\nrest reported as `scope_insufficient` partial failures. This mirrors\nthe CLI fan-out contract exactly so `echopai digest` can either call\nthis endpoint (preferred, single round-trip) or fall back to local\nfan-out without behavior drift.\n\nSee `docs/PLAN_CLI_V2_AGENT_SURFACE.md` §3.3 (digest spec) and §11\nPhase 5.2 (server endpoint).\n",
         "summary": "One-shot research digest for a single security (composite)",
         "positional": [
             "code"
@@ -526,6 +460,46 @@ export const OPERATIONS = {
             ]
         }
     },
+    "financials.quote-snapshot": {
+        "cliKey": "financials.quote-snapshot",
+        "cliName": "financials quote-snapshot",
+        "method": "GET",
+        "path": "/v1/financials/quote-snapshot",
+        "description": "一站式估值快照 —— 一次返回 14 个字段，**全部基于 TDX 原始数据 + Sina 实时\n价自算，不依赖 Tushare**：\n\n- 估值: `pe` / `pe_ttm` / `pb` / `ps` / `ps_ttm`\n- 股本（万股）: `total_share` / `float_share` / `free_share`\n- 市值（万元）: `total_mv` / `circ_mv`\n- 流动性: `turnover_rate` / `turnover_rate_f`（%）/ `volume_ratio`（倍）\n- 分红: `dv_ratio` / `dv_ttm`（%）\n\n计算口径：\n- PE-TTM = 当前总市值 / 近 4 季度滚动净利润（PIT 表 `ni_parent_ttm`）\n- PE     = 当前总市值 / 上年报净利润（`ni_parent_last1y`）\n- PB     = 当前总市值 / 归母净资产（`equity_parent`，PIT 防穿越）\n- 换手率 = 当日累计成交量 / 流通股本 × 100\n- 量比   = 当日累计 / 近 5 日同时段累计平均（实时模式）\n          / 近 5 日全日成交量平均（指定历史日期模式）\n- 股息率 = Σ(去年 / 近12月内派息事件 派现/10) / 现价 × 100\n\n默认 `date` 留空 → 实时（Sina 5s 快照价 + 当日累计成交量）；\n给 `date=YYYY-MM-DD` 则按当日 close 取值（用于历史回测 / 校验）。\n\n财报数据走 `security_financial_indicators_pit` PIT 视图：保证 `visible_date`\n≤ trade_date，避免未来函数。\n\n准确性已对照 Tushare `daily_basic` 校验（见 `scripts/validation/validate_quote_snapshot_vs_tushare.py`）。\n",
+        "summary": "Real-time valuation / share / turnover snapshot for one A-share",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "financials:read"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "pattern": "^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$",
+                    "description": "Canonical A-share code.",
+                    "example": "SSE:600519"
+                },
+                "date": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "Trade date YYYY-MM-DD; omit for real-time (Redis snapshot price).\n",
+                    "example": "2026-05-13"
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "code"
+            ]
+        }
+    },
     "financials.reports": {
         "cliKey": "financials.reports",
         "cliName": "financials reports",
@@ -642,7 +616,7 @@ export const OPERATIONS = {
         "cliName": "index daily-bars",
         "method": "GET",
         "path": "/v1/index/bars/daily",
-        "description": "指数日线 OHLC。覆盖 v2 表中的指数（上证综指 000001.SH / 深证成指\n399001.SZ / 沪深300 000300.SH / 北证50 899050.BJ / 中证系列 000922.CSI 等）。\n与 `/v1/bars/daily` 同语义，但 index 没有 `turnover_rate` / `paused` 等股票特有字段。\n",
+        "description": "指数日线 OHLC。覆盖 v2 表中的指数（上证综指 `SSE:000001` / 深证成指\n`SZSE:399001` / 沪深300 `SSE:000300` / 北证50 `BSE:899050` / 中证系列 `CSI:000922` 等）。\n与 `/v1/bars/daily` 同语义，但 index 没有 `turnover_rate` / `paused` 等股票特有字段。\n",
         "summary": "Daily OHLC bars for one A-share index",
         "positional": [],
         "outputDefault": "json",
@@ -663,7 +637,7 @@ export const OPERATIONS = {
                 "code": {
                     "type": "string",
                     "description": "Canonical index code.",
-                    "example": "000001.SH"
+                    "example": "SSE:000001"
                 },
                 "from": {
                     "type": "string",
@@ -712,7 +686,7 @@ export const OPERATIONS = {
                 "code": {
                     "type": "string",
                     "description": "Canonical index code.",
-                    "example": "000001.SH"
+                    "example": "SSE:000001"
                 },
                 "from": {
                     "type": "string",
@@ -738,7 +712,7 @@ export const OPERATIONS = {
         "cliName": "index snapshot",
         "method": "GET",
         "path": "/v1/index/snapshot",
-        "description": "Returns the latest real-time snapshot for the 172 indices that Sina\nexposes a quote for (SSE / SZSE / BSE — includes 北证50 `899050.BJ`\nand 专精特新 `899601.BJ`). Source is the Redis hash\n`stockpulse:index_snapshots:latest` which the Rust collector refreshes\nevery ~15 seconds during market hours; outside trading hours the last\nintraday snapshot is returned.\n\nUse `codes` to narrow to a subset (canonical format like `000001.SH`).\nOmit to receive all 172.\n\nNote: CSI-series indices (e.g. `000922.CSI`) are not available here —\nSina has no quote feed for them. Daily/minute history for those still\nlives behind `/api/internal/index/{daily-bars,minute-bars-range}`.\n\nRequires `quote:l1`, `quote:l2`, or `quote:delayed` scope.\n",
+        "description": "Returns the latest real-time snapshot for the 172 indices that Sina\nexposes a quote for (SSE / SZSE / BSE — includes 北证50 `BSE:899050`\nand 专精特新 `899601.BJ`). Source is the Redis hash\n`stockpulse:index_snapshots:latest` which the Rust collector refreshes\nevery ~15 seconds during market hours; outside trading hours the last\nintraday snapshot is returned.\n\nUse `codes` to narrow to a subset (canonical format `SSE:000001` (exchange-prefix; legacy `000001.SH` is also accepted but discouraged)).\nOmit to receive all 172.\n\nNote: CSI-series indices (e.g. `CSI:000922`) are not available here —\nSina has no quote feed for them. Daily/minute history for those still\nlives behind `/api/internal/index/{daily-bars,minute-bars-range}`.\n\nRequires `quote:l1`, `quote:l2`, or `quote:delayed` scope.\n",
         "summary": "Real-time snapshot of all Sina-OK A-share indices (172 indices)",
         "positional": [],
         "outputDefault": "json",
@@ -758,8 +732,8 @@ export const OPERATIONS = {
             "properties": {
                 "codes": {
                     "type": "string",
-                    "description": "Comma-separated canonical index codes (e.g. `000001.SH,399001.SZ,899050.BJ`).\nOmit to return all 172.\n",
-                    "example": "000001.SH,399001.SZ,899050.BJ"
+                    "description": "Comma-separated canonical index codes (e.g. `SSE:000001,SZSE:399001,BSE:899050`).\nOmit to return all 172.\n",
+                    "example": "SSE:000001,SZSE:399001,BSE:899050"
                 }
             },
             "additionalProperties": false
@@ -943,28 +917,6 @@ export const OPERATIONS = {
             ]
         }
     },
-    "news.sources": {
-        "cliKey": "news.sources",
-        "cliName": "news sources",
-        "method": "GET",
-        "path": "/v1/news/sources",
-        "description": "返回新闻 source 标识列表（如 `cls`、`jin10`、`twitter`、`wallstreetcn`），可用于 list/search 的 source 过滤。",
-        "summary": "List canonical news source identifiers",
-        "positional": [],
-        "outputDefault": "json",
-        "pagination": "none",
-        "stream": false,
-        "billable": false,
-        "idempotencyRequired": false,
-        "scopesAny": [],
-        "sideEffect": "read",
-        "dryRunSupported": false,
-        "inputSchema": {
-            "type": "object",
-            "properties": {},
-            "additionalProperties": false
-        }
-    },
     "payment.plans": {
         "cliKey": "payment.plans",
         "cliName": "payment plans",
@@ -1075,60 +1027,6 @@ export const OPERATIONS = {
             "additionalProperties": false
         }
     },
-    "research.entity-performance": {
-        "cliKey": "research.entity-performance",
-        "cliName": "research entity-performance",
-        "method": "GET",
-        "path": "/v1/research-entities/{entity_id}/performance",
-        "description": "单个研究实体的细化绩效指标，对照 `/v1/research-entities/performance`。",
-        "summary": "Performance of one research entity",
-        "positional": [
-            "entity_id"
-        ],
-        "outputDefault": "json",
-        "pagination": "none",
-        "stream": false,
-        "billable": false,
-        "idempotencyRequired": false,
-        "scopesAny": [],
-        "sideEffect": "read",
-        "dryRunSupported": false,
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "entity_id": {
-                    "type": "string",
-                    "description": "Research-entity id (returned by research-entities.list / matcher)."
-                }
-            },
-            "additionalProperties": false,
-            "required": [
-                "entity_id"
-            ]
-        }
-    },
-    "research.entity-performance-list": {
-        "cliKey": "research.entity-performance-list",
-        "cliName": "research entity-performance-list",
-        "method": "GET",
-        "path": "/v1/research-entities/performance",
-        "description": "全体研究实体（analyst / team / institution）的命中率、平均目标价达成率、覆盖股票数等汇总。需要 `research:read` scope。",
-        "summary": "Aggregate performance of research entities",
-        "positional": [],
-        "outputDefault": "json",
-        "pagination": "none",
-        "stream": false,
-        "billable": false,
-        "idempotencyRequired": false,
-        "scopesAny": [],
-        "sideEffect": "read",
-        "dryRunSupported": false,
-        "inputSchema": {
-            "type": "object",
-            "properties": {},
-            "additionalProperties": false
-        }
-    },
     "search.semantic": {
         "cliKey": "search.semantic",
         "cliName": "search semantic",
@@ -1408,60 +1306,6 @@ export const OPERATIONS = {
             "additionalProperties": false
         }
     },
-    "signals.outcome": {
-        "cliKey": "signals.outcome",
-        "cliName": "signals outcome",
-        "method": "GET",
-        "path": "/v1/signals/{signal_id}/outcome",
-        "description": "单条 signal 的细化结果追踪。",
-        "summary": "Outcome trace for a single signal",
-        "positional": [
-            "signal_id"
-        ],
-        "outputDefault": "json",
-        "pagination": "none",
-        "stream": false,
-        "billable": false,
-        "idempotencyRequired": false,
-        "scopesAny": [],
-        "sideEffect": "read",
-        "dryRunSupported": false,
-        "inputSchema": {
-            "type": "object",
-            "properties": {
-                "signal_id": {
-                    "type": "string",
-                    "description": "Signal id (returned by signals/outcomes items[].signal_id)."
-                }
-            },
-            "additionalProperties": false,
-            "required": [
-                "signal_id"
-            ]
-        }
-    },
-    "signals.outcomes": {
-        "cliKey": "signals.outcomes",
-        "cliName": "signals outcomes",
-        "method": "GET",
-        "path": "/v1/signals/outcomes",
-        "description": "返回分析师 views 派生信号的实际结果（目标价命中 / 止损 / 到期），含命中时长、最大回撤等。",
-        "summary": "Outcomes of analyst-view-derived signals",
-        "positional": [],
-        "outputDefault": "json",
-        "pagination": "offset",
-        "stream": false,
-        "billable": false,
-        "idempotencyRequired": false,
-        "scopesAny": [],
-        "sideEffect": "read",
-        "dryRunSupported": false,
-        "inputSchema": {
-            "type": "object",
-            "properties": {},
-            "additionalProperties": false
-        }
-    },
     "squawk.audio": {
         "cliKey": "squawk.audio",
         "cliName": "squawk audio",

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, buildSearchCommand, 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,11 +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);
@@ -135,19 +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());
@@ -160,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,11 +8,11 @@
 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";
@@ -20,11 +20,11 @@ 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";
@@ -33,8 +33,10 @@ 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) → search (hybrid semantic discovery
- * for themes / concepts) → quote → views/research (PRIMARY research) → news
- * (supplementary) → sentiment → hot → chart → bars_batch → scan.
+ * 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,
@@ -42,11 +44,14 @@ export const ALL_VERB_SPECS = [
     searchSpec,
     quoteSpec,
     viewsSpec,
-    researchSpec,
     newsSpec,
     sentimentSpec,
     hotSpec,
     chartSpec,
     barsBatchSpec,
     scanSpec,
+    financialsQuoteSnapshotSpec,
+    financialsPitSpec,
+    financialsReportsSpec,
+    financialsSeriesSpec,
 ];

package/dist/verbs/views.js

@@ -10,7 +10,7 @@ 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.",
     inputSchema: {
         code: z
             .string()

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.2.0";

package/package.json

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