pp-beehiiv

Beehiiv — Printing Press CLI

前置条件：安装 CLI

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

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

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

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

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

Beehiiv-pp-cli 会将 publications、订阅者、细分群体、帖子、播客等数据镜像到 SQLite 中。洞察命令可计算来源归因、退订来源、发送时间表现和跨 publication 对比，且无需调用 API。完整的 v2 功能（包括 2026-09 新增的播客、导出和免费访问）均以带有 dry-run 和 Agent 输出功能的类型化命令提供。

何时使用此 CLI

可使用此 CLI 进行离线受众分析、批量订阅者操作、脚本编写和 CI 流水线。在需要适用于 Agent 的 JSON 输出（支持 select/compact/quiet 模式），以及能在无需调用 API 的情况下回答增长问题的本地存储时，使用此 CLI。

不适用场景

请勿在以下场景使用此 CLI：

• 请勿使用此 CLI 搜索 beehiiv 文档；请改用官方文档 MCP：developers.beehiiv.com/_mcp/server
• 请勿使用此 CLI 处理 OAuth 应用授权流程；它是 API 密钥客户端
• 创建状态已确认且未设置 scheduled_at 的帖子会立即发布（发送）；请先使用 --dry-run 检查请求

独特功能

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

从本地存储获取增长洞察

• insights subscriber-sources — 精确查看新订阅者的来源：UTM、渠道和引荐网站，一次调用即可汇总。

  需要在增长问题中了解来源归因，又不想通过 API 翻查完整订阅者列表时，可使用此命令。

  beehiiv-pp-cli insights subscriber-sources pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --limit 20 --agent
  

• insights post-performance — 在一张精简表格中查看近期发送的状态、时间和详细统计数据。

  发送后如需查看表现，又不想消耗逐帖 API 调用额度，可使用此命令。

  beehiiv-pp-cli insights post-performance pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --limit 10 --agent
  

• insights referral-health — 检查推荐计划配置，以及实际持有推荐代码的订阅者数量。

  调整推荐循环时，可使用此命令了解配置与实际覆盖情况。

  beehiiv-pp-cli insights referral-health pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --agent
  

• insights subscriber-lookup — 按电子邮件或订阅 ID 查找单个订阅者，并立即获取精简记录。

  需要快速离线回答有关单个订阅者的支持问题时，可使用此命令。

  beehiiv-pp-cli insights subscriber-lookup pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 [email protected] --agent --select subscription.email,subscription.status
  

• insights churn-sources — 查看导致用户退订的来源、渠道和营销活动。

  退订量激增且需要快速找到问题渠道时，可使用此命令。

  beehiiv-pp-cli insights churn-sources pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --limit 20 --agent
  

• insights send-times — 根据历史数据，按星期和小时查找最佳发送时段及打开率。

  安排下一次发送且希望依据数据而非习惯时，可使用此命令。

  beehiiv-pp-cli insights send-times pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --agent
  

• insights compare-publications — 并排比较所有已同步 publication 的增长和互动情况。

  管理多个 publication，且客户报告需要一张对比表时，可使用此命令。

  beehiiv-pp-cli insights compare-publications --agent --select publications.name,publications.net_growth
  

命令参考

advertisement-opportunities — 管理广告机会

• beehiiv-pp-cli advertisement-opportunities <publicationId> — 获取广告机会 OAuth Scope: posts:read

authors — 管理作者

• beehiiv-pp-cli authors index — 获取该出版物可用的作者列表。
• beehiiv-pp-cli authors show — 获取该出版物中的单个作者。

automations — 管理自动化

• beehiiv-pp-cli automations index — 列出自动化 OAuth Scope: automations:read
• beehiiv-pp-cli automations show — 获取自动化 OAuth Scope: automations:read

bulk-subscription-updates — 管理批量订阅更新

• beehiiv-pp-cli bulk-subscription-updates index — 列出订阅更新 OAuth Scope: subscriptions:read
• beehiiv-pp-cli bulk-subscription-updates show — 获取订阅更新 OAuth Scope: subscriptions:read

bulk-subscriptions — 管理批量订阅

• beehiiv-pp-cli bulk-subscriptions <publicationId> — 批量创建订阅 OAuth Scope: subscriptions:write

complimentary-access — 管理免费访问权限

• beehiiv-pp-cli complimentary-access index — 获取该出版物的免费访问权限对象。
• beehiiv-pp-cli complimentary-access show — 获取单个免费访问权限对象。

condition-sets — 管理条件集

• beehiiv-pp-cli condition-sets index — 获取某个出版物的所有有效条件集。
• beehiiv-pp-cli condition-sets show — 获取某个出版物的单个有效动态内容条件集。

custom-fields — 管理自定义字段

• beehiiv-pp-cli custom-fields create — 创建自定义字段 OAuth Scope: custom_fields:write
• beehiiv-pp-cli custom-fields delete — 删除自定义字段 OAuth Scope: custom_fields:write
• beehiiv-pp-cli custom-fields index — 列出自定义字段 OAuth Scope: custom_fields:read
• beehiiv-pp-cli custom-fields patch — 更新自定义字段 OAuth Scope: custom_fields:write
• beehiiv-pp-cli custom-fields put — 更新自定义字段 OAuth Scope: custom_fields:write
• beehiiv-pp-cli custom-fields show — 获取自定义字段 OAuth Scope: custom_fields:read

data-privacy — 管理数据隐私

• beehiiv-pp-cli data-privacy data-deletion-create — 此功能需要启用后才能使用。
• beehiiv-pp-cli data-privacy data-deletion-index — 此功能需要启用后才能使用。
• beehiiv-pp-cli data-privacy data-deletion-show — 此功能需要启用后才能使用。

email-blasts — 管理邮件群发

• beehiiv-pp-cli email-blasts index — 列出邮件群发 OAuth Scope: posts:read
• beehiiv-pp-cli email-blasts show — 获取邮件群发 OAuth Scope: posts:read

engagements — 管理互动数据

• beehiiv-pp-cli engagements <publicationId> — 获取指定出版物在设定日期范围和粒度内的邮件互动指标。

exports — 管理导出

• beehiiv-pp-cli exports subscription-create — 开始导出订阅数据。如果已有正在进行的导出，则返回该导出，而不是重复启动。
• beehiiv-pp-cli exports subscription-index — 按时间从新到旧列出该出版物的订阅导出。
• beehiiv-pp-cli exports subscription-show — 获取订阅导出。轮询直到状态为 completed，然后读取 download_url。此功能需要启用后才能使用。

newsletter-lists — 管理新闻通讯列表

• beehiiv-pp-cli newsletter-lists index — Newsletter Lists 目前处于 Beta 阶段，API 可能会发生变化。
• beehiiv-pp-cli newsletter-lists show — Newsletter Lists 目前处于 Beta 阶段，API 可能会发生变化。

podcasts — 管理播客

• beehiiv-pp-cli podcasts index — 列出出版物的播客。
• beehiiv-pp-cli podcasts show — 获取单个播客。

polls — 管理投票

• beehiiv-pp-cli polls index — 获取特定出版物的所有投票。始终包含投票选项。
• beehiiv-pp-cli polls show — 获取出版物中特定投票的详细信息。

post-templates — 管理文章模板

• beehiiv-pp-cli post-templates <publicationId> — 获取该出版物可用的文章模板列表。

posts — 管理文章

• beehiiv-pp-cli posts aggregate-stats — 获取汇总统计数据 OAuth Scope: posts:read
• beehiiv-pp-cli posts create — 此功能目前处于 Beta 阶段，API 可能会发生变化
• beehiiv-pp-cli posts delete — 删除或归档文章。任何已确认的文章，其状态都会更改为 archived。
• beehiiv-pp-cli posts index — 列出文章 OAuth Scope: posts:read
• beehiiv-pp-cli posts show — 获取文章 OAuth Scope: posts:read
• beehiiv-pp-cli posts update — 此功能目前处于 Beta 阶段，API 可能会发生变化

publications — 管理出版物

• beehiiv-pp-cli publications index — 列出出版物 OAuth Scope: publications:read
• beehiiv-pp-cli publications show — 获取出版物 OAuth Scope: publications:read

referral-program — 管理推荐计划

• beehiiv-pp-cli referral-program <publicationId> — 获取推荐计划 OAuth Scope: referral_program:read

segments — 管理细分群组

• beehiiv-pp-cli segments create — 创建新的细分群组。
• beehiiv-pp-cli segments delete — 删除细分群组。删除细分群组不会影响其中的订阅。
• beehiiv-pp-cli segments index — 列出细分群组 OAuth Scope: segments:read
• beehiiv-pp-cli segments show — 获取细分群组 OAuth Scope: segments:read

subscriptions — 管理订阅

• beehiiv-pp-cli subscriptions bulk-updates-patch — 更新订阅 OAuth Scope: subscriptions:write
• beehiiv-pp-cli subscriptions bulk-updates-patch-status — 更新订阅状态 OAuth Scope: subscriptions:write
• beehiiv-pp-cli subscriptions bulk-updates-put — 更新订阅 OAuth Scope: subscriptions:write
• beehiiv-pp-cli subscriptions bulk-updates-put-status — 更新订阅状态 OAuth Scope: subscriptions:write
• beehiiv-pp-cli subscriptions create — 创建订阅 OAuth Scope: subscriptions:write
• beehiiv-pp-cli subscriptions delete — 此操作无法撤销。与该订阅相关的所有数据也将被删除。
• beehiiv-pp-cli subscriptions get-by-email — 请注意，此端点要求对电子邮件地址进行 URL 编码。
• beehiiv-pp-cli subscriptions get-by-id — 在该 API 的早期版本中，曾有另一个端点用于通过订阅者 ID 检索订阅。
• beehiiv-pp-cli subscriptions get-by-subscriber-id — 通过订阅者 ID 获取订阅 OAuth Scope: subscriptions:read
• beehiiv-pp-cli subscriptions index — 检索特定出版物的所有订阅。
• beehiiv-pp-cli subscriptions patch — 通过 ID 更新订阅 OAuth Scope: subscriptions:write
• beehiiv-pp-cli subscriptions put — 通过 ID 更新订阅 OAuth Scope: subscriptions:write
• beehiiv-pp-cli subscriptions update-by-email — 通过电子邮件地址更新订阅 OAuth Scope: subscriptions:write

tiers — 管理等级

• beehiiv-pp-cli tiers create — 创建等级 OAuth Scope: tiers:write
• beehiiv-pp-cli tiers index — 列出等级 OAuth Scope: tiers:read
• beehiiv-pp-cli tiers patch — 更新等级 OAuth Scope: tiers:write
• beehiiv-pp-cli tiers put — 更新等级 OAuth Scope: tiers:write
• beehiiv-pp-cli tiers show — 获取等级 OAuth Scope: tiers:read

users — 管理用户

• beehiiv-pp-cli users — 识别用户 OAuth Scope: identify:read

webhooks — 管理 Webhook

• beehiiv-pp-cli webhooks create — 创建 Webhook OAuth Scope: webhooks:write
• beehiiv-pp-cli webhooks delete — 删除 Webhook OAuth Scope: webhooks:write
• beehiiv-pp-cli webhooks index — 列出 Webhook OAuth Scope: webhooks:read
• beehiiv-pp-cli webhooks show — 获取 Webhook OAuth Scope: webhooks:read
• beehiiv-pp-cli webhooks update — 更新 Webhook OAuth Scope: webhooks:write

workspaces — 管理工作区

• beehiiv-pp-cli workspaces identify — 识别工作区 OAuth Scope: identify:read
• beehiiv-pp-cli workspaces permissions-show — 检索为此工作区的 OAuth 或 API 令牌授予的权限。
• beehiiv-pp-cli workspaces publications-by-subscription-email — 检索工作区中订阅了指定电子邮件地址的所有出版物。

查找合适的命令

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

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

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

使用示例

镜像受众数据

beehiiv-pp-cli sync --resources publications,subscriptions,segments,posts --max-pages 100

使用游标分页，将四种对增长至关重要的实体同步到 SQLite。

适用于 Agent 的增长概览

beehiiv-pp-cli insights growth-summary pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --agent

基于本地存储计算得出的只读健康状况摘要。

缩小深度查询的范围

beehiiv-pp-cli insights subscriber-lookup pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 [email protected] --agent --select subscription.email,subscription.status

将 --agent 与 --select 点分路径搭配使用，仅返回 Agent 所需的字段。

分析流失率激增的来源

beehiiv-pp-cli insights churn-sources pub_477b0b68-0ab1-4b3f-954e-d1f6302b58a7 --limit 20

离线按来源、渠道、UTM 和引荐来源对退订进行分组。

导出订阅者 CSV

beehiiv-pp-cli search "@example.com" --type subscriptions --limit 1000 --csv > subscribers.csv

所有列表和搜索命令都可输出 CSV，供电子表格使用。

身份验证设置

在 app.beehiiv.com（Settings > API Keys）创建 API 密钥，并导出 BEEHIIV_API_KEY。该密钥是作用域限定为你组织的持有者令牌；每个组织共享每分钟 180 次请求的限额。

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

Agent 模式

在任何命令中添加 --agent。它相当于启用：--json --compact --no-input --no-color。

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

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

  beehiiv-pp-cli advertisement-opportunities mock-value --agent --select advertisement_kind,advertiser_name,id
  

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

• 适用于离线环境 — 有本地 SQLite 存储时，同步和搜索命令可使用该存储

• 非交互式 — 不会发出提示；所有输入都通过标志传入

• 明确确认 — --agent 不等同于 --yes；仅在确认目标、参数和副作用后，才单独传入 --yes

• 明确重试 — 仅当重复创建的目标已存在也应视为成功时使用 --idempotent；仅当删除目标不存在也应视为成功时使用 --ignore-missing

响应封装

从本地存储或 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>，或设置 BEEHIIV_HOME=<dir>，将四类路径都重定位到同一个根目录下。

• 仅当某一类路径需要单独设置时，才使用对应的环境变量：BEEHIIV_CONFIG_DIR、BEEHIIV_DATA_DIR、BEEHIIV_STATE_DIR、BEEHIIV_CACHE_DIR。

• 解析优先级依次为：对应类型的环境变量、--home、BEEHIIV_HOME、XDG（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME、XDG_CACHE_HOME），然后是平台默认路径。

• config 存放 config.toml 和配置档等设置。data 存放 credentials.toml、data.db、cookies 和认证附属文件。state 存放持久化查询、作业和 teach.log。cache 存放可重新生成的 HTTP/缓存文件。

• 存储的密钥位于 data 目录下的 credentials.toml 中。为保持兼容性，程序会读取现有的旧版 config.toml 密钥，并在首次写入认证信息时将其从 config.toml 中移出。

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

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

  {
    "mcpServers": {
      "beehiiv": {
        "command": "beehiiv-pp-mcp",
        "env": {
          "BEEHIIV_HOME": "/srv/beehiiv"
        }
      }
    }
  }
  

集群环境中的优先级：继承的对应类型环境变量会覆盖该类型显式设置的 --home。使用 BEEHIIV_HOME 或对应类型的环境变量作为持久的集群配置手段，仅在单次调用时使用 --home。取消设置环境变量无法撤销重定位；清除 BEEHIIV_HOME 前请手动移动文件，否则 doctor 将无法找到原根目录下的凭证。

自动学习

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

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

针对新的用户问题，在执行列表、搜索或深入查询命令之前，先运行：

beehiiv-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>", "beehiiv-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 `beehiiv-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> 会将推导签名标记为已废弃，以免同一候选项再次出现。封装中只包含当前值得采取行动的少数候选项；beehiiv-pp-cli learnings candidates 会列出所有未处理的候选项。

优雅降级：如果 learnings confirm 不是已知命令，说明你使用的是较旧版本的二进制文件——忽略候选项相关指引，继续遵循其余流程。

步骤 3：始终读取 warnings

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

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

学习是无条件的。解决存储无法回答的查询后，在后台学习最终的资源映射——不设调用次数门槛，也不判断学习“是否值得”。学习是整个循环的锚点：如果某个族没有操作手册，它会触发操作手册合成；对于同一指代对象的不同表述会合并到同一个族中，因此近似重复的学习不会导致存储碎片化。整理好面向用户的回复后、发出回复前，使用 shell & 执行该操作，使调用立即返回：

beehiiv-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：playbook - 可选标记、自动合成

你不必判断某个会话是否“值得”编写 playbook：如果某个类别还没有 playbook，使用该类别进行 teach 会根据会话日志自动合成一个 playbook_candidate，并由下一次会话通过确认/拒绝来判断。只有当你已经掌握值得原样记录的操作流程时，才附加明确的 playbook 标记——例如 CLI 未显示的变通方法（被静默丢弃的标记、未记录的参数、分页技巧、负载问题）。优先使用集成式单次调用形式——在同一次 teach 调用中记录资源学习内容和 playbook：

# Common case: record both the resource learning AND the playbook in one call.
beehiiv-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).
beehiiv-pp-cli teach-playbook \
  --query "<user's question>" \
  --playbook-file ~/playbooks/<shape>.json \
  --notes-file ~/playbooks/<shape>-notes.md

Playbook 文件是包含 steps、entity_slots、expected_tool_calls 的 JSON 文件。Notes 文件是原样记录问题细节的 Markdown 文件。不使用文件的调用方（仅使用 MCP 的 Agent）可直接内联传入相同内容：在集成式 teach 形式中使用 --playbook-json 和 --playbook-notes，在 teach-playbook 中使用 --playbook-json 和 --notes。在集成式 teach 形式中，playbook 标记是可选的——如果只想 teach 资源，可完全省略这些标记。在独立的 teach-playbook 形式中，必须至少设置 playbook 标记和 notes 标记中的一个；两者都为空时会被拒绝。Playbook 以结构化查询类别（去除实体）为键，因此从一种实体形态的查询中学到的操作步骤适用于同一形态的所有其他查询，并在回忆时通过 slots_resolved 绑定当前查询的规范形式。

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

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

如果你的调试协议响应指出 notes 或 playbook 应记录一项具体更正——例如变通方法、未记录的端点结构、过时的字段名称、观察到的架构漂移、空负载回退方案——请在生成面向用户的响应之前触发 playbook amend。与 teach 一样，采用触发后即不等待结果的方式。

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

哪些内容值得修订：本次会话中你 OBSERVED 到、且未来的你会受益于了解的行为。值得修订的示例：

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

哪些内容不应写入 notes：

• 用户问题中与年份或实体相关的答案。这是响应内容，不是学习内容。
• playbook 已在运行时获取的团队、运动员或行数据。
• 只是转述现有 notes 内容的陈述。

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

amend notes 中的 PII 规范

playbook amend notes 可能会在未来版本的 Printing Press 中作为共享知识向上游传递。请勿在其中包含可识别用户身份的内容，以便保持向上游贡献的渠道畅通，避免之后再进行清理：

• 请勿嵌入用户文件系统路径、个人 API 密钥或令牌、用户电子邮件地址、用户 GitHub 用户名，或与单个用户关联的特定查询历史记录。
• 可以包含：端点结构、未记录的字段名称、API 问题、观察到的架构漂移、CLI 界面的变通方法、可泛化的分页或重试策略。

如果某项更正只有结合用户特定的上下文才有意义，就应写入个人笔记，而不是 playbook amend。

衡量闭环效果

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

禁用学习

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

Agent 反馈

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

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

条目会在本地存储为解析后的数据目录下的 feedback.jsonl。除非设置了 BEEHIIV_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 BEEHIIV_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 每次提供不同输入、但重复使用相同的已保存标志时，可使用配置文件。

beehiiv-pp-cli profile save briefing --json
beehiiv-pp-cli --profile briefing advertisement-opportunities mock-value
beehiiv-pp-cli profile list --json
beehiiv-pp-cli profile show briefing
beehiiv-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

安装 MCP 服务

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

claude mcp add beehiiv-pp-mcp -- beehiiv-pp-mcp

验证：claude mcp list

直接使用

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

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

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