gangtise-openapi-cli 0.11.1 → 0.12.0

package/README.md

@@ -2,6 +2,49 @@
 
 一个可直接调用 Gangtise OpenAPI 获取金融数据的命令行工具，同时提供Agent Skill。
 
+## Changelog
+
+### v0.12.0 — 2026-05-10
+
+**性能 / 架构**
+- 翻页并行化：自动翻页接口拉到首页 `total` 后，剩余页通过 `Promise.all` 并发请求（默认并发 5，`GANGTISE_PAGE_CONCURRENCY` 可调）
+- 共享 `undici.Agent`：所有请求复用连接池（keep-alive 60s，max 16 连接），避免重复 TLS 握手
+- 流式下载：`--output` 指定时二进制响应直接 `pipeline` 到磁盘，不再走内存 `Uint8Array`
+- 流式输出：`--format jsonl/csv --output xxx` 且 ≥1000 行时逐行写盘
+- Token 内存缓存：Token 在进程内不再每次读盘
+- 自动重试：5xx / `ECONNRESET` / `ETIMEDOUT` / `999999` 自动指数退避重试 2 次
+- Token 自愈：8000014/8000015 自动重新登录并重试一次
+- 异步轮询退避：`earnings-review` / `viewpoint-debate` 轮询从固定 15s 改为 5→8→13→20→30s 指数退避
+- K线自动分片：`quote day-kline --security all` 等全市场查询自动按日期切分并发执行
+- 标题缓存：原"读全文→改→写全文"改为内存快照 + 原子写入（temp+rename）
+
+**调试 / 可观测性**
+- 新增 `--verbose` / `GANGTISE_VERBOSE=1`：打印每个请求的耗时、状态码、响应字节数到 stderr
+
+### v0.11.1 — 2026-05-10
+
+**新增接口**
+- `insight announcement-hk list/download` — 查询/下载港股公告
+- `insight foreign-opinion list` — 查询外资机构观点（外资券商）
+- `insight independent-opinion list/download` — 查询/下载外资独立分析师观点
+- `reference securities-search` — GTS Code 搜索（按名称/代码/拼音多维度匹配证券）
+
+**接口变更**
+- `insight summary download` 新增可选 `--file-type`（`1`=原始内容 / `2`=HTML），仅影响来源为会议平台的纪要
+- `insight announcement list/download` 名称调整为"查询A股公告列表/下载A股公告文件"（路径不变）
+- `insight opinion list` 名称调整为"查询内资机构观点列表"（路径不变）
+
+### v0.11.0 — 2026-04-17
+
+- 新增 `ai viewpoint-debate` / `viewpoint-debate-check` — 观点PK（异步）
+- 新增 `ai management-discuss-announcement` / `management-discuss-earnings-call` — 管理层讨论
+
+### v0.10.9 — 2026-04-10
+
+- 修复信封检测、版本更新检查、端点去重
+- 新增 `quote index-day-kline` 指数日K线
+- 新增 `vault wechat-message-list` / `wechat-chatroom-list` 群消息
+
 ## 首次安装
 
 ```bash
@@ -46,9 +89,14 @@ export GANGTISE_ACCESS_KEY="your-ak"
 export GANGTISE_SECRET_KEY="your-sk"
 export GANGTISE_BASE_URL="https://open.gangtise.com"
 export GANGTISE_TOKEN="Bearer xxx"
+
+# 性能/调试可选项
+export GANGTISE_PAGE_CONCURRENCY=5     # 翻页并发数（默认 5）
+export GANGTISE_VERBOSE=1              # 打印每个请求的耗时与字节数
+export GANGTISE_TIMEOUT_MS=30000       # 请求超时（默认 30s）
 ```
 
-如果没有 `GANGTISE_TOKEN`，CLI 会自动调用 token 接口并缓存到本地（`~/.config/gangtise/token.json`，权限 0600）。
+如果没有 `GANGTISE_TOKEN`，CLI 会自动调用 token 接口并缓存到本地（`~/.config/gangtise/token.json`，权限 0600）。Token 失效（8000014/8000015）时会自动重新登录并重试一次。
 
 
 ## AI Agent Skill
@@ -102,15 +150,19 @@ cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
 |------|--------|------|
 | **Auth** | `login` / `status` | 认证登录、状态查询 |
 | **Lookup** | `research-area list` / `broker-org list` / `meeting-org list` / `industry list` / `industry-code list` / `region list` / `announcement-category list` / `theme-id list` | 枚举速查（内置，无需额外文档） |
-| **Insight** | `opinion list` | 首席观点 |
-| | `summary list` / `download` | 纪要（含下载） |
+| **Insight** | `opinion list` | 内资机构观点 |
+| | `summary list` / `download` | 纪要（含下载，支持 `--file-type` 选原始/HTML） |
 | | `roadshow list` | 路演 |
 | | `site-visit list` | 调研 |
 | | `strategy list` | 策略 |
 | | `forum list` | 论坛 |
 | | `research list` / `download` | 研报（含 Markdown 下载） |
 | | `foreign-report list` / `download` | 外资研报（含中文翻译下载） |
-| | `announcement list` / `download` | 公告（含 Markdown 下载） |
+| | `announcement list` / `download` | A股公告（含 Markdown 下载） |
+| | `announcement-hk list` / `download` | 港股公告（含下载） |
+| | `foreign-opinion list` | 外资机构观点 |
+| | `independent-opinion list` / `download` | 外资独立分析师观点（含原文/翻译HTML下载） |
+| **Reference** | `securities-search` | GTS Code 搜索（按名称/代码/拼音匹配） |
 | **Quote** | `day-kline` / `day-kline-hk` | A股/港股日K线 |
 | | `index-day-kline` | 沪深京指数日K线 |
 | | `minute-kline` | A股分钟K线 |
@@ -148,6 +200,7 @@ cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
 - `gangtise fundamental ...`
 - `gangtise ai ...`
 - `gangtise vault ...`
+- `gangtise reference ...`
 - `gangtise raw call ...`
 
 ## 推荐工作流
@@ -173,6 +226,18 @@ gangtise quote day-kline --security 600519.SH --start-date 2025-03-01 --end-date
 gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 ```
 
+## 性能特性
+
+- **并发翻页**：自动翻页接口的首页拿到 `total` 后，剩余页用 `Promise.all` 并发拉取（默认并发数 5，可通过 `GANGTISE_PAGE_CONCURRENCY` 调整）。20 页查询从串行 ~10s 降到 ~2s。
+- **HTTP keep-alive**：所有请求复用同一个 `undici.Agent`（连接池 16），避免重复 TLS 握手。
+- **流式下载**：指定 `--output` 时，二进制响应（PDF 等）直接 `pipeline` 到磁盘，不经过内存缓冲；50MB PDF 内存占用近乎为零。
+- **流式输出**：`jsonl`/`csv` 格式且 `--output` 指定时，超过 1000 行自动切换为逐行写盘，避免一次性构建百 MB 字符串。
+- **自动重试**：5xx / `ECONNRESET` / `ETIMEDOUT` / `999999` 系统错误自动指数退避重试 2 次。
+- **Token 自愈**：调用返回 8000014/8000015 时自动强制刷新 Token 并重试一次。
+- **K线自动分片**：`quote day-kline --security all` 等全市场查询自动按日期切分（A股 2 天/片、HK 3 天/片、指数 30 天/片），并发执行后合并结果。
+- **Token 内存缓存**：Token 在进程内存中缓存，避免每次请求读盘。
+- **`--verbose`**：打印每个请求的方法、路径、状态码、耗时和响应大小到 stderr，方便定位慢查询。
+
 ## 自动翻页
 
 以下列表接口会自动翻页：
@@ -185,6 +250,9 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 - `insight research list`
 - `insight foreign-report list`
 - `insight announcement list`
+- `insight announcement-hk list`
+- `insight foreign-opinion list`
+- `insight independent-opinion list`
 - `ai security-clue`
 - `vault drive-list`
 - `vault record-list`
@@ -249,6 +317,31 @@ gangtise insight announcement download --announcement-id 123456 --file-type 2
 gangtise insight research download --report-id 12345 --output ./report.pdf
 
 gangtise insight roadshow list --institution C100000017
+
+# 港股公告
+gangtise insight announcement-hk list --security 01913.HK --rank-type 2 --size 20 --format json
+gangtise insight announcement-hk download --announcement-id ANN2026040200012345
+
+# 外资机构观点
+gangtise insight foreign-opinion list --keyword "自动驾驶" --region us --rank-type 2 --format json
+gangtise insight foreign-opinion list --security APP.O --rating buy --format json
+
+# 外资独立观点
+gangtise insight independent-opinion list --keyword "肿瘤" --industry 104370000 --format json
+gangtise insight independent-opinion download --independent-opinion-id 207051900018372 --file-type 2
+
+# 纪要下载（会议平台来源可选 HTML 格式）
+gangtise insight summary download --summary-id 4906813 --file-type 2
+```
+
+### Reference
+
+```bash
+# GTS Code 搜索：按公司名/代码/拼音查证券代码
+gangtise reference securities-search --keyword "贵州茅台" --category stock
+gangtise reference securities-search --keyword "600519" --category stock
+gangtise reference securities-search --keyword gzmt --top 5
+gangtise reference securities-search --keyword "银行" --category stock --category index
 ```
 
 ### Quote

package/dist/src/cli.js

@@ -4,6 +4,7 @@ import { checkAsyncContent, pollAsyncContent, POLL_MAX_ATTEMPTS } from "./core/a
 import { readTokenCache } from "./core/auth.js";
 import { collectKeyValue, collectList, collectNumberList, maybeArray, parseFrom, parseNumberOption, parseOptionalNumberOption, parseSize, parseTimestamp13 } from "./core/args.js";
 import { buildQuoteKlineBody, buildWechatChatroomListBody, buildWechatMessageListBody } from "./core/commandBodies.js";
+import { callKlineWithSharding } from "./core/quoteSharding.js";
 import { loadConfig } from "./core/config.js";
 import { resolveTitle, saveDownloadResult } from "./core/download.js";
 import { ENDPOINTS } from "./core/endpoints.js";
@@ -16,6 +17,21 @@ async function createClient() {
     const { GangtiseClient } = await import("./core/client.js");
     return new GangtiseClient(loadConfig());
 }
+/**
+ * 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);
+ * otherwise we buffer and let the caller resolve a friendly title.
+ */
+async function runDownload(client, endpointKey, query, options) {
+    if (options.output) {
+        const result = await client.call(endpointKey, undefined, query, { streamTo: options.output });
+        await saveDownloadResult(result, options.fallbackName, options.output);
+        return;
+    }
+    const result = await client.call(endpointKey, undefined, query);
+    const resolved = options.resolveOutputPath ? await options.resolveOutputPath(result) : undefined;
+    await saveDownloadResult(result, options.fallbackName, resolved);
+}
 function addTimeFilters(command) {
     return command
         .option("--from <number>", "Starting offset", "0")
@@ -24,9 +40,18 @@ function addTimeFilters(command) {
         .option("--end-time <datetime>", "End time")
         .option("--keyword <keyword>", "Keyword");
 }
+import { setVerbose } from "./core/transport.js";
 import { CLI_VERSION } from "./version.js";
 const program = new Command();
-program.name("gangtise").description("Gangtise OpenAPI CLI").version(CLI_VERSION);
+program
+    .name("gangtise")
+    .description("Gangtise OpenAPI CLI")
+    .version(CLI_VERSION)
+    .option("--verbose", "Print per-request timings to stderr (also: GANGTISE_VERBOSE=1)")
+    .hook("preAction", (thisCommand) => {
+    if (thisCommand.opts().verbose)
+        setVerbose(true);
+});
 program
     .command("auth")
     .description("Authentication commands")
@@ -88,6 +113,9 @@ const forum = new Command("forum");
 const research = new Command("research");
 const foreignReport = new Command("foreign-report");
 const announcement = new Command("announcement");
+const announcementHk = new Command("announcement-hk");
+const foreignOpinion = new Command("foreign-opinion");
+const independentOpinion = new Command("independent-opinion");
 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(async (options) => {
     const client = await createClient();
     await printData(await client.call("insight.opinion.list", {
@@ -106,11 +134,16 @@ addTimeFilters(summary.command("list").option("--search-type <number>", "Search
         categoryList: maybeArray(options.category), marketList: maybeArray(options.market), participantRoleList: maybeArray(options.participantRole),
     }), parseOutputFormat(options.format), options.output, { endpointKey: "insight.summary.list", idField: "summaryId" });
 });
-summary.command("download").requiredOption("--summary-id <id>").option("--output <path>").action(async (options) => {
+summary.command("download").requiredOption("--summary-id <id>").option("--file-type <number>", "File type: 1=original(default) 2=HTML; only affects meeting platform summaries").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    const result = await client.call("insight.summary.download", undefined, { summaryId: options.summaryId });
-    const title = options.output ? undefined : await resolveTitle(client, result, "insight.summary.list", "summaryId", options.summaryId);
-    await saveDownloadResult(result, `summary-${options.summaryId}`, options.output ?? title);
+    const qp = { summaryId: options.summaryId };
+    if (options.fileType)
+        qp.fileType = parseNumberOption(options.fileType, "--file-type", { integer: true, min: 1 });
+    await runDownload(client, "insight.summary.download", qp, {
+        output: options.output,
+        fallbackName: `summary-${options.summaryId}`,
+        resolveOutputPath: (result) => resolveTitle(client, result, "insight.summary.list", "summaryId", options.summaryId),
+    });
 });
 const addScheduleList = (command, endpointKey) => addTimeFilters(command.command("list").option("--research-area <id>", "Research area", collectList, []).option("--institution <id>", "Institution ID", collectList, []).option("--security <code>", "Security code", collectList, []).option("--category <name>", "Category", collectList, []).option("--market <name>", "Market", collectList, []).option("--participant-role <name>", "Participant role", collectList, []).option("--broker-type <name>", "Broker type", collectList, []).option("--object <type>", "Object type: company/industry", collectList, []).option("--permission <number>", "Permission", collectNumberList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action(async (options) => {
     const client = await createClient();
@@ -138,9 +171,11 @@ addTimeFilters(research.command("list").option("--search-type <number>", "Search
 });
 research.command("download").requiredOption("--report-id <id>").option("--file-type <number>", "File type: 1=PDF 2=Markdown", "1").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    const result = await client.call("insight.research.download", undefined, { reportId: options.reportId, fileType: parseNumberOption(options.fileType, "--file-type", { integer: true, min: 1 }) });
-    const title = options.output ? undefined : await resolveTitle(client, result, "insight.research.list", "reportId", options.reportId);
-    await saveDownloadResult(result, `research-${options.reportId}`, options.output ?? title);
+    await runDownload(client, "insight.research.download", { reportId: options.reportId, fileType: parseNumberOption(options.fileType, "--file-type", { integer: true, min: 1 }) }, {
+        output: options.output,
+        fallbackName: `research-${options.reportId}`,
+        resolveOutputPath: (result) => resolveTitle(client, result, "insight.research.list", "reportId", options.reportId),
+    });
 });
 addTimeFilters(foreignReport.command("list").option("--search-type <number>", "Search type: 1=title 2=fulltext", "1").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--security <code>", "Security code", collectList, []).option("--region <id>", "Region ID", collectList, []).option("--category <name>", "Report category", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--broker <id>", "Broker ID", collectList, []).option("--llm-tag <tag>", "Semantic tag", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--min-pages <number>", "Min report pages").option("--max-pages <number>", "Max report pages").option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action(async (options) => {
     const client = await createClient();
@@ -155,9 +190,11 @@ addTimeFilters(foreignReport.command("list").option("--search-type <number>", "S
 });
 foreignReport.command("download").requiredOption("--report-id <id>").option("--file-type <number>", "File type: 1=PDF 2=Markdown 3=CN-PDF 4=CN-Markdown", "1").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    const result = await client.call("insight.foreign-report.download", undefined, { reportId: options.reportId, fileType: parseNumberOption(options.fileType, "--file-type", { integer: true, min: 1 }) });
-    const title = options.output ? undefined : await resolveTitle(client, result, "insight.foreign-report.list", "reportId", options.reportId);
-    await saveDownloadResult(result, `foreign-report-${options.reportId}`, options.output ?? title);
+    await runDownload(client, "insight.foreign-report.download", { reportId: options.reportId, fileType: parseNumberOption(options.fileType, "--file-type", { integer: true, min: 1 }) }, {
+        output: options.output,
+        fallbackName: `foreign-report-${options.reportId}`,
+        resolveOutputPath: (result) => resolveTitle(client, result, "insight.foreign-report.list", "reportId", options.reportId),
+    });
 });
 addTimeFilters(announcement.command("list").option("--search-type <number>", "Search type: 1=title 2=fulltext", "1").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--security <code>", "Security code", collectList, []).option("--announcement-type <type>", "Announcement type", collectList, []).option("--category <id>", "Category ID", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action(async (options) => {
     const client = await createClient();
@@ -170,9 +207,60 @@ addTimeFilters(announcement.command("list").option("--search-type <number>", "Se
 });
 announcement.command("download").requiredOption("--announcement-id <id>").option("--file-type <number>", "File type: 1=PDF 2=Markdown", "1").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    const result = await client.call("insight.announcement.download", undefined, { announcementId: options.announcementId, fileType: parseNumberOption(options.fileType, "--file-type", { integer: true, min: 1 }) });
-    const title = options.output ? undefined : await resolveTitle(client, result, "insight.announcement.list", "announcementId", options.announcementId);
-    await saveDownloadResult(result, `announcement-${options.announcementId}`, options.output ?? title);
+    await runDownload(client, "insight.announcement.download", { announcementId: options.announcementId, fileType: parseNumberOption(options.fileType, "--file-type", { integer: true, min: 1 }) }, {
+        output: options.output,
+        fallbackName: `announcement-${options.announcementId}`,
+        resolveOutputPath: (result) => resolveTitle(client, result, "insight.announcement.list", "announcementId", options.announcementId),
+    });
+});
+addTimeFilters(announcementHk.command("list").option("--search-type <number>", "Search type: 1=title 2=fulltext", "1").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--security <code>", "Security code (e.g. 01913.HK)", collectList, []).option("--category <id>", "Category ID", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action(async (options) => {
+    const client = await createClient();
+    await printData(await client.call("insight.announcement-hk.list", {
+        from: parseFrom(options.from), size: parseSize(options.size),
+        startTime: options.startTime, endTime: options.endTime,
+        searchType: parseNumberOption(options.searchType, "--search-type", { integer: true, min: 1 }),
+        rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }),
+        keyword: options.keyword,
+        securityList: maybeArray(options.security), categoryList: maybeArray(options.category),
+    }), parseOutputFormat(options.format), options.output, { endpointKey: "insight.announcement-hk.list", idField: "announcementId" });
+});
+announcementHk.command("download").requiredOption("--announcement-id <id>").option("--output <path>").action(async (options) => {
+    const client = await createClient();
+    await runDownload(client, "insight.announcement-hk.download", { announcementId: options.announcementId }, {
+        output: options.output,
+        fallbackName: `announcement-hk-${options.announcementId}`,
+        resolveOutputPath: (result) => resolveTitle(client, result, "insight.announcement-hk.list", "announcementId", options.announcementId),
+    });
+});
+addTimeFilters(foreignOpinion.command("list").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--security <code>", "Security code (e.g. UBER.N)", collectList, []).option("--region <code>", "Region code", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--broker <id>", "Broker ID", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action(async (options) => {
+    const client = await createClient();
+    await printData(await client.call("insight.foreign-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,
+        regionList: maybeArray(options.region), industryList: maybeArray(options.industry),
+        securityList: maybeArray(options.security), brokerList: maybeArray(options.broker),
+        ratingList: maybeArray(options.rating), ratingChangeList: maybeArray(options.ratingChange),
+    }), parseOutputFormat(options.format), options.output);
+});
+addTimeFilters(independentOpinion.command("list").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--security <code>", "Security code (e.g. GSK.N)", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action(async (options) => {
+    const client = await createClient();
+    await printData(await client.call("insight.independent-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,
+        industryList: maybeArray(options.industry), securityList: maybeArray(options.security),
+        ratingList: maybeArray(options.rating), ratingChangeList: maybeArray(options.ratingChange),
+    }), parseOutputFormat(options.format), options.output);
+});
+independentOpinion.command("download").requiredOption("--independent-opinion-id <id>").requiredOption("--file-type <number>", "File type: 1=original HTML 2=CN-translated HTML").option("--output <path>").action(async (options) => {
+    const client = await createClient();
+    await runDownload(client, "insight.independent-opinion.download", { independentOpinionId: options.independentOpinionId, fileType: parseNumberOption(options.fileType, "--file-type", { integer: true, min: 1 }) }, {
+        output: options.output,
+        fallbackName: `independent-opinion-${options.independentOpinionId}`,
+    });
 });
 insight.addCommand(opinion);
 insight.addCommand(summary);
@@ -183,19 +271,22 @@ insight.addCommand(forum);
 insight.addCommand(research);
 insight.addCommand(foreignReport);
 insight.addCommand(announcement);
+insight.addCommand(announcementHk);
+insight.addCommand(foreignOpinion);
+insight.addCommand(independentOpinion);
 program.addCommand(insight);
 const quote = new Command("quote").description("Quote APIs");
 quote.command("day-kline").option("--security <code>", "Security code (A-share: .SH/.SZ/.BJ, or 'all' for full market)", collectList, []).option("--start-date <date>", "Start date (default: 1 year before end-date)").option("--end-date <date>", "End date (default: latest)").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(async (options) => {
     const client = await createClient();
-    await printData(await client.call("quote.day-kline", buildQuoteKlineBody(options)), parseOutputFormat(options.format), options.output);
+    await printData(await callKlineWithSharding(client, "quote.day-kline", buildQuoteKlineBody(options), { shardDays: 2 }), parseOutputFormat(options.format), options.output);
 });
 quote.command("day-kline-hk").option("--security <code>", "Security code (HK stock: .HK, or 'all' for full market)", collectList, []).option("--start-date <date>", "Start date (default: 1 year before end-date)").option("--end-date <date>", "End date (default: latest)").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(async (options) => {
     const client = await createClient();
-    await printData(await client.call("quote.day-kline-hk", buildQuoteKlineBody(options)), parseOutputFormat(options.format), options.output);
+    await printData(await callKlineWithSharding(client, "quote.day-kline-hk", buildQuoteKlineBody(options), { shardDays: 3 }), parseOutputFormat(options.format), options.output);
 });
 quote.command("index-day-kline").option("--security <code>", "Index code (.SH/.SZ/.BJ, or 'all' for full market)", collectList, []).option("--start-date <date>", "Start date (default: 1 year before end-date)").option("--end-date <date>", "End date (default: latest)").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(async (options) => {
     const client = await createClient();
-    await printData(await client.call("quote.index-day-kline", buildQuoteKlineBody(options)), parseOutputFormat(options.format), options.output);
+    await printData(await callKlineWithSharding(client, "quote.index-day-kline", buildQuoteKlineBody(options), { shardDays: 30 }), parseOutputFormat(options.format), options.output);
 });
 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(async (options) => {
     const client = await createClient();
@@ -254,7 +345,10 @@ ai.command("knowledge-batch").requiredOption("--query <text>", "Query", collectL
 });
 ai.command("knowledge-resource-download").requiredOption("--resource-type <number>").requiredOption("--source-id <id>").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    await saveDownloadResult(await client.call("ai.knowledge-resource.download", undefined, { resourceType: parseNumberOption(options.resourceType, "--resource-type", { integer: true, min: 0 }), sourceId: options.sourceId }), `resource-${options.sourceId}`, options.output);
+    await runDownload(client, "ai.knowledge-resource.download", { resourceType: parseNumberOption(options.resourceType, "--resource-type", { integer: true, min: 0 }), sourceId: options.sourceId }, {
+        output: options.output,
+        fallbackName: `resource-${options.sourceId}`,
+    });
 });
 ai.command("security-clue").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").requiredOption("--start-time <datetime>").requiredOption("--end-time <datetime>").addOption(new Option("--query-mode <mode>").choices(["bySecurity", "byIndustry"]).makeOptionMandatory()).option("--gts-code <code>", "GTS code", collectList, []).option("--source <name>", "Source", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action(async (options) => {
     const client = await createClient();
@@ -358,6 +452,16 @@ ai.command("viewpoint-debate-check").requiredOption("--data-id <id>", "dataId fr
     const client = await createClient();
     await checkAsyncContent(client, "ai.viewpoint-debate.get-content", options.dataId, parseOutputFormat(options.format), options.output);
 });
+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(async (options) => {
+    const client = await createClient();
+    await printData(await client.call("reference.securities-search", {
+        keyword: options.keyword,
+        category: options.category.length ? options.category : undefined,
+        top: parseNumberOption(options.top, "--top", { integer: true, min: 1 }),
+    }), parseOutputFormat(options.format), options.output);
+});
+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(async (options) => {
     const client = await createClient();
@@ -365,9 +469,11 @@ vault.command("drive-list").option("--from <number>", "Starting offset", "0").op
 });
 vault.command("drive-download").requiredOption("--file-id <id>").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    const result = await client.call("vault.drive.download", undefined, { fileId: options.fileId });
-    const title = options.output ? undefined : await resolveTitle(client, result, "vault.drive.list", "fileId", options.fileId);
-    await saveDownloadResult(result, `file-${options.fileId}`, options.output ?? title);
+    await runDownload(client, "vault.drive.download", { fileId: options.fileId }, {
+        output: options.output,
+        fallbackName: `file-${options.fileId}`,
+        resolveOutputPath: (result) => resolveTitle(client, result, "vault.drive.list", "fileId", options.fileId),
+    });
 });
 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(async (options) => {
     const client = await createClient();
@@ -375,9 +481,11 @@ vault.command("record-list").option("--from <number>", "Starting offset", "0").o
 });
 vault.command("record-download").requiredOption("--record-id <id>").requiredOption("--content-type <type>", "Content type: original/asr/summary").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    const result = await client.call("vault.record.download", undefined, { recordId: options.recordId, contentType: options.contentType });
-    const title = options.output ? undefined : await resolveTitle(client, result, "vault.record.list", "recordId", options.recordId);
-    await saveDownloadResult(result, `record-${options.recordId}`, options.output ?? title);
+    await runDownload(client, "vault.record.download", { recordId: options.recordId, contentType: options.contentType }, {
+        output: options.output,
+        fallbackName: `record-${options.recordId}`,
+        resolveOutputPath: (result) => resolveTitle(client, result, "vault.record.list", "recordId", options.recordId),
+    });
 });
 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(async (options) => {
     const client = await createClient();
@@ -385,9 +493,11 @@ vault.command("my-conference-list").option("--from <number>", "Starting offset",
 });
 vault.command("my-conference-download").requiredOption("--conference-id <id>").requiredOption("--content-type <type>", "Content type: asr/summary").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    const result = await client.call("vault.my-conference.download", undefined, { conferenceId: options.conferenceId, contentType: options.contentType });
-    const title = options.output ? undefined : await resolveTitle(client, result, "vault.my-conference.list", "conferenceId", options.conferenceId);
-    await saveDownloadResult(result, `conference-${options.conferenceId}`, options.output ?? title);
+    await runDownload(client, "vault.my-conference.download", { conferenceId: options.conferenceId, contentType: options.contentType }, {
+        output: options.output,
+        fallbackName: `conference-${options.conferenceId}`,
+        resolveOutputPath: (result) => resolveTitle(client, result, "vault.my-conference.list", "conferenceId", options.conferenceId),
+    });
 });
 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("--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(async (options) => {
     const client = await createClient();
@@ -414,11 +524,14 @@ program.command("raw").description("Raw API calls").addCommand(new Command("call
             throw new ConfigError(`Invalid JSON in --body: ${options.body}`);
         }
     }
-    const data = await client.call(endpointKey, body, options.query);
     if (endpoint.kind === "download") {
-        await saveDownloadResult(data, "download.bin", options.output);
+        await runDownload(client, endpointKey, options.query, {
+            output: options.output,
+            fallbackName: "download.bin",
+        });
         return;
     }
+    const data = await client.call(endpointKey, body, options.query);
     await printData(data, parseOutputFormat(options.format), options.output);
 }));
 async function checkForUpdate(timeoutMs = 2000) {

package/dist/src/core/asyncContent.js

@@ -1,7 +1,15 @@
 import { ApiError } from "./errors.js";
 import { printData } from "./printer.js";
-export const POLL_MAX_ATTEMPTS = 12;
-export const POLL_DELAY_MS = 15_000;
+export const POLL_MAX_ATTEMPTS = 14;
+const POLL_INITIAL_DELAY_MS = 5_000;
+const POLL_MAX_DELAY_MS = 30_000;
+/** Total wait time stays close to the previous 12*15s=180s budget. */
+export const POLL_DELAY_MS = POLL_INITIAL_DELAY_MS;
+function nextDelayMs(attempt) {
+    // 5s, 8s, 13s, 20s, 30s, 30s, ...
+    const grown = POLL_INITIAL_DELAY_MS * 1.6 ** (attempt - 1);
+    return Math.min(POLL_MAX_DELAY_MS, Math.round(grown));
+}
 function isAsyncPending(error) {
     return error instanceof ApiError && error.code === "410110";
 }
@@ -23,8 +31,9 @@ export async function pollAsyncContent(client, getContentEndpoint, dataId, forma
                 throw error;
         }
         if (attempt < POLL_MAX_ATTEMPTS) {
-            process.stderr.write(`Attempt ${attempt}/${POLL_MAX_ATTEMPTS}: content not ready, retrying in 15s...\n`);
-            await new Promise(resolve => setTimeout(resolve, POLL_DELAY_MS));
+            const delay = nextDelayMs(attempt);
+            process.stderr.write(`Attempt ${attempt}/${POLL_MAX_ATTEMPTS}: content not ready, retrying in ${Math.round(delay / 1000)}s...\n`);
+            await new Promise(resolve => setTimeout(resolve, delay));
         }
     }
     return false;