Karakeep Agentic Skills 实战指南让 AI 助手通过 CLI 自然语言管理书签【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarderKarakeep书签全能管理应用支持链接、笔记与图片为 AI 助手提供了一套官方 Agentic Skills智能体技能通过自然语言对话即可完成书签的搜索、保存与整理。本文以 docs/docs/05-integrations/07-agentic-skills.md 为骨架结合仓库中 skills/SKILL.md 技能定义与 apps/cli 官方 CLI 源码完整讲解技能安装、CLI 认证、书签增删查改、搜索语法、语义搜索与机器可读输出帮助你把 Karakeep 接入任何支持 Skill 的 AI Agent 工作流。什么是 Agentic Skills为什么它适合 KarakeepAgentic Skills 是一段结构化的、教 AI 助手如何操作某个系统的指令集。Karakeep 将官方技能打包进karakeep/cli让大模型代理可以通过自然语言调用 CLI 来读写你的书签库而不是直接手写 HTTP 请求。从仓库的 skills/SKILL.md 头部元数据可以看到技能的设计取向name: karakeep描述为Official skill for how to use karakeep (the bookmark manager) and interact with it programmatically官方技能如何使用 Karakeep 书签管理器并与之程序化交互metadata.openclaw.envVars声明了两个可选环境变量KARAKEEP_API_KEY与KARAKEEP_SERVER_ADDR并标注primaryEnv: KARAKEEP_API_KEYrequires.bins要求系统中存在karakeep可执行文件cliHelp指向karakeep --helpinstall段声明通过 Node 包karakeep/cli安装并提供karakeepbin。技能的核心使用原则在 skills/SKILL.md 中有明确交代优先使用 CLI 而非直接编写 HTTP 请求。当命令未覆盖到某个场景时运行karakeep --help或karakeep command --help而karakeep skill会直接打印随 CLI 一起打包的技能文件——它可能比单独安装的副本更新。这一点在源码中有直接对应apps/cli/src/commands/skill.ts中的skillCmd会在构建时将仓库根目录的skills/SKILL.md内容嵌入 CLI回退方案是从../../../../skills/SKILL.md读取并原样输出到标准输出。这意味着技能与 CLI 同版本发布始终保持同步。安装技能ClawHub 与 skills.sh 两条路径原文档给出了两条技能安装渠道方式一ClawHub技能已发布在 ClawHub 的 Karakeep 官方主页clawhub.ai/karakeep/karakeep-app适用于使用 ClawHub 生态的 Agent 环境直接在 Hub 中搜索并添加即可。方式二skills.shnpx 方式npx skills add karakeep-app/karakeep该命令从 skills.sh 注册表拉取技能包并写入当前 Agent 环境的技能目录。两种方式安装的是同一个官方技能区别仅在于分发渠道。需要强调的是技能只是说明书真正的执行引擎是karakeepCLI。技能元数据中requires.bins: [karakeep]说明 Agent 环境必须先具备 CLI 二进制技能才会生效。安装 Karakeep CLI技能通过官方 CLI 驱动 Karakeep 实例安装方式有两种npm 全局安装npm install -g karakeep/cli安装后可执行文件为karakeep这一点由 apps/cli/package.json 中的bin字段karakeep: dist/index.mjs保证。Docker 容器运行docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help以容器方式运行无需在宿主机安装 Node 环境适合隔离或一次性使用场景。CLI 的命令树定义在 apps/cli/src/index.ts通过commander注册了admin、assets、auth、bookmarks、highlights、lists、tags、whoami、migrate、wipe、dump与skill等子命令其中auth与skill两个命令不需要认证即可执行doesNotRequireAuthentication逻辑其余命令在preAction钩子中统一解析并注入全局凭据。认证API Key 的三种注入方式在 Karakeep 的 Web 设置页面创建 API Key 后技能推荐最简洁的持久化配置方式karakeep auth init karakeep whoamikarakeep whoami用于验证认证是否成功。auth init的行为由 apps/cli/src/commands/auth.ts 实现交互式提示输入服务器地址与 API KeyTTY 环境下提供默认值与既有值回显直接回车沿用配置文件写入$XDG_CONFIG_HOME/karakeep/config.json当XDG_CONFIG_HOME未设置时回退到~/.config/karakeep/config.json见 apps/cli/src/lib/config.ts 的getConfigPath文件以0600权限写入mode: 0o600并显式chmod保证 API Key 不被同机其他用户读取若配置文件已存在会先询问是否更新非交互环境下必须使用--force覆盖否则直接报错退出。非交互式初始化CI、容器、Agent 脚本场景可将全局选项放在auth init之前karakeep --server-addr https://karakeep.example.com --api-key $KARAKEEP_API_KEY auth init --force凭据解析顺序技能文档明确且与 apps/cli/src/index.ts 的resolveGlobalOptions一致全局命令行选项--api-key与--server-addr优先级最高环境变量KARAKEEP_API_KEY与KARAKEEP_SERVER_ADDR由commander的.env()声明注入持久化配置文件。服务器地址默认值为https://cloud.karakeep.app见 apps/cli/src/lib/config.ts 的DEFAULT_SERVER_ADDRAPI Key 无默认值、缺失时报错并提示配置位置。如果你不想修改已保存的配置也可以单次执行时临时指定凭据karakeep --api-key key --server-addr addr whoami添加与导入书签添加三类书签Karakeep 的书签分三种类型链接Link可抓取标题、描述、图片、截图、可读内容与整页归档、文本Text/Note笔记与文本片段和资源Asset图片与 PDF。技能文档对应的 CLI 用法# 添加一个或多个链接重复 --link 可添加多个 URL karakeep bookmarks add --link https://example.com # 保存时同时附加标签和列表归属 karakeep bookmarks add --link https://example.com --tag-name reading --tag-name work --list-id list-id # 直接添加文本或从 stdin 读取 karakeep bookmarks add --note Review the proposal --title Reminder printf %s\n Long note | karakeep bookmarks add --stdin # 上传图片或 PDF 作为资源书签 karakeep bookmarks add --asset ./paper.pdf --title Research paper从 apps/cli/src/commands/bookmarks.ts 的add命令实现看链接与文本都会调用 tRPC 的bookmarks.createBookmark并统一标记source: cli这正是搜索语法中source:cli的来源--stdin通过fs.readFileSync(0, utf-8)读取标准输入存为文本书签--asset上传后同样支持--tag-name/--list-id附加标签与列表。技能文档还强调了去重语义保存已存在的链接不会产生重复记录。普通保存含 CLI会从归档中恢复既有书签并将其移动到顶部且调用方未提供的元数据保持不变——这对 Agent 幂等操作非常友好。导入 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。带recrawl的变体会在存储归档后排队触发一次爬取用于刷新页面快照与可读内容。查找书签三种搜索模式与搜索查询语言搜索查询语言技能文档完整定义了 Karakeep 的搜索语法底层由 packages/shared/searchQueryParser.ts 的typescript-parsec词法/语法分析器实现限定符与and/or/括号的优先级均在 lexer 规则中体现条件之间的空格表示and可用and、or与括号组织显式布尔逻辑限定符前加-或!表示取反不属于限定符的文本会作为搜索关键词全文搜索。限定符含义示例is:fav收藏的书签is:favis:archived已归档的书签-is:archivedis:tagged至少带一个标签-is:taggedis:inlist至少属于一个列表is:inlistis:link链接书签is:linkis:text文本书签is:textis:media图片或 PDF 书签is:mediais:broken爬取失败或非 2xx 响应的书签is:brokenurl:valueURL 子串url:github.comtitle:value标题子串title:release notes#tag或tag:tag标签名#important、tag:in progresslist:name列表名list:to reviewafter:date创建于YYYY-MM-DD及之后after:2026-01-01before:date创建于YYYY-MM-DD及之前before:2026-06-01age:range按创建时长筛选单位d/w/m/yage:1w、age:6mfeed:name来源 RSS 订阅源feed:Hackernewssource: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 machine learning is:fav -is:archived三种搜索模式bookmarks search支持--search-mode参数源码校验取值必须为fts、semantic、hybrid三者之一默认ftsfts默认全文搜索semantic基于书签向量的语义搜索需要非空搜索文本、已配置 embedding 与向量库提供方低于相似度阈值的结果会被过滤因此返回数量可能少于请求的--limithybrid融合全文与语义排序当查询只包含限定符或语义基础设施不可用时自动回退为纯全文搜索。语义/混合模式仅在语义排序运行时才支持按相关性relevance排序且实例需开启语义搜索与自动 embedding 索引。# 全文搜索 限定符 karakeep bookmarks search rust is:fav --limit 10 # 语义搜索找概念相关的内容 karakeep bookmarks search durable background jobs --search-mode semantic # 混合搜索关键词 语义排序 karakeep bookmarks search rust async patterns #programming --search-mode hybrid # 包含存储内容并翻完所有分页 karakeep bookmarks search incident review --include-content --all结构化筛选bookmarks list如果不需要搜索语言bookmarks list提供结构化过滤karakeep bookmarks list --list-id list-id --include-archived karakeep bookmarks list --tag-id tag-id --all分页约定不带--all时若还有下一页list/search 命令会打印一个 cursor将其通过--cursor cursor传回即可继续翻页。读取内容与下载资源获取单个书签元数据karakeep bookmarks get bookmark-id karakeep bookmarks get bookmark-id --include-content--include-content会把存储的完整内容一并放入结果源码中该选项默认false。对于长内容使用有界的 readable-content 命令返回 Markdown 或纯文本内容超出时打印续读 cursorkarakeep bookmarks content bookmark-id --format markdown --max-chars 20000 karakeep bookmarks content bookmark-id --cursor cursor单次最大块大小为50,000 个 Unicode 字符源码中MAX_READABLE_CONTENT_MAX_CHARS校验max-chars必须是 1 到该上限之间的整数这一上限专为 LLM 上下文窗口设计避免一次性灌入超长正文。下载附件或资源asset ID 由bookmarks get输出中的Asset Id/Attachments字段给出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列表Listskarakeep 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-idlists create的默认类型是manual手动列表--type smart配合--query创建智能列表其成员由保存的搜索查询动态决定匹配的书签变化时自动更新apps/cli/src/commands/lists.ts 中create命令将query原样传给lists.create。lists list以树形输出展示嵌套列表及各列表书签数。标签Tagskarakeep tags list karakeep tags get --name important karakeep tags merge --into target-tag-id --from tag-id tag-idtags merge支持把多个标签合并进目标标签适合整理重复或近义标签。高亮Highlightskarakeep highlights list --bookmark bookmark-id karakeep highlights get highlight-id书签、列表、标签与高亮均提供 delete 命令技能文档特别提醒删除类操作前必须先与用户确认目标避免 Agent 误删数据。机器可读输出--json 全局选项当结果由另一个程序或 Agent 消费时使用全局--json选项且必须放在命令之前以避免歧义karakeep --json bookmarks search #work --all karakeep --json whoami--json由 apps/cli/src/index.ts 的全局Option声明所有子命令共享在 apps/cli/src/commands/bookmarks.ts 中printBookmarkDetail等输出函数会检测getGlobalOptions().json为真时通过printObject输出结构化 JSON书签的tags数组会被规范化为标签名字符串列表否则输出带 chalk 着色的人类可读卡片含 Id、Type、URL、Tags、Archived、Favourited、Created、Source、Note、Summary、Attachments 等字段。对 Agent 而言JSON 模式是解析结果、决定下一步动作的最可靠接口。与其他集成的关系Agentic Skills 并非孤立的集成方式它与 docs/docs/05-integrations/02-command-line.mdCLI 手册共享同一套karakeep/cli与 docs/docs/05-integrations/03-mcp.mdMCP 服务器位于 apps/mcp相比Skill 的优势是零额外服务、纯指令驱动缺点是依赖 Agent 对指令的遵循能力而 MCP 提供的是确定性的工具协议。RSS 消费/发布与规则引擎自动打标签、收藏、路由到列表以及 Webhook 事件通知则进一步扩展了Agent 之外的自动化维度。常见问题与最佳实践技能未生效确认karakeep命令存在requires.bins校验并运行karakeep skill查看 CLI 内置的最新技能文本是否与你安装的副本一致。认证失败先karakeep --api-key key --server-addr addr whoami单次验证凭据再决定是否写入auth init的持久化配置自托管实例注意服务器地址必须包含协议与端口。长文本截断bookmarks content --max-chars上限 50,000 Unicode 字符配合--cursor续读避免一次性把超长文章灌入 LLM 上下文。搜索结果偏少语义搜索会过滤低于相似度阈值的结果必要时改用hybrid模式或确认实例已开启语义搜索与 embedding 索引。幂等保存重复保存同一链接不会重复入库会恢复归档并置顶适合 Agent 的保存-校验循环。延伸阅读技能定义全文skills/SKILL.mdCLI 入口与全局选项apps/cli/src/index.ts认证与配置apps/cli/src/commands/auth.ts、apps/cli/src/lib/config.ts书签子命令实现apps/cli/src/commands/bookmarks.ts搜索查询语言解析器packages/shared/searchQueryParser.ts相关集成文档命令行、MCP、SingleFile【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考