tweetsmash-api

TweetSmash API

使用此技能可依据当前端点证据，直接调用 TweetSmash REST API。重用本任务中已验证的文档；若文档缺失、过时或与 API 返回结果矛盾，请重新核实。选择端点前，请先阅读 references/api-reference.md。仅在需要筛选书签时，才阅读 references/bookmarks-filters.md。

操作步骤

第 1 步：验证凭据和访问范围

1. 发出请求前，确认有可用的 TweetSmash API 密钥。优先使用 shell 环境中的 TWEETSMASH_API_KEY。
2. 阅读 references/api-reference.md，确认当前端点、必需的标头、速率限制和状态码。
3. 如果任务需要筛选书签或分页，请阅读 references/bookmarks-filters.md。

第 2 步：构造请求

1. 每个请求都使用 Authorization: Bearer $TWEETSMASH_API_KEY。
2. 此技能中的所有示例都使用 Content-Type: application/json。基础 URL 保持为 https://api.tweetsmash.com/v1。
3. 如果任务需要使用筛选条件获取书签，请执行 python3 <tweetsmash-api-dir>/scripts/build-bookmarks-url.py，并传入所需标志以生成正确编码的 URL。
4. 如果任务需要添加标签，请以 assets/add-labels-body.json 为基础，填入 tweet_ids，以及 label_id 或 label_name。
5. 如果任务需要移除标签，请以 assets/remove-labels-body.json 为基础，填入 tweet_ids 和 label_name。

第 3 步：调用正确的端点

1. 使用 GET /bookmarks 获取书签。如果存在筛选条件、搜索条件或游标，请使用 scripts/build-bookmarks-url.py 生成的 URL。
2. 如果任务需要当前标签 ID、标签名称或使用次数，请使用 GET /labels 列出标签。
3. 如果任务需要整理一个或多个已收藏的推文，请使用 POST /labels/add 添加标签。
4. 如果任务需要清理或重新分类已收藏的推文，请使用 POST /labels/remove 移除标签。
5. 可使用 cURL 快速执行；只有在确认端点和请求载荷后，才将相同请求转换为调用方运行环境所需的格式。

第 4 步：验证响应

1. 报告成功前，确认响应 JSON 包含 "status": true。
2. 读取书签时，如果涉及分页，请检查 meta.next_cursor、meta.limit 和 meta.total_count。
3. 修改标签时，确认成功消息与预期操作相符。
4. 如果任务依赖标签存在，而修改响应无法确认这一点，请调用 GET /labels 验证结果状态。

第 5 步：返回可用结果

1. 概述所用的请求方法、端点，以及实际使用的筛选条件或请求载荷字段。
2. 根据调用方要求的输出格式，返回响应正文或结构化摘要。
3. 如果可以继续分页，请提供 meta.next_cursor，以便后续请求从上一页继续。

错误处理

• 如果身份验证失败并返回 401，请确认 Bearer 令牌存在、非空，且来自正确的 TweetSmash 账户。
• 如果 API 返回 402，请停止操作，并说明当前套餐不允许访问所请求的 API。
• 如果 API 返回 429，请停止发送请求，并遵守 Retry-After 或当前速率限制标头的要求。随附的参考资料记录的是历史限制；请勿将其视为通用限制，也不要在短时间内连续重试。
• 如果手动构造书签查询较为困难，请重新运行 python3 <tweetsmash-api-dir>/scripts/build-bookmarks-url.py --help，然后重新构造 URL，而不要手动拼接查询字符串。
• 如果标签修改结果不明确，请先使用 GET /labels 列出标签，然后使用已确认的标签标识符或名称重新执行修改操作。