gangtise-openapi-cli 0.31.0 → 0.32.0

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

@@ -3,7 +3,7 @@
 > 本组覆盖 `/application/open-indicator/*`：证券级**数据指标**的检索与取数，主要用于多证券批量取已实现财务 / 估值指标。即使能搜到收盘价、成交量等行情指标，常规行情与 K 线仍走免费的 `quote`。
 > 与 `alternative edb-*`（EDB 行业/宏观指标，无证券维度）是两套接口，别混。
 >
-> **取数前先 `indicator search` 拿 `indicatorCode` 和 `parameterList`**，绝不猜测指标编码或参数名——服务端调过参数名（`adjustmentType` → `adjustType`），传错名是**静默失效**不是报错。
+> **取数前先 `indicator search` 拿 `indicatorCode` 和 `parameterList`**，绝不猜测指标编码或参数名——参数名写错不会报错，而是按该参数的默认值取数，结果看着正常但口径不对。
 
 ## EDE 与专用接口的优先级
 
@@ -13,6 +13,7 @@
 | 多证券批量取一组**已实现**财务 / 估值指标 | 先 `indicator search`，通过下方三项校验后用 `cross-section` / `time-series` 一次拉取，避免逐只循环 |
 | A股盈利预测 / 一致预期（含预测 EPS） | `fundamental earning-forecast`；EDE 搜到的基本 / 稀释 EPS 是已实现值，不能替代预测 |
 | A股估值历史分位 | `fundamental valuation-analysis` |
+| **估值指标的历史序列**（分位 / 回测 / 择时） | 两个接口口径不同、都要交叉核——EDE 按正式财报披露日切换财报口径，`valuation-analysis` 按业绩快报切，见下方专门小节 |
 | 开高低收 / 成交量等行情与 K 线 | `quote`；免费且支持多证券批量 |
 | 单证券三大报表全部科目 | 对应 `fundamental` 利润表 / 资产负债表 / 现金流量表命令 |
 
@@ -30,8 +31,8 @@ gangtise indicator search --keyword <text> [--limit <n>]
 - 返回字段：`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[].usageRestriction`**：该指标在具体接口上的限制，`null` = 无限制。⚠️ **它是提示不是硬约束**——标着「不支持指标时间序列接口」的 `qte_vol_intvl` 实测调时序照样返数据、服务端不拦（2026-08-02）。当成「口径可能不对、结果别当真」看，别指望它会报错
-- ⚠️ **`scopeList` 是声明不是保证**：它可能**超前于数据**——`finc_pb_mrq` 声称覆盖 A股+港股，实测港股无数据（2026-08-03）。反过来也发生过：`qte_mkt_cptl`/`shr_tot` 在 08-02 时声称覆盖港/美股却无数据，08-03 数据补上了。缺数据的**表现形式由证券、指标两个维度共同决定**（详见下方「缺数据的四种形态」）：只有当这只证券在同批还有别的指标有数、**且**这个指标对同批还有别的证券有数时，才是 `null` 单元格；否则是整列 / 整行消失（退出码 3）或整表为空。所以「有 `null` 就说明覆盖了」是错的，批量前抽查一行
-- 美股代码用交易所后缀 `.O`(NASDAQ) / `.N`(NYSE)，**不是 `.US`**——实测 `AAPL.US` 查不到数据，须用 `AAPL.O`（官方示例里的 `AAPL.US` 是笔误）
+- ⚠️ **`scopeList` 是声明不是保证**：它可能**超前于数据**——`finc_pb_mrq` 声称覆盖 A股+港股，实测港股仍无数据（复测 2026-08-08）。反过来也发生过：`qte_mkt_cptl`/`shr_tot` 在 08-02 时声称覆盖港/美股却无数据，08-03 数据补上了。**2026-08-08 起判断成本降了**：无数据一律是 `null` 单元格（行列都保留），不再因「同批还查了什么」变成整列/整行消失，所以抽查一行就能直接看出覆盖情况（详见下方「缺数据 vs 代码写错」）
+- 美股代码用交易所后缀 `.O`(NASDAQ) / `.N`(NYSE)：用 `AAPL.O`，`AAPL.US` 取不到数据
 
 ```bash
 gangtise indicator search --keyword 营业收入 --limit 10 --format json   # 做语义 + scopeList + parameterList 三项校验
@@ -48,15 +49,15 @@ 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` 也必填，同理；那边曾另有一个「空 `parameters` 被丢弃」的服务端缺陷，2026-08-03 已修复，见下方缺陷表）
-  - ⚠️ **吃 `reportDate` 的指标必须显式传**：`--indicator-param "code:reportDate=2024-12-31"`。这类指标收到 `tradeDate` 会**静默返回空结果**（不报错，实测 `is_op_rev_mom`）。CLI 检测到你已为某指标传了 `tradeDate` 或 `reportDate` 就不再注入 `--date`
+  - `--date` 必填是 CLI 的**护栏**，不是协议要求：`cross-section` 本身接受 `indicatorParamList: []`（无参指标如 `pty_op_scope` 照常返值，实测 2026-08-02）。但绝大多数指标吃 `tradeDate`，漏传就是一张空表且退出码 0，所以宁可多带一个无害参数。（`screener` 的 `--date` 也必填，同理）
+  - 吃 `reportDate` 的指标可以显式传：`--indicator-param "code:reportDate=2024-12-31"`。这类指标**过去**收到 `tradeDate` 会静默返回空结果，**2026-08-08 复测已修复**——服务端会把 `tradeDate` 归一到所在报告期，`is_op_rev_mom` 两种传法都返 33.4903（@2026-03-31）。显式传 `reportDate` 仍是更稳的写法（语义明确、能扛回滚）。CLI 检测到你已为某指标传了 `tradeDate` 或 `reportDate` 就不再注入 `--date`
   - `sDate`（区间起始日）**不算**替代日期：它和 `tradeDate` 共存（`tradeDate` 是区间终点且 required），传了 `sDate` 后 `--date` 照常下发
 - `--currency`：币种 `DFT`(原始,默认)/`CNY`/`HKD`/`USD`/`EUR`/`GBP`/`JPY`/`TWD`/`MOP`/`AUD`（**大写**，2026-08-01 起服务端枚举已统一大写）
 - `--scale`：量纲 `0`(个,默认)/`3`(千)/`4`(万)/`6`(百万)/`8`(亿)/`9`(十亿)
-  - ⚠️ **根级 `--scale` 会污染不支持 scale 的指标**：`qte_close` 的 `parameterList` 里没有 `scale`，但根级 `--scale 8` 会把收盘价 1350.6 缩成 `0`（实测 2026-08-01，与文档「根级参数仅对支持的指标生效」不符）。价格类和金额类指标混查时，别用根级 `--scale`，改用 `--indicator-param "code:scale=8"` 只作用于该指标
+  - ✅ **根级 `--scale` 污染已修复**（2026-08-08 复测）：过去根级 `--scale 8` 会把不支持 scale 的 `qte_close` 收盘价缩成 `0`；现在只作用于支持该参数的指标——`qte_close` + `qte_mkt_cptl` 混查加 `--scale 8`，收盘价照旧 1309.22、总市值正确缩到 16366.3183（亿）。价格类和金额类可以放心混查了。要精确控制到单个指标仍可用 `--indicator-param "code:scale=8"`
 - **支持多指标 × 多证券**（单日横截面）
 - **输出（宽表）**：每行一只证券，列为 `security / name / <各指标名>…`。**没有 `date` 列**——查询日期现在挂在每个指标自己的参数上，各列可以是不同日期
-- **`--key-by name|code`**（默认 `name`）：指标列头用显示名还是 `indicatorCode`。**批量按 code 回填必用 `--key-by code`**——指标名会碰撞（多个指标同显示名，如 `cf_finc_exp`/`_qtr` 都叫「财务费用」）、服务端还会重排返回列序（实测请求 `qte_close,qte_vol` 回来是 `qte_vol,qte_close`），唯有 code 唯一且与顺序无关（行轴 `security` 本就是 code，`code` 模式整表可按 code 寻址，免去 raw API 手工回填）
+- **`--key-by name|code`**（默认 `name`）：指标列头用显示名还是 `indicatorCode`。**批量按 code 回填必用 `--key-by code`**——指标名会碰撞（多个指标同显示名，如 `cf_finc_exp`/`_qtr` 都叫「财务费用」），唯有 code 唯一（行轴 `security` 本就是 code，`code` 模式整表可按 code 寻址，免去 raw API 手工回填）。顺序本身现在是稳的（服务端曾随机重排），但**两个轴的排法不一样**，2026-08-08 复测：`indicatorList` **= 请求顺序**（请求 `qte_vol,qte_close` 就回 `qte_vol,qte_close`）；`securityCodeList` **是按代码升序重排的，不是请求顺序**（请求 `000858,600519,000001` → 回 `000001,000858,600519`，连跑 3 次一致）。所以**行序绝不能按请求下标对位**，一律按 `security` 字段取值
 
 ```bash
 # 多证券 × 同一报告期的已实现财务指标
@@ -78,6 +79,7 @@ gangtise indicator time-series --indicator <code> [--indicator <code2>] \
 
 - `--indicator` / `--security`：同上，但**只允许「多指标 × 单证券」或「单指标 × 多证券」**，不能两边都多个（要多 × 多用 `cross-section`，否则报 `100003`「仅支持多指标单证券或单指标多证券」）。**单指标时 `--security` 才能传板块 ID**；多指标时只能传一个证券代码、不得传板块 ID
 - `--start-date` / `--end-date`（**均必选**）：区间端点 `yyyy-MM-dd`。时序的时间范围由这两个参数统管，**不要**再用 `--indicator-param` 传 `tradeDate` 这类单日期参数
+- ⚠️ **同一 `indicatorCode` 挂多套参数：截面和时序都不支持，这是设计如此，要拆成两次调用**。只有 `screener` 支持（它把指标绑到不同变量 `F1`/`F2` 上，天然可区分）。CLI 也表达不了该请求——`--indicator-param` 按 code 建 Map，同 code 的多组参数会被合并成一组，与服务端设计一致。🔴 **但服务端的失败是静默的**：真发出去它会**取最后一组**、丢弃其余且不报错（raw 实测 `adjustType` `[2,3]` 返后复权 13609.6168、`[3,2]` 返前复权 1531.225，量级差 9 倍）。所以走 `raw call` 时务必自己保证同 code 不重复
 - `--calendar-type`：日期类型 `ND`(自然日)/`TD`(交易日,默认)/`WD`(工作日)。`TD` 且跨市场时，`date` 列是各市场交易日的**并集**
 - `--currency` / `--scale`：同 `cross-section`（含根级 `--scale` 的污染坑）
 - **输出（宽表）**：每行一个日期，列为 `date / <各序列名>…`；序列在「单指标」时是各**证券**，在「单证券多指标」时是各**指标**。**板块 ID 算多证券**——传 1 个 `sectorId` 服务端会展开成 N 只成分股，列就是这 N 只（实测中信白酒 → 19 列）
@@ -114,12 +116,21 @@ gangtise indicator screener --indicator <F1:code> [--indicator <F2:code2>] \
 - **输出（宽表）**：同 `cross-section`，每行一只**命中**的证券，列为 `security / name / <各指标名>…`；无命中返回空表
 - **积分**：与 `cross-section` 同价（按单元格计），但计费基数是**筛选前**的范围 × 指标数，别拿全市场板块随手试
 
-### 已知服务端缺陷（2026-08-03 复测，已报后台）
+### 同一指标绑多个变量：已可用（2026-08-08 修复）
 
-| 现象 | 影响 | 现在怎么办 |
-| :--- | :--- | :--- |
-| **同一 `indicatorCode` 绑到多个变量** → 整份结果不可信 | 服务端把这些绑定**全部按其中最早的那个日期**取数，该值落到它们的第一列、其余列 `null`（实测 `F1@07-31 + F2@07-30` → F1 列返回 07-30 的 1361.76，F1 自己的 1350.6 根本没出现）。所以**活下来的数字未必属于它标注的变量**；命中的证券集合同样不可信（针对 null 变量的条件等于没筛）；同一请求还有约 1/3 概率返回空集 | CLI 标 `unreliable: true` + `duplicatedIndicators` + **退出码 3**，并在 stderr 警告。**这类结果不能直接用于结论**，拆成两次 `cross-section` 再本地比 |
-| ~~`contains` / `notcontains` 需要指标带参数才生效~~ | 官方文档的招牌示例 `F3 contains '酒'`（`parameters: []`）曾 0 命中 | **✅ 2026-08-03 服务端已修复**，`parameters: []` 现可直接用。CLI 仍无条件下发 `--date`（对无参指标无害、能扛回滚），此行仅作记录 |
+把同一个 `indicatorCode` 绑到多个变量、各带不同参数，是**受支持的用法**——典型场景是「同一个价格的两个日期」做跨期比较：
+
+```bash
+# 茅台：08-07 收盘价 vs 08-06 收盘价，两列各自取到自己那天的值
+gangtise indicator screener --indicator F1:qte_close --indicator F2:qte_close \
+  --indicator-param "F1:tradeDate=2026-08-07" --indicator-param "F2:tradeDate=2026-08-06" \
+  --security 600519.SH --expression "F1 > F2" --date 2026-08-07
+# 日收盘价 (F1)=1309.22 / 日收盘价 (F2)=1308.55，与 time-series 对照一致
+```
+
+服务端**曾经**把这些绑定全部按其中最早的那个日期取数、值落到第一列其余置 `null`，还有约 1/3 概率返回空集，CLI 为此标过 `unreliable` + 退出码 3。**2026-08-08 复测已修复**（连跑 5 次值都正确且稳定），CLI 的 `unreliable` / `duplicatedIndicators` 标记与警告**已一并移除**——现在这类结果直接可用。列头会按变量加后缀区分（显示名相同）。
+
+> 同期修复的还有：`contains` / `notcontains` 曾要求指标带参数才生效（官方招牌示例 `F3 contains '酒'` 因 `parameters: []` 0 命中，2026-08-03 修复），以及运算符大小写敏感（`CONTAINS` 曾报语法错，2026-08-08 复测大写/混合大小写均正常，19 只全部命中）。
 
 ```bash
 # 文本筛选：白酒板块里经营范围含「酒」的公司
@@ -151,42 +162,45 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 ```
 
 - `adjustType`（复权方式）：`1`=不复权(默认) `2`=前复权 `3`=后复权 `4`=定点复权（配 `baseDate` 基期）
-  - ⚠️ **参数名是 `adjustType`，不是 `adjustmentType`**（官方文档示例写的 `adjustmentType` 是错的）。传错名服务端**静默忽略并退回不复权**——实测 `adjustmentType=3` 返回 1685.01（= 不复权），看着正常其实是错数据
+  - ⚠️ **参数名是 `adjustType`**（不是 `adjustmentType`）。写错名不会报错，会按默认值 `1`（不复权）取数——实测错名返回 1685.01、正确的 `adjustType=3` 返回 13609.6168，前者看着正常其实口径不对
   - 前复权以最新交易日为基准，所以在**最新交易日上前复权价 == 不复权价**；验证复权是否生效要用历史日期
 - 同一指标多个参数 → 重复 `--indicator-param "code:k1=v1" --indicator-param "code:k2=v2"`
-- **参数名与取值一律以 `indicator search --format json` 的 `parameterList` 为准**，不要照抄本文档或官方文档的示例名——服务端会调整参数名（`adjustmentType` → `adjustType` 就是一例），且传错名是静默失效而非报错。币种枚举 2026-08-01 起**统一大写**（`DFT`/`CNY`/`HKD`…），历史文档里的小写 `dft`/`cny` 已过时
+- **参数名与取值一律以 `indicator search --format json` 的 `parameterList` 为准**，不要照抄任何文档里的示例名——参数名会随版本调整，且写错是按默认值取数而非报错。币种枚举**统一大写**（`DFT`/`CNY`/`HKD`…），小写形式不生效
 - `--indicator-param` 与根级 `--currency`/`--scale` 冲突时，以 `--indicator-param` 为准
 
 ## 必填参数与错误码（取数前必读）
 
-**缺数据的四种形态（务必分清）**：
+**缺数据 vs 代码写错（2026-08-08 服务端改版，判据整个换了）**：
 
-| 缺的范围 | 服务端怎么返 | 后果 |
-| :--- | :--- | :--- |
-| **部分**缺（某证券的某指标） | 该单元格 `null`，行列都在 | 安全，一眼可见 |
-| 某指标对 universe 内**所有**证券都无数据 | 该指标**整列**从 `indicatorList` 消失 | CLI 标 `partial` + `omittedIndicators` + **退出码 3**；`--key-by code` 回填时该 key 根本不存在。**`screener` 按表达式布尔结构判**：缺列的变量视为无法求值，整个表达式再无可成立分支时 → **退出码 1 且不输出**；仍有分支可求值（如 `F1 || F2` 只缺 F1）→ `partial` + 退出码 3（见 screener 小节） |
-| 某证券对**所有**指标都无数据 | 该证券**整行**从 `securityCodeList` 消失 | CLI 标 `partial` + `omittedSecurities` + **退出码 3** |
-| 整个查询无数据 | `securityCodeList`/`values` 皆 `[]`（`Total: 0`），不再报 `999999` | **退出码 0**、不标 partial（什么都没被丢）。但 🔴 **参数写错也长这样**，stderr 会提醒这一歧义 |
+**缺数据一律是 `null` 单元格，行列都保留**，连单指标 × 单证券的 1×1 缺口也是 `null` 而不是空表。判据是**代码认不认识**，跟有没有数据无关：
 
-⚠️ 由 ②③ 与 ④ 的分界推出一个不直觉但自洽的结果：**同一个 scope 落空，单查是 0、混查是 3**——`finc_pb_mrq` 只查 `09992.HK` 时整体全空（退出 0），和 `600519.SH` 一起查时泡泡玛特整行被丢（退出 3 + `omittedSecurities`）。全空时没有任何证据能区分「无覆盖」和「无数据」，只有存在对照物时才有。**想确认某标的是否被某指标覆盖，就把它和一个已知有数的标的一起查。**
+| 情况 | 服务端怎么返 | CLI |
+| :--- | :--- | :--- |
+| 代码有效、但**无数据 / 无覆盖 / 非交易日 / 未来日期** | 单元格 `null`，行列都在 | **退出 0**，不标 partial |
+| **指标码无法解析**（拼错、不存在） | 该指标整列从 `indicatorList` 消失 | `partial` + `omittedIndicators` + **退出 3** |
+| **证券码无法解析**（拼错、后缀错，如 `AAPL.US`） | 该证券整行从 `securityCodeList` 消失 | `partial` + `omittedSecurities` + **退出 3** |
+| 请求里**没有任何**可解析的代码 | 四个数组全空（`Total: 0`） | **退出 0** + stderr 提示，因为无从判断是哪一轴写错了 |
 
-同一个覆盖缺口（`finc_pb_mrq` 无港股数据），会因**同批里还查了什么**而落进不同的档。2026-08-03 实测四种：
+2026-08-08 实测：
 
 | 查法 | 服务端返回 | CLI |
 | :--- | :--- | :--- |
-| `--indicator finc_pb_mrq --security 09992.HK` | 四个数组全空 | **退出 0**，不标 partial（第 ④ 档：什么都没被丢，就是没数据） |
-| 上面 + `--security 600519.SH` | 只回茅台 1 行，泡泡玛特整行消失 | **退出 3** + `partial` + `omittedSecurities: ["09992.HK"]`（第 ③ 档） |
-| `finc_pb_mrq` + `qte_close`，只查 `09992.HK` | 回 1 行，`indicatorList` 里没有 `finc_pb_mrq` | **退出 3** + `partial` + `omittedIndicators: ["finc_pb_mrq"]`（第 ② 档：`qte_close` 保住了这只证券，但 PB 对同批**每一只**证券都无数） |
-| `finc_pb_mrq` + `qte_close` × `600519.SH` + `09992.HK` | 回 2 行，泡泡玛特的 `市净率(MRQ)` 为 `null` | **退出 0**（第 ① 档：行由 `qte_close` 保住、列由茅台保住，缺口降级成单元格） |
+| `--indicator finc_pb_mrq --security 09992.HK`（港股无 PB 数据） | 1 行，`finc_pb_mrq: null` | **退出 0** |
+| `--indicator mgn_bal --security 00700.HK`（融资融券仅 A 股） | 1 行，`mgn_bal: null` | **退出 0** |
+| `--indicator qte_close --date 2027-01-04`（未来日期） | 1 行，`qte_close: null` | **退出 0** |
+| `--indicator qte_close --security AAPL.US --security AAPL.O` | 只回 `AAPL.O` | **退出 3** + `omittedSecurities: ["AAPL.US"]` |
+| `--indicator qte_close --indicator not_a_real_code` | 只回 `qte_close` 一列 | **退出 3** + `omittedIndicators: ["not_a_real_code"]` |
+| `--indicator not_a_real_code --security 999999.SH` | 全空 | **退出 0** + stderr 提示 |
 
-**判据是两个维度各自独立的，别只看一维**：
+**这是个净收益的变化**：`partial` / 退出码 3 从「这批数据不完整」变成了**「你有代码写错了」**——后者原本是完全静默的（退出 0、表看着正常、`--key-by code` 回填时 key 直接不存在）。反过来，真实的覆盖缺口现在一眼可见（就是 `null`），不再需要「和一个已知有数的标的一起查」这种对照法。
 
-- 单元格 `null` ⟺ 该**证券**在同批还有别的指标有数 **且** 该**指标**对同批还有别的证券有数
-- 整列消失 ⟺ 该指标对同批**所有**证券都无数
-- 整行消失 ⟺ 该证券对同批**所有**指标都无数
-- 整表为空 ⟺ 两者同时成立，即请求矩阵里**没有任何有数单元格**（单指标单证券的缺口是最简形态，多证券 × 多指标全缺同样如此）
+⚠️ **但这个检测需要同批里有对照物**：拼错的 code 必须和至少一个能解析的 code 同批，差集才算得出来。**整个轴都写错时（最常见的就是只查一个指标、而它拼错了）响应是空表、退出码 0**，只有 stderr 提示。所以「空表」现在的第一嫌疑就是拼写和后缀，不是没数据。
 
-所以「和一只有数的标的一起查就会变成 `null`」是错的——上表第 2 行正是反例：加了茅台，泡泡玛特那行照样整行消失，因为批次里只有 PB 这一个指标。**要把「整行消失」降级成 `null` 单元格，得加的是有覆盖的指标，不是有数据的证券。**标 `partial` 的那档会在 stderr 打印被略过的 code（`--format json` 下 stdout 仍是干净 JSON）。脚本按 `!= 0` 判失败的要注意：3 表示「有数据但不完整」，不是硬失败。
+`screener` 的缺列判据同理：变量绑的指标码认不出来 → 该列不返回 → 按表达式布尔结构判，整个表达式再无可成立分支 → **退出码 1 且不输出**；仍有分支可求值（如 `F1 || F2` 只缺 F1）→ `partial` + 退出码 3。
+
+⚠️ **退出码 1 那一档有个前提：服务端得先返回了命中行**。零命中时没有任何行需要被质疑，走的是「nothing matched」提示 + **退出码 0**——即使表达式里的变量整个求不了值也一样（实测 `F1:not_a_real_code` 单绑、以及 `F1 > 0 && F2 > 0` 其中 F2 无效，都是空集 + 退出 0）。所以**空集不能当成「条件成立但没标的符合」**，先核对指标码拼写。
+
+标 `partial` 的那档会在 stderr 打印被略过的 code（`--format json` 下 stdout 仍是干净 JSON）。脚本按 `!= 0` 判失败的要注意：3 表示「有数据但不完整」，不是硬失败。
 
 取数报错主要是这几个码：
 
@@ -195,7 +209,8 @@ 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 已恢复） | 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 三个接口不一致：截面 / 时序已放宽（本机到 2016-01-01），**`screener` 仍卡 today−3 年滚动**（实测 2023-08-07 报错、2023-08-08 通过；同日同指标同证券 `cross-section` 正常出数） | 把日期移进范围；`screener` 撞界时改用 `cross-section` 拉数再本地筛 |
 | `130001`（旧 `410004`） | 数据未找到，或**该指标无权限**（内层信封失败会带具体 msg，如"指标无权限"；此码被服务端复用） | 检查查询条件与指标权限；换证券/日期仍失败多为无权限，联系管理员开通 |
 
 ### 必填参数（`140002` 的根因）
@@ -205,25 +220,60 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 | 参数 | 适用指标 | 示例 |
 | :--- | :--- | :--- |
 | `periodNum` | N 期统计（N 期均值/最值，如 `finc_roe_avg_avg` 平均ROE N期均值） | `--indicator-param "finc_roe_avg_avg:periodNum=4"`；部分还需配**年报日期**才出数（实测 `finc_roe_avg_avg`@`2026-03-31` 空、@`2025-12-31` 有） |
-| `sDate` | 区间类的**起始日**（如 `qte_vol_intvl` 区间成交量、`qte_avg_vol` 区间日均成交量），格式 `yyyy-MM-dd` | `--indicator-param "qte_vol_intvl:sDate=2024-01-02"`。⚠️ **`sDate` 不能替代 `tradeDate`**——它是区间起点，`tradeDate`（=区间终点）仍是 required，`--date` 会照常下发。历史文档写的 `startDate=YYYYMMDD` 已不存在，传它是静默失效（茅台实测：错名 296 万 vs 正确 4673 万）。另：`qte_amp_mo`（月振幅）等周期变体现在只吃 `tradeDate`，没有起始日参数 |
+| `sDate` | 区间类的**起始日**（如 `qte_vol_intvl` 区间成交量、`qte_avg_vol` 区间日均成交量），格式 `yyyy-MM-dd` | `--indicator-param "qte_vol_intvl:sDate=2024-01-02"`。⚠️ **`sDate` 不能替代 `tradeDate`**——它是区间起点，`tradeDate`（=区间终点）仍是 required，`--date` 会照常下发。区间起始日的参数名是 `sDate`；写成 `startDate` 不存在、会被忽略（茅台实测：296 万 vs 正确 4673 万）。另：`qte_amp_mo`（月振幅）等周期变体现在只吃 `tradeDate`，没有起始日参数 |
 | `fiscalYear` | 年度/报告期类（如 `div_cash_yr` 年度现金分红） | `--indicator-param "div_cash_yr:fiscalYear=2025"` |
+| `industryType` + `industryLevel` | `scr_indu` 所属行业（两个都 required，缺任一报 `140002`） | `--indicator-param "scr_indu:industryType=1" --indicator-param "scr_indu:industryLevel=0"` |
 
 > `paramValue` 一律按**字符串**约定传（`periodNum=4` 内部即 `"4"`，CLI 已处理）。
 
+### 2026-08-07 新增指标
+
+**融资融券（21 个 `mgn_*`）**——`scopeList` 与实测都只有 **A 股**（港/美股返 `null`）：
+
+| 维度 | 当日 | 区间 |
+| :--- | :--- | :--- |
+| 两融合计 | `mgn_bal` 融资融券余额 | `mgn_bal_avg_intvl` 区间均值 |
+| 融资 | `mgn_fin_bal` 余额、`mgn_fin_buy` 买入额、`mgn_fin_repay` 偿还额 | `mgn_fin_bal_avg_intvl`、`mgn_fin_buy_intvl`、`mgn_fin_repay_intvl` |
+| 融券 | `mgn_sl_bal` 余额、`mgn_sl_qty` 余量、`mgn_sl_sell` 卖出额、`mgn_sl_sell_qty` 卖出量、`mgn_sl_repay` 偿还额、`mgn_sl_repay_qty` 偿还量 | `mgn_sl_bal_avg_intvl`、`mgn_sl_qty_avg_intvl`、`mgn_sl_sell_intvl`、`mgn_sl_sell_qty_intvl`、`mgn_sl_repay_intvl`、`mgn_sl_repay_qty_intvl` |
+| 标的资格 | `mgn_flag` 是否融资融券标的（字符串「是」/「否」，可用 `screener` 的 `contains` 筛） | — |
+
+```bash
+gangtise indicator cross-section --indicator mgn_bal --indicator mgn_fin_bal --indicator mgn_sl_bal \
+  --security 600519.SH --date 2026-08-07 --format table
+# 茅台 2026-08-07：两融 176.7 亿 / 融资 175.4 亿 / 融券 1.3 亿
+```
+
+**行业分类 `scr_indu`（所属行业）**——一个指标覆盖四套体系，A/港/美股均支持，返回**字符串**：
+
+- `industryType`：`1`=申万 `2`=中信 `3`=恒生 `4`=GICS
+- `industryLevel`：`0`=全路径（用 `-` 连接各级）`1`=一级 `2`=二级 `3`=三级 `4`=四级
+
+```bash
+gangtise indicator cross-section --indicator scr_indu \
+  --indicator-param "scr_indu:industryType=1" --indicator-param "scr_indu:industryLevel=0" \
+  --security 600519.SH --date 2026-08-07
+# 申万全路径「食品饮料-白酒Ⅱ-白酒Ⅲ」；industryType=2 → 中信「食品饮料-酒类-白酒」
+# 腾讯 + 恒生(3) → 「资讯科技业-软件服务-数码解决方案服务」；微软 + GICS(4) → 「信息技术-软件与服务-软件-系统软件」
+```
+
+体系与市场要配对：A 股查恒生 / GICS、美股查申万，都返 `null`（实测茅台 `industryType=3/4` 均为 `null`）。
+
+**`finc_pb_mrq`（市净率 MRQ）修复**：过去只在报告期末打值，现在每个交易日都返数据（2026-08-02 起复测逐日变动，08-08 仍然如此）。
+
 ## 取数最佳实践
 
 - **先 search 做三项校验**：看 `indicatorName` + `description` 确认语义和口径，看 `scopeList` 确认覆盖全部目标市场 / 证券类型（并看 `usageRestriction` 有无接口限制），再看 `parameterList` 补齐必填参数（required）并核对专属参数**名称**与枚举（`adjustType`/`scale`/`currency` 等）；任一不符就回退专用接口。**参数名以 search 返回为准，不要照抄文档示例**——服务端调过参数名，传错名是静默失效不是报错。
-- **`scopeList` 声称覆盖 ≠ 真有数**：截至 2026-08-03，`finc_pb_mrq` 的 `scopeList` 写着 A股+港股，实测港股无数据。它的表现按上面「缺数据的四种形态」走，由证券与指标**两个维度**共同决定：只查它 + 港股 → 整表为空（退出 0）；只加一只 A 股 → 港股仍整行消失（退出 3，批次里只有这一个指标）；只加一个有港股覆盖的指标 → PB 整列消失（退出 3）；两者都加 → 才降级成 `null` 单元格（退出 0）。跨市场批量取数后**逐市场抽查一行**，别默认 scopeList 就是事实——反过来也一样，`qte_mkt_cptl`/`shr_tot` 在 08-02 还是港/美无数据、08-03 就补上了，**否定结论同样会过期**。
+- **`scopeList` 声称覆盖 ≠ 真有数**：截至 2026-08-08，`finc_pb_mrq` 的 `scopeList` 写着 A股+港股，实测港股仍无数据。**2026-08-08 起这件事好查了**：无覆盖就是 `null` 单元格（行列都在，跟同批查了什么无关），抽查一行即可判定，不用再靠对照组反推。跨市场批量取数后**逐市场抽查一行**，别默认 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`，无需是交易日）
-  - 日频估值类（如 `finc_pe_ttm` / `finc_pb_mrq`）→ 用最新已入库的**交易日**。⚠️ **MRQ 口径已改**：`finc_pb_mrq` 过去只在报告期末打值、交易日取 `null`，2026-08-02 复测**任意交易日都有数且逐日变动**（茅台 `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`/实测区分
+  - 日频估值类（如 `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`
-- **探索性取数**：只有**部分**缺值才返回 `null` 且保留行列；整指标 / 整证券无数据是**整列 / 整行消失**，整个查询无数据是**空表**（不再报 `999999`）。看趋势用 `time-series` + 覆盖报告期的区间，但不能把缺值当成通过语义 / scope 校验。
+- **探索性取数**：缺值一律是 `null` 且保留行列（2026-08-08 起，含 1×1 的最简形态）；整列 / 整行消失现在只意味着**那个 code 服务端不认识**。看趋势用 `time-series` + 覆盖报告期的区间，但不能把缺值当成通过语义 / scope 校验。
 - **名称反查 code 要核对，别取首条**：存在同显示名的兄弟指标——单季 `cf_finc_exp_qtr` 与累计 `cf_finc_exp` 都叫「财务费用」，`bs_fmt`/`cf_fmt`/`is_fmt` 都叫「报表格式」。`search` 按名称模糊匹配，目标 code 高概率在 top1 但不绝对，要看 `indicatorCode` 确认。
-- **批量查询做失败拆分**：某指标**缺必填参数**或入参错误时会整批报 `140002`，逐指标单查能定位是哪个指标缺参/不可查。留意 stderr 的「整列/整行被略过」警告——那不是报错，但同样是这批数据不完整的信号。
+- **批量查询做失败拆分**：某指标**缺必填参数**或入参错误时会整批报 `140002`，逐指标单查能定位是哪个指标缺参/不可查。留意 stderr 的「整列/整行被略过」警告——那不是报错，而是**有 code 没被服务端认出来**，先查拼写和证券后缀。
 - **市值量纲（复测 2026-08-03）**：`qte_mkt_cptl`（总市值）与 `shr_tot`（总股本）**A/港/美股均已有数**（08-02 时港美股还是空的，服务端已补：泡泡玛特 2165.47 亿 / 腾讯 43207.64 亿 / 苹果 45128.55 亿）；**默认返原始「元」**（茅台 ≈ `1.7e12`，即 1.7 万亿），别误当天文数字。用 `scale` 数字码缩放（`0`元 / `3`千 / `4`万 / `6`百万 / `8`亿 / `9`十亿——`scale=8` → `16883` 亿元）、`currency` 换币种（**大写** `DFT`本币 / `CNY` / `HKD` / `USD` …）。**跨证券比市值前先统一 `scale`+`currency`**。
 - **币种与汇率（复测 2026-08-01，已修复）**：`DFT`（原始币种）识别正确——A股=CNY、港股行情=HKD、美股=USD；汇率换算自洽（互逆且三角一致，误差 <0.003%）。⚠️ 但**同一只港股，行情类的原始币种是 HKD、财务类可能是 CNY**（如泡泡玛特财报以人民币计），跨市场比财务数据时显式传 `--currency CNY` 别依赖 `DFT`。另：财务类指标的汇率按**报告期**折算、行情类按查询日折算，两者隐含汇率会有细微差异，属正常口径差别。
 - **EDE 财务指标的 `reportType`（2026-08-01 裁决）**：`enumList` 的 label 已与实际取数**一致**，按 label 传即可。⚠️ 但同一份 `search` 响应里的 `paramDescription` 仍留着**相反的旧映射文字**——**以 `enumList` 和下方实测值为准，别读 `paramDescription`**：
@@ -235,14 +285,28 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
   | `3` | **母公司报表** | |
   | `4` | **母公司报表（调整）** | 该报告期无重述数时为空 |
 
-  实测闭环（`is_tot_op_rev` + 中信证券 `600030.SH` FY2024 营业总收入，2026-08-01）：`1`→637.8922亿、`2`→581.19亿、`3`→321.924亿、`4`→321.924亿；与 `fundamental income-statement --security-code 600030.SH --fiscal-year 2024 --period annual` 返回的「合并报表」`totalOpRev = 63,789,215,688.23`（637.892亿）在 `1` 上完全吻合。取数值与 2026-07-24 的历史实测一致——**变的只是服务端 label，取数从未变过**。历史文档里「label 与 value 错位、按 label 传会取反」的警告已作废。
+  实测闭环（`is_tot_op_rev` + 中信证券 `600030.SH` FY2024 营业总收入，2026-08-01）：`1`→637.8922亿、`2`→581.19亿、`3`→321.924亿、`4`→321.924亿；与 `fundamental income-statement --security-code 600030.SH --fiscal-year 2024 --period annual` 返回的「合并报表」`totalOpRev = 63,789,215,688.23`（637.892亿）在 `1` 上完全吻合。取数值与 2026-07-24 的历史实测一致——**变的只是服务端 label，取数从未变过**。
 
   `2`/`4` 返回空值**不是枚举失效**，是该报告期尚无调整表（如最新年报 FY2025：`1`/`3` 有数、`2`/`4` 无值，与 `fundamental --report-type consolidatedRestated` 同期无数据一致）。港股默认口径同样是合并。
 
+## 估值指标的历史序列：两个接口口径不同，要交叉核
+
+| 接口 | 财报口径切换时点 |
+| :--- | :--- |
+| `indicator time-series`（EDE） | **正式财报披露日** |
+| `fundamental valuation-analysis` | **业绩快报**口径，通常更早 |
+
+两者都是点时口径，只是切换时机不同，同一天取到的估值指标可能不一样。**做估值分位 / 回测时两个接口都拉一遍交叉核**，尤其业绩大幅变动的标的——抽查中出现过个别标的在 `valuation-analysis` 侧长期未更新、估值明显偏低的情况。
+
+判别方法（**已验证的是 `finc_pe_ttm` / `peTtm`**）：用**总市值 ÷ PE 反推隐含净利润**，再对照利润表的滚动 TTM（= 上年全年 − 上年同期累计 + 本年累计），就能判出哪一侧用的是陈值。`finc_pb_mrq` 等非 TTM 口径的指标同样会在报告期节点变化，但分母是净资产（MRQ）不是 TTM，切换规则未单独验证——分叉时按同法反推净资产对照资产负债表。
+
+⚠️ **不要用 `fundamental income-statement` 的 `announcementDate` 做时点对齐**——实测该字段会把季报的披露日填成年报披露日。要真实披露日请查 `insight announcement list`。
+
+
 ## 通用说明
 
 - **发现流程**：`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 计
-- **空结果排查顺序**：整查询无数据现在返回空表而非报错，所以空表既可能是真无数据、也可能是参数写错。按序排查：① 参数名对不对（`indicator search` 的 `parameterList`）② 日期语义对不对（`tradeDate` vs `reportDate`）③ `scopeList` 覆不覆盖该市场 ④ 才考虑确实没数据
-- **数据权限**：试用账号默认可取近 3 年；正式账号按服务等级
+- **空结果排查顺序**：2026-08-08 起真无数据会返回 `null` 单元格而不是空表，所以**空表基本等于「没有任何 code 被认出来」或参数名写错**。按序排查：① 证券代码与后缀对不对（美股 `.O`/`.N`，不是 `.US`）② 指标 code 拼写对不对 ③ 参数名对不对（`indicator search` 的 `parameterList`）④ 日期语义对不对（`tradeDate` vs `reportDate`）
+- **数据权限**：2026-08-07 起正式账号行情 / 财务 / 指标类由前溯 3 年放宽到**前溯 5 年**；试用账号按服务等级。⚠️ **同一账号下三个 EDE 接口的范围可能不一致**：本机实测扩展权限只落到 `cross-section` / `time-series`，**`screener` 仍是 today−3 年滚动**（2026-08-08 实测边界 2023-08-08；同日同指标同证券截面取得到、选股报 `110003`）。选股撞界时改用 `cross-section` 拉数再本地筛
 - 所有格式（table/json/jsonl/csv/markdown）均可用；导出宽表给 Excel 直接用 `--format csv --output xxx.csv`

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

@@ -4,7 +4,21 @@
 
 时间格式：`"YYYY-MM-DD HH:mm:ss"`（datetime，需引号）。
 
-支持 `--rank-type` 的命令：opinion / summary / research / foreign-report / announcement / announcement-hk / announcement-us / foreign-opinion / independent-opinion / official-account。
+支持 `--rank-type` 的命令：opinion / summary / **pamirs-summary** / research / foreign-report / announcement / announcement-hk / announcement-us / foreign-opinion / independent-opinion / official-account。
+
+⚠️ **`--rank-type` 的效果同时依赖 `--keyword` 和 `--search-type`，而且强弱按端点不同**（2026-08-08 全量实测三个端点 × 两种 searchType）：
+
+下表三个端点是本次实测对象；**支持 `--rank-type` 的另外 8 个端点未验证**，别把结论外推过去。在这三个上，`--rank-type 2` 都是严格按 `publishTime` 倒序、稳定可依赖，差别全在 `1`（综合排序）上：
+
+| 端点 | `--search-type 1`（标题） | `--search-type 2`（全文） |
+| :--- | :--- | :--- |
+| `pamirs-summary` | 与 `2` **完全相同**（结果集无并列时间戳） | 🔴 **真正的相关度重排**——`rank1` 对 `publishTime`/`summaryTime` 都不单调，`rank2` 的首条在 `rank1` 里排到第 118 位 |
+| `summary` | 与 `2` 有差异，但 `rank1` **仍严格时间倒序**——差异只发生在时间戳并列处（`keyword=机器人` 前 200 条有 22 处并列） | 同左 |
+| `research` | 与 `2` **完全相同** | 有差异，同样只在并列处（4 处并列） |
+
+**没有 `--keyword` 时一律无差异**（综合排序无从计算），这不是参数失效。
+
+实用结论：**要"最相关"而不是"最新"，三个实测端点里只有 `pamirs-summary --search-type 2` 真能做到**；`summary` / `research` 的 `rank-type 1` 至多改变同一时间戳内几条的先后，别指望它能把更相关的旧内容提到前面。未验证的端点按 `summary` 的保守预期对待，需要时自己按「跨 `searchType` × 全量取回 × 比 `total` 再比序列」复测。
 **不支持** `--rank-type` 的命令：roadshow / site-visit / strategy / forum（API 无此参数）。
 
 `--rank-type`：`1` 综合排序（默认）| `2` 时间倒序
@@ -36,6 +50,42 @@ gangtise insight summary download --summary-id <id> [--file-type <n>] [--output
 - `--category`：`earningsCall` 业绩会 | `strategyMeeting` 策略会 | `fundRoadshow` 基金路演 | `shareholdersMeeting` 股东大会 | `maMeeting` 并购会议 | `specialMeeting` 特别会议 | `companyAnalysis` 公司分析 | `industryAnalysis` 行业分析 | `other`
 - `--file-type`（download 可选）：`1` 原始内容（默认）| `2` HTML 格式；**仅影响来源为会议平台的纪要**
 
+## 帕米尔纪要 `insight pamirs-summary list/download`
+
+```bash
+gangtise insight pamirs-summary list [--search-type <n>] [--rank-type <n>] [--research-area <id>] [--security <code>] [--category <name>] [--market <name>]
+gangtise insight pamirs-summary download --summary-id <id> [--file-type <n>] [--output <path>]
+```
+
+帕米尔（Pamirs）是平台内一个特殊牵头机构的**专家纪要库**，走独立端点，不是 `summary list` 的一个筛选项。⚠️ **需单独购买专家纪要数据库**，未购买调用报权限错误。**不限制历史数据范围**（不受 3 个月窗口约束）。
+
+- **筛选项比 `summary` 少**：没有 `--source` / `--institution` / `--participant-role`。服务端会静默丢弃不认识的 body 字段，所以别照搬 `summary` 的参数，那样只会拿到没过滤的全量
+- `--search-type`：`1` 标题搜索（默认）| `2` 全文搜索。实测 `--keyword PCB`：标题 36 条 vs 全文 113 条
+- `--rank-type`：`1` 综合排序（默认）| `2` 时间倒序。⚠️ 效果依赖 `--keyword`，详见本文开头的公共说明；本端点是该结论的实测对象之一
+- `--category`：`companyAnalysis` 公司分析 | `industryAnalysis` 行业分析（实测 2673 / 279）
+- `--market`：`aShares` | `hkStocks` | `usChinaConcept` | `usStocks`
+- `--research-area`：**citic（`1008001xx`）和申万（`104xx0000`）都生效**（实测食品饮料：citic 373 条 / 申万 145 条）——这点与多数 insight list 不同（那些的 `--research-area` 只吃 gangtise 码）
+- `--file-type`（download 可选）：`1` 原始文件（默认）| `2` HTML；**只有这两种**
+- 单页上限 50（CLI 按此翻页；服务端实测未执行该上限，传 100 会返 100），省略 `--size` 自动翻页拉全量。翻页完整性实测干净：三页无重复无缺口、可重放、`total` 不漂移
+- 返回字段：`summaryId` / `title` / `brief`（摘要）/ `summaryTime`（纪要注明的生成时间）/ `publishTime`（发布时间）/ `categoryList` / `securityList[]{securityCode, securityName}` / `researchAreaList[]{researchAreaId, researchAreaName}` / `conceptList[]{conceptId, conceptName}` / `marketList`
+- ⚠️ **标签字段大面积不回填**（2026-08-08 实测 6 种查法 × 30 条）：
+  - **`conceptList` 在所有查法下恒为空**（无过滤 / category / market / security / researchArea / keyword 全是 `[]`），而接口**没有** concept 过滤参数——所以**目前拿不到主题概念标签，没有变通办法**，别写依赖它的逻辑
+  - **`categoryList` 与 `marketList` 绑定在一起**：只要用 `--category` **或** `--market` 任一过滤，两个字段就都回填（30/30）；其余查法（含无过滤、`--security`、`--research-area`、`--keyword`）两个都是空。回填的是该记录的**全部**值（多市场纪要按 `aShares` 过滤也回 `["aShares","hkStocks"]`，不是"回显过滤值"）
+  - **所以别拉全量再本地分组**——标签会全丢。要按类别/市场分组就逐个枚举值各查一遍再合并（请求数放大 2~4 倍），或直接让服务端筛
+  - `researchAreaList`（抽 200 条 6% 空）和 `securityList`（10% 空）基本正常
+
+```bash
+# 近一周的帕米尔纪要
+gangtise insight pamirs-summary list --start-time 2026-08-01 --end-time 2026-08-07 --format table
+
+# 全文搜 + 时间倒序，只要前 20 条
+gangtise insight pamirs-summary list --keyword PCB --search-type 2 --rank-type 2 --size 20
+
+# 下载 HTML（省略 --output 自动用标题命名）
+gangtise insight pamirs-summary download --summary-id 5863771 --file-type 2
+# → PCB钻针：高端钻针扩产有壁垒，供需紧缺会持续到28年.html
+```
+
 ## 路演 / 调研 / 策略会 / 论坛
 
 ```bash

package/gangtise-openapi/references/commands/reference-and-lookup.md

@@ -96,7 +96,7 @@ gangtise reference constant-category [--format json]
 | category | 名称 | 结构 | 用于参数 |
 |----------|------|------|---------|
 | `citicIndustry` | 中信一级行业（30，`1008001xx`） | flat | `--industry` 全命令通用首选（见下方说明） |
-| `swIndustry` | 申万一级行业（31，`104xxx`） | flat | `--industry`（仅 6 个 insight list；wechat 静默忽略，见下方说明） |
+| `swIndustry` | 申万一级行业（31，`104xxx`） | flat | `--industry`（仅 6 个 insight list；`vault wechat-message-list` 的 `--industry` 当前两套码都不生效） |
 | `gangtiseIndustry` | Gangtise 行业（30 行业 `1008001xx` + 6 方向 `122000xxx`） | flat | `--research-area` 首选（含宏观/策略等方向，见下方说明） |
 | `domesticCity` | 国内城市（省级 ID） | flat | `--location`（roadshow / site-visit / strategy / forum）|
 | `aShareAnnouncementCategory` | A股公告分类 | tree（2 级） | `insight announcement --category` |
@@ -105,7 +105,7 @@ gangtise reference constant-category [--format json]
 | `regionCategory` | 区域分类 | flat | `insight foreign-report --region` |
 
 > **行业 / 研究方向过滤——选哪套 category（⭐ 权威口径，其他文件引用此处、勿重复枚举命令清单以免漂移；实测 + spec，2026-06-15）：**
-> - **`--industry`（industryList）→ 用 `citicIndustry`（`1008001xx`）**：opinion / research / foreign-report / foreign-opinion / independent-opinion / official-account / wechat-message 全部正确过滤。`swIndustry`（`104xxx`）在 6 个 insight list（含 official-account）上等效（spec 多数命令写 citic+sw），但 **`vault wechat-message-list` 只认中信码、传申万码会静默返回全量** → 统一用中信码最稳。
+> - **`--industry`（industryList）→ 用 `citicIndustry`（`1008001xx`）**：opinion / research / foreign-report / foreign-opinion / independent-opinion / official-account 正确过滤。⚠️ **`vault wechat-message-list` 例外——该命令的 `--industry` 当前两套码都不生效**（2026-08-08 复测，详见 `vault.md`）。`swIndustry`（`104xxx`）在 6 个 insight list（含 official-account）上等效（spec 多数命令写 citic+sw）→ 统一用中信码最稳。
 > - **`--research-area`（researchAreaList）→ 用 `gangtiseIndustry`**：完整研究方向分类 = 30 个行业（`1008001xx`，与 citicIndustry 相同）+ 6 个方向（宏观 `122000001` / 策略 `122000002` / 固收 `122000003` / 金工 `122000004` / 海外 `122000005` / 其他 `122000007`）。行业码与方向码均已实测正确过滤（opinion / summary / roadshow / site-visit / forum）。`citicIndustry` 也能用但只含行业、无方向；`swIndustry`（`104xxx`）除 summary / my-conference 外返 0，勿用。
 
 ## 常量值 `reference constant-list`
@@ -209,9 +209,9 @@ gangtise lookup meeting-org list          # 会议/牵头机构全量（--instit
 | 银行 / 银行股 | 银行 | `104480000` | `821047.SWI` |
 | 汽车 / 新车 | 汽车 | `104280000` | `821036.SWI` |
 
-> ¹ 第 3 列是**申万码**（`104xxx`），仅在 opinion / research / foreign-report / foreign-opinion / independent-opinion / official-account 这 6 个 insight list 上作 `--industry` 等效；`vault wechat-message-list` 会静默返回全量、`--research-area` 返 0——通用/推荐的**中信码**（`1008001xx`）见 `references/lookup-ids.md` 中信表或 `constant-list --category citicIndustry`。
+> ¹ 第 3 列是**申万码**（`104xxx`），仅在 opinion / research / foreign-report / foreign-opinion / independent-opinion / official-account 这 6 个 insight list 上作 `--industry` 等效；`--research-area` 返 0。`vault wechat-message-list` 的 `--industry` 与码表无关——**两套码都不生效**——通用/推荐的**中信码**（`1008001xx`）见 `references/lookup-ids.md` 中信表或 `constant-list --category citicIndustry`。
 
-> **参数名选择**：`--industry`（industryList，用 `citicIndustry` 码 `1008001xx`）用于 opinion / research / foreign-report / foreign-opinion / independent-opinion / official-account / wechat-message；`--research-area`（researchAreaList，用 `gangtiseIndustry` 码 = 行业 `1008001xx` + 方向 `122000xxx`）用于 opinion / summary / roadshow / site-visit / forum / my-conference；`--gts-code` 仅用于 `ai security-clue`（需申万格式 `821xxx.SWI`，不是数字 ID）。注意 strategy（线下策略会）无 `--research-area`，只按 `--institution` / `--location` 筛。
+> **参数名选择**：`--industry`（industryList，用 `citicIndustry` 码 `1008001xx`）用于 opinion / research / foreign-report / foreign-opinion / independent-opinion / official-account（`vault wechat-message-list` 也有这个参数，但**当前不生效**，见 `vault.md`）；`--research-area`（researchAreaList，用 `gangtiseIndustry` 码 = 行业 `1008001xx` + 方向 `122000xxx`）用于 opinion / summary / roadshow / site-visit / forum / my-conference；`--gts-code` 仅用于 `ai security-clue`（需申万格式 `821xxx.SWI`，不是数字 ID）。注意 strategy（线下策略会）无 `--research-area`，只按 `--institution` / `--location` 筛。
 
 > **"消费"歧义**：用户说"消费/大消费"覆盖多个子行业（食品饮料 `104340000` / 商贸零售 `104450000` / 社会服务 `104460000` / 家电 `104330000` / 纺织服饰 `104350000` / 美容护理 `104770000`），需向用户确认具体方向，或用 `--keyword 消费` 做宽泛搜索。
 

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

@@ -49,11 +49,11 @@ gangtise vault wechat-message-list [--keyword <text>] [--security <code>] [--wec
 
 - 数据权限：仅用户已绑定并激活群消息助理、且助理已入群的群消息
 - `--security`：按证券代码过滤（如 `000001.SZ`），可重复
-- `--industry`：行业 ID，**必须用中信码 `citicIndustry`（`1008001xx`）**；实测传申万码 `104xxx` 会被静默忽略、返回全量
+- `--industry`：⚠️ **本命令上该过滤当前不生效**（2026-08-08 复测：不传 / 中信码 `100800111` / 申万码 `104340000` / 乱码，四种都返回同一个 total）。中信码和申万码都不起作用，需要按行业收窄时改在本地按返回内容筛
 - `--wechat-group-id`：先用 `vault wechat-chatroom-list` 查；可重复
 - `--category`：`text` | `image` | `documents` | `url`（可重复）
 - `--tag`：`roadShow` | `research` | `strategyMeeting` | `meetingSummary` | `industryComment` | `companyComment` | `earningsReview`（可重复）
-- 返回字段（实测 2026-07-25）：`msgId` / **`content`**（正文）/ **`url`**（链接）/ `msgTime` / `wechatGroupId` / `wechatGroupName` / `speakerName` / `category` / `tagList[]{tagCode, tagName}` / `securityList[]{securityCode, securityName}` / `quoteMsg{quoteMsgId, quoteContent, quoteUrl}`。旧版本文档写作 `msgContent` / `contentUrl` 是错的，取值请用 `content` / `url`
+- 返回字段（实测 2026-07-25）：`msgId` / **`content`**（正文）/ **`url`**（链接）/ `msgTime` / `wechatGroupId` / `wechatGroupName` / `speakerName` / `category` / `tagList[]{tagCode, tagName}` / `securityList[]{securityCode, securityName}` / `quoteMsg{quoteMsgId, quoteContent, quoteUrl}`。正文取 `content`、链接取 `url`（不是 `msgContent` / `contentUrl`）
 - `quoteMsg`（2026-07-24 新增）：被引用的消息，无引用时为 `null`；`quoteContent` / `quoteUrl` 也可能为空。做上下文还原时用它把「回复」接回原消息
 - 未打标签/未关联证券的消息，`tagList` / `securityList` 返回 `null`（不是空数组）
 

package/gangtise-openapi/references/examples.md

@@ -248,14 +248,40 @@
        --security 600519.SH --security 000858.SZ --security 300750.SZ \
        --date 2025-12-31 --key-by code --format json
    b) 估值 PE + PB 同为日频，用同一个最新交易日即可（2026-08-02 复测 finc_pb_mrq
-      在任意交易日都有数；旧文档说它只在报告期末打值，照那样改用季末日期会拿到
-      几个月前的陈值）：
+      在任意交易日都有数；用季末日期会拿到几个月前的陈值）。
+      ⚠️ 要估值指标的历史序列做分位/回测，两个接口都拉一遍交叉核：EDE 按正式财报
+      披露日切换财报口径，fundamental valuation-analysis 按业绩快报切，同一天取到
+      的值可能不同（已验证 PE TTM；PB 是 MRQ 口径，规则未单独验证）。详见 indicator.md：
      gangtise indicator cross-section --indicator finc_pe_ttm --indicator finc_pb_mrq \
        --security 600519.SH --security 000858.SZ --security 300750.SZ \
        --date 2026-07-31 --key-by code --format json
 4. 按 security 合并两张宽表（列头即 indicatorCode，各取所需日期的值）；不要把不同日期语义的指标塞进同一个 --date。
 5. 计费：search 免费；两次取数各按请求单元格数量计费，每次不足 100 单元格按 100 计。
-6. 无数据分四档：**部分**缺 → 单元格 null 且行列都在；某指标对所有证券无数据 → 整列消失；某证券对所有指标无数据 → 整行消失（后两种 CLI 会标 partial + 退出码 3 并在 stderr 列出被略过的 code）；整查询无数据 → 空表（不再报 999999）。空表也可能是参数名/日期语义写错，先核对 parameterList、日期语义、scopeList 和公司类型。
+6. 无数据（无覆盖 / 非交易日 / 未来日期）一律是单元格 null 且行列都在，退出码 0。整列/整行消失现在只意味着那个 code 服务端不认识——指标码拼错，或证券后缀错（美股用 .O/.N，不是 .US），CLI 会标 partial + 退出码 3 并在 stderr 列出。空表则是「一个 code 都没认出来」或参数名写错，先核对代码后缀与 parameterList。
+```
+
+## 例 15b：帕米尔专家纪要（新库，筛选项与踩坑都和 summary 不同）
+
+**用户**："看看帕米尔最近有什么 PCB 相关的纪要" / "帕米尔纪要下载一篇"
+
+```
+1. 确认走的是帕米尔而不是普通纪要——两者是不同的库，pamirs 需单独购买专家纪要数据库。
+   用户没点名"帕米尔/Pamirs"就走 insight summary。
+2. 检索（全文 + 按相关度）：
+     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
+   - 筛选项比 summary 少：没有 --source / --institution / --participant-role
+3. 🔴 别拉全量再本地按类别/市场分组——服务端只在你用该字段过滤时才回填标签：
+   不带 --category 查，categoryList 100% 是空数组；conceptList 任何查法都是空。
+   要分组就让服务端筛：
+     gangtise insight pamirs-summary list --category industryAnalysis --market aShares --size 50
+4. 下载（省略 --output 自动用标题命名）：
+     gangtise insight pamirs-summary download --summary-id 5863771 --file-type 2
+     → PCB钻针：高端钻针扩产有壁垒，供需紧缺会持续到28年.html
+   --file-type 只有 1（原始）/ 2（HTML）两种
+5. 数据范围不限历史；单价未公布，大批量前先小量试。
 ```
 
 ## 例 16：A 股资金流向（个股 vs 全市场按日分片）

package/gangtise-openapi/references/lookup-ids.md

@@ -6,7 +6,7 @@
 
 ## 中信行业分类（--industry 参数）
 
-完整列表用 `reference constant-list --category citicIndustry`。**`--industry` 全命令通用首选用这套（`1008001xx`）**——opinion / research / foreign-report / foreign-opinion / independent-opinion / wechat-message 都正确过滤；这套 ID 同时也是 `--research-area` 的行业部分（见下方研究方向）。
+完整列表用 `reference constant-list --category citicIndustry`。**`--industry` 全命令通用首选用这套（`1008001xx`）**——opinion / research / foreign-report / foreign-opinion / independent-opinion 都正确过滤（⚠️ `vault wechat-message-list` 例外，该命令的 `--industry` 当前两套码都不生效）；这套 ID 同时也是 `--research-area` 的行业部分（见下方研究方向）。
 
 | ID | 行业 | ID | 行业 |
 |----|------|----|------|
@@ -30,7 +30,7 @@
 
 ## 申万行业（--industry 参数）
 
-完整列表用 `reference constant-list --category swIndustry`。⚠️ 申万码（`104xxx`）只在**部分** insight list 上作 `--industry` 等效、**不能用于 `--research-area`（返 0）**、`vault wechat-message-list` 会**静默返全量**——哪套码用于哪些命令的**权威口径见 `references/commands/reference-and-lookup.md`「行业 / 研究方向过滤——选哪套 category」**，勿在此重复枚举。拿不准就统一用上方中信码。
+完整列表用 `reference constant-list --category swIndustry`。⚠️ 申万码（`104xxx`）只在**部分** insight list 上作 `--industry` 等效、**不能用于 `--research-area`（返 0）**；`vault wechat-message-list` 的 `--industry` **两套码都不生效**（连不存在的码也返全量，该过滤整个被忽略）——哪套码用于哪些命令的**权威口径见 `references/commands/reference-and-lookup.md`「行业 / 研究方向过滤——选哪套 category」**，勿在此重复枚举。拿不准就统一用上方中信码。
 
 | ID | 行业 | ID | 行业 | ID | 行业 |
 |----|------|----|------|----|------|

package/gangtise-openapi/references/response-schema.md

@@ -4,7 +4,7 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 
 > 例外：`indicator`（EDE）四个接口（`search` / `cross-section` / `time-series` / `screener`）成功时**双层信封**（`data` 里再裹一层 `{code, status, data}`）。内层字段名 2026-08-01 起为 `securityCodeList` / `securityNameList` / `indicatorList[{code,name,dataType}]`（screener 另带 `field`），`values` 是 2D 矩阵：**截面与 screener 为 `[证券][指标]`**（该版转置过，此前是 `[指标][证券]`）、时序仍为 `[序列][日期]`。
 >
-> 缺数据分四档：**部分**缺 → 单元格 `null`；某指标对所有证券都无数据 → 该指标**整列**从 `indicatorList` 消失；某证券对所有指标都无数据 → 该证券**整行**从 `securityCodeList` 消失；整查询无数据 → 全空数组。CLI 的 `indicator` 子命令已二次解包、拍平成宽表，并在整列/整行被略过时标 `partial` + `omittedIndicators`/`omittedSecurities` + 退出码 3。**`screener` 例外**：把缺列的变量当作无法求值，按表达式的**布尔结构**判断是否还有分支能成立（`A && B` 要两边、`A || B` 只要一边）。一条都不剩 → **退出码 1 且不输出**（那些行以「通过了该条件」的名义呈现，而条件根本无法证明被执行过）；仍有分支可求值、或缺的只是输出用的辅助变量 → `partial` + 退出码 3。重复绑定同一指标另标 `unreliable` + `duplicatedIndicators` + 退出码 3；直接 `raw call indicator.*` 只会剥外层，内层与缺数据形态需自行处理。
+> **缺数据 vs 代码写错**（2026-08-08 实测）：无数据 / 无覆盖一律是单元格 `null`，行列都保留。仍会整列 / 整行消失的只有**服务端解析不了的 code**——指标 code 拼错，或证券 code 后缀错（美股是 `.O`/`.N`，`AAPL.US` 会整行消失）。请求里没有任何可解析 code 时才是全空数组。CLI 的 `indicator` 子命令已二次解包、拍平成宽表，并在整列/整行被略过时标 `partial` + `omittedIndicators`/`omittedSecurities` + 退出码 3——**这个信号现在读作「有 code 写错了」**。**`screener` 例外**：把缺列的变量当作无法求值，按表达式的**布尔结构**判断是否还有分支能成立（`A && B` 要两边、`A || B` 只要一边）。一条都不剩 → **退出码 1 且不输出**（那些行以「通过了该条件」的名义呈现，而条件根本无法证明被执行过）；仍有分支可求值、或缺的只是输出用的辅助变量 → `partial` + 退出码 3。直接 `raw call indicator.*` 只会剥外层，内层需自行处理。
 
 ## 通用模式（5 类）
 
@@ -23,6 +23,8 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | insight opinion list | `{list, total}` | `list[].id` / `list[].title` / `list[].publishDate` / `list[].chiefName` / `list[].securityCode` / `list[].institutionName` |
 | insight summary list | `{list, total}` | `list[].summaryId` / `list[].title` / `list[].publishTime` |
 | insight summary download | 文件路径（stdout） | — |
+| insight pamirs-summary list | `{list, total}` | `list[].summaryId` / `list[].title` / `list[].brief` / `list[].summaryTime`（纪要生成时间）/ `list[].publishTime`（发布时间）/ `list[].securityList[]{securityCode, securityName}` / `list[].researchAreaList[]{researchAreaId, researchAreaName}` / `list[].conceptList[]{conceptId, conceptName}` / `list[].categoryList` / `list[].marketList`。⚠️ 标签字段大面积不回填：`conceptList` **在所有查法下恒为空**（接口也没有 concept 过滤参数，拿不到）；`categoryList` 与 `marketList` **只在用 `--category` 或 `--market` 任一过滤时才回填**（两者绑定，一起有或一起没有）。拉全量再本地分组会丢标签 |
+| insight pamirs-summary download | 文件路径（stdout） | — |
 | insight roadshow / site-visit / strategy / forum list | `{list, total}` | `list[].id` / `list[].title` / `list[].publishTime` / `list[].institution.institutionName` |
 | insight research list | `{list, total}` | `list[].reportId` / `list[].title` / `list[].brief`（全文摘要） / `list[].publishTime` / `list[].publisher.brokerName` / `list[].securityList[].rating` |
 | insight research download | 文件路径（stdout） | — |
@@ -78,7 +80,7 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | vault record-download | 文件路径（stdout） | — |
 | vault my-conference-list | `{list, total}` | `list[].conferenceId` / `list[].title` / `list[].category` / `list[].institution.institutionName` / `list[].publishTime` |
 | vault my-conference-download | 文件路径（stdout） | — |
-| vault wechat-message-list | `{list, total}` | `list[].msgId` / `list[].content`（正文）/ `list[].url` / `list[].msgTime` / `list[].wechatGroupName` / `list[].speakerName` / `list[].category` / `list[].tagList[].tagCode` / `list[].securityList[].securityCode` / `list[].quoteMsg.quoteContent`（引用消息，无引用为 `null`）。**不是 `msgContent`/`contentUrl`**（旧文档笔误，实测 2026-07-25） |
+| vault wechat-message-list | `{list, total}` | `list[].msgId` / `list[].content`（正文）/ `list[].url` / `list[].msgTime` / `list[].wechatGroupName` / `list[].speakerName` / `list[].category` / `list[].tagList[].tagCode` / `list[].securityList[].securityCode` / `list[].quoteMsg.quoteContent`（引用消息，无引用为 `null`）。**字段名是 `content` / `url`**，不是 `msgContent` / `contentUrl`（实测 2026-07-25） |
 | vault wechat-chatroom-list | `{list, total}` | `list[].chatroomName` / `list[].chatroomId` |
 | alternative edb-search | `{list: [...]}` 指标列表 | `indicatorId` / `indicatorName` / `dataSource` / `frequency` / `unit` |
 | alternative edb-data | 列表，每行 `{date, <indicatorId>: value, ...}` 宽表 | `date` + 每个 `--indicator-id` 一列（该日指标值） |

package/package.json

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