知识库按需读取

以下接口用于茄总的 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 读取契约；不能通过删除新接口恢复旧版服务。