gangtise-openapi-cli 0.51.0 → 0.52.0

package/dist/src/commands/fundamental.js

@@ -4,16 +4,16 @@ import { COSTLY_FETCH_CREDITS } from "../core/endpoints.js";
 import { normalizeRows } from "../core/normalize.js";
 import { parseOutputFormat } from "../core/output.js";
 import { printData } from "../core/printer.js";
-import { emit, withClient, flagIfLimitTruncated, field, required, date, list, format, output, query } from "./shared.js";
+import { emit, withClient, flagIfLimitTruncated, field, date, list, format, output, query, OUTPUT_HELP, SECURITY_CODE_FLAGS, SECURITY_CODE_HELP, oneSecurityCode, securityCode } from "./shared.js";
 export const fundamental = new Command("fundamental").description("Fundamental APIs");
-const addFinancialReport = (name, endpointKey, periodHelp = "Period") => query(fundamental, name, {
+const addFinancialReport = (name, endpointKey, periodHelp = "Period: q1/interim/q3/annual/latest") => query(fundamental, name, {
     endpoint: endpointKey,
     fields: [
-        required("--security-code <code>", undefined, "securityCode"),
+        securityCode(),
         date("--start-date <date>", "Start date (yyyy-MM-dd)", "startDate"),
         date("--end-date <date>", "End date (yyyy-MM-dd)", "endDate"),
-        list("--fiscal-year <year>", "Fiscal year", "fiscalYear"),
-        list("--period <period>", periodHelp, "period"),
+        list("--fiscal-year <year>", "Fiscal year; pass --period with it, or the latest report comes back whatever the year", "fiscalYear"),
+        list("--period <period>", `${periodHelp} (server default: latest)`, "period"),
         list("--report-type <type>", "Report type", "reportType"),
         list("--field <field>", "Field", "fieldList"),
         format(), output(),
@@ -33,7 +33,7 @@ addFinancialReport("cash-flow-us", "fundamental.cash-flow-us", "Period: q1/h1/q3
 query(fundamental, "main-business", {
     endpoint: "fundamental.main-business",
     fields: [
-        required("--security-code <code>", undefined, "securityCode"),
+        securityCode(),
         date("--start-date <date>", "Start date (yyyy-MM-dd)", "startDate"),
         date("--end-date <date>", "End date (yyyy-MM-dd)", "endDate"),
         field(new Option("--breakdown <type>", "Breakdown: product/industry/region").choices(["product", "industry", "region"]).default("product"), (v) => ({ breakdown: v })),
@@ -62,7 +62,7 @@ function firstRowTradeDate(data) {
     return typeof value === "string" ? value : undefined;
 }
 fundamental.command("valuation-analysis")
-    .requiredOption("--security-code <code>")
+    .requiredOption(SECURITY_CODE_FLAGS, SECURITY_CODE_HELP, oneSecurityCode)
     .addOption(new Option("--indicator <name>", "Indicator").choices(["peTtm", "pbMrq", "peg", "psTtm", "pcfTtm", "em"]).makeOptionMandatory())
     .option("--start-date <date>", "Start date (yyyy-MM-dd)", dateArg("--start-date"))
     .option("--end-date <date>", "End date (yyyy-MM-dd)", dateArg("--end-date"))
@@ -70,7 +70,7 @@ fundamental.command("valuation-analysis")
     .option("--field <field>", "Field", collectList, [])
     .option("--skip-null", "Drop rows where value or percentileRank is null")
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
     const requested = maybeArray(options.field);
@@ -115,7 +115,7 @@ fundamental.command("valuation-analysis")
 query(fundamental, "top-holders", {
     endpoint: "fundamental.top-holders",
     fields: [
-        required("--security-code <code>", undefined, "securityCode"),
+        securityCode(),
         field(new Option("--holder-type <type>", "Holder type: top10/top10Float").choices(["top10", "top10Float"]).makeOptionMandatory(), (v) => ({ holderType: v })),
         date("--start-date <date>", "Start date (yyyy-MM-dd)", "startDate"),
         date("--end-date <date>", "End date (yyyy-MM-dd)", "endDate"),
@@ -125,13 +125,13 @@ query(fundamental, "top-holders", {
     ],
 });
 fundamental.command("earning-forecast")
-    .requiredOption("--security-code <code>")
+    .requiredOption(SECURITY_CODE_FLAGS, SECURITY_CODE_HELP, oneSecurityCode)
     .option("--start-date <date>", "Start date (default: 1 year before end-date)", dateArg("--start-date"))
     .option("--end-date <date>", "End date (default: today)", dateArg("--end-date"))
     .option("--consensus <name>", "Consensus indicator: netIncome/netIncomeYoy/eps/pe/bps/pb/peg/roe/ps", collectList, [])
     .option("--yes", `Fetch a range estimated above ${COSTLY_FETCH_CREDITS} credits (billed per row; see the refusal for the estimate)`)
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => emit(options, (client) => {
     const endDate = options.endDate ?? beijingDateString(new Date());
     const startDate = options.startDate ?? new Date(new Date(`${endDate}T00:00:00Z`).getTime() - 365 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);

package/dist/src/commands/indicator.js

@@ -5,7 +5,7 @@ import { checkScreenerBindings, droppedFromMatrix, flattenCrossSection, flattenT
 import { ValidationError } from "../core/errors.js";
 import { parseOutputFormat } from "../core/output.js";
 import { printData } from "../core/printer.js";
-import { withClient } from "./shared.js";
+import { withClient, OUTPUT_HELP } from "./shared.js";
 function flagDropped(rows, data, requestedSecurities, requestedIndicators, timeSeries = false) {
     if (isEmptyMatrix(data)) {
         if (timeSeries) {
@@ -44,7 +44,7 @@ indicator.command("search")
     .requiredOption("--keyword <text>", "Search keyword, e.g. '收盘价' '成交量' '营业收入' (not free-form questions)")
     .option("--limit <number>", "Max results (default: 50, max: 100)", "50")
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
     const raw = await client.call("indicator.search", {
@@ -62,7 +62,7 @@ indicator.command("cross-section")
     .option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustType=2 for 前复权 (repeat); read exact keys from 'indicator search'. Bare 'code:' (nothing after the colon) declares the indicator takes NO date — required by any indicator whose parameterList has no date key at all, which otherwise rejects the tradeDate --date injects: the pty_* / scr_* static-attribute families (pty_op_scope, scr_exchg_mkt, scr_isin …), plus div_cash_paid_ratio / div_cash_yr (add 'code:fiscalYear=YYYY' too) and pty_shr_reg. It composes with real params, so 'code:' + 'code:scale=8' keeps the scale", collectNames, [])
     .addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode, unique & order-stable for batch code→value mapping").choices(["name", "code"]).default("name"))
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
     requireIndicatorScope(options.indicator, options.security);
@@ -83,7 +83,7 @@ indicator.command("time-series")
     .option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustType=2 for 前复权 (repeat); read exact keys from 'indicator search'", collectNames, [])
     .addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode/securityCode, unique & order-stable for batch mapping").choices(["name", "code"]).default("name"))
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
     requireIndicatorScope(options.indicator, options.security);
@@ -102,7 +102,7 @@ indicator.command("screener")
     .option("--indicator-param <spec>", "Per-variable param 'F1:key=value', e.g. F1:scale=8 (repeat); read exact keys from 'indicator search'. Bare 'F1:' (nothing after the colon) declares that the indicator takes NO date — required by any indicator whose parameterList has no date key at all, which otherwise rejects the tradeDate --date injects: the pty_* / scr_* static-attribute families (pty_op_scope, scr_exchg_sctr, scr_isin …), plus div_cash_paid_ratio / div_cash_yr (add 'F1:fiscalYear=YYYY' too) and pty_shr_reg. It composes with real params, so 'F1:' + 'F1:scale=8' keeps the scale", collectNames, [])
     .addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode").choices(["name", "code"]).default("name"))
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
     requireIndicatorScope(options.indicator, options.security);

package/dist/src/commands/insight.js

@@ -3,7 +3,7 @@ import { collectList, dateArg, datetimeArg, maybeArray, parseChoiceList, parseEn
 import { ValidationError } from "../core/errors.js";
 import { fetchOpinionDetails } from "../core/opinionDetail.js";
 import { rowCount } from "../core/rowSink.js";
-import { emit, addDownloadCommand, confirmCostly, multiChoice, field, value, required, list, numberList, choiceList, count, rankType, searchType, top, flag, format, output, from, size, startTime, endTime, timeFilters, query, RESEARCH_AREA_CITIC_OR_DIRECTION } from "./shared.js";
+import { emit, addDownloadCommand, confirmCostly, multiChoice, field, value, required, list, numberList, choiceList, count, rankType, searchType, top, flag, format, output, from, size, startTime, endTime, timeFilters, query, RESEARCH_AREA_CITIC_OR_DIRECTION, OUTPUT_HELP, securityCode } from "./shared.js";
 export const insight = new Command("insight").description("Insight APIs");
 const SW_INDUSTRY_ONLY = "Industry ID -- swIndustry codes only (104xx0000); citicIndustry codes are rejected with 100005 even where constant-category declares them";
 const opinion = new Command("opinion");
@@ -21,6 +21,7 @@ const announcementHk = new Command("announcement-hk");
 const announcementUs = new Command("announcement-us");
 const foreignOpinion = new Command("foreign-opinion");
 const independentOpinion = new Command("independent-opinion");
+const overseasOpinion = new Command("overseas-opinion");
 const officialAccount = new Command("official-account");
 const qa = new Command("qa");
 const reportImage = new Command("report-image");
@@ -46,7 +47,7 @@ query(opinion, "list", {
         list("--broker-tag <tag>", "Broker tag: topBroker/newFortune", "brokerTagList"),
         list("--source <source>", "Source", "sourceList"),
         flag("--with-content", "Return the full body inline (v1 list, 30 credits/row) instead of the 200-char brief (1 credit/row). v1 shape: title and body sit under contentList.title / contentList.content, and there is no brief. Takes no --category / --broker-tag, and --llm-tag only strongRcmd/earningsReview/topBroker/newFortune"),
-        format(), output("Output path"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
@@ -62,7 +63,7 @@ query(summary, "list", {
         list("--category <name>", "Category", "categoryList"),
         list("--market <name>", "Market", "marketList"),
         list("--participant-role <name>", "Participant role", "participantRoleList"),
-        format(), output("Output path"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
@@ -79,7 +80,7 @@ query(pamirsSummary, "list", {
         list("--security <code>", "Security code, e.g. 000001.SZ", "securityList"),
         choiceList("--category <name>", `Category: ${PAMIRS_CATEGORIES.join(" / ")}`, "categoryList", PAMIRS_CATEGORIES),
         choiceList("--market <name>", `Market: ${PAMIRS_MARKETS.join(" / ")}`, "marketList", PAMIRS_MARKETS),
-        format(), output("Output path"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
@@ -102,7 +103,7 @@ const addScheduleList = (command, endpointKey, fields) => query(command, "list",
         fields.brokerType && list("--broker-type <name>", "Lead broker type: cnBroker/otherBroker", "brokerTypeList"),
         fields.permission && numberList("--permission <number>", "Permission: 1=public 2=private", "permission"),
         fields.location && list("--location <id>", "Location ID (domesticCity constant, via 'reference constant-list')", "locationList"),
-        format(), output("Output path"),
+        format(), output(),
         ...timeFilters(),
         publishTime("--publish-start-time <datetime>", "Collected from (publishTime, when the schedule first came in — not when it is held); combines with --start-time/--end-time", "publishStartTime"),
         publishTime("--publish-end-time <datetime>", "Collected until (publishTime); a bare date covers that whole day", "publishEndTime"),
@@ -146,7 +147,7 @@ performanceCalendar.command("list").description("Earnings calendar (业绩预告
     .option("--security <code>", "Security code (e.g. 000001.SZ)", collectList, [])
     .addOption(multiChoice("--market <name>", `Market: ${PERFORMANCE_MARKETS.join("/")}`, PERFORMANCE_MARKETS))
     .addOption(multiChoice("--category <name>", `Event type: ${PERFORMANCE_CATEGORIES.join("/")}`, PERFORMANCE_CATEGORIES))
-    .option("--format <format>", "Output format", "table").option("--output <path>", "Output path")
+    .option("--format <format>", "Output format", "table").option("--output <path>", OUTPUT_HELP)
     .addOption(confirmCostly().option)
     .action((options) => {
     const marketList = parseChoiceList(options.market, "--market", PERFORMANCE_MARKETS);
@@ -186,7 +187,7 @@ query(research, "list", {
         count("--min-pages <number>", "Min report pages", "minReportPages"),
         count("--max-pages <number>", "Max report pages", "maxReportPages"),
         list("--source <type>", "Source type", "sourceList"),
-        format(), output("Output path"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
@@ -206,7 +207,7 @@ query(foreignReport, "list", {
         list("--rating-change <name>", "Rating change", "ratingChangeList"),
         count("--min-pages <number>", "Min report pages", "minReportPages"),
         count("--max-pages <number>", "Max report pages", "maxReportPages"),
-        format(), output("Output path"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
@@ -218,7 +219,7 @@ query(announcement, "list", {
         searchType(), rankType(),
         list("--security <code>", "Security code", "securityList"),
         list("--category <id>", "Category ID", "categoryList"),
-        format(), output("Output path"),
+        format(), output(),
         ...timeFilters(parseTimestamp13, parseEndTimestamp13),
     ],
 });
@@ -230,7 +231,7 @@ query(announcementHk, "list", {
         searchType(), rankType(),
         list("--security <code>", "Security code (e.g. 01913.HK)", "securityList"),
         list("--category <id>", "Category ID", "categoryList"),
-        format(), output("Output path"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
@@ -242,7 +243,7 @@ query(announcementUs, "list", {
         searchType(), rankType(),
         list("--security <code>", "Security code (e.g. TSLA.O)", "securityList"),
         list("--category <id>", "Category ID (constant-list usShareAnnouncementCategory)", "categoryList"),
-        format(), output("Output path"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
@@ -258,17 +259,17 @@ query(foreignOpinion, "list", {
         list("--rating <name>", "Rating", "ratingList"),
         list("--rating-change <name>", "Rating change", "ratingChangeList"),
         flag("--with-content", "Return the full body inline (v1 list, 30 credits/row) as content / contentTranslate, instead of the 200-char brief (1 credit/row)"),
-        format(), output("Output path"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
 opinion.command("detail").description("Full bodies of domestic chief opinions by ID (30 credits per returned opinion; batched 20 per call)")
     .requiredOption("--chief-opinion-id <id>", "chiefOpinionId from 'insight opinion list' (repeat or comma-separate)", collectList)
-    .option("--format <format>", "Output format", "json").option("--output <path>")
+    .option("--format <format>", "Output format", "json").option("--output <path>", OUTPUT_HELP)
     .action((options) => emit(options, (client) => fetchOpinionDetails(client, "insight.opinion.detail", "chiefOpinionIdList", "chiefOpinionId", options.chiefOpinionId)));
 foreignOpinion.command("detail").description("Full bodies (content + contentTranslate) of foreign opinions by ID (30 credits per returned opinion; batched 20 per call)")
     .requiredOption("--foreign-opinion-id <id>", "foreignOpinionId from 'insight foreign-opinion list' (repeat or comma-separate)", collectList)
-    .option("--format <format>", "Output format", "json").option("--output <path>")
+    .option("--format <format>", "Output format", "json").option("--output <path>", OUTPUT_HELP)
     .action((options) => emit(options, (client) => fetchOpinionDetails(client, "insight.foreign-opinion.detail", "foreignOpinionIdList", "foreignOpinionId", options.foreignOpinionId)));
 query(independentOpinion, "list", {
     endpoint: "insight.independent-opinion.list",
@@ -278,11 +279,30 @@ query(independentOpinion, "list", {
         list("--industry <id>", SW_INDUSTRY_ONLY, "industryList"),
         list("--rating <name>", "Rating", "ratingList"),
         list("--rating-change <name>", "Rating change", "ratingChangeList"),
-        format(), output("Output path"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
 addDownloadCommand(independentOpinion, { endpointKey: "insight.independent-opinion.download", idOption: "--independent-opinion-id", idField: "independentOpinionId", fallbackPrefix: "independent-opinion", fileType: { description: "File type: 1=original HTML 2=CN-translated HTML", choices: ["1", "2"], required: true } });
+query(overseasOpinion, "list", {
+    description: "List overseas opinions: brief + briefTranslate, body via 'overseas-opinion detail' (0.1 credits/row)",
+    endpoint: "insight.overseas-opinion.list",
+    fields: [
+        rankType(),
+        list("--account <id>", "Account ID from 'reference overseas-account-search' (repeat or comma-separate)", "accountIdList"),
+        list("--security <code>", "Security code with market suffix, e.g. NVDA.O. A missing suffix is rejected (120001); a real suffix of the wrong market (NVDA.N) matches nothing", "securityList"),
+        list("--category <name>", "Category: opinion/news/dataAnalysis/promotion (repeat). A row in several categories is returned under each; rows without a category only when this is omitted", "categoryList"),
+        list("--industry <id>", "GICS sector ID: 107700001 energy ... 107700011 real estate (list: 'reference constant-list --category gicsIndustry'). Other industry code sets are rejected (100005)", "industryList"),
+        list("--region <code>", "Region code: cn/cnHk/cnTw/us/jp/kr/uk/gl; other regionCategory values are rejected (100005)", "regionList"),
+        count("--original-flag <number>", "1=original posts only 0=reposts only; omit for both", "originalFlag"),
+        format(), output(),
+        ...timeFilters(),
+    ],
+});
+overseasOpinion.command("detail").description("Full bodies (content + contentTranslate) of overseas opinions by ID (10 credits per returned opinion; batched 20 per call)")
+    .requiredOption("--overseas-opinion-id <id>", "overseasOpinionId from 'insight overseas-opinion list' (repeat or comma-separate)", collectList)
+    .option("--format <format>", "Output format", "json").option("--output <path>", OUTPUT_HELP)
+    .action((options) => emit(options, (client) => fetchOpinionDetails(client, "insight.overseas-opinion.detail", "overseasOpinionIdList", "overseasOpinionId", options.overseasOpinionId)));
 query(officialAccount, "list", {
     endpoint: "insight.official-account.list",
     cache: { endpointKey: "insight.official-account.list", idField: "articleId" },
@@ -292,7 +312,7 @@ query(officialAccount, "list", {
         list("--security <code>", "Security code (e.g. 000001.SZ)", "securityList"),
         list("--category <type>", "Article type: news/law/report/view/data/event/meeting/notice/recruit/investEdu/brand/notes/other", "categoryList"),
         list("--industry <id>", "Industry ID (constant-list citicIndustry/swIndustry)", "industryList"),
-        format(), output("Output path"),
+        format(), output(),
         ...timeFilters(),
     ],
 });
@@ -300,7 +320,7 @@ addDownloadCommand(officialAccount, { endpointKey: "insight.official-account.dow
 query(qa, "list", {
     endpoint: "insight.qa.list",
     fields: [
-        required("--security-code <code>", "Security code, e.g. 601012.SH", "securityCode"),
+        securityCode("Security code, e.g. 601012.SH"),
         from(), size("Total rows to return; omit to fetch all (max page 500)"),
         startTime("Start time (yyyy-MM-dd or yyyy-MM-dd HH:mm:ss)"), endTime("End time (yyyy-MM-dd or yyyy-MM-dd HH:mm:ss)"),
         list("--source <type>", "Source: conference/interactive/survey (repeat)", "source"),
@@ -335,6 +355,7 @@ insight.addCommand(announcementHk);
 insight.addCommand(announcementUs);
 insight.addCommand(foreignOpinion);
 insight.addCommand(independentOpinion);
+insight.addCommand(overseasOpinion);
 insight.addCommand(officialAccount);
 insight.addCommand(qa);
 insight.addCommand(reportImage);

package/dist/src/commands/quote.js

@@ -8,7 +8,7 @@ import { flagMissingFields } from "../core/normalize.js";
 import { parseOutputFormat } from "../core/output.js";
 import { printData } from "../core/printer.js";
 import { rowCount } from "../core/rowSink.js";
-import { emit, withClient, DEFAULT_QUOTE_LIMIT, MAX_QUOTE_LIMIT, flagIfLimitTruncated, noteLateStart } from "./shared.js";
+import { emit, withClient, DEFAULT_QUOTE_LIMIT, MAX_QUOTE_LIMIT, flagIfLimitTruncated, noteLateStart, OUTPUT_HELP } from "./shared.js";
 export const quote = new Command("quote").description("Quote APIs");
 const KLINE_MARKETS = { aShares: 1, hkStocks: 2, usStocks: 1 };
 const LEGACY_ALL_MARKET = (shardDays) => ({ all: shardDays });
@@ -48,7 +48,7 @@ const addKlineCommand = (name, endpointKey, securityHelp, markets, noKeywordReas
     .option("--limit <number>", `Max rows per request (default: ${DEFAULT_QUOTE_LIMIT}, max: ${MAX_QUOTE_LIMIT}). With several securities it also sizes the groups they are fetched in, so a small value fetches one security per request`)
     .option("--field <field>", "Field", collectList, [])
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => {
     checkMarketKeywords(options.security, Object.keys(markets), `quote ${name}`, noKeywordReason);
     options.security = canonicalizeMarketKeywords(options.security, Object.keys(markets));
@@ -100,7 +100,7 @@ quote.command("minute-kline")
     .option("--limit <number>", `Max rows per request (default: ${DEFAULT_QUOTE_LIMIT}, max: ${MAX_QUOTE_LIMIT})`)
     .option("--field <field>", "Field", collectList, [])
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => withClient(options, async (client) => {
     const format = parseOutputFormat(options.format);
     client.rowSink?.watchEarliest("tradeTime");
@@ -127,7 +127,7 @@ quote.command("realtime")
     .option("--security <code>", "Security code — stock .SH/.SZ/.BJ/.HK/.O/.N/.A, ETF .SH/.SZ (e.g. 512800.SH), exchange index .SH/.SZ/.BJ, concept index .GT, industry index .CI/.SWI, global index (e.g. SPX.SPI / N225.NKI / HSI.HI); or one market keyword: aShares / hkStocks / usStocks (must be passed alone; keywords cover stocks only — ETFs and indices have no whole-market keyword)", collectList, [])
     .option("--field <field>", "Field", collectList, [])
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => {
     checkMarketKeywords(options.security, REALTIME_MARKETS, "quote realtime");
     return emit(options, async (client) => {
@@ -147,7 +147,7 @@ quote.command("fund-flow")
     .option("--limit <number>", `Max rows per request (default: ${DEFAULT_QUOTE_LIMIT}, max: ${MAX_QUOTE_LIMIT}; single-security cap — aShares auto-shards by day)`)
     .option("--field <field>", "Field, e.g. mainNetInflow/largeInflow/xlargeOutflow (repeat); omit for all", collectList, [])
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => {
     checkMarketKeywords(options.security, FUND_FLOW_MARKETS, "quote fund-flow");
     options.security = canonicalizeMarketKeywords(options.security, FUND_FLOW_MARKETS);
@@ -187,7 +187,7 @@ quote.command("sector-fund-flow")
     .option("--limit <number>", `Max rows returned (default: ${DEFAULT_QUOTE_LIMIT}, max: ${MAX_QUOTE_LIMIT}). It cuts the answer only: a query too heavy to compute fails with 100006 whatever the limit — shorten the range, or pass fewer sectors or fields`)
     .option("--field <field>", "Field, e.g. sectorMainNetInflow / sectorLargeInflow (repeat); omit for all. sectorId and tradeDate always come first", collectList, [])
     .option("--format <format>", "Output format", "table")
-    .option("--output <path>")
+    .option("--output <path>", OUTPUT_HELP)
     .action((options) => emit(options, async (client) => {
     const limit = parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1, max: MAX_QUOTE_LIMIT }) ?? DEFAULT_QUOTE_LIMIT;
     const fieldList = maybeArray(options.field);

package/dist/src/commands/raw.js

@@ -5,8 +5,8 @@ import { ConfigError, ValidationError } from "../core/errors.js";
 import { flagFailedItems } from "../core/normalize.js";
 import { parseOutputFormat } from "../core/output.js";
 import { printData } from "../core/printer.js";
-import { createClient, runDownload, assertConfirmed } from "./shared.js";
-export const raw = new Command("raw").description("Raw API calls").addCommand(new Command("call").argument("<endpointKey>").option("--body <json>").option("--query <key=value>", "Query string pair", collectKeyValue, {}).option("--yes", "Confirm an irreversible endpoint (required for the ones marked destructive), or fetch every row of a per-row billed list past the credit guard").option("--format <format>", "Output format", "json").option("--output <path>").action(async (endpointKey, options) => {
+import { createClient, runDownload, assertConfirmed, OUTPUT_HELP } from "./shared.js";
+export const raw = new Command("raw").description("Raw API calls").addCommand(new Command("call").argument("<endpointKey>").option("--body <json>", "Request body as a JSON string").option("--query <key=value>", "Query string pair", collectKeyValue, {}).option("--yes", "Confirm an irreversible endpoint (required for the ones marked destructive), or fetch every row of a per-row billed list past the credit guard").option("--format <format>", "Output format", "json").option("--output <path>", OUTPUT_HELP).action(async (endpointKey, options) => {
     const endpoint = ENDPOINTS[endpointKey];
     if (!endpoint) {
         throw new ConfigError(`Unknown endpoint key: ${endpointKey}`);
@@ -47,4 +47,4 @@ export const raw = new Command("raw").description("Raw API calls").addCommand(ne
     finally {
         await client.rowSink?.abort();
     }
-})).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)));
+})).addCommand(new Command("list").description("List all registered endpoint keys (for use with 'raw call')").option("--format <format>", "Output format", "table").option("--output <path>", OUTPUT_HELP).action((options) => printData(listEndpoints(), parseOutputFormat(options.format), options.output)));

package/dist/src/commands/reference.js

@@ -1,11 +1,11 @@
 import { Command } from "commander";
-import { value, required, requiredList, date, choiceList, top, format, output, query } from "./shared.js";
+import { value, required, requiredList, date, choiceList, top, format, output, from, size, query } from "./shared.js";
 export const reference = new Command("reference").description("Reference data APIs");
 query(reference, "securities-search", {
     endpoint: "reference.securities-search",
     fields: [
         required("--keyword <text>", "Search keyword (name/code/pinyin/English)", "keyword"),
-        choiceList("--category <type>", "Category: stock/dr/index/fund/bond. Convertible bonds can come back under any category — keep the rows whose returned category matches", "category", ["stock", "dr", "index", "fund", "bond"]),
+        choiceList("--category <type>", "Category: stock/dr/index/fund/bond. Without it, a convertible bond can rank above its stock on a short name", "category", ["stock", "dr", "index", "fund", "bond"]),
         top(10),
         format(), output(),
     ],
@@ -73,9 +73,18 @@ query(reference, "institution-search", {
 query(reference, "official-account-search", {
     endpoint: "reference.official-account-search",
     fields: [
-        required("--keyword <text>", "Search keyword (account name / institution / keyword, e.g. 东吴证券)", "keyword"),
+        required("--keyword <text>", "Account name fragment, e.g. 中信证券 (finds 中信证券研究). Matches the account name: an institution's full name misses accounts named by short form (东吴证券 finds none, 东吴 finds 东吴策略陈刚团队)", "keyword"),
         choiceList("--category <name>", "Category: listedCompany/broker/government/media (repeat); omit for all incl. uncategorized", "category", ["listedCompany", "broker", "government", "media"]),
         top(10),
         format(), output(),
     ],
 });
+query(reference, "overseas-account-search", {
+    description: "Search overseas opinion account IDs by name fragment, for 'insight overseas-opinion list --account' (free)",
+    endpoint: "reference.overseas-account-search",
+    fields: [
+        required("--keyword <text>", "Account name fragment: substring match anywhere in the name, case-insensitive (e.g. elo matches Elon Musk and Financelot)", "accountName"),
+        from(), size(),
+        format(), output(),
+    ],
+});

package/dist/src/commands/shared.js

@@ -1,18 +1,19 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { Option } from "commander";
+import { InvalidArgumentError, Option } from "commander";
 import { QUOTE_MAX_LIMIT } from "../core/quoteSharding.js";
 import { collectList, dateArg, datetimeArg, maybeArray, numberListArg, parseChoiceList, parseFrom, parseNumberOption, parseOptionalNumberOption, parseSize } from "../core/args.js";
 import { loadConfig } from "../core/config.js";
-import { placeStreamedDownload, releaseClaim, resolveTitle, saveDownloadResult, uniquePath } from "../core/download.js";
+import { assertOutputFilePath, placeStreamedDownload, releaseClaim, resolveTitle, saveDownloadResult, uniquePath } from "../core/download.js";
+import { isDryRun } from "../core/dryRun.js";
 import { ENDPOINTS } from "../core/endpoints.js";
 import { ValidationError } from "../core/errors.js";
 import { parseOutputFormat, stagingPath } from "../core/output.js";
-import { printData } from "../core/printer.js";
+import { columnsSelected, printData } from "../core/printer.js";
 import { ExportSink, getRowSink } from "../core/rowSink.js";
 export async function createClient(stream) {
     const { GangtiseClient } = await import("../core/client.js");
-    const sink = stream?.output && (stream.format === "jsonl" || stream.format === "csv") ? new ExportSink(stream.output, stream.format, stream.cache) : undefined;
+    const sink = stream?.output && (stream.format === "jsonl" || stream.format === "csv") && !columnsSelected() ? new ExportSink(stream.output, stream.format, stream.cache) : undefined;
     const client = new GangtiseClient(loadConfig(), sink);
     client.allowCostlyFetch = Boolean(stream?.yes);
     return client;
@@ -89,6 +90,7 @@ export function noteLateStart(data, requestedStart, field, label, cause = "The s
 }
 export async function runDownload(client, endpointKey, query, options) {
     if (options.output) {
+        await assertOutputFilePath(options.output);
         const result = await client.call(endpointKey, options.body, query, { streamTo: options.output });
         await saveDownloadResult(result, options.fallbackName, options.output);
         return;
@@ -120,7 +122,7 @@ export async function runDownload(client, endpointKey, query, options) {
     }
 }
 export function addDownloadCommand(parent, spec) {
-    const cmd = parent.command(spec.name ?? "download").requiredOption(`${spec.idOption} <id>`);
+    const cmd = parent.command(spec.name ?? "download").requiredOption(`${spec.idOption} <id>`, `The ${spec.idField} of the record, from the matching list command`);
     if (spec.fileType) {
         const option = new Option("--file-type <number>", spec.fileType.description).choices(spec.fileType.choices);
         cmd.addOption(spec.fileType.required ? option.makeOptionMandatory() : option.default(spec.fileType.default));
@@ -132,7 +134,7 @@ export function addDownloadCommand(parent, spec) {
     if (spec.titleListEndpoint) {
         cmd.option("--resolve-title", "On a title-cache miss, query the list endpoint for a friendly filename (4 extra requests; most of these list endpoints bill per row). Without it the server filename or <prefix>-<id> is used. Ignored when --output is given");
     }
-    cmd.option("--output <path>").action((options) => withClient(async (client) => {
+    cmd.option("--output <path>", DOWNLOAD_OUTPUT_HELP).action((options) => withClient(async (client) => {
         const id = options[spec.idField];
         const qp = { [spec.idField]: id };
         if (spec.fileType && options.fileType)
@@ -151,7 +153,7 @@ export function addDownloadCommand(parent, spec) {
 }
 export function assertConfirmed(endpointKey, confirmed, target) {
     const destructive = ENDPOINTS[endpointKey]?.destructive;
-    if (!destructive || confirmed)
+    if (!destructive || confirmed || isDryRun())
         return;
     throw new ValidationError(`${destructive.warning} 确认要对 ${target} 执行就加上 --yes。`);
 }
@@ -201,8 +203,18 @@ export const rankType = () => numberEnum("--rank-type <number>", "Rank type: 1=c
 export const searchType = () => numberEnum("--search-type <number>", "Search type: 1=title 2=fulltext", "searchType", ["1", "2"], "1");
 export const top = (max) => field(new Option("--top <number>", `Max results (default: 10, max: ${max})`).default("10"), (v) => ({ top: parseNumberOption(v, "--top", { integer: true, min: 1, max }) }));
 export const flag = (flags, description) => field(new Option(flags, description));
+export const OUTPUT_HELP = "Write the result to this file instead of stdout (a file path, not a directory)";
+export const DOWNLOAD_OUTPUT_HELP = "Save the file to this path (a file path, not a directory); omit for an automatic name in the current directory";
+export const SECURITY_CODE_FLAGS = "--security, --security-code <code>";
+export const SECURITY_CODE_HELP = "Security code, e.g. 600519.SH";
+export const oneSecurityCode = (value) => {
+    if (value.includes(","))
+        throw new InvalidArgumentError("takes one security code; run the command once per code");
+    return value;
+};
 export const format = (fallback = "table") => field(new Option("--format <format>", "Output format").default(fallback));
-export const output = (description) => field(new Option("--output <path>", description));
+export const output = (description = OUTPUT_HELP) => field(new Option("--output <path>", description));
+export const securityCode = (description = SECURITY_CODE_HELP) => field(new Option(SECURITY_CODE_FLAGS, description).makeOptionMandatory().argParser(oneSecurityCode), (v) => ({ securityCode: v }));
 export const from = () => field(new Option("--from <number>", "Starting offset").default("0"), (v) => ({ from: parseFrom(v) }));
 export const size = (description = "Total rows to return; omit to fetch all") => field(new Option("--size <number>", description), (v) => ({ size: parseSize(v) }));
 const asTyped = (v) => v;

package/dist/src/commands/tool.js

@@ -2,15 +2,18 @@ import { Command, Option } from "commander";
 import { POLL_MAX_ATTEMPTS } from "../core/asyncContent.js";
 import { collectList, maybeArray, parseNumberOption, parseOptionalNumberOption } from "../core/args.js";
 import { ValidationError } from "../core/errors.js";
+import { assertOutputFilePath } from "../core/download.js";
 import { fetchFileParseResult, pollFileParseResult, submitFileParse } from "../core/fileParse.js";
 import { markFailed } from "../core/exitStatus.js";
-import { emit, withClient } from "./shared.js";
+import { emit, withClient, OUTPUT_HELP } from "./shared.js";
 export const tool = new Command("tool").description("Research tool APIs: PDF parsing");
 tool.command("file-parse").description("Parse a PDF into Markdown + images (async; 0.8 credits/page, billed at submit)")
     .requiredOption("--file <path>", "PDF to upload (max 100MB / 500 pages)")
     .option("--wait", "Wait for the parse to finish and save the result ZIP (blocking, up to ~5 min)")
-    .option("--output <path>", "Where to save the result ZIP (used with --wait)")
+    .option("--output <path>", "Where to save the result ZIP (a file path, not a directory; used with --wait)")
     .action((options) => withClient(async (client) => {
+    if (options.wait && options.output)
+        await assertOutputFilePath(options.output);
     const taskId = await submitFileParse(client, options.file);
     if (!options.wait) {
         process.stderr.write(`File parse task submitted. taskId: ${taskId}\n`);
@@ -25,8 +28,10 @@ tool.command("file-parse").description("Parse a PDF into Markdown + images (asyn
 }));
 tool.command("file-parse-check").description("Download a finished file-parse result ZIP by taskId (free)")
     .requiredOption("--task-id <id>", "taskId from 'tool file-parse'")
-    .option("--output <path>", "Where to save the result ZIP")
+    .option("--output <path>", "Where to save the result ZIP (a file path, not a directory)")
     .action((options) => withClient(async (client) => {
+    if (options.output)
+        await assertOutputFilePath(options.output);
     if (await fetchFileParseResult(client, options.taskId, options.output) === "pending") {
         process.stdout.write(`${JSON.stringify({ taskId: options.taskId, status: "pending", hint: "Parse not finished yet, retry in ~1 minute" })}\n`);
     }
@@ -39,7 +44,7 @@ tool.command("web-search").description("Search the public web for research: dedu
     .option("--site <domain>", "Restrict to a registered domain or subdomain, e.g. csrc.gov.cn (repeatable, max 10, OR-ed)", collectList, [])
     .option("--include-content", "Return page body as Markdown; caps --size at 5")
     .option("--max-content-chars <number>", "Max chars per body, 1000-20000 (only with --include-content)")
-    .option("--format <format>", "Output format", "table").option("--output <path>")
+    .option("--format <format>", "Output format", "table").option("--output <path>", OUTPUT_HELP)
     .action((options) => emit(options, (client) => {
     const size = parseNumberOption(options.size ?? (options.includeContent ? "5" : "10"), "--size", { integer: true, min: 1, max: 20 });
     if (options.includeContent && size > 5)

package/dist/src/commands/update.js

@@ -1,6 +1,7 @@
 import os from "node:os";
 import { Command } from "commander";
 import { isVersionNewer } from "../core/args.js";
+import { isDryRun } from "../core/dryRun.js";
 import { installVersion, refreshSkillCopies } from "../core/selfUpdate.js";
 import { latestVersion, PACKAGE_NAME, REGISTRY } from "../core/updateCheck.js";
 import { CLI_VERSION, PACKAGE_ROOT } from "../version.js";
@@ -9,6 +10,16 @@ export const update = new Command("update")
     .option("--check", "Only report whether a newer version is published; install nothing")
     .option("--no-skill", "Leave the Agent Skill copies as they are")
     .action(async (options) => {
+    if (isDryRun()) {
+        const steps = [`look up the latest published version on ${REGISTRY}`];
+        if (!options.check) {
+            steps.push(`if newer than ${CLI_VERSION}: npm install -g ${PACKAGE_NAME}@<latest> --registry=${REGISTRY}`);
+            if (options.skill)
+                steps.push("refresh older copies of the Agent Skill");
+        }
+        process.stdout.write(`${JSON.stringify({ dryRun: true, command: "update", steps, note: "Nothing was looked up or installed." }, null, 2)}\n`);
+        return;
+    }
     const latest = await latestVersion(undefined, 15_000, Date.now(), true);
     if (!latest)
         throw new Error(`Could not reach ${REGISTRY} to look up the latest version. Check the network and retry, or install directly: npm install -g ${PACKAGE_NAME}@latest --registry=${REGISTRY}`);