echopai 2.0.0

package/dist/_generated/operations.js

@@ -0,0 +1,1306 @@
+/**
+ * AUTO-GENERATED — DO NOT EDIT BY HAND.
+ *
+ * Source: docs/api-contract/openapi.yaml (operations with x-cli-key + x-visibility: public)
+ * Generator: scripts/codegen/generate_cli_v2.py
+ *
+ * Regenerate:
+ *   make codegen
+ */
+export const OPERATIONS = {
+    "agent.session-end": {
+        "cliKey": "agent.session-end",
+        "cliName": "agent session-end",
+        "method": "POST",
+        "path": "/v1/agent/session/{id}/end",
+        "description": "关闭 `/v1/agent/session/start` 开启的会话，最终用量提交入库。",
+        "summary": "End a billable agent session",
+        "positional": [
+            "id"
+        ],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": false,
+        "idempotencyRequired": true,
+        "scopesAny": [
+            "agent:session.create",
+            "agent:session.read"
+        ],
+        "sideEffect": "write",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "description": "Session id returned by /v1/agent/session/start."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "id"
+            ]
+        }
+    },
+    "agent.session-start": {
+        "cliKey": "agent.session-start",
+        "cliName": "agent session-start",
+        "method": "POST",
+        "path": "/v1/agent/session/start",
+        "description": "开启 agent kind 凭据的计费会话。返回 session_id，用于将多次调用归并到一次 billable 单位。需要 `Idempotency-Key` 头。",
+        "summary": "Start a billable agent session",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": false,
+        "idempotencyRequired": true,
+        "scopesAny": [
+            "agent:session.create"
+        ],
+        "sideEffect": "write",
+        "dryRunSupported": true,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "agent_id": {
+                    "type": "string",
+                    "maxLength": 200,
+                    "description": "Partner-defined agent identifier (max 200 chars).",
+                    "example": "agent-prod-1"
+                },
+                "conversation_id": {
+                    "type": "string",
+                    "maxLength": 200,
+                    "description": "Optional conversation thread id (max 200 chars)."
+                },
+                "scopes": {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    },
+                    "description": "Subset of partner scopes to derive into the agent token. Omit for \"all derivable from partner scopes\"."
+                },
+                "budget_usd": {
+                    "type": "number",
+                    "exclusiveMinimum": 0,
+                    "maximum": 1000,
+                    "default": 1.0,
+                    "description": "Hard USD budget cap; session terminates when exhausted (0 < x ≤ 1000).",
+                    "example": 1.0
+                },
+                "ttl_seconds": {
+                    "type": "integer",
+                    "minimum": 60,
+                    "maximum": 28800,
+                    "default": 3600,
+                    "description": "Session lifetime cap (60 ≤ x ≤ 28800, default 1h)."
+                },
+                "metadata": {
+                    "type": "object",
+                    "description": "Free-form JSON object for partner bookkeeping (e.g. user_intent, model name)."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "agent_id"
+            ]
+        }
+    },
+    "agent.session-usage": {
+        "cliKey": "agent.session-usage",
+        "cliName": "agent session-usage",
+        "method": "GET",
+        "path": "/v1/agent/session/{id}/usage",
+        "description": "返回 session 内累计 billable 调用次数、各 scope 配额消耗。",
+        "summary": "Get cumulative usage of an agent session",
+        "positional": [
+            "id"
+        ],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": false,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "agent:session.create",
+            "agent:session.read"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "description": "Session id returned by /v1/agent/session/start."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "id"
+            ]
+        }
+    },
+    "auth.whoami": {
+        "cliKey": "auth.whoami",
+        "cliName": "auth whoami",
+        "method": "GET",
+        "path": "/v1/auth/whoami",
+        "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",
+        "summary": "Token introspection (CLI/MCP capability discovery)",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": false,
+        "idempotencyRequired": false,
+        "scopesAny": [],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "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",
+        "method": "GET",
+        "path": "/v1/bars/daily",
+        "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.",
+        "summary": "Daily OHLC bars for one A-share security",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "bars:30d",
+            "bars:full"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "pattern": "^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$",
+                    "description": "Single canonical code.",
+                    "example": "SSE:600519"
+                },
+                "from": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "Inclusive start date (YYYY-MM-DD).",
+                    "example": "2026-01-01"
+                },
+                "to": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "Inclusive end date (YYYY-MM-DD).",
+                    "example": "2026-05-01"
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "code",
+                "from",
+                "to"
+            ]
+        }
+    },
+    "bars.daily-batch": {
+        "cliKey": "bars.daily-batch",
+        "cliName": "bars daily-batch",
+        "method": "GET",
+        "path": "/v1/bars/daily-batch",
+        "description": "Batch daily OHLC bars for multiple A-share securities. Up to 100 codes\nper call, up to 1-year date range. Single round-trip; ClickHouse `IN(...)`\nunder the hood.\n\nReturns partial success envelope: codes denied by `allowed_securities`\nappear in `errors[]`, others in `items[]` (with empty `bars[]` if no\ndata found). Order in `items[]` matches input order.\n\nRequires `bars:30d` or `bars:full` scope.\n",
+        "summary": "Batch daily OHLC bars for up to 100 A-share securities",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "bars:30d",
+            "bars:full"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "codes": {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "pattern": "^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$"
+                    },
+                    "minItems": 1,
+                    "maxItems": 100,
+                    "description": "1-100 canonical codes; CSV-encoded on the wire.",
+                    "example": [
+                        "SSE:600519",
+                        "SZSE:000001"
+                    ]
+                },
+                "from": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "Inclusive start date (YYYY-MM-DD)."
+                },
+                "to": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "Inclusive end date (YYYY-MM-DD). Range must be ≤ 365 days."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "codes",
+                "from",
+                "to"
+            ]
+        }
+    },
+    "bars.minute": {
+        "cliKey": "bars.minute",
+        "cliName": "bars minute",
+        "method": "GET",
+        "path": "/v1/bars/minute",
+        "description": "Minute-level OHLC bars for one A-share security on a single trade date. Requires `bars:30d` or `bars:full` scope.",
+        "summary": "Minute-level OHLC bars for one A-share security",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "bars:30d",
+            "bars:full"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "pattern": "^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$",
+                    "description": "Single canonical code.",
+                    "example": "SSE:600519"
+                },
+                "date": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "Single trade date (YYYY-MM-DD). Returns 240 minute bars for that session.",
+                    "example": "2026-05-09"
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "code",
+                "date"
+            ]
+        }
+    },
+    "bars.minute-batch": {
+        "cliKey": "bars.minute-batch",
+        "cliName": "bars minute-batch",
+        "method": "GET",
+        "path": "/v1/bars/minute-batch",
+        "description": "Batch minute OHLC bars for multiple A-share securities. Up to 20 codes\nper call, up to 7 calendar days (≈5 trading days) date range. Single\nClickHouse round-trip; app groups rows by canonical_code.\n\nPartial success envelope same as daily-batch: codes denied by\n`allowed_securities` go to `errors[]`; others to `items[]` with flat\n`bars[]` (each bar carries its own `trade_date` for client grouping).\n\nRequires `bars:30d` or `bars:full` scope.\n",
+        "summary": "Batch minute OHLC bars for up to 20 A-share securities",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "bars:30d",
+            "bars:full"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "codes": {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "pattern": "^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$"
+                    },
+                    "minItems": 1,
+                    "maxItems": 20,
+                    "description": "1-20 canonical codes; CSV-encoded on the wire.",
+                    "example": [
+                        "SSE:600519",
+                        "SZSE:000001"
+                    ]
+                },
+                "from": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "Inclusive start date (YYYY-MM-DD)."
+                },
+                "to": {
+                    "type": "string",
+                    "format": "date",
+                    "description": "Inclusive end date. Range must be ≤ 7 calendar days."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "codes",
+                "from",
+                "to"
+            ]
+        }
+    },
+    "digest.get": {
+        "cliKey": "digest.get",
+        "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",
+        "summary": "One-shot research digest for a single security (composite)",
+        "positional": [
+            "code"
+        ],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "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 security code, e.g. SSE:600519."
+                },
+                "views_since_days": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 90,
+                    "default": 7,
+                    "description": "Views lookback in days (1-90)."
+                },
+                "news_hours": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 168,
+                    "default": 24,
+                    "description": "News lookback in hours (1-168)."
+                },
+                "limit_per_bucket": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 50,
+                    "default": 10,
+                    "description": "Per-bucket item cap for views / news (1-50)."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "code"
+            ]
+        }
+    },
+    "market.status": {
+        "cliKey": "market.status",
+        "cliName": "market status",
+        "method": "GET",
+        "path": "/v1/market/status",
+        "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.",
+        "summary": "Current A-share market session state",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": false,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "market:read",
+            "quote:l1",
+            "quote:l2",
+            "quote:delayed"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": false
+        }
+    },
+    "news.feed": {
+        "cliKey": "news.feed",
+        "cliName": "news feed",
+        "method": "GET",
+        "path": "/v1/news",
+        "description": "与 `/v1/news/list` 行为一致，旧客户端兼容用。",
+        "summary": "List recent news (alias of /v1/news/list)",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "offset",
+        "stream": false,
+        "billable": false,
+        "idempotencyRequired": false,
+        "scopesAny": [],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": false
+        }
+    },
+    "news.get": {
+        "cliKey": "news.get",
+        "cliName": "news get",
+        "method": "GET",
+        "path": "/v1/news/{news_id}",
+        "description": "返回新闻完整内容：title、content snippet、source URL、tagged securities。",
+        "summary": "Fetch a single news item by id",
+        "positional": [
+            "news_id"
+        ],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": false,
+        "idempotencyRequired": false,
+        "scopesAny": [],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "news_id": {
+                    "type": "string",
+                    "description": "News item id (returned by news.list / search items[].id)."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "news_id"
+            ]
+        }
+    },
+    "news.list": {
+        "cliKey": "news.list",
+        "cliName": "news list",
+        "method": "GET",
+        "path": "/v1/news/list",
+        "description": "List news mentioning a specific A-share security, ordered by published_at desc. Requires `news:read` scope.",
+        "summary": "List news mentioning a specific security",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "news:read"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "security": {
+                    "type": "string",
+                    "pattern": "^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$",
+                    "description": "Canonical security code.",
+                    "example": "SSE:600519"
+                },
+                "since_hours": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 720,
+                    "default": 24,
+                    "description": "Lookback window in hours (max 720 = 30 days)."
+                },
+                "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 100,
+                    "default": 20,
+                    "description": "Max items per page."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "security"
+            ]
+        }
+    },
+    "news.search": {
+        "cliKey": "news.search",
+        "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.",
+        "summary": "Full-text search recent news",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "news:read"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 200,
+                    "description": "Free-text query (Chinese or English).",
+                    "example": "光伏龙头"
+                },
+                "since_hours": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 168,
+                    "default": 24,
+                    "description": "Lookback window in hours."
+                },
+                "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 100,
+                    "default": 20,
+                    "description": "Max items per page."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "query"
+            ]
+        }
+    },
+    "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",
+        "method": "GET",
+        "path": "/v1/payment/plans",
+        "description": "返回订阅计划清单（plan_id + 价格 + 时长 + 描述）。",
+        "summary": "List subscription plans",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": false,
+        "idempotencyRequired": false,
+        "scopesAny": [],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": false
+        }
+    },
+    "quote": {
+        "cliKey": "quote",
+        "cliName": "quote",
+        "method": "GET",
+        "path": "/v1/quote/realtime",
+        "description": "Real-time quote for one or more A-share securities. Returns last price, volume, change %, bid/ask. Up to 200 codes per call. Requires `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
+        "summary": "Real-time quote for one or more A-share securities",
+        "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": "array",
+                    "items": {
+                        "type": "string",
+                        "pattern": "^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$"
+                    },
+                    "minItems": 1,
+                    "maxItems": 200,
+                    "description": "1-200 canonical codes; CSV-encoded on the wire.",
+                    "example": [
+                        "SSE:600519",
+                        "SZSE:000001"
+                    ]
+                },
+                "include_l2": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Include L2 5-level order book (requires quote:l2 scope)."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "codes"
+            ]
+        }
+    },
+    "quote.scan": {
+        "cliKey": "quote.scan",
+        "cliName": "quote scan",
+        "method": "GET",
+        "path": "/v1/quote/scan",
+        "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",
+        "summary": "Full-market real-time quote scan (~5800 A-share securities)",
+        "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": {
+                "exchange": {
+                    "type": "string",
+                    "enum": [
+                        "SSE",
+                        "SZSE",
+                        "BSE",
+                        "sse",
+                        "szse",
+                        "bse"
+                    ],
+                    "description": "Filter by exchange: SSE / SZSE / BSE (case-insensitive). Omit for all."
+                }
+            },
+            "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
+        }
+    },
+    "semantic.find": {
+        "cliKey": "semantic.find",
+        "cliName": "semantic find",
+        "method": "GET",
+        "path": "/v1/securities/search",
+        "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.",
+        "summary": "Find A-share securities by name / code / pinyin",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": false,
+        "idempotencyRequired": false,
+        "scopesAny": [],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 20,
+                    "description": "Search query: Chinese name, A-share code, or pinyin initials.",
+                    "example": "贵州茅台"
+                },
+                "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 30,
+                    "default": 10,
+                    "description": "Max matches."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "query"
+            ]
+        }
+    },
+    "sentiment.breadth": {
+        "cliKey": "sentiment.breadth",
+        "cliName": "sentiment breadth",
+        "method": "GET",
+        "path": "/v1/sentiment/breadth",
+        "description": "Intraday breadth time series. Requires `sentiment:read` scope.",
+        "summary": "Intraday breadth time series",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "sentiment:read"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "scope": {
+                    "type": "string",
+                    "enum": [
+                        "all_a",
+                        "all_a_ex_st",
+                        "main_board",
+                        "star_market",
+                        "chinext",
+                        "bse"
+                    ],
+                    "default": "all_a_ex_st",
+                    "description": "Universe filter."
+                }
+            },
+            "additionalProperties": false
+        }
+    },
+    "sentiment.overview": {
+        "cliKey": "sentiment.overview",
+        "cliName": "sentiment overview",
+        "method": "GET",
+        "path": "/v1/sentiment/overview",
+        "description": "Aggregate sentiment: limit-up/down counts, breadth, divergence index, top movers. Requires `sentiment:read` scope.",
+        "summary": "Aggregate market sentiment indicators",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "sentiment:read"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "scope": {
+                    "type": "string",
+                    "enum": [
+                        "all_a",
+                        "all_a_ex_st",
+                        "main_board",
+                        "star_market",
+                        "chinext",
+                        "bse"
+                    ],
+                    "default": "all_a_ex_st",
+                    "description": "Universe filter.",
+                    "example": "main_board"
+                }
+            },
+            "additionalProperties": false
+        }
+    },
+    "sentiment.pct-distribution": {
+        "cliKey": "sentiment.pct-distribution",
+        "cliName": "sentiment pct-distribution",
+        "method": "GET",
+        "path": "/v1/sentiment/pct-distribution",
+        "description": "返回 A 股全市场涨跌幅分桶（≤-10% / -9% / ... / +10% / 涨停）的家数分布，用于市场宽度可视化。",
+        "summary": "Distribution of intraday percent change across the universe",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "sentiment:read"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": false
+        }
+    },
+    "sentiment.turnover": {
+        "cliKey": "sentiment.turnover",
+        "cliName": "sentiment turnover",
+        "method": "GET",
+        "path": "/v1/sentiment/turnover",
+        "description": "Intraday turnover time series. Requires `sentiment:read` scope.",
+        "summary": "Intraday turnover time series",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "sentiment:read"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "scope": {
+                    "type": "string",
+                    "enum": [
+                        "all_a",
+                        "all_a_ex_st",
+                        "main_board",
+                        "star_market",
+                        "chinext",
+                        "bse"
+                    ],
+                    "default": "all_a_ex_st",
+                    "description": "Universe filter."
+                }
+            },
+            "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",
+        "method": "GET",
+        "path": "/v1/squawk/{item_id}/audio",
+        "description": "返回 squawk 项的 TTS 音频（MP3）。直接 stream，可作为 `<audio>` src 用。",
+        "summary": "Stream squawk TTS audio",
+        "positional": [
+            "item_id"
+        ],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": false,
+        "idempotencyRequired": false,
+        "scopesAny": [],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "item_id": {
+                    "type": "string",
+                    "description": "Squawk item id (returned by squawk.recent items[].id)."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "item_id"
+            ]
+        }
+    },
+    "squawk.waveform": {
+        "cliKey": "squawk.waveform",
+        "cliName": "squawk waveform",
+        "method": "GET",
+        "path": "/v1/squawk/{item_id}/waveform",
+        "description": "返回 squawk 音频的预计算波形 peak 数据，用于客户端波形可视化。",
+        "summary": "Waveform peaks for squawk audio",
+        "positional": [
+            "item_id"
+        ],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": false,
+        "idempotencyRequired": false,
+        "scopesAny": [],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "item_id": {
+                    "type": "string",
+                    "description": "Squawk item id (returned by squawk.recent items[].id)."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "item_id"
+            ]
+        }
+    },
+    "stocks.hot": {
+        "cliKey": "stocks.hot",
+        "cliName": "stocks hot",
+        "method": "GET",
+        "path": "/v1/stocks/hot",
+        "description": "今日最热股票榜（来源 East-Money），按搜索 / 关注 / 评论综合分排序。",
+        "summary": "Today's hot-stock leaderboard",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": false,
+        "idempotencyRequired": false,
+        "scopesAny": [],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": false
+        }
+    },
+    "stocks.social-hot": {
+        "cliKey": "stocks.social-hot",
+        "cliName": "stocks social-hot",
+        "method": "GET",
+        "path": "/v1/stocks/social-hot",
+        "description": "跨平台（微博 / 雪球 / Twitter）社交媒体提及聚合榜，按提及量 / 情感打分。",
+        "summary": "Cross-platform social-hot stocks",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": false,
+        "idempotencyRequired": false,
+        "scopesAny": [],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": false
+        }
+    },
+    "views.feed": {
+        "cliKey": "views.feed",
+        "cliName": "views feed",
+        "method": "GET",
+        "path": "/v1/views",
+        "description": "分析师观点 / 卖方研报 / 长文本观点流。可按机构 / 分析师 / 证券 / hours 过滤。需要 `views:read` scope。",
+        "summary": "List analyst views",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "offset",
+        "stream": false,
+        "billable": false,
+        "idempotencyRequired": false,
+        "scopesAny": [],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": false
+        }
+    },
+    "views.get": {
+        "cliKey": "views.get",
+        "cliName": "views get",
+        "method": "GET",
+        "path": "/v1/views/{view_id}",
+        "description": "返回单条 view 完整内容、附件图片、tagged securities、AI 摘要。",
+        "summary": "Fetch a single analyst view",
+        "positional": [
+            "view_id"
+        ],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": false,
+        "idempotencyRequired": false,
+        "scopesAny": [],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "view_id": {
+                    "type": "string",
+                    "description": "Analyst-view id (returned by views.recent / list items[].id)."
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "view_id"
+            ]
+        }
+    },
+    "views.recent": {
+        "cliKey": "views.recent",
+        "cliName": "views recent",
+        "method": "GET",
+        "path": "/v1/views/recent",
+        "description": "List recent broker / analyst views (research notes, price targets, ratings). Filter by analyst, institution, or a specific security. Requires `views:read` scope.",
+        "summary": "Recent broker / analyst views",
+        "positional": [],
+        "outputDefault": "json",
+        "pagination": "none",
+        "stream": false,
+        "billable": true,
+        "idempotencyRequired": false,
+        "scopesAny": [
+            "views:read"
+        ],
+        "sideEffect": "read",
+        "dryRunSupported": false,
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "analyst": {
+                    "type": "string",
+                    "description": "Analyst name (Chinese), exact or fuzzy."
+                },
+                "institution": {
+                    "type": "string",
+                    "description": "Broker / institution Chinese name."
+                },
+                "security": {
+                    "type": "string",
+                    "pattern": "^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$",
+                    "description": "Filter by security code."
+                },
+                "since_days": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 90,
+                    "default": 7,
+                    "description": "Lookback window in days. (Translated to hours upstream.)"
+                },
+                "limit": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 100,
+                    "default": 30,
+                    "description": "Max items per page."
+                }
+            },
+            "additionalProperties": false
+        }
+    }
+};
+export function getOperation(key) {
+    return OPERATIONS[key];
+}
+export function listOperations() {
+    return Object.values(OPERATIONS);
+}