pp-movie-goat

Movie Goat — Printing Press CLI

前置条件：安装 CLI

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

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

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

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

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

何时使用此 CLI

当 Agent 需要结合流媒体可用性和多个来源的评分来回答影迷问题时，请使用 Movie Goat。它适用于今晚选片、系列电影马拉松规划和带评分的演艺生涯时间线场景。不适用于票房追踪、影评情感分析，也不适用于需要大模型风格的剧情或影评摘要的工作流。

何时不使用此 CLI

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

独特功能

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

影迷仪式

• tonight — 从你订阅的服务中，筛选实际可观看的热门影片，挑选今晚要看的内容。

  当 Agent 需要经过流媒体筛选的候选列表时使用；一次调用即可替代在 TMDb/RT/JustWatch 之间来回切换。

  movie-goat-pp-cli tonight --mood thriller --max-runtime 120 --providers netflix,max --region US --json
  

• ratings — 在一张卡片中展示任意影片的 TMDb、IMDb、Rotten Tomatoes 和 Metacritic 评分。

  当 Agent 需要影片的权威多来源评分时使用；如果未设置 OMDB_API_KEY，则会自动退化为仅使用 TMDb 评分。

  movie-goat-pp-cli ratings 550 --json
  

• 支持翻拍片的片名解析 — 接受片名而非 TMDb id 的每条命令都会明确提示是否存在同名影片。

  TMDb 搜索会按专有相关性评分排序，因此 "Sabrina" 会解析为 1995 年的翻拍版，即使 1954 年 Wilder 执导的原版评分更高。当多个匹配影片的评分都较高时，CLI 会通过两种渠道报告：在 stderr 上向用户显示提示，并在 stdout 的 JSON 中提供 meta.ambiguous 记录，供不会读取 stderr 的使用方使用。可通过 --year、"Title (YYYY)" 后缀或 id 指定你想要的影片。

  movie-goat-pp-cli ratings "Sabrina" --year 1954 --json
  

• marathon — 规划系列电影马拉松，包括观看顺序、总时长和建议休息时间。

  规划集体观影活动时使用；Agent 可导出日程并与群组分享。

  movie-goat-pp-cli marathon "The Avengers" --order release --breaks-every 240 --json
  

• career — 探索任意演员或导演的完整作品年表，包含评分和时间顺序。

  当 Agent 需要带评分的时间顺序作品年表时使用；以跨来源评分取代平铺的 IMDb 列表。

  movie-goat-pp-cli career "Christopher Nolan" --since 2010 --role director --json
  

• versus — 并排比较两部电影或剧集的评分、演员阵容、时长和流媒体信息。

  当 Agent 需要在两个最终候选作品中做出选择时使用；一条命令即可展示它们在各个方面的差异。

  movie-goat-pp-cli versus 550 27205 --region US --json
  

• collaborators — 列出某人的作品中出现 2 次或以上的合作人员，并显示次数和作品名称。

  研究电影人的合作圈时使用；可自动找出反复合作的摄影指导、作曲家和演员。

  movie-goat-pp-cli collaborators "Christopher Nolan" --min-count 3 --role crew --json
  

能持续积累的本地状态

• watchlist list — 本地 SQLite 关注列表；标记可在你订阅的服务上播放的条目。

  每周使用一次，从已保存的列表中找出可播放的内容；无需再针对每部影片临时查询 JustWatch。

  movie-goat-pp-cli watchlist list --available --providers netflix,max --region US --json
  

• queue — 根据关注列表中的推荐和相似内容，推荐下一部要看的作品。

  当 Agent 需要根据已保存的兴趣生成新片单时使用；结合本地状态与 API 推荐。

  movie-goat-pp-cli queue --limit 20 --providers netflix,max --region US --json
  

命令参考

auth — 管理 TMDB_API_KEY 和 OMDB_API_KEY 凭据

• movie-goat-pp-cli auth status — 显示 TMDb 和 OMDb 凭据的身份验证状态
• movie-goat-pp-cli auth set-token — 将 TMDb API 令牌保存到配置文件
• movie-goat-pp-cli auth set-omdb-token — 将可选的 OMDb API 令牌保存到配置文件
• movie-goat-pp-cli auth logout — 清除已保存的凭据

discover — 使用丰富的筛选条件发现电影和电视节目

• movie-goat-pp-cli discover movies — 按类型、年份、评分、分级、演员、剧组、流媒体服务等条件发现电影
• movie-goat-pp-cli discover tv — 按类型、年份、评分、电视网和流媒体服务发现电视节目

genres — 获取电影和电视节目的类型列表

• movie-goat-pp-cli genres movies — 获取电影类型列表
• movie-goat-pp-cli genres tv — 获取电视节目类型列表

movies — 搜索和浏览电影

• movie-goat-pp-cli movies get — 获取电影的详细信息，包括演员、评分和流媒体播放情况
• movie-goat-pp-cli movies now-playing — 获取当前正在影院上映的电影
• movie-goat-pp-cli movies popular — 获取当前热门电影
• movie-goat-pp-cli movies search — 按片名搜索电影
• movie-goat-pp-cli movies top-rated — 获取评分最高的电影
• movie-goat-pp-cli movies upcoming — 获取即将上映的电影

multi — 跨电影、电视节目和人物进行多类型搜索

• movie-goat-pp-cli multi <query> — 使用单个查询搜索电影、电视节目和人物

people — 搜索和浏览人物（演员、导演、剧组成员）

• movie-goat-pp-cli people get — 获取人物的详细信息，包括其影视作品列表
• movie-goat-pp-cli people popular — 获取娱乐行业的热门人物
• movie-goat-pp-cli people search — 按姓名搜索人物

trending — 获取热门电影、电视节目和人物

• movie-goat-pp-cli trending all — 获取热门电影、电视节目和人物
• movie-goat-pp-cli trending movies — 获取热门电影
• movie-goat-pp-cli trending people — 获取热门人物
• movie-goat-pp-cli trending tv — 获取热门电视节目

tv — 搜索和浏览电视节目

• movie-goat-pp-cli tv airing-today — 获取今天有剧集播出的电视节目
• movie-goat-pp-cli tv get — 获取电视节目的详细信息
• movie-goat-pp-cli tv on-the-air — 获取当前正在播出的电视节目
• movie-goat-pp-cli tv popular — 获取当前热门电视节目
• movie-goat-pp-cli tv search — 按名称搜索电视节目
• movie-goat-pp-cli tv top-rated — 获取评分最高的电视节目

找到合适的命令

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

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

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

使用示例

今晚观看：评分高且可在我的服务上播放

movie-goat-pp-cli tonight --mood drama --max-runtime 130 --providers netflix,max,prime --region US --agent --select "results.title,results.year,results.rating,results.providers"

按流媒体服务筛选的候选短名单，仅包含 Agent 决策所需的关键字段。

扫描关注列表

movie-goat-pp-cli watchlist list --available --providers netflix,max --region US --agent

每周检查：已保存的哪些影片现在可以在我订阅的服务上播放。

按评分深入探索演员生涯

movie-goat-pp-cli career "Lynne Ramsay" --role director --agent --select "credits.title,credits.year,credits.rating_imdb,credits.rating_rt"

由 Agent 界定范围的按时间顺序排列的影视作品列表，包含重要的跨来源评分列。

从两部决赛作品中挑选

movie-goat-pp-cli versus 27205 87108 --region US --agent

并排比较《Inception》和《Tenet》的卡片，包含评分、片长、演员阵容重合情况和提供方。

不接触 shell 环境即可保存两个 API 密钥

movie-goat-pp-cli auth set-token YOUR_TMDB_API_KEY
movie-goat-pp-cli auth set-omdb-token YOUR_OMDB_API_KEY
movie-goat-pp-cli auth status --agent

将两项凭据写入 ~/.config/movie-goat-pp-cli/config.toml（模式为 0600），这样机器上的每个 Agent 和 shell 都能看到它们，而不仅仅是导出环境变量的那个。auth status 会报告 authenticated、omdb_configured 和 omdb_source，让 Agent 在运行 ratings 前判断 IMDb / RT / Metacritic 列是否会有数据。

锁定原版，而非翻拍版

movie-goat-pp-cli ratings "Sabrina" --year 1954 --agent
movie-goat-pp-cli ratings "Sabrina (1954)" --agent
movie-goat-pp-cli versus "Sabrina (1954)" "Sabrina (1995)" --agent

ratings、marathon 和 watchlist add 支持 --year；所有接受标题的命令（包括带两个位置参数的 versus）都支持内联的 "Title (YYYY)" 后缀。若两者都未指定，CLI 仍会采用 TMDb 排名最高的结果，但会在 stderr 中打印其他候选的 ID：

warn: "Sabrina" matches 3 titles on TMDb; using id 11860 — Sabrina (1995).
      TMDb's search relevance put it first, but Sabrina (1954) has more ratings (1373 vs 703).
      Other matches:
        6620  Sabrina (1954)
        503902  Sabrina (2018)
      Disambiguate with --year <YYYY>, a "title (YYYY)" suffix, or the TMDb id.

/search/* 会按 TMDb 未公开的相关性分数对结果排序。它不是投票数，也不是 popularity 字段——在这个案例中，1954 年的条目在这两项上都领先（1373 对 703 条评分，4.25 对 3.60 的受欢迎度），但结果仍排在第二位。这就是排名第一的结果可能与公认版本不一致的原因，也是提示会比较投票数的原因：这是唯一可读取的排序依据。

同名但没有评分的冷门作品不会触发提示，因此 ratings "Inception" 不会输出提示。

即使脚本从不读取 stderr，也能发现这一情况。 同一事件会记录在 JSON 响应的 meta.ambiguous 中，因此，即使是使用 2>/dev/null 运行的 cron 作业或管道——也就是无人监看、错误年份最危险的情况——也能检测到：

movie-goat-pp-cli ratings "Sabrina" --agent 2>/dev/null | jq '.meta.ambiguous'

[
  {
    "query": "Sabrina",
    "kind": "titles",
    "match_count": 3,
    "signal": "alternative_better_rated",
    "chosen":  { "tmdb_id": 11860, "title": "Sabrina", "year": "1995", "vote_count": 703 },
    "alternatives": [
      { "tmdb_id": 6620,   "title": "Sabrina", "year": "1954", "vote_count": 1373 },
      { "tmdb_id": 503902, "title": "Sabrina", "year": "2018", "vote_count": 194 }
    ],
    "hint": "Disambiguate with --year <YYYY>, a \"title (YYYY)\" suffix, or the TMDb id."
  }
]

当 TMDb 搜索排名第一的条目并非评分最高的条目时，signal 的值为 alternative_better_rated——应将其视为“停止操作并锁定一个 ID”；如果首选条目同时也是评分最高的条目，则值为 multiple_exact_matches。meta.ambiguous 是一个列表，因为一条命令可能会解析多个标题（versus 会解析两个）。

popularity 是 TMDb 的趋势分数，按报告值原样传递。它不是结果返回的顺序，也不是信号比较的依据——比较依据是 vote_count。

值得了解的规则：

• 附加式。 仅当 stderr 提示触发时才会出现该字段。没有歧义的查询完全不包含 meta 键，因此现有解析器不会受到影响。
• --select 无法将其过滤掉。 如果查询存在歧义，--select title,ratings 仍会返回 meta.ambiguous——缩小字段列表的习惯恰恰会让它在其他情况下被隐藏。
• --compact / --agent 会保留它。 紧凑模式的允许列表适用于数组；这些响应是对象，其紧凑处理采用的是阻止列表，不会改动 meta。
• --quiet 会静默 stderr 提示，但不会删除记录。 两者是面向不同受众的独立通道。请注意，这些命令中的 --quiet 会完全抑制 stdout（这是原有行为），因此应使用不带 --quiet 的 --json 来读取该字段。

规划一场系列电影之夜

movie-goat-pp-cli marathon "Mission: Impossible" --order release --breaks-every 240 --agent

按顺序排列的片单，附总片长和休息建议。

身份验证设置

Movie Goat 使用两个 API 密钥，每个密钥都可以存放在配置文件或环境中。

密钥	必需	保存到配置	环境变量
TMDb v3（免费，https://www.themoviedb.org/settings/api）	是	movie-goat-pp-cli auth set-token <token>	TMDB_API_KEY
OMDb（免费，http://www.omdbapi.com/apikey.aspx）	否	movie-goat-pp-cli auth set-omdb-token <token>	OMDB_API_KEY

两个密钥都以 api_key 和 omdb_api_key 的名称存储在 ~/.config/movie-goat-pp-cli/config.toml 中（模式为 0600）。对于任一密钥，环境变量的优先级都高于已保存的值，因此现有的基于环境变量的设置会照常运行。

TMDb 密钥通过查询参数发送，而不是通过 Bearer 标头发送。没有 OMDb 密钥时，ratings、versus 和 career 会仅显示 TMDb 数据，并妥善省略 IMDb / RT / Metacritic 列。

movie-goat-pp-cli auth status 会报告两个凭据及其各自的来源；movie-goat-pp-cli auth logout 会从配置文件中清除这两个密钥。

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

Agent 模式

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

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

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

  movie-goat-pp-cli movies get 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 指向终端时，才会将易读的 N results (live) 摘要输出到 stderr；通过管道传输的使用方或 Agent 使用方会在 stdout 上收到纯 JSON。

Agent 反馈

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

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

条目会本地存储在 ~/.movie-goat-pp-cli/feedback.jsonl 中。只有设置了 MOVIE_GOAT_FEEDBACK_ENDPOINT，并且传入了 --send 或将 MOVIE_GOAT_FEEDBACK_AUTO_SEND=true 时，才会通过 POST 发送。默认行为仅在本地存储。

写下让你感到意外的地方，而不是提交错误报告。简短、具体、一行即可：这才是会不断累积价值的内容。

输出传递

每个命令都接受 --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”模式。

movie-goat-pp-cli profile save briefing --json
movie-goat-pp-cli --profile briefing movies get mock-value
movie-goat-pp-cli profile list --json
movie-goat-pp-cli profile show briefing
movie-goat-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

安装 MCP 服务

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/movie-goat/cmd/movie-goat-pp-mcp@latest
   

2. 注册到 Claude Code：

   claude mcp add -e TMDB_API_KEY=<your-tmdb-key> -e OMDB_API_KEY=<your-omdb-key> movie-goat-pp-mcp -- movie-goat-pp-mcp
   

   OMDB_API_KEY 是可选项，但它能在 ratings、versus 和 career 中启用 IMDb、Rotten Tomatoes 和 Metacritic 的信息补充。
3. 验证：claude mcp list

直接使用

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

   movie-goat-pp-cli <command> [subcommand] [args] --agent
   

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