← Back to Blog

SEC 工具使用指南

Xiao Wu
Xiao WuAuthor
June 25, 2025工具
Tags:
工具SEC

SEC 工具使用指南

这个文档介绍如何在项目中使用SEC工具来获取和分析美国证券交易委员会(SEC)的10-K报告数据。

概述

SEC工具提供了三个核心功能：

  1. 获取10-K元数据 - 搜索和获取10-K报告的基本信息
  2. 下载10-K报告 - 下载完整的10-K报告文件(HTML/PDF格式)
  3. 提取10-K章节 - 提取10-K报告中的特定章节内容

环境配置

1. 获取SEC API密钥

首先需要从 SEC API 获取API密钥。

2. 设置环境变量

# 在 .env 文件中添加
SEC_API_KEY=your_sec_api_key_here

3. 启用SEC工具

在工具配置中启用SEC工具：

const toolConfig = {
  enabled: true,
  apps: ['sec_api', 'tavily', 'user_query'] // 添加 sec_api
}

工具功能详解

1. SEC 10-K 元数据工具 (sec_10k_metadata)

获取公司10-K报告的基本信息和元数据。

输入参数：

  • ticker: 股票代码 (如: AAPL, TSLA, MSFT)
  • startDate: 搜索开始日期 (格式: YYYY-MM-DD)
  • endDate: 搜索结束日期 (格式: YYYY-MM-DD)

输出：

{
  success: true,
  ticker: "AAPL",
  metadata: {
    formType: "10-K",
    filedAt: "2023-11-03",
    companyName: "Apple Inc.",
    ticker: "AAPL",
    linkToFilingDetails: "https://...",
    linkToTxt: "https://...",
    linkToHtml: "https://...",
    periodOfReport: "2023-09-30"
  },
  timestamp: "2024-01-15T10:30:00.000Z"
}

2. SEC 10-K 下载工具 (sec_10k_download)

下载完整的10-K报告文件。

输入参数：

  • ticker: 股票代码
  • startDate: 搜索开始日期
  • endDate: 搜索结束日期
  • saveFolder: 保存目录路径
  • format: 文件格式 ("html" | "pdf")

输出：

{
  success: true,
  ticker: "AAPL",
  filePath: "./downloads/2023-10-02_10-K_0000320193-23-000106.html",
  fileName: "2023-10-02_10-K_0000320193-23-000106.html",
  format: "html",
  filing: { /* 报告元数据 */ },
  timestamp: "2024-01-15T10:30:00.000Z"
}

3. SEC 10-K 章节工具 (sec_10k_section)

提取10-K报告中的特定章节内容。

输入参数：

  • ticker: 股票代码
  • fiscalYear: 财年 (如: "2023")
  • section: 章节编号 ("1", "1A", "2", "3", "7", "7A", "8", "9A")
  • reportUrl: (可选) 直接指定报告URL
  • savePath: (可选) 保存提取内容的路径

输出：

{
  success: true,
  ticker: "AAPL",
  fiscalYear: "2023",
  section: "1",
  content: "Business section content...",
  contentLength: 25000,
  cached: true,
  timestamp: "2024-01-15T10:30:00.000Z"
}

10-K 章节说明

章节 名称 内容描述 适用分析
1 Business 业务描述、产品服务、竞争优势 收入分析、业务价值
1A Risk Factors 风险因素和不确定性 风险评估、业务价值
2 Properties 房地产和物业信息 资产分析、业务价值
3 Legal Proceedings 法律诉讼情况 风险评估
7 MD&A 管理层讨论与分析 收入分析、增长分析
7A Market Risk 市场风险量化披露 增长分析、风险评估
8 Financial Statements 财务报表 财务分析
9A Controls and Procedures 内控制度 合规分析

使用示例

基础使用

import { getAllSECTools } from './lib/tools/sec-tools';
 
// 获取所有SEC工具
const secTools = await getAllSECTools();
 
// 使用元数据工具
const metadataTool = secTools.find(tool => tool.actionName === 'sec_10k_metadata');
const result = await metadataTool.callback({
  ticker: 'AAPL',
  startDate: '2023-01-01',
  endDate: '2023-12-31'
});
 
console.log('Apple 10-K metadata:', result);

财务分析工作流

import { setupSECWorkflow, getAnalysisSections } from './lib/tools/sec-example';
 
// 设置SEC工作流
const { toolset } = await setupSECWorkflow();
 
// 根据分析类型获取所需章节
const sectionsNeeded = getAnalysisSections('revenue'); // ["1", "7"]
 
// 获取各个章节的内容
for (const section of sectionsNeeded) {
  const sectionResult = await getSECSection('AAPL', '2023', section);
  console.log(`Section ${section}:`, sectionResult.contentLength, 'characters');
}

与LangGraph集成

import { StateGraph } from "@langchain/langgraph";
 
// 在LangGraph工作流中使用
const workflow = new StateGraph(YourAnnotation)
  .addNode("sec_data", async (state) => {
    const secTools = await getAllSECTools();
    const metadataTool = secTools[0];
    
    const result = await metadataTool.callback({
      ticker: state.ticker,
      startDate: `${state.fiscalYear}-01-01`,
      endDate: `${state.fiscalYear}-12-31`
    });
    
    return { ...state, secData: result };
  })
  .addNode("analysis", analysisNode)
  .addEdge("sec_data", "analysis");

缓存机制

SEC工具自动缓存提取的章节内容到 .cache/sec_tools/ 目录，避免重复API调用：

.cache/sec_tools/
├── AAPL_2023_section_1.txt
├── AAPL_2023_section_7.txt
└── TSLA_2023_section_1A.txt

缓存文件命名格式：{TICKER}_{FISCAL_YEAR}_section_{SECTION}.txt

错误处理

工具包含完善的错误处理机制：

const result = await tool.callback(params);
 
if (!result.success) {
  console.error('SEC API Error:', result.error);
  // 处理错误情况
}

常见错误：

  • SEC_API_KEY not configured - 未设置API密钥
  • No 10-K filing found for the specified period - 指定时间段内没有找到10-K报告
  • Invalid section number - 无效的章节编号
  • API rate limit exceeded - API调用频率超限

测试

运行测试来验证工具是否正常工作：

# 运行单元测试
npx tsx lib/tools/sec-tools.test.ts
 
# 或使用测试脚本
npx tsx scripts/test-sec-tools.ts unit
 
# 运行集成测试（需要真实API密钥）
SEC_API_KEY=your_key npx tsx scripts/test-sec-tools.ts integration

最佳实践

1. 选择合适的章节

根据分析目标选择相关章节：

  • 收入分析: 章节1(业务) + 章节7(MD&A)
  • 业务价值评估: 章节1(业务) + 章节1A(风险) + 章节2(资产)
  • 增长分析: 章节7(MD&A) + 章节7A(市场风险)

2. 合理使用缓存

  • 首次提取后，相同的章节会自动缓存
  • 定期清理缓存目录避免占用过多空间
  • 新财年数据发布后需要清理对应缓存

3. API调用优化

  • 批量处理多个公司时，添加适当延迟避免频率限制
  • 优先使用缓存的内容，减少不必要的API调用
  • 在工作流中合理安排SEC数据获取的时机

4. 内容处理

  • 提取的章节内容可能包含HTML标签，需要清理
  • 内容长度可能很大，考虑分块处理
  • 重要信息可能分散在多个章节中，需要综合分析

支持的公司

理论上支持所有在SEC注册的美国上市公司，包括但不限于：

科技公司: AAPL, MSFT, GOOGL, AMZN, META, TSLA, NVDA, NFLX 金融公司: JPM, BAC, WFC, GS, MS 工业公司: GE, CAT, MMM, BA 消费公司: KO, PG, JNJ, WMT

故障排除

常见问题

  1. "SEC_API_KEY not configured"

    • 检查环境变量是否正确设置
    • 确认API密钥有效

  2. "No 10-K filing found"

    • 检查股票代码是否正确
    • 调整搜索日期范围
    • 确认公司在指定期间有提交10-K报告

  3. API调用失败

    • 检查网络连接
    • 确认API密钥额度充足
    • 检查API服务状态

调试模式

启用调试日志：

// 在工具调用前设置
process.env.SEC_DEBUG = 'true';

这将输出详细的API调用信息和错误详情。

更新日志

  • v1.0.0 - 初始版本，支持10-K元数据获取、文件下载、章节提取
  • 计划功能：支持其他SEC表格类型(10-Q, 8-K等)、增强的内容解析、更多缓存选项

更多信息请参考：

Comments