gangtise-openapi-cli 0.34.0 → 0.35.0

package/dist/src/core/quoteSharding.js

@@ -1,11 +1,7 @@
 import { isVerbose, PAGE_CONCURRENCY, runWithConcurrency } from "./transport.js";
 const DAY_MS = 86_400_000;
-/** API-side row cap (per docs). Used to lift the default 6000-row cap on whole-market
- * queries so a 2-day A-share shard (~11K rows) isn't silently truncated. Single-security
- * queries are untouched. */
 const ALL_MARKET_LIMIT = 10_000;
 function parseDate(value) {
-    // Accept yyyy-MM-dd; reject anything else so we can fall back to a single request.
     if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
         return null;
     const d = new Date(`${value}T00:00:00Z`);
@@ -22,7 +18,6 @@ export function isFullMarket(body, fullMarketValue) {
         return false;
     return list[0] === fullMarketValue;
 }
-/** Sat/Sun in UTC — shard dates are formatted from UTC midnight (see parseDate). */
 function isWeekendUtc(d) {
     const day = d.getUTCDay();
     return day === 0 || day === 6;
@@ -33,16 +28,6 @@ function buildShards(start, end, shardDays) {
     const endTime = end.getTime();
     while (cursor <= endTime) {
         const shardEnd = Math.min(cursor + (shardDays - 1) * DAY_MS, endTime);
-        // Per-day sharding (shardDays===1): a lone weekend day always returns empty (A/HK/US
-        // markets closed) — skip it to save ~28% of requests and daily quota. This covers
-        // every 1-day-sharded full-market query: fund-flow AND day-kline (aShares/usStocks)
-        // / day-kline-us.
-        //
-        // Multi-day shards (day-kline hkStocks=2, index-day-kline=15) are NOT filtered. Note
-        // this is a deliberate simplification, not a claim that they always contain a weekday:
-        // a 2-day shard starting on a Saturday is Sat+Sun and returns nothing. That costs one
-        // wasted request at a range boundary and never drops a trading day, whereas filtering
-        // multi-day windows correctly would mean walking each window's days.
         if (!(shardDays === 1 && isWeekendUtc(new Date(cursor)))) {
             shards.push({
                 startDate: formatDate(new Date(cursor)),
@@ -53,36 +38,17 @@ function buildShards(start, end, shardDays) {
     }
     return shards;
 }
-/**
- * For full-market (`--security all`) K-line queries that span more than `shardDays`,
- * split the date range and run shards in parallel. Each shard is sized so the
- * combined row count stays under the 10K-row API limit. For small ranges or
- * single-security queries this is a no-op.
- */
 export async function callKlineWithSharding(client, endpointKey, body, config) {
     const fullMarketValue = config.fullMarketValue ?? "all";
     if (!isFullMarket(body, fullMarketValue)) {
         return client.call(endpointKey, body);
     }
-    // `--security all` returns thousands of rows per day; lift the default 6000-row
-    // cap to the API max so single-shard requests aren't silently truncated. This
-    // must apply even when a date is missing (no sharding possible then, but the
-    // single request still needs the lifted cap).
     const allMarketBody = { ...body, limit: body.limit ?? ALL_MARKET_LIMIT };
     const perShardLimit = allMarketBody.limit ?? ALL_MARKET_LIMIT;
-    // A shard maxes out for two reasons with different fixes: a user-set low --limit is
-    // raisable; hitting the API cap itself is not (only a smaller internal shardDays window
-    // would help). Word the truncation warning accordingly.
     const truncationHint = perShardLimit < ALL_MARKET_LIMIT
         ? "raise or omit --limit to fetch the full market"
         : `a single ${config.shardDays}-day window exceeds the ${ALL_MARKET_LIMIT}-row API cap`;
-    // A full-market response whose row count reaches the per-request limit was itself
-    // capped (a low user --limit, or a single day exceeding the API row cap) — its slice
-    // is incomplete, so the result must be flagged partial rather than shown as complete.
     const isTruncated = (rec) => Array.isArray(rec.list) && rec.list.length >= perShardLimit;
-    // A single full-market request (missing/unparseable dates, or a range that fits one
-    // shard) skips the merge loop below, so it needs the same truncation check inline — or
-    // a low --limit / oversized day slips through as a silent exit-0 success.
     const callSingle = async () => {
         const single = await client.call(endpointKey, allMarketBody);
         if (single && typeof single === "object" && !Array.isArray(single) && isTruncated(single)) {
@@ -105,37 +71,21 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
         return callSingle();
     }
     const shards = buildShards(start, end, config.shardDays);
-    // A range that's entirely weekends (per-day sharding) filters down to nothing — no
-    // trading days to fetch. Return empty rather than falling into the all-shards-failed
-    // check below, which would misread 0 shards as a total outage and throw.
     if (shards.length === 0)
         return { list: [] };
-    // isVerbose() (not a direct env read) so the global --verbose flag reaches
-    // shard logging too — cli.ts enables it via setVerbose in a preAction hook.
     if (isVerbose()) {
         process.stderr.write(`[gangtise] sharding ${endpointKey} into ${shards.length} requests (${config.shardDays} day(s) each)\n`);
     }
-    // Per-shard fault tolerance: a failing shard is recorded and skipped (returns a
-    // null sentinel) instead of rejecting, so the surviving shards still complete.
-    // runWithConcurrency uses Promise.all under the hood, which would otherwise abort
-    // every shard on the first rejection.
     const failedShards = [];
     let firstError = null;
     let aborted = false;
     const results = await runWithConcurrency(shards, config.concurrency ?? PAGE_CONCURRENCY, async (shard) => {
-        // A prior shard hit a hard error (rate limit, no-perm, retries exhausted). Stop
-        // dispatching the rest rather than burning quota into the same failure; record them
-        // as failed so the merged result is flagged partial. Mirrors requestPaginated.
         if (aborted) {
             failedShards.push(shard);
             return null;
         }
         try {
             const res = await client.call(endpointKey, { ...allMarketBody, startDate: shard.startDate, endDate: shard.endDate });
-            // A shard that resolves but carries no `list` array is shape-broken (an error
-            // object, a truncated envelope) — its rows are missing. Treat it exactly like a
-            // thrown shard so the result is marked partial, not silently short. Unlike a hard
-            // error this doesn't abort the fan-out: one malformed shard isn't systemic.
             if (!(res && typeof res === "object" && Array.isArray(res.list))) {
                 failedShards.push(shard);
                 return null;
@@ -153,8 +103,6 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
     let fieldList;
     let header = null;
     const merged = [];
-    // 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];
@@ -167,21 +115,15 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
             fieldList = rec.fieldList;
         if (isTruncated(rec))
             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))
             for (const item of rec.list)
                 merged.push(item);
     }
-    // Every shard failed → surface the error loudly (non-zero exit) rather than
-    // masking a total outage as an empty success.
     if (failedShards.length === shards.length) {
         throw firstError ?? new Error(`All ${shards.length} kline shards failed`);
     }
     if (!header)
         return { list: [] };
-    // `total` on a shard is that shard's own row count; overwrite it with the merged count
-    // so the JSON `total` and the `Total:` stderr line reflect the whole combined result.
     const out = { ...header, total: merged.length, list: merged };
     if (fieldList)
         out.fieldList = fieldList;

package/dist/src/core/titleCache.js

@@ -4,63 +4,65 @@ import path from "node:path";
 export const DEFAULT_TITLE_CACHE_PATH = path.join(os.homedir(), ".config", "gangtise", "title-cache.json");
 export const TITLE_LOOKUP_SIZE = 200;
 const TITLE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
-/**
- * Hard cap on titles kept per endpoint. The cache only needs the recent working
- * set so downloads can resolve friendly filenames; without a cap, `writeTitleCache`
- * merges forever and the endpoint's `ts` refreshes on every write, so the TTL
- * never expires it — the file grew to tens of MB in practice, and `resolveTitle`
- * re-parses the whole thing on every download. Bounds the file to roughly
- * (#cached endpoints × this × avg entry size).
- */
 export const MAX_TITLES_PER_ENDPOINT = 5_000;
-// Per-process in-memory snapshot of the cache. We read the file at most once,
-// merge subsequent writes in memory, and flush atomically. This avoids the
-// "read whole file → modify → write whole file" pattern firing on every list
-// command (which got expensive once dozens of endpoints accumulated).
 let memoryCache = null;
 let memoryCachePath = null;
 let pendingWrite = null;
+let pendingLoad = null;
+let pendingLoadPath = null;
 let dirty = false;
 async function loadInto(filePath) {
     if (memoryCache && memoryCachePath === filePath)
         return memoryCache;
+    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 {
+        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;
+    for (;;) {
+        if (!dirty || !memoryCache) {
+            pendingWrite = null;
+            return;
+        }
+        dirty = false;
+        const snapshot = JSON.stringify(memoryCache);
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        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;
+        }
     }
 }
-/**
- * Trim `merged` down to `cap` entries. The freshly-written ids (`freshKeys`) are
- * kept first since those are what the user just listed and is most likely to
- * download; remaining capacity is filled from the rest. Returns `merged` as-is
- * when already within the cap.
- */
 function capTitles(merged, freshKeys, cap) {
     if (Object.keys(merged).length <= cap)
         return merged;
@@ -75,8 +77,6 @@ function capTitles(merged, freshKeys, cap) {
         }
     }
     if (n < cap) {
-        // Newest-inserted keys sit at the END of the merged object — fill in reverse so
-        // eviction drops the oldest entries, not the batch the user just listed yesterday.
         const rest = Object.keys(merged);
         for (let i = rest.length - 1; i >= 0 && n < cap; i--) {
             const k = rest[i];
@@ -88,12 +88,6 @@ function capTitles(merged, freshKeys, cap) {
     }
     return out;
 }
-/**
- * Keep the cache bounded on every write: drop endpoint entries past their TTL
- * (lookups already ignore them) and cap each endpoint's titles. The just-written
- * endpoint keeps its newest ids first; others over the cap are trimmed too, so a
- * pre-existing oversized file shrinks on the next write.
- */
 function pruneCache(data, freshEndpoint, freshKeys) {
     const now = Date.now();
     for (const key of Object.keys(data)) {
@@ -117,15 +111,15 @@ export async function writeTitleCache(endpoint, titles, filePath = DEFAULT_TITLE
     data[endpoint] = { titles: { ...existing, ...titles }, ts: Date.now() };
     pruneCache(data, endpoint, Object.keys(titles));
     dirty = true;
-    // Coalesce concurrent writes: the in-flight flush picks up everything dirty.
     if (pendingWrite)
         return pendingWrite;
     pendingWrite = (async () => {
         try {
             await flush(filePath);
         }
-        finally {
+        catch (error) {
             pendingWrite = null;
+            throw error;
         }
     })();
     return pendingWrite;
@@ -151,10 +145,11 @@ export function extractTitles(items, cache) {
     }
     return titles;
 }
-/** Test-only hook to reset the in-memory snapshot between cases. */
 export function __resetTitleCacheForTests() {
     memoryCache = null;
     memoryCachePath = null;
     pendingWrite = null;
+    pendingLoad = null;
+    pendingLoadPath = null;
     dirty = false;
 }

package/dist/src/core/transport.js

@@ -1,25 +1,11 @@
 import { gunzipSync } from "node:zlib";
 import { Agent } from "undici";
 import { ApiError } from "./errors.js";
-/** Decode an HTTP response body honoring Content-Encoding. undici does not
- * auto-decompress, so requestJson advertises `accept-encoding: gzip` and gunzips
- * here; an unencoded body is read as-is. */
 export function decodeResponseBody(buf, contentEncoding) {
     const enc = (Array.isArray(contentEncoding) ? contentEncoding[0] : contentEncoding)?.toLowerCase().trim();
     const b = Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength);
     return enc === "gzip" ? gunzipSync(b).toString("utf8") : b.toString("utf8");
 }
-/**
- * Re-quote the *unquoted numeric* values of the named JSON fields so ids past
- * 2^53 survive JSON.parse: `{"taskId":1782345678901234567}` would otherwise come
- * back as 1782345678901234700 and address a task that does not exist.
- *
- * Probed 2026-07-25: file-parse's submit returns `taskId` as a STRING (matching
- * the spec), so this is a forward guard, not a live fix — but the failure mode it
- * covers is silent and expensive (the parse job is already billed, and a rounded
- * id can never fetch its result). Values already in quotes are left alone: the
- * pattern only matches a bare number right after the key.
- */
 export function quoteBigIntFields(text, fields) {
     if (!fields?.length)
         return text;
@@ -29,11 +15,7 @@ export function quoteBigIntFields(text, fields) {
     }
     return out;
 }
-/** A Retry-After delay we'll honor even if it exceeds maxDelay — but never past this
- * ceiling, so a hostile/misconfigured header can't hang the CLI for minutes. */
 const RETRY_AFTER_CEILING_MS = 60_000;
-/** Parse a Retry-After header (delta-seconds or an HTTP-date) into a delay in ms.
- * Returns undefined when absent or unparseable. `nowMs` is injected for testing. */
 export function parseRetryAfterMs(value, nowMs) {
     const raw = (Array.isArray(value) ? value[0] : value)?.trim();
     if (!raw)
@@ -43,8 +25,6 @@ export function parseRetryAfterMs(value, nowMs) {
     const dateMs = Date.parse(raw);
     return Number.isNaN(dateMs) ? undefined : Math.max(0, dateMs - nowMs);
 }
-/** A retryable error may carry a server-specified Retry-After (attached by the
- * client on a 429); prefer it over the computed backoff. */
 function retryAfterFromError(error) {
     if (error && typeof error === "object") {
         const v = error.retryAfterMs;
@@ -82,37 +62,17 @@ 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 = 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 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".
 const NO_REPLAY_NETWORK_CODES = new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT"]);
 function isRetryableError(error, policy) {
     if (error && typeof error === "object" && error.__retryable === true) {
@@ -146,9 +106,6 @@ 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");
 }
@@ -164,8 +121,6 @@ export async function withRetry(fn, options = {}) {
         catch (error) {
             if (attempt >= retries || !isRetryableError(error, options.policy ?? "default"))
                 throw error;
-            // A server-sent Retry-After (429) wins over exponential backoff, but is capped
-            // so it can't stall the CLI; otherwise fall back to jittered exponential backoff.
             const retryAfter = retryAfterFromError(error);
             const delay = retryAfter !== undefined
                 ? Math.min(retryAfter, RETRY_AFTER_CEILING_MS)

package/dist/src/version.js

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

package/gangtise-openapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gangtise-openapi
-version: "0.34.0"
+version: "0.35.0"
 description: |-
   通过 gangtise CLI 直接调用 Gangtise OpenAPI，拉取投研原始数据、批量导出、下载文件、调用 AI 能力。
 
@@ -265,7 +265,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 
 日期参数**按参数名判断、不按命令组**（命令组会误导——AI 里既有 `--start-time` 又有 `--date`/`--report-date`；Insight 里 `performance-calendar` 是唯一用 `--start-date`/`--end-date` 的 list）：名字带 `-date` 的（`--start-date`/`--end-date`/`--date`/`--report-date`）一律 `YYYY-MM-DD`，覆盖 Quote/Fundamental、`insight performance-calendar`、AI 的 `theme-tracking`(`--date`)/`hot-topic`/`management-discuss-*`(`--report-date`)、Alternative `edb-data`、Indicator `cross-section`(`--date`)/`time-series`；名字带 `-time` 的（`--start-time`/`--end-time`）用 `YYYY-MM-DD[ HH:mm[:ss]]`（秒可省、空格或 `T` 分隔）或 10/13 位时间戳，覆盖 Insight/Vault 各 list、`quote minute-kline`、`ai security-clue`、`ai knowledge-batch`。其中 **A 股公告（`insight announcement list`）与 `knowledge-batch` 会把输入转成 13 位毫秒**（10 位秒自动 ×1000），其余 `-time` 命令（含 `announcement-hk`/`announcement-us`）原样透传字符串；CLI 输入统一接受 10/13 位纯数字或 `YYYY-MM-DD[ HH:mm[:ss]]`（同上：秒可省、空格或 `T` 分隔）。
 
-支持排序切换的命令：opinion / summary / pamirs-summary / research / foreign-report / announcement / announcement-hk / announcement-us / foreign-opinion / independent-opinion / official-account。**要最新的加 `--rank-type 2`（严格按 `publishTime` 倒序）；要最相关的用默认 `--rank-type 1` + `--keyword` + `--search-type 2`（综合排序按相关度挑条目）**——两者从同一结果集里取的是**不同的子集**，不是同一批内容换个排法。⚠️ 综合排序**挑完之后仍按时间倒序排列**，所以别用「结果是不是时间倒序」判断它有没有生效，要比条目 ID。没有 `--keyword` 时两者无差异，属正常。详见 `insight.md` 开头。其他 list 命令按 API 默认排序。
+支持排序切换的命令：opinion / summary / pamirs-summary / research / foreign-report / announcement / announcement-hk / announcement-us / foreign-opinion / independent-opinion / official-account。**要最新的加 `--rank-type 2`（严格按 `publishTime` 倒序）；要最相关的用默认 `--rank-type 1` + `--keyword`（综合排序按相关度挑条目）**——两者从同一结果集里取的是**不同的子集**，不是同一批内容换个排法。🔴 **`--search-type` 不改变 `--rank-type 1` 取回哪些条目**（实测 19 组 0 反例，前 50 逐位相同，其中一组 `total` 从 1522 涨到 45257 仍逐位不变），**要相关度不必加 `--search-type 2`**；它扩大的是命中总数和 `--rank-type 2` 的候选池。🔴 **两档差别有多大取决于关键词，别拿一个词判断参数有没有用**：有些关键词下两档返回同一批，有些交集接近 0，判据见 `insight.md` 开头。⚠️ 综合排序**挑完之后仍按时间倒序排列**，所以别用「结果是不是时间倒序」判断它有没有生效，要比条目 ID。没有 `--keyword` 时两者无差异，属正常。详见 `insight.md` 开头。其他 list 命令按 API 默认排序。
 
 ## 异常处理
 

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

@@ -49,7 +49,20 @@ gangtise indicator cross-section --indicator <code> [--indicator <code2>] \
 - `--indicator`（**至少 1 个**）：指标编码，来自 `search`，可重复传多个
 - `--security`（**至少 1 个**）：证券代码，如 `600519.SH`（A股）/ `09992.HK`（港股）/ `AAPL.O`（美股，用 `.O`/`.N` 后缀，非 `.US`），可重复传多个。**也接受板块 ID**（`reference sector-search` 返回的 10 位 `sectorId`，如 `1000000287` 中信白酒 → 19 只成分股），代码与板块可混传，服务端取并集去重。⚠️ 中信行业码那类 9 位 ID（`100800109`）**不是** `sectorId`，传进去返 0 只
 - `--date`（**必选**）：数据日期 `yyyy-MM-dd`。**CLI 把它下发为每个指标各自的 `tradeDate`**（2026-08-01 起服务端取消了根级 date）。日期语义按指标分两类——财务报表指标=报告期末（可为非交易日，实测 `2024-03-31` 可取数）、`finc_pe_ttm` / `finc_pb_mrq` 等日频估值=交易日（详见下方「日期路由」）
-  - `--date` 必填是 CLI 的**护栏**，不是协议要求：`cross-section` 本身接受 `indicatorParamList: []`（无参指标如 `pty_op_scope` 照常返值，实测 2026-08-02）。但绝大多数指标吃 `tradeDate`，漏传就是一张空表且退出码 0，所以宁可多带一个无害参数。（`screener` 的 `--date` 也必填，同理）
+  - `--date` 必填是 CLI 的**护栏**，不是协议要求：`cross-section` 本身接受 `indicatorParamList: []`。但绝大多数指标吃 `tradeDate`，漏传就是一张空表且退出码 0，所以宁可多带一个。（`screener` 的 `--date` 也必填，同理）
+  - 🔴 **判据一句话：该指标的 `parameterList` 里有 `tradeDate` 就不用管；没有，`--date` 下发的 `tradeDate` 就可能被拒。** 按这条走，四种情形四种写法（`parameterList` 从 `indicator search --keyword <code> --format json` 读，别按 code 前缀推断）：
+
+    | `parameterList` | 怎么写 |
+    | :--- | :--- |
+    | 有 `tradeDate` | 什么都不用加，`--date` 即可 |
+    | 无 `tradeDate`、有 `reportDate`（`is_*` 等报告期类） | 加 `--indicator-param "<code>:reportDate=2024-12-31"`；CLI 检测到就不再注入 `tradeDate` |
+    | 无 `tradeDate`、有别的参数 | 传那些参数，**再加一条 `--indicator-param "<code>:"`**（冒号后留空 = 不要日期）。如 `div_cash_paid_ratio` / `div_cash_yr` 要 `fiscalYear`、`pty_shr_reg`(注册资本) 只有 `currency`/`scale` |
+    | 无 `tradeDate`、`parameterList` 为空 | 只加 `--indicator-param "<code>:"` |
+
+    - **空冒号那条与真实参数可以共存**：`"div_cash_yr:" "div_cash_yr:fiscalYear=2025"` 两条一起给，前者只关掉日期注入，不会把 `fiscalYear` 清掉
+    - **哪些指标属于后两种**：已知是 `pty_*`（公司属性：注册地址 / 法定代表人 / 经营范围 / 公司简介…）与 `scr_*`（证券属性：证券简称 / ISIN / 上市市场 / 上市板块 / 上市日期…）两族，加上 `div_cash_paid_ratio` / `div_cash_yr` / `pty_shr_reg`。🔴 **这只是当前已知的快照，不是完整清单**——`indicator search` 必须给关键词、`--limit` 上限 100 且没有翻页，所以指标库无法整体枚举。**永远以 `parameterList` 为准**；要重新生成某一族用 `indicator search --keyword <前缀>_ --limit 100`，返回条数小于 100 即该族已列全
+    - ⚠️ **别把「有 `fiscalYear`」当成「不要 `tradeDate`」**——`frcst_pe` / `frcst_shnp` / `frcst_op_rev` 等预测类指标 `parameterList` 里**两个都是必填**，照常用 `--date` 再加一条 `fiscalYear`，**不要**加空冒号那条
+    - ⚠️ **也别把「有 `reportDate`」当成「不受影响」**——报告期类指标同样拒收注入的 `tradeDate`，只是解法（自己传 `reportDate`）刚好顺带关掉了注入
   - 🔴 **吃 `reportDate` 的指标必须显式传 `reportDate`**：`--indicator-param "code:reportDate=2024-12-31"`。**2026-08-15 起服务端不再接受 `tradeDate`**——只给 `--date` 会报 `100003「指标 xxx 不支持参数 tradeDate; 指标 xxx 缺少必填参数 reportDate」`（此前一版会把 `tradeDate` 归一到所在报告期，现已改为报错）。哪些指标属于这一类看 `indicator search` 的 `parameterList`：`reportDate` 标 `required: true` 且列表里没有 `tradeDate` 的就是。利润表 / 资产负债表 / 现金流量表类（`is_*` 等）都在此列；行情与估值类（`qte_*` / `finc_*`）仍用 `--date` 即可。CLI 检测到你已为某指标传了 `tradeDate` 或 `reportDate` 就不再注入 `--date`，所以补上 `--indicator-param` 就能正常取数
   - `sDate`（区间起始日）**不算**替代日期：它和 `tradeDate` 共存（`tradeDate` 是区间终点且 required），传了 `sDate` 后 `--date` 照常下发
 - `--currency`：币种 `DFT`(原始,默认)/`CNY`/`HKD`/`USD`/`EUR`/`GBP`/`JPY`/`TWD`/`MOP`/`AUD`（**大写**，2026-08-01 起服务端枚举已统一大写）
@@ -110,7 +123,8 @@ gangtise indicator screener --indicator <F1:code> [--indicator <F2:code2>] \
   - 比较：`==` `>` `<` `>=` `<=` `!=`
   - 文本：`contains` / `notcontains`（不区分大小写，**仅对 `dataType: string` 的指标有效**）
   - 逻辑：`&&` `||`，分组 `(` `)`
-- `--date`（**必选**）：下发为**每个**指标的 `tradeDate`（已带 `tradeDate`/`reportDate` 的不覆盖）。绝大多数指标吃 `tradeDate`，漏传就是一张空表且退出码 0，所以必填。对无参指标（如 `pty_op_scope`）多挂一个 `tradeDate` 无害，因此不做例外
+- `--date`（**必选**）：下发为**每个**指标的 `tradeDate`（已带 `tradeDate`/`reportDate` 的不覆盖）。绝大多数指标吃 `tradeDate`，漏传就是一张空表且退出码 0，所以必填
+- 🔴 **`parameterList` 里一个日期参数都没有的指标（`pty_*` / `scr_*` 静态属性两族、`div_cash_paid_ratio` / `div_cash_yr`、`pty_shr_reg`），`screener` 上当前取不到**：带 `tradeDate` 会被拒（`100003`）；不带则该指标不进结果，**筛选条件等于没加、返回 0 行且不报错**——这一档最危险，看起来像「没有标的符合条件」。CLI 因此在 `screener` 上拦下 `--indicator-param "F1:"` 写法并说明原因（同样的写法在 `cross-section` 上可用）。**替代做法**：用 `indicator cross-section` 把这几列取回来，在本地筛。注意这只影响**没有任何日期参数**的指标，报告期类（`is_*` 等）在 `screener` 上给 `F1:reportDate=...` 照常可用
 - `--indicator-param`：格式是 **`F1:key=value`（按变量，不是按 code）**。引用了没绑定的变量会直接报错，不会静默丢弃
 - `--expression` 里引用未绑定的变量，CLI **本地就拦**（不发请求、不计费）；服务端也会报 `100003`
 - **输出（宽表）**：同 `cross-section`，每行一只**命中**的证券，列为 `security / name / <各指标名>…`；无命中返回空表
@@ -134,9 +148,14 @@ gangtise indicator screener --indicator F1:qte_close --indicator F2:qte_close \
 
 ```bash
 # 文本筛选：白酒板块里经营范围含「酒」的公司
-gangtise indicator screener --indicator F1:pty_op_scope \
-  --security 1000000287 --expression "F1 contains '酒'" \
-  --date 2026-07-31 --format table   # 19 只全部命中
+# ⚠️ pty_op_scope 的 parameterList 为空，属于上面说的「screener 当前取不到」那一类，改走 cross-section 本地筛：
+gangtise indicator cross-section --indicator pty_op_scope \
+  --indicator-param "pty_op_scope:" \
+  --security 1000000287 --date 2026-08-13 --format jsonl | grep 酒
+# screener 上可用的文本筛选换成有日期参数的字符串指标，例如：
+gangtise indicator screener --indicator F1:mgn_flag \
+  --security 1000000287 --expression "F1 contains '是'" \
+  --date 2026-08-13 --format table   # 融资融券标的
 ```
 
 ```bash

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

@@ -6,16 +6,37 @@
 
 支持 `--rank-type` 的命令：opinion / summary / **pamirs-summary** / research / foreign-report / announcement / announcement-hk / announcement-us / foreign-opinion / independent-opinion / official-account。
 
-⚠️ **`--rank-type` 的效果依赖 `--keyword`**：没有关键词时综合排序无从计算，两种取值结果一致，这不是参数失效。
-
-**`--rank-type 1`（综合排序，默认）按相关度挑选条目**，`--rank-type 2` 严格按 `publishTime` 倒序取最新的。两者从同一结果集里取的是**不同的子集**，不是同一批内容换个排法：
+**`--rank-type 1`（默认）按相关度挑条目，`--rank-type 2` 严格按 `publishTime` 倒序取最新的。** 两者从同一结果集里取的是**不同的子集**，不是同一批内容换个排法。
 
 | 想要 | 用 |
 | :--- | :--- |
-| 最相关的内容（可以是旧的） | `--rank-type 1` + `--keyword` + `--search-type 2`（全文） |
+| 最相关的内容（可以是旧的） | `--rank-type 1` + `--keyword` |
 | 最新的内容（按时间铺） | `--rank-type 2` |
 
-同一个查询下，`--rank-type 1` 取回的条目时间跨度更宽（每天只挑相关度高的几条），`--rank-type 2` 则集中在最近几天（把最新的逐条铺出来）。
+🔴 **两档差别有多大取决于关键词，别拿一个关键词去判断这个参数有没有用**。同一天、同一命令实测（前 50 条比条目 ID）：
+
+| 关键词 | `research` 两档交集 | `summary` 两档交集 |
+| :--- | ---: | ---: |
+| `机器人` / `PCB` | 50/50（**完全相同**） | 50/50 |
+| `固态电池` / `半导体设备` | 50/50 | 50/50 |
+| `人形机器人` | 9/50 | 15/50 |
+| `新能源汽车` | 2/50 | 0/50 |
+
+**判据不是「词够不够具体」**（`固态电池` / `半导体设备` 都很具体，却毫无差别），而是**看 `total` 与组成词的关系**——用 `--size 1` 各查一次即可，免费：
+
+| 关键词 | `total` | 与组成词比 | 两档 |
+| :--- | --: | :--- | --: |
+| `新能源汽车` | 79059 | **大于**「新能源」42406 与「汽车」48474 单独查 → 近似并集 | 差别大 |
+| `人形机器人` | 12165 | ≈ 最大组成词「机器人」12164 → 也是拆词 | 差别大 |
+| `固态电池` | 1156 | **小于**「固态」1541 与「电池」12569 → 近似交集 | 无差别 |
+
+`total` 比组成词大（服务端把词拆开按 OR 找）时，候选里既有整词命中也有只中一半的，相关度拉得开，两档取的自然是不同的批；`total` 比组成词小（按整个短语找）时全是真命中、相关度并列，两档就是同一批。**这属正常，不是参数没生效**。
+
+`新能源汽车` 那组里 `--rank-type 1` 前 50 有 47 条标题含「新能源」、22 条含完整词「新能源汽车」，`--rank-type 2` 分别是 28 条和 **0 条**——**综合排序确实在按相关度挑**。
+
+⚠️ **`--search-type` 不影响 `--rank-type 1` 取回哪些条目**：实测多组「命令 × 关键词」组合无一例外：`--search-type 1` 与 `2` 下 `--rank-type 1` 的前 50 条**逐位相同**，其中一组 `total` 从 1522 涨到 45257（近 30 倍）仍逐位不变。`--search-type 2`（全文）扩大的是命中总数和 `--rank-type 2` 的候选池。**所以「要最相关」不需要加 `--search-type 2`。**
+
+⚠️ **没有 `--keyword` 时两档结果一致**，这不是参数失效——没有关键词就无从计算相关度。
 
 ⚠️ **别用「返回结果是不是按时间倒序」判断综合排序有没有生效** —— `--rank-type 1` **挑完之后仍按时间倒序排列**，所以两种取值下返回序列都是时间单调的。要看差别就**比条目 ID 集合**，不是比排序。
 **不支持** `--rank-type` 的命令：roadshow / site-visit / strategy / forum（API 无此参数）。

package/gangtise-openapi/references/examples.md

@@ -271,7 +271,8 @@
      gangtise insight pamirs-summary list --keyword PCB --search-type 2 --rank-type 1 \
        --size 20 --format json
    - --search-type 2 = 全文（标题搜索是 1，命中少很多：PCB 标题 36 / 全文 113）
-   - --rank-type 1 只在「有 keyword + 全文」时才是真正的相关度排序；要最新就用 2
+   - --rank-type 1 在有 keyword 时按相关度挑条目；要最新就用 2。差别多大取决于关键词本身，
+     --search-type 不影响 rank-type 1 挑哪些条目（这里加 2 是为了扩大命中面，不是为了排序）
    - 筛选项比 summary 少：没有 --source / --institution / --participant-role
 3. 🔴 别拉全量再本地按类别/市场分组——服务端只在你用该字段过滤时才回填标签：
    不带 --category 查，categoryList 100% 是空数组；conceptList 任何查法都是空。

package/package.json

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