pp-usgs-earthquakes

USGS 地震 — Printing Press CLI

前提条件：安装 CLI

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

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

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

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

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

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

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

何时使用此 CLI

只要 Agent 需要回答有关 USGS 地震的问题，就可以使用此 CLI——例如近期活动、历史搜索、单个事件详情、余震序列、区域比较或实时监控。需要速度（离线 SQLite 缓存）、输出便于 Agent 处理（每个命令都支持 --json、--select、--compact、--csv），或工作流涉及多个事件而原始 FDSN API 需要将结果拼接起来时，此 CLI 都是合适的选择。对于非 USGS 地震网络（IRIS 事件服务、EMSC）或波形/台站数据，则不适用——这些需要使用 obspy 这类 FDSN 台站服务客户端。

何时不使用此 CLI

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

独特功能

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

实时监控

• watch — 长时间轮询 USGS 摘要 Feed，并与本地存储进行去重。每发现一个新事件，都会调用可选的 Shell 钩子，用于自定义告警。

  如果你想要长时间监控 USGS 地震，而不想编写轮询循环，可以使用此功能。可插拔的 Shell 钩子可与 notify-send、Slack curl、寻呼系统等任意工具组合使用。

  usgs-earthquakes-pp-cli watch --min-magnitude 5 --notify "echo {id}: {place}" --interval 60s
  

跨事件分析

• aftershocks — 显示主震发生后 R 公里范围内、T 天内的事件，并按时间排序。使用本地 SQLite haversine 查询；若缓存中没有数据，则回退到 FDSN。

  只要你有主震事件 ID，并想查看之后发生了什么，就可以使用此功能。单次调用的替代方案需要将数十次 /query 调用的结果通过 jq 拼接起来。

  usgs-earthquakes-pp-cli aftershocks us7000abcd --radius-km 100 --days 30 --min-mag 3.0 --json
  

• swarm-detect — 检测本地地震存储中的时空集群。网格分桶聚类可找出前震/余震序列、火山群震和诱发地震热点。

  如果你要监控火山、断层带或水力压裂区域中的异常聚集现象，可以使用此功能。输出会为每个集群列出中心、数量、最大震级和时间范围。

  usgs-earthquakes-pp-cli swarm-detect --bbox -122.5,46.5,-121.5,47.5 --window 7d --min-events 10 --cluster-radius-km 20 --json
  

• compare — 并排比较两个区域或两个时间段。以并列列的形式返回事件数量、最大震级和总地震能量。

  回答“区域 A 是否比区域 B 更活跃？”或“这个区域是否比过去安静了？”时，可以使用此功能。输出包含变化百分比和能量比。

  usgs-earthquakes-pp-cli compare --region-a -122.5,37.5,-122.0,37.9 --region-b -118.5,33.8,-118.0,34.2 --window 30d --json
  

面向 Agent 的输出

• brief — 面向 Agent 的单次地震简报：震级、地点、PAGER 警报、DYFI 震感人数、ShakeMap MMI、海啸状态和产品清单。

  在新闻编辑部或 Slack 场景中，如果你需要一份编辑或下游 Agent 可以直接用于文案的单次事件摘要，请使用此工具。包含 USGS 事件页面 URL。

  usgs-earthquakes-pp-cli brief us7000abcd --format markdown
  

• top — 按综合编辑评分对近期事件排序：重要性 × 警报权重 × 震感人数 × 海啸标记。默认时间范围为 24h，数量上限为 10。

  如果你想了解“当前值得关注的事件”，而不是“按震级排列的所有事件”，请使用此工具。综合评分会优先突出有震感、PAGER 警报和海啸的事件，而非仅看震级。

  usgs-earthquakes-pp-cli top --window 24h --limit 10 --score composite --json
  

持续积累的本地状态

• changes — 与上次同步相比的差异：新增了哪些事件、哪些事件的震级／深度／警报有所修订，以及哪些事件已撤回。跟踪 USGS 解决方案随时间的修订。至少完成两次同步后，才会记录修订；在此之前会返回“尚无修订记录”。

  如果某个此前自动生成的事件可能刚由分析师审核过（震级或警报有所修订），或者你想了解“自上次查看后有什么新变化？”，请使用此工具。

  usgs-earthquakes-pp-cli changes --since 24h --type revised --min-mag-delta 0.3 --json
  

• decode-id — 将 USGS 事件 ID 解析为其来源网络代码、序列号和运营方名称。通过缓存的贡献者字典补充网络显示名称。

  如果你看到不透明的 USGS 事件 ID（例如 nc73947885、ak0202xyz），并想在读取数据前了解是哪个网络报告了该事件，请使用此工具。

  usgs-earthquakes-pp-cli decode-id us7000abcd
  

命令参考

catalogs — USGS 地震来源目录（ANSS 贡献者和处理中心）

• usgs-earthquakes-pp-cli catalogs — 列出 FDSN Event 服务已知的所有来源目录（XML 响应）

contributors — USGS 地震数据贡献者

• usgs-earthquakes-pp-cli contributors — 列出 FDSN Event 服务已知的所有数据贡献者（XML 响应）

events — 从 USGS FDSN Event 服务搜索和获取地震信息

• usgs-earthquakes-pp-cli events count — 统计符合给定筛选条件的事件数量，不返回事件数据（完整搜索前的快速预检）
• usgs-earthquakes-pp-cli events get — 按 USGS 事件 ID 获取单个地震事件（例如 us7000abcd）
• usgs-earthquakes-pp-cli events search — 使用完整的 FDSN 参数集搜索 USGS 地震目录

feeds — 预构建的 GeoJSON 地震摘要 Feed（USGS 每分钟更新一次）

• usgs-earthquakes-pp-cli feeds <feed> — 获取指定名称的 GeoJSON 摘要 Feed。可使用：significant_{hour|day|week|month}、4.5_{hour|day|week|month}、...

metadata — FDSN Event 服务元数据：每个参数的枚举值

• usgs-earthquakes-pp-cli metadata — 显示目录、贡献者、事件类型、产品类型和震级类型的枚举字典

查找合适的命令

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

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

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

手写扩展

这些命令由规范作者声明，需要单独手写接线；生成器不会为它们生成 Cobra 注册代码。这里列出这些命令以便查找，并有意将其放在 ## Command Reference 之外，这样 verify-skill 的未知命令检查就不会将它们视为生成器负责的路径。

• usgs-earthquakes-pp-cli recent — 列出近期地震（默认：过去 24 小时，M2.5+）。这是 events search 的便捷封装，支持 --since/--near 标志。
• usgs-earthquakes-pp-cli near <latitude> <longitude> — 显示坐标附近的近期地震，按距离 + 显著性排序。
• usgs-earthquakes-pp-cli sync — 同步滚动地震目录（默认：过去 30 天，M2.5+）以及目录/贡献者/元数据……
• usgs-earthquakes-pp-cli search [query] — 对本地同步的地震数据进行全文搜索（在地点和事件标题上使用 FTS5）。
• usgs-earthquakes-pp-cli sql <query> — 对本地地震存储运行 SELECT 查询。
• usgs-earthquakes-pp-cli feed-list — 列出全部 20 个 USGS 摘要订阅源名称，以及震级级别、周期和更新频率。
• usgs-earthquakes-pp-cli watch — 持续轮询摘要订阅源，并与本地存储去重；可调用可选的 --notify 钩子……
• usgs-earthquakes-pp-cli aftershocks <event-id> — 显示主震发生后 R km、T 天范围内的事件，并按时间排序。使用本地 SQLite 查询；当……时回退到 FDSN。
• usgs-earthquakes-pp-cli swarm-detect — 检测本地存储中的时空集群（前震/余震序列、火山群震、诱发地震……）。
• usgs-earthquakes-pp-cli compare — 并排比较两个区域或两个时间段。使用 --region-a/--region-b 或 --period-a/--period-b。
• usgs-earthquakes-pp-cli brief <event-id> — 面向 Agent 的事件新闻简报：震级、地点、PAGER 警报、DYFI、海啸状态、ShakeMap MMI……
• usgs-earthquakes-pp-cli top — 按综合编辑评分（显著性 × 警报 × 震感 × 海啸）对近期事件排名。默认值：--window 24h……
• usgs-earthquakes-pp-cli changes — 显示自上次同步以来的有状态差异：新增事件、修订后的震级/深度/警报、已删除事件。
• usgs-earthquakes-pp-cli decode-id <event-id> — 将 USGS 事件 ID 解析为网络代码、序列号和运营方（来自缓存的贡献者字典）。

使用示例

过去一小时内发生过值得报道的事件吗？

usgs-earthquakes-pp-cli top --window 1h --limit 10 --json --select events.id,events.mag,events.place,events.alert,events.tsunami,events.score

按综合编辑评分（显著性 × 警报 × 震感 × 海啸）对过去一小时的事件排名，并通过 --select 将 Agent 上下文缩小到仅包含与编辑相关的字段。

跟踪过去 7 天内胡德山附近的群震

usgs-earthquakes-pp-cli swarm-detect --near 45.3736,-121.6960 --radius-km 25 --window 7d --min-events 5 --json

围绕胡德山坐标进行时空聚类；返回带有中心、数量、峰值震级和时间范围的具名集群。

近期主震的余震报告

usgs-earthquakes-pp-cli aftershocks us7000abcd --radius-km 100 --days 14 --min-mag 3.0 --json

使用本地 SQLite haversine 查询，按主震的时间和位置限定范围；如果事件不在缓存中，则回退到 FDSN /query。

每日新闻室头条事件简报

usgs-earthquakes-pp-cli top --window 24h --limit 1 --json --select events.id

仅返回排名最高事件的 ID；通过管道传给 xargs -I {} usgs-earthquakes-pp-cli brief {} --format markdown，即可生成适合新闻室使用的简报。

查找旧金山附近具有 ShakeMap 产品的事件

usgs-earthquakes-pp-cli events search --latitude 37.7749 --longitude -122.4194 --max-radius-km 200 --product-type shakemap --start 2025-01-01 --json

使用 FDSN --product-type 筛选器（竞争 MCP 未提供此筛选器），并结合 --latitude/--longitude 圆形筛选器，查找今年年初以来具有 ShakeMap 多边形的事件。

身份验证设置

无需身份验证。

运行 usgs-earthquakes-pp-cli doctor 以验证设置。

Agent 模式

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

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

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

  usgs-earthquakes-pp-cli catalogs --agent --select id,name,status
  

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

• 适合离线使用 — 若本地 SQLite 存储可用，同步/搜索命令可使用该存储

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

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

响应封装

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

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

解析 .results 获取数据，并查看 .meta.source 以确定数据来自实时数据还是本地数据。只有当 stdout 是终端，且未设置机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将人类可读的 N results (live) 摘要打印到 stderr；通过管道传输的消费者、Agent 消费者以及显式指定格式的运行都会在 stdout 输出纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有问题时，请记录下来：

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

条目会保存在本地 ~/.usgs-earthquakes-pp-cli/feedback.jsonl。除非设置了 USGS_EARTHQUAKES_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 USGS_EARTHQUAKES_FEEDBACK_AUTO_SEND=true，否则不会发送 POST 请求。默认情况下，反馈仅保存在本地。

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

输出交付

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

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

遇到未知方案时会拒绝执行，并返回一条结构化错误，列出支持的方案。Webhook 请求失败时会返回非零状态码，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置

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

usgs-earthquakes-pp-cli profile save briefing --json
usgs-earthquakes-pp-cli --profile briefing catalogs
usgs-earthquakes-pp-cli profile list --json
usgs-earthquakes-pp-cli profile show briefing
usgs-earthquakes-pp-cli profile delete briefing --yes

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

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
5	API 错误（上游问题）
7	触发速率限制（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/other/usgs-earthquakes/cmd/usgs-earthquakes-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add usgs-earthquakes-pp-mcp -- usgs-earthquakes-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which usgs-earthquakes-pp-cli 如果未找到，请提供安装选项（参见本技能开头的先决条件）。
2. 根据“独特功能”和“命令参考”中的内容，将用户查询匹配到最合适的命令。
3. 使用 --agent 标志执行：

   usgs-earthquakes-pp-cli <command> [subcommand] [args] --agent
   

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