gangtise-openapi-cli 0.34.1 → 0.36.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,40 +4,16 @@ 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;
-/** 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 () => {
@@ -58,7 +34,6 @@ async function loadInto(filePath) {
         return await load;
     }
     finally {
-        // Only clear if still ours — a load for another path may have replaced it.
         if (pendingLoad === load) {
             pendingLoad = null;
             pendingLoadPath = null;
@@ -69,14 +44,7 @@ export async function readTitleCache(filePath = DEFAULT_TITLE_CACHE_PATH) {
     return loadInto(filePath);
 }
 async function flush(filePath) {
-    // 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;
@@ -84,7 +52,6 @@ async function flush(filePath) {
         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 {
@@ -96,12 +63,6 @@ async function flush(filePath) {
         }
     }
 }
-/**
- * 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;
@@ -116,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];
@@ -129,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)) {
@@ -158,16 +111,6 @@ 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.
-    //
-    // `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 () => {
@@ -175,16 +118,6 @@ export async function writeTitleCache(endpoint, titles, filePath = DEFAULT_TITLE
             await flush(filePath);
         }
         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;
         }
@@ -212,14 +145,10 @@ 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;
-    // 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/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.1";
+export const CLI_VERSION = "0.36.0";

package/gangtise-openapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gangtise-openapi
-version: "0.34.1"
+version: "0.36.0"
 description: |-
   通过 gangtise CLI 直接调用 Gangtise OpenAPI，拉取投研原始数据、批量导出、下载文件、调用 AI 能力。
 
@@ -24,7 +24,7 @@ description: |-
 1. **`--format json`**：列表/数据类必加。AI 内容生成（`one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `*-check`）也加 json，但呈现时**直接取 `content` 字段**，不要展示 JSON 包装层。
 2. **opaque ID**：先读 `references/lookup-ids.md`；找不到再按类型查：行业/区域/公告分类/城市 → `reference constant-list --category <分类>`（分类代码用 `reference constant-category` 查）；题材 → `reference concept-search --keyword <名>`；板块 → `reference sector-search --keyword <名>`；申万 `--gts-code` 行业代码全量 → `sector-search --keyword 申万一级行业指数` 取指数数据板块层级的 sectorId 再 `sector-constituents`；券商/牵头/观点机构（按名称找 ID）→ `reference institution-search --keyword <名> [--category ...]`（服务端搜索，返回 `institutionId` + `usageScopes` 标明该 ID 用于哪个接口的哪个参数；覆盖 `--broker` / `--institution` 全部 5 类机构，含 `foreignOpinionInstitution`）——仅当要**全量枚举**时才用本地表 `gangtise lookup broker-org/meeting-org list`（institution-search 是搜索型：top≤10、非全量）。**绝不猜测**。
 3. **公司名 → 证券代码**：先查下方速查表（5 只 mega-cap），其余一律 `gangtise reference securities-search --keyword <名> --category stock` 取 `list[0].gtsCode`。
-4. **时间格式**：datetime `"YYYY-MM-DD HH:mm:ss"`（引号包裹），date `YYYY-MM-DD`。
+4. **时间格式**：datetime `"YYYY-MM-DD HH:mm:ss"`（引号包裹），date `YYYY-MM-DD`（`YYYY/MM/DD`、`YYYYMMDD` 也收，会归一；**年在后写法一律拒绝**）。
 5. **多值参数**：优先重复传（最稳、最明确）：`--security 600519.SH --security 000858.SZ`。CLI 也支持半/全角逗号分隔（`args.ts` 为语音输入容错），但重复传不易被 shell 吞。
 6. **K 线"最近 N 条"**：必须用 `--start-date`/`--end-date` 拉日期范围，从结果按 `tradeDate` 取尾部最近 N 条。**不要只用 `--limit N`**（截取的是窗口开头）。
 6.1. **日 K 仅历史**：`day-kline` **不返回盘中实时数据**。当日数据入库时间：A 股 ~15:30 / 港股 ~16:30 / 美股 ~07:00（北京时间）。需要盘中快照请走 `quote realtime`。
@@ -74,9 +74,12 @@ description: |-
 - **按条（观点/含详情类 list）**：independent-opinion list 与 `ai security-clue` 5；roadshow/site-visit/strategy/forum list 20；opinion / foreign-opinion list 30；`fundamental earning-forecast` 0.5；`ai stock-summary` 3（无看点的证券不返回也不扣）；`alternative edb-data` 30
 - **各 download（/篇）**：announcement / official-account / research 10；announcement-hk / announcement-us 20；independent-opinion 30；summary / foreign-report / my-conference 50；`performance-calendar download` A 股 10 / 港美股 20
 - **按页**：`tool file-parse` 0.8/页，**提交（`--file`）时按实际页数一次性扣**，取结果（`file-parse-check`）免费——50 页 PDF = 40 积分，别重复提交同一文件
-- 🔴 **按次贵**：`ai knowledge-batch` 10、`management-discuss-*` 10；AI Agent（`one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `earnings-review` / `viewpoint-debate` / `theme-tracking`）**50/次**；`ai hot-topic` 50/篇
+- 🔴 **按次贵**：`ai knowledge-batch` 10、`management-discuss-*` 10；AI Agent（`one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `earnings-review` / `viewpoint-debate` / `theme-tracking`）**50/次**
+- 🔴 **`ai hot-topic` 50/篇，按返回条数计**（不是按调用次数）。📌 **一「篇」= 一整份报告**（一份早报 / 午报 / 盘中快报 / 晚报），**不是报告里的一条话题**——一份报告通常包含多条热点话题。所以 `--size 20` 的一页 = 最多 20 份报告 = 1000 积分，**先用 `--start-date`/`--end-date` + `--category` 收窄再拉**，别省略 `--size` 直接全量。**可查的历史范围跟账号权限走**（试用档是滚动的「当前 −1 个月」，正式/定制档更长）——超出范围的日期返回空结果而不是报错，拿到空先想想是不是撞了权限窗口
 - 🔴 **极贵**：`alternative concept-info` / `concept-securities` **500/次**
-- ⚠️ **同参数重复调用不免费**：按次计费无缓存命中豁免（2026-07-11 实测 `one-pager` 重复调用每次扣分，即使秒回缓存内容）——生成类结果拿到后自行留存复用，别为"刷新"重调；CLI 已对上述 🔴 贵档端点关闭 5xx/超时自动重放，50/篇 的 `summary` / `foreign-report` / `my-conference` download、单价未公布但保守同档处理的 `pamirs-summary` download、以及 `tool file-parse` 的提交，同样不重放（共 18 个端点），正是为防重复扣分
+- ✅ **按篇 / 按条计费的接口，没查到内容就不扣分**（空结果 = 0 积分）：各 download（`pamirs-summary` 除外，见 ②）、`ai hot-topic`（50/篇）、`ai stock-summary`（3/条，无看点总结的个股不进返回列表也不计费）。**所以「先小范围试探再放大」是安全的**——先用窄条件确认能查到东西，再扩范围。⚠️ **两类不适用**：① **按次计费的**——`ai knowledge-batch` / `management-discuss-*`、AI Agent 那批 50/次、`alternative concept-info` / `concept-securities` 500/次，不管有没有内容都扣，超时报错也可能已经扣过；② **单价未公布的**——`pamirs-summary`（见下），别据此假定
+- ⚠️ **同参数重复调用不免费**：按次计费的那批无缓存命中豁免（2026-07-11 实测 `one-pager` 重复调用每次扣分，即使秒回缓存内容）；**按篇/按条的也一样**——重拉同一批 `hot-topic` 就是按条数再计一次费。生成类与列表结果拿到后自行留存复用，别为「刷新」重调
+- ⚠️ **贵档端点超时/5xx 不自动重放**（共 18 个：AI Agent 那批 + `ai knowledge-batch` / `management-discuss-*` / `hot-topic`、`alternative concept-info`·`concept-securities`、50/篇 的 `summary`·`foreign-report`·`my-conference` download 与同档处理的 `pamirs-summary` download、`tool file-parse` 提交）。**理由是重放会重复扣分**——服务端可能已经执行并计费，重发按次计费的会再扣一次，重发按篇/按条计费的会把**已交付的行**再计一次；两种都亏。仅连接失败、429 与 token 自愈会重试
 - **按单元格**：`indicator cross-section` / `time-series` / `screener`（A股 0.05 / 港股 0.1 / 美股 0.2 积分每 100 单元格；screener 按**筛选前**范围计费，见 `indicator.md`）；`ai knowledge-resource-download` 按下游资源计费
 - **单价未公布**：`insight pamirs-summary list` / `download`——spec 只写了「需购买专家纪要数据库」这个准入门槛，没给单次价格。**别据此假定免费**；大批量拉取前先小量试，或向平台确认
 
@@ -263,9 +266,9 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 | 最新一期 / 最新报告期（财报） | — | — | 省略 `--fiscal-year`，传 `--period latest`（默认） |
 | 最新观点 / 今日观点 | 1 天范围 + `--rank-type 2` | — | — |
 
-日期参数**按参数名判断、不按命令组**（命令组会误导——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` 分隔）。
+日期参数**按参数名判断、不按命令组**（命令组会误导——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` 首选，`YYYY/MM/DD`/`YYYYMMDD` 也收），覆盖 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`）用年在前日期 + `[ 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` 取回哪些条目**（同一关键词下，两档的 `--rank-type 1` 结果相同——即使 `--search-type 2` 让 `total` 大出一个数量级），**要相关度不必加 `--search-type 2`**；它扩大的是命中总数和 `--rank-type 2` 的候选池。🔴 **两档差别有多大取决于关键词，别拿一个词判断参数有没有用**：有些关键词下两档返回同一批，有些交集接近 0，判据见 `insight.md` 开头。⚠️ 综合排序**挑完之后仍按时间倒序排列**，所以别用「结果是不是时间倒序」判断它有没有生效，要比条目 ID。没有 `--keyword` 时两者无差异，属正常。详见 `insight.md` 开头。其他 list 命令按 API 默认排序。
 
 ## 异常处理
 
@@ -305,7 +308,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 | ✅ `140002` | 终态参数错：AI 异步生成失败，或 `indicator` 的指标必填参数缺失 / 枚举越界 / 表达式语法错（实测 2026-08-02） | **不重试**（终态码） | 按 msg 改参数重提；EDE 的参数名与枚举读 `indicator search --format json` 的 `parameterList` |
 
 **⚠️ 几类"不报错"的坑（最难发现，逐条都关系到拿没拿到对的数）**
-- **日期只写 `YYYY-MM-DD`、时间只写 `YYYY-MM-DD HH:mm:ss`（或 10/13 位时间戳）**。CLI v0.28.0 起 date 与 datetime 两类（含所有 insight/vault 透传参数）都在发请求前校验，其余写法直接报 `ValidationError`。接口本身能接受多种格式，但**「年在后」写法（`01-07-2026`）存在月/日歧义**——会按月在前读作 1 月 7 日，本意写 7 月 1 日的就拿到差半年的数据且不报错。**CLI 只放行 `YYYY-MM-DD` 就是为了堵掉这个歧义，这是有意的**；绕过 CLI 直连接口时务必自己用标准格式
+- **日期用「年在前」写法**：`YYYY-MM-DD`（首选）、`YYYY/MM/DD`、`YYYYMMDD` 三种 CLI 都收，并**统一归一成 `YYYY-MM-DD` 再发出**；时间加 `[ HH:mm[:ss]]`（秒可省、空格或 `T` 分隔）或用 10/13 位时间戳。🔴 **「年在后」写法（`01-07-2026`、`07/01/2026`）CLI 直接报 `ValidationError`，这是有意的**——接口本身会解析它，且**一律按美式「月在前」**（`01-07-2026` = 1 月 7 日，`07-01-2026` = 7 月 1 日）。按欧洲/国际习惯写 `01-07-2026` 想表达「7 月 1 日」的，会拿到差半年的数据且**不报错**；本地拒掉才有信号，还省一次请求与计费。绕过 CLI 直连接口时务必自己统一用 `YYYY-MM-DD`
 - **财报接口的日期按「报告期末」过滤**，不是公告日：`fundamental balance-sheet` 等的 `--start-date`/`--end-date` 匹配的是 `endDate` 字段（如 `20200630`）；公告日看 `earliestAnncDate`（首次公告日，做时点对齐用这个）而不是 `announcementDate`。**查某期财报要传季度末日期**（`2020-06-30` / `2020-03-31` / `2020-09-30` / `2020-12-31`）；传 `2020-07-01` 这类非报告期日期会返回 0 行，属正常行为，不是没数据
 - **非法证券代码**：`quote day-kline` / `realtime` / `minute-kline` / `fund-flow` 与 Fundamental 系都会报 `120001`，按报错核对后缀即可。⚠️ **三个已下线的旧端点 `quote day-kline-hk` / `day-kline-us` / `index-day-kline` 则返回 `total:0`**，与"该票该区间真无数据"无法区分——**用这三个拿到空结果时先回头核对代码后缀**。它们的能力已并入统一 `day-kline`（支持 A 股 / 港股 / 美股 / 交易所指数 / 概念指数 `.GT` / 申万行业指数 `.SWI`），新代码直接用 `day-kline`
 - **枚举值拼错的后果按端点不同，且部分端点不报错**：纪要 `summary`、三个公告 list、路演 `roadshow`、调研 `site-visit` 的 `--search-type` / `--rank-type` / `--category` / `--market` 等传非法值会报 `100005`；而 `insight research`（内资研报）、`foreign-report`（外资研报）、`official-account`、`opinion` 上非法值被**静默忽略**，该筛选按未传处理。🔴 **最坏的一种**：`research` / `foreign-report` 上非法的 `--search-type` 会**连带吞掉 `--keyword`**——`research list --keyword 茅台 --search-type 99` 拿到的是**未经筛选的全库**，与不传 `--keyword` 的结果一致，而不是搜索结果。**v0.32.0 起 CLI 本地拦截**：全部 `--search-type` / `--rank-type`（19 处）、全部 `--file-type`（9 处下载，`foreign-report` 为 1–4、其余 1–2）、`pamirs-summary` 的 `--category` / `--market`、`--top` 上限、以及 `reference securities-search` / `institution-search` / `official-account-search` 的 `--category`。**仍未覆盖**：`insight research/summary --category`、`--market`、`--source`、`--llm-tag` 等仍是自由字符串，拼错不报错也不生效——这些要自己核对。**拼错的筛选条件会伪装成"结果正常"，枚举拼写要自己保证**

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

@@ -2,7 +2,7 @@
 
 注意：`ai one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `viewpoint-debate-check` / `earnings-review-check` 返回 `{content: "markdown文本"}`；这类命令仍然加 `--format json`，但呈现给用户时直接取 `content` 字段，不要展示 JSON 包装层。
 
-**⏱ 超时与重复扣分**：7 个 agent 类（`one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `theme-tracking` / `management-discuss-*`）CLI 已内置 120s 超时下限，**无需前缀**；`stock-summary` / `hot-topic` 首次生成也常 >30s，仍建议前置 `GANGTISE_TIMEOUT_MS=120000`。自 v0.26.0 起**贵档端点超时/5xx 不再自动重试**（重放=重复扣分）——超时报错后内容可能已在服务端生成并扣费，同参数再调会**再扣一次**（实测按次计费、无缓存命中豁免），所以一次调用给足超时比失败重跑省钱；拿到的生成内容自行留存复用，别为"刷新"重调。`earnings-review` / `viewpoint-debate` 是异步——用 `--wait`（工具超时 ≥360s）或 `*-check` 轮询，不吃这个超时。
+**⏱ 超时与重复扣分**：7 个 agent 类（`one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `theme-tracking` / `management-discuss-*`）CLI 已内置 120s 超时下限，**无需前缀**；`stock-summary` / `hot-topic` 首次生成也常 >30s，仍建议前置 `GANGTISE_TIMEOUT_MS=120000`。自 v0.26.0 起**贵档端点超时/5xx 不再自动重试**（重放=重复扣分）——超时报错后内容可能已在服务端生成并扣费，同参数再调会**再扣一次**（`one-pager` 等生成类实测按次计费、无缓存命中豁免），所以一次调用给足超时比失败重跑省钱；拿到的生成内容自行留存复用，别为"刷新"重调。`earnings-review` / `viewpoint-debate` 是异步——用 `--wait`（工具超时 ≥360s）或 `*-check` 轮询，不吃这个超时。
 
 ---
 
@@ -126,6 +126,8 @@ gangtise ai hot-topic [--start-date <date>] [--end-date <date>] [--category <nam
 - `--category`：`morningBriefing` 早报 | `noonBriefing` 午报 | `afternoonFlash` 盘中快报 | `eveningBriefing` 晚报（可重复，默认全部）
 - `--with-related-securities` / `--with-close-reading`：默认开启；`--no-with-related-securities` / `--no-with-close-reading` 显式排除（响应里相应字段置空）
 - 自动翻页，单页最大 20
+- 🔴 **计费 50/篇，按返回条数计**（不是按调用次数）。📌 **一「篇」= 一整份报告**（一份早报 / 午报 / 盘中快报 / 晚报），**不是报告里的一条话题**——一份报告通常包含多条热点话题，`--category` 选的也是报告类型而不是话题。所以一页 20 条 = 20 份报告 = 1000 积分：**先用 `--start-date`/`--end-date` + `--category` 把范围收窄，再考虑要不要全量**（省略 `--size` 即拉全量）
+- **可查的历史范围跟账号权限走**：试用档是滚动的「当前 −1 个月」，正式/定制档更长。超出范围的日期**返回空结果、不报错**——拿到空先确认是不是撞了本账号的窗口，别当成「那天没有报告」
 
 ## 管理层讨论-财报 `ai management-discuss-announcement`
 

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`）必须显式声明「不要日期」**：写 `--indicator-param "F1:"`（冒号后什么都不写）。不写的话 `--date` 会给它注入 `tradeDate`，而这些指标不接受该参数，**整条请求**报 `100003 指标 xxx 不支持参数 tradeDate`。`F1:` 与真参数可组合，`div_cash_*` 要同时给 `F1:` 和 `F1:fiscalYear=2025`。这与 `cross-section` 的 `"code:"` 是同一个写法。注意只有**没有任何日期参数**的指标需要，报告期类（`is_*` 等）给 `F1:reportDate=...` 即可
 - `--indicator-param`：格式是 **`F1:key=value`（按变量，不是按 code）**。引用了没绑定的变量会直接报错，不会静默丢弃
 - `--expression` 里引用未绑定的变量，CLI **本地就拦**（不发请求、不计费）；服务端也会报 `100003`
 - **输出（宽表）**：同 `cross-section`，每行一只**命中**的证券，列为 `security / name / <各指标名>…`；无命中返回空表
@@ -134,9 +148,15 @@ gangtise indicator screener --indicator F1:qte_close --indicator F2:qte_close \
 
 ```bash
 # 文本筛选：白酒板块里经营范围含「酒」的公司
+# ⚠️ pty_op_scope 的 parameterList 为空 → 必须带 "F1:" 声明它不吃日期，否则整条请求报 100003
 gangtise indicator screener --indicator F1:pty_op_scope \
+  --indicator-param "F1:" \
   --security 1000000287 --expression "F1 contains '酒'" \
-  --date 2026-07-31 --format table   # 19 只全部命中
+  --date 2026-08-13 --format table
+# 有日期参数的字符串指标不需要 "F1:"，直接筛：
+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` 结果相同——即使 `--search-type 2` 把 `total` 放大一个数量级，取回的条目仍是同一批。`--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.1",
+  "version": "0.36.0",
   "description": "CLI for Gangtise OpenAPI",
   "license": "MIT",
   "repository": {