yahoo-finance2

yahoo-finance2

此技能的用途

当任务涉及 yahoo-finance2 时使用此技能，包括：

• 在服务端 JavaScript/TypeScript 应用中添加 Yahoo Finance 市场数据。
• 在 quote、chart、historical、quoteSummary、 fundamentalsTimeSeries、screener、options 或其他模块中进行选择。
• 使用软件包 CLI 或内置的 MCP 服务。
• 修改此仓库的 Deno 源码、测试、生成的 schema、文档或 npm 输出构建。

这是一个非官方的 Yahoo Finance 客户端。请勿将其描述为受支持的 Yahoo API，也不要假设 Yahoo 数据的可用性、时效性或格式有保证。

使用软件包

优先使用 v3 类 API：

import YahooFinance from "yahoo-finance2";

const yahooFinance = new YahooFinance();
const quote = await yahooFinance.quote("AAPL");
console.log(quote?.regularMarketPrice, quote?.currency);

请勿使用旧版 v1/v2 单例模式，例如 yahooFinance.setGlobalConfig()。在 v3 中，使用 new YahooFinance(options) 实例化。

此软件包适用于服务端运行环境。请勿在浏览器/客户端包中直接调用 Yahoo Finance；Yahoo 的 CORS 和 cookie 行为要求使用服务端、 无服务器、边缘、Deno、Bun 或 Node 环境。

模块选择

• 符号不确定时，先使用 search(query)。
• 使用 quote(symbolOrSymbols) 获取当前或近实时的报价字段。它 接受单个符号或数组。使用 fields 限制载荷；若需按键访问，请请求对象或映射返回值。
• 当许多独立代码路径都需要报价数据时，使用 quoteCombine(symbol)； 它会对多个单符号调用进行防抖，将其合并为更少的 quote() 请求。
• 使用 chart(symbol, { period1, period2, interval }) 获取适用于图表的历史 数据，其中包含股息和拆股等事件。return: "array" 更便于 遍历；return: "object" 则与 Yahoo 的原生格式一致。
• 使用 historical() 获取更简单的 OHLCV 历史数据接口。
• 使用 quoteSummary(symbol, { modules }) 获取简介、价格、摘要详情、 文件申报、持股、建议和其他报价摘要模块。仅请求所需模块。
• 使用 fundamentalsTimeSeries() 获取财务报表。自 2024 年末起， incomeStatementHistory、balanceSheetHistory 和 cashflowStatementHistory 等报价摘要财务报表模块提供的数据很少。
• 使用 options(symbol) 获取期权链。
• 请使用 screener()，而不要使用已移除/弃用的每日涨幅榜或跌幅榜 模块。常见的预定义筛选器包括 day_gainers、day_losers 和 most_actives。
• 使用 trendingSymbols(region)、recommendationsBySymbol() 和 insights() 调用对应的 Yahoo Finance 专用端点。

可靠性、验证和错误

请使用 try/catch 包装模块调用。网络错误、Yahoo API 错误、已退市 符号、数据缺失和验证失败都属于预期的运行情况。

默认情况下，返回的数据会经过验证和强制转换，以便将已知日期转换为 Date 对象，并确保已知结果格式可安全使用。如果验证失败，通常最好修正 类型化接口并重新生成 schema，而不是关闭验证。

只有在调用方接受 unknown 输出并自行执行检查时，才使用 { validateResult: false }。 只有在试验库尚未建模的 Yahoo 查询参数时，才使用 { validateOptions: false }。

默认客户端队列会限制并发的 Yahoo 请求。需要更严格的速率控制时，请使用构造函数或单次调用的 queue 选项：

const yahooFinance = new YahooFinance({
  queue: { concurrency: 2, interval: 250 },
});

CLI 和 MCP

如需快速通过 shell 使用：

npx yahoo-finance2 search AMZN
npx yahoo-finance2 quote AAPL
npx yahoo-finance2 quoteSummary NVDA '{"modules":["assetProfile","secFilings"]}'

看起来像 JSON 的位置参数会被解析为 JSON。成功的管道输出可安全用于 JSON。

对于 MCP 客户端，此软件包包含一个只读的 Yahoo Finance MCP 服务：

npx -y -p yahoo-finance2 yahoo-finance-mcp

有关 stdio、HTTP、嵌入式处理程序和客户端注册的详情，请参阅 docs/mcp.md。

在此存储库中贡献

请先阅读 AGENTS.md 和 CONTRIBUTING.md。此存储库优先使用 Deno 和 TypeScript；npm 输出由生成流程创建。

请编辑 src/ 下的源文件，而不是 npm/ 下的生成文件，除非任务明确要求生成输出。保留本地 .ts 导入扩展名。

公共模块文件通常遵循以下模式：

• 类型化的查询／结果接口是事实来源。
• 带有 @yf-schema 的文件会导入生成的 .schema.json。
• 模块函数使用查询默认值、运行时参数、可选转换、结果转换、架构键和模块选项调用 this._moduleExec()。
• 重载用于区分已验证的结果与 { validateResult: false }；后者会返回 unknown。

更改带有 @yf-schema 标记的文件中导出的接口时，请运行：

deno task schema

如果要添加模块，请通过 src/modules/index.ts、deno.json 导出项、文档／README 链接、README 模块列表（如相关）、测试，以及仅在模块应面向用户公开时需要的 CLI／MCP 接入，将其接入。

测试和固定样例

运行所有测试：

deno task test

运行指定测试：

deno task test src/modules/quote.test.ts

调试或限制 Yahoo 实时请求并发时，请使用 deno task test:serial src/modules/quote.test.ts。

涉及 Yahoo HTTP 响应的测试应调用 tests/common.ts 中的 setupCache()。优先采用现有模式：

const YahooFinance = createTestYahooFinance({ modules: { quote } });
const yf = new YahooFinance();

describe("quote", () => {
  setupCache();

  it("passes validation", async (t, onFinish) => {
    await yf.quote("AAPL", {}, {
      devel: { id: "quote-AAPL", t, onFinish },
    });
  });
});

固定样例 ID 应与模块和场景相符。FETCH_DEVEL=nocache 会强制发起实时网络请求。FETCH_DEVEL=recache 会为失败的测试刷新缓存文件。请勿重新缓存以 .static.json 或 .fake.json 结尾的固定样例；它们有意保持稳定或为合成数据。

修复验证失败时，请检查验证错误路径和缓存的 Yahoo 响应，先更新 TypeScript 接口，再运行架构生成，最后运行指定测试。

构建、lint 和发布范围

请酌情运行以下检查：

deno fmt
deno lint
deno task test
deno task build:npm

scripts/build_npm.ts 控制生成的 npm 包元数据、二进制文件、依赖项、复制的文件和包关键词。除非明确要求重新生成 npm/，否则请在此处维护 npm 包相关更改。

提交消息应使用带作用域的 Conventional Commits，例如 fix(quote): handle missing extended market fields。

Agent 技能安装

规范技能位于 skills/yahoo-finance2/SKILL.md。如要通过 Skills CLI 安装，并使其显示在 skills.sh 遥测中，请使用：

npx skills add gadicc/yahoo-finance2