史矛革 🐉

将你的 Twitter/X 书签（和/或可选的点赞）自动归档为 Markdown 格式。

就像龙守护着宝藏一样，史矛革会收集你收藏的珍贵内容和点赞。

多模型支持： 史矛革支持 Claude Code（默认）和 OpenCode，让你可以使用多种 AI 模型。不同模型的结果可能会有所差异——请仔细测试并找到最适合你工作流程的模型。设置详情请参阅 AI CLI 集成。

目录

• 快速入门
• 获取 Twitter 凭证
• 它能做什么
• 运行
• 分类
• 自动化
• 输出
• 配置
• AI CLI 集成
• 故障排除
• 致谢

  🔥  🔥  🔥  🔥  🔥  🔥  🔥  🔥  🔥  🔥  🔥  🔥
       _____ __  __   _   _   _  ____
      / ____|  \/  | / \ | | | |/ ___|
      \___ \| |\/| |/ _ \| | | | |  _
       ___) | |  | / ___ \ |_| | |_| |
      |____/|_|  |_/_/  \_\___/ \____|

   🐉 龙苏醒了……又有宝藏等着被收藏！

快速入门（5 分钟）

# 1. 安装 bird CLI（Twitter API 封装工具）
# 安装说明见 https://github.com/steipete/bird

# 2. 克隆并安装史矛革
git clone https://github.com/alexknowshtml/smaug
cd smaug
npm install

# 3. 运行设置向导
npx smaug setup

# 4. 运行完整任务（抓取 + 使用 Claude 处理）
npx smaug run

设置向导将完成以下操作：

• 创建必要的目录
• 引导你获取 Twitter 凭证
• 创建你的配置文件

手动获取 Twitter 凭证

史矛革使用 bird CLI，而 bird CLI 需要你的 Twitter 会话 Cookie。

如果你不想使用向导来简化流程，也可以手动将会话信息填入配置文件。

1. 复制示例配置文件：

   cp smaug.config.example.json smaug.config.json
   

2. 在浏览器中打开 Twitter/X
3. 打开开发者工具 → 应用程序 → Cookies
4. 找到并复制以下值：
   • auth_token
   • ct0
5. 将它们添加到你的 smaug.config.json 中：

{
  "twitter": {
    "authToken": "your_auth_token_here",
    "ct0": "your_ct0_here"
  }
}

注意： smaug.config.json 已被 .gitignore 忽略，以防止意外提交凭证。取而代之的是跟踪示例文件。

史矛革的实际功能

1. 从 Twitter/X 抓取书签，使用 bird CLI（也可同时抓取点赞，或两者兼抓）
2. 展开 t.co 链接，揭示真实 URL
3. 提取链接页面的内容：
   • GitHub 仓库（通过 API 获取星标数、描述、README）
   • 外部文章（标题、作者、内容）
   • X/Twitter 长文（通过 bird CLI 提取全文）
   • 引用推文和回复线程（完整上下文）
4. 调用 Claude Code 来分析并分类每条推文
5. 保存为 Markdown 文件，按日期整理，并附带丰富上下文
6. 归档到知识库：GitHub 仓库存入 knowledge/tools/，文章存入 knowledge/articles/

手动运行

# 完整任务（抓取 + 使用 Claude 处理）
npx smaug run

# 默认抓取书签
npx smaug fetch 20

# 抓取所有书签（分页加载，需使用 git 版本的 bird CLI）
npx smaug fetch --all
npx smaug fetch --all --max-pages 5  # 限制为 5 页

# 改为抓取点赞
npx smaug fetch --source likes

# 同时抓取书签和点赞
npx smaug fetch --source both

# 处理已抓取的推文
npx smaug process

# 强制重新处理（忽略重复项）
npx smaug process --force

# 检查待处理的任务
node -e "console.log(require('./.state/pending-bookmarks.json').count)"

抓取所有书签

默认情况下，Twitter 的 API 每次请求会返回约 50–70 条书签。若需抓取更多，可使用 --all 标志启用分页功能：

npx smaug fetch --all              # 抓取全部（最多 10 页）
npx smaug fetch --all --max-pages 20  # 抓取最多 20 页

注意： 这需要使用从 git 构建的 bird CLI（而非 npm 发布版本）。安装说明请参阅 故障排除。

费用提示： 处理大量书签可能会消耗大量 Claude Token。每个包含复杂内容的书签（如长篇文章、GitHub README 等）都会增加上下文长度。建议分批处理以控制成本：

npx smaug run --limit 50 -t    # 每次处理 50 条，并跟踪 Token 使用情况

使用 -t 标志可监控用量。不同模型的成本估算请参阅 Token 使用追踪。

分类

分类定义了不同类型书签的处理方式。史矛革提供了合理的默认分类，但你可以在 smaug.config.json 中自定义它们。

默认分类

分类	匹配条件	动作	归档位置
github	github.com	存档	./knowledge/tools/
article	medium.com, substack.com, dev.to, 博客等	存档	./knowledge/articles/
x-article	x.com/i/article/*	存档	./knowledge/articles/
tweet	（备用）	记录	仅保存到 bookmarks.md

🔜 注意：转录功能已标记，但尚未自动化。欢迎提交 PR！

X/Twitter 长文

X 文章（x.com/i/article/*）是 Twitter 原生的长文格式。史矛革会使用 bird CLI 提取完整的文章内容：

1. 直接提取：如果书签中的推文是文章作者的原创帖子，则直接提取内容。
2. 搜索回退：如果你书签的是他人分享或引用的文章，史矛革会搜索原始作者的推文，并从中提取完整内容。
3. 元数据回退：如果搜索失败，则记录基本元数据（标题、描述）。

示例 X 文章书签：

## @joaomdmoura - 从 20 亿个智能体工作流中学到的经验
> [完整文章内容已提取]

- **推文：** https://x.com/joaomdmoura/status/123456789
- **链接：** https://x.com/i/article/987654321
- **归档：** [lessons-from-2-billion-agentic-workflows.md](./knowledge/articles/lessons-from-2-billion-agentic-workflows.md)
- **内容：** 深入探讨将 CrewAI 扩展到数十亿次智能体执行过程中所发现的模式。

动作

• 存档：创建带有丰富元数据的独立 Markdown 文件
• 记录：仅添加到 bookmarks.md，不另建文件
• 转录：标记以供未来转录 (自动转录功能即将推出！欢迎提交 PR)

自定义分类

在 smaug.config.json 中添加您自己的分类：

{
  "categories": {
    "research": {
      "match": ["arxiv.org", "papers.", "scholar.google"],
      "action": "file",
      "folder": "./knowledge/research",
      "template": "article",
      "description": "学术论文"
    },
    "newsletter": {
      "match": ["buttondown.email", "beehiiv.com"],
      "action": "file",
      "folder": "./knowledge/newsletters",
      "template": "article",
      "description": "新闻通讯期刊"
    }
  }
}

您的自定义分类会与默认分类合并。要覆盖某个默认分类，只需使用相同的键（例如 github、article）。

书签文件夹

如果您已将 Twitter 书签组织到文件夹中，Smaug 可以将这种组织方式保留为标签。通过配置文件夹 ID 到标签名称的映射来实现：

{
  "folders": {
    "1234567890": "ai-tools",
    "0987654321": "articles-to-read",
    "1122334455": "research"
  }
}

如何找到文件夹 ID：

1. 打开 Twitter/X 并进入您的书签。
2. 点击一个文件夹。
3. URL 将显示为 https://x.com/i/bookmarks/1234567890，其中的数字即为文件夹 ID。

当文件夹配置完成后：

• Smaug 会分别从每个文件夹中抓取数据。
• 每个书签都会被标记为其所属的文件夹名称。
• 标签会出现在 bookmarks.md 条目和知识文件的 frontmatter 中。

注意： Twitter 的 API 在一次性获取所有书签时不会返回文件夹归属信息，因此 Smaug 必须单独逐个文件夹进行抓取。

自动化

每 30 分钟自动运行一次 Smaug：

选项 A：PM2（推荐）

npm install -g pm2
pm2 start "npx smaug run" --cron "*/30 * * * *" --name smaug
pm2 save
pm2 startup    # 开机启动

选项 B：Cron

crontab -e
# 添加：
*/30 * * * * cd /path/to/smaug && npx smaug run >> smaug.log 2>&1

选项 C：systemd

# 创建 /etc/systemd/system/smaug.service
# 详情请参阅 docs/systemd-setup.md

输出

bookmarks.md

您的书签按日期整理：

# 2026年1月2日 星期四

## @simonw - Gist Host Fork for Rendering GitHub Gists
> 我分叉了优秀的 gistpreview.github.io，创建了 gisthost.github.io

- **推文:** https://x.com/simonw/status/123456789
- **链接:** https://gisthost.github.io/
- **归档:** [gisthost-gist-rendering.md](./knowledge/articles/gisthost-gist-rendering.md)
- **内容:** 一款免费的 GitHub Pages 托管工具，用于渲染来自 Gist 的 HTML 文件。

---

## @tom_doerr - Whisper-Flow 实时转录
> 这太棒了——使用 Whisper 实现实时转录

- **推文:** https://x.com/tom_doerr/status/987654321
- **链接:** https://github.com/dimastatz/whisper-flow
- **归档:** [whisper-flow.md](./knowledge/tools/whisper-flow.md)
- **内容:** 使用 OpenAI Whisper 并支持流式传输的实时语音转文字工具。

knowledge/tools/*.md

GitHub 仓库会生成各自的文件：

---
title: "whisper-flow"
type: tool
date_added: 2026-01-02
source: "https://github.com/dimastatz/whisper-flow"
tags: [ai, transcription, whisper, streaming]
via: "Twitter bookmark from @tom_doerr"
---

使用 OpenAI Whisper 进行实时语音转文字转录……

## 主要特性
- 流式音频输入
- 多语言支持
- 低延迟输出

## 链接
- [GitHub](https://github.com/dimastatz/whisper-flow)
- [原始推文](https://x.com/tom_doerr/status/987654321)

配置

复制示例配置并进行自定义：

cp smaug.config.example.json smaug.config.json

示例 smaug.config.json：

{
  "source": "bookmarks",
  "archiveFile": "./bookmarks.md",
  "pendingFile": "./.state/pending-bookmarks.json",
  "stateFile": "./.state/bookmarks-state.json",
  "timezone": "America/New_York",
  "twitter": {
    "authToken": "your_auth_token",
    "ct0": "your_ct0"
  },
  "autoInvokeClaude": true,
  "claudeModel": "sonnet",
  "claudeTimeout": 900000,
  "allowedTools": "Read,Write,Edit,Glob,Grep,Bash,Task,TodoWrite",
  "webhookUrl": null,
  "webhookType": "discord"
}

选项	默认值	描述
source	bookmarks	要抓取的内容：bookmarks（默认）、likes 或 both
includeMedia	false	实验性：包含媒体附件（照片、视频、GIF）
archiveFile	./bookmarks.md	主归档文件
timezone	America/New_York	用于日期格式化
cliTool	claude	要使用的 AI CLI：claude 或 opencode
autoInvokeClaude	true	自动运行 Claude Code 进行分析
claudeModel	sonnet	要使用的模型（sonnet、haiku 或 opus）
autoInvokeOpencode	true	自动运行 OpenCode 进行分析
opencodeModel	opencode/glm-4.7-free	OpenCode 模型（详见 OpenCode 文档）
claudeTimeout	900000	最大处理时间（15 分钟）
parallelThreshold	8	同时处理的最小书签数量
webhookUrl	null	用于通知的 Discord/Slack webhook

环境变量同样适用：AUTH_TOKEN、CT0、SOURCE、INCLUDE_MEDIA、ARCHIVE_FILE、TIMEZONE、CLI_TOOL、CLAUDE_MODEL、OPENCODE_MODEL 等。

实验性：媒体附件

媒体提取功能（照片、视频、GIF）目前可用，但默认关闭。要启用：

# 一次性使用标志
npx smaug fetch --media

# 或在配置中
{
  "includeMedia": true
}

启用后，media[] 数组会包含在待处理的 JSON 中，内容包括：

• type: “photo”、“video” 或 “animated_gif”
• url: 媒体全尺寸链接
• previewUrl: 缩略图（更小、加载更快）
• width、height: 尺寸
• videoUrl、durationMs: 仅适用于视频

⚠️ 为什么是实验性？

1. 需要支持媒体的 bird 版本 —— PR #14 添加了媒体提取功能。在合并之前，您需要使用包含此 PR 的分支，或等待上游发布。否则，--media 将不起作用（数组为空）。
2. 工作流程仍在完善中 —— 短截屏（< 30 秒）不需要转录，但较长的视频可能需要。我们仍在探索最佳处理方式。

AI CLI 集成

Smaug 支持多种 AI CLI 工具，用于智能处理书签：

• Claude Code（默认）— Anthropic 的 Claude CLI
• OpenCode — 另一种支持多种模型的 AI CLI

使用 OpenCode（替代 Claude）

要使用 OpenCode 替代 Claude Code：

{
  "cliTool": "opencode",
  "opencodeModel": "opencode/glm-4.7-free",
  "autoInvokeOpencode": true
}

可用的 OpenCode 模型包括：

• opencode/glm-4.7-free（免费版）
• opencode/kimi-k2.5-free（免费版）
• opencode/claude-sonnet-4.5（通过 OpenCode 使用 Claude）
• opencode/gpt-5.2（通过 OpenCode 使用 GPT）

可通过环境变量设置：

export CLI_TOOL=opencode
export OPENCODE_MODEL=opencode/kimi-k2.5-free

Claude Code 集成

Smaug 默认使用 Claude Code 进行智能书签处理。.claude/commands/process-bookmarks.md 文件包含以下说明：

• 生成描述性标题（而非通用的“文章”或“推文”）
• 将 GitHub 仓库归档到 knowledge/tools/
• 将文章归档到 knowledge/articles/
• 处理带有完整上下文的引用推文
• 处理带有父级上下文的回复线程
• 对大批量书签进行并行处理（可配置阈值，默认为 8 个书签）

你也可以手动运行处理命令：

claude
> Run /process-bookmarks

Token 使用跟踪

使用 -t 标志跟踪 API 费用：

npx smaug run -t
# 或
npx smaug run --track-tokens

每次运行结束时，都会显示如下细分信息：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 TOKEN 使用情况
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
主模型 (sonnet):
  输入：               85 tokens  <$0.01
  输出：           5,327 tokens  $0.08
  缓存读取：     724,991 tokens  $0.22
  缓存写入：     62,233 tokens  $0.23

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💰 总费用：$0.53
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

成本优化：Haiku 子代理

对于大批量书签（默认 8 个及以上），Smaug 会启动并行子代理。默认情况下，这些子代理使用 Haiku 模型而非 Sonnet 模型，从而将成本几乎降低一半：

配置	20 个书签	时间
Sonnet 子代理	$1.00	4 分 12 秒
Haiku 子代理	$0.53	4 分 18 秒

速度相同，但成本降低了约 50%。由于分类和归档任务并不需要 Sonnet 级别的推理能力，因此 Haiku 模型完全可以胜任。

这一设置在 .claude/commands/process-bookmarks.md 中通过在 Task 调用中添加 model="haiku" 来配置。

故障排除

“没有新的书签需要处理”

这意味着以下两种情况之一：

1. 未成功获取任何书签（请检查 bird CLI 的凭据）
2. 所有已获取的书签已存在于 bookmarks.md 中

若要从头开始，请执行以下操作：

rm -rf .state/ bookmarks.md knowledge/
mkdir -p .state knowledge/tools knowledge/articles
npx smaug run

bird CLI 出现 403 错误

你的 Twitter Cookie 可能已过期。请从浏览器中获取新的 Cookie。

处理速度较慢

• 在配置中尝试使用 haiku 模型代替 sonnet，以获得更快但略显粗糙的处理效果
• 确保未使用 --force 参数重复处理（这会导致编辑而非追加内容）

仅获取了约 50–70 个书签

npm 发布的 bird CLI（v0.5.1）不支持分页功能。要获取所有书签，请从 Git 安装 bird：

# 克隆并构建 bird 源代码
cd /tmp
git clone https://github.com/steipete/bird.git
cd bird
pnpm install    # 或：npm install -g pnpm && pnpm install
pnpm run build:dist

# 全局链接（可能需要 sudo 或 --force）
npm link --force

# 验证
bird --version  # 应显示更新的提交哈希
bird bookmarks --help  # 应显示 --all 标志

然后使用 npx smaug fetch --all 来启用分页功能，获取所有书签。

致谢

• bird CLI 由 Peter Steinberger 开发
• 基于 Claude Code 构建

许可证

MIT

Smaug 快速上手指南

Smaug 是一个自动化工具，能将你的 Twitter/X 书签（及点赞）归档为结构化的 Markdown 文件。它利用 AI（默认 Claude Code 或 OpenCode）分析链接内容，提取关键信息并分类存储到本地知识库。

环境准备

在开始之前，请确保满足以下系统要求和前置依赖：

• Node.js: 需安装 Node.js (推荐 v18+) 以运行 npm 包。
• Git: 用于克隆仓库。
• Bird CLI: Smaug 依赖 bird 作为 Twitter API 的封装层。
  • 注意：若要获取全部书签（分页拉取），建议从源码构建 bird，而非仅使用 npm 发布版。
• AI CLI:
  • Claude Code (默认): 需安装并配置好 Anthropic API Key。
  • OpenCode (可选): 如需使用其他模型，可安装 OpenCode。
• Twitter/X 账号: 需要有效的账号以获取会话凭证。

安装步骤

1. 安装 Bird CLI

首先安装核心依赖 bird。请参考其官方仓库进行安装：

# 访问 https://github.com/steipete/bird 获取安装指令
# 通常涉及克隆仓库并构建二进制文件

2. 克隆并安装 Smaug

git clone https://github.com/alexknowshtml/smaug
cd smaug
npm install

3. 初始化配置

运行设置向导，它将自动创建所需目录并引导你完成配置：

npx smaug setup

向导会提示你输入 Twitter 凭证。若选择手动配置，请参阅下文“获取 Twitter 凭证”部分。

4. 获取 Twitter 凭证 (手动方式)

如果未使用向导，需手动将 Twitter 会话 Cookie 填入配置文件：

1. 复制示例配置：

   cp smaug.config.example.json smaug.config.json
   

2. 在浏览器打开 Twitter/X，按 F12 打开开发者工具。
3. 进入 Application (应用) -> Cookies -> https://x.com。
4. 找到并复制以下两个值：
   • auth_token
   • ct0
5. 编辑 smaug.config.json，填入凭证：

   {
     "twitter": {
       "authToken": "your_auth_token_here",
       "ct0": "your_ct0_here"
     }
   }
   

   安全提示: smaug.config.json 已被列入 .gitignore，请勿将其提交到公共仓库。

基本使用

运行完整流程

这是最常用的命令，它将执行“抓取书签 -> AI 分析内容 -> 生成 Markdown 归档”的全过程：

npx smaug run

常用操作命令

• 仅抓取书签 (默认抓取最近约 50-70 条):

  npx smaug fetch 20       # 抓取 20 条
  npx smaug fetch --all    # 抓取所有书签 (需分页支持)
  

• 仅处理已抓取的数据 (不重新联网抓取):

  npx smaug process
  

• 从点赞中抓取 (默认为书签):

  npx smaug fetch --source likes
  

• 批量处理以控制成本 (限制每次处理数量并监控 Token 消耗):

  npx smaug run --limit 50 -t
  

输出结果

运行成功后，你将得到：

1. bookmarks.md: 按日期排序的书签摘要列表。
2. knowledge/ 目录:
   • knowledge/tools/: GitHub 仓库等工具类链接的详细分析文件。
   • knowledge/articles/: 文章、长推文等内容的详细归档。

自动化运行 (可选)

若需每 30 分钟自动同步一次，推荐使用 PM2：

npm install -g pm2
pm2 start "npx smaug run" --cron "*/30 * * * *" --name smaug
pm2 save
pm2 startup