gangtise-openapi-cli 0.25.0 → 0.27.0

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

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`**（误传触发 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 中提示；先核对日期是交易日、标的在覆盖范围，确认应有数据仍报错才按系统故障处理 |
+| `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`