pp-bandsintown

Bandsintown — Printing Press CLI

前置条件：安装 CLI

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

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

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

2. 验证：bandsintown-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/bandsintown/cmd/bandsintown-pp-cli@latest

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

何时使用此 CLI

当预订相关问题需要汇总多个艺人的 Bandsintown 数据或一段时间内的数据时，请使用此 CLI，例如巡演路线可行性、日历空档检测、联合演出模式、tracker_count 变化。对于“一次性查询 Phoenix 有哪些演出”这类问题，bandsintown.com 网页界面就足够了。对于可重复、由 Agent 驱动的多艺人情报分析，这是合适的工具。

何时不使用此 CLI

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

独特功能

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

路线情报

• route — 查找在指定日期范围内、目标城市附近已有演出的关注艺人，并按可行性为预订提供路线候选。

  在特定城市筹办活动时，成本最低的方案是寻找已经在该地区巡演的艺人。在主动联系新艺人之前，先使用此功能。

  bandsintown-pp-cli route --to "Jakarta,ID" --on 2026-08-15 --window 7d --tracked --json
  

• gaps — 查找艺人巡演日历中符合活动时长的空档，可选按地区筛选。

  使用此功能找出巡演安排中有空档且时间与活动日期相符的艺人，获取最具可操作性的预订线索。

  bandsintown-pp-cli gaps "Beach House" --min 5d --max 21d --in SEA --json
  

• sea-radar — 一键生成东南亚简报：汇总指定日期范围内所有关注艺人的即将举行的演出，按城市分组并标注关注者层级。

  只需调用一次，即可生成周一早间简报：了解活动时间段内哪些艺人在东南亚巡演，并按需求排序。

  bandsintown-pp-cli sea-radar --date 2026-08-01,2026-08-31 --tier mid --json
  

阵容情报

• lineup co-bill — 汇总多个活动的阵容列表，找出经常与指定艺人联合演出的艺人。

  筹备音乐节阵容时，借助真实的同台历史，寻找自然的联合演出组合。

  bandsintown-pp-cli lineup co-bill "Phoenix" --since 2024-01-01 --min-shared 2 --json
  

需求情报

• trend — 跟踪每位艺人的 tracker_count 和 upcoming_event_count 随时间的变化，发现需求上升或下降的信号。

  tracker_count 上升是观众需求的先行指标；使用此功能，在同行注意到之前决定预订哪些艺人。

  bandsintown-pp-cli trend --top 20 --period 30d --json
  

面向 Agent 的基础设施

• pull — 根据过期时间窗口重新获取所有关注艺人的演出，并输出结构化差异（新增／移除／变更的演出），供下游 Agent 使用。

  将此命令设为每日 cron 任务；把差异传入 Slack 或项目跟踪工具，以便在关注的艺人新增演出时发出提醒。

  bandsintown-pp-cli pull --tracked --since-stale 12 --json
  

持续积累的本地状态

• track — 用于关注艺人的本地关注列表，为 sync、snapshot、route 和 sea-radar 提供数据。

  只需创建一次精选关注列表；其他所有情报命令都会读取该列表。

  bandsintown-pp-cli track add "Phoenix" "Tame Impala" "Beach House"
  

命令参考

artists — 管理艺人

• bandsintown-pp-cli artists <artistname> — 获取艺人信息

events — 管理演出

• bandsintown-pp-cli events <artistname> — 获取艺人即将举行、过去或所有演出，也可获取指定日期范围内的演出

查找合适的命令

当你知道想做什么，但不知道该用哪个命令时，可以直接询问 CLI：

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

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

示例用法

周一早晨的 SEA 路线简报

bandsintown-pp-cli sea-radar --date 2026-08-01,2026-08-31 --tier mid --json --select 'shows.city,shows.artist,shows.datetime,shows.tracker_count'

仅打印 8 月活动时段的 SEA 简报，并只包含你需要的字段。先运行 bandsintown-pp-cli pull --tracked，以填充本地存储。

本月需求上升的艺人

bandsintown-pp-cli trend --top 20 --period 30d --json

将今天的 tracker_count 快照与过去 30 天内的快照进行比较。输出上升最快的 20 位艺人。随着时间推移，多次运行 bandsintown-pp-cli snapshot 以扩充时间序列。

候选压轴艺人的音乐节联合演出

bandsintown-pp-cli lineup co-bill "Phoenix" --since 2024-01-01 --min-shared 2 --json

列出自 2024 年以来与 Phoenix 同台演出至少 2 场的所有艺人。结果可直接传入你的阵容规划工具。

查找适合举办活动的艺人日程空档

bandsintown-pp-cli gaps "Beach House" --min 5d --max 21d --in SEA --json

显示 Beach House 的 SEA 巡演日程中 5–21 天的空档——这些都是可采取行动的预订线索。

身份验证设置

无需身份验证。

运行 bandsintown-pp-cli doctor 验证设置。

Agent 模式

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

• 支持管道 — JSON 输出到 stdout，错误输出到 stderr

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

  bandsintown-pp-cli artists mock-value --app-id 550e8400-e29b-41d4-a716-446655440000 --agent --select id,name,status
  

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

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

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

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

响应封装

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

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

解析 .results 获取数据，并查看 .meta.source 以判断数据来自实时来源还是本地存储。只有当 stdout 连接到终端时，才会将便于阅读的 N results (live) 摘要打印到 stderr；通过管道传输的程序／Agent 消费者会在 stdout 上获得纯 JSON。

Agent 反馈

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

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

条目会保存在本地的 ~/.bandsintown-pp-cli/feedback.jsonl 中。除非设置了 BANDSINTOWN_FEEDBACK_ENDPOINT，并且传入了 --send 或 BANDSINTOWN_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” 模式。

bandsintown-pp-cli profile save briefing --json
bandsintown-pp-cli --profile briefing artists mock-value --app-id 550e8400-e29b-41d4-a716-446655440000
bandsintown-pp-cli profile list --json
bandsintown-pp-cli profile show briefing
bandsintown-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

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

claude mcp add bandsintown-pp-mcp -- bandsintown-pp-mcp

验证：claude mcp list

直接使用

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

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

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