gangtise-openapi-cli 0.40.0 → 0.41.0

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

@@ -2,7 +2,9 @@
 
 通用：所有命令都需 `--security-code`（如 `600519.SH`，注意是 `--security-code` 不是 `--security`）。`--field` 可重复，可用字段见 `references/fields.md`；A / 港 / 美股三大报表命令都在省略 `--field` 时返回完整报表，指定后只保留基础字段与所选科目。
 
-**`--field` 字段名必须核对**：三大报表遇到不存在的字段名会补 `null`（安全），但 `main-business` / `valuation-analysis` 是**只丢值、字段名照请求回显**，按位置拍平会把值贴到错误的字段上（同 `quote realtime`，详见 `references/commands/quote.md`）。CLI 长度不匹配就直接失败（退出码 1），不输出错位数据。不确定字段名就别传 `--field`。
+**`--field` 字段名必须核对**：三大报表遇到不存在的字段名会补 `null`（安全），但 `main-business` / `valuation-analysis` 是**只丢值、字段名照请求回显**，`fieldList` 比行长，按位置拍平会把值贴到错误的字段上。CLI 长度不匹配就直接失败（退出码 1），不输出错位数据。不确定字段名就别传 `--field`。
+
+⚠️ **别把这个行为套到 `quote` 系上**——那边是**字段名和值一起消失**、列数与值数始终对得上，CLI 的处理也不同（标 `partial` + `missingFields`、退出码 3）。两族的完整对照见 `references/fields.md` 顶部。
 
 ---
 

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/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

@@ -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

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

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

@@ -20,7 +20,9 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 
 | 命令 | data 结构 | 关键提取字段 |
 |------|----------|------------|
-| insight opinion list | `{list, total}` | `list[].id` / `list[].title` / `list[].publishDate` / `list[].chiefName` / `list[].securityCode` / `list[].institutionName` |
+| 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 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） | — |
 | insight pamirs-summary list | `{list, total}` | `list[].summaryId` / `list[].title` / `list[].brief` / `list[].summaryTime`（纪要生成时间）/ `list[].publishTime`（发布时间）/ `list[].securityList[]{securityCode, securityName}` / `list[].researchAreaList[]{researchAreaId, researchAreaName}` / `list[].conceptList[]{conceptId, conceptName}` / `list[].categoryList` / `list[].marketList`。⚠️ `conceptList` / `categoryList` / `marketList` 三个标签字段**稀疏，且是否有值随记录和查法而变**：不带筛选时经常整条为空，用 `--category` 或 `--market` 任一过滤时回填率明显更高（这两个字段绑定，一起有或一起没有）。所以**别拉全量再本地分组**（会漏记录），也**别据此断言某条记录没有该属性**（为空只说明这次没回填）。详见 `commands/insight.md` |
@@ -36,7 +38,8 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | insight announcement-hk download | 文件路径（stdout） | — |
 | insight announcement-us list | `{list, total}` | `list[].announcementId` / `list[].title` / `list[].publishTime` / `list[].securityList[].securityCode` / `list[].primaryCategory.categoryName` / `list[].sourceName` |
 | insight announcement-us download | 文件路径（stdout） | — |
-| insight foreign-opinion list | `{list, total}` | `list[].foreignOpinionId` / `list[].titleTranslate` / `list[].publishTime` / `list[].publisher.brokerName` / `list[].securityList[].rating` |
+| insight foreign-opinion list | `{list, total}` | `list[].foreignOpinionId`（`detail` 用）/ `list[].title` / `list[].titleTranslate` / `list[].brief` / `list[].briefTranslate` / `list[].publishTime` / `list[].region{regionCode, regionName}` / `list[].publisher{brokerId, brokerName}` / `list[].securityList[]{securityCode, securityName, rating, ratingChange, targetPrice, currency}` / `list[].industryList[]{industryId, industryName, rating, ratingChange}`；`--with-content` 另有顶层 `content` / `contentTranslate`、无 `brief` |
+| insight foreign-opinion detail | 同 opinion detail | `list[]` 同 list 的字段 + `content`（原文）/ `contentTranslate`（中文译文） |
 | insight independent-opinion list | `{list, total}` | `list[].independentOpinionId` / `list[].titleTranslate` / `list[].briefTranslate` / `list[].publishTime` / `list[].analyst.analystName` |
 | insight independent-opinion download | 文件路径（stdout） | — |
 | insight official-account list | `{list, total}` | `list[].articleId` / `list[].accountName` / `list[].title` / `list[].publishTime` / `list[].articleCategory` / `list[].summary` / `list[].industryList[].industryName` / `list[].conceptList[].conceptName` / `list[].securityList[].securityCode` |
@@ -44,7 +47,9 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | insight qa list | `{list, total}` | `list[].source`（conference/interactive/survey）/ `list[].publishTime` / `list[].question` / `list[].answer` / `list[].member` / `list[].securityCode` / `list[].questionCategory[]` / `list[].answerImportant`（1/0） |
 | insight performance-calendar list | `{list, total}` | `list[].performanceReportId`（下载用）/ `list[].securityCodeList[]`（A+H 可能多个）/ `list[].securityName` / `list[].category`（performanceForecast/performanceExpress/performanceAnnouncement）/ `list[].publishDate`（带 ` 00:00:00` 后缀）/ `list[].title` / `list[].hasAttachment`（`false` 则无法下载） |
 | insight performance-calendar download | 文件路径（stdout，PDF） | — |
+| insight highlight list | `{list, total}` | `list[].highlightId` / `list[].title`（会议名称）/ `list[].publishTime` / `list[].content`（**HTML 片段**：`<p>` 包裹、小标题 `<strong>`）/ `list[].securityList[]{securityCode, securityName}` / `list[].researchAreaList[]{researchAreaId, researchAreaName}` |
 | tool file-parse | `{taskId, status:"pending", hint}`（提交）；`--wait` 或 `file-parse-check` 就绪后 = 文件路径（stdout，ZIP） | ZIP 内 `file.md` + `images/`；未就绪时 check 输出 `{taskId, status:"pending"}`（退出码 0） |
+| tool web-search | `{query, total, hints, list}` | `list[].title` / `list[].url` / `list[].site` / `list[].snippet` / `list[].content`（仅 `--include-content`，否则 `null`）/ `list[].contentTruncated` / `list[].publishTime`（判不出时 `null`）/ `list[].publishTimeSource` / `list[].indexTime`（索引时间，不等于发布时间）/ `list[].tier`（T0–T3）/ `list[].flags[]` / `list[].upgradedFrom[]`；`total = 0` 时看 `hints` |
 | insight report-image list | `[{...}]`（扁平数组，无 `total`） | `[].chunkId`（下载用 `--chunk-id`）/ `[].title` / `[].sourceId` / `[].broker` / `[].category` / `[].page` / `[].totalPages` / `[].imageCaption[]` / `[].imageFootnote[]` / `[].pageContent`（该页 OCR/描述） |
 | insight report-image download | 文件路径（stdout，JPEG） | — |
 | reference securities-search | `{returnedCount, list}` | `list[].gtsCode` / `list[].gtsName` / `list[].category` / `list[].matchScore` / `list[].matchType` |
@@ -76,6 +81,13 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | ai viewpoint-debate | 同 earnings-review | — |
 | vault drive-list | `{list, total}` | `list[].fileId`（下载用 `--file-id`）/ `list[].title` / `list[].fileType` / `list[].uploadTime` |
 | vault drive-download | 文件路径（stdout） | — |
+| vault drive-folder-list | `{folderTotal, folderList, fileTotal, fileList}` | `folderList[]{folderId, parentId, folderName, spaceType, createTime}` / `fileList[]{fileId, title, fileSize, createTime}`；只含直接下级 |
+| vault drive-upload | `{fileId, title, folderId, spaceType, fileSize}` | `fileId`（后续重命名 / 移动 / 删除用） |
+| vault drive-create-folder | `{folderId, parentId, folderName, spaceType, createTime}` | `folderId` |
+| vault drive-rename | `{id, name}` | — |
+| vault drive-move-folder / drive-delete-folder | `{folderId, parentId}` / `{folderId}` | — |
+| vault drive-copy | `{successList, failList}` | `successList[]{fileId, newFileId}`（`newFileId` 是另一空间里副本的 ID）；`failList[]{fileId, failReason}`，非空时 `partial` + 退出码 3 |
+| vault drive-move-file / drive-delete-file | `{successList, failList}` | `successList[]` 为文件 ID；`failList[]{fileId, failReason}`，非空时 `partial` + 退出码 3 |
 | vault record-list | `{list, total}` | `list[].recordId` / `list[].title` / `list[].category` / `list[].createTime` / `list[].recordDuration` |
 | vault record-download | 文件路径（stdout） | — |
 | vault my-conference-list | `{list, total}` | `list[].conferenceId` / `list[].title` / `list[].category` / `list[].institution.institutionName` / `list[].publishTime` |
@@ -89,8 +101,10 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | vault stock-pool-delete | `{successList, failList}` | 同上，但键是 `failList[].poolId`；删不存在的池算幂等成功，计入 `successList` |
 | alternative edb-search | `{list: [...]}` 指标列表 | `indicatorId` / `indicatorName` / `dataSource` / `frequency` / `unit` |
 | alternative edb-data | 列表，每行 `{date, <indicatorId>: value, ...}` 宽表 | `date` + 每个 `--indicator-id` 一列（该日指标值） |
-| alternative concept-info | `{conceptId, conceptName, ...}`（单对象，**非列表**） | `conceptName` / `definition` / `investmentLogic` / `industrySpace` / `competitiveLandscape` / `keyEvents[].date` / `keyEvents[].content`；文本字段未配置为 `null` |
-| alternative concept-securities | `{conceptId, conceptName, securityCount, securityDetail}`（单对象，分组） | `securityCount` / `securityDetail[].groupName` / `securityDetail[].securityList[].securityCode` / `.securityName` / `.isKey` / `.inclusionReason`；无成分股时 `securityDetail` 为 `null` |
+| alternative concept-info | `{conceptId, conceptName, ...}`（单对象，**非列表**） | `conceptName` / `definition` / `investmentLogic` / `industrySpace` / `competitiveLandscape`；**`keyEvents[].date` / `keyEvents[].content` 仅 `--full`**；文本字段未配置为 `null` |
+| alternative concept-securities | `{conceptId, conceptName, securityCount, securityDetail}`（单对象，分组） | `securityCount` / `securityDetail[].groupName` / `securityDetail[].securityList[].securityCode` / `.securityName` / `.isKey` / `.inclusionReason`（**这两列仅 `--full`**）；无成分股时 `securityDetail` 为 `null` |
+| bond basic-info / issuer-info / daily-quote / valuation / cash-flow / issuance-detail / rating-overview / rating-change / issuer-rating-change / issuance-plan / exercise-notice | 列式 `{fieldList, list, total}` → 规范化后 `{list: [{...}], total}` | 字段名按 `--field` 或全部；每条命令的默认列恒在最前（如 `securityCode` + `tradeDate`、`issuerName`、`issueDate`），见 `commands/bond.md` |
+| bond announcement | 列式 `{fieldList, list}`（**无 `total`**）→ 规范化后为行数组 | `announcementDate` / `securityCode` + 其余字段；翻过末页为 `[]` |
 | indicator search | `[{indicatorCode, indicatorName, ...}]`（列表） | `indicatorCode` / `indicatorName` / `description` / `scopeList[].market` / `scopeList[].securityType` / `scopeList[].usageRestriction`（接口限制，`null`=无限制） / `parameterList[].paramKey`（**参数名以此为准**） / `.enumList[].value` / `score` |
 | indicator cross-section | CLI 拍平为宽表 `{list, total}` | `list[].security` / `list[].name` + 每个指标名一列；**单日多指标 × 多证券**，每行一只证券。**没有 `date` 列**（查询日期挂在每个指标的参数上，各列可为不同日期）；原始响应的 `values` 为 `[证券][指标]` |
 | indicator time-series | CLI 拍平为宽表 `{list, total}` | `list[].date` + 序列列：单证券时列=各指标、多证券时列=各证券；每行一个日期。原始响应 `values` 仍为 `[序列][日期]` |

package/package.json

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