getnote-search

# 得到大脑搜索 通过官方 `getnote` CLI 搜索真实笔记。不要自己拼 OpenAPI 请求、笔记 ID 或访问链接。机器调用使用 `-o json`；只有退出码为 0 且 JSON 的 `success=true` 才是业务成功。 ## 何时使用 - “关于某主题、模糊记忆”：使用 `getnote search`；明确书籍/来源或要全量时按下方路径选择。 - “最近有哪些笔记、按保存时间列出来”：交给笔记 Skill 的 `getnote notes`，不要把列表误当语义搜索。 - 用户选中某一条后，再交给笔记 Skill 用 `getnote note <note_id>` 读取详情；搜索阶段不自动修改、移动、分享或创建笔记。 ## 先选查找路径 - 明确书籍（书名或书籍作者），尤其要“全部划线”：先读知识库参考。书名用 `kbs --scope BOOKSPACE --query`；只有作者名时用 `kbs --scope BOOKSPACE --author` 并省略 `--query`，不能把作者塞进只匹配名称的 query。书名和作者都已知时才同时传，两者为 AND 条件。必要时用真实 `--book-id` 消歧，再按用户要“全部笔记”还是“划线”选择是否加 `--note-type ref`，需要全文时按 ID 调用 `note`。 - 明确文章/课程（包括“某老师的课”）：按下方“课程、文稿与评论定位”执行。已有真实来源 ID/文章链接时直接精确筛选；没有候选也能按来源列定位信息。`topics=[]` 不阻断这条路线。 - 只有主题或模糊记忆：语义搜索 → 按字符串笔记 ID 去重 → 对选中候选读详情/原文。Top-K（最大 10）不是完整清单；零命中也不能证明全库没有相关笔记。 ## 容易混淆的组合问法 | 用户说法 | 路径与不能丢失的条件 | |---|---| | “找博尔赫斯的书籍笔记” / “找提到博尔赫斯的笔记” | 前者按书籍 author 定位；后者是内容主题搜索，不把所有提到一个人的笔记都限制为其著作。 | | “某课程共读《某本书》那篇文稿” | 明确课程/文稿时优先课程引用路径，书名在这里是文稿线索，不跳去 BOOKSPACE。 | | “课程笔记” | 先区分得到课程引用与自己录制的课堂笔记；只有用户明确来源时才设 dedao/course_article，不能把课堂录音排除掉。 | | “某库/某书里关于某主题” | 先定位真实 topic_id，再 search --kb；未命中按知识库参考在该库列表补查，不把空搜索当作库内没有，不得遗漏库范围。 | | “上周保存/昨天修改的某课程笔记” | 列表用对应时间筛选；search 没有时间/来源筛选参数，语义候选需核对 timestamps/reference。不能把时间词拼进 query 就宣称完成了时间筛选。 | | “某课程链接下的笔记” / “这篇文稿链接的划线” | 课程主页 URL 匹配 reference.url 后取该课程各篇；文稿 URL 才传 --article-url。URL 中的编码 ID 不是 --reference-id，不自行转换。 | | “全部笔记” / “全部划线” | 前者不默认加 note-type ref；书籍库可能有心得等非引用笔记。得到课程引用路径只能证明该来源下的划线集合，不能涵盖用户另写的课程心得或录音。 | 多条件查询要保留用户全部约束；从候选转入精确文稿列表时也保留已指定的 topic/time/source。条件冲突或作者、版本不符时说明实际候选，不静默删除条件。有正文主题限制时，来源匹配只证明“来自这里”，还需核对正文；截断 preview 未出现某词不能当作全文不包含。多个库/多本书合并结果时按字符串 note_id 去重，不能合并不同 ID 的不同划线。 增强结果的 `resource_type` 使用小写 note/file 等资源类型，旧顶层 `note_type` 保留大写 NOTE/FILE 兼容值；真正笔记类型在 `note.note_type`。用 `note.display_title` 展示，用 `snippet`（旧接口为 `content`）解释命中，不拿详情 preview 替换搜索片段。`snippet_source=unknown` 如实保留；`score=null` 是未知，不是 0；`returned_count` 是片段数，`distinct_note_count` 是去重笔记数。FILE 等非笔记结果没有笔记 ID 时只呈现真实资源信息，不能拼笔记链接。 ## 课程、文稿与评论定位 `search` 是 Top-K 语义召回，来源元数据出现在返回值中不保证它参与了召回。不要因为搜到了别的笔记就把指定课程的任务判为成功。 1. **提取约束**：区分课程名、文稿名、授课人、内容主题、评论和用户给定时间。例如“帮我找林老师《科学课》里讲概率那篇划线”应保留课程/授课人约束，不把整句话只搜一次便结束。已提供精确文章 URL 时直接读笔记参考的来源筛选。 2. **发现候选**：可先用课程/文稿关键词 `getnote search '<课程名或文稿标题关键词>' --limit 10 -o json`。核对结果的 `note.reference`；旧结果没有它时对相关候选读 `note`。无来源匹配、只有无关结果，或用户要“整门课程的全部笔记”时，进入下面的来源列表，不反复换整句搜索。 3. **来源列表补查**：用户明确说得到课程时执行以下命令；同一对话可复用已经读取的页，但用户说新增了笔记时必须重新读取。 ```bash getnote notes --source dedao --note-type ref --reference-type course_article --page-size 20 -o json # 有下一页时，保持筛选和 page-size，用真实返回的 pagination.next_cursor 继续 getnote notes --source dedao --note-type ref --reference-type course_article --page-size 20 --cursor '<pagination.next_cursor>' -o json ``` 用户给定时间/知识库时同时保留对应筛选，不擅自增加“最近一个月”等限制；来源未明确时先依据候选核实，不把所有课程都当作得到来源。只读取定位信息，不先下载全库正文。此命令没有课程名查询参数，名称由 Agent 在返回的元数据中匹配，不能说成服务端按课程名直接筛选。 | 用户线索 | 核对字段与边界 | |---|---| | 课程名称、简称 | `reference.title`；允许忽略外围书名号、空格、全半角差异来找候选，保留季数/版本，不把“日课6”当成其它季。 | | 文稿标题 | `reference.article.title`；片段可用于候选匹配，详情核验后再认定。 | | 老师/作者 | 优先 `reference.author`；缺失时，名称出现在课程标题中可作为候选线索，但不能虚构 author 字段或断言身份。 | | 同课程、多篇文稿 | 用真实 `reference.url` 区分课程，缺失或同名冲突时列候选；每篇文稿的 resource_id 不能代替课程 ID。 | | 个人评论 | 读取候选详情的 `content`，不在 `preview` 或 `ref_content` 中猜评论。 | 4. **控制遍历与消歧**：按返回 `pagination.has_more/next_cursor` 翻页，按字符串 note_id 去重，并核对 capabilities/applied_filters；遇到游标循环、重复无进展或中途失败就说明未完成。一次来源候选发现先读最多 5 页（每页 20 条）；超过时保留已找到候选与进度，说明仍未查完，结合用户线索缩小范围或询问是否继续。不得把这个执行预算当作“全库没有”。用户明确要求全部时按知识库参考的完整分页规则继续；只有确实遍历完成才能给全量结论。同名课程/同名文稿无法区分时列候选让用户选择。相关 `metadata_state.reference` 为 partial/unavailable 或所需字段缺失时，保留为待核验候选，必要时读详情；不能仅靠字段缺失断言不属于目标来源。 5. **完成用户的目标**：找一条时读取匹配候选详情；找同篇全部划线时，用笔记参考的 `--reference-id` 或 `--article-url` 精确取全；找整门课全部时需完成课程引用范围遍历，按课程来源分组，再逐条按需读详情。保留原文、个人评论、来源的区别；不按文稿 ID 把多条划线合并成一条。 只记得个人评论时：先用评论的实质文本做语义搜索并读详情核对。若用户已限定得到课程但搜索无匹配，可按上述来源列表缩小候选；评论在列表被省略，不能据此排除候选。小候选集（不超过 20 条）可按需逐条读取详情匹配，多于 20 条时先用已给的课程/文稿/时间进一步缩小，仍不足再向用户询问线索，不能批量下载整个账号全文。“有启发”等泛化评论可能对应多条，返回全部已核实候选而非随意选第一条。用户没有限定来源时，不自行只查课程后声称查完所有评论。 ## 语义搜索执行步骤 仅当上面的路径选择需要语义搜索时执行；没有指定知识库不等于必须先语义搜索。 1. 用户没有指定知识库时，执行 `getnote search <query> --limit <1-10> -o json`。默认上限是 10，不能自行放大。 2. 用户指定知识库名称时，先按其类型执行 `getnote kbs --scope <scope> -o json`；默认查 `DEFAULT`，书籍、客户档案和团队知识库分别使用 `BOOKSPACE`、`CUSTOMER`、`TEAMSPACE`。用返回的真实 `topic_id` 和 `scope` 匹配；同名或意图不明确时必须让用户选择。 3. 已确认知识库后执行 `getnote search <query> --kb <topic_id> --limit <1-10> -o json`。 4. 只从返回值读取标题、摘要、字符串 `note_id` 和真实 `note_url`。没有 `note_id/note_url` 的非笔记结果可以展示内容，但不能伪造“打开笔记”链接。 5. 同一篇笔记可能因命中多个片段出现多次。面向用户列“几篇笔记”时必须按字符串 `note_id` 去重；若去重后不足用户要求的数量，可在上限 10 内增大 `--limit` 重搜，仍不足时如实返回实际数量。 ## 命令结果与用户呈现 ### 搜索 ```bash getnote search "支付流程" --limit 10 -o json getnote search "客户反馈" --kb <topic_id> --limit 5 -o json ``` 成功 JSON 的稳定字段： | 字段 | 含义 | Agent 如何使用 | |---|---|---| | `success` | 业务是否成功 | 只有 `true` 才继续呈现结果。 | | `data.results[]` | 搜索结果 | 空数组是一次成功的“未找到”，不是失败。 | | `data.results[].title` | 笔记标题 | 优先用 note.display_title；旧响应再用 title，均缺失才显示未命名。 | | `data.results[].note_id` | 笔记雪花 ID | 始终作为字符串原样传入后续 `note` 命令。 | | `data.results[].note_url` | 真实笔记链接 | 只有非空时才给用户“打开笔记”。 | | `data.results[].content` | 命中摘要或正文片段 | 只摘取与问题相关的短片段，不能冒充全文。 | | `data.results[].score` | 相关性分数，可为 null | null 表示未知；仅用于内部排序，不向用户虚构“准确率”。 | 成功时按相关性给出编号列表，例如： ```text 这次搜索找到 3 条不同的相关笔记： 1. 《支付流程优化想法》——“用户等待时增加进度提示…” 打开：<真实 note_url> 2. 《客户支付反馈》——“…” 打开：<真实 note_url> 你想看哪一条的详情或原文？ ``` 若 `data.partial=true` 或存在 `data.warnings`，先说明检索有部分结果未能完成权限验证或读取，并按 warnings 解释原因；空结果也不能表述为完整检索后无命中。若 `data.results=[]` 或结果均不符合用户指定来源，先按已选路径完成同一请求范围内的来源补查；补查不是跨知识库或跨账号扩大范围。只有主题搜索且无可用来源线索时，说明“这次语义搜索未找到”，不要说接口失败或全库没有；不创建笔记、不编造结果。 ## 失败、隐私与后续动作 - `success=false` 或退出码非 0：回复失败步骤、`error.message` / `error.reason`、是否 `retryable` 和可选 `request_id`；不要将 HTTP 成功或空输出说成搜索成功。 - 若 CLI 提示“搜索服务响应超时”，这是检索未完成，不是“没有结果”。建议稍后重试，或缩小关键词、指定知识库后再试；不要伪造空列表。 - 检索结果可能包含私密正文。群聊或共享会话默认只展示标题、必要摘要和真实链接；用户明确要求后再展开全文。 - 用户选中结果后，复用返回的字符串 `note_id`，再读取 `getnote note <note_id> -o json`；不要从 URL 截取或转换为数字。