XArc

搜索你的 X 归档，数据只留在本地。

English

XArc 是一款本地命令行工具，可以浏览、检索和导出 X（原 Twitter）归档。它会为帖子、Note Tweet 和 Article 建立 SQLite 索引，还能按时间线浏览帖子、查看上下文和查找媒体文件。源归档不会被改动，也不会另存副本。

当前版本不联网，运行时没有第三方依赖。

运行环境

• Linux 或 WSL（暂不支持原生 Windows）
• Python 3.11 或更高版本
• Python 自带的 SQLite 需要支持 FTS5

索引发布和只读保护用到了 fcntl，因此需要 Linux 环境。

请先解压 X 归档。配置中的 archive 应指向解压后的归档根目录，即直接包含 data/ 的目录；不要填写 data/ 本身。

从源码运行

下载或克隆源码后，进入项目目录：

cd xarc

cp config.example.json config.local.json
# 编辑 config.local.json，把 archive 改成归档根目录。
python3 -m xarc_cli build
python3 -m xarc_cli stats

也可以在构建时直接传路径：

ARCHIVE_PATH='/path/to/archive'
python3 -m xarc_cli build --archive "$ARCHIVE_PATH"

config.local.json 和 var/ 下生成的数据库、报表与导出文件都已加入 Git 忽略规则。生成的数据库权限固定为仅所有者可读（0400）；如果最终数据库路径是符号链接，build 会拒绝覆盖。

可编辑安装

开发时可以装到虚拟环境里，这样就能直接使用 xarc：

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --editable .
xarc --help

下面的示例都使用 xarc。不安装也没关系，把它换成 python3 -m xarc_cli 即可。

常用命令

先构建索引：

xarc build --archive '/path/to/archive'
xarc stats --json

如果拥有多个 X 账号，每个账号需要构建一次。可以统一放到一个数据库里（多账号合并），也可以分别建库：

# 合并到同一个库（多账号）
xarc build --archive '/path/to/account-a' --db var/x-archive.sqlite3
xarc build --archive '/path/to/account-b' --db var/x-archive.sqlite3

# 或者分别建库
xarc build --archive '/path/to/account-a' --db var/x-archive-a.sqlite3
xarc build --archive '/path/to/account-b' --db var/x-archive-b.sqlite3

合并后，xarc stats 会显示每个账号的帖子数；search、timeline、export 等命令不加 --account 时默认跨所有账号搜索，加 --account 则只查该账号：

xarc accounts                    # 列出库中的账号
xarc search 'token 经济学'       # 搜所有账号
xarc search 'token 经济学' --account account_id_or_username  # 只搜指定账号
xarc timeline --account GetAskClaw --limit 20
xarc export search 'token 经济学' --account BlueBirdBack --format markdown

浏览时间线，再用返回的帖子 ID 查看内容和本地媒体：

xarc timeline --limit 20
POST_ID='<id-from-timeline>'
xarc post "$POST_ID" --thread --json
xarc media "$POST_ID" --json

时间线支持类型、日期和顺序筛选：

xarc timeline \
  --kind tweet --since 'YYYY-MM-DD' --until 'YYYY-MM-DD' \
  --order oldest --json

检索正文或文件名：

xarc search 'archive migration'
xarc search '供应链安全' --literal --json
xarc search 'image.png' --files

search 默认返回全部匹配结果。只想看前几条时，可以加上 --limit，例如 xarc search 'archive migration' --limit 20。

仓库还附带一个可选的 Hermes Agent 搜索展示 skill：结果不超过 1,000 字符时直接回复；超过后保存完整 Markdown，由 agent 返回摘要并附上文件。XArc 本身仍然只在本地运行，不负责调用 LLM。

检索结果和筛选后的时间线都可以导出为 Markdown、JSON 或 CSV：

xarc export search 'archive migration' --format markdown --limit 25
xarc export timeline --kind community --since 'YYYY-MM-DD' --format csv

export search 同样默认导出全部匹配结果；需要控制文件大小时再加 --limit。

默认导出目录是 var/exports/。已有文件不会被覆盖，除非加上 --force。任何指向源归档内部的导出路径都会被拒绝。

检查本地配置和索引状态：

xarc doctor --json

doctor 会核对当前归档与数据库记录的索引来源。已知数据集结构损坏时，build 会给出明确错误，并保留原有的数据库、摘要和文件清单。

articles 命令可浏览 Note Tweet 和 Article：

xarc articles --limit 20 --json

检索范围

目前只支持词法检索：默认使用 SQLite FTS5，--literal 可直接按子串查找，其中 % 和 _ 都是普通字符。语义检索和混合检索尚未实现，规划见多语言混合检索计划。

post --thread 只会从本地索引中查找父帖、回复、引用帖和其他编辑版本，不会连接 X 或其他服务补全内容。

隐私边界

XArc 会记录归档内所有文件的路径、大小等基本信息，但正文索引和导出仅包含：

• 普通帖子、Community 帖子和已删除帖子
• Note Tweet
• Article

私信、联系人、账号安全数据和 Grok 对话只记录文件路径和基本信息，不索引正文，也不会出现在导出结果中。

数据库、摘要、文件清单、导出内容和本地配置都可能包含私人信息。不要提交到 Git，也不要直接附在公开问题里。构建和导出路径如果落在源归档内，即使经过符号链接，也会被拒绝。

兼容入口

旧入口仍然可用，并统一调用 xarc_cli，没有重复实现：

askclaw-x-archive --help
python3 -m askclaw_x_archive --help
python3 -m x_archive_index --help

新脚本和文档请使用 xarc 或 python3 -m xarc_cli。

这些旧名称只在公开发布前的开发版本中使用过，askclaw-x-archive 从未发布到 PyPI，无需迁移或卸载旧发行包。

开发与开源

测试会在临时目录中生成模拟归档，无需真实数据，也不得将真实归档用作测试数据。

python3 -m unittest discover -s tests -v
python3 -m compileall -q xarc_cli askclaw_x_archive x_archive_index tests skills
python3 -m xarc_cli --help
python3 -m askclaw_x_archive --help
python3 -m x_archive_index --help
git diff --check

构建源码包和 wheel：

uv build

XArc 采用 MIT 许可证 开源。提交代码前请看参与贡献；报告安全问题前请看安全说明，不要附带私人归档或本地配置。