gangtise-openapi-cli 0.32.0 → 0.34.0

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

@@ -30,8 +30,8 @@ gangtise indicator search --keyword <text> [--limit <n>]
 - 默认 `--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[].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 数据补上了。**2026-08-08 起判断成本降了**：无数据一律是 `null` 单元格（行列都保留），不再因「同批还查了什么」变成整列/整行消失，所以抽查一行就能直接看出覆盖情况（详见下方「缺数据 vs 代码写错」）
+- **`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 代码写错」）
 - 美股代码用交易所后缀 `.O`(NASDAQ) / `.N`(NYSE)：用 `AAPL.O`，`AAPL.US` 取不到数据
 
 ```bash
@@ -50,14 +50,14 @@ gangtise indicator cross-section --indicator <code> [--indicator <code2>] \
 - `--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` 也必填，同理）
-  - 吃 `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`
+  - 🔴 **吃 `reportDate` 的指标必须显式传 `reportDate`**：`--indicator-param "code:reportDate=2024-12-31"`。**2026-08-15 起服务端不再接受 `tradeDate`**——只给 `--date` 会报 `100003「指标 xxx 不支持参数 tradeDate; 指标 xxx 缺少必填参数 reportDate」`（此前一版会把 `tradeDate` 归一到所在报告期，现已改为报错）。哪些指标属于这一类看 `indicator search` 的 `parameterList`：`reportDate` 标 `required: true` 且列表里没有 `tradeDate` 的就是。利润表 / 资产负债表 / 现金流量表类（`is_*` 等）都在此列；行情与估值类（`qte_*` / `finc_*`）仍用 `--date` 即可。CLI 检测到你已为某指标传了 `tradeDate` 或 `reportDate` 就不再注入 `--date`，所以补上 `--indicator-param` 就能正常取数
   - `sDate`（区间起始日）**不算**替代日期：它和 `tradeDate` 共存（`tradeDate` 是区间终点且 required），传了 `sDate` 后 `--date` 照常下发
 - `--currency`：币种 `DFT`(原始,默认)/`CNY`/`HKD`/`USD`/`EUR`/`GBP`/`JPY`/`TWD`/`MOP`/`AUD`（**大写**，2026-08-01 起服务端枚举已统一大写）
 - `--scale`：量纲 `0`(个,默认)/`3`(千)/`4`(万)/`6`(百万)/`8`(亿)/`9`(十亿)
-  - ✅ **根级 `--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"`
+  - 根级 `--scale` **只作用于支持该参数的指标**：`qte_close` + `qte_mkt_cptl` 混查加 `--scale 8`，收盘价保持原值、总市值按亿缩放，价格类与金额类可以放心混查。要精确控制到单个指标用 `--indicator-param "code:scale=8"`
 - **支持多指标 × 多证券**（单日横截面）
 - **输出（宽表）**：每行一只证券，列为 `security / name / <各指标名>…`。**没有 `date` 列**——查询日期现在挂在每个指标自己的参数上，各列可以是不同日期
-- **`--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` 字段取值
+- **`--key-by name|code`**（默认 `name`）：指标列头用显示名还是 `indicatorCode`。**批量按 code 回填必用 `--key-by code`**——指标名会碰撞（多个指标同显示名，如 `cf_finc_exp`/`_qtr` 都叫「财务费用」），唯有 code 唯一（行轴 `security` 本就是 code，`code` 模式整表可按 code 寻址，免去 raw API 手工回填）。顺序是稳定的，但**两个轴的排法不一样**：`indicatorList` **= 请求顺序**（请求 `qte_vol,qte_close` 就回 `qte_vol,qte_close`）；`securityCodeList` **是按代码升序重排的，不是请求顺序**（请求 `000858,600519,000001` → 回 `000001,000858,600519`）。所以**行序绝不能按请求下标对位**，一律按 `security` 字段取值
 
 ```bash
 # 多证券 × 同一报告期的已实现财务指标
@@ -79,12 +79,12 @@ 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 不重复
+- ⚠️ **同一 `indicatorCode` 挂多套参数：截面和时序都不支持，这是设计如此，要拆成两次调用**。只有 `screener` 支持（它把指标绑到不同变量 `F1`/`F2` 上，天然可区分）。CLI 也表达不了该请求——`--indicator-param` 按 code 建 Map，同 code 的多组参数会被合并成一组，与服务端设计一致。走 `raw call` 真发出去会报 `100003「指标 xxx 重复配置」`（2026-08-15 实测；此前一版是静默取最后一组）
 - `--calendar-type`：日期类型 `ND`(自然日)/`TD`(交易日,默认)/`WD`(工作日)。`TD` 且跨市场时，`date` 列是各市场交易日的**并集**
 - `--currency` / `--scale`：同 `cross-section`（含根级 `--scale` 的污染坑）
 - **输出（宽表）**：每行一个日期，列为 `date / <各序列名>…`；序列在「单指标」时是各**证券**，在「单证券多指标」时是各**指标**。**板块 ID 算多证券**——传 1 个 `sectorId` 服务端会展开成 N 只成分股，列就是这 N 只（实测中信白酒 → 19 列）
 - **`--key-by name|code`**（默认 `name`）：同 `cross-section`；`code` 模式下单证券列=各 `indicatorCode`、多证券列=各 `securityCode`，批量按 code 回填用它
-- ⚠️ 部分指标标注**不支持时序接口**：`search` 返回的 `scopeList[].usageRestriction` 会写明（如「不支持指标时间序列接口」），`null` 表示无限制。**但它不是硬约束**——实测 `qte_vol_intvl` 带着该标注调时序照样返回数据，服务端不拦。把它当"口径可能不对、结果别当真"的提示，而不是"会报错"的保证
+- ⚠️ 部分指标标注**不支持时序接口**：`search` 返回的 `scopeList[].usageRestriction` 会写明（如「不支持指标时间序列接口」），`null` 表示无限制。**但它不是硬约束**——实测 `qte_vol_intvl` 带着该标注调时序照样返回数据，不会被拦下。把它当"口径可能不对、结果别当真"的提示，而不是"会报错"的保证
 
 ```bash
 # 单个已实现估值指标 × 多证券：列 = 证券
@@ -128,9 +128,9 @@ gangtise indicator screener --indicator F1:qte_close --indicator F2:qte_close \
 # 日收盘价 (F1)=1309.22 / 日收盘价 (F2)=1308.55，与 time-series 对照一致
 ```
 
-服务端**曾经**把这些绑定全部按其中最早的那个日期取数、值落到第一列其余置 `null`，还有约 1/3 概率返回空集，CLI 为此标过 `unreliable` + 退出码 3。**2026-08-08 复测已修复**（连跑 5 次值都正确且稳定），CLI 的 `unreliable` / `duplicatedIndicators` 标记与警告**已一并移除**——现在这类结果直接可用。列头会按变量加后缀区分（显示名相同）。
+同一指标绑到多个变量（各带不同参数）是 `screener` 支持的用法，结果直接可用；列头会按变量加后缀区分（显示名相同）。
 
-> 同期修复的还有：`contains` / `notcontains` 曾要求指标带参数才生效（官方招牌示例 `F3 contains '酒'` 因 `parameters: []` 0 命中，2026-08-03 修复），以及运算符大小写敏感（`CONTAINS` 曾报语法错，2026-08-08 复测大写/混合大小写均正常，19 只全部命中）。
+> `contains` / `notcontains` 对大小写不敏感（`CONTAINS` / `contains` / 混合写法等价）。
 
 ```bash
 # 文本筛选：白酒板块里经营范围含「酒」的公司
@@ -162,43 +162,61 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 ```
 
 - `adjustType`（复权方式）：`1`=不复权(默认) `2`=前复权 `3`=后复权 `4`=定点复权（配 `baseDate` 基期）
-  - ⚠️ **参数名是 `adjustType`**（不是 `adjustmentType`）。写错名不会报错，会按默认值 `1`（不复权）取数——实测错名返回 1685.01、正确的 `adjustType=3` 返回 13609.6168，前者看着正常其实口径不对
+  - ⚠️ **参数名是 `adjustType`**（不是 `adjustmentType`）。写错名会报 `100003` 并指出是哪个指标的哪个参数，按报错改即可
   - 前复权以最新交易日为基准，所以在**最新交易日上前复权价 == 不复权价**；验证复权是否生效要用历史日期
 - 同一指标多个参数 → 重复 `--indicator-param "code:k1=v1" --indicator-param "code:k2=v2"`
-- **参数名与取值一律以 `indicator search --format json` 的 `parameterList` 为准**，不要照抄任何文档里的示例名——参数名会随版本调整，且写错是按默认值取数而非报错。币种枚举**统一大写**（`DFT`/`CNY`/`HKD`…），小写形式不生效
+- **参数名与取值一律以 `indicator search --format json` 的 `parameterList` 为准**，不要照抄任何文档里的示例名——参数名会随版本调整。写错会报 `100003` 并指出是哪个指标的哪个参数（2026-08-15 起；此前是静默按默认值取数），按报错改即可。币种枚举**统一大写**（`DFT`/`CNY`/`HKD`…），小写形式不生效
 - `--indicator-param` 与根级 `--currency`/`--scale` 冲突时，以 `--indicator-param` 为准
 
 ## 必填参数与错误码（取数前必读）
 
 **缺数据 vs 代码写错（2026-08-08 服务端改版，判据整个换了）**：
 
-**缺数据一律是 `null` 单元格，行列都保留**，连单指标 × 单证券的 1×1 缺口也是 `null` 而不是空表。判据是**代码认不认识**，跟有没有数据无关：
+**缺数据一律保留行列并给一个占位单元格**，连单指标 × 单证券的 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 股）：
+>
+> | 表达式 | 非报告期末日期 | 报告期末日期 |
+> | :--- | :--- | :--- |
+> | `F1 > 0` | **命中 0 只** | 命中 3 只 |
+> | `F1 < 50亿` | **命中 3 只**（值全是 `0`） | 命中 1 只 |
+>
+> 只换了日期，两个条件的结果全部反转，全程不报错。「扣非净利 > 0 筛出空集」会被读成「没有盈利的股票」。
+>
+> **时序上更难躲**：报告期类指标按日返回，只有报告期末那几行是真值，其余是占位。`is_op_rev` 的 `null` 通常被聚合跳过、均值仍然对；`is_dnrpnp` 的 `0` 会被算进去——茅台 5 个月 104 行里 102 行是 `0`，整列求均值比正确值低 50 倍以上。而**时序没有任何参数能让它只返回报告期末**（传 `tradeDate`/`reportDate` 都会被拒）。
+>
+> **怎么办**：① 报告期类指标一律把日期落在**报告期末**（`2025-03-31` / `06-30` / `09-30` / `12-31`）；② 拿 `is_dnrpnp` 这类做筛选或聚合前，先单查一次确认不是占位；③ **别对时序整列直接求均值 / 求和**，先按报告期末取子集。
 
 | 情况 | 服务端怎么返 | CLI |
 | :--- | :--- | :--- |
-| 代码有效、但**无数据 / 无覆盖 / 非交易日 / 未来日期** | 单元格 `null`，行列都在 | **退出 0**，不标 partial |
-| **指标码无法解析**（拼错、不存在） | 该指标整列从 `indicatorList` 消失 | `partial` + `omittedIndicators` + **退出 3** |
-| **证券码无法解析**（拼错、后缀错，如 `AAPL.US`） | 该证券整行从 `securityCodeList` 消失 | `partial` + `omittedSecurities` + **退出 3** |
-| 请求里**没有任何**可解析的代码 | 四个数组全空（`Total: 0`） | **退出 0** + stderr 提示，因为无从判断是哪一轴写错了 |
+| 代码有效、但**无数据 / 无覆盖 / 非交易日 / 未来日期** | 占位单元格（多数 `null`，个别指标 `0`，见上），行列都在 | **退出 0**，不标 partial |
+| **指标码无法解析**（拼错、不存在） | `100003「指标 xxx 不存在」` | **退出 1**，报错 |
+| **证券码无法解析**（拼错、后缀错，如 `AAPL.US`） | `100003「xxx 不是有效证券或者板块ID」` | **退出 1**，报错 |
+| **参数名写错 / 同 code 重复配置** | `100003` 并指名参数 / 「重复配置」 | **退出 1**，报错 |
 
-2026-08-08 实测：
+2026-08-15 实测：
 
-| 查法 | 服务端返回 | CLI |
-| :--- | :--- | :--- |
-| `--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 提示 |
+| 查法 | 服务端返回 |
+| :--- | :--- |
+| `--indicator finc_pb_mrq --security 09992.HK`（港股无 PB 数据） | 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 不存在` ← 同样报错 |
+| `--indicator qte_close --security 999999.SH` | `100003 999999.SH 不是有效证券或者板块ID` |
+
+**代码写错现在一律报错、且消息里带上那个代码**，无论同批有没有别的正确代码——不用再靠「和一个已知有数的标的一起查」推断是哪个写错了。**所以「空表」的含义变干净了：它现在基本只意味着真的没数据**（此前空表既可能是没数据、也可能是整个轴写错）。
 
-**这是个净收益的变化**：`partial` / 退出码 3 从「这批数据不完整」变成了**「你有代码写错了」**——后者原本是完全静默的（退出 0、表看着正常、`--key-by code` 回填时 key 直接不存在）。反过来，真实的覆盖缺口现在一眼可见（就是 `null`），不再需要「和一个已知有数的标的一起查」这种对照法。
+⚠️ **唯一还需要对照法的是占位值那一档**：占位**多数是 `null`、个别是 `0`**（见上方 🔴 段），`0` 长得和真值一样。拿 `is_dnrpnp` 这类做筛选或聚合前，仍要和已知有数的标的一起查做对照。
 
-⚠️ **但这个检测需要同批里有对照物**：拼错的 code 必须和至少一个能解析的 code 同批，差集才算得出来。**整个轴都写错时（最常见的就是只查一个指标、而它拼错了）响应是空表、退出码 0**，只有 stderr 提示。所以「空表」现在的第一嫌疑就是拼写和后缀，不是没数据。
+> CLI 侧仍保留 `partial` + `omittedIndicators` / `omittedSecurities` + 退出码 3 的差集检测，但在当前服务端行为下基本收不到样本（错代码在服务端就被拒了）。留着是为了万一服务端回退时还有兜底，不影响正常使用。
 
-`screener` 的缺列判据同理：变量绑的指标码认不出来 → 该列不返回 → 按表达式布尔结构判，整个表达式再无可成立分支 → **退出码 1 且不输出**；仍有分支可求值（如 `F1 || F2` 只缺 F1）→ `partial` + 退出码 3。
+`screener` 上指标码写错同样直接报 `100003`，不会再走到「缺列」那条路。CLI 的缺列判据（按表达式布尔结构判，整个表达式再无可成立分支 → 退出码 1 且不输出；仍有分支可求值如 `F1 || F2` 只缺 F1 → `partial` + 退出码 3）保留作兜底。
 
-⚠️ **退出码 1 那一档有个前提：服务端得先返回了命中行**。零命中时没有任何行需要被质疑，走的是「nothing matched」提示 + **退出码 0**——即使表达式里的变量整个求不了值也一样（实测 `F1:not_a_real_code` 单绑、以及 `F1 > 0 && F2 > 0` 其中 F2 无效，都是空集 + 退出 0）。所以**空集不能当成「条件成立但没标的符合」**，先核对指标码拼写。
+⚠️ **`screener` 的空集仍要当心，但原因变了**：现在空集基本只有两种来源——**真的没有标的满足条件**，或者**某个变量的值是占位 `0`**（`F1 > 0` 在 `is_dnrpnp` 全是占位 `0` 时必然筛出空集，见上方 🔴 段）。指标码拼错已不在其列（会直接报错）。
 
 标 `partial` 的那档会在 stderr 打印被略过的 code（`--format json` 下 stdout 仍是干净 JSON）。脚本按 `!= 0` 判失败的要注意：3 表示「有数据但不完整」，不是硬失败。
 
@@ -209,8 +227,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 已恢复）。⚠️ 别把它和空表混为一谈：无数据现在是 `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` 拉数再本地筛 |
+| `999999` | 系统故障。2026-08-01 起「无数据」不再用此码，所以它基本只剩真故障（2026-07-26 曾出现 EDE 取数端全线 999999，08-01 已恢复）。⚠️ 别把它和空表混为一谈：无数据现在是占位单元格（多数 `null`、个别指标 `0`），空表表示整轴 code 未识别 | CLI 对 indicator 端点**不重试此码**（v0.27.0）；确认参数无误仍报错就是服务端问题 |
+| `110003` | **超出账号数据权限的时间范围**。⚠️ EDE 三个接口的可查范围可能不一致：出现过同日同指标同证券 `cross-section` 正常出数、而 `screener` 报此码 | 把日期移进范围；`screener` 撞界时先用 `cross-section` 查同一天验证，能取到就改用它拉数再本地筛 |
 | `130001`（旧 `410004`） | 数据未找到，或**该指标无权限**（内层信封失败会带具体 msg，如"指标无权限"；此码被服务端复用） | 检查查询条件与指标权限；换证券/日期仍失败多为无权限，联系管理员开通 |
 
 ### 必填参数（`140002` 的根因）
@@ -220,7 +238,7 @@ 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` 会照常下发。区间起始日的参数名是 `sDate`；写成 `startDate` 不存在、会被忽略（茅台实测：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` 会报 `100003 不支持参数 startDate`（2026-08-15 起；此前是被静默忽略、套用默认区间返回一个合理但错误的数）。⚠️ **不传 `sDate` 不报错**——它是可选参数，缺了就按默认区间算，所以要的是特定区间就必须显式传。另：`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"` |
 
@@ -258,12 +276,27 @@ gangtise indicator cross-section --indicator scr_indu \
 
 体系与市场要配对：A 股查恒生 / GICS、美股查申万，都返 `null`（实测茅台 `industryType=3/4` 均为 `null`）。
 
-**`finc_pb_mrq`（市净率 MRQ）修复**：过去只在报告期末打值，现在每个交易日都返数据（2026-08-02 起复测逐日变动，08-08 仍然如此）。
+**行业组合指标（2026-08-14 新增，3 个）**——把体系写进指标编码，省掉 `industryType`：
+
+| 指标 | 体系 | 参数 |
+| :-- | :-- | :-- |
+| `scr_indu_citic` | 中信行业 | `tradeDate`（必填）+ `industryLevel`（**可选**） |
+| `scr_indu_sw` | 申万行业 | 同上 |
+| `scr_indu_gics` | GICS 行业 | 同上 |
+
+```bash
+gangtise indicator cross-section --indicator scr_indu_citic --indicator scr_indu_sw \
+  --security 600519.SH --date 2026-08-13
+```
+
+与 `scr_indu` 的取舍：**只要一套体系就用组合指标**（少一个必填参数，且 `industryLevel` 可省），**要在同一次请求里横比多套体系**才用 `scr_indu`（换 `industryType` 即可，不必记三个编码）。恒生体系没有组合指标，仍走 `scr_indu:industryType=3`。
+
+**`finc_pb_mrq`（市净率 MRQ）是日频指标**：每个交易日都有数且逐日变动，别按报告期末取（那会拿到几个月前的陈值）。
 
 ## 取数最佳实践
 
 - **先 search 做三项校验**：看 `indicatorName` + `description` 确认语义和口径，看 `scopeList` 确认覆盖全部目标市场 / 证券类型（并看 `usageRestriction` 有无接口限制），再看 `parameterList` 补齐必填参数（required）并核对专属参数**名称**与枚举（`adjustType`/`scale`/`currency` 等）；任一不符就回退专用接口。**参数名以 search 返回为准，不要照抄文档示例**——服务端调过参数名，传错名是静默失效不是报错。
-- **`scopeList` 声称覆盖 ≠ 真有数**：截至 2026-08-08，`finc_pb_mrq` 的 `scopeList` 写着 A股+港股，实测港股仍无数据。**2026-08-08 起这件事好查了**：无覆盖就是 `null` 单元格（行列都在，跟同批查了什么无关），抽查一行即可判定，不用再靠对照组反推。跨市场批量取数后**逐市场抽查一行**，别默认 scopeList 就是事实——反过来也一样，`qte_mkt_cptl`/`shr_tot` 在 08-02 还是港/美无数据、08-03 就补上了，**否定结论同样会过期**。
+- **`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 就补上了，**否定结论同样会过期**。
 - **公司类型决定有没有这个科目**：财务科目分公司类型——银行有「存放同业」、券商有「客户资金存款」、保险有「预收保费」，一般企业没有。某指标对茅台返回 `null`（无此科目），换到对应类型证券（招行/中信/平安）就有数。
 - **日期路由**：
   - 财务报表类（`bs_`/`is_`/`cf_`/`div_`/`shr_`，以及 description 明确按报告期统计的 `finc_`）→ 用**报告期末**（Q1 `2026-03-31`、年报 `2025-12-31`，无需是交易日）
@@ -271,11 +304,11 @@ gangtise indicator cross-section --indicator scr_indu \
   - 现金流量表附注/间接法科目（多数 `cf_`）→ **只在年报/半年报披露**，季报日期取不到，改用年报日期 `2025-12-31`
   - 行情类（`qte_` 等）→ 用**交易日**，但常规行情仍应改走 `quote`
 - **混合日期语义要拆查询**：同时要“某报告期营收 / EPS”和“估值 PE / PB”时，按各自有效日期分别调用 `cross-section` 再按 `security` 合并（财务=报告期末、PE/PB=最新交易日）；不要把不同日期语义的指标塞进同一个 `--date`
-- **探索性取数**：缺值一律是 `null` 且保留行列（2026-08-08 起，含 1×1 的最简形态）；整列 / 整行消失现在只意味着**那个 code 服务端不认识**。看趋势用 `time-series` + 覆盖报告期的区间，但不能把缺值当成通过语义 / scope 校验。
+- **探索性取数**：缺值会保留行列并给占位单元格（含 1×1 的最简形态），但**占位值不统一**（多数 `null`、个别 `0`，见上）；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 没被服务端认出来**，先查拼写和证券后缀。
-- **市值量纲（复测 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`。另：财务类指标的汇率按**报告期**折算、行情类按查询日折算，两者隐含汇率会有细微差异，属正常口径差别。
+- **市值量纲**：`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`**：
 
   | value | 口径 | 说明 |
@@ -291,6 +324,16 @@ gangtise indicator cross-section --indicator scr_indu \
 
 ## 估值指标的历史序列：两个接口口径不同，要交叉核
 
+> 🔴 **对照前先避开这个陷阱：两个接口在非交易日的行为不一样。**
+>
+> | 日期 | EDE `finc_pe_ttm` | `fundamental valuation-analysis` |
+> | :-- | :-- | :-- |
+> | 2026-08-07（周五） | 23.1374 | 23.1374 |
+> | **2026-08-08（周六）** | **`null`** | **23.1374**（顺延上一交易日） |
+>
+> 拿非交易日做对照，会看到「EDE 全是 null、对照组搭不起来」，很容易误判成 EDE 没有这些数据——**其实只是它不给非交易日补值，而 `valuation-analysis` 补**。做交叉核对时**日期一律落在交易日上**；已经撞上的，换一个交易日重跑再下结论。
+
+
 | 接口 | 财报口径切换时点 |
 | :--- | :--- |
 | `indicator time-series`（EDE） | **正式财报披露日** |
@@ -300,13 +343,13 @@ gangtise indicator cross-section --indicator scr_indu \
 
 判别方法（**已验证的是 `finc_pe_ttm` / `peTtm`**）：用**总市值 ÷ PE 反推隐含净利润**，再对照利润表的滚动 TTM（= 上年全年 − 上年同期累计 + 本年累计），就能判出哪一侧用的是陈值。`finc_pb_mrq` 等非 TTM 口径的指标同样会在报告期节点变化，但分母是净资产（MRQ）不是 TTM，切换规则未单独验证——分叉时按同法反推净资产对照资产负债表。
 
-⚠️ **不要用 `fundamental income-statement` 的 `announcementDate` 做时点对齐**——实测该字段会把季报的披露日填成年报披露日。要真实披露日请查 `insight announcement list`。
+⚠️ **不要用 `fundamental income-statement` 的 `announcementDate` 做时点对齐**——它在部分证券上各期取值相同。**改用同一响应里的 `earliestAnncDate`（首次公告日）**；要交叉核实披露日就查 `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 计
-- **空结果排查顺序**：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` 拉数再本地筛
+- **空结果排查顺序**：2026-08-08 起真无数据会返回占位单元格（多数 `null`、个别指标 `0`）而不是空表，所以**空表基本等于「没有任何 code 被认出来」或参数名写错**。按序排查：① 证券代码与后缀对不对（美股 `.O`/`.N`，不是 `.US`）② 指标 code 拼写对不对 ③ 参数名对不对（`indicator search` 的 `parameterList`）④ 日期语义对不对（`tradeDate` vs `reportDate`）
+- **数据权限**：正式账号行情 / 财务 / 指标类可回溯的年限按服务等级而定，试用账号更短。⚠️ **同一账号下三个 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

@@ -6,19 +6,18 @@
 
 支持 `--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` 的效果依赖 `--keyword`**：没有关键词时综合排序无从计算，两种取值结果一致，这不是参数失效。
 
-下表三个端点是本次实测对象；**支持 `--rank-type` 的另外 8 个端点未验证**，别把结论外推过去。在这三个上，`--rank-type 2` 都是严格按 `publishTime` 倒序、稳定可依赖，差别全在 `1`（综合排序）上：
+**`--rank-type 1`（综合排序，默认）按相关度挑选条目**，`--rank-type 2` 严格按 `publishTime` 倒序取最新的。两者从同一结果集里取的是**不同的子集**，不是同一批内容换个排法：
 
-| 端点 | `--search-type 1`（标题） | `--search-type 2`（全文） |
-| :--- | :--- | :--- |
-| `pamirs-summary` | 与 `2` **完全相同**（结果集无并列时间戳） | 🔴 **真正的相关度重排**——`rank1` 对 `publishTime`/`summaryTime` 都不单调，`rank2` 的首条在 `rank1` 里排到第 118 位 |
-| `summary` | 与 `2` 有差异，但 `rank1` **仍严格时间倒序**——差异只发生在时间戳并列处（`keyword=机器人` 前 200 条有 22 处并列） | 同左 |
-| `research` | 与 `2` **完全相同** | 有差异，同样只在并列处（4 处并列） |
+| 想要 | 用 |
+| :--- | :--- |
+| 最相关的内容（可以是旧的） | `--rank-type 1` + `--keyword` + `--search-type 2`（全文） |
+| 最新的内容（按时间铺） | `--rank-type 2` |
 
-**没有 `--keyword` 时一律无差异**（综合排序无从计算），这不是参数失效。
+同一个查询下，`--rank-type 1` 取回的条目时间跨度更宽（每天只挑相关度高的几条），`--rank-type 2` 则集中在最近几天（把最新的逐条铺出来）。
 
-实用结论：**要"最相关"而不是"最新"，三个实测端点里只有 `pamirs-summary --search-type 2` 真能做到**；`summary` / `research` 的 `rank-type 1` 至多改变同一时间戳内几条的先后，别指望它能把更相关的旧内容提到前面。未验证的端点按 `summary` 的保守预期对待，需要时自己按「跨 `searchType` × 全量取回 × 比 `total` 再比序列」复测。
+⚠️ **别用「返回结果是不是按时间倒序」判断综合排序有没有生效** —— `--rank-type 1` **挑完之后仍按时间倒序排列**，所以两种取值下返回序列都是时间单调的。要看差别就**比条目 ID 集合**，不是比排序。
 **不支持** `--rank-type` 的命令：roadshow / site-visit / strategy / forum（API 无此参数）。
 
 `--rank-type`：`1` 综合排序（默认）| `2` 时间倒序
@@ -33,7 +32,7 @@ gangtise insight opinion list [--keyword <text>] [--research-area <id>] [--chief
 
 - `--llm-tag`：`strongRcmd` 强烈推荐 | `earningsReview` 业绩点评 | `topBroker` 头部券商 | `newFortune` 新财富团队
 - `--source`：`realTime` 实时 | `openSource` 开放来源
-- `--industry`：用 `citicIndustry` 码 `1008001xx`（申万码 `104xxx` 也等效）；`--research-area`：用 `gangtiseIndustry` 码（行业 `1008001xx` + 方向 `122000xxx`，申万码返 0）。详见 `reference-and-lookup.md`
+- `--industry`：用 `citicIndustry` 码 `1008001xx`；申万码 `104xx0000` 也生效，但**两套码的行业成分不同、取回的结果集不一致**（同一行业实测相差约 5%），同一批查询别混用。`--research-area`：行业用 `citicIndustry` 码 `1008001xx`、方向用 `gangtiseIndustry` 码 `122000xxx`，**申万码在本端点返 0**。详见 `reference-and-lookup.md`
 
 ## 纪要 `insight summary list/download`
 
@@ -44,7 +43,7 @@ gangtise insight summary download --summary-id <id> [--file-type <n>] [--output
 
 - `--search-type`：`1` 标题搜索（默认，速度快）| `2` 全文搜索
 - `--source`：`1` 实时 | `2` 开放来源
-- `--research-area`：用 `gangtiseIndustry` 码（行业 `1008001xx` + 方向 `122000xxx`）；summary 的 spec 额外接受 citic/sw，但统一用 gangtise 最稳
+- `--research-area`：行业用 `citicIndustry` 码 `1008001xx`、方向用 `gangtiseIndustry` 码 `122000xxx`。summary 是少数**申万码 `104xx0000` 也生效**的端点，但两套行业码取到的集合略有出入（同一行业实测相差约 2%），同一批查询里别混用
 - `--market`：`aShares` | `hkStocks` | `usChinaConcept` | `usStocks`
 - `--participant-role`：`management` 管理层 | `expert` 专家
 - `--category`：`earningsCall` 业绩会 | `strategyMeeting` 策略会 | `fundRoadshow` 基金路演 | `shareholdersMeeting` 股东大会 | `maMeeting` 并购会议 | `specialMeeting` 特别会议 | `companyAnalysis` 公司分析 | `industryAnalysis` 行业分析 | `other`
@@ -57,22 +56,24 @@ gangtise insight pamirs-summary list [--search-type <n>] [--rank-type <n>] [--re
 gangtise insight pamirs-summary download --summary-id <id> [--file-type <n>] [--output <path>]
 ```
 
-帕米尔（Pamirs）是平台内一个特殊牵头机构的**专家纪要库**，走独立端点，不是 `summary list` 的一个筛选项。⚠️ **需单独购买专家纪要数据库**，未购买调用报权限错误。**不限制历史数据范围**（不受 3 个月窗口约束）。
+帕米尔（Pamirs）是平台内一个特殊牵头机构的**专家纪要库**，走独立端点，不是 `summary list` 的一个筛选项。⚠️ **需单独购买专家纪要数据库**：未开通时 `list` 直接报 `999004`（不是返回空列表），**整库拿不到**。**不限制历史数据范围**（不受 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）
+> 未开通该库时任何查询都直接报 `999004`，不必怀疑参数写错。下面各参数的行为描述来自已开通账号的实测。
+
+- **筛选项比 `summary` 少**：没有 `--source` / `--institution` / `--participant-role`。不认识的 body 字段会被丢弃且不报错，所以别照搬 `summary` 的参数，那样只会拿到没过滤的全量
+- `--search-type`：`1` 标题搜索（默认）| `2` 全文搜索。同一关键词全文搜索的命中数明显多于标题搜索
+- `--rank-type`：`1` 综合排序（默认）| `2` 时间倒序。⚠️ 效果依赖 `--keyword`，详见本文开头的公共说明
+- `--category`：`companyAnalysis` 公司分析 | `industryAnalysis` 行业分析（两者过滤均生效，公司分析占绝大多数）
 - `--market`：`aShares` | `hkStocks` | `usChinaConcept` | `usStocks`
-- `--research-area`：**citic（`1008001xx`）和申万（`104xx0000`）都生效**（实测食品饮料：citic 373 条 / 申万 145 条）——这点与多数 insight list 不同（那些的 `--research-area` 只吃 gangtise 码）
+- `--research-area`：**行业码两套都生效**——citic `1008001xx` 和申万 `104xx0000`。申万码这点与多数 insight list 不同（那些只有 summary 认申万码）。⚠️ 反过来，**方向码 `122000xxx` 在本端点返 0**，别在这里传方向
 - `--file-type`（download 可选）：`1` 原始文件（默认）| `2` HTML；**只有这两种**
-- 单页上限 50（CLI 按此翻页；服务端实测未执行该上限，传 100 会返 100），省略 `--size` 自动翻页拉全量。翻页完整性实测干净：三页无重复无缺口、可重放、`total` 不漂移
+- 单页上限：spec 写 50，实际传更大的 `size` 也会照数返回。**CLI 仍按 50 翻页**——保守值在上限某天开始执行时不会被静默截断。省略 `--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% 空）基本正常
+- ⚠️ **`conceptList` / `categoryList` / `marketList` 三个标签字段稀疏，且是否有值随记录和查法而变**：
+  - **不带筛选时经常整条为空**，用 `--category` 或 `--market` 过滤时回填率明显更高（这两个字段是绑定的：用任一过滤，两个都会有值）。有值时给的是该记录的**全部**值（多市场纪要按 `aShares` 过滤也回 `["aShares","hkStocks"]`，不是"回显过滤值"）
+  - **所以别拉全量再本地分组**——会漏掉大量记录。要按类别/市场分组就逐个枚举值各查一遍再合并（请求数放大 2~4 倍），或直接让服务端筛
+  - **反过来也别据此断言某条记录没有该属性**——标签为空只说明这次查询没回填，不代表该纪要真的没有概念/分类/市场归属
+  - `researchAreaList` 和 `securityList` 相对完整，抽样空值比例都在 10% 以内
 
 ```bash
 # 近一周的帕米尔纪要
@@ -104,7 +105,7 @@ gangtise insight forum list      [--research-area <id>] [--location <id>]
 - `--participant-role`（仅路演）：`management` | `expert`
 - `--permission`（路演/调研）：`1` 公开 | `2` 私密
 - `--market`：路演 `aShares`｜`hkStocks`｜`usChinaConcept`｜`usStocks`；调研 `aShares`｜`hkStocks`｜`usChinaConcept`（无 usStocks）
-- `--research-area`（路演/调研/论坛）：用 `gangtiseIndustry` 码（行业 `1008001xx` + 方向 `122000xxx`，见 `reference-and-lookup.md`）。**strategy 无 `--research-area`，只按 `--institution`/`--location` 筛**
+- `--research-area`（路演/调研/论坛）：行业用 `citicIndustry` 码 `1008001xx`、方向用 `gangtiseIndustry` 码 `122000xxx`，**申万码 `104xx0000` 在这三个端点返 0**（见 `reference-and-lookup.md`）。**strategy 无 `--research-area`，只按 `--institution`/`--location` 筛**
 
 ## 财报日历 `insight performance-calendar list/download`
 
@@ -194,7 +195,8 @@ gangtise insight foreign-opinion list [--rank-type <n>] [--security <code>] [--r
 ```
 
 - `--security`：境外证券代码，如 `UBER.N`
-- `--region`：`cn` | `cnHk` | `cnTw` | `us` | `jp` | `uk`
+- ⚠️ `--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[]` 筛
 - `--broker`：外资券商 ID（见 `references/lookup-ids.md`）
 - `--rating` / `--rating-change`：同研报
 - 返回字段：`foreignOpinionId` / `title` / `titleTranslate` / `content` / `contentTranslate` / `publishTime` / `publisher{brokerId, brokerName}` / `securityList[]{securityCode, rating, targetPrice, currency}` / `region`
@@ -207,6 +209,7 @@ gangtise insight independent-opinion download --independent-opinion-id <id> --fi
 ```
 
 - `--security`：境外证券代码，如 `GSK.N`
+- ⚠️ `--industry`：**当前传任何值都拿不到数据，且 payload 是字面 `null` 而非空 list**（同 foreign-opinion，注意事项见上），改用不带该参数取回后按 `industryList[]` 本地筛
 - `--rating` / `--rating-change`：同外资观点
 - `--file-type`（download **必选**）：`1` 原文 HTML | `2` 中文翻译 HTML
 - 返回字段：`independentOpinionId` / `title` / `titleTranslate` / `brief` / `briefTranslate` / `publishTime` / `analyst{analystId, analystName}` / `securityList[]` / `industryList[]`

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

@@ -6,41 +6,54 @@
 
 **关键规则**：查"最近"K线必须显式 `--start-date`/`--end-date` 拉范围，再从 `tradeDate` 取尾部最近 N 条；不要只用 `--limit N`（会截取查询窗口开头）。
 
-**自动分片**（v0.12.0；v0.14.2 修正分片粒度并注入 limit=10000）：`--security all` 跨日期范围 CLI 会自动按日切片并并发执行（A 股 1 天/片，美股 1 天/片，HK 2 天/片，指数 30 天/片），合并结果返回。CLI 在 `--security all` 路径会自动把 `limit` 抬到 10000（API 上限），避免默认 6000 行截断。无需手动按季度分批。
+🔴 **全市场关键字换了（2026-08-14）**：`quote day-kline` 的 `--security all` **已不再支持**，改为三个市场关键字之一——`aShares` / `hkStocks` / `usStocks`，且**必须单独传**（不能与证券代码或另一个关键字混填）。传 `all` 或混填 CLI 会直接报错并提示正确写法。三个已下线的旧命令（`day-kline-hk` / `day-kline-us` / `index-day-kline`）仍认 `all`。
+
+**自动分片**：全市场关键字跨日期范围时 CLI 自动按日切片并并发执行，合并结果返回，无需手动分批。分片粒度按各市场单个交易日的行数规模定，保证单请求不撞 10000 行的 API 上限：
+
+| 命令 | 全市场关键字 | 分片粒度 |
+| :-- | :-- | :-- |
+| `day-kline` | `aShares` | 1 天/片 |
+| `day-kline` | `hkStocks` | 2 天/片 |
+| `day-kline` | `usStocks` | 1 天/片 |
+| `fund-flow` | `aShares` | 1 天/片 |
+| `day-kline-hk` / `day-kline-us` / `index-day-kline`（旧） | `all` | 2 / 1 / 15 天/片 |
+
+分片路径会自动把 `limit` 抬到 10000（API 上限），避免默认 6000 行截断；按日分片自动跳过周六日。
 
 **日K线历史性**（v0.14.0 起 API 文档明确）：所有日K线接口仅返回**历史数据**，不提供实时行情。盘中实时数据请改用 `quote realtime`。当日数据入库时间：A 股约 15:30、港股约 16:30、美股约 07:00（北京时间）。
 
 ---
 
-## 日 K 线（A 股） `quote day-kline`
+## 日 K 线（统一，A 股 / 港股 / 美股 / 指数） `quote day-kline`
 
 ```bash
 gangtise quote day-kline [--security <code>] [--start-date <YYYY-MM-DD>] [--end-date <YYYY-MM-DD>] [--limit <n>] [--field <name>]
 ```
 
-- 支持 `.SH` `.SZ` `.BJ`，`--security all` 全市场
-- `--limit` 默认 6000，上限 10000
-- 常用字段：`open` `high` `low` `close` `pctChange` `volume` `amount`
-
-## 日 K 线（港股） `quote day-kline-hk`
+**2026-08-14 起这一个命令覆盖全部品种**，港股 / 美股 / 指数不用再换命令，也可以在一次请求里混着传：
 
-```bash
-gangtise quote day-kline-hk [--security <code>] [--start-date <YYYY-MM-DD>] [--end-date <YYYY-MM-DD>] [--limit <n>] [--field <name>]
-```
+| 品种 | 代码格式 | 示例 |
+| :-- | :-- | :-- |
+| A 股 | `.SH` `.SZ` `.BJ` | `600519.SH` `835305.BJ` |
+| 港股 | `.HK` | `00700.HK` |
+| 美股 | `.O` 纳斯达克 / `.N` 纽交所 / `.A` AMEX | `AAPL.O` |
+| 交易所指数 | `.SH` `.SZ` `.BJ` | `000001.SH` 上证指数、`399006.SZ` 创业板指 |
+| 概念指数 | `.GT` | `880134.GT` 机器人 |
+| 行业指数 | `.CI` 中信 / `.SWI` 申万（一二三级） | `821031.SWI` |
 
-- 支持 `.HK`，`--security all` 全市场
+- **全市场**：`--security aShares` / `hkStocks` / `usStocks`，**必须单独传**（见文件开头）。⚠️ 指数**不支持**全市场关键字，必须逐个传代码
+- 混市场查询时各证券只返回其所属交易所的交易日：春节期间 A 股休市而美股正常，则当期只有美股行；美国独立日反之
 - `--limit` 默认 6000，上限 10000
+- 常用字段：`open` `high` `low` `close` `pctChange` `volume` `amount` `adjustFactor`
+- `adjustFactor` 复权因子：后复权价 = 不复权价 × `adjustFactor`；前复权价 = 不复权价 × `adjustFactor` ÷ 最新交易日的 `adjustFactor`。**指数无复权因子，该字段为 `null`**
 
-## 日 K 线（美股） `quote day-kline-us`
+## ⚠️ 已下线的三个旧命令（仍可调用）
 
-```bash
-gangtise quote day-kline-us [--security <code>] [--start-date <YYYY-MM-DD>] [--end-date <YYYY-MM-DD>] [--limit <n>] [--field <name>]
-```
+`quote day-kline-hk` / `quote day-kline-us` / `quote index-day-kline` 的能力已并入上面的 `day-kline`，官方于 2026-08-14 把它们从菜单下线，接口仍可调用。**新代码一律用 `day-kline`**，理由不止是少记三个命令：
 
-- 美股代码格式：`AAPL.O`（纳斯达克 `.O`，纽交所 `.N`，AMEX `.A`），`--security all` 全市场
-- 数据范围：NYSE / NASDAQ / AMEX
-- `--limit` 默认 6000，上限 10000
-- 字段与 A 股/港股相同，货币单位为美元
+- 旧命令**不校验证券代码**——传错代码返回 `{"total":0}` 而不是报错，与「该票该区间真无数据」无法区分；`day-kline` 会报 `120001`
+- 参数与字段和 `day-kline` 完全一致（`--security` / `--start-date` / `--end-date` / `--limit` / `--field`），迁移只是换命令名
+- 三者的全市场关键字仍是 `all`（不是 `aShares` 那套）
 
 ## 实时行情 `quote realtime`
 
@@ -48,8 +61,9 @@ gangtise quote day-kline-us [--security <code>] [--start-date <YYYY-MM-DD>] [--e
 gangtise quote realtime [--security <code>] [--field <name>]
 ```
 
-- **覆盖三大市场**：支持 A 股 / 港股 / 美股代码混合传入（如 `--security 600519.SH --security 00700.HK --security AAPL.O`）
-- **全市场关键字**：`--security aShares` 全部 A 股 / `--security hkStocks` 全部港股 / `--security usStocks` 全部美股；建议配合 `--field` 精简返回字段
+- **覆盖三大市场 + 指数**：A 股 / 港股 / 美股个股与交易所指数（`.SH`/`.SZ`/`.BJ`）、概念指数（`.GT`）、行业指数（`.CI`/`.SWI`）可混合传入（如 `--security 600519.SH --security 00700.HK --security 000001.SH --security 880134.GT`）
+- **全市场关键字**：`--security aShares` 全部 A 股 / `hkStocks` 全部港股 / `usStocks` 全部美股，**必须单独传**（不能与代码或另一个关键字混填，CLI 会本地拦截）；建议配合 `--field` 精简返回字段。⚠️ 指数不支持全市场关键字
+- 指数返回的是点位，无货币单位；概念 / 行业指数交易时间与 A 股一致
 - 返回**最新时刻**的行情快照（最新价/开高低/涨跌/成交量额/振幅）
 - 非交易时间返回最近一个交易日的收盘快照；停牌证券返回停牌前最后一个有效快照
 - **实测全量字段（16 个，2026-07-24）**：`securityCode` `exchange` `tradeDate` `tradeTime` `open` `high` `low` `latestPrice` `preClose` `change` `pctChange` `volume` `amount` `turnoverRate` `amplitude` `volumeRatio`
@@ -74,24 +88,29 @@ gangtise quote fund-flow [--security <code>] [--start-date <YYYY-MM-DD>] [--end-
 - 金额单位：元；占比单位：%（各分类流入占比之和 = 100）
 - 无积分消耗
 
-## 指数日 K 线 `quote index-day-kline`
+## 指数日 K 线 `quote index-day-kline`（⚠️ 已下线，改用 `day-kline`）
 
 ```bash
 gangtise quote index-day-kline [--security <code>] [--start-date <YYYY-MM-DD>] [--end-date <YYYY-MM-DD>] [--limit <n>] [--field <name>]
 ```
 
-- 沪深京指数：如 `000001.SH` 上证综指、`399001.SZ` 深成指；`--security all` 全市场指数
+- 沪深京指数：如 `000001.SH` 上证综指、`399001.SZ` 深成指；`--security all` 全市场指数（**仍是 `all`，不是 `aShares` 那套**）
 - `--limit` 默认 6000，上限 10000
 - 常用字段：`securityCode` `securityName` `tradeDate` `open` `high` `low` `close` `preClose` `change` `pctChange` `volume` `amount`
 - `securityName` 为指数名称（如 `上证指数`），v0.15.0 起返回
+- **还值得用它的两个场景**（都是 `day-kline` 做不到的，实测 2026-08-13）：
+  1. **一次拿全部沪深京指数**（`--security all`）——`day-kline` 的指数必须逐个传代码
+  2. **要指数名称**——`index-day-kline` 返回 `securityName`（如「上证指数」），`day-kline` **没有这个字段**，查指数只拿得到代码
+- 反过来 `day-kline` 独有 `adjustFactor`（复权因子），但指数本来就没有复权，该字段查指数时恒为 `null`
 
-## 分钟 K 线（A 股） `quote minute-kline`
+## 分钟 K 线 `quote minute-kline`
 
 ```bash
 gangtise quote minute-kline --security <code> [--start-time <datetime>] [--end-time <datetime>] [--limit <n>] [--field <name>]
 ```
 
-- 仅支持 A 股，**必须传 `--security`**（否则返回 `100003`，msg 为「securityCode不可为空」；2026-07-20 实测）
+- 支持**沪深** A 股个股（`.SH` / `.SZ`，不含北交所）、交易所指数（`.SH` / `.SZ`）、概念指数（`.GT`）、行业指数（`.CI` / `.SWI`），2026-08-14 起扩展；**必须传 `--security`**（否则返回 `100003`，msg 为「securityCode不可为空」；2026-07-20 实测）
+- **一次只能查一只**（参数是 `securityCode` 单值，不是列表），要多只就循环调用
 - `--start-time` / `--end-time`：`yyyy-MM-dd HH:mm:ss`（兼容 `yyyy-MM-dd` 自动补全）
 - `--limit` 默认 6000，上限 10000
 - 常用字段：`securityCode` `tradeTime` `open` `high` `low` `close` `change` `pctChange` `volume` `amount`

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

@@ -96,17 +96,32 @@ gangtise reference constant-category [--format json]
 | category | 名称 | 结构 | 用于参数 |
 |----------|------|------|---------|
 | `citicIndustry` | 中信一级行业（30，`1008001xx`） | flat | `--industry` 全命令通用首选（见下方说明） |
-| `swIndustry` | 申万一级行业（31，`104xxx`） | flat | `--industry`（仅 6 个 insight list；`vault wechat-message-list` 的 `--industry` 当前两套码都不生效） |
-| `gangtiseIndustry` | Gangtise 行业（30 行业 `1008001xx` + 6 方向 `122000xxx`） | flat | `--research-area` 首选（含宏观/策略等方向，见下方说明） |
+| `swIndustry` | 申万一级行业（31，`104xx0000`） | flat | `--industry`（opinion / research / foreign-report / official-account 可用，但**与中信码不等效**，见下方说明）；`--research-area` 只有 summary / pamirs-summary 认 |
+| `gangtiseIndustry` | Gangtise 研究方向（**只有 6 条方向码** `122000xxx`，不含行业码） | flat | `--research-area` 的方向维度（宏观/策略/固收/金工/海外/其他，见下方说明） |
 | `domesticCity` | 国内城市（省级 ID） | flat | `--location`（roadshow / site-visit / strategy / forum）|
 | `aShareAnnouncementCategory` | A股公告分类 | tree（2 级） | `insight announcement --category` |
 | `hkShareAnnouncementCategory` | 港股公告分类 | tree（2 级） | `insight announcement-hk --category` |
 | `usShareAnnouncementCategory` | 美股公告分类（`103980xxx` 段） | tree（2 级） | `insight announcement-us --category` |
 | `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 正确过滤。⚠️ **`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，勿用。
+> **行业 / 研究方向过滤——选哪套 category（⭐ 权威口径，其他文件引用此处、勿重复枚举命令清单以免漂移；全部为逐端点实测，2026-08-08）：**
+>
+> 先记住三套码的归属，**别把行业码算到 `gangtiseIndustry` 头上**：`citicIndustry` = 30 条行业码 `1008001xx`；`swIndustry` = 31 条行业码 `104xx0000`；`gangtiseIndustry` = **只有 6 条方向码** `122000xxx`（宏观 `122000001` / 策略 `122000002` / 固收 `122000003` / 金工 `122000004` / 海外 `122000005` / 其他 `122000007`），里面**没有任何行业**，去它那里找「食品饮料」永远找不到。
+>
+> - **`--industry`（industryList）→ 用 `citicIndustry`（`1008001xx`）**：opinion / research / foreign-report / official-account 正确过滤。`swIndustry`（`104xx0000`）在这 4 个上**也生效，但不是等效**——两套码的行业成分不同，4 个里有 2 个结果集对不上（research / foreign-report 完全一致；**opinion 与 official-account 传两套码取回的条数相差约 2%–5%**）。所以**统一用中信码**，同一批查询里别把两套码混着传。方向码 `122000xxx` 在 `--industry` 上一律返 0。⚠️ 一个例外：`insight foreign-opinion` / `independent-opinion` 只要传 `--industry` 就拿不到数据（不报错，且 **payload 是字面 `null`、不是空 list**，详见 `insight.md`），只能不带该过滤取回后本地筛。`vault wechat-message-list` 的 `--industry` **只认中信码**，申万码会被静默忽略并返回全量（详见 `vault.md`）。
+> - **`--research-area`（researchAreaList）→ 用 `citicIndustry` 行业码 `1008001xx`，方向再叠 `gangtiseIndustry` 的 `122000xxx`**。⚠️ **申万码 `104xx0000` 只有 `summary` / `pamirs-summary` 认**，其余端点返 0（与传乱码表现一致，不报错）。逐端点实测（同一行业分别传三套码，✅ = 正常过滤，❌ = 返 0）：
+>
+> | 端点 | 中信 `1008001xx` | 申万 `104xx0000` | 方向 `122000xxx` |
+> | :--- | :---: | :---: | :---: |
+> | `insight summary` | ✅ | ✅ | ✅ |
+> | `insight pamirs-summary` | ✅ | ✅ | **❌ 返 0** |
+> | `insight opinion` | ✅ | **❌ 返 0** | ✅ |
+> | `insight roadshow` | ✅ | **❌ 返 0** | ✅ |
+> | `insight site-visit` | ✅ | **❌ 返 0** | ✅ |
+> | `insight forum` | ✅ | **❌ 返 0** | ✅ |
+> | `vault my-conference-list` | ✅ | **❌ 返 0** | ✅ |
+>
+> 一句话结论：**行业维度一律传中信码**（唯一全端点通吃的一套），方向维度传 `122000xxx`（`pamirs-summary` 不支持方向）。
 
 ## 常量值 `reference constant-list`
 
@@ -209,9 +224,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` 等效；`--research-area` 返 0。`vault wechat-message-list` 的 `--industry` 与码表无关——**两套码都不生效**——通用/推荐的**中信码**（`1008001xx`）见 `references/lookup-ids.md` 中信表或 `constant-list --category citicIndustry`。
+> ¹ 第 3 列是**申万码**（`104xx0000`），仅在 opinion / research / foreign-report / official-account 上可作 `--industry` 使用，且**与中信码不等效**（opinion / official-account 两套码结果集不同，见上方 ⭐ 权威口径）；用于 `--research-area` 时只有 summary / pamirs-summary 认，其余端点返 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（`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` 筛。
+> **参数名选择**：`--industry`（industryList，用 `citicIndustry` 码 `1008001xx`）用于 opinion / research / foreign-report / official-account / `vault wechat-message-list`（后者只认中信码）；`foreign-opinion` / `independent-opinion` 也有这个参数，但**当前不生效**，见上方 ⭐ 权威口径；`--research-area`（researchAreaList，行业用 `citicIndustry` 码 `1008001xx`、方向用 `gangtiseIndustry` 码 `122000xxx`）用于 opinion / summary / pamirs-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 消费` 做宽泛搜索。