ZenX 是一款基于 Chrome Extension Manifest V3 开发的高保真、现代化浏览器扩展。它致力于解决社交平台 X (Twitter) 生态中泛滥的垃圾评论（黄推引流、色情推广、刷屏表情包矩阵、无意义回复等），为您还原清爽的社交阅读体验。
本扩展采用由 IndexedDB 缓存 + 本地字符/正则拦截 + 大语言模型 (LLM) 批量语义解析 构成的三层过滤漏斗，并在后台利用抓包鉴权实现零侵入的 Native API 静默拉黑与极客感十足的单色 TUI 侧边栏交互。
无限制的大模型接入能力：ZenX 现已全面支持通过配置 host_permissions，允许您自由对接 OpenAI、Claude、DeepSeek 等任何第三方主流大模型 API，同时也完美兼容运行在 http://localhost:11434 等本机的开源模型（如 Ollama / LMStudio）。
-
🚀 三层过滤漏斗：
-
L1 级 IndexedDB 极速缓存：基于 Dexie.js 建立持久化黑名单，在页面渲染时以
$O(1)$ 时间复杂度秒级完成本地屏蔽，具备 30 天自动 TTL 淘汰机制，防止存储过度膨胀。 - L2 级 本地正则/字符拦截：支持用户自定义屏蔽词或正则表达式，实现对回复文本、用户 Handle 及 DisplayName 的瞬时正则检测，拦截开销极低。
- L3 级 异步批量 AI 判定：将未命中的边缘评论存入缓冲池（如满 8 条或超时 1000ms），通过 Service Worker 统一调度 fetch 发送给兼容 OpenAI/Claude 格式的大模型。支持强约束 JSON-Schema，极大节约 API 消耗与网络带宽。
-
L1 级 IndexedDB 极速缓存：基于 Dexie.js 建立持久化黑名单，在页面渲染时以
-
🛡 零感静默 Native 拉黑 (RPA 引擎)：
- 弃用传统的、易碎的 DOM 模拟点击操作，改用后台网络包分析拦截机制。自动抓取 X 平台的
Authorization凭证与x-csrf-token，直接以官方 API 请求形式（/i/api/1.1/blocks/create.json）在后台完成静默拉黑。 - 内置防风控限频队列，限制每分钟拉黑频次，每步请求插入随机时延，在保障账号安全的前提下实现批量自动化净化。
- 弃用传统的、易碎的 DOM 模拟点击操作，改用后台网络包分析拦截机制。自动抓取 X 平台的
-
👁 辅助阅读与防误伤交互 (Assist)：
- 在“辅助阅读”模式下，垃圾评论不会生硬消失，而是被蒙上磨砂玻璃滤镜 (
blur) 并标记拦截原因。 - 侧边栏与页面实时联动，点击拦截卡片上的 [撤销 / Undo] 按钮即可一键恢复原帖展示，彻底杜绝误伤。
- 主贴作者豁免保护：若评论者为当前主推文的原作者，自动放行判定，避免影响与博主的正常互动。
- 在“辅助阅读”模式下，垃圾评论不会生硬消失，而是被蒙上磨砂玻璃滤镜 (
-
🤖 自动巡逻净网机器人 (Auto-Patrol)：
- 接管浏览器行为，开启全自动净化。状态机依据
HOME -> LOADING -> CLEANING -> BACK -> HOME闭环循环。 - 自动滚动主页 -> 寻找未读推文 -> 点击进入详情页 -> 提取并过滤评论 -> 触发 AI 判断与 API 静默拉黑 -> 点击返回首页。
- 具备 60秒看门狗守护、LRU 网页去重队列 与状态自愈容错机制，在异常时自动回退，实现真正的 24 小时无人值守。
- 接管浏览器行为，开启全自动净化。状态机依据
-
📟 极客终端 (TUI) 侧边栏与 i18n 联动：
- 遵循 OpenCode Mono 设计系统，采用 Radix Themes + 终端单色风格，提供独一无二的 TUI 日志流交互。
- 支持中英文双语界面切换，一键清空日志、快捷键 Tab 轮转与 Ctrl-C 清屏。
- 将日志划分为
engine,filter,llm,rpa,patrol,cache,ui七大类与 5 级状态色彩，支持 200 条热日志回溯。
本扩展由三部分核心组件协作完成：Side Panel (侧边栏界面)、Background Service Worker (后台逻辑总线)、Content Scripts (页面注入脚本)。
┌─────────────────────────────────────────────────────────────────────┐
│ Chrome Side Panel (sidepanel.tsx) │
│ ┌───────────────────────────────┐ ┌─────────────────────────────┐ │
│ │ Preferences / Engine (设置) │ │ TUI Logs (实时终端日志) │ │
│ │ · 模式选择 (Segmented) │ │ · Log Categories 过滤 │ │
│ │ · 自定义 API 终端 / Key │ │ · 实时流 / 5级彩色渲染 │ │
│ │ · 本地屏蔽词/正则维护 │ │ · 拦截数据计数 │ │
│ └───────────────────────────────┘ └─────────────────────────────┘ │
└──────────────────────────┬──────────────────────────────────────────┘
│ chrome.runtime.sendMessage
┌──────────────────────────▼──────────────────────────────────────────┐
│ Background Service Worker (background/index.ts) │
│ · 状态机启停控制中心与全局 engineStatus 广播 │
│ · chrome.webRequest 监听：截获鉴权头 (Authorization / CSRF) │
│ · IndexedDB 本地缓存代理 (持久化管理与 O(1) 过滤响应) │
│ · 跨域大模型代理 (LLM Dispatcher，无视 CORS，支持全局任意模型 URL) │
│ · 日志中继管道 (带 200 条上限的冷启动持久化 buffer) │
└──────────────────────────┬──────────────────────────────────────────┘
│ chrome.tabs.sendMessage
┌──────────────────────────▼──────────────────────────────────────────┐
│ Content Scripts (运行于 https://x.com/* & twitter.com/*) │
│ │
│ zenx.ts (辅助阅读引擎) auto-patrol.ts (自动巡逻引擎) │
│ ┌─────────────────────────┐ ┌─────────────────────────┐ │
│ │ DOMObserver │ │ PatrolStateMachine │ │
│ │ ↓ │ │ ↓ (状态转移驱动) │ │
│ │ FilterPipeline │ │ HOME → LOADING → │ │
│ │ ├─ L1: IndexedDB 缓存 │ │ CLEANING → BACK │ │
│ │ ├─ L2: 本地字符/正则 │ │ ↓ │ │
│ │ └─ L3: LLM 异步攒批 │ │ FilterPipeline 判定 │ │
│ │ ↓ │ │ ↓ │ │
│ │ UIManager (滤镜 & 撤销) │ │ RPAEngine (静默拉黑) │ │
│ └─────────────────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
- 基础骨架：Plasmo — 基于 React 19 + TypeScript 的现代化 Manifest V3 浏览器扩展框架。
- 本地存储：Dexie.js — 针对 IndexedDB 的极简包装器，实现大容量规则缓存的高效检索。
- 界面组件：Radix Themes — 无障碍、样式自由定制的极简 UI 系统。
- 样式方案：Tailwind CSS v4 + 模块化原生 CSS，定义终端配色与高保真滤镜。
x-tool/
├── package.json # 项目依赖与 Plasmo MV3 扩展配置
├── plasmo.config.ts # Plasmo 打包配置文件
├── tsconfig.json # TypeScript 编译器配置
├── readme.md # 工程说明与技术白皮书
├── docs/ # 说明文档与上架物料
│ ├── PRIVACY.md # 隐私政策协议 (Chrome 商店提审必备)
│ └── STORE_SUBMISSION.md # 谷歌商店审核表单指南
├── assets/
│ └── icon.png # 插件图标 (Plasmo 自动缩放生成多尺寸)
├── scripts/
│ └── log-server.js # 开发环境专用：本地 Node.js 终端日志收集服务器
└── src/
├── sidepanel.tsx # Chrome 侧边栏主面板 UI (Radix Themes + 终端交互)
├── options.tsx # 扩展高级偏好设置页
├── background/
│ └── index.ts # Service Worker (全局状态、鉴权头拦截、LLM 代理)
├── contents/
│ ├── zenx.ts # 辅助阅读 Content Script (DOMObserver 驱动)
│ └── auto-patrol.ts # 自动巡逻 Content Script (状态机 RPA 驱动)
├── core/
│ ├── dom-observer.ts # MutationObserver 推文解析与异常降级
│ ├── filter-pipeline.ts # 三层过滤管道与 LLM 异步 Promise 批处理桥接
│ ├── lm-dispatcher.ts # LLM 动态分发 (兼容 OpenAI JSON Schema 与 Claude 格式)
│ ├── regex-filter.ts # 本地正则与敏感词匹配过滤器
│ ├── cache-manager.ts # IndexedDB 本地缓存管理器 (Dexie.js + TTL 淘汰)
│ ├── ui-manager.ts # 磨砂遮罩渲染、拦截标徽注入与撤销恢复操作
│ ├── rpa-engine.ts # Native API 静默拉黑引擎 (限频与随机时延队列)
│ └── patrol-state-machine.ts # 自动巡逻状态机 (含状态看门狗与异常自愈)
├── lib/
│ ├── i18n.ts # 中英文双语国际化文案
│ ├── log-manager.ts # 结构化日志管理器 (推送日志至 SW 与本地 Log Server)
│ └── message-bus.ts # 强类型 Content 与 Background 消息通信总线
├── types/
│ └── index.ts # 全局 TypeScript 接口与 DOM Selectors 集中定义
└── styles/
├── design.css # 终端极客风格全局配色与排版样式表
├── sidepanel.css # 侧边栏样式覆写
└── content.css # 宿主页面注入样式 (磨砂滤镜与拦截撤销 Badge)
npm install为了在开发时更好地追踪后台和页面注入层的日志流，强烈建议您在启动 Plasmo 的同时开启本项目的专属日志服务。 开启一个终端，运行日志服务器：
npm run log-server再开启另一个终端，启动热重载构建：
npm run devPlasmo 会自动在根目录下创建 build/chrome-mv3-dev/ 目录。
打开 Chrome 浏览器，访问 chrome://extensions/，开启右上角的 开发者模式，点击 加载已解压的扩展程序 并选择上述输出目录。扩展运行时产生的 TUI 日志将同步输出至 logs/runtime.log。
npm run build编译成功后，产物会打包输出至 build/chrome-mv3-prod/（并自动生成 .zip 压缩包），该压缩包直接用于向 Google Chrome Web Store 提交正式版本。
- 大模型 URL 无限制声明：本插件
package.json中的host_permissions已配置为无限制跨域请求（<all_urls>/*://*/*），这是因为本插件必须支持用户填入任何自托管本地 AI 服务（如 127.0.0.1 端口）或未知域名的云端接口。开发者保证请求绝不被用于采集用户隐私。 - 防账号风控：虽然扩展采用了 Native API 及限频防风控队列，但拉黑频率如果设置过快（如超过 10 次/分钟）仍可能被 X 平台监测。建议采用默认的每分钟不超过 6 次配置。
- 数据隐私生命周期：所有的鉴权头 (
x-csrf-token)、本地拦截规则和 LLM API 密钥均只驻留在您的浏览器存储 (LocalStorage / IndexedDB / Memory) 中，仅发生浏览器到大模型服务商的单向传输，绝不向拓展开发者的服务器上传任何数据。详见 隐私政策。
本项目基于 MIT License 开源。