gangtise-openapi-cli 0.30.1 → 0.32.0

package/gangtise-openapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gangtise-openapi
-version: "0.30.1"
+version: "0.32.0"
 description: |-
   通过 gangtise CLI 直接调用 Gangtise OpenAPI，拉取投研原始数据、批量导出、下载文件、调用 AI 能力。
 
@@ -36,7 +36,7 @@ description: |-
    - Token 失效（`0000001008` / `999002`，含已废弃的 `8000014`/`8000015`）→ 自动重新登录并重试一次；凭证错 `999011` → **不重试**（AK/SK 不对不会自己好），查环境变量
 8. **参数命名差异**：Insight/Quote/Vault 用 `--security`，Fundamental/AI 用 `--security-code`（例外：`ai stock-summary` 用 `--security`，`ai security-clue` 用 `--gts-code`）。
 9. **调试**：`--verbose` 或 `GANGTISE_VERBOSE=1` 打印每个请求的耗时/字节数到 stderr。
-10. **`--field` 字段名必须核对，不确定就别传**（返回全量最稳）：`quote realtime` / `fundamental main-business` / `valuation-analysis` 遇到不存在的字段名时，上游只丢**值**、字段名照请求**回显**，按位置拍平会把值贴到错误的字段上（实测 realtime 传 `close`——它没有这个字段——换手率 28.5573 被贴成 `close`，茅台真实价 1297.41）。v0.28.3 起 CLI 检测到长度不匹配直接报错（退出码 1）：**带 `--field` 的命令看到这个报错，先去 `references/fields.md` 核对字段名**（没有 `--field` 的命令如 `alternative edb-data` 报此错则是上游响应结构异常，报障时若报错末尾附了 `（trace …）` 就一并带上）。另：realtime **无 `close`**（用 `latestPrice`）、**无市值**（总市值走 `indicator cross-section --indicator qte_mkt_cptl`，仅 A 股）。
+10. **`--field` 字段名必须核对，不确定就别传**（返回全量最稳）：`quote realtime` / `fundamental main-business` / `valuation-analysis` 遇到不存在的字段名时，上游只丢**值**、字段名照请求**回显**，按位置拍平会把值贴到错误的字段上（实测 realtime 传 `close`——它没有这个字段——换手率 28.5573 被贴成 `close`，茅台真实价 1297.41）。v0.28.3 起 CLI 检测到长度不匹配直接报错（退出码 1）：**带 `--field` 的命令看到这个报错，先去 `references/fields.md` 核对字段名**（没有 `--field` 的命令如 `alternative edb-data` 报此错则是上游响应结构异常，报障时若报错末尾附了 `（trace …）` 就一并带上）。另：realtime **无 `close`**（用 `latestPrice`）、**无市值**（总市值走 `indicator cross-section --indicator qte_mkt_cptl`，2026-08-03 起 A/港/美股均有数）。
 
 ## 工作流（3 步）
 
@@ -65,7 +65,7 @@ description: |-
 
 ### 积分计费速查
 
-"免费"=0 积分；**只列单价**，数据范围（可查多久）随账号等级不同、不在此列。
+"免费"=0 积分；**只列单价**，数据范围见下一节。
 
 - **免费**：所有 `quote` 行情、`fundamental` 报表/主营/估值/股东（**盈利预测除外**）、`reference`/`constant` 查询（含 `official-account-search`）、`alternative edb-search`、`vault`（record/wechat/股票池/drive/AI云盘）、`insight report-image list`
 - **0.1/条 list**：research / foreign-report / official-account / announcement(A/港/美) / summary / qa / performance-calendar 的 list、`vault my-conference-list`；`insight report-image download` 0.1/张
@@ -74,8 +74,23 @@ description: |-
 - **按页**：`tool file-parse` 0.8/页，**提交（`--file`）时按实际页数一次性扣**，取结果（`file-parse-check`）免费——50 页 PDF = 40 积分，别重复提交同一文件
 - 🔴 **按次贵**：`ai knowledge-batch` 10、`management-discuss-*` 10；AI Agent（`one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `earnings-review` / `viewpoint-debate` / `theme-tracking`）**50/次**；`ai hot-topic` 50/篇
 - 🔴 **极贵**：`alternative concept-info` / `concept-securities` **500/次**
-- ⚠️ **同参数重复调用不免费**：按次计费无缓存命中豁免（2026-07-11 实测 `one-pager` 重复调用每次扣分，即使秒回缓存内容）——生成类结果拿到后自行留存复用，别为"刷新"重调；CLI 已对上述 🔴 贵档端点关闭 5xx/超时自动重放（v0.26.0），50/篇 的 `summary` / `foreign-report` / `my-conference` download 同样不重放（v0.27.0），正是为防重复扣分
+- ⚠️ **同参数重复调用不免费**：按次计费无缓存命中豁免（2026-07-11 实测 `one-pager` 重复调用每次扣分，即使秒回缓存内容）——生成类结果拿到后自行留存复用，别为"刷新"重调；CLI 已对上述 🔴 贵档端点关闭 5xx/超时自动重放，50/篇 的 `summary` / `foreign-report` / `my-conference` download、单价未公布但保守同档处理的 `pamirs-summary` download、以及 `tool file-parse` 的提交，同样不重放（共 18 个端点），正是为防重复扣分
 - **按单元格**：`indicator cross-section` / `time-series` / `screener`（A股 0.05 / 港股 0.1 / 美股 0.2 积分每 100 单元格；screener 按**筛选前**范围计费，见 `indicator.md`）；`ai knowledge-resource-download` 按下游资源计费
+- **单价未公布**：`insight pamirs-summary list` / `download`——spec 只写了「需购买专家纪要数据库」这个准入门槛，没给单次价格。**别据此假定免费**；大批量拉取前先小量试，或向平台确认
+
+### 数据范围（能查多久）
+
+2026-08-07 官方放宽后的**正式账号**口径（下表是官方公布值；本机验证账号另开了 10 年定制权限，所以实测范围比这宽，**别拿本仓库的实测数字当平台口径**）：
+
+| 命令组 | 可回溯 |
+|--------|--------|
+| `quote` 行情 / `fundamental` 财报、主营、估值、股东 / `indicator`（EDE） | 前溯 **5 年**（原 3 年） |
+| `ai security-clue` 投研线索 | 前溯 **1 个月**（原 7 天） |
+| 主题 / 热点 / QA / 日程（路演·调研·策略会·论坛）/ 纪要 / 观点 / 研报 / 公众号 | 前溯 **3 个月**（原 1 个月） |
+| 管理层讨论 / A·港·美股公告 / `alternative edb-*` 行业指标 | 前溯 **3 年**（原 1 年） |
+| `insight pamirs-summary` 帕米尔纪要 | **不限**（但需单独购买专家纪要库） |
+
+⚠️ **这是官方口径，不是硬边界**：实际范围按账号等级而定，**同一账号下按接口还可能不同**（实测 `indicator screener` 仍卡 today−3 年，而同模块的 `cross-section`/`time-series` 已放宽）。超范围查询返回 `110003`，**不是空结果**——拿到 `110003` 就是撞了权限边界，缩窗口对「整段都在界外」的查询无效，要把日期移进范围或联系客户经理。
 
 ### 下载规则（`--file-type` / `--content-type`）
 
@@ -85,6 +100,7 @@ description: |-
 | `insight foreign-report download` | `--file-type` | `1` PDF / `2` MD / `3` 中译 PDF / `4` 中译 MD |
 | `insight announcement download` | `--file-type` | `1` PDF / `2` Markdown |
 | `insight summary download` | `--file-type`（可选） | `1` 原始（默认）/ `2` HTML（仅会议平台来源） |
+| `insight pamirs-summary download` | `--file-type`（可选） | `1` 原始（默认）/ `2` HTML（仅此两种） |
 | `insight independent-opinion download` | `--file-type` **必选** | `1` 原文 HTML / `2` 翻译 HTML |
 | `insight announcement-hk download` | `--file-type` | `1` 原始（默认）/ `2` Markdown |
 | `insight announcement-us download` | `--file-type` | `1` 原始 PDF（默认）/ `2` Markdown |
@@ -104,6 +120,7 @@ description: |-
 | 外资机构观点 / 外资券商观点 | `insight foreign-opinion list` |
 | 外资独立观点 / 独立分析师观点 | `insight independent-opinion list` |
 | 纪要 / 会议纪要（外部） | `insight summary list` |
+| 帕米尔纪要 / 帕米尔专家纪要 / Pamirs | `insight pamirs-summary list`（专家纪要库，需单独购买；筛选项比 `summary` 少，无 `--source`/`--institution`/`--participant-role`） |
 | 路演 / 调研 / 策略会 / 论坛 | `insight roadshow / site-visit / strategy / forum list` |
 | 财报日历 / 业绩预告 / 业绩快报 / 财报披露排期 | `insight performance-calendar list`（**用 `--start-date`/`--end-date`，不是 `--start-time`**；全表 >12 万条，CLI 强制要求日期范围 / `--security` / `--size` 三者至少其一；只给 `--security` 时另有 1000 行隐式上限，撞上限且 total 还有剩余=筛选可能没生效（标 `partial`、退出码 3），改用日期范围重查。下载原文 `performance-calendar download --performance-report-id`，仅 `hasAttachment: true` 可下） |
 | A 股公告 / 公告 | `insight announcement list` |
@@ -161,19 +178,21 @@ description: |-
 | PDF 转 Markdown / 解析文件 / 提取 PDF 正文 | `tool file-parse --file <x.pdf> --wait`（异步，0.8 积分/页，提交时扣；取结果 `tool file-parse-check --task-id`。**平台自有研报/公告优先用各 download 的 `--file-type 2` 直出 Markdown**，别花解析费） |
 
 **易混淆消歧**：
-- "纪要" → 外部信息走 `insight summary`；公司内部录音/会议走 `vault my-conference`
+- "纪要" → 外部信息走 `insight summary`；明确点名"帕米尔 / Pamirs"才走 `insight pamirs-summary`（另一个库，不是 `summary` 的子集）；公司内部录音/会议走 `vault my-conference`
 - "搜索 X" → 数据维度精确（按行业/券商）走对应 `insight ... list`；跨类型语义搜索走 `ai knowledge-batch`
 - 港股代码用在 `insight foreign-opinion --security` 还是 `quote day-kline-hk --security`？前者要"境外"格式（`UBER.N`），后者要 `.HK`
 - "成分股" → 题材深度（分组/重点标记/纳入理由）走 `alternative concept-securities`；板块（行业/概念分类树，纯代码名单）走 `reference sector-constituents`
 - **证券基本面 / 指标先按任务形态路由，不是搜到 EDE 就一律走 EDE**：
-  - 单证券先优先对应 `fundamental` 专用命令（财务、估值、盈利预测、股东、主营或完整三大报表，多数免费 / 低价）。其中 `valuation-analysis` / `earning-forecast` 实测仅支持 A 股；港 / 美股的估值历史分位、盈利预测、以及 PE/PB 等核心估值（EDE 也仅 A 股）当前 CLI 均无可用接口，如实说明不支持、勿用别的语义顶替
-  - 多证券批量取一组**已实现**财务 / 估值指标 → 优先 `indicator search` 后用 EDE 一次拉取，替代逐只循环；单日或同一报告期横向比较用 `cross-section`，区间走势用 `time-series`（后者不能多指标 × 多证券同时）。**批量按 code 回填加 `--key-by code`**（列头用 `indicatorCode`，防同名指标碰撞 + 服务端重排列序导致的错位）
-  - 始终排除 EDE：A股盈利预测 / 一致预期（含预测 EPS）→ `fundamental earning-forecast`；A股估值历史分位 → `fundamental valuation-analysis`；开高低收 / 成交量等行情与 K 线 → `quote`；单证券完整报表 → 对应三大报表命令。**例外：总市值只有 EDE 有**——`quote realtime` / `day-kline` 都不返回市值，走 `indicator cross-section --indicator qte_mkt_cptl`（仅 A 股，默认单位「元」，用 `--scale` 缩放）。EDE 搜到的基本 / 稀释 EPS 是已实现值，**不能冒充预测 EPS**；港 / 美股缺少上述专用能力时应如实说明不支持，不能用别的语义代替
+  - 单证券先优先对应 `fundamental` 专用命令（财务、估值、盈利预测、股东、主营或完整三大报表，多数免费 / 低价）。其中 `valuation-analysis` / `earning-forecast` 实测仅支持 A 股，港 / 美股的**估值历史分位**与**盈利预测**当前无可用口径。但**估值指标本身别照抄旧结论**：2026-08-03 实测 `finc_pe_ttm` 港股已有数、`qte_mkt_cptl`/`shr_tot` 港美股都已有数。⚠️ **凡「仅 A 股」「无数据」这类否定结论都只是某时点抽查**，服务端在持续补数据；负面结论过期不会报错、只会让你白白拒掉一个能跑的查询。**一律以当次 `scopeList` + 抽查为准**
+  - 多证券批量取一组**已实现**财务 / 估值指标 → 优先 `indicator search` 后用 EDE 一次拉取，替代逐只循环；单日或同一报告期横向比较用 `cross-section`，区间走势用 `time-series`（后者不能多指标 × 多证券同时）。**批量按 code 回填加 `--key-by code`**（列头用 `indicatorCode`，防同名指标碰撞）。⚠️ **两个轴的顺序规则不同**：`indicatorList` = 请求顺序，但 **`securityCodeList` 是按代码升序重排的**（请求 `000858,600519,000001` → 回 `000001,000858,600519`）——**行绝不能按请求下标对位**，一律按 `security` 字段取值
+  - ⚠️ **估值指标的历史序列：两个接口的财报口径切换时点不同**——`indicator time-series`（EDE）按**正式财报披露日**切，`fundamental valuation-analysis` 按**业绩快报**口径切、通常更早，所以同一天取到的估值指标可能不一样（已验证 `finc_pe_ttm`/`peTtm`；`finc_pb_mrq` 等非 TTM 口径同样在报告期节点变化，规则未单独验证）。做估值分位 / 回测时**两个接口都拉一遍交叉核**，尤其业绩大幅变动的标的（抽查中出现过个别标的在 `valuation-analysis` 侧长期未更新）。分叉时用「总市值 ÷ PE 反推隐含净利润」对照利润表滚动 TTM，即可判出哪侧是陈值。**判断某财报在某日是否已公开，查 `insight announcement list` 的公告披露日**，不要用 `fundamental income-statement` 返回的 `announcementDate`（实测该字段会把季报披露日填成年报日）。
+  - 始终排除 EDE：A股盈利预测 / 一致预期（含预测 EPS）→ `fundamental earning-forecast`；A股估值历史分位 → `fundamental valuation-analysis`；开高低收 / 成交量等行情与 K 线 → `quote`；单证券完整报表 → 对应三大报表命令。**例外：总市值只有 EDE 有**——`quote realtime` / `day-kline` 都不返回市值，走 `indicator cross-section --indicator qte_mkt_cptl`（2026-08-03 起 A/港/美股均有数，默认单位「元」，用 `--scale` 缩放）。EDE 搜到的基本 / 稀释 EPS 是已实现值，**不能冒充预测 EPS**；港 / 美股缺少上述专用能力时应如实说明不支持，不能用别的语义代替
   - EDE 取数前必须用 `search --format json` 同时核对：`indicatorName` + `description` 语义准确、`scopeList` 覆盖全部目标市场 / 证券类型、`parameterList` 必填参数与枚举可满足；`scopeList` 缺失 / `null` / 空或任一项不符，都视为无法证明覆盖并回退专用接口。专用接口也不覆盖目标市场时，说明当前不可用，不要硬调。`scopeList` 按指标各不相同，不能因 EDE 服务支持 A / 港 / 美股就假定某个指标三市场都覆盖
   - `indicator search` 免费，`cross-section` / `time-series` 按单元格计费；除多证券批量的效率收益外，仍优先免费 / 低价的 `quote` 或 `fundamental`
 - 行业 / 宏观指标（空调销量、社融等，无证券维度）走 `alternative edb-*`（EDB），不要与证券级 EDE 混用
-- EDE 缺数据分三档，**别只认 `null`**：部分缺 → 单元格 `null`（行列都在）；某指标对所有证券都无数据 → **整列消失**；某证券对所有指标都无数据 → **整行消失**；整个查询无数据 → **空表**（2026-08-01 起不再报 `999999`）。后三种退出码都是 0，`--key-by code` 回填时 key 会直接不存在。CLI 已在 stderr 提示被整个略过的指标/证券。**参数写错也表现为空表**，拿到空表先查参数名和日期语义，别当成真没数据。日期语义按指标分三类：财务报表指标=报告期末（可为非交易日）、`finc_pe_ttm` 等日频估值=最新交易日、`finc_pb_mrq`(MRQ) 等=最近报告期末（交易日取 `null`）；混合取数按各自有效日期分次 `cross-section` 再按证券合并，别塞进同一个 `--date`。详见 `references/commands/indicator.md`
-- **EDE 指标参数名一律以 `indicator search --format json` 的 `parameterList` 为准**，不要凭记忆或照抄示例：服务端会改参数名（`adjustmentType` → `adjustType`，2026-08-01），**传错名是静默忽略、退回默认值**而不是报错——实测 `adjustmentType=3` 返回的是不复权价，看着正常实则错数据。`--security` 支持板块 ID（`reference sector-search` 的 10 位 `sectorId`；`--indicator` 只收指标编码）。⚠️ 根级 `--scale` 会污染不声明 `scale` 的指标（`qte_close` 被 `--scale 8` 缩成 `0`），价格与金额混查时改用 `--indicator-param "code:scale=8"`
+- **EDE「没数据」和「代码写错」是两回事**（2026-08-08 实测）：①代码有效但无数据 / 无覆盖 / 未来日期 → 单元格 `null`，**行列都保留**（含单指标 × 单证券的 1×1），**退出码 0**；②**指标 code 认不出来** → 该指标整列消失；③**证券 code 认不出来**（拼错，或美股用了 `.US` 而非 `.O`/`.N`）→ 该证券整行消失——②③ CLI 标 `partial: true` + `omittedIndicators`/`omittedSecurities` 并**退出码 3**（**`screener` 例外见下**），`--key-by code` 回填时 key 会直接不存在；④请求里没有任何可解析的 code → **空表**，退出码 0 + stderr 提示。**所以退出码 3 现在读作「你有 code 写错了」，不是「这批数据不完整」**——⚠️ 但它**需要同批有对照物**：整个轴都写错（比如只查一个指标而它拼错了）拿到的是空表 + 退出码 0，所以**空表的第一嫌疑是拼写和证券后缀，不是没数据**；反过来，真实的覆盖缺口一眼可见（就是 `null`），不用再靠「和已知有数的标的一起查」做对照。拿到空表先查证券后缀和 code 拼写，再查参数名。日期语义按指标分两类：财务报表指标=报告期末（可为非交易日）、`finc_pe_ttm` / `finc_pb_mrq` 等日频估值=最新交易日（⚠️ `finc_pb_mrq` 是日频的，用报告期末日期会取到几个月前的陈值）；混合取数按各自有效日期分次 `cross-section` 再按证券合并，别塞进同一个 `--date`。详见 `references/commands/indicator.md`
+- **EDE 指标参数名一律以 `indicator search --format json` 的 `parameterList` 为准**，不要凭记忆或照抄示例：**参数名写错不报错、按默认值取数**——如复权参数是 `adjustType`，写成 `adjustmentType` 会返回不复权价，看着正常实则口径不对。`--security` 支持板块 ID（`reference sector-search` 的 10 位 `sectorId`；`--indicator` 只收指标编码）。✅ 根级 `--scale` 污染不声明 `scale` 的指标（`qte_close` 被 `--scale 8` 缩成 `0`）**已于 2026-08-08 修复**，价格与金额可以混查了
+- **2026-08-07 新增指标**：融资融券 21 个 `mgn_*`（`mgn_bal` 两融余额 / `mgn_fin_*` 融资 / `mgn_sl_*` 融券 / `mgn_flag` 是否标的，**仅 A 股有数**）；行业分类 `scr_indu`（一个指标覆盖申万/中信/恒生/GICS 四套，**必填** `industryType` 1-4 + `industryLevel` 0-4，A/港/美股均支持，返回字符串）
 - "业绩点评"双义消歧：**检索已有**（研报/纪要里的业绩点评内容）走 `insight ... list --llm-tag earningsReview`（0.1/条）；**AI 现生成**一份走 `ai earnings-review`（异步、50/次）。不确定问一句
 
 ## 公司名 → 证券代码
@@ -245,7 +264,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 
 日期参数**按参数名判断、不按命令组**（命令组会误导——AI 里既有 `--start-time` 又有 `--date`/`--report-date`；Insight 里 `performance-calendar` 是唯一用 `--start-date`/`--end-date` 的 list）：名字带 `-date` 的（`--start-date`/`--end-date`/`--date`/`--report-date`）一律 `YYYY-MM-DD`，覆盖 Quote/Fundamental、`insight performance-calendar`、AI 的 `theme-tracking`(`--date`)/`hot-topic`/`management-discuss-*`(`--report-date`)、Alternative `edb-data`、Indicator `cross-section`(`--date`)/`time-series`；名字带 `-time` 的（`--start-time`/`--end-time`）用 `YYYY-MM-DD[ HH:mm[:ss]]`（秒可省、空格或 `T` 分隔）或 10/13 位时间戳，覆盖 Insight/Vault 各 list、`quote minute-kline`、`ai security-clue`、`ai knowledge-batch`。其中 **A 股公告（`insight announcement list`）与 `knowledge-batch` 会把输入转成 13 位毫秒**（10 位秒自动 ×1000），其余 `-time` 命令（含 `announcement-hk`/`announcement-us`）原样透传字符串；CLI 输入统一接受 10/13 位纯数字或 `YYYY-MM-DD[ HH:mm[:ss]]`（同上：秒可省、空格或 `T` 分隔）。
 
-支持时间倒序的命令加 `--rank-type 2`：opinion / summary / research / foreign-report / announcement / announcement-hk / announcement-us / foreign-opinion / independent-opinion / official-account。其他 list 命令按 API 默认排序。
+支持时间倒序的命令加 `--rank-type 2`：opinion / summary / pamirs-summary / research / foreign-report / announcement / announcement-hk / announcement-us / foreign-opinion / independent-opinion / official-account（⚠️ **只实测过 `pamirs-summary` / `summary` / `research` 三个，另外 8 个未验证、别外推**。在这三个上：`--rank-type 2` 是严格时间倒序；`1`=综合排序只在带 `--keyword` 时才有差异，且强弱不同——`pamirs-summary --search-type 2` 是真正的相关度重排，`summary`/`research` 的 `1` 仍是时间倒序、只改变同一时间戳内几条的先后。未验证的端点按后者的保守预期对待。详见 `insight.md` 开头）。其他 list 命令按 API 默认排序。
 
 ## 异常处理
 
@@ -264,7 +283,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 | 错误码 | 含义 | CLI 行为 | Agent 是否介入 |
 |--------|------|---------|--------------|
 | ✅ `100003` | 参数值非法——**最宽的兜底码**：类型错、`limit` 越界都归这里。**msg 通常已指明字段**（如「请求体字段类型不匹配: size 期望类型 Integer」「limit 最小为 1，最大为 10000」），先读 msg 再猜 | — | 按 msg 指的字段改；msg 没指明才对照 `--help` 查枚举拼写，**不要重试同命令** |
-| ✅ `999999` | 系统错误。**`indicator`（EDE）2026-08-01 前用此码表示查询无数据，现已改为返回空数组**，所以这个码基本只剩真故障 | 普通端点自动重试 ×2；🔴 贵档与 `indicator` 端点不重试 | 确认参数无误仍报此码即服务端故障 |
+| ✅ `999999` | 系统错误。**`indicator`（EDE）2026-08-01 前用此码表示查询无数据，之后改为返回数据体**，所以这个码基本只剩真故障。⚠️ 现在「无数据」是保留行列的 `null` 单元格，**不是空表**；空表另有含义（整轴 code 未识别） | 普通端点自动重试 ×2；🔴 贵档与 `indicator` 端点不重试 | 确认参数无误仍报此码即服务端故障 |
 | ✅ `410110` | **异步生成中**（HTTP 400，旧码未切）。新码 `140001`，CLI 两码都认 | 轮询视为 pending | 继续等 |
 | ✅ `410111` | **异步生成失败**（HTTP 400，旧码未切）。新码 `140002`，CLI 两码都认 | 终态 | **不重试**，换参数 |
 | ✅ `130002` | 资源不存在——**下载类的兜底码**：`reportId` 不存在 / 非数字 / `fileType` 非法**全归这里**（`130003`/`130004`/`130005` 实测均未启用） | — | 确认 ID 有效且本账号可见；换 `--file-type` 或换一篇验证 |
@@ -272,6 +291,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 | ✅ `100001` | 缺必填参数——**msg 带字段名**（「缺少必填参数: reportId」） | — | 按 msg 指的字段补上 |
 | ✅ `110001` / `110002` | 日期格式错（msg 带字段名）/ 起晚于止。**哪个格式报错、哪个被静默误读是端点相关的**（实测 `fundamental` 对 `2020/01/01` 报 110001，`insight research list` 对 `30/06/2025` 却宽松解析返回数据）——别按命令组预判 | — | 按参数名：`--*-date` 用 `YYYY-MM-DD`、`--*-time` 用 `YYYY-MM-DD HH:mm:ss`；`ai knowledge-batch` 的 --start-time/--end-time 收时间戳或 datetime，CLI 统一转 13 位毫秒 |
 | ✅ `120001` | 证券代码无效——msg 带原因（「非有效A股」）。**只有 Fundamental 系报**，Quote 系静默返回空 | — | `reference securities-search` 确认代码与后缀（`600519.SH` / `00700.HK`） |
+| ✅ `110003` | **超出账号数据权限的时间范围**。范围按账号等级而定、**不是平台常量**，且**同一账号下按接口还可能不一样**——本机 10 年定制权限账号上实测 `indicator screener` 仍卡 today−3 年，而同模块的 `cross-section`/`time-series` 已放宽（正式账号是否同样如此未验证） | — | 把日期移进权限范围内；整个区间都早于下界时缩短窗口无用（`--fiscal-year 2015` 无论怎么缩都报错）。`screener` 撞界改用 `cross-section` 拉数再本地筛，否则联系客户经理开通 |
 | ✅ `100006` | 查询/下载数量超限——**取代旧 `430007`**；实测 `fund-flow` 全市场不传日期即此码 | — | 缩短日期范围或调小 `--size`/`--limit`；全市场场景应已自动分片 |
 | ✅ `240001` | 财报期未披露或超出查询期（`earnings-review` 提交阶段就报，**不扣积分**） | — | 换更早的 `--period`（`2025q3` → `2025interim`） |
 | ✅ `250001` | 不支持的数据源——**取代旧 `433007`** | — | 检查 `resourceType + sourceId` 组合 |
@@ -279,14 +299,14 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 | ✅ `999010` | 接口地址不存在 | — | `raw call` 的 key 可能已下线，用 `gangtise raw list` 核对 |
 | ✅ `0000001008` | Token 服务端失效（他处登录挤掉）——**旧码未切，token 自愈依赖它** | **强制重新登录并重试一次** | 无 AK/SK 时无法自愈，提示重新登录 |
 | ✅ `0000001007` | 请求未携带 Bearer token | — | 检查 `GANGTISE_TOKEN` / AK/SK 是否已 export |
-| ✅ `900002` | **请求方法不正确**（msg「请求类型有误」，HTTP 405）——旧文档写作"缺少 uid"是错的 | — | `raw call` 时确认该 endpoint 是 GET 还是 POST |
+| ✅ `900002` | **请求方法不正确**（msg「请求类型有误」，HTTP 405） | — | `raw call` 时确认该 endpoint 是 GET 还是 POST |
 | ✅ `140002` | 终态参数错：AI 异步生成失败，或 `indicator` 的指标必填参数缺失 / 枚举越界 / 表达式语法错（实测 2026-08-02） | **不重试**（终态码） | 按 msg 改参数重提；EDE 的参数名与枚举读 `indicator search --format json` 的 `parameterList` |
 
 **⚠️ 实测发现的坑（都是"不报错"型，最难发现）**
 - 🔴 **日期只写 `YYYY-MM-DD`、时间只写 `YYYY-MM-DD HH:mm:ss`（或 10/13 位时间戳）；CLI v0.28.0 起 date 与 datetime 两类、含所有 insight/vault 透传参数都本地拦截**。服务端对「年在后」格式**日月顺序随分隔符翻转**且静默误解析（HTTP 200、不回显实际用的日期）：`07/01/2026`（斜杠）读成 **2026-01-07**、`07-01-2026`（横杠）读成 **2026-07-01**，差半年。实测 `insight research list --start-time`：`07/01/2026` 命中 1562 条、`07-01-2026` 命中 210 条（分别 = 标准 `2026-01-07` / `2026-07-01`）；`quote day-kline`/`kline-hk`/`kline-us`/`index`、`fundamental balance-sheet` 同理。v0.28.0 前透传命令（research/summary/announcement-hk/us/vault/minute-kline 等）**静默放行**，且同值在本地转时间戳的 `announcement`（A 股）与透传的 hk/us 之间还会差半年、都 exit 0。现在全部在发请求前报 `ValidationError`，**但绕过 CLI 直连接口务必自己保证格式**
 - **财报接口的日期按「报告期末」过滤**，不是公告日：`fundamental balance-sheet` 等的 `--start-date`/`--end-date` 匹配的是 `endDate` 字段（如 `20200630`），响应里的 `announcementDate`（如 `20200729`）只是公告日。**查某期财报要传季度末日期**（`2020-06-30` / `2020-03-31` / `2020-09-30` / `2020-12-31`）；传 `2020-07-01` 这类非报告期日期会返回 0 行，属正常行为，不是没数据
 - 🔴 **Quote 系对非法证券代码不报错**，静默返回 `total:0` 空列表——无法区分"代码写错"和"该票该区间真无数据"。**空结果先回头核对代码后缀**。Fundamental 系会正常报 `120001`
-- **枚举值拼错、分页参数越界服务端不报错**——静默忽略该条件返回全量/正常结果。所以 `100004`/`100005` 实测触发不到。CLI 只对**部分**参数加了本地白名单（`--top` 上限；`--category` 仅 `reference securities-search` / `institution-search` / `official-account-search` 三个命令），**`insight research --category` 等仍是自由字符串、拼错不报错也不生效**。**拼错的筛选条件会伪装成"结果正常"，枚举拼写要自己保证**
+- **枚举值拼错、分页参数越界服务端不报错**——静默忽略该条件返回全量/正常结果。所以 `100004`/`100005` 实测触发不到。最坏一例：非法 `--search-type` 会**连带吞掉 `--keyword`**（`summary list --keyword 茅台 --search-type 99` 返 196988 全库 vs 正常 135）。**v0.32.0 起 CLI 本地拦截**：全部 `--search-type` / `--rank-type`（19 处）、全部 `--file-type`（9 处下载，`foreign-report` 为 1–4、其余 1–2）、`pamirs-summary` 的 `--category` / `--market`、`--top` 上限、以及 `reference securities-search` / `institution-search` / `official-account-search` 的 `--category`。**仍未覆盖**：`insight research/summary --category`、`--market`、`--source`、`--llm-tag` 等仍是自由字符串，拼错不报错也不生效——这些要自己核对。**拼错的筛选条件会伪装成"结果正常"，枚举拼写要自己保证**
 - **`viewpoint-debate` 传敏感内容不会被提前拦截**——实测不返回 `240002`，而是照常受理、扣满 50 积分、生成阶段才以 `410111` 失败。**提交前自己把关措辞**
 - **`ai one-pager` 的非法 `mode` 被静默忽略**，照常生成并扣 50 积分
 
@@ -299,10 +319,10 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 | `999003` / `999004` / `999005` / `999006` | 无接口权限 / 无资源权限 / 积分不足 / 限流 | 未构造出（需特定账号状态） |
 | `999012`–`999016` | 账号禁用/过期、租户失效、无长期 token、IP 不合规 | 未构造出 |
 | `100002` / `100004` / `100005` | 类型错 / 分页非法 / 枚举非法 | 类型错归 `100003`；后两者服务端静默忽略 |
-| `110003` | 超出时间范围限制 | 未触发（1900 年至今的范围仍正常返回） |
 | `130003` / `130004` / `130005` | 无文件可下 / ID 非数字 / 文件类型不支持 | 全部归 `130002` |
 | `140001` / `140002` | 结果生成中 / 处理失败 | 异步端点仍用 `410110` / `410111` |
 | `210001` / `220001` / `230001` | 研报/观点/分享文件不支持下载 | 未构造出 |
+| `230002` | 微信账号未绑定（私域，2026-08-07 新增）。⚠️ **`vault wechat-*` 就在该模块下、够得着**：要求先绑定并激活群消息助理且助理已入群 | 未构造出（本账号已绑定） |
 | `240002` / `240003` | 敏感词 / 模式不支持 | 敏感词走 `410111`；`one-pager` 的非法 `mode` 被静默忽略 |
 | `903301` / `10011401` | 今日调用上限 / 白名单未开通 | 历史遗留，**均未实测触发**。不臆断对应新码——`10011401` 按语义更接近 `999003`（未开通接口权限）而非 `999016`（IP 限制），别据此去查 IP |
 
@@ -315,7 +335,12 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 
 **其他场景**：
 - CLI 未安装 → `npm install -g gangtise-openapi-cli`
-- **退出码 3 = 部分结果**：翻页/K线分片有页失败、或服务端返回行数与 `total` 矛盾（提前短页）时，已取到的数据保留——stderr 有 warning，`--format json` 可见 `partial: true`（页失败另有 `failedPages`；分片失败为 `failedShards`、分片撞行数上限为 `truncatedShards`，均带具体日期区间可定向缩窗补拉）；table/csv/jsonl 只有数据行、看不出缺失。拿部分数据继续前必须告知用户缺了哪段
+- **退出码 3 = `partial: true`，结果少了数据**（保留已取到的部分；stderr 有 warning，`--format json` 才看得见标记，table/csv/jsonl 只有数据行、看不出问题）：
+  - 触发场景：翻页/K线分片有页失败、服务端返回行数与 `total` 矛盾（提前短页）、或 **EDE 有 code 没被服务端认出来**。附带定位字段：页失败 `failedPages`；分片失败 `failedShards`、分片撞行数上限 `truncatedShards`（均带日期区间可缩窗补拉）；EDE 为 `omittedIndicators` / `omittedSecurities`
+  - **EDE 的这两个字段现在读作「这些 code 服务端不认识」**——先查拼写和证券后缀（美股 `.O`/`.N`，不是 `.US`），而不是查 `scopeList` 覆盖：真的没覆盖会返 `null` 单元格、退出码 0
+  - **`screener` 的缺列按表达式的布尔结构判**：把缺列的变量当作「无法求值」，看整个表达式**是否还有一条能成立的分支**——`A && B` 要两边都可求值，`A || B` 只要一边。**一条分支都不剩 → 退出码 1、不输出任何结果**（返回的行以「通过了该条件」的名义呈现，而条件根本无法证明被执行过）；**还有分支可求值，或缺的只是未参与表达式的辅助变量 → `partial` + 退出码 3**。所以 `F1 || F2` 缺 F1 是降级（行可能靠 F2 正当命中），缺两个则是致命；`F1 && (F2 || F3)` 缺 F1 仍是致命（F1 是必选合取项）。⚠️ **前提是服务端返回了命中行**——零命中时没有行需要质疑，一律是「nothing matched」+ **退出码 0**，哪怕变量整个求不了值（实测 `F1:拼错的码` 单绑就是空集 + 退出 0）。**空集别当成「条件成立但无标的符合」**，先核对指标码
+  - 拿到 3 就必须告知用户缺了哪段，不能当成功静默继续
+  - （历史：条件选股把同一指标绑到多个变量曾触发 `unreliable: true` + `duplicatedIndicators`，因服务端把所有绑定按最早日期取数。2026-08-08 服务端已修复，该标记**已从 CLI 移除**，这类查询现在正常可用）
 - 空结果（list 为空数组） → 建议扩大时间范围、换关键词、去掉部分筛选
 - 模糊公司名匹配多只（"平安" → 中国平安 / 平安银行 / ...） → 列出让用户选
 - 下载文件路径冲突 → 询问覆盖

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

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