stock-sdk 2.2.2 → 2.4.0

package/README.md

@@ -61,6 +61,7 @@
 - ✅ **统一符号模型**：`string` 一等公民，`sh600519` / `600519` / `600519.SH` / `00700` / `hk00700` / `AAPL` / `105.AAPL` 等写法容错解析；支持中证等特殊指数（`930955` / `H30533` / `HSHCI` / `GDAXI`，[详见符号指南](https://stock-sdk.linkdiary.cn/guide/symbols.html)）
 - ✅ **A 股 / 港股 / 美股 / 公募基金**实时行情、历史 K 线（日/周/月）、分钟 K 线（1/5/15/30/60）、当日分时
 - ✅ **技术指标**：MA / MACD / BOLL / KDJ / RSI / WR / BIAS / CCI / ATR / OBV / ROC / DMI / SAR / KC
+- ✅ **筹码分布（CYQ）**：`sdk.chips.cn/hk/us` 获利比例 / 平均成本 / 90-70 成本区间与集中度 / 筹码峰直方图（东财算法本地计算，零新增数据源）
 - ✅ **信号 / 选股 / 回测**：`calcSignals`（金叉死叉/超买超卖等事件识别）、链式选股器、本地回测
 - ✅ **期货 / 期权 / 资金流 / 龙虎榜 / 北向 / 大宗交易 / 融资融券 / 涨停板** 等全套扩展数据
 - ✅ **基金深度数据**：历史净值、实时估值、同类排名走势、基金/ETF 分红送配、**主题基金**
@@ -154,6 +155,8 @@ npx stock-sdk mcp
 
 环境变量 `STOCK_SDK_MCP_TOOLS=core|full|<逗号分隔工具名>` 控制工具集范围（默认 `core`）。
 
+除工具外还内置 **7 个场景化 AI Skills**（MCP Prompts，如 `analyze_stock` / `screen_stocks` / `diagnose_stock`），支持的客户端可一键触发；`STOCK_SDK_MCP_PROMPTS=core|full|<名单>` 控制技能集（默认 `core`）。详见 [AI Skills 文档](https://stock-sdk.linkdiary.cn/skills/)。
+
 👉 [完整 MCP 文档](https://stock-sdk.linkdiary.cn/mcp/)
 
 ---
@@ -241,6 +244,7 @@ import { SdkError, isSdkError, getSdkErrorCode } from 'stock-sdk/errors';
 | 实时行情 | ✅ | ✅ | ✅ | ✅ | ✅ 全球期货 | ✅ ETF / 中金所 / 商品 |
 | 历史 K 线（日/周/月） | ✅ | ✅ | ✅ | ⚠️ 场内 ETF/LOF | ✅ 国内 + 全球 | ✅ |
 | 分钟 K 线（5/15/30/60） | ✅ | ✅ `kline.hkMinute` | ✅ `kline.usMinute` | ⚠️ 场内 ETF/LOF | ❌ | ❌ |
+| 筹码分布（CYQ） | ✅ `chips.cn` | ✅ `chips.hk` | ✅ `chips.us` | — | — | — |
 | 当日分时（1 分钟） | ✅ `quotes.timeline` | ✅ `kline.hkMinute`(period='1') | ✅ `kline.usMinute`(period='1') | ⚠️ 场内 ETF/LOF | ❌ | ✅ ETF 期权 |
 | 分红派送 | ✅ | ❌ | ❌ | ✅ 基金 + ETF | — | — |
 | 资金流向 | ✅ 个股/大盘/排名/板块 | ❌ | ❌ | — | — | — |
@@ -266,13 +270,14 @@ import { SdkError, isSdkError, getSdkErrorCode } from 'stock-sdk/errors';
 | `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.kline` | `.cn` / `.cnMinute` / `.hk` / `.hkMinute` / `.us` / `.usMinute` / `.withIndicators` / `.signals` |
+| `sdk.chips` | `.cn` / `.hk` / `.us`（筹码分布：获利比例 / 平均成本 / 成本区间 / 筹码峰） |
 | `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.marketEvent` | `.ztPool` / `.stockChanges`(支持多类型 / `'all'`) / `.boardChanges` / `.individualChanges` / `.individualChangesHistory`(个股异动) |
 | `sdk.dragonTiger` | `.detail` / `.stockStats` / `.institution` / `.branchRank` / `.seatDetail` |
 | `sdk.blockTrade` / `sdk.margin` | 大宗交易 / 融资融券 |
 | `sdk.fund` | `.dividendList` / `.navHistory` / `.estimate` / `.rankHistory` / `.theme` |

package/dist/{adapters-BiH4keVd.d.cts → adapters-CZUNRbxi.d.cts}

@@ -74,5 +74,33 @@ declare function toTencentSymbol(ns: NormalizedSymbol): string;
 declare function toEastmoneySecid(ns: NormalizedSymbol): string;
 /** → 纯代码（去前缀） */
 declare function toPlainCode(ns: NormalizedSymbol): string;
+/** {@link tryToTencentSymbols} 的归一结果。 */
+interface TencentSymbolBatch {
+    /** 成功映射的腾讯行情键（按输入顺序，跳过失败项） */
+    keys: string[];
+    /** 无法映射的输入（非法格式 / 腾讯无该市场映射，如 CSI 特殊指数码 930955） */
+    invalid: Array<{
+        code: string;
+        reason: string;
+    }>;
+}
+/**
+ * 行情入口批量容错归一（R7-2/R7-3）：
+ * - market:'CN'：`'600036'`→`'sh600036'`、`'SH600519'`→`'sh600519'`
+ * - market:'HK'：`'00700'`/`'hk00700'`/`'700'`→`'hk00700'`
+ * - market:'US'：`'BABA'`/`'usAAPL'`→`'usBABA'`/`'usAAPL'`
+ *
+ * 【设计决策：逐码容错，不整批抛错】单个代码失败只跳过该码——与行情
+ * 解析侧"无匹配行静默丢弃"的既有语义对齐。理由：
+ * - batch.* 全市场扫描把上游代码表整表灌进来（~5600 码/次），一条脏数据
+ *   不应废掉整批已完成的网络请求；
+ * - SDK 自身支持的特殊指数码（930955/HSHCI 等）在 symbols 层合法但腾讯
+ *   无行情映射（toTencentSymbol 对 CSI 抛错）——这类输入应"跳过"而非
+ *   炸掉整个调用。
+ *
+ * 注意示例按 market 而异：`'00700'` 仅在 market:'HK' 下映射为 `hk00700`，
+ * 在 market:'CN' 下按 A 股推断为 `sz00700`（无此标的，行情侧自然无匹配）。
+ */
+declare function tryToTencentSymbols(codes: string[], market: 'CN' | 'HK' | 'US'): TencentSymbolBatch;
 
-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, EXCHANGE_TO_SECID_PREFIX as d, marketOf as m, normalizeSymbol as n, toTencentSymbol as t };
+export { type AssetType as A, type Exchange as E, type Market as M, type NormalizedSymbol as N, type SymbolRef as S, type TencentSymbolBatch as T, type SymbolInput as a, toEastmoneySecid as b, toPlainCode as c, tryToTencentSymbols as d, EXCHANGE_TO_SECID_PREFIX as e, marketOf as m, normalizeSymbol as n, toTencentSymbol as t };

package/dist/{adapters-BiH4keVd.d.ts → adapters-CZUNRbxi.d.ts}

@@ -74,5 +74,33 @@ declare function toTencentSymbol(ns: NormalizedSymbol): string;
 declare function toEastmoneySecid(ns: NormalizedSymbol): string;
 /** → 纯代码（去前缀） */
 declare function toPlainCode(ns: NormalizedSymbol): string;
+/** {@link tryToTencentSymbols} 的归一结果。 */
+interface TencentSymbolBatch {
+    /** 成功映射的腾讯行情键（按输入顺序，跳过失败项） */
+    keys: string[];
+    /** 无法映射的输入（非法格式 / 腾讯无该市场映射，如 CSI 特殊指数码 930955） */
+    invalid: Array<{
+        code: string;
+        reason: string;
+    }>;
+}
+/**
+ * 行情入口批量容错归一（R7-2/R7-3）：
+ * - market:'CN'：`'600036'`→`'sh600036'`、`'SH600519'`→`'sh600519'`
+ * - market:'HK'：`'00700'`/`'hk00700'`/`'700'`→`'hk00700'`
+ * - market:'US'：`'BABA'`/`'usAAPL'`→`'usBABA'`/`'usAAPL'`
+ *
+ * 【设计决策：逐码容错，不整批抛错】单个代码失败只跳过该码——与行情
+ * 解析侧"无匹配行静默丢弃"的既有语义对齐。理由：
+ * - batch.* 全市场扫描把上游代码表整表灌进来（~5600 码/次），一条脏数据
+ *   不应废掉整批已完成的网络请求；
+ * - SDK 自身支持的特殊指数码（930955/HSHCI 等）在 symbols 层合法但腾讯
+ *   无行情映射（toTencentSymbol 对 CSI 抛错）——这类输入应"跳过"而非
+ *   炸掉整个调用。
+ *
+ * 注意示例按 market 而异：`'00700'` 仅在 market:'HK' 下映射为 `hk00700`，
+ * 在 market:'CN' 下按 A 股推断为 `sz00700`（无此标的，行情侧自然无匹配）。
+ */
+declare function tryToTencentSymbols(codes: string[], market: 'CN' | 'HK' | 'US'): TencentSymbolBatch;
 
-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, EXCHANGE_TO_SECID_PREFIX as d, marketOf as m, normalizeSymbol as n, toTencentSymbol as t };
+export { type AssetType as A, type Exchange as E, type Market as M, type NormalizedSymbol as N, type SymbolRef as S, type TencentSymbolBatch as T, type SymbolInput as a, toEastmoneySecid as b, toPlainCode as c, tryToTencentSymbols as d, EXCHANGE_TO_SECID_PREFIX as e, marketOf as m, normalizeSymbol as n, toTencentSymbol as t };

package/dist/cache.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkWCBK5KYAcjs = require('./chunk-WCBK5KYA.cjs');var _chunkTVIEKKDQcjs = require('./chunk-TVIEKKDQ.cjs');require('./chunk-4VDLQK6F.cjs');exports.MemoryCache = _chunkTVIEKKDQcjs.a; exports.MemoryCacheStore = _chunkWCBK5KYAcjs.a; exports.cacheThrough = _chunkWCBK5KYAcjs.b; exports.clearSharedCaches = _chunkTVIEKKDQcjs.c; exports.createCacheKey = _chunkTVIEKKDQcjs.d; exports.getSharedCache = _chunkTVIEKKDQcjs.b;
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunk6FZNYDNNcjs = require('./chunk-6FZNYDNN.cjs');var _chunk6MCPZDKNcjs = require('./chunk-6MCPZDKN.cjs');require('./chunk-4VDLQK6F.cjs');exports.MemoryCache = _chunk6MCPZDKNcjs.a; exports.MemoryCacheStore = _chunk6FZNYDNNcjs.a; exports.cacheThrough = _chunk6FZNYDNNcjs.b; exports.clearClientScopedCaches = _chunk6MCPZDKNcjs.f; exports.clearSharedCaches = _chunk6MCPZDKNcjs.d; exports.configureSharedCache = _chunk6MCPZDKNcjs.c; exports.createCacheKey = _chunk6MCPZDKNcjs.g; exports.getSharedCache = _chunk6MCPZDKNcjs.b;

package/dist/cache.d.cts

@@ -61,6 +61,14 @@ declare class MemoryCache<T = unknown> {
      * 淘汰最久未访问的缓存（LRU）
      */
     private evictLRU;
+    /** options 浅等价（defaultTTL / maxSize，与构造默认值对齐后比较） */
+    matchesOptions(options: CacheOptions): boolean;
+    /**
+     * 运行时重配（R7-13，配合 {@link configureSharedCache}）。
+     * 新 defaultTTL 只影响后续 set（已存条目的 expireAt 不回溯改写）；
+     * maxSize 调小时立即淘汰至达标。
+     */
+    configure(options: CacheOptions): void;
     /**
      * 带缓存的异步获取
      * 如果缓存存在则返回缓存，否则执行 fetcher 并缓存结果
@@ -68,13 +76,37 @@ declare class MemoryCache<T = unknown> {
     getOrFetch(key: string, fetcher: () => Promise<T>, ttl?: number): Promise<T>;
 }
 /**
- * 获取具名共享缓存
+ * 获取具名共享缓存。
+ *
+ * **first-caller-wins**：`options` 仅在 namespace 首次创建时生效；命中已存在
+ * 的 namespace 时 options 被忽略（与现行配置不等价时警告一次），如需运行时
+ * 调整请用 {@link configureSharedCache}。
  */
 declare function getSharedCache<T = unknown>(namespace: string, options?: CacheOptions): MemoryCache<T>;
 /**
- * 清空所有共享缓存
+ * 显式重配已存在的共享缓存（R7-13）；namespace 不存在返回 `false`。
+ * 语义见 {@link MemoryCache.configure}。
+ */
+declare function configureSharedCache(namespace: string, options: CacheOptions): boolean;
+/**
+ * 清空所有**共享**缓存。
+ *
+ * ⚠️ v2.4.0 起不覆盖实例级缓存：代码表 / 交易日历 / 板块映射 / us-secid
+ * 已迁移为按 client 隔离（R7-11），强刷它们请用 `StockSDK.clearCaches()`。
  */
 declare function clearSharedCaches(): void;
+/**
+ * 清空某 client 的全部作用域缓存（测试 teardown / 手动强制失效用；
+ * 面向 SDK 用户的入口是 `StockSDK.clearCaches()`；不经 StockSDK、直接以
+ * 自建 RequestClient 调 provider 函数的用户，从 `stock-sdk/cache` 导入本函数
+ * 传入该 client 即可 —— v2.4.0 起代码表/日历/板块映射迁到实例级后,
+ * `clearSharedCaches()` 不再覆盖它们。
+ *
+ * 已知残留:清空瞬间仍在途的 getOrFetch 解析完成后会写进被丢弃的旧缓存
+ * 实例(无害,首次新调用会重新解析),清空窗口内的"强制重解析"对该 key
+ * 可能晚一拍生效。
+ */
+declare function clearClientScopedCaches(client: object): void;
 /**
  * 生成缓存键的辅助函数
  */
@@ -123,4 +155,4 @@ declare class MemoryCacheStore implements CacheStore {
  */
 declare function cacheThrough<T>(store: CacheStore, key: string, fetcher: () => Promise<T>, ttl?: number): Promise<T>;
 
-export { type CacheOptions, type CacheStore, type MaybePromise, MemoryCache, MemoryCacheStore, cacheThrough, clearSharedCaches, createCacheKey, getSharedCache };
+export { type CacheOptions, type CacheStore, type MaybePromise, MemoryCache, MemoryCacheStore, cacheThrough, clearClientScopedCaches, clearSharedCaches, configureSharedCache, createCacheKey, getSharedCache };

package/dist/cache.d.ts

@@ -61,6 +61,14 @@ declare class MemoryCache<T = unknown> {
      * 淘汰最久未访问的缓存（LRU）
      */
     private evictLRU;
+    /** options 浅等价（defaultTTL / maxSize，与构造默认值对齐后比较） */
+    matchesOptions(options: CacheOptions): boolean;
+    /**
+     * 运行时重配（R7-13，配合 {@link configureSharedCache}）。
+     * 新 defaultTTL 只影响后续 set（已存条目的 expireAt 不回溯改写）；
+     * maxSize 调小时立即淘汰至达标。
+     */
+    configure(options: CacheOptions): void;
     /**
      * 带缓存的异步获取
      * 如果缓存存在则返回缓存，否则执行 fetcher 并缓存结果
@@ -68,13 +76,37 @@ declare class MemoryCache<T = unknown> {
     getOrFetch(key: string, fetcher: () => Promise<T>, ttl?: number): Promise<T>;
 }
 /**
- * 获取具名共享缓存
+ * 获取具名共享缓存。
+ *
+ * **first-caller-wins**：`options` 仅在 namespace 首次创建时生效；命中已存在
+ * 的 namespace 时 options 被忽略（与现行配置不等价时警告一次），如需运行时
+ * 调整请用 {@link configureSharedCache}。
  */
 declare function getSharedCache<T = unknown>(namespace: string, options?: CacheOptions): MemoryCache<T>;
 /**
- * 清空所有共享缓存
+ * 显式重配已存在的共享缓存（R7-13）；namespace 不存在返回 `false`。
+ * 语义见 {@link MemoryCache.configure}。
+ */
+declare function configureSharedCache(namespace: string, options: CacheOptions): boolean;
+/**
+ * 清空所有**共享**缓存。
+ *
+ * ⚠️ v2.4.0 起不覆盖实例级缓存：代码表 / 交易日历 / 板块映射 / us-secid
+ * 已迁移为按 client 隔离（R7-11），强刷它们请用 `StockSDK.clearCaches()`。
  */
 declare function clearSharedCaches(): void;
+/**
+ * 清空某 client 的全部作用域缓存（测试 teardown / 手动强制失效用；
+ * 面向 SDK 用户的入口是 `StockSDK.clearCaches()`；不经 StockSDK、直接以
+ * 自建 RequestClient 调 provider 函数的用户，从 `stock-sdk/cache` 导入本函数
+ * 传入该 client 即可 —— v2.4.0 起代码表/日历/板块映射迁到实例级后,
+ * `clearSharedCaches()` 不再覆盖它们。
+ *
+ * 已知残留:清空瞬间仍在途的 getOrFetch 解析完成后会写进被丢弃的旧缓存
+ * 实例(无害,首次新调用会重新解析),清空窗口内的"强制重解析"对该 key
+ * 可能晚一拍生效。
+ */
+declare function clearClientScopedCaches(client: object): void;
 /**
  * 生成缓存键的辅助函数
  */
@@ -123,4 +155,4 @@ declare class MemoryCacheStore implements CacheStore {
  */
 declare function cacheThrough<T>(store: CacheStore, key: string, fetcher: () => Promise<T>, ttl?: number): Promise<T>;
 
-export { type CacheOptions, type CacheStore, type MaybePromise, MemoryCache, MemoryCacheStore, cacheThrough, clearSharedCaches, createCacheKey, getSharedCache };
+export { type CacheOptions, type CacheStore, type MaybePromise, MemoryCache, MemoryCacheStore, cacheThrough, clearClientScopedCaches, clearSharedCaches, configureSharedCache, createCacheKey, getSharedCache };

package/dist/cache.js

@@ -1 +1 @@
-import{a as e,b as f}from"./chunk-F3KZXCVO.js";import{a,b,c,d}from"./chunk-DU7MCVLJ.js";import"./chunk-WOT6VMZA.js";export{a as MemoryCache,e as MemoryCacheStore,f as cacheThrough,c as clearSharedCaches,d as createCacheKey,b as getSharedCache};
+import{a as g,b as h}from"./chunk-VKXPLWPL.js";import{a,b,c,d,f as e,g as f}from"./chunk-SMCYQ6NL.js";import"./chunk-WOT6VMZA.js";export{a as MemoryCache,g as MemoryCacheStore,h as cacheThrough,e as clearClientScopedCaches,d as clearSharedCaches,c as configureSharedCache,f as createCacheKey,b as getSharedCache};

package/dist/chip-BbA23rr1.d.cts

@@ -0,0 +1,113 @@
+/**
+ * 筹码计算所需的最小 K 线形状:SDK 的 A 股 / 港股 / 美股历史日 K 线
+ * (`HistoryKline` / `HKHistoryKline` / `USHistoryKline`)均满足。
+ */
+interface ChipKlineLike {
+    /** 日期 YYYY-MM-DD(或任意可标识该 bar 的字符串,原样透传到输出行) */
+    date: string;
+    /** 开盘价 */
+    open: number | null;
+    /** 最高价 */
+    high: number | null;
+    /** 最低价 */
+    low: number | null;
+    /** 收盘价 */
+    close: number | null;
+    /** 换手率 % */
+    turnoverRate: number | null;
+}
+/**
+ * 筹码峰直方图(单日分布形状)
+ */
+interface ChipHistogram {
+    /** 价格档(150 档,低 → 高,已按原算法保留 2 位小数) */
+    prices: number[];
+    /** 各价格档筹码占比(0..1,总和 ≈ 1;按 6 位小数舍入) */
+    ratios: number[];
+}
+/**
+ * `calcChipDistribution` 配置
+ */
+interface ChipDistributionOptions {
+    /**
+     * 分布回看窗口(根)。每日分布只由最近 `range` 根 K 线推演。
+     *
+     * - `120`(默认):与东财 App / 网页筹码分布的显示口径一致;
+     * - `0`:从序列首根全量累计(akshare `stock_cyq_em` 的口径)。
+     *   注意该模式下每行成本为 O(序列长度),长序列请配合 {@link tail}。
+     *
+     * @default 120
+     */
+    range?: number;
+    /**
+     * 仅对输入序列**最后 `tail` 根**产出统计行(输出长度 = min(tail, 输入长度))。
+     * 前面的 bar 仍参与分布推演,只是不生成输出行 —— 用于「取足暖机数据、
+     * 只要尾部结果」的场景,避免 `range: 0` + 长序列时的 O(N²) 全量计算。
+     * 不传时对每根输入 bar 都产出统计行;`tail <= 0` 或 `NaN` 输出空数组,
+     * 非整数向下取整,`Infinity` 等价于不传(输出全部行)。
+     */
+    tail?: number;
+    /**
+     * 是否在输出行上附带筹码峰直方图:
+     * - `false`(默认):不附带;
+     * - `'last'` 或 `true`:仅最后一行附带(看「当前筹码峰」的常见场景);
+     * - `'all'`:每行都附带(数据量为 每行 150 档 × 2 数组,注意体积)。
+     *
+     * @default false
+     */
+    includeHistogram?: boolean | 'last' | 'all';
+    /**
+     * 比例类字段(获利比例 / 集中度)的输出舍入小数位。
+     * 价格类字段(平均成本 / 90-70 成本区间)固定 2 位小数(原算法口径),不受此项影响。
+     *
+     * @default 3
+     */
+    decimals?: number;
+}
+/**
+ * 单日筹码分布统计(字段口径与 akshare `stock_cyq_em` 输出对齐)
+ */
+interface ChipDistributionItem {
+    /** 日期(透传输入 bar 的 date) */
+    date: string;
+    /** 获利比例 0..1(收盘价之下的筹码占比);收盘价缺失或分布退化时为 null */
+    profitRatio: number | null;
+    /** 平均成本(元,累计 50% 筹码处的价格,即中位数成本 —— 东财「平均成本」口径) */
+    avgCost: number | null;
+    /** 90% 筹码成本区间下沿(元) */
+    cost90Low: number | null;
+    /** 90% 筹码成本区间上沿(元) */
+    cost90High: number | null;
+    /** 90% 筹码集中度 (高-低)/(高+低) */
+    concentration90: number | null;
+    /** 70% 筹码成本区间下沿(元) */
+    cost70Low: number | null;
+    /** 70% 筹码成本区间上沿(元) */
+    cost70High: number | null;
+    /** 70% 筹码集中度 */
+    concentration70: number | null;
+    /** 筹码峰直方图(按 includeHistogram 配置附带) */
+    histogram?: ChipHistogram;
+}
+/**
+ * 计算筹码分布(纯函数,零网络)。
+ *
+ * 输入通常为**日 K 线**(需含换手率;SDK 的 `kline.cn` / `kline.hk` / `kline.us`
+ * 返回值可直接使用)。对输入的每根 bar(或 `tail` 限定的尾部)输出一行统计。
+ *
+ * 口径说明:
+ * - `range` 默认 120(东财 App 显示口径);`range: 0` 为 akshare 全量累计口径,
+ *   两者数值不同,对拍 akshare 输出时请显式传 `range: 0`;
+ * - 复权方式由调用方在取 K 线时决定,分布数值随复权口径变化;
+ * - 换手率缺失(null)的 bar 按 0 换手处理(沿用东财 `hsl/100 || 0` 语义);
+ *   OHLC 含 null 的脏行整体跳过,不贡献分布;
+ * - 窗口内累计换手极低(如长期停牌 / 仙股)时分布主要由窗口首日堆叠决定,
+ *   参考价值有限;指数 / 无换手率概念的品种不适用本模型。
+ *
+ * @param klines - K 线序列(按时间升序)
+ * @param options - 见 {@link ChipDistributionOptions}
+ * @returns 每日筹码分布统计(与输入尾部 bar 一一对应)
+ */
+declare function calcChipDistribution(klines: ChipKlineLike[], options?: ChipDistributionOptions): ChipDistributionItem[];
+
+export { type ChipKlineLike as C, type ChipHistogram as a, type ChipDistributionOptions as b, calcChipDistribution as c, type ChipDistributionItem as d };

package/dist/chip-BbA23rr1.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 筹码计算所需的最小 K 线形状:SDK 的 A 股 / 港股 / 美股历史日 K 线
+ * (`HistoryKline` / `HKHistoryKline` / `USHistoryKline`)均满足。
+ */
+interface ChipKlineLike {
+    /** 日期 YYYY-MM-DD(或任意可标识该 bar 的字符串,原样透传到输出行) */
+    date: string;
+    /** 开盘价 */
+    open: number | null;
+    /** 最高价 */
+    high: number | null;
+    /** 最低价 */
+    low: number | null;
+    /** 收盘价 */
+    close: number | null;
+    /** 换手率 % */
+    turnoverRate: number | null;
+}
+/**
+ * 筹码峰直方图(单日分布形状)
+ */
+interface ChipHistogram {
+    /** 价格档(150 档,低 → 高,已按原算法保留 2 位小数) */
+    prices: number[];
+    /** 各价格档筹码占比(0..1,总和 ≈ 1;按 6 位小数舍入) */
+    ratios: number[];
+}
+/**
+ * `calcChipDistribution` 配置
+ */
+interface ChipDistributionOptions {
+    /**
+     * 分布回看窗口(根)。每日分布只由最近 `range` 根 K 线推演。
+     *
+     * - `120`(默认):与东财 App / 网页筹码分布的显示口径一致;
+     * - `0`:从序列首根全量累计(akshare `stock_cyq_em` 的口径)。
+     *   注意该模式下每行成本为 O(序列长度),长序列请配合 {@link tail}。
+     *
+     * @default 120
+     */
+    range?: number;
+    /**
+     * 仅对输入序列**最后 `tail` 根**产出统计行(输出长度 = min(tail, 输入长度))。
+     * 前面的 bar 仍参与分布推演,只是不生成输出行 —— 用于「取足暖机数据、
+     * 只要尾部结果」的场景,避免 `range: 0` + 长序列时的 O(N²) 全量计算。
+     * 不传时对每根输入 bar 都产出统计行;`tail <= 0` 或 `NaN` 输出空数组,
+     * 非整数向下取整,`Infinity` 等价于不传(输出全部行)。
+     */
+    tail?: number;
+    /**
+     * 是否在输出行上附带筹码峰直方图:
+     * - `false`(默认):不附带;
+     * - `'last'` 或 `true`:仅最后一行附带(看「当前筹码峰」的常见场景);
+     * - `'all'`:每行都附带(数据量为 每行 150 档 × 2 数组,注意体积)。
+     *
+     * @default false
+     */
+    includeHistogram?: boolean | 'last' | 'all';
+    /**
+     * 比例类字段(获利比例 / 集中度)的输出舍入小数位。
+     * 价格类字段(平均成本 / 90-70 成本区间)固定 2 位小数(原算法口径),不受此项影响。
+     *
+     * @default 3
+     */
+    decimals?: number;
+}
+/**
+ * 单日筹码分布统计(字段口径与 akshare `stock_cyq_em` 输出对齐)
+ */
+interface ChipDistributionItem {
+    /** 日期(透传输入 bar 的 date) */
+    date: string;
+    /** 获利比例 0..1(收盘价之下的筹码占比);收盘价缺失或分布退化时为 null */
+    profitRatio: number | null;
+    /** 平均成本(元,累计 50% 筹码处的价格,即中位数成本 —— 东财「平均成本」口径) */
+    avgCost: number | null;
+    /** 90% 筹码成本区间下沿(元) */
+    cost90Low: number | null;
+    /** 90% 筹码成本区间上沿(元) */
+    cost90High: number | null;
+    /** 90% 筹码集中度 (高-低)/(高+低) */
+    concentration90: number | null;
+    /** 70% 筹码成本区间下沿(元) */
+    cost70Low: number | null;
+    /** 70% 筹码成本区间上沿(元) */
+    cost70High: number | null;
+    /** 70% 筹码集中度 */
+    concentration70: number | null;
+    /** 筹码峰直方图(按 includeHistogram 配置附带) */
+    histogram?: ChipHistogram;
+}
+/**
+ * 计算筹码分布(纯函数,零网络)。
+ *
+ * 输入通常为**日 K 线**(需含换手率;SDK 的 `kline.cn` / `kline.hk` / `kline.us`
+ * 返回值可直接使用)。对输入的每根 bar(或 `tail` 限定的尾部)输出一行统计。
+ *
+ * 口径说明:
+ * - `range` 默认 120(东财 App 显示口径);`range: 0` 为 akshare 全量累计口径,
+ *   两者数值不同,对拍 akshare 输出时请显式传 `range: 0`;
+ * - 复权方式由调用方在取 K 线时决定,分布数值随复权口径变化;
+ * - 换手率缺失(null)的 bar 按 0 换手处理(沿用东财 `hsl/100 || 0` 语义);
+ *   OHLC 含 null 的脏行整体跳过,不贡献分布;
+ * - 窗口内累计换手极低(如长期停牌 / 仙股)时分布主要由窗口首日堆叠决定,
+ *   参考价值有限;指数 / 无换手率概念的品种不适用本模型。
+ *
+ * @param klines - K 线序列(按时间升序)
+ * @param options - 见 {@link ChipDistributionOptions}
+ * @returns 每日筹码分布统计(与输入尾部 bar 一一对应)
+ */
+declare function calcChipDistribution(klines: ChipKlineLike[], options?: ChipDistributionOptions): ChipDistributionItem[];
+
+export { type ChipKlineLike as C, type ChipHistogram as a, type ChipDistributionOptions as b, calcChipDistribution as c, type ChipDistributionItem as d };