stock-sdk 1.10.1 → 2.0.0-beta.0

package/README.md

@@ -3,22 +3,29 @@
 [![npm version](https://img.shields.io/npm/v/stock-sdk.svg)](https://www.npmjs.com/package/stock-sdk)
 [![npm downloads](https://img.shields.io/npm/dm/stock-sdk.svg)](https://www.npmjs.com/package/stock-sdk)
 [![license](https://img.shields.io/npm/l/stock-sdk)](https://github.com/chengzuopeng/stock-sdk/blob/master/LICENSE)
-[![MCP](https://img.shields.io/badge/protocol-MCP-blue)](https://www.npmjs.com/package/stock-sdk-mcp)
-[![AI Ready](https://img.shields.io/badge/AI-Ready-orange)](https://stock-sdk.linkdiary.cn/mcp/)
+[![MCP](https://img.shields.io/badge/protocol-MCP-blue)](https://stock-sdk-v2.linkdiary.cn/mcp/)
+[![AI Ready](https://img.shields.io/badge/AI-Ready-orange)](https://stock-sdk-v2.linkdiary.cn/mcp/)
 
 **[English](./README_EN.md)** | 中文
 
 为 **前端和 Node.js 设计的股票行情 JavaScript SDK**。
 
-无需 Python、无需后端服务，直接在 **浏览器或 Node.js** 中获取 **A 股 / 港股 / 美股 / 公募基金** 的实时行情与 K 线数据。
+无需 Python、无需后端服务，直接在 **浏览器或 Node.js** 中获取 **A 股 / 港股 / 美股 / 公募基金** 的实时行情与 K 线数据。还自带 **命令行工具** 与 **MCP server**，一条命令取行情或接入 AI。
 
-**✨ 零依赖 | 🌐 Browser + Node.js | 📦 轻量发布包 | 🧠 完整 TypeScript 类型**
+**✨ 零依赖 | 🌐 Browser + Node.js | 📦 ESM + CJS + subpath | 🧠 完整 TypeScript 类型 | 🖥️ CLI | 🤖 MCP**
 
-## Documentation
+> 🧪 **v2.0.0 Beta**：v2 是一次架构跃迁（命名空间 API、统一符号模型、`Quote` 可辨识联合、统一错误体系、CLI / MCP / subpath 导出）。
+> 安装 beta：`npm i stock-sdk@beta`。从 v1 升级请先读 [v1 → v2 迁移指南](https://stock-sdk-v2.linkdiary.cn/guide/migration-v1-to-v2)（**破坏性变更，无兼容别名**）。
 
-👉🏻 [官方文档](https://stock-sdk.linkdiary.cn/)
+## 📖 官网文档（v2 Beta）
 
-📦 [NPM](https://www.npmjs.com/package/stock-sdk) | 📖 [GitHub](https://github.com/chengzuopeng/stock-sdk) | 🎮 [在线演示](https://stock-sdk.linkdiary.cn/playground/)
+> ## 👉 https://stock-sdk-v2.linkdiary.cn
+>
+> **v2 Beta 的临时官网** —— 完整 API、命名空间总览、CLI / MCP 指南、在线 Playground、v1 → v2 迁移文档全部在这里。先看官网再上手最快。
+>
+> （v1 稳定版文档仍在 https://stock-sdk.linkdiary.cn）
+
+📦 [NPM](https://www.npmjs.com/package/stock-sdk) | 📖 [GitHub](https://github.com/chengzuopeng/stock-sdk) | 🎮 [在线 Playground](https://stock-sdk-v2.linkdiary.cn/playground/)
 
 🧭 [Stock Dashboard](https://chengzuopeng.github.io/stock-dashboard/)：基于 stock-sdk 搭建的股票数据大盘演示站点，欢迎体验。
 
@@ -29,7 +36,6 @@
 * 股票行情工具大多是 **Python 生态**，前端难以直接使用
 * 想做行情看板 / Demo，不想额外维护后端服务
 * 财经接口返回格式混乱、编码复杂（GBK / 并发 / 批量）
-* AkShare 很强，但并不适合浏览器或 Node.js 项目
 
 **stock-sdk 的目标很简单：**
 
@@ -44,355 +50,246 @@
 * 🎓 股票 / 金融课程 Demo
 * 🧪 量化策略原型验证（JS / Node）
 * 🕒 Node.js 定时抓取行情数据
+* 🖥️ 命令行临时查行情 / 🤖 给 AI 工具接数据源
 
 ---
 
 ## 特性
 
-- ✅ **零依赖**，轻量级发布包
-- ✅ 支持 **浏览器** 和 **Node.js 18+** 双端运行
-- ✅ 同时提供 **ESM** 和 **CommonJS** 两种模块格式
-- ✅ 完整的 **TypeScript** 类型定义和单元测试覆盖
-- ✅ **A 股、港股、美股、公募基金**实时行情
-- ✅ **基金深度数据**（v1.10.0+）：历史净值（全历史单位/累计）、实时估值（盘中刷新）、同类排名走势、基金/ETF 分红送配
-- ✅ **历史 K 线**（日/周/月）、**分钟 K 线**（1/5/15/30/60 分钟）和**当日分时走势**数据
-- ✅ **技术指标**：内置 MA、MACD、BOLL、KDJ、RSI、WR、BIAS、CCI、ATR、OBV、ROC、DMI、SAR、KC
-- ✅ **期货行情**：国内期货 K 线、全球期货实时行情与 K 线、期货库存数据
-- ✅ **期权数据**：中金所股指期权、上交所 ETF 期权、商品期权的报价 / K 线 / 分钟行情
-- ✅ **资金流向**（个股/大盘/排名/板块）、**盘口大单**、**涨停板池**、**盘口异动** 等扩展数据
-- ✅ **沪深港通 / 北向资金**（分时、汇总、持股排行、历史、个股持仓）
-- ✅ **龙虎榜**（详情、个股统计、机构买卖、营业部排行、席位明细）
-- ✅ **大宗交易** + **融资融券** 全套数据
-- ✅ 获取全部 **A 股代码列表**（5000+ 只股票）和批量获取**全市场行情**（内置并发控制）
-- ✅ 支持 **provider 级重试 / 限流 / 熔断策略覆盖**，兼容旧的全局请求配置
-- ✅ **AI / MCP 就绪** — 配套 [stock-sdk-mcp](https://www.npmjs.com/package/stock-sdk-mcp) MCP Server，一行命令接入 Cursor / Claude / Gemini 等 AI 工具
-
-## 市场支持矩阵
-
-不同市场的能力覆盖度差异较大，下表帮你快速判断 SDK 是否覆盖你的场景。
-
-- ✅ 已支持
-- ⚠️ 部分支持 / 限制见备注
-- ❌ 暂未实现（市场有此能力或存在数据源，SDK 后续可补）
-- — 概念不适用（该市场 / 产品本身不存在此能力，如基金不会涨停、期货合约无分红）
-
-| 能力 | A 股 | 港股 | 美股 | 公募基金 | 期货 | 期权 |
-|------|:----:|:----:|:----:|:--------:|:----:|:----:|
-| 实时行情 | ✅ | ✅ | ✅ | ✅ | ✅ 全球期货 | ✅ ETF / 中金所 / 商品 |
-| 历史 K 线（日/周/月） | ✅ | ✅ | ✅ | ⚠️ 场内 ETF/LOF（走 `getHistoryKline`） | ✅ 国内 + 全球 | ✅ |
-| 分钟 K 线（5/15/30/60） | ✅ | ✅ `getHKMinuteKline` | ✅ `getUSMinuteKline` | ⚠️ 场内 ETF/LOF（走 `getMinuteKline`） | ❌ | ❌ |
-| 当日分时（1 分钟） | ✅ | ✅ `getHKMinuteKline` (period='1') | ✅ `getUSMinuteKline` (period='1') | ⚠️ 场内 ETF/LOF | ❌ | ✅ ETF 期权 |
-| 分红派送 | ✅ | ❌ | ❌ | ✅ 基金 + ETF（`getFundDividendList`） | — | — |
-| 资金流向 | ✅ 个股/大盘/排名/板块 | ❌ | ❌ | — | — | — |
-| 板块（行业 / 概念） | ✅ | ❌ | ❌ | ❌ | — | — |
-| 龙虎榜 | ✅ | — | — | — | — | ✅ 期权龙虎榜 |
-| 沪深港通 / 北向资金 | ✅ 北向 | ✅ 南向 | — | — | — | — |
-| 大宗交易 | ✅ | ❌ | ❌ | — | — | — |
-| 融资融券 | ✅ | — | — | — | — | — |
-| 涨停板 / 盘口异动 | ✅ | — | — | — | — | — |
-| 全市场代码列表 | ✅ 5000+ | ✅ | ✅ | ✅ | ❌ | ❌ |
-| 批量行情 | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
-| 库存数据 | — | — | — | — | ✅ 国内 + COMEX | — |
-| 交易日历 | ✅ + `isTradingDay()` 等工具 | ⚠️ 仅市场状态判断（按周一-周五） | ⚠️ 仅市场状态判断（按周一-周五） | — | — | — |
+- ✅ **零依赖**，浏览器 + Node.js 18+ 双端运行；同时提供 **ESM** 和 **CommonJS**
+- ✅ **命名空间 API**：`sdk.quotes.cn()` / `sdk.kline.cn()` / `sdk.options.etf.dailyKline()`，按领域分组、IDE 自动补全友好
+- ✅ **统一符号模型**：`string` 一等公民，`sh600519` / `600519` / `600519.SH` / `00700` / `hk00700` / `AAPL` / `105.AAPL` 等写法容错解析
+- ✅ **A 股 / 港股 / 美股 / 公募基金**实时行情、历史 K 线（日/周/月）、分钟 K 线（1/5/15/30/60）、当日分时
+- ✅ **技术指标**：MA / MACD / BOLL / KDJ / RSI / WR / BIAS / CCI / ATR / OBV / ROC / DMI / SAR / KC
+- ✅ **信号 / 选股 / 回测**：`calcSignals`（金叉死叉/超买超卖等事件识别）、链式选股器、本地回测
+- ✅ **期货 / 期权 / 资金流 / 龙虎榜 / 北向 / 大宗交易 / 融资融券 / 涨停板** 等全套扩展数据
+- ✅ **基金深度数据**：历史净值、实时估值、同类排名走势、基金/ETF 分红送配
+- ✅ **subpath 导出**：`stock-sdk/{indicators,signals,symbols,screener,cache,errors}`，纯计算不拖入网络层，tree-shake 友好
+- ✅ **统一错误体系**：对外只抛 `SdkError`，带标准 `code`，可从 `stock-sdk/errors` 导入
+- ✅ **请求治理**：provider 级重试 / 限流 / 熔断 + 可注入 `fetchImpl` / `signal` / 生命周期 `hooks`
+- ✅ **CLI**：`stock-sdk quote 600519` 终端直接取行情
+- ✅ **内置 MCP server**：`stock-sdk mcp` 一行接入 Cursor / Claude / Codex 等 AI 工具（零依赖手写，无 `@modelcontextprotocol/sdk`）
 
-> **数据延迟**：实时行情来自腾讯财经 / 东方财富等公开接口，**非实时撮合**，
-> 通常有数十秒到数分钟延迟。SDK 不适合做高频交易决策。
->
-> **港股 / 美股 K 线类型**：自 v1.9.1 起拆分为 `HKHistoryKline` / `USHistoryKline`，
-> 各自带 `currency` 与时区元信息；老的 `HKUSHistoryKline` 别名仍兼容。
+---
 
 ## 安装
 
 ```bash
+# v2 Beta（命名空间 API / CLI / MCP）
+npm install stock-sdk@beta
+
+# v1 稳定版
 npm install stock-sdk
-# 或
-yarn add stock-sdk
-# 或
-pnpm add stock-sdk
 ```
 
-## 快速开始（10 行 Demo）
+## 快速开始
 
 ```ts
 import { StockSDK } from 'stock-sdk';
 
 const sdk = new StockSDK();
 
-const quotes = await sdk.getSimpleQuotes([
-  'sh000001',
-  'sz000858',
-  'sh600519',
-]);
-
-quotes.forEach(q => {
+// 命名空间 API（v2）— 符号写法容错，'600519' / 'sh600519' / '600519.SH' 都可
+const quotes = await sdk.quotes.cnSimple(['sh000001', 'sz000858', 'sh600519']);
+quotes.forEach((q) => {
   console.log(`${q.name}: ${q.price} (${q.changePercent}%)`);
 });
+
+// 历史 K 线 + 技术指标
+const kline = await sdk.kline.withIndicators('600519', {
+  period: 'daily',
+  indicators: { ma: { periods: [5, 10, 20] }, macd: {} },
+});
+
+// 全市场 A 股行情（5000+ 股票，内置并发控制）
+const all = await sdk.batch.cn({ concurrency: 5 });
+console.log(`共 ${all.length} 只`);
 ```
 
-## 示例：全市场 A 股行情
+> 港股 `'00700'` / `'hk00700'`，美股 `'AAPL'` / `'105.AAPL'`，由 `normalizeSymbol` 统一容错解析。
 
-前端直接一次性获取全市场 A 股行情（5000+股票），无需 Python 或后端服务。
+---
+
+## 命令行（CLI）
+
+安装后即得 `stock-sdk` 命令（或用 `npx`）：
+
+```bash
+# 行情（按代码自动识别市场）
+npx stock-sdk quote 600519 00700 AAPL
+# K 线 + 输出截断
+npx stock-sdk kline 600519 --period weekly --limit 30
+# 带技术指标
+npx stock-sdk indicators 600519 --ma 5,10,20 --macd
+# 搜索
+npx stock-sdk search 茅台
+# 任意命名空间方法直达
+npx stock-sdk quotes cn sh600519 sz000001
+```
+
+默认 JSON 输出，可加 `--format table|csv`、`--pretty`、`--limit N`。
+
+---
+
+## 🤖 AI / MCP 集成
+
+v2 内置零依赖 MCP server，一条命令启动：
+
+```bash
+npx stock-sdk mcp
+```
+
+接入 Cursor / Claude Desktop / Codex / Gemini 等（配置 `mcpServers`）：
+
+```json
+{
+  "mcpServers": {
+    "stock-sdk": {
+      "command": "npx",
+      "args": ["-y", "stock-sdk", "mcp"]
+    }
+  }
+}
+```
+
+环境变量 `STOCK_SDK_MCP_TOOLS=core|full|<逗号分隔工具名>` 控制工具集范围（默认 `core`）。
+
+👉 [完整 MCP 文档](https://stock-sdk-v2.linkdiary.cn/mcp/)
+
+---
+
+## 信号 / 选股 / 回测
 
 ```ts
-const allQuotes = await sdk.getAllAShareQuotes({
-  batchSize: 300,
-  concurrency: 5,
-  onProgress: (completed, total) => {
-    console.log(`进度: ${completed}/${total}`);
-  },
+import { calcSignals } from 'stock-sdk/signals';
+import { screen, backtest } from 'stock-sdk/screener';
+
+// 金叉/死叉/超买超卖等事件识别（基于带指标的 K 线）
+const signals = calcSignals(klineWithIndicators, {
+  ma: { fast: 5, slow: 20 },
+  rsi: {},
 });
 
-console.log(`共获取 ${allQuotes.length} 只股票`);
+// 链式选股（输入任意行情数组，纯本地、无网络）
+const picks = screen(allQuotes)
+  .where((q) => q.pe != null && q.pe < 20)
+  .where((q) => q.changePercent > 3)
+  .sortBy((q) => q.amount)
+  .top(20);
+
+// 本地回测
+const report = backtest({
+  klines,
+  strategy: (bar, i, all) => 'hold', // 返回 'buy' | 'sell' | 'hold'
+});
+console.log(report.totalReturn, report.winRate, report.maxDrawdown);
 ```
 
-## 请求治理与错误码
+---
+
+## 请求治理与错误
 
 ```ts
-import { StockSDK, HttpError, getSdkErrorCode } from 'stock-sdk';
+import { StockSDK } from 'stock-sdk';
+import { HttpError, getSdkErrorCode } from 'stock-sdk/errors';
 
 const sdk = new StockSDK({
   retry: { maxRetries: 2, baseDelay: 500 },
   providerPolicies: {
-    eastmoney: {
-      timeout: 12000,
-      rateLimit: { requestsPerSecond: 3, maxBurst: 3 },
-    },
+    eastmoney: { timeout: 12000, rateLimit: { requestsPerSecond: 3, maxBurst: 3 } },
   },
 });
 
 try {
-  await sdk.getSimpleQuotes(['sh600519']);
+  await sdk.quotes.cnSimple(['sh600519']);
 } catch (error) {
-  if (error instanceof HttpError) {
-    console.log(error.status, error.statusText);
-  }
-
-  console.log(getSdkErrorCode(error)); // HTTP_ERROR / NETWORK_ERROR / TIMEOUT ...
+  // v2 对外只抛 SdkError，带统一 code
+  if (error instanceof HttpError) console.log(error.status, error.statusText);
+  console.log(getSdkErrorCode(error)); // HTTP_ERROR / NETWORK_ERROR / TIMEOUT / ABORTED / PARSE_ERROR ...
 }
 ```
 
-`getSdkErrorCode` 只做标准化识别，不会改变原始错误实例类型。网络错误仍然保持 `TypeError`，超时仍然保持 `AbortError` / `DOMException` 的兼容行为。
+---
 
-## 开发校验命令
+## 子路径导出（subpath）
 
-```bash
-yarn typecheck
-yarn build
-yarn test
-yarn test:integration:smoke
-# 全量集成回归
-yarn test:integration:full
+只用纯计算（指标 / 符号 / 信号 / 选股）时，从 subpath 导入，bundle 不会拖入 `RequestClient` 与所有 provider：
+
+```ts
+import { calcMACD, calcKDJ } from 'stock-sdk/indicators';
+import { normalizeSymbol, toTencentSymbol } from 'stock-sdk/symbols';
+import { calcSignals } from 'stock-sdk/signals';
+import { screen, backtest } from 'stock-sdk/screener';
+import { MemoryCacheStore, cacheThrough } from 'stock-sdk/cache';
+import { SdkError, isSdkError, getSdkErrorCode } from 'stock-sdk/errors';
 ```
 
-## 🤖 AI / MCP 集成
+---
 
-Stock SDK 配套 MCP Server（[stock-sdk-mcp](https://www.npmjs.com/package/stock-sdk-mcp)），可一键接入主流 AI 工具：
+## 市场支持矩阵
 
-| AI 工具 | 配置方式 |
-|---------|---------|
-| Cursor | `~/.cursor/mcp.json` |
-| Claude Desktop | `claude_desktop_config.json` |
-| OpenClaw | `~/.clawdbot/config.yaml` |
-| Codex CLI | `~/.codex/config.json` |
-| Gemini CLI | `~/.gemini/settings.json` |
+不同市场的能力覆盖度差异较大，下表帮你快速判断 SDK 是否覆盖你的场景。
 
-**配置示例：**
+- ✅ 已支持 ｜ ⚠️ 部分支持（见备注）｜ ❌ 暂未实现 ｜ — 概念不适用
 
-```json
-{
-  "mcpServers": {
-    "stock-sdk": {
-      "command": "npx",
-      "args": ["-y", "stock-sdk-mcp"]
-    }
-  }
-}
-```
+| 能力 | A 股 | 港股 | 美股 | 公募基金 | 期货 | 期权 |
+|------|:----:|:----:|:----:|:--------:|:----:|:----:|
+| 实时行情 | ✅ | ✅ | ✅ | ✅ | ✅ 全球期货 | ✅ ETF / 中金所 / 商品 |
+| 历史 K 线（日/周/月） | ✅ | ✅ | ✅ | ⚠️ 场内 ETF/LOF | ✅ 国内 + 全球 | ✅ |
+| 分钟 K 线（5/15/30/60） | ✅ | ✅ `kline.hkMinute` | ✅ `kline.usMinute` | ⚠️ 场内 ETF/LOF | ❌ | ❌ |
+| 当日分时（1 分钟） | ✅ `quotes.timeline` | ✅ `kline.hkMinute`(period='1') | ✅ `kline.usMinute`(period='1') | ⚠️ 场内 ETF/LOF | ❌ | ✅ ETF 期权 |
+| 分红派送 | ✅ | ❌ | ❌ | ✅ 基金 + ETF | — | — |
+| 资金流向 | ✅ 个股/大盘/排名/板块 | ❌ | ❌ | — | — | — |
+| 板块（行业 / 概念） | ✅ | ❌ | ❌ | ❌ | — | — |
+| 龙虎榜 | ✅ | — | — | — | — | ✅ 期权龙虎榜 |
+| 沪深港通 / 北向资金 | ✅ 北向 | ✅ 南向 | — | — | — | — |
+| 大宗交易 / 融资融券 | ✅ | ❌ | ❌ | — | — | — |
+| 涨停板 / 盘口异动 | ✅ | — | — | — | — | — |
+| 全市场代码列表 / 批量行情 | ✅ 5000+ | ✅ | ✅ | ✅ 代码 | ❌ | ❌ |
+| 库存数据 | — | — | — | — | ✅ 国内 + COMEX | — |
+| 交易日历 | ✅ `calendar.*` | ⚠️ 仅市场状态 | ⚠️ 仅市场状态 | — | — | — |
+
+> **数据延迟**：实时行情来自腾讯财经 / 东方财富等公开接口，**非实时撮合**，通常有数十秒到数分钟延迟，不适合高频交易决策。
 
-**内置 4 个专业 AI Skills：** 技术分析 / 智能选股 / 市场概览 / 实时监控
+---
 
-👉 [完整 MCP 文档](https://stock-sdk.linkdiary.cn/mcp/)
+## API 概览（命名空间）
+
+💡 完整 API 见 [官方文档](https://stock-sdk-v2.linkdiary.cn/api/)。v2 全部方法挂在命名空间下：
+
+| 命名空间 | 代表方法 |
+|---|---|
+| `sdk.quotes` | `.cn` / `.cnSimple` / `.hk` / `.us` / `.fund` / `.fundFlow` / `.largeOrder` / `.timeline` |
+| `sdk.codes` | `.cn` / `.us` / `.hk` / `.fund` |
+| `sdk.batch` | `.cn` / `.hk` / `.us` / `.byCodes` / `.raw` |
+| `sdk.kline` | `.cn` / `.cnMinute` / `.hk` / `.hkMinute` / `.us` / `.usMinute` / `.withIndicators` |
+| `sdk.board` | `.industry.*` / `.concept.*`（`list` / `spot` / `constituents` / `kline` / `minuteKline`） |
+| `sdk.options` | `.index.*` / `.etf.*` / `.commodity.*` / `.cffex.*` / `.lhb` |
+| `sdk.futures` | `.kline` / `.globalSpot` / `.globalKline` / `.inventory` / `.comexInventory` … |
+| `sdk.fundFlow` | `.individual` / `.market` / `.rank` / `.sectorRank` / `.sectorHistory` |
+| `sdk.northbound` | `.minute` / `.summary` / `.holdingRank` / `.history` / `.individual` |
+| `sdk.marketEvent` | `.ztPool` / `.stockChanges` / `.boardChanges` |
+| `sdk.dragonTiger` | `.detail` / `.stockStats` / `.institution` / `.branchRank` / `.seatDetail` |
+| `sdk.blockTrade` / `sdk.margin` | 大宗交易 / 融资融券 |
+| `sdk.fund` | `.dividendList` / `.navHistory` / `.estimate` / `.rankHistory` |
+| `sdk.calendar` | `.isTradingDay` / `.nextTradingDay` / `.prevTradingDay` / `.marketStatus` |
+| `sdk.reference` | `.dividendDetail` / `.tradingCalendar` |
+| 顶层 | `sdk.search(keyword)` |
+
+> 指标计算从主包改为 subpath：`import { calcMACD } from 'stock-sdk/indicators'`。
+> 从 v1 扁平 API 迁移？见 [v1 → v2 迁移指南](https://stock-sdk-v2.linkdiary.cn/guide/migration-v1-to-v2)（含完整 `sdk.getXxx()` → `sdk.<ns>.<method>()` 映射表）。
 
 ---
 
-## API 列表
-
-💡 API 详细文档请查阅 [https://stock-sdk.linkdiary.cn/](https://stock-sdk.linkdiary.cn/)
-
-### 实时行情
-
-| 方法 | 说明 |
-|------|------|
-| `getFullQuotes` | A 股/指数全量行情 |
-| `getSimpleQuotes` | A 股/指数简要行情 |
-| `getHKQuotes` | 港股行情 |
-| `getUSQuotes` | 美股行情 |
-| `getFundQuotes` | 公募基金行情 |
-
-### K 线数据
-
-| 方法 | 说明 |
-|------|------|
-| `getHistoryKline` | A 股历史 K 线（日/周/月） |
-| `getHKHistoryKline` | 港股历史 K 线（日/周/月） |
-| `getUSHistoryKline` | 美股历史 K 线（日/周/月） |
-| `getMinuteKline` | A 股分钟 K 线（1/5/15/30/60 分钟） |
-| `getHKMinuteKline` | 港股分钟 K 线（5/15/30/60 分钟）或当日分时（period='1'），v1.10.0+ |
-| `getUSMinuteKline` | 美股分钟 K 线（5/15/30/60 分钟）或当日分时（period='1'），v1.10.0+ |
-| `getTodayTimeline` | A 股当日分时走势 |
-
-### 技术指标
-
-| 方法 | 说明 |
-|------|------|
-| `getKlineWithIndicators` | 获取带技术指标的 K 线数据 |
-| `calcMA` | 计算均线（SMA/EMA/WMA） |
-| `calcMACD` | 计算 MACD |
-| `calcBOLL` | 计算布林带 |
-| `calcKDJ` | 计算 KDJ |
-| `calcRSI` | 计算 RSI |
-| `calcWR` | 计算威廉指标 |
-| `calcBIAS` | 计算乖离率 |
-| `calcCCI` | 计算商品通道指数 |
-| `calcATR` | 计算平均真实波幅 |
-| `calcOBV` | 计算能量潮 |
-| `calcROC` | 计算变动率指标 |
-| `calcDMI` | 计算趋向指标 |
-| `calcSAR` | 计算抛物线转向 |
-| `calcKC` | 计算肯特纳通道 |
-
-### 行业板块
-
-| 方法 | 说明 |
-|------|------|
-| `getIndustryList` | 行业板块名称列表 |
-| `getIndustrySpot` | 行业板块实时行情 |
-| `getIndustryConstituents` | 行业板块成分股 |
-| `getIndustryKline` | 行业板块历史 K 线（日/周/月） |
-| `getIndustryMinuteKline` | 行业板块分时行情（1/5/15/30/60 分钟） |
-
-### 概念板块
-
-| 方法 | 说明 |
-|------|------|
-| `getConceptList` | 概念板块名称列表 |
-| `getConceptSpot` | 概念板块实时行情 |
-| `getConceptConstituents` | 概念板块成分股 |
-| `getConceptKline` | 概念板块历史 K 线（日/周/月） |
-| `getConceptMinuteKline` | 概念板块分时行情（1/5/15/30/60 分钟） |
-
-### 期货行情
-
-| 方法 | 说明 |
-|------|------|
-| `getFuturesKline` | 国内期货历史 K 线（日/周/月） |
-| `getGlobalFuturesSpot` | 全球期货实时行情 |
-| `getGlobalFuturesKline` | 全球期货历史 K 线（日/周/月） |
-| `getFuturesInventorySymbols` | 期货库存品种列表 |
-| `getFuturesInventory` | 期货库存数据 |
-| `getComexInventory` | COMEX 黄金/白银库存 |
-
-### 期权数据
-
-| 方法 | 说明 |
-|------|------|
-| `getIndexOptionSpot` | 中金所股指期权 T 型报价（看涨 + 看跌） |
-| `getIndexOptionKline` | 股指期权合约日 K 线 |
-| `getCFFEXOptionQuotes` | 中金所全部期权实时行情列表 |
-| `getETFOptionMonths` | 上交所 ETF 期权到期月份列表 |
-| `getETFOptionExpireDay` | ETF 期权到期日与剩余天数 |
-| `getETFOptionMinute` | ETF 期权当日分钟行情 |
-| `getETFOptionDailyKline` | ETF 期权历史日 K 线 |
-| `getETFOption5DayMinute` | ETF 期权 5 日分钟行情 |
-| `getCommodityOptionSpot` | 商品期权 T 型报价 |
-| `getCommodityOptionKline` | 商品期权合约日 K 线 |
-| `getOptionLHB` | 期权龙虎榜 |
-
-### 扩展数据
-
-| 方法 | 说明 |
-|------|------|
-| `getFundFlow` | 资金流向（按代码批量查询） |
-| `getPanelLargeOrder` | 盘口大单占比 |
-| `getTradingCalendar` | A 股交易日历 |
-| `getDividendDetail` | 股票分红派送详情 |
-
-### 基金扩展（v1.10.0+）
-
-| 方法 | 说明 |
-|------|------|
-| `getFundDividendList` | 基金 / ETF 分红明细（全市场，按年份分页，可按代码过滤） |
-| `getFundNavHistory` | 基金历史净值（单位 + 累计，全历史一次返回） |
-| `getFundEstimate` | 基金当日实时估值（含 T-1 单位净值 + 盘中估算） |
-| `getFundRankHistory` | 基金同类排名走势（每日近三月排名 + 百分位） |
-
-### 资金流向（深度）
-
-| 方法 | 说明 |
-|------|------|
-| `getIndividualFundFlow` | 个股资金流历史（日/周/月） |
-| `getMarketFundFlow` | 大盘（上证 + 深证）资金流历史 |
-| `getFundFlowRank` | 个股资金流排名（今日 / 3 日 / 5 日 / 10 日） |
-| `getSectorFundFlowRank` | 板块资金流排名（行业 / 概念 / 地域） |
-| `getSectorFundFlowHistory` | 单个板块的历史资金流 |
-
-### 沪深港通 / 北向资金
-
-| 方法 | 说明 |
-|------|------|
-| `getNorthboundMinute` | 北向 / 南向资金分时数据 |
-| `getNorthboundFlowSummary` | 沪深港通市场资金流向汇总 |
-| `getNorthboundHoldingRank` | 北向 / 沪股通 / 深股通持股个股排行 |
-| `getNorthboundHistory` | 北向 / 南向资金历史 |
-| `getNorthboundIndividual` | 个股北向持仓历史 |
-
-### 涨停板 / 盘口异动
-
-| 方法 | 说明 |
-|------|------|
-| `getZTPool` | 涨停 / 昨日涨停 / 强势 / 次新 / 炸板 / 跌停 6 大股池 |
-| `getStockChanges` | 22 种盘口异动（火箭发射 / 大笔买入 / 封涨停 等） |
-| `getBoardChanges` | 当日板块异动详情 |
-
-### 龙虎榜
-
-| 方法 | 说明 |
-|------|------|
-| `getDragonTigerDetail` | 龙虎榜详情（按日期范围） |
-| `getDragonTigerStockStats` | 个股上榜统计（近 1/3/6 月、1 年） |
-| `getDragonTigerInstitution` | 机构买卖统计 |
-| `getDragonTigerBranchRank` | 营业部排行 |
-| `getDragonTigerStockSeatDetail` | 个股某日上榜席位明细（买入榜 + 卖出榜） |
-
-### 大宗交易 / 融资融券
-
-| 方法 | 说明 |
-|------|------|
-| `getBlockTradeMarketStat` | 大宗交易市场每日总览 |
-| `getBlockTradeDetail` | 大宗交易明细 |
-| `getBlockTradeDailyStat` | 大宗交易每日统计（按股票汇总） |
-| `getMarginAccountInfo` | 融资融券账户统计 |
-| `getMarginTargetList` | 融资融券标的明细 |
-
-### 批量查询
-
-| 方法 | 说明 |
-|------|------|
-| `getAShareCodeList` | 获取全部 A 股代码 |
-| `getUSCodeList` | 获取全部美股代码 |
-| `getHKCodeList` | 获取全部港股代码 |
-| `getAllAShareQuotes` | 获取全市场 A 股行情 |
-| `getAllHKShareQuotes` | 获取全市场港股行情 |
-| `getAllUSShareQuotes` | 获取全市场美股行情 |
-| `getAllQuotesByCodes` | 批量获取指定股票行情 |
-
-### 搜索
-
-| 方法 | 说明 |
-|------|------|
-| `search` | 搜索股票代码/名称/拼音 |
-
-搜索结果可配合 `generateSearchExternalLinks(result)` 生成东方财富、雪球外链。
+## 开发校验
+
+```bash
+yarn typecheck
+yarn build
+yarn test
+yarn test:integration:smoke   # 冒烟集成（真实网络）
+yarn test:integration:full    # 全量集成回归
+```
 
 ---
 
@@ -402,7 +299,7 @@ Stock SDK 配套 MCP Server（[stock-sdk-mcp](https://www.npmjs.com/package/stoc
 
 ---
 
-🌐 [官网](https://stock-sdk.linkdiary.cn) | 📦 [NPM](https://www.npmjs.com/package/stock-sdk) | 📖 [GitHub](https://github.com/chengzuopeng/stock-sdk) | 🎮 [在线演示](https://stock-sdk.linkdiary.cn/playground) | 🧭 [Stock Dashboard](https://chengzuopeng.github.io/stock-dashboard/) | 🐛 [Issues](https://github.com/chengzuopeng/stock-sdk/issues)
+🌐 [官网](https://stock-sdk-v2.linkdiary.cn) | 📦 [NPM](https://www.npmjs.com/package/stock-sdk) | 📖 [GitHub](https://github.com/chengzuopeng/stock-sdk) | 🎮 [在线演示](https://stock-sdk-v2.linkdiary.cn/playground) | 🧭 [Stock Dashboard](https://chengzuopeng.github.io/stock-dashboard/) | 🐛 [Issues](https://github.com/chengzuopeng/stock-sdk/issues)
 
 ---
 

package/dist/adapters-C0s5bM8O.d.cts

@@ -0,0 +1,62 @@
+/**
+ * 统一符号模型类型（v2 A1）
+ *
+ * 设计要点：
+ * - `string` 是一等公民，`SymbolRef` 是「带提示的 string」（其 code 也走 normalizeSymbol）
+ * - `NormalizedSymbol` 是 SDK 内部唯一表示，各 provider 适配器只认它
+ */
+/** 交易区域 / 体系（GLOBAL = 海外期货/商品） */
+type Market = 'CN' | 'HK' | 'US' | 'GLOBAL';
+/** 资产类型 */
+type AssetType = 'stock' | 'index' | 'fund' | 'bond' | 'futures' | 'option' | 'board';
+/**
+ * 交易所 / 市场强判别字段。
+ * 股票：SSE/SZSE/BSE/HKEX/NASDAQ/NYSE/AMEX；
+ * 国内期货：SHFE/DCE/CZCE/INE/CFFEX/GFEX；海外期货：COMEX/NYMEX/CBOT/LME。
+ * 允许 string 兜底以容纳未来扩展。
+ */
+type Exchange = 'SSE' | 'SZSE' | 'BSE' | 'HKEX' | 'NASDAQ' | 'NYSE' | 'AMEX' | 'US' | 'SHFE' | 'DCE' | 'CZCE' | 'INE' | 'CFFEX' | 'GFEX' | 'COMEX' | 'NYMEX' | 'CBOT' | 'LME' | (string & {});
+/** 用户入参：裸 string，或「带提示的 string」对象 */
+interface SymbolRef {
+    code: string;
+    market?: Market;
+    assetType?: AssetType;
+    exchange?: Exchange;
+}
+/** SDK 内部统一表示 */
+interface NormalizedSymbol {
+    market: Market;
+    assetType: AssetType;
+    exchange: Exchange;
+    /** 纯代码，无前缀（如 '600519' / '00700' / 'AAPL' / 'IF2412'） */
+    code: string;
+    /** 期货品种（如 'IF' / 'RB'） */
+    variety?: string;
+    /** 原始入参，便于报错与调试 */
+    input: string;
+}
+/** API 接受的符号入参类型 */
+type SymbolInput = string | SymbolRef;
+
+declare function normalizeSymbol(input: SymbolInput, hint?: Partial<SymbolRef>): NormalizedSymbol;
+
+/**
+ * Provider 符号适配器：NormalizedSymbol → 各数据源原生格式（纯函数）
+ *
+ * 仅覆盖股票/指数/基金/板块这类有明确 secid 体系的资产；期货/期权的 secid
+ * 体系不同（且由各自 provider 内联处理），这里对它们显式抛错而非静默兜底，
+ * 避免把海外期货误拼成美股 secid（105.xxx）这类隐蔽错误。
+ */
+
+/**
+ * → 腾讯行情格式：sh600519 / sz000001 / bj920819 / hk00700 / usAAPL
+ */
+declare function toTencentSymbol(ns: NormalizedSymbol): string;
+/**
+ * → 东财 secid：1.600519 / 0.000001 / 116.00700 / 105.AAPL / 90.BK0475（板块）
+ */
+declare function toEastmoneySecid(ns: NormalizedSymbol): string;
+/** → 纯代码（去前缀） */
+declare function toPlainCode(ns: NormalizedSymbol): string;
+
+export { type AssetType as A, type Exchange as E, type Market as M, type NormalizedSymbol as N, type SymbolRef as S, type SymbolInput as a, toEastmoneySecid as b, toPlainCode as c, normalizeSymbol as n, toTencentSymbol as t };