gangtise-openapi-cli 0.28.2 → 0.29.0

package/README.md

@@ -4,6 +4,35 @@
 
 ## Changelog
 
+### v0.29.0 — 2026-07-25
+
+对齐服务端 2026-07-24 更新：新增财报日历（列表 + 原文下载）与 PDF 解析工具，群消息补 `quoteMsg` 引用字段。
+
+**新增**
+- `insight performance-calendar list` — 财报日历：业绩预告 / 业绩快报 / 业绩公告三类事件，按 `--start-date`/`--end-date`（过滤 `publishDate`）、`--market`、`--security`、`--category` 筛选，自动翻页（单页上限 50）。**它是唯一按 `--*-date` 过滤的 insight list**（其余用 `--start-time`）；`--market` / `--category` 拼错本地直接报错，不会静默返全量。**全表 >12 万条（0.1/条），裸跑会被本地拦下**——必须给一个约束：日期范围、`--security` 或显式 `--size`；`--security` 作为唯一约束时另加 1000 行隐式上限（**仅当 `total` 显示还有未取行时**才标 `partial` + 退出码 3——恰好取满 1000 行且 total 也是 1000 属完整结果，不会误报）
+- `insight performance-calendar download --performance-report-id <id>` — 下载业绩报告原文 PDF（A股 10 积分 / 港美股 20 积分）；仅 `hasAttachment: true` 的记录可下。省略 `--output` 时沿用标题命名
+- `gangtise tool file-parse --file <x.pdf>` — PDF 解析（异步）：上传拿 `taskId`，`--wait` 阻塞轮询（≈316s 预算）直接落盘结果 ZIP（内含 `file.md` + `images/`）；不带 `--wait` 时用 `gangtise tool file-parse-check --task-id <id>` 取结果。**0.8 积分/页，提交时一次性扣费**，取结果免费。本地先校验 PDF 后缀 / 非空 / ≤100MB 再上传；提交端点标 `no-replay`（超时不重放，防重复扣分），单请求超时下限 300s
+
+**变更**
+- 群消息 `vault wechat-message-list` 返回新增 `quoteMsg`（`quoteMsgId` / `quoteContent` / `quoteUrl`，无引用时为 `null`）。**同时修正随包 skill 里写错的字段名**：正文字段是 `content`、链接是 `url`（旧文档写作 `msgContent` / `contentUrl`，实测 2026-07-25 不存在）
+- `raw call` 现在允许对 POST 型 download 端点传 `--body`（file-parse 取结果用），GET 型仍只收 `--query`；upload 型端点（`tool.file-parse.submit`）明确报错并指向 `tool file-parse`
+- 新增 `EndpointDefinition.bigIntFields`：解析响应前把指定字段的裸数字重新加引号，防止雪花 ID 被 `JSON.parse` 丢位（`1782345678901234567` → `…4700`）。file-parse 的 `taskId` 实测返回字符串、当前不受影响，属前向防护——ID 丢位=已扣费的解析任务取不回结果
+- `--verbose` 的下载日志改用端点真实 method（此前一律打印 `GET`）
+
+### v0.28.3 — 2026-07-24
+
+🔴 **数据完整性修复**：`--field` 传错字段名会导致**静默错列**（值贴到错误的字段上）。
+
+**修复**
+- 列式响应（`{fieldList, list}`）拍平时校验字段数与行长度，不匹配直接报错（`ValidationError`，退出码 1），不再输出错位数据。上游对不存在的字段名有两套处理：`day-kline` / `minute-kline` / `fund-flow` 名值同丢、三大报表补 `null`（长度相等，安全）；但 **`quote realtime` / `fundamental main-business` / `valuation-analysis` 只丢值、字段名照请求回显**——实测 `quote realtime --field securityCode --field close --field turnoverRate`（realtime 根本没有 `close`）把换手率 `28.5573` 拍成了 `close`，茅台真实价 1297.41。不报错、数字看着合理、却完全是另一个指标。`alternative edb-data` 的同款拍平一并纳入校验
+
+**文档（随包 skill）**
+- SKILL.md 必备规则加第 10 条：`--field` 不确定就别传；`quote realtime` **无 `close`**（用 `latestPrice`）、**无市值**（总市值走 `indicator cross-section --indicator qte_mkt_cptl`，仅 A 股）
+- `quote realtime` 补全 16 个实测字段（此前 `fields.md` 漏 `turnoverRate` / `volumeRatio`）；`valuation-analysis` 标注只有 7 个字段、无 `securityCode`（误传会拿到一列重复的 `tradeDate`，长度相等拦不住）
+- **推翻 07-23 关于 EDE `reportType` 的结论**（复测 2026-07-24）：旧文档写「枚举不可信、`value=2/4` 直接 `999999`、指定口径请改用 `fundamental --report-type`」。实测是 label 与 value **错位但映射稳定**：`1`=合并（默认）、`2`=合并(调整)、`3`=母公司、`4`=母公司(调整)，四值与三大报表逐一对得上；`2`/`4` 为空只是该报告期尚无调整表。**EDE 可以指定口径——母公司传 `3`，合并省略即可**
+- 修正 `response-schema.md` 里会**反向诱导传错字段**的陈旧记录：`main-business` 行原写 `endDate` / `breakdownName` / `revenue`（实测均不存在），改为真实的 `periodName` / `periodEndDate` / `categoryName` + `opRevenue` / `grossProfit` 等 15 个字段
+- 标注上游 meta 字段错位（实测边界）：**A 股累计口径的 `balance-sheet` / `cash-flow`** 的 `companyType` 与 `currency` 值互换（`companyType=人民币`、`currency=银行`），A 股 `income-statement`、港股/美股三表均正确；A 股 `*-quarterly` 单季表另有 `companyType` 返回未映射数字码（`102119999`）的问题——读这两列按值判断语义，科目数字不受影响
+
 ### v0.28.2 — 2026-07-24
 
 EDE 指标批量取数优化（基于对上游 990 个指标的实测）。
@@ -31,6 +60,7 @@ Agent Skill 文档取数路由对齐（对齐 gangtise-mcp 0.1.46）：多证券
 **实测校正（2026-07-23）**
 - `scope` 字段更正为 `scopeList[].market/.securityType`（服务端已返回实际覆盖），覆盖按指标而异：`finc_pe_ttm`/`finc_pb_mrq` 仅 A 股、`is_op_rev` A 股+港股，均不含美股；`valuation-analysis`/`earning-forecast` 仅 A 股
 - `finc_pb_mrq`(市净率 MRQ) 只在报告期末打值（交易日取 `null`），非日频；EDE 财务指标 `reportType` 枚举 label 与实测取数不符（`value=2/4` 直接 `999999`），要指定报表口径改用 `fundamental` 三大报表 `--report-type`
+  - ⚠️ **本条 `reportType` 结论已被 v0.28.3 复测推翻，勿据此路由**：实际是 `1`=合并 / `2`=合并(调整) / `3`=母公司 / `4`=母公司(调整)，EDE 可直接指定口径，见上方 v0.28.3 条目（`finc_pb_mrq` 部分仍成立）
 
 ### v0.28.0 — 2026-07-21
 
@@ -290,6 +320,7 @@ cp -r "$SKILL_SRC" ~/.hermes/skills/gangtise-openapi
 | | `site-visit list` | 调研 |
 | | `strategy list` | 策略 |
 | | `forum list` | 论坛 |
+| | `performance-calendar list` / `download` | 财报日历（业绩预告/快报/公告，含原文 PDF 下载） |
 | | `research list` / `download` | 研报（含 Markdown 下载） |
 | | `foreign-report list` / `download` | 外资研报（含中文翻译下载） |
 | | `announcement list` / `download` | A股公告（含 Markdown 下载） |
@@ -348,7 +379,8 @@ cp -r "$SKILL_SRC" ~/.hermes/skills/gangtise-openapi
 | | `edb-data` | 行业指标时序数据（批量拉取，最多10个指标） |
 | | `concept-info` | 题材指数基本信息（投资逻辑/行业空间/竞争格局/催化事件） |
 | | `concept-securities` | 题材指数成分股（题材深度F8，按分组，标记重点个股） |
-| **Raw** | `call` | 原始接口调用（可访问任意 endpoint） |
+| **Tool** | `file-parse` / `file-parse-check` | PDF 解析为 Markdown + 图片（异步，返回 ZIP） |
+| **Raw** | `call` | 原始接口调用（可访问任意 JSON / download endpoint；upload 型如 `tool.file-parse.submit` 需走 `tool file-parse`，raw 带不了文件） |
 
 ## 命令概览
 
@@ -362,6 +394,7 @@ cp -r "$SKILL_SRC" ~/.hermes/skills/gangtise-openapi
 - `gangtise indicator ...`
 - `gangtise alternative ...`
 - `gangtise reference ...`
+- `gangtise tool ...`
 - `gangtise raw call ...` / `gangtise raw list`
 
 ## 推荐工作流
@@ -410,6 +443,7 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 - `insight site-visit list`
 - `insight strategy list`
 - `insight forum list`
+- `insight performance-calendar list`
 - `insight research list`
 - `insight foreign-report list`
 - `insight announcement list`
@@ -438,7 +472,7 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 
 ## 智能文件命名
 
-下载命令（`summary download`、`research download`、`foreign-report download`、`announcement download`、`announcement-hk download`、`announcement-us download`、`official-account download`、`vault drive-download`、`vault record-download`、`vault my-conference-download`）省略 `--output` 时，自动使用真实标题作为文件名：
+下载命令（`summary download`、`research download`、`foreign-report download`、`announcement download`、`announcement-hk download`、`announcement-us download`、`official-account download`、`performance-calendar download`、`vault drive-download`、`vault record-download`、`vault my-conference-download`）省略 `--output` 时，自动使用真实标题作为文件名：
 
 1. **缓存优先** — 如果之前执行过对应的 `list` 命令，标题已缓存在 `~/.config/gangtise/title-cache.json`，直接使用，无额外 API 调用
 2. **API 回查** — 缓存未命中时，自动查询最近 200 条记录匹配标题
@@ -515,6 +549,12 @@ gangtise insight report-image download --chunk-id image_10_384655917758685184_8
 
 # 纪要下载（会议平台来源可选 HTML 格式）
 gangtise insight summary download --summary-id 4906813 --file-type 2
+
+# 财报日历：注意用 --start-date/--end-date（按 publishDate 过滤），不是 --start-time
+gangtise insight performance-calendar list --start-date 2026-07-01 --end-date 2026-07-25 \
+  --market aShares --category performanceForecast --size 20 --format json
+# 下载业绩报告原文（仅 hasAttachment: true 的记录；A股 10 积分 / 港美股 20 积分）
+gangtise insight performance-calendar download --performance-report-id 33753017 --output ./业绩预告.pdf
 ```
 
 ### Reference
@@ -749,6 +789,19 @@ gangtise alternative concept-info --concept-id 121000130 --format json
 gangtise alternative concept-securities --concept-id 121000130 --format json
 ```
 
+### Tool（PDF 解析）
+
+```bash
+# 一步到位：上传 → 阻塞等待 → 结果 ZIP 落盘（含 file.md + images/）
+gangtise tool file-parse --file ./研报.pdf --wait --output ./研报.zip
+
+# 分两步：先提交拿 taskId（此时按页扣费 0.8/页），约 3 分钟后取结果（免费）
+gangtise tool file-parse --file ./研报.pdf
+gangtise tool file-parse-check --task-id 829081108954501120 --output ./研报.zip
+```
+
+限制：单文件 ≤100MB、≤500 页，同一用户最多 10 个并发任务；未就绪时 `file-parse-check` 输出 `{"status":"pending"}`（退出码 0），重试即可，不会重复扣费。
+
 ### Raw
 
 ```bash

package/dist/src/cli.js

@@ -10,7 +10,8 @@ import { loadConfig } from "./core/config.js";
 import { resolveTitle, saveDownloadResult, uniquePath } from "./core/download.js";
 import { ENDPOINTS, listEndpoints } from "./core/endpoints.js";
 import { ApiError, ConfigError, ValidationError } from "./core/errors.js";
-import { normalizeRows } from "./core/normalize.js";
+import { fetchFileParseResult, pollFileParseResult, submitFileParse } from "./core/fileParse.js";
+import { normalizeRows, zipFieldRow } from "./core/normalize.js";
 import { parseOutputFormat } from "./core/output.js";
 import { printData } from "./core/printer.js";
 // --- Lazy-loaded modules (deferred to action handlers) ---
@@ -69,11 +70,11 @@ function flagIfLimitTruncated(data, cap, label) {
  */
 async function runDownload(client, endpointKey, query, options) {
     if (options.output) {
-        const result = await client.call(endpointKey, undefined, query, { streamTo: options.output });
+        const result = await client.call(endpointKey, options.body, query, { streamTo: options.output });
         await saveDownloadResult(result, options.fallbackName, options.output);
         return;
     }
-    const result = await client.call(endpointKey, undefined, query);
+    const result = await client.call(endpointKey, options.body, query);
     const resolved = options.resolveOutputPath ? await options.resolveOutputPath(result) : undefined;
     // Title-derived names are auto-generated too — dedupe them like the fallback names.
     await saveDownloadResult(result, options.fallbackName, resolved ? await uniquePath(resolved) : undefined);
@@ -161,6 +162,7 @@ const roadshow = new Command("roadshow");
 const siteVisit = new Command("site-visit");
 const strategy = new Command("strategy");
 const forum = new Command("forum");
+const performanceCalendar = new Command("performance-calendar");
 const research = new Command("research");
 const foreignReport = new Command("foreign-report");
 const announcement = new Command("announcement");
@@ -235,6 +237,79 @@ addScheduleList(siteVisit, "insight.site-visit.list", {
 });
 addScheduleList(strategy, "insight.strategy.list", { institution: true, location: true });
 addScheduleList(forum, "insight.forum.list", { researchArea: true, location: true });
+// Earnings calendar: the only insight list filtered by DATE (--start-date/--end-date
+// on publishDate), not by the --start-time datetime every sibling uses — so it does
+// not go through addTimeFilters. It also takes no --keyword / --rank-type / --search-type.
+/** Row ceiling applied when `--security` is the only thing bounding a
+ * performance-calendar fetch. Far above any single company's calendar (a whole
+ * A-share history is dozens of rows), far below the 50k the auto-pagination
+ * would otherwise pull if the server ever stopped honoring securityList. */
+const SECURITY_ONLY_ROW_CAP = 1000;
+/** Warn + mark partial when a `--security`-only fetch lands on the cap with rows
+ * still unfetched: that is the signature of a filter that did not narrow anything,
+ * and the rows on screen are then a truncated slice of the whole calendar rather
+ * than a company's. `total` decides it — a result that happens to be exactly `cap`
+ * rows long IS complete (from + rows covers total) and must stay exit 0, or every
+ * automated caller reads a full answer as truncated. */
+function flagIfImplicitCapHit(data, cap, from) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const rec = data;
+    if (!Array.isArray(rec.list) || rec.list.length < cap)
+        return;
+    const total = typeof rec.total === "number" ? rec.total : undefined;
+    if (total !== undefined && from + rec.list.length >= total)
+        return;
+    rec.partial = true;
+    process.stderr.write(`[gangtise] warning: --security was the only bound, so the fetch was capped at ${cap} rows and more remain (total=${String(rec.total)}) — the filter may not have narrowed anything. Re-run with --start-date/--end-date or an explicit --size.\n`);
+}
+const PERFORMANCE_MARKETS = ["aShares", "hkStocks", "usChinaConcept", "usStocks"];
+const PERFORMANCE_CATEGORIES = ["performanceForecast", "performanceExpress", "performanceAnnouncement"];
+performanceCalendar.command("list").description("Earnings calendar (业绩预告 / 快报 / 公告)")
+    .option("--from <number>", "Starting offset", "0")
+    .option("--size <number>", "Total rows to return; omit to fetch all")
+    .option("--start-date <date>", "Start date (yyyy-MM-dd), filters publishDate", dateArg("--start-date"))
+    .option("--end-date <date>", "End date (yyyy-MM-dd), filters publishDate", dateArg("--end-date"))
+    .option("--security <code>", "Security code (e.g. 000001.SZ)", collectList, [])
+    .option("--market <name>", `Market: ${PERFORMANCE_MARKETS.join("/")}`, collectList, [])
+    .option("--category <name>", `Event type: ${PERFORMANCE_CATEGORIES.join("/")}`, collectList, [])
+    .option("--format <format>", "Output format", "table").option("--output <path>", "Output path")
+    .action((options) => {
+    // Enum typos first: a misspelled --category is the likelier mistake, and its
+    // message is the more useful one when both checks would fire.
+    const marketList = parseChoiceList(options.market, "--market", PERFORMANCE_MARKETS);
+    const categoryList = parseChoiceList(options.category, "--category", PERFORMANCE_CATEGORIES);
+    // Unfiltered, this endpoint holds >120k rows (probed 2026-07-25: 126683, it
+    // also carries FUTURE scheduled events) and an omitted --size means "fetch
+    // everything" — 50k rows at the 1000-page cap, ~5000 credits at 0.1/row.
+    // Require a bound: a full date range, an explicit --size, or a security filter.
+    const explicitlyBounded = Boolean(options.size) || Boolean(options.startDate && options.endDate);
+    if (!explicitlyBounded && !options.security.length) {
+        throw new ValidationError("insight performance-calendar list without a bound would auto-paginate the whole calendar (>120k rows at 0.1 credits each): pass --start-date and --end-date, or --security, or an explicit --size");
+    }
+    // --security is only a real bound while the server honors securityList. It does
+    // today (probed 2026-07-25: an unknown or malformed code returns total 0, it is
+    // not silently ignored like a bad enum) — but a five-figure credit bill must not
+    // rest on that staying true. When --security is the ONLY bound, cap the fetch:
+    // one company's whole calendar is dozens of rows, so the cap is invisible in
+    // normal use and turns a filter regression into a truncated result (partial +
+    // exit 3) instead of a 5000-credit pull.
+    const implicitCap = explicitlyBounded ? undefined : SECURITY_ONLY_ROW_CAP;
+    const from = parseFrom(options.from);
+    return emit(options, async (client) => {
+        const data = await client.call("insight.performance-calendar.list", {
+            from, size: parseSize(options.size) ?? implicitCap,
+            startDate: options.startDate, endDate: options.endDate,
+            marketList,
+            securityList: maybeArray(options.security),
+            categoryList,
+        });
+        if (implicitCap)
+            flagIfImplicitCapHit(data, implicitCap, from);
+        return data;
+    }, { endpointKey: "insight.performance-calendar.list", idField: "performanceReportId" });
+});
+addDownloadCommand(performanceCalendar, { endpointKey: "insight.performance-calendar.download", idOption: "--performance-report-id", idField: "performanceReportId", fallbackPrefix: "performance-calendar", titleListEndpoint: "insight.performance-calendar.list" });
 addTimeFilters(research.command("list").option("--search-type <number>", "Search type: 1=title 2=fulltext", "1").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--broker <id>", "Broker ID", collectList, []).option("--security <code>", "Security code", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--category <name>", "Report category", collectList, []).option("--llm-tag <tag>", "Semantic tag", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--min-pages <number>", "Min report pages").option("--max-pages <number>", "Max report pages").option("--source <type>", "Source type", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.research.list", {
     from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword,
     searchType: parseNumberOption(options.searchType, "--search-type", { integer: true, min: 1 }), rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }),
@@ -331,6 +406,7 @@ insight.addCommand(roadshow);
 insight.addCommand(siteVisit);
 insight.addCommand(strategy);
 insight.addCommand(forum);
+insight.addCommand(performanceCalendar);
 insight.addCommand(research);
 insight.addCommand(foreignReport);
 insight.addCommand(announcement);
@@ -612,10 +688,8 @@ alternative.command("edb-data").option("--indicator-id <id>", "Indicator ID (rep
     });
     let data = raw;
     if (raw && Array.isArray(raw.fieldList) && Array.isArray(raw.dataList)) {
-        const list = raw.dataList.map((row) => raw.fieldList.reduce((acc, field, i) => {
-            acc[field] = row[i];
-            return acc;
-        }, {}));
+        const fields = raw.fieldList;
+        const list = raw.dataList.map((row) => zipFieldRow(fields, row, raw));
         data = { list, total: list.length };
     }
     await printData(data, format, options.output);
@@ -643,6 +717,35 @@ indicator.command("time-series").option("--indicator <code>", "Indicator code, e
     await printData(flattenTimeSeries(unwrapIndicatorData(raw), options.keyBy), format, options.output);
 }));
 program.addCommand(indicator);
+const tool = new Command("tool").description("Research tool APIs: PDF parsing");
+tool.command("file-parse").description("Parse a PDF into Markdown + images (async; 0.8 credits/page, billed at submit)")
+    .requiredOption("--file <path>", "PDF to upload (max 100MB / 500 pages)")
+    .option("--wait", "Wait for the parse to finish and save the result ZIP (blocking, up to ~5 min)")
+    .option("--output <path>", "Where to save the result ZIP (used with --wait)")
+    .action((options) => withClient(async (client) => {
+    const taskId = await submitFileParse(client, options.file);
+    if (!options.wait) {
+        process.stderr.write(`File parse task submitted. taskId: ${taskId}\n`);
+        process.stdout.write(`${JSON.stringify({ taskId, status: "pending", hint: `Run 'gangtise tool file-parse-check --task-id ${taskId}' in ~3 minutes to download the result ZIP` })}\n`);
+        return;
+    }
+    process.stderr.write(`Got taskId: ${taskId}, waiting for the parse to finish...\n`);
+    if (await pollFileParseResult(client, taskId, options.output) !== "ok") {
+        // Fetching the result is free and the task keeps running server-side —
+        // re-checking later costs nothing, resubmitting re-bills the whole file.
+        process.stderr.write(`Parse result not available after ${POLL_MAX_ATTEMPTS} attempts. Try again later with: gangtise tool file-parse-check --task-id ${taskId}\n`);
+        process.exitCode = 1;
+    }
+}));
+tool.command("file-parse-check").description("Download a finished file-parse result ZIP by taskId (free)")
+    .requiredOption("--task-id <id>", "taskId from 'tool file-parse'")
+    .option("--output <path>", "Where to save the result ZIP")
+    .action((options) => withClient(async (client) => {
+    if (await fetchFileParseResult(client, options.taskId, options.output) === "pending") {
+        process.stdout.write(`${JSON.stringify({ taskId: options.taskId, status: "pending", hint: "Parse not finished yet, retry in ~1 minute" })}\n`);
+    }
+}));
+program.addCommand(tool);
 program.command("raw").description("Raw API calls").addCommand(new Command("call").argument("<endpointKey>").option("--body <json>").option("--query <key=value>", "Query string pair", collectKeyValue, {}).option("--format <format>", "Output format", "json").option("--output <path>").action(async (endpointKey, options) => {
     const endpoint = ENDPOINTS[endpointKey];
     if (!endpoint) {
@@ -662,12 +765,15 @@ program.command("raw").description("Raw API calls").addCommand(new Command("call
     // Fail loudly on arguments the endpoint kind can't use — they used to be
     // silently dropped, leaving the user to puzzle over server-side errors.
     if (endpoint.kind === "download") {
-        if (body !== undefined) {
-            throw new ValidationError(`--body is not supported for download endpoints (use --query key=value); ${endpointKey} is kind=download`);
+        // POST download endpoints (file-parse result) take their parameters as a JSON
+        // body; GET ones take --query and can't carry a body at all.
+        if (body !== undefined && endpoint.method !== "POST") {
+            throw new ValidationError(`--body is not supported for GET download endpoints (use --query key=value); ${endpointKey} is kind=download`);
         }
         await runDownload(client, endpointKey, options.query, {
             output: options.output,
             fallbackName: "download.bin",
+            body,
         });
         return;
     }

package/dist/src/core/asyncContent.js

@@ -5,7 +5,7 @@ import { isTransientError } from "./transport.js";
 export const POLL_MAX_ATTEMPTS = 14;
 const POLL_INITIAL_DELAY_MS = 5_000;
 const POLL_MAX_DELAY_MS = 30_000;
-function nextDelayMs(attempt) {
+export function nextPollDelayMs(attempt) {
     // 5s, 8s, 13s, 20s, 30s, 30s, ...
     const grown = POLL_INITIAL_DELAY_MS * 1.6 ** (attempt - 1);
     return Math.min(POLL_MAX_DELAY_MS, Math.round(grown));
@@ -19,7 +19,9 @@ function nextDelayMs(attempt) {
 // recognize the pending code aborts the poll on a job already billed 50 credits.
 const PENDING_CODES = new Set(["410110", "140001"]);
 const FAILED_CODES = new Set(["410111", "140002"]);
-function isAsyncPending(error) {
+/** Shared by the AI content endpoints and `tool file-parse` — both report
+ * "still generating" with the same codes. */
+export function isAsyncPending(error) {
     return error instanceof ApiError && error.code !== undefined && PENDING_CODES.has(error.code);
 }
 function isAsyncFailed(error) {
@@ -66,7 +68,7 @@ export async function pollAsyncContent(client, getContentEndpoint, dataId, forma
             }
         }
         if (attempt < POLL_MAX_ATTEMPTS) {
-            const delay = nextDelayMs(attempt);
+            const delay = nextPollDelayMs(attempt);
             process.stderr.write(`Attempt ${attempt}/${POLL_MAX_ATTEMPTS}: content not ready, retrying in ${Math.round(delay / 1000)}s...\n`);
             await new Promise(resolve => setTimeout(resolve, delay));
         }

package/dist/src/core/client.js

@@ -2,12 +2,12 @@ import { createWriteStream } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pipeline } from "node:stream/promises";
-import { request } from "undici";
+import { FormData, request } from "undici";
 import { isTokenCacheValid, normalizeToken, readTokenCache, requireAccessCredentials, writeTokenCache } from "./auth.js";
 import { ApiError, attachEnvelopeTraceId, ValidationError } from "./errors.js";
 import { ENDPOINTS, resolveTimeoutMs } from "./endpoints.js";
 import { getLookupData } from "./lookupData/index.js";
-import { decodeResponseBody, getDispatcher, isVerbose, logTiming, markRetryable, PAGE_CONCURRENCY, parseRetryAfterMs, runWithConcurrency, withRetry } from "./transport.js";
+import { decodeResponseBody, getDispatcher, isVerbose, logTiming, markRetryable, PAGE_CONCURRENCY, parseRetryAfterMs, quoteBigIntFields, runWithConcurrency, withRetry } from "./transport.js";
 // Auth errors that warrant a forced re-login + one replay: the token was rejected
 // server-side while still looking valid by local expiry, so only a forced refresh
 // recovers it. 0000001008 is the legacy code (probed 2026-07-20: still what the
@@ -343,12 +343,17 @@ export class GangtiseClient {
         const authState = { retried: false };
         const timeoutMs = resolveTimeoutMs(this.config.timeoutMs, endpoint);
         return withRetry(async () => {
+            // An upload endpoint hands undici the FormData itself: undici derives the
+            // multipart content-type (boundary included) from the body, so setting one
+            // here would corrupt the request.
+            const isUpload = endpoint.kind === 'upload';
             const headers = {
-                'content-type': 'application/json',
                 // undici does not auto-decompress; decodeResponseBody gunzips below. Server
                 // gzip cuts JSON payloads ~3-10x (measured 3.6x on constant-list).
                 'accept-encoding': 'gzip',
             };
+            if (!isUpload)
+                headers['content-type'] = 'application/json';
             // Keep the header we actually sent: the self-heal check compares it against
             // the current memoCache token to tell "stale token" from "fresh token died".
             let usedAuthorization;
@@ -360,7 +365,7 @@ export class GangtiseClient {
             const response = await request(url, {
                 method: endpoint.method,
                 headers,
-                body: endpoint.method === 'GET' ? undefined : JSON.stringify(body ?? {}),
+                body: endpoint.method === 'GET' ? undefined : (isUpload ? body : JSON.stringify(body ?? {})),
                 headersTimeout: timeoutMs,
                 bodyTimeout: timeoutMs,
                 dispatcher,
@@ -392,7 +397,7 @@ export class GangtiseClient {
             const retryAfterMs = parseRetryAfterMs(response.headers['retry-after'], Date.now());
             let parsed;
             try {
-                parsed = JSON.parse(text);
+                parsed = JSON.parse(quoteBigIntFields(text, endpoint.bigIntFields));
             }
             catch {
                 const message = response.statusCode >= 400
@@ -434,7 +439,22 @@ export class GangtiseClient {
             throw error;
         });
     }
-    async download(endpoint, query, options) {
+    /** POST a file as multipart/form-data under the field name `file`. Reuses
+     * requestJson for auth / retry / envelope handling — only the body differs. */
+    async uploadFile(endpointKey, file) {
+        const endpoint = ENDPOINTS[endpointKey];
+        if (!endpoint || endpoint.kind !== 'upload') {
+            throw new ApiError(`Not an upload endpoint: ${endpointKey}`);
+        }
+        const form = new FormData();
+        // Cast: TS 5.7+ types Uint8Array as Uint8Array<ArrayBufferLike>, which BlobPart
+        // (ArrayBufferView<ArrayBuffer>) rejects; a Node Buffer is always ArrayBuffer-backed.
+        form.append('file', new Blob([file.data], { type: file.contentType ?? 'application/octet-stream' }), file.filename);
+        return this.requestJson(endpoint, form);
+    }
+    /** `body` is only sent for POST download endpoints (the file-parse result
+     * endpoint takes `{taskId}` as JSON and answers with the ZIP bytes). */
+    async download(endpoint, query, options, body) {
         const dispatcher = getDispatcher();
         const url = this.buildUrl(endpoint.path);
         Object.entries(query).forEach(([key, value]) => {
@@ -446,9 +466,13 @@ export class GangtiseClient {
             const startedAt = Date.now();
             let currentUrl = url;
             let auth = authorization;
+            const isPost = endpoint.method === 'POST';
             let response = await request(currentUrl, {
                 method: endpoint.method,
-                headers: { Authorization: authorization },
+                headers: isPost
+                    ? { Authorization: authorization, 'content-type': 'application/json' }
+                    : { Authorization: authorization },
+                body: isPost ? JSON.stringify(body ?? {}) : undefined,
                 headersTimeout: this.config.timeoutMs,
                 bodyTimeout: this.config.timeoutMs,
                 dispatcher,
@@ -488,7 +512,7 @@ export class GangtiseClient {
             const retryAfterMs = parseRetryAfterMs(response.headers['retry-after'], Date.now());
             if (contentType?.includes('application/json')) {
                 const text = await response.body.text();
-                logTiming(`GET ${endpoint.path} (json)`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
+                logTiming(`${endpoint.method} ${endpoint.path} (json)`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
                 let parsed;
                 try {
                     parsed = JSON.parse(text);
@@ -517,7 +541,7 @@ export class GangtiseClient {
             }
             if (contentType?.includes('text/plain') || contentType?.includes('text/html')) {
                 const text = await response.body.text();
-                logTiming(`GET ${endpoint.path} (text)`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
+                logTiming(`${endpoint.method} ${endpoint.path} (text)`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
                 if (response.statusCode >= 400) {
                     throw new ApiError('Download failed', undefined, response.statusCode, text, retryAfterMs);
                 }
@@ -560,11 +584,11 @@ export class GangtiseClient {
                     await fs.unlink(partPath).catch(() => { });
                     throw error;
                 }
-                logTiming(`GET ${endpoint.path} (stream)`, Date.now() - startedAt, `${response.statusCode}`);
+                logTiming(`${endpoint.method} ${endpoint.path} (stream)`, Date.now() - startedAt, `${response.statusCode}`);
                 return { contentType, filename, savedPath: options.streamTo };
             }
             const buffer = await response.body.arrayBuffer();
-            logTiming(`GET ${endpoint.path} (binary)`, Date.now() - startedAt, `${response.statusCode}, ${buffer.byteLength}B`);
+            logTiming(`${endpoint.method} ${endpoint.path} (binary)`, Date.now() - startedAt, `${response.statusCode}, ${buffer.byteLength}B`);
             return {
                 data: new Uint8Array(buffer),
                 contentType,
@@ -587,8 +611,11 @@ export class GangtiseClient {
         if (!endpoint) {
             throw new ApiError(`Unknown endpoint key: ${endpointKey}`);
         }
+        if (endpoint.kind === 'upload') {
+            throw new ValidationError(`${endpointKey} takes a file upload — use 'gangtise tool file-parse --file <path>' ('raw call' cannot send files)`);
+        }
         if (endpoint.kind === 'download') {
-            return this.download(endpoint, query ?? {}, options);
+            return this.download(endpoint, query ?? {}, options, body);
         }
         if (endpoint.kind === 'json' && endpoint.pagination?.enabled) {
             return this.requestPaginated(endpoint, body);

package/dist/src/core/endpoints.js

@@ -77,6 +77,19 @@ const ENDPOINT_DEFS = {
         description: "List forums",
         pagination: { enabled: true, maxPageSize: 50 },
     },
+    "insight.performance-calendar.list": {
+        method: "POST",
+        path: "/application/open-insight/schedule/performance-calendar/getList",
+        kind: "json",
+        description: "List earnings calendar events (forecast / express / announcement)",
+        pagination: { enabled: true, maxPageSize: 50 },
+    },
+    "insight.performance-calendar.download": {
+        method: "GET",
+        path: "/application/open-insight/schedule/performance-calendar/download/file",
+        kind: "download",
+        description: "Download an earnings report file (A-share 10 credits, HK/US 20)",
+    },
     "insight.research.list": {
         method: "POST",
         path: "/application/open-insight/broker-report/getList",
@@ -619,6 +632,27 @@ const ENDPOINT_DEFS = {
         description: "Get time-series data (multi-indicator x single-security OR single-indicator x multi-security)",
         retry: "no-999999",
     },
+    // ─── tool (open-tool: async file parsing) ───
+    "tool.file-parse.submit": {
+        method: "POST",
+        path: "/application/open-tool/file-parse/submit",
+        kind: "upload",
+        description: "Submit a PDF for parsing (multipart upload), returns taskId",
+        // Billed per page (0.8/页) at submit time, and the upload itself can take
+        // minutes on a 100MB file — never replay it, and don't let the default 30s
+        // headers timeout kill an in-flight upload.
+        timeoutMs: 300_000,
+        retry: "no-replay",
+        // Probed 2026-07-25: taskId comes back as a string today. Guard anyway — if it
+        // ever arrives as a bare number, rounding would strand a paid parse job.
+        bigIntFields: ["taskId"],
+    },
+    "tool.file-parse.result": {
+        method: "POST",
+        path: "/application/open-tool/file-parse/result",
+        kind: "download",
+        description: "Fetch a file-parse result ZIP by taskId (140001 = still generating)",
+    },
 };
 export const ENDPOINTS = Object.fromEntries(Object.entries(ENDPOINT_DEFS).map(([key, def]) => [key, { key, ...def }]));
 /** Flat catalog of every registered endpoint, for `raw list` discoverability

package/dist/src/core/fileParse.js

@@ -0,0 +1,87 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isAsyncPending, nextPollDelayMs, POLL_MAX_ATTEMPTS } from "./asyncContent.js";
+import { saveDownloadResult } from "./download.js";
+import { ApiError, ValidationError } from "./errors.js";
+import { isTransientError } from "./transport.js";
+/** Server-side upload cap (spec: ≤100MB, ≤500 pages). Checked locally so a
+ * doomed 100MB+ upload fails instantly instead of after a long transfer. */
+export const FILE_PARSE_MAX_BYTES = 100 * 1024 * 1024;
+/** Upload a PDF and return its taskId. Billed at submit time (0.8 credits/page),
+ * so every reason to reject a file is checked before the request goes out. */
+export async function submitFileParse(client, filePath) {
+    const resolved = path.resolve(filePath);
+    let stat;
+    try {
+        stat = await fs.stat(resolved);
+    }
+    catch {
+        throw new ValidationError(`File not found: ${filePath}`);
+    }
+    if (!stat.isFile())
+        throw new ValidationError(`Not a file: ${filePath}`);
+    if (stat.size === 0)
+        throw new ValidationError(`File is empty: ${filePath}`);
+    if (stat.size > FILE_PARSE_MAX_BYTES) {
+        throw new ValidationError(`File is ${(stat.size / 1024 / 1024).toFixed(1)}MB — the parse API accepts at most 100MB`);
+    }
+    if (path.extname(resolved).toLowerCase() !== ".pdf") {
+        throw new ValidationError(`Only PDF files are supported: ${filePath}`);
+    }
+    // Buffered, not streamed: undici's FormData needs a Blob, so a 100MB file peaks
+    // at ~2× its size in memory. Acceptable against the API's own 100MB ceiling —
+    // switch to a hand-rolled streaming multipart body if that ceiling ever rises.
+    const data = await fs.readFile(resolved);
+    const result = await client.uploadFile("tool.file-parse.submit", {
+        filename: path.basename(resolved),
+        data,
+        contentType: "application/pdf",
+    });
+    const taskId = result?.taskId;
+    if (taskId === undefined || taskId === null || taskId === "") {
+        throw new ApiError("File parse task was accepted but the response carried no taskId", undefined, undefined, result);
+    }
+    return String(taskId);
+}
+/**
+ * One result fetch. "pending" = the server answered with the generating code
+ * (140001 / legacy 410110); "ok" = the ZIP was written and its path printed.
+ * Free to call — only the submit step is billed.
+ */
+export async function fetchFileParseResult(client, taskId, output) {
+    let result;
+    try {
+        result = await client.call("tool.file-parse.result", { taskId }, undefined, output ? { streamTo: output } : undefined);
+    }
+    catch (error) {
+        if (isAsyncPending(error))
+            return "pending";
+        throw error;
+    }
+    await saveDownloadResult(result, `file-parse-${taskId}`, output);
+    return "ok";
+}
+/** Poll until the ZIP is ready. Same backoff budget as the AI async endpoints
+ * (≈316s), which covers the documented ~3 min parse time. */
+export async function pollFileParseResult(client, taskId, output) {
+    for (let attempt = 1; attempt <= POLL_MAX_ATTEMPTS; attempt++) {
+        try {
+            if (await fetchFileParseResult(client, taskId, output) === "ok")
+                return "ok";
+        }
+        catch (error) {
+            // The task is already paid for: a blip must not void the wait. Transient
+            // errors consume the attempt, anything else (bad taskId, no permission) aborts.
+            if (!isTransientError(error))
+                throw error;
+            const msg = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`Attempt ${attempt}/${POLL_MAX_ATTEMPTS}: transient error (${msg.slice(0, 80)}), continuing to wait...\n`);
+        }
+        if (attempt < POLL_MAX_ATTEMPTS) {
+            const delay = nextPollDelayMs(attempt);
+            process.stderr.write(`Attempt ${attempt}/${POLL_MAX_ATTEMPTS}: parse result not ready, retrying in ${Math.round(delay / 1000)}s...\n`);
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    return "timeout";
+}

package/dist/src/core/normalize.js

@@ -1,3 +1,33 @@
+import { ENVELOPE_TRACE_ID, ValidationError } from "./errors.js";
+/** 信封 traceId 由 `client.ts` 挂在每个成功响应的 payload 上（非枚举 symbol）。
+ * 结构异常报障没这个 id 服务端查不了，所以拍平失败时要一并带出。 */
+function traceSuffix(source) {
+    if (!source || typeof source !== "object")
+        return "";
+    const traceId = source[ENVELOPE_TRACE_ID];
+    return typeof traceId === "string" ? `（trace ${traceId}）` : "";
+}
+/** 按位置把列式响应的一行值拍平成对象。
+ *
+ * 上游对「fieldList 里有该接口不存在的字段名」有两套处理，实测 2026-07-24：
+ * day-kline / minute-kline / fund-flow 把名和值一起丢、三大报表补 null——长度仍相等，安全；
+ * 但 realtime / main-business / valuation-analysis 是**值只按有效字段返回、字段名却按请求
+ * 原样回显**。长度一旦不等，按位置拍平就会把值贴到错误的字段上：realtime 传
+ * ["securityCode","close","turnoverRate"]（realtime 根本没有 close）只回 2 个值，
+ * 换手率 28.5573 被贴成 close，读起来就是「茅台收盘价 28.56」（真实价 1297.41）。
+ * 不报错、数字看着还合理、却完全是另一个指标——静默错列必须变成显式失败。
+ *
+ * 文案不能一口咬定「字段名传错」：`alternative edb-data` 走同一个拍平却根本没有
+ * `--field`（只有 `--indicator-id`），那里长度不等只可能是上游响应结构变了。 */
+export function zipFieldRow(fields, row, source) {
+    if (row.length !== fields.length) {
+        throw new ValidationError(`响应字段数与 fieldList 不匹配（fieldList ${fields.length} 项、该行返回 ${row.length} 个值）——按位置拍平会把值贴到错误的字段上，已拒绝输出。带 --field 的命令多为传了该接口不存在的字段名（上游只返回有效字段的值、字段名却按请求回显）：核对 --field 取值（如 quote realtime 没有 close，最新价是 latestPrice），不确定就不传 --field（返回全量字段最稳）。没有 --field 的命令（如 alternative edb-data）出现此错，是上游响应结构异常，请报障${traceSuffix(source)}。`);
+    }
+    return fields.reduce((acc, field, index) => {
+        acc[String(field)] = row[index];
+        return acc;
+    }, {});
+}
 export function normalizeRows(value) {
     if (!value || typeof value !== "object") {
         return value;
@@ -7,14 +37,8 @@ export function normalizeRows(value) {
     }
     const record = value;
     if (Array.isArray(record.fieldList) && Array.isArray(record.list)) {
-        const normalizedList = record.list.map((row) => {
-            if (!Array.isArray(row))
-                return row;
-            return record.fieldList.reduce((acc, field, index) => {
-                acc[String(field)] = row[index];
-                return acc;
-            }, {});
-        });
+        const fields = record.fieldList;
+        const normalizedList = record.list.map((row) => (Array.isArray(row) ? zipFieldRow(fields, row, record) : row));
         const { fieldList, list, ...meta } = record;
         const hasMeta = Object.keys(meta).length > 0;
         return hasMeta ? { ...meta, list: normalizedList } : normalizedList;

package/dist/src/core/transport.js

@@ -9,6 +9,26 @@ export function decodeResponseBody(buf, contentEncoding) {
     const b = Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength);
     return enc === "gzip" ? gunzipSync(b).toString("utf8") : b.toString("utf8");
 }
+/**
+ * Re-quote the *unquoted numeric* values of the named JSON fields so ids past
+ * 2^53 survive JSON.parse: `{"taskId":1782345678901234567}` would otherwise come
+ * back as 1782345678901234700 and address a task that does not exist.
+ *
+ * Probed 2026-07-25: file-parse's submit returns `taskId` as a STRING (matching
+ * the spec), so this is a forward guard, not a live fix — but the failure mode it
+ * covers is silent and expensive (the parse job is already billed, and a rounded
+ * id can never fetch its result). Values already in quotes are left alone: the
+ * pattern only matches a bare number right after the key.
+ */
+export function quoteBigIntFields(text, fields) {
+    if (!fields?.length)
+        return text;
+    let out = text;
+    for (const field of fields) {
+        out = out.replace(new RegExp(`("${field}"\\s*:\\s*)(-?\\d+)`, "g"), '$1"$2"');
+    }
+    return out;
+}
 /** A Retry-After delay we'll honor even if it exceeds maxDelay — but never past this
  * ceiling, so a hostile/misconfigured header can't hang the CLI for minutes. */
 const RETRY_AFTER_CEILING_MS = 60_000;

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated — DO NOT EDIT
-export const CLI_VERSION = "0.28.2";
+export const CLI_VERSION = "0.29.0";

package/gangtise-openapi/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: gangtise-openapi
-version: "0.28.2"
+version: "0.29.0"
 description: |-
   通过 gangtise CLI 直接调用 Gangtise OpenAPI，拉取投研原始数据、批量导出、下载文件、调用 AI 能力。
 
   **触发词**：调接口 / CLI / openapi / 导出 / 下载研报 / 批量查 / 拉数据 / 跑一下 / 钢尼斯 / gtIC（Gangtise 语音误识别）
 
-  **适用**：原始数据导出、批量 jsonl/csv、下载 PDF/MD、行情 K 线、财务报表、估值指标、证券级数据指标（EDE 截面/时序）、AI 能力（一页通/投资逻辑/同业对比/个股看点·投研总结/投研线索/业绩点评/观点PK·多空辩论/主题跟踪/热点话题/管理层讨论/调研提纲/知识库搜索）、云盘文件管理（Vault）
+  **适用**：原始数据导出、批量 jsonl/csv、下载 PDF/MD、行情 K 线、财务报表、估值指标、证券级数据指标（EDE 截面/时序）、财报日历（业绩预告/快报/公告）、PDF 解析为 Markdown、AI 能力（一页通/投资逻辑/同业对比/个股看点·投研总结/投研线索/业绩点评/观点PK·多空辩论/主题跟踪/热点话题/管理层讨论/调研提纲/知识库搜索）、云盘文件管理（Vault）
 
   **不适用**：不脱离 OpenAPI 自行撰写研报、编造投研结论或做自由问答——观点总结、多空 PK 等 AI 产物本 skill 只经由 Gangtise 平台 AI 接口获取，不自行生成
 
@@ -36,6 +36,7 @@ description: |-
    - Token 失效（`0000001008` / `999002`，含已废弃的 `8000014`/`8000015`）→ 自动重新登录并重试一次；凭证错 `999011` → **不重试**（AK/SK 不对不会自己好），查环境变量
 8. **参数命名差异**：Insight/Quote/Vault 用 `--security`，Fundamental/AI 用 `--security-code`（例外：`ai stock-summary` 用 `--security`，`ai security-clue` 用 `--gts-code`）。
 9. **调试**：`--verbose` 或 `GANGTISE_VERBOSE=1` 打印每个请求的耗时/字节数到 stderr。
+10. **`--field` 字段名必须核对，不确定就别传**（返回全量最稳）：`quote realtime` / `fundamental main-business` / `valuation-analysis` 遇到不存在的字段名时，上游只丢**值**、字段名照请求**回显**，按位置拍平会把值贴到错误的字段上（实测 realtime 传 `close`——它没有这个字段——换手率 28.5573 被贴成 `close`，茅台真实价 1297.41）。v0.28.3 起 CLI 检测到长度不匹配直接报错（退出码 1）：**带 `--field` 的命令看到这个报错，先去 `references/fields.md` 核对字段名**（没有 `--field` 的命令如 `alternative edb-data` 报此错则是上游响应结构异常，报障时若报错末尾附了 `（trace …）` 就一并带上）。另：realtime **无 `close`**（用 `latestPrice`）、**无市值**（总市值走 `indicator cross-section --indicator qte_mkt_cptl`，仅 A 股）。
 
 ## 工作流（3 步）
 
@@ -67,9 +68,10 @@ description: |-
 "免费"=0 积分；**只列单价**，数据范围（可查多久）随账号等级不同、不在此列。
 
 - **免费**：所有 `quote` 行情、`fundamental` 报表/主营/估值/股东（**盈利预测除外**）、`reference`/`constant` 查询（含 `official-account-search`）、`alternative edb-search`、`vault`（record/wechat/股票池/drive/AI云盘）、`insight report-image list`
-- **0.1/条 list**：research / foreign-report / official-account / announcement(A/港/美) / summary / qa 的 list、`vault my-conference-list`；`insight report-image download` 0.1/张
+- **0.1/条 list**：research / foreign-report / official-account / announcement(A/港/美) / summary / qa / performance-calendar 的 list、`vault my-conference-list`；`insight report-image download` 0.1/张
 - **按条（观点/含详情类 list）**：independent-opinion list 与 `ai security-clue` 5；roadshow/site-visit/strategy/forum list 20；opinion / foreign-opinion list 30；`fundamental earning-forecast` 0.5；`ai stock-summary` 3（无看点的证券不返回也不扣）；`alternative edb-data` 30
-- **各 download（/篇）**：announcement / official-account / research 10；announcement-hk / announcement-us 20；independent-opinion 30；summary / foreign-report / my-conference 50
+- **各 download（/篇）**：announcement / official-account / research 10；announcement-hk / announcement-us 20；independent-opinion 30；summary / foreign-report / my-conference 50；`performance-calendar download` A 股 10 / 港美股 20
+- **按页**：`tool file-parse` 0.8/页，**提交（`--file`）时按实际页数一次性扣**，取结果（`file-parse-check`）免费——50 页 PDF = 40 积分，别重复提交同一文件
 - 🔴 **按次贵**：`ai knowledge-batch` 10、`management-discuss-*` 10；AI Agent（`one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `earnings-review` / `viewpoint-debate` / `theme-tracking`）**50/次**；`ai hot-topic` 50/篇
 - 🔴 **极贵**：`alternative concept-info` / `concept-securities` **500/次**
 - ⚠️ **同参数重复调用不免费**：按次计费无缓存命中豁免（2026-07-11 实测 `one-pager` 重复调用每次扣分，即使秒回缓存内容）——生成类结果拿到后自行留存复用，别为"刷新"重调；CLI 已对上述 🔴 贵档端点关闭 5xx/超时自动重放（v0.26.0），50/篇 的 `summary` / `foreign-report` / `my-conference` download 同样不重放（v0.27.0），正是为防重复扣分
@@ -103,6 +105,7 @@ description: |-
 | 外资独立观点 / 独立分析师观点 | `insight independent-opinion list` |
 | 纪要 / 会议纪要（外部） | `insight summary list` |
 | 路演 / 调研 / 策略会 / 论坛 | `insight roadshow / site-visit / strategy / forum list` |
+| 财报日历 / 业绩预告 / 业绩快报 / 财报披露排期 | `insight performance-calendar list`（**用 `--start-date`/`--end-date`，不是 `--start-time`**；全表 >12 万条，CLI 强制要求日期范围 / `--security` / `--size` 三者至少其一；只给 `--security` 时另有 1000 行隐式上限，撞上限且 total 还有剩余=筛选可能没生效（标 `partial`、退出码 3），改用日期范围重查。下载原文 `performance-calendar download --performance-report-id`，仅 `hasAttachment: true` 可下） |
 | A 股公告 / 公告 | `insight announcement list` |
 | 港股公告 / HK 公告 | `insight announcement-hk list` |
 | 美股公告 / US 公告 | `insight announcement-us list` |
@@ -154,6 +157,7 @@ description: |-
 | 题材 ID 搜索 | `reference concept-search` |
 | 板块 ID 搜索 | `reference sector-search` |
 | 板块成分股 | `reference sector-constituents`（前置：`reference sector-search` 拿 `sector-id`） |
+| PDF 转 Markdown / 解析文件 / 提取 PDF 正文 | `tool file-parse --file <x.pdf> --wait`（异步，0.8 积分/页，提交时扣；取结果 `tool file-parse-check --task-id`。**平台自有研报/公告优先用各 download 的 `--file-type 2` 直出 Markdown**，别花解析费） |
 
 **易混淆消歧**：
 - "纪要" → 外部信息走 `insight summary`；公司内部录音/会议走 `vault my-conference`
@@ -163,7 +167,7 @@ description: |-
 - **证券基本面 / 指标先按任务形态路由，不是搜到 EDE 就一律走 EDE**：
   - 单证券先优先对应 `fundamental` 专用命令（财务、估值、盈利预测、股东、主营或完整三大报表，多数免费 / 低价）。其中 `valuation-analysis` / `earning-forecast` 实测仅支持 A 股；港 / 美股的估值历史分位、盈利预测、以及 PE/PB 等核心估值（EDE 也仅 A 股）当前 CLI 均无可用接口，如实说明不支持、勿用别的语义顶替
   - 多证券批量取一组**已实现**财务 / 估值指标 → 优先 `indicator search` 后用 EDE 一次拉取，替代逐只循环；单日或同一报告期横向比较用 `cross-section`，区间走势用 `time-series`（后者不能多指标 × 多证券同时）。**批量按 code 回填加 `--key-by code`**（列头用 `indicatorCode`，防同名指标碰撞 + 服务端重排列序导致的错位）
-  - 始终排除 EDE：A股盈利预测 / 一致预期（含预测 EPS）→ `fundamental earning-forecast`；A股估值历史分位 → `fundamental valuation-analysis`；开高低收 / 成交量等行情与 K 线 → `quote`；单证券完整报表 → 对应三大报表命令。EDE 搜到的基本 / 稀释 EPS 是已实现值，**不能冒充预测 EPS**；港 / 美股缺少上述专用能力时应如实说明不支持，不能用别的语义代替
+  - 始终排除 EDE：A股盈利预测 / 一致预期（含预测 EPS）→ `fundamental earning-forecast`；A股估值历史分位 → `fundamental valuation-analysis`；开高低收 / 成交量等行情与 K 线 → `quote`；单证券完整报表 → 对应三大报表命令。**例外：总市值只有 EDE 有**——`quote realtime` / `day-kline` 都不返回市值，走 `indicator cross-section --indicator qte_mkt_cptl`（仅 A 股，默认单位「元」，用 `--scale` 缩放）。EDE 搜到的基本 / 稀释 EPS 是已实现值，**不能冒充预测 EPS**；港 / 美股缺少上述专用能力时应如实说明不支持，不能用别的语义代替
   - EDE 取数前必须用 `search --format json` 同时核对：`indicatorName` + `description` 语义准确、`scopeList` 覆盖全部目标市场 / 证券类型、`parameterList` 必填参数与枚举可满足；`scopeList` 缺失 / `null` / 空或任一项不符，都视为无法证明覆盖并回退专用接口。专用接口也不覆盖目标市场时，说明当前不可用，不要硬调。`scopeList` 按指标各不相同，不能因 EDE 服务支持 A / 港 / 美股就假定某个指标三市场都覆盖
   - `indicator search` 免费，`cross-section` / `time-series` 按单元格计费；除多证券批量的效率收益外，仍优先免费 / 低价的 `quote` 或 `fundamental`
 - 行业 / 宏观指标（空调销量、社融等，无证券维度）走 `alternative edb-*`（EDB），不要与证券级 EDE 混用
@@ -203,6 +207,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 | **AI 内容** | one-pager / investment-logic / peer-comparison / research-outline | `{content: "markdown文本"}` | 取 `content` 直接呈现 |
 | **K 线** | quote * | `{list: [{tradeDate, ...}]}` | 按 tradeDate 排序，取需要的尾部 |
 | **异步（含 *-check）** | earnings-review / viewpoint-debate / earnings-review-check / viewpoint-debate-check | 提交 `{dataId, status, hint}`；check 成功 `{date, content}` / pending `{status:"pending"}` 或抛 `140001`（旧 `410110`） | 见下方"异步任务流程" |
+| **异步文件** | tool file-parse / file-parse-check | 提交 `{taskId, status, hint}`；就绪后 stdout = ZIP 路径，未就绪 `{status:"pending"}` | 解压取 `file.md`；重取用 `file-parse-check`（免费），别重跑 `file-parse`（按页重扣） |
 
 完整字段对照见 `references/response-schema.md`。
 
@@ -236,7 +241,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 | 最新一期 / 最新报告期（财报） | — | — | 省略 `--fiscal-year`，传 `--period latest`（默认） |
 | 最新观点 / 今日观点 | 1 天范围 + `--rank-type 2` | — | — |
 
-日期参数**按参数名判断、不按命令组**（命令组会误导——AI 里既有 `--start-time` 又有 `--date`/`--report-date`）：名字带 `-date` 的（`--start-date`/`--end-date`/`--date`/`--report-date`）一律 `YYYY-MM-DD`，覆盖 Quote/Fundamental、AI 的 `theme-tracking`(`--date`)/`hot-topic`/`management-discuss-*`(`--report-date`)、Alternative `edb-data`、Indicator `cross-section`(`--date`)/`time-series`；名字带 `-time` 的（`--start-time`/`--end-time`）用 `YYYY-MM-DD[ HH:mm[:ss]]`（秒可省、空格或 `T` 分隔）或 10/13 位时间戳，覆盖 Insight/Vault 各 list、`quote minute-kline`、`ai security-clue`、`ai knowledge-batch`。其中 **A 股公告（`insight announcement list`）与 `knowledge-batch` 会把输入转成 13 位毫秒**（10 位秒自动 ×1000），其余 `-time` 命令（含 `announcement-hk`/`announcement-us`）原样透传字符串；CLI 输入统一接受 10/13 位纯数字或 `YYYY-MM-DD[ HH:mm[:ss]]`（同上：秒可省、空格或 `T` 分隔）。
+日期参数**按参数名判断、不按命令组**（命令组会误导——AI 里既有 `--start-time` 又有 `--date`/`--report-date`；Insight 里 `performance-calendar` 是唯一用 `--start-date`/`--end-date` 的 list）：名字带 `-date` 的（`--start-date`/`--end-date`/`--date`/`--report-date`）一律 `YYYY-MM-DD`，覆盖 Quote/Fundamental、`insight performance-calendar`、AI 的 `theme-tracking`(`--date`)/`hot-topic`/`management-discuss-*`(`--report-date`)、Alternative `edb-data`、Indicator `cross-section`(`--date`)/`time-series`；名字带 `-time` 的（`--start-time`/`--end-time`）用 `YYYY-MM-DD[ HH:mm[:ss]]`（秒可省、空格或 `T` 分隔）或 10/13 位时间戳，覆盖 Insight/Vault 各 list、`quote minute-kline`、`ai security-clue`、`ai knowledge-batch`。其中 **A 股公告（`insight announcement list`）与 `knowledge-batch` 会把输入转成 13 位毫秒**（10 位秒自动 ×1000），其余 `-time` 命令（含 `announcement-hk`/`announcement-us`）原样透传字符串；CLI 输入统一接受 10/13 位纯数字或 `YYYY-MM-DD[ HH:mm[:ss]]`（同上：秒可省、空格或 `T` 分隔）。
 
 支持时间倒序的命令加 `--rank-type 2`：opinion / summary / research / foreign-report / announcement / announcement-hk / announcement-us / foreign-opinion / independent-opinion / official-account。其他 list 命令按 API 默认排序。
 
@@ -361,13 +366,14 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 
 按需 Read 对应文件：
 
-- 内资观点 / 纪要 / 路演 / 调研 / 策略 / 论坛 / 研报 / 外资研报 / A 股公告 / 港股公告 / 美股公告 / 外资观点 / 独立观点 / 公众号（official-account）/ 投资者问答（qa）/ 研报图表（report-image）→ `references/commands/insight.md`
+- 内资观点 / 纪要 / 路演 / 调研 / 策略 / 论坛 / 财报日历（performance-calendar）/ 研报 / 外资研报 / A 股公告 / 港股公告 / 美股公告 / 外资观点 / 独立观点 / 公众号（official-account）/ 投资者问答（qa）/ 研报图表（report-image）→ `references/commands/insight.md`
 - 行情命令（A 股 / 港股 / 美股日 K / 指数日 K / 分钟 K / 实时行情 / 资金流向 fund-flow） → `references/commands/quote.md`
 - 三大报表（A 股 / 港股 / 美股）/ 主营 / 估值 / 盈利预测 / 股东 → `references/commands/fundamental.md`
 - knowledge-batch / security-clue / 个股看点（stock-summary）/ AI agent / 异步任务 / 主题跟踪 / 热点 / 管理层讨论 → `references/commands/ai.md`
 - drive / record / my-conference / wechat / 股票池 → `references/commands/vault.md`
 - 行业指标数据库（EDB）/ 题材指数画像与成分股（concept-info / concept-securities）→ `references/commands/alternative.md`
 - 数据指标（EDE：search / cross-section / time-series，证券级指标截面与时序）→ `references/commands/indicator.md`
+- PDF 解析（file-parse：上传 PDF → Markdown + 图片 ZIP）→ `references/commands/tool.md`
 - securities-search / chiefs-search（首席 ID）/ institution-search（机构 ID）/ official-account-search（公众号 ID）/ 常量查询（constant-category / constant-list）/ 题材 ID（concept-search）/ 板块（sector-search / sector-constituents）/ lookup 本地表 / 行业别名 / raw call → `references/commands/reference-and-lookup.md`
 
 跑通流程对照 → `references/examples.md`

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

@@ -2,6 +2,8 @@
 
 通用：所有命令都需 `--security-code`（如 `600519.SH`，注意是 `--security-code` 不是 `--security`）。`--field` 可重复，可用字段见 `references/fields.md`；A / 港 / 美股三大报表命令都在省略 `--field` 时返回完整报表，指定后只保留基础字段与所选科目。
 
+**`--field` 字段名必须核对**（v0.28.3 起传错直接报错）：三大报表遇到不存在的字段名会补 `null`（安全），但 `main-business` / `valuation-analysis` 是**只丢值、字段名照请求回显**，按位置拍平会把值贴到错误的字段上（同 `quote realtime`，详见 `references/commands/quote.md`）。CLI 现在长度不匹配就直接失败（退出码 1），不输出错位数据。不确定字段名就别传 `--field`。
+
 ---
 
 ## A股三大报表（累计） `income-statement` / `balance-sheet` / `cash-flow`
@@ -15,6 +17,7 @@ gangtise fundamental <income-statement|balance-sheet|cash-flow> --security-code
 - `--fiscal-year` 可重复：`--fiscal-year 2023 --fiscal-year 2024`
 - `--start-date`/`--end-date` 有值时覆盖 `--fiscal-year`
 - **固定返回字段**（无需 `--field` 指定）：`securityCode` `companyName` `category` `announcementDate` `endDate` `fiscalYear` `period` `reportType` `companyType` `currency` `unit`
+- ⚠️ **本节两个命令的 `companyType` / `currency` 值是反的**（实测 2026-07-24，服务端字段名映射问题，与公司类型无关）：A 股累计口径的 `balance-sheet` / `cash-flow` 返回 `companyType=人民币`、`currency=一般企业`（工行则是 `currency=银行`）；**`income-statement` 是对的**。另：A 股 `*-quarterly` 单季表的 `companyType` 返回未映射的数字码（如 `102119999`）、`currency` 正确；**港股 / 美股三表实测均正常**（`companyType=一般企业`、`currency=人民币`/`美元`）。读这两列时按**值**判断语义，别按列名——科目数字本身不受影响
 
 **常用字段速查：**
 - 利润表：`totalOpRev` 营收 | `netProfit` 净利润 | `netProfitAttrParent` 归母 | `basicEPS` EPS | `rdExp` 研发
@@ -75,6 +78,7 @@ gangtise fundamental main-business --security-code <code> [--breakdown <type>] [
 - `--period`：`interim` 中报 | `annual` 年报（可重复）
 - 默认时间窗：`endDate` 当前日期、`startDate` 三年前
 - **不支持 `--fiscal-year`**（误传触发 `100001`/`100003`，旧 `900001`）；按年份筛选用 `--start-date`/`--end-date`
+- `--field` 只认 `references/fields.md` 「主营业务」小节的字段（`opRevenue` / `grossProfit` 等）；`securityCode`、`itemName` 这类**不是**该接口字段，传了会报「响应字段数与 fieldList 不匹配」（前 3 列 `periodName` / `periodEndDate` / `categoryName` 恒定返回）
 
 ## A股估值分析 `fundamental valuation-analysis`
 
@@ -86,6 +90,7 @@ gangtise fundamental valuation-analysis --security-code <code> --indicator <name
 - `--indicator`（**必选**）：`peTtm` 滚动PE | `pbMrq` PB | `peg` PEG | `psTtm` 滚动PS | `pcfTtm` 滚动PCF | `em` 企业倍数
 - `--limit` 默认 2000，省略 `--start-date` 时自动查近一年
 - `--skip-null`：丢弃 `value`/`percentileRank` 为 null 的行（最新交易日可能未入库）
+- **返回字段只有 7 个**（实测 2026-07-24）：`tradeDate` `value` `percentileRank` `average` `median` `upper1Std` `lower1Std`。**没有 `securityCode`**——误传会拿到一列重复的 `tradeDate`（长度相等，CLI 拦不住），传其他不存在的字段名则直接报错。**建议不传 `--field`**，证券代码本来就是你自己传进去的
 
 ## A股盈利预测 `fundamental earning-forecast`
 

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

@@ -59,7 +59,7 @@ gangtise indicator cross-section \
   --security 600519.SH --security 000858.SZ --security 300750.SZ \
   --date 2025-12-31 --format table
 # 列：date / security / name / 营业收入(利润表,累计) / 基本每股收益(利润表,累计)
-# 省略 reportType 即取到合并口径数（茅台2025=1688亿）。⚠️ 该枚举 label 与实测不符：label 标 1母公司/2合并/3母公司调整/4合并调整，实测 value=2/4 直接 999999、value=1 反返合并值——要指定报表口径改用 `fundamental income-statement --report-type`，勿在 EDE 按 label 传 reportType
+# 省略 reportType 即取合并口径（茅台2025=1688亿）。⚠️ 服务端 label 与实际取数错位：实际 1=合并 2=合并(调整) 3=母公司 4=母公司(调整)，按 label 传会取反（详见下方「reportType 口径」）
 ```
 
 ## 指标时间序列 `indicator time-series`
@@ -138,7 +138,18 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 - **名称反查 code 要核对，别取首条**：存在同显示名的兄弟指标——单季 `cf_finc_exp_qtr` 与累计 `cf_finc_exp` 都叫「财务费用」，`bs_fmt`/`cf_fmt`/`is_fmt` 都叫「报表格式」。`search` 按名称模糊匹配，目标 code 高概率在 top1 但不绝对，要看 `indicatorCode` 确认。
 - **批量查询做失败拆分**：某指标**缺必填参数**或入参错误时会整批报错（单元格级无数据按 `null` 返回；整个查询无数据的 `999999` 例外见上），逐指标单查能定位是哪个指标缺参/不可查。
 - **市值量纲（实测 2026-07）**：`qte_mkt_cptl`（总市值）**仅 A 股**——港股/美股返 `null`（换 `currency` 也没用，是 scope 外 ≠ 无数据）；**默认返原始「元」**（茅台 ≈ `1.5e12`，即 1.5 万亿），别误当天文数字。用 `scale` 数字码缩放（`0`元 / `3`千 / `4`万 / `6`百万 / `8`亿 / `9`十亿——`scale=8` → `15038` 亿元）、`currency` 换币种（`dft`本币 / `cny` / `hkd` / `usd` …）。**跨证券比市值前先统一 `scale`+`currency`**。
-- **EDE 财务指标的 `reportType` 枚举不可信（实测 2026-07-23）**：服务端 label（`1`母公司/`2`合并/`3`母公司调整/`4`合并调整）与实际取数不符——`value=2/4` 常直接 `999999`、`value=1` 反而返合并数（茅台2025营收 `value=1`→1688亿、`=3`→983亿、`=2/4`→999999）。**省略即用默认（合并口径，已实测有数）**；要明确指定合并/母公司口径请改用 `fundamental` 三大报表的 `--report-type`（口径语义可靠）。
+- **EDE 财务指标的 `reportType`：label 与 value 错位，但映射本身稳定可用（复测 2026-07-24，修正 07-23 的结论）**。服务端 label 标 `1`母公司/`2`合并/`3`母公司调整/`4`合并调整，**实际取数是**：
+
+  | value | 实际口径 | 说明 |
+  |-------|---------|------|
+  | `1`（默认，省略即此值） | **合并报表** | 绝大多数场景要的就是这个 |
+  | `2` | **合并报表（调整）** | 该报告期无重述数时为空 |
+  | `3` | **母公司报表** | |
+  | `4` | **母公司报表（调整）** | 该报告期无重述数时为空 |
+
+  实测对照（中信证券 `600030.SH` FY2024 营业收入，与 `fundamental income-statement --report-type` 逐一相等）：`1`→637.9亿（合并）、`2`→581.2亿（合并调整）、`3`→321.9亿（母公司）、`4`→321.9亿（母公司调整）；中国神华 `601088.SH` 同期 `1`→3383.75亿、`2`→3397.88亿，两值不同，可排除「2 就是合并原值」。**按 label 传会取反**（想要母公司却传 `1` 拿到合并）——认 value 不认 label：合并省略即可，母公司传 `3`。
+
+  `2`/`4` 返回空值**不是枚举失效**，是该报告期尚无调整表（如最新年报 FY2025：`1`/`3` 有数、`2`/`4` 无值，与 `fundamental --report-type consolidatedRestated` 同期无数据一致）；查询内所有单元格都无值时才会升级成 `999999`。港股默认口径同样是合并（腾讯 FY2024 营收 6602.57亿）。
 
 ## 通用说明
 

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

@@ -56,6 +56,25 @@ gangtise insight forum list      [--research-area <id>] [--location <id>]
 - `--market`：路演 `aShares`｜`hkStocks`｜`usChinaConcept`｜`usStocks`；调研 `aShares`｜`hkStocks`｜`usChinaConcept`（无 usStocks）
 - `--research-area`（路演/调研/论坛）：用 `gangtiseIndustry` 码（行业 `1008001xx` + 方向 `122000xxx`，见 `reference-and-lookup.md`）。**strategy 无 `--research-area`，只按 `--institution`/`--location` 筛**
 
+## 财报日历 `insight performance-calendar list/download`
+
+```bash
+gangtise insight performance-calendar list [--start-date <date>] [--end-date <date>] [--market <name>] [--security <code>] [--category <name>] [--from <n>] [--size <n>]
+gangtise insight performance-calendar download --performance-report-id <id> [--output <path>]
+```
+
+- ⚠️ **本命令用 `--start-date` / `--end-date`（`yyyy-MM-dd`），不是其余 insight list 的 `--start-time`**；过滤的是 `publishDate`（财报事件发布日）。也**没有** `--keyword` / `--rank-type` / `--search-type`
+- `--category`：`performanceForecast` 业绩预告 | `performanceExpress` 业绩快报 | `performanceAnnouncement` 业绩公告（可重复）
+- `--market`：`aShares` | `hkStocks` | `usChinaConcept` | `usStocks`（可重复）
+- `--market` / `--category` 拼错 CLI 本地直接报错（不是静默返全量）——这两个参数的枚举值不必猜
+- `--security`：证券代码，如 `000001.SZ`（可重复）
+- 自动翻页（`{total,list}`，单页上限 50）。**不加任何筛选时 total 十万量级**（实测 2026-07-25 为 126683，含未来已排期的财报日程）——CLI 因此要求至少一个约束：`--start-date` + `--end-date`、或 `--security`、或显式 `--size`，裸跑直接报 `ValidationError`（不发请求、不扣分）
+- 只给 `--security`（不给日期/`--size`）时，CLI 额外套一个 **1000 行隐式上限**：单只证券的整段日历只有几十条，正常查询感知不到；万一服务端哪天不再按 `securityList` 过滤，结果会在 1000 行截断并标 `partial`（stderr 警告 + 退出码 3），而不是闷头翻完全表。判据是 `total`：只有「取满 1000 行且 total 显示还有更多」才告警——恰好 1000 行且 total=1000 是完整结果，退出码仍是 0。看到告警说明筛选**可能**没生效，改用日期范围重查
+- 返回字段：`performanceReportId`（下载用）/ `securityCodeList[]`（A+H 同时上市会有多个代码）/ `securityName` / `category` / `publishDate` / `title` / `hasAttachment`
+- 实测 `publishDate` 返回的是 `yyyy-MM-dd 00:00:00`（文档写 `yyyy-MM-dd`），取日期请截前 10 位
+- download：**只有 `hasAttachment: true` 的记录能下**（先 list 确认）；省略 `--output` 用真实标题命名（走 title-cache，未命中会回查 list 接口，那次回查按 0.1/条 计费——批量下载建议显式 `--output`）
+- **积分**：list 0.1/条；download A 股 10/篇、港美股 20/篇
+
 ## 研报 `insight research list/download`
 
 ```bash

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

@@ -2,6 +2,8 @@
 
 通用：`--field` 可重复（`--field open --field close`），可用字段见 `references/fields.md`。
 
+**`--field` 字段名必须核对**（v0.28.3 起传错直接报错）：上游对不存在的字段名有两套处理——day-kline / minute-kline / fund-flow 把字段名和值一起丢掉（安全）；但 `quote realtime`（及 `fundamental main-business` / `valuation-analysis`）**只丢值、字段名照请求回显**，按位置拍平就把值贴到了错误的字段上。实测 `quote realtime --field securityCode --field close --field turnoverRate`：realtime 根本没有 `close`，返回的 2 个值被拍成 `close = 28.5573`（那是换手率，茅台真实价 1297.41）——不报错、数字看着合理、却完全是另一个指标。CLI 现在长度不匹配就直接失败（退出码 1），不输出错位数据。**不确定字段名就别传 `--field`**（返回全量最稳）。
+
 **关键规则**：查"最近"K线必须显式 `--start-date`/`--end-date` 拉范围，再从 `tradeDate` 取尾部最近 N 条；不要只用 `--limit N`（会截取查询窗口开头）。
 
 **自动分片**（v0.12.0；v0.14.2 修正分片粒度并注入 limit=10000）：`--security all` 跨日期范围 CLI 会自动按日切片并并发执行（A 股 1 天/片，美股 1 天/片，HK 2 天/片，指数 30 天/片），合并结果返回。CLI 在 `--security all` 路径会自动把 `limit` 抬到 10000（API 上限），避免默认 6000 行截断。无需手动按季度分批。
@@ -50,6 +52,8 @@ gangtise quote realtime [--security <code>] [--field <name>]
 - **全市场关键字**：`--security aShares` 全部 A 股 / `--security hkStocks` 全部港股 / `--security usStocks` 全部美股；建议配合 `--field` 精简返回字段
 - 返回**最新时刻**的行情快照（最新价/开高低/涨跌/成交量额/振幅）
 - 非交易时间返回最近一个交易日的收盘快照；停牌证券返回停牌前最后一个有效快照
+- **实测全量字段（16 个，2026-07-24）**：`securityCode` `exchange` `tradeDate` `tradeTime` `open` `high` `low` `latestPrice` `preClose` `change` `pctChange` `volume` `amount` `turnoverRate` `amplitude` `volumeRatio`
+- **没有 `close`**——收盘价语义用 `latestPrice`（非交易时间即为收盘价），或改用 `quote day-kline` 的 `close`；**也没有市值**，总市值走 `indicator cross-section --indicator qte_mkt_cptl`（仅 A 股）
 - 字段速查：见 `references/fields.md` 中的"实时行情"小节
 
 ## A股资金流向 `quote fund-flow`

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

@@ -0,0 +1,40 @@
+# Tool 命令详细参数（投研工具）
+
+## PDF 解析 `tool file-parse` / `file-parse-check`
+
+把 PDF（研报、公告、合同等）解析成 Markdown 正文 + 提取的图片，结果打包成 ZIP。异步两步：提交拿 `taskId` → 取结果 ZIP。
+
+```bash
+# 一步到位（推荐）：提交后阻塞轮询，就绪即落盘
+gangtise tool file-parse --file <x.pdf> --wait [--output <out.zip>]
+
+# 两步：先提交，稍后取结果
+gangtise tool file-parse --file <x.pdf>                       # 输出 {"taskId": "...", "status": "pending"}
+gangtise tool file-parse-check --task-id <id> [--output <out.zip>]
+```
+
+- `--file`（**必填**）：待解析的 PDF。CLI 在上传前本地校验：文件存在、非空、后缀 `.pdf`、≤100MB——不合格直接报 `ValidationError`，不发请求也不扣分
+- `--wait`：阻塞轮询到结果就绪（预算 ≈316s，覆盖官方「单文件约 3 分钟」）。**外层工具/命令超时要设到 ≥360s**，否则外层先超时（任务仍在服务端跑，之后 `file-parse-check` 照样能取）
+- `--output`：结果 ZIP 落盘路径。省略时用服务端返回的文件名（实测形如 `<taskId>.md.zip`），无则 `file-parse-<taskId>.zip`
+- 服务端限制：单文件 ≤100MB、≤500 页，同一用户最多 10 个并发任务
+- **积分**：**提交时按实际页数一次性扣费，0.8 积分/页**（50 页 = 40 积分）；取结果免费。提交端点标 `no-replay`——超时/5xx 不自动重放，避免同一文件重复扣费。**重跑 `file-parse` 会重新扣费，取结果请一律用 `file-parse-check --task-id`**
+- 未就绪时 `file-parse-check` 输出 `{"taskId": "...", "status": "pending"}` 且退出码 0（服务端返 `140001` RESULT_GENERATING，HTTP 409，实测 2026-07-25），隔 ~1 分钟再取即可
+
+ZIP 内容：
+
+```
+├── file.md          # Markdown 正文（保留标题层级与阅读顺序）
+└── images/          # 从 PDF 提取的图片（JPG，文件名由服务端生成；无图时为空目录）
+```
+
+呈现建议：解压后读 `file.md`；正文很长时先 `wc -l` / `head` 采样，不要整篇灌进上下文。
+
+## 常见搭配
+
+```bash
+# 下载研报原文 PDF → 解析成 Markdown
+gangtise insight research download --report-id 1234567 --output ./r.pdf
+gangtise tool file-parse --file ./r.pdf --wait --output ./r.zip
+```
+
+⚠️ 研报/公告类接口本身多数支持 `--file-type 2`（Markdown）直出，**先看能不能直接下 Markdown**（只算下载积分），别为已有 Markdown 的文件再花 0.8/页 走解析。`file-parse` 的价值在于外部来源的 PDF（自己的资料、非平台文件）。

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

@@ -53,7 +53,9 @@ gangtise vault wechat-message-list [--keyword <text>] [--security <code>] [--wec
 - `--wechat-group-id`：先用 `vault wechat-chatroom-list` 查；可重复
 - `--category`：`text` | `image` | `documents` | `url`（可重复）
 - `--tag`：`roadShow` | `research` | `strategyMeeting` | `meetingSummary` | `industryComment` | `companyComment` | `earningsReview`（可重复）
-- 返回字段：`msgId` / `msgContent` / `contentUrl` / `msgTime` / `wechatGroupId` / `wechatGroupName` / `speakerName` / `category` / `tagList` / `securityList`（含 `securityCode` / `securityName`）
+- 返回字段（实测 2026-07-25）：`msgId` / **`content`**（正文）/ **`url`**（链接）/ `msgTime` / `wechatGroupId` / `wechatGroupName` / `speakerName` / `category` / `tagList[]{tagCode, tagName}` / `securityList[]{securityCode, securityName}` / `quoteMsg{quoteMsgId, quoteContent, quoteUrl}`。旧版本文档写作 `msgContent` / `contentUrl` 是错的，取值请用 `content` / `url`
+- `quoteMsg`（2026-07-24 新增）：被引用的消息，无引用时为 `null`；`quoteContent` / `quoteUrl` 也可能为空。做上下文还原时用它把「回复」接回原消息
+- 未打标签/未关联证券的消息，`tagList` / `securityList` 返回 `null`（不是空数组）
 
 ## 群 ID 查询 `vault wechat-chatroom-list`
 

package/gangtise-openapi/references/examples.md

@@ -241,7 +241,7 @@
    - scopeList：覆盖全部三只 A 股；缺失/null/空也视为不通过
    - parameterList：补 required 参数并核对枚举
    任一不符 → 回退相应专用接口。
-3. 三类指标日期语义不同 → 拆三次截面，均加 `--key-by code`（列头用 indicatorCode，跨三张表按 code 稳定合并、免受同名/服务端重排干扰；省略 reportType 即取合并口径，⚠️ 该枚举 label 与实测不符、value=2/4 会 999999，需指定口径改用 fundamental income-statement --report-type）：
+3. 三类指标日期语义不同 → 拆三次截面，均加 `--key-by code`（列头用 indicatorCode，跨三张表按 code 稳定合并、免受同名/服务端重排干扰；省略 reportType 即取合并口径，⚠️ 该枚举 label 与实际取数错位——实际 1=合并 2=合并(调整) 3=母公司 4=母公司(调整)，要母公司口径传 3、别按 label 传 1）：
    a) 财务（营收/EPS）用报告期末 2025-12-31：
      gangtise indicator cross-section \
        --indicator is_op_rev --indicator is_eps_bas \
@@ -294,3 +294,37 @@
      --start-time "2026-06-06 00:00:00" --end-time "2026-07-06 23:59:59" --format json
 4. 只有要「全量枚举」券商/机构表时才用本地 lookup broker-org/meeting-org list（institution-search 是搜索、非全量）
 ```
+
+## 例 18：财报日历（本周谁发业绩预告）
+
+**用户**："这周 A 股有哪些业绩预告"
+
+```
+1. 路由 → insight performance-calendar list（不是 announcement——预告/快报/公告事件走财报日历）
+2. ⚠️ 本命令用 --start-date/--end-date（yyyy-MM-dd，过滤 publishDate），不是其余 insight list 的 --start-time
+   "这周" → 本周一至今天
+3. Pre-flight：不加筛选 total 十万量级（含未来排期）→ 必须带日期范围；0.1 积分/条，先 --size 探量
+4. gangtise insight performance-calendar list \
+     --start-date 2026-07-20 --end-date 2026-07-25 \
+     --market aShares --category performanceForecast \
+     --size 50 --format json
+   → list[].securityName / title / publishDate / performanceReportId / hasAttachment
+5. 用户要原文时：只有 hasAttachment: true 能下（A股 10 积分/篇）
+   gangtise insight performance-calendar download --performance-report-id 33753017 --output ./预告.pdf
+```
+
+## 例 19：外部 PDF 转 Markdown（异步文件解析）
+
+**用户**："把这份 PDF 转成 Markdown 我要读正文"
+
+```
+1. 先判断来源：平台自有研报/公告 → 直接 download --file-type 2 出 Markdown（只花下载积分），不要走解析
+   外部 PDF（用户自己的文件）→ tool file-parse
+2. Pre-flight：🔴 按页计费 0.8/页、提交即扣——先看页数估积分（50 页 = 40 积分）告知用户
+   本地限制 CLI 会先校验：.pdf 后缀 / 非空 / ≤100MB
+3. gangtise tool file-parse --file ./x.pdf --wait --output ./x.zip
+   （--wait 内部轮询 ≈316s；外层工具超时设 ≥360s。不带 --wait 则拿 taskId，稍后
+     gangtise tool file-parse-check --task-id <id> --output ./x.zip——取结果免费）
+4. unzip 后读 file.md（图片在 images/）；正文长先 wc -l / head 采样再呈现
+5. 超时不要重跑 file-parse（会重复扣费），用 file-parse-check 拿同一个 taskId 的结果
+```

package/gangtise-openapi/references/fields.md

@@ -30,6 +30,9 @@
 | `low` | 最低价 | `change` | 涨跌额 |
 | `pctChange` | 涨跌幅(%) | `volume` | 成交量(股，当日累计) |
 | `amount` | 成交总额(当日累计) | `amplitude` | 振幅(%) |
+| `turnoverRate` | 换手率(%) | `volumeRatio` | 量比 |
+
+**以上 16 个就是全部**（实测 2026-07-24）：**无 `close`**（用 `latestPrice`）、**无市值**（走 `indicator cross-section --indicator qte_mkt_cptl`）。realtime 传了不存在的字段名不会被忽略——上游只丢值、字段名照回显，CLI 检测到长度不匹配会直接报错（v0.28.3 起）。
 
 ### 指数日K线（沪深京 `quote index-day-kline`）
 

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

@@ -38,6 +38,9 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | 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` |
 | insight official-account download | 文件路径（stdout） | — |
 | 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） | — |
+| tool file-parse | `{taskId, status:"pending", hint}`（提交）；`--wait` 或 `file-parse-check` 就绪后 = 文件路径（stdout，ZIP） | ZIP 内 `file.md` + `images/`；未就绪时 check 输出 `{taskId, status:"pending"}`（退出码 0） |
 | 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` |
@@ -51,11 +54,11 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | reference sector-constituents | `{total, list}` | `list[].gtsCode` / `list[].gtsName`；total=0 说明 sectorId 不对（先 sector-search 确认） |
 | quote day-kline / day-kline-hk / day-kline-us / index-day-kline | `{fieldList, list}` 或规范化后 `{list: [{...}]}` | `tradeDate` / `securityCode` / `open` / `close` / `pctChange` / `volume`；index 另含 `securityName`（指数名称，v0.15.0 起） |
 | quote minute-kline | `{list: [{...}]}` | `tradeTime` / `open` / `close` / `volume` |
-| quote realtime | `{fieldList, list, total}` 或规范化后 `{list: [{...}]}` | `securityCode` / `exchange` / `tradeDate` / `tradeTime` / `latestPrice` / `pctChange` / `volume` / `amount` / `amplitude` |
+| quote realtime | `{fieldList, list, total}` 或规范化后 `{list: [{...}]}` | `securityCode` / `exchange` / `tradeDate` / `tradeTime` / `open` / `high` / `low` / `latestPrice` / `preClose` / `change` / `pctChange` / `volume` / `amount` / `turnoverRate` / `amplitude` / `volumeRatio`（共 16 个，**无 `close`、无市值**） |
 | quote fund-flow | `{fieldList, list, total}` 列式 → 规范化后 `{list: [{...}], total}` 宽表 | `securityCode` / `tradeDate` + 请求的字段（`mainNetInflow` / `largeInflow` / `xlargeOutflow` / …） |
-| fundamental income-statement / balance-sheet / cash-flow（含 quarterly / -hk / -us） | `{total, list: [{...}]}` | `fiscalYear` / `period` / `endDate` / `companyName` / `companyType`（企业类型名称，如 `一般企业`/`银行`）+ 各 `--field` 字段；港股/美股另含 `timeCovered`（不规则跨度） |
-| fundamental main-business | `{list: [{...}]}` | `endDate` / `breakdownName` / `revenue` / `revenueRatio` / `grossProfitRatio` |
-| fundamental valuation-analysis（仅 A 股） | `{list: [{...}]}` | `tradeDate` / `value` / `percentileRank` |
+| fundamental income-statement / balance-sheet / cash-flow（含 quarterly / -hk / -us） | `{total, list: [{...}]}` | `fiscalYear` / `period` / `endDate` / `companyName` / `companyType` / `currency` / `unit` + 各 `--field` 字段；港股/美股另含 `timeCovered`（不规则跨度）。⚠️ **A 股累计口径的 `balance-sheet` / `cash-flow` 两个命令**，`companyType` 与 `currency` 的值是互换的（实测 2026-07-24：`companyType=人民币`、`currency=银行`/`一般企业`；A 股 `income-statement` 正确，港股/美股三表均正确）；A 股 `*-quarterly` 单季表则是 `companyType` 返回未映射的数字码（如 `102119999`）、`currency` 正确。读这两列按**值**判断语义，别按列名；科目数字不受影响 |
+| fundamental main-business | `{fieldList, list}` 列式 → 规范化后 `{list: [{...}]}` | 前 3 列恒定：`periodName` / `periodEndDate` / `categoryName`（分项名，随 `--breakdown` 变）+ `opRevenue` / `opRevenueYoy` / `opRevenueRatio` / `opCost` / `opCostYoy` / `opCostRatio` / `grossProfit` / `grossProfitYoy` / `grossProfitRatio` / `grossMargin` / `grossMarginYoy` / `grossMarginRatio`（共 15 个，实测 2026-07-24）。`--field` 只能从后 12 个里选 |
+| fundamental valuation-analysis（仅 A 股） | `{fieldList, list}` 列式 → 规范化后 `{list: [{...}]}` | `tradeDate` / `value` / `percentileRank` / `average` / `median` / `upper1Std` / `lower1Std`（共 7 个，实测 2026-07-24）；**无 `securityCode`**——误传会拿到一列重复的 `tradeDate` |
 | fundamental earning-forecast（仅 A 股） | `{securityCode, securityName, updateList: [...]}` | `updateList[].date` / `updateList[].fieldList[].forecastYear` + 各 consensus 指标 |
 | fundamental top-holders | `{holderType, list: [{...}]}` | `reportPeriod` / `rank` / `shareholderName` / `holdingNum` / `holdingPct` / `chgNum` / `chgPct` |
 | ai knowledge-batch | `{list: [{...}]}` | `list[].resourceType` / `list[].sourceId` / `list[].title` / `list[].summary` |
@@ -73,7 +76,7 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 | vault record-download | 文件路径（stdout） | — |
 | vault my-conference-list | `{list, total}` | `list[].conferenceId` / `list[].title` / `list[].category` / `list[].institution.institutionName` / `list[].publishTime` |
 | vault my-conference-download | 文件路径（stdout） | — |
-| vault wechat-message-list | `{list, total}` | `list[].msgId` / `list[].msgContent` / `list[].msgTime` / `list[].wechatGroupName` / `list[].speakerName` / `list[].category` / `list[].tagList` |
+| vault wechat-message-list | `{list, total}` | `list[].msgId` / `list[].content`（正文）/ `list[].url` / `list[].msgTime` / `list[].wechatGroupName` / `list[].speakerName` / `list[].category` / `list[].tagList[].tagCode` / `list[].securityList[].securityCode` / `list[].quoteMsg.quoteContent`（引用消息，无引用为 `null`）。**不是 `msgContent`/`contentUrl`**（旧文档笔误，实测 2026-07-25） |
 | vault wechat-chatroom-list | `{list, total}` | `list[].chatroomName` / `list[].chatroomId` |
 | alternative edb-search | `{list: [...]}` 指标列表 | `indicatorId` / `indicatorName` / `dataSource` / `frequency` / `unit` |
 | alternative edb-data | 列表，每行 `{date, <indicatorId>: value, ...}` 宽表 | `date` + 每个 `--indicator-id` 一列（该日指标值） |

package/package.json

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