gangtise-openapi-cli 0.18.0 → 0.20.0

package/README.md

@@ -1,9 +1,59 @@
 # Gangtise OpenAPI CLI
 
-一个可直接调用 Gangtise OpenAPI 获取金融数据的命令行工具，同时提供Agent Skill。
+一个可直接调用 Gangtise OpenAPI 获取全量金融信息的命令行工具，同时提供Agent Skill。
 
 ## Changelog
 
+### 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）**
+- `indicator search` — 按名称搜索证券级数据指标，返回 `indicatorCode` 及可传参数 `parameterList`（含 `required` 必填标记与枚举）；取数前必先 search 拿 code，绝不猜编码
+- `indicator cross-section` — 指标截面数据（多指标 × 多证券，单日快照）：`--indicator` / `--security`（均可重复）/ `--date` / `--currency` / `--scale` / `--indicator-param`
+- `indicator time-series` — 指标时间序列（多指标 × 单证券 或 单指标 × 多证券，按区间）：另有 `--start-date` / `--end-date` / `--calendar-type`（`ND`/`TD`/`WD`）
+- 复权等指标专属参数用 `--indicator-param "code:key=value"`，参数 key 与取值以 search 的 `parameterList` 为准（行情复权键为 `adjustmentType`：`1` 不复权 / `2` 前复权 / `3` 后复权）
+- 很多指标有必填参数，默认调用会报 `410106`（缺必填参数）：N 期统计补 `periodNum`、区间/周期类补 `startDate`、年度/分红类补 `fiscalYear`；`999999` 多为「该证券公司类型/报告期无数据」而非系统故障。详见 `gangtise-openapi/references/commands/indicator.md`
+
+**修复**
+- `vault stock-pool-stocks --pool-id <id>` 过滤失效：此前因选项默认值 `["all"]` 泄漏，传具体 pool id 仍返回全部股票池证券；现已修复——传 id 精确过滤，省略则默认全量
+- `auth` 缺凭证报错补充跨 shell（bash/zsh/fish）的 `export` 提示
+
+**文档**
+- README / SKILL 补充 indicator 命令组与取数最佳实践；`official-account` 命令文档补全
+
+### v0.18.0 — 2026-06-17
+
+**新增接口（Insight · 产业公众号资讯）**
+- `insight official-account list` — 查询公众号资讯列表：支持 `--keyword`（需用数据中的具体词，非整句白话）/ `--account-id`（公众号 ID）/ `--security` / `--category`（文章类型枚举：`news`/`law`/`report`/`view`/`data`/`event`/`meeting`/`notice`/`recruit`/`investEdu`/`brand`/`notes`/`other`）/ `--industry`（`citicIndustry`/`swIndustry` 行业 ID）/ `--search-type`（`1` 标题 / `2` 全文）/ `--rank-type`（`1` 综合 / `2` 时间倒序）；返回含模型生成摘要 `summary` 及关联行业/题材/证券列表
+- `insight official-account download --article-id <id>` — 下载公众号文章：`--file-type 1` txt（默认）/ `2` HTML
+
 ### v0.17.0 — 2026-06-15
 
 **接口变更（Breaking）**
@@ -28,106 +78,7 @@
 - `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` 群消息
+> 更早版本（v0.15.0 及之前）的完整更新历史见 [GitHub Releases](https://github.com/gangtiser/gangtise-openapi-cli/releases)。
 
 ## 首次安装
 
@@ -141,6 +92,12 @@ npm install -g gangtise-openapi-cli
 gangtise --help
 ```
 
+更新到最新版（`gangtise --version` 会自动与线上版本比对）：
+
+```bash
+npm update -g gangtise-openapi-cli
+```
+
 本地开发：
 
 ```bash
@@ -150,36 +107,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
-```
-
-
 ## 环境配置
 
 优先读取以下环境变量：
@@ -217,6 +144,7 @@ gangtise-openapi/
     │   ├── ai.md                     #   AI 能力命令（one-pager / earnings-review / viewpoint-debate 等）
     │   ├── alternative.md            #   行业指标数据库（EDB search / EDB data）
     │   ├── fundamental.md            #   财务数据命令（A股/港股三大报表 / 估值 / 盈利预测 / 股东）
+    │   ├── indicator.md              #   证券级数据指标 EDE（search / 截面 / 时序）
     │   ├── insight.md                #   投研内容命令（研报 / 观点 / 纪要 / 公告 / 外资）
     │   ├── quote.md                  #   行情命令（A股/港股/指数 K 线）
     │   ├── reference-and-lookup.md   #   GTS Code 搜索与枚举速查
@@ -269,10 +197,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 搜索（名称/拼音/分组名匹配） |
@@ -285,6 +216,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` | 盈利预测（一致预期） |
@@ -292,6 +224,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` | 同业对比 |
@@ -307,6 +240,9 @@ cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
 | | `my-conference-list` / `my-conference-download` | 我的会议列表与下载 |
 | | `wechat-message-list` / `wechat-chatroom-list` | 群消息列表与群ID查询 |
 | | `stock-pool-list` / `stock-pool-stocks` | 自选股股票池列表与证券明细 |
+| **Indicator** | `search` | 证券级数据指标搜索（按名称匹配，返回 indicatorCode 及可传参数 parameterList） |
+| | `cross-section` | 指标截面数据（多指标 × 多证券，单日快照；前置 `search` 拿 code） |
+| | `time-series` | 指标时间序列（多指标 × 单证券 或 单指标 × 多证券，按区间） |
 | **Alternative** | `edb-search` | 行业指标搜索（按关键词匹配，返回 indicatorId 等元信息） |
 | | `edb-data` | 行业指标时序数据（批量拉取，最多10个指标） |
 | | `concept-info` | 题材指数基本信息（投资逻辑/行业空间/竞争格局/催化事件） |
@@ -376,8 +312,10 @@ 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`
 - `ai security-clue`
 - `vault drive-list`
 - `vault record-list`
@@ -395,7 +333,7 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 
 ## 智能文件命名
 
-下载命令（`summary download`、`research download`、`foreign-report download`、`announcement 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 条记录匹配标题
@@ -446,6 +384,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
@@ -455,6 +398,10 @@ gangtise insight foreign-opinion list --security APP.O --rating buy --format jso
 gangtise insight independent-opinion list --keyword "肿瘤" --industry 100800118 --format json
 gangtise insight independent-opinion download --independent-opinion-id 207051900018372 --file-type 2
 
+# 产业公众号资讯
+gangtise insight official-account list --keyword 泡泡玛特 --rank-type 2 --size 20 --format json
+gangtise insight official-account download --article-id 7286248 --file-type 2
+
 # 纪要下载（会议平台来源可选 HTML 格式）
 gangtise insight summary download --summary-id 4906813 --file-type 2
 ```
@@ -468,10 +415,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
@@ -546,6 +498,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
@@ -556,6 +513,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
@@ -613,6 +573,34 @@ gangtise vault stock-pool-stocks --pool-id 808477293
 gangtise vault stock-pool-stocks
 ```
 
+### Indicator（证券级数据指标 EDE）
+
+```bash
+# Step 1：按名称搜索，拿 indicatorCode（绝不猜编码）；--format json 看可传参数 parameterList 及 required
+gangtise indicator search --keyword 收盘价 --format table             # → qte_close
+gangtise indicator search --keyword 平均ROE --limit 5 --format json    # 看 parameterList
+
+# 截面：多指标 × 多证券，单日快照（行情类用交易日；财务类用报告期末，如 2026-03-31）
+gangtise indicator cross-section \
+  --indicator qte_close --indicator qte_vol --indicator qte_mkt_cptl \
+  --security 600519.SH --security 09992.HK \
+  --date 2026-05-18 --format table
+
+# 时间序列：多指标 × 单证券 或 单指标 × 多证券（不能多 × 多，否则报 410001）
+gangtise indicator time-series --indicator qte_close \
+  --security 600519.SH --security 09992.HK \
+  --start-date 2026-05-12 --end-date 2026-05-18 --format table
+
+# 复权 / 指标专属参数用 --indicator-param "code:key=value"，参数 key 以 search 的 parameterList 为准
+gangtise indicator cross-section --indicator qte_close --security 600519.SH \
+  --date 2026-05-18 --indicator-param "qte_close:adjustmentType=3"   # 1不复权/2前复权/3后复权
+
+# 必填参数：很多指标默认调用报 410106（缺必填参数），按 parameterList 的 required 补齐再取：
+#   N 期统计补 periodNum、区间/周期类（如 qte_amp_mo 月振幅）补 startDate、年度/分红类补 fiscalYear
+gangtise indicator cross-section --indicator finc_roe_avg_avg --security 600519.SH \
+  --date 2026-03-31 --indicator-param "finc_roe_avg_avg:periodNum=4"
+```
+
 ### Alternative（行业指标数据库 EDB）
 
 ```bash
@@ -694,3 +682,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,14 +1,15 @@
 #!/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 { buildQuoteKlineBody, buildWechatChatroomListBody, buildWechatMessageListBody } from "./core/commandBodies.js";
+import { buildIndicatorCrossSectionBody, buildIndicatorTimeSeriesBody, buildQuoteKlineBody, buildStockPoolStocksBody, buildWechatChatroomListBody, buildWechatMessageListBody } from "./core/commandBodies.js";
+import { flattenCrossSection, flattenTimeSeries, unwrapIndicatorData } from "./core/indicatorMatrix.js";
 import { callKlineWithSharding } from "./core/quoteSharding.js";
 import { loadConfig } from "./core/config.js";
 import { resolveTitle, saveDownloadResult } from "./core/download.js";
 import { 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";
@@ -99,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) => {
@@ -129,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");
@@ -214,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"),
@@ -229,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,
@@ -268,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);
@@ -299,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) });
@@ -327,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,
@@ -371,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", {
@@ -405,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,
@@ -422,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" }));
@@ -433,7 +473,7 @@ addDownloadCommand(vault, { endpointKey: "vault.my-conference.download", name: "
 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("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; use 'all' for all pools", collectList, ["all"]).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("vault.stock-pool.stocks", { poolIdList: options.poolId })));
+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);
 program.addCommand(ai);
 const alternative = new Command("alternative").description("Alternative data APIs");
@@ -460,6 +500,23 @@ alternative.command("edb-data").option("--indicator-id <id>", "Indicator ID (rep
 alternative.command("concept-info").requiredOption("--concept-id <id>", "Concept (theme index) ID, e.g. 121000130 机器人; discover via 'gangtise reference concept-search'").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => emit(options, (client) => client.call("alternative.concept-info", { conceptId: options.conceptId })));
 alternative.command("concept-securities").requiredOption("--concept-id <id>", "Concept (theme index) ID, e.g. 121000130 机器人; discover via 'gangtise reference concept-search'").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => emit(options, (client) => client.call("alternative.concept-securities", { conceptId: options.conceptId })));
 program.addCommand(alternative);
+const indicator = new Command("indicator").description("Data indicator (EDE) APIs: search codes, cross-section, time-series");
+indicator.command("search").requiredOption("--keyword <text>", "Search keyword, e.g. '收盘价' '成交量' '营业收入' (not free-form questions)").option("--limit <number>", "Max results (default: 50, max: 100)", "50").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
+    const raw = await client.call("indicator.search", {
+        keyword: options.keyword,
+        limit: parseNumberOption(options.limit, "--limit", { integer: true, min: 1 }),
+    });
+    await printData(unwrapIndicatorData(raw), parseOutputFormat(options.format), options.output);
+}));
+indicator.command("cross-section").option("--indicator <code>", "Indicator code, e.g. qte_close (repeat for multiple)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH (repeat for multiple)", collectList, []).requiredOption("--date <date>", "Data date (yyyy-MM-dd)").option("--currency <code>", "Currency: DFT/CNY/HKD/USD/EUR/GBP/JPY/TWD/MOP/AUD (default DFT)").option("--scale <code>", "Scale: 0=个 3=千 4=万 6=百万 8=亿 9=十亿 (default 0)").option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustmentType=2 for 前复权 (repeat)", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
+    const raw = await client.call("indicator.cross-section", buildIndicatorCrossSectionBody(options));
+    await printData(flattenCrossSection(unwrapIndicatorData(raw)), parseOutputFormat(options.format), options.output);
+}));
+indicator.command("time-series").option("--indicator <code>", "Indicator code, e.g. qte_close (repeat for multiple)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH (repeat for multiple)", collectList, []).requiredOption("--start-date <date>", "Start date (yyyy-MM-dd)").requiredOption("--end-date <date>", "End date (yyyy-MM-dd)").option("--calendar-type <type>", "Calendar: ND=natural TD=trading WD=weekday (default TD)").option("--currency <code>", "Currency: DFT/CNY/HKD/USD/EUR/GBP/JPY/TWD/MOP/AUD (default DFT)").option("--scale <code>", "Scale: 0=个 3=千 4=万 6=百万 8=亿 9=十亿 (default 0)").option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustmentType=2 for 前复权 (repeat)", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
+    const raw = await client.call("indicator.time-series", buildIndicatorTimeSeriesBody(options));
+    await printData(flattenTimeSeries(unwrapIndicatorData(raw)), parseOutputFormat(options.format), options.output);
+}));
+program.addCommand(indicator);
 program.command("raw").description("Raw API calls").addCommand(new Command("call").argument("<endpointKey>").option("--body <json>").option("--query <key=value>", "Query string pair", collectKeyValue, {}).option("--format <format>", "Output format", "json").option("--output <path>").action(async (endpointKey, options) => {
     const endpoint = ENDPOINTS[endpointKey];
     if (!endpoint) {

package/dist/src/core/args.js

@@ -79,3 +79,29 @@ export function parseTimestamp13(value, optionName) {
     }
     return parsed;
 }
+// Parse repeatable `--indicator-param "code:key=value"` specs into the nested
+// indicatorParamList the EDE cross-section / time-series endpoints expect.
+// Multiple specs for the same code accumulate into one group, first-seen order.
+export function parseIndicatorParams(specs) {
+    if (specs.length === 0)
+        return undefined;
+    const groups = new Map();
+    for (const spec of specs) {
+        const colon = spec.indexOf(":");
+        const rest = colon === -1 ? "" : spec.slice(colon + 1);
+        const eq = rest.indexOf("=");
+        const code = colon === -1 ? "" : spec.slice(0, colon).trim();
+        const paramKey = eq === -1 ? "" : rest.slice(0, eq).trim();
+        const paramValue = eq === -1 ? "" : rest.slice(eq + 1).trim();
+        if (!code || !paramKey) {
+            throw new ValidationError(`Invalid --indicator-param: expected "code:key=value", got "${spec}"`);
+        }
+        let group = groups.get(code);
+        if (!group) {
+            group = { indicatorCode: code, parameters: [] };
+            groups.set(code, group);
+        }
+        group.parameters.push({ paramKey, paramValue });
+    }
+    return [...groups.values()];
+}

package/dist/src/core/auth.js

@@ -14,6 +14,23 @@ 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 });
@@ -30,7 +47,12 @@ export function normalizeToken(token) {
 }
 export function requireAccessCredentials(accessKey, secretKey) {
     if (!accessKey || !secretKey) {
-        throw new ConfigError("Missing GANGTISE_ACCESS_KEY or GANGTISE_SECRET_KEY");
+        const missing = [!accessKey && "GANGTISE_ACCESS_KEY", !secretKey && "GANGTISE_SECRET_KEY"].filter(Boolean).join(", ");
+        throw new ConfigError(`缺少环境变量: ${missing}（未导出到当前进程环境）\n`
+            + `注意：在 shell 里赋值还不够，必须"导出"，子进程才读得到：\n`
+            + `  bash/zsh:  export GANGTISE_ACCESS_KEY=... GANGTISE_SECRET_KEY=...\n`
+            + `  fish:      set -gx GANGTISE_ACCESS_KEY ...; set -gx GANGTISE_SECRET_KEY ...\n`
+            + `验证：env | grep GANGTISE（能列出对应行才算导出成功）`);
     }
     return { accessKey, secretKey };
 }

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,18 @@ 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;
     }
     async login() {
         const authorization = await this.getAuthorizationHeader();

package/dist/src/core/commandBodies.js

@@ -1,4 +1,4 @@
-import { maybeArray, parseFrom, parseOptionalNumberOption, parseSize } from "./args.js";
+import { maybeArray, parseFrom, parseIndicatorParams, parseOptionalNumberOption, parseSize } from "./args.js";
 export function buildQuoteKlineBody(options) {
     return {
         securityList: maybeArray(options.security),
@@ -29,3 +29,30 @@ export function buildWechatChatroomListBody(options) {
         roomName: options.roomName.length > 0 ? options.roomName.join(",") : undefined,
     };
 }
+export function buildStockPoolStocksBody(options) {
+    return {
+        poolIdList: options.poolId?.length ? options.poolId : ["all"],
+    };
+}
+export function buildIndicatorCrossSectionBody(options) {
+    return {
+        indicatorCodeList: maybeArray(options.indicator),
+        securityCodeList: maybeArray(options.security),
+        date: options.date,
+        currency: options.currency,
+        scale: options.scale,
+        indicatorParamList: parseIndicatorParams(options.indicatorParam),
+    };
+}
+export function buildIndicatorTimeSeriesBody(options) {
+    return {
+        indicatorCodeList: maybeArray(options.indicator),
+        securityCodeList: maybeArray(options.security),
+        startDate: options.startDate,
+        endDate: options.endDate,
+        calendarType: options.calendarType,
+        currency: options.currency,
+        scale: options.scale,
+        indicatorParamList: parseIndicatorParams(options.indicatorParam),
+    };
+}

package/dist/src/core/download.js

@@ -2,6 +2,12 @@ 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 with `_` so a title or a server-supplied
+ * filename can't create stray subdirectories or escape the intended output path.
+ * Shared by title-based naming and the download fallback. */
+function sanitizeFilename(name) {
+    return name.replace(/[/\\:*?"<>|]/g, "_");
+}
 const MIME_EXT = {
     "application/pdf": ".pdf",
     "application/msword": ".doc",
@@ -38,7 +44,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 +82,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",
@@ -559,4 +609,26 @@ export const ENDPOINTS = {
         kind: "json",
         description: "Query concept (theme index) constituent securities, grouped",
     },
+    // ─── indicator (EDE: security-level data indicators) ───
+    "indicator.search": {
+        key: "indicator.search",
+        method: "POST",
+        path: "/application/open-indicator/EDE/search",
+        kind: "json",
+        description: "Search data indicators by keyword (returns indicatorCode + params)",
+    },
+    "indicator.cross-section": {
+        key: "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)",
+    },
+    "indicator.time-series": {
+        key: "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)",
+    },
 };

package/dist/src/core/indicatorMatrix.js

@@ -0,0 +1,94 @@
+import { ApiError } from "./errors.js";
+// The EDE endpoints double-wrap on success: the shared client strips the outer
+// envelope but leaves an inner { code, status, data } around the real payload.
+// Peel that inner envelope so the list (search) / matrix (cross-section,
+// time-series) is reachable. Observed errors arrive single-enveloped (the
+// client throws on those), but a failure code carried only by the inner
+// envelope must still surface instead of rendering its null payload as success.
+export function unwrapIndicatorData(raw) {
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        const record = raw;
+        if ("data" in record && ("code" in record || "status" in record)) {
+            const code = record.code === undefined ? undefined : String(record.code);
+            const ok = record.status === true || code === "000000" || code === "0";
+            if (!ok) {
+                throw new ApiError(typeof record.msg === "string" && record.msg ? record.msg : "Indicator API request failed", code);
+            }
+            return record.data;
+        }
+    }
+    return raw;
+}
+function asStringArray(value) {
+    return Array.isArray(value) ? value.map((item) => String(item)) : undefined;
+}
+function rowOf(values, index) {
+    const row = values[index];
+    return Array.isArray(row) ? row : undefined;
+}
+// Build one column header per series. Prefer the human-readable name; on a
+// duplicate name append the code so a column is never silently overwritten.
+function buildHeaders(names, codes, count) {
+    const used = new Set();
+    const headers = [];
+    for (let i = 0; i < count; i++) {
+        const base = String(names?.[i] ?? codes?.[i] ?? `col${i}`);
+        let header = base;
+        let attempt = 1;
+        while (used.has(header)) {
+            const suffix = codes?.[i] ?? i;
+            header = attempt === 1 ? `${base} (${suffix})` : `${base} (${suffix})_${attempt}`;
+            attempt++;
+        }
+        used.add(header);
+        headers.push(header);
+    }
+    return headers;
+}
+// Cross-section: one row per security, one column per indicator. The live
+// `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.securityCodeList);
+    const indicators = asStringArray(d.indicatorCodeList);
+    if (!Array.isArray(d.values) || !securityCode || !indicators)
+        return data;
+    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)?.[j];
+        }
+        return row;
+    });
+    return { list, total: list.length };
+}
+// Time-series: one row per date. Columns are the indicators (single-security
+// case) or the securities (single-indicator case) — exactly one dimension
+// varies, per the API contract. `values` is a 2D [series][date] matrix.
+export function flattenTimeSeries(data) {
+    if (!data || typeof data !== "object")
+        return data;
+    const d = data;
+    const dates = asStringArray(d.dates);
+    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.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++) {
+            row[headers[i]] = rowOf(d.values, i)?.[k];
+        }
+        return row;
+    });
+    return { list, total: list.length };
+}

package/dist/src/core/output.js

@@ -141,7 +141,10 @@ 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))
         return `"${out.replaceAll("\"", "\"\"")}"`;

package/dist/src/version.js

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

package/package.json

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