mcpField
U
us-stock

us-stock

github.com/starchild-ai-agent数据与数据库30129 次安装1 周前更新
代码仓库

关于 us-stock

us-stock 是面向美国股票查询的 Python 技能，结合 TwelveData 和 yfinance 获取行情及公司数据，并提供统一函数接口。

主要功能

  1. 01行情与 OHLCV K 线查询
  2. 02公司资料及财务报表
  3. 03机构持仓与内部人交易
  4. 04财报日、股息、拆股及新闻
  5. 05分析师评级、期权到期日与 ETF 持仓

适用场景

  1. 01查询美股行情和公司基本面
  2. 02检查机构持仓及内部人交易
  3. 03查看财报、股息、新闻和 ETF 持仓

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/starchild-ai-agent/official-skills --skill us-stock

安装后在 Claude Code 中输入/us-stock确认已加载。

附带文件exports.py

详细介绍

🇺🇸 us-stock — 美国股票数据

用于美股的单个 Python 模块，支持多数据源回退。这是面向美国市场的 cn-stock 镜像。用户询问美股代码的基本面、持有人、内部人或财务数据时，请使用此模块。对于美股的纯价格／K 线数据，此技能会在内部调用付费的 TwelveData 技能，因此你可以使用统一的接口。

架构

your call → exports.py
            ├─ twelvedata (paid, primary)  → realtime quote, time series
            └─ yfinance (free, primary for fundamentals)
                                          → info, holders, insiders,
                                            financials, news, options,
                                            dividends, splits, earnings

大多数函数都会返回统一的封装结构：

{"ok": bool, "source": str, "data": <payload>, "error": str|None, "ts": int}

例外：get_full_report(symbol) 会返回由子结果（报价／公司／持有人／内部人／财报／新闻）组成的合并字典。

快速开始

首选 — 使用 core.skill_tools（可处理导入隔离）：

python3 - <<'EOF'
from core.skill_tools import _modules
us = _modules["us-stock"]

q = us.get_realtime_quote("AAPL")
print(q["data"]["last"], q["data"]["pct_change"], "%")

c = us.get_company_info("NVDA")
d = c["data"]
print(f"{d['name']} | mcap ${d['market_cap']/1e12:.2f}T | shares {d['shares_outstanding']/1e9:.2f}B")

full = us.get_full_report("MSFT")
print(full["company"]["data"]["sector"])
EOF

备选（仅限单技能脚本）：

python3 - <<'EOF'
import importlib.util as ilu
spec = ilu.spec_from_file_location("us_stock_mod", "/data/workspace/skills/us-stock/exports.py")
us = ilu.module_from_spec(spec); spec.loader.exec_module(us)
print(us.get_realtime_quote("AAPL")["data"])
EOF

⚠️ 请勿使用 sys.path.insert + from exports import ... — cn-stock 也定义了 exports.py，它们会在同一进程中发生冲突。

函数一览

函数返回内容来源
get_realtime_quote(symbol)价格、OHLC、涨跌幅、52 周区间、市值twelvedata → yfinance 回退
get_company_info(symbol)市值、已发行股数、自由流通股数、内部人持股比例、机构持股比例、板块、行业、业务摘要、估值、利润率、股息、分析师目标价yfinance.get_info
get_institutional_holders(symbol, top=15)前 N 大机构持有人 + 持股价值 + pctChangeyfinance
get_mutualfund_holders(symbol, top=15)前 N 大共同基金持有人yfinance
get_insider_transactions(symbol, limit=20)最新的 Form 4 买入／卖出记录yfinance
get_financials(symbol, statement, period, max_periods=5)损益表／资产负债表／现金流量表，年度或季度yfinance
get_earnings(symbol, limit=8)过去及即将发布的财报日期，以及 EPS 预估值与实际值yfinance
get_dividends(symbol, limit=20)历史股息yfinance
get_splits(symbol, limit=10)历史拆股记录yfinance
get_news(symbol, limit=10)最新新闻标题 + 摘要 + URLyfinance
get_kline(symbol, interval, outputsize)OHLCV 数据条twelvedata → yfinance 回退
get_recommendations(symbol, limit=12)各时期的分析师评级分布yfinance
get_options_expirations(symbol)所有可用的期权到期日yfinance
get_etf_holdings(symbol, top=15)ETF／基金主要持仓 + 板块／资产权重（例如 SPY／QQQ）yfinance.funds_data
get_full_report(symbol)报价 + 公司信息 + 机构持有人 + 内部人 + 财报 + 新闻的合并结果组合

股票代码格式

纯美股代码 — 不带交易所后缀：

  • AAPL、MSFT、NVDA、GOOGL、TSLA
  • 双重股权类别：BRK.B、BRK-B、GOOG／GOOGL
  • 两种格式均可接受；按原样传入

复用 TwelveData（重要）

此技能不会单独注册 TwelveData 凭证。它通过 importlib 使用明确的文件路径（/data/workspace/skills/twelvedata/exports.py）加载现有的 TwelveData 技能，从而避免与其他技能的 exports.py 名称冲突。 Starchild 的 TwelveData 计费涵盖这些调用。如果 TwelveData 失败，会自动启用 yfinance 回退。

get_company_info 字段参考

最适用于 Telegram 回复的字段（均来自 yfinance）：

字段含义备注
market_cap总市值（USD）除以 1e9 → 十亿，除以 1e12 → 万亿
enterprise_value企业价值（EV）市值 + 债务 − 现金
shares_outstanding流通股数（实际为已发行股数）除以 1e9
float_shares自由流通股数（排除限售股）通常略小于 shares_outstanding
shares_short当前空头持仓
short_pct_of_float空头占自由流通股比例已是比率，×100 得到百分比
pct_held_insiders内部人持股比例已是比率
pct_held_institutions机构持股比例已是比率
trailing_pe / forward_pe静态／动态 PE
price_to_book市净率
dividend_yield股息率已是比率（0.0036 = 0.36%）
beta贝塔系数相对于 SP500
recommendation'buy'／'hold'／'sell'分析师共识
target_mean_price分析师目标均价

注意事项

  • yfinance 速率限制：Yahoo 会限制调用过于频繁的用户（约每小时 2000 次）。每次 get_full_report 约需 6 次调用。批量监控时，请在各个股票代码之间使用 time.sleep(0.3)。该技能已包含 _retry(tries=2)。
  • get_info() 开销较大（约 1–2 秒，返回 120 多个字段）。如果只需要价格，请改用 get_realtime_quote()（TwelveData 约 150 毫秒）。
  • NaN 处理：对于缺失字段（例如不派发股息的公司没有股息收益率），yfinance 会返回 NaN。该技能会在 JSON 中将 NaN 转换为 null。格式化前请务必检查值是否为 None。
  • 季度财务数据限制：yfinance 最多返回约 4 个季度的数据。需要更长的历史数据时，请使用 SEC EDGAR 10-Q 解析（未来增强项）。
  • 实时与延迟数据：TwelveData 数据直接来自交易所（延迟低）。yfinance 在交易时段约有 1 分钟延迟。两者数据冲突时，请以 TwelveData 为准。
  • 机构持有人数据过时：13F 文件提交时间比季度末晚 45 天。Date Reported 字段会标明数据截至日期。
  • 新闻提供方 ID 会变更：yfinance 的 news 架构偶尔会增删字段。该技能会将数据统一为 {title, summary, publisher, pub_date, url, type}。
  • 期权数据量较大：get_options_expirations 速度很快，但获取完整期权链（各行权价的看涨/看跌期权）需要针对每个到期日单独调用，目前尚未开放，以保持该技能轻量。

面向用户的回复格式

Telegram 用户希望看到纯文本，不要使用 Markdown。请遵循以下约定：

  • 市值：$3.91T（万亿 = T，十亿 = B，百万 = M）
  • 股数：14.69B 股
  • 比率：+2.34%（必须带正负号）、PE 36.2、Beta 1.07
  • 持有人：贝莱德 (BlackRock) 7.32%
  • 结尾务必注明数据来源：数据来源：TwelveData + Yahoo Finance (yfinance)，非投资建议

未来增强项（尚未实现）

  • 深入分析 SEC EDGAR 13F（追踪多个季度中排名前 N 的持仓）
  • 提供包含明确交易类型（P/S/A/D 代码）的 Form 4 原始文件
  • 盘前／盘后报价（TwelveData 支持 prepost=True——如有需要，可通过 get_realtime_quote 开放）
  • 期权链 Greeks（需要按到期日 × 行权价逐次调用）

评论

支持 Markdown