@dshtrading/kit-us 0.1.0

package/lib/fundamentals.d.ts

@@ -0,0 +1,28 @@
+import { CompanyProfile, FinancialReportMatrix, FundamentalsPackage, StockFundamentals } from "./api/lib/index.js";
+//#region src/fundamentals.d.ts
+interface UsFundamentalsOptions {
+  symbol: string;
+  fetch?: typeof globalThis.fetch;
+}
+interface UsFundamentalsResult {
+  data?: StockFundamentals;
+  beta?: number;
+  fiftyTwoWeekChangePercent?: number;
+  avgVolume3Month?: number;
+  currency?: string;
+  exchange?: string;
+  unavailable?: string[];
+}
+/** US ticker 白名单校验（2026-09-02 整改）：CN/HK 有严格正则，US 原先裸插值进 URL path。 */
+declare function normalizeUsSymbol(input: string): string;
+declare function fetchUsFundamentals(options: UsFundamentalsOptions): Promise<UsFundamentalsResult>;
+/** 从 Yahoo Finance quoteSummary 动态拉取美股多期财务报表与指标矩阵。 */
+declare function fetchUsFinancialMatrix(symbol: string, fetchImpl?: typeof globalThis.fetch): Promise<{
+  matrix?: FinancialReportMatrix;
+  profile?: CompanyProfile;
+}>;
+/** 获取完整美股基本面数据包。 */
+declare function fetchUsFundamentalsPackage(symbol: string, fetchImpl?: typeof globalThis.fetch): Promise<FundamentalsPackage>;
+declare function renderUsFundamentals(result: UsFundamentalsResult, requestedSymbol: string): string;
+//#endregion
+export { UsFundamentalsOptions, UsFundamentalsResult, fetchUsFinancialMatrix, fetchUsFundamentals, fetchUsFundamentalsPackage, normalizeUsSymbol, renderUsFundamentals };

package/lib/fundamentals.js

@@ -0,0 +1,267 @@
+//#region src/fundamentals.ts
+const YAHOO_QUOTE_URL = "https://query1.finance.yahoo.com/v7/finance/quote";
+const YAHOO_CHART_URL = "https://query2.finance.yahoo.com/v8/finance/chart";
+const YAHOO_UA = "Mozilla/5.0";
+/** 上游超时（2026-09-02 整改）：对齐 connector 模式，防挂起拖死桥请求。 */
+const UPSTREAM_TIMEOUT_MS = 1e4;
+/** US ticker 白名单校验（2026-09-02 整改）：CN/HK 有严格正则，US 原先裸插值进 URL path。 */
+function normalizeUsSymbol(input) {
+	const sym = input.trim().toUpperCase();
+	if (!/^[A-Z0-9.\-^=]{1,12}$/.test(sym)) throw new Error(`us_get_fundamentals: invalid US symbol ${JSON.stringify(input)} — expected e.g. AAPL, BRK.B, ^GSPC`);
+	return sym;
+}
+const usFundamentalsCache = /* @__PURE__ */ new Map();
+const US_FUNDAMENTALS_TTL_MS = 3e5;
+async function fetchUsFundamentals(options) {
+	const fetchImpl = options.fetch ?? globalThis.fetch;
+	const symbol = normalizeUsSymbol(options.symbol);
+	const unavailable = [];
+	const cached = usFundamentalsCache.get(symbol);
+	if (cached && cached.expiresAt > Date.now()) return cached.data;
+	const fmpApiKey = process.env.FMP_API_KEY;
+	if (fmpApiKey) try {
+		const fmpRes = await fetchImpl(`https://financialmodelingprep.com/api/v3/profile/${encodeURIComponent(symbol)}?apikey=${fmpApiKey}`, {
+			headers: { accept: "application/json" },
+			signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS)
+		});
+		if (fmpRes.ok) {
+			const p = (await fmpRes.json())?.[0];
+			if (p) {
+				let fiftyTwoWeekLow;
+				let fiftyTwoWeekHigh;
+				if (p.range) {
+					const parts = p.range.split("-");
+					if (parts.length === 2) {
+						fiftyTwoWeekLow = Number(parts[0]);
+						fiftyTwoWeekHigh = Number(parts[1]);
+					}
+				}
+				const result = {
+					data: {
+						symbol: p.symbol ?? symbol,
+						...p.companyName ? { name: p.companyName } : {},
+						...p.mktCap !== void 0 ? { marketCap: p.mktCap } : {},
+						...Number.isFinite(fiftyTwoWeekHigh) ? { fiftyTwoWeekHigh } : {},
+						...Number.isFinite(fiftyTwoWeekLow) ? { fiftyTwoWeekLow } : {},
+						timestamp: Date.now()
+					},
+					...p.beta !== void 0 ? { beta: p.beta } : {},
+					...p.volAvg !== void 0 ? { avgVolume3Month: p.volAvg } : {},
+					...p.currency ? { currency: p.currency } : {},
+					...p.exchangeShortName ? { exchange: p.exchangeShortName } : {},
+					unavailable
+				};
+				usFundamentalsCache.set(symbol, {
+					data: result,
+					expiresAt: Date.now() + US_FUNDAMENTALS_TTL_MS
+				});
+				return result;
+			}
+		}
+	} catch (err) {
+		unavailable.push(`fmp-official: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	try {
+		const url = new URL(YAHOO_QUOTE_URL);
+		url.searchParams.set("symbols", symbol);
+		const response = await fetchImpl(url.toString(), {
+			headers: {
+				accept: "application/json",
+				"user-agent": YAHOO_UA
+			},
+			signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS)
+		});
+		if (response.ok) {
+			const item = (await response.json()).quoteResponse?.result?.[0];
+			if (item) {
+				const dividendRate = item.dividendYield ?? item.trailingAnnualDividendYield;
+				return {
+					data: {
+						symbol: item.symbol ?? symbol,
+						name: item.shortName ?? item.longName,
+						marketCap: item.marketCap,
+						peTtm: item.trailingPE,
+						peDynamic: item.forwardPE,
+						pb: item.priceToBook,
+						eps: item.epsTrailingTwelveMonths,
+						dividendYield: dividendRate,
+						fiftyTwoWeekHigh: item.fiftyTwoWeekHigh,
+						fiftyTwoWeekLow: item.fiftyTwoWeekLow,
+						timestamp: Date.now()
+					},
+					beta: item.beta,
+					fiftyTwoWeekChangePercent: item.fiftyTwoWeekChangePercent,
+					avgVolume3Month: item.averageDailyVolume3Month,
+					currency: item.currency,
+					exchange: item.fullExchangeName,
+					unavailable
+				};
+			}
+		} else unavailable.push(`yahoo-quote: HTTP ${response.status}`);
+	} catch (err) {
+		unavailable.push(`yahoo-quote: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	try {
+		const chartRes = await fetchImpl(`${YAHOO_CHART_URL}/${encodeURIComponent(symbol)}?interval=1d`, {
+			headers: {
+				accept: "application/json",
+				"user-agent": YAHOO_UA
+			},
+			signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS)
+		});
+		if (chartRes.ok) {
+			const meta = (await chartRes.json()).chart?.result?.[0]?.meta;
+			if (meta) return {
+				data: {
+					symbol,
+					name: meta.shortName ?? meta.longName,
+					fiftyTwoWeekHigh: meta.fiftyTwoWeekHigh,
+					fiftyTwoWeekLow: meta.fiftyTwoWeekLow,
+					timestamp: Date.now()
+				},
+				fiftyTwoWeekChangePercent: meta.regularMarketChangePercent !== void 0 ? meta.regularMarketChangePercent / 100 : void 0,
+				avgVolume3Month: meta.regularMarketVolume,
+				currency: meta.currency,
+				exchange: meta.fullExchangeName,
+				unavailable
+			};
+		} else unavailable.push(`yahoo-chart-meta: HTTP ${chartRes.status}`);
+	} catch (err) {
+		unavailable.push(`yahoo-chart-meta: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	return { unavailable };
+}
+const usMatrixCache = /* @__PURE__ */ new Map();
+const US_MATRIX_TTL_MS = 864e5;
+/** 从 Yahoo Finance quoteSummary 动态拉取美股多期财务报表与指标矩阵。 */
+async function fetchUsFinancialMatrix(symbol, fetchImpl = globalThis.fetch) {
+	try {
+		const sym = normalizeUsSymbol(symbol);
+		const cached = usMatrixCache.get(sym);
+		if (cached && cached.expiresAt > Date.now()) return cached.data;
+		const res = await fetchImpl(`https://query1.finance.yahoo.com/v10/finance/quoteSummary/${encodeURIComponent(sym)}?modules=financialData,defaultKeyStatistics,incomeStatementHistoryQuarterly,balanceSheetHistoryQuarterly,cashflowStatementHistoryQuarterly,assetProfile`, {
+			headers: {
+				accept: "application/json",
+				"user-agent": YAHOO_UA
+			},
+			signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS)
+		});
+		if (!res.ok) return {};
+		const item = (await res.json()).quoteSummary?.result?.[0];
+		if (!item) return {};
+		const profile = {
+			symbol: sym,
+			industry: item.assetProfile?.industry,
+			sector: item.assetProfile?.sector,
+			description: item.assetProfile?.longBusinessSummary,
+			website: typeof item.assetProfile?.website === "string" && /^https?:/i.test(item.assetProfile.website) ? item.assetProfile.website : void 0,
+			executives: item.assetProfile?.companyOfficers?.slice(0, 5).map((o) => ({
+				name: o.name,
+				title: o.title
+			}))
+		};
+		const incomes = item.incomeStatementHistoryQuarterly?.incomeStatementHistory ?? [];
+		if (incomes.length === 0) return { profile };
+		const sortedIncomes = [...incomes].filter((i) => i.endDate?.fmt);
+		const periods = sortedIncomes.map((i) => i.endDate.fmt.slice(0, 7).replace("-", "/"));
+		for (let i = 1; i < periods.length; i++) if (periods[i] === periods[i - 1]) periods[i] = `${periods[i]}#${i}`;
+		const latestPeriod = periods[periods.length - 1] ?? "";
+		const latestReportTitle = latestPeriod ? `${latestPeriod} 季报` : void 0;
+		const revValues = {};
+		const netValues = {};
+		const grossMarginValues = {};
+		sortedIncomes.forEach((inc, idx) => {
+			const p = periods[idx];
+			const rev = inc.totalRevenue?.raw;
+			const net = inc.netIncome?.raw;
+			const gross = inc.grossProfit?.raw;
+			revValues[p] = { value: rev };
+			netValues[p] = { value: net };
+			const margin = rev && gross ? gross / rev * 100 : void 0;
+			grossMarginValues[p] = { value: margin };
+		});
+		const result = {
+			matrix: {
+				currency: "USD",
+				latestReportTitle,
+				periods,
+				groups: [{
+					id: "profitability",
+					title: "盈利与收益能力",
+					rows: [
+						{
+							id: "gross_margin",
+							name: "毛利率",
+							unit: "%",
+							values: grossMarginValues
+						},
+						{
+							id: "revenue",
+							name: "营业总收入",
+							unit: "USD",
+							values: revValues
+						},
+						{
+							id: "net_income",
+							name: "净利润",
+							unit: "USD",
+							values: netValues
+						}
+					]
+				}]
+			},
+			profile
+		};
+		usMatrixCache.set(sym, {
+			data: result,
+			expiresAt: Date.now() + US_MATRIX_TTL_MS
+		});
+		return result;
+	} catch {
+		return {};
+	}
+}
+/** 获取完整美股基本面数据包。 */
+async function fetchUsFundamentalsPackage(symbol, fetchImpl = globalThis.fetch) {
+	const sym = normalizeUsSymbol(symbol);
+	const [quoteRes, { matrix, profile }] = await Promise.all([fetchUsFundamentals({
+		symbol: sym,
+		fetch: fetchImpl
+	}), fetchUsFinancialMatrix(sym, fetchImpl)]);
+	return {
+		market: "us",
+		symbol: sym,
+		stock: quoteRes.data,
+		matrix,
+		profile: {
+			symbol: sym,
+			name: quoteRes.data?.name ?? sym,
+			...profile
+		}
+	};
+}
+function renderUsFundamentals(result, requestedSymbol) {
+	const { data, beta, fiftyTwoWeekChangePercent, avgVolume3Month, currency = "USD", exchange, unavailable = [] } = result;
+	if (!data) return `us_get_fundamentals ${requestedSymbol}: no fundamental data available.${unavailable.length > 0 ? ` (errors: ${unavailable.join("; ")})` : ""}`;
+	const lines = [`us_get_fundamentals ${data.symbol}${data.name ? ` (${data.name})` : ""}${exchange ? ` [${exchange}]` : ""}:`];
+	if (data.marketCap !== void 0) lines.push(`- Market Cap: \$${data.marketCap.toLocaleString(void 0, { maximumFractionDigits: 0 })} ${currency}`);
+	if (data.peTtm !== void 0) lines.push(`- Trailing PE (TTM): ${data.peTtm.toFixed(2)}`);
+	if (data.peDynamic !== void 0) lines.push(`- Forward PE: ${data.peDynamic.toFixed(2)}`);
+	if (data.pb !== void 0) lines.push(`- Price to Book (PB): ${data.pb.toFixed(2)}`);
+	if (data.eps !== void 0) lines.push(`- Diluted EPS (TTM): \$${data.eps.toFixed(2)}`);
+	if (data.dividendYield !== void 0) {
+		const pct = (data.dividendYield * (data.dividendYield < 1 ? 100 : 1)).toFixed(2);
+		lines.push(`- Dividend Yield: ${pct}%`);
+	}
+	if (beta !== void 0) lines.push(`- Beta (5Y Monthly): ${beta.toFixed(2)}`);
+	if (data.fiftyTwoWeekLow !== void 0 && data.fiftyTwoWeekHigh !== void 0) lines.push(`- 52-Week Range: \$${data.fiftyTwoWeekLow.toFixed(2)} - \$${data.fiftyTwoWeekHigh.toFixed(2)}`);
+	if (fiftyTwoWeekChangePercent !== void 0) {
+		const pct = (fiftyTwoWeekChangePercent * (Math.abs(fiftyTwoWeekChangePercent) < 1 ? 100 : 1)).toFixed(2);
+		lines.push(`- 52-Week Change: ${Number(pct) > 0 ? "+" : ""}${pct}%`);
+	}
+	if (avgVolume3Month !== void 0) lines.push(`- Volume / Avg Volume: ${avgVolume3Month.toLocaleString()} shares`);
+	if (unavailable.length > 0) lines.push(`  (partially unavailable details: ${unavailable.join("; ")})`);
+	return lines.join("\n");
+}
+//#endregion
+export { fetchUsFinancialMatrix, fetchUsFundamentals, fetchUsFundamentalsPackage, normalizeUsSymbol, renderUsFundamentals };

package/lib/index.d.ts

@@ -0,0 +1,21 @@
+import { UsFundamentalsOptions, UsFundamentalsResult, fetchUsFinancialMatrix, fetchUsFundamentals, fetchUsFundamentalsPackage, normalizeUsSymbol, renderUsFundamentals } from "./fundamentals.js";
+import { AggregateNewsOptions, AggregateNewsResult, NewsItem, NewsSource, aggregateNews, parseGoogleNewsRss, parseSecEdgarAtom } from "./news.js";
+import Schema from "@deepseek-ai/schemastery";
+import { SkillProvider } from "@deepseek-ai/dsh-skill";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/index.d.ts
+declare const provider: SkillProvider;
+interface Config {
+  dryRun: boolean;
+  liveTrading: boolean;
+}
+declare const Config: Schema<Config>;
+declare const inject: string[];
+declare const name = "dsh-trading-us-kit";
+declare function apply(ctx: Context, _config: Config): void;
+declare function createGetNewsTool(): import("@deepseek-ai/dsh-tools").ToolDefinition;
+declare function createGetFundamentalsTool(options?: {
+  fetch?: typeof globalThis.fetch;
+}): import("@deepseek-ai/dsh-tools").ToolDefinition;
+//#endregion
+export { AggregateNewsOptions, AggregateNewsResult, Config, NewsItem, NewsSource, UsFundamentalsOptions, UsFundamentalsResult, aggregateNews, apply, createGetFundamentalsTool, createGetNewsTool, fetchUsFinancialMatrix, fetchUsFundamentals, fetchUsFundamentalsPackage, inject, name, normalizeUsSymbol, parseGoogleNewsRss, parseSecEdgarAtom, provider, renderUsFundamentals };

package/lib/index.js

@@ -0,0 +1,224 @@
+import { aggregateNews, parseGoogleNewsRss, parseSecEdgarAtom } from "./news.js";
+import { fetchUsFinancialMatrix, fetchUsFundamentals, fetchUsFundamentalsPackage, normalizeUsSymbol, renderUsFundamentals } from "./fundamentals.js";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import Schema from "@deepseek-ai/schemastery";
+import { BUNDLED_SKILL_RANK } from "@deepseek-ai/dsh-skill";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { createGetIndicatorsTool } from "@dshtrading/indicators/tool";
+//#region src/index.ts
+/**
+* US 工具箱插件（dsh-trading us 切片）。
+*
+* 包含：
+*   1. skill provider：us-risk-checklist、indicator-authoring、trading-strategy-paradigms、knowledge-curation 与 trading-notes-setup 随包分发；
+*   2. us_get_news 与 us_get_fundamentals 工具；
+*   3. indicator_author 创作工具（Issue #19）；
+*   4. knowledge_ingest 与 knowledge_search 知识库工具（Issue #24）。
+*
+* @module @dshtrading/kit-us
+*/
+const PROVIDER_NAME = "dsh-trading-us";
+const SKILL_BODY_URL = new URL("../assets/skills/us-risk-checklist.md", import.meta.url);
+const AUTHORING_BODY_URL = new URL("../assets/skills/indicator-authoring.md", import.meta.url);
+const STRATEGY_BODY_URL = new URL("../assets/skills/trading-strategy-paradigms.md", import.meta.url);
+const KNOWLEDGE_CURATION_BODY_URL = new URL("../assets/skills/knowledge-curation.md", import.meta.url);
+const JOURNAL_BODY_URL = new URL("../assets/skills/trading-notes-setup.md", import.meta.url);
+const RESOURCE_BASE = {
+	kind: "directory",
+	path: fileURLToPath(new URL("../assets/skills/", import.meta.url))
+};
+const CANDIDATE = {
+	name: "us-risk-checklist",
+	description: "美股交易风控检查清单：开仓前逐项核对盘前盘后流动性、熔断与停牌、做空规则、T+1 与 PDT 日内限制、财报跳空风险。",
+	invocation: {
+		modelInvocable: true,
+		userInvocable: true
+	},
+	provider: PROVIDER_NAME,
+	source: "bundled",
+	resourceBase: RESOURCE_BASE,
+	rank: BUNDLED_SKILL_RANK,
+	locator: SKILL_BODY_URL
+};
+const SKILL_CANDIDATES = [
+	CANDIDATE,
+	{
+		name: "indicator-authoring",
+		description: "自定义技术指标创作指南：根据用户自然语言需求生成符合契约的指标代码（TD9/SuperTrend/OBV+MA等），并通过 indicator_author 工具验证与落库。",
+		invocation: {
+			modelInvocable: true,
+			userInvocable: true
+		},
+		provider: PROVIDER_NAME,
+		source: "bundled",
+		resourceBase: RESOURCE_BASE,
+		rank: BUNDLED_SKILL_RANK,
+		locator: AUTHORING_BODY_URL
+	},
+	{
+		name: "trading-strategy-paradigms",
+		description: "经典交易策略参考范式指南：提供短线（唐奇安突破/RSI极值回归）、波段（EMA双均线/布林带下轨回归）、长线（200日均线基线/12月动量）6大策略原理、参数调优、8项回测指标研读与风险防范 SOP。",
+		invocation: {
+			modelInvocable: true,
+			userInvocable: true
+		},
+		provider: PROVIDER_NAME,
+		source: "bundled",
+		resourceBase: RESOURCE_BASE,
+		rank: BUNDLED_SKILL_RANK,
+		locator: STRATEGY_BODY_URL
+	},
+	{
+		name: "knowledge-curation",
+		description: "财经观点沉淀与知识库策展指南：基于 Content Insight 事实核查产物，规范化提取知识卡片字段、受控词表对齐、查重与关联建立，通过 knowledge_ingest 工具入库。",
+		invocation: {
+			modelInvocable: true,
+			userInvocable: true
+		},
+		provider: PROVIDER_NAME,
+		source: "bundled",
+		resourceBase: RESOURCE_BASE,
+		rank: BUNDLED_SKILL_RANK,
+		locator: KNOWLEDGE_CURATION_BODY_URL
+	},
+	{
+		name: "trading-notes-setup",
+		description: "交易日志建立与记录规范：检查/创建工作区 .trading-journal/ 双轨目录（agent 轨 + human 轨），分别记录 agent 与人类各自的操作。会话启动检查发现工作区没有交易日志目录时调用本技能建立骨架；记录条目格式以本技能为权威。",
+		invocation: {
+			modelInvocable: true,
+			userInvocable: true
+		},
+		provider: PROVIDER_NAME,
+		source: "bundled",
+		resourceBase: RESOURCE_BASE,
+		rank: BUNDLED_SKILL_RANK,
+		locator: JOURNAL_BODY_URL
+	}
+];
+const provider = {
+	name: PROVIDER_NAME,
+	list: () => Promise.resolve(SKILL_CANDIDATES),
+	async get(candidate) {
+		const target = SKILL_CANDIDATES.find((c) => c.name === candidate.name) ?? CANDIDATE;
+		return {
+			name: target.name,
+			description: target.description,
+			invocation: target.invocation,
+			provider: target.provider,
+			source: target.source,
+			resourceBase: RESOURCE_BASE,
+			content: await readFile(target.locator, "utf8")
+		};
+	}
+};
+const Config = Schema.object({
+	dryRun: Schema.boolean().default(true),
+	liveTrading: Schema.boolean().default(false)
+});
+const inject = ["skills", "tools"];
+const name = "dsh-trading-us-kit";
+function apply(ctx, _config) {
+	ctx.skills.registerProvider(() => provider);
+	const newsTool = createGetNewsTool();
+	const fundamentalsTool = createGetFundamentalsTool();
+	const tools = ctx.tools;
+	const registerOnce = (tool) => {
+		if (tools.get(tool.name) !== void 0) {
+			ctx.logger("dsh-trading-us-kit").info("[dsh-trading-us-kit] tool %s already registered by another provider — skipped (mutual exclusion)", tool.name);
+			return;
+		}
+		tools.register(tool);
+	};
+	registerOnce(newsTool);
+	registerOnce(fundamentalsTool);
+	const serviceGetter = ctx;
+	const marketData = (serviceGetter.get?.("tradingMarketDataRegistry", false))?.active("us")?.service ?? serviceGetter.get?.("tradingUsMarketData", false);
+	if (marketData !== void 0) registerOnce(createGetIndicatorsTool({
+		marketData,
+		market: "us"
+	}));
+	const lifecycle = ctx;
+	lifecycle.inject?.(["tradingNewsRegistry"], (scope) => {
+		const registry = scope.tradingNewsRegistry;
+		if (registry && typeof registry.register === "function") lifecycle.effect?.(() => registry.register("us", aggregateNews), "kit-us news registration");
+	});
+}
+const DEFAULT_NEWS_WINDOW_HOURS = 24;
+const DEFAULT_NEWS_LIMIT = 20;
+function renderNewsItem(item) {
+	return `[${item.source}] ${item.publishedAt}  ${item.title}\n  ${item.url}`;
+}
+function createGetNewsTool() {
+	return defineTool({
+		name: "us_get_news",
+		description: "Get recent US stock market news from Yahoo Finance RSS and CNBC RSS feeds. Aggregates and sorts newest-first; each item carries source name, publish time and a link for traceability. Optionally filter by symbol (e.g. AAPL, TSLA, NVDA) and by a time window. Source failures are tolerated and reported instead of failing the whole call. No credentials required.",
+		parameters: {
+			symbol: {
+				type: "string",
+				description: "Optional US stock symbol to filter by (e.g. AAPL, TSLA, NVDA). Matched against item titles."
+			},
+			windowHours: {
+				type: "number",
+				description: `Only keep items published within the last N hours (1-168, default ${DEFAULT_NEWS_WINDOW_HOURS}).`,
+				default: DEFAULT_NEWS_WINDOW_HOURS
+			},
+			limit: {
+				type: "number",
+				description: `Max items to return (1-50, default ${DEFAULT_NEWS_LIMIT}).`,
+				default: DEFAULT_NEWS_LIMIT
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: String(value)
+			}]
+		},
+		async execute(raw) {
+			const args = raw ?? {};
+			const options = {
+				symbol: typeof args.symbol === "string" ? args.symbol : void 0,
+				windowHours: typeof args.windowHours === "number" ? args.windowHours : void 0,
+				limit: typeof args.limit === "number" ? args.limit : void 0
+			};
+			const { items, unavailable } = await aggregateNews(options);
+			if (items.length === 0 && unavailable.length === 0) return "us_get_news: no news items found within the requested window.";
+			const symbolNote = options.symbol ? ` symbol=${options.symbol.trim().toUpperCase()}` : "";
+			const lines = [`us_get_news — ${items.length} item(s)${symbolNote}, window=${options.windowHours ?? DEFAULT_NEWS_WINDOW_HOURS}h (newest-first):`, ...items.map(renderNewsItem)];
+			if (unavailable.length > 0) lines.push("  (source(s) unavailable this call: " + unavailable.join("; ") + ")");
+			return lines.join("\n");
+		}
+	});
+}
+function createGetFundamentalsTool(options = {}) {
+	return defineTool({
+		name: "us_get_fundamentals",
+		description: "Get fundamental valuation and financial indicators for US stocks (Market Cap, Trailing P/E, Forward P/E, P/B, Dividend Yield, Beta, 52-Week High/Low, EPS, 50-Day & 200-Day Moving Averages) via Stooq public equity data. Accepts market-canonical symbol (e.g. AAPL.US, TSLA.US) or pure ticker (AAPL, TSLA). No credentials required.",
+		parameters: { symbol: {
+			type: "string",
+			required: true,
+			description: "US stock symbol or ticker, market-canonical vocabulary, e.g. AAPL.US, TSLA.US, AAPL, TSLA"
+		} },
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: String(value)
+			}]
+		},
+		async execute(raw) {
+			const args = raw ?? {};
+			const symbol = typeof args.symbol === "string" ? args.symbol.trim() : "";
+			if (!symbol) throw new Error("us_get_fundamentals: symbol parameter is required (e.g. AAPL.US or AAPL)");
+			const result = await fetchUsFundamentals({
+				symbol,
+				fetch: options.fetch
+			});
+			return renderUsFundamentals(result, symbol);
+		}
+	});
+}
+//#endregion
+export { Config, aggregateNews, apply, createGetFundamentalsTool, createGetNewsTool, fetchUsFinancialMatrix, fetchUsFundamentals, fetchUsFundamentalsPackage, inject, name, normalizeUsSymbol, parseGoogleNewsRss, parseSecEdgarAtom, provider, renderUsFundamentals };

package/lib/news.d.ts

@@ -0,0 +1,45 @@
+//#region src/news.d.ts
+/**
+ * us_get_news 取数层（WS4 #1：#6 子工作流，spike/s impl-uscnhk-news EVIDENCE 推荐）。
+ *
+ * 两源均为单端点、无鉴权、无状态公共 GET（本出口实测）：
+ *   - Yahoo Finance news API（v8 家族，与既有 connector-yahoo 同族）——JSON，news[] 带 publisher/link/publishTime
+ *   - Google News RSS（news.google.com/rss/search）——RSS 2.0，<source> 为原始媒体名；link 为 Google 跳转链接
+ * 本模块只做取数 + 归一化为 NewsItem[]；时间窗/币种过滤 + 排序截尾；defineTool 装配在 index.ts。
+ * 铁律 #5：输出只带元数据（来源名/标题/链接/发布时间），不取正文，不缓存，不再分发。
+ * 每源独立容错：单源失败不炸整体，失败源在 `unavailable` 中注明，fail-soft。
+ */
+type NewsSource = 'yahoo' | 'googlenews';
+interface NewsItem {
+  /** 来源名（铁律 #5 的来源标注）。 */
+  source: string;
+  title: string;
+  url: string;
+  /** ISO 8601 发布时间。 */
+  publishedAt: string;
+}
+interface AggregateNewsOptions {
+  /** 标的（市场规范词汇，如 AAPL）；缺省 = 通用市场主题。 */
+  symbol?: string | undefined;
+  /** 时间窗（小时）：只保留 now - windowHours 内的条目；缺省 24。 */
+  windowHours?: number | undefined;
+  /** 输出条数上限；缺省 20。 */
+  limit?: number | undefined;
+  /** 依赖注入的 fetch（测试用 mock；缺省 globalThis.fetch）。 */
+  fetch?: typeof globalThis.fetch | undefined;
+  /** 注入当前时间戳（ms，测试用）；缺省 Date.now()。 */
+  now?: number | undefined;
+  /** CryptoPanic API token（桥面透传，us 聚合器忽略；对齐 api 契约形状）。 */
+  cryptoPanicKey?: string | undefined;
+}
+interface AggregateNewsResult {
+  items: NewsItem[];
+  /** 取数失败的源：`<匿名>`（如 'yahoo: HTTP 500 — ...'），工具输出需注明缺席。 */
+  unavailable: string[];
+}
+/** 解析 Google News RSS（title/link/pubDate/source；link 为 Google 跳转，溯源用 source）。 */
+declare function parseGoogleNewsRss(xml: string): NewsItem[];
+declare function parseSecEdgarAtom(xml: string): NewsItem[];
+declare function aggregateNews(options?: AggregateNewsOptions): Promise<AggregateNewsResult>;
+//#endregion
+export { AggregateNewsOptions, AggregateNewsResult, NewsItem, NewsSource, aggregateNews, parseGoogleNewsRss, parseSecEdgarAtom };