gangtise-openapi-cli 0.45.0 → 0.46.0

package/README.md

@@ -6,6 +6,8 @@
 
 README 仅列最近 5 个版本摘要：
 
+- **v0.46.0 — 2026-10-14**：① **`reference securities-search --category bond`**：按代码或简称搜债券，代码用于 `bond` 命令组。⚠️ **可转债可能出现在任何 `--category` 的结果里**（按简称查股票时常排第一），**只取返回行 `category` 等于所查类别的那一行**；债券代码传给 `fund` 命令会返回空结果、不报错。② **场外基金可按名称搜到**（`--category fund` 同时返回 `.OF` 与场内代码）。③ **计费单价按平台最新价目更新**：一页通等 AI 生成 10/次、业绩点评 / 观点 PK 20/次、热点话题 10/篇、个股看点 1/条、路演四件套 10/条、独立观点列表 1/条、纪要 / 外资研报 / 我的会议下载 30/篇、公告下载 A 股 1 / 港美股 2、`edb-data` 30/指标；额度保护随之调整。④ **数据范围**：`SKILL.md` 按官方权限表逐命令列出正式 / 试用两档，规划查询区间按表来。⑤ **报错口径**：EDE 漏传必填的 `fiscalYear` 报 `100001`；`main-business` / `valuation-analysis` 的 `--field` 写错名字报 `100005`；`screener` 计费按筛选前范围保守估算。完整列表见 CHANGELOG。
+
 - **v0.45.0 — 2026-10-07**：① **`vault drive-copy` 可复制整个文件夹**：`--folder-id` + `--target-parent-id`，连同子文件夹与文件复制到另一空间，返回 `{folderId, newFolderId}`；复制文件的写法不变，两组参数二选一。② **下载文件名**：响应同时给出 UTF-8 文件名与普通文件名时用 UTF-8 的那个。③ `GANGTISE_BASE_URL` 指向非本机地址却用 `http://` 时 stderr 提示一次（凭证会明文传输）。④ 文档：`bond daily-quote` / `bond valuation` 的数据可能比账号窗口短，**按年份取长序列时核对首行日期**；`bond announcement` 按日期查询时有代码的行都带后缀；基金只知道名称时怎么换代码；分钟 K 的可查历史是滚动的短窗口。
 
 - **v0.44.0 — 2026-09-30**：**新增 `fund` 公募基金 18 个命令，一律 0.4 积分/次**（按次，与返回行数、基金只数无关）：`basic-info` / `nav`（日频净值）/ `fee-rate` / `manager-info`（按姓名精确匹配，同名全返回）/ `manager-history` / `asset-size` / `holder-structure` / `top10-holders` / `asset-allocation` / `stock-portfolio` / `industry-allocation` / `bond-portfolio` / `bond-type-allocation` / `fund-portfolio` / `fund-type-allocation` / `etf-pcf-header` / `etf-pcf-components` / `etf-share-change`。`--security` 用带大写后缀的基金代码（场外 `.OF`，场内 `.SH` / `.SZ`），**代码不存在、不带后缀或后缀小写都返回空结果、不报错**。不分页：单次上限 10000 行，超出整批报 `100006`；日期两端都不传取账号可回溯窗口内的全部，起点早于窗口整批报 `110003`。**整族超时 / 5xx 不自动重发**（避免重复扣费）。取数前注意：各命令单位不同（元 / 万元 / 万份 / 万股）；`holder-structure` 的 `holderCount` 是带千分位的字符串；持仓明细只返回证券简称、不返回代码；`fund-type-allocation` 季报期只含重仓基金。逐条见 `gangtise-openapi/references/commands/fund.md`。**另有几处行为变化**：只收一个值的参数重复传直接报错；代码类列表也按顿号 / 分号 / 空格分隔并去重；显式 `--size` 与 `fundamental earning-forecast` 的日期区间估算超过 1000 积分同样要 `--yes`；jsonl / csv 文件一律以换行结尾，csv 不再给 `-3.5%` 这类值加 `'`；全市场分片早于账号窗口的部分跳过而不中止；接口返回下载链接时不带 `--output` 也会下载；A 股公告与 `ai knowledge-batch` 只写日期的 `--end-time` 按当日 23:59:59 换算；`--indicator-param` 里的日期值与 `--date` 同样校验；单次请求另有总时长上限（`GANGTISE_TIMEOUT_MS` 的 2 倍，下载与上传 60 倍）；环境变量设成空字符串按未设置处理。完整列表见 CHANGELOG。
@@ -14,10 +16,9 @@ README 仅列最近 5 个版本摘要：
 
 - **v0.43.0 — 2026-09-26**：① **按条计费列表的额度保护**：省略 `--size` 时先拿到 `total` 估算全量积分（整页超过 50 积分的列表只先取 1 条），超过 1000 积分报错退出 1，加 `--yes` 或传 `--size N` 放行。② **翻页结果的完整性**：跨页重复的行去掉并标 `duplicateRows`；同一 ID 在后面的页内容变了，两版都保留并标 `changedRows`；`total` 正好等于偏移窗口时标 `totalCapped`；都退出 3。热点话题、纪要、A 股 / 港股公告、财报日历查不到内容时按空结果、退出 0（此前退出 3）。③ **`quote` 的 `--field` 在多只证券或全市场时自动补身份列**（日 K 补 `securityCode` / `tradeDate`、分钟 K 补 `securityCode` / `tradeTime`、`realtime` 补 `securityCode`；单只不补），**多只证券只点一列的脚本输出会多出这些列**。④ **多证券日 K 合批**：按行数上限装入尽量多的证券，请求数大幅减少；全市场分片按工作日计（港股 2 个工作日一片），全市场关键字须同时给起止日期。⑤ **首行晚到提示**：行情首行比请求起点晚 14 天以上时 stderr 提示（上市较晚或越过回溯窗口）。⑥ **`ai stock-summary` 与 `fundamental earning-forecast` 超时 / 5xx 不再自动重试**（单次可能扣数千积分）。⑦ 四个枚举参数写错时本地报错；Ctrl-C / `kill` / 终端断开时清理暂存文件，进程以该信号结束（`$?` 为 130 / 143 / 129），脚本循环随之停下。⑧ Agent Skill 主文件精简，细节移到 `references/`。
 
-- **v0.42.0 — 2026-09-25**：① **数值参数只收十进制写法**：`--size 0x10`、`--size 1e3`、`--limit 5.0` 这类写法发请求前报错并点名参数（此前会被换算成 16 / 1000 / 5 照常发出）；数字列表类参数逐项要求整数。**脚本里用了这类写法的，请改成普通整数。** ② **接管道时保留退出码**：`gangtise … | head` 提前关掉读端时，以已判定的退出码（`3` / `4`）结束，此前一律 `0`；脚本用 `set -o pipefail` 即可看到。③ **`GANGTISE_TIMEOUT_MS` 只收整数毫秒**：低于 1 秒回退默认、高于 1 小时按 1 小时，所写数值没有按原样生效时 stderr 提示一次。④ 观点 `detail` 与估值分析的返回结构与约定不符时报错并附 trace，不再按空结果处理。⑤ `fundamental valuation-analysis` 的 `--field` 不含数值列、接口返回 0 行时，stderr 说明原因。⑥ 性能：大批量导出按块写盘；自动翻页时单个慢页对其余页的拖累更小；`GANGTISE_PAGE_CONCURRENCY` 设到 16 以上时并发随之增加。
-
 ### 历史里程碑
 
+- **v0.42.0**：数值参数只收十进制写法（`0x10` / `1e3` 这类写法发请求前报错）；接管道时保留退出码 `3` / `4`。
 - **v0.41.0**：新增债券 12 个命令与云盘管理 9 个命令；观点列表改走 v2（列表只含摘要 1 积分/条，正文按 ID 另取）；新增会议线索与联网搜索。
 - **v0.40.0**：自选股股票池可增删改（首批写操作，删池须显式 `--yes`）；`indicator time-series` 自动判定日期轴；Token 缓存绑定签发它的凭证。
 - **v0.39.0**：`csv` / `jsonl` 导出的元信息加上字节数与 `sha256`，转交前可核验；并发导出到同一 `--output` 不再互相掺混，文件被另一次导出替换时退出码 4。
@@ -167,7 +168,7 @@ install_skill ~/.hermes/skills               # Hermes
 | | `qa list` | 投资者问答 QA（互动平台/电话会议/调研纪要，按证券） |
 | | `report-image list` / `download` | 研报图表搜索（按关键词，含原图 JPEG 下载） |
 | | `highlight list` | 会议线索（会议核心要点信息流，按时间倒序；5 积分/条） |
-| **Reference** | `securities-search` | GTS Code 搜索（按名称/代码/拼音匹配） |
+| **Reference** | `securities-search` | GTS Code 搜索（按名称/代码/拼音匹配；`--category` 可选 stock / dr / index / fund / bond，按返回行的 `category` 取） |
 | | `chiefs-search` | 首席分析师 ID 搜索（按姓名/机构/团队匹配） |
 | | `institution-search` | 机构 ID 搜索（内资券商/外资/牵头/观点机构，按名称匹配） |
 | | `official-account-search` | 公众号 ID 搜索（按公众号名/机构/分类匹配，返回 accountId） |
@@ -243,7 +244,7 @@ install_skill ~/.hermes/skills               # Hermes
 | | `time-series` | 指标时间序列（多指标 × 单证券 或 单指标 × 多证券，按区间） |
 | | `screener` | 条件选股（按指标表达式从证券/板块范围筛股；前置 `search` 拿 code） |
 | **Alternative** | `edb-search` | 行业指标搜索（按关键词匹配，返回 indicatorId 等元信息） |
-| | `edb-data` | 行业指标时序数据（批量拉取，最多10个指标） |
+| | `edb-data` | 行业指标时序数据（批量拉取，最多10个指标；30 积分/指标） |
 | | `concept-info` | 题材指数基本信息（定义/投资逻辑/行业空间/竞争格局；50 积分/次，`--full` 另含催化事件 500 积分/次） |
 | | `concept-securities` | 题材指数成分股（按分组；50 积分/次，`--full` 另含重点个股标识与纳入理由 500 积分/次） |
 | **Tool** | `file-parse` / `file-parse-check` | PDF 解析为 Markdown + 图片（异步，返回 ZIP） |
@@ -304,7 +305,7 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 - **流式下载**：二进制响应（PDF 等）直接 `pipeline` 到磁盘，不经过内存缓冲；不带 `--output` 时先写入临时文件，定好文件名后再改名。50MB PDF 内存占用近乎为零。
 - **流式输出**：`--format jsonl` 或 `csv` 加 `--output <file>` 时，翻页 / 全市场分片 / 多证券分批请求的行**按到达顺序逐批写盘**，取数阶段不持有整份结果，内存不随行数增长；csv 先落临时行文件、收尾时按列并集写表头再转成 csv（磁盘两遍、内存不变）。jsonl / csv 无论写文件还是输出到终端都按批写出，每行以换行结尾。任一只 / 页 / 片失败，命令退出时后台已无取数与写盘，不留 `.part`。
 - **导出元信息**：`csv` / `jsonl` 落盘时旁边生成 `<文件>.meta.json`——命令行、数据行数、列名、`complete`（写元信息时的判定：退出 3 即 `false`）、`total` / `partial` / `failedPages` / `failedShards` / `truncatedShards` / `droppedColumns` / `missingFields` / `duplicateRows` / `changedRows` / `totalCapped` 等全部完整性标记（以及不影响完整性判定的 `outOfWindowShards`）、抓取时间与时区、CLI 版本，以及数据文件的字节数 `bytes` 与内容哈希 `sha256`。命令行与结果里的 key / secret / token 类字段写成 `[redacted]`。元信息在数据文件发布之后才就位，导出失败不会留下新数据配旧元信息。**转交或归档前建议核一次**：`shasum -a 256 <文件>` 与元信息里的 `sha256` 相等，才说明这份元信息描述的就是旁边这份数据——两个进程同时导出到**同一个 `--output`** 时，最终文件一定是其中某一次的完整产物，但旁边的元信息有可能来自另一次，核哈希就能发现。**输的那一次自己也会报**：收尾时核对 `--output` 是否仍是本次写出的文件（仍是同一个文件就不必回读，否则回读比对哈希），不符就在 stderr 说明「这个文件不是本次命令的产物」并**退出码 4**。这两种格式的文件本身只有数据行，转交之后靠它核验是否完整；`json` 自带标记，不生成。
-- **自动重试**：5xx / 429 / `ECONNREFUSED` / `ECONNRESET` / `ETIMEDOUT` / `ENOTFOUND` / `EAI_AGAIN` / `UND_ERR_*`（undici 连接/超时类）/ `999999` 系统错误自动指数退避重试 2 次。**不重放的端点例外**（贵档：one-pager 等生成/提交类 + `tool file-parse` 提交 + 50/篇 的 summary / foreign-report / my-conference 下载 + 单价未公布但保守同档的 pamirs-summary 下载 + 题材 `concept-info` / `concept-securities`（含 `--full`）；`bond` 全部 12 个命令（多数按次，三个评级命令按条 / 按债券 / 按发行人）、`fund` 全部 18 个命令（按次）与按次计费的 `tool web-search`；按条计费的 `insight highlight list`、观点 `detail` 与 `list --with-content`，以及单次最多 6000 只、按只计费的 `ai stock-summary` 与行数随日期区间增长的 `fundamental earning-forecast`；另加不计分但不可重复执行的 `vault stock-pool-create` 与云盘的上传 / 新建文件夹 / 复制 / 两个删除，共 64 个）：5xx/超时不重放，仅连接失败、429 与 token 自愈重试。**两类端点各有各的理由**：贵档是**重放会重复扣分**——服务端可能已经执行并计费，重发按次计费的再扣一次，重发按篇/按条计费的会把已交付的行再计一次；不计分的那几个是**重放会造成副作用或把成功报成失败**——股票池名不允许重复，重发一个其实已经建成的请求，回来的是 `230006 股票池名称重复`；云盘允许同名，重发上传 / 新建 / 复制会多出一份；重发一个其实已经删掉的删除，回来的是「文件不存在」或 `130002`。**`indicator`（EDE）端点对 `999999` 不重试**——重放一次已计费的查询没有意义（EDE 无数据不用此码，而是保留行列的占位单元格 `null`；代码或参数名写错报 `100003`、缺必填参数报 `100001`，漏传 `fiscalYear` 例外、不报错）。**终态码 `999011`（凭证无效）/ `140002`（终态失败：异步生成失败、参数错误或业务处理失败）在任何 HTTP 状态下都不重试**——凭证错不会因重试而变，`140002` 立即重发得到的还是同一结果。
+- **自动重试**：5xx / 429 / `ECONNREFUSED` / `ECONNRESET` / `ETIMEDOUT` / `ENOTFOUND` / `EAI_AGAIN` / `UND_ERR_*`（undici 连接/超时类）/ `999999` 系统错误自动指数退避重试 2 次。**不重放的端点例外**（贵档：one-pager 等生成/提交类 + `tool file-parse` 提交 + 30/篇 的 summary / foreign-report / my-conference 下载 + 单价未公布但保守同档的 pamirs-summary 下载 + 题材 `concept-info` / `concept-securities`（含 `--full`）；`bond` 全部 12 个命令（多数按次，三个评级命令按条 / 按债券 / 按发行人）、`fund` 全部 18 个命令（按次）与按次计费的 `tool web-search`；按条计费的 `insight highlight list`、观点 `detail` 与 `list --with-content`，以及单次最多 6000 只、按只计费的 `ai stock-summary` 与行数随日期区间增长的 `fundamental earning-forecast`；另加不计分但不可重复执行的 `vault stock-pool-create` 与云盘的上传 / 新建文件夹 / 复制 / 两个删除，共 64 个）：5xx/超时不重放，仅连接失败、429 与 token 自愈重试。**两类端点各有各的理由**：贵档是**重放会重复扣分**——服务端可能已经执行并计费，重发按次计费的再扣一次，重发按篇/按条计费的会把已交付的行再计一次；不计分的那几个是**重放会造成副作用或把成功报成失败**——股票池名不允许重复，重发一个其实已经建成的请求，回来的是 `230006 股票池名称重复`；云盘允许同名，重发上传 / 新建 / 复制会多出一份；重发一个其实已经删掉的删除，回来的是「文件不存在」或 `130002`。**`indicator`（EDE）端点对 `999999` 不重试**——重放一次已计费的查询没有意义（EDE 无数据不用此码，而是保留行列的占位单元格 `null`；代码或参数名写错报 `100003`、缺必填参数报 `100001`）。**终态码 `999011`（凭证无效）/ `140002`（终态失败：异步生成失败、参数错误或业务处理失败）在任何 HTTP 状态下都不重试**——凭证错不会因重试而变，`140002` 立即重发得到的还是同一结果。
 
 <!-- no-replay-endpoints
      上面那句点名的「不重放」端点，完整清单如下（endpoint key，与 `gangtise raw list` 一致）：
@@ -411,7 +412,7 @@ vault.stock-pool.create
 
 规则：
 - **省略 `--size` 一律拉全量**（无论是否传时间范围），CLI 自动翻页查完
-- **按条计费的列表有额度保护**：省略 `--size` 时，CLI 先拿到 `total`，按 `total × 单价` 估算全量要花的积分，超过 1000 积分就报错、退出码 1，不再往下拉，报错写明估算值。整页不超过 50 积分的列表用第一页拿 `total`；整页更贵的（路演 / 调研 / 策略会 / 论坛、独立观点、会议线索、个股线索、热点话题、`--with-content`）先只取 1 条：结果最多 1 条时它就是全部结果；否则放行后从头翻页，这 1 条会多计一次费（知道要多少条就直接传 `--size N`，不走这一步）。确认要全量就加 `--yes`，只要一部分就传 `--size N`——显式 `--size` 按 `min(--size, total) × 单价` 估算仍超过 1000 积分时同样报错（`--size 100000` 不能当「全量」绕过），要 `--yes`。`fundamental earning-forecast` 不分页，按日期区间估算（工作日数 × 3 条 × 0.5），同一条线。免费列表不受影响
+- **按条计费的列表有额度保护**：省略 `--size` 时，CLI 先拿到 `total`，按 `total × 单价` 估算全量要花的积分，超过 1000 积分就报错、退出码 1，不再往下拉，报错写明估算值。整页不超过 50 积分的列表用第一页拿 `total`；整页更贵的（路演 / 调研 / 策略会 / 论坛、会议线索、个股线索、热点话题、`--with-content`）先只取 1 条：结果最多 1 条时它就是全部结果；否则放行后从头翻页，这 1 条会多计一次费（知道要多少条就直接传 `--size N`，不走这一步）。确认要全量就加 `--yes`，只要一部分就传 `--size N`——显式 `--size` 按 `min(--size, total) × 单价` 估算仍超过 1000 积分时同样报错（`--size 100000` 不能当「全量」绕过），要 `--yes`。`fundamental earning-forecast` 不分页，按日期区间估算（工作日数 × 3 条 × 0.5），同一条线。免费列表不受影响
 - 数据量未知时，可先 `--size 1` 从 stderr 的 `Total: N` 探明量级，再决定是否全量
 - 如果显式传了 `--size`，则按指定值翻页，直到达到 `size` 或数据取完
 - `--from` 必须是非负整数，`--size` 必须是正整数；非法数字会在本地直接报 `ValidationError`，不会继续请求 API
@@ -433,7 +434,7 @@ vault.stock-pool.create
 
 推荐工作流：先 `list` 再 `download`，文件名自动正确且零额外成本。
 
-🔴 **缓存未命中时不会自动回查 list 接口**。回查要拉最近 200 条记录（4 次请求），而这些 list 多数按 **0.1 积分/条**计费，约 20 积分——这笔开销只用于取一个更易读的文件名（下载本身 10–50 积分），所以默认不回查。需要时加 `--resolve-title`：
+🔴 **缓存未命中时不会自动回查 list 接口**。回查要拉最近 200 条记录（4 次请求），而这些 list 多数按 **0.1 积分/条**计费，约 20 积分——这笔开销只用于取一个更易读的文件名（下载本身 1–30 积分），所以默认不回查。需要时加 `--resolve-title`：
 
 ```bash
 gangtise insight research download --report-id 432092410345574400 --resolve-title
@@ -530,7 +531,7 @@ gangtise insight summary download --summary-id 4906813 --file-type 2
 # 财报日历：注意用 --start-date/--end-date（按 publishDate 过滤），不是 --start-time
 gangtise insight performance-calendar list --start-date 2026-07-01 --end-date 2026-07-25 \
   --market aShares --category performanceForecast --size 20 --format json
-# 下载业绩报告原文（仅 hasAttachment: true 的记录；A股 10 积分 / 港美股 20 积分）
+# 下载业绩报告原文（仅 hasAttachment: true 的记录；A股 1 积分 / 港美股 2 积分）
 gangtise insight performance-calendar download --performance-report-id 33753017 --output ./业绩预告.pdf
 
 # 会议线索：会议核心要点信息流（按时间倒序；5 积分/条，务必带 --size 控量）
@@ -550,6 +551,8 @@ gangtise reference securities-search --keyword "贵州茅台" --category stock
 gangtise reference securities-search --keyword "600519" --category stock
 gangtise reference securities-search --keyword gzmt --top 5
 gangtise reference securities-search --keyword "银行" --category stock --category index
+# 债券：按代码或简称查，代码用于 bond 命令组；按简称查股票时同名可转债也会出现，按返回的 category 取
+gangtise reference securities-search --keyword 甬金转债 --category bond
 
 # 首席分析师 ID 搜索（按姓名/机构/团队；拿 chiefId 供 insight opinion list --chief 使用）
 gangtise reference chiefs-search --keyword 东吴证券 --top 3 --format json
@@ -869,7 +872,6 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 
 # 必填参数：缺了会报 100001 并点名，按 parameterList 的 required 补齐再取：
 #   N 期统计补 periodNum、年度/分红/预测类补 fiscalYear；区间类要特定区间时传 sDate（可选，起始日，tradeDate 仍是终点）
-#   ⚠️ fiscalYear 漏传不报错：按一个服务端自定的默认年度取数（不随 --date 变），该年度有数就返回它、看着正常，没有就是 null，要显式传
 # finc_roe_avg_avg 是报告期类，日期用 reportDate：
 gangtise indicator cross-section --indicator finc_roe_avg_avg --security 600519.SH \
   --date 2026-03-31 --indicator-param "finc_roe_avg_avg:periodNum=4" \

package/dist/src/commands/bond.js

@@ -13,7 +13,7 @@ function requireBondCodes(codes, max) {
     return unique;
 }
 const bondSecurityOption = (command) => command
-    .option("--security <code>", "Bond code, e.g. 019742.SH / 123456.SZ / 220205.IB (repeatable). Short names and pinyin are rejected — resolve them with 'reference securities-search' first", collectList, [])
+    .option("--security <code>", "Bond code, e.g. 019742.SH / 123456.SZ / 220205.IB (repeatable). Short names and pinyin are rejected — resolve them with 'reference securities-search --category bond' first", collectList, [])
     .option("--field <field>", "Field to return (repeatable); omit for all. An unsupported name rejects the whole call with 100003", collectList, [])
     .option("--format <format>", "Output format", "table").option("--output <path>");
 const addBondRange = (name, endpointKey, describe, rangeHelp, max) => bondSecurityOption(bond.command(name).description(describe))

package/dist/src/commands/fund.js

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import { collectNames } from "../core/args.js";
 import { date, format, list, output, query, requiredList, value } from "./shared.js";
 export const fund = new Command("fund").description("Fund APIs: profiles, NAV, fees, managers, scale, holders, holdings and allocation, ETF creation/redemption");
-const code = () => requiredList("--security <code>", "Fund code, e.g. 005827.OF / 159967.SZ / 510300.SH (repeatable, comma-separated accepted)", "fundCodeList");
+const code = () => requiredList("--security <code>", "Fund code, e.g. 005827.OF / 159967.SZ / 510300.SH (repeatable, comma-separated accepted). From a fund name: 'reference securities-search --category fund', keeping only rows whose category is fund", "fundCodeList");
 const range = (what) => [
     date("--start-date <date>", `${what} range start (yyyy-MM-dd); omit both ends for everything in your account's history window`, "startDate"),
     date("--end-date <date>", `${what} range end (yyyy-MM-dd)`, "endDate"),

package/dist/src/commands/reference.js

@@ -5,7 +5,7 @@ query(reference, "securities-search", {
     endpoint: "reference.securities-search",
     fields: [
         required("--keyword <text>", "Search keyword (name/code/pinyin/English)", "keyword"),
-        choiceList("--category <type>", "Category: stock/dr/index/fund", "category", ["stock", "dr", "index", "fund"]),
+        choiceList("--category <type>", "Category: stock/dr/index/fund/bond. Convertible bonds can come back under any category — keep the rows whose returned category matches", "category", ["stock", "dr", "index", "fund", "bond"]),
         top(10),
         format(), output(),
     ],

package/dist/src/core/client.js

@@ -550,7 +550,7 @@ export class GangtiseClient {
         }).catch((error) => {
             const isIndicatorFetch = endpoint.key === 'indicator.cross-section' || endpoint.key === 'indicator.time-series' || endpoint.key === 'indicator.screener';
             if (isIndicatorFetch && error instanceof ApiError && error.code === '999999') {
-                throw new ApiError(error.message, error.code, error.statusCode, error.details, error.retryAfterMs, 'EDE 取数故障。先核对参数再重试：参数名以 indicator search 的 parameterList 为准（传错名会报 100003 并指名）、日期匹配指标周期（财务报表类用报告期末如 2025-12-31，PE/PB 等日频估值用交易日）、标的在 scopeList 覆盖内、required 参数已补。注意此码不表示无数据——无数据返回保留行列的 null 单元格；code 或参数名写错报 100003、缺必填参数报 100001，都会指名（fiscalYear 例外：漏传不报错，返回 null 或默认年度的值）。');
+                throw new ApiError(error.message, error.code, error.statusCode, error.details, error.retryAfterMs, 'EDE 取数故障。先核对参数再重试：参数名以 indicator search 的 parameterList 为准（传错名会报 100003 并指名）、日期匹配指标周期（财务报表类用报告期末如 2025-12-31，PE/PB 等日频估值用交易日）、标的在 scopeList 覆盖内、required 参数已补。注意此码不表示无数据——无数据返回保留行列的 null 单元格；code 或参数名写错报 100003、缺必填参数报 100001，都会指名。');
             }
             throw error;
         });

package/dist/src/core/endpoints.js

@@ -89,7 +89,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/summary/v2/download/file",
         kind: "download",
         description: "Download summary file",
-        billing: { per: "document", price: 50 },
+        billing: { per: "document", price: 30 },
         retry: "no-replay",
     },
     "insight.pamirs-summary.list": {
@@ -112,7 +112,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/schedule/roadshow/getList",
         kind: "json",
         description: "List roadshows",
-        billing: { per: "row", price: 20 },
+        billing: { per: "row", price: 10 },
         pagination: { enabled: true, maxPageSize: 50 },
         rowId: "id",
         rowIdUnverified: true,
@@ -122,7 +122,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/schedule/site-visit/getList",
         kind: "json",
         description: "List site visits",
-        billing: { per: "row", price: 20 },
+        billing: { per: "row", price: 10 },
         pagination: { enabled: true, maxPageSize: 50 },
         rowId: "id",
         rowIdUnverified: true,
@@ -132,7 +132,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/schedule/strategy-meeting/getList",
         kind: "json",
         description: "List strategy meetings",
-        billing: { per: "row", price: 20 },
+        billing: { per: "row", price: 10 },
         pagination: { enabled: true, maxPageSize: 50 },
         rowId: "id",
         rowIdUnverified: true,
@@ -142,7 +142,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/schedule/forum/getList",
         kind: "json",
         description: "List forums",
-        billing: { per: "row", price: 20 },
+        billing: { per: "row", price: 10 },
         pagination: { enabled: true, maxPageSize: 50 },
         rowId: "id",
         rowIdUnverified: true,
@@ -160,8 +160,8 @@ const ENDPOINT_DEFS = {
         method: "GET",
         path: "/application/open-insight/schedule/performance-calendar/download/file",
         kind: "download",
-        description: "Download an earnings report file (A-share 10 credits, HK/US 20)",
-        billing: { per: "document", price: 20 },
+        description: "Download an earnings report file (A-share 1 credit, HK/US 2)",
+        billing: { per: "document", price: 2 },
     },
     "insight.research.list": {
         method: "POST",
@@ -193,7 +193,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/foreign-report/download/file",
         kind: "download",
         description: "Download foreign report",
-        billing: { per: "document", price: 50 },
+        billing: { per: "document", price: 30 },
         retry: "no-replay",
     },
     "insight.announcement.list": {
@@ -210,7 +210,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/announcement/download/file",
         kind: "download",
         description: "Download A-share announcement file",
-        billing: { per: "document", price: 10 },
+        billing: { per: "document", price: 1 },
     },
     "insight.announcement-hk.list": {
         method: "POST",
@@ -226,7 +226,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/announcement-hk/download/file",
         kind: "download",
         description: "Download HK announcement file",
-        billing: { per: "document", price: 20 },
+        billing: { per: "document", price: 2 },
     },
     "insight.announcement-us.list": {
         method: "POST",
@@ -242,7 +242,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/announcement-us/download/file",
         kind: "download",
         description: "Download US announcement file",
-        billing: { per: "document", price: 20 },
+        billing: { per: "document", price: 2 },
     },
     "insight.foreign-opinion.list": {
         method: "POST",
@@ -276,7 +276,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/independent-opinion/getList",
         kind: "json",
         description: "List foreign independent analyst opinions",
-        billing: { per: "row", price: 5 },
+        billing: { per: "row", price: 1 },
         pagination: { enabled: true, maxPageSize: 50 },
         rowId: "independentOpinionId",
         rowIdUnverified: true,
@@ -812,7 +812,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-ai/stock-summary/getList",
         kind: "json",
         description: "Stock highlights (refined research summary per security)",
-        billing: { per: "row", price: 3, maxUnits: 6000 },
+        billing: { per: "row", price: 1, maxUnits: 6000 },
         retry: "no-replay",
         timeoutMs: 120_000,
     },
@@ -843,7 +843,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-ai/agent/one-pager",
         kind: "json",
         description: "Generate one pager",
-        billing: { per: "call", price: 50 },
+        billing: { per: "call", price: 10 },
         timeoutMs: 120_000,
         retry: "no-replay",
     },
@@ -852,7 +852,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-ai/agent/investment-logic",
         kind: "json",
         description: "Generate investment logic",
-        billing: { per: "call", price: 50 },
+        billing: { per: "call", price: 10 },
         timeoutMs: 120_000,
         retry: "no-replay",
     },
@@ -861,7 +861,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-ai/agent/peer-comparison",
         kind: "json",
         description: "Generate peer comparison",
-        billing: { per: "call", price: 50 },
+        billing: { per: "call", price: 10 },
         timeoutMs: 120_000,
         retry: "no-replay",
     },
@@ -870,7 +870,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-ai/agent/earnings-review-getid",
         kind: "json",
         description: "Get earnings review ID",
-        billing: { per: "call", price: 50 },
+        billing: { per: "call", price: 20 },
         retry: "no-replay",
     },
     "ai.earnings-review.get-content": {
@@ -884,7 +884,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-ai/agent/theme-tracking",
         kind: "json",
         description: "Get theme tracking daily report",
-        billing: { per: "call", price: 50 },
+        billing: { per: "call", price: 10 },
         timeoutMs: 120_000,
         retry: "no-replay",
     },
@@ -893,7 +893,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-ai/agent/research-outline",
         kind: "json",
         description: "Get company research outline",
-        billing: { per: "call", price: 50 },
+        billing: { per: "call", price: 10 },
         timeoutMs: 120_000,
         retry: "no-replay",
     },
@@ -902,7 +902,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-ai/hot-topic/getList",
         kind: "json",
         description: "List hot topic reports",
-        billing: { per: "row", price: 50 },
+        billing: { per: "row", price: 10 },
         pagination: { enabled: true, maxPageSize: 20 },
         retry: "no-replay",
     },
@@ -911,7 +911,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-ai/management-discuss/from-announcement",
         kind: "json",
         description: "Management discussion from financial reports (half-year/annual)",
-        billing: { per: "call", price: 10 },
+        billing: { per: "call", price: 5 },
         timeoutMs: 120_000,
         retry: "no-replay",
     },
@@ -929,7 +929,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-ai/agent/viewpoint-debate-getid",
         kind: "json",
         description: "Get viewpoint debate ID",
-        billing: { per: "call", price: 50 },
+        billing: { per: "call", price: 20 },
         retry: "no-replay",
     },
     "ai.viewpoint-debate.get-content": {
@@ -1045,7 +1045,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-vault/my-conference/download/file",
         kind: "download",
         description: "Download my conference resource",
-        billing: { per: "document", price: 50 },
+        billing: { per: "document", price: 30 },
         retry: "no-replay",
     },
     "vault.wechat-message.list": {
@@ -1122,6 +1122,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-alternative/EDB/getData",
         kind: "json",
         description: "Get industry indicator time-series data by indicator ID list",
+        billing: { per: "indicator", price: 30, maxUnits: 10 },
     },
     "alternative.concept-info": {
         method: "POST",

package/dist/src/core/normalize.js

@@ -7,7 +7,7 @@ function traceSuffix(source) {
 }
 export function zipFieldRow(fields, row, source) {
     if (row.length !== fields.length) {
-        throw new ValidationError(`响应字段数与 fieldList 不匹配（fieldList ${fields.length} 项、该行返回 ${row.length} 个值）——按位置拍平会把值贴到错误的字段上，已拒绝输出。带 --field 的命令多为传了该接口不存在的字段名（上游只返回有效字段的值、字段名却按请求回显）：核对 --field 取值（如 quote realtime 没有 close，最新价是 latestPrice），不确定就不传 --field（返回全量字段最稳）。没有 --field 的命令（如 alternative edb-data）出现此错，是上游响应结构异常，请报障${traceSuffix(source)}。`);
+        throw new ValidationError(`响应字段数与 fieldList 不匹配（fieldList ${fields.length} 项、该行返回 ${row.length} 个值）——按位置拍平会把值贴到错误的字段上，已拒绝输出。这是响应结构异常：带 --field 的命令先去掉 --field 重试（返回全量字段最稳）；没有 --field 的命令（如 alternative edb-data）或去掉后仍报此错，请报障${traceSuffix(source)}。`);
     }
     return fields.reduce((acc, field, index) => {
         acc[String(field)] = row[index];

package/gangtise-openapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gangtise-openapi
-version: "0.45.0"
+version: "0.46.0"
 description: |-
   通过 gangtise CLI 直接调用 Gangtise OpenAPI，拉取投研原始数据、批量导出、下载文件、调用 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` 取 `list[0].gtsCode`。
+3. **公司名 → 证券代码**：先查下方速查表（几只常用大盘股），其余一律 `gangtise reference securities-search --keyword <名> --category stock`，取第一条 `category` 为 `stock` 的 `gtsCode`（按简称查时同名可转债可能排在前面）。
 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`**（截取的是窗口开头）。
@@ -38,7 +38,7 @@ description: |-
    - 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`）一律用 `--security`。
 9. **调试**：`--verbose` 或 `GANGTISE_VERBOSE=1` 打印每个请求的耗时/字节数到 stderr。
-10. **`--field` 字段名必须核对，不确定就别传**（返回全量最稳）。上游对不存在的字段名有两种处理：`quote` 系（realtime / day-kline / minute-kline / fund-flow）名和值一起丢、不报错——CLI 比对请求与返回的列名，缺列标 `partial` + `missingFields` 并退出 3；`fundamental main-business` / `valuation-analysis` 只丢值、字段名照请求回显——CLI 检测到长度不匹配直接报错退出 1（没有 `--field` 的命令如 `alternative edb-data` 报此错则是上游响应结构异常，报障时带上报错末尾的 `（trace …）`）。多只证券或全市场时，缺的身份列 CLI 会补到最前（日 K 补 `securityCode` / `tradeDate`、分钟 K 补 `securityCode` / `tradeTime`、realtime 补 `securityCode`）；单只不补。realtime **无 `close`**（用 `latestPrice`）、**无市值**（总市值走 `indicator cross-section --indicator qte_mkt_cptl`，A/港/美股均有数）。
+10. **`--field` 字段名必须核对，不确定就别传**（返回全量最稳）。上游对不存在的字段名：`quote` 系（realtime / day-kline / minute-kline / fund-flow）名和值一起丢、不报错——CLI 比对请求与返回的列名，缺列标 `partial` + `missingFields` 并退出 3；`fundamental main-business` / `valuation-analysis` 报 `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` 筛出空集是**日期用错，不是没有符合条件的标的**。时序按日返回、只有报告期末那几行是真值，**别对整列直接求均值 / 求和**。**`--calendar-type` 默认别传**（CLI 自动选日期轴；显式传 `TD` 会让报告期类指标整行 `null`）。详见 `references/commands/indicator.md`。
 
 ## 工作流（3 步）
@@ -77,19 +77,19 @@ description: |-
 
 - **免费**：所有 `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）**：independent-opinion list 与 `ai security-clue` 5；roadshow/site-visit/strategy/forum list 20；**opinion / foreign-opinion list 1（只含摘要 `brief`）**，要正文用 `detail` 30/条或 `list --with-content` 30/条；`fundamental earning-forecast` 0.5；`ai stock-summary` 3（无看点的证券不返回也不扣）；`alternative edb-data` 30
-- **各 download（/篇）**：announcement / official-account / research 10；announcement-hk / announcement-us 20；independent-opinion 30；summary / foreign-report / my-conference 50；`performance-calendar download` A 股 10 / 港美股 20
+- **按条（观点/含详情类 list）**：`ai security-clue` 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`
 - **按页**：`tool file-parse` 0.8/页，**提交（`--file`）时按实际页数一次性扣**，取结果（`file-parse-check`）免费——50 页 PDF = 40 积分，别重复提交同一文件
-- 🔴 **按次贵**：`ai knowledge-batch` 10、`management-discuss-*` 10；AI Agent（`one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `earnings-review` / `viewpoint-debate` / `theme-tracking`）**50/次**
-- 🔴 **`ai hot-topic` 50/篇，按返回条数计**（不是按调用次数）。📌 **一「篇」= 一整份报告**（一份早报 / 午报 / 盘中快报 / 晚报），**不是报告里的一条话题**——一份报告通常包含多条热点话题。所以 `--size 20` 的一页 = 最多 20 份报告 = 1000 积分，**先用 `--start-date`/`--end-date` + `--category` 收窄再拉**，别省略 `--size` 直接全量。**可查的历史范围跟账号权限走**（试用档是滚动的「当前 −1 个月」，正式/定制档更长）——超出范围的日期返回空结果而不是报错，拿到空先想想是不是撞了权限窗口
+- 🔴 **按次**：`ai knowledge-batch` 10、`management-discuss-earnings-call` 10、`management-discuss-announcement` 5；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`（50/篇）、`ai stock-summary`（3/条，无看点总结的个股不进返回列表也不计费）、AI 生成类（`one-pager` 等 50/次），以及按次计费的 `ai knowledge-batch`、题材、`tool web-search` 都是这样。**所以「先小范围试探再放大」是安全的**——先用窄条件确认能查到东西，再扩范围。⚠️ **「成功返回」按服务端算**：超时报错时服务端可能已经生成并返回了内容（只是客户端没收到），这次已经扣过，同参数重调会再扣一次；异步的 `earnings-review` / `viewpoint-debate` 在提交成功（拿到任务 ID）时就扣，之后生成失败不退。**单价未公布的** `pamirs-summary`（见下）别据此假定
+- ✅ **扣费发生在接口成功返回数据之后**（平台计费规则）：没查到内容（空结果）、报错都不扣分——各 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 不自动重放**（共 64 个，完整清单见下方注释块：按次计费的 AI Agent 那批、`ai knowledge-batch` / `management-discuss-*` / `hot-topic`、题材两接口（含 `--full`）、`bond` 与 `fund` 全部命令、`tool web-search`、`tool file-parse` 提交；50/篇 的几个 download；按条计费的 `insight highlight list`、观点 `detail` / `list --with-content`、`ai stock-summary` 与 `fundamental earning-forecast`；以及不计分但重放有副作用的 `vault stock-pool-create` 与云盘上传 / 新建文件夹 / 复制 / 删除）。仅连接失败、429 与 token 自愈会重试。服务端可能已经执行并计费，重放会重复扣分、多建一份或把成功报成失败——**一次调用给足超时比失败重跑省钱**
+- ⚠️ **这些端点超时 / 5xx 不自动重放**（共 64 个，完整清单见下方注释块：按次计费的 AI Agent 那批、`ai knowledge-batch` / `management-discuss-*` / `hot-topic`、题材两接口（含 `--full`）、`bond` 与 `fund` 全部命令、`tool web-search`、`tool file-parse` 提交；summary / foreign-report / my-conference 三个 download；按条计费的 `insight highlight list`、观点 `detail` / `list --with-content`、`ai stock-summary` 与 `fundamental earning-forecast`；以及不计分但重放有副作用的 `vault stock-pool-create` 与云盘上传 / 新建文件夹 / 复制 / 删除）。仅连接失败、429 与 token 自愈会重试。服务端可能已经执行并计费，重放会重复扣分、多建一份或把成功报成失败——**一次调用给足超时比失败重跑省钱**
 
 <!-- no-replay-endpoints
      上面那句点名的「不重放」端点，完整清单如下（endpoint key，与 `gangtise raw list` 一致）：
@@ -158,28 +158,45 @@ vault.drive.upload
 vault.my-conference.download
 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` 按下游资源计费
+- **按单元格**：`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` 行情 / `fundamental` 财报、主营、估值、股东 / `indicator`（EDE） | 前溯 **5 年** |
-| `bond daily-quote` / `bond valuation` / `bond issuance-plan` | 前溯 **5 年**（试用账号 3 年） |
-| `bond` 其余命令 | **不限**（返回最新静态资料或全部历史记录） |
-| `fund` 净值 / 规模 / 持有人 / 资产配置 / 持仓与分布 / `etf-share-change` | 前溯 **5 年**（试用账号 3 年）；两端日期都不传 = 窗口内全部 |
-| `fund` 其余命令（`basic-info` / `fee-rate` / 经理两个 / `etf-pcf-*`） | **不限**（返回当前资料或全部任职记录） |
-| `insight highlight list` 会议线索 | 前溯 **3 个月**（试用账号 1 个月） |
-| `ai security-clue` 投研线索 | 前溯 **1 个月** |
-| 主题 / 热点 / QA / 日程（路演·调研·策略会·论坛）/ 纪要 / 观点 / 研报 / 公众号 | 前溯 **3 个月** |
-| 管理层讨论 / A·港·美股公告 / `alternative edb-*` 行业指标 | 前溯 **3 年** |
-| `insight pamirs-summary` 帕米尔纪要 | **不限**（但需单独购买专家纪要库） |
-
-⚠️ **实际窗口按账号配**，换接口绕不过去（`indicator` 与 `quote day-kline` 同界）。整段在界外返回 `110003`（不是空结果），把日期移进范围或联系客户经理。🔴 **区间跨过下界时各接口不同**：`quote` 日 K / 分钟 K / 资金流向与 `fundamental valuation-analysis` 从下界起返回、**不报错**（首行明显晚于起始日时 CLI 在 stderr 提示）；`indicator`、`bond` 与 `fund` 整批报 `110003`；`bond daily-quote` / `bond valuation` 的数据还可能比账号窗口短——区间早于数据起点时返回 `130001`，跨过数据起点时从有数据的那天起返回、不报错，核对首行日期。**例外**：`quote minute-kline` 窗口短得多且随日期滚动，整段在窗外返回空结果、不报错（CLI 在 stderr 提示）；`ai hot-topic` 超出账号可查范围时也返回空结果、不报错。
+| 命令 | 正式账号 | 试用账号 |
+|------|------|------|
+| `quote day-kline` / `fund-flow` | **5 年** | 3 年 |
+| `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` | 最新截面 | 最新截面 |
+| `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 theme-tracking` | **1 个月** | 1 个月 |
+| `ai management-discuss-*` | **1 年** | 1 年 |
+| `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`，跨过数据起点时从有数据的那天起返回、不报错，核对首行日期。**例外**：`quote minute-kline` 窗口只有 1 个月且随日期滚动，整段在窗外返回空结果、不报错（CLI 在 stderr 提示）；`ai hot-topic` 超出账号可查范围时也返回空结果、不报错。
 
 ### 下载规则（`--file-type` / `--content-type`）
 
@@ -199,7 +216,7 @@ vault.stock-pool.create
 
 省略 `--output` 时 CLI 用本地 title-cache 里的真实标题做文件名（`independent-opinion` 与 `report-image` 的下载不在此列，也没有 `--resolve-title`）——**只读缓存**，命中就零额外调用。缓存由同端点的 `list` 写入，所以「先 `list` 再 `download`」这个正常工作流本来就免费拿到正确文件名。
 
-🔴 **未命中时默认不回查**，退回服务端文件名或 `<type>-<id>.<ext>`。要回查得显式加 `--resolve-title`——它拉最近 200 条（4 次请求），而这些 list 多数按 **0.1 积分/条**计费，约 20 积分，只用于取一个更易读的文件名（下载本身 10–50）。**批量下载或按 ID 下旧文件**时：要么先跑一次 `list` 把标题灌进缓存，要么直接 `--output ./<名>.<ext>` 自己定名；`--resolve-title` 会把取回的 200 条一并写回缓存，同批后续下载不再重复消耗。
+🔴 **未命中时默认不回查**，退回服务端文件名或 `<type>-<id>.<ext>`。要回查得显式加 `--resolve-title`——它拉最近 200 条（4 次请求），而这些 list 多数按 **0.1 积分/条**计费，约 20 积分，只用于取一个更易读的文件名（下载本身 1–30）。**批量下载或按 ID 下旧文件**时：要么先跑一次 `list` 把标题灌进缓存，要么直接 `--output ./<名>.<ext>` 自己定名；`--resolve-title` 会把取回的 200 条一并写回缓存，同批后续下载不再重复消耗。
 
 ## 意图路由表
 
@@ -255,7 +272,7 @@ vault.stock-pool.create
 | 评级调整 / 评级变动历史 | `bond rating-change`（债项评级，最多 10 只）、`bond issuer-rating-change`（主体评级，`--security` 或 `--issuer` 二选一） |
 | 利率债发行计划 / 国债发行安排 | `bond issuance-plan`（**只按日期区间查，不收债券码**） |
 | 含权债行权 / 回售 / 赎回提示 | `bond exercise-notice` |
-| 基金资料 / 基金分类 / 管理人 / 成立日 / 业绩基准 / 跟踪指数 / 风险等级 | `fund basic-info`（`--security` 用 `005827.OF` / `159967.SZ` 这类带后缀代码；只知道名称时，场内基金用 `reference securities-search --keyword <场内简称或 6 位代码> --category fund` 换代码（全称常搜不到），场外 `.OF` 搜不到、需自备；`--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` 区分） |
@@ -306,10 +323,10 @@ vault.stock-pool.create
   - 单证券 → 优先 `fundamental` 专用命令（多数免费 / 低价）；多证券批量取**已实现**指标 → `indicator`（EDE）一次拉取：同一日期 / 报告期横比用 `cross-section`，区间走势用 `time-series`（不能多指标 × 多证券同时）
   - 始终不走 EDE：盈利预测 / 一致预期 → `fundamental earning-forecast`（EDE 的 EPS 是已实现值，**不能冒充预测**）；A 股估值历史分位 → `valuation-analysis`；行情与 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` 等）一律显式给——漏传**不报错**，按一个服务端自定的默认年度取数（不随 `--date` 变）：该年度有数就返回它、看着完全正常，没有就是 `null`。日频估值（`finc_pe_ttm` / `finc_pb_mrq`）用最新交易日，用报告期末日期会取到陈值；参数名同样以 `parameterList` 为准（复权是 `adjustType`）
-  - 结果**按 `security` 字段取值**，别按请求下标对位（证券会按代码升序重排）；批量回填加 `--key-by code`
+  - 日期参数**只看 `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`）
+  - 结果**按 `security` 字段取值**，别按请求下标对位（证券的返回顺序不作保证）；批量回填加 `--key-by code`
   - 估值历史：EDE 与 `valuation-analysis` 的财报口径切换时点与财报版本都不同，做分位 / 回测两边都拉交叉核
-- "业绩点评"双义消歧：**检索已有**的业绩点评：研报走 `insight research list --llm-tag earningsReview`（0.1/条；`--llm-tag` 只有 `opinion` / `research` / `foreign-report` 三个列表有），业绩会纪要走 `insight summary list --category earningsCall`；**AI 现生成**一份走 `ai earnings-review`（异步、50/次）。不确定问一句
+- "业绩点评"双义消歧：**检索已有**的业绩点评：研报走 `insight research list --llm-tag earningsReview`（0.1/条；`--llm-tag` 只有 `opinion` / `research` / `foreign-report` 三个列表有），业绩会纪要走 `insight summary list --category earningsCall`；**AI 现生成**一份走 `ai earnings-review`（异步、20/次）。不确定问一句
 
 ## 公司名 → 证券代码
 
@@ -329,7 +346,7 @@ vault.stock-pool.create
 ```bash
 gangtise reference securities-search --keyword <公司名> --category stock --top 3 --format json
 ```
-取 `list[0].gtsCode`（CLI 已剥掉信封，输出顶层就是 `{returnedCount, list}`）。matchScore < 0.5 时让用户从前 3 条选。
+取第一条 `category` 为 `stock` 的 `gtsCode`（CLI 已剥掉信封，输出顶层就是 `{returnedCount, list}`）——**别直接取 `list[0]`**：按简称查时同名可转债（`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`，**别猜**）。
 

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

@@ -49,7 +49,7 @@ gangtise ai investment-logic --security-code <code>
 gangtise ai peer-comparison  --security-code <code>
 ```
 
-- **积分**：50/次（按次计费，重复调用每次都扣；超时不自动重发）
+- **积分**：10/次（按次计费，重复调用每次都扣；超时不自动重发）
 
 - 都支持 A 股 / 港股
 - 返回 `{content: "markdown"}`（`one-pager` 另带 `date`，即一页通的生成日期；取的是该公司最新一份）— 直接呈现 content
@@ -61,10 +61,10 @@ gangtise ai peer-comparison  --security-code <code>
 gangtise ai stock-summary --security <code> [--security <code2> ...]
 ```
 
-- `--security`（**必选**，可重复）：**只收具体证券代码**，单次最多 6000 个（接口上限，CLI 同值拦截，超过报错并提示分批）——全 A 股可一次提交完，但**按返回条数 3 积分/条计**，数千只就是上万积分，提交前先把估算总价告诉用户
+- `--security`（**必选**，可重复）：**只收具体证券代码**，单次最多 6000 个（接口上限，CLI 同值拦截，超过报错并提示分批）——全 A 股可一次提交完，但**按返回条数 1 积分/条计**，数千只就是数千积分，提交前先把估算总价告诉用户
 - 🔴 **不支持全市场批量**：`aShares` / `hkStocks` 这类市场关键词不被接受，CLI 会本地报错（服务端对它们返 `120001`，读起来像代码写错，容易误判）。需要覆盖一批标的就先用 `reference securities-search` 或自有清单取到代码，再分批传入
 - **仅支持 A 股和港股**
-- **积分**：`3`/条；个股若无看点总结则不在返回列表中，也不扣分——所以**返回行数少于提交数是正常的**，不是丢了数据。超时 / 5xx **不自动重试**（一次最多可扣 18000 积分，重放可能重复扣分）：CLI 已给它 120 秒超时下限；失败后先确认再重跑
+- **积分**：`1`/条；个股若无看点总结则不在返回列表中，也不扣分——所以**返回行数少于提交数是正常的**，不是丢了数据。超时 / 5xx **不自动重试**（一次最多可扣 6000 积分，重放可能重复扣分）：CLI 已给它 120 秒超时下限；失败后先确认再重跑
 - 🔴 **整批返 0 行别直接读成「这批都没有看点」**：它与「确实都没有看点」长得一样。挑其中一两只单查确认后再下结论
 - 返回字段：`securityCode` / `securityName` / `summary`（精炼投研总结）/ `date`（更新日期 `yyyy-MM-dd`）
 
@@ -79,7 +79,7 @@ gangtise ai stock-summary --security 600519.SH --security 00700.HK --format json
 gangtise ai research-outline --security-code <code>
 ```
 
-- **积分**：50/次（按次计费；超时不自动重发）
+- **积分**：10/次（按次计费；超时不自动重发）
 
 - 仅 A 股
 - 返回 `{content: "markdown"}`
@@ -91,7 +91,7 @@ gangtise ai earnings-review --security-code <code> --period <period> [--wait]
 gangtise ai earnings-review-check --data-id <id>
 ```
 
-- **积分**：提交 50/次（按次计费；超时不自动重发，重提会再扣一次）
+- **积分**：提交 20/次（按次计费；超时不自动重发，重提会再扣一次）
 
 - `--period`：`年份+报告期`，如 `2025q3`（q1/interim/q3/annual），仅 A 股，覆盖最近 6 期
 - `--wait`（**推荐**）：阻塞等待到出结果（最长约 5 分钟：14 次指数退避轮询 5s→30s，累计 ≈316s）——**用它时把工具/命令超时设到 ≥360s**，否则外层先超时
@@ -107,7 +107,7 @@ gangtise ai viewpoint-debate --viewpoint <text> [--wait]
 gangtise ai viewpoint-debate-check --data-id <id>
 ```
 
-- **积分**：提交 50/次（按次计费；超时不自动重发，重提会再扣一次）
+- **积分**：提交 20/次（按次计费；超时不自动重发，重提会再扣一次）
 
 - `--viewpoint`：观点文本，**上限 1000 字**
 - 双向逻辑校验：看多→拆解风险，看空→挖反转
@@ -120,7 +120,7 @@ gangtise ai viewpoint-debate-check --data-id <id>
 gangtise ai theme-tracking --theme-id <id> --date <yyyy-MM-dd> [--type <name>]
 ```
 
-- **积分**：50/次（按次计费；超时不自动重发）
+- **积分**：10/次（按次计费；超时不自动重发）
 
 - `--theme-id`（**必选**）：用 `gangtise reference concept-search --keyword <主题名>` 查，取 `conceptId`（题材与主题共用 ID 体系）
 - `--date`（**必选**）：支持近 30 天
@@ -144,8 +144,8 @@ gangtise ai hot-topic [--start-date <date>] [--end-date <date>] [--category <nam
 - `--category`：`morningBriefing` 早报 | `noonBriefing` 午报 | `afternoonFlash` 盘中快报 | `eveningBriefing` 晚报（可重复，默认全部；其他取值 CLI 在本地拒绝——接口对错值不报错，结果看着像正常查询）
 - `--with-related-securities` / `--with-close-reading`：默认开启；`--no-with-related-securities` / `--no-with-close-reading` 显式排除（响应里相应字段置空）
 - 自动翻页，单页最大 20
-- 🔴 **计费 50/篇，按返回条数计**（不是按调用次数）。📌 **一「篇」= 一整份报告**（一份早报 / 午报 / 盘中快报 / 晚报），**不是报告里的一条话题**——一份报告通常包含多条热点话题，`--category` 选的也是报告类型而不是话题。所以一页 20 条 = 20 份报告 = 1000 积分：**先用 `--start-date`/`--end-date` + `--category` 把范围收窄，再考虑要不要全量**（省略 `--size` 时 CLI 先取 1 篇拿到总数来估算，超过 1000 积分报错，确认要全量加 `--yes`；结果多于 1 篇时这 1 篇会多计一次，知道要几篇就直接传 `--size`）
-- **可查的历史范围跟账号权限走**：试用档是滚动的「当前 −1 个月」，正式/定制档更长。超出范围的日期**返回空结果、不报错**——拿到空先确认是不是撞了本账号的窗口，别当成「那天没有报告」
+- 🔴 **计费 10/篇，按返回条数计**（不是按调用次数）。📌 **一「篇」= 一整份报告**（一份早报 / 午报 / 盘中快报 / 晚报），**不是报告里的一条话题**——一份报告通常包含多条热点话题，`--category` 选的也是报告类型而不是话题。所以一页 20 条 = 20 份报告 = 200 积分：**先用 `--start-date`/`--end-date` + `--category` 把范围收窄，再考虑要不要全量**（省略 `--size` 时 CLI 先取 1 篇拿到总数来估算，超过 1000 积分报错，确认要全量加 `--yes`；结果多于 1 篇时这 1 篇会多计一次，知道要几篇就直接传 `--size`）
+- **可查的历史范围是前溯 3 个月**（各档相同）。超出范围的日期**返回空结果、不报错**——拿到空先确认是不是撞了本账号的窗口，别当成「那天没有报告」
 
 ## 管理层讨论-财报 `ai management-discuss-announcement`
 
@@ -153,7 +153,7 @@ gangtise ai hot-topic [--start-date <date>] [--end-date <date>] [--category <nam
 gangtise ai management-discuss-announcement --report-date <date> --security-code <code> --dimension <name>
 ```
 
-- **积分**：10/次（按次计费；超时不自动重发）
+- **积分**：5/次（按次计费；超时不自动重发）
 
 - `--report-date`（**严格**）：仅接受 `xxxx-06-30`（半年报）/ `xxxx-12-31`（年报）
 - `--dimension`（**必选**）：`businessOperation` 业务经营与行业 | `financialPerformance` 财务与经营成果 | `developmentAndRisk` 发展规划与风险 | `all` 返回报告中完整的管理层讨论内容（内容可能过长，谨慎使用）

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

@@ -27,6 +27,7 @@ gangtise alternative edb-data --indicator-id <id> [--indicator-id <id2>] --start
 - `--indicator-id`（**至少 1 个**，最多 10 个——上限由接口校验，CLI 不拦）：指标 ID，来自 `edb-search` 返回的 `indicatorId`，可重复传
 - `--start-date`（**必选**）：开始日期，格式 `yyyy-MM-dd`
 - `--end-date`（**必选**）：结束日期，格式 `yyyy-MM-dd`
+- **积分**：30/指标（单次最多 10 个指标，即最多 300）
 - 返回格式：列表，每行为 `{date, <indicatorId1>: value, <indicatorId2>: value, ...}`
 - 日期列为字符串（如 `"2010-01-31"`），数值列为字符串数字（如 `"447184.41"`）
 

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

@@ -2,7 +2,7 @@
 
 **全部计费，0.4 积分起**：多数按次（与返回行数无关）；`rating-overview` 按条、`rating-change` 按有数据的债券只数、`issuer-rating-change` 按发行人计，见各命令。
 
-`--security` 收**标准债券代码**——`019742.SH` / `123456.SZ` / `220205.IB`（银行间）。**不接受简称或拼音**，传了按 `120001` 整批拒绝、不会退化成模糊匹配；只有简称时先 `reference securities-search --keyword <简称>` 换代码。可重复，也接受逗号分隔；有单次只数上限的命令按**去重后**的只数计。
+`--security` 收**标准债券代码**——`019742.SH` / `123456.SZ` / `220205.IB`（银行间）。**不接受简称或拼音**，传了按 `120001` 整批拒绝、不会退化成模糊匹配；只有简称时先 `reference securities-search --keyword <简称> --category bond` 换代码。可重复，也接受逗号分隔；有单次只数上限的命令按**去重后**的只数计。
 
 ⚠️ **超时 / 5xx 不自动重放**（避免重复扣费），偶发失败自行重跑。
 
@@ -131,4 +131,4 @@ gangtise bond announcement (--security <code>... | --start-date <d> --end-date <
 ## 相关常量
 
 债券字段里的枚举 ID 可通过 `reference constant-list --category <code>` 查全量：
-`bondType` 债券类型 | `interestRateType` 利率类型 | `interestFrequency` 付息频率 | `absUnderlyingAssetType` ABS 基础资产类型 | `ratingType` 评级类型 | `exchange` 交易市场。
+`bondType` 债券类型 | `interestRateType` 利率类型 | `interestFrequency` 付息频率 | `absUnderlyingAssetType` ABS 基础资产类型 | `ratingType` 评级类型 | `exchange` 交易市场 | `interestBondSubtype` 利率债子类型。⚠️ 同名字段 `bondType` 两套码：`basic-info` 用 `bondType`，`issuance-plan` 用 `interestBondSubtype`。

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

@@ -5,7 +5,7 @@
 `--security` 收**基金交易代码**，后缀大写：场外 `005827.OF`；场内 `159967.SZ` / `510300.SH`。可重复，也接受逗号分隔；重复代码服务端自动去重。
 
 - 🔴 **代码不存在、不带后缀（`005827`）、后缀小写（`.of`）、传成股票代码，都返回空结果、不报错**——拿到空先核对代码与后缀
-- **只知道基金名称时**：场内基金（ETF、LOF 的场内份额）用 `reference securities-search --keyword <场内简称或 6 位代码> --category fund` 换代码（基金全称常搜不到，如「华泰柏瑞沪深300ETF」要搜「沪深300ETF」或 `510300`）；场外 `.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` 区分后取一个
 - LOF / ETF 的场内代码（`161005.SZ`）与场外代码（`161005.OF`）都能查，返回的 `fundCode` 与 `fundName` 跟随传入的代码（场内简称 / 场外简称不同）；同一只基金别两种代码混着传，会重复
 - A / C 等份额各有代码，要合并到同一只基金用 `basic-info` 的 `mainFundCode`
 - 多只基金的结果**按 `fundCode` 字段对应**，别按请求顺序对位

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

@@ -2,7 +2,7 @@
 
 通用：所有命令都需 `--security-code`（如 `600519.SH`，注意是 `--security-code` 不是 `--security`）。`--field` 可重复，可用字段见 `references/fields.md`；A / 港 / 美股三大报表命令都在省略 `--field` 时返回完整报表，指定后只保留基础字段与所选科目。
 
-**`--field` 字段名必须核对**：三大报表遇到不存在的字段名会补 `null`（安全），但 `main-business` / `valuation-analysis` 是**只丢值、字段名照请求回显**，`fieldList` 比行长，按位置拍平会把值贴到错误的字段上。CLI 长度不匹配就直接失败（退出码 1），不输出错位数据。不确定字段名就别传 `--field`。
+**`--field` 字段名必须核对**：三大报表遇到不存在的字段名会补 `null`，`main-business` / `valuation-analysis` 整条报 `100005` 并点名写错的名字。不确定字段名就别传 `--field`。
 
 ⚠️ **别把这个行为套到 `quote` 系上**——那边是**字段名和值一起消失**、列数与值数始终对得上，CLI 的处理也不同（标 `partial` + `missingFields`、退出码 3）。两族的完整对照见 `references/fields.md` 顶部。
 
@@ -95,7 +95,7 @@ gangtise fundamental valuation-analysis --security-code <code> --indicator <name
 - 🔴 **序列按自然日逐日一行（含周末）**，行数超过 `--limit` 时接口**保留最近的行、丢掉区间开头**。CLI 撞满即标 `partial`、退出码 3 并在 stderr 说明（首行恰好就是 `--start-date` 时说明没丢，不标）。取长区间把 `--limit` 设到不小于区间天数：取 N 年就设 `--limit` ≥ 366 × N（且不早于账号权限窗口的起点）
 - 🔴 **`--start-date` 早于账号回溯下界时，接口从下界起返回、不报错**（整段都在界外才报 `110003`）。首行晚于 `--start-date` 时 CLI 在 stderr 提示——可能是该证券上市较晚，也可能是撞了权限窗口，看首行日期判断
 - `--skip-null`：丢弃 `value`/`percentileRank` 为 null 的行（最新交易日可能未入库）
-- **返回字段只有 7 个**：`tradeDate` `value` `percentileRank` `average` `median` `upper1Std` `lower1Std`，**没有 `securityCode`**。🔴 `--field` 里**至少要有一个数值列**（`tradeDate` 以外的 6 个）：只传 `tradeDate`、只传不存在的名字（含 `securityCode`）时接口返回 0 行、**不报错**，读起来像「这只票没有估值数据」（CLI 会在 stderr 提示原因）；数值列与不存在的名字混传时，回显的字段比每行的值多，CLI 直接报错退出 1。`tradeDate` 总在第一列返回，不用写进 `--field`（写了 CLI 会在发请求前去掉；同一字段写两次也只发一次）。**建议不传 `--field`**，证券代码本来就是你自己传进去的
+- **返回字段只有 7 个**：`tradeDate` `value` `percentileRank` `average` `median` `upper1Std` `lower1Std`，**没有 `securityCode`**。🔴 `--field` 里**至少要有一个数值列**（`tradeDate` 以外的 6 个）：只传 `tradeDate` 时接口返回 0 行、**不报错**，读起来像「这只票没有估值数据」（CLI 会在 stderr 提示原因）；不存在的名字（含 `securityCode`）整条报 `100005` 并点名。`tradeDate` 总在第一列返回，不用写进 `--field`。**建议不传 `--field`**，证券代码本来就是你自己传进去的
 
 ## A股盈利预测 `fundamental earning-forecast`
 
@@ -105,6 +105,7 @@ gangtise fundamental earning-forecast --security-code <code> [--start-date <date
 
 - **市场与路由**：本命令仅支持 A 股（港股 / 美股会报 `120001`「非有效A股」）。A股盈利预测 / 一致预期始终走本命令，不走 EDE；EDE 搜索目前没有一致预期语义，搜到的基本 / 稀释 EPS 是已实现值，不能冒充预测 EPS。港 / 美股盈利预测当前 CLI 不支持
 - `--start-date` / `--end-date`：默认截至北京时间的今天、向前一年
+- **可查范围：前溯 1 年**（各档相同，个别账号更长，以实际返回为准）
 - `--consensus` 可重复：`netIncome` 归母净利润 | `netIncomeYoy` 同比增速 | `eps` 每股收益 | `pe` 市盈率 | `bps` 每股净资产 | `pb` 市净率 | `peg` PEG | `roe` 净资产收益率 | `ps` 市销率
 - **`roe` 的单位是百分比（%）**：`35.6` 即 35.6%，**不要再做 ÷100 之类的单位换算**——换算后的数字看着仍像个 ROE，不会报错
 - 返回结构：`{securityCode, securityName, updateList: [{date, fieldList: [{forecastYear, ...consensus}]}]}` — 每个日期固定返回 3 年预测（如 `2026E` / `2027E` / `2028E`）

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

@@ -71,7 +71,7 @@ gangtise indicator cross-section --indicator <code> [--indicator <code2>] \
   - 根级 `--scale` **只作用于支持该参数的指标**：`qte_close` + `qte_mkt_cptl` 混查加 `--scale 8`，收盘价保持原值、总市值按亿缩放，价格类与金额类可以放心混查。要精确控制到单个指标用 `--indicator-param "code:scale=8"`
 - **支持多指标 × 多证券**（单日横截面）
 - **输出（宽表）**：每行一只证券，列为 `security / name / <各指标名>…`。**没有 `date` 列**——查询日期挂在每个指标自己的参数上，各列可以是不同日期
-- **`--key-by name|code`**（默认 `name`）：指标列头用显示名还是 `indicatorCode`。**批量按 code 回填必用 `--key-by code`**——指标名会碰撞（多个指标同显示名，如 `cf_finc_exp`/`_qtr` 都叫「财务费用」），唯有 code 唯一（行轴 `security` 本就是 code，`code` 模式整表可按 code 寻址，免去 raw API 手工回填）。顺序是稳定的，但**两个轴的排法不一样**：`indicatorList` **= 请求顺序**（请求 `qte_vol,qte_close` 就回 `qte_vol,qte_close`）；`securityCodeList` **是按代码升序重排的，不是请求顺序**（请求 `000858,600519,000001` → 回 `000001,000858,600519`）。所以**行序绝不能按请求下标对位**，一律按 `security` 字段取值
+- **`--key-by name|code`**（默认 `name`）：指标列头用显示名还是 `indicatorCode`。**批量按 code 回填必用 `--key-by code`**——指标名会碰撞（多个指标同显示名，如 `cf_finc_exp`/`_qtr` 都叫「财务费用」），唯有 code 唯一（行轴 `security` 本就是 code，`code` 模式整表可按 code 寻址，免去 raw API 手工回填）。`indicatorList` 的返回顺序 = 请求顺序；`securityCodeList` 的返回顺序**不作保证**（可能与请求顺序不同）。所以**行序不能按请求下标对位**，一律按 `security` 字段取值
 
 ```bash
 # 多证券 × 同一报告期的已实现财务指标（报告期类指标必须显式给 reportDate，只给 --date 会报 100003）
@@ -144,7 +144,7 @@ gangtise indicator screener --indicator <F1:code> [--indicator <F2:code2>] \
 - `--indicator-param`：格式是 **`F1:key=value`（按变量，不是按 code）**。引用了没绑定的变量会直接报错，不会静默丢弃
 - `--expression` 里引用未绑定的变量，CLI **本地就拦**（不发请求、不计费）；服务端也会报 `100003`
 - **输出（宽表）**：同 `cross-section`，每行一只**命中**的证券，列为 `security / name / <各指标名>…`；无命中返回空表
-- **积分**：与 `cross-section` 同价（按单元格计），但计费基数是**筛选前**的范围 × 指标数，别拿全市场板块随手试
+- **积分**：与 `cross-section` 同价（按单元格计）；计费基数按**筛选前**的范围 × 指标数保守估算（实际以平台账单为准），别拿全市场板块随手试
 
 ### 同一指标绑多个变量
 
@@ -275,22 +275,22 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 
 | 错误码 | 实际含义 | 怎么办 |
 | :--- | :--- | :--- |
-| `100001` | **缺少必填参数**：如 `universe` 没传，或指标 `parameterList` 里 `required` 的参数没给（msg 会点名是哪个指标的哪个参数）。⚠️ 漏传 `fiscalYear` **不报这个码**，见下「必填参数」 | 补齐 `--indicator` / `--security`，或用 `--indicator-param` 补上点名的参数 |
+| `100001` | **缺少必填参数**：如 `universe` 没传，或指标 `parameterList` 里 `required` 的参数没给（msg 会点名是哪个指标的哪个参数） | 补齐 `--indicator` / `--security`，或用 `--indicator-param` 补上点名的参数 |
 | `100003`@400 | 入参/表达式错误：`time-series` 传了「多指标 × 多证券」、`expression` 引用未声明变量、`indicatorParamList` 的 code 不在 `indicatorCodeList` 里 | 按 msg 改；多 × 多改用 `cross-section`。CLI 已在本地拦截「表达式引用未绑定变量」，不会白发一次请求 |
 | `140002`@500 | **终态参数错**：枚举越界（如「参数 adjustType 的值 99 不在有效范围内 [1,2,3,4]」）、表达式语法错误 | **不重试**（CLI 已把 140002 列为终态码）。读 `search --format json` 的 `parameterList` 改参数名/取值 |
-| `999999` | 系统故障。「无数据」不用此码，所以它基本只剩真故障。⚠️ 无数据是占位单元格（统一 `null`）；代码或参数名写错报 `100003`、缺必填参数报 `100001`，都会点名（漏传 `fiscalYear` 例外，不报错） | CLI 对 indicator 端点**不重试此码**；确认参数无误仍报错，稍后再试或联系平台支持 |
+| `999999` | 系统故障。「无数据」不用此码，所以它基本只剩真故障。⚠️ 无数据是占位单元格（统一 `null`）；代码或参数名写错报 `100003`、缺必填参数报 `100001`，都会点名 | CLI 对 indicator 端点**不重试此码**；确认参数无误仍报错，稍后再试或联系平台支持 |
 | `110003` | **超出账号数据权限的时间范围**。窗口按**账号**配、不按接口配——`cross-section` / `time-series` / `screener` 同界，区间**跨过**下界也整批报这个码；`quote day-kline` 在同一条界上，但跨界时从下界起返回、不报错 | 把起点移进范围；整段区间都早于下界时缩短窗口无用，**换接口绕不过去**，要更长历史联系客户经理开通 |
 | `130001` | 数据未找到，或**该指标无权限**（内层信封失败会带具体 msg，如"指标无权限"；此码被服务端复用） | 检查查询条件与指标权限；换证券/日期仍失败多为无权限，联系管理员开通 |
 
 ### 指标专属参数
 
-缺必填参数报 `100001` 并点名是哪个指标的哪个参数。🔴 **`fiscalYear` 例外：漏传不报错**——预测类（如 `frcst_pe`）与分红类（`div_cash_yr` / `div_cash_paid_ratio`）都会按一个服务端自定的默认年度取数（不随 `--date` 变）：该年度有数就返回它，看着完全正常，但未必是你要的那一年；没有就是 `null`，与「没有数据」无法区分。所以 `parameterList` 里标 `required` 的 `fiscalYear` 一律显式传。**先完成语义 + `scopeList` + `parameterList` 三项校验；其中凡 `required:true` 的参数都用 `--indicator-param "指标code:参数=值"` 补上。** 常见的几个：
+缺必填参数报 `100001` 并点名是哪个指标的哪个参数（含 `fiscalYear`）。**先完成语义 + `scopeList` + `parameterList` 三项校验；其中凡 `required:true` 的参数都用 `--indicator-param "指标code:参数=值"` 补上。** 常见的几个：
 
 | 参数 | 适用指标 | 示例 |
 | :--- | :--- | :--- |
 | `periodNum` | N 期统计（N 期均值/最值，如 `finc_roe_avg_avg` 平均ROE N期均值） | `--indicator-param "finc_roe_avg_avg:periodNum=4"`；`finc_roe_avg_avg` 属报告期类，还要补 `--indicator-param "finc_roe_avg_avg:reportDate=2025-12-31"`（只给 `--date` 报 `100003`） |
 | `sDate` | 区间类的**起始日**（如 `qte_vol_intvl` 区间成交量、`qte_avg_vol` 区间日均成交量），格式 `yyyy-MM-dd` | `--indicator-param "qte_vol_intvl:sDate=2024-01-02"`。⚠️ **`sDate` 不能替代 `tradeDate`**——它是区间起点，`tradeDate`（=区间终点）仍是 required，`--date` 会照常下发。区间起始日的参数名就是 `sDate`，写成 `startDate` 会报 `100003 不支持参数 startDate`。⚠️ **不传 `sDate` 不报错**——它是可选参数，缺了就按默认区间算，所以要的是特定区间就必须显式传。另：`qte_amp_mo`（月振幅）等周期变体只吃 `tradeDate`，没有起始日参数 |
-| `fiscalYear` | 年度/报告期类（如 `div_cash_yr` 年度现金分红）、预测类（如 `frcst_pe`，与 `tradeDate` 同时必填）。**漏传不报错**，见上 | `--indicator-param "div_cash_yr:fiscalYear=2025"` |
+| `fiscalYear` | 年度/报告期类（如 `div_cash_yr` 年度现金分红）、预测类（如 `frcst_pe`，与 `tradeDate` 同时必填） | `--indicator-param "div_cash_yr:fiscalYear=2025"` |
 | `industryType` + `industryLevel` | `scr_indu` 所属行业（两个都 required，缺任一报 `100001`） | `--indicator-param "scr_indu:industryType=1" --indicator-param "scr_indu:industryLevel=0"` |
 
 > `paramValue` 一律按**字符串**约定传（`periodNum=4` 内部即 `"4"`，CLI 已处理）。
@@ -384,7 +384,7 @@ gangtise indicator cross-section --indicator scr_indu_citic --indicator scr_indu
 - **混合日期语义要拆查询**：同时要“某报告期营收 / EPS”和“估值 PE / PB”时，按各自有效日期分别调用 `cross-section` 再按 `security` 合并（财务=报告期末、PE/PB=最新交易日）；不要把不同日期语义的指标塞进同一个 `--date`
 - **探索性取数**：缺值会保留行列并给占位单元格（含 1×1 的最简形态），占位值统一为 `null`；code 写错会直接报 `100003`，不会伪装成缺值。看趋势用 `time-series` + 覆盖报告期的区间，但不能把缺值当成通过语义 / scope 校验。
 - **名称反查 code 要核对，别取首条**：存在同显示名的兄弟指标——单季 `cf_finc_exp_qtr` 与累计 `cf_finc_exp` 都叫「财务费用」，`bs_fmt`/`cf_fmt`/`is_fmt` 都叫「报表格式」。`search` 按名称模糊匹配，目标 code 高概率在 top1 但不绝对，要看 `indicatorCode` 确认。
-- **批量查询出错先读 msg**：缺必填参数报 `100001`、代码或参数名写错报 `100003`，msg 都会点名是哪个指标或证券，照 msg 改即可。漏传 `fiscalYear` 不报错，见「必填参数」。
+- **批量查询出错先读 msg**：缺必填参数报 `100001`、代码或参数名写错报 `100003`，msg 都会点名是哪个指标或证券，照 msg 改即可。
 - **市值量纲**：`qte_mkt_cptl`（总市值）与 `shr_tot`（总股本）**A/港/美股均有数**；**默认返原始「元」**（大市值公司是 `1e12` 量级，即万亿级），别误当天文数字。用 `scale` 数字码缩放（`0`元 / `3`千 / `4`万 / `6`百万 / `8`亿 / `9`十亿——`scale=8` 即以亿元为单位）、`currency` 换币种（**大写** `DFT`本币 / `CNY` / `HKD` / `USD` …）。**跨证券比市值前先统一 `scale`+`currency`**。
 - **币种与汇率**：`DFT`（原始币种）按市场识别——A股=CNY、港股行情=HKD、美股=USD；汇率换算自洽（互逆且三角一致）。⚠️ 但**同一只港股，行情类的原始币种是 HKD、财务类可能是 CNY**（如泡泡玛特财报以人民币计），跨市场比财务数据时显式传 `--currency CNY` 别依赖 `DFT`。另：财务类指标的汇率按**报告期**折算、行情类按查询日折算，两者隐含汇率会有细微差异，属正常口径差别。
 - **EDE 财务指标的 `reportType`**：`enumList` 的 label 与实际取数**一致**，按 label 传即可（取值以 `enumList` 为准）：
@@ -419,6 +419,6 @@ gangtise indicator cross-section --indicator scr_indu_citic --indicator scr_indu
 
 - **发现流程**：`indicator search --format json` → 核对 `indicatorName` + `description`、`scopeList`（含 `usageRestriction`）、`parameterList`（**参数名以此为准**）→ 三项都通过才用 `cross-section` / `time-series` / `screener`
 - **积分**：`search` 免费；`cross-section` / `time-series` / `screener` 按请求单元格数量计费，标价为每 100 单元格 A 股 0.05 / 港股 0.1 / 美股 0.2 积分，每次查询不足 100 单元格按 100 计
-- **空结果排查顺序**：代码、参数名写错与缺必填参数会直接报错并点名（`100003` / `100001`），不会以空结果出现——已知例外是漏传 `fiscalYear`（按默认年度取数，该年度无数据时返回 `null`）。拿到整批 `null` 或 `screener` 空集时按序排查：① 日期语义对不对（`tradeDate` vs `reportDate`——报告期类指标日期用错会整批返 `null`，看着像「没数据」；`parameterList` 要 `fiscalYear` 的传了没有）② 该指标覆不覆盖这批证券（`scopeList`，单查一行确认）③ 真的没有数据
+- **空结果排查顺序**：代码、参数名写错与缺必填参数会直接报错并点名（`100003` / `100001`），不会以空结果出现。拿到整批 `null` 或 `screener` 空集时按序排查：① 日期语义对不对（`tradeDate` vs `reportDate`——报告期类指标日期用错会整批返 `null`，看着像「没数据」）② 该指标覆不覆盖这批证券（`scopeList`，单查一行确认）③ 真的没有数据
 - **数据权限**：正式账号行情 / 财务 / 指标类可回溯的年限按服务等级而定，试用账号更短。这个时间窗口按**账号**配、不按接口配——三个 EDE 接口同界，区间跨过下界也整批返 `110003`（`quote day-kline` 在同一条界上，但跨界时从下界起返回、不报错），**换接口绕不过去**；整段区间都早于下界时缩短窗口无用，要更长历史联系客户经理开通
 - 所有格式（table/json/jsonl/csv/markdown）均可用；导出宽表给 Excel 直接用 `--format csv --output xxx.csv`

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

@@ -61,7 +61,7 @@ gangtise insight summary list [--search-type <n>] [--rank-type <n>] [--source <n
 gangtise insight summary download --summary-id <id> [--file-type <n>] [--output <path>]
 ```
 
-- **积分**：列表 0.1/条；下载 50/篇
+- **积分**：列表 0.1/条；下载 30/篇
 
 - `--search-type`：`1` 标题搜索（默认，速度快）| `2` 全文搜索
 - `--source`：`1` 实时 | `2` 开放来源
@@ -96,7 +96,7 @@ gangtise insight pamirs-summary list [--search-type <n>] [--rank-type <n>] [--re
 gangtise insight pamirs-summary download --summary-id <id> [--file-type <n>] [--output <path>]
 ```
 
-帕米尔（Pamirs）是平台内一个特殊牵头机构的**专家纪要库**，走独立端点，不是 `summary list` 的一个筛选项。⚠️ **需单独购买专家纪要数据库**：未开通时 `list` 直接报 `999004`（不是返回空列表），**整库拿不到**。**不限制历史数据范围**（不受 3 个月窗口约束）。
+帕米尔（Pamirs）是平台内一个特殊牵头机构的**专家纪要库**，走独立端点，不是 `summary list` 的一个筛选项。⚠️ **需单独购买专家纪要数据库**：未开通时 `list` 直接报 `999004`（不是返回空列表），**整库拿不到**。**不限制历史数据范围**（不受纪要列表的窗口约束）。
 
 > 未开通该库时任何查询都直接报 `999004`，不必怀疑参数写错。
 
@@ -136,7 +136,7 @@ gangtise insight strategy list   [--institution <id>] [--location <id>]
 gangtise insight forum list      [--research-area <id>] [--location <id>]
 ```
 
-- **积分**：列表 **20/条**——务必带 `--size`
+- **积分**：列表 **10/条**——务必带 `--size`
 
 - 共用：`--keyword` `--start-time` `--end-time` `--from` `--size` `--location`
 - `--location`：城市/省份 ID（`reference constant-list --category domesticCity` 查，如 `156440000` 广东省）。传省份 ID 会命中该省
@@ -166,7 +166,7 @@ gangtise insight performance-calendar download --performance-report-id <id> [--o
 - 返回字段：`performanceReportId`（下载用）/ `securityCodeList[]`（A+H 同时上市会有多个代码）/ `securityName` / `category` / `publishDate` / `title` / `hasAttachment`
 - `publishDate` 返回的是 `yyyy-MM-dd 00:00:00`，取日期请截前 10 位
 - download：**只有 `hasAttachment: true` 的记录能下**（先 list 确认）；省略 `--output` 用 title-cache 里的真实标题命名，**未命中不自动回查**，退回服务端文件名或 `<type>-<id>`。要回查加 `--resolve-title`——拉 200 条、按 0.1/条 约 20 积分，取回的标题会写回缓存供同批复用
-- **积分**：list 0.1/条；download A 股 10/篇、港美股 20/篇
+- **积分**：list 0.1/条；download A 股 1/篇、港美股 2/篇
 
 ## 研报 `insight research list/download`
 
@@ -191,7 +191,7 @@ gangtise insight foreign-report list [--search-type <n>] [--rank-type <n>] [--se
 gangtise insight foreign-report download --report-id <id> [--file-type <n>] [--output <path>]
 ```
 
-- **积分**：列表 0.1/条；下载 50/篇
+- **积分**：列表 0.1/条；下载 30/篇
 
 - `--region`：`cn` 中国 | `cnHk` 香港 | `us` 美国 | `jp` 日本 | `sea` 东南亚 | `gl` 全球 | `uk` 英国 | `kr` 韩国 | `in` 印度（完整列表见 `references/lookup-ids.md`）。⚠️ 写错区域码不会报错，会返回不按区域筛选的全量结果——传之前核对取值
 - `--category` / `--llm-tag` / `--rating` / `--rating-change`：同研报
@@ -204,7 +204,7 @@ gangtise insight announcement list [--search-type <n>] [--rank-type <n>] [--secu
 gangtise insight announcement download --announcement-id <id> [--file-type <n>] [--output <path>]
 ```
 
-- **积分**：列表 0.1/条；下载 10/篇
+- **积分**：列表 0.1/条；下载 1/篇
 
 - `--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
@@ -217,7 +217,7 @@ gangtise insight announcement-hk list [--search-type <n>] [--rank-type <n>] [--s
 gangtise insight announcement-hk download --announcement-id <id> [--file-type <n>] [--output <path>]
 ```
 
-- **积分**：列表 0.1/条；下载 20/篇
+- **积分**：列表 0.1/条；下载 2/篇
 
 - `--security`：港股代码，如 `01913.HK`（两位数字前缀需补零）
 - `--category`：港股公告类型 ID（见 `references/lookup-ids.md`）
@@ -233,7 +233,7 @@ gangtise insight announcement-us download --announcement-id <id> [--file-type <n
 - `--security`：美股代码，如 `TSLA.O`（可重复）
 - `--category`：美股公告分类 ID，用 `reference constant-list --category usShareAnnouncementCategory` 查（美股独立的 `103980xxx` 段，一级分类：财务报告 / 证券发行 / 重大事项 / 交易提示 / 股本股东 / 股东大会 / 一般公告）
 - `--file-type`（download）：`1` 原始PDF（默认）| `2` Markdown
-- **积分**：list 0.1/条；download 20/篇
+- **积分**：list 0.1/条；download 2/篇
 - `--security TSLA.O` 的 `sourceName` 为「美国证券交易委员会」
 
 ## 外资机构观点 `insight foreign-opinion list/detail`
@@ -261,7 +261,7 @@ gangtise insight independent-opinion list [--rank-type <n>] [--security <code>]
 gangtise insight independent-opinion download --independent-opinion-id <id> --file-type <n> [--output <path>]
 ```
 
-- **积分**：列表 **5/条**——务必带 `--size`；下载 30/篇
+- **积分**：列表 **1/条**——务必带 `--size`；下载 30/篇
 
 - `--security`：境外证券代码，如 `GSK.N`
 - ⚠️ `--industry`：**只认申万码**（`104xx0000`），中信码报 `100005 枚举值非法`（同 `foreign-opinion`，见上）。返回记录的 `industryList[]` 两套码都带，回查挑申万那条

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

@@ -2,7 +2,7 @@
 
 通用：`--field` 可重复（`--field open --field close`），可用字段见 `references/fields.md`。
 
-**`--field` 字段名必须核对**：上游对不存在的字段名有两套处理——day-kline / minute-kline / fund-flow / realtime 把字段名和值**一起丢掉**（不报错，结果里就是少一列）；`fundamental main-business` / `valuation-analysis` 则**只丢值、字段名照请求回显**，按位置拍平就把值贴到了错误的字段上。CLI 对后一种长度不匹配直接失败（退出码 1），不输出错位数据；对前一种比对请求与返回的列名，**缺列就标 `partial` + `missingFields`、退出码 3 并在 stderr 点名是哪几列**（字段名写错或已下线，按 `references/fields.md` 核对）。**不确定字段名就别传 `--field`**（返回全量最稳）。另外 `--field` 只返回点名的列，所以**多只证券或全市场关键字**时 CLI 会补上区分行所需的列并在 stderr 说明：日 K 补 `securityCode` / `tradeDate`、分钟 K 补 `securityCode` / `tradeTime`、实时行情补 `securityCode`（需要时点自己加 `tradeDate` / `tradeTime`）；单只证券按点名的列原样返回。`fund-flow` 由服务端自动附带 `securityCode` / `tradeDate`。
+**`--field` 字段名必须核对**：day-kline / minute-kline / fund-flow / realtime 对不存在的字段名把字段名和值**一起丢掉**（不报错，结果里就是少一列）。CLI 比对请求与返回的列名，**缺列就标 `partial` + `missingFields`、退出码 3 并在 stderr 点名是哪几列**（字段名写错或已下线，按 `references/fields.md` 核对）。**不确定字段名就别传 `--field`**（返回全量最稳）。另外 `--field` 只返回点名的列，所以**多只证券或全市场关键字**时 CLI 会补上区分行所需的列并在 stderr 说明：日 K 补 `securityCode` / `tradeDate`、分钟 K 补 `securityCode` / `tradeTime`、实时行情补 `securityCode`（需要时点自己加 `tradeDate` / `tradeTime`）；单只证券按点名的列原样返回。`fund-flow` 由服务端自动附带 `securityCode` / `tradeDate`。
 
 **关键规则**：查"最近"K线必须显式 `--start-date`/`--end-date` 拉范围，再从 `tradeDate` 取尾部最近 N 条；不要只用 `--limit N`（会截取查询窗口开头）。
 
@@ -133,6 +133,7 @@ gangtise quote minute-kline --security <code> [--start-time <datetime>] [--end-t
 - 支持**沪深** A 股个股（`.SH` / `.SZ`，不含北交所）、沪深 ETF（`512800.SH`）、交易所指数（`.SH` / `.SZ`）、概念指数（`.GT`）、行业指数（`.CI` / `.SWI`）、全球指数（`SPX.SPI` / `N225.NKI` / `HSI.HI`…，清单见日 K 一节）；**必须传 `--security`**（缺了 CLI 在本地报错）
 - `--security` 可重复传多只：接口一次只收一只，CLI 逐只并发请求后按传入顺序合并；任一只撞上 `--limit` 时结果标 `partial` + `truncatedSecurities`、退出码 3
 - `--start-time` / `--end-time`：`yyyy-MM-dd HH:mm:ss`（兼容 `yyyy-MM-dd` 自动补全）
+- **可查范围：最近 1 个月**，随日期滚动（各档相同）；整段早于窗口返回空结果、不报错
 - `--limit` 默认 6000，上限 10000
 - 常用字段：`securityCode` `tradeTime` `open` `high` `low` `close` `change` `pctChange` `volume` `amount`
 - **全球指数**：`volume` / `amount` 为 `null`；`tradeTime` 与 `--start-time` / `--end-time` 都按**交易所当地时间**（如日经225 一天的分钟线是 `09:01`–`15:30`，德国 DAX 是 `09:01`–`17:30`）

package/gangtise-openapi/references/commands/reference-and-lookup.md

@@ -8,7 +8,9 @@ gangtise reference securities-search --keyword <text> [--category <type>] [--top
 
 - 用途：把公司名/简称/代码/拼音/英文名/曾用名 → `gtsCode`，是 `ai security-clue --gts-code` 等接口的前置查询
 - `--keyword`（**必选**）：支持多维度匹配（中文名/简称/证券代码/拼音首字母/英文名/曾用名）
-- `--category`（可重复）：`stock` | `dr` 存托凭证 | `index` | `fund`（不传则查所有）
+- `--category`（可重复）：`stock` | `dr` 存托凭证 | `index` | `fund` | `bond`（不传则查所有）
+  - `bond` 覆盖交易所可转债、国债、地方债、金融债与银行间债券（后缀 `.SH` / `.SZ` / `.IB`），按代码或简称查（如 `113636.SH`、`甬金转债`）。债券代码用于 `bond` 命令组；`quote` 行情、公告等其余命令不收债券代码（传了报 `120001`）
+  - 🔴 **可转债在任何 `--category` 下都可能出现**：按公司简称查 `stock` 时，同名可转债常排第一（「甬金」→ `113636.SH 甬金转债` 在 `603995.SH 甬金股份` 之前）。**取第一条 `category` 等于所查类别的行**，别直接取 `list[0]`；用公司全称查时一般只返回正股
 - `--top`：默认 10，**上限 10**
 - 返回字段：`gtsCode` / `gtsName` / `category` / `matchScore` / `matchType`
   - `matchType`：`code` 代码 | `abbr` 简称 | `pinyin` 拼音 | `prev` 曾用名 | `engName` 英文名
@@ -18,6 +20,7 @@ gangtise reference securities-search --keyword <text> [--category <type>] [--top
 gangtise reference securities-search --keyword 茅台 --category stock --top 3
 gangtise reference securities-search --keyword 600519
 gangtise reference securities-search --keyword gzmt
+gangtise reference securities-search --keyword 甬金转债 --category bond
 ```
 
 ## 首席 ID 搜索 `reference chiefs-search`
@@ -91,7 +94,7 @@ gangtise reference constant-category [--format json]
 
 - 用途：全量导出常量分类及每个分类适用于哪些接口的哪些参数（无需传参，免积分）
 - 返回 `{total, list}`，`list[]` 字段：`category`（分类代码）/ `categoryName` / `structureType`（`flat` 平铺 | `tree` 树形）/ `maxLevel` / `usageScopes[]`（`apiName` + `paramName`）
-- 分类清单以 `reference constant-category` 的实际返回为准（服务端会随新接口上线增补）。截至 2026-09 的分类：
+- 分类清单以 `reference constant-category` 的实际返回为准（服务端会随新接口上线增补）。截至 2026-10 的分类：
 
 | category | 名称 | 结构 | 用于参数 |
 |----------|------|------|---------|
@@ -112,6 +115,7 @@ gangtise reference constant-category [--format json]
 | `absUnderlyingAssetType` | ABS 基础资产类型 | flat | `bond basic-info` 的 `absUnderlyingAssetType` |
 | `ratingType` | 评级类型 | flat | `bond rating-*` 的 `ratingType` |
 | `exchange` | 交易市场 | flat | `bond` 各命令的 `exchange` |
+| `interestBondSubtype` | 利率债子类型 | flat | `bond issuance-plan` 的 `bondType`（`basic-info` 的 `bondType` 用 `bondType` 这一套） |
 
 > **行业 / 研究方向过滤——选哪套 category（⭐ 以此处为准）：**
 >

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

@@ -62,7 +62,8 @@ gangtise vault my-conference-list [--keyword <text>] [--research-area <id>] [--s
 gangtise vault my-conference-download --conference-id <id> --content-type <type> [--output <path>] [--resolve-title]
 ```
 
-- **积分**：列表 0.1/条；下载 50/篇（超时不自动重发）
+- **积分**：列表 0.1/条；下载 30/篇（超时不自动重发）
+- **可查范围：前溯 1 个月**（各档相同）
 
 - `--category`：`earningsCall` 业绩会 | `strategyMeeting` 策略会 | `fundRoadshow` 基金路演 | `shareholdersMeeting` 股东大会 | `maMeeting` 并购会议 | `specialMeeting` 特别会议 | `companyAnalysis` 公司分析 | `industryAnalysis` 行业分析 | `other`（可重复）
 - `--source`：录制来源 `1`=企微会议助理 | `2`=会议服务微信群（可重复；不传返回全部）

package/gangtise-openapi/references/errors.md

@@ -13,7 +13,7 @@
 | 错误码 | 含义 | CLI 行为 | Agent 是否介入 |
 |--------|------|---------|--------------|
 | `100003` | 参数值非法——**最宽的兜底码**：类型错、`limit` 越界都归这里。**msg 通常已指明字段**（如「请求体字段类型不匹配: size 期望类型 Integer」「limit 最小为 1，最大为 10000」），先读 msg 再猜 | — | 按 msg 指的字段改；msg 没指明才对照 `--help` 查枚举拼写，**不要重试同命令** |
-| `999999` | 系统错误。`indicator`（EDE）的「无数据」不用此码（无数据是保留行列的占位单元格 `null`，见 `commands/indicator.md`；代码或参数名写错报 `100003`、缺必填参数报 `100001`，都会点名；例外是漏传 `fiscalYear` 不报错，见 `commands/indicator.md`「必填参数」），所以这个码基本只剩真故障 | 普通端点自动重试 ×2；🔴 贵档与 `indicator` 端点不重试 | 确认参数无误仍报此码即服务端故障 |
+| `999999` | 系统错误。`indicator`（EDE）的「无数据」不用此码（无数据是保留行列的占位单元格 `null`，见 `commands/indicator.md`；代码或参数名写错报 `100003`、缺必填参数报 `100001`，都会点名），所以这个码基本只剩真故障 | 普通端点自动重试 ×2；🔴 贵档与 `indicator` 端点不重试 | 确认参数无误仍报此码即服务端故障 |
 | `410110` | **异步生成中**（HTTP 400，旧码）。新码 `140001`，CLI 两码都认 | 轮询视为 pending | 继续等 |
 | `410111` | **异步生成失败**（HTTP 400，旧码）。新码 `140002`，CLI 两码都认 | 终态 | **不重试**，换参数 |
 | `130002` | 资源不存在——下载类的常见码：`reportId` 不存在 / 非数字多归此码。另有更具体的 `130003`（资源未生成 / 无附件）；`--file-type` 写错由 CLI 在本地报错、不发请求 | — | 确认 ID 有效且本账号可见；换 `--file-type` 或换一篇验证 |
@@ -43,7 +43,7 @@
 - **非法证券代码**：`quote day-kline` / `realtime` / `minute-kline` / `fund-flow` 与 Fundamental 系都会报 `120001`，按报错核对后缀即可。⚠️ **三个已弃用的旧端点 `quote day-kline-hk` / `day-kline-us` / `index-day-kline` 则返回空结果**，与"该票该区间真无数据"无法区分——**用这三个拿到空结果时先回头核对代码后缀**。它们的能力已并入统一 `day-kline`（支持 A 股 / 港股 / 美股 / 沪深 ETF / 交易所指数 / 概念指数 `.GT` / 行业指数 `.CI` `.SWI` / 全球指数），新代码直接用 `day-kline`
 - **枚举值拼错不一定报错**：`--search-type` / `--rank-type` 传非法值报 `100005`；但 `insight foreign-report --region` 写错区域码会返回全量、不报错，拿到「看着正常」的结果。⚠️ **「该端点根本没有这个参数」同样静默**：经 `raw call` 手写请求体时，传端点不支持的字段名（如给 `opinion` 传 `searchType`——它只有 `--rank-type`）会被丢弃、按未传处理，返回未经筛选的结果（专用命令对不存在的选项直接报 unknown option）。**CLI 本地拦截的**：全部 `--search-type` / `--rank-type`、全部 `--file-type`（`foreign-report` 为 1–4、其余 1–2）、`pamirs-summary` 与财报日历的 `--category` / `--market`、`--top` 上限、`reference securities-search` / `institution-search` / `official-account-search` 的 `--category`、`vault record-download` / `my-conference-download` 的 `--content-type`、`ai hot-topic --category`、`ai security-clue --source`。**其余取值（如 `foreign-report --region`、`--llm-tag`、`theme-tracking --type`）CLI 不拦**，写之前对照 `--help` 与对应命令文档核对拼写——**拼错的筛选条件会伪装成「结果正常」**
 - **股票池写操作的单条失败不报错**：`vault stock-pool-add-stock` / `stock-pool-remove-stock` / `stock-pool-delete` 是逐条处理的，证券代码不存在这类单条失败仍返回成功信封（`code` 为 `000000`），失败明细在 `failList` 里。**CLI 已拦**：`failList` 非空时 stderr 列出失败项、结果标 `partial`、退出码 3。绕过 CLI 直连接口时要自己读 `failList`，别只看 `code`
-- **`viewpoint-debate` 的观点过不了平台的敏感词检测时不会被提前拦截**——不返回 `240002`，而是照常受理、扣 50 积分、生成阶段才以 `410111` 失败；同样的内容重提仍会失败。**提交前自己把关措辞**
+- **`viewpoint-debate` 的观点过不了平台的敏感词检测时不会被提前拦截**——不返回 `240002`，而是照常受理、扣 20 积分、生成阶段才以 `410111` 失败；同样的内容重提仍会失败。**提交前自己把关措辞**
 
 ## 官方文档列出、但未见触发的码
 
@@ -116,7 +116,7 @@
 3. 账号是否到期 / 异常：`gangtise auth login` 会真的登录一次，到期或禁用时报 `999012` / `999013`（`auth status` 只看本地缓存，判断不了）
 
 **异步任务 `410111` 反复**（生成失败，终态）
-1. `viewpoint-debate`：先检查观点措辞——过不了敏感词检测的内容不会被提前拦截，会扣 50 积分再以 `410111` 失败；换个说法再提交，同样的内容重试仍会失败
+1. `viewpoint-debate`：先检查观点措辞——过不了敏感词检测的内容不会被提前拦截，会扣 20 积分再以 `410111` 失败；换个说法再提交，同样的内容重试仍会失败
 2. `earnings-review`：换更早的 `--period`（如 `2025q3` → `2025interim`）
 3. `--period` 用已发布的报告期（如 `2025q3` / `2025interim` / `2025annual`）
 4. 若提交阶段就返回 `240001`（财报期未披露），说明该期不可查且**未扣积分**，别再换参数试
@@ -138,4 +138,6 @@
 
 **同一公司既是股票又是 DR** → `securities-search` 默认返回所有分类 → 加 `--category stock` 收敛。
 
+**`--category stock` / `fund` 的结果里出现 `category: bond`** → 可转债不受 `--category` 约束、按简称查时常排第一（如「甬金」→ `113636.SH 甬金转债`） → 只取 `category` 等于所查类别的行；查股票可改用公司全称，查基金换更具体的基金简称。债券代码传给基金命令返回空结果、不报错，传给股票行情 / 财报报 `120001`。
+
 **`sector-constituents` 返回 0 条** → sectorId 不对（题材 conceptId 与板块 sectorId 是两套 ID，不通用）→ 先 `reference sector-search --keyword <名>` 拿 `sectorId` 重试。

package/gangtise-openapi/references/examples.md

@@ -2,7 +2,7 @@
 
 每个示例展示从用户语句到完整命令的全流程。示例集中在这里，Skill 主文件只放规则；遇到不确定的场景时来这里查同类。
 
-**日期占位**：`<今天>`、`<今天-7天>`、`<最新交易日>` 这类写法按实跑当天换算成 `YYYY-MM-DD`；写成具体日期的（如报告期末 `2025-12-31`）照抄即可。回溯窗口有限（研报、观点等约 3 个月），别把旧日期原样照抄。
+**日期占位**：`<今天>`、`<今天-7天>`、`<最新交易日>` 这类写法按实跑当天换算成 `YYYY-MM-DD`；写成具体日期的（如报告期末 `2025-12-31`）照抄即可。各接口能回溯多久不同（见 `SKILL.md`「数据范围」），别把旧日期原样照抄。
 
 ---
 
@@ -137,7 +137,7 @@
 1. 路由 → insight research list；公司名不在速查表
 2. 先调 reference securities-search：
      gangtise reference securities-search --keyword 蔚蓝生物 --category stock --top 3 --format json
-   返回 list[0].gtsCode = "603739.SH"
+   取第一条 category 为 stock 的 gtsCode = "603739.SH"（按简称查时同名可转债可能排在前面）
 3. 拼正式查询：
      gangtise insight research list --security 603739.SH --rank-type 2 \
        --start-time "<今天-7天> 00:00:00" --end-time "<今天> 23:59:59" --format json
@@ -188,9 +188,9 @@
    → 取 content 呈现
 5. 不能等那么久时去掉 --wait：提交返回 {dataId, status, hint}，之后手动查：
      gangtise ai earnings-review-check --data-id xxx --format json
-   - 若 {dataId, status: "pending", hint} → 过两分钟再查；**仍在生成时别重新提交**（重提再扣 50 积分），把 dataId 交给用户稍后查
+   - 若 {dataId, status: "pending", hint} → 过两分钟再查；**仍在生成时别重新提交**（重提再扣 20 积分），把 dataId 交给用户稍后查
    - 若 {date, content} → 取 content 呈现
-   - 若 410111（新码 140002）→ 终态失败，**不要重提同一任务**（会再扣 50 积分且结果相同）；改参数后再提交，或直接告知用户该期数据暂不可用
+   - 若 410111（新码 140002）→ 终态失败，**不要重提同一任务**（会再扣 20 积分且结果相同）；改参数后再提交，或直接告知用户该期数据暂不可用
 ```
 
 ## 例 13：题材画像 ＋ 成分股（先查 ID 再拉两接口）
@@ -343,7 +343,7 @@
      --market aShares --category performanceForecast \
      --size 50 --format json
    → list[].securityName / title / publishDate / performanceReportId / hasAttachment
-5. 用户要原文时：只有 hasAttachment: true 能下（A股 10 积分/篇）
+5. 用户要原文时：只有 hasAttachment: true 能下（A股 1 积分/篇）
    gangtise insight performance-calendar download --performance-report-id 33753017 --output ./预告.pdf
 ```
 

package/gangtise-openapi/references/fields.md

@@ -2,24 +2,20 @@
 
 > 按命令分组，`--field` 参数可重复传入。不传 `--field` 时返回全部字段。`quote` 系多只证券或全市场时传了 `--field` 而缺身份列，CLI 会把它补到最前并在 stderr 说明：日 K 补 `securityCode` / `tradeDate`、分钟 K 补 `securityCode` / `tradeTime`、实时行情补 `securityCode`；单只证券不补（`fund-flow` 本就自带 `securityCode` / `tradeDate`）。
 
-## 🔴 字段名写错时，两族接口的表现完全不同
+## 🔴 字段名写错时，各族接口的表现不同
 
-`--field` 里写了一个不存在的字段名（拼错、或该字段已下线），**行情与 fundamental 这两族接口都不会报错**（`bond` 的 `--field` 写错会整批报 `100003`），但丢的东西不一样——这决定了你能不能按位置拍平结果：
+`--field` 里写了一个不存在的字段名（拼错、或该字段已下线），多数接口整条报错并点名，**行情这一族不报错**：
 
 | 接口 | 响应里发生什么 | CLI 怎么处理 |
 | :-- | :-- | :-- |
-| `quote realtime` / `day-kline` / `minute-kline` / `fund-flow` | **字段名和值一起消失**，`fieldList` 里也没有它，列数与值数始终对得上 | 比对请求与返回的列名，缺列标 `partial` + `missingFields`、在 stderr 点名、**退出码 3** |
-| `fundamental main-business` / `valuation-analysis` | **字段名照请求回显在 `fieldList` 里，行里却少一个值**，两者长度对不上 | 检测到长度不匹配**直接报错退出 1**，不输出任何可能错位的数据 |
+| `quote realtime` / `day-kline` / `minute-kline` / `fund-flow` | **不报错，字段名和值一起消失**，`fieldList` 里也没有它，列数与值数始终对得上 | 比对请求与返回的列名，缺列标 `partial` + `missingFields`、在 stderr 点名、**退出码 3** |
+| `fundamental main-business` / `valuation-analysis` | 整条报 `100005`，msg 点名写错的名字（`fieldList 枚举值非法: <名字>`） | 原样报错，退出 1 |
+| `bond` / `fund` | 整条报 `100003` 并点名 | 原样报错，退出 1 |
 
-**第二族才是危险的那个**：`fieldList` 比行长，按下标对位会让缺口之后的每一个值都贴到错误的字段名上——一列合理的数字配着错误的表头，肉眼看不出来。CLI 因此选择整条失败而不是给你一份错位的表。
+**行情这一族才是要留神的那个**：结果只是少一列、看着正常。绕过 CLI 直连时，`fieldList` 与行**始终等长**，只比长度什么都查不出来——要拿**请求的字段名**去比**返回的 `fieldList`**，少了哪个就是那个名字没被认出来。
 
 **结论一样**：`--field` 的字段名以本文件为准，不确定就别传（不传即返回全部字段，永远安全）。
 
-绕过 CLI 直连接口时**两族要查的东西不同，别只做一种**：
-
-- `quote` 系：`fieldList` 与行**始终等长**，只比长度什么都查不出来——要拿**请求的字段名**去比**返回的 `fieldList`**，少了哪个就是那个名字没被认出来
-- `fundamental` 两个：`fieldList` 会把你写的名字原样回显，所以对比请求没用——要比 **`fieldList` 长度与每行的值个数**，对不上就不能按下标取值
-
 ---
 
 ## Quote 行情
@@ -193,7 +189,7 @@
 
 ### 主营业务 (`fundamental main-business`)
 
-> ⚠️ `--field` 写错字段名时**只丢值、字段名照回显**，CLI 会因长度不匹配报错退出 1——见本文顶部「字段名写错时，两族接口的表现完全不同」。
+> `--field` 写错字段名整条报 `100005` 并点名——见本文顶部「字段名写错时，各族接口的表现不同」。
 
 | 字段 | 含义 | 字段 | 含义 |
 |------|------|------|------|
@@ -206,7 +202,7 @@
 
 ### 估值分析 (`fundamental valuation-analysis`)
 
-> ⚠️ `--field` 写错字段名时**只丢值、字段名照回显**，CLI 会因长度不匹配报错退出 1——见本文顶部「字段名写错时，两族接口的表现完全不同」。🔴 例外：`--field` 里一个数值列都没有时（只传 `tradeDate`、或只有不存在的名字），接口返回 0 行、不报错。 `tradeDate` 总在第一列返回，不用写进 `--field`（写了 CLI 会自动去掉）。
+> `--field` 写错字段名整条报 `100005` 并点名——见本文顶部「字段名写错时，各族接口的表现不同」。🔴 `--field` 只传 `tradeDate` 时接口返回 0 行、不报错，至少要带一个数值列。`tradeDate` 总在第一列返回，不用写进 `--field`。
 
 | 字段 | 含义 | 字段 | 含义 |
 |------|------|------|------|

package/gangtise-openapi/references/response-schema.md

@@ -67,7 +67,7 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | quote fund-flow | `{fieldList, list, total}` 列式 → 规范化后 `{list: [{...}], total}` 宽表 | `securityCode` / `tradeDate` + 请求的字段（`mainNetInflow` / `largeInflow` / `xlargeOutflow` / …） |
 | fundamental income-statement / balance-sheet / cash-flow（含 quarterly / -hk / -us） | `{total, list: [{...}]}` | `fiscalYear` / `period` / `endDate` / `companyName` / `companyType` / `currency` / `unit` + 各 `--field` 字段；港股/美股另含 `timeCovered`（不规则跨度）。⚠️ A 股 `*-quarterly` 单季表的 `companyType` 返回未映射的数字码（如 `102119999`），`currency` 正常；累计口径的三张表两列均正确。科目数字不受影响 |
 | fundamental main-business | `{fieldList, list}` 列式 → 规范化后 `{list: [{...}]}` | 前 3 列恒定：`periodName` / `periodEndDate` / `categoryName`（分项名，随 `--breakdown` 变）+ `opRevenue` / `opRevenueYoy` / `opRevenueRatio` / `opCost` / `opCostYoy` / `opCostRatio` / `grossProfit` / `grossProfitYoy` / `grossProfitRatio` / `grossMargin` / `grossMarginYoy` / `grossMarginRatio`（共 15 个）。`--field` 只能从后 12 个里选 |
-| fundamental valuation-analysis（仅 A 股） | `{fieldList, list}` 列式 → 规范化后 `{list: [{...}]}` | `tradeDate` / `value` / `percentileRank` / `average` / `median` / `upper1Std` / `lower1Std`（共 7 个）；**无 `securityCode`**——`--field` 只传不存在的名字（含 `securityCode`）时接口返回 0 行、不报错，与数值列混传时 CLI 报错退出 1 |
+| fundamental valuation-analysis（仅 A 股） | `{fieldList, list}` 列式 → 规范化后 `{list: [{...}]}` | `tradeDate` / `value` / `percentileRank` / `average` / `median` / `upper1Std` / `lower1Std`（共 7 个）；**无 `securityCode`**——`--field` 写不存在的名字（含 `securityCode`）报 `100005`；只传 `tradeDate` 返回 0 行、不报错 |
 | fundamental earning-forecast（仅 A 股） | `{securityCode, securityName, updateList: [...]}` | `updateList[].date` / `updateList[].fieldList[].forecastYear` + 各 consensus 指标 |
 | fundamental top-holders | `{holderType, list: [{...}]}` | `reportPeriod` / `rank` / `shareholderName` / `shareholderType` / `holdingNum` / `holdingPct` / `chgNum` / `chgPct` / `shareCategory` |
 | ai knowledge-batch | `{list: [{...}]}` | `list[].resourceType` / `list[].sourceId` / `list[].title` / `list[].summary` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gangtise-openapi-cli",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "CLI for Gangtise OpenAPI",
   "license": "MIT",
   "repository": {