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本指南以 Karakeep原 Hoarder官方文档 bookmarking.md 为骨架结合仓库源码深入讲解书签的核心数据模型与日常管理方式。你将掌握链接 / 文本 / 媒体三类书签的差异与存储结构、收藏Favourites与归档Archiving的底层实现、以及笔记、高亮、附件如何与书签协同工作并学会用搜索查询语言把这些能力串起来实现首页的收件箱归零inbox-zero式整洁管理。Karakeep 是一款可自托管的收藏一切应用链接、笔记、图片而一切内容都从一条书签bookmark开始。无论你是通过浏览器扩展、Web 界面、移动端、CLI 还是 REST API 保存内容最终都会落成一条统一结构的书签记录。理解书签的数据模型与管理机制是高效使用 Karakeep 的前提。一、书签的底层数据模型一切皆书签在深入具体功能之前先看 Karakeep 在数据层如何定义一条书签。核心定义位于 packages/shared/types/bookmarks.tsexport const enum BookmarkTypes { LINK link, TEXT text, ASSET asset, UNKNOWN unknown, }每条书签由两部分组成公共字段与类型化内容content。公共字段定义在zBareBookmarkSchemabookmarks.ts包括archived: boolean是否已归档favourited: boolean是否已收藏加星note: string | null附带的个人笔记summary: string | nullAI 生成的摘要taggingStatus / summarizationStatus / embeddingStatus分别表示 AI 自动打标签、摘要、向量化嵌入的处理状态success / failure / pendingsource书签来源取值包括api、web、cli、mobile、extension、singlefile、rss、import见 bookmarks.ts可用于区分用户主动保存与批量导入/订阅抓取title、createdAt、modifiedAt、userId等基础字段。值得注意的是Karakeep 通过 Zod 对 URL 做了严格校验bookmarks.ts只允许http和https协议以规避javascript:、data:等危险 scheme 被反射进导出文件或 RSS 订阅的安全风险。同时标题长度上限为 1000 字符MAX_BOOKMARK_TITLE_LENGTH。二、三类书签链接、文本与媒体Karakeep 使用z.discriminatedUnion(type, ...)bookmarks.ts将书签内容严格区分为三种类型每种类型有独立的存储结构与处理流程。Links链接书签从网页或浏览器扩展保存的 URL。其结构定义在zBookmarkedLinkSchemabookmarks.ts包含大量与抓取相关的字段url、title、description、imageUrl、favicon元数据与预览信息screenshotAssetId、pdfAssetId、fullPageArchiveAssetId、precrawledArchiveAssetId、videoAssetId、contentAssetId各类派生资产截图、PDF、整页归档、视频、可读内容的关联 IDreaderViewStatus阅读器视图状态取值为readable / not_readable / uncertain / unavailable见 bookmarks.tsreaderViewScore可读性评分0–100 整数preferredPreview首选预览方式reader_view / screenshot / overviewcrawledAt与crawlStatus抓取时间与状态success / failure / pendingauthor、publisher、datePublished、dateModified文章类元数据。保存链接后Karakeep 会抓取元数据、预览图与截图在配置了单文件归档SingleFile的情况下还会保存完整页面归档作为原页面变更或消失时的回退方案详见 SingleFile 集成文档。Text文本书签快速记录的想法、引文或片段。结构极简bookmarks.tsexport const zBookmarkedTextSchema z.object({ type: z.literal(BookmarkTypes.TEXT), text: z.string(), sourceUrl: z.string().nullish(), });text是正文内容sourceUrl是可选的来源链接——这让你可以在链接旁附带上下文说明形成链接 注释的组合。Media媒体书签想留存的图片或 PDF。结构定义在zBookmarkedAssetSchemabookmarks.tsexport const zBookmarkedAssetSchema z.object({ type: z.literal(BookmarkTypes.ASSET), assetType: z.enum([image, pdf]), assetId: z.string(), fileName: z.string().nullish(), sourceUrl: z.string().nullish(), size: z.number().nullish(), content: z.string().nullish(), });媒体书签的关键特性是Karakeep 会自动从图片/PDF 中提取内容如图片 OCR、PDF 文本抽取使其进入全文搜索索引因此保存的图片和 PDF 也能被检索到。此外UNKNOWN类型用于向后兼容无法识别的历史数据。三、收藏Favourites给书签加星收藏是最轻量的管理手段给喜欢的书签加星它会出现在专属的收藏视图中便于快速回访——适合经常重读的文章、反复查阅的参考资料、以及值得分享的内容。从源码看favourited只是书签公共字段中的一个布尔值bookmarks.ts但围绕它有完整的查询链路列表接口GET /v1/bookmarks支持favourited过滤参数bookmarks.ts搜索匹配器zFavouritedMatchersearch.ts支持按收藏状态过滤搜索语法中对应is:fav见 searchQueryParser.tstRPC 的updateBookmark路由会写入favourited字段并在变更时触发对应事件与向量索引更新bookmarks.ts。四、归档Archiving实现首页收件箱归零归档是 Karakeep 管理首页整洁度的核心机制归档 从首页隐藏而非删除归档后的书签不会出现在主页但数据完整保留归档内容依然可搜索且保留全部标签tags、高亮highlights和附件attachments适合追求收件箱归零inbox-zero工作流的用户先快速保存一切再通过归档把已处理/暂时不需要看到的内容移出首页。源码层面的对应关系归档状态由archived: z.boolean()字段承载bookmarks.ts新建书签时即可指定zNewBookmarkRequestSchema中的archived可选字段bookmarks.ts列表接口支持archived过滤bookmarks.ts搜索匹配器zArchivedMatchersearch.ts与搜索语法is:archivedsearchQueryParser.ts可随时调出归档内容更新路由在archived变化时会记录bookmark.archive事件并触发重新索引bookmarks.ts。由于归档书签保留一切你可以放心地随手保存、随手归档需要时再通过搜索找回——这正是 inbox-zero 工作流在 Karakeep 中的落地方式。五、笔记Notes为书签附加上下文任何书签都可以附加个人笔记用来记录上下文、提醒事项或下一步行动。要点笔记与书签同存同生命周期不会随页面变化而丢失笔记可被搜索因此当时为什么收藏它也能被检索回来。源码层面note字段同时出现在公共字段bookmarks.ts、新建请求bookmarks.ts与更新请求bookmarks.ts中updateBookmark路由会将其随其他字段一并写入并触发索引更新bookmarks.ts。六、高亮Highlights阅读时标记金句在阅读器/书签详情视图中你可以保存引文、摘要或 TODO这些标记即高亮高亮显示在书签详情视图/阅读器中并参与搜索让你能直接跳转到关键想法每个高亮包含color颜色默认黄色、text高亮文本和note可选备注定义见 packages/shared/types/highlights.ts。后端通过highlightsAppRouter提供完整的 CRUD 与检索能力highlights.tscreate在指定书签下创建高亮会先校验书签归属ensureBookmarkOwnershipgetForBookmark取某书签的全部高亮getAll分页遍历全部高亮默认每页条数见DEFAULT_NUM_HIGHLIGHTS_PER_PAGEsearch按文本搜索高亮update/delete修改或删除高亮。所有操作都经过ensureHighlightOwnership中间件校验归属权确保只能操作自己的高亮。七、附件Attachments为书签补充一切上下文附件是与书签绑定的额外素材截图、页面归档、视频以及你上传的文件。Karakeep 通过统一的资产Asset模型管理它们类型枚举定义在 bookmarks.tsexport const zAssetTypesSchema z.enum([ linkHtmlContent, // 链接的 HTML 内容 screenshot, // 页面截图 pdf, // 渲染出的 PDF assetScreenshot, // 媒体资产的截图 bannerImage, // 横幅图 fullPageArchive, // 整页归档SingleFile video, // 视频 bookmarkAsset, // 书签级资产 precrawledArchive, // 预抓取归档 userUploaded, // 用户上传 avatar, // 头像 unknown, ]);这些类型回答了附件从哪来截图与归档Screenshots archives抓取流程自动生成screenshot、fullPageArchive、pdf等作为原页面变更或消失时的回退快照上传文件Uploaded filesuserUploaded类型让你把 PDF、笔记或其他支持材料直接放在链接旁。附件可以在书签详情视图中管理上传、下载或分离detach均可。对应的 API 有 upload-asset.api.mdx、attach-asset-to-bookmark.api.mdx 与 detach-asset-from-bookmark.api.mdx。八、用搜索查询语言串起整套书签能力收藏、归档、类型、笔记与高亮之所以能高效协同离不开 Karakeep 的搜索查询语言。解析器实现位于 packages/shared/searchQueryParser.ts它基于typescript-parsec将查询字符串解析为结构化的匹配器matcher树search.ts。与本文主题直接相关的查询语法包括查询含义解析依据is:link/is:text/is:media按书签类型过滤链接/文本/媒体searchQueryParser.tsis:fav只看收藏的书签searchQueryParser.tsis:archived只看已归档的书签searchQueryParser.tsis:tagged/is:inlist是否有标签 / 是否在列表中searchQueryParser.tsis:broken已损坏无法抓取的链接searchQueryParser.tsurl:/title:按 URL 或标题过滤searchQueryParser.ts#标签/tag:/list:/feed:按标签、列表、RSS 源过滤searchQueryParser.tssource:按来源过滤api/extension/cli/import 等searchQueryParser.tsafter:/before:/age:按时间范围过滤searchQueryParser.ts-/!前缀、and/or、括号、引号字符串否定、逻辑组合与精确匹配searchQueryParser.ts例如想找回收藏过但还没归档的 PDF 资产可以搜索is:media is:fav !is:archived。完整的查询语言说明见 search-query-language.md。配合 标签 与 列表 使用可以搭建完整的个人知识管理流。九、多端创建与管理书签Karakeep 的所有客户端最终都走同一套数据模型。新建书签的请求结构zNewBookmarkRequestSchemabookmarks.ts明确支持链接type: linkurl可选precrawledArchiveId文本type: texttext可选sourceUrl媒体type: assetassetType: image | pdfassetId通用可选字段title、archived、favourited、note、summary、createdAt、source、crawlPrioritylow/normal用于区分用户手动保存与批量导入的抓取优先级。更新请求zUpdateBookmarksRequestSchemabookmarks.ts则覆盖archived、favourited、note、title、summary以及链接类专属字段url、description、author、publisher、datePublished、dateModified等。因此无论你在哪一端操作浏览器扩展右键或点击扩展图标保存当前页面为链接书签Web / 移动端手动粘贴 URL、输入文本、上传图片/PDFCLI通过命令行快速保存见 command-line 文档REST API / SDK调用 create-bookmark.api.mdx 与 update-bookmark.api.mdx 等接口实现程序化收藏。十、总结从一条书签开始的组织方法论Karakeep 的设计哲学可以概括为保存一切 → 用收藏标记重要 → 用归档保持首页整洁 → 用搜索随时找回。保存链接、文本、媒体三类书签覆盖绝大多数收藏场景媒体文件还能自动抽取内容进入全文索引收藏一键加星收藏视图直达常回访内容归档隐藏但不删除所有标签、高亮、附件、笔记完整保留配合is:archived随时可查深化笔记记录为什么重要高亮标记关键在哪附件保存完整快照检索全文搜索加上is:/url:/tag:/after:等查询符让归档内容与高亮笔记都能被精确定位。本文涉及的核心源码与文档均可在仓库中继续深入书签类型定义、搜索匹配器、搜索查询解析器、高亮路由、官方书签文档 与 搜索查询语言文档。【免费下载链接】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），仅供参考
Karakeep 书签体系完全指南：类型、收藏、归档、笔记、高亮与附件机制深度解析
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本指南以 Karakeep原 Hoarder官方文档 bookmarking.md 为骨架结合仓库源码深入讲解书签的核心数据模型与日常管理方式。你将掌握链接 / 文本 / 媒体三类书签的差异与存储结构、收藏Favourites与归档Archiving的底层实现、以及笔记、高亮、附件如何与书签协同工作并学会用搜索查询语言把这些能力串起来实现首页的收件箱归零inbox-zero式整洁管理。Karakeep 是一款可自托管的收藏一切应用链接、笔记、图片而一切内容都从一条书签bookmark开始。无论你是通过浏览器扩展、Web 界面、移动端、CLI 还是 REST API 保存内容最终都会落成一条统一结构的书签记录。理解书签的数据模型与管理机制是高效使用 Karakeep 的前提。一、书签的底层数据模型一切皆书签在深入具体功能之前先看 Karakeep 在数据层如何定义一条书签。核心定义位于 packages/shared/types/bookmarks.tsexport const enum BookmarkTypes { LINK link, TEXT text, ASSET asset, UNKNOWN unknown, }每条书签由两部分组成公共字段与类型化内容content。公共字段定义在zBareBookmarkSchemabookmarks.ts包括archived: boolean是否已归档favourited: boolean是否已收藏加星note: string | null附带的个人笔记summary: string | nullAI 生成的摘要taggingStatus / summarizationStatus / embeddingStatus分别表示 AI 自动打标签、摘要、向量化嵌入的处理状态success / failure / pendingsource书签来源取值包括api、web、cli、mobile、extension、singlefile、rss、import见 bookmarks.ts可用于区分用户主动保存与批量导入/订阅抓取title、createdAt、modifiedAt、userId等基础字段。值得注意的是Karakeep 通过 Zod 对 URL 做了严格校验bookmarks.ts只允许http和https协议以规避javascript:、data:等危险 scheme 被反射进导出文件或 RSS 订阅的安全风险。同时标题长度上限为 1000 字符MAX_BOOKMARK_TITLE_LENGTH。二、三类书签链接、文本与媒体Karakeep 使用z.discriminatedUnion(type, ...)bookmarks.ts将书签内容严格区分为三种类型每种类型有独立的存储结构与处理流程。Links链接书签从网页或浏览器扩展保存的 URL。其结构定义在zBookmarkedLinkSchemabookmarks.ts包含大量与抓取相关的字段url、title、description、imageUrl、favicon元数据与预览信息screenshotAssetId、pdfAssetId、fullPageArchiveAssetId、precrawledArchiveAssetId、videoAssetId、contentAssetId各类派生资产截图、PDF、整页归档、视频、可读内容的关联 IDreaderViewStatus阅读器视图状态取值为readable / not_readable / uncertain / unavailable见 bookmarks.tsreaderViewScore可读性评分0–100 整数preferredPreview首选预览方式reader_view / screenshot / overviewcrawledAt与crawlStatus抓取时间与状态success / failure / pendingauthor、publisher、datePublished、dateModified文章类元数据。保存链接后Karakeep 会抓取元数据、预览图与截图在配置了单文件归档SingleFile的情况下还会保存完整页面归档作为原页面变更或消失时的回退方案详见 SingleFile 集成文档。Text文本书签快速记录的想法、引文或片段。结构极简bookmarks.tsexport const zBookmarkedTextSchema z.object({ type: z.literal(BookmarkTypes.TEXT), text: z.string(), sourceUrl: z.string().nullish(), });text是正文内容sourceUrl是可选的来源链接——这让你可以在链接旁附带上下文说明形成链接 注释的组合。Media媒体书签想留存的图片或 PDF。结构定义在zBookmarkedAssetSchemabookmarks.tsexport const zBookmarkedAssetSchema z.object({ type: z.literal(BookmarkTypes.ASSET), assetType: z.enum([image, pdf]), assetId: z.string(), fileName: z.string().nullish(), sourceUrl: z.string().nullish(), size: z.number().nullish(), content: z.string().nullish(), });媒体书签的关键特性是Karakeep 会自动从图片/PDF 中提取内容如图片 OCR、PDF 文本抽取使其进入全文搜索索引因此保存的图片和 PDF 也能被检索到。此外UNKNOWN类型用于向后兼容无法识别的历史数据。三、收藏Favourites给书签加星收藏是最轻量的管理手段给喜欢的书签加星它会出现在专属的收藏视图中便于快速回访——适合经常重读的文章、反复查阅的参考资料、以及值得分享的内容。从源码看favourited只是书签公共字段中的一个布尔值bookmarks.ts但围绕它有完整的查询链路列表接口GET /v1/bookmarks支持favourited过滤参数bookmarks.ts搜索匹配器zFavouritedMatchersearch.ts支持按收藏状态过滤搜索语法中对应is:fav见 searchQueryParser.tstRPC 的updateBookmark路由会写入favourited字段并在变更时触发对应事件与向量索引更新bookmarks.ts。四、归档Archiving实现首页收件箱归零归档是 Karakeep 管理首页整洁度的核心机制归档 从首页隐藏而非删除归档后的书签不会出现在主页但数据完整保留归档内容依然可搜索且保留全部标签tags、高亮highlights和附件attachments适合追求收件箱归零inbox-zero工作流的用户先快速保存一切再通过归档把已处理/暂时不需要看到的内容移出首页。源码层面的对应关系归档状态由archived: z.boolean()字段承载bookmarks.ts新建书签时即可指定zNewBookmarkRequestSchema中的archived可选字段bookmarks.ts列表接口支持archived过滤bookmarks.ts搜索匹配器zArchivedMatchersearch.ts与搜索语法is:archivedsearchQueryParser.ts可随时调出归档内容更新路由在archived变化时会记录bookmark.archive事件并触发重新索引bookmarks.ts。由于归档书签保留一切你可以放心地随手保存、随手归档需要时再通过搜索找回——这正是 inbox-zero 工作流在 Karakeep 中的落地方式。五、笔记Notes为书签附加上下文任何书签都可以附加个人笔记用来记录上下文、提醒事项或下一步行动。要点笔记与书签同存同生命周期不会随页面变化而丢失笔记可被搜索因此当时为什么收藏它也能被检索回来。源码层面note字段同时出现在公共字段bookmarks.ts、新建请求bookmarks.ts与更新请求bookmarks.ts中updateBookmark路由会将其随其他字段一并写入并触发索引更新bookmarks.ts。六、高亮Highlights阅读时标记金句在阅读器/书签详情视图中你可以保存引文、摘要或 TODO这些标记即高亮高亮显示在书签详情视图/阅读器中并参与搜索让你能直接跳转到关键想法每个高亮包含color颜色默认黄色、text高亮文本和note可选备注定义见 packages/shared/types/highlights.ts。后端通过highlightsAppRouter提供完整的 CRUD 与检索能力highlights.tscreate在指定书签下创建高亮会先校验书签归属ensureBookmarkOwnershipgetForBookmark取某书签的全部高亮getAll分页遍历全部高亮默认每页条数见DEFAULT_NUM_HIGHLIGHTS_PER_PAGEsearch按文本搜索高亮update/delete修改或删除高亮。所有操作都经过ensureHighlightOwnership中间件校验归属权确保只能操作自己的高亮。七、附件Attachments为书签补充一切上下文附件是与书签绑定的额外素材截图、页面归档、视频以及你上传的文件。Karakeep 通过统一的资产Asset模型管理它们类型枚举定义在 bookmarks.tsexport const zAssetTypesSchema z.enum([ linkHtmlContent, // 链接的 HTML 内容 screenshot, // 页面截图 pdf, // 渲染出的 PDF assetScreenshot, // 媒体资产的截图 bannerImage, // 横幅图 fullPageArchive, // 整页归档SingleFile video, // 视频 bookmarkAsset, // 书签级资产 precrawledArchive, // 预抓取归档 userUploaded, // 用户上传 avatar, // 头像 unknown, ]);这些类型回答了附件从哪来截图与归档Screenshots archives抓取流程自动生成screenshot、fullPageArchive、pdf等作为原页面变更或消失时的回退快照上传文件Uploaded filesuserUploaded类型让你把 PDF、笔记或其他支持材料直接放在链接旁。附件可以在书签详情视图中管理上传、下载或分离detach均可。对应的 API 有 upload-asset.api.mdx、attach-asset-to-bookmark.api.mdx 与 detach-asset-from-bookmark.api.mdx。八、用搜索查询语言串起整套书签能力收藏、归档、类型、笔记与高亮之所以能高效协同离不开 Karakeep 的搜索查询语言。解析器实现位于 packages/shared/searchQueryParser.ts它基于typescript-parsec将查询字符串解析为结构化的匹配器matcher树search.ts。与本文主题直接相关的查询语法包括查询含义解析依据is:link/is:text/is:media按书签类型过滤链接/文本/媒体searchQueryParser.tsis:fav只看收藏的书签searchQueryParser.tsis:archived只看已归档的书签searchQueryParser.tsis:tagged/is:inlist是否有标签 / 是否在列表中searchQueryParser.tsis:broken已损坏无法抓取的链接searchQueryParser.tsurl:/title:按 URL 或标题过滤searchQueryParser.ts#标签/tag:/list:/feed:按标签、列表、RSS 源过滤searchQueryParser.tssource:按来源过滤api/extension/cli/import 等searchQueryParser.tsafter:/before:/age:按时间范围过滤searchQueryParser.ts-/!前缀、and/or、括号、引号字符串否定、逻辑组合与精确匹配searchQueryParser.ts例如想找回收藏过但还没归档的 PDF 资产可以搜索is:media is:fav !is:archived。完整的查询语言说明见 search-query-language.md。配合 标签 与 列表 使用可以搭建完整的个人知识管理流。九、多端创建与管理书签Karakeep 的所有客户端最终都走同一套数据模型。新建书签的请求结构zNewBookmarkRequestSchemabookmarks.ts明确支持链接type: linkurl可选precrawledArchiveId文本type: texttext可选sourceUrl媒体type: assetassetType: image | pdfassetId通用可选字段title、archived、favourited、note、summary、createdAt、source、crawlPrioritylow/normal用于区分用户手动保存与批量导入的抓取优先级。更新请求zUpdateBookmarksRequestSchemabookmarks.ts则覆盖archived、favourited、note、title、summary以及链接类专属字段url、description、author、publisher、datePublished、dateModified等。因此无论你在哪一端操作浏览器扩展右键或点击扩展图标保存当前页面为链接书签Web / 移动端手动粘贴 URL、输入文本、上传图片/PDFCLI通过命令行快速保存见 command-line 文档REST API / SDK调用 create-bookmark.api.mdx 与 update-bookmark.api.mdx 等接口实现程序化收藏。十、总结从一条书签开始的组织方法论Karakeep 的设计哲学可以概括为保存一切 → 用收藏标记重要 → 用归档保持首页整洁 → 用搜索随时找回。保存链接、文本、媒体三类书签覆盖绝大多数收藏场景媒体文件还能自动抽取内容进入全文索引收藏一键加星收藏视图直达常回访内容归档隐藏但不删除所有标签、高亮、附件、笔记完整保留配合is:archived随时可查深化笔记记录为什么重要高亮标记关键在哪附件保存完整快照检索全文搜索加上is:/url:/tag:/after:等查询符让归档内容与高亮笔记都能被精确定位。本文涉及的核心源码与文档均可在仓库中继续深入书签类型定义、搜索匹配器、搜索查询解析器、高亮路由、官方书签文档 与 搜索查询语言文档。【免费下载链接】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），仅供参考
