gangtise-openapi-cli 0.45.0 → 0.47.0

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

@@ -38,7 +38,7 @@
 ## 内资机构观点 `insight opinion list/detail`
 
 ```bash
-gangtise insight opinion list [--keyword <text>] [--research-area <id>] [--chief <id>] [--security <code>] [--broker <id>] [--industry <id>] [--concept <id>] [--llm-tag <tag>] [--source <src>] [--rank-type <n>] [--with-content]
+gangtise insight opinion list [--keyword <text>] [--research-area <id>] [--chief <id>] [--security <code>] [--broker <id>] [--industry <id>] [--concept <id>] [--category <name>] [--llm-tag <tag>] [--broker-tag <tag>] [--source <src>] [--rank-type <n>] [--with-content]
 gangtise insight opinion detail --chief-opinion-id <id> [--chief-opinion-id <id>...]
 ```
 
@@ -47,10 +47,18 @@ gangtise insight opinion detail --chief-opinion-id <id> [--chief-opinion-id <id>
 - 🔴 **列表只含摘要**：`brief` 是正文前 200 字的截断，**1 积分/条**。要正文用 `detail` 按 `chiefOpinionId` 取（`content`，**30 积分/条**，按返回条数计）；或 `list --with-content` 让列表直接带正文（30 积分/条）。只需判断相关性、做筛选时看 `brief` 就够，别默认加 `--with-content`
 - `detail` 与 `--with-content` 都按返回条数计费，**超时 / 5xx 不自动重发**（重发可能对已交付的正文再计一次费），偶发失败自行重跑
 - ⚠️ **`--with-content` 返回的是旧版结构**：标题与正文在 `contentList.title` / `contentList.content`（`contentList` 是对象，不是数组），顶层没有 `title` / `brief`。按 `content` 字段名取会取不到；要统一成 `detail` 的结构就走 `list` + `detail`
+- ⚠️ **`--with-content` 的筛选项与默认列表不同**：不支持 `--category` / `--broker-tag`（同时传本地直接报错：旧版列表不认这两个字段，会按 30/条返回未经筛选的结果）；`--llm-tag` 只收 `strongRcmd` / `earningsReview` / `topBroker` / `newFortune` 四个值，下面的投研业务标签除 `strongRcmd` 外传给它都报 `100005`。返回行也没有 `categoryList` / `brokerTagList`。既要按类别 / 标签筛、又要正文，走 `list` + `detail`
 - `detail`：ID 可重复传或逗号分隔，CLI 去重后按 **20 个一批**自动拆分请求。**没有有效正文的 ID 不报错、直接跳过**（ID 写错时即如此；刚发布的观点也可能暂时取不到，稍后重取）。CLI 比对请求与返回，缺的 ID 列在 `missingIds`；某一批请求失败或返回异常时，已取到的正文（包括这一批里已返回的）照常输出，没取到的 ID 列在 `unfetchedIds`、原因在 `unfetchedError`，只需对这些 ID 重跑。两种情况都标 `partial`、**退出 3**
-- 返回字段（list）：`chiefOpinionId` / `publishTime` / `title` / `brief` / `author{chiefId, chiefName, researchAreaList, brokerID, brokerName}` / `securityList[]` / `industryList[]` / `conceptList[]` / `llmTagList`；`detail` 另加 `content`。`author.chiefId` / `chiefName` 在机构点评类观点上为 `null`
-
-- `--llm-tag`：`strongRcmd` 强烈推荐 | `earningsReview` 业绩点评 | `topBroker` 头部券商 | `newFortune` 新财富团队
+- 返回字段（list）：`chiefOpinionId` / `publishTime` / `title` / `brief` / `author{chiefId, chiefName, researchAreaList, brokerID, brokerName}` / `securityList[]` / `industryList[]` / `conceptList[]` / `categoryList` / `llmTagList` / `brokerTagList`（三个标签字段取值同下方筛选项的英文标识，无标签时为 `[]`）；`detail` 另加 `content`。`author.chiefId` / `chiefName` 在机构点评类观点上为 `null`
+
+- `--category`（观点类别）：`earningsReview` 业绩点评 | `abnormalReview` 异动点评 | `researchUpdate` 调研/访谈更新 | `tradingDesk` 交易台 | `industryAnalysis` 行业分析。一条观点可同时属于多个类别
+- `--llm-tag`（投研业务标签）：
+  - 推荐：`strongRcmd` 强烈推荐 | `undervalued` 低估值 | `highElasticity` 高弹性 | `highDividend` 高股息 | `reversal` 拐点/反转 | `bottom` 底部 | `beatExpect` 超预期 | `expectGap` 预期差 | `oversold` 错杀/超跌 | `targetPrice` 目标股价/市值 | `certainty` 确定性
+  - 业绩侧：`highGrowth` 高增 | `withProfitForecast` 含盈利预测 | `withGuidance` 含指引 | `marginalImprovement` 边际改善
+  - 产业链：`priceHike` 涨价 | `tightSupplyDemand` 供需趋紧 | `capacityRelease` 产能释放 | `newOrder` 新订单 | `orderSurge` 订单高增/大单 | `keyCustomer` 大客户 | `soleSupplier` 独供/一供 | `coreSupplier` 核心供应商 | `industryEntry` 产业导入
+  - 壁垒：`leader` 龙头 | `moat` 壁垒 | `scarcity` 稀缺性 | `breakthrough` 突破
+- `--broker-tag`（机构标签）：`topBroker` 头部券商 | `newFortune` 新财富团队
+- 三个标签选项传非法值报 `100005`。**同一选项传多个值取并集**（命中任一即返回）：`--llm-tag strongRcmd --llm-tag beatExpect` 是「强烈推荐或超预期」，不是「两者都有」；要两者都有，取回后按返回行的 `llmTagList` 自行过滤
 - `--source`：`realTime` 实时 | `openSource` 开放来源
 - `--industry`：用 `citicIndustry` 码 `1008001xx`；申万码 `104xx0000` 也生效，但**两套码的行业成分不同、取回的结果集不一致**，同一批查询别混用。`--research-area`：行业用 `citicIndustry` 码 `1008001xx`、方向用 `gangtiseIndustry` 码 `122000xxx`，**申万码在本端点返 0**。详见 `reference-and-lookup.md`
 
@@ -61,7 +69,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 +104,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 +144,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 +174,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 +199,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 +212,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 +225,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 +241,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 +269,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` 或换一篇验证 |
@@ -41,9 +41,9 @@
 - **日期用「年在前」写法**：`YYYY-MM-DD`（首选）、`YYYY/MM/DD`、`YYYYMMDD` 三种 CLI 都收，并**统一归一成 `YYYY-MM-DD` 再发出**；时间加 `[ HH:mm[:ss]]`（秒可省、空格或 `T` 分隔）或用 10/13 位时间戳。🔴 **「年在后」写法（`01-07-2026`、`07/01/2026`）CLI 直接报 `ValidationError`，这是有意的**——接口本身会解析它，且**一律按美式「月在前」**（`01-07-2026` = 1 月 7 日，`07-01-2026` = 7 月 1 日）。按欧洲/国际习惯写 `01-07-2026` 想表达「7 月 1 日」的，会拿到差半年的数据且**不报错**；本地拒掉才有信号，还省一次请求与计费。绕过 CLI 直连接口时务必自己统一用 `YYYY-MM-DD`
 - **财报接口的日期按「报告期末」过滤**，不是公告日：`fundamental balance-sheet` 等的 `--start-date`/`--end-date` 匹配的是 `endDate` 字段（如 `20200630`）；公告日看 `earliestAnncDate`（首次公告日，做时点对齐用这个）而不是 `announcementDate`。**查某期财报要传季度末日期**（`2020-06-30` / `2020-03-31` / `2020-09-30` / `2020-12-31`）；传 `2020-07-01` 这类非报告期日期会返回 0 行，属正常行为，不是没数据
 - **非法证券代码**：`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` 与对应命令文档核对拼写——**拼错的筛选条件会伪装成「结果正常」**
+- **枚举值拼错不一定报错**：`--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 不拦**（`opinion list` 的 `--category` / `--llm-tag` / `--broker-tag` 写错由服务端报 `100005`），写之前对照 `--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`「数据范围」），别把旧日期原样照抄。
 
 ---
 
@@ -35,7 +35,7 @@
 
 ```
 1. 路由 → insight opinion list
-2. "最近" → Insight 默认 7 天；"AI" → --keyword AI
+2. "最近" → Insight 默认 7 天；"AI" → --keyword AI（用户限定「业绩点评」「超预期」「头部券商」这类 → --category / --llm-tag / --broker-tag，取值见 commands/insight.md）
 3. Pre-flight：模糊时间已映射，认证 OK，无歧义
 4. gangtise insight opinion list \
      --keyword AI \
@@ -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

@@ -20,8 +20,8 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 
 | 命令 | data 结构 | 关键提取字段 |
 |------|----------|------------|
-| insight opinion list | `{list, total}` | `list[].chiefOpinionId`（`detail` 用）/ `list[].title` / `list[].brief`（正文前 200 字）/ `list[].publishTime` / `list[].author{chiefId, chiefName, researchAreaList, brokerID, brokerName}`（机构点评类 `chiefId` / `chiefName` 为 `null`）/ `list[].securityList[]{securityCode, securityName}` / `list[].industryList[]{industryCode, industryName}` / `list[].conceptList[]{conceptId, conceptName}` / `list[].llmTagList` |
-| insight opinion list --with-content | `{list, total}`（旧版结构） | 同上但**没有顶层 `title` / `brief`**；标题与正文在 `list[].contentList.title` / `list[].contentList.content`（对象，不是数组） |
+| insight opinion list | `{list, total}` | `list[].chiefOpinionId`（`detail` 用）/ `list[].title` / `list[].brief`（正文前 200 字）/ `list[].publishTime` / `list[].author{chiefId, chiefName, researchAreaList, brokerID, brokerName}`（机构点评类 `chiefId` / `chiefName` 为 `null`）/ `list[].securityList[]{securityCode, securityName}` / `list[].industryList[]{industryCode, industryName}` / `list[].conceptList[]{conceptId, conceptName}` / `list[].categoryList` / `list[].llmTagList` / `list[].brokerTagList`（无标签为 `[]`） |
+| insight opinion list --with-content | `{list, total}`（旧版结构） | 同上但**没有顶层 `title` / `brief`，也没有 `categoryList` / `brokerTagList`**；标题与正文在 `list[].contentList.title` / `list[].contentList.content`（对象，不是数组） |
 | insight opinion detail | `{total, list}`；缺失时另有 `missingIds` / `unfetchedIds` / `unfetchedError` + `partial` | `list[]` 同 list 的字段 + `content`（正文全文） |
 | insight summary list | `{list, total}` | `list[].summaryId` / `list[].title` / `list[].publishTime` |
 | insight summary download | 文件路径（stdout） | — |
@@ -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.47.0",
   "description": "CLI for Gangtise OpenAPI",
   "license": "MIT",
   "repository": {