gangtise-openapi-cli 0.26.0 → 0.28.0

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;
@@ -40,12 +125,28 @@ export class ApiError extends CliError {
     constructor(message, code, statusCode, details, 
     /** Server-specified Retry-After (ms), set on 429 responses so the transport
      * backoff can honor it instead of the default exponential schedule. */
-    retryAfterMs) {
+    retryAfterMs, 
+    /** Context-specific hint that beats the generic per-code table — e.g. EDE's
+     * 999999 means "no data", not the table's "系统错误，请稍后重试". */
+    hintOverride) {
         super(message);
         this.code = code;
         this.statusCode = statusCode;
         this.details = details;
         this.retryAfterMs = retryAfterMs;
-        this.hint = code ? ERROR_HINTS[code] : undefined;
+        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;
@@ -34,7 +38,9 @@ function rowOf(values, index) {
 // Build one column header per series. Prefer the human-readable name; on a
 // duplicate name append the code so a column is never silently overwritten.
 function buildHeaders(names, codes, count) {
-    const used = new Set();
+    // Pre-seed the metadata column names: an indicator literally named "date" /
+    // "security" / "name" must get a suffixed header, not overwrite the metadata.
+    const used = new Set(["date", "security", "name"]);
     const headers = [];
     for (let i = 0; i < count; i++) {
         const base = String(names?.[i] ?? codes?.[i] ?? `col${i}`);

package/dist/src/core/output.js

@@ -9,10 +9,11 @@ export function parseOutputFormat(value) {
     throw new ConfigError(`Unsupported format: ${format}`);
 }
 /** Cell text for terminal-facing formats (table/markdown): newlines collapsed for
- * alignment, remaining C0/DEL control chars stripped so server data can't inject
- * terminal escape sequences (ESC[31m etc.) into the user's terminal. */
+ * alignment, remaining C0/DEL/C1 control chars stripped so server data can't inject
+ * terminal escape sequences into the user's terminal (U+009B is a one-byte CSI
+ * that 8-bit-control terminals treat exactly like ESC[). */
 function sanitizeCell(value) {
-    return value.replace(/[\r\n]+/g, " ").replace(/[\u0000-\u001f\u007f]/g, "");
+    return value.replace(/[\r\n]+/g, " ").replace(/[\u0000-\u001f\u007f\u0080-\u009f]/g, "");
 }
 /** Terminal display width: CJK/fullwidth chars and emoji occupy 2 columns — padEnd
  * counts UTF-16 code units and misaligns every table containing Chinese text or emoji
@@ -62,6 +63,24 @@ function toRows(value) {
     }
     return [{ value }];
 }
+// One huge cell (a 50KB brief/chat message) would otherwise force every row of
+// that column to be padded to the same width — rows × width of pure spaces.
+const MAX_CELL_DISPLAY_WIDTH = 120;
+/** Truncate a cell to the display-width cap, ellipsis included in the budget. */
+function clampCell(value) {
+    if (displayWidth(value) <= MAX_CELL_DISPLAY_WIDTH)
+        return value;
+    let out = "";
+    let width = 0;
+    for (const ch of value) {
+        const w = displayWidth(ch);
+        if (width + w > MAX_CELL_DISPLAY_WIDTH - 1)
+            break;
+        out += ch;
+        width += w;
+    }
+    return out + "…";
+}
 function renderTable(rows) {
     if (rows.length === 0) {
         return "(empty)";
@@ -73,8 +92,8 @@ function renderTable(rows) {
     // spreading a per-row array overflows the call stack on large results (table is
     // the default format, e.g. `quote day-kline --security all`). Widths and padding
     // use displayWidth so CJK cells stay aligned.
-    const headerCells = columns.map(sanitizeCell);
-    const matrix = rows.map((row) => columns.map((column) => sanitizeCell(formatScalar(row[column]))));
+    const headerCells = columns.map((column) => clampCell(sanitizeCell(column)));
+    const matrix = rows.map((row) => columns.map((column) => clampCell(sanitizeCell(formatScalar(row[column])))));
     const widths = columns.map((_, c) => matrix.reduce((max, cells) => Math.max(max, displayWidth(cells[c])), displayWidth(headerCells[c])));
     const renderLine = (values) => values.map((value, index) => value + " ".repeat(Math.max(0, widths[index] - displayWidth(value)))).join("  ");
     const header = renderLine(headerCells);
@@ -89,9 +108,12 @@ function renderMarkdown(rows) {
     const columns = Array.from(new Set(rows.flatMap((row) => Object.keys(row))));
     // Column names come from server data (e.g. EDE indicator display names) — escape
     // them like cell values or a name containing | / , breaks the whole table.
-    const header = `| ${columns.map((column) => sanitizeCell(column).replaceAll("|", "\\|")).join(" | ")} |`;
+    // Backslash must go first: escaping only "|" turns a literal `\|` into `\\|`,
+    // which GFM reads as an escaped backslash + BARE pipe → an extra column.
+    const mdEscape = (value) => value.replaceAll("\\", "\\\\").replaceAll("|", "\\|");
+    const header = `| ${columns.map((column) => mdEscape(sanitizeCell(column))).join(" | ")} |`;
     const divider = `| ${columns.map(() => "---").join(" | ")} |`;
-    const body = rows.map((row) => `| ${columns.map((column) => sanitizeCell(formatScalar(row[column])).replaceAll("|", "\\|")).join(" | ")} |`);
+    const body = rows.map((row) => `| ${columns.map((column) => mdEscape(sanitizeCell(formatScalar(row[column])))).join(" | ")} |`);
     return [header, divider, ...body].join("\n");
 }
 function renderCsv(rows) {

package/dist/src/core/quoteSharding.js

@@ -153,8 +153,11 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
     let fieldList;
     let header = null;
     const merged = [];
-    let truncatedShards = 0;
-    for (const r of results) {
+    // Record WHICH windows maxed out, not just how many: a script/agent consumer
+    // needs the concrete date ranges to re-pull narrower windows (mirrors failedShards).
+    const truncatedShards = [];
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
         if (!(r && typeof r === "object"))
             continue;
         const rec = r;
@@ -163,7 +166,7 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
         if (!fieldList && Array.isArray(rec.fieldList))
             fieldList = rec.fieldList;
         if (isTruncated(rec))
-            truncatedShards++;
+            truncatedShards.push(shards[i]);
         // Append one-by-one rather than push(...list): a future higher row cap could
         // make a single shard's list large enough to overflow the stack via spread.
         if (Array.isArray(rec.list))
@@ -187,9 +190,10 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
         out.failedShards = failedShards;
         process.stderr.write(`[gangtise] warning: ${failedShards.length}/${shards.length} shards failed; results are partial (see failedShards)\n`);
     }
-    if (truncatedShards > 0) {
+    if (truncatedShards.length > 0) {
         out.partial = true;
-        process.stderr.write(`[gangtise] warning: ${truncatedShards}/${shards.length} shard(s) hit the ${perShardLimit}-row limit and were likely truncated; results are partial — ${truncationHint}.\n`);
+        out.truncatedShards = truncatedShards;
+        process.stderr.write(`[gangtise] warning: ${truncatedShards.length}/${shards.length} shard(s) hit the ${perShardLimit}-row limit and were likely truncated; results are partial (see truncatedShards) — ${truncationHint}.\n`);
     }
     return out;
 }

package/dist/src/core/transport.js

@@ -62,11 +62,34 @@ export async function runWithConcurrency(items, concurrency, fn) {
     await Promise.all(Array.from({ length: limit }, () => worker()));
     return results;
 }
+/** Parse GANGTISE_PAGE_CONCURRENCY defensively. runWithConcurrency clamps to
+ * ≥1 worker, so a negative/zero/NaN value silently degrades to SERIAL fetching
+ * (slow, confusing); an absurd value fans out up to items.length workers at
+ * once and can 429-storm the server. Fall back to the default and cap at 32. */
+export function resolvePageConcurrency(raw, fallback = 5, max = 32) {
+    const parsed = Math.floor(Number(raw));
+    if (!Number.isFinite(parsed) || parsed < 1)
+        return fallback;
+    return Math.min(parsed, max);
+}
 /** Fan-out width for pagination and kline shards — one env knob tunes both. */
-export const PAGE_CONCURRENCY = Number(process.env.GANGTISE_PAGE_CONCURRENCY ?? 5) || 5;
+export const PAGE_CONCURRENCY = resolvePageConcurrency(process.env.GANGTISE_PAGE_CONCURRENCY);
 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"]);
@@ -75,13 +98,15 @@ 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")
             return false;
-        if (error.statusCode != null && RETRYABLE_HTTP_STATUS.has(error.statusCode))
-            return true;
         if (error.code && RETRYABLE_API_CODES.has(error.code))
+            return policy !== "no-999999";
+        if (error.statusCode != null && RETRYABLE_HTTP_STATUS.has(error.statusCode))
             return true;
         return false;
     }
@@ -100,6 +125,12 @@ function isRetryableError(error, policy) {
 export function markRetryable(error) {
     return Object.assign(error, { __retryable: true });
 }
+/** Errors worth waiting out (anything the default policy would retry): transient
+ * 5xx / network / timeout / 429 / 999999. Used by async polling to survive a
+ * blip without abandoning a multi-minute wait. */
+export function isTransientError(error) {
+    return isRetryableError(error, "default");
+}
 export async function withRetry(fn, options = {}) {
     const retries = options.retries ?? 2;
     const baseDelay = options.baseDelayMs ?? 400;

package/dist/src/version.js

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