gangtise-openapi-cli 0.48.0 → 0.49.0

package/README.md

@@ -6,6 +6,8 @@
 
 README 仅列最近 5 个版本摘要：
 
+- **v0.49.0 — 2026-10-28**：① **新增 `gangtise update`**：一条命令更新到最新版（从 npmjs.org `npm install -g`），并替换 `~/.claude` / `~/.codex` / `~/.openclaw/workspace` / `~/.hermes` 下版本较旧的 Agent Skill 副本；`--check` 只查不装，`--no-skill` 不动 skill 副本。② **新版本提示**：在终端里运行任何命令时，若已有新版本，结束后 stderr 提示一行（同一新版本约一天一次）；版本信息在后台刷新、命令不等网络，脚本 / Agent / CI 中不提示，`GANGTISE_NO_UPDATE_CHECK=1` 关闭。③ **管理层情绪的 `publishTime` 现为北京时间**，与 `--start-time` / `--end-time` 同一口径；按 v0.48.0 说明「先加 8 小时」处理过的脚本要去掉这一步。④ **路演 / 调研 / 策略会 / 论坛列表的翻页去重改按各自的 ID**（`roadshowId` / `siteVisitId` / `strategyMeetingId` / `forumId`）：跨页重复的行会被去掉、结果标为不完整（退出码 3），提示缩短时间范围重拉；`response-schema.md` 同步更正这四个列表的字段名。⑤ **公募基金**：`fund holder-structure` 的 `holderCount` 现为整数，按 v0.44.0 说明「先去千分位逗号再转数字」的处理要去掉（对整数做字符串替换会报错）；`fund etf-pcf-components` 的接口只返回成分名称，CLI 按名称匹配补上 `componentCode`（带市场后缀，如 `600519.SH` / `00941.HK`；用该行收盘价核对，A+H 同名两行分别匹配；现金行等匹配不到的为 `null`，stderr 列出），`--no-component-code` 关闭。⑥ `ai security-clue` 的 `--query-mode` / `--gts-code` 补充帮助说明。
+
 - **v0.48.0 — 2026-10-24**：① **新增管理层情绪三个命令**：`ai management-sentiment-indicator`（每场业绩会的正面回应程度 / 回复乐观度 / 回复确定度评分与按问题类型拆分）、`ai management-sentiment-conclusion`（情绪结论与较上一场的问答对照），各 5 积分/条、自动翻页；`ai management-sentiment-detail` 按列表返回的 `source.sourceId` 取逐条问答评分与依据，10 积分/次。⚠️ 返回的 `publishTime` 比北京时间早 8 小时（时间筛选按北京时间），按时刻展示或按日期归档前先加 8 小时。② **新增 `bond default-list` 违约债券**（0.4 积分/次）：按违约日期区间（不超过 1 年）/ `--security` / `--issuer` 三选一；`--issuer` 一次一个、用发行人全称，简称只返回最匹配的一家主体，核对 `issuerName`。③ 文档：EDE 基金指标（分类、复权净值、区间收益与风险指标、同类排名），区间指标的参数须显式传。④ 依赖 `undici` 升级到 7.30.1（含上游安全修复）。
 
 - **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`。
@@ -14,10 +16,9 @@ README 仅列最近 5 个版本摘要：
 
 - **v0.45.0 — 2026-10-07**：① **`vault drive-copy` 可复制整个文件夹**：`--folder-id` + `--target-parent-id`，连同子文件夹与文件复制到另一空间，返回 `{folderId, newFolderId}`；复制文件的写法不变，两组参数二选一。② **下载文件名**：响应同时给出 UTF-8 文件名与普通文件名时用 UTF-8 的那个。③ `GANGTISE_BASE_URL` 指向非本机地址却用 `http://` 时 stderr 提示一次（凭证会明文传输）。④ 文档：`bond daily-quote` / `bond valuation` 的数据可能比账号窗口短，**按年份取长序列时核对首行日期**；`bond announcement` 按日期查询时有代码的行都带后缀；基金只知道名称时怎么换代码；分钟 K 的可查历史是滚动的短窗口。
 
-- **v0.44.0 — 2026-09-30**：**新增 `fund` 公募基金 18 个命令，一律 0.4 积分/次**（按次，与返回行数、基金只数无关）：`basic-info` / `nav`（日频净值）/ `fee-rate` / `manager-info`（按姓名精确匹配，同名全返回）/ `manager-history` / `asset-size` / `holder-structure` / `top10-holders` / `asset-allocation` / `stock-portfolio` / `industry-allocation` / `bond-portfolio` / `bond-type-allocation` / `fund-portfolio` / `fund-type-allocation` / `etf-pcf-header` / `etf-pcf-components` / `etf-share-change`。`--security` 用带大写后缀的基金代码（场外 `.OF`，场内 `.SH` / `.SZ`），**代码不存在、不带后缀或后缀小写都返回空结果、不报错**。不分页：单次上限 10000 行，超出整批报 `100006`；日期两端都不传取账号可回溯窗口内的全部，起点早于窗口整批报 `110003`。**整族超时 / 5xx 不自动重发**（避免重复扣费）。取数前注意：各命令单位不同（元 / 万元 / 万份 / 万股）；`holder-structure` 的 `holderCount` 是带千分位的字符串；持仓明细只返回证券简称、不返回代码；`fund-type-allocation` 季报期只含重仓基金。逐条见 `gangtise-openapi/references/commands/fund.md`。**另有几处行为变化**：只收一个值的参数重复传直接报错；代码类列表也按顿号 / 分号 / 空格分隔并去重；显式 `--size` 与 `fundamental earning-forecast` 的日期区间估算超过 1000 积分同样要 `--yes`；jsonl / csv 文件一律以换行结尾，csv 不再给 `-3.5%` 这类值加 `'`；全市场分片早于账号窗口的部分跳过而不中止；接口返回下载链接时不带 `--output` 也会下载；A 股公告与 `ai knowledge-batch` 只写日期的 `--end-time` 按当日 23:59:59 换算；`--indicator-param` 里的日期值与 `--date` 同样校验；单次请求另有总时长上限（`GANGTISE_TIMEOUT_MS` 的 2 倍，下载与上传 60 倍）；环境变量设成空字符串按未设置处理。完整列表见 CHANGELOG。
-
 ### 历史里程碑
 
+- **v0.44.0**：新增公募基金 `fund` 命令组 18 个命令（0.4 积分/次），额度保护覆盖显式 `--size`。
 - **v0.43.0**：按条计费列表的额度保护（省略 `--size` 时估算超过 1000 积分须 `--yes`）；翻页结果的跨页重复、版本变化与 `total` 封顶检测。
 - **v0.42.0**：数值参数只收十进制写法（`0x10` / `1e3` 这类写法发请求前报错）；接管道时保留退出码 `3` / `4`。
 - **v0.41.0**：新增债券 12 个命令与云盘管理 9 个命令；观点列表改走 v2（列表只含摘要 1 积分/条，正文按 ID 另取）；新增会议线索与联网搜索。
@@ -48,13 +49,17 @@ npm install -g gangtise-openapi-cli
 gangtise --help
 ```
 
-更新到最新版（在终端里运行 `gangtise --version` 会与线上版本比对并提示，比对结果一天内复用）：
+更新到最新版：
 
 ```bash
-npm update -g gangtise-openapi-cli
+gangtise update            # 从 npmjs.org 安装最新版（npm install -g），并更新已安装的 Agent Skill 副本
+gangtise update --check    # 只查看有没有新版本，不安装
 ```
 
-> 更新后若使用 Agent Skill：包内 skill 已随包更新，但复制到 `~/.claude/skills/` 等目录的副本是快照，**需重新执行下方「安装」段的复制命令**才能让 AI 助手拿到新版 skill。
+- `update` 命令从 v0.49.0 起提供，更早的版本先运行一次 `npm install -g gangtise-openapi-cli@latest`
+- `gangtise update` 只更新通过 `npm install -g` 安装的 CLI；从仓库 clone 运行的，按原方式 `git pull` 后重新构建。npm 报权限错误（`EACCES`）时，按提示用 `sudo npm install -g …` 安装后，再运行一次 `gangtise update` 更新 Agent Skill 副本
+- Agent Skill：`~/.claude/skills/`、`~/.codex/skills/`、`~/.openclaw/workspace/skills/`、`~/.hermes/skills/` 下版本低于新版的 `gangtise-openapi` 副本会被替换（**对副本做过的本地修改会被覆盖**）；版本相同或更新的副本、符号链接、以及其他目录下的副本不动。加 `--no-skill` 则不碰 skill 副本
+- 在终端里运行任何命令时，若已有新版本，命令结束后 stderr 提示一行（同一个新版本大约一天提示一次）。版本信息在后台刷新，命令本身不等待网络；输出不是终端时（脚本、Agent、CI）不提示。设 `GANGTISE_NO_UPDATE_CHECK=1` 可关闭提示与后台查询
 
 本地开发：
 
@@ -80,6 +85,7 @@ export GANGTISE_PAGE_CONCURRENCY=5     # 翻页/分片并发数（默认 5，上
 export GANGTISE_VERBOSE=1              # 打印每个请求的耗时与字节数
 export GANGTISE_TIMEOUT_MS=30000       # 请求超时，整数毫秒（默认 30s；上限 1 小时；低于 1 秒或写法非法时用默认值；未按所写数值生效时在 stderr 提示）。按「多久没收到数据」计时，另有单次请求总时长上限：普通请求为它的 2 倍，下载与上传为 60 倍。one-pager 等生成类命令至少 120 秒、上传类至少 300 秒，设得更短不生效
 export GANGTISE_TOKEN_CACHE_PATH=...   # 覆盖 token 缓存路径（默认 ~/.config/gangtise/token.json）
+export GANGTISE_NO_UPDATE_CHECK=1      # 关闭新版本提示与后台版本查询
 ```
 
 环境变量设成空字符串（如 `GANGTISE_BASE_URL=`）按未设置处理，取默认值。`GANGTISE_BASE_URL` 指向非本机地址却用 `http://` 时，CLI 在 stderr 提示一次：登录与请求里的 AK / SK / token 会明文传输。
@@ -137,7 +143,7 @@ install_skill ~/.hermes/skills               # Hermes
 
 > 从仓库 clone 开发时，把 `$SKILL_SRC` 换成仓库内 `gangtise-openapi` 目录的绝对路径即可。
 
-> **版本更新**：`SKILL.md` 头部的 `version` 字段与 CLI 版本一致。`npm update -g gangtise-openapi-cli` 之后重新执行上面这段，再看已安装副本的 `version` 是否与 `gangtise --version` 相同。对已安装副本做过的本地修改会被覆盖。
+> **版本更新**：`SKILL.md` 头部的 `version` 字段与 CLI 版本一致。`gangtise update` 会一并替换上面四个目录里版本较旧的副本；装在其他目录的副本，更新 CLI 后重新执行上面这段，再看已安装副本的 `version` 是否与 `gangtise --version` 相同。对已安装副本做过的本地修改会被覆盖。
 
 安装后，可以用自然语言触发，例如：
 - "帮我查今天所有的研报"
@@ -272,6 +278,7 @@ install_skill ~/.hermes/skills               # Hermes
 - `gangtise reference ...`
 - `gangtise tool ...`
 - `gangtise raw call ...` / `gangtise raw list`
+- `gangtise update`（更新 CLI 与 Agent Skill 副本）
 
 ## 推荐工作流
 
@@ -735,7 +742,7 @@ gangtise fund etf-share-change --security 510300.SH --start-date 2026-09-01 --en
 
 > **基金命令一律按次计费 0.4 积分**（与返回行数、基金只数无关，多只基金合并成一次调用最省），超时 / 5xx 不自动重放。不分页：单次上限 10000 行，超出整批报 `100006`，减少只数或缩短区间分批查。**代码不存在、不带后缀或后缀小写都返回空结果、不报错**——拿到空先核对代码。日期两端都不传 = 取账号可回溯窗口内的全部；起点早于窗口整批报 `110003`。
 
-> **取数前注意**：各命令单位不同（`nav` / `asset-allocation` 为元，`asset-size` 为万份 / 万元，持仓明细为万股 / 万张 / 万元）；`holder-structure` 的 `holderCount` 是带千分位的字符串；持仓明细只返回证券简称、不返回代码；`fund-type-allocation` 季报期只含重仓基金（`positionType: top`），中报 / 年报为全部持基（`all`）。逐条见 `gangtise-openapi/references/commands/fund.md`。
+> **取数前注意**：各命令单位不同（`nav` / `asset-allocation` 为元，`asset-size` 为万份 / 万元，持仓明细为万股 / 万张 / 万元）；持仓明细只返回证券简称、不返回代码；ETF 申赎成分的 `componentCode` 由 CLI 按名称匹配补上（匹配不到为 `null`，`--no-component-code` 关闭）；`fund-type-allocation` 季报期只含重仓基金（`positionType: top`），中报 / 年报为全部持基（`all`）。逐条见 `gangtise-openapi/references/commands/fund.md`。
 
 ### AI
 
@@ -762,7 +769,7 @@ gangtise ai management-discuss-announcement --report-date 2025-12-31 --security-
 gangtise ai management-discuss-announcement --report-date 2025-12-31 --security-code 000001.SZ --dimension all
 # 管理层讨论-业绩会
 gangtise ai management-discuss-earnings-call --report-date 2025-06-30 --security-code 000001.SZ --dimension financialPerformance
-# 管理层情绪：指标与结论按条计费（5 积分/条），记得带 --size；返回的 publishTime 比北京时间早 8 小时
+# 管理层情绪：指标与结论按条计费（5 积分/条），记得带 --size；publishTime 与时间筛选都是北京时间
 gangtise ai management-sentiment-indicator --security 300285.SZ --size 5
 gangtise ai management-sentiment-conclusion --security 300285.SZ --start-time 2026-08-01 --end-time 2026-08-31 --size 5
 # 逐条问答的评分与依据：--source-id 取上面返回的 source.sourceId（10 积分/次）

package/dist/src/cli.js

@@ -4,19 +4,21 @@ import { ACCUMULATING_PARSERS, unknownChoiceMessage } from "./core/args.js";
 import { ApiError, ValidationError } from "./core/errors.js";
 import { removeStagingFiles } from "./core/output.js";
 import { isVerbose, setVerbose } from "./core/transport.js";
-import { checkForUpdate } from "./core/updateCheck.js";
+import { checkForUpdate, noticeUpdate } from "./core/updateCheck.js";
 import { CLI_VERSION } from "./version.js";
 import { COMMAND_GROUPS } from "./commands/groups.js";
 import { decidedExitCode, markFailed } from "./core/exitStatus.js";
 const program = new Command();
+let ranCommand;
 program
     .name("gangtise")
     .description("Gangtise OpenAPI CLI")
     .version(CLI_VERSION)
     .option("--verbose", "Print per-request timings to stderr (also: GANGTISE_VERBOSE=1)")
-    .hook("preAction", (thisCommand) => {
+    .hook("preAction", (thisCommand, actionCommand) => {
     if (thisCommand.opts().verbose)
         setVerbose(true);
+    ranCommand = actionCommand;
 });
 for (const group of COMMAND_GROUPS) {
     program.addCommand(group);
@@ -100,7 +102,7 @@ async function main() {
     const firstArg = process.argv[2];
     if (firstArg === "--version" || firstArg === "-V") {
         process.stdout.write(`${CLI_VERSION}\n`);
-        if (process.stdout.isTTY) {
+        if (process.stdout.isTTY && !process.env.GANGTISE_NO_UPDATE_CHECK) {
             await Promise.race([checkForUpdate(CLI_VERSION), new Promise((resolve) => setTimeout(resolve, 2500))]);
             process.exit(0);
         }
@@ -125,5 +127,9 @@ async function main() {
         process.stderr.write("Unknown error\n");
         markFailed();
     }
+    finally {
+        if (process.stderr.isTTY && !process.env.CI && !process.env.GANGTISE_NO_UPDATE_CHECK && ranCommand?.name() !== "update")
+            noticeUpdate(CLI_VERSION);
+    }
 }
 void main();

package/dist/src/commands/ai.js

@@ -64,8 +64,8 @@ query(ai, "security-clue", {
         from(), size(),
         field(new Option("--start-time <datetime>", "Start time").argParser(datetimeArg("--start-time")).makeOptionMandatory(), (v) => ({ startTime: v })),
         field(new Option("--end-time <datetime>", "End time").argParser(datetimeArg("--end-time")).makeOptionMandatory(), (v) => ({ endTime: v })),
-        field(new Option("--query-mode <mode>").choices(["bySecurity", "byIndustry"]).makeOptionMandatory(), (v) => ({ queryMode: v })),
-        list("--gts-code <code>", "GTS code", "gtsCodeList"),
+        field(new Option("--query-mode <mode>", "bySecurity: --gts-code takes stock codes; byIndustry: Shenwan industry codes").choices(["bySecurity", "byIndustry"]).makeOptionMandatory(), (v) => ({ queryMode: v })),
+        list("--gts-code <code>", "Stock code (e.g. 600519.SH) or Shenwan industry code (e.g. 821035.SWI), per --query-mode; repeatable", "gtsCodeList"),
         choiceList("--source <name>", "Source: researchReport/conference/announcement/view (repeat)", "source", ["researchReport", "conference", "announcement", "view"]),
         format(), output(),
     ],

package/dist/src/commands/fund.js

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { collectNames } from "../core/args.js";
-import { date, format, list, output, query, requiredList, value } from "./shared.js";
+import { addComponentCodes, clientLookup } from "../core/etfComponents.js";
+import { date, flag, format, list, output, query, requiredList, value } from "./shared.js";
 export const fund = new Command("fund").description("Fund APIs: profiles, NAV, fees, managers, scale, holders, holdings and allocation, ETF creation/redemption");
 const code = () => requiredList("--security <code>", "Fund code, e.g. 005827.OF / 159967.SZ / 510300.SH (repeatable, comma-separated accepted). From a fund name: 'reference securities-search --category fund', keeping only rows whose category is fund", "fundCodeList");
 const range = (what) => [
@@ -89,9 +90,10 @@ query(fund, "etf-pcf-header", {
     fields: [code(), format(), output()],
 });
 query(fund, "etf-pcf-components", {
-    description: "ETF creation/redemption component list for the latest trade date: quantities, weights, cash substitution",
+    description: "ETF creation/redemption component list for the latest trade date: quantities, weights, cash substitution. componentCode is matched by the CLI from each component name",
     endpoint: "fund.etf-pcf-components",
-    fields: [code(), format(), output()],
+    fields: [code(), format(), output(), flag("--no-component-code", "Skip matching componentCode: no download of the securities list, no name searches, no quote request")],
+    shape: (data, client, options) => options.componentCode === false ? Promise.resolve(data) : addComponentCodes(data, clientLookup(client)),
 });
 query(fund, "etf-share-change", {
     description: "ETF shares and scale per trade date, with the change vs the previous one",

package/dist/src/commands/groups.js

@@ -10,5 +10,6 @@ import { quote } from "./quote.js";
 import { raw } from "./raw.js";
 import { reference } from "./reference.js";
 import { tool } from "./tool.js";
+import { update } from "./update.js";
 import { vault } from "./vault.js";
-export const COMMAND_GROUPS = [auth, lookup, insight, quote, fundamental, bond, fund, reference, vault, ai, alternative, indicator, tool, raw];
+export const COMMAND_GROUPS = [auth, lookup, insight, quote, fundamental, bond, fund, reference, vault, ai, alternative, indicator, tool, raw, update];

package/dist/src/commands/indicator.js

@@ -28,7 +28,7 @@ function flagDropped(rows, data, requestedSecurities, requestedIndicators) {
         parts.push(`indicators ${indicators.join(", ")}`);
     if (securities.length > 0)
         parts.push(`securities ${securities.join(", ")}`);
-    process.stderr.write(`[gangtise] warning: the response omits ${parts.join(" and ")} entirely — no row/column at all, not a null one. A code the server merely has no data for still comes back as null, so this normally means the code itself was not recognised: check it for typos and, for securities, for the wrong market suffix (US tickers are .O/.N, not .US). Result marked partial (exit 3).\n`);
+    process.stderr.write(`[gangtise] warning: the response omits ${parts.join(" and ")} entirely — no row/column at all, not a null one. A code the server merely has no data for still comes back as null, so this normally means the code itself was not recognised: check it for typos and, for securities, for the wrong market suffix (US tickers are .O/.N/.A, not .US). Result marked partial (exit 3).\n`);
 }
 function requireIndicatorScope(indicators, securities) {
     const missing = [indicators.length === 0 ? "--indicator" : "", securities.length === 0 ? "--security" : ""].filter(Boolean);

package/dist/src/commands/shared.js

@@ -221,6 +221,7 @@ export function query(parent, name, spec) {
     return command.action(async (options) => {
         const body = requestBody(fields, options);
         const endpoint = typeof spec.endpoint === "string" ? spec.endpoint : spec.endpoint(options);
-        return emit(options, (client) => client.call(endpoint, body), spec.cache);
+        const shape = spec.shape;
+        return emit(options, shape ? async (client) => shape(await client.call(endpoint, body), client, options) : (client) => client.call(endpoint, body), spec.cache);
     });
 }

package/dist/src/commands/update.js

@@ -0,0 +1,30 @@
+import os from "node:os";
+import { Command } from "commander";
+import { isVersionNewer } from "../core/args.js";
+import { installVersion, refreshSkillCopies } from "../core/selfUpdate.js";
+import { latestVersion, PACKAGE_NAME, REGISTRY } from "../core/updateCheck.js";
+import { CLI_VERSION, PACKAGE_ROOT } from "../version.js";
+export const update = new Command("update")
+    .description("Update to the latest published version (npm install -g), then refresh older copies of the Agent Skill installed for Claude Code / Codex / OpenClaw / Hermes")
+    .option("--check", "Only report whether a newer version is published; install nothing")
+    .option("--no-skill", "Leave the Agent Skill copies as they are")
+    .action(async (options) => {
+    const latest = await latestVersion(undefined, 15_000, Date.now(), true);
+    if (!latest)
+        throw new Error(`Could not reach ${REGISTRY} to look up the latest version. Check the network and retry, or install directly: npm install -g ${PACKAGE_NAME}@latest --registry=${REGISTRY}`);
+    const outdated = isVersionNewer(latest, CLI_VERSION);
+    if (options.check) {
+        process.stdout.write(outdated ? `Update available: ${CLI_VERSION} → ${latest}. Run: gangtise update\n` : `gangtise ${CLI_VERSION} is the latest version.\n`);
+        return;
+    }
+    if (outdated) {
+        installVersion(latest, PACKAGE_ROOT);
+        process.stdout.write(`Updated gangtise ${CLI_VERSION} → ${latest}.\n`);
+    }
+    else {
+        process.stdout.write(`gangtise ${CLI_VERSION} is the latest version.\n`);
+    }
+    if (options.skill)
+        for (const line of refreshSkillCopies(PACKAGE_ROOT, os.homedir()))
+            process.stdout.write(`${line}\n`);
+});

package/dist/src/core/endpoints.js

@@ -114,7 +114,7 @@ const ENDPOINT_DEFS = {
         description: "List roadshows",
         billing: { per: "row", price: 10 },
         pagination: { enabled: true, maxPageSize: 50 },
-        rowId: "id",
+        rowId: "roadshowId",
         rowIdUnverified: true,
     },
     "insight.site-visit.list": {
@@ -124,7 +124,7 @@ const ENDPOINT_DEFS = {
         description: "List site visits",
         billing: { per: "row", price: 10 },
         pagination: { enabled: true, maxPageSize: 50 },
-        rowId: "id",
+        rowId: "siteVisitId",
         rowIdUnverified: true,
     },
     "insight.strategy.list": {
@@ -134,7 +134,7 @@ const ENDPOINT_DEFS = {
         description: "List strategy meetings",
         billing: { per: "row", price: 10 },
         pagination: { enabled: true, maxPageSize: 50 },
-        rowId: "id",
+        rowId: "strategyMeetingId",
         rowIdUnverified: true,
     },
     "insight.forum.list": {
@@ -144,7 +144,7 @@ const ENDPOINT_DEFS = {
         description: "List forums",
         billing: { per: "row", price: 10 },
         pagination: { enabled: true, maxPageSize: 50 },
-        rowId: "id",
+        rowId: "forumId",
         rowIdUnverified: true,
     },
     "insight.performance-calendar.list": {

package/dist/src/core/etfComponents.js

@@ -0,0 +1,301 @@
+import { beijingDateString } from "./args.js";
+import { normalizeRows } from "./normalize.js";
+import { PAGE_CONCURRENCY, runWithConcurrency } from "./transport.js";
+const PRICE_TOLERANCE = 0.0005;
+const agrees = (close, price) => price > 0 && Math.abs(close - price) / price <= PRICE_TOLERANCE;
+const QUOTABLE = /^(\d{6}\.(SH|SZ|BJ)|\d{5}\.HK|[A-Z][A-Z0-9.]*\.(O|N|A))$/;
+const QUOTE_BATCH = 500;
+const CLOSES_WINDOW_DAYS = 10;
+const CLOSES_BATCH = 1000;
+const squash = (name) => name.replace(/\s+/g, "");
+const base = (name) => squash(name).replace(/-[A-Z]+$/, "");
+const ticker = (code) => code.slice(0, code.lastIndexOf("."));
+const exchange = (code) => code.slice(code.lastIndexOf(".") + 1);
+const market = (code) => {
+    const suffix = exchange(code);
+    return ["SH", "SZ", "BJ"].includes(suffix) ? "CN" : ["O", "N", "A"].includes(suffix) ? "US" : suffix;
+};
+function toCandidates(rows) {
+    return rows.flatMap((row) => {
+        const r = row;
+        return typeof r.gtsCode === "string" && typeof r.gtsName === "string" && r.category !== "index"
+            ? [{ code: r.gtsCode, name: r.gtsName, category: String(r.category), prefix: false }]
+            : [];
+    });
+}
+async function candidatesFor(name, lookup) {
+    const key = squash(name);
+    const found = toCandidates(await lookup.search(key));
+    const exact = found.filter((c) => base(c.name) === base(key) || ticker(c.code) === key);
+    if (/^[A-Z][A-Z0-9]{0,6}$/.test(key) && !exact.some((c) => market(c.code) === "US")) {
+        const bySuffix = (await Promise.all(["O", "N"].map((suffix) => lookup.search(`${key}.${suffix}`))))
+            .flatMap((rows) => toCandidates(rows))
+            .filter((c) => ticker(c.code) === key);
+        exact.push(...bySuffix);
+    }
+    const prefix = base(key).length >= 2 ? found.filter((c) => !exact.includes(c) && base(c.name).startsWith(base(key))) : [];
+    return [...exact, ...prefix.map((c) => ({ ...c, prefix: true }))];
+}
+function narrow(candidates, etf) {
+    let left = candidates;
+    if (new Set(left.map((c) => market(c.code))).size > 1) {
+        if (!etf.market)
+            return null;
+        left = left.filter((c) => market(c.code) === etf.market);
+    }
+    if (left.length > 1) {
+        const same = left.filter((c) => exchange(c.code) === etf.exchange);
+        if (same.length)
+            left = same;
+    }
+    return left.length === 1 ? left[0].code : null;
+}
+function byPrice(row, candidates, prices, etf, unchecked) {
+    const close = typeof row.close === "number" ? row.close : undefined;
+    if (close === undefined)
+        return undefined;
+    const open = candidates.filter((c) => !etf.used.has(c.code));
+    for (const tier of [open.filter((c) => !c.prefix), open.filter((c) => c.prefix)]) {
+        if (tier.some((c) => !prices.get(c.code)?.some((p) => p > 0) && unchecked(c)))
+            return undefined;
+        const matched = tier.filter((c) => prices.get(c.code)?.some((p) => agrees(close, p)));
+        if (matched.length)
+            return narrow(matched, etf);
+    }
+    return undefined;
+}
+function byName(candidates, etf) {
+    if (!etf.market)
+        return null;
+    const pool = candidates.filter((c) => !c.prefix && !etf.used.has(c.code) && market(c.code) === etf.market);
+    return pool.length ? narrow(pool, etf) : null;
+}
+async function splitting(codes, fetch) {
+    try {
+        return await fetch(codes);
+    }
+    catch (error) {
+        if (codes.length === 1 || error?.code !== "120001")
+            return new Map();
+        const half = Math.ceil(codes.length / 2);
+        const first = await splitting(codes.slice(0, half), fetch);
+        return new Map([...first, ...await splitting(codes.slice(half), fetch)]);
+    }
+}
+const inBatches = (codes, size) => Array.from({ length: Math.ceil(codes.length / size) }, (_, i) => codes.slice(i * size, (i + 1) * size));
+function listDates(rows, candidates, history) {
+    const votes = new Map();
+    for (const row of rows) {
+        if (typeof row.close !== "number")
+            continue;
+        const exact = (candidates.get(row.componentName) ?? []).filter((c) => !c.prefix);
+        if (exact.length !== 1)
+            continue;
+        const tally = votes.get(market(exact[0].code)) ?? new Map();
+        for (const [date, close] of history.get(exact[0].code) ?? []) {
+            if (agrees(row.close, close))
+                tally.set(date, (tally.get(date) ?? 0) + 1);
+        }
+        votes.set(market(exact[0].code), tally);
+    }
+    const dates = new Map();
+    for (const [where, tally] of votes) {
+        const ranked = [...tally].sort((a, b) => b[1] - a[1]);
+        if (ranked.length && ranked[0][1] >= 2 && ranked[1]?.[1] !== ranked[0][1])
+            dates.set(where, ranked[0][0]);
+    }
+    return dates;
+}
+function closesOn(dates, history) {
+    const out = new Map();
+    for (const [code, series] of history) {
+        const date = dates.get(market(code));
+        if (!date)
+            continue;
+        const last = series.filter(([d]) => d <= date).at(-1);
+        if (last)
+            out.set(code, [last[1]]);
+    }
+    return out;
+}
+const carriesCode = (row) => typeof row.componentCode === "string" && row.componentCode !== "";
+const needsCode = (row) => !carriesCode(row) && typeof row.componentName === "string";
+export async function fillComponentCodes(rows, lookup) {
+    const pending = rows.filter(needsCode);
+    const names = [...new Set(pending.map((r) => r.componentName))];
+    const candidates = new Map();
+    await runWithConcurrency(names, PAGE_CONCURRENCY, async (name) => {
+        candidates.set(name, await candidatesFor(name, lookup).catch(() => []));
+    });
+    const quotable = [...new Set([...candidates.values()].flat().filter((c) => ["stock", "dr"].includes(c.category) && QUOTABLE.test(c.code)).map((c) => c.code))];
+    const prices = new Map((await runWithConcurrency(inBatches(quotable, QUOTE_BATCH), PAGE_CONCURRENCY, (batch) => splitting(batch, (codes) => lookup.quotes(codes)))).flatMap((quoted) => [...quoted]));
+    const isQuotable = (c) => ["stock", "dr"].includes(c.category) && QUOTABLE.test(c.code);
+    const codes = new Map();
+    const etfs = new Map();
+    const place = (row, code, etf) => {
+        codes.set(row, code);
+        if (code)
+            etf.used.add(code);
+    };
+    for (const fundCode of new Set(pending.map((r) => r.fundCode))) {
+        const own = pending.filter((r) => r.fundCode === fundCode);
+        const etf = { exchange: exchange(String(fundCode)), used: new Set() };
+        etfs.set(fundCode, { own, etf });
+        for (const row of own) {
+            const code = byPrice(row, candidates.get(row.componentName) ?? [], prices, etf, isQuotable);
+            if (code !== undefined)
+                place(row, code, etf);
+        }
+    }
+    const open = (own) => own.filter((r) => !codes.has(r) && typeof r.close === "number" && (candidates.get(r.componentName) ?? []).some(isQuotable));
+    const lagging = [...etfs.values()].filter(({ own }) => open(own).length);
+    if (lagging.length && lookup.closes) {
+        const wanted = [...new Set(lagging.flatMap(({ own }) => own.flatMap((r) => (candidates.get(r.componentName) ?? []).filter(isQuotable).map((c) => c.code))))];
+        const end = beijingDateString(new Date());
+        const start = beijingDateString(new Date(Date.now() - CLOSES_WINDOW_DAYS * 86_400_000));
+        const history = new Map((await runWithConcurrency(inBatches(wanted, CLOSES_BATCH), PAGE_CONCURRENCY, (batch) => splitting(batch, (codes) => lookup.closes(codes, start, end)))).flatMap((part) => [...part]));
+        for (const { own, etf } of lagging) {
+            const dates = listDates(own, candidates, history);
+            const onDate = closesOn(dates, history);
+            for (const row of open(own)) {
+                const unchecked = (c) => isQuotable(c) && (history.get(c.code)?.some(([, close]) => agrees(row.close, close)) ?? true);
+                const code = byPrice(row, candidates.get(row.componentName) ?? [], onDate, etf, unchecked);
+                if (code !== undefined)
+                    place(row, code, etf);
+            }
+        }
+    }
+    for (const { own, etf } of etfs.values()) {
+        const markets = new Set([...etf.used].map(market));
+        for (const r of own) {
+            const held = new Set((candidates.get(r.componentName) ?? []).filter((c) => !c.prefix).map((c) => market(c.code)));
+            if (held.size === 1)
+                markets.add([...held][0]);
+        }
+        if (markets.size === 1)
+            etf.market = [...markets][0];
+        for (const row of own)
+            if (!codes.has(row))
+                place(row, byName(candidates.get(row.componentName) ?? [], etf), etf);
+    }
+    const unresolved = [];
+    const filled = rows.map((row) => {
+        if (!codes.has(row))
+            return row;
+        const code = codes.get(row) ?? null;
+        if (!code)
+            unresolved.push({ fundCode: row.fundCode, serialNumber: row.serialNumber, componentName: row.componentName });
+        const out = {};
+        for (const [key, value] of Object.entries(row)) {
+            if (key === "componentCode")
+                continue;
+            out[key] = value;
+            if (key === "serialNumber")
+                out.componentCode = code;
+        }
+        if (!("componentCode" in out))
+            out.componentCode = code;
+        return out;
+    });
+    return { rows: filled, unresolved };
+}
+export async function addComponentCodes(data, lookup) {
+    const list = data?.list;
+    if (!Array.isArray(list))
+        return data;
+    const rows = list;
+    const pending = rows.filter(needsCode).length;
+    if (!pending)
+        return data;
+    const filled = await fillComponentCodes(rows, lookup);
+    const left = filled.unresolved.map((u) => `${String(u.fundCode)} ${String(u.componentName)}`);
+    const shown = left.length > 20 ? `${left.slice(0, 20).join(", ")}, …` : left.join(", ");
+    process.stderr.write(`[gangtise] note: the API returns component names only; componentCode is the CLI's match for each name (looked up in the securities list, and checked against the component's close where it can be quoted): ${pending - left.length} of ${pending} rows.${left.length ? ` Left null (cash lines, commodities, names without a confident match): ${shown}` : ""}\n`);
+    return { ...data, list: filled.rows };
+}
+const MARKET_SECTORS = ["1000000002", "1000002615", "1000002618"];
+export async function loadSecurityTable(fetchSector) {
+    try {
+        const markets = await Promise.all(MARKET_SECTORS.map(async (sectorId) => {
+            const data = await fetchSector(sectorId);
+            const list = (Array.isArray(data?.list) ? data.list : []).flatMap((row) => {
+                const r = row;
+                return typeof r.gtsCode === "string" && typeof r.gtsName === "string" ? [[r.gtsCode, r.gtsName]] : [];
+            });
+            if (!list.length)
+                throw new Error(`sector ${sectorId} listed nothing`);
+            return list;
+        }));
+        return markets.flat();
+    }
+    catch {
+        return undefined;
+    }
+}
+export function tableSearch(list) {
+    const byBase = new Map();
+    const byTicker = new Map();
+    const byCode = new Map();
+    const add = (index, key, listing) => {
+        const listed = index.get(key);
+        if (listed)
+            listed.push(listing);
+        else
+            index.set(key, [listing]);
+    };
+    for (const listing of list) {
+        add(byBase, base(listing[1]), listing);
+        add(byTicker, ticker(listing[0]), listing);
+        byCode.set(listing[0], listing);
+    }
+    const bases = [...byBase.keys()];
+    return (keyword) => {
+        const key = squash(keyword);
+        const name = base(key);
+        const coded = byCode.get(key);
+        const exact = [...(byBase.get(name) ?? []), ...(byTicker.get(key) ?? []), ...(coded ? [coded] : [])];
+        if (!exact.length)
+            return undefined;
+        const prefix = name.length >= 2 ? bases.filter((b) => b !== name && b.startsWith(name)).flatMap((b) => byBase.get(b)) : [];
+        return [...new Set([...exact, ...prefix])].map(([gtsCode, gtsName]) => ({ gtsCode, gtsName, category: "stock" }));
+    };
+}
+export function clientLookup(client) {
+    let table;
+    const local = () => (table ??= loadSecurityTable((sectorId) => client.call("reference.sector-constituents", { sectorId })).then((list) => list && tableSearch(list)));
+    return {
+        async search(keyword) {
+            const hits = (await local())?.(keyword);
+            if (hits)
+                return hits;
+            const data = await client.call("reference.securities-search", { keyword, top: 10 });
+            return Array.isArray(data?.list) ? data.list : [];
+        },
+        async closes(codes, startDate, endDate) {
+            const data = normalizeRows(await client.call("quote.day-kline", { securityList: codes, startDate, endDate, fieldList: ["securityCode", "tradeDate", "close"], limit: 10_000 }));
+            const list = Array.isArray(data) ? data : (data?.list ?? []);
+            const out = new Map();
+            for (const k of list) {
+                if (typeof k.securityCode !== "string" || typeof k.tradeDate !== "string" || typeof k.close !== "number")
+                    continue;
+                const series = out.get(k.securityCode) ?? [];
+                series.push([k.tradeDate, k.close]);
+                out.set(k.securityCode, series);
+            }
+            for (const series of out.values())
+                series.sort((a, b) => (a[0] < b[0] ? -1 : 1));
+            return out;
+        },
+        async quotes(codes) {
+            const data = normalizeRows(await client.call("quote.realtime", { securityList: codes }));
+            const list = Array.isArray(data) ? data : (data?.list ?? []);
+            const out = new Map();
+            for (const q of list) {
+                const prices = [q.preClose, q.latestPrice].filter((p) => typeof p === "number");
+                if (typeof q.securityCode === "string" && prices.length)
+                    out.set(q.securityCode, prices);
+            }
+            return out;
+        },
+    };
+}

package/dist/src/core/selfUpdate.js

@@ -0,0 +1,94 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { isVersionNewer } from "./args.js";
+import { PACKAGE_NAME, REGISTRY } from "./updateCheck.js";
+export const SKILL_HOMES = [[".claude", "skills"], [".codex", "skills"], [".openclaw", "workspace", "skills"], [".hermes", "skills"]];
+const SKILL_DIR = "gangtise-openapi";
+const runNpm = (args, inherit) => {
+    const options = { encoding: "utf8", stdio: inherit ? "inherit" : "pipe" };
+    const result = process.platform === "win32" ? spawnSync(["npm", ...args].join(" "), { ...options, shell: true }) : spawnSync("npm", args, options);
+    return { status: result.status, stdout: result.stdout ?? "" };
+};
+function isSymlink(file) {
+    try {
+        return fs.lstatSync(file).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function samePath(a, b) {
+    try {
+        return fs.realpathSync(a) === fs.realpathSync(b);
+    }
+    catch {
+        return false;
+    }
+}
+export function installVersion(version, packageRoot, npm = runNpm) {
+    if (!/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(version))
+        throw new Error(`The registry answered an unexpected version (${JSON.stringify(version)}); nothing was installed.`);
+    const root = npm(["root", "-g"], false);
+    const globalRoot = root.status === 0 ? root.stdout.trim() : "";
+    if (!globalRoot)
+        throw new Error("Could not run npm, which gangtise update uses to install. Install Node.js with npm, or update gangtise the way it was installed.");
+    const installed = path.join(globalRoot, PACKAGE_NAME);
+    if (!samePath(installed, packageRoot)) {
+        throw new Error(`This gangtise runs from ${packageRoot}, which is not npm's global install (${globalRoot}). Update it the way it was installed — in a clone: git pull && npm install && npm run build.`);
+    }
+    if (isSymlink(installed)) {
+        throw new Error(`This gangtise is a checkout linked into npm's global install (${installed} → ${packageRoot}, npm link). Update the checkout instead: git pull && npm install && npm run build.`);
+    }
+    const spec = `${PACKAGE_NAME}@${version}`;
+    const install = npm(["install", "-g", spec, `--registry=${REGISTRY}`], true);
+    if (install.status !== 0) {
+        throw new Error(`npm install exited with ${install.status ?? "a signal"}. On a permission error (EACCES), run: sudo npm install -g ${spec} --registry=${REGISTRY} — then gangtise update again to refresh the Agent Skill copies.`);
+    }
+    const landed = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version;
+    if (landed !== version)
+        throw new Error(`npm reported success, but ${packageRoot} still holds ${landed}.`);
+}
+function skillVersion(dir) {
+    try {
+        return /^version:\s*["']?([^"'\n]+)/m.exec(fs.readFileSync(path.join(dir, "SKILL.md"), "utf8"))?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
+export function refreshSkillCopies(packageRoot, home) {
+    const source = path.join(packageRoot, SKILL_DIR);
+    const version = skillVersion(source);
+    if (!version)
+        return [];
+    const replaced = [];
+    for (const parts of SKILL_HOMES) {
+        const target = path.join(home, ...parts, SKILL_DIR);
+        let stat;
+        try {
+            stat = fs.lstatSync(target);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        const current = skillVersion(target);
+        if (current !== undefined && !isVersionNewer(version, current))
+            continue;
+        const staging = `${target}.update-${process.pid}`;
+        fs.rmSync(staging, { recursive: true, force: true });
+        try {
+            fs.cpSync(source, staging, { recursive: true });
+            fs.rmSync(target, { recursive: true, force: true });
+            fs.renameSync(staging, target);
+        }
+        catch (error) {
+            fs.rmSync(staging, { recursive: true, force: true });
+            throw new Error(`Could not replace the Agent Skill copy at ${target} (${error.message}). Copy ${source} there again.`);
+        }
+        replaced.push(`Agent Skill updated: ${target} (${current ?? "no version"} → ${version})`);
+    }
+    return replaced;
+}

package/dist/src/core/updateCheck.js

@@ -1,36 +1,47 @@
+import { spawn } from "node:child_process";
 import { mkdirSync, readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { isVersionNewer } from "./args.js";
 import { writeFileAtomicSync } from "./output.js";
 export const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+export const REFRESH_RETRY_MS = 60 * 60 * 1000;
 export const DEFAULT_UPDATE_CHECK_PATH = path.join(os.homedir(), ".config", "gangtise", "update-check.json");
-function saveLatest(cachePath, latest, now) {
+export const REGISTRY = "https://registry.npmjs.org";
+export const PACKAGE_NAME = "gangtise-openapi-cli";
+function readFile(cachePath) {
+    try {
+        const kept = JSON.parse(readFileSync(cachePath, "utf8"));
+        if (kept && typeof kept === "object")
+            return kept;
+    }
+    catch { }
+    return {};
+}
+const answerIn = (kept) => typeof kept.checkedAt === "number" && typeof kept.latest === "string" ? kept : undefined;
+const isFresh = (kept, now) => now - kept.checkedAt >= 0 && now - kept.checkedAt < UPDATE_CHECK_TTL_MS;
+function keep(cachePath, kept) {
     try {
         mkdirSync(path.dirname(cachePath), { recursive: true });
-        writeFileAtomicSync(cachePath, JSON.stringify({ checkedAt: now, latest }), { suffix: "tmp" });
+        writeFileAtomicSync(cachePath, JSON.stringify(kept), { suffix: "tmp" });
     }
     catch {
     }
 }
-export async function latestVersion(cachePath = DEFAULT_UPDATE_CHECK_PATH, timeoutMs = 2000, now = Date.now()) {
+export async function latestVersion(cachePath = DEFAULT_UPDATE_CHECK_PATH, timeoutMs = 2000, now = Date.now(), fresh = false) {
     const cacheable = path.isAbsolute(cachePath);
-    if (cacheable) {
-        try {
-            const cached = JSON.parse(readFileSync(cachePath, "utf8"));
-            const age = typeof cached.checkedAt === "number" ? now - cached.checkedAt : -1;
-            if (typeof cached.latest === "string" && age >= 0 && age < UPDATE_CHECK_TTL_MS)
-                return cached.latest;
-        }
-        catch { }
+    if (cacheable && !fresh) {
+        const kept = answerIn(readFile(cachePath));
+        if (kept && isFresh(kept, now))
+            return kept.latest;
     }
     try {
-        const response = await fetch("https://registry.npmjs.org/gangtise-openapi-cli/latest", { signal: AbortSignal.timeout(timeoutMs) });
+        const response = await fetch(`${REGISTRY}/${PACKAGE_NAME}/latest`, { signal: AbortSignal.timeout(timeoutMs) });
         const latest = (await response.json()).version;
         if (typeof latest !== "string")
             return undefined;
         if (cacheable)
-            saveLatest(cachePath, latest, now);
+            keep(cachePath, { checkedAt: now, latest });
         return latest;
     }
     catch {
@@ -40,6 +51,31 @@ export async function latestVersion(cachePath = DEFAULT_UPDATE_CHECK_PATH, timeo
 export async function checkForUpdate(current) {
     const latest = await latestVersion();
     if (latest && isVersionNewer(latest, current)) {
-        process.stderr.write(`Update available: ${current} → ${latest}\nRun: npm update -g gangtise-openapi-cli\n`);
+        process.stderr.write(`Update available: ${current} → ${latest}\nRun: gangtise update\n`);
+    }
+}
+function refreshInBackground(cachePath) {
+    try {
+        const script = `import(${JSON.stringify(import.meta.url)}).then((m) => m.latestVersion(${JSON.stringify(cachePath)}, 10000, Date.now(), true))`;
+        const child = spawn(process.execPath, ["-e", script], { detached: true, stdio: "ignore", windowsHide: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch { }
+}
+export function noticeUpdate(current, cachePath = DEFAULT_UPDATE_CHECK_PATH, now = Date.now(), refresh = refreshInBackground) {
+    if (!path.isAbsolute(cachePath))
+        return;
+    const file = readFile(cachePath);
+    const kept = answerIn(file);
+    const started = file.refreshStartedAt;
+    if ((!kept || !isFresh(kept, now)) && !(typeof started === "number" && now - started >= 0 && now - started < REFRESH_RETRY_MS)) {
+        file.refreshStartedAt = now;
+        keep(cachePath, file);
+        refresh(cachePath);
     }
+    if (!kept || kept.notifiedAt !== undefined || !isVersionNewer(kept.latest, current))
+        return;
+    process.stderr.write(`Update available: ${current} → ${kept.latest}. Run: gangtise update\n`);
+    keep(cachePath, { ...file, notifiedAt: now });
 }

package/dist/src/version.js

@@ -1,14 +1,14 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-function packageVersion() {
+function findPackage() {
     let dir = path.dirname(fileURLToPath(import.meta.url));
     for (;;) {
         const file = path.join(dir, "package.json");
         if (fs.existsSync(file)) {
             const pkg = JSON.parse(fs.readFileSync(file, "utf8"));
             if (pkg.name === "gangtise-openapi-cli" && pkg.version)
-                return pkg.version;
+                return { root: dir, version: pkg.version };
         }
         const parent = path.dirname(dir);
         if (parent === dir)
@@ -16,4 +16,6 @@ function packageVersion() {
         dir = parent;
     }
 }
-export const CLI_VERSION = packageVersion();
+const found = findPackage();
+export const PACKAGE_ROOT = found.root;
+export const CLI_VERSION = found.version;

package/gangtise-openapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gangtise-openapi
-version: "0.48.0"
+version: "0.49.0"
 description: |-
   通过 gangtise CLI 直接调用 Gangtise OpenAPI，拉取投研原始数据、批量导出、下载文件、调用 AI 能力。
 
@@ -10,7 +10,7 @@ description: |-
 
   **不适用**：不脱离 OpenAPI 自行撰写研报、编造投研结论或做自由问答——观点总结、多空 PK 等 AI 产物本 skill 只经由 Gangtise 平台 AI 接口获取，不自行生成
 
-  **前置**：依赖 gangtise CLI，未安装时提示用户 `npm install -g gangtise-openapi-cli`
+  **前置**：依赖 gangtise CLI，未安装时提示用户 `npm install -g gangtise-openapi-cli`；升级用 `gangtise update`
 ---
 
 # Gangtise OpenAPI CLI
@@ -252,7 +252,7 @@ vault.stock-pool.create
 | 热点话题 / 早午晚报 | `ai hot-topic` |
 | 管理层讨论（财报） | `ai management-discuss-announcement` |
 | 管理层讨论（业绩会） | `ai management-discuss-earnings-call` |
-| 管理层情绪 / 业绩会问答是否回避 · 乐观 · 确定 / 情绪较上一场的变化 | `ai management-sentiment-indicator`（三维评分，5/条）/ `ai management-sentiment-conclusion`（结论文本与较上一场的对比，5/条）；逐条问答与判断依据 → `ai management-sentiment-detail --source-id <source.sourceId>`（10/次）。⚠️ 返回的 `publishTime` 比北京时间早 8 小时，见 `ai.md` |
+| 管理层情绪 / 业绩会问答是否回避 · 乐观 · 确定 / 情绪较上一场的变化 | `ai management-sentiment-indicator`（三维评分，5/条）/ `ai management-sentiment-conclusion`（结论文本与较上一场的对比，5/条）；逐条问答与判断依据 → `ai management-sentiment-detail --source-id <source.sourceId>`（10/次） |
 | 日 K（历史，A 股 / 港股 / 美股 / 沪深 ETF / 各类指数含全球指数，可混查） | `quote day-kline` |
 | 沪深京指数日 K / 要指数名称 | `quote day-kline` 逐个传指数代码（**没有一次拿全部指数的写法**，`index-day-kline --security all` 会被 CLI 拒绝）；指数名称用 `reference securities-search --keyword <指数代码> --category index`（返回 `gtsName`） |
 | ~~港股 / 美股日 K~~ | ⚠️ 已弃用，用 `quote day-kline`（`day-kline-hk` / `day-kline-us` 仍可调但不校验代码） |
@@ -284,13 +284,13 @@ vault.stock-pool.create
 | 基金经理画像（按人名） | `fund manager-info --manager <姓名>`（精确匹配，同名全返回，用 `currentCompany` 区分） |
 | 某只基金的历任 / 现任经理 | `fund manager-history`（`endDate` 为 `null` = 现任） |
 | 基金规模 / 份额变动 / 申赎份额 | `fund asset-size`（报告期口径）；ETF 逐日份额与规模 → `fund etf-share-change` |
-| 基金持有人结构 / 机构占比 / 前十大持有人 | `fund holder-structure`（`holderCount` 是带千分位的字符串）、`fund top10-holders`（仅上市基金） |
+| 基金持有人结构 / 机构占比 / 前十大持有人 | `fund holder-structure`、`fund top10-holders`（仅上市基金） |
 | 基金资产配置 / 股票仓位 / 债券仓位 | `fund asset-allocation` |
 | 基金重仓股 / 全部持股 / 持仓明细 | `fund stock-portfolio`（`--position-type all` 仅中报、年报有；只返回股票简称、无代码） |
 | 基金行业配置 / 行业分布 | `fund industry-allocation`（申万 / 中信一级二选一） |
 | 基金持债 / 券种分布 | `fund bond-portfolio` / `fund bond-type-allocation` |
 | FOF 持有的基金 / 持有基金类型分布 | `fund fund-portfolio` / `fund fund-type-allocation` |
-| ETF 申购赎回清单 / 成分股 / 现金差额 | `fund etf-pcf-components` / `fund etf-pcf-header`（**只有最新一份清单**，无历史） |
+| ETF 申购赎回清单 / 成分股 / 现金差额 | `fund etf-pcf-components` / `fund etf-pcf-header`（**只有最新一份清单**，无历史；成分代码 `componentCode` 由 CLI 按名称匹配补上，现金行等匹配不到的为 `null`） |
 | 会议线索 / 会议要点 / 核心结论信息流 / 今天有什么会 | `insight highlight list`（🔴 **5 积分/条**，必须带 `--size`；`content` 是 HTML 片段） |
 | 联网搜索 / 查公开信息 / 政策原文 / 传闻核实 | `tool web-search`（1 积分/次；`--site` 定向站点、`--min-tier` 收信源、`--include-content` 取正文〔此时 `--size` ≤5〕） |
 | 云盘文件 | `vault drive-list / drive-download` |
@@ -430,7 +430,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 | `0000001008` / `999002` | token 失效 | CLI 自动换 token（必要时重新登录）后重发，无 AK/SK 时提示重新登录 |
 | `100006` | 查询/下载数量超限 | 缩短日期范围或调小 `--size`/`--limit`；`fund` 没有这两个参数，减少 `--security` 只数或缩短区间 |
 
-其他场景：CLI 未安装 → `npm install -g gangtise-openapi-cli`；空结果 → 扩大时间范围 / 换关键词 / 去掉部分筛选；模糊公司名匹配多只 → 列出让用户选；下载路径冲突 → 询问覆盖。
+其他场景：CLI 未安装 → `npm install -g gangtise-openapi-cli`；命令或选项报不存在、`gangtise --version` 低于本文件头部的 `version` → 跑 `gangtise update --check`，有新版就请用户运行 `gangtise update`（会一并更新本 skill 的副本）；报 `update` 命令不存在（0.49.0 之前的版本）则请用户运行 `npm install -g gangtise-openapi-cli@latest`。别自行安装；空结果 → 扩大时间范围 / 换关键词 / 去掉部分筛选；模糊公司名匹配多只 → 列出让用户选；下载路径冲突 → 询问覆盖。
 
 ## 详细参数
 

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

@@ -186,7 +186,7 @@ gangtise ai management-sentiment-detail     --source-id <id> [--source-type <typ
 - `--security`：可重复，只收具体代码（`aShares` 这类市场关键词报 `120001`），任一代码非法整批报 `120001`。**不传 = 全部证券**——按条计费，省略 `--size` 时 CLI 先取 1 条拿到总数估算，超过 1000 积分报错退出，确认后加 `--yes`
 - `--start-time` / `--end-time`：按发布时间筛，写 `yyyy-MM-dd`、`yyyy-MM-dd HH:mm:ss` 或 10 / 13 位时间戳——**写日期时间就要带秒**（`HH:mm` 报 `110001`）；只写日期的 `--end-time` 含当天整天
 - `--from` / `--size`：自动翻页（单页 100）；省略 `--size` 拉全量
-- 🔴 **返回的 `publishTime`（含 `conclusion` 里的 `previousSource.publishTime`）比北京时间早 8 小时**：北京时间 20:30 开的业绩会返回 `12:30:00`。`--start-time` / `--end-time` 按北京时间筛（`--start-time "2026-10-23 20:00:00"` 取得到这一场）。展示时刻、与纪要 / 路演按时间对齐、按日期归档前先加 8 小时——否则北京时间 0–8 点开的会会落到前一天
+- `publishTime`（含 `conclusion` 里的 `previousSource.publishTime`）是北京时间，与 `--start-time` / `--end-time` 的筛选同一口径（北京时间 20:30 开的业绩会返回 `20:30:00`，`--start-time "2026-10-23 20:00:00"` 取得到这一场）
 
 **`indicator`**：整场评分 `sentimentResponsiveness` / `sentimentPolarity` / `sentimentConviction`（0–5，两位小数）、有效问答数 `qaCount`、回避 / 风险 / 低确定度三个占比 `qaEvasionRatio` / `qaRiskRatio` / `qaUncertaintyRatio`（**百分数**：`7.14` 即 7.14%，分母是 `qaCount`），以及按问题类型拆分的 `questionCategoryList`。
 

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

@@ -108,7 +108,7 @@ gangtise fund holder-structure --security <code>... [--start-date <d>] [--end-da
 
 持有人户数、户均份额，机构 / 个人 / 员工持有份额（份）与占比（%）。只有半年报与年报披露，季报期没有行。
 
-- 🔴 **`holderCount` 是带千分位逗号的字符串**（如 `"2,219,140"`），不是数字。做数值计算或排序前先去掉逗号再转数字，否则按字符串比较会排错
+- `holderCount` 为整数（如 `2219140`）
 - 占比字段可能为 `null`
 
 ## `top10-holders` 前十大持有人
@@ -165,7 +165,11 @@ gangtise fund etf-share-change    --security <code>... [--start-date <d>] [--end
 
 - **`etf-pcf-header` / `etf-pcf-components` 只返回最新一份申购赎回清单**，无日期参数，查不了历史清单。`tradeDate` 是清单对应的交易日（清单盘前发布，可能就是当天）
 - **`etf-pcf-header`**：申赎允许情况（`允许申购·允许赎回` 这种 `·` 分隔的组合）、最小申赎单位（份）及其净值（元）、单日申购 / 赎回上限（份，无上限为 `null`）、现金差额与预估现金（元，可为负）、现金替代比例上限（%）、`componentCount` 成分记录数
-- **`etf-pcf-components`**：每个成分一行，按 `serialNumber` 排序：成分代码 `componentCode` 与名称、收盘价、涨跌幅、市值占比（%）、申购数量（股）、`cashSubstituteFlag`（`允许` / `必须`，中文）、申购 / 赎回现金替代溢价比例（%）、固定替代金额与申购 / 赎回替代金额（元）。宽基 ETF 动辄数百行，多只一起查注意 10000 行上限。`componentCode` **不带市场后缀**（如 `600519`），要接着查行情先补上后缀
+- **`etf-pcf-components`**：每个成分一行，按 `serialNumber` 排序：成分代码 `componentCode`、成分名称 `componentName`、收盘价、涨跌幅、市值占比（%）、申购数量（股）、`cashSubstituteFlag`（`允许` / `必须`，中文）、申购 / 赎回现金替代溢价比例（%）、固定替代金额与申购 / 赎回替代金额（元）。宽基 ETF 动辄数百行，多只一起查注意 10000 行上限
+  - 🔴 **`componentCode` 是 CLI 按名称匹配补上的**（接口只返回名称），带市场后缀（如 `600519.SH` / `00941.HK` / `NVDA.O` / 国债 `019848.SH`）。匹配方式：按名称找证券（先查证券列表，没有再搜索），再用该行的 `close` 核对候选证券的最新价或昨收；核对不上的（清单价格滞后于行情、停牌等），改按清单价格所属那天的收盘价核对（A 股与港股各自定日期）——A+H 型 ETF 里同名的 A 股与 H 股两行据此分开；价格定不了时（债券、停牌、除权除息当天、行情查询失败）：成分都在同一市场的 ETF 取该市场里名称完全一致的那只，同市场多只时取与 ETF 同一交易所的；**A+H 等跨市场的 ETF 里，价格定不了的行一律为 `null`**，不按名称猜
+  - **匹配不到的为 `null`**：现金行（如 `申赎现金`）、商品（如 `黄金9999`）、交易所简称与证券名称对不上的（如港股 `港交所`、`中海油`）。stderr 会说明匹配了多少行、列出为 `null` 的行
+  - ⚠️ 成分的 `close` 是清单给出的价格，日期可能早于 `tradeDate` 的前一交易日，一天之内还会更新，同一清单里 A 股与港股的日期也可能不同。要用价格计算，请以 `quote day-kline` / `quote realtime` 为准
+  - 额外请求都免费：下载一次 A 股 / 港股 / 美股证券列表（3 次请求）在本地按名称匹配，列表里没有的名称（债券、被截断的简称、现金行等）才逐个搜索，另加一两次实时行情查询；有实时价格核对不上的行时（清单价格滞后、停牌、除权除息等），再加一次日 K 查询。只要接口原始返回时加 `--no-component-code`（不发这些请求，行里没有 `componentCode`）
 - **`etf-share-change`**：逐交易日一行，份额（万份）、规模（万元）及较上期变动，`sharesChangeRate` 为份额变化率（%）。按日期倒序
 
 ---

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

@@ -34,7 +34,7 @@ gangtise indicator search --keyword <text> [--limit <n>]
 - **市场范围按指标判断**：`scopeList` 会返回实际覆盖范围，且指标之间不同；不能笼统写成每个指标都覆盖 A / 港 / 美股。覆盖面在持续扩，别把抽查结论当常量：例如 `qte_mkt_cptl`/`shr_tot` 覆盖 A/港/美股，`finc_pe_ttm` / `finc_pb_mrq` 覆盖 A/港股，`is_op_rev_ttm`/`is_shnp_ttm` 覆盖 A/港股。目标列表含任一 scope 外证券时，本批 EDE 校验不通过，应回退专用接口
 - **`scopeList[].usageRestriction`**：该指标在具体接口上的限制，`null` = 无限制。⚠️ **它是提示不是硬约束**——标着「不支持指标时间序列接口」的 `qte_vol_intvl` 调时序照样返数据、不会被拦下。当成「口径可能不对、结果别当真」看，别指望它会报错
 - ⚠️ **`scopeList` 是声明不是保证**：它可能**超前于数据**（声明覆盖但该市场暂无数据），也可能**滞后于数据**（已有数据尚未声明）。**「某某仍无数据」这类否定结论过期得和正面结论一样快**，照着它走会白白拒掉一个现在能跑的查询，而且不报错。**判断成本很低**：无数据会保留行列、给一个占位单元格，抽查一行就能看出覆盖情况；code 写错则直接报 `100003`，两种情形不会混淆。占位值统一是 `null`（详见下方「缺数据 vs 代码写错」）
-- 美股代码用交易所后缀 `.O`(NASDAQ) / `.N`(NYSE)：用 `AAPL.O`，`AAPL.US` 取不到数据
+- 美股代码用交易所后缀 `.O`(NASDAQ) / `.N`(NYSE) / `.A`(NYSE American，原 AMEX)：用 `AAPL.O`，`AAPL.US` 取不到数据
 
 ```bash
 gangtise indicator search --keyword 营业收入 --limit 10 --format json   # 做语义 + scopeList + parameterList 三项校验
@@ -49,7 +49,7 @@ gangtise indicator cross-section --indicator <code> [--indicator <code2>] \
 ```
 
 - `--indicator`（**至少 1 个**）：指标编码，来自 `search`，可重复传多个
-- `--security`（**至少 1 个**）：证券代码，如 `600519.SH`（A股）/ `09992.HK`（港股）/ `AAPL.O`（美股，用 `.O`/`.N` 后缀，非 `.US`），可重复传多个。**也接受板块 ID**（`reference sector-search` 返回的 10 位 `sectorId`，如 `1000000287` 中信白酒 → 展开成它的全部成分股），代码与板块可混传，服务端取并集去重。⚠️ 中信行业码那类 9 位 ID（`100800109`）**不是** `sectorId`，传进去返 0 只
+- `--security`（**至少 1 个**）：证券代码，如 `600519.SH`（A股）/ `09992.HK`（港股）/ `AAPL.O`（美股，用 `.O`/`.N`/`.A` 后缀，非 `.US`），可重复传多个。**也接受板块 ID**（`reference sector-search` 返回的 10 位 `sectorId`，如 `1000000287` 中信白酒 → 展开成它的全部成分股），代码与板块可混传，服务端取并集去重。⚠️ 中信行业码那类 9 位 ID（`100800109`）**不是** `sectorId`，传进去返 0 只
 - `--date`（**必选**）：数据日期 `yyyy-MM-dd`。**CLI 把它下发为每个指标各自的 `tradeDate`**（接口没有根级 date）。日期语义按指标分两类——财务报表指标=报告期末（可为非交易日；**⚠️ `_ttm` 后缀整族例外，走交易日，见下方「日期路由」**）、`finc_pe_ttm` / `finc_pb_mrq` 等日频估值=交易日（详见下方「日期路由」）
   - `--date` 必填：绝大多数指标必填 `tradeDate`，漏传服务端报 `100001` 并点名缺哪个参数，所以 CLI 要求带上、下发给每个指标。（`screener` 的 `--date` 也必填，同理）
   - 🔴 **判据一句话：该指标的 `parameterList` 里有 `tradeDate` 就不用管；没有，`--date` 下发的 `tradeDate` 就可能被拒。** 按这条走，四种情形四种写法（`parameterList` 从 `indicator search --keyword <code> --format json` 读，别按 code 前缀推断）：

package/gangtise-openapi/references/errors.md

@@ -76,7 +76,7 @@
 `partial: true`，保留已取到的部分；stderr 有 warning，`--format json` 才看得见标记，table/csv/jsonl 只有数据行、看不出问题。**拿到 3 就必须告知用户缺了哪段，不能当成功静默继续。**
 
 - 触发场景：翻页 / K 线分片有页失败、服务端返回行数与 `total` 矛盾（提前短页）、`total` 撞服务端上限（`totalCapped`：`total` 是封顶值而非真实条数，或正好等于偏移窗口、窗口外的行取不到也数不到）、`quote` 系带 `--field` 时请求了但服务端没回的列（`missingFields`）。附带定位字段：页失败 `failedPages`；分片失败 `failedShards`、分片撞行数上限 `truncatedShards`（均带日期区间可缩窗补拉）、只有部分分片返回的列 `droppedColumns`（合并结果的列集取自第一个有数据的分片，多出来的列放不下，需要就缩小日期区间单独拉）；缺列 `missingFields`（字段名写错或已下线，按 `references/fields.md` 核对）；多证券分批请求里撞行数上限的证券 `truncatedSecurities`；翻页时同一行在相邻两页各出现一次 `duplicateRows`（列表按时间这类可重复的字段排序，同一时刻的一组数据跨在页边界上时，重复了几行也就漏了几行；重复行已去掉，缩短时间范围重拉可补齐）；同一 ID 在后面的页以不同内容再次出现 `changedRows`（翻页期间列表有变动、也可能漏了行；两版都保留，按 ID 去重只留一版，重拉即可；重拉后仍在同一处出现，说明该列表同一 ID 对应多条记录，按 ID 去重前先核对）。EDE 的 `omittedIndicators` / `omittedSecurities`：服务端对写错的 code 直接报 `100003`（退出 1），所以这两个标记很少出现
-- **EDE 代码写错是退出码 1 + `100003`，msg 里直接点名是哪个 code**（美股后缀用 `.O`/`.N`，不是 `.US`），不用从退出码 3 反推。真的没覆盖是占位单元格（统一 `null`）+ 退出码 0
+- **EDE 代码写错是退出码 1 + `100003`，msg 里直接点名是哪个 code**（美股后缀用 `.O`/`.N`/`.A`，不是 `.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_*` 融资融券系列）。②③ 都要靠单查一行确认，不能只改日期
 
 ## 退出码 4：数据写全了，但文件被另一次导出替换

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

@@ -4,7 +4,7 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 
 > 例外：`indicator`（EDE）四个接口（`search` / `cross-section` / `time-series` / `screener`）成功时**双层信封**（`data` 里再裹一层 `{code, status, data}`）。内层字段名为 `securityCodeList` / `securityNameList` / `indicatorList[{code,name,dataType}]`（screener 另带 `field`），`values` 是 2D 矩阵：**截面与 screener 为 `[证券][指标]`**、时序为 `[序列][日期]`。
 >
-> **缺数据 vs 代码写错**：无数据 / 无覆盖一律保留行列并给占位单元格——**占位值统一为 `null`**；⚠️ 报告期类指标（`is_*`）的时序只有报告期末那几行是真值，其余全是 `null`，详见 `commands/indicator.md`。**代码写错则直接报 `100003` 并点名**（指标 code 拼错 →「指标 xxx 不存在」；证券 code 后缀错 →「xxx 不是有效证券或者板块ID」，美股是 `.O`/`.N` 不是 `.US`），**无论同批有没有正确的 code 都会报**。CLI 的 `indicator` 子命令已二次解包、拍平成宽表；服务端没有返回请求里的某个指标或证券时标 `partial` + `omittedIndicators` / `omittedSecurities`、退出码 3（写错的 code 会直接报 `100003`，所以这种情况很少出现）。**`screener` 例外**：把缺列的变量当作无法求值，按表达式的**布尔结构**判断是否还有分支能成立（`A && B` 要两边、`A || B` 只要一边）。一条都不剩 → **退出码 1 且不输出**（那些行以「通过了该条件」的名义呈现，而条件根本无法证明被执行过）；仍有分支可求值、或缺的只是输出用的辅助变量 → `partial` + 退出码 3。直接 `raw call indicator.*` 只会剥外层，内层需自行处理。
+> **缺数据 vs 代码写错**：无数据 / 无覆盖一律保留行列并给占位单元格——**占位值统一为 `null`**；⚠️ 报告期类指标（`is_*`）的时序只有报告期末那几行是真值，其余全是 `null`，详见 `commands/indicator.md`。**代码写错则直接报 `100003` 并点名**（指标 code 拼错 →「指标 xxx 不存在」；证券 code 后缀错 →「xxx 不是有效证券或者板块ID」，美股是 `.O`/`.N`/`.A` 不是 `.US`），**无论同批有没有正确的 code 都会报**。CLI 的 `indicator` 子命令已二次解包、拍平成宽表；服务端没有返回请求里的某个指标或证券时标 `partial` + `omittedIndicators` / `omittedSecurities`、退出码 3（写错的 code 会直接报 `100003`，所以这种情况很少出现）。**`screener` 例外**：把缺列的变量当作无法求值，按表达式的**布尔结构**判断是否还有分支能成立（`A && B` 要两边、`A || B` 只要一边）。一条都不剩 → **退出码 1 且不输出**（那些行以「通过了该条件」的名义呈现，而条件根本无法证明被执行过）；仍有分支可求值、或缺的只是输出用的辅助变量 → `partial` + 退出码 3。直接 `raw call indicator.*` 只会剥外层，内层需自行处理。
 
 ## 通用模式（5 类）
 
@@ -27,7 +27,7 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | 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` |
 | insight pamirs-summary download | 文件路径（stdout） | — |
-| insight roadshow / site-visit / strategy / forum list | `{list, total}` | `list[].id` / `list[].title` / `list[].publishTime` / `list[].institution.institutionName` |
+| insight roadshow / site-visit / strategy / forum list | `{list, total}` | 各自的 ID：`list[].roadshowId` / `siteVisitId` / `strategyMeetingId` / `forumId`；`list[].title` / `list[].startTime` / `list[].endTime` / `list[].publishTime` / `list[].location`；路演、调研、策略会另有 `list[].institutionList[]{institutionId, institutionName}`（论坛没有） |
 | insight research list | `{list, total}` | `list[].reportId` / `list[].title` / `list[].brief`（全文摘要） / `list[].publishTime` / `list[].publisher.brokerName` / `list[].securityList[].rating` |
 | insight research download | 文件路径（stdout） | — |
 | insight foreign-report list | `{list, total}` | `list[].reportId` / `list[].title` / `list[].titleTranslate` / `list[].brief` / `list[].briefTranslate`（中译全文摘要） / `list[].publishTime` / `list[].publisher.brokerName` |
@@ -113,11 +113,11 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | fund fee-rate | 同上 | `[].fundCode` / `feeType` / `feeCondition`（分档条件，无分档为 `null`）/ `feeRate`（**字符串**，如 `"1.5%"`） |
 | fund manager-info | 同上 | `[].managerName` / `currentCompany` / `careerStartDate` / `workingYears` / `managedFundScale`（亿元）/ `managedFundCount` / `historyFundCount` / `introduction`；同名经理多行 |
 | fund manager-history | 同上 | `[].fundCode` / `managerName` / `startDate` / `endDate`（`null` = 现任）/ `managedDays` / `managedReturn`（%） |
-| fund asset-size / holder-structure / top10-holders | 同上，每报告期一行（`top10-holders` 每期按名次多行） | `[].fundCode` / `reportDate` + 规模（`sharesEnd` / `netAsset`，万份 / 万元）、持有人结构（`holderCount` 是**带千分位的字符串** / `pctInstitution` / `pctIndividual`）、前十大（`serialNumber` / `holderName` / `holdingShares` / `holdingPct`） |
+| fund asset-size / holder-structure / top10-holders | 同上，每报告期一行（`top10-holders` 每期按名次多行） | `[].fundCode` / `reportDate` + 规模（`sharesEnd` / `netAsset`，万份 / 万元）、持有人结构（`holderCount` 整数 / `pctInstitution` / `pctIndividual`）、前十大（`serialNumber` / `holderName` / `holdingShares` / `holdingPct`） |
 | fund asset-allocation | 同上，每报告期按资产类型多行 | `[].fundCode` / `reportDate` / `assetLevel` / `assetType` / `assetTypeName` / `holdingValue`（元）/ `pctToTotalAsset` |
 | fund stock-portfolio / bond-portfolio / fund-portfolio | 同上，每报告期按持仓多行 | `[].fundCode` / `reportDate` / `stockName` · `bondName` · `holdingFundName`（**只有简称、无代码**）/ `holdingQuantity` / `holdingValue`（万元）/ `pctToNav`；股票另有 `pctToFloatShares` / `pctToNavChg` |
 | fund industry-allocation / bond-type-allocation / fund-type-allocation | 同上，每报告期按分类多行 | `[].fundCode` / `reportDate` / `industryCode` + `industryName` · `bondTypeCode` + `bondTypeName` · `investTypeCodeLevel1` + `investTypeNameLevel1` / `pctToNav`；行业与基金类型另有 `positionType`（`top` / `all`） |
-| fund etf-pcf-header / etf-pcf-components / etf-share-change | 同上 | 申赎参数（`tradeDate` / `purchaseRedemptionStatus` / `minUnitShares` / `cashBalance` / `componentCount`）；成分清单（`serialNumber` / `componentCode` / `componentName` / `pctWeight` / `purchaseQuantity` / `cashSubstituteFlag`）；份额变动（`tradeDate` / `shares` / `sharesChange` / `scale`，万份 / 万元） |
+| fund etf-pcf-header / etf-pcf-components / etf-share-change | 同上 | 申赎参数（`tradeDate` / `purchaseRedemptionStatus` / `minUnitShares` / `cashBalance` / `componentCount`）；成分清单（`serialNumber` / `componentCode`（CLI 按名称匹配补上，匹配不到为 `null`，见 `commands/fund.md`）/ `componentName` / `pctWeight` / `purchaseQuantity` / `cashSubstituteFlag`）；份额变动（`tradeDate` / `shares` / `sharesChange` / `scale`，万份 / 万元） |
 | 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.48.0",
+  "version": "0.49.0",
   "description": "CLI for Gangtise OpenAPI",
   "license": "MIT",
   "repository": {