pp-youtube

YouTube — Printing Press CLI

前置条件：安装 CLI

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

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

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

2. 验证：youtube-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/media-and-entertainment/youtube/cmd/youtube-pp-cli@latest

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

YouTube Data API v3 中与市场和竞品调研相关的只读功能，支持完整的参数配置，并将数据写入专为竞品监控设计的本地 SQLite 数据库：通过 watch 跟踪约 15 个竞品，通过 monitor 刷新数据，每次运行约消耗 20–40 个配额单位；再通过 velocity、growth、breakouts、comments-mine 和 packaging，将累积的快照转化为最新的市场情报。相比之下，滞后的分析平台往往要晚一到两周才能提供这些信息。

何时使用此 CLI

只要任务涉及 YouTube 市场或竞品调研，就可以使用此 CLI：持续跟踪一组固定竞品频道、衡量当前哪些内容正在获得播放量、在某个细分领域发现新兴爆款视频、挖掘评论以了解受众信号，或收集标题、缩略图和钩子用于包装分析。如果答案需要来自本地拥有且定期刷新的数据库，而不是滞后的外部分析平台，那么此工具就是合适的选择。

不适用场景

以下情况不要使用此 CLI：

• 不要将此 CLI 用于你自己频道的私有分析数据（收入、观众留存、人口统计、流量来源）——这些数据只能通过 OAuth 使用 YouTube Analytics API 获取，而此 CLI 有意不包含这项功能
• 不要用它上传、编辑、评价或删除视频，也不要用它管理频道——所有写入操作均不在支持范围内
• 不要用它下载视频或音频媒体——媒体文件请使用 yt-dlp
• 不要用它做跨细分领域异常值评分或变现估算等广泛市场分析判断——这些应由精选分析数据库负责；此 CLI 专注于你跟踪频道的最新数据

独特功能

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

竞品监控机器

• watch — 在你拥有的类型化监控列表表中，登记监控机器要追踪的竞品频道。

  只需定义一次要追踪的市场；之后每条监控命令都会针对这些频道运行，无需重新指定。

  youtube-pp-cli watch add @mkbhd --json
  

• monitor — 一次运行即可刷新所有监控频道：统计数据快照、新上传内容，以及近期视频统计数据的重新快照。

  一条命令即可保持数据库最新，让市场信息的时效从数周缩短到数小时。

  youtube-pp-cli monitor --json
  

• velocity — 查看当前观看量增长最快的追踪视频，数据根据真实的两次快照间差值计算。

  了解当前市场动态——看看今天哪些内容正在走红，而不是两周前走红的内容。

  youtube-pp-cli velocity --json
  

• growth — 查看频道级别的订阅者数、观看量和上传数量在不同日期的本地快照之间的变化。

  无需任何外部历史数据服务，即可让 Agent 判断竞品是否正在加速增长。

  youtube-pp-cli growth @mkbhd --json
  

• backfill — 一条命令即可将某个频道的完整上传历史及统计数据拉取到本地数据库。

  每个竞品只需运行一次；之后有关该频道的问题都可以离线免费解答。

  youtube-pp-cli backfill @mkbhd --json
  

• workspace — 命名数据库：在一个数据库中保留竞品监控机器，在另一个数据库中探索新领域，并可即时切换。

  让 Agent 能为每个领域创建独立的研究沙盒，同时避免影响生产用监控列表数据库。

  youtube-pp-cli workspace list --json
  

• auth keys — 存储多个命名的 YouTube API 密钥，即时切换密钥；还可在某个密钥的配额用尽时，通过 --rotate 选择自动故障转移。

  第一个密钥的每日配额用尽后，Agent 仍可在无需人工干预的情况下完成大型数据采集任务。

  youtube-pp-cli auth keys list --json
  

新鲜市场发现

• breakouts — 将搜索筛选条件组合成矩阵（搜索词 x 上传时间范围 x 时长 x 地区），将结果与频道规模关联，并按近期高热度视频排序。

  在上传数天后、滞后分析平台发现数周前，找到细分领域中的爆款。

  youtube-pp-cli breakouts "berlin history" --days 14 --json
  

• comments-mine — 将评论同步到类型化、支持全文搜索的表中，并汇报获赞最多的评论、关键词频率和观众问题。

  快速获取你拥有的数据中的观众反馈信号——了解观众在频道内容中称赞什么、提问什么和抱怨什么。

  youtube-pp-cli comments-mine @mkbhd --json
  

• packaging — 收集标题、缩略图（下载为本地图片文件）以及从转录开头提取的钩子文本，并存入包装信息表。

  为多模态 Agent 提供缩略图和钩子分析所需的一切，无需抓取数据或手动收集。

  youtube-pp-cli packaging @mkbhd --json
  

命令参考

youtube — YouTube Data API v3（只读，api-key），用于市场和竞争对手分析

• youtube-pp-cli youtube activities-list — 检索资源列表，可按条件筛选。
• youtube-pp-cli youtube captions-list — 检索资源列表，可按条件筛选。
• youtube-pp-cli youtube channel-sections-list — 检索资源列表，可按条件筛选。
• youtube-pp-cli youtube channels-list — 检索资源列表，可按条件筛选。
• youtube-pp-cli youtube comment-threads-list — 检索顶级评论串列表，可按视频、频道或评论串 ID 筛选。
• youtube-pp-cli youtube i18n-languages-list — 检索资源列表，可按条件筛选。
• youtube-pp-cli youtube i18n-regions-list — 检索资源列表，可按条件筛选。
• youtube-pp-cli youtube playlist-items-list — 检索资源列表，可按条件筛选。
• youtube-pp-cli youtube playlists-list — 检索资源列表，可按条件筛选。
• youtube-pp-cli youtube search-list — 检索搜索资源列表
• youtube-pp-cli youtube video-categories-list — 检索资源列表，可按条件筛选。
• youtube-pp-cli youtube videos-list — 检索资源列表，可按条件筛选。
• youtube-pp-cli youtube channel-uploads — 列出频道最近上传的视频（解析 @handle 或 channelId，然后遍历上传播放列表）。
• youtube-pp-cli youtube playlist-enrich — 一次并发调用，将播放列表解析为逐视频元数据、字幕稿和描述。
• youtube-pp-cli youtube search-bulk — 一次调用搜索多个 YouTube 词条，并返回每个词条排名靠前的 N 条结果。
• youtube-pp-cli youtube videos-comments — 分页获取视频热门评论，并按点赞数排序。
• youtube-pp-cli youtube videos-embed — 输出视频的嵌入 HTML、iframe 或 Markdown 片段。
• youtube-pp-cli youtube videos-enrich — 一次调用获取单个视频的元数据、字幕稿和描述。
• youtube-pp-cli youtube videos-links — 从视频描述中提取资源链接（展开短链接，跳过社交媒体杂项）。
• youtube-pp-cli youtube videos-related — 查找相关视频，共享主题的排名高于同频道视频。
• youtube-pp-cli youtube videos-transcript — 无需 OAuth 获取字幕稿（timedtext；--format markdown|text|json）。

查找合适的命令

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

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

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

操作示例

搭建监控机器

youtube-pp-cli watch add @mkbhd --json

每个竞争对手只需添加一次；回填操作会播种历史数据，每次监控运行都会更新数据

今日动态

youtube-pp-cli velocity --agent --select items.title,items.views_per_day

查看受跟踪视频在两次快照之间的播放速度变化，并缩小到 Agent 所需的字段

细分领域的新爆款

youtube-pp-cli breakouts "berlin history" --days 14 --json

将链式筛选矩阵与频道规模关联起来，找出过去两周发布且播放量／订阅者数较高的视频

为 Agent 准备的包装资料

youtube-pp-cli packaging @mkbhd --json

并排列出标题、本地缩略图文件和吸引点文本，便于进行多模态包装分析

观众反复提出的问题

youtube-pp-cli comments-mine @mkbhd --json

从已同步的评论表中提取点赞数最高的评论、关键词频率和问题

身份验证设置

将 YOUTUBE_API_KEY 设为 YouTube Data API v3 密钥（可在 console.cloud.google.com 的 APIs & Services > Credentials 下创建），或使用 auth set-token 保存一次。环境变量中的密钥优先于已保存的密钥——如果 doctor 显示 auth_source env，但调用因 HTTP 400 'API key not valid' 而失败，说明环境变量中的副本已过期：请取消设置或更新它。仅限只读公开数据操作；完全不使用 OAuth。

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

Agent 模式

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

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

• 可筛选 — --select 保留一部分字段。点分路径可深入嵌套结构；数组会逐元素遍历。对于输出冗长的 API，这是保持上下文精简的关键：

  youtube-pp-cli youtube activities-list --part snippet --agent --select contentDetails,etag,id
  

• 可预览 — --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 应将 CLI 的路径解析器视为运行时契约的一部分：

• 单次调用使用 --home <dir>，或设置 YOUTUBE_HOME=<dir>，将四种路径都重定位到同一个根目录下。

• 只有在特定路径类型必须单独设置时，才使用对应的环境变量：YOUTUBE_CONFIG_DIR、YOUTUBE_DATA_DIR、YOUTUBE_STATE_DIR、YOUTUBE_CACHE_DIR。

• 解析顺序为：对应路径类型的环境变量、--home、YOUTUBE_HOME、XDG（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME、XDG_CACHE_HOME），然后是平台默认值。

• config 包含 config.toml 和配置档案等设置。data 包含 credentials.toml、data.db、Cookie 和认证辅助文件。state 包含持久化查询、任务和 teach.log。cache 包含可重新生成的 HTTP／缓存文件。

• 已存储的密钥位于 data 目录下的 credentials.toml 中。为兼容性，系统会读取现有的旧版 config.toml 密钥；首次写入认证信息时，会将密钥移出 config.toml。

• 运行 youtube-pp-cli doctor --fail-on warn，以显示路径和凭据位置警告。对于需要解析后目录路径的 Agent，agent-context 会提供 schema v4 的 paths 区块。

• 对于 MCP，请通过 MCP 主机配置传递重定位设置。MCP 二进制程序不会继承 CLI 标志：

  {
    "mcpServers": {
      "youtube": {
        "command": "youtube-pp-mcp",
        "env": {
          "YOUTUBE_HOME": "/srv/youtube"
        }
      }
    }
  }
  

⚠️ 有两个文件有意存放在可重定位目录树之外，即平台配置目录中（macOS 上为 ~/Library/Application Support/youtube-pp-cli/）：workspaces.json（工作区注册表必须位于工作区主目录之外，否则切换会变成自我引用）和 keyring.json（配额按密钥计算，而非按工作区计算）。因此，--home／YOUTUBE_HOME 不会隔离密钥环或工作区注册表——即使在隔离的主目录下，keys add/use 和 workspace create/use 也会修改共享状态。

多节点环境中的优先级：继承的对应路径类型环境变量会覆盖显式指定的 --home。使用 YOUTUBE_HOME 或对应路径类型的环境变量作为持久的多节点配置手段；仅在单次调用时使用 --home。取消设置环境变量并不能撤销重定位；清除 YOUTUBE_HOME 前，请手动移动文件，否则 doctor 将找不到留在原根目录下的凭据。

分析师数据库（SQL 架构）

每条分析师命令都会写入一个本地 SQLite 数据库——doctor --json 报告的存储路径即为该文件。文件名按当前 API key 区分（data-<hash>.db）；workspace 会在完全独立的数据库文件之间切换。Agent 通过两种方式查询：MCP sql 工具（只读、经过验证）以及 MCP search / CLI search 全文搜索接口。

表	每行对应	关键列
yt_watchlist	已跟踪的竞争对手频道	channel_id、handle、title、note、added_at、last_monitored_at
yt_channel_snapshots	某频道在一次采集时的数据	channel_id、captured_at、subscriber_count、view_count、video_count
yt_videos	已知视频（维度表）	video_id、channel_id、title、published_at、duration_seconds、is_short、description
yt_video_snapshots	某视频在一次采集时的数据	video_id、captured_at、view_count、like_count、comment_count
yt_comments	已同步评论	comment_id、video_id、channel_id、author、text、like_count、published_at、is_reply
yt_comments_fts	针对 yt_comments.text 的 FTS5 索引	MATCH 查询；通过插入/更新/删除触发器保持同步
yt_packaging	已采集的包装素材	video_id、channel_id、title、thumb_url、thumb_path、hook_text、view_count、captured_at、hook_error、thumb_error
yt_monitor_runs	一次 monitor 运行	run_id、started_at、finished_at、channels、new_videos、video_snapshots、comments_synced、quota_units_est

monitor、backfill、breakouts、comments-mine 和 packaging 会自动写入这些表（写入即生效）；velocity 和 growth 根据连续的 yt_video_snapshots / yt_channel_snapshots 行计算——至少需要在不同日期运行两次，才能得到非空结果。

示例查询（均已在有实时数据的存储中验证）：

-- What moved: views per video from the latest snapshots
SELECT s.video_id, v.title, s.view_count, s.captured_at
FROM yt_video_snapshots s JOIN yt_videos v USING(video_id)
ORDER BY s.captured_at DESC, s.view_count DESC LIMIT 20;

-- Audience signal: most-liked comments mentioning a topic (FTS5)
SELECT c.like_count, c.author, c.text
FROM yt_comments_fts f JOIN yt_comments c ON c.rowid = f.rowid
WHERE yt_comments_fts MATCH 'gemini' ORDER BY c.like_count DESC LIMIT 10;

-- Growth rate per tracked channel between first and last snapshot
SELECT channel_id,
       MAX(subscriber_count) - MIN(subscriber_count) AS subs_delta,
       MIN(captured_at) AS first_seen, MAX(captured_at) AS last_seen
FROM yt_channel_snapshots GROUP BY channel_id;

自动学习

此 CLI 内置自动捕获的学习循环。CLI 会自行记录：每次调用都会在本地写入日志；失败标记后再经修正重试，会自动生成一个 flag_alias 候选项；如果某个查询类别没有操作手册，对该类别执行 teach 会根据会话日志自动合成一个 playbook_candidate。你只需做判断：先执行 recall，根据显示的候选项采取行动，再用 teach 记录最终答案；发现修正时执行 playbook amend。你不必手动记录失败。

第 1 步：任何探索前先执行 recall

针对新的用户问题，在执行 list/search/drill 命令前，先运行：

youtube-pp-cli recall "<user's question>" --agent

响应结构：

{
  "query": "...",
  "normalized": "<normalized form>",
  "query_entities": ["..."],
  "found": true | false,
  "match_score": 0.0,
  "results": [
    { "resource_id": "...", "resource_type": "...", "venue": "...",
      "confidence": 2, "entity_match": "exact|partial|unknown",
      "source": "taught|preseed|pattern", "warnings": ["..."] }
  ],
  "mismatches": [ /* only when --debug-mismatches */ ],
  "warnings": [ /* top-level */ ],
  "candidates": [
    { "id": 12, "class": "flag_alias | playbook_candidate",
      "summary": "...", "sightings": 3, "last_seen": "...",
      "rationale": "...",
      "next_action": ["<trial command>", "youtube-pp-cli learnings confirm 12"] }
  ],
  "playbook": {
    "query_family": "...",
    "playbook": {
      "steps": [ { "cmd": "<command with {slot} substitution>", "purpose": "..." } ],
      "entity_slots": ["$ENTITY"],
      "expected_tool_calls": 3
    },
    "slots_resolved": { "$ENTITY": { "token": "<live token>", "canonical": "<canonical>" } },
    "notes": "<workarounds + gotchas for this query family>"
  },
  "notes": "<duplicate surface for non-playbook callers>"
}

空存储快速跳过：如果存储中还没有学习记录、操作手册或候选项（recall 没有结果，且 learnings list 和 learnings candidates 都为空），则本次会话后续不再执行 recall，避免每次查询都产生开销；一旦有内容通过 teach 记录，就恢复先执行 recall 的流程。

第 2 步：决策树

按以下顺序查看 candidates、playbook、notes、results[0] 和警告：

if Candidates present (warnings include "candidates_present"):
    -> candidates are try-then-confirm, never facts. Follow each candidate's
       two-step next_action verbatim: run the trial command first, then run
       `learnings confirm <id>` only after the trial verified the behavior.
       Reject a wrong candidate with `learnings reject <id>`.
    -> NEVER re-teach something recall surfaced as a candidate; confirm or
       reject that candidate instead of teaching a duplicate.
    -> candidates ride alongside playbooks and resource hits, not instead of
       them; continue with the branches below after acting on them.

if Playbook present:
    -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose)
    -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries
       for the entity slot tokens. If a step's slot is unresolved, fall back to
       discovery for that step only.
    -> the Playbook's expected_tool_calls is a budget; if you find yourself running
       materially more, record the divergence via `youtube-pp-cli playbook amend`
       at end-of-session.

elif Notes present (no Playbook):
    -> read Notes verbatim before any discovery step; they carry known gotchas
       for this query family even when no structured choreography exists yet.

elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2:
    -> skip discovery; fetch live data for Results[*].ResourceID in parallel

elif Found AND Results[0].EntityMatch == "partial":
    -> candidate hint, NOT a hit; read the resource title to validate before trusting

elif (any row in Mismatches[] when --debug-mismatches was passed):
    -> treat as cold start; the stored learning is for a different entity
       (different canonical resolved from query_entities)

else:  // Found == false, no playbook, no notes
    -> cold start; run discovery normally; teach the answer afterward (Step 4).
       If the family has no playbook yet, that teach auto-synthesizes a
       playbook candidate from this session's journal - you do not need to
       record one by hand.

Playbook 和 Notes 与针对单个资源的处理路径彼此独立。一次 recall 响应可能同时包含 Playbook 和 Results[] 命中项——两者都要使用：Playbook 会告诉你要按什么流程操作；资源命中项则可以跳过特定步骤。默认跳过 mismatches；只有在调查冷启动意外情况时才传入 --debug-mismatches。

候选项判断详情：learnings confirm <id> 会在创建候选项前打印其完整负载——请确认打印出的负载与已验证的行为一致。learnings reject <id> 会将推导签名标记为已废弃，避免同一候选项再次出现。响应结构只包含当前值得采取行动的少数候选项；youtube-pp-cli learnings candidates 会列出所有尚未处理的候选项。

平滑降级：如果 learnings confirm 被识别为未知命令，说明你使用的是较旧版本的二进制文件——忽略候选项相关说明，继续遵循协议的其余部分。

步骤 3：始终读取 warnings

• low_confidence：存在 confidence<2 的行。将其视为提示，而非跳过发现的命中项。
• resource_not_in_store：本地存储中没有学习记录所指向的资源。匹配验证器无法对实体进行分类——直接获取资源并重新评估。
• cross_alias_match（针对单条结果）：该行是在另一个别名下学习的，并通过 entity_lookups 与实时查询的规范实体匹配（例如，针对「United States」的回忆命中了针对「USA」的学习记录）。信任 resource_id。
• similar_shape_different_entity:<canonical>（顶层）：存在结构匹配的行，但其规范实体与实时查询的不同。按冷启动处理；此警告会提供冲突规范实体作为提示，但该行不会被提升到 Results 中。
• ambiguous_alias（顶层）：单个查询实体解析出了多个规范实体（例如，「Cards」→ Arizona Cardinals + St. Louis Cardinals）。在确定资源之前，根据上下文指出歧义。
• candidates_present（顶层）：信封中包含 candidates 部分。先按照步骤 2 中的候选分支处理，再进行其他操作。
• lookup_refresh_available（顶层）：查询中的某个实体尚无查找行，但同步数据可能会提供一条。运行 youtube-pp-cli sync 以刷新实体查找。
• 顶层 no_learnings_for_query_family：表中没有 Jaccard 值高于下限的行。纯粹的冷启动。

步骤 4：完成回复后始终执行 teach &

无条件进行教学。解决存储无法回答的查询后，在后台记录最终资源映射——不设调用次数门槛，也不评判是否「值得」学习。教学是整个循环的锚点：对于尚无操作手册的族，它会触发操作手册合成；同一指代对象的不同表述会归入同一个族，因此近似重复的教学不会将存储拆分成多个部分。在整理好面向用户的回复后、发送回复前执行，并在末尾加上 shell &，使调用立即返回：

youtube-pp-cli teach --query "<user's question>" --resource-type <type> --resource <id1> --resource <id2>
# (append shell `&` to background it)

成功时不输出任何信息。错误仅会写入已解析状态目录下的 teach.log。教学时使用最具体的资源——如果用户提出宽泛问题，而你通过检查父记录找到了具体答案，则教学时使用叶节点 ID，而不是父节点。CLI 会在回忆时使用预置的 entity_lookups 进行跨别名解析，因此在一个别名下进行的教学（例如，「Niners」）会自动满足未来使用其他别名（例如，「49ers」、「San Francisco」）的查询。

PII 规则：教学时保留结构性问题，并移除标识符——切勿在教学查询或备注中包含姓名、电子邮件、电话号码、账户 ID 或其他个人标识符。CLI 会扫描教学查询中明显的电子邮件或电话号码格式并发出警告，但不会阻止；应在教学前移除这些信息，而不要依赖警告。

步骤 5：playbooks——可选标志、自动综合

你不需要判断某个会话是否“值得”编写 playbook：如果某个会话教授的功能族尚无 playbook，系统会根据该会话的日志自动综合出一个 playbook_candidate，并由下一个会话通过确认或拒绝来评估它。只有在你已经掌握值得逐字记录的操作流程时，才添加明确的 playbook 标志——例如 CLI 未显示的变通方法（被静默丢弃的标志、未记录的参数、分页技巧、负载陷阱）。优先使用集成式单次调用形式——在同一次 teach 调用中记录资源学习内容和 playbook：

# Common case: record both the resource learning AND the playbook in one call.
youtube-pp-cli teach \
  --query "<user's question>" \
  --resource <id> \
  --playbook-file ~/playbooks/<shape>.json \
  --playbook-notes-file ~/playbooks/<shape>-notes.md
# (append shell `&` to background it)

# Alternate: playbook-only (no resource to record alongside).
youtube-pp-cli teach-playbook \
  --query "<user's question>" \
  --playbook-file ~/playbooks/<shape>.json \
  --notes-file ~/playbooks/<shape>-notes.md

Playbook 文件为 JSON，包含 steps、entity_slots、expected_tool_calls。Notes 文件为 markdown，原样记录各种陷阱。仅使用文件的调用方（仅使用 MCP 的 Agent）可将相同内容内联传入：在集成式 teach 形式中使用 --playbook-json 和 --playbook-notes，在 teach-playbook 中使用 --playbook-json 和 --notes。在集成式 teach 形式中，playbook 标志是可选的——如果只教授资源，可完全省略这些标志。在独立的 teach-playbook 形式中，必须至少设置 playbook 或 notes 标志之一；两者均为空时会被拒绝。Playbook 根据结构化查询族（去除实体）建立索引，因此，从一个实体形状的查询教授的操作方案适用于所有其他形状相同的查询，而 slots_resolved 会在调用时绑定当前查询的规范形式。

如果你在后续查询中确实找到了 playbook，请将其视为事实依据：使用 slots_resolved 替换项重放步骤，跳过操作流程中已记录的探索步骤，并在执行任何步骤前阅读 notes。

步骤 6：当调试响应指出需要更正时，使用 playbook amend &

如果你的调试协议响应指出了 notes 或 playbook 应记录的一项具体更正——例如变通方法、未记录的端点格式、过时的字段名、观察到的架构漂移或空负载回退方案——请在输出面向用户的响应前执行 playbook amend。其执行方式与 teach 相同，均为触发后即继续。

youtube-pp-cli playbook amend \
  --query "<exact recall query string>" \
  --add-note "<your concrete correction>"
# (append shell `&` to background it)

值得修订的内容：本次会话中你观察到的、未来的自己会受益的行为。值得修订的示例：

• 针对会静默丢弃或重新排列标志的 CLI 界面的变通方法。
• 未记录的端点格式（响应包装在 {meta, results} 中，负载嵌套层级比文档所述多两层）。
• 观察到的架构漂移（字段重命名、索引在不同赛季间发生变化、API 现在返回小写类别标签）。

以下内容不应写入 notes：

• 用户问题中与年份或实体相关的答案。这属于响应，而非学习内容。
• Playbook 已在运行时检索的每队、每位运动员或每行数据。
• 复述现有 notes 内容的陈述。

amend 命令会将内容追加到该功能族现有的 notes 中，并附带带时间戳的标记（[amend YYYY-MM-DDTHH:MMZ]: <text>）。多次修订会累积保留；审计记录清晰可见。如果该功能族尚无 playbook，amend 会创建一个仅含 notes 的 playbook（因此，冷启动时发现的更正也会被记录下来）。

amend notes 的 PII 规范

playbook amend notes 可能会在 Printing Press 的未来版本中作为共享知识上传。请勿在其中包含可识别用户身份的信息，以免影响上游贡献渠道的开放性，并避免日后清理：

• 不得嵌入用户文件系统路径、个人 API 密钥或令牌、用户电子邮件地址、用户 GitHub 账号，或与单个用户关联的特定查询历史。
• 可以包含：端点格式、未记录的字段名、API 陷阱、观察到的架构漂移、CLI 界面的变通方法、可通用的分页或重试技巧。

如果某项更正只有结合用户专属背景才有意义，应将其写入个人笔记，而不是 playbook amend。

衡量闭环

youtube-pp-cli learnings stats 会根据本地 learn_events 表，报告召回命中率、教学复用率、操作手册解决率，以及候选项确认／拒绝次数。尚无分母时，相关比率为 null；所有数据都留在本机。用它来检查这个 CLI 是否值得建立这样的闭环。

禁用学习

• 单条命令使用 --no-learn，会同时短路 recall 和 teach 写入路径。适用于必须不受累积学习内容影响的确定性 Agent 流程或测试。
• 在环境中设置 YOUTUBE_NO_LEARN=true，可全局禁用该流程。

Agent 反馈

当你（或 Agent）发现这个 CLI 有不对劲的地方时，请记录下来：

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

条目会以 feedback.jsonl 的形式存储在解析后的数据目录中。除非设置了 YOUTUBE_FEEDBACK_ENDPOINT，并且传入 --send 或设置 YOUTUBE_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 每次都使用相同的已保存标志，但输入不同，就适合使用配置文件。

youtube-pp-cli profile save briefing --json
youtube-pp-cli --profile briefing youtube activities-list --part snippet
youtube-pp-cli profile list --json
youtube-pp-cli profile show briefing
youtube-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 youtube-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/youtube/cmd/youtube-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add youtube-pp-mcp -- youtube-pp-mcp
   

3. 验证：claude mcp list

直接使用

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

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

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