@dshtrading/connector-tencent 0.6.1 → 0.6.2

package/README.md

@@ -1,8 +1,13 @@
 # @dshtrading/connector-tencent
 
-> **状态：已实证（本出口可用）**。2026-08-31 实测：报价（qt.gtimg.cn）与日/周/月 K（web.ifzq.gtimg.cn fqkline/hkfqkline）从本开发出口均可返回真实数据，cn（贵州茅台）+ hk（腾讯控股）真实网络验证 PASS 2/2，证据 `spikes/impl-cn-hk/REPORT.md` 与 `r1/r2/r3-*` 原始文件。
+> **状态：已实证（本出口可用）**。报价（`qt.gtimg.cn`）、日/周/月 K（`web.ifzq.gtimg.cn`
+> `fqkline`/`hkfqkline`）、分钟 K（`ifzq.gtimg.cn` `mkline`）与批量报价均从本开发出口返回真实数据。
+> 证据 `spikes/impl-cn-hk/REPORT.md`、`spikes/impl-tencent-minute/EVIDENCE.md`、
+> `spikes/impl-tencent-quote-batch/EVIDENCE.md`、`spikes/impl-cn-datasource-bench/EVIDENCE.md`。
 
-dsh-trading **cn+hk 双市场切片**市场连接器：经腾讯公共行情端点实现 `@dshtrading/api` 的 `MarketDataService` 契约，并提供 `<market>_get_ticker` / `<market>_get_klines` / `<market>_place_order` 三工具（下单三段闸门与 connector-binance/connector-stooq 同构）。
+dsh-trading **cn+hk 双市场切片**市场连接器：经腾讯公共行情端点实现 `@dshtrading/api` 的
+`MarketDataService` 契约，并提供 `<market>_get_ticker` / `<market>_get_klines` / `<market>_place_order`
+三工具（下单三段闸门与 connector-binance/connector-stooq 同构）。
 
 ## 单包双市场（多实例模式）
 
@@ -13,13 +18,56 @@ dsh-trading **cn+hk 双市场切片**市场连接器：经腾讯公共行情端
 - cn 实例 provide `tradingCnMarketData` + 注册 `cn_get_ticker/cn_get_klines/cn_place_order`；hk 实例 provide `tradingHkMarketData` + `hk_` 三件；
 - isolate 组键 = 对应服务名（preset 挂载硬规则）。
 
+## 配置
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `market` | 必填 | `cn` = A 股，`hk` = 港股（两个实例各写一行） |
+| `dryRun` | `true` | 下单工具默认模拟 |
+| `liveTrading` | `false` | 实盘总开关；base 审批闸门不得绕过 |
+
+## 上游端点
+
+| 用途 | 端点 |
+|---|---|
+| 报价（单只与批量同端点） | `qt.gtimg.cn/q=<wire[,wire…]>`（`q=` 原生支持逗号列表） |
+| 日/周/月 K（前复权） | `web.ifzq.gtimg.cn/appstock/app/{fqkline,hkfqkline}/get` |
+| 分钟 K（**仅 cn**） | `ifzq.gtimg.cn/appstock/app/kline/mkline`（host **无 `www.`**，带则 301） |
+| 名册检索 | `smartbox.gtimg.cn/s3/?t=all&q=` |
+
+单次请求超时 10 s（`DEFAULT_TIMEOUT_MS`）。
+
+## 周期与能力面
+
+- 周期：cn `5m/30m/1d/1w/1M`（`mkline` / `fqkline` 前复权）；**hk 仅 `1d/1w/1M`**，分钟周期抛
+  `TRADING_UNSUPPORTED_INTERVAL`（公开端点不通）。
+- `getTickers` 一次上游请求取多只标的（键 = 入参原字符串，未收录的整行缺席故跳过，整批失败抛出）；
+  实现不分片，标的数由调用方裁剪。
+- cn 实例独有：`getActiveBuySnapshot`（同一报价行的外盘/内盘，「盘口推断」口径）；
+  该方法在 hk 实例上**本身缺席**，消费方按「方法是否存在」判降级。
+- `getOrderbook`（同一报价行五档）两个实例都声明，但 hk 调用抛 `TRADING_NOT_IMPLEMENTED`
+  ——`r_hk` 行的档位字段恒 0，桥层据此显示「未提供」而不是空盘口。
+- cn/hk 均有：`getTicker` / `getKlines` / `getFundamentals` / `listInstruments` /
+  `subscribeTicker`（快照轮询，最小 250 ms，默认 5 s）。
+
 ## 已知局限（实现时已内置）
 
 - 报价响应为 **GBK 编码**，客户端用 `TextDecoder('gbk')` 解码（Node 全 ICU 内置）；
 - cn/hk 报价字段布局不同：cn 成交量单位是**手**（×100 归一到股）、hk 是**股**；hk 买卖档位字段全 0（`r_hk` 无实时档）→ bid/ask 缺省；
 - hk K 线 wire 前缀是 `hk`（报价才是 `r_hk`）；K 线行字段序是**开收高低量**，hk 行第 7 元素起为分红/回购附加对象（解析丢弃）；
-- 分钟线端点（kline/mkline）本出口不可达，未实现（待验证）；支持 interval = 1d/1w/1M（前权 qfq）。
+- **超限静默降级**（HTTP 仍 200、`code=0`）：`mkline` 的 `count > 800` 降到 320 根；`fqkline` 的 `count ≥ 801` 降到 641 根。
+  实现侧 `Math.min(limit, 800)` 让这两个悬崖在调用面上不可达，代价是**日 K 最多只能取到 801 根（约 3.2 年）**，
+  需要更长历史须换 provider；
+- 北交所不在符号词汇内（只认 `sh`/`sz` 前缀），裸 wire 也只回 09:00:00 / 零成交量的占位行。
 
 ## 合规记录（README 铁律 #5）
 
 **腾讯公共行情端点：公开、无 key、无官方授权；个人使用边界自负**，以腾讯服务条款为准。本仓不缓存、不批量抓取、不再分发行情数据。腾讯不提供交易 API——live 下单路径恒为 `TRADING_NOT_IMPLEMENTED`（券商 API 是后续任务）。
+
+## 出网验证
+
+```sh
+node spikes/impl-cn-hk/r3-real-network-verify.mjs          # cn+hk 链路（报价 + K 线）
+node spikes/impl-tencent-quote-batch/r0-live-probe.mjs     # 批量报价（默认只打印，不落盘）
+./node_modules/.bin/tsx spikes/impl-cn-datasource-bench/bench.mts   # 时延 / 并发 / 批量 / 分钟 K 上限
+```

package/lib/dataplane.d.ts

@@ -2,6 +2,6 @@ import { Config } from "./index.js";
 import { Context } from "@deepseek-ai/cordis";
 //#region src/dataplane.d.ts
 declare const inject: string[];
-declare function apply(ctx: Context, config: Config): void;
+declare function apply(ctx: Context, config?: Config): void;
 //#endregion
-export { apply, inject };
+export { Config, apply, inject };

package/lib/dataplane.js

@@ -1,14 +1,14 @@
-import { TencentMarketDataService, marketDataKey } from "./index.js";
+import { Config, ROUTER_PROVIDER, TencentMarketDataService, marketDataKey } from "./index.js";
 //#region src/dataplane.ts
 const inject = [];
+/** schema 的运行时可调用形态（校验即补默认值）；手工构造 ctx 不传 config 时按 schema 默认值处理。 */
+const withDefaults = (value) => Config(value);
 /** 解析注册表服务；老部署（base/router 未升级）返回 undefined → 调用方回退旧的直接 provide 路径。 */
 function resolveMarketDataRegistry(ctx) {
 	const candidate = ctx.get?.("tradingMarketDataRegistry", false);
 	return candidate !== void 0 ? candidate : void 0;
 }
-/** 本连接器的路由 provider slug（路由层词汇，docs/exchange-routing.md §2.2）。 */
-const ROUTER_PROVIDER = "tencent";
-function apply(ctx, config) {
+function apply(ctx, config = withDefaults(void 0)) {
 	const market = config.market;
 	const key = marketDataKey(market);
 	const registry = resolveMarketDataRegistry(ctx);
@@ -21,4 +21,4 @@ function apply(ctx, config) {
 	ctx.effect(() => registry.register(market, ROUTER_PROVIDER, service));
 }
 //#endregion
-export { apply, inject };
+export { Config, apply, inject };

package/lib/index.d.ts

@@ -1,7 +1,7 @@
-import { CnTickerExtra, HkTickerExtra, INTERVAL_VOCABULARY, TencentFundamentals, TencentIntervalDef, TencentKlineType, TencentMarket, TencentRestClient, TencentRestOptions, TencentTicker, TradingServiceError, klineDateToEpochMs, minuteKlineTimeToEpochMs, normalizeCnSymbol, normalizeHkSymbol, normalizeSymbol, parseCnOrderbook, toCanonicalTencentSymbol, wallTimeToEpochMs } from "./rest.js";
+import { ACTIVE_BUY_SOURCE, CnTickerExtra, HkTickerExtra, INTERVAL_VOCABULARY, TENCENT_KLINE_MAX_BARS, TencentFundamentals, TencentIntervalDef, TencentKlineType, TencentMarket, TencentRestClient, TencentRestOptions, TencentTicker, TradingServiceError, isoWithOffset, klineDateToEpochMs, minuteKlineTimeToEpochMs, normalizeCnSymbol, normalizeHkSymbol, normalizeSymbol, parseCnActiveBuySnapshot, parseCnOrderbook, tencentKlineCapabilities, toCanonicalTencentSymbol, wallTimeToEpochMs } from "./rest.js";
 import { Context, Service } from "@deepseek-ai/cordis";
 import Schema from "@deepseek-ai/schemastery";
-import { Disposable, Interval, Kline, MarketDataService, Orderbook, StockFundamentals, Ticker } from "@dshtrading/api";
+import { ActiveBuySnapshot, Disposable, Interval, Kline, KlineCapability, MarketDataService, Orderbook, StockFundamentals, Ticker } from "@dshtrading/api";
 //#region src/index.d.ts
 /**
  * Cordis 插件名：`dsh-trading-*` 命名空间（TEMPLATES §8）。**两个 preset 实例共享此
@@ -31,7 +31,16 @@ interface SubscribeTickerOptions {
 declare class TencentMarketDataService extends Service implements MarketDataService {
   private readonly client;
   constructor(ctx: Context, market: MarketOption, options?: TencentRestOptions, name?: string);
+  /** 当日累计主动买盘快照；仅 cn 实例存在（hk 实例为 undefined）。 */
+  getActiveBuySnapshot?: (symbol: string) => Promise<ActiveBuySnapshot>;
   getTicker(symbol: string): Promise<TencentTicker>;
+  /**
+   * 批量最新报价（MarketDataService 可选契约 2026-10-14）：一次上游请求取多只标的，
+   * 自选栏「每拍 N 次请求」降成 1 次（cn / hk 实例同能力，均走同一报价行端点）。
+   * 键=入参原字符串、未知/字段不足的符号跳过、整批失败抛出、不自行分片——语义见
+   * TencentRestClient.getTickers。
+   */
+  getTickers(symbols: string[]): Promise<Record<string, TencentTicker>>;
   /** 基本面快照（同一报价行解析，MarketDataService 可选契约 2026-09-02）。 */
   getFundamentals(symbol: string): Promise<StockFundamentals>;
   /**
@@ -40,6 +49,11 @@ declare class TencentMarketDataService extends Service implements MarketDataServ
    */
   getOrderbook(symbol: string): Promise<Orderbook>;
   getKlines(symbol: string, interval: Interval, limit?: number): Promise<Kline[]>;
+  /**
+   * K 线能力声明（api 可选契约，2026-10-15 跨源 K 线路由）：透传 REST 客户端的本市场口径
+   * （hk 实例不含 5m/30m；深度 = 单请求上限 800）。
+   */
+  klineCapabilities(): readonly KlineCapability[];
   listInstruments(query?: string): Promise<Array<{
     symbol: string;
     name: string;
@@ -86,6 +100,27 @@ interface PlaceOrderToolDeps {
  * `tools/pre-execute` waterfall 统一 ask（S4：headless 下 ask=deny，fail-closed）。
  */
 declare function createPlaceOrderTool(deps: PlaceOrderToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/**
+ * 本连接器在路由层的 provider slug（cn/hk 两个实例共用同一个 slug；
+ * docs/guides/exchange-routing.md §2.2）。
+ */
+declare const ROUTER_PROVIDER = "tencent";
+/**
+ * 路由闸门（互斥纪律）：preset 平面的同市场连接器行挂在**同一个**
+ * `cordis:group + isolate` realm 里（`isolate: { tradingCnMarketData: true }` 的
+ * label=true → loader 给该组一个 LocalRealm、组内子行共用，见 cordis-plugin-loader
+ * 的 `isolate()`），因此任意时刻只能有一个 provider 真正 provide 市场服务键——每个
+ * provider 自己按路由让位。
+ *
+ * 缺这道闸门时：用户把 cn/hk 路由切到别家（如 eastmoney），腾讯实例仍无条件 provide →
+ * 后挂载的那行抛 `service "tradingCnMarketData" has been registered at
+ * <dsh-trading-tencent>` → 整个 agent preset 判 invalid，新建会话直接失败
+ * （2026-10-14 实测复现）。
+ *
+ * 无 router 服务的老部署（或手搓 ctx 的单测）→ 放行，保持旧的单 provider 行为；
+ * 与 eastmoney/xysz/qmt/tushare/akshare 的 `routeAllows` 同款语义。
+ */
+declare function routeAllows(ctx: Context, market: MarketOption): boolean;
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { CnTickerExtra, Config, HkTickerExtra, INTERVAL_VOCABULARY, MarketOption, OrderGateVerdict, PlaceOrderArgs, PlaceOrderToolDeps, SubscribeTickerOptions, TRADING_CN_MARKET_DATA_KEY, TRADING_HK_MARKET_DATA_KEY, TencentFundamentals, TencentIntervalDef, TencentKlineType, TencentMarket, TencentMarketDataService, TencentRestClient, TencentRestOptions, TencentTicker, TradingServiceError, apply, buildDryRunReceipt, createPlaceOrderTool, evaluateOrderGate, inject, klineDateToEpochMs, marketDataKey, minuteKlineTimeToEpochMs, name, normalizeCnSymbol, normalizeHkSymbol, normalizeSymbol, parseCnOrderbook, toCanonicalTencentSymbol, wallTimeToEpochMs };
+export { ACTIVE_BUY_SOURCE, CnTickerExtra, Config, HkTickerExtra, INTERVAL_VOCABULARY, MarketOption, OrderGateVerdict, PlaceOrderArgs, PlaceOrderToolDeps, ROUTER_PROVIDER, SubscribeTickerOptions, TENCENT_KLINE_MAX_BARS, TRADING_CN_MARKET_DATA_KEY, TRADING_HK_MARKET_DATA_KEY, TencentFundamentals, TencentIntervalDef, TencentKlineType, TencentMarket, TencentMarketDataService, TencentRestClient, TencentRestOptions, TencentTicker, TradingServiceError, apply, buildDryRunReceipt, createPlaceOrderTool, evaluateOrderGate, inject, isoWithOffset, klineDateToEpochMs, marketDataKey, minuteKlineTimeToEpochMs, name, normalizeCnSymbol, normalizeHkSymbol, normalizeSymbol, parseCnActiveBuySnapshot, parseCnOrderbook, routeAllows, tencentKlineCapabilities, toCanonicalTencentSymbol, wallTimeToEpochMs };

package/lib/index.js

@@ -1,4 +1,4 @@
-import { INTERVAL_VOCABULARY, TencentRestClient, TradingServiceError, klineDateToEpochMs, minuteKlineTimeToEpochMs, normalizeCnSymbol, normalizeHkSymbol, normalizeSymbol, parseCnOrderbook, toCanonicalTencentSymbol, wallTimeToEpochMs } from "./rest.js";
+import { ACTIVE_BUY_SOURCE, INTERVAL_VOCABULARY, TENCENT_KLINE_MAX_BARS, TencentRestClient, TradingServiceError, isoWithOffset, klineDateToEpochMs, minuteKlineTimeToEpochMs, normalizeCnSymbol, normalizeHkSymbol, normalizeSymbol, parseCnActiveBuySnapshot, parseCnOrderbook, tencentKlineCapabilities, toCanonicalTencentSymbol, wallTimeToEpochMs } from "./rest.js";
 import { liveTradingEnabled } from "@dshtrading/authority";
 import { Service } from "@deepseek-ai/cordis";
 import { defineTool } from "@deepseek-ai/dsh-tools";
@@ -51,10 +51,20 @@ var TencentMarketDataService = class extends Service {
 	constructor(ctx, market, options = {}, name = TRADING_CN_MARKET_DATA_KEY) {
 		super(ctx, name);
 		this.client = new TencentRestClient(market, options);
+		if (market === "cn") this.getActiveBuySnapshot = (symbol) => this.client.getActiveBuySnapshot(symbol);
 	}
 	getTicker(symbol) {
 		return this.client.getTicker(symbol);
 	}
+	/**
+	* 批量最新报价（MarketDataService 可选契约 2026-10-14）：一次上游请求取多只标的，
+	* 自选栏「每拍 N 次请求」降成 1 次（cn / hk 实例同能力，均走同一报价行端点）。
+	* 键=入参原字符串、未知/字段不足的符号跳过、整批失败抛出、不自行分片——语义见
+	* TencentRestClient.getTickers。
+	*/
+	getTickers(symbols) {
+		return this.client.getTickers(symbols);
+	}
 	/** 基本面快照（同一报价行解析，MarketDataService 可选契约 2026-09-02）。 */
 	getFundamentals(symbol) {
 		return this.client.getFundamentals(symbol);
@@ -69,6 +79,13 @@ var TencentMarketDataService = class extends Service {
 	getKlines(symbol, interval, limit) {
 		return this.client.getKlines(symbol, interval, limit);
 	}
+	/**
+	* K 线能力声明（api 可选契约，2026-10-15 跨源 K 线路由）：透传 REST 客户端的本市场口径
+	* （hk 实例不含 5m/30m；深度 = 单请求上限 800）。
+	*/
+	klineCapabilities() {
+		return this.client.klineCapabilities();
+	}
 	listInstruments(query) {
 		return this.client.listInstruments(query);
 	}
@@ -211,8 +228,34 @@ function createPlaceOrderTool(deps) {
 		}
 	});
 }
+/**
+* 本连接器在路由层的 provider slug（cn/hk 两个实例共用同一个 slug；
+* docs/guides/exchange-routing.md §2.2）。
+*/
+const ROUTER_PROVIDER = "tencent";
+/**
+* 路由闸门（互斥纪律）：preset 平面的同市场连接器行挂在**同一个**
+* `cordis:group + isolate` realm 里（`isolate: { tradingCnMarketData: true }` 的
+* label=true → loader 给该组一个 LocalRealm、组内子行共用，见 cordis-plugin-loader
+* 的 `isolate()`），因此任意时刻只能有一个 provider 真正 provide 市场服务键——每个
+* provider 自己按路由让位。
+*
+* 缺这道闸门时：用户把 cn/hk 路由切到别家（如 eastmoney），腾讯实例仍无条件 provide →
+* 后挂载的那行抛 `service "tradingCnMarketData" has been registered at
+* <dsh-trading-tencent>` → 整个 agent preset 判 invalid，新建会话直接失败
+* （2026-10-14 实测复现）。
+*
+* 无 router 服务的老部署（或手搓 ctx 的单测）→ 放行，保持旧的单 provider 行为；
+* 与 eastmoney/xysz/qmt/tushare/akshare 的 `routeAllows` 同款语义。
+*/
+function routeAllows(ctx, market) {
+	const router = ctx.get?.("tradingMarketRouter", false);
+	if (router === void 0) return true;
+	return router.activeProvider(market) === ROUTER_PROVIDER;
+}
 function apply(ctx, config) {
 	const market = config.market;
+	if (!routeAllows(ctx, market)) return;
 	const key = marketDataKey(market);
 	new TencentMarketDataService(ctx, market, {}, key);
 	ctx.inject([key], (ctx) => {
@@ -279,4 +322,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { Config, INTERVAL_VOCABULARY, TRADING_CN_MARKET_DATA_KEY, TRADING_HK_MARKET_DATA_KEY, TencentMarketDataService, TencentRestClient, TradingServiceError, apply, buildDryRunReceipt, createPlaceOrderTool, evaluateOrderGate, inject, klineDateToEpochMs, marketDataKey, minuteKlineTimeToEpochMs, name, normalizeCnSymbol, normalizeHkSymbol, normalizeSymbol, parseCnOrderbook, toCanonicalTencentSymbol, wallTimeToEpochMs };
+export { ACTIVE_BUY_SOURCE, Config, INTERVAL_VOCABULARY, ROUTER_PROVIDER, TENCENT_KLINE_MAX_BARS, TRADING_CN_MARKET_DATA_KEY, TRADING_HK_MARKET_DATA_KEY, TencentMarketDataService, TencentRestClient, TradingServiceError, apply, buildDryRunReceipt, createPlaceOrderTool, evaluateOrderGate, inject, isoWithOffset, klineDateToEpochMs, marketDataKey, minuteKlineTimeToEpochMs, name, normalizeCnSymbol, normalizeHkSymbol, normalizeSymbol, parseCnActiveBuySnapshot, parseCnOrderbook, routeAllows, tencentKlineCapabilities, toCanonicalTencentSymbol, wallTimeToEpochMs };

package/lib/rest.d.ts

@@ -1,4 +1,4 @@
-import { Interval, Kline, Orderbook, StockFundamentals, Ticker, TradingErrorCode } from "@dshtrading/api";
+import { ActiveBuySnapshot, Interval, Kline, KlineCapability, Orderbook, StockFundamentals, Ticker, TradingErrorCode } from "@dshtrading/api";
 //#region src/rest.d.ts
 /** api 包 TradingError 契约的运行时 Error 实现。 */
 declare class TradingServiceError extends Error {
@@ -33,6 +33,19 @@ interface TencentIntervalDef {
 }
 /** 工具 parameters enum 用：受支持 interval 词汇。 */
 declare const INTERVAL_VOCABULARY: readonly string[];
+/**
+ * 单请求能承接的根数上限 = 800（2026-10-14 实测，spikes/impl-five-day-1m-probe/EVIDENCE.md §1）：
+ * mkline 端点 count ≤ 800 正常，**超过即静默降级到 320 根**（不是报错），无游标可翻页。
+ * 故 800 是本连接器能诚实承接的 limit 上限（getKlines 也按它 min 裁剪）。
+ */
+declare const TENCENT_KLINE_MAX_BARS = 800;
+/**
+ * K 线能力声明（api 可选契约 klineCapabilities）：本实例能诚实服务的 (周期, 请求深度)。
+ * - 周期集 = INTERVAL_TO_TENCENT 的键；**hk 实例不含 5m/30m**——mkline 端点对港股一律
+ *   `msg: param error`（实测同上 §1），getKlines 也显式抛 TRADING_UNSUPPORTED_INTERVAL；
+ * - 深度 = TENCENT_KLINE_MAX_BARS（上限即截断点，超过就静默降级，不是「多给几根」）。
+ */
+declare function tencentKlineCapabilities(market: TencentMarket): KlineCapability[];
 /**
  * 分钟 K 线时间 `YYYYMMDDHHmm` → epoch ms（Asia/Shanghai 墙钟，12 位紧凑格式）。
  */
@@ -87,6 +100,31 @@ type TencentTicker = Ticker & (CnTickerExtra | HkTickerExtra);
 declare function parseCnOrderbook(fields: string[], timestamp: number): Orderbook;
 /** 基本面快照 = api 契约形（币种单位由市场决定：cn=CNY，hk=HKD，展示层标注）。 */
 type TencentFundamentals = StockFundamentals;
+/** ActiveBuySnapshot.source 的取值（与 api 契约同一事实，只在这里写一次）。 */
+declare const ACTIVE_BUY_SOURCE = "qt.gtimg.cn";
+/**
+ * cn 主动买盘快照解析（字段布局与 parseCnTicker 同一行报价；字段号 2026-10-13 实测
+ * spikes/impl-active-buy/r1-raw-sz002714.gbk）：
+ * 6=成交量=当日总量(**手**) 7=外盘=主动买(手) 8=内盘=主动卖(手)
+ * 30=时间 YYYYMMDDHHMMSS(Asia/Shanghai) 47=涨停价 48=跌停价。
+ *
+ * 口径与失败语义（api ActiveBuySnapshot 契约）：
+ *   - 外盘/内盘是**行情源按盘口推断**的当日累计主动方向，非交易所官方逐笔方向；
+ *   - 总量 <= 0、外盘/内盘字段缺失（空串也算缺失）、非有限或为负 → 抛
+ *     TRADING_EXCHANGE_ERROR，**绝不补 0、绝不返回 NaN**（无读数 ≠ 读数 0）；
+ *   - 占比按「÷当日总量」口径；`total - outer - inner` 的残差是**未归向成交**（集合竞价与
+ *     价间成交计入总量但不计入外/内盘），实测 2026-10-13 为 002714 12/121808 手、
+ *     600519 45/7154 手——不是固定量级，且**不参与修正**（源读数原样返回，见 spike 的
+ *     sumGap 对照）；
+ *   - 涨跌停价字段缺省（指数/ETF）时整字段省略，不用 0 占位。
+ */
+declare function parseCnActiveBuySnapshot(fields: string[], symbol: string, fetchedAt: string): ActiveBuySnapshot;
+/**
+ * epoch ms → ISO 8601 **带偏移**（该时区的墙钟，形如 2026-10-13T09:53:12+08:00）。
+ * 用 Intl 求时区偏移（含夏令时，与 wallTimeToEpochMs 同一套机制）；不用
+ * `Date#toISOString`——它是 UTC `Z` 形，读不出「本地」，且会让同一读数随宿主时区漂移。
+ */
+declare function isoWithOffset(epochMs: number, timeZone: string): string;
 interface TencentRestOptions {
   /** 覆盖报价 base（测试/反代用），末尾不带斜杠。 */
   readonly quoteBaseUrl?: string;
@@ -100,6 +138,8 @@ interface TencentRestOptions {
   readonly timeoutMs?: number;
   /** 注入 fetch 实现；缺省用全局 fetch（Node 22+ 内置）。 */
   readonly fetchImpl?: typeof fetch;
+  /** 时钟注入（单测固定 active-buy 快照的 fetchedAt 用；缺省 Date.now）。 */
+  readonly now?: () => number;
 }
 declare class TencentRestClient {
   #private;
@@ -109,6 +149,19 @@ declare class TencentRestClient {
    * 最新行情快照（同一报价行含基本面字段，getFundamentals 零额外请求成本地解析）。
    */
   getTicker(symbol: string): Promise<TencentTicker>;
+  /**
+   * 批量最新报价（api 可选契约 getTickers，2026-10-14）：自选栏「每拍 N 只标的 N 次请求」
+   * → **一次请求**（`q=` 原生支持逗号列表，实证见 #fetchQuoteRows）。**实现不分片**——
+   * 单次请求的标的数由调用方按 MAX_SYMBOLS 裁剪。
+   *
+   * 契约语义：
+   *   - 键 = **入参原字符串**（调用方按它一一对应），值 Ticker.symbol 仍是市场规范形；
+   *   - 只返回**确实拿到**的标的：入参不可规范化、上游整行缺席、行字段不足、行内时间读数
+   *     坏掉——一律跳过该符号（调用方回落 getTicker 拿它自己的错误码），绝不凑数造假行；
+   *   - 整批 HTTP/网络失败 → 抛出（不做 N 次重试）；
+   *   - 空入参（或全部入参都不可规范化）→ `{}` 且**不发请求**。
+   */
+  getTickers(symbols: string[]): Promise<Record<string, TencentTicker>>;
   /**
    * 基本面与估值快照：与 getTicker 同一行报价（字段布局见 parseCnFundamentals /
    * parseHkFundamentals 注释），无额外端点。估值字段缺省（指数/ETF）时整字段省略。
@@ -121,6 +174,16 @@ declare class TencentRestClient {
    * TRADING_NOT_IMPLEMENTED 上报，桥层转 ok:false（前端显示「未提供」而非空盘口）。
    */
   getOrderbook(symbol: string): Promise<Orderbook>;
+  /**
+   * 当日累计主动买盘快照（api 可选契约 getActiveBuySnapshot，2026-10-13）：与 getTicker
+   * 同一行报价的外盘/内盘字段（cn 布局 6/7/8/30/47/48，见 parseCnActiveBuySnapshot 注释），
+   * 每次调用仍独立发起一次报价请求，不复用 getTicker 的应答。**hk 结构性不支持**——r_hk 行的 7/8 位恒为 0（2026-10-13 实测
+   * spikes/impl-active-buy/r2-raw-hk00700.gbk），直接按 TRADING_NOT_IMPLEMENTED 上报；
+   * 服务层 hk 实例上该方法本身缺席（能力自然缺席，消费方按「方法是否存在」判降级）。
+   */
+  getActiveBuySnapshot(symbol: string): Promise<ActiveBuySnapshot>;
+  /** K 线能力声明（api 可选契约）：本实例市场的诚实 (周期, 请求深度) 清单，口径见 tencentKlineCapabilities。 */
+  klineCapabilities(): readonly KlineCapability[];
   /**
    * K 线（日/周/月走 fqkline 前权 qfq；5m/30m 分钟线走 mkline 端点）。
    * 港股 mkline 端点不支持分钟线，请求 5m/30m 会抛出 TRADING_UNSUPPORTED_INTERVAL。
@@ -137,4 +200,4 @@ declare class TencentRestClient {
   }>>;
 }
 //#endregion
-export { CnTickerExtra, HkTickerExtra, INTERVAL_VOCABULARY, TencentFundamentals, TencentIntervalDef, TencentKlineType, TencentMarket, TencentRestClient, TencentRestOptions, TencentTicker, TradingServiceError, klineDateToEpochMs, minuteKlineTimeToEpochMs, normalizeCnSymbol, normalizeHkSymbol, normalizeSymbol, parseCnOrderbook, toCanonicalTencentSymbol, wallTimeToEpochMs };
+export { ACTIVE_BUY_SOURCE, CnTickerExtra, HkTickerExtra, INTERVAL_VOCABULARY, TENCENT_KLINE_MAX_BARS, TencentFundamentals, TencentIntervalDef, TencentKlineType, TencentMarket, TencentRestClient, TencentRestOptions, TencentTicker, TradingServiceError, isoWithOffset, klineDateToEpochMs, minuteKlineTimeToEpochMs, normalizeCnSymbol, normalizeHkSymbol, normalizeSymbol, parseCnActiveBuySnapshot, parseCnOrderbook, tencentKlineCapabilities, toCanonicalTencentSymbol, wallTimeToEpochMs };

package/lib/rest.js

@@ -95,6 +95,24 @@ const INTERVAL_TO_TENCENT = /* @__PURE__ */ new Map([
 /** 工具 parameters enum 用：受支持 interval 词汇。 */
 const INTERVAL_VOCABULARY = [...INTERVAL_TO_TENCENT.keys()];
 /**
+* 单请求能承接的根数上限 = 800（2026-10-14 实测，spikes/impl-five-day-1m-probe/EVIDENCE.md §1）：
+* mkline 端点 count ≤ 800 正常，**超过即静默降级到 320 根**（不是报错），无游标可翻页。
+* 故 800 是本连接器能诚实承接的 limit 上限（getKlines 也按它 min 裁剪）。
+*/
+const TENCENT_KLINE_MAX_BARS = 800;
+/**
+* K 线能力声明（api 可选契约 klineCapabilities）：本实例能诚实服务的 (周期, 请求深度)。
+* - 周期集 = INTERVAL_TO_TENCENT 的键；**hk 实例不含 5m/30m**——mkline 端点对港股一律
+*   `msg: param error`（实测同上 §1），getKlines 也显式抛 TRADING_UNSUPPORTED_INTERVAL；
+* - 深度 = TENCENT_KLINE_MAX_BARS（上限即截断点，超过就静默降级，不是「多给几根」）。
+*/
+function tencentKlineCapabilities(market) {
+	return [...INTERVAL_TO_TENCENT].filter(([, def]) => !(def.type === "mkline" && market === "hk")).map(([interval]) => ({
+		interval,
+		maxBars: 800
+	}));
+}
+/**
 * 分钟 K 线时间 `YYYYMMDDHHmm` → epoch ms（Asia/Shanghai 墙钟，12 位紧凑格式）。
 */
 function minuteKlineTimeToEpochMs(value, timeZone = "Asia/Shanghai") {
@@ -305,6 +323,119 @@ function parseHkFundamentals(fields, timestamp) {
 		timestamp
 	};
 }
+/** ActiveBuySnapshot.source 的取值（与 api 契约同一事实，只在这里写一次）。 */
+const ACTIVE_BUY_SOURCE = "qt.gtimg.cn";
+/**
+* 行的严格数值读数：空串/纯空白视为**缺失**。
+* `Number('') === 0`——用宽松读数会把「字段缺席」伪装成 0 读数，而「主动买/卖为 0」
+* 本身是有效事实，两者不能混同（本文件此前的 num() 保留给宽容字段用）。
+*/
+function strictNum(value) {
+	if (value === void 0) return void 0;
+	const trimmed = value.trim();
+	if (!trimmed) return void 0;
+	const n = Number(trimmed);
+	return Number.isFinite(n) ? n : void 0;
+}
+/** 占比归一：保留 2 位小数（-0 归一为 0，避免 wire 上出现 `-0`）。 */
+function round2(value) {
+	const r = Math.round(value * 100) / 100;
+	return r === 0 ? 0 : r;
+}
+/** 源字段 30（`YYYYMMDDHHMMSS`，交易所本地墙钟）→ 契约的 date/time 两个字符串。 */
+function splitQuoteTime(value, symbol) {
+	const m = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})$/.exec(value ?? "");
+	if (!m) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Tencent CN active-buy for ${symbol}: invalid quote time field ${JSON.stringify(value ?? null)}`);
+	return {
+		date: `${m[1]}-${m[2]}-${m[3]}`,
+		time: `${m[4]}:${m[5]}:${m[6]}`
+	};
+}
+/**
+* cn 主动买盘快照解析（字段布局与 parseCnTicker 同一行报价；字段号 2026-10-13 实测
+* spikes/impl-active-buy/r1-raw-sz002714.gbk）：
+* 6=成交量=当日总量(**手**) 7=外盘=主动买(手) 8=内盘=主动卖(手)
+* 30=时间 YYYYMMDDHHMMSS(Asia/Shanghai) 47=涨停价 48=跌停价。
+*
+* 口径与失败语义（api ActiveBuySnapshot 契约）：
+*   - 外盘/内盘是**行情源按盘口推断**的当日累计主动方向，非交易所官方逐笔方向；
+*   - 总量 <= 0、外盘/内盘字段缺失（空串也算缺失）、非有限或为负 → 抛
+*     TRADING_EXCHANGE_ERROR，**绝不补 0、绝不返回 NaN**（无读数 ≠ 读数 0）；
+*   - 占比按「÷当日总量」口径；`total - outer - inner` 的残差是**未归向成交**（集合竞价与
+*     价间成交计入总量但不计入外/内盘），实测 2026-10-13 为 002714 12/121808 手、
+*     600519 45/7154 手——不是固定量级，且**不参与修正**（源读数原样返回，见 spike 的
+*     sumGap 对照）；
+*   - 涨跌停价字段缺省（指数/ETF）时整字段省略，不用 0 占位。
+*/
+function parseCnActiveBuySnapshot(fields, symbol, fetchedAt) {
+	const totalLots = strictNum(fields[6]);
+	if (totalLots === void 0 || totalLots <= 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Tencent CN active-buy for ${symbol}: missing/invalid total volume field 6 ${JSON.stringify(fields[6] ?? null)}`);
+	const outerLots = strictNum(fields[7]);
+	const innerLots = strictNum(fields[8]);
+	if (outerLots === void 0 || innerLots === void 0 || outerLots < 0 || innerLots < 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Tencent CN active-buy for ${symbol}: missing/invalid outer/inner volume fields 7/8 ${JSON.stringify(fields[7] ?? null)}/${JSON.stringify(fields[8] ?? null)}`);
+	const { date, time } = splitQuoteTime(fields[30], symbol);
+	const limitUp = strictNum(fields[47]);
+	const limitDown = strictNum(fields[48]);
+	return {
+		symbol,
+		date,
+		time,
+		totalLots,
+		outerLots,
+		innerLots,
+		buySharePct: round2(outerLots / totalLots * 100),
+		netSharePct: round2((outerLots - innerLots) / totalLots * 100),
+		...limitUp !== void 0 ? { limitUp } : {},
+		...limitDown !== void 0 ? { limitDown } : {},
+		source: ACTIVE_BUY_SOURCE,
+		fetchedAt
+	};
+}
+/**
+* epoch ms → ISO 8601 **带偏移**（该时区的墙钟，形如 2026-10-13T09:53:12+08:00）。
+* 用 Intl 求时区偏移（含夏令时，与 wallTimeToEpochMs 同一套机制）；不用
+* `Date#toISOString`——它是 UTC `Z` 形，读不出「本地」，且会让同一读数随宿主时区漂移。
+*/
+function isoWithOffset(epochMs, timeZone) {
+	const parts = new Intl.DateTimeFormat("en-US", {
+		timeZone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit",
+		hour: "2-digit",
+		minute: "2-digit",
+		second: "2-digit",
+		hour12: false
+	}).formatToParts(new Date(epochMs));
+	const get = (type) => parts.find((p) => p.type === type)?.value ?? "00";
+	const hour = String(Number(get("hour")) % 24).padStart(2, "0");
+	const wall = Date.UTC(Number(get("year")), Number(get("month")) - 1, Number(get("day")), Number(hour), Number(get("minute")), Number(get("second")));
+	const offsetMinutes = Math.round((wall - epochMs) / 6e4);
+	const abs = Math.abs(offsetMinutes);
+	const offset = `${offsetMinutes < 0 ? "-" : "+"}${String(Math.floor(abs / 60)).padStart(2, "0")}:${String(abs % 60).padStart(2, "0")}`;
+	return `${get("year")}-${get("month")}-${get("day")}T${hour}:${get("minute")}:${get("second")}${offset}`;
+}
+/**
+* 整段报价响应文本（**已 GBK 解码**）→ wire(小写归一)→字段数组。
+*
+* 每行形如 `v_<wire>="字段~字段~…";\n`——wire 原样可能是 `sh600519` / `r_hk00700` /
+* `r_hkHSI`。**键统一小写归一**：hk 指数 wire 大小写敏感（`r_hkHSI` 有行、`r_hkhsi` 返回
+* `v_pv_none_match="1";`，2026-10-14 实测），请求侧必须原样带大小写，只有查表键归一化；
+* 规范形由调用方持有的 sym 还原，不用响应键（否则指数会变成 `hsi.HK`）。字段切分与单标的
+* 路径同源，批量不另写解析器。
+*
+* 未知代码的两种上游形态都在调用侧处理：单标的短 body `v_pv_none="1"`（键也匹配不上）、
+* 批量响应里**整行缺席**（2026-10-14 实证 `q=sh600519,sz000001,sz159869,sz999999` 只回
+* 3 行，HTTP 200）。
+*/
+function parseQuoteRows(text) {
+	const rows = /* @__PURE__ */ new Map();
+	for (const m of text.matchAll(/v_([A-Za-z0-9_^]+)="([^"]*)"/g)) {
+		const wire = (m[1] ?? "").toLowerCase();
+		if (!rows.has(wire)) rows.set(wire, (m[2] ?? "").split("~"));
+	}
+	return rows;
+}
 const DEFAULT_QUOTE_BASE_URL = "https://qt.gtimg.cn";
 const DEFAULT_KLINE_BASE_URL = "https://web.ifzq.gtimg.cn";
 const DEFAULT_MKLINE_BASE_URL = "https://ifzq.gtimg.cn";
@@ -318,6 +449,7 @@ var TencentRestClient = class {
 	#searchBaseUrl;
 	#timeoutMs;
 	#fetchImpl;
+	#now;
 	constructor(market, options = {}) {
 		this.#market = market;
 		this.#quoteBaseUrl = options.quoteBaseUrl ?? DEFAULT_QUOTE_BASE_URL;
@@ -326,6 +458,7 @@ var TencentRestClient = class {
 		this.#searchBaseUrl = options.searchBaseUrl ?? DEFAULT_SEARCH_BASE_URL;
 		this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
 		this.#fetchImpl = options.fetchImpl ?? ((input, init) => globalThis.fetch(input, init));
+		this.#now = options.now ?? (() => Date.now());
 	}
 	get market() {
 		return this.#market;
@@ -345,7 +478,11 @@ var TencentRestClient = class {
 		if (!res.ok) throw new TradingServiceError(res.status === 429 ? "TRADING_RATE_LIMITED" : "TRADING_EXCHANGE_ERROR", `Tencent ${url}: HTTP ${res.status} ${res.statusText}`);
 		return new Uint8Array(await res.arrayBuffer());
 	}
-	/** 报价 wire 形态：cn=sh600519；hk=r_hk00700（hk K 线另用 hk 前缀，见文件头注）。 */
+	/**
+	* 报价 wire 形态：cn=sh600519；hk=r_hk00700（hk K 线另用 hk 前缀，见文件头注）。
+	* **大小写原样进 URL**：hk 指数 wire 大小写敏感（`r_hkHSI` 有行、`r_hkhsi` 返回
+	* `v_pv_none_match="1";`，2026-10-14 实测），只有响应查表键才小写归一。
+	*/
 	#quoteWireCode(symbol) {
 		return this.#market === "hk" ? `r_hk${symbol}` : symbol;
 	}
@@ -354,22 +491,47 @@ var TencentRestClient = class {
 		return this.#market === "hk" ? `hk${symbol}` : symbol;
 	}
 	/**
-	* 报价行取数（getTicker/getFundamentals 共用）：**GBK 解码**（响应 charset=GBK，
-	* UTF-8 直接乱码）；未知代码返回 `v_pv_none="1"` 之类短 body，按
-	* TRADING_UNSUPPORTED_SYMBOL 上报。返回 `~` 分隔字段数组 + 行情时间戳。
+	* 报价批量取数：一次 `GET /q=<wire,wire,…>`（腾讯端点原生支持逗号列表，2026-10-14 实证
+	* 40 码单请求 HTTP 200 / 17954 B / 180 ms）→ wire(小写)→字段数组。wires 原样拼 URL
+	* （hk 指数大小写敏感，见 #quoteWireCode）；整批失败（网络/超时/HTTP 非 2xx）在
+	* #requestArrayBuffer 里抛出，不在这里吞。
 	*/
-	async #fetchQuoteFields(symbol) {
-		const sym = normalizeSymbol(this.#market, symbol);
-		const url = `${this.#quoteBaseUrl}/q=${this.#quoteWireCode(sym)}`;
-		const bytes = await this.#requestArrayBuffer(url);
-		const text = new TextDecoder("gbk").decode(bytes);
-		const m = /="([^"]*)"/.exec(text);
-		if (!m) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `Tencent ticker for ${sym}: unparseable payload ${JSON.stringify(text.slice(0, 80))} (unknown symbol?)`);
-		const fields = m[1].split("~");
+	async #fetchQuoteRows(wires) {
+		const url = `${this.#quoteBaseUrl}/q=${wires.join(",")}`;
+		return parseQuoteRows(new TextDecoder("gbk").decode(await this.#requestArrayBuffer(url)));
+	}
+	/**
+	* 单行校验（getTicker 与 getTickers **共用**）：字段数 < 35 = 未知/退市代码的短行
+	* （`v_pv_none="1"` 之类）；字段 30 是行情时间（cn=Asia/Shanghai，hk=Asia/Hong_Kong）。
+	*/
+	#validateQuoteRow(fields, sym) {
 		if (fields.length < 35) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `Tencent ticker for ${sym}: payload has ${fields.length} fields, expected >= 35 (unknown/delisted symbol?)`);
 		return {
 			fields,
-			timestamp: this.#market === "hk" ? wallTimeToEpochMs(fields[30] ?? "", "Asia/Hong_Kong") : wallTimeToEpochMs(fields[30] ?? "", "Asia/Shanghai"),
+			timestamp: this.#market === "hk" ? wallTimeToEpochMs(fields[30] ?? "", "Asia/Hong_Kong") : wallTimeToEpochMs(fields[30] ?? "", "Asia/Shanghai")
+		};
+	}
+	/** 已校验的行 → 契约快照（getTicker 与 getTickers 共用同一解析与规范形出口）。 */
+	#tickerFrom(fields, timestamp, sym) {
+		return {
+			...this.#market === "hk" ? parseHkTicker(fields, timestamp) : parseCnTicker(fields, timestamp),
+			symbol: toCanonicalTencentSymbol(this.#market, sym)
+		};
+	}
+	/**
+	* 单标的报价行取数（getTicker/getFundamentals/getOrderbook/getActiveBuySnapshot 共用）：
+	* **GBK 解码**（响应 charset=GBK，UTF-8 直接乱码）；未知代码返回 `v_pv_none="1"` 之类
+	* 短 body（行键匹配不上），按 TRADING_UNSUPPORTED_SYMBOL 上报。返回 `~` 分隔字段数组 +
+	* 行情时间戳 + 规范化符号。
+	*/
+	async #fetchQuoteFields(symbol) {
+		const sym = normalizeSymbol(this.#market, symbol);
+		const wire = this.#quoteWireCode(sym);
+		const rows = await this.#fetchQuoteRows([wire]);
+		const fields = rows.get(wire.toLowerCase());
+		if (fields === void 0) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `Tencent ticker for ${sym}: no row for wire ${wire} (${rows.size} quote rows in payload, unknown symbol?)`);
+		return {
+			...this.#validateQuoteRow(fields, sym),
 			sym
 		};
 	}
@@ -378,10 +540,56 @@ var TencentRestClient = class {
 	*/
 	async getTicker(symbol) {
 		const { fields, timestamp, sym } = await this.#fetchQuoteFields(symbol);
-		return {
-			...this.#market === "hk" ? parseHkTicker(fields, timestamp) : parseCnTicker(fields, timestamp),
-			symbol: toCanonicalTencentSymbol(this.#market, sym)
-		};
+		return this.#tickerFrom(fields, timestamp, sym);
+	}
+	/**
+	* 批量最新报价（api 可选契约 getTickers，2026-10-14）：自选栏「每拍 N 只标的 N 次请求」
+	* → **一次请求**（`q=` 原生支持逗号列表，实证见 #fetchQuoteRows）。**实现不分片**——
+	* 单次请求的标的数由调用方按 MAX_SYMBOLS 裁剪。
+	*
+	* 契约语义：
+	*   - 键 = **入参原字符串**（调用方按它一一对应），值 Ticker.symbol 仍是市场规范形；
+	*   - 只返回**确实拿到**的标的：入参不可规范化、上游整行缺席、行字段不足、行内时间读数
+	*     坏掉——一律跳过该符号（调用方回落 getTicker 拿它自己的错误码），绝不凑数造假行；
+	*   - 整批 HTTP/网络失败 → 抛出（不做 N 次重试）；
+	*   - 空入参（或全部入参都不可规范化）→ `{}` 且**不发请求**。
+	*/
+	async getTickers(symbols) {
+		const tickers = {};
+		if (symbols.length === 0) return tickers;
+		const byWire = /* @__PURE__ */ new Map();
+		for (const symbol of symbols) {
+			let sym;
+			try {
+				sym = normalizeSymbol(this.#market, symbol);
+			} catch {
+				continue;
+			}
+			const wire = this.#quoteWireCode(sym);
+			const key = wire.toLowerCase();
+			const group = byWire.get(key);
+			if (group === void 0) byWire.set(key, {
+				wire,
+				sym,
+				inputs: [symbol]
+			});
+			else if (!group.inputs.includes(symbol)) group.inputs.push(symbol);
+		}
+		if (byWire.size === 0) return tickers;
+		const rows = await this.#fetchQuoteRows([...byWire.values()].map((group) => group.wire));
+		for (const [key, group] of byWire) {
+			const fields = rows.get(key);
+			if (fields === void 0) continue;
+			let ticker;
+			try {
+				const row = this.#validateQuoteRow(fields, group.sym);
+				ticker = this.#tickerFrom(row.fields, row.timestamp, group.sym);
+			} catch {
+				continue;
+			}
+			for (const input of group.inputs) tickers[input] = ticker;
+		}
+		return tickers;
 	}
 	/**
 	* 基本面与估值快照：与 getTicker 同一行报价（字段布局见 parseCnFundamentals /
@@ -409,6 +617,22 @@ var TencentRestClient = class {
 		};
 	}
 	/**
+	* 当日累计主动买盘快照（api 可选契约 getActiveBuySnapshot，2026-10-13）：与 getTicker
+	* 同一行报价的外盘/内盘字段（cn 布局 6/7/8/30/47/48，见 parseCnActiveBuySnapshot 注释），
+	* 每次调用仍独立发起一次报价请求，不复用 getTicker 的应答。**hk 结构性不支持**——r_hk 行的 7/8 位恒为 0（2026-10-13 实测
+	* spikes/impl-active-buy/r2-raw-hk00700.gbk），直接按 TRADING_NOT_IMPLEMENTED 上报；
+	* 服务层 hk 实例上该方法本身缺席（能力自然缺席，消费方按「方法是否存在」判降级）。
+	*/
+	async getActiveBuySnapshot(symbol) {
+		if (this.#market === "hk") throw new TradingServiceError("TRADING_NOT_IMPLEMENTED", "Tencent HK active-buy: r_hk quote row carries no outer/inner (active buy/sell) fields (7/8 always 0) — unavailable for hk");
+		const { fields, sym } = await this.#fetchQuoteFields(symbol);
+		return parseCnActiveBuySnapshot(fields, toCanonicalTencentSymbol("cn", sym), isoWithOffset(this.#now(), "Asia/Shanghai"));
+	}
+	/** K 线能力声明（api 可选契约）：本实例市场的诚实 (周期, 请求深度) 清单，口径见 tencentKlineCapabilities。 */
+	klineCapabilities() {
+		return tencentKlineCapabilities(this.#market);
+	}
+	/**
 	* K 线（日/周/月走 fqkline 前权 qfq；5m/30m 分钟线走 mkline 端点）。
 	* 港股 mkline 端点不支持分钟线，请求 5m/30m 会抛出 TRADING_UNSUPPORTED_INTERVAL。
 	*/
@@ -504,4 +728,4 @@ var TencentRestClient = class {
 	}
 };
 //#endregion
-export { INTERVAL_VOCABULARY, TencentRestClient, TradingServiceError, klineDateToEpochMs, minuteKlineTimeToEpochMs, normalizeCnSymbol, normalizeHkSymbol, normalizeSymbol, parseCnOrderbook, toCanonicalTencentSymbol, wallTimeToEpochMs };
+export { ACTIVE_BUY_SOURCE, INTERVAL_VOCABULARY, TENCENT_KLINE_MAX_BARS, TencentRestClient, TradingServiceError, isoWithOffset, klineDateToEpochMs, minuteKlineTimeToEpochMs, normalizeCnSymbol, normalizeHkSymbol, normalizeSymbol, parseCnActiveBuySnapshot, parseCnOrderbook, tencentKlineCapabilities, toCanonicalTencentSymbol, wallTimeToEpochMs };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dshtrading/connector-tencent",
   "description": "CN + HK dual-market connector plugin for dsh-trading: public market data from Tencent quote/kline endpoints implementing the @dshtrading/api contracts (single package, per-instance market split; no key, no official authorization — personal use boundary at your own discretion)",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -21,12 +21,12 @@
   ],
   "license": "PolyForm-Noncommercial-1.0.0",
   "dependencies": {
-    "@dshtrading/authority": "^0.6.1",
-    "@dshtrading/api": "^0.6.1"
+    "@dshtrading/authority": "^0.6.2",
+    "@dshtrading/api": "^0.6.2"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.0",
-    "@deepseek-ai/dsh-tools": ">=0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": ">=0.2.1-rc.2",
     "@deepseek-ai/schemastery": ">=3.18.0"
   },
   "devDependencies": {