gangtise-openapi-cli 0.26.0 → 0.27.0

package/gangtise-openapi/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: gangtise-openapi
+version: "0.27.0"
+description: |-
+  通过 gangtise CLI 直接调用 Gangtise OpenAPI，拉取投研原始数据、批量导出、下载文件、调用 AI 能力。
+
+  **触发词**：调接口 / CLI / openapi / 导出 / 下载研报 / 批量查 / 拉数据 / 跑一下 / 钢尼斯 / gtIC（Gangtise 语音误识别）
+
+  **适用**：原始数据导出、批量 jsonl/csv、下载 PDF/MD、行情 K 线、财务报表、估值指标、证券级数据指标（EDE 截面/时序）、AI 能力（一页通/投资逻辑/同业对比/个股看点·投研总结/投研线索/业绩点评/观点PK·多空辩论/主题跟踪/热点话题/管理层讨论/调研提纲/知识库搜索）、云盘文件管理（Vault）
+
+  **不适用**：不脱离 OpenAPI 自行撰写研报、编造投研结论或做自由问答——观点总结、多空 PK 等 AI 产物本 skill 只经由 Gangtise 平台 AI 接口获取，不自行生成
+
+  **前置**：依赖 gangtise CLI，未安装时提示用户 `npm install -g gangtise-openapi-cli`
+---
+
+# Gangtise OpenAPI CLI
+
+> **详细参数 → `references/commands/<group>.md`**（按需 Read）
+> **响应字段 → `references/response-schema.md`** ｜ **典型示例 → `references/examples.md`**
+> **高频 ID → `references/lookup-ids.md`** ｜ **K 线/财务字段 → `references/fields.md`**
+
+## 必备规则
+
+1. **`--format json`**：列表/数据类必加。AI 内容生成（`one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `*-check`）也加 json，但呈现时**直接取 `content` 字段**，不要展示 JSON 包装层。
+2. **opaque ID**：先读 `references/lookup-ids.md`；找不到再按类型查：行业/区域/公告分类/城市 → `reference constant-list --category <分类>`（分类代码用 `reference constant-category` 查）；题材 → `reference concept-search --keyword <名>`；板块 → `reference sector-search --keyword <名>`；申万 `--gts-code` 行业代码全量 → `sector-search --keyword 申万一级行业指数` 取指数数据板块层级的 sectorId 再 `sector-constituents`；券商/牵头/观点机构（按名称找 ID）→ `reference institution-search --keyword <名> [--category ...]`（服务端搜索，返回 `institutionId` + `usageScopes` 标明该 ID 用于哪个接口的哪个参数；覆盖 `--broker` / `--institution` 全部 5 类机构，含 `foreignOpinionInstitution`）——仅当要**全量枚举**时才用本地表 `gangtise lookup broker-org/meeting-org list`（institution-search 是搜索型：top≤10、非全量）。**绝不猜测**。
+3. **公司名 → 证券代码**：先查下方速查表（5 只 mega-cap），其余一律 `gangtise reference securities-search --keyword <名> --category stock` 取 `list[0].gtsCode`。
+4. **时间格式**：datetime `"YYYY-MM-DD HH:mm:ss"`（引号包裹），date `YYYY-MM-DD`。
+5. **多值参数**：优先重复传（最稳、最明确）：`--security 600519.SH --security 000858.SZ`。CLI 也支持半/全角逗号分隔（`args.ts` 为语音输入容错），但重复传不易被 shell 吞。
+6. **K 线"最近 N 条"**：必须用 `--start-date`/`--end-date` 拉日期范围，从结果按 `tradeDate` 取尾部最近 N 条。**不要只用 `--limit N`**（截取的是窗口开头）。
+6.1. **日 K 仅历史**：`day-kline` / `day-kline-hk` / `day-kline-us` **不返回盘中实时数据**。当日数据入库时间：A 股 ~15:30 / 港股 ~16:30 / 美股 ~07:00（北京时间）。需要盘中快照请走 `quote realtime`。
+6.2. **多标的日 K 不自动分片**：只有 `--security all` 才按日切片提额；显式传多个 `--security` 时走单请求（默认 `--limit 6000` / 上限 10000）。**v0.23.0 起：返回行数撞上 `--limit` 时结果会标 `partial`、退出码 3、stderr 警告**（不再静默截断；`--limit` 超 10000 本地直接报错）。仍建议先估 标的数 × 交易日数，接近/超 6000 → 逐只分开拉、或显式 `--limit 10000` 并按日期区间分批。
+7. **CLI 已内置自动化，不要手动复刻**：
+   - 翻页 → 首页拿 total 后剩余页并发拉取
+   - K 线 `--security all` 跨日期 → 自动按日切片并合并
+   - 5xx / `429` / 网络错误 / `999999` → 自动指数退避重试（🔴 贵档端点例外：仅连接失败 / 429 / token 自愈重试，5xx/超时不重放防重复扣分，v0.26.0；`indicator` 端点对 `999999` 不重试——该码=查询无数据，v0.27.0）
+   - Token 失效（`0000001008` 服务端失效 / `8000014` / `8000015` AK/SK 错误）→ 自动重新登录并重试一次
+8. **参数命名差异**：Insight/Quote/Vault 用 `--security`，Fundamental/AI 用 `--security-code`（例外：`ai stock-summary` 用 `--security`，`ai security-clue` 用 `--gts-code`）。
+9. **调试**：`--verbose` 或 `GANGTISE_VERBOSE=1` 打印每个请求的耗时/字节数到 stderr。
+
+## 工作流（3 步）
+
+```
+意图 → 命令（路由表）  →  执行（pre-flight + 拼参数）  →  呈现（按响应模式）
+```
+
+### Pre-flight（执行前必过）
+
+🔴 **需用户确认**：
+- `gangtise auth status` 未登录 → 提示配置 AK/SK 并中止
+- 多个命令同时匹配 → 复述理解让用户挑（如"搜索研报" → research list 还是 knowledge-batch？）
+- 用户说"全部 / 全量 / 全市场" → 确认量级再拉：省略 `--size` 就是拉全量（自动翻页，上限 1000 页）；先 `--size 1` 看 stderr 的 `Total: N` 再决定（探量这步别加 `--format json`——json 下不打 `Total` 行）；全市场/跨一年分片等大批量可 `GANGTISE_PAGE_CONCURRENCY=10` 提速（默认 5，同时管翻页与 K 线分片）
+- **高积分操作先确认**：任何 50 积分/次及以上、或"按条 × 大批量"（如 `stock-summary` 全市场数千只、`opinion` 全量翻页、`concept-info` 500/次）→ 先估总积分告知用户再执行（单价见下「积分计费速查」）
+- 下载**必选**格式未定才问：`independent-opinion --file-type`（必选）、`vault record/my-conference --content-type`（record 三种 original/asr/summary、my-conference 两种 asr/summary）；其余 download 有默认（多为 `1`=PDF/原始），用户没提格式就用默认、不必问
+- list→download 用户没指定具体文件 → 展示前 10 条让用户挑
+
+🟡 **自行判断**：
+- 公司名 → 先速查表，否则 `reference securities-search`
+- opaque ID → 先 `references/lookup-ids.md`
+- 模糊时间词 → 查"时间词映射"
+- 无时间范围且用户没要求全量 → 主动加 `--size 200` 兜底（不必问）；注意 CLI 省略 `--size` 会拉全量
+- 预估结果 >200 行 → 别全量 `--format json` 引进上下文，改 `--format jsonl --output <file>` 落盘（CLI ≥1000 行自动流式、stdout 只回显文件路径），再 `wc -l` + `head` 采样呈现
+- 路由到 AI 同步生成命令 → 7 个 agent 类（`one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `theme-tracking` / `management-discuss-*`）CLI 已内置 120s 超时下限，无需前缀；`stock-summary` / `hot-topic` 仍建议前置 `GANGTISE_TIMEOUT_MS=120000`。**贵档端点超时/5xx 已不再自动重试**（v0.26.0；重放=重复扣分）——超时报错后内容可能已在服务端生成并扣费，同参数再调仍会**再扣一次**（实测无缓存豁免），所以一次调用给足超时比失败重跑省钱。`earnings-review` / `viewpoint-debate` 是异步（`--wait` 或 `*-check` 轮询），不吃这个超时
+- "AI速记/智能摘要/会议纪要"→`summary`、"原始文件/原文件"→`original`、"语音识别/转写文本/ASR"→`asr` — 用户已明示时直接映射 content-type，不必问
+
+### 积分计费速查
+
+"免费"=0 积分；**只列单价**，数据范围（可查多久）随账号等级不同、不在此列。
+
+- **免费**：所有 `quote` 行情、`fundamental` 报表/主营/估值/股东（**盈利预测除外**）、`reference`/`constant` 查询（含 `official-account-search`）、`alternative edb-search`、`vault`（record/wechat/股票池/drive/AI云盘）、`insight report-image list`
+- **0.1/条 list**：research / foreign-report / official-account / announcement(A/港/美) / summary / qa 的 list、`vault my-conference-list`；`insight report-image download` 0.1/张
+- **按条（观点/含详情类 list）**：independent-opinion list 与 `ai security-clue` 5；roadshow/site-visit/strategy/forum list 20；opinion / foreign-opinion list 30；`fundamental earning-forecast` 0.5；`ai stock-summary` 3（无看点的证券不返回也不扣）；`alternative edb-data` 30
+- **各 download（/篇）**：announcement / official-account 10；research / announcement-hk / announcement-us 20；independent-opinion 30；summary / foreign-report / my-conference 50
+- 🔴 **按次贵**：`ai knowledge-batch` 10、`management-discuss-*` 10；AI Agent（`one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `earnings-review` / `viewpoint-debate` / `theme-tracking`）**50/次**；`ai hot-topic` 50/篇
+- 🔴 **极贵**：`alternative concept-info` / `concept-securities` **500/次**
+- ⚠️ **同参数重复调用不免费**：按次计费无缓存命中豁免（2026-07-11 实测 `one-pager` 重复调用每次扣分，即使秒回缓存内容）——生成类结果拿到后自行留存复用，别为"刷新"重调；CLI 已对上述 🔴 贵档端点关闭 5xx/超时自动重放（v0.26.0），50/篇 的 `summary` / `foreign-report` / `my-conference` download 同样不重放（v0.27.0），正是为防重复扣分
+- **按单元格**：`indicator cross-section` / `time-series`（A股 0.05 / 港股 0.1 / 美股 0.2 积分每 100 单元格，见 `indicator.md`）；`ai knowledge-resource-download` 按下游资源计费
+
+### 下载规则（`--file-type` / `--content-type`）
+
+| 命令 | 参数 | 取值 |
+|------|------|------|
+| `insight research download` | `--file-type` | `1` PDF（默认）/ `2` Markdown |
+| `insight foreign-report download` | `--file-type` | `1` PDF / `2` MD / `3` 中译 PDF / `4` 中译 MD |
+| `insight announcement download` | `--file-type` | `1` PDF / `2` Markdown |
+| `insight summary download` | `--file-type`（可选） | `1` 原始（默认）/ `2` HTML（仅会议平台来源） |
+| `insight independent-opinion download` | `--file-type` **必选** | `1` 原文 HTML / `2` 翻译 HTML |
+| `insight announcement-hk download` | `--file-type` | `1` 原始（默认）/ `2` Markdown |
+| `insight announcement-us download` | `--file-type` | `1` 原始 PDF（默认）/ `2` Markdown |
+| `insight official-account download` | `--file-type` | `1` txt（默认）/ `2` HTML |
+| `vault record-download` | `--content-type` | `original` 原始文件 / `asr` 语音识别 / `summary` AI 速记 |
+| `vault my-conference-download` | `--content-type` | `asr` 语音识别 / `summary` AI 速记 |
+
+省略 `--output` 时 CLI 自动用真实标题做文件名（先读本地 title-cache，未命中则回查 list 接口）。**批量下载或下载旧文件**（跳过 list 直接按 ID 下）时 title-cache 大概率未命中、每个文件都回查一次 list，建议显式 `--output ./<名>.<ext>` 省掉回查。
+
+## 意图路由表
+
+| 用户意图 | 命令 |
+|---------|------|
+| 研报 / 券商报告 | `insight research list` |
+| 外资研报 | `insight foreign-report list` |
+| 首席观点 / 内资机构观点 / 分析师观点 | `insight opinion list` |
+| 外资机构观点 / 外资券商观点 | `insight foreign-opinion list` |
+| 外资独立观点 / 独立分析师观点 | `insight independent-opinion list` |
+| 纪要 / 会议纪要（外部） | `insight summary list` |
+| 路演 / 调研 / 策略会 / 论坛 | `insight roadshow / site-visit / strategy / forum list` |
+| A 股公告 / 公告 | `insight announcement list` |
+| 港股公告 / HK 公告 | `insight announcement-hk list` |
+| 美股公告 / US 公告 | `insight announcement-us list` |
+| 公众号资讯 / 产业资讯 / 公众号文章 | `insight official-account list` |
+| 投资者问答 / 互动平台 / 电话会议 / 调研纪要 QA | `insight qa list`（按证券，`--security-code` 必填；`--source`/`--question-category`/`--answer-important` 精筛） |
+| 研报图表 / 研报图片搜索 | `insight report-image list`（`--keyword`；下载原图 `insight report-image download --chunk-id`） |
+| 跨类型语义搜索（研报+纪要+...） | `ai knowledge-batch`（多个 `--resource-type`） |
+| 知识库原文下载（搜到后取全文） | `ai knowledge-resource-download`（前置：`knowledge-batch` 拿 `resourceType`+`sourceId`；`433007`=组合不匹配） |
+| 一页通 / 投资逻辑 / 同业对比 / 调研提纲 | `ai one-pager / investment-logic / peer-comparison / research-outline` |
+| 个股看点 / 投研总结 / 公司速览 | `ai stock-summary`（`--security` 代码或 `aShares`/`hkStocks` 全市场；仅 A 股/港股） |
+| 业绩点评（异步） | `ai earnings-review` |
+| 观点 PK / 多空辩论（异步） | `ai viewpoint-debate` |
+| 投研线索 | `ai security-clue`（前置：`reference securities-search` 拿 `gts-code`） |
+| 主题跟踪 | `ai theme-tracking`（前置：`reference concept-search` 拿 `theme-id`） |
+| 热点话题 / 早午晚报 | `ai hot-topic` |
+| 管理层讨论（财报） | `ai management-discuss-announcement` |
+| 管理层讨论（业绩会） | `ai management-discuss-earnings-call` |
+| A 股日 K（历史） | `quote day-kline` |
+| 港股日 K（历史） | `quote day-kline-hk` |
+| 美股日 K（历史） | `quote day-kline-us` |
+| 指数日 K（沪深京） | `quote index-day-kline` |
+| 分钟 K（A 股） | `quote minute-kline` |
+| 实时行情（A / 港 / 美） | `quote realtime` |
+| A股资金流向（主力/大单净流入，日频） | `quote fund-flow`（`--security` 或 `aShares` 全市场〔须带 `--start-date`/`--end-date`，按日自动分片〕；免费） |
+| A股利润表 / 资产负债 / 现金流（累计 / 单季） | `fundamental income-statement[-quarterly] / balance-sheet / cash-flow[-quarterly]` |
+| 港股利润表 / 资产负债 / 现金流 | `fundamental income-statement-hk / balance-sheet-hk / cash-flow-hk` |
+| 美股利润表 / 资产负债 / 现金流 | `fundamental income-statement-us / balance-sheet-us / cash-flow-us` |
+| 主营业务 / 收入结构 | `fundamental main-business` |
+| 估值 / PE / PB | `fundamental valuation-analysis` |
+| 盈利预测 / 一致预期 | `fundamental earning-forecast` |
+| 前十大股东 | `fundamental top-holders` |
+| 云盘文件 | `vault drive-list / drive-download` |
+| 录音速记 | `vault record-list / record-download` |
+| 我的会议（业绩会/策略会/路演内部记录） | `vault my-conference-list / my-conference-download` |
+| 微信群消息 | `vault wechat-message-list`（先 `vault wechat-chatroom-list` 拿群 ID） |
+| 自选股股票池 | `vault stock-pool-list / stock-pool-stocks` |
+| 行业指标搜索（EDB） | `alternative edb-search` |
+| 行业指标时序数据（EDB） | `alternative edb-data` |
+| 题材画像 / 投资逻辑 / 行业空间 / 竞争格局 / 催化事件 | `alternative concept-info`（前置：`reference concept-search` 拿 `concept-id`） |
+| 题材成分股 / 题材深度 F8 / 题材龙头 | `alternative concept-securities`（前置：`reference concept-search` 拿 `concept-id`） |
+| 指标搜索 / 找指标编码（收盘价/成交量/总市值/财务指标的 code） | `indicator search` |
+| 指标截面数据（多指标 × 多证券，单日快照） | `indicator cross-section`（前置：`indicator search` 拿 indicatorCode） |
+| 指标时间序列（多指标 × 单证券 或 单指标 × 多证券，按区间） | `indicator time-series`（前置：`indicator search` 拿 indicatorCode） |
+| 证券代码 / gtsCode 搜索 | `reference securities-search` |
+| 首席 ID / 分析师 ID 搜索 | `reference chiefs-search`（按姓名/机构/团队，用于 `insight opinion --chief`） |
+| 机构 ID 搜索（内资券商/外资/牵头/观点机构） | `reference institution-search`（按机构名，用于 `--institution` / `--broker`；免费） |
+| 公众号 ID 搜索（按公众号名/机构/分类） | `reference official-account-search`（返回 `accountId`，喂 `insight official-account list --account-id`；免费） |
+| 常量/枚举 ID（行业/城市/公告分类/区域） | `reference constant-list --category <code>`（分类代码用 `reference constant-category` 查） |
+| 题材 ID 搜索 | `reference concept-search` |
+| 板块 ID 搜索 | `reference sector-search` |
+| 板块成分股 | `reference sector-constituents`（前置：`reference sector-search` 拿 `sector-id`） |
+
+**易混淆消歧**：
+- "纪要" → 外部信息走 `insight summary`；公司内部录音/会议走 `vault my-conference`
+- "搜索 X" → 数据维度精确（按行业/券商）走对应 `insight ... list`；跨类型语义搜索走 `ai knowledge-batch`
+- 港股代码用在 `insight foreign-opinion --security` 还是 `quote day-kline-hk --security`？前者要"境外"格式（`UBER.N`），后者要 `.HK`
+- "成分股" → 题材深度（分组/重点标记/纳入理由）走 `alternative concept-securities`；板块（行业/概念分类树，纯代码名单）走 `reference sector-constituents`
+- "指标" → 证券级指标（总市值/估值分位/财务指标等，需 `--security` 证券代码）走 `indicator`（EDE）；**但基础行情（收盘价/开高低收/成交量/成交额/涨跌幅）优先 `quote`**（免费、可 `--security all` 自动分片；`indicator` 按单元格计费且需先 search 拿 code）；行业/宏观指标（空调销量、社融等，无证券维度）走 `alternative edb-*`（EDB），三套接口不同
+- `indicator` 取数二选一：单日多标的横向对比 → `cross-section`；时间区间纵向走势 → `time-series`（且 `time-series` 不能多指标 × 多证券同时，截面才可以）
+- `indicator` 取数前**先 `search --format json` 看 `parameterList`**：很多指标有必填参数（`periodNum`/`startDate`/`fiscalYear`），不补会报错（服务端现直接指明「必填参数 X 不能为空」）；**无数据已统一返回 `null`**（截面不再抛 `999999`、不丢行），换公司类型/年报日期可取到对应类型科目的数。**取"最新"值别踩空**：行情类 `--date` 填当天且盘中/未入库会整行 `null`（≠无数据，别据此报"无数据"），改用 T-1 交易日；财务类用报告期末（如 `2025-12-31`）。详见 `references/commands/indicator.md`
+- "业绩点评"双义消歧：**检索已有**（研报/纪要里的业绩点评内容）走 `insight ... list --llm-tag earningsReview`（0.1/条）；**AI 现生成**一份走 `ai earnings-review`（异步、50/次）。不确定问一句
+- "多公司最新 PE / 总市值"：单证券估值序列走 `fundamental valuation-analysis`（免费、默认近一年日频、**无总市值指标**）；要总市值或多证券横向快照走 `indicator cross-section`（先 search 拿 code，按单元格计费）。总市值 `qte_mkt_cptl` **仅 A 股**、默认原始「元」（茅台 ≈1.5e12），比大小前用 `scale`/`currency` 统一（详见 indicator.md）
+
+## 公司名 → 证券代码
+
+**速查表**（仅 mega-cap，命中率不高的一律走 securities-search）：
+
+| 公司 | A 股 | 港股 | 美股 |
+|------|------|------|------|
+| 贵州茅台 | `600519.SH` | — | — |
+| 宁德时代 | `300750.SZ` | — | — |
+| 比亚迪 | `002594.SZ` | `01211.HK` | — |
+| 中国平安 | `601318.SH` | `02318.HK` | — |
+| 腾讯控股 | — | `00700.HK` | — |
+| 苹果 Apple | — | — | `AAPL.O` |
+| 微软 Microsoft | — | — | `MSFT.O` |
+
+**其余一律**：
+```bash
+gangtise reference securities-search --keyword <公司名> --category stock --top 3 --format json
+```
+取 `data.list[0].gtsCode`。matchScore < 0.5 时让用户从前 3 条选。
+
+**交易所后缀**：`.SH` 上交所（6 开头）｜ `.SZ` 深交所（0/3 开头）｜ `.BJ` 北交所 ｜ `.HK` 港股 ｜ `.O` 纳斯达克 ｜ `.N` 纽交所 ｜ `.A` AMEX。
+
+**跨市场**：日 K 线需分别调对应命令（`day-kline` / `day-kline-hk` / `day-kline-us`）。**实时行情可一次混合**：`quote realtime --security 600519.SH --security 00700.HK --security AAPL.O` 单接口同时返回。
+
+## 响应解析骨架（5 类通用模式）
+
+| 模式 | 出现命令 | 结构 | 处理 |
+|------|---------|------|------|
+| **列表** | 大多数 `list` | `{list: [...], total: N}` | 遍历 list；CLI 已自动翻页 |
+| **下载** | 各 `download` | stdout = 文件路径字符串 | 直接读 stdout 整行 |
+| **AI 内容** | one-pager / investment-logic / peer-comparison / research-outline | `{content: "markdown文本"}` | 取 `content` 直接呈现 |
+| **K 线** | quote * | `{list: [{tradeDate, ...}]}` | 按 tradeDate 排序，取需要的尾部 |
+| **异步（含 *-check）** | earnings-review / viewpoint-debate / earnings-review-check / viewpoint-debate-check | 提交 `{dataId, status, hint}`；check 成功 `{date, content}` / pending `{status:"pending"}` 或抛 `410110` | 见下方"异步任务流程" |
+
+完整字段对照见 `references/response-schema.md`。
+
+### 异步任务流程
+
+`earnings-review` / `viewpoint-debate` 异步生成，两条路径：
+
+- **`--wait`（推荐）**：命令带 `--wait` 阻塞到出结果（CLI 内轮询最长 ≈316s）。**把工具/命令超时设到 ≥360s**，否则外层先超时。直接拿 `{date, content}` 呈现。
+- **手动轮询**（不带 `--wait`）：① 提交 → 拿 `{dataId, status, hint}`；② 间隔 ~30s 调 `*-check --data-id <id>`（预算给足 ~2-3 分钟）；③ `{date, content}`=成功 / `{status:"pending"}`=继续等 / 终态失败=换参重试；④ 多次仍 pending → 把 `dataId` 交用户稍后再 check。
+
+**别把原始码甩给用户**：`410110`=生成中（继续等）、`410111`=终态失败（换参），按 `status` + 退出码判断后用人话说明。
+
+### 呈现规范
+
+- 列表 ≤20 行表格 + 总数；>20 条仅展示前 20 条 + 询问是否导出全量
+- 下载完成后告知文件路径
+- AI content 直接 markdown 呈现
+- K 线展示最近 10 个交易日表格
+
+## 时间词映射
+
+| 模糊词 | Insight / Vault / AI | Quote K 线 | Fundamental（财报/估值） |
+|--------|---------------------|-----------|----------------------|
+| 最近 / 近期 | 7 天 | 45 天 | 1 年 |
+| 最近一周 | 7 天 | 7 天 | — |
+| 最近一个月 | 30 天 | 30 天 | — |
+| 过去一年 / 近一年 | 1 年 | 1 年 | 1 年 |
+| 今年 | 1/1 至今 | 1/1 至今 | 1/1 至今 |
+| 今天 / 今日 | 当天（`start=end=`今天） | 见下行「最新 / 今日 / 当前（K 线）」 | — |
+| 最新 / 今日 / 当前（K 线） | — | **45 天范围 → 从尾部取最近交易日**，不要只用 `--limit` | — |
+| 最新一期 / 最新报告期（财报） | — | — | 省略 `--fiscal-year`，传 `--period latest`（默认） |
+| 最新观点 / 今日观点 | 1 天范围 + `--rank-type 2` | — | — |
+
+参数命名：Insight/Vault/AI 用 `--start-time` / `--end-time`（datetime）；Quote/Fundamental 用 `--start-date` / `--end-date`（date）。**三个例外**：`ai knowledge-batch` 的 `--start-time`/`--end-time` 收 **13 位毫秒时间戳**（传 datetime 字符串会报 `expected a finite number`）；`ai hot-topic` 用 `--start-date`/`--end-date`（date）；`quote minute-kline` 虽属 Quote 却用 `--start-time`/`--end-time` 且为 datetime。
+
+支持时间倒序的命令加 `--rank-type 2`：opinion / summary / research / foreign-report / announcement / announcement-hk / announcement-us / foreign-opinion / independent-opinion / official-account。其他 list 命令按 API 默认排序。
+
+## 异常处理
+
+| 错误码 | 含义 | CLI 行为 | Agent 是否介入 |
+|--------|------|---------|--------------|
+| `999999` | 系统错误；但 **`indicator`（EDE）仍会用此码 + HTTP 500 表示查询无数据**（节假日 / 未来日期 / 未覆盖标的，2026-07-11 实测）——单元格级缺值才是 `null` | 普通端点自动重试 ×2；🔴 贵档与 `indicator` 端点不重试（CLI hint 会直接提示「多为查询无数据」） | `indicator` 遇到先检查日期/标的是否该有数据，别盲目重试 |
+| `410110` | 异步生成中 | 异步轮询逻辑视为 pending | 继续等 |
+| `410111` | 异步生成失败 | 终态 | **不重试**，建议换参数 |
+| `410106` / 缺参 | `indicator` **缺必填参数**（服务端现直接指明缺哪个，如「必填参数 periodNum 不能为空」；以 HTTP 500 返回故 CLI 重试 ×2） | **自动重试 ×2** | 读 `indicator search --format json` 的 `parameterList`，补 `required:true` 参数（periodNum/startDate/fiscalYear） |
+| `0000001008` | Token 服务端失效（他处登录挤掉） | **强制重新登录并重试一次** | 无 AK/SK 时无法自愈，提示重新登录 |
+| `8000014` / `8000015` | AK/SK 错误 | **自动刷新 token 并重试一次** | 再失败提示检查 env |
+| `8000016` / `8000018` | 账号异常 / 到期 | — | 提示联系管理员 |
+| `999997` | 未开通权限 | — | 联系管理员 |
+| `999995` | 积分不足 | — | 联系管理员 |
+| `903301` | 今日调用上限 | **不重试** | 告知用户次日重试或升级配额 |
+| `433007` | 数据源不匹配 | — | 检查 `resourceType + sourceId` 组合 |
+| `410004` | 数据未找到，或**该指标无权限**（服务端复用此码；`indicator` 内层失败会带具体 msg 如"指标无权限"） | — | 检查查询条件与指标权限 |
+| `430007` | 行情查询超出限制 | — | 缩短日期范围；全市场场景应已自动分片 |
+| `430004` | 研报下载报错（官方未文档化，实测出现于 download） | — | 确认 reportId 有效；换 `--file-type` 或换一篇验证 |
+| `900001` | 请求参数缺失 | — | 检查必填项（如 `--indicator` / `--date`） |
+| `100003` | 参数值非法（服务端不指明是哪个参数） | — | 对照命令 `--help` 检查枚举参数拼写/取值（如 `--source` / `--question-category` / `--answer-important`），**不要重试同命令** |
+| `900002` | 请求缺少 uid | — | `gangtise auth status` 查登录状态，重登后重试 |
+| `10011401` | 白名单未开通 | — | 联系管理员 |
+| HTTP 5xx / `ECONNRESET` / 超时 | 网络/服务端 | **自动指数退避重试 ×2** | 仍失败提示用户 |
+| `ValidationError` | 本地参数校验失败 | — | 检查 `--from` / `--size` / `--limit` 数值，**不要重试同命令** |
+
+**其他场景**：
+- CLI 未安装 → `npm install -g gangtise-openapi-cli`
+- **退出码 3 = 部分结果**：翻页/K线分片有页失败、或服务端返回行数与 `total` 矛盾（提前短页）时，已取到的数据保留——stderr 有 warning，`--format json` 可见 `partial: true`（页失败另有 `failedPages`；分片失败为 `failedShards`、分片撞行数上限为 `truncatedShards`，均带具体日期区间可定向缩窗补拉）；table/csv/jsonl 只有数据行、看不出缺失。拿部分数据继续前必须告知用户缺了哪段
+- 空结果（list 为空数组） → 建议扩大时间范围、换关键词、去掉部分筛选
+- 模糊公司名匹配多只（"平安" → 中国平安 / 平安银行 / ...） → 列出让用户选
+- 下载文件路径冲突 → 询问覆盖
+
+## Troubleshooting（常见困境自救）
+
+按问题→诊断顺序依次尝试，第一条解决就停。
+
+**`securities-search` 找不到公司**
+1. 试拼音 / 首字母（如"贵州茅台"试 `gzmt`）
+2. 去掉"股份/有限公司/集团"等后缀重试
+3. 不传 `--category` 查所有分类（可能是 fund / DR）
+4. 还不行 → 请用户提供精确代码
+
+**`list` 全空但参数看着对**
+1. 时间窗太窄 → 扩到 30 天试
+2. `--security` 后缀拼错（如 `300750` 漏了 `.SZ`）
+3. 行业 ID 用错体系：`--industry`（用 `citicIndustry` 码 `1008001xx`）/ `--research-area`（用 `gangtiseIndustry`：行业 `1008001xx` + 方向 `122000xxx`）/ `--gts-code`（申万 `821xxx.SWI`）——三套体系不同，详见 `references/commands/reference-and-lookup.md`
+4. `--rating` / `--category` 等枚举值拼错（参考对应命令的 references 文件）
+
+**`8000014` / `8000015` 反复**（CLI 已自动重试一次仍失败）
+1. `echo $GANGTISE_ACCESS_KEY` 验环境变量是否 export
+2. AK 和 SK 是否写反
+3. 账号是否到期 / 异常（`gangtise auth status`）
+
+**异步任务 `410111` 反复**（该报告期数据未生成）
+1. 换更早的 `--period`（如 `2025q3` → `2025interim`）
+2. `report-date` 用已发布的标准期：`xxxx-06-30` / `xxxx-12-31`
+3. 直接告知用户该期数据暂不可用
+
+**K 线返回的不是"最近"几条** → 只用 `--limit` 截的是窗口开头。必须改用 `--start-date`/`--end-date` 拉范围，再从结果尾部按 `tradeDate` 取最近 N 条。
+
+**翻页很慢 / 卡住** → `--verbose` 看哪一页慢；可 `GANGTISE_PAGE_CONCURRENCY=10` 提速，或缩小时间范围。
+
+**`--security all` 报 `430007`** → 单日数据仍超 10K 行（极端情况）→ 临时改用更窄的 `--start-date`/`--end-date`，或改为单只 `--security` 单独拉。
+
+**AI agent 命令（one-pager 等）超时** → 服务端生成耗时长，CLI 默认 30s → `GANGTISE_TIMEOUT_MS=120000` 后重试。
+
+**估值结果出现大量 `null`** → 最新交易日数据未入库 → 加 `--skip-null` 过滤掉 `value` / `percentileRank` 为 null 的行。
+
+**下载文件名乱码 / 截断** → terminal locale 或 shell quoting 问题 → 显式 `--output ./<title>.<ext>` 避开。
+
+**同一公司既是股票又是 DR** → `securities-search` 默认返回所有分类 → 加 `--category stock` 收敛。
+
+**`sector-constituents` 返回 0 条** → sectorId 不对（题材 conceptId 与板块 sectorId 是两套 ID，不通用）→ 先 `reference sector-search --keyword <名>` 拿 `sectorId` 重试。
+
+## 详细参数
+
+按需 Read 对应文件：
+
+- 内资观点 / 纪要 / 路演 / 调研 / 策略 / 论坛 / 研报 / 外资研报 / A 股公告 / 港股公告 / 美股公告 / 外资观点 / 独立观点 / 公众号（official-account）/ 投资者问答（qa）/ 研报图表（report-image）→ `references/commands/insight.md`
+- 行情命令（A 股 / 港股 / 美股日 K / 指数日 K / 分钟 K / 实时行情 / 资金流向 fund-flow） → `references/commands/quote.md`
+- 三大报表（A 股 / 港股 / 美股）/ 主营 / 估值 / 盈利预测 / 股东 → `references/commands/fundamental.md`
+- knowledge-batch / security-clue / 个股看点（stock-summary）/ AI agent / 异步任务 / 主题跟踪 / 热点 / 管理层讨论 → `references/commands/ai.md`
+- drive / record / my-conference / wechat / 股票池 → `references/commands/vault.md`
+- 行业指标数据库（EDB）/ 题材指数画像与成分股（concept-info / concept-securities）→ `references/commands/alternative.md`
+- 数据指标（EDE：search / cross-section / time-series，证券级指标截面与时序）→ `references/commands/indicator.md`
+- securities-search / chiefs-search（首席 ID）/ institution-search（机构 ID）/ official-account-search（公众号 ID）/ 常量查询（constant-category / constant-list）/ 题材 ID（concept-search）/ 板块（sector-search / sector-constituents）/ lookup 本地表 / 行业别名 / raw call → `references/commands/reference-and-lookup.md`
+
+跑通流程对照 → `references/examples.md`

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

@@ -0,0 +1,149 @@
+# AI 命令详细参数
+
+注意：`ai one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `viewpoint-debate-check` / `earnings-review-check` 返回 `{content: "markdown文本"}`；这类命令仍然加 `--format json`，但呈现给用户时直接取 `content` 字段，不要展示 JSON 包装层。
+
+**⏱ 超时与重复扣分**：7 个 agent 类（`one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `theme-tracking` / `management-discuss-*`）CLI 已内置 120s 超时下限，**无需前缀**；`stock-summary` / `hot-topic` 首次生成也常 >30s，仍建议前置 `GANGTISE_TIMEOUT_MS=120000`。自 v0.26.0 起**贵档端点超时/5xx 不再自动重试**（重放=重复扣分）——超时报错后内容可能已在服务端生成并扣费，同参数再调会**再扣一次**（实测按次计费、无缓存命中豁免），所以一次调用给足超时比失败重跑省钱；拿到的生成内容自行留存复用，别为"刷新"重调。`earnings-review` / `viewpoint-debate` 是异步——用 `--wait`（工具超时 ≥360s）或 `*-check` 轮询，不吃这个超时。
+
+---
+
+## 知识库搜索 `ai knowledge-batch`
+
+```bash
+gangtise ai knowledge-batch --query <text> [--query <text2>] [--top <n>] [--resource-type <n>] [--knowledge-name <name>] [--start-time <ms>] [--end-time <ms>]
+```
+
+- `--query`（**必选**，可重复，最多 5 个）：缺失时本地报错，不发空请求
+- `--top` 默认 10，最大 20
+- `--resource-type`：`10` 券商研报 | `11` 外资研报 | `20` 内部报告 | `40` 首席观点 | `50` 公司公告 | `51` 港股公告 | `60` 会议平台纪要 | `70` 调研纪要公告 | `80` 网络资源纪要 | `90` 产业公众号
+- `--knowledge-name`：`system_knowledge_doc` 系统知识库 | `tenant_knowledge_doc` 机构知识库
+- `--start-time` / `--end-time`：13 位毫秒时间戳，按时间范围过滤
+
+## 知识资源下载 `ai knowledge-resource-download`
+
+```bash
+gangtise ai knowledge-resource-download --resource-type <n> --source-id <id> [--output <path>]
+```
+
+`resourceType + sourceId` 必须匹配（来自 knowledge-batch 返回），错配返回 `433007`。
+
+## 投研线索 `ai security-clue`
+
+```bash
+gangtise ai security-clue --start-time <datetime> --end-time <datetime> --query-mode <mode> [--gts-code <code>] [--source <name>] [--from <n>] [--size <n>]
+```
+
+- `--query-mode`（**必选**）：`bySecurity` 按证券 | `byIndustry` 按行业
+- `--gts-code`（建议必传，CLI 未强制）：个股代码（如 `600519.SH`）或申万行业代码（如 `821035.SWI`）。**先用 `reference securities-search` 查个股，或读 `references/lookup-ids.md` 查行业**（全量行业代码：`reference sector-constituents --sector-id 2000000014`）
+- `--source`：`researchReport` | `conference` | `announcement` | `view`
+- `--from` / `--size`：自动翻页（单页 500）；省略 `--size` 拉全量
+
+## 一页通 / 投资逻辑 / 同业对比
+
+```bash
+gangtise ai one-pager        --security-code <code>
+gangtise ai investment-logic --security-code <code>
+gangtise ai peer-comparison  --security-code <code>
+```
+
+- 都支持 A 股 / 港股
+- 返回 `{content: "markdown"}` — 直接呈现 content
+- 首次调用可能耗时数十秒，告知用户
+
+## 个股看点 `ai stock-summary`
+
+```bash
+gangtise ai stock-summary --security <code> [--security <code2> ...]
+gangtise ai stock-summary --security <aShares|hkStocks>
+```
+
+- `--security`（**必选**，可重复）：证券代码，单次最多 6000 个；**或**传市场关键词 `aShares`（全部 A 股）/ `hkStocks`（全部港股）
+- **仅支持 A 股和港股**
+- **积分**：`3`/条；个股若无看点总结则不在返回列表中，也不扣分
+- 返回字段：`securityCode` / `securityName` / `summary`（精炼投研总结）/ `date`（更新日期 `yyyy-MM-dd`）
+
+**示例：**
+```bash
+GANGTISE_TIMEOUT_MS=120000 gangtise ai stock-summary --security 600519.SH --security 00700.HK --format json   # 茅台 / 腾讯看点
+GANGTISE_TIMEOUT_MS=120000 gangtise ai stock-summary --security hkStocks --format json                        # 全部港股，total 2662
+```
+
+## 调研提纲 `ai research-outline`
+
+```bash
+gangtise ai research-outline --security-code <code>
+```
+
+- 仅 A 股
+- 返回 `{content: "markdown"}`
+
+## 业绩点评 `ai earnings-review`（异步）
+
+```bash
+gangtise ai earnings-review --security-code <code> --period <period> [--wait]
+gangtise ai earnings-review-check --data-id <id>
+```
+
+- `--period`：`年份+报告期`，如 `2025q3`（q1/interim/q3/annual），仅 A 股，覆盖最近 6 期
+- `--wait`（**推荐**）：阻塞等待到出结果（最长约 5 分钟：14 次指数退避轮询 5s→30s，累计 ≈316s）——**用它时把工具/命令超时设到 ≥360s**，否则外层先超时
+- 不带 `--wait` 的手动轮询：① `earnings-review` → 拿 `{dataId, status, hint}` → ② 间隔 ~30s `*-check`（预算 ~2-3 分钟）→ pending 继续 → 多次仍 pending 交用户稍后手动 check
+- 错误码：`410110` 生成中（继续等待）；`410111` 生成失败（终态，不重试）
+
+## 观点 PK `ai viewpoint-debate`（异步）
+
+```bash
+gangtise ai viewpoint-debate --viewpoint <text> [--wait]
+gangtise ai viewpoint-debate-check --data-id <id>
+```
+
+- `--viewpoint`：观点文本，**上限 1000 字**
+- 双向逻辑校验：看多→拆解风险，看空→挖反转
+- 异步流程同 earnings-review
+
+## 主题跟踪 `ai theme-tracking`
+
+```bash
+gangtise ai theme-tracking --theme-id <id> --date <yyyy-MM-dd> [--type <name>]
+```
+
+- `--theme-id`（**必选**）：用 `gangtise reference concept-search --keyword <主题名>` 查，取 `conceptId`（题材与主题共用 ID 体系）
+- `--date`：支持近 30 天
+- `--type`：`morning` 晨报 | `night` 晚报（不传返回两者）
+- **返回**：`[{type, date, content}, ...]` — 列表，每个元素是一份报告。某主题在指定日期可能只有一种类型（如只有晚报）或两种都没（空列表）。空结果不代表接口出错，建议换主题或换日期再试
+
+**示例：**
+```bash
+# 查"核电"主题 2026-05-09 的晚报
+GANGTISE_TIMEOUT_MS=120000 gangtise ai theme-tracking --theme-id 121000002 --date 2026-05-09 --type night --format json
+# 返回 [{"type":"night","date":"2026-05-09","content":"..."}]
+```
+
+## 热点话题 `ai hot-topic`
+
+```bash
+gangtise ai hot-topic [--start-date <date>] [--end-date <date>] [--category <name>] [--with-related-securities] [--no-with-related-securities] [--with-close-reading] [--no-with-close-reading] [--from <n>] [--size <n>]
+```
+
+- 结构化数据：驱动事件 / 投资逻辑 / 核心标的 / 话题精读
+- `--category`：`morningBriefing` 早报 | `noonBriefing` 午报 | `afternoonFlash` 盘中快报 | `eveningBriefing` 晚报（可重复，默认全部）
+- `--with-related-securities` / `--with-close-reading`：默认开启；`--no-with-related-securities` / `--no-with-close-reading` 显式排除（响应里相应字段置空）
+- 自动翻页，单页最大 20
+
+## 管理层讨论-财报 `ai management-discuss-announcement`
+
+```bash
+gangtise ai management-discuss-announcement --report-date <date> --security-code <code> --dimension <name>
+```
+
+- `--report-date`（**严格**）：仅接受 `xxxx-06-30`（半年报）/ `xxxx-12-31`（年报）
+- `--dimension`（**必选**）：`businessOperation` 业务经营与行业 | `financialPerformance` 财务与经营成果 | `developmentAndRisk` 发展规划与风险 | `all` 返回报告中完整的管理层讨论内容（内容可能过长，谨慎使用）
+- 返回 `content` 为字符串数组（每段一个元素）
+
+## 管理层讨论-业绩会 `ai management-discuss-earnings-call`
+
+```bash
+gangtise ai management-discuss-earnings-call --report-date <date> --security-code <code> --dimension <name>
+```
+
+- `--report-date`：接受 `xxxx-03-31` / `xxxx-06-30` / `xxxx-09-30` / `xxxx-12-31`
+- `--dimension`（**必选**）：`businessOperation` | `financialPerformance` | `developmentAndRisk`（注意：不支持 `all`，与财报版不同）
+- 返回 `content` 为字符串

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

@@ -0,0 +1,102 @@
+# Alternative 命令详细参数（行业指标数据库 EDB / 题材指数）
+
+> 本组覆盖 `/application/open-alternative/*`：行业指标数据库（EDB `edb-search` / `edb-data`）与题材指数画像（`concept-info` / `concept-securities`）。
+
+## 行业指标搜索 `alternative edb-search`
+
+```bash
+gangtise alternative edb-search --keyword <text> [--limit <n>]
+```
+
+- `--keyword`（**必选**）：关键词模糊匹配指标名称，如 `空调` / `空调销量` / `海尔`
+- `--limit`：返回条数上限，默认 100，最大 200
+- 返回字段：`indicatorId` / `indicatorName` / `dataSource` / `frequency` / `unit`
+- **用途**：在不知道 indicatorId 时先搜索，拿到 ID 后再调 `edb-data` 获取时序数据
+
+**示例：**
+```bash
+gangtise alternative edb-search --keyword 空调 --limit 50 --format table
+```
+
+## 行业指标时序数据 `alternative edb-data`
+
+```bash
+gangtise alternative edb-data --indicator-id <id> [--indicator-id <id2>] --start-date <date> --end-date <date>
+```
+
+- `--indicator-id`（**至少 1 个**，最多 10 个）：指标 ID，来自 `edb-search` 返回的 `indicatorId`，可重复传
+- `--start-date`（**必选**）：开始日期，格式 `yyyy-MM-dd`
+- `--end-date`（**必选**）：结束日期，格式 `yyyy-MM-dd`
+- 返回格式：列表，每行为 `{date, <indicatorId1>: value, <indicatorId2>: value, ...}`
+- 日期列为字符串（如 `"2010-01-31"`），数值列为字符串数字（如 `"447184.41"`）
+
+**典型流程：**
+```bash
+# Step 1: 找空调相关指标
+gangtise alternative edb-search --keyword 空调 --format table
+
+# Step 2: 拉 2024 年的时序数据
+gangtise alternative edb-data \
+  --indicator-id S14001618 \
+  --indicator-id S14001620 \
+  --start-date 2024-01-01 \
+  --end-date 2024-12-31 \
+  --format table
+```
+
+- `frequency` 决定数据的时间颗粒度（`日` / `周` / `月` / `季` / `年`）
+- 空值用 `null` 表示（某日期某指标无数据时）
+
+---
+
+## 题材指数基本信息 `alternative concept-info`
+
+```bash
+gangtise alternative concept-info --concept-id <id>
+```
+
+- `--concept-id`（**必选**）：题材指数 ID，如 `121000130`（机器人）
+- **如何拿 ID**：题材指数与主题（`ai theme-tracking --theme-id`）共用同一套 ID 体系，用 `gangtise reference concept-search --keyword <名称>` 查，取 `conceptId`（如 机器人 → `121000130`）。**绝不猜测**
+- 仅返回**最新截面**画像，不支持历史回溯
+- 默认 `--format json`（含大段文本，建议直接读字段）
+- 返回字段（单对象，非列表）：
+  - `conceptId` / `conceptName` — 题材 ID / 名称
+  - `definition` — 题材定义（核心定位与覆盖范围）
+  - `investmentLogic` — 投资逻辑（需求背景 / 技术临界点 / 产业链 / 风险点）
+  - `industrySpace` — 行业空间测算（全球 / 中国各时点市场规模）
+  - `competitiveLandscape` — 竞争格局（整机及核心细分头部玩家与份额）
+  - `keyEvents` — 催化事件列表 `[{date, content}]`，过去 1 年已发生 + 未来预期，最多 10 条，按时间倒序
+- **空值规范**：文本字段若题材未配置返回 `null`；`keyEvents` 无任何事件返回 `null`
+
+**示例：**
+```bash
+# 先查 ID
+gangtise reference concept-search --keyword 机器人 --format json
+# 再拉题材画像
+gangtise alternative concept-info --concept-id 121000130 --format json
+```
+
+## 题材指数成分股 `alternative concept-securities`
+
+```bash
+gangtise alternative concept-securities --concept-id <id>
+```
+
+- `--concept-id`（**必选**）：题材指数 ID，同上（`reference concept-search` 查）
+- 返回当前成分股，**按分组结构**组织（题材深度 F8）；仅最新截面，不支持历史回溯
+- 默认 `--format json`：成分股是 `securityDetail[].securityList[]` 两层嵌套，`table` / `csv` / `markdown` / `jsonl` 不会展开成逐只成分股（会把整个 `securityDetail` 压成单格/单行）；要逐只数据请用 json 自行解析分组
+- 返回字段（单对象）：
+  - `conceptId` / `conceptName` — 题材 ID / 名称
+  - `securityCount` — 成分股总数
+  - `securityDetail` — 分组数组 `[{groupName, securityList}]`，按 `groupName` 字母序
+    - `groupName` — 分组名（如 灵巧手 / 丝杠）
+    - `securityList` — 该组成分股 `[{securityCode, securityName, isKey, inclusionReason}]`
+      - `isKey` — 是否重点个股（`true` 排在组内前面）
+      - `inclusionReason` — 纳入理由，未配置返回 `null`
+- **排序**：组按 `groupName` 字母序；组内 `isKey=true` 优先，再按 `securityCode` 升序
+- **空值规范**：题材无成分股时 `securityDetail` 返回 `null`，`securityCount` 为 0，接口仍返回成功（`000000`）
+
+**示例：**
+```bash
+gangtise alternative concept-securities --concept-id 121000130 --format json
+```