pp-nasa-images

NASA Image and Video Library — Printing Press CLI

前提条件：安装 CLI

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

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

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

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

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

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/nasa-images/cmd/nasa-images-pp-cli@latest

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

何时使用此 CLI

当 Agent 或工作流需要以确定的方式访问 NASA 公有领域媒体档案时，可使用此 CLI——例如搜索图像、选择素材版本、提取说明文字、批量归档专辑，无需解析散文内容。本地 SQLite 镜像可让重复查询无需额外成本，并支持上游 API 不具备的时间顺序／主题时间线分析。MCP 接口为 Claude Agent 提供了针对每个端点的类型化工具，以及新颖的组合命令（assets best、captions fetch text、citation 等）。

何时不使用此 CLI

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

独特功能

这些功能是此 API 的其他工具所不具备的。

可累积的本地状态

• download album — 批量下载精选 NASA 专辑中的每个素材，并支持按字节范围续传；重新运行时会从上次传输失败处准确继续。

  当你需要为演示文稿或档案收集 200 张 NASA 图像时，这个命令能一锤定音——不稳定的 Wi-Fi、休眠后恢复、中途取消都不再是问题。

  nasa-images-pp-cli download album Apollo-at-50 --variant orig --resume --out ./apollo
  

• recent — 在已同步的本地镜像中进行 FTS5 搜索（标题、描述、description_508、关键词、专辑），并按上游 API 不提供的时间顺序排序。

  突发新闻出现时，你可以在毫秒内调出有关主题的最新 NASA 图像，无需在数十年的档案结果中逐页查找。

  nasa-images-pp-cli recent --q "perseverance" --sort date-desc --limit 20 --json
  

• center profile — 在已同步的缓存上进行本地汇总：统计 11 个 NASA 中心之一的 media_type、按年份分桶的直方图、热门关键词和热门摄影师。

  记者可以在搜索前回答“哪个中心会发布这类图像”，在某个中心显然是信息来源的报道中节省搜索时间。

  nasa-images-pp-cli center profile JPL --json
  

• unused-in — 列出精选专辑中尚未在本地下载的 nasa_ids——通过反连接查询下载记录表得出。

  规划下周的幻灯片时，无需重复选择同一张图像，也无需手动记录已使用过的 nasa_ids。

  nasa-images-pp-cli unused-in Apollo-at-50 --json
  

• timeline — 对 FTS 匹配的行按 strftime('%Y-%m', date_created) 进行本地 GROUP BY；输出按月份分桶的数量，显示某个主题何时获得报道。

  找出发布模式——沉寂的月份、新品发布高峰——从而发现关键词搜索会隐藏的报道角度。

  nasa-images-pp-cli timeline --q "perseverance" --bucket month --json
  

我们为你处理的 API 间接跳转

• captions fetch — 返回字幕文件内容（.srt 或 .vtt），而不只是 URL；还提供可选的 --format text 模式，可去除字幕序号和时间码，生成易读的文字稿。

  使用 NASA 视频字幕进行分析、搜索或查找引文的 Agent，无需额外发起 HTTP 请求，也不必再进行解析。

  nasa-images-pp-cli captions fetch jsc2022m000123 --format text --agent
  

• metadata fetch — 跟进 /metadata/{id} 间接跳转，获取 metadata.json 伴随文件，展平 AVAIL:* 和 EXIF 字段，并丢弃会泄露内部路径的字段（SourceFile、File:Directory、AVAIL:Owner）。

  记者和教育工作者无需手动清理冗余字段，即可获取署名照片来源信息（摄影师 + 中心 + 日期）。

  nasa-images-pp-cli metadata fetch PIA24439 --json --select AVAIL:Title,AVAIL:Photographer,AVAIL:DateCreated
  

面向 Agent 的原生管道

• assets best — 解析资源的衍生版本清单，按变体（orig/large/medium/small/thumb）对每个文件分类，按调用方的偏好顺序筛选，可选设置字节上限，并准确输出一个 URL。

  MCP 中的 Claude Agent 可以请求“获取 nasa_id X 的 5 MB 以下最佳版本”，并准确得到一个 URL，无需耗费 token 解析文件名。

  nasa-images-pp-cli assets best as11-40-5874 --prefer orig,large,medium --max-bytes 5000000
  

特定领域快捷命令

• citation — 根据缓存的元数据（摄影师、日期、中心、nasa_id、URL）生成可直接粘贴的引用字符串（APA / MLA / Chicago）。

  在作品中插入一张 NASA 图片，然后在下方粘贴引用即可，无需手动设置格式。

  nasa-images-pp-cli citation PIA24439 --style apa
  

命令参考

albums — 获取 NASA 精选相册的内容（例如 Apollo-at-50、Mars-Perseverance）

• nasa-images-pp-cli albums <album_name> — 返回精选相册的分页资源列表。相册名称区分大小写（Apollo-at-50 可用，apollo-at-50……

assets — 获取资源的衍生版本清单（每个文件的 URL：图片包含 original/large/medium/small/thumb；视频包含 mp4 变体；音频包含 mp3/m4a）

• nasa-images-pp-cli assets <nasa_id> — 返回资源的所有文件 URL 列表

captions — 获取视频资源字幕文件（.srt 或 .vtt）的位置 URL

• nasa-images-pp-cli captions <nasa_id> — 返回字幕文件的位置 URL。仅适用于视频资源；图片返回 400，没有字幕的视频返回 404……

media — 使用自由文本和筛选条件搜索 NASA 图片与视频库目录

• nasa-images-pp-cli media — 使用自由文本或筛选条件搜索目录。至少需要一个查询参数。

metadata — 获取资源 metadata.json 伴随文件的位置 URL（AVAIL 编辑信息 + ExifTool 字段）

• nasa-images-pp-cli metadata <nasa_id> — 返回资源 metadata.json 伴随文件的位置 URL。使用 metadata fetch（新命令）来跟进……

找到合适的命令

知道要做什么，但不清楚该用哪个命令时，可以直接询问 CLI：

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

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中找出最匹配的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有可信的匹配项，此时可回退到 --help，或使用更具体的查询。

手写扩展

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

• nasa-images-pp-cli download album <album_name> — 批量下载精选相册中的所有资源，并支持按字节范围续传 — 重新运行时会从上次中断的位置继续……
• nasa-images-pp-cli captions fetch <nasa_id> — 获取视频资源的字幕文件内容（.srt 或 .vtt），而不只是获取其 URL。使用 --format text 时，会去除字幕序号……
• nasa-images-pp-cli metadata fetch <nasa_id> — 获取资源的完整元数据 sidecar 内容，并将其扁平化（AVAIL:* 和 EXIF 字段）。移除泄露字段（SourceFile，……
• nasa-images-pp-cli assets best <nasa_id> — 确定性地挑选最佳变体。解析资源的版本清单，按优先级顺序筛选并输出……
• nasa-images-pp-cli recent — 对本地同步镜像进行 FTS5 全文搜索，并按时间顺序排列（date_created 降序）——……
• nasa-images-pp-cli center profile <center_code> — 按 NASA 中心进行本地汇总（media_type 计数、年份分桶直方图、热门关键词、热门摄影师）……
• nasa-images-pp-cli unused-in <album_name> — 列出精选相册中尚未下载到本地的 nasa_id（与下载记录表执行反连接）
• nasa-images-pp-cli timeline — 主题时间线直方图。对 FTS 匹配的行按年月在本地执行 GROUP BY；显示某个主题何时获得报道
• nasa-images-pp-cli citation <nasa_id> — 根据缓存或获取的元数据生成可直接粘贴的引文（APA、MLA 或 Chicago 格式）

示例

查找最近的火星图像并挑选最佳变体

nasa-images-pp-cli media --q "mars rover" --year-start 2024 --media-type image --page-size 5 --json --select 'collection.items.data.nasa_id,collection.items.data.title' | jq -r '.collection.items[0].data[0].nasa_id' | xargs -I {} nasa-images-pp-cli assets best {} --prefer orig,large

分两步执行：搜索返回 nasa_ids，assets best 将选中的资源解析为单个 URL。

存档整个精选相册

nasa-images-pp-cli download album Webb-Telescope-First-Images --variant large --resume --out ./webb-firsts

遍历相册的每一页，为每个项目获取资源清单，然后按字节范围续传每个变体的下载。

获取视频文字稿

nasa-images-pp-cli captions fetch jsc2022m000123 --format text > webb-deployment.txt

字幕需通过两次 GET 请求获取；--format text 会去除 SRT 字幕序号，生成干净的文字稿。

构建离线 FTS 搜索索引

nasa-images-pp-cli mirror search --q "apollo" --year-start 1968 --year-end 1975 && nasa-images-pp-cli recent --q "bootprint" --sort date-desc --json --select 'nasa_id,title,date_created'

mirror search 会填充 SQLite 镜像；recent 使用 FTS5 并按时间顺序排序，这是 NASA 上游搜索不支持的功能。

生成 APA 引文

nasa-images-pp-cli citation PIA24439 --style apa

获取元数据 sidecar（来自缓存或实时请求），并将其格式化为可直接粘贴的引文。

身份验证设置

无需身份验证。

运行 nasa-images-pp-cli doctor 验证设置。

Agent 模式

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

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

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

  nasa-images-pp-cli albums mock-value --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 有什么不对劲时，请记录下来：

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

条目会本地存储在 ~/.nasa-images-pp-cli/feedback.jsonl。除非设置了 NASA_IMAGES_FEEDBACK_ENDPOINT，并且传入 --send 或设置 NASA_IMAGES_FEEDBACK_AUTO_SEND=true，否则绝不会发送 POST 请求。默认行为仅限本地。

记录让你感到意外的事情，而不是提交错误报告。简短、具体，写成一行：这才是会不断累积的部分。

输出传递

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

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

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

命名配置

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

nasa-images-pp-cli profile save briefing --json
nasa-images-pp-cli --profile briefing albums mock-value
nasa-images-pp-cli profile list --json
nasa-images-pp-cli profile show briefing
nasa-images-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

安装 MCP 服务

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

claude mcp add nasa-images-pp-mcp -- nasa-images-pp-mcp

验证：claude mcp list

直接使用

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

   nasa-images-pp-cli <command> [subcommand] [args] --agent
   

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