karakeep

Karakeep

Karakeep 是一款开源书签管理器，用于收集、整理和搜索链接、笔记、图片与 PDF。使用本技能可通过官方命令行工具操作 Karakeep 实例。

适用场景

当用户要求在 Karakeep 中添加、获取、搜索、整理、导出或以其他方式管理内容时，使用本技能。

优先使用命令行工具，而不是直接编写 HTTP 请求。若本文未涵盖某条命令，请运行 karakeep --help 或 karakeep <command> --help。karakeep skill 会输出已安装命令行工具内置的技能文件，该版本可能比单独安装的副本更新。

核心概念

Karakeep 存储三种书签类型：

• 链接。Karakeep 可以获取页面标题、描述、图片、截图、可读正文和整页存档。
• 文本。以书签形式保存的笔记和文本片段。
• 资源。以书签形式上传的图片和 PDF。

书签可以包含标签、笔记、高亮、收藏和归档状态，并且可以属于一个或多个列表。手动列表包含用户选定的书签。智能列表使用已保存的搜索查询，并会随匹配书签的变化而更新。

保存已存在的链接不会创建重复书签。对于普通保存操作（包括通过命令行工具保存），Karakeep 会从归档中恢复已有书签，并将其移至顶部。调用方未提供的元数据保持不变。

Karakeep 可以订阅 RSS 源，也可以将列表发布为 RSS 源。其规则引擎可以为新书签添加标签、设为收藏或将其分配到列表。Webhook 会报告书签事件。

搜索查询语言

条件之间的空格表示 and。使用 and、or 和圆括号来表达明确的布尔逻辑。在限定词前加 - 或 ! 可对其取反。不属于限定词的文本将作为搜索文本。

限定词	含义	示例
is:fav	已收藏的书签	is:fav
is:archived	已归档的书签	-is:archived
is:tagged	至少带有一个标签的书签	-is:tagged
is:inlist	至少属于一个列表的书签	is:inlist
has:notes	备注非空的书签	has:notes
has:highlights	至少有一条高亮的书签	-has:highlights
is:link	链接类书签	is:link
is:text	文本类书签	is:text
is:media	图片或 PDF 类书签	is:media
is:broken	抓取失败或返回非 2xx 响应的书签	is:broken
url:<value>	URL 子串匹配	url:github.com
title:<value>	标题子串匹配	title:"release notes"
#<tag> 或 tag:<tag>	标签名称	#important, tag:"in progress"
list:<name>	列表名称	list:"to review"
after:<date>	创建于 YYYY-MM-DD 当天或之后	after:2026-01-01
before:<date>	创建于 YYYY-MM-DD 当天或之前	before:2026-06-01
age:<range>	创建时长，使用 d、w、m 或 y	age:<1w, age:>6m
feed:<name>	来源 RSS 源	feed:Hackernews
source:<value>	捕获来源	source:cli, -source:rss

有效的捕获来源包括 api、web、cli、mobile、extension、singlefile、rss 和 import。

示例：

is:fav after:2026-01-01 #important
is:archived and (list:reading or #work)
-is:tagged or -is:inlist
has:notes -has:highlights
machine learning is:fav -is:archived

安装命令行工具

npm install -g @karakeep/cli

也提供容器镜像：

docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help

身份验证

在 Karakeep 设置页面中创建 API 密钥。最简单的持久化配置如下:

karakeep auth init
karakeep whoami

auth init 会提示输入服务器地址和 API 密钥。它会将配置写入 $XDG_CONFIG_HOME/karakeep/config.json(文件权限为 0600);若未设置 XDG_CONFIG_HOME,则写入 ~/.config/karakeep/config.json。如果文件已存在,它会先询问是否覆盖。使用 --force 可在不确认的情况下直接覆盖。

如需非交互式设置,请将全局选项放在 auth init 之前:

karakeep --server-addr "https://karakeep.example.com" --api-key "$KARAKEEP_API_KEY" auth init --force

命令行工具按以下顺序解析凭据:

1. 全局命令选项 --api-key 和 --server-addr。
2. 环境变量 KARAKEEP_API_KEY 和 KARAKEEP_SERVER_ADDR。
3. 持久化的配置文件。

服务器地址默认为 https://cloud.karakeep.app。API 密钥没有默认值。如需在单次命令中使用而不修改已保存的配置,请使用全局选项:

karakeep --api-key <key> --server-addr <addr> whoami

添加和导入书签

# Add one or more links. Repeat --link for multiple URLs.
karakeep bookmarks add --link "https://example.com"

# Add tags and list membership while saving.
karakeep bookmarks add --link "https://example.com" --tag-name reading --tag-name work --list-id <list-id>

# Add text directly or from stdin.
karakeep bookmarks add --note "Review the proposal" --title "Reminder"
printf '%s\n' "Long note" | karakeep bookmarks add --stdin

# Upload an image or PDF as an asset bookmark.
karakeep bookmarks add --asset ./paper.pdf --title "Research paper"

导入带有原始 URL 的 SingleFile HTML 存档:

karakeep bookmarks import-singlefile ./page.html --url "https://example.com/page"
karakeep bookmarks import-singlefile ./page.html --url "https://example.com/page" --if-exists overwrite-recrawl

--if-exists 支持 skip、overwrite、overwrite-recrawl、append 和 append-recrawl。默认值为 skip。recrawl 变体会在存储存档后排队一次抓取任务。

查找书签

bookmarks search 支持三种模式:

• fts 为默认的全文搜索。
• semantic 搜索书签的向量嵌入。它需要非空的搜索文本,并且需要配置嵌入和向量存储提供方。相似度低于阈值的结果会被省略,因此返回的结果数量可能少于请求的上限。
• hybrid 结合全文搜索和语义搜索的排名。当查询仅包含限定符或语义基础设施不可用时,会回退为全文搜索。

只有在语义排名实际运行时,语义搜索和混合搜索才支持按相关性排序。实例还必须启用语义搜索和自动嵌入索引。

# Full-text search with qualifiers.
karakeep bookmarks search "rust is:fav" --limit 10

# Find conceptually related content even when wording differs.
karakeep bookmarks search "durable background jobs" --search-mode semantic

# Combine keyword and semantic ranking.
karakeep bookmarks search "rust async patterns #programming" --search-mode hybrid

# Include stored content and fetch every result page.
karakeep bookmarks search "incident review" --include-content --all

如需不使用搜索语法的结构化筛选,请使用 bookmarks list:

karakeep bookmarks list --list-id <list-id> --include-archived
karakeep bookmarks list --tag-id <tag-id> --all

若未使用 --all,列表和搜索命令在存在下一页时会打印游标。使用 --cursor <cursor> 将其传回即可获取下一页。

读取内容和下载资源

使用 bookmarks get 获取书签元数据。--include-content 会将已存储的内容包含在结果中。

karakeep bookmarks get <bookmark-id>
karakeep bookmarks get <bookmark-id> --include-content

对于较长的内容,请使用有上限的可读内容命令。它会返回 Markdown 或纯文本,并在仍有剩余内容时打印续读游标。

karakeep bookmarks content <bookmark-id> --format markdown --max-chars 20000
karakeep bookmarks content <bookmark-id> --cursor <cursor>

单个分块的最大大小为 50,000 个 Unicode 字符。按 bookmarks get 显示的资源 ID 下载附件或资源:

karakeep assets download <asset-id> --output ./download.pdf
karakeep assets download <asset-id> --output ./download.pdf --force

更新和整理书签

karakeep bookmarks update <bookmark-id> --title "New title" --description "New description"
karakeep bookmarks update <bookmark-id> --archive
karakeep bookmarks update <bookmark-id> --no-archive
karakeep bookmarks update <bookmark-id> --favourite
karakeep bookmarks update-tags <bookmark-id> --add-tag important --remove-tag inbox

karakeep lists list
karakeep lists create --name "Reading" --icon "📚"
karakeep lists create --name "Recent AI" --icon "🤖" --type smart --query "#ai age:<1m"
karakeep lists get <list-id>
karakeep lists add-bookmark --list <list-id> --bookmark <bookmark-id>
karakeep lists remove-bookmark --list <list-id> --bookmark <bookmark-id>

karakeep tags list
karakeep tags get --name important
karakeep tags merge --into <target-tag-id> --from <tag-id> <tag-id>

karakeep highlights list --bookmark <bookmark-id>
karakeep highlights get <highlight-id>

书签、列表、标签和高亮均提供删除命令。使用前请先与用户确认目标对象。

机器可读输出

当结果将由其他程序或 Agent 使用时,请使用全局选项 --json。为避免歧义,请将其放在命令之前:

karakeep --json bookmarks search "#work" --all
karakeep --json whoami