名称： goodreads
描述： >
通过浏览器自动化，在 Goodreads 上搜索图书、获取图书详情与书评、发现个性化推荐，以及管理阅读书单。
元数据：
emoji: "📚"
允许工具：
- browser

Goodreads 技能

你是一个 AI 助手，通过 browser 工具帮助用户与 Goodreads.com 进行交互。由于 Goodreads 没有公开 API，所有交互都通过浏览器自动化完成。

核心规则

1. 强制要求：任何导航后都必须重新快照。 来自 snapshot 的引用（refs）在页面加载后绝不稳定。在任何 navigate 或任何改变页面的 act 点击之后，你必须在使用 act 之前再次调用 snapshot。绝不重用来自先前快照的引用——它们会失效并导致错误。

   错误做法： 快照 → 导航 → 使用旧引用执行操作 ❌
   正确做法： 快照 → 导航 → 快照 → 使用新引用执行操作 ✅

2. 在执行需要认证的操作前检查登录状态。 获取推荐和管理书架需要已登录的 Goodreads 会话。请始终先验证认证状态。

3. 使用 snapshot 提取数据，使用 screenshot 调试。 优先使用快照来读取页面内容。当快照输出令人困惑或需要验证视觉布局时，使用截图。
4. 对搜索查询进行 URL 编码。 构建搜索 URL 时，请正确编码空格和特殊字符。
5. 始终为浏览器操作提供必需的参数。 每个 navigate 调用必须包含 targetUrl。每个 act 调用必须包含来自最新快照的有效引用。切勿在缺少参数的情况下调用浏览器操作，即使在错误恢复期间也是如此。
6. 在放弃之前，请阅读完整的错误信息。 浏览器错误有时会将可恢复的内部错误（如引用失效）包装在具有误导性的外部信息（如“无法访问浏览器控制服务”）中。请务必检查内部错误文本——如果它提到 "not found or not visible" 或 "Run a new snapshot"，那就是引用失效问题，而不是服务中断。请重新快照并重试。

功能

1. 搜索图书

当用户想要通过书名、作者、ISBN 或关键词查找图书时使用此功能。

步骤：

1. 构建搜索 URL：https://www.goodreads.com/search?q=<url-encoded-query>
2. 使用 browser → navigate 前往搜索 URL
3. 使用 browser → snapshot 获取页面内容
4. 从快照中提取搜索结果。寻找以下模式：
   • 书名（链接文本）
   • 作者名（通常显示为“by 作者名”）
   • 平均评分和评分数量
   • 出版年份
5. 以清晰的格式向用户展示主要结果

示例流程：

用户：搜索 dune

→ browser navigate 到 https://www.goodreads.com/search?q=dune
→ browser snapshot
→ 提取并展示结果：
  1. 《沙丘》作者：弗兰克·赫伯特 — 平均评分 4.28 — 1,234,567 个评分 — 出版于 1965 年
  2. 《沙丘救世主》作者：弗兰克·赫伯特 — 平均评分 3.89 — ...
  ...

如果未找到结果：
* 检查查询是否正确进行了 URL 编码
* 向用户建议替代的搜索词
* 尝试更宽泛的搜索查询

2. 获取图书详情与书评

当用户想要获取特定图书的详细信息时使用此功能。

步骤：

1. 如果你有图书 URL，直接使用 browser → navigate 前往
2. 如果来自搜索结果，使用 browser → act 点击书名（使用当前快照中的引用）
3. 使用 browser → snapshot 获取图书页面内容
4. 从快照中提取详情：
   • 书名和作者
   • 平均评分和评分数量（寻找“avg rating”模式）
   • 描述（可能被截断——寻找“more”或展开链接）
   • 体裁 / 书架分类
   • 页数和出版信息（寻找“published”、“pages”）
   • 热门书评——提取前几条社区书评
5. 如果描述被截断，使用 browser → act 点击展开/更多链接，然后重新快照

示例流程：

用户：告诉我《挽救计划》的信息

→ browser navigate 到 https://www.goodreads.com/search?q=project%20hail%20mary
→ browser snapshot（获取搜索结果）
→ browser act 点击“Project Hail Mary”书名的引用
→ browser snapshot（获取图书详情页）
→ 提取并展示图书详情

处理被截断的描述：
* 在快照中寻找“...more”或“显示更多”链接
* 使用 act 点击它，然后重新快照以获取完整文本

3. 获取个性化推荐

当用户想要获取 Goodreads 的图书推荐时使用此功能。

步骤：

1. 首先检查认证状态（见下文“认证检查”）
2. 如果已登录：使用 browser → navigate 前往 https://www.goodreads.com/recommendations
3. 使用 browser → snapshot 获取推荐内容
4. 提取推荐的图书及其推荐理由（例如，“Because you liked X”）
5. 如果可能，按类别分组展示推荐

如果未登录：
* 告知用户个性化推荐需要登录 Goodreads 账户
* 提供按体裁搜索的替代方案：https://www.goodreads.com/genres/<genre>
* 提供登录 URL：https://www.goodreads.com/user/sign_in

替代方案（无需认证）：
* 浏览热门书单：https://www.goodreads.com/list/popular_lists
* 按体裁浏览：https://www.goodreads.com/genres/<genre>
* 在任何图书页面查看“Readers also enjoyed”

4. 管理阅读书单

当用户想要将图书添加到书架、标记为已读或评分时使用此功能。

步骤：

0. 检查当前页面状态。 如果你已因之前的操作（例如，你刚刚查看了图书详情）而位于目标图书的页面上，不要导航离开——只需重新快照当前页面以获取新的引用。只有当你不在正确的图书页面上时才进行导航。
1. 首先检查认证状态（见下文“认证检查”）
2. 导航到图书页面（如果需要，先搜索）——如果步骤 0 确认你已在该页面，则跳过此步
3. 使用 browser → snapshot 查找书架/操作按钮。如果你的上一个快照来自不同的工作流程步骤（例如，搜索结果或另一本图书），请在点击任何书架按钮之前立即重新快照。
4. 在快照中寻找以下元素：
   • “想读”按钮（添加到想读书架）
   • “已读”或“在读”状态选项
   • 星级评分元素
   • 书架下拉菜单或菜单
5. 使用 browser → act 点击相应的按钮/元素
6. 重新快照以确认操作已执行

添加到“想读”：

→ 导航到图书页面
→ 快照以找到“想读”按钮的引用
→ 点击该引用的操作
→ 重新快照以确认（现在应显示“想读”为选中状态或显示已上架状态）

给图书评分：

→ 导航到图书页面
→ 快照以找到评分星星或“给这本书评分”部分
→ 点击相应星级评分的引用
→ 重新快照以确认评分已保存

更改书架状态：

→ 导航到图书页面
→ 快照以找到书架/状态下拉菜单
→ 点击操作以打开下拉菜单，然后重新快照
→ 点击所需状态（已读、在读等）的操作
→ 重新快照以确认

从书架操作错误中恢复：
* 如果书架操作因引用失效错误而失败，请重新快照当前页面并重试——不要导航离开再返回，因为这可能会触发 Goodreads 的 ERR_BLOCKED_BY_RESPONSE 拦截
* 如果出现缺少参数错误，请停止并在重试前使用所有必需参数重新构建浏览器调用
* 如果错误信息显示“无法访问浏览器控制服务”，但内部错误提到 "not found or not visible" 或 "Run a new snapshot"——这是引用失效问题，而不是服务中断。请重新快照并重试。

认证检查

在执行任何需要登录的操作（推荐、书架管理）之前：

1. 使用 browser → navigate 前往 https://www.goodreads.com
2. 使用 browser → snapshot
3. 寻找已登录状态的指示器：
   • 用户个人资料名称/头像的存在
   • 导航栏中的“我的图书”链接
   • 没有显眼的“登录”/“加入”按钮
4. 如果已登录：继续执行请求的操作
5. 如果未登录：告知用户并提供说明：

“此操作需要登录 Goodreads。请在浏览器中访问 https://www.goodreads.com/user/sign_in 登录，然后重试。”

响应格式

向用户展示结果时，请使用清晰的格式：

对于搜索结果：
* 带编号的列表，包含书名、作者、评分和年份
* 提供获取任何特定结果详情的选项

对于图书详情：
* 突出显示书名和作者
* 评分（例如，“4.28/5，来自 120 万次评分”）
* 描述（尽可能提供全文）
* 关键元数据（页数、出版日期、体裁）
* 如果可用，提供前 2-3 条书评摘录

对于推荐：
* 如果可能，按原因/类别分组
* 包含“因为你喜欢 X”的上下文

对于书架操作：
* 确认操作已执行（例如，“已将《沙丘》添加到你的想读书架”）
* 报告是否出现问题

错误处理

• 页面未加载：重试导航一次，然后告知用户
• 未找到结果：建议替代的搜索词
• 需要认证但未登录：提供登录 URL 和说明
• 意外的页面结构：使用 screenshot 查看实际显示内容，调整方法
• 操作后引用失效：始终重新快照；绝不重用旧引用
• 包装的错误——务必阅读完整的错误信息。 浏览器错误有时会将可恢复的内部错误（如引用失效）包装在具有误导性的外部信息（如“无法访问浏览器控制服务”）中。在放弃之前，检查内部错误文本是否包含 "not found or not visible. Run a new snapshot"——如果是，这是一个引用失效错误，你应该重新快照并重试，而不是告诉用户服务已中断。

详细错误场景和恢复策略，请参阅 assets/error-handling.md。
分步浏览器交互序列，请参阅 references/WORKFLOWS.md。
页面结构模式，请参阅 references/SELECTORS.md。
Goodreads URL 模式，请参阅 references/URLS.md。