TweetGuard 在浏览器端识别并静默折叠 X (Twitter) 信息流里的垃圾推文。无后端、无遥测，所有数据保存在 chrome.storage.local。内置规则开箱即用；可选启用 AI 复审（需要你自己提供 API Key），让系统在浏览时自动学习并沉淀新的 spam 模板；还能与 GitHub 社区规则库双向同步，大家共建同一套规则。
每条推文按"成本从低到高"依次经过几道关，任意一关定案即停：
① 名单保护（最高优先级）
白名单 / 你关注的人 → 永不隐藏；黑名单 → 强制隐藏。
任何规则（含社区规则）都不会越过它去隐藏你信任的人。
│
② 规则命中（命中即隐藏）
内置硬规则 + AI 学习规则 + GitHub 社区规则
—— 推文关键词 / 短中文混写 / 固定 emoji 模板。
│
③ L0 评分（13 项信号累加，过阈值则隐藏 / 模糊）
显示名维度信号已整体降权（显示名不可靠）。
│
④ 推文上下文缓存
账号 + 推文内容 + 回复/认证上下文完全一致 → 复用结果，零 AI 调用。
同一账号发布的新内容仍会重新检查，避免账号级误判和漏判。
│
⑤ AI 复核（灰区，可选）
本地拿不准时，送你配置的 AI（DeepSeek / OpenAI / Anthropic /
Gemini / xAI Grok / Groq / OpenRouter / Ollama）。AI 判定的同时会
**自动沉淀规则** —— 下次同模板本地直接命中，不再花 AI。
被识别的推文折叠成一条与卡片等宽的细条，标注命中原因与来源（本地规则 / 社区 / AI / 缓存），点击可展开、再点可收起。
| 来源 | 怎么来的 | 在哪看 / 管 |
|---|---|---|
| 内置规则 | 写死在引擎里：4 条硬规则（黑名单、pump.fun、显示名中文引流词、加微/TG+回复）+ 13 项评分信号 | 设置 →「规则与权重」（动态展示，与引擎单一数据源对齐） |
| AI 学习规则 | AI 判 spam 时自动蒸馏推文关键词；分类没产出时用复审 prompt 兜底补一次；你手动标记误判时也会复审产出 | 设置 →「AI 学习到的规则」（每条标注来源「自动」/「你反馈」，可禁可删） |
| GitHub 社区规则 | 从社区仓库同步大家共建的规则；你也能一键贡献自己的 | 设置 →「规则与权重」→「社区规则同步」 |
自我进化：AI 每识别一条本地规则漏掉的 spam，就把它的推文关键词（文字、短中文混写如 sao货、或固定 emoji 模板）沉淀成规则，下次同模板零 AI 命中 —— 越用越省、越用越准。
- 名单优先保护：你关注 / 加白名单的人，任何规则（含社区规则）都不会误隐藏 —— fail-open 底线。
- 三来源规则：内置 + AI 自学习 + GitHub 社区，统统可见、可禁、可删。
- AI 自动沉淀：判定 spam 后自动归纳规则（含 emoji 模板）；分类没产出时复用复审 prompt 兜底补一次。
- AI 自备 Key（BYOK · Bring Your Own Key）：插件不提供 API Key，需要你自己注册并填入；支持 DeepSeek、OpenAI、Anthropic、Gemini、xAI Grok、Groq、OpenRouter、OpenCode Go、Ollama（本地）和自定义 endpoint。Key 只存本机 storage，请求直连你选择的 endpoint。
- GitHub 社区规则同步：双向——拉取共享规则 + 一键贡献你的规则；误判的社区规则可在本地否决，且同步不覆盖你的否决。
- 关注列表自动同步：在你自己的「正在关注」页点一下，自动滚动抓取全部关注账号纳入保护（用 X 自身的加载机制，不逆向接口）。
- 配置备份 / 恢复：完整导出导入（学习规则、黑白名单、关注列表、反馈历史、自定义关键词、判定缓存、偏好），换设备一键迁移；API Key 可选包含。
- 反馈学习：误隐藏点「信任」自动禁用闯祸规则；漏判点旗标触发规则归纳。
- 隐藏方式可选：折叠条 / 原地模糊 / 彻底移除；三档灵敏度。
- 无遥测：无服务器、无埋点、无远程加载。对外流量仅为你显式发起的 AI 调用，以及（启用时）从 GitHub 拉取社区规则。
推荐从 Chrome Web Store 安装正式版本：无需开发者模式，Chrome 会自动更新扩展，适合绝大多数用户。
如果你想测试最新源码、验证未发布版本或自行修改，也可以通过开发者模式安装。两种方式任选其一：
方式一：下载打包好的 zip
- 到 Releases 下载最新的
tweetguard-x.y.z.zip，解压到一个固定目录（别删，扩展从这里运行）。 - 在 Chrome / Edge / Brave 中打开
chrome://extensions。 - 开启右上角的 开发者模式。
- 点击 加载已解压的扩展程序，选择刚解压出来的目录。
- 打开
x.com即生效，默认启用内置规则。
为什么不是双击安装的
.crx？Chrome 出于安全策略会自动停用「非应用商店来源」的.crx，所以走「解压 + 加载已解压」是当前最可靠的侧载方式。
方式二：克隆源码（开发者）
- 克隆本仓库：
git clone https://github.com/viewer12/tweetguard.git
chrome://extensions→ 开启 开发者模式 → 加载已解压的扩展程序 → 选择克隆下来的目录。
修改代码后，需在
chrome://extensions点扩展的 刷新 图标重载，再刷新x.com才会生效。
仅用内置规则即可覆盖大部分显性 spam。启用 AI 层后，覆盖率从约 80% 提升到约 95%，并开始自动学习沉淀内置规则尚未覆盖的新模板。
- 工具栏 TweetGuard 图标 → 设置 → AI 提供商。
- 选择内置提供商，或点提供商右侧的 + 新建一条可命名的自定义连接；配置协议、模型、API Key 与 Base URL 后点 运行测试（用 5 条已知样本验证）。
| Provider | 推荐模型 | 备注 |
|---|---|---|
| DeepSeek | deepseek-v4-flash |
极快极便宜；原生 Responses API 目前仅支持 V4 Flash |
| OpenAI | gpt-5.6-luna |
GPT-5.6 高吞吐层级，默认走 Responses API |
| Anthropic | claude-haiku-4-5 |
最快的 Claude，近前沿智能 |
| Gemini | gemini-3.5-flash-lite |
低延迟、低成本，原生 generateContent |
| xAI | grok-4.3 |
分类质量与成本均衡；可选 Grok 4.5 |
| Groq | openai/gpt-oss-20b |
高吞吐、支持 JSON Mode |
| OpenRouter | google/gemini-3.6-flash |
一个 Key 路由多家模型 |
| OpenCode Go | deepseek-v4-flash |
月付订阅，一个 Key 用多家精选开源模型 |
| Ollama | qwen3.5:4b |
本地运行，推文不离开本机 |
协议层支持 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 和 Gemini generateContent。内置厂商只展示其官方支持的协议；自定义提供商可选择全部协议，也可填写预设之外的模型 ID。
内置提供商的设置会分别自动保存；自定义提供商可创建多条命名连接，并独立保存协议、模型、Base URL、API Key 和超时。连接支持重命名、复制和删除，切换回来时会恢复各自配置。
两个 Prompt（分类 / 复审）都在 设置 → Prompt 里可看、可改、可还原。
TweetGuard 自带从 GitHub 同步社区规则的能力（默认开启，可关）：
- 同步（拉取）：默认从本仓库的
community-rules.json拉取，启动时 + 每 24 小时各一次，也可手动「立即同步」。拉来的规则与 AI 学习规则走同一道安全闸门：只接受推文关键词（tweet_keyword），显示名 / 用户名类规则一律拒绝。 - 贡献（推送）：设置 →「规则与权重」→「社区规则同步」→「贡献我的规则」，把你的本地学习规则导出成社区格式（复制到剪贴板 + 下载 + 打开 GitHub 提交页），确认后提个 PR 即可。
- 否决：误判的社区规则可点「信任」本地否决，且每次同步不会覆盖你的否决。
规则文件格式：
{ "format": "tweetguard-rules-v1", "rules": [ { "kind": "tweet_keyword", "value": "完整版来了", "category": "cn_nsfw_bot" } ] }- 无后端、无遥测，仓库不含任何服务端代码。
- 所有状态保存在
chrome.storage.local：配置、缓存、学习规则、反馈历史均仅在本机。 - 对外流量仅为：你主动发起的 AI API 调用（本地直连你选的 provider，TweetGuard 不中转）+ 启用时从 GitHub 拉取社区规则。
- 支持 Ollama 本地模式，推文数据可不离开本机。
- 不基于用户名（@handle）判定 spam：handle 在结构上不可靠（亚洲用户大量使用「罗马名 + 数字」格式）。显示名维度的内置硬规则也克制到极少数（仅中文引流词、加微/TG），其余显示名信号在评分层降权；AI 学习与社区规则只基于推文内容。
完整隐私政策见 PRIVACY.md。
- 提交规则：最快的方式是用插件内「贡献我的规则」导出后 PR 到
community-rules.json。 - 代码方向：中文 spam 模板（
src/inject.js的RX区）、多语种规则、provider 适配、UI 细节、回归测试 fixture。
提交 PR 前请：在真实 x.com 滚动测试；确认不会基于弱信号误伤合法账号；运行 npm test 并确保扩展可正常打包。
MIT — 见 LICENSE。