# 知识库按需读取

以下接口用于茄总的 Web 与原生宿主，不是沙箱应用的 `platform.*` API。用户应用不能直接请求这些接口；知识库暂未作为应用 Bridge 能力开放。

## 目录与正文分离

宿主使用 `GET /api/knowledge/v2/children` 读取直接子项。省略 `folder_id` 表示知识库根目录；根目录同时包含未分类笔记、直接属于系统根目录的笔记，以及历史上归属知识库子树之外的笔记。

参数：

- `folder_id`：可选，当前用户的知识库文件夹 ID。
- `kind`：`all`（默认）、`note` 或 `source`。仅过滤笔记，不隐藏可浏览的子文件夹。
- `sort`：`updated`（默认）、`created` 或 `name`。文件夹优先，组内按更新时间倒序、创建时间倒序或名称升序，排序值相同使用 ID 升序。
- `limit`：默认 50，范围 1–100。
- `cursor`：使用上一页 `next_cursor` 原样传递；账号、文件夹、类型、排序、页尺寸变化后必须重新请求第一页。

返回 `{ root, items, next_cursor }`。`next_cursor: null` 表示没有下一页。

笔记项包含 `item_type: "note"`、`id`、`title`、`kind`、`folder_id`、`created_at`、`updated_at`。文件夹项包含 `item_type: "folder"`、`id`、`name`、`parent_id`、`system_key`、时间字段、`has_children` 和 `note_count`（直接归属的全部笔记数量，不受 kind 筛选影响）。

目录不会返回正文、来源说明、来源文件名或正文摘要，也不会读取 R2 正文。只有展开文件夹或主动继续翻页时才读取更多子项。

点击笔记使用 `GET /api/knowledge/v2/notes/:id`，返回 `note`（完整笔记）、`links`、`backlinks`、`links_next_cursor`、`backlinks_next_cursor`。每个关联集合首批最多 50 项。继续读取使用 `GET /api/knowledge/v2/notes/:id/links?direction=in&cursor=...`，其中 `in` 表示反向链接，`out` 表示正向链接；返回 `{ items, next_cursor }`，支持相同的 `limit` 限制。

## 搜索与引用

`GET /api/knowledge/v2/search?query=关键词` 在服务端搜索标题与正文，不要求相关目录已经展开。支持 `kind`、`sort`、`limit`、`cursor` 和 `folder_id`；指定文件夹时仅搜索直接归属，根目录归属规则与 children 一致，不隐式递归后代。

结果为 `{ items, next_cursor }`，每项包含笔记元数据、`folder_name`、`folder_path` 与最多 240 字符的 `snippet`。空 query 返回空结果。query 最长 200 字符；至少 3 字符使用现有 FTS，多词为 OR，短词使用子串匹配。路径查询最多追溯 64 层，异常或超深路径明确标记上级未显示。

`GET /api/knowledge/v2/titles?query=标题` 提供 `[[` 输入建议，每次默认 10 项、最多 20 项。`exact=true` 表示精确解析标题，按更新时间倒序、ID 升序选择。可以传递 `from_note_id`，优先保留该笔记已经记录的链接目标，避免重名笔记改变旧引用身份。精确解析只用于选择引用，不提供翻页。

标题建议包含所属路径；用户无需先下载全量标题。显式笔记 ID 链接仍然保留原目标 ID，所有读取均按登录用户权限执行。

## 状态、缓存与兼容

目录、搜索、正文独立显示等待与失败状态。刷新已经展示的目录时保留原内容，后台结果不得覆盖未保存正文；退出或切换账号清空状态。折叠目录的缓存最多保留 20 页，当前主动浏览的数据不受此缓存淘汰影响；不会自动下载尚未查看的分页。

旧 `/api/knowledge/notes` 与 `/api/knowledge/folders` 保留原有字段，供旧版 iOS 与既有 Agent 调用。新端目录不使用旧全量接口，也不在新接口失败时静默回退到下载全库正文。

发布顺序必须是兼容服务端、Web、iOS。新版 iOS 分发后，服务端回滚也必须保留 v2 读取契约；不能通过删除新接口恢复旧版服务。