gangtise-openapi-cli 0.19.0 → 0.21.0

package/README.md

@@ -1,9 +1,53 @@
 # Gangtise OpenAPI CLI
 
-一个可直接调用 Gangtise OpenAPI 获取金融数据的命令行工具，同时提供Agent Skill。
+一个可直接调用 Gangtise OpenAPI 获取全量金融信息的命令行工具，同时提供Agent Skill。
 
 ## 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
+
+**新增接口**
+- `insight announcement-us list` / `download` — 美股公司公告列表与下载（`--security TSLA.O`、`--category`〔分类用 `reference constant-list --category usShareAnnouncementCategory`，美股独立的 `103980xxx` 段〕、`--search-type`、`--rank-type`、下载 `--file-type 1` 原始 PDF / `2` Markdown）；自动翻页，单页上限 50
+- `ai stock-summary` — 个股看点（精炼投研总结）：`--security` 传具体代码（A股/港股，可重复，单次最多 6000）或市场关键词 `aShares` / `hkStocks` 拉全市场；无看点的证券不返回、不扣分
+- `fundamental income-statement-us` / `balance-sheet-us` / `cash-flow-us` — 美股三大财务报表（参数同其他财报：`--security-code` / `--period` / `--report-type` / `--fiscal-year` / `--field` 等）
+- `reference chiefs-search` — 首席分析师 ID 搜索（`--keyword` 按姓名/机构/团队匹配，`--top` 默认 10）；用于 `insight opinion list --chief` 的入参
+
+**变更**
+- `insight announcement-hk download` 新增 `--file-type`（`1` 原始（默认）/ `2` Markdown），此前无格式选项
+
+**行为变更（注意）**
+- ⚠️ `auth login` / `auth status` 默认脱敏 access token：`--format json` 输出里 `authorization` 与 `cache.accessToken` 显示为 `<redacted>`，仅保留过期时间 / 用户名 / 产品码 / uid 等非敏感字段。**依赖 `auth login` 原始 token 输出的脚本会拿到 `<redacted>`**，需改用 `auth login --show-token` 获取明文。
+
+**修复（安全）**
+- `auth status` / `auth login` token 脱敏：按凭证字段名模式匹配（`token`/`key`/`secret`/`password`/`credential`），覆盖 `apiKey`/`privateKey`/`refreshToken` 等任何可能携带的凭证字段
+- 自愈守卫：同时设 `GANGTISE_TOKEN` + AK/SK 时，注入 token 失效后重新登录不再被旧 token 短路，重试改用登录拿到的新 token
+
+**修复（数据正确性 / 健壮性）**
+- ⚠️ **CSV 负数不再被破坏**（影响所有 CSV 导出）：此前防公式注入会把负数（如跌幅 `-3.5`）加 `'` 前缀变成文本，Excel/pandas 无法参与计算；现仅对非有限数字的可疑串（`=`/`@`/`-1+cmd` 等）加前缀，合法数字原样输出
+- 自动翻页改为 fail-soft：某页遇不可重试错误（限流 `903301` 等）不再丢弃已取的全部数据，返回已取页 + `partial` / `failedPages` 标记，并在首错后停止继续请求（避免撞限流多烧配额）
+- 下载文件名 fallback（服务端 `Content-Disposition`）补清洗：含 `/`、`:` 等字符的文件名不再写到意外路径
+- `ai stock-summary` / `ai knowledge-batch` 缺 `--security` / `--query` 时本地报错，不再发空请求（stock-summary 借此避免被后台当全市场误扣积分）
+- `ai hot-topic` `--no-with-related-securities` / `--no-with-close-reading` 改为显式发 `false`（语义更明确，不依赖"字段缺失=排除"的隐含约定）
+
+**修复（indicator 适配 EDE 后台新结构）**
+- `indicator cross-section` / `time-series` 适配后台改版的返回结构（字段名加 `List` 后缀 `securityCodeList/indicatorCodeList/…`、截面 `values` 改二维 `[指标][证券]`）：此前后台改结构后 CLI 拍平失配、退化成原始矩阵，现恢复 `{date, security, name, 指标:值}` 宽表。配合后台同步变化——无数据从 `999999` 报错改为返回 `null`（截面不再 500、不丢行），缺必填参数从笼统 `410106` 改为直接指明缺哪个参数
+
 ### v0.19.0 — 2026-06-24
 
 **新增接口（Indicator · 证券级数据指标 EDE）**
@@ -36,120 +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 — 2026-05-29
-
-**新增接口**
-- `alternative concept-info` — 题材指数基本信息：返回题材整体画像（定义 / 投资逻辑 / 行业空间 / 竞争格局 / 催化事件）。按 `--concept-id` 查询，仅返回最新截面数据，不支持历史回溯
-- `alternative concept-securities` — 题材指数成分股（题材深度 F8）：按分组结构返回当前成分股，每只含是否重点个股 `isKey` 与纳入理由 `inclusionReason`。按 `--concept-id` 查询
-
-**接口变更**
-- `quote index-day-kline` 返回字段新增 `securityName`（指数名称，如"上证指数"）
-
-> `--concept-id` 与主题跟踪 `ai theme-tracking --theme-id` 共用同一套题材 ID 体系，可用 `gangtise lookup theme-id list` 按名称查询（如 机器人 → `121000130`）。
-
-### v0.14.4 — 2026-05-29
-
-**Bug fix（全市场 K 线分片容错）**
-- `quote day-kline --security all` 等全市场查询的日期分片改为容错：部分分片失败时返回已成功分片的数据并标记 `partial: true` + `failedShards`（失败的日期区间），同时向 stderr 告警；只有全部分片失败才抛错。此前为 fail-fast，单片失败会让整次查询失败，或在异常路径上被误判为空结果。
-
-### v0.14.3 — 2026-05-29
-
-**性能 / 健壮性**
-- 标题缓存按端点封顶（5000 条/端点）并清理过期项，修复 `title-cache.json` 无上限增长（曾达 ~58MB）拖慢启动的问题
-- 下载接口遇鉴权失效（`8000014` / `8000015`）自动刷新 token 并重试一次（此前仅普通 JSON 调用具备 token 自愈）
-- CLI handler 抽出 `emit` / `withClient` 公共封装去除重复样板；CSV 转义逻辑去重；翻页与 K 线分片统一走 `GANGTISE_PAGE_CONCURRENCY` 并发控制
-- 补齐多个 core 模块的单元测试
-
-### v0.14.2 — 2026-05-22
-
-**Bug fix（A 股 / HK 全市场 K 线同源问题）**
-- `quote day-kline --security all` 由 2 天/片改为 **1 天/片**（A 股全市场单日约 5500 行）
-- `quote day-kline-hk --security all` 由 3 天/片改为 **2 天/片**（港股全市场单日约 2770 行）
-- 根治性修复：`callKlineWithSharding` 在 `--security all` 路径上，若用户未显式传 `--limit`，强制写入 `limit: 10000`（API 上限），不再走默认 6000——这样即便分片日数估算偏大，每个 shard 也能拿满 10K 行。用户自己传的 `--limit` 仍然保留生效。
-
-### v0.14.1 — 2026-05-22
-
-**Bug fix**
-- `quote day-kline-us --security all` 分片由 2 天/片改为 **1 天/片**。美股全市场单日约 5800 行，原 2 天/片会在第一个 shard 命中默认 `--limit 6000` 上限，导致 shard 内第二日数据被截断到几百行。改 1 天/片后每个 shard 数据完整。
-
-### v0.14.0 — 2026-05-22
-
-**新增接口**
-- `quote realtime` — 个股实时行情快照，单接口同时覆盖 A 股 / 港股 / 美股；支持代码混合传入或市场关键字（`aShares` / `hkStocks` / `usStocks`）批量查询全市场
-- `quote day-kline-us` — 美股历史日 K 线，数据范围 NYSE / NASDAQ / AMEX；支持 `--security all` 全市场（CLI 自动按 1 天/片切分并发拉取，美股全市场单日约 5800 行）
-
-**接口变更**
-- `quote day-kline` / `quote day-kline-hk` 明确仅返回**历史**日 K 线，不包含盘中实时数据；当日数据入库时间：A 股 ~15:30 / 港股 ~16:30（北京时间）。盘中实时请走 `quote realtime`
-- `fundamental valuation-analysis` 返回字段移除 `p10` / `p25` / `p75` / `p90`（仍保留 `value` / `percentileRank` / `average` / `median` / `upper1Std` / `lower1Std`）
-
-### v0.13.0 — 2026-05-15
-
-**新增接口**
-- `fundamental income-statement-hk / balance-sheet-hk / cash-flow-hk` — 港股三大报表（中国会计准则）
-- `alternative edb-search` — 行业指标列表搜索（按关键词匹配指标名称，返回 indicatorId 等元信息）
-- `alternative edb-data` — 行业指标时序数据（批量按 indicatorId 拉取时间序列，最多 10 个指标）
-- `vault stock-pool-list` — 查询用户自选股股票池列表（poolId / poolName）
-- `vault stock-pool-stocks` — 查询股票池证券明细（支持 `--pool-id all` 全量查询）
-
-**接口变更**
-- `fundamental income-statement / balance-sheet / cash-flow / income-statement-quarterly / cash-flow-quarterly` 名称调整为 A股报表（路径不变）
-- `ai management-discuss-announcement` `--dimension` 新增 `all` 选项，返回报告中完整的管理层讨论内容（内容可能较长）
-- `vault wechat-message-list` 新增 `--security <code>` 参数（按证券代码过滤），返回结果增加 `securityList` 字段
-
-### v0.12.0 — 2026-05-10
-
-**性能 / 架构**
-- 翻页并行化：自动翻页接口拉到首页 `total` 后，剩余页通过 `Promise.all` 并发请求（默认并发 5，`GANGTISE_PAGE_CONCURRENCY` 可调）
-- 共享 `undici.Agent`：所有请求复用连接池（keep-alive 60s，max 16 连接），避免重复 TLS 握手
-- 流式下载：`--output` 指定时二进制响应直接 `pipeline` 到磁盘，不再走内存 `Uint8Array`
-- 流式输出：`--format jsonl/csv --output xxx` 且 ≥1000 行时逐行写盘
-- Token 内存缓存：Token 在进程内不再每次读盘
-- 自动重试：5xx / `ECONNRESET` / `ETIMEDOUT` / `999999` 自动指数退避重试 2 次
-- Token 自愈：8000014/8000015 自动重新登录并重试一次
-- 异步轮询退避：`earnings-review` / `viewpoint-debate` 轮询从固定 15s 改为 5→8→13→20→30s 指数退避
-- K线自动分片：`quote day-kline --security all` 等全市场查询自动按日期切分并发执行
-- 标题缓存：原"读全文→改→写全文"改为内存快照 + 原子写入（temp+rename）
-
-**调试 / 可观测性**
-- 新增 `--verbose` / `GANGTISE_VERBOSE=1`：打印每个请求的耗时、状态码、响应字节数到 stderr
-
-### v0.11.1 — 2026-05-10
-
-**新增接口**
-- `insight announcement-hk list/download` — 查询/下载港股公告
-- `insight foreign-opinion list` — 查询外资机构观点（外资券商）
-- `insight independent-opinion list/download` — 查询/下载外资独立分析师观点
-- `reference securities-search` — GTS Code 搜索（按名称/代码/拼音多维度匹配证券）
-
-**接口变更**
-- `insight summary download` 新增可选 `--file-type`（`1`=原始内容 / `2`=HTML），仅影响来源为会议平台的纪要
-- `insight announcement list/download` 名称调整为"查询A股公告列表/下载A股公告文件"（路径不变）
-- `insight opinion list` 名称调整为"查询内资机构观点列表"（路径不变）
-
-### v0.11.0 — 2026-04-17
-
-- 新增 `ai viewpoint-debate` / `viewpoint-debate-check` — 观点PK（异步）
-- 新增 `ai management-discuss-announcement` / `management-discuss-earnings-call` — 管理层讨论
-
-### v0.10.9 — 2026-04-10
-
-- 修复信封检测、版本更新检查、端点去重
-- 新增 `quote index-day-kline` 指数日K线
-- 新增 `vault wechat-message-list` / `wechat-chatroom-list` 群消息
+> 更早版本及完整更新历史见 [CHANGELOG.md](CHANGELOG.md)。
 
 ## 首次安装
 
@@ -163,6 +94,12 @@ npm install -g gangtise-openapi-cli
 gangtise --help
 ```
 
+更新到最新版（`gangtise --version` 会自动与线上版本比对）：
+
+```bash
+npm update -g gangtise-openapi-cli
+```
+
 本地开发：
 
 ```bash
@@ -172,36 +109,6 @@ npm install
 npm run dev -- --help
 ```
 
-## 发布
-
-npm 发版通过 GitHub Actions Trusted Publishing 完成，不需要 `NPM_TOKEN`。npm 包设置里的 Trusted Publisher 需要匹配本仓库和 workflow 文件名 `publish.yml`。
-
-```bash
-npm version patch --no-git-tag-version
-npm run prepare
-VERSION=$(node -p "require('./package.json').version")
-git commit -am "chore: release v$VERSION"
-git tag -a "v$VERSION" -m "v$VERSION"   # 必须 annotated：--follow-tags 不推 lightweight tag
-git push --follow-tags
-```
-
-推送 `v*` tag 后，`.github/workflows/publish.yml` 会在 GitHub-hosted runner 上使用 OIDC 发布到 `https://registry.npmjs.org/`。也可以从 GitHub Actions 页面手动运行该 workflow。
-
-## 版本更新
-
-查看当前版本（自动与线上版本比对）：
-
-```bash
-gangtise --version
-```
-
-手动更新到最新版：
-
-```bash
-npm update -g gangtise-openapi-cli
-```
-
-
 ## 环境配置
 
 优先读取以下环境变量：
@@ -226,6 +133,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/`
 
@@ -256,6 +164,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
 
@@ -292,11 +203,13 @@ cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
 | | `research list` / `download` | 研报（含 Markdown 下载） |
 | | `foreign-report list` / `download` | 外资研报（含中文翻译下载） |
 | | `announcement list` / `download` | A股公告（含 Markdown 下载） |
-| | `announcement-hk list` / `download` | 港股公告（含下载） |
+| | `announcement-hk list` / `download` | 港股公告（含 PDF/Markdown 下载） |
+| | `announcement-us list` / `download` | 美股公告（含 PDF/Markdown 下载） |
 | | `foreign-opinion list` | 外资机构观点 |
 | | `independent-opinion list` / `download` | 外资独立分析师观点（含原文/翻译HTML下载） |
 | | `official-account list` / `download` | 产业公众号资讯（含 txt/HTML 下载） |
 | **Reference** | `securities-search` | GTS Code 搜索（按名称/代码/拼音匹配） |
+| | `chiefs-search` | 首席分析师 ID 搜索（按姓名/机构/团队匹配） |
 | | `constant-category` | 常量分类列表（含各分类适用的接口与参数） |
 | | `constant-list` | 按分类导出常量值全量列表（行业/城市/公告分类/区域等） |
 | | `concept-search` | 题材 ID 搜索（名称/拼音/分组名匹配） |
@@ -309,6 +222,7 @@ cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
 | **Fundamental** | `income-statement` / `balance-sheet` / `cash-flow` | A股三大财务报表（累计） |
 | | `income-statement-quarterly` / `cash-flow-quarterly` | A股利润表/现金流量表（单季度） |
 | | `income-statement-hk` / `balance-sheet-hk` / `cash-flow-hk` | 港股三大财务报表（中国会计准则） |
+| | `income-statement-us` / `balance-sheet-us` / `cash-flow-us` | 美股三大财务报表 |
 | | `main-business` | 主营构成（按地区/产品拆分） |
 | | `valuation-analysis` | 估值分析 |
 | | `earning-forecast` | 盈利预测（一致预期） |
@@ -316,6 +230,7 @@ cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
 | **AI** | `knowledge-batch` | 知识库批量检索 |
 | | `knowledge-resource-download` | 知识资源下载 |
 | | `security-clue` | 个股线索 |
+| | `stock-summary` | 个股看点（精炼投研总结，按代码或全市场；仅 A 股/港股） |
 | | `one-pager` | 一页通 |
 | | `investment-logic` | 投资逻辑 |
 | | `peer-comparison` | 同业对比 |
@@ -403,6 +318,7 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 - `insight foreign-report list`
 - `insight announcement list`
 - `insight announcement-hk list`
+- `insight announcement-us list`
 - `insight foreign-opinion list`
 - `insight independent-opinion list`
 - `insight official-account list`
@@ -411,6 +327,7 @@ 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`
 
 规则：
@@ -420,10 +337,11 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 - `--from` 必须是非负整数，`--size` 必须是正整数；非法数字会在本地直接报 `ValidationError`，不会继续请求 API
 - 安全上限：自动翻页最多 1000 页，防止异常循环
 - 分页结果中 `total` 字段会被保留（json 格式输出 `{total, list}`），同时 stderr 输出 `Total: N, showing: M`
+- `vault wechat-chatroom-list` 是特例：接口不返回 `total`，CLI 改为串行翻页——省略 `--size` 拉全量、传 `--size N` 取前 N 条，单页 50，无 `Total:` 提示
 
 ## 智能文件命名
 
-下载命令（`summary download`、`research download`、`foreign-report download`、`announcement 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`、`vault drive-download`、`vault record-download`、`vault my-conference-download`）省略 `--output` 时，自动使用真实标题作为文件名：
 
 1. **缓存优先** — 如果之前执行过对应的 `list` 命令，标题已缓存在 `~/.config/gangtise/title-cache.json`，直接使用，无额外 API 调用
 2. **API 回查** — 缓存未命中时，自动查询最近 200 条记录匹配标题
@@ -474,6 +392,11 @@ gangtise insight roadshow list --institution C100000017
 # 港股公告
 gangtise insight announcement-hk list --security 01913.HK --rank-type 2 --size 20 --format json
 gangtise insight announcement-hk download --announcement-id ANN2026040200012345
+gangtise insight announcement-hk download --announcement-id ANN2026040200012345 --file-type 2   # Markdown
+
+# 美股公告（--security 用美股代码；分类用 reference constant-list --category usShareAnnouncementCategory）
+gangtise insight announcement-us list --security TSLA.O --rank-type 2 --size 20 --format json
+gangtise insight announcement-us download --announcement-id 49629029 --file-type 2   # Markdown
 
 # 外资机构观点
 gangtise insight foreign-opinion list --keyword "自动驾驶" --region us --rank-type 2 --format json
@@ -500,10 +423,15 @@ gangtise reference securities-search --keyword "600519" --category stock
 gangtise reference securities-search --keyword gzmt --top 5
 gangtise reference securities-search --keyword "银行" --category stock --category index
 
+# 首席分析师 ID 搜索（按姓名/机构/团队；拿 chiefId 供 insight opinion list --chief 使用）
+gangtise reference chiefs-search --keyword 东吴证券 --top 3 --format json
+gangtise reference chiefs-search --keyword 芦哲 --format json
+
 # 常量查询：先看分类，再按分类导出全量常量值
 gangtise reference constant-category --format json
 gangtise reference constant-list --category citicIndustry --format json
 gangtise reference constant-list --category aShareAnnouncementCategory --format json   # 树形，含 children
+gangtise reference constant-list --category usShareAnnouncementCategory --format json  # 美股公告分类（103980xxx 段）
 
 # 题材 ID 搜索（供 concept-info / concept-securities / theme-tracking 使用）
 gangtise reference concept-search --keyword 机器人 --top 3 --format json
@@ -578,6 +506,11 @@ gangtise fundamental balance-sheet-hk --security-code 09992.HK --fiscal-year 202
 gangtise fundamental cash-flow-hk --security-code 09992.HK --fiscal-year 2025 --period annual --field netOpCashFlows --field netInvCashFlows --field netFinCashFlows
 # 最新一期完整港股利润表
 gangtise fundamental income-statement-hk --security-code 09992.HK --format json
+
+# 美股三大报表（--security-code 用美股代码；period 同港股但无 h2）
+gangtise fundamental income-statement-us --security-code TSLA.O --period latest --format json
+gangtise fundamental balance-sheet-us --security-code TSLA.O --fiscal-year 2025 --period annual --field totalAssets --field totalLiab --field totalEquity
+gangtise fundamental cash-flow-us --security-code TSLA.O --fiscal-year 2024 --fiscal-year 2025 --period annual --field netOpCashFlows
 ```
 
 ### AI
@@ -588,6 +521,9 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 gangtise ai knowledge-batch --query 新能源汽车 --resource-type 10 --resource-type 11 --top 10
 gangtise ai security-clue --start-time "2026-04-01 00:00:00" --end-time "2026-04-09 23:59:59" --query-mode byIndustry --gts-code 821035.SWI --source researchReport --source announcement
 gangtise ai one-pager --security-code 600519.SH
+# 个股看点（精炼投研总结，仅 A 股/港股）：传具体代码，或 aShares/hkStocks 拉全市场
+gangtise ai stock-summary --security 600519.SH --security 00700.HK --format json
+gangtise ai stock-summary --security hkStocks --format json
 gangtise ai investment-logic --security-code 600519.SH
 gangtise ai peer-comparison --security-code 600519.SH
 gangtise ai earnings-review --security-code 600519.SH --period 2025q3
@@ -754,3 +690,22 @@ CLI 会在本地校验常见数值参数，避免把明显非法的请求发到
 | `430007` | 行情查询超出限制（数据量过大，请缩短日期范围或减少 `--limit`） |
 | `410110` | 异步任务生成中（非终态，需继续轮询） |
 | `410111` | 异步任务生成失败（终态，不可重试） |
+
+---
+
+## 发布（维护者）
+
+> 面向仓库维护者的发版流程，普通用户可跳过。
+
+npm 发版通过 GitHub Actions Trusted Publishing 完成，不需要 `NPM_TOKEN`。npm 包设置里的 Trusted Publisher 需要匹配本仓库和 workflow 文件名 `publish.yml`。
+
+```bash
+npm version patch --no-git-tag-version
+npm run prepare
+VERSION=$(node -p "require('./package.json').version")
+git commit -am "chore: release v$VERSION"
+git tag -a "v$VERSION" -m "v$VERSION"   # 必须 annotated：--follow-tags 不推 lightweight tag
+git push --follow-tags
+```
+
+推送 `v*` tag 后，`.github/workflows/publish.yml` 会在 GitHub-hosted runner 上使用 OIDC 发布到 `https://registry.npmjs.org/`。也可以从 GitHub Actions 页面手动运行该 workflow。

package/dist/src/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { Command, Option } from "commander";
 import { checkAsyncContent, pollAsyncContent, POLL_MAX_ATTEMPTS } from "./core/asyncContent.js";
-import { readTokenCache } from "./core/auth.js";
+import { readTokenCache, redactTokenCache } from "./core/auth.js";
 import { collectKeyValue, collectList, collectNumberList, maybeArray, 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";
@@ -9,7 +9,7 @@ import { callKlineWithSharding } from "./core/quoteSharding.js";
 import { loadConfig } from "./core/config.js";
 import { resolveTitle, saveDownloadResult } from "./core/download.js";
 import { ENDPOINTS } from "./core/endpoints.js";
-import { ApiError, ConfigError } from "./core/errors.js";
+import { ApiError, ConfigError, ValidationError } from "./core/errors.js";
 import { normalizeRows } from "./core/normalize.js";
 import { parseOutputFormat } from "./core/output.js";
 import { printData } from "./core/printer.js";
@@ -100,14 +100,18 @@ program
     .command("auth")
     .description("Authentication commands")
     .addCommand(new Command("login")
+    .option("--show-token", "Show the raw access token (default: redacted)")
     .option("--format <format>", "Output format", "json")
-    .action((options) => emit(options, (client) => client.login())))
+    .action((options) => emit(options, async (client) => {
+    const result = await client.login();
+    return options.showToken ? result : { authorization: "<redacted>", cache: redactTokenCache(result.cache) };
+})))
     .addCommand(new Command("status")
     .option("--format <format>", "Output format", "json")
     .action(async (options) => {
     const config = loadConfig();
     const cache = await readTokenCache(config.tokenCachePath);
-    await printData({ hasEnvToken: Boolean(config.token), hasCachedToken: Boolean(cache?.accessToken), cache }, parseOutputFormat(options.format));
+    await printData({ hasEnvToken: Boolean(config.token), hasCachedToken: Boolean(cache?.accessToken), cache: redactTokenCache(cache) }, parseOutputFormat(options.format));
 }));
 const lookup = new Command("lookup").description("Local lookup tables (IDs not covered by 'reference constant-list')");
 const addLookupList = (name, endpointKey, description) => {
@@ -130,6 +134,7 @@ const research = new Command("research");
 const foreignReport = new Command("foreign-report");
 const announcement = new Command("announcement");
 const announcementHk = new Command("announcement-hk");
+const announcementUs = new Command("announcement-us");
 const foreignOpinion = new Command("foreign-opinion");
 const independentOpinion = new Command("independent-opinion");
 const officialAccount = new Command("official-account");
@@ -215,6 +220,12 @@ addTimeFilters(foreignReport.command("list").option("--search-type <number>", "S
     minReportPages: parseOptionalNumberOption(options.minPages, "--min-pages", { integer: true, min: 0 }), maxReportPages: parseOptionalNumberOption(options.maxPages, "--max-pages", { integer: true, min: 0 }),
 }), { endpointKey: "insight.foreign-report.list", idField: "reportId" }));
 addDownloadCommand(foreignReport, { endpointKey: "insight.foreign-report.download", idOption: "--report-id", idField: "reportId", fallbackPrefix: "foreign-report", fileType: { description: "File type: 1=PDF 2=Markdown 3=CN-PDF 4=CN-Markdown", default: "1" }, titleListEndpoint: "insight.foreign-report.list" });
+// Contract: A-share announcement startTime/endTime go out as 13-digit epoch millis
+// (parseTimestamp13), while HK/US announcement and every other insight list send the
+// datetime string straight through. All three filter correctly — verified live against
+// a narrow past window (each returns in-window rows). A-share's API also accepts the
+// string form, but the 13-digit conversion is kept as the historical spec contract;
+// don't "unify" it away without re-confirming the A-share announcement spec.
 addTimeFilters(announcement.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("--security <code>", "Security code", collectList, []).option("--category <id>", "Category ID", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.announcement.list", {
     from: parseFrom(options.from), size: parseSize(options.size),
     startTime: parseTimestamp13(options.startTime, "--start-time"), endTime: parseTimestamp13(options.endTime, "--end-time"),
@@ -230,7 +241,16 @@ addTimeFilters(announcementHk.command("list").option("--search-type <number>", "
     keyword: options.keyword,
     securityList: maybeArray(options.security), categoryList: maybeArray(options.category),
 }), { endpointKey: "insight.announcement-hk.list", idField: "announcementId" }));
-addDownloadCommand(announcementHk, { endpointKey: "insight.announcement-hk.download", idOption: "--announcement-id", idField: "announcementId", fallbackPrefix: "announcement-hk", titleListEndpoint: "insight.announcement-hk.list" });
+addDownloadCommand(announcementHk, { endpointKey: "insight.announcement-hk.download", idOption: "--announcement-id", idField: "announcementId", fallbackPrefix: "announcement-hk", fileType: { description: "File type: 1=original 2=Markdown", default: "1" }, titleListEndpoint: "insight.announcement-hk.list" });
+addTimeFilters(announcementUs.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("--security <code>", "Security code (e.g. TSLA.O)", collectList, []).option("--category <id>", "Category ID (constant-list usShareAnnouncementCategory)", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.announcement-us.list", {
+    from: parseFrom(options.from), size: parseSize(options.size),
+    startTime: options.startTime, endTime: options.endTime,
+    searchType: parseNumberOption(options.searchType, "--search-type", { integer: true, min: 1 }),
+    rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }),
+    keyword: options.keyword,
+    securityList: maybeArray(options.security), categoryList: maybeArray(options.category),
+}), { endpointKey: "insight.announcement-us.list", idField: "announcementId" }));
+addDownloadCommand(announcementUs, { endpointKey: "insight.announcement-us.download", idOption: "--announcement-id", idField: "announcementId", fallbackPrefix: "announcement-us", fileType: { description: "File type: 1=original PDF 2=Markdown", default: "1" }, titleListEndpoint: "insight.announcement-us.list" });
 addTimeFilters(foreignOpinion.command("list").option("--rank-type <number>", "Rank type: 1=composite 2=time desc", "1").option("--security <code>", "Security code (e.g. UBER.N)", collectList, []).option("--region <code>", "Region code", collectList, []).option("--industry <id>", "Industry ID", collectList, []).option("--broker <id>", "Broker ID", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.foreign-opinion.list", {
     from: parseFrom(options.from), size: parseSize(options.size),
     startTime: options.startTime, endTime: options.endTime,
@@ -269,6 +289,7 @@ insight.addCommand(research);
 insight.addCommand(foreignReport);
 insight.addCommand(announcement);
 insight.addCommand(announcementHk);
+insight.addCommand(announcementUs);
 insight.addCommand(foreignOpinion);
 insight.addCommand(independentOpinion);
 insight.addCommand(officialAccount);
@@ -300,6 +321,9 @@ addFinancialReport("cash-flow-quarterly", "fundamental.cash-flow-quarterly", "Pe
 addFinancialReport("income-statement-hk", "fundamental.income-statement-hk", "Period: q1/h1/q3/h2/nsd/annual/latest");
 addFinancialReport("balance-sheet-hk", "fundamental.balance-sheet-hk", "Period: q1/h1/q3/h2/nsd/annual/latest");
 addFinancialReport("cash-flow-hk", "fundamental.cash-flow-hk", "Period: q1/h1/q3/h2/nsd/annual/latest");
+addFinancialReport("income-statement-us", "fundamental.income-statement-us", "Period: q1/h1/q3/nsd/annual/latest");
+addFinancialReport("balance-sheet-us", "fundamental.balance-sheet-us", "Period: q1/h1/q3/nsd/annual/latest");
+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) => {
     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) });
@@ -328,7 +352,11 @@ fundamental.command("earning-forecast").requiredOption("--security-code <code>")
 }));
 program.addCommand(fundamental);
 const ai = new Command("ai").description("AI APIs");
-ai.command("knowledge-batch").requiredOption("--query <text>", "Query", collectList, []).option("--top <number>", "Top", "10").option("--resource-type <number>", "Resource type", collectNumberList, []).option("--knowledge-name <name>", "Knowledge name", collectList, []).option("--start-time <ms>").option("--end-time <ms>").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => emit(options, (client) => client.call("ai.knowledge-batch", { queries: options.query, top: parseNumberOption(options.top, "--top", { integer: true, min: 1 }), resourceTypes: options.resourceType.length ? options.resourceType : undefined, knowledgeNames: maybeArray(options.knowledgeName), startTime: parseOptionalNumberOption(options.startTime, "--start-time", { integer: true, min: 0 }), endTime: parseOptionalNumberOption(options.endTime, "--end-time", { integer: true, min: 0 }) })));
+ai.command("knowledge-batch").option("--query <text>", "Query", collectList, []).option("--top <number>", "Top", "10").option("--resource-type <number>", "Resource type", collectNumberList, []).option("--knowledge-name <name>", "Knowledge name", collectList, []).option("--start-time <ms>").option("--end-time <ms>").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => {
+    if (!options.query.length)
+        throw new ValidationError("--query is required: pass at least one --query");
+    return emit(options, (client) => client.call("ai.knowledge-batch", { queries: options.query, top: parseNumberOption(options.top, "--top", { integer: true, min: 1 }), resourceTypes: options.resourceType.length ? options.resourceType : undefined, knowledgeNames: maybeArray(options.knowledgeName), startTime: parseOptionalNumberOption(options.startTime, "--start-time", { integer: true, min: 0 }), endTime: parseOptionalNumberOption(options.endTime, "--end-time", { integer: true, min: 0 }) }));
+});
 ai.command("knowledge-resource-download").requiredOption("--resource-type <number>").requiredOption("--source-id <id>").option("--output <path>").action((options) => withClient(async (client) => {
     await runDownload(client, "ai.knowledge-resource.download", { resourceType: parseNumberOption(options.resourceType, "--resource-type", { integer: true, min: 0 }), sourceId: options.sourceId }, {
         output: options.output,
@@ -372,8 +400,8 @@ ai.command("hot-topic").option("--from <number>", "Starting offset", "0").option
         startDate: options.startDate,
         endDate: options.endDate,
         categoryList: options.category.length > 0 ? options.category : ALL_CATEGORIES,
-        withRelatedSecurities: options.withRelatedSecurities === false ? undefined : true,
-        withCloseReading: options.withCloseReading === false ? undefined : true,
+        withRelatedSecurities: options.withRelatedSecurities !== false,
+        withCloseReading: options.withCloseReading !== false,
     });
 }));
 ai.command("management-discuss-announcement").requiredOption("--report-date <date>", "Report date (yyyy-MM-dd, e.g. 2025-06-30)").requiredOption("--security-code <code>", "Security code (e.g. 000001.SZ)").addOption(new Option("--dimension <name>", "Discussion dimension: businessOperation/financialPerformance/developmentAndRisk/all").choices(["businessOperation", "financialPerformance", "developmentAndRisk", "all"]).makeOptionMandatory()).option("--format <format>", "Output format", "json").option("--output <path>").action((options) => emit(options, (client) => client.call("ai.management-discuss-announcement", {
@@ -406,6 +434,13 @@ ai.command("viewpoint-debate").requiredOption("--viewpoint <text>", "Viewpoint t
     }
 }));
 ai.command("viewpoint-debate-check").requiredOption("--data-id <id>", "dataId from viewpoint-debate").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => withClient((client) => checkAsyncContent(client, "ai.viewpoint-debate.get-content", options.dataId, parseOutputFormat(options.format), options.output)));
+ai.command("stock-summary").description("Stock highlights: refined research summary per security (A-share / HK)").option("--security <code>", "Security code (e.g. 600519.SH / 00700.HK), or market keyword: aShares / hkStocks; max 6000", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => {
+    // Guard against an empty --security: omitting it would send securityList:undefined,
+    // which the backend may treat as all-market (3 credits/row × thousands of rows).
+    if (!options.security.length)
+        throw new ValidationError("--security is required: pass security code(s) or a market keyword (aShares / hkStocks)");
+    return emit(options, (client) => client.call("ai.stock-summary.list", { securityList: maybeArray(options.security) }));
+});
 const reference = new Command("reference").description("Reference data APIs");
 reference.command("securities-search").requiredOption("--keyword <text>", "Search keyword (name/code/pinyin/English)").option("--category <type>", "Category: stock/dr/index/fund", collectList, []).option("--top <number>", "Max results (default: 10, max: 10)", "10").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("reference.securities-search", {
     keyword: options.keyword,
@@ -423,6 +458,10 @@ reference.command("sector-search").option("--keyword <text>", "Search keyword (n
     top: parseNumberOption(options.top, "--top", { integer: true, min: 1 }),
 })));
 reference.command("sector-constituents").requiredOption("--sector-id <id>", "Sector ID from 'reference sector-search'").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("reference.sector-constituents", { sectorId: options.sectorId })));
+reference.command("chiefs-search").requiredOption("--keyword <text>", "Search keyword (chief name / institution / team)").option("--top <number>", "Max results (default: 10, max: 10)", "10").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("reference.chiefs-search", {
+    keyword: options.keyword,
+    top: parseNumberOption(options.top, "--top", { integer: true, min: 1 }),
+})));
 program.addCommand(reference);
 const vault = new Command("vault").description("Vault APIs");
 vault.command("drive-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("--file-type <number>", "File type", collectNumberList, []).option("--space-type <number>", "Space type", collectNumberList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("vault.drive.list", { from: parseFrom(options.from), size: parseSize(options.size), startTime: options.startTime, endTime: options.endTime, keyword: options.keyword, fileTypeList: options.fileType.length ? options.fileType : undefined, spaceTypeList: options.spaceType.length ? options.spaceType : undefined }), { endpointKey: "vault.drive.list", idField: "fileId" }));
@@ -432,7 +471,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);

package/dist/src/core/args.js

@@ -42,12 +42,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,

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);

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";
@@ -14,9 +15,39 @@ export async function readTokenCache(filePath) {
         return null;
     }
 }
+/**
+ * Return a display-safe copy of a token cache for `auth status`: any field whose
+ * name matches a credential pattern (token / key / secret / password / credential)
+ * is replaced with "<redacted>" so the raw bearer token — or any unknown credential
+ * field the cache file might carry (apiKey, privateKey, …) — is never printed; all
+ * other metadata (expiresAt, userName, productCode, …) is preserved.
+ */
+export function redactTokenCache(cache) {
+    if (!cache)
+        return null;
+    const SENSITIVE = /token|secret|password|credential|key/i;
+    const out = {};
+    for (const [key, value] of Object.entries(cache)) {
+        out[key] = SENSITIVE.test(key) ? "<redacted>" : value;
+    }
+    return out;
+}
 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) {

package/dist/src/core/client.js

@@ -17,11 +17,14 @@ export class GangtiseClient {
     config;
     refreshPromise = null;
     memoCache = null;
+    // After an injected env token (GANGTISE_TOKEN) is rejected and we self-heal via
+    // login, stop preferring that now-stale token so the retry uses the fresh one.
+    envTokenInvalidated = false;
     constructor(config) {
         this.config = config;
     }
     async getAuthorizationHeader(forceRefresh = false) {
-        if (this.config.token && !forceRefresh) {
+        if (this.config.token && !this.envTokenInvalidated && !forceRefresh) {
             return normalizeToken(this.config.token);
         }
         if (!forceRefresh) {
@@ -69,6 +72,7 @@ export class GangtiseClient {
             && this.config.secretKey) {
             authState.retried = true;
             this.memoCache = null;
+            this.envTokenInvalidated = true;
             await this.getAuthorizationHeader(true);
             throw markRetryable(new ApiError(error.message, error.code, error.statusCode, error.details));
         }
@@ -175,19 +179,40 @@ export class GangtiseClient {
         }
         let unexpectedShape = false;
         let totalDrift = false;
+        // Fail-soft fan-out: a hard page failure (rate-limit 903301, no-perm, retries
+        // exhausted) must NOT discard the pages already fetched. Catch per page, record
+        // it, and stop starting new requests so we don't keep burning quota into a rate
+        // limit. Mirrors quoteSharding's partial-result tolerance — but firstPage already
+        // succeeded to get here, so unlike sharding there's no total-failure case.
+        const failedPages = [];
+        let firstError = null;
+        let aborted = false;
         const pages = await runWithConcurrency(pageRequests, PAGINATION_CONCURRENCY, async (req) => {
-            const page = await this.requestJson(endpoint, {
-                ...initialBody,
-                from: req.from,
-                size: req.size,
-            });
-            if (!this.isPaginatedListResponse(page)) {
-                unexpectedShape = true;
+            if (aborted) {
+                failedPages.push(req);
+                return [];
+            }
+            try {
+                const page = await this.requestJson(endpoint, {
+                    ...initialBody,
+                    from: req.from,
+                    size: req.size,
+                });
+                if (!this.isPaginatedListResponse(page)) {
+                    unexpectedShape = true;
+                    return [];
+                }
+                if (page.total !== total)
+                    totalDrift = true;
+                return page.list;
+            }
+            catch (error) {
+                if (!firstError)
+                    firstError = error;
+                aborted = true;
+                failedPages.push(req);
                 return [];
             }
-            if (page.total !== total)
-                totalDrift = true;
-            return page.list;
         });
         for (const list of pages) {
             if (list.length === 0)
@@ -206,11 +231,82 @@ export class GangtiseClient {
         if (truncatedByPageCap) {
             process.stderr.write(`[gangtise] warning: hit the ${MAX_PAGES}-page safety cap; fetched ${collected.length} of ${total} rows. Narrow the query (e.g. a shorter date range) or pass --size to fetch a bounded subset.\n`);
         }
-        return {
+        const out = {
             ...firstPage,
             total,
             list: requestedSize === undefined ? collected : collected.slice(0, requestedSize),
         };
+        if (failedPages.length > 0) {
+            out.partial = true;
+            out.failedPages = failedPages.map((p) => ({ from: p.from, size: p.size }));
+            const detail = firstError instanceof Error ? `: ${firstError.message}` : "";
+            process.stderr.write(`[gangtise] warning: ${failedPages.length}/${pageRequests.length} pages not fetched${detail}; results are partial — got ${collected.length}/${total} rows (see failedPages). A page hit a non-retryable error (e.g. rate limit); remaining pages were skipped.\n`);
+        }
+        return out;
+    }
+    /**
+     * Sequential pagination for endpoints that page by offset but return NO `total`
+     * and use a non-standard list key (e.g. wechat chatroom's `chatRoomList`). We
+     * can't fan out like requestPaginated (no total ⇒ unknown page count), so page
+     * serially until a short page (fewer rows than requested) signals the end.
+     * Returns `{ [listKey]: rows }` so normalize/printer treat it like any list.
+     */
+    async requestSequentialPaginated(endpoint, body) {
+        const initialBody = body && typeof body === 'object' ? { ...body } : {};
+        if ('from' in initialBody && (typeof initialBody.from !== 'number' || !Number.isFinite(initialBody.from) || initialBody.from < 0)) {
+            throw new ValidationError('Invalid from: expected a non-negative number');
+        }
+        if ('size' in initialBody && initialBody.size !== undefined && (typeof initialBody.size !== 'number' || !Number.isFinite(initialBody.size) || initialBody.size <= 0)) {
+            throw new ValidationError('Invalid size: expected a positive number');
+        }
+        const listKey = endpoint.pagination?.listKey ?? 'list';
+        const maxPageSize = endpoint.pagination?.maxPageSize ?? 50;
+        const startFrom = typeof initialBody.from === 'number' && Number.isFinite(initialBody.from) ? initialBody.from : 0;
+        const requestedSize = typeof initialBody.size === 'number' && Number.isFinite(initialBody.size) ? initialBody.size : undefined;
+        const extractList = (page) => {
+            if (!page || typeof page !== 'object')
+                return null;
+            const arr = page[listKey];
+            return Array.isArray(arr) ? arr : null;
+        };
+        const collected = [];
+        let firstPage = null;
+        let from = startFrom;
+        const MAX_PAGES = 1000;
+        let truncatedByPageCap = false;
+        for (let page = 0;; page++) {
+            const remaining = requestedSize === undefined ? maxPageSize : requestedSize - collected.length;
+            if (requestedSize !== undefined && remaining <= 0)
+                break;
+            const size = Math.min(maxPageSize, remaining);
+            const pageData = await this.requestJson(endpoint, { ...initialBody, from, size });
+            if (firstPage === null)
+                firstPage = pageData;
+            const list = extractList(pageData);
+            if (list === null) {
+                // First response isn't a paginated-list shape → return it untouched. But a
+                // LATER page losing shape must NOT discard the rows already collected (mirrors
+                // requestPaginated's fail-soft fan-out): stop, keep them, and warn loudly.
+                if (page === 0)
+                    return firstPage;
+                process.stderr.write(`[gangtise] warning: a page response had unexpected shape; results are partial — ${collected.length} rows fetched.\n`);
+                break;
+            }
+            for (const item of list)
+                collected.push(item);
+            if (list.length < size)
+                break; // short page ⇒ no more rows
+            if (page + 1 >= MAX_PAGES) {
+                truncatedByPageCap = true;
+                break;
+            }
+            from += list.length;
+        }
+        if (truncatedByPageCap) {
+            process.stderr.write(`[gangtise] warning: hit the ${MAX_PAGES}-page safety cap; fetched ${collected.length} rows. Pass --size to fetch a bounded subset.\n`);
+        }
+        const rows = requestedSize === undefined ? collected : collected.slice(0, requestedSize);
+        return { [listKey]: rows };
     }
     async login() {
         const authorization = await this.getAuthorizationHeader();
@@ -379,7 +475,9 @@ export class GangtiseClient {
             return this.download(endpoint, query ?? {}, options);
         }
         if (endpoint.kind === 'json' && endpoint.pagination?.enabled) {
-            return this.requestPaginated(endpoint, body);
+            return endpoint.pagination.sequential
+                ? this.requestSequentialPaginated(endpoint, body)
+                : this.requestPaginated(endpoint, body);
         }
         return this.requestJson(endpoint, body);
     }

package/dist/src/core/download.js

@@ -2,6 +2,13 @@ import { extname } from "node:path";
 import { DownloadError } from "./errors.js";
 import { saveOutputIfNeeded } from "./output.js";
 import { lookupTitleCache, readTitleCache, TITLE_LOOKUP_SIZE } from "./titleCache.js";
+/** Replace filesystem-unsafe characters (path separators, wildcards, and control
+ * characters / NUL) with `_` so a title or a server-supplied filename can't create
+ * stray subdirectories, escape the intended output path, or break fs.writeFile.
+ * Shared by title-based naming and the download fallback. */
+function sanitizeFilename(name) {
+    return name.replace(/[/\\:*?"<>|\u0000-\u001f]/g, "_");
+}
 const MIME_EXT = {
     "application/pdf": ".pdf",
     "application/msword": ".doc",
@@ -38,7 +45,7 @@ export async function resolveTitle(client, result, listEndpoint, idField, idValu
     const file = result;
     const serverExt = file.filename ? extname(file.filename) : extFromContentType(file.contentType);
     function buildFilename(rawTitle) {
-        let title = rawTitle.replace(/[/\\:*?"<>|]/g, "_").trim();
+        let title = sanitizeFilename(rawTitle).trim();
         if (serverExt && !title.toLowerCase().endsWith(serverExt.toLowerCase())) {
             title += serverExt;
         }
@@ -76,7 +83,9 @@ export async function saveDownloadResult(result, fallbackName, output) {
         return;
     }
     if (file.data instanceof Uint8Array) {
-        const outputPath = output ?? file.filename ?? (fallbackName + extFromContentType(file.contentType));
+        // Sanitize the server-provided filename so a Content-Disposition value with
+        // / or : can't write outside the intended path (same rule as buildFilename).
+        const outputPath = output ?? (file.filename ? sanitizeFilename(file.filename) : undefined) ?? (fallbackName + extFromContentType(file.contentType));
         await saveOutputIfNeeded(file.data, outputPath);
         process.stdout.write(`${outputPath}\n`);
         return;

package/dist/src/core/endpoints.js

@@ -138,6 +138,21 @@ export const ENDPOINTS = {
         kind: "download",
         description: "Download HK announcement file",
     },
+    "insight.announcement-us.list": {
+        key: "insight.announcement-us.list",
+        method: "POST",
+        path: "/application/open-insight/announcement-us/getList",
+        kind: "json",
+        description: "List US announcements",
+        pagination: { enabled: true, maxPageSize: 50 },
+    },
+    "insight.announcement-us.download": {
+        key: "insight.announcement-us.download",
+        method: "GET",
+        path: "/application/open-insight/announcement-us/download/file",
+        kind: "download",
+        description: "Download US announcement file",
+    },
     "insight.foreign-opinion.list": {
         key: "insight.foreign-opinion.list",
         method: "POST",
@@ -184,6 +199,13 @@ export const ENDPOINTS = {
         kind: "json",
         description: "Search GTS codes (securities)",
     },
+    "reference.chiefs-search": {
+        key: "reference.chiefs-search",
+        method: "POST",
+        path: "/application/open-reference/chiefs/search",
+        kind: "json",
+        description: "Search chief analyst IDs by name / institution / team",
+    },
     "reference.constant-category": {
         key: "reference.constant-category",
         method: "GET",
@@ -319,6 +341,27 @@ export const ENDPOINTS = {
         kind: "json",
         description: "Query HK cash flow statement (China GAAP)",
     },
+    "fundamental.income-statement-us": {
+        key: "fundamental.income-statement-us",
+        method: "POST",
+        path: "/application/open-fundamental/financial-report/income-statement/us",
+        kind: "json",
+        description: "Query US income statement",
+    },
+    "fundamental.balance-sheet-us": {
+        key: "fundamental.balance-sheet-us",
+        method: "POST",
+        path: "/application/open-fundamental/financial-report/balance-sheet/us",
+        kind: "json",
+        description: "Query US balance sheet",
+    },
+    "fundamental.cash-flow-us": {
+        key: "fundamental.cash-flow-us",
+        method: "POST",
+        path: "/application/open-fundamental/financial-report/cash-flow-statement/us",
+        kind: "json",
+        description: "Query US cash flow statement",
+    },
     "fundamental.main-business": {
         key: "fundamental.main-business",
         method: "POST",
@@ -348,6 +391,13 @@ export const ENDPOINTS = {
         description: "Query earning forecast (consensus estimates)",
     },
     // ─── ai ───
+    "ai.stock-summary.list": {
+        key: "ai.stock-summary.list",
+        method: "POST",
+        path: "/application/open-ai/stock-summary/getList",
+        kind: "json",
+        description: "Stock highlights (refined research summary per security)",
+    },
     "ai.knowledge-batch": {
         key: "ai.knowledge-batch",
         method: "POST",
@@ -515,6 +565,8 @@ export const ENDPOINTS = {
         path: "/application/open-vault/wechatgroupmsg/chatroomId",
         kind: "json",
         description: "List WeChat group chatroom IDs",
+        // No `total` in the response, list key is `chatRoomList`, server caps size at 50.
+        pagination: { enabled: true, maxPageSize: 50, sequential: true, listKey: "chatRoomList" },
     },
     "vault.stock-pool.list": {
         key: "vault.stock-pool.list",

package/dist/src/core/indicatorMatrix.js

@@ -46,23 +46,22 @@ function buildHeaders(names, codes, count) {
     return headers;
 }
 // Cross-section: one row per security, one column per indicator. The live
-// `values` is a flat [numIndicators * numSecurities][1] array in
-// indicator-major order, so indicator i on security j is values[i*numSec+j][0].
+// `values` is a 2D [numIndicators][numSecurities] matrix in indicator-major
+// order, so indicator i on security j is values[i][j].
 export function flattenCrossSection(data) {
     if (!data || typeof data !== "object")
         return data;
     const d = data;
-    const securityCode = asStringArray(d.securityCode);
-    const indicators = asStringArray(d.indicators);
+    const securityCode = asStringArray(d.securityCodeList);
+    const indicators = asStringArray(d.indicatorCodeList);
     if (!Array.isArray(d.values) || !securityCode || !indicators)
         return data;
-    const securityName = asStringArray(d.securityName);
-    const headers = buildHeaders(asStringArray(d.indicatorName), indicators, indicators.length);
-    const numSec = securityCode.length;
+    const securityName = asStringArray(d.securityNameList);
+    const headers = buildHeaders(asStringArray(d.indicatorNameList), indicators, indicators.length);
     const list = securityCode.map((code, j) => {
         const row = { date: d.date, security: code, name: securityName?.[j] };
         for (let i = 0; i < indicators.length; i++) {
-            row[headers[i]] = rowOf(d.values, i * numSec + j)?.[0];
+            row[headers[i]] = rowOf(d.values, i)?.[j];
         }
         return row;
     });
@@ -76,14 +75,14 @@ export function flattenTimeSeries(data) {
         return data;
     const d = data;
     const dates = asStringArray(d.dates);
-    const securityCode = asStringArray(d.securityCode);
-    const indicators = asStringArray(d.indicators);
+    const securityCode = asStringArray(d.securityCodeList);
+    const indicators = asStringArray(d.indicatorCodeList);
     if (!Array.isArray(d.values) || !dates || !securityCode || !indicators)
         return data;
     const seriesAreIndicators = securityCode.length <= 1;
     const headers = seriesAreIndicators
-        ? buildHeaders(asStringArray(d.indicatorName), indicators, indicators.length)
-        : buildHeaders(asStringArray(d.securityName), securityCode, securityCode.length);
+        ? buildHeaders(asStringArray(d.indicatorNameList), indicators, indicators.length)
+        : buildHeaders(asStringArray(d.securityNameList), securityCode, securityCode.length);
     const list = dates.map((date, k) => {
         const row = { date };
         for (let i = 0; i < headers.length; i++) {

package/dist/src/core/output.js

@@ -42,14 +42,17 @@ function renderTable(rows) {
         return "(empty)";
     }
     const columns = Array.from(new Set(rows.flatMap((row) => Object.keys(row))));
-    const widths = columns.map((column) => {
-        const cellWidths = rows.map((row) => formatScalar(row[column]).length);
-        return Math.max(column.length, ...cellWidths);
-    });
+    // Format every cell once (formatScalar may JSON.stringify objects), collapsing
+    // newlines so multi-line fields don't break alignment. Reuse the matrix for both
+    // width and rendering — and compute widths with reduce, NOT Math.max(...arr):
+    // spreading a per-row array overflows the call stack on large results (table is
+    // the default format, e.g. `quote day-kline --security all`).
+    const matrix = rows.map((row) => columns.map((column) => formatScalar(row[column]).replace(/[\r\n]+/g, " ")));
+    const widths = columns.map((column, c) => matrix.reduce((max, cells) => Math.max(max, cells[c].length), column.length));
     const renderLine = (values) => values.map((value, index) => value.padEnd(widths[index], " ")).join("  ");
     const header = renderLine(columns);
     const divider = renderLine(widths.map((width) => "-".repeat(width)));
-    const body = rows.map((row) => renderLine(columns.map((column) => formatScalar(row[column]))));
+    const body = matrix.map((cells) => renderLine(cells));
     return [header, divider, ...body].join("\n");
 }
 function renderMarkdown(rows) {
@@ -59,7 +62,7 @@ function renderMarkdown(rows) {
     const columns = Array.from(new Set(rows.flatMap((row) => Object.keys(row))));
     const header = `| ${columns.join(" | ")} |`;
     const divider = `| ${columns.map(() => "---").join(" | ")} |`;
-    const body = rows.map((row) => `| ${columns.map((column) => formatScalar(row[column]).replaceAll("|", "\\|")).join(" | ")} |`);
+    const body = rows.map((row) => `| ${columns.map((column) => formatScalar(row[column]).replace(/[\r\n]+/g, " ").replaceAll("|", "\\|")).join(" | ")} |`);
     return [header, divider, ...body].join("\n");
 }
 function renderCsv(rows) {
@@ -96,7 +99,7 @@ export function renderOutput(value, format) {
 export async function streamOutputToFile(value, format, outputPath) {
     if (format !== "jsonl" && format !== "csv")
         return false;
-    const list = pickListForStreaming(value);
+    const list = pickList(value);
     if (!list)
         return false;
     // Below this row count the join() approach is cheaper than per-row writes.
@@ -129,7 +132,9 @@ export async function streamOutputToFile(value, format, outputPath) {
     }
     return true;
 }
-function pickListForStreaming(value) {
+/** Extract a row array from a value: the array itself, or its `.list` property,
+ * else null. Shared by streaming, printer's title-cache, and list detection. */
+export function pickList(value) {
     if (Array.isArray(value))
         return value;
     if (value && typeof value === "object") {
@@ -141,9 +146,12 @@ function pickListForStreaming(value) {
 }
 function csvEscape(value) {
     let out = value;
-    if (/^[=+\-@\t\r]/.test(out))
+    // Formula-injection guard, but don't mangle legitimate numbers: a leading
+    // -/+ only needs escaping when the cell isn't a finite number (e.g. "-1+cmd"),
+    // so values like "-3.5" stay numeric for Excel/pandas.
+    if (/^[=@\t\r]/.test(out) || (/^[+\-]/.test(out) && !Number.isFinite(Number(out))))
         out = "'" + out;
-    if (/[",\n]/.test(out))
+    if (/[",\n\r]/.test(out))
         return `"${out.replaceAll("\"", "\"\"")}"`;
     return out;
 }
@@ -161,7 +169,7 @@ export async function saveOutputIfNeeded(content, outputPath) {
         return;
     }
     const { dirname } = await import("node:path");
-    await (await import("node:fs/promises")).mkdir(dirname(outputPath), { recursive: true });
+    await fs.mkdir(dirname(outputPath), { recursive: true });
     if (typeof content === "string") {
         await fs.writeFile(outputPath, content, "utf8");
         return;

package/dist/src/core/printer.js

@@ -1,13 +1,9 @@
 import { normalizeRows } from "./normalize.js";
-import { renderOutput, saveOutputIfNeeded, streamOutputToFile } from "./output.js";
+import { pickList, renderOutput, saveOutputIfNeeded, streamOutputToFile } from "./output.js";
 import { extractTitles, writeTitleCache } from "./titleCache.js";
 export async function printData(data, format, output, cache) {
     const normalized = normalizeRows(data);
-    const items = Array.isArray(normalized)
-        ? normalized
-        : (normalized && typeof normalized === "object" && Array.isArray(normalized.list))
-            ? normalized.list
-            : null;
+    const items = pickList(normalized);
     if (cache && items) {
         const titles = extractTitles(items, cache);
         if (Object.keys(titles).length > 0) {

package/dist/src/core/quoteSharding.js

@@ -93,8 +93,11 @@ export async function callKlineWithSharding(client, endpointKey, body, config) {
             header = rec;
         if (!fieldList && Array.isArray(rec.fieldList))
             fieldList = rec.fieldList;
+        // Append one-by-one rather than push(...list): a future higher row cap could
+        // make a single shard's list large enough to overflow the stack via spread.
         if (Array.isArray(rec.list))
-            merged.push(...rec.list);
+            for (const item of rec.list)
+                merged.push(item);
     }
     // Every shard failed → surface the error loudly (non-zero exit) rather than
     // masking a total outage as an empty success.

package/dist/src/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gangtise-openapi-cli",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "CLI for Gangtise OpenAPI",
   "license": "MIT",
   "repository": {
@@ -26,6 +26,7 @@
     "build": "tsc -p tsconfig.json",
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
     "prepare": "node scripts/prepare.cjs && npm run build"
   },
   "engines": {
@@ -39,6 +40,6 @@
     "@types/node": "^24.3.0",
     "tsx": "^4.20.5",
     "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.6"
   }
 }