gangtise-openapi-cli 0.28.1 → 0.28.2

package/README.md

@@ -4,6 +4,20 @@
 
 ## Changelog
 
+### v0.28.2 — 2026-07-24
+
+EDE 指标批量取数优化（基于对上游 990 个指标的实测）。
+
+**新增**
+- `indicator cross-section` / `time-series` 加 `--key-by name|code`（默认 `name`）：`code` 模式列头用 `indicatorCode`（时序多证券侧用 `securityCode`），唯一且与服务端返回列序无关。**多证券批量按 code 回填必用**——此前拍平只按指标显示名，而多个指标同名（如 `cf_finc_exp`/`_qtr` 都叫「财务费用」）+ 服务端会重排返回列序，导致按名/按位置都错位、只能绕道 raw API 手工回填
+
+**修复**
+- EDE `999999` 无数据提示只对取数端点（`cross-section`/`time-series`）套用，`indicator.search`（同为 no-999999 策略、仅关键词入参）回落通用提示；文案改为「日期匹配指标周期（财务/MRQ 用报告期末、日频估值用交易日）、`scopeList`、`parameterList` 中 required 参数」——修正此前「行情/估值用交易日」与 `finc_pb_mrq` 仅报告期末的矛盾
+
+**文档（随包 skill）**
+- `indicator.md`：`--key-by` 文档 + 两处 synopsis；`periodNum` 补「部分需配年报日期」、`startDate` 补「取值须匹配指标周期」
+- `examples.md` 例15：批量三截面示例改用 `--key-by code`
+
 ### v0.28.1 — 2026-07-23
 
 Agent Skill 文档取数路由对齐（对齐 gangtise-mcp 0.1.46）：多证券取一批**已实现**财务/估值指标优先走 EDE `indicator cross-section`/`time-series` 一次拉取，替代逐只 `fundamental` 循环。**本版仅改随包分发的 skill 文档（`gangtise-openapi/`），无 CLI 代码/命令/参数变更。**

package/dist/src/cli.js

@@ -632,15 +632,15 @@ indicator.command("search").requiredOption("--keyword <text>", "Search keyword,
     });
     await printData(unwrapIndicatorData(raw), format, options.output);
 }));
-indicator.command("cross-section").option("--indicator <code>", "Indicator code, e.g. qte_close (repeat for multiple)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH (repeat for multiple)", collectList, []).requiredOption("--date <date>", "Data date (yyyy-MM-dd)", dateArg("--date")).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) => {
+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)", dateArg("--date")).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, []).addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode, unique & order-stable for batch code→value mapping").choices(["name", "code"]).default("name")).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
     const raw = await client.call("indicator.cross-section", buildIndicatorCrossSectionBody(options));
-    await printData(flattenCrossSection(unwrapIndicatorData(raw)), format, options.output);
+    await printData(flattenCrossSection(unwrapIndicatorData(raw), options.keyBy), 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)", dateArg("--start-date")).requiredOption("--end-date <date>", "End date (yyyy-MM-dd)", dateArg("--end-date")).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) => {
+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)", dateArg("--start-date")).requiredOption("--end-date <date>", "End date (yyyy-MM-dd)", dateArg("--end-date")).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, []).addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode/securityCode, unique & order-stable for batch mapping").choices(["name", "code"]).default("name")).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
     const raw = await client.call("indicator.time-series", buildIndicatorTimeSeriesBody(options));
-    await printData(flattenTimeSeries(unwrapIndicatorData(raw)), format, options.output);
+    await printData(flattenTimeSeries(unwrapIndicatorData(raw), options.keyBy), 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) => {

package/dist/src/core/client.js

@@ -423,9 +423,13 @@ export class GangtiseClient {
         }).catch((error) => {
             // EDE uses 999999 for "no data for this query" (probed 2026-07-11) — the
             // generic "系统错误，请稍后重试" hint would send the user retrying a query
-            // that will never have data. Swap in a context-specific hint.
-            if (endpoint.retry === 'no-999999' && error instanceof ApiError && error.code === '999999') {
-                throw new ApiError(error.message, error.code, error.statusCode, error.details, error.retryAfterMs, 'EDE 的 999999 多为查询无数据（节假日 / 未来日期 / 未覆盖标的）——先检查查询条件，确认应有数据再重试。');
+            // that will never have data. Swap in a fetch-specific hint. Only the data
+            // endpoints take a date/security/params; indicator.search shares the
+            // no-999999 policy but has just a keyword, so it keeps the generic hint
+            // instead of nonsensical date/scope/param guidance.
+            const isIndicatorFetch = endpoint.key === 'indicator.cross-section' || endpoint.key === 'indicator.time-series';
+            if (isIndicatorFetch && error instanceof ApiError && error.code === '999999') {
+                throw new ApiError(error.message, error.code, error.statusCode, error.details, error.retryAfterMs, 'EDE 的 999999 多为查询无数据——先核对：日期匹配指标周期（财务/MRQ 用报告期末如 2025-12-31、日频估值用交易日）、标的在 scopeList 覆盖内、parameterList 中 required 参数已补；确认应有数据再重试。');
             }
             throw error;
         });

package/dist/src/core/indicatorMatrix.js

@@ -59,7 +59,11 @@ function buildHeaders(names, codes, count) {
 // 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) {
+// keyBy "code" makes each indicator column its `indicatorCode` (unique, and
+// independent of the display name or the server's column order) instead of the
+// human name — required for batch code→value mapping, where names collide
+// (many indicators share a display name) and the server reorders columns.
+export function flattenCrossSection(data, keyBy = "name") {
     if (!data || typeof data !== "object")
         return data;
     const d = data;
@@ -68,7 +72,7 @@ export function flattenCrossSection(data) {
     if (!Array.isArray(d.values) || !securityCode || !indicators)
         return data;
     const securityName = asStringArray(d.securityNameList);
-    const headers = buildHeaders(asStringArray(d.indicatorNameList), indicators, indicators.length);
+    const headers = buildHeaders(keyBy === "code" ? indicators : 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++) {
@@ -81,7 +85,7 @@ export function flattenCrossSection(data) {
 // 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) {
+export function flattenTimeSeries(data, keyBy = "name") {
     if (!data || typeof data !== "object")
         return data;
     const d = data;
@@ -92,8 +96,8 @@ export function flattenTimeSeries(data) {
         return data;
     const seriesAreIndicators = securityCode.length <= 1;
     const headers = seriesAreIndicators
-        ? buildHeaders(asStringArray(d.indicatorNameList), indicators, indicators.length)
-        : buildHeaders(asStringArray(d.securityNameList), securityCode, securityCode.length);
+        ? buildHeaders(keyBy === "code" ? indicators : asStringArray(d.indicatorNameList), indicators, indicators.length)
+        : buildHeaders(keyBy === "code" ? securityCode : 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/version.js

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

package/gangtise-openapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gangtise-openapi
-version: "0.28.1"
+version: "0.28.2"
 description: |-
   通过 gangtise CLI 直接调用 Gangtise OpenAPI，拉取投研原始数据、批量导出、下载文件、调用 AI 能力。
 
@@ -162,7 +162,7 @@ description: |-
 - "成分股" → 题材深度（分组/重点标记/纳入理由）走 `alternative concept-securities`；板块（行业/概念分类树，纯代码名单）走 `reference sector-constituents`
 - **证券基本面 / 指标先按任务形态路由，不是搜到 EDE 就一律走 EDE**：
   - 单证券先优先对应 `fundamental` 专用命令（财务、估值、盈利预测、股东、主营或完整三大报表，多数免费 / 低价）。其中 `valuation-analysis` / `earning-forecast` 实测仅支持 A 股；港 / 美股的估值历史分位、盈利预测、以及 PE/PB 等核心估值（EDE 也仅 A 股）当前 CLI 均无可用接口，如实说明不支持、勿用别的语义顶替
-  - 多证券批量取一组**已实现**财务 / 估值指标 → 优先 `indicator search` 后用 EDE 一次拉取，替代逐只循环；单日或同一报告期横向比较用 `cross-section`，区间走势用 `time-series`（后者不能多指标 × 多证券同时）
+  - 多证券批量取一组**已实现**财务 / 估值指标 → 优先 `indicator search` 后用 EDE 一次拉取，替代逐只循环；单日或同一报告期横向比较用 `cross-section`，区间走势用 `time-series`（后者不能多指标 × 多证券同时）。**批量按 code 回填加 `--key-by code`**（列头用 `indicatorCode`，防同名指标碰撞 + 服务端重排列序导致的错位）
   - 始终排除 EDE：A股盈利预测 / 一致预期（含预测 EPS）→ `fundamental earning-forecast`；A股估值历史分位 → `fundamental valuation-analysis`；开高低收 / 成交量等行情与 K 线 → `quote`；单证券完整报表 → 对应三大报表命令。EDE 搜到的基本 / 稀释 EPS 是已实现值，**不能冒充预测 EPS**；港 / 美股缺少上述专用能力时应如实说明不支持，不能用别的语义代替
   - EDE 取数前必须用 `search --format json` 同时核对：`indicatorName` + `description` 语义准确、`scopeList` 覆盖全部目标市场 / 证券类型、`parameterList` 必填参数与枚举可满足；`scopeList` 缺失 / `null` / 空或任一项不符，都视为无法证明覆盖并回退专用接口。专用接口也不覆盖目标市场时，说明当前不可用，不要硬调。`scopeList` 按指标各不相同，不能因 EDE 服务支持 A / 港 / 美股就假定某个指标三市场都覆盖
   - `indicator search` 免费，`cross-section` / `time-series` 按单元格计费；除多证券批量的效率收益外，仍优先免费 / 低价的 `quote` 或 `fundamental`

package/gangtise-openapi/references/commands/indicator.md

@@ -40,7 +40,7 @@ gangtise indicator search --keyword 营业收入 --limit 10 --format json   #
 ```bash
 gangtise indicator cross-section --indicator <code> [--indicator <code2>] \
   --security <code> [--security <code2>] --date <yyyy-MM-dd> \
-  [--currency <c>] [--scale <s>] [--indicator-param <spec>]
+  [--currency <c>] [--scale <s>] [--indicator-param <spec>] [--key-by name|code]
 ```
 
 - `--indicator`（**至少 1 个**）：指标编码，来自 `search`，可重复传多个
@@ -50,6 +50,7 @@ gangtise indicator cross-section --indicator <code> [--indicator <code2>] \
 - `--scale`：量纲 `0`(个,默认)/`3`(千)/`4`(万)/`6`(百万)/`8`(亿)/`9`(十亿)
 - **支持多指标 × 多证券**（单日横截面）
 - **输出（宽表）**：每行一只证券，列为 `date / security / name / <各指标名>…`
+- **`--key-by name|code`**（默认 `name`）：指标列头用显示名还是 `indicatorCode`。**批量按 code 回填必用 `--key-by code`**——指标名会碰撞（多个指标同显示名，如 `cf_finc_exp`/`_qtr` 都叫「财务费用」）、服务端还会重排返回列序，唯有 code 唯一且与顺序无关（行轴 `security` 本就是 code，`code` 模式整表可按 code 寻址，免去 raw API 手工回填）
 
 ```bash
 # 多证券 × 同一报告期的已实现财务指标
@@ -66,7 +67,7 @@ gangtise indicator cross-section \
 ```bash
 gangtise indicator time-series --indicator <code> [--indicator <code2>] \
   --security <code> [--security <code2>] --start-date <date> --end-date <date> \
-  [--calendar-type <ND|TD|WD>] [--currency <c>] [--scale <s>] [--indicator-param <spec>]
+  [--calendar-type <ND|TD|WD>] [--currency <c>] [--scale <s>] [--indicator-param <spec>] [--key-by name|code]
 ```
 
 - `--indicator` / `--security`：同上，但**只允许「多指标 × 单证券」或「单指标 × 多证券」**，不能两边都多个（要多 × 多用 `cross-section`，否则报 `410001`）
@@ -74,6 +75,7 @@ gangtise indicator time-series --indicator <code> [--indicator <code2>] \
 - `--calendar-type`：日期类型 `ND`(自然日)/`TD`(交易日,默认)/`WD`(工作日)
 - `--currency` / `--scale`：同 `cross-section`
 - **输出（宽表）**：每行一个日期，列为 `date / <各序列名>…`；序列在「单证券」时是各**指标**，在「多证券」时是各**证券**
+- **`--key-by name|code`**（默认 `name`）：同 `cross-section`；`code` 模式下单证券列=各 `indicatorCode`、多证券列=各 `securityCode`，批量按 code 回填用它
 
 ```bash
 # 单个已实现估值指标 × 多证券：列 = 证券
@@ -116,8 +118,8 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 
 | 参数 | 适用指标 | 示例 |
 | :--- | :--- | :--- |
-| `periodNum` | N 期统计（N 期均值/最值，如 `finc_roe_avg_avg` 平均ROE N期均值） | `--indicator-param "finc_roe_avg_avg:periodNum=4"` |
-| `startDate` | 区间/周期类，整数 `YYYYMMDD`（含全部 `qte` 周期变体，如 `qte_amp_mo` 月振幅、换手率） | `--indicator-param "qte_amp_mo:startDate=20260401"` |
+| `periodNum` | N 期统计（N 期均值/最值，如 `finc_roe_avg_avg` 平均ROE N期均值） | `--indicator-param "finc_roe_avg_avg:periodNum=4"`；部分还需配**年报日期**才出数（实测 `finc_roe_avg_avg`@`2026-03-31` 空、@`2025-12-31` 有） |
+| `startDate` | 区间/周期类，整数 `YYYYMMDD`（含全部 `qte` 周期变体，如 `qte_amp_mo` 月振幅、换手率） | `--indicator-param "qte_amp_mo:startDate=20260401"`；取值须匹配该指标**周期**（月/季/周/年窗口不同，`20260101` 未必命中，空则按变体周期调 `startDate`） |
 | `fiscalYear` | 年度/报告期类（如 `div_cash_yr` 年度现金分红） | `--indicator-param "div_cash_yr:fiscalYear=2025"` |
 
 > `paramValue` 一律按**字符串**约定传（`periodNum=4` 内部即 `"4"`，CLI 已处理）。

package/gangtise-openapi/references/examples.md

@@ -241,21 +241,21 @@
    - scopeList：覆盖全部三只 A 股；缺失/null/空也视为不通过
    - parameterList：补 required 参数并核对枚举
    任一不符 → 回退相应专用接口。
-3. 三类指标日期语义不同 → 拆三次截面（省略 reportType 即取合并口径；⚠️ 该枚举 label 与实测不符、value=2/4 会 999999，需指定报表口径改用 fundamental income-statement --report-type）：
+3. 三类指标日期语义不同 → 拆三次截面，均加 `--key-by code`（列头用 indicatorCode，跨三张表按 code 稳定合并、免受同名/服务端重排干扰；省略 reportType 即取合并口径，⚠️ 该枚举 label 与实测不符、value=2/4 会 999999，需指定口径改用 fundamental income-statement --report-type）：
    a) 财务（营收/EPS）用报告期末 2025-12-31：
      gangtise indicator cross-section \
        --indicator is_op_rev --indicator is_eps_bas \
        --security 600519.SH --security 000858.SZ --security 300750.SZ \
-       --date 2025-12-31 --format json
+       --date 2025-12-31 --key-by code --format json
    b) PE 日频，用最新交易日 2026-07-22（此日 PB 为 null，勿并入）：
      gangtise indicator cross-section --indicator finc_pe_ttm \
        --security 600519.SH --security 000858.SZ --security 300750.SZ \
-       --date 2026-07-22 --format json
+       --date 2026-07-22 --key-by code --format json
    c) PB(MRQ) 只在报告期末打值，用最近报告期末 2026-03-31：
      gangtise indicator cross-section --indicator finc_pb_mrq \
        --security 600519.SH --security 000858.SZ --security 300750.SZ \
-       --date 2026-03-31 --format json
-4. 按 security 合并三张宽表（各取所需日期的值）；不要把不同日期语义的指标塞进同一个 --date。
+       --date 2026-03-31 --key-by code --format json
+4. 按 security 合并三张宽表（列头即 indicatorCode，各取所需日期的值）；不要把不同日期语义的指标塞进同一个 --date。
 5. 计费：search 免费；三次取数各按请求单元格数量计费，每次不足 100 单元格按 100 计。
 6. 无数据：单元格缺值返回 null 且不丢证券行；整个查询无数据仍可能报 999999，先核对日期语义、scopeList、公司类型和指标参数。
 ```

package/package.json

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