@dshtrading/connector-tencent 0.1.0

package/LICENSE

@@ -0,0 +1,75 @@
+Copyright (c) 2026 zhu1090093659 (dsh-trading)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -0,0 +1,25 @@
+# @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-*` 原始文件。
+
+dsh-trading **cn+hk 双市场切片**市场连接器：经腾讯公共行情端点实现 `@dshtrading/api` 的 `MarketDataService` 契约，并提供 `<market>_get_ticker` / `<market>_get_klines` / `<market>_place_order` 三工具（下单三段闸门与 connector-binance/connector-stooq 同构）。
+
+## 单包双市场（多实例模式）
+
+本包是**一个插件、两个市场实例**（手册 §8，新模式）：
+
+- Config 首键 `market: 'cn' | 'hk'` 分流；插件名统一为 `dsh-trading-tencent`；
+- cn-trader / hk-trader 两个 preset 用**不同行 id**（`dsh-trading-cn-connector` / `dsh-trading-hk-connector`）挂载**同一 bare 包名**，`config.market` 决定实例行为；
+- cn 实例 provide `tradingCnMarketData` + 注册 `cn_get_ticker/cn_get_klines/cn_place_order`；hk 实例 provide `tradingHkMarketData` + `hk_` 三件；
+- isolate 组键 = 对应服务名（preset 挂载硬规则）。
+
+## 已知局限（实现时已内置）
+
+- 报价响应为 **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）。
+
+## 合规记录（README 铁律 #5）
+
+**腾讯公共行情端点：公开、无 key、无官方授权；个人使用边界自负**，以腾讯服务条款为准。本仓不缓存、不批量抓取、不再分发行情数据。腾讯不提供交易 API——live 下单路径恒为 `TRADING_NOT_IMPLEMENTED`（券商 API 是后续任务）。

package/lib/dataplane.d.ts

@@ -0,0 +1,7 @@
+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;
+//#endregion
+export { apply, inject };

package/lib/dataplane.js

@@ -0,0 +1,24 @@
+import { TencentMarketDataService, marketDataKey } from "./index.js";
+//#region src/dataplane.ts
+const inject = [];
+/** 解析注册表服务；老部署（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) {
+	const market = config.market;
+	const key = marketDataKey(market);
+	const registry = resolveMarketDataRegistry(ctx);
+	if (registry === void 0) {
+		new TencentMarketDataService(ctx, market, {}, key);
+		return;
+	}
+	const inner = ctx.isolate(key);
+	const service = new TencentMarketDataService(inner, market, {}, key);
+	ctx.effect(() => registry.register(market, ROUTER_PROVIDER, service));
+}
+//#endregion
+export { apply, inject };

package/lib/index.d.ts

@@ -0,0 +1,86 @@
+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 { Context, Service } from "@deepseek-ai/cordis";
+import Schema from "@deepseek-ai/schemastery";
+import { Disposable, Interval, Kline, MarketDataService, Orderbook, StockFundamentals, Ticker } from "@dshtrading/api";
+//#region src/index.d.ts
+/**
+ * Cordis 插件名：`dsh-trading-*` 命名空间（TEMPLATES §8）。**两个 preset 实例共享此
+ * 插件名**——实例区分靠 preset 行 id（dsh-trading-cn-connector / dsh-trading-hk-connector）
+ * 与 config.market，不再依赖插件名后缀（单包双市场与 crypto/us 的「一市场一插件名」不同）。
+ */
+declare const name = "dsh-trading-tencent";
+type MarketOption = TencentMarket;
+interface Config {
+  /** 市场分流（单包双市场的核心开关）：cn = A 股，hk = 港股。 */
+  market: MarketOption;
+  /** 交易安全闸门（铁律 #3）：true 时下单类工具强制 dry-run。 */
+  dryRun: boolean;
+  /** 实盘总闸门：默认 false；false 时无论 dryRun 与否都拒绝实盘下单 [S4]。 */
+  liveTrading: boolean;
+}
+declare const Config: Schema<Config>;
+/** 需要宿主提供的 Cordis 服务。 */
+declare const inject: string[];
+declare const TRADING_CN_MARKET_DATA_KEY = "tradingCnMarketData";
+declare const TRADING_HK_MARKET_DATA_KEY = "tradingHkMarketData";
+declare function marketDataKey(market: MarketOption): string;
+interface SubscribeTickerOptions {
+  /** 轮询间隔（ms）。subscribeTicker 以快照轮询实现（腾讯公共端点无推送面）。 */
+  readonly intervalMs?: number;
+}
+declare class TencentMarketDataService extends Service implements MarketDataService {
+  private readonly client;
+  constructor(ctx: Context, market: MarketOption, options?: TencentRestOptions, name?: string);
+  getTicker(symbol: string): Promise<TencentTicker>;
+  /** 基本面快照（同一报价行解析，MarketDataService 可选契约 2026-09-02）。 */
+  getFundamentals(symbol: string): Promise<StockFundamentals>;
+  /**
+   * 盘口快照（MarketDataService 可选契约，issue #39）：同一报价行五档字段。
+   * hk 实例结构性不支持（r_hk 行档位全 0，getOrderbook 内按 NOT_IMPLEMENTED 拒绝）。
+   */
+  getOrderbook(symbol: string): Promise<Orderbook>;
+  getKlines(symbol: string, interval: Interval, limit?: number): Promise<Kline[]>;
+  subscribeTicker(symbol: string, cb: (ticker: Ticker) => void, options?: SubscribeTickerOptions): Disposable;
+}
+/** <market>_place_order 参数契约（dryRun 缺省 true）。 */
+interface PlaceOrderArgs {
+  /** A 股 6 位代码（600519/SH600519）或港股 1-5 位代码（00700/700）。 */
+  readonly symbol: string;
+  readonly side: 'BUY' | 'SELL';
+  readonly type: 'MARKET' | 'LIMIT';
+  /** 股数（整股），必须 > 0。 */
+  readonly quantity: number;
+  /** LIMIT 单必填（schema 无法条件必填，execute 内校验），必须 > 0。 */
+  readonly price?: number;
+  /** 缺省视为 true：仅模拟。显式 false 即实盘意图，进入闸门 ①/③。 */
+  readonly dryRun?: boolean;
+}
+/** 闸门判定结果（三条路径与裁决顺序与 crypto/us 同构）。 */
+type OrderGateVerdict = {
+  action: 'reject';
+  code: 'TRADING_LIVE_TRADING_DISABLED';
+  message: string;
+} | {
+  action: 'simulate';
+} | {
+  action: 'live';
+};
+declare function evaluateOrderGate(config: Config, args: PlaceOrderArgs): OrderGateVerdict;
+/** DRY-RUN 回执：模拟成交 + 腾讯最新行情参照（参照取不到不阻断模拟本身）。 */
+declare function buildDryRunReceipt(market: MarketOption, args: PlaceOrderArgs, marketData: Pick<MarketDataService, 'getTicker'>): Promise<string>;
+interface PlaceOrderToolDeps {
+  /** 行情服务（dry-run 回执的市价参照），按接口取用，不直连 HTTP。 */
+  readonly marketData: Pick<MarketDataService, 'getTicker'>;
+  /** 插件配置（market 分流 + dryRun 强制模拟 / liveTrading 总闸门）。 */
+  readonly config: Config;
+}
+/**
+ * <market>_place_order 工具工厂（独立导出便于单测三条闸门路径）。
+ *
+ * 审批不在这里做：dryRun!==true 的调用由 @dshtrading/base 的 gate 插件在
+ * `tools/pre-execute` waterfall 统一 ask（S4：headless 下 ask=deny，fail-closed）。
+ */
+declare function createPlaceOrderTool(deps: PlaceOrderToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
+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 };

package/lib/index.js

@@ -0,0 +1,256 @@
+import { INTERVAL_VOCABULARY, TencentRestClient, TradingServiceError, klineDateToEpochMs, minuteKlineTimeToEpochMs, normalizeCnSymbol, normalizeHkSymbol, normalizeSymbol, parseCnOrderbook, toCanonicalTencentSymbol, wallTimeToEpochMs } from "./rest.js";
+import { Service } from "@deepseek-ai/cordis";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import Schema from "@deepseek-ai/schemastery";
+//#region src/index.ts
+/**
+* Cordis 插件名：`dsh-trading-*` 命名空间（TEMPLATES §8）。**两个 preset 实例共享此
+* 插件名**——实例区分靠 preset 行 id（dsh-trading-cn-connector / dsh-trading-hk-connector）
+* 与 config.market，不再依赖插件名后缀（单包双市场与 crypto/us 的「一市场一插件名」不同）。
+*/
+const name = "dsh-trading-tencent";
+const Config = Schema.object({
+	market: Schema.union(["cn", "hk"]).required(),
+	dryRun: Schema.boolean().default(true),
+	liveTrading: Schema.boolean().default(false)
+});
+/** 需要宿主提供的 Cordis 服务。 */
+const inject = ["tools"];
+const TRADING_CN_MARKET_DATA_KEY = "tradingCnMarketData";
+const TRADING_HK_MARKET_DATA_KEY = "tradingHkMarketData";
+function marketDataKey(market) {
+	return market === "hk" ? TRADING_HK_MARKET_DATA_KEY : TRADING_CN_MARKET_DATA_KEY;
+}
+const SUBSCRIBE_MIN_MS = 250;
+const SUBSCRIBE_DEFAULT_MS = 5e3;
+var TencentMarketDataService = class extends Service {
+	client;
+	constructor(ctx, market, options = {}, name = TRADING_CN_MARKET_DATA_KEY) {
+		super(ctx, name);
+		this.client = new TencentRestClient(market, options);
+	}
+	getTicker(symbol) {
+		return this.client.getTicker(symbol);
+	}
+	/** 基本面快照（同一报价行解析，MarketDataService 可选契约 2026-09-02）。 */
+	getFundamentals(symbol) {
+		return this.client.getFundamentals(symbol);
+	}
+	/**
+	* 盘口快照（MarketDataService 可选契约，issue #39）：同一报价行五档字段。
+	* hk 实例结构性不支持（r_hk 行档位全 0，getOrderbook 内按 NOT_IMPLEMENTED 拒绝）。
+	*/
+	getOrderbook(symbol) {
+		return this.client.getOrderbook(symbol);
+	}
+	getKlines(symbol, interval, limit) {
+		return this.client.getKlines(symbol, interval, limit);
+	}
+	subscribeTicker(symbol, cb, options) {
+		const ms = Math.max(options?.intervalMs ?? SUBSCRIBE_DEFAULT_MS, SUBSCRIBE_MIN_MS);
+		const tick = () => {
+			this.client.getTicker(symbol).then(cb, () => {});
+		};
+		tick();
+		const timer = setInterval(tick, ms);
+		return { dispose: () => clearInterval(timer) };
+	}
+};
+function evaluateOrderGate(config, args) {
+	const requestedDryRun = args.dryRun ?? true;
+	if (!requestedDryRun && !config.liveTrading) return {
+		action: "reject",
+		code: "TRADING_LIVE_TRADING_DISABLED",
+		message: `${config.market}_place_order rejected: the call requests real execution (dryRun=${String(args.dryRun)}) but live trading is disabled (liveTrading=false). Ask the user to enable liveTrading explicitly after confirmation, or keep dryRun=true for a simulated fill.`
+	};
+	if (requestedDryRun || config.dryRun) return { action: "simulate" };
+	return { action: "live" };
+}
+/** 参数校验（模型调用问题抛普通 Error；服务故障才用错误词汇）。 */
+function validatePlaceOrderArgs(market, args) {
+	try {
+		normalizeSymbol(market, args.symbol);
+	} catch (cause) {
+		const expected = market === "hk" ? "an HK code like 00700 or 700" : "a CN A-share code like 600519 or SH600519";
+		throw new Error(`${market}_place_order: invalid symbol ${JSON.stringify(args.symbol)} — expected ${expected}`, { cause });
+	}
+	if (args.side !== "BUY" && args.side !== "SELL") throw new Error(`${market}_place_order: invalid side ${JSON.stringify(args.side)} — expected BUY or SELL`);
+	if (args.type !== "MARKET" && args.type !== "LIMIT") throw new Error(`${market}_place_order: invalid type ${JSON.stringify(args.type)} — expected MARKET or LIMIT`);
+	if (typeof args.quantity !== "number" || !Number.isFinite(args.quantity) || args.quantity <= 0) throw new Error(`${market}_place_order: invalid quantity ${JSON.stringify(args.quantity)} — expected a positive number`);
+	if (args.type === "LIMIT" && (typeof args.price !== "number" || !Number.isFinite(args.price) || args.price <= 0)) throw new Error(`${market}_place_order: LIMIT orders require a positive price`);
+}
+function normalizePlaceOrderArgs(raw) {
+	const args = raw ?? {};
+	const symbol = typeof args.symbol === "string" ? args.symbol.trim() : void 0;
+	return {
+		...args,
+		symbol
+	};
+}
+/** DRY-RUN 回执：模拟成交 + 腾讯最新行情参照（参照取不到不阻断模拟本身）。 */
+async function buildDryRunReceipt(market, args, marketData) {
+	const symbol = normalizeSymbol(market, args.symbol);
+	let reference;
+	try {
+		const ticker = await marketData.getTicker(symbol);
+		reference = {
+			source: "tencent-quote",
+			price: ticker.price,
+			volume: ticker.volume,
+			timestamp: ticker.timestamp
+		};
+	} catch (error) {
+		reference = {
+			source: "tencent-quote",
+			unavailable: error instanceof Error ? error.message : String(error)
+		};
+	}
+	return JSON.stringify({
+		status: "filled",
+		dryRun: true,
+		note: "DRY-RUN — simulated fill; no order was sent to any broker. Tencent is a data source only (no trading API); the reference price is the latest public quote snapshot.",
+		id: `dry-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+		market,
+		symbol,
+		side: args.side.toLowerCase(),
+		type: args.type.toLowerCase(),
+		quantity: args.quantity,
+		...args.type === "LIMIT" ? { price: args.price } : {},
+		reference,
+		timestamp: Date.now()
+	});
+}
+/**
+* <market>_place_order 工具工厂（独立导出便于单测三条闸门路径）。
+*
+* 审批不在这里做：dryRun!==true 的调用由 @dshtrading/base 的 gate 插件在
+* `tools/pre-execute` waterfall 统一 ask（S4：headless 下 ask=deny，fail-closed）。
+*/
+function createPlaceOrderTool(deps) {
+	const market = deps.config.market;
+	return defineTool({
+		name: `${market}_place_order`,
+		description: `Place a ${market === "hk" ? "Hong Kong" : "China A-share"} stock order, or simulate one. dryRun defaults to true and returns a DRY-RUN simulated fill receipt referencing the latest Tencent public quote. Real execution (dryRun=false) requires the plugin liveTrading switch plus user approval, and is not implemented yet in this slice (Tencent has no trading API).`,
+		parameters: {
+			symbol: {
+				type: "string",
+				required: true,
+				description: market === "hk" ? "HK stock code, e.g. 00700 or 700 (normalized internally)" : "CN A-share code, e.g. 600519 / SH600519 / sz000001 (normalized internally)"
+			},
+			side: {
+				type: "string",
+				enum: ["BUY", "SELL"],
+				required: true,
+				description: "Order side"
+			},
+			type: {
+				type: "string",
+				enum: ["MARKET", "LIMIT"],
+				required: true,
+				description: "Order type"
+			},
+			quantity: {
+				type: "number",
+				required: true,
+				description: "Share quantity (whole shares), must be > 0"
+			},
+			price: {
+				type: "number",
+				description: "Limit price; required when type=LIMIT"
+			},
+			dryRun: {
+				type: "boolean",
+				description: "true (default) = simulate only and return a DRY-RUN receipt; false = request real execution (gated by liveTrading and user approval)",
+				default: true
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const args = normalizePlaceOrderArgs(raw);
+			validatePlaceOrderArgs(market, args);
+			const verdict = evaluateOrderGate(deps.config, args);
+			if (verdict.action === "reject") return JSON.stringify({
+				status: "rejected",
+				code: verdict.code,
+				message: verdict.message
+			});
+			if (verdict.action === "simulate") return buildDryRunReceipt(market, args, deps.marketData);
+			throw new TradingServiceError("TRADING_NOT_IMPLEMENTED", `${market}_place_order: live order execution is not implemented in this slice — Tencent provides market data only; a broker API is a follow-up. Keep dryRun=true for simulated fills.`);
+		}
+	});
+}
+function apply(ctx, config) {
+	const market = config.market;
+	const key = marketDataKey(market);
+	new TencentMarketDataService(ctx, market, {}, key);
+	ctx.inject([key], (ctx) => {
+		const marketData = ctx[key];
+		ctx.tools.register(defineTool({
+			name: `${market}_get_ticker`,
+			description: `Get the latest market snapshot for a ${market === "hk" ? "Hong Kong (HKEX)" : "China A-share"} stock via the Tencent public quote endpoint (qt.gtimg.cn). Returns price, open/high/low, prev close, volume (shares) and quote time. No credentials required; Tencent public endpoint, no official authorization — personal use at your own discretion per Tencent terms.`,
+			parameters: { symbol: {
+				type: "string",
+				required: true,
+				description: market === "hk" ? "HK stock code, e.g. 00700 or 700 (normalized internally)" : "CN A-share code, e.g. 600519 / SH600519 / sz000001 (normalized internally)"
+			} },
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{
+					type: "text",
+					text: value
+				}]
+			},
+			async execute(args) {
+				const ticker = await marketData.getTicker(args.symbol);
+				return JSON.stringify(ticker);
+			}
+		}));
+		ctx.tools.register(defineTool({
+			name: `${market}_get_klines`,
+			description: `Get recent OHLCV candles for a ${market === "hk" ? "Hong Kong (HKEX)" : "China A-share"} stock via the Tencent public kline endpoint (cn supports 5m/30m/1d/1w/1M; hk supports 1d/1w/1M forward-adjusted qfq). No credentials required; Tencent public endpoint, no official authorization — personal use at your own discretion per Tencent terms.`,
+			parameters: {
+				symbol: {
+					type: "string",
+					required: true,
+					description: market === "hk" ? "HK stock code, e.g. 00700 or 700 (normalized internally)" : "CN A-share code, e.g. 600519 / SH600519 / sz000001 (normalized internally)"
+				},
+				interval: {
+					type: "string",
+					enum: INTERVAL_VOCABULARY,
+					description: "Kline interval (Tencent-supported subset)",
+					default: "1d"
+				},
+				limit: {
+					type: "integer",
+					description: "Number of most recent candles to return (1-800)",
+					default: 100
+				}
+			},
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{
+					type: "text",
+					text: value
+				}]
+			},
+			async execute(args) {
+				const interval = args.interval ?? "1d";
+				const limit = args.limit ?? 100;
+				const klines = await marketData.getKlines(args.symbol, interval, limit);
+				return JSON.stringify(klines);
+			}
+		}));
+		ctx.tools.register(createPlaceOrderTool({
+			marketData,
+			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 };

package/lib/rest.d.ts

@@ -0,0 +1,129 @@
+import { Interval, Kline, Orderbook, StockFundamentals, Ticker, TradingErrorCode } from "@dshtrading/api";
+//#region src/rest.d.ts
+/** api 包 TradingError 契约的运行时 Error 实现。 */
+declare class TradingServiceError extends Error {
+  readonly code: TradingErrorCode;
+  constructor(code: TradingErrorCode, message: string, cause?: unknown);
+}
+type TencentMarket = 'cn' | 'hk';
+/**
+ * 规范化 A 股符号：接受 `600519` / `SH600519` / `sh600519` / `sz000001`，统一为
+ * 腾讯 wire 形态小写 `<sh|sz><6位数字>`。6/9 开头→sh（沪，含科创板 688），0/3 开头→sz
+ * （深，含创业板 300）。4/8 开头（北交所）不在本切片支持范围。
+ */
+declare function normalizeCnSymbol(symbol: string): string;
+/**
+ * 规范化港股符号：接受 `00700` / `700`（1-5 位数字，不足 5 位左补零，统一为 5 位数字
+ * 形态 `00700`）及 `HSI` / `HSTECH` / `HSCEI` 等指数符号。wire 形态由客户端按端点再加前缀（报价 `r_hk` / K线 `hk`）。
+ */
+declare function normalizeHkSymbol(symbol: string): string;
+/** 按市场规范化符号并返回市场。 */
+declare function normalizeSymbol(market: TencentMarket, symbol: string): string;
+/**
+ * 输出归一 → 规范形（docs/symbol-vocabulary.md）：cn wire 形 sh600519 → 600519.SH；
+ * hk 5 位形 00700 → 00700.HK，指数形 HSI → HSI.HK。下游永远看到市场规范词汇。
+ */
+declare function toCanonicalTencentSymbol(market: TencentMarket, wireOrCode: string): string;
+type TencentKlineType = 'fqkline' | 'mkline';
+interface TencentIntervalDef {
+  readonly type: TencentKlineType;
+  readonly tf: string;
+  readonly key: string;
+  readonly durationMs: number;
+}
+/** 工具 parameters enum 用：受支持 interval 词汇。 */
+declare const INTERVAL_VOCABULARY: readonly string[];
+/**
+ * 分钟 K 线时间 `YYYYMMDDHHmm` → epoch ms（Asia/Shanghai 墙钟，12 位紧凑格式）。
+ */
+declare function minuteKlineTimeToEpochMs(value: string, timeZone?: string): number;
+/** K 线日期 `YYYY-MM-DD` → epoch ms（UTC 当日零点锚定，行情日界语义，与 stooq 映射同构）。 */
+declare function klineDateToEpochMs(date: string): number;
+/**
+ * 交易所当地墙钟 → epoch ms（Intl 求时区偏移，含夏令时；同 stooq easternWallTimeToEpochMs
+ * 的两轮逼近法，泛化时区参数）。cn 报价时间是 `YYYYMMDDHHMMSS`（Asia/Shanghai），
+ * hk 报价时间是 `YYYY/MM/DD HH:MM:SS`（Asia/Hong_Kong）。
+ */
+declare function wallTimeToEpochMs(value: string, timeZone: string): number;
+/** cn 报价扩展字段（Ticker 契约的超集；风控 skill 用涨停/跌停价）。 */
+interface CnTickerExtra {
+  readonly market: 'cn';
+  readonly name: string;
+  readonly prevClose?: number;
+  readonly open?: number;
+  readonly high?: number;
+  readonly low?: number;
+  /** 涨停价（f47）。 */
+  readonly limitUp?: number;
+  /** 跌停价（f48）。 */
+  readonly limitDown?: number;
+  readonly change?: number;
+  readonly changePercent?: number;
+  readonly currency: 'CNY';
+}
+/** hk 报价扩展字段。 */
+interface HkTickerExtra {
+  readonly market: 'hk';
+  readonly name: string;
+  readonly prevClose?: number;
+  readonly open?: number;
+  readonly high?: number;
+  readonly low?: number;
+  readonly change?: number;
+  readonly changePercent?: number;
+  /** 52 周最高（f48）。 */
+  readonly week52High?: number;
+  /** 52 周最低（f49）。 */
+  readonly week52Low?: number;
+  readonly currency: 'HKD';
+}
+type TencentTicker = Ticker & (CnTickerExtra | HkTickerExtra);
+/**
+ * cn 五档盘口解析（issue #39）。字段布局（v_sh600519，与 parseCnTicker 同一行）：
+ * 9=买一价 10=买一量(**手**) … 17=买五价 18=买五量；19=卖一价 20=卖一量 … 27=卖五价
+ * 28=卖五量。档位全 0/缺省时该档丢弃——全部无效时返回空档位（消费方显示空态，
+ * 盘后/集合竞价外时段属正常），不抛错。
+ */
+declare function parseCnOrderbook(fields: string[], timestamp: number): Orderbook;
+/** 基本面快照 = api 契约形（币种单位由市场决定：cn=CNY，hk=HKD，展示层标注）。 */
+type TencentFundamentals = StockFundamentals;
+interface TencentRestOptions {
+  /** 覆盖报价 base（测试/反代用），末尾不带斜杠。 */
+  readonly quoteBaseUrl?: string;
+  /** 覆盖 K 线 base（测试/反代用），末尾不带斜杠。 */
+  readonly klineBaseUrl?: string;
+  /** 覆盖分钟 K 线 base（测试/反代用），末尾不带斜杠。 */
+  readonly mklineBaseUrl?: string;
+  /** 单请求超时（ms），默认 10s。 */
+  readonly timeoutMs?: number;
+  /** 注入 fetch 实现；缺省用全局 fetch（Node 22+ 内置）。 */
+  readonly fetchImpl?: typeof fetch;
+}
+declare class TencentRestClient {
+  #private;
+  constructor(market: TencentMarket, options?: TencentRestOptions);
+  get market(): TencentMarket;
+  /**
+   * 最新行情快照（同一报价行含基本面字段，getFundamentals 零额外请求成本地解析）。
+   */
+  getTicker(symbol: string): Promise<TencentTicker>;
+  /**
+   * 基本面与估值快照：与 getTicker 同一行报价（字段布局见 parseCnFundamentals /
+   * parseHkFundamentals 注释），无额外端点。估值字段缺省（指数/ETF）时整字段省略。
+   */
+  getFundamentals(symbol: string): Promise<TencentFundamentals>;
+  /**
+   * 盘口快照（api 可选契约 getOrderbook，issue #39）：与 getTicker 同一行报价的
+   * 五档字段（cn 布局 fields 9-28，见 parseCnOrderbook）。**hk 结构性不支持**——
+   * r_hk 行买卖档位全 0（2026-08-31 实测，parseHkTicker 注释），直接按
+   * TRADING_NOT_IMPLEMENTED 上报，桥层转 ok:false（前端显示「未提供」而非空盘口）。
+   */
+  getOrderbook(symbol: string): Promise<Orderbook>;
+  /**
+   * K 线（日/周/月走 fqkline 前权 qfq；5m/30m 分钟线走 mkline 端点）。
+   * 港股 mkline 端点不支持分钟线，请求 5m/30m 会抛出 TRADING_UNSUPPORTED_INTERVAL。
+   */
+  getKlines(symbol: string, interval: Interval, limit?: number): Promise<Kline[]>;
+}
+//#endregion
+export { CnTickerExtra, HkTickerExtra, INTERVAL_VOCABULARY, TencentFundamentals, TencentIntervalDef, TencentKlineType, TencentMarket, TencentRestClient, TencentRestOptions, TencentTicker, TradingServiceError, klineDateToEpochMs, minuteKlineTimeToEpochMs, normalizeCnSymbol, normalizeHkSymbol, normalizeSymbol, parseCnOrderbook, toCanonicalTencentSymbol, wallTimeToEpochMs };

package/lib/rest.js

@@ -0,0 +1,449 @@
+//#region src/rest.ts
+/** api 包 TradingError 契约的运行时 Error 实现。 */
+var TradingServiceError = class extends Error {
+	code;
+	constructor(code, message, cause) {
+		super(message);
+		this.name = "TradingServiceError";
+		this.code = code;
+		if (cause !== void 0) this.cause = cause;
+	}
+};
+const CN_SYMBOL_PATTERN = /^(?:(sh|sz)(\d{6})|(\d{6})(?:\.(sh|sz))?)$/;
+const HK_SYMBOL_PATTERN = /^(?:r_hk|hk)?([a-z0-9^]{1,10})(?:\.hk)?$/i;
+/**
+* 规范化 A 股符号：接受 `600519` / `SH600519` / `sh600519` / `sz000001`，统一为
+* 腾讯 wire 形态小写 `<sh|sz><6位数字>`。6/9 开头→sh（沪，含科创板 688），0/3 开头→sz
+* （深，含创业板 300）。4/8 开头（北交所）不在本切片支持范围。
+*/
+function normalizeCnSymbol(symbol) {
+	if (typeof symbol !== "string" || !symbol.trim()) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", "Symbol must be a non-empty string, e.g. 600519 / SH600519 / sz000001");
+	const raw = symbol.trim().toLowerCase();
+	const m = CN_SYMBOL_PATTERN.exec(raw);
+	if (!m) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `Symbol ${JSON.stringify(symbol)} is not a valid CN A-share symbol (expected 6-digit code, optionally SH/SZ prefixed)`);
+	if (m[1]) return `${m[1]}${m[2]}`;
+	const code = m[3];
+	if (m[4]) return `${m[4]}${code}`;
+	return `${code.startsWith("6") || code.startsWith("9") ? "sh" : "sz"}${code}`;
+}
+/**
+* 规范化港股符号：接受 `00700` / `700`（1-5 位数字，不足 5 位左补零，统一为 5 位数字
+* 形态 `00700`）及 `HSI` / `HSTECH` / `HSCEI` 等指数符号。wire 形态由客户端按端点再加前缀（报价 `r_hk` / K线 `hk`）。
+*/
+function normalizeHkSymbol(symbol) {
+	if (typeof symbol !== "string" || !symbol.trim()) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", "Symbol must be a non-empty string, e.g. 00700, 700 or HSI");
+	const m = HK_SYMBOL_PATTERN.exec(symbol.trim().toLowerCase());
+	if (!m) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `Symbol ${JSON.stringify(symbol)} is not a valid HK stock code or index (expected 1-5 digits or index symbol, e.g. 700 / 00700 / HSI)`);
+	const code = m[1] ?? "";
+	if (/^\d+$/.test(code)) return code.padStart(5, "0");
+	return code.toUpperCase();
+}
+/** 按市场规范化符号并返回市场。 */
+function normalizeSymbol(market, symbol) {
+	return market === "hk" ? normalizeHkSymbol(symbol) : normalizeCnSymbol(symbol);
+}
+/**
+* 输出归一 → 规范形（docs/symbol-vocabulary.md）：cn wire 形 sh600519 → 600519.SH；
+* hk 5 位形 00700 → 00700.HK，指数形 HSI → HSI.HK。下游永远看到市场规范词汇。
+*/
+function toCanonicalTencentSymbol(market, wireOrCode) {
+	if (market === "hk") return `${wireOrCode.replace(/^r_hk|^hk/i, "")}.HK`;
+	const m = /^(sh|sz)(\d{6})$/i.exec(wireOrCode);
+	return m ? `${m[2]}.${(m[1] ?? "").toUpperCase()}` : wireOrCode;
+}
+/** api Interval 词汇的受支持子集 → 腾讯 tf= 值与响应键。 */
+const INTERVAL_TO_TENCENT = /* @__PURE__ */ new Map([
+	["5m", {
+		type: "mkline",
+		tf: "m5",
+		key: "m5",
+		durationMs: 3e5
+	}],
+	["30m", {
+		type: "mkline",
+		tf: "m30",
+		key: "m30",
+		durationMs: 18e5
+	}],
+	["1d", {
+		type: "fqkline",
+		tf: "day",
+		key: "qfqday",
+		durationMs: 864e5
+	}],
+	["1w", {
+		type: "fqkline",
+		tf: "week",
+		key: "qfqweek",
+		durationMs: 6048e5
+	}],
+	["1M", {
+		type: "fqkline",
+		tf: "month",
+		key: "qfqmonth",
+		durationMs: 2592e6
+	}]
+]);
+/** 工具 parameters enum 用：受支持 interval 词汇。 */
+const INTERVAL_VOCABULARY = [...INTERVAL_TO_TENCENT.keys()];
+/**
+* 分钟 K 线时间 `YYYYMMDDHHmm` → epoch ms（Asia/Shanghai 墙钟，12 位紧凑格式）。
+*/
+function minuteKlineTimeToEpochMs(value, timeZone = "Asia/Shanghai") {
+	const m = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})$/.exec(value);
+	if (!m) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `invalid tencent minute kline timestamp ${JSON.stringify(value)}`);
+	const [, y, mo, d, h, mi] = m;
+	const guess = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), 0);
+	const offsetMs = (date) => {
+		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(date));
+		const get = (type) => Number(parts.find((p) => p.type === type)?.value ?? "0");
+		const hour = get("hour") % 24;
+		return Date.UTC(get("year"), get("month") - 1, get("day"), hour, get("minute"), get("second")) - date;
+	};
+	return guess - offsetMs(guess);
+}
+/** K 线日期 `YYYY-MM-DD` → epoch ms（UTC 当日零点锚定，行情日界语义，与 stooq 映射同构）。 */
+function klineDateToEpochMs(date) {
+	const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+	if (!m) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `invalid tencent kline date ${JSON.stringify(date)}`);
+	return Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+}
+/**
+* 交易所当地墙钟 → epoch ms（Intl 求时区偏移，含夏令时；同 stooq easternWallTimeToEpochMs
+* 的两轮逼近法，泛化时区参数）。cn 报价时间是 `YYYYMMDDHHMMSS`（Asia/Shanghai），
+* hk 报价时间是 `YYYY/MM/DD HH:MM:SS`（Asia/Hong_Kong）。
+*/
+function wallTimeToEpochMs(value, timeZone) {
+	const compact = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})$/.exec(value);
+	const normalized = (compact ? `${compact[1]}-${compact[2]}-${compact[3]}T${compact[4]}:${compact[5]}:${compact[6]}` : value.replace(/\//g, "-")).replace(/^(\d{4}-\d{2}-\d{2})$/, "$1T00:00:00");
+	const m = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?$/.exec(normalized);
+	if (!m) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `invalid tencent quote timestamp ${JSON.stringify(value)}`);
+	const [, y, mo, d, h, mi, s] = m;
+	const guess = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s ?? 0));
+	const offsetMs = (date) => {
+		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(date));
+		const get = (type) => Number(parts.find((p) => p.type === type)?.value ?? "0");
+		const hour = get("hour") % 24;
+		return Date.UTC(get("year"), get("month") - 1, get("day"), hour, get("minute"), get("second")) - date;
+	};
+	return guess - offsetMs(guess);
+}
+/** 宽松转 number（非有限值返回 undefined）。 */
+function num(value) {
+	if (value === void 0) return void 0;
+	const n = Number(value);
+	return Number.isFinite(n) ? n : void 0;
+}
+/**
+* cn 报价字段布局（v_sh600519，2026-08-31 实测 sh600519，88 字段）：
+* 1=名称 2=代码 3=现价 4=昨收 5=今开 6=成交量(**手**) 9=买一价 19=卖一价
+* 30=时间 YYYYMMDDHHMMSS(Asia/Shanghai) 31=涨跌 32=涨跌% 33=最高 34=最低
+* 35="价/量(手)/额(元)" 47=涨停价 48=跌停价 82=币种(CNY)。
+*/
+function parseCnTicker(fields, timestamp) {
+	const price = num(fields[3]);
+	if (price === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", "Tencent CN ticker: missing/invalid price field");
+	const bid = num(fields[9]);
+	const ask = num(fields[19]);
+	const volumeLots = num(fields[6]);
+	return {
+		market: "cn",
+		currency: "CNY",
+		name: fields[1] ?? "",
+		symbol: String(fields[2] ?? ""),
+		price,
+		...bid !== void 0 && bid > 0 ? { bid } : {},
+		...ask !== void 0 && ask > 0 ? { ask } : {},
+		...volumeLots !== void 0 ? { volume: volumeLots * 100 } : {},
+		timestamp,
+		prevClose: num(fields[4]),
+		open: num(fields[5]),
+		high: num(fields[33]),
+		low: num(fields[34]),
+		limitUp: num(fields[47]),
+		limitDown: num(fields[48]),
+		change: num(fields[31]),
+		changePercent: num(fields[32])
+	};
+}
+/**
+* hk 报价字段布局（v_r_hk00700，2026-08-31 实测腾讯控股，78 字段——与 cn 布局不同）：
+* 1=名称 2=代码 3=现价 4=昨收 5=今开 6=成交量(**股**，非手) 30=时间 YYYY/MM/DD
+* HH:MM:SS(Asia/Hong_Kong) 31=涨跌 32=涨跌% 33=最高 34=最低 37=成交额(HKD)
+* 46=英文名 48=52周高 49=52周低 75=币种(HKD)。买卖档位字段全 0（r_hk 实时档不可用），
+* bid/ask 置缺省。
+*/
+function parseHkTicker(fields, timestamp) {
+	const price = num(fields[3]);
+	if (price === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", "Tencent HK ticker: missing/invalid price field");
+	return {
+		market: "hk",
+		currency: "HKD",
+		name: fields[1] ?? "",
+		symbol: String(fields[2] ?? ""),
+		price,
+		...num(fields[6]) !== void 0 ? { volume: num(fields[6]) } : {},
+		timestamp,
+		prevClose: num(fields[4]),
+		open: num(fields[5]),
+		high: num(fields[33]),
+		low: num(fields[34]),
+		change: num(fields[31]),
+		changePercent: num(fields[32]),
+		week52High: num(fields[48]),
+		week52Low: num(fields[49])
+	};
+}
+/**
+* cn 五档盘口解析（issue #39）。字段布局（v_sh600519，与 parseCnTicker 同一行）：
+* 9=买一价 10=买一量(**手**) … 17=买五价 18=买五量；19=卖一价 20=卖一量 … 27=卖五价
+* 28=卖五量。档位全 0/缺省时该档丢弃——全部无效时返回空档位（消费方显示空态，
+* 盘后/集合竞价外时段属正常），不抛错。
+*/
+function parseCnOrderbook(fields, timestamp) {
+	const bids = [];
+	const asks = [];
+	for (let i = 0; i < 5; i++) {
+		const price = num(fields[9 + i * 2]);
+		const amountLots = num(fields[10 + i * 2]);
+		if (price !== void 0 && amountLots !== void 0 && price > 0 && amountLots > 0) bids.push({
+			price,
+			amount: amountLots * 100
+		});
+	}
+	for (let i = 0; i < 5; i++) {
+		const price = num(fields[19 + i * 2]);
+		const amountLots = num(fields[20 + i * 2]);
+		if (price !== void 0 && amountLots !== void 0 && price > 0 && amountLots > 0) asks.push({
+			price,
+			amount: amountLots * 100
+		});
+	}
+	return {
+		symbol: "",
+		bids,
+		asks,
+		timestamp
+	};
+}
+/**
+* cn 基本面字段布局（与 parseCnTicker 同一行报价；字段号 2026-09-02 实测
+* spikes/impl-cn-hk/r4-fundamentals/ 核对）：38=换手率% 39=动态PE 44=流通市值(亿)
+* 45=总市值(亿) 46=PB 52=静态PE 53=PE(TTM) **67=52周高 68=52周低**。
+* 注意：kit-cn/fundamentals 的 68/69 与其实测夹具自洽，但夹具比真实响应多一个空字段
+* （真实行 53 之后只有两个空位，52 周高在 67）——本解析器以 r4 原始字节证据为准。
+* 字段缺省（指数/ETF）时 num() 置 undefined 后整字段省略。
+*/
+function parseCnFundamentals(fields, timestamp) {
+	const peDynamic = num(fields[39]);
+	const peTtm = num(fields[53]) ?? peDynamic;
+	const totalMarketCapYi = num(fields[45]);
+	const floatMarketCapYi = num(fields[44]);
+	return {
+		symbol: "",
+		name: fields[1] ?? "",
+		...totalMarketCapYi !== void 0 ? { marketCap: totalMarketCapYi * 1e8 } : {},
+		...floatMarketCapYi !== void 0 ? { floatMarketCap: floatMarketCapYi * 1e8 } : {},
+		...peTtm !== void 0 ? { peTtm } : {},
+		...peDynamic !== void 0 ? { peDynamic } : {},
+		...num(fields[46]) !== void 0 ? { pb: num(fields[46]) } : {},
+		...num(fields[38]) !== void 0 ? { turnoverRate: num(fields[38]) } : {},
+		...num(fields[67]) !== void 0 ? { fiftyTwoWeekHigh: num(fields[67]) } : {},
+		...num(fields[68]) !== void 0 ? { fiftyTwoWeekLow: num(fields[68]) } : {},
+		timestamp
+	};
+}
+/**
+* hk 基本面字段布局（与 parseHkTicker 同一行报价，字段号对齐 kit-hk/fundamentals 实测）：
+* 39=动态PE 44=总市值(亿港元) 45=流通市值(亿港元) 47=股息率(百分比数值) 48=52周高 49=52周低
+* 57=PE(TTM) 58=PB 59=换手率%。
+*/
+function parseHkFundamentals(fields, timestamp) {
+	const peDynamic = num(fields[39]);
+	const peTtm = num(fields[57]) ?? peDynamic;
+	const totalMarketCapYi = num(fields[44]);
+	const floatMarketCapYi = num(fields[45]);
+	const dividendYieldPercent = num(fields[47]);
+	return {
+		symbol: "",
+		name: fields[1] ?? "",
+		...totalMarketCapYi !== void 0 ? { marketCap: totalMarketCapYi * 1e8 } : {},
+		...floatMarketCapYi !== void 0 ? { floatMarketCap: floatMarketCapYi * 1e8 } : {},
+		...peTtm !== void 0 ? { peTtm } : {},
+		...peDynamic !== void 0 ? { peDynamic } : {},
+		...num(fields[58]) !== void 0 ? { pb: num(fields[58]) } : {},
+		...dividendYieldPercent !== void 0 ? { dividendYield: dividendYieldPercent / 100 } : {},
+		...num(fields[59]) !== void 0 ? { turnoverRate: num(fields[59]) } : {},
+		...num(fields[48]) !== void 0 ? { fiftyTwoWeekHigh: num(fields[48]) } : {},
+		...num(fields[49]) !== void 0 ? { fiftyTwoWeekLow: num(fields[49]) } : {},
+		timestamp
+	};
+}
+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";
+const DEFAULT_TIMEOUT_MS = 1e4;
+var TencentRestClient = class {
+	#market;
+	#quoteBaseUrl;
+	#klineBaseUrl;
+	#mklineBaseUrl;
+	#timeoutMs;
+	#fetchImpl;
+	constructor(market, options = {}) {
+		this.#market = market;
+		this.#quoteBaseUrl = options.quoteBaseUrl ?? DEFAULT_QUOTE_BASE_URL;
+		this.#klineBaseUrl = options.klineBaseUrl ?? DEFAULT_KLINE_BASE_URL;
+		this.#mklineBaseUrl = options.mklineBaseUrl ?? DEFAULT_MKLINE_BASE_URL;
+		this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		this.#fetchImpl = options.fetchImpl ?? ((input, init) => globalThis.fetch(input, init));
+	}
+	get market() {
+		return this.#market;
+	}
+	async #requestArrayBuffer(url) {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(new DOMException(`request timed out after ${this.#timeoutMs}ms`, "TimeoutError")), this.#timeoutMs);
+		let res;
+		try {
+			res = await this.#fetchImpl(url, { signal: controller.signal });
+		} catch (cause) {
+			const timedOut = controller.signal.aborted;
+			throw new TradingServiceError("TRADING_NETWORK", timedOut ? `Tencent ${url}: request timed out after ${this.#timeoutMs}ms` : `Tencent ${url}: network error`, cause);
+		} finally {
+			clearTimeout(timer);
+		}
+		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 前缀，见文件头注）。 */
+	#quoteWireCode(symbol) {
+		return this.#market === "hk" ? `r_hk${symbol}` : symbol;
+	}
+	/** K 线 wire 形态：cn=sh600519；hk=hk00700（r_hk 打 K 线端点是 param error，实测）。 */
+	#klineWireCode(symbol) {
+		return this.#market === "hk" ? `hk${symbol}` : symbol;
+	}
+	/**
+	* 报价行取数（getTicker/getFundamentals 共用）：**GBK 解码**（响应 charset=GBK，
+	* UTF-8 直接乱码）；未知代码返回 `v_pv_none="1"` 之类短 body，按
+	* TRADING_UNSUPPORTED_SYMBOL 上报。返回 `~` 分隔字段数组 + 行情时间戳。
+	*/
+	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("~");
+		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"),
+			sym
+		};
+	}
+	/**
+	* 最新行情快照（同一报价行含基本面字段，getFundamentals 零额外请求成本地解析）。
+	*/
+	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)
+		};
+	}
+	/**
+	* 基本面与估值快照：与 getTicker 同一行报价（字段布局见 parseCnFundamentals /
+	* parseHkFundamentals 注释），无额外端点。估值字段缺省（指数/ETF）时整字段省略。
+	*/
+	async getFundamentals(symbol) {
+		const { fields, timestamp, sym } = await this.#fetchQuoteFields(symbol);
+		return {
+			...this.#market === "hk" ? parseHkFundamentals(fields, timestamp) : parseCnFundamentals(fields, timestamp),
+			symbol: toCanonicalTencentSymbol(this.#market, sym)
+		};
+	}
+	/**
+	* 盘口快照（api 可选契约 getOrderbook，issue #39）：与 getTicker 同一行报价的
+	* 五档字段（cn 布局 fields 9-28，见 parseCnOrderbook）。**hk 结构性不支持**——
+	* r_hk 行买卖档位全 0（2026-08-31 实测，parseHkTicker 注释），直接按
+	* TRADING_NOT_IMPLEMENTED 上报，桥层转 ok:false（前端显示「未提供」而非空盘口）。
+	*/
+	async getOrderbook(symbol) {
+		if (this.#market === "hk") throw new TradingServiceError("TRADING_NOT_IMPLEMENTED", "Tencent HK orderbook: r_hk quote row carries no five-level depth (all-zero fields) — orderbook unavailable for hk");
+		const { fields, timestamp, sym } = await this.#fetchQuoteFields(symbol);
+		return {
+			...parseCnOrderbook(fields, timestamp),
+			symbol: toCanonicalTencentSymbol(this.#market, sym)
+		};
+	}
+	/**
+	* K 线（日/周/月走 fqkline 前权 qfq；5m/30m 分钟线走 mkline 端点）。
+	* 港股 mkline 端点不支持分钟线，请求 5m/30m 会抛出 TRADING_UNSUPPORTED_INTERVAL。
+	*/
+	async getKlines(symbol, interval, limit) {
+		const sym = normalizeSymbol(this.#market, symbol);
+		const mapping = INTERVAL_TO_TENCENT.get(interval);
+		if (!mapping) throw new TradingServiceError("TRADING_UNSUPPORTED_INTERVAL", `Tencent klines: unsupported interval ${String(interval)} — supported: ${INTERVAL_VOCABULARY.join("/")}`);
+		if (mapping.type === "mkline" && this.#market === "hk") throw new TradingServiceError("TRADING_UNSUPPORTED_INTERVAL", `Tencent klines: Hong Kong market (HKEX) does not support minute intervals (${interval}) via public endpoint`);
+		const count = typeof limit === "number" && Number.isInteger(limit) && limit > 0 ? Math.min(limit, 800) : 100;
+		const wire = this.#klineWireCode(sym);
+		const isMinute = mapping.type === "mkline";
+		const url = isMinute ? `${this.#mklineBaseUrl}/appstock/app/kline/mkline?param=${wire},${mapping.tf},,${count}` : `${this.#klineBaseUrl}/${this.#market === "hk" ? "appstock/app/hkfqkline/get" : "appstock/app/fqkline/get"}?param=${wire},${mapping.tf},,,${count},qfq`;
+		const bytes = await this.#requestArrayBuffer(url);
+		let payload;
+		try {
+			payload = JSON.parse(new TextDecoder("utf-8").decode(bytes));
+		} catch (cause) {
+			throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Tencent klines for ${sym}: non-JSON payload`, cause);
+		}
+		if (payload.code !== 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Tencent klines for ${sym}: upstream code=${String(payload.code)} msg=${JSON.stringify(payload.msg ?? "")}`);
+		const market = payload.data?.[wire];
+		const raw = isMinute ? market?.[mapping.key] : market?.[mapping.key] ?? market?.[mapping.tf];
+		const rows = Array.isArray(raw) ? raw : void 0;
+		if (rows === void 0 || rows.length === 0) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `Tencent klines for ${sym}: no ${mapping.key}/${mapping.tf} rows (unknown/delisted symbol?)`);
+		const klines = [];
+		for (const row of rows) {
+			if (!Array.isArray(row) || typeof row[0] !== "string") throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Tencent klines for ${sym}: malformed row ${JSON.stringify(row)?.slice(0, 80)}`);
+			const open = num(String(row[1]));
+			const close = num(String(row[2]));
+			const high = num(String(row[3]));
+			const low = num(String(row[4]));
+			const volume = num(String(row[5]));
+			if (open === void 0 || close === void 0 || high === void 0 || low === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Tencent klines for ${sym}: malformed row values ${JSON.stringify(row).slice(0, 80)}`);
+			const openTime = isMinute ? minuteKlineTimeToEpochMs(row[0]) : klineDateToEpochMs(row[0]);
+			klines.push({
+				openTime,
+				open,
+				high,
+				low,
+				close,
+				volume: volume ?? 0,
+				closeTime: openTime + mapping.durationMs - 1
+			});
+		}
+		return klines;
+	}
+};
+//#endregion
+export { INTERVAL_VOCABULARY, TencentRestClient, TradingServiceError, klineDateToEpochMs, minuteKlineTimeToEpochMs, normalizeCnSymbol, normalizeHkSymbol, normalizeSymbol, parseCnOrderbook, toCanonicalTencentSymbol, wallTimeToEpochMs };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "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.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json",
+    "./dataplane": {
+      "types": "./lib/dataplane.d.ts",
+      "default": "./lib/dataplane.js"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "dependencies": {
+    "@dshtrading/api": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.2-alpha.1",
+    "@deepseek-ai/schemastery": ">=3.18.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}