需要本地同步、搜索、分类 X/Twitter 书签并供…

当你需要把 X/Twitter 书签同步到本地、全文搜索、自动分类，并让 AI Agent 通过 ft 命令查询时，可用这套流程。

适用场景

解决思路

1. 安装 Field Theory CLI：运行 npm install -g fieldtheory。
2. 确认环境满足：Node.js 20+；默认同步模式需要已登录 X/Twitter 的 Google Chrome；Chrome 会话同步仅 macOS 支持，Linux/Windows 需用 OAuth 模式。
3. 验证安装：运行 ft --version 和 ft status。
4. 快速开始同步：运行 ft sync，自动读取 Chrome 会话同步书签。
5. 立即搜索：运行 ft search "machine learning"。
6. 终端探索：运行 ft viz。
7. 数据默认存储于 ~/.ft-bookmarks/。
8. 增量同步：运行 ft sync，只同步新书签。
9. 同步后自动用 LLM 分类：运行 ft sync --classify。
10. 从头全量爬取历史：运行 ft sync --full。
11. 通过 OAuth API 同步（跨平台，无需 Chrome）：运行 ft sync --api。
12. 查看同步状态：运行 ft status。
13. 全文 BM25 搜索：运行 ft search "distributed systems"、ft search "rust async runtime"、ft search "cancer immunotherapy"。
14. 按作者过滤：运行 ft list --author elonmusk。
15. 按分类过滤：运行 ft list --category tool。
16. 按领域过滤：运行 ft list --domain ai。
17. 按日期过滤：运行 ft list --since 2024-01-01。
18. 组合过滤：运行 ft list --category research --domain biology。
19. 按 ID 查看单条书签：运行 ft show 1234567890。
20. 用 LLM 分类：运行 ft classify（需要 LLM 访问）。
21. 用正则分类：运行 ft classify --regex（无需 LLM，更快）。
22. 重建搜索索引并保留已有分类：运行 ft index。
23. 终端仪表盘：运行 ft viz。
24. 查看分类分布：运行 ft categories。
25. 查看主题领域分布：运行 ft domains。
26. 查看顶级作者、语言、日期范围：运行 ft stats。
27. 打印数据目录路径：运行 ft path。
28. 下载书签中的静态图片：运行 ft fetch-media。
29. OAuth 交互设置：运行 ft auth。
30. OAuth 设置后同步：运行 ft sync --api。
31. OAuth token 存于 ~/.ft-bookmarks/oauth-token.json，并设置 chmod 600。
32. 自定义数据目录：在 ~/.zshrc 或 ~/.bashrc 设置 export FT_DATA_DIR=/path/to/custom/dir。
33. 单次命令使用自定义目录：运行 FT_DATA_DIR=/Volumes/external/bookmarks ft sync。
34. 了解数据文件布局：bookmarks.jsonl 是原始书签；bookmarks.db 是 SQLite FTS5 搜索索引；bookmarks-meta.json 是同步游标和元数据；oauth-token.json 是 OAuth 凭据（仅 API 模式）。
35. 定时同步：运行 crontab -e，添加 0 7 * * * ft sync。
36. 定时同步并分类：添加 0 7 * * * ft sync --classify。
37. 每周全量同步：添加 0 0 * * 0 ft sync --full。
38. 分类参考类别：tool（GitHub 仓库、CLI 工具、npm 包、开源）、security（CVE、漏洞、利用、供应链）、technique（教程、演示、代码模式、how-to 线程）、launch（产品发布、公告、just shipped）、research（ArXiv 论文、研究、学术发现）、opinion（观点、分析、评论、线程）、commerce（产品、购物、实体商品）。
39. 直接用 TypeScript/Node.js 读取 bookmarks.jsonl：从 fs、readline、os、path 导入；定义 Bookmark 接口；使用 FT_DATA_DIR ?? join(homedir(), ".ft-bookmarks")；读取 bookmarks.jsonl；逐行 JSON.parse 非空行；可按 category 过滤。
40. 直接查询 SQLite 索引：使用 better-sqlite3；以 readonly 打开 ~/.ft-bookmarks/bookmarks.db；用 FTS5 的 bookmarks MATCH ? ORDER BY rank LIMIT ? 做全文搜索；用 category = ? ORDER BY created_at DESC 按分类过滤。
41. 在 Agent 脚本中通过 shell 调用 ft：使用 child_process.execSync；ftSearch 运行 ft search "${query}"；ftList 拼接 --category、--since、--author 并运行 ft list。
42. 让 AI Agent 用自然语言直接使用 ft：例如“Search my bookmarks for distributed tracing tools and summarize the top 5.”、“Sync any new X bookmarks, then list all research papers from 2025.”、“Find everything I've bookmarked about Rust and categorize it by subtopic.”、“Every morning, run ft sync --classify to keep my bookmarks up to date.”。
43. Claude Code 示例提示：让 Claude Code 使用 ft CLI 搜索 "vector database"，运行 ft search "vector database" --category tool，并挑选最佳开源选项加入项目。
44. 排查 Chrome 会话未找到：确保 Chrome 已打开并登录 X，重试 ft sync；若仍失败，运行 ft auth 和 ft sync --api。
45. 排查同步卡住或返回 0 条：运行 ft status；运行 ft sync --full；运行 ls -la ~/.ft-bookmarks/ 检查权限。
46. 排查搜索无结果：运行 ft index 重建索引；运行 ft stats 验证书签存在；运行 wc -l ~/.ft-bookmarks/bookmarks.jsonl。
47. 排查分类未运行：LLM 分类需要 LLM，改用 ft classify --regex，或 ft sync --classify --regex。
48. 重置所有数据：运行 rm -rf ~/.ft-bookmarks，然后运行 ft sync。
49. 排查自定义数据目录问题：运行 echo $FT_DATA_DIR；运行 ft path；运行 mkdir -p "$FT_DATA_DIR"；运行 chmod 755 "$FT_DATA_DIR"。
50. 安全注意：所有数据仅本地，无遥测；同步时临时读取 Chrome cookies 且不单独存储；OAuth token 按 chmod 600 保存，视为密码；默认同步用 X 内部 GraphQL API，--api 用官方 v2 API。
51. 平台支持：macOS 支持 ft sync（Chrome session）、ft sync --api、搜索/分类/viz；Linux/Windows 不支持 Chrome session，必须先 ft auth 再用 ft sync --api，搜索/分类/viz 可用。

适用边界 · 注意事项

• Linux/Windows 不能使用默认 Chrome 会话同步，必须改用 OAuth API 模式。
• 需要安装 Node.js 20+ 和 fieldtheory CLI，并拥有 X/Twitter 账号与书签数据；不想本地安装 CLI 或没有 X 账号时不适用。
• LLM 分类需要 LLM 访问；无 LLM 时只能用 --regex 分类，不能使用 ft classify 默认 LLM 分类。