gangtise-openapi-cli 0.23.0 → 0.25.0

package/README.md

@@ -4,6 +4,42 @@
 
 ## Changelog
 
+### v0.25.0 — 2026-07-10
+
+**新增接口（4）**
+- `insight qa list` — 投资者问答 QA：按证券提取互动平台 / 电话会议 / 调研纪要的提问与回答；`--security-code`（必填）、`--source`（`conference`/`interactive`/`survey`）、`--question-category`（11 类，见 `insight.md`）、`--answer-important`（`1` 是 / `0` 否）、`--start-time`/`--end-time`（字符串直传）；自动翻页（单页上限 500）；0.1 积分/条
+- `insight report-image list` / `download` — 研报图表：按关键词搜索研报图片，返回 `chunkId` + 元数据（`--keyword` 必填、`--top` 默认 10 上限 20、`--source-id`、时间过滤；**免费**），再 `download --chunk-id` 下二进制原图（JPEG，0.1 积分/张）
+- `reference official-account-search` — 公众号 ID 搜索：输入公众号名 / 机构 / 关键字返回 `accountId`（喂 `insight official-account list --account-id`）；`--keyword`（必填）、`--category`（`listedCompany`/`broker`/`government`/`media`，可重复；未分类公众号 `category` 为 `null`，传 `--category` 会漏掉）、`--top`（默认 10 上限 10）；免费
+
+**变更**
+- `indicator search` / `cross-section` / `time-series` 市场范围从仅 A 股扩展至 A 股 / 港股 / 美股（服务端变更；CLI 早已支持 `--currency` 与多市场证券代码，无需改动）。⚠️ 美股代码用交易所后缀 `.O`(NASDAQ) / `.N`(NYSE)，**非 `.US`**——官方示例的 `AAPL.US` 查不到数据，实测须 `AAPL.O`
+
+**修复 / 加固**（承接上一批未单独发版的改动）
+- 分页 / 分片 `partial` 检测补全：`requestPaginated` 的短后续页、`MAX_PAGES` 上限、`total` 漂移、失败页四种场景统一触发 `partial`（退出码 3）——失败页独立成判定条件，避免超额返回的兄弟页把行数补满、掩盖失败页空洞；`quote` 全市场分片硬错后熔断、破损形状分片计入 `failedShards`
+- `--top` 本地上限校验（`report-image` / `knowledge-batch` ≤20，reference 六个搜索命令 ≤10）——实测服务端对超限值**静默截断**不报错，现在发请求前本地报错；`securities-search` / `institution-search` / `official-account-search` 的 `--category` 加本地白名单——实测服务端对拼错的分类**不报错**（securities-search 静默忽略过滤返回全类别、另两个静默返回空），拼写错误不再伪装成"无结果"（`insight qa` 的枚举服务端会报 `100003`，故不做本地白名单）
+- 错误码 `100003`（参数值非法）补充中文提示——服务端不指明是哪个参数，提示对照命令 `--help` 检查枚举参数拼写
+- undici `^7.16.0` → `^7.28.0`（修 keep-alive 队列污染 GHSA-35p6-xmwp-9g52），`engines.node` `>=20` → `>=20.18.1` 对齐 undici 实际最低要求
+
+### 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
 
 **行为变更（注意）**
@@ -49,82 +85,6 @@
 - `gangtise ... | head` 遇 stdout `EPIPE` 时安静退出；只有首个参数是 `--version` / `-V` 时才触发版本快捷路径
 - Endpoint registry 的 `key` 改为由记录键自动派生，减少映射漂移；新增真实 CLI 选项到请求体的 stub 测试；测试 272 → 323
 
-### v0.21.0 — 2026-06-29
-
-**行为变更（注意）**
-- ⚠️ `vault wechat-chatroom-list` 省略 `--size` 现在**拉全量**（此前默认只返回 20 条）。该接口不返回 `total`，CLI 改为串行翻页（翻到不满页为止，单页上限 50）；传 `--size N` 仍只取前 N 条。依赖"默认 20 条"的脚本会拿到全部群。
-
-**修复**
-- `quote day-kline --security all` 等大结果集用默认 `table` 格式输出时不再因 `Math.max(...大数组)` 撑爆调用栈崩溃（`RangeError`）；`renderTable` 改用 reduce 计算列宽
-- CSV 导出：含回车符 `\r` 的字段现在正确加引号（RFC 4180）；`table` / `markdown` 的多行字段折叠换行，保持表格对齐
-- 下载文件名剥离控制字符 / NUL，避免 `fs.writeFile` 报错
-
-**修复（安全）**
-- token 缓存文件（`~/.config/gangtise/token.json`）改为临时文件 + 原子 `rename` 写入：从第一字节即 `0600`，消除"旧文件宽松权限残留"与"崩溃截断"两个隐患
-
-**内部 / 工程**
-- 依赖 `vitest` 升级到 3.2.6（修复 dev-only 安全告警）；新增 `npm run typecheck`；测试 257 → 272
-
-### v0.20.0 — 2026-06-26
-
-**新增接口**
-- `insight announcement-us list` / `download` — 美股公司公告列表与下载（`--security TSLA.O`、`--category`〔分类用 `reference constant-list --category usShareAnnouncementCategory`，美股独立的 `103980xxx` 段〕、`--search-type`、`--rank-type`、下载 `--file-type 1` 原始 PDF / `2` Markdown）；自动翻页，单页上限 50
-- `ai stock-summary` — 个股看点（精炼投研总结）：`--security` 传具体代码（A股/港股，可重复，单次最多 6000）或市场关键词 `aShares` / `hkStocks` 拉全市场；无看点的证券不返回、不扣分
-- `fundamental income-statement-us` / `balance-sheet-us` / `cash-flow-us` — 美股三大财务报表（参数同其他财报：`--security-code` / `--period` / `--report-type` / `--fiscal-year` / `--field` 等）
-- `reference chiefs-search` — 首席分析师 ID 搜索（`--keyword` 按姓名/机构/团队匹配，`--top` 默认 10）；用于 `insight opinion list --chief` 的入参
-
-**变更**
-- `insight announcement-hk download` 新增 `--file-type`（`1` 原始（默认）/ `2` Markdown），此前无格式选项
-
-**行为变更（注意）**
-- ⚠️ `auth login` / `auth status` 默认脱敏 access token：`--format json` 输出里 `authorization` 与 `cache.accessToken` 显示为 `<redacted>`，仅保留过期时间 / 用户名 / 产品码 / uid 等非敏感字段。**依赖 `auth login` 原始 token 输出的脚本会拿到 `<redacted>`**，需改用 `auth login --show-token` 获取明文。
-
-**修复（安全）**
-- `auth status` / `auth login` token 脱敏：按凭证字段名模式匹配（`token`/`key`/`secret`/`password`/`credential`），覆盖 `apiKey`/`privateKey`/`refreshToken` 等任何可能携带的凭证字段
-- 自愈守卫：同时设 `GANGTISE_TOKEN` + AK/SK 时，注入 token 失效后重新登录不再被旧 token 短路，重试改用登录拿到的新 token
-
-**修复（数据正确性 / 健壮性）**
-- ⚠️ **CSV 负数不再被破坏**（影响所有 CSV 导出）：此前防公式注入会把负数（如跌幅 `-3.5`）加 `'` 前缀变成文本，Excel/pandas 无法参与计算；现仅对非有限数字的可疑串（`=`/`@`/`-1+cmd` 等）加前缀，合法数字原样输出
-- 自动翻页改为 fail-soft：某页遇不可重试错误（限流 `903301` 等）不再丢弃已取的全部数据，返回已取页 + `partial` / `failedPages` 标记，并在首错后停止继续请求（避免撞限流多烧配额）
-- 下载文件名 fallback（服务端 `Content-Disposition`）补清洗：含 `/`、`:` 等字符的文件名不再写到意外路径
-- `ai stock-summary` / `ai knowledge-batch` 缺 `--security` / `--query` 时本地报错，不再发空请求（stock-summary 借此避免被后台当全市场误扣积分）
-- `ai hot-topic` `--no-with-related-securities` / `--no-with-close-reading` 改为显式发 `false`（语义更明确，不依赖"字段缺失=排除"的隐含约定）
-
-**修复（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)。
 
 ## 首次安装
@@ -254,9 +214,12 @@ cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
 | | `foreign-opinion list` | 外资机构观点 |
 | | `independent-opinion list` / `download` | 外资独立分析师观点（含原文/翻译HTML下载） |
 | | `official-account list` / `download` | 产业公众号资讯（含 txt/HTML 下载） |
+| | `qa list` | 投资者问答 QA（互动平台/电话会议/调研纪要，按证券） |
+| | `report-image list` / `download` | 研报图表搜索（按关键词，含原图 JPEG 下载） |
 | **Reference** | `securities-search` | GTS Code 搜索（按名称/代码/拼音匹配） |
 | | `chiefs-search` | 首席分析师 ID 搜索（按姓名/机构/团队匹配） |
 | | `institution-search` | 机构 ID 搜索（内资券商/外资/牵头/观点机构，按名称匹配） |
+| | `official-account-search` | 公众号 ID 搜索（按公众号名/机构/分类匹配，返回 accountId） |
 | | `constant-category` | 常量分类列表（含各分类适用的接口与参数） |
 | | `constant-list` | 按分类导出常量值全量列表（行业/城市/公告分类/区域等） |
 | | `concept-search` | 题材 ID 搜索（名称/拼音/分组名匹配） |
@@ -315,7 +278,7 @@ cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
 - `gangtise indicator ...`
 - `gangtise alternative ...`
 - `gangtise reference ...`
-- `gangtise raw call ...`
+- `gangtise raw call ...` / `gangtise raw list`
 
 ## 推荐工作流
 
@@ -350,7 +313,7 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 - **流式输出**：`jsonl`/`csv` 格式且 `--output` 指定时，超过 1000 行自动切换为逐行写盘，避免一次性构建百 MB 字符串。
 - **自动重试**：5xx / 429 / `ECONNRESET` / `ETIMEDOUT` / `ENOTFOUND` / `EAI_AGAIN` / `UND_ERR_*`（undici 超时类）/ `999999` 系统错误自动指数退避重试 2 次。
 - **Token 自愈**：调用返回 8000014/8000015 时自动强制刷新 Token 并重试一次。
-- **K线自动分片**：`quote day-kline --security all` 等全市场查询自动按日期切分（A股 1 天/片、美股 1 天/片、HK 2 天/片、指数 30 天/片），并发执行后合并结果。分片时如果用户未传 `--limit`，自动注入 `limit: 10000`（API 上限）避免默认 6000 截断。
+- **K线/资金流向自动分片**：`quote day-kline --security all`、`quote fund-flow --security aShares` 等全市场查询自动按日期切分（A股 K线/资金流向 1 天/片、美股 1 天/片、HK 2 天/片、指数 30 天/片），并发执行后合并结果；按日分片自动跳过周六日。分片时如果用户未传 `--limit`，自动注入 `limit: 10000`（API 上限）避免默认 6000 截断。
 - **Token 内存缓存**：Token 在进程内存中缓存，避免每次请求读盘。
 - **`--verbose`**：打印每个请求的方法、路径、状态码、耗时和响应大小到 stderr，方便定位慢查询。
 
@@ -371,6 +334,7 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 - `insight foreign-opinion list`
 - `insight independent-opinion list`
 - `insight official-account list`
+- `insight qa list`
 - `ai security-clue`
 - `vault drive-list`
 - `vault record-list`
@@ -459,6 +423,12 @@ gangtise insight independent-opinion download --independent-opinion-id 207051900
 gangtise insight official-account list --keyword 泡泡玛特 --rank-type 2 --size 20 --format json
 gangtise insight official-account download --article-id 7286248 --file-type 2
 
+# 投资者问答 QA（按证券；--source/--question-category/--answer-important 精筛，自动翻页）
+gangtise insight qa list --security-code 601012.SH --source interactive --answer-important 1 --size 20 --format json
+# 研报图表：按关键词搜图拿 chunkId，再下原图（JPEG）
+gangtise insight report-image list --keyword AI --top 5 --format json
+gangtise insight report-image download --chunk-id image_10_384655917758685184_8 --output ./ai-chart.jpg
+
 # 纪要下载（会议平台来源可选 HTML 格式）
 gangtise insight summary download --summary-id 4906813 --file-type 2
 ```
@@ -475,8 +445,10 @@ 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）
+# 机构 ID 搜索（--category: domesticBroker/foreignInstitution/leadInstitution/opinionInstitution/foreignOpinionInstitution）
 gangtise reference institution-search --keyword 招商证券 --category domesticBroker --top 3 --format json
+# 公众号 ID 搜索（按名称/机构/分类；拿 accountId 供 insight official-account list --account-id）
+gangtise reference official-account-search --keyword 中信证券 --top 3 --format json
 
 # 常量查询：先看分类，再按分类导出全量常量值
 gangtise reference constant-category --format json
@@ -696,6 +668,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, parseChoiceList, 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, 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";
@@ -169,6 +169,8 @@ const announcementUs = new Command("announcement-us");
 const foreignOpinion = new Command("foreign-opinion");
 const independentOpinion = new Command("independent-opinion");
 const officialAccount = new Command("official-account");
+const qa = new Command("qa");
+const reportImage = new Command("report-image");
 addTimeFilters(opinion.command("list").option("--rank-type <number>", "Rank type", "1").option("--research-area <id>", "Research area ID", collectList, []).option("--chief <id>", "Chief ID", collectList, []).option("--security <code>", "Security code", collectList, []).option("--broker <id>", "Broker ID", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--concept <id>", "Concept ID", collectList, []).option("--llm-tag <tag>", "Semantic tag", collectList, []).option("--source <source>", "Source", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.opinion.list", {
     from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime,
     rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }), keyword: options.keyword, researchAreaList: maybeArray(options.researchArea), chiefList: maybeArray(options.chief),
@@ -310,6 +312,19 @@ addTimeFilters(officialAccount.command("list").option("--search-type <number>",
     categoryList: maybeArray(options.category), industryList: maybeArray(options.industry),
 }), { endpointKey: "insight.official-account.list", idField: "articleId" }));
 addDownloadCommand(officialAccount, { endpointKey: "insight.official-account.download", idOption: "--article-id", idField: "articleId", fallbackPrefix: "official-account", fileType: { description: "File type: 1=txt(default) 2=HTML", default: "1" }, titleListEndpoint: "insight.official-account.list" });
+// QA request keys are BARE (source/questionCategory/answerImportant), not the *List
+// convention — the body below mirrors the spec exactly. Datetimes pass through as strings.
+qa.command("list").requiredOption("--security-code <code>", "Security code, e.g. 601012.SH").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all (max page 500)").option("--start-time <datetime>", "Start time (yyyy-MM-dd or yyyy-MM-dd HH:mm:ss)").option("--end-time <datetime>", "End time (yyyy-MM-dd or yyyy-MM-dd HH:mm:ss)").option("--source <type>", "Source: conference/interactive/survey (repeat)", collectList, []).option("--question-category <name>", "Question category (repeat): productAndBusiness/capacityAndProjects/ordersAndCustomers/financialData/materialEvents/capitalOperations/shareholdersAndDividends/corporateGovernance/marketAndValuation/macroAndIndustry/risksAndOthers", collectList, []).option("--answer-important <flag>", "Answer involves key info: 1=yes 0=no (repeat; omit for all)", collectNumberList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("insight.qa.list", {
+    from: parseFrom(options.from), size: parseSize(options.size),
+    securityCode: options.securityCode, startTime: options.startTime, endTime: options.endTime,
+    source: maybeArray(options.source), questionCategory: maybeArray(options.questionCategory),
+    answerImportant: options.answerImportant.length ? options.answerImportant : undefined,
+})));
+reportImage.command("list").requiredOption("--keyword <text>", "Search keyword, e.g. 'AI' '新能源汽车'").option("--top <number>", "Max results (default: 10, max: 20)", "10").option("--source-id <id>", "Report source ID, to filter to one report (from a report list or knowledge base)").option("--start-time <datetime>", "Start time (yyyy-MM-dd HH:mm:ss; yyyy-MM-dd auto-completed)").option("--end-time <datetime>", "End time (yyyy-MM-dd HH:mm:ss; yyyy-MM-dd auto-completed)").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("insight.report-image.list", {
+    keyword: options.keyword, top: parseNumberOption(options.top, "--top", { integer: true, min: 1, max: 20 }),
+    sourceId: options.sourceId, startTime: options.startTime, endTime: options.endTime,
+})));
+addDownloadCommand(reportImage, { endpointKey: "insight.report-image.download", idOption: "--chunk-id", idField: "chunkId", fallbackPrefix: "report-image" });
 insight.addCommand(opinion);
 insight.addCommand(summary);
 insight.addCommand(roadshow);
@@ -324,6 +339,8 @@ insight.addCommand(announcementUs);
 insight.addCommand(foreignOpinion);
 insight.addCommand(independentOpinion);
 insight.addCommand(officialAccount);
+insight.addCommand(qa);
+insight.addCommand(reportImage);
 program.addCommand(insight);
 const quote = new Command("quote").description("Quote APIs");
 const addKlineCommand = (name, endpointKey, securityHelp, shardDays) => quote.command(name)
@@ -428,7 +445,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);
@@ -436,10 +453,10 @@ fundamental.command("earning-forecast").requiredOption("--security-code <code>")
 }));
 program.addCommand(fundamental);
 const ai = new Command("ai").description("AI APIs");
-ai.command("knowledge-batch").option("--query <text>", "Query", collectList, []).option("--top <number>", "Top", "10").option("--resource-type <number>", "Resource type", collectNumberList, []).option("--knowledge-name <name>", "Knowledge name", collectList, []).option("--start-time <ms>").option("--end-time <ms>").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => {
+ai.command("knowledge-batch").option("--query <text>", "Query", collectList, []).option("--top <number>", "Max results (default: 10, max: 20)", "10").option("--resource-type <number>", "Resource type", collectNumberList, []).option("--knowledge-name <name>", "Knowledge name", collectList, []).option("--start-time <ms>").option("--end-time <ms>").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => {
     if (!options.query.length)
         throw new ValidationError("--query is required: pass at least one --query");
-    return emit(options, (client) => client.call("ai.knowledge-batch", { queries: options.query, top: parseNumberOption(options.top, "--top", { integer: true, min: 1 }), resourceTypes: options.resourceType.length ? options.resourceType : undefined, knowledgeNames: maybeArray(options.knowledgeName), startTime: parseOptionalNumberOption(options.startTime, "--start-time", { integer: true, min: 0 }), endTime: parseOptionalNumberOption(options.endTime, "--end-time", { integer: true, min: 0 }) }));
+    return emit(options, (client) => client.call("ai.knowledge-batch", { queries: options.query, top: parseNumberOption(options.top, "--top", { integer: true, min: 1, max: 20 }), resourceTypes: options.resourceType.length ? options.resourceType : undefined, knowledgeNames: maybeArray(options.knowledgeName), startTime: parseOptionalNumberOption(options.startTime, "--start-time", { integer: true, min: 0 }), endTime: parseOptionalNumberOption(options.endTime, "--end-time", { integer: true, min: 0 }) }));
 });
 ai.command("knowledge-resource-download").requiredOption("--resource-type <number>").requiredOption("--source-id <id>").option("--output <path>").action((options) => withClient(async (client) => {
     await runDownload(client, "ai.knowledge-resource.download", { resourceType: parseNumberOption(options.resourceType, "--resource-type", { integer: true, min: 0 }), sourceId: options.sourceId }, {
@@ -538,28 +555,34 @@ ai.command("stock-summary").description("Stock highlights: refined research summ
 const reference = new Command("reference").description("Reference data APIs");
 reference.command("securities-search").requiredOption("--keyword <text>", "Search keyword (name/code/pinyin/English)").option("--category <type>", "Category: stock/dr/index/fund", 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.securities-search", {
     keyword: options.keyword,
-    category: options.category.length ? options.category : undefined,
-    top: parseNumberOption(options.top, "--top", { integer: true, min: 1 }),
+    category: parseChoiceList(options.category, "--category", ["stock", "dr", "index", "fund"]),
+    top: parseNumberOption(options.top, "--top", { integer: true, min: 1, max: 10 }),
 })));
 reference.command("constant-category").description("List constant categories and which API params accept them").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("reference.constant-category")));
 reference.command("constant-list").requiredOption("--category <code>", "Category code from 'reference constant-category' (e.g. citicIndustry/swIndustry/regionCategory)").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("reference.constant-list", { category: options.category })));
 reference.command("concept-search").requiredOption("--keyword <text>", "Search keyword (name/pinyin/group name)").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.concept-search", {
     keyword: options.keyword,
-    top: parseNumberOption(options.top, "--top", { integer: true, min: 1 }),
+    top: parseNumberOption(options.top, "--top", { integer: true, min: 1, max: 10 }),
 })));
 reference.command("sector-search").option("--keyword <text>", "Search keyword (name/pinyin)").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.sector-search", {
     keyword: options.keyword,
-    top: parseNumberOption(options.top, "--top", { integer: true, min: 1 }),
+    top: parseNumberOption(options.top, "--top", { integer: true, min: 1, max: 10 }),
 })));
 reference.command("sector-constituents").requiredOption("--sector-id <id>", "Sector ID from 'reference sector-search'").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("reference.sector-constituents", { sectorId: options.sectorId })));
 reference.command("chiefs-search").requiredOption("--keyword <text>", "Search keyword (chief name / institution / team)").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.chiefs-search", {
     keyword: options.keyword,
-    top: parseNumberOption(options.top, "--top", { integer: true, min: 1 }),
+    top: parseNumberOption(options.top, "--top", { integer: true, min: 1, max: 10 }),
 })));
 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 }),
+    categoryList: parseChoiceList(options.category, "--category", ["domesticBroker", "foreignInstitution", "leadInstitution", "opinionInstitution", "foreignOpinionInstitution"]),
+    top: parseNumberOption(options.top, "--top", { integer: true, min: 1, max: 10 }),
+})));
+// Note: request key is BARE `category` here (spec), unlike institution-search's `categoryList`.
+reference.command("official-account-search").requiredOption("--keyword <text>", "Search keyword (account name / institution / keyword, e.g. 东吴证券)").option("--category <name>", "Category: listedCompany/broker/government/media (repeat); omit for all incl. uncategorized", 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.official-account-search", {
+    keyword: options.keyword,
+    category: parseChoiceList(options.category, "--category", ["listedCompany", "broker", "government", "media"]),
+    top: parseNumberOption(options.top, "--top", { integer: true, min: 1, max: 10 }),
 })));
 program.addCommand(reference);
 const vault = new Command("vault").description("Vault APIs");
@@ -653,7 +676,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

@@ -62,6 +62,17 @@ export function collectKeyValue(value, previous = {}) {
 export function maybeArray(value) {
     return value.length > 0 ? value : undefined;
 }
+// Whitelist for enum-valued repeatable options. Only used where the server was
+// probed NOT to reject bad values (it silently ignores the filter or returns
+// empty instead) — endpoints that answer 100003 keep server-side validation.
+export function parseChoiceList(values, optionName, allowed) {
+    for (const value of values) {
+        if (!allowed.includes(value)) {
+            throw new ValidationError(`Invalid ${optionName}: "${value}" is not one of ${allowed.join("/")}`);
+        }
+    }
+    return maybeArray(values);
+}
 export function toTimestamp13(value) {
     if (value === undefined)
         return undefined;
@@ -94,6 +105,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)) {
@@ -285,13 +285,30 @@ export class GangtiseClient {
             total,
             list: requestedSize === undefined ? collected : collected.slice(0, requestedSize),
         };
-        if (failedPages.length > 0) {
+        // Unified completeness backstop. Whatever the cause — a failed/shape-broken page,
+        // a short later page (server page cap < maxPageSize), the MAX_PAGES cap, or `total`
+        // drifting mid-fetch — the result is partial. A short row count or a total drift each
+        // force it; so does any failedPages entry on its own — an over-returning sibling page
+        // can lift the row count back to target and mask the hole (short would read false), yet
+        // the failedPages branch below still writes "results are partial" to stderr, so the flag
+        // must agree. printData maps partial → exit 3 so a script can't read a truncated export
+        // as complete. The cap and drift branches above already warned on stderr; failedPages
+        // warns below.
+        const short = collected.length < target;
+        if (short || totalDrift || failedPages.length > 0)
             out.partial = true;
+        if (failedPages.length > 0) {
             out.failedPages = failedPages.map((p) => ({ from: p.from, size: p.size }));
             const detail = firstError instanceof Error ? `: ${firstError.message}` : "";
             const skippedHint = aborted ? " A page hit a non-retryable error (e.g. rate limit); remaining pages were skipped." : "";
             process.stderr.write(`[gangtise] warning: ${failedPages.length}/${pageRequests.length} pages not fetched${detail}; results are partial — got ${collected.length}/${total} rows (see failedPages).${skippedHint}\n`);
         }
+        else if (short && !truncatedByPageCap && !totalDrift) {
+            // A short later page with no failure, cap, or drift to explain it: the server
+            // simply delivered fewer rows than `total` promised. Warn so an interactive run
+            // sees why the result is partial (the other causes each warn on their own path).
+            process.stderr.write(`[gangtise] warning: server returned ${collected.length} of ${total} rows (a later page came back short); results may be incomplete\n`);
+        }
         return out;
     }
     async login() {
@@ -309,9 +326,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".
@@ -325,12 +346,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);
@@ -339,13 +370,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);
             }
@@ -404,6 +435,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`);
@@ -413,14 +447,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);
                 }
@@ -437,13 +471,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)

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 = {
@@ -168,6 +173,26 @@ const ENDPOINT_DEFS = {
         kind: "download",
         description: "Download WeChat official account article (txt/HTML)",
     },
+    "insight.qa.list": {
+        method: "POST",
+        // The literal '&' is the vendor's path segment (Q&A-data), not a query separator.
+        path: "/application/open-insight/Q&A-data/getList",
+        kind: "json",
+        description: "List investor Q&A (conference/interactive/survey) for a security",
+        pagination: { enabled: true, maxPageSize: 500 },
+    },
+    "insight.report-image.list": {
+        method: "POST",
+        path: "/application/open-insight/report-image/getList",
+        kind: "json",
+        description: "Search research report images by keyword (returns chunkId + metadata)",
+    },
+    "insight.report-image.download": {
+        method: "GET",
+        path: "/application/open-insight/report-image/download/file",
+        kind: "download",
+        description: "Download a research report image by chunkId",
+    },
     // ─── reference ───
     "reference.securities-search": {
         method: "POST",
@@ -187,6 +212,12 @@ const ENDPOINT_DEFS = {
         kind: "json",
         description: "Search institution IDs by keyword (domestic broker / foreign / lead / opinion institution)",
     },
+    "reference.official-account-search": {
+        method: "POST",
+        path: "/application/open-reference/officialAccount/search",
+        kind: "json",
+        description: "Search official account (WeChat public account) IDs by name / institution / category",
+    },
     "reference.constant-category": {
         method: "GET",
         path: "/application/open-reference/constants/category",
@@ -382,18 +413,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",
@@ -412,12 +446,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",
@@ -431,12 +467,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",
@@ -563,3 +601,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

@@ -16,6 +16,7 @@ const ERROR_HINTS = {
     "999995": "当前账号积分不足。",
     "900002": "请求缺少 uid。",
     "900001": "请求参数为空或缺少必填项。",
+    "100003": "参数值非法——服务端不会指明是哪个参数，多为枚举参数拼写或取值超范围（如 --source / --question-category / --answer-important），对照命令 --help 列出的合法值检查。",
     "0000001008": "Token 已失效（多为他处登录挤掉本会话）；有 AK/SK 时 CLI 会自动重新登录重试一次，否则请重新登录。",
     "8000014": "GANGTISE_ACCESS_KEY 错误。",
     "8000015": "GANGTISE_SECRET_KEY 错误。",
@@ -34,12 +35,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/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

@@ -27,16 +27,28 @@ export function isFullMarket(body, fullMarketValue) {
 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 = [];
     let cursor = start.getTime();
     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;
@@ -93,6 +105,11 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
         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()) {
@@ -104,13 +121,31 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
     // every shard on the first rejection.
     const failedShards = [];
     let firstError = null;
+    let aborted = false;
     const results = await runWithConcurrency(shards, config.concurrency ?? PAGE_CONCURRENCY, async (shard) => {
+        // A prior shard hit a hard error (rate limit, no-perm, retries exhausted). Stop
+        // dispatching the rest rather than burning quota into the same failure; record them
+        // as failed so the merged result is flagged partial. Mirrors requestPaginated.
+        if (aborted) {
+            failedShards.push(shard);
+            return null;
+        }
         try {
-            return await client.call(endpointKey, { ...allMarketBody, startDate: shard.startDate, endDate: shard.endDate });
+            const res = await client.call(endpointKey, { ...allMarketBody, startDate: shard.startDate, endDate: shard.endDate });
+            // A shard that resolves but carries no `list` array is shape-broken (an error
+            // object, a truncated envelope) — its rows are missing. Treat it exactly like a
+            // thrown shard so the result is marked partial, not silently short. Unlike a hard
+            // error this doesn't abort the fan-out: one malformed shard isn't systemic.
+            if (!(res && typeof res === "object" && Array.isArray(res.list))) {
+                failedShards.push(shard);
+                return null;
+            }
+            return res;
         }
         catch (error) {
             if (!firstError)
                 firstError = error;
+            aborted = true;
             failedShards.push(shard);
             return null;
         }

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gangtise-openapi-cli",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "CLI for Gangtise OpenAPI",
   "license": "MIT",
   "repository": {
@@ -23,6 +23,7 @@
     "README.md"
   ],
   "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "tsc -p tsconfig.json",
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
@@ -30,11 +31,11 @@
     "prepare": "node scripts/prepare.cjs && npm run build"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20.18.1"
   },
   "dependencies": {
     "commander": "^14.0.0",
-    "undici": "^7.16.0"
+    "undici": "^7.28.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.43",