@dshtrading/connector-jin10 0.3.0

package/lib/service.js

@@ -0,0 +1,117 @@
+import { Jin10Error } from "./errors.js";
+import { parseArticle, parseCalendar, parseFlashItems, parseFlashPage, parseKlines, parseNewsPage, parseQuote, parseQuoteCodes } from "./parse.js";
+import { fetchJin10HotFlash } from "./web-flash.js";
+import "./mcp.js";
+//#region src/service.ts
+/**
+* 取数层：把 MCP 工具名（list_flash / search_flash / list_news / search_news / get_news /
+* list_calendar / get_quote / get_kline）与 quote://codes 资源封装成本仓语义的读法，
+* 分页统一 `cursor → data.next_cursor / data.has_more`（用户契约 5）。
+*
+* 工具名与参数不对外泄漏到 agent 面：工具面用业务命名（tools.ts），provider 可替换。
+*/
+/** 快讯/资讯单页上限（上游 list_* 每页 20 条；search_flash 一次性最多 150 条且不可翻页）。 */
+const FLASH_PAGE_SIZE = 20;
+const SEARCH_FLASH_MAX = 150;
+/** 品种代码表缓存 TTL（静态名册，按小时级缓存；失败不缓存，下次调用重试）。 */
+const INSTRUMENT_CACHE_TTL_MS = 36e5;
+var Jin10Service = class {
+	client;
+	webFetch;
+	webTimeoutMs;
+	instruments;
+	constructor(client, web = {}) {
+		this.client = client;
+		this.webFetch = web.fetchImpl ?? globalThis.fetch.bind(globalThis);
+		this.webTimeoutMs = web.timeoutMs ?? 15e3;
+	}
+	/**
+	* 按热度取快讯（金十网页版服务端过滤，火/热/沸/爆）：官方 MCP 的 list_flash
+	* 无热度参数，故热度路径走网页版接口（见 web-flash.ts）。cursor = 上一页
+	* 最旧一条的 time 原串。
+	*/
+	async listFlashByHeat(options) {
+		return fetchJin10HotFlash(this.webFetch, {
+			hot: options.hot,
+			cursor: options.cursor
+		}, { timeoutMs: this.webTimeoutMs });
+	}
+	/** 最新快讯流（cursor 翻页；正文不下发，只留标题/时间/链接）。 */
+	async listFlash(options = {}) {
+		const data = await this.client.callToolData("list_flash", options.cursor === void 0 ? {} : { cursor: options.cursor });
+		return parseFlashPage(data, "list_flash", options.limit);
+	}
+	/** 关键词搜快讯：上游一次性返回（最多 150 条，不支持翻页），故无 cursor。 */
+	async searchFlash(keyword, limit) {
+		const trimmed = requireKeyword(keyword);
+		const cap = Math.min(limit ?? 150, 150);
+		const data = await this.client.callToolData("search_flash", { keyword: trimmed });
+		return parseFlashItems(data, "search_flash", cap);
+	}
+	async listNews(options = {}) {
+		const data = await this.client.callToolData("list_news", options.cursor === void 0 ? {} : { cursor: options.cursor });
+		return parseNewsPage(data, "list_news", options.limit);
+	}
+	async searchNews(keyword, options = {}) {
+		const args = { keyword: requireKeyword(keyword) };
+		if (options.cursor !== void 0) args.cursor = options.cursor;
+		const data = await this.client.callToolData("search_news", args);
+		return parseNewsPage(data, "search_news", options.limit);
+	}
+	/** 文章详情：标题/导语/时间/链接（正文按铁律 #5 不下发）。 */
+	async getArticle(id) {
+		const trimmed = (id ?? "").trim();
+		if (trimmed.length === 0) throw new Jin10Error("TRADING_UNKNOWN", "jin10 news_get: id is required");
+		return parseArticle(await this.client.callToolData("get_news", { id: trimmed }));
+	}
+	/** 本周财经日历（周一~周日；上游一次返回整周）。 */
+	async listCalendar(limit) {
+		return parseCalendar(await this.client.callToolData("list_calendar", {}), limit);
+	}
+	/** 品种名册（quote://codes 资源）；query 按代码或中文名过滤。 */
+	async listInstruments(query) {
+		const items = await this.instrumentCatalog();
+		const needle = query?.trim().toLowerCase();
+		if (needle === void 0 || needle.length === 0) return items;
+		return items.filter((item) => item.code.toLowerCase().includes(needle) || item.name.toLowerCase().includes(needle));
+	}
+	async getQuote(code) {
+		const trimmed = requireCode(code);
+		return parseQuote(await this.client.callToolData("get_quote", { code: trimmed }));
+	}
+	/** 分钟级 K 线：`time` = 起始秒级时间戳（从此往后取，窗口 24h 内），count ≤ 100。 */
+	async getKlines(code, options = {}) {
+		const args = { code: requireCode(code) };
+		if (options.time !== void 0) {
+			if (!Number.isInteger(options.time) || options.time <= 0) throw new Jin10Error("TRADING_UNKNOWN", "jin10 global_klines: time must be a positive Unix timestamp in seconds");
+			args.time = options.time;
+		}
+		if (options.count !== void 0) {
+			if (!Number.isInteger(options.count) || options.count < 1 || options.count > 100) throw new Jin10Error("TRADING_UNKNOWN", "jin10 global_klines: count must be an integer from 1 to 100");
+			args.count = options.count;
+		}
+		return parseKlines(await this.client.callToolData("get_kline", args), options.count);
+	}
+	async instrumentCatalog() {
+		const cached = this.instruments;
+		if (cached !== void 0 && Date.now() - cached.at < 36e5) return cached.items;
+		const items = parseQuoteCodes(await this.client.readResource("quote://codes"));
+		this.instruments = {
+			at: Date.now(),
+			items
+		};
+		return items;
+	}
+};
+function requireKeyword(keyword) {
+	const trimmed = (keyword ?? "").trim();
+	if (trimmed.length === 0) throw new Jin10Error("TRADING_UNKNOWN", "jin10 search: keyword is required");
+	return trimmed;
+}
+function requireCode(code) {
+	const trimmed = (code ?? "").trim();
+	if (trimmed.length === 0) throw new Jin10Error("TRADING_UNSUPPORTED_SYMBOL", "jin10 quote: code is required (see the global_instruments tool for the code space)");
+	return trimmed;
+}
+//#endregion
+export { FLASH_PAGE_SIZE, INSTRUMENT_CACHE_TTL_MS, Jin10Service, SEARCH_FLASH_MAX };

package/lib/tools.d.ts

@@ -0,0 +1,7 @@
+import { Jin10Service } from "./service.js";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/tools.d.ts
+/** 工具集合：service 注入即得全部工具（测试用假 service，生产用真 MCP 链路）。 */
+declare function createJin10Tools(service: Jin10Service): Array<ReturnType<typeof defineTool>>;
+//#endregion
+export { createJin10Tools };

package/lib/tools.js

@@ -0,0 +1,282 @@
+import "./service.js";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/tools.ts
+/**
+* agent 工具面（市场无关命名，provider 可替换 —— 与 `symbol_search`、`knowledge_search`
+* 同族的跨市场命名，不带交易所名）：快讯、资讯、财经日历、全球品种报价/K线。
+*
+* 输出纪律：
+*   - 列表类工具只回**元数据**（时间/标题/链接/id），正文与摘要正文不下发（数据零再分发）；
+*   - 时间统一 ISO 8601；标题与链接必须可点回原文；
+*   - 分页显式回带 `next_cursor`/`has_more`，让模型能续页而不是猜；
+*   - 上游业务错误（isError / status≠200 / 限流）抛错，绝不静默返回空列表。
+*/
+const textOutput = {
+	schema: { type: "string" },
+	render: (_args, value) => [{
+		type: "text",
+		text: value
+	}]
+};
+const SOURCE = "Jin10 (金十数据) MCP feed";
+function renderNewsLines(items) {
+	return items.map((item) => {
+		const id = "id" in item && typeof item.id === "string" ? ` | id=${item.id}` : "";
+		return `${item.publishedAt} | ${item.title} | ${item.url}${id}`;
+	});
+}
+function pageFooter(page, tool) {
+	if (page.hasMore && page.nextCursor !== void 0) return `has_more=true — pass cursor="${page.nextCursor}" to ${tool} for the next (older) page.`;
+	return "has_more=false — no further pages.";
+}
+function renderCalendarLine(entry) {
+	const fields = [
+		`前值=${entry.previous ?? "-"}`,
+		`预期=${entry.consensus ?? "-"}`,
+		`公布=${entry.actual ?? "-"}`
+	];
+	if (entry.revised !== void 0) fields.push(`修正=${entry.revised}`);
+	if (entry.affect !== void 0) fields.push(`影响=${entry.affect}`);
+	return `${entry.publishedAt} | ★${entry.star} | ${entry.title} | ${fields.join(" ")}`;
+}
+/** 工具集合：service 注入即得全部工具（测试用假 service，生产用真 MCP 链路）。 */
+function createJin10Tools(service) {
+	return [
+		defineTool({
+			name: "flash_list",
+			description: `Latest market flash headlines from ${SOURCE}, newest first. Market-wide wire (macro, commodities, FX, A-shares, geopolitics) — not tied to one instrument. Each item carries publish time, headline and the source link; the full flash text stays on the linked page. Pages return up to 20 items: pass the returned cursor to read older pages. Upstream rate limit: 1500 calls per tool per Beijing calendar day.`,
+			parameters: {
+				cursor: {
+					type: "string",
+					description: "Opaque page cursor from a previous flash_list call (omit for the newest page)"
+				},
+				limit: {
+					type: "number",
+					description: `Max items to return (integer 1..50; default 20)`
+				}
+			},
+			output: textOutput,
+			async execute(raw) {
+				const args = raw ?? {};
+				const limit = readLimit(args.limit, 20, 50);
+				const cursor = readCursor(args.cursor);
+				const page = await service.listFlash({
+					limit,
+					...cursor !== void 0 ? { cursor } : {}
+				});
+				if (page.items.length === 0) return "flash_list: no flash items returned by the upstream feed.";
+				return [
+					`flash_list — ${page.items.length} item(s), newest-first, source: ${SOURCE}:`,
+					...renderNewsLines(page.items),
+					pageFooter(page, "flash_list")
+				].join("\n");
+			}
+		}),
+		defineTool({
+			name: "flash_search",
+			description: `Keyword search over recent ${SOURCE} flash headlines (e.g. 黄金 / 原油 / 美联储 / 非农 / 日本央行 / 欧佩克). Upstream returns at most 150 matches in one shot and does not paginate — narrow the keyword instead of paging. Only metadata is returned; open the link for the full text. Upstream rate limit: 1500 calls per tool per Beijing calendar day.`,
+			parameters: {
+				keyword: {
+					type: "string",
+					required: true,
+					description: "Chinese keyword, e.g. 黄金 / 原油 / 美联储"
+				},
+				limit: {
+					type: "number",
+					description: `Max matches to return (integer 1..150; default 30)`
+				}
+			},
+			output: textOutput,
+			async execute(raw) {
+				const args = raw ?? {};
+				const limit = readLimit(args.limit, 30, 150);
+				const items = await service.searchFlash(String(args.keyword ?? ""), limit);
+				if (items.length === 0) return `flash_search: no flash items matched ${JSON.stringify(String(args.keyword ?? ""))}.`;
+				return [`flash_search — ${items.length} match(es) for ${JSON.stringify(String(args.keyword ?? ""))}, newest-first, source: ${SOURCE}:`, ...renderNewsLines(items)].join("\n");
+			}
+		}),
+		defineTool({
+			name: "news_list",
+			description: `Latest ${SOURCE} editorial articles (longer-form macro/market analysis), newest first. Articles are paged: pass the returned cursor for older pages. Returns metadata plus the article id; call news_get with that id for the publisher abstract. Upstream rate limit: 1500 calls per tool per Beijing calendar day.`,
+			parameters: {
+				cursor: {
+					type: "string",
+					description: "Opaque page cursor from a previous news_list call (omit for the newest page)"
+				},
+				limit: {
+					type: "number",
+					description: "Max items to return (integer 1..50; default 10)"
+				}
+			},
+			output: textOutput,
+			async execute(raw) {
+				const args = raw ?? {};
+				const limit = readLimit(args.limit, 10, 50);
+				const cursor = readCursor(args.cursor);
+				const page = await service.listNews({
+					limit,
+					...cursor !== void 0 ? { cursor } : {}
+				});
+				if (page.items.length === 0) return "news_list: no articles returned by the upstream feed.";
+				return [
+					`news_list — ${page.items.length} article(s), newest-first, source: ${SOURCE}:`,
+					...renderNewsLines(page.items),
+					pageFooter(page, "news_list")
+				].join("\n");
+			}
+		}),
+		defineTool({
+			name: "news_search",
+			description: `Keyword search over ${SOURCE} editorial articles (e.g. 美联储 / 通胀 / 欧佩克 / 日元). Paged like news_list; each hit carries an id for news_get. Metadata only — the article body stays on the publisher page. Upstream rate limit: 1500 calls per tool per Beijing calendar day.`,
+			parameters: {
+				keyword: {
+					type: "string",
+					required: true,
+					description: "Chinese keyword, e.g. 美联储 / 通胀 / 日元"
+				},
+				cursor: {
+					type: "string",
+					description: "Opaque page cursor from a previous news_search call"
+				},
+				limit: {
+					type: "number",
+					description: "Max matches to return (integer 1..50; default 10)"
+				}
+			},
+			output: textOutput,
+			async execute(raw) {
+				const args = raw ?? {};
+				const limit = readLimit(args.limit, 10, 50);
+				const cursor = readCursor(args.cursor);
+				const page = await service.searchNews(String(args.keyword ?? ""), {
+					limit,
+					...cursor !== void 0 ? { cursor } : {}
+				});
+				if (page.items.length === 0) return `news_search: no articles matched ${JSON.stringify(String(args.keyword ?? ""))}.`;
+				return [
+					`news_search — ${page.items.length} match(es) for ${JSON.stringify(String(args.keyword ?? ""))}, newest-first, source: ${SOURCE}:`,
+					...renderNewsLines(page.items),
+					pageFooter(page, "news_search")
+				].join("\n");
+			}
+		}),
+		defineTool({
+			name: "news_get",
+			description: `Publisher metadata for one ${SOURCE} article: title, publish time, link and the publisher's own introduction/abstract, by article id from news_list or news_search. The full article body is not redistributed — open the link to read it. Upstream rate limit: 1500 calls per tool per Beijing calendar day.`,
+			parameters: { id: {
+				type: "string",
+				required: true,
+				description: "Article id from news_list / news_search, e.g. 229952"
+			} },
+			output: textOutput,
+			async execute(raw) {
+				const args = raw ?? {};
+				const article = await service.getArticle(String(args.id ?? ""));
+				return [
+					`news_get — id=${article.id}, source: ${SOURCE}`,
+					`title: ${article.title}`,
+					`publishedAt: ${article.publishedAt}`,
+					`url: ${article.url}`,
+					...article.introduction !== void 0 ? [`introduction: ${article.introduction}`] : []
+				].join("\n");
+			}
+		}),
+		defineTool({
+			name: "econ_calendar",
+			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)"
+			} },
+			output: textOutput,
+			async execute(raw) {
+				const limit = readLimit((raw ?? {}).limit, 40, 250);
+				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");
+			}
+		}),
+		defineTool({
+			name: "global_instruments",
+			description: `Code catalog for the ${SOURCE} quote space (spot metals, energy, FX, global and A-share indices). Call this before global_quote / global_klines whenever the code is not obvious; codes are the publisher's own (XAUUSD, USOIL, USBND, USDJPY …), NOT the market symbol vocabulary. Upstream rate limit: 1500 calls per tool per Beijing calendar day.`,
+			parameters: { query: {
+				type: "string",
+				description: "Optional filter on code or Chinese name, e.g. 黄金 / 原油 / JPY"
+			} },
+			output: textOutput,
+			async execute(raw) {
+				const args = raw ?? {};
+				const query = typeof args.query === "string" && args.query.trim().length > 0 ? args.query.trim() : void 0;
+				const items = await service.listInstruments(query);
+				const label = query === void 0 ? "all instruments" : `matches for ${JSON.stringify(query)}`;
+				if (items.length === 0) return `global_instruments: no ${label} in the quote space.`;
+				return [`global_instruments — ${items.length} ${label} (source: ${SOURCE}):`, ...items.map((item) => `${item.code} — ${item.name}`)].join("\n");
+			}
+		}),
+		defineTool({
+			name: "global_quote",
+			description: `Real-time quote for one ${SOURCE} instrument (spot gold/silver/copper, WTI/Brent, FX, indices). Fields: open/close/high/low/volume plus change and change percent; \`time\` is the quote timestamp (Beijing time) — quotes may be delayed or closed-market. Use global_instruments to resolve a code. Upstream rate limit: 1500 calls per tool per Beijing calendar day.`,
+			parameters: { code: {
+				type: "string",
+				required: true,
+				description: "Publisher code, e.g. XAUUSD / XAGUSD / USOIL / UKOIL / COPPER / USDJPY / EURUSD / USDCNH"
+			} },
+			output: textOutput,
+			async execute(raw) {
+				const args = raw ?? {};
+				const quote = await service.getQuote(String(args.code ?? ""));
+				return JSON.stringify(quote);
+			}
+		}),
+		defineTool({
+			name: "global_klines",
+			description: `Minute-level candles for one ${SOURCE} instrument. Upstream semantics: \`time\` is the START Unix timestamp in seconds and candles are returned forward from it, within a 24-hour window (omit it and the window starts at the current minute, which often yields an empty result — pass a start time inside the last 24h for real data). count is 1..100 (default 100). An empty array means no candles in that window (closed market/weekend), not an upstream failure. Upstream rate limit: 1500 calls per tool per Beijing calendar day.`,
+			parameters: {
+				code: {
+					type: "string",
+					required: true,
+					description: "Publisher code, e.g. XAUUSD / USOIL / USDJPY"
+				},
+				time: {
+					type: "number",
+					description: "Start Unix timestamp in seconds (from the last 24 hours)"
+				},
+				count: {
+					type: "number",
+					description: "Number of candles from time, integer 1..100 (default 100)"
+				}
+			},
+			output: textOutput,
+			async execute(raw) {
+				const args = raw ?? {};
+				const code = String(args.code ?? "");
+				const options = {};
+				if (args.time !== void 0) options.time = Math.floor(Number(args.time));
+				if (args.count !== void 0) options.count = Math.floor(Number(args.count));
+				const klines = await service.getKlines(code, options);
+				if (klines.length === 0) return JSON.stringify({
+					code,
+					klines: [],
+					note: "no candles in the requested window (upstream returns forward from time, 24h window)"
+				});
+				return JSON.stringify({
+					code,
+					klines
+				});
+			}
+		})
+	];
+}
+function readLimit(value, fallback, max) {
+	if (value === void 0) return fallback;
+	const parsed = Math.floor(Number(value));
+	if (!Number.isFinite(parsed) || parsed < 1) return fallback;
+	return Math.min(parsed, max);
+}
+function readCursor(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : void 0;
+}
+//#endregion
+export { createJin10Tools };

package/lib/web-flash.d.ts

@@ -0,0 +1,34 @@
+import { Jin10NewsItem, Jin10NewsPage } from "./parse.js";
+//#region src/web-flash.d.ts
+declare const JIN10_WEB_FLASH_ENDPOINT = "https://3318fc142ea545eab931e22a61ec6e5c.z3c.jin10.com/flash";
+/** 网页版 x-app-id / x-version（bundle 内常量，网页版请求原样复刻）。 */
+declare const JIN10_WEB_APP_ID = "bVBF4FyRTn5NJF5n";
+declare const JIN10_WEB_X_VERSION = "1.0";
+/** 网页版快讯频道（bundle d.Xr = [1,5,9]）。 */
+declare const JIN10_WEB_FLASH_CHANNELS: readonly [1, 5, 9];
+/** 网页版单页条数（上游固定，无 pageSize 参数）。 */
+declare const JIN10_WEB_PAGE_SIZE = 50;
+/** 四级热度：1=火 2=热 3=沸 4=爆（bundle o）。数组顺序即网页版展示顺序。 */
+declare const JIN10_HEAT_LEVELS: readonly ["火", "热", "沸", "爆"];
+type Jin10HeatLevel = (typeof JIN10_HEAT_LEVELS)[number];
+declare function isJin10HeatLevel(value: unknown): value is Jin10HeatLevel;
+/** 热度快讯条目（比 MCP 快讯多一个 hot 标签）。 */
+interface Jin10FlashItem extends Jin10NewsItem {
+  readonly hot?: string;
+}
+interface Jin10HotFlashOptions {
+  hot: readonly Jin10HeatLevel[];
+  /** 翻页游标 = 上一页最旧一条的网页版 time 原串（上游 max_time 语义）。 */
+  cursor?: string | undefined;
+}
+/** 网页版条目 → 本仓 NewsItem 形状（坏形状丢弃，绝不回退「现在」或臆造 url）。 */
+declare function parseWebFlashItems(payload: unknown): Jin10FlashItem[];
+/**
+ * 按热度取快讯（服务端过滤）。上游单页 50 条，max_time 翻页；
+ * hasMore 以「满页」判断，nextCursor = 本页最旧一条的 time 原串。
+ */
+declare function fetchJin10HotFlash(fetchImpl: typeof globalThis.fetch, options: Jin10HotFlashOptions, config: {
+  timeoutMs: number;
+}): Promise<Jin10NewsPage<Jin10FlashItem>>;
+//#endregion
+export { 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 };

package/lib/web-flash.js

@@ -0,0 +1,121 @@
+import { Jin10Error } from "./errors.js";
+import { flashTitle, parseJin10Time } from "./parse.js";
+//#region src/web-flash.ts
+/**
+* 金十网页版「热度快讯」取数（2026-09-13）。
+*
+* 背景：官方 MCP 的 list_flash 不支持热度（inputSchema 只有 cursor，额外参数被上游
+* 以 unexpected additional properties 拒绝），条目也只有 content/time/url。而金十
+* **网页版**对快讯有 火/热/沸/爆 四级热度筛选，且是**服务端过滤**。本模块复刻网页版
+* 实际请求（从 www.jin10.com 前端 bundle 逆向 + 真实网络复核）：
+*
+*   GET https://3318fc142ea545eab931e22a61ec6e5c.z3c.jin10.com/flash?params=<JSON>
+*   headers: x-app-id: bVBF4FyRTn5NJF5n, x-version: 1.0, handleError: 1
+*   params : { channel:[1,5,9], hot:['热','爆'], max_time?, date? }
+*   响应   : { status, message, data:[{ id, time, data:{title,content,source,…}, hot, important, … }] }
+*
+* 与 MCP 是两套入口：本接口属网页版公开接口（非官方 MCP 契约），仅用于热度筛选。
+* 铁律 #5：只下发 title/time/url（+ hot 标签），正文 content 不取不再分发。
+*/
+const JIN10_WEB_FLASH_ENDPOINT = "https://3318fc142ea545eab931e22a61ec6e5c.z3c.jin10.com/flash";
+/** 网页版 x-app-id / x-version（bundle 内常量，网页版请求原样复刻）。 */
+const JIN10_WEB_APP_ID = "bVBF4FyRTn5NJF5n";
+const JIN10_WEB_X_VERSION = "1.0";
+/** 网页版快讯频道（bundle d.Xr = [1,5,9]）。 */
+const JIN10_WEB_FLASH_CHANNELS = [
+	1,
+	5,
+	9
+];
+/** 网页版单页条数（上游固定，无 pageSize 参数）。 */
+const JIN10_WEB_PAGE_SIZE = 50;
+/** 四级热度：1=火 2=热 3=沸 4=爆（bundle o）。数组顺序即网页版展示顺序。 */
+const JIN10_HEAT_LEVELS = [
+	"火",
+	"热",
+	"沸",
+	"爆"
+];
+function isJin10HeatLevel(value) {
+	return typeof value === "string" && JIN10_HEAT_LEVELS.includes(value);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** 网页版条目 → 本仓 NewsItem 形状（坏形状丢弃，绝不回退「现在」或臆造 url）。 */
+function parseWebFlashItems(payload) {
+	if (!isRecord(payload)) throw new Jin10Error("TRADING_EXCHANGE_ERROR", "jin10 hot-flash: unexpected payload (expected an object)");
+	if (payload.status !== 200) {
+		const message = typeof payload.message === "string" && payload.message.length > 0 ? payload.message : "unknown upstream error";
+		throw new Jin10Error("TRADING_EXCHANGE_ERROR", `jin10 hot-flash: upstream status ${String(payload.status)} — ${message}`);
+	}
+	if (!Array.isArray(payload.data)) throw new Jin10Error("TRADING_EXCHANGE_ERROR", "jin10 hot-flash: unexpected payload (expected data[])");
+	const items = [];
+	for (const raw of payload.data) {
+		if (!isRecord(raw)) continue;
+		const id = typeof raw.id === "string" ? raw.id.trim() : "";
+		const publishedAt = parseJin10Time(raw.time);
+		if (id.length === 0 || publishedAt === void 0) continue;
+		const data = isRecord(raw.data) ? raw.data : void 0;
+		const content = typeof data?.content === "string" ? data.content : "";
+		const explicit = typeof data?.title === "string" ? data.title.trim() : "";
+		const title = explicit.length > 0 ? explicit : flashTitle(content);
+		if (title === void 0) continue;
+		const hot = isJin10HeatLevel(raw.hot) ? raw.hot : void 0;
+		items.push({
+			source: "jin10",
+			title,
+			url: `https://flash.jin10.com/detail/${id}`,
+			publishedAt,
+			...hot !== void 0 ? { hot } : {}
+		});
+	}
+	return items;
+}
+/**
+* 按热度取快讯（服务端过滤）。上游单页 50 条，max_time 翻页；
+* hasMore 以「满页」判断，nextCursor = 本页最旧一条的 time 原串。
+*/
+async function fetchJin10HotFlash(fetchImpl, options, config) {
+	const hot = options.hot.filter(isJin10HeatLevel);
+	if (hot.length === 0) throw new Jin10Error("TRADING_UNKNOWN", "jin10 hot-flash: hot must contain at least one of 火/热/沸/爆");
+	const params = {
+		channel: [...JIN10_WEB_FLASH_CHANNELS],
+		hot
+	};
+	if (options.cursor !== void 0 && options.cursor.length > 0) params.max_time = options.cursor;
+	const url = new URL(JIN10_WEB_FLASH_ENDPOINT);
+	url.searchParams.set("params", JSON.stringify(params));
+	const response = await fetchImpl(url, {
+		headers: {
+			accept: "application/json",
+			"user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124 Safari/537.36",
+			"x-app-id": JIN10_WEB_APP_ID,
+			"x-version": "1.0",
+			handleError: "1",
+			referer: "https://www.jin10.com/"
+		},
+		signal: AbortSignal.timeout(config.timeoutMs)
+	});
+	if (!response.ok) {
+		const body = await response.text().catch(() => "");
+		throw new Jin10Error("TRADING_EXCHANGE_ERROR", `jin10 hot-flash: HTTP ${response.status}${body ? ` — ${body.slice(0, 160)}` : ""}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(await response.text());
+	} catch {
+		throw new Jin10Error("TRADING_EXCHANGE_ERROR", "jin10 hot-flash: upstream returned non-JSON body");
+	}
+	const items = parseWebFlashItems(parsed);
+	const rawData = parsed.data;
+	const oldest = rawData[rawData.length - 1];
+	const cursor = typeof oldest?.time === "string" ? oldest.time : void 0;
+	return {
+		items,
+		hasMore: items.length >= 50,
+		...cursor !== void 0 ? { nextCursor: cursor } : {}
+	};
+}
+//#endregion
+export { 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 };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@dshtrading/connector-jin10",
+  "description": "金十数据 MCP 连接器：把 mcp.jin10.com 的行情/快讯/资讯/财经日历封装成本仓的连接器（市场无关，host 面工具行）",
+  "version": "0.3.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./dataplane": {
+      "types": "./lib/dataplane.d.ts",
+      "default": "./lib/dataplane.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "dependencies": {
+    "@dshtrading/api": "^0.3.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.5-rc.1",
+    "@deepseek-ai/schemastery": ">=3.18.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}