gangtise-openapi-cli 0.28.3 → 0.29.0

package/README.md

@@ -4,6 +4,21 @@
 
 ## 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` 传错字段名会导致**静默错列**（值贴到错误的字段上）。
@@ -305,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 下载） |
@@ -363,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 带不了文件） |
 
 ## 命令概览
 
@@ -377,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`
 
 ## 推荐工作流
@@ -425,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`
@@ -453,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 条记录匹配标题
@@ -530,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
@@ -764,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,6 +10,7 @@ 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 { 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";
@@ -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);
@@ -641,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) {
@@ -660,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/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.3";
+export const CLI_VERSION = "0.29.0";

package/gangtise-openapi/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: gangtise-openapi
-version: "0.28.3"
+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 接口获取，不自行生成
 
@@ -68,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），正是为防重复扣分
@@ -104,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` |
@@ -155,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`
@@ -204,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`。
 
@@ -237,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 默认排序。
 
@@ -362,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/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/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

@@ -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/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` |
@@ -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.3",
+  "version": "0.29.0",
   "description": "CLI for Gangtise OpenAPI",
   "license": "MIT",
   "repository": {