AI 驱动的社交平台收藏知识库 —— Chrome MV3 浏览器扩展，中文优先，数据 100% 本地。
MindSort 把你在社交平台上的"收藏夹"沉淀为可检索的个人知识库：
收藏 → 同步入库 → AI 自动整理（标签 / 摘要 / 向量）→ 关键词 + 语义双通道检索
- 关键词搜索：纯本地倒排索引，中文 bigram 分词，离线可用（基座能力）
- 语义搜索：OpenAI Embedding + 本地向量扫描，未配置 Key 时自动降级为关键词搜索
- AI 自动整理：为收藏内容生成标签、分类与摘要，一键"立即处理"
- 数据主权：全部数据存于浏览器 IndexedDB；平台故障、AI 欠费、网络离线均不丢数据，可随时 CSV / JSON 导出备份
- 账号安全：凭证不落盘、串行限速请求、熔断保护、安全模式默认开启，账号风险最小化
本项目为非官方工具，与任何社交平台无关联，未获任何平台方认可或赞助。
| 模块 | 能力 |
|---|---|
| 被动认证捕获 | 正常浏览社交平台即自动捕获认证会话，无需输入任何密码 |
| 渐进式同步 | 首次全量按每日额度切片、跨天断点续传；日常增量游标早停（典型 1–2 次请求） |
| 同步中心 | 独立页面可视化同步全过程：实时进度条、相位状态、本次抓取/新增、今日额度、随时停止、可选同步条数（≤ 当日剩余额度） |
| AI 标注 | 批量生成标签/分类/摘要（gpt-4o-mini），contentHash 去重防重复调用 |
| 语义向量 | text-embedding-3-small 批量向量化 + Int8 量化本地扫描 |
| 混合检索 | 关键词（MiniSearch + bigram）与语义双路 RRF 融合排序，单路可用时自动降级 |
| 数据管理 | CSV / JSON 全量导出、JSON 导入恢复、一键清空（均二次确认） |
| 诊断能力 | 同步失败时展示结构化错误码与原始响应结构，真机问题可快速定位 |
flowchart LR
A[日常浏览 X] -->|webRequest 被动捕获| B[(SW 内存凭证)]
B --> C[手动触发同步]
C -->|GraphQL 分页抓取| D[(IndexedDB 六表)]
D --> E[AI 队列]
E -->|标注 + 向量| F[混合索引]
F --> G[关键词 + 语义检索]
D --> H[CSV / JSON 导出]
关键设计：
- 同步仅手动触发，绝无定时 / 后台静默请求（平台安全铁律）
- 认证凭证仅驻留内存，不写入任何 storage / IndexedDB，浏览器关闭即消失（合规红线 D8）
- AI 为可降级增强层：未配置 Key / 服务故障时自动退化为纯关键词搜索，AI 故障永不阻塞同步、搜索与导出
- Node.js >= 20.19（仅开发 / 构建时需要）
- 任一 Chromium 内核浏览器（Chrome / Edge 等）
npm install
npm run build # 产物输出至 dist/然后在浏览器中手动加载：
- 打开
chrome://extensions - 开启右上角「开发者模式」
- 点击「加载已解压的扩展程序」，选择本项目的
dist/目录
⚠️ Chrome 137+ 已封禁--load-extension命令行加载方式，请务必通过chrome://extensions页面手动加载。
- 免责声明确认（必须勾选后才能继续）
- OpenAI API Key（可跳过；跳过则语义搜索与 AI 标注不可用，本地功能不受影响）
- 认证捕获引导：按提示打开社交平台正常浏览几秒，扩展被动捕获认证
- 首次同步引导：了解渐进式同步机制后触发首次同步
进入顶部导航「同步」页，可查看完整同步状态并控制：
- 条数选择：当日额度（默认）/ 50 / 100 / 200 / 自定义，最大值不超过当日剩余额度
- 实时进度：相位（抓取中 / 限流退避 / 会话冷却）、进度条、本次抓取与新增条数、今日额度消耗
- 随时停止：断点已随每页原子落库，停止后下次自动续跑
- 每日额度：默认 500 条/天，安全模式（默认开启）下 250 条/天，次日 0 点自动重置
- 搜索：关键词 + 语义混合检索（RRF 融合），中文 bigram 分词
- 标签筛选：多选标签 AND 过滤
- 虚拟列表：万级数据流畅滚动，点击条目打开详情侧栏
- 导出：设置页导出 CSV / JSON 全量备份
| 设置项 | 说明 |
|---|---|
| OpenAI API Key | 掩码显示、可更新 / 删除，仅存本地 chrome.storage.local |
| 同步 / AI 开关 | 独立控制，关闭后纯本地模式（搜索与导出照常可用） |
| 安全模式（推荐开启） | 抓取间隔加倍、每日上限减半，关闭需二次确认 |
| 导入 / 导出 / 清空 | 全量备份恢复与清理，危险操作均二次确认 |
本项目遵循"账号安全高于功能完整性"原则：
| 机制 | 说明 |
|---|---|
| 凭证不落盘 | 认证凭证仅驻留内存，不写入任何 storage / IndexedDB，浏览器关闭即消失 |
| 数据 100% 本地 | 全部数据存 IndexedDB；任何外部服务故障均不丢数据 |
| 串行限速请求 | 请求间隔 2.5s ± 0.5s 随机抖动，单会话上限 200 条，永不并发 |
| 熔断保护 | 连续 2 次限流触发熔断，随机锁定 24–48 小时，倒计时结束后需人工确认恢复 |
| 安全模式默认开启 | 请求间隔加倍、每日额度减半；关闭需二次确认并自担风险 |
| 冻结前兆识别 | 单会话非 200 异常 ≥ 5 次预警，401 抖动序列自动进入熔断流程 |
src/
├── core/ # 纯业务逻辑，禁止 chrome.*（fetcher / ai / search / pipeline）
├── infra/ # 平台适配层（db / messaging / config / net）
├── shared/ # types / constants / errors
├── background/ # Service Worker 薄层（认证捕获、Query ID 监听、消息路由）
├── content/ # 内容脚本（仅登录态检测，< 100 行硬约束）
├── options/ # Options Page 主界面（React 18 + 搜索 Worker + 同步中心）
└── popup/ # 只读状态速览
分层规则：依赖单向（ui → core → infra 接口），core/ 内禁止 chrome.* 调用，UI 不直接操作 IndexedDB（一律经 Repository）。由构建期红线脚本（scripts/check-redlines.mjs）强制保证。
| 命令 | 说明 |
|---|---|
npm run dev |
Vite 开发模式（热更新） |
npm run build |
红线自检 → tsc --noEmit → Vite 构建 |
npm run lint |
ESLint 全量检查 |
npm test |
Vitest 单元测试（195 项） |
npm run redline |
仅运行合规红线自检 |
- 框架：Vitest；IndexedDB 层使用
fake-indexeddb，core 层在纯 Node 环境运行 - 外部 API 测试采用 fixture 录制回放（
tests/fixtures/），不消耗任何真实账号额度 - 限速 / 熔断逻辑注入虚拟时钟，秒级验证天级行为
- 真机校准（2026-08）已覆盖：X 各版本响应骨架兼容（
bookmark_timeline/bookmark_timeline_v2）、新版扁平化 User 结构（base64 id）、422 状态码映射
| 文档 | 说明 |
|---|---|
| 使用说明 | 面向用户的完整使用手册 |
| 开发文档 | 完成状态、质量记录、待办项与架构决策 |
| MVP 规格说明书 | MVP 唯一实施依据（13 章完整规格） |
| 需求分析文档集 | 竞品 / 技术 / 需求 / 成本 / 合规 / 账号策略分析 |
- 构建：Vite 7 + @crxjs/vite-plugin（MV3 多入口，版本精确锁定）
- 前端：React 18 + TypeScript 5.9（严格模式）+ Zustand
- 数据：Dexie.js（IndexedDB，六表 schema + 版本迁移）
- 搜索：MiniSearch + 中文 bigram 分词 / Int8 量化余弦扫描 / RRF 融合
- AI：OpenAI Chat Completions（json_object）+ Embeddings
- 质量：Vitest 195 项、ESLint 9、红线自检脚本
- 平台接口非公开：同步依赖 X 未公开的 GraphQL 接口，平台更新可能导致短暂不可用（已内置结构诊断与快速适配机制）
- Batch API：积压 > 100 条时标记 batch 通道，实际仍走实时 API，待按通道分流
- i18n：界面文案为中文硬编码，多语言迁移待做
- 10K–50K 数据验证区：bigram 内存占用与标签集合求交优化待实测
- 本项目仅供个人学习与研究使用
- 本工具调用平台非公开接口，存在账号被限制的风险；由此产生的一切账号风险由使用者自行承担
- 使用前请在首看向导中阅读并确认完整免责声明
- 请勿将本项目用于任何商业用途或对平台服务造成负担的场景
本项目暂无正式开源许可证，保留所有权利，仅供个人学习与研究使用。