gangtise-openapi-cli 0.51.0 → 0.52.0

package/gangtise-openapi/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: gangtise-openapi
-version: "0.51.0"
+version: "0.52.0"
 description: |-
   通过 gangtise CLI 直接调用 Gangtise OpenAPI，拉取投研原始数据、批量导出、下载文件、调用 AI 能力。
 
-  **触发词**：Gangtise / 冈底斯 / 岗底斯 / gtIC（Gangtise 语音误识别）/ 调接口 / CLI / openapi / 导出 / 下载研报 / 批量查 / 拉数据 / 跑一下 / 研报 / 纪要 / 公告 / K线 / 财报 / 估值 / 选股 / 债券 / 基金 / ETF / 自选股 / 股票池 / 个股笔记
+  **触发词**：Gangtise / 冈底斯 / 岗底斯 / gtIC（Gangtise 语音误识别）/ 调接口 / CLI / openapi / 导出 / 下载研报 / 批量查 / 拉数据 / 跑一下 / 研报 / 纪要 / 公告 / 海外观点 / K线 / 财报 / 估值 / 选股 / 债券 / 基金 / ETF / 自选股 / 股票池 / 个股笔记
 
-  **适用**：原始数据导出、批量 jsonl/csv、下载 PDF/MD、行情 K 线、财务报表、估值指标、证券级数据指标（EDE 截面/时序/条件选股）、财报日历（业绩预告/快报/公告）、会议线索、帕米尔专家纪要、资金流向、题材与板块、指数成分权重、债券（资料/行情/估值/评级/公告/违约）、公募基金（资料/净值/费率/经理/规模/持有人/持仓与配置/ETF 申赎）、联网搜索、PDF 解析为 Markdown、AI 能力（一页通/投资逻辑/同业对比/个股看点·投研总结/投研线索/AI 专家情报/业绩点评/观点PK·多空辩论/主题跟踪/热点话题/管理层讨论/管理层情绪/调研提纲/知识库搜索）、云盘文件管理、群消息与群文件下载、股票池、个股笔记（Vault）
+  **适用**：原始数据导出、批量 jsonl/csv、下载 PDF/MD、行情 K 线、财务报表、估值指标、证券级数据指标（EDE 截面/时序/条件选股）、财报日历（业绩预告/快报/公告）、会议线索、帕米尔专家纪要、海外观点（海外媒体 / 投资人账号帖子 + 中文翻译）、资金流向、题材与板块、指数成分权重、债券（资料/行情/估值/评级/公告/违约）、公募基金（资料/净值/费率/经理/规模/持有人/持仓与配置/ETF 申赎）、联网搜索、PDF 解析为 Markdown、AI 能力（一页通/投资逻辑/同业对比/个股看点·投研总结/投研线索/AI 专家情报/业绩点评/观点PK·多空辩论/主题跟踪/热点话题/管理层讨论/管理层情绪/调研提纲/知识库搜索）、云盘文件管理、群消息与群文件下载、股票池、个股笔记（Vault）
 
   **不适用**：不脱离 OpenAPI 自行撰写研报、编造投研结论或做自由问答——观点总结、多空 PK 等 AI 产物本 skill 只经由 Gangtise 平台 AI 接口获取，不自行生成
 
@@ -24,7 +24,7 @@ description: |-
 
 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`；板块 → `reference sector-search`；券商 / 牵头 / 观点机构 → `reference institution-search`（按返回的 `usageScopes` 选能喂给目标参数的 ID）。**绝不猜测**。
-3. **公司名 → 证券代码**：先查下方速查表（几只常用大盘股），其余一律 `gangtise reference securities-search --keyword <名> --category stock`，取第一条 `category` 为 `stock` 的 `gtsCode`（按简称查时同名可转债可能排在前面）。
+3. **公司名 → 证券代码**：先查下方速查表（几只常用大盘股），其余一律 `gangtise reference securities-search --keyword <名> --category stock`，取第一条 `category` 为 `stock` 的 `gtsCode`（不带 `--category` 时，按简称查同名可转债可能排在前面）。
 4. **时间格式**：datetime `"YYYY-MM-DD HH:mm:ss"`（引号包裹），date `YYYY-MM-DD`（`YYYY/MM/DD`、`YYYYMMDD` 也收，会归一；**年在后写法一律拒绝**）；`--indicator-param` 里 `reportDate` / `tradeDate` 等以 `Date` 结尾的值同样适用。
 5. **多值参数**：优先重复传（最稳、最明确）：`--security 600519.SH --security 000858.SZ`。代码 / ID / 字段名类参数也接受半/全角逗号、顿号、分号或空格分隔（语音输入容错），重复值自动去掉；名称类（`--manager` / `--issuer` / `--room-name` / `--knowledge-name`）只按逗号分隔，名称里的空格和顿号原样保留。**只收一个值的参数（如 `--security-code`）重复传会直接报错**，不会只取最后一个。
 6. **K 线"最近 N 条"**：必须用 `--start-date`/`--end-date` 拉日期范围，从结果按 `tradeDate` 取尾部最近 N 条。**不要只用 `--limit N`**（截取的是窗口开头）。
@@ -36,8 +36,8 @@ description: |-
    - K 线全市场关键字（`aShares` / `hkStocks` / `usStocks`；旧命令 `all`）跨日期 → 自动按日切片并合并，粒度按各市场单日行数定（A 1 个工作日 / 港 2 个工作日 / 美 1 个工作日）
    - 5xx / `429` / 网络错误 / `999999` → 自动指数退避重试（🔴 贵档端点例外：仅连接失败 / 429 / token 自愈重试，5xx/超时不重放防重复扣分；`indicator` 端点对 `999999` 不重试）
    - Token 失效 → 自动换用已刷新的 token 或重新登录，再重发；凭证错 `999011` → **不重试**（AK/SK 不对不会自己好），查环境变量
-8. **参数命名差异**：`--security-code` 只用于 **Fundamental 全组、AI 单证券生成类**（`one-pager` / `investment-logic` / `peer-comparison` / `earnings-review` / `research-outline` / `management-discuss-*`）**与 `insight qa list`**；`ai security-clue` 用 `--gts-code`；`fund manager-info` 按人名查、用 `--manager`；其余（Insight 其他命令、Quote、Vault、Bond、Fund、Indicator、`ai stock-summary`、`ai management-sentiment-indicator` / `-conclusion`、`ai expert-intel`）一律用 `--security`；`reference index-weight` 的指数代码用 `--index`。
-9. **调试**：`--verbose` 或 `GANGTISE_VERBOSE=1` 打印每个请求的耗时/字节数到 stderr。
+8. **参数命名差异**：`--security-code` 只用于 **Fundamental 全组、AI 单证券生成类**（`one-pager` / `investment-logic` / `peer-comparison` / `earnings-review` / `research-outline` / `management-discuss-*`）**与 `insight qa list`**（这些命令写 `--security` 也认，只收一个代码）；`ai security-clue` 用 `--gts-code`；`fund manager-info` 按人名查、用 `--manager`；其余（Insight 其他命令、Quote、Vault、Bond、Fund、Indicator、`ai stock-summary`、`ai management-sentiment-indicator` / `-conclusion`、`ai expert-intel`）一律用 `--security`；`reference index-weight` 的指数代码用 `--index`。
+9. **调试与省 token**：`--verbose` 或 `GANGTISE_VERBOSE=1` 打印每个请求的耗时/字节数到 stderr；`--dry-run` 打印命令将发出的第一个请求（端点、请求体、单价、最多扣多少积分）后退出 0，**不发请求、不需要凭证**——核对参数映射或估算花费时用（删除类预览不需要 `--yes`，`needsYes: true` 表示真正执行要加）；`--columns a,b,c` 只保留这几列（按此顺序，所有格式都生效），列名写错会在 stderr 列出实际有的列；带它的 `jsonl` / `csv --output` 导出先在内存里收齐再写，大导出别加。
 10. **`--field` 字段名必须核对，不确定就别传**（返回全量最稳）。上游对不存在的字段名：`quote` 系（realtime / day-kline / minute-kline / fund-flow）名和值一起丢、不报错——CLI 比对请求与返回的列名，缺列标 `partial` + `missingFields` 并退出 3；`fundamental main-business` / `valuation-analysis`、`quote sector-fund-flow` 报 `100005`、`bond` / `fund` 报 `100003`，都会点名写错的名字。CLI 另检查每行的值个数与字段数，对不上直接报错退出 1，报障时带上报错末尾的 `（trace …）`。多只证券或全市场时，缺的身份列 CLI 会补到最前（日 K 补 `securityCode` / `tradeDate`、分钟 K 补 `securityCode` / `tradeTime`、realtime 补 `securityCode`）；单只不补。realtime **无 `close`**（用 `latestPrice`）、**无市值**（总市值走 `indicator cross-section --indicator qte_mkt_cptl`，A/港/美股均有数）。
 11. 🔴 **EDE（`indicator` 截面 / 时序 / 选股）取不到数返 `null` 占位、行列都保留、退出码 0**；代码写错才报 `100003` 并指名。报告期类指标（`is_*` 等）的日期一律落**报告期末**（`03-31` / `06-30` / `09-30` / `12-31`），截面用 `--indicator-param "<指标code>:reportDate=YYYY-MM-DD"`（`screener` 用 `"F1:reportDate=..."`）——日期不在报告期末时整批 `null`，`screener` 筛出空集是**日期用错，不是没有符合条件的标的**。时序与交易日类指标混查、或显式传 `ND` / `TD` / `WD` 时，报告期类指标只有报告期末那几行是真值，**别对整列直接求均值 / 求和**。**`--calendar-type` 默认别传**（服务端按指标定日期轴：行情类给交易日、报告期类给报告期、混查给两者并集——单独查报告期类指标时区间要含报告期末，否则返回空结果；显式传 `TD` 时报告期类指标落在非交易日的报告期末那几期整期缺失、不报错，其余几期照常有值，看着像正常数据；一致预期 `frcst_*` 要节假日也有值的逐日序列才传 `ND`）。详见 `references/commands/indicator.md`。
 
@@ -53,7 +53,7 @@ description: |-
 - 凭证：`gangtise auth status` 只看本地（缓存的 token、`GANGTISE_TOKEN`），不联服务端。两项都没有、环境变量里也没配 `GANGTISE_ACCESS_KEY` / `GANGTISE_SECRET_KEY` → 提示配置 AK/SK 并中止；**只配了 AK/SK 时首次调用会自动登录，不算未登录**。要确认凭证有效或账号状态，用 `gangtise auth login`
 - 多个命令同时匹配 → 复述理解让用户挑（如"搜索研报" → 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 detail` / `--with-content` 批量取正文、`concept-info --full` 500/次）→ 先估总积分告知用户再执行（单价见下「积分计费速查」）
+- **高积分操作先确认**：任何 50 积分/次及以上、或"按条 × 大批量"（如 `stock-summary` 按代码批量数千只、`opinion detail` / `--with-content` 批量取正文、`concept-info --full` 500/次）→ 先估总积分告知用户再执行（单价见下「积分计费」与 `references/billing.md`）
 - 下载**必选**格式未定才问：`independent-opinion --file-type`（必选）、`vault record/my-conference --content-type`（record 三种 original/asr/summary、my-conference 两种 asr/summary）；其余 download 有默认（多为 `1`=PDF/原始），用户没提格式就用默认、不必问
 - list→download 用户没指定具体文件 → 展示前 10 条让用户挑
 - 🔴 **改动账号数据的命令**（其余命令都只读）：
@@ -68,146 +68,23 @@ description: |-
 - opaque ID → 先 `references/lookup-ids.md`
 - 模糊时间词 → 查"时间词映射"
 - 列表类命令用户没要求全量 → 按单价主动加 `--size` 兜底（不必问）：免费或 0.1 积分/条的列表用 `--size 200`；**≥1 积分/条的（观点、独立观点、路演四件套、会议线索、个股线索、热点话题、管理层情绪、AI 专家情报等）用 `--size 20`**，要更多先 `--size 1` 看 stderr 的 `Total` 估总价再定。CLI 省略 `--size` 会拉全量；按条计费的列表估算全量超过 1000 积分时报错退出（报错里有估算积分），此时把估算积分告诉用户，确认后加 `--yes` 重跑或改传较小的 `--size N`。**显式 `--size` 本身估算超过 1000 积分也同样拦截**（别用 `--size 100000` 当「全量」绕过），`fundamental earning-forecast` 按日期区间估算、同一条线
-- 预估结果 >200 行 → 别全量 `--format json` 引进上下文，改 `--format jsonl --output <file>` 落盘（行边取边写、内存不随行数增长，stdout 只回显文件路径），再 `wc -l` + `head` 采样呈现。落盘的 `csv` / `jsonl` 旁边会有 `<file>.meta.json`：`complete` / `rows` / `result.partial` 与缺失项标记都在里面，转交文件时一并给、核验完整性先看它（`complete: false` = 那次导出退出码 3）
+- 预估结果 >200 行 → 别全量 `--format json` 引进上下文，改 `--format jsonl --output <file>` 落盘（行边取边写、内存不随行数增长——加了 `--columns` 时除外，stdout 只回显文件路径），再 `wc -l` + `head` 采样呈现。落盘的 `csv` / `jsonl` 旁边会有 `<file>.meta.json`：`complete` / `rows` / `result.partial` 与缺失项标记都在里面，转交文件时一并给、核验完整性先看它（`complete: false` = 那次导出退出码 3）
 - 路由到 AI 同步生成命令 → 同步生成类（`one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `theme-tracking` / `management-discuss-*`）CLI 已内置 120s 超时下限，无需前缀；`stock-summary` 同样有 120s 下限；`hot-topic` 仍建议前置 `GANGTISE_TIMEOUT_MS=120000`。**贵档端点超时/5xx 不自动重试**（重放=重复扣分）——超时报错后内容可能已在服务端生成并扣费，同参数再调仍会**再扣一次**（无缓存豁免），所以一次调用给足超时比失败重跑省钱。`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 / performance-calendar 的 list、`vault my-conference-list`；`insight report-image download` 0.1/张
-- **按条（观点/含详情类 list）**：`ai security-clue` 5；`ai management-sentiment-indicator` / `-conclusion` 5；roadshow/site-visit/strategy/forum list 10；independent-opinion list 1；**opinion / foreign-opinion list 1（只含摘要 `brief`）**，要正文用 `detail` 30/条或 `list --with-content` 30/条；`fundamental earning-forecast` 0.5；`ai stock-summary` 1（无看点的证券不返回也不扣）；`alternative edb-data` 30/指标
-- **各 download（/篇）**：official-account / research 10；announcement 1；announcement-hk / announcement-us 2；independent-opinion / summary / foreign-report / my-conference 30；`performance-calendar download` A 股 1 / 港美股 2
-- **0.4 的 `bond` 系**：`bond` 全部命令 **0.4/次**（按次，与返回行数无关），三个例外按量计：`rating-overview` 0.4/**条**、`rating-change` 0.4/**只有数据的债券**、`issuer-rating-change` 0.4/**个发行人**
-- **0.4 的 `fund` 系**：`fund` 全部命令 **0.4/次**（按次，与返回行数、基金只数无关）——多只基金合并成一次调用最省
-- **`tool web-search` 1/次**（按次，与返回条数、是否带 `--include-content` 无关；零结果与报错不扣）
-- 🔴 **`insight highlight list` 5/条**——**按返回条数计**，`--size 20` 的一页 = 100 积分。省略 `--size` 时 CLI 先估算，超过 1000 积分（约 200 条）报错退出，要全量须加 `--yes`
-- 🔴 **`ai expert-intel` 20/条**——**按返回条数计**，`--size 20` = 400 积分，一整页（50 条）= 1000 积分。省略 `--size` 时 CLI 先取 1 条拿总数再估算，超过 1000 积分（50 条）报错退出，要全量须加 `--yes`；先用 `--security` / `--tag` / 时间收窄
-- **按页**：`tool file-parse` 0.8/页，**提交（`--file`）时按实际页数一次性扣**，取结果（`file-parse-check`）免费——50 页 PDF = 40 积分，别重复提交同一文件
-- 🔴 **按次**：`ai knowledge-batch` 10、`management-discuss-earnings-call` 10、`management-discuss-announcement` 5、`management-sentiment-detail` 10；AI Agent `one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `theme-tracking` **10/次**，`earnings-review` / `viewpoint-debate` **20/次**
-- 🔴 **`ai hot-topic` 10/篇，按返回条数计**（不是按调用次数）。📌 **一「篇」= 一整份报告**（一份早报 / 午报 / 盘中快报 / 晚报），**不是报告里的一条话题**——一份报告通常包含多条热点话题。所以 `--size 20` 的一页 = 最多 20 份报告 = 200 积分，**先用 `--start-date`/`--end-date` + `--category` 收窄再拉**，别省略 `--size` 直接全量。**可查的历史范围是前溯 3 个月**（各档相同）——超出范围的日期返回空结果而不是报错，拿到空先想想是不是撞了权限窗口
-- **题材**：`alternative concept-info` / `concept-securities` **50/次**；🔴 加 `--full`（催化事件 / 重点个股标识 / 纳入理由）走旧版 **500/次**，不需要这几列就别加
-- ✅ **扣费发生在接口成功返回数据之后**（平台计费规则）：没查到内容（空结果）、报错都不扣分——各 download、`ai hot-topic`（10/篇）、`ai stock-summary`（1/条，无看点总结的个股不进返回列表也不计费）、AI 生成类（`one-pager` 等 10～20/次），以及按次计费的 `ai knowledge-batch`、题材、`tool web-search` 都是这样。**所以「先小范围试探再放大」是安全的**——先用窄条件确认能查到东西，再扩范围。⚠️ **「成功返回」按服务端算**：超时报错时服务端可能已经生成并返回了内容（只是客户端没收到），这次已经扣过，同参数重调会再扣一次；异步的 `earnings-review` / `viewpoint-debate` 在提交成功（拿到任务 ID）时就扣，之后生成失败不退。**单价未公布的** `pamirs-summary`（见下）别据此假定
-- ⚠️ **同参数重复调用不免费**：按次计费的那批无缓存命中豁免（`one-pager` 等生成类重复调用每次扣分，即使秒回缓存内容）；**按篇/按条的也一样**——重拉同一批 `hot-topic` 就是按条数再计一次费。生成类与列表结果拿到后自行留存复用，别为「刷新」重调
-- ⚠️ **这些端点超时 / 5xx 不自动重放**（共 68 个，完整清单见下方注释块：按次计费的 AI Agent 那批、`ai knowledge-batch` / `management-discuss-*` / `management-sentiment-detail` / `hot-topic`、题材两接口（含 `--full`）、`bond` 与 `fund` 全部命令、`tool web-search`、`tool file-parse` 提交；summary / foreign-report / my-conference 三个 download；按条计费的 `insight highlight list`、`ai expert-intel`、观点 `detail` / `list --with-content`、`ai stock-summary` 与 `fundamental earning-forecast`；以及不计分但重放有副作用的 `vault stock-pool-create`、`vault stock-note-add` 与云盘上传 / 新建文件夹 / 复制 / 删除）。仅连接失败、429 与 token 自愈会重试。服务端可能已经执行并计费，重放会重复扣分、多建一份或把成功报成失败——**一次调用给足超时比失败重跑省钱**
-
-<!-- no-replay-endpoints
-     上面那句点名的「不重放」端点，完整清单如下（endpoint key，与 `gangtise raw list` 一致）：
-ai.earnings-review.get-id
-ai.expert-intel.list
-ai.hot-topic
-ai.investment-logic
-ai.knowledge-batch
-ai.management-discuss-announcement
-ai.management-discuss-earnings-call
-ai.management-sentiment-detail
-ai.one-pager
-ai.peer-comparison
-ai.research-outline
-ai.stock-summary.list
-ai.theme-tracking
-ai.viewpoint-debate.get-id
-alternative.concept-info
-alternative.concept-info-full
-alternative.concept-securities
-alternative.concept-securities-full
-bond.announcement
-bond.basic-info
-bond.cash-flow
-bond.daily-quote
-bond.default-list
-bond.exercise-notice
-bond.issuance-detail
-bond.issuance-plan
-bond.issuer-info
-bond.issuer-rating-change
-bond.rating-change
-bond.rating-overview
-bond.valuation
-fund.asset-allocation
-fund.asset-size
-fund.basic-info
-fund.bond-portfolio
-fund.bond-type-allocation
-fund.etf-pcf-components
-fund.etf-pcf-header
-fund.etf-share-change
-fund.fee-rate
-fund.fund-portfolio
-fund.fund-type-allocation
-fund.holder-structure
-fund.industry-allocation
-fund.manager-history
-fund.manager-info
-fund.nav
-fund.stock-portfolio
-fund.top10-holders
-fundamental.earning-forecast
-insight.foreign-opinion.detail
-insight.foreign-opinion.list-with-content
-insight.foreign-report.download
-insight.highlight.list
-insight.opinion.detail
-insight.opinion.list-with-content
-insight.pamirs-summary.download
-insight.summary.download
-tool.file-parse.submit
-tool.web-search
-vault.drive.copy
-vault.drive.create-folder
-vault.drive.delete-file
-vault.drive.delete-folder
-vault.drive.upload
-vault.my-conference.download
-vault.stock-note.add
-vault.stock-pool.create
--->
-- **按单元格**：`indicator cross-section` / `time-series` / `screener`（A股 0.05 / 港股 0.1 / 美股 0.2 积分每 100 单元格；screener 按**筛选前**范围 × 指标数保守估算，实际以平台账单为准，见 `indicator.md`）；`ai knowledge-resource-download` 按下游资源计费
-  - 🔴 截面 / 时序另有**单次 30000 单元格硬上限**（截面 = 证券数 × 指标数，时序 = 序列数 × 日期数），超出报 `100006`、不返回部分结果——按这个乘积拆批。板块 ID 会展开成全部成分股，实际证券数常远超写进命令的条数
-- **单价未公布**：`insight pamirs-summary list` / `download`——spec 只写了「需购买专家纪要数据库」这个准入门槛，没给单次价格。**别据此假定免费**；大批量拉取前先小量试，或向平台确认
-
-### 数据范围（能查多久）
-
-官方权限表的正式账号与试用账号口径（Plan 基础版同试用，高级版介于两者之间）。个别账号权限更大，以实际返回为准——**规划查询区间按下表，别自行缩短**：
-
-| 命令 | 正式账号 | 试用账号 |
-|------|------|------|
-| `quote day-kline` / `fund-flow` | **5 年** | 3 年 |
-| `quote sector-fund-flow` | 官方权限表未列；可能短于 `fund-flow`，长区间先试最早一段 | 同左 |
-| `quote minute-kline` | **1 个月**（随日期滚动） | 1 个月 |
-| `quote realtime` | 最新快照 | 最新快照 |
-| `fundamental` 三大报表（A / 港 / 美）/ `main-business` / `valuation-analysis` / `top-holders` | **5 年** | 3 年 |
-| `fundamental earning-forecast` | **1 年** | 1 年 |
-| `indicator cross-section` / `time-series` / `screener` | **5 年** | 3 年 |
-| `indicator search`、`alternative edb-search` / `edb-data` | **不限** | 不限 |
-| `alternative concept-info` / `concept-securities` | 最新截面 | 最新截面 |
-| `reference index-weight` | 按账号权限（界外报 `110003`）；只有月末交易日有数 | 同左 |
-| `bond daily-quote` / `valuation` / `issuance-plan` | **5 年** | 3 年 |
-| `bond` 其余命令 | **不限** | 不限 |
-| `fund` 净值 / 规模 / 持有人 / 资产配置 / 持仓与分布 / `etf-share-change` | **5 年**（两端日期都不传 = 窗口内全部） | 3 年 |
-| `fund` 其余命令（`basic-info` / `fee-rate` / 经理两个 / `etf-pcf-*`） | **不限** | 不限 |
-| `insight research`（内资研报）/ `report-image`（研报图表） | **3 年** | 1 年 |
-| `insight announcement` / `announcement-hk` / `announcement-us`、`performance-calendar`（列表与下载） | **5 年** | 2 年 |
-| `insight opinion` / `foreign-opinion`（列表与详情）/ `independent-opinion` / `summary` 纪要 / `foreign-report` 外资研报 / `official-account` 公众号 | **1 年** | 3 个月 |
-| `insight highlight list` 会议线索 | **1 年** | 3 个月 |
-| `insight roadshow` / `site-visit` / `strategy` / `forum` | **历史 1 年 + 未来日程** | 同正式 |
-| `insight qa` | **1 年** | 1 年 |
-| `insight pamirs-summary` 帕米尔纪要 | **不限**（需单独购买专家纪要库） | — |
-| `ai hot-topic` / `security-clue` | **3 个月** | 3 个月 |
-| `ai expert-intel` | 按账号权限（界外报 `110003`） | 同左 |
-| `ai theme-tracking` | **1 个月** | 1 个月 |
-| `ai management-discuss-*` | **1 年** | 1 年 |
-| `ai management-sentiment-indicator` / `-conclusion` | **1 年** | 6 个月 |
-| `ai management-sentiment-detail` | 按 `--source-id` 取整场，不按日期限制 | 同正式 |
-| `ai earnings-review` | 最近 6 期财报 | 同正式 |
-| `ai one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `viewpoint-debate` / `stock-summary` | 最新截面 | 最新截面 |
-| `ai knowledge-batch` | **不限** | 不限 |
-| `vault my-conference-list` / `my-conference-download` | **1 个月** | 1 个月 |
-| `vault` 其余（速记 / 群消息 / 股票池 / 云盘） | **不限** | 不限 |
-
-⚠️ **实际窗口按账号配**，换接口绕不过去（`indicator` 与 `quote day-kline` 同界）。整段在界外返回 `110003`（不是空结果），把日期移进范围或联系客户经理。🔴 **区间跨过下界时各接口不同**：`quote` 日 K / 分钟 K / 资金流向与 `fundamental valuation-analysis` 从下界起返回、**不报错**（首行明显晚于起始日时 CLI 在 stderr 提示）；`indicator`、`bond` 与 `fund` 整批报 `110003`；`bond daily-quote` / `bond valuation` 的数据还可能比账号窗口短——区间早于数据起点时返回 `130001`，跨过数据起点时从有数据的那天起返回、不报错（首行明显晚于起始日时 CLI 在 stderr 提示），核对首行日期。上面两处 stderr 提示都只看整批最早的首行：多只同查时有一只够早就不提示，逐只的起点按 `securityCode` 核对。**例外**：`quote minute-kline` 窗口只有 1 个月且随日期滚动，整段在窗外返回空结果、不报错（CLI 在 stderr 提示）；`ai hot-topic` 超出账号可查范围时也返回空结果、不报错。
+### 积分计费（要点，全表见 `references/billing.md`）
+
+- **免费**：`quote` 行情、`fundamental` 报表 / 主营 / 估值 / 股东（**盈利预测 0.5/条除外**）、`reference` 查询、`alternative edb-search`、`vault`（`my-conference` 列表 0.1/条、下载 30/篇除外）、`insight report-image list`
+- **列表按返回条数计**：研报 / 公告 / 纪要 / 公众号 / 问答 / 财报日历 / 海外观点等 **0.1/条**（海外观点正文 `detail` 10/条）；内资 / 外资观点、独立观点 **1/条**（只含摘要，内资 / 外资观点正文 `detail` 或 `--with-content` **30/条**）；路演四件套 **10/条**；🔴 `insight highlight list` **5/条**、`ai expert-intel` **20/条**、`ai hot-topic` **10/篇**（一篇是一整份报告）、`ai security-clue` / 管理层情绪 **5/条**；`ai stock-summary` 1/条、`alternative edb-data` 30/指标
+- **按次**：AI 生成与管理层讨论类 **5～20/次**、`ai knowledge-batch` 10；`bond` / `fund` **0.4/次**（`bond` 三个评级类按量计；`fund` 多只合并一次调用最省）；`tool web-search` 1；🔴 题材 `concept-*` 50/次，加 `--full` **500/次**；`tool file-parse` 0.8/页（提交时扣）；各 download 0.1～30/篇
+- **按单元格**：`indicator` 截面 / 时序 / 选股（A 股 0.05、港股 0.1、美股 0.2 积分每 100 格）；🔴 截面 / 时序单次上限 **30000 格**（证券数 × 指标数，或序列数 × 日期数），超出报 `100006`，按乘积拆批
+- `insight pamirs-summary` 单价未公布，**别假定免费**，大批量前先小量试
+- 扣费在接口成功返回数据之后，空结果与报错不扣——「先小范围试再放大」是安全的；但**同参数重复调用每次都扣**，结果拿到后留存复用
+- 🔴 **按次 / 贵档端点超时、5xx 不自动重放**（服务端可能已执行并扣费，重放会重复扣分；清单见 `references/billing.md`）——**一次调用给足超时比失败重跑省钱**；`--dry-run` 只打印将发出的请求与单价、不发送，不确定花费时先用它看
+
+### 数据范围（要点，全表见 `references/billing.md`）
+
+能查多久**跟着账号权限走**，以实际返回为准；官方权限表的正式账号口径多为行情 / 报表 / EDE **5 年**、研报 3 年、观点 / 纪要 / 公众号 **1 年**、分钟 K **1 个月**，试用账号更短（全表供参考，别按表预先缩短区间）。整段在界外报 `110003`；🔴 **跨过下界时**：`quote` 日 K / 分钟 K / 资金流向与 `valuation-analysis` 从下界起返回、**不报错**（首行明显晚于起始日时 stderr 提示），`indicator` / `bond` / `fund` / `insight overseas-opinion` 整批报 `110003`；`quote minute-kline` 与 `ai hot-topic` 在窗外返回空结果、不报错。
 
 ### 下载规则（`--file-type` / `--content-type`）
 
@@ -225,7 +102,7 @@ vault.stock-pool.create
 | `vault record-download` | `--content-type` | `original` 原始文件 / `asr` 语音识别 / `summary` AI 速记 |
 | `vault my-conference-download` | `--content-type` | `asr` 语音识别 / `summary` AI 速记 |
 
-省略 `--output` 时 CLI 用本地 title-cache 里的真实标题做文件名（`independent-opinion`、`report-image` 与 `vault wechat-message-download` 的下载不在此列，也没有 `--resolve-title`；群消息文件按服务端给的文件名保存，内容原样落盘）——**只读缓存**，命中就零额外调用。缓存由同端点的 `list` 写入，所以「先 `list` 再 `download`」这个正常工作流本来就免费拿到正确文件名。
+`--output` 是**文件路径**（含文件名）；传目录（已存在的目录或以 `/` 结尾的路径）会在发请求前报错、不扣费，所有带 `--output` 的命令同理；CLI 自己的配置目录（`~/.config/gangtise/`，存 token 缓存）不能作 `--output`，其中的文件也不能作 `--file` 上传。省略 `--output` 时 CLI 用本地 title-cache 里的真实标题做文件名（`independent-opinion`、`report-image` 与 `vault wechat-message-download` 的下载不在此列，也没有 `--resolve-title`；群消息文件按服务端给的文件名保存，内容原样落盘）——**只读缓存**，命中就零额外调用。缓存由同端点的 `list` 写入，所以「先 `list` 再 `download`」这个正常工作流本来就免费拿到正确文件名。
 
 🔴 **未命中时默认不回查**，退回服务端文件名或 `<type>-<id>.<ext>`。要回查得显式加 `--resolve-title`——它拉最近 200 条（4 次请求），而这些 list 多数按 **0.1 积分/条**计费，约 20 积分，只用于取一个更易读的文件名（下载本身 1–30）。**批量下载或按 ID 下旧文件**时：要么先跑一次 `list` 把标题灌进缓存，要么直接 `--output ./<名>.<ext>` 自己定名；`--resolve-title` 会把取回的 200 条一并写回缓存，同批后续下载不再重复消耗。
 
@@ -238,6 +115,7 @@ vault.stock-pool.create
 | 首席观点 / 内资机构观点 / 分析师观点 | `insight opinion list`（只含摘要 `brief`，1/条）；要正文 → `insight opinion detail --chief-opinion-id`（30/条）。按观点类别（业绩点评 / 异动点评…）、投研标签（强烈推荐 / 超预期 / 涨价 / 龙头…）、机构标签（头部券商 / 新财富）筛 → `--category` / `--llm-tag` / `--broker-tag`，取值见 `insight.md` |
 | 外资机构观点 / 外资券商观点 | `insight foreign-opinion list`（摘要 + 中文摘要）；要原文与译文 → `insight foreign-opinion detail --foreign-opinion-id`（30/条） |
 | 外资独立观点 / 独立分析师观点 | `insight independent-opinion list` |
+| 海外观点 / 海外媒体与投资人帖子 / 海外社交平台观点 | `insight overseas-opinion list`（摘要 + 中文摘要，0.1/条；按账号 / 证券 / 类别 / GICS 行业 / 地区 / 原创或转发筛）；要全文与译文 → `insight overseas-opinion detail --overseas-opinion-id`（10/条） |
 | 纪要 / 会议纪要（外部） | `insight summary list` |
 | 帕米尔纪要 / 帕米尔专家纪要 / Pamirs | `insight pamirs-summary list`（专家纪要库，需单独购买；筛选项比 `summary` 少，无 `--source`/`--institution`/`--participant-role`） |
 | 路演 / 调研 / 策略会 / 论坛 | `insight roadshow / site-visit / strategy / forum list`（`--start-time` / `--end-time` 按举办时间；按收录时间增量同步用 `--publish-start-time` / `--publish-end-time`，两组可同时传） |
@@ -287,7 +165,7 @@ vault.stock-pool.create
 | 利率债发行计划 / 国债发行安排 | `bond issuance-plan`（**只按日期区间查，不收债券码**） |
 | 含权债行权 / 回售 / 赎回提示 | `bond exercise-notice` |
 | 违约债券 / 债券违约记录 / 某主体违约历史 | `bond default-list`（违约日期区间〔两端都给、不超过 1 年〕/ `--security` / `--issuer` **三选一**；`--issuer` 一次一个，用发行人**全称**并核对返回的 `issuerName`） |
-| 基金资料 / 基金分类 / 管理人 / 成立日 / 业绩基准 / 跟踪指数 / 风险等级 | `fund basic-info`（`--security` 用 `005827.OF` / `159967.SZ` 这类带后缀代码；只知道名称时用 `reference securities-search --keyword <基金简称或 6 位代码> --category fund` 换代码（**只取 `category` 为 `fund` 的行**，结果里可能混有债券、债券代码查基金返回空结果；没有就换更具体的简称；场内场外都能搜到；全称常搜不到；不同份额与场内 / 场外代码会一起返回，按 `gtsName` 区分）；`--field` 写错**整批拒绝** `100003`） |
+| 基金资料 / 基金分类 / 管理人 / 成立日 / 业绩基准 / 跟踪指数 / 风险等级 | `fund basic-info`（`--security` 用 `005827.OF` / `159967.SZ` 这类带后缀代码；只知道名称时用 `reference securities-search --keyword <基金简称或 6 位代码> --category fund` 换代码（带上 `--category fund` 只返回基金；没有就换更具体的简称；场内场外都能搜到；全称常搜不到；不同份额与场内 / 场外代码会一起返回，按 `gtsName` 区分）；`--field` 写错**整批拒绝** `100003`） |
 | 基金净值 / 复权净值 / 区间收益 / 货币基金七日年化 | `fund nav`（算收益用 `navAdjusted`） |
 | 基金费率 / 管理费 / 申购赎回费 | `fund fee-rate`（`feeRate` 是字符串） |
 | 基金经理画像（按人名） | `fund manager-info --manager <姓名>`（精确匹配，同名全返回，用 `currentCompany` 区分） |
@@ -325,7 +203,8 @@ vault.stock-pool.create
 | 证券代码 / gtsCode 搜索 | `reference securities-search` |
 | 首席 ID / 分析师 ID 搜索 | `reference chiefs-search`（按姓名/机构/团队，用于 `insight opinion list --chief`） |
 | 机构 ID 搜索（内资券商/外资/牵头/观点机构） | `reference institution-search`（按机构名，用于 `--institution` / `--broker`；免费） |
-| 公众号 ID 搜索（按公众号名/机构/分类） | `reference official-account-search`（返回 `accountId`，喂 `insight official-account list --account-id`；免费） |
+| 公众号 ID 搜索（按公众号名称；名称用简称的，按机构全称查不到，换简称） | `reference official-account-search`（返回 `accountId`，喂 `insight official-account list --account-id`；免费） |
+| 海外观点账号 ID 搜索（按账号名片段） | `reference overseas-account-search`（返回 `accountId`，喂 `insight overseas-opinion list --account`；免费） |
 | 常量/枚举 ID（行业/城市/公告分类/区域/债券类型/评级类型/交易市场等，分类以 `reference constant-category` 的返回为准） | `reference constant-list --category <code>`（分类代码用 `reference constant-category` 查；该接口会列出每个分类适用于哪些接口的哪个参数） |
 | 题材 ID 搜索 | `reference concept-search` |
 | 板块 ID 搜索 | `reference sector-search` |
@@ -344,7 +223,7 @@ vault.stock-pool.create
   - 单证券 → 优先 `fundamental` 专用命令（多数免费 / 低价）；多证券批量取**已实现**指标 → `indicator`（EDE）一次拉取：同一日期 / 报告期横比用 `cross-section`，区间走势用 `time-series`（不能多指标 × 多证券同时）
   - 始终不走 EDE：盈利预测 / 一致预期 → `fundamental earning-forecast`（EDE 的 EPS 是已实现值，**不能冒充预测**）；A 股估值历史分位 → `valuation-analysis`（港 / 美股的估值历史分位走 EDE `finc_*_quantile`，逐指标核 `scopeList`）；行情与 K 线 → `quote`；行业 / 宏观指标（无证券维度）→ `alternative edb-*`。**例外：总市值只有 EDE 有**——`indicator cross-section --indicator qte_mkt_cptl`（单位「元」，用 `--scale` 缩放）
   - 取数前 `indicator search --format json` 核三项：`indicatorName` + `description` 语义对、`scopeList` 覆盖全部目标市场、`parameterList` 必填参数可满足；任一不符就回退专用接口，港 / 美股缺专用能力时如实说不支持。「某市场无数据」这类否定结论以当次 `scopeList` + 抽查一行为准
-  - 日期参数**只看 `parameterList` 必填哪个**：`tradeDate` → `--date`，`reportDate` → `--indicator-param "code:reportDate=..."`（多数报告期类要后者，但 `_ttm` 整族要 `tradeDate`）；两个都必填（如 `div_cash_yld`）就两个都用 `--indicator-param` 显式给，只给 `reportDate` 时 `--date` 不再注入、会报 `100001`。`parameterList` 要 `fiscalYear` 的（预测类 `frcst_*`、分红类 `div_cash_yr` 等）显式给，漏传报 `100001` 并点名。日频估值（`finc_pe_ttm` / `finc_pb_mrq`）用最新交易日，用报告期末日期会取到陈值；参数名同样以 `parameterList` 为准（复权是 `adjustType`）
+  - 日期参数**只看 `parameterList` 必填哪个**：`tradeDate` → `--date`，`reportDate` → `--indicator-param "code:reportDate=..."`（多数报告期类要后者；`_ttm` 后缀的多数要 `tradeDate`，但不是全部，如 `finc_ebit_to_aset_ttm` 要 `reportDate`——别按后缀推）；两个都必填（如 `div_cash_yld`、`finc_pe`）就两个都用 `--indicator-param` 显式给，只给 `reportDate` 时 `--date` 不再注入、会报 `100001`。`parameterList` 要 `fiscalYear` 的（预测类 `frcst_*`、分红类 `div_cash_yr` 等）显式给，漏传报 `100001` 并点名；一个日期参数都没有的（`pty_*` / `scr_*` / `ipo_*` 等；行业分类 `scr_indu` / `scr_indu_*` 不在此列，要 `--date`）加 `--indicator-param "code:"`，否则报 `100003`。日频估值（`finc_pe_ttm` / `finc_pb_mrq`）用最新交易日，用报告期末日期会取到陈值；参数名同样以 `parameterList` 为准（复权是 `adjustType`）
   - 结果**按 `security` 字段取值**，别按请求下标对位（证券的返回顺序不作保证）；批量回填加 `--key-by code`
   - 估值历史：EDE 与 `valuation-analysis` 的财报口径切换时点与财报版本都不同，做分位 / 回测两边都拉交叉核
 - "业绩点评"双义消歧：**检索已有**的业绩点评：研报走 `insight research list --llm-tag earningsReview`（0.1/条；`--llm-tag` 只有 `opinion` / `research` / `foreign-report` 三个列表有），首席观点走 `insight opinion list --category earningsReview`（1/条；观点的「业绩点评」是类别，不是 `--llm-tag`），业绩会纪要走 `insight summary list --category earningsCall`；**AI 现生成**一份走 `ai earnings-review`（异步、20/次）。不确定问一句
@@ -367,7 +246,7 @@ vault.stock-pool.create
 ```bash
 gangtise reference securities-search --keyword <公司名> --category stock --top 3 --format json
 ```
-取第一条 `category` 为 `stock` 的 `gtsCode`（CLI 已剥掉信封，输出顶层就是 `{returnedCount, list}`）——**别直接取 `list[0]`**：按简称查时同名可转债（`category: bond`）可能排第一。matchScore < 0.5 时让用户从前 3 条选。债券代码用 `--category bond` 查。
+取第一条 `category` 为 `stock` 的 `gtsCode`（CLI 已剥掉信封，输出顶层就是 `{returnedCount, list}`）——**`--category stock` 别省略**：不带它按简称查时，同名可转债（`category: bond`）可能排第一。matchScore < 0.5 时让用户从前 3 条选。债券代码用 `--category bond` 查。
 
 **交易所后缀**：`.SH` 上交所（6 开头）｜ `.SZ` 深交所（0/3 开头）｜ `.BJ` 北交所 ｜ `.HK` 港股 ｜ `.O` 纳斯达克 ｜ `.N` 纽交所 ｜ `.A` AMEX ｜ 沪深 ETF 同 `.SH` / `.SZ` ｜ 场外基金 `.OF`（`fund` 命令组） ｜ 全球指数用数据源后缀（`SPX.SPI` `N225.NKI` `HSI.HI` `GDAXI.FRA` …，清单见 `references/commands/quote.md`，**别猜**）。
 
@@ -420,11 +299,11 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 
 日期参数**按参数名判断、不按命令组**：名字带 `-date` 的（`--start-date` / `--end-date` / `--date` / `--report-date`）收年在前日期（`YYYY-MM-DD` 首选，`YYYY/MM/DD` / `YYYYMMDD` 也收）；名字带 `-time` 的（`--start-time` / `--end-time`）收年在前日期 + 可选 ` HH:mm[:ss]`（空格或 `T` 分隔）或 10 / 13 位时间戳（`ai management-sentiment-indicator` / `-conclusion` 写时刻必须带秒，`HH:mm` 报 `110001`）。易错：Insight / Vault 各 list 用 `-time`，**唯独 `insight performance-calendar` 用 `-date`**；AI 组两种都有（`theme-tracking --date`、`hot-topic` / `management-discuss-*` 用 `-date`，`security-clue` / `knowledge-batch` / `management-sentiment-indicator` / `-conclusion` / `expert-intel` 用 `-time`）；`quote minute-kline` 用 `-time`，其余 Quote / Fundamental / Indicator / `bond` / `fund` / `edb-data` 与 `reference index-weight` 用 `-date`。拿不准看该命令 `--help`。
 
-支持排序切换的 list：opinion / summary / pamirs-summary / research / foreign-report / 三个公告 / foreign-opinion / independent-opinion / official-account。**要最新加 `--rank-type 2`（按 `publishTime` 倒序）；要最相关用默认 `--rank-type 1` + `--keyword`**——两者从同一结果集取的是**不同子集**，没有 `--keyword` 时无差异。`--search-type 2`（只有 summary / pamirs-summary / research / foreign-report / 三个公告 / official-account 有）扩大命中总数与 `--rank-type 2` 的候选池，**不改变 `--rank-type 1` 取回的条目**，要相关度不必加。判断这两个参数是否生效的方法见 `references/commands/insight.md` 开头。
+支持排序切换的 list：opinion / summary / pamirs-summary / research / foreign-report / 三个公告 / foreign-opinion / independent-opinion / overseas-opinion / official-account。**要最新加 `--rank-type 2`（按 `publishTime` 倒序）；要最相关用默认 `--rank-type 1` + `--keyword`**——两者从同一结果集取的是**不同子集**，没有 `--keyword` 时无差异。`--search-type 2`（只有 summary / pamirs-summary / research / foreign-report / 三个公告 / official-account 有）扩大命中总数与 `--rank-type 2` 的候选池，**不改变 `--rank-type 1` 取回的条目**，要相关度不必加。判断这两个参数是否生效的方法见 `references/commands/insight.md` 开头。
 
 ## 异常处理
 
-**退出码**：`0` 完整成功（含合法空结果）／ `3` 有数据但不完整（`partial: true`，stderr 有 warning；标记只在 `--format json` 里看得见，csv / jsonl 落盘看旁边 `<file>.meta.json` 的 `complete` 与 `result`）／ `4` 数据写全了，但 `--output` 文件在收尾时被另一次写向同一路径的导出替换（给并发导出各自的 `--output` 即可）／ `1` 硬失败／ `130` / `143` / `129` 被 Ctrl-C / `kill` / 终端断开中断（本次的暂存文件已删除）。**拿到 3 就必须告知用户缺了哪段，不能当成功静默继续**。按标记处理：`failedPages` / `failedShards` 重拉失败段；`truncatedShards` / `truncatedSecurities` / `totalCapped` / `duplicateRows` 缩小日期范围分批重拉；`changedRows` 直接重拉；`missingFields` 核对字段名；其余标记见 `references/errors.md`。`outOfWindowShards` 不影响退出码：列的是早于账号可回溯窗口、被跳过的日期区间，告诉用户结果从哪天开始即可。报错行带 `[trace <id>]`，**报障给 Gangtise 时务必带上**。
+**退出码**：`0` 完整成功（含合法空结果）／ `3` 有数据但不完整（`partial: true`，stderr 有 warning；标记只在 `--format json` 里看得见，csv / jsonl 落盘看旁边 `<file>.meta.json` 的 `complete` 与 `result`）／ `4` 数据写全了，但 `--output` 文件在收尾时被另一次写向同一路径的导出替换（给并发导出各自的 `--output` 即可）／ `1` 硬失败（请求可能已发出、可能已计费）／ `2` 发请求前就被拒（选项或取值不对、缺 `--yes`、未配凭证），**什么都没发、没有计费**，按报错改了重跑即可／ `130` / `143` / `129` 被 Ctrl-C / `kill` / 终端断开中断（本次的暂存文件已删除）。**拿到 3 就必须告知用户缺了哪段，不能当成功静默继续**。按标记处理：`failedPages` / `failedShards` 重拉失败段；`truncatedShards` / `truncatedSecurities` / `totalCapped` / `duplicateRows` 缩小日期范围分批重拉；`changedRows` 直接重拉；`missingFields` 核对字段名；其余标记见 `references/errors.md`。`outOfWindowShards` 不影响退出码：列的是早于账号可回溯窗口、被跳过的日期区间，告诉用户结果从哪天开始即可。报错行带 `[trace <id>]`，**报障给 Gangtise 时务必带上**。
 
 最高频的几个码（全表、「不报错的坑」、`screener` 缺列判据与困境自救见 `references/errors.md`）：
 
@@ -449,7 +328,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 
 按需 Read 对应文件：
 
-- 内资观点 / 纪要 / 路演 / 调研 / 策略 / 论坛 / 财报日历（performance-calendar）/ 研报 / 外资研报 / A 股公告 / 港股公告 / 美股公告 / 外资观点 / 独立观点 / 公众号（official-account）/ 投资者问答（qa）/ 研报图表（report-image）→ `references/commands/insight.md`
+- 内资观点 / 纪要 / 路演 / 调研 / 策略 / 论坛 / 财报日历（performance-calendar）/ 研报 / 外资研报 / A 股公告 / 港股公告 / 美股公告 / 外资观点 / 独立观点 / 海外观点（overseas-opinion）/ 公众号（official-account）/ 投资者问答（qa）/ 研报图表（report-image）→ `references/commands/insight.md`
 - 行情命令（A 股 / 港股 / 美股 / ETF / 指数日 K、分钟 K、实时行情、资金流向 fund-flow / sector-fund-flow，含全球指数清单） → `references/commands/quote.md`
 - 三大报表（A 股 / 港股 / 美股）/ 主营 / 估值 / 盈利预测 / 股东 → `references/commands/fundamental.md`
 - knowledge-batch / security-clue / 个股看点（stock-summary）/ AI 专家情报（expert-intel）/ AI agent / 异步任务 / 主题跟踪 / 热点 / 管理层讨论 / 管理层情绪 → `references/commands/ai.md`
@@ -459,7 +338,8 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 - 债券（basic-info / issuer-info / daily-quote / valuation / cash-flow / announcement / issuance-* / rating-overview / rating-change / issuer-rating-change / exercise-notice / default-list）→ `references/commands/bond.md`
 - 公募基金（basic-info / nav / fee-rate / manager-* / asset-size / holder-structure / top10-holders / asset-allocation / 持仓与分布六个 / etf-pcf-* / etf-share-change）→ `references/commands/fund.md`
 - PDF 解析（file-parse）/ 联网搜索（web-search）→ `references/commands/tool.md`
-- securities-search / chiefs-search（首席 ID）/ institution-search（机构 ID）/ official-account-search（公众号 ID）/ 常量查询（constant-category / constant-list）/ 题材 ID（concept-search）/ 板块（sector-search / sector-constituents）/ 指数成分股权重（index-weight）/ lookup 本地表 / 行业别名 / raw call → `references/commands/reference-and-lookup.md`
-- 错误码全表 / 不报错的坑 / 退出码 3 与 `screener` 缺列判据 / Troubleshooting → `references/errors.md`
+- securities-search / chiefs-search（首席 ID）/ institution-search（机构 ID）/ official-account-search（公众号 ID）/ overseas-account-search（海外观点账号 ID）/ 常量查询（constant-category / constant-list）/ 题材 ID（concept-search）/ 板块（sector-search / sector-constituents）/ 指数成分股权重（index-weight）/ lookup 本地表 / 行业别名 / raw call → `references/commands/reference-and-lookup.md`
+- 积分单价全表 / 不自动重放的端点清单 / 各命令可查的数据范围 → `references/billing.md`
+- 错误码全表 / 不报错的坑 / 退出码 2 / 3 与 `screener` 缺列判据 / Troubleshooting → `references/errors.md`
 
 跑通流程对照 → `references/examples.md`

package/gangtise-openapi/references/billing.md

@@ -0,0 +1,142 @@
+# 积分计费与数据范围
+
+> 单价是平台公布的价目，CLI 无法实测扣费；以平台账单为准。
+
+## 积分计费
+
+"免费"=0 积分；**只列单价**，数据范围见下一节「数据范围」。
+
+- **免费**：所有 `quote` 行情、`fundamental` 报表/主营/估值/股东（**盈利预测除外**）、`reference`/`constant` 查询（含 `official-account-search` / `overseas-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 / performance-calendar 的 list、`vault my-conference-list`；`insight overseas-opinion list`（只含摘要，要全文用 `detail` 10/条）；`insight report-image download` 0.1/张
+- **按条（观点/含详情类 list）**：`ai security-clue` 5；`ai management-sentiment-indicator` / `-conclusion` 5；roadshow/site-visit/strategy/forum list 10；independent-opinion list 1；**opinion / foreign-opinion list 1（只含摘要 `brief`）**，要正文用 `detail` 30/条或 `list --with-content` 30/条；`fundamental earning-forecast` 0.5；`ai stock-summary` 1（无看点的证券不返回也不扣）；`alternative edb-data` 30/指标
+- **各 download（/篇）**：official-account / research 10；announcement 1；announcement-hk / announcement-us 2；independent-opinion / summary / foreign-report / my-conference 30；`performance-calendar download` A 股 1 / 港美股 2（下载前分不出市场，`--dry-run` 按 2 显示）
+- **0.4 的 `bond` 系**：`bond` 全部命令 **0.4/次**（按次，与返回行数无关），三个例外按量计：`rating-overview` 0.4/**条**、`rating-change` 0.4/**只有数据的债券**、`issuer-rating-change` 0.4/**个发行人**
+- **0.4 的 `fund` 系**：`fund` 全部命令 **0.4/次**（按次，与返回行数、基金只数无关）——多只基金合并成一次调用最省
+- **`tool web-search` 1/次**（按次，与返回条数、是否带 `--include-content` 无关；零结果与报错不扣）
+- 🔴 **`insight highlight list` 5/条**——**按返回条数计**，`--size 20` 的一页 = 100 积分。省略 `--size` 时 CLI 先估算，超过 1000 积分（约 200 条）报错退出，要全量须加 `--yes`
+- 🔴 **`ai expert-intel` 20/条**——**按返回条数计**，`--size 20` = 400 积分，一整页（50 条）= 1000 积分。省略 `--size` 时 CLI 先取 1 条拿总数再估算，超过 1000 积分（50 条）报错退出，要全量须加 `--yes`；先用 `--security` / `--tag` / 时间收窄
+- **按页**：`tool file-parse` 0.8/页，**提交（`--file`）时按实际页数一次性扣**，取结果（`file-parse-check`）免费——50 页 PDF = 40 积分，别重复提交同一文件
+- 🔴 **按次**：`ai knowledge-batch` 10、`management-discuss-earnings-call` 10、`management-discuss-announcement` 5、`management-sentiment-detail` 10；AI Agent `one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `theme-tracking` **10/次**，`earnings-review` / `viewpoint-debate` **20/次**
+- 🔴 **`ai hot-topic` 10/篇，按返回条数计**（不是按调用次数）。📌 **一「篇」= 一整份报告**（一份早报 / 午报 / 盘中快报 / 晚报），**不是报告里的一条话题**——一份报告通常包含多条热点话题。所以 `--size 20` 的一页 = 最多 20 份报告 = 200 积分，**先用 `--start-date`/`--end-date` + `--category` 收窄再拉**，别省略 `--size` 直接全量。**可查的历史范围是前溯 3 个月**（各档相同）——超出范围的日期返回空结果而不是报错，拿到空先想想是不是撞了权限窗口
+- **题材**：`alternative concept-info` / `concept-securities` **50/次**；🔴 加 `--full`（催化事件 / 重点个股标识 / 纳入理由）走旧版 **500/次**，不需要这几列就别加
+- ✅ **扣费发生在接口成功返回数据之后**（平台计费规则）：没查到内容（空结果）、报错都不扣分——各 download、`ai hot-topic`（10/篇）、`ai stock-summary`（1/条，无看点总结的个股不进返回列表也不计费）、AI 生成类（`one-pager` 等 10～20/次），以及按次计费的 `ai knowledge-batch`、题材、`tool web-search` 都是这样。**所以「先小范围试探再放大」是安全的**——先用窄条件确认能查到东西，再扩范围。⚠️ **「成功返回」按服务端算**：超时报错时服务端可能已经生成并返回了内容（只是客户端没收到），这次已经扣过，同参数重调会再扣一次；异步的 `earnings-review` / `viewpoint-debate` 在提交成功（拿到任务 ID）时就扣，之后生成失败不退。**单价未公布的** `pamirs-summary`（见下）别据此假定
+- ⚠️ **同参数重复调用不免费**：按次计费的那批无缓存命中豁免（`one-pager` 等生成类重复调用每次扣分，即使秒回缓存内容）；**按篇/按条的也一样**——重拉同一批 `hot-topic` 就是按条数再计一次费。生成类与列表结果拿到后自行留存复用，别为「刷新」重调
+- ⚠️ **这些端点超时 / 5xx 不自动重放**（共 69 个，完整清单见下方注释块：按次计费的 AI Agent 那批、`ai knowledge-batch` / `management-discuss-*` / `management-sentiment-detail` / `hot-topic`、题材两接口（含 `--full`）、`bond` 与 `fund` 全部命令、`tool web-search`、`tool file-parse` 提交；summary / foreign-report / my-conference 三个 download；按条计费的 `insight highlight list`、`ai expert-intel`、观点 `detail` / `list --with-content`、`ai stock-summary` 与 `fundamental earning-forecast`；以及不计分但重放有副作用的 `vault stock-pool-create`、`vault stock-note-add` 与云盘上传 / 新建文件夹 / 复制 / 删除）。仅连接失败、429 与 token 自愈会重试。服务端可能已经执行并计费，重放会重复扣分、多建一份或把成功报成失败——**一次调用给足超时比失败重跑省钱**
+
+<!-- no-replay-endpoints
+     上面那句点名的「不重放」端点，完整清单如下（endpoint key，与 `gangtise raw list` 一致）：
+ai.earnings-review.get-id
+ai.expert-intel.list
+ai.hot-topic
+ai.investment-logic
+ai.knowledge-batch
+ai.management-discuss-announcement
+ai.management-discuss-earnings-call
+ai.management-sentiment-detail
+ai.one-pager
+ai.peer-comparison
+ai.research-outline
+ai.stock-summary.list
+ai.theme-tracking
+ai.viewpoint-debate.get-id
+alternative.concept-info
+alternative.concept-info-full
+alternative.concept-securities
+alternative.concept-securities-full
+bond.announcement
+bond.basic-info
+bond.cash-flow
+bond.daily-quote
+bond.default-list
+bond.exercise-notice
+bond.issuance-detail
+bond.issuance-plan
+bond.issuer-info
+bond.issuer-rating-change
+bond.rating-change
+bond.rating-overview
+bond.valuation
+fund.asset-allocation
+fund.asset-size
+fund.basic-info
+fund.bond-portfolio
+fund.bond-type-allocation
+fund.etf-pcf-components
+fund.etf-pcf-header
+fund.etf-share-change
+fund.fee-rate
+fund.fund-portfolio
+fund.fund-type-allocation
+fund.holder-structure
+fund.industry-allocation
+fund.manager-history
+fund.manager-info
+fund.nav
+fund.stock-portfolio
+fund.top10-holders
+fundamental.earning-forecast
+insight.foreign-opinion.detail
+insight.foreign-opinion.list-with-content
+insight.foreign-report.download
+insight.highlight.list
+insight.opinion.detail
+insight.opinion.list-with-content
+insight.overseas-opinion.detail
+insight.pamirs-summary.download
+insight.summary.download
+tool.file-parse.submit
+tool.web-search
+vault.drive.copy
+vault.drive.create-folder
+vault.drive.delete-file
+vault.drive.delete-folder
+vault.drive.upload
+vault.my-conference.download
+vault.stock-note.add
+vault.stock-pool.create
+-->
+- **按单元格**：`indicator cross-section` / `time-series` / `screener`（A股 0.05 / 港股 0.1 / 美股 0.2 积分每 100 单元格；screener 按**筛选前**范围 × 指标数保守估算，实际以平台账单为准，见 `indicator.md`）；`ai knowledge-resource-download` 按下游资源计费
+  - 🔴 截面 / 时序另有**单次 30000 单元格硬上限**（截面 = 证券数 × 指标数，时序 = 序列数 × 日期数），超出报 `100006`、不返回部分结果——按这个乘积拆批。板块 ID 会展开成全部成分股，实际证券数常远超写进命令的条数
+- **单价未公布**：`insight pamirs-summary list` / `download`——spec 只写了「需购买专家纪要数据库」这个准入门槛，没给单次价格。**别据此假定免费**；大批量拉取前先小量试，或向平台确认
+
+## 数据范围（能查多久）
+
+**能查多久跟着账号权限走**：各账号单独配置，同一命令在不同账号上可能不同，以实际返回为准。下表是官方权限表的正式账号与试用账号口径（Plan 基础版同试用，高级版介于两者之间），供规划参考——**别按表预先缩短区间**，越界时的表现见表后：
+
+| 命令 | 正式账号 | 试用账号 |
+|------|------|------|
+| `quote day-kline` / `fund-flow` | **5 年** | 3 年 |
+| `quote sector-fund-flow` | 官方权限表未列；可能短于 `fund-flow`，长区间先试最早一段 | 同左 |
+| `quote minute-kline` | **1 个月**（随日期滚动） | 1 个月 |
+| `quote realtime` | 最新快照 | 最新快照 |
+| `fundamental` 三大报表（A / 港 / 美）/ `main-business` / `valuation-analysis` / `top-holders` | **5 年** | 3 年 |
+| `fundamental earning-forecast` | **1 年** | 1 年 |
+| `indicator cross-section` / `time-series` / `screener` | **5 年** | 3 年 |
+| `indicator search`、`alternative edb-search` / `edb-data` | **不限** | 不限 |
+| `alternative concept-info` / `concept-securities` | 最新截面 | 最新截面 |
+| `reference index-weight` | 按账号权限（界外报 `110003`）；只有月末交易日有数 | 同左 |
+| `bond daily-quote` / `valuation` / `issuance-plan` | **5 年** | 3 年 |
+| `bond` 其余命令 | **不限** | 不限 |
+| `fund` 净值 / 规模 / 持有人 / 资产配置 / 持仓与分布 / `etf-share-change` | **5 年**（两端日期都不传 = 窗口内全部） | 3 年 |
+| `fund` 其余命令（`basic-info` / `fee-rate` / 经理两个 / `etf-pcf-*`） | **不限** | 不限 |
+| `insight research`（内资研报）/ `report-image`（研报图表） | **3 年** | 1 年 |
+| `insight announcement` / `announcement-hk` / `announcement-us`、`performance-calendar`（列表与下载） | **5 年** | 2 年 |
+| `insight opinion` / `foreign-opinion` / `independent-opinion` / `summary` 纪要 / `foreign-report` 外资研报 / `official-account` 公众号 | **1 年** | 3 个月 |
+| `insight highlight list` 会议线索 | **1 年** | 3 个月 |
+| `insight overseas-opinion`（列表与详情） | 官方权限表未列，按账号权限 | 同左 |
+| `insight roadshow` / `site-visit` / `strategy` / `forum` | **历史 1 年 + 未来日程** | 同正式 |
+| `insight qa` | **1 年** | 1 年 |
+| `insight pamirs-summary` 帕米尔纪要 | **不限**（需单独购买专家纪要库） | — |
+| `ai hot-topic` / `security-clue` | **3 个月** | 3 个月 |
+| `ai expert-intel` | 按账号权限（界外报 `110003`） | 同左 |
+| `ai theme-tracking` | **1 个月** | 1 个月 |
+| `ai management-discuss-*` | **1 年** | 1 年 |
+| `ai management-sentiment-indicator` / `-conclusion` | **1 年** | 6 个月 |
+| `ai management-sentiment-detail` | 按 `--source-id` 取整场，不按日期限制 | 同正式 |
+| `ai earnings-review` | 最近 6 期财报 | 同正式 |
+| `ai one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `viewpoint-debate` / `stock-summary` | 最新截面 | 最新截面 |
+| `ai knowledge-batch` | **不限** | 不限 |
+| `vault my-conference-list` / `my-conference-download` | **1 个月** | 1 个月 |
+| `vault` 其余（速记 / 群消息 / 股票池 / 云盘） | **不限** | 不限 |
+
+⚠️ **实际窗口按账号配**，换接口绕不过去（`indicator` 与 `quote day-kline` 同界）。整段在界外返回 `110003`（不是空结果），把日期移进范围或联系客户经理。🔴 **区间跨过下界时各接口不同**：`quote` 日 K / 分钟 K / 资金流向与 `fundamental valuation-analysis` 从下界起返回、**不报错**（首行明显晚于起始日时 CLI 在 stderr 提示）；`indicator`、`bond`、`fund` 与 `insight overseas-opinion` 整批报 `110003`；`bond daily-quote` / `bond valuation` 的数据还可能比账号窗口短——区间早于数据起点时返回 `130001`，跨过数据起点时从有数据的那天起返回、不报错（首行明显晚于起始日时 CLI 在 stderr 提示），核对首行日期。上面两处 stderr 提示都只看整批最早的首行：多只同查时有一只够早就不提示，逐只的起点按 `securityCode` 核对。**例外**：`quote minute-kline` 窗口只有 1 个月且随日期滚动，整段在窗外返回空结果、不报错（CLI 在 stderr 提示）；`ai hot-topic` 超出账号可查范围时也返回空结果、不报错。

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

@@ -5,7 +5,7 @@
 `--security` 收**基金交易代码**，后缀大写：场外 `005827.OF`；场内 `159967.SZ` / `510300.SH`。可重复，也接受逗号分隔；重复代码服务端自动去重。
 
 - 🔴 **代码不存在、不带后缀（`005827`）、后缀小写（`.of`）、传成股票代码，都返回空结果、不报错**——拿到空先核对代码与后缀
-- **只知道基金名称时**：用 `reference securities-search --keyword <基金简称或 6 位代码> --category fund` 换代码，🔴 **只取返回里 `category` 为 `fund` 的行**——结果里可能混有可转债等债券（关键词含「转债」时前几条可能全是债券），把债券代码传给基金命令会返回空结果、不报错；没有 `category: fund` 的行时，换更具体的基金简称再搜。场内（`.SH` / `.SZ`）与场外（`.OF`）都能搜到（如「易方达蓝筹精选」或 `005827` → `005827.OF`）。基金全称常搜不到，如「华泰柏瑞沪深300ETF」要搜「沪深300ETF」或 `510300`。同一只基金的不同份额与场内 / 场外代码会一起返回（「富国天惠」→ `161005.SZ`、`161005.OF`、`003494.OF` 等），按 `gtsName` 区分后取一个
+- **只知道基金名称时**：用 `reference securities-search --keyword <基金简称或 6 位代码> --category fund` 换代码，🔴 **`--category fund` 别省略**——不带它时结果里会混有可转债等债券，把债券代码传给基金命令会返回空结果、不报错；搜不到时换更具体的基金简称再搜。场内（`.SH` / `.SZ`）与场外（`.OF`）都能搜到（如「易方达蓝筹精选」或 `005827` → `005827.OF`）。基金全称常搜不到，如「华泰柏瑞沪深300ETF」要搜「沪深300ETF」或 `510300`。同一只基金的不同份额与场内 / 场外代码会一起返回（「富国天惠」→ `161005.SZ`、`161005.OF`、`003494.OF` 等），按 `gtsName` 区分后取一个
 - LOF / ETF 的场内代码（`161005.SZ`）与场外代码（`161005.OF`）都能查，返回的 `fundCode` 与 `fundName` 跟随传入的代码（场内简称 / 场外简称不同）；同一只基金别两种代码混着传，会重复
 - A / C 等份额各有代码，要合并到同一只基金用 `basic-info` 的 `mainFundCode`
 - 多只基金的结果**按 `fundCode` 字段对应**，别按请求顺序对位
@@ -120,7 +120,7 @@ gangtise fund top10-holders --security <code>... [--start-date <d>] [--end-date
 **仅上市基金**（LOF / ETF 等）。每个报告期按 `serialNumber` 排名各一行：持有人名称、持有份额（份）、占上市总份额比例（%）。半年报与年报披露。
 
 - ETF 在前十名之外可能多一行 `serialNumber = 11`，是该 ETF 的**联接基金**（定期报告单列披露），它的占比可能高于前十中的多位。只要前十名就按 `serialNumber <= 10` 过滤
-- 最新一期的更新可能晚于其他持仓类命令。按最新报告期查不到时，先不带日期查一次，看已有哪些报告期
+- **2026 年中报起披露要求有调整**：除另有披露规则的产品（如 REITs）外，基金中报不再披露前十大持有人，这一期查不到属正常，不是数据缺失（同一基金的 `holder-structure` 仍有这一期）。先不带日期查一次，看该基金有哪些报告期
 
 ## `asset-allocation` 资产配置
 
@@ -166,7 +166,7 @@ gangtise fund etf-share-change    --security <code>... [--start-date <d>] [--end
 - **`etf-pcf-header` / `etf-pcf-components` 只返回最新一份申购赎回清单**，无日期参数，查不了历史清单。`tradeDate` 是清单对应的交易日（清单盘前发布，可能就是当天）
 - **`etf-pcf-header`**：申赎允许情况（`允许申购·允许赎回` 这种 `·` 分隔的组合）、最小申赎单位（份）及其净值（元）、单日申购 / 赎回上限（份，无上限为 `null`）、现金差额与预估现金（元，可为负）、现金替代比例上限（%）、`componentCount` 成分记录数
 - **`etf-pcf-components`**：每个成分一行，按 `serialNumber` 排序：成分代码 `componentCode`、成分名称 `componentName`、收盘价、涨跌幅、市值占比（%）、申购数量（股）、`cashSubstituteFlag`（`允许` / `必须`，中文）、申购 / 赎回现金替代溢价比例（%）、固定替代金额与申购 / 赎回替代金额（元）。宽基 ETF 动辄数百行，多只一起查注意 10000 行上限
-  - 🔴 **`componentCode` 是 CLI 按名称匹配补上的**（接口只返回名称），带市场后缀（如 `600519.SH` / `00941.HK` / `NVDA.O` / 国债 `019848.SH`）。匹配方式：按名称找证券（先查证券列表，没有再搜索），再用该行的 `close` 核对候选证券的最新价或昨收；核对不上的（清单价格滞后于行情、停牌等），改按清单价格所属那天的收盘价核对（A 股与港股各自定日期）——A+H 型 ETF 里同名的 A 股与 H 股两行据此分开。同名证券在两个市场都有时，实时价对上的一方还要另一市场那只的近期收盘价都对不上才直接采用（清单价格滞后时，另一市场那只的实时价可能碰巧等于该行）；**两个市场的价格都对得上、或另一市场那只排除不了时，再用该行的 `pctChange` 核对**：哪只证券有一天的收盘价与涨跌幅都和该行相同，就是哪只（同一公司 A / H 股价格碰巧相同的日子，涨跌幅几乎不会也相同）。价格定不了时（债券、停牌、除权除息当天、行情查询失败）：成分都在同一市场的 ETF 取该市场里名称完全一致的那只，同市场多只时取与 ETF 同一交易所的。价格与涨跌幅都定不了的（候选里有一只没有近期日 K、或在该收盘价那天算不出涨跌幅、或涨跌幅和哪只都对不上，如除权除息日）：另一市场那只的近期收盘价都对不上时按其余行所在的单一市场取，否则为 `null`——这样的行本身就说明 ETF 可能跨市场，不拿其余行替它定。**A+H 等跨市场的 ETF，以及还有一行可能在两个市场（同名 A / H 股、或港股名称更长的同一公司）没定下来、或某个名称查询失败的 ETF，价格定不了的行一律为 `null`**，不按名称猜
+  - 🔴 **`componentCode` 是 CLI 按名称匹配补上的**（接口只返回名称），带市场后缀（如 `600519.SH` / `00941.HK` / `NVDA.O` / 国债 `019848.SH`）。匹配方式：按名称找证券（先查证券列表，没有再搜索），再用该行的 `close` 核对候选证券的最新价或昨收；核对不上的（清单价格滞后于行情、停牌等），改按清单价格所属那天的收盘价核对（A 股与港股各自定日期）——A+H 型 ETF 里同名的 A 股与 H 股两行据此分开。同名证券在两个市场都有时，实时价对上的一方还要另一市场那只的近期收盘价都对不上才直接采用（清单价格滞后时，另一市场那只的实时价可能碰巧等于该行）；**两个市场的价格都对得上、或另一市场那只排除不了时，再用该行的 `pctChange` 核对**：哪只证券有一天的收盘价与涨跌幅都和该行相同，就是哪只（同一公司 A / H 股价格碰巧相同的日子，涨跌幅几乎不会也相同）。**排除一只证券要有证据**：它的日 K 要覆盖到相应那天、且收盘价对不上——实时行情对上该行而日 K 还没到行情那天（按行情日期判断）、或日 K 从更晚的日期才开始的，都不算排除；补码的每一步都按这条。价格定不了时（债券、停牌、除权除息当天、行情查询失败）：成分都在同一市场的 ETF 取该市场里名称完全一致的那只，同市场多只时取与 ETF 同一交易所的。价格与涨跌幅都定不了的（候选里有一只没有近期日 K、日 K 还没覆盖到相应那天——如实时行情比日 K 快一天、或在该收盘价那天算不出涨跌幅、或涨跌幅和哪只都对不上，如除权除息日）：另一市场那只被近期日 K 排除时（覆盖到相应那天、收盘价都对不上）按其余行所在的单一市场取，否则为 `null`——这样的行本身就说明 ETF 可能跨市场，不拿其余行替它定。**A+H 等跨市场的 ETF，以及还有一行可能在两个市场（同名 A / H 股、或港股名称更长的同一公司）没定下来、或某个名称查询失败的 ETF，价格定不了的行一律为 `null`**，不按名称猜
   - **匹配不到的为 `null`**：现金行（如 `申赎现金`）、商品（如 `黄金9999`）、交易所简称与证券名称对不上的（如港股 `港交所`、`中海油`）。stderr 会说明匹配了多少行、列出为 `null` 的行
   - ⚠️ 成分的 `close` 是清单给出的价格，日期可能早于 `tradeDate` 的前一交易日，一天之内还会更新，同一清单里 A 股与港股的日期也可能不同。要用价格计算，请以 `quote day-kline` / `quote realtime` 为准
   - 额外请求都免费：下载一次 A 股 / 港股 / 美股证券列表（3 次请求）在本地按名称匹配，列表里没有的名称（债券、被截断的简称、现金行等）才逐个搜索，另加一两次实时行情查询；有实时价格核对不上的行、或同名证券在两个市场都有时（清单价格滞后、停牌、除权除息、A+H 成分等），再加一次日 K 查询。只要接口原始返回时加 `--no-component-code`（不发这些请求，行里没有 `componentCode`）

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

@@ -17,6 +17,7 @@ gangtise fundamental <income-statement|balance-sheet|cash-flow> --security-code
 - `--period`：`q1` | `interim` 中报 | `q3` | `annual` | `latest`（默认）
 - `--report-type`：`consolidated`（默认）| `consolidatedRestated` | `standalone` | `standaloneRestated`
 - `--fiscal-year` 可重复：`--fiscal-year 2023 --fiscal-year 2024`
+- 🔴 **`--fiscal-year` 要和 `--period` 一起传**：不传 `--period` 时按默认 `latest` 取数，返回的是最新一期，与 `--fiscal-year` 无关（`--fiscal-year 2019` 单独传，拿到的是最新季报）。要某年年报写 `--fiscal-year 2019 --period annual`；港股、美股三张表同样如此
 - `--start-date`/`--end-date` 有值时覆盖 `--fiscal-year`
 - **固定返回字段**（无需 `--field` 指定）：`securityCode` `companyName` `category` `announcementDate` **`earliestAnncDate`** `endDate` `fiscalYear` `period` `reportType` `companyType` `currency` `unit`
 - 🔴 **做时点对齐（「这份财报在某日是否已公开」）用 `earliestAnncDate`（首次公告日），不要用 `announcementDate`**：`announcementDate` 是**返回数值所属公告**的日期——被重述过的报告期显示的是重述公告日（同一财年几期可能都是同一天），据此判断「某期数据在某日是否已公开」会得出相反的结论；`earliestAnncDate` 是该报告期自身的首次公告日。盘后披露的报告计次日，即**永不早于**真实披露时点，用来做 point-in-time 是安全的方向。要交叉核实披露日可查 `insight announcement list`