gangtise-openapi-cli 0.30.0 → 0.31.0

package/README.md

@@ -6,12 +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 文档。
-- **v0.28.1 — 2026-07-23**：调整 Agent Skill 取数路由，多证券财务与估值指标优先使用 EDE 批量接口。
-- **v0.28.0 — 2026-07-21**：适配新版错误码，强化日期校验、异步状态处理、可观测性与计费安全。
 
 ### 历史里程碑
 
@@ -298,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 格式不输出该行）
 
 ## 智能文件命名
@@ -576,12 +576,13 @@ gangtise indicator cross-section \
   --date 2026-07-31 --format table
 # 输出列：security / name / <各指标名>…（v0.30.0 起无 date 列——日期挂在每个指标的参数上）
 
-# 时间序列：多指标 × 单证券 或 单指标 × 多证券（不能多 × 多，否则报 410001）
+# 时间序列：多指标 × 单证券 或 单指标 × 多证券（不能多 × 多，否则报 100003）
 gangtise indicator time-series --indicator qte_close \
   --security 600519.SH --security 09992.HK \
   --start-date 2026-07-29 --end-date 2026-07-31 --format table
 
 # 条件选股：F1/F2… 绑定指标，用表达式组合筛选（--indicator-param 按变量索引，不是按 code）
+# --date 必填：绝大多数指标吃 tradeDate，漏传就是空表 + 退出码 0
 gangtise indicator screener \
   --indicator F1:qte_mkt_cptl --indicator F2:finc_pe_ttm \
   --indicator-param "F1:scale=8" \
@@ -589,16 +590,25 @@ gangtise indicator screener \
   --expression "F1 >= 500 && F2 <= 30" \
   --date 2026-07-31 --format table
 
+# 文本筛选：经营范围含「酒」（contains/notcontains 只对 string 类型指标有效）
+gangtise indicator screener --indicator F1:pty_op_scope \
+  --security 1000000287 --expression "F1 contains '酒'" \
+  --date 2026-07-31 --format table
+
 # 复权 / 指标专属参数用 --indicator-param "code:key=value"
 # ⚠️ 参数名必须以 search 的 parameterList 为准：传错名服务端静默忽略、退回默认值，不报错
 gangtise indicator cross-section --indicator qte_close --security 600519.SH \
   --date 2024-01-02 --indicator-param "qte_close:adjustType=3"   # 1不复权/2前复权/3后复权/4定点
 # 不复权 1685.01 → 前复权 1531.225 → 后复权 13609.6168（前复权在最新交易日等于不复权，验证要用历史日）
 
-# 必填参数：很多指标默认调用报 410106（缺必填参数），按 parameterList 的 required 补齐再取：
-#   N 期统计补 periodNum、区间/周期类（如 qte_amp_mo 月振幅）补 startDate、年度/分红类补 fiscalYear
+# 必填参数：部分指标缺必填参数会报 140002，按 parameterList 的 required 补齐再取：
+#   N 期统计补 periodNum、区间类补 sDate（起始日，tradeDate 仍是终点）、年度/分红类补 fiscalYear
 gangtise indicator cross-section --indicator finc_roe_avg_avg --security 600519.SH \
   --date 2026-03-31 --indicator-param "finc_roe_avg_avg:periodNum=4"
+
+# 区间指标：sDate 是起点、--date 下发的 tradeDate 是终点，两者共存
+gangtise indicator cross-section --indicator qte_vol_intvl --security 600519.SH \
+  --date 2024-01-31 --indicator-param "qte_vol_intvl:sDate=2024-01-02"
 ```
 
 ### Alternative（行业指标数据库 EDB）
@@ -696,6 +706,7 @@ CLI 会在本地校验常见数值参数，避免把明显非法的请求发到
 | `999012` / `999013` / `999014` | 账号禁用 / 已过期 / 租户失效 |
 | `999016` | 调用方 IP 不在允许范围 |
 | `999999` | Gangtise 系统错误，请稍后重试（`indicator` 端点无数据已改为返回空表，此码基本只剩真故障） |
+| `140002` | 终态失败：AI 异步生成失败，或 `indicator` 的参数/表达式错误（枚举越界、语法错）——改参数重提，不重试 |
 | `100003` | 参数值非法——**最宽的兜底码**；msg 通常已指明字段（如「limit 最小为 1，最大为 10000」），先读 msg |
 | `100001` | 缺必填参数（msg 带字段名，如「缺少必填参数: reportId」） |
 | `100006` | 查询/下载数量超限——**取代旧 `430007`** |

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, isVersionNewer, localDateString, maybeArray, parseChoiceList, parseFrom, parseNumberOption, parseOptionalNumberOption, 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 { 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,7 +697,67 @@ 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);
-const indicator = new Command("indicator").description("Data indicator (EDE) APIs: search codes, cross-section, time-series");
+/** 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.
+ *
+ * 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(", ")}`);
+    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");
 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>").action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
     const raw = await client.call("indicator.search", {
@@ -706,22 +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));
-    await printData(flattenCrossSection(unwrapIndicatorData(raw), 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));
-    await printData(flattenTimeSeries(unwrapIndicatorData(raw), options.keyBy), 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").option("--date <date>", "Data date (yyyy-MM-dd); sent as each indicator's tradeDate unless it already has one", 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);
+    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 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.
-    await printData(flattenCrossSection(unwrapIndicatorData(raw), options.keyBy), format, options.output);
+    // column per indicator) with a `field` on each indicator entry. No dropped-row
+    // flag here: a security missing from a screener result means it failed the
+    // filter, which is the whole point.
+    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");
@@ -802,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

@@ -283,11 +283,110 @@ export function parseIndicatorParams(specs) {
  * else, and a typo'd variable would otherwise surface as an opaque expression
  * error rather than pointing at the binding that is wrong. */
 const SCREENER_FIELD = /^F[1-9][0-9]*$/;
+/** Variable references inside a screener expression, e.g. the F1/F2 in
+ * `F1 >= 800 && F2 <= 30`. String literals are stripped first, so a
+ * `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
 // with different parameters (e.g. the same price on two dates).
-export function parseScreenerIndicators(bindings, paramSpecs) {
+export function parseScreenerIndicators(bindings, paramSpecs, expression) {
     const params = parseParamSpecs(paramSpecs, "--indicator-param", "F1:key=value");
     const indicators = new Map();
     for (const spec of bindings) {
@@ -312,5 +411,35 @@ export function parseScreenerIndicators(bindings, paramSpecs) {
             throw new ValidationError(`--indicator-param references "${field}", which no --indicator binds`);
         }
     }
+    // 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 screenerExpressionFields(expression)) {
+        if (!indicators.has(ref)) {
+            throw new ValidationError(`--expression references "${ref}", which no --indicator binds`);
+        }
+    }
     return [...indicators.values()];
 }
+/** 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 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();
+    for (const { indicatorCode } of indicators) {
+        if (seen.has(indicatorCode))
+            duplicated.add(indicatorCode);
+        seen.add(indicatorCode);
+    }
+    return [...duplicated];
+}

package/dist/src/core/client.js

@@ -426,15 +426,17 @@ export class GangtiseClient {
                 process.stderr.write(`[gangtise] retry ${attempt} after ${delay.toFixed(0)}ms: ${msg.slice(0, 120)}\n`);
             },
         }).catch((error) => {
-            // EDE uses 999999 for "no data for this query" (probed 2026-07-11) — the
-            // generic "系统错误，请稍后重试" hint would send the user retrying a query
-            // that will never have data. Swap in a fetch-specific hint. Only the data
+            // Until 2026-08-01 EDE answered a no-data query with 999999, so this hint
+            // led with "多为查询无数据". No-data now comes back as an empty array, which
+            // leaves 999999 meaning an actual server fault — but the parameter checklist
+            // is still the right first move, because a wrong param name or date axis
+            // silently yields an EMPTY TABLE rather than this error. Only the data
             // endpoints take a date/security/params; indicator.search shares the
             // no-999999 policy but has just a keyword, so it keeps the generic hint
             // instead of nonsensical date/scope/param guidance.
-            const isIndicatorFetch = endpoint.key === 'indicator.cross-section' || endpoint.key === 'indicator.time-series';
+            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 的 999999 多为查询无数据——先核对：日期匹配指标周期（财务/MRQ 用报告期末如 2025-12-31、日频估值用交易日）、标的在 scopeList 覆盖内、parameterList 中 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

@@ -34,15 +34,21 @@ export function buildStockPoolStocksBody(options) {
         poolIdList: options.poolId?.length ? options.poolId : ["all"],
     };
 }
-/** Parameter keys that carry an indicator's own query date. The 2026-08-01 EDE
+/** Parameter keys that REPLACE an indicator's `tradeDate`. The 2026-08-01 EDE
  * revision dropped the root-level `date`, so `--date` now fans out into each
- * indicator's `tradeDate`. Report-period indicators read `reportDate`/`sDate`
- * instead and answer a `tradeDate` with an EMPTY result rather than an error
- * (probed 2026-08-01 on `is_op_rev_mom`), so a caller-supplied date of any of
- * these kinds suppresses the injection for that indicator. Injecting into an
- * indicator that takes no date at all is harmless — `pty_op_scope` still
- * answers normally with a stray `tradeDate` attached. */
-const DATE_PARAM_KEYS = new Set(["tradeDate", "reportDate", "sDate"]);
+ * indicator's `tradeDate`. Report-period indicators read `reportDate` instead
+ * and answer a `tradeDate` with an EMPTY result rather than an error (probed
+ * 2026-08-01 on `is_op_rev_mom`), so a caller-supplied `reportDate` suppresses
+ * the injection for that indicator. Injecting into an indicator that takes no
+ * date at all is harmless — `pty_op_scope` still answers normally with a stray
+ * `tradeDate` attached.
+ *
+ * `sDate` is deliberately NOT here. It is an interval START, not a substitute:
+ * `qte_vol_intvl` declares `tradeDate` required (the interval END) and `sDate`
+ * optional. Treating it as a replacement dropped `--date` and silently moved the
+ * interval end — probed 2026-08-02, 茅台 sDate=2024-01-02 returned 2,265,873,849
+ * without a tradeDate vs 65,687,435 with tradeDate=2024-01-31, both exit 0. */
+const DATE_PARAM_KEYS = new Set(["tradeDate", "reportDate"]);
 function withQueryDate(groups, codes, date) {
     const merged = new Map();
     for (const group of groups ?? [])
@@ -81,14 +87,22 @@ export function buildIndicatorTimeSeriesBody(options) {
     };
 }
 export function buildIndicatorScreenerBody(options) {
-    const indicators = parseScreenerIndicators(options.indicator, options.indicatorParam);
+    const indicators = parseScreenerIndicators(options.indicator, options.indicatorParam, options.expression);
     return {
         universe: maybeArray(options.security),
         expression: options.expression,
-        indicatorList: options.date
-            ? indicators.map((indicator) => (indicator.parameters.some((param) => DATE_PARAM_KEYS.has(param.paramKey))
-                ? indicator
-                : { ...indicator, parameters: [...indicator.parameters, { paramKey: "tradeDate", paramValue: options.date }] }))
-            : indicators,
+        // Every indicator gets a date, including ones whose parameterList is empty.
+        // 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

@@ -83,7 +83,10 @@ const ERROR_HINTS = {
     "130004": "下载 ID 需为数字，检查该命令的 --*-id 参数是否传对。",
     "130005": "对照命令 --help 检查 --file-type / --content-type 取值。",
     "140001": "稍后用对应 *-check 命令查询。",
-    "140002": "异步生成失败（终态）——换参数重新提交，重试同一 dataId 不会变。",
+    // 两类来源共用此码：AI 异步生成失败，以及 EDE 的参数/表达式错误（实测 2026-08-02：
+    // 枚举越界「参数 adjustType 的值 99 不在有效范围内 [1,2,3,4]」、表达式语法错误）。
+    // 两者都是终态、都不该重试，所以文案只说「换参数重来」而不预设是哪一类。
+    "140002": "终态失败，重试同一请求不会变——按 msg 改参数后重新提交；EDE 的指标参数名/枚举以 indicator search 的 parameterList 为准。",
     // ── 接口专有 2xxxxx ──
     "210001": "换一篇，或改用 list 取正文摘要。",
     "220001": "改用 list 取正文摘要。",
@@ -98,10 +101,11 @@ const ERROR_HINTS = {
     "900001": "对照命令 --help 检查必填项。",
     "900002": "请求方法不正确（服务端 msg 为「请求类型有误」）——`raw call` 时检查该 endpoint 是 GET 还是 POST。",
     "903301": "次日再试，或联系客户经理提额。",
-    // EDE 专有旧码，未被 2026-07-17 重排收编但仍是 indicator 取数的主要报错
-    // （references/commands/indicator.md 把这两个列为首要排查项）。
+    // EDE 专有旧码。2026-08-02 复测已不再出现——入参/表达式错走 100003，指标必填
+    // 参数缺失与枚举越界走 140002。保留兜底：错误码是按模块分批迁移的，回滚或未迁完
+    // 的路径仍可能吐旧码，届时给条能用的提示比 fallthrough 强。
     "410001": "补齐 --indicator / --security；`time-series` 不支持「多指标 × 多证券」，改用 `indicator cross-section`。",
-    "410106": "读 `indicator search --format json` 的 parameterList，用 --indicator-param 补上 required:true 的参数（如 periodNum / startDate / fiscalYear）。",
+    "410106": "读 `indicator search --format json` 的 parameterList，用 --indicator-param 补上 required:true 的参数（如 periodNum / sDate / fiscalYear）。",
     "410004": "换证券或日期确认该条件下本应有数据；仍失败多为未开通该指标，联系客户经理。",
     "410110": "稍后用对应 *-check 命令查询。",
     "410111": "终态，换参数后重新提交，重试同一请求不会变。",
@@ -126,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;