gangtise-openapi-cli 0.27.0 → 0.28.1

package/dist/src/core/args.js

@@ -90,38 +90,154 @@ export function parseChoiceList(values, optionName, allowed) {
     }
     return maybeArray(values);
 }
+const YYYY_MM_DD = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * Strict `YYYY-MM-DD` guard for Quote/Fundamental date options.
+ *
+ * Beyond the documented shape the server accepts two extra year-last formats
+ * whose day/month order is *opposite* to each other (probed 2026-07-20 on
+ * quote/kline/daily and fundamental/balance-sheet; other groups sharing these
+ * flags were not probed, so the guard is applied uniformly as the safe default):
+ *
+ *   "07/01/2026" -> 2026-01-07   slash  reads DD/MM/YYYY
+ *   "07-01-2026" -> 2026-07-01   hyphen reads MM-DD-YYYY
+ *
+ * Same three digits, six months apart, both HTTP 200, and nothing in the
+ * response echoes which date the server actually used. Confirmed by the
+ * complement: "25/12/2026" parses while "12/25/2026" errors, and the hyphen
+ * forms behave exactly the other way round. Since the CLI cannot know which
+ * reading was meant, it forwards only the unambiguous form.
+ *
+ * Other unambiguous shapes (`20260701`, `2026/07/01`) are rejected too, even
+ * though the server handles them — one accepted form beats a per-shape allowlist
+ * that has to be re-probed per endpoint group. The message says which form is
+ * wanted rather than claiming the input itself was ambiguous.
+ *
+ * Datetime options (`--start-time`) are guarded separately: pass-through ones by
+ * `parseDatetimeOption` (a timezone-free field check that returns the string as-is),
+ * and the two conversion endpoints (A-share announcement / knowledge-batch) by
+ * `parseTimestamp13`.
+ */
+export function parseDateOption(value, optionName) {
+    if (!YYYY_MM_DD.test(value)) {
+        throw new ValidationError(`Invalid ${optionName}: expected YYYY-MM-DD, got "${value}" — only that form is forwarded; some endpoints silently misread other layouts (e.g. "07/01/2026") as a different day`);
+    }
+    // Shape alone lets 2026-02-30 / 2026-13-01 through; round-trip to reject those.
+    // Built from the ISO string, not Date.UTC(y,...), whose two-digit-year mapping
+    // would turn a valid year 0050 into 1950 and report it as a non-existent date.
+    const [year, month, day] = value.split("-").map(Number);
+    const parsed = new Date(`${value}T00:00:00Z`);
+    if (parsed.getUTCFullYear() !== year || parsed.getUTCMonth() !== month - 1 || parsed.getUTCDate() !== day) {
+        throw new ValidationError(`Invalid ${optionName}: "${value}" is not a real calendar date`);
+    }
+    return value;
+}
+/** Commander argParser factory — `.option("--start-date <date>", desc, dateArg("--start-date"))`. */
+export function dateArg(optionName) {
+    return (value) => parseDateOption(value, optionName);
+}
+/** `yyyy-MM-dd` with an optional ` HH:mm[:ss]` / `THH:mm[:ss]` tail. Anything else
+ * is rejected rather than handed to `new Date()`: V8's fallback parser accepts the
+ * same year-last shapes the server does but reads them the OTHER way round —
+ * `07/01/2026` is July 1 to V8 and January 7 to the server, `25/12/2026` is invalid
+ * to V8 and valid to the server (both probed 2026-07-20). Since `announcement list`
+ * converts locally while its HK/US siblings pass the string through, an open
+ * fallback made the same flag mean two dates six months apart across sibling
+ * commands, silently and with exit 0. */
+const LOCAL_DATETIME = /^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?$/;
+/** Field-level datetime validation, timezone-free — a real calendar day plus a
+ * valid clock time, judged by arithmetic alone (no Date construction, so no
+ * dependence on the client's timezone or DST). This is what the pass-through guard
+ * needs: a string the CLI forwards verbatim must be judged on its fields, not on
+ * whether the local zone happens to contain that wall-clock instant. */
+function datetimeFieldsValid(value) {
+    const parts = LOCAL_DATETIME.exec(value);
+    if (!parts)
+        return false;
+    const [, y, mo, d, hh = "0", mi = "0", ss = "0"] = parts;
+    const year = Number(y), month = Number(mo), day = Number(d);
+    if (month < 1 || month > 12)
+        return false;
+    const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    const dim = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1];
+    if (day < 1 || day > dim)
+        return false;
+    return Number(hh) <= 23 && Number(mi) <= 59 && Number(ss) <= 59;
+}
+/** A 10-digit seconds or 13-digit millis epoch, normalized to millis. Judged by
+ * digit count, NOT magnitude: a `> 1e12` test sends a real 13-digit `1000000000000`
+ * (which equals 1e12) down the seconds branch, and lets Number() coerce scientific
+ * / hex / whitespace-padded / 11–12–14-digit inputs through as a "timestamp" — all
+ * of which then convert wrong or get rejected by the server. Exactly 10 or 13
+ * digits, nothing else. */
+function epochMillis(value) {
+    if (/^\d{13}$/.test(value))
+        return Number(value);
+    if (/^\d{10}$/.test(value))
+        return Number(value) * 1000;
+    return undefined;
+}
 export function toTimestamp13(value) {
     if (value === undefined)
         return undefined;
-    const num = Number(value);
-    if (!Number.isNaN(num) && num > 1e12)
-        return num;
-    if (!Number.isNaN(num) && num > 1e9)
-        return num * 1000;
-    // `new Date("yyyy-MM-dd")` parses as UTC midnight while `new Date("yyyy-MM-dd HH:mm:ss")`
-    // parses as local time — for CST users the two forms would differ by 8 hours and
-    // silently shift the query window. Anchor date-only input to local midnight so both
-    // forms mean the same wall-clock day.
-    const dateOnly = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
-    if (dateOnly) {
-        const d = new Date(Number(dateOnly[1]), Number(dateOnly[2]) - 1, Number(dateOnly[3]));
-        const valid = d.getMonth() === Number(dateOnly[2]) - 1 && d.getDate() === Number(dateOnly[3]);
-        return valid ? d.getTime() : undefined;
-    }
-    const ms = new Date(value).getTime();
-    if (Number.isNaN(ms))
+    const ts = epochMillis(value);
+    if (ts !== undefined)
+        return ts;
+    if (!datetimeFieldsValid(value))
         return undefined;
-    return ms;
+    // `new Date("yyyy-MM-dd")` parses as UTC midnight while `new Date("yyyy-MM-dd
+    // HH:mm:ss")` parses as local time — for CST users the two forms would differ by 8
+    // hours. Build from local components so both mean the same wall-clock day.
+    const parts = LOCAL_DATETIME.exec(value);
+    const [, y, mo, d, hh = "0", mi = "0", ss = "0"] = parts;
+    const year = Number(y);
+    const dt = new Date(year, Number(mo) - 1, Number(d), Number(hh), Number(mi), Number(ss));
+    // Full round-trip on every field: rejects the two inputs that cannot convert
+    // faithfully — the two-digit-year remap (new Date(50,…) → 1950) and a DST gap (a
+    // wall-clock time the local zone skips: 02:30 on a US spring-forward morning, or
+    // 02:15 in Lord Howe's 30-minute gap, which only a minute-level check catches).
+    const faithful = dt.getFullYear() === year && dt.getMonth() === Number(mo) - 1
+        && dt.getDate() === Number(d) && dt.getHours() === Number(hh)
+        && dt.getMinutes() === Number(mi) && dt.getSeconds() === Number(ss);
+    return faithful ? dt.getTime() : undefined;
 }
 export function parseTimestamp13(value, optionName) {
     if (value === undefined)
         return undefined;
     const parsed = toTimestamp13(value);
     if (parsed === undefined) {
-        throw new ValidationError(`Invalid ${optionName}: expected a Unix timestamp or date string`);
+        throw new ValidationError(`Invalid ${optionName}: expected a Unix timestamp or "YYYY-MM-DD" optionally with " HH:mm[:ss]" (space or T separator), got "${value}" — year-last forms are refused because Node and the API read their day/month order the opposite way round`);
     }
     return parsed;
 }
+/**
+ * Guard for datetime options forwarded to the server AS A STRING (never converted
+ * to a timestamp): the pass-through Insight/Vault list endpoints echo the string
+ * verbatim, and probing 2026-07-21 showed they misread year-last separators exactly
+ * like the date endpoints — `insight research list` read `07/01/2026` as 2026-01-07
+ * but `07-01-2026` as 2026-07-01, a half-year apart, both HTTP 200 with nothing in
+ * the response flagging it. Accept a finite epoch or a well-formed `YYYY-MM-DD
+ * [ HH:mm[:ss]]` and return the ORIGINAL string unchanged.
+ *
+ * Validated with `datetimeFieldsValid`, NOT `toTimestamp13`: the latter's local Date
+ * round-trip would reject a DST-gap string (e.g. `2026-03-08 02:30:00` under
+ * America/New_York) that the server accepts — the CLI forwards this string as-is and
+ * the server resolves it in its own zone, so the client's timezone must not decide
+ * validity. Distinct from `parseTimestamp13`, which DOES convert (A-share
+ * announcement / knowledge-batch want epoch millis, where an unrepresentable local
+ * instant genuinely cannot convert).
+ */
+export function parseDatetimeOption(value, optionName) {
+    if (epochMillis(value) === undefined && !datetimeFieldsValid(value)) {
+        throw new ValidationError(`Invalid ${optionName}: expected a Unix timestamp or "YYYY-MM-DD" optionally with " HH:mm[:ss]" (space or T separator), got "${value}" — year-last forms are refused because the API reads their day/month order differently per separator`);
+    }
+    return value;
+}
+/** Commander argParser factory for pass-through datetime options — same role as
+ * `dateArg`, but allows an optional time part and keeps the string as-is. */
+export function datetimeArg(optionName) {
+    return (value) => parseDatetimeOption(value, optionName);
+}
 /** Machine-local calendar date as `yyyy-MM-dd`, for CLI "default: today" options.
  * `new Date().toISOString().slice(0,10)` renders the UTC day — for CST users a
  * pre-08:00 "today" resolves to yesterday. Anchoring to local components matches

package/dist/src/core/asyncContent.js

@@ -10,8 +10,35 @@ function nextDelayMs(attempt) {
     const grown = POLL_INITIAL_DELAY_MS * 1.6 ** (attempt - 1);
     return Math.min(POLL_MAX_DELAY_MS, Math.round(grown));
 }
+// Probed 2026-07-20 against a real viewpoint-debate job: the async endpoints are
+// still entirely on the legacy codes — 410110 "正在生成中" and 410111 "生成失败",
+// both string-typed, both HTTP 400, neither carrying the new `errorType` field.
+// The 2026-07-17 spec renumbers them to 140001 RESULT_GENERATING (409) and
+// 140002 PROCESSING_FAILED (500); those are listed ahead of the switchover
+// because the failure mode is expensive and silent — a `--wait` that does not
+// recognize the pending code aborts the poll on a job already billed 50 credits.
+const PENDING_CODES = new Set(["410110", "140001"]);
+const FAILED_CODES = new Set(["410111", "140002"]);
 function isAsyncPending(error) {
-    return error instanceof ApiError && error.code === "410110";
+    return error instanceof ApiError && error.code !== undefined && PENDING_CODES.has(error.code);
+}
+function isAsyncFailed(error) {
+    return error instanceof ApiError && error.code !== undefined && FAILED_CODES.has(error.code);
+}
+/** Terminal failures are swallowed here rather than rethrown, so this line is the
+ * user's only record of them — it has to carry what the global handler in cli.ts
+ * would have printed (code, msg, traceId). Without the traceId the failure is
+ * unreportable to Gangtise support, and README promises every error line has one. */
+function terminalFailureLine(error) {
+    const api = error instanceof ApiError ? error : undefined;
+    const code = api?.code ? ` ${api.code}` : "";
+    const trace = api?.traceId ? ` [trace ${api.traceId}]` : "";
+    const detail = api?.message ? `: ${api.message}` : "";
+    // Name the *submit* endpoint explicitly: re-running a `*-check` is a free
+    // lookup, it is resubmitting the generation job that re-bills 50 credits for a
+    // verdict that will not change (probed 2026-07-20 on sensitive content).
+    return `Content generation failed (terminal${code})${trace}${detail}\n`
+        + "This dataId is final — re-checking it will not change. Resubmitting the generation task bills again for the same result; change the parameters first.\n";
 }
 export async function pollAsyncContent(client, getContentEndpoint, dataId, format, output) {
     for (let attempt = 1; attempt <= POLL_MAX_ATTEMPTS; attempt++) {
@@ -23,8 +50,8 @@ export async function pollAsyncContent(client, getContentEndpoint, dataId, forma
             }
         }
         catch (error) {
-            if (error instanceof ApiError && error.code === "410111") {
-                process.stderr.write("Content generation failed (terminal). Do not retry.\n");
+            if (isAsyncFailed(error)) {
+                process.stderr.write(terminalFailureLine(error));
                 return "failed";
             }
             if (!isAsyncPending(error)) {
@@ -55,8 +82,8 @@ export async function checkAsyncContent(client, getContentEndpoint, dataId, form
         }
     }
     catch (error) {
-        if (error instanceof ApiError && error.code === "410111") {
-            process.stderr.write("Content generation failed (terminal). Do not retry.\n");
+        if (isAsyncFailed(error)) {
+            process.stderr.write(terminalFailureLine(error));
             process.exitCode = 1;
             return;
         }

package/dist/src/core/client.js

@@ -4,14 +4,20 @@ import path from "node:path";
 import { pipeline } from "node:stream/promises";
 import { request } from "undici";
 import { isTokenCacheValid, normalizeToken, readTokenCache, requireAccessCredentials, writeTokenCache } from "./auth.js";
-import { ApiError, ValidationError } from "./errors.js";
+import { ApiError, attachEnvelopeTraceId, ValidationError } from "./errors.js";
 import { ENDPOINTS, resolveTimeoutMs } from "./endpoints.js";
 import { getLookupData } from "./lookupData/index.js";
 import { decodeResponseBody, getDispatcher, isVerbose, logTiming, markRetryable, PAGE_CONCURRENCY, parseRetryAfterMs, runWithConcurrency, withRetry } from "./transport.js";
-// Auth errors that warrant a forced re-login + one replay. 8000014/8000015 are
-// AK/SK errors; 0000001008 is a server-side token invalidation (the token still
-// looks valid by local expiry, so only a forced refresh recovers it).
-const AUTH_RETRY_CODES = new Set(["8000014", "8000015", "0000001008"]);
+// Auth errors that warrant a forced re-login + one replay: the token was rejected
+// server-side while still looking valid by local expiry, so only a forced refresh
+// recovers it. 0000001008 is the legacy code (probed 2026-07-20: still what the
+// token filter emits); 999002 TOKEN_INVALID is its 2026-07-17 replacement, listed
+// ahead of the rollout so self-heal does not silently die when the filter switches.
+// 8000014/8000015 are the retired AK/SK codes, kept for older server builds.
+// 999011 CREDENTIAL_INVALID is not here and could not act if it were — it comes from
+// auth.login, which runs useAuth=false and so never reaches this check. Its "never
+// replay" guarantee lives in transport's TERMINAL_API_CODES instead.
+const AUTH_RETRY_CODES = new Set(["8000014", "8000015", "0000001008", "999002"]);
 export class GangtiseClient {
     config;
     refreshPromise = null;
@@ -126,17 +132,20 @@ export class GangtiseClient {
         }
         throw new ApiError(`API request failed (HTTP ${statusCode})`, undefined, statusCode, parsed, retryAfterMs);
     }
-    unwrapEnvelope(parsed, statusCode) {
+    unwrapEnvelope(parsed, statusCode, retryAfterMs) {
         if (!this.isEnvelope(parsed)) {
             return parsed;
         }
         const code = parsed.code === undefined ? undefined : String(parsed.code);
         const ok = parsed.status === true || parsed.success === true || code === "000000" || code === "0";
         if (!ok) {
-            throw new ApiError(parsed.msg || "API request failed", code, statusCode, parsed);
+            throw new ApiError(parsed.msg || "API request failed", code, statusCode, parsed, retryAfterMs);
         }
         if ('data' in parsed) {
-            return parsed.data;
+            // Carry the envelope's traceId onto the payload: the EDE endpoints wrap a
+            // second envelope inside `data` and raise their own failures from it, by
+            // which point this is the only traceId in reach.
+            return attachEnvelopeTraceId(parsed.data, parsed.traceId);
         }
         return parsed;
     }
@@ -397,7 +406,7 @@ export class GangtiseClient {
                 if (response.statusCode >= 400) {
                     this.throwHttpError(parsed, response.statusCode, retryAfterMs);
                 }
-                return this.unwrapEnvelope(parsed, response.statusCode);
+                return this.unwrapEnvelope(parsed, response.statusCode, retryAfterMs);
             }
             catch (error) {
                 await this.refreshAuthIfRecoverable(error, useAuth, authState, usedAuthorization);
@@ -491,7 +500,7 @@ export class GangtiseClient {
                     if (response.statusCode >= 400) {
                         this.throwHttpError(parsed, response.statusCode, retryAfterMs);
                     }
-                    data = this.unwrapEnvelope(parsed, response.statusCode);
+                    data = this.unwrapEnvelope(parsed, response.statusCode, retryAfterMs);
                 }
                 catch (error) {
                     await this.refreshAuthIfRecoverable(error, true, authState, authorization);

package/dist/src/core/errors.js

@@ -10,26 +10,111 @@ export class ValidationError extends CliError {
 }
 export class DownloadError extends CliError {
 }
+/** Outer-envelope traceId, stashed on the unwrapped payload so it survives
+ * `unwrapEnvelope` discarding the envelope. Needed by the EDE endpoints alone:
+ * they double-wrap, and probing 2026-07-20 showed the traceId lives only on the
+ * OUTER envelope — the inner failure envelope (`{code, status:false, msg}`) has
+ * none. Without this the one correlation id Gangtise support can trace is gone
+ * exactly where the inner failure is raised. Non-enumerable so it never reaches
+ * JSON/CSV output. */
+export const ENVELOPE_TRACE_ID = Symbol("gangtise.envelopeTraceId");
+export function attachEnvelopeTraceId(payload, traceId) {
+    if (payload && typeof payload === "object" && (typeof traceId === "string" || typeof traceId === "number")) {
+        Object.defineProperty(payload, ENVELOPE_TRACE_ID, { value: String(traceId), enumerable: false, configurable: true });
+    }
+    return payload;
+}
+/** Keyed by the code as a string — `unwrapEnvelope` runs every envelope code
+ * through `String()` first, which matters because the 2026-07-17 error-code
+ * overhaul emits the new codes as JSON *numbers* while legacy codes stay strings.
+ *
+ * Both generations are listed on purpose. Probed 2026-07-20: the rollout is
+ * partial — the business layer already answers with the new codes (`999011`,
+ * `130001`, `130002`, `100003`, `999010`), but the outer token filter still
+ * emits `0000001007` / `0000001008` / `900002`. Dropping either set would leave
+ * a live code hintless. */
 const ERROR_HINTS = {
-    "999999": "Gangtise 系统错误，请稍后重试。",
-    "999997": "当前账号未开通该接口权限。",
-    "999995": "当前账号积分不足。",
-    "900002": "请求缺少 uid。",
-    "900001": "请求参数为空或缺少必填项。",
-    "100003": "参数值非法——服务端不会指明是哪个参数，多为枚举参数拼写或取值超范围（如 --source / --question-category / --answer-important），对照命令 --help 列出的合法值检查。",
+    // The hint is appended after the server's own msg, so it must carry the *action*,
+    // never restate the diagnosis — "资源不存在 资源不存在，确认 ID 有效" reads as a stutter.
+    // ── 服务统一层 999xxx ──
+    "999001": "检查 GANGTISE_TOKEN 或 AK/SK 是否已 export。",
+    "999002": "有 AK/SK 时 CLI 会自动重新登录重试一次，否则请重新登录。",
+    "999003": "定制接口需联系客户经理开通。",
+    "999004": "换一条本账号可见的记录重试。",
+    "999005": "联系客户经理充值，或缩小查询范围降低消耗。",
+    "999006": "触发限流，稍后再试或联系客户经理提额；429 所有端点都退避重试，5xx 仅普通端点重试（贵档 no-replay 端点的 5xx 不重放，但其 429 仍重试）。",
+    // CLI 自身发不出这三类请求（method / Content-Type 都由 endpoint 定义固定），
+    // 只有 raw call 打错端点或服务端行为变化才可能撞上。实测 2026-07-20 分别落到
+    // 900002 / 999999 / 100003，此处为服务端接上新码后的预置。
+    "999007": "请求方法不支持——`raw call` 时确认该 endpoint 是 GET 还是 POST。",
+    "999008": "Content-Type 不支持，该接口只收 application/json。",
+    "999009": "请求体无法解析，检查 JSON 是否合法。",
+    "999010": "`raw call` 传的 endpoint key 可能已下线，用 `gangtise raw list` 核对。",
+    "999011": "检查 GANGTISE_ACCESS_KEY / GANGTISE_SECRET_KEY 是否写反或未 export。",
+    "999012": "联系客户经理。",
+    "999013": "联系客户经理续期。",
+    "999014": "联系客户经理。",
+    "999015": "联系客户经理开通长期 token。",
+    "999016": "联系客户经理登记当前出口 IP。",
+    "999999": "请稍后重试；持续失败请带上面的 trace 报障。",
+    // ── 业务通用 1xxxxx ──
+    "100001": "对照命令 --help 检查必填项。",
+    "100002": "检查数值/字符串参数是否传反。",
+    // 实测两种形态都有：类型/范围错的 msg 带字段（「请求体字段类型不匹配: size 期望类型
+    // Integer」「limit 最小为 1，最大为 10000」），枚举错的 msg 只有笼统的「参数值非法」。
+    // 条件句让两种形态都读得通——v0.25.0 的旧文案断言"服务端不会指明"，与前一种直接打架。
+    "100003": "msg 已指明字段名或取值范围时直接按 msg 改；msg 只说「参数值非法」时多为枚举参数拼写错误（如 --source / --question-category / --answer-important），对照命令 --help 列出的合法值检查。",
+    "100004": "检查 --size / --from 是否为非负数且未超单页上限。",
+    "100005": "对照命令 --help 列出的合法取值检查。",
+    "100006": "缩短日期范围或调小 --size / --limit。",
+    // 按参数名判断，不要按命令组：AI 下 management-discuss 的 --report-date 是 date，
+    // 而同属 AI 的 knowledge-batch 收时间戳或 datetime——旧文案笼统写"AI 用 datetime"会把
+    // --report-date 的用户越导越错。
+    "110001": "看参数名：`--*-date` 用 YYYY-MM-DD，`--*-time` 用 \"YYYY-MM-DD HH:mm:ss\"（`ai knowledge-batch` 的 --start-time/--end-time 收时间戳或 datetime，CLI 统一转 13 位毫秒）。",
+    "110002": "起始晚于结束——检查 --start-date/--end-date 或 --start-time/--end-time 的先后。",
+    "110003": "缩短查询窗口后重试。",
+    "120001": "用 `gangtise reference securities-search` 确认代码与后缀（如 600519.SH / 00700.HK）。",
+    "130001": "未找到数据——先核对查询条件；EDE 指标端点此码也可能是未开通该指标权限，仍失败联系客户经理。",
+    "130002": "确认下载 ID 有效且本账号可见；下载类还需检查 --file-type 取值是否合法（非法 file-type 也归此码）。",
+    "130003": "该条记录可能未附带文件。",
+    // 下载类命令各有各的 ID 参数（--report-id / --announcement-id / --chunk-id /
+    // --summary-id / --conference-id / --record-id / --file-id / --article-id /
+    // --independent-opinion-id）；--data-id 是异步 *-check 用的，不产生此码。
+    "130004": "下载 ID 需为数字，检查该命令的 --*-id 参数是否传对。",
+    "130005": "对照命令 --help 检查 --file-type / --content-type 取值。",
+    "140001": "稍后用对应 *-check 命令查询。",
+    "140002": "异步生成失败（终态）——换参数重新提交，重试同一 dataId 不会变。",
+    // ── 接口专有 2xxxxx ──
+    "210001": "换一篇，或改用 list 取正文摘要。",
+    "220001": "改用 list 取正文摘要。",
+    "230001": "只有自己上传的文件可下载。",
+    "240001": "换更早的 --period（如 2025q3 → 2025interim）。",
+    "240002": "改述后重新提交。",
+    "240003": "对照命令 --help 检查取值。",
+    "250001": "检查 resourceType 与 sourceId 组合（两者都来自 knowledge-batch 返回）。",
+    // ── 旧码（2026-07-20 实测仍在线，或历史遗留） ──
+    "0000001007": "请求未携带 Bearer token，检查 GANGTISE_TOKEN 或 AK/SK 是否已 export。",
     "0000001008": "Token 已失效（多为他处登录挤掉本会话）；有 AK/SK 时 CLI 会自动重新登录重试一次，否则请重新登录。",
-    "8000014": "GANGTISE_ACCESS_KEY 错误。",
-    "8000015": "GANGTISE_SECRET_KEY 错误。",
-    "8000016": "开发账号状态异常。",
-    "8000018": "开发账号已到期。",
-    "903301": "今日调用次数已达上限。",
-    "410110": "异步内容生成中，稍后用对应 *-check 命令查询。",
-    "410111": "异步内容生成失败（终态），请更换参数后重新提交。",
-    "410004": "数据未找到或无指标权限，请检查查询条件与指标权限。",
-    "430004": "下载失败（官方未文档化错误码），请确认 reportId 有效或更换 --file-type 重试。",
-    "430007": "行情查询超出限制，请缩短日期范围。",
-    "433007": "数据源不匹配，请检查 resourceType 与 sourceId 组合。",
-    "10011401": "白名单未开通，请联系管理员。",
+    "900001": "对照命令 --help 检查必填项。",
+    "900002": "请求方法不正确（服务端 msg 为「请求类型有误」）——`raw call` 时检查该 endpoint 是 GET 还是 POST。",
+    "903301": "次日再试，或联系客户经理提额。",
+    // EDE 专有旧码，未被 2026-07-17 重排收编但仍是 indicator 取数的主要报错
+    // （references/commands/indicator.md 把这两个列为首要排查项）。
+    "410001": "补齐 --indicator / --security；`time-series` 不支持「多指标 × 多证券」，改用 `indicator cross-section`。",
+    "410106": "读 `indicator search --format json` 的 parameterList，用 --indicator-param 补上 required:true 的参数（如 periodNum / startDate / fiscalYear）。",
+    "410004": "换证券或日期确认该条件下本应有数据；仍失败多为未开通该指标，联系客户经理。",
+    "410110": "稍后用对应 *-check 命令查询。",
+    "410111": "终态，换参数后重新提交，重试同一请求不会变。",
+    "430004": "确认 reportId 有效，或更换 --file-type 重试（官方未文档化错误码）。",
+    "430007": "缩短日期范围或调小 --limit。",
+    "433007": "检查 resourceType 与 sourceId 组合（两者都来自 knowledge-batch 返回）。",
+    "8000014": "检查 GANGTISE_ACCESS_KEY 是否正确、是否与 SECRET_KEY 写反。",
+    "8000015": "检查 GANGTISE_SECRET_KEY 是否正确、是否与 ACCESS_KEY 写反。",
+    "8000016": "联系客户经理核查账号状态。",
+    "8000018": "联系客户经理续期。",
+    "999995": "联系客户经理充值，或缩小查询范围降低消耗。",
+    "999997": "联系客户经理开通。",
+    "10011401": "联系客户经理开通白名单。",
 };
 export class ApiError extends CliError {
     code;
@@ -51,4 +136,17 @@ export class ApiError extends CliError {
         this.retryAfterMs = retryAfterMs;
         this.hint = hintOverride ?? (code ? ERROR_HINTS[code] : undefined);
     }
+    /** Server-side correlation id from the 2026-07-17 envelope
+     * (`{code, errorType, msg, status, data, traceId}`). Read off `details` rather
+     * than threading a 7th positional constructor arg through every call site.
+     * Worth surfacing: it is the only handle Gangtise support can trace a 999999 by. */
+    get traceId() {
+        if (!this.details || typeof this.details !== "object")
+            return undefined;
+        // Fall back to the outer envelope's id for double-wrapped (EDE) responses,
+        // whose inner failure envelope carries no traceId of its own.
+        const details = this.details;
+        const value = details.traceId ?? details[ENVELOPE_TRACE_ID];
+        return typeof value === "string" || typeof value === "number" ? String(value) : undefined;
+    }
 }

package/dist/src/core/indicatorMatrix.js

@@ -16,7 +16,11 @@ export function unwrapIndicatorData(raw) {
             // (status/msg/data) so a non-envelope object that merely carries a `code`
             // field can't be misread as a failure.
             if (!ok && ("status" in record || "msg" in record || "data" in record)) {
-                throw new ApiError(typeof record.msg === "string" && record.msg ? record.msg : "Indicator API request failed", code);
+                // Pass `record` as details: the inner envelope carries no traceId of its
+                // own, but unwrapEnvelope attached the outer one to this object and
+                // ApiError.traceId falls back to it. Without it these failures — the EDE
+                // 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);
             }
             if (ok && "data" in record)
                 return record.data;

package/dist/src/core/transport.js

@@ -77,6 +77,19 @@ export const PAGE_CONCURRENCY = resolvePageConcurrency(process.env.GANGTISE_PAGE
 const RETRYABLE_HTTP_STATUS = new Set([429, 500, 502, 503, 504]);
 const RETRYABLE_NETWORK_CODES = new Set(["ECONNREFUSED", "ECONNRESET", "ETIMEDOUT", "ENOTFOUND", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_SOCKET", "UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT"]);
 const RETRYABLE_API_CODES = new Set(["999999"]);
+// Never replayed on any HTTP status:
+// - 999011 CREDENTIAL_INVALID: bad AK/SK, only from auth.login (useAuth=false, so it
+//   never consults AUTH_RETRY_CODES, and it declares no retry policy) — a 5xx would
+//   otherwise be retried twice by the status rule.
+// - 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.
+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".
 const NO_REPLAY_NETWORK_CODES = new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT"]);
@@ -85,6 +98,8 @@ function isRetryableError(error, policy) {
         return true;
     }
     if (error instanceof ApiError) {
+        if (error.code && TERMINAL_API_CODES.has(error.code))
+            return false;
         if (error.statusCode === 429)
             return true;
         if (policy === "no-replay")

package/dist/src/version.js

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