echopai 2.0.0 → 2.1.0

package/dist/_generated/commands.js

@@ -127,6 +127,38 @@ export function buildCommandTree(program, dispatch) {
             attachOperation(cmd, OPERATIONS["digest.get"], dispatch);
         }
     }
+    {
+        const noun = program.command("financials");
+        noun.description("financials commands");
+        {
+            const cmd = noun.command("pit");
+            attachOperation(cmd, OPERATIONS["financials.pit"], dispatch);
+        }
+        {
+            const cmd = noun.command("reports");
+            attachOperation(cmd, OPERATIONS["financials.reports"], dispatch);
+        }
+        {
+            const cmd = noun.command("series");
+            attachOperation(cmd, OPERATIONS["financials.series"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("index");
+        noun.description("index commands");
+        {
+            const cmd = noun.command("daily-bars");
+            attachOperation(cmd, OPERATIONS["index.daily-bars"], dispatch);
+        }
+        {
+            const cmd = noun.command("minute-bars");
+            attachOperation(cmd, OPERATIONS["index.minute-bars"], dispatch);
+        }
+        {
+            const cmd = noun.command("snapshot");
+            attachOperation(cmd, OPERATIONS["index.snapshot"], dispatch);
+        }
+    }
     {
         const noun = program.command("market");
         noun.description("market commands");
@@ -191,6 +223,22 @@ export function buildCommandTree(program, dispatch) {
             attachOperation(cmd, OPERATIONS["research.entity-performance-list"], dispatch);
         }
     }
+    {
+        const noun = program.command("search");
+        noun.description("search commands");
+        {
+            const cmd = noun.command("semantic");
+            attachOperation(cmd, OPERATIONS["search.semantic"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("securities");
+        noun.description("securities commands");
+        {
+            const cmd = noun.command("industry");
+            attachOperation(cmd, OPERATIONS["securities.industry"], dispatch);
+        }
+    }
     {
         const noun = program.command("semantic");
         noun.description("semantic commands");

package/dist/_generated/help.js

@@ -62,6 +62,36 @@ export const HELP = {
         "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",
         "example": "echopai digest get VALUE"
     },
+    "financials.pit": {
+        "summary": "Point-in-time financial indicators for one A-share at a given date",
+        "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.reports": {
+        "summary": "Recent financial reports for one A-share security",
+        "description": "返回该股票最近 N 期财务报告的核心指标（EPS/BPS/ROE/毛利率/营收/净利润/总\n资产/归母权益/经营现金流/总股本 等 ~25 字段）。可按 `kind` 过滤季报/半年报/\n年报。每期 `announce_date` 字段告知何时市场可见，建议结合回测时使用。\n",
+        "example": "echopai financials reports --code SSE:600519"
+    },
+    "financials.series": {
+        "summary": "Time series of a single financial metric for one security",
+        "description": "返回某只股票某个财务指标的历史时间序列（按报告期排列）。`metric` 是\nindicators 表中的字段名（如 `roe_simple` / `revenue` / `ni_parent` /\n`debt_asset_ratio` / `gross_margin` / `eps_basic` 等共 150 个）。\n\n典型用法：画茅台 10 年 ROE 走势、对比 5 只白酒股 net_margin。\n",
+        "example": "echopai financials series --code SSE:600519 --metric roe_simple"
+    },
+    "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"
+    },
+    "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"
+    },
+    "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"
+    },
     "market.status": {
         "summary": "Current A-share market session state",
         "description": "Current A-share market session: pre-open / open / lunch / closed; current and next trading day; holiday flag. Requires `market:read` or any `quote:*` scope.",
@@ -74,7 +104,7 @@ export const HELP = {
     },
     "news.get": {
         "summary": "Fetch a single news item by id",
-        "description": "返回新闻完整内容：title、content snippet、source URL、tagged securities。",
+        "description": "返回新闻完整内容：title、content snippet、tagged securities。（采集端字段 source / source_id / source_url 对外不暴露，admin 路径 /v1/admin/news/{id} 可见。）",
         "example": "echopai news get VALUE"
     },
     "news.list": {
@@ -84,7 +114,7 @@ export const HELP = {
     },
     "news.search": {
         "summary": "Full-text search recent news",
-        "description": "Full-text search recent news / market briefs. Returns title, source, published_at, snippet, tagged securities. Requires `news:read` scope. Note: news fields are user-generated; meta.untrusted_text_fields lists fields that need sanitization before passing to an LLM.",
+        "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": {
@@ -117,6 +147,16 @@ export const HELP = {
         "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",
+        "example": "echopai search semantic --q 锂电池"
+    },
+    "securities.industry": {
+        "summary": "TDX + 申万 industry classification for one A-share security",
+        "description": "返回该股票的 TDX 自定义行业代码（T1001 食品饮料等）与申万行业三级代码\nL1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。\n\n用法：\n- 股票详情页\"申万行业：白酒 / 食品饮料\"标签\n- 筛选器交叉过滤：行业 + ROE/营收增长率\n- AI agent `find_peers(code)` 用申万二级行业找同业\n",
+        "example": "echopai securities industry --code SSE:600519"
+    },
     "semantic.find": {
         "summary": "Find A-share securities by name / code / pinyin",
         "description": "Find A-share securities matching a name (Chinese), code (e.g. 600519), or pinyin initials (e.g. gzmt). Use this when an agent has a description and needs canonical codes.",

package/dist/_generated/operations.js

@@ -486,6 +486,285 @@ export const OPERATIONS = {
             ]
         }
     },
+    "financials.pit": {
+        "cliKey": "financials.pit",
+        "cliName": "financials pit",
+        "method": "GET",
+        "path": "/v1/financials/pit",
+        "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",
+        "summary": "Point-in-time financial indicators for one A-share at a given date",
+        "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 in YYYY-MM-DD; defaults to today.",
+                    "example": "2024-11-01"
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "code"
+            ]
+        }
+    },
+    "financials.reports": {
+        "cliKey": "financials.reports",
+        "cliName": "financials reports",
+        "method": "GET",
+        "path": "/v1/financials/reports",
+        "description": "返回该股票最近 N 期财务报告的核心指标（EPS/BPS/ROE/毛利率/营收/净利润/总\n资产/归母权益/经营现金流/总股本 等 ~25 字段）。可按 `kind` 过滤季报/半年报/\n年报。每期 `announce_date` 字段告知何时市场可见，建议结合回测时使用。\n",
+        "summary": "Recent financial reports for one A-share security",
+        "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"
+                },
+                "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 100,
+                    "default": 12,
+                    "description": "Max periods to return (1-100, default 12)."
+                },
+                "kind": {
+                    "type": "string",
+                    "enum": [
+                        "Q1",
+                        "H1",
+                        "Q3",
+                        "annual",
+                        "preliminary"
+                    ],
+                    "description": "Filter by report kind."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "code"
+            ]
+        }
+    },
+    "financials.series": {
+        "cliKey": "financials.series",
+        "cliName": "financials series",
+        "method": "GET",
+        "path": "/v1/financials/series",
+        "description": "返回某只股票某个财务指标的历史时间序列（按报告期排列）。`metric` 是\nindicators 表中的字段名（如 `roe_simple` / `revenue` / `ni_parent` /\n`debt_asset_ratio` / `gross_margin` / `eps_basic` 等共 150 个）。\n\n典型用法：画茅台 10 年 ROE 走势、对比 5 只白酒股 net_margin。\n",
+        "summary": "Time series of a single financial metric for one security",
+        "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"
+                },
+                "metric": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 64,
+                    "description": "Indicator field name (e.g. roe_simple, revenue, ni_parent).",
+                    "example": "roe_simple"
+                },
+                "from": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "Inclusive earliest report_date."
+                },
+                "to": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "Inclusive latest report_date."
+                },
+                "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 200,
+                    "default": 40,
+                    "description": "Max points (1-200, default 40)."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "code",
+                "metric"
+            ]
+        }
+    },
+    "index.daily-bars": {
+        "cliKey": "index.daily-bars",
+        "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",
+        "summary": "Daily OHLC bars for one A-share index",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "quote:l1",
+            "quote:l2",
+            "quote:delayed"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "description": "Canonical index code.",
+                    "example": "000001.SH"
+                },
+                "from": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "Inclusive start date (YYYY-MM-DD).",
+                    "example": "2024-01-01"
+                },
+                "to": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "Inclusive end date.",
+                    "example": "2024-12-31"
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "code",
+                "from",
+                "to"
+            ]
+        }
+    },
+    "index.minute-bars": {
+        "cliKey": "index.minute-bars",
+        "cliName": "index minute-bars",
+        "method": "GET",
+        "path": "/v1/index/bars/minute",
+        "description": "指数 1min OHLC。日期范围 ≤ 7 天（与 `/v1/bars/minute-batch` 对齐）。\n返回 `bar_time` / `trade_date` / OHLC / volume / amount / pct_change。\n",
+        "summary": "Minute OHLC bars for one A-share index",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "quote:l1",
+            "quote:l2",
+            "quote:delayed"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "description": "Canonical index code.",
+                    "example": "000001.SH"
+                },
+                "from": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "Inclusive start date (YYYY-MM-DD)."
+                },
+                "to": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "Inclusive end date. Range ≤ 7 calendar days."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "code",
+                "from",
+                "to"
+            ]
+        }
+    },
+    "index.snapshot": {
+        "cliKey": "index.snapshot",
+        "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",
+        "summary": "Real-time snapshot of all Sina-OK A-share indices (172 indices)",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "quote:l1",
+            "quote:l2",
+            "quote:delayed"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "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"
+                }
+            },
+            "additionalProperties": false
+        }
+    },
     "market.status": {
         "cliKey": "market.status",
         "cliName": "market status",
@@ -540,7 +819,7 @@ export const OPERATIONS = {
         "cliName": "news get",
         "method": "GET",
         "path": "/v1/news/{news_id}",
-        "description": "返回新闻完整内容：title、content snippet、source URL、tagged securities。",
+        "description": "返回新闻完整内容：title、content snippet、tagged securities。（采集端字段 source / source_id / source_url 对外不暴露，admin 路径 /v1/admin/news/{id} 可见。）",
         "summary": "Fetch a single news item by id",
         "positional": [
             "news_id"
@@ -620,7 +899,7 @@ export const OPERATIONS = {
         "cliName": "news search",
         "method": "GET",
         "path": "/v1/news/search",
-        "description": "Full-text search recent news / market briefs. Returns title, source, published_at, snippet, tagged securities. Requires `news:read` scope. Note: news fields are user-generated; meta.untrusted_text_fields lists fields that need sanitization before passing to an LLM.",
+        "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.",
         "summary": "Full-text search recent news",
         "positional": [],
         "outputDefault": "json",
@@ -850,6 +1129,106 @@ export const OPERATIONS = {
             "additionalProperties": false
         }
     },
+    "search.semantic": {
+        "cliKey": "search.semantic",
+        "cliName": "search semantic",
+        "method": "GET",
+        "path": "/v1/search",
+        "description": "语义 + 模糊泛化搜索。结合 entity 精确匹配（公司代码/分析师）、向量召回（pgvector\n+ DashScope embedding）、trigram 模糊、ILIKE 精确四路召回，RRF 融合后用 reranker\n精排，叠时间衰减 + views 加权（views 主源优先）。\n\n- 搜\"锂电池\"会带出新能源产业链（正极/负极/碳酸锂/宁德时代…）\n- 搜\"芯片\"会带出存储芯片/洁净室/晶圆代工…\n- mode=exact 兼容老 ILIKE 行为，仅在精确关键词命中时返回。\n",
+        "summary": "Hybrid semantic search across news + analyst views",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "news:read",
+            "views:read"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "q": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 200,
+                    "description": "Free-text query (Chinese or English).",
+                    "example": "锂电池"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "news",
+                        "views",
+                        "all"
+                    ],
+                    "default": "all",
+                    "description": "Search scope: news | views | all"
+                },
+                "mode": {
+                    "type": "string",
+                    "enum": [
+                        "hybrid",
+                        "exact"
+                    ],
+                    "default": "hybrid",
+                    "description": "hybrid = 语义 + 精确融合 + rerank；exact = 仅 ILIKE 兼容老逻辑"
+                },
+                "hours": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 720,
+                    "description": "Lookback window in hours."
+                },
+                "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 50,
+                    "default": 20,
+                    "description": "Max items returned."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "q"
+            ]
+        }
+    },
+    "securities.industry": {
+        "cliKey": "securities.industry",
+        "cliName": "securities industry",
+        "method": "GET",
+        "path": "/v1/securities/industry",
+        "description": "返回该股票的 TDX 自定义行业代码（T1001 食品饮料等）与申万行业三级代码\nL1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。\n\n用法：\n- 股票详情页\"申万行业：白酒 / 食品饮料\"标签\n- 筛选器交叉过滤：行业 + ROE/营收增长率\n- AI agent `find_peers(code)` 用申万二级行业找同业\n",
+        "summary": "TDX + 申万 industry classification for one A-share security",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": false,
+        "idempotencyRequired": false,
+        "scopesAny": [],
+        "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"
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "code"
+            ]
+        }
+    },
     "semantic.find": {
         "cliKey": "semantic.find",
         "cliName": "semantic find",

package/dist/bin.js

@@ -20,7 +20,7 @@ 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, buildHotCommand, buildLookupCommand, buildNewsCommand, buildQuoteCommand, buildResearchCommand, 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";
@@ -120,6 +120,7 @@ const CURATED_NOUNS = new Set([
     "hot",
     "lookup",
     "digest",
+    "search",
 ]);
 const topLevelSpecDispatch = async (op, args) => {
     await dispatch(op, args);
@@ -137,6 +138,7 @@ for (const sub of topLevelStub.commands) {
 // Product priority (see feedback_views_over_news.md): views > research > 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

package/dist/verbs/index.js

@@ -14,6 +14,7 @@ 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";
@@ -25,18 +26,20 @@ 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/research (PRIMARY research) → news
+ * (supplementary) → sentiment → hot → chart → bars_batch → scan.
  */
 export const ALL_VERB_SPECS = [
     lookupSpec,
     digestSpec,
+    searchSpec,
     quoteSpec,
     viewsSpec,
     researchSpec,

package/dist/verbs/search.js

@@ -0,0 +1,105 @@
+/**
+ * `echopai search ...` + MCP tool `search`.
+ *
+ * HYBRID semantic search across news + analyst views.
+ *
+ * Use this verb when:
+ *   - the user is exploring a THEME / 概念 ("锂电池", "芯片", "AI 算力") — pure
+ *     vector + concept expansion brings out the full supply chain even when
+ *     the query word never appears verbatim in the doc.
+ *   - the user gives a non-canonical company name or analyst name — entity
+ *     lane resolves it through securities / research_entities tables.
+ *
+ * Prefer this over `news` / `views` for open-ended discovery. For strict
+ * time-window listing or filtered feed, keep using `views` / `news`.
+ */
+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 searchSpec = {
+    name: "search",
+    description: "HYBRID semantic search across analyst views + news (views weighted higher per feedback_views_over_news). Combines entity lookup (company codes, analyst names), pgvector kNN, trigram fuzzy and exact ILIKE; RRF-fused then reranked. Best for theme/concept queries: '锂电池' brings out 正极材料/碳酸锂/宁德时代; '芯片' brings out 存储芯片/洁净室/晶圆代工. Use `news` or `views` instead if you need strict time-window listing.",
+    inputSchema: {
+        q: z
+            .string()
+            .min(1)
+            .max(200)
+            .describe("Free-text query (Chinese or English)"),
+        type: z
+            .enum(["news", "views", "all"])
+            .default("all")
+            .describe("Search scope (views weighted higher in 'all')"),
+        mode: z
+            .enum(["hybrid", "exact"])
+            .default("hybrid")
+            .describe("hybrid = semantic + concept expansion + rerank; exact = ILIKE only"),
+        hours: z
+            .number()
+            .int()
+            .min(1)
+            .max(720)
+            .optional()
+            .describe("Lookback window in hours; omit for no time limit"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .default(20)
+            .describe("Max items returned"),
+    },
+    handler: async (args, ctx) => {
+        const op = OPERATIONS["search.semantic"];
+        if (!op)
+            throw new Error("search.semantic op missing from codegen");
+        const callArgs = {
+            q: args.q,
+            type: args.type,
+            mode: args.mode,
+            limit: args.limit,
+        };
+        if (args.hours !== undefined)
+            callArgs.hours = args.hours;
+        return callOp(op, callArgs, ctx);
+    },
+    backingOps: ["search.semantic"],
+};
+function clamp(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 buildSearchCommand() {
+    const cmd = new Command(searchSpec.name).description(searchSpec.description);
+    cmd.argument("<query...>", "Search query (Chinese or English)");
+    cmd.addOption(new Option("--type <scope>", "Search scope")
+        .choices(["news", "views", "all"])
+        .default("all"));
+    cmd.addOption(new Option("--mode <mode>", "hybrid | exact")
+        .choices(["hybrid", "exact"])
+        .default("hybrid"));
+    cmd.addOption(new Option("--exact", "shortcut for --mode exact"));
+    cmd.addOption(new Option("--hours <n>", "Lookback window (1-720 hours)"));
+    cmd.addOption(new Option("--limit <n>", "Max items (1-50)").default("20"));
+    cmd.action(async (queryTokens, opts) => {
+        const q = queryTokens.join(" ").trim();
+        const args = {
+            q,
+            type: opts.type,
+            mode: opts.exact ? "exact" : opts.mode,
+            limit: clamp(opts.limit, 1, 50, 20),
+        };
+        if (opts.hours !== undefined) {
+            args.hours = clamp(opts.hours, 1, 720, 24);
+        }
+        await executeVerb(async (ctx) => searchSpec.handler(args, ctx));
+    });
+    return cmd;
+}

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.0.0";
+export const CLI_VERSION = "2.1.0";

package/package.json

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