gangtise-openapi-cli 0.40.1 → 0.41.1

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

@@ -0,0 +1,132 @@
+# Bond 命令详细参数
+
+**全部计费，0.4 积分起**：多数按次（与返回行数无关）；`rating-overview` 按条、`rating-change` 按有数据的债券只数、`issuer-rating-change` 按发行人计，见各命令。
+
+`--security` 收**标准债券代码**——`019742.SH` / `123456.SZ` / `220205.IB`（银行间）。**不接受简称或拼音**，传了按 `120001` 整批拒绝、不会退化成模糊匹配；只有简称时先 `reference securities-search --keyword <简称>` 换代码。可重复，也接受逗号分隔；有单次只数上限的命令按**去重后**的只数计。
+
+⚠️ **超时 / 5xx 不自动重放**（避免重复扣费），偶发失败自行重跑。
+
+---
+
+返回是**列式**的（`fieldList` + 数组行），CLI 已自动拍平成对象，直接按字段名取值即可。
+
+`--field` 可重复，不传返回全部字段。**传了不支持的字段名整批拒绝**（`100003` 并指名），不会静默丢列——与 `quote` 系「字段名和值一起消失」的行为不同。各命令的默认返回列（无需指定）见下。
+
+## 日期与权限窗口
+
+`bond daily-quote` / `bond valuation` / `bond issuance-plan` 的历史范围是**正式账号前溯 5 年、试用 3 年**，其余命令不限。
+
+⚠️ **`--start-date` 早于可回溯下界时整批返回 `110003`「超出时间范围限制」**（这三个命令都是）——即使 `--end-date` 在窗口内，也不会只返回窗口内那一段。把 `--start-date` 移进窗口再查；实际下界随账号服务等级而定，以返回为准。
+
+## `basic-info` 债券基本资料
+
+```bash
+gangtise bond basic-info --security <code> [--security <code>...] [--field <name>]
+```
+
+静态档案，**不提供历史快照**。默认返回 `securityCode`。单次最多 10000 只。格式合法但库中无资料的债券**不报错**，仍占一行、除 `securityCode` 外全为 `null`。
+
+字段分组：基础标识 / 发行信息 / 期限与日期 / 利率与付息 / 评级 / 担保 / 特殊条款 / 质押回购 / ABS 专项（`abs*`，仅资产支持证券有值）/ 可转债专项（`conversion*`，仅可转债有值）。
+
+- `parValue`、`issuePriceOrReferenceYield` 是 `/` 分隔的**复合展示值**（`"100.00/100.00"`），某侧无数据时以 `-` 占位。要数值用 `latestParValue`
+- `actualMaturityDate` 含提前赎回 / 回售 / 全额转股，未提前终止时与 `maturityDate` 一致；算剩余期限用前者
+- `remainingDays` 已到期返回 `0`
+
+## `issuer-info` 发债主体基本信息
+
+```bash
+gangtise bond issuer-info (--security <code>... | --issuer <name>...) [--field <name>]
+```
+
+🔴 **`--security` 与 `--issuer` 二选一**，同时传报 `100003`（CLI 会先本地拦下）。`--issuer` 按公司全称或简称**模糊匹配**，一个名称只返回最匹配的一家，匹配不到不产生行。默认返回 `issuerName`。
+
+- 行业有两套：`swIndustry` 是**申万**「一级/二级」（如 `"食品饮料/白酒Ⅱ"`），`nationalIndustry` 是**国民经济行业分类**「一级/二级」（如 `"制造业/酒、饮料和精制茶制造业"`）。某一级无数据时该侧以 `-` 占位；要申万一级按 `/` 切前半段
+- `latestIssuerRating` 是复合值 `评级(展望,日期)`（如 `"AAA(维持,2026-08-11)"`），但**括号部分可能缺省**、只返回评级符号（如 `"AAA"`）——解析时别用硬套括号的正则
+- ⚠️ **这一列混合了境内与境外评级口径**：既可能是境内机构（中诚信、大公等）的评级，也可能是惠誉等国际机构的评级，两套口径不可直接比较。做信用排序或筛选前，**一并取 `ratingAgency` 判断口径**
+- `outstandingBondList` 是存续债券**简称**的中文逗号分隔串；要代码得拿简称去 `reference securities-search` 换
+
+## `daily-quote` 债券日收盘行情
+
+```bash
+gangtise bond daily-quote --security <code>... --start-date <d> --end-date <d> [--field <name>]
+```
+
+**日期必填**。默认返回 `securityCode` + `tradeDate`。字段分组：全价（`dirty*`）/ 净价（`clean*`）/ 成交与收益率（`ytmClose` `volume` `turnover` `ytc` `ytp`）/ 风险指标（`duration` `modifiedDuration` `convexity`）/ 票息要素。不限传入只数。
+
+## `valuation` 上清所估值
+
+```bash
+gangtise bond valuation --security <code>... --start-date <d> --end-date <d> [--confidence-level 推荐|不推荐] [--field <name>]
+```
+
+**日期必填**。默认返回 `securityCode` + `tradeDate` + `confidenceLevel`。**`--confidence-level` 不传默认只返回「推荐」的估值**——要看全部需显式传另一个值分别查。风险指标含 `pvbp`、利率与利差各自的久期凸性。
+
+## `cash-flow` / `issuance-detail` / `rating-change` / `exercise-notice`
+
+```bash
+gangtise bond cash-flow              --security <code>... [--start-date <d>] [--end-date <d>] [--field <name>]   # 日期筛兑付日
+gangtise bond issuance-detail        --security <code>... [--start-date <d>] [--end-date <d>] [--field <name>]   # 日期筛发行公告日
+gangtise bond rating-change          --security <code>... [--start-date <d>] [--end-date <d>] [--field <name>]   # 日期筛评级变动公告日，最多 10 只
+gangtise bond exercise-notice        --security <code>... [--start-date <d>] [--end-date <d>] [--field <name>]   # 日期筛行权日
+```
+
+日期可省略，省略则返回全部历史。默认返回列各不相同：`cash-flow` 是 `securityCode`+`paymentDate`，`issuance-detail` 是 `securityCode`+`issueBatchNo`，`rating-change` 是 `securityCode`+`announcementDate`，`exercise-notice` 是 `securityCode`+`exerciseDate`。
+
+🔴 **`rating-change`（债项评级变动）单次最多 10 只**（按去重后计，CLI 本地拦截并提示分批），计费按**有数据的债券只数**。一只债券每次评级变动一行，返回本次 / 上次评级（`currentRating` / `previousRating`）、变动方向、评级展望、评级类型与评级机构；首次评级的 `previousRating` 为 `null`。
+
+## `rating-overview` 债券评级一览
+
+```bash
+gangtise bond rating-overview --security <code>... [--field <name>]
+```
+
+债项 / 发行人 / 担保人三套评级并列，一只债券一行。🔴 **单次最多 10 只**（按去重后计），计费按**条**。
+
+⚠️ **评级值可能带小写后缀**：`sf`（结构化融资产品评级，如 `AA+sf`）、`pi`（中债资信主动评级，如 `AAApi`），紧跟评级符号、无分隔符。按档位匹配、排序或分档统计前先识别处理，否则 `AAA` 与 `AAApi` 会被当成两档。`rating-change` / `issuer-rating-change` 同样适用。
+
+## `issuer-rating-change` 发债主体评级变动
+
+```bash
+gangtise bond issuer-rating-change (--security <code>... | --issuer <name>...) [--start-date <d>] [--end-date <d>] [--field <name>]
+```
+
+**二选一**，同 `issuer-info`。默认返回 `issuerName`+`announcementDate`。命中的发行人总数超过 10 个触发 `100006`。计费按**发行人**。
+
+## `issuance-plan` 利率债发行计划
+
+```bash
+gangtise bond issuance-plan --start-date <d> --end-date <d> [--field <name>]
+```
+
+🔴 **只按日期区间查，不收债券码**，日期必填。默认返回 `issueDate`。返回计划年份、发行人、债券性质与类型、期限、计划发行量、利率类型、付息频率、是否跨市场。
+
+## `announcement` 债券公告
+
+```bash
+gangtise bond announcement (--security <code>... | --start-date <d> --end-date <d>) [--page-no N] [--page-size N] [--field <name>]
+```
+
+🔴 **`--security` 与 `--start-date`/`--end-date` 二选一**，同传报 `100003`（CLI 先本地拦下）。默认返回 `announcementDate`+`securityCode`。
+
+🔴 **本命令需要手动翻页**：它是本族唯一分页的接口，且响应里**没有 `total`**，因此不走 CLI 的自动翻页。`--page-no` 从 1 开始逐页递增，`--page-size` 取值 1–200（超出报 `100004`）。终止条件：
+
+- 翻过末页返回**空数组**（`--format json` 输出 `[]`，退出码 0）——到这一页就停
+- 条件下**一条公告都没有**时，任何页码都返回 `404` / `130001`（退出码 1）——第 1 页收到它就是没有数据，不用再翻
+
+⚠️ **按日期区间查询时，返回的 `securityCode` 不带市场后缀**（如 `012682337`）；按 `--security` 查询时带后缀。要把结果接着传给其他 `bond` 命令（它们只收带后缀的代码，否则 `120001`），用该行的 `securityName` 走 `reference securities-search --keyword <简称>` 换回带后缀的 `gtsCode`，并核对它去掉后缀后与原代码一致。**别拿不带后缀的代码本身去搜**——检索按相似度返回，可能给出相邻的其他代码；部分资产支持证券按简称也检索不到。
+
+其余债券命令一次返回全部匹配行。
+
+## 空结果
+
+查询条件合法但全部没有数据时（如区间内全是非交易日、区间内无发行计划），返回 `404` / `130001 数据未找到`，表示没有数据、不是故障。只有部分代码有数据时不报错：
+
+- `basic-info`、`rating-overview`、按 `--security` 查的 `issuer-info`：**每个代码固定占一行**（按去重后的请求顺序），没数据的行除代码外全为 `null`
+- 其余命令（以及按 `--issuer` 查的两个命令）：没数据的代码**不产生行**，用「请求的代码 − 返回里出现的代码」判断哪些没数据
+
+另外国债这类品种本身没有评级与行权数据，查 `rating-overview` / `rating-change` / `exercise-notice` 返回 `130001` 属正常。
+
+## 相关常量
+
+债券字段里的枚举 ID 可通过 `reference constant-list --category <code>` 查全量：
+`bondType` 债券类型 | `interestRateType` 利率类型 | `interestFrequency` 付息频率 | `absUnderlyingAssetType` ABS 基础资产类型 | `ratingType` 评级类型 | `exchange` 交易市场。

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

@@ -92,8 +92,10 @@ gangtise fundamental valuation-analysis --security-code <code> --indicator <name
 - **市场与路由**：本命令仅支持 A 股（港股 / 美股会报 `120001`「非有效A股」）。A股单证券估值序列与估值历史分位始终优先本命令；多证券批量取一组已实现估值点值，且 `indicator search` 三项校验都通过时，才优先 EDE `cross-section` / `time-series`。港 / 美股估值历史分位当前 CLI 不支持，不能用普通 EDE 点值冒充
 - `--indicator`（**必选**）：`peTtm` 滚动PE | `pbMrq` PB | `peg` PEG | `psTtm` 滚动PS | `pcfTtm` 滚动PCF | `em` 企业倍数
 - `--limit` 默认 2000，省略 `--start-date` 时自动查近一年
+- 🔴 **序列按自然日逐日一行（含周末）**，行数超过 `--limit` 时接口**保留最近的行、丢掉区间开头**。CLI 撞满即标 `partial`、退出码 3 并在 stderr 说明（首行恰好就是 `--start-date` 时说明没丢，不标）。取长区间把 `--limit` 设到不小于区间天数（账号权限窗口内的十年约 3700 行，可设 `--limit 4000`）
+- 🔴 **`--start-date` 早于账号回溯下界时，接口从下界起返回、不报错**（整段都在界外才报 `110003`）。首行晚于 `--start-date` 时 CLI 在 stderr 提示——可能是该证券上市较晚，也可能是撞了权限窗口，看首行日期判断
 - `--skip-null`：丢弃 `value`/`percentileRank` 为 null 的行（最新交易日可能未入库）
-- **返回字段只有 7 个**：`tradeDate` `value` `percentileRank` `average` `median` `upper1Std` `lower1Std`。**没有 `securityCode`**——误传会拿到一列重复的 `tradeDate`（长度相等，CLI 拦不住），传其他不存在的字段名则直接报错。**建议不传 `--field`**，证券代码本来就是你自己传进去的
+- **返回字段只有 7 个**：`tradeDate` `value` `percentileRank` `average` `median` `upper1Std` `lower1Std`，**没有 `securityCode`**。🔴 `--field` 里**至少要有一个数值列**（`tradeDate` 以外的 6 个）：只传 `tradeDate`、只传不存在的名字（含 `securityCode`）时接口返回 0 行、**不报错**，读起来像「这只票没有估值数据」；数值列与不存在的名字混传时，回显的字段比每行的值多，CLI 直接报错退出 1。`tradeDate` 总在第一列返回，不用写进 `--field`（写了 CLI 会在发请求前去掉；同一字段写两次也只发一次）。**建议不传 `--field`**，证券代码本来就是你自己传进去的
 
 ## A股盈利预测 `fundamental earning-forecast`
 

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

@@ -278,7 +278,7 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 | `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`），空表表示整轴 code 未识别或参数名写错 | CLI 对 indicator 端点**不重试此码**；确认参数无误仍报错，稍后再试或联系平台支持 |
-| `110003` | **超出账号数据权限的时间范围**。窗口按**账号**配、不按接口配——`cross-section` / `time-series` / `screener` 同界，`quote day-kline` 也在同一条界上 | 把日期移进范围；整段区间都早于下界时缩短窗口无用，**换接口绕不过去**，要更长历史联系客户经理开通 |
+| `110003` | **超出账号数据权限的时间范围**。窗口按**账号**配、不按接口配——`cross-section` / `time-series` / `screener` 同界，区间**跨过**下界也整批报这个码；`quote day-kline` 在同一条界上，但跨界时从下界起返回、不报错 | 把起点移进范围；整段区间都早于下界时缩短窗口无用，**换接口绕不过去**，要更长历史联系客户经理开通 |
 | `130001`（旧 `410004`） | 数据未找到，或**该指标无权限**（内层信封失败会带具体 msg，如"指标无权限"；此码被服务端复用） | 检查查询条件与指标权限；换证券/日期仍失败多为无权限，联系管理员开通 |
 
 ### 必填参数（`140002` 的根因）
@@ -418,5 +418,5 @@ 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 计
 - **空结果排查顺序**：真无数据会返回占位单元格（统一 `null`）而不是空表，所以**空表基本等于「没有任何 code 被认出来」或参数名写错**。按序排查：① 证券代码与后缀对不对（美股 `.O`/`.N`，不是 `.US`）② 指标 code 拼写对不对 ③ 参数名对不对（`indicator search` 的 `parameterList`）④ 日期语义对不对（`tradeDate` vs `reportDate`——报告期类指标日期用错会整批返 `null`，看着像「没数据」）
-- **数据权限**：正式账号行情 / 财务 / 指标类可回溯的年限按服务等级而定，试用账号更短。这个时间窗口按**账号**配、不按接口配——三个 EDE 接口同界（`quote day-kline` 也在同一条界上），撞界统一返 `110003`，**换接口绕不过去**；整段区间都早于下界时缩短窗口无用，要更长历史联系客户经理开通
+- **数据权限**：正式账号行情 / 财务 / 指标类可回溯的年限按服务等级而定，试用账号更短。这个时间窗口按**账号**配、不按接口配——三个 EDE 接口同界，区间跨过下界也整批返 `110003`（`quote day-kline` 在同一条界上，但跨界时从下界起返回、不报错），**换接口绕不过去**；整段区间都早于下界时缩短窗口无用，要更长历史联系客户经理开通
 - 所有格式（table/json/jsonl/csv/markdown）均可用；导出宽表给 Excel 直接用 `--format csv --output xxx.csv`

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

@@ -45,12 +45,19 @@
 
 ---
 
-## 内资机构观点 `insight opinion list`
+## 内资机构观点 `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>]
+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 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`
+- `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` 新财富团队
 - `--source`：`realTime` 实时 | `openSource` 开放来源
 - `--industry`：用 `citicIndustry` 码 `1008001xx`；申万码 `104xx0000` 也生效，但**两套码的行业成分不同、取回的结果集不一致**（同一行业约相差 5%），同一批查询别混用。`--research-area`：行业用 `citicIndustry` 码 `1008001xx`、方向用 `gangtiseIndustry` 码 `122000xxx`，**申万码在本端点返 0**。详见 `reference-and-lookup.md`
@@ -70,6 +77,24 @@ gangtise insight summary download --summary-id <id> [--file-type <n>] [--output
 - `--category`：`earningsCall` 业绩会 | `strategyMeeting` 策略会 | `fundRoadshow` 基金路演 | `shareholdersMeeting` 股东大会 | `maMeeting` 并购会议 | `specialMeeting` 特别会议 | `companyAnalysis` 公司分析 | `industryAnalysis` 行业分析 | `other`
 - `--file-type`（download 可选）：`1` 原始内容（默认）| `2` HTML 格式；**仅影响来源为会议平台的纪要**
 
+## 会议线索 `insight highlight list`
+
+```bash
+gangtise insight highlight list [--from N] [--size N] [--start-time <t>] [--end-time <t>] [--security <code>] [--research-area <id>]
+```
+
+Gangtise 会议内容的核心要点信息流（官方名「会议线索」），固定按发布时间倒序，适合做每日会议跟踪看板。
+
+- 🔴 **5 积分/条**，按返回条数计。**必须带 `--size`**——省略会自动翻页拉全量（范围内常有数千条）。先 `--size 1` 看 stderr 的 `Total: N` 探量级，再决定取多少
+- `--size` 单页上限 50
+- 按偏移量**最多取到第 10000 条**（`--from` + 条数不能超过 10000）。命中更多时 CLI 取到第 10000 条为止、stderr 说明并**退出 3**；`--from` 本身 ≥10000 直接拒绝。要更多请缩短时间范围分段取
+- `--start-time` / `--end-time`：`yyyy-MM-dd HH:mm:ss`，也接受 `yyyy-MM-dd`（自动补全）。超出账号数据权限窗口返回 `110003`
+- `--security`：证券代码，**大小写敏感需精确匹配**。A 股 `601702.SH`、港股 **5 位数字** `09992.HK`、美股 `AAPL.O`
+- `--research-area`：中信行业码 `1008001xx` 或 Gangtise 方向码 `122000xxx`。⚠️ **本端点不认申万码 `swIndustry`**
+- 返回字段：`highlightId` / `title` 会议名称 / `publishTime` / `content` / `securityList`（含 `securityCode`+`securityName`）/ `researchAreaList`（含 `researchAreaId`+`researchAreaName`）
+- ⚠️ **`content` 是 HTML 片段**：整体由 `<p>` 包裹，各要点小标题由 `<strong>` 包裹，除这两种标签外不含其他标签。要纯文本自行去标签（如 `re.sub(r"<[^>]+>", "", content)`）
+- 要点可能不关联任何证券（`securityList` 为 `[]`），宏观 / 行业类会议尤其常见——按证券筛会漏掉这批
+
 ## 帕米尔纪要 `insight pamirs-summary list/download`
 
 ```bash
@@ -209,18 +234,21 @@ gangtise insight announcement-us download --announcement-id <id> [--file-type <n
 - **积分**：list 0.1/条；download 20/篇
 - `--security TSLA.O` 的 `sourceName` 为「美国证券交易委员会」
 
-## 外资机构观点 `insight foreign-opinion list`
+## 外资机构观点 `insight foreign-opinion list/detail`
 
 ```bash
-gangtise insight foreign-opinion list [--rank-type <n>] [--security <code>] [--region <code>] [--industry <id>] [--broker <id>] [--rating <name>] [--rating-change <name>]
+gangtise insight foreign-opinion list [--rank-type <n>] [--security <code>] [--region <code>] [--industry <id>] [--broker <id>] [--rating <name>] [--rating-change <name>] [--with-content]
+gangtise insight foreign-opinion detail --foreign-opinion-id <id> [--foreign-opinion-id <id>...]
 ```
 
+- 🔴 **列表只含摘要**：`brief`（英文）/ `briefTranslate`（中文），取正文前 200 字，**1 积分/条**。原文与译文（`content` / `contentTranslate`）用 `detail` 按 `foreignOpinionId` 取（**30 积分/条**），或 `list --with-content`（30 积分/条，`content` / `contentTranslate` 直接在顶层，不含 `brief`）。`detail` 的分批与缺失 ID 处理同内资 `opinion detail`
+
 - `--security`：境外证券代码，如 `UBER.N`
 - ⚠️ `--region`：**本端点只接受 6 个取值**——`cn` | `cnHk` | `cnTw` | `us` | `jp` | `uk`。`regionCategory` 常量表里另外 13 个（`sea` / `gl` / `fr` / `de` / `kr` / `in` / `ca` / `me` / `othAs` / `othEur` / `latAm` / `oce` / `af`）在这里一律报 `100005 枚举值非法`，**而它们在 `insight foreign-report` 上全部合法且能正常收窄**。要按这 13 个区域筛，只能用 `foreign-report`，或不带该参数取回后按 `region` 字段本地筛
 - ⚠️ `--industry`：**只认申万码**（`104xx0000`）。中信码报 `100005 枚举值非法`——即使 `reference constant-category` 把本端点列在 `citicIndustry` 的 `usageScopes` 里也一样。⚠️ **返回记录的 `industryList[]` 同时带两套码**（如 `100800122 中信非银` + `104490000 申万非银金融`），**回查时要挑申万那条**，拿中信码回查会报错
 - `--broker`：外资券商 ID（见 `references/lookup-ids.md`）
 - `--rating` / `--rating-change`：同研报
-- 返回字段：`foreignOpinionId` / `title` / `titleTranslate` / `content` / `contentTranslate` / `publishTime` / `publisher{brokerId, brokerName}` / `securityList[]{securityCode, rating, targetPrice, currency}` / `region`
+- 返回字段（list）：`foreignOpinionId` / `title` / `titleTranslate` / `brief` / `briefTranslate` / `publishTime` / `publisher{brokerId, brokerName}` / `securityList[]{securityCode, securityName, rating, ratingChange, targetPrice, currency}` / `industryList[]` / `region{regionCode, regionName}`；`detail` 另加 `content` / `contentTranslate`
 
 ## 外资独立观点 `insight independent-opinion list/download`
 

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

@@ -6,7 +6,7 @@
 
 **关键规则**：查"最近"K线必须显式 `--start-date`/`--end-date` 拉范围，再从 `tradeDate` 取尾部最近 N 条；不要只用 `--limit N`（会截取查询窗口开头）。
 
-🔴 **全市场关键字**：`quote day-kline` 不认 `--security all`，只认三个市场关键字之一——`aShares` / `hkStocks` / `usStocks`，且**必须单独传**（不能与证券代码或另一个关键字混填）。传 `all` 或混填 CLI 会直接报错并提示正确写法。三个已下线的旧命令（`day-kline-hk` / `day-kline-us` / `index-day-kline`）仍认 `all`。
+🔴 **全市场关键字**：`quote day-kline` 不认 `--security all`，只认三个市场关键字之一——`aShares` / `hkStocks` / `usStocks`，且**必须单独传**（不能与证券代码或另一个关键字混填）。传 `all` 或混填 CLI 会直接报错并提示正确写法。已下线的旧命令里，`day-kline-hk` / `day-kline-us` 仍认 `all`；`index-day-kline` 对 `all` 返回空结果，CLI 在发请求前直接拒绝——**全部沪深京指数没有一次拿全的写法**，要逐个传指数代码。
 
 **自动分片**：全市场关键字跨日期范围时 CLI 自动按日切片并并发执行，合并结果返回，无需手动分批。分片粒度按各市场单个交易日的行数规模定，保证单请求不撞 10000 行的 API 上限：
 
@@ -16,7 +16,7 @@
 | `day-kline` | `hkStocks` | 2 天/片 |
 | `day-kline` | `usStocks` | 1 天/片 |
 | `fund-flow` | `aShares` | 1 天/片 |
-| `day-kline-hk` / `day-kline-us` / `index-day-kline`（旧） | `all` | 2 / 1 / 15 天/片 |
+| `day-kline-hk` / `day-kline-us`（旧） | `all` | 2 / 1 天/片 |
 
 分片路径会自动把 `limit` 抬到 10000（API 上限），避免默认 6000 行截断；按日分片自动跳过周六日。
 
@@ -73,7 +73,7 @@ gangtise quote day-kline [--security <code>] [--start-date <YYYY-MM-DD>] [--end-
 
 - 旧命令**不校验证券代码**——传错代码返回空结果（`{"total":0,"list":[]}`）而不是报错，与「该票该区间真无数据」无法区分；`day-kline` 会报 `120001`
 - 参数与字段和 `day-kline` 完全一致（`--security` / `--start-date` / `--end-date` / `--limit` / `--field`），迁移只是换命令名
-- 三者的全市场关键字仍是 `all`（不是 `aShares` 那套）
+- `day-kline-hk` / `day-kline-us` 的全市场关键字仍是 `all`（不是 `aShares` 那套）；`index-day-kline` 没有全市场关键字，只收明确的指数代码
 
 ## 实时行情 `quote realtime`
 
@@ -118,14 +118,11 @@ gangtise quote fund-flow [--security <code>] [--start-date <YYYY-MM-DD>] [--end-
 gangtise quote index-day-kline [--security <code>] [--start-date <YYYY-MM-DD>] [--end-date <YYYY-MM-DD>] [--limit <n>] [--field <name>]
 ```
 
-- 沪深京指数：如 `000001.SH` 上证综指、`399001.SZ` 深成指；`--security all` 全市场指数（**仍是 `all`，不是 `aShares` 那套**）
+- 沪深京指数：如 `000001.SH` 上证综指、`399001.SZ` 深成指，可重复传；**没有全市场关键字**——`--security all` 在这个接口上返回空结果，CLI 直接拒绝
 - `--limit` 默认 6000，上限 10000
-- 常用字段：`securityCode` `securityName` `tradeDate` `open` `high` `low` `close` `preClose` `change` `pctChange` `volume` `amount`
-- `securityName` 为指数名称（如 `上证指数`）
-- **还值得用它的两个场景**（都是 `day-kline` 做不到的）：
-  1. **一次拿全部沪深京指数**（`--security all`）——`day-kline` 的指数必须逐个传代码
-  2. **要指数名称**——`index-day-kline` 返回 `securityName`（如「上证指数」），`day-kline` **没有这个字段**，查指数只拿得到代码
-- 反过来 `day-kline` 独有 `adjustFactor`（复权因子），但指数本来就没有复权，该字段查指数时恒为 `null`
+- 返回字段与 `day-kline` 相同：`securityCode` `tradeDate` `open` `high` `low` `close` `preClose` `change` `pctChange` `volume` `amount` `adjustFactor`（指数恒为 `null`）。**不含指数名称**
+- 没有 `day-kline` 做不到的能力，新代码直接用 `day-kline` 传同样的代码
+- **要指数名称**：`gangtise reference securities-search --keyword 000001.SH --category index`，返回的 `gtsName` 即名称（如「上证指数」）
 
 ## 分钟 K 线 `quote minute-kline`
 

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

@@ -91,7 +91,7 @@ gangtise reference constant-category [--format json]
 
 - 用途：全量导出常量分类及每个分类适用于哪些接口的哪些参数（无需传参，免积分）
 - 返回 `{total, list}`，`list[]` 字段：`category`（分类代码）/ `categoryName` / `structureType`（`flat` 平铺 | `tree` 树形）/ `maxLevel` / `usageScopes[]`（`apiName` + `paramName`）
-- 当前 8 个分类：
+- 分类清单以 `reference constant-category` 的实际返回为准（服务端会随新接口上线增补）。截至 2026-09 的分类：
 
 | category | 名称 | 结构 | 用于参数 |
 |----------|------|------|---------|
@@ -103,6 +103,15 @@ gangtise reference constant-category [--format json]
 | `hkShareAnnouncementCategory` | 港股公告分类 | tree（2 级） | `insight announcement-hk --category` |
 | `usShareAnnouncementCategory` | 美股公告分类（`103980xxx` 段） | tree（2 级） | `insight announcement-us --category` |
 | `regionCategory` | 区域分类 | flat | `insight foreign-report --region` |
+| `nationalEconomicIndustry` | 国民经济行业分类 | flat | 行业归属参考 |
+| `fundType` | 基金分类 | tree（2 级） | 基金类接口的基金分类字段 |
+| `fundBondType` | 基金持仓券种类别 | flat | 基金类接口的券种类别字段 |
+| `bondType` | 债券类型 | flat | `bond basic-info` / `bond rating-change` 的 `bondType` |
+| `interestRateType` | 利率类型 | flat | `bond basic-info` / `bond issuance-plan` 的 `interestRateType` |
+| `interestFrequency` | 付息频率 | flat | `bond basic-info` / `bond issuance-plan` 的 `interestFrequency` |
+| `absUnderlyingAssetType` | ABS 基础资产类型 | flat | `bond basic-info` 的 `absUnderlyingAssetType` |
+| `ratingType` | 评级类型 | flat | `bond rating-*` 的 `ratingType` |
+| `exchange` | 交易市场 | flat | `bond` 各命令的 `exchange` |
 
 > **行业 / 研究方向过滤——选哪套 category（⭐ 权威口径，其他文件引用此处、勿重复枚举命令清单以免漂移；逐端点核对）：**
 >

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

@@ -29,6 +29,41 @@ ZIP 内容：
 
 呈现建议：解压后读 `file.md`；正文很长时先 `wc -l` / `head` 采样，不要整篇灌进上下文。
 
+## 联网搜索 `tool web-search`
+
+对公开互联网做投研定向检索。服务端已做转载去重、信源分级、黑名单剔除与内容特征打标，按信源等级排序返回。
+
+```bash
+# 轻搜：默认 10 条摘要
+gangtise tool web-search --query "<检索词>" [--size N]
+
+# 收窄：定向站点 + 只要高等级信源 + 近一周
+gangtise tool web-search --query "减持新规" --site csrc.gov.cn --site sse.com.cn --min-tier T1 --freshness week
+
+# 精读：返回网页正文
+gangtise tool web-search --query "<标题>" --site csrc.gov.cn --include-content --max-content-chars 6000 --size 2 --format json
+```
+
+- `--query`（**必填**）：1–200 字符。**服务端不做意图推断或改写**，检索词原样发送；要限定站点必须显式用 `--site`
+- `--size`：1–20，默认 10；**带 `--include-content` 时上限降为 5**（CLI 本地拦截并说明是哪个 flag 压低了上限）。指去重与过滤**之后**的条数，不足不补
+- `--freshness`：`day` / `week` / `month` / `none`（默认）。按 `publishTime` 过滤，⚠️ **判不出发布日期（`publishTime` 为 `null`）的结果在 `day`/`week`/`month` 下不返回**——收窄时效会连带丢掉这批
+- `--min-tier`：`T0` / `T1` / `T2` / `T3`（默认 T3 = 不过滤）。低于该等级不返回
+- `--site`：注册域或子域（`csrc.gov.cn`、`finance.sina.com.cn`），可重复，**最多 10 个**（按去重后计），相互之间是**或**关系，子域按后缀匹配
+- `--include-content`：返回网页正文 `content`（Markdown，保留标题/列表/表格，图片只留链接）。个别页面取不到正文时该条 `content` 为 `null`，不报错
+- `--max-content-chars`：1000–20000，默认 8000，仅在 `--include-content` 时生效；超出截断并置 `contentTruncated: true`（按段落边界回退，实际长度可能略小）
+- **积分**：**1 积分/次**，与返回条数、是否带 `--include-content` 无关；**零结果与报错不扣**。标 `no-replay`，超时/5xx 不自动重放
+
+返回字段要点：
+
+- `publishTime`（`yyyy-MM-dd`）是**规则判定**的发布日期，判不出为 `null`——**`null` 不表示网页没有日期**。排序与 `--freshness` 只用它；`publishTimeSource` 说明判定依据（`url` / `cluster` / `page` / `index`），与 `publishTime` 同空同有
+- `indexTime` 是搜索索引记录的网页时间，**原样转述、不保证是发布时间**（政府站常把页面生成时间写进元数据，部分站点是抓取批次日）。做时点判断用 `publishTime`，不要用它
+- `tier` 信源等级 T0–T3；`flags` 内容特征标：`rumor` 传闻 / `forward` 转载稿 / `disclaimer` 含免责声明 / `toutSuspect` 疑似荐股 / `paywall` 付费墙
+- `upgradedFrom` 是转载簇合并时被替换掉的低等级来源 URL，本条是簇内保留的最高等级来源
+- `hints`：`total = 0` 时必非空（给出放宽建议）；有结果时也可能带提示（如「结果全部为 T3 自媒体」）
+- **排序是 `tier` 升序 → `publishTime` 降序 → 相关性**，⚠️ **首条不等于最相关**，接口只保证信源与时效的确定性次序
+
+典型链路：先轻搜 10 条选定目标 → 再用 `--site` 收束到目标站点、带 `--include-content` 搜一次取正文。
+
 ## 常见搭配
 
 ```bash

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

@@ -14,6 +14,32 @@ gangtise vault drive-download --file-id <id> [--output <path>]
 - `--file-type`：`1` 文档（含 PDF/Word/PPT）| `2` 图片 | `3` 音视频 | `4` 公众号文章 | `5` 其他
 - `--space-type`：`1` 我的云盘 | `2` 租户云盘
 
+## AI 云盘管理 `vault drive-*`（目录、上传、增删改）
+
+全部**免费**。🔴 **除 `drive-folder-list` 外都会改动账号数据**；租户云盘（`--space-type 2`）的内容对整个租户可见，往里上传、复制，或在里面删除前先向用户确认。
+
+```bash
+gangtise vault drive-folder-list [--space-type 1|2] [--parent-id <id>]
+gangtise vault drive-upload --file <path> [--space-type 1|2] [--folder-id <id>] [--title <name>]
+gangtise vault drive-create-folder --name <name> [--space-type 1|2] [--parent-id <id>]
+gangtise vault drive-rename --type file|folder --id <id> --name <name>
+gangtise vault drive-move-file --file-id <id>... --target-folder-id <id|root>
+gangtise vault drive-move-folder --folder-id <id> --target-parent-id <id|root>
+gangtise vault drive-copy --file-id <id>... --target-folder-id <id|root>
+gangtise vault drive-delete-file --file-id <id>... --yes
+gangtise vault drive-delete-folder --folder-id <id> --yes
+```
+
+- **ID 从哪来**：文件夹 ID 用 `drive-folder-list` 逐层看（根目录写 `root` 或不传）；文件 ID 在 `drive-folder-list` 的 `fileList` 或 `drive-list` 里。`--space-type` 默认 `1`（我的云盘），**`--parent-id` / `--folder-id` 必须属于该空间**，否则报 `100003`（「parentId 与 spaceType 不一致」）
+- `drive-folder-list` 只返回该文件夹的**直接**子文件夹（`folderList`）与**直接**文件（`fileList`），不递归；返回为 `{folderTotal, folderList, fileTotal, fileList}`，默认 json 输出
+- **同名不报错**：文件与文件夹都允许同名，以 ID 区分。所以**上传 / 新建 / 复制每执行一次就多一份**，这三个命令超时不会自动重发；对同一内容别重复执行
+- `drive-upload`：单个文件 ≤100MB（CLI 本地先拦）；试用账号每天累计上传 ≤500MB（超出 `230008`）。`--title` 不传用本地文件名
+- 名称（`--name` / `--title`）≤200 个字符，按 UTF-16 计——中文算 1、emoji 算 2；超出 `230004`
+- **移动只能在同一空间内**：`drive-move-file` 里跨空间的文件进 `failList`（「空间不一致」）；`drive-move-folder` 移到其他空间、自身或其子文件夹报 `230005`
+- **跨空间用 `drive-copy`**：把文件在「我的云盘 ↔ 租户云盘」之间复制（可批量），源保留不动；`--target-folder-id` 必须在另一空间，`root` 即另一空间的根目录，同空间复制报 `100003`。返回 `successList[]{fileId, newFileId}`。**目前只支持复制文件**，整个文件夹的复制暂未提供
+- 🔴 **删除不可恢复，必须 `--yes`**：`drive-delete-file` 可批量；`drive-delete-folder` **连同其中全部子文件夹与文件一起删除**，删前先 `drive-folder-list --parent-id <id>` 看清里面有什么。拒绝后**不要自行补 `--yes` 重跑**，把要删的名称列给用户确认
+- **批量命令的部分失败**：`drive-delete-file` / `drive-move-file` / `drive-copy` 对单条失败仍返回成功，明细在 `failList`（`fileId` + `failReason`，如「文件不存在」）。CLI 把失败的 ID 写到 stderr、结果标 `partial` 并**退出 3**
+
 ## 录音速记 `vault record-list/download`
 
 ```bash
@@ -87,7 +113,7 @@ gangtise vault stock-pool-stocks [--pool-id <id>]
 
 ### 增删改
 
-🔴 **这五个命令会改动账号数据**，是本 CLI 仅有的写操作；`--pool-id` 一律取自 `stock-pool-list`。
+🔴 **这五个命令会改动账号数据**（与上面的云盘管理命令同属写操作）；`--pool-id` 一律取自 `stock-pool-list`。
 
 ```bash
 gangtise vault stock-pool-create      --name <名称>

package/gangtise-openapi/references/errors.md

@@ -1,7 +1,7 @@
 # 错误码、退出码与常见困境自救
 
 > 主文件 `SKILL.md` 只保留最高频的几个码；这里是全表。
-> **退出码语义**：`0` 完整成功（含合法空结果）／ `3` 有数据但不完整（`partial: true`）／ `1` 硬失败。
+> **退出码语义**：`0` 完整成功（含合法空结果）／ `3` 有数据但不完整（`partial: true`）／ `4` 导出的数据完整，但 `--output` 已被另一次导出替换（见下文「退出码 4」）／ `1` 硬失败。
 > 报错行末尾的 `[trace <id>]` 是 Gangtise 支持定位问题的唯一凭据，**报障时带上它**。
 
 ## 错误码怎么读
@@ -21,7 +21,7 @@
 | `100001` | 缺必填参数——**msg 带字段名**（「缺少必填参数: reportId」） | — | 按 msg 指的字段补上 |
 | `110001` / `110002` | 日期格式错（msg 带字段名）/ 起晚于止。⚠️ **服务端对多种格式做宽松解析**（`2026/07/01`、`20260701`、`07/01/2026` 都能被接受），所以「没报 110001」不等于「格式被按你的意思理解了」 | — | 按参数名：`--*-date` 用 `YYYY-MM-DD`、`--*-time` 用 `YYYY-MM-DD HH:mm:ss`；`ai knowledge-batch` 的 --start-time/--end-time 收时间戳或 datetime，CLI 统一转 13 位毫秒 |
 | `120001` | 证券代码无效——msg 带原因（「非有效A股」）。Fundamental 系与 `quote day-kline`/`realtime`/`minute-kline`/`fund-flow` 都会报；**旧版 `day-kline-hk`/`day-kline-us`/`index-day-kline` 静默返回空** | — | `reference securities-search` 确认代码与后缀（`600519.SH` / `00700.HK`） |
-| `110003` | **超出账号数据权限的时间范围**。范围按账号等级而定、**不是平台常量**；窗口按**账号**配、不按接口配 | — | 把日期移进权限范围内；整个区间都早于下界时缩短窗口无用（`--fiscal-year 2015` 无论怎么缩都报错）；**换接口绕不过去**，要更长历史联系客户经理开通 |
+| `110003` | **超出账号数据权限的时间范围**。范围按账号等级而定、**不是平台常量**；窗口按**账号**配、不按接口配 | — | 把日期移进权限范围内；整个区间都早于下界时缩短窗口无用（`--fiscal-year 2015` 无论怎么缩都报错）；**换接口绕不过去**，要更长历史联系客户经理开通。⚠️ 区间**跨过**下界时，`indicator` 与 `bond` 报这个码，`quote` 日 K 与 `valuation-analysis` 则从下界起返回、不报错——核对首行日期 |
 | `100006` | 查询/下载数量超限（旧码 `430007`）；`fund-flow` 全市场不传日期即此码；**`indicator cross-section` / `time-series` 单次单元格数超 30000** 也是此码（msg 写明限额） | — | 缩短日期范围或调小 `--size`/`--limit`；全市场场景应已自动分片；EDE 按「截面=证券数×指标数、时序=证券数或指标数×日期数」拆批 |
 | `240001` | 财报期未披露或超出查询期（`earnings-review` 提交阶段就报，**不扣积分**） | — | 换更早的 `--period`（`2025q3` → `2025interim`） |
 | `250001` | 不支持的数据源（旧码 `433007`） | — | 检查 `resourceType + sourceId` 组合 |
@@ -31,7 +31,7 @@
 | `0000001008` | Token 服务端失效（他处登录挤掉）——**旧码，token 自愈依赖它** | **强制重新登录并重试一次** | 无 AK/SK 时无法自愈，提示重新登录 |
 | `0000001007` | 请求未携带 Bearer token | — | 检查 `GANGTISE_TOKEN` / AK/SK 是否已 export |
 | `900002` | **请求方法不正确**（msg「请求类型有误」，HTTP 405） | — | `raw call` 时确认该 endpoint 是 GET 还是 POST |
-| `140002` | 终态参数错：AI 异步生成失败，或 `indicator` 的指标必填参数缺失 / 枚举越界 / 表达式语法错 | **不重试**（终态码） | 按 msg 改参数重提；EDE 的参数名与枚举读 `indicator search --format json` 的 `parameterList` |
+| `140002` | 终态失败：AI 异步生成失败；`indicator` 的指标必填参数缺失 / 枚举越界 / 表达式语法错；或其他接口的「业务处理失败」（与入参无关） | **不立即重试**（终态码） | msg 指向参数就按 msg 改参数重提（EDE 的参数名与枚举读 `indicator search --format json` 的 `parameterList`）；「业务处理失败」则稍后再试，持续出现带 trace 报障 |
 | `230003` | 股票池数量已达账号上限（30 个） | — | 先 `vault stock-pool-delete` 删掉不用的池再建 |
 | `230006` | 建 / 改股票池撞池名重复 | — | 先 `vault stock-pool-list` 看现有名称再换一个 |
 | `230007` | 股票池名超过 10 个字符（中文算 1 个） | — | 缩短名称；终端里建的老池可以更长，本接口不行 |
@@ -53,7 +53,7 @@
 | 错误码 | 含义 | 实际行为 |
 |--------|------|---------|
 | `999001` / `999002` | 缺 token / token 无效 | 实际返回旧码 `0000001007` / `0000001008` |
-| `999007` / `999008` / `999009` | 方法/媒体类型/请求体不支持 | 实际返回 `900002` / `999999` / `100003` |
+| `999007` | 请求方法不支持 | 实际返回旧码 `900002`（HTTP 405）。`999008`（Content-Type 不支持，HTTP 415）与 `999009`（请求体无法解析，HTTP 400）按文档返回 |
 | `999003` / `999005` / `999006` | 无接口权限 / 积分不足 / 限流 | 需特定账号状态才会出现 |
 | `999012`–`999016` | 账号禁用/过期、租户失效、无长期 token、IP 不合规 | 需特定账号状态才会出现 |
 | `100002` / `100004` / `100005` | 类型错 / 分页非法 / 枚举非法 | 类型错归 `100003`。**`100005`（枚举非法）与 `100006`（`size` 超 50）在各 list 端点上普遍触发**（`official-account` / `research` / `foreign-report` / 三个 opinion / `summary`）。仍按未传处理的只剩「该端点不支持的字段名」，见上方「不报错的坑」 |
@@ -75,7 +75,7 @@
 
 `partial: true`，保留已取到的部分；stderr 有 warning，`--format json` 才看得见标记，table/csv/jsonl 只有数据行、看不出问题。**拿到 3 就必须告知用户缺了哪段，不能当成功静默继续。**
 
-- 触发场景：翻页 / K 线分片有页失败、服务端返回行数与 `total` 矛盾（提前短页）、`total` 撞服务端上限（`totalCapped`，见 opinion 家族）、`quote` 系带 `--field` 时请求了但服务端没回的列（`missingFields`）。附带定位字段：页失败 `failedPages`；分片失败 `failedShards`、分片撞行数上限 `truncatedShards`（均带日期区间可缩窗补拉）、只有部分分片返回的列 `droppedColumns`（合并结果的列集取自第一个有数据的分片，多出来的列放不下，需要就缩小日期区间单独拉）；缺列 `missingFields`（字段名写错或已下线，按 `references/fields.md` 核对）；多证券逐只请求里撞行数上限的证券 `truncatedSecurities`。EDE 的 `omittedIndicators` / `omittedSecurities` 仍在，但写错的 code 在服务端就被 `100003` 拒了（退出 1），这条路基本收不到样本
+- 触发场景：翻页 / K 线分片有页失败、服务端返回行数与 `total` 矛盾（提前短页）、`total` 撞服务端上限（`totalCapped`：`total` 是封顶值而非真实条数）、`quote` 系带 `--field` 时请求了但服务端没回的列（`missingFields`）。附带定位字段：页失败 `failedPages`；分片失败 `failedShards`、分片撞行数上限 `truncatedShards`（均带日期区间可缩窗补拉）、只有部分分片返回的列 `droppedColumns`（合并结果的列集取自第一个有数据的分片，多出来的列放不下，需要就缩小日期区间单独拉）；缺列 `missingFields`（字段名写错或已下线，按 `references/fields.md` 核对）；多证券逐只请求里撞行数上限的证券 `truncatedSecurities`。EDE 的 `omittedIndicators` / `omittedSecurities` 仍在，但写错的 code 在服务端就被 `100003` 拒了（退出 1），这条路基本收不到样本
 - **EDE 代码写错是退出码 1 + `100003`，msg 里直接点名是哪个 code**（美股后缀用 `.O`/`.N`，不是 `.US`），不用从退出码 3 反推。真的没覆盖是占位单元格（统一 `null`）+ 退出码 0
 - **`screener` 的缺列按表达式的布尔结构判**：把缺列的变量当作「无法求值」，看整个表达式**是否还有一条能成立的分支**——`A && B` 要两边都可求值，`A || B` 只要一边。**一条分支都不剩 → 退出码 1、不输出任何结果**（返回的行以「通过了该条件」的名义呈现，而条件根本无法证明被执行过）；**还有分支可求值，或缺的只是未参与表达式的辅助变量 → `partial` + 退出码 3**。所以 `F1 || F2` 缺 F1 是降级，缺两个则是致命；`F1 && (F2 || F3)` 缺 F1 仍是致命。⚠️ **前提是服务端返回了命中行**——零命中时走「nothing matched」+ **退出码 0**。**空集别急着当成「条件成立但无标的符合」**：指标码写错会直接报 `100003`（退出 1），剩下**三种成因产生逐字相同的输出**——① 真的没有标的满足条件；② **日期没落在报告期末**（报告期类指标此时整批 `null`）；③ **该指标不覆盖这批证券**（拿 A 股专属指标查港美股，如 `mgn_*` 融资融券系列）。②③ 都要靠单查一行确认，不能只改日期
 

package/gangtise-openapi/references/examples.md

@@ -38,8 +38,11 @@
 4. gangtise insight opinion list \
      --keyword AI \
      --start-time "2026-04-08 00:00:00" --end-time "2026-04-15 23:59:59" \
-     --rank-type 2 --format json
-5. 提取 list[].title / chiefName / publishDate，按时间倒序列表
+     --rank-type 2 --size 20 --format json
+5. 提取 list[].title / author.chiefName / author.brokerName / publishTime / brief，按时间倒序列表
+6. 用户要看某几条全文 → 取对应 chiefOpinionId：
+     gangtise insight opinion detail --chief-opinion-id <id1> --chief-opinion-id <id2> --format json
+   （30 积分/条；list 只有 200 字摘要 brief，1 积分/条）
 ```
 
 ## 例 3：AI 内容生成（content 字段直接呈现）
@@ -198,14 +201,15 @@
      gangtise reference concept-search --keyword 机器人 --top 5 --format json
        → list[0].conceptId = 121000130
    注意：concept-id 不在速查表，**绝不猜测**，必须查 concept-search
-3. Pre-flight：认证 OK；两接口都仅返回最新截面，无历史回溯
+3. Pre-flight：认证 OK；两接口都仅返回最新截面，无历史回溯。
+   「龙头股」要用重点个股标识 isKey，它只在 --full 下返回（500 积分/次，默认 50）→ 先告知积分再加
 4. gangtise alternative concept-info --concept-id 121000130 --format json
-     → 单对象 {conceptName, definition, investmentLogic, industrySpace,
-              competitiveLandscape, keyEvents:[{date,content}]}
-   gangtise alternative concept-securities --concept-id 121000130 --format json
-     → 单对象 {securityCount, securityDetail:[{groupName, securityList:[...]}]}
+     → 单对象 {conceptName, definition, investmentLogic, industrySpace, competitiveLandscape}
+   gangtise alternative concept-securities --concept-id 121000130 --full --format json
+     → 单对象 {securityCount, securityDetail:[{groupName, securityList:[{securityCode, securityName, isKey, inclusionReason}]}]}
 5. 呈现：concept-info 各文本字段直接展示（含 null 则跳过）；
-   成分股按 groupName 分组列出，isKey=true 标记为「重点」
+   成分股按 groupName 分组列出，isKey=true 标记为「重点」。
+   没加 --full 时没有 isKey，不要自行判断哪只是龙头
 ```
 
 ## 例 14：板块成分股（sector-search → sector-constituents 两步）
@@ -357,7 +361,7 @@
 5. 超时不要重跑 file-parse（会重复扣费），用 file-parse-check 拿同一个 taskId 的结果
 ```
 
-## 例 20：维护自选股股票池（本 CLI 仅有的写操作）
+## 例 20：维护自选股股票池（会改动账号数据）
 
 **用户**："把今天筛出来的这几只建个池叫「AI算力观察」"
 

package/gangtise-openapi/references/fields.md

@@ -76,12 +76,14 @@
 
 | 字段 | 含义 | 字段 | 含义 |
 |------|------|------|------|
-| `securityCode` | 指数代码 | `securityName` | 指数名称（如 上证指数） |
-| `tradeDate` | 交易日期 | `open` | 开盘价 |
-| `high` | 最高价 | `low` | 最低价 |
-| `close` | 收盘价 | `preClose` | 昨收价 |
-| `change` | 涨跌额 | `pctChange` | 涨跌幅(%) |
-| `volume` | 成交量(股) | `amount` | 成交总额(元) |
+| `securityCode` | 指数代码 | `tradeDate` | 交易日期 |
+| `open` | 开盘价 | `high` | 最高价 |
+| `low` | 最低价 | `close` | 收盘价 |
+| `preClose` | 昨收价 | `change` | 涨跌额 |
+| `pctChange` | 涨跌幅(%) | `volume` | 成交量(股) |
+| `amount` | 成交总额(元) | `adjustFactor` | 复权因子（指数恒为 `null`） |
+
+与 `day-kline` 查指数的返回完全相同，**不含指数名称**；要名称用 `reference securities-search --keyword <指数代码> --category index` 的 `gtsName`。
 
 ---
 
@@ -202,7 +204,7 @@
 
 ### 估值分析 (`fundamental valuation-analysis`)
 
-> ⚠️ `--field` 写错字段名时**只丢值、字段名照回显**，CLI 会因长度不匹配报错退出 1——见本文顶部「字段名写错时，两族接口的表现完全不同」。
+> ⚠️ `--field` 写错字段名时**只丢值、字段名照回显**，CLI 会因长度不匹配报错退出 1——见本文顶部「字段名写错时，两族接口的表现完全不同」。🔴 例外：`--field` 里一个数值列都没有时（只传 `tradeDate`、或只有不存在的名字），接口返回 0 行、不报错。 `tradeDate` 总在第一列返回，不用写进 `--field`（写了 CLI 会自动去掉）。
 
 | 字段 | 含义 | 字段 | 含义 |
 |------|------|------|------|