pp-edgar

SEC EDGAR — Printing Press CLI

前置条件：安装 CLI

此技能通过 edgar-pp-cli 二进制文件运行。**调用此技能中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 通过 Printing Press 安装程序安装。在 macOS/Linux 上，默认将二进制文件安装到 $HOME/.local/bin；在 Windows 上，则安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install edgar --cli-only
   

2. 验证：edgar-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（未安装 Node、处于离线状态等），则改用 Go 直接安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/other/edgar/cmd/edgar-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件目录。验证成功前，请勿继续执行技能命令。

何时使用此 CLI

当 Agent 需要以便于节省 token 的形式获取结构化 SEC 文件数据时，请使用 edgar-pp-cli，例如一手来源资料包、区分 S/F 的内部人士摘要、跨季度 MD&A 差异，或针对缓存文件的本地 FTS5 搜索。复合命令 primary-sources 是 LODESTAR 的形式：一次调用即可返回用于 Gate 1/2/3 论点的完整证据包。此 CLI 不适用于 Federal Register 搜索、regulations.gov 案卷、激进做空报告或 NASDAQ 做空利息数据；这些都不在其范围内，由其他工具处理。

何时不使用此 CLI

对于需要创建、更新、删除、发布、评论、点赞、邀请、下单、发送消息、预订、购买或更改远程状态的请求，请勿启用此 CLI。此打印版 CLI 只提供用于检查、导出、同步和分析的只读命令。

独特功能

这些功能在其他任何用于此 API 的工具中都不可用。

可累积的本地状态

• since — 使用每个 CIK 的本地游标，仅返回指定时间戳之后提交的文件 — 一次调用即可完成整个 LODESTAR /$recheck 循环。

  对于季度论点复查，优先使用此命令，而不是获取完整的 submissions 索引 — 它可以避免对已查看过的文件重复消耗 token。

  edgar-pp-cli since AAPL --as-of 2026-05-08 --json
  

• fts — 通过 FTS5 对本地缓存的文件正文进行全文搜索 — 可限定股票代码和表单类型 — 并提供片段窗口和字节偏移量，便于精确重新读取。

  在需要多次查询同一文件正文的深入分析中使用 fts；首次查找或进行跨发行方查询时，使用已整合的 efts 命令。

  edgar-pp-cli fts "going concern" --ticker AAPL --form 10-Q --json
  

服务专属内容模式

• eightk-items — 列出已解析 Item 编号的 8-K，并提供 --material-only 标志，以排除仅包含附件（只有 Item 9.01）的重新提交文件。

  当你只需要了解“是否发生了重大事项？”时，请使用此命令，而不是提取 8-K 正文 — 一次调用即可获得答案，无需阅读文件文本。

  edgar-pp-cli eightk-items AAPL --since 2026-05-08 --material-only --json
  

• ownership-crosses — 列出针对某发行方提交的 13D 和 13G 文件（即其他人持有该股票代码 5% 以上的股份），并提供申报人姓名、持股比例和提交时间。

  在 LODESTAR Gate 3 非对称结构检查中使用此命令，无需翻阅 submissions 即可发现激进投资者或机构持股集中情况。

  edgar-pp-cli ownership-crosses AAPL --json
  

• governance-flags — 将三个服务专属信号组合为一次调用：8-K Item 4.01 审计师变更、Item 4.02 不依赖重述，以及 NT-10-K 延迟提交通知（Form 12b-25）。

  将其用作早期排除项检查 — 如果触发任何标记，请先告知 LODESTAR，再花费 token 分析完整论点。

  edgar-pp-cli governance-flags AAPL --since 2y --json
  

跨实体联接

• insider-followthrough — 对每笔金额 ≥$1M 的高级管理人员代码 S 卖出交易，扫描之后 90 天内的 8-K 重大事项，并输出（卖出交易、后续重大 8-K、间隔天数）配对。

  在 LODESTAR Gate 2 执行验证中，当内幕人士卖出发生在重大披露之前时使用此功能——在坏消息出现之前揭示管理层退出。

  edgar-pp-cli insider-followthrough AAPL --json
  

  Form 4 摄取上限。 insider-summary、insider-followthrough 和 primary-sources 通过共享的 --max-form4 N 上限（默认值为 200）摄取 Form 4 文件，以限制高申报量发行人的数据库/API 压力。达到上限而截去较早文件时，输出会在 form4_skipped 下显示 form4_truncated: true 和 form4_total_in_window: <N>，并在 stderr 输出 WARN——绝不会静默处理。传入 --max-form4 0 可禁用上限；传入更大的值可扩大窗口。

• xbrl-pivot — 多股票代码 XBRL 透视表，可解析概念别名（Revenues ↔ RevenueFromContractWithCustomerExcludingAssessedTax ↔ SalesRevenueNet），生成扁平的股票代码×季度×概念表。

  用于横截面质量筛选——先进行透视，再手动解析 50 个 companyfacts JSON 文件。

  edgar-pp-cli xbrl-pivot --tickers AAPL,MSFT,GOOGL --concepts Revenues,NetIncomeLoss --quarters 8 --csv
  

高效提取 Token

• sections — 使用字节偏移边界，从 10-K 或 10-Q 中提取指定条款；仅以精简 JSON 输出所需条款，而非完整的 100KB-10MB HTML 正文。

  只需要风险因素和 MD&A 时，用此功能代替获取原始 10-K 正文——可节省一个数量级的 Token。

  edgar-pp-cli sections AAPL --form 10-K --items 1A,7,7A --json
  

命令参考

companies — 公司标识符（股票代码 → CIK）和发行人提交文件索引

• edgar-pp-cli companies lookup — 从 SEC 的夜间索引解析股票代码 → CIK（以及公司名称和 SIC）。在本地 SQLite 中缓存 24 小时。
• edgar-pp-cli companies submissions — 公司的结构化提交文件索引（包含 accession 编号、表格类型、提交时间的申报历史）。

companyfacts — CIK 对应的 XBRL 公司事实（财务概念：收入、净利润、资产、现金流等）

• edgar-pp-cli companyfacts <cik> — CIK 对应的所有 XBRL 公司事实。可选在客户端筛选单个概念。

efts — 跨所有申报文件进行 EDGAR 全文搜索（efts.sec.gov）。若要对已缓存的申报正文进行离线 FTS5 搜索，请改用离线 fts 命令。

• edgar-pp-cli efts <q> — 在线搜索 EDGAR 申报文件全文。若要对已缓存的正文进行离线 FTS5 搜索，请使用 edgar-pp-cli fts。

filings — 按表格类型检索申报文件并获取单份申报文件

• edgar-pp-cli filings browse — 获取 CIK 和表格类型对应的 EDGAR 申报文件索引。返回 HTML/Atom；生成器会对其进行封装，但解析发生在……
• edgar-pp-cli filings get — 获取原始申报文件索引页面或指定 accession 对应的文件。Accession 必须是不带连字符的形式（例如，……）

查找合适的命令

知道要执行什么操作，但不确定该用哪个命令时，可直接询问 CLI：

edgar-pp-cli which "<capability in your own words>"

which 会根据自然语言功能查询，从此 CLI 精选的功能索引中解析出最匹配的命令。退出代码 0 表示至少有一个匹配项；退出代码 2 表示没有可信的匹配项——请改用 --help 或缩小查询范围。

操作示例

完整的 LODESTAR 研究数据提取

edgar-pp-cli primary-sources AAPL --json --select shares_outstanding,senior_insider_sales,recent_eightk_items,def14a_governance

面向 Agent 的精简 JSON——primary-sources 返回完整数据包；--select 仅保留 LODESTAR Gate 评估实际需要的字段，剔除模板内容。

季度复核增量

edgar-pp-cli since AAPL --as-of 2026-05-08 --json

仅包含在指定时间戳之后提交的文件。本地游标——缓存有效时无需再次请求 SEC。若增量中包含 8-K，可与 eightk-items --material-only 搭配使用。

内幕人士后续追踪模式

edgar-pp-cli insider-followthrough AAPL --json

跨实体联接：将金额 ≥$1M 的高级管理人员代码 S 卖出交易，与 90 天内后续出现的重大 8-K 事项配对。在坏消息出现之前揭示管理层退出。

横截面 XBRL 筛选

edgar-pp-cli xbrl-pivot --tickers AAPL,MSFT,GOOGL,META --concepts Revenues,NetIncomeLoss --quarters 8 --csv

支持概念别名解析的多股票代码透视表——生成扁平表格，供下游筛选或导入电子表格。使用 --csv 生成表格数据流。

高效提取 10-K 条目，节省令牌

edgar-pp-cli sections AAPL --form 10-K --items 1A,7,7A --json --select item,text_offset,text

仅提取风险因素（1A）、管理层讨论与分析（7）以及定量披露（7A），并包含字节偏移量——与完整申报文件正文相比，令牌数量减少一个数量级。

本地 FTS5 深入检索

edgar-pp-cli fts "going concern" --ticker AAPL --form 10-Q --json

对缓存的申报文件正文进行离线 FTS5 检索；输出摘要片段和字节偏移量，以便精确重新读取。如果缓存为空，请先运行 sync。

身份验证设置

无需 API 密钥——SEC EDGAR 可公开访问。身份标识由 User-Agent 提供：设置一次 COMPANY_PP_CONTACT_EMAIL，之后每个请求都会以 lodestar-edgar-pp-cli <email> 的身份发出。如果未设置环境变量，CLI 会拒绝运行，并显示指向设置说明的清晰错误。速率限制为持续 ≤2 req/sec，远低于 SEC 的 10 req/sec 上限；遇到 429 时会自适应退避。

运行 edgar-pp-cli doctor 验证设置。

Agent 模式

为任何命令添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可管道传输 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留部分字段。点分路径可深入嵌套结构；数组会逐元素遍历。对于输出冗长的 API，这对控制上下文大小至关重要：

  edgar-pp-cli companyfacts mock-value --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求，但不会发送

• 支持离线使用 — 若本地 SQLite 存储可用，sync/search 命令可以使用该存储

• 非交互式 — 从不显示提示，每项输入都通过标志传入

• 只读 — 请勿使用此 CLI 执行创建、更新、删除、发布、评论、点赞、邀请、订购、发送或其他会修改数据的请求

响应信封

从本地存储或 API 读取的命令会将输出包装在来源信息信封中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并通过 .meta.source 判断数据来自实时数据还是本地数据。仅当 stdout 连接到终端时，才会将人类可读的 N results (live) 摘要打印到 stderr；通过管道传输或由 Agent 使用时，stdout 只包含纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有任何不妥之处时，请记录下来：

edgar-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
edgar-pp-cli feedback --stdin < notes.txt
edgar-pp-cli feedback list --json --limit 10

条目会保存在本地的 ~/.edgar-pp-cli/feedback.jsonl 中。除非设置了 EDGAR_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 EDGAR_FEEDBACK_AUTO_SEND=true，否则不会通过 POST 发送。默认行为仅保存在本地。

请写下让你感到意外的地方，而不是提交错误报告。简短、具体、一行即可：这才是不断积累价值的部分。

输出传递

每个命令都接受 --deliver <sink>。输出会写入指定的接收端，同时写入 stdout，或取代 stdout，这样 Agent 无需手动通过管道传输即可路由命令结果。支持三种接收端：

接收端	效果
stdout	默认值；仅写入 stdout
file:<path>	以原子方式将输出写入 <path>（tmp + rename）
webhook:<url>	将输出正文 POST 到 URL（--compact 时使用 application/json 或 application/x-ndjson）

不支持的方案会被拒绝，并返回结构化错误，列出受支持的方案。Webhook 请求失败时会返回非零状态，并在 stderr 中记录 URL 和 HTTP 状态。

命名配置

配置是保存的一组标志值，可在多次调用中重复使用。当计划任务中的 Agent 每次运行都以相同配置调用同一命令时，可以使用配置——即 HeyGen 的“Beacon”模式。

edgar-pp-cli profile save briefing --json
edgar-pp-cli --profile briefing companyfacts mock-value
edgar-pp-cli profile list --json
edgar-pp-cli profile show briefing
edgar-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，以便 Agent 在运行时发现它们。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	速率受限（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 edgar-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的先决条件
3. 其他任何内容 → 直接使用（作为 CLI 命令执行，并附带 --agent）

MCP 服务安装

从此 CLI 发布的公共库条目或预构建版本中安装 MCP 二进制文件，然后注册它：

claude mcp add edgar-pp-mcp -- edgar-pp-mcp

验证：claude mcp list

直接使用

1. 检查是否已安装：which edgar-pp-cli 如果未找到，则提供安装选项（参见本技能顶部的先决条件）。
2. 根据用户查询，从上文的独特功能和命令参考中选择最合适的命令。
3. 使用 --agent 标志执行：

   edgar-pp-cli <command> [subcommand] [args] --agent
   

4. 如果存在歧义，请查看子命令帮助：edgar-pp-cli <command> --help。