gangtise-openapi-cli 0.26.0 → 0.27.0

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

@@ -0,0 +1,229 @@
+# Reference / Lookup 命令详细参数
+
+## 证券代码搜索 `reference securities-search`
+
+```bash
+gangtise reference securities-search --keyword <text> [--category <type>] [--top <n>]
+```
+
+- 用途：把公司名/简称/代码/拼音/英文名/曾用名 → `gtsCode`，是 `ai security-clue --gts-code` 等接口的前置查询
+- `--keyword`（**必选**）：支持多维度匹配（中文名/简称/证券代码/拼音首字母/英文名/曾用名）
+- `--category`（可重复）：`stock` | `dr` 存托凭证 | `index` | `fund`（不传则查所有）
+- `--top`：默认 10，**上限 10**
+- 返回字段：`gtsCode` / `gtsName` / `category` / `matchScore` / `matchType`
+  - `matchType`：`code` 代码 | `abbr` 简称 | `pinyin` 拼音 | `prev` 曾用名 | `engName` 英文名
+
+**示例：**
+```bash
+gangtise reference securities-search --keyword 茅台 --category stock --top 3
+gangtise reference securities-search --keyword 600519
+gangtise reference securities-search --keyword gzmt
+```
+
+## 首席 ID 搜索 `reference chiefs-search`
+
+```bash
+gangtise reference chiefs-search --keyword <text> [--top <n>]
+```
+
+- 用途：查首席分析师 ID，拿到的 `chiefId` 用于 `insight opinion list --chief <id>` 按首席筛选内资观点
+- `--keyword`（**必选**）：支持中文姓名 / 机构名称 / 所属团队多维匹配
+- `--top`：默认 10，**上限 10**
+- 免费调用
+- 返回字段：`chiefId` / `chiefName` / `institution`（所属证券机构）/ `team`（所属团队）/ `matchScore`（`0~1`）
+
+**示例：**
+```bash
+gangtise reference chiefs-search --keyword 东吴证券 --top 3 --format json   # → 周良玖 / 芦哲 / 陈李，chiefId 如 P100005161
+```
+
+## 机构 ID 搜索 `reference institution-search`
+
+```bash
+gangtise reference institution-search --keyword <text> [--category <name>] [--top <n>]
+```
+
+- 用途：查机构 ID，拿到的 `institutionId` 用于各接口的 `--institution`（牵头机构）/ `--broker`（券商 / 观点机构）入参。**每条结果自带 `usageScopes[{apiName, paramName}]`，服务端直接标明该 ID 用于哪个接口的哪个参数**——拿不准某 ID 该喂给谁时以此为准
+- `--keyword`（**必选**）：机构名称 / 简称（如 `招商证券`、`华泰`、`摩根`）
+- `--category`：机构分类，缩小范围（可重复；不传查所有分类）。5 个分类与既有命令参数的对应（均实测有效）：
+
+  | category | CLI 命令 · 参数 | 用途 |
+  |----------|----------------|------|
+  | `domesticBroker` | `insight research list --broker` | 内资研报 |
+  | `foreignInstitution` | `insight foreign-report list --broker` | 外资研报 |
+  | `opinionInstitution` | `insight opinion list --broker` | 内资机构观点 |
+  | `foreignOpinionInstitution` | `insight foreign-opinion list --broker` | 外资机构观点 |
+  | `leadInstitution` | `--institution`（`summary` / `roadshow` / `site-visit` / `strategy` / `vault my-conference` list） | 纪要 / 路演 / 调研 / 线下策略会 / 我的会议的牵头机构 |
+
+  注：API 文档 `categoryList` 只列了前 4 类，但 `foreignOpinionInstitution` 同样是有效过滤值（实测确认，服务端接受且返回该类）
+- `--top`：默认 10，**上限 10**；结果按 `matchScore`（`0~1`）降序
+- 免费调用
+- 返回字段：`institutionId` / `institutionName` / `category` / `usageScopes[{apiName, paramName}]`（该机构适用的接口及参数）/ `matchScore`
+
+**示例：**
+```bash
+gangtise reference institution-search --keyword 招商证券 --category domesticBroker --top 3 --format json   # → C100000020 招商证券
+```
+
+## 公众号 ID 搜索 `reference official-account-search`
+
+```bash
+gangtise reference official-account-search --keyword <text> [--category <name>] [--top <n>]
+```
+
+- 用途：查公众号 ID，拿到的 `accountId` 喂给 `insight official-account list --account-id` 拉该公众号资讯
+- `--keyword`（**必选**）：公众号名称 / 所属机构 / 关键字（如 `中信证券`、`人民日报`）
+- `--category`：分类过滤，可多选——`listedCompany` 上市公司 | `broker` 券商团队 | `government` 政府官方 | `media` 媒体。⚠️ 部分公众号不属这四类（`category` 返回 `null`）；一旦传 `--category` 就会漏掉这些未分类公众号，要全量（含未分类）就**别传** `--category`
+- `--top`：默认 10，**上限 10**；结果按 `matchScore`（`0~1`）降序
+- 免费调用
+- 返回 `{returnedCount, list}`；list 字段：`accountId` / `accountName` / `category`（四类之一或 `null`）/ `matchScore`
+
+**示例：**
+```bash
+gangtise reference official-account-search --keyword 中信证券 --top 3 --format json   # → gh_fe1d2be7e8db 中信证券研究
+```
+
+## 常量分类 `reference constant-category`
+
+```bash
+gangtise reference constant-category [--format json]
+```
+
+- 用途：全量导出常量分类及每个分类适用于哪些接口的哪些参数（无需传参，免积分）
+- 返回 `{total, list}`，`list[]` 字段：`category`（分类代码）/ `categoryName` / `structureType`（`flat` 平铺 | `tree` 树形）/ `maxLevel` / `usageScopes[]`（`apiName` + `paramName`）
+- 当前 8 个分类：
+
+| category | 名称 | 结构 | 用于参数 |
+|----------|------|------|---------|
+| `citicIndustry` | 中信一级行业（30，`1008001xx`） | flat | `--industry` 全命令通用首选（见下方说明） |
+| `swIndustry` | 申万一级行业（31，`104xxx`） | flat | `--industry`（仅 6 个 insight list；wechat 静默忽略，见下方说明） |
+| `gangtiseIndustry` | Gangtise 行业（30 行业 `1008001xx` + 6 方向 `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` |
+| `usShareAnnouncementCategory` | 美股公告分类（`103980xxx` 段） | tree（2 级） | `insight announcement-us --category` |
+| `regionCategory` | 区域分类 | flat | `insight foreign-report --region` |
+
+> **行业 / 研究方向过滤——选哪套 category（⭐ 权威口径，其他文件引用此处、勿重复枚举命令清单以免漂移；实测 + spec，2026-06-15）：**
+> - **`--industry`（industryList）→ 用 `citicIndustry`（`1008001xx`）**：opinion / research / foreign-report / foreign-opinion / independent-opinion / official-account / wechat-message 全部正确过滤。`swIndustry`（`104xxx`）在 6 个 insight list（含 official-account）上等效（spec 多数命令写 citic+sw），但 **`vault wechat-message-list` 只认中信码、传申万码会静默返回全量** → 统一用中信码最稳。
+> - **`--research-area`（researchAreaList）→ 用 `gangtiseIndustry`**：完整研究方向分类 = 30 个行业（`1008001xx`，与 citicIndustry 相同）+ 6 个方向（宏观 `122000001` / 策略 `122000002` / 固收 `122000003` / 金工 `122000004` / 海外 `122000005` / 其他 `122000007`）。行业码与方向码均已实测正确过滤（opinion / summary / roadshow / site-visit / forum）。`citicIndustry` 也能用但只含行业、无方向；`swIndustry`（`104xxx`）除 summary / my-conference 外返 0，勿用。
+
+## 常量值 `reference constant-list`
+
+```bash
+gangtise reference constant-list --category <code> [--format json]
+```
+
+- `--category`（**必选**）：分类代码，见上表
+- 返回 `{category, structureType, maxLevel, constantCount, list}`（CLI 把 API 的 `constants` 规范化为 `list`）
+- `list[]` 字段：`constantId` / `constantName` / `level`；树形分类的父节点含 `children[]`（结构同父节点，可继续嵌套）
+- 树形分类（公告分类）用 `--format json` 自行递归 `children`；`table` 不会展开子节点
+
+**示例：**
+```bash
+gangtise reference constant-list --category citicIndustry --format json
+gangtise reference constant-list --category aShareAnnouncementCategory --format json   # 树形，含 children
+```
+
+## 题材 ID 搜索 `reference concept-search`
+
+```bash
+gangtise reference concept-search --keyword <text> [--top <n>]
+```
+
+- 用途：查题材 ID，供 `alternative concept-info / concept-securities --concept-id` 和 `ai theme-tracking --theme-id` 使用（三者共用同一套 ID）
+- `--keyword`（**必选**）：中文题材名/简称、拼音/首字母（`jqr`）、分组名（如 灵巧手）
+- `--top`：默认 10，**上限 10**；搜索型接口，**非全量导出**
+- 返回 `{returnedCount, list}`，`list[]`：`conceptId` / `conceptName` / `matchScore`（0~1，降序）
+
+**示例：**
+```bash
+gangtise reference concept-search --keyword 机器人 --top 3 --format json   # → 121000130
+gangtise reference concept-search --keyword jqr
+```
+
+## 板块 ID 搜索 `reference sector-search`
+
+```bash
+gangtise reference sector-search [--keyword <text>] [--top <n>]
+```
+
+- 用途：查板块 ID（行业/概念/指数成份等分类树节点），供 `sector-constituents` 使用
+- `--keyword`：中文板块名/简称、拼音/首字母
+- `--top`：默认 10，**上限 10**
+- 返回 `{returnedCount, list}`，`list[]`：`sectorId` / `sectorName` / `hierarchy`（层级路径，如 `中国内地股票-概念类-科技-半导体设备`）/ `matchScore`
+- 同名板块可能出现在多个层级（概念类 vs 指数成份类），用 `hierarchy` 区分
+
+## 板块成分股 `reference sector-constituents`
+
+```bash
+gangtise reference sector-constituents --sector-id <id>
+```
+
+- `--sector-id`（**必选**）：板块 ID，**必须来自 `reference sector-search`**
+- 返回 `{total, list}`，`list[]`：`gtsCode` / `gtsName`（全量成分股，纯名单）
+- **返回 0 条** → sectorId 不对：题材 `conceptId` 与板块 `sectorId` 是两套 ID，不通用；先 `sector-search` 确认
+- 与 `alternative concept-securities` 的区别：后者是题材深度 F8（按分组、含 `isKey` / `inclusionReason`），本接口是板块树节点的纯成分股名单
+
+**示例：**
+```bash
+gangtise reference sector-search --keyword 半导体 --top 3 --format json   # → 1000001005 半导体设备
+gangtise reference sector-constituents --sector-id 1000001005 --format json
+```
+
+**申万行业代码全量列表**（`ai security-clue --gts-code` 用的 `821xxx.SWI`）也走这两步——申万行业指数板块的成分就是 31 只行业指数本身：
+
+```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
+```
+
+单个行业也可以直接 `reference securities-search --keyword 申万银行 --category index` → `821047.SWI`。
+
+## Lookup 本地表（仅剩 2 个）
+
+**按名称找机构 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 条静态表）
+```
+
+行业 / 区域 / 公告分类 / 研究方向 / 题材 ID / 申万行业代码已改用 API：`reference constant-list` / `reference concept-search` / `reference sector-constituents`（v0.16.0 起移除对应 lookup 子命令）。
+
+### 常见行业别名映射
+
+| 用户说法 | 标准（申万）行业 | 申万码¹ | `--gts-code`（security-clue） |
+|----------|---------|----------------|---------------------------|
+| 新能源 / 光伏 / 风电 / 电新 | 电力设备 | `104630000` | `821052.SWI` |
+| AI / 人工智能 / 算力 | 计算机 | `104710000` | `821055.SWI` |
+| 半导体 / 芯片 | 电子 | `104270000` | `821035.SWI` |
+| 互联网 / 平台 | 传媒 | `104720000` | `821056.SWI` |
+| 白酒 | 食品饮料 | `104340000` | `821038.SWI` |
+| 医药 / 创新药 | 医药生物 | `104370000` | `821041.SWI` |
+| 地产 | 房地产 | `104430000` | `821044.SWI` |
+| 券商 / 券商股 | 非银金融 | `104490000` | `821048.SWI` |
+| 银行 / 银行股 | 银行 | `104480000` | `821047.SWI` |
+| 汽车 / 新车 | 汽车 | `104280000` | `821036.SWI` |
+
+> ¹ 第 3 列是**申万码**（`104xxx`），仅在 opinion / research / foreign-report / foreign-opinion / independent-opinion / official-account 这 6 个 insight list 上作 `--industry` 等效；`vault wechat-message-list` 会静默返回全量、`--research-area` 返 0——通用/推荐的**中信码**（`1008001xx`）见 `references/lookup-ids.md` 中信表或 `constant-list --category citicIndustry`。
+
+> **参数名选择**：`--industry`（industryList，用 `citicIndustry` 码 `1008001xx`）用于 opinion / research / foreign-report / foreign-opinion / independent-opinion / official-account / wechat-message；`--research-area`（researchAreaList，用 `gangtiseIndustry` 码 = 行业 `1008001xx` + 方向 `122000xxx`）用于 opinion / summary / roadshow / site-visit / forum / my-conference；`--gts-code` 仅用于 `ai security-clue`（需申万格式 `821xxx.SWI`，不是数字 ID）。注意 strategy（线下策略会）无 `--research-area`，只按 `--institution` / `--location` 筛。
+
+> **"消费"歧义**：用户说"消费/大消费"覆盖多个子行业（食品饮料 `104340000` / 商贸零售 `104450000` / 社会服务 `104460000` / 家电 `104330000` / 纺织服饰 `104350000` / 美容护理 `104770000`），需向用户确认具体方向，或用 `--keyword 消费` 做宽泛搜索。
+
+## Raw 调用 `gangtise raw call`
+
+```bash
+gangtise raw call <endpoint.key> --body '{"from":0,"size":120}'                                       # JSON 端点（POST，绝大多数）
+gangtise raw call insight.research.download --query reportId=<id> --query fileType=1 --output x.pdf   # 仅 kind=download 端点用 --query
+```
+
+- 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 复用与封装命令一致

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

@@ -0,0 +1,79 @@
+# Vault 命令详细参数（私域数据）
+
+通用：`--keyword` `--start-time` `--end-time` `--from` `--size`（list 类）。
+
+---
+
+## AI 云盘 `vault drive-list/download`
+
+```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>]
+```
+
+- `--file-type`：`1` 文档（含 PDF/Word/PPT）| `2` 图片 | `3` 音视频 | `4` 公众号文章 | `5` 其他
+- `--space-type`：`1` 我的云盘 | `2` 租户云盘
+
+## 录音速记 `vault record-list/download`
+
+```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>]
+```
+
+- `--category`：`upload` | `link` | `mobile` | `gtNote` | `pc` | `share`（可重复）
+- `--space-type`：`1` 我的速记 | `2` 租户速记
+- `--content-type`（download **必选**）：`original` 原始文件 | `asr` 语音识别 | `summary` AI 速记
+  - 口语映射：「原始文件/原文件」→`original`、「语音识别/转写文本/ASR」→`asr`、「AI速记/智能摘要/会议纪要」→`summary`
+  - 「与我分享」类型录音无法下载原始文件
+- 返回字段：`recordId` / `title` / `createTime` / `category` / `recordDuration`（秒） / `recordSize`（Byte）/ `url` / `spaceType` / `uploader`
+
+## 我的会议 `vault my-conference-list/download`
+
+```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>]
+```
+
+- `--category`：`earningsCall` 业绩会 | `strategyMeeting` 策略会 | `fundRoadshow` 基金路演 | `shareholdersMeeting` 股东大会 | `maMeeting` 并购会议 | `specialMeeting` 特别会议 | `companyAnalysis` 公司分析 | `industryAnalysis` 行业分析 | `other`（可重复）
+- `--source`：录制来源 `1`=企微会议助理 | `2`=会议服务微信群（可重复；不传返回全部）
+- `--keyword` vs `--research-area`：用户说"关于AI的"用 `--keyword AI`；说"电子行业的会议"用 `--research-area 100800126`（research-area 用 `gangtiseIndustry` 码 `1008001xx` + 方向 `122000xxx`，**不要用申万码 `104xxx`**）
+- `--content-type`（download **必选**）：`asr` 语音识别 | `summary` AI 速记
+- 返回字段：`conferenceId` / `title` / `publishTime` / `category` / `institution{...}` / `security{...}` / `researchArea{...}` / `guest` / `sourceList`（录制来源，`1`/`2`）
+
+## 群消息 `vault wechat-message-list`
+
+```bash
+gangtise vault wechat-message-list [--keyword <text>] [--security <code>] [--wechat-group-id <id>] [--industry <id>] [--category <type>] [--tag <tag>] [--start-time <datetime>] [--end-time <datetime>] [--from <n>] [--size <n>]
+```
+
+- 数据权限：仅用户已绑定并激活群消息助理、且助理已入群的群消息
+- `--security`：按证券代码过滤（如 `000001.SZ`），可重复
+- `--industry`：行业 ID，**必须用中信码 `citicIndustry`（`1008001xx`）**；实测传申万码 `104xxx` 会被静默忽略、返回全量
+- `--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`）
+
+## 群 ID 查询 `vault wechat-chatroom-list`
+
+```bash
+gangtise vault wechat-chatroom-list [--room-name <name>] [--from <n>] [--size <n>]
+```
+
+- `--room-name`：可重复或英文逗号分隔
+- 省略 `--size` 拉全量（接口返回 `total`，CLI 按 total 并发翻页）；传 `--size N` 只取前 N 条。单页最大 50
+- 返回字段：`total`（总条数）/ `chatroomName` / `chatroomId`
+
+## 自选股股票池 `vault stock-pool-list / stock-pool-stocks`
+
+```bash
+gangtise vault stock-pool-list
+gangtise vault stock-pool-stocks [--pool-id <id>]
+```
+
+- `stock-pool-list`：查询当前用户的全部股票池，返回 `poolId` / `poolName`
+- `stock-pool-stocks`：查询股票池中的证券明细
+  - `--pool-id`：股票池 ID，可重复；不传默认 `all`（返回所有池中的非重复证券）
+  - 传入 `--pool-id all` 等同于全量查询，最多返回 10000 只
+  - 返回字段：`securityCode` / `securityName`

package/gangtise-openapi/references/examples.md

@@ -0,0 +1,291 @@
+# 典型执行示例
+
+每个示例展示从用户语句到完整命令的全流程。Skill 主文件不再内嵌示例；遇到不确定的场景时来这里查同类。
+
+---
+
+## 例 1：研报检索 ＋ 下载（list→download 多步编排）
+
+**用户**："下载中金最近的宏观策略研报"
+
+```
+1. 路由 → insight research list + download
+2. 中金 → C100000026（references/lookup-ids.md 速查）
+   "宏观策略" → 研报分类 --category macro + strategy（research list 无 --research-area）
+   "最近" → 默认 7 天
+3. Pre-flight：
+   - 认证 OK
+   - 结果可能 >200 条 → 🔴 询问"先看前 20 还是导出全量？"
+   - 下载格式 → 🔴 询问 PDF 还是 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" \
+     --rank-type 2 --format json
+   （选"导出全量"分支：改 `--format jsonl --output cicc_macro.jsonl` 落盘，再 `wc -l` / `head` 采样，别把全量塞进上下文）
+5. 提取 reportId + title 展示，让用户选择具体一篇 → 确认 file-type
+6. gangtise insight research download --report-id <id> --file-type 1
+```
+
+## 例 2：观点检索（带模糊时间）
+
+**用户**："查一下最近有哪些首席观点提到 AI"
+
+```
+1. 路由 → insight opinion list
+2. "最近" → Insight 默认 7 天；"AI" → --keyword AI
+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" \
+     --rank-type 2 --format json
+5. 提取 list[].title / chiefName / publishDate，按时间倒序列表
+```
+
+## 例 3：AI 内容生成（content 字段直接呈现）
+
+**用户**："比亚迪的一页通"
+
+```
+1. 路由 → ai one-pager
+2. 比亚迪 → 002594.SZ（速查表）
+   注意：one-pager 用 --security-code，不是 --security
+3. Pre-flight：首次生成常 >30s → 前置 `GANGTISE_TIMEOUT_MS=120000` 防超时重试；告知用户"生成中..."
+4. GANGTISE_TIMEOUT_MS=120000 gangtise ai one-pager --security-code 002594.SZ --format json
+5. 返回 {content: "markdown"} → 直接呈现 content，不要展示 JSON 包装
+```
+
+## 例 4：估值分析（默认时间范围）
+
+**用户**："贵州茅台过去一年的 PE 估值"
+
+```
+1. 路由 → fundamental valuation-analysis
+2. 贵州茅台 → 600519.SH；"PE" → --indicator peTtm
+   "过去一年"对 valuation 来说是命令默认行为，省略 --start-date 自动查近一年
+3. Pre-flight：认证 OK
+4. gangtise fundamental valuation-analysis \
+     --security-code 600519.SH --indicator peTtm --format json
+5. 提取 list[].tradeDate / value / percentileRank，表格 + 分位标注
+```
+
+## 例 5：跨市场 K 线（A 股 + 港股）
+
+**用户**："比亚迪 A 股和港股最近的日 K 线"
+
+```
+1. 路由 → quote day-kline + quote day-kline-hk（跨市场需分别调用）
+2. 比亚迪 A 股 002594.SZ，港股 01211.HK
+   "最近" → K 线默认今日往前 45 天（保证含最近 10 个交易日）
+3. Pre-flight：认证 OK
+4. gangtise quote day-kline --security 002594.SZ --start-date 2026-03-19 --end-date 2026-05-03 --format json
+   gangtise quote day-kline-hk --security 01211.HK --start-date 2026-03-19 --end-date 2026-05-03 --format json
+5. 合并两次结果，按 tradeDate 取尾部最近 10 个交易日
+```
+
+## 例 6：指数最近值（务必拉范围）
+
+**用户**："查上证综指最近的指数"
+
+```
+1. 路由 → quote index-day-kline
+2. 上证综指 → 000001.SH；"最近" → 今日往前 45 天
+3. Pre-flight：认证 OK；今天若周末 end-date 仍填当天，API 返回最近交易日
+4. gangtise quote index-day-kline --security 000001.SH --start-date 2026-03-19 --end-date 2026-05-03 --format json
+5. 按 tradeDate 取尾部最近 10 个交易日。**不要用 --limit 20**（截取的是窗口开头）
+```
+
+## 例 7：云盘文件下载（list→download，需用户选择）
+
+**用户**："帮我下载云盘里那个 AI 相关的 PDF"
+
+```
+1. 路由 → vault drive-list → drive-download
+2. "AI 相关" → --keyword AI；"PDF" → --file-type 1（文档含 PDF）
+3. Pre-flight："那个"暗示特定文件 → 🔴 展示结果让用户选择
+4. gangtise vault drive-list --keyword AI --file-type 1 --format json
+5. 展示前 10 条让用户挑 → gangtise vault drive-download --file-id <id>
+   （省略 --output 自动用真实标题做文件名）
+```
+
+## 例 8：跨资源类型语义搜索
+
+**用户**："搜索一下新能源相关的研报和纪要"
+
+```
+1. 路由 → ai knowledge-batch（多类文档统一搜索时优先走 knowledge-batch）
+2. "新能源" → 行业别名映射 → 电力设备
+   "研报和纪要" → resource-type 10(券商研报) + 60(会议平台纪要) + 70(调研纪要公告)
+3. Pre-flight：意图明确，无歧义
+4. gangtise ai knowledge-batch \
+     --query "新能源" \
+     --resource-type 10 --resource-type 60 --resource-type 70 \
+     --format json
+5. 提取 list[].title / resourceType / summary，编号列表呈现
+```
+
+## 例 9：未知公司名（走 securities-search）
+
+**用户**："查蔚蓝生物的最新研报"
+
+```
+1. 路由 → insight research list；公司名不在速查表
+2. 先调 reference securities-search：
+     gangtise reference securities-search --keyword 蔚蓝生物 --category stock --top 3 --format json
+   返回 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
+```
+
+## 例 10：实时行情（盘中快照，跨市场）
+
+**用户**："茅台、腾讯、苹果现在的最新价"
+
+```
+1. 路由 → quote realtime（A/港/美都走同一个接口）
+2. 茅台 600519.SH（速查表）/ 腾讯 00700.HK（速查表）/ 苹果 AAPL.O
+3. Pre-flight：用户只关心几个核心字段 → 用 --field 精简返回
+4. gangtise quote realtime \
+     --security 600519.SH --security 00700.HK --security AAPL.O \
+     --field securityCode --field tradeTime --field latestPrice --field pctChange --field volume \
+     --format json
+5. 返回最新时刻快照；非交易时间返回最近一个交易日的收盘快照
+   注意：日 K 线（day-kline）不返回盘中数据，问"现在/此刻"必须走 realtime
+```
+
+## 例 11：美股日 K 线（历史）
+
+**用户**："苹果过去一个月的日 K 线"
+
+```
+1. 路由 → quote day-kline-us（仅历史；盘中数据走 realtime）
+2. 苹果 AAPL.O；"过去一个月" → 今日往前 30 天
+3. Pre-flight：认证 OK；当日数据约 07:00（北京时间）入库
+4. gangtise quote day-kline-us --security AAPL.O \
+     --start-date 2026-04-22 --end-date 2026-05-22 \
+     --field tradeDate --field open --field close --field volume --field pctChange --format json
+5. 按 tradeDate 排序展示
+```
+
+## 例 12：异步任务（业绩点评）
+
+**用户**："给贵州茅台写一份 2025Q3 业绩点评"
+
+```
+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：
+     gangtise ai earnings-review-check --data-id xxx --format json
+   - 若 {status: "pending"} → 再等再 check（最多 3 次）
+   - 若 {date, content} → 取 content 呈现
+   - 若 410111 → 终态失败，告知用户重试
+```
+
+## 例 13：题材画像 ＋ 成分股（先查 ID 再拉两接口）
+
+**用户**："机器人这个题材现在的逻辑和龙头股"
+
+```
+1. 路由 → alternative concept-info（投资逻辑/行业空间/竞争格局）
+          + alternative concept-securities（成分股，按分组）
+2. "机器人" → concept-id：题材与主题共用 ID 体系，用 concept-search 查
+     gangtise reference concept-search --keyword 机器人 --top 5 --format json
+       → list[0].conceptId = 121000130
+   注意：concept-id 不在速查表，**绝不猜测**，必须查 concept-search
+3. Pre-flight：认证 OK；两接口都仅返回最新截面，无历史回溯
+4. gangtise alternative concept-info --concept-id 121000130 --format json
+     → 单对象 {conceptName, definition, investmentLogic, industrySpace,
+              competitiveLandscape, keyEvents:[{date,content}]}
+   gangtise alternative concept-securities --concept-id 121000130 --format json
+     → 单对象 {securityCount, securityDetail:[{groupName, securityList:[...]}]}
+5. 呈现：concept-info 各文本字段直接展示（含 null 则跳过）；
+   成分股按 groupName 分组列出，isKey=true 标记为「重点」
+```
+
+## 例 14：板块成分股（sector-search → sector-constituents 两步）
+
+**用户**："半导体设备板块现在有哪些股票"
+
+```
+1. 路由 → reference sector-search + sector-constituents
+   （用户要的是板块名单，不是题材深度 F8 → 不走 alternative concept-securities）
+2. gangtise reference sector-search --keyword 半导体设备 --top 5 --format json
+     → 同名板块可能出现在多个层级，用 hierarchy 区分：
+       中国内地股票-概念类-科技-半导体设备 → sectorId 1000001005
+3. gangtise reference sector-constituents --sector-id 1000001005 --format json
+     → {total: 59, list: [{gtsCode, gtsName}, ...]}
+4. 陷阱：sectorId 必须来自 sector-search；拿题材 conceptId（如 121000130）来查会返回 0 条
+5. 呈现：total + 前 20 只列表
+```
+
+## 例 15：指标取数（search → cross-section / time-series）
+
+**用户**："茅台和泡泡玛特上周的收盘价、成交量对比一下"
+
+```
+1. 路由 → indicator（证券级指标，需证券代码 → EDE，不是 alternative edb）
+2. 先拿 indicatorCode（绝不猜）：
+     gangtise indicator search --keyword 收盘价 --format table   → qte_close
+     gangtise indicator search --keyword 成交量 --format table   → qte_vol
+3. 取数二选一：
+   - 单日横向对比 → cross-section（多指标 × 多证券）：
+       gangtise indicator cross-section \
+         --indicator qte_close --indicator qte_vol \
+         --security 600519.SH --security 09992.HK \
+         --date 2026-05-22 --format table
+       → 每行一只证券，列 = date/security/name/日收盘价/成交量
+   - 一段区间走势 → time-series（这里两只证券 → 只能单指标 × 多证券）：
+       gangtise indicator time-series --indicator qte_close \
+         --security 600519.SH --security 09992.HK \
+         --start-date 2026-05-18 --end-date 2026-05-22 --format table
+       → 每行一个日期，列 = date/贵州茅台/泡泡玛特
+4. 复权：要前复权收盘价加 --indicator-param "qte_close:adjustmentType=2"
+   （参数 key 以 indicator search --format json 的 parameterList 为准）
+5. 陷阱：time-series 不能多指标 × 多证券同时（报 410001），那种情况用 cross-section
+6. 必填参数：很多指标默认调用会缺参报错（服务端指明缺哪个，如「必填参数 periodNum 不能为空」）→ 先看 parameterList 的 required，补
+   periodNum（N期统计）/startDate（区间周期类，如 qte_amp_mo）/fiscalYear（年度分红）：
+     gangtise indicator cross-section --indicator finc_roe_avg_avg --security 600519.SH \
+       --date 2026-03-31 --indicator-param "finc_roe_avg_avg:periodNum=4"
+7. 无数据：截面/时序对无此科目的**格**返回 null（不丢行）；**整个查询无数据**（节假日/未来日期/未覆盖标的）
+   仍报 999999+HTTP 500，CLI 不重试并提示检查条件 → 财务用报告期末、现金流附注用年报
+   日期(2025-12-31)、行情用交易日；银行/券商/保险科目不同，换对公司类型。详见 commands/indicator.md
+```
+
+## 例 16：A 股资金流向（个股 vs 全市场按日分片）
+
+**用户**："看下宁德时代最近一个月的主力资金净流入" / "拉今天全 A 股的资金流向"
+
+```
+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 \
+     --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（缺日期本地报错；否则单请求被服务端 430012 拒）
+   单日约 5500 行，CLI 按日自动分片并发合并、无需手动分批（宽区间落盘再采样）：
+   gangtise quote fund-flow --security aShares \
+     --start-date 2026-07-06 --end-date 2026-07-06 --format jsonl --output aShares_flow.jsonl
+```
+
+## 例 17：机构 ID 搜索（名称 → institutionId，喂给 --broker/--institution）
+
+**用户**："查渤海证券最近的研报"
+
+```
+1. 机构名不在速查表、要按机构筛选 → 先 reference institution-search 拿 ID（免费，搜索型 top≤10，绝不猜 ID）
+2. gangtise reference institution-search --keyword 渤海证券 --format json
+   → list[0] = {institutionId: "C100000001", institutionName, usageScopes:[...]}
+   usageScopes 直接标明这个 ID 用于哪个命令的哪个参数（省去猜 --broker 还是 --institution）
+   可选 --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
+4. 只有要「全量枚举」券商/机构表时才用本地 lookup broker-org/meeting-org list（institution-search 是搜索、非全量）
+```