Karakeep 书签管理技能
通过官方 CLI 让 AI 代理替你收藏、搜索和整理自托管书签库中的链接、笔记、图片与 PDF。
技能文档透明：凭据解析顺序明确，配置文件以0600权限写入且覆盖前询问，删除类操作明确要求先与用户确认，无越权或隐蔽行为。扣分：技能本身不执行权限控制，依赖外部CLI，回滚机制与数据流(向服务器发送书签数据)仅部分披露。
文档自洽、命令示例一致、错误路径有说明(如语义搜索需配置embedding、游标分页)。扣分：纯静态审阅无法复现CLI关键路径，异常输入下的失败反馈质量未经执行验证，依赖npm安装的@karakeep/cli可用性未验证。
适用场景清晰(增删查管理书签)，边界说明较好(语义搜索前提、--if-exists语义、上限50000字符)。扣分：无明确非适用范围声明，技能与文档均为英文，未说明中文环境适配；默认服务器指向海外cloud.karakeep.app，中国大陆可达性未评估。
文档分层良好(概念→安装→认证→各操作)，有机器可读metadata、homepage、repository链接，许可证AGPL-3.0明确，仓库有SECURITY.md和活跃CI。扣分：技能文件本身无版本号或变更日志，skill与CLI版本同步关系仅一句带过，无FAQ或已知限制清单。
文档结构直接可操作，覆盖核心工作流(添加、搜索、分页、导出、--机器输出)，对Agent使用价值明确高于手工拼HTTP请求。扣分：静态审阅无法验证命令实际输出，边际收益依赖CLI与文档描述一致这一未验证假设。
仓库含真实e2e测试(bookmarks、assets、backups API)和CI工作流，可部分佐证底层API能力。扣分：测试覆盖API而非技能描述的CLI命令路径，无第三方执行证据，静态审阅下复现性有限。
- 技能为纯文档型，依赖用户自行安装并认证@karakeep/cli；未执行验证，命令行为以`karakeep --help`实际输出为准。
- 删除操作(bookmarks/lists/tags删除)不可逆或影响数据，文档要求先向用户确认，Agent调用时应严格遵守。
- 语义/混合搜索需服务端配置embedding与向量存储，未配置时会静默降级为全文搜索。
- 默认服务器为海外cloud.karakeep.app；中国大陆用户应自建实例或显式指定--server-addr，注意网络可达性。
- 发布方未经FollowSkills企业注册表验证，身份按未知处理，不构成加分或扣分依据。
这个 Skill 能做什么，适合哪些场景？
Karakeep（前身为 Hoarder）是一个可自托管的书签应用，支持收藏链接、笔记、图片和 PDF，并提供基于 LLM 的自动打标与全文检索。该技能指导代理使用官方 karakeep CLI 对实例进行程序化操作，涵盖书签的增删改查、搜索、列表与标签管理、内容读取和资产下载。CLI 通过 npm 安装，凭据可用环境变量 KARAKEEP_API_KEY 与 KARAKEEP_SERVER_ADDR 或配置文件提供。它是 README 中明确提及的官方技能，面向 OpenClaw、Hermes 等 LLM 代理。
该技能不执行代码脚本，而是一份操作手册：指导代理运行 karakeep CLI 完成以下操作——用 bookmarks add 添加链接、文本笔记或上传图片/PDF 资产；用 bookmarks search 以限定符查询语言（如 is:fav、#tag、after:date）做全文搜索，或在实例启用语义搜索时使用 semantic/hybrid 模式；用 bookmarks get/content 分页读取书签元数据与可读内容（Markdown 或纯文本，每块最多 5 万字符）；用 bookmarks update、update-tags 及 lists/tags/highlights 子命令归档、收藏、打标、管理列表与合并标签；用 assets download 下载附件；用 -- 获得机器可读输出；还支持导入 SingleFile HTML 归档。所有命令都连接到用户自己部署的 Karakeep 实例或其云服务。
- 自托管用户在浏览网页时想让代理把找到的文章按标签存入自己的 Karakeep 实例，稍后再读。
- 重度收藏者想批量整理书签：按 Smart List 查询筛选、合并重复标签、归档旧内容。
- 研究者想让代理从已存的 PDF/论文书签中提取正文要点并下载附件资产。
- 团队协作场景中，用户向共享列表添加或移除书签，并利用规则引擎和 RSS 订阅自动收纳新内容。
- 开发者或自动化脚本通过 -- 输出将 Karakeep 数据接入其他工作流。
这个 Skill 有哪些优点和局限？
- 官方技能，随 CLI 一起维护，karakeep skill 命令可打印与已装 CLI 版本一致的最新说明。
- 覆盖面完整：从添加、搜索、读取、更新到导入、下载资产均有对应命令。
- 查询语言表达力强（布尔逻辑、标签、列表、日期、来源等限定符），并支持语义/混合搜索。
- -- 全局选项便于程序化消费；凭据解析顺序清晰（全局选项 > 环境变量 > 配置文件）。
- 必须有已部署的 Karakeep 实例和有效 API key，无法独立使用。
- 语义/混合搜索依赖实例端配置（嵌入与向量存储），未配置时能力受限。
- 源材料未提供本技能在具体代理平台上的独立测试记录。
- 删除命令不可逆风险由代理承担，技能只要求人工确认，无额外防护。
如何安装这个 Skill？
- 确保已有一个可访问的 Karakeep 实例（自托管或 cloud.karakeep.app）。2. 安装 CLI：npm install -g @karakeep/cli（或用 Docker：docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help）。3. 在 Karakeep 设置页创建 API key。4. 认证：运行 karakeep auth init 按提示输入服务器地址和 API key（配置以 0600 权限写入 ~/.config/karakeep/config.），或设置环境变量 KARAKEEP_API_KEY 与 KARAKEEP_SERVER_ADDR。技能文件本身按 Agent Skills 标准放置在技能目录的 skills/SKILL.md。
如何使用这个 Skill？
对代理说例如："帮我把 https://example.com 这篇文章存进 Karakeep，打上 reading 标签"、"在 Karakeep 里搜索最近一周收藏的、带 #important 标签且未归档的链接"或"读取书签 <id> 的正文，只取前 2 万字符"。代理将运行类似命令：karakeep bookmarks add --link <url> --tag-name reading；karakeep bookmarks search "#important -is:archived after:2026-01-01"；karakeep bookmarks content <id> --format markdown --max-chars 20000。需要注意：语义搜索模式要求实例已配置嵌入模型与向量存储；删除类命令技能要求先与用户确认。
这个 Skill 与同类方案有什么区别？
README 将 Karakeep 与 Pocket（已停止服务）、Linkwarden、Wallabag、Shiori、memos、Raindrop.io、mymind 等对比：Karakeep 的差异点在于自托管优先 + AI 自动打标 + 链接/笔记/图片/PDF 全类型收藏 + 完整 CLI 与官方代理技能。若你只需纯链接的只读归档，Wallabag 或 Linkwarden 可能更简单；若想要带 AI 和代理自动化的自托管方案，Karakeep 更合适。