gangtise-openapi-cli 0.51.0 → 0.52.0

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

@@ -51,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 前缀推断）：
 
@@ -63,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` 就能正常取数
@@ -142,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 / <各指标名>…`；无命中返回空表
@@ -359,13 +359,14 @@ gangtise indicator cross-section --indicator scr_indu \
 
 | 指标 | 体系 | 参数 |
 | :-- | :-- | :-- |
-| `scr_indu_citic` | 中信行业 | `industryLevel`（**可选**，取值同上；不传为全路径）。`parameterList` 现列为空，但 `--date` 照常传、不会被拒 |
+| `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:industryType=3`，`scr_indu` 下线后 EDE 不再提供恒生行业。
@@ -451,6 +452,48 @@ gangtise indicator cross-section --indicator finc_pe_ttm_quantile --indicator-pa
 - **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` 已搜不到，取数暂时仍可用，**存量取数尽快迁走**：
@@ -498,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`
@@ -507,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` |

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` 即另一空间的根目录

package/gangtise-openapi/references/errors.md

@@ -1,7 +1,7 @@
 # 错误码、退出码与常见困境自救
 
 > 主文件 `SKILL.md` 只保留最高频的几个码；这里是全表。
-> **退出码语义**：`0` 完整成功（含合法空结果）／ `3` 有数据但不完整（`partial: true`）／ `4` 导出的数据完整，但 `--output` 已被另一次导出替换（见下文「退出码 4」）／ `1` 硬失败／ `130` / `143` / `129` 被 Ctrl-C / `kill` / 终端断开中断（进程以该信号结束；本次导出的暂存文件已删除；中断前已发出的请求服务端照常处理并计费）。
+> **退出码语义**：`0` 完整成功（含合法空结果）／ `3` 有数据但不完整（`partial: true`）／ `4` 导出的数据完整，但 `--output` 已被另一次导出替换（见下文「退出码 4」）／ `1` 硬失败（请求可能已发出、可能已计费）／ `2` 发请求前就被拒：未知选项、取值不合法、缺必选项或 `--yes`、`--output` 是目录、未配凭证——没有发出任何请求，不计费，改了重跑即可（同类报错若发生在已经发过请求之后，例如按条计费的列表先取了 total 才被额度保护拦下，仍是 `1`）／ `130` / `143` / `129` 被 Ctrl-C / `kill` / 终端断开中断（进程以该信号结束；本次导出的暂存文件已删除；中断前已发出的请求服务端照常处理并计费）。
 > 报错行末尾的 `[trace <id>]` 是 Gangtise 支持定位问题的唯一凭据，**报障时带上它**。
 
 ## 错误码怎么读
@@ -138,6 +138,6 @@
 
 **同一公司既是股票又是 DR** → `securities-search` 默认返回所有分类 → 加 `--category stock` 收敛。
 
-**`--category stock` / `fund` 的结果里出现 `category: bond`** → 可转债不受 `--category` 约束、按简称查时常排第一（如「甬金」→ `113636.SH 甬金转债`） → 只取 `category` 等于所查类别的行；查股票可改用公司全称，查基金换更具体的基金简称。债券代码传给基金命令返回空结果、不报错，传给股票行情 / 财报报 `120001`。
+**按简称查股票，第一条是 `category: bond`** → 没带 `--category`，同名可转债排在了正股前面（如「甬金」→ `113636.SH 甬金转债`） → 加 `--category stock`。债券代码传给基金命令返回空结果、不报错，传给股票行情 / 财报报 `120001`。
 
 **`sector-constituents` 返回 0 条** → sectorId 不对（题材 conceptId 与板块 sectorId 是两套 ID，不通用）→ 先 `reference sector-search --keyword <名>` 拿 `sectorId` 重试。

package/gangtise-openapi/references/examples.md

@@ -137,7 +137,7 @@
 1. 路由 → insight research list；公司名不在速查表
 2. 先调 reference securities-search：
      gangtise reference securities-search --keyword 蔚蓝生物 --category stock --top 3 --format json
-   取第一条 category 为 stock 的 gtsCode = "603739.SH"（按简称查时同名可转债可能排在前面）
+   取第一条 category 为 stock 的 gtsCode = "603739.SH"
 3. 拼正式查询：
      gangtise insight research list --security 603739.SH --rank-type 2 \
        --start-time "<今天-7天> 00:00:00" --end-time "<今天> 23:59:59" --format json
@@ -284,8 +284,8 @@
    - --rank-type 1 在有 keyword 时按相关度挑条目；要最新就用 --rank-type 2 --search-type 2
      （--search-type 2 = 全文，只扩大 --rank-type 2 的候选池，不改变 --rank-type 1 取回哪些条目）
    - 筛选项比 summary 少：没有 --source / --institution / --participant-role
-3. 🔴 别拉全量再本地按类别/市场分组——categoryList / conceptList / marketList 这几个标签字段稀疏，
-   是否有值随记录和查法而变（用该字段过滤时回填率更高，详见 insight.md）。要分组就让服务端筛：
+3. 🔴 别拉全量再本地按类别/市场分组——不按 --category / --market 筛时 categoryList 为空，
+   marketList 不含 aShares / usChinaConcept（详见 insight.md）。要分组就让服务端筛：
      gangtise insight pamirs-summary list --category industryAnalysis --market aShares --size 50
 4. 下载（省略 --output 自动用标题命名）：
      gangtise insight pamirs-summary download --summary-id 5863771 --file-type 2

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

@@ -70,6 +70,19 @@
 
 ---
 
+## GICS 一级行业（insight overseas-opinion --industry 参数）
+
+只用于 `insight overseas-opinion list --industry`；申万码、中信码在这里报 `100005`。`reference constant-list --category gicsIndustry` 返回同一套 ID。
+
+| ID | 行业 | ID | 行业 | ID | 行业 |
+|----|------|----|------|----|------|
+| 107700001 | 能源 | 107700002 | 原材料 | 107700003 | 工业 |
+| 107700004 | 非日常生活消费品 | 107700005 | 日常消费品 | 107700006 | 医疗保健 |
+| 107700007 | 金融 | 107700008 | 信息技术 | 107700009 | 通讯业务 |
+| 107700010 | 公用事业 | 107700011 | 房地产 | | |
+
+---
+
 ## 常用券商（--broker 参数）
 
 完整列表用 `lookup broker-org list`

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

@@ -25,7 +25,7 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | insight opinion detail | `{total, list}`；缺失时另有 `missingIds` / `unfetchedIds` / `unfetchedError` + `partial` | `list[]` 同 list 的字段 + `content`（正文全文） |
 | insight summary list | `{list, total}` | `list[].summaryId` / `list[].title` / `list[].publishTime` |
 | insight summary download | 文件路径（stdout） | — |
-| insight pamirs-summary list | `{list, total}` | `list[].summaryId` / `list[].title` / `list[].brief` / `list[].summaryTime`（纪要生成时间）/ `list[].publishTime`（发布时间）/ `list[].securityList[]{securityCode, securityName}` / `list[].researchAreaList[]{researchAreaId, researchAreaName}` / `list[].conceptList[]{conceptId, conceptName}` / `list[].categoryList` / `list[].marketList`。⚠️ `conceptList` / `categoryList` / `marketList` 三个标签字段**稀疏，且是否有值随记录和查法而变**：不带筛选时经常整条为空，用 `--category` 或 `--market` 任一过滤时回填率明显更高（这两个字段绑定，一起有或一起没有）。所以**别拉全量再本地分组**（会漏记录），也**别据此断言某条记录没有该属性**（为空只说明这次没回填）。详见 `commands/insight.md` |
+| insight pamirs-summary list | `{list, total}` | `list[].summaryId` / `list[].title` / `list[].brief` / `list[].summaryTime`（纪要生成时间）/ `list[].publishTime`（发布时间）/ `list[].securityList[]{securityCode, securityName}` / `list[].researchAreaList[]{researchAreaId, researchAreaName}` / `list[].conceptList[]{conceptId, conceptName}` / `list[].categoryList` / `list[].marketList`。⚠️ `categoryList` / `marketList` **只在按 `--category` 或 `--market` 筛选时返回完整**：其余查法下 `categoryList` 为空、`marketList` 不含 `aShares` / `usChinaConcept`。所以**别拉全量再按这两个字段本地分组**（A 股、中概股归属会整批缺失），也**别据此断言某条记录没有该属性**。`conceptList` 不随查法变。详见 `commands/insight.md` |
 | insight pamirs-summary download | 文件路径（stdout） | — |
 | insight roadshow / site-visit / strategy / forum list | `{list, total}` | 各自的 ID：`list[].roadshowId` / `siteVisitId` / `strategyMeetingId` / `forumId`；`list[].title` / `list[].startTime` / `list[].endTime`（举办时间）/ `list[].publishTime`（首次收录时间，可为 `null`）/ `list[].location`；路演、调研、策略会另有 `list[].institutionList[]{institutionId, institutionName}`（论坛没有） |
 | insight research list | `{list, total}` | `list[].reportId` / `list[].title` / `list[].brief`（全文摘要） / `list[].publishTime` / `list[].publisher.brokerName` / `list[].securityList[].rating` |
@@ -42,6 +42,8 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | insight foreign-opinion detail | 同 opinion detail | `list[]` 同 list 的字段 + `content`（原文）/ `contentTranslate`（中文译文） |
 | insight independent-opinion list | `{list, total}` | `list[].independentOpinionId` / `list[].titleTranslate` / `list[].briefTranslate` / `list[].publishTime` / `list[].analyst.analystName` |
 | insight independent-opinion download | 文件路径（stdout） | — |
+| insight overseas-opinion list | `{list, total}` | `list[].overseasOpinionId`（`detail` 用）/ `list[].accountId` / `list[].accountName` / `list[].publishTime` / `list[].originalFlag`（1 原创 / 0 转发）/ `list[].categoryList[]`（类别，可多个、可为空数组）/ `list[].brief` / `list[].briefTranslate` / `list[].forwardPost{accountName, publishTime, brief, briefTranslate}`（原创为 `null`）/ `list[].industryList[]{industryId, industryName}` / `list[].securityList[]{securityCode, securityName}` / `list[].regionList[]{regionCode, regionName}` |
+| insight overseas-opinion detail | 同 opinion detail | `list[]` 同 list 的字段，以 `content`（原文）/ `contentTranslate`（中文译文）代替 `brief` / `briefTranslate`（`forwardPost` 内同） |
 | insight official-account list | `{list, total}` | `list[].articleId` / `list[].accountName` / `list[].title` / `list[].publishTime` / `list[].articleCategory` / `list[].summary` / `list[].industryList[].industryName` / `list[].conceptList[].conceptName` / `list[].securityList[].securityCode` |
 | insight official-account download | 文件路径（stdout） | — |
 | insight qa list | `{list, total}` | `list[].source`（conference/interactive/survey）/ `list[].publishTime` / `list[].question` / `list[].answer` / `list[].member` / `list[].securityCode` / `list[].questionCategory[]` / `list[].answerImportant`（1/0） |
@@ -55,6 +57,7 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | reference securities-search | `{returnedCount, list}` | `list[].gtsCode` / `list[].gtsName` / `list[].category` / `list[].matchScore` / `list[].matchType` |
 | reference chiefs-search | `{returnedCount, list}` | `list[].chiefId` / `list[].chiefName` / `list[].institution` / `list[].team` / `list[].matchScore` |
 | reference institution-search | `{returnedCount, list}` | `list[].institutionId` / `list[].institutionName` / `list[].category` / `list[].usageScopes[{apiName, paramName}]` / `list[].matchScore` |
+| reference overseas-account-search | `{list, total}` | `list[].accountId`（喂 `insight overseas-opinion list --account`）/ `list[].accountName` / `list[].accountIntroduction` / `list[].matchScore` |
 | reference official-account-search | `{returnedCount, list}` | `list[].accountId`（喂 `insight official-account list --account-id`）/ `list[].accountName` / `list[].category`（四类或 `null`）/ `list[].matchScore` |
 | reference constant-category | `{total, list}` | `list[].category` / `list[].categoryName` / `list[].structureType`（flat/tree） / `list[].maxLevel` / `list[].usageScopes[].apiName` / `.paramName` |
 | reference constant-list | `{category, structureType, maxLevel, constantCount, list}`（CLI 把 `constants` 规范化为 `list`） | `list[].constantId` / `list[].constantName` / `list[].level`；树形分类父节点含 `list[].children[]`（递归同构） |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gangtise-openapi-cli",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "CLI for Gangtise OpenAPI",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "commander": "^14.0.0",
-    "undici": "^7.30.1"
+    "undici": "^7.30.2"
   },
   "devDependencies": {
     "@types/node": "^20.19.43",