gangtise-openapi-cli 0.26.0 → 0.28.0

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
+```

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

@@ -0,0 +1,108 @@
+# Fundamental 命令详细参数
+
+通用：所有命令都需 `--security-code`（如 `600519.SH`，注意是 `--security-code` 不是 `--security`）。`--field` 可重复，可用字段见 `references/fields.md`。
+
+---
+
+## A股三大报表（累计） `income-statement` / `balance-sheet` / `cash-flow`
+
+```bash
+gangtise fundamental <income-statement|balance-sheet|cash-flow> --security-code <code> [--start-date <date>] [--end-date <date>] [--fiscal-year <year>] [--period <p>] [--report-type <type>] [--field <name>]
+```
+
+- `--period`：`q1` | `interim` 中报 | `q3` | `annual` | `latest`（默认）
+- `--report-type`：`consolidated`（默认）| `consolidatedRestated` | `standalone` | `standaloneRestated`
+- `--fiscal-year` 可重复：`--fiscal-year 2023 --fiscal-year 2024`
+- `--start-date`/`--end-date` 有值时覆盖 `--fiscal-year`
+- **固定返回字段**（无需 `--field` 指定）：`securityCode` `companyName` `category` `announcementDate` `endDate` `fiscalYear` `period` `reportType` `companyType` `currency` `unit`
+
+**常用字段速查：**
+- 利润表：`totalOpRev` 营收 | `netProfit` 净利润 | `netProfitAttrParent` 归母 | `basicEPS` EPS | `rdExp` 研发
+- 资产负债表：`totalAssets` 总资产 | `totalLiab` 总负债 | `totalParentEq` 归母权益 | `monetaryAssets` 货币资金
+- 现金流：`netOpCashFlows` 经营 | `netInvCashFlows` 投资 | `netFinCashFlows` 筹资
+
+## A股三大报表（单季度） `income-statement-quarterly` / `cash-flow-quarterly`
+
+参数同累计，区别在返回单季度数据。`--period`：`q1` | `q2` | `q3` | `q4` | `latest`（默认）
+
+## 港股三大报表（中国会计准则） `income-statement-hk` / `balance-sheet-hk` / `cash-flow-hk`
+
+```bash
+gangtise fundamental <income-statement-hk|balance-sheet-hk|cash-flow-hk> --security-code <code> [--start-date <date>] [--end-date <date>] [--fiscal-year <year>] [--period <p>] [--report-type <type>] [--field <name>]
+```
+
+- **股票代码**：港股格式，如 `09992.HK`（5 位代码 + `.HK`）
+- `--period`：`q1` | `h1` 中报 | `q3` | `h2` 下半年报 | `nsd` 不规则跨度 | `annual` | `latest`（默认）
+- 其余参数与 A 股三大报表相同
+- **固定返回字段**：与 A 股相同，其中利润表/现金流增加 `startDate` 字段
+- 报表类型说明：
+  - `consolidated` 合并报表（首次发布原始值，默认）
+  - `consolidatedRestated` 合并报表（调整）：最新报告中对上年同期的修订
+  - `standalone` / `standaloneRestated` 母公司报表（及调整）
+
+**常用字段速查（港股利润表）：**
+- `totalOpRev` 营业总收入 | `opRev` 营业收入 | `netProfit` 净利润 | `netProfitAttrParent` 归母净利润 | `basicEPS` 基本每股收益 | `rdExp` 研发费用
+
+**常用字段速查（港股资产负债表）：**
+- `totalCurrAssets` 流动资产合计 | `totalNonCurrAssets` 非流动资产合计 | `totalAssets` 资产总计
+- `totalCurrLiab` 流动负债合计 | `totalNonCurrLiab` 非流动负债合计 | `totalLiab` 负债合计
+- `totalParentEq` 归母权益合计 | `totalEquity` 所有者权益合计 | `totalLAndE` 负债和权益总计
+
+**常用字段速查（港股现金流）：**
+- `netOpCashFlows` 经营活动现金流量净额 | `netInvCashFlows` 投资活动现金流量净额 | `netFinCashFlows` 筹资活动现金流量净额
+
+## 美股三大报表 `income-statement-us` / `balance-sheet-us` / `cash-flow-us`
+
+```bash
+gangtise fundamental <income-statement-us|balance-sheet-us|cash-flow-us> --security-code <code> [--start-date <date>] [--end-date <date>] [--fiscal-year <year>] [--period <p>] [--report-type <type>] [--field <name>]
+```
+
+- **股票代码**：美股格式，如 `TSLA.O`
+- `--period`：`q1` | `h1` 中报 | `q3` | `nsd` 不规则跨度 | `annual` | `latest`（默认），可重复——**美股无 `h2`**（区别于港股）
+- `--report-type`：`consolidated`（默认）| `consolidatedRestated` | `standalone` | `standaloneRestated`
+- `--field` 可重复，指定科目；留空返回完整报表
+- 其余参数（`--start-date` / `--end-date` / `--fiscal-year`）与 A 股三大报表相同
+- **不消耗积分**
+- 返回 `{total, list}`：每行一个报告期；留空 `--field` 返回完整报表，指定 `--field` 时只返回基础字段和所选科目；`companyType` 为企业类型名称，如 `一般企业` / `银行` / `保险` / `证券` / `REIT` / `其他`
+
+## 主营业务 `fundamental main-business`
+
+```bash
+gangtise fundamental main-business --security-code <code> [--breakdown <type>] [--start-date <date>] [--end-date <date>] [--period <type>] [--field <name>]
+```
+
+- `--breakdown`（默认 `product`）：`product` 按产品 | `industry` 按行业 | `region` 按地区
+- `--period`：`interim` 中报 | `annual` 年报（可重复）
+- 默认时间窗：`endDate` 当前日期、`startDate` 三年前
+- **不支持 `--fiscal-year`**（误传触发 `100001`/`100003`，旧 `900001`）；按年份筛选用 `--start-date`/`--end-date`
+
+## 估值分析 `fundamental valuation-analysis`
+
+```bash
+gangtise fundamental valuation-analysis --security-code <code> --indicator <name> [--start-date <date>] [--end-date <date>] [--limit <n>] [--field <name>] [--skip-null]
+```
+
+- `--indicator`（**必选**）：`peTtm` 滚动PE | `pbMrq` PB | `peg` PEG | `psTtm` 滚动PS | `pcfTtm` 滚动PCF | `em` 企业倍数
+- `--limit` 默认 2000，省略 `--start-date` 时自动查近一年
+- `--skip-null`：丢弃 `value`/`percentileRank` 为 null 的行（最新交易日可能未入库）
+
+## 盈利预测 `fundamental earning-forecast`
+
+```bash
+gangtise fundamental earning-forecast --security-code <code> [--start-date <date>] [--end-date <date>] [--consensus <name>]
+```
+
+- `--start-date` / `--end-date`：默认近一年
+- `--consensus` 可重复：`netIncome` 归母净利润 | `netIncomeYoy` 同比增速 | `eps` 每股收益 | `pe` 市盈率 | `bps` 每股净资产 | `pb` 市净率 | `peg` PEG | `roe` 净资产收益率 | `ps` 市销率
+- 返回结构：`{securityCode, securityName, updateList: [{date, fieldList: [{forecastYear, ...consensus}]}]}` — 每个日期固定返回 3 年预测（如 `2026E` / `2027E` / `2028E`）
+- **积分**：`0.5`/条（盈利预测是 `fundamental` 里唯一收费项，其余报表/主营/估值/股东均免费）
+
+## 前十大股东 `fundamental top-holders`
+
+```bash
+gangtise fundamental top-holders --security-code <code> --holder-type <type> [--start-date <date>] [--end-date <date>] [--fiscal-year <year>] [--period <p>]
+```
+
+- `--holder-type`（**必选**）：`top10` 前十大股东 | `top10Float` 前十大流通股东
+- `--period`：`q1` | `interim` | `q3` | `annual` | `latest`（默认），可重复
+- 返回字段：`reportPeriod` / `rank` / `shareholderName` / `shareholderType` / `holdingNum` / `holdingPct` / `chgNum` / `chgPct` / `shareCategory`

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

@@ -0,0 +1,136 @@
+# Indicator 命令详细参数（数据指标 EDE：证券级指标截面 / 时序）
+
+> 本组覆盖 `/application/open-indicator/EDE/*`：证券级**数据指标**的检索与取数（收盘价、成交量、总市值、财务指标等，按个股取值）。
+> 与 `alternative edb-*`（EDB 行业/宏观指标，无证券维度）是两套接口，别混。
+>
+> **取数前先 `indicator search` 拿 `indicatorCode`**，绝不猜测指标编码。
+
+## 指标搜索 `indicator search`
+
+```bash
+gangtise indicator search --keyword <text> [--limit <n>]
+```
+
+- `--keyword`（**必选**）：按指标名称模糊匹配。用具体词，如 `收盘价` / `成交量` / `营业收入` / `总市值`，**不能用整句白话**（"我想查茅台的收盘价" ✗）
+- `--limit`：返回条数上限，默认 50，最大 100
+- 默认 `--format table`（看 `indicatorCode` / `indicatorName` / `description` 即可）；要看每个指标支持哪些参数（`parameterList`），用 `--format json`
+- 返回字段：`indicatorCode` / `indicatorName` / `description`（算法）/ `parameterList`（可传的 `--indicator-param` 参数及枚举）/ `score`（`scope` 适用市场/品种字段服务端当前多返 `null`）
+- **市场范围**：指标数据覆盖 A 股 / 港股 / 美股（2026-07 起扩展，此前仅 A 股）。美股代码用交易所后缀 `.O`(NASDAQ) / `.N`(NYSE)，**不是 `.US`**——实测 `AAPL.US` 查不到数据，须用 `AAPL.O`（官方示例里的 `AAPL.US` 是笔误）
+
+```bash
+gangtise indicator search --keyword 收盘价 --limit 5 --format json   # 看 parameterList
+```
+
+## 指标截面数据 `indicator cross-section`
+
+```bash
+gangtise indicator cross-section --indicator <code> [--indicator <code2>] \
+  --security <code> [--security <code2>] --date <yyyy-MM-dd> \
+  [--currency <c>] [--scale <s>] [--indicator-param <spec>]
+```
+
+- `--indicator`（**至少 1 个**）：指标编码，来自 `search`，可重复传多个
+- `--security`（**至少 1 个**）：证券代码，如 `600519.SH`（A股）/ `09992.HK`（港股）/ `AAPL.O`（美股，用 `.O`/`.N` 后缀，非 `.US`），可重复传多个
+- `--date`（**必选**）：数据日期 `yyyy-MM-dd`（须为交易日，非交易日/无数据日返回空）
+- `--currency`：币种 `DFT`(原始,默认)/`CNY`/`HKD`/`USD`/`EUR`/`GBP`/`JPY`/`TWD`/`MOP`/`AUD`
+- `--scale`：量纲 `0`(个,默认)/`3`(千)/`4`(万)/`6`(百万)/`8`(亿)/`9`(十亿)
+- **支持多指标 × 多证券**（单日横截面）
+- **输出（宽表）**：每行一只证券，列为 `date / security / name / <各指标名>…`
+
+```bash
+gangtise indicator cross-section \
+  --indicator qte_close --indicator qte_vol --indicator qte_mkt_cptl \
+  --security 600519.SH --security 09992.HK \
+  --date 2026-05-18 --format table
+# date        security   name   日收盘价  成交量      总市值
+# 2026-05-18  600519.SH  贵州茅台  1323   4966097   1656753494445
+# 2026-05-18  09992.HK   泡泡玛特  150.7  15301079  20209520.2705
+```
+
+## 指标时间序列 `indicator time-series`
+
+```bash
+gangtise indicator time-series --indicator <code> [--indicator <code2>] \
+  --security <code> [--security <code2>] --start-date <date> --end-date <date> \
+  [--calendar-type <ND|TD|WD>] [--currency <c>] [--scale <s>] [--indicator-param <spec>]
+```
+
+- `--indicator` / `--security`：同上，但**只允许「多指标 × 单证券」或「单指标 × 多证券」**，不能两边都多个（要多 × 多用 `cross-section`，否则报 `410001`）
+- `--start-date` / `--end-date`（**均必选**）：区间端点 `yyyy-MM-dd`
+- `--calendar-type`：日期类型 `ND`(自然日)/`TD`(交易日,默认)/`WD`(工作日)
+- `--currency` / `--scale`：同 `cross-section`
+- **输出（宽表）**：每行一个日期，列为 `date / <各序列名>…`；序列在「单证券」时是各**指标**，在「多证券」时是各**证券**
+
+```bash
+# 多指标 × 单证券：列 = 指标
+gangtise indicator time-series --indicator qte_close --indicator qte_vol \
+  --security 600519.SH --start-date 2026-05-18 --end-date 2026-05-22
+# date        日收盘价    成交量
+# 2026-05-18  1323     4966097 ...
+
+# 单指标 × 多证券：列 = 证券
+gangtise indicator time-series --indicator qte_close \
+  --security 600519.SH --security 09992.HK --start-date 2026-05-18 --end-date 2026-05-22
+# date        贵州茅台    泡泡玛特
+# 2026-05-18  1323     150.7 ...
+```
+
+## 复权 / 指标专属参数 `--indicator-param`
+
+通用的币种/量纲用 `--currency` / `--scale`；指标**专属**参数（如行情复权方式）用 `--indicator-param`，格式 `指标code:参数key=值`，可重复：
+
+```bash
+# 茅台收盘价后复权（adjustmentType=3）
+gangtise indicator cross-section --indicator qte_close --security 600519.SH \
+  --date 2026-05-18 --indicator-param "qte_close:adjustmentType=3"
+#   不复权 1323 → 后复权 11487.0308
+```
+
+- `adjustmentType`（复权方式）：`1`=不复权 `2`=前复权 `3`=后复权 `4`=定点复权
+- 同一指标多个参数 → 重复 `--indicator-param "code:k1=v1" --indicator-param "code:k2=v2"`
+- 某指标支持哪些 `paramKey` 及其枚举值，用 `indicator search --format json` 看该指标的 `parameterList`（**参数 key 与取值（含大小写）均以 search 返回为准**——如 `currency` 在 parameterList 中可能为小写 `dft`/`cny`）
+- `--indicator-param` 与根级 `--currency`/`--scale` 冲突时，以 `--indicator-param` 为准
+
+## 必填参数与错误码（取数前必读）
+
+截面/时序**单元格级缺值返回 `null`**（证券行保留、不丢行）；但**整个查询无数据时仍会报 `999999` + HTTP 500**（节假日 / 未来日期 / 未覆盖标的，2026-07-11 实测）。取数报错主要是这几个码：
+
+| 错误码 | 实际含义 | 怎么办 |
+| :--- | :--- | :--- |
+| `410001` | 入参错误：没传指标/证券，或 `time-series` 传了「多指标 × 多证券」 | 补齐 `--indicator`/`--security`；多 × 多改用 `cross-section` |
+| 缺参报错（曾为 `410106`） | **缺必填参数**：服务端现已直接指明缺哪个，如「指标 X 的必填参数 periodNum(期数) 不能为空」（仍以 HTTP 500 返回，CLI 重试 2 次后透出该消息） | 读 `search --format json` 的 `parameterList`，把 `required:true` 的参数用 `--indicator-param` 补上 |
+| `999999` | **多为整查询无数据**（节假日 / 未来日期 / 未覆盖标的；单元格级缺值才是 `null`），也可能是真系统故障——服务端不区分两者 | CLI 对 indicator 端点**不重试此码**（v0.27.0）并在 hint 中提示；先核对日期是交易日、标的在覆盖范围，确认应有数据仍报错才按系统故障处理 |
+| `130001`（旧 `410004`） | 数据未找到，或**该指标无权限**（内层信封失败会带具体 msg，如"指标无权限"；此码被服务端复用） | 检查查询条件与指标权限；换证券/日期仍失败多为无权限，联系管理员开通 |
+
+### 必填参数（`410106` 的根因）
+
+相当一部分指标默认调用就报 `410106`，因为有必填参数没传。**取数前先 `search --format json` 看 `parameterList`，凡 `required:true` 的都用 `--indicator-param "指标code:参数=值"` 补上。** 三类高频必填参数：
+
+| 参数 | 适用指标 | 示例 |
+| :--- | :--- | :--- |
+| `periodNum` | N 期统计（N 期均值/最值，如 `finc_roe_avg_avg` 平均ROE N期均值） | `--indicator-param "finc_roe_avg_avg:periodNum=4"` |
+| `startDate` | 区间/周期类，整数 `YYYYMMDD`（含全部 `qte` 周期变体，如 `qte_amp_mo` 月振幅、换手率） | `--indicator-param "qte_amp_mo:startDate=20260401"` |
+| `fiscalYear` | 年度/报告期类（如 `div_cash_yr` 年度现金分红） | `--indicator-param "div_cash_yr:fiscalYear=2025"` |
+
+> `paramValue` 一律按**字符串**约定传（`periodNum=4` 内部即 `"4"`，CLI 已处理）。
+
+## 取数最佳实践
+
+- **先 search 看 parameterList**：一步拿到 code、必填参数（required）、专属参数枚举（`adjustmentType`/`scale`/`currency` 等）。
+- **公司类型决定有没有这个科目**：财务科目分公司类型——银行有「存放同业」、券商有「客户资金存款」、保险有「预收保费」，一般企业没有。某指标对茅台返回 `null`（无此科目），换到对应类型证券（招行/中信/平安）就有数。
+- **日期路由**：
+  - 财务类（`bs_`/`is_`/`cf_`/`finc_`/`div_`/`shr_` 等）→ 用**报告期末**（Q1 `2026-03-31`、年报 `2025-12-31`）
+  - 现金流量表附注/间接法科目（多数 `cf_`）→ **只在年报/半年报披露**，季报日期取不到，改用年报日期 `2025-12-31`
+  - 行情/基本资料（`qte_`/`pty_`/`scr_`/`frcst_`）→ 用**交易日**
+- **探索性取数**：截面与时序现在对无数据都优雅处理（截面返 `null` 单元格、时序返空行），都适合"先看有没有数"；看趋势仍优先 `time-series` + 覆盖报告期的区间。
+- **名称反查 code 要核对，别取首条**：存在同显示名的兄弟指标——单季 `cf_finc_exp_qtr` 与累计 `cf_finc_exp` 都叫「财务费用」，`bs_fmt`/`cf_fmt`/`is_fmt` 都叫「报表格式」。`search` 按名称模糊匹配，目标 code 高概率在 top1 但不绝对，要看 `indicatorCode` 确认。
+- **批量查询做失败拆分**：某指标**缺必填参数**或入参错误时会整批报错（无数据不会——按 `null` 返回），逐指标单查能定位是哪个指标缺参/不可查。
+- **市值量纲（实测 2026-07）**：`qte_mkt_cptl`（总市值）**仅 A 股**——港股/美股返 `null`（换 `currency` 也没用，是 scope 外 ≠ 无数据）；**默认返原始「元」**（茅台 ≈ `1.5e12`，即 1.5 万亿），别误当天文数字。用 `scale` 数字码缩放（`0`元 / `3`千 / `4`万 / `6`百万 / `8`亿 / `9`十亿——`scale=8` → `15038` 亿元）、`currency` 换币种（`dft`本币 / `cny` / `hkd` / `usd` …）。**跨证券比市值前先统一 `scale`+`currency`**。
+
+## 通用说明
+
+- **发现流程**：`indicator search`（拿 code + 看 parameterList）→ `cross-section` / `time-series` 取数
+- **积分**：`search` 免费；`cross-section` / `time-series` 按单元格计费（A 股 0.05 / 港股 0.1 / 美股 0.2 积分每 100 单元格，不足 100 按 100）
+- **空结果**：日期区间无数据时返回空表（不报错），换交易日/有效区间重试
+- **数据权限**：试用账号默认可取近 3 年；正式账号按服务等级
+- 所有格式（table/json/jsonl/csv/markdown）均可用；导出宽表给 Excel 直接用 `--format csv --output xxx.csv`

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

@@ -0,0 +1,188 @@
+# 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
+- **积分**：list 0.1/条；download 10/篇
+
+## 外资研报 `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`**（否则返回 `100003`，msg 为「securityCode不可为空」；2026-07-20 实测）
+- `--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`