gangtise-openapi-cli 0.35.0 → 0.37.0

package/gangtise-openapi/references/commands/reference-and-lookup.md

@@ -108,7 +108,7 @@ gangtise reference constant-category [--format json]
 >
 > 先记住三套码的归属，**别把行业码算到 `gangtiseIndustry` 头上**：`citicIndustry` = 30 条行业码 `1008001xx`；`swIndustry` = 31 条行业码 `104xx0000`；`gangtiseIndustry` = **只有 6 条方向码** `122000xxx`（宏观 `122000001` / 策略 `122000002` / 固收 `122000003` / 金工 `122000004` / 海外 `122000005` / 其他 `122000007`），里面**没有任何行业**，去它那里找「食品饮料」永远找不到。
 >
-> - **`--industry`（industryList）→ 用 `citicIndustry`（`1008001xx`）**：opinion / research / foreign-report / official-account 正确过滤。`swIndustry`（`104xx0000`）在这 4 个上**也生效，但不是等效**——两套码的行业成分不同，4 个里有 2 个结果集对不上（research / foreign-report 完全一致；**opinion 与 official-account 传两套码取回的条数相差约 2%–5%**）。所以**统一用中信码**，同一批查询里别把两套码混着传。方向码 `122000xxx` 在 `--industry` 上一律返 0。⚠️ 一个例外：`insight foreign-opinion` / `independent-opinion` 只要传 `--industry` 就拿不到数据（不报错，且 **payload 是字面 `null`、不是空 list**，详见 `insight.md`），只能不带该过滤取回后本地筛。`vault wechat-message-list` 的 `--industry` **只认中信码**，申万码会被静默忽略并返回全量（详见 `vault.md`）。
+> - **`--industry`（industryList）→ 用 `citicIndustry`（`1008001xx`）**：opinion / research / foreign-report / official-account 正确过滤。`swIndustry`（`104xx0000`）在这 4 个上**也生效，但不是等效**——两套码的行业成分不同，4 个里有 2 个结果集对不上（research / foreign-report 完全一致；**opinion 与 official-account 传两套码取回的条数相差约 2%–5%**）。所以**统一用中信码**，同一批查询里别把两套码混着传。方向码 `122000xxx` 在 `--industry` 上一律返 0。⚠️ 一个例外：`insight foreign-opinion` / `independent-opinion` 的 `--industry` **只认申万码 `104xx0000`**，传中信码报 `100005 枚举值非法`（详见 `insight.md`）。`vault wechat-message-list` 反过来**只认中信码**，传申万码报 `100005`（详见 `vault.md`）。
 > - **`--research-area`（researchAreaList）→ 用 `citicIndustry` 行业码 `1008001xx`，方向再叠 `gangtiseIndustry` 的 `122000xxx`**。⚠️ **申万码 `104xx0000` 只有 `summary` / `pamirs-summary` 认**，其余端点返 0（与传乱码表现一致，不报错）。逐端点实测（同一行业分别传三套码，✅ = 正常过滤，❌ = 返 0）：
 >
 > | 端点 | 中信 `1008001xx` | 申万 `104xx0000` | 方向 `122000xxx` |
@@ -224,9 +224,9 @@ gangtise lookup meeting-org list          # 会议/牵头机构全量（--instit
 | 银行 / 银行股 | 银行 | `104480000` | `821047.SWI` |
 | 汽车 / 新车 | 汽车 | `104280000` | `821036.SWI` |
 
-> ¹ 第 3 列是**申万码**（`104xx0000`），仅在 opinion / research / foreign-report / official-account 上可作 `--industry` 使用，且**与中信码不等效**（opinion / official-account 两套码结果集不同，见上方 ⭐ 权威口径）；用于 `--research-area` 时只有 summary / pamirs-summary 认，其余端点返 0。`vault wechat-message-list` 的 `--industry` **只认中信码，申万码被静默忽略**。通用/推荐的**中信码**（`1008001xx`）见 `references/lookup-ids.md` 中信表或 `constant-list --category citicIndustry`。
+> ¹ 第 3 列是**申万码**（`104xx0000`），仅在 opinion / research / foreign-report / official-account 上可作 `--industry` 使用，且**与中信码不等效**（opinion / official-account 两套码结果集不同，见上方 ⭐ 权威口径）；用于 `--research-area` 时只有 summary / pamirs-summary 认，其余端点返 0。`vault wechat-message-list` 的 `--industry` **只认中信码，传申万码报 `100005`**。通用/推荐的**中信码**（`1008001xx`）见 `references/lookup-ids.md` 中信表或 `constant-list --category citicIndustry`。
 
-> **参数名选择**：`--industry`（industryList，用 `citicIndustry` 码 `1008001xx`）用于 opinion / research / foreign-report / official-account / `vault wechat-message-list`（后者只认中信码）；`foreign-opinion` / `independent-opinion` 也有这个参数，但**当前不生效**，见上方 ⭐ 权威口径；`--research-area`（researchAreaList，行业用 `citicIndustry` 码 `1008001xx`、方向用 `gangtiseIndustry` 码 `122000xxx`）用于 opinion / summary / pamirs-summary / roadshow / site-visit / forum / my-conference；`--gts-code` 仅用于 `ai security-clue`（需申万格式 `821xxx.SWI`，不是数字 ID）。注意 strategy（线下策略会）无 `--research-area`，只按 `--institution` / `--location` 筛。
+> **参数名选择**：`--industry`（industryList，用 `citicIndustry` 码 `1008001xx`）用于 opinion / research / foreign-report / official-account / `vault wechat-message-list`（后者只认中信码）；`foreign-opinion` / `independent-opinion` 的这个参数**只认申万码 `104xx0000`**，见上方 ⭐ 权威口径；`--research-area`（researchAreaList，行业用 `citicIndustry` 码 `1008001xx`、方向用 `gangtiseIndustry` 码 `122000xxx`）用于 opinion / summary / pamirs-summary / roadshow / site-visit / forum / my-conference；`--gts-code` 仅用于 `ai security-clue`（需申万格式 `821xxx.SWI`，不是数字 ID）。注意 strategy（线下策略会）无 `--research-area`，只按 `--institution` / `--location` 筛。
 
 > **"消费"歧义**：用户说"消费/大消费"覆盖多个子行业（食品饮料 `104340000` / 商贸零售 `104450000` / 社会服务 `104460000` / 家电 `104330000` / 纺织服饰 `104350000` / 美容护理 `104770000`），需向用户确认具体方向，或用 `--keyword 消费` 做宽泛搜索。
 

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

@@ -49,7 +49,7 @@ gangtise vault wechat-message-list [--keyword <text>] [--security <code>] [--wec
 
 - 数据权限：仅用户已绑定并激活群消息助理、且助理已入群的群消息
 - `--security`：按证券代码过滤（如 `000001.SZ`），可重复
-- `--industry`：**只认中信码**（`1008001xx`，见 `reference constant-list --category citicIndustry`）。⚠️ 申万码（`104xx0000`）和任何不认识的值都会被**静默忽略、返回未过滤的全量**，不报错——所以别混用码表，拿到的条数与不加过滤一样时先核对码系。返回行里不含行业标签字段，过滤在服务端完成
+- `--industry`：**只认中信码**（`1008001xx`，见 `reference constant-list --category citicIndustry`）。⚠️ 申万码（`104xx0000`）与任何不认识的值都报 `100005 枚举值非法`——**换中信码即可**。返回行里不含行业标签字段，过滤在服务端完成
 - 🔴 **`--industry` 是收窄工具，不是全量召回**：行业标签由服务端标注，**同一条消息可能挂多个行业，也可能一个都没挂**。实测同一个关键词加上「本行业」过滤后，命中数掉到三到四成——**少掉的既有没打标签的，也有被标到相邻行业去的**（如半导体相关的消息在计算机 / 机械 / 通信下同样查得到）。所以「按行业筛出 N 条」不能读成「该行业只有 N 条」；要尽量全，用 `--keyword` 取回后本地判断，或把相邻行业码一起查再去重
 - `--wechat-group-id`：先用 `vault wechat-chatroom-list` 查；可重复
 - `--category`：`text` | `image` | `documents` | `url`（可重复）

package/gangtise-openapi/references/examples.md

@@ -105,7 +105,7 @@
 3. Pre-flight："那个"暗示特定文件 → 🔴 展示结果让用户选择
 4. gangtise vault drive-list --keyword AI --file-type 1 --format json
 5. 展示前 10 条让用户挑 → gangtise vault drive-download --file-id <id>
-   （省略 --output 自动用真实标题做文件名）
+   （第 4 步的 drive-list 已把标题写进 title-cache，省略 --output 即自动用真实标题做文件名）
 ```
 
 ## 例 8：跨资源类型语义搜索
@@ -257,7 +257,7 @@
        --date 2026-07-31 --key-by code --format json
 4. 按 security 合并两张宽表（列头即 indicatorCode，各取所需日期的值）；不要把不同日期语义的指标塞进同一个 --date。
 5. 计费：search 免费；两次取数各按请求单元格数量计费，每次不足 100 单元格按 100 计。
-6. 无数据（无覆盖 / 非交易日 / 未来日期）一律保留行列并给占位单元格，退出码 0——但占位值多数是 null、个别指标（如 is_dnrpnp）是 0，0 会穿过比较与聚合，别当真值（见 commands/indicator.md）。代码写错或参数名写错则直接报 100003 并点名是哪个（指标码拼错、证券后缀错如美股写成 .US、参数名写错、同 code 重复配置），按报错改即可。
+6. 无数据（无覆盖 / 非交易日 / 未来日期）一律保留行列并给占位单元格，退出码 0——占位值统一是 null（见 commands/indicator.md）；⚠️ 报告期类指标（is_*）的时序只有报告期末那几行是真值，别对整列手工求均值。代码写错或参数名写错则直接报 100003 并点名是哪个（指标码拼错、证券后缀错如美股写成 .US、参数名写错、同 code 重复配置），按报错改即可。
 ```
 
 ## 例 15b：帕米尔专家纪要（新库，筛选项与踩坑都和 summary 不同）

package/gangtise-openapi/references/fields.md

@@ -6,6 +6,23 @@
 
 ## Quote 行情
 
+> ⚠️ **`volume` 的单位是「股」**。四个端点同一口径——`day-kline` / `realtime` / `minute-kline` / `index-day-kline`，A股 / 港股 / 美股一致，历史数据同口径。
+>
+> 🔴 **存量脚本里若对 `volume` 做过 `× 100` 还原股数，要撤掉**——现在会差 100 倍，而数字看着仍然「像个成交量」，不会报错。
+>
+> **一眼自检（仅适用于个股）**：`amount ÷ volume` 得到的均价应落在当日 `[low, high]` 区间内。
+>
+> ⚠️ **这个自检有两类必然失败，不要据此判定数据有问题**：
+>
+> 1. **指数不适用**。指数的 OHLC 是**点位**，而 `amount` / `volume` 是成分股合计，两者量纲不同——比值算出来是成分股均价（上证 / 深成 ≈ 20 元），永远落不进四千点的区间，**数据本身是对的**。
+> 2. 🔴 **美股的 `quote realtime`**。它的 `amount` **恒为 `0`**（见下方 realtime 字段表），自检值必然算出 0。**要美股的实时成交额，只能用别的口径**（收盘后用 `day-kline`，或 EDE `qte_amt`）。
+>
+> 🔴 **分钟线加总对日线时，先看收盘那根**：正常情况下 **Σ分钟 `volume` = 日线 `volume`、Σ分钟 `amount` = 日线 `amount`**，两者都**精确相等**（正常交易日 241 根，逐根加总与日线一致）。
+>
+> ⚠️ **但 `15:00` 那根（收盘集合竞价）会随机返 `volume=0, amount=0`**，此时 Σ分钟比日线少约 1.2%。**这是逐只、逐日、且同一只票重复取也未必一致的**——同一个交易日里，有的标的每次都对得上（Σ分钟 `amount` 与日线只差浮点级），有的则时有时无。**所以不能拿一只票的一次结果推断当天整批数据**，也与「是不是最新交易日」无关。
+>
+> **最省事的对账法：直接拿 `quote day-kline` 的 `amount` 比**——差额若恰好等于某一根，就是那一根在翻。（`14:58` / `14:59` 恒为 0 是**正常的**：14:57 后进入收盘集合竞价，只申报不撮合，成交在 15:00 一次性发生。）
+
 ### 日K线 `quote day-kline`（A股 / 港股 / 美股 / 各类指数；旧的 `day-kline-hk` / `day-kline-us` 已下线，字段相同）
 
 各市场字段相同（货币单位随市场：A股=元、港股=港元、美股=美元；**指数为点位、无货币单位，且 `adjustFactor` 恒为 `null`**）：
@@ -29,8 +46,12 @@
 | `open` | 开盘价 | `high` | 最高价 |
 | `low` | 最低价 | `change` | 涨跌额 |
 | `pctChange` | 涨跌幅(%) | `volume` | 成交量(股，当日累计) |
-| `amount` | 成交总额(当日累计) | `amplitude` | 振幅(%) |
-| `turnoverRate` | 换手率(%) | `volumeRatio` | 量比 |
+| `amount` | 成交总额(当日累计)🔴 **美股恒 0** | `amplitude` | 振幅(%) |
+| `turnoverRate` | 换手率(%)🔴 **美股恒 0** | `volumeRatio` | 量比 🔴 **美股恒 0** |
+
+> 🔴 **美股的 `amount` / `turnoverRate` / `volumeRatio` 这三个字段恒为 `0`，A股 / 港股正常。** 全市场拉取核对过（2026-08-24）：美股有成交的记录里这三个字段全部为 `0`，同一时刻的港股与 A 股则没有一行是 `0`。
+>
+> ⚠️ **`0` 不是「没有成交」**——同一行的 `volume` 是有值的（如 `DTSS.O` `volume=174` 而 `amount=0`）。**取美股实时成交额会静默拿到 `0`、退出码 0、无告警**，直接写进结论就是错数。要美股成交额：收盘后用 `quote day-kline`，或用 EDE `indicator cross-section --indicator qte_amt`。
 
 **以上 16 个就是全部**（实测 2026-07-24）：**无 `close`**（用 `latestPrice`）、**无市值**（走 `indicator cross-section --indicator qte_mkt_cptl`）。realtime 传了不存在的字段名不会被忽略——上游只丢值、字段名照回显，CLI 检测到长度不匹配会直接报错（v0.28.3 起）。
 
@@ -43,7 +64,7 @@
 | `high` | 最高价 | `low` | 最低价 |
 | `close` | 收盘价 | `preClose` | 昨收价 |
 | `change` | 涨跌额 | `pctChange` | 涨跌幅(%) |
-| `volume` | 成交量(手) | `amount` | 成交总额(元) |
+| `volume` | 成交量(股) | `amount` | 成交总额(元) |
 
 ---
 

package/gangtise-openapi/references/lookup-ids.md

@@ -6,7 +6,7 @@
 
 ## 中信行业分类（--industry 参数）
 
-完整列表用 `reference constant-list --category citicIndustry`（30 条）。**`--industry` 全命令通用首选用这套（`1008001xx`）**——opinion / research / foreign-report / official-account 都正确过滤，`vault wechat-message-list` 也认这一套（⚠️ 两个例外：`insight foreign-opinion` / `independent-opinion` 传了 `--industry` 拿不到数据、且 **payload 是字面 `null` 不是空 list**）；这套 ID 同时也是 `--research-area` **行业维度唯一全端点通吃的一套**（见下方研究方向）。
+完整列表用 `reference constant-list --category citicIndustry`（30 条）。**`--industry` 全命令通用首选用这套（`1008001xx`）**——opinion / research / foreign-report / official-account 都正确过滤，`vault wechat-message-list` 也认这一套（⚠️ 两个例外：`insight foreign-opinion` / `independent-opinion` 的 `--industry` **只认申万码 `104xx0000`，传中信码报 `100005`**）；这套 ID 同时也是 `--research-area` **行业维度唯一全端点通吃的一套**（见下方研究方向）。
 
 | ID | 行业 | ID | 行业 |
 |----|------|----|------|
@@ -30,7 +30,7 @@
 
 ## 申万行业（--industry 参数）
 
-完整列表用 `reference constant-list --category swIndustry`（31 条）。⚠️ 申万码（`104xx0000`）只在**部分** insight list 上可作 `--industry` 使用，且**与中信码不等效**——两套码行业成分不同，实测 opinion 与 official-account 上取回的结果集就对不上（同一行业相差约 2%–5%），别混用；用于 `--research-area` 时**只有 `summary` / `pamirs-summary` 认，其余端点返 0**（不报错，与传乱码表现一致）。`vault wechat-message-list` 的 `--industry` **只认中信码**，传申万码会被静默忽略并返回全量——哪套码用于哪些命令的**权威口径见 `references/commands/reference-and-lookup.md`「行业 / 研究方向过滤——选哪套 category」**（含逐端点实测矩阵），勿在此重复枚举。拿不准就统一用上方中信码。
+完整列表用 `reference constant-list --category swIndustry`（31 条）。⚠️ 申万码（`104xx0000`）只在**部分** insight list 上可作 `--industry` 使用，且**与中信码不等效**——两套码行业成分不同，实测 opinion 与 official-account 上取回的结果集就对不上（同一行业相差约 2%–5%），别混用；用于 `--research-area` 时**只有 `summary` / `pamirs-summary` 认，其余端点返 0**（不报错，与传乱码表现一致）。`vault wechat-message-list` 的 `--industry` **只认中信码**，传申万码报 `100005`——哪套码用于哪些命令的**权威口径见 `references/commands/reference-and-lookup.md`「行业 / 研究方向过滤——选哪套 category」**（含逐端点实测矩阵），勿在此重复枚举。拿不准就统一用上方中信码。
 
 | ID | 行业 | ID | 行业 | ID | 行业 |
 |----|------|----|------|----|------|

package/gangtise-openapi/references/response-schema.md

@@ -4,7 +4,7 @@ CLI 自动处理 envelope：`{code, msg, data}` 信封会按 `code === "000000"`
 
 > 例外：`indicator`（EDE）四个接口（`search` / `cross-section` / `time-series` / `screener`）成功时**双层信封**（`data` 里再裹一层 `{code, status, data}`）。内层字段名 2026-08-01 起为 `securityCodeList` / `securityNameList` / `indicatorList[{code,name,dataType}]`（screener 另带 `field`），`values` 是 2D 矩阵：**截面与 screener 为 `[证券][指标]`**（该版转置过，此前是 `[指标][证券]`）、时序仍为 `[序列][日期]`。
 >
-> **缺数据 vs 代码写错**（2026-08-15 实测）：无数据 / 无覆盖一律保留行列并给占位单元格——**多数指标是 `null`，个别（如 `is_dnrpnp`）是 `0`，`0` 会穿过比较与聚合，详见 `commands/indicator.md`**。**代码写错则直接报 `100003` 并点名**（指标 code 拼错 →「指标 xxx 不存在」；证券 code 后缀错 →「xxx 不是有效证券或者板块ID」，美股是 `.O`/`.N` 不是 `.US`），**无论同批有没有正确的 code 都会报**。CLI 的 `indicator` 子命令已二次解包、拍平成宽表；`partial` + `omittedIndicators`/`omittedSecurities` + 退出码 3 的差集检测仍保留作兜底，但当前服务端行为下基本收不到样本。**`screener` 例外**：把缺列的变量当作无法求值，按表达式的**布尔结构**判断是否还有分支能成立（`A && B` 要两边、`A || B` 只要一边）。一条都不剩 → **退出码 1 且不输出**（那些行以「通过了该条件」的名义呈现，而条件根本无法证明被执行过）；仍有分支可求值、或缺的只是输出用的辅助变量 → `partial` + 退出码 3。直接 `raw call indicator.*` 只会剥外层，内层需自行处理。
+> **缺数据 vs 代码写错**（2026-08-15 实测）：无数据 / 无覆盖一律保留行列并给占位单元格——**占位值统一为 `null`**；⚠️ 报告期类指标（`is_*`）的时序只有报告期末那几行是真值，其余全是 `null`，详见 `commands/indicator.md`。**代码写错则直接报 `100003` 并点名**（指标 code 拼错 →「指标 xxx 不存在」；证券 code 后缀错 →「xxx 不是有效证券或者板块ID」，美股是 `.O`/`.N` 不是 `.US`），**无论同批有没有正确的 code 都会报**。CLI 的 `indicator` 子命令已二次解包、拍平成宽表；`partial` + `omittedIndicators`/`omittedSecurities` + 退出码 3 的差集检测仍保留作兜底，但当前服务端行为下基本收不到样本。**`screener` 例外**：把缺列的变量当作无法求值，按表达式的**布尔结构**判断是否还有分支能成立（`A && B` 要两边、`A || B` 只要一边）。一条都不剩 → **退出码 1 且不输出**（那些行以「通过了该条件」的名义呈现，而条件根本无法证明被执行过）；仍有分支可求值、或缺的只是输出用的辅助变量 → `partial` + 退出码 3。直接 `raw call indicator.*` 只会剥外层，内层需自行处理。
 
 ## 通用模式（5 类）
 

package/package.json

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