gangtise-openapi-cli 0.30.0 → 0.31.0

package/dist/src/core/indicatorMatrix.js

@@ -1,4 +1,5 @@
-import { ApiError } from "./errors.js";
+import { screenerExpressionFields, screenerExpressionIsEvaluable } from "./args.js";
+import { ApiError, attachEnvelopeTraceId, ENVELOPE_TRACE_ID } from "./errors.js";
 // The EDE endpoints double-wrap on success: the shared client strips the outer
 // envelope but leaves an inner { code, status, data } around the real payload.
 // Peel that inner envelope so the list (search) / matrix (cross-section,
@@ -22,8 +23,12 @@ export function unwrapIndicatorData(raw) {
                 // 999999 / 130001 that most need reporting — reach the user trace-less.
                 throw new ApiError(typeof record.msg === "string" && record.msg ? record.msg : "Indicator API request failed", code, undefined, record);
             }
+            // Carry the envelope's traceId onto the inner payload. `unwrapEnvelope`
+            // attached it to THIS object, but everything downstream (the flatteners'
+            // shape guards) only ever sees `record.data` — without this hand-off those
+            // failures, exactly the ones support needs to trace, arrive trace-less.
             if (ok && "data" in record)
-                return record.data;
+                return attachEnvelopeTraceId(record.data, record[ENVELOPE_TRACE_ID] ?? record.traceId);
         }
     }
     return raw;
@@ -31,10 +36,33 @@ export function unwrapIndicatorData(raw) {
 function asStringArray(value) {
     return Array.isArray(value) ? value.map((item) => String(item)) : undefined;
 }
-function asIndicatorMetaList(value) {
+/** An IDENTITY axis — the security codes a row belongs to, the dates a column
+ * belongs to. `String(item)` would turn a `null` into the literal `"null"` and
+ * render it as a perfectly plausible label (probed 2026-08-02: `dates: [null]`
+ * produced `date: "null"`, `securityCodeList: [null]` produced
+ * `security: "null"`), so a fabricated identity would reach the output at exit
+ * 0. Nothing here may be coerced: every entry must already be a non-empty string. */
+function asIdentityArray(data, value, key) {
     if (!Array.isArray(value))
         return undefined;
-    return value.map((item) => (item && typeof item === "object" && !Array.isArray(item) ? item : {}));
+    const bad = value.findIndex((item) => typeof item !== "string" || item.trim() === "");
+    if (bad !== -1) {
+        throw new ApiError(`Indicator matrix shape mismatch: ${key}[${bad}] is not a usable identifier (${JSON.stringify(value[bad])}) — rows would be labelled with a value that identifies nothing`, undefined, undefined, data);
+    }
+    return value;
+}
+/** Indicator metadata is an identity axis too: `--key-by code` addresses columns
+ * by `code`, so an entry without one cannot be mapped back to what was asked
+ * for. A non-object entry used to collapse into `{}` and surface as `col0`. */
+function asIndicatorMetaList(data, value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const bad = value.findIndex((item) => !item || typeof item !== "object" || Array.isArray(item)
+        || typeof item.code !== "string" || String(item.code).trim() === "");
+    if (bad !== -1) {
+        throw new ApiError(`Indicator matrix shape mismatch: indicatorList[${bad}] carries no usable \`code\` (${JSON.stringify(value[bad])}) — the column could not be mapped back to a requested indicator`, undefined, undefined, data);
+    }
+    return value;
 }
 function optionalString(value) {
     return value === undefined || value === null ? undefined : String(value);
@@ -76,26 +104,257 @@ function indicatorHeaders(indicators, keyBy, reserved) {
     const codes = indicators.map((meta) => optionalString(meta.code));
     const fields = indicators.map((meta, i) => optionalString(meta.field) ?? codes[i]);
     const bases = keyBy === "code" ? codes : indicators.map((meta) => optionalString(meta.name));
-    return buildHeaders(bases, fields, reserved);
+    // On a screener payload every column carries its variable, so a repeated base
+    // can suffix ALL of its occurrences instead of leaving the first one bare.
+    // A bare `收盘价` next to `收盘价 (F2)` reads as "the" close price when it is
+    // really just whichever variable the server happened to list first.
+    const screener = indicators.some((meta) => meta.field !== undefined);
+    if (!screener)
+        return buildHeaders(bases, fields, reserved);
+    const repeated = new Set(bases.filter((base, i) => base !== undefined && bases.indexOf(base) !== i));
+    return buildHeaders(bases.map((base, i) => (base !== undefined && repeated.has(base) ? `${base} (${fields[i] ?? i})` : base)), fields, reserved);
 }
 const CROSS_SECTION_COLUMNS = ["security", "name"];
+/** A response carrying neither securities nor indicators: the query as a whole
+ * resolved to nothing. This is NOT a dropped axis — nothing was left out, there
+ * simply is no data (a non-trading range, a date outside coverage), so it must
+ * not be reported as partial. Calling every requested code "omitted" here would
+ * be false metadata: the diff against the request is total by construction.
+ *
+ * The check covers every STRUCTURAL array, not just the two axis lists, because
+ * accepting anything looser would let a malformed payload — `values: null`, a
+ * missing `values`, or dates with no matrix — pass as "legitimately empty" and
+ * exit 0, which is precisely the protocol regression this release's shape guards
+ * exist to catch. Required empty: `securityCodeList`, `indicatorList`, `values`;
+ * plus `dates` when present. Probed 2026-08-02: a time-series no-data answer is
+ * five empty arrays, a cross-section one is four (it carries no `dates` key at
+ * all), hence "absent or empty" rather than a flat count.
+ *
+ * `securityNameList` is deliberately NOT checked: it holds display labels, not
+ * structure, so a `null` there cannot misalign anything — and rejecting it would
+ * re-introduce the false-partial this function exists to prevent. */
+export function isEmptyMatrix(data) {
+    if (!data || typeof data !== "object")
+        return false;
+    const d = data;
+    if (asStringArray(d.securityCodeList)?.length !== 0)
+        return false;
+    if (!Array.isArray(d.indicatorList) || d.indicatorList.length !== 0)
+        return false;
+    if (!Array.isArray(d.values) || d.values.length !== 0)
+        return false;
+    // `dates` is time-series only; when present it must be empty too.
+    return d.dates === undefined || (Array.isArray(d.dates) && d.dates.length === 0);
+}
+/** Validate the variable bindings a screener answered with, returning the bound
+ * variables that are merely missing (see below).
+ *
+ * The screener answers with the variable each column was requested under, and
+ * that binding is the ONLY thing tying a column back to the filter it came from
+ * — nothing else in the payload can catch it going wrong. A swapped or unknown
+ * `field` renders as a perfectly ordinary result (probed 2026-08-02: a response
+ * labelling a requested `F1` as `F9` printed a normal table at exit 0), which
+ * would make every screening decision downstream unfounded.
+ *
+ * Every returned entry must therefore name a REQUESTED variable and carry that
+ * variable's code, and no variable may appear twice. A wholly empty result binds
+ * nothing and is left alone. */
+export function checkScreenerBindings(data, requested, expression) {
+    if (!data || typeof data !== "object")
+        return [];
+    const d = data;
+    // A result with no securities matched nothing and binds nothing — the
+    // canonical empty answer, left alone.
+    if (!Array.isArray(d.securityCodeList) || d.securityCodeList.length === 0)
+        return [];
+    const indicators = Array.isArray(d.indicatorList) ? d.indicatorList : [];
+    const wanted = new Map(requested.map((binding) => [binding.field, binding.indicatorCode]));
+    const seen = new Set();
+    for (const [i, meta] of indicators.entries()) {
+        const field = optionalString(meta?.field);
+        const code = optionalString(meta?.code);
+        if (!field || !wanted.has(field)) {
+            throw new ApiError(`Screener binding mismatch: indicatorList[${i}] is bound to ${field ? `"${field}"` : "no variable"}, which --indicator never requested — the column cannot be traced to a filter`, undefined, undefined, data);
+        }
+        if (wanted.get(field) !== code) {
+            throw new ApiError(`Screener binding mismatch: variable ${field} came back as "${code}" but was requested as "${wanted.get(field)}" — the filter and the column disagree`, undefined, undefined, data);
+        }
+        if (seen.has(field)) {
+            throw new ApiError(`Screener binding mismatch: variable ${field} appears twice in the response — the mapping back to a filter is ambiguous`, undefined, undefined, data);
+        }
+        seen.add(field);
+    }
+    // Securities came back, so the filter ran. A column vanishing is never "it got
+    // filtered out" — filtering removes securities (rows), never indicators
+    // (columns); the absence means that indicator had no data for any matched
+    // security. What that implies depends on how the expression combines terms:
+    //
+    // The answer follows the expression's BOOLEAN STRUCTURE, not the mere presence
+    // of a `||` — see screenerExpressionIsEvaluable. If no branch survives the
+    // missing columns, the rows cannot be shown to satisfy anything and the result
+    // is fatal; if some branch still could have matched, the absence proves nothing
+    // wrong and it degrades to partial.
+    const missing = [...wanted.keys()].filter((field) => !seen.has(field));
+    if (!screenerExpressionIsEvaluable(expression, seen)) {
+        const absent = [...new Set(screenerExpressionFields(expression))].filter((field) => !seen.has(field));
+        throw new ApiError(`Screener binding mismatch: the expression cannot be evaluated from what came back — ${absent.join(", ")} ${absent.length > 1 ? "have" : "has"} no column, and no branch of the expression survives without ${absent.length > 1 ? "them" : "it"}, so the rows cannot be shown to satisfy it`, undefined, undefined, data);
+    }
+    // Whatever survives is an output column that went missing: information lost,
+    // correctness intact.
+    return missing;
+}
+/** What the caller asked for that the response does not contain. The server
+ * does NOT pad missing data with `null`: an indicator that is empty for every
+ * security disappears from `indicatorList`, and a security that is empty for
+ * every indicator disappears from `securityCodeList` (re-probed 2026-08-03 with
+ * `finc_pb_mrq`, which has no HK data: over 09992.HK alongside `qte_close` the
+ * indicator vanishes; over 600519.SH + 09992.HK as the only indicator the
+ * security vanishes). A gap becomes `null` only when BOTH axes survive it — the
+ * security still has another indicator with data AND the indicator still has
+ * another security with data.
+ *
+ * That is the dangerous shape: `--key-by code` batch mapping finds no key at
+ * all rather than a null, and a cross-market pull quietly returns fewer rows
+ * than requested with exit code 0.
+ *
+ * Universe entries with no `.` are skipped — those are sector IDs, which the
+ * server expands into constituents, so their absence from the response is
+ * expected rather than a dropped row. */
+export function droppedFromMatrix(data, requestedSecurities, requestedIndicators) {
+    const empty = { securities: [], indicators: [] };
+    if (!data || typeof data !== "object")
+        return empty;
+    const d = data;
+    const returnedSecurities = new Set(asStringArray(d.securityCodeList) ?? []);
+    const returnedIndicators = new Set((Array.isArray(d.indicatorList) ? d.indicatorList : []).map((meta) => optionalString(meta?.code)));
+    return {
+        securities: requestedSecurities.filter((code) => code.includes(".") && !returnedSecurities.has(code)),
+        indicators: requestedIndicators.filter((code) => !returnedIndicators.has(code)),
+    };
+}
+/** True only when the payload carries NONE of the EDE matrix keys — a foreign
+ * shape. Nothing legitimately reaches the flatteners in that state — `indicator
+ * search` prints its unwrapped list directly and `raw call` bypasses them — so
+ * this is a protocol failure, not a payload to hand back: returning it would
+ * print the raw envelope and exit 0, indistinguishable from success. */
+function assertMatrixPayload(data, d) {
+    const bare = d.securityCodeList === undefined && d.securityNameList === undefined
+        && d.indicatorList === undefined && d.dates === undefined && d.values === undefined;
+    if (bare) {
+        throw new ApiError("Indicator matrix shape mismatch: the response carries none of the matrix fields — the response layout may have changed", undefined, undefined, data);
+    }
+}
+function assertAxis(data, axis, key) {
+    if (axis === undefined) {
+        throw new ApiError(`Indicator matrix shape mismatch: the response is missing \`${key}\` or it is not an array — the response layout may have changed`, undefined, undefined, data);
+    }
+}
+/** Resolve the display names for a security axis, degrading instead of failing.
+ *
+ * Names are consumed POSITIONALLY, so a list that does not line up cannot be
+ * trusted at all: `["泡泡玛特"]` against `["600519.SH","09992.HK"]` labels 茅台's
+ * series 泡泡玛特, and a `[null]` element used to render a column literally
+ * headed `"null"` (both probed 2026-08-02). Neither may reach the output.
+ *
+ * But a name is a LABEL, not structure — `securityCodeList` already carries
+ * identity, and every header falls back to the code. So an anomaly here drops
+ * the names and keeps the values, rather than killing an EDE command whose
+ * numbers are all correct. That is a deliberate asymmetry with the other guards
+ * in this module: they protect against MISATTRIBUTED VALUES and must be fatal;
+ * this one protects a caption. */
+function resolveSecurityNames(names, codes) {
+    if (names === undefined || names === null)
+        return undefined;
+    if (!Array.isArray(names) || names.length !== codes.length) {
+        process.stderr.write(`[gangtise] warning: securityNameList carries ${Array.isArray(names) ? `${names.length} entries` : "no array"} for ${codes.length} securities — names are positional, so all of them were dropped; columns fall back to the security code.\n`);
+        return undefined;
+    }
+    let warned = false;
+    return names.map((name, i) => {
+        if (typeof name === "string" && name.trim() !== "")
+            return name;
+        // A blank or null name is a plausible gap for one security — fall back
+        // quietly. A non-string (an object, a number) means the field changed type,
+        // which is worth saying once.
+        if (typeof name !== "string" && name !== null && name !== undefined && !warned) {
+            warned = true;
+            process.stderr.write(`[gangtise] warning: securityNameList holds non-string entries; those columns fall back to the security code.\n`);
+        }
+        return codes[i];
+    });
+}
+/** The matrix endpoints cannot legitimately answer with a non-object payload:
+ * `indicator search` never reaches the flatteners (it prints the unwrapped list
+ * directly) and `raw call` bypasses them entirely, so there is no caller for
+ * which `null`, an array, or a foreign object is a valid cross-section /
+ * time-series / screener body. Checked here, BEFORE the envelope is discarded,
+ * because a `data: null` cannot carry the non-enumerable traceId — passing the
+ * envelope as details is the only way such a failure stays traceable. */
+export function requireIndicatorMatrix(raw) {
+    const data = unwrapIndicatorData(raw);
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        throw new ApiError(`Indicator API returned no matrix object (got ${data === null ? "null" : Array.isArray(data) ? "an array" : typeof data}) — the response layout may have changed`, undefined, undefined, raw);
+    }
+    return data;
+}
+function assertValuesPresent(data, values) {
+    if (!Array.isArray(values)) {
+        throw new ApiError(`Indicator matrix shape mismatch: the response carries axis lists but no \`values\` array — the response layout may have changed`, undefined, undefined, data);
+    }
+}
+/** The matrix and its axis labels must agree on BOTH dimensions, or cells are
+ * dropped or misread. The 2026-08-01 revision transposed cross-section without a
+ * version marker, so a re-transpose has to fail loudly rather than silently
+ * relabel columns — with the caveat that this only catches a NON-SQUARE change.
+ * A 2×2 or 1×1 matrix keeps its dimensions when transposed and would still be
+ * read with the axes swapped; nothing in the payload distinguishes the two.
+ *
+ * Row length is checked exactly, not leniently: the server pads a row with
+ * `null` rather than truncating it — probed 2026-08-02 across A/HK/US, where a
+ * US security missing 3 of 4 indicators still came back with a full-length row,
+ * and a cross-market time series padded every security to the union of trading
+ * days (each market's own holidays land as `null`). A short or long row is
+ * therefore a structural change, not missing data.
+ *
+ * `data` rides along as ApiError details so the failure keeps the response's
+ * traceId — a shape mismatch is precisely the kind of thing support needs to
+ * trace, and without it the error reaches the user trace-less. */
+function assertMatrixShape(data, values, rows, rowAxis, cols, colAxis) {
+    if (values.length !== rows) {
+        throw new ApiError(`Indicator matrix shape mismatch: got ${values.length} value rows for ${rows} ${rowAxis} — the response layout may have changed`, undefined, undefined, data);
+    }
+    for (const [i, row] of values.entries()) {
+        const width = Array.isArray(row) ? row.length : -1;
+        if (width !== cols) {
+            throw new ApiError(`Indicator matrix shape mismatch: value row ${i} has ${width < 0 ? "no array of" : String(width)} cells for ${cols} ${colAxis} — the response layout may have changed`, undefined, undefined, data);
+        }
+    }
+}
 // Cross-section (and the screener, whose payload is the same shape plus a
 // per-indicator `field`): one row per security, one column per indicator.
 // `values` is [security][indicator], so security i's value for indicator j is
 // values[i][j]. There is no row-level date any more — the query date now lives
 // in each indicator's own parameters and may legitimately differ per column.
 export function flattenCrossSection(data, keyBy = "name") {
-    if (!data || typeof data !== "object")
-        return data;
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        throw new ApiError(`Indicator API returned no matrix object (got ${data === null ? "null" : Array.isArray(data) ? "an array" : typeof data}) — the response layout may have changed`, undefined, undefined, data);
+    }
     const d = data;
-    const securityCode = asStringArray(d.securityCodeList);
-    const indicators = asIndicatorMetaList(d.indicatorList);
-    if (!Array.isArray(d.values) || !securityCode || !indicators)
-        return data;
-    const securityName = asStringArray(d.securityNameList);
+    assertMatrixPayload(data, d);
+    // Past this point the payload claims to be a matrix, so every axis it needs
+    // must actually be there. A `null` or absent axis is a broken response.
+    const securityCode = asIdentityArray(data, d.securityCodeList, "securityCodeList");
+    const indicators = asIndicatorMetaList(data, d.indicatorList);
+    assertAxis(data, securityCode, "securityCodeList");
+    assertAxis(data, indicators, "indicatorList");
+    assertValuesPresent(data, d.values);
+    assertMatrixShape(data, d.values, securityCode.length, "securities", indicators.length, "indicators");
+    const securityName = resolveSecurityNames(d.securityNameList, securityCode);
     const headers = indicatorHeaders(indicators, keyBy, CROSS_SECTION_COLUMNS);
     const list = securityCode.map((code, i) => {
-        const row = { security: code, name: securityName?.[i] };
+        // Only create `name` when there IS one: an always-present `name: undefined`
+        // is invisible in JSON but renders as a real empty column in CSV/table.
+        const row = securityName ? { security: code, name: securityName[i] } : { security: code };
         const cells = rowOf(d.values, i);
         for (let j = 0; j < headers.length; j++) {
             row[headers[j]] = cells?.[j];
@@ -107,17 +366,66 @@ export function flattenCrossSection(data, keyBy = "name") {
 // Time-series: one row per date. Columns are the indicators (single-security
 // case) or the securities (single-indicator case) — exactly one dimension
 // varies, per the API contract. `values` stays a 2D [series][date] matrix.
-export function flattenTimeSeries(data, keyBy = "name") {
-    if (!data || typeof data !== "object")
-        return data;
+//
+// Axis rule, in priority order:
+//  1. More than one indicator came back → multi-indicator × single-security.
+//  2. More than one security came back → single-indicator × multi-security.
+//     This is what a sector ID produces: the request carries ONE universe entry
+//     and the server expands it into N constituents, so the request count says
+//     nothing about the axis.
+//  3. Both are 1 → genuinely ambiguous, so fall back to what was REQUESTED:
+//     - a universe holding a sector ID always takes the security axis. The
+//       sector may expand to one constituent, or the rest may have been dropped
+//       for lack of data; either way the caller asked "which securities", and an
+//       indicator-named column would erase whose series this is.
+//     - otherwise the entry count decides. The server drops securities with no
+//       data at all, so a two-security request that comes back with one must
+//       still be labelled by security (probed 2026-08-02: `finc_pe_ttm` over
+//       600519.SH + 09992.HK).
+export function flattenTimeSeries(data, keyBy = "name", requestedUniverse) {
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        throw new ApiError(`Indicator API returned no matrix object (got ${data === null ? "null" : Array.isArray(data) ? "an array" : typeof data}) — the response layout may have changed`, undefined, undefined, data);
+    }
     const d = data;
-    const dates = asStringArray(d.dates);
-    const securityCode = asStringArray(d.securityCodeList);
-    const indicators = asIndicatorMetaList(d.indicatorList);
-    if (!Array.isArray(d.values) || !dates || !securityCode || !indicators)
-        return data;
-    const securityName = asStringArray(d.securityNameList);
-    const seriesAreIndicators = securityCode.length <= 1;
+    assertMatrixPayload(data, d);
+    const dates = asIdentityArray(data, d.dates, "dates");
+    const securityCode = asIdentityArray(data, d.securityCodeList, "securityCodeList");
+    const indicators = asIndicatorMetaList(data, d.indicatorList);
+    assertAxis(data, dates, "dates");
+    assertAxis(data, securityCode, "securityCodeList");
+    assertAxis(data, indicators, "indicatorList");
+    assertValuesPresent(data, d.values);
+    const securityName = resolveSecurityNames(d.securityNameList, securityCode);
+    // The API permits multi-indicator × single-security OR single-indicator ×
+    // multi-security, never both — the server rejects such a REQUEST with 100003.
+    // A RESPONSE carrying both axes plural is therefore unattributable: whichever
+    // axis becomes the columns, the other one's identity is silently discarded
+    // (probed 2026-08-02: 2×2 rendered as 收盘价/成交量 with both securities gone,
+    // and droppedFromMatrix sees nothing missing so it would not even flag).
+    // Data with only one identity axis is unattributable in the other direction:
+    // `securityCodeList: []` alongside a populated matrix leaves every row
+    // belonging to no security at all, and the row/column counts still line up so
+    // no other guard notices.
+    // Without this, dates-with-no-series still passes the later shape check (0 rows
+    // for 0 series) and emits one row per date carrying nothing but the date. A
+    // genuine no-data answer empties `dates` too (probed 2026-08-02), so dates
+    // alongside a missing axis is always a broken response.
+    if (dates.length > 0 && (securityCode.length === 0 || indicators.length === 0)) {
+        throw new ApiError(`Indicator matrix shape mismatch: the time-series response carries ${dates.length} dates but ${securityCode.length} securities and ${indicators.length} indicators — the data could not be attributed`, undefined, undefined, data);
+    }
+    if (securityCode.length > 1 && indicators.length > 1) {
+        throw new ApiError(`Indicator matrix shape mismatch: the time-series response carries ${securityCode.length} securities AND ${indicators.length} indicators, which the endpoint does not support — one of the two identities would be lost`, undefined, undefined, data);
+    }
+    // A universe entry without a `.` is a sector ID — the server expands it, so
+    // neither its presence nor the entry count says anything about the axis.
+    const requested = requestedUniverse === undefined ? undefined : [...new Set(requestedUniverse)];
+    const hasSector = requested?.some((entry) => !entry.includes(".")) ?? false;
+    const seriesAreIndicators = indicators.length > 1 ? true
+        : securityCode.length > 1 ? false
+            : hasSector ? false
+                : (requested?.length ?? securityCode.length) <= 1;
+    const seriesCount = seriesAreIndicators ? indicators.length : securityCode.length;
+    assertMatrixShape(data, d.values, seriesCount, seriesAreIndicators ? "indicators" : "securities", dates.length, "dates");
     // Map over securityCode rather than securityNameList directly: a response that
     // omits the names must still yield one header per security (falling back to
     // the code), not zero columns.

package/dist/src/core/printer.js

@@ -28,10 +28,16 @@ export async function printData(data, format, output, cache) {
             const listLen = Array.isArray(meta.list) ? meta.list.length : 0;
             process.stderr.write(`Total: ${meta.total}, showing: ${listLen}\n`);
         }
-        // Partial results (failed pages/shards) exit with code 3: the table/csv/jsonl
+        // Incomplete or untrustworthy results exit with code 3: the table/csv/jsonl
         // renderers only emit the rows, so without a distinct exit code a script or AI
-        // consumer cannot tell a partial export from a complete one.
-        if (meta.partial === true) {
+        // consumer cannot tell such an export from a clean one.
+        // - `partial`: rows are missing (failed pages/shards, a row cap, or an EDE
+        //   response that dropped whole securities/indicators).
+        // - `unreliable`: the rows that ARE here may hold wrong values — currently
+        //   only the screener's duplicate-indicator defect, where every binding of a
+        //   repeated code is resolved from the EARLIEST date among them, so the one
+        //   surviving number need not belong to the variable it is labelled with.
+        if (meta.partial === true || meta.unreliable === true) {
             process.exitCode = 3;
         }
     }

package/dist/src/core/transport.js

@@ -104,11 +104,12 @@ const RETRYABLE_API_CODES = new Set(["999999"]);
 // - 140002 PROCESSING_FAILED: the async *-check endpoints (get-content) declare no
 //   retry policy, so a 140002@500 would be retried 2× by the default policy BEFORE
 //   asyncContent's FAILED_CODES gets to call it terminal — that guard sits above
-//   client.call's withRetry and cannot see the retries. 140002 means "generation
-//   failed" (terminal by definition) and only those async endpoints can return it,
-//   so a blanket rule is safe and skips the wasted retries. Server still emits the
-//   legacy 410111 today (410111@400 isn't retryable anyway); this is a forward guard
-//   for the documented 140002@500.
+//   client.call's withRetry and cannot see the retries. 140002 is terminal in both
+//   of its meanings — async "generation failed", and (probed 2026-08-02) the EDE
+//   indicator endpoints' parameter/expression errors, e.g. an out-of-range enum or
+//   a malformed screener expression — so the blanket rule stays correct and skips
+//   the wasted retries. Server still emits the legacy 410111 today (410111@400
+//   isn't retryable anyway); this is a forward guard for the documented 140002@500.
 const TERMINAL_API_CODES = new Set(["999011", "140002"]);
 // Connect-phase / DNS failures: the request provably never reached the server, so a
 // replay cannot double-execute (or double-bill) anything even under "no-replay".

package/dist/src/version.js

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

package/gangtise-openapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gangtise-openapi
-version: "0.30.0"
+version: "0.31.0"
 description: |-
   通过 gangtise CLI 直接调用 Gangtise OpenAPI，拉取投研原始数据、批量导出、下载文件、调用 AI 能力。
 
@@ -36,7 +36,7 @@ description: |-
    - Token 失效（`0000001008` / `999002`，含已废弃的 `8000014`/`8000015`）→ 自动重新登录并重试一次；凭证错 `999011` → **不重试**（AK/SK 不对不会自己好），查环境变量
 8. **参数命名差异**：Insight/Quote/Vault 用 `--security`，Fundamental/AI 用 `--security-code`（例外：`ai stock-summary` 用 `--security`，`ai security-clue` 用 `--gts-code`）。
 9. **调试**：`--verbose` 或 `GANGTISE_VERBOSE=1` 打印每个请求的耗时/字节数到 stderr。
-10. **`--field` 字段名必须核对，不确定就别传**（返回全量最稳）：`quote realtime` / `fundamental main-business` / `valuation-analysis` 遇到不存在的字段名时，上游只丢**值**、字段名照请求**回显**，按位置拍平会把值贴到错误的字段上（实测 realtime 传 `close`——它没有这个字段——换手率 28.5573 被贴成 `close`，茅台真实价 1297.41）。v0.28.3 起 CLI 检测到长度不匹配直接报错（退出码 1）：**带 `--field` 的命令看到这个报错，先去 `references/fields.md` 核对字段名**（没有 `--field` 的命令如 `alternative edb-data` 报此错则是上游响应结构异常，报障时若报错末尾附了 `（trace …）` 就一并带上）。另：realtime **无 `close`**（用 `latestPrice`）、**无市值**（总市值走 `indicator cross-section --indicator qte_mkt_cptl`，仅 A 股）。
+10. **`--field` 字段名必须核对，不确定就别传**（返回全量最稳）：`quote realtime` / `fundamental main-business` / `valuation-analysis` 遇到不存在的字段名时，上游只丢**值**、字段名照请求**回显**，按位置拍平会把值贴到错误的字段上（实测 realtime 传 `close`——它没有这个字段——换手率 28.5573 被贴成 `close`，茅台真实价 1297.41）。v0.28.3 起 CLI 检测到长度不匹配直接报错（退出码 1）：**带 `--field` 的命令看到这个报错，先去 `references/fields.md` 核对字段名**（没有 `--field` 的命令如 `alternative edb-data` 报此错则是上游响应结构异常，报障时若报错末尾附了 `（trace …）` 就一并带上）。另：realtime **无 `close`**（用 `latestPrice`）、**无市值**（总市值走 `indicator cross-section --indicator qte_mkt_cptl`，2026-08-03 起 A/港/美股均有数）。
 
 ## 工作流（3 步）
 
@@ -166,14 +166,14 @@ description: |-
 - 港股代码用在 `insight foreign-opinion --security` 还是 `quote day-kline-hk --security`？前者要"境外"格式（`UBER.N`），后者要 `.HK`
 - "成分股" → 题材深度（分组/重点标记/纳入理由）走 `alternative concept-securities`；板块（行业/概念分类树，纯代码名单）走 `reference sector-constituents`
 - **证券基本面 / 指标先按任务形态路由，不是搜到 EDE 就一律走 EDE**：
-  - 单证券先优先对应 `fundamental` 专用命令（财务、估值、盈利预测、股东、主营或完整三大报表，多数免费 / 低价）。其中 `valuation-analysis` / `earning-forecast` 实测仅支持 A 股；港 / 美股的估值历史分位、盈利预测、以及 PE/PB 等核心估值（EDE 也仅 A 股）当前 CLI 均无可用接口，如实说明不支持、勿用别的语义顶替
+  - 单证券先优先对应 `fundamental` 专用命令（财务、估值、盈利预测、股东、主营或完整三大报表，多数免费 / 低价）。其中 `valuation-analysis` / `earning-forecast` 实测仅支持 A 股，港 / 美股的**估值历史分位**与**盈利预测**当前无可用口径。但**估值指标本身别照抄旧结论**：2026-08-03 实测 `finc_pe_ttm` 港股已有数、`qte_mkt_cptl`/`shr_tot` 港美股都已有数。⚠️ **凡「仅 A 股」「无数据」这类否定结论都只是某时点抽查**，服务端在持续补数据；负面结论过期不会报错、只会让你白白拒掉一个能跑的查询。**一律以当次 `scopeList` + 抽查为准**
   - 多证券批量取一组**已实现**财务 / 估值指标 → 优先 `indicator search` 后用 EDE 一次拉取，替代逐只循环；单日或同一报告期横向比较用 `cross-section`，区间走势用 `time-series`（后者不能多指标 × 多证券同时）。**批量按 code 回填加 `--key-by code`**（列头用 `indicatorCode`，防同名指标碰撞 + 服务端重排列序导致的错位）
-  - 始终排除 EDE：A股盈利预测 / 一致预期（含预测 EPS）→ `fundamental earning-forecast`；A股估值历史分位 → `fundamental valuation-analysis`；开高低收 / 成交量等行情与 K 线 → `quote`；单证券完整报表 → 对应三大报表命令。**例外：总市值只有 EDE 有**——`quote realtime` / `day-kline` 都不返回市值，走 `indicator cross-section --indicator qte_mkt_cptl`（仅 A 股，默认单位「元」，用 `--scale` 缩放）。EDE 搜到的基本 / 稀释 EPS 是已实现值，**不能冒充预测 EPS**；港 / 美股缺少上述专用能力时应如实说明不支持，不能用别的语义代替
+  - 始终排除 EDE：A股盈利预测 / 一致预期（含预测 EPS）→ `fundamental earning-forecast`；A股估值历史分位 → `fundamental valuation-analysis`；开高低收 / 成交量等行情与 K 线 → `quote`；单证券完整报表 → 对应三大报表命令。**例外：总市值只有 EDE 有**——`quote realtime` / `day-kline` 都不返回市值，走 `indicator cross-section --indicator qte_mkt_cptl`（2026-08-03 起 A/港/美股均有数，默认单位「元」，用 `--scale` 缩放）。EDE 搜到的基本 / 稀释 EPS 是已实现值，**不能冒充预测 EPS**；港 / 美股缺少上述专用能力时应如实说明不支持，不能用别的语义代替
   - EDE 取数前必须用 `search --format json` 同时核对：`indicatorName` + `description` 语义准确、`scopeList` 覆盖全部目标市场 / 证券类型、`parameterList` 必填参数与枚举可满足；`scopeList` 缺失 / `null` / 空或任一项不符，都视为无法证明覆盖并回退专用接口。专用接口也不覆盖目标市场时，说明当前不可用，不要硬调。`scopeList` 按指标各不相同，不能因 EDE 服务支持 A / 港 / 美股就假定某个指标三市场都覆盖
   - `indicator search` 免费，`cross-section` / `time-series` 按单元格计费；除多证券批量的效率收益外，仍优先免费 / 低价的 `quote` 或 `fundamental`
 - 行业 / 宏观指标（空调销量、社融等，无证券维度）走 `alternative edb-*`（EDB），不要与证券级 EDE 混用
-- EDE 单元格级缺值返回 `null` 且保留证券行；**整个查询无数据返回空表**（2026-08-01 起不再报 `999999`）——所以**参数写错也表现为空表**，拿到空表先查参数名和日期语义，别当成真没数据。日期语义按指标分三类：财务报表指标=报告期末（可为非交易日）、`finc_pe_ttm` 等日频估值=最新交易日、`finc_pb_mrq`(MRQ) 等=最近报告期末（交易日取 `null`）；混合取数按各自有效日期分次 `cross-section` 再按证券合并，别塞进同一个 `--date`。详见 `references/commands/indicator.md`
-- **EDE 指标参数名一律以 `indicator search --format json` 的 `parameterList` 为准**，不要凭记忆或照抄示例：服务端会改参数名（`adjustmentType` → `adjustType`，2026-08-01），**传错名是静默忽略、退回默认值**而不是报错——实测 `adjustmentType=3` 返回的是不复权价，看着正常实则错数据。`--indicator` / `--security` 支持板块 ID（`reference sector-search` 的 10 位 `sectorId`）。⚠️ 根级 `--scale` 会污染不声明 `scale` 的指标（`qte_close` 被 `--scale 8` 缩成 `0`），价格与金额混查时改用 `--indicator-param "code:scale=8"`
+- EDE 缺数据分四档，**别只认 `null`**：①部分缺 → 单元格 `null`（行列都在），**退出码 0**；②某指标对所有证券都无数据 → 该指标**整列消失**；③某证券对所有指标都无数据 → 该证券**整行消失**——②③ CLI 会标 `partial: true` + `omittedIndicators`/`omittedSecurities` 并**退出码 3**（**`screener` 例外见下**）（`--key-by code` 回填时 key 会直接不存在，务必先看这两个字段）；④整个查询无数据 → **空表**（2026-08-01 起不再报 `999999`），**退出码 0**、不标 partial（什么都没被丢，就是没数据），但 stderr 会提醒这也可能是参数名写错。⚠️ 由此推出一个不直觉但自洽的结果：**同一个 scope 落空，单查是 0、混查是 3**（`finc_pb_mrq` 只查 `09992.HK` → 整体全空 → 0；和茅台一起查 → 泡泡玛特整行被丢 → 3）。全空时没有任何证据能证明「被丢了」，只有存在对照物时才有——所以**要验证某标的是否被覆盖，就把它和一个已知有数的标的一起查**。**参数写错表现为空表**，拿到空表先查参数名和日期语义，别当成真没数据。日期语义按指标分两类：财务报表指标=报告期末（可为非交易日）、`finc_pe_ttm` / `finc_pb_mrq` 等日频估值=最新交易日（⚠️ MRQ 口径 2026-08-02 已改为日频，旧文档「只在报告期末打值」已作废，照旧写法会取到几个月前的陈值）；混合取数按各自有效日期分次 `cross-section` 再按证券合并，别塞进同一个 `--date`。详见 `references/commands/indicator.md`
+- **EDE 指标参数名一律以 `indicator search --format json` 的 `parameterList` 为准**，不要凭记忆或照抄示例：服务端会改参数名（`adjustmentType` → `adjustType`，2026-08-01），**传错名是静默忽略、退回默认值**而不是报错——实测 `adjustmentType=3` 返回的是不复权价，看着正常实则错数据。`--security` 支持板块 ID（`reference sector-search` 的 10 位 `sectorId`；`--indicator` 只收指标编码）。⚠️ 根级 `--scale` 会污染不声明 `scale` 的指标（`qte_close` 被 `--scale 8` 缩成 `0`），价格与金额混查时改用 `--indicator-param "code:scale=8"`
 - "业绩点评"双义消歧：**检索已有**（研报/纪要里的业绩点评内容）走 `insight ... list --llm-tag earningsReview`（0.1/条）；**AI 现生成**一份走 `ai earnings-review`（异步、50/次）。不确定问一句
 
 ## 公司名 → 证券代码
@@ -280,7 +280,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 | ✅ `0000001008` | Token 服务端失效（他处登录挤掉）——**旧码未切，token 自愈依赖它** | **强制重新登录并重试一次** | 无 AK/SK 时无法自愈，提示重新登录 |
 | ✅ `0000001007` | 请求未携带 Bearer token | — | 检查 `GANGTISE_TOKEN` / AK/SK 是否已 export |
 | ✅ `900002` | **请求方法不正确**（msg「请求类型有误」，HTTP 405）——旧文档写作"缺少 uid"是错的 | — | `raw call` 时确认该 endpoint 是 GET 还是 POST |
-| `410106` / 缺参 | `indicator` 缺必填参数（msg 直接指明，如「必填参数 periodNum 不能为空」；HTTP 500 故 CLI 重试 ×2） | **自动重试 ×2** | 读 `indicator search --format json` 的 `parameterList` 补 `required:true` 参数 |
+| ✅ `140002` | 终态参数错：AI 异步生成失败，或 `indicator` 的指标必填参数缺失 / 枚举越界 / 表达式语法错（实测 2026-08-02） | **不重试**（终态码） | 按 msg 改参数重提；EDE 的参数名与枚举读 `indicator search --format json` 的 `parameterList` |
 
 **⚠️ 实测发现的坑（都是"不报错"型，最难发现）**
 - 🔴 **日期只写 `YYYY-MM-DD`、时间只写 `YYYY-MM-DD HH:mm:ss`（或 10/13 位时间戳）；CLI v0.28.0 起 date 与 datetime 两类、含所有 insight/vault 透传参数都本地拦截**。服务端对「年在后」格式**日月顺序随分隔符翻转**且静默误解析（HTTP 200、不回显实际用的日期）：`07/01/2026`（斜杠）读成 **2026-01-07**、`07-01-2026`（横杠）读成 **2026-07-01**，差半年。实测 `insight research list --start-time`：`07/01/2026` 命中 1562 条、`07-01-2026` 命中 210 条（分别 = 标准 `2026-01-07` / `2026-07-01`）；`quote day-kline`/`kline-hk`/`kline-us`/`index`、`fundamental balance-sheet` 同理。v0.28.0 前透传命令（research/summary/announcement-hk/us/vault/minute-kline 等）**静默放行**，且同值在本地转时间戳的 `announcement`（A 股）与透传的 hk/us 之间还会差半年、都 exit 0。现在全部在发请求前报 `ValidationError`，**但绕过 CLI 直连接口务必自己保证格式**
@@ -315,7 +315,11 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 
 **其他场景**：
 - CLI 未安装 → `npm install -g gangtise-openapi-cli`
-- **退出码 3 = 部分结果**：翻页/K线分片有页失败、或服务端返回行数与 `total` 矛盾（提前短页）时，已取到的数据保留——stderr 有 warning，`--format json` 可见 `partial: true`（页失败另有 `failedPages`；分片失败为 `failedShards`、分片撞行数上限为 `truncatedShards`，均带具体日期区间可定向缩窗补拉）；table/csv/jsonl 只有数据行、看不出缺失。拿部分数据继续前必须告知用户缺了哪段
+- **退出码 3 = 结果不完整或不可信**（两种语义，都保留已取到的数据；stderr 有 warning，`--format json` 才看得见标记，table/csv/jsonl 只有数据行、看不出问题）：
+  - **`partial: true` = 少了数据**。翻页/K线分片有页失败、服务端返回行数与 `total` 矛盾（提前短页）、或 **EDE 整指标/整证券被服务端略过**。附带定位字段：页失败 `failedPages`；分片失败 `failedShards`、分片撞行数上限 `truncatedShards`（均带日期区间可缩窗补拉）；EDE 为 `omittedIndicators` / `omittedSecurities`（那几个 code 一个值都没有，先查 `scopeList` 覆盖和日期语义）
+  - **`unreliable: true` = 在场的值不可信**。目前只有 EDE 条件选股把同一指标绑到多个变量时会出现，附 `duplicatedIndicators`。服务端缺陷（2026-08-03 实测）：这些绑定**全部按其中最早的那个日期取数**，该值落到它们的第一列、其余列为 `null`——所以**活下来的那个数字未必属于它标注的变量**（声明 07-31 的变量拿到了 07-30 的价）。**整份结果都不可信**：显示的值可能张冠李戴，命中的证券集合也不可信（针对 null 变量的条件等于没筛），同一请求还有约 1/3 概率返回空集。**不能拿来下任何结论**，拆成多次调用重跑
+  - **`screener` 的缺列按表达式的布尔结构判**：把缺列的变量当作「无法求值」，看整个表达式**是否还有一条能成立的分支**——`A && B` 要两边都可求值，`A || B` 只要一边。**一条分支都不剩 → 退出码 1、不输出任何结果**（返回的行以「通过了该条件」的名义呈现，而条件根本无法证明被执行过）；**还有分支可求值，或缺的只是未参与表达式的辅助变量 → `partial` + 退出码 3**。所以 `F1 || F2` 缺 F1 是降级（行可能靠 F2 正当命中），缺两个则是致命；`F1 && (F2 || F3)` 缺 F1 仍是致命（F1 是必选合取项）
+  - 拿到 3 就必须告知用户缺了哪段 / 哪些值不可信，不能当成功静默继续
 - 空结果（list 为空数组） → 建议扩大时间范围、换关键词、去掉部分筛选
 - 模糊公司名匹配多只（"平安" → 中国平安 / 平安银行 / ...） → 列出让用户选
 - 下载文件路径冲突 → 询问覆盖