gangtise-openapi-cli 0.16.0 → 0.17.1

package/README.md

@@ -4,6 +4,16 @@
 
 ## Changelog
 
+### 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 时曾未生效）
+
 ### v0.16.0 — 2026-06-12
 
 **新增接口（参考数据 · 常量查询，均免积分）**
@@ -16,7 +26,7 @@
 **接口变更（Breaking）**
 - 移除已被新 API 覆盖的 6 个本地 lookup 子命令及静态数据：`lookup research-area / industry / region / announcement-category / theme-id / industry-code list`，请改用 `reference constant-list` / `reference concept-search` / `reference sector-constituents`（申万行业代码 `821xxx.SWI` 全量：`sector-constituents --sector-id 2000000014`，即申万一级行业指数板块）
 - `lookup` 仅保留 2 个 API 未覆盖的本地表：`broker-org` / `meeting-org`
-- 路演/调研/策略会/论坛 list 新增 `--location <id>` 按城市过滤（domesticCity 常量 ID；实测 2026-06-12 服务端过滤暂未生效）
+- 路演/调研/策略会/论坛 list 新增 `--location <id>` 按城市过滤（domesticCity 常量 ID；服务端过滤 v0.17.0 起已生效）
 
 ### v0.15.0 — 2026-05-29
 
@@ -322,7 +332,8 @@ cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
 
 ```bash
 gangtise reference constant-category                              # 有哪些常量分类、各用于哪些参数
-gangtise reference constant-list --category citicIndustry         # 中信行业（--industry / --research-area）
+gangtise reference constant-list --category citicIndustry         # 中信行业（--industry 通用）
+gangtise reference constant-list --category gangtiseIndustry      # Gangtise 行业 + 方向（--research-area 用）
 gangtise reference constant-list --category swIndustry            # 申万行业
 gangtise reference constant-list --category regionCategory        # 外资研报区域
 gangtise reference constant-list --category aShareAnnouncementCategory  # A股公告分类（树形）
@@ -334,7 +345,7 @@ gangtise lookup meeting-org list     # 会议机构（本地表）
 再调用业务命令：
 
 ```bash
-gangtise insight opinion list --industry 104710000
+gangtise insight opinion list --industry 100800128
 gangtise insight summary list --institution C100000017
 gangtise quote day-kline --security 600519.SH --start-date 2025-03-01 --end-date 2025-03-12
 gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
@@ -408,10 +419,10 @@ gangtise auth status
 gangtise insight research list --start-time "2026-04-01 00:00:00" --end-time "2026-04-09 23:59:59"
 
 # 无时间范围 → 默认 --size 200
-gangtise insight research list --industry 104270000 --category company --llm-tag inDepth --rating buy
+gangtise insight research list --industry 100800126 --category company --llm-tag inDepth --rating buy
 
 # 多值 List 模式：一次查多家券商 + 多个行业 + 多个评级
-gangtise insight research list --broker C100000027 --broker C100000014 --industry 104340000 --industry 104370000 --rating buy --rating overweight --format json
+gangtise insight research list --broker C100000027 --broker C100000014 --industry 100800119 --industry 100800118 --rating buy --rating overweight --format json
 
 gangtise insight opinion list --keyword AI
 gangtise insight summary list --keyword 算力
@@ -441,7 +452,7 @@ gangtise insight foreign-opinion list --keyword "自动驾驶" --region us --ran
 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 list --keyword "肿瘤" --industry 100800118 --format json
 gangtise insight independent-opinion download --independent-opinion-id 207051900018372 --file-type 2
 
 # 纪要下载（会议平台来源可选 HTML 格式）

package/dist/src/cli.js

@@ -144,17 +144,57 @@ addTimeFilters(summary.command("list").option("--search-type <number>", "Search
     categoryList: maybeArray(options.category), marketList: maybeArray(options.market), participantRoleList: maybeArray(options.participantRole),
 }), { endpointKey: "insight.summary.list", idField: "summaryId" }));
 addDownloadCommand(summary, { endpointKey: "insight.summary.download", idOption: "--summary-id", idField: "summaryId", fallbackPrefix: "summary", fileType: { description: "File type: 1=original(default) 2=HTML; only affects meeting platform summaries" }, titleListEndpoint: "insight.summary.list" });
-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("--location <id>", "Location ID (domesticCity constant, via 'reference constant-list')", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call(endpointKey, {
-    from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword,
-    researchAreaList: maybeArray(options.researchArea), institutionList: maybeArray(options.institution), securityList: maybeArray(options.security),
-    categoryList: maybeArray(options.category), marketList: maybeArray(options.market), participantRoleList: maybeArray(options.participantRole),
-    brokerTypeList: maybeArray(options.brokerType), objectList: maybeArray(options.object), permission: options.permission.length ? options.permission : undefined,
-    locationList: maybeArray(options.location),
-})));
-addScheduleList(roadshow, "insight.roadshow.list");
-addScheduleList(siteVisit, "insight.site-visit.list");
-addScheduleList(strategy, "insight.strategy.list");
-addScheduleList(forum, "insight.forum.list");
+const addScheduleList = (command, endpointKey, fields) => {
+    const list = command.command("list");
+    if (fields.researchArea)
+        list.option("--research-area <id>", "Research area ID (constant-list category gangtiseIndustry: 1008001xx industries + 122000xxx macro/strategy/fixed-income/quant/overseas directions)", collectList, []);
+    if (fields.institution)
+        list.option("--institution <id>", "Lead institution ID", collectList, []);
+    if (fields.security)
+        list.option("--security <code>", "Security code", collectList, []);
+    if (fields.object)
+        list.option("--object <type>", "Object type: company/industry", collectList, []);
+    if (fields.category)
+        list.option("--category <name>", fields.category, collectList, []);
+    if (fields.market)
+        list.option("--market <name>", fields.market, collectList, []);
+    if (fields.participantRole)
+        list.option("--participant-role <name>", "Participant role: management/expert", collectList, []);
+    if (fields.brokerType)
+        list.option("--broker-type <name>", "Lead broker type: cnBroker/otherBroker", collectList, []);
+    if (fields.permission)
+        list.option("--permission <number>", "Permission: 1=public 2=private", collectNumberList, []);
+    if (fields.location)
+        list.option("--location <id>", "Location ID (domesticCity constant, via 'reference constant-list')", collectList, []);
+    list.option("--format <format>", "Output format", "table").option("--output <path>", "Output path");
+    addTimeFilters(list).action((options) => emit(options, (client) => client.call(endpointKey, {
+        from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword,
+        researchAreaList: fields.researchArea ? maybeArray(options.researchArea) : undefined,
+        institutionList: fields.institution ? maybeArray(options.institution) : undefined,
+        securityList: fields.security ? maybeArray(options.security) : undefined,
+        objectList: fields.object ? maybeArray(options.object) : undefined,
+        categoryList: fields.category ? maybeArray(options.category) : undefined,
+        marketList: fields.market ? maybeArray(options.market) : undefined,
+        participantRoleList: fields.participantRole ? maybeArray(options.participantRole) : undefined,
+        brokerTypeList: fields.brokerType ? maybeArray(options.brokerType) : undefined,
+        permission: fields.permission && options.permission?.length ? options.permission : undefined,
+        locationList: fields.location ? maybeArray(options.location) : undefined,
+    })));
+};
+addScheduleList(roadshow, "insight.roadshow.list", {
+    researchArea: true, institution: true, security: true, location: true,
+    category: "Roadshow type: earningsCall/strategyMeeting/companyAnalysis/industryAnalysis/fundRoadshow",
+    market: "Market: aShares/hkStocks/usChinaConcept/usStocks",
+    participantRole: true, brokerType: true, permission: true,
+});
+addScheduleList(siteVisit, "insight.site-visit.list", {
+    researchArea: true, institution: true, security: true, location: true, object: true,
+    category: "Site-visit form: single/series",
+    market: "Market: aShares/hkStocks/usChinaConcept",
+    permission: true,
+});
+addScheduleList(strategy, "insight.strategy.list", { institution: true, location: true });
+addScheduleList(forum, "insight.forum.list", { researchArea: true, location: true });
 addTimeFilters(research.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("--broker <id>", "Broker ID", collectList, []).option("--security <code>", "Security code", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--category <name>", "Report category", 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("--source <type>", "Source type", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.research.list", {
     from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword,
     searchType: parseNumberOption(options.searchType, "--search-type", { integer: true, min: 1 }), rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }),
@@ -173,11 +213,11 @@ addTimeFilters(foreignReport.command("list").option("--search-type <number>", "S
     minReportPages: parseOptionalNumberOption(options.minPages, "--min-pages", { integer: true, min: 0 }), maxReportPages: parseOptionalNumberOption(options.maxPages, "--max-pages", { integer: true, min: 0 }),
 }), { endpointKey: "insight.foreign-report.list", idField: "reportId" }));
 addDownloadCommand(foreignReport, { endpointKey: "insight.foreign-report.download", idOption: "--report-id", idField: "reportId", fallbackPrefix: "foreign-report", fileType: { description: "File type: 1=PDF 2=Markdown 3=CN-PDF 4=CN-Markdown", default: "1" }, titleListEndpoint: "insight.foreign-report.list" });
-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((options) => emit(options, (client) => client.call("insight.announcement.list", {
+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("--category <id>", "Category ID", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.announcement.list", {
     from: parseFrom(options.from), size: parseSize(options.size),
     startTime: parseTimestamp13(options.startTime, "--start-time"), endTime: parseTimestamp13(options.endTime, "--end-time"),
     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), announcementTypeList: maybeArray(options.announcementType), categoryList: maybeArray(options.category),
+    securityList: maybeArray(options.security), categoryList: maybeArray(options.category),
 }), { endpointKey: "insight.announcement.list", idField: "announcementId" }));
 addDownloadCommand(announcement, { endpointKey: "insight.announcement.download", idOption: "--announcement-id", idField: "announcementId", fallbackPrefix: "announcement", fileType: { description: "File type: 1=PDF 2=Markdown", default: "1" }, titleListEndpoint: "insight.announcement.list" });
 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((options) => emit(options, (client) => client.call("insight.announcement-hk.list", {
@@ -221,10 +261,19 @@ 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((options) => emit(options, (client) => callKlineWithSharding(client, "quote.day-kline", buildQuoteKlineBody(options), { shardDays: 1 })));
-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((options) => emit(options, (client) => callKlineWithSharding(client, "quote.day-kline-hk", buildQuoteKlineBody(options), { shardDays: 2 })));
-quote.command("day-kline-us").option("--security <code>", "Security code (US stock: e.g. AAPL.O, 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((options) => emit(options, (client) => callKlineWithSharding(client, "quote.day-kline-us", buildQuoteKlineBody(options), { shardDays: 1 })));
-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((options) => emit(options, (client) => callKlineWithSharding(client, "quote.index-day-kline", buildQuoteKlineBody(options), { shardDays: 30 })));
+const addKlineCommand = (name, endpointKey, securityHelp, shardDays) => quote.command(name)
+    .option("--security <code>", securityHelp, 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((options) => emit(options, (client) => callKlineWithSharding(client, endpointKey, buildQuoteKlineBody(options), { shardDays })));
+addKlineCommand("day-kline", "quote.day-kline", "Security code (A-share: .SH/.SZ/.BJ, or 'all' for full market)", 1);
+addKlineCommand("day-kline-hk", "quote.day-kline-hk", "Security code (HK stock: .HK, or 'all' for full market)", 2);
+addKlineCommand("day-kline-us", "quote.day-kline-us", "Security code (US stock: e.g. AAPL.O, or 'all' for full market)", 1);
+addKlineCommand("index-day-kline", "quote.index-day-kline", "Index code (.SH/.SZ/.BJ, or 'all' for full market)", 30);
 quote.command("minute-kline").option("--security <code>", "Security code (A-share only: .SH/.SZ/.BJ)").option("--start-time <datetime>", "Start time (yyyy-MM-dd HH:mm:ss)").option("--end-time <datetime>", "End time (yyyy-MM-dd HH:mm:ss)").option("--limit <number>", "Max rows per request (default: 5000, max: 10000)").option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("quote.minute-kline", { securityCode: options.security, startTime: options.startTime, endTime: options.endTime, limit: parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1 }), fieldList: maybeArray(options.field) })));
 quote.command("realtime").description("Realtime quote snapshot (A-share / HK / US)").option("--security <code>", "Security code (e.g. 600519.SH / 00700.HK / AAPL.O), or market keyword: aShares / hkStocks / usStocks", collectList, []).option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("quote.realtime", { securityList: maybeArray(options.security), fieldList: maybeArray(options.field) })));
 program.addCommand(quote);

package/dist/src/core/client.js

@@ -165,8 +165,10 @@ export class GangtiseClient {
             nextFrom += size;
         }
         const MAX_PAGES = 1000;
+        let truncatedByPageCap = false;
         if (pageRequests.length + 1 > MAX_PAGES) {
             pageRequests.length = MAX_PAGES - 1;
+            truncatedByPageCap = true;
         }
         let unexpectedShape = false;
         let totalDrift = false;
@@ -195,6 +197,12 @@ export class GangtiseClient {
         if (totalDrift && isVerbose()) {
             process.stderr.write(`[gangtise] warning: 'total' changed across pages (data shifted during fetch)\n`);
         }
+        // Always surface a cap-induced truncation (not gated on verbose): the user
+        // asked for everything and is silently getting a subset, mirroring the
+        // partial-result warning in quoteSharding.
+        if (truncatedByPageCap) {
+            process.stderr.write(`[gangtise] warning: hit the ${MAX_PAGES}-page safety cap; fetched ${collected.length} of ${total} rows. Narrow the query (e.g. a shorter date range) or pass --size to fetch a bounded subset.\n`);
+        }
         return {
             ...firstPage,
             total,
@@ -330,7 +338,16 @@ export class GangtiseClient {
             // Stream directly to disk when caller already knows the destination
             if (options?.streamTo) {
                 await fs.mkdir(path.dirname(options.streamTo), { recursive: true });
-                await pipeline(response.body, createWriteStream(options.streamTo));
+                try {
+                    await pipeline(response.body, createWriteStream(options.streamTo));
+                }
+                catch (error) {
+                    // A mid-stream failure leaves a truncated file on disk; remove it so a
+                    // failed download never looks like a complete one. withRetry may still
+                    // replay the request (the next attempt re-creates the file).
+                    await fs.unlink(options.streamTo).catch(() => { });
+                    throw error;
+                }
                 logTiming(`GET ${endpoint.path} (stream)`, Date.now() - startedAt, `${response.statusCode}`);
                 return { contentType, filename, savedPath: options.streamTo };
             }

package/dist/src/version.js

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

package/package.json

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