pp-goodreads

Goodreads — Printing Press CLI

前置条件：安装 CLI

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

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

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

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

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

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/goodreads/cmd/goodreads-pp-cli@latest

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

HTTP 传输

此 CLI 使用兼容 Chrome 的 HTTP 传输来访问面向浏览器的端点，并将配置的 Goodreads 会话作为 _session_id2 Cookie 发送。正常 API 调用无需常驻的浏览器进程。

MCP 接口

MCP 二进制文件默认使用 stdio，也可通过流式 HTTP 为托管 Agent 提供服务：

goodreads-pp-mcp
goodreads-pp-mcp --transport http --addr :7777

默认 MCP 注册会为完整路由映射公开 goodreads_search 和 goodreads_execute，以及本地的 search、sql 和 context。原始端点镜像工具需通过 GOODREADS_MCP_ENDPOINT_MIRRORS=1 启用。除非在明确批准后设置 GOODREADS_PP_ALLOW_WRITES=1，否则会阻止修改数据的路由。

命令参考

amazon-purchases — 管理 Amazon 购买记录

• goodreads-pp-cli amazon-purchases — Amazon 购买记录导入/检查页面。

book — 管理图书

• goodreads-pp-cli book <book_slug> — 图书详情页面。当前页面由 Next.js 提供支持。

comment — 管理评论

• goodreads-pp-cli comment <user_slug> — 用户评论/近期帖子页面。

feed — 阅读主页动态源（好友活动）

• goodreads-pp-cli feed list — 阅读主页动态源（好友活动）。使用 --page <n> 查看更早的动态。对 /home/load_more_updates 发起只读 POST 请求。

friend — 查看 Goodreads 好友和好友请求

• goodreads-pp-cli friend list — 好友索引页面。
• goodreads-pp-cli friend list-requests — 好友请求页面。

genres — 浏览 Goodreads 类型和书架发现页面

• goodreads-pp-cli genres get — 类型首页。
• goodreads-pp-cli genres list — 类型索引页面。
• goodreads-pp-cli genres list-list — 类型书架字母索引。
• goodreads-pp-cli genres list-search — 类型查找路由。

giveaway — 浏览并参与 Goodreads 赠书活动

• goodreads-pp-cli giveaway list — 浏览 Goodreads 赠书活动列表（--format、--genre）。
• goodreads-pp-cli giveaway show <giveaway_id> — 显示一项赠书活动的详情页面。
• goodreads-pp-cli giveaway enter <giveaway_id> — 参与赠书活动。尚未上线：尚未捕获报名 POST 请求格式；拒绝实际执行，--dry-run 会预览目前已知的最佳请求。

goodreads-web-undocumented-search — 管理 Goodreads 网页未公开的搜索功能

• goodreads-pp-cli goodreads-web-undocumented-search — 来自 OpenSearch 描述符的规范图书搜索路由。

list — 管理列表

• goodreads-pp-cli list <list_id> — 公开的 Listopia 列表页面。

message — 检查并规划 Goodreads 消息文件夹操作

• goodreads-pp-cli message create — 批量执行消息文件夹/已读操作。
• goodreads-pp-cli message get — 用户消息文件夹页面。
• goodreads-pp-cli message get-show — 消息详情页面。
• goodreads-pp-cli message list — 用户消息收件箱。
• goodreads-pp-cli message list-markallasread — 将收件箱中所有可见消息标记为已读。

notes — 阅读并规划 Kindle 笔记/高亮操作

• goodreads-pp-cli notes get — 用户 Kindle 笔记与高亮索引。

• goodreads-pp-cli notes get-bookslug — 某本图书及用户的笔记/高亮详情页面。 notifications — 检查 Goodreads 通知和跟踪调用

• goodreads-pp-cli notifications create — UI 发出的通知跟踪调用。

• goodreads-pp-cli notifications list — 用户通知页面。

opensearch-xml — 管理 opensearch xml

• goodreads-pp-cli opensearch-xml — Goodreads 图书搜索的 OpenSearch 描述符。

quotes — 查看 Goodreads 引言和引言小组件

• goodreads-pp-cli quotes get — 用户引言小组件脚本。
• goodreads-pp-cli quotes list — 当前用户的引言列表。

rating — 为图书设置或清除星级评分（GraphQL）

评分通过现代 Goodreads AWS AppSync GraphQL API（RateBook / UnrateBook）写入，而非旧版表单。此操作需要绑定的 AppSync JWT 凭证，该凭证与会话 Cookie 不同。通过 GOODREADS_GRAPHQL_TOKEN 设置（参见 Auth Setup）。写入操作受到限制：使用 --dry-run 预览，或在批准后设置 GOODREADS_PP_ALLOW_WRITES=1 执行。

• goodreads-pp-cli rating set <book_id> --stars <1-5> — 为图书评分（RateBook GraphQL mutation）。
• goodreads-pp-cli rating clear <book_id> — 清除你的评分（UnrateBook GraphQL mutation）。

recommendations — 查看 Goodreads 推荐页面

• goodreads-pp-cli recommendations list — 个性化推荐页面。
• goodreads-pp-cli recommendations list-tome — 好友推荐页面。

review — 阅读和撰写评论；规划书架／评论表格操作

• goodreads-pp-cli review create <book_id> — 撰写／更新图书评论（--review、--spoiler、--publicize、--add-to-blog、--shelf、--notes）。提交旧版 /review/update/:book_id 表单（form-urlencoded）。Rails CSRF 令牌来自 GOODREADS_AUTHENTICITY_TOKEN 环境变量或标准输入（--authenticity-token 标志已弃用——它会泄露到 shell 历史记录／ps aux 中）。星级评分只能通过 GraphQL 设置——请使用 rating set。
• goodreads-pp-cli review create-update <book_id> --stdin — 更新单本图书的评论／日期／备注字段。通过管道传入 Rails 评论表单字段的 JSON 对象（例如 {"review[review]":"..."}）；以 form-urlencoded 格式发送到 /review/update/:book_id。CSRF 令牌通过 GOODREADS_AUTHENTICITY_TOKEN 提供。
• goodreads-pp-cli review create-updatelist — 批量更新用户书架表格中选定的评论／图书。
• goodreads-pp-cli review get — 用户书架列表，可按书架筛选。
• goodreads-pp-cli review get-listrss — 这是当前最简洁的书架导出读取 API 公共 XML 路由。
• goodreads-pp-cli review get-stats — 阅读统计页面。
• goodreads-pp-cli review list — 评论草稿页面。
• goodreads-pp-cli review list-duplicates — 重复图书工具。
• goodreads-pp-cli review list-import — 导入／导出页面。

shelf — 查看和规划 Goodreads 书架操作

• goodreads-pp-cli shelf create — 通过书架选择辅助工具，从书架添加或移除一本图书。
• goodreads-pp-cli shelf create-movebatch — 批量重新排列图书／书架。
• goodreads-pp-cli shelf create-movebatch-2 — 保存用户书架表格中的位置更改。
• goodreads-pp-cli shelf create-movetoposition — 将一行书架／图书移到指定位置。
• goodreads-pp-cli shelf create-removebook — 通过按钮辅助工具从书架移除一本图书。
• goodreads-pp-cli shelf create-update — 更新书架显示／设置。
• goodreads-pp-cli shelf get — 公共书架首页。
• goodreads-pp-cli shelf list — 公共热门书架索引。

tooltips — 管理工具提示

• goodreads-pp-cli tooltips — 获取书架／列表页面所示图书 ID 的批量工具提示元数据。

topic — 管理话题

• goodreads-pp-cli topic — 讨论页面，可按群组筛选。

user — 查看 Goodreads 个人资料和用户页面

• goodreads-pp-cli user get — 查看个人资料的延迟加载部分。
• goodreads-pp-cli user get-show — 查看用户个人资料页。
• goodreads-pp-cli user get-yearinbooks — 查看「年度读书」页面。
• goodreads-pp-cli user list — 查看最受欢迎书评人的用户发现页面。
• goodreads-pp-cli user list-topreaders — 查看顶级读者的用户发现页面。
• goodreads-pp-cli user list-topreviewers — 查看顶级书评人的用户发现页面。

user-following — 查看 Goodreads 最受关注用户的发现页面

• goodreads-pp-cli user-following — 查看最受关注用户的用户发现页面。

user-shelves — 规划创建自定义 Goodreads 书架

• goodreads-pp-cli user-shelves — 创建自定义用户书架。

查找合适的命令

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

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

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

身份验证设置

Goodreads 不再提供新的公开开发者 API 密钥。运行 goodreads-pp-cli auth setup，查看配置 Goodreads 浏览器会话 Cookie 的 URL 和步骤（添加 --launch 可打开 Goodreads）。然后只设置 Goodreads 的 _session_id2 Cookie 值：

export GOODREADS_GOODREADS_COOKIE_SESSION="<your-goodreads-session-cookie>"

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

请勿粘贴 Amazon、AWS 或其他无关浏览器 Cookie。

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

GraphQL 令牌（仅用于写入评分）

rating set / rating clear 命令通过现代 Goodreads AWS AppSync GraphQL API 写入数据，该 API 使用绑定的 JWT 进行身份验证——这是与会话 Cookie 分开的凭据。获取方式如下：

1. 登录 goodreads.com，打开浏览器开发者工具 →「网络」。
2. 在任意图书页面上点击一个评分星级；找到发往 *.appsync-api.*.amazonaws.com/graphql 的请求。
3. 复制请求头 Authorization 的值。
4. export GOODREADS_GRAPHQL_TOKEN='<that value>'

会话 Cookie 本身无法通过 GraphQL 身份验证。在实际抓取中未发现可从 Cookie 生成令牌的端点，因此受支持的方式是设置环境变量。其他所有命令（读取、旧版书评表单、书架写入）都只使用会话 Cookie。

Rails CSRF 令牌（书评／书架表单写入）

旧版表单写入（review create、review create-update、shelf create）需要从相关编辑页面获取 Rails CSRF authenticity_token（例如 /review/edit/:book_id 中隐藏的 authenticity_token 输入项）。请通过 GOODREADS_AUTHENTICITY_TOKEN 环境变量提供（首选），或通过标准输入传入——两种方式都能避免将其记录在 shell 历史记录和进程表（ps aux）中。--authenticity-token 标志仍然可用，但出于上述原因已弃用。

Agent 模式

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

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

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

  goodreads-pp-cli amazon-purchases --agent --select id,name,status
  

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

• 适合离线使用 — sync/search 命令在本地 SQLite 存储可用时可使用该存储

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

• 明确重试 — 仅当已存在的创建结果应视为成功时，才使用 --idempotent

响应封装

读取本地存储或 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 有任何不妥之处时，请记录下来：

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

条目会本地存储在 ~/.goodreads-pp-cli/feedback.jsonl。除非设置了 GOODREADS_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 GOODREADS_FEEDBACK_AUTO_SEND=true，否则不会发送 POST 请求。默认行为仅限本地存储。

记录让你感到意外的地方，而不是提交 Bug 报告。写得简短、具体，限一行：这才是产生累积价值的关键。

输出传递

每条命令都接受 --deliver <sink>。输出会发送到指定的 sink，同时输出到 stdout，或取代 stdout 输出，因此 Agent 无需手动通过管道传递命令结果。支持三种 sink：

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

遇到未知方案时，会拒绝请求并返回结构化错误，说明支持的方案。Webhook 请求失败会返回非零退出码，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置

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

goodreads-pp-cli profile save briefing --json
goodreads-pp-cli --profile briefing amazon-purchases
goodreads-pp-cli profile list --json
goodreads-pp-cli profile show briefing
goodreads-pp-cli profile delete briefing --yes

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

退出码

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

参数解析

解析 $ARGUMENTS：

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

安装 MCP 服务

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

claude mcp add goodreads-pp-mcp -- goodreads-pp-mcp

验证：claude mcp list

直接使用

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

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

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