Corsair Marketstack 插件实战在 AI Agent 中接入全球股票行情数据【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair本篇技术指南围绕 Corsair 官方插件corsair-dev/marketstack展开讲解如何在 Corsair 应用中为终端用户接入 Marketstack 的股票市场数据能力——包括实时与历史 EODEnd-of-Day每日收盘行情、股票代码Ticker元数据、交易所、货币、股息与拆股数据。读完本文你将掌握插件的安装、认证配置、10 个只读端点的完整参数与返回结构以及底层调用链与错误重试机制可直接在你的 Corsair 应用如 LangChain / Mastra 等框架集成中落地使用。插件概述corsair-dev/marketstack是 Corsair 的官方插件包位于仓库 packages/marketstack定位是 Marketstack stock market data plugin for Corsair。它把 Marketstack v2 API 的能力封装为一组类型安全、可被权限系统管控、支持租户密钥托管的 Corsair 插件端点供 AI Agent 在对话或工作流中按需调用。从 index.ts 的注册结构可以确认该插件插件 ID 为marketstack只支持一种认证方式api_keymarketstackAuthConfig暴露 10 个端点全部为read风险级别见 plugin.test.ts 中对 10 个只读操作的注册断言不注册任何 WebhookmarketstackWebhooksNested为空对象README 中亦明确 No webhooks。安装使用 pnpm 安装插件包pnpm add corsair-dev/marketstack从 package.json 可见该包以corsair 0.1.0与zod ^4.1.13作为 peer 依赖输入输出校验基于 Zod 4 的 schema 体系实现类型声明随dist/index.d.ts一并发布。认证机制API Key 与租户密钥托管README 明确指出Auth: API key. Corsair prompts your tenant for credentials on first use.即插件使用 API Key 认证在用户租户首次使用相关端点时Corsair 会提示其录入 Marketstack 的access_key此后由 Corsair 的密钥托管系统负责保存与注入。在 index.ts 的keyBuilder中可以完整看到密钥解析顺序若在初始化插件时通过options.key显式传入密钥且调用来源为endpoint则直接使用该密钥否则调用ctx.keys?.get_api_key()从租户托管的密钥存储中读取读取失败或抛出的错误消息匹配/no dek found/i即租户尚未配置数据加密密钥见 client.ts 的tryGetStoredKey时抛出AuthMissingError(marketstack, api_key)。对应测试 plugin.test.ts 覆盖了三种场景直接注入密钥、无托管密钥、无 DEK 时均按预期返回或抛错。HTTPS 是硬性要求client.ts 的注释明确说明了一个安全约束HTTPS only — marketstacks access_key is sent as a query parameter on every request, so this must never be requested over plain HTTP.由于 Marketstack 的access_key会作为查询参数出现在每一次请求的 URL 中插件将 API 基地址固定为https://api.marketstack.com/v2即 MARKETSTACK_API_BASE。官方所有套餐含免费版均提供 HTTPS无需为此升级付费套餐。请求构造走corsair/http的request工具所有查询参数含access_key统一注入参见 makeMarketstackRequest。端点全景10 个只读操作README 给出了完整的端点清单每个端点都对应一个operationId形如marketstack.api.group.operation用于权限配置与调用定位OperationOperation IDRiskDescriptioncurrencies.listmarketstack.api.currencies.listread列出 Marketstack API 支持的所有货币dividends.getmarketstack.api.dividends.getread获取一只或多只股票的股息金额与派息日期历史eod.getmarketstack.api.eod.getread获取一只或多只股票的 EODOHLCV数据exchanges.getmarketstack.api.exchanges.getread按 MIC 获取交易所详情地点、状态、运营字段等exchanges.listmarketstack.api.exchanges.listread列出或搜索 Marketstack 支持的证券交易所splits.getmarketstack.api.splits.getread获取一只或多只股票的历史拆股数据tickers.getmarketstack.api.tickers.getread获取股票详细信息含交易所、板块、行业tickers.getEodmarketstack.api.tickers.getEodread获取指定股票的 EOD 历史价格tickers.getEodLatestmarketstack.api.tickers.getEodLatestread获取指定股票最近一个交易日的数据tickers.listmarketstack.api.tickers.listread列出或搜索 Marketstack 支持的股票代码上述 10 个操作在源码中的注册位置index.ts 的marketstackEndpointsNested按eod / tickers / exchanges / currencies / dividends / splits分组嵌套对应的实现分别位于 endpoints/eod.ts、endpoints/tickers.ts、endpoints/exchanges.ts、endpoints/currencies.ts、endpoints/dividends.ts 与 endpoints/splits.ts。通用输入参数约定所有分页/筛选参数在 endpoints/types.ts 中统一定义跨端点保持一致limit整数1 ~ 1000默认100控制单页返回条数offset整数默认0用于翻页sortASC或DESC按日期排序默认DESCsymbols字符串数组长度1 ~ 100如[AAPL, MSFT]用于多标的查询日期参数dateFrom/dateToISO 日期字符串YYYY-MM-DD闭区间筛选。响应统一包含paginationlimit、offset、count、total四个字段与data数组见PaginationSchema。EOD 行情端点核心数据能力eod.get多标的历史 EODeod.get对应 Marketstack v2 的GET /v2/eod返回 OHLCV 数据。OHLCV 指 Open开盘、High最高、Low最低、Close收盘、Volume成交量是行情分析的基石数据。调用示例const data await plugin.endpoints.eod.get(ctx, { symbols: [AAPL, MSFT], exchange: XNAS, // 可选按交易所 MIC 过滤 sort: DESC, // 可选ASC | DESC dateFrom: 2025-01-01, // 可选 dateTo: 2025-01-31, // 可选 limit: 10, offset: 0, });实现见 endpoints/eod.tssymbols数组经joinSymbolsclient.ts拼接为逗号分隔字符串后放入查询参数。tickers.getEod单标的历史 EODtickers.getEod对应GET /v2/tickers/{symbol}/eod聚焦单个标的如AAPL的历史收盘数据。注意 endpoints/types.ts 中标注的v2 wire shape 差异Marketstack v2 把 K 线嵌套在data.eod下而非直接放在data数组。插件通过GetTickerEodWireResponseSchema解析原始响应后将其重映射为统一的{ pagination, data: EodBar[] }输出结构调用方无需感知底层差异。tickers.getEodLatest最近交易日数据tickers.getEodLatest对应GET /v2/tickers/{symbol}/eod/latest直接返回最近一个交易日的 EOD Bar单对象非数组适合这只股票今天收盘多少这类高频问题。输入仅需symbol输出即EodBarSchema。EOD Bar 数据结构EOD 数据实体定义在 schema/database.ts字段包括open/high/low/close/volume基础 OHLCV 五元组adj_open/adj_high/adj_low/adj_close/adj_volume复权调整后价格与成交量split_factor、dividend该日拆股因子与股息symbol、exchange、exchange_code、price_currency、asset_type、date等上下文字段。Ticker 元数据端点tickers.get单标详情tickers.get对应GET /v2/tickers/{symbol}返回 MarketstackTicker 定义的结构包含标识信息symbol、name、cik、isin、cusip、lei、series_id等分类信息sector板块、industry行业、sic_code、sic_name、item_type能力标记has_intraday、has_eod是否支持盘中/日终数据嵌套的stock_exchange引用含name、acronym、mic。tickers.list搜索股票代码tickers.list对应 v2 的GET /v2/tickerslist支持按名称/代码搜索、按交易所过滤并分页const res await plugin.endpoints.tickers.list(ctx, { search: Apple, // 可选按名称或代码搜索 exchange: XNAS, // 可选按 MIC 过滤 limit: 50, offset: 0, });这里同样存在 v2 兼容处理wire 返回以ticker字段作为键插件在 endpoints/tickers.ts 中将其映射回统一的symbol字段保证与其他端点输出一致schema 定义见 endpoints/types.ts。交易所、货币、股息与拆股端点exchanges.get / exchanges.listexchanges.getGET /v2/exchanges/{mic}按 MICMarket Identifier Code市场标识码如XNAS代表纳斯达克查询单个交易所。v2 会把交易所对象包在data信封里插件在 endpoints/exchanges.ts 中解包后返回。exchanges.listGET /v2/exchanges列出或搜索交易所支持search、limit、offset。交易所对象MarketstackExchange包含name、acronym、mic、country、country_code、city、website、operating_mic、oprt_sgmt、legal_entity_name、exchange_lei、market_category_code、exchange_status及date_creation等日期字段日期可能是字符串或 PHP DateTime 对象形态schema 做了联合类型兼容。currencies.listcurrencies.listGET /v2/currencies返回 Marketstack 支持的货币列表字段为code、symbol、name、symbol_native仅支持limit/offset分页。dividends.get股息数据dividends.getGET /v2/dividends接受symbols、dateFrom、dateTo、limit、offset返回股息事件列表。每个事件MarketstackDividend包含symbol、date、dividend每股股息金额payment_date派息日、record_date股权登记日、declaration_date公告日distr_freq派息频率。splits.get拆股数据splits.getGET /v2/splits参数与股息端点一致返回拆股事件。每个事件MarketstackSplit包含symbol、date、split_factor拆股因子与stock_split如2:1的人类可读描述。错误处理与重试策略插件内置了面向 Marketstack 错误语义的处理器定义在 error-handlers.ts按官方错误码与 HTTP 状态码分类处理器匹配依据策略AUTH_ERROR错误码invalid_access_key/missing_access_key/inactive_user或 HTTP 401不重试QUOTA_ERROR错误码usage_limit_reached不重试PLAN_RESTRICTED_ERROR错误码https_access_restricted/function_access_restricted或 HTTP 403不重试VALIDATION_ERROR错误码validation_error/invalid_api_function/404_not_found或 HTTP 400 / 422不重试RATE_LIMIT_ERROR错误码rate_limit_reached、HTTP 429或消息包含 429 / rate limit / too many requests指数退避重试最多 3 次优先遵循Retry-After头SERVER_ERRORHTTP 500 或消息含 500 / internal server error指数退避重试最多 2 次DEFAULT兜底不重试错误统一包装为 MarketstackAPIError携带status、statusText、原始响应body、retryAfter与 Marketstack 业务错误码apiCode供上层解析与日志。自定义错误处理器可通过插件选项的errorHandlers传入并与内置处理器合并合并逻辑保证DEFAULT始终位于末尾见 index.ts 与 plugin.test.ts 的回归测试。在应用中使用插件初始化示例import { marketstack } from corsair-dev/marketstack; // 方式一通过租户密钥托管推荐首次使用时提示用户录入 access_key const plugin marketstack(); // 方式二在服务端直接注入 API key const plugin marketstack({ key: process.env.MARKETSTACK_ACCESS_KEY });插件初始化后可像其他 Corsair 插件一样挂载到应用实例将端点暴露给 Agent 工具调用每个端点的输入输出均经过 Zod schema 运行时校验marketstackEndpointSchemas见 index.ts并且所有调用都会通过logEventFromContext记录操作事件含参数摘要与completed状态便于审计与可观测。典型场景组合示例先用tickers.list按名称搜索找到代码再用tickers.getEod/tickers.getEodLatest拉取历史与最新行情配合dividends.get、splits.get补充基本面事件即可支撑某股票近 30 日走势 最近分红/拆股一类的 Agent 问答。补充说明版本与依赖插件当前版本 0.1.1peer 依赖corsair 0.1.0与zod ^4.1.13构建产物通过 tsup 输出至dist见 package.json。仅支持 v2插件固定调用 v2 APIv1 已弃用v2 下个别端点的响应结构差异已由插件内部完成重映射对外输出结构稳定见 client.ts 的说明注释。无 Webhook该插件不注册任何 Webhook 事件纯请求/响应模式。许可Apache-2.0。完整的数据模型、端点 schema 与单元/集成测试可进一步查阅 packages/marketstack/schema、packages/marketstack/endpoints/types.ts 以及 packages/marketstack 下的测试文件。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
