KarakeepHoarder列表Lists完全指南手动列表、智能列表与协作分享【免费下载链接】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/hoarderLists列表是 Karakeep 的核心组织层每一条收藏书签、笔记或图片可以同时归属于多个列表从而在不复制数据的前提下按项目、主题或受众对内容进行灵活分组。本文基于 lists.md 展开并结合仓库中的数据表定义、tRPC 路由与模型实现系统讲解手动列表、智能列表、公开分享与协作邀请的完整用法帮助你掌握 Karakeep 中最重要的一套信息组织能力。列表在 Karakeep 中的定位在 Karakeep 中任何保存的条目链接、笔记、图片都可以被加入多个列表形成多对多关系——同一个书签既可以在AI 学习资料里也可以在本月精读里无需重复保存也不会产生数据冗余。列表因此成为与标签tags互补的组织维度标签强调扁平化的属性标注而列表强调可管理、可分享、可自动更新的内容集合。从数据库层面看这种多对多关系由bookmarksInLists关联表承载packages/db/schema.ts它记录了bookmarkId、listId与加入时间addedAt并建立了按列表优先查询的复合索引支撑查看某列表下所有书签这类高频操作。手动列表Manual lists手动列表是手工精选的内容集合适合项目归档、阅读队列、手工挑选的收藏夹等场景。由你手动把书签加入或移出列表可以设为私有仅自己可见或公开通过只读链接分享给任何人支持协作通过邮箱邀请他人加入被邀请者可担任查看者viewer或编辑者editor编辑者可以向列表添加自己的书签查看者只能浏览即使在共享列表中你的个人状态如收藏 favourite / 归档 archive始终只属于你自己不会被共享列表的其他人覆盖。手动列表的创建在校验层有明确约束列表名不能为空、最长 100 字符描述最长 500 字符packages/shared/types/lists.ts。同时手动列表不允许携带查询query字段——校验规则Manual lists cannot have a query会在创建时直接拦截packages/shared/types/lists.ts因为由查询自动填充是智能列表专属的能力。智能列表Smart lists智能列表是由保存的搜索查询驱动的自动更新列表例如查询#ai -archived。只要书签满足查询条件就会自动出现在列表中无需任何手动维护。典型应用场景Youtube links added last week上周新增的 YouTube 链接All reddit links from r/selfhosted来自 r/selfhosted 的所有 Reddit 链接其他一切适合用 搜索查询语言 表达的动态视图智能列表的查询在创建与编辑时都会经过严格校验packages/shared/types/lists.ts智能列表必须携带 querySmart lists must have a query否则创建失败查询必须能被完整解析通过parseSearchQuery解析后结果必须是full查询中不允许出现无限定词的全文检索词智能列表只能由结构化条件标签、域名、时间范围、其他列表等构成不能包含自由文本搜索词以保证列表结果是确定、可复现的。智能列表的嵌套与循环保护智能列表可以引用其他列表包括手动列表和另一个智能列表从而构建层级化的动态视图。从源码结构看SmartList在求值时会递归解析查询匹配器packages/trpc/models/lists.ts并引入一系列防环机制设定MAX_VISITED_LISTS 30的最大访问深度超过后直接返回空结果避免无限递归拖垮查询通过已访问列表集合检测自引用与循环引用A→B→A遇到环即返回空引用不存在的列表同样安全地返回空结果。这些边界行为在 packages/trpc/routers/lists.test.ts 中有完整覆盖嵌套智能列表、多层嵌套3 层深、反向引用、循环引用、自引用、超过最大访问深度、引用不存在列表等场景均有测试用例验证。列表的底层数据模型所有列表无论手动还是智能都存储在bookmarkLists表中packages/db/schema.ts关键字段如下字段类型说明idtext (PK)列表 ID自动生成nametext列表名称非空≤100 字符descriptiontext列表描述≤500 字符icontext列表图标userIdtext (FK)列表创建者级联删除typeenummanual或smartquerytext仅智能列表使用保存的搜索查询parentIdtext (FK)父列表 ID支持列表嵌套删除时置空rssTokentext列表 RSS 订阅令牌持有者可读取列表内容publicboolean是否公开默认false围绕列表还有三张关联表bookmarksInLists书签与列表的多对多关联记录加入时间listCollaborators已接受的协作者含roleviewer/editor、addedBy等listInvitations待处理邀请含role、statuspending/declined、invitedEmail、invitedBy等packages/db/schema.ts。列表的权限模型从 packages/trpc/models/lists.ts 的实现可以看出列表权限被抽象为四种角色并对应三层操作能力角色查看view编辑增删书签管理改元数据/删列表/管协作者owner所有者✅✅✅editor编辑者✅✅❌viewer查看者✅❌❌public公开访问者✅❌❌ensureCanView()确认可查看列表及其书签ensureCanEdit()确认可向列表添加/移除书签仅 owner 与 editorensureCanManage()确认可编辑列表元数据、删除列表、管理协作者仅 owner。这三个中间件被串联在 tRPC 路由上packages/trpc/routers/lists.ts例如addToList同时要求ensureListAtLeastViewer与ensureListAtLeastEditor确保只有具备编辑权的人才能操作而edit、delete、merge、协作管理等端点则进一步要求ensureListAtLeastOwner。隐私与信息遮蔽值得注意的一个细节当非所有者查看列表时asZBookmarkList()会刻意隐藏parentId与public字段packages/trpc/models/lists.ts注释中明确说明这是出于隐私考量。协作者界面中非所有者也只能看到协作者的姓名与头像邮箱仅对所有者可见packages/trpc/models/lists.ts。公开列表与 RSS 订阅手动列表可以设置为公开public: true分享一个只读链接即可让任何人浏览。公开列表的内容读取通过getPublicList实现只要列表的public为真或请求携带了有效的rssToken即可访问packages/trpc/models/lists.ts。与公开分享相关的还有RSS 订阅能力详见 quick-sharing.md每个列表都可以生成独立的rssToken32 字节随机十六进制串packages/trpc/models/lists.ts持有该令牌的人可以订阅列表的 RSS 流可以通过 tRPC 端点regenRssToken重新生成令牌旧令牌立即失效或clearRssToken彻底撤销订阅能力packages/trpc/routers/lists.ts。公开列表不暴露协作者信息hasCollaborators强制为false并且只返回经过asPublicBookmark()处理的书签数据避免泄露个人状态。协作邀请、接受与退出手动列表的协作以邮箱邀请为入口所有者调用addCollaborator携带邮箱与viewer/editor角色系统创建一条pending状态的邀请并返回invitationId被邀请用户通过acceptInvitation接受或declineInvitation拒绝所有者也可revokeInvitation撤销接受后生成listCollaborators记录该列表出现在协作者的与我共享列表中packages/trpc/models/lists.ts。邀请端点带有速率限制每 15 分钟最多 20 次调用packages/trpc/routers/lists.ts防止被滥用。所有者可以随时调整角色updateCollaboratorRole或移除协作者removeCollaborator协作者也可以主动退出列表leaveList仅 owner 不能退出自己的列表。从源码注释看移除协作者或退出列表时该协作者曾添加到列表的书签也会一并移除packages/trpc/models/lists.ts。需要注意智能列表不支持协作者相关行为在 sharedLists.test.ts 中有测试验证同时智能列表也无法手动添加书签addBookmark会直接抛出BAD_REQUESTpackages/trpc/models/lists.ts。列表的进阶管理操作除了基础的增删改查tRPC 路由还提供了若干管理能力packages/trpc/routers/lists.ts合并列表merge将源列表的书签合并进目标列表并可选择合并后删除源列表deleteSourceAfterMerge校验层禁止把列表合并进自身级联删除deleteChildren删除列表时可选择是否同时删除其所有子列表父子关系通过parentId维护packages/trpc/models/lists.ts 中通过邻接表 BFS 收集全部后代列表统计stats批量获取每个列表的书签数量手动列表走 SQLcount聚合智能列表逐条求值见 packages/trpc/models/lists.ts删除列表时还会自动清理引用该列表的规则引擎规则addedToList/removedFromList事件避免留下悬挂引用packages/trpc/models/lists.ts。实战建议手动列表用于策展智能列表用于视图需要精挑细选的场景如周报、对外分享集用手动列表需要永远保持最新的动态视图如未归档的 #ai 书签最近一周的 YouTube 链接用智能列表二者可以组合使用——智能列表甚至可以引用手动列表。善用搜索查询语言智能列表的价值完全取决于查询质量建议先熟悉 search-query-language.md 中的标签、域名、时间与排除语法再落地为列表。协作列表注意书签归属编辑者添加的书签在退出/被移除时会随之删除规划多人协作时需留意这一行为。公开分享注意隐私公开列表与 RSS 令牌都能被任何人访问分享前确认列表内容不含隐私信息如需撤销重新生成rssToken即可让旧链接失效。通过手动列表与智能列表的组合、公开只读链接与邮箱协作机制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），仅供参考