pp-instagram

Instagram — Printing Press CLI

先决条件：安装 CLI

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

1. 通过 Printing Press 安装程序安装：

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

2. 验证：instagram-pp-cli --version
3. 确保 $GOPATH/bin（或 $HOME/go/bin）位于 $PATH 中。

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

go install github.com/mvanhorn/printing-press-library/library/social-and-messaging/instagram/cmd/instagram-pp-cli@latest

如果安装后 --version 报告“command not found”，说明安装步骤未将二进制文件放入 $PATH。验证成功之前，不要继续执行技能命令。

这是一款本地优先的 Instagram Graph API 分析 CLI，专为管理多个自有 Business/Creator 账号的管理者打造。它会将账号、媒体、洞察数据和竞争对手快照同步到可查询的 SQLite 存储中，并提供官方工具所缺少的视图：并排排名你的品牌（compare）、跟踪粉丝增长趋势（growth）、寻找最佳发帖时间、分析内容形式以及对比竞争对手数据。全程提供适合 Agent 的输出、离线搜索和类型化退出代码。

何时使用此 CLI

当 Agent 或操作人员需要分析多个自有 Instagram Business/Creator 账号的数据时，请使用此 CLI：例如比较品牌、跟踪粉丝增长和互动趋势、为帖子排名、分析内容形式或对标竞争对手。如果问题涉及多个账号，或需要 Graph API 的短期窗口无法提供的历史数据，那么它就是合适的工具。

不适用场景

以下情况请勿使用此 CLI：

• 请勿使用此 CLI 抓取或分析你不拥有的任意公开个人资料——它仅支持关联到你的 Pages 的账号，以及公开的 business_discovery 快照。
• 请勿将其用作主要的内容排期工具；它支持通过 --dry-run 发布内容，但 CLI 的核心用途是分析。
• 请勿将其用于 Facebook Page 或 Meta Ads 分析——它仅覆盖 Instagram 自然内容。
• 请勿将其用于实时/流式指标——Graph 洞察数据按日汇总，不是实时数据。

独特功能

这些功能在其他适用于此 API 的工具中均不可用。

跨账号组合分析

• compare — 按一段时间内的覆盖人数、互动量和互动率并排排列所有品牌账号。

  当 Agent 需要在一个排名表中回答“我的哪些品牌表现最好”时，使用此功能，而不是分别调用 N 次账号洞察接口。

  instagram-pp-cli compare --since 30d --agent
  

• growth — 按品牌跟踪粉丝数随时间的增长情况，逐周查看。

  当问题关注趋势（我们是否在增长？）时，使用此功能，而不是查看个人资料字段已提供的某个时间点粉丝数。

  instagram-pp-cli growth --since 8w --agent
  

• rivals — 跨多次同步跟踪竞争对手公开账号的粉丝和互动增长情况，并与自己的品牌进行对标。

  当需要回答单次 business_discovery 调用无法解决的竞争趋势问题时，使用此功能。

  instagram-pp-cli rivals --since 30d --agent
  

基于本地历史数据推导

• best-time — 找出历史上帖子互动量最高的星期和时段。

  当需要依据账号自身数据（而非泛泛而谈的经验）推荐发帖时间时，使用此功能。

  instagram-pp-cli best-time --account acme --agent
  

• top-posts — 在一段时间内，按覆盖人数、互动量、保存量或分享量为各品牌的帖子排名。

  当需要快速找出表现最佳的内容，而不是手动翻页并对媒体内容排序时，使用此功能。

  instagram-pp-cli top-posts --since 30d --metric reach --agent
  

• formats — 按覆盖人数、互动率和 Reels 观看时长比较 Reels、Feed、Story 和 Carousel。

  当需要汇总回答“哪种内容形式最适合这个品牌”时，使用此功能，而不是逐个调用帖子的洞察接口。

  instagram-pp-cli formats --account bistro --agent
  

• hashtag-perf — 按热门媒体的覆盖人数和互动量为你跟踪的标签排名。

  当需要比较标签的投资回报率时，使用此功能；若要发现新标签，请改用整合的标签搜索。

  instagram-pp-cli hashtag-perf --agent
  

命令参考

account-insights — 账户级洞察（触达、浏览量、互动、人口统计）

• instagram-pp-cli account-insights demographics — 按年龄、性别、城市或国家细分的粉丝终身人口统计数据
• instagram-pp-cli account-insights list — 指定时间范围内的账户洞察（触达、accounts_engaged、total_interactions、浏览量）

accounts — 品牌账户资料（关联到你管理的 Page 的 Instagram Business/Creator 用户）

• instagram-pp-cli accounts get — 获取品牌账户资料（粉丝数、关注数、媒体数量、简介）
• instagram-pp-cli accounts pages — 列出你管理的 Facebook Page 及其关联的 Instagram Business 账户 ID

business-discovery — 任意商业/创作者账户的公开指标（竞品调研）

• instagram-pp-cli business-discovery <ig_user_id> — 通过 business_discovery 字段表达式获取竞品的公开数据

comments — 媒体上的评论和回复

• instagram-pp-cli comments list — 列出媒体对象上的评论
• instagram-pp-cli comments replies — 列出对某条评论的回复

hashtags — 话题标签搜索及热门/最新媒体

• instagram-pp-cli hashtags recent-media — 获取某个话题标签 ID 对应的最新公开媒体
• instagram-pp-cli hashtags search — 将话题标签字符串解析为其 ID（每个账户每 7 天最多可查询 30 个不同标签）
• instagram-pp-cli hashtags top-media — 获取某个话题标签 ID 对应的表现最佳公开媒体

media — 帖子、Reels 和单条媒体的洞察

• instagram-pp-cli media create — 创建媒体容器（发布第 1 步）。此 CLI 以分析为先；请使用 --dry-run。
• instagram-pp-cli media get — 按 ID 获取单个媒体对象
• instagram-pp-cli media insights — 单条媒体的洞察（触达、浏览量、保存、分享、互动；Reels 观看时长）
• instagram-pp-cli media list — 按时间从新到旧列出品牌媒体（帖子、Reels、轮播）
• instagram-pp-cli media publish — 发布之前创建的媒体容器（第 2 步）。
• instagram-pp-cli media publish-limit — 检查剩余的内容发布配额（滚动 24 小时）

stories — 当前有效的快拍（24 小时窗口）

• instagram-pp-cli stories <ig_user_id> — 列出品牌当前有效的快拍（24 小时后过期）

tags — 你被标记的媒体

• instagram-pp-cli tags <ig_user_id> — 列出标记了你品牌账户的公开媒体

查找合适的命令

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

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

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

配方

按本月互动率为品牌排名

instagram-pp-cli compare --since 30d --agent

一张排名表涵盖所有自有账户——Meta Business Suite 从不展示这一视图。

为 Agent 精简媒体洞察中的嵌套数据

instagram-pp-cli media list 17841400000000000 --agent --select data.caption,data.media_product_type,data.like_count,data.comments_count

传入品牌的 IG 用户 ID（来自 'brands list'）；媒体响应包含深层嵌套数据，因此 --select 可筛出最关键的字段，避免 Agent 解析数十 KB 的内容。

查找该品牌适合发帖的时间

instagram-pp-cli best-time --account bistro --agent

按星期和小时对品牌自身的发帖历史进行分组，以推荐发布时间段，而非提供泛泛的建议。

追踪竞品增长

instagram-pp-cli rivals --since 30d --agent

对累积的 business_discovery 快照进行差异比较，得出竞品粉丝数/互动量的变化。

比较内容形式

instagram-pp-cli formats --account cafe --agent

汇总比较 Reels、Feed、Story 和 Carousel，包括 Reels 观看时长。

身份验证设置

身份验证使用 Business 类型应用在 Facebook-Login 流程中的 Meta Graph API 访问令牌。将 INSTAGRAM_ACCESS_TOKEN 设置为长期有效的用户令牌，或（推荐）永不过期的系统用户令牌，并授予 instagram_basic、instagram_manage_insights、pages_show_list、pages_read_engagement、business_management 权限范围。CLI 会通过 /me/accounts 从你的 Pages 中解析每个品牌的 IG 用户 ID，且除非你明确运行发布命令，否则不会执行任何写入操作。运行 'doctor' 以验证令牌权限范围、过期时间和已解析的账户 ID。

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

Agent 模式

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

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

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

  instagram-pp-cli account-insights list 17841400000000000 --agent --select data.name,data.period
  

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

• 支持离线使用 — 同步／搜索命令在本地 SQLite 存储可用时可使用该存储

• 非交互式 — 从不提示，每项输入都通过标志传入

• 显式重试 — 仅当已存在的创建操作也应视为成功时，才使用 --idempotent

响应信封

从本地存储或 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 有异常之处时，请记录下来：

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

条目会本地存储在 ~/.local/share/instagram-pp-cli/feedback.jsonl。除非设置了 INSTAGRAM_FEEDBACK_ENDPOINT，且传入了 --send 或 INSTAGRAM_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”模式。

instagram-pp-cli profile save briefing --json
instagram-pp-cli --profile briefing account-insights list 17841400000000000
instagram-pp-cli profile list --json
instagram-pp-cli profile show briefing
instagram-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/social-and-messaging/instagram/cmd/instagram-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add instagram-pp-mcp -- instagram-pp-mcp
   

3. 验证：claude mcp list

直接使用

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

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

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