gangtise-openapi-cli 0.50.0 → 0.52.0

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

@@ -5,7 +5,7 @@
 `--security` 收**基金交易代码**，后缀大写：场外 `005827.OF`；场内 `159967.SZ` / `510300.SH`。可重复，也接受逗号分隔；重复代码服务端自动去重。
 
 - 🔴 **代码不存在、不带后缀（`005827`）、后缀小写（`.of`）、传成股票代码，都返回空结果、不报错**——拿到空先核对代码与后缀
-- **只知道基金名称时**：用 `reference securities-search --keyword <基金简称或 6 位代码> --category fund` 换代码，🔴 **只取返回里 `category` 为 `fund` 的行**——结果里可能混有可转债等债券（关键词含「转债」时前几条可能全是债券），把债券代码传给基金命令会返回空结果、不报错；没有 `category: fund` 的行时，换更具体的基金简称再搜。场内（`.SH` / `.SZ`）与场外（`.OF`）都能搜到（如「易方达蓝筹精选」或 `005827` → `005827.OF`）。基金全称常搜不到，如「华泰柏瑞沪深300ETF」要搜「沪深300ETF」或 `510300`。同一只基金的不同份额与场内 / 场外代码会一起返回（「富国天惠」→ `161005.SZ`、`161005.OF`、`003494.OF` 等），按 `gtsName` 区分后取一个
+- **只知道基金名称时**：用 `reference securities-search --keyword <基金简称或 6 位代码> --category fund` 换代码，🔴 **`--category fund` 别省略**——不带它时结果里会混有可转债等债券，把债券代码传给基金命令会返回空结果、不报错；搜不到时换更具体的基金简称再搜。场内（`.SH` / `.SZ`）与场外（`.OF`）都能搜到（如「易方达蓝筹精选」或 `005827` → `005827.OF`）。基金全称常搜不到，如「华泰柏瑞沪深300ETF」要搜「沪深300ETF」或 `510300`。同一只基金的不同份额与场内 / 场外代码会一起返回（「富国天惠」→ `161005.SZ`、`161005.OF`、`003494.OF` 等），按 `gtsName` 区分后取一个
 - LOF / ETF 的场内代码（`161005.SZ`）与场外代码（`161005.OF`）都能查，返回的 `fundCode` 与 `fundName` 跟随传入的代码（场内简称 / 场外简称不同）；同一只基金别两种代码混着传，会重复
 - A / C 等份额各有代码，要合并到同一只基金用 `basic-info` 的 `mainFundCode`
 - 多只基金的结果**按 `fundCode` 字段对应**，别按请求顺序对位
@@ -120,7 +120,7 @@ gangtise fund top10-holders --security <code>... [--start-date <d>] [--end-date
 **仅上市基金**（LOF / ETF 等）。每个报告期按 `serialNumber` 排名各一行：持有人名称、持有份额（份）、占上市总份额比例（%）。半年报与年报披露。
 
 - ETF 在前十名之外可能多一行 `serialNumber = 11`，是该 ETF 的**联接基金**（定期报告单列披露），它的占比可能高于前十中的多位。只要前十名就按 `serialNumber <= 10` 过滤
-- 最新一期的更新可能晚于其他持仓类命令。按最新报告期查不到时，先不带日期查一次，看已有哪些报告期
+- **2026 年中报起披露要求有调整**：除另有披露规则的产品（如 REITs）外，基金中报不再披露前十大持有人，这一期查不到属正常，不是数据缺失（同一基金的 `holder-structure` 仍有这一期）。先不带日期查一次，看该基金有哪些报告期
 
 ## `asset-allocation` 资产配置
 
@@ -166,7 +166,7 @@ gangtise fund etf-share-change    --security <code>... [--start-date <d>] [--end
 - **`etf-pcf-header` / `etf-pcf-components` 只返回最新一份申购赎回清单**，无日期参数，查不了历史清单。`tradeDate` 是清单对应的交易日（清单盘前发布，可能就是当天）
 - **`etf-pcf-header`**：申赎允许情况（`允许申购·允许赎回` 这种 `·` 分隔的组合）、最小申赎单位（份）及其净值（元）、单日申购 / 赎回上限（份，无上限为 `null`）、现金差额与预估现金（元，可为负）、现金替代比例上限（%）、`componentCount` 成分记录数
 - **`etf-pcf-components`**：每个成分一行，按 `serialNumber` 排序：成分代码 `componentCode`、成分名称 `componentName`、收盘价、涨跌幅、市值占比（%）、申购数量（股）、`cashSubstituteFlag`（`允许` / `必须`，中文）、申购 / 赎回现金替代溢价比例（%）、固定替代金额与申购 / 赎回替代金额（元）。宽基 ETF 动辄数百行，多只一起查注意 10000 行上限
-  - 🔴 **`componentCode` 是 CLI 按名称匹配补上的**（接口只返回名称），带市场后缀（如 `600519.SH` / `00941.HK` / `NVDA.O` / 国债 `019848.SH`）。匹配方式：按名称找证券（先查证券列表，没有再搜索），再用该行的 `close` 核对候选证券的最新价或昨收；核对不上的（清单价格滞后于行情、停牌等），改按清单价格所属那天的收盘价核对（A 股与港股各自定日期）——A+H 型 ETF 里同名的 A 股与 H 股两行据此分开。同名证券在两个市场都有时，实时价对上的一方还要另一市场那只的近期收盘价都对不上才直接采用（清单价格滞后时，另一市场那只的实时价可能碰巧等于该行）。价格定不了时（债券、停牌、除权除息当天、行情查询失败）：成分都在同一市场的 ETF 取该市场里名称完全一致的那只，同市场多只时取与 ETF 同一交易所的；两个市场的价格都对得上、或另一市场那只排除不了的行，同样在成分都在同一市场时取该市场那只。**A+H 等跨市场的 ETF，以及还有一行可能在两个市场（同名 A / H 股、或港股名称更长的同一公司）没定下来、或某个名称查询失败的 ETF，这两类行一律为 `null`**，不按名称猜。⚠️「成分都在同一市场」是从其余各行推断的：一只 A+H 型 ETF 若除这一行外没有别的行显出港股，而这一行同名 A / H 的价格又恰好都对得上，会被补成 A 股代码——A+H 型 ETF 用 `componentCode` 前先看港股行是否都有代码
+  - 🔴 **`componentCode` 是 CLI 按名称匹配补上的**（接口只返回名称），带市场后缀（如 `600519.SH` / `00941.HK` / `NVDA.O` / 国债 `019848.SH`）。匹配方式：按名称找证券（先查证券列表，没有再搜索），再用该行的 `close` 核对候选证券的最新价或昨收；核对不上的（清单价格滞后于行情、停牌等），改按清单价格所属那天的收盘价核对（A 股与港股各自定日期）——A+H 型 ETF 里同名的 A 股与 H 股两行据此分开。同名证券在两个市场都有时，实时价对上的一方还要另一市场那只的近期收盘价都对不上才直接采用（清单价格滞后时，另一市场那只的实时价可能碰巧等于该行）；**两个市场的价格都对得上、或另一市场那只排除不了时，再用该行的 `pctChange` 核对**：哪只证券有一天的收盘价与涨跌幅都和该行相同，就是哪只（同一公司 A / H 股价格碰巧相同的日子，涨跌幅几乎不会也相同）。**排除一只证券要有证据**：它的日 K 要覆盖到相应那天、且收盘价对不上——实时行情对上该行而日 K 还没到行情那天（按行情日期判断）、或日 K 从更晚的日期才开始的，都不算排除；补码的每一步都按这条。价格定不了时（债券、停牌、除权除息当天、行情查询失败）：成分都在同一市场的 ETF 取该市场里名称完全一致的那只，同市场多只时取与 ETF 同一交易所的。价格与涨跌幅都定不了的（候选里有一只没有近期日 K、日 K 还没覆盖到相应那天——如实时行情比日 K 快一天、或在该收盘价那天算不出涨跌幅、或涨跌幅和哪只都对不上，如除权除息日）：另一市场那只被近期日 K 排除时（覆盖到相应那天、收盘价都对不上）按其余行所在的单一市场取，否则为 `null`——这样的行本身就说明 ETF 可能跨市场，不拿其余行替它定。**A+H 等跨市场的 ETF，以及还有一行可能在两个市场（同名 A / H 股、或港股名称更长的同一公司）没定下来、或某个名称查询失败的 ETF，价格定不了的行一律为 `null`**，不按名称猜
   - **匹配不到的为 `null`**：现金行（如 `申赎现金`）、商品（如 `黄金9999`）、交易所简称与证券名称对不上的（如港股 `港交所`、`中海油`）。stderr 会说明匹配了多少行、列出为 `null` 的行
   - ⚠️ 成分的 `close` 是清单给出的价格，日期可能早于 `tradeDate` 的前一交易日，一天之内还会更新，同一清单里 A 股与港股的日期也可能不同。要用价格计算，请以 `quote day-kline` / `quote realtime` 为准
   - 额外请求都免费：下载一次 A 股 / 港股 / 美股证券列表（3 次请求）在本地按名称匹配，列表里没有的名称（债券、被截断的简称、现金行等）才逐个搜索，另加一两次实时行情查询；有实时价格核对不上的行、或同名证券在两个市场都有时（清单价格滞后、停牌、除权除息、A+H 成分等），再加一次日 K 查询。只要接口原始返回时加 `--no-component-code`（不发这些请求，行里没有 `componentCode`）

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

@@ -17,6 +17,7 @@ gangtise fundamental <income-statement|balance-sheet|cash-flow> --security-code
 - `--period`：`q1` | `interim` 中报 | `q3` | `annual` | `latest`（默认）
 - `--report-type`：`consolidated`（默认）| `consolidatedRestated` | `standalone` | `standaloneRestated`
 - `--fiscal-year` 可重复：`--fiscal-year 2023 --fiscal-year 2024`
+- 🔴 **`--fiscal-year` 要和 `--period` 一起传**：不传 `--period` 时按默认 `latest` 取数，返回的是最新一期，与 `--fiscal-year` 无关（`--fiscal-year 2019` 单独传，拿到的是最新季报）。要某年年报写 `--fiscal-year 2019 --period annual`；港股、美股三张表同样如此
 - `--start-date`/`--end-date` 有值时覆盖 `--fiscal-year`
 - **固定返回字段**（无需 `--field` 指定）：`securityCode` `companyName` `category` `announcementDate` **`earliestAnncDate`** `endDate` `fiscalYear` `period` `reportType` `companyType` `currency` `unit`
 - 🔴 **做时点对齐（「这份财报在某日是否已公开」）用 `earliestAnncDate`（首次公告日），不要用 `announcementDate`**：`announcementDate` 是**返回数值所属公告**的日期——被重述过的报告期显示的是重述公告日（同一财年几期可能都是同一天），据此判断「某期数据在某日是否已公开」会得出相反的结论；`earliestAnncDate` 是该报告期自身的首次公告日。盘后披露的报告计次日，即**永不早于**真实披露时点，用来做 point-in-time 是安全的方向。要交叉核实披露日可查 `insight announcement list`
@@ -89,7 +90,7 @@ gangtise fundamental main-business --security-code <code> [--breakdown <type>] [
 gangtise fundamental valuation-analysis --security-code <code> --indicator <name> [--start-date <date>] [--end-date <date>] [--limit <n>] [--field <name>] [--skip-null]
 ```
 
-- **市场与路由**：本命令仅支持 A 股（港股 / 美股会报 `120001`「非有效A股」）。A股单证券估值序列与估值历史分位始终优先本命令；多证券批量取一组已实现估值点值，且 `indicator search` 三项校验都通过时，才优先 EDE `cross-section` / `time-series`。港 / 美股估值历史分位当前 CLI 不支持，不能用普通 EDE 点值冒充
+- **市场与路由**：本命令仅支持 A 股（港股 / 美股会报 `120001`「非有效A股」）。A股单证券估值序列与估值历史分位始终优先本命令；多证券批量取一组已实现估值点值，且 `indicator search` 三项校验都通过时，才优先 EDE `cross-section` / `time-series`。港 / 美股估值历史分位走 EDE 的 `finc_*_quantile`（各指标覆盖的市场以 `scopeList` 为准，见 `indicator.md`），不能用普通 EDE 点值冒充
 - `--indicator`（**必选**）：`peTtm` 滚动PE | `pbMrq` PB | `peg` PEG | `psTtm` 滚动PS | `pcfTtm` 滚动PCF | `em` 企业倍数
 - `--limit` 默认 2000，省略 `--start-date` 时自动查近一年
 - 🔴 **序列按自然日逐日一行（含周末）**，行数超过 `--limit` 时接口**保留最近的行、丢掉区间开头**。CLI 撞满即标 `partial`、退出码 3 并在 stderr 说明（首行恰好就是 `--start-date` 时说明没丢，不标）。取长区间把 `--limit` 设到不小于区间天数：取 N 年就设 `--limit` ≥ 366 × N（且不早于账号权限窗口的起点）

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

@@ -13,13 +13,14 @@
 | 多证券批量取一组**已实现**财务 / 估值指标 | 先 `indicator search`，通过下方三项校验后用 `cross-section` / `time-series` 一次拉取，避免逐只循环 |
 | A股盈利预测 / 一致预期（含预测 EPS） | `fundamental earning-forecast`；EDE 搜到的基本 / 稀释 EPS 是已实现值，不能替代预测 |
 | A股估值历史分位 | `fundamental valuation-analysis` |
+| 港 / 美股估值历史分位 | EDE `finc_*_quantile`（`sDate` 至 `--date` 区间里的分位；各指标覆盖的市场不同，以 `scopeList` 为准，见下方「银行 / 保险 / 券商专项指标与估值分位数」） |
 | **估值指标的历史序列**（分位 / 回测 / 择时） | 两个接口口径不同、都要交叉核——EDE 按正式财报披露日切换财报口径，`valuation-analysis` 按业绩快报切，见下方专门小节 |
 | 开高低收 / 成交量等行情与 K 线 | `quote`；免费且支持多证券批量。**换接口不换口径**：`quote` 的 `volume` 与 EDE `qte_vol` 逐位相同（A股 / 港股 / 美股，单位均为股）。EDE 只在 `quote` 不提供的口径上才需要——周 / 月 / 季 / 年 / 区间成交量 |
 | 单只基金的净值 / 持仓 / 规模 / 经理 | `fund` 命令组；多只基金批量取分类、复权净值与风险收益指标才用 EDE，见下方「基金指标」 |
 | 单证券资金流向（要占比字段） | `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) 与 `finc_pb_mrq`(PB MRQ)。⚠️ **本文里所有「仅 A 股」「无数据」这类否定结论都只是某个时点的抽查**——服务端在持续补数据，正面结论过期会给错数，负面结论过期则会让你白白拒掉一个现在能跑的查询（不报错、不告警，只是少调一次）。**一律以当次 `scopeList` + 抽查一行为准。**`search` 免费，EDE 取数按单元格计费；除多证券批量的效率收益外，仍优先免费 / 低价的 `quote` 或 `fundamental`。
+EDE 不是“搜到就优先”。取数前必须核对：① `indicatorName` + `description` 与目标语义一致；② `scopeList` 覆盖**全部**目标市场和证券类型；③ `parameterList` 的必填参数与枚举可满足。`scopeList` 缺失 / `null` / 空或任一项不符，都视为无法证明覆盖并回退上表的专用接口；专用接口也不支持目标市场时，如实说明当前 CLI 无可用口径，不能用其他语义代替。`valuation-analysis` / `earning-forecast` 仅支持 A 股：港 / 美股的**盈利预测**当前无可用口径；**估值历史分位**走 EDE 的 `finc_*_quantile`（逐指标核 `scopeList`，见上表）。估值指标本身港 / 美股也有数：`finc_pe_ttm`（PE TTM，`scopeList` 列 A / 港 / 美）与 `finc_pb_mrq`（PB MRQ，列 A / 港）。⚠️ **本文里所有「仅 A 股」「无数据」这类否定结论都只是某个时点的抽查**——服务端在持续补数据，正面结论过期会给错数，负面结论过期则会让你白白拒掉一个现在能跑的查询（不报错、不告警，只是少调一次）。**一律以当次 `scopeList` + 抽查一行为准。**`search` 免费，EDE 取数按单元格计费；除多证券批量的效率收益外，仍优先免费 / 低价的 `quote` 或 `fundamental`。
 
 ## 指标搜索 `indicator search`
 
@@ -31,7 +32,7 @@ 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 / 港 / 美股。覆盖面在持续扩，别把抽查结论当常量：例如 `qte_mkt_cptl`/`shr_tot` 覆盖 A/港/美股，`finc_pe_ttm` / `finc_pb_mrq` 覆盖 A/港股，`is_op_rev_ttm`/`is_shnp_ttm` 覆盖 A/港股。目标列表含任一 scope 外证券时，本批 EDE 校验不通过，应回退专用接口
+- **市场范围按指标判断**：`scopeList` 会返回实际覆盖范围，且指标之间不同；不能笼统写成每个指标都覆盖 A / 港 / 美股。覆盖面在持续扩，别把抽查结论当常量：例如 `qte_mkt_cptl` / `shr_tot` / `finc_pe_ttm` / `is_op_rev_ttm` / `is_shnp_ttm` 覆盖 A/港/美股，`finc_pb_mrq` 的 `scopeList` 只列 A/港股。目标列表含任一 scope 外证券时，本批 EDE 校验不通过，应回退专用接口
 - **`scopeList[].usageRestriction`**：该指标在具体接口上的限制，`null` = 无限制。⚠️ **它是提示不是硬约束**——标着「不支持指标时间序列接口」的 `qte_vol_intvl` 调时序照样返数据、不会被拦下。当成「口径可能不对、结果别当真」看，别指望它会报错
 - ⚠️ **`scopeList` 是声明不是保证**：它可能**超前于数据**（声明覆盖但该市场暂无数据），也可能**滞后于数据**（已有数据尚未声明）。**「某某仍无数据」这类否定结论过期得和正面结论一样快**，照着它走会白白拒掉一个现在能跑的查询，而且不报错。**判断成本很低**：无数据会保留行列、给一个占位单元格，抽查一行就能看出覆盖情况；code 写错则直接报 `100003`，两种情形不会混淆。占位值统一是 `null`（详见下方「缺数据 vs 代码写错」）
 - 美股代码用交易所后缀 `.O`(NASDAQ) / `.N`(NYSE) / `.A`(NYSE American，原 AMEX)：用 `AAPL.O`，`AAPL.US` 取不到数据
@@ -50,7 +51,7 @@ gangtise indicator cross-section --indicator <code> [--indicator <code2>] \
 
 - `--indicator`（**至少 1 个**）：指标编码，来自 `search`，可重复传多个
 - `--security`（**至少 1 个**）：证券代码，如 `600519.SH`（A股）/ `09992.HK`（港股）/ `AAPL.O`（美股，用 `.O`/`.N`/`.A` 后缀，非 `.US`），可重复传多个。**也接受板块 ID**（`reference sector-search` 返回的 10 位 `sectorId`，如 `1000000287` 中信白酒 → 展开成它的全部成分股），代码与板块可混传，服务端取并集去重。⚠️ 中信行业码那类 9 位 ID（`100800109`）**不是** `sectorId`，传进去返 0 只
-- `--date`（**必选**）：数据日期 `yyyy-MM-dd`。**CLI 把它下发为每个指标各自的 `tradeDate`**（接口没有根级 date）。日期语义按指标分两类——财务报表指标=报告期末（可为非交易日；**⚠️ `_ttm` 后缀整族例外，走交易日，见下方「日期路由」**）、`finc_pe_ttm` / `finc_pb_mrq` 等日频估值=交易日（详见下方「日期路由」）
+- `--date`（**必选**）：数据日期 `yyyy-MM-dd`。**CLI 把它下发为每个指标各自的 `tradeDate`**（接口没有根级 date）。日期语义按指标分两类——财务报表指标=报告期末（可为非交易日；**⚠️ `_ttm` 后缀的多数走交易日，但不是全部，见下方「日期路由」**）、`finc_pe_ttm` / `finc_pb_mrq` 等日频估值=交易日（详见下方「日期路由」）
   - `--date` 必填：绝大多数指标必填 `tradeDate`，漏传服务端报 `100001` 并点名缺哪个参数，所以 CLI 要求带上、下发给每个指标。（`screener` 的 `--date` 也必填，同理）
   - 🔴 **判据一句话：该指标的 `parameterList` 里有 `tradeDate` 就不用管；没有，`--date` 下发的 `tradeDate` 就可能被拒。** 按这条走，四种情形四种写法（`parameterList` 从 `indicator search --keyword <code> --format json` 读，别按 code 前缀推断）：
 
@@ -62,7 +63,7 @@ gangtise indicator cross-section --indicator <code> [--indicator <code2>] \
     | 无 `tradeDate`、`parameterList` 为空 | 只加 `--indicator-param "<code>:"` |
 
     - **空冒号那条与真实参数可以共存**：`"div_cash_yr:" "div_cash_yr:fiscalYear=2025"` 两条一起给，前者只关掉日期注入，不会把 `fiscalYear` 清掉
-    - **哪些指标属于后两种**：已知是 `pty_*`（公司属性：注册地址 / 法定代表人 / 经营范围 / 公司简介…）与 `scr_*`（证券属性：证券简称 / ISIN / 上市市场 / 上市板块 / 上市日期…）两族，加上 `div_cash_paid_ratio` / `div_cash_yr` / `pty_shr_reg` 与基金的 `fund_main_code` / `fund_estb_dt`。🔴 **这只是当前已知的快照，不是完整清单**——`indicator search` 必须给关键词、`--limit` 上限 100 且没有翻页，所以指标库无法整体枚举。**永远以 `parameterList` 为准**；要重新生成某一族用 `indicator search --keyword <前缀>_ --limit 100`，返回条数小于 100 即该族已列全
+    - **哪些指标属于后两种**：已知是 `pty_*`（公司属性：注册地址 / 法定代表人 / 经营范围 / 公司简介…）与 `scr_*`（证券属性：证券简称 / ISIN / 上市市场 / 上市板块 / 上市日期…；**行业分类 `scr_indu` / `scr_indu_*` 除外**，它们要 `tradeDate` 与行业参数，见下文「行业分类」）两族，加上 `ipo_*`（首发：价格、数量、募资、网上网下申购与配售）整族、`div_cash_paid_ratio` / `div_cash_yr` / `pty_shr_reg` 与基金的 `fund_main_code` / `fund_estb_dt`。🔴 **这只是当前已知的快照，不是完整清单**——`indicator search` 必须给关键词、`--limit` 上限 100 且没有翻页，所以指标库无法整体枚举。**永远以 `parameterList` 为准**；要重新生成某一族用 `indicator search --keyword <前缀>_ --limit 100`，返回条数小于 100 即该族已列全
     - ⚠️ **别把「有 `fiscalYear`」当成「不要 `tradeDate`」**——`frcst_pe` / `frcst_shnp` / `frcst_op_rev` 等预测类指标 `parameterList` 里**两个都是必填**，照常用 `--date` 再加一条 `fiscalYear`，**不要**加空冒号那条
     - ⚠️ **也别把「有 `reportDate`」当成「不受影响」**——报告期类指标同样拒收注入的 `tradeDate`，只是解法（自己传 `reportDate`）刚好顺带关掉了注入
   - 🔴 **吃 `reportDate` 的指标必须显式传 `reportDate`**：`--indicator-param "code:reportDate=2024-12-31"`。服务端不接受 `tradeDate`——只给 `--date` 会报 `100003「指标 xxx 不支持参数 tradeDate; 指标 xxx 缺少必填参数 reportDate」`。哪些指标属于这一类看 `indicator search` 的 `parameterList`：`reportDate` 标 `required: true` 且列表里没有 `tradeDate` 的就是。利润表 / 资产负债表 / 现金流量表类（`is_*` 等）都在此列；行情与估值类（`qte_*` / `finc_*`）仍用 `--date` 即可。CLI 检测到你已为某指标传了 `tradeDate` 或 `reportDate` 就不再注入 `--date`，所以补上 `--indicator-param` 就能正常取数
@@ -141,7 +142,7 @@ gangtise indicator screener --indicator <F1:code> [--indicator <F2:code2>] \
   - 文本：`contains` / `notcontains`（不区分大小写，**仅对 `dataType: string` 的指标有效**）
   - 逻辑：`&&` `||`，分组 `(` `)`
 - `--date`（**必选**）：下发为**每个**指标的 `tradeDate`（已带 `tradeDate`/`reportDate` 的不覆盖）。绝大多数指标必填 `tradeDate`，漏传服务端报 `100001`，所以必填
-- 🔴 **`parameterList` 里一个日期参数都没有的指标（`pty_*` / `scr_*` 静态属性两族、`div_cash_paid_ratio` / `div_cash_yr`、`pty_shr_reg`、`fund_main_code` / `fund_estb_dt`）必须显式声明「不要日期」**：写 `--indicator-param "F1:"`（冒号后什么都不写）。不写的话 `--date` 会给它注入 `tradeDate`，而这些指标不接受该参数，**整条请求**报 `100003 指标 xxx 不支持参数 tradeDate`。`F1:` 与真参数可组合，`div_cash_*` 要同时给 `F1:` 和 `F1:fiscalYear=2025`。这与 `cross-section` 的 `"code:"` 是同一个写法。注意只有**没有任何日期参数**的指标需要，报告期类（`is_*` 等）给 `F1:reportDate=...` 即可
+- 🔴 **`parameterList` 里一个日期参数都没有的指标（`pty_*` / `scr_*` 静态属性两族——**行业分类 `scr_indu` / `scr_indu_*` 除外**，它们要 `--date`，写成 `code:` 会把 `tradeDate` 去掉——、`ipo_*` 首发一族、`div_cash_paid_ratio` / `div_cash_yr`、`pty_shr_reg`、`fund_main_code` / `fund_estb_dt`）必须显式声明「不要日期」**：写 `--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 / <各指标名>…`；无命中返回空表
@@ -292,7 +293,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` 属报告期类，还要补 `--indicator-param "finc_roe_avg_avg:reportDate=2025-12-31"`（只给 `--date` 报 `100003`） |
 | `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`。⚠️ **不传 `sDate` 不报错**——它是可选参数，缺了就按默认区间算，所以要的是特定区间就必须显式传。另：`qte_amp_mo`（月振幅）等周期变体只吃 `tradeDate`，没有起始日参数 |
 | `fiscalYear` | 年度/报告期类（如 `div_cash_yr` 年度现金分红）、预测类（如 `frcst_pe`，与 `tradeDate` 同时必填） | `--indicator-param "div_cash_yr:fiscalYear=2025"` |
-| `industryType` + `industryLevel` | `scr_indu` 所属行业（两个都 required，缺任一报 `100001`） | `--indicator-param "scr_indu:industryType=1" --indicator-param "scr_indu:industryLevel=0"` |
+| `industryType` + `industryLevel` | `scr_indu` 所属行业（两个都 required，缺任一报 `100001`；⚠️ 预计下线，改用下文的 `scr_indu_citic` / `scr_indu_sw` / `scr_indu_gics`） | `--indicator-param "scr_indu:industryType=1" --indicator-param "scr_indu:industryLevel=0"` |
 
 > `paramValue` 一律按**字符串**约定传（`periodNum=4` 内部即 `"4"`，CLI 已处理）。
 
@@ -339,7 +340,7 @@ gangtise indicator cross-section --indicator mgn_bal --indicator mgn_fin_bal --i
 # 茅台 2026-08-07：两融 176.7 亿 / 融资 175.4 亿 / 融券 1.3 亿
 ```
 
-**行业分类 `scr_indu`（所属行业）**——一个指标覆盖四套体系，A/港/美股均支持，返回**字符串**：
+**行业分类 `scr_indu`（所属行业）**——⚠️ **预计下线**：`indicator search` 已搜不到，取数暂时仍可用，新写的取数一律改用下文的**行业组合指标**。一个指标覆盖四套体系，A/港/美股均支持，返回**字符串**：
 
 - `industryType`：`1`=申万 `2`=中信 `3`=恒生 `4`=GICS
 - `industryLevel`：`0`=全路径（用 `-` 连接各级）`1`=一级 `2`=二级 `3`=三级 `4`=四级
@@ -354,20 +355,21 @@ gangtise indicator cross-section --indicator scr_indu \
 
 体系与市场要配对：A 股查恒生 / GICS、美股查申万，都返 `null`（如茅台 `industryType=3/4` 均为 `null`）。
 
-**行业组合指标（3 个）**——把体系写进指标编码，省掉 `industryType`：
+**行业组合指标（3 个）**——把体系写进指标编码，省掉 `industryType`；`scr_indu` 下线后行业分类走这三个：
 
 | 指标 | 体系 | 参数 |
 | :-- | :-- | :-- |
-| `scr_indu_citic` | 中信行业 | `tradeDate`（必填）+ `industryLevel`（**可选**） |
+| `scr_indu_citic` | 中信行业 | `industryLevel`（**必传**，取值同上，`0` 为全路径；不传报 `100001`）+ `--date` |
 | `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
+  --indicator-param "scr_indu_citic:industryLevel=0" --indicator-param "scr_indu_sw:industryLevel=1" \
+  --security 600519.SH --date 2026-11-06
 ```
 
-与 `scr_indu` 的取舍：**只要一套体系就用组合指标**（少一个必填参数，且 `industryLevel` 可省），**要在同一次请求里横比多套体系**才用 `scr_indu`（换 `industryType` 即可，不必记三个编码）。恒生体系没有组合指标，仍走 `scr_indu:industryType=3`。
+多套体系横比就在同一次请求里列多个组合指标（如上例）。⚠️ **恒生体系没有组合指标**：目前只能走 `scr_indu:industryType=3`，`scr_indu` 下线后 EDE 不再提供恒生行业。
 
 **`finc_pb_mrq`（市净率 MRQ）是日频指标**：每个交易日都有数且逐日变动，别按报告期末取（那会拿到几个月前的陈值）。
 
@@ -416,6 +418,95 @@ gangtise indicator cross-section --indicator qte_vol_ratio --indicator qte_turn_
   --security 600036.SH --security 600519.SH --date 2026-10-30
 ```
 
+### 银行 / 保险 / 券商专项指标与估值分位数
+
+**行业专项财务指标**——`scopeList` 只有 **A 股**，都是报告期类（`reportDate` 必填，`reportType` 可选、默认 `1` 合并报表）；**非本行业的公司返回 `null`**。比率类直接是百分数（`0.94` 即 0.94%）。
+
+| 族 | 覆盖 | 例 |
+| :-- | :-- | :-- |
+| 银行 `bk_*` | 资本充足率（含 2013 口径 `_2`）与资本净额、存贷款余额与成本 / 收益率、不良贷款率与拨备覆盖率、净息差 / 净利差、流动性比率、非利息收入、客户集中度 | `bk_npl_rti` 不良贷款比率、`bk_npl_prvs_covrg` 拨备覆盖率、`bk_net_int_margin` 净息差 |
+| 保险 `insu_*` | 寿险 / 产险分列（`_li` / `_pci`）的实际资本与偿付能力充足率、产险综合成本率 / 费用率 / 赔付率、退保率、净 / 总投资收益率 | `insu_solv_adeq_rti_li`、`insu_compr_cost_rti_pci` |
+| 券商 `secu_*` | 净资本、净资本 / 净资产、净资本 / 各项风险准备之和 | `secu_net_captl`（另有可选 `currency` / `scale`） |
+
+```bash
+gangtise indicator cross-section --indicator bk_npl_rti --indicator bk_npl_prvs_covrg --indicator bk_captl_adeq_rti_2 \
+  --indicator-param "bk_npl_rti:reportDate=2025-12-31" --indicator-param "bk_npl_prvs_covrg:reportDate=2025-12-31" \
+  --indicator-param "bk_captl_adeq_rti_2:reportDate=2025-12-31" --security 600036.SH --date 2026-11-06
+# 招商银行 2025 年报：不良贷款比率 0.94 / 拨备覆盖率 391.79 / 资本充足率(2013) 18.24
+```
+
+**估值分位数（5 个 `finc_*_quantile`）**——`finc_pe_ttm_quantile` 市盈率(TTM)、`finc_pb_mrq_quantile` 市净率(MRQ)、`finc_ps_ttm_quantile` 市销率(TTM)、`finc_pcf_ttm_quantile` / `finc_pcf_ncf_ttm_quantile` 市现率(TTM，经营 / 全部现金净流量)。`scopeList`：`finc_pb_mrq_quantile` 列 A / 港股，其余四个列 A / 港 / 美股——按目标市场逐个核，个别证券取不到时为 `null`。返回当前估值在 `sDate` 至 `tradeDate` 区间里的历史分位（%，0–100，越低越便宜）；负值估值不参与计算，取不到时为 `null`。
+
+- `tradeDate`（即 `--date`）与 **`sDate`（统计区间起点）都必填**，缺 `sDate` 报 `100001`；`quantile` 可选
+
+```bash
+gangtise indicator cross-section --indicator finc_pe_ttm_quantile --indicator-param "finc_pe_ttm_quantile:sDate=2021-11-05" \
+  --security 600519.SH --security 00700.HK --date 2026-11-06
+```
+
+**其他新增的常用指标**（参数以 `parameterList` 为准）：
+
+- **N 年增长率 `*_yoy_n`**（营业收入、净利润、归母净利润、扣非归母净利润、营业利润、利润总额、总资产、股东权益、经营现金流、ROE 等）与 `is_tot_op_rev_cagr` 营业总收入复合增长率：报告期类，`reportDate` + `periodNum`（N 年）都必填
+- **相对年初增长率 `*_yoy_ytd`**（总资产、每股净资产、归母权益）：报告期类
+- **单季度**：`is_gr_prft_qtr` 毛利、`is_oth_bus_incm_qtr` 其他业务净收益、`cf_op_cf_indir_qtr` 间接法经营现金流、`cf_exchg_eff_qtr` 汇率变动影响
+- **TTM 与交易日类**：`finc_fcff_ttm` 企业自由现金流、`finc_roic_ttm` 投入资本回报率——用 `tradeDate`（`--date`）
+- **`div_cash_paid_ratio_cum` 累计股利支付率**：`tradeDate` + `periodNum` 都必填
+
+### 单季度 / MRQ / 年化财务指标、区间估值、市值口径与 IPO 指标
+
+参数以 `parameterList` 为准；**同一族里日期参数也会不同**，下表按实际声明归类：
+
+| 类别 | 指标（例） | 日期参数 / 覆盖 |
+| :-- | :-- | :-- |
+| 单季度与环比 / 同比 | `is_*_qtr`（如 `is_ae_to_tor_qtr` 管理费用 / 营业总收入、`is_np_to_tor_qtr`）、`is_net_prft_qtr_yoy` / `_mom`、`is_tot_op_rev_qtr_yoy` / `_mom`、`is_op_rev_qtr_mom`、`is_eps_adj_qtr`、`cf_opcf_to_cf_qtr`、`finc_roe_qtr` / `finc_roe_dnrp_qtr` / `finc_np_roa_qtr` | `reportDate`。A 股 |
+| TTM | `is_eps_ttm`、`is_or_ps_ttm`、`is_np_to_tor_ttm`、`cf_opcf_ps_ttm` / `cf_ps_ttm`、`finc_roe_avg_ttm` / `finc_np_roa_ttm` / `finc_ebit_roa_ttm`、`finc_pe_ttm_dnrpnp` 扣非 PE(TTM) | `tradeDate`（`--date`）。⚠️ `finc_ebit_to_aset_ttm` 例外，要 `reportDate`。覆盖按指标 A / 港 / 美不等 |
+| MRQ（最新一期存量） | `bs_aset_mrq` 资产、`bs_liblty_mrq` 负债、`bs_eqty_mrq` 股东权益、`bs_sh_owner_eqty_mrq` 归母权益 | `tradeDate`：取截至该日最新报告期的值。A / 港 / 美 |
+| 报告期比率与每股 | `finc_roe_wt` / `finc_roe_diluted` / `finc_roe_dnrp_*` 各口径 ROE、`finc_roe_avg_ann` / `finc_np_roa_ann` / `finc_ebit_roa_ann` 年化、`is_eps_ltsd` / `bs_naps_ltsd` 最新股本摊薄、`is_eps_dnrpnp_bas` / `_dil` 扣非 EPS（另有可选 `reportType`）、`bs_aset_to_eqty_2` 权益乘数(杜邦)、`finc_z_score` | `reportDate`。覆盖按指标 A / 港 / 美不等 |
+| 报告期年化估值 | `finc_pe` / `finc_ps` / `finc_peg` / `finc_pcf_op` / `finc_pcf_ncf` | 🔴 **`tradeDate` 与 `reportDate` 都必填**，两个都用 `--indicator-param` 给。A 股 |
+| 企业价值 | `finc_ev_in_cash` / `finc_ev_ex_cash` 含 / 剔除货币资金、`finc_ev_to_ebitda` / `finc_ev2_to_ebitda` 企业倍数 | `tradeDate`。A 股；金融类公司不计算 |
+| 区间估值 | `qte_intvl_{avg,high,low}_{pe,ps}_ttm` 区间平均 / 最高 / 最低 PE(TTM)、PS(TTM) | `tradeDate` + **`sDate`**（区间起点）；`sDate` 晚于 `tradeDate` 返回 `null`、不报错。A / 港 / 美 |
+| 市值口径 | `qte_free_float_mkt_cptl` 自由流通市值（A / 港）；`qte_mkt_cptl_a_ex_lim` / `_a_in_lim` / `_b_ex_lim` / `_b_in_lim` A / B 股市值（不含 / 含限售）；`qte_mkt_cptl_csrc` 总市值(证监会算法) | `tradeDate`，可选 `currency` / `scale`（`qte_mkt_cptl_csrc` 只有 `scale`）。`_b_*` 只有发行 B 股的公司有值，用 A 股或 B 股代码查都返回该公司的值；`qte_mkt_cptl_csrc` 的港股目前只有 A+H 公司有值 |
+| IPO 首发 | `ipo_issue_px` 首发价格、`ipo_issue_qty` 发行股数、`ipo_gross_procd` / `ipo_net_procd` 募资总额 / 净额、`ipo_pe_post` 首发后市盈率、`ipo_onl_alloc_rti` / `ipo_off_alloc_rti` 网上中签率 / 网下获配比例、`ipo_onl_sub_dt` 网上申购日、`ipo_prosp_dt` 招股公告日、`ipo_lst_std` 上市标准 | **没有日期参数**，必须写 `--indicator-param "<code>:"`，否则报 `100003`；金额 / 数量类可选 `scale`。A 股 |
+
+- **单位**：多数比率是百分数；`bs_aset_to_eqty_2` 是 %（茅台 2025 年报 126.17 即 1.26 倍，与期末口径的 `bs_aset_to_eqty` 不同）、`finc_mkt_cptl_to_liblty` 与 `bs_mony_fnd_to_st_debt` 也是 %；`ipo_onl_alloc_rti` 的 `0.0212` 即 0.0212%；`finc_z_score` 无单位。金额默认元
+- **一季报 / 三季报多为 `null` 的**：`finc_cf_op_idx`、`is_eps_dnrpnp_bas` / `_dil`、`finc_roe_dnrp_wt`（多数公司只在中报 / 年报有值）；`is_eps_dnrpnp_*` 的 `reportType=3/4`（母公司口径）目前取不到值
+- **IPO 字段按当时的发行制度披露**：超额配售（`ipo_oa_*`）只有带绿鞋的发行有；北交所没有网下（`ipo_off_*`）数据；`ipo_alloc_num` 中签号是长字符串；日期类返回 `20261028` 这样的数字
+- `is_fe_to_tor_qtr`（财务费用 / 营业总收入，单季度）A 股目前取不到值，用 `is_fe_to_tor`（报告期累计）或 `is_fe_to_tor_ttm`
+- `reportDate` 传的不是报告期末（如 `2026-11-12`）时返回 `null`、不报错；只覆盖 A 股的指标查港美股代码同样返回 `null`
+
+```bash
+gangtise indicator cross-section --indicator is_eps_ttm --indicator bs_aset_mrq --indicator cf_opcf_ps_ttm \
+  --security 600519.SH --date 2026-11-12
+# 茅台：EPS(TTM) 65.7243、资产总计(MRQ) 318304891882.72、每股经营现金流(TTM) 85.9019
+
+gangtise indicator cross-section --indicator finc_pe \
+  --indicator-param "finc_pe:reportDate=2025-12-31" --indicator-param "finc_pe:tradeDate=2026-11-12" \
+  --security 600519.SH --date 2026-11-12
+# 21.4158；只给 reportDate 报 100001「必填参数 tradeDate 不能为空」
+
+gangtise indicator cross-section --indicator qte_intvl_avg_pe_ttm --indicator-param "qte_intvl_avg_pe_ttm:sDate=2026-01-05" \
+  --security 600519.SH --date 2026-11-12
+# 区间平均 PE(TTM) 19.8981
+
+gangtise indicator cross-section --indicator ipo_issue_px --indicator-param "ipo_issue_px:" \
+  --indicator ipo_gross_procd --indicator-param "ipo_gross_procd:" --indicator-param "ipo_gross_procd:scale=8" \
+  --security 688827.SH --date 2026-11-12
+# 首发价格 45.37、募资总额 7.7712 亿元
+```
+
+### 预计下线的指标
+
+共 23 个，`indicator search` 已搜不到，取数暂时仍可用，**存量取数尽快迁走**：
+
+| 预计下线 | 改用 |
+| :-- | :-- |
+| `scr_indu` 所属行业 | `scr_indu_citic` / `scr_indu_sw` / `scr_indu_gics`（恒生行业暂无替代） |
+| `cdr_conv_ratio` CDR 转换比例 | — |
+| 半年期行情 `qte_*_halfyr`：振幅、涨跌幅、收盘价、最高 / 最低价、前收盘价、换手率与最高 / 最低换手率、成交额、成交量 | 带 `sDate` 的区间指标，`sDate` 取半年前：`qte_amp_intvl` / `qte_chg_pct_intvl` / `qte_high_intvl` / `qte_low_intvl` / `qte_turn_intvl` / `qte_amt_intvl` / `qte_vol_intvl`；收盘价、前收盘价直接用 `quote day-kline` 取对应日 |
+| 周 / 月 / 季 / 半年 / 年均成交额与均成交量 `qte_avg_amt_{wk,mo,qtr,halfyr,yr}` / `qte_avg_vol_{…}` | `qte_avg_amt` 区间日均成交额 / `qte_avg_vol` 区间日均成交量，`sDate` 取对应周期的起点 |
+
+区间指标的 `sDate` 是可选参数，**不传不报错、按默认区间算**——要的是特定区间就必须显式传。
+
 ### 基金指标
 
 `--security` 传基金代码（场外 `.OF`，场内 `.SH` / `.SZ`，如 `005827.OF` / `510300.SH`）。
@@ -428,7 +519,7 @@ gangtise indicator cross-section --indicator qte_vol_ratio --indicator qte_turn_
 
 - 🔴 **区间指标的其余参数一律显式传**，漏传报 `100001`（`parameterList` 列了默认值也一样）：`changePeriod` 变化周期、`yieldType`（`0` 普通 / `1` 对数收益率）、`riskFreeRate`（`0` = 常数 0）、`benchmarkCode` 基准代码（Alpha / Beta / 相关系数 / Jensen / Treynor / 非系统风险要）、`industryLevel`（同类排名按哪一级分类）。每个指标要哪几个以 `parameterList` 为准
 - ⚠️ **`changePeriod` 列出的默认值 `6`（区间）不是每个指标都收**：Sharpe 等的 `description` 写明只支持日 / 周 / 月 / 年（`0` / `1` / `2` / `5`），传 `6` 报 `100003`
-- ⚠️ **`fund_ret_rank` / `fund_ret_rank_pct` 的「同类基金数量」不一定等于所属分类的基金数**：不同分类的基金（如偏股混合型 FOF、偏股混合型、QDII 偏股混合型）在同一 `industryLevel` 下可能拿到几乎相同、接近全部基金数的分母。按同类位置下结论前先核对分母；要在同类里比，用 `fund_cls2_typ` 自己分组后比区间收益（`finc_ann_ret` 等）
+- `fund_ret_rank` / `fund_ret_rank_pct` 的「同类」是 `industryLevel` 指定那一级的 Gangtise 分类：`1` 按 `fund_cls1_typ`、`2` 按 `fund_cls2_typ`，同分类的基金分母相同（如两只偏股混合型基金在 `industryLevel=2` 下同为 `/3098`）
 - `finc_intvl_max_dd` 返回负的百分数（`-19.23` 即 -19.23%），无回撤为 `0`；`fund_estb_dt` 返回 `yyyyMMdd` 整数（如 `20180905`），不是日期字符串
 - 这批区间指标的 `scopeList` 标着「不支持指标时间序列接口」，用 `cross-section` 取
 - 单只基金的净值序列、持仓、规模走 `fund` 命令组；EDE 适合多只基金横向比
@@ -450,8 +541,8 @@ gangtise indicator cross-section --indicator finc_sharpe_ann \
 - **`scopeList` 声称覆盖 ≠ 每只都有数**：声明可能超前于数据，同一指标下也可能只有部分证券有数，既不能当「全覆盖」也不能当「无覆盖」。**判断成本很低**：无覆盖会留下占位单元格（行列都在，跟同批查了什么无关），抽查一行即可判定，不用再靠对照组反推。跨市场批量取数后仍建议**逐市场抽查一行**，别默认 scopeList 就是事实——反过来也一样，**否定结论同样会过期**。
 - **公司类型决定有没有这个科目**：财务科目分公司类型——银行有「存放同业」、券商有「客户资金存款」、保险有「预收保费」，一般企业没有。某指标对茅台返回 `null`（无此科目），换到对应类型证券（招行/中信/平安）就有数。
 - **日期路由**：
-  - 财务报表类（`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` 一律走交易日。**一眼验证**：在一个**非报告期末的普通交易日**直接 `--date` 取 `is_op_rev_ttm`，照样返真值；反过来给它传 `reportDate` 会报 `100003 不支持参数 reportDate; 缺少必填参数 tradeDate`。同族对照：普通 `is_op_rev` 只传 `--date` 则报「不支持参数 tradeDate; 缺少必填参数 reportDate」——**两者恰好相反**。**所以前缀只是提示，判据仍是上面 `--date` 那条：读 `parameterList` 里必填的是哪个，别按 code 前缀推断**
-  - **`tradeDate` 与 `reportDate` 都必填的**（如 `div_cash_yld` 股息率(报告期)）→ 两个都用 `--indicator-param` 显式给：`"div_cash_yld:reportDate=YYYY-MM-DD"` 加 `"div_cash_yld:tradeDate=YYYY-MM-DD"`。只给 `reportDate` 时 CLI 不再把 `--date` 作为 `tradeDate` 注入，会报 `100001 缺少必填参数 tradeDate`
+  - 财务报表类（`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`），**但有例外**：`finc_ebit_to_aset_ttm` 必填 `reportDate`，传 `tradeDate` 报 `100003`。**一眼验证**：在一个**非报告期末的普通交易日**直接 `--date` 取 `is_op_rev_ttm`，照样返真值；反过来给它传 `reportDate` 会报 `100003 不支持参数 reportDate; 缺少必填参数 tradeDate`。同族对照：普通 `is_op_rev` 只传 `--date` 则报「不支持参数 tradeDate; 缺少必填参数 reportDate」——**两者恰好相反**。**所以前缀只是提示，判据仍是上面 `--date` 那条：读 `parameterList` 里必填的是哪个，别按 code 前缀推断**
+  - **`tradeDate` 与 `reportDate` 都必填的**（如 `div_cash_yld` 股息率(报告期)；`finc_pe` / `finc_ps` / `finc_peg` / `finc_pcf_op` / `finc_pcf_ncf` 按报告期年化的估值同样）→ 两个都用 `--indicator-param` 显式给：`"div_cash_yld:reportDate=YYYY-MM-DD"` 加 `"div_cash_yld:tradeDate=YYYY-MM-DD"`。只给 `reportDate` 时 CLI 不再把 `--date` 作为 `tradeDate` 注入，会报 `100001 缺少必填参数 tradeDate`
   - 日频估值类（如 `finc_pe_ttm` / `finc_pb_mrq`）→ 用最新已入库的**交易日**。⚠️ `finc_pb_mrq` 是**日频**的：任意交易日都有数且逐日变动。**别用季度末日期**——那会拿到几个月前的陈值（季末值与当日值可能差得很远，估值指标上就是错数）。别因 code 都以 `finc_` 开头就一律套报告期末，按 `description` 与抽查区分
   - 现金流量表附注/间接法科目（多数 `cf_`）→ **只在年报/半年报披露**，季报日期取不到，改用年报日期 `2025-12-31`
   - 行情类（`qte_` 等）→ 用**交易日**，但常规行情仍应改走 `quote`
@@ -459,7 +550,7 @@ gangtise indicator cross-section --indicator finc_sharpe_ann \
 - **探索性取数**：缺值会保留行列并给占位单元格（含 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` 确认。
 - **批量查询出错先读 msg**：缺必填参数报 `100001`、代码或参数名写错报 `100003`，msg 都会点名是哪个指标或证券，照 msg 改即可。
-- **市值量纲**：`qte_mkt_cptl`（总市值）与 `shr_tot`（总股本）**A/港/美股均有数**；**默认返原始「元」**（大市值公司是 `1e12` 量级，即万亿级），别误当天文数字。用 `scale` 数字码缩放（`0`元 / `3`千 / `4`万 / `6`百万 / `8`亿 / `9`十亿——`scale=8` 即以亿元为单位）、`currency` 换币种（**大写** `DFT`本币 / `CNY` / `HKD` / `USD` …）。**跨证券比市值前先统一 `scale`+`currency`**。
+- **市值量纲**：`qte_mkt_cptl`（总市值）与 `shr_tot`（总股本）**A/港/美股均有数**；`qte_mkt_cptl` 的 `scopeList` 另列指数，部分指数有值（`000300.SH`、`000001.SH` 有，`399006.SZ` 为 `null`），按目标指数先取一行核对；**默认返原始「元」**（大市值公司是 `1e12` 量级，即万亿级），别误当天文数字。用 `scale` 数字码缩放（`0`元 / `3`千 / `4`万 / `6`百万 / `8`亿 / `9`十亿——`scale=8` 即以亿元为单位）、`currency` 换币种（**大写** `DFT`本币 / `CNY` / `HKD` / `USD` …）。**跨证券比市值前先统一 `scale`+`currency`**。
 - **币种与汇率**：`DFT`（原始币种）按市场识别——A股=CNY、港股行情=HKD、美股=USD；汇率换算自洽（互逆且三角一致）。⚠️ 但**同一只港股，行情类的原始币种是 HKD、财务类可能是 CNY**（如泡泡玛特财报以人民币计），跨市场比财务数据时显式传 `--currency CNY` 别依赖 `DFT`。另：财务类指标的汇率按**报告期**折算、行情类按查询日折算，两者隐含汇率会有细微差异，属正常口径差别。
 - **EDE 财务指标的 `reportType`**：`enumList` 的 label 与实际取数**一致**，按 label 传即可（取值以 `enumList` 为准）：
 

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

@@ -108,7 +108,7 @@ gangtise insight pamirs-summary download --summary-id <id> [--file-type <n>] [--
 
 > 未开通该库时任何查询都直接报 `999004`，不必怀疑参数写错。
 
-- **筛选项比 `summary` 少**：没有 `--source` / `--institution` / `--participant-role`。不认识的 body 字段会被丢弃且不报错，所以别照搬 `summary` 的参数，那样只会拿到没过滤的全量
+- **筛选项比 `summary` 少**：没有 `--source` / `--institution` / `--participant-role`。经 `raw call` 手写请求体时，本端点不支持的字段不报错：多数被丢弃、返回没过滤的全量，个别（如 `institutionList`）会被应用、筛成 0 条——别照搬 `summary` 的参数
 - `--search-type`：`1` 标题搜索（默认）| `2` 全文搜索。同一关键词全文搜索的命中数明显多于标题搜索
 - `--rank-type`：`1` 综合排序（默认）| `2` 时间倒序。⚠️ 效果依赖 `--keyword`，详见本文开头的公共说明
 - `--category`：`companyAnalysis` 公司分析 | `industryAnalysis` 行业分析（两者过滤均生效，公司分析占绝大多数）
@@ -117,11 +117,12 @@ gangtise insight pamirs-summary download --summary-id <id> [--file-type <n>] [--
 - `--file-type`（download 可选）：`1` 原始文件（默认）| `2` HTML；**只有这两种**
 - 单页上限 50，CLI 按 50 自动翻页；省略 `--size` 拉全量
 - 返回字段：`summaryId` / `title` / `brief`（摘要）/ `summaryTime`（纪要注明的生成时间）/ `publishTime`（发布时间）/ `categoryList` / `securityList[]{securityCode, securityName}` / `researchAreaList[]{researchAreaId, researchAreaName}` / `conceptList[]{conceptId, conceptName}` / `marketList`
-- ⚠️ **`conceptList` / `categoryList` / `marketList` 三个标签字段稀疏，且是否有值随记录和查法而变**：
-  - **不带筛选时经常整条为空**，用 `--category` 或 `--market` 过滤时回填率明显更高（这两个字段是绑定的：用任一过滤，两个都会有值）。有值时给的是该记录的**全部**值（多市场纪要按 `aShares` 过滤也回 `["aShares","hkStocks"]`，不是"回显过滤值"）
-  - **所以别拉全量再本地分组**——会漏掉大量记录。要按类别/市场分组就逐个枚举值各查一遍再合并（请求数放大 2~4 倍），或直接让服务端筛
-  - **反过来也别据此断言某条记录没有该属性**——标签为空只说明这次查询没回填，不代表该纪要真的没有概念/分类/市场归属
-  - `researchAreaList` 和 `securityList` 的回填要完整得多，不受上面这条影响，可以直接用来做本地分组
+- ⚠️ **`categoryList` / `marketList` 只在按 `--category` 或 `--market` 筛选时返回完整**：
+  - 不带筛选、或只按 `--security` / `--research-area` / `--keyword` 查时，`categoryList` 为空，`marketList` 只会出现 `hkStocks` / `usStocks`，**不会出现 `aShares` / `usChinaConcept`**
+  - 用 `--category` 或 `--market` 任一筛选时，两个字段都给该记录的**全部**值（多市场纪要按 `aShares` 筛也回 `["aShares","hkStocks"]`，不是回显筛选值）
+  - **所以别拉全量再按这两个字段本地分组**——A 股、中概股的归属会整批缺失。要分组就按两个类别、四个市场各查一遍再合并，或直接让服务端筛
+  - **反过来也别据此断言某条记录没有该属性**——标签为空只说明这次查询没返回，不代表该纪要真的没有类别 / 市场归属
+  - `conceptList` / `researchAreaList` / `securityList` 不随查法变，可以直接用来做本地分组
 
 ```bash
 # 近一周的帕米尔纪要
@@ -280,6 +281,30 @@ gangtise insight independent-opinion download --independent-opinion-id <id> --fi
 - `--file-type`（download **必选**）：`1` 原文 HTML | `2` 中文翻译 HTML
 - 返回字段：`independentOpinionId` / `title` / `titleTranslate` / `brief` / `briefTranslate` / `publishTime` / `analyst{analystId, analystName}` / `securityList[]` / `industryList[]`
 
+## 海外观点 `insight overseas-opinion list/detail`
+
+```bash
+gangtise insight overseas-opinion list [--rank-type <n>] [--account <id>] [--security <code>] [--category <name>] [--industry <id>] [--region <code>] [--original-flag <n>]
+gangtise insight overseas-opinion detail --overseas-opinion-id <id> [--overseas-opinion-id <id>...]
+```
+
+- **积分**：列表 0.1/条（只含摘要）；`detail` 10/条
+
+海外媒体、投资人、分析师等账号发布的帖子（新闻、观点、数据分析等），每条附中文翻译。
+
+- 🔴 **列表只含摘要**：`brief`（原文前 200 字）/ `briefTranslate`（中文）。全文与译文（`content` / `contentTranslate`）用 `detail` 按 `overseasOpinionId` 取（**10 积分/条**），单次最多 20 个 ID、CLI 自动分批；分批与缺失 ID 处理同内资 `opinion detail`。一批里有任一条的发布时间超出账号可查范围时，**整批**报 `110003`：第一批就报时整条命令失败（退出 1）；之后的批次报时，已取到的正文照常输出，这批及之后的 ID 列在 `unfetchedIds`。先用 `list` 的时间范围筛到账号范围内再取
+- **可查范围跟着账号权限走**：`--start-time` 早于账号可查的下界时，整段报 `110003`，不会从下界起截断返回——把起点移到下界之后再查
+- ⚠️ **一次查询最多取到前 10000 条**（`from + size` ≤ 10000）。条件较宽（如不带时间范围）时很容易超过：CLI 只取前 10000 条，stderr 提示并以退出码 3 标为不完整——用 `--start-time` / `--end-time` 切成几段分别拉
+- `--account`：账号 ID，用 `reference overseas-account-search --keyword <名称片段>` 查（如 `bloomberg` → Bloomberg 的 `34713362`）
+- `--security`：带市场后缀的证券代码，如 `NVDA.O`；缺后缀报 `120001`。⚠️ 后缀存在但市场不对（`NVDA.N`）不报错、返回空结果，拿到空先核对后缀
+- `--category`：`opinion` 观点分析 | `news` 新闻资讯 | `dataAnalysis` 数据分析 | `promotion` 品牌宣传；写错报 `100005`。传多个类别取并集（命中任一即返回），一次传齐不会重复。一条记录可属于多个类别（`categoryList` 如 `["opinion", "dataAnalysis"]`），在每个所属类别下都会返回——⚠️ 按类别分别拉再合并时，按 `overseasOpinionId` 去重；部分记录的 `categoryList` 为空，这些记录只在不传 `--category` 时返回
+- `--industry`：**GICS 一级行业 ID**（`107700001`–`107700011`，用 `reference constant-list --category gicsIndustry` 查，对照表见 `references/lookup-ids.md`「GICS 一级行业」）；申万码、中信码报 `100005`
+- `--region`：`cn` | `cnHk` | `cnTw` | `us` | `jp` | `kr` | `uk` | `gl`（全球）；`regionCategory` 的其他取值报 `100005`
+- `--original-flag`：`1` 只要原创 | `0` 只要转发；不传返回两者
+- `--start-time` / `--end-time`：按发布时间（北京时间）；只给日期时，结束日期覆盖当天
+- 返回字段（list）：`overseasOpinionId` / `accountId` / `accountName` / `accountIntroduction` / `publishTime` / `originalFlag` / `categoryList[]`（类别，可多个、可为空）/ `brief` / `briefTranslate` / `forwardPost{accountName, publishTime, brief, briefTranslate}`（仅转发帖，原创为 `null`）/ `industryList[]{industryId, industryName}` / `securityList[]{securityCode, securityName}` / `regionList[]{regionCode, regionName}`；`detail` 以 `content` / `contentTranslate` 代替 `brief` / `briefTranslate`（`forwardPost` 内同）
+- 转发帖的 `brief` / `content` 是转发者附带的评论，纯转发时为空字符串。⚠️ 个别转发帖的 `forwardPost` 为 `null`，这时拿不到被转发的原帖
+
 ## 产业公众号资讯 `insight official-account list/download`
 
 ```bash

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

@@ -10,7 +10,7 @@ gangtise reference securities-search --keyword <text> [--category <type>] [--top
 - `--keyword`（**必选**）：支持多维度匹配（中文名/简称/证券代码/拼音首字母/英文名/曾用名）
 - `--category`（可重复）：`stock` | `dr` 存托凭证 | `index` | `fund` | `bond`（不传则查所有）
   - `bond` 覆盖交易所可转债、国债、地方债、金融债与银行间债券（后缀 `.SH` / `.SZ` / `.IB`），按代码或简称查（如 `113636.SH`、`甬金转债`）。债券代码用于 `bond` 命令组；`quote` 行情、公告等其余命令不收债券代码（传了报 `120001`）
-  - 🔴 **可转债在任何 `--category` 下都可能出现**：按公司简称查 `stock` 时，同名可转债常排第一（「甬金」→ `113636.SH 甬金转债` 在 `603995.SH 甬金股份` 之前）。**取第一条 `category` 等于所查类别的行**，别直接取 `list[0]`；用公司全称查时一般只返回正股
+  - 🔴 **查股票带上 `--category stock`**：不带分类按公司简称查时，同名可转债常排第一（「甬金」→ `113636.SH 甬金转债` 在 `603995.SH 甬金股份` 之前）。带了 `--category` 只返回该类别
 - `--top`：默认 10，**上限 10**
 - 返回字段：`gtsCode` / `gtsName` / `category` / `matchScore` / `matchType`
   - `matchType`：`code` 代码 | `abbr` 简称 | `pinyin` 拼音 | `prev` 曾用名 | `engName` 英文名
@@ -75,7 +75,7 @@ gangtise reference official-account-search --keyword <text> [--category <name>]
 ```
 
 - 用途：查公众号 ID，拿到的 `accountId` 喂给 `insight official-account list --account-id` 拉该公众号资讯
-- `--keyword`（**必选**）：公众号名称 / 所属机构 / 关键字（如 `中信证券`、`人民日报`）
+- `--keyword`（**必选**）：公众号名称片段（如 `中信证券` 能查到「中信证券研究」、`人民日报`）。⚠️ 匹配的是公众号**名称**：名称里用简称的公众号，按机构全称查不到——`东吴证券` 返回 0 行，`东吴` 能查到「东吴策略陈刚团队」「东吴食饮」等。按全称查到 0 行时换简称再查
 - `--category`：分类过滤，可多选——`listedCompany` 上市公司 | `broker` 券商团队 | `government` 政府官方 | `media` 媒体。⚠️ 部分公众号不属这四类（`category` 返回 `null`）；一旦传 `--category` 就会漏掉这些未分类公众号，要全量（含未分类）就**别传** `--category`
 - `--top`：默认 10，**上限 10**；结果按 `matchScore`（`0~1`）降序
 - 免费调用
@@ -86,6 +86,23 @@ gangtise reference official-account-search --keyword <text> [--category <name>]
 gangtise reference official-account-search --keyword 中信证券 --top 3 --format json   # → gh_fe1d2be7e8db 中信证券研究
 ```
 
+## 海外观点账号 ID 搜索 `reference overseas-account-search`
+
+```bash
+gangtise reference overseas-account-search --keyword <text> [--from <n>] [--size <n>]
+```
+
+- 用途：查海外观点账号 ID，拿到的 `accountId` 喂给 `insight overseas-opinion list --account`
+- `--keyword`（**必选**）：账号名称片段，一次一个。在账号名任意位置做子串匹配，英文不区分大小写（`elo` 同时命中 `Elon Musk` 与 `Financelot`）；按英文账号名匹配，中文名（如「彭博」）查不到
+- 分页：`--from` / `--size`，省略 `--size` 拉全量；结果按 `matchScore`（`0~1`）降序
+- 免费调用
+- 返回 `{total, list}`；list 字段：`accountId` / `accountName` / `accountIntroduction`（中文简介，无简介为空字符串）/ `matchScore`
+
+**示例：**
+```bash
+gangtise reference overseas-account-search --keyword bloomberg --format json   # → 34713362 Bloomberg
+```
+
 ## 常量分类 `reference constant-category`
 
 ```bash
@@ -94,7 +111,7 @@ gangtise reference constant-category [--format json]
 
 - 用途：全量导出常量分类及每个分类适用于哪些接口的哪些参数（无需传参，免积分）
 - 返回 `{total, list}`，`list[]` 字段：`category`（分类代码）/ `categoryName` / `structureType`（`flat` 平铺 | `tree` 树形）/ `maxLevel` / `usageScopes[]`（`apiName` + `paramName`）
-- 分类清单以 `reference constant-category` 的实际返回为准（服务端会随新接口上线增补）。截至 2026-10 的分类：
+- 分类清单以 `reference constant-category` 的实际返回为准（服务端会随新接口上线增补）。截至 2026-11 的分类：
 
 | category | 名称 | 结构 | 用于参数 |
 |----------|------|------|---------|
@@ -106,6 +123,7 @@ gangtise reference constant-category [--format json]
 | `hkShareAnnouncementCategory` | 港股公告分类 | tree（2 级） | `insight announcement-hk --category` |
 | `usShareAnnouncementCategory` | 美股公告分类（`103980xxx` 段） | tree（2 级） | `insight announcement-us --category` |
 | `regionCategory` | 区域分类 | flat | `insight foreign-report --region` |
+| `gicsIndustry` | GICS 一级行业（`1077000xx`） | flat | `insight overseas-opinion --industry` |
 | `nationalEconomicIndustry` | 国民经济行业分类 | flat | 行业归属参考 |
 | `fundType` | 基金分类 | tree（2 级） | 基金类接口的基金分类字段 |
 | `fundBondType` | 基金持仓券种类别 | flat | 基金类接口的券种类别字段 |
@@ -121,7 +139,7 @@ gangtise reference constant-category [--format json]
 >
 > 先记住三套码的归属，**别把行业码算到 `gangtiseIndustry` 头上**：`citicIndustry` = 行业码 `1008001xx`；`swIndustry` = 行业码 `104xx0000`；`gangtiseIndustry` = **只有方向码** `122000xxx`（宏观 `122000001` / 策略 `122000002` / 固收 `122000003` / 金工 `122000004` / 海外 `122000005` / 其他 `122000007`），里面**没有任何行业**，去它那里找「食品饮料」永远找不到。
 >
-> - **`--industry`（industryList）→ 用 `citicIndustry`（`1008001xx`）**：opinion / research / foreign-report / official-account 正确过滤。`swIndustry`（`104xx0000`）在这 4 个上**也生效，但不是等效**——两套码的行业成分不同，**opinion 与 official-account 上两套码取回的结果集不同**。所以**统一用中信码**，同一批查询里别把两套码混着传。方向码 `122000xxx` 在 `--industry` 上一律返 0。⚠️ 一个例外：`insight foreign-opinion` / `independent-opinion` 的 `--industry` **只认申万码 `104xx0000`**，传中信码报 `100005 枚举值非法`（详见 `insight.md`）。`vault wechat-message-list` 反过来**只认中信码**，传申万码报 `100005`（详见 `vault.md`）。
+> - **`--industry`（industryList）→ 用 `citicIndustry`（`1008001xx`）**：opinion / research / foreign-report / official-account 正确过滤。`swIndustry`（`104xx0000`）在这 4 个上**也生效，但不是等效**——两套码的行业成分不同，**opinion 与 official-account 上两套码取回的结果集不同**。所以**统一用中信码**，同一批查询里别把两套码混着传。方向码 `122000xxx` 在 `--industry` 上一律返 0。⚠️ 一个例外：`insight foreign-opinion` / `independent-opinion` 的 `--industry` **只认申万码 `104xx0000`**，传中信码报 `100005 枚举值非法`（详见 `insight.md`）。`vault wechat-message-list` 反过来**只认中信码**，传申万码报 `100005`（详见 `vault.md`）。`insight overseas-opinion` 的 `--industry` 两套都不认，**只认 GICS 一级行业码** `107700001`–`107700011`（`reference constant-list --category gicsIndustry`，对照表见 `references/lookup-ids.md`「GICS 一级行业」），申万码、中信码报 `100005`。
 > - **`--research-area`（researchAreaList）→ 用 `citicIndustry` 行业码 `1008001xx`，方向再叠 `gangtiseIndustry` 的 `122000xxx`**。⚠️ **申万码 `104xx0000` 只有 `summary` / `pamirs-summary` 认**，其余端点返 0（与传乱码表现一致，不报错）。逐端点对照（同一行业分别传三套码，✅ = 正常过滤，❌ = 返 0）：
 >
 > | 端点 | 中信 `1008001xx` | 申万 `104xx0000` | 方向 `122000xxx` |
@@ -134,6 +152,7 @@ gangtise reference constant-category [--format json]
 > | `insight forum` | ✅ | **❌ 返 0** | ✅ |
 > | `vault my-conference-list` | ✅ | **❌ 返 0** | ✅ |
 > | `insight highlight` | ✅ | **❌ 不可用** | ✅ |
+> | `ai expert-intel` | ✅ | **❌ 返 0** | 返 0（情报按公司归类，未见方向类） |
 >
 > 一句话结论：**行业维度一律传中信码**（唯一全端点通吃的一套），方向维度传 `122000xxx`（`pamirs-summary` 不支持方向）。
 
@@ -212,6 +231,25 @@ gangtise reference sector-constituents --sector-id 2000000014 --format json
 
 单个行业也可以直接 `reference securities-search --keyword 申万银行 --category index` → `821047.SWI`。
 
+## 指数成分股权重 `reference index-weight`
+
+```bash
+gangtise reference index-weight --index <code>... --date <yyyy-MM-dd>
+```
+
+- 免费。`--index`（**必选**，可重复或逗号分隔）：指数代码，如 `000300.SH` 沪深300、`000905.SH` 中证500、`000852.SH` 中证1000、`000016.SH` 上证50、`000688.SH` 科创50、`399006.SZ` 创业板指；不确定用 `reference securities-search --keyword <指数名> --category index`
+- `--date`（**必选**）：单个交易日。🔴 **只有每月最后一个交易日有数**（如 `2026-09-30`、`2026-10-30`）——其他交易日、非交易日与写错的指数代码都返回空结果、**不报错**；CLI 在 stderr 点名没取到数据的指数。要「最新」权重就取上个月最后一个交易日
+- 超出账号可查范围报 `110003`
+- 不分页、不限条数：一次返回所选指数当日的全部成分股，多个指数合在同一个 `list` 里，按 `indexCode` 区分
+- 返回 `{total, list}`，`list[]`：`indexCode` / `indexName` / `tradeDate` / `securityCode` / `securityName` / `weight`（**单位 %**，最多四位小数）。同一指数的权重合计约为 100，受舍入影响不严格等于 100，校验合计时留容差
+- 与 `reference sector-constituents` 的区别：后者是板块的纯成分名单、不带权重；要权重（基金归因、指数对标）用本接口
+
+**示例：**
+```bash
+gangtise reference index-weight --index 000300.SH --date 2026-10-30 --format csv --output hs300-weight.csv
+gangtise reference index-weight --index 000300.SH,000905.SH --date 2026-09-30 --format json
+```
+
 ## Lookup 本地表
 
 **按名称找机构 ID 优先用 `reference institution-search`**（服务端搜索、覆盖全部 5 类机构、带 usageScopes）；本地表主要用于**全量枚举**券商/会议机构（institution-search 为搜索型：top≤10、非全量）：

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

@@ -13,9 +13,9 @@ gangtise tool file-parse --file <x.pdf>                       # 输出 {"taskId"
 gangtise tool file-parse-check --task-id <id> [--output <out.zip>]
 ```
 
-- `--file`（**必填**）：待解析的 PDF。CLI 在上传前本地校验：文件存在、非空、后缀 `.pdf`、≤100MB——不合格直接报 `ValidationError`，不发请求也不扣分
+- `--file`（**必填**）：待解析的 PDF。CLI 在上传前本地校验：文件存在、非空、后缀 `.pdf`、前 1KB 内有 `%PDF-` 文件头（改了后缀的非 PDF 过不去）、≤100MB、不在 CLI 自己的配置目录里——不合格直接报 `ValidationError`，不发请求也不扣分
 - `--wait`：阻塞轮询到结果就绪（预算 ≈316s，覆盖官方「单文件约 3 分钟」）。**外层工具/命令超时要设到 ≥360s**，否则外层先超时（任务仍在服务端跑，之后 `file-parse-check` 照样能取）
-- `--output`：结果 ZIP 落盘路径。省略时用服务端返回的文件名（形如 `<taskId>.md.zip`），无则 `file-parse-<taskId>.zip`
+- `--output`：结果 ZIP 落盘路径。省略时用服务端返回的文件名（形如 `<taskId>.md.zip`），无则 `file-parse-<taskId>.zip`。是文件路径：传目录（已存在的目录或以 `/` 结尾的路径）会在提交前报错，不扣费
 - 服务端限制：单文件 ≤100MB、≤500 页，同一用户最多 10 个并发任务
 - **积分**：**提交时按实际页数一次性扣费，0.8 积分/页**（50 页 = 40 积分）；取结果免费。提交端点标 `no-replay`——超时/5xx 不自动重放，避免同一文件重复扣费。**重跑 `file-parse` 会重新扣费，取结果请一律用 `file-parse-check --task-id`**
 - 未就绪时 `file-parse-check` 输出 `{"taskId": "...", "status": "pending"}` 且退出码 0（服务端返 `140001` RESULT_GENERATING，HTTP 409），隔 ~1 分钟再取即可

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

@@ -34,7 +34,7 @@ gangtise vault drive-delete-folder --folder-id <id> --yes
 - **ID 从哪来**：文件夹 ID 用 `drive-folder-list` 逐层看（根目录写 `root` 或不传）；文件 ID 在 `drive-folder-list` 的 `fileList` 或 `drive-list` 里。`--space-type` 默认 `1`（我的云盘），**`--parent-id` / `--folder-id` 必须属于该空间**，否则报 `100003`（「parentId 与 spaceType 不一致」）
 - `drive-folder-list` 只返回该文件夹的**直接**子文件夹（`folderList`）与**直接**文件（`fileList`），不递归；返回为 `{folderTotal, folderList, fileTotal, fileList}`，默认 json 输出
 - **同名不报错**：文件与文件夹都允许同名，以 ID 区分。所以**上传 / 新建 / 复制每执行一次就多一份**，这三个命令超时不会自动重发；对同一内容别重复执行
-- `drive-upload`：单个文件 ≤100MB（CLI 本地先拦）；试用账号每天累计上传 ≤500MB（超出 `230008`）。`--title` 不传用本地文件名
+- `drive-upload`：单个文件 ≤100MB（CLI 本地先拦）；试用账号每天累计上传 ≤500MB（超出 `230008`）。`--title` 不传用本地文件名。CLI 自己的配置目录（`~/.config/gangtise/`，存 token 缓存）里的文件与 `GANGTISE_TOKEN_CACHE_PATH` 指向的文件不收，发请求前报错
 - 名称（`--name` / `--title`）≤200 个字符，按 UTF-16 计——中文算 1、emoji 算 2；超出 `230004`
 - **移动只能在同一空间内**：`drive-move-file` 里跨空间的文件进 `failList`（「空间不一致」）；`drive-move-folder` 移到其他空间、自身或其子文件夹报 `230005`
 - **跨空间用 `drive-copy`**：在「我的云盘 ↔ 租户云盘」之间复制，源保留不动，同空间复制报 `100003`。两种用法二选一：复制文件用 `--file-id`（可批量）+ `--target-folder-id`，返回 `successList[]{fileId, newFileId}`；复制整个文件夹用 `--folder-id` + `--target-parent-id`，连同其中的子文件夹与文件一起复制，返回 `{folderId, newFolderId}`。目标 ID 必须在另一空间，`root` 即另一空间的根目录
@@ -83,12 +83,34 @@ gangtise vault wechat-message-list [--keyword <text>] [--security <code>] [--wec
 - 🔴 **`--industry` 是收窄工具，不是全量召回**：行业标签由服务端标注，**同一条消息可能挂多个行业，也可能一个都没挂**。同一个关键词加上「本行业」过滤后，命中数会明显少于只用关键词——**少掉的既有没打标签的，也有被标到相邻行业去的**（如半导体相关的消息在计算机 / 机械 / 通信下同样查得到）。所以「按行业筛出 N 条」不能读成「该行业只有 N 条」；要尽量全，用 `--keyword` 取回后本地判断，或把相邻行业码一起查再去重
 - `--wechat-group-id`：先用 `vault wechat-chatroom-list` 查；可重复
 - 按偏移量**最多取到第 10000 条**（`--from` + 条数不能超过 10000），且 `total` 最多也只报到 10000——正好报 10000 时实际条数可能更多，CLI 按封顶处理：标 `partial` + `totalCapped`、退出码 3。要更多请缩短时间范围分段取，每段的 `total` 低于 10000 才说明取全了
-- `--category`：`text` | `image` | `documents` | `url`（可重复）
+- `--category`：`text` | `image` | `document`（PDF、Excel 等文档）| `url` | `audio` | `video`（可重复）。其他取值（如 `documents`、`pdf`、`mp4` 这类文件格式名）报 `100005`，`--tag` / `--industry` 同样整批拒绝、不会忽略筛选返回全部
 - `--tag`：`roadShow` | `research` | `strategyMeeting` | `meetingSummary` | `industryComment` | `companyComment` | `earningsReview`（可重复）
-- 返回字段：`msgId` / **`content`**（正文）/ **`url`**（链接）/ `msgTime` / `wechatGroupId` / `wechatGroupName` / `speakerName` / `category` / `tagList[]{tagCode, tagName}` / `securityList[]{securityCode, securityName}` / `quoteMsg{quoteMsgId, quoteContent, quoteUrl}`。正文取 `content`、链接取 `url`（不是 `msgContent` / `contentUrl`）
-- `quoteMsg`：被引用的消息，无引用时为 `null`；`quoteContent` / `quoteUrl` 也可能为空。做上下文还原时用它把「回复」接回原消息
+- 返回字段：`msgId` / **`content`**（正文）/ **`url`**（链接）/ `msgTime` / `wechatGroupId` / `wechatGroupName` / `speakerName` / `category` / `fileInfo{fileName, fileSize}` / `tagList[]{tagCode, tagName}` / `securityList[]{securityCode, securityName}` / `quoteMsg{quoteMsgId, quoteCategory, quoteContent, quoteUrl, quoteFileInfo}`。正文取 `content`、链接取 `url`（不是 `msgContent` / `contentUrl`）
+- `msgId` 是长数字串，可能超过 JavaScript 安全整数范围——**始终按字符串保存和传递**，别转成数字（会被舍入，拿去下载就对不上）
+- `content` 随 `category` 不同：`text` 为正文、`document` 为文件名、`image` 为图片识别出的文字（可能含 AI 摘要段落，也可能为空，不保证逐字准确）、`url` 为链接标题、`audio` / `video` 为附带文字（常为空，不含转写）
+- `fileInfo`：`document` / `image` / `audio` / `video` 消息的文件名与字节数（`fileSize`，未知时为 `null`），其他类型为 `null`。要文件本身用下面的 `wechat-message-download`
+- `quoteMsg`：被引用的消息，无引用时为 `null`；`quoteContent` / `quoteUrl` 也可能为空。做上下文还原时用它把「回复」接回原消息。被引用的是文件消息时，`quoteFileInfo` 给文件名与大小，下载用 `quoteMsgId`
 - 未打标签/未关联证券的消息，`tagList` / `securityList` 返回 `null`（不是空数组）
 
+## 群消息文件下载 `vault wechat-message-download`
+
+```bash
+gangtise vault wechat-message-download --msg-id <msgId> [--output <path>]
+```
+
+- 免费。`--msg-id` 取自 `wechat-message-list` 的 `msgId`（按字符串原样传）；只有 `document` / `image` / `audio` / `video` 消息有文件。引用里的文件用 `quoteMsg.quoteMsgId`（先确认 `quoteCategory` 是这四类之一）
+- 一次一个文件。不带 `--output` 时按服务端给的文件名保存（文档、音频一般是原文件名，图片、视频多为一串随机字符），同名自动加 `-1`、`-2`；stdout 是保存路径
+- 内容原样落盘：`.txt` / `.json` / `.html` 等文本类文件也按原字节保存，不做转码。图片是平台保存的版本，不保证原图分辨率；音频、视频只有文件本身，没有转写
+- 报错：`130005` = 该消息是 `text` / `url`，没有文件；`130003` = 消息不存在、本账号无权访问或文件已不可用（三种情况不区分，**重试不会变**，别轮询）；`100003` = `--msg-id` 不是纯数字
+- 列表里有 `fileInfo` 不代表文件一定还能下载，以下载结果为准
+
+```bash
+# 某个群里最近的文件消息 → 逐个下载
+gangtise vault wechat-message-list --wechat-group-id <群ID> --category document --category image --category audio --category video --size 20 --format json
+gangtise vault wechat-message-download --msg-id 4784255865508301077
+gangtise vault wechat-message-download --msg-id 4784255865508301077 --output ./群文件/研报.pdf
+```
+
 ## 群 ID 查询 `vault wechat-chatroom-list`
 
 ```bash