开源的 X 评论区 AI 反垃圾扩展 —— 黄推 / 诈骗 / 纯广告 / 人机，一律看得见地挡在门外
中文图文教程 · English Guide · 项目主要功能与特点 · 隐私说明 · 下载安装包
一款保护 X（Twitter）浏览体验的浏览器扩展：自动识别并隐藏评论区垃圾内容，把垃圾账号送入待拉黑名单，按安全节奏真实拉黑，并支持社区共享黑名单。
你在 X 上刷评论时，总会遇到黄推、诈骗、引流号。XShield 做三件事：
- 看：浏览评论区时，命中屏蔽词的垃圾回复立即自动隐藏（也可切换为高亮标记）；
- 记：垃圾账号进入「触发记录」（即待拉黑名单），谁触发的、因为什么、什么时候，一目了然；
- 拉：30 分钟内你没有干预，扩展按安全节奏替你真实拉黑这些账号（和你在网页上手动拉黑完全一样）。
所有人拉黑的数据可手动共享进社区共享黑名单仓库：你在设置页「同步与共享」填好 GitHub Token 后点「共享拉黑名单」上传；其他用户点「同步黑名单」手动拉取后生效。同步与共享全部为手动操作，无自动同步。
关键字触发是默认引擎，开箱即用。想要更准的判断，可在**总设置 →「AI 判断引擎」**切换为 AI 智能判断（基于 TypeSafe System One / Jev 模型）：
- 在总设置粘贴你自己的 TypeSafe API Key（console.typesafe.ai/keys 获取，只存本地），点「测试连通」确认；
- AI 会对每条回帖并行判定黄推 / 诈骗 / 纯广告 / 人机四类并打分，置信度达到阈值（默认 70%）才处理，宁漏放不误杀；
- 阅读时每条判定回帖实时打上四类彩色标签（黄推=粉、诈骗=红、纯广告=橙、人机=紫，高亮模式按类别着色），隐藏/高亮的底色设计保持不变；关键字仍作为基础信号——命中先挂起等 AI 裁决（AI 可否决关键字误报），干净回帖静默扫描兜底（可关闭省配额）；
- 命中处理双选择：AI 引擎与关键字引擎各自可选「仅隐藏（不拉黑）」或「隐藏并拉黑」（默认）；
- 看到疑似误判？页面右下角「🛡 X护盾 · 已隐藏 N 条」面板可以查看每条被隐藏的内容，「恢复显示」立即撤回并退出待拉黑，「白名单」永久豁免。
不填 API Key 时保持关键字引擎即可，一切照旧。
方式 A：从 Release 下载安装包（推荐）
- 打开 GitHub Releases 页面，下载最新版的
xshield-vX.Y.Z.zip（每个版本都附有已构建好的安装包）； - 解压 zip，得到一个内含
manifest.json的文件夹（例如xshield-v1.1.19）； - Chrome 打开
chrome://extensions→ 右上角开启「开发者模式」→ 点「加载已解压的扩展程序」→ 选择刚才解压的文件夹； - 把 XShield 固定到工具栏，用你的 X 账号登录 x.com。
方式 B：从源码自行构建
git clone https://github.com/smthdagg/XShield.git
cd XShield
pnpm install
pnpm build # 产物：apps/extension/dist加载 apps/extension/dist 即可（步骤同 A 的 3、4）。构建要求 Node ≥ 22。
更新扩展：下载新版本 zip → 在 chrome://extensions 点扩展卡片上的「重新加载」（或移除后重新加载新文件夹）→ 刷新已打开的 X 页面（更新后旧页面不会自动注入新代码）。
安装排错
| 现象 | 处理 |
|---|---|
| 「扩展程序包无效」/无法加载 | 确认选择的是解压后的文件夹（内含 manifest.json），不是 zip 本身；重新解压再试 |
| 加载后没有「重新加载」按钮 | 确认右上角开发者模式已开启 |
| 过滤不生效 | 刷新 X 页面；确认扩展已启用 |
| 拉黑不执行 | 打开 x.com 并保持登录（拉黑依赖 X 会话），日志页查看原因 |
拉黑功能依赖当前浏览器的 X 登录状态；未登录时过滤功能照常可用，但拉黑会失败。
日常使用（零操作）：打开任意推文评论区，垃圾回复自动消失，作者自动进入待拉黑名单。什么都不用点。
管理面板（点工具栏图标进入，共五页）：
| 页面 | 用途 |
|---|---|
| 触发记录 | 待拉黑名单（唯一一份）：每张卡片显示触发的账号、原因、内容，带「拉黑 / 白名单 / 删除」按钮；工具栏支持全选后批量拉黑、批量删除，及「清理社区记录」一键清掉社区喂送的历史记录；本页还可调拉黑节奏（每日上限、每批数量、单次间隔） |
| 拉黑记录 | 统计数字（今日 / 剩余 / 累计）、近 7 天按日拉黑、待拉黑队列列表（社区共享 / 正常触发分类筛选）、已拉黑用户列表（最新 300 个分页浏览，搜索可定位全部，可解除拉黑） |
| 白名单 | 永久豁免的用户，永不触发、永不拉黑 |
| 规则与同步 | 云端规则（keywords.txt）手动同步与共享、本地词库增删改、导入导出 |
| 状态与日志 | 运行状态（累计拉黑 / 平均每天 / 累计触发 / 当前账号）、活动日志（可筛选、导出、清理） |
| 总设置 | 运行状态卡片、总开关、隐藏/高亮切换、各项过滤开关、词库源、同步与共享（黑名单手动同步/共享、GitHub Token、同步记录）、导出诊断信息 |
同步说明：无自动同步。规则（keywords.txt）在「规则与同步」页手动同步/共享；黑名单（handles.txt）在「总设置 → 同步与共享」手动同步/共享；两者共用同一个仓库源（默认 smthdagg/XShield-keywords，可在总设置修改）。每次同步/共享/删除都会写入本地日志（「日志」页可查可导出）。
自动拉黑节奏（触发记录页可调，默认保守）：每日 20 个、每批 5 个（批后随机歇 20–60 分钟）、单次间隔随机化（基线 90 秒，常夹带 3–12 分钟的长停顿；触发限流后冷却 60–180 分钟）。节奏刻意做成类人模式而非机械节拍，降低被 X 反自动化系统识别为脚本的风险。X 没有官方限制文档，请按自己账号权重调整。手动确认的拉黑优先执行（排在队列最前）。
拉黑失败怎么办：打开 x.com 并保持登录（拉黑依赖 X 会话）；失败的用户 24 小时内不会自动重试，日志页可查看原因；手动「拉黑列表」可随时显式重试。
误拉恢复：拉黑记录页找到该用户 → 点「白名单」（解除拉黑并加白）。
不确定扩展是否在跑：看面板侧栏底部版本号；或在 X 页面按 F12，控制台应有 [XShield] content vX ready 日志。
报障：总设置 → 「导出诊断信息」，把 JSON 文件发给维护者。
所有数据只存在你的浏览器本地。联网仅四类：下载云端词库/黑名单（手动同步时）、X 拉黑接口、你主动点击的 GitHub 共享上传（可选功能，不填 Token 不上传）、以及可选的 AI 判断请求（仅在你切换到 AI 引擎并填入自己的 TypeSafe API Key 后，回帖文本截断后发送至 api.typesafe.ai，结果只存本地；默认关键字引擎不产生该请求）。
扩展免费开源。上架与维护有成本，欢迎支持：GitHub Sponsors · 爱发电
MIT License，详见 LICENSE。
A browser extension that protects your X (Twitter) timeline: it auto-hides spam replies in comment sections, queues the offending accounts for a real block, and blocks them at a safe pace — plus an optional manually-synced community blocklist.
Keyword triggering is the default engine and works out of the box. For sharper judgement, switch to AI judgement under Settings → AI engine (powered by TypeSafe System One / Jev):
- Paste your own TypeSafe API Key (get one at console.typesafe.ai/keys, stored locally) and hit "Test connection";
- The AI classifies every reply into porn-bait / scam / pure ads / bot with a score; only verdicts above the confidence threshold (default 70%) are acted on;
- While reading, flagged replies get a real-time colored tag (porn-bait=pink, scam=red, ads=orange, bot=purple; highlight mode tints per category); hide/highlight styling stays unchanged; keywords remain the base layer — a keyword hit is held for the AI verdict (the AI can veto false positives), clean replies get one silent scan (toggleable to save quota);
- Hit action, per engine: both the AI and keyword engines offer "hide only" vs "hide + queue for block" (default);
- Suspicious hide? Open the "🛡 XShield · N hidden" panel at the bottom-right, Restore to unhide and leave the pending queue, or Whitelist to exempt the author permanently.
No API key? Keep the keyword engine — everything works as before.
Option A: release package (recommended)
- Open GitHub Releases and download the latest
xshield-vX.Y.Z.zip(every release ships a pre-built package); - Unzip it — you get a folder containing
manifest.json(e.g.xshield-v1.1.19); - Chrome →
chrome://extensions→ enable Developer mode → Load unpacked → select that folder; - Pin XShield to the toolbar and log in to x.com.
Option B: build from source
git clone https://github.com/smthdagg/XShield.git
cd XShield
pnpm install
pnpm build # output: apps/extension/distThen load apps/extension/dist (steps 3–4 of Option A). Building requires Node ≥ 22.
Updating: download the new zip → click Reload on the extension card at chrome://extensions (or remove and load the new folder) → refresh already-open X tabs (old pages don't pick up new code automatically).
Troubleshooting
| Symptom | Fix |
|---|---|
| "Package is invalid" / won't load | Select the unzipped folder containing manifest.json, not the zip; re-unzip and retry |
| No Reload button | Make sure Developer mode is on |
| Filtering not working | Refresh the X page; check the extension is enabled |
| Blocking not executing | Open x.com and stay logged in (blocking needs an X session); check the Logs page |
Blocking requires being logged in to x.com; filtering works without login.
Daily use (zero clicks): open any comment section — spam replies disappear and their authors enter the pending list automatically.
Dashboard (toolbar icon, five pages):
| Page | Purpose |
|---|---|
| 触发记录 (Pending list) | every not-yet-blocked account with 拉黑 (block now) / 白名单 (whitelist) / 删除 (delete) buttons; toolbar bulk block / bulk delete / one-shot community-record purge; block pacing settings live here |
| 拉黑记录 (Block log) | counters (today / remaining / total), last-7-days daily blocks, pending-queue list (community/trigger filters), blocked-users database view (newest 300 paginated, full search, unblock) |
| 白名单 (Whitelist) | permanently exempted users |
| 规则与同步 (Rules & sync) | manual rules (keywords.txt) sync & share, local library add/edit/import/export |
| 状态与日志 (Status & Logs) | runtime stats (total blocked / avg per active day / total triggers / current account) + activity logs (filter, export, prune) |
| 总设置 (Settings) | runtime stats card, master switch, hide/highlight, filter toggles, library source, manual blacklist sync & share, GitHub token, sync records, export diagnostics |
Sync is manual — there is no auto-sync. Rules (keywords.txt) sync/share on the Rules & sync page; the blacklist (handles.txt) sync/share under Settings → Sync & share; both share one repo source (default smthdagg/XShield-keywords). Every sync, share and deletion is written to the local log (Logs page, exportable).
Block pacing (adjustable, conservative defaults): 20/day, batches of 5 (random 20–60 min pause after each), randomized per-block gaps around a 90 s baseline with frequent longer pauses (3–12 min), and a 60–180 min cooldown when X rate-limits (429). The pacing is deliberately human-like rather than a fixed tick, to reduce the chance X's anti-automation flags it as a script. X publishes no official limits — tune to your account's age and weight. Manually confirmed blocks jump the queue.
Block failures: open x.com and stay logged in (blocking needs an X session); failed users are not auto-retried for 24 hours — see the Logs page for reasons; the manual 拉黑列表 button always retries explicitly.
Undo a mistaken block: block-log page → that user's card → 白名单 (unblock + whitelist).
Is it running? Version badge at the sidebar bottom; or F12 on X for the [XShield] content vX ready console line.
Report an issue: 总设置 → Export diagnostics → send the JSON file.
Everything is stored locally in your browser. Network requests: cloud library/blocklist downloads (on manual sync), the X block endpoint, optional GitHub sharing uploads (only on explicit click with a token), and — optionally — AI judgement requests (only after you switch to the AI engine with your own TypeSafe API key; reply text is truncated and sent to api.typesafe.ai, verdicts stay local). The default keyword engine makes no such request.
MIT License, see LICENSE.
详细教程 / Full tutorials: 中文说明书 · English Guide