如果这个项目对你有启发，也欢迎点个 Star。

GitHub：

```text

https://github.com/yuanrengu/xcrawler

```

你有没有遇到过这种情况：

想快速了解一个公开 X/Twitter 账号，于是打开主页，一条条往下翻。

看他最近在聊什么，长期关注什么话题，什么时候最活跃，内容偏技术还是偏生活，情绪状态有没有变化，经常提到哪些人和标签。

如果只是几十条内容，人工浏览还可以。

但如果样本变成几百条、几千条，而且里面混杂中文、英文、日文、韩文、缩写、网络梗、Hashtag 和各种专有名词，这件事就会迅速变得低效。

更重要的是，人工看完之后，得到的结论往往是这样的：

“这个人好像挺关注 AI。”

“这个账号应该偏技术内容。”

“他晚上比较活跃。”

“最近情绪好像有点负面。”

这些判断未必错。

但真正的问题是：

**证据在哪里？**

这些结论来自哪些具体推文？

能不能回溯？

能不能更新？

能不能把主观感觉变成结构化结果？

这就是我做 `xcrawler` 的原因。

---

不是再写一个爬虫，而是做一个可追溯的分析工具

`xcrawler` 是一个面向公开 X/Twitter 时间线的开源用户画像分析工具。

它可以把公开账号的时间线内容抓取下来，进行清洗、翻译、分析，并生成一份相对结构化、可复盘、可追溯的用户画像报告。

它不是单纯的“抓数据”。

也不是简单地把推文丢给大模型，然后让 AI 总结一句“这个人喜欢什么”。

我更想做的是：

> 把公开 X/Twitter 时间线，转化为有证据支撑的用户画像、兴趣地图和行为洞察。

目前它已经支持：

* 公开推文抓取

* 新推文与历史推文增量同步

* 多语言检测与翻译

* 兴趣画像分析

* 时间行为分析

* 情感趋势分析

* 生活事件信号检测

* Hashtag / Mention 网络分析

* 图表与 HTML 报告生成

* CSV 数据导出

* evidence tweet 证据追溯

* 本地缓存与多用户数据隔离

所以，我更愿意把它定义为一个：

**公开社交内容洞察工具。**

---

## 为什么这件事有价值？

公开社交内容里有大量信号。

一个人长期转发什么、反复讨论什么、经常使用哪些词、什么时候发内容、和哪些话题或账号产生连接，都在某种程度上反映了他的内容偏好、表达方式和社交参与路径。

但这些信号通常是碎片化的。

单条推文没有太多意义。

真正有价值的是长期样本里的重复模式。

比如：

一个账号是不是长期关注 AI？

它关注的是大模型应用，还是底层模型、Agent、工程化？

它的内容更偏研究、产品、投资，还是个人表达？

它在什么时间段最活跃？

它最近的内容方向有没有变化？

它经常提到哪些标签和账号？

它的内容情绪是稳定的，还是有明显波动？

这些问题，靠人工浏览也能判断。

但人工判断的问题是：慢、不稳定、难复盘。

`xcrawler` 想解决的，就是把这种“感觉”尽量变成结构化结果，并且保留证据。

---

它可以用在哪些场景？

我最初做这个项目，是为了更系统地理解公开账号长期输出的内容特征。

后来随着功能逐渐完善，我发现它可以用在很多场景。

比如：

**公开账号研究**

快速理解一个公开账号长期关注什么、表达什么、活跃节奏如何。

**创作者画像**

分析创作者的内容方向、兴趣标签、表达风格和潜在受众信号。

**内容策略分析**

观察某个领域里高频出现的话题、标签、情绪和发布时间节奏。

**品牌与竞品观察**

分析品牌账号、竞品账号或行业意见领袖的公开内容变化。

**受众洞察**

对一组公开账号进行分析，理解他们公开表达出来的兴趣、话题和行为信号。

**营销投放前的人群理解**

在内容策划、投放或合作前，先了解目标人群公开呈现出的兴趣结构。

**多语言内容整理**

对日语、英语、韩语、法语等多语言推文统一翻译，再进行后续分析。

**长期变化追踪**

通过增量抓取和运行记录，观察账号内容随着时间发生的变化。

当然，这里有一个非常重要的前提：

`xcrawler` 只适用于公开内容分析。

它不应该被用于骚扰、跟踪、人肉搜索、隐私挖掘、敏感身份判断，也不应该被用于违反平台规则或当地法律的场景。

工具越接近“人”的分析，边界就越重要。

---

xcrawler 具体能分析什么？


目前 `xcrawler` 主要包含几类能力。

---

## 1. 抓取公开推文，并支持增量同步

工具支持抓取指定公开账号的原创推文，并排除转发和回复。

除了首次抓取，也支持增量同步：

* 抓取比现有数据更新的推文

* 补全更早的历史推文

* 根据目标日期停止历史抓取

* 合并数据时自动去重

* 在 API 限流时尽量等待和恢复

这对于长期观察一个账号很重要。

因为真实使用中，我们很少希望每天全量重跑。更常见的需求是：

今天补一点新内容。

明天补一点历史缺口。

后天再更新一次分析报告。

所以增量抓取不是锦上添花，而是长期使用的基础能力。

---

## 2. 自动处理多语言内容

X/Twitter 上的内容经常是多语言混合的。

一个账号可能今天发英文，明天发日文，后天又发中文，中间还夹杂缩写、梗图、链接、标签和专有名词。

如果直接分析原文，后续聚类、画像和情感判断会变得很混乱。

所以 `xcrawler` 会先做文本清洗和语言检测，再把非中文内容翻译成中文，方便后续统一分析。

这里我特别做了几件事：

* 中文内容直接跳过翻译

* 已翻译文本写入缓存

* 后续运行不重复翻译

* 多条推文批量翻译，降低 LLM 调用次数

* 翻译失败会记录失败列表，方便重试

这对成本控制很关键。

因为只要涉及 LLM，工程上就必须考虑三个问题：**慢任务、失败恢复、成本可控。**

---

## 3. 生成兴趣画像，但尽量避免过度推断

兴趣画像是这个项目最核心的能力之一。


`xcrawler` 会尝试从长期内容中提取稳定兴趣，而不是根据单条推文做夸张推断。

它会关注：

* 反复出现的话题

* 长期出现的关键词

* 内容领域分布

* 核心兴趣与边缘兴趣

* 置信度

* 支撑结论的 tweet_id

我在 prompt 和输出结构里刻意加入了比较克制的原则：

* 不根据单条内容推断长期兴趣

* 不做人格、心理、价值观推断

* 证据不足时降低置信度

* 输出结构化 JSON

* evidence_tweet_ids 必须来自输入数据

也就是说，它不是让 AI “自由发挥”。

它更像是要求 AI 在明确边界内做归纳：

- 你可以总结，但要告诉我证据来自哪里。

- 你可以判断，但不要把不确定性包装成确定结论。

- 你可以分析公开内容，但不要跨过隐私和伦理边界。

这是我认为它区别于普通 AI 总结工具的地方。

---

4. 分析时间行为和活跃节奏

一个账号什么时候活跃，也是一种很有价值的行为信号。


`xcrawler` 会分析：

* 24 小时发推分布

* 工作日与周末活跃度

* 最活跃时段

* 最活跃星期

* 不同时间段的内容密度

* 作息和发布节奏特征

这些信息可以帮助我们理解一个账号的内容发布习惯。

比如：

- 她（他）是白天更活跃，还是晚上更活跃？

- 她（他）更像工作日输出，还是周末输出？

- 她（他）是稳定发布，还是阶段性爆发？

- 她（他）适合在什么时间窗口观察或互动？

这些不一定能直接得出强结论，但可以作为内容研究和账号观察的重要辅助信号。

---

## 5. 做情感趋势分析，但失败不伪装成成功

工具也支持对翻译后的推文做情感分类：

* positive

* neutral

* negative

* unknown

这里有一个小细节，我认为很重要：

如果某个 LLM 批次失败，结果不会被默认归为 `neutral`，而是标记为 `unknown`。

为什么？

因为失败不等于中性。

如果把失败数据默默算成 neutral，最后报告看起来会很平稳，但其实已经被污染了。

这类细节很容易被忽略，但它直接影响分析可信度。

在数据分析和 AI 工程里，有时候真正危险的不是失败，而是：

**失败了，却看起来像成功。**

---

6. 检测生活事件，但默认保持克制

`xcrawler` 也可以从公开推文中识别一些明确提到的生活事件，例如：

* 生日

* 感情状态

* 学业变化

* 职业变化

* 健康事件

* 旅行或搬家

* 重大购物

* 其他明确事件

但这部分我做得比较谨慎。

因为生活事件分析天然更接近隐私边界。

即使内容是公开发布的，也不意味着工具可以无限放大、聚合和推断。

所以项目默认对敏感生活事件做隐藏处理，HTML 报告中的证据原文也支持脱敏。

这不是形式主义，而是我认为这类工具必须具备的底线设计。

---

## 7. 分析 Hashtag / Mention 网络

除了文本内容，社交信号也很重要。

`xcrawler` 会统计：

* 高频 Hashtag

* 高频 Mention

* Hashtag 与 Mention 的共现关系

* Hashtag 柱状图

* Mention 柱状图

* 网络分析结果 JSON

这些信息可以帮助我们理解：

- 这个账号经常参与哪些话题？

- 它经常提到哪些账号？

- 它的内容更靠近哪个社交圈层？

- 某些话题和某些账号是否经常一起出现？

相比单纯看文本总结，Hashtag 和 Mention 更像是账号的“外部连接图谱”。

它能补充兴趣画像里看不到的社交关系信号。

---

## 8. 生成可视化报告和数据导出


最终，`xcrawler` 可以生成图表和 HTML 报告，包括：

* 24 小时发推分布图

* 星期分布图

* 语言分布图

* 兴趣标签图

* 情感趋势图

* 情感分布图

* Hashtag / Mention 图表

* HTML 汇总报告

* CSV 导出文件

更重要的是，报告里会尽量保留 evidence tweet。

也就是说，当报告说“这个账号关注 AI”时，你可以回头看到这个判断来自哪些具体推文。

这也是我做这个项目时一直坚持的原则：

> AI 分析不应该只给结论，还应该尽量保留证据链。

---

为什么我把它从脚本改造成开源工具？

最早的时候，`xcrawler` 其实只是几个脚本。

能跑，但不适合开源。

因为一个真正给别人用的开源项目，不能只满足“作者自己知道怎么运行”。

后来我开始逐步做工程化封装。

---

统一 CLI：让新用户不用理解一堆脚本

现在项目推荐使用统一命令入口：

```bash

xcrawler fetch

xcrawler fetch-more

xcrawler translate

xcrawler analyze interest

xcrawler analyze behavior

xcrawler analyze sentiment

xcrawler analyze network

xcrawler report

xcrawler export csv

```

这样新用户不需要先理解每个 Python 脚本之间的调用关系。

他只需要知道：

- 我要抓取。

- 我要翻译。

- 我要分析兴趣。

- 我要生成报告。

- 我要导出数据。

CLI 就应该围绕用户任务来组织，而不是围绕作者的脚本习惯来组织。

---

配置管理：让项目更容易复用

项目通过 `.env` 管理配置，例如：

```bash

X_BEARER_TOKEN=your_x_bearer_token

DEEPSEEK_API_KEY=your_deepseek_api_key

TARGET_USERNAME=MiracleHe

TIMEZONE_OFFSET=8

```

也支持 CLI 参数覆盖 `.env`：

```bash

xcrawler fetch -u some_user --pages 3

```

这样既适合固定分析一个账号，也适合临时切换目标用户。

---

## 多用户缓存隔离：避免数据互相覆盖

不同用户的数据会按用户名保存：

```bash

cache/{username}_raw_tweets.json

cache/{username}_translated.json

cache/{username}_interest_profile.json

cache/{username}_behavior.json

cache/{username}_sentiment.json

cache/{username}_network.json

```

这样多个账号可以并行分析，不会互相覆盖。

这看起来只是文件命名问题，但对于真正长期使用来说非常关键。

因为只要涉及多账号、多次运行、多版本结果，数据隔离就是基础设施。

---

执行计划和参数校验：让慢任务更可控

这类项目天然会遇到慢任务。

因为它涉及：

* X API 抓取

* 多语言翻译

* embedding 模型

* KMeans 聚类

* LLM 分析

* 图表生成

* HTML 报告生成

所以我加入了参数校验和执行计划。

例如：

* `pages >= 1`

* `batch-size >= 1`

* `top >= 1`

* `0 <= temperature <= 2`

一些任务在启动前也会显示执行计划，例如预计抓取页数、最多推文数、翻译批次数、是否会调用 LLM 等。

这能避免一种很糟糕的体验：

命令一运行，用户完全不知道接下来会发生什么，也不知道会不会调用大量 token。

慢任务并不可怕。

可怕的是慢任务不透明。

---

## 运行记录：让每次分析都能复盘

项目会记录分析运行元数据，包括：

* 用户名

* 分析类型

* 模型

* 参数

* 输入范围

* 开始时间

* 结束时间

* 运行状态

* 耗时

* LLM 调用次数

* token 用量

* 失败批次

这些记录会写入 `analysis_runs.json`。

这样你可以回头知道：

- 这次分析用了什么模型？

- 分析了多少内容？

- 有没有失败？

- 花了多少 token？

- 结果是不是部分成功？

- 下次要不要缩小输入规模？

对个人项目来说，这可能不是第一眼最酷的功能。

但对长期使用来说，它非常重要。

因为可复盘，才有可能持续优化。

---

## 测试和 CI：避免项目只在作者电脑上能跑

项目目前包含 94 个单元测试，覆盖了很多关键路径：

* 文本清洗

* 语言检测

* 翻译缓存

* 批量翻译响应解析

* X API mock

* CLI 参数解析与校验

* evidence 校验

* 隐私保护

* LLM Provider

* analysis run

* 情感分析失败处理

* JSON Store

* CSV 导出

* HTML 报告证据区

* 敏感证据隐藏

同时项目也接入了 GitHub Actions。

这并不代表项目已经完美。

但至少它已经不再是“只能在我电脑上跑”的状态。

我希望它逐步变成一个真正可维护、可复用、可协作的开源项目。

---

## 慢任务和成本，我是怎么处理的？

这个项目会遇到两个现实问题：

第一，慢。

第二，贵。

所以我做了几类优化。

---

1. 增量抓取，避免每天全量重跑

```bash

xcrawler fetch-more --pages 3

```

只补充新增内容和历史缺口，而不是每次从头开始。

---

2. 翻译缓存，避免重复调用 LLM

已经翻译过的内容会写入缓存。

下次再跑时，不会重复翻译同一条文本。

---

3. 批量翻译，减少 API 调用次数

多条推文可以合并为一次 LLM 调用。

这比逐条翻译更适合批处理场景。

---

4. 控制抓取规模

```bash

xcrawler fetch --pages 3

```

先小规模验证配置，再决定是否扩大抓取范围。

---

5. 控制分析输入规模

```bash

xcrawler analyze interest --limit 300

```

对专业兴趣分析设置输入上限，避免一次性把过多内容丢给模型。

---

6. 失败不伪装成功

比如情感分析失败时，结果标记为 `unknown`，而不是默认写成 `neutral`。

这件事很小，但对结果可信度很重要。

---

隐私和边界：这类工具必须先把话说清楚

我一直觉得，这类工具最容易被误解。

因为它分析的是人发布的公开内容。

公开，不等于可以无限使用。

可抓取，不等于可以滥用。

能分析，不等于应该推断一切。

所以 `xcrawler` 的定位很明确：

它适合用于：

* 公开账号研究

* 创作者分析

* 内容策略

* 品牌观察

* 受众洞察

* 学习和研究

* LLM 应用工程化实践

它不应该用于：

* 骚扰

* 跟踪

* 人肉搜索

* 非公开信息推断

* 敏感身份判断

* 歧视性画像

* 违反平台规则或当地法律的行为

项目默认把数据保存在本地。

敏感生活事件默认隐藏。

HTML 报告中的证据原文支持脱敏。

README 中也明确写了 responsible use 的边界。

工具本身不能替使用者做伦理判断。

但一个负责任的工具，至少应该在设计上保持克制。

---

## 快速使用

安装：

```bash

git clone https://github.com/yuanrengu/xcrawler.git

cd xcrawler

python3 -m venv .venv

source .venv/bin/activate

python3 -m pip install -e ".[all]"

cp .env.example .env

```

编辑 `.env`，填入：

```bash

X_BEARER_TOKEN=your_x_bearer_token

DEEPSEEK_API_KEY=your_deepseek_api_key

TARGET_USERNAME=MiracleHe

```

运行：

```bash

xcrawler fetch -u MiracleHe --pages 3

xcrawler analyze interest -u MiracleHe

xcrawler analyze behavior -u MiracleHe

xcrawler analyze sentiment -u MiracleHe

xcrawler analyze network -u MiracleHe

xcrawler report -u MiracleHe

```

生成的数据、图表和报告会保存在本地 `cache/` 目录。

---

## 当前限制

我不想把它包装成一个“完美产品”。

它现在已经可以使用，但仍然有不少限制：

**1. 依赖 X API 权限和额度**

不同账号的 API 权限会影响可抓取的数据量。

**2. 首次运行可能需要下载 embedding 模型**

这会消耗一些时间和磁盘空间。

**3. LLM 分析会产生 token 成本**

尤其是大量推文翻译、情感分析和兴趣画像分析。

**4. 兴趣分析还可以继续升级**

目前已经有输入上限保护，但更理想的形态是分片提取、候选归并、置信度重排和证据校验。

**5. 长期多用户分析需要更强的存储层**

当前默认是 JSON 文件，适合个人、小规模、低频分析。后续可以加入 SQLite Store，更方便查询运行历史、模型参数和结果版本。

**6. 项目命名未来可能调整**

`xcrawler` 这个名字偏技术脚本，未来如果产品化，可能会改成更有品牌感的名字。

---

## 后续计划

接下来我希望继续做几件事：

* SQLite Store

* LLM 成本看板

* 更完整的分片分析和归并策略

* 更好的 HTML 报告模板

* 更多开箱即用的分析 preset

* 示例数据和 demo

* 更清晰的项目品牌化

* 更完善的文档和贡献指南

我希望它不只是一个“能跑的脚本”，而是一个可以被复用、可以被审计、可以持续演进的开源工具。

---

最后

公开社交内容里有很多信号。

但真正有价值的不是“抓到数据”，而是把数据整理成可复盘、可解释、可追溯的洞察。

`xcrawler` 尝试做的就是这件事：

> 把公开 X/Twitter 时间线，转化为用户画像、兴趣地图和行为洞察。

如果你对公开账号研究、创作者分析、受众洞察、内容策略，或者 LLM 应用工程化感兴趣，欢迎试用，也欢迎提 issue 和 PR。

","createTime":1783399053,"ext":{"closeTextLink":0,"comment_ban":0,"description":"","focusRead":0},"favNum":0,"html":"","isOriginal":0,"likeNum":1,