机器翻译正文由机器翻译自项目原始文档（英文），排版经程序统一处理，可能存在偏差，请以原项目仓库为准。

Siftly是什么？

Siftly 将你的 Twitter/X 收藏夹变成一个可搜索、分类、可视化的知识库——完全在你的设备上运行。无需云端、无需订阅、无需浏览器扩展。除你配置的 AI API 调用外，一切数据都保持本地。

它在你的收藏夹上运行一个四阶段 AI 流程：

📥 Import (built-in bookmarklet or console script — no extensions needed)
    ↓
🏷️  Entity Extraction   — mines hashtags, URLs, mentions, and 100+ known tools from raw tweet data (free, zero API calls)
    ↓
👁️  Vision Analysis      — reads text, objects, and context from every image/GIF/video thumbnail (30–40 visual tags per image)
    ↓
🧠 Semantic Tagging     — generates 25–35 searchable tags per bookmark for AI-powered search
    ↓
📂 Categorization       — assigns each bookmark to 1–3 categories with confidence scores

管道运行后，你会得到：

• AI 搜索 — 按意义查找书签，而不仅仅是关键词（“关于加密货币暴跌的搞笑表情包”）
• 交互式思维导图 — 可视化探索你的整个书签图谱
• 过滤浏览 — 网格或列表视图，可按类别、媒体类型和日期过滤
• 导出工具 — 下载媒体，导出为 CSV / JSON / ZIP

快速开始

先决条件

• Node.js 18
• npm（随 Node.js 一起提供）

就这些。 如果你已经安装并登录了 Claude Code CLI，AI 功能会自动工作 — 无需 API 密钥。

选项 A — 一条命令（推荐）

git clone https://github.com/viperrcrypto/Siftly.git
cd Siftly
./start.sh

start.sh 安装依赖项，设置数据库，检查 Claude CLI 认证，并自动打开 http://localhost:3000 。

选项 B — 使用 Claude Code

如果你使用 Claude Code 来设置项目，它会读取 CLAUDE.md 并完全了解如何开始。只需打开项目文件夹：

git clone https://github.com/viperrcrypto/Siftly.git
claude Siftly/

Claude Code 将使用您现有的 Claude 订阅来处理设置并启动应用程序 —— 无需额外配置。

选项 C —— 手动设置

git clone https://github.com/viperrcrypto/Siftly.git
cd Siftly
npm install
npx prisma generate
npx prisma migrate dev --name init
npx next dev

打开 http://localhost:3000

AI 身份验证

Siftly会自动检测最适合的认证方法——在大多数常见情况下无需配置。

优先顺序

Claude Code CLI（无需API密钥）

如果你使用Claude Code，你已经登录。Siftly会从macOS钥匙串检测你的会话，并自动使用你的Claude订阅（免费/Pro/Max）。

在此功能激活时，设置页面会显示绿色“检测到Claude CLI — 无需API密钥”徽章，以及你的订阅等级。

注意： 仅限macOS。在Linux/Windows上，请在设置中添加API密钥。

获取API密钥（如需要）

1. 访问 console.anthropic.com
2. 创建新的API密钥
3. 打开Siftly → 设置 → 粘贴密钥

新账户包含5美元免费额度——足够用于以Haiku价格(~$0.00025/书签)保存数千条书签。

导入您的书签

Siftly 内置了导入工具 —— 无需浏览器扩展。前往导入页面并选择任一方法：

方法 A — 书签小工具 (推荐)

1. 在 Siftly 侧边栏中进入导入
2. 将“导出 X 个书签”链接拖到浏览器的书签栏 (或右键点击书签栏 → 添加书签 → 粘贴 URL)
3. 登录 X 后访问 x.com/i/bookmarks
4. 点击书签栏中的 “导出 X 个书签” —— 页面上会出现紫色按钮
5. 点击 “▶ 自动滚动” —— 工具会自动滚动并捕获所有书签
6. 完成后，点击紫色 “导出 N 个书签” 按钮 —— bookmarks.json 会自动下载
7. 回到 Siftly → 导入 → 拖放或上传文件

方法 B — 浏览器控制台脚本

1. 登录 X 后访问 x.com/i/bookmarks
2. 打开开发者工具：按 F12 (Windows/Linux) 或 ⌘⌥J (Mac)，然后进入控制台标签
3. 从 Siftly 导入页面复制控制台脚本，粘贴到控制台中并按回车
4. 点击 “▶ 自动滚动” 并等待所有书签被捕获
5. 点击导出按钮 —— bookmarks.json 会自动下载
6. 回到 Siftly → 导入 → 上传文件

重新导入

随时可重新导入 —— Siftly 会自动跳过重复项，只添加新的书签。

AI 分类

一旦导入，分类会自动开始。 你也可以从以下位置手动触发它：

• 导入 页面（上传后）
• 思维导图 页面（当书签未分类时）
• 侧边栏中的 分类 页面

四阶段管道

该管道是 增量式 的 — 如果中断，它会从中断处继续。使用 "重新运行全部（强制所有）" 以重新分析已经处理过的书签。

功能

🔍 AI 搜索

跨所有收藏数据的自然语言查询：

• “有关加密货币崩盘的搞笑表情包”
• “React Hooks 教程”
• “比特币价格图表”
• “最佳 AI 编程工具”

同时搜索推文文本、图像 OCR、视觉标签、语义标签和类别，使用全文搜索索引 (FTS5) 并进行 Claude 语义重新排序。结果按相关性排名，并为每个匹配项生成 AI 解释。

🗺️ 思维导图

显示按类别组织的所有收藏的交互式力导向图：

• 展开/折叠任意类别以查看其收藏
• 点击收藏节点以在 X 打开原始推文
• 按类别的颜色编码图例
• 如果收藏尚未分类，内联 AI 分类 按钮可在不离开页面的情况下启动流程

📚 浏览与筛选

• 网格视图（瀑布流布局）或 列表视图
• 按类别、媒体类型（照片/视频）或搜索文本筛选
• 按最新或最旧排序
• 每页 24 项的分页
• 活动筛选标签 — 可单独或全部移除
• 悬停任意卡片以下载媒体或跳转到原始推文

⚙️ 类别

8 个默认类别，预设有 AI 可读描述：

创建自定义类别，可设置名称、颜色和可选描述。描述会在分类时直接传递给 AI —— 描述越具体，结果越准确。

📤 导出

• CSV — 与电子表格兼容的所有字段
• JSON — 完整结构化数据导出
• ZIP — 导出某个类别的书签及所有媒体文件，带有 manifest.csv

⌨️ 命令面板

按下 Cmd+K（Mac）或 Ctrl+K（Windows/Linux）即可从应用中的任何位置搜索所有书签。

配置

所有设置都可以在 Settings（设置） 页面 /settings 或通过环境变量进行管理：

自定义 API 端点

将 Siftly 指向任何兼容 Anthropic 的服务器：

ANTHROPIC_BASE_URL=http://localhost:8080

架构

siftly/
├── app/
│   ├── api/
│   │   ├── analyze/images/   # Batch image vision analysis (GET progress, POST run)
│   │   ├── bookmarks/        # List, filter, paginate, delete
│   │   │   └── [id]/categories/ # Per-bookmark category management
│   │   ├── categories/       # Category CRUD
│   │   │   └── [slug]/       # Individual category operations
│   │   ├── categorize/       # 4-stage AI pipeline (start, status, stop)
│   │   ├── export/           # CSV, JSON, ZIP export
│   │   ├── import/           # JSON file import with dedup + auto-pipeline trigger
│   │   │   ├── bookmarklet/  # Bookmarklet-specific import endpoint
│   │   │   └── twitter/      # Twitter-specific import endpoint
│   │   ├── link-preview/     # Server-side OG metadata scraper
│   │   ├── media/            # Media proxy/download endpoint
│   │   ├── mindmap/          # Graph nodes + edges for visualization
│   │   ├── search/ai/        # Natural language semantic search (FTS5 + Claude)
│   │   ├── settings/         # API key + model config
│   │   │   ├── cli-status/   # Claude CLI auth detection endpoint
│   │   │   └── test/         # API key validation endpoint
│   │   └── stats/            # Dashboard stats
│   ├── ai-search/            # AI search page
│   ├── bookmarks/            # Browse, filter, paginate
│   ├── categories/           # Category management
│   │   └── [slug]/           # Category detail page
│   ├── categorize/           # Pipeline monitor with live progress
│   ├── import/               # 3-step import flow (instructions → upload → categorize)
│   ├── mindmap/              # Interactive graph
│   ├── settings/             # Configuration
│   └── page.tsx              # Dashboard
│
├── components/
│   ├── mindmap/              # Mindmap canvas, nodes, edges
│   │   ├── mindmap-canvas.tsx
│   │   ├── category-node.tsx
│   │   ├── tweet-node.tsx
│   │   ├── root-node.tsx
│   │   ├── chain-edge.tsx
│   │   └── mindmap-context.ts
│   ├── command-palette.tsx   # Cmd+K global search
│   ├── nav.tsx               # Sidebar navigation
│   └── theme-toggle.tsx      # Light/dark mode
│
├── lib/
│   ├── categorizer.ts        # AI categorization logic + default categories
│   ├── claude-cli-auth.ts    # Claude CLI OAuth session detection (macOS keychain)
│   ├── vision-analyzer.ts    # Image analysis + batch semantic tagging
│   ├── image-context.ts      # Shared image context builder
│   ├── fts.ts                # SQLite FTS5 full-text search index
│   ├── rawjson-extractor.ts  # Entity extraction from raw tweet JSON
│   ├── parser.ts             # Multi-format JSON parser
│   ├── exporter.ts           # CSV, JSON, ZIP export
│   ├── types.ts              # Shared TypeScript types
│   └── db.ts                 # Prisma client singleton
│
├── prisma/
│   └── schema.prisma         # SQLite schema
│
├── start.sh                  # One-command launcher (install + DB setup + open browser)
└── CLAUDE.md                 # Instructions for Claude Code AI assistant

数据库模式

Bookmark          — tweet text, author, date, raw JSON, semantic tags, enrichment metadata
  ├── MediaItem   — images / videos / GIFs with AI-generated image tags
  └── BookmarkCategory — category assignments with confidence scores (0–1)

Category          — name, slug, hex color, AI-readable description
Setting           — key-value store (API keys, model preferences)
ImportJob         — tracks import file status and progress

Prisma SQLite FTS5

Siftly 使用 Prisma 迁移进行关系模式更改。在开发中，当模式更改时运行 npx prisma migrate dev --name <change-name>。对于运行时/生产风格的启动，使用 npx prisma migrate deploy 应用已提交的迁移。FTS5（bookmark_fts）在运行时由 lib/fts.ts 管理，而不是在 schema.prisma 中管理。这是有意为之，因为 Prisma 目前不能直接建模 SQLite 虚拟表定义。

有关 Prisma 命令和工作流的详细信息，请参见：

• https://www.prisma.io/docs/orm/prisma-migrate/workflows/development-and-production
• https://www.prisma.io/docs/orm/prisma-client/setup-and-configuration/generating-prisma-client

技术栈

开发

# One-command start (installs, sets up DB, opens browser)
./start.sh

# Or manually:
npm install
npx prisma generate
npx prisma migrate dev --name init
npx next dev

# Type check
npx tsc --noEmit

# Open database GUI
npx prisma studio

# Build for production
npm run build && npm start

自定义类别

在 lib/categorizer.ts 中编辑 DEFAULT_CATEGORIES 。每个条目需要：

{
  name: 'My Category',       // Display name
  slug: 'my-category',       // URL-safe identifier (must be unique)
  color: '#6366f1',          // Hex color shown in UI
  description: '...',        // Natural language description — used verbatim in AI prompts
}

description 字段直接决定 AI 如何对书签进行分类。请具体说明。

添加已知工具

在 lib/rawjson-extractor.ts 中将域字符串添加到 KNOWN_TOOL_DOMAINS，以便实体提取器自动识别推文数据中指向这些工具的链接。

隐私

• 所有数据都存储在您计算机上的 本地 SQLite 文件中
• 唯一的外部调用是您配置的 AI 提供者（推文文本、图像数据）
• 没有遥测，没有跟踪，也不需要账户
• 您的书签永远不会接触任何第三方服务器，除了您配置的 AI 端点

支持开发

如果 Siftly 为你节省了时间，考虑留下小费 ☕

许可证

MIT — 参见 LICENSE