facetmark · 连接工具与备份

浏览器扩展#

从地址栏搜你的书签，以及不离开当前页面就把它存下来。扩展连的是网页界面连的同一个本机服务。

先起服务：facetmark serve。
从仓库里的 extension/ 加载扩展——Chrome：chrome://extensions，开开发者模式，加载已解压的扩展程序。
打开它的选项。服务在默认端口上它会自己配对；否则把 facetmark token 的输出粘进去。

验证连接

在扩展里搜索一个已知书签，确认返回结果。扩展把请求发到你配置的服务地址；服务端还可能调用已配置的模型。远程使用时检查地址、令牌和浏览器权限。

Claude、Cursor，以及任何说 MCP 的东西#

facetmark 自带一个 MCP 服务，所以助手可以把「搜你的书签」当成一个工具来用，而不是你手动往对话框里粘链接。

先手动跑一下

facetmark mcp

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "facetmark": {
      "command": "facetmark",
      "args": ["mcp"]
    }
  }
}

Cursor 在它自己的 MCP 设置里是同样的形状。如果编辑器看到的 PATH 里没有 facetmark，就写绝对路径——几乎每一份「工具一直不出现」的反馈都是这个原因。

助手能做什么、不能做什么

它能搜索、能读一条书签、能列时段、能在你的库上提问。它不能删任何东西，不能写配置，也碰不到数据库以外的地方。

验证工具是否可用

重启客户端，确认工具列表中出现 facetmark，再搜索一个已知标题。GUI 客户端可能没有终端中的 PATH 和环境变量；必要时使用可执行文件的绝对路径并显式配置环境。

karakeep#

如果你的链接都放在 karakeep 里，facetmark 可以从那边建索引，而不是从浏览器导出文件。

具体安装和调用方式见 karakeep 接入参考。先用少量页面对照直接检索结果，再决定是否接入整个书签库。

有实测，值得在你投入之前先知道

经 karakeep 自己的关键词抽取绕一圈，代价是 Recall@5 掉 0.81 个百分点（CI95 −2.44 到 +0.81），并且和直接建索引在第一名上只有 79.06% 一致。词表会塌缩：19,016 个不同词项变成 13 个。仓库里记下来的结论是 roundtrip_unfaithful——能用，但不等价。能直接索引页面就直接索引。

命令行#

页面能做的都在这里，还有几样页面做不到的。任何一条后面都能加 --help。

命令	作用
`facetmark import`	读入一个书签导出文件
`facetmark browsers`	找出这台机器上已有的书签文件
`facetmark index`	建索引，或者补齐
`facetmark reindex`	全部从头再建一遍
`facetmark search`	在终端里搜
`facetmark show`	一条书签的全部信息
`facetmark sessions`	列出所有时段
`facetmark stats`	「库」那一屏的文字版
`facetmark health`	找死链
`facetmark serve`	网页界面和 API
`facetmark mcp`	MCP 服务
`facetmark token`	打印配对令牌
`facetmark config path`	配置写到哪
`facetmark config show`	所有配置，敏感项掩码
`facetmark migrate`	把旧数据库升上来
`facetmark demo`	一个假的库，用来到处点点看
`facetmark eval`	重跑那些检索实测
`facetmark version`	版本

facetmark demo 是判断你到底要不要用这东西最实在的办法：它用生成的页面搭出一个库，不要 key 不联网，让你在导入任何自己的东西之前先把每一屏都点一遍。

备份与恢复#

可移植的书签导出

shell

facetmark export bookmarks-backup.json

导出保存书签数据，恢复后需要重建衍生索引。请先在独立数据目录验证恢复；不要覆盖现有书签库。

shell

facetmark import bookmarks-backup.json
facetmark index

保留正文和向量的完整备份

用 facetmark stats 确认数据库路径。停止服务及所有使用该库的 CLI / MCP 进程后，复制数据库文件；如果仍有 -wal / -shm 文件，勿直接丢弃，应使用 SQLite 的备份机制取得一致快照。

恢复后检查

把备份放入独立目录，以该数据库运行 facetmark stats，检查数量并搜索已知标题。升级版本前保留原始备份。配置文件与配对令牌需要单独保管，其中可能包含密钥。