gangtise-openapi-cli 0.25.0 → 0.27.0

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

@@ -0,0 +1,187 @@
+# Insight 命令详细参数
+
+所有 `insight ... list` 共享：`--keyword <text>` `--start-time <datetime>` `--end-time <datetime>` `--from <n>` `--size <n>`
+
+时间格式：`"YYYY-MM-DD HH:mm:ss"`（datetime，需引号）。
+
+支持 `--rank-type` 的命令：opinion / summary / research / foreign-report / announcement / announcement-hk / announcement-us / foreign-opinion / independent-opinion / official-account。
+**不支持** `--rank-type` 的命令：roadshow / site-visit / strategy / forum（API 无此参数）。
+
+`--rank-type`：`1` 综合排序（默认）| `2` 时间倒序
+
+---
+
+## 内资机构观点 `insight opinion list`
+
+```bash
+gangtise insight opinion list [--keyword <text>] [--research-area <id>] [--chief <id>] [--security <code>] [--broker <id>] [--industry <id>] [--concept <id>] [--llm-tag <tag>] [--source <src>] [--rank-type <n>]
+```
+
+- `--llm-tag`：`strongRcmd` 强烈推荐 | `earningsReview` 业绩点评 | `topBroker` 头部券商 | `newFortune` 新财富团队
+- `--source`：`realTime` 实时 | `openSource` 开放来源
+- `--industry`：用 `citicIndustry` 码 `1008001xx`（申万码 `104xxx` 也等效）；`--research-area`：用 `gangtiseIndustry` 码（行业 `1008001xx` + 方向 `122000xxx`，申万码返 0）。详见 `reference-and-lookup.md`
+
+## 纪要 `insight summary list/download`
+
+```bash
+gangtise insight summary list [--search-type <n>] [--rank-type <n>] [--source <n>] [--research-area <id>] [--security <code>] [--institution <id>] [--category <name>] [--market <name>] [--participant-role <name>]
+gangtise insight summary download --summary-id <id> [--file-type <n>] [--output <path>]
+```
+
+- `--search-type`：`1` 标题搜索（默认，速度快）| `2` 全文搜索
+- `--source`：`1` 实时 | `2` 开放来源
+- `--research-area`：用 `gangtiseIndustry` 码（行业 `1008001xx` + 方向 `122000xxx`）；summary 的 spec 额外接受 citic/sw，但统一用 gangtise 最稳
+- `--market`：`aShares` | `hkStocks` | `usChinaConcept` | `usStocks`
+- `--participant-role`：`management` 管理层 | `expert` 专家
+- `--category`：`earningsCall` 业绩会 | `strategyMeeting` 策略会 | `fundRoadshow` 基金路演 | `shareholdersMeeting` 股东大会 | `maMeeting` 并购会议 | `specialMeeting` 特别会议 | `companyAnalysis` 公司分析 | `industryAnalysis` 行业分析 | `other`
+- `--file-type`（download 可选）：`1` 原始内容（默认）| `2` HTML 格式；**仅影响来源为会议平台的纪要**
+
+## 路演 / 调研 / 策略会 / 论坛
+
+```bash
+gangtise insight roadshow list   [--security <code>] [--institution <id>] [--research-area <id>] [--category <name>] [--market <name>] [--participant-role <name>] [--broker-type <name>] [--permission <n>] [--location <id>]
+gangtise insight site-visit list [--security <code>] [--institution <id>] [--research-area <id>] [--object <name>] [--category <name>] [--market <name>] [--permission <n>] [--location <id>]
+gangtise insight strategy list   [--institution <id>] [--location <id>]
+gangtise insight forum list      [--research-area <id>] [--location <id>]
+```
+
+- 共用：`--keyword` `--start-time` `--end-time` `--from` `--size` `--location`
+- `--location`：城市/省份 ID（`reference constant-list --category domesticCity` 查，如 `156440000` 广东省）。实测（2026-06-15）服务端过滤已生效，按省份正确命中
+- 路演 `--category`：`earningsCall` | `strategyMeeting` | `companyAnalysis` | `industryAnalysis` | `fundRoadshow`
+- 调研 `--category`：`single` 单场 | `series` 系列
+- 调研 `--object`（仅调研）：`company` | `industry`
+- `--broker-type`（仅路演）：`cnBroker` 内资 | `otherBroker` 外资
+- `--participant-role`（仅路演）：`management` | `expert`
+- `--permission`（路演/调研）：`1` 公开 | `2` 私密
+- `--market`：路演 `aShares`｜`hkStocks`｜`usChinaConcept`｜`usStocks`；调研 `aShares`｜`hkStocks`｜`usChinaConcept`（无 usStocks）
+- `--research-area`（路演/调研/论坛）：用 `gangtiseIndustry` 码（行业 `1008001xx` + 方向 `122000xxx`，见 `reference-and-lookup.md`）。**strategy 无 `--research-area`，只按 `--institution`/`--location` 筛**
+
+## 研报 `insight research list/download`
+
+```bash
+gangtise insight research list [--search-type <n>] [--rank-type <n>] [--broker <id>] [--security <code>] [--industry <id>] [--category <name>] [--llm-tag <tag>] [--rating <name>] [--rating-change <name>] [--min-pages <n>] [--max-pages <n>] [--source <type>]
+gangtise insight research download --report-id <id> [--file-type <n>] [--output <path>]
+```
+
+- `--category`：`macro` | `strategy` | `industry` | `company` | `bond` | `quant` | `morningNotes` | `fund` | `forex` | `futures` | `options` | `warrants` | `market` | `wealthManagement` | `other`
+- `--llm-tag`：`inDepth` 深度 | `earningsReview` 业绩点评 | `industryStrategy` 行业策略
+- `--industry`：仅 `industry`/`company` 类别研报时生效
+- `--rating`：`buy` | `overweight` | `neutral` | `underweight` | `sell`
+- `--rating-change`：`upgrade` | `maintain` | `downgrade` | `initiate`
+- `--source`：`1` PDF研报 | `2` 公众号
+- `--file-type`（download）：`1` 原始PDF（默认）| `2` Markdown
+
+## 外资研报 `insight foreign-report list/download`
+
+```bash
+gangtise insight foreign-report list [--search-type <n>] [--rank-type <n>] [--security <code>] [--region <id>] [--category <name>] [--industry <id>] [--broker <id>] [--llm-tag <tag>] [--rating <name>] [--rating-change <name>] [--min-pages <n>] [--max-pages <n>]
+gangtise insight foreign-report download --report-id <id> [--file-type <n>] [--output <path>]
+```
+
+- `--region`：`cn` 中国 | `cnHk` 香港 | `us` 美国 | `jp` 日本 | `sea` 东南亚 | `gl` 全球 | `uk` 英国 | `kr` 韩国 | `in` 印度（完整列表见 `references/lookup-ids.md`）
+- `--category` / `--llm-tag` / `--rating` / `--rating-change`：同研报
+- `--file-type`（download）：`1` 原始PDF | `2` Markdown | `3` 中文翻译PDF | `4` 中文翻译Markdown
+
+## A 股公告 `insight announcement list/download`
+
+```bash
+gangtise insight announcement list [--search-type <n>] [--rank-type <n>] [--security <code>] [--category <id>]
+gangtise insight announcement download --announcement-id <id> [--file-type <n>] [--output <path>]
+```
+
+- `--category`：公告分类 ID，用 `reference constant-list --category aShareAnnouncementCategory` 查。常用：`103910200` 财务报告、`103910700` 股权股本、`103910201` 业绩预告、`103910703` 质押冻结、`103910803` 股权激励、`103910818` 股份增减持、`103910823` 问询函（完整列表见 `references/lookup-ids.md`）
+- `--file-type`（download）：`1` 原始PDF | `2` Markdown
+- 时间过滤时区：本命令（A 股公告，独有）会把 `--start-time`/`--end-time` 按**运行机器的时区**换算成毫秒时间戳（其余 insight 列表是把字符串直传服务端）。CST 机器上即北京时；在 UTC 云环境（cloud agent / CI）跑则日窗整体偏 8 小时。需跨机器精确边界时，直接传 13 位毫秒时间戳（原样透传，与机器时区无关）。
+
+## 港股公告 `insight announcement-hk list/download`
+
+```bash
+gangtise insight announcement-hk list [--search-type <n>] [--rank-type <n>] [--security <code>] [--category <id>]
+gangtise insight announcement-hk download --announcement-id <id> [--file-type <n>] [--output <path>]
+```
+
+- `--security`：港股代码，如 `01913.HK`（两位数字前缀需补零）
+- `--category`：港股公告类型 ID（见 `references/lookup-ids.md`）
+- `--file-type`（download）：`1` 原始（默认）| `2` Markdown
+
+## 美股公告 `insight announcement-us list/download`
+
+```bash
+gangtise insight announcement-us list [--search-type <n>] [--rank-type <n>] [--security <code>] [--category <id>]
+gangtise insight announcement-us download --announcement-id <id> [--file-type <n>] [--output <path>]
+```
+
+- `--security`：美股代码，如 `TSLA.O`（可重复）
+- `--category`：美股公告分类 ID，用 `reference constant-list --category usShareAnnouncementCategory` 查（美股独立的 `103980xxx` 段，7 个一级分类：财务报告 / 证券发行 / 重大事项 / 交易提示 / 股本股东 / 股东大会 / 一般公告）
+- `--file-type`（download）：`1` 原始PDF（默认）| `2` Markdown
+- **积分**：list 0.1/条；download 20/篇
+- 实测 `--security TSLA.O` 返回的 `sourceName` 为「美国证券交易委员会」
+
+## 外资机构观点 `insight foreign-opinion list`
+
+```bash
+gangtise insight foreign-opinion list [--rank-type <n>] [--security <code>] [--region <code>] [--industry <id>] [--broker <id>] [--rating <name>] [--rating-change <name>]
+```
+
+- `--security`：境外证券代码，如 `UBER.N`
+- `--region`：`cn` | `cnHk` | `cnTw` | `us` | `jp` | `uk`
+- `--broker`：外资券商 ID（见 `references/lookup-ids.md`）
+- `--rating` / `--rating-change`：同研报
+- 返回字段：`foreignOpinionId` / `title` / `titleTranslate` / `content` / `contentTranslate` / `publishTime` / `publisher{brokerId, brokerName}` / `securityList[]{securityCode, rating, targetPrice, currency}` / `region`
+
+## 外资独立观点 `insight independent-opinion list/download`
+
+```bash
+gangtise insight independent-opinion list [--rank-type <n>] [--security <code>] [--industry <id>] [--rating <name>] [--rating-change <name>]
+gangtise insight independent-opinion download --independent-opinion-id <id> --file-type <n> [--output <path>]
+```
+
+- `--security`：境外证券代码，如 `GSK.N`
+- `--rating` / `--rating-change`：同外资观点
+- `--file-type`（download **必选**）：`1` 原文 HTML | `2` 中文翻译 HTML
+- 返回字段：`independentOpinionId` / `title` / `titleTranslate` / `brief` / `briefTranslate` / `publishTime` / `analyst{analystId, analystName}` / `securityList[]` / `industryList[]`
+
+## 产业公众号资讯 `insight official-account list/download`
+
+```bash
+gangtise insight official-account list [--search-type <n>] [--rank-type <n>] [--account-id <id>] [--security <code>] [--category <type>] [--industry <id>]
+gangtise insight official-account download --article-id <id> [--file-type <n>] [--output <path>]
+```
+
+- `--search-type`：`1` 标题搜索（默认）| `2` 全文搜索
+- `--account-id`：公众号 ID（取自 list 返回的 `accountId`），可多次传入限定账号
+- `--category`：文章类型，可多选——`news` 新闻资讯 | `law` 法律法规 | `report` 报告类 | `view` 个人观点 | `data` 产业数据 | `event` 日程活动 | `meeting` 会议纪要 | `notice` 通知 | `recruit` 招聘 | `investEdu` 投资科普 | `brand` 品牌宣传 | `notes` 个人随笔 | `other` 其他
+- `--industry`：行业 ID，用 `reference constant-list --category citicIndustry`（或 `swIndustry`）查
+- `--keyword`：需用数据中的具体词（如 `泡泡玛特`），不能用整句白话
+- `--file-type`（download）：`1` txt（默认）| `2` HTML
+- 返回字段：`articleId` / `accountId` / `accountName` / `author` / `title` / `publishTime` / `url` / `originalFlag`（`0` 非原创 / `1` 原创）/ `articleCategory` / `summary`（模型摘要）/ `industryList[]{industryId, industryName}` / `conceptList[]{conceptId, conceptName}` / `securityList[]{securityCode, securityName}`
+
+## 投资者问答 QA `insight qa list`
+
+```bash
+gangtise insight qa list --security-code <code> [--start-time <t>] [--end-time <t>] [--source <type>] [--question-category <name>] [--answer-important <0|1>] [--size <n>]
+```
+
+- `--security-code`（**必填**）：证券代码，如 `601012.SH`（按单只证券提取投资者问答）
+- `--start-time` / `--end-time`：`yyyy-MM-dd` 或 `yyyy-MM-dd HH:mm:ss`（字符串直传，不转时间戳）
+- `--source`：问题来源，可多选——`conference` 电话会议 | `interactive` 互动平台 | `survey` 调研纪要
+- `--question-category`：问题类型，可多选——`productAndBusiness` 产品技术与业务布局 | `capacityAndProjects` 产能与项目进展 | `ordersAndCustomers` 订单与客户 | `financialData` 财务与经营数据 | `materialEvents` 重大事项 | `capitalOperations` 资本运作 | `shareholdersAndDividends` 股东户数与常规分红 | `corporateGovernance` 治理与管理 | `marketAndValuation` 市场与估值 | `macroAndIndustry` 宏观与行业看法 | `risksAndOthers` 风险质疑其他
+- `--answer-important`：答案是否涉及重要信息，可多选——`1` 是（回答匹配提问且涉及重要信息）| `0` 否；`--answer-important 1` 只取重要，省略或 `0 1` 两个都传=不按此维度筛选
+- 自动翻页（`{total,list}`，单页上限 500）；省略 `--size` 拉全量
+- 返回字段：`source` / `publishTime` / `question` / `answer` / `member`（回答方身份，如企业高管/董秘）/ `securityCode` / `questionCategory[]` / `answerImportant`（`1` 是 / `0` 否）
+- **积分**：0.1/条
+
+## 研报图表 `insight report-image list` / `download`
+
+```bash
+gangtise insight report-image list --keyword <text> [--top <n>] [--source-id <id>] [--start-time <t>] [--end-time <t>]
+gangtise insight report-image download --chunk-id <id> [--output <path>]
+```
+
+- `--keyword`（**必填**，list）：搜索关键词，如 `AI`、`新能源汽车`
+- `--top`：返回上限，默认 10，**最大 20**
+- `--source-id`：研报 ID，限定到某篇研报（可从研报列表或知识库取）
+- `--start-time` / `--end-time`：`yyyy-MM-dd HH:mm:ss`（兼容 `yyyy-MM-dd` 自动补全），限定图片所属研报的发布时间
+- `--chunk-id`（**必填**，download）：图片唯一标识，取自 list 返回的 `chunkId`；直接下二进制原图（JPEG）。省略 `--output` 时优先用服务端返回的文件名，无则按 `report-image-<chunkId>` 命名
+- list 返回字段：`chunkId` / `title` / `sourceId` / `broker` / `category` / `typeList[]` / `industry` / `publishTime` / `page` / `totalPages` / `imageCaption[]` / `imageFootnote[]` / `pageContent`（该页 OCR/描述文本）；扁平数组、无 `total`（不翻页，靠 `--top` 控量）
+- **积分**：list 免费；download 0.1/张

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

@@ -0,0 +1,93 @@
+# Quote 命令详细参数
+
+通用：`--field` 可重复（`--field open --field close`），可用字段见 `references/fields.md`。
+
+**关键规则**：查"最近"K线必须显式 `--start-date`/`--end-date` 拉范围，再从 `tradeDate` 取尾部最近 N 条；不要只用 `--limit N`（会截取查询窗口开头）。
+
+**自动分片**（v0.12.0；v0.14.2 修正分片粒度并注入 limit=10000）：`--security all` 跨日期范围 CLI 会自动按日切片并并发执行（A 股 1 天/片，美股 1 天/片，HK 2 天/片，指数 30 天/片），合并结果返回。CLI 在 `--security all` 路径会自动把 `limit` 抬到 10000（API 上限），避免默认 6000 行截断。无需手动按季度分批。
+
+**日K线历史性**（v0.14.0 起 API 文档明确）：所有日K线接口仅返回**历史数据**，不提供实时行情。盘中实时数据请改用 `quote realtime`。当日数据入库时间：A 股约 15:30、港股约 16:30、美股约 07:00（北京时间）。
+
+---
+
+## 日 K 线（A 股） `quote day-kline`
+
+```bash
+gangtise quote day-kline [--security <code>] [--start-date <YYYY-MM-DD>] [--end-date <YYYY-MM-DD>] [--limit <n>] [--field <name>]
+```
+
+- 支持 `.SH` `.SZ` `.BJ`，`--security all` 全市场
+- `--limit` 默认 6000，上限 10000
+- 常用字段：`open` `high` `low` `close` `pctChange` `volume` `amount`
+
+## 日 K 线（港股） `quote day-kline-hk`
+
+```bash
+gangtise quote day-kline-hk [--security <code>] [--start-date <YYYY-MM-DD>] [--end-date <YYYY-MM-DD>] [--limit <n>] [--field <name>]
+```
+
+- 支持 `.HK`，`--security all` 全市场
+- `--limit` 默认 6000，上限 10000
+
+## 日 K 线（美股） `quote day-kline-us`
+
+```bash
+gangtise quote day-kline-us [--security <code>] [--start-date <YYYY-MM-DD>] [--end-date <YYYY-MM-DD>] [--limit <n>] [--field <name>]
+```
+
+- 美股代码格式：`AAPL.O`（纳斯达克 `.O`，纽交所 `.N`，AMEX `.A`），`--security all` 全市场
+- 数据范围：NYSE / NASDAQ / AMEX
+- `--limit` 默认 6000，上限 10000
+- 字段与 A 股/港股相同，货币单位为美元
+
+## 实时行情 `quote realtime`
+
+```bash
+gangtise quote realtime [--security <code>] [--field <name>]
+```
+
+- **覆盖三大市场**：支持 A 股 / 港股 / 美股代码混合传入（如 `--security 600519.SH --security 00700.HK --security AAPL.O`）
+- **全市场关键字**：`--security aShares` 全部 A 股 / `--security hkStocks` 全部港股 / `--security usStocks` 全部美股；建议配合 `--field` 精简返回字段
+- 返回**最新时刻**的行情快照（最新价/开高低/涨跌/成交量额/振幅）
+- 非交易时间返回最近一个交易日的收盘快照；停牌证券返回停牌前最后一个有效快照
+- 字段速查：见 `references/fields.md` 中的"实时行情"小节
+
+## A股资金流向 `quote fund-flow`
+
+```bash
+gangtise quote fund-flow [--security <code>] [--start-date <YYYY-MM-DD>] [--end-date <YYYY-MM-DD>] [--limit <n>] [--field <name>]
+```
+
+- A 股个股**日频**资金流向（沪深京 `.SH` / `.SZ` / `.BJ`），仅历史数据；交易日数据约 16:30 入库
+- `--security`：证券代码（可重复），或 `aShares` 全市场 A 股（**须显式传 `--start-date`/`--end-date`**，CLI 按日自动分片并发合并；缺日期会本地报错）
+- `--start-date` / `--end-date`：`yyyy-MM-dd`；省略时 `end-date` 默认最新交易日、`start-date` 默认往前 1 年
+- `--limit`：默认 6000，**上限 10000**（超 10000 本地直接报错）
+  - **单只证券**：接口无翻页，返回行数撞上 `--limit` 时结果标 `partial`、退出码 3、stderr 警告——缩小日期区间分批拉取
+  - **`aShares` 全市场**（单日约 5000+ 行）：**须显式传 `--start-date`/`--end-date`**，CLI 按日自动分片并发合并、无需手动分批（缺日期或单请求多日全市场会触发服务端 `430012/430013`，分片规避了它）
+- `--field`：指定返回字段（`securityCode` / `tradeDate` 默认返回，恒在最前）；不传返回全部
+  - 小/中/大/特大单：`{small|medium|large|xlarge}{Inflow|Outflow|NetInflow|InflowRatio|OutflowRatio}`
+  - 汇总与主力：`total{Inflow|Outflow|NetInflow}` / `main{Inflow|Outflow|NetInflow|InflowRatio|OutflowRatio}`（主力 = 大单 + 特大单）
+- 金额单位：元；占比单位：%（各分类流入占比之和 = 100）
+- 无积分消耗
+
+## 指数日 K 线 `quote index-day-kline`
+
+```bash
+gangtise quote index-day-kline [--security <code>] [--start-date <YYYY-MM-DD>] [--end-date <YYYY-MM-DD>] [--limit <n>] [--field <name>]
+```
+
+- 沪深京指数：如 `000001.SH` 上证综指、`399001.SZ` 深成指；`--security all` 全市场指数
+- `--limit` 默认 6000，上限 10000
+- 常用字段：`securityCode` `securityName` `tradeDate` `open` `high` `low` `close` `preClose` `change` `pctChange` `volume` `amount`
+- `securityName` 为指数名称（如 `上证指数`），v0.15.0 起返回
+
+## 分钟 K 线（A 股） `quote minute-kline`
+
+```bash
+gangtise quote minute-kline --security <code> [--start-time <datetime>] [--end-time <datetime>] [--limit <n>] [--field <name>]
+```
+
+- 仅支持 A 股，**必须传 `--security`**（否则返回 430007）
+- `--start-time` / `--end-time`：`yyyy-MM-dd HH:mm:ss`（兼容 `yyyy-MM-dd` 自动补全）
+- `--limit` 默认 6000，上限 10000
+- 常用字段：`securityCode` `tradeTime` `open` `high` `low` `close` `change` `pctChange` `volume` `amount`

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`