pp-ahrefs

Ahrefs — Printing Press CLI

前提条件：安装 CLI

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

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

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

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

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

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

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

不要使用此 CLI 的情况

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

命令参考

keywords-explorer — Keywords Explorer 端点。

• ahrefs-pp-cli keywords-explorer matching-terms — 匹配词
• ahrefs-pp-cli keywords-explorer overview — 概览
• ahrefs-pp-cli keywords-explorer related-terms — 相关词
• ahrefs-pp-cli keywords-explorer search-suggestions — 搜索建议
• ahrefs-pp-cli keywords-explorer volume-by-country — 按国家/地区划分的搜索量
• ahrefs-pp-cli keywords-explorer volume-history — 时间序列。搜索量历史

public — 公共端点。

• ahrefs-pp-cli public crawler-ip-ranges — 爬虫 IP 范围
• ahrefs-pp-cli public crawler-ips — 爬虫 IP 地址

rank-tracker — Rank Tracker 端点。

• ahrefs-pp-cli rank-tracker competitors-overview — 竞争对手概览
• ahrefs-pp-cli rank-tracker overview — 概览
• ahrefs-pp-cli rank-tracker serp-overview — SERP 概览

serp-overview — Serp Overview 端点。

• ahrefs-pp-cli serp-overview — SERP 概览

site-audit — Site Audit 端点。

• ahrefs-pp-cli site-audit issues — 项目问题
• ahrefs-pp-cli site-audit page-content — 页面内容
• ahrefs-pp-cli site-audit page-explorer — 页面浏览器
• ahrefs-pp-cli site-audit projects — 项目健康评分

site-explorer — Site Explorer 端点。

• ahrefs-pp-cli site-explorer all-backlinks — 反向链接
• ahrefs-pp-cli site-explorer backlinks-stats — 反向链接统计
• ahrefs-pp-cli site-explorer broken-backlinks — 失效反向链接
• ahrefs-pp-cli site-explorer domain-rating — 指定时间点快照。域名评级
• ahrefs-pp-cli site-explorer domain-rating-history — 时间序列。域名评级历史
• ahrefs-pp-cli site-explorer metrics — 指定时间点快照。指标
• ahrefs-pp-cli site-explorer metrics-by-country — 按国家/地区划分的指标
• ahrefs-pp-cli site-explorer organic-competitors — 自然搜索竞争对手
• ahrefs-pp-cli site-explorer organic-keywords — 自然搜索关键词
• ahrefs-pp-cli site-explorer pages-by-traffic — 按流量排列的页面
• ahrefs-pp-cli site-explorer refdomains-history — 时间序列。引用域名历史
• ahrefs-pp-cli site-explorer top-pages — 热门页面

subscription-info — Subscription Info 端点。

• ahrefs-pp-cli subscription-info — 限额和用量

查找合适的命令

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

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

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

身份验证设置

通过环境变量设置 API key：

export AHREFS_API_KEY="<your-key>"

或者将其保存在 ~/.config/ahrefs-pp-cli/config.toml 中。

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

Agent 模式

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

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

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

  ahrefs-pp-cli keywords-explorer matching-terms --agent --select id,name,status
  

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

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

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

• 只读 — 不要使用此 CLI 执行创建、更新、删除、发布、评论、点赞、邀请、订购、发送或其他会修改数据的请求

响应封装

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

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

解析 .results 获取数据，并查看 .meta.source 判断数据来自实时来源还是本地。仅当 stdout 连接到终端时，才会向 stderr 打印人类可读的 N results (live) 摘要；通过管道传递的消费者或 Agent 消费者会在 stdout 上获得纯 JSON。

Agent 反馈

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

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

条目会保存在本地的 ~/.ahrefs-pp-cli/feedback.jsonl。除非设置了 AHREFS_FEEDBACK_ENDPOINT，且传入了 --send 或 AHREFS_FEEDBACK_AUTO_SEND=true，否则绝不会通过 POST 发送。默认行为仅在本地保存。

写下让你感到意外的地方，而不是提交 Bug 报告。简短、具体、一行即可：这部分会不断累积价值。

输出传递

每条命令都接受 --deliver <sink>。输出会发送到指定的 sink，同时输出到 stdout，或替代 stdout 输出，让 Agent 无需手动通过管道即可路由命令结果。支持以下三种 sink：

Sink	效果
stdout	默认；仅写入 stdout
file:<path>	将输出原子性地写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（使用 application/json，或在传入 --compact 时使用 application/x-ndjson）

不支持的 scheme 会被拒绝，并返回一条结构化错误，指出支持的 scheme。Webhook 请求失败时会返回非零退出码，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置

配置是保存的一组标志值，可在多次调用中重复使用。当定时 Agent 每次运行都以相同配置调用同一命令时，可使用配置——这是 HeyGen 的 “Beacon” 模式。

ahrefs-pp-cli profile save briefing --json
ahrefs-pp-cli --profile briefing keywords-explorer matching-terms
ahrefs-pp-cli profile list --json
ahrefs-pp-cli profile show briefing
ahrefs-pp-cli profile delete briefing --yes

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

退出码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

1. 安装 MCP 服务：

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

2. 注册到 Claude Code：

   claude mcp add ahrefs-pp-mcp -- ahrefs-pp-mcp
   

3. 验证：claude mcp list

直接使用

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

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

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