gangtise-openapi-cli 0.22.1 → 0.24.0

package/README.md

@@ -4,6 +4,38 @@
 
 ## Changelog
 
+### v0.24.0 — 2026-07-07
+
+**新增**
+- `raw list` — 列出所有已注册的 endpoint key（含 method / path / description），配合 `raw call <key>` 使用，不必再翻文档记 key；支持 `--format`（默认 table）/ `--output`
+- AI 同步生成端点内置 120s 超时下限（`one-pager` / `investment-logic` / `peer-comparison` / `theme-tracking` / `research-outline` / `management-discuss-announcement` / `management-discuss-earnings-call`）——生成耗时长不再撞 30s 默认超时触发重试，**不必再手动前缀 `GANGTISE_TIMEOUT_MS`**；显式设更大值仍生效（取 max）
+- 429 响应尊重 `Retry-After`（秒或 HTTP-date；覆盖 JSON、非 JSON、下载三类错误路径），优先于默认指数退避，封顶 60s 防挂死
+- 超大结果（≥5 万行且走非流式渲染：table/json/markdown，或 jsonl/csv 未带 `--output`）在 stderr 提示改用 `--format jsonl --output <path>` 流式落盘
+
+**性能**
+- JSON 请求启用 gzip（`accept-encoding: gzip` + 本地解压）——实测 `reference constant-list` 2110B→586B（3.6x），K 线类高重复大 JSON 收益更高；下载二进制路径不变
+- 全市场按日分片（`quote fund-flow` / `day-kline` / `day-kline-us`，均 1 天/片）自动跳过周六日（A/港/美股周末闭市必空），省 ~28% 请求与每日调用配额；多日分片（`day-kline-hk` 2 天、`index-day-kline` 30 天）不受影响
+
+**修复**
+- 表格（table/markdown）显示宽度纳入 emoji 码位区（0x1F000–0x1FAFF），含 emoji 的微信群名/消息不再错位
+- `fundamental earning-forecast` 默认 `--end-date`（"today"）改用运行机器本地日期；此前用 UTC 日期，CST 凌晨 0–8 点会算成"昨天"
+
+**文档 / 工程**（不影响已发布 CLI 行为）
+- `insight announcement`（A 股公告）时间过滤时区说明：`--start-time`/`--end-time` 按运行机器时区换算，跨机器精确边界改传 13 位毫秒时间戳
+- CI 测试矩阵增加 Node 24（此前仅 20；发布用 24）
+
+### v0.23.0 — 2026-07-05
+
+**行为变更（注意）**
+- ⚠️ 默认 API 域名迁移：`https://open.gangtise.com` → `https://openapi.gangtise.com`。旧域名仍可用，CLI 只是切换了默认值（新旧域名多接口实测等价）；如需固定旧域名设 `GANGTISE_BASE_URL=https://open.gangtise.com`
+- `vault wechat-chatroom-list`：服务端接口改版为返回 `{ total, list }`（此前无 `total`、列名 `chatRoomList`）。CLI 相应改为按 `total` 并发翻页（不再串行翻页）；省略 `--size` 仍拉全量、传 `--size N` 取前 N 条，`Total:` 提示恢复
+- 无翻页的行情端点（`quote fund-flow` / `minute-kline` / 显式多标的的日 K：`day-kline`·`-hk`·`-us`·`index-day-kline`）返回行数撞上单次 `--limit` 时标 `partial`（退出码 3）+ stderr 警告，避免被静默截断；`--limit` 现本地校验 ≤ 10000（撞服务端上限也不漏标）。K 线 `--security all` 仍走日期分片自动补全，不受影响
+
+**新增**
+- `quote fund-flow` — A股个股日资金流向（沪深京），含小/中/大/特大单流入流出金额及占比、主力净流入等字段；`--security`（或 `aShares` 全市场）、`--start-date` / `--end-date`、`--limit`（默认 6000，上限 10000）、`--field` 指定返回字段；无积分消耗（单只证券无翻页，撞 `--limit` 时的截断处理见上「行为变更」；**`aShares` 全市场须显式传 `--start-date`/`--end-date`，CLI 按日自动分片并发合并——缺日期会本地报错**）
+- `reference institution-search` — 机构 ID 搜索，输入机构名/简称返回 `institutionId` 及适用接口参数（`usageScopes`）；`--keyword`（必填）、`--category`（`domesticBroker`/`foreignInstitution`/`leadInstitution`/`opinionInstitution`/`foreignOpinionInstitution`，可重复）、`--top`（默认 10，上限 10）；免费。覆盖既有 `--broker`/`--institution` 全部机构类（research/foreign-report/opinion/foreign-opinion/summary/roadshow/site-visit/strategy/my-conference）
+- `vault my-conference-list` 新增 `--source` — 按录制来源筛选（`1`=企微会议助理 `2`=会议服务微信群，可重复；不传返回全部）
+
 ### v0.22.1 — 2026-07-03
 
 **修复**
@@ -81,38 +113,6 @@
 **修复（indicator 适配 EDE 后台新结构）**
 - `indicator cross-section` / `time-series` 适配后台改版的返回结构（字段名加 `List` 后缀 `securityCodeList/indicatorCodeList/…`、截面 `values` 改二维 `[指标][证券]`）：此前后台改结构后 CLI 拍平失配、退化成原始矩阵，现恢复 `{date, security, name, 指标:值}` 宽表。配合后台同步变化——无数据从 `999999` 报错改为返回 `null`（截面不再 500、不丢行），缺必填参数从笼统 `410106` 改为直接指明缺哪个参数
 
-### v0.19.0 — 2026-06-24
-
-**新增接口（Indicator · 证券级数据指标 EDE）**
-- `indicator search` — 按名称搜索证券级数据指标，返回 `indicatorCode` 及可传参数 `parameterList`（含 `required` 必填标记与枚举）；取数前必先 search 拿 code，绝不猜编码
-- `indicator cross-section` — 指标截面数据（多指标 × 多证券，单日快照）：`--indicator` / `--security`（均可重复）/ `--date` / `--currency` / `--scale` / `--indicator-param`
-- `indicator time-series` — 指标时间序列（多指标 × 单证券 或 单指标 × 多证券，按区间）：另有 `--start-date` / `--end-date` / `--calendar-type`（`ND`/`TD`/`WD`）
-- 复权等指标专属参数用 `--indicator-param "code:key=value"`，参数 key 与取值以 search 的 `parameterList` 为准（行情复权键为 `adjustmentType`：`1` 不复权 / `2` 前复权 / `3` 后复权）
-- 很多指标有必填参数，默认调用会报 `410106`（缺必填参数）：N 期统计补 `periodNum`、区间/周期类补 `startDate`、年度/分红类补 `fiscalYear`；`999999` 多为「该证券公司类型/报告期无数据」而非系统故障。详见 `gangtise-openapi/references/commands/indicator.md`
-
-**修复**
-- `vault stock-pool-stocks --pool-id <id>` 过滤失效：此前因选项默认值 `["all"]` 泄漏，传具体 pool id 仍返回全部股票池证券；现已修复——传 id 精确过滤，省略则默认全量
-- `auth` 缺凭证报错补充跨 shell（bash/zsh/fish）的 `export` 提示
-
-**文档**
-- README / SKILL 补充 indicator 命令组与取数最佳实践；`official-account` 命令文档补全
-
-### v0.18.0 — 2026-06-17
-
-**新增接口（Insight · 产业公众号资讯）**
-- `insight official-account list` — 查询公众号资讯列表：支持 `--keyword`（需用数据中的具体词，非整句白话）/ `--account-id`（公众号 ID）/ `--security` / `--category`（文章类型枚举：`news`/`law`/`report`/`view`/`data`/`event`/`meeting`/`notice`/`recruit`/`investEdu`/`brand`/`notes`/`other`）/ `--industry`（`citicIndustry`/`swIndustry` 行业 ID）/ `--search-type`（`1` 标题 / `2` 全文）/ `--rank-type`（`1` 综合 / `2` 时间倒序）；返回含模型生成摘要 `summary` 及关联行业/题材/证券列表
-- `insight official-account download --article-id <id>` — 下载公众号文章：`--file-type 1` txt（默认）/ `2` HTML
-
-### v0.17.0 — 2026-06-15
-
-**接口变更（Breaking）**
-- 日程类命令（`roadshow` / `site-visit` / `strategy` / `forum` list）改为各自只暴露 API spec 支持的筛选选项，移除原先一刀切多出的无效选项：`strategy` 仅保留 `--institution` / `--location`；`forum` 仅保留 `--research-area` / `--location`；`site-visit` 移除 `--participant-role` / `--broker-type`；`roadshow` 移除 `--object`。传不支持的选项现由 commander 直接报 `unknown option`（此前会静默发送、服务端返回空结果）
-- `insight announcement list` 移除无效的 `--announcement-type`（服务端忽略、恒返全量）；A 股公告分类筛选用 `--category`（`aShareAnnouncementCategory` 常量 ID）
-
-**说明 / 修正**
-- `--industry` 用 `citicIndustry` 码（`1008001xx`，全命令通用）；`--research-area` 用 `gangtiseIndustry` 码（行业 `1008001xx` + 宏观/策略/固收/金工/海外等方向 `122000xxx`）。详见 `gangtise-openapi/references/commands/reference-and-lookup.md`
-- 日程类 `--location`（domesticCity）服务端过滤已生效（v0.16.0 时曾未生效）
-
 > 更早版本及完整更新历史见 [CHANGELOG.md](CHANGELOG.md)。
 
 ## 首次安装
@@ -149,7 +149,7 @@ npm run dev -- --help
 ```bash
 export GANGTISE_ACCESS_KEY="your-ak"
 export GANGTISE_SECRET_KEY="your-sk"
-export GANGTISE_BASE_URL="https://open.gangtise.com"
+export GANGTISE_BASE_URL="https://openapi.gangtise.com"
 export GANGTISE_TOKEN="Bearer xxx"
 
 # 性能/调试可选项
@@ -227,7 +227,7 @@ cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
 | 模块 | 子命令 | 说明 |
 |------|--------|------|
 | **Auth** | `login` / `status` | 认证登录、状态查询 |
-| **Lookup** | `broker-org list` / `meeting-org list` | 本地枚举表（API 未覆盖的部分；行业/区域/公告分类/题材/申万行业代码改用 Reference 接口） |
+| **Lookup** | `broker-org list` / `meeting-org list` | 券商/会议机构本地全量枚举表（按名称找 ID 优先 `reference institution-search`；行业/区域/公告分类/题材/申万码已改用 Reference 接口） |
 | **Insight** | `opinion list` | 内资机构观点 |
 | | `summary list` / `download` | 纪要（含下载，支持 `--file-type` 选原始/HTML） |
 | | `roadshow list` | 路演 |
@@ -244,6 +244,7 @@ cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
 | | `official-account list` / `download` | 产业公众号资讯（含 txt/HTML 下载） |
 | **Reference** | `securities-search` | GTS Code 搜索（按名称/代码/拼音匹配） |
 | | `chiefs-search` | 首席分析师 ID 搜索（按姓名/机构/团队匹配） |
+| | `institution-search` | 机构 ID 搜索（内资券商/外资/牵头/观点机构，按名称匹配） |
 | | `constant-category` | 常量分类列表（含各分类适用的接口与参数） |
 | | `constant-list` | 按分类导出常量值全量列表（行业/城市/公告分类/区域等） |
 | | `concept-search` | 题材 ID 搜索（名称/拼音/分组名匹配） |
@@ -253,6 +254,7 @@ cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
 | | `index-day-kline` | 沪深京指数日K线 |
 | | `minute-kline` | A股分钟K线 |
 | | `realtime` | 个股实时行情快照（A股/港股/美股） |
+| | `fund-flow` | A股个股日资金流向（沪深京；小/中/大/特大单 + 主力净流入） |
 | **Fundamental** | `income-statement` / `balance-sheet` / `cash-flow` | A股三大财务报表（累计） |
 | | `income-statement-quarterly` / `cash-flow-quarterly` | A股利润表/现金流量表（单季度） |
 | | `income-statement-hk` / `balance-sheet-hk` / `cash-flow-hk` | 港股三大财务报表（中国会计准则） |
@@ -301,7 +303,7 @@ cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
 - `gangtise indicator ...`
 - `gangtise alternative ...`
 - `gangtise reference ...`
-- `gangtise raw call ...`
+- `gangtise raw call ...` / `gangtise raw list`
 
 ## 推荐工作流
 
@@ -362,7 +364,7 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 - `vault record-list`
 - `vault my-conference-list`
 - `vault wechat-message-list`
-- `vault wechat-chatroom-list`（特例：接口无 `total`，CLI 串行翻页）
+- `vault wechat-chatroom-list`
 - `ai hot-topic`
 
 规则：
@@ -373,7 +375,6 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 - 安全上限：自动翻页最多 1000 页，防止异常循环
 - 部分页失败、或服务端实际返回行数与 `total` 矛盾（提前短页）时，不丢弃已取到的数据：结果带 `partial: true`（页失败时另有 `failedPages`；K线分片为 `failedShards`；`--format json` 可见），stderr 输出警告，**进程退出码为 3**（完整成功为 0）
 - 分页结果中 `total` 字段会被保留（json 格式输出 `{total, list}`）；其他格式下 stderr 输出 `Total: N, showing: M`（json 格式不输出该行）
-- `vault wechat-chatroom-list` 是特例：接口不返回 `total`，CLI 改为串行翻页——省略 `--size` 拉全量、传 `--size N` 取前 N 条，单页 50，无 `Total:` 提示
 
 ## 智能文件命名
 
@@ -462,6 +463,8 @@ gangtise reference securities-search --keyword "银行" --category stock --categ
 # 首席分析师 ID 搜索（按姓名/机构/团队；拿 chiefId 供 insight opinion list --chief 使用）
 gangtise reference chiefs-search --keyword 东吴证券 --top 3 --format json
 gangtise reference chiefs-search --keyword 芦哲 --format json
+# 机构 ID 搜索（--category: domesticBroker/foreignInstitution/leadInstitution/opinionInstitution）
+gangtise reference institution-search --keyword 招商证券 --category domesticBroker --top 3 --format json
 
 # 常量查询：先看分类，再按分类导出全量常量值
 gangtise reference constant-category --format json
@@ -502,6 +505,8 @@ gangtise quote minute-kline --security 600519.SH --start-time "2026-04-15 09:30:
 gangtise quote realtime --security 600519.SH --security 00700.HK --security AAPL.O --field securityCode --field tradeTime --field latestPrice --field pctChange --field volume --format json
 # 实时行情：全市场批量（建议配合 --field 精简字段）
 gangtise quote realtime --security aShares --field securityCode --field latestPrice --field pctChange --field volume --format json
+# A股个股日资金流向（沪深京；--security aShares 全市场；--limit 上限 10000，超限缩短日期区间分批）
+gangtise quote fund-flow --security 600519.SH --security 000001.SZ --start-date 2026-06-01 --end-date 2026-06-05 --field mainNetInflow --field largeInflow --field xlargeInflow --format json
 ```
 
 > **历史 vs 实时**：`day-kline*` 仅返回历史数据（当日数据入库时间：A 股 ~15:30 / 港股 ~16:30 / 美股 ~07:00 北京时间）。盘中需要最新成交价、振幅等实时字段必须走 `quote realtime`。
@@ -598,8 +603,9 @@ gangtise vault record-list --keyword 晨会 --category upload --category mobile
 # 录音速记下载（--content-type: original/asr/summary）
 gangtise vault record-download --record-id 49412 --content-type summary
 
-# 我的会议列表
+# 我的会议列表（--source 录制来源：1=企微会议助理 2=会议服务微信群，可重复；不传返回全部）
 gangtise vault my-conference-list --keyword AI --category earningsCall --institution C100000027
+gangtise vault my-conference-list --source 2 --category earningsCall --size 20
 # 我的会议下载（--content-type: asr/summary）
 gangtise vault my-conference-download --conference-id 43319 --content-type asr
 
@@ -678,6 +684,10 @@ gangtise alternative concept-securities --concept-id 121000130 --format json
 ### Raw
 
 ```bash
+# 先列出所有 endpoint key（配合 raw call，不必翻文档记 key）
+gangtise raw list
+gangtise raw list --format json   # key / method / path / description
+
 gangtise raw call insight.opinion.list --body '{"from":0,"size":120}'
 ```
 

package/dist/src/cli.js

@@ -2,13 +2,13 @@
 import { Command, Option } from "commander";
 import { checkAsyncContent, pollAsyncContent, POLL_MAX_ATTEMPTS } from "./core/asyncContent.js";
 import { readTokenCache, redactTokenCache } from "./core/auth.js";
-import { collectKeyValue, collectList, collectNumberList, maybeArray, parseFrom, parseNumberOption, parseOptionalNumberOption, parseSize, parseTimestamp13 } from "./core/args.js";
+import { collectKeyValue, collectList, collectNumberList, localDateString, maybeArray, parseFrom, parseNumberOption, parseOptionalNumberOption, parseSize, parseTimestamp13 } from "./core/args.js";
 import { buildIndicatorCrossSectionBody, buildIndicatorTimeSeriesBody, buildQuoteKlineBody, buildStockPoolStocksBody, buildWechatChatroomListBody, buildWechatMessageListBody } from "./core/commandBodies.js";
 import { flattenCrossSection, flattenTimeSeries, unwrapIndicatorData } from "./core/indicatorMatrix.js";
-import { callKlineWithSharding } from "./core/quoteSharding.js";
+import { callKlineWithSharding, isAllMarket, isFullMarket } from "./core/quoteSharding.js";
 import { loadConfig } from "./core/config.js";
 import { resolveTitle, saveDownloadResult, uniquePath } from "./core/download.js";
-import { ENDPOINTS } from "./core/endpoints.js";
+import { ENDPOINTS, listEndpoints } from "./core/endpoints.js";
 import { ApiError, ConfigError, ValidationError } from "./core/errors.js";
 import { normalizeRows } from "./core/normalize.js";
 import { parseOutputFormat } from "./core/output.js";
@@ -35,6 +35,33 @@ async function emit(options, produce, cache) {
 async function withClient(fn) {
     await fn(await createClient());
 }
+/**
+ * Server-side default row cap shared by the limit-capped, non-paginated quote endpoints
+ * (fund-flow, minute-kline, day/index kline — all default to 6000 per the API docs). We
+ * send it EXPLICITLY when `--limit` is omitted (rather than letting the server apply its
+ * own default) so the request limit and the truncation `cap` below are always the same
+ * number — never a guess about the server's default that can drift out of sync.
+ */
+const DEFAULT_QUOTE_LIMIT = 6000;
+/**
+ * Limit-capped, non-paginated endpoints (fund-flow, kline) report `total` as the
+ * RETURNED row count, not the true total, so a full page (rows == the limit we sent) is
+ * the only truncation signal. Flag the result partial (printData → exit 3) + warn so a
+ * capped export isn't mistaken for the full set. `cap` MUST be the exact limit the caller
+ * sent on the request; `--limit` is validated to <= 10000 so `cap` can't exceed the
+ * server ceiling and hide a truncation.
+ */
+function flagIfLimitTruncated(data, cap, label) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const rec = data;
+    if (rec.partial === true)
+        return;
+    if (Array.isArray(rec.list) && rec.list.length >= cap) {
+        rec.partial = true;
+        process.stderr.write(`[gangtise] warning: ${label} returned ${rec.list.length} rows = the ${cap}-row limit; results are likely truncated (this endpoint has no pagination). Narrow --start-date/--end-date or raise --limit (max 10000), fetching in date batches.\n`);
+    }
+}
 /**
  * Run a download. If `output` is set we already know the destination, so the
  * client streams the body straight to disk (no in-memory Uint8Array copy);
@@ -307,13 +334,63 @@ const addKlineCommand = (name, endpointKey, securityHelp, shardDays) => quote.co
     .option("--field <field>", "Field", collectList, [])
     .option("--format <format>", "Output format", "table")
     .option("--output <path>")
-    .action((options) => emit(options, (client) => callKlineWithSharding(client, endpointKey, buildQuoteKlineBody(options), { shardDays })));
+    .action((options) => withClient(async (client) => {
+    const format = parseOutputFormat(options.format);
+    const body = buildQuoteKlineBody(options);
+    if (isAllMarket(body)) {
+        // `--security all` is date-sharded: callKlineWithSharding lifts the limit to the
+        // API max and owns completeness (partial / failedShards), so leave `limit` unset
+        // and skip the single-request truncation guard.
+        const data = await callKlineWithSharding(client, endpointKey, body, { shardDays });
+        await printData(data, format, options.output);
+        return;
+    }
+    // Explicit securities go out as one request: pin the limit to the known default so
+    // the sent limit and the truncation cap are the same number by construction.
+    const limit = body.limit ?? DEFAULT_QUOTE_LIMIT;
+    const data = await callKlineWithSharding(client, endpointKey, { ...body, limit }, { shardDays });
+    flagIfLimitTruncated(data, limit, name);
+    await printData(data, format, options.output);
+}));
 addKlineCommand("day-kline", "quote.day-kline", "Security code (A-share: .SH/.SZ/.BJ, or 'all' for full market)", 1);
 addKlineCommand("day-kline-hk", "quote.day-kline-hk", "Security code (HK stock: .HK, or 'all' for full market)", 2);
 addKlineCommand("day-kline-us", "quote.day-kline-us", "Security code (US stock: e.g. AAPL.O, or 'all' for full market)", 1);
 addKlineCommand("index-day-kline", "quote.index-day-kline", "Index code (.SH/.SZ/.BJ, or 'all' for full market)", 30);
-quote.command("minute-kline").option("--security <code>", "Security code (A-share only: .SH/.SZ/.BJ)").option("--start-time <datetime>", "Start time (yyyy-MM-dd HH:mm:ss)").option("--end-time <datetime>", "End time (yyyy-MM-dd HH:mm:ss)").option("--limit <number>", "Max rows per request (default: 5000, max: 10000)").option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("quote.minute-kline", { securityCode: options.security, startTime: options.startTime, endTime: options.endTime, limit: parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1 }), fieldList: maybeArray(options.field) })));
+quote.command("minute-kline").option("--security <code>", "Security code (A-share only: .SH/.SZ/.BJ)").option("--start-time <datetime>", "Start time (yyyy-MM-dd HH:mm:ss)").option("--end-time <datetime>", "End time (yyyy-MM-dd HH:mm:ss)").option("--limit <number>", "Max rows per request (default: 6000, max: 10000)").option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
+    const format = parseOutputFormat(options.format);
+    const limit = parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1, max: 10000 }) ?? DEFAULT_QUOTE_LIMIT;
+    const data = await client.call("quote.minute-kline", { securityCode: options.security, startTime: options.startTime, endTime: options.endTime, limit, fieldList: maybeArray(options.field) });
+    flagIfLimitTruncated(data, limit, "minute-kline");
+    await printData(data, format, options.output);
+}));
 quote.command("realtime").description("Realtime quote snapshot (A-share / HK / US)").option("--security <code>", "Security code (e.g. 600519.SH / 00700.HK / AAPL.O), or market keyword: aShares / hkStocks / usStocks", collectList, []).option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("quote.realtime", { securityList: maybeArray(options.security), fieldList: maybeArray(options.field) })));
+quote.command("fund-flow").description("A-share daily fund flow (SH/SZ/BJ)").option("--security <code>", "Security code (e.g. 600519.SH / 872931.BJ), or 'aShares' for full A-share market — auto-sharded by day (repeat)", collectList, []).option("--start-date <date>", "Start date yyyy-MM-dd (default: endDate minus 1 year)").option("--end-date <date>", "End date yyyy-MM-dd (default: latest trading day)").option("--limit <number>", "Max rows per request (default: 6000, max: 10000; single-security cap — aShares auto-shards by day)").option("--field <field>", "Field, e.g. mainNetInflow/largeInflow/xlargeOutflow (repeat); omit for all", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
+    const format = parseOutputFormat(options.format);
+    const body = {
+        securityList: maybeArray(options.security),
+        startDate: options.startDate,
+        endDate: options.endDate,
+        limit: parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1, max: 10000 }),
+        fieldList: maybeArray(options.field),
+    };
+    if (isFullMarket(body, "aShares")) {
+        // Full-market fund-flow: the server errors (430012/430013) instead of truncating when
+        // a single request exceeds the row cap, so date-shard by day (~5.4k A-share rows/day,
+        // under the lifted API cap) and merge — same mechanism as `--security all` kline.
+        // Sharding needs an explicit range; without both dates it would fall back to one
+        // doomed full-market request, so require the range up front with a clear message.
+        if (!body.startDate || !body.endDate) {
+            throw new ValidationError("quote fund-flow --security aShares requires both --start-date and --end-date (the full market is fetched via per-day shards)");
+        }
+        const data = await callKlineWithSharding(client, "quote.fund-flow", body, { shardDays: 1, fullMarketValue: "aShares" });
+        await printData(data, format, options.output);
+        return;
+    }
+    const limit = body.limit ?? DEFAULT_QUOTE_LIMIT;
+    const data = await client.call("quote.fund-flow", { ...body, limit });
+    flagIfLimitTruncated(data, limit, "fund-flow");
+    await printData(data, format, options.output);
+}));
 program.addCommand(quote);
 const fundamental = new Command("fundamental").description("Fundamental APIs");
 const addFinancialReport = (name, endpointKey, periodHelp = "Period") => fundamental.command(name).requiredOption("--security-code <code>").option("--start-date <date>").option("--end-date <date>").option("--fiscal-year <year>", "Fiscal year", collectList, []).option("--period <period>", periodHelp, collectList, []).option("--report-type <type>", "Report type", collectList, []).option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call(endpointKey, { securityCode: options.securityCode, startDate: options.startDate, endDate: options.endDate, fiscalYear: maybeArray(options.fiscalYear), period: options.period.length ? options.period : undefined, reportType: options.reportType.length ? options.reportType : undefined, fieldList: maybeArray(options.field) })));
@@ -351,7 +428,7 @@ fundamental.command("valuation-analysis").requiredOption("--security-code <code>
 }));
 fundamental.command("top-holders").requiredOption("--security-code <code>").addOption(new Option("--holder-type <type>", "Holder type: top10/top10Float").choices(["top10", "top10Float"]).makeOptionMandatory()).option("--start-date <date>").option("--end-date <date>").option("--fiscal-year <year>", "Fiscal year", collectList, []).option("--period <period>", "Period: q1/interim/q3/annual/latest", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("fundamental.top-holders", { securityCode: options.securityCode, holderType: options.holderType, startDate: options.startDate, endDate: options.endDate, fiscalYear: maybeArray(options.fiscalYear), period: options.period.length ? options.period : undefined })));
 fundamental.command("earning-forecast").requiredOption("--security-code <code>").option("--start-date <date>", "Start date (default: 1 year before end-date)").option("--end-date <date>", "End date (default: today)").option("--consensus <name>", "Consensus indicator: netIncome/netIncomeYoy/eps/pe/bps/pb/peg/roe/ps", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => {
-    const endDate = options.endDate ?? new Date().toISOString().slice(0, 10);
+    const endDate = options.endDate ?? localDateString(new Date());
     // Anchor the default window to endDate (as the help text promises), not to today —
     // a historical --end-date without --start-date should mean "the year before it".
     const startDate = options.startDate ?? new Date(new Date(`${endDate}T00:00:00Z`).getTime() - 365 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
@@ -479,13 +556,18 @@ reference.command("chiefs-search").requiredOption("--keyword <text>", "Search ke
     keyword: options.keyword,
     top: parseNumberOption(options.top, "--top", { integer: true, min: 1 }),
 })));
+reference.command("institution-search").requiredOption("--keyword <text>", "Search keyword (institution name / abbreviation)").option("--category <name>", "Category: domesticBroker/foreignInstitution/leadInstitution/opinionInstitution/foreignOpinionInstitution (repeat); omit for all", collectList, []).option("--top <number>", "Max results (default: 10, max: 10)", "10").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("reference.institution-search", {
+    keyword: options.keyword,
+    categoryList: maybeArray(options.category),
+    top: parseNumberOption(options.top, "--top", { integer: true, min: 1 }),
+})));
 program.addCommand(reference);
 const vault = new Command("vault").description("Vault APIs");
 vault.command("drive-list").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").option("--start-time <datetime>").option("--end-time <datetime>").option("--keyword <text>").option("--file-type <number>", "File type", collectNumberList, []).option("--space-type <number>", "Space type", collectNumberList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("vault.drive.list", { from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword, fileTypeList: options.fileType.length ? options.fileType : undefined, spaceTypeList: options.spaceType.length ? options.spaceType : undefined }), { endpointKey: "vault.drive.list", idField: "fileId" }));
 addDownloadCommand(vault, { endpointKey: "vault.drive.download", name: "drive-download", idOption: "--file-id", idField: "fileId", fallbackPrefix: "file", titleListEndpoint: "vault.drive.list" });
 vault.command("record-list").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").option("--start-time <datetime>").option("--end-time <datetime>").option("--keyword <text>").option("--category <name>", "Recording type: upload/link/mobile/gtNote/pc/share", collectList, []).option("--space-type <number>", "Space type: 1=my records / 2=tenant records", collectNumberList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("vault.record.list", { from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword, categoryList: maybeArray(options.category), spaceTypeList: options.spaceType.length ? options.spaceType : undefined }), { endpointKey: "vault.record.list", idField: "recordId" }));
 addDownloadCommand(vault, { endpointKey: "vault.record.download", name: "record-download", idOption: "--record-id", idField: "recordId", fallbackPrefix: "record", contentTypeDescription: "Content type: original/asr/summary", titleListEndpoint: "vault.record.list" });
-vault.command("my-conference-list").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").option("--start-time <datetime>").option("--end-time <datetime>").option("--keyword <text>").option("--research-area <id>", "Research area ID", collectList, []).option("--security <code>", "Security code", collectList, []).option("--institution <id>", "Institution ID", collectList, []).option("--category <name>", "Conference category: earningsCall/strategyMeeting/fundRoadshow/shareholdersMeeting/maMeeting/specialMeeting/companyAnalysis/industryAnalysis/other", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("vault.my-conference.list", { from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword, researchAreaList: maybeArray(options.researchArea), securityList: maybeArray(options.security), institutionList: maybeArray(options.institution), categoryList: maybeArray(options.category) }), { endpointKey: "vault.my-conference.list", idField: "conferenceId" }));
+vault.command("my-conference-list").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").option("--start-time <datetime>").option("--end-time <datetime>").option("--keyword <text>").option("--research-area <id>", "Research area ID", collectList, []).option("--security <code>", "Security code", collectList, []).option("--institution <id>", "Institution ID", collectList, []).option("--category <name>", "Conference category: earningsCall/strategyMeeting/fundRoadshow/shareholdersMeeting/maMeeting/specialMeeting/companyAnalysis/industryAnalysis/other", collectList, []).option("--source <number>", "Recording source: 1=企微会议助理 2=会议服务微信群 (repeat)", collectNumberList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("vault.my-conference.list", { from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword, researchAreaList: maybeArray(options.researchArea), securityList: maybeArray(options.security), institutionList: maybeArray(options.institution), categoryList: maybeArray(options.category), sourceList: options.source.length ? options.source : undefined }), { endpointKey: "vault.my-conference.list", idField: "conferenceId" }));
 addDownloadCommand(vault, { endpointKey: "vault.my-conference.download", name: "my-conference-download", idOption: "--conference-id", idField: "conferenceId", fallbackPrefix: "conference", contentTypeDescription: "Content type: asr/summary", titleListEndpoint: "vault.my-conference.list" });
 vault.command("wechat-message-list").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").option("--start-time <datetime>").option("--end-time <datetime>").option("--keyword <text>").option("--security <code>", "Security code (e.g. 000001.SZ)", collectList, []).option("--wechat-group-id <id>", "WeChat group ID", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--category <name>", "Message type: text/image/documents/url", collectList, []).option("--tag <name>", "Tag: roadShow/research/strategyMeeting/meetingSummary/industryComment/companyComment/earningsReview", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("vault.wechat-message.list", buildWechatMessageListBody(options))));
 vault.command("wechat-chatroom-list").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").option("--room-name <name>", "WeChat group name; repeat or comma-separate for multiple names", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("vault.wechat-chatroom.list", buildWechatChatroomListBody(options))));
@@ -571,7 +653,7 @@ program.command("raw").description("Raw API calls").addCommand(new Command("call
     }
     const data = await client.call(endpointKey, body);
     await printData(data, format, options.output);
-}));
+})).addCommand(new Command("list").description("List all registered endpoint keys (for use with 'raw call')").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => printData(listEndpoints(), parseOutputFormat(options.format), options.output)));
 async function checkForUpdate(timeoutMs = 2000) {
     try {
         const response = await fetch("https://registry.npmjs.org/gangtise-openapi-cli/latest", { signal: AbortSignal.timeout(timeoutMs) });

package/dist/src/core/args.js

@@ -24,6 +24,9 @@ export function parseNumberOption(value, optionName, config = {}) {
     if (config.min !== undefined && parsed < config.min) {
         throw new ValidationError(`Invalid ${optionName}: expected a number >= ${config.min}`);
     }
+    if (config.max !== undefined && parsed > config.max) {
+        throw new ValidationError(`Invalid ${optionName}: expected a number <= ${config.max}`);
+    }
     return parsed;
 }
 export function parseOptionalNumberOption(value, optionName, config = {}) {
@@ -91,6 +94,15 @@ export function parseTimestamp13(value, optionName) {
     }
     return parsed;
 }
+/** Machine-local calendar date as `yyyy-MM-dd`, for CLI "default: today" options.
+ * `new Date().toISOString().slice(0,10)` renders the UTC day — for CST users a
+ * pre-08:00 "today" resolves to yesterday. Anchoring to local components matches
+ * toTimestamp13's local-midnight convention. */
+export function localDateString(d) {
+    const month = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${d.getFullYear()}-${month}-${day}`;
+}
 // Parse repeatable `--indicator-param "code:key=value"` specs into the nested
 // indicatorParamList the EDE cross-section / time-series endpoints expect.
 // Multiple specs for the same code accumulate into one group, first-seen order.

package/dist/src/core/client.js

@@ -5,9 +5,9 @@ import { pipeline } from "node:stream/promises";
 import { request } from "undici";
 import { isTokenCacheValid, normalizeToken, readTokenCache, requireAccessCredentials, writeTokenCache } from "./auth.js";
 import { ApiError, ValidationError } from "./errors.js";
-import { ENDPOINTS } from "./endpoints.js";
+import { ENDPOINTS, resolveTimeoutMs } from "./endpoints.js";
 import { getLookupData } from "./lookupData/index.js";
-import { getDispatcher, isVerbose, logTiming, markRetryable, PAGE_CONCURRENCY, runWithConcurrency, withRetry } from "./transport.js";
+import { decodeResponseBody, getDispatcher, isVerbose, logTiming, markRetryable, PAGE_CONCURRENCY, parseRetryAfterMs, runWithConcurrency, withRetry } from "./transport.js";
 // Auth errors that warrant a forced re-login + one replay. 8000014/8000015 are
 // AK/SK errors; 0000001008 is a server-side token invalidation (the token still
 // looks valid by local expiry, so only a forced refresh recovers it).
@@ -119,12 +119,12 @@ export class GangtiseClient {
             return false;
         return 'msg' in obj || 'data' in obj || 'success' in obj || 'status' in obj;
     }
-    throwHttpError(parsed, statusCode) {
+    throwHttpError(parsed, statusCode, retryAfterMs) {
         if (this.isEnvelope(parsed)) {
             const code = parsed.code === undefined ? undefined : String(parsed.code);
-            throw new ApiError(parsed.msg || `API request failed (HTTP ${statusCode})`, code, statusCode, parsed);
+            throw new ApiError(parsed.msg || `API request failed (HTTP ${statusCode})`, code, statusCode, parsed, retryAfterMs);
         }
-        throw new ApiError(`API request failed (HTTP ${statusCode})`, undefined, statusCode, parsed);
+        throw new ApiError(`API request failed (HTTP ${statusCode})`, undefined, statusCode, parsed, retryAfterMs);
     }
     unwrapEnvelope(parsed, statusCode) {
         if (!this.isEnvelope(parsed)) {
@@ -294,75 +294,6 @@ export class GangtiseClient {
         }
         return out;
     }
-    /**
-     * Sequential pagination for endpoints that page by offset but return NO `total`
-     * and use a non-standard list key (e.g. wechat chatroom's `chatRoomList`). We
-     * can't fan out like requestPaginated (no total ⇒ unknown page count), so page
-     * serially until a short page (fewer rows than requested) signals the end.
-     * Returns `{ [listKey]: rows }` so normalize/printer treat it like any list.
-     */
-    async requestSequentialPaginated(endpoint, body) {
-        const initialBody = body && typeof body === 'object' ? { ...body } : {};
-        if ('from' in initialBody && (typeof initialBody.from !== 'number' || !Number.isFinite(initialBody.from) || initialBody.from < 0)) {
-            throw new ValidationError('Invalid from: expected a non-negative number');
-        }
-        if ('size' in initialBody && initialBody.size !== undefined && (typeof initialBody.size !== 'number' || !Number.isFinite(initialBody.size) || initialBody.size <= 0)) {
-            throw new ValidationError('Invalid size: expected a positive number');
-        }
-        const listKey = endpoint.pagination?.listKey ?? 'list';
-        const maxPageSize = endpoint.pagination?.maxPageSize ?? 50;
-        const startFrom = typeof initialBody.from === 'number' && Number.isFinite(initialBody.from) ? initialBody.from : 0;
-        const requestedSize = typeof initialBody.size === 'number' && Number.isFinite(initialBody.size) ? initialBody.size : undefined;
-        const extractList = (page) => {
-            if (!page || typeof page !== 'object')
-                return null;
-            const arr = page[listKey];
-            return Array.isArray(arr) ? arr : null;
-        };
-        const collected = [];
-        let firstPage = null;
-        let from = startFrom;
-        const MAX_PAGES = 1000;
-        let truncatedByPageCap = false;
-        let partialShape = false;
-        for (let page = 0;; page++) {
-            const remaining = requestedSize === undefined ? maxPageSize : requestedSize - collected.length;
-            if (requestedSize !== undefined && remaining <= 0)
-                break;
-            const size = Math.min(maxPageSize, remaining);
-            const pageData = await this.requestJson(endpoint, { ...initialBody, from, size });
-            if (firstPage === null)
-                firstPage = pageData;
-            const list = extractList(pageData);
-            if (list === null) {
-                // First response isn't a paginated-list shape → return it untouched. But a
-                // LATER page losing shape must NOT discard the rows already collected (mirrors
-                // requestPaginated's fail-soft fan-out): stop, keep them, and warn loudly.
-                if (page === 0)
-                    return firstPage;
-                partialShape = true;
-                process.stderr.write(`[gangtise] warning: a page response had unexpected shape; results are partial — ${collected.length} rows fetched.\n`);
-                break;
-            }
-            for (const item of list)
-                collected.push(item);
-            if (list.length < size)
-                break; // short page ⇒ no more rows
-            if (page + 1 >= MAX_PAGES) {
-                truncatedByPageCap = true;
-                break;
-            }
-            from += list.length;
-        }
-        if (truncatedByPageCap) {
-            process.stderr.write(`[gangtise] warning: hit the ${MAX_PAGES}-page safety cap; fetched ${collected.length} rows. Pass --size to fetch a bounded subset.\n`);
-        }
-        const rows = requestedSize === undefined ? collected : collected.slice(0, requestedSize);
-        const out = { [listKey]: rows };
-        if (partialShape)
-            out.partial = true;
-        return out;
-    }
     async login() {
         const authorization = await this.getAuthorizationHeader();
         const cache = await readTokenCache(this.config.tokenCachePath);
@@ -378,9 +309,13 @@ export class GangtiseClient {
         const dispatcher = getDispatcher();
         const url = this.buildUrl(endpoint.path);
         const authState = { retried: false };
+        const timeoutMs = resolveTimeoutMs(this.config.timeoutMs, endpoint);
         return withRetry(async () => {
             const headers = {
                 'content-type': 'application/json',
+                // undici does not auto-decompress; decodeResponseBody gunzips below. Server
+                // gzip cuts JSON payloads ~3-10x (measured 3.6x on constant-list).
+                'accept-encoding': 'gzip',
             };
             // Keep the header we actually sent: the self-heal check compares it against
             // the current memoCache token to tell "stale token" from "fresh token died".
@@ -394,12 +329,22 @@ export class GangtiseClient {
                 method: endpoint.method,
                 headers,
                 body: endpoint.method === 'GET' ? undefined : JSON.stringify(body ?? {}),
-                headersTimeout: this.config.timeoutMs,
-                bodyTimeout: this.config.timeoutMs,
+                headersTimeout: timeoutMs,
+                bodyTimeout: timeoutMs,
                 dispatcher,
             });
-            const text = await response.body.text();
+            // Only buffer + gunzip when the server actually compressed; an unencoded
+            // response reads as text directly (and keeps existing behavior on that path).
+            const encoding = response.headers['content-encoding'];
+            const gzipped = (Array.isArray(encoding) ? encoding[0] : encoding)?.toLowerCase().trim() === 'gzip';
+            const text = gzipped
+                ? decodeResponseBody(new Uint8Array(await response.body.arrayBuffer()), encoding)
+                : await response.body.text();
             logTiming(`${endpoint.method} ${endpoint.path}`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
+            // Parse Retry-After once so every error path below (JSON parse failure AND the
+            // envelope/HTTP-error throw) carries it — a non-JSON 429/503 must still honor
+            // the server's rate window instead of falling back to default backoff.
+            const retryAfterMs = parseRetryAfterMs(response.headers['retry-after'], Date.now());
             let parsed;
             try {
                 parsed = JSON.parse(text);
@@ -408,13 +353,13 @@ export class GangtiseClient {
                 const message = response.statusCode >= 400
                     ? `API request failed (HTTP ${response.statusCode})`
                     : 'Failed to parse API response';
-                throw new ApiError(message, undefined, response.statusCode, text.slice(0, 500));
+                throw new ApiError(message, undefined, response.statusCode, text.slice(0, 500), retryAfterMs);
             }
             try {
                 // Auth errors can arrive as HTTP 4xx or as a 200-wrapped error envelope;
                 // both routes must reach the self-heal check below.
                 if (response.statusCode >= 400) {
-                    this.throwHttpError(parsed, response.statusCode);
+                    this.throwHttpError(parsed, response.statusCode, retryAfterMs);
                 }
                 return this.unwrapEnvelope(parsed, response.statusCode);
             }
@@ -473,6 +418,9 @@ export class GangtiseClient {
                 });
             }
             const contentType = Array.isArray(response.headers['content-type']) ? response.headers['content-type'][0] : response.headers['content-type'];
+            // From the final (post-redirect) response, so a rate-limited download honors
+            // Retry-After too — every error branch below passes it into the ApiError.
+            const retryAfterMs = parseRetryAfterMs(response.headers['retry-after'], Date.now());
             if (contentType?.includes('application/json')) {
                 const text = await response.body.text();
                 logTiming(`GET ${endpoint.path} (json)`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
@@ -482,14 +430,14 @@ export class GangtiseClient {
                 }
                 catch {
                     if (response.statusCode >= 400) {
-                        throw new ApiError('Download failed', undefined, response.statusCode, text);
+                        throw new ApiError('Download failed', undefined, response.statusCode, text, retryAfterMs);
                     }
                     return { text, contentType };
                 }
                 let data;
                 try {
                     if (response.statusCode >= 400) {
-                        this.throwHttpError(parsed, response.statusCode);
+                        this.throwHttpError(parsed, response.statusCode, retryAfterMs);
                     }
                     data = this.unwrapEnvelope(parsed, response.statusCode);
                 }
@@ -506,13 +454,13 @@ export class GangtiseClient {
                 const text = await response.body.text();
                 logTiming(`GET ${endpoint.path} (text)`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
                 if (response.statusCode >= 400) {
-                    throw new ApiError('Download failed', undefined, response.statusCode, text);
+                    throw new ApiError('Download failed', undefined, response.statusCode, text, retryAfterMs);
                 }
                 return { text, contentType };
             }
             if (response.statusCode >= 400) {
                 const text = await response.body.text();
-                throw new ApiError('Download failed', undefined, response.statusCode, text);
+                throw new ApiError('Download failed', undefined, response.statusCode, text, retryAfterMs);
             }
             const contentDisposition = response.headers['content-disposition'];
             const filenameMatch = Array.isArray(contentDisposition)
@@ -572,9 +520,7 @@ export class GangtiseClient {
             return this.download(endpoint, query ?? {}, options);
         }
         if (endpoint.kind === 'json' && endpoint.pagination?.enabled) {
-            return endpoint.pagination.sequential
-                ? this.requestSequentialPaginated(endpoint, body)
-                : this.requestPaginated(endpoint, body);
+            return this.requestPaginated(endpoint, body);
         }
         return this.requestJson(endpoint, body);
     }

package/dist/src/core/commandBodies.js

@@ -4,7 +4,7 @@ export function buildQuoteKlineBody(options) {
         securityList: maybeArray(options.security),
         startDate: options.startDate,
         endDate: options.endDate,
-        limit: parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1 }),
+        limit: parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1, max: 10000 }),
         fieldList: maybeArray(options.field),
     };
 }

package/dist/src/core/config.js

@@ -1,6 +1,6 @@
 import os from "node:os";
 import path from "node:path";
-export const DEFAULT_BASE_URL = "https://open.gangtise.com";
+export const DEFAULT_BASE_URL = "https://openapi.gangtise.com";
 export const DEFAULT_TIMEOUT_MS = 30_000;
 export const DEFAULT_TOKEN_CACHE_PATH = path.join(os.homedir(), ".config", "gangtise", "token.json");
 export function loadConfig() {

package/dist/src/core/endpoints.js

@@ -1,3 +1,8 @@
+/** Effective request timeout: the endpoint's floor, or the config timeout if higher
+ * (a user who raised GANGTISE_TIMEOUT_MS keeps their value). */
+export function resolveTimeoutMs(configTimeoutMs, endpoint) {
+    return Math.max(configTimeoutMs, endpoint.timeoutMs ?? 0);
+}
 // Registry entries omit `key`: it is derived from the record key when ENDPOINTS is
 // built below, so the two can never drift.
 const ENDPOINT_DEFS = {
@@ -181,6 +186,12 @@ const ENDPOINT_DEFS = {
         kind: "json",
         description: "Search chief analyst IDs by name / institution / team",
     },
+    "reference.institution-search": {
+        method: "POST",
+        path: "/application/open-reference/institutions/search",
+        kind: "json",
+        description: "Search institution IDs by keyword (domestic broker / foreign / lead / opinion institution)",
+    },
     "reference.constant-category": {
         method: "GET",
         path: "/application/open-reference/constants/category",
@@ -248,6 +259,12 @@ const ENDPOINT_DEFS = {
         kind: "json",
         description: "Query realtime quote snapshot (A-share / HK / US)",
     },
+    "quote.fund-flow": {
+        method: "POST",
+        path: "/application/open-quote/fund-flow/daily",
+        kind: "json",
+        description: "Query A-share daily fund flow (SH/SZ/BJ; small/medium/large/xlarge orders + main net inflow)",
+    },
     // ─── fundamental ───
     "fundamental.income-statement": {
         method: "POST",
@@ -370,18 +387,21 @@ const ENDPOINT_DEFS = {
         path: "/application/open-ai/agent/one-pager",
         kind: "json",
         description: "Generate one pager",
+        timeoutMs: 120_000,
     },
     "ai.investment-logic": {
         method: "POST",
         path: "/application/open-ai/agent/investment-logic",
         kind: "json",
         description: "Generate investment logic",
+        timeoutMs: 120_000,
     },
     "ai.peer-comparison": {
         method: "POST",
         path: "/application/open-ai/agent/peer-comparison",
         kind: "json",
         description: "Generate peer comparison",
+        timeoutMs: 120_000,
     },
     "ai.earnings-review.get-id": {
         method: "POST",
@@ -400,12 +420,14 @@ const ENDPOINT_DEFS = {
         path: "/application/open-ai/agent/theme-tracking",
         kind: "json",
         description: "Get theme tracking daily report",
+        timeoutMs: 120_000,
     },
     "ai.research-outline": {
         method: "POST",
         path: "/application/open-ai/agent/research-outline",
         kind: "json",
         description: "Get company research outline",
+        timeoutMs: 120_000,
     },
     "ai.hot-topic": {
         method: "POST",
@@ -419,12 +441,14 @@ const ENDPOINT_DEFS = {
         path: "/application/open-ai/management-discuss/from-announcement",
         kind: "json",
         description: "Management discussion from financial reports (half-year/annual)",
+        timeoutMs: 120_000,
     },
     "ai.management-discuss-earnings-call": {
         method: "POST",
         path: "/application/open-ai/management-discuss/from-earningsCall",
         kind: "json",
         description: "Management discussion from earnings calls",
+        timeoutMs: 120_000,
     },
     "ai.viewpoint-debate.get-id": {
         method: "POST",
@@ -490,8 +514,8 @@ const ENDPOINT_DEFS = {
         path: "/application/open-vault/wechatgroupmsg/chatroomId",
         kind: "json",
         description: "List WeChat group chatroom IDs",
-        // No `total` in the response, list key is `chatRoomList`, server caps size at 50.
-        pagination: { enabled: true, maxPageSize: 50, sequential: true, listKey: "chatRoomList" },
+        // Response is `{ total, list }` (server caps size at 50); auto-paginate by total.
+        pagination: { enabled: true, maxPageSize: 50 },
     },
     "vault.stock-pool.list": {
         method: "POST",
@@ -551,3 +575,8 @@ const ENDPOINT_DEFS = {
     },
 };
 export const ENDPOINTS = Object.fromEntries(Object.entries(ENDPOINT_DEFS).map(([key, def]) => [key, { key, ...def }]));
+/** Flat catalog of every registered endpoint, for `raw list` discoverability
+ * (so `raw call` doesn't require memorizing endpoint keys). */
+export function listEndpoints() {
+    return Object.values(ENDPOINTS).map(({ key, method, path, description }) => ({ key, method, path, description }));
+}

package/dist/src/core/errors.js

@@ -34,12 +34,17 @@ export class ApiError extends CliError {
     code;
     statusCode;
     details;
+    retryAfterMs;
     hint;
-    constructor(message, code, statusCode, details) {
+    constructor(message, code, statusCode, details, 
+    /** Server-specified Retry-After (ms), set on 429 responses so the transport
+     * backoff can honor it instead of the default exponential schedule. */
+    retryAfterMs) {
         super(message);
         this.code = code;
         this.statusCode = statusCode;
         this.details = details;
+        this.retryAfterMs = retryAfterMs;
         this.hint = code ? ERROR_HINTS[code] : undefined;
     }
 }

package/dist/src/core/normalize.js

@@ -24,11 +24,6 @@ export function normalizeRows(value) {
         const hasMeta = Object.keys(meta).length > 0;
         return hasMeta ? { ...meta, list } : list;
     }
-    if (Array.isArray(record.chatRoomList)) {
-        const { chatRoomList, ...meta } = record;
-        const hasMeta = Object.keys(meta).length > 0;
-        return hasMeta ? { ...meta, list: chatRoomList } : chatRoomList;
-    }
     if (Array.isArray(record.constants)) {
         const { constants, ...meta } = record;
         const hasMeta = Object.keys(meta).length > 0;

package/dist/src/core/output.js

@@ -14,8 +14,9 @@ export function parseOutputFormat(value) {
 function sanitizeCell(value) {
     return value.replace(/[\r\n]+/g, " ").replace(/[\u0000-\u001f\u007f]/g, "");
 }
-/** Terminal display width: CJK/fullwidth chars occupy 2 columns — padEnd counts
- * UTF-16 code units and misaligns every table containing Chinese text. */
+/** Terminal display width: CJK/fullwidth chars and emoji occupy 2 columns — padEnd
+ * counts UTF-16 code units and misaligns every table containing Chinese text or emoji
+ * (e.g. WeChat group names). */
 function displayWidth(value) {
     let width = 0;
     for (const ch of value) {
@@ -23,7 +24,8 @@ function displayWidth(value) {
         const wide = (cp >= 0x1100 && cp <= 0x115f) || (cp >= 0x2e80 && cp <= 0xa4cf)
             || (cp >= 0xac00 && cp <= 0xd7a3) || (cp >= 0xf900 && cp <= 0xfaff)
             || (cp >= 0xfe30 && cp <= 0xfe4f) || (cp >= 0xff00 && cp <= 0xff60)
-            || (cp >= 0xffe0 && cp <= 0xffe6) || (cp >= 0x20000 && cp <= 0x3fffd);
+            || (cp >= 0xffe0 && cp <= 0xffe6) || (cp >= 0x1f000 && cp <= 0x1faff)
+            || (cp >= 0x20000 && cp <= 0x3fffd);
         width += wide ? 2 : 1;
     }
     return width;

package/dist/src/core/printer.js

@@ -1,6 +1,18 @@
 import { normalizeRows } from "./normalize.js";
 import { pickList, renderOutput, saveOutputIfNeeded, streamOutputToFile } from "./output.js";
 import { extractTitles, writeTitleCache } from "./titleCache.js";
+/** Rows above which renderOutput's single in-memory string risks high memory / the V8
+ * max-string-length cap. Well above normal result sizes, so it only fires on huge exports. */
+const LARGE_RESULT_ROWS = 50_000;
+/** Warn when we're about to renderOutput a huge result. Called only on the paths that
+ * actually render — never after streamOutputToFile streamed — so it can't misfire on a
+ * genuinely streamed export, and it DOES fire on the all-scalar-csv list that streaming
+ * declines (which then falls back to a full in-memory string). */
+function warnIfLargeInMemory(items, format) {
+    if (items && items.length >= LARGE_RESULT_ROWS) {
+        process.stderr.write(`[gangtise] note: ${items.length} rows in '${format}' is built entirely in memory; stream large exports to a file with --format jsonl --output <path> (or csv).\n`);
+    }
+}
 export async function printData(data, format, output, cache) {
     const normalized = normalizeRows(data);
     const items = pickList(normalized);
@@ -28,6 +40,9 @@ export async function printData(data, format, output, cache) {
             process.stdout.write(`${output}\n`);
             return;
         }
+        // streamOutputToFile declined (non-stream format, or an all-scalar csv list) \u2192 we
+        // fall back to renderOutput, which builds the whole result as one string.
+        warnIfLargeInMemory(items, format);
         const content = renderOutput(normalized, format);
         // CSV files get a BOM so Excel double-click decodes Chinese as UTF-8 (stdout
         // stays BOM-free for pipes).
@@ -35,5 +50,6 @@ export async function printData(data, format, output, cache) {
         process.stdout.write(`${output}\n`);
         return;
     }
+    warnIfLargeInMemory(items, format);
     process.stdout.write(`${renderOutput(normalized, format)}\n`);
 }

package/dist/src/core/quoteSharding.js

@@ -16,11 +16,21 @@ function parseDate(value) {
 function formatDate(d) {
     return d.toISOString().slice(0, 10);
 }
-function isAllMarket(body) {
+export function isFullMarket(body, fullMarketValue) {
     const list = body.securityList;
     if (!Array.isArray(list) || list.length !== 1)
         return false;
-    return list[0] === "all";
+    return list[0] === fullMarketValue;
+}
+/** Kline uses `all` as its whole-market keyword; fund-flow uses `aShares`. Thin wrapper
+ * so kline call sites read naturally. */
+export function isAllMarket(body) {
+    return isFullMarket(body, "all");
+}
+/** Sat/Sun in UTC — shard dates are formatted from UTC midnight (see parseDate). */
+function isWeekendUtc(d) {
+    const day = d.getUTCDay();
+    return day === 0 || day === 6;
 }
 function buildShards(start, end, shardDays) {
     const shards = [];
@@ -28,10 +38,17 @@ function buildShards(start, end, shardDays) {
     const endTime = end.getTime();
     while (cursor <= endTime) {
         const shardEnd = Math.min(cursor + (shardDays - 1) * DAY_MS, endTime);
-        shards.push({
-            startDate: formatDate(new Date(cursor)),
-            endDate: formatDate(new Date(shardEnd)),
-        });
+        // Per-day sharding (shardDays===1): a lone weekend day always returns empty (A/HK/US
+        // markets closed) — skip it to save ~28% of requests and daily quota. This covers
+        // every 1-day-sharded full-market query: fund-flow AND day-kline / day-kline-us
+        // (both shardDays 1 in cli.ts). Multi-day shards (day-kline-hk=2, index=30) always
+        // straddle weekdays, so they're never dropped.
+        if (!(shardDays === 1 && isWeekendUtc(new Date(cursor)))) {
+            shards.push({
+                startDate: formatDate(new Date(cursor)),
+                endDate: formatDate(new Date(shardEnd)),
+            });
+        }
         cursor = shardEnd + DAY_MS;
     }
     return shards;
@@ -43,7 +60,8 @@ function buildShards(start, end, shardDays) {
  * single-security queries this is a no-op.
  */
 export async function callKlineWithSharding(client, endpointKey, body, config) {
-    if (!isAllMarket(body)) {
+    const fullMarketValue = config.fullMarketValue ?? "all";
+    if (!isFullMarket(body, fullMarketValue)) {
         return client.call(endpointKey, body);
     }
     // `--security all` returns thousands of rows per day; lift the default 6000-row
@@ -51,19 +69,47 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
     // must apply even when a date is missing (no sharding possible then, but the
     // single request still needs the lifted cap).
     const allMarketBody = { ...body, limit: body.limit ?? ALL_MARKET_LIMIT };
+    const perShardLimit = allMarketBody.limit ?? ALL_MARKET_LIMIT;
+    // A shard maxes out for two reasons with different fixes: a user-set low --limit is
+    // raisable; hitting the API cap itself is not (only a smaller internal shardDays window
+    // would help). Word the truncation warning accordingly.
+    const truncationHint = perShardLimit < ALL_MARKET_LIMIT
+        ? "raise or omit --limit to fetch the full market"
+        : `a single ${config.shardDays}-day window exceeds the ${ALL_MARKET_LIMIT}-row API cap`;
+    // A full-market response whose row count reaches the per-request limit was itself
+    // capped (a low user --limit, or a single day exceeding the API row cap) — its slice
+    // is incomplete, so the result must be flagged partial rather than shown as complete.
+    const isTruncated = (rec) => Array.isArray(rec.list) && rec.list.length >= perShardLimit;
+    // A single full-market request (missing/unparseable dates, or a range that fits one
+    // shard) skips the merge loop below, so it needs the same truncation check inline — or
+    // a low --limit / oversized day slips through as a silent exit-0 success.
+    const callSingle = async () => {
+        const single = await client.call(endpointKey, allMarketBody);
+        if (single && typeof single === "object" && !Array.isArray(single) && isTruncated(single)) {
+            ;
+            single.partial = true;
+            process.stderr.write(`[gangtise] warning: full-market request hit the ${perShardLimit}-row limit and was likely truncated; results are partial — ${truncationHint}.\n`);
+        }
+        return single;
+    };
     if (!body.startDate || !body.endDate) {
-        return client.call(endpointKey, allMarketBody);
+        return callSingle();
     }
     const start = parseDate(body.startDate);
     const end = parseDate(body.endDate);
     if (!start || !end || end < start) {
-        return client.call(endpointKey, allMarketBody);
+        return callSingle();
     }
     const totalDays = Math.floor((end.getTime() - start.getTime()) / DAY_MS) + 1;
     if (totalDays <= config.shardDays) {
-        return client.call(endpointKey, allMarketBody);
+        return callSingle();
     }
     const shards = buildShards(start, end, config.shardDays);
+    // A range that's entirely weekends (per-day sharding) filters down to nothing — no
+    // trading days to fetch. Return empty rather than falling into the all-shards-failed
+    // check below, which would misread 0 shards as a total outage and throw.
+    if (shards.length === 0)
+        return { list: [] };
     // isVerbose() (not a direct env read) so the global --verbose flag reaches
     // shard logging too — cli.ts enables it via setVerbose in a preAction hook.
     if (isVerbose()) {
@@ -89,6 +135,7 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
     let fieldList;
     let header = null;
     const merged = [];
+    let truncatedShards = 0;
     for (const r of results) {
         if (!(r && typeof r === "object"))
             continue;
@@ -97,6 +144,8 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
             header = rec;
         if (!fieldList && Array.isArray(rec.fieldList))
             fieldList = rec.fieldList;
+        if (isTruncated(rec))
+            truncatedShards++;
         // Append one-by-one rather than push(...list): a future higher row cap could
         // make a single shard's list large enough to overflow the stack via spread.
         if (Array.isArray(rec.list))
@@ -110,7 +159,9 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
     }
     if (!header)
         return { list: [] };
-    const out = { ...header, list: merged };
+    // `total` on a shard is that shard's own row count; overwrite it with the merged count
+    // so the JSON `total` and the `Total:` stderr line reflect the whole combined result.
+    const out = { ...header, total: merged.length, list: merged };
     if (fieldList)
         out.fieldList = fieldList;
     if (failedShards.length > 0) {
@@ -118,5 +169,9 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
         out.failedShards = failedShards;
         process.stderr.write(`[gangtise] warning: ${failedShards.length}/${shards.length} shards failed; results are partial (see failedShards)\n`);
     }
+    if (truncatedShards > 0) {
+        out.partial = true;
+        process.stderr.write(`[gangtise] warning: ${truncatedShards}/${shards.length} shard(s) hit the ${perShardLimit}-row limit and were likely truncated; results are partial — ${truncationHint}.\n`);
+    }
     return out;
 }

package/dist/src/core/transport.js

@@ -1,5 +1,38 @@
+import { gunzipSync } from "node:zlib";
 import { Agent } from "undici";
 import { ApiError } from "./errors.js";
+/** Decode an HTTP response body honoring Content-Encoding. undici does not
+ * auto-decompress, so requestJson advertises `accept-encoding: gzip` and gunzips
+ * here; an unencoded body is read as-is. */
+export function decodeResponseBody(buf, contentEncoding) {
+    const enc = (Array.isArray(contentEncoding) ? contentEncoding[0] : contentEncoding)?.toLowerCase().trim();
+    const b = Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength);
+    return enc === "gzip" ? gunzipSync(b).toString("utf8") : b.toString("utf8");
+}
+/** A Retry-After delay we'll honor even if it exceeds maxDelay — but never past this
+ * ceiling, so a hostile/misconfigured header can't hang the CLI for minutes. */
+const RETRY_AFTER_CEILING_MS = 60_000;
+/** Parse a Retry-After header (delta-seconds or an HTTP-date) into a delay in ms.
+ * Returns undefined when absent or unparseable. `nowMs` is injected for testing. */
+export function parseRetryAfterMs(value, nowMs) {
+    const raw = (Array.isArray(value) ? value[0] : value)?.trim();
+    if (!raw)
+        return undefined;
+    if (/^\d+$/.test(raw))
+        return Number(raw) * 1000;
+    const dateMs = Date.parse(raw);
+    return Number.isNaN(dateMs) ? undefined : Math.max(0, dateMs - nowMs);
+}
+/** A retryable error may carry a server-specified Retry-After (attached by the
+ * client on a 429); prefer it over the computed backoff. */
+function retryAfterFromError(error) {
+    if (error && typeof error === "object") {
+        const v = error.retryAfterMs;
+        if (typeof v === "number" && Number.isFinite(v) && v >= 0)
+            return v;
+    }
+    return undefined;
+}
 let cachedDispatcher = null;
 export function getDispatcher() {
     if (!cachedDispatcher) {
@@ -70,8 +103,12 @@ export async function withRetry(fn, options = {}) {
         catch (error) {
             if (attempt >= retries || !isRetryableError(error))
                 throw error;
-            const jitter = Math.random() * baseDelay;
-            const delay = Math.min(maxDelay, baseDelay * 2 ** attempt + jitter);
+            // A server-sent Retry-After (429) wins over exponential backoff, but is capped
+            // so it can't stall the CLI; otherwise fall back to jittered exponential backoff.
+            const retryAfter = retryAfterFromError(error);
+            const delay = retryAfter !== undefined
+                ? Math.min(retryAfter, RETRY_AFTER_CEILING_MS)
+                : Math.min(maxDelay, baseDelay * 2 ** attempt + Math.random() * baseDelay);
             options.onRetry?.(attempt + 1, error, delay);
             await new Promise(resolve => setTimeout(resolve, delay));
             attempt++;

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated — DO NOT EDIT
-export const CLI_VERSION = "0.22.1";
+export const CLI_VERSION = "0.24.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gangtise-openapi-cli",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "description": "CLI for Gangtise OpenAPI",
   "license": "MIT",
   "repository": {