gangtise-openapi-cli 0.35.0 → 0.37.0

package/gangtise-openapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gangtise-openapi
-version: "0.35.0"
+version: "0.37.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`。
@@ -38,7 +38,7 @@ description: |-
 8. **参数命名差异**：Insight/Quote/Vault 用 `--security`，Fundamental/AI 用 `--security-code`（例外：`ai stock-summary` 用 `--security`，`ai security-clue` 用 `--gts-code`）。
 9. **调试**：`--verbose` 或 `GANGTISE_VERBOSE=1` 打印每个请求的耗时/字节数到 stderr。
 10. **`--field` 字段名必须核对，不确定就别传**（返回全量最稳）：`quote realtime` / `fundamental main-business` / `valuation-analysis` 遇到不存在的字段名时，上游只丢**值**、字段名照请求**回显**，按位置拍平会把值贴到错误的字段上（实测 realtime 传 `close`——它没有这个字段——换手率 28.5573 被贴成 `close`，茅台真实价 1297.41）。v0.28.3 起 CLI 检测到长度不匹配直接报错（退出码 1）：**带 `--field` 的命令看到这个报错，先去 `references/fields.md` 核对字段名**（没有 `--field` 的命令如 `alternative edb-data` 报此错则是上游响应结构异常，报障时若报错末尾附了 `（trace …）` 就一并带上）。另：realtime **无 `close`**（用 `latestPrice`）、**无市值**（总市值走 `indicator cross-section --indicator qte_mkt_cptl`，2026-08-03 起 A/港/美股均有数）。
-11. 🔴 **EDE 取不到数时给的是占位值，而 `0` 和 `null` 都可能**（`indicator` 截面 / 时序 / 选股）：多数指标填 `null`，但个别——最常用的是 `is_dnrpnp` 扣非归母净利润——填 **`0`**，且这是**指标属性、与日期对不对无关**（日期落在报告期末时，覆盖不到的证券如美股同样返 `0`，行还在、无告警、退出码 0）。**`null` 通常被聚合跳过，`0` 会照常穿过比较与比率计算**：`screener` 的 `F1 > 0` 可能筛出空集（读起来像「没有盈利的股票」），时序整列求均值可能差几十倍。所以：报告期类指标的日期一律落**报告期末**；拿 `is_dnrpnp` 这类做筛选或聚合前先单查确认不是占位；**别对时序整列直接求均值 / 求和**。详见 `references/commands/indicator.md`。
+11. 🔴 **EDE 取不到数时返 `null` 占位，行列都保留**（`indicator` 截面 / 时序 / 选股），无告警、退出码 0。**报告期类指标（`is_*`）的时序尤其要当心**：按日返回，**只有报告期末那几行是真值**——茅台 `is_dnrpnp` 查 5 个月共 104 行，只有 2 行有数，其余全是 `null`，而时序没有任何参数能只返回报告期末。`null` 会被 Excel / pandas / SQL 的聚合跳过（**但 `jq` 不跳过**——`add/length` 会把 `null` 计入分母，得到偏低几十倍的值，要先 `map(select(. != null))`），且**行数不会变**，手工「总和 ÷ 行数」同样会差几十倍。截面上日期不落在报告期末时整批返 `null`，`screener` 会筛出空集——**那是日期用错了，不是「没有符合条件的标的」**。所以：报告期类指标的日期一律落**报告期末**（`03-31` / `06-30` / `09-30` / `12-31`），截面用 `--indicator-param "F1:reportDate=..."` 显式给；**别对时序整列直接求均值 / 求和**。详见 `references/commands/indicator.md`。
 
 ## 工作流（3 步）
 
@@ -52,7 +52,7 @@ description: |-
 - `gangtise auth status` 未登录 → 提示配置 AK/SK 并中止
 - 多个命令同时匹配 → 复述理解让用户挑（如"搜索研报" → research list 还是 knowledge-batch？）
 - 用户说"全部 / 全量 / 全市场" → 确认量级再拉：省略 `--size` 就是拉全量（自动翻页，上限 1000 页）；先 `--size 1` 看 stderr 的 `Total: N` 再决定（探量这步别加 `--format json`——json 下不打 `Total` 行）；全市场/跨一年分片等大批量可 `GANGTISE_PAGE_CONCURRENCY=10` 提速（默认 5，同时管翻页与 K 线分片）
-- **高积分操作先确认**：任何 50 积分/次及以上、或"按条 × 大批量"（如 `stock-summary` 全市场数千只、`opinion` 全量翻页、`concept-info` 500/次）→ 先估总积分告知用户再执行（单价见下「积分计费速查」）
+- **高积分操作先确认**：任何 50 积分/次及以上、或"按条 × 大批量"（如 `stock-summary` 按代码批量数千只、`opinion` 全量翻页、`concept-info` 500/次）→ 先估总积分告知用户再执行（单价见下「积分计费速查」）
 - 下载**必选**格式未定才问：`independent-opinion --file-type`（必选）、`vault record/my-conference --content-type`（record 三种 original/asr/summary、my-conference 两种 asr/summary）；其余 download 有默认（多为 `1`=PDF/原始），用户没提格式就用默认、不必问
 - list→download 用户没指定具体文件 → 展示前 10 条让用户挑
 
@@ -74,9 +74,34 @@ 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 自愈会重试
+
+<!-- no-replay-endpoints
+     上面那句点名的「不重放」端点，完整清单如下（endpoint key，与 `gangtise raw list` 一致）：
+ai.earnings-review.get-id
+ai.hot-topic
+ai.investment-logic
+ai.knowledge-batch
+ai.management-discuss-announcement
+ai.management-discuss-earnings-call
+ai.one-pager
+ai.peer-comparison
+ai.research-outline
+ai.theme-tracking
+ai.viewpoint-debate.get-id
+alternative.concept-info
+alternative.concept-securities
+insight.foreign-report.download
+insight.pamirs-summary.download
+insight.summary.download
+tool.file-parse.submit
+vault.my-conference.download
+-->
 - **按单元格**：`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 只写了「需购买专家纪要数据库」这个准入门槛，没给单次价格。**别据此假定免费**；大批量拉取前先小量试，或向平台确认
 
@@ -110,7 +135,9 @@ description: |-
 | `vault record-download` | `--content-type` | `original` 原始文件 / `asr` 语音识别 / `summary` AI 速记 |
 | `vault my-conference-download` | `--content-type` | `asr` 语音识别 / `summary` AI 速记 |
 
-省略 `--output` 时 CLI 自动用真实标题做文件名（先读本地 title-cache，未命中则回查 list 接口）。**批量下载或下载旧文件**（跳过 list 直接按 ID 下）时 title-cache 大概率未命中、每个文件都回查一次 list，建议显式 `--output ./<名>.<ext>` 省掉回查。
+省略 `--output` 时 CLI 用本地 title-cache 里的真实标题做文件名——**只读缓存**，命中就零额外调用。缓存由同端点的 `list` 写入，所以「先 `list` 再 `download`」这个正常工作流本来就免费拿到正确文件名。
+
+🔴 **未命中时默认不回查**（v0.37.0 起），退回服务端文件名或 `<type>-<id>.<ext>`。要回查得显式加 `--resolve-title`——它拉最近 200 条（4 次请求），而这些 list 多数按 **0.1 积分/条**计费，约 20 积分，只用于取一个更易读的文件名（下载本身 10–50）。**批量下载或按 ID 下旧文件**时：要么先跑一次 `list` 把标题灌进缓存，要么直接 `--output ./<名>.<ext>` 自己定名；`--resolve-title` 会把取回的 200 条一并写回缓存，同批后续下载不再重复消耗。
 
 ## 意图路由表
 
@@ -191,8 +218,8 @@ description: |-
   - EDE 取数前必须用 `search --format json` 同时核对：`indicatorName` + `description` 语义准确、`scopeList` 覆盖全部目标市场 / 证券类型、`parameterList` 必填参数与枚举可满足；`scopeList` 缺失 / `null` / 空或任一项不符，都视为无法证明覆盖并回退专用接口。专用接口也不覆盖目标市场时，说明当前不可用，不要硬调。`scopeList` 按指标各不相同，不能因 EDE 服务支持 A / 港 / 美股就假定某个指标三市场都覆盖
   - `indicator search` 免费，`cross-section` / `time-series` 按单元格计费；除多证券批量的效率收益外，仍优先免费 / 低价的 `quote` 或 `fundamental`
 - 行业 / 宏观指标（空调销量、社融等，无证券维度）走 `alternative edb-*`（EDB），不要与证券级 EDE 混用
-- **EDE「没数据」和「代码写错」是两回事**（2026-08-15 实测）：**①代码写错 → 直接报 `100003` 并指名是哪个**（指标写错报「指标 xxx 不存在」，证券写错报「xxx 不是有效证券或者板块ID」，美股用 `.US` 而非 `.O`/`.N` 同理），**无论同批有没有其它正确的 code 都会报**，所以拼写错误现在是一眼可见的、不用再靠对照推断；**②代码有效但无数据 / 无覆盖 / 未来日期 → 行列都保留**（含单指标 × 单证券的 1×1）并给一个占位单元格，**退出码 0**。🔴 **占位值不统一、由指标决定**：多数是 `null`，但个别（最常用的是 `is_dnrpnp` 扣非归母净利润）填 **`0`**，而 `0` 会照常穿过比较与聚合——`screener` 的 `F1 > 0` 因此可能筛出空集、整列求均值可能差几十倍（茅台时序实测差 52 倍）。**别把 `0` 当真值**，无覆盖时它与真值无法区分，**和已知有数的标的一起查做对照仍然必要**，详见 `references/commands/indicator.md`。日期语义按指标分两类：财务报表指标=报告期末（可为非交易日）、`finc_pe_ttm` / `finc_pb_mrq` 等日频估值=最新交易日（⚠️ `finc_pb_mrq` 是日频的，用报告期末日期会取到几个月前的陈值）；混合取数按各自有效日期分次 `cross-section` 再按证券合并，别塞进同一个 `--date`。详见 `references/commands/indicator.md`
-- **EDE 指标参数名一律以 `indicator search --format json` 的 `parameterList` 为准**，不要凭记忆或照抄示例。参数名写错会报 `100003` 并指出是哪个指标的哪个参数（如复权参数是 `adjustType`，写成 `adjustmentType` 直接报错），按报错信息改即可。⚠️ **报告期类指标（`is_*` 利润表等）必填 `reportDate`，不吃 `tradeDate`**——只传 `--date` 会报「不支持参数 tradeDate; 缺少必填参数 reportDate」，要补 `--indicator-param "code:reportDate=YYYY-MM-DD"`；行情 / 估值类（`qte_*` / `finc_*`）用 `--date` 即可。`--security` 支持板块 ID（`reference sector-search` 的 10 位 `sectorId`；`--indicator` 只收指标编码）。根级 `--scale` 只作用于声明了 `scale` 的指标，价格与金额可以混查。
+- **EDE「没数据」和「代码写错」是两回事**（2026-08-15 实测）：**①代码写错 → 直接报 `100003` 并指名是哪个**（指标写错报「指标 xxx 不存在」，证券写错报「xxx 不是有效证券或者板块ID」，美股用 `.US` 而非 `.O`/`.N` 同理），**无论同批有没有其它正确的 code 都会报**，所以拼写错误现在是一眼可见的、不用再靠对照推断；**②代码有效但无数据 / 无覆盖 / 未来日期 → 行列都保留**（含单指标 × 单证券的 1×1）并给一个占位单元格，**退出码 0**。占位值**统一为 `null`**（2026-08-24 实测跨 4 指标 × 4 市场 + 243 行时序确认）。⚠️ **仍要当心报告期类指标的时序**：只有报告期末那几行是真值，其余全是 `null`（茅台 5 个月 104 行只有 2 行有数），整列手工求均值会差几十倍；截面日期不落在报告期末则整批 `null`、`screener` 筛出空集。详见 `references/commands/indicator.md`。日期语义按指标分两类：财务报表指标=报告期末（可为非交易日）、`finc_pe_ttm` / `finc_pb_mrq` 等日频估值=最新交易日（⚠️ `finc_pb_mrq` 是日频的，用报告期末日期会取到几个月前的陈值）；混合取数按各自有效日期分次 `cross-section` 再按证券合并，别塞进同一个 `--date`。详见 `references/commands/indicator.md`
+- **EDE 指标参数名一律以 `indicator search --format json` 的 `parameterList` 为准**，不要凭记忆或照抄示例。参数名写错会报 `100003` 并指出是哪个指标的哪个参数（如复权参数是 `adjustType`，写成 `adjustmentType` 直接报错），按报错信息改即可。🔴 **日期参数不能按 code 前缀推**——**唯一判据是 `parameterList` 里必填的是哪个**：有 `tradeDate` 就用 `--date`，有 `reportDate` 就补 `--indicator-param "code:reportDate=YYYY-MM-DD"`。多数报告期类指标（`is_*` 利润表等）确实要 `reportDate`（只传 `--date` 会报「不支持参数 tradeDate; 缺少必填参数 reportDate」），**但 `_ttm` 后缀整族相反、必填 `tradeDate`**（`is_op_rev_ttm` / `is_net_prft_ttm` / `cf_op_cf_ttm` / `div_cash_ttm` … 跨 `is_`/`cf_`/`div_`/`finc_` 四族都有），传 `reportDate` 会报「不支持参数 reportDate」。行情 / 估值类（`qte_*` / `finc_pe_ttm` 等）用 `--date` 即可。`--security` 支持板块 ID（`reference sector-search` 的 10 位 `sectorId`；`--indicator` 只收指标编码）。根级 `--scale` 只作用于声明了 `scale` 的指标，价格与金额可以混查。
 - **新增指标**：融资融券 21 个 `mgn_*`（`mgn_bal` 两融余额 / `mgn_fin_*` 融资 / `mgn_sl_*` 融券 / `mgn_flag` 是否标的，**仅 A 股有数**；区间类的 `changePeriod` 2026-08-14 起改为**可选**）；行业分类 `scr_indu`（一个指标覆盖申万/中信/恒生/GICS 四套，**必填** `industryType` 1-4 + `industryLevel` 0-4，A/港/美股均支持，返回字符串），2026-08-14 又加了三个**行业组合指标** `scr_indu_citic` / `scr_indu_sw` / `scr_indu_gics`（体系写进编码，只需可选的 `industryLevel`；单套体系用它们更省事，横比多套仍用 `scr_indu`）
 - "业绩点评"双义消歧：**检索已有**（研报/纪要里的业绩点评内容）走 `insight ... list --llm-tag earningsReview`（0.1/条）；**AI 现生成**一份走 `ai earnings-review`（异步、50/次）。不确定问一句
 
@@ -263,9 +290,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` 不改变 `--rank-type 1` 取回哪些条目**（实测 19 组 0 反例，前 50 逐位相同，其中一组 `total` 从 1522 涨到 45257 仍逐位不变），**要相关度不必加 `--search-type 2`**；它扩大的是命中总数和 `--rank-type 2` 的候选池。🔴 **两档差别有多大取决于关键词，别拿一个词判断参数有没有用**：有些关键词下两档返回同一批，有些交集接近 0，判据见 `insight.md` 开头。⚠️ 综合排序**挑完之后仍按时间倒序排列**，所以别用「结果是不是时间倒序」判断它有没有生效，要比条目 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 默认排序。
 
 ## 异常处理
 
@@ -284,7 +311,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 | 错误码 | 含义 | CLI 行为 | Agent 是否介入 |
 |--------|------|---------|--------------|
 | ✅ `100003` | 参数值非法——**最宽的兜底码**：类型错、`limit` 越界都归这里。**msg 通常已指明字段**（如「请求体字段类型不匹配: size 期望类型 Integer」「limit 最小为 1，最大为 10000」），先读 msg 再猜 | — | 按 msg 指的字段改；msg 没指明才对照 `--help` 查枚举拼写，**不要重试同命令** |
-| ✅ `999999` | 系统错误。**`indicator`（EDE）2026-08-01 前用此码表示查询无数据，之后改为返回数据体**，所以这个码基本只剩真故障。⚠️ 现在「无数据」是保留行列的占位单元格（多为 `null`，个别指标是 `0`，见 `indicator.md`），**不是空表**；空表另有含义（整轴 code 未识别） | 普通端点自动重试 ×2；🔴 贵档与 `indicator` 端点不重试 | 确认参数无误仍报此码即服务端故障 |
+| ✅ `999999` | 系统错误。**`indicator`（EDE）2026-08-01 前用此码表示查询无数据，之后改为返回数据体**，所以这个码基本只剩真故障。⚠️ 现在「无数据」是保留行列的占位单元格（统一 `null`，见 `indicator.md`），**不是空表**；空表另有含义（整轴 code 未识别） | 普通端点自动重试 ×2；🔴 贵档与 `indicator` 端点不重试 | 确认参数无误仍报此码即服务端故障 |
 | ✅ `410110` | **异步生成中**（HTTP 400，旧码未切）。新码 `140001`，CLI 两码都认 | 轮询视为 pending | 继续等 |
 | ✅ `410111` | **异步生成失败**（HTTP 400，旧码未切）。新码 `140002`，CLI 两码都认 | 终态 | **不重试**，换参数 |
 | ✅ `130002` | 资源不存在——下载类的常见码：`reportId` 不存在 / 非数字多归此码。另有更具体的 `130003`（资源未生成 / 无附件）与 `130005`（`fileType` 非法） | — | 确认 ID 有效且本账号可见；换 `--file-type` 或换一篇验证 |
@@ -305,10 +332,10 @@ 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` 等仍是自由字符串，拼错不报错也不生效——这些要自己核对。**拼错的筛选条件会伪装成"结果正常"，枚举拼写要自己保证**
+- **枚举值拼错基本都会报 `100005`，但「字段名不被该端点支持」仍然静默**：纪要 `summary`、三个公告 list、路演 `roadshow`、调研 `site-visit` 的 `--search-type` / `--rank-type` / `--category` / `--market` 等传非法值报 `100005`；`insight research`（内资研报）、`foreign-report`（外资研报）、`official-account` 的 `--search-type` / `--rank-type` 现在同样报 `100005`。⚠️ **剩下的口子是「该端点根本没有这个参数」**：传一个端点不支持的字段名（如给 `opinion` 传 `searchType`——它只有 `--rank-type`）会被静默丢弃、按未传处理，返回未经筛选的全库而不报错。**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` 等仍是自由字符串，拼错不报错也不生效——这些要自己核对。**拼错的筛选条件会伪装成"结果正常"，枚举拼写要自己保证**
 - **`viewpoint-debate` 传敏感内容不会被提前拦截**——实测不返回 `240002`，而是照常受理、扣满 50 积分、生成阶段才以 `410111` 失败。**提交前自己把关措辞**
 - **`ai one-pager` 的非法 `mode` 被静默忽略**，照常生成并扣 50 积分
 
@@ -320,7 +347,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 | `999007` / `999008` / `999009` | 方法/媒体类型/请求体不支持 | 实际返回 `900002` / `999999` / `100003` |
 | `999003` / `999005` / `999006` | 无接口权限 / 积分不足 / 限流 | 未构造出（需特定账号状态） |
 | `999012`–`999016` | 账号禁用/过期、租户失效、无长期 token、IP 不合规 | 未构造出 |
-| `100002` / `100004` / `100005` | 类型错 / 分页非法 / 枚举非法 | 类型错归 `100003`。**`100005` 与 `100006` 2026-08-14 起在部分 list 上真会触发**（枚举非法、`size` 超 50）；未覆盖的端点（`research` / `foreign-report` / `opinion` / `official-account`）仍按未传处理，见上方「实测发现的坑」 |
+| `100002` / `100004` / `100005` | 类型错 / 分页非法 / 枚举非法 | 类型错归 `100003`。**`100005`（枚举非法）与 `100006`（`size` 超 50）现在在各 list 端点上普遍触发**——`size=51` 实测七端点一致报 `100006`（`official-account` / `research` / `foreign-report` / 三个 opinion / `summary`）。仍按未传处理的只剩「该端点不支持的字段名」，见上方「实测发现的坑」 |
 | `130004` | 下载 ID 非数字 | 多归 `130002` |
 | `140001` / `140002` | 结果生成中 / 处理失败 | 异步端点仍用 `410110` / `410111` |
 | `210001` / `220001` / `230001` | 研报/观点/分享文件不支持下载 | 未构造出 |
@@ -339,8 +366,8 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 - CLI 未安装 → `npm install -g gangtise-openapi-cli`
 - **退出码 3 = `partial: true`，结果少了数据**（保留已取到的部分；stderr 有 warning，`--format json` 才看得见标记，table/csv/jsonl 只有数据行、看不出问题）：
   - 触发场景：翻页/K线分片有页失败、服务端返回行数与 `total` 矛盾（提前短页）、`total` 撞服务端上限（`totalCapped`，见 opinion 家族）。附带定位字段：页失败 `failedPages`；分片失败 `failedShards`、分片撞行数上限 `truncatedShards`（均带日期区间可缩窗补拉）。⚠️ EDE 的 `omittedIndicators` / `omittedSecurities` 仍在代码里，但 2026-08-15 起写错的 code 在服务端就被 `100003` 拒了（退出 1），这条路基本收不到样本
-  - **EDE 代码写错现在是退出码 1 + `100003`，msg 里直接点名是哪个 code**（美股后缀用 `.O`/`.N`，不是 `.US`），不用再从退出码 3 反推。真的没覆盖仍是占位单元格（多数 `null`、个别指标 `0`）+ 退出码 0
-  - **`screener` 的缺列按表达式的布尔结构判**：把缺列的变量当作「无法求值」，看整个表达式**是否还有一条能成立的分支**——`A && B` 要两边都可求值，`A || B` 只要一边。**一条分支都不剩 → 退出码 1、不输出任何结果**（返回的行以「通过了该条件」的名义呈现，而条件根本无法证明被执行过）；**还有分支可求值，或缺的只是未参与表达式的辅助变量 → `partial` + 退出码 3**。所以 `F1 || F2` 缺 F1 是降级（行可能靠 F2 正当命中），缺两个则是致命；`F1 && (F2 || F3)` 缺 F1 仍是致命（F1 是必选合取项）。⚠️ **前提是服务端返回了命中行**——零命中时走「nothing matched」+ **退出码 0**。**空集别急着当成「条件成立但无标的符合」**：指标码写错现在会直接报 `100003`（退出 1），所以剩下的头号嫌疑是**占位值 `0`** —— `F1 > 0` 在 `is_dnrpnp` 这类填 `0` 的指标上必然筛出空集
+  - **EDE 代码写错现在是退出码 1 + `100003`，msg 里直接点名是哪个 code**（美股后缀用 `.O`/`.N`，不是 `.US`），不用再从退出码 3 反推。真的没覆盖仍是占位单元格（统一 `null`）+ 退出码 0
+  - **`screener` 的缺列按表达式的布尔结构判**：把缺列的变量当作「无法求值」，看整个表达式**是否还有一条能成立的分支**——`A && B` 要两边都可求值，`A || B` 只要一边。**一条分支都不剩 → 退出码 1、不输出任何结果**（返回的行以「通过了该条件」的名义呈现，而条件根本无法证明被执行过）；**还有分支可求值，或缺的只是未参与表达式的辅助变量 → `partial` + 退出码 3**。所以 `F1 || F2` 缺 F1 是降级（行可能靠 F2 正当命中），缺两个则是致命；`F1 && (F2 || F3)` 缺 F1 仍是致命（F1 是必选合取项）。⚠️ **前提是服务端返回了命中行**——零命中时走「nothing matched」+ **退出码 0**。**空集别急着当成「条件成立但无标的符合」**：指标码写错现在会直接报 `100003`（退出 1），剩下**三种成因产生逐字相同的输出**——① 真的没有标的满足条件；② **日期没落在报告期末**（报告期类指标此时整批 `null`）；③ **该指标不覆盖这批证券**（拿 A 股专属指标查港美股，如 `finc_pb_mrq` / `mgn_*`）。②③ 都要靠单查一行确认，不能只改日期
   - 拿到 3 就必须告知用户缺了哪段，不能当成功静默继续
 - 空结果（list 为空数组） → 建议扩大时间范围、换关键词、去掉部分筛选
 - 模糊公司名匹配多只（"平安" → 中国平安 / 平安银行 / ...） → 列出让用户选

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

@@ -3,7 +3,7 @@
 > 本组覆盖 `/application/open-indicator/*`：证券级**数据指标**的检索与取数，主要用于多证券批量取已实现财务 / 估值指标。即使能搜到收盘价、成交量等行情指标，常规行情与 K 线仍走免费的 `quote`。
 > 与 `alternative edb-*`（EDB 行业/宏观指标，无证券维度）是两套接口，别混。
 >
-> **取数前先 `indicator search` 拿 `indicatorCode` 和 `parameterList`**，绝不猜测指标编码或参数名——参数名写错不会报错，而是按该参数的默认值取数，结果看着正常但口径不对。
+> **取数前先 `indicator search` 拿 `indicatorCode` 和 `parameterList`**，绝不猜测指标编码或参数名——参数名与枚举会随版本调整，写错会直接报 `100003` 并指出是哪个指标的哪个参数，照报错改即可；照抄示例里的旧参数名则会白跑一次。
 
 ## EDE 与专用接口的优先级
 
@@ -15,9 +15,10 @@
 | A股估值历史分位 | `fundamental valuation-analysis` |
 | **估值指标的历史序列**（分位 / 回测 / 择时） | 两个接口口径不同、都要交叉核——EDE 按正式财报披露日切换财报口径，`valuation-analysis` 按业绩快报切，见下方专门小节 |
 | 开高低收 / 成交量等行情与 K 线 | `quote`；免费且支持多证券批量 |
+| 单证券资金流向（要占比字段） | `quote fund-flow`；免费，且有 EDE 没有的 `*Ratio` 占比。多证券批量取某一两个档位才用 EDE 的 `flow_*` |
 | 单证券三大报表全部科目 | 对应 `fundamental` 利润表 / 资产负债表 / 现金流量表命令 |
 
-EDE 不是“搜到就优先”。取数前必须核对：① `indicatorName` + `description` 与目标语义一致；② `scopeList` 覆盖**全部**目标市场和证券类型；③ `parameterList` 的必填参数与枚举可满足。`scopeList` 缺失 / `null` / 空或任一项不符，都视为无法证明覆盖并回退上表的专用接口；专用接口也不支持目标市场时，如实说明当前 CLI 无可用口径，不能用其他语义代替。实测 `valuation-analysis` / `earning-forecast` 仅支持 A 股，港 / 美股的**估值历史分位**与**盈利预测**当前无可用口径。但**估值指标本身别照抄旧结论**：`finc_pe_ttm`(PE TTM) 2026-08-03 起港股已有数（腾讯 16.15 / 泡泡玛特 14.93），`finc_pb_mrq`(PB MRQ) 仍只有 A 股。⚠️ **本文里所有「仅 A 股」「无数据」这类否定结论都只是某个时点的抽查**——服务端在持续补数据，正面结论过期会给错数，负面结论过期则会让你白白拒掉一个现在能跑的查询（不报错、不告警，只是少调一次）。**一律以当次 `scopeList` + 抽查为准，本段结论截至 2026-08-03。**`search` 免费，EDE 取数按单元格计费；除多证券批量的效率收益外，仍优先免费 / 低价的 `quote` 或 `fundamental`。
+EDE 不是“搜到就优先”。取数前必须核对：① `indicatorName` + `description` 与目标语义一致；② `scopeList` 覆盖**全部**目标市场和证券类型；③ `parameterList` 的必填参数与枚举可满足。`scopeList` 缺失 / `null` / 空或任一项不符，都视为无法证明覆盖并回退上表的专用接口；专用接口也不支持目标市场时，如实说明当前 CLI 无可用口径，不能用其他语义代替。实测 `valuation-analysis` / `earning-forecast` 仅支持 A 股，港 / 美股的**估值历史分位**与**盈利预测**当前无可用口径。但**估值指标本身别照抄旧结论**：`finc_pe_ttm`(PE TTM) 2026-08-03 起港股已有数（腾讯 16.15 / 泡泡玛特 14.93）；`finc_pb_mrq`(PB MRQ) 的港股覆盖是**部分**的（2026-08-24 实测：建设银行 0.6318 / 中国移动 1.2222 / 中芯国际 28.8783 / 小米 −5.5223 / 中国平安 0.9656 有数，而腾讯 / 阿里 / 泡泡玛特为 `null`）。⚠️ **本文里所有「仅 A 股」「无数据」这类否定结论都只是某个时点的抽查**——服务端在持续补数据，正面结论过期会给错数，负面结论过期则会让你白白拒掉一个现在能跑的查询（不报错、不告警，只是少调一次）。**一律以当次 `scopeList` + 抽查为准，本段所引实测截至 2026-08-24。**`search` 免费，EDE 取数按单元格计费；除多证券批量的效率收益外，仍优先免费 / 低价的 `quote` 或 `fundamental`。
 
 ## 指标搜索 `indicator search`
 
@@ -29,9 +30,9 @@ gangtise indicator search --keyword <text> [--limit <n>]
 - `--limit`：返回条数上限，默认 50，最大 100
 - 默认 `--format table` 只适合浏览名称；正式路由 / 取数前必须加 `--format json`，才能完成语义、`scopeList`、`parameterList` 三项校验
 - 返回字段：`indicatorCode` / `indicatorName` / `description`（算法与口径）/ `scopeList`（该指标适用的市场 + 证券类型 + `usageRestriction`）/ `parameterList`（可传的 `--indicator-param` 参数名及枚举）/ `score`
-- **市场范围按指标判断**：`scopeList` 会返回实际覆盖范围，且指标之间不同；不能笼统写成每个指标都覆盖 A / 港 / 美股。覆盖面在持续扩，别把抽查结论当常量：截至 **2026-08-03** 实测 `qte_mkt_cptl`/`shr_tot` 已覆盖 A/港/美股，`finc_pe_ttm` 覆盖 A/港股，`finc_pb_mrq` 仍只有 A 股，`is_op_rev_ttm`/`is_shnp_ttm` 覆盖 A/港股。目标列表含任一 scope 外证券时，本批 EDE 校验不通过，应回退专用接口
+- **市场范围按指标判断**：`scopeList` 会返回实际覆盖范围，且指标之间不同；不能笼统写成每个指标都覆盖 A / 港 / 美股。覆盖面在持续扩，别把抽查结论当常量：截至 **2026-08-03** 实测 `qte_mkt_cptl`/`shr_tot` 已覆盖 A/港/美股，`finc_pe_ttm` 覆盖 A/港股，`finc_pb_mrq` 覆盖 A 股 + **部分**港股（2026-08-24 实测 TOP 港股约三分之一有数），`is_op_rev_ttm`/`is_shnp_ttm` 覆盖 A/港股。目标列表含任一 scope 外证券时，本批 EDE 校验不通过，应回退专用接口
 - **`scopeList[].usageRestriction`**：该指标在具体接口上的限制，`null` = 无限制。⚠️ **它是提示不是硬约束**——标着「不支持指标时间序列接口」的 `qte_vol_intvl` 实测调时序照样返数据、不会被拦下（2026-08-02）。当成「口径可能不对、结果别当真」看，别指望它会报错
-- ⚠️ **`scopeList` 是声明不是保证**：它可能**超前于数据**——`finc_pb_mrq` 声称覆盖 A股+港股，实测港股仍无数据（复测 2026-08-08）。反过来也发生过：`qte_mkt_cptl`/`shr_tot` 在 08-02 时声称覆盖港/美股却无数据，08-03 数据补上了。**判断成本已经很低**：无数据会保留行列、给一个占位单元格，抽查一行就能看出覆盖情况；code 写错则直接报 `100003`，两种情形不会再混淆。⚠️ **但占位值不统一**——多数指标是 `null`，个别是 `0`（详见下方「缺数据 vs 代码写错」）
+- ⚠️ **`scopeList` 是声明不是保证**：它可能**超前于数据**，也可能**滞后于你上次的抽查**——`finc_pb_mrq` 声称覆盖 A股+港股，2026-08-08 实测港股无数据，**但 2026-08-24 复测已有约三分之一的港股有数**（建设银行 / 中国移动 / 中芯国际 / 小米 / 中国平安有值，腾讯 / 阿里 / 泡泡玛特仍 `null`）。同向的例子：`qte_mkt_cptl`/`shr_tot` 在 08-02 声称覆盖港/美股却无数据，08-03 就补上了。**「某某仍无数据」这类否定结论过期得和正面结论一样快**，照着它走会白白拒掉一个现在能跑的查询，而且不报错。**判断成本已经很低**：无数据会保留行列、给一个占位单元格，抽查一行就能看出覆盖情况；code 写错则直接报 `100003`，两种情形不会再混淆。占位值统一是 `null`（详见下方「缺数据 vs 代码写错」）
 - 美股代码用交易所后缀 `.O`(NASDAQ) / `.N`(NYSE)：用 `AAPL.O`，`AAPL.US` 取不到数据
 
 ```bash
@@ -48,7 +49,7 @@ 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`（**必选**）：数据日期 `yyyy-MM-dd`。**CLI 把它下发为每个指标各自的 `tradeDate`**（2026-08-01 起服务端取消了根级 date）。日期语义按指标分两类——财务报表指标=报告期末（可为非交易日，实测 `2024-03-31` 可取数；**⚠️ `_ttm` 后缀整族例外，走交易日，见下方「日期路由」**）、`finc_pe_ttm` / `finc_pb_mrq` 等日频估值=交易日（详见下方「日期路由」）
   - `--date` 必填是 CLI 的**护栏**，不是协议要求：`cross-section` 本身接受 `indicatorParamList: []`。但绝大多数指标吃 `tradeDate`，漏传就是一张空表且退出码 0，所以宁可多带一个。（`screener` 的 `--date` 也必填，同理）
   - 🔴 **判据一句话：该指标的 `parameterList` 里有 `tradeDate` 就不用管；没有，`--date` 下发的 `tradeDate` 就可能被拒。** 按这条走，四种情形四种写法（`parameterList` 从 `indicator search --keyword <code> --format json` 读，别按 code 前缀推断）：
 
@@ -124,7 +125,7 @@ gangtise indicator screener --indicator <F1:code> [--indicator <F2:code2>] \
   - 文本：`contains` / `notcontains`（不区分大小写，**仅对 `dataType: string` 的指标有效**）
   - 逻辑：`&&` `||`，分组 `(` `)`
 - `--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=...` 照常可用
+- 🔴 **`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 / <各指标名>…`；无命中返回空表
@@ -148,11 +149,12 @@ gangtise indicator screener --indicator F1:qte_close --indicator F2:qte_close \
 
 ```bash
 # 文本筛选：白酒板块里经营范围含「酒」的公司
-# ⚠️ 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 上可用的文本筛选换成有日期参数的字符串指标，例如：
+# ⚠️ pty_op_scope 的 parameterList 为空 → 必须带 "F1:" 声明它不吃日期，否则整条请求报 100003
+gangtise indicator screener --indicator F1:pty_op_scope \
+  --indicator-param "F1:" \
+  --security 1000000287 --expression "F1 contains '酒'" \
+  --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   # 融资融券标的
@@ -184,35 +186,54 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
   - ⚠️ **参数名是 `adjustType`**（不是 `adjustmentType`）。写错名会报 `100003` 并指出是哪个指标的哪个参数，按报错改即可
   - 前复权以最新交易日为基准，所以在**最新交易日上前复权价 == 不复权价**；验证复权是否生效要用历史日期
 - 同一指标多个参数 → 重复 `--indicator-param "code:k1=v1" --indicator-param "code:k2=v2"`
-- **参数名与取值一律以 `indicator search --format json` 的 `parameterList` 为准**，不要照抄任何文档里的示例名——参数名会随版本调整。写错会报 `100003` 并指出是哪个指标的哪个参数（2026-08-15 起；此前是静默按默认值取数），按报错改即可。币种枚举**统一大写**（`DFT`/`CNY`/`HKD`…），小写形式不生效
+- 🔴 **冒号左边的 code 必须是 `--indicator` 列出过的**：写了别的（多为拼写错误）会在发请求前报 `--indicator-param references "xxx", which no --indicator names`（v0.37.0 起）。这条拦的是「参数没落到你要查的指标上」——按报错核对拼写即可。`screener` 上是同款检查，只是按变量：变量必须被 `--indicator` 绑定
+- **参数名与取值一律以 `indicator search --format json` 的 `parameterList` 为准**，不要照抄任何文档里的示例名——参数名会随版本调整。写错会报 `100003` 并指出是哪个指标的哪个参数（2026-08-15 起），按报错改即可。币种枚举**统一大写**（`DFT`/`CNY`/`HKD`…），小写形式不生效
 - `--indicator-param` 与根级 `--currency`/`--scale` 冲突时，以 `--indicator-param` 为准
 
 ## 必填参数与错误码（取数前必读）
 
+### 取数可靠性：`qte_vol` 等指标在某些日期上会随机返 `null`
+
+🔴 **同一条请求多次调用，结果会在「有值」和 `null` 之间跳。** 这**与「是不是最新交易日」无关**——是**特定日期**的数据在部分副本上缺失。
+
+实测（2026-08-24，`00941.HK` 各 8 次）：
+
+| 日期 | 结果 |
+| :-- | :-- |
+| `2026-08-24`（当时的最新交易日） | `########` 8/8 有值 |
+| **`2026-08-21`** | `0#0#0#00` **多数请求返 `null`** |
+| `2026-08-20` / `08-19` | `########` 8/8 有值 |
+
+受影响的**只是部分标的**：同一批里 A股、美股、腾讯、阿里都稳定。同一条请求内，受影响的证券**全有或全无**（不会一半有一半没有）。
+
+**做法，按优先级**：
+
+1. 🟢 **只要日成交量 / 成交额，别用 EDE，直接用 `quote day-kline`** —— 同一天同一只票实测 6/6 稳定，`amount` 与分钟线加总精确相等。**不用重试、不用换日期、不丢数据**；它的 `volume` 与 EDE `qte_vol` **逐位相同**（2026-08-28 实测 7 只，A股 / 港股 / 美股，单位同为股），**没有精度损失**
+2. 确实需要 EDE 才有的口径时（周 / 月 / 季 / 年 / 区间成交量等 `quote` 不提供的），**重试，但不要设固定次数上限** —— 实测出现过**连续 8 次全 `null`**。**若必须设上限，超限时要显式报错退出，绝不能把最后一次的 `null` 当成「无数据」写进结果**
+
+⚠️ **不要用「改取前一个交易日」当通用兜底**：它在 `2026-08-21` 这个个案上碰巧有效，但坏的是哪一天并无规律，而且会丢掉那一整天的数据。
+
+**单次 `null` 不能读成「该股当日无数据」** —— 它与真无数据无法区分，且退出码 0。判别法：**同一条请求再打几次**，只要出现过非 `null` 就说明数据是有的。
+
+---
+
 **缺数据 vs 代码写错（2026-08-08 服务端改版，判据整个换了）**：
 
 **缺数据一律保留行列并给一个占位单元格**，连单指标 × 单证券的 1×1 缺口也有行有列、不是空表。判据是**代码认不认识**，跟有没有数据无关：
 
-> 🔴 **占位值不统一，而且由指标决定——这一条会直接毁掉筛选和聚合结果**
->
-> 多数指标缺数据填 `null`，但**个别指标填 `0`**，其中最常用的是 `is_dnrpnp`（扣非归母净利润）。同一天同一只股票：`is_dnrpnp` 给 `0`、`is_op_rev` 给 `null`。**与日期对不对无关**——日期完全正确（报告期末）时，覆盖不到的证券（如美股）同样给 `0`：同一次请求里茅台、泡泡玛特返真值，苹果、微软的 `is_dnrpnp` 返 `0`、`is_op_rev` 返 `null`，四行都在、无告警、退出码 0。
->
-> **`0` 会照常穿过比较与比率计算**，`null` 不会。实测 `screener`（`F1 = is_dnrpnp`，三只 A 股）：
+> 🔴 **报告期类指标（`is_*`）取不到数时返 `null`，而时序上大部分行都是 `null`——这一条会直接影响聚合结果**
 >
-> | 表达式 | 非报告期末日期 | 报告期末日期 |
-> | :--- | :--- | :--- |
-> | `F1 > 0` | **命中 0 只** | 命中 3 只 |
-> | `F1 < 50亿` | **命中 3 只**（值全是 `0`） | 命中 1 只 |
+> 占位值统一是 `null`（2026-08-24 实测：4 个指标 × 4 个市场的截面、243 行 × 3 指标的时序，无一格是 `0`）。`null` 在宽表里一眼可见，**Excel `AVERAGE` / pandas `mean()` / SQL `AVG` 会跳过它**，但**行数不会变**。🔴 **`jq` 不跳过**：`[1,null,2,null,null] | add/length` 得 **0.6**（正确值 1.5），`add` 把 `null` 当加法单位元而 `length` 照数——正是「整列求均值差几十倍」那个错法本身；全为 `null` 时 `add/length` 直接报错。用 jq 聚合前先 `map(select(. != null))`。
 >
-> 只换了日期，两个条件的结果全部反转，全程不报错。「扣非净利 > 0 筛出空集」会被读成「没有盈利的股票」。
+> **时序这一档最容易踩**：报告期类指标按日返回，**只有报告期末那几行是真值**，其余全是 `null`——茅台 `is_dnrpnp` 查 2025-03-01→07-31 共 **104 行，只有 03-31 和 06-30 两行有数**。而**时序没有任何参数能让它只返回报告期末**（传 `tradeDate` / `reportDate` 都会被拒）。用「总和 ÷ 行数」手工求均值会得到偏低 50 倍的结果；用会跳过 `null` 的聚合（如多数 DataFrame 的 `mean()`）才是对的。
 >
-> **时序上更难躲**：报告期类指标按日返回，只有报告期末那几行是真值，其余是占位。`is_op_rev` 的 `null` 通常被聚合跳过、均值仍然对；`is_dnrpnp` 的 `0` 会被算进去——茅台 5 个月 104 行里 102 行是 `0`，整列求均值比正确值低 50 倍以上。而**时序没有任何参数能让它只返回报告期末**（传 `tradeDate`/`reportDate` 都会被拒）。
+> **截面这一档**：日期不落在报告期末（如 `2025-05-15`）时整批返 `null`，`screener` 的任何比较都不成立、筛出空集——**这不是「没有符合条件的标的」，是日期用错了**。
 >
-> **怎么办**：① 报告期类指标一律把日期落在**报告期末**（`2025-03-31` / `06-30` / `09-30` / `12-31`）；② 拿 `is_dnrpnp` 这类做筛选或聚合前，先单查一次确认不是占位；③ **别对时序整列直接求均值 / 求和**，先按报告期末取子集。
+> **怎么办**：① 报告期类指标一律把日期落在**报告期末**（`2025-03-31` / `06-30` / `09-30` / `12-31`），截面用 `--indicator-param "F1:reportDate=..."` 显式指定；② **别对时序整列直接求均值 / 求和**，先按报告期末取子集，或确认你的聚合会跳过 `null`。
 
 | 情况 | 服务端怎么返 | CLI |
 | :--- | :--- | :--- |
-| 代码有效、但**无数据 / 无覆盖 / 非交易日 / 未来日期** | 占位单元格（多数 `null`，个别指标 `0`，见上），行列都在 | **退出 0**，不标 partial |
+| 代码有效、但**无数据 / 无覆盖 / 非交易日 / 未来日期** | 占位单元格（统一 `null`），行列都在 | **退出 0**，不标 partial |
 | **指标码无法解析**（拼错、不存在） | `100003「指标 xxx 不存在」` | **退出 1**，报错 |
 | **证券码无法解析**（拼错、后缀错，如 `AAPL.US`） | `100003「xxx 不是有效证券或者板块ID」` | **退出 1**，报错 |
 | **参数名写错 / 同 code 重复配置** | `100003` 并指名参数 / 「重复配置」 | **退出 1**，报错 |
@@ -221,7 +242,7 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 
 | 查法 | 服务端返回 |
 | :--- | :--- |
-| `--indicator finc_pb_mrq --security 09992.HK`（港股无 PB 数据） | 1 行，`finc_pb_mrq: null`，**退出 0** |
+| `--indicator finc_pb_mrq --security 09992.HK`（**这一只**港股无 PB 数据；同指标下 `00939.HK`/`00941.HK` 等是有数的） | 1 行，`finc_pb_mrq: null`，**退出 0** |
 | `--indicator qte_close --date 2027-01-04`（未来日期） | 1 行，`qte_close: null`，**退出 0** |
 | `--indicator qte_close --indicator not_a_real_code`（有对照物） | `100003 指标 not_a_real_code 不存在` |
 | `--indicator not_a_real_code`（**无对照物**） | `100003 指标 not_a_real_code 不存在` ← 同样报错 |
@@ -229,13 +250,21 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 
 **代码写错现在一律报错、且消息里带上那个代码**，无论同批有没有别的正确代码——不用再靠「和一个已知有数的标的一起查」推断是哪个写错了。**所以「空表」的含义变干净了：它现在基本只意味着真的没数据**（此前空表既可能是没数据、也可能是整个轴写错）。
 
-⚠️ **唯一还需要对照法的是占位值那一档**：占位**多数是 `null`、个别是 `0`**（见上方 🔴 段），`0` 长得和真值一样。拿 `is_dnrpnp` 这类做筛选或聚合前，仍要和已知有数的标的一起查做对照。
+**占位值统一为 `null` 后，「和一个已知有数的标的一起查」这套对照法不再必要**——缺数据一眼可见。仍要留意的是**日期语义**（见上方 🔴 段）：日期用错时整批返 `null`，形态与「真的没覆盖」一样。
 
 > CLI 侧仍保留 `partial` + `omittedIndicators` / `omittedSecurities` + 退出码 3 的差集检测，但在当前服务端行为下基本收不到样本（错代码在服务端就被拒了）。留着是为了万一服务端回退时还有兜底，不影响正常使用。
 
 `screener` 上指标码写错同样直接报 `100003`，不会再走到「缺列」那条路。CLI 的缺列判据（按表达式布尔结构判，整个表达式再无可成立分支 → 退出码 1 且不输出；仍有分支可求值如 `F1 || F2` 只缺 F1 → `partial` + 退出码 3）保留作兜底。
 
-⚠️ **`screener` 的空集仍要当心，但原因变了**：现在空集基本只有两种来源——**真的没有标的满足条件**，或者**某个变量的值是占位 `0`**（`F1 > 0` 在 `is_dnrpnp` 全是占位 `0` 时必然筛出空集，见上方 🔴 段）。指标码拼错已不在其列（会直接报错）。
+⚠️ **`screener` 的空集仍要当心：三种成因产生逐字相同的输出（都是退出码 0 + 同一句 note）**
+
+| # | 成因 | 怎么区分 |
+| :-- | :-- | :-- |
+| ① | 真的没有标的满足条件 | —— |
+| ② | **日期没落在报告期末**（报告期类指标整批返 `null`，任何比较都不成立） | 改用报告期末日期重跑 |
+| ③ | **该指标不覆盖这批证券**（如拿 A 股专属指标查港美股：`mgn_*` 融资融券系列仅 A 股，2026-08-24 实测港/美股均 `null`） | 用 `cross-section` 单查一行看是不是 `null`。⚠️ **覆盖面是逐只的、且会变**，别按「某指标只有 A 股」这种整体结论排除 |
+
+实测：`is_dnrpnp` + `F1 > 0`，「AAPL+MSFT 且日期完全正确」与「茅台+五粮液但日期错」两种查法的输出**逐字相同**。**所以只改日期改不出来时，要怀疑覆盖面。** 指标码拼错已不在其列（会直接报错）。
 
 标 `partial` 的那档会在 stderr 打印被略过的 code（`--format json` 下 stdout 仍是干净 JSON）。脚本按 `!= 0` 判失败的要注意：3 表示「有数据但不完整」，不是硬失败。
 
@@ -246,7 +275,7 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 | `100001` | **缺少必填参数**：如 `universe` 没传 | 补齐 `--indicator`/`--security` |
 | `100003`@400 | 入参/表达式错误：`time-series` 传了「多指标 × 多证券」、`expression` 引用未声明变量、`indicatorParamList` 的 code 不在 `indicatorCodeList` 里 | 按 msg 改；多 × 多改用 `cross-section`。CLI 已在本地拦截「表达式引用未绑定变量」，不会白发一次请求 |
 | `140002`@500 | **终态参数错**：指标必填参数缺失、枚举越界（如「参数 adjustType 的值 99 不在有效范围内 [1,2,3,4]」）、表达式语法错误 | **不重试**（CLI 已把 140002 列为终态码）。读 `search --format json` 的 `parameterList` 改参数名/取值 |
-| `999999` | 系统故障。2026-08-01 起「无数据」不再用此码，所以它基本只剩真故障（2026-07-26 曾出现 EDE 取数端全线 999999，08-01 已恢复）。⚠️ 别把它和空表混为一谈：无数据现在是占位单元格（多数 `null`、个别指标 `0`），空表表示整轴 code 未识别 | CLI 对 indicator 端点**不重试此码**（v0.27.0）；确认参数无误仍报错就是服务端问题 |
+| `999999` | 系统故障。2026-08-01 起「无数据」不再用此码，所以它基本只剩真故障（2026-07-26 曾出现 EDE 取数端全线 999999，08-01 已恢复）。⚠️ 别把它和空表混为一谈：无数据现在是占位单元格（统一 `null`），空表表示整轴 code 未识别 | CLI 对 indicator 端点**不重试此码**（v0.27.0）；确认参数无误仍报错就是服务端问题 |
 | `110003` | **超出账号数据权限的时间范围**。⚠️ EDE 三个接口的可查范围可能不一致：出现过同日同指标同证券 `cross-section` 正常出数、而 `screener` 报此码 | 把日期移进范围；`screener` 撞界时先用 `cross-section` 查同一天验证，能取到就改用它拉数再本地筛 |
 | `130001`（旧 `410004`） | 数据未找到，或**该指标无权限**（内层信封失败会带具体 msg，如"指标无权限"；此码被服务端复用） | 检查查询条件与指标权限；换证券/日期仍失败多为无权限，联系管理员开通 |
 
@@ -263,6 +292,30 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 
 > `paramValue` 一律按**字符串**约定传（`periodNum=4` 内部即 `"4"`，CLI 已处理）。
 
+### 个股资金流向（17 个 `flow_*`）
+
+`scopeList` 与实测都只有 **A 股**（港 / 美股返 `null`）。必填 `tradeDate`，可选 `currency` / `scale`；**单位是元**（`scale` 默认 0 不缩放）。
+
+| 档位 | 流入额 | 流出额 | 净流入额 |
+| :--- | :--- | :--- | :--- |
+| 小单 | `flow_small_in_amt` | `flow_small_out_amt` | `flow_small_net_in_amt` |
+| 中单 | `flow_med_in_amt` | `flow_med_out_amt` | `flow_med_net_in_amt` |
+| 大单 | `flow_lrg_in_amt` | `flow_lrg_out_amt` | `flow_lrg_net_in_amt` |
+| 超大单 | `flow_xl_in_amt` | `flow_xl_out_amt` | `flow_xl_net_in_amt` |
+| **主力** = 大单 + 超大单 | `flow_main_in_amt` | `flow_main_out_amt` | `flow_main_net_in_amt` |
+| **全单** = 四档合计 | `flow_all_in_amt` | `flow_all_out_amt` | — |
+
+**为什么全单没有净额**：`flow_all_in_amt` 与 `flow_all_out_amt` **恒相等**（每笔成交都同时是一买一卖），净额恒为 0，所以只有 17 个而不是 18 个。这两个数就是当日成交额。
+
+🔴 **与 `quote fund-flow` 是同一套数，逐位相同**（实测 600519.SH：小单 38740 / 中单 1660538795 / 大单 1042050312 / 超大单 501475504 两边完全一致）。**选哪个**：
+
+| 场景 | 用 |
+| :--- | :--- |
+| 单只或少量证券、要全部档位和占比 | `quote fund-flow` —— **免费**，且额外给 `*Ratio` 占比字段（EDE 没有） |
+| 多证券批量、只要其中一两个档位 | `indicator cross-section` —— 一次请求取回，但**按单元格计费** |
+
+⚠️ 档位名易混：`main`（主力）= 大单 + 超大单，**不是**中单；中单是 `med`。
+
 ### 2026-08-07 新增指标
 
 **融资融券（21 个 `mgn_*`）**——`scopeList` 与实测都只有 **A 股**（港/美股返 `null`）：
@@ -314,21 +367,21 @@ gangtise indicator cross-section --indicator scr_indu_citic --indicator scr_indu
 
 ## 取数最佳实践
 
-- **先 search 做三项校验**：看 `indicatorName` + `description` 确认语义和口径，看 `scopeList` 确认覆盖全部目标市场 / 证券类型（并看 `usageRestriction` 有无接口限制），再看 `parameterList` 补齐必填参数（required）并核对专属参数**名称**与枚举（`adjustType`/`scale`/`currency` 等）；任一不符就回退专用接口。**参数名以 search 返回为准，不要照抄文档示例**——服务端调过参数名，传错名是静默失效不是报错。
-- **`scopeList` 声称覆盖 ≠ 真有数**：截至 2026-08-08，`finc_pb_mrq` 的 `scopeList` 写着 A股+港股，实测港股仍无数据。**2026-08-08 起这件事好查了一半**：无覆盖会留下占位单元格（行列都在，跟同批查了什么无关），抽查一行即可判定，不用再靠对照组反推。🔴 **但只有 `null` 那一档真的「一眼可见」**——`is_dnrpnp` 这类填 `0` 的指标，无覆盖和真值长得一模一样（美股实测：日期正确、行都在，`is_dnrpnp` 返 `0`、`is_op_rev` 返 `null`）。对填 `0` 的指标，抽查一行判不出覆盖，要拿一个已知有数的市场做对照。跨市场批量取数后**逐市场抽查一行**，别默认 scopeList 就是事实——反过来也一样，`qte_mkt_cptl`/`shr_tot` 在 08-02 还是港/美无数据、08-03 就补上了，**否定结论同样会过期**。
+- **先 search 做三项校验**：看 `indicatorName` + `description` 确认语义和口径，看 `scopeList` 确认覆盖全部目标市场 / 证券类型（并看 `usageRestriction` 有无接口限制），再看 `parameterList` 补齐必填参数（required）并核对专属参数**名称**与枚举（`adjustType`/`scale`/`currency` 等）；任一不符就回退专用接口。**参数名一律以 search 返回的 `parameterList` 为准，不要照抄任何示例里的参数名**——参数名会随版本调整，写错会报 `100003` 并指出是哪个指标的哪个参数，按报错改即可。
+- **`scopeList` 声称覆盖 ≠ 每只都有数**：`finc_pb_mrq` 的 `scopeList` 写着 A股+港股，2026-08-08 实测港股无数据，**2026-08-24 复测已有约三分之一港股有数**——所以它是**部分覆盖**，既不能当「全覆盖」也不能当「无覆盖」。**判断成本很低**：无覆盖会留下占位单元格（行列都在，跟同批查了什么无关），抽查一行即可判定，不用再靠对照组反推。占位值统一为 `null` 后这一步是可靠的（2026-08-24 实测）。跨市场批量取数后仍建议**逐市场抽查一行**，别默认 scopeList 就是事实——反过来也一样，`qte_mkt_cptl`/`shr_tot` 在 08-02 还是港/美无数据、08-03 就补上了，**否定结论同样会过期**。
 - **公司类型决定有没有这个科目**：财务科目分公司类型——银行有「存放同业」、券商有「客户资金存款」、保险有「预收保费」，一般企业没有。某指标对茅台返回 `null`（无此科目），换到对应类型证券（招行/中信/平安）就有数。
 - **日期路由**：
-  - 财务报表类（`bs_`/`is_`/`cf_`/`div_`/`shr_`，以及 description 明确按报告期统计的 `finc_`）→ 用**报告期末**（Q1 `2026-03-31`、年报 `2025-12-31`，无需是交易日）
+  - 财务报表类（`bs_`/`is_`/`cf_`/`div_`/`shr_`，以及 description 明确按报告期统计的 `finc_`）→ 多数用**报告期末**（Q1 `2026-03-31`、年报 `2025-12-31`，无需是交易日）。🔴 **但 `_ttm` 后缀是整族例外，必填 `tradeDate`**——`is_*_ttm` / `cf_*_ttm` / `div_cash_ttm` / `finc_*_ttm` 一律走交易日。**一眼验证**：在一个**非报告期末的普通交易日**（如 `2026-08-19`）直接 `--date` 取 `is_op_rev_ttm`，照样返真值（茅台 170152009062.43）；反过来给它传 `reportDate` 会报 `100003 不支持参数 reportDate; 缺少必填参数 tradeDate`。同族对照：普通 `is_op_rev` 只传 `--date` 则报「不支持参数 tradeDate; 缺少必填参数 reportDate」——**两者恰好相反**。**所以前缀只是提示，判据仍是上面 `--date` 那条：读 `parameterList` 里必填的是哪个，别按 code 前缀推断**
   - 日频估值类（如 `finc_pe_ttm` / `finc_pb_mrq`）→ 用最新已入库的**交易日**。⚠️ `finc_pb_mrq` 是**日频**的：任意交易日都有数且逐日变动（茅台 `07-31`=6.2325、`07-22`=6.0221、`06-30`=5.4706、`03-31`=7.0634；五粮液/宁德时代同样）。**别用季度末日期**——那会拿到几个月前的陈值（茅台季末 7.0634 比当日 6.2325 高 13.5%，估值指标上就是错数）。别因 code 都以 `finc_` 开头就一律套报告期末，按 `description`/实测区分
   - 现金流量表附注/间接法科目（多数 `cf_`）→ **只在年报/半年报披露**，季报日期取不到，改用年报日期 `2025-12-31`
   - 行情类（`qte_` 等）→ 用**交易日**，但常规行情仍应改走 `quote`
 - **混合日期语义要拆查询**：同时要“某报告期营收 / EPS”和“估值 PE / PB”时，按各自有效日期分别调用 `cross-section` 再按 `security` 合并（财务=报告期末、PE/PB=最新交易日）；不要把不同日期语义的指标塞进同一个 `--date`
-- **探索性取数**：缺值会保留行列并给占位单元格（含 1×1 的最简形态），但**占位值不统一**（多数 `null`、个别 `0`，见上）；code 写错会直接报 `100003`，不会伪装成缺值。看趋势用 `time-series` + 覆盖报告期的区间，但不能把缺值当成通过语义 / scope 校验。
+- **探索性取数**：缺值会保留行列并给占位单元格（含 1×1 的最简形态），占位值统一为 `null`；code 写错会直接报 `100003`，不会伪装成缺值。看趋势用 `time-series` + 覆盖报告期的区间，但不能把缺值当成通过语义 / scope 校验。
 - **名称反查 code 要核对，别取首条**：存在同显示名的兄弟指标——单季 `cf_finc_exp_qtr` 与累计 `cf_finc_exp` 都叫「财务费用」，`bs_fmt`/`cf_fmt`/`is_fmt` 都叫「报表格式」。`search` 按名称模糊匹配，目标 code 高概率在 top1 但不绝对，要看 `indicatorCode` 确认。
 - **批量查询做失败拆分**：某指标**缺必填参数**或入参错误时会整批报 `140002`，逐指标单查能定位是哪个指标缺参/不可查。留意 stderr 的「整列/整行被略过」警告——那不是报错，而是**有 code 没被服务端认出来**，先查拼写和证券后缀。
 - **市值量纲**：`qte_mkt_cptl`（总市值）与 `shr_tot`（总股本）**A/港/美股均有数**；**默认返原始「元」**（茅台 ≈ `1.7e12`，即 1.7 万亿），别误当天文数字。用 `scale` 数字码缩放（`0`元 / `3`千 / `4`万 / `6`百万 / `8`亿 / `9`十亿——`scale=8` → `16883` 亿元）、`currency` 换币种（**大写** `DFT`本币 / `CNY` / `HKD` / `USD` …）。**跨证券比市值前先统一 `scale`+`currency`**。
 - **币种与汇率**：`DFT`（原始币种）按市场识别——A股=CNY、港股行情=HKD、美股=USD；汇率换算自洽（互逆且三角一致）。⚠️ 但**同一只港股，行情类的原始币种是 HKD、财务类可能是 CNY**（如泡泡玛特财报以人民币计），跨市场比财务数据时显式传 `--currency CNY` 别依赖 `DFT`。另：财务类指标的汇率按**报告期**折算、行情类按查询日折算，两者隐含汇率会有细微差异，属正常口径差别。
-- **EDE 财务指标的 `reportType`（2026-08-01 裁决）**：`enumList` 的 label 已与实际取数**一致**，按 label 传即可。⚠️ 但同一份 `search` 响应里的 `paramDescription` 仍留着**相反的旧映射文字**——**以 `enumList` 和下方实测值为准，别读 `paramDescription`**：
+- **EDE 财务指标的 `reportType`**：`enumList` 的 label 与实际取数**一致**，按 label 传即可（取值以 `enumList` 为准）：
 
   | value | 口径 | 说明 |
   |-------|---------|------|
@@ -369,6 +422,6 @@ gangtise indicator cross-section --indicator scr_indu_citic --indicator scr_indu
 
 - **发现流程**：`indicator search --format json` → 核对 `indicatorName` + `description`、`scopeList`（含 `usageRestriction`）、`parameterList`（**参数名以此为准**）→ 三项都通过才用 `cross-section` / `time-series` / `screener`
 - **积分**：`search` 免费；`cross-section` / `time-series` / `screener` 按请求单元格数量计费，标价为每 100 单元格 A 股 0.05 / 港股 0.1 / 美股 0.2 积分，每次查询不足 100 单元格按 100 计
-- **空结果排查顺序**：2026-08-08 起真无数据会返回占位单元格（多数 `null`、个别指标 `0`）而不是空表，所以**空表基本等于「没有任何 code 被认出来」或参数名写错**。按序排查：① 证券代码与后缀对不对（美股 `.O`/`.N`，不是 `.US`）② 指标 code 拼写对不对 ③ 参数名对不对（`indicator search` 的 `parameterList`）④ 日期语义对不对（`tradeDate` vs `reportDate`）
+- **空结果排查顺序**：真无数据会返回占位单元格（统一 `null`）而不是空表，所以**空表基本等于「没有任何 code 被认出来」或参数名写错**。按序排查：① 证券代码与后缀对不对（美股 `.O`/`.N`，不是 `.US`）② 指标 code 拼写对不对 ③ 参数名对不对（`indicator search` 的 `parameterList`）④ 日期语义对不对（`tradeDate` vs `reportDate`——报告期类指标日期用错会整批返 `null`，看着像「没数据」）
 - **数据权限**：正式账号行情 / 财务 / 指标类可回溯的年限按服务等级而定，试用账号更短。⚠️ **同一账号下三个 EDE 接口的可查范围可能不一致**：出现过同一天、同一指标、同一证券在 `cross-section` 取得到、而 `screener` 报 `110003`（超出时间范围）的情况。**选股撞到 `110003` 时先别改日期格式**——用 `cross-section` 拉同一天的数据验证一下，能取到就说明是接口间范围差异，改用 `cross-section` 拉数再本地筛即可
 - 所有格式（table/json/jsonl/csv/markdown）均可用；导出宽表给 Excel 直接用 `--format csv --output xxx.csv`

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

@@ -34,7 +34,7 @@
 
 `新能源汽车` 那组里 `--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`。**
+⚠️ **`--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` 时两档结果一致**，这不是参数失效——没有关键词就无从计算相关度。
 
@@ -94,7 +94,7 @@ gangtise insight pamirs-summary download --summary-id <id> [--file-type <n>] [--
   - **不带筛选时经常整条为空**，用 `--category` 或 `--market` 过滤时回填率明显更高（这两个字段是绑定的：用任一过滤，两个都会有值）。有值时给的是该记录的**全部**值（多市场纪要按 `aShares` 过滤也回 `["aShares","hkStocks"]`，不是"回显过滤值"）
   - **所以别拉全量再本地分组**——会漏掉大量记录。要按类别/市场分组就逐个枚举值各查一遍再合并（请求数放大 2~4 倍），或直接让服务端筛
   - **反过来也别据此断言某条记录没有该属性**——标签为空只说明这次查询没回填，不代表该纪要真的没有概念/分类/市场归属
-  - `researchAreaList` 和 `securityList` 相对完整，抽样空值比例都在 10% 以内
+  - `researchAreaList` 和 `securityList` 的回填要完整得多，不受上面这条影响，可以直接用来做本地分组
 
 ```bash
 # 近一周的帕米尔纪要
@@ -144,7 +144,7 @@ gangtise insight performance-calendar download --performance-report-id <id> [--o
 - 只给 `--security`（不给日期/`--size`）时，CLI 额外套一个 **1000 行隐式上限**：单只证券的整段日历只有几十条，正常查询感知不到；万一服务端哪天不再按 `securityList` 过滤，结果会在 1000 行截断并标 `partial`（stderr 警告 + 退出码 3），而不是闷头翻完全表。判据是 `total`：只有「取满 1000 行且 total 显示还有更多」才告警——恰好 1000 行且 total=1000 是完整结果，退出码仍是 0。看到告警说明筛选**可能**没生效，改用日期范围重查
 - 返回字段：`performanceReportId`（下载用）/ `securityCodeList[]`（A+H 同时上市会有多个代码）/ `securityName` / `category` / `publishDate` / `title` / `hasAttachment`
 - 实测 `publishDate` 返回的是 `yyyy-MM-dd 00:00:00`（文档写 `yyyy-MM-dd`），取日期请截前 10 位
-- download：**只有 `hasAttachment: true` 的记录能下**（先 list 确认）；省略 `--output` 用真实标题命名（走 title-cache，未命中会回查 list 接口，那次回查按 0.1/条 计费——批量下载建议显式 `--output`）
+- download：**只有 `hasAttachment: true` 的记录能下**（先 list 确认）；省略 `--output` 用 title-cache 里的真实标题命名，**未命中不再自动回查**（v0.37.0 起），退回服务端文件名或 `<type>-<id>`。要回查加 `--resolve-title`——拉 200 条、按 0.1/条 约 20 积分，取回的标题会写回缓存供同批复用
 - **积分**：list 0.1/条；download A 股 10/篇、港美股 20/篇
 
 ## 研报 `insight research list/download`
@@ -216,8 +216,8 @@ gangtise insight foreign-opinion list [--rank-type <n>] [--security <code>] [--r
 ```
 
 - `--security`：境外证券代码，如 `UBER.N`
-- ⚠️ `--region`：`cn` | `cnHk` | `cnTw` | `us` | `jp` | `uk` | `gl`——**本端点上该过滤当前取不到数据**：除 `gl` 外的取值返回 `null` payload 而不是报错。需要按区域筛请不带该参数取回后按 `region` 字段本地筛。注意这是本端点的情况，`insight foreign-report` 的 `--region` 可正常收窄结果
-- ⚠️ `--industry`：**当前传任何值都拿不到数据**（中信码 / 申万码 / 乱码一样，不报错、退出码 0）。🔴 **返回的 payload 是字面 `null`，不是 `{total:0,list:[]}`** ——按空列表解析的脚本（`data.list.length`、`for row in data["list"]`）会在这里抛错或静默跳过，务必先判 `null`。需要按行业筛时不带该参数取回后本地按 `industryList[]` 筛
+- ⚠️ `--region`：**本端点只接受 6 个取值**——`cn` | `cnHk` | `cnTw` | `us` | `jp` | `uk`。`regionCategory` 常量表里另外 13 个（`sea` / `gl` / `fr` / `de` / `kr` / `in` / `ca` / `me` / `othAs` / `othEur` / `latAm` / `oce` / `af`）在这里一律报 `100005 枚举值非法`，**而它们在 `insight foreign-report` 上全部合法且能正常收窄**。要按这 13 个区域筛，只能用 `foreign-report`，或不带该参数取回后按 `region` 字段本地筛
+- ⚠️ `--industry`：**只认申万码**（`104xx0000`）。中信码报 `100005 枚举值非法`——即使 `reference constant-category` 把本端点列在 `citicIndustry` 的 `usageScopes` 里也一样。⚠️ **返回记录的 `industryList[]` 同时带两套码**（如 `100800122 中信非银` + `104490000 申万非银金融`），**回查时要挑申万那条**，拿中信码回查会报错
 - `--broker`：外资券商 ID（见 `references/lookup-ids.md`）
 - `--rating` / `--rating-change`：同研报
 - 返回字段：`foreignOpinionId` / `title` / `titleTranslate` / `content` / `contentTranslate` / `publishTime` / `publisher{brokerId, brokerName}` / `securityList[]{securityCode, rating, targetPrice, currency}` / `region`
@@ -230,7 +230,7 @@ gangtise insight independent-opinion download --independent-opinion-id <id> --fi
 ```
 
 - `--security`：境外证券代码，如 `GSK.N`
-- ⚠️ `--industry`：**当前传任何值都拿不到数据，且 payload 是字面 `null` 而非空 list**（同 foreign-opinion，注意事项见上），改用不带该参数取回后按 `industryList[]` 本地筛
+- ⚠️ `--industry`：**只认申万码**（`104xx0000`），中信码报 `100005 枚举值非法`（同 `foreign-opinion`，见上）。返回记录的 `industryList[]` 两套码都带，回查挑申万那条
 - `--rating` / `--rating-change`：同外资观点
 - `--file-type`（download **必选**）：`1` 原文 HTML | `2` 中文翻译 HTML
 - 返回字段：`independentOpinionId` / `title` / `titleTranslate` / `brief` / `briefTranslate` / `publishTime` / `analyst{analystId, analystName}` / `securityList[]` / `industryList[]`