x-bookmarks

X 书签 v2

将 X/Twitter 书签从「善意的坟场」变成可执行的工作。

核心理念： 不要只做总结，还要提出 Agent 可以执行的行动建议。

数据源选择

此技能支持两种后端。选择第一个可用的：

1. bird CLI（优先使用）

• 速度快，无需 API 密钥，使用浏览器 Cookie
• 安装：npm install -g bird-cli
• 测试：bird whoami — 如果输出用户名，就可以使用

2. X API v2（备用）

• 无需 bird CLI 即可使用
• 需要 X Developer 账号和 OAuth 2.0 应用
• 设置方法：参见 references/auth-setup.md → “X API 设置”

自动检测逻辑

1. Check if `bird` command exists → try `bird whoami`
2. If bird works → use bird CLI path
3. If not → check for X API tokens (~/.config/x-bookmarks/tokens.json)
4. If tokens exist → use X API path (auto-refresh)
5. If neither → guide user through setup (offer both options)

获取书签

通过 bird CLI

# Latest 20 bookmarks (default)
bird bookmarks --json

# Specific count
bird bookmarks -n 50 --json

# All bookmarks (paginated)
bird bookmarks --all --json

# With thread context
bird bookmarks --include-parent --thread-meta --json

# With Chrome cookie auth
bird --chrome-profile "Default" bookmarks --json

# With manual tokens
bird --auth-token "$AUTH_TOKEN" --ct0 "$CT0" bookmarks --json

如果用户有 .env.bird 文件或 AUTH_TOKEN/CT0 环境变量，请先加载：source .env.bird

通过 X API v2

# First-time setup (opens browser for OAuth)
python3 scripts/x_api_auth.py --client-id "YOUR_CLIENT_ID" --client-secret "YOUR_SECRET"

# Fetch bookmarks (auto-refreshes token)
python3 scripts/fetch_bookmarks_api.py -n 20

# All bookmarks
python3 scripts/fetch_bookmarks_api.py --all

# Since a specific tweet
python3 scripts/fetch_bookmarks_api.py --since-id "1234567890"

# Pretty print
python3 scripts/fetch_bookmarks_api.py -n 50 --pretty

API 脚本输出的 JSON 格式与 bird CLI 相同，因此所有下游工作流都能以相同方式运行。

**令牌管理是自动的：**令牌存储在 ~/.config/x-bookmarks/tokens.json 中，并通过已保存的 refresh_token 刷新。如果刷新失败，Agent 应引导用户重新运行 x_api_auth.py。

环境变量覆盖

如果用户已有 Bearer 令牌（例如来自其他工具），可以跳过 OAuth 流程：

X_API_BEARER_TOKEN="your_token" python3 scripts/fetch_bookmarks_api.py -n 20

JSON 输出格式（两个后端均适用）

每个书签返回：

{
  "id": "tweet_id",
  "text": "tweet content",
  "createdAt": "2026-02-11T01:00:06.000Z",
  "replyCount": 46,
  "retweetCount": 60,
  "likeCount": 801,
  "bookmarkCount": 12,
  "viewCount": 50000,
  "author": { "username": "handle", "name": "Display Name" },
  "media": [{ "type": "photo|video", "url": "..." }],
  "quotedTweet": { "id": "..." }
}

核心工作流

1. 行动优先的摘要（主要用途）

关键差异化特点：不要只做总结，还要提出 Agent 可以执行的行动建议。

1. 获取书签（自动检测使用 bird 或 API）
2. 按主题解析并分类（自动检测：加密货币、AI、营销、工具、个人等）
3. 针对每个类别提出具体行动建议：
   • 工具/代码库书签 → “我可以测试、设置或分析这项内容”
   • 策略/建议书签 → “以下是提取出的可执行步骤——需要我帮你落实其中某项吗？”
   • 新闻/趋势 → “这与你的工作相关。以下是可用于内容创作的切入点”
   • 内容创意 → “用你的风格创作一条推文或视频会很合适。以下是草稿”
   • 问题/讨论 → “我可以深入研究并为你总结”
4. 标记过时书签（超过 2 周）——“现在使用，否则就会忘掉”
5. 按类别整理摘要并附上行动建议

输出格式如下：

📂 CATEGORY (count)
• Bookmark summary (@author)
→ 🤖 I CAN: [specific action the agent can take]

2. 定期摘要（Cron）

设置定期书签检查。向用户推荐以下 cron 配置：

Schedule: daily or weekly
Payload: "Check my X bookmarks for new saves since last check.
  Fetch bookmarks, compare against last digest, summarize only NEW ones.
  Categorize and propose actions. Deliver to me."

通过保存最近处理的书签 ID 来跟踪状态。在工作区中存储： memory/bookmark-state.json → { "lastSeenId": "...", "lastDigestAt": "..." }

3. 内容再利用

用户要求根据书签生成内容创意时：

1. 获取近期书签
2. 找出互动量较高的推文（点赞数 >500），其中包含框架、技巧或见解
3. 用用户的风格改写核心观点（如果有可用的风格数据）
4. 根据书签原始互动情况建议发布时间

4. 模式检测

当用户有足够的书签历史记录时：

1. 获取所有书签（--all）
2. 按主题/关键词聚类
3. 报告：“你收藏了 N 条关于[主题]的推文。要我深入研究吗？”
4. 根据模式推荐研究报告、系列内容或工具

5. 书签清理

清理过时书签时：

1. 找出超过某个时间阈值的书签（默认：30 天）
2. 对每条书签提取 TL;DR 和一条可执行的要点
3. 提示：“今天就落实，或者清除它”
4. 用户可以通过以下命令取消收藏：bird unbookmark <tweet-id>（仅限 bird）

错误处理

错误	原因	解决方法
bird: command not found	未安装 bird CLI	改用 X API，或运行 npm i -g bird-cli
"No Twitter cookies found"	未在浏览器中登录 X	在 Chrome/Firefox 中登录 x.com，或使用 X API
Safari Cookie 出现 EPERM	macOS 权限问题	改用 Chrome/Firefox 或 X API
结果为空	Cookie/令牌已过期	重新登录或重新运行 x_api_auth.py
速率限制（429）	API 请求过多	等待后重试，使用 --count 限制数量
"No X API token found"	尚未运行身份验证设置	运行 x_api_auth.py --client-id YOUR_ID
令牌刷新失败	刷新令牌已过期	重新运行 x_api_auth.py 以重新授权

提示

• 快速生成摘要时从 -n 20 开始，深入分析时使用 --all
• bird：对回复使用 --include-parent 获取线程上下文
• API：包含 bookmarkCount 和 viewCount（bird 可能不包含）
• bird 支持通过 --folder-id <id> 指定书签文件夹
• 两种后端输出的 JSON 相同，工作流不受后端影响