Karakeep 高级工作流实战规则引擎、API 与 Webhook 自动化指南【免费下载链接】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原 Hoarder是一款可自托管的收藏一切应用书签、笔记与图片而真正让它从存储工具进阶为自动化枢纽的是文档 docs/versioned_docs/version-v0.30.0/04-using-karakeep/advanced-workflows.md 所描述的三大进阶能力规则引擎Rule Engine、API 与 Webhook。读完本文你将掌握如何用 if-this-then-that 规则自动打标签、收藏、归档、路由书签到列表如何用与 App 同源的 API 编写脚本与定时任务以及如何订阅书签事件把 Karakeep 与自己的系统写作队列、团队聊天、通知机器人等无缝打通构建端到端自动化。规则引擎if-this-then-that 式的自动化规则引擎是 Karakeep 内置的条件动作系统当某个事件发生时若书签满足条件则自动执行一系列动作——自动打标签、收藏、归档或把书签路由进列表。它的典型用途是保持收件箱整洁自动归档新闻通讯、按域名自动打标签、标记视频类书签等。规则由三部分构成定义见 packages/shared/types/rules.ts事件Event触发规则的时机条件Condition书签必须满足的匹配规则可为空即总是为真动作Action匹配成功后执行的操作可同时配置多个。可触发的事件规则可以绑定以下 7 类事件zRuleEngineRuleEventSchema见 rules.ts事件类型说明附加字段bookmarkAdded新书签被添加无tagAdded书签被添加了某个标签tagIdtagRemoved书签被移除了某个标签tagIdaddedToList书签被加入列表listIds可多个removedFromList书签被移出列表listIds可多个favourited书签被收藏无archived书签被归档无可用的条件条件既可以是单一条件也可以是用and/or组合的嵌套表达式zRuleEngineConditionSchema允许递归最大嵌套深度为 10条件类型语义alwaysTrue恒真不设条件urlContains/urlDoesNotContainURL 包含 / 不包含指定子串titleContains/titleDoesNotContain标题包含 / 不包含指定子串importedFromFeed书签来自指定 RSS 订阅源feedIdbookmarkTypeIs书签类型为link/text/assetbookmarkSourceIs书签来源为指定渠道如 API、CLI、浏览器扩展等hasTag书签带有指定标签tagIdisFavourited书签已被收藏isArchived书签已被归档and/or条件组合可嵌套深度上限 10条件在真实书签数据上的求值逻辑见 packages/trpc/lib/ruleEngine.ts 的doesBookmarkMatchConditions例如urlContains实际执行link.url.includes(str)titleContains会同时匹配书签自身标题与 link 抓取到的页面标题importedFromFeed通过书签关联的rssFeeds判断hasTag则检查tagsOnBookmarks关联表。可执行的动作动作类型效果addTag/removeTag为书签添加 / 移除指定标签tagIdaddToList/removeFromList把书签加入 / 移出指定列表listIddownloadFullPageArchive触发低优先级爬虫队列为书签生成整页归档archiveFullPagefavouriteBookmark将书签标记为收藏archiveBookmark将书签标记为归档动作的实际执行在executeAction中完成ruleEngine.tsaddTag通过onConflictDoNothing幂等插入tagsOnBookmarksdownloadFullPageArchive会把任务投入LowPriorityCrawlerQueue并设置groupId、低优先级与基于载荷的幂等键buildCrawlIdempotencyKey保证同一请求不会重复入队。规则的校验与生命周期一条规则包含id、name非空、description、enabled、event、condition与actions至少一个。创建和更新时会经过superRefine校验rules.ts事件与条件、动作引用的标签 / 列表必须存在由 routers/rules.ts 的ensureTagListOwnership中间件在创建 / 更新时逐一校验所有权条件嵌套深度超过 10 会被拒绝and/or至少需要一个子条件。规则的增删改查create/update/delete/list均通过 tRPC 暴露并带有规则所有权检查ensureRuleOwnership。规则引擎的底层运行机制从源码结构看规则求值并不在请求链路内同步完成而是异步队列化处理书签发生变更创建、打标签、加列表、收藏、归档等时业务代码调用RuleEngine.triggerOnEventruleEngine.ts该方法先通过matchesAnyRule快速判断该用户是否存在事件匹配的已启用规则仅当匹配时才把{ bookmarkId, events }投入RuleEngineQueue避免无谓的队列开销apps/workers/workers/ruleEngineWorker.ts 中的RuleEngineWorker以serverConfig.ruleEngine.numWorkers并发度消费队列为书签构建RuleEngine.forBookmark对每个事件调用onEvent求值并执行动作结果会以结构化日志输出含matched_count等指标。事件匹配的判定在doesEventMatchRuleruleEngine.ts对于addedToList/removedFromList采用规则声明列表是否包含该列表的包含式匹配其余事件则做严格深度相等比较。worker 的并发数、轮询间隔1000ms与超时10s均由serverConfig.ruleEngine控制。实战配置示例自动整理收件箱以下三个规则覆盖文档提到的典型场景在 Dashboard 的设置界面创建规则一自动归档新闻通讯事件bookmarkAdded条件urlContains值为substack.com可再加一个or分支mailchi.mp动作archiveBookmarkaddTag标签如newsletter规则二按域名自动打标签事件bookmarkAdded条件urlContains值为youtube.com动作addTagvideoaddToListWatch later列表规则三高价值内容自动收藏并整页归档事件bookmarkAdded条件and→ [titleContains如tutorial,bookmarkTypeIslink]动作favouriteBookmarkdownloadFullPageArchiveAPI与 App 同源的脚本化能力Karakeep 的 API 面与前端 App 使用的是同一套 tRPC 路由因此脚本、cron 任务或其他服务可以用与 App 完全相同的能力读写数据。API 的正式契约以 OpenAPI 规范维护在 packages/open-api/karakeep-openapi-spec.json每个端点均有对应的.api.mdx文档见 docs/docs/api例如 create-bookmark.api.mdx、search-bookmarks.api.mdx。认证方式API 支持两种认证实现见 packages/api/middlewares/apiKeyScopes.ts 与 packages/api/middlewares/auth.tsAPI Key用于脚本与服务集成可附加作用域scope限制避免使用主账号密码用户 Cookie / Session浏览器端 App 的认证方式。API Key 的 scope 由 tRPC 路由的createScopedAuthedProcedure(bookmarks)等调用点声明如rules、webhooks、bookmarks、lists、tags等这意味着你可以按最小权限原则为不同脚本签发不同的 Key。典型用法脚本化导入 / 同步调用书签创建、更新、删除端点实现批量导入或与外部系统双向同步自定义工具用 API 查询书签、标签、列表构建自己的统计看板或检索工具与 cron 搭配编写定时任务定期调用 API 检查、清理或归档书签与 CLI 结合仓库还提供官方 CLIapps/cli适合在终端或脚本中直接操作。搜索端点支持完整的查询语言解析实现见 packages/shared/searchQueryParser.ts可组合标签、列表、收藏状态、类型等过滤条件也支持语义向量搜索。对结果的混合排序逻辑见 packages/trpc/lib/searchRanking.ts 的reciprocalRankFusion。Webhook订阅书签事件并触发你的系统Webhook 允许你订阅书签事件当书签被添加、更新、抓取、AI 打标或被删除时Karakeep 会向你的端点发送 HTTP POST 请求。与 API 配合即可构建端到端自动化——例如把新保存的内容推送进写作队列或团队聊天。可订阅的事件事件类型定义在 packages/shared/types/webhooks.ts 的zWebhookEventSchema事件触发时机created书签被创建edited书签被编辑crawled书签内容被抓取完成ai taggedAI 自动打标完成deleted书签被删除创建 Webhook 的约束由zNewWebhookSchemawebhooks.ts可见url必须是合法 URL长度上限 500 字符events至少订阅一个事件token可选长度上限 100 字符用于鉴权配置后Karakeep 会在请求头携带Authorization: Bearer token你可以据此验证请求确实来自你的 Karakeep 实例。Webhook 的增删改查由 packages/trpc/routers/webhooks.ts 暴露token 不会在响应中回传仅返回hasToken布尔值见toPublicWebhook。投递机制与重试语义Webhook 的投递由 apps/workers/workers/webhookWorker.ts 异步执行事件发生时WebhooksServicepackages/trpc/models/webhooks.service.ts把{ bookmarkId, operation }投入WebhookQueueworker 取出任务后查出该用户的所有 webhook过滤出订阅了该事件的端点对每个匹配端点并发发送POST请求正文为 JSON包含jobId、bookmarkId、userId、url书签链接、type书签类型与operation事件名若配置了 token 则附加 Bearer 头请求使用AbortSignal.timeout设置超时默认serverConfig.webhook.timeoutSec失败会按retryTimes自动重试每次重试间隔由队列控制整体超时预算为timeoutSec × (retryTimes 1) 1秒所有端点投递完成后日志记录matching_count、delivered_count与failed_count指标。一个值得注意的细节deleted事件的书签已被删除worker 允许在书签不存在时仍投递该事件canDeliverWebhookWithoutBookmark因此你可以放心用deleted事件做下游清理。实战示例把新保存推送到团队聊天假设你要在每次新书签保存时通知团队聊天在 Karakeep 设置中创建 webhookurl填聊天机器人的接收端点events勾选created若聊天平台支持配置token服务端校验Authorization: Bearer token在接收端解析 POST 正文中的url与type拼成消息发送。再进一步在接收端把收到的bookmarkId通过 get-bookmark.api.mdx 拉取完整内容标签、摘要、正文写入自己的写作队列——这就是文档所说的用 API 构建端到端自动化的典型形态。把三者组合成完整的自动化管线规则引擎、API 与 Webhook 是互补的三层能力规则引擎负责内部自动化事件发生后在 Karakeep 内部完成打标签、归档、路由、整页归档等动作且无需任何外部系统参与Webhook负责对外广播把创建、编辑、抓取、AI 打标、删除等事件推送给你自己的系统API负责反向操作你的系统收到事件后可以用 API 查询书签详情、批量修改、或把数据同步回 Karakeep形成闭环。例如一个完整的文章收集 → 整理 → 推送管线可以是RSS 订阅的文章保存进 KarakeepbookmarkAdded→ 规则引擎按域名自动打标签、归档并整页归档 → Webhook 把created事件推送到写作队列 → 写作队列用 API 拉取书签详情与正文进入草稿流程。补充说明与运维提示规则引擎与 Webhook 都依赖队列 worker规则由ruleEngineWorker处理webhook 由webhookWorker处理两者在 Docker 部署中均随 worker 容器启动参见 docker-compose.yml 与 charts/README.md相关配置项并发数、超时、重试次数集中在 packages/shared/config.ts 的serverConfig.ruleEngine与serverConfig.webhook中可在部署时通过环境变量调整API 端点的完整请求 / 响应示例请查阅 docs/docs/api 下的各.api.mdx文档OpenAPI 规范见 packages/open-api/karakeep-openapi-spec.json规则引擎与 webhook 路由的单元测试分别在 packages/trpc/routers/rules.test.ts 与 packages/trpc/routers/webhooks.test.ts可作为理解行为边界的参考。以上能力与本文提到的全部源码、配置和 API 文档均位于本仓库内你可以按需深入阅读对应文件把 Karakeep 从收藏箱改造成真正属于你的自动化数据管道。【免费下载链接】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），仅供参考