@dshtrading/connector-jin10 0.6.0 → 0.6.2

package/lib/errors.d.ts

@@ -7,6 +7,29 @@ declare class Jin10Error extends Error {
   readonly code: TradingErrorCode;
   constructor(code: TradingErrorCode, message: string, cause?: unknown);
 }
+/** MCP initialize 握手中可机器识别的契约违约种类。 */
+type Jin10McpContractViolationKind = 'initialize_result_invalid' | 'unsupported_protocol_version' | 'missing_capability';
+/** 结构化契约违约载荷：错误码之外，调用方可按 kind 分支处理而不必解析文案。 */
+interface Jin10McpContractViolation {
+  readonly kind: Jin10McpContractViolationKind;
+  readonly method: string;
+  /** unsupported_protocol_version：客户端声明/支持的版本。 */
+  readonly requestedVersion?: string;
+  readonly negotiatedVersion?: string;
+  readonly supportedVersions?: readonly string[];
+  /** missing_capability：缺失的服务端能力与触发它的方法。 */
+  readonly capability?: 'tools' | 'resources';
+  readonly detail?: string;
+}
+/**
+ * MCP 协议契约违约（initialize 结果非法、协商版本不受支持、方法能力未声明）。
+ * 错误码沿用统一词汇 TRADING_EXCHANGE_ERROR（本包对上游坏形状的既有口径），
+ * 可分支信息放在 violation 上——不新造跨包错误码，也不把契约违约伪装成网络故障。
+ */
+declare class Jin10McpContractError extends Jin10Error {
+  readonly violation: Jin10McpContractViolation;
+  constructor(violation: Jin10McpContractViolation, message: string);
+}
 /**
  * 上游业务错误消息 → 错误码。
  * 限流文案必须单独识别（决定「今天别再试」的语义）；「不支持该品种」= 代码不在
@@ -15,4 +38,4 @@ declare class Jin10Error extends Error {
  */
 declare function codeForUpstreamMessage(message: string): TradingErrorCode;
 //#endregion
-export { Jin10Error, TOKEN_HINT, codeForUpstreamMessage };
+export { Jin10Error, Jin10McpContractError, Jin10McpContractViolation, Jin10McpContractViolationKind, TOKEN_HINT, codeForUpstreamMessage };

package/lib/errors.js

@@ -12,6 +12,19 @@ var Jin10Error = class extends Error {
 	}
 };
 /**
+* MCP 协议契约违约（initialize 结果非法、协商版本不受支持、方法能力未声明）。
+* 错误码沿用统一词汇 TRADING_EXCHANGE_ERROR（本包对上游坏形状的既有口径），
+* 可分支信息放在 violation 上——不新造跨包错误码，也不把契约违约伪装成网络故障。
+*/
+var Jin10McpContractError = class extends Jin10Error {
+	violation;
+	constructor(violation, message) {
+		super("TRADING_EXCHANGE_ERROR", message);
+		this.name = "Jin10McpContractError";
+		this.violation = Object.freeze({ ...violation });
+	}
+};
+/**
 * 上游业务错误消息 → 错误码。
 * 限流文案必须单独识别（决定「今天别再试」的语义）；「不支持该品种」= 代码不在
 * quote://codes 名册内（本出口实测文案，2026-09-13），映射到 UNSUPPORTED_SYMBOL
@@ -23,4 +36,4 @@ function codeForUpstreamMessage(message) {
 	return "TRADING_EXCHANGE_ERROR";
 }
 //#endregion
-export { Jin10Error, TOKEN_HINT, codeForUpstreamMessage };
+export { Jin10Error, Jin10McpContractError, TOKEN_HINT, codeForUpstreamMessage };

package/lib/index.d.ts

@@ -1,13 +1,13 @@
-import { DEFAULT_ENDPOINT, DEFAULT_PROTOCOL_VERSION, DEFAULT_TIMEOUT_MS, Jin10McpClient, Jin10McpOptions, McpContentPart, McpResourceDescriptor, McpToolDescriptor, McpToolResult, parseMcpBody } from "./mcp.js";
+import { DEFAULT_ENDPOINT, DEFAULT_PROTOCOL_VERSION, DEFAULT_TIMEOUT_MS, Jin10McpClient, Jin10McpOptions, McpContentPart, McpToolDescriptor, McpToolResult, PROTOCOL_VERSION_HEADER, SUPPORTED_PROTOCOL_VERSIONS, parseMcpBody } from "./mcp.js";
 import { Jin10ArticleDetail, Jin10ArticleSummary, Jin10CalendarEntry, Jin10Instrument, Jin10Kline, Jin10NewsItem, Jin10NewsPage, Jin10Quote, flashTitle, parseArticle, parseCalendar, parseFlashItems, parseFlashPage, parseJin10Time, parseKlines, parseNewsItems, parseNewsPage, parseQuote, parseQuoteCodes } from "./parse.js";
 import { JIN10_HEAT_LEVELS, JIN10_WEB_APP_ID, JIN10_WEB_FLASH_CHANNELS, JIN10_WEB_FLASH_ENDPOINT, JIN10_WEB_PAGE_SIZE, JIN10_WEB_X_VERSION, Jin10FlashItem, Jin10HeatLevel, Jin10HotFlashOptions, fetchJin10HotFlash, isJin10HeatLevel, parseWebFlashItems } from "./web-flash.js";
 import { JIN10_RATES_APP_ID, JIN10_RATES_ENDPOINT, JIN10_RATES_X_VERSION, Jin10RateEntry, fetchJin10Rates, parseWebRates } from "./web-rates.js";
 import { FLASH_PAGE_SIZE, INSTRUMENT_CACHE_TTL_MS, Jin10PageOptions, Jin10Service, SEARCH_FLASH_MAX } from "./service.js";
 import { Config, apply, inject, name } from "./plugin.js";
-import { Jin10Error, TOKEN_HINT, codeForUpstreamMessage } from "./errors.js";
+import { Jin10Error, Jin10McpContractError, Jin10McpContractViolation, Jin10McpContractViolationKind, TOKEN_HINT, codeForUpstreamMessage } from "./errors.js";
 import { TRADING_FLASH_FEED_KEY, createJin10FlashFeed } from "./flash-service.js";
 import { MACRO_CALENDAR_MAX, TRADING_MACRO_FEED_KEY, createJin10MacroFeed } from "./macro-service.js";
-import { GLOBAL_MARKET, JIN10_PROVIDER, MAX_MINUTE_WINDOW, MINUTE_BARS_PER_CALL, TICKER_POLL_MS, TRADING_GLOBAL_MARKET_DATA_KEY, aggregateKlines, createJin10GlobalMarketDataService, resolveIntervalMinutes, tickerFromQuote } from "./market-data.js";
+import { GLOBAL_MARKET, JIN10_PROVIDER, MAX_MINUTE_WINDOW, MINUTE_BARS_PER_CALL, TRADING_GLOBAL_MARKET_DATA_KEY, aggregateKlines, createJin10GlobalMarketDataService, resolveIntervalMinutes, tickerFromQuote } from "./market-data.js";
 import { JIN10_REGIONS, Jin10Region, regionOfFlagUrl, regionOfTitle } from "./regions.js";
 import { createJin10Tools } from "./tools.js";
-export { Config, DEFAULT_ENDPOINT, DEFAULT_PROTOCOL_VERSION, DEFAULT_TIMEOUT_MS, FLASH_PAGE_SIZE, GLOBAL_MARKET, INSTRUMENT_CACHE_TTL_MS, JIN10_HEAT_LEVELS, JIN10_PROVIDER, JIN10_RATES_APP_ID, JIN10_RATES_ENDPOINT, JIN10_RATES_X_VERSION, JIN10_REGIONS, JIN10_WEB_APP_ID, JIN10_WEB_FLASH_CHANNELS, JIN10_WEB_FLASH_ENDPOINT, JIN10_WEB_PAGE_SIZE, JIN10_WEB_X_VERSION, Jin10ArticleDetail, Jin10ArticleSummary, Jin10CalendarEntry, Jin10Error, Jin10FlashItem, Jin10HeatLevel, Jin10HotFlashOptions, Jin10Instrument, Jin10Kline, Jin10McpClient, Jin10McpOptions, Jin10NewsItem, Jin10NewsPage, Jin10PageOptions, Jin10Quote, Jin10RateEntry, Jin10Region, Jin10Service, MACRO_CALENDAR_MAX, MAX_MINUTE_WINDOW, MINUTE_BARS_PER_CALL, McpContentPart, McpResourceDescriptor, McpToolDescriptor, McpToolResult, SEARCH_FLASH_MAX, TICKER_POLL_MS, TOKEN_HINT, TRADING_FLASH_FEED_KEY, TRADING_GLOBAL_MARKET_DATA_KEY, TRADING_MACRO_FEED_KEY, aggregateKlines, apply, codeForUpstreamMessage, createJin10FlashFeed, createJin10GlobalMarketDataService, createJin10MacroFeed, createJin10Tools, fetchJin10HotFlash, fetchJin10Rates, flashTitle, inject, isJin10HeatLevel, name, parseArticle, parseCalendar, parseFlashItems, parseFlashPage, parseJin10Time, parseKlines, parseMcpBody, parseNewsItems, parseNewsPage, parseQuote, parseQuoteCodes, parseWebFlashItems, parseWebRates, regionOfFlagUrl, regionOfTitle, resolveIntervalMinutes, tickerFromQuote };
+export { Config, DEFAULT_ENDPOINT, DEFAULT_PROTOCOL_VERSION, DEFAULT_TIMEOUT_MS, FLASH_PAGE_SIZE, GLOBAL_MARKET, INSTRUMENT_CACHE_TTL_MS, JIN10_HEAT_LEVELS, JIN10_PROVIDER, JIN10_RATES_APP_ID, JIN10_RATES_ENDPOINT, JIN10_RATES_X_VERSION, JIN10_REGIONS, JIN10_WEB_APP_ID, JIN10_WEB_FLASH_CHANNELS, JIN10_WEB_FLASH_ENDPOINT, JIN10_WEB_PAGE_SIZE, JIN10_WEB_X_VERSION, Jin10ArticleDetail, Jin10ArticleSummary, Jin10CalendarEntry, Jin10Error, Jin10FlashItem, Jin10HeatLevel, Jin10HotFlashOptions, Jin10Instrument, Jin10Kline, Jin10McpClient, Jin10McpContractError, Jin10McpContractViolation, Jin10McpContractViolationKind, Jin10McpOptions, Jin10NewsItem, Jin10NewsPage, Jin10PageOptions, Jin10Quote, Jin10RateEntry, Jin10Region, Jin10Service, MACRO_CALENDAR_MAX, MAX_MINUTE_WINDOW, MINUTE_BARS_PER_CALL, McpContentPart, McpToolDescriptor, McpToolResult, PROTOCOL_VERSION_HEADER, SEARCH_FLASH_MAX, SUPPORTED_PROTOCOL_VERSIONS, TOKEN_HINT, TRADING_FLASH_FEED_KEY, TRADING_GLOBAL_MARKET_DATA_KEY, TRADING_MACRO_FEED_KEY, aggregateKlines, apply, codeForUpstreamMessage, createJin10FlashFeed, createJin10GlobalMarketDataService, createJin10MacroFeed, createJin10Tools, fetchJin10HotFlash, fetchJin10Rates, flashTitle, inject, isJin10HeatLevel, name, parseArticle, parseCalendar, parseFlashItems, parseFlashPage, parseJin10Time, parseKlines, parseMcpBody, parseNewsItems, parseNewsPage, parseQuote, parseQuoteCodes, parseWebFlashItems, parseWebRates, regionOfFlagUrl, regionOfTitle, resolveIntervalMinutes, tickerFromQuote };

package/lib/index.js

@@ -1,13 +1,13 @@
-import { Jin10Error, TOKEN_HINT, codeForUpstreamMessage } from "./errors.js";
+import { Jin10Error, Jin10McpContractError, TOKEN_HINT, codeForUpstreamMessage } from "./errors.js";
 import { JIN10_REGIONS, regionOfFlagUrl, regionOfTitle } from "./regions.js";
 import { flashTitle, parseArticle, parseCalendar, parseFlashItems, parseFlashPage, parseJin10Time, parseKlines, parseNewsItems, parseNewsPage, parseQuote, parseQuoteCodes } from "./parse.js";
 import { JIN10_HEAT_LEVELS, JIN10_WEB_APP_ID, JIN10_WEB_FLASH_CHANNELS, JIN10_WEB_FLASH_ENDPOINT, JIN10_WEB_PAGE_SIZE, JIN10_WEB_X_VERSION, fetchJin10HotFlash, isJin10HeatLevel, parseWebFlashItems } from "./web-flash.js";
 import { TRADING_FLASH_FEED_KEY, createJin10FlashFeed } from "./flash-service.js";
 import { MACRO_CALENDAR_MAX, TRADING_MACRO_FEED_KEY, createJin10MacroFeed } from "./macro-service.js";
-import { GLOBAL_MARKET, JIN10_PROVIDER, MAX_MINUTE_WINDOW, MINUTE_BARS_PER_CALL, TICKER_POLL_MS, TRADING_GLOBAL_MARKET_DATA_KEY, aggregateKlines, createJin10GlobalMarketDataService, resolveIntervalMinutes, tickerFromQuote } from "./market-data.js";
-import { DEFAULT_ENDPOINT, DEFAULT_PROTOCOL_VERSION, DEFAULT_TIMEOUT_MS, Jin10McpClient, parseMcpBody } from "./mcp.js";
+import { GLOBAL_MARKET, JIN10_PROVIDER, MAX_MINUTE_WINDOW, MINUTE_BARS_PER_CALL, TRADING_GLOBAL_MARKET_DATA_KEY, aggregateKlines, createJin10GlobalMarketDataService, resolveIntervalMinutes, tickerFromQuote } from "./market-data.js";
+import { DEFAULT_ENDPOINT, DEFAULT_PROTOCOL_VERSION, DEFAULT_TIMEOUT_MS, Jin10McpClient, PROTOCOL_VERSION_HEADER, SUPPORTED_PROTOCOL_VERSIONS, parseMcpBody } from "./mcp.js";
 import { JIN10_RATES_APP_ID, JIN10_RATES_ENDPOINT, JIN10_RATES_X_VERSION, fetchJin10Rates, parseWebRates } from "./web-rates.js";
 import { FLASH_PAGE_SIZE, INSTRUMENT_CACHE_TTL_MS, Jin10Service, SEARCH_FLASH_MAX } from "./service.js";
 import { createJin10Tools } from "./tools.js";
 import { Config, apply, inject, name } from "./plugin.js";
-export { Config, DEFAULT_ENDPOINT, DEFAULT_PROTOCOL_VERSION, DEFAULT_TIMEOUT_MS, FLASH_PAGE_SIZE, GLOBAL_MARKET, INSTRUMENT_CACHE_TTL_MS, JIN10_HEAT_LEVELS, JIN10_PROVIDER, JIN10_RATES_APP_ID, JIN10_RATES_ENDPOINT, JIN10_RATES_X_VERSION, JIN10_REGIONS, JIN10_WEB_APP_ID, JIN10_WEB_FLASH_CHANNELS, JIN10_WEB_FLASH_ENDPOINT, JIN10_WEB_PAGE_SIZE, JIN10_WEB_X_VERSION, Jin10Error, Jin10McpClient, Jin10Service, MACRO_CALENDAR_MAX, MAX_MINUTE_WINDOW, MINUTE_BARS_PER_CALL, SEARCH_FLASH_MAX, TICKER_POLL_MS, TOKEN_HINT, TRADING_FLASH_FEED_KEY, TRADING_GLOBAL_MARKET_DATA_KEY, TRADING_MACRO_FEED_KEY, aggregateKlines, apply, codeForUpstreamMessage, createJin10FlashFeed, createJin10GlobalMarketDataService, createJin10MacroFeed, createJin10Tools, fetchJin10HotFlash, fetchJin10Rates, flashTitle, inject, isJin10HeatLevel, name, parseArticle, parseCalendar, parseFlashItems, parseFlashPage, parseJin10Time, parseKlines, parseMcpBody, parseNewsItems, parseNewsPage, parseQuote, parseQuoteCodes, parseWebFlashItems, parseWebRates, regionOfFlagUrl, regionOfTitle, resolveIntervalMinutes, tickerFromQuote };
+export { Config, DEFAULT_ENDPOINT, DEFAULT_PROTOCOL_VERSION, DEFAULT_TIMEOUT_MS, FLASH_PAGE_SIZE, GLOBAL_MARKET, INSTRUMENT_CACHE_TTL_MS, JIN10_HEAT_LEVELS, JIN10_PROVIDER, JIN10_RATES_APP_ID, JIN10_RATES_ENDPOINT, JIN10_RATES_X_VERSION, JIN10_REGIONS, JIN10_WEB_APP_ID, JIN10_WEB_FLASH_CHANNELS, JIN10_WEB_FLASH_ENDPOINT, JIN10_WEB_PAGE_SIZE, JIN10_WEB_X_VERSION, Jin10Error, Jin10McpClient, Jin10McpContractError, Jin10Service, MACRO_CALENDAR_MAX, MAX_MINUTE_WINDOW, MINUTE_BARS_PER_CALL, PROTOCOL_VERSION_HEADER, SEARCH_FLASH_MAX, SUPPORTED_PROTOCOL_VERSIONS, TOKEN_HINT, TRADING_FLASH_FEED_KEY, TRADING_GLOBAL_MARKET_DATA_KEY, TRADING_MACRO_FEED_KEY, aggregateKlines, apply, codeForUpstreamMessage, createJin10FlashFeed, createJin10GlobalMarketDataService, createJin10MacroFeed, createJin10Tools, fetchJin10HotFlash, fetchJin10Rates, flashTitle, inject, isJin10HeatLevel, name, parseArticle, parseCalendar, parseFlashItems, parseFlashPage, parseJin10Time, parseKlines, parseMcpBody, parseNewsItems, parseNewsPage, parseQuote, parseQuoteCodes, parseWebFlashItems, parseWebRates, regionOfFlagUrl, regionOfTitle, resolveIntervalMinutes, tickerFromQuote };

package/lib/market-data.d.ts

@@ -12,16 +12,12 @@ declare const TRADING_GLOBAL_MARKET_DATA_KEY = "tradingGlobalMarketData";
 declare const MINUTE_BARS_PER_CALL = 100;
 /** 本仓最多拼的分钟窗口（3 次上游调用）；再深的历史上游没有，不做假数据。 */
 declare const MAX_MINUTE_WINDOW = 300;
-/** Ticker 轮询周期（上游无推送通道）。 */
-declare const TICKER_POLL_MS = 5000;
 declare function resolveIntervalMinutes(interval: string): number | undefined;
 /** 按分钟数聚合（桶起点 = 本地时间轴对齐；量能求和，缺量按 0）。 */
 declare function aggregateKlines(bars: readonly Kline[], minutes: number): Kline[];
 /** get_quote → Ticker（缺失最新价 = 上游形状异常，如实报错，不编价格）。 */
 declare function tickerFromQuote(quote: Jin10Quote): Ticker;
 /** global 市场数据面实现（纯对象；与快讯面同款，避免 Service 构造签名的类型漂移）。 */
-declare function createJin10GlobalMarketDataService(feed: Jin10Service, options?: {
-  pollMs?: number;
-}): MarketDataService;
+declare function createJin10GlobalMarketDataService(feed: Jin10Service): MarketDataService;
 //#endregion
-export { GLOBAL_MARKET, JIN10_PROVIDER, MAX_MINUTE_WINDOW, MINUTE_BARS_PER_CALL, TICKER_POLL_MS, TRADING_GLOBAL_MARKET_DATA_KEY, aggregateKlines, createJin10GlobalMarketDataService, resolveIntervalMinutes, tickerFromQuote };
+export { GLOBAL_MARKET, JIN10_PROVIDER, MAX_MINUTE_WINDOW, MINUTE_BARS_PER_CALL, TRADING_GLOBAL_MARKET_DATA_KEY, aggregateKlines, createJin10GlobalMarketDataService, resolveIntervalMinutes, tickerFromQuote };

package/lib/market-data.js

@@ -10,8 +10,14 @@ const TRADING_GLOBAL_MARKET_DATA_KEY = "tradingGlobalMarketData";
 const MINUTE_BARS_PER_CALL = 100;
 /** 本仓最多拼的分钟窗口（3 次上游调用）；再深的历史上游没有，不做假数据。 */
 const MAX_MINUTE_WINDOW = 300;
-/** Ticker 轮询周期（上游无推送通道）。 */
-const TICKER_POLL_MS = 5e3;
+/**
+* 本市场**不提供常驻 ticker 订阅**：`global_quote` / `global_klines` 的 UI/价格
+* 路径预算为 **0 常驻**——上游配额按工具分池，固定间隔轮询按秒折算必然超出一个
+* 数量级。分配口径与折算数值的家是 dsh-trading-bot 的
+* `packages/tradectl/bin/feeds-budget.mjs` 与 `docs/guides/connectors-guide.md`
+* 的「金十额度预算分配」节（本仓只引用规则，不复写数值）；GUI 侧节奏执行见
+* client-ui-trading 的 quote-budget.ts。要价格一律按需：`getTicker` / `getKlines`。
+*/
 /** 支持的周期 → 每根分钟数（api Interval 的子集：分钟级来源能诚实支撑的部分）。 */
 const INTERVAL_MINUTES = {
 	"1m": 1,
@@ -88,8 +94,7 @@ function minuteBarToKline(bar) {
 	};
 }
 /** global 市场数据面实现（纯对象；与快讯面同款，避免 Service 构造签名的类型漂移）。 */
-function createJin10GlobalMarketDataService(feed, options = {}) {
-	const pollMs = options.pollMs ?? 5e3;
+function createJin10GlobalMarketDataService(feed) {
 	const requireCode = (symbol) => {
 		const trimmed = symbol.trim().toUpperCase();
 		if (trimmed === "") throw new Jin10Error("TRADING_UNKNOWN", "jin10 global: symbol must not be empty");
@@ -128,25 +133,12 @@ function createJin10GlobalMarketDataService(feed, options = {}) {
 			const wanted = Math.max(1, Math.min(Math.floor(limit), Math.floor(300 / minutes)));
 			return aggregateKlines(await loadMinuteWindow(requireCode(symbol), wanted * minutes), minutes).slice(-wanted);
 		},
-		subscribeTicker(symbol, listener) {
-			let stopped = false;
-			const tick = async () => {
-				if (stopped) return;
-				try {
-					const ticker = await loadTicker(symbol);
-					if (!stopped) listener(ticker);
-				} catch (error) {
-					if (!stopped) console.warn("[dsh-trading] jin10 ticker poll failed for " + symbol + ":", error);
-				}
-			};
-			tick();
-			const timer = setInterval(() => {
-				tick();
-			}, pollMs);
-			return { dispose() {
-				stopped = true;
-				clearInterval(timer);
-			} };
+		/**
+		* 常驻 ticker 订阅显式拒绝（见模块头注释）：本市场没有常驻轮询预算，静默
+		* 轮询正是预算失控的形态。要价格请按需 `getTicker`。
+		*/
+		subscribeTicker(symbol) {
+			throw new Jin10Error("TRADING_NOT_IMPLEMENTED", "jin10 global: 不提供常驻 ticker 订阅（global_quote 的 UI/价格路径预算为 0 常驻，见 connectors-guide「金十额度预算分配」）；请按需调用 getTicker。symbol=" + symbol);
 		},
 		async listInstruments() {
 			return (await feed.listInstruments()).map((item) => ({
@@ -157,4 +149,4 @@ function createJin10GlobalMarketDataService(feed, options = {}) {
 	};
 }
 //#endregion
-export { GLOBAL_MARKET, JIN10_PROVIDER, MAX_MINUTE_WINDOW, MINUTE_BARS_PER_CALL, TICKER_POLL_MS, TRADING_GLOBAL_MARKET_DATA_KEY, aggregateKlines, createJin10GlobalMarketDataService, resolveIntervalMinutes, tickerFromQuote };
+export { GLOBAL_MARKET, JIN10_PROVIDER, MAX_MINUTE_WINDOW, MINUTE_BARS_PER_CALL, TRADING_GLOBAL_MARKET_DATA_KEY, aggregateKlines, createJin10GlobalMarketDataService, resolveIntervalMinutes, tickerFromQuote };

package/lib/mcp.d.ts

@@ -2,18 +2,22 @@
 declare const DEFAULT_ENDPOINT = "https://mcp.jin10.com/mcp";
 declare const DEFAULT_PROTOCOL_VERSION = "2025-11-25";
 declare const DEFAULT_TIMEOUT_MS = 15000;
+/**
+ * 本客户端能说的 Streamable HTTP 协议版本（官方 revision）：
+ * - `2025-11-25`：金十本出口 spike 实测协商版本；
+ * - `2025-06-18`：官方首个定义 `MCP-Protocol-Version` 头的 revision。
+ * 上游协商出集合之外的版本时按官方「客户端 SHOULD disconnect」报结构化错误，
+ * 不降级猜测协议语义。
+ */
+declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+/** initialize 之后每个 HTTP 请求都必须携带的协商版本头（官方 Streamable HTTP）。 */
+declare const PROTOCOL_VERSION_HEADER = "MCP-Protocol-Version";
 interface McpToolDescriptor {
   name: string;
   description?: string;
   inputSchema?: unknown;
   outputSchema?: unknown;
 }
-interface McpResourceDescriptor {
-  uri: string;
-  name?: string;
-  mimeType?: string;
-  description?: string;
-}
 /** 可读文本段（structuredContent 缺席时的兜底来源）。 */
 interface McpContentPart {
   type?: string;
@@ -33,6 +37,8 @@ interface Jin10McpOptions {
   timeoutMs?: number;
   /** 依赖注入的 fetch（测试用 mock；缺省 globalThis.fetch）。 */
   fetchImpl?: typeof globalThis.fetch;
+  /** 可选会话级取消信号：与单次请求超时合并，取消报「request aborted」。 */
+  signal?: AbortSignal;
   /** 协议版本（缺省 2025-11-25）。 */
   protocolVersion?: string;
   clientName?: string;
@@ -58,12 +64,16 @@ declare class Jin10McpClient {
   private readonly protocolVersion;
   private readonly clientName;
   private readonly clientVersion;
+  private readonly signal;
   private nextId;
   private sessionId;
   private handshake;
+  /** initialize 协商出的协议版本（其后每个请求的 MCP-Protocol-Version 头来源）。 */
+  private negotiatedProtocolVersion;
+  /** initialize 声明的服务端能力表（方法族能力闸门的判据）。 */
+  private serverCapabilities;
   constructor(options: Jin10McpOptions);
   listTools(): Promise<McpToolDescriptor[]>;
-  listResources(): Promise<McpResourceDescriptor[]>;
   /** 读资源正文（quote://codes 等；返回全部 text 段拼接）。 */
   readResource(uri: string): Promise<string>;
   /** 原始 tools/call（不做业务解包；协议/HTTP 错误在此抛出）。 */
@@ -74,8 +84,22 @@ declare class Jin10McpClient {
    */
   callToolData(tool: string, args?: Record<string, unknown>): Promise<unknown>;
   private ensureHandshake;
+  /** 丢弃一次未完成的握手留下的全部状态（initialize 之后、initialized 之前的任何失败）。 */
+  private resetHandshakeState;
   private performHandshake;
+  /**
+   * 校验 initialize 结果并返回服务端能力表；违反官方 lifecycle 契约时抛结构化错误。
+   * 依据：官方 revision 2025-11-25 lifecycle——服务端 MUST 回 protocolVersion 与
+   * capabilities；客户端不支持的协商版本 SHOULD disconnect。
+   */
+  private acceptInitializeResult;
+  /** 客户端可接受的协商版本：声明的版本 + 官方可说的版本集合。 */
+  private supportedVersions;
+  /** 方法族能力闸门：能力未声明时在发请求前抛结构化错误（缺能力 ≠ 上游 4xx）。 */
+  private assertMethodCapability;
+  /** 单次请求信号：调用方取消信号与超时窗口合并，任一触发都以 AbortError 结束。 */
+  private requestSignal;
   private rpc;
 }
 //#endregion
-export { DEFAULT_ENDPOINT, DEFAULT_PROTOCOL_VERSION, DEFAULT_TIMEOUT_MS, Jin10McpClient, Jin10McpOptions, McpContentPart, McpResourceDescriptor, McpToolDescriptor, McpToolResult, parseMcpBody };
+export { DEFAULT_ENDPOINT, DEFAULT_PROTOCOL_VERSION, DEFAULT_TIMEOUT_MS, Jin10McpClient, Jin10McpOptions, McpContentPart, McpToolDescriptor, McpToolResult, PROTOCOL_VERSION_HEADER, SUPPORTED_PROTOCOL_VERSIONS, parseMcpBody };

package/lib/mcp.js

@@ -1,20 +1,42 @@
-import { Jin10Error, TOKEN_HINT, codeForUpstreamMessage } from "./errors.js";
+import { Jin10Error, Jin10McpContractError, TOKEN_HINT, codeForUpstreamMessage } from "./errors.js";
 //#region src/mcp.ts
 /**
 * MCP 传输层（Streamable HTTP / JSON-RPC 2.0）。
 *
 * 标准流程（用户 2026-09-13 给定契约，本出口实测复核）：
-*   initialize → notifications/initialized → tools/list / resources/list / resources/read → tools/call
+*   initialize → notifications/initialized → tools/list / resources/read → tools/call
 * 响应形态两种都要吃：`application/json` 直出 JSON，或 `text/event-stream` 里
 * `event: message` + 单行 `data: {…}`（金十本出口实测为后者）。若上游回
 * `mcp-session-id` 头则后续请求原样回带（本出口当前无会话头，属可选能力）。
 *
 * 结果读取：`result.structuredContent` 优先，`result.content[].text` 仅在
 * structuredContent 缺席时作可读文本兜底（用户契约 3/4）。
+*
+* 握手契约（官方 MCP revision 2025-11-25 / 2025-06-18，本仓 spike 原始证据
+* `spikes/impl-jin10-mcp/EVIDENCE/01-initialize.json`）：客户端必须校验 initialize
+* 结果里的 `protocolVersion` 与 `capabilities`；协商版本用于其后每个 HTTP 请求的
+* `MCP-Protocol-Version` 头；未声明 `tools` / `resources` 能力时对应方法族直接报
+* 结构化契约错误，不发业务请求（不重造宿主 MCP、不升级 SDK）。
 */
 const DEFAULT_ENDPOINT = "https://mcp.jin10.com/mcp";
 const DEFAULT_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_TIMEOUT_MS = 15e3;
+/**
+* 本客户端能说的 Streamable HTTP 协议版本（官方 revision）：
+* - `2025-11-25`：金十本出口 spike 实测协商版本；
+* - `2025-06-18`：官方首个定义 `MCP-Protocol-Version` 头的 revision。
+* 上游协商出集合之外的版本时按官方「客户端 SHOULD disconnect」报结构化错误，
+* 不降级猜测协议语义。
+*/
+const SUPPORTED_PROTOCOL_VERSIONS = Object.freeze(["2025-11-25", "2025-06-18"]);
+/** initialize 之后每个 HTTP 请求都必须携带的协商版本头（官方 Streamable HTTP）。 */
+const PROTOCOL_VERSION_HEADER = "MCP-Protocol-Version";
+/** 服务端能力 → 依赖它的 JSON-RPC 方法族（缺能力即拒发，不靠上游 4xx 兜底）。 */
+const METHOD_CAPABILITY = Object.freeze({
+	"tools/list": "tools",
+	"tools/call": "tools",
+	"resources/read": "resources"
+});
 /** 把响应体解析成 JSON-RPC 消息（直出 JSON 或 SSE 单行 data 均可）。 */
 function parseMcpBody(text) {
 	const trimmed = text.trim();
@@ -45,10 +67,16 @@ function parseMcpBody(text) {
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function networkError(method, cause) {
+/**
+* 传输层失败：超时与取消分别显式标注（前者带超时窗口，后者标明调用方取消），
+* 不混成一句 network failure，也不在这里重试（重试由调用方显式发起）。
+*/
+function networkError(method, cause, timeoutMs) {
 	const reason = cause instanceof Error ? cause.message : String(cause);
-	const timedOut = cause instanceof Error && (cause.name === "TimeoutError" || cause.name === "AbortError");
-	return new Jin10Error("TRADING_NETWORK", `jin10 mcp ${method}: ${timedOut ? "request timed out" : "network failure"} — ${reason}`, cause);
+	const name = cause instanceof Error ? cause.name : "";
+	if (name === "TimeoutError") return new Jin10Error("TRADING_NETWORK", `jin10 mcp ${method}: request timed out after ${timeoutMs}ms`, cause);
+	if (name === "AbortError") return new Jin10Error("TRADING_NETWORK", `jin10 mcp ${method}: request aborted before completion — ${reason}`, cause);
+	return new Jin10Error("TRADING_NETWORK", `jin10 mcp ${method}: network failure — ${reason}`, cause);
 }
 var Jin10McpClient = class {
 	endpoint;
@@ -58,14 +86,20 @@ var Jin10McpClient = class {
 	protocolVersion;
 	clientName;
 	clientVersion;
+	signal;
 	nextId = 1;
 	sessionId;
 	handshake;
+	/** initialize 协商出的协议版本（其后每个请求的 MCP-Protocol-Version 头来源）。 */
+	negotiatedProtocolVersion;
+	/** initialize 声明的服务端能力表（方法族能力闸门的判据）。 */
+	serverCapabilities;
 	constructor(options) {
 		this.endpoint = options.endpoint ?? "https://mcp.jin10.com/mcp";
 		this.token = options.token;
 		this.timeoutMs = options.timeoutMs ?? 15e3;
 		this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+		this.signal = options.signal;
 		this.protocolVersion = options.protocolVersion ?? "2025-11-25";
 		this.clientName = options.clientName ?? "dsh-trading-connector-jin10";
 		this.clientVersion = options.clientVersion ?? "0.2.1";
@@ -81,17 +115,6 @@ var Jin10McpClient = class {
 			...tool.outputSchema !== void 0 ? { outputSchema: tool.outputSchema } : {}
 		}));
 	}
-	async listResources() {
-		const result = await this.rpc("resources/list", {});
-		const resources = isRecord(result) ? result.resources : void 0;
-		if (!Array.isArray(resources)) throw new Jin10Error("TRADING_EXCHANGE_ERROR", "jin10 mcp resources/list: unexpected payload (expected result.resources[])");
-		return resources.filter(isRecord).map((resource) => ({
-			uri: String(resource.uri ?? ""),
-			...typeof resource.name === "string" ? { name: resource.name } : {},
-			...typeof resource.mimeType === "string" ? { mimeType: resource.mimeType } : {},
-			...typeof resource.description === "string" ? { description: resource.description } : {}
-		}));
-	}
 	/** 读资源正文（quote://codes 等；返回全部 text 段拼接）。 */
 	async readResource(uri) {
 		const result = await this.rpc("resources/read", { uri });
@@ -131,12 +154,19 @@ var Jin10McpClient = class {
 	async ensureHandshake() {
 		if (this.handshake === void 0) this.handshake = this.performHandshake().catch((error) => {
 			this.handshake = void 0;
+			this.resetHandshakeState();
 			throw error;
 		});
 		return this.handshake;
 	}
+	/** 丢弃一次未完成的握手留下的全部状态（initialize 之后、initialized 之前的任何失败）。 */
+	resetHandshakeState() {
+		this.negotiatedProtocolVersion = void 0;
+		this.serverCapabilities = void 0;
+		this.sessionId = void 0;
+	}
 	async performHandshake() {
-		await this.rpc("initialize", {
+		const result = await this.rpc("initialize", {
 			protocolVersion: this.protocolVersion,
 			capabilities: {},
 			clientInfo: {
@@ -144,13 +174,73 @@ var Jin10McpClient = class {
 				version: this.clientVersion
 			}
 		}, { skipHandshake: true });
+		this.serverCapabilities = this.acceptInitializeResult(result);
 		await this.rpc("notifications/initialized", void 0, {
 			notification: true,
 			skipHandshake: true
 		});
 	}
+	/**
+	* 校验 initialize 结果并返回服务端能力表；违反官方 lifecycle 契约时抛结构化错误。
+	* 依据：官方 revision 2025-11-25 lifecycle——服务端 MUST 回 protocolVersion 与
+	* capabilities；客户端不支持的协商版本 SHOULD disconnect。
+	*/
+	acceptInitializeResult(result) {
+		if (!isRecord(result)) throw new Jin10McpContractError({
+			kind: "initialize_result_invalid",
+			method: "initialize",
+			detail: "result is not an object"
+		}, "jin10 mcp initialize: result is not an object");
+		const negotiated = result.protocolVersion;
+		if (typeof negotiated !== "string" || negotiated.trim().length === 0) throw new Jin10McpContractError({
+			kind: "initialize_result_invalid",
+			method: "initialize",
+			detail: "missing protocolVersion"
+		}, "jin10 mcp initialize: server did not return a protocolVersion");
+		const supported = this.supportedVersions();
+		if (!supported.includes(negotiated)) throw new Jin10McpContractError({
+			kind: "unsupported_protocol_version",
+			method: "initialize",
+			requestedVersion: this.protocolVersion,
+			negotiatedVersion: negotiated,
+			supportedVersions: supported
+		}, `jin10 mcp initialize: server negotiated unsupported protocol version "${negotiated}" (client supports ${supported.join(", ")})`);
+		const capabilities = result.capabilities;
+		if (!isRecord(capabilities)) throw new Jin10McpContractError({
+			kind: "initialize_result_invalid",
+			method: "initialize",
+			detail: "missing capabilities"
+		}, "jin10 mcp initialize: server did not return a capabilities object");
+		this.negotiatedProtocolVersion = negotiated;
+		return capabilities;
+	}
+	/** 客户端可接受的协商版本：声明的版本 + 官方可说的版本集合。 */
+	supportedVersions() {
+		return SUPPORTED_PROTOCOL_VERSIONS.includes(this.protocolVersion) ? SUPPORTED_PROTOCOL_VERSIONS : Object.freeze([this.protocolVersion, ...SUPPORTED_PROTOCOL_VERSIONS]);
+	}
+	/** 方法族能力闸门：能力未声明时在发请求前抛结构化错误（缺能力 ≠ 上游 4xx）。 */
+	assertMethodCapability(method) {
+		const capability = METHOD_CAPABILITY[method];
+		if (capability === void 0) return;
+		const declared = this.serverCapabilities;
+		if (declared !== void 0 && isRecord(declared[capability])) return;
+		throw new Jin10McpContractError({
+			kind: "missing_capability",
+			method,
+			capability
+		}, `jin10 mcp ${method}: server did not declare the "${capability}" capability during initialize; refusing to send the request`);
+	}
+	/** 单次请求信号：调用方取消信号与超时窗口合并，任一触发都以 AbortError 结束。 */
+	requestSignal() {
+		const timeout = AbortSignal.timeout(this.timeoutMs);
+		if (this.signal === void 0) return timeout;
+		return AbortSignal.any([this.signal, timeout]);
+	}
 	async rpc(method, params, options = {}) {
-		if (options.skipHandshake !== true) await this.ensureHandshake();
+		if (options.skipHandshake !== true) {
+			await this.ensureHandshake();
+			this.assertMethodCapability(method);
+		}
 		const token = this.token();
 		if (token === void 0 || token.trim().length === 0) throw new Jin10Error("TRADING_CREDENTIALS_MISSING", `jin10 mcp ${method}: missing MCP token. ${TOKEN_HINT}`);
 		const payload = {
@@ -167,13 +257,14 @@ var Jin10McpClient = class {
 					"content-type": "application/json",
 					accept: "application/json, text/event-stream",
 					authorization: `Bearer ${token.trim()}`,
+					...this.negotiatedProtocolVersion !== void 0 ? { [PROTOCOL_VERSION_HEADER]: this.negotiatedProtocolVersion } : {},
 					...this.sessionId !== void 0 ? { "mcp-session-id": this.sessionId } : {}
 				},
 				body: JSON.stringify(payload),
-				signal: AbortSignal.timeout(this.timeoutMs)
+				signal: this.requestSignal()
 			});
 		} catch (error) {
-			throw networkError(method, error);
+			throw networkError(method, error, this.timeoutMs);
 		}
 		const sessionId = response.headers.get("mcp-session-id");
 		if (sessionId !== null && sessionId.length > 0) this.sessionId = sessionId;
@@ -190,7 +281,7 @@ var Jin10McpClient = class {
 			throw new Jin10Error("TRADING_EXCHANGE_ERROR", `jin10 mcp ${method}: HTTP ${response.status}${body ? ` — ${body.slice(0, 200)}` : ""}`);
 		}
 		const message = parseMcpBody(await response.text().catch((error) => {
-			throw networkError(method, error);
+			throw networkError(method, error, this.timeoutMs);
 		}));
 		if (message === void 0) return void 0;
 		if (isRecord(message.error)) {
@@ -219,4 +310,4 @@ function textEnvelope(result) {
 	}
 }
 //#endregion
-export { DEFAULT_ENDPOINT, DEFAULT_PROTOCOL_VERSION, DEFAULT_TIMEOUT_MS, Jin10McpClient, parseMcpBody };
+export { DEFAULT_ENDPOINT, DEFAULT_PROTOCOL_VERSION, DEFAULT_TIMEOUT_MS, Jin10McpClient, PROTOCOL_VERSION_HEADER, SUPPORTED_PROTOCOL_VERSIONS, parseMcpBody };

package/lib/tools.js

@@ -1,3 +1,4 @@
+import "./macro-service.js";
 import "./service.js";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 //#region src/tools.ts
@@ -186,11 +187,11 @@ function createJin10Tools(service) {
 			description: `Current-week economic calendar from ${SOURCE} (Monday–Sunday, Beijing time): release time, importance stars, consensus / previous / actual values and the stated market impact. Values are the publisher snapshot as of the call — the same release may be revised; treat actual=null as "not published yet". Upstream rate limit: 1500 calls per tool per Beijing calendar day.`,
 			parameters: { limit: {
 				type: "number",
-				description: "Max entries to return (integer 1..250; default 40, earliest first)"
+				description: `Max entries to return (integer 1..400; default 40, earliest first)`
 			} },
 			output: textOutput,
 			async execute(raw) {
-				const limit = readLimit((raw ?? {}).limit, 40, 250);
+				const limit = readLimit((raw ?? {}).limit, 40, 400);
 				const entries = await service.listCalendar(limit);
 				if (entries.length === 0) return "econ_calendar: the upstream calendar is empty for the current week.";
 				return [`econ_calendar — ${entries.length} entr(ies) for the current week (Beijing time), source: ${SOURCE}:`, ...entries.map(renderCalendarLine)].join("\n");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dshtrading/connector-jin10",
   "description": "金十数据 MCP 连接器：把 mcp.jin10.com 的行情/快讯/资讯/财经日历封装成本仓的连接器（市场无关，host 面工具行）",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -25,11 +25,11 @@
   ],
   "license": "PolyForm-Noncommercial-1.0.0",
   "dependencies": {
-    "@dshtrading/api": "^0.6.0"
+    "@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": {