pp-kit

Kit — Printing Press 命令行工具

前置条件：安装 CLI

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

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

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

2. 验证：kit-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用 Go 直接安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/marketing/kit/cmd/kit-pp-cli@latest

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

Agent Kit 工作流

当用户要求进行规划、诊断、审计、支持或了解账户情况时，优先使用以下只读工作流，而不是原始端点镜像：

• kit-pp-cli workflow creator-snapshot --agent — 提供一份运营快照，包含账户、增长、受众、内容、webhook 和广播统计数据。
• kit-pp-cli workflow audience-health --agent — 提供订阅者状态计数、增长统计数据，以及按订阅者数量排列的最大标签。
• kit-pp-cli workflow content-inventory --agent — 提供序列、序列邮件、片段、表单、邮件模板和近期广播统计数据，供内容规划使用。
• kit-pp-cli workflow subscriber-lookup --email <email> --agent — 提供一份订阅者资料，包含自定义字段、标签、归因信息和邮件统计数据。

当用户需要特定的 CRUD 操作、与端点完全一致的结果、超出工作流限制的分页，或写入操作时，请使用原始端点命令。这些工作流会调用真实的 Kit v4 端点；它们不是缓存摘要，也不是模拟数据。

独有功能

其他用于此 API 的工具均不具备这些功能。

创作者操作

• workflow creator-snapshot — 通过一次只读调用，获取 Kit 账户、增长、受众、内容、webhook 和广播统计数据的运营快照。

  当 Agent 需要了解当前创作者账户情况，而不想手动调用多个端点镜像时，请优先使用此工作流。

  kit-pp-cli workflow creator-snapshot --agent
  

受众洞察

• workflow audience-health — 提供只读的订阅者状态计数、近期增长统计数据，以及按订阅者数量排列的最大标签。

  在清理列表、进行细分或规划营销活动前使用此工作流，避免多次调用不稳定的订阅者和标签接口。

  kit-pp-cli workflow audience-health --agent
  

• workflow subscriber-lookup — 按电子邮件地址或 ID 查询只读订阅者档案，包含个人资料、自定义字段、标签、归因信息和邮件统计数据。

  在调用原始订阅者端点前，用于支持、细分检查和个性化问题排查。

内容规划

• workflow content-inventory — 提供序列、序列邮件、片段、表单、模板和近期广播统计数据的只读清单。

  进行内容审计和规划时，请使用此工作流，而不是分别列出 Kit 的每种内容类型。

  kit-pp-cli workflow content-inventory --agent
  

趋势和排名

• growth-trends — 关联指定日期范围内的账户增长统计数据与广播表现。可选通过类型化的 UpsertBroadcastsStats 写入路径缓存结果。
• tag-performance — 按订阅者数量对标签进行排名，并显示占总数的百分比；可选的 --subscriber-query 会使用 SearchSubscribers 将范围缩小到某个细分群体。

MCP 意图工具

四个一类 MCP 意图工具通过类型化输入架构和只读注解提供工作流命令。当 Agent 宿主需要类型化参数和明确的安全提示时，请通过 MCP 服务（kit-pp-mcp）使用这些工具：

• intent_workflow_creator_snapshot
• intent_workflow_audience_health
• intent_workflow_content_inventory
• intent_workflow_subscriber_lookup

MCP 服务支持 stdio 和可流式传输的 HTTP 传输方式（--transport http --addr :7777 或 PP_MCP_TRANSPORT=http）。

命令参考

workflow — 面向 Agent 的 Kit 专属复合工作流

• kit-pp-cli workflow creator-snapshot — 汇总账户、受众、内容和广播的健康状况
• kit-pp-cli workflow audience-health — 汇总订阅者状态、近期增长情况和数量最多的标签
• kit-pp-cli workflow content-inventory — 清点序列、邮件、片段、表单、模板和广播
• kit-pp-cli workflow subscriber-lookup — 获取一位订阅者的信息，包括标签、自定义字段、归因和邮件统计

account — 管理账户

• kit-pp-cli account list — 获取当前账户
• kit-pp-cli account list-colors — 列出颜色
• kit-pp-cli account list-creatorprofile — 获取 Creator Profile
• kit-pp-cli account list-emailstats — 获取邮件统计数据
• kit-pp-cli account list-growthstats — 获取指定时间段的增长统计数据。默认为最近 90 天。
  
  注意：我们以你的...
• kit-pp-cli account update — 更新颜色

broadcasts — 管理广播

• kit-pp-cli broadcasts create — 起草或安排广播，向所有或部分订阅者发送。
  
  要保存为草稿，请设置...
• kit-pp-cli broadcasts delete — 删除广播
• kit-pp-cli broadcasts get — 获取广播
• kit-pp-cli broadcasts list — 列出广播
• kit-pp-cli broadcasts list-stats — 获取广播列表的统计数据
• kit-pp-cli broadcasts update — 更新现有广播。继续起草或安排广播，向所有或部分订阅者发送...

bulk — 管理批量操作

• kit-pp-cli bulk create — 更多信息请参阅“批量与异步处理”。
• kit-pp-cli bulk create-customfields — 批量更新订阅者的自定义字段值
• kit-pp-cli bulk create-forms — 将订阅者添加到双重确认表单会触发发送激励邮件。已添加到该...
• kit-pp-cli bulk create-subscribers — 更多信息请参阅“批量与异步处理”。
• kit-pp-cli bulk create-tags — 更多信息请参阅“批量与异步处理”。
• kit-pp-cli bulk create-tags-2 — 要添加标签的订阅者必须已存在。可以使用“[批量创建...
• kit-pp-cli bulk delete — 更多信息请参阅“批量与异步处理”。

custom-fields — 管理自定义字段

• kit-pp-cli custom-fields create — 为账户创建自定义字段。标签字段必须在账户中唯一。空白字符将被移除...
• kit-pp-cli custom-fields delete — 此操作将删除订阅者在此字段中的所有数据。
• kit-pp-cli custom-fields list — 自定义字段可用于收集订阅者信息，不限于姓名和电子邮件等标准字段...
• kit-pp-cli custom-fields update — 更新自定义字段标签（请参阅创建自定义字段，了解...

email-templates — 管理邮件模板

• kit-pp-cli email-templates — 列出邮件模板

forms — 管理表单

• kit-pp-cli forms — 列出表单

posts — 管理帖子

• kit-pp-cli posts get — 获取帖子
• kit-pp-cli posts list — 列出帖子

purchases — 管理购买记录

• kit-pp-cli purchases create — 创建购买记录
• kit-pp-cli purchases get — 获取购买记录
• kit-pp-cli purchases list — 列出购买记录

segments — 管理细分群体

• kit-pp-cli segments — 列出细分群体

sequences — 管理序列

• kit-pp-cli sequences create — 创建一个空序列，即用于容纳序列邮件的容器。创建好框架后，使用 [Create a...
• kit-pp-cli sequences delete — 软删除一个序列。该序列会立即从活动投递中移除，并清理相关状态...
• kit-pp-cli sequences get — 按 id 获取单个序列。需要查看当前计划、active / repeat / hold... 时使用此命令
• kit-pp-cli sequences list — 返回账户中的所有序列。序列是一组独立的自动化邮件 — 订阅者加入后，...
• kit-pp-cli sequences update — 更新任何序列设置 — name、email_address、计划（send_days、send_hour、time_zone）...

snippets — 管理片段

• kit-pp-cli snippets create — 片段是可重复使用的邮件内容，可通过 Liquid 插入到广播邮件或序列邮件中：`{{...
• kit-pp-cli snippets get — 按 id 获取单个片段。与 List snippets 不同，此端点...
• kit-pp-cli snippets list — 返回账户中的所有片段。每个片段的 key 是 Liquid 中使用的标识符 — {{ snippet.key }}...
• kit-pp-cli snippets update — 重命名片段、替换其正文，或将其归档/恢复。更新会在任何邮件下次发送时生效...

subscribers — 管理订阅者

• kit-pp-cli subscribers create — 执行插入或更新操作。如果提供的电子邮件地址对应的订阅者不存在，则会创建一个，并设置...
• kit-pp-cli subscribers create-filter — 根据互动情况筛选订阅者
• kit-pp-cli subscribers get — 获取订阅者
• kit-pp-cli subscribers list — 列出订阅者
• kit-pp-cli subscribers update — 如果包含账户中不存在的自定义字段键，请求会返回错误。使用 [List...

tags — 管理标签

• kit-pp-cli tags create — 创建标签
• kit-pp-cli tags list — 列出标签
• kit-pp-cli tags update — 更新标签名称

webhooks — 管理 Webhook

• kit-pp-cli webhooks create — 可用事件类型：
  - subscriber.subscriber_activate
  - subscriber.subscriber_unsubscribe
  -...
• kit-pp-cli webhooks delete — 删除 Webhook
• kit-pp-cli webhooks list — Webhook 是一种自动化机制，会在订阅者事件触发时接收订阅者数据，例如当...

查找合适的命令

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

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

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

身份验证设置

运行 kit-pp-cli auth setup，打印获取密钥所需的 URL 和步骤（添加 --launch 可打开 URL）。然后设置：

export KIT_API_KEY="<your-key>"

或者将其保存到 ~/.config/kit-pp-cli/config.toml。

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

Agent 模式

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

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

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

  kit-pp-cli account list --agent --select id,name,status
  

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

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

• 非交互式 — 从不提示输入，所有输入均通过标志提供

• 显式重试 — 仅当已存在的创建操作应视为成功时才使用 --idempotent；仅当缺失的删除目标应视为成功时才使用 --ignore-missing

响应封装

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

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

从 .results 解析数据，并通过 .meta.source 判断数据来自实时数据还是本地数据。只有当 stdout 是终端，且未设置机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会仅向 stderr 输出人类可读的 N results (live) 摘要；通过管道传递的结果、供 Agent 使用的结果以及显式指定格式的运行都会在 stdout 输出纯 JSON。

Agent 反馈

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

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

条目会保存在本地的 ~/.kit-pp-cli/feedback.jsonl 中。只有在设置了 KIT_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 KIT_FEEDBACK_AUTO_SEND=true 时，才会 POST。默认行为仅保存在本地。

记录让你感到意外的地方，而不是提交 Bug 报告。简短、具体，写成一行：这才是能不断积累价值的内容。

输出交付

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

kit-pp-cli profile save briefing --json
kit-pp-cli --profile briefing account list
kit-pp-cli profile list --json
kit-pp-cli profile show briefing
kit-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/marketing/kit/cmd/kit-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add kit-pp-mcp -- kit-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which kit-pp-cli 如果未找到，请提供安装选项（请参阅本技能顶部的前置条件）。
2. 对于涉及账户、受众、内容或订阅者背景信息的广泛请求，优先使用上文的 Agentic Kit 工作流。
3. 对于范围较窄的用户查询，从上文的命令参考中选择最合适的命令。
4. 使用 --agent 标志执行：

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

5. 如果有歧义，请查看子命令帮助：kit-pp-cli <command> --help。