pp-trustpilot

Trustpilot — Printing Press 命令行工具

前置条件：安装命令行工具

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

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

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

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

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

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

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

何时使用此命令行工具

当 Agent 或研究人员需要按域名或名称查询公司的消费者评价时，可使用 Trustpilot 命令行工具。适用场景包括：为研究叙述补充近期好评与差评兼具的平衡样本、追踪 TrustScore 随时间的变化、在一次调用中比较多家公司，或按星级和日期筛选条件，在已同步的评价中搜索某个词（refund、chargeback）。也可与 last30days 配合，用于补充故事背景。

何时不使用此命令行工具

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

独特功能

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

last30days Agent 桥接

• top-recent — 一次调用即可获取某家公司最新的 N 条 4–5 星评价和最新的 N 条 1–2 星评价，让 Agent 无需分别抓取两次，就能引用平衡的观点。

  当 Agent 总结消费者过去 30 天对某家公司的评价时，此命令能返回可供引用的平衡样本。

  trustpilot-pp-cli top-recent thriftbooks.com --window 30d --good 5 --bad 5 --json
  

• agent-bundle — 返回一个 JSON 载荷，其中包含公司元数据、TrustScore、Trustpilot 自带的 AI 摘要、近期好评和差评精选，以及五档评分直方图——外部 Agent 所需的信息一应俱全，只需一次调用。

  如果要从其他 Agent 调用一个 Trustpilot 命令，就调用此命令。它专为 last30days 风格的故事补充而设计。

  trustpilot-pp-cli agent-bundle thriftbooks.com --json --select company.trustScore,company.numberOfReviews,topRecent.good,topRecent.bad,histogram
  

可持续积累的本地状态

• drift — 根据本地同步的评论重建周环比 TrustScore、1 星占比、5 星占比和评论量。Trustpilot 仅公开当前 TrustScore；此工具可呈现历史数据。

  在声称某公司的声誉正在改善或下滑之前使用；一次查询即可获得按星级构成细分的每周趋势。

  trustpilot-pp-cli drift thriftbooks.com --weeks 12 --json
  

• compare — 在选定的时间窗口内，对比 N 家公司的 TrustScore、评论增长速度以及 1 星／5 星占比，所有数据均来自本地同步存储。

  在推荐供应商或撰写对比文章之前进行行业分析的最佳命令。

  trustpilot-pp-cli compare thriftbooks.com bookshop.org powells.com --window 90d --json
  

• surge — 使用本地同步的数据行，通过滚动基线的 Z 分数检测评论总量或 1 星评论量是否出现统计显著的激增。

  在发布有关某公司的内容之前运行；新近出现的 1 星评论激增可能就是你会错过的头条。

  trustpilot-pp-cli surge thriftbooks.com --baseline 90d --window 7d --stars 1 --json
  

• search-reviews — 在已同步评论的标题、正文和商家回复中进行全文搜索，并可按星级、语言和日期筛选。基于 FTS5，可离线使用。

  如果问题是“过去 90 天内，1 星评论者对退款说了什么”，只有这个命令能给出答案。

  trustpilot-pp-cli search-reviews thriftbooks.com 'refund' --stars 1 --window 90d --lang en --json
  

• replies — 按星级统计已同步评论的回复率；设置 --unreplied 后，还会列出尚未回复的 1 星评论。

  忽视 1 星评论的公司可能无法做好客户支持；这是对此进行快速审核的命令。

  trustpilot-pp-cli replies thriftbooks.com --unreplied --stars 1 --json
  

• geo — 按时间窗口统计评论者所在国家／地区的分布，包括各国家／地区的评论数、平均评分和 1 星评论率。

  当不同地区的情绪表现不同时使用；国家／地区细分数据是发现局部事件的首个信号。

  trustpilot-pp-cli geo thriftbooks.com --window 90d --json
  

• whats-new — 按星级列出上次同步后新增的评论，让 Agent 无需重新获取全部内容即可轮询最新客户反馈。

  适用于只需获取增量而非完整归档的定时 Agent。

  trustpilot-pp-cli whats-new thriftbooks.com --since 2026-05-01 --json
  

Trustpilot 原生数据补充

• topics — 以 JSON 格式呈现 Trustpilot 预先计算的主题 AI 摘要（例如“配送”“价格”“状况”）。

  需要查看评论者实际讨论内容的分类主题时，Trustpilot 已完成主题聚类；此工具可呈现这些结果。

  trustpilot-pp-cli topics thriftbooks.com --json
  

• similar-sweep — 获取 Trustpilot 为某家公司返回的 8 家“相似企业”，并行抓取每家企业的信息，再按 TrustScore 和评论总数排名。

  自动发现的竞争对手及其指标，适用于客户拓展或生成未经你筛选的竞争对手列表。

  trustpilot-pp-cli similar-sweep thriftbooks.com --json
  

• category-top — 按 TrustScore 对 Trustpilot 某个类别中的公司排名（可选设置最低评论数门槛）。

  如果你想查询“Trustpilot 上至少有 100 条评论的最佳在线书店”，使用此命令即可。

  trustpilot-pp-cli category-top online-bookstore --limit 25 --min-reviews 100 --json
  

HTTP 传输

此 CLI 使用兼容 Chrome 的 HTTP 传输来访问面向浏览器的端点。常规 API 调用无需常驻浏览器进程。

命令参考

companies — 在 Trustpilot 中按名称搜索公司，并解析其规范域名

• trustpilot-pp-cli companies <search_build_id> — 搜索名称匹配的公司；返回可与 reviews-fetch 配合使用的 identifyingName 域名

reviews — 获取某家公司的 Trustpilot 评论

• trustpilot-pp-cli reviews <review_build_id> <domain> — 按域名获取某家公司的一个页面评论（在 CLI 中使用 'reviews-fetch '）。通过...进行身份验证

查找合适的命令

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

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

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

使用示例

last30days 过去 30 天的均衡样本

trustpilot-pp-cli top-recent www.thriftbooks.com --window 30d --good 5 --bad 5 --json

一次调用即可返回 5 条近期优质评论和 5 条近期差评——这是为报道提供可引用样本的标准方式。

单次调用 Agent 套件（最高效）

trustpilot-pp-cli agent-bundle www.thriftbooks.com --json --select company.trustScore,company.numberOfReviews,topRecent.good,topRecent.bad,histogram,aiSummary

将信息、近期热门内容、AI 摘要和直方图合并为单个数据包；对于深层嵌套字段，使用 --select 可将响应控制在几 KB 以内。

12 周信任评分和 1 星趋势

trustpilot-pp-cli drift www.thriftbooks.com --weeks 12 --json

根据已同步的评论重建每周 TrustScore；发现 Trustpilot 网站从不展示的转折点。

周一竞品概览：对比三家竞争对手

trustpilot-pp-cli compare www.thriftbooks.com bookshop.org powells.com --window 90d

从本地存储读取同一组竞品的数据，横向对比 TrustScore、评论速度以及 1 星／5 星占比。

用 Grep 搜索已同步的 1 星评论中的退款投诉

trustpilot-pp-cli search-reviews www.thriftbooks.com 'refund' --stars 1 --window 90d --lang en --json

FTS5 查询——同步数据为最新时可离线运行；结合 --select rating,title,publishedAt,text 可缩小输出范围。

身份验证设置

无需身份验证。

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

Agent 模式

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

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

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

  trustpilot-pp-cli companies mock-value --query example-value --agent --select id,name,status
  

• 可预览 — --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 反馈

当你（或 Agent）发现此 CLI 有异常时，请记录下来：

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

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

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

输出传递

每条命令都接受 --deliver <sink>。输出会写入指定的接收端，同时写入 stdout（或替代 stdout），因此 Agent 无需手动通过管道传递即可路由命令结果。支持以下三种接收端：

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

对于未知方案，系统会拒绝并返回结构化错误，指出受支持的方案。Webhook 请求失败时会返回非零状态，并将 URL 和 HTTP 状态记录到 stderr。

命名配置

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

trustpilot-pp-cli profile save briefing --json
trustpilot-pp-cli --profile briefing companies mock-value --query example-value
trustpilot-pp-cli profile list --json
trustpilot-pp-cli profile show briefing
trustpilot-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

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

claude mcp add trustpilot-pp-mcp -- trustpilot-pp-mcp

验证：claude mcp list

直接使用

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

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

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