金融数据采集_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 CollectorCollect 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 ConstraintsNO 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.WorkflowStep 1: Collect DataRun the collection script:python scripts/collect_data.py TICKER[--years5][--output path/to/output.json]The script collects in this priority:yfinance— market data, historical financials, beta, analyst estimatesyfinance ^TNX— 10Y Treasury yield as risk-free rate proxyUser supplement— for years where yfinance returns NaN (report to user, do not guess)Step 2: Validate Datapython scripts/validate_data.py path/to/output.jsonChecks: field completeness, cross-field consistency (Market Cap Price × Shares), range sanity (WACC 5-20%, beta 0.3-3.0), sign conventions.Step 3: Deliver JSONSingle 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.mdcorrect_patternsHandling Missing Yearsifpd.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 Preservationcapexcash_flow.loc[Capital Expenditure,year_col]# -37256.0result[capex]float(capex)# Preserve negativeDatetime Column Indexingyear_col[cforcinfinancials.columnsifc.yeartarget_year][0]revenuefinancials.loc[Total Revenue,year_col]Field Name GuardsifTotal Revenueinfinancials.index:revenuefinancials.loc[Total Revenue,year_col]elifRevenueinfinancials.index:revenuefinancials.loc[Revenue,year_col]else:revenueNone/correct_patternscommon_mistakesMistake 1: Default Values for Missing Data# ❌ WRONGbetainfo.get(beta,1.0)growthdata.get(growth)or0.02# ✅ RIGHTbetainfo.get(beta)# May be None — thats OKMistake 2: Assuming All Years Have Data# ❌ WRONG — 2020-2021 may be NaNrevenuefloat(financials.loc[Total Revenue,year_col])# ✅ RIGHTvaluefinancials.loc[Total Revenue,year_col]revenuefloat(value)ifpd.notna(value)elseNoneMistake 3: Using yfinance FCF in DCF Models Directlyyfinance 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 downstreamcapexabs(cash_flow.loc[Capital Expenditure,year_col])# ✅ RIGHT — preserve original, document conventioncapexfloat(cash_flow.loc[Capital Expenditure,year_col])# -37256.0/common_mistakesKnown yfinance PitfallsSeereferences/yfinance-pitfalls.mdfor detailed field mapping and workarounds.