用途：从 SEC EDGAR 官方结构化 XBRL 数据中提取美国上市公司财务报表数字，避免模型凭记忆编造或从网页抓取。每次取数都会附带对应申报文件的引用信息。
主要能力：
- resolve：通过 ticker、CIK 或名称片段解析公司，名称不明确时列出候选项。
- pull：按指标和年份/季度拉取数据，默认返回最近 3 个财年、最新季度及 TTM。支持 revenue、net_income、eps_diluted、capex、total_assets 等多项指标。
- compare：多家公司并排对比。
- tags / concept / frame：查询某公司使用的标准标签、追踪某标签的全部申报值、按日历期筛选公司。
安装与用法：需先设置带联系方式的 User-Agent，否则请求返回 HTTP 403： export SEC_USER_AGENT="Acme Research jane@acme.com" pip install pandas 主要命令如 python3 scripts/sec_pull.py pull AAPL；缓存位于 ~/.cache/sec-filing-puller，可设 SEC_CACHE_DIR 或 --refresh。
输出：stdout 为 markdown 表格，加 --out 后另写 CSV/JSON，每行含 value、unit、basis、form、accn、filed、filing_index_url、original_value、revised、notes 等列。
限制与注意事项：需核对警告行与 notes，注意各公司财年错位、Q4 及季度现金流为推导值、重述（revised=True，可用 --as-reported 看原始值）、标签定义差异、币种（外国申报人用本币）及数据覆盖滞后。XBRL 不含分部与地区收入、非 GAAP 指标、订阅数等同店销售类 KPI、公司自定义扩展标签及部分外国私人发行人的季度数据，缺失时应明确写“not in XBRL”并指向相应文件。取数仅呈现公司申报数据，不构成投资建议。效率上脚本遵循 SEC 每秒 10 次请求限制，测试可离线运行：python3 -m unittest discover -s tests -v。