gangtise-openapi-cli 0.20.0 → 0.22.0

package/README.md

@@ -4,6 +4,22 @@
 
 ## Changelog
 
+### v0.21.0 — 2026-06-29
+
+**行为变更（注意）**
+- ⚠️ `vault wechat-chatroom-list` 省略 `--size` 现在**拉全量**（此前默认只返回 20 条）。该接口不返回 `total`，CLI 改为串行翻页（翻到不满页为止，单页上限 50）；传 `--size N` 仍只取前 N 条。依赖"默认 20 条"的脚本会拿到全部群。
+
+**修复**
+- `quote day-kline --security all` 等大结果集用默认 `table` 格式输出时不再因 `Math.max(...大数组)` 撑爆调用栈崩溃（`RangeError`）；`renderTable` 改用 reduce 计算列宽
+- CSV 导出：含回车符 `\r` 的字段现在正确加引号（RFC 4180）；`table` / `markdown` 的多行字段折叠换行，保持表格对齐
+- 下载文件名剥离控制字符 / NUL，避免 `fs.writeFile` 报错
+
+**修复（安全）**
+- token 缓存文件（`~/.config/gangtise/token.json`）改为临时文件 + 原子 `rename` 写入：从第一字节即 `0600`，消除"旧文件宽松权限残留"与"崩溃截断"两个隐患
+
+**内部 / 工程**
+- 依赖 `vitest` 升级到 3.2.6（修复 dev-only 安全告警）；新增 `npm run typecheck`；测试 257 → 272
+
 ### v0.20.0 — 2026-06-26
 
 **新增接口**
@@ -64,21 +80,7 @@
 - `--industry` 用 `citicIndustry` 码（`1008001xx`，全命令通用）；`--research-area` 用 `gangtiseIndustry` 码（行业 `1008001xx` + 宏观/策略/固收/金工/海外等方向 `122000xxx`）。详见 `gangtise-openapi/references/commands/reference-and-lookup.md`
 - 日程类 `--location`（domesticCity）服务端过滤已生效（v0.16.0 时曾未生效）
 
-### v0.16.0 — 2026-06-12
-
-**新增接口（参考数据 · 常量查询，均免积分）**
-- `reference constant-category` — 查询常量分类：全量导出常量分类及各分类适用于哪些接口的哪些参数（7 个分类：中信/申万/Gangtise 行业、国内城市、A股/港股公告分类、区域）
-- `reference constant-list --category <code>` — 查询常量值：按分类导出全量常量（`constantId` / `constantName`，树形分类含 `children` 嵌套）
-- `reference concept-search --keyword <kw>` — 查询题材 ID：按名称/拼音/分组名搜索，返回 `conceptId`（供 `alternative concept-info / concept-securities`、`ai theme-tracking` 使用）
-- `reference sector-search --keyword <kw>` — 查询板块 ID：返回 `sectorId` + `hierarchy` 层级路径
-- `reference sector-constituents --sector-id <id>` — 查询板块成分股：返回该板块全量成分股（`gtsCode` / `gtsName`）；注意 sectorId 必须来自 sector-search，题材 conceptId 查不到成分
-
-**接口变更（Breaking）**
-- 移除已被新 API 覆盖的 6 个本地 lookup 子命令及静态数据：`lookup research-area / industry / region / announcement-category / theme-id / industry-code list`，请改用 `reference constant-list` / `reference concept-search` / `reference sector-constituents`（申万行业代码 `821xxx.SWI` 全量：`sector-constituents --sector-id 2000000014`，即申万一级行业指数板块）
-- `lookup` 仅保留 2 个 API 未覆盖的本地表：`broker-org` / `meeting-org`
-- 路演/调研/策略会/论坛 list 新增 `--location <id>` 按城市过滤（domesticCity 常量 ID；服务端过滤 v0.17.0 起已生效）
-
-> 更早版本（v0.15.0 及之前）的完整更新历史见 [GitHub Releases](https://github.com/gangtiser/gangtise-openapi-cli/releases)。
+> 更早版本及完整更新历史见 [CHANGELOG.md](CHANGELOG.md)。
 
 ## 首次安装
 
@@ -121,9 +123,10 @@ export GANGTISE_TOKEN="Bearer xxx"
 export GANGTISE_PAGE_CONCURRENCY=5     # 翻页并发数（默认 5）
 export GANGTISE_VERBOSE=1              # 打印每个请求的耗时与字节数
 export GANGTISE_TIMEOUT_MS=30000       # 请求超时（默认 30s）
+export GANGTISE_TOKEN_CACHE_PATH=...   # 覆盖 token 缓存路径（默认 ~/.config/gangtise/token.json）
 ```
 
-如果没有 `GANGTISE_TOKEN`，CLI 会自动调用 token 接口并缓存到本地（`~/.config/gangtise/token.json`，权限 0600）。Token 失效（8000014/8000015）时会自动重新登录并重试一次。
+如果没有 `GANGTISE_TOKEN`，CLI 会自动调用 token 接口并缓存到本地（`~/.config/gangtise/token.json`，权限 0600）。Token 失效（8000014/8000015/0000001008）时会自动重新登录并重试一次。
 
 
 ## AI Agent Skill
@@ -131,6 +134,7 @@ export GANGTISE_TIMEOUT_MS=30000       # 请求超时（默认 30s）
 本项目包含 Skill 定义（`gangtise-openapi/SKILL.md`），可让 AI agent 自动调用 `gangtise` CLI 完成投研数据查询。支持以下 AI 编程助手：
 
 - [Claude Code](https://claude.ai/claude-code) — `~/.claude/skills/`
+- [Codex](https://github.com/openai/codex) — `~/.codex/skills/`
 - [OpenClaw](https://github.com/openclaw/openclaw) — `~/.openclaw/skills/`
 - [Hermes](https://github.com/nicepkg/hermes) — `~/.hermes/skills/`
 
@@ -161,6 +165,9 @@ gangtise-openapi/
 # Claude Code
 cp -r gangtise-openapi ~/.claude/skills/gangtise-openapi
 
+# Codex
+cp -r gangtise-openapi ~/.codex/skills/gangtise-openapi
+
 # OpenClaw
 cp -r gangtise-openapi ~/.openclaw/skills/gangtise-openapi
 
@@ -258,6 +265,7 @@ cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
 - `gangtise fundamental ...`
 - `gangtise ai ...`
 - `gangtise vault ...`
+- `gangtise indicator ...`
 - `gangtise alternative ...`
 - `gangtise reference ...`
 - `gangtise raw call ...`
@@ -293,7 +301,7 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 - **HTTP keep-alive**：所有请求复用同一个 `undici.Agent`（连接池 16），避免重复 TLS 握手。
 - **流式下载**：指定 `--output` 时，二进制响应（PDF 等）直接 `pipeline` 到磁盘，不经过内存缓冲；50MB PDF 内存占用近乎为零。
 - **流式输出**：`jsonl`/`csv` 格式且 `--output` 指定时，超过 1000 行自动切换为逐行写盘，避免一次性构建百 MB 字符串。
-- **自动重试**：5xx / `ECONNRESET` / `ETIMEDOUT` / `999999` 系统错误自动指数退避重试 2 次。
+- **自动重试**：5xx / 429 / `ECONNRESET` / `ETIMEDOUT` / `ENOTFOUND` / `EAI_AGAIN` / `UND_ERR_*`（undici 超时类）/ `999999` 系统错误自动指数退避重试 2 次。
 - **Token 自愈**：调用返回 8000014/8000015 时自动强制刷新 Token 并重试一次。
 - **K线自动分片**：`quote day-kline --security all` 等全市场查询自动按日期切分（A股 1 天/片、美股 1 天/片、HK 2 天/片、指数 30 天/片），并发执行后合并结果。分片时如果用户未传 `--limit`，自动注入 `limit: 10000`（API 上限）避免默认 6000 截断。
 - **Token 内存缓存**：Token 在进程内存中缓存，避免每次请求读盘。
@@ -321,15 +329,18 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 - `vault record-list`
 - `vault my-conference-list`
 - `vault wechat-message-list`
+- `vault wechat-chatroom-list`（特例：接口无 `total`，CLI 串行翻页）
 - `ai hot-topic`
 
 规则：
-- **有时间范围时**（传了 `--start-time/--end-time` 或 `--start-date/--end-date`）：**省略 `--size`**，CLI 自动翻页查全
-- **无时间范围时**（未传时间参数）：默认 `--size 200`，防止一次查询数据量过大
+- **省略 `--size` 一律拉全量**（无论是否传时间范围），CLI 自动翻页查完
+- 数据量未知时，可先 `--size 1` 从 stderr 的 `Total: N` 探明量级，再决定是否全量
 - 如果显式传了 `--size`，则按指定值翻页，直到达到 `size` 或数据取完
 - `--from` 必须是非负整数，`--size` 必须是正整数；非法数字会在本地直接报 `ValidationError`，不会继续请求 API
 - 安全上限：自动翻页最多 1000 页，防止异常循环
-- 分页结果中 `total` 字段会被保留（json 格式输出 `{total, list}`），同时 stderr 输出 `Total: N, showing: M`
+- 部分页失败、或服务端实际返回行数与 `total` 矛盾（提前短页）时，不丢弃已取到的数据：结果带 `partial: true`（页失败时另有 `failedPages`；K线分片为 `failedShards`；`--format json` 可见），stderr 输出警告，**进程退出码为 3**（完整成功为 0）
+- 分页结果中 `total` 字段会被保留（json 格式输出 `{total, list}`）；其他格式下 stderr 输出 `Total: N, showing: M`（json 格式不输出该行）
+- `vault wechat-chatroom-list` 是特例：接口不返回 `total`，CLI 改为串行翻页——省略 `--size` 拉全量、传 `--size N` 取前 N 条，单页 50，无 `Total:` 提示
 
 ## 智能文件命名
 
@@ -353,11 +364,11 @@ gangtise auth status
 ### Insight
 
 ```bash
-# 有时间范围 → 省略 --size，自动查全
+# 省略 --size → 自动翻页查全
 gangtise insight research list --start-time "2026-04-01 00:00:00" --end-time "2026-04-09 23:59:59"
 
-# 无时间范围 → 默认 --size 200
-gangtise insight research list --industry 100800126 --category company --llm-tag inDepth --rating buy
+# 无时间范围也是拉全量；只要前 200 条就显式传 --size
+gangtise insight research list --industry 100800126 --category company --llm-tag inDepth --rating buy --size 200
 
 # 多值 List 模式：一次查多家券商 + 多个行业 + 多个评级
 gangtise insight research list --broker C100000027 --broker C100000014 --industry 100800119 --industry 100800118 --rating buy --rating overweight --format json
@@ -535,7 +546,7 @@ gangtise ai management-discuss-earnings-call --report-date 2025-06-30 --security
 gangtise ai viewpoint-debate --viewpoint "飞天茅台的批价低点是1500元"
 # 等待生成完成后查询结果
 gangtise ai viewpoint-debate-check --data-id 202603310528
-# 也可以 --wait 同步等待结果（最长3分钟）
+# 也可以 --wait 同步等待结果（最长约 5 分钟：14 次指数退避轮询，累计 ≈316s）
 gangtise ai viewpoint-debate --viewpoint "比亚迪股价将突破500元" --wait
 gangtise ai knowledge-resource-download --resource-type 60 --source-id 3052524 --output ./resource.txt
 ```

package/dist/src/cli.js

@@ -7,7 +7,7 @@ import { buildIndicatorCrossSectionBody, buildIndicatorTimeSeriesBody, buildQuot
 import { flattenCrossSection, flattenTimeSeries, unwrapIndicatorData } from "./core/indicatorMatrix.js";
 import { callKlineWithSharding } from "./core/quoteSharding.js";
 import { loadConfig } from "./core/config.js";
-import { resolveTitle, saveDownloadResult } from "./core/download.js";
+import { resolveTitle, saveDownloadResult, uniquePath } from "./core/download.js";
 import { ENDPOINTS } from "./core/endpoints.js";
 import { ApiError, ConfigError, ValidationError } from "./core/errors.js";
 import { normalizeRows } from "./core/normalize.js";
@@ -25,8 +25,11 @@ async function createClient() {
  * query command repeated.
  */
 async function emit(options, produce, cache) {
+    // Validate --format before fetching: a typo'd format must not burn a full
+    // (possibly credit-metered) data pull only to fail at render time.
+    const format = parseOutputFormat(options.format);
     const client = await createClient();
-    await printData(await produce(client), parseOutputFormat(options.format), options.output, cache);
+    await printData(await produce(client), format, options.output, cache);
 }
 /** Acquire a client and run an arbitrary action (downloads, polling, custom shaping). */
 async function withClient(fn) {
@@ -45,7 +48,8 @@ async function runDownload(client, endpointKey, query, options) {
     }
     const result = await client.call(endpointKey, undefined, query);
     const resolved = options.resolveOutputPath ? await options.resolveOutputPath(result) : undefined;
-    await saveDownloadResult(result, options.fallbackName, resolved);
+    // Title-derived names are auto-generated too — dedupe them like the fallback names.
+    await saveDownloadResult(result, options.fallbackName, resolved ? await uniquePath(resolved) : undefined);
 }
 /**
  * Register a download subcommand. All download commands share one shape: a
@@ -326,6 +330,7 @@ addFinancialReport("balance-sheet-us", "fundamental.balance-sheet-us", "Period:
 addFinancialReport("cash-flow-us", "fundamental.cash-flow-us", "Period: q1/h1/q3/nsd/annual/latest");
 fundamental.command("main-business").requiredOption("--security-code <code>").option("--start-date <date>").option("--end-date <date>").addOption(new Option("--breakdown <type>", "Breakdown: product/industry/region").choices(["product", "industry", "region"]).default("product")).option("--period <type>", "Period: interim/annual", collectList, []).option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("fundamental.main-business", { securityCode: options.securityCode, startDate: options.startDate, endDate: options.endDate, breakdown: options.breakdown, periodList: maybeArray(options.period), fieldList: maybeArray(options.field) })));
 fundamental.command("valuation-analysis").requiredOption("--security-code <code>").addOption(new Option("--indicator <name>", "Indicator").choices(["peTtm", "pbMrq", "peg", "psTtm", "pcfTtm", "em"]).makeOptionMandatory()).option("--start-date <date>").option("--end-date <date>").option("--limit <number>").option("--field <field>", "Field", collectList, []).option("--skip-null", "Drop rows where value or percentileRank is null").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
+    const format = parseOutputFormat(options.format);
     let data = await client.call("fundamental.valuation-analysis", { securityCode: options.securityCode, indicator: options.indicator, startDate: options.startDate, endDate: options.endDate, limit: parseOptionalNumberOption(options.limit, "--limit", { integer: true, min: 1 }), fieldList: maybeArray(options.field) });
     if (options.skipNull) {
         const normalized = normalizeRows(data);
@@ -342,12 +347,14 @@ fundamental.command("valuation-analysis").requiredOption("--security-code <code>
             }
         }
     }
-    await printData(data, parseOutputFormat(options.format), options.output);
+    await printData(data, format, options.output);
 }));
 fundamental.command("top-holders").requiredOption("--security-code <code>").addOption(new Option("--holder-type <type>", "Holder type: top10/top10Float").choices(["top10", "top10Float"]).makeOptionMandatory()).option("--start-date <date>").option("--end-date <date>").option("--fiscal-year <year>", "Fiscal year", collectList, []).option("--period <period>", "Period: q1/interim/q3/annual/latest", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("fundamental.top-holders", { securityCode: options.securityCode, holderType: options.holderType, startDate: options.startDate, endDate: options.endDate, fiscalYear: maybeArray(options.fiscalYear), period: options.period.length ? options.period : undefined })));
 fundamental.command("earning-forecast").requiredOption("--security-code <code>").option("--start-date <date>", "Start date (default: 1 year before end-date)").option("--end-date <date>", "End date (default: today)").option("--consensus <name>", "Consensus indicator: netIncome/netIncomeYoy/eps/pe/bps/pb/peg/roe/ps", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => {
     const endDate = options.endDate ?? new Date().toISOString().slice(0, 10);
-    const startDate = options.startDate ?? new Date(Date.now() - 365 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+    // Anchor the default window to endDate (as the help text promises), not to today —
+    // a historical --end-date without --start-date should mean "the year before it".
+    const startDate = options.startDate ?? new Date(new Date(`${endDate}T00:00:00Z`).getTime() - 365 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
     return client.call("fundamental.earning-forecast", { securityCode: options.securityCode, startDate, endDate, consensusList: maybeArray(options.consensus) });
 }));
 program.addCommand(fundamental);
@@ -367,7 +374,8 @@ ai.command("security-clue").option("--from <number>", "Starting offset", "0").op
 ai.command("one-pager").requiredOption("--security-code <code>").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => emit(options, (client) => client.call("ai.one-pager", { securityCode: options.securityCode })));
 ai.command("investment-logic").requiredOption("--security-code <code>").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => emit(options, (client) => client.call("ai.investment-logic", { securityCode: options.securityCode })));
 ai.command("peer-comparison").requiredOption("--security-code <code>").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => emit(options, (client) => client.call("ai.peer-comparison", { securityCode: options.securityCode })));
-ai.command("earnings-review").requiredOption("--security-code <code>").requiredOption("--period <period>", "Report period (e.g. 2025q3, 2025interim, 2025annual)").option("--wait", "Wait for content generation (blocking, up to 3 min)").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => withClient(async (client) => {
+ai.command("earnings-review").requiredOption("--security-code <code>").requiredOption("--period <period>", "Report period (e.g. 2025q3, 2025interim, 2025annual)").option("--wait", "Wait for content generation (blocking, up to ~5 min)").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => withClient(async (client) => {
+    const format = parseOutputFormat(options.format);
     const idResult = await client.call("ai.earnings-review.get-id", { securityCode: options.securityCode, period: options.period });
     const dataId = idResult?.dataId;
     if (!dataId) {
@@ -381,8 +389,13 @@ ai.command("earnings-review").requiredOption("--security-code <code>").requiredO
         return;
     }
     process.stderr.write(`Got dataId: ${dataId}, waiting for content generation...\n`);
-    if (!await pollAsyncContent(client, "ai.earnings-review.get-content", dataId, parseOutputFormat(options.format), options.output)) {
-        process.stderr.write(`Content not available after ${POLL_MAX_ATTEMPTS} attempts. Try again later with: gangtise ai earnings-review-check --data-id ${dataId}\n`);
+    const outcome = await pollAsyncContent(client, "ai.earnings-review.get-content", dataId, format, options.output);
+    if (outcome !== "ok") {
+        // "failed" already printed its terminal "Do not retry" line — only a timeout
+        // gets the retry hint.
+        if (outcome === "timeout") {
+            process.stderr.write(`Content not available after ${POLL_MAX_ATTEMPTS} attempts. Try again later with: gangtise ai earnings-review-check --data-id ${dataId}\n`);
+        }
         process.exitCode = 1;
     }
 }));
@@ -414,7 +427,8 @@ ai.command("management-discuss-earnings-call").requiredOption("--report-date <da
     securityCode: options.securityCode,
     discussionDimension: options.dimension,
 })));
-ai.command("viewpoint-debate").requiredOption("--viewpoint <text>", "Viewpoint text (max 1000 chars)").option("--wait", "Wait for content generation (blocking, up to 3 min)").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => withClient(async (client) => {
+ai.command("viewpoint-debate").requiredOption("--viewpoint <text>", "Viewpoint text (max 1000 chars)").option("--wait", "Wait for content generation (blocking, up to ~5 min)").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => withClient(async (client) => {
+    const format = parseOutputFormat(options.format);
     const idResult = await client.call("ai.viewpoint-debate.get-id", { viewpoint: options.viewpoint });
     const dataId = idResult?.dataId;
     if (!dataId) {
@@ -428,8 +442,11 @@ ai.command("viewpoint-debate").requiredOption("--viewpoint <text>", "Viewpoint t
         return;
     }
     process.stderr.write(`Got dataId: ${dataId}, waiting for content generation...\n`);
-    if (!await pollAsyncContent(client, "ai.viewpoint-debate.get-content", dataId, parseOutputFormat(options.format), options.output)) {
-        process.stderr.write(`Content not available after ${POLL_MAX_ATTEMPTS} attempts. Try again later with: gangtise ai viewpoint-debate-check --data-id ${dataId}\n`);
+    const outcome = await pollAsyncContent(client, "ai.viewpoint-debate.get-content", dataId, format, options.output);
+    if (outcome !== "ok") {
+        if (outcome === "timeout") {
+            process.stderr.write(`Content not available after ${POLL_MAX_ATTEMPTS} attempts. Try again later with: gangtise ai viewpoint-debate-check --data-id ${dataId}\n`);
+        }
         process.exitCode = 1;
     }
 }));
@@ -471,7 +488,7 @@ addDownloadCommand(vault, { endpointKey: "vault.record.download", name: "record-
 vault.command("my-conference-list").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").option("--start-time <datetime>").option("--end-time <datetime>").option("--keyword <text>").option("--research-area <id>", "Research area ID", collectList, []).option("--security <code>", "Security code", collectList, []).option("--institution <id>", "Institution ID", collectList, []).option("--category <name>", "Conference category: earningsCall/strategyMeeting/fundRoadshow/shareholdersMeeting/maMeeting/specialMeeting/companyAnalysis/industryAnalysis/other", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("vault.my-conference.list", { from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword, researchAreaList: maybeArray(options.researchArea), securityList: maybeArray(options.security), institutionList: maybeArray(options.institution), categoryList: maybeArray(options.category) }), { endpointKey: "vault.my-conference.list", idField: "conferenceId" }));
 addDownloadCommand(vault, { endpointKey: "vault.my-conference.download", name: "my-conference-download", idOption: "--conference-id", idField: "conferenceId", fallbackPrefix: "conference", contentTypeDescription: "Content type: asr/summary", titleListEndpoint: "vault.my-conference.list" });
 vault.command("wechat-message-list").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").option("--start-time <datetime>").option("--end-time <datetime>").option("--keyword <text>").option("--security <code>", "Security code (e.g. 000001.SZ)", collectList, []).option("--wechat-group-id <id>", "WeChat group ID", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--category <name>", "Message type: text/image/documents/url", collectList, []).option("--tag <name>", "Tag: roadShow/research/strategyMeeting/meetingSummary/industryComment/companyComment/earningsReview", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("vault.wechat-message.list", buildWechatMessageListBody(options))));
-vault.command("wechat-chatroom-list").option("--from <number>", "Starting offset", "0").option("--size <number>", "Rows to return", "20").option("--room-name <name>", "WeChat group name; repeat or comma-separate for multiple names", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("vault.wechat-chatroom.list", buildWechatChatroomListBody(options))));
+vault.command("wechat-chatroom-list").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").option("--room-name <name>", "WeChat group name; repeat or comma-separate for multiple names", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("vault.wechat-chatroom.list", buildWechatChatroomListBody(options))));
 vault.command("stock-pool-list").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("vault.stock-pool.list", {})));
 vault.command("stock-pool-stocks").option("--pool-id <id>", "Pool ID; repeat for multiple; omit (or 'all') for all pools", collectList).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("vault.stock-pool.stocks", buildStockPoolStocksBody(options))));
 program.addCommand(vault);
@@ -482,6 +499,7 @@ alternative.command("edb-search").requiredOption("--keyword <text>", "Search key
     limit: parseNumberOption(options.limit, "--limit", { integer: true, min: 1 }),
 })));
 alternative.command("edb-data").option("--indicator-id <id>", "Indicator ID (repeat, max 10)", collectList, []).requiredOption("--start-date <date>", "Start date (yyyy-MM-dd)").requiredOption("--end-date <date>", "End date (yyyy-MM-dd)").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
+    const format = parseOutputFormat(options.format);
     const raw = await client.call("alternative.edb-data", {
         indicatorIdList: options.indicatorId,
         startDate: options.startDate,
@@ -495,26 +513,29 @@ alternative.command("edb-data").option("--indicator-id <id>", "Indicator ID (rep
         }, {}));
         data = { list, total: list.length };
     }
-    await printData(data, parseOutputFormat(options.format), options.output);
+    await printData(data, format, options.output);
 }));
 alternative.command("concept-info").requiredOption("--concept-id <id>", "Concept (theme index) ID, e.g. 121000130 机器人; discover via 'gangtise reference concept-search'").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => emit(options, (client) => client.call("alternative.concept-info", { conceptId: options.conceptId })));
 alternative.command("concept-securities").requiredOption("--concept-id <id>", "Concept (theme index) ID, e.g. 121000130 机器人; discover via 'gangtise reference concept-search'").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => emit(options, (client) => client.call("alternative.concept-securities", { conceptId: options.conceptId })));
 program.addCommand(alternative);
 const indicator = new Command("indicator").description("Data indicator (EDE) APIs: search codes, cross-section, time-series");
 indicator.command("search").requiredOption("--keyword <text>", "Search keyword, e.g. '收盘价' '成交量' '营业收入' (not free-form questions)").option("--limit <number>", "Max results (default: 50, max: 100)", "50").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
+    const format = parseOutputFormat(options.format);
     const raw = await client.call("indicator.search", {
         keyword: options.keyword,
         limit: parseNumberOption(options.limit, "--limit", { integer: true, min: 1 }),
     });
-    await printData(unwrapIndicatorData(raw), parseOutputFormat(options.format), options.output);
+    await printData(unwrapIndicatorData(raw), format, options.output);
 }));
 indicator.command("cross-section").option("--indicator <code>", "Indicator code, e.g. qte_close (repeat for multiple)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH (repeat for multiple)", collectList, []).requiredOption("--date <date>", "Data date (yyyy-MM-dd)").option("--currency <code>", "Currency: DFT/CNY/HKD/USD/EUR/GBP/JPY/TWD/MOP/AUD (default DFT)").option("--scale <code>", "Scale: 0=个 3=千 4=万 6=百万 8=亿 9=十亿 (default 0)").option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustmentType=2 for 前复权 (repeat)", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
+    const format = parseOutputFormat(options.format);
     const raw = await client.call("indicator.cross-section", buildIndicatorCrossSectionBody(options));
-    await printData(flattenCrossSection(unwrapIndicatorData(raw)), parseOutputFormat(options.format), options.output);
+    await printData(flattenCrossSection(unwrapIndicatorData(raw)), format, options.output);
 }));
 indicator.command("time-series").option("--indicator <code>", "Indicator code, e.g. qte_close (repeat for multiple)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH (repeat for multiple)", collectList, []).requiredOption("--start-date <date>", "Start date (yyyy-MM-dd)").requiredOption("--end-date <date>", "End date (yyyy-MM-dd)").option("--calendar-type <type>", "Calendar: ND=natural TD=trading WD=weekday (default TD)").option("--currency <code>", "Currency: DFT/CNY/HKD/USD/EUR/GBP/JPY/TWD/MOP/AUD (default DFT)").option("--scale <code>", "Scale: 0=个 3=千 4=万 6=百万 8=亿 9=十亿 (default 0)").option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustmentType=2 for 前复权 (repeat)", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
+    const format = parseOutputFormat(options.format);
     const raw = await client.call("indicator.time-series", buildIndicatorTimeSeriesBody(options));
-    await printData(flattenTimeSeries(unwrapIndicatorData(raw)), parseOutputFormat(options.format), options.output);
+    await printData(flattenTimeSeries(unwrapIndicatorData(raw)), format, options.output);
 }));
 program.addCommand(indicator);
 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) => {
@@ -522,6 +543,7 @@ program.command("raw").description("Raw API calls").addCommand(new Command("call
     if (!endpoint) {
         throw new ConfigError(`Unknown endpoint key: ${endpointKey}`);
     }
+    const format = parseOutputFormat(options.format);
     const client = await createClient();
     let body;
     if (options.body) {
@@ -532,39 +554,46 @@ program.command("raw").description("Raw API calls").addCommand(new Command("call
             throw new ConfigError(`Invalid JSON in --body: ${options.body}`);
         }
     }
+    // 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`);
+        }
         await runDownload(client, endpointKey, options.query, {
             output: options.output,
             fallbackName: "download.bin",
         });
         return;
     }
-    const data = await client.call(endpointKey, body, options.query);
-    await printData(data, parseOutputFormat(options.format), options.output);
+    if (Object.keys(options.query).length > 0) {
+        throw new ValidationError(`--query is not supported for JSON endpoints (use --body '{...}'); ${endpointKey} is kind=json`);
+    }
+    const data = await client.call(endpointKey, body);
+    await printData(data, format, options.output);
 }));
 async function checkForUpdate(timeoutMs = 2000) {
-    const https = await import("node:https");
-    await new Promise((resolve) => {
-        const req = https.get("https://registry.npmjs.org/gangtise-openapi-cli/latest", (res) => {
-            let body = "";
-            res.on("data", (chunk) => { body += chunk; });
-            res.on("end", () => {
-                try {
-                    const latest = JSON.parse(body).version;
-                    if (latest && latest !== CLI_VERSION) {
-                        process.stderr.write(`Update available: ${CLI_VERSION} → ${latest}\nRun: npm update -g gangtise-openapi-cli\n`);
-                    }
-                }
-                catch { /* ignore */ }
-                resolve();
-            });
-        });
-        req.on("error", () => resolve());
-        req.setTimeout(timeoutMs, () => { req.destroy(); resolve(); });
-    });
+    try {
+        const response = await fetch("https://registry.npmjs.org/gangtise-openapi-cli/latest", { signal: AbortSignal.timeout(timeoutMs) });
+        const latest = (await response.json()).version;
+        if (latest && latest !== CLI_VERSION) {
+            process.stderr.write(`Update available: ${CLI_VERSION} → ${latest}\nRun: npm update -g gangtise-openapi-cli\n`);
+        }
+    }
+    catch { /* best-effort: offline or a slow registry must not break --version */ }
 }
+// `gangtise ... | head` closes stdout early; without a handler the final big write
+// crashes Node with an unhandled 'error' event. Exit quietly like a normal CLI.
+process.stdout.on("error", (error) => {
+    if (error?.code === "EPIPE")
+        process.exit(0);
+    throw error;
+});
 async function main() {
-    if (process.argv.includes("--version") || process.argv.includes("-V")) {
+    // Positional check, not argv.includes: "--version" appearing later (e.g. as
+    // another option's value) must not short-circuit the whole command.
+    const firstArg = process.argv[2];
+    if (firstArg === "--version" || firstArg === "-V") {
         process.stdout.write(`${CLI_VERSION}\n`);
         await checkForUpdate();
         return;

package/dist/src/core/args.js

@@ -1,7 +1,9 @@
 import { ValidationError } from "./errors.js";
 export function splitCsv(value) {
+    // Also split on full-width "，": voice-input IMEs produce it, and an unsplit
+    // "600519，000858" goes to the API as one bogus code with no local hint.
     return value
-        .split(",")
+        .split(/[,，]/)
         .map((item) => item.trim())
         .filter(Boolean);
 }
@@ -42,12 +44,12 @@ export function collectNumberList(value, previous = []) {
 export function collectKeyValue(value, previous = {}) {
     const index = value.indexOf("=");
     if (index === -1) {
-        throw new Error(`Invalid key=value pair: ${value}`);
+        throw new ValidationError(`Invalid key=value pair: ${value}`);
     }
     const key = value.slice(0, index).trim();
     const rawValue = value.slice(index + 1).trim();
     if (!key) {
-        throw new Error(`Invalid key=value pair: ${value}`);
+        throw new ValidationError(`Invalid key=value pair: ${value}`);
     }
     return {
         ...previous,
@@ -65,6 +67,16 @@ export function toTimestamp13(value) {
         return num;
     if (!Number.isNaN(num) && num > 1e9)
         return num * 1000;
+    // `new Date("yyyy-MM-dd")` parses as UTC midnight while `new Date("yyyy-MM-dd HH:mm:ss")`
+    // parses as local time — for CST users the two forms would differ by 8 hours and
+    // silently shift the query window. Anchor date-only input to local midnight so both
+    // forms mean the same wall-clock day.
+    const dateOnly = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    if (dateOnly) {
+        const d = new Date(Number(dateOnly[1]), Number(dateOnly[2]) - 1, Number(dateOnly[3]));
+        const valid = d.getMonth() === Number(dateOnly[2]) - 1 && d.getDate() === Number(dateOnly[3]);
+        return valid ? d.getTime() : undefined;
+    }
     const ms = new Date(value).getTime();
     if (Number.isNaN(ms))
         return undefined;

package/dist/src/core/asyncContent.js

@@ -1,10 +1,9 @@
 import { ApiError } from "./errors.js";
 import { printData } from "./printer.js";
+// 14 attempts with exponential backoff (5s→30s cap) ≈ 316s total wait budget.
 export const POLL_MAX_ATTEMPTS = 14;
 const POLL_INITIAL_DELAY_MS = 5_000;
 const POLL_MAX_DELAY_MS = 30_000;
-/** Total wait time stays close to the previous 12*15s=180s budget. */
-export const POLL_DELAY_MS = POLL_INITIAL_DELAY_MS;
 function nextDelayMs(attempt) {
     // 5s, 8s, 13s, 20s, 30s, 30s, ...
     const grown = POLL_INITIAL_DELAY_MS * 1.6 ** (attempt - 1);
@@ -19,13 +18,13 @@ export async function pollAsyncContent(client, getContentEndpoint, dataId, forma
             const result = await client.call(getContentEndpoint, { dataId });
             if (result?.content != null) {
                 await printData(result, format, output);
-                return true;
+                return "ok";
             }
         }
         catch (error) {
             if (error instanceof ApiError && error.code === "410111") {
                 process.stderr.write("Content generation failed (terminal). Do not retry.\n");
-                return false;
+                return "failed";
             }
             if (!isAsyncPending(error))
                 throw error;
@@ -36,7 +35,7 @@ export async function pollAsyncContent(client, getContentEndpoint, dataId, forma
             await new Promise(resolve => setTimeout(resolve, delay));
         }
     }
-    return false;
+    return "timeout";
 }
 export async function checkAsyncContent(client, getContentEndpoint, dataId, format, output) {
     try {

package/dist/src/core/auth.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { ConfigError } from "./errors.js";
@@ -33,7 +34,20 @@ export function redactTokenCache(cache) {
 }
 export async function writeTokenCache(filePath, cache) {
     await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await fs.writeFile(filePath, JSON.stringify(cache, null, 2), { encoding: "utf8", mode: 0o600 });
+    // Write to a fresh 0600 temp file then rename over the target. Writing the bearer
+    // token straight to token.json would (a) keep an existing file's lax perms — the
+    // `mode` option only applies on creation, so a follow-up chmod still leaves a brief
+    // world-readable window — and (b) risk a truncated file on crash. A temp file is
+    // 0600 from the first byte and rename is atomic, carrying the 0600 perms over.
+    const tmp = `${filePath}.tmp-${randomUUID()}`;
+    await fs.writeFile(tmp, JSON.stringify(cache, null, 2), { encoding: "utf8", mode: 0o600 });
+    try {
+        await fs.rename(tmp, filePath);
+    }
+    catch (error) {
+        await fs.unlink(tmp).catch(() => { });
+        throw error;
+    }
 }
 export function isTokenCacheValid(cache, bufferSeconds = 300) {
     if (!cache?.accessToken || !cache.expiresAt) {
@@ -43,7 +57,10 @@ export function isTokenCacheValid(cache, bufferSeconds = 300) {
     return cache.expiresAt - bufferSeconds > now;
 }
 export function normalizeToken(token) {
-    return token.startsWith("Bearer ") ? token : `Bearer ${token}`;
+    // Case-insensitive prefix check: GANGTISE_TOKEN="bearer xxx" must become
+    // "Bearer xxx", not the silently-invalid "Bearer bearer xxx".
+    const prefix = /^bearer\s+/i.exec(token);
+    return `Bearer ${prefix ? token.slice(prefix[0].length) : token}`;
 }
 export function requireAccessCredentials(accessKey, secretKey) {
     if (!accessKey || !secretKey) {