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 中的列表（Lists）是书签组织的核心层：每条保存的内容都可以同时放在多个列表里，按项目、主题或读者分组而不需要复制书签。列表分两种——手动列表（manual，手动往里加书签）和智能列表（smart，由一条保存的搜索查询驱动、自动更新）。这篇文章的目标是：在你的 Karakeep 实例中创建这两种列表，用查询语言设计一个"动态视图"（比如只显示未归档的 AI 标签书签），并通过 CLI 与 API 验证列表内容是否符合预期。
前提是你已经有一个可访问的 Karakeep 实例。命令行操作部分还需要一个 API key：从 Karakeep 的设置页获取，文档见 Command Line Tool (CLI)。
先弄清两种列表的分工
根据 Lists 文档：
- 手动列表：手工维护的精选集合，适合项目、阅读队列或手挑的合集。可以是private（只有你自己可见）或public（分享一个只读链接），也可以协作——通过邮件邀请别人以 viewer（只浏览）或 editor（可以加入自己的书签）身份参与；即使列表共享，你个人的状态（收藏/归档）仍然属于你自己。
- 智能列表：由一条保存的搜索查询（saved search query）驱动、自动更新的列表，文档给出的例子是
#ai -archived。适合做动态视图，例如 "Youtube links added last week" 或 "All reddit links from r/selfhosted" 这类会随新书签自动变化的集合。
Tags 文档 的建议是：标签（tags）用于宽泛发现，列表用于干净的手挑整理；标签会跟着书签出现在任何地方，而智能列表正好用#<tag>查询把标签筛选固化成一个视图。
用查询语言设计动态视图
智能列表的query使用 Karakeep 的搜索查询语言。基本语法规则：
- 空格分隔多个条件，表示隐式 AND；
- 用
and/or写显式布尔逻辑； - 用
-或!前缀取反，例如-is:archived或!is:archived； - 用括号
()分组条件（注意：分组本身不能被取反）。
与"动态视图"最相关的一组限定符（qualifier）如下（完整表格见上述文档）：
| 限定符 | 含义 | 文档示例 |
|---|---|---|
is:archived | 已归档书签 | -is:archived |
is:inlist/is:tagged | 在一个或多个列表 / 带标签的书签 | is:inlist |
is:link,is:text,is:media | 按书签类型过滤 | is:link |
url:<value> | URL 子串匹配 | url:example.com |
title:<value> | 标题子串匹配 | title:example |
#<tag>/tag:<tag> | 按标签匹配 | #important |
list:<name> | 在指定列表中的书签 | list:reading |
after:<date>/before:<date> | 创建日期在某个日期（YYYY-MM-DD）之后/之前 | after:2023-01-01 |
age:<time-range> | 按创建时间距今多久，单位d/w/m/y，</>表示最大/最小年龄 | age:<1dage:>2w |
feed:<name> | 从某个 RSS feed 导入的书签 | feed:Hackernews |
source:<value> | 按来源过滤（api、web、cli、mobile、extension、singlefile、rss、import） | source:rss |
不属于限定符的文本会被当作全文搜索。文档中给出的示例查询（可直接照抄到智能列表的query里）：
# 2023 年收藏的、带 "important" 标签的书签 is:fav after:2023-01-01 before:2023-12-31 #important # 已归档、且在 "reading" 列表或带 "work" 标签的书签 is:archived and (list:reading or #work) # 没有标签、也没有放进任何列表的书签 -is:tagged or -is:inlist # 未收藏且未归档的书签 -is:fav -is:archived准备条件：安装 CLI 并配置 API key
npm install -g @karakeep/cli也可以不改本机环境，用 Docker 方式体验：
docker run --rm ghcr.io/karakeep-app/karakeep-cli:release --help从 Karakeep 设置页拿到 API key 后，先验证连接是否正常：
karakeep --api-key <key> --server-addr <addr> whoami其中<key>换成你的 API key，<addr>换成你的服务器地址。文档示例（仅为格式参考，不是你的实际输出）：
{ id: 'j29gnbzxxd01q74j2lu88tnb', name: 'Test User', email: 'test@gmail.com' }不想每次传--api-key/--server-addr的话，把配置存到$XDG_CONFIG_HOME/karakeep/config.json（未设置XDG_CONFIG_HOME时为~/.config/karakeep/config.json）：
{ "serverAddr": "https://try.karakeep.app", "apiKey": "mysupersecretkey" }优先级规则是：命令行选项 > 环境变量（KARAKEEP_API_KEY、KARAKEEP_SERVER_ADDR）> 配置文件。不提供服务器地址时，CLI 默认连接https://cloud.karakeep.app。也可以用karakeep auth init交互式创建或更新这个文件。
创建一个智能列表
lists create子命令定义在 CLI 源码 apps/cli/src/commands/lists.ts 中（官方 CLI 文档的命令帮助里只列出了list/delete/add-bookmark/remove-bookmark，如果你的版本帮助里看不到create，先跑karakeep lists --help确认）。参数说明：
--name <name>：列表名，必填；--icon <icon>：列表图标，必填，取一个 emoji；--type <type>：manual或smart，默认manual；--query <query>：智能列表的搜索查询，smart 列表必填；--description <description>：描述；--parent-id <id>：父列表 id，用于把列表组织成树。
按上一步设计的查询创建一个智能列表：
karakeep lists create --name "AI Inbox" --icon "🤖" --type smart --query "#ai -archived"创建成功时 CLI 会打印新列表的对象；失败时打印Failed to create list。同一入口也可以建手动列表——--type省略即为manual，且此时不能带--query。
如果你走 API 而不是 CLI，对应的是POST /lists（文档：Create a new list）。请求体要求name和icon，type取manual或smart，smart 列表必须带query、manual 列表不能带query——违反这一点会返回 400（文档原文给出的 400 情形就是 "smart list missing query, or manual list with a query"）。成功返回 201 和列表对象，其中包含id、type、query等字段；401 表示 Bearer token 缺失、无效或过期。
把书签加入或移出手动列表
手动列表靠显式增删维护。CLI 对应子命令：
# 把指定书签加入列表 karakeep lists add-bookmark --list <listId> --bookmark <bookmarkId> # 从列表移除书签 karakeep lists remove-bookmark --list <listId> --bookmark <bookmarkId><listId>和<bookmarkId>分别替换为你列表和书签的 id。成功时打印Successfully added bookmark ... to list with id ...之类的确认信息，失败时打印对应错误。智能列表不需要（也不靠）手动增删——它的内容由查询实时算出。
验证列表与动态视图
验证分三层：
- 列表清单与计数：
karakeep lists list不带--json时，CLI 以树形表格列出所有列表，列为Id、Name、Description、Bookmarks（书签数），并顺带打印各列表的书签统计；加--json则输出原始 JSON。新建的智能列表应出现在表中，且Bookmarks数量就是当前匹配查询的书签数。
- 列表详情：
karakeep lists get <id>输出包含Type、Query（智能列表的查询）、Parent、Public、Role等字段，用它确认列表类型和查询内容与你的设计一致。
- 列表内书签（智能列表的核心验证点）：调用
GET /lists/{listId}/bookmarks（文档：Get bookmarks in a list）。该接口文档明确说明："For smart lists, bookmarks are computed from the list's query."返回 200，含bookmarks数组和nextCursor（无更多结果时为 null，可用作翻页游标）。可选查询参数：sortOrder（按创建时间asc/desc，默认desc）、limit（每页条数）、cursor（上一页返回的游标）、includeContent（设为 true 时返回完整正文内容，false 时响应更轻）。返回 401 是认证问题，404 表示列表不存在。
动态视图的验证方式：新保存的书签如果满足列表查询，会出现在该智能列表中；不符合的不会。这正是 smart 列表相对手动列表的差异——视图随书签库自动演化，而不是靠手工维护。
限制与边界
- 查询里括号分组可以嵌套，但分组不能被取反（查询语言文档明确说明 groups can't be negated）。
name上限 100 字符，description上限 500 字符（POST /lists的请求 schema）。- public 只读分享与 email 协作（viewer/editor）是文档在手动列表条目下描述的属性；智能列表条目没有说明这两点，不要假设它们同样可用。
- CLI 认证三件套（API key、服务器地址、配置文件的 JSON 格式）必须与 Command Line Tool (CLI) 一致，
whoami是判断配置是否正确的第一道检查。
想进一步自动化（例如新书签满足条件时自动归档或进列表），文档给出的下一步是规则引擎与 API/Webhooks：用 if-this-then-that 风格规则基于元数据或内容自动打标、收藏或把书签路由进列表。
【免费下载链接】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），仅供参考
