pp-alltrails

Alltrails — Printing Press CLI

前提条件：安装 CLI

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

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

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

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

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

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

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

HTTP 传输

此 CLI 使用标准的 Go HTTP 传输；当 AllTrails 协商使用 HTTP/2 时，会启用 HTTP/2。正常的 API 调用无需常驻的浏览器进程。

命令参考

alltrails — 管理 alltrails

• alltrails-pp-cli alltrails create — 上传新的活动记录
• alltrails-pp-cli alltrails get — 获取含 GPS/统计信息界面的活动详情
• alltrails-pp-cli alltrails get-v3 — 获取路线详情数据
• alltrails-pp-cli alltrails get-v3-2 — 获取离线地图元数据
• alltrails-pp-cli alltrails get-v3-3 — 获取地图静态图像元数据/渲染端点
• alltrails-pp-cli alltrails get-v3-4 — 获取路线静态地图图像元数据/渲染端点
• alltrails-pp-cli alltrails get-v3-5 — 获取用户活动列表
• alltrails-pp-cli alltrails list — 按文本、位置和筛选条件搜索路线
• alltrails-pp-cli alltrails list-v3 — 获取当前账户资料

查找合适的命令

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

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

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

身份验证设置

公开读取操作可能无需凭据即可使用。账户路由使用调用方自己的凭据：

• ALLTRAILS_ACCESS_TOKEN — 用于经过身份验证的 API 请求的 Bearer 令牌。
• ALLTRAILS_COOKIE — 用于经过身份验证的路由的浏览器 Cookie 标头。
• ALLTRAILS_CSRF_TOKEN — 必要时，用于基于浏览器的写入路由的 CSRF 标头。

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

写入安全

默认使用读取命令。写入路由会标注 mcp:read-only=false 和 mcp:risk=<level>。

为确保 PP 侧安全，除非同时满足以下两个条件，否则会阻止对 AllTrails 执行实时写入：

1. 调用命令时使用 --live-write，而不是默认的写入试运行模式。
2. 环境中存在 ALLTRAILS_PP_ALLOW_WRITES=1。

如果缺少任一条件，写入路由会预览请求，或在 HTTP 传输前安全地拒绝请求。除非用户已明确批准确切的实时账户变更，否则请勿设置 ALLTRAILS_PP_ALLOW_WRITES。

Agent 模式

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

• 可通过管道传输 — JSON 输出到标准输出，错误输出到标准错误

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

  alltrails-pp-cli alltrails list --agent --select id,name,status
  

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

• 适用于离线场景 — 有本地 SQLite 存储时，sync/search 命令可以使用该存储

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

• 明确重试 — 仅当已存在的创建结果应视为成功时，才使用 --idempotent

sync 默认安全地不执行任何操作，因为在已登录的浏览器上下文之外，AllTrails 浏览器 API 受到 DataDome 保护。只有在配置了调用方自有的身份验证信息/ Cookie，且明确需要实时读取时，才使用 sync --resources routing_info。

响应封装

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

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

解析 .results 获取数据，并通过 .meta.source 判断数据来自实时读取还是本地存储。仅当标准输出连接到终端，且未设置任何机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将便于人类阅读的 N results (live) 摘要打印到标准错误；通过管道传输的/Agent 消费者以及显式指定格式的运行都会在标准输出上获得纯 JSON。

Agent 反馈

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

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

条目会保存在本地 ~/.local/share/alltrails-pp-cli/feedback.jsonl。除非设置了 ALLTRAILS_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 ALLTRAILS_FEEDBACK_AUTO_SEND=true，否则不会发送 POST 请求。默认行为仅保存在本地。

记录让你感到意外的地方，而不是编写错误报告。简短、具体、单行描述：这才是会不断累积价值的部分。

输出传递

每条命令都接受 --deliver <sink>。输出会发送到指定的目标，同时输出到标准输出或替代标准输出，因此 Agent 无需手动通过管道即可路由命令结果。支持三种目标：

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

对于未知方案，系统会拒绝处理，并返回结构化错误，指出支持的方案。Webhook 请求失败时会返回非零状态，并在标准错误中记录 URL 和 HTTP 状态码。

命名配置

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

alltrails-pp-cli profile save briefing --json
alltrails-pp-cli --profile briefing alltrails list
alltrails-pp-cli profile list --json
alltrails-pp-cli profile show briefing
alltrails-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

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

claude mcp add alltrails-pp-mcp -- alltrails-pp-mcp

验证：claude mcp list

直接使用

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

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

4. 如果含义不明确，查看子命令帮助：alltrails-pp-cli <command> --help。