gangtise-openapi-cli 0.41.1 → 0.42.0

package/dist/src/core/fileParse.js

@@ -1,9 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { isAsyncPending, nextPollDelayMs, POLL_MAX_ATTEMPTS } from "./asyncContent.js";
+import { isAsyncPending, pollUntilDone } from "./asyncContent.js";
 import { saveDownloadResult } from "./download.js";
 import { ApiError, ValidationError } from "./errors.js";
-import { isTransientError } from "./transport.js";
 export const FILE_PARSE_MAX_BYTES = 100 * 1024 * 1024;
 export async function submitFileParse(client, filePath) {
     const resolved = path.resolve(filePath);
@@ -50,22 +49,6 @@ export async function fetchFileParseResult(client, taskId, output) {
     return "ok";
 }
 export async function pollFileParseResult(client, taskId, output) {
-    for (let attempt = 1; attempt <= POLL_MAX_ATTEMPTS; attempt++) {
-        try {
-            if (await fetchFileParseResult(client, taskId, output) === "ok")
-                return "ok";
-        }
-        catch (error) {
-            if (!isTransientError(error))
-                throw error;
-            const msg = error instanceof Error ? error.message : String(error);
-            process.stderr.write(`Attempt ${attempt}/${POLL_MAX_ATTEMPTS}: transient error (${msg.slice(0, 80)}), continuing to wait...\n`);
-        }
-        if (attempt < POLL_MAX_ATTEMPTS) {
-            const delay = nextPollDelayMs(attempt);
-            process.stderr.write(`Attempt ${attempt}/${POLL_MAX_ATTEMPTS}: parse result not ready, retrying in ${Math.round(delay / 1000)}s...\n`);
-            await new Promise(resolve => setTimeout(resolve, delay));
-        }
-    }
-    return "timeout";
+    const outcome = await pollUntilDone(async () => await fetchFileParseResult(client, taskId, output), "parse result not ready");
+    return outcome === "ok" ? "ok" : "timeout";
 }

package/dist/src/core/opinionDetail.js

@@ -0,0 +1,39 @@
+import { ApiError, ValidationError } from "./errors.js";
+export async function fetchOpinionDetails(client, endpointKey, idListField, idField, ids) {
+    const BATCH = 20;
+    const unique = [...new Set(ids)];
+    if (!unique.length)
+        throw new ValidationError("pass at least one opinion ID");
+    const list = [];
+    let unfetched = [];
+    let unfetchedError;
+    for (let i = 0; i < unique.length; i += BATCH) {
+        try {
+            const rows = await client.call(endpointKey, { [idListField]: unique.slice(i, i + BATCH) });
+            list.push(...rows);
+        }
+        catch (error) {
+            if (i === 0)
+                throw error;
+            unfetched = unique.slice(i);
+            const message = error instanceof Error ? error.message : String(error);
+            unfetchedError = { message, ...(error instanceof ApiError ? { code: error.code, traceId: error.traceId } : {}) };
+            process.stderr.write(`[gangtise] warning: ${endpointKey} failed on batch ${i / BATCH + 1} (${message}); ${unfetched.length} ID(s) not fetched: ${unfetched.join(", ")}. The bodies already returned are kept below — re-run for the IDs in unfetchedIds only.\n`);
+            break;
+        }
+    }
+    const returned = new Set(list.map((row) => String(row[idField])));
+    const missing = unique.filter((id) => !returned.has(id) && !unfetched.includes(id));
+    const out = { total: list.length, list };
+    if (missing.length > 0) {
+        process.stderr.write(`[gangtise] warning: no body returned for ${missing.length} ID(s): ${missing.join(", ")} — the server skips an ID it has no body for without an error (e.g. a wrong ID; a just-published opinion may also not have its body yet). Result marked partial (exit 3).\n`);
+        out.missingIds = missing;
+    }
+    if (unfetched.length > 0) {
+        out.unfetchedIds = unfetched;
+        out.unfetchedError = unfetchedError;
+    }
+    if (missing.length > 0 || unfetched.length > 0)
+        out.partial = true;
+    return out;
+}

package/dist/src/core/output.js

@@ -170,16 +170,26 @@ export async function streamOutputToFile(value, format, outputPath) {
     stream.on("error", () => { });
     try {
         if (format === "jsonl") {
+            let chunk = [];
             for (const item of jsonlItems(value)) {
-                await writeLine(stream, JSON.stringify(item));
+                chunk.push(JSON.stringify(item));
+                if (chunk.length >= LINES_PER_WRITE) {
+                    await writeLines(stream, chunk);
+                    chunk = [];
+                }
             }
+            await writeLines(stream, chunk);
         }
         else {
-            await writeLine(stream, "\ufeff" + csvColumns.map(csvEscape).join(","));
+            let chunk = ["\ufeff" + csvColumns.map(csvEscape).join(",")];
             for (const row of csvRows) {
-                const cells = csvColumns.map((column) => csvEscape(formatScalar(row[column])));
-                await writeLine(stream, cells.join(","));
+                chunk.push(csvColumns.map((column) => csvEscape(formatScalar(row[column]))).join(","));
+                if (chunk.length >= LINES_PER_WRITE) {
+                    await writeLines(stream, chunk);
+                    chunk = [];
+                }
             }
+            await writeLines(stream, chunk);
         }
         await new Promise((resolve, reject) => {
             stream.end((err) => err ? reject(err) : resolve());
@@ -215,6 +225,10 @@ export function csvEscape(value) {
         return `"${out.replaceAll("\"", "\"\"")}"`;
     return out;
 }
+export const LINES_PER_WRITE = 1000;
+export function writeLines(stream, lines) {
+    return lines.length === 0 ? Promise.resolve() : writeLine(stream, lines.join("\n"));
+}
 export function writeLine(stream, line) {
     return new Promise((resolve, reject) => {
         const ok = stream.write(line + "\n", (err) => err ? reject(err) : undefined);

package/dist/src/core/printer.js

@@ -5,16 +5,16 @@ import { countOutputRows, digestFile, pickList, renderOutput, saveOutputIfNeeded
 import { getRowSink } from "./rowSink.js";
 import { extractTitles, writeTitleCache } from "./titleCache.js";
 import { CLI_VERSION } from "../version.js";
+import { decidedExitCode, EXIT_SUPERSEDED, markIncomplete, markSuperseded } from "./exitStatus.js";
 const LARGE_RESULT_ROWS = 50_000;
-export const SUPERSEDED_EXIT = 4;
+export const SUPERSEDED_EXIT = EXIT_SUPERSEDED;
 export async function warnIfSuperseded(output, digest) {
     const actual = await digestFile(output).catch(() => undefined);
     if (!actual || actual.sha256 === digest.sha256)
         return;
     process.stderr.write(`[gangtise] warning: ${output} was replaced by another export to the same path while this one was finishing — the file there is not this command's output `
         + `(wrote sha256 ${digest.sha256.slice(0, 12)}…, found ${actual.sha256.slice(0, 12)}…). Give concurrent exports distinct --output paths.\n`);
-    if (process.exitCode !== 3)
-        process.exitCode = SUPERSEDED_EXIT;
+    markSuperseded();
 }
 function warnIfLargeInMemory(items, format) {
     if (items && items.length >= LARGE_RESULT_ROWS) {
@@ -63,7 +63,7 @@ async function stageExportMeta(output, format, rows, columns, normalized, comple
         format,
         rows,
         complete,
-        exitCode: complete ? 0 : 3,
+        exitCode: decidedExitCode(),
         command: redactSecrets(process.argv.slice(2)),
         cliVersion: CLI_VERSION,
         fetchedAt: localIso(new Date()),
@@ -121,11 +121,10 @@ export async function printData(data, format, output, cache) {
         if (typeof meta.total === "number" && format !== "json") {
             process.stderr.write(`Total: ${meta.total}, showing: ${showing}\n`);
         }
-        if (meta.partial === true) {
-            process.exitCode = 3;
-        }
+        if (meta.partial === true)
+            markIncomplete();
     }
-    const complete = process.exitCode !== 3;
+    const complete = decidedExitCode() === 0;
     if (output) {
         const staged = format === "csv" || format === "jsonl"
             ? await stageExportMeta(output, format, streamed ? streamed.dataRows : countOutputRows(normalized, format), columns, normalized, complete)

package/dist/src/core/rowSink.js

@@ -2,7 +2,7 @@ import { createReadStream, createWriteStream } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertColumnarHeader, zipFieldRow } from "./normalize.js";
-import { csvEscape, digestFile, formatScalar, stagingPath, writeLine } from "./output.js";
+import { csvEscape, digestFile, formatScalar, stagingPath, writeLine, writeLines, LINES_PER_WRITE } from "./output.js";
 import { extractTitles, MAX_TITLES_PER_ENDPOINT } from "./titleCache.js";
 export const ROW_SINK = Symbol("gangtise.rowSink");
 const STREAM_THRESHOLD = 1000;
@@ -100,6 +100,7 @@ export class ExportSink {
     }
     async write(rows) {
         const stream = this.stream;
+        let chunk = [];
         for (const row of rows) {
             let item = row;
             if (Array.isArray(row)) {
@@ -118,7 +119,11 @@ export class ExportSink {
                     }
                 }
             }
-            await writeLine(stream, JSON.stringify(item));
+            chunk.push(JSON.stringify(item));
+            if (chunk.length >= LINES_PER_WRITE) {
+                await writeLines(stream, chunk);
+                chunk = [];
+            }
             this.rows++;
             if (this.cache && this.titleCount < MAX_TITLES_PER_ENDPOINT) {
                 for (const [id, title] of Object.entries(extractTitles([item], this.cache))) {
@@ -128,6 +133,7 @@ export class ExportSink {
                 }
             }
         }
+        await writeLines(stream, chunk);
     }
     async assembleCsv() {
         const out = createWriteStream(this.partPath, { encoding: "utf8" });
@@ -139,17 +145,18 @@ export class ExportSink {
         const input = createReadStream(this.rowsPath, { encoding: "utf8" });
         try {
             let index = 0;
-            const emit = async (line) => {
+            let csvLines = [];
+            const emit = (line) => {
                 if (!line)
                     return;
                 const item = JSON.parse(line);
                 if (objectMode) {
                     if (!isObjectRow(item))
                         return;
-                    await writeLine(out, columns.map((column) => csvEscape(formatScalar(item[column]))).join(","));
+                    csvLines.push(columns.map((column) => csvEscape(formatScalar(item[column]))).join(","));
                 }
                 else {
-                    await writeLine(out, `${csvEscape(String(index++))},${csvEscape(formatScalar(item))}`);
+                    csvLines.push(`${csvEscape(String(index++))},${csvEscape(formatScalar(item))}`);
                 }
             };
             let rest = "";
@@ -157,9 +164,14 @@ export class ExportSink {
                 const lines = (rest + String(chunk)).split("\n");
                 rest = lines.pop() ?? "";
                 for (const line of lines)
-                    await emit(line);
+                    emit(line);
+                if (csvLines.length >= LINES_PER_WRITE) {
+                    await writeLines(out, csvLines);
+                    csvLines = [];
+                }
             }
-            await emit(rest);
+            emit(rest);
+            await writeLines(out, csvLines);
             await endStream(out);
         }
         catch (error) {

package/dist/src/core/transport.js

@@ -39,7 +39,7 @@ export function getDispatcher() {
         cachedDispatcher = new Agent({
             keepAliveTimeout: 60_000,
             keepAliveMaxTimeout: 600_000,
-            connections: 16,
+            connections: Math.max(16, PAGE_CONCURRENCY),
             pipelining: 1,
         });
     }
@@ -62,8 +62,9 @@ export async function runWithConcurrency(items, concurrency, fn) {
     await Promise.all(Array.from({ length: limit }, () => worker()));
     return results;
 }
-export async function runInOrder(items, concurrency, fn, consume) {
+export async function runInOrder(items, concurrency, fn, consume, window = concurrency) {
     const width = Math.max(1, concurrency);
+    const maxPending = Math.max(width, window);
     const pending = new Map();
     let next = 0;
     let failure = null;
@@ -104,7 +105,7 @@ export async function runInOrder(items, concurrency, fn, consume) {
             return;
         pending.set(index, result);
         drain();
-        while (!failure && pending.size >= width) {
+        while (!failure && pending.size >= maxPending) {
             await new Promise((resolve) => waiters.push(resolve));
         }
     });

package/dist/src/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "0.41.1";
+export const CLI_VERSION = "0.42.0";

package/gangtise-openapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gangtise-openapi
-version: "0.41.1"
+version: "0.42.0"
 description: |-
   通过 gangtise CLI 直接调用 Gangtise OpenAPI，拉取投研原始数据、批量导出、下载文件、调用 AI 能力。
 

package/gangtise-openapi/references/commands/ai.md

@@ -115,7 +115,7 @@ gangtise ai theme-tracking --theme-id <id> --date <yyyy-MM-dd> [--type <name>]
 **示例：**
 ```bash
 # 查"核电"主题 2026-05-09 的晚报
-GANGTISE_TIMEOUT_MS=120000 gangtise ai theme-tracking --theme-id 121000002 --date 2026-05-09 --type night --format json
+gangtise ai theme-tracking --theme-id 121000002 --date 2026-05-09 --type night --format json
 # 返回 [{"type":"night","date":"2026-05-09","content":"..."}]
 ```
 

package/gangtise-openapi/references/commands/fundamental.md

@@ -95,7 +95,7 @@ gangtise fundamental valuation-analysis --security-code <code> --indicator <name
 - 🔴 **序列按自然日逐日一行（含周末）**，行数超过 `--limit` 时接口**保留最近的行、丢掉区间开头**。CLI 撞满即标 `partial`、退出码 3 并在 stderr 说明（首行恰好就是 `--start-date` 时说明没丢，不标）。取长区间把 `--limit` 设到不小于区间天数（账号权限窗口内的十年约 3700 行，可设 `--limit 4000`）
 - 🔴 **`--start-date` 早于账号回溯下界时，接口从下界起返回、不报错**（整段都在界外才报 `110003`）。首行晚于 `--start-date` 时 CLI 在 stderr 提示——可能是该证券上市较晚，也可能是撞了权限窗口，看首行日期判断
 - `--skip-null`：丢弃 `value`/`percentileRank` 为 null 的行（最新交易日可能未入库）
-- **返回字段只有 7 个**：`tradeDate` `value` `percentileRank` `average` `median` `upper1Std` `lower1Std`，**没有 `securityCode`**。🔴 `--field` 里**至少要有一个数值列**（`tradeDate` 以外的 6 个）：只传 `tradeDate`、只传不存在的名字（含 `securityCode`）时接口返回 0 行、**不报错**，读起来像「这只票没有估值数据」；数值列与不存在的名字混传时，回显的字段比每行的值多，CLI 直接报错退出 1。`tradeDate` 总在第一列返回，不用写进 `--field`（写了 CLI 会在发请求前去掉；同一字段写两次也只发一次）。**建议不传 `--field`**，证券代码本来就是你自己传进去的
+- **返回字段只有 7 个**：`tradeDate` `value` `percentileRank` `average` `median` `upper1Std` `lower1Std`，**没有 `securityCode`**。🔴 `--field` 里**至少要有一个数值列**（`tradeDate` 以外的 6 个）：只传 `tradeDate`、只传不存在的名字（含 `securityCode`）时接口返回 0 行、**不报错**，读起来像「这只票没有估值数据」（CLI 会在 stderr 提示原因）；数值列与不存在的名字混传时，回显的字段比每行的值多，CLI 直接报错退出 1。`tradeDate` 总在第一列返回，不用写进 `--field`（写了 CLI 会在发请求前去掉；同一字段写两次也只发一次）。**建议不传 `--field`**，证券代码本来就是你自己传进去的
 
 ## A股盈利预测 `fundamental earning-forecast`
 

package/gangtise-openapi/references/errors.md

@@ -69,7 +69,8 @@
 | 情形 | CLI 行为 | Agent 是否介入 |
 |------|---------|--------------|
 | HTTP 5xx / `ECONNRESET` / 超时 | **自动指数退避重试 ×2**（🔴 贵档端点不重放） | 仍失败提示用户 |
-| `ValidationError` | 本地参数校验失败 | 检查 `--from` / `--size` / `--limit` 数值，**不要重试同命令** |
+| `ValidationError` | 本地参数校验失败 | 检查 `--from` / `--size` / `--limit` 数值（数值只收十进制写法，`1e3` / `0x10` / `5.0` 会被拒），**不要重试同命令** |
+| 返回结构与约定不符（报错含 `returned no … payload` 与 trace） | 不猜测结构、按失败处理：单次请求的命令退出 1；分批 / 分片中某一批出现时，已取到的保留、其余标为未取（退出 3） | 带 trace 反馈；换参数重试没用 |
 
 ## 退出码 3：结果少了数据
 
@@ -81,10 +82,12 @@
 
 ## 退出码 4：数据写全了，但文件被另一次导出替换
 
-本次导出的数据完整写出了，`--output` 指向的文件却在收尾期间被**另一次写向同一路径的导出**替换掉——文件在，只是不是这条命令的产物。stderr 会给出两边的 `sha256` 前缀。给并发的导出各自的 `--output` 即可。
+本次导出的数据完整写出了，`--output` 指向的文件却在收尾期间被**另一次写向同一路径的导出**替换掉——文件在，只是不是这条命令的产物。stderr 会给出两边的 `sha256` 前缀。给并发的导出各自的 `--output` 即可。本次生成的 `.meta.json` 记录的是替换检查之前的判定；并发导出时，数据文件和元信息都可能被另一次导出覆盖。所以退出码 4 以本次进程的退出码和 stderr 为准，`sha256` 只能说明当前的数据文件与旁边的元信息是否匹配。
 
 与 `3` 分开是因为行没有缺、缺的是目的地。**两者同时发生时退出码是 `3`**——少了行是更重的那一个，替换另在 stderr 说明。
 
+**接管道时**：`gangtise … | head` 这类提前关掉读端的用法，CLI 仍以已判定的退出码（`3` / `4`）结束；shell 默认只看管道里最后一个命令，脚本要 `set -o pipefail` 才看得到。
+
 ## 其他场景
 
 - CLI 未安装 → `npm install -g gangtise-openapi-cli`
@@ -128,7 +131,7 @@
 
 **`quote day-kline --security all` 被 CLI 拒**（`'all' is not a whole-market keyword`）→ 服务端不支持该写法 → 换成 `aShares` / `hkStocks` / `usStocks` 之一，单独传。
 
-**AI agent 命令（one-pager 等）超时** → 服务端生成耗时长，CLI 默认 30s → `GANGTISE_TIMEOUT_MS=120000` 后重试。
+**AI 生成命令超时** → `one-pager` 等 7 个 agent 类 CLI 已内置 120 秒超时下限，无需再设 `GANGTISE_TIMEOUT_MS`。超时报错时内容可能已在服务端生成并扣费，**同参数重跑会再扣一次**：先告知用户，别自动重跑（详见 `references/commands/ai.md`）。`stock-summary` / `hot-topic` 可前置 `GANGTISE_TIMEOUT_MS=120000`（写整数毫秒；没按所写数值生效时 stderr 会提示）。
 
 **估值结果出现大量 `null`** → 最新交易日数据未入库 → 加 `--skip-null` 过滤掉 `value` / `percentileRank` 为 null 的行。
 

package/gangtise-openapi/references/examples.md

@@ -53,8 +53,8 @@
 1. 路由 → ai one-pager
 2. 比亚迪 → 002594.SZ（速查表）
    注意：one-pager 用 --security-code，不是 --security
-3. Pre-flight：首次生成常 >30s → 前置 `GANGTISE_TIMEOUT_MS=120000` 防超时重试；告知用户"生成中..."
-4. GANGTISE_TIMEOUT_MS=120000 gangtise ai one-pager --security-code 002594.SZ --format json
+3. Pre-flight：首次生成常 >30s，CLI 已内置 120 秒超时下限，无需前缀；告知用户"生成中..."
+4. gangtise ai one-pager --security-code 002594.SZ --format json
 5. 返回 {content: "markdown"} → 直接呈现 content，不要展示 JSON 包装
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gangtise-openapi-cli",
-  "version": "0.41.1",
+  "version": "0.42.0",
   "description": "CLI for Gangtise OpenAPI",
   "license": "MIT",
   "repository": {