pp-sec-edgar

SEC EDGAR — Printing Press CLI

前置条件：安装 CLI

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

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

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

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

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

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

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

何时使用此 CLI

当 Agent 需要查询多家公司或多个时期的 SEC 文件、XBRL 财务数据、内幕交易（Form 4）或机构持仓（13F）时，请选择此 CLI——尤其适用于本地 SQLite 存储比逐次 API 往返更合适的场景。对于一次性读取单份文件，无需同步即可使用类型化端点镜像（filings get、facts get）。对于跨公司比较、内幕人士聚类、同业基准或实时文件监控，transcendence 命令可将原本需要十次 API 调用加一个 Python 循环的操作简化为一次 CLI 调用。

何时不使用此 CLI

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

独特功能

其他用于此 API 的工具均不具备这些功能。

可持续积累的本地状态

• watchlist items — 在已保存的 CIK 观察列表中，按 Item 代码对时间范围内提交的 8-K 进行分组展示（2.05 重组、5.02 高管变动、4.02 不再依赖）。

  股票分析师按 Item 代码而非公司筛选文件。当 Agent 需要按 Item 跨公司筛选 8-K 时，请选择此功能。

  sec-edgar-pp-cli watchlist items --since 30d --item 2.05,5.02,4.02 --cik 0000320193,0000789019,0001652044 --json
  

• insider-cluster — 标记在滚动的 N 天窗口内，有 3 位或更多不同内幕人士提交了相同交易代码（公开市场买入或卖出）的发行人。

  内幕人士集中抛售是教科书级的取证信号。当 Agent 需要从原始 Form 4 数据中提取衍生信号时，请选择此功能。

  sec-edgar-pp-cli insider-cluster --within 5d --min-insiders 3 --code S --since 90d --json
  

• industry-bench — 对一个报告期的 XBRL 概念按 SIC 代码分组，并输出该 SIC 下所有上市公司申报者的百分位统计数据（p10/p50/p90）。

  量化研究员和股票分析师需要同业基准。当 Agent 需要回答“X 与行业同业相比如何”时，请选择此功能。

  sec-edgar-pp-cli industry-bench --tag us-gaap:Revenues --period CY2024Q4 --sic 7372 --stat p50,p90 --json
  

• cross-section — 对指定的公司列表和最近 N 个报告期内的单个 XBRL 概念进行透视。输出宽表透视表（每家公司一行，每个报告期一列）。

  可比公司分析是分析师最常见的工作之一。当 Agent 需要比较指定股票代码列表中的基本面时，请选择此功能。

  sec-edgar-pp-cli cross-section --tag us-gaap:Revenues --ticker AAPL,MSFT,GOOGL --periods last8 --json
  

• holdings delta — 比较某机构投资者连续两个季度的 13F 持仓。根据股份数量变化，将每个发行人归类为 ADD / EXIT / INCREASE / DECREASE。

  追踪机构资金流向是经典的因子信号。当 Agent 需要比较某基金在不同季度的持仓时，请选择此功能。

  sec-edgar-pp-cli holdings delta --filer-cik 0001067983 --period 2024Q4 --vs 2024Q3 --json
  

面向 Agent 的原生基础设施

• watch — 以多维度筛选条件（表单类型、8-K Item、CIK 观察列表和关键词正则表达式）流式读取 SEC Atom getcurrent feed。每个匹配项输出一行 NDJSON。

  监控特定文件事件的 Agent 应订阅此数据流，而不是按 CIK 轮询提交记录。

  sec-edgar-pp-cli watch --form 8-K --item 2.05 --cik 0000320193,0000789019 --keyword 'going concern' --one-shot --json
  

SEC 特定信号

• restatements — 显示 8-K 第 4.02 项（不再依赖先前财务报表），以及该时间范围内提交的所有 10-K/A 和 10-Q/A 修订文件——这是典型的会计异常信号。

  法证会计 Agent 会将重述视为问题的先行指标。若 Agent 需要会计质量信号，请选择此项。

  sec-edgar-pp-cli restatements --since 90d --json
  

• late-filers — 查找在该时间范围内提交了 NT 10-K、NT 10-Q 或 NT 20-F 的发行人——这是 SEC 的“我将错过报告截止日期”通知。

  逾期申报是运营或会计问题的先行指标。若 Agent 需要标记高风险公司，请选择此项。

  sec-edgar-pp-cli late-filers --since 90d --form 10-K --json
  

代理声明与所有权

• ownership — 根据股票代码、名称或 CIK 查找公司，找到该公司最新的 DEF 14A 代理声明，获取文件，并将“特定受益所有人的证券所有权”部分提取为可读文本。

  每份代理声明中都有标题几乎相同的受益所有权表，但要找到它，需要串联提交记录查询 → 获取文件 → 提取 HTML 部分，而 SEC 没有任何单一端点能完成这一流程。若 Agent 需要直接从代理声明中了解公司所有者，请选择此项。

  sec-edgar-pp-cli ownership MSFT --json
  

命令参考

companies — 公司目录（股票代码 → CIK → 名称）

• sec-edgar-pp-cli companies tickers — 所有拥有上市股票代码的上市公司发行人的完整股票代码到 CIK 映射（约 1 万条）
• sec-edgar-pp-cli companies tickers_exchange — 按交易所（Nasdaq、NYSE 等）索引的股票代码到 CIK 映射
• sec-edgar-pp-cli companies tickers_mf — 共同基金股票代码到 CIK 的映射（每个股份类别一行）

facts — XBRL 财务事实（data.sec.gov）

• sec-edgar-pp-cli facts company — 获取公司所有报告期的 XBRL 事实
• sec-edgar-pp-cli facts frame — 获取一个期间内所有公开申报者报告的某个 XBRL 概念值（跨公司切片）
• sec-edgar-pp-cli facts get — 获取一家公司的单个 XBRL 概念时间序列（一个标签，涵盖其所有申报文件）

submissions — 申报者（公司）申报历史

• sec-edgar-pp-cli submissions <cik> — 根据 10 位补零 CIK 获取申报者的完整申报历史

查找合适的命令

如果你知道要做什么，但不知道该用哪个命令，可以直接向 CLI 提问：

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

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中匹配最合适的命令。退出代码 0 表示至少找到一项匹配；退出代码 2 表示没有足够可信的匹配——请改用 --help，或使用范围更窄的查询。

用例

适合 Agent 使用的 Apple 利润表趋势

sec-edgar-pp-cli facts statement --cik 0000320193 --kind income --periods last8 --agent --select 'facts.us-gaap.Revenues,facts.us-gaap.OperatingIncomeLoss,facts.us-gaap.NetIncomeLoss'

XBRL 响应嵌套层级很深；使用带点号路径的 --select，只提取 Agent 需要的三个概念在最近 8 个期间的数据。

集中买入观察名单扫描

sec-edgar-pp-cli insider-cluster --within 14d --min-insiders 3 --code P --since 90d --json

在最近 90 天内，筛选 14 天内有 3 名或更多内部人士集中进行公开市场买入（Form 4 代码 P）的情况。由存储层支持的 JOIN 让这一切只需一条命令即可完成。

季度同业组收入透视

sec-edgar-pp-cli cross-section --tag us-gaap:Revenues --cik 0000320193,0000789019,0001652044 --periods last8 --json

将 Apple、Microsoft 和 Alphabet 最近 8 个季度的收入汇总为一个透视表。两个轴都有限定条件——edgartools 和 frames 端点都无法处理这种数据形态。

周一观察名单筛查

sec-edgar-pp-cli watchlist items --since 30d --item 2.05,5.02,4.02 --cik 0000320193,0000789019,0001652044 --json --agent

跨 CIK 的 8-K 第 4 项透视——这是 Maya 每周一固定执行的流程。观察名单文件每行包含一个 CIK。

逾期申报合规扫描

sec-edgar-pp-cli late-filers --since 60d --form 10-K --json

显示 NT 10-K 申报文件（即警告将错过报告截止日期的公司）。通过针对本地申报文件表的单条 SELECT 查询完成。

身份验证设置

SEC EDGAR 无需 API 密钥。每个请求都必须包含 User-Agent 标头，其中注明个人姓名和联系邮箱（例如 'Alex Researcher [email protected]'）。请在环境中设置 SEC_EDGAR_USER_AGENT；未设置时 CLI 会拒绝运行。SEC 对每台主机实施每秒 10 个请求的速率上限；此 CLI 会将自身限制为每秒 8 个请求，并加入随机抖动。

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

Agent 模式

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

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

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

  sec-edgar-pp-cli facts get --cik example-value --taxonomy example-value --tag example-value --agent --select id,name,status
  

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

• 支持离线 — 同步／搜索命令在本地 SQLite 存储可用时可以使用它

• 非交互式 — 不会提示输入，所有输入都通过标志传入

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

响应封装

从本地存储或 API 读取数据的命令会将输出封装在溯源信封中：

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

解析 .results 获取数据，并通过 .meta.source 判断数据来自实时来源还是本地来源。只有 stdout 连接到终端时，才会向 stderr 输出易读的 N results (live) 摘要；通过管道传递或由 Agent 使用时，stdout 只会输出纯 JSON。

Agent 反馈

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

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

条目会本地存储在 ~/.sec-edgar-pp-cli/feedback.jsonl 中。只有设置了 SEC_EDGAR_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 SEC_EDGAR_FEEDBACK_AUTO_SEND=true，才会通过 POST 发送。默认情况下，反馈仅保存在本地。

写下让你感到意外的地方，而不是提交错误报告。简短、具体、单行：这才是能持续累积价值的内容。

输出交付

每个命令都接受 --deliver <sink>。输出除了（或不再输出到）stdout 外，还会发送到指定的目标，因此 Agent 无需手动通过管道传递命令结果。支持三种目标：

目标	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子性地写入 <path>（先写入临时文件，再重命名）
webhook:<url>	将输出正文 POST 到 URL（使用 --compact 时，内容类型为 application/json 或 application/x-ndjson）

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

命名配置

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

sec-edgar-pp-cli profile save briefing --json
sec-edgar-pp-cli --profile briefing facts get --cik example-value --taxonomy example-value --tag example-value
sec-edgar-pp-cli profile list --json
sec-edgar-pp-cli profile show briefing
sec-edgar-pp-cli profile delete briefing --yes

显式标志始终优先于配置文件中的值；配置文件中的值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置文件，供进行自检的 Agent 在运行时发现它们。

退出码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/developer-tools/sec-edgar/cmd/sec-edgar-pp-mcp@latest
   

2. 在 Claude Code 中注册：

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

3. 验证：claude mcp list

直接使用

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

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

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