Moedim.Edgar

用于访问美国证券交易委员会（SEC）EDGAR数据库的C# .NET库，支持现代异步/等待模式和依赖注入。

"Moedim" 是一个希伯来词，意为“节日”或“约定时间”。 “约定时间”指的是在利未记第23章中提到的HaShem的节日。 节日是“信号和标志”，帮助我们了解HaShem的心意。

特性

• 现代HTTP客户端 - 使用IHttpClientFactory进行高效可靠的HTTP通信
• 依赖注入 - 支持Microsoft.Extensions.DependencyInjection
• 类型安全模型 - 强类型的SEC EDGAR数据结构模型
• 异步/等待 - 完全异步API
• 重试逻辑 - 内置重试机制处理速率限制和瞬时故障
• 可配置 - 灵活的选项模式以定制行为
• 详尽文档 - 所有公共API的全面XML文档
• 多框架支持 - 针对.NET 8.0
• 📄 文档检索 - 下载完整的SEC文件作为干净的Markdown或HTML
• ✂️ 智能部分提取 - 解析并提取文件中的特定部分（风险因素、MD&A等）
• 🔍 部分预览 - 在下载完整内容之前浏览文件部分
• 💾 内置缓存 - 自动缓存以减少API调用并提高性能
• 🤖 MCP服务器 - 用于LLM集成的Model Context Protocol服务器（包含在Moedim.Edgar.Mcp包中）

聘请我

如果您考虑聘请我，请发送电子邮件。

给个星！:star:

如果您喜欢或正在使用这个项目来学习或启动您的解决方案，请给它一个星。谢谢！

安装

dotnet add package Moedim.Edgar

AI集成的MCP服务器

通过Model Context Protocol (MCP)集成AI助手，安装配套的MCP服务器包：

# 通过dnx安装（推荐）
dnx Moedim.Edgar.Mcp --version 1.0.0 --yes

MCP服务器提供：

• 17种工具用于访问SEC EDGAR数据（公司事实、文件搜索、文档检索、部分提取）
• 6种引导提示用于结构化分析工作流（公司评估、同行比较、变化跟踪等）

详见src/Moedim.Edgar.Mcp/README.md的完整文档。

快速开始

1. 配置服务

using Moedim.Edgar.Extensions;

services.AddSecEdgar(options =>
{
    options.AppName = "YourCompany";
    options.AppVersion = "1.0.0";
    options.Email = "your@email.com";
    options.RequestDelay = TimeSpan.FromMilliseconds(100);
    options.MaxRetryCount = 3;
});

2. 使用服务

using Moedim.Edgar.Models;

public class FinancialDataService
{
    private readonly ICompanyFactsService _companyFactsService;
    private readonly ICompanyConceptService _companyConceptService;

    public FinancialDataService(
        ICompanyFactsService companyFactsService,
        ICompanyConceptService companyConceptService)
    {
        _companyFactsService = companyFactsService;
        _companyConceptService = companyConceptService;
    }

    public async Task<CompanyFactsQuery> GetCompanyFactsAsync(int cik)
    {
        return await _companyFactsService.QueryAsync(cik);
    }

    public async Task<CompanyConceptQuery> GetRevenueDataAsync(int cik)
    {
        return await _companyConceptService.QueryAsync(cik, "Revenues");
    }
}

使用示例

检索公司事实

// 获取公司的所有事实（例如，苹果公司 - CIK：320193）
var facts = await companyFactsService.QueryAsync(320193);

// 访问公司信息
Console.WriteLine($"公司: {facts.EntityName}");
Console.WriteLine($"CIK: {facts.Cik}");

// 遍历事实
foreach (var fact in facts.Facts)
{
    Console.WriteLine($"概念: {fact.Label}");
    Console.WriteLine($"值: {fact.Value}");
}

查询特定概念

// 获取特定财务概念（例如，收入）
var revenues = await companyConceptService.QueryAsync(320193, "Revenues");

// 访问数据点
foreach (var dataPoint in revenues.DataPoints)
{
    Console.WriteLine($"期间: {dataPoint.FiscalPeriod}");
    Console.WriteLine($"值: {dataPoint.Value:C}");
    Console.WriteLine($"提交日期: {dataPoint.Filed:d}");
}

下载文件文档（新）

// 将完整文件作为干净的Markdown获取
var markdown = await filingDetailsService.GetFilingDocumentAsync(
    accessionNumber: "0000320193-23-000077",
    tickerOrCik: "AAPL",
    format: "markdown"
);

// 或者获取为HTML
var html = await filingDetailsService.GetFilingDocumentAsync(
    accessionNumber: "0000320193-23-000077",
    format: "html"
);

提取特定部分（新）

// 首先，预览可用的部分
var previewRequest = new FilingSectionsRequest { PreviewOnly = true };
var preview = await filingDetailsService.GetFilingSectionsAsync(
    accessionNumber: "0000320193-23-000077",
    request: previewRequest
);

// 显示可用部分
foreach (var section in preview.Preview)
{
    Console.WriteLine($"{section.AnchorTargetId}: {section.Label}");
}

// 然后，获取特定部分
var sectionsRequest = new FilingSectionsRequest
{
    PreviewOnly = false,
    AnchorIds = new[] { "item_1a_risk_factors", "item_7_managements_discussion_analysis" },
    Merge = true, // 合并部分为单个内容
    Format = "markdown"
};

var result = await filingDetailsService.GetFilingSectionsAsync(
    accessionNumber: "0000320193-23-000077",
    request: sectionsRequest
);

Console.WriteLine(result.MergedContent); // 选择部分的干净Markdown

配置选项

services.AddSecEdgar(options =>
{
    // 必需：SEC需要识别
    options.AppName = "YourCompany";
    options.AppVersion = "1.0.0";
    options.Email = "your@email.com";

    // 可选：请求之间的延迟（默认：250毫秒）
    options.RequestDelay = TimeSpan.FromMilliseconds(100);

    // 可选：达到速率限制后的延迟（默认：2秒）
    options.TimeoutDelay = TimeSpan.FromSeconds(1);

    // 可选：最大重试次数（默认：10）
    options.MaxRetryCount = 3;

    // 可选：覆盖重试行为（显示默认值）
    options.RetryCountOverride = 5; // 包括初始调用在内的总尝试次数
    options.RetryDelay = TimeSpan.FromSeconds(1); // 当没有返回Retry-After头时的回退
    options.UseExponentialBackoff = true; // 每次重试后乘以延迟
    options.RetryBackoffMultiplier = 1.5; // 指数策略的增长因子
});

要求

• .NET 8.0或更高版本
• C# 11或更高版本（对于消费项目）
• Visual Studio 2022或Rider（最佳IDE支持）

项目结构

• Moedim.Edgar - 核心库，包括服务、模型和扩展
  • Services/ - SEC EDGAR客户端和服务实现
  • Models/ - 数据模型和查询类型
  • Extensions/ - 依赖注入扩展
• Moedim.Edgar.Mcp - 用于AI助手集成的Model Context Protocol服务器
  • Tools/ - MCP工具实现（17种工具）
  • Prompts/ - 引导分析工作流（6种提示）
  • 详情见src/Moedim.Edgar.Mcp/README.md

API文档

核心服务

• ISecEdgarClient - 低级HTTP客户端用于SEC EDGAR API
• ICompanyFactsService - 用于检索所有公司事实的服务
• ICompanyConceptService - 用于查询特定财务概念的服务
• ICompanyLookupService - 用于从股票代码查找公司CIK的服务
• IEdgarSearchService - 用于搜索公司文件的服务
• IEdgarLatestFilingsService - 用于检索最新文件的服务
• IFilingDetailsService - 用于检索文件详细信息、文档和部分的服务
• ICacheService - 用于缓存SEC EDGAR数据的服务（实现为LocalFileCache）

新特性（v1.1.0）

文档检索

IFilingDetailsService现在支持以Markdown或HTML格式下载完整的文件文档：

Task<string?> GetFilingDocumentAsync(
    string accessionNumber,
    string? tickerOrCik = null,
    string? format = null,
    CancellationToken cancellationToken = default);

• accessionNumber: SEC存取编号（例如，“0000320193-23-000077”）
• tickerOrCik: 可选的股票代码或CIK以帮助定位文件
• format: "markdown"（默认）或"html"
• 返回: 请求格式下的完整文件内容

部分提取

使用两步工作流程从文件中提取特定部分：

步骤1：预览部分

Task<FilingSectionsResult?> GetFilingSectionsAsync(
    string accessionNumber,
    FilingSectionsRequest request,
    string? tickerOrCik = null,
    CancellationToken cancellationToken = default);

当request.PreviewOnly = true时，返回部分ID和标题而无完整内容。

步骤2：获取完整部分 当request.PreviewOnly = false且指定request.AnchorIds时，返回所选部分的完整内容。

FilingSectionsRequest属性:

• PreviewOnly - 返回仅部分元数据
• AnchorIds - 要检索的部分ID列表
• Format - "markdown"（默认）或"html"
• Merge - 将所有部分合并为单个内容块

缓存

内置缓存减少API调用并提高性能：

• 自动缓存文件文档（24小时）
• 缓存部分解析结果
• 默认为基于本地文件的缓存
• 缓存目录：临时文件夹中的.edgar_cache

数据模型

• CompanyFactsQuery - 所有公司事实的容器
• CompanyConceptQuery - 特定概念数据的容器
• Fact - 带标签、值和元数据的单独事实
• FactDataPoint - 事实的时间序列数据点
• FiscalPeriod - 财政期枚举（Q1、Q2、Q3、Q4、FY）

贡献

欢迎贡献！请随意提交Pull Request。

许可证

本项目采用MIT许可证 - 详情见LICENSE文件。

致谢

使用以下技术构建：

• IHttpClientFactory
• Microsoft.Extensions.DependencyInjection
• Newtonsoft.Json

版本历史

查看CHANGELOG.md了解版本历史和发布说明。

资源

• SEC EDGAR API文档
• SEC公司搜索