金融数据采集_financial-data-collector

以下为本文档的中文说明

financial-data-collector 是一个专业的金融数据采集技能，能够从 yfinance 等免费公开渠道收集美国上市公司的真实财务数据，并以标准化 JSON 格式输出，供下游金融分析技能（如 DCF 估值建模、可比公司分析、财报审查）使用。该技能有严格的数据采集规范：第一，严格禁止使用回退值——如果某个字段无法获取，必须设置为 null 并附带 _source: missing 标记，绝不允许用默认值替代（例如不能将缺失的 beta 值设为 1.0），由下游技能自行决定如何处理缺失数据。第二，强制数据来源标注——每个数据部分都必须包含 _source 字段，确保数据可追溯。第三，保持原始符号约定——yfinance 返回的 CapEx（资本支出）为负值（现金流出），必须保留原始符号并在输出元数据中注明约定。第四，明确数据差异——yfinance 的自由现金流与投资银行算法不同（yfinance FCF = 运营现金流 + CapEx，不扣除股权激励），必须标注这一差异。该技能采集的数据涵盖：市场数据（价格、流通股、Beta）、历史财务报表（利润表、现金流量表、资产负债表）、WACC 输入参数、分析师预测。核心原则是“真实、可追溯、不篡改”——金融数据的准确性是后续分析的前提，任何人为回退或修改都可能误导决策。

Financial Data Collector

Collect and validate real financial data for US public companies using free data sources.
Output is a standardized JSON file ready for consumption by other financial skills.

Critical Constraints

NO FALLBACK values.If a field cannot be retrieved, set it tonullwith_source: "missing".
Never substitute defaults (e.g.,beta or 1.0). The downstream skill decides how to handle missing data.

Data source attribution is mandatory.Every data section must have a_sourcefield.

CapEx sign convention:yfinance returns CapEx as negative (cash outflow). Preserve the original sign. Document the convention in output metadata. Do NOT flip signs.

yfinance FCF ≠ Investment bank FCF.yfinance FCF = Operating CF + CapEx (no SBC deduction). Flag this in output metadata so downstream DCF skills don’t overstate FCF.

Workflow

Step 1: Collect Data

Run the collection script:

python scripts/collect_data.py TICKER[--years5][--output path/to/output.json]

The script collects in this priority:

1. yfinance— market data, historical financials, beta, analyst estimates
2. yfinance ^TNX— 10Y Treasury yield as risk-free rate proxy
3. User supplement— for years where yfinance returns NaN (report to user, do not guess)

Step 2: Validate Data

python scripts/validate_data.py path/to/output.json

Checks: field completeness, cross-field consistency (Market Cap = Price × Shares), range sanity (WACC 5-20%, beta 0.3-3.0), sign conventions.

Step 3: Deliver JSON

Single file:{TICKER}_financial_data.json. Schema inreferences/output-schema.md.

Do NOT create: README, CSV, summary reports, or any auxiliary files.

Output Schema (Summary)

{"ticker":"META","company_name":"Meta Platforms, Inc.","data_date":"2026-03-02","currency":"USD","unit":"millions_usd","data_sources":{"market_data":"...","2022_to_2024":"..."},"market_data":{"current_price":648.18,"shares_outstanding_millions":2187,"market_cap_millions":1639607,"beta_5y_monthly":1.284},"income_statement":{"2024":{"revenue":164501,"ebit":69380,"tax_expense":...,"net_income":...,"_source":"yfinance"}},"cash_flow":{"2024":{"operating_cash_flow":...,"capex":-37256,"depreciation_amortization":15498,"free_cash_flow":...,"change_in_nwc":...,"_source":"yfinance"}},"balance_sheet":{"2024":{"total_debt":30768,"cash_and_equivalents":77815,"net_debt":-47047,"current_assets":...,"current_liabilities":...,"_source":"yfinance"}},"wacc_inputs":{"risk_free_rate":0.0396,"beta":1.284,"credit_rating":null,"_source":"yfinance + ^TNX"},"analyst_estimates":{"revenue_next_fy":251113,"revenue_fy_after":295558,"eps_next_fy":29.59,"_source":"yfinance"},"metadata":{"_capex_convention":"negative = cash outflow","_fcf_note":"yfinance FCF = OperatingCF + CapEx. Does NOT deduct SBC."}}

Full schema with all field definitions:references/output-schema.md

<correct_patterns>

Handling Missing Years

ifpd.isna(revenue):result[year]={"revenue":None,"_source":"yfinance returned NaN — supplement from 10-K"}# Report missing years to the user. Do NOT skip or fill with estimates.

CapEx Sign Preservation

capex=cash_flow.loc["Capital Expenditure",year_col]# -37256.0result["capex"]=float(capex)# Preserve negative

Datetime Column Indexing

year_col=[cforcinfinancials.columnsifc.year==target_year][0]revenue=financials.loc["Total Revenue",year_col]

Field Name Guards

if"Total Revenue"infinancials.index:revenue=financials.loc["Total Revenue",year_col]elif"Revenue"infinancials.index:revenue=financials.loc["Revenue",year_col]else:revenue=None

</correct_patterns>

<common_mistakes>

Mistake 1: Default Values for Missing Data

# ❌ WRONGbeta=info.get("beta",1.0)growth=data.get("growth")or0.02# ✅ RIGHTbeta=info.get("beta")# May be None — that's OK

Mistake 2: Assuming All Years Have Data

# ❌ WRONG — 2020-2021 may be NaNrevenue=float(financials.loc["Total Revenue",year_col])# ✅ RIGHTvalue=financials.loc["Total Revenue",year_col]revenue=float(value)ifpd.notna(value)elseNone

Mistake 3: Using yfinance FCF in DCF Models Directly

yfinance FCF does NOT deduct SBC. For mega-caps like META, SBC can be $20-30B/yr, making yfinance FCF ~30% higher than investment-bank FCF. Always flag this in output.

Mistake 4: Flipping CapEx Sign

# ❌ WRONG — double-negation risk downstreamcapex=abs(cash_flow.loc["Capital Expenditure",year_col])# ✅ RIGHT — preserve original, document conventioncapex=float(cash_flow.loc["Capital Expenditure",year_col])# -37256.0

</common_mistakes>

Known yfinance Pitfalls

Seereferences/yfinance-pitfalls.mdfor detailed field mapping and workarounds.