echopai 2.7.0 → 2.8.1

package/dist/bin.js

@@ -574,6 +574,28 @@ var OPERATIONS = {
       ]
     }
   },
+  "capabilities.show": {
+    cliKey: "capabilities.show",
+    cliName: "capabilities show",
+    method: "GET",
+    path: "/v1/capabilities",
+    description: "Returns the current API spec version plus a machine-readable changelog of capability changes (new endpoints, new fields, behavior fixes), newest first. Check it at session start — or after an unexpected response shape — to discover capabilities added since your integration was written. Free and unauthenticated.",
+    summary: "Capability changelog and API version discovery.",
+    positional: [],
+    outputDefault: "json",
+    pagination: "none",
+    stream: false,
+    billable: false,
+    idempotencyRequired: false,
+    scopesAny: [],
+    sideEffect: "read",
+    dryRunSupported: false,
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    }
+  },
   "concepts.alerts": {
     cliKey: "concepts.alerts",
     cliName: "concepts alerts",
@@ -1437,7 +1459,7 @@ var OPERATIONS = {
         include_broken: {
           type: "boolean",
           default: false,
-          description: "true 时连炸板（status=broken）也一起返回；默认只返回当前封板 status=limit_up。"
+          description: "true 时连真炸板（盘中封板后跌出、当前未回封，status=broken）也一起返回；默认只返回当前封板 status=limit_up。"
         }
       },
       additionalProperties: false
@@ -1516,7 +1538,7 @@ var OPERATIONS = {
     cliName: "news feed",
     method: "GET",
     path: "/v1/news",
-    description: "Returns recent news. Equivalent to `/v1/news/list`; retained for backward compatibility.",
+    description: "Returns recent news. Equivalent to `/v1/news/list`; retained for backward compatibility. Partner/agent callers receive `fields=compact` by default (id, title, ai_summary, tagged securities, first ~300 chars of content); pass `fields=full` for complete content.",
     summary: "List recent news.",
     positional: [],
     outputDefault: "json",
@@ -1529,7 +1551,16 @@ var OPERATIONS = {
     dryRunSupported: false,
     inputSchema: {
       type: "object",
-      properties: {},
+      properties: {
+        fields: {
+          type: "string",
+          enum: [
+            "compact",
+            "full"
+          ],
+          description: "Response shape: `compact` (the default for partner/agent callers) returns id, title, ai_summary, tagged securities, and the first ~300 chars of content with a `content_truncated` flag; `full` returns complete content."
+        }
+      },
       additionalProperties: false
     }
   },
@@ -1621,6 +1652,14 @@ var OPERATIONS = {
           minimum: 0,
           default: 0,
           description: "Pagination offset (page through long history ranges)."
+        },
+        fields: {
+          type: "string",
+          enum: [
+            "compact",
+            "full"
+          ],
+          description: "Response shape: `compact` (the default for partner/agent callers) returns id, title/ai_summary, attribution, tagged securities, and the first ~300 chars of content with a `content_truncated` flag; `full` returns complete content. Prefer compact for scanning; fetch full text per item only when needed."
         }
       },
       additionalProperties: false,
@@ -1686,6 +1725,14 @@ var OPERATIONS = {
           minimum: 0,
           default: 0,
           description: "Pagination offset (page through long history ranges)."
+        },
+        fields: {
+          type: "string",
+          enum: [
+            "compact",
+            "full"
+          ],
+          description: "Response shape: `compact` (the default for partner/agent callers) returns id, title/ai_summary, attribution, tagged securities, and the first ~300 chars of content with a `content_truncated` flag; `full` returns complete content. Prefer compact for scanning; fetch full text per item only when needed."
         }
       },
       additionalProperties: false,
@@ -1800,7 +1847,7 @@ var OPERATIONS = {
     cliName: "quote",
     method: "GET",
     path: "/v1/quote/realtime",
-    description: "Returns real-time quotes for one or more A-share securities (canonical codes, e.g. `SSE:600519`): last price, volume, percent change, and bid/ask. Up to 200 codes per call. Requires a `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
+    description: "Returns real-time quotes for one or more A-share securities (canonical codes, e.g. `SSE:600519`): last price, volume, percent change, and bid/ask. Up to 200 codes per call. The response carries a `session` label (`pre_open` / `auction` / `open` / `break` / `closed`) and, outside continuous trading, an explanatory `note`: during 9:00–9:14 pre-open the previous session's snapshot is returned; during the 9:15–9:29 call auction, prices are indicative auction match prices. Rows whose feed has stopped updating (suspension / feed drop) keep their last snapshot and are flagged `stale: true` with `stale_since`. Requires a `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
     summary: "Get real-time quotes for one or more securities.",
     positional: [],
     outputDefault: "json",
@@ -1851,7 +1898,7 @@ var OPERATIONS = {
     cliName: "quote scan",
     method: "GET",
     path: "/v1/quote/scan",
-    description: "Returns a real-time quote for every A-share in a single call — use it for full-market scans or to discover a universe of interest when you do not yet know which codes to query. Filter with `exchange=SSE|SZSE|BSE` to narrow to one exchange. The payload is large (~3 MB, ~5,800 instruments), so pair it with `--fields`, `--jq`, or `--max-bytes` to trim it. During the 9:00–9:14 pre-open auction an empty result is returned with an explanatory note. Each item also includes `main_net_in` (current-day cumulative net main-capital inflow in CNY, which may be negative) and a companion `main_net_in_stale` flag (true when served from the last-close fallback). Requires a `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
+    description: "Returns a real-time quote for every A-share in a single call — use it for full-market scans or to discover a universe of interest when you do not yet know which codes to query. Filter with `exchange=SSE|SZSE|BSE` to narrow to one exchange. The payload is large (~3 MB, ~5,800 instruments), so pair it with `--fields`, `--jq`, or `--max-bytes` to trim it. The response carries a `session` label (`pre_open` / `auction` / `open` / `break` / `closed`) plus an explanatory `note` outside continuous trading: during 9:00–9:14 pre-open the previous session's snapshot is returned; during the 9:15–9:29 call auction, prices are indicative auction match prices. Instruments whose feed has stopped updating (suspension / feed drop) are excluded from the default scan; pass `include=all` to keep them, flagged with `stale: true` and `stale_since`. Each item also includes `main_net_in` (current-day cumulative net main-capital inflow in CNY, which may be negative) and a companion `main_net_in_stale` flag (true when served from the last-close fallback). Requires a `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
     summary: "Snapshot every A-share real-time quote in one call.",
     positional: [],
     outputDefault: "json",
@@ -1880,6 +1927,15 @@ var OPERATIONS = {
             "bse"
           ],
           description: "Filter by exchange: SSE / SZSE / BSE (case-insensitive). Omit for all."
+        },
+        include: {
+          type: "string",
+          enum: [
+            "active",
+            "all"
+          ],
+          default: "active",
+          description: "`active` (default) excludes ST, delisted, and stale (feed-dropped / suspended) instruments; `all` returns the full set with stale rows flagged."
         }
       },
       additionalProperties: false
@@ -2259,7 +2315,7 @@ var OPERATIONS = {
     cliName: "views feed",
     method: "GET",
     path: "/v1/views",
-    description: "Returns a stream of analyst views, sell-side research, and long-form opinion. Filter by institution, analyst, security, or recency (`hours`). Requires the `views:read` scope.",
+    description: "Returns a stream of analyst views, sell-side research, and long-form opinion. Filter by institution, analyst, security, or recency (`hours`). Partner/agent callers receive `fields=compact` by default (id, ai_summary, attribution, tagged securities, first ~300 chars of content); pass `fields=full` for complete content. Requires the `views:read` scope.",
     summary: "List analyst views.",
     positional: [],
     outputDefault: "json",
@@ -2272,7 +2328,16 @@ var OPERATIONS = {
     dryRunSupported: false,
     inputSchema: {
       type: "object",
-      properties: {},
+      properties: {
+        fields: {
+          type: "string",
+          enum: [
+            "compact",
+            "full"
+          ],
+          description: "Response shape: `compact` (the default for partner/agent callers) returns id, ai_summary, attribution, tagged securities, and the first ~300 chars of content with a `content_truncated` flag; `full` returns complete content."
+        }
+      },
       additionalProperties: false
     }
   },
@@ -2372,6 +2437,14 @@ var OPERATIONS = {
           minimum: 0,
           default: 0,
           description: "Pagination offset (page through long history ranges)."
+        },
+        fields: {
+          type: "string",
+          enum: [
+            "compact",
+            "full"
+          ],
+          description: "Response shape: `compact` (the default for partner/agent callers) returns id, title/ai_summary, attribution, tagged securities, and the first ~300 chars of content with a `content_truncated` flag; `full` returns complete content. Prefer compact for scanning; fetch full text per item only when needed."
         }
       },
       additionalProperties: false
@@ -2490,6 +2563,14 @@ function buildCommandTree(program, dispatch) {
       attachOperation(cmd, OPERATIONS["bars.minute-batch"], dispatch);
     }
   }
+  {
+    const noun = program.command("capabilities");
+    noun.description("capabilities commands");
+    {
+      const cmd = noun.command("show");
+      attachOperation(cmd, OPERATIONS["capabilities.show"], dispatch);
+    }
+  }
   {
     const noun = program.command("concepts");
     noun.description("Thematic concept boards: constituents, quotes, and alerts.");
@@ -3349,6 +3430,22 @@ function buildHttpHeaders(ctx) {
 function resolveRequestId(serverHeader, clientGenerated) {
   return serverHeader && serverHeader.length > 0 ? serverHeader : clientGenerated;
 }
+var DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+var WHOAMI_TIMEOUT_MS = 8000;
+async function fetchWithTimeout(fn, url, init, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+  const ac = new AbortController;
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    return await fn(url, { ...init, signal: ac.signal });
+  } catch (e) {
+    if (ac.signal.aborted) {
+      throw new Error(`request timed out after ${timeoutMs}ms: ${url}`);
+    }
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+}
 
 // src/runtime/trace.ts
 import {
@@ -3479,7 +3576,10 @@ async function paginate(op, initialParams, ctx, write = writeStdout) {
       process.stderr.write(`> [page ${pages + 1}] ${op.method} ${url}
 `);
     }
-    const res = await fetchFn(url, { method: op.method, headers });
+    const res = await fetchWithTimeout(fetchFn, url, {
+      method: op.method,
+      headers
+    });
     const body = await res.text();
     let json = null;
     try {
@@ -3619,7 +3719,7 @@ import os2 from "node:os";
 import path2 from "node:path";
 
 // src/version.ts
-var CLI_VERSION = "2.7.0";
+var CLI_VERSION = "2.8.1";
 
 // src/runtime/update_check.ts
 var UPDATE_CACHE_PATH = path2.join(os2.homedir(), ".config", "echopai", "update_cache.json");
@@ -3752,9 +3852,10 @@ async function invoke(op, args, ctx) {
     }
     throw e;
   }
+  const opOwnedFlags = new Set(Object.keys(op.inputSchema.properties).filter((k) => SYSTEM_FLAGS.has(k)));
   const apiParams = {};
   for (const [k, v] of Object.entries(args)) {
-    if (SYSTEM_FLAGS.has(k))
+    if (SYSTEM_FLAGS.has(k) && !opOwnedFlags.has(k))
       continue;
     if (v === undefined || v === "")
       continue;
@@ -3861,7 +3962,7 @@ async function invoke(op, args, ctx) {
   const startedAt = Date.now();
   let res;
   try {
-    res = await fetch(url, init);
+    res = await fetchWithTimeout(fetch, url, init);
   } catch (e) {
     trace(op, { exit_code: 2, error_code: "network_error" });
     writeError("network_error", e instanceof Error ? e.message : String(e), 2);
@@ -3921,9 +4022,10 @@ async function invoke(op, args, ctx) {
   let envelope = rawEnvelope;
   try {
     const jq = typeof args.jq === "string" ? args.jq : undefined;
+    const fieldsProjection = opOwnedFlags.has("fields") ? undefined : parseFieldsFlag(args.fields);
     envelope = applyFilters(rawEnvelope, {
       ...jq ? { query: jq } : {},
-      ...parseFieldsFlag(args.fields) ? { fields: parseFieldsFlag(args.fields) } : {},
+      ...fieldsProjection ? { fields: fieldsProjection } : {},
       ...parseMaxBytesFlag(args.max_bytes) ? { maxBytes: parseMaxBytesFlag(args.max_bytes) } : {}
     });
   } catch (e) {
@@ -4089,7 +4191,7 @@ async function getWhoami(ctx, opts) {
   if (inflight && inflight.key === key) {
     return inflight.promise;
   }
-  const promise = doFetch(ctx, opts?.fetchImpl).then((resp) => {
+  const promise = doFetch(ctx, opts?.fetchImpl, opts?.requestTimeoutMs).then((resp) => {
     cache = { key, resp, expiresAt: Date.now() + ttlMs };
     return resp;
   }).finally(() => {
@@ -4099,7 +4201,7 @@ async function getWhoami(ctx, opts) {
   inflight = { key, promise };
   return promise;
 }
-async function doFetch(ctx, fetchImpl) {
+async function doFetch(ctx, fetchImpl, requestTimeoutMs = WHOAMI_TIMEOUT_MS) {
   const fn = fetchImpl ?? fetch;
   const url = ctx.baseUrl.replace(/\/+$/, "") + "/v1/auth/whoami";
   const { headers, requestId: clientRequestId } = buildHttpHeaders({
@@ -4109,7 +4211,7 @@ async function doFetch(ctx, fetchImpl) {
   });
   let res;
   try {
-    res = await fn(url, { method: "GET", headers });
+    res = await fetchWithTimeout(fn, url, { method: "GET", headers }, requestTimeoutMs);
   } catch (e) {
     throw new CallApiError({
       code: "network_error",
@@ -4255,7 +4357,7 @@ async function callOp(op, args, ctx) {
   const startedAt = Date.now();
   let res;
   try {
-    res = await fetchFn(url, init);
+    res = await fetchWithTimeout(fetchFn, url, init);
   } catch (e) {
     throw new CallApiError({
       code: "network_error",
@@ -4533,6 +4635,19 @@ function buildBarsBatchCommand() {
   });
   return cmd;
 }
+// src/verbs/capabilities.ts
+var capabilitiesSpec = {
+  name: "capabilities",
+  description: "API capability changelog and spec-version discovery. Returns the current spec version plus a newest-first changelog of capability changes (new endpoints, new fields, behavior fixes). Call once at session start — or when a response shape surprises you — to learn what changed since your integration was written. Free, unauthenticated, non-billable.",
+  inputSchema: {},
+  handler: async (_args, ctx) => {
+    const op = OPERATIONS["capabilities.show"];
+    if (!op)
+      throw new Error("capabilities.show op missing from codegen");
+    return callOp(op, {}, ctx);
+  },
+  backingOps: ["capabilities.show"]
+};
 // src/verbs/chart.ts
 import { Command as Command5, Option as Option4 } from "commander";
 import { z as z3 } from "zod";
@@ -5478,9 +5593,29 @@ function buildHotCommand() {
   });
   return cmd;
 }
+// src/verbs/indices.ts
+import { z as z8 } from "zod";
+var indexSnapshotSpec = {
+  name: "index_snapshot",
+  description: "Real-time snapshot for the 172 A-share indices with a live quote feed (e.g. 上证指数 SSE:000001, 深证成指 SZSE:399001, 创业板指 SZSE:399006, 科创50 SSE:000688, 北证50 BSE:899050): price, pct_change, amount, speed_3min per index, refreshed ~15s during market hours (last intraday snapshot outside trading hours). Pass `codes` to narrow to a subset; omit for all 172. Use this for 'how is the broad market doing right now' — `quote` covers individual stocks only. CSI-series indices (CSI:*) have no live feed and are not returned.",
+  inputSchema: {
+    codes: z8.array(z8.string().regex(/^(SSE|SZSE|BSE):[0-9]{6}$/)).min(1).max(172).optional().describe("Canonical index codes to narrow the snapshot (e.g. ['SSE:000001', 'BSE:899050']); omit for all 172")
+  },
+  handler: async (args, ctx) => {
+    const op = OPERATIONS["index.snapshot"];
+    if (!op)
+      throw new Error("index.snapshot op missing from codegen");
+    const callArgs = {};
+    if (Array.isArray(args.codes) && args.codes.length > 0) {
+      callArgs.codes = args.codes.join(",");
+    }
+    return callOp(op, callArgs, ctx);
+  },
+  backingOps: ["index.snapshot"]
+};
 // src/verbs/limit_up.ts
 import { Command as Command11, Option as Option9 } from "commander";
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var DATE_RE5 = /^\d{4}-\d{2}-\d{2}$/;
 var INCLUDE_VALUES = ["active", "all"];
 function clampInt5(raw, min, max, fallback) {
@@ -5497,9 +5632,9 @@ var limitUpPoolSpec = {
   name: "limit_up_pool",
   description: "A-share limit-up pool for a given trade date — per-stock detail: first/last seal time, final pct, seal amount/volume, broken count, consecutive_days (连板数), board_count_within (N-day 板数), one-word-board flag, current status (limit_up / broken), board classification. Sort: consecutive_days desc → board_count_within desc → seal_amount desc. Pre-open fallback applies. Use when an agent needs the concrete list of '今天涨停了哪些票'.",
   inputSchema: {
-    trade_date: z8.string().regex(DATE_RE5).optional().describe("ISO date YYYY-MM-DD; omit for latest (pre-open fallback)"),
-    include: z8.enum(INCLUDE_VALUES).default("active").describe("active = 排除 ST/退市（默认）; all = 全部"),
-    include_broken: z8.boolean().default(false).describe("true 时连炸板（status=broken）也一起返回；默认只返回当前封板 status=limit_up")
+    trade_date: z9.string().regex(DATE_RE5).optional().describe("ISO date YYYY-MM-DD; omit for latest (pre-open fallback)"),
+    include: z9.enum(INCLUDE_VALUES).default("active").describe("active = 排除 ST/退市（默认）; all = 全部"),
+    include_broken: z9.boolean().default(false).describe("true 时连炸板（status=broken）也一起返回；默认只返回当前封板 status=limit_up")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["limit-up.pool"];
@@ -5519,8 +5654,8 @@ var limitUpSummarySpec = {
   name: "limit_up_summary",
   description: "Limit-up summary for a given trade date: 涨停数 (limit_up_count) / 炸板数 (broken_count) / 跌停数 (limit_down_count) / 最高连板 (max_height) / 连板梯队 ladder[{height, count}]. 炸板/跌停 与情绪页同源 (market_breadth_intraday 当日最新分钟行). Pre-open fallback applies.",
   inputSchema: {
-    trade_date: z8.string().regex(DATE_RE5).optional().describe("ISO date YYYY-MM-DD; omit for latest"),
-    include: z8.enum(INCLUDE_VALUES).default("active").describe("active = all_a_ex_st 口径（默认）; all = all_a 口径")
+    trade_date: z9.string().regex(DATE_RE5).optional().describe("ISO date YYYY-MM-DD; omit for latest"),
+    include: z9.enum(INCLUDE_VALUES).default("active").describe("active = all_a_ex_st 口径（默认）; all = all_a 口径")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["limit-up.summary"];
@@ -5537,7 +5672,7 @@ var limitUpHistorySpec = {
   name: "limit_up_history",
   description: "Daily limit-up trend over the last N trading days: { trade_date, limit_up_count, broken_count, max_height }. 涨停数/最高连板 from market_limit_up_pool; 炸板数 from market_breadth_intraday (all_a_ex_st). Sorted by trade_date asc (oldest first).",
   inputSchema: {
-    days: z8.number().int().min(1).max(250).default(30).describe("Lookback window in trading days (1-250, default 30)")
+    days: z9.number().int().min(1).max(250).default(30).describe("Lookback window in trading days (1-250, default 30)")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["limit-up.history"];
@@ -5551,7 +5686,7 @@ var limitUpAnalysisSpec = {
   name: "limit_up_analysis",
   description: "Per-stock limit-up LLM attribution for a given trade date: leading_concept (主导题材) + concept_tags (相关标签) + reason (涨停理由). Themes are judged by an LLM from the latest research / views / news (NOT from the concept graph, so brand-new themes are covered) and refreshed across 6 Beijing slots daily. Complements limit-up pool (which says '哪些票涨停'); this says '为什么涨停/属什么题材'. STALE-DATA WARNING: omitting trade_date returns the latest *attributed* trading day, NOT necessarily today — before today's first slot lands (~09:47 Beijing) it falls back to the PREVIOUS day's attribution. For today's data pass trade_date explicitly and verify the returned trade_date / generated_at fields. An explicit trade_date with no attribution yet returns an empty analyses list.",
   inputSchema: {
-    trade_date: z8.string().regex(DATE_RE5).optional().describe("ISO date YYYY-MM-DD; omit for the latest *attributed* day (falls back to the previous day until today's first slot lands ~09:47 Beijing — pass today explicitly for today's data)")
+    trade_date: z9.string().regex(DATE_RE5).optional().describe("ISO date YYYY-MM-DD; omit for the latest *attributed* day (falls back to the previous day until today's first slot lands ~09:47 Beijing — pass today explicitly for today's data)")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["limit-up.analysis"];
@@ -5617,7 +5752,7 @@ function buildLimitUpCommand() {
 }
 // src/verbs/lookup.ts
 import { Command as Command12, Option as Option10 } from "commander";
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 function mapLookupResponse(raw) {
   if (!Array.isArray(raw))
     return [];
@@ -5641,8 +5776,8 @@ var lookupSpec = {
   name: "lookup",
   description: "Resolve a Chinese name / A-share code / pinyin initials to canonical codes (e.g. SSE:600519). Use this first whenever the agent has a description but needs a canonical_code for downstream calls. AH dual-listing: when a company is listed on both A-share and HK (e.g. 工商银行 SSE:601398 / HK:01398), prefer the A-share canonical for all downstream analysis unless the user explicitly asks for the HK side.",
   inputSchema: {
-    text: z9.string().min(1).max(50).describe("Search text: Chinese name (贵州茅台), code (600519), or pinyin (gzmt)"),
-    limit: z9.number().int().min(1).max(30).default(10).describe("Max matches (1-30)")
+    text: z10.string().min(1).max(50).describe("Search text: Chinese name (贵州茅台), code (600519), or pinyin (gzmt)"),
+    limit: z10.number().int().min(1).max(30).default(10).describe("Max matches (1-30)")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["semantic.find"];
@@ -5676,7 +5811,7 @@ function buildLookupCommand() {
 }
 // src/verbs/market.ts
 import { Command as Command13, Option as Option11 } from "commander";
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 var marketStatusSpec = {
   name: "market_status",
   description: "Current A-share market session: pre-open / open / lunch / closed; current and next trading day; holiday flag. Cheap and non-billable — call it before any quote / bars fetch when the agent needs to decide pre-market fallback vs intraday vs after-close behavior.",
@@ -5729,10 +5864,10 @@ var marketMoversSpec = {
   name: "market_movers",
   description: "A-share market movers — top N from the full real-time snapshot, sorted by chosen field. Sort keys: `pct` (涨幅榜) / `pct_asc` (跌幅榜) / `speed` (3-min 涨速 speed_3min) / `amount` (成交额) / `turnover` (换手率 turnover_rate) / `total_mv` (总市值). Backed by `quote.scan` so 9:00-9:14 集合竞价时段会返空 (with `note`). Defaults: sort=pct, top=20, include=active (排除 ST / 退市). Use this for /market-style 'who's running today' instead of pulling the full 3 MB scan and sorting client-side.",
   inputSchema: {
-    sort: z10.enum(MOVERS_SORT_VALUES).default("pct").describe("Sort field: pct / pct_asc / speed / amount / turnover / total_mv"),
-    top: z10.number().int().min(1).max(500).default(20).describe("Top N items (1-500, default 20)"),
-    exchange: z10.enum(EXCHANGE_VALUES).optional().describe("Narrow to one exchange: SSE / SZSE / BSE"),
-    include: z10.enum(INCLUDE_VALUES2).default("active").describe("active = 排除 ST/退市（默认）; all = 全集（含 ST + 退市 + 未知 status）")
+    sort: z11.enum(MOVERS_SORT_VALUES).default("pct").describe("Sort field: pct / pct_asc / speed / amount / turnover / total_mv"),
+    top: z11.number().int().min(1).max(500).default(20).describe("Top N items (1-500, default 20)"),
+    exchange: z11.enum(EXCHANGE_VALUES).optional().describe("Narrow to one exchange: SSE / SZSE / BSE"),
+    include: z11.enum(INCLUDE_VALUES2).default("active").describe("active = 排除 ST/退市（默认）; all = 全集（含 ST + 退市 + 未知 status）")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["quote.scan"];
@@ -5816,18 +5951,19 @@ function buildMarketCommand() {
 }
 // src/verbs/news.ts
 import { Command as Command14, Option as Option12 } from "commander";
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 var newsSpec = {
   name: "news",
-  description: "SUPPLEMENTARY news / market briefs (short time-horizon event stream). Use ONLY to fill gaps not covered by `views`; prefer `views` as the primary research source. Three modes: `code` (canonical, works across A-share | HK | US — e.g. SSE:600519, HK:00700 腾讯, US:BABA) → news mentioning that security; `query` (free text) → full-text search; neither → recent time-window feed. AH dual-listing: when filtering by `code` for an A+H listed company, pass the A-share canonical (e.g. SSE:601398) for consolidated coverage; HK side only if the user explicitly asks. Note: `query` is matched against news text, so passing a canonical_code as `query` will not work — use `code` for security filtering.",
+  description: "SUPPLEMENTARY news / market briefs (short time-horizon event stream). Use ONLY to fill gaps not covered by `views`; prefer `views` as the primary research source. Returns `fields=compact` by default (title + ai_summary + first ~300 chars of content, `content_truncated` flag) — typically 20-50x smaller than full; pass fields='full' only when you need complete article text. Three modes: `code` (canonical, works across A-share | HK | US — e.g. SSE:600519, HK:00700 腾讯, US:BABA) → news mentioning that security; `query` (free text) → full-text search; neither → recent time-window feed. AH dual-listing: when filtering by `code` for an A+H listed company, pass the A-share canonical (e.g. SSE:601398) for consolidated coverage; HK side only if the user explicitly asks. Note: `query` is matched against news text, so passing a canonical_code as `query` will not work — use `code` for security filtering.",
   inputSchema: {
-    code: z11.string().regex(/^((SSE|SZSE|BSE):[0-9]{6}|HK:[0-9]{5}|US:[A-Z][A-Z0-9.\-]{0,5})$/).optional().describe("Filter by security canonical_code (e.g. SSE:600519, HK:00700). Takes precedence over `query`."),
-    query: z11.string().optional().describe("Free-text query (Chinese or English) matched against news content; omit for time-window feed. Do NOT pass canonical_code here — use `code` instead."),
-    hours: z11.number().int().min(1).max(168).default(24).describe("Rolling-feed lookback in hours (default 24 — much narrower than views). For longer history use from/to with code or query."),
-    from: z11.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("History range start (China date YYYY-MM-DD). Range mode: needs code or query; Pro-only up to 365 days back."),
-    to: z11.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("History range end (inclusive, China date; defaults to today). Use with from."),
-    offset: z11.number().int().min(0).optional().describe("Pagination offset for paging through long history ranges."),
-    limit: z11.number().int().min(1).max(100).default(20).describe("Max items per page")
+    code: z12.string().regex(/^((SSE|SZSE|BSE):[0-9]{6}|HK:[0-9]{5}|US:[A-Z][A-Z0-9.\-]{0,5})$/).optional().describe("Filter by security canonical_code (e.g. SSE:600519, HK:00700). Takes precedence over `query`."),
+    query: z12.string().optional().describe("Free-text query (Chinese or English) matched against news content; omit for time-window feed. Do NOT pass canonical_code here — use `code` instead."),
+    hours: z12.number().int().min(1).max(168).default(24).describe("Rolling-feed lookback in hours (default 24 — much narrower than views). For longer history use from/to with code or query."),
+    from: z12.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("History range start (China date YYYY-MM-DD). Range mode: needs code or query; Pro-only up to 365 days back."),
+    to: z12.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("History range end (inclusive, China date; defaults to today). Use with from."),
+    offset: z12.number().int().min(0).optional().describe("Pagination offset for paging through long history ranges."),
+    limit: z12.number().int().min(1).max(100).default(20).describe("Max items per page"),
+    fields: z12.enum(["compact", "full"]).optional().describe("Response shape: compact (default — title + ai_summary + first ~300 chars) or full (complete content)")
   },
   handler: async (args, ctx) => {
     const { opKey, callArgs } = buildNewsCall(args);
@@ -5840,11 +5976,14 @@ var newsSpec = {
 };
 function buildNewsCall(args) {
   const hasRange = typeof args.from === "string" && args.from.length > 0;
+  const fields = args.fields === "compact" || args.fields === "full" ? args.fields : undefined;
   const withWindow = (a) => {
     if (typeof args.limit === "number")
       a.limit = args.limit;
     if (typeof args.offset === "number")
       a.offset = args.offset;
+    if (fields)
+      a.fields = fields;
     if (hasRange) {
       a.from = args.from;
       if (typeof args.to === "string" && args.to.length > 0)
@@ -5861,7 +6000,7 @@ function buildNewsCall(args) {
   if (hasRange) {
     throw new Error("range history (from/to) requires --code or --query; the bare feed has no narrowing filter");
   }
-  return { opKey: "news.feed", callArgs: {} };
+  return { opKey: "news.feed", callArgs: fields ? { fields } : {} };
 }
 function clamp3(raw, min, max, fallback) {
   const n = Math.floor(Number(raw));
@@ -5882,6 +6021,10 @@ function buildNewsCommand() {
   cmd.addOption(new Option12("--to <date>", "History range end YYYY-MM-DD (inclusive; default today)"));
   cmd.addOption(new Option12("--offset <n>", "Pagination offset for long history").default("0"));
   cmd.addOption(new Option12("--limit <n>", "Max items").default("20"));
+  cmd.addOption(new Option12("--fields <mode>", "Response shape: compact (default) or full").choices([
+    "compact",
+    "full"
+  ]));
   cmd.action(async (opts) => {
     const args = {
       hours: clamp3(opts.hours, 1, 168, 24),
@@ -5896,19 +6039,21 @@ function buildNewsCommand() {
       args.from = opts.from;
     if (opts.to)
       args.to = opts.to;
+    if (opts.fields)
+      args.fields = opts.fields;
     await executeVerb(async (ctx) => newsSpec.handler(args, ctx));
   });
   return cmd;
 }
 // src/verbs/quote.ts
 import { Command as Command15, Option as Option13 } from "commander";
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 var quoteSpec = {
   name: "quote",
   description: "Real-time quote for 1-200 A-share securities (last price, volume, change %, bid/ask). For >200 codes use `scan` instead. AH dual-listing: HK codes are not supported here; for an A+H listed company use the A-share canonical (e.g. SSE:601398 not HK:01398).",
   inputSchema: {
-    codes: z12.array(z12.string().regex(/^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$/)).min(1).max(200).describe("Array of canonical codes (e.g. ['SSE:600519', 'SZSE:000001'])"),
-    include_l2: z12.boolean().optional().describe("Include L2 5-level order book (requires quote:l2 scope)")
+    codes: z13.array(z13.string().regex(/^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$/)).min(1).max(200).describe("Array of canonical codes (e.g. ['SSE:600519', 'SZSE:000001'])"),
+    include_l2: z13.boolean().optional().describe("Include L2 5-level order book (requires quote:l2 scope)")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["quote"];
@@ -5939,12 +6084,12 @@ function buildQuoteCommand() {
 }
 // src/verbs/scan.ts
 import { Command as Command16, Option as Option14 } from "commander";
-import { z as z13 } from "zod";
+import { z as z14 } from "zod";
 var scanSpec = {
   name: "scan",
   description: "Full-market real-time quote scan (~5800 A-share securities in one round-trip). Use for universe discovery; agents should slim output with field/byte limits in their tool host or post-processing.",
   inputSchema: {
-    exchange: z13.enum(["SSE", "SZSE", "BSE"]).optional().describe("Filter by exchange (omit for all)")
+    exchange: z14.enum(["SSE", "SZSE", "BSE"]).optional().describe("Filter by exchange (omit for all)")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["quote.scan"];
@@ -5973,16 +6118,16 @@ function buildScanCommand() {
 }
 // src/verbs/search.ts
 import { Command as Command17, Option as Option15 } from "commander";
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 var searchSpec = {
   name: "search",
   description: "Structured-first hybrid search across analyst views + news (views weighted higher per feedback_views_over_news). Three lanes — entity (company codes / names, analyst names), concept-graph hub (theme alias → concept → constituents & research), and ParadeDB BM25 full-text (jieba) — fused with RRF. Deterministic & explainable: no vector kNN, no LLM rerank. Best for theme/concept queries: 'CPO' brings out 光模块/光通信/光芯片; '减肥药' brings out 创新药; '智驾' brings out 智能驾驶. Use `news` or `views` instead if you need strict time-window listing.",
   inputSchema: {
-    q: z14.string().min(1).max(200).describe("Free-text query (Chinese or English)"),
-    type: z14.enum(["news", "views", "all"]).default("all").describe("Search scope (views weighted higher in 'all')"),
-    mode: z14.enum(["hybrid", "exact"]).default("hybrid").describe("hybrid = entity + concept-graph + BM25 fused; exact = BM25 keyword only"),
-    hours: z14.number().int().min(1).max(720).optional().describe("Lookback window in hours; omit for no time limit"),
-    limit: z14.number().int().min(1).max(50).default(20).describe("Max items returned")
+    q: z15.string().min(1).max(200).describe("Free-text query (Chinese or English)"),
+    type: z15.enum(["news", "views", "all"]).default("all").describe("Search scope (views weighted higher in 'all')"),
+    mode: z15.enum(["hybrid", "exact"]).default("hybrid").describe("hybrid = entity + concept-graph + BM25 fused; exact = BM25 keyword only"),
+    hours: z15.number().int().min(1).max(720).optional().describe("Lookback window in hours; omit for no time limit"),
+    limit: z15.number().int().min(1).max(50).default(20).describe("Max items returned")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["search.semantic"];
@@ -6035,7 +6180,7 @@ function buildSearchCommand() {
 }
 // src/verbs/sentiment.ts
 import { Command as Command18, Option as Option16 } from "commander";
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 var SCOPE_VALUES = [
   "all_a",
   "all_a_ex_st",
@@ -6059,8 +6204,8 @@ var sentimentSpec = {
   name: "sentiment",
   description: "Aggregate market sentiment indicators (limit-up/down counts, breadth, divergence index, top movers). Defaults to all_a_ex_st (all A-shares ex-ST). Pass `at_date` (YYYY-MM-DD) for any historical trading day; omit for today's latest snapshot. Backward-compat alias of `sentiment_overview` — prefer the latter in new agent code.",
   inputSchema: {
-    scope: z15.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
-    at_date: z15.string().regex(DATE_RE6).optional().describe("Trade date YYYY-MM-DD; omit for today's realtime snapshot")
+    scope: z16.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
+    at_date: z16.string().regex(DATE_RE6).optional().describe("Trade date YYYY-MM-DD; omit for today's realtime snapshot")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["sentiment.overview"];
@@ -6077,8 +6222,8 @@ var sentimentOverviewSpec = {
   name: "sentiment_overview",
   description: "Aggregate sentiment snapshot for one trading day's latest minute: up/down/flat counts, limit-up/down, gt3/lt3 breadth, divergence index + label, MA20/50/200 breadth, 52w new high/low. `at_date` omitted = today realtime (Redis); explicit YYYY-MM-DD = historical from ClickHouse `market_breadth_intraday` last minute.",
   inputSchema: {
-    scope: z15.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
-    at_date: z15.string().regex(DATE_RE6).optional().describe("Trade date YYYY-MM-DD; omit for today realtime")
+    scope: z16.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
+    at_date: z16.string().regex(DATE_RE6).optional().describe("Trade date YYYY-MM-DD; omit for today realtime")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["sentiment.overview"];
@@ -6095,8 +6240,8 @@ var sentimentBreadthSpec = {
   name: "sentiment_breadth",
   description: "Intraday breadth time series for one trading day (up to 241 minute bars; 13:00 excluded due to sparse Sina ticks). `at_date` omitted = today (pre-open returns empty); explicit YYYY-MM-DD = historical replay. Returns per-minute rows of up/down/flat/limit_up/limit_down/breadth/divergence fields — same shape as `sentiment_overview` per row.",
   inputSchema: {
-    scope: z15.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
-    at_date: z15.string().regex(DATE_RE6).optional().describe("Trade date YYYY-MM-DD; omit for today")
+    scope: z16.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
+    at_date: z16.string().regex(DATE_RE6).optional().describe("Trade date YYYY-MM-DD; omit for today")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["sentiment.breadth"];
@@ -6113,9 +6258,9 @@ var sentimentTurnoverSpec = {
   name: "sentiment_turnover",
   description: "Intraday turnover time series with `current_turnover` / `predicted_total` / `delta_vs_yesterday` headline fields. `at_date` omitted = today (pre-open returns nulls); explicit YYYY-MM-DD = historical. `days` (1-5) pulls that day + N-1 prior trading days for same-minute YoY comparison.",
   inputSchema: {
-    scope: z15.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
-    at_date: z15.string().regex(DATE_RE6).optional().describe("Trade date YYYY-MM-DD; omit for today"),
-    days: z15.number().int().min(1).max(5).default(1).describe("at_date 当日 + 之前 days-1 天（1-5，默认 1）")
+    scope: z16.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
+    at_date: z16.string().regex(DATE_RE6).optional().describe("Trade date YYYY-MM-DD; omit for today"),
+    days: z16.number().int().min(1).max(5).default(1).describe("at_date 当日 + 之前 days-1 天（1-5，默认 1）")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["sentiment.turnover"];
@@ -6210,19 +6355,20 @@ function buildSentimentCommand() {
 }
 // src/verbs/views.ts
 import { Command as Command19, Option as Option17 } from "commander";
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 var viewsSpec = {
   name: "views",
-  description: "PRIMARY research source for stock judgement: analyst views / sell-side reports / long-form opinion stream, with research_entity_id attribution. Prefer this over `news` when forming an investment opinion. Each item carries `full_text_available`; when true the item is a parsed research report and you can pull its full text with the `report` verb. AH dual-listing: for an A+H listed company pass the A-share canonical to get the consolidated coverage (most domestic analyst views attribute to the A-share security); use HK code only if the user explicitly asks for the HK perspective.",
+  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. Returns `fields=compact` by default (ai_summary + first ~300 chars of content, `content_truncated` flag) — typically 20-50x smaller than full; pass fields='full' only when summaries are not enough. Recommended reading path: `digest` for a one-shot overview → this verb (compact) to scan → `report` for the full text of a single item (`full_text_available=true` means a parsed research report). AH dual-listing: for an A+H listed company pass the A-share canonical to get the consolidated coverage (most domestic analyst views attribute to the A-share security); use HK code only if the user explicitly asks for the HK perspective.",
   inputSchema: {
-    code: z16.string().regex(/^((SSE|SZSE|BSE):[0-9]{6}|HK:[0-9]{5}|US:[A-Z][A-Z0-9.\-]{0,5})$/).optional().describe("Filter by security canonical_code (e.g. SSE:600519, HK:00700, US:AAPL)"),
-    analyst: z16.string().optional().describe("Analyst Chinese name (exact / fuzzy)"),
-    institution: z16.string().optional().describe("Broker / institution Chinese name"),
-    since_days: z16.number().int().min(1).max(365).default(7).describe("Lookback in days. ≤30 = rolling feed; >30 auto-switches to range history " + "(needs a code/analyst/institution filter; Pro-only up to 365). For an explicit window use from/to."),
-    from: z16.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("History range start (China date YYYY-MM-DD). Range mode: needs a filter; Pro-only up to 365 days back."),
-    to: z16.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("History range end (inclusive, China date; defaults to today). Use with from."),
-    offset: z16.number().int().min(0).optional().describe("Pagination offset for paging through long history ranges."),
-    limit: z16.number().int().min(1).max(100).default(30).describe("Max items per page")
+    code: z17.string().regex(/^((SSE|SZSE|BSE):[0-9]{6}|HK:[0-9]{5}|US:[A-Z][A-Z0-9.\-]{0,5})$/).optional().describe("Filter by security canonical_code (e.g. SSE:600519, HK:00700, US:AAPL)"),
+    analyst: z17.string().optional().describe("Analyst Chinese name (exact / fuzzy)"),
+    institution: z17.string().optional().describe("Broker / institution Chinese name"),
+    since_days: z17.number().int().min(1).max(365).default(7).describe("Lookback in days. ≤30 = rolling feed; >30 auto-switches to range history " + "(needs a code/analyst/institution filter; Pro-only up to 365). For an explicit window use from/to."),
+    from: z17.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("History range start (China date YYYY-MM-DD). Range mode: needs a filter; Pro-only up to 365 days back."),
+    to: z17.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("History range end (inclusive, China date; defaults to today). Use with from."),
+    offset: z17.number().int().min(0).optional().describe("Pagination offset for paging through long history ranges."),
+    limit: z17.number().int().min(1).max(100).default(30).describe("Max items per page"),
+    fields: z17.enum(["compact", "full"]).optional().describe("Response shape: compact (default — ai_summary + first ~300 chars) or full (complete content)")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["views.recent"];
@@ -6246,6 +6392,8 @@ function buildViewsCallArgs(args) {
     callArgs.institution = args.institution;
   if (typeof args.offset === "number")
     callArgs.offset = args.offset;
+  if (args.fields === "compact" || args.fields === "full")
+    callArgs.fields = args.fields;
   const explicitRange = typeof args.from === "string" && args.from.length > 0;
   if (explicitRange || sinceDays > 30) {
     if (!hasFilter) {
@@ -6267,10 +6415,10 @@ var reportSpec = {
   name: "report",
   description: "Fetch the FULL research-report text behind a view (mineru-parsed long-form), for when the `views` summary is not enough. Only works on views where `full_text_available=true` (gdrive sell-side reports). Two-step usage: default `format=outline` returns a few-KB heading map + total_chars + each heading's char_offset; then call `format=full` with `offset` (e.g. an outline char_offset) to read the body in pages — follow `next_offset` to page through large docs instead of pulling everything at once.",
   inputSchema: {
-    view_id: z16.string().regex(/^[0-9]+$/).describe("View id from `views` items[].id (must have full_text_available=true)"),
-    format: z16.enum(["outline", "full"]).default("outline").describe("outline=heading map (default); full=body slice"),
-    offset: z16.number().int().min(0).default(0).describe("full mode: start char offset (use an outline char_offset)"),
-    max_chars: z16.number().int().min(1).max(80000).default(40000).describe("full mode: max chars per page (hard cap 80000)")
+    view_id: z17.string().regex(/^[0-9]+$/).describe("View id from `views` items[].id (must have full_text_available=true)"),
+    format: z17.enum(["outline", "full"]).default("outline").describe("outline=heading map (default); full=body slice"),
+    offset: z17.number().int().min(0).default(0).describe("full mode: start char offset (use an outline char_offset)"),
+    max_chars: z17.number().int().min(1).max(80000).default(40000).describe("full mode: max chars per page (hard cap 80000)")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["views.document"];
@@ -6308,6 +6456,10 @@ function buildViewsCommand() {
   cmd.addOption(new Option17("--to <date>", "History range end YYYY-MM-DD (inclusive; default today)"));
   cmd.addOption(new Option17("--offset <n>", "Pagination offset for long history").default("0"));
   cmd.addOption(new Option17("--limit <n>", "Max items (1-100)").default("30"));
+  cmd.addOption(new Option17("--fields <mode>", "Response shape: compact (default) or full").choices([
+    "compact",
+    "full"
+  ]));
   cmd.action(async (opts) => {
     if (!OPERATIONS["views.recent"]) {
       emitVerbError("internal_error", "views.recent missing from codegen", undefined, 2);
@@ -6327,6 +6479,8 @@ function buildViewsCommand() {
       args.from = opts.from;
     if (opts.to)
       args.to = opts.to;
+    if (opts.fields)
+      args.fields = opts.fields;
     await executeVerb(async (ctx) => viewsSpec.handler(args, ctx));
   });
   return cmd;
@@ -6360,6 +6514,7 @@ var ALL_VERB_SPECS = [
   quoteSpec,
   marketStatusSpec,
   marketMoversSpec,
+  indexSnapshotSpec,
   viewsSpec,
   reportSpec,
   newsSpec,
@@ -6394,7 +6549,8 @@ var ALL_VERB_SPECS = [
   financialsReportsSpec,
   financialsSeriesSpec,
   ownershipShowSpec,
-  ownershipLockupsSpec
+  ownershipLockupsSpec,
+  capabilitiesSpec
 ];
 
 // src/tools/mcp.ts
@@ -6469,24 +6625,51 @@ function buildMcpCommand() {
       }
       throw e;
     }
-    let whoami;
-    try {
-      whoami = await getWhoami({
-        baseUrl: creds.baseUrl,
-        bearer: creds.key,
-        cliVersion: CLI_VERSION,
-        channel: "mcp"
-      });
-    } catch (e) {
-      process.stderr.write(`[mcp] whoami failed: ${e instanceof Error ? e.message : String(e)}
+    const WHOAMI_MAX_ATTEMPTS = 3;
+    const WHOAMI_BACKOFF_MS = [500, 1500];
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    let whoami = null;
+    let lastErr = null;
+    for (let attempt = 1;attempt <= WHOAMI_MAX_ATTEMPTS; attempt++) {
+      try {
+        whoami = await getWhoami({
+          baseUrl: creds.baseUrl,
+          bearer: creds.key,
+          cliVersion: CLI_VERSION,
+          channel: "mcp"
+        });
+        break;
+      } catch (e) {
+        lastErr = e;
+        const status = e instanceof CallApiError ? e.httpStatus : undefined;
+        const code = e instanceof CallApiError ? e.code : undefined;
+        const isAuthError = status === 401 || status === 403 || code === "auth_missing" || code === "forbidden";
+        if (isAuthError) {
+          process.stderr.write(`[mcp] whoami auth failed${status ? ` (HTTP ${status})` : ""}: ` + `${e instanceof Error ? e.message : String(e)}
+` + "[mcp] hint: key 失效或无权限，请 `echopai login` 或检查 ECHOPAI_KEY。\n");
+          process.exit(1);
+        }
+        if (attempt < WHOAMI_MAX_ATTEMPTS) {
+          const backoffMs = WHOAMI_BACKOFF_MS[attempt - 1] ?? 1500;
+          process.stderr.write(`[mcp] whoami attempt ${attempt}/${WHOAMI_MAX_ATTEMPTS} failed ` + `(${e instanceof Error ? e.message : String(e)}); ` + `retrying in ${backoffMs}ms
 `);
-      process.exit(1);
+          await sleep(backoffMs);
+        }
+      }
     }
-    const tokenScopes = new Set(whoami.scopes);
-    const availableVerbs = filterAvailableVerbs(ALL_VERB_SPECS, tokenScopes);
-    process.stderr.write(`[mcp] kind=${whoami.kind} scopes=[${whoami.scopes.join(",")}]
+    let availableVerbs;
+    if (whoami) {
+      const tokenScopes = new Set(whoami.scopes);
+      availableVerbs = filterAvailableVerbs(ALL_VERB_SPECS, tokenScopes);
+      process.stderr.write(`[mcp] kind=${whoami.kind} scopes=[${whoami.scopes.join(",")}]
 ` + `[mcp] exposing ${availableVerbs.length}/${ALL_VERB_SPECS.length} curated verbs as MCP tools
 `);
+    } else {
+      availableVerbs = [...ALL_VERB_SPECS];
+      process.stderr.write(`[mcp] whoami failed after ${WHOAMI_MAX_ATTEMPTS} attempts: ` + `${lastErr instanceof Error ? lastErr.message : String(lastErr)}
+` + `[mcp] degraded start: exposing all ${availableVerbs.length} curated verbs; ` + `scopes enforced per-call by the server
+`);
+    }
     const server = new McpServer({
       name: "echopai",
       version: CLI_VERSION,
@@ -7181,7 +7364,7 @@ function buildDoctorCommand() {
 
 // src/tools/schema.ts
 import { Command as Command27 } from "commander";
-import { z as z17 } from "zod";
+import { z as z18 } from "zod";
 
 // src/_generated/help.ts
 var HELP = {
@@ -7245,6 +7428,11 @@ var HELP = {
     description: "Returns minute-level OHLC bars for multiple A-share securities in one call: up to 20 codes and up to a 7 calendar-day (~5 trading-day) range. Responses use a partial-success envelope: codes the token may not access are reported in `errors[]`, the rest in `items[]` with a flat `bars[]` array where each bar carries its own `trade_date` for client-side grouping. Requires the `bars:30d` or `bars:full` scope.",
     example: "echopai bars minute-batch --codes ['SSE:600519', 'SZSE:000001']"
   },
+  "capabilities.show": {
+    summary: "Capability changelog and API version discovery.",
+    description: "Returns the current API spec version plus a machine-readable changelog of capability changes (new endpoints, new fields, behavior fixes), newest first. Check it at session start — or after an unexpected response shape — to discover capabilities added since your integration was written. Free and unauthenticated.",
+    example: "echopai capabilities show"
+  },
   "concepts.alerts": {
     summary: "List currently active concept alerts.",
     description: "Returns the live set of concept alerts. Two rules fire: `big_move` when absolute percent change exceeds 3%, and `limit_up_cluster` when a concept has at least 3 limit-up members across at least 5 member stocks.",
@@ -7357,7 +7545,7 @@ var HELP = {
   },
   "news.feed": {
     summary: "List recent news.",
-    description: "Returns recent news. Equivalent to `/v1/news/list`; retained for backward compatibility.",
+    description: "Returns recent news. Equivalent to `/v1/news/list`; retained for backward compatibility. Partner/agent callers receive `fields=compact` by default (id, title, ai_summary, tagged securities, first ~300 chars of content); pass `fields=full` for complete content.",
     example: "echopai news feed"
   },
   "news.get": {
@@ -7387,12 +7575,12 @@ var HELP = {
   },
   quote: {
     summary: "Get real-time quotes for one or more securities.",
-    description: "Returns real-time quotes for one or more A-share securities (canonical codes, e.g. `SSE:600519`): last price, volume, percent change, and bid/ask. Up to 200 codes per call. Requires a `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
+    description: "Returns real-time quotes for one or more A-share securities (canonical codes, e.g. `SSE:600519`): last price, volume, percent change, and bid/ask. Up to 200 codes per call. The response carries a `session` label (`pre_open` / `auction` / `open` / `break` / `closed`) and, outside continuous trading, an explanatory `note`: during 9:00–9:14 pre-open the previous session's snapshot is returned; during the 9:15–9:29 call auction, prices are indicative auction match prices. Rows whose feed has stopped updating (suspension / feed drop) keep their last snapshot and are flagged `stale: true` with `stale_since`. Requires a `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
     example: "echopai quote --codes ['SSE:600519', 'SZSE:000001']"
   },
   "quote.scan": {
     summary: "Snapshot every A-share real-time quote in one call.",
-    description: "Returns a real-time quote for every A-share in a single call — use it for full-market scans or to discover a universe of interest when you do not yet know which codes to query. Filter with `exchange=SSE|SZSE|BSE` to narrow to one exchange. The payload is large (~3 MB, ~5,800 instruments), so pair it with `--fields`, `--jq`, or `--max-bytes` to trim it. During the 9:00–9:14 pre-open auction an empty result is returned with an explanatory note. Each item also includes `main_net_in` (current-day cumulative net main-capital inflow in CNY, which may be negative) and a companion `main_net_in_stale` flag (true when served from the last-close fallback). Requires a `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
+    description: "Returns a real-time quote for every A-share in a single call — use it for full-market scans or to discover a universe of interest when you do not yet know which codes to query. Filter with `exchange=SSE|SZSE|BSE` to narrow to one exchange. The payload is large (~3 MB, ~5,800 instruments), so pair it with `--fields`, `--jq`, or `--max-bytes` to trim it. The response carries a `session` label (`pre_open` / `auction` / `open` / `break` / `closed`) plus an explanatory `note` outside continuous trading: during 9:00–9:14 pre-open the previous session's snapshot is returned; during the 9:15–9:29 call auction, prices are indicative auction match prices. Instruments whose feed has stopped updating (suspension / feed drop) are excluded from the default scan; pass `include=all` to keep them, flagged with `stale: true` and `stale_since`. Each item also includes `main_net_in` (current-day cumulative net main-capital inflow in CNY, which may be negative) and a companion `main_net_in_stale` flag (true when served from the last-close fallback). Requires a `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
     example: "echopai quote scan"
   },
   "search.semantic": {
@@ -7442,7 +7630,7 @@ var HELP = {
   },
   "views.feed": {
     summary: "List analyst views.",
-    description: "Returns a stream of analyst views, sell-side research, and long-form opinion. Filter by institution, analyst, security, or recency (`hours`). Requires the `views:read` scope.",
+    description: "Returns a stream of analyst views, sell-side research, and long-form opinion. Filter by institution, analyst, security, or recency (`hours`). Partner/agent callers receive `fields=compact` by default (id, ai_summary, attribution, tagged securities, first ~300 chars of content); pass `fields=full` for complete content. Requires the `views:read` scope.",
     example: "echopai views feed"
   },
   "views.get": {
@@ -7461,7 +7649,7 @@ var HELP = {
 function verbToRecord(spec) {
   let inputSchema;
   try {
-    inputSchema = z17.toJSONSchema(z17.object(spec.inputSchema));
+    inputSchema = z18.toJSONSchema(z18.object(spec.inputSchema));
   } catch {
     inputSchema = {
       type: "object",

package/package.json

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