EDGAR 工具

要解决什么问题

做美股基本面、合规或事件研究时，原始材料往往在 SEC EDGAR 的申报体系里：10-K/10-Q 财报、8-K 重大事项、Form 4 内部人交易、13F 持仓等。手工下载 PDF/HTML、再抠表格，既慢又难做可复现的多期对比。你需要的是按公司、表单类型和时间范围批量拉取申报，并拿到可编程的结构化对象，而不是零散文件链接。

技能如何工作

edgartools 是面向 EDGAR 的 Python 库，覆盖自 1994 年以来的申报记录。使用前 SEC 要求标识访问身份，应通过环境变量设置 EDGAR_IDENTITY="Your Name your@email.com"，避免在代码里硬编码。

典型流程可以概括为四步：

• 查找公司：按 ticker、CIK 或名称定位实体
• 获取申报：按表单类型（如 10-K、10-Q）筛选 Filings 集合
• 结构化提取：将申报映射为对应对象（如 TenK、TenQ），读取 financials、income_statement、balance_sheet 等
• 深入内容：访问正文、附件与 XBRL 相关能力（细节见 bundled 参考文档）

常见表单与对象对应关系包括：10-K → TenK，10-Q → TenQ，8-K → EightK，Form 4 → Form4，13F-HR → ThirteenF 等。财务类数据应走 filing.obj().financials，而不是不存在的 filing.financials。

适用边界与注意点

• get_filings() 没有 limit 参数；限制条数用 .head(n) 或 .latest(n)
• 多期分析时建议 amendments=False，修订版申报有时字段不完整
• 可选字段访问前先判 None，避免链式假设
• 复杂场景（公司批量筛选、XBRL 事实查询、MCP/AI 集成）可对照技能内的 companies.md、filings.md、financial-data.md、xbrl.md 等参考文件按需加载

本技能适合已在 Python 环境做 SEC 数据管道或研究脚本的工程师；它不替代你对 SEC 表单语义与会计口径的理解。