企业官网建设流程全解析

birdclaw 是一款开源的 local-first 工具,它能把你的整个 Twitter/X 历史档案导入本地 SQLite 数据库,从此离线、即时地搜索每一条发过的推文、私信和收藏,数据完全由你自己掌控,不依赖任何云端服务。本文带你从零上手:一分钟安装 birdclaw、导入推特存档、用 FTS5 全文索引秒搜历史推文,并体验配套的本地 Web 应用与 AI agent 接入。🪶

birdclaw 是什么?为什么值得本地存一份推特历史

Twitter 的搜索功能众所周知"随缘"——想找三年前发过的一条推文、某年收藏过的某个链接,经常一无所获。birdclaw 的思路很简单:

Your Twitter, in a SQLite file.

它把推特档案一次性导入本地,再为搜索、浏览、备份提供三种"表面":

• 本地 Web 应用—— 自己的时间线、Mentions、Likes、Bookmarks、DMs、Inbox、Blocks,还能画出关注者地图(Map)
• CLI 命令行—— 搜索、同步、回复、批量拉黑,全部输出稳定的--json,方便脚本和 AI agent 消费
• 只读 MCP Server—— 让 AI agent 安全地检索你本地缓存的推文,不暴露 DM、不做任何实时 X 调用

核心设计只有三句话:

1. 一个 SQLite 数据库承载 tweets、DMs、likes、bookmarks、follows、blocks、mutes,多账号、FTS5 全文索引
2. 档案优先,直播感知—— 先导入官方存档确立账号身份,再用xurl按需同步增量数据
3. 离线读取零流量—— 本地搜索和浏览默认不触发任何网络请求

一键安装 birdclaw:最快上手路径

birdclaw 通过 Homebrew 或 npm 分发,无需单独安装 SQLite(它使用运行时内置的node:sqliteAPI)。

macOS / Linux 用户推荐 Homebrew:

brew install steipete/tap/birdclaw birdclaw --version

其他平台用 npm:

npm install -g birdclaw

安装完成后,不想马上折腾存档的话,可以先跑一个自带示例数据的 demo,零凭证、零网络体验完整功能:

birdclaw init --demo birdclaw serve

然后打开http://localhost:3000,就能看到装满示例推文、DM 和个人资料的本地时间线。demo 的输出还会提示接下来可以试哪些只读命令,非常适合新手熟悉界面。

安装细节、可选依赖(xurl、OPENAI_API_KEY)的说明见 docs/install.md 和 docs/quickstart.md。

导入推特存档:5 步把全部推文变成 SQLite 表

这是 birdclaw 最核心的工作流:

第 1 步,申请官方存档。登录 X,进入 设置与隐私 → 你的账号 → 下载你的数据存档,点击 Request archive。X 会排队导出并邮件通知你(官方提示可能要等几天),下载后得到一个形如twitter-YYYY-MM-DD-<hash>.zip的压缩文件,建议放进~/Downloads。

第 2 步,让 birdclaw 找到它。macOS 下支持 Spotlight 自动发现:

birdclaw archive find --json

第 3 步,执行导入:

birdclaw import archive ~/Downloads/twitter-archive.zip --json

这一条命令会把推文、点赞、书签、个人资料、DM、关注/粉丝关系、附带媒体文件全部写入规范 SQLite 表,并完成 FTS5 索引。

第 4 步,验证落库:

birdclaw db stats --json

第 5 步,立刻搜索试试:

birdclaw search tweets "ship local software" --limit 5 --json

导入过程有几个对新手很友好的特性:

• 幂等可重跑—— 同一个存档反复执行不会产生重复数据
• 合并安全—— 导入更新的存档时,默认保留本地独有的行(比如你后来 live 同步到的新点赞),不会误删
• 切片重导—— 用--select likes,bookmarks只刷新某一个过期切片,不动其他本地数据;想精确替换则加--restore
• 媒体本地化—— 存档里的图片、视频、GIF 会被解压到~/.birdclaw/media/originals/archive/,连视频的高清 mp4 变体 URL 都一并保存,离线也能播放

完整规则(删除墓碑、编辑历史、切片清单)在 docs/archive.md 中有详细说明。

离线秒搜:FTS5 全文索引如何索引你的全部推文

birdclaw 用 SQLite 的FTS5 全文索引分别对推文和私信建了两张虚拟表tweets_fts和dm_fts,定义在 src/lib/database-schema.ts。索引是增量维护的:存档导入、live 同步、回复写入都会同步更新,搜索永远即时返回,完全离线。

推文搜索支持丰富的过滤器:

# 关键词全文搜索 birdclaw search tweets "local-first" --json # 只搜点赞/收藏过的 birdclaw search tweets --liked --limit 20 --json birdclaw search tweets --bookmarked --hide-low-quality --since 2024-01-01 --limit 50 --json # 时间窗口 birdclaw search tweets --since 2020-01-01 --until 2021-01-01 --limit 200 --json # 指定作者 birdclaw search tweets "AI" --author @sam --limit 20 --json

常用旗标一览:--originals-only(排除转推)、--hide-low-quality(过滤纯表情/链接垃圾)、--list <名称>(限定某个 List)、--limit、--json。

DM 搜索同样走 FTS5,还叠加了发送者影响力维度:

birdclaw search dms "prototype" --min-followers 1000 --sort followers --json

如果索引漂移,跑一次birdclaw db vacuum --json即可重算 FTS5 影子表并回收空间。更多参数见 docs/search.md。

可选:接上 live 同步,保持数据新鲜

存档是"时间点快照"。如果你希望持续获取新数据,birdclaw 可以委托xurl做实时读写,采用缓存优先策略——重复读取不再消耗 API 配额:

birdclaw sync timeline --limit 100 --refresh --json birdclaw sync bookmarks --mode auto --limit 100 --refresh --json

注意顺序:先导入存档确立账号身份,再做 live 同步。--mode auto会优先尝试 xurl,失败时回退到已有的 bird 安装。没有 xurl/bird 也完全没关系——纯档案模式下的搜索、浏览、备份全部可用。同步的分页、游标、限流细节见 docs/sync.md。

本地 Web 应用:你的私人推特时间线

birdclaw serve

打开http://localhost:3000,birdclaw 的 Web 应用就起来了。它只监听 loopback 地址,专为"专注刷自己的历史"而设计:

默认页面包括:

• Home—— 不被主时间线干扰,安心上翻几年前的自己
• Mentions—— 带 replied/unreplied 过滤的回复队列
• Likes / Bookmarks—— 重温保存过的帖子
• DMs—— 按发送者粉丝数、简介、影响力分档分诊
• Inbox—— 启发式或 OpenAI 打分,把"可能重要"的事项浮到顶部
• Blocks—— 维护本地优先的账号级拉黑名单
• Map—— 按资料位置在地图上绘制你的关注者/关注网络

点击任意推文的Thread可展开存档中的整段对话;每个帖子都有Permalink(/tweets/<tweet-id>),刷新或新标签页打开都能精确定位,且永不调用 X 实时接口。

数据主权:Git 友好备份与 AI agent 接入

birdclaw 把"备份"做成了一个正经的一等公民:backup export会把 SQLite 里的规范表导出成确定性 JSONL 分片——推文按年分片、DM 按对话分片、大文件自动切成 48 MiB 以内的编号分片,全部可以git diff、git merge:

birdclaw backup export --repo ~/Projects/birdclaw-store --commit --push

在 docs/backup.md 的设计里,备份仓库是"长期版本化记录",而本地 SQLite 只是从它构建出来的"快速索引"。

如果你用 AI agent 工作,birdclaw 还内置了一个只读 MCP server(端点/mcp):提供search_tweets和get_tweet_thread两个工具,只读本地缓存、不含 DM、不发起任何 X 调用,默认关闭,配置了专用 token 和 URL 才启用。安全边界见 docs/mcp.md。

小结:3 个命令拥有你的推特全史

所有数据落在~/.birdclaw(可用BIRDCLAW_HOME改根目录),搜索与浏览默认零网络流量;如果你只想托管一份只读存档,设置BIRDCLAW_DEPLOYMENT_READ_ONLY=1后再birdclaw serve即可。

项目核心模块位置:CLI 入口 src/cli.ts、架构与数据模型 docs/data-architecture.md、完整文档索引 docs/index.md。把推特历史握在自己手里,从这一条import archive开始。💾