pp-atlas-obscura

Atlas Obscura — Printing Press CLI

前提条件：安装 CLI

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

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

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

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

如果 npx 安装失败（例如没有 Node、处于离线状态等），请改用 Go 直接安装（需要 Go 1.26.6 或更高版本）。此方式会将程序安装到 $GOPATH/bin（默认是 $HOME/go/bin），因此请将该目录添加到 $PATH：

go install github.com/mvanhorn/printing-press-library/library/travel/atlas-obscura/cmd/atlas-obscura-pp-cli@latest

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

按关键词或坐标搜索世界上隐秘的奇观，获取地点详情及出行须知，并将所有内容同步到本地 SQLite 存储中，以便离线使用和原生支持 Agent。还可以完成任何抓取工具都做不到的事：查找驾车路线沿途的奇观、保存并导出行程，以及记录你去过的地方。内容来自 atlasobscura.com 社区，不是官方 API。

何时使用此 CLI

当用户想寻找偏僻、特别或隐秘的兴趣点时，可使用 Atlas Obscura，例如规划旅行、自驾游，或在行程中添加令人好奇的停留点。它擅长查找两座城市之间路线沿线的景点、累积保存的行程，以及离线查询本地镜像数据。当任务是发现奇特或奇妙的地方，而非预订常规旅行服务时，就应使用它。

不适用场景

以下情况不要使用此 CLI：

• 不要用于预订酒店、航班或餐厅——它只展示地点。
• 不要用于查找主流旅游景点或评论；它精选的是奇特景点，不是通用兴趣点目录。
• 不要用于查询实时营业时间或售票信息——Atlas Obscura 没有结构化的营业时间数据；请查看地点自己的网站。

独特功能

这些功能是其他任何用于此 API 的工具都不具备的。

行程规划

• route — 查找两座城市之间驾车路线沿途的 Atlas Obscura 奇观，而不只是单个地点的奇观。

  当用户要在两地之间驾车，并希望沿途停留参观有意思的地方时使用。

  atlas-obscura-pp-cli route "San Francisco" "Los Angeles" --min-score 6 --limit 15 --json
  

• cluster — 将邻近的奇观划分为紧凑的空间集群，方便安排半天的步行行程。

  将一批邻近的奇观规划成高效的步行一日游路线。

  atlas-obscura-pp-cli cluster "Edinburgh" --radius 3 --min 3 --json
  

• export — 将已保存的行程导出为 GPX、GeoJSON 或 Markdown 行程安排，全程离线完成。

  将自驾游路线导入 GPS 或地图工具，也可以生成人类可读的记录。

  atlas-obscura-pp-cli export california-oddities --format md
  

持续积累的本地状态

• trip — 将地点添加到命名行程中，并在不同会话间保留。

  跨多个会话逐步规划行程，无需每次都重新搜索。

  atlas-obscura-pp-cli trip add winchester-mystery-house --trip california-oddities
  

• visited — 记录你看过的奇观，可选择添加日期和备注。

  记住已经看过的地方，让 gaps 和 surprise 跳过这些地点，避免遗漏或重复惊喜。

  atlas-obscura-pp-cli visited mark salvation-mountain --note "worth the desert drive"
  

• gaps — 显示某地点附近尚未游览的优质奇观，并按趣味性排序。

  规划重访某地时，还可以去看看附近哪些地方。

  atlas-obscura-pp-cli gaps "Portland, Oregon" --radius 40 --min-score 6 --json
  

• surprise — 挑选一个尚未游览且趣味性高的奇观；按日期设定随机种子，确保每天的结果固定。

  在 Agent 的每日心跳中使用，推荐新奇观且不会重复。

  atlas-obscura-pp-cli surprise --near "Tokyo" --exclude-visited --json
  

命令参考

categories — 按 Atlas Obscura 类别浏览地点

• atlas-obscura-pp-cli categories <slug> — 列出某个类别中的地点链接（例如 cemeteries、caves、ruins）

destinations — 按目的地（城市／地区）浏览地点

• atlas-obscura-pp-cli destinations <slug> — 列出某个目的地的地点链接（例如 paris-france、new-york）

places — Atlas Obscura 地点（奇观）

• atlas-obscura-pp-cli places <slug> — 按 slug 或数字 ID 获取地点详情页

查找合适的命令

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

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

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

使用示例

规划公路旅行沿途的停靠点

atlas-obscura-pp-cli route "Denver" "Moab" --min-score 6 --limit 12 --json

找出两座城市之间的行车路线范围内评分最高的奇观。

为 Agent 快速扫描附近地点

atlas-obscura-pp-cli near "35.0116,135.7681" --radius 3 --json --select results.title,results.distance_from_query,results.url

将层层嵌套的响应精简为标题、距离和 URL，让 Agent 无需解析图片和坐标等杂项。

创建并导出行程

atlas-obscura-pp-cli trip add winchester-mystery-house --trip ca && atlas-obscura-pp-cli export ca --format md

将地点添加到指定名称的行程中，然后生成包含描述和出行须知的 Markdown 行程单。

查询家附近哪些地方还没去过

atlas-obscura-pp-cli gaps "Austin, Texas" --radius 30 --min-score 6 --json

将缓存的奇观与您的已访问记录进行交叉比对，只返回值得一看的未访地点。

身份验证设置

无需身份验证。

运行 atlas-obscura-pp-cli doctor 以验证设置。

Agent 模式

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

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

• 可筛选 — --select 保留指定字段的子集。点分路径可访问嵌套结构，数组则会逐项遍历。在响应冗长的 API 中，这对于控制上下文大小至关重要：

  atlas-obscura-pp-cli places 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 有不妥之处时，请记录下来：

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

条目会保存在本地 ~/.local/share/atlas-obscura-pp-cli/feedback.jsonl。除非设置了 ATLAS_OBSCURA_FEEDBACK_ENDPOINT，并且传入 --send 或设置 ATLAS_OBSCURA_FEEDBACK_AUTO_SEND=true，否则绝不会通过 POST 发送。默认行为仅保存到本地。

请写下让您意外的地方，而不是提交 Bug 报告。简短、具体、一行即可：这种反馈会逐渐积累价值。

输出传递

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

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

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

命名配置

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

atlas-obscura-pp-cli profile save briefing --json
atlas-obscura-pp-cli --profile briefing places mock-value
atlas-obscura-pp-cli profile list --json
atlas-obscura-pp-cli profile show briefing
atlas-obscura-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/travel/atlas-obscura/cmd/atlas-obscura-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add atlas-obscura-pp-mcp -- atlas-obscura-pp-mcp
   

3. 验证：claude mcp list

直接使用

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

   atlas-obscura-pp-cli <command> [subcommand] [args] --agent
   

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