pp-podcast-goat

Podcast GOAT — Printing Press CLI

前置条件：安装 CLI

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

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

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

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

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

何时使用此 CLI

当 Agent 需要阅读或引用长篇播客内容，且你已经订阅该节目时，可以使用 podcast-goat。CLI 会优先尝试你的会员 Cookie，然后回退到免费的 YouTube/Substack/RSS 来源；只有在免费来源都无法使用时，才会付费使用 spoken.md 或音频转录。MCP 接口使其成为 Claude Code Agent 的标准播客适配器——每个命令都是一个 MCP 工具，每次读取都会标注 mcp:read-only。

何时不应使用此 CLI

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

反向触发条件

以下情况不要使用 podcast-goat：

• **下载音频。**此 CLI 不会将音频写入磁盘。请直接使用 yt-dlp 或播客应用。
• **绕过付费墙。**Cookie 层级适配器会重放你自己的已登录会话，仅适用于你已订阅的节目。不要通过此工具读取用户尚未付费获取的内容。
• **由大模型进行摘要或分析。**此 CLI 会将规范 Markdown 内容提供给你的 Agent。摘要由 Agent 完成，而不是在此处完成。
• **实时转录。**音频流水线（whisperapi）是计划在 v0.2 中推出的延后功能；如需实时字幕，请使用流式 Deepgram 客户端。
• **就地编辑或标注转录内容。**输出为只读；请将标注保存在其他位置。

独特功能

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

可不断扩充的跨来源语料库

• magic — 将关于某个主题的排名前 N 的缓存转录内容打包为一个 Markdown 文件，供 Agent 一次调用即可进行摘要。

  用一个命令取代 chip-supply-chain.fly.dev 的复制粘贴工作流。需要 Agent 综合分析多个剧集时，请使用此功能。

  podcast-goat-pp-cli magic 'AI chip supply chain' --out ~/chip-supply-chain.md
  

• episode get --explain — 试运行会显示将使用哪个来源层级，以及跳过更早层级的原因，并在进行任何付费调用前预估费用。

  让 Agent 在确认之前预览费用和来源归属。进行任何付费操作前，请使用此功能。

  podcast-goat-pp-cli episode get https://www.hubermanlab.com/episode/example --explain
  

• episode quote — FTS5 短语搜索会返回匹配片段及其前后 N 个片段，同时保留规范的发言者格式和深度链接时间戳。

  5 秒内搜索你的播客记忆。记得某段引用的大致内容、需要找回原句时，请使用此功能。

  podcast-goat-pp-cli episode quote 'pricing power' -C 3 --json
  

• source compare — 对于可从多个来源解析的剧集，获取所有可用适配器的内容，并比较片段数、令牌数、不同发言者数量和标签置信度。

  揭示免费来源是否足够，还是需要付费来源。推荐上游来源前，请使用此功能。

  podcast-goat-pp-cli source compare https://www.acquired.fm/episodes/vanguard --json
  

• speakers list — 汇总缓存语料库中的发言者姓名及其剧集数量，也可以按节目筛选。

  回答“我有哪些关于 Senra/Buffett/Karpathy 的内容”。构建综合分析提示词时，请使用此功能。

  podcast-goat-pp-cli speakers list --show acquired --json
  

多语言覆盖

• episode get --lang — 获取 yt-dlp 支持的任意单一语言的 YouTube 自动字幕（每次获取一种语言）；默认仍为 en。

  非英语节目也有字幕。若不使用 --lang，只有意大利语的视频即使存在字幕也会获取失败。按设计有两项限制：滚动字幕去重仅适用于以空格分词的语言（像 zh/ja/th 这样不带空格的字幕会原样保留，不会合并），且非默认语言的获取结果不会写入本地缓存（v0.1 中缓存按 URL 标识，不区分语言——请使用 --out 保存这些字幕）。

  podcast-goat-pp-cli episode get 'https://www.youtube.com/watch?v=EXAMPLE' --lang it
  

面向 Agent 的基础功能

• episode info --probe — 免费检查可用性：查询 spoken.md 的搜索端点，确认是否确实有该集，而非只显示静态费用估算。

  费用估算说明获取内容的成本，但无法确认来源是否有该集。付费前先探测——使用演示密钥即可运行。

  podcast-goat-pp-cli episode info <url> --paid --probe --json
  

• auth services — 每项服务一行，显示 Cookie 年限、到期时间、上次获取结果；若已过期，还会提供修复提示。

  Cookie 会在不知不觉中过期。批量运行前先查看此处，确认会员访问权限仍然有效。

  podcast-goat-pp-cli auth services --json
  

• budget show --by-show — 将 spend.jsonl 按 URL 与 episodes 关联，并按节目、提供商和月份汇总费用归属。

  查看哪些订阅物有所值，哪些节目仍需付费。建议每月查看一次。

  podcast-goat-pp-cli budget show --by-show --since 30 --json
  

命令参考

episode — 获取、搜索和查看播客单集字幕

• podcast-goat-pp-cli episode get — 通过 Cookie → 免费 → 付费的分发链，按 URL 获取一份字幕
• podcast-goat-pp-cli episode latest — 获取已订阅节目源的最新单集

查找合适的命令

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

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

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

使用示例

Hermes / Claude / Agent 工作流

以下三个示例涵盖了此 CLI 为之打造的端到端 Agent 工作流。根据用户的表述进行模式匹配——每个示例末尾的触发语句，都是 Agent 应选择此示例而非手动获取字幕时可能遇到的自然语言表达。

周一早晨批量获取 → 主题合集 → Agent 摘要

# One-time setup (if not already done):
podcast-goat-pp-cli auth set-key --provider spoken --value "$SPOKEN_API_KEY"
podcast-goat-pp-cli auth login-service --service spotify    # if user has Spotify Premium

# The actual workflow:
podcast-goat-pp-cli episode batch \
  https://www.dwarkesh.com/p/andrej-karpathy \
  https://open.spotify.com/episode/<id> \
  https://www.acquired.fm/episodes/<slug> \
  --json

podcast-goat-pp-cli magic "AI chip supply chain" --limit 5 --out /tmp/bundle.md
# Then: ask the user's preferred LLM to summarize /tmp/bundle.md

并行获取多集（默认同时 3 集），缓存每一集，然后将符合主题的缓存单集汇总到一个带 YAML front matter 的 Markdown 文件中，可供 Agent 一次性生成摘要。合集中的每集都包含 source、show、host、date、provider、cost，以便生成摘要的 Agent 将观点归属到正确的单集。

触发语句：“获取这些播客单集”、“总结一下我本周听的内容”、“围绕 创建合集”、“把最新一期 做成提示词”、“周一早晨获取播客”。

对 说了什么？——本地引文搜索

podcast-goat-pp-cli episode quote "<phrase>" -C 3 --json \
  --select 'results.episode_url,results.segments'

在本地缓存语料库中使用 FTS5 进行短语搜索。返回匹配片段及其前后 N 个带说话者标签的片段。每条命中结果都包含 episode_url + ts_sec，方便 Agent 将用户直接引至对应时间点。在重新获取字幕前务必先使用此功能——如果用户已缓存该集，查询无需付费。

触发语句：“Senra 对 说了什么”、“找一下那段关于 的引文”、“ 有没有谈到 ”、“在我的播客缓存中搜索 ”。

付费获取前进行成本感知探索

# Step 1: preview — no transcript fetch, no spend, no commitment
podcast-goat-pp-cli episode info <url> --paid

# Step 1b: coverage check — does spoken.md actually HAVE this episode?
# Spend-free (search endpoint only; works with the demo key).
podcast-goat-pp-cli episode info <url> --paid --probe

# Step 2: only after preview confirms the URL + cost are right:
podcast-goat-pp-cli episode get <url> --paid --provider spoken --yes

episode info 会显示哪些适配器可以获取某个 URL、每个来源的预估成本、该节目是否已缓存，以及默认会调用哪个来源。每当用户粘贴你之前没见过的 URL 时，都应使用此命令，尤其是在花费付费额度之前。JSON 输出便于直接解析成本和来源决策。若要确认是否可用，而不只是了解成本，请添加 --probe：静态估算会显示获取 spoken.md 内容的费用，而 --probe 会询问 spoken.md 的搜索端点，确认该节目是否存在（probe: available (<title>) 与 probe: no results），因此无需尝试任何付费获取，就能梳理整个订阅源的覆盖情况。

触发短语：“这个 URL 的费用是多少”“这期节目已经缓存了吗”“获取前预览一下费用”“哪些来源能获取这个内容”“spoken 上有这期节目吗”。

其他实用示例

获取单期 Dwarkesh 文字稿

podcast-goat-pp-cli episode get https://www.dwarkesh.com/p/andrej-karpathy --md --out karpathy.md

免费，无需身份验证。提供带有说话者标签和时间戳的规范 Markdown。将文件交给任何 Agent 即可。

对比同一期节目的免费与付费版本

podcast-goat-pp-cli source compare https://www.acquired.fm/episodes/vanguard --json

会并行调用所有符合 URL 模式的适配器；显示各来源的片段数、不同说话者数量和说话人分离质量。可用于决定高价值节目应采用哪个来源。

订阅价值报告

podcast-goat-pp-cli budget show --by-show --since 30

按节目 + 提供商 + 月份汇总 spend_log。显示哪些订阅节省了费用（Cookie 命中费用为 $0，而获取同一节目的 spoken 内容则需要付费）。

反面示例——请勿这样做

• 不要在 shell 中循环调用 episode get。 请使用 episode batch——它会并行派发任务并显示进度；shell 循环则会顺序运行，且不提供进度反馈。
• 不要在无人看管的情况下重复获取同一 URL。 请先检查 cache list 或 episode info；已缓存的节目会立即返回。Agent 应始终知道自己是否即将重复处理。
• 不要对未知 URL 传入 --yes --paid。 请先运行 episode info <url> --paid 查看费用，再决定是否执行。简报明确将获取前预览费用列为不可妥协的用户体验要求。
• 不要忽略 --json 输出中的 meta.source 字段。 Agent 应始终能够追溯引文的来源；该字段就是审计记录。
• 不要将 SPOKEN_API_KEY（或任何付费密钥）写入用户可能提交的共享文件。 请使用 auth set-key——它会将密钥写入用户主目录中权限为 0600 的配置文件，而不是项目目录。

身份验证设置

按费用顺序分为三种身份验证方式。（1）auth login-service --service <huberman|acquired|founders|peterattia> 会提取你已登录的 Chrome Cookie，并在本地保存一次——这是主要工作流。（2）免费来源（Dwarkesh Substack、Podcasting 2.0 RSS 文字稿、yt-dlp 自动字幕）无需身份验证。（3）付费来源（spoken.md SPOKEN_API_KEY、Taddy TADDY_API_KEY+TADDY_USER_ID、ElevenLabs/OpenAI/Deepgram 等音频提供商）仅用于你通过 --paid 或 --provider <name> 明确选择的命令。spoken.md 的 pt_demo 密钥无需注册即可使用。

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

Agent 模式

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

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

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

  podcast-goat-pp-cli episode 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 是终端且未设置任何机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将易读的 N results (live) 摘要打印到 stderr；对于管道或 Agent 消费者，以及显式指定格式的运行，stdout 只会输出纯 JSON。

Agent 反馈

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

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

条目会存储在本地的 ~/.podcast-goat-pp-cli/feedback.jsonl。除非设置了 PODCAST_GOAT_FEEDBACK_ENDPOINT，并且传入 --send 或设置 PODCAST_GOAT_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”模式。

podcast-goat-pp-cli profile save briefing --json
podcast-goat-pp-cli --profile briefing episode get mock-value
podcast-goat-pp-cli profile list --json
podcast-goat-pp-cli profile show briefing
podcast-goat-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

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

claude mcp add podcast-goat-pp-mcp -- podcast-goat-pp-mcp

验证：claude mcp list

直接使用

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

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

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