gangtise-openapi-cli 0.42.0 → 0.43.0

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

@@ -55,7 +55,7 @@ gangtise reference institution-search --keyword <text> [--category <name>] [--to
   | `foreignOpinionInstitution` | `insight foreign-opinion list --broker` | 外资机构观点 |
   | `leadInstitution` | `--institution`（`summary` / `roadshow` / `site-visit` / `strategy` / `vault my-conference` list） | 纪要 / 路演 / 调研 / 线下策略会 / 我的会议的牵头机构 |
 
-  注：API 文档 `categoryList` 只列了前 4 类，但 `foreignOpinionInstitution` 同样是有效过滤值（服务端接受且返回该类）
+  注：`foreignOpinionInstitution` 同样是有效过滤值（服务端接受且返回该类）
 - `--top`：默认 10，**上限 10**；结果按 `matchScore`（`0~1`）降序
 - 免费调用
 - 返回字段：`institutionId` / `institutionName` / `category` / `usageScopes[{apiName, paramName}]`（该机构适用的接口及参数）/ `matchScore`
@@ -95,9 +95,9 @@ gangtise reference constant-category [--format json]
 
 | category | 名称 | 结构 | 用于参数 |
 |----------|------|------|---------|
-| `citicIndustry` | 中信一级行业（30，`1008001xx`） | flat | `--industry` 全命令通用首选（见下方说明） |
-| `swIndustry` | 申万一级行业（31，`104xx0000`） | flat | `--industry`（opinion / research / foreign-report / official-account 可用，但**与中信码不等效**，见下方说明）；`--research-area` 只有 summary / pamirs-summary 认 |
-| `gangtiseIndustry` | Gangtise 研究方向（**只有 6 条方向码** `122000xxx`，不含行业码） | flat | `--research-area` 的方向维度（宏观/策略/固收/金工/海外/其他，见下方说明） |
+| `citicIndustry` | 中信一级行业（`1008001xx`） | flat | `--industry` 全命令通用首选（见下方说明） |
+| `swIndustry` | 申万一级行业（`104xx0000`） | flat | `--industry`（opinion / research / foreign-report / official-account 可用，但**与中信码不等效**，见下方说明）；`--research-area` 只有 summary / pamirs-summary 认 |
+| `gangtiseIndustry` | Gangtise 研究方向（**只有方向码** `122000xxx`，不含行业码） | flat | `--research-area` 的方向维度（宏观/策略/固收/金工/海外/其他，见下方说明） |
 | `domesticCity` | 国内城市（省级 ID） | flat | `--location`（roadshow / site-visit / strategy / forum）|
 | `aShareAnnouncementCategory` | A股公告分类 | tree（2 级） | `insight announcement --category` |
 | `hkShareAnnouncementCategory` | 港股公告分类 | tree（2 级） | `insight announcement-hk --category` |
@@ -113,11 +113,11 @@ gangtise reference constant-category [--format json]
 | `ratingType` | 评级类型 | flat | `bond rating-*` 的 `ratingType` |
 | `exchange` | 交易市场 | flat | `bond` 各命令的 `exchange` |
 
-> **行业 / 研究方向过滤——选哪套 category（⭐ 权威口径，其他文件引用此处、勿重复枚举命令清单以免漂移；逐端点核对）：**
+> **行业 / 研究方向过滤——选哪套 category（⭐ 以此处为准）：**
 >
-> 先记住三套码的归属，**别把行业码算到 `gangtiseIndustry` 头上**：`citicIndustry` = 30 条行业码 `1008001xx`；`swIndustry` = 31 条行业码 `104xx0000`；`gangtiseIndustry` = **只有 6 条方向码** `122000xxx`（宏观 `122000001` / 策略 `122000002` / 固收 `122000003` / 金工 `122000004` / 海外 `122000005` / 其他 `122000007`），里面**没有任何行业**，去它那里找「食品饮料」永远找不到。
+> 先记住三套码的归属，**别把行业码算到 `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 个上**也生效，但不是等效**——两套码的行业成分不同，4 个里有 2 个结果集对不上（research / foreign-report 完全一致；**opinion 与 official-account 传两套码取回的条数相差约 2%–5%**）。所以**统一用中信码**，同一批查询里别把两套码混着传。方向码 `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`）。
 > - **`--research-area`（researchAreaList）→ 用 `citicIndustry` 行业码 `1008001xx`，方向再叠 `gangtiseIndustry` 的 `122000xxx`**。⚠️ **申万码 `104xx0000` 只有 `summary` / `pamirs-summary` 认**，其余端点返 0（与传乱码表现一致，不报错）。逐端点对照（同一行业分别传三套码，✅ = 正常过滤，❌ = 返 0）：
 >
 > | 端点 | 中信 `1008001xx` | 申万 `104xx0000` | 方向 `122000xxx` |
@@ -129,6 +129,7 @@ gangtise reference constant-category [--format json]
 > | `insight site-visit` | ✅ | **❌ 返 0** | ✅ |
 > | `insight forum` | ✅ | **❌ 返 0** | ✅ |
 > | `vault my-conference-list` | ✅ | **❌ 返 0** | ✅ |
+> | `insight highlight` | ✅ | **❌ 不可用** | ✅ |
 >
 > 一句话结论：**行业维度一律传中信码**（唯一全端点通吃的一套），方向维度传 `122000xxx`（`pamirs-summary` 不支持方向）。
 
@@ -195,28 +196,28 @@ gangtise reference sector-search --keyword 半导体 --top 3 --format json   #
 gangtise reference sector-constituents --sector-id 1000001005 --format json
 ```
 
-**申万行业代码全量列表**（`ai security-clue --gts-code` 用的 `821xxx.SWI`）也走这两步——申万行业指数板块的成分就是 31 只行业指数本身：
+**申万行业代码全量列表**（`ai security-clue --gts-code` 用的 `821xxx.SWI`）也走这两步——申万行业指数板块的成分就是各一级行业指数本身：
 
 ```bash
 gangtise reference sector-search --keyword 申万一级行业指数 --format json
 # 取「指数数据板块-行业指数-申万指数-申万一级行业指数」层级的 sectorId（2000000014）
 # 注意：「中国内地股票-指数成份类」层级下的同名节点查成分返回 0 条
 gangtise reference sector-constituents --sector-id 2000000014 --format json
-# → total 31，gtsCode 即 821xxx.SWI
+# → 每条的 gtsCode 即 821xxx.SWI
 ```
 
 单个行业也可以直接 `reference securities-search --keyword 申万银行 --category index` → `821047.SWI`。
 
-## Lookup 本地表（仅剩 2 个）
+## Lookup 本地表
 
 **按名称找机构 ID 优先用 `reference institution-search`**（服务端搜索、覆盖全部 5 类机构、带 usageScopes）；本地表主要用于**全量枚举**券商/会议机构（institution-search 为搜索型：top≤10、非全量）：
 
 ```bash
-gangtise lookup broker-org list           # 券商机构全量（--broker 用；180 条静态表）
-gangtise lookup meeting-org list          # 会议/牵头机构全量（--institution 用；130 条静态表）
+gangtise lookup broker-org list           # 券商机构全量（--broker 用；静态表）
+gangtise lookup meeting-org list          # 会议/牵头机构全量（--institution 用；静态表）
 ```
 
-行业 / 区域 / 公告分类 / 研究方向 / 题材 ID / 申万行业代码已改用 API：`reference constant-list` / `reference concept-search` / `reference sector-constituents`（对应 lookup 子命令已移除）。
+行业 / 区域 / 公告分类 / 研究方向 / 题材 ID / 申万行业代码用 API 查：`reference constant-list` / `reference concept-search` / `reference sector-constituents`。
 
 ### 常见行业别名映射
 
@@ -249,5 +250,7 @@ gangtise raw call insight.research.download --query reportId=<id> --query fileTy
 - endpoint key 格式：`<命令组>.<子命令>.<操作>`，如：
   - `insight.opinion.list`、`insight.announcement-hk.list`、`insight.foreign-opinion.list`、`insight.independent-opinion.list`
   - `reference.securities-search`、`reference.constant-list`、`quote.day-kline`、`fundamental.income-statement`、`ai.knowledge-batch`
-- **JSON 端点**（绝大多数）用 `--body` 传 JSON；**`kind=download` 端点**（各 `*.download`）用 `--query key=value`（可重复）。传反会被 CLI **直接拒绝**（JSON 端点给 `--query`、或 download 端点给 `--body`，都抛 ValidationError，不发请求）
-- 自动翻页 / 重试 / Agent 复用与封装命令一致
+- **endpoint key 不能按命令名猜**（如券商本地表是 `lookup.broker-orgs.list`），先用 `gangtise raw list` 查
+- **JSON 端点**（绝大多数）用 `--body` 传 JSON；**`kind=download` 端点**（各 `*.download`）用 `--query key=value`（可重复）。传反会被 CLI **直接拒绝**（JSON 端点给 `--query`、或 GET 下载端点给 `--body`，都抛 ValidationError，不发请求；POST 下载端点 `tool.file-parse.result` 的参数走 `--body`）
+- `--yes`：删除 / 改动数据的端点必须加才会执行；按条计费的列表省略 `size` 时，也要加它才会越过积分额度保护拉全量
+- **与专用命令一致的只有**自动翻页、重试策略、翻页的完整性标记。K 线全市场分片、多证券分批请求、撞 `limit` 标 `partial`、`--field` 缺列检测、EDE 解包与拍平、时序日期轴自动判定都**只在专用命令里**——能用专用命令就别用 `raw call`

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

@@ -1,6 +1,6 @@
 # Vault 命令详细参数（私域数据）
 
-通用：`--keyword` `--start-time` `--end-time` `--from` `--size`（list 类）。
+列表类命令大多有 `--keyword` `--start-time` `--end-time` `--from` `--size`；`wechat-chatroom-list` 只有 `--from` / `--size`，股票池的查询命令都没有这些选项。`my-conference-list` 按条计费，省略 `--size` 时估算全量超过 1000 积分会报错退出 1，确认后加 `--yes` 或改传 `--size N`。
 
 ---
 
@@ -8,7 +8,7 @@
 
 ```bash
 gangtise vault drive-list [--keyword <text>] [--file-type <n>] [--space-type <n>] [--start-time <datetime>] [--end-time <datetime>] [--from <n>] [--size <n>]
-gangtise vault drive-download --file-id <id> [--output <path>]
+gangtise vault drive-download --file-id <id> [--output <path>] [--resolve-title]
 ```
 
 - `--file-type`：`1` 文档（含 PDF/Word/PPT）| `2` 图片 | `3` 音视频 | `4` 公众号文章 | `5` 其他
@@ -44,12 +44,12 @@ gangtise vault drive-delete-folder --folder-id <id> --yes
 
 ```bash
 gangtise vault record-list [--keyword <text>] [--category <name>] [--space-type <n>] [--start-time <datetime>] [--end-time <datetime>] [--from <n>] [--size <n>]
-gangtise vault record-download --record-id <id> --content-type <type> [--output <path>]
+gangtise vault record-download --record-id <id> --content-type <type> [--output <path>] [--resolve-title]
 ```
 
 - `--category`：`upload` | `link` | `mobile` | `gtNote` | `pc` | `share`（可重复）
 - `--space-type`：`1` 我的速记 | `2` 租户速记
-- `--content-type`（download **必选**）：`original` 原始文件 | `asr` 语音识别 | `summary` AI 速记
+- `--content-type`（download **必选**）：`original` 原始文件 | `asr` 语音识别 | `summary` AI 速记（其他取值 CLI 在本地拒绝：接口对错值报的是「没有文件可供下载」，容易误读成这条记录没附件）
   - 口语映射：「原始文件/原文件」→`original`、「语音识别/转写文本/ASR」→`asr`、「AI速记/智能摘要/会议纪要」→`summary`
   - 「与我分享」类型录音无法下载原始文件
 - 返回字段：`recordId` / `title` / `createTime` / `category` / `recordDuration`（秒） / `recordSize`（Byte）/ `url` / `spaceType` / `uploader`
@@ -58,12 +58,14 @@ gangtise vault record-download --record-id <id> --content-type <type> [--output
 
 ```bash
 gangtise vault my-conference-list [--keyword <text>] [--research-area <id>] [--security <code>] [--institution <id>] [--category <name>] [--source <n>] [--start-time <datetime>] [--end-time <datetime>] [--from <n>] [--size <n>]
-gangtise vault my-conference-download --conference-id <id> --content-type <type> [--output <path>]
+gangtise vault my-conference-download --conference-id <id> --content-type <type> [--output <path>] [--resolve-title]
 ```
 
+- **积分**：列表 0.1/条；下载 50/篇（超时不自动重发）
+
 - `--category`：`earningsCall` 业绩会 | `strategyMeeting` 策略会 | `fundRoadshow` 基金路演 | `shareholdersMeeting` 股东大会 | `maMeeting` 并购会议 | `specialMeeting` 特别会议 | `companyAnalysis` 公司分析 | `industryAnalysis` 行业分析 | `other`（可重复）
 - `--source`：录制来源 `1`=企微会议助理 | `2`=会议服务微信群（可重复；不传返回全部）
-- `--keyword` vs `--research-area`：用户说"关于AI的"用 `--keyword AI`；说"电子行业的会议"用 `--research-area 100800126`（行业用 `citicIndustry` 码 `1008001xx`、方向用 `gangtiseIndustry` 码 `122000xxx`，**不要用申万码 `104xx0000`**——本端点传申万码一律返 0 且不报错，食饮 / 电子 / 医药三个行业交叉验证过，换中信码即正常过滤）
+- `--keyword` vs `--research-area`：用户说"关于AI的"用 `--keyword AI`；说"电子行业的会议"用 `--research-area 100800126`（行业用 `citicIndustry` 码 `1008001xx`、方向用 `gangtiseIndustry` 码 `122000xxx`，**不要用申万码 `104xx0000`**——本端点传申万码一律返 0 且不报错，换中信码即正常过滤）
 - `--content-type`（download **必选**）：`asr` 语音识别 | `summary` AI 速记
 - 返回字段：`conferenceId` / `title` / `publishTime` / `category` / `institution{...}` / `security{...}` / `researchArea{...}` / `guest` / `sourceList`（录制来源，`1`/`2`）
 
@@ -76,8 +78,9 @@ gangtise vault wechat-message-list [--keyword <text>] [--security <code>] [--wec
 - 数据权限：仅用户已绑定并激活群消息助理、且助理已入群的群消息
 - `--security`：按证券代码过滤（如 `000001.SZ`），可重复
 - `--industry`：**只认中信码**（`1008001xx`，见 `reference constant-list --category citicIndustry`）。⚠️ 申万码（`104xx0000`）与任何不认识的值都报 `100005 枚举值非法`——**换中信码即可**。返回行里不含行业标签字段，过滤在服务端完成
-- 🔴 **`--industry` 是收窄工具，不是全量召回**：行业标签由服务端标注，**同一条消息可能挂多个行业，也可能一个都没挂**。同一个关键词加上「本行业」过滤后，命中数只剩三到四成——**少掉的既有没打标签的，也有被标到相邻行业去的**（如半导体相关的消息在计算机 / 机械 / 通信下同样查得到）。所以「按行业筛出 N 条」不能读成「该行业只有 N 条」；要尽量全，用 `--keyword` 取回后本地判断，或把相邻行业码一起查再去重
+- 🔴 **`--industry` 是收窄工具，不是全量召回**：行业标签由服务端标注，**同一条消息可能挂多个行业，也可能一个都没挂**。同一个关键词加上「本行业」过滤后，命中数会明显少于只用关键词——**少掉的既有没打标签的，也有被标到相邻行业去的**（如半导体相关的消息在计算机 / 机械 / 通信下同样查得到）。所以「按行业筛出 N 条」不能读成「该行业只有 N 条」；要尽量全，用 `--keyword` 取回后本地判断，或把相邻行业码一起查再去重
 - `--wechat-group-id`：先用 `vault wechat-chatroom-list` 查；可重复
+- 按偏移量**最多取到第 10000 条**（`--from` + 条数不能超过 10000），且 `total` 最多也只报到 10000——正好报 10000 时实际条数可能更多，CLI 按封顶处理：标 `partial` + `totalCapped`、退出码 3。要更多请缩短时间范围分段取，每段的 `total` 低于 10000 才说明取全了
 - `--category`：`text` | `image` | `documents` | `url`（可重复）
 - `--tag`：`roadShow` | `research` | `strategyMeeting` | `meetingSummary` | `industryComment` | `companyComment` | `earningsReview`（可重复）
 - 返回字段：`msgId` / **`content`**（正文）/ **`url`**（链接）/ `msgTime` / `wechatGroupId` / `wechatGroupName` / `speakerName` / `category` / `tagList[]{tagCode, tagName}` / `securityList[]{securityCode, securityName}` / `quoteMsg{quoteMsgId, quoteContent, quoteUrl}`。正文取 `content`、链接取 `url`（不是 `msgContent` / `contentUrl`）

package/gangtise-openapi/references/errors.md

@@ -1,7 +1,7 @@
 # 错误码、退出码与常见困境自救
 
 > 主文件 `SKILL.md` 只保留最高频的几个码；这里是全表。
-> **退出码语义**：`0` 完整成功（含合法空结果）／ `3` 有数据但不完整（`partial: true`）／ `4` 导出的数据完整，但 `--output` 已被另一次导出替换（见下文「退出码 4」）／ `1` 硬失败。
+> **退出码语义**：`0` 完整成功（含合法空结果）／ `3` 有数据但不完整（`partial: true`）／ `4` 导出的数据完整，但 `--output` 已被另一次导出替换（见下文「退出码 4」）／ `1` 硬失败／ `130` / `143` / `129` 被 Ctrl-C / `kill` / 终端断开中断（进程以该信号结束；本次导出的暂存文件已删除；中断前已发出的请求服务端照常处理并计费）。
 > 报错行末尾的 `[trace <id>]` 是 Gangtise 支持定位问题的唯一凭据，**报障时带上它**。
 
 ## 错误码怎么读
@@ -13,25 +13,25 @@
 | 错误码 | 含义 | CLI 行为 | Agent 是否介入 |
 |--------|------|---------|--------------|
 | `100003` | 参数值非法——**最宽的兜底码**：类型错、`limit` 越界都归这里。**msg 通常已指明字段**（如「请求体字段类型不匹配: size 期望类型 Integer」「limit 最小为 1，最大为 10000」），先读 msg 再猜 | — | 按 msg 指的字段改；msg 没指明才对照 `--help` 查枚举拼写，**不要重试同命令** |
-| `999999` | 系统错误。`indicator`（EDE）的「无数据」不用此码（无数据是保留行列的占位单元格 `null`，见 `commands/indicator.md`；空表另有含义：整轴 code 未识别或参数名写错），所以这个码基本只剩真故障 | 普通端点自动重试 ×2；🔴 贵档与 `indicator` 端点不重试 | 确认参数无误仍报此码即服务端故障 |
+| `999999` | 系统错误。`indicator`（EDE）的「无数据」不用此码（无数据是保留行列的占位单元格 `null`，见 `commands/indicator.md`；代码或参数名写错报 `100003`、缺必填参数报 `100001`，都会点名），所以这个码基本只剩真故障 | 普通端点自动重试 ×2；🔴 贵档与 `indicator` 端点不重试 | 确认参数无误仍报此码即服务端故障 |
 | `410110` | **异步生成中**（HTTP 400，旧码）。新码 `140001`，CLI 两码都认 | 轮询视为 pending | 继续等 |
 | `410111` | **异步生成失败**（HTTP 400，旧码）。新码 `140002`，CLI 两码都认 | 终态 | **不重试**，换参数 |
-| `130002` | 资源不存在——下载类的常见码：`reportId` 不存在 / 非数字多归此码。另有更具体的 `130003`（资源未生成 / 无附件）与 `130005`（`fileType` 非法） | — | 确认 ID 有效且本账号可见；换 `--file-type` 或换一篇验证 |
+| `130002` | 资源不存在——下载类的常见码：`reportId` 不存在 / 非数字多归此码。另有更具体的 `130003`（资源未生成 / 无附件）；`--file-type` 写错由 CLI 在本地报错、不发请求 | — | 确认 ID 有效且本账号可见；换 `--file-type` 或换一篇验证 |
 | `130001` | 数据未找到，或**该指标无权限**（`indicator` 内层失败会带具体 msg 如"指标无权限"） | — | 检查查询条件与指标权限 |
 | `100001` | 缺必填参数——**msg 带字段名**（「缺少必填参数: reportId」） | — | 按 msg 指的字段补上 |
 | `110001` / `110002` | 日期格式错（msg 带字段名）/ 起晚于止。⚠️ **服务端对多种格式做宽松解析**（`2026/07/01`、`20260701`、`07/01/2026` 都能被接受），所以「没报 110001」不等于「格式被按你的意思理解了」 | — | 按参数名：`--*-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 day-kline`/`realtime`/`minute-kline`/`fund-flow` 都会报；**旧版 `day-kline-hk`/`day-kline-us`/`index-day-kline` 静默返回空** | — | `reference securities-search` 确认代码与后缀（`600519.SH` / `00700.HK`） |
 | `110003` | **超出账号数据权限的时间范围**。范围按账号等级而定、**不是平台常量**；窗口按**账号**配、不按接口配 | — | 把日期移进权限范围内；整个区间都早于下界时缩短窗口无用（`--fiscal-year 2015` 无论怎么缩都报错）；**换接口绕不过去**，要更长历史联系客户经理开通。⚠️ 区间**跨过**下界时，`indicator` 与 `bond` 报这个码，`quote` 日 K 与 `valuation-analysis` 则从下界起返回、不报错——核对首行日期 |
-| `100006` | 查询/下载数量超限（旧码 `430007`）；`fund-flow` 全市场不传日期即此码；**`indicator cross-section` / `time-series` 单次单元格数超 30000** 也是此码（msg 写明限额） | — | 缩短日期范围或调小 `--size`/`--limit`；全市场场景应已自动分片；EDE 按「截面=证券数×指标数、时序=证券数或指标数×日期数」拆批 |
+| `100006` | 查询/下载数量超限；**`indicator cross-section` / `time-series` 单次单元格数超 30000** 也是此码（msg 写明限额） | — | 缩短日期范围或调小 `--size`/`--limit`；全市场场景应已自动分片；EDE 按「截面=证券数×指标数、时序=证券数或指标数×日期数」拆批 |
 | `240001` | 财报期未披露或超出查询期（`earnings-review` 提交阶段就报，**不扣积分**） | — | 换更早的 `--period`（`2025q3` → `2025interim`） |
-| `250001` | 不支持的数据源（旧码 `433007`） | — | 检查 `resourceType + sourceId` 组合 |
-| `999011` | 开发账号凭证无效（旧码 `8000014`/`8000015`，已合并，不区分 AK 错还是 SK 错） | 登录即失败，**不重试** | 检查 `GANGTISE_ACCESS_KEY`/`GANGTISE_SECRET_KEY` 是否写反或未 export |
+| `250001` | 不支持的数据源 | — | 检查 `resourceType + sourceId` 组合 |
+| `999011` | 开发账号凭证无效（不区分 AK 错还是 SK 错） | 登录即失败，**不重试** | 检查 `GANGTISE_ACCESS_KEY`/`GANGTISE_SECRET_KEY` 是否写反或未 export |
 | `999010` | 接口地址不存在 | — | `raw call` 的 key 可能已下线，用 `gangtise raw list` 核对 |
 | `999004` | 无资源权限。**整库未开通与单条记录不可见都走这个码**——`insight pamirs-summary list`（专家纪要库需单独购买）未开通时即报此码 | — | `list` 撞上多为整库未开通，先确认该数据库是否已购买；`download` 撞上再考虑换一条本账号可见的记录 |
 | `0000001008` | Token 服务端失效（他处登录挤掉）——**旧码，token 自愈依赖它** | **强制重新登录并重试一次** | 无 AK/SK 时无法自愈，提示重新登录 |
 | `0000001007` | 请求未携带 Bearer token | — | 检查 `GANGTISE_TOKEN` / AK/SK 是否已 export |
-| `900002` | **请求方法不正确**（msg「请求类型有误」，HTTP 405） | — | `raw call` 时确认该 endpoint 是 GET 还是 POST |
-| `140002` | 终态失败：AI 异步生成失败；`indicator` 的指标必填参数缺失 / 枚举越界 / 表达式语法错；或其他接口的「业务处理失败」（与入参无关） | **不立即重试**（终态码） | msg 指向参数就按 msg 改参数重提（EDE 的参数名与枚举读 `indicator search --format json` 的 `parameterList`）；「业务处理失败」则稍后再试，持续出现带 trace 报障 |
+| `900002` | **请求方法不正确**（msg「请求类型有误」，HTTP 405） | — | 请求方法由 CLI 按端点固定、用户改不了；出现说明接口的方法变了，带 trace 反馈 |
+| `140002` | 终态失败：AI 异步生成失败；`indicator` 的枚举越界 / 表达式语法错；或其他接口的「业务处理失败」（与入参无关） | **不立即重试**（终态码） | msg 指向参数就按 msg 改参数重提（EDE 的参数名与枚举读 `indicator search --format json` 的 `parameterList`）；「业务处理失败」则稍后再试，持续出现带 trace 报障 |
 | `230003` | 股票池数量已达账号上限（30 个） | — | 先 `vault stock-pool-delete` 删掉不用的池再建 |
 | `230006` | 建 / 改股票池撞池名重复 | — | 先 `vault stock-pool-list` 看现有名称再换一个 |
 | `230007` | 股票池名超过 10 个字符（中文算 1 个） | — | 缩短名称；终端里建的老池可以更长，本接口不行 |
@@ -40,11 +40,10 @@
 
 - **日期用「年在前」写法**：`YYYY-MM-DD`（首选）、`YYYY/MM/DD`、`YYYYMMDD` 三种 CLI 都收，并**统一归一成 `YYYY-MM-DD` 再发出**；时间加 `[ HH:mm[:ss]]`（秒可省、空格或 `T` 分隔）或用 10/13 位时间戳。🔴 **「年在后」写法（`01-07-2026`、`07/01/2026`）CLI 直接报 `ValidationError`，这是有意的**——接口本身会解析它，且**一律按美式「月在前」**（`01-07-2026` = 1 月 7 日，`07-01-2026` = 7 月 1 日）。按欧洲/国际习惯写 `01-07-2026` 想表达「7 月 1 日」的，会拿到差半年的数据且**不报错**；本地拒掉才有信号，还省一次请求与计费。绕过 CLI 直连接口时务必自己统一用 `YYYY-MM-DD`
 - **财报接口的日期按「报告期末」过滤**，不是公告日：`fundamental balance-sheet` 等的 `--start-date`/`--end-date` 匹配的是 `endDate` 字段（如 `20200630`）；公告日看 `earliestAnncDate`（首次公告日，做时点对齐用这个）而不是 `announcementDate`。**查某期财报要传季度末日期**（`2020-06-30` / `2020-03-31` / `2020-09-30` / `2020-12-31`）；传 `2020-07-01` 这类非报告期日期会返回 0 行，属正常行为，不是没数据
-- **非法证券代码**：`quote day-kline` / `realtime` / `minute-kline` / `fund-flow` 与 Fundamental 系都会报 `120001`，按报错核对后缀即可。⚠️ **三个已下线的旧端点 `quote day-kline-hk` / `day-kline-us` / `index-day-kline` 则返回空结果**，与"该票该区间真无数据"无法区分——**用这三个拿到空结果时先回头核对代码后缀**。它们的能力已并入统一 `day-kline`（支持 A 股 / 港股 / 美股 / 沪深 ETF / 交易所指数 / 概念指数 `.GT` / 行业指数 `.CI` `.SWI` / 20 个全球指数），新代码直接用 `day-kline`
-- **枚举值拼错基本都会报 `100005`，但「字段名不被该端点支持」仍然静默**：纪要 `summary`、三个公告 list、路演 `roadshow`、调研 `site-visit`、`insight research`、`foreign-report`、`official-account` 的 `--search-type` / `--rank-type` / `--category` / `--market` 等传非法值报 `100005`。⚠️ **剩下的口子是「该端点根本没有这个参数」**：传一个端点不支持的字段名（如给 `opinion` 传 `searchType`——它只有 `--rank-type`）会被静默丢弃、按未传处理，返回未经筛选的全库而不报错。**CLI 本地拦截**：全部 `--search-type` / `--rank-type`、全部 `--file-type`（`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` 等仍是自由字符串，拼错不报错也不生效——这些要自己核对。**拼错的筛选条件会伪装成"结果正常"，枚举拼写要自己保证**
+- **非法证券代码**：`quote day-kline` / `realtime` / `minute-kline` / `fund-flow` 与 Fundamental 系都会报 `120001`，按报错核对后缀即可。⚠️ **三个已弃用的旧端点 `quote day-kline-hk` / `day-kline-us` / `index-day-kline` 则返回空结果**，与"该票该区间真无数据"无法区分——**用这三个拿到空结果时先回头核对代码后缀**。它们的能力已并入统一 `day-kline`（支持 A 股 / 港股 / 美股 / 沪深 ETF / 交易所指数 / 概念指数 `.GT` / 行业指数 `.CI` `.SWI` / 全球指数），新代码直接用 `day-kline`
+- **枚举值拼错不一定报错**：`--search-type` / `--rank-type` 传非法值报 `100005`；但 `insight foreign-report --region` 写错区域码会返回全量、不报错，拿到「看着正常」的结果。⚠️ **「该端点根本没有这个参数」同样静默**：经 `raw call` 手写请求体时，传端点不支持的字段名（如给 `opinion` 传 `searchType`——它只有 `--rank-type`）会被丢弃、按未传处理，返回未经筛选的结果（专用命令对不存在的选项直接报 unknown option）。**CLI 本地拦截的**：全部 `--search-type` / `--rank-type`、全部 `--file-type`（`foreign-report` 为 1–4、其余 1–2）、`pamirs-summary` 与财报日历的 `--category` / `--market`、`--top` 上限、`reference securities-search` / `institution-search` / `official-account-search` 的 `--category`、`vault record-download` / `my-conference-download` 的 `--content-type`、`ai hot-topic --category`、`ai security-clue --source`。**其余取值（如 `foreign-report --region`、`--llm-tag`、`theme-tracking --type`）CLI 不拦**，写之前对照 `--help` 与对应命令文档核对拼写——**拼错的筛选条件会伪装成「结果正常」**
 - **股票池写操作的单条失败不报错**：`vault stock-pool-add-stock` / `stock-pool-remove-stock` / `stock-pool-delete` 是逐条处理的，证券代码不存在这类单条失败仍返回成功信封（`code` 为 `000000`），失败明细在 `failList` 里。**CLI 已拦**：`failList` 非空时 stderr 列出失败项、结果标 `partial`、退出码 3。绕过 CLI 直连接口时要自己读 `failList`，别只看 `code`
-- **`viewpoint-debate` 传敏感内容不会被提前拦截**——不返回 `240002`，而是照常受理、扣满 50 积分、生成阶段才以 `410111` 失败。**提交前自己把关措辞**
-- **`ai one-pager` 的非法 `mode` 被静默忽略**，照常生成并扣 50 积分
+- **`viewpoint-debate` 的观点过不了平台的敏感词检测时不会被提前拦截**——不返回 `240002`，而是照常受理、扣 50 积分、生成阶段才以 `410111` 失败；同样的内容重提仍会失败。**提交前自己把关措辞**
 
 ## 官方文档列出、但未见触发的码
 
@@ -56,12 +55,12 @@
 | `999007` | 请求方法不支持 | 实际返回旧码 `900002`（HTTP 405）。`999008`（Content-Type 不支持，HTTP 415）与 `999009`（请求体无法解析，HTTP 400）按文档返回 |
 | `999003` / `999005` / `999006` | 无接口权限 / 积分不足 / 限流 | 需特定账号状态才会出现 |
 | `999012`–`999016` | 账号禁用/过期、租户失效、无长期 token、IP 不合规 | 需特定账号状态才会出现 |
-| `100002` / `100004` / `100005` | 类型错 / 分页非法 / 枚举非法 | 类型错归 `100003`。**`100005`（枚举非法）与 `100006`（`size` 超 50）在各 list 端点上普遍触发**（`official-account` / `research` / `foreign-report` / 三个 opinion / `summary`）。仍按未传处理的只剩「该端点不支持的字段名」，见上方「不报错的坑」 |
+| `100002` / `100004` / `100005` | 类型错 / 分页非法 / 枚举非法 | 类型错归 `100003`。**`100005`（枚举非法）与 `100006`（单页 `size` 超 50，`raw call` 发单页时会遇到；CLI 的 `--size` 会自动拆页，可以大于 50）在各 list 端点上普遍触发**（`official-account` / `research` / `foreign-report` / 三个 opinion / `summary`）。仍按未传处理的：「该端点不支持的字段名」与 `foreign-report --region` 的非法值，见上方「不报错的坑」 |
 | `130004` | 下载 ID 非数字 | 多归 `130002` |
-| `140001` / `140002` | 结果生成中 / 处理失败 | 异步端点仍用 `410110` / `410111` |
+| `140001` | 结果生成中 | 异步端点仍用旧码 `410110`（`140002` 已在用，见上方常用码表） |
 | `210001` / `220001` / `230001` | 研报/观点/分享文件不支持下载 | 未见触发 |
 | `230002` | 微信账号未绑定（私域）。⚠️ **`vault wechat-*` 就在该模块下、够得着**：要求先绑定并激活群消息助理且助理已入群 | 已绑定账号不会遇到 |
-| `240002` / `240003` | 敏感词 / 模式不支持 | 敏感词走 `410111`；`one-pager` 的非法 `mode` 被静默忽略 |
+| `240002` / `240003` | 敏感词 / 模式不支持 | 敏感词走 `410111` |
 | `903301` / `10011401` | 今日调用上限 / 白名单未开通 | 历史遗留，未见触发。不臆断对应新码——`10011401` 按语义更接近 `999003`（未开通接口权限）而非 `999016`（IP 限制），别据此去查 IP |
 
 ## 非错误码
@@ -76,7 +75,7 @@
 
 `partial: true`，保留已取到的部分；stderr 有 warning，`--format json` 才看得见标记，table/csv/jsonl 只有数据行、看不出问题。**拿到 3 就必须告知用户缺了哪段，不能当成功静默继续。**
 
-- 触发场景：翻页 / K 线分片有页失败、服务端返回行数与 `total` 矛盾（提前短页）、`total` 撞服务端上限（`totalCapped`：`total` 是封顶值而非真实条数）、`quote` 系带 `--field` 时请求了但服务端没回的列（`missingFields`）。附带定位字段：页失败 `failedPages`；分片失败 `failedShards`、分片撞行数上限 `truncatedShards`（均带日期区间可缩窗补拉）、只有部分分片返回的列 `droppedColumns`（合并结果的列集取自第一个有数据的分片，多出来的列放不下，需要就缩小日期区间单独拉）；缺列 `missingFields`（字段名写错或已下线，按 `references/fields.md` 核对）；多证券逐只请求里撞行数上限的证券 `truncatedSecurities`。EDE 的 `omittedIndicators` / `omittedSecurities` 仍在，但写错的 code 在服务端就被 `100003` 拒了（退出 1），这条路基本收不到样本
+- 触发场景：翻页 / K 线分片有页失败、服务端返回行数与 `total` 矛盾（提前短页）、`total` 撞服务端上限（`totalCapped`：`total` 是封顶值而非真实条数，或正好等于偏移窗口、窗口外的行取不到也数不到）、`quote` 系带 `--field` 时请求了但服务端没回的列（`missingFields`）。附带定位字段：页失败 `failedPages`；分片失败 `failedShards`、分片撞行数上限 `truncatedShards`（均带日期区间可缩窗补拉）、只有部分分片返回的列 `droppedColumns`（合并结果的列集取自第一个有数据的分片，多出来的列放不下，需要就缩小日期区间单独拉）；缺列 `missingFields`（字段名写错或已下线，按 `references/fields.md` 核对）；多证券分批请求里撞行数上限的证券 `truncatedSecurities`；翻页时同一行在相邻两页各出现一次 `duplicateRows`（列表按时间这类可重复的字段排序，同一时刻的一组数据跨在页边界上时，重复了几行也就漏了几行；重复行已去掉，缩短时间范围重拉可补齐）；同一 ID 在后面的页以不同内容再次出现 `changedRows`（翻页期间列表有变动、也可能漏了行；两版都保留，按 ID 去重只留一版，重拉即可；重拉后仍在同一处出现，说明该列表同一 ID 对应多条记录，按 ID 去重前先核对）。EDE 的 `omittedIndicators` / `omittedSecurities`：服务端对写错的 code 直接报 `100003`（退出 1），所以这两个标记很少出现
 - **EDE 代码写错是退出码 1 + `100003`，msg 里直接点名是哪个 code**（美股后缀用 `.O`/`.N`，不是 `.US`），不用从退出码 3 反推。真的没覆盖是占位单元格（统一 `null`）+ 退出码 0
 - **`screener` 的缺列按表达式的布尔结构判**：把缺列的变量当作「无法求值」，看整个表达式**是否还有一条能成立的分支**——`A && B` 要两边都可求值，`A || B` 只要一边。**一条分支都不剩 → 退出码 1、不输出任何结果**（返回的行以「通过了该条件」的名义呈现，而条件根本无法证明被执行过）；**还有分支可求值，或缺的只是未参与表达式的辅助变量 → `partial` + 退出码 3**。所以 `F1 || F2` 缺 F1 是降级，缺两个则是致命；`F1 && (F2 || F3)` 缺 F1 仍是致命。⚠️ **前提是服务端返回了命中行**——零命中时走「nothing matched」+ **退出码 0**。**空集别急着当成「条件成立但无标的符合」**：指标码写错会直接报 `100003`（退出 1），剩下**三种成因产生逐字相同的输出**——① 真的没有标的满足条件；② **日期没落在报告期末**（报告期类指标此时整批 `null`）；③ **该指标不覆盖这批证券**（拿 A 股专属指标查港美股，如 `mgn_*` 融资融券系列）。②③ 都要靠单查一行确认，不能只改日期
 
@@ -108,18 +107,18 @@
 **`list` 全空但参数看着对**
 1. 时间窗太窄 → 扩到 30 天试
 2. `--security` 后缀拼错（如 `300750` 漏了 `.SZ`）
-3. 行业 ID 用错体系：`--industry`（用 `citicIndustry` 码 `1008001xx`）/ `--research-area`（行业同样用 `citicIndustry` 码 `1008001xx`，方向才用 `gangtiseIndustry` 码 `122000xxx`——`gangtiseIndustry` 里**只有 6 条方向码、没有行业**）/ `--gts-code`（申万 `821xxx.SWI`）。申万数字码 `104xx0000` 用于 `--research-area` 时多数端点返 0，详见 `references/commands/reference-and-lookup.md`
+3. 行业 ID 用错体系：`--industry`（用 `citicIndustry` 码 `1008001xx`）/ `--research-area`（行业同样用 `citicIndustry` 码 `1008001xx`，方向才用 `gangtiseIndustry` 码 `122000xxx`——`gangtiseIndustry` 里**只有方向码、没有行业**）/ `--gts-code`（申万 `821xxx.SWI`）。申万数字码 `104xx0000` 用于 `--research-area` 时多数端点返 0，详见 `references/commands/reference-and-lookup.md`
 4. `--rating` / `--category` 等枚举值拼错（参考对应命令的 references 文件）
 
-**`999011` 凭证无效**（旧码 `8000014`/`8000015`；不区分是 AK 错还是 SK 错，**登录直接失败、CLI 不重试**）
+**`999011` 凭证无效**（不区分是 AK 错还是 SK 错，**登录直接失败、CLI 不重试**）
 1. `echo $GANGTISE_ACCESS_KEY` 验环境变量是否 export
 2. AK 和 SK 是否写反
-3. 账号是否到期 / 异常（`gangtise auth status`；对应 `999012`/`999013`）
+3. 账号是否到期 / 异常：`gangtise auth login` 会真的登录一次，到期或禁用时报 `999012` / `999013`（`auth status` 只看本地缓存，判断不了）
 
 **异步任务 `410111` 反复**（生成失败，终态）
-1. `viewpoint-debate`：先检查观点措辞——敏感内容不会被提前拦截，会扣满 50 积分再以 `410111` 失败
+1. `viewpoint-debate`：先检查观点措辞——过不了敏感词检测的内容不会被提前拦截，会扣 50 积分再以 `410111` 失败；换个说法再提交，同样的内容重试仍会失败
 2. `earnings-review`：换更早的 `--period`（如 `2025q3` → `2025interim`）
-3. `report-date` 用已发布的标准期：`xxxx-06-30` / `xxxx-12-31`
+3. `--period` 用已发布的报告期（如 `2025q3` / `2025interim` / `2025annual`）
 4. 若提交阶段就返回 `240001`（财报期未披露），说明该期不可查且**未扣积分**，别再换参数试
 5. 直接告知用户该期数据暂不可用
 
@@ -127,11 +126,11 @@
 
 **翻页很慢 / 卡住** → `--verbose` 看哪一页慢；可 `GANGTISE_PAGE_CONCURRENCY=10` 提速，或缩小时间范围。
 
-**全市场 K 线报 `100006`**（旧码 `430007`）→ 单日数据仍超 10K 行（极端情况）→ 临时改用更窄的 `--start-date`/`--end-date`，或改为单只 `--security` 单独拉。
+**全市场 K 线报 `100006`**→ 单日数据仍超 10K 行（极端情况）→ 临时改用更窄的 `--start-date`/`--end-date`，或改为单只 `--security` 单独拉。
 
 **`quote day-kline --security all` 被 CLI 拒**（`'all' is not a whole-market keyword`）→ 服务端不支持该写法 → 换成 `aShares` / `hkStocks` / `usStocks` 之一，单独传。
 
-**AI 生成命令超时** → `one-pager` 等 7 个 agent 类 CLI 已内置 120 秒超时下限，无需再设 `GANGTISE_TIMEOUT_MS`。超时报错时内容可能已在服务端生成并扣费，**同参数重跑会再扣一次**：先告知用户，别自动重跑（详见 `references/commands/ai.md`）。`stock-summary` / `hot-topic` 可前置 `GANGTISE_TIMEOUT_MS=120000`（写整数毫秒；没按所写数值生效时 stderr 会提示）。
+**AI 生成命令超时** → `one-pager` 等同步生成类命令 CLI 已内置 120 秒超时下限，无需再设 `GANGTISE_TIMEOUT_MS`。超时报错时内容可能已在服务端生成并扣费，**同参数重跑会再扣一次**：先告知用户，别自动重跑（详见 `references/commands/ai.md`）。`stock-summary` 同样已内置 120 秒下限；`hot-topic` 可前置 `GANGTISE_TIMEOUT_MS=120000`（写整数毫秒；没按所写数值生效时 stderr 会提示）。
 
 **估值结果出现大量 `null`** → 最新交易日数据未入库 → 加 `--skip-null` 过滤掉 `value` / `percentileRank` 为 null 的行。
 

package/gangtise-openapi/references/examples.md

@@ -2,6 +2,8 @@
 
 每个示例展示从用户语句到完整命令的全流程。示例集中在这里，Skill 主文件只放规则；遇到不确定的场景时来这里查同类。
 
+**日期占位**：`<今天>`、`<今天-7天>`、`<最新交易日>` 这类写法按实跑当天换算成 `YYYY-MM-DD`；写成具体日期的（如报告期末 `2025-12-31`）照抄即可。回溯窗口有限（研报、观点等约 3 个月），别把旧日期原样照抄。
+
 ---
 
 ## 例 1：研报检索 ＋ 下载（list→download 多步编排）
@@ -16,11 +18,11 @@
 3. Pre-flight：
    - 认证 OK
    - 结果可能 >200 条 → 🔴 询问"先看前 20 还是导出全量？"
-   - 下载格式 → 🔴 询问 PDF 还是 Markdown
+   - 下载格式：研报下载默认 PDF（`--file-type 2` 为 Markdown），用户没指定就不必问
 4. gangtise insight research list \
      --broker C100000026 \
      --category macro --category strategy \
-     --start-time "2026-04-08 00:00:00" --end-time "2026-04-15 23:59:59" \
+     --start-time "<今天-7天> 00:00:00" --end-time "<今天> 23:59:59" \
      --rank-type 2 --format json
    （选"导出全量"分支：改 `--format jsonl --output cicc_macro.jsonl` 落盘，再 `wc -l` / `head` 采样，别把全量塞进上下文）
 5. 提取 reportId + title 展示，让用户选择具体一篇 → 确认 file-type
@@ -37,7 +39,7 @@
 3. Pre-flight：模糊时间已映射，认证 OK，无歧义
 4. gangtise insight opinion list \
      --keyword AI \
-     --start-time "2026-04-08 00:00:00" --end-time "2026-04-15 23:59:59" \
+     --start-time "<今天-7天> 00:00:00" --end-time "<今天> 23:59:59" \
      --rank-type 2 --size 20 --format json
 5. 提取 list[].title / author.chiefName / author.brokerName / publishTime / brief，按时间倒序列表
 6. 用户要看某几条全文 → 取对应 chiefOpinionId：
@@ -81,7 +83,7 @@
 2. 比亚迪 A 股 002594.SZ，港股 01211.HK
    "最近" → K 线默认今日往前 45 天（保证含最近 10 个交易日）
 3. Pre-flight：认证 OK
-4. gangtise quote day-kline --security 002594.SZ --security 01211.HK --start-date 2026-03-19 --end-date 2026-05-03 --format json
+4. gangtise quote day-kline --security 002594.SZ --security 01211.HK --start-date <今天-45天> --end-date <今天> --format json
 5. 按 securityCode 分组，各自按 tradeDate 取尾部最近 10 个交易日
    注意：两地交易日历不同（A 股与港股假期不重合），同一日期未必两边都有行——按 securityCode 分组后再取尾部，别按行下标对齐
 ```
@@ -91,10 +93,10 @@
 **用户**："查上证综指最近的指数"
 
 ```
-1. 路由 → quote day-kline（指数已并入，index-day-kline 已下线）
+1. 路由 → quote day-kline（指数已并入，index-day-kline 已弃用）
 2. 上证综指 → 000001.SH；"最近" → 今日往前 45 天
 3. Pre-flight：认证 OK；今天若周末 end-date 仍填当天，API 返回最近交易日
-4. gangtise quote day-kline --security 000001.SH --start-date 2026-03-19 --end-date 2026-05-03 --format json
+4. gangtise quote day-kline --security 000001.SH --start-date <今天-45天> --end-date <今天> --format json
 5. 按 tradeDate 取尾部最近 10 个交易日。**不要用 --limit 20**（截取的是窗口开头）
 ```
 
@@ -138,7 +140,7 @@
    返回 list[0].gtsCode = "603739.SH"
 3. 拼正式查询：
      gangtise insight research list --security 603739.SH --rank-type 2 \
-       --start-time "2026-04-08 00:00:00" --end-time "2026-04-15 23:59:59" --format json
+       --start-time "<今天-7天> 00:00:00" --end-time "<今天> 23:59:59" --format json
 ```
 
 ## 例 10：实时行情（盘中快照，跨市场）
@@ -155,7 +157,7 @@
      --format json
 5. 返回最新时刻快照；非交易时间返回最近一个交易日的收盘快照
    注意：日 K 线（day-kline）不返回盘中数据，问"现在/此刻"必须走 realtime
-   沪深 ETF（512800.SH）与 20 个全球指数（SPX.SPI 标普500 / N225.NKI 日经225 / HSI.HI 恒生…）同样走 realtime，
+   沪深 ETF（512800.SH）与全球指数（SPX.SPI 标普500 / N225.NKI 日经225 / HSI.HI 恒生…）同样走 realtime，
    代码清单见 references/commands/quote.md；全球指数 volume/amount/amplitude 为 null，tradeTime 是交易所当地时间
 ```
 
@@ -164,11 +166,11 @@
 **用户**："苹果过去一个月的日 K 线"
 
 ```
-1. 路由 → quote day-kline（仅历史；盘中数据走 realtime。day-kline-us 已下线，不校验代码）
+1. 路由 → quote day-kline（仅历史；盘中数据走 realtime。day-kline-us 已弃用，不校验代码）
 2. 苹果 AAPL.O；"过去一个月" → 今日往前 30 天
 3. Pre-flight：认证 OK；当日数据约 07:00（北京时间）入库
 4. gangtise quote day-kline --security AAPL.O \
-     --start-date 2026-04-22 --end-date 2026-05-22 \
+     --start-date <今天-30天> --end-date <今天> \
      --field tradeDate --field open --field close --field volume --field pctChange --format json
 5. 按 tradeDate 排序展示
 ```
@@ -181,11 +183,12 @@
 1. 路由 → ai earnings-review（异步）
 2. 茅台 600519.SH；--period 2025q3
 3. Pre-flight：异步任务，告知用户"提交后需等待，期间可以做别的"
-4. gangtise ai earnings-review --security-code 600519.SH --period 2025q3 --format json
-   → 返回 {dataId: "xxx"}
-5. 等 30s-1min 后调 check：
+4. gangtise ai earnings-review --security-code 600519.SH --period 2025q3 --wait --format json
+   （--wait 在 CLI 内轮询约 5 分钟，外层工具超时给足 360 秒以上；完成即输出 {date, content}）
+   → 取 content 呈现
+5. 不能等那么久时去掉 --wait：提交返回 {dataId, status, hint}，之后手动查：
      gangtise ai earnings-review-check --data-id xxx --format json
-   - 若 {status: "pending"} → 再等再 check（最多 3 次）
+   - 若 {dataId, status: "pending", hint} → 过两分钟再查；**仍在生成时别重新提交**（重提再扣 50 积分），把 dataId 交给用户稍后查
    - 若 {date, content} → 取 content 呈现
    - 若 410111（新码 140002）→ 终态失败，**不要重提同一任务**（会再扣 50 积分且结果相同）；改参数后再提交，或直接告知用户该期数据暂不可用
 ```
@@ -223,7 +226,7 @@
      → 同名板块可能出现在多个层级，用 hierarchy 区分：
        中国内地股票-概念类-科技-半导体设备 → sectorId 1000001005
 3. gangtise reference sector-constituents --sector-id 1000001005 --format json
-     → {total: 59, list: [{gtsCode, gtsName}, ...]}
+     → {total, list: [{gtsCode, gtsName}, ...]}
 4. 陷阱：sectorId 必须来自 sector-search；拿题材 conceptId（如 121000130）来查会返回 0 条
 5. 呈现：total + 前 20 只列表
 ```
@@ -232,7 +235,7 @@
 
 **用户**："把茅台、五粮液、宁德时代 2025 年营收和已实现 EPS，与最新 PE/PB 做成一张表"
 
-> 示例里的 `2026-07-31` 是写作时的最新交易日，实跑时替换为当下的最新交易日即可；PE 与 PB 同为日频。
+> PE 与 PB 同为日频，用 `<最新交易日>` 即可。
 
 ```
 1. 路由 → indicator：多证券批量取一组已实现财务 / 估值指标；不是逐只 fundamental，也不是 EDB。
@@ -247,27 +250,29 @@
    - scopeList：覆盖全部三只 A 股；缺失/null/空也视为不通过
    - parameterList：补 required 参数并核对枚举
    任一不符 → 回退相应专用接口。
-3. 两类指标日期语义不同 → 拆两次截面，均加 `--key-by code`（列头用 indicatorCode，跨表按 code 稳定合并、免受同名/服务端重排干扰；省略 reportType 即取合并口径，label 与取数已一致：1=合并 2=合并(调整) 3=母公司 4=母公司(调整)）：
+3. 两类指标日期语义不同 → 拆两次截面，均加 `--key-by code`（列头用 indicatorCode，跨表按 code 稳定合并、免受同名/服务端重排干扰；省略 reportType 即取合并口径：1=合并 2=合并(调整) 3=母公司 4=母公司(调整)）：
    a) 财务（营收/EPS）用报告期末 2025-12-31：
      gangtise indicator cross-section \
        --indicator is_op_rev --indicator is_eps_bas \
+       --indicator-param "is_op_rev:reportDate=2025-12-31" --indicator-param "is_eps_bas:reportDate=2025-12-31" \
        --security 600519.SH --security 000858.SZ --security 300750.SZ \
        --date 2025-12-31 --key-by code --format json
+     （报告期类指标必须显式给 reportDate；--date 对已带 reportDate 的指标不生效）
    b) 估值 PE + PB 同为日频，用同一个最新交易日即可（finc_pb_mrq 在任意交易日都有数；
       用季末日期会拿到几个月前的陈值）。
       ⚠️ 要估值指标的历史序列做分位/回测，两个接口都拉一遍交叉核：EDE 按正式财报
       披露日切换财报口径且历史期用含重述后的最新数据回算，fundamental valuation-analysis
-      按业绩快报切、保留当时披露的原始数据，同一天取到的值可能不同（PE TTM 已核对；
-      PB 是 MRQ 口径，切换规则未单独核对）。详见 indicator.md：
+      按业绩快报切、保留当时披露的原始数据，同一天取到的值可能不同（PB 是
+      MRQ 口径，切换规则以实际取数为准）。详见 indicator.md：
      gangtise indicator cross-section --indicator finc_pe_ttm --indicator finc_pb_mrq \
        --security 600519.SH --security 000858.SZ --security 300750.SZ \
-       --date 2026-07-31 --key-by code --format json
+       --date <最新交易日> --key-by code --format json
 4. 按 security 合并两张宽表（列头即 indicatorCode，各取所需日期的值）；不要把不同日期语义的指标塞进同一个 --date。
 5. 计费：search 免费；两次取数各按请求单元格数量计费，每次不足 100 单元格按 100 计。
 6. 无数据（无覆盖 / 非交易日 / 未来日期）一律保留行列并给占位单元格，退出码 0——占位值统一是 null（见 commands/indicator.md）；⚠️ 报告期类指标（is_*）的时序只有报告期末那几行是真值，别对整列手工求均值。代码写错或参数名写错则直接报 100003 并点名是哪个（指标码拼错、证券后缀错如美股写成 .US、参数名写错、同 code 重复配置），按报错改即可。
 ```
 
-## 例 15b：帕米尔专家纪要（新库，筛选项与踩坑都和 summary 不同）
+## 例 15b：帕米尔专家纪要（独立库，筛选项与踩坑都和 summary 不同）
 
 **用户**："看看帕米尔最近有什么 PCB 相关的纪要" / "帕米尔纪要下载一篇"
 
@@ -275,15 +280,12 @@
 1. 确认走的是帕米尔而不是普通纪要——两者是不同的库，pamirs 需单独购买专家纪要数据库。
    用户没点名"帕米尔/Pamirs"就走 insight summary。
 2. 检索（全文 + 按相关度）：
-     gangtise insight pamirs-summary list --keyword PCB --search-type 2 --rank-type 1 \
-       --size 20 --format json
-   - --search-type 2 = 全文（标题搜索是 1，命中少很多）
-   - --rank-type 1 在有 keyword 时按相关度挑条目；要最新就用 2。差别多大取决于关键词本身，
-     --search-type 不影响 rank-type 1 挑哪些条目（这里加 2 是为了扩大命中面，不是为了排序）
+     gangtise insight pamirs-summary list --keyword PCB --rank-type 1 --size 20 --format json
+   - --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. 🔴 别拉全量再本地按类别/市场分组——服务端只在你用该字段过滤时才回填标签：
-   不带 --category 查，categoryList 100% 是空数组；conceptList 任何查法都是空。
-   要分组就让服务端筛：
+3. 🔴 别拉全量再本地按类别/市场分组——categoryList / conceptList / marketList 这几个标签字段稀疏，
+   是否有值随记录和查法而变（用该字段过滤时回填率更高，详见 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
@@ -300,15 +302,15 @@
 1. 路由 → quote fund-flow（A 股日频资金流向，免费；仅历史，约 16:30 入库）
 2. 个股：宁德时代 300750.SZ；"最近一个月" → 今日往前 30 天
    gangtise quote fund-flow --security 300750.SZ \
-     --start-date 2026-06-06 --end-date 2026-07-06 \
+     --start-date <今天-30天> --end-date <今天> \
      --field tradeDate --field mainNetInflow --field mainInflowRatio --format json
    → 主力 = 大单 + 特大单；字段族 {small|medium|large|xlarge}{Inflow|Outflow|NetInflow|InflowRatio}
    单只无翻页：撞 --limit（默认 6000/上限 10000）会标 partial + 退出码 3 → 缩小日期区间
 3. 全市场：--security aShares
    ⚠️ aShares 必须显式传 --start-date/--end-date（缺日期本地报错）
-   单日约 5500 行，CLI 按日自动分片并发合并、无需手动分批（宽区间落盘再采样）：
+   单日数千行，CLI 按日自动分片并发合并、无需手动分批（宽区间落盘再采样）：
    gangtise quote fund-flow --security aShares \
-     --start-date 2026-07-06 --end-date 2026-07-06 --format jsonl --output aShares_flow.jsonl
+     --start-date <最新交易日> --end-date <最新交易日> --format jsonl --output aShares_flow.jsonl
 ```
 
 ## 例 17：机构 ID 搜索（名称 → institutionId，喂给 --broker/--institution）
@@ -323,7 +325,7 @@
    可选 --category 缩类：domesticBroker / foreignInstitution / leadInstitution / opinionInstitution / foreignOpinionInstitution
 3. 研报按券商筛选走 --broker：
    gangtise insight research list --broker C100000001 --rank-type 2 \
-     --start-time "2026-06-06 00:00:00" --end-time "2026-07-06 23:59:59" --format json
+     --start-time "<今天-30天> 00:00:00" --end-time "<今天> 23:59:59" --format json
 4. 只有要「全量枚举」券商/机构表时才用本地 lookup broker-org/meeting-org list（institution-search 是搜索、非全量）
 ```
 
@@ -337,7 +339,7 @@
    "这周" → 本周一至今天
 3. Pre-flight：不加筛选 total 十万量级（含未来排期）→ 必须带日期范围；0.1 积分/条，先 --size 探量
 4. gangtise insight performance-calendar list \
-     --start-date 2026-07-20 --end-date 2026-07-25 \
+     --start-date <本周一> --end-date <今天> \
      --market aShares --category performanceForecast \
      --size 50 --format json
    → list[].securityName / title / publishDate / performanceReportId / hasAttachment

package/gangtise-openapi/references/fields.md

@@ -1,10 +1,10 @@
 # CLI 可选字段速查
 
-> 按命令分组，`--field` 参数可重复传入。不传 `--field` 时返回全部字段。`quote` 系传了 `--field` 就只回点名的列、不自动附带身份列（`fund-flow` 除外，它自动带 `securityCode` / `tradeDate`）：日 K 要一起写进 `securityCode` / `tradeDate`，分钟 K 是 `securityCode` / `tradeTime`，实时行情是 `securityCode`。
+> 按命令分组，`--field` 参数可重复传入。不传 `--field` 时返回全部字段。`quote` 系多只证券或全市场时传了 `--field` 而缺身份列，CLI 会把它补到最前并在 stderr 说明：日 K 补 `securityCode` / `tradeDate`、分钟 K 补 `securityCode` / `tradeTime`、实时行情补 `securityCode`；单只证券不补（`fund-flow` 本就自带 `securityCode` / `tradeDate`）。
 
 ## 🔴 字段名写错时，两族接口的表现完全不同
 
-`--field` 里写了一个不存在的字段名（拼错、或该字段已下线），**没有任何接口会报错**，但丢的东西不一样——这决定了你能不能按位置拍平结果：
+`--field` 里写了一个不存在的字段名（拼错、或该字段已下线），**行情与 fundamental 这两族接口都不会报错**（`bond` 的 `--field` 写错会整批报 `100003`），但丢的东西不一样——这决定了你能不能按位置拍平结果：
 
 | 接口 | 响应里发生什么 | CLI 怎么处理 |
 | :-- | :-- | :-- |
@@ -34,15 +34,15 @@
 >
 > 1. **指数不适用**。指数的 OHLC 是**点位**，而 `amount` / `volume` 是成分股合计，两者量纲不同——比值算出来是成分股均价（上证 / 深成 ≈ 20 元），永远落不进四千点的区间，**数据本身是对的**。
 > 2. 🔴 **美股的 `quote realtime`**。它的 `amount` 是 **`null`**（接口不提供该字段，见下方 realtime 字段表），自检算不出来。**要美股的实时成交额，只能用别的口径**（收盘后用 `day-kline`，或 EDE `qte_amt`）。
-> 3. **全球指数**（`SPX.SPI` 等 20 个）：realtime 与分钟 K 的 `volume` / `amount` 都是 `null`，日 K 只有 `amount` 是 `null`。
+> 3. **全球指数**（如 `SPX.SPI`，清单见 `references/commands/quote.md`）：realtime 与分钟 K 的 `volume` / `amount` 都是 `null`，日 K 只有 `amount` 是 `null`。
 >
-> 🔴 **分钟线加总不等于日线，别把它当校验条件**。正常交易日 241 根，多数证券多数日子里 Σ分钟 `volume` 与日线逐位相等、`amount` 只差末位舍入；但**个别历史交易日的分钟数据口径与日线不一致**，那几天怎么加都对不上，两条序列各自稳定、都不报错，历史数据也不会回改。
+> 🔴 **分钟线加总不等于日线，别把它当校验条件**。正常交易日 241 根，多数证券多数日子里 Σ分钟 `volume` 与日线逐位相等、`amount` 只差末位舍入；但**个别历史交易日的分钟数据口径与日线不一致**，那几天怎么加都对不上，两条序列各自稳定、都不报错。
 >
 > **口径**：成交量 / 成交额的统计一律**以日线为准**，分钟线用于日内分布。撞到对不上时，那是那一天的数据，不是你的加总代码有问题——**更不要用分钟加总去反推或"修正"日线**。
 >
 > （`14:58` / `14:59` 恒为 0 是**正常的**：14:57 后进入收盘集合竞价，只申报不撮合，成交在 `15:00` 那一根一次性发生——**收盘那根在序列里**，241 根的末根就是它。）
 
-### 日K线 `quote day-kline`（A股 / 港股 / 美股 / ETF / 各类指数含全球指数；旧的 `day-kline-hk` / `day-kline-us` 已下线，字段相同）
+### 日K线 `quote day-kline`（A股 / 港股 / 美股 / ETF / 各类指数含全球指数；旧的 `day-kline-hk` / `day-kline-us` 已弃用，字段相同）
 
 各市场字段相同（货币单位随市场：A股=元、港股=港元、美股=美元、ETF=元且 `volume` 为「份」；**指数为点位、无货币单位，且 `adjustFactor` 恒为 `null`**——ETF 有 `adjustFactor`；**全球指数 `amount` 恒为 `null`**，`volume` 正常）：
 
@@ -72,7 +72,9 @@
 
 **以上 15 个就是全部**：**无 `close`**（用 `latestPrice`）、**无市值**（走 `indicator cross-section --indicator qte_mkt_cptl`）、**无 `turnoverRate` / `volumeRatio`**（传了会连字段名一起被静默丢掉，不报错、结果里就是没这两列；换手率走 EDE `qte_turn`，A 股）。realtime 对不存在的字段名是名和值一起丢：CLI 比对请求与返回的列名，**缺列标 `partial` + `missingFields`、退出码 3**（字段名写错或已下线）。
 
-### 指数日K线（沪深京 `quote index-day-kline`）
+### 指数日K线（沪深京 `quote index-day-kline`，已弃用）
+
+新代码用 `quote day-kline` 传指数代码即可，字段与上方日 K 相同；本节只为已有脚本保留。分钟 K 与资金流向的字段见 `references/commands/quote.md`。
 
 | 字段 | 含义 | 字段 | 含义 |
 |------|------|------|------|