gangtise-openapi-cli 0.28.3 → 0.30.0

package/gangtise-openapi/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: gangtise-openapi
-version: "0.28.3"
+version: "0.30.0"
 description: |-
   通过 gangtise CLI 直接调用 Gangtise OpenAPI，拉取投研原始数据、批量导出、下载文件、调用 AI 能力。
 
   **触发词**：调接口 / CLI / openapi / 导出 / 下载研报 / 批量查 / 拉数据 / 跑一下 / 钢尼斯 / gtIC（Gangtise 语音误识别）
 
-  **适用**：原始数据导出、批量 jsonl/csv、下载 PDF/MD、行情 K 线、财务报表、估值指标、证券级数据指标（EDE 截面/时序）、AI 能力（一页通/投资逻辑/同业对比/个股看点·投研总结/投研线索/业绩点评/观点PK·多空辩论/主题跟踪/热点话题/管理层讨论/调研提纲/知识库搜索）、云盘文件管理（Vault）
+  **适用**：原始数据导出、批量 jsonl/csv、下载 PDF/MD、行情 K 线、财务报表、估值指标、证券级数据指标（EDE 截面/时序/条件选股）、财报日历（业绩预告/快报/公告）、PDF 解析为 Markdown、AI 能力（一页通/投资逻辑/同业对比/个股看点·投研总结/投研线索/业绩点评/观点PK·多空辩论/主题跟踪/热点话题/管理层讨论/调研提纲/知识库搜索）、云盘文件管理（Vault）
 
   **不适用**：不脱离 OpenAPI 自行撰写研报、编造投研结论或做自由问答——观点总结、多空 PK 等 AI 产物本 skill 只经由 Gangtise 平台 AI 接口获取，不自行生成
 
@@ -32,7 +32,7 @@ description: |-
 7. **CLI 已内置自动化，不要手动复刻**：
    - 翻页 → 首页拿 total 后剩余页并发拉取
    - K 线 `--security all` 跨日期 → 自动按日切片并合并
-   - 5xx / `429` / 网络错误 / `999999` → 自动指数退避重试（🔴 贵档端点例外：仅连接失败 / 429 / token 自愈重试，5xx/超时不重放防重复扣分，v0.26.0；`indicator` 端点对 `999999` 不重试——该码=查询无数据，v0.27.0）
+   - 5xx / `429` / 网络错误 / `999999` → 自动指数退避重试（🔴 贵档端点例外：仅连接失败 / 429 / token 自愈重试，5xx/超时不重放防重复扣分，v0.26.0；`indicator` 端点对 `999999` 不重试，v0.27.0）
    - 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。
@@ -68,13 +68,14 @@ description: |-
 "免费"=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 的 list、`vault my-conference-list`；`insight report-image download` 0.1/张
+- **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/张
 - **按条（观点/含详情类 list）**：independent-opinion list 与 `ai security-clue` 5；roadshow/site-visit/strategy/forum list 20；opinion / foreign-opinion list 30；`fundamental earning-forecast` 0.5；`ai stock-summary` 3（无看点的证券不返回也不扣）；`alternative edb-data` 30
-- **各 download（/篇）**：announcement / official-account / research 10；announcement-hk / announcement-us 20；independent-opinion 30；summary / foreign-report / my-conference 50
+- **各 download（/篇）**：announcement / official-account / research 10；announcement-hk / announcement-us 20；independent-opinion 30；summary / foreign-report / my-conference 50；`performance-calendar download` A 股 10 / 港美股 20
+- **按页**：`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），正是为防重复扣分
-- **按单元格**：`indicator cross-section` / `time-series`（A股 0.05 / 港股 0.1 / 美股 0.2 积分每 100 单元格，见 `indicator.md`）；`ai knowledge-resource-download` 按下游资源计费
+- **按单元格**：`indicator cross-section` / `time-series` / `screener`（A股 0.05 / 港股 0.1 / 美股 0.2 积分每 100 单元格；screener 按**筛选前**范围计费，见 `indicator.md`）；`ai knowledge-resource-download` 按下游资源计费
 
 ### 下载规则（`--file-type` / `--content-type`）
 
@@ -104,6 +105,7 @@ description: |-
 | 外资独立观点 / 独立分析师观点 | `insight independent-opinion list` |
 | 纪要 / 会议纪要（外部） | `insight summary list` |
 | 路演 / 调研 / 策略会 / 论坛 | `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` |
 | 港股公告 / HK 公告 | `insight announcement-hk list` |
 | 美股公告 / US 公告 | `insight announcement-us list` |
@@ -147,6 +149,7 @@ description: |-
 | 多证券已实现财务 / 估值指标搜索（含总市值） | `indicator search` |
 | 多证券已实现指标截面（多指标 × 多证券，同一查询日期） | `indicator cross-section`（前置：`indicator search --format json` 通过三项校验） |
 | 多证券已实现指标时序（单指标 × 多证券，按区间） | `indicator time-series`（前置：`indicator search --format json` 通过三项校验） |
+| 条件选股 / 按指标筛股票（市值+PE+经营范围等多条件组合） | `indicator screener`（前置：`indicator search` 拿 code；范围可传板块 ID，见 `reference sector-search`） |
 | 证券代码 / gtsCode 搜索 | `reference securities-search` |
 | 首席 ID / 分析师 ID 搜索 | `reference chiefs-search`（按姓名/机构/团队，用于 `insight opinion --chief`） |
 | 机构 ID 搜索（内资券商/外资/牵头/观点机构） | `reference institution-search`（按机构名，用于 `--institution` / `--broker`；免费） |
@@ -155,6 +158,7 @@ description: |-
 | 题材 ID 搜索 | `reference concept-search` |
 | 板块 ID 搜索 | `reference sector-search` |
 | 板块成分股 | `reference sector-constituents`（前置：`reference sector-search` 拿 `sector-id`） |
+| 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`
@@ -168,7 +172,8 @@ description: |-
   - 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` 且保留证券行；**整个查询无数据仍可能报 `999999`**。日期语义按指标分三类：财务报表指标=报告期末（可为非交易日）、`finc_pe_ttm` 等日频估值=最新交易日、`finc_pb_mrq`(MRQ) 等=最近报告期末（交易日取 `null`）；混合取数按各自有效日期分次 `cross-section` 再按证券合并，别塞进同一个 `--date`。详见 `references/commands/indicator.md`
+- EDE 单元格级缺值返回 `null` 且保留证券行；**整个查询无数据返回空表**（2026-08-01 起不再报 `999999`）——所以**参数写错也表现为空表**，拿到空表先查参数名和日期语义，别当成真没数据。日期语义按指标分三类：财务报表指标=报告期末（可为非交易日）、`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` 返回的是不复权价，看着正常实则错数据。`--indicator` / `--security` 支持板块 ID（`reference sector-search` 的 10 位 `sectorId`）。⚠️ 根级 `--scale` 会污染不声明 `scale` 的指标（`qte_close` 被 `--scale 8` 缩成 `0`），价格与金额混查时改用 `--indicator-param "code:scale=8"`
 - "业绩点评"双义消歧：**检索已有**（研报/纪要里的业绩点评内容）走 `insight ... list --llm-tag earningsReview`（0.1/条）；**AI 现生成**一份走 `ai earnings-review`（异步、50/次）。不确定问一句
 
 ## 公司名 → 证券代码
@@ -204,6 +209,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 | **AI 内容** | one-pager / investment-logic / peer-comparison / research-outline | `{content: "markdown文本"}` | 取 `content` 直接呈现 |
 | **K 线** | quote * | `{list: [{tradeDate, ...}]}` | 按 tradeDate 排序，取需要的尾部 |
 | **异步（含 *-check）** | earnings-review / viewpoint-debate / earnings-review-check / viewpoint-debate-check | 提交 `{dataId, status, hint}`；check 成功 `{date, content}` / pending `{status:"pending"}` 或抛 `140001`（旧 `410110`） | 见下方"异步任务流程" |
+| **异步文件** | tool file-parse / file-parse-check | 提交 `{taskId, status, hint}`；就绪后 stdout = ZIP 路径，未就绪 `{status:"pending"}` | 解压取 `file.md`；重取用 `file-parse-check`（免费），别重跑 `file-parse`（按页重扣） |
 
 完整字段对照见 `references/response-schema.md`。
 
@@ -237,7 +243,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 | 最新一期 / 最新报告期（财报） | — | — | 省略 `--fiscal-year`，传 `--period latest`（默认） |
 | 最新观点 / 今日观点 | 1 天范围 + `--rank-type 2` | — | — |
 
-日期参数**按参数名判断、不按命令组**（命令组会误导——AI 里既有 `--start-time` 又有 `--date`/`--report-date`）：名字带 `-date` 的（`--start-date`/`--end-date`/`--date`/`--report-date`）一律 `YYYY-MM-DD`，覆盖 Quote/Fundamental、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` 分隔）。
+日期参数**按参数名判断、不按命令组**（命令组会误导——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 默认排序。
 
@@ -258,7 +264,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）用此码 + HTTP 500 表示查询无数据**（节假日 / 未来日期 / 未覆盖标的，2026-07-11 实测）——单元格级缺值才是 `null` | 普通端点自动重试 ×2；🔴 贵档与 `indicator` 端点不重试 | `indicator` 遇到先检查日期/标的是否该有数据，别盲目重试 |
+| ✅ `999999` | 系统错误。**`indicator`（EDE）2026-08-01 前用此码表示查询无数据，现已改为返回空数组**，所以这个码基本只剩真故障 | 普通端点自动重试 ×2；🔴 贵档与 `indicator` 端点不重试 | 确认参数无误仍报此码即服务端故障 |
 | ✅ `410110` | **异步生成中**（HTTP 400，旧码未切）。新码 `140001`，CLI 两码都认 | 轮询视为 pending | 继续等 |
 | ✅ `410111` | **异步生成失败**（HTTP 400，旧码未切）。新码 `140002`，CLI 两码都认 | 终态 | **不重试**，换参数 |
 | ✅ `130002` | 资源不存在——**下载类的兜底码**：`reportId` 不存在 / 非数字 / `fileType` 非法**全归这里**（`130003`/`130004`/`130005` 实测均未启用） | — | 确认 ID 有效且本账号可见；换 `--file-type` 或换一篇验证 |
@@ -362,13 +368,14 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 
 按需 Read 对应文件：
 
-- 内资观点 / 纪要 / 路演 / 调研 / 策略 / 论坛 / 研报 / 外资研报 / A 股公告 / 港股公告 / 美股公告 / 外资观点 / 独立观点 / 公众号（official-account）/ 投资者问答（qa）/ 研报图表（report-image）→ `references/commands/insight.md`
+- 内资观点 / 纪要 / 路演 / 调研 / 策略 / 论坛 / 财报日历（performance-calendar）/ 研报 / 外资研报 / A 股公告 / 港股公告 / 美股公告 / 外资观点 / 独立观点 / 公众号（official-account）/ 投资者问答（qa）/ 研报图表（report-image）→ `references/commands/insight.md`
 - 行情命令（A 股 / 港股 / 美股日 K / 指数日 K / 分钟 K / 实时行情 / 资金流向 fund-flow） → `references/commands/quote.md`
 - 三大报表（A 股 / 港股 / 美股）/ 主营 / 估值 / 盈利预测 / 股东 → `references/commands/fundamental.md`
 - knowledge-batch / security-clue / 个股看点（stock-summary）/ AI agent / 异步任务 / 主题跟踪 / 热点 / 管理层讨论 → `references/commands/ai.md`
 - drive / record / my-conference / wechat / 股票池 → `references/commands/vault.md`
 - 行业指标数据库（EDB）/ 题材指数画像与成分股（concept-info / concept-securities）→ `references/commands/alternative.md`
-- 数据指标（EDE：search / cross-section / time-series，证券级指标截面与时序）→ `references/commands/indicator.md`
+- 数据指标（EDE：search / cross-section / time-series / screener，证券级指标截面、时序与条件选股）→ `references/commands/indicator.md`
+- PDF 解析（file-parse：上传 PDF → Markdown + 图片 ZIP）→ `references/commands/tool.md`
 - securities-search / chiefs-search（首席 ID）/ institution-search（机构 ID）/ official-account-search（公众号 ID）/ 常量查询（constant-category / constant-list）/ 题材 ID（concept-search）/ 板块（sector-search / sector-constituents）/ lookup 本地表 / 行业别名 / raw call → `references/commands/reference-and-lookup.md`
 
 跑通流程对照 → `references/examples.md`

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

@@ -1,9 +1,9 @@
-# Indicator 命令详细参数（数据指标 EDE：证券级指标截面 / 时序）
+# Indicator 命令详细参数（数据指标 EDE：证券级指标截面 / 时序 / 条件选股）
 
-> 本组覆盖 `/application/open-indicator/EDE/*`：证券级**数据指标**的检索与取数，主要用于多证券批量取已实现财务 / 估值指标。即使能搜到收盘价、成交量等行情指标，常规行情与 K 线仍走免费的 `quote`。
+> 本组覆盖 `/application/open-indicator/*`：证券级**数据指标**的检索与取数，主要用于多证券批量取已实现财务 / 估值指标。即使能搜到收盘价、成交量等行情指标，常规行情与 K 线仍走免费的 `quote`。
 > 与 `alternative edb-*`（EDB 行业/宏观指标，无证券维度）是两套接口，别混。
 >
-> **取数前先 `indicator search` 拿 `indicatorCode`**，绝不猜测指标编码。
+> **取数前先 `indicator search` 拿 `indicatorCode` 和 `parameterList`**，绝不猜测指标编码或参数名——服务端调过参数名（`adjustmentType` → `adjustType`），传错名是**静默失效**不是报错。
 
 ## EDE 与专用接口的优先级
 
@@ -27,8 +27,10 @@ gangtise indicator search --keyword <text> [--limit <n>]
 - `--keyword`（**必选**）：按指标名称模糊匹配。用具体词，如 `营业收入` / `基本每股收益` / `市盈率` / `总市值`，**不能用整句白话**（"我想查一批公司的财务估值" ✗）
 - `--limit`：返回条数上限，默认 50，最大 100
 - 默认 `--format table` 只适合浏览名称；正式路由 / 取数前必须加 `--format json`，才能完成语义、`scopeList`、`parameterList` 三项校验
-- 返回字段：`indicatorCode` / `indicatorName` / `description`（算法与口径）/ `scopeList`（该指标适用的市场 + 证券类型）/ `parameterList`（可传的 `--indicator-param` 参数及枚举）/ `score`
-- **市场范围按指标判断**：`scopeList` 现在会返回实际覆盖范围，且指标之间不同；不能笼统写成每个指标都覆盖 A / 港 / 美股。实测 `finc_pe_ttm` / `finc_pb_mrq` 仅 A 股，`is_op_rev` 覆盖 A 股 + 港股，这些财务 / 估值指标均不含美股。目标列表含任一 scope 外证券时，本批 EDE 校验不通过，应回退专用接口
+- 返回字段：`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` 声称覆盖港股，实测港股仍返 `null`（2026-08-01）。批量前抽查一行
 - 美股代码用交易所后缀 `.O`(NASDAQ) / `.N`(NYSE)，**不是 `.US`**——实测 `AAPL.US` 查不到数据，须用 `AAPL.O`（官方示例里的 `AAPL.US` 是笔误）
 
 ```bash
@@ -44,13 +46,15 @@ gangtise indicator cross-section --indicator <code> [--indicator <code2>] \
 ```
 
 - `--indicator`（**至少 1 个**）：指标编码，来自 `search`，可重复传多个
-- `--security`（**至少 1 个**）：证券代码，如 `600519.SH`（A股）/ `09992.HK`（港股）/ `AAPL.O`（美股，用 `.O`/`.N` 后缀，非 `.US`），可重复传多个
-- `--date`（**必选**）：数据日期 `yyyy-MM-dd`；日期语义按指标分三类——财务报表指标=报告期末（可为非交易日，实测 `2024-03-31` 可取数）、`finc_pe_ttm` 等日频估值=交易日、`finc_pb_mrq`(MRQ) 等=最近报告期末（交易日取 `null`，详见下方「日期路由」）。单元格级缺值返回 `null`，整个查询无数据可能报 `999999`
-- `--currency`：币种 `DFT`(原始,默认)/`CNY`/`HKD`/`USD`/`EUR`/`GBP`/`JPY`/`TWD`/`MOP`/`AUD`
+- `--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` / `sDate` 的指标必须显式传**：`--indicator-param "code:reportDate=2024-12-31"`。这类指标收到 `tradeDate` 会**静默返回空结果**（不报错，实测 `is_op_rev_mom`）。CLI 检测到你已为某指标传了 `tradeDate`/`reportDate`/`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"` 只作用于该指标
 - **支持多指标 × 多证券**（单日横截面）
-- **输出（宽表）**：每行一只证券，列为 `date / security / name / <各指标名>…`
-- **`--key-by name|code`**（默认 `name`）：指标列头用显示名还是 `indicatorCode`。**批量按 code 回填必用 `--key-by code`**——指标名会碰撞（多个指标同显示名，如 `cf_finc_exp`/`_qtr` 都叫「财务费用」）、服务端还会重排返回列序，唯有 code 唯一且与顺序无关（行轴 `security` 本就是 code，`code` 模式整表可按 code 寻址，免去 raw API 手工回填）
+- **输出（宽表）**：每行一只证券，列为 `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 手工回填）
 
 ```bash
 # 多证券 × 同一报告期的已实现财务指标
@@ -58,8 +62,8 @@ gangtise indicator cross-section \
   --indicator is_op_rev --indicator is_eps_bas \
   --security 600519.SH --security 000858.SZ --security 300750.SZ \
   --date 2025-12-31 --format table
-# 列：date / security / name / 营业收入(利润表,累计) / 基本每股收益(利润表,累计)
-# 省略 reportType 即取合并口径（茅台2025=1688亿）。⚠️ 服务端 label 与实际取数错位：实际 1=合并 2=合并(调整) 3=母公司 4=母公司(调整)，按 label 传会取反（详见下方「reportType 口径」）
+# 列：security / name / 营业收入(利润表,累计) / 基本每股收益(利润表,累计)
+# 省略 reportType 即取合并口径（茅台2025=1688亿）；口径映射见下方「reportType 口径」
 ```
 
 ## 指标时间序列 `indicator time-series`
@@ -70,12 +74,13 @@ gangtise indicator time-series --indicator <code> [--indicator <code2>] \
   [--calendar-type <ND|TD|WD>] [--currency <c>] [--scale <s>] [--indicator-param <spec>] [--key-by name|code]
 ```
 
-- `--indicator` / `--security`：同上，但**只允许「多指标 × 单证券」或「单指标 × 多证券」**，不能两边都多个（要多 × 多用 `cross-section`，否则报 `410001`）
-- `--start-date` / `--end-date`（**均必选**）：区间端点 `yyyy-MM-dd`
-- `--calendar-type`：日期类型 `ND`(自然日)/`TD`(交易日,默认)/`WD`(工作日)
-- `--currency` / `--scale`：同 `cross-section`
+- `--indicator` / `--security`：同上，但**只允许「多指标 × 单证券」或「单指标 × 多证券」**，不能两边都多个（要多 × 多用 `cross-section`，否则报 `410001`）。**单指标时 `--security` 才能传板块 ID**；多指标时只能传一个证券代码、不得传板块 ID
+- `--start-date` / `--end-date`（**均必选**）：区间端点 `yyyy-MM-dd`。时序的时间范围由这两个参数统管，**不要**再用 `--indicator-param` 传 `tradeDate` 这类单日期参数
+- `--calendar-type`：日期类型 `ND`(自然日)/`TD`(交易日,默认)/`WD`(工作日)。`TD` 且跨市场时，`date` 列是各市场交易日的**并集**
+- `--currency` / `--scale`：同 `cross-section`（含根级 `--scale` 的污染坑）
 - **输出（宽表）**：每行一个日期，列为 `date / <各序列名>…`；序列在「单证券」时是各**指标**，在「多证券」时是各**证券**
 - **`--key-by name|code`**（默认 `name`）：同 `cross-section`；`code` 模式下单证券列=各 `indicatorCode`、多证券列=各 `securityCode`，批量按 code 回填用它
+- ⚠️ 部分指标**不支持时序接口**：`search` 返回的 `scopeList[].usageRestriction` 会写明（如「不支持指标时间序列接口」），`null` 表示无限制。取数前顺手看一眼，省得白花积分
 
 ```bash
 # 单个已实现估值指标 × 多证券：列 = 证券
@@ -85,31 +90,66 @@ gangtise indicator time-series --indicator finc_pe_ttm \
 # date        贵州茅台    五粮液    宁德时代
 ```
 
+## 条件选股 `indicator screener`
+
+```bash
+gangtise indicator screener --indicator <F1:code> [--indicator <F2:code2>] \
+  --security <code|sectorId> [--security <code2>] --expression <expr> \
+  [--date <yyyy-MM-dd>] [--indicator-param <F1:key=value>] [--key-by name|code]
+```
+
+按指标条件从一个证券范围里筛出符合条件的股票，一次调用完成「取数 + 过滤」，比 `cross-section` 拉全量再本地筛更省事。
+
+- `--indicator`（**至少 1 个**）：把变量绑定到指标，格式 `F1:指标code`。变量必须是 `F` + 正整数、同一次请求内不重复；建议从 `F1` 开始连续编号
+- `--security`（**至少 1 个**）：同 `cross-section`，证券代码与板块 ID 可混传取并集
+- `--expression`（**必选**）：筛选表达式，引用上面绑定的变量
+  - 比较：`==` `>` `<` `>=` `<=` `!=`
+  - 文本：`contains` / `notcontains`（不区分大小写，**仅对 `dataType: string` 的指标有效**）
+  - 逻辑：`&&` `||`，分组 `(` `)`
+- `--date`：同 `cross-section`，下发为每个指标的 `tradeDate`（已自带日期参数的指标不覆盖）
+- `--indicator-param`：格式是 **`F1:key=value`（按变量，不是按 code）**——同一个指标 code 允许绑到两个变量取不同参数（如比较两个日期的收盘价），只有变量能区分。引用了没绑定的变量会直接报错，不会静默丢弃
+- **输出（宽表）**：同 `cross-section`，每行一只**命中**的证券，列为 `security / name / <各指标名>…`；无命中返回空表
+- **积分**：与 `cross-section` 同价（按单元格计），但计费基数是**筛选前**的范围 × 指标数，别拿全市场板块随手试
+
+```bash
+# 中信白酒板块里，市值≥500亿 且 PE(TTM)≤30
+gangtise indicator screener \
+  --indicator F1:qte_mkt_cptl --indicator F2:finc_pe_ttm \
+  --indicator-param "F1:scale=8" \
+  --security 1000000287 \
+  --expression "F1 >= 500 && F2 <= 30" \
+  --date 2026-07-31 --format table
+# security / name / 总市值 / 市盈率(TTM) —— 19 只成分股筛出 5 只
+```
+
 ## 复权 / 指标专属参数 `--indicator-param`
 
-通用的币种/量纲用 `--currency` / `--scale`；指标**专属**参数用 `--indicator-param`，格式 `指标code:参数key=值`，可重复。下面的行情复权仅演示底层参数语法；常规行情 / K 线仍优先 `quote`，不要照此例改走 EDE：
+通用的币种/量纲用 `--currency` / `--scale`；指标**专属**参数用 `--indicator-param`，格式 `指标code:参数key=值`，可重复（screener 例外，按变量索引：`F1:key=值`）。下面的行情复权仅演示底层参数语法；常规行情 / K 线仍优先 `quote`，不要照此例改走 EDE：
 
 ```bash
-# 茅台收盘价后复权（adjustmentType=3）
+# 茅台收盘价后复权（adjustType=3）
 gangtise indicator cross-section --indicator qte_close --security 600519.SH \
-  --date 2026-05-18 --indicator-param "qte_close:adjustmentType=3"
-#   不复权 1323 → 后复权 11487.0308
+  --date 2024-01-02 --indicator-param "qte_close:adjustType=3"
+#   不复权 1685.01 → 前复权 1531.225 → 后复权 13609.6168
 ```
 
-- `adjustmentType`（复权方式）：`1`=不复权 `2`=前复权 `3`=后复权 `4`=定点复权
+- `adjustType`（复权方式）：`1`=不复权(默认) `2`=前复权 `3`=后复权 `4`=定点复权（配 `baseDate` 基期）
+  - ⚠️ **参数名是 `adjustType`，不是 `adjustmentType`**（官方文档示例写的 `adjustmentType` 是错的）。传错名服务端**静默忽略并退回不复权**——实测 `adjustmentType=3` 返回 1685.01（= 不复权），看着正常其实是错数据
+  - 前复权以最新交易日为基准，所以在**最新交易日上前复权价 == 不复权价**；验证复权是否生效要用历史日期
 - 同一指标多个参数 → 重复 `--indicator-param "code:k1=v1" --indicator-param "code:k2=v2"`
-- 三项校验通过后，再从 `indicator search --format json` 的 `parameterList` 读取该指标支持的 `paramKey` 及枚举值（**参数 key 与取值（含大小写）均以 search 返回为准**——如 `currency` 在 parameterList 中可能为小写 `dft`/`cny`）
+- **参数名与取值一律以 `indicator search --format json` 的 `parameterList` 为准**，不要照抄本文档或官方文档的示例名——服务端会调整参数名（`adjustmentType` → `adjustType` 就是一例），且传错名是静默失效而非报错。币种枚举 2026-08-01 起**统一大写**（`DFT`/`CNY`/`HKD`…），历史文档里的小写 `dft`/`cny` 已过时
 - `--indicator-param` 与根级 `--currency`/`--scale` 冲突时，以 `--indicator-param` 为准
 
 ## 必填参数与错误码（取数前必读）
 
-截面/时序**单元格级缺值返回 `null`**（证券行保留、不丢行）；但**整个查询无数据时仍会报 `999999` + HTTP 500**（节假日 / 未来日期 / 未覆盖标的，2026-07-11 实测）。取数报错主要是这几个码：
+截面/时序**单元格级缺值返回 `null`**（证券行保留、不丢行）。**整个查询无数据现在返回空数组**（`securityCodeList`/`values` 皆为 `[]`，CLI 显示 `Total: 0`），不再像 2026-07 那样报 `999999` + HTTP 500 —— 这也意味着**参数写错的失败会以「空表」而不是报错的形式出现**，拿到空表先怀疑日期语义 / 参数名，别当成「确实没数据」。取数报错主要是这几个码：
 
 | 错误码 | 实际含义 | 怎么办 |
 | :--- | :--- | :--- |
-| `410001` | 入参错误：没传指标/证券，或 `time-series` 传了「多指标 × 多证券」 | 补齐 `--indicator`/`--security`；多 × 多改用 `cross-section` |
-| 缺参报错（曾为 `410106`） | **缺必填参数**：服务端现已直接指明缺哪个，如「指标 X 的必填参数 periodNum(期数) 不能为空」（仍以 HTTP 500 返回，CLI 重试 2 次后透出该消息） | 读 `search --format json` 的 `parameterList`，把 `required:true` 的参数用 `--indicator-param` 补上 |
-| `999999` | **多为整查询无数据**（日期语义不符 / 未来日期 / 未覆盖标的；单元格级缺值才是 `null`），也可能是真系统故障——服务端不区分两者 | CLI 对 indicator 端点**不重试此码**（v0.27.0）并在 hint 中提示；先核对日期符合指标语义、标的在覆盖范围，确认应有数据仍报错才按系统故障处理 |
+| `100001` | **缺少必填参数**：如 `universe` 没传 | 补齐 `--indicator`/`--security` |
+| `410001` | 入参错误：`time-series` 传了「多指标 × 多证券」 | 多 × 多改用 `cross-section` |
+| 缺参报错（曾为 `410106`） | **缺指标级必填参数**：服务端会直接指明缺哪个，如「指标 X 的必填参数 periodNum(期数) 不能为空」（仍以 HTTP 500 返回，CLI 重试 2 次后透出该消息） | 读 `search --format json` 的 `parameterList`，把 `required:true` 的参数用 `--indicator-param` 补上 |
+| `999999` | 系统故障。2026-08-01 起「无数据」已改为返回空数组，所以这个码基本只剩真故障（2026-07-26 曾出现 EDE 取数端全线 999999，08-01 已恢复） | CLI 对 indicator 端点**不重试此码**（v0.27.0）；确认参数无误仍报错就是服务端问题 |
 | `130001`（旧 `410004`） | 数据未找到，或**该指标无权限**（内层信封失败会带具体 msg，如"指标无权限"；此码被服务端复用） | 检查查询条件与指标权限；换证券/日期仍失败多为无权限，联系管理员开通 |
 
 ### 必填参数（`410106` 的根因）
@@ -126,7 +166,8 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 
 ## 取数最佳实践
 
-- **先 search 做三项校验**：看 `indicatorName` + `description` 确认语义和口径，看 `scopeList` 确认覆盖全部目标市场 / 证券类型，再看 `parameterList` 补齐必填参数（required）并核对专属参数枚举（`adjustmentType`/`scale`/`currency` 等）；任一不符就回退专用接口。
+- **先 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 就是事实。
 - **公司类型决定有没有这个科目**：财务科目分公司类型——银行有「存放同业」、券商有「客户资金存款」、保险有「预收保费」，一般企业没有。某指标对茅台返回 `null`（无此科目），换到对应类型证券（招行/中信/平安）就有数。
 - **日期路由**：
   - 财务报表类（`bs_`/`is_`/`cf_`/`div_`/`shr_`，以及 description 明确按报告期统计的 `finc_`）→ 用**报告期末**（Q1 `2026-03-31`、年报 `2025-12-31`，无需是交易日）
@@ -134,27 +175,28 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
   - 现金流量表附注/间接法科目（多数 `cf_`）→ **只在年报/半年报披露**，季报日期取不到，改用年报日期 `2025-12-31`
   - 行情类（`qte_` 等）→ 用**交易日**，但常规行情仍应改走 `quote`
 - **混合日期语义要拆查询**：同时要“某报告期营收 / EPS”和“估值 PE / PB”时，按各自有效日期分别调用 `cross-section` 再按 `security` 合并（财务=报告期末、PE=最新交易日、PB(MRQ)=最近报告期末）；不要把不同日期语义的指标塞进同一个 `--date`
-- **探索性取数**：单元格级缺值返回 `null` 且保留证券行，时序局部无值可为空行；**整个查询无数据仍可能报 `999999`**。看趋势用 `time-series` + 覆盖报告期的区间，但不能把缺值当成通过语义 / scope 校验。
+- **探索性取数**：单元格级缺值返回 `null` 且保留证券行，时序局部无值可为空行；**整个查询无数据返回空表**（不再报 `999999`）。看趋势用 `time-series` + 覆盖报告期的区间，但不能把缺值当成通过语义 / scope 校验。
 - **名称反查 code 要核对，别取首条**：存在同显示名的兄弟指标——单季 `cf_finc_exp_qtr` 与累计 `cf_finc_exp` 都叫「财务费用」，`bs_fmt`/`cf_fmt`/`is_fmt` 都叫「报表格式」。`search` 按名称模糊匹配，目标 code 高概率在 top1 但不绝对，要看 `indicatorCode` 确认。
-- **批量查询做失败拆分**：某指标**缺必填参数**或入参错误时会整批报错（单元格级无数据按 `null` 返回；整个查询无数据的 `999999` 例外见上），逐指标单查能定位是哪个指标缺参/不可查。
-- **市值量纲（实测 2026-07）**：`qte_mkt_cptl`（总市值）**仅 A 股**——港股/美股返 `null`（换 `currency` 也没用，是 scope 外 ≠ 无数据）；**默认返原始「元」**（茅台 ≈ `1.5e12`，即 1.5 万亿），别误当天文数字。用 `scale` 数字码缩放（`0`元 / `3`千 / `4`万 / `6`百万 / `8`亿 / `9`十亿——`scale=8` → `15038` 亿元）、`currency` 换币种（`dft`本币 / `cny` / `hkd` / `usd` …）。**跨证券比市值前先统一 `scale`+`currency`**。
-- **EDE 财务指标的 `reportType`：label 与 value 错位，但映射本身稳定可用（复测 2026-07-24，修正 07-23 的结论）**。服务端 label 标 `1`母公司/`2`合并/`3`母公司调整/`4`合并调整，**实际取数是**：
+- **批量查询做失败拆分**：某指标**缺必填参数**或入参错误时会整批报错（单元格级无数据按 `null` 返回），逐指标单查能定位是哪个指标缺参/不可查。
+- **市值量纲（复测 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`**。
+- **币种与汇率（复测 2026-08-01，已修复）**：`DFT`（原始币种）识别正确——A股=CNY、港股行情=HKD、美股=USD；汇率换算自洽（互逆且三角一致，误差 <0.003%）。⚠️ 但**同一只港股，行情类的原始币种是 HKD、财务类可能是 CNY**（如泡泡玛特财报以人民币计），跨市场比财务数据时显式传 `--currency CNY` 别依赖 `DFT`。另：财务类指标的汇率按**报告期**折算、行情类按查询日折算，两者隐含汇率会有细微差异，属正常口径差别。
+- **EDE 财务指标的 `reportType`（2026-08-01 裁决完毕，悬案关闭）**：服务端 enum label 已改正，现在 **label 与实际取数一致**，直接按 label 传即可：
 
-  | value | 实际口径 | 说明 |
+  | value | 口径 | 说明 |
   |-------|---------|------|
   | `1`（默认，省略即此值） | **合并报表** | 绝大多数场景要的就是这个 |
   | `2` | **合并报表（调整）** | 该报告期无重述数时为空 |
   | `3` | **母公司报表** | |
   | `4` | **母公司报表（调整）** | 该报告期无重述数时为空 |
 
-  实测对照（中信证券 `600030.SH` FY2024 营业收入，与 `fundamental income-statement --report-type` 逐一相等）：`1`→637.9亿（合并）、`2`→581.2亿（合并调整）、`3`→321.9亿（母公司）、`4`→321.9亿（母公司调整）；中国神华 `601088.SH` 同期 `1`→3383.75亿、`2`→3397.88亿，两值不同，可排除「2 就是合并原值」。**按 label 传会取反**（想要母公司却传 `1` 拿到合并）——认 value 不认 label：合并省略即可，母公司传 `3`。
+  实测闭环（`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 传会取反」的警告已作废。
 
-  `2`/`4` 返回空值**不是枚举失效**，是该报告期尚无调整表（如最新年报 FY2025：`1`/`3` 有数、`2`/`4` 无值，与 `fundamental --report-type consolidatedRestated` 同期无数据一致）；查询内所有单元格都无值时才会升级成 `999999`。港股默认口径同样是合并（腾讯 FY2024 营收 6602.57亿）。
+  `2`/`4` 返回空值**不是枚举失效**，是该报告期尚无调整表（如最新年报 FY2025：`1`/`3` 有数、`2`/`4` 无值，与 `fundamental --report-type consolidatedRestated` 同期无数据一致）。港股默认口径同样是合并。
 
 ## 通用说明
 
-- **发现流程**：`indicator search --format json` → 核对 `indicatorName` + `description`、`scopeList`、`parameterList` → 三项都通过才用 `cross-section` / `time-series`
-- **积分**：`search` 免费；`cross-section` / `time-series` 按请求单元格数量计费，标价为每 100 单元格 A 股 0.05 / 港股 0.1 / 美股 0.2 积分，每次查询不足 100 单元格按 100 计
-- **空结果 / 整查询无数据**：时序可能返回空表，截面或整批无数据也可能报 `999999`；先改用符合指标语义的日期 / 有效区间并核对 `scopeList`
+- **发现流程**：`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 年；正式账号按服务等级
 - 所有格式（table/json/jsonl/csv/markdown）均可用；导出宽表给 Excel 直接用 `--format csv --output xxx.csv`

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

@@ -56,6 +56,25 @@ gangtise insight forum list      [--research-area <id>] [--location <id>]
 - `--market`：路演 `aShares`｜`hkStocks`｜`usChinaConcept`｜`usStocks`；调研 `aShares`｜`hkStocks`｜`usChinaConcept`（无 usStocks）
 - `--research-area`（路演/调研/论坛）：用 `gangtiseIndustry` 码（行业 `1008001xx` + 方向 `122000xxx`，见 `reference-and-lookup.md`）。**strategy 无 `--research-area`，只按 `--institution`/`--location` 筛**
 
+## 财报日历 `insight performance-calendar list/download`
+
+```bash
+gangtise insight performance-calendar list [--start-date <date>] [--end-date <date>] [--market <name>] [--security <code>] [--category <name>] [--from <n>] [--size <n>]
+gangtise insight performance-calendar download --performance-report-id <id> [--output <path>]
+```
+
+- ⚠️ **本命令用 `--start-date` / `--end-date`（`yyyy-MM-dd`），不是其余 insight list 的 `--start-time`**；过滤的是 `publishDate`（财报事件发布日）。也**没有** `--keyword` / `--rank-type` / `--search-type`
+- `--category`：`performanceForecast` 业绩预告 | `performanceExpress` 业绩快报 | `performanceAnnouncement` 业绩公告（可重复）
+- `--market`：`aShares` | `hkStocks` | `usChinaConcept` | `usStocks`（可重复）
+- `--market` / `--category` 拼错 CLI 本地直接报错（不是静默返全量）——这两个参数的枚举值不必猜
+- `--security`：证券代码，如 `000001.SZ`（可重复）
+- 自动翻页（`{total,list}`，单页上限 50）。**不加任何筛选时 total 十万量级**（实测 2026-07-25 为 126683，含未来已排期的财报日程）——CLI 因此要求至少一个约束：`--start-date` + `--end-date`、或 `--security`、或显式 `--size`，裸跑直接报 `ValidationError`（不发请求、不扣分）
+- 只给 `--security`（不给日期/`--size`）时，CLI 额外套一个 **1000 行隐式上限**：单只证券的整段日历只有几十条，正常查询感知不到；万一服务端哪天不再按 `securityList` 过滤，结果会在 1000 行截断并标 `partial`（stderr 警告 + 退出码 3），而不是闷头翻完全表。判据是 `total`：只有「取满 1000 行且 total 显示还有更多」才告警——恰好 1000 行且 total=1000 是完整结果，退出码仍是 0。看到告警说明筛选**可能**没生效，改用日期范围重查
+- 返回字段：`performanceReportId`（下载用）/ `securityCodeList[]`（A+H 同时上市会有多个代码）/ `securityName` / `category` / `publishDate` / `title` / `hasAttachment`
+- 实测 `publishDate` 返回的是 `yyyy-MM-dd 00:00:00`（文档写 `yyyy-MM-dd`），取日期请截前 10 位
+- download：**只有 `hasAttachment: true` 的记录能下**（先 list 确认）；省略 `--output` 用真实标题命名（走 title-cache，未命中会回查 list 接口，那次回查按 0.1/条 计费——批量下载建议显式 `--output`）
+- **积分**：list 0.1/条；download A 股 10/篇、港美股 20/篇
+
 ## 研报 `insight research list/download`
 
 ```bash

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

@@ -0,0 +1,40 @@
+# Tool 命令详细参数（投研工具）
+
+## PDF 解析 `tool file-parse` / `file-parse-check`
+
+把 PDF（研报、公告、合同等）解析成 Markdown 正文 + 提取的图片，结果打包成 ZIP。异步两步：提交拿 `taskId` → 取结果 ZIP。
+
+```bash
+# 一步到位（推荐）：提交后阻塞轮询，就绪即落盘
+gangtise tool file-parse --file <x.pdf> --wait [--output <out.zip>]
+
+# 两步：先提交，稍后取结果
+gangtise tool file-parse --file <x.pdf>                       # 输出 {"taskId": "...", "status": "pending"}
+gangtise tool file-parse-check --task-id <id> [--output <out.zip>]
+```
+
+- `--file`（**必填**）：待解析的 PDF。CLI 在上传前本地校验：文件存在、非空、后缀 `.pdf`、≤100MB——不合格直接报 `ValidationError`，不发请求也不扣分
+- `--wait`：阻塞轮询到结果就绪（预算 ≈316s，覆盖官方「单文件约 3 分钟」）。**外层工具/命令超时要设到 ≥360s**，否则外层先超时（任务仍在服务端跑，之后 `file-parse-check` 照样能取）
+- `--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，实测 2026-07-25），隔 ~1 分钟再取即可
+
+ZIP 内容：
+
+```
+├── file.md          # Markdown 正文（保留标题层级与阅读顺序）
+└── images/          # 从 PDF 提取的图片（JPG，文件名由服务端生成；无图时为空目录）
+```
+
+呈现建议：解压后读 `file.md`；正文很长时先 `wc -l` / `head` 采样，不要整篇灌进上下文。
+
+## 常见搭配
+
+```bash
+# 下载研报原文 PDF → 解析成 Markdown
+gangtise insight research download --report-id 1234567 --output ./r.pdf
+gangtise tool file-parse --file ./r.pdf --wait --output ./r.zip
+```
+
+⚠️ 研报/公告类接口本身多数支持 `--file-type 2`（Markdown）直出，**先看能不能直接下 Markdown**（只算下载积分），别为已有 Markdown 的文件再花 0.8/页 走解析。`file-parse` 的价值在于外部来源的 PDF（自己的资料、非平台文件）。

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

@@ -53,7 +53,9 @@ gangtise vault wechat-message-list [--keyword <text>] [--security <code>] [--wec
 - `--wechat-group-id`：先用 `vault wechat-chatroom-list` 查；可重复
 - `--category`：`text` | `image` | `documents` | `url`（可重复）
 - `--tag`：`roadShow` | `research` | `strategyMeeting` | `meetingSummary` | `industryComment` | `companyComment` | `earningsReview`（可重复）
-- 返回字段：`msgId` / `msgContent` / `contentUrl` / `msgTime` / `wechatGroupId` / `wechatGroupName` / `speakerName` / `category` / `tagList` / `securityList`（含 `securityCode` / `securityName`）
+- 返回字段（实测 2026-07-25）：`msgId` / **`content`**（正文）/ **`url`**（链接）/ `msgTime` / `wechatGroupId` / `wechatGroupName` / `speakerName` / `category` / `tagList[]{tagCode, tagName}` / `securityList[]{securityCode, securityName}` / `quoteMsg{quoteMsgId, quoteContent, quoteUrl}`。旧版本文档写作 `msgContent` / `contentUrl` 是错的，取值请用 `content` / `url`
+- `quoteMsg`（2026-07-24 新增）：被引用的消息，无引用时为 `null`；`quoteContent` / `quoteUrl` 也可能为空。做上下文还原时用它把「回复」接回原消息
+- 未打标签/未关联证券的消息，`tagList` / `securityList` 返回 `null`（不是空数组）
 
 ## 群 ID 查询 `vault wechat-chatroom-list`
 

package/gangtise-openapi/references/examples.md

@@ -241,7 +241,7 @@
    - scopeList：覆盖全部三只 A 股；缺失/null/空也视为不通过
    - parameterList：补 required 参数并核对枚举
    任一不符 → 回退相应专用接口。
-3. 三类指标日期语义不同 → 拆三次截面，均加 `--key-by code`（列头用 indicatorCode，跨三张表按 code 稳定合并、免受同名/服务端重排干扰；省略 reportType 即取合并口径，⚠️ 该枚举 label 与实际取数错位——实际 1=合并 2=合并(调整) 3=母公司 4=母公司(调整)，要母公司口径传 3、别按 label 传 1）：
+3. 三类指标日期语义不同 → 拆三次截面，均加 `--key-by code`（列头用 indicatorCode，跨三张表按 code 稳定合并、免受同名/服务端重排干扰；省略 reportType 即取合并口径，label 与取数已一致：1=合并 2=合并(调整) 3=母公司 4=母公司(调整)）：
    a) 财务（营收/EPS）用报告期末 2025-12-31：
      gangtise indicator cross-section \
        --indicator is_op_rev --indicator is_eps_bas \
@@ -257,7 +257,7 @@
        --date 2026-03-31 --key-by code --format json
 4. 按 security 合并三张宽表（列头即 indicatorCode，各取所需日期的值）；不要把不同日期语义的指标塞进同一个 --date。
 5. 计费：search 免费；三次取数各按请求单元格数量计费，每次不足 100 单元格按 100 计。
-6. 无数据：单元格缺值返回 null 且不丢证券行；整个查询无数据仍可能报 999999，先核对日期语义、scopeList、公司类型和指标参数。
+6. 无数据：单元格缺值返回 null 且不丢证券行；整个查询无数据返回空表（不再报 999999）——空表也可能是参数名/日期语义写错，先核对 parameterList、日期语义、scopeList 和公司类型。
 ```
 
 ## 例 16：A 股资金流向（个股 vs 全市场按日分片）
@@ -294,3 +294,37 @@
      --start-time "2026-06-06 00:00:00" --end-time "2026-07-06 23:59:59" --format json
 4. 只有要「全量枚举」券商/机构表时才用本地 lookup broker-org/meeting-org list（institution-search 是搜索、非全量）
 ```
+
+## 例 18：财报日历（本周谁发业绩预告）
+
+**用户**："这周 A 股有哪些业绩预告"
+
+```
+1. 路由 → insight performance-calendar list（不是 announcement——预告/快报/公告事件走财报日历）
+2. ⚠️ 本命令用 --start-date/--end-date（yyyy-MM-dd，过滤 publishDate），不是其余 insight list 的 --start-time
+   "这周" → 本周一至今天
+3. Pre-flight：不加筛选 total 十万量级（含未来排期）→ 必须带日期范围；0.1 积分/条，先 --size 探量
+4. gangtise insight performance-calendar list \
+     --start-date 2026-07-20 --end-date 2026-07-25 \
+     --market aShares --category performanceForecast \
+     --size 50 --format json
+   → list[].securityName / title / publishDate / performanceReportId / hasAttachment
+5. 用户要原文时：只有 hasAttachment: true 能下（A股 10 积分/篇）
+   gangtise insight performance-calendar download --performance-report-id 33753017 --output ./预告.pdf
+```
+
+## 例 19：外部 PDF 转 Markdown（异步文件解析）
+
+**用户**："把这份 PDF 转成 Markdown 我要读正文"
+
+```
+1. 先判断来源：平台自有研报/公告 → 直接 download --file-type 2 出 Markdown（只花下载积分），不要走解析
+   外部 PDF（用户自己的文件）→ tool file-parse
+2. Pre-flight：🔴 按页计费 0.8/页、提交即扣——先看页数估积分（50 页 = 40 积分）告知用户
+   本地限制 CLI 会先校验：.pdf 后缀 / 非空 / ≤100MB
+3. gangtise tool file-parse --file ./x.pdf --wait --output ./x.zip
+   （--wait 内部轮询 ≈316s；外层工具超时设 ≥360s。不带 --wait 则拿 taskId，稍后
+     gangtise tool file-parse-check --task-id <id> --output ./x.zip——取结果免费）
+4. unzip 后读 file.md（图片在 images/）；正文长先 wc -l / head 采样再呈现
+5. 超时不要重跑 file-parse（会重复扣费），用 file-parse-check 拿同一个 taskId 的结果
+```

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

@@ -38,6 +38,9 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | 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） |
+| insight performance-calendar list | `{list, total}` | `list[].performanceReportId`（下载用）/ `list[].securityCodeList[]`（A+H 可能多个）/ `list[].securityName` / `list[].category`（performanceForecast/performanceExpress/performanceAnnouncement）/ `list[].publishDate`（实测带 ` 00:00:00` 后缀）/ `list[].title` / `list[].hasAttachment`（`false` 则无法下载） |
+| insight performance-calendar download | 文件路径（stdout，PDF） | — |
+| tool file-parse | `{taskId, status:"pending", hint}`（提交）；`--wait` 或 `file-parse-check` 就绪后 = 文件路径（stdout，ZIP） | ZIP 内 `file.md` + `images/`；未就绪时 check 输出 `{taskId, status:"pending"}`（退出码 0） |
 | insight report-image list | `[{...}]`（扁平数组，无 `total`） | `[].chunkId`（下载用 `--chunk-id`）/ `[].title` / `[].sourceId` / `[].broker` / `[].category` / `[].page` / `[].totalPages` / `[].imageCaption[]` / `[].imageFootnote[]` / `[].pageContent`（该页 OCR/描述） |
 | insight report-image download | 文件路径（stdout，JPEG） | — |
 | reference securities-search | `{returnedCount, list}` | `list[].gtsCode` / `list[].gtsName` / `list[].category` / `list[].matchScore` / `list[].matchType` |
@@ -73,13 +76,14 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | vault record-download | 文件路径（stdout） | — |
 | vault my-conference-list | `{list, total}` | `list[].conferenceId` / `list[].title` / `list[].category` / `list[].institution.institutionName` / `list[].publishTime` |
 | vault my-conference-download | 文件路径（stdout） | — |
-| vault wechat-message-list | `{list, total}` | `list[].msgId` / `list[].msgContent` / `list[].msgTime` / `list[].wechatGroupName` / `list[].speakerName` / `list[].category` / `list[].tagList` |
+| vault wechat-message-list | `{list, total}` | `list[].msgId` / `list[].content`（正文）/ `list[].url` / `list[].msgTime` / `list[].wechatGroupName` / `list[].speakerName` / `list[].category` / `list[].tagList[].tagCode` / `list[].securityList[].securityCode` / `list[].quoteMsg.quoteContent`（引用消息，无引用为 `null`）。**不是 `msgContent`/`contentUrl`**（旧文档笔误，实测 2026-07-25） |
 | vault wechat-chatroom-list | `{list, total}` | `list[].chatroomName` / `list[].chatroomId` |
 | alternative edb-search | `{list: [...]}` 指标列表 | `indicatorId` / `indicatorName` / `dataSource` / `frequency` / `unit` |
 | alternative edb-data | 列表，每行 `{date, <indicatorId>: value, ...}` 宽表 | `date` + 每个 `--indicator-id` 一列（该日指标值） |
 | alternative concept-info | `{conceptId, conceptName, ...}`（单对象，**非列表**） | `conceptName` / `definition` / `investmentLogic` / `industrySpace` / `competitiveLandscape` / `keyEvents[].date` / `keyEvents[].content`；文本字段未配置为 `null` |
 | alternative concept-securities | `{conceptId, conceptName, securityCount, securityDetail}`（单对象，分组） | `securityCount` / `securityDetail[].groupName` / `securityDetail[].securityList[].securityCode` / `.securityName` / `.isKey` / `.inclusionReason`；无成分股时 `securityDetail` 为 `null` |
-| indicator search | `[{indicatorCode, indicatorName, ...}]`（列表） | `indicatorCode` / `indicatorName` / `description` / `scopeList[].market` / `scopeList[].securityType` / `parameterList[].paramKey` / `.enumList[].value`（专属参数及枚举） / `score` |
-| indicator cross-section | CLI 拍平为宽表 `{list, total}` | `list[].date` / `list[].security` / `list[].name` + 每个指标名一列；**单日多指标 × 多证券**，每行一只证券 |
-| indicator time-series | CLI 拍平为宽表 `{list, total}` | `list[].date` + 序列列：单证券时列=各指标、多证券时列=各证券；每行一个日期 |
+| indicator search | `[{indicatorCode, indicatorName, ...}]`（列表） | `indicatorCode` / `indicatorName` / `description` / `scopeList[].market` / `scopeList[].securityType` / `scopeList[].usageRestriction`（接口限制，`null`=无限制） / `parameterList[].paramKey`（**参数名以此为准**） / `.enumList[].value` / `score` |
+| indicator cross-section | CLI 拍平为宽表 `{list, total}` | `list[].security` / `list[].name` + 每个指标名一列；**单日多指标 × 多证券**，每行一只证券。**v0.30.0 起没有 `date` 列**（查询日期改挂在每个指标的参数上，各列可为不同日期）；原始响应的 `values` 为 `[证券][指标]`（2026-08-01 转置） |
+| indicator time-series | CLI 拍平为宽表 `{list, total}` | `list[].date` + 序列列：单证券时列=各指标、多证券时列=各证券；每行一个日期。原始响应 `values` 仍为 `[序列][日期]` |
+| indicator screener | CLI 拍平为宽表 `{list, total}` | 同 `cross-section`：`list[].security` / `list[].name` + 每个指标名一列，每行一只**命中**的证券；无命中返回空表。原始响应的 `indicatorList[]` 多一个 `field`（F1/F2…），CLI 用它给同 code 的重复列去重 |
 | lookup broker-org / meeting-org list | `[...]` | `[].id` / `[].name` |

package/package.json

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