gangtise-openapi-cli 0.30.1 → 0.31.0

package/README.md

@@ -6,11 +6,11 @@
 
 README 仅列最近 5 个版本摘要：
 
+- **v0.31.0 — 2026-08-03**：修复 v0.30.1 的矩阵维度校验误杀「单指标 × 板块 ID」时序查询的回归；EDE 结果不完整或不可信时改以退出码 3 标记（`partial` / `unreliable`）。
 - **v0.30.1 — 2026-08-02**：修复 `sDate` 吞掉查询日期导致的区间指标静默错数，让条件选股的文本筛选真正可用，并在服务端整行/整列丢数据时给出警告。
 - **v0.30.0 — 2026-08-02**：适配 EDE 接口重构（`universe` 取代 `securityCodeList`、截面矩阵转置、指标元数据结构化），新增 `indicator screener` 条件选股，并修正复权参数名。
 - **v0.29.0 — 2026-07-25**：新增财报日历与 PDF 解析工具，群消息补 `quoteMsg`，并加强大整数 ID 与高积分调用防护。
 - **v0.28.3 — 2026-07-24**：修复列式响应在错误 `--field` 下静默错列的问题，并校正 EDE 与字段文档。
-- **v0.28.2 — 2026-07-24**：EDE 批量取数新增 `--key-by name|code`，优化无数据诊断与相关 Skill 文档。
 
 ### 历史里程碑
 
@@ -297,6 +297,7 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 - `--from` 必须是非负整数，`--size` 必须是正整数；非法数字会在本地直接报 `ValidationError`，不会继续请求 API
 - 安全上限：自动翻页最多 1000 页，防止异常循环
 - 部分页失败、或服务端实际返回行数与 `total` 矛盾（提前短页）时，不丢弃已取到的数据：结果带 `partial: true`（页失败时另有 `failedPages`；K线分片为 `failedShards`；`--format json` 可见），stderr 输出警告，**进程退出码为 3**（完整成功为 0）
+- **v0.31.0 起退出码 3 的覆盖面扩大**（脚本按 `!= 0` 判失败的需留意）：`indicator` 命令在服务端整指标/整证券无数据时同样标 `partial` + `omittedIndicators` / `omittedSecurities` 并退出 3；条件选股把同一指标绑到多个变量时标 `unreliable: true` + `duplicatedIndicators` 并退出 3（那些值不可信，不是少了行）。**条件选股的缺列另有更严的一档**：把缺列的变量当作无法求值，若表达式（按 `&&`/`||` 的布尔结构）再无任何可成立的分支，则**退出码 1 且不输出**——那些行以「通过了该条件」的名义呈现，而条件根本无法证明被执行过。**整个查询合法无数据仍是退出码 0 且不标 partial**。语义约定：`0` 完整成功（含合法空结果）／`3` 有数据但不完整或不可信／`1` 硬失败
 - 分页结果中 `total` 字段会被保留（json 格式输出 `{total, list}`）；其他格式下 stderr 输出 `Total: N, showing: M`（json 格式不输出该行）
 
 ## 智能文件命名
@@ -581,7 +582,7 @@ gangtise indicator time-series --indicator qte_close \
   --start-date 2026-07-29 --end-date 2026-07-31 --format table
 
 # 条件选股：F1/F2… 绑定指标，用表达式组合筛选（--indicator-param 按变量索引，不是按 code）
-# --date 必填：screener 会丢弃 parameters 为空的指标，CLI 靠它给每个指标挂上日期
+# --date 必填：绝大多数指标吃 tradeDate，漏传就是空表 + 退出码 0
 gangtise indicator screener \
   --indicator F1:qte_mkt_cptl --indicator F2:finc_pe_ttm \
   --indicator-param "F1:scale=8" \

package/dist/src/cli.js

@@ -2,9 +2,9 @@
 import { Command, Option } from "commander";
 import { checkAsyncContent, pollAsyncContent, POLL_MAX_ATTEMPTS } from "./core/asyncContent.js";
 import { readTokenCache, redactTokenCache } from "./core/auth.js";
-import { collectKeyValue, collectList, collectNumberList, dateArg, datetimeArg, duplicateScreenerCodes, isVersionNewer, localDateString, maybeArray, parseChoiceList, parseFrom, parseNumberOption, parseOptionalNumberOption, parseScreenerIndicators, parseSize, parseTimestamp13 } from "./core/args.js";
+import { collectKeyValue, collectList, collectNumberList, dateArg, datetimeArg, duplicateScreenerCodes, screenerExpressionFields, isVersionNewer, localDateString, maybeArray, parseChoiceList, parseFrom, parseNumberOption, parseOptionalNumberOption, parseScreenerIndicators, parseSize, parseTimestamp13 } from "./core/args.js";
 import { buildIndicatorCrossSectionBody, buildIndicatorScreenerBody, buildIndicatorTimeSeriesBody, buildQuoteKlineBody, buildStockPoolStocksBody, buildWechatChatroomListBody, buildWechatMessageListBody } from "./core/commandBodies.js";
-import { droppedFromMatrix, flattenCrossSection, flattenTimeSeries, unwrapIndicatorData } from "./core/indicatorMatrix.js";
+import { checkScreenerBindings, droppedFromMatrix, flattenCrossSection, flattenTimeSeries, isEmptyMatrix, requireIndicatorMatrix, unwrapIndicatorData } from "./core/indicatorMatrix.js";
 import { callKlineWithSharding, isAllMarket, isFullMarket } from "./core/quoteSharding.js";
 import { loadConfig } from "./core/config.js";
 import { resolveTitle, saveDownloadResult, uniquePath } from "./core/download.js";
@@ -116,7 +116,7 @@ function addTimeFilters(command) {
         .option("--end-time <datetime>", "End time", datetimeArg("--end-time"))
         .option("--keyword <keyword>", "Keyword");
 }
-import { setVerbose } from "./core/transport.js";
+import { isVerbose, setVerbose } from "./core/transport.js";
 import { CLI_VERSION } from "./version.js";
 const program = new Command();
 program
@@ -697,21 +697,64 @@ alternative.command("edb-data").option("--indicator-id <id>", "Indicator ID (rep
 alternative.command("concept-info").requiredOption("--concept-id <id>", "Concept (theme index) ID, e.g. 121000130 机器人; discover via 'gangtise reference concept-search'").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => emit(options, (client) => client.call("alternative.concept-info", { conceptId: options.conceptId })));
 alternative.command("concept-securities").requiredOption("--concept-id <id>", "Concept (theme index) ID, e.g. 121000130 机器人; discover via 'gangtise reference concept-search'").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => emit(options, (client) => client.call("alternative.concept-securities", { conceptId: options.conceptId })));
 program.addCommand(alternative);
-/** Tell the caller what the server left out. EDE does not pad missing data with
+/** Mark and report what the server left out. EDE does not pad missing data with
  * `null`: an indicator empty for every security vanishes from `indicatorList`,
  * a security empty for every indicator vanishes from `securityCodeList` (probed
  * 2026-08-02). Without this the shortfall is invisible — exit code 0, a
  * plausible-looking table, and a `--key-by code` mapping whose key simply is not
- * there. stderr only, so piped output stays machine-readable. */
-function warnDropped(data, requestedSecurities, requestedIndicators) {
+ * there.
+ *
+ * This is the same class of defect as a failed page or a row cap, so it reuses
+ * the same signal: `partial` on the payload (printData → exit 3) plus the
+ * omitted codes, so an automated caller can react without parsing stderr. */
+function flagDropped(rows, data, requestedSecurities, requestedIndicators) {
+    // A wholly empty response is a legitimate answer, not a partial one: the diff
+    // against the request would list everything as "omitted", which is false —
+    // nothing was dropped, there is no data. Exit 0, but say why it is ambiguous.
+    if (isEmptyMatrix(data)) {
+        process.stderr.write("[gangtise] note: the query returned no data at all. That is a normal answer for a non-trading range or a date outside coverage — but since 2026-08-01 it is ALSO what a wrong parameter name or the wrong date field (tradeDate vs reportDate) produces. Cross-check against 'gangtise indicator search --format json'.\n");
+        return;
+    }
     const { securities, indicators } = droppedFromMatrix(data, requestedSecurities, requestedIndicators);
+    if (securities.length === 0 && indicators.length === 0)
+        return;
+    if (rows && typeof rows === "object" && !Array.isArray(rows)) {
+        const rec = rows;
+        rec.partial = true;
+        if (indicators.length > 0)
+            rec.omittedIndicators = indicators;
+        if (securities.length > 0)
+            rec.omittedSecurities = securities;
+    }
     const parts = [];
     if (indicators.length > 0)
         parts.push(`indicators ${indicators.join(", ")}`);
     if (securities.length > 0)
         parts.push(`securities ${securities.join(", ")}`);
-    if (parts.length > 0) {
-        process.stderr.write(`[gangtise] warning: the response omits ${parts.join(" and ")} entirely (no data for any counterpart, not null) — check scopeList coverage and the date semantics for those indicators.\n`);
+    process.stderr.write(`[gangtise] warning: the response omits ${parts.join(" and ")} entirely (no data for any counterpart, not null) — check scopeList coverage and the date semantics for those indicators. Result marked partial (exit 3).\n`);
+}
+/** Mark a screener result whose values cannot be trusted. Distinct from
+ * `partial`: no rows are missing — the numbers themselves may belong to the
+ * wrong variable. A duplicated indicator code is resolved from the EARLIEST date
+ * among its bindings, that single value lands in the first of their columns, and
+ * the rest come back null (probed 2026-08-03), so both the values shown and the
+ * set of matched securities are untrustworthy. */
+function flagUnreliable(rows, duplicated) {
+    if (rows && typeof rows === "object" && !Array.isArray(rows)) {
+        const rec = rows;
+        rec.unreliable = true;
+        rec.duplicatedIndicators = duplicated;
+    }
+}
+/** `--indicator` / `--security` are repeatable, so Commander cannot mark them
+ * required — but every matrix endpoint needs at least one of each and answers a
+ * missing one with 100001, whose hint sends the user to `--help`, which in turn
+ * showed them as optional with a `[]` default. Catch it here: no request, no
+ * round trip, and a message that names the flag. */
+function requireIndicatorScope(indicators, securities) {
+    const missing = [indicators.length === 0 ? "--indicator" : "", securities.length === 0 ? "--security" : ""].filter(Boolean);
+    if (missing.length > 0) {
+        throw new ValidationError(`${missing.join(" and ")} ${missing.length > 1 ? "are" : "is"} required (repeat the flag for multiple values)`);
     }
 }
 const indicator = new Command("indicator").description("Data indicator (EDE) APIs: search codes, cross-section, time-series, screener");
@@ -723,35 +766,83 @@ indicator.command("search").requiredOption("--keyword <text>", "Search keyword,
     });
     await printData(unwrapIndicatorData(raw), format, options.output);
 }));
-indicator.command("cross-section").option("--indicator <code>", "Indicator code, e.g. qte_close (repeat for multiple)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (repeat; union, deduped)", collectList, []).requiredOption("--date <date>", "Data date (yyyy-MM-dd); sent as each indicator's tradeDate — report-period indicators need --indicator-param 'code:reportDate=...' instead", dateArg("--date")).option("--currency <code>", "Currency: DFT/CNY/HKD/USD/EUR/GBP/JPY/TWD/MOP/AUD (default DFT)").option("--scale <code>", "Scale: 0=个 3=千 4=万 6=百万 8=亿 9=十亿 (default 0)").option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustType=2 for 前复权 (repeat); read exact keys from 'indicator search'", collectList, []).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>").action((options) => withClient(async (client) => {
+indicator.command("cross-section").option("--indicator <code>", "Indicator code, e.g. qte_close (REQUIRED, repeat for multiple)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (REQUIRED, repeat; union, deduped)", collectList, []).requiredOption("--date <date>", "Data date (yyyy-MM-dd); sent as each indicator's tradeDate — report-period indicators need --indicator-param 'code:reportDate=...' instead", dateArg("--date")).option("--currency <code>", "Currency: DFT/CNY/HKD/USD/EUR/GBP/JPY/TWD/MOP/AUD (default DFT)").option("--scale <code>", "Scale: 0=个 3=千 4=万 6=百万 8=亿 9=十亿 (default 0)").option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustType=2 for 前复权 (repeat); read exact keys from 'indicator search'", collectList, []).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>").action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
+    requireIndicatorScope(options.indicator, options.security);
     const raw = await client.call("indicator.cross-section", buildIndicatorCrossSectionBody(options));
-    const data = unwrapIndicatorData(raw);
-    warnDropped(data, options.security, options.indicator);
-    await printData(flattenCrossSection(data, options.keyBy), format, options.output);
+    const data = requireIndicatorMatrix(raw);
+    // Flatten first: a shape error must not be preceded by a dropped-rows warning
+    // that reads like the run merely came back short.
+    const rows = flattenCrossSection(data, options.keyBy);
+    flagDropped(rows, data, options.security, options.indicator);
+    await printData(rows, format, options.output);
 }));
-indicator.command("time-series").option("--indicator <code>", "Indicator code, e.g. qte_close (repeat for multiple)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (repeat; union, deduped)", collectList, []).requiredOption("--start-date <date>", "Start date (yyyy-MM-dd)", dateArg("--start-date")).requiredOption("--end-date <date>", "End date (yyyy-MM-dd)", dateArg("--end-date")).option("--calendar-type <type>", "Calendar: ND=natural TD=trading WD=weekday (default TD)").option("--currency <code>", "Currency: DFT/CNY/HKD/USD/EUR/GBP/JPY/TWD/MOP/AUD (default DFT)").option("--scale <code>", "Scale: 0=个 3=千 4=万 6=百万 8=亿 9=十亿 (default 0)").option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustType=2 for 前复权 (repeat); read exact keys from 'indicator search'", collectList, []).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>").action((options) => withClient(async (client) => {
+indicator.command("time-series").option("--indicator <code>", "Indicator code, e.g. qte_close (REQUIRED, repeat for multiple)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (REQUIRED, repeat; union, deduped)", collectList, []).requiredOption("--start-date <date>", "Start date (yyyy-MM-dd)", dateArg("--start-date")).requiredOption("--end-date <date>", "End date (yyyy-MM-dd)", dateArg("--end-date")).option("--calendar-type <type>", "Calendar: ND=natural TD=trading WD=weekday (default TD)").option("--currency <code>", "Currency: DFT/CNY/HKD/USD/EUR/GBP/JPY/TWD/MOP/AUD (default DFT)").option("--scale <code>", "Scale: 0=个 3=千 4=万 6=百万 8=亿 9=十亿 (default 0)").option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustType=2 for 前复权 (repeat); read exact keys from 'indicator search'", collectList, []).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>").action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
+    requireIndicatorScope(options.indicator, options.security);
     const raw = await client.call("indicator.time-series", buildIndicatorTimeSeriesBody(options));
-    const data = unwrapIndicatorData(raw);
-    warnDropped(data, options.security, options.indicator);
-    // Pass the REQUESTED security count: the server drops securities with no data,
-    // and deriving the axis from the response turns a single-indicator ×
-    // two-security query into an unlabelled indicator column when one is uncovered.
-    await printData(flattenTimeSeries(data, options.keyBy, options.security.length), format, options.output);
+    const data = requireIndicatorMatrix(raw);
+    // Pass the universe itself, not a count: flattenTimeSeries needs to know
+    // whether a sector ID is in play (the server expands it, so one entry can mean
+    // many securities) and dedupes internally. The request only breaks the tie when
+    // the response is 1×1 anyway. Flatten before flagging so a shape error surfaces
+    // on its own.
+    const rows = flattenTimeSeries(data, options.keyBy, options.security);
+    flagDropped(rows, data, options.security, options.indicator);
+    await printData(rows, format, options.output);
 }));
-indicator.command("screener").description("Screen securities by an expression over indicator values (条件选股)").option("--indicator <spec>", "Bind a variable to an indicator, 'F1:code', e.g. F1:qte_mkt_cptl (repeat)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (repeat; union, deduped)", collectList, []).requiredOption("--expression <expr>", "Filter over the bound variables, e.g. 'F1 >= 800 && (F2 >= 20 && F2 <= 30)'; also supports contains/notcontains on string indicators").requiredOption("--date <date>", "Data date (yyyy-MM-dd); sent as every indicator's tradeDate unless it already has one — required because the screener drops any indicator sent with no parameters at all", dateArg("--date")).option("--indicator-param <spec>", "Per-variable param 'F1:key=value', e.g. F1:scale=8 (repeat); read exact keys from 'indicator search'", collectList, []).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>").action((options) => withClient(async (client) => {
+indicator.command("screener").description("Screen securities by an expression over indicator values (条件选股)").option("--indicator <spec>", "Bind a variable to an indicator, 'F1:code', e.g. F1:qte_mkt_cptl (REQUIRED, repeat)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (REQUIRED, repeat; union, deduped)", collectList, []).requiredOption("--expression <expr>", "Filter over the bound variables, e.g. 'F1 >= 800 && (F2 >= 20 && F2 <= 30)'; also supports contains/notcontains on string indicators").requiredOption("--date <date>", "Data date (yyyy-MM-dd); sent as every indicator's tradeDate unless it already has one — omitting it leaves date-bearing indicators unfiltered and silently yields an empty screen", dateArg("--date")).option("--indicator-param <spec>", "Per-variable param 'F1:key=value', e.g. F1:scale=8 (repeat); read exact keys from 'indicator search'", collectList, []).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>").action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
-    const duplicated = duplicateScreenerCodes(parseScreenerIndicators(options.indicator, options.indicatorParam, options.expression));
+    requireIndicatorScope(options.indicator, options.security);
+    const bindings = parseScreenerIndicators(options.indicator, options.indicatorParam, options.expression);
+    const duplicated = duplicateScreenerCodes(bindings);
     if (duplicated.length > 0) {
-        process.stderr.write(`[gangtise] warning: ${duplicated.join(", ")} bound to more than one variable — the API allows this but the server currently answers such a request with an empty result (probed 2026-08-02). Split into separate calls until it is fixed.\n`);
+        process.stderr.write(`[gangtise] warning: ${duplicated.join(", ")} bound to more than one variable — the API allows this, but the server currently resolves ALL of those bindings against the EARLIEST date among them, puts that single value in the first of their columns, and leaves the rest null (probed 2026-08-03). So the surviving number is not necessarily the variable it is labelled with: a variable asking for 07-31 came back holding 07-30's price. Every part of the result is affected — the values shown, and which securities matched at all, since conditions on the null variables filtered on nothing. The same request also returns an empty set about a third of the time. Treat the WHOLE result as unusable and split into separate calls until it is fixed.\n`);
     }
     const raw = await client.call("indicator.screener", buildIndicatorScreenerBody(options));
     // Same payload shape as cross-section (one row per matched security, one
     // column per indicator) with a `field` on each indicator entry. No dropped-row
-    // warning here: a security missing from a screener result means it failed the
+    // flag here: a security missing from a screener result means it failed the
     // filter, which is the whole point.
-    await printData(flattenCrossSection(unwrapIndicatorData(raw), options.keyBy), format, options.output);
+    const data = requireIndicatorMatrix(raw);
+    // Before anything is rendered: the returned bindings must be the ones that
+    // were asked for, and the expression must still be evaluable from the columns
+    // that came back — otherwise the rows cannot be shown to satisfy the
+    // conditions they claim to. See checkScreenerBindings for how a missing column
+    // is weighed against the expression's boolean structure.
+    // Flatten first: it asserts the payload's structural axes, and a response
+    // missing `indicatorList` outright deserves that diagnosis rather than being
+    // reported as a binding problem. Nothing renders in between, so ordering the
+    // structural check ahead of the semantic one is free.
+    const rows = flattenCrossSection(data, options.keyBy);
+    const filteredOn = screenerExpressionFields(options.expression);
+    const unbound = checkScreenerBindings(data, bindings, options.expression);
+    // Same ambiguity as the other matrix commands: an empty screen is a normal
+    // answer AND what a wrong parameter name produces. Keyed on "nothing matched"
+    // rather than the strict canonical-empty shape — a response that returns zero
+    // securities while still echoing `indicatorList` is just as empty to the
+    // caller, and just as ambiguous, but would slip past isEmptyMatrix.
+    // flattenCrossSection above already asserted this is an array of non-empty
+    // strings, so only its length is left to read.
+    if (data.securityCodeList.length === 0) {
+        process.stderr.write("[gangtise] note: nothing matched the expression. That is a normal answer — but since 2026-08-01 an empty result is ALSO what a wrong parameter name or the wrong date field produces. Cross-check the indicator parameters against 'gangtise indicator search --format json'.\n");
+    }
+    if (unbound.length > 0) {
+        // Whatever reached here still leaves the expression evaluable (or was never
+        // read by it), so the rows stand: losing the column costs information, not
+        // correctness, and it degrades rather than failing.
+        const rec = rows;
+        rec.partial = true;
+        rec.omittedIndicators = unbound.map((field) => bindings.find((b) => b.field === field)?.indicatorCode ?? field);
+        const alsoFiltered = unbound.filter((field) => filteredOn.includes(field));
+        const filterNote = alsoFiltered.length > 0
+            ? ` The expression also filters on ${alsoFiltered.join(", ")}, so that condition was applied to none of these rows — another branch of the expression could still have matched them legitimately, but verify before relying on that filter.`
+            : "";
+        process.stderr.write(`[gangtise] warning: ${unbound.join(", ")} produced no column at all (no data for any matched security) — those output values are missing.${filterNote} Result marked partial (exit 3).\n`);
+    }
+    if (duplicated.length > 0)
+        flagUnreliable(rows, duplicated);
+    await printData(rows, format, options.output);
 }));
 program.addCommand(indicator);
 const tool = new Command("tool").description("Research tool APIs: PDF parsing");
@@ -832,12 +923,64 @@ async function checkForUpdate(timeoutMs = 2000) {
     }
     catch { /* best-effort: offline or a slow registry must not break --version */ }
 }
-// `gangtise ... | head` closes stdout early; without a handler the final big write
-// crashes Node with an unhandled 'error' event. Exit quietly like a normal CLI.
+/** Last-resort reporting for anything that escapes main()'s try/catch: an error
+ * thrown inside an event callback or a rejected promise nobody awaited. Node's
+ * default is a multi-line crash dump on stdout/stderr AND a non-zero exit — so a
+ * command whose data was already printed correctly would end up looking like a
+ * hard failure, with a stack trace where a message belongs. This release is
+ * about exit codes meaning what they say; that is the one path that lies.
+ *
+ * The stack is kept behind --verbose: reaching here at all means a CLI bug
+ * rather than an API failure, and one line is not enough to locate one. */
+/** Milliseconds to let already-queued stdout reach the pipe before leaving. */
+const FATAL_FLUSH_MS = 200;
+let leaving = false;
+function reportFatal(error) {
+    // `error.stack` already opens with "Name: message" — printing both duplicates
+    // the first line.
+    const stack = error instanceof Error ? error.stack : undefined;
+    const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+    const text = `${isVerbose() && stack ? stack : message}\n`;
+    if (leaving) {
+        process.stderr.write(text);
+        return;
+    }
+    leaving = true;
+    process.exitCode = 1;
+    // Terminating is not optional: a fatal error with a live handle (a timer, an
+    // open socket) would otherwise keep the process running forever on `exitCode`
+    // alone. But `process.exit()` on the spot truncates whatever is still queued —
+    // to a pipe BOTH streams are written asynchronously — and a handler meant to
+    // stop this release from lying about exit codes must not start dropping output
+    // to do it. So wait for the diagnostic itself AND for anything stdout still
+    // owes, each bounded by the same deadline.
+    //
+    // stderr is not merely "check the length": the write is issued right here, so
+    // its callback is the only thing that knows when it actually reached the pipe.
+    // Exiting on the spot truncated a large diagnostic to one 64 KiB buffer.
+    let pending = 1;
+    const leave = () => { if (--pending === 0)
+        process.exit(1); };
+    if (process.stdout.writableLength > 0) {
+        pending++;
+        process.stdout.once("drain", leave);
+    }
+    setTimeout(() => process.exit(1), FATAL_FLUSH_MS);
+    process.stderr.write(text, leave);
+}
+process.on("uncaughtException", reportFatal);
+process.on("unhandledRejection", reportFatal);
+/** Teardown races on a closed stdout: the reader went away, which is not this
+ * process's failure. `gangtise ... | head` is the everyday case — it truncates
+ * the output and still exits 0, so a same-class race has no principled reason to
+ * exit 1. Without a handler the final write crashes Node with an unhandled
+ * 'error' event; rethrowing from this callback did the same by another route
+ * (a crash dump appended AFTER the correct JSON had already been written). */
+const READER_GONE = new Set(["EPIPE", "ERR_STREAM_DESTROYED", "EBADF"]);
 process.stdout.on("error", (error) => {
-    if (error?.code === "EPIPE")
+    if (error?.code && READER_GONE.has(error.code))
         process.exit(0);
-    throw error;
+    reportFatal(error);
 });
 async function main() {
     // Positional check, not argv.includes: "--version" appearing later (e.g. as

package/dist/src/core/args.js

@@ -288,6 +288,100 @@ const SCREENER_FIELD = /^F[1-9][0-9]*$/;
  * `contains 'F2 系列'` operand is not mistaken for a reference. */
 const SCREENER_FIELD_REF = /\bF[1-9][0-9]*\b/g;
 const SCREENER_STRING_LITERAL = /'[^']*'|"[^"]*"/g;
+/** Split an expression into `(`, `)`, `&&`, `||` and the atoms between them.
+ * String literals are copied verbatim so a `||` or an `F2` inside one is never
+ * mistaken for syntax. */
+function tokenizeScreenerExpression(src) {
+    const tokens = [];
+    let atom = "";
+    const flush = () => {
+        if (atom.trim())
+            tokens.push(atom);
+        atom = "";
+    };
+    for (let i = 0; i < src.length;) {
+        const ch = src[i];
+        if (ch === "'" || ch === '"') {
+            const close = src.indexOf(ch, i + 1);
+            const stop = close === -1 ? src.length : close + 1;
+            atom += src.slice(i, stop);
+            i = stop;
+        }
+        else if (src.startsWith("&&", i) || src.startsWith("||", i)) {
+            flush();
+            tokens.push(src.slice(i, i + 2));
+            i += 2;
+        }
+        else if (ch === "(" || ch === ")") {
+            flush();
+            tokens.push(ch);
+            i += 1;
+        }
+        else {
+            atom += ch;
+            i += 1;
+        }
+    }
+    flush();
+    return tokens;
+}
+/** Whether the expression still has a path that could have been evaluated, given
+ * the variables the response actually returned a column for.
+ *
+ * The boolean structure decides, not the mere presence of a `||`:
+ *   - a term is evaluable when every variable it names has a column;
+ *   - `A && B` needs BOTH sides — a missing mandatory conjunct is an unprovable
+ *     claim even if the other side is a disjunction;
+ *   - `A || B` needs only one — a row can legitimately match through one operand
+ *     while the other is not evaluable at all (probed 2026-08-03: `F1 > 0 || F2
+ *     > 0` over 09992.HK, where `finc_pe_ttm` has no HK coverage, matches on F2).
+ *
+ * So `F1 && (F2 || F3)` missing F1, and `F1 || F2` missing both, are both
+ * unevaluable and must fail — checking only for a `||` anywhere would let them
+ * through. */
+export function screenerExpressionIsEvaluable(expression, present) {
+    const tokens = tokenizeScreenerExpression(expression ?? "");
+    let pos = 0;
+    const unit = () => {
+        if (tokens[pos] === "(") {
+            pos += 1;
+            const value = or();
+            if (tokens[pos] === ")")
+                pos += 1;
+            return value;
+        }
+        const atom = tokens[pos++] ?? "";
+        // A term naming no variable (a literal comparison) is always evaluable.
+        return (atom.replace(SCREENER_STRING_LITERAL, "").match(SCREENER_FIELD_REF) ?? []).every((ref) => present.has(ref));
+    };
+    const and = () => {
+        let value = unit();
+        // Evaluate both sides before combining: short-circuiting would leave the
+        // parser mid-expression.
+        while (tokens[pos] === "&&") {
+            pos += 1;
+            const right = unit();
+            value = value && right;
+        }
+        return value;
+    };
+    const or = () => {
+        let value = and();
+        while (tokens[pos] === "||") {
+            pos += 1;
+            const right = and();
+            value = value || right;
+        }
+        return value;
+    };
+    return or();
+}
+/** Variables the expression actually filters on, string literals stripped. These
+ * are the bindings whose VALUES the result depends on — a column missing for one
+ * of them means the filter cannot be shown to have been applied. */
+export function screenerExpressionFields(expression) {
+    return (expression ?? "").replace(SCREENER_STRING_LITERAL, "").match(SCREENER_FIELD_REF) ?? [];
+}
 // Parse the screener's `--indicator "F1:code"` bindings and merge each one's
 // `--indicator-param "F1:key=value"` specs. Params key off the variable, not the
 // code, because the same indicator may legitimately appear under two variables
@@ -320,7 +414,7 @@ export function parseScreenerIndicators(bindings, paramSpecs, expression) {
     // The server does reject this (100003), but only after a round trip — and the
     // symmetric mistake (binding a variable the expression never uses) it accepts
     // silently while still billing the extra column.
-    for (const ref of (expression ?? "").replace(SCREENER_STRING_LITERAL, "").match(SCREENER_FIELD_REF) ?? []) {
+    for (const ref of screenerExpressionFields(expression)) {
         if (!indicators.has(ref)) {
             throw new ValidationError(`--expression references "${ref}", which no --indicator binds`);
         }
@@ -329,10 +423,16 @@ export function parseScreenerIndicators(bindings, paramSpecs, expression) {
 }
 /** Indicator codes bound to more than one screener variable, in first-seen
  * order. The API is specified to allow this (one code under two variables with
- * different parameters), but the server currently answers such a request with an
- * empty result set — probed 2026-08-02. Callers warn rather than reject: the
- * capability is intended and a server-side fix is in flight, so a hard block
- * here would have to be reverted. */
+ * different parameters), but the server currently mis-resolves it — probed
+ * 2026-08-03: ALL such bindings are answered from the EARLIEST date among them,
+ * that one value lands in the first of their columns, and the rest come back
+ * null. The surviving number therefore need not belong to the variable it is
+ * labelled with, so it is not merely "one column is missing": the values shown
+ * and the set of matched securities are both untrustworthy. (The same request
+ * also returns an empty set roughly a third of the time.)
+ *
+ * Callers warn rather than reject: the capability is intended and a server-side
+ * fix is in flight, so a hard block here would have to be reverted. */
 export function duplicateScreenerCodes(indicators) {
     const seen = new Set();
     const duplicated = new Set();

package/dist/src/core/client.js

@@ -436,7 +436,7 @@ export class GangtiseClient {
             // instead of nonsensical date/scope/param guidance.
             const isIndicatorFetch = endpoint.key === 'indicator.cross-section' || endpoint.key === 'indicator.time-series' || endpoint.key === 'indicator.screener';
             if (isIndicatorFetch && error instanceof ApiError && error.code === '999999') {
-                throw new ApiError(error.message, error.code, error.statusCode, error.details, error.retryAfterMs, 'EDE 取数故障。先核对参数再重试：参数名以 indicator search 的 parameterList 为准（传错名是静默失效）、日期匹配指标周期（财务/MRQ 用报告期末如 2025-12-31、日频估值用交易日）、标的在 scopeList 覆盖内、required 参数已补。注意「查询无数据」现在返回空表而不是此码。');
+                throw new ApiError(error.message, error.code, error.statusCode, error.details, error.retryAfterMs, 'EDE 取数故障。先核对参数再重试：参数名以 indicator search 的 parameterList 为准（传错名是静默失效）、日期匹配指标周期（财务报表类用报告期末如 2025-12-31，PE/PB 等日频估值用交易日）、标的在 scopeList 覆盖内、required 参数已补。注意「查询无数据」现在返回空表而不是此码。');
             }
             throw error;
         });

package/dist/src/core/commandBodies.js

@@ -92,11 +92,15 @@ export function buildIndicatorScreenerBody(options) {
         universe: maybeArray(options.security),
         expression: options.expression,
         // Every indicator gets a date, including ones whose parameterList is empty.
-        // That is not just convenience: the screener drops any indicator sent with
-        // `parameters: []` — probed 2026-08-02, `pty_op_scope` + `F1 contains '酒'`
-        // matches nothing with an empty list and correctly returns 五粮液/贵州茅台
-        // with a (for that indicator meaningless) tradeDate attached. The official
-        // doc's own `F3 contains '酒'` example cannot work as written.
+        // Harmless there (a parameterless indicator answers normally with a stray
+        // tradeDate), and it keeps one rule for the whole list rather than a
+        // per-indicator exception.
+        //
+        // It also used to be load-bearing: through 2026-08-02 the screener DROPPED
+        // any indicator sent with `parameters: []`, so the official doc's own
+        // `F3 contains '酒'` example could not work as written. Re-probed 2026-08-03:
+        // fixed server-side. Kept anyway — unconditional is simpler than conditional,
+        // and it survives a rollback.
         indicatorList: indicators.map((indicator) => (indicator.parameters.some((param) => DATE_PARAM_KEYS.has(param.paramKey))
             ? indicator
             : { ...indicator, parameters: [...indicator.parameters, { paramKey: "tradeDate", paramValue: options.date }] })),

package/dist/src/core/errors.js

@@ -130,8 +130,10 @@ export class ApiError extends CliError {
     /** Server-specified Retry-After (ms), set on 429 responses so the transport
      * backoff can honor it instead of the default exponential schedule. */
     retryAfterMs, 
-    /** Context-specific hint that beats the generic per-code table — e.g. EDE's
-     * 999999 means "no data", not the table's "系统错误，请稍后重试". */
+    /** Context-specific hint that beats the generic per-code table — e.g. the
+     * EDE fetch endpoints replace 999999's generic "系统错误，请稍后重试" with a
+     * parameter checklist, because a wrong param name or date axis there yields
+     * an empty TABLE rather than this code. */
     hintOverride) {
         super(message);
         this.code = code;