@dshtrading/connector-yahoo 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-yahoo
+
+dsh-trading us 切片市场连接器：经 **Yahoo Finance v8 chart API**（`query1.finance.yahoo.com/v8/finance/chart/...`）实现 `@dshtrading/api` 的 `MarketDataService` 契约（ctx 键 `tradingUsMarketData`），并提供 `us_get_ticker` / `us_get_klines` / `us_place_order` 三工具（下单三段闸门与 connector-stooq/binance 同构）。
+
+## 数据源状态：已实证（2026-08-29）
+
+本出口（开发机）实测可用：`interval=1d&range=5d` 返回完整 `meta` + `timestamp[]` + `indicators.quote[0]` 序列；需 `User-Agent: Mozilla/5.0` 头。ticker + klines 真实请求证据与交叉一致性分析见 `spikes/impl-us-yahoo/`（probe-output.txt / ticker-AAPL.json / klines-AAPL-1d.json / klines-AAPL-60m.json / EVIDENCE.md）。
+
+已知局限（工具描述同步向模型说明）：
+
+- **非官方 API**：无 key、无 SLA、无稳定性承诺；主机为 query1/query2 双活备用。
+- **日线汇总滞后**：最新已收盘交易日的日 K 可能延后补齐（实证：周五收盘后周六早晨日线序列仍缺周五，但 60m 序列完整且收盘价与 `meta.regularMarketPrice` 一致到 float32 精度）。`getTicker` 的价格/时间取 meta（权威实时面），volume 取最新日 K 量、可能滞后一个交易日。
+- 1m 线历史上限约 7 天（Yahoo 端约束）。
+
+## 合规记录（README 铁律 #5）
+
+Yahoo Finance 的 v8 chart API 为**非官方接口**：个人使用属灰色但被普遍使用的边界。本仓按现状如实记录：
+
+- 无凭证、无 key；仅拉取公开行情，**本仓不缓存、不批量抓取、不再次分发**任何行情数据；
+- 使用边界以 [Yahoo Terms of Use](https://legal.yahoo.com/terms-of-use/) 与其数据提供方条款为准；
+- 若 Yahoo 收紧该接口（风控/鉴权），本连接器会如实报 `TRADING_*` 错误，不做伪装或挑战求解。
+
+## 前任数据源
+
+us 切片原用 connector-stooq；Stooq 自本出口被反爬拒止（挑战页 + Access denied，证据 `spikes/impl-us/REPORT.md`），无成功实证，于任务 G 切换至 Yahoo。connector-stooq 代码保留（其他出口可能可用），状态见其 README。

package/lib/dataplane.d.ts

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

package/lib/dataplane.js

@@ -0,0 +1,22 @@
+import { TRADING_US_MARKET_DATA_KEY, YahooMarketDataService } 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 = "yahoo";
+function apply(ctx) {
+	const registry = resolveMarketDataRegistry(ctx);
+	if (registry === void 0) {
+		new YahooMarketDataService(ctx);
+		return;
+	}
+	const inner = ctx.isolate(TRADING_US_MARKET_DATA_KEY);
+	const service = new YahooMarketDataService(inner);
+	ctx.effect(() => registry.register("us", ROUTER_PROVIDER, service));
+}
+//#endregion
+export { apply, inject };

package/lib/index.d.ts

@@ -0,0 +1,83 @@
+import { INTERVAL_VOCABULARY, TradingServiceError, YahooChartEnvelope, YahooChartResult, YahooRestClient, YahooRestOptions, isSupportedInterval, normalizeYahooSymbol, parseChartBars } from "./rest.js";
+import { Context, Service } from "@deepseek-ai/cordis";
+import Schema from "@deepseek-ai/schemastery";
+import { Disposable, Interval, Kline, MarketDataService, Ticker } from "@dshtrading/api";
+//#region src/index.d.ts
+/**
+ * Cordis 插件名 = patch 行 id（TEMPLATES §8）：`dsh-trading-us-*` 市场命名空间，
+ * 全仓唯一（insert-only 铁律 #1）。
+ */
+declare const name = "dsh-trading-us-connector-yahoo";
+interface Config {
+  /** 交易安全闸门（铁律 #3）：true 时下单类工具强制 dry-run。 */
+  dryRun: boolean;
+  /** 实盘总闸门：默认 false；false 时无论 dryRun 与否都拒绝实盘下单 [S4]。 */
+  liveTrading: boolean;
+}
+declare const Config: Schema<Config>;
+/** 需要宿主提供的 Cordis 服务。 */
+declare const inject: string[];
+/** ctx 服务键：与 @dshtrading/api 的 Context 模块增强一致（市场命名空间）。 */
+declare const TRADING_US_MARKET_DATA_KEY = "tradingUsMarketData";
+interface SubscribeTickerOptions {
+  /** 轮询间隔（ms）。subscribeTicker 以 meta 快照轮询实现（Yahoo 无官方推送面）。 */
+  readonly intervalMs?: number;
+}
+declare class YahooMarketDataService extends Service implements MarketDataService {
+  private readonly client;
+  constructor(ctx: Context, options?: YahooRestOptions, name?: string);
+  getTicker(symbol: string): Promise<Ticker>;
+  getKlines(symbol: string, interval: Interval, limit?: number): Promise<Kline[]>;
+  subscribeTicker(symbol: string, cb: (ticker: Ticker) => void, options?: SubscribeTickerOptions): Disposable;
+}
+/** us_place_order 参数契约（美股词汇，dryRun 缺省 true）。 */
+interface PlaceOrderArgs {
+  /** 股票代码，如 `AAPL` 或 `brk-b`（执行前归一化为 Yahoo 大写形态）。 */
+  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/stooq 同构，见 connector-binance evaluateOrderGate）。
+ */
+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 回执：模拟成交 + Yahoo 最新 regular-market 参照（参照取不到不阻断模拟本身）。 */
+interface DryRunReference {
+  source: 'yahoo-regular-market';
+  price?: number;
+  volume?: number;
+  timestamp?: number;
+  unavailable?: string;
+}
+declare function buildDryRunReceipt(args: PlaceOrderArgs, marketData: Pick<MarketDataService, 'getTicker'>): Promise<string>;
+interface PlaceOrderToolDeps {
+  /** 行情服务（dry-run 回执的市价参照），按接口取用，不直连 HTTP。 */
+  readonly marketData: Pick<MarketDataService, 'getTicker'>;
+  /** 插件配置（dryRun 强制模拟 / liveTrading 总闸门）。 */
+  readonly config: Config;
+}
+/**
+ * us_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 { Config, DryRunReference, INTERVAL_VOCABULARY, OrderGateVerdict, PlaceOrderArgs, PlaceOrderToolDeps, SubscribeTickerOptions, TRADING_US_MARKET_DATA_KEY, TradingServiceError, YahooChartEnvelope, YahooChartResult, YahooMarketDataService, YahooRestClient, YahooRestOptions, apply, buildDryRunReceipt, createPlaceOrderTool, evaluateOrderGate, inject, isSupportedInterval, name, normalizeYahooSymbol, parseChartBars };

package/lib/index.js

@@ -0,0 +1,235 @@
+import { INTERVAL_VOCABULARY, TradingServiceError, YahooRestClient, isSupportedInterval, normalizeYahooSymbol, parseChartBars } 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 插件名 = patch 行 id（TEMPLATES §8）：`dsh-trading-us-*` 市场命名空间，
+* 全仓唯一（insert-only 铁律 #1）。
+*/
+const name = "dsh-trading-us-connector-yahoo";
+const Config = Schema.object({
+	dryRun: Schema.boolean().default(true),
+	liveTrading: Schema.boolean().default(false)
+});
+/** 需要宿主提供的 Cordis 服务。 */
+const inject = ["tools"];
+/** ctx 服务键：与 @dshtrading/api 的 Context 模块增强一致（市场命名空间）。 */
+const TRADING_US_MARKET_DATA_KEY = "tradingUsMarketData";
+const SUBSCRIBE_MIN_MS = 250;
+const SUBSCRIBE_DEFAULT_MS = 5e3;
+var YahooMarketDataService = class extends Service {
+	client;
+	constructor(ctx, options = {}, name = TRADING_US_MARKET_DATA_KEY) {
+		super(ctx, name);
+		this.client = new YahooRestClient(options);
+	}
+	getTicker(symbol) {
+		return this.client.getTicker(symbol);
+	}
+	getKlines(symbol, interval, limit) {
+		return this.client.getKlines(symbol, interval).then((all) => typeof limit === "number" && Number.isInteger(limit) && limit > 0 ? all.slice(-limit) : all);
+	}
+	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: `us_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，与 crypto 先例一致；服务故障才用错误词汇）。 */
+function validatePlaceOrderArgs(args) {
+	if (typeof args.symbol !== "string" || !args.symbol.trim()) throw new Error("us_place_order: invalid symbol — expected a US ticker like AAPL or BRK-B");
+	try {
+		normalizeYahooSymbol(args.symbol);
+	} catch (cause) {
+		throw new Error(`us_place_order: invalid symbol ${JSON.stringify(args.symbol)} — expected a US ticker like AAPL`, { cause });
+	}
+	if (args.side !== "BUY" && args.side !== "SELL") throw new Error(`us_place_order: invalid side ${JSON.stringify(args.side)} — expected BUY or SELL`);
+	if (args.type !== "MARKET" && args.type !== "LIMIT") throw new Error(`us_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(`us_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("us_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
+	};
+}
+async function buildDryRunReceipt(args, marketData) {
+	const symbol = normalizeYahooSymbol(args.symbol);
+	let reference;
+	try {
+		const ticker = await marketData.getTicker(symbol);
+		reference = {
+			source: "yahoo-regular-market",
+			price: ticker.price,
+			volume: ticker.volume,
+			timestamp: ticker.timestamp
+		};
+	} catch (error) {
+		reference = {
+			source: "yahoo-regular-market",
+			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. Yahoo Finance is a data source only (no trading API); the reference price is the latest regular-market price, which may not reflect pre/post-market moves.",
+		id: `dry-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+		symbol,
+		side: args.side.toLowerCase(),
+		type: args.type.toLowerCase(),
+		quantity: args.quantity,
+		...args.type === "LIMIT" ? { price: args.price } : {},
+		reference,
+		timestamp: Date.now()
+	});
+}
+/**
+* us_place_order 工具工厂（独立导出便于单测三条闸门路径）。
+*
+* 审批不在这里做：dryRun!==true 的调用由 @dshtrading/base 的 gate 插件在
+* `tools/pre-execute` waterfall 统一 ask（S4：headless 下 ask=deny，fail-closed）。
+*/
+function createPlaceOrderTool(deps) {
+	return defineTool({
+		name: "us_place_order",
+		description: "Place a US stock order, or simulate one. dryRun defaults to true and returns a DRY-RUN simulated fill receipt referencing the latest Yahoo Finance regular-market price. Real execution (dryRun=false) requires the plugin liveTrading switch plus user approval, and is not implemented yet in this slice (Yahoo has no trading API).",
+		parameters: {
+			symbol: {
+				type: "string",
+				required: true,
+				description: "US stock ticker, e.g. AAPL or BRK-B"
+			},
+			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(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(args, deps.marketData);
+			throw new TradingServiceError("TRADING_NOT_IMPLEMENTED", "us_place_order: live order execution is not implemented in this slice — Yahoo Finance provides market data only; a broker API (e.g. Alpaca/IBKR) is a follow-up. Keep dryRun=true for simulated fills.");
+		}
+	});
+}
+function apply(ctx, config) {
+	new YahooMarketDataService(ctx);
+	ctx.inject(["tradingUsMarketData"], (ctx) => {
+		const marketData = ctx.tradingUsMarketData;
+		ctx.tools.register(defineTool({
+			name: "us_get_ticker",
+			description: "Get the latest market snapshot for a US stock via the Yahoo Finance v8 chart API (unofficial; no key). Returns the latest regular-market price/time (meta.regularMarketPrice/Time), the official previous close as prevClose (change anchor) with changePercent, and the session volume (meta.regularMarketVolume — official figure, unaffected by Yahoo's daily-bar consolidation lag). Personal use per Yahoo terms of use.",
+			parameters: { symbol: {
+				type: "string",
+				required: true,
+				description: "US stock ticker, e.g. AAPL or BRK-B (normalized to upper-case 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: "us_get_klines",
+			description: "Get recent OHLCV candles for a US stock via the Yahoo Finance v8 chart API (unofficial; no key). Supported intervals: 1m/5m/15m/30m (intraday history is limited by Yahoo: 1m caps at ~7 days), 1h, 1d, 1w, 1M. Personal use per Yahoo terms of use.",
+			parameters: {
+				symbol: {
+					type: "string",
+					required: true,
+					description: "US stock ticker, e.g. AAPL or BRK-B (normalized to upper-case internally)"
+				},
+				interval: {
+					type: "string",
+					enum: INTERVAL_VOCABULARY,
+					description: "Kline interval (Yahoo-supported subset)",
+					default: "1d"
+				},
+				limit: {
+					type: "integer",
+					description: "Number of most recent candles to return (1-1000; the client fetches a fixed window and the tool trims)",
+					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_US_MARKET_DATA_KEY, TradingServiceError, YahooMarketDataService, YahooRestClient, apply, buildDryRunReceipt, createPlaceOrderTool, evaluateOrderGate, inject, isSupportedInterval, name, normalizeYahooSymbol, parseChartBars };

package/lib/rest.d.ts

@@ -0,0 +1,77 @@
+import { Interval, Kline, 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);
+}
+/** 规范化并校验符号：接受 `AAPL` / `aapl` / `brk-b`，统一为大写；不补任何后缀。 */
+declare function normalizeYahooSymbol(symbol: string): string;
+/** 工具 parameters enum 用：受支持 interval 词汇（与 connector-stooq 同一子集口径）。 */
+declare const INTERVAL_VOCABULARY: readonly string[];
+declare function isSupportedInterval(value: Interval): boolean;
+/** v8 chart 响应的最小类型面（只取本客户端消费的字段）。 */
+interface YahooChartResult {
+  meta: {
+    currency?: string;
+    regularMarketPrice?: number;
+    regularMarketTime?: number;
+    regularMarketDayHigh?: number;
+    regularMarketDayLow?: number;
+    regularMarketVolume?: number;
+    regularMarketChangePercent?: number;
+    /** range 窗口首根前一收盘的锚点（range=1d 时即官方昨收，见 getTicker 注释）。 */
+    chartPreviousClose?: number;
+    previousClose?: number;
+    exchangeTimezoneName?: string;
+  };
+  timestamp: number[];
+  indicators: {
+    quote: Array<{
+      open?: Array<number | null>;
+      high?: Array<number | null>;
+      low?: Array<number | null>;
+      close?: Array<number | null>;
+      volume?: Array<number | null>;
+    }>;
+  };
+}
+interface YahooChartEnvelope {
+  chart: {
+    error?: {
+      code?: string;
+      description?: string;
+    } | null;
+    result?: YahooChartResult[] | null;
+  };
+}
+/** 把 timestamp[] + quote 序列对齐成 Kline[]（旧→新；null 行如实丢弃）。 */
+declare function parseChartBars(result: YahooChartResult, interval: Interval): Kline[];
+interface YahooRestOptions {
+  /** 覆盖 API base（测试/反代用），末尾不带斜杠。query2 是同一服务的备用主机。 */
+  readonly baseUrl?: string;
+  /** 单请求超时（ms），默认 10s。 */
+  readonly timeoutMs?: number;
+  /** 注入 fetch 实现；缺省用全局 fetch（Node 22+ 内置）。 */
+  readonly fetchImpl?: typeof fetch;
+  /** 覆盖 User-Agent（默认 Mozilla/5.0 裸 UA，实测够用）。 */
+  readonly userAgent?: string;
+}
+declare class YahooRestClient {
+  #private;
+  constructor(options?: YahooRestOptions);
+  /** 拉取并解析 K 线（旧→新全窗口，由服务层按 limit 截尾）。 */
+  getKlines(symbol: string, interval: Interval): Promise<Kline[]>;
+  /**
+   * 最新行情快照：单请求 interval=1d&range=1d。
+   * price/time/volume/prevClose 全取 meta（权威实时面）：昨收锚点取 meta.chartPreviousClose
+   * ——range=1d 窗口恰只含最新一个会话，其「窗口首根前一收盘」即官方昨收，与富途等终端
+   * 同语义（2026-09-01 AAPL 实测 319.7，富途同值）。不能用 range=5d：其 chartPreviousClose
+   * 锚在窗口首根前一收盘（≈6 个交易日前）；bars[len-2] 兜底也不可靠——日 K 序列存在
+   * 「最新收盘交易日滞后补齐/跳缺」的 vintage 行为（模块头注记），缺口期会错位一个交易日。
+   * 日线滞后窗口内 bars 可能为空：仅凭 meta 仍能出全量快照，不再因缺 bar 抛错。
+   */
+  getTicker(symbol: string): Promise<Ticker>;
+}
+//#endregion
+export { INTERVAL_VOCABULARY, TradingServiceError, YahooChartEnvelope, YahooChartResult, YahooRestClient, YahooRestOptions, isSupportedInterval, normalizeYahooSymbol, parseChartBars };

package/lib/rest.js

@@ -0,0 +1,175 @@
+//#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;
+	}
+};
+/** Yahoo 符号：字母/数字或指数前导 `^` 开头，可含 `.` `-` `^`（ADR/优先股/指数写法）。 */
+const YAHOO_SYMBOL_PATTERN = /^[A-Z0-9^][A-Z0-9.\-^]{0,15}$/;
+/** 规范化并校验符号：接受 `AAPL` / `aapl` / `brk-b`，统一为大写；不补任何后缀。 */
+function normalizeYahooSymbol(symbol) {
+	if (typeof symbol !== "string" || !symbol.trim()) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", "Symbol must be a non-empty string, e.g. AAPL or BRK-B");
+	const normalized = symbol.trim().toUpperCase();
+	if (!YAHOO_SYMBOL_PATTERN.test(normalized)) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `Symbol ${JSON.stringify(symbol)} is not a valid Yahoo Finance symbol (expected like AAPL / BRK-B / 7203.T)`);
+	return normalized;
+}
+/** api Interval 词汇的受支持子集 → Yahoo `interval=` 值。 */
+const INTERVAL_TO_YAHOO = /* @__PURE__ */ new Map([
+	["1m", "1m"],
+	["5m", "5m"],
+	["15m", "15m"],
+	["30m", "30m"],
+	["1h", "60m"],
+	["1d", "1d"],
+	["1w", "1wk"],
+	["1M", "1mo"]
+]);
+/** 工具 parameters enum 用：受支持 interval 词汇（与 connector-stooq 同一子集口径）。 */
+const INTERVAL_VOCABULARY = [...INTERVAL_TO_YAHOO.keys()];
+function isSupportedInterval(value) {
+	return INTERVAL_TO_YAHOO.has(value);
+}
+/** 每个 interval 的默认取数窗口（1m 上限 7 天；日线给足近三年——服务层再按 limit 截尾）。 */
+const RANGE_BY_INTERVAL = /* @__PURE__ */ new Map([
+	["1m", "7d"],
+	["5m", "1mo"],
+	["15m", "1mo"],
+	["30m", "1mo"],
+	["1h", "3mo"],
+	["1d", "3y"],
+	["1w", "5y"],
+	["1M", "10y"]
+]);
+/** 单根 K 线名义时长（ms），closeTime = openTime + 时长 − 1。1M 按 30 天近似（月界不精确，工具语义足够）。 */
+const INTERVAL_MS = /* @__PURE__ */ new Map([
+	["1m", 6e4],
+	["5m", 3e5],
+	["15m", 9e5],
+	["30m", 18e5],
+	["1h", 36e5],
+	["1d", 864e5],
+	["1w", 6048e5],
+	["1M", 2592e6]
+]);
+/** 把 timestamp[] + quote 序列对齐成 Kline[]（旧→新；null 行如实丢弃）。 */
+function parseChartBars(result, interval) {
+	const quote = result.indicators.quote[0] ?? {};
+	const periodMs = INTERVAL_MS.get(interval) ?? 864e5;
+	const bars = [];
+	for (let i = 0; i < result.timestamp.length; i++) {
+		const close = quote.close?.[i];
+		if (close == null) continue;
+		const openTime = result.timestamp[i] * 1e3;
+		bars.push({
+			openTime,
+			open: quote.open?.[i] ?? close,
+			high: quote.high?.[i] ?? close,
+			low: quote.low?.[i] ?? close,
+			close,
+			volume: quote.volume?.[i] ?? 0,
+			closeTime: openTime + periodMs - 1
+		});
+	}
+	return bars;
+}
+const DEFAULT_BASE_URL = "https://query1.finance.yahoo.com";
+const DEFAULT_TIMEOUT_MS = 1e4;
+/** 非官方 API 但需浏览器特征头；Mozilla/5.0 裸 UA 实测即可（2026-08-29 本出口）。 */
+const DEFAULT_USER_AGENT = "Mozilla/5.0";
+var YahooRestClient = class {
+	#baseUrl;
+	#timeoutMs;
+	#fetchImpl;
+	#userAgent;
+	constructor(options = {}) {
+		this.#baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+		this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		this.#fetchImpl = options.fetchImpl ?? ((input, init) => globalThis.fetch(input, init));
+		this.#userAgent = options.userAgent ?? DEFAULT_USER_AGENT;
+	}
+	async #requestChart(symbol, interval, rangeOverride) {
+		const sym = normalizeYahooSymbol(symbol);
+		const yInterval = INTERVAL_TO_YAHOO.get(interval);
+		if (yInterval === void 0) throw new TradingServiceError("TRADING_UNSUPPORTED_INTERVAL", `Yahoo klines: unsupported interval ${String(interval)} — supported: ${INTERVAL_VOCABULARY.join("/")}`);
+		const range = rangeOverride ?? RANGE_BY_INTERVAL.get(interval) ?? "1y";
+		const query = new URLSearchParams({
+			interval: yInterval,
+			range
+		});
+		const target = `${this.#baseUrl}/v8/finance/chart/${encodeURIComponent(sym)}?${query}`;
+		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(target, {
+				signal: controller.signal,
+				headers: {
+					accept: "application/json",
+					"user-agent": this.#userAgent
+				}
+			});
+		} catch (cause) {
+			const timedOut = controller.signal.aborted;
+			throw new TradingServiceError("TRADING_NETWORK", timedOut ? `Yahoo chart ${sym}: request timed out after ${this.#timeoutMs}ms` : `Yahoo chart ${sym}: network error`, cause);
+		} finally {
+			clearTimeout(timer);
+		}
+		if (!res.ok) throw new TradingServiceError(res.status === 429 ? "TRADING_RATE_LIMITED" : "TRADING_EXCHANGE_ERROR", `Yahoo chart ${sym}: HTTP ${res.status} ${res.statusText}`);
+		let envelope;
+		try {
+			envelope = await res.json();
+		} catch (cause) {
+			throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Yahoo chart ${sym}: response is not valid JSON`, cause);
+		}
+		if (envelope.chart.error) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Yahoo chart ${sym}: upstream error ${envelope.chart.error.code ?? ""} ${envelope.chart.error.description ?? ""}`.trim());
+		const result = envelope.chart.result?.[0];
+		if (!result || !Array.isArray(result.timestamp) || result.timestamp.length === 0) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `Yahoo chart ${sym}: no data rows (unknown/delisted symbol?)`);
+		return result;
+	}
+	/** 拉取并解析 K 线（旧→新全窗口，由服务层按 limit 截尾）。 */
+	async getKlines(symbol, interval) {
+		const sym = normalizeYahooSymbol(symbol);
+		const bars = parseChartBars(await this.#requestChart(sym, interval), interval);
+		if (bars.length === 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Yahoo klines for ${sym}: no non-null bars in range`);
+		return bars;
+	}
+	/**
+	* 最新行情快照：单请求 interval=1d&range=1d。
+	* price/time/volume/prevClose 全取 meta（权威实时面）：昨收锚点取 meta.chartPreviousClose
+	* ——range=1d 窗口恰只含最新一个会话，其「窗口首根前一收盘」即官方昨收，与富途等终端
+	* 同语义（2026-09-01 AAPL 实测 319.7，富途同值）。不能用 range=5d：其 chartPreviousClose
+	* 锚在窗口首根前一收盘（≈6 个交易日前）；bars[len-2] 兜底也不可靠——日 K 序列存在
+	* 「最新收盘交易日滞后补齐/跳缺」的 vintage 行为（模块头注记），缺口期会错位一个交易日。
+	* 日线滞后窗口内 bars 可能为空：仅凭 meta 仍能出全量快照，不再因缺 bar 抛错。
+	*/
+	async getTicker(symbol) {
+		const sym = normalizeYahooSymbol(symbol);
+		const result = await this.#requestChart(sym, "1d", "1d");
+		const bars = parseChartBars(result, "1d");
+		const last = bars[bars.length - 1];
+		const price = result.meta.regularMarketPrice ?? last?.close;
+		if (price === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Yahoo ticker for ${sym}: no price in meta and no bars`);
+		const prevClose = result.meta.chartPreviousClose ?? result.meta.previousClose ?? (bars.length >= 2 ? bars[bars.length - 2]?.close : void 0);
+		const changePercent = typeof result.meta.regularMarketChangePercent === "number" ? result.meta.regularMarketChangePercent : prevClose !== void 0 && prevClose > 0 ? (price - prevClose) / prevClose * 100 : void 0;
+		const timestamp = result.meta.regularMarketTime != null ? result.meta.regularMarketTime * 1e3 : last?.closeTime;
+		if (timestamp === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Yahoo ticker for ${sym}: no timestamp in meta and no bars`);
+		const name = result.meta.shortName ?? result.meta.longName;
+		const volume = result.meta.regularMarketVolume ?? last?.volume;
+		return {
+			symbol: sym,
+			...name ? { name } : {},
+			price,
+			timestamp,
+			...volume !== void 0 ? { volume } : {},
+			...prevClose !== void 0 ? { prevClose } : {},
+			...changePercent !== void 0 ? { changePercent } : {}
+		};
+	}
+};
+//#endregion
+export { INTERVAL_VOCABULARY, TradingServiceError, YahooRestClient, isSupportedInterval, normalizeYahooSymbol, parseChartBars };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@dshtrading/connector-yahoo",
+  "description": "US market connector plugin for dsh-trading: public market data from the Yahoo Finance v8 chart API implementing the @dshtrading/api contracts (unofficial API, no key; personal use per Yahoo terms of use)",
+  "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"
+  }
+}