gangtise-openapi-cli 0.34.0 → 0.34.1

package/README.md

@@ -6,6 +6,7 @@
 
 README 仅列最近 5 个版本摘要：
 
+- **v0.34.1 — 2026-08-15**：EDE 报告期类指标传错日期参数时，报错里直接给出该改的 CLI 写法（此前只有服务端那句「缺少必填参数 reportDate」，要自己推断该用 `--indicator-param`）；该提示对 `100001` / `100003` 两个错误码都生效，并注明少数指标两个日期都要、另有指标要 `fiscalYear`，一律以 `indicator search` 的 `parameterList` 为准。另修复下载文件名缓存在并发写入下可能丢条目的问题（单进程使用不受影响）。
 - **v0.34.0 — 2026-08-15**：跟进 2026-08-14 服务端更新。🔴 **破坏性**：`quote day-kline --security all` 已失效（服务端停止支持），改用 `aShares` / `hkStocks` / `usStocks`，且市场关键字必须单独传（不能与证券代码或另一个关键字混填）——这两种写法 CLI 都会在发请求前报错并指出正确写法；`ai stock-summary` 同理不再接受市场关键字。`day-kline` 现覆盖 A股/港股/美股个股与交易所/概念/行业指数（可混查），三个旧命令 `day-kline-hk`/`day-kline-us`/`index-day-kline` 标记为已下线；`minute-kline` 支持指数。**另两处影响取数完整性的修复**：`quote fund-flow` 把市场关键字与证券代码混填时，此前会只返回那几个代码的数据且不报错（"全市场 + 这只"静默变成"只有这只"），现改为本地拦截；`quote index-day-kline --security all` 跨 30 天以上时分片过宽会撞行数上限被截断（标 `partial` + 退出 3），现已调细粒度，同区间可完整取回。另：三大报表新增 `earliestAnncDate`（做时点对齐用它，不要用 `announcementDate`），EDE 报告期类指标改为必须显式传 `reportDate`，错误码提示按新行为更新。
 - **v0.33.0 — 2026-08-09**：四处行为变更，都是把「静默给出看着正常的错结果」改成显式失败——分页端点返回异形首包（含 `data: null`）改退出码 3；`total` 被服务端封顶时探测并标 `totalCapped` + 退出 3（三个 opinion 端点的 `total` 恒为 10000 而实际远不止，全量导出此前会被静默截断）；空结果不再在 stdout 留空行、`null` 不再被渲染成一条记录。另补多处帮助文案与 EDE 占位值（个别指标填 `0` 而非 `null`）的说明。
 - **v0.32.0 — 2026-08-08**：新增帕米尔专家纪要列表与下载；跟进 2026-08-07 服务端更新——EDE 缺数据不再整列/整行消失（退出码 3 现在专指「代码没被识别」），条件选股重复指标的 `unreliable` 告警随之移除；`--search-type`/`--rank-type`/`--file-type` 等枚举改为本地拦截（此前传非法值不会报错，会拿到未过滤的全量）。

package/dist/src/core/errors.js

@@ -128,6 +128,31 @@ const ERROR_HINTS = {
     "999997": "联系客户经理开通。",
     "10011401": "联系客户经理开通白名单。",
 };
+/** Hints keyed on the server's message rather than its code. Used where one code
+ * covers many causes and the message identifies which — `100003` in particular is
+ * the catch-all for every EDE input error, so its per-code hint can only be generic.
+ *
+ * Kept to cases where the server names the problem but not the CLI flag that fixes
+ * it: the caller is told "缺少必填参数 reportDate" and still has to work out that
+ * such indicators need `--indicator-param`, not `--date`.
+ *
+ * ⚠️ Do NOT restate this as a rule about code prefixes or as a clean two-way split.
+ * Survey of 170 indicators (2026-08-15) says otherwise: 117 take `reportDate` only,
+ * 51 take `tradeDate` only, `div_cash_yld` takes BOTH (both required), and
+ * `div_cash_yr` / `div_cash_paid_ratio` take NEITHER (they want `fiscalYear`).
+ * Prefixes cut across it too — 7 `finc_*` and 3 `div_*` want `reportDate`, while 8
+ * `is_*` and 4 `cf_*` want `tradeDate`. The hint therefore points at
+ * `indicator search` rather than asserting which indicators are affected.
+ *
+ * Both codes are listed because the server sends this same sentence under either:
+ * `is_op_rev` answers 100003, `div_cash_yld` answers 100001 (probed 2026-08-15). */
+const MESSAGE_HINTS = [
+    {
+        codes: ["100001", "100003"],
+        match: /不支持参数\s*tradeDate|缺少必填参数[:：]?\s*reportDate/,
+        hint: "这个指标要的是 reportDate（报告期），不是 --date 下发的 tradeDate。补 --indicator-param \"<指标code>:reportDate=YYYY-MM-DD\"（screener 用 \"F1:reportDate=...\"），--date 仍要保留。⚠️ 少数指标两个日期都要（如 div_cash_yld），补完 reportDate 若再报缺 tradeDate，就把 tradeDate 也显式传上；另有指标要的是 fiscalYear。**以 `indicator search` 返回的 parameterList 为准，别按 code 前缀推断**。",
+    },
+];
 export class ApiError extends CliError {
     code;
     statusCode;
@@ -148,7 +173,13 @@ export class ApiError extends CliError {
         this.statusCode = statusCode;
         this.details = details;
         this.retryAfterMs = retryAfterMs;
-        this.hint = hintOverride ?? (code ? ERROR_HINTS[code] : undefined);
+        // Precedence: explicit override > message-specific > per-code. The message rule
+        // sits in the middle because it identifies a narrower cause than the code alone,
+        // but a call site that already knows the context still knows better.
+        const byMessage = code
+            ? MESSAGE_HINTS.find((rule) => rule.codes.includes(code) && rule.match.test(message))?.hint
+            : undefined;
+        this.hint = hintOverride ?? byMessage ?? (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

package/dist/src/core/titleCache.js

@@ -20,39 +20,80 @@ export const MAX_TITLES_PER_ENDPOINT = 5_000;
 let memoryCache = null;
 let memoryCachePath = null;
 let pendingWrite = null;
+let pendingLoad = null;
+/** Which file `pendingLoad` is loading. Keyed alongside the promise because the
+ * cache is a single-slot module global: coalescing on the promise ALONE would hand
+ * a caller asking for file B the contents of file A. */
+let pendingLoadPath = null;
 let dirty = false;
 async function loadInto(filePath) {
     if (memoryCache && memoryCachePath === filePath)
         return memoryCache;
+    // Coalesce concurrent first-loads. Without this, two callers that both miss the
+    // cache each run their own readFile and each assign their OWN object to
+    // `memoryCache`; the last assignment wins, and entries written against the
+    // loser's reference are silently dropped. Sharing one promise means every
+    // caller gets the same object, so merges land in one place.
+    //
+    // The path check is what keeps that from becoming a worse bug than the one it
+    // fixes: same promise for the same file is deduplication, same promise for a
+    // different file is handing back the wrong file's data.
+    if (pendingLoad && pendingLoadPath === filePath)
+        return pendingLoad;
+    const load = (async () => {
+        try {
+            const content = await fs.readFile(filePath, "utf8");
+            const parsed = JSON.parse(content);
+            memoryCache = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+        }
+        catch {
+            memoryCache = {};
+        }
+        memoryCachePath = filePath;
+        return memoryCache;
+    })();
+    pendingLoad = load;
+    pendingLoadPath = filePath;
     try {
-        const content = await fs.readFile(filePath, "utf8");
-        const parsed = JSON.parse(content);
-        memoryCache = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+        return await load;
     }
-    catch {
-        memoryCache = {};
+    finally {
+        // Only clear if still ours — a load for another path may have replaced it.
+        if (pendingLoad === load) {
+            pendingLoad = null;
+            pendingLoadPath = null;
+        }
     }
-    memoryCachePath = filePath;
-    return memoryCache;
 }
 export async function readTitleCache(filePath = DEFAULT_TITLE_CACHE_PATH) {
     return loadInto(filePath);
 }
 async function flush(filePath) {
-    if (!dirty || !memoryCache)
-        return;
-    dirty = false;
-    const snapshot = JSON.stringify(memoryCache);
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-    // Atomic-ish: write to temp file then rename (rename is atomic within a fs).
-    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
-    await fs.writeFile(tmp, snapshot, { encoding: "utf8", mode: 0o600 });
-    try {
-        await fs.rename(tmp, filePath);
-    }
-    catch (error) {
-        await fs.unlink(tmp).catch(() => { });
-        throw error;
+    // Loop rather than snapshot once. `dirty` is cleared before the snapshot, so an
+    // entry added while we await the rename sets it again — and `writeTitleCache`
+    // hands that caller THIS in-flight promise instead of starting a second flush.
+    // Returning after one pass would leave that entry in memory only, never on disk.
+    for (;;) {
+        // Deciding to stop and releasing the in-flight handle must happen in ONE
+        // synchronous block. If they were split by an await, a write landing between
+        // them would attach to an already-resolving flush and never be written.
+        if (!dirty || !memoryCache) {
+            pendingWrite = null;
+            return;
+        }
+        dirty = false;
+        const snapshot = JSON.stringify(memoryCache);
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        // Atomic-ish: write to temp file then rename (rename is atomic within a fs).
+        const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+        await fs.writeFile(tmp, snapshot, { encoding: "utf8", mode: 0o600 });
+        try {
+            await fs.rename(tmp, filePath);
+        }
+        catch (error) {
+            await fs.unlink(tmp).catch(() => { });
+            throw error;
+        }
     }
 }
 /**
@@ -118,14 +159,34 @@ export async function writeTitleCache(endpoint, titles, filePath = DEFAULT_TITLE
     pruneCache(data, endpoint, Object.keys(titles));
     dirty = true;
     // Coalesce concurrent writes: the in-flight flush picks up everything dirty.
+    //
+    // `flush` clears `pendingWrite` itself, in the same synchronous block as the
+    // `if (!dirty || !memoryCache)` test that decides to stop looping. Clearing it out
+    // here — in a `finally` after `await flush(...)` — would leave a gap of microtasks
+    // between "flush decided nothing is left" and "flush is no longer in flight": a
+    // write landing in that gap sets `dirty`, sees a non-null `pendingWrite`, and
+    // attaches to a promise that is already resolving, so its entry never reaches
+    // disk while its `await` still resolves normally. Same silent loss the loop was
+    // added to fix, just a narrower window.
     if (pendingWrite)
         return pendingWrite;
     pendingWrite = (async () => {
         try {
             await flush(filePath);
         }
-        finally {
+        catch (error) {
+            // flush throws before reaching its own clear, so release the handle here.
+            // Safe to null unconditionally: nothing else can have replaced it, since a
+            // non-null pendingWrite is exactly what stops another flush from starting.
+            //
+            // ⚠️ Only the SUCCESS path is atomic. A write landing between the throw and
+            // this line still attaches to the rejecting promise and never reaches disk;
+            // it recovers on the next successful write (which re-serialises the whole
+            // in-memory cache), and is lost only if no write ever follows. Left as-is
+            // deliberately — retrying against a filesystem that is already failing is
+            // worse than deferring to the next write.
             pendingWrite = null;
+            throw error;
         }
     })();
     return pendingWrite;
@@ -156,5 +217,10 @@ export function __resetTitleCacheForTests() {
     memoryCache = null;
     memoryCachePath = null;
     pendingWrite = null;
+    // Must include the load handles: a reset that leaves `pendingLoad` set would hand
+    // the next readTitleCache the pre-reset promise, breaking the "force a fresh read
+    // from disk" contract this helper exists to provide.
+    pendingLoad = null;
+    pendingLoadPath = null;
     dirty = false;
 }

package/dist/src/version.js

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

package/gangtise-openapi/SKILL.md

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

package/package.json

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