gangtise-openapi-cli 0.25.0 → 0.27.0

package/README.md

@@ -4,6 +4,49 @@
 
 ## Changelog
 
+### v0.27.0 — 2026-07-11
+
+**EDE 指标（体验修复）**
+- `indicator` 三端点对 `999999` 不再自动重试——实测服务端用 `999999` + HTTP 500 表示「查询无数据」（节假日 / 未来日期 / 未覆盖标的），此前每次空查询白烧 3 个请求 + ~4 秒；错误提示改为指向检查查询条件而非「稍后重试」
+
+**资金与下载加固（承接 v0.26.0）**
+- 下载路径同样接入重试策略：50/篇 的 `summary` / `foreign-report` / `my-conference` download 改为 no-replay（与 AI Agent 同价档；下载中断重试可能重复计费），10-30/篇 的下载维持默认重试
+- 签名 URL 下载增加整体硬截止（10× 单请求超时）——headers/body 超时是空闲型，慢滴速传输可无限续命；最终 rename 失败时清理 `.part`
+- `GANGTISE_PAGE_CONCURRENCY` 防御性解析：非法/非正数回退默认 5、上限 32——负值此前被底层钳制成**单 worker 串行**（静默变慢），过大值可能造成过度并发触发限流
+- `--version` 更新提示改为数值分段版本比较（不处理预发布号；本项目只发 x.y.z）——刚发版的 registry 滞后窗口不再把旧版本提示成"可更新"
+
+**体验与正确性小修**
+- `--wait` 异步轮询容忍瞬态错误：5xx/网络抖动只消耗一次尝试并继续等待，不再作废整段等待（积分不足等终态错误仍立即中止）
+- table 输出单元格显示宽度上限 120（超长截断加 `…`）——一个超长字段不再把整列所有行 pad 成同宽（行数 × 宽度的空格放大）
+- markdown 输出先转义反斜杠再转义竖线，字面 `\|` 单元格不再错位列；table/markdown 过滤 C1 控制符（U+009B 单字节 CSI 注入面）
+- 自动文件名按码点截断，emoji 不再被截成 `�`；EDE 矩阵中与 `date`/`security`/`name` 同名的指标列自动加后缀，不再覆盖元数据列
+- 全市场分片截断时输出 `truncatedShards`（具体日期区间，与 `failedShards` 对称），脚本/AI 消费者可定向缩窗补拉
+- 分页端点首页形状漂移（如 `total` 变字符串）时 `--verbose` 下告警，不再完全静默退化单页
+
+**Skill 分发**
+- `gangtise-openapi/` 目录纳入 npm 包；README 安装命令改为从 `$(npm root -g)` 复制——此前的相对路径命令对 npm 用户不可执行
+
+**防漂移门禁（工程，不影响 CLI 行为）**
+- 新增 README↔ENDPOINTS 一致性测试：「自动翻页」清单与注册表 pagination 标记双向比对（此类手抄清单漂移已发生两次）；insight/reference 子命令的 `--help` 覆盖改为从端点注册表派生，新命令漏接线直接测试失败
+- `npm run prepare` 前置断言 README/CHANGELOG 含当前版本条目（写盘前检查，失败零残留）；`npm run typecheck` 纳入 tests/（tsconfig.test.json）
+- CI：`npm pack` 装包冒烟（`--help` + skill 文件存在校验）、测试矩阵 Node 下限改精确 20.18.1、CI typecheck；publish 的 `workflow_dispatch` 必须指向 `v*` tag（关闭无护栏发布通道）
+
+### v0.26.0 — 2026-07-11
+
+**资金安全（重要）**
+- 13 个贵档端点（`one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `theme-tracking` / `management-discuss-*`×2 / `hot-topic` / `knowledge-batch` / `earnings-review get-id` / `viewpoint-debate get-id` / `concept-info` / `concept-securities`）改为 **no-replay 重试策略**：5xx / 超时 / `999999` 不再自动重放——实测（2026-07-11）平台按次计费且**缓存命中不豁免**，同参数重放每次都扣分；仅连接期错误（`ECONNREFUSED`/DNS，请求未发出）、429 限流和 token 自愈仍重试。便宜按条计费的 list 类维持原全量重试（失败响应没有数据行、不计费）
+- 连接失败 `ECONNREFUSED` / `UND_ERR_CONNECT_TIMEOUT` 纳入默认重试范围（此前这两类不重试）
+
+**文件安全**
+- 所有 `--output` 落盘（导出、流式下载主路径、签名 URL 跟随下载）改为原子写：先写同目录 `.part` 成功后 rename——重跑失败不再毁掉已有旧文件；顺带修掉中止路径上 `.part` 因流懒打开竞态残留的问题
+- 签名 URL 跟随下载改走 transport 层：遵守 `GANGTISE_TIMEOUT_MS`（此前裸 `fetch` 无超时，慢滴速 CDN 可无限挂起）、网络错误自动重试、跟随最多 3 跳重定向（undici 不自动跟随，超限/缺 `Location` 报错而非把跳转页存成文件）、`--verbose` 日志剥离签名 query 只留 origin+path
+- 自动命名去重后缀试尽 `-1`…`-99` 仍冲突时报错，不再静默覆盖最早的文件
+
+**修复 / 加固**
+- 下载重定向超过 3 跳或缺 `Location` 时报错，不再把跳转页 HTML 当文件内容保存
+- 损坏的 gzip 响应包装为带请求上下文的 `ApiError`（此前抛裸 zlib `Z_DATA_ERROR`，与请求无关联且不可定位）
+- `alternative edb-search --limit` ≤200、`indicator search --limit` ≤100 本地上限校验——实测服务端对超限值静默截断（201→200、101→100），与 v0.25.0 的 `--top` 同类同修法
+
 ### v0.25.0 — 2026-07-10
 
 **新增接口（4）**
@@ -52,39 +95,6 @@
 - `reference institution-search` — 机构 ID 搜索，输入机构名/简称返回 `institutionId` 及适用接口参数（`usageScopes`）；`--keyword`（必填）、`--category`（`domesticBroker`/`foreignInstitution`/`leadInstitution`/`opinionInstitution`/`foreignOpinionInstitution`，可重复）、`--top`（默认 10，上限 10）；免费。覆盖既有 `--broker`/`--institution` 全部机构类（research/foreign-report/opinion/foreign-opinion/summary/roadshow/site-visit/strategy/my-conference）
 - `vault my-conference-list` 新增 `--source` — 按录制来源筛选（`1`=企微会议助理 `2`=会议服务微信群，可重复；不传返回全部）
 
-### v0.22.1 — 2026-07-03
-
-**修复**
-- 错误码 `410004` 提示改为中性措辞「数据未找到或无指标权限，请检查查询条件与指标权限」——此前只说"数据未找到"，与 `indicator` 内层信封的"无权限"消息拼接后自相矛盾
-
-**文档 / Skill**（随 `/sync-skill` 分发，不影响 CLI 行为）
-- gangtise-openapi Agent Skill 经 fable5 审计 + 多轮 review 优化：官方积分计费速查表 + 高积分 pre-flight 闸门、AI 同步生成命令 `GANGTISE_TIMEOUT_MS=120000` 超时前置、大结果集 `--output` 落盘、异步 `--wait` 主路径、行业码口径收敛到单一权威、市值量纲实测（`qte_mkt_cptl` 仅 A 股 / 默认原始「元」/ `scale`+`currency`）等文档补全与消歧
-
-### v0.22.0 — 2026-07-02
-
-**行为变更（注意）**
-- ⚠️ 自动翻页接口省略 `--size` 现在一律拉全量（不再区分是否传时间范围）；需要只取前 N 条时请显式传 `--size N`。数据量未知时可先用 `--size 1` 从 stderr 的 `Total: N` 探明量级
-- 部分结果可机器识别：翻页页失败、K 线分片失败、或服务端提前短页但仍报告更大 `total` 时，结果会带 `partial: true`（页失败另有 `failedPages`，分片为 `failedShards`），非 json 行式输出仍只输出数据行，但进程退出码为 3
-
-**修复（鉴权 / 请求可靠性）**
-- Token 自愈覆盖服务端 `0000001008` 踢线失效，并能处理 HTTP 4xx 错误信封；`GANGTISE_TOKEN` + AK/SK 场景下环境 token 失效后不再反复回放旧 token
-- 并发请求同时遇到旧 token 失效时复用一次刷新结果；若刚拿到的新 token 本身被踢掉，则强制再次登录，避免"刚登录窗口期"误跳过刷新
-- 自动重试范围扩展到 429、DNS/网络临时错误与 undici 超时类错误；`GANGTISE_BASE_URL` 带路径前缀时 URL 拼接不再丢前缀
-
-**修复（下载 / 输出 / 数据正确性）**
-- 下载接口跟随最多 3 次 30x 跳转；跨域跳到对象存储签名 URL 时不携带 Authorization；服务端返回 `{url}` 且用户传 `--output` 时会真正下载文件，而不是把 URL 字符串写进文件
-- 自动文件名补齐清洗、截断与去重：服务端文件名、标题缓存名和 fallback 名都不会把 `/`、控制字符、过长中文名或重复标题变成路径/覆盖问题
-- `table`/`markdown` 输出清理控制字符、正确按 CJK 宽字符对齐，并转义 markdown 表头中的 `|`；CSV 输出转义表头、文件输出带 UTF-8 BOM，流式 CSV 遇全标量列表时回退到正常渲染而不是只写 BOM
-- `indicator search` / `cross-section` / `time-series` 的内层失败信封即使没有 `data` 字段也会抛出 `ApiError`，不再把"无权限/参数错误"渲染成成功结果
-- `--indicator-param` 等逗号列表支持全角逗号 `，`；日期型时间参数按本地零点解析，避免 `yyyy-MM-dd` 被当作 UTC 造成查询窗口偏移
-- `fundamental earning-forecast` 省略 `--start-date` 时按传入的 `--end-date` 往前一年计算，不再总是按今天往前一年
-- AI 异步 `--wait` 对 `410111` 终态失败只提示"不要重试"，超时才提示稍后用 check 命令查询；等待说明同步为最长约 5 分钟
-
-**CLI / 工程**
-- `raw call` 会在本地拒绝 JSON endpoint 的 `--query` 和 download endpoint 的 `--body`，避免静默丢参数；`--format` 在发请求前校验，格式拼错不再先消耗接口调用
-- `gangtise ... | head` 遇 stdout `EPIPE` 时安静退出；只有首个参数是 `--version` / `-V` 时才触发版本快捷路径
-- Endpoint registry 的 `key` 改为由记录键自动派生，减少映射漂移；新增真实 CLI 选项到请求体的 stub 测试；测试 272 → 323
-
 > 更早版本及完整更新历史见 [CHANGELOG.md](CHANGELOG.md)。
 
 ## 首次安装
@@ -105,6 +115,8 @@ gangtise --help
 npm update -g gangtise-openapi-cli
 ```
 
+> 更新后若使用 Agent Skill：包内 skill 已随包更新，但复制到 `~/.claude/skills/` 等目录的副本是快照，**需重新执行下方「安装」段的复制命令**才能让 AI 助手拿到新版 skill。
+
 本地开发：
 
 ```bash
@@ -125,7 +137,7 @@ export GANGTISE_BASE_URL="https://openapi.gangtise.com"
 export GANGTISE_TOKEN="Bearer xxx"
 
 # 性能/调试可选项
-export GANGTISE_PAGE_CONCURRENCY=5     # 翻页并发数（默认 5）
+export GANGTISE_PAGE_CONCURRENCY=5     # 翻页/分片并发数（默认 5，上限 32；非法值回退默认）
 export GANGTISE_VERBOSE=1              # 打印每个请求的耗时与字节数
 export GANGTISE_TIMEOUT_MS=30000       # 请求超时（默认 30s）
 export GANGTISE_TOKEN_CACHE_PATH=...   # 覆盖 token 缓存路径（默认 ~/.config/gangtise/token.json）
@@ -164,22 +176,26 @@ gangtise-openapi/
     └── response-schema.md            # 各接口响应字段说明
 ```
 
-安装：
+安装（skill 目录随 npm 包分发，`npm install -g` 之后即可从全局安装位置复制）：
 
 ```bash
+SKILL_SRC="$(npm root -g)/gangtise-openapi-cli/gangtise-openapi"
+
 # Claude Code
-cp -r gangtise-openapi ~/.claude/skills/gangtise-openapi
+cp -r "$SKILL_SRC" ~/.claude/skills/gangtise-openapi
 
 # Codex
-cp -r gangtise-openapi ~/.codex/skills/gangtise-openapi
+cp -r "$SKILL_SRC" ~/.codex/skills/gangtise-openapi
 
 # OpenClaw
-cp -r gangtise-openapi ~/.openclaw/skills/gangtise-openapi
+cp -r "$SKILL_SRC" ~/.openclaw/skills/gangtise-openapi
 
 # Hermes
-cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
+cp -r "$SKILL_SRC" ~/.hermes/skills/gangtise-openapi
 ```
 
+> 从仓库 clone 开发时，把 `$SKILL_SRC` 换成仓库内的 `gangtise-openapi` 目录即可。
+
 > **版本更新**：每次 CLI 发版时，`gangtise-openapi/SKILL.md` 的 `version` 字段会自动同步。更新 CLI 后，请将项目中的 `gangtise-openapi/` 目录重新复制到对应的 skills 目录覆盖更新：
 >
 > ```bash
@@ -311,7 +327,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 / 429 / `ECONNRESET` / `ETIMEDOUT` / `ENOTFOUND` / `EAI_AGAIN` / `UND_ERR_*`（undici 超时类）/ `999999` 系统错误自动指数退避重试 2 次。
+- **自动重试**：5xx / 429 / `ECONNREFUSED` / `ECONNRESET` / `ETIMEDOUT` / `ENOTFOUND` / `EAI_AGAIN` / `UND_ERR_*`（undici 连接/超时类）/ `999999` 系统错误自动指数退避重试 2 次。**贵档端点例外**（one-pager 等 13 个生成/提交类 + 50/篇 的 summary/foreign-report/my-conference 下载，共 16 个）：5xx/超时不重放——按次计费不幂等，重放即重复扣分；仅连接失败、429 与 token 自愈重试。**`indicator`（EDE）端点对 `999999` 不重试**——该码实为「查询无数据」（实测），重试纯浪费。
 - **Token 自愈**：调用返回 8000014/8000015 时自动强制刷新 Token 并重试一次。
 - **K线/资金流向自动分片**：`quote day-kline --security all`、`quote fund-flow --security aShares` 等全市场查询自动按日期切分（A股 K线/资金流向 1 天/片、美股 1 天/片、HK 2 天/片、指数 30 天/片），并发执行后合并结果；按日分片自动跳过周六日。分片时如果用户未传 `--limit`，自动注入 `limit: 10000`（API 上限）避免默认 6000 截断。
 - **Token 内存缓存**：Token 在进程内存中缓存，避免每次请求读盘。

package/dist/src/cli.js

@@ -2,7 +2,7 @@
 import { Command, Option } from "commander";
 import { checkAsyncContent, pollAsyncContent, POLL_MAX_ATTEMPTS } from "./core/asyncContent.js";
 import { readTokenCache, redactTokenCache } from "./core/auth.js";
-import { collectKeyValue, collectList, collectNumberList, localDateString, maybeArray, parseChoiceList, parseFrom, parseNumberOption, parseOptionalNumberOption, parseSize, parseTimestamp13 } from "./core/args.js";
+import { collectKeyValue, collectList, collectNumberList, isVersionNewer, localDateString, maybeArray, parseChoiceList, parseFrom, parseNumberOption, parseOptionalNumberOption, parseSize, parseTimestamp13 } from "./core/args.js";
 import { buildIndicatorCrossSectionBody, buildIndicatorTimeSeriesBody, buildQuoteKlineBody, buildStockPoolStocksBody, buildWechatChatroomListBody, buildWechatMessageListBody } from "./core/commandBodies.js";
 import { flattenCrossSection, flattenTimeSeries, unwrapIndicatorData } from "./core/indicatorMatrix.js";
 import { callKlineWithSharding, isAllMarket, isFullMarket } from "./core/quoteSharding.js";
@@ -601,7 +601,7 @@ program.addCommand(ai);
 const alternative = new Command("alternative").description("Alternative data APIs");
 alternative.command("edb-search").requiredOption("--keyword <text>", "Search keyword (e.g. '空调')").option("--limit <number>", "Max results (default: 100, max: 200)", "100").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("alternative.edb-search", {
     keyword: options.keyword,
-    limit: parseNumberOption(options.limit, "--limit", { integer: true, min: 1 }),
+    limit: parseNumberOption(options.limit, "--limit", { integer: true, min: 1, max: 200 }),
 })));
 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);
@@ -628,7 +628,7 @@ indicator.command("search").requiredOption("--keyword <text>", "Search keyword,
     const format = parseOutputFormat(options.format);
     const raw = await client.call("indicator.search", {
         keyword: options.keyword,
-        limit: parseNumberOption(options.limit, "--limit", { integer: true, min: 1 }),
+        limit: parseNumberOption(options.limit, "--limit", { integer: true, min: 1, max: 100 }),
     });
     await printData(unwrapIndicatorData(raw), format, options.output);
 }));
@@ -681,7 +681,9 @@ async function checkForUpdate(timeoutMs = 2000) {
     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) {
+        // Ordered compare, not inequality: during the just-published window the
+        // registry still serves the PREVIOUS version — don't suggest a "downgrade".
+        if (latest && isVersionNewer(latest, CLI_VERSION)) {
             process.stderr.write(`Update available: ${CLI_VERSION} → ${latest}\nRun: npm update -g gangtise-openapi-cli\n`);
         }
     }

package/dist/src/core/args.js

@@ -62,6 +62,23 @@ export function collectKeyValue(value, previous = {}) {
 export function maybeArray(value) {
     return value.length > 0 ? value : undefined;
 }
+/** True when `latest` is strictly newer than `current` (numeric per-segment
+ * compare). Plain inequality would nag "update available" during the
+ * just-published window while the registry still serves the previous version. */
+export function isVersionNewer(latest, current) {
+    const parse = (v) => v.split(".").map(Number);
+    const a = parse(latest);
+    const b = parse(current);
+    if (a.some(Number.isNaN) || b.some(Number.isNaN))
+        return false;
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x !== y)
+            return x > y;
+    }
+    return false;
+}
 // Whitelist for enum-valued repeatable options. Only used where the server was
 // probed NOT to reject bad values (it silently ignores the filter or returns
 // empty instead) — endpoints that answer 100003 keep server-side validation.

package/dist/src/core/asyncContent.js

@@ -1,5 +1,6 @@
 import { ApiError } from "./errors.js";
 import { printData } from "./printer.js";
+import { isTransientError } from "./transport.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;
@@ -26,8 +27,16 @@ export async function pollAsyncContent(client, getContentEndpoint, dataId, forma
                 process.stderr.write("Content generation failed (terminal). Do not retry.\n");
                 return "failed";
             }
-            if (!isAsyncPending(error))
-                throw error;
+            if (!isAsyncPending(error)) {
+                // AI generation windows are exactly when the server is busiest: one 5xx
+                // (after the client's own retries) must not void minutes of waiting —
+                // the dataId is still valid. Transient errors consume this attempt and
+                // polling continues; anything else (no credits, bad params) 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 = nextDelayMs(attempt);

package/dist/src/core/client.js

@@ -175,8 +175,14 @@ export class GangtiseClient {
             from: startFrom,
             size: firstPageSize,
         });
-        if (!this.isPaginatedListResponse(firstPage))
+        if (!this.isPaginatedListResponse(firstPage)) {
+            // Shape drift (e.g. total arriving as a string) silently degrades fetch-all
+            // to a single page with no partial marker — make it visible on verbose.
+            if (isVerbose()) {
+                process.stderr.write(`[gangtise] warning: ${endpoint.key} is marked paginated but the first page has an unexpected shape (no numeric total + list); returning it as-is\n`);
+            }
             return firstPage;
+        }
         const total = firstPage.total;
         const collected = [...firstPage.list];
         const available = Math.max(total - startFrom, 0);
@@ -354,9 +360,22 @@ export class GangtiseClient {
             // response reads as text directly (and keeps existing behavior on that path).
             const encoding = response.headers['content-encoding'];
             const gzipped = (Array.isArray(encoding) ? encoding[0] : encoding)?.toLowerCase().trim() === 'gzip';
-            const text = gzipped
-                ? decodeResponseBody(new Uint8Array(await response.body.arrayBuffer()), encoding)
-                : await response.body.text();
+            let text;
+            if (gzipped) {
+                // A proxy/middlebox can declare gzip and deliver garbage — surface that as
+                // an ApiError with request context instead of a bare zlib Z_DATA_ERROR.
+                const bytes = new Uint8Array(await response.body.arrayBuffer());
+                try {
+                    text = decodeResponseBody(bytes, encoding);
+                }
+                catch (error) {
+                    const detail = error instanceof Error ? error.message : String(error);
+                    throw new ApiError(`Failed to decode gzip response for ${endpoint.method} ${endpoint.path}: ${detail}`, undefined, response.statusCode);
+                }
+            }
+            else {
+                text = await response.body.text();
+            }
             logTiming(`${endpoint.method} ${endpoint.path}`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
             // Parse Retry-After once so every error path below (JSON parse failure AND the
             // envelope/HTTP-error throw) carries it — a non-JSON 429/503 must still honor
@@ -385,12 +404,21 @@ export class GangtiseClient {
                 throw error;
             }
         }, {
+            policy: endpoint.retry ?? "default",
             onRetry: (attempt, error, delay) => {
                 if (!isVerbose())
                     return;
                 const msg = error instanceof Error ? error.message : String(error);
                 process.stderr.write(`[gangtise] retry ${attempt} after ${delay.toFixed(0)}ms: ${msg.slice(0, 120)}\n`);
             },
+        }).catch((error) => {
+            // EDE uses 999999 for "no data for this query" (probed 2026-07-11) — the
+            // generic "系统错误，请稍后重试" hint would send the user retrying a query
+            // that will never have data. Swap in a context-specific hint.
+            if (endpoint.retry === 'no-999999' && error instanceof ApiError && error.code === '999999') {
+                throw new ApiError(error.message, error.code, error.statusCode, error.details, error.retryAfterMs, 'EDE 的 999999 多为查询无数据（节假日 / 未来日期 / 未覆盖标的）——先检查查询条件，确认应有数据再重试。');
+            }
+            throw error;
         });
     }
     async download(endpoint, query, options) {
@@ -434,6 +462,13 @@ export class GangtiseClient {
                     dispatcher,
                 });
             }
+            // The loop above can exit with a 3xx still in hand (hop limit exceeded, or a
+            // redirect without Location) — that response must never be treated as file
+            // content: its HTML placeholder body would be saved as the "downloaded file".
+            if (response.statusCode >= 300 && response.statusCode < 400) {
+                await response.body.text().catch(() => { });
+                throw new ApiError(`Download failed: unresolved redirect (HTTP ${response.statusCode})`, undefined, response.statusCode);
+            }
             const contentType = Array.isArray(response.headers['content-type']) ? response.headers['content-type'][0] : response.headers['content-type'];
             // From the final (post-redirect) response, so a rate-limited download honors
             // Retry-After too — every error branch below passes it into the ApiError.
@@ -499,14 +534,17 @@ export class GangtiseClient {
             // Stream directly to disk when caller already knows the destination
             if (options?.streamTo) {
                 await fs.mkdir(path.dirname(options.streamTo), { recursive: true });
+                // Stream into a .part sibling and rename over the target only on success:
+                // writing to the target directly would truncate an existing file on the
+                // FIRST byte and delete it on failure — a failed re-download (or each
+                // withRetry attempt) must never destroy the user's previous good file.
+                const partPath = `${options.streamTo}.part`;
                 try {
-                    await pipeline(response.body, createWriteStream(options.streamTo));
+                    await pipeline(response.body, createWriteStream(partPath));
+                    await fs.rename(partPath, options.streamTo);
                 }
                 catch (error) {
-                    // A mid-stream failure leaves a truncated file on disk; remove it so a
-                    // failed download never looks like a complete one. withRetry may still
-                    // replay the request (the next attempt re-creates the file).
-                    await fs.unlink(options.streamTo).catch(() => { });
+                    await fs.unlink(partPath).catch(() => { });
                     throw error;
                 }
                 logTiming(`GET ${endpoint.path} (stream)`, Date.now() - startedAt, `${response.statusCode}`);
@@ -520,6 +558,9 @@ export class GangtiseClient {
                 filename,
             };
         }, {
+            // Download endpoints carry per-篇 billing too (summary/foreign-report/
+            // my-conference at 50/篇) — honor the endpoint's retry policy here as well.
+            policy: endpoint.retry ?? "default",
             onRetry: (attempt, error, delay) => {
                 if (!isVerbose())
                     return;

package/dist/src/core/download.js

@@ -18,15 +18,19 @@ function truncateFilename(name, maxBytes = 200) {
     if (Buffer.byteLength(name, "utf8") <= maxBytes)
         return name;
     const ext = extname(name);
-    let stem = name.slice(0, name.length - ext.length);
-    while (stem.length > 1 && Buffer.byteLength(stem + ext, "utf8") > maxBytes)
-        stem = stem.slice(0, -1);
-    return stem + ext;
+    // Trim by code point, not UTF-16 unit: a cut inside a surrogate pair would put
+    // a lone surrogate in the name, which reaches the filesystem as U+FFFD (�).
+    const stem = [...name.slice(0, name.length - ext.length)];
+    while (stem.length > 1 && Buffer.byteLength(stem.join("") + ext, "utf8") > maxBytes)
+        stem.pop();
+    return stem.join("") + ext;
 }
 /** Pick a non-existing path by suffixing -1, -2, … before the extension, so batch
  * downloads whose titles collide ("2025年第一季度报告" from several companies) don't
  * silently overwrite each other. Only auto-derived names go through this — an
- * explicit --output path keeps plain overwrite semantics. */
+ * explicit --output path keeps plain overwrite semantics. Throws instead of
+ * falling back to the original path once the suffixes run out: returning `p`
+ * there would silently overwrite the very first file. */
 export async function uniquePath(p) {
     const exists = (f) => fs.access(f).then(() => true, () => false);
     if (!(await exists(p)))
@@ -38,7 +42,7 @@ export async function uniquePath(p) {
         if (!(await exists(candidate)))
             return candidate;
     }
-    return p;
+    throw new DownloadError(`Refusing to overwrite: 100 files already share the name "${p}" — pass --output or clean up the directory`);
 }
 const MIME_EXT = {
     "application/pdf": ".pdf",
@@ -106,19 +110,80 @@ export async function resolveTitle(client, result, listEndpoint, idField, idValu
 }
 async function downloadUrlTo(url, outputPath) {
     const { createWriteStream } = await import("node:fs");
-    const { Readable } = await import("node:stream");
     const { pipeline } = await import("node:stream/promises");
     const { dirname } = await import("node:path");
-    const response = await fetch(url);
-    if (!response.ok || !response.body) {
-        throw new DownloadError(`Failed to fetch download URL (HTTP ${response.status})`);
-    }
+    const { request } = await import("undici");
+    const { getDispatcher, logTiming, withRetry } = await import("./transport.js");
+    const { loadConfig } = await import("./config.js");
+    // Through the transport layer instead of a bare global fetch: the configured
+    // timeout applies (a slow-drip CDN can no longer hang the CLI indefinitely),
+    // network-level failures retry, and --verbose logs the request.
+    const timeoutMs = loadConfig().timeoutMs;
     await fs.mkdir(dirname(outputPath), { recursive: true });
+    // Signed URLs carry credentials in the query string — verbose logs must strip
+    // search/hash so signatures never land in terminal/CI logs.
+    const redactUrl = (u) => {
+        try {
+            const parsed = new URL(u);
+            return parsed.origin + parsed.pathname;
+        }
+        catch {
+            return "signed-url";
+        }
+    };
+    // .part + rename so a failed follow-download never destroys an existing file.
+    const partPath = `${outputPath}.part`;
+    await withRetry(async () => {
+        const startedAt = Date.now();
+        const requestOptions = {
+            method: "GET",
+            headersTimeout: timeoutMs,
+            bodyTimeout: timeoutMs,
+            // headers/body timeouts are IDLE timeouts — a stream trickling one byte
+            // per interval resets them forever. A generous total deadline (10× the
+            // per-request timeout) bounds the whole transfer without killing large
+            // legitimate downloads.
+            signal: AbortSignal.timeout(timeoutMs * 10),
+            dispatcher: getDispatcher(),
+        };
+        let currentUrl = url;
+        let response = await request(currentUrl, requestOptions);
+        // undici does not follow redirects (the old global fetch did): a signed URL
+        // may 302 to the real CDN object. Follow a bounded number of hops; no
+        // Authorization header is involved on this path, so nothing leaks cross-origin.
+        for (let hops = 0; hops < 3 && response.statusCode >= 300 && response.statusCode < 400; hops++) {
+            const locationHeader = response.headers.location;
+            const location = Array.isArray(locationHeader) ? locationHeader[0] : locationHeader;
+            if (!location)
+                break;
+            await response.body.text().catch(() => { });
+            currentUrl = new URL(location, currentUrl).toString();
+            response = await request(currentUrl, requestOptions);
+        }
+        if (response.statusCode >= 300 && response.statusCode < 400) {
+            await response.body.text().catch(() => { });
+            throw new DownloadError(`Failed to fetch download URL: unresolved redirect (HTTP ${response.statusCode})`);
+        }
+        if (response.statusCode >= 400) {
+            await response.body.text().catch(() => { });
+            // DownloadError (not retried): signed URLs expire — replaying a 403 is useless.
+            throw new DownloadError(`Failed to fetch download URL (HTTP ${response.statusCode})`);
+        }
+        try {
+            await pipeline(response.body, createWriteStream(partPath));
+        }
+        catch (error) {
+            await fs.unlink(partPath).catch(() => { });
+            throw error;
+        }
+        logTiming(`GET ${redactUrl(currentUrl)}`, Date.now() - startedAt, String(response.statusCode));
+    });
     try {
-        await pipeline(Readable.fromWeb(response.body), createWriteStream(outputPath));
+        await fs.rename(partPath, outputPath);
     }
     catch (error) {
-        await fs.unlink(outputPath).catch(() => { });
+        // e.g. outputPath turned out to be a directory — don't leave the .part behind.
+        await fs.unlink(partPath).catch(() => { });
         throw error;
     }
 }

package/dist/src/core/endpoints.js

@@ -46,6 +46,8 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/summary/v2/download/file",
         kind: "download",
         description: "Download summary file",
+        // 50/篇 — same price tier as the AI Agent calls; billing probed non-idempotent.
+        retry: "no-replay",
     },
     "insight.roadshow.list": {
         method: "POST",
@@ -100,6 +102,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-insight/foreign-report/download/file",
         kind: "download",
         description: "Download foreign report",
+        retry: "no-replay",
     },
     "insight.announcement.list": {
         method: "POST",
@@ -394,6 +397,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-data/ai/search/knowledge/batch",
         kind: "json",
         description: "Batch knowledge search",
+        retry: "no-replay",
     },
     "ai.knowledge-resource.download": {
         method: "GET",
@@ -414,6 +418,7 @@ const ENDPOINT_DEFS = {
         kind: "json",
         description: "Generate one pager",
         timeoutMs: 120_000,
+        retry: "no-replay",
     },
     "ai.investment-logic": {
         method: "POST",
@@ -421,6 +426,7 @@ const ENDPOINT_DEFS = {
         kind: "json",
         description: "Generate investment logic",
         timeoutMs: 120_000,
+        retry: "no-replay",
     },
     "ai.peer-comparison": {
         method: "POST",
@@ -428,12 +434,14 @@ const ENDPOINT_DEFS = {
         kind: "json",
         description: "Generate peer comparison",
         timeoutMs: 120_000,
+        retry: "no-replay",
     },
     "ai.earnings-review.get-id": {
         method: "POST",
         path: "/application/open-ai/agent/earnings-review-getid",
         kind: "json",
         description: "Get earnings review ID",
+        retry: "no-replay",
     },
     "ai.earnings-review.get-content": {
         method: "POST",
@@ -447,6 +455,7 @@ const ENDPOINT_DEFS = {
         kind: "json",
         description: "Get theme tracking daily report",
         timeoutMs: 120_000,
+        retry: "no-replay",
     },
     "ai.research-outline": {
         method: "POST",
@@ -454,6 +463,7 @@ const ENDPOINT_DEFS = {
         kind: "json",
         description: "Get company research outline",
         timeoutMs: 120_000,
+        retry: "no-replay",
     },
     "ai.hot-topic": {
         method: "POST",
@@ -461,6 +471,7 @@ const ENDPOINT_DEFS = {
         kind: "json",
         description: "List hot topic reports",
         pagination: { enabled: true, maxPageSize: 20 },
+        retry: "no-replay",
     },
     "ai.management-discuss-announcement": {
         method: "POST",
@@ -468,6 +479,7 @@ const ENDPOINT_DEFS = {
         kind: "json",
         description: "Management discussion from financial reports (half-year/annual)",
         timeoutMs: 120_000,
+        retry: "no-replay",
     },
     "ai.management-discuss-earnings-call": {
         method: "POST",
@@ -475,12 +487,14 @@ const ENDPOINT_DEFS = {
         kind: "json",
         description: "Management discussion from earnings calls",
         timeoutMs: 120_000,
+        retry: "no-replay",
     },
     "ai.viewpoint-debate.get-id": {
         method: "POST",
         path: "/application/open-ai/agent/viewpoint-debate-getid",
         kind: "json",
         description: "Get viewpoint debate ID",
+        retry: "no-replay",
     },
     "ai.viewpoint-debate.get-content": {
         method: "POST",
@@ -527,6 +541,7 @@ const ENDPOINT_DEFS = {
         path: "/application/open-vault/my-conference/download/file",
         kind: "download",
         description: "Download my conference resource",
+        retry: "no-replay",
     },
     "vault.wechat-message.list": {
         method: "POST",
@@ -573,12 +588,14 @@ const ENDPOINT_DEFS = {
         path: "/application/open-alternative/concept/info",
         kind: "json",
         description: "Query latest concept (theme index) profile by conceptId",
+        retry: "no-replay",
     },
     "alternative.concept-securities": {
         method: "POST",
         path: "/application/open-alternative/concept/securities",
         kind: "json",
         description: "Query concept (theme index) constituent securities, grouped",
+        retry: "no-replay",
     },
     // ─── indicator (EDE: security-level data indicators) ───
     "indicator.search": {
@@ -586,18 +603,21 @@ const ENDPOINT_DEFS = {
         path: "/application/open-indicator/EDE/search",
         kind: "json",
         description: "Search data indicators by keyword (returns indicatorCode + params)",
+        retry: "no-999999",
     },
     "indicator.cross-section": {
         method: "POST",
         path: "/application/open-indicator/EDE/cross-section",
         kind: "json",
         description: "Get cross-section data (multi-indicator x multi-security, single date)",
+        retry: "no-999999",
     },
     "indicator.time-series": {
         method: "POST",
         path: "/application/open-indicator/EDE/time-series",
         kind: "json",
         description: "Get time-series data (multi-indicator x single-security OR single-indicator x multi-security)",
+        retry: "no-999999",
     },
 };
 export const ENDPOINTS = Object.fromEntries(Object.entries(ENDPOINT_DEFS).map(([key, def]) => [key, { key, ...def }]));

package/dist/src/core/errors.js

@@ -40,12 +40,15 @@ export class ApiError extends CliError {
     constructor(message, code, statusCode, details, 
     /** Server-specified Retry-After (ms), set on 429 responses so the transport
      * backoff can honor it instead of the default exponential schedule. */
-    retryAfterMs) {
+    retryAfterMs, 
+    /** Context-specific hint that beats the generic per-code table — e.g. EDE's
+     * 999999 means "no data", not the table's "系统错误，请稍后重试". */
+    hintOverride) {
         super(message);
         this.code = code;
         this.statusCode = statusCode;
         this.details = details;
         this.retryAfterMs = retryAfterMs;
-        this.hint = code ? ERROR_HINTS[code] : undefined;
+        this.hint = hintOverride ?? (code ? ERROR_HINTS[code] : undefined);
     }
 }