需要被动采集 X/Twitter 社区互动数据并导出…

通过 Chrome/Brave 扩展在正常浏览 X/Twitter 时捕获 GraphQL 响应，提取推文、点赞者、回复和资料数据，再导出结构化 JSON 供后端分析。

适用场景

解决思路

1. 通过拦截浏览器 fetch 被动捕获 X/Twitter GraphQL 响应：正常浏览时采集，不额外调用 API，从而避免 rate limit。
2. 针对指定 handle 监控 tweets、replies、likes 和 engagement。
3. 输出结构化 JSON，包含 tweets、metrics、favoriters、engagement summaries，并设计为可摄入 Laravel/database 后端。
4. 捕获 `UserTweets` 端点：提取 tracked handle 的所有 tweets 与完整 metrics。
5. 捕获 `Favoriters` 端点：提取点赞特定 tweet 的用户，并带上 mutual follow 状态。
6. 捕获 `TweetDetail` 端点：提取回复线程和互动详情。
7. 捕获 `UserByScreenName` 端点：提取资料数据，如 followers、bio、verification。
8. 在 Chrome/Brave 打开 `chrome://extensions/`，启用右上角 Developer mode，点击 Load unpacked 选择项目目录，并把扩展图标固定到工具栏。
9. 创建项目结构：`manifest.json`、`interceptor.js`、`content.js`、`background.js`、`popup.html/css/js`、`icons/`（16、48、128px）。
10. 在 `manifest.json` 使用 Manifest V3，配置 `permissions` 为 `storage`、`activeTab`，`host_permissions` 为 `https://x.com/*`、`https://twitter.com/*`，`background.service_worker` 为 `background.js`，`action.default_popup` 为 `popup.html`。
11. 在 `manifest.json` 注册两个 content scripts，匹配 `https://x.com/*` 与 `https://twitter.com/*`，`run_at` 都为 `document_start`；`content.js` 在 ISOLATED world，`interceptor.js` 在 MAIN world。
12. 在 `interceptor.js` 的 MAIN world 保存 `window.fetch` 原始引用，并替换 `window.fetch`。
13. 在替换后的 `window.fetch` 中调用 `originalFetch.apply(this, args)`，在 then 中 clone response，仅当 URL 字符串包含 `api.x.com/graphql` 时处理。
14. 从 URL 中提取 endpoint 名称：匹配 `/graphql/` 后、查询参数前的片段。
15. 对 clone 的 response 调用 `.json()`，通过 `window.postMessage` 发送 `{ type: 'TWITTER_GRAPHQL_RESPONSE', url, endpoint, data, timestamp: Date.now() }`；非 JSON 响应忽略。
16. 在 `content.js` 监听 `message`，检查 `event.source === window` 且 `event.data.type === 'TWITTER_GRAPHQL_RESPONSE'`，用 `chrome.runtime.sendMessage({ type: 'GRAPHQL_INTERCEPTED', payload: event.data })` 转发给 background。
17. 在 `content.js` 可选给 `chrome.runtime.sendMessage` 加回调，打印 `Data forwarded to background:`。
18. 在 `background.js` 维护 `capturedTweets` Map（`tweet_id -> tweet object`）、`capturedFavoriters` Map（`tweet_id -> array of users`）、`capturedReplies` 数组、`trackedHandle`。
19. 启动时用 `chrome.storage.local.get(['trackedHandle'])` 加载 tracked handle。
20. 在 `background.js` 监听 `chrome.runtime.onMessage`，收到 `GRAPHQL_INTERCEPTED` 后按 endpoint 分发：`UserTweets` 调 `processTweets`、`Favoriters` 调 `processFavoriters`、`TweetDetail` 调 `processReplies`、`UserByScreenName` 调 `processUserProfile`；返回 `{ status: 'processed' }`，并 `return true` 保持消息通道。
21. `processTweets` 从 `data?.data?.user?.result?.timeline_v2?.timeline?.instructions` 取 instructions，遍历 `TimelineAddEntries`，对每个 entry 调用 `extractTweetFromEntry`，若 `shouldTrack(tweet)` 则写入 `capturedTweets`。
22. `extractTweetFromEntry` 从 `entry.content?.itemContent?.tweet_results?.result` 取 content，从 `content.legacy` 取 legacy，从 `content.core?.user_results?.result?.legacy` 取 user/screenName；返回 `tweet_id: content.rest_id`、`text`、`created_at`、`author_screen_name`、metrics（`favorite_count`、`retweet_count`、`reply_count`、`quote_count`、`bookmark_count`、`view_count: parseInt(content.views?.count || '0')`）、hashtags、user_mentions、media_count、is_retweet、source。
23. `shouldTrack` 比较 `tweet.author_screen_name?.toLowerCase()` 与 `trackedHandle.toLowerCase()`。
24. `processFavoriters` 从 URL 的 variables 中匹配 `tweetId` 并提取数字 tweetId；从 `data?.data?.favoriters_timeline?.timeline?.instructions?.[0]?.entries` 取 entries，遍历 `entry.content?.itemContent?.user_results?.result`。
25. `processFavoriters` 提取用户字段：`rest_id`、`screen_name`、`name`、`followers_count`、`following`、`followed_by`、`verified`，追加到 `capturedFavoriters` 的对应 tweetId 数组。
26. 提供 `setTrackedHandle(screenName)`：用 `chrome.storage.local.set({ trackedHandle: screenName.replace('@', '') })` 保存。
27. 提供 `getTrackedHandle()`：用 `chrome.storage.local.get(['trackedHandle'])` 获取，默认返回 null。
28. `buildExportJSON` 从 `capturedTweets` 生成 tweets，分离 originalTweets（`!is_retweet`）和 retweets（`is_retweet`）。
29. 将 `capturedFavoriters` 转成 `favoritersByTweet` 对象。
30. 计算 summary：`total_tweets`、`total_original`、`total_retweets`、`total_community_replies`、`total_likes`、`total_views`、`avg_likes_per_original`、`avg_views_per_original`、`unique_engagers`、`top_tweet_by_likes`、`top_tweet_by_views`。
31. 计算 topTweetByLikes：对 originalTweets 按 `metrics.favorite_count` 降序排序取第一个 `tweet_id`；计算 topTweetByViews：按 `metrics.view_count` 降序排序取第一个 `tweet_id`。
32. 在 `buildExportJSON` 中统计 uniqueEngagers：合并 favoriters 的 `rest_id` 与 replies 的 `author.rest_id`。
33. 返回导出结构：`tracked_account`（含 `screen_name` 等）、`exported_at`、`tweets`、`community_replies`、`favoriters_by_tweet`、`summary`。
34. `downloadJSON` 将 `buildExportJSON()` 用 `JSON.stringify(json, null, 2)` 转字符串，创建 `Blob` 类型 `application/json`，用 `URL.createObjectURL`，文件名 `x-${trackedHandle}-${new Date().toISOString().split('T')[0]}.json`，调用 `chrome.downloads.download({ url, filename, saveAs: true })`。
35. `popup.js` 在 DOMContentLoaded 后获取 `handle-input`、`track-btn`、`export-btn`、`stats`；读取 `trackedHandle` 填入 input 并加载统计。
36. 点击 `track-btn` 时，取 `handleInput.value.trim().replace('@', '')`，非空则 `chrome.storage.local.set({ trackedHandle: handle })`，发送 `{ type: 'SET_TRACKED_HANDLE', handle }` 给 background，按钮临时显示 `Tracking!`，再 `loadStats()`。
37. 点击 export 按钮时，发送 `{ type: 'EXPORT_JSON' }` 给 background；成功则按钮临时显示 `Exported!`。
38. `loadStats` 发送 `{ type: 'GET_STATS' }`，将 `total_tweets`、`total_likes`、`total_views`、`unique_engagers` 渲染到 stats。
39. 在 popup 中用 `setInterval(loadStats, 5000)` 每 5 秒刷新统计。
40. Laravel 后端可创建 `IngestTwitterAnalytics` command，签名 `twitter:ingest {file}`；读取 JSON，`json_decode(..., true)`；用 `TwitterAccount::updateOrCreate` upsert tracked account；用 `Tweet::updateOrCreate` upsert tweets；用 `CommunityEngagement::updateOrCreate` 处理 favoriters 的 like 和 community_replies 的 reply；输出导入推文数和 unique engagers 数。
41. Laravel like 记录包含 `user_screen_name`、`user_name`、`followers_count`、`is_mutual`（`following && followed_by`）、`is_verified`；reply 记录包含 `user_screen_name`、`in_reply_to_tweet_id`。
42. Node.js/Express 提供 `POST /api/analytics/ingest`，使用 `express.json({ limit: '50mb' })`；upsert account，批量 `createMany` tweets（`skipDuplicates: true`），把 favoriters_by_tweet 展平成 engagements 并 `createMany`（`skipDuplicates: true`），返回 `{ success: true, summary }`。
43. Node.js 批量插入 tweets 时，将 `metrics` 和 `hashtags` 用 `JSON.stringify` 处理后再写入。
44. Pattern 1 每日快照：在 `background.js` 用 `chrome.alarms.create('daily-export', { when: Date.now() + 1000, periodInMinutes: 1440 })`，监听 `chrome.alarms.onAlarm`，到期构建 JSON，用 `fetch` POST 到后端 `/analytics/ingest`，带 `Authorization: Bearer ${process.env.API_KEY}`，成功后清空 `capturedTweets`、`capturedFavoriters`、`capturedReplies`。
45. Pattern 2 多 handle：维护 `trackedHandles` Set；`addTrackedHandle(handle)` 从 `chrome.storage.local.get(['trackedHandles'])` 读取，push 后写回，并更新 Set；`shouldTrack` 用 `trackedHandles.has(tweet.author_screen_name?.toLowerCase())`；`buildExportJSON(handle)` 按 handle 过滤 tweets。
46. Pattern 3 实时指标：`renderTweetFeed` 发送 `{ type: 'GET_RECENT_TWEETS', limit: 10 }`，将返回 tweets 渲染为 tweet-card，显示文本、`favorite_count`、`retweet_count`、`view_count`，用 `escapeHtml` 防 XSS。
47. Troubleshooting 扩展未采集：在 x.com console 执行 `console.log(window.fetch.toString())`，应看到 patched function 而非 native code。
48. Troubleshooting 扩展未采集：在 popup.js 用 `chrome.tabs.query({ active: true, currentWindow: true })` 检查当前 URL 必须是 x.com 或 twitter.com。
49. Troubleshooting 扩展未采集：测试 storage：`chrome.storage.local.set({ test: 'value' })` 后 `chrome.storage.local.get(['test'])`。
50. Troubleshooting GraphQL 未解析：在 background.js 收到 `GRAPHQL_INTERCEPTED` 时 `console.log('Raw endpoint:', ...)` 和 `console.log('Raw data:', JSON.stringify(..., null, 2))`。
51. 应对 Twitter API 结构变化：实现 `safeExtract(obj, path, defaultValue = null)`，通过 `path.split('.').reduce((acc, part) => acc?.[part], obj) ?? defaultValue` 安全取值，例如 `safeExtract(entry, 'content.itemContent.tweet_results.result.legacy.full_text', '')`。
52. 导出文件过大：实现分页 `buildExportJSON(page = 1, pageSize = 100)`，返回 `page`、`total_pages`、当前 `tweets` 分片。
53. 导出文件过大：使用 `pako.gzip(json)` 压缩，创建 `Blob` 类型 `application/gzip` 下载压缩 JSON。
54. 性能问题：用 debounce 保存存储，`debouncedSave` 中 `clearTimeout`，`setTimeout` 5000ms 后把 `capturedTweets` 和 `capturedFavoriters` 的 entries 写入 `chrome.storage.local`。
55. 内存管理：设置 `MAX_TWEETS = 1000`；`addTweet` 在超过上限时删除 `capturedTweets` 最旧 key，再写入新 tweet。
56. Advanced Webhook 自动推送：在 background.js 设置 `WEBHOOK_URL`，`pushToWebhook(data)` 用 `fetch` POST JSON，带 `X-API-Key` 从 chrome.storage 获取；在 `processTweets` 中发现新 tweet 时立即调用，payload 含 `type: 'new_tweet'`、`tweet`、`captured_at`。
57. Engagement scoring：`calculateEngagementScore(tweet)` 中 like 权重 1、retweet 权重 5、reply 权重 10、quote 权重 15；rawScore 为各 metrics 乘权重之和；normalizedScore 为 `rawScore / Math.log10(tweet.author_followers_count + 10)`；返回 `Math.round(normalizedScore * 100) / 100`。

适用边界 · 注意事项

• 不适合需要完整历史推文或无法在浏览器中自然触发对应 GraphQL 响应的场景；该方案只被动捕获浏览时已收到的数据。
• 不适合 X/Twitter 修改 GraphQL 字段或端点后未同步更新解析逻辑的场景。
• 不适合不能安装或加载 Chrome 扩展、或非 Chrome/Brave Manifest V3 环境。