gangtise-openapi-cli 0.27.0 → 0.28.1

package/gangtise-openapi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gangtise-openapi
-version: "0.27.0"
+version: "0.28.1"
 description: |-
   通过 gangtise CLI 直接调用 Gangtise OpenAPI，拉取投研原始数据、批量导出、下载文件、调用 AI 能力。
 
@@ -33,7 +33,7 @@ description: |-
    - 翻页 → 首页拿 total 后剩余页并发拉取
    - K 线 `--security all` 跨日期 → 自动按日切片并合并
    - 5xx / `429` / 网络错误 / `999999` → 自动指数退避重试（🔴 贵档端点例外：仅连接失败 / 429 / token 自愈重试，5xx/超时不重放防重复扣分，v0.26.0；`indicator` 端点对 `999999` 不重试——该码=查询无数据，v0.27.0）
-   - Token 失效（`0000001008` 服务端失效 / `8000014` / `8000015` AK/SK 错误）→ 自动重新登录并重试一次
+   - Token 失效（`0000001008` / `999002`，含已废弃的 `8000014`/`8000015`）→ 自动重新登录并重试一次；凭证错 `999011` → **不重试**（AK/SK 不对不会自己好），查环境变量
 8. **参数命名差异**：Insight/Quote/Vault 用 `--security`，Fundamental/AI 用 `--security-code`（例外：`ai stock-summary` 用 `--security`，`ai security-clue` 用 `--gts-code`）。
 9. **调试**：`--verbose` 或 `GANGTISE_VERBOSE=1` 打印每个请求的耗时/字节数到 stderr。
 
@@ -69,7 +69,7 @@ description: |-
 - **免费**：所有 `quote` 行情、`fundamental` 报表/主营/估值/股东（**盈利预测除外**）、`reference`/`constant` 查询（含 `official-account-search`）、`alternative edb-search`、`vault`（record/wechat/股票池/drive/AI云盘）、`insight report-image list`
 - **0.1/条 list**：research / foreign-report / official-account / announcement(A/港/美) / summary / qa 的 list、`vault my-conference-list`；`insight report-image download` 0.1/张
 - **按条（观点/含详情类 list）**：independent-opinion list 与 `ai security-clue` 5；roadshow/site-visit/strategy/forum list 20；opinion / foreign-opinion list 30；`fundamental earning-forecast` 0.5；`ai stock-summary` 3（无看点的证券不返回也不扣）；`alternative edb-data` 30
-- **各 download（/篇）**：announcement / official-account 10；research / announcement-hk / announcement-us 20；independent-opinion 30；summary / foreign-report / my-conference 50
+- **各 download（/篇）**：announcement / official-account / research 10；announcement-hk / announcement-us 20；independent-opinion 30；summary / foreign-report / my-conference 50
 - 🔴 **按次贵**：`ai knowledge-batch` 10、`management-discuss-*` 10；AI Agent（`one-pager` / `investment-logic` / `peer-comparison` / `research-outline` / `earnings-review` / `viewpoint-debate` / `theme-tracking`）**50/次**；`ai hot-topic` 50/篇
 - 🔴 **极贵**：`alternative concept-info` / `concept-securities` **500/次**
 - ⚠️ **同参数重复调用不免费**：按次计费无缓存命中豁免（2026-07-11 实测 `one-pager` 重复调用每次扣分，即使秒回缓存内容）——生成类结果拿到后自行留存复用，别为"刷新"重调；CLI 已对上述 🔴 贵档端点关闭 5xx/超时自动重放（v0.26.0），50/篇 的 `summary` / `foreign-report` / `my-conference` download 同样不重放（v0.27.0），正是为防重复扣分
@@ -110,7 +110,7 @@ description: |-
 | 投资者问答 / 互动平台 / 电话会议 / 调研纪要 QA | `insight qa list`（按证券，`--security-code` 必填；`--source`/`--question-category`/`--answer-important` 精筛） |
 | 研报图表 / 研报图片搜索 | `insight report-image list`（`--keyword`；下载原图 `insight report-image download --chunk-id`） |
 | 跨类型语义搜索（研报+纪要+...） | `ai knowledge-batch`（多个 `--resource-type`） |
-| 知识库原文下载（搜到后取全文） | `ai knowledge-resource-download`（前置：`knowledge-batch` 拿 `resourceType`+`sourceId`；`433007`=组合不匹配） |
+| 知识库原文下载（搜到后取全文） | `ai knowledge-resource-download`（前置：`knowledge-batch` 拿 `resourceType`+`sourceId`；`250001`/旧 `433007`=组合不匹配） |
 | 一页通 / 投资逻辑 / 同业对比 / 调研提纲 | `ai one-pager / investment-logic / peer-comparison / research-outline` |
 | 个股看点 / 投研总结 / 公司速览 | `ai stock-summary`（`--security` 代码或 `aShares`/`hkStocks` 全市场；仅 A 股/港股） |
 | 业绩点评（异步） | `ai earnings-review` |
@@ -127,12 +127,12 @@ description: |-
 | 分钟 K（A 股） | `quote minute-kline` |
 | 实时行情（A / 港 / 美） | `quote realtime` |
 | A股资金流向（主力/大单净流入，日频） | `quote fund-flow`（`--security` 或 `aShares` 全市场〔须带 `--start-date`/`--end-date`，按日自动分片〕；免费） |
-| A股利润表 / 资产负债 / 现金流（累计 / 单季） | `fundamental income-statement[-quarterly] / balance-sheet / cash-flow[-quarterly]` |
-| 港股利润表 / 资产负债 / 现金流 | `fundamental income-statement-hk / balance-sheet-hk / cash-flow-hk` |
-| 美股利润表 / 资产负债 / 现金流 | `fundamental income-statement-us / balance-sheet-us / cash-flow-us` |
-| 主营业务 / 收入结构 | `fundamental main-business` |
-| 估值 / PE / PB | `fundamental valuation-analysis` |
-| 盈利预测 / 一致预期 | `fundamental earning-forecast` |
+| 单证券 A股完整利润表 / 资产负债 / 现金流（累计 / 单季） | `fundamental income-statement[-quarterly] / balance-sheet / cash-flow[-quarterly]` |
+| 单证券 港股完整利润表 / 资产负债 / 现金流 | `fundamental income-statement-hk / balance-sheet-hk / cash-flow-hk` |
+| 单证券 美股完整利润表 / 资产负债 / 现金流 | `fundamental income-statement-us / balance-sheet-us / cash-flow-us` |
+| 单证券主营业务 / 收入结构 | `fundamental main-business` |
+| A股单证券估值序列 / PE / PB / 历史分位 | `fundamental valuation-analysis` |
+| A股盈利预测 / 一致预期 | `fundamental earning-forecast` |
 | 前十大股东 | `fundamental top-holders` |
 | 云盘文件 | `vault drive-list / drive-download` |
 | 录音速记 | `vault record-list / record-download` |
@@ -143,9 +143,9 @@ description: |-
 | 行业指标时序数据（EDB） | `alternative edb-data` |
 | 题材画像 / 投资逻辑 / 行业空间 / 竞争格局 / 催化事件 | `alternative concept-info`（前置：`reference concept-search` 拿 `concept-id`） |
 | 题材成分股 / 题材深度 F8 / 题材龙头 | `alternative concept-securities`（前置：`reference concept-search` 拿 `concept-id`） |
-| 指标搜索 / 找指标编码（收盘价/成交量/总市值/财务指标的 code） | `indicator search` |
-| 指标截面数据（多指标 × 多证券，单日快照） | `indicator cross-section`（前置：`indicator search` 拿 indicatorCode） |
-| 指标时间序列（多指标 × 单证券 或 单指标 × 多证券，按区间） | `indicator time-series`（前置：`indicator search` 拿 indicatorCode） |
+| 多证券已实现财务 / 估值指标搜索（含总市值） | `indicator search` |
+| 多证券已实现指标截面（多指标 × 多证券，同一查询日期） | `indicator cross-section`（前置：`indicator search --format json` 通过三项校验） |
+| 多证券已实现指标时序（单指标 × 多证券，按区间） | `indicator time-series`（前置：`indicator search --format json` 通过三项校验） |
 | 证券代码 / gtsCode 搜索 | `reference securities-search` |
 | 首席 ID / 分析师 ID 搜索 | `reference chiefs-search`（按姓名/机构/团队，用于 `insight opinion --chief`） |
 | 机构 ID 搜索（内资券商/外资/牵头/观点机构） | `reference institution-search`（按机构名，用于 `--institution` / `--broker`；免费） |
@@ -160,11 +160,15 @@ description: |-
 - "搜索 X" → 数据维度精确（按行业/券商）走对应 `insight ... list`；跨类型语义搜索走 `ai knowledge-batch`
 - 港股代码用在 `insight foreign-opinion --security` 还是 `quote day-kline-hk --security`？前者要"境外"格式（`UBER.N`），后者要 `.HK`
 - "成分股" → 题材深度（分组/重点标记/纳入理由）走 `alternative concept-securities`；板块（行业/概念分类树，纯代码名单）走 `reference sector-constituents`
-- "指标" → 证券级指标（总市值/估值分位/财务指标等，需 `--security` 证券代码）走 `indicator`（EDE）；**但基础行情（收盘价/开高低收/成交量/成交额/涨跌幅）优先 `quote`**（免费、可 `--security all` 自动分片；`indicator` 按单元格计费且需先 search 拿 code）；行业/宏观指标（空调销量、社融等，无证券维度）走 `alternative edb-*`（EDB），三套接口不同
-- `indicator` 取数二选一：单日多标的横向对比 → `cross-section`；时间区间纵向走势 → `time-series`（且 `time-series` 不能多指标 × 多证券同时，截面才可以）
-- `indicator` 取数前**先 `search --format json` 看 `parameterList`**：很多指标有必填参数（`periodNum`/`startDate`/`fiscalYear`），不补会报错（服务端现直接指明「必填参数 X 不能为空」）；**无数据已统一返回 `null`**（截面不再抛 `999999`、不丢行），换公司类型/年报日期可取到对应类型科目的数。**取"最新"值别踩空**：行情类 `--date` 填当天且盘中/未入库会整行 `null`（≠无数据，别据此报"无数据"），改用 T-1 交易日；财务类用报告期末（如 `2025-12-31`）。详见 `references/commands/indicator.md`
+- **证券基本面 / 指标先按任务形态路由，不是搜到 EDE 就一律走 EDE**：
+  - 单证券先优先对应 `fundamental` 专用命令（财务、估值、盈利预测、股东、主营或完整三大报表，多数免费 / 低价）。其中 `valuation-analysis` / `earning-forecast` 实测仅支持 A 股；港 / 美股的估值历史分位、盈利预测、以及 PE/PB 等核心估值（EDE 也仅 A 股）当前 CLI 均无可用接口，如实说明不支持、勿用别的语义顶替
+  - 多证券批量取一组**已实现**财务 / 估值指标 → 优先 `indicator search` 后用 EDE 一次拉取，替代逐只循环；单日或同一报告期横向比较用 `cross-section`，区间走势用 `time-series`（后者不能多指标 × 多证券同时）
+  - 始终排除 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`
+- 行业 / 宏观指标（空调销量、社融等，无证券维度）走 `alternative edb-*`（EDB），不要与证券级 EDE 混用
+- EDE 单元格级缺值返回 `null` 且保留证券行；**整个查询无数据仍可能报 `999999`**。日期语义按指标分三类：财务报表指标=报告期末（可为非交易日）、`finc_pe_ttm` 等日频估值=最新交易日、`finc_pb_mrq`(MRQ) 等=最近报告期末（交易日取 `null`）；混合取数按各自有效日期分次 `cross-section` 再按证券合并，别塞进同一个 `--date`。详见 `references/commands/indicator.md`
 - "业绩点评"双义消歧：**检索已有**（研报/纪要里的业绩点评内容）走 `insight ... list --llm-tag earningsReview`（0.1/条）；**AI 现生成**一份走 `ai earnings-review`（异步、50/次）。不确定问一句
-- "多公司最新 PE / 总市值"：单证券估值序列走 `fundamental valuation-analysis`（免费、默认近一年日频、**无总市值指标**）；要总市值或多证券横向快照走 `indicator cross-section`（先 search 拿 code，按单元格计费）。总市值 `qte_mkt_cptl` **仅 A 股**、默认原始「元」（茅台 ≈1.5e12），比大小前用 `scale`/`currency` 统一（详见 indicator.md）
 
 ## 公司名 → 证券代码
 
@@ -198,7 +202,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 | **下载** | 各 `download` | stdout = 文件路径字符串 | 直接读 stdout 整行 |
 | **AI 内容** | one-pager / investment-logic / peer-comparison / research-outline | `{content: "markdown文本"}` | 取 `content` 直接呈现 |
 | **K 线** | quote * | `{list: [{tradeDate, ...}]}` | 按 tradeDate 排序，取需要的尾部 |
-| **异步（含 *-check）** | earnings-review / viewpoint-debate / earnings-review-check / viewpoint-debate-check | 提交 `{dataId, status, hint}`；check 成功 `{date, content}` / pending `{status:"pending"}` 或抛 `410110` | 见下方"异步任务流程" |
+| **异步（含 *-check）** | earnings-review / viewpoint-debate / earnings-review-check / viewpoint-debate-check | 提交 `{dataId, status, hint}`；check 成功 `{date, content}` / pending `{status:"pending"}` 或抛 `140001`（旧 `410110`） | 见下方"异步任务流程" |
 
 完整字段对照见 `references/response-schema.md`。
 
@@ -209,7 +213,7 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 - **`--wait`（推荐）**：命令带 `--wait` 阻塞到出结果（CLI 内轮询最长 ≈316s）。**把工具/命令超时设到 ≥360s**，否则外层先超时。直接拿 `{date, content}` 呈现。
 - **手动轮询**（不带 `--wait`）：① 提交 → 拿 `{dataId, status, hint}`；② 间隔 ~30s 调 `*-check --data-id <id>`（预算给足 ~2-3 分钟）；③ `{date, content}`=成功 / `{status:"pending"}`=继续等 / 终态失败=换参重试；④ 多次仍 pending → 把 `dataId` 交用户稍后再 check。
 
-**别把原始码甩给用户**：`410110`=生成中（继续等）、`410111`=终态失败（换参），按 `status` + 退出码判断后用人话说明。
+**别把原始码甩给用户**：`140001`/旧 `410110`=生成中（继续等）、`140002`/旧 `410111`=终态失败（换参），按 `status` + 退出码判断后用人话说明。
 
 ### 呈现规范
 
@@ -232,34 +236,75 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 | 最新一期 / 最新报告期（财报） | — | — | 省略 `--fiscal-year`，传 `--period latest`（默认） |
 | 最新观点 / 今日观点 | 1 天范围 + `--rank-type 2` | — | — |
 
-参数命名：Insight/Vault/AI 用 `--start-time` / `--end-time`（datetime）；Quote/Fundamental 用 `--start-date` / `--end-date`（date）。**三个例外**：`ai knowledge-batch` 的 `--start-time`/`--end-time` 收 **13 位毫秒时间戳**（传 datetime 字符串会报 `expected a finite number`）；`ai hot-topic` 用 `--start-date`/`--end-date`（date）；`quote minute-kline` 虽属 Quote 却用 `--start-time`/`--end-time` 且为 datetime。
+日期参数**按参数名判断、不按命令组**（命令组会误导——AI 里既有 `--start-time` 又有 `--date`/`--report-date`）：名字带 `-date` 的（`--start-date`/`--end-date`/`--date`/`--report-date`）一律 `YYYY-MM-DD`，覆盖 Quote/Fundamental、AI 的 `theme-tracking`(`--date`)/`hot-topic`/`management-discuss-*`(`--report-date`)、Alternative `edb-data`、Indicator `cross-section`(`--date`)/`time-series`；名字带 `-time` 的（`--start-time`/`--end-time`）用 `YYYY-MM-DD[ HH:mm[:ss]]`（秒可省、空格或 `T` 分隔）或 10/13 位时间戳，覆盖 Insight/Vault 各 list、`quote minute-kline`、`ai security-clue`、`ai knowledge-batch`。其中 **A 股公告（`insight announcement list`）与 `knowledge-batch` 会把输入转成 13 位毫秒**（10 位秒自动 ×1000），其余 `-time` 命令（含 `announcement-hk`/`announcement-us`）原样透传字符串；CLI 输入统一接受 10/13 位纯数字或 `YYYY-MM-DD[ HH:mm[:ss]]`（同上：秒可省、空格或 `T` 分隔）。
 
 支持时间倒序的命令加 `--rank-type 2`：opinion / summary / research / foreign-report / announcement / announcement-hk / announcement-us / foreign-opinion / independent-opinion / official-account。其他 list 命令按 API 默认排序。
 
 ## 异常处理
 
+服务端 2026-07-17 重排了错误码（41 个公开码，三层：`999xxx` 服务统一层 / `1xxxxx` 业务通用层 / `2xxxxx` 接口专有层），信封新增 `errorType` 和 `traceId`。
+
+**2026-07-20 逐码实测的结论：迁移是按「错误处理层」而非按业务模块进行的，不能假定文档即现状。**
+- 判别方式：**新码 `code` 是 JSON 数字且带 `errorType`；旧码是字符串且没有**。但这判断的是**这一条错误路径**切没切，不是整个接口——同一个 Insight 接口内，参数校验已发新码 `100003`、路由不存在发新码 `999010`，方法用错却仍发旧码 `900002`。（成功响应也没有 `errorType`，别拿它当判据。）
+- **异步端点（`earnings-review` / `viewpoint-debate`）的生成状态没切**——实测仍是 `410110`/`410111`，HTTP 400，无 `errorType`
+- **token 过滤器没切**——仍是 `0000001007`/`0000001008`；方法路由层的 `900002` 同理
+- 参数校验层、路由层已切
+- 更外层的未知路径（不属于任何已识别路由）**根本不返回统一信封**，是纯文本 `default backend - 404`
+- CLI 对两代都认，报错行带 `[trace <id>]`，**报障给 Gangtise 时务必带上这个 traceId**
+
+**实测确认在用的码**（按遇到概率排；✅=已实测复现）
+
 | 错误码 | 含义 | CLI 行为 | Agent 是否介入 |
 |--------|------|---------|--------------|
-| `999999` | 系统错误；但 **`indicator`（EDE）仍会用此码 + HTTP 500 表示查询无数据**（节假日 / 未来日期 / 未覆盖标的，2026-07-11 实测）——单元格级缺值才是 `null` | 普通端点自动重试 ×2；🔴 贵档与 `indicator` 端点不重试（CLI hint 会直接提示「多为查询无数据」） | `indicator` 遇到先检查日期/标的是否该有数据，别盲目重试 |
-| `410110` | 异步生成中 | 异步轮询逻辑视为 pending | 继续等 |
-| `410111` | 异步生成失败 | 终态 | **不重试**，建议换参数 |
-| `410106` / 缺参 | `indicator` **缺必填参数**（服务端现直接指明缺哪个，如「必填参数 periodNum 不能为空」；以 HTTP 500 返回故 CLI 重试 ×2） | **自动重试 ×2** | 读 `indicator search --format json` 的 `parameterList`，补 `required:true` 参数（periodNum/startDate/fiscalYear） |
-| `0000001008` | Token 服务端失效（他处登录挤掉） | **强制重新登录并重试一次** | 无 AK/SK 时无法自愈，提示重新登录 |
-| `8000014` / `8000015` | AK/SK 错误 | **自动刷新 token 并重试一次** | 再失败提示检查 env |
-| `8000016` / `8000018` | 账号异常 / 到期 | — | 提示联系管理员 |
-| `999997` | 未开通权限 | — | 联系管理员 |
-| `999995` | 积分不足 | — | 联系管理员 |
-| `903301` | 今日调用上限 | **不重试** | 告知用户次日重试或升级配额 |
-| `433007` | 数据源不匹配 | — | 检查 `resourceType + sourceId` 组合 |
-| `410004` | 数据未找到，或**该指标无权限**（服务端复用此码；`indicator` 内层失败会带具体 msg 如"指标无权限"） | — | 检查查询条件与指标权限 |
-| `430007` | 行情查询超出限制 | — | 缩短日期范围；全市场场景应已自动分片 |
-| `430004` | 研报下载报错（官方未文档化，实测出现于 download） | — | 确认 reportId 有效；换 `--file-type` 或换一篇验证 |
-| `900001` | 请求参数缺失 | — | 检查必填项（如 `--indicator` / `--date`） |
-| `100003` | 参数值非法（服务端不指明是哪个参数） | — | 对照命令 `--help` 检查枚举参数拼写/取值（如 `--source` / `--question-category` / `--answer-important`），**不要重试同命令** |
-| `900002` | 请求缺少 uid | — | `gangtise auth status` 查登录状态，重登后重试 |
-| `10011401` | 白名单未开通 | — | 联系管理员 |
-| HTTP 5xx / `ECONNRESET` / 超时 | 网络/服务端 | **自动指数退避重试 ×2** | 仍失败提示用户 |
-| `ValidationError` | 本地参数校验失败 | — | 检查 `--from` / `--size` / `--limit` 数值，**不要重试同命令** |
+| ✅ `100003` | 参数值非法——**最宽的兜底码**：类型错、`limit` 越界都归这里。**msg 通常已指明字段**（如「请求体字段类型不匹配: size 期望类型 Integer」「limit 最小为 1，最大为 10000」），先读 msg 再猜 | — | 按 msg 指的字段改；msg 没指明才对照 `--help` 查枚举拼写，**不要重试同命令** |
+| ✅ `999999` | 系统错误；但 **`indicator`（EDE）用此码 + HTTP 500 表示查询无数据**（节假日 / 未来日期 / 未覆盖标的，2026-07-11 实测）——单元格级缺值才是 `null` | 普通端点自动重试 ×2；🔴 贵档与 `indicator` 端点不重试 | `indicator` 遇到先检查日期/标的是否该有数据，别盲目重试 |
+| ✅ `410110` | **异步生成中**（HTTP 400，旧码未切）。新码 `140001`，CLI 两码都认 | 轮询视为 pending | 继续等 |
+| ✅ `410111` | **异步生成失败**（HTTP 400，旧码未切）。新码 `140002`，CLI 两码都认 | 终态 | **不重试**，换参数 |
+| ✅ `130002` | 资源不存在——**下载类的兜底码**：`reportId` 不存在 / 非数字 / `fileType` 非法**全归这里**（`130003`/`130004`/`130005` 实测均未启用） | — | 确认 ID 有效且本账号可见；换 `--file-type` 或换一篇验证 |
+| ✅ `130001` | 数据未找到，或**该指标无权限**（`indicator` 内层失败会带具体 msg 如"指标无权限"） | — | 检查查询条件与指标权限 |
+| ✅ `100001` | 缺必填参数——**msg 带字段名**（「缺少必填参数: reportId」） | — | 按 msg 指的字段补上 |
+| ✅ `110001` / `110002` | 日期格式错（msg 带字段名）/ 起晚于止。**哪个格式报错、哪个被静默误读是端点相关的**（实测 `fundamental` 对 `2020/01/01` 报 110001，`insight research list` 对 `30/06/2025` 却宽松解析返回数据）——别按命令组预判 | — | 按参数名：`--*-date` 用 `YYYY-MM-DD`、`--*-time` 用 `YYYY-MM-DD HH:mm:ss`；`ai knowledge-batch` 的 --start-time/--end-time 收时间戳或 datetime，CLI 统一转 13 位毫秒 |
+| ✅ `120001` | 证券代码无效——msg 带原因（「非有效A股」）。**只有 Fundamental 系报**，Quote 系静默返回空 | — | `reference securities-search` 确认代码与后缀（`600519.SH` / `00700.HK`） |
+| ✅ `100006` | 查询/下载数量超限——**取代旧 `430007`**；实测 `fund-flow` 全市场不传日期即此码 | — | 缩短日期范围或调小 `--size`/`--limit`；全市场场景应已自动分片 |
+| ✅ `240001` | 财报期未披露或超出查询期（`earnings-review` 提交阶段就报，**不扣积分**） | — | 换更早的 `--period`（`2025q3` → `2025interim`） |
+| ✅ `250001` | 不支持的数据源——**取代旧 `433007`** | — | 检查 `resourceType + sourceId` 组合 |
+| ✅ `999011` | 开发账号凭证无效——**取代旧 `8000014`/`8000015`，已合并，不再区分 AK 错还是 SK 错** | 登录即失败，**不重试** | 检查 `GANGTISE_ACCESS_KEY`/`GANGTISE_SECRET_KEY` 是否写反或未 export |
+| ✅ `999010` | 接口地址不存在 | — | `raw call` 的 key 可能已下线，用 `gangtise raw list` 核对 |
+| ✅ `0000001008` | Token 服务端失效（他处登录挤掉）——**旧码未切，token 自愈依赖它** | **强制重新登录并重试一次** | 无 AK/SK 时无法自愈，提示重新登录 |
+| ✅ `0000001007` | 请求未携带 Bearer token | — | 检查 `GANGTISE_TOKEN` / AK/SK 是否已 export |
+| ✅ `900002` | **请求方法不正确**（msg「请求类型有误」，HTTP 405）——旧文档写作"缺少 uid"是错的 | — | `raw call` 时确认该 endpoint 是 GET 还是 POST |
+| `410106` / 缺参 | `indicator` 缺必填参数（msg 直接指明，如「必填参数 periodNum 不能为空」；HTTP 500 故 CLI 重试 ×2） | **自动重试 ×2** | 读 `indicator search --format json` 的 `parameterList` 补 `required:true` 参数 |
+
+**⚠️ 实测发现的坑（都是"不报错"型，最难发现）**
+- 🔴 **日期只写 `YYYY-MM-DD`、时间只写 `YYYY-MM-DD HH:mm:ss`（或 10/13 位时间戳）；CLI v0.28.0 起 date 与 datetime 两类、含所有 insight/vault 透传参数都本地拦截**。服务端对「年在后」格式**日月顺序随分隔符翻转**且静默误解析（HTTP 200、不回显实际用的日期）：`07/01/2026`（斜杠）读成 **2026-01-07**、`07-01-2026`（横杠）读成 **2026-07-01**，差半年。实测 `insight research list --start-time`：`07/01/2026` 命中 1562 条、`07-01-2026` 命中 210 条（分别 = 标准 `2026-01-07` / `2026-07-01`）；`quote day-kline`/`kline-hk`/`kline-us`/`index`、`fundamental balance-sheet` 同理。v0.28.0 前透传命令（research/summary/announcement-hk/us/vault/minute-kline 等）**静默放行**，且同值在本地转时间戳的 `announcement`（A 股）与透传的 hk/us 之间还会差半年、都 exit 0。现在全部在发请求前报 `ValidationError`，**但绕过 CLI 直连接口务必自己保证格式**
+- **财报接口的日期按「报告期末」过滤**，不是公告日：`fundamental balance-sheet` 等的 `--start-date`/`--end-date` 匹配的是 `endDate` 字段（如 `20200630`），响应里的 `announcementDate`（如 `20200729`）只是公告日。**查某期财报要传季度末日期**（`2020-06-30` / `2020-03-31` / `2020-09-30` / `2020-12-31`）；传 `2020-07-01` 这类非报告期日期会返回 0 行，属正常行为，不是没数据
+- 🔴 **Quote 系对非法证券代码不报错**，静默返回 `total:0` 空列表——无法区分"代码写错"和"该票该区间真无数据"。**空结果先回头核对代码后缀**。Fundamental 系会正常报 `120001`
+- **枚举值拼错、分页参数越界服务端不报错**——静默忽略该条件返回全量/正常结果。所以 `100004`/`100005` 实测触发不到。CLI 只对**部分**参数加了本地白名单（`--top` 上限；`--category` 仅 `reference securities-search` / `institution-search` / `official-account-search` 三个命令），**`insight research --category` 等仍是自由字符串、拼错不报错也不生效**。**拼错的筛选条件会伪装成"结果正常"，枚举拼写要自己保证**
+- **`viewpoint-debate` 传敏感内容不会被提前拦截**——实测不返回 `240002`，而是照常受理、扣满 50 积分、生成阶段才以 `410111` 失败。**提交前自己把关措辞**
+- **`ai one-pager` 的非法 `mode` 被静默忽略**，照常生成并扣 50 积分
+
+**官方文档列出、但实测未触发的码**（遇到再查，多数被上面的兜底码接管）
+
+| 错误码 | 含义 | 实测情况 |
+|--------|------|---------|
+| `999001` / `999002` | 缺 token / token 无效 | 实际返回旧码 `0000001007` / `0000001008` |
+| `999007` / `999008` / `999009` | 方法/媒体类型/请求体不支持 | 实际返回 `900002` / `999999` / `100003` |
+| `999003` / `999004` / `999005` / `999006` | 无接口权限 / 无资源权限 / 积分不足 / 限流 | 未构造出（需特定账号状态） |
+| `999012`–`999016` | 账号禁用/过期、租户失效、无长期 token、IP 不合规 | 未构造出 |
+| `100002` / `100004` / `100005` | 类型错 / 分页非法 / 枚举非法 | 类型错归 `100003`；后两者服务端静默忽略 |
+| `110003` | 超出时间范围限制 | 未触发（1900 年至今的范围仍正常返回） |
+| `130003` / `130004` / `130005` | 无文件可下 / ID 非数字 / 文件类型不支持 | 全部归 `130002` |
+| `140001` / `140002` | 结果生成中 / 处理失败 | 异步端点仍用 `410110` / `410111` |
+| `210001` / `220001` / `230001` | 研报/观点/分享文件不支持下载 | 未构造出 |
+| `240002` / `240003` | 敏感词 / 模式不支持 | 敏感词走 `410111`；`one-pager` 的非法 `mode` 被静默忽略 |
+| `903301` / `10011401` | 今日调用上限 / 白名单未开通 | 历史遗留，**均未实测触发**。不臆断对应新码——`10011401` 按语义更接近 `999003`（未开通接口权限）而非 `999016`（IP 限制），别据此去查 IP |
+
+**非错误码**
+
+| 情形 | CLI 行为 | Agent 是否介入 |
+|------|---------|--------------|
+| HTTP 5xx / `ECONNRESET` / 超时 | **自动指数退避重试 ×2**（🔴 贵档端点不重放） | 仍失败提示用户 |
+| `ValidationError` | 本地参数校验失败 | 检查 `--from` / `--size` / `--limit` 数值，**不要重试同命令** |
 
 **其他场景**：
 - CLI 未安装 → `npm install -g gangtise-openapi-cli`
@@ -284,21 +329,23 @@ gangtise reference securities-search --keyword <公司名> --category stock --to
 3. 行业 ID 用错体系：`--industry`（用 `citicIndustry` 码 `1008001xx`）/ `--research-area`（用 `gangtiseIndustry`：行业 `1008001xx` + 方向 `122000xxx`）/ `--gts-code`（申万 `821xxx.SWI`）——三套体系不同，详见 `references/commands/reference-and-lookup.md`
 4. `--rating` / `--category` 等枚举值拼错（参考对应命令的 references 文件）
 
-**`8000014` / `8000015` 反复**（CLI 已自动重试一次仍失败）
+**`999011` 凭证无效**（旧码 `8000014`/`8000015`；服务端已合并为一个码，不再指明是 AK 错还是 SK 错，**登录直接失败、CLI 不重试**）
 1. `echo $GANGTISE_ACCESS_KEY` 验环境变量是否 export
 2. AK 和 SK 是否写反
-3. 账号是否到期 / 异常（`gangtise auth status`）
+3. 账号是否到期 / 异常（`gangtise auth status`；对应 `999012`/`999013`）
 
-**异步任务 `410111` 反复**（该报告期数据未生成）
-1. 换更早的 `--period`（如 `2025q3` → `2025interim`）
-2. `report-date` 用已发布的标准期：`xxxx-06-30` / `xxxx-12-31`
-3. 直接告知用户该期数据暂不可用
+**异步任务 `410111` 反复**（生成失败，终态）
+1. `viewpoint-debate`：先检查观点措辞——实测敏感内容不会被提前拦截，会扣满 50 积分再以 `410111` 失败
+2. `earnings-review`：换更早的 `--period`（如 `2025q3` → `2025interim`）
+3. `report-date` 用已发布的标准期：`xxxx-06-30` / `xxxx-12-31`
+4. 若提交阶段就返回 `240001`（财报期未披露），说明该期不可查且**未扣积分**，别再换参数试
+5. 直接告知用户该期数据暂不可用
 
 **K 线返回的不是"最近"几条** → 只用 `--limit` 截的是窗口开头。必须改用 `--start-date`/`--end-date` 拉范围，再从结果尾部按 `tradeDate` 取最近 N 条。
 
 **翻页很慢 / 卡住** → `--verbose` 看哪一页慢；可 `GANGTISE_PAGE_CONCURRENCY=10` 提速，或缩小时间范围。
 
-**`--security all` 报 `430007`** → 单日数据仍超 10K 行（极端情况）→ 临时改用更窄的 `--start-date`/`--end-date`，或改为单只 `--security` 单独拉。
+**`--security all` 报 `100006`**（旧码 `430007`）→ 单日数据仍超 10K 行（极端情况）→ 临时改用更窄的 `--start-date`/`--end-date`，或改为单只 `--security` 单独拉。
 
 **AI agent 命令（one-pager 等）超时** → 服务端生成耗时长，CLI 默认 30s → `GANGTISE_TIMEOUT_MS=120000` 后重试。
 

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

@@ -9,14 +9,14 @@
 ## 知识库搜索 `ai knowledge-batch`
 
 ```bash
-gangtise ai knowledge-batch --query <text> [--query <text2>] [--top <n>] [--resource-type <n>] [--knowledge-name <name>] [--start-time <ms>] [--end-time <ms>]
+gangtise ai knowledge-batch --query <text> [--query <text2>] [--top <n>] [--resource-type <n>] [--knowledge-name <name>] [--start-time <ts|datetime>] [--end-time <ts|datetime>]
 ```
 
 - `--query`（**必选**，可重复，最多 5 个）：缺失时本地报错，不发空请求
 - `--top` 默认 10，最大 20
 - `--resource-type`：`10` 券商研报 | `11` 外资研报 | `20` 内部报告 | `40` 首席观点 | `50` 公司公告 | `51` 港股公告 | `60` 会议平台纪要 | `70` 调研纪要公告 | `80` 网络资源纪要 | `90` 产业公众号
 - `--knowledge-name`：`system_knowledge_doc` 系统知识库 | `tenant_knowledge_doc` 机构知识库
-- `--start-time` / `--end-time`：13 位毫秒时间戳，按时间范围过滤
+- `--start-time` / `--end-time`：13/10 位时间戳或 `YYYY-MM-DD[ HH:mm[:ss]]`（秒可省、空格或 `T` 分隔；CLI 统一转 13 位毫秒，10 位秒自动 ×1000），按时间范围过滤
 
 ## 知识资源下载 `ai knowledge-resource-download`
 
@@ -24,7 +24,7 @@ gangtise ai knowledge-batch --query <text> [--query <text2>] [--top <n>] [--reso
 gangtise ai knowledge-resource-download --resource-type <n> --source-id <id> [--output <path>]
 ```
 
-`resourceType + sourceId` 必须匹配（来自 knowledge-batch 返回），错配返回 `433007`。
+`resourceType + sourceId` 必须匹配（来自 knowledge-batch 返回），错配返回 `250001`（旧 `433007`）。
 
 ## 投研线索 `ai security-clue`
 
@@ -86,7 +86,7 @@ gangtise ai earnings-review-check --data-id <id>
 - `--period`：`年份+报告期`，如 `2025q3`（q1/interim/q3/annual），仅 A 股，覆盖最近 6 期
 - `--wait`（**推荐**）：阻塞等待到出结果（最长约 5 分钟：14 次指数退避轮询 5s→30s，累计 ≈316s）——**用它时把工具/命令超时设到 ≥360s**，否则外层先超时
 - 不带 `--wait` 的手动轮询：① `earnings-review` → 拿 `{dataId, status, hint}` → ② 间隔 ~30s `*-check`（预算 ~2-3 分钟）→ pending 继续 → 多次仍 pending 交用户稍后手动 check
-- 错误码：`410110` 生成中（继续等待）；`410111` 生成失败（终态，不重试）
+- 错误码：`140001`（旧 `410110`）生成中，继续等待；`140002`（旧 `410111`）生成失败，终态不重试。CLI 两代码都识别
 
 ## 观点 PK `ai viewpoint-debate`（异步）
 

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

@@ -1,6 +1,6 @@
 # Fundamental 命令详细参数
 
-通用：所有命令都需 `--security-code`（如 `600519.SH`，注意是 `--security-code` 不是 `--security`）。`--field` 可重复，可用字段见 `references/fields.md`。
+通用：所有命令都需 `--security-code`（如 `600519.SH`，注意是 `--security-code` 不是 `--security`）。`--field` 可重复，可用字段见 `references/fields.md`；A / 港 / 美股三大报表命令都在省略 `--field` 时返回完整报表，指定后只保留基础字段与所选科目。
 
 ---
 
@@ -74,24 +74,26 @@ gangtise fundamental main-business --security-code <code> [--breakdown <type>] [
 - `--breakdown`（默认 `product`）：`product` 按产品 | `industry` 按行业 | `region` 按地区
 - `--period`：`interim` 中报 | `annual` 年报（可重复）
 - 默认时间窗：`endDate` 当前日期、`startDate` 三年前
-- **不支持 `--fiscal-year`**（误传触发 900001）；按年份筛选用 `--start-date`/`--end-date`
+- **不支持 `--fiscal-year`**（误传触发 `100001`/`100003`，旧 `900001`）；按年份筛选用 `--start-date`/`--end-date`
 
-## 估值分析 `fundamental valuation-analysis`
+## A股估值分析 `fundamental valuation-analysis`
 
 ```bash
 gangtise fundamental valuation-analysis --security-code <code> --indicator <name> [--start-date <date>] [--end-date <date>] [--limit <n>] [--field <name>] [--skip-null]
 ```
 
+- **市场与路由**：本命令实测仅支持 A 股（港股 / 美股会报 `120001`「非有效A股」）。A股单证券估值序列与估值历史分位始终优先本命令；多证券批量取一组已实现估值点值，且 `indicator search` 三项校验都通过时，才优先 EDE `cross-section` / `time-series`。港 / 美股估值历史分位当前 CLI 不支持，不能用普通 EDE 点值冒充
 - `--indicator`（**必选**）：`peTtm` 滚动PE | `pbMrq` PB | `peg` PEG | `psTtm` 滚动PS | `pcfTtm` 滚动PCF | `em` 企业倍数
 - `--limit` 默认 2000，省略 `--start-date` 时自动查近一年
 - `--skip-null`：丢弃 `value`/`percentileRank` 为 null 的行（最新交易日可能未入库）
 
-## 盈利预测 `fundamental earning-forecast`
+## A股盈利预测 `fundamental earning-forecast`
 
 ```bash
 gangtise fundamental earning-forecast --security-code <code> [--start-date <date>] [--end-date <date>] [--consensus <name>]
 ```
 
+- **市场与路由**：本命令实测仅支持 A 股（港股 / 美股会报 `120001`「非有效A股」）。A股盈利预测 / 一致预期始终走本命令，不走 EDE；EDE 搜索目前没有一致预期语义，搜到的基本 / 稀释 EPS 是已实现值，不能冒充预测 EPS。港 / 美股盈利预测当前 CLI 不支持
 - `--start-date` / `--end-date`：默认近一年
 - `--consensus` 可重复：`netIncome` 归母净利润 | `netIncomeYoy` 同比增速 | `eps` 每股收益 | `pe` 市盈率 | `bps` 每股净资产 | `pb` 市净率 | `peg` PEG | `roe` 净资产收益率 | `ps` 市销率
 - 返回结构：`{securityCode, securityName, updateList: [{date, fieldList: [{forecastYear, ...consensus}]}]}` — 每个日期固定返回 3 年预测（如 `2026E` / `2027E` / `2028E`）

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

@@ -1,24 +1,38 @@
 # Indicator 命令详细参数（数据指标 EDE：证券级指标截面 / 时序）
 
-> 本组覆盖 `/application/open-indicator/EDE/*`：证券级**数据指标**的检索与取数（收盘价、成交量、总市值、财务指标等，按个股取值）。
+> 本组覆盖 `/application/open-indicator/EDE/*`：证券级**数据指标**的检索与取数，主要用于多证券批量取已实现财务 / 估值指标。即使能搜到收盘价、成交量等行情指标，常规行情与 K 线仍走免费的 `quote`。
 > 与 `alternative edb-*`（EDB 行业/宏观指标，无证券维度）是两套接口，别混。
 >
 > **取数前先 `indicator search` 拿 `indicatorCode`**，绝不猜测指标编码。
 
+## EDE 与专用接口的优先级
+
+| 请求形态 | 优先接口 |
+| :--- | :--- |
+| 单证券的财务 / 股东 / 主营，或 A股单证券估值 | 对应 `fundamental` 专用命令；多数免费，且字段口径固定 |
+| 多证券批量取一组**已实现**财务 / 估值指标 | 先 `indicator search`，通过下方三项校验后用 `cross-section` / `time-series` 一次拉取，避免逐只循环 |
+| A股盈利预测 / 一致预期（含预测 EPS） | `fundamental earning-forecast`；EDE 搜到的基本 / 稀释 EPS 是已实现值，不能替代预测 |
+| A股估值历史分位 | `fundamental valuation-analysis` |
+| 开高低收 / 成交量等行情与 K 线 | `quote`；免费且支持多证券批量 |
+| 单证券三大报表全部科目 | 对应 `fundamental` 利润表 / 资产负债表 / 现金流量表命令 |
+
+EDE 不是“搜到就优先”。取数前必须核对：① `indicatorName` + `description` 与目标语义一致；② `scopeList` 覆盖**全部**目标市场和证券类型；③ `parameterList` 的必填参数与枚举可满足。`scopeList` 缺失 / `null` / 空或任一项不符，都视为无法证明覆盖并回退上表的专用接口；专用接口也不支持目标市场时，如实说明当前 CLI 无可用口径，不能用其他语义代替。实测 `valuation-analysis` / `earning-forecast` 仅支持 A 股，港 / 美股估值历史分位与盈利预测当前无可用口径；PE/PB 等核心估值指标 EDE 也只有 A 股（`finc_pe_ttm`/`finc_pb_mrq` 均 `[A股]`），别假定港 / 美股估值能从 EDE 取，一律以 `scopeList` 为准。`search` 免费，EDE 取数按单元格计费；除多证券批量的效率收益外，仍优先免费 / 低价的 `quote` 或 `fundamental`。
+
 ## 指标搜索 `indicator search`
 
 ```bash
 gangtise indicator search --keyword <text> [--limit <n>]
 ```
 
-- `--keyword`（**必选**）：按指标名称模糊匹配。用具体词，如 `收盘价` / `成交量` / `营业收入` / `总市值`，**不能用整句白话**（"我想查茅台的收盘价" ✗）
+- `--keyword`（**必选**）：按指标名称模糊匹配。用具体词，如 `营业收入` / `基本每股收益` / `市盈率` / `总市值`，**不能用整句白话**（"我想查一批公司的财务估值" ✗）
 - `--limit`：返回条数上限，默认 50，最大 100
-- 默认 `--format table`（看 `indicatorCode` / `indicatorName` / `description` 即可）；要看每个指标支持哪些参数（`parameterList`），用 `--format json`
-- 返回字段：`indicatorCode` / `indicatorName` / `description`（算法）/ `parameterList`（可传的 `--indicator-param` 参数及枚举）/ `score`（`scope` 适用市场/品种字段服务端当前多返 `null`）
-- **市场范围**：指标数据覆盖 A 股 / 港股 / 美股（2026-07 起扩展，此前仅 A 股）。美股代码用交易所后缀 `.O`(NASDAQ) / `.N`(NYSE)，**不是 `.US`**——实测 `AAPL.US` 查不到数据，须用 `AAPL.O`（官方示例里的 `AAPL.US` 是笔误）
+- 默认 `--format table` 只适合浏览名称；正式路由 / 取数前必须加 `--format json`，才能完成语义、`scopeList`、`parameterList` 三项校验
+- 返回字段：`indicatorCode` / `indicatorName` / `description`（算法与口径）/ `scopeList`（该指标适用的市场 + 证券类型）/ `parameterList`（可传的 `--indicator-param` 参数及枚举）/ `score`
+- **市场范围按指标判断**：`scopeList` 现在会返回实际覆盖范围，且指标之间不同；不能笼统写成每个指标都覆盖 A / 港 / 美股。实测 `finc_pe_ttm` / `finc_pb_mrq` 仅 A 股，`is_op_rev` 覆盖 A 股 + 港股，这些财务 / 估值指标均不含美股。目标列表含任一 scope 外证券时，本批 EDE 校验不通过，应回退专用接口
+- 美股代码用交易所后缀 `.O`(NASDAQ) / `.N`(NYSE)，**不是 `.US`**——实测 `AAPL.US` 查不到数据，须用 `AAPL.O`（官方示例里的 `AAPL.US` 是笔误）
 
 ```bash
-gangtise indicator search --keyword 收盘价 --limit 5 --format json   # 看 parameterList
+gangtise indicator search --keyword 营业收入 --limit 10 --format json   # 做语义 + scopeList + parameterList 三项校验
 ```
 
 ## 指标截面数据 `indicator cross-section`
@@ -31,20 +45,20 @@ gangtise indicator cross-section --indicator <code> [--indicator <code2>] \
 
 - `--indicator`（**至少 1 个**）：指标编码，来自 `search`，可重复传多个
 - `--security`（**至少 1 个**）：证券代码，如 `600519.SH`（A股）/ `09992.HK`（港股）/ `AAPL.O`（美股，用 `.O`/`.N` 后缀，非 `.US`），可重复传多个
-- `--date`（**必选**）：数据日期 `yyyy-MM-dd`（须为交易日，非交易日/无数据日返回空）
+- `--date`（**必选**）：数据日期 `yyyy-MM-dd`；日期语义按指标分三类——财务报表指标=报告期末（可为非交易日，实测 `2024-03-31` 可取数）、`finc_pe_ttm` 等日频估值=交易日、`finc_pb_mrq`(MRQ) 等=最近报告期末（交易日取 `null`，详见下方「日期路由」）。单元格级缺值返回 `null`，整个查询无数据可能报 `999999`
 - `--currency`：币种 `DFT`(原始,默认)/`CNY`/`HKD`/`USD`/`EUR`/`GBP`/`JPY`/`TWD`/`MOP`/`AUD`
 - `--scale`：量纲 `0`(个,默认)/`3`(千)/`4`(万)/`6`(百万)/`8`(亿)/`9`(十亿)
 - **支持多指标 × 多证券**（单日横截面）
 - **输出（宽表）**：每行一只证券，列为 `date / security / name / <各指标名>…`
 
 ```bash
+# 多证券 × 同一报告期的已实现财务指标
 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
-# date        security   name   日收盘价  成交量      总市值
-# 2026-05-18  600519.SH  贵州茅台  1323   4966097   1656753494445
-# 2026-05-18  09992.HK   泡泡玛特  150.7  15301079  20209520.2705
+  --indicator is_op_rev --indicator is_eps_bas \
+  --security 600519.SH --security 000858.SZ --security 300750.SZ \
+  --date 2025-12-31 --format table
+# 列：date / security / name / 营业收入(利润表,累计) / 基本每股收益(利润表,累计)
+# 省略 reportType 即取到合并口径数（茅台2025=1688亿）。⚠️ 该枚举 label 与实测不符：label 标 1母公司/2合并/3母公司调整/4合并调整，实测 value=2/4 直接 999999、value=1 反返合并值——要指定报表口径改用 `fundamental income-statement --report-type`，勿在 EDE 按 label 传 reportType
 ```
 
 ## 指标时间序列 `indicator time-series`
@@ -62,22 +76,16 @@ gangtise indicator time-series --indicator <code> [--indicator <code2>] \
 - **输出（宽表）**：每行一个日期，列为 `date / <各序列名>…`；序列在「单证券」时是各**指标**，在「多证券」时是各**证券**
 
 ```bash
-# 多指标 × 单证券：列 = 指标
-gangtise indicator time-series --indicator qte_close --indicator qte_vol \
-  --security 600519.SH --start-date 2026-05-18 --end-date 2026-05-22
-# date        日收盘价    成交量
-# 2026-05-18  1323     4966097 ...
-
-# 单指标 × 多证券：列 = 证券
-gangtise indicator time-series --indicator qte_close \
-  --security 600519.SH --security 09992.HK --start-date 2026-05-18 --end-date 2026-05-22
-# date        贵州茅台    泡泡玛特
-# 2026-05-18  1323     150.7 ...
+# 单个已实现估值指标 × 多证券：列 = 证券
+gangtise indicator time-series --indicator finc_pe_ttm \
+  --security 600519.SH --security 000858.SZ --security 300750.SZ \
+  --start-date 2026-05-18 --end-date 2026-05-22
+# date        贵州茅台    五粮液    宁德时代
 ```
 
 ## 复权 / 指标专属参数 `--indicator-param`
 
-通用的币种/量纲用 `--currency` / `--scale`；指标**专属**参数（如行情复权方式）用 `--indicator-param`，格式 `指标code:参数key=值`，可重复：
+通用的币种/量纲用 `--currency` / `--scale`；指标**专属**参数用 `--indicator-param`，格式 `指标code:参数key=值`，可重复。下面的行情复权仅演示底层参数语法；常规行情 / K 线仍优先 `quote`，不要照此例改走 EDE：
 
 ```bash
 # 茅台收盘价后复权（adjustmentType=3）
@@ -88,7 +96,7 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 
 - `adjustmentType`（复权方式）：`1`=不复权 `2`=前复权 `3`=后复权 `4`=定点复权
 - 同一指标多个参数 → 重复 `--indicator-param "code:k1=v1" --indicator-param "code:k2=v2"`
-- 某指标支持哪些 `paramKey` 及其枚举值，用 `indicator search --format json` 看该指标的 `parameterList`（**参数 key 与取值（含大小写）均以 search 返回为准**——如 `currency` 在 parameterList 中可能为小写 `dft`/`cny`）
+- 三项校验通过后，再从 `indicator search --format json` 的 `parameterList` 读取该指标支持的 `paramKey` 及枚举值（**参数 key 与取值（含大小写）均以 search 返回为准**——如 `currency` 在 parameterList 中可能为小写 `dft`/`cny`）
 - `--indicator-param` 与根级 `--currency`/`--scale` 冲突时，以 `--indicator-param` 为准
 
 ## 必填参数与错误码（取数前必读）
@@ -99,12 +107,12 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 | :--- | :--- | :--- |
 | `410001` | 入参错误：没传指标/证券，或 `time-series` 传了「多指标 × 多证券」 | 补齐 `--indicator`/`--security`；多 × 多改用 `cross-section` |
 | 缺参报错（曾为 `410106`） | **缺必填参数**：服务端现已直接指明缺哪个，如「指标 X 的必填参数 periodNum(期数) 不能为空」（仍以 HTTP 500 返回，CLI 重试 2 次后透出该消息） | 读 `search --format json` 的 `parameterList`，把 `required:true` 的参数用 `--indicator-param` 补上 |
-| `999999` | **多为整查询无数据**（节假日 / 未来日期 / 未覆盖标的；单元格级缺值才是 `null`），也可能是真系统故障——服务端不区分两者 | CLI 对 indicator 端点**不重试此码**（v0.27.0）并在 hint 中提示；先核对日期是交易日、标的在覆盖范围，确认应有数据仍报错才按系统故障处理 |
-| `410004` | 数据未找到，或**该指标无权限**（内层信封失败会带具体 msg，如"指标无权限"；此码被服务端复用） | 检查查询条件与指标权限；换证券/日期仍失败多为无权限，联系管理员开通 |
+| `999999` | **多为整查询无数据**（日期语义不符 / 未来日期 / 未覆盖标的；单元格级缺值才是 `null`），也可能是真系统故障——服务端不区分两者 | CLI 对 indicator 端点**不重试此码**（v0.27.0）并在 hint 中提示；先核对日期符合指标语义、标的在覆盖范围，确认应有数据仍报错才按系统故障处理 |
+| `130001`（旧 `410004`） | 数据未找到，或**该指标无权限**（内层信封失败会带具体 msg，如"指标无权限"；此码被服务端复用） | 检查查询条件与指标权限；换证券/日期仍失败多为无权限，联系管理员开通 |
 
 ### 必填参数（`410106` 的根因）
 
-相当一部分指标默认调用就报 `410106`，因为有必填参数没传。**取数前先 `search --format json` 看 `parameterList`，凡 `required:true` 的都用 `--indicator-param "指标code:参数=值"` 补上。** 三类高频必填参数：
+相当一部分指标默认调用就报 `410106`，因为有必填参数没传。**先完成语义 + `scopeList` + `parameterList` 三项校验；其中凡 `required:true` 的参数都用 `--indicator-param "指标code:参数=值"` 补上。** 三类高频必填参数：
 
 | 参数 | 适用指标 | 示例 |
 | :--- | :--- | :--- |
@@ -116,21 +124,24 @@ gangtise indicator cross-section --indicator qte_close --security 600519.SH \
 
 ## 取数最佳实践
 
-- **先 search 看 parameterList**：一步拿到 code、必填参数（required）、专属参数枚举（`adjustmentType`/`scale`/`currency` 等）。
+- **先 search 做三项校验**：看 `indicatorName` + `description` 确认语义和口径，看 `scopeList` 确认覆盖全部目标市场 / 证券类型，再看 `parameterList` 补齐必填参数（required）并核对专属参数枚举（`adjustmentType`/`scale`/`currency` 等）；任一不符就回退专用接口。
 - **公司类型决定有没有这个科目**：财务科目分公司类型——银行有「存放同业」、券商有「客户资金存款」、保险有「预收保费」，一般企业没有。某指标对茅台返回 `null`（无此科目），换到对应类型证券（招行/中信/平安）就有数。
 - **日期路由**：
-  - 财务类（`bs_`/`is_`/`cf_`/`finc_`/`div_`/`shr_` 等）→ 用**报告期末**（Q1 `2026-03-31`、年报 `2025-12-31`）
+  - 财务报表类（`bs_`/`is_`/`cf_`/`div_`/`shr_`，以及 description 明确按报告期统计的 `finc_`）→ 用**报告期末**（Q1 `2026-03-31`、年报 `2025-12-31`，无需是交易日）
+  - 日频估值类（如 `finc_pe_ttm`）→ 用最新已入库的交易日；但 `finc_pb_mrq`(市净率 MRQ) 等 MRQ 口径**只在报告期末打值**，交易日会取到 `null`，要用季度末日期（实测 `2026-07-22` PB 空、`2026-03-31` 有）。别因 code 都以 `finc_` 开头就一律套报告期末、也别一律套交易日——按 `description`/实测区分
   - 现金流量表附注/间接法科目（多数 `cf_`）→ **只在年报/半年报披露**，季报日期取不到，改用年报日期 `2025-12-31`
-  - 行情/基本资料（`qte_`/`pty_`/`scr_`/`frcst_`）→ 用**交易日**
-- **探索性取数**：截面与时序现在对无数据都优雅处理（截面返 `null` 单元格、时序返空行），都适合"先看有没有数"；看趋势仍优先 `time-series` + 覆盖报告期的区间。
+  - 行情类（`qte_` 等）→ 用**交易日**，但常规行情仍应改走 `quote`
+- **混合日期语义要拆查询**：同时要“某报告期营收 / EPS”和“估值 PE / PB”时，按各自有效日期分别调用 `cross-section` 再按 `security` 合并（财务=报告期末、PE=最新交易日、PB(MRQ)=最近报告期末）；不要把不同日期语义的指标塞进同一个 `--date`
+- **探索性取数**：单元格级缺值返回 `null` 且保留证券行，时序局部无值可为空行；**整个查询无数据仍可能报 `999999`**。看趋势用 `time-series` + 覆盖报告期的区间，但不能把缺值当成通过语义 / scope 校验。
 - **名称反查 code 要核对，别取首条**：存在同显示名的兄弟指标——单季 `cf_finc_exp_qtr` 与累计 `cf_finc_exp` 都叫「财务费用」，`bs_fmt`/`cf_fmt`/`is_fmt` 都叫「报表格式」。`search` 按名称模糊匹配，目标 code 高概率在 top1 但不绝对，要看 `indicatorCode` 确认。
-- **批量查询做失败拆分**：某指标**缺必填参数**或入参错误时会整批报错（无数据不会——按 `null` 返回），逐指标单查能定位是哪个指标缺参/不可查。
+- **批量查询做失败拆分**：某指标**缺必填参数**或入参错误时会整批报错（单元格级无数据按 `null` 返回；整个查询无数据的 `999999` 例外见上），逐指标单查能定位是哪个指标缺参/不可查。
 - **市值量纲（实测 2026-07）**：`qte_mkt_cptl`（总市值）**仅 A 股**——港股/美股返 `null`（换 `currency` 也没用，是 scope 外 ≠ 无数据）；**默认返原始「元」**（茅台 ≈ `1.5e12`，即 1.5 万亿），别误当天文数字。用 `scale` 数字码缩放（`0`元 / `3`千 / `4`万 / `6`百万 / `8`亿 / `9`十亿——`scale=8` → `15038` 亿元）、`currency` 换币种（`dft`本币 / `cny` / `hkd` / `usd` …）。**跨证券比市值前先统一 `scale`+`currency`**。
+- **EDE 财务指标的 `reportType` 枚举不可信（实测 2026-07-23）**：服务端 label（`1`母公司/`2`合并/`3`母公司调整/`4`合并调整）与实际取数不符——`value=2/4` 常直接 `999999`、`value=1` 反而返合并数（茅台2025营收 `value=1`→1688亿、`=3`→983亿、`=2/4`→999999）。**省略即用默认（合并口径，已实测有数）**；要明确指定合并/母公司口径请改用 `fundamental` 三大报表的 `--report-type`（口径语义可靠）。
 
 ## 通用说明
 
-- **发现流程**：`indicator search`（拿 code + 看 parameterList）→ `cross-section` / `time-series` 取数
-- **积分**：`search` 免费；`cross-section` / `time-series` 按单元格计费（A 股 0.05 / 港股 0.1 / 美股 0.2 积分每 100 单元格，不足 100 按 100）
-- **空结果**：日期区间无数据时返回空表（不报错），换交易日/有效区间重试
+- **发现流程**：`indicator search --format json` → 核对 `indicatorName` + `description`、`scopeList`、`parameterList` → 三项都通过才用 `cross-section` / `time-series`
+- **积分**：`search` 免费；`cross-section` / `time-series` 按请求单元格数量计费，标价为每 100 单元格 A 股 0.05 / 港股 0.1 / 美股 0.2 积分，每次查询不足 100 单元格按 100 计
+- **空结果 / 整查询无数据**：时序可能返回空表，截面或整批无数据也可能报 `999999`；先改用符合指标语义的日期 / 有效区间并核对 `scopeList`
 - **数据权限**：试用账号默认可取近 3 年；正式账号按服务等级
 - 所有格式（table/json/jsonl/csv/markdown）均可用；导出宽表给 Excel 直接用 `--format csv --output xxx.csv`

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

@@ -70,6 +70,7 @@ gangtise insight research download --report-id <id> [--file-type <n>] [--output
 - `--rating-change`：`upgrade` | `maintain` | `downgrade` | `initiate`
 - `--source`：`1` PDF研报 | `2` 公众号
 - `--file-type`（download）：`1` 原始PDF（默认）| `2` Markdown
+- **积分**：list 0.1/条；download 10/篇
 
 ## 外资研报 `insight foreign-report list/download`
 

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

@@ -87,7 +87,7 @@ gangtise quote index-day-kline [--security <code>] [--start-date <YYYY-MM-DD>] [
 gangtise quote minute-kline --security <code> [--start-time <datetime>] [--end-time <datetime>] [--limit <n>] [--field <name>]
 ```
 
-- 仅支持 A 股，**必须传 `--security`**（否则返回 430007）
+- 仅支持 A 股，**必须传 `--security`**（否则返回 `100003`，msg 为「securityCode不可为空」；2026-07-20 实测）
 - `--start-time` / `--end-time`：`yyyy-MM-dd HH:mm:ss`（兼容 `yyyy-MM-dd` 自动补全）
 - `--limit` 默认 6000，上限 10000
 - 常用字段：`securityCode` `tradeTime` `open` `high` `low` `close` `change` `pctChange` `volume` `amount`