gangtise-openapi-cli 0.46.0 → 0.47.0

package/README.md

@@ -6,6 +6,8 @@
 
 README 仅列最近 5 个版本摘要：
 
+- **v0.47.0 — 2026-10-17**：① **`insight opinion list` 新增 `--category`（观点类别：业绩点评 / 异动点评 / 调研访谈更新 / 交易台 / 行业分析）与 `--broker-tag`（头部券商 / 新财富团队）**，返回行带 `categoryList` / `brokerTagList`。② **`--llm-tag` 改为 28 项投研业务标签**（强烈推荐、超预期、涨价、龙头等，取值见 `--help`）；⚠️ **存量脚本要改**：业绩点评、头部券商、新财富团队改用 `--category earningsReview` / `--broker-tag topBroker` / `--broker-tag newFortune`，传给 `--llm-tag` 报 `100005`。同一选项传多个值取并集。③ `--with-content` 不支持 `--category` / `--broker-tag`（本地报错、不发请求），其 `--llm-tag` 仍只收旧的四个值；要按新标签筛又要正文，用 `list` + `detail`。④ **`bond daily-quote` / `bond valuation` 首行比起始日晚超过 14 天时 stderr 提示**（上市较晚或数据起点较晚；多只同查只看整批最早的首行，逐只起点按 `securityCode` 核对）。⑤ 文档：股东结构类 EDE 指标（`shr_*`），大股东系列须传 `rank`、户均持股系列须传 `shareType`。
+
 - **v0.46.0 — 2026-10-14**：① **`reference securities-search --category bond`**：按代码或简称搜债券，代码用于 `bond` 命令组。⚠️ **可转债可能出现在任何 `--category` 的结果里**（按简称查股票时常排第一），**只取返回行 `category` 等于所查类别的那一行**；债券代码传给 `fund` 命令会返回空结果、不报错。② **场外基金可按名称搜到**（`--category fund` 同时返回 `.OF` 与场内代码）。③ **计费单价按平台最新价目更新**：一页通等 AI 生成 10/次、业绩点评 / 观点 PK 20/次、热点话题 10/篇、个股看点 1/条、路演四件套 10/条、独立观点列表 1/条、纪要 / 外资研报 / 我的会议下载 30/篇、公告下载 A 股 1 / 港美股 2、`edb-data` 30/指标；额度保护随之调整。④ **数据范围**：`SKILL.md` 按官方权限表逐命令列出正式 / 试用两档，规划查询区间按表来。⑤ **报错口径**：EDE 漏传必填的 `fiscalYear` 报 `100001`；`main-business` / `valuation-analysis` 的 `--field` 写错名字报 `100005`；`screener` 计费按筛选前范围保守估算。完整列表见 CHANGELOG。
 
 - **v0.45.0 — 2026-10-07**：① **`vault drive-copy` 可复制整个文件夹**：`--folder-id` + `--target-parent-id`，连同子文件夹与文件复制到另一空间，返回 `{folderId, newFolderId}`；复制文件的写法不变，两组参数二选一。② **下载文件名**：响应同时给出 UTF-8 文件名与普通文件名时用 UTF-8 的那个。③ `GANGTISE_BASE_URL` 指向非本机地址却用 `http://` 时 stderr 提示一次（凭证会明文传输）。④ 文档：`bond daily-quote` / `bond valuation` 的数据可能比账号窗口短，**按年份取长序列时核对首行日期**；`bond announcement` 按日期查询时有代码的行都带后缀；基金只知道名称时怎么换代码；分钟 K 的可查历史是滚动的短窗口。
@@ -14,10 +16,9 @@ README 仅列最近 5 个版本摘要：
 
 - **v0.43.1 — 2026-09-27**：① **EDE `fiscalYear` 漏传不报错**：预测类（`frcst_*`）与分红类（`div_cash_yr` 等）漏传时按服务端自定的默认年度取数，数看着正常但未必是你要的年度——**一律显式传 `fiscalYear`**；其余必填参数缺失仍报 `100001`。② **翻页去重**：同一 ID 的任一已出现版本再次出现都按重复去掉（计入 `duplicateRows`），不区分字段顺序。③ **观点 `detail`**：某一批夹有空元素或格式异常的元素时，这一批已返回的正文照常输出；空元素的 ID 列在 `missingIds`，其余没取到的列在 `unfetchedIds`（`unfetchedError` 带 traceId）。④ 文档：`finc_roe_avg_avg` 示例补 `reportDate`；债券三个评级命令的计费说明统一。
 
-- **v0.43.0 — 2026-09-26**：① **按条计费列表的额度保护**：省略 `--size` 时先拿到 `total` 估算全量积分（整页超过 50 积分的列表只先取 1 条），超过 1000 积分报错退出 1，加 `--yes` 或传 `--size N` 放行。② **翻页结果的完整性**：跨页重复的行去掉并标 `duplicateRows`；同一 ID 在后面的页内容变了，两版都保留并标 `changedRows`；`total` 正好等于偏移窗口时标 `totalCapped`；都退出 3。热点话题、纪要、A 股 / 港股公告、财报日历查不到内容时按空结果、退出 0（此前退出 3）。③ **`quote` 的 `--field` 在多只证券或全市场时自动补身份列**（日 K 补 `securityCode` / `tradeDate`、分钟 K 补 `securityCode` / `tradeTime`、`realtime` 补 `securityCode`；单只不补），**多只证券只点一列的脚本输出会多出这些列**。④ **多证券日 K 合批**：按行数上限装入尽量多的证券，请求数大幅减少；全市场分片按工作日计（港股 2 个工作日一片），全市场关键字须同时给起止日期。⑤ **首行晚到提示**：行情首行比请求起点晚 14 天以上时 stderr 提示（上市较晚或越过回溯窗口）。⑥ **`ai stock-summary` 与 `fundamental earning-forecast` 超时 / 5xx 不再自动重试**（单次可能扣数千积分）。⑦ 四个枚举参数写错时本地报错；Ctrl-C / `kill` / 终端断开时清理暂存文件，进程以该信号结束（`$?` 为 130 / 143 / 129），脚本循环随之停下。⑧ Agent Skill 主文件精简，细节移到 `references/`。
-
 ### 历史里程碑
 
+- **v0.43.0**：按条计费列表的额度保护（省略 `--size` 时估算超过 1000 积分须 `--yes`）；翻页结果的跨页重复、版本变化与 `total` 封顶检测。
 - **v0.42.0**：数值参数只收十进制写法（`0x10` / `1e3` 这类写法发请求前报错）；接管道时保留退出码 `3` / `4`。
 - **v0.41.0**：新增债券 12 个命令与云盘管理 9 个命令；观点列表改走 v2（列表只含摘要 1 积分/条，正文按 ID 另取）；新增会议线索与联网搜索。
 - **v0.40.0**：自选股股票池可增删改（首批写操作，删池须显式 `--yes`）；`indicator time-series` 自动判定日期轴；Token 缓存绑定签发它的凭证。
@@ -149,7 +150,7 @@ install_skill ~/.hermes/skills               # Hermes
 |------|--------|------|
 | **Auth** | `login` / `status` | 认证登录、状态查询 |
 | **Lookup** | `broker-org list` / `meeting-org list` | 券商/会议机构本地全量枚举表（按名称找 ID 优先 `reference institution-search`；行业/区域/公告分类/题材/申万码用 Reference 接口查） |
-| **Insight** | `opinion list` / `detail` | 内资机构观点（列表只含摘要 1 积分/条；`detail` 按 ID 取正文 30 积分/条；`list --with-content` 列表直接带正文 30 积分/条） |
+| **Insight** | `opinion list` / `detail` | 内资机构观点（列表只含摘要 1 积分/条；`detail` 按 ID 取正文 30 积分/条；`list --with-content` 列表直接带正文 30 积分/条；可按 `--category` 观点类别 / `--llm-tag` 投研标签 / `--broker-tag` 机构标签筛） |
 | | `summary list` / `download` | 纪要（含下载，支持 `--file-type` 选原始/HTML） |
 | | `pamirs-summary list` / `download` | 帕米尔专家纪要（需单独购买专家纪要库；筛选项比 `summary` 少，无 `--source`/`--institution`/`--participant-role`） |
 | | `roadshow list` | 路演 |
@@ -468,6 +469,8 @@ gangtise insight opinion list --keyword AI --size 20
 gangtise insight opinion detail --chief-opinion-id 4047400241800281391 --chief-opinion-id 2581139
 # 想让列表直接带正文（30 积分/条）；注意内资旧版结构：标题与正文在 contentList.title / contentList.content
 gangtise insight opinion list --keyword AI --size 20 --with-content
+# 按观点类别 / 投研业务标签 / 机构标签筛（同一选项传多个值取并集；--with-content 不支持 --category / --broker-tag）
+gangtise insight opinion list --category earningsReview --llm-tag beatExpect --broker-tag topBroker --size 20
 gangtise insight summary list --keyword 算力
 
 # 帕米尔专家纪要（需单独购买专家纪要库；全文搜索 + 时间倒序）

package/dist/src/commands/bond.js

@@ -2,7 +2,8 @@ import { Command, Option } from "commander";
 import { collectList, collectNames, dateArg, maybeArray, parseNumberOption } from "../core/args.js";
 import { maxUnitsOf } from "../core/endpoints.js";
 import { ValidationError } from "../core/errors.js";
-import { emit } from "./shared.js";
+import { emit, noteLateStart } from "./shared.js";
+const BOND_LATE_CAUSE = "The bond may have listed later, or this data starts later than the requested range — the endpoint returns from its first day of data without an error.";
 export const bond = new Command("bond").description("Bond APIs: profiles, issuers, quotes, valuations, cash flows, ratings, announcements");
 function requireBondCodes(codes, max) {
     if (!codes.length)
@@ -31,12 +32,20 @@ addBondRange("exercise-notice", "bond.exercise-notice", "Put/call exercise sched
 bondSecurityOption(bond.command("daily-quote").description("Daily close quotes (exchange + CFETS): dirty/clean price, YTM, duration, convexity"))
     .requiredOption("--start-date <date>", "Trade date range start (yyyy-MM-dd)", dateArg("--start-date"))
     .requiredOption("--end-date <date>", "Trade date range end (yyyy-MM-dd)", dateArg("--end-date"))
-    .action((options) => emit(options, (client) => client.call("bond.daily-quote", { securityList: requireBondCodes(options.security), startDate: options.startDate, endDate: options.endDate, fieldList: maybeArray(options.field) })));
+    .action((options) => emit(options, async (client) => {
+    const data = await client.call("bond.daily-quote", { securityList: requireBondCodes(options.security), startDate: options.startDate, endDate: options.endDate, fieldList: maybeArray(options.field) });
+    noteLateStart(data, options.startDate, "tradeDate", "bond daily-quote", BOND_LATE_CAUSE);
+    return data;
+}));
 bondSecurityOption(bond.command("valuation").description("Shanghai Clearing House valuations: price, yield, duration, convexity, PVBP"))
     .requiredOption("--start-date <date>", "Valuation date range start (yyyy-MM-dd)", dateArg("--start-date"))
     .requiredOption("--end-date <date>", "Valuation date range end (yyyy-MM-dd)", dateArg("--end-date"))
     .addOption(new Option("--confidence-level <level>", "Valuation confidence; defaults to 推荐 server-side, which already filters out 不推荐").choices(["推荐", "不推荐"]))
-    .action((options) => emit(options, (client) => client.call("bond.valuation", { securityList: requireBondCodes(options.security), startDate: options.startDate, endDate: options.endDate, confidenceLevel: options.confidenceLevel, fieldList: maybeArray(options.field) })));
+    .action((options) => emit(options, async (client) => {
+    const data = await client.call("bond.valuation", { securityList: requireBondCodes(options.security), startDate: options.startDate, endDate: options.endDate, confidenceLevel: options.confidenceLevel, fieldList: maybeArray(options.field) });
+    noteLateStart(data, options.startDate, "tradeDate", "bond valuation", BOND_LATE_CAUSE);
+    return data;
+}));
 function issuerSelector(security, issuer) {
     if (security.length && issuer.length)
         throw new ValidationError("--security and --issuer are mutually exclusive: pass bond codes or issuer names, not both");

package/dist/src/commands/insight.js

@@ -25,7 +25,14 @@ const officialAccount = new Command("official-account");
 const qa = new Command("qa");
 const reportImage = new Command("report-image");
 query(opinion, "list", {
-    endpoint: (options) => options.withContent ? "insight.opinion.list-with-content" : "insight.opinion.list",
+    endpoint: (options) => {
+        if (!options.withContent)
+            return "insight.opinion.list";
+        if (options.category.length || options.brokerTag.length) {
+            throw new ValidationError("--category / --broker-tag do not work with --with-content: its v1 list ignores them and would return unfiltered rows at 30 credits/row. Filter with 'opinion list', then fetch bodies with 'opinion detail'");
+        }
+        return "insight.opinion.list-with-content";
+    },
     fields: [
         rankType(),
         list("--research-area <id>", RESEARCH_AREA_CITIC_OR_DIRECTION, "researchAreaList"),
@@ -34,9 +41,11 @@ query(opinion, "list", {
         list("--broker <id>", "Broker ID", "brokerList"),
         list("--industry <id>", "Industry ID", "industryList"),
         list("--concept <id>", "Concept ID", "conceptList"),
-        list("--llm-tag <tag>", "Semantic tag", "llmTagList"),
+        list("--category <name>", "Opinion category: earningsReview/abnormalReview/researchUpdate/tradingDesk/industryAnalysis", "categoryList"),
+        list("--llm-tag <tag>", "Research tag, several = any of them. Recommendation: strongRcmd/undervalued/highElasticity/highDividend/reversal/bottom/beatExpect/expectGap/oversold/targetPrice/certainty; earnings: highGrowth/withProfitForecast/withGuidance/marginalImprovement; supply chain: priceHike/tightSupplyDemand/capacityRelease/newOrder/orderSurge/keyCustomer/soleSupplier/coreSupplier/industryEntry; moat: leader/moat/scarcity/breakthrough", "llmTagList"),
+        list("--broker-tag <tag>", "Broker tag: topBroker/newFortune", "brokerTagList"),
         list("--source <source>", "Source", "sourceList"),
-        flag("--with-content", "Return the full body inline (v1 list, 30 credits/row) instead of the 200-char brief (1 credit/row). v1 shape: title and body sit under contentList.title / contentList.content, and there is no brief"),
+        flag("--with-content", "Return the full body inline (v1 list, 30 credits/row) instead of the 200-char brief (1 credit/row). v1 shape: title and body sit under contentList.title / contentList.content, and there is no brief. Takes no --category / --broker-tag, and --llm-tag only strongRcmd/earningsReview/topBroker/newFortune"),
         format(), output("Output path"),
         ...timeFilters(),
     ],

package/dist/src/commands/shared.js

@@ -72,7 +72,7 @@ export function earliestRowDate(data, field) {
     }
     return earliest;
 }
-export function noteLateStart(data, requestedStart, field, label) {
+export function noteLateStart(data, requestedStart, field, label, cause = "The security may have listed or resumed trading later, or the range reaches past your account's history window for this data — the endpoint returns what lies inside the window without an error.") {
     const failedShards = data?.failedShards;
     if (Array.isArray(failedShards) && failedShards.length > 0)
         return;
@@ -85,7 +85,7 @@ export function noteLateStart(data, requestedStart, field, label) {
     const lateDays = (Date.parse(`${first}T00:00:00Z`) - Date.parse(`${start}T00:00:00Z`)) / 86_400_000;
     if (lateDays <= LATE_START_DAYS)
         return;
-    process.stderr.write(`[gangtise] note: ${label} starts at ${first}, ${lateDays} days after the requested start ${start}. The security may have listed or resumed trading later, or the range reaches past your account's history window for this data — the endpoint returns what lies inside the window without an error.\n`);
+    process.stderr.write(`[gangtise] note: ${label} starts at ${first}, ${lateDays} days after the requested start ${start}. ${cause}\n`);
 }
 export async function runDownload(client, endpointKey, query, options) {
     if (options.output) {

package/gangtise-openapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gangtise-openapi
-version: "0.46.0"
+version: "0.47.0"
 description: |-
   通过 gangtise CLI 直接调用 Gangtise OpenAPI，拉取投研原始数据、批量导出、下载文件、调用 AI 能力。
 
@@ -196,7 +196,7 @@ vault.stock-pool.create
 | `vault my-conference-list` / `my-conference-download` | **1 个月** | 1 个月 |
 | `vault` 其余（速记 / 群消息 / 股票池 / 云盘） | **不限** | 不限 |
 
-⚠️ **实际窗口按账号配**，换接口绕不过去（`indicator` 与 `quote day-kline` 同界）。整段在界外返回 `110003`（不是空结果），把日期移进范围或联系客户经理。🔴 **区间跨过下界时各接口不同**：`quote` 日 K / 分钟 K / 资金流向与 `fundamental valuation-analysis` 从下界起返回、**不报错**（首行明显晚于起始日时 CLI 在 stderr 提示）；`indicator`、`bond` 与 `fund` 整批报 `110003`；`bond daily-quote` / `bond valuation` 的数据还可能比账号窗口短——区间早于数据起点时返回 `130001`，跨过数据起点时从有数据的那天起返回、不报错，核对首行日期。**例外**：`quote minute-kline` 窗口只有 1 个月且随日期滚动，整段在窗外返回空结果、不报错（CLI 在 stderr 提示）；`ai hot-topic` 超出账号可查范围时也返回空结果、不报错。
+⚠️ **实际窗口按账号配**，换接口绕不过去（`indicator` 与 `quote day-kline` 同界）。整段在界外返回 `110003`（不是空结果），把日期移进范围或联系客户经理。🔴 **区间跨过下界时各接口不同**：`quote` 日 K / 分钟 K / 资金流向与 `fundamental valuation-analysis` 从下界起返回、**不报错**（首行明显晚于起始日时 CLI 在 stderr 提示）；`indicator`、`bond` 与 `fund` 整批报 `110003`；`bond daily-quote` / `bond valuation` 的数据还可能比账号窗口短——区间早于数据起点时返回 `130001`，跨过数据起点时从有数据的那天起返回、不报错（首行明显晚于起始日时 CLI 在 stderr 提示），核对首行日期。上面两处 stderr 提示都只看整批最早的首行：多只同查时有一只够早就不提示，逐只的起点按 `securityCode` 核对。**例外**：`quote minute-kline` 窗口只有 1 个月且随日期滚动，整段在窗外返回空结果、不报错（CLI 在 stderr 提示）；`ai hot-topic` 超出账号可查范围时也返回空结果、不报错。
 
 ### 下载规则（`--file-type` / `--content-type`）
 
@@ -224,7 +224,7 @@ vault.stock-pool.create
 |---------|------|
 | 研报 / 券商报告 | `insight research list` |
 | 外资研报 | `insight foreign-report list` |
-| 首席观点 / 内资机构观点 / 分析师观点 | `insight opinion list`（只含摘要 `brief`，1/条）；要正文 → `insight opinion detail --chief-opinion-id`（30/条） |
+| 首席观点 / 内资机构观点 / 分析师观点 | `insight opinion list`（只含摘要 `brief`，1/条）；要正文 → `insight opinion detail --chief-opinion-id`（30/条）。按观点类别（业绩点评 / 异动点评…）、投研标签（强烈推荐 / 超预期 / 涨价 / 龙头…）、机构标签（头部券商 / 新财富）筛 → `--category` / `--llm-tag` / `--broker-tag`，取值见 `insight.md` |
 | 外资机构观点 / 外资券商观点 | `insight foreign-opinion list`（摘要 + 中文摘要）；要原文与译文 → `insight foreign-opinion detail --foreign-opinion-id`（30/条） |
 | 外资独立观点 / 独立分析师观点 | `insight independent-opinion list` |
 | 纪要 / 会议纪要（外部） | `insight summary list` |
@@ -326,7 +326,7 @@ vault.stock-pool.create
   - 日期参数**只看 `parameterList` 必填哪个**：`tradeDate` → `--date`，`reportDate` → `--indicator-param "code:reportDate=..."`（多数报告期类要后者，但 `_ttm` 整族要 `tradeDate`）；两个都必填（如 `div_cash_yld`）就两个都用 `--indicator-param` 显式给，只给 `reportDate` 时 `--date` 不再注入、会报 `100001`。`parameterList` 要 `fiscalYear` 的（预测类 `frcst_*`、分红类 `div_cash_yr` 等）显式给，漏传报 `100001` 并点名。日频估值（`finc_pe_ttm` / `finc_pb_mrq`）用最新交易日，用报告期末日期会取到陈值；参数名同样以 `parameterList` 为准（复权是 `adjustType`）
   - 结果**按 `security` 字段取值**，别按请求下标对位（证券的返回顺序不作保证）；批量回填加 `--key-by code`
   - 估值历史：EDE 与 `valuation-analysis` 的财报口径切换时点与财报版本都不同，做分位 / 回测两边都拉交叉核
-- "业绩点评"双义消歧：**检索已有**的业绩点评：研报走 `insight research list --llm-tag earningsReview`（0.1/条；`--llm-tag` 只有 `opinion` / `research` / `foreign-report` 三个列表有），业绩会纪要走 `insight summary list --category earningsCall`；**AI 现生成**一份走 `ai earnings-review`（异步、20/次）。不确定问一句
+- "业绩点评"双义消歧：**检索已有**的业绩点评：研报走 `insight research list --llm-tag earningsReview`（0.1/条；`--llm-tag` 只有 `opinion` / `research` / `foreign-report` 三个列表有），首席观点走 `insight opinion list --category earningsReview`（1/条；观点的「业绩点评」是类别，不是 `--llm-tag`），业绩会纪要走 `insight summary list --category earningsCall`；**AI 现生成**一份走 `ai earnings-review`（异步、20/次）。不确定问一句
 
 ## 公司名 → 证券代码
 

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

@@ -18,7 +18,7 @@
 
 ⚠️ **`--start-date` 早于可回溯下界时整批返回 `110003`「超出时间范围限制」**（这三个命令都是）——即使 `--end-date` 在窗口内，也不会只返回窗口内那一段。把 `--start-date` 移进窗口再查；实际下界随账号服务等级而定，以返回为准。
 
-⚠️ **`bond daily-quote` / `bond valuation` 的数据可能比账号窗口短**：区间在窗口内、但早于数据起点时整段返回 `130001`「数据未找到」；跨过数据起点时从有数据的那天起返回、不报错。按年份取长序列时核对返回的首行日期。
+⚠️ **`bond daily-quote` / `bond valuation` 的数据可能比账号窗口短**：区间在窗口内、但早于数据起点时整段返回 `130001`「数据未找到」；跨过数据起点时从有数据的那天起返回、不报错（首行比 `--start-date` 晚超过 14 天时 CLI 在 stderr 提示，退出码仍为 0）。按年份取长序列时按 `securityCode` 逐只核对首行日期——CLI 的提示只看整批最早的首行，多只同查时有一只数据够早就不会提示。
 
 ## `basic-info` 债券基本资料
 

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

@@ -9,7 +9,7 @@
 
 | 请求形态 | 优先接口 |
 | :--- | :--- |
-| 单证券的财务 / 股东 / 主营，或 A股单证券估值 | 对应 `fundamental` 专用命令；多数免费，且字段口径固定 |
+| 单证券的财务 / 股东 / 主营，或 A股单证券估值 | 对应 `fundamental` 专用命令；多数免费，且字段口径固定。多证券批量取股东户数 / 户均持股 / 前十大与第 N 大股东走 EDE，见下方「股东结构指标」 |
 | 多证券批量取一组**已实现**财务 / 估值指标 | 先 `indicator search`，通过下方三项校验后用 `cross-section` / `time-series` 一次拉取，避免逐只循环 |
 | A股盈利预测 / 一致预期（含预测 EPS） | `fundamental earning-forecast`；EDE 搜到的基本 / 稀释 EPS 是已实现值，不能替代预测 |
 | A股估值历史分位 | `fundamental valuation-analysis` |
@@ -370,6 +370,31 @@ gangtise indicator cross-section --indicator scr_indu_citic --indicator scr_indu
 
 **`finc_pb_mrq`（市净率 MRQ）是日频指标**：每个交易日都有数且逐日变动，别按报告期末取（那会拿到几个月前的陈值）。
 
+### 股东结构指标（`shr_*`）
+
+`scopeList` 只有 **A 股**。两种日期口径，按 `parameterList` 区分：
+
+| 维度 | 按交易日（`tradeDate`，取截至该日最新披露的值） | 按报告期（`reportDate`） |
+| :--- | :--- | :--- |
+| 股东户数 | `shr_hld` 股东户数、`shr_hld_tot` 股东总户数、`shr_hld_g_rti` / `shr_hld_tot_g_rti` 区间增长率（另需 `sDate`）、`shr_hld_chg_dt` 最新变更日期、`shr_hld_dcl_dt` 最新披露日期 | `shr_hld_rp`、`shr_hld_tot_rp` |
+| 户均持股 | `shr_avg_qty` 数量、`shr_avg_pct` 比例、`shr_avg_qty_g_rti` / `shr_avg_pct_g_rti` 区间增长率（另需 `sDate`） | `shr_avg_qty_rp`、`shr_avg_pct_rp`；半年 / 季度增长率 `shr_avg_qty_hyrg_rp` / `shr_avg_qty_qtrg_rp` / `shr_avg_pct_hyrg_rp` / `shr_avg_pct_qtrg_rp`；`shr_avg_pct_chg_rp` 较上一报告期变化 |
+| 前十大股东 | — | `shr_top10_hld_name` 名称、`shr_top10_hld_pct` 持股比例合计、`shr_top10_hld_qty` 持股数量合计 |
+| 大股东（前十大里指定排名的一位） | — | `shr_top_hld_name` 名称、`shr_top_hld_pct` 持股比例、`shr_top_hld_qty` 持股数量、`shr_top_hld_cat` 类型、`shr_top_hld_typ` 性质、`shr_top_hld_ntr` 持股股本性质 |
+
+- 🔴 **两个必填参数要显式传**，漏传报 `100001`：大股东系列的 `rank`（前十大股东里的排名，`1` = 第一大股东）；户均持股系列的 `shareType`（`1` 流通股 / `2` 总股本）——`parameterList` 给 `shareType` 列了默认值 `1`，但仍须显式传
+- 单只证券要前十大股东逐个明细，用 `fundamental top-holders`（免费）；EDE 适合多证券批量取汇总值或第 N 大股东
+
+```bash
+gangtise indicator cross-section --indicator shr_top_hld_name --indicator shr_top_hld_pct \
+  --indicator-param "shr_top_hld_name:reportDate=2025-12-31" --indicator-param "shr_top_hld_name:rank=1" \
+  --indicator-param "shr_top_hld_pct:reportDate=2025-12-31" --indicator-param "shr_top_hld_pct:rank=1" \
+  --security 600519.SH --security 000001.SZ --date 2025-12-31
+# 茅台 2025 年报第一大股东「中国贵州茅台酒厂(集团)有限责任公司」54.4038%
+
+gangtise indicator cross-section --indicator shr_hld --indicator shr_avg_qty \
+  --indicator-param "shr_avg_qty:shareType=2" --security 600519.SH --date 2026-10-15
+```
+
 ## 取数最佳实践
 
 - **先 search 做三项校验**：看 `indicatorName` + `description` 确认语义和口径，看 `scopeList` 确认覆盖全部目标市场 / 证券类型（并看 `usageRestriction` 有无接口限制），再看 `parameterList` 补齐必填参数（required）并核对专属参数**名称**与枚举（`adjustType`/`scale`/`currency` 等）；任一不符就回退专用接口。**参数名一律以 search 返回的 `parameterList` 为准，不要照抄任何示例里的参数名**——参数名会随版本调整，写错会报 `100003` 并指出是哪个指标的哪个参数，按报错改即可。

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`
 

package/gangtise-openapi/references/errors.md

@@ -41,7 +41,7 @@
 - **日期用「年在前」写法**：`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`，而是照常受理、扣 20 积分、生成阶段才以 `410111` 失败；同样的内容重提仍会失败。**提交前自己把关措辞**
 

package/gangtise-openapi/references/examples.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 \

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） | — |

package/package.json

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