@getnote/cli 1.7.0 → 1.7.1

package/README.md

@@ -1,5 +1,9 @@
 # 得到大脑（Get笔记） CLI
 
+## 1.7.1 查找修复
+
+修复订阅书库查询因布尔筛选字段而解析失败的问题，保留作者、书名和分页校验。随包 Skill 明确作者与书名的不同查法，补充课程、文稿、评论的来源补查，并区分全部笔记与划线。
+
 ## 1.7.0 查找与引用
 
 支持书库身份与书名查找、引用来源筛选及完整分页。列表用于定位，完整内容由 `getnote note <id>` 读取；引用原文与个人评论分别返回。搜索保留部分结果与资源身份，Top-K 不代表全量。随包五个领域 Skill 已同步这些调用规则。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getnote/cli",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "CLI tool for 得到大脑（Get笔记） — manage notes and knowledge bases from the terminal",
   "keywords": [
     "getnote",

package/skills/getnote-kb/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: getnote-kb
-description: 查看和管理得到大脑的知识库、文件夹、书籍、客户档案、团队知识库、抖音博主订阅与直播，归档笔记，以及查询文件格式限制、直传文件到 OSS 并提交知识库入库。用户要上传文档或文件时也使用。
+description: 按书名或作者查找书籍笔记，查看和管理得到大脑知识库、文件夹、客户档案、团队知识库、博主订阅与直播，归档笔记，以及查询文件限制、上传文件入库。
 ---
 
 # 得到大脑知识库
@@ -45,26 +45,40 @@ description: 查看和管理得到大脑的知识库、文件夹、书籍、客
 4. 订阅知识库通常只读。若列表结果明确返回角色或可写标记，按真实字段判断；当前 CLI 契约未保证权限字段时，不得声称已经预检为 owner/admin，可在用户明确授权后尝试写入，并忠实处理权限失败。
 5. 普通成员写入失败时明确说明权限不足，不尝试绕过。当前不代替用户新建团队知识库。
 
-## 按书名找全部划线
+## 按书名、作者定位，再选择内容范围
 
-用户要某本书的划线或“全部笔记”时，先定位书籍知识库，不把语义搜索的 Top-K 当全量。
+用户要某本书或某位作者的划线时，先定位书籍知识库，不把语义搜索的 Top-K 当全量。`--query` 只匹配知识库名或书名，`--author` 匹配书籍作者；两个参数同时传时是 AND，不是任选其一。
+
+- “找《某本书》的笔记”：传 `--query`，查询词只放书名，不把“我的笔记”“全部划线”或作者名拼进去。
+- “找某位作者的书籍笔记”：只传 `--author`，省略 `--query`，再按返回书籍库读取。用户要该作者全部书籍时逐库遍历；仅要其中一本但候选不唯一时再消歧。
+- “找某位作者写的《某本书》”：同时传书名 `--query` 和作者 `--author`。作者关键词误传 query 得到空列表不能解释为用户没有该作者的笔记。
 
 ```bash
+# 只有作者线索，无需先猜书名
+getnote kbs --scope BOOKSPACE --author '用户提供的作者' --all -o json
+# 同时知道书名与作者
 getnote kbs --scope BOOKSPACE --query '书名' --author '用户提供的作者' --all -o json
-# 用户明确查订阅库，或自有库无匹配时，再查询真实订阅的书籍库
-getnote kbs-sub --scope BOOKSPACE --query '书名' --all -o json
+# 用户明确查订阅库时保持原有条件；只知作者仍只传 author
+getnote kbs-sub --scope BOOKSPACE --author '用户提供的作者' --all -o json
+# 只要划线 / 摘录
 getnote kb '<返回的 topic_id>' --note-type ref --page-size 20 --all -o json
+# 要这本书里的全部笔记：不加 note-type，避免漏掉读书心得等其它类型
+getnote kb '<返回的 topic_id>' --page-size 20 --all -o json
 getnote note original '<返回的 note_id>' -o json
 ```
 
+- “全部笔记”和“全部划线”不是同一范围：只在用户明确要划线/摘录时加 `--note-type ref`。用户要某章划线时，在候选 `reference.location.chapter_name/chapter_id` 核对，不把章节名当书名；字段缺失不能证明该章没有笔记。
+- “书里关于某主题的内容”：定位书库后用 `getnote search '主题' --kb '<topic_id>' --limit 10 -o json`，不退回全局搜索再把别处内容归到这本书。搜索为空或结果不符合主题时，用 `getnote kb '<topic_id>' --page-size 20 -o json` 在同一库内补查；沿真实 pagination 翻页，先匹配定位信息，截断或不足时按需读候选详情的真实正文/原文。发现与深读预算沿用搜索参考，超出预算说明范围未查完而非判定没有。用户要求全部时按完整分页逐项核验，Top-K 不能给全量承诺。
+- 自有书库无匹配且用户未限定“只查我的”时，可以查询真实订阅书库，保留原有 scope/query/author/book-id；用户明确只查订阅库则直接用 kbs-sub。命令报错、权限不足或解析失败不能当空库，不能去掉条件后称筛选成功。
 - 作者未知时省略 `--author`。先用 `name`、`scope=BOOKSPACE`、`book_info.title/author/book_id` 核对候选；同名多作者、多版本仍不唯一时请用户选择，不能用第一项代替。已有真实书 ID 可加 `--book-id`，它不是知识库 ID。
-- query/author 会做 NFKC、外围书名号/引号和大小写归一化；这只是候选定位，不证明同名书是同一本。
+- query/author 会做 NFKC、外围书名号/引号和大小写归一化，但不是自动分词或模糊纠错。全名未匹配时可用用户原话中的稳定片段找候选（如作者姓氏、连续书名片段），再核对完整书名/作者；不擅自更换作者、季数或版本，不无提示忽略冲突条件。
+- `BOOKSPACE` 表示书籍库，不等于全部来自得到。用户明确“得到电子书”时核对 `book_info.source` 与引用的 `reference.source`；不要把豆瓣等其它来源的同名书当作得到来源。只说某本书时不擅自加平台限制。
 - 普通知识库在笔记的 `topics[]` 中仍只有 `id/name`；书籍关联才附带 `scope/book_info`。标签、知识库名称都不能代替 `reference` 来源证据。
 - 新查询核对 `meta.capabilities`（`knowledge.lookup.v1`、`pagination.v1`；笔记筛选还需 `note.filters.v1`，引用筛选还需 `note.reference.v1`）和 `applied_filters`。CLI 会拒绝不支持或未应用的条件；不得去掉条件后把未筛选结果交差。列表只返回定位信息，需要完整内容时按 `note_id` 调用 `getnote note`。
 - 候选知识库的 `stats.note_count` 可能滞后，也不代表筛选后的划线数；回答以本次验证过的分页结果和去重 ID 为准。
 - `--all` 只有退出码为 0、`success=true`、`data.traversal.completed=true` 且 `pagination_verified=true` 才能确认完成了当前授权范围的遍历。按字符串笔记 ID 去重；`traversal.returned_count` 是本次实际取回数，`traversal.total_count=null` 仍表示服务端精确总数未知。旧 `total` 保留兼容语义，不能当新的筛选总数。
 - 手动翻页或 MCP：保持 scope、全部筛选和 page_size 不变；按 `pagination.next_page` / `next_cursor` 原样继续，直到 `has_more=false`。记录已经访问的页码/游标和笔记 ID；循环、空页仍声称有下一页、重复结果无进展或中途失败都不能声称“全部找到”。
-- `topics=[]` 不能证明没有来源或没有划线；知识库为空时先核对原文访问权限、筛选和 `metadata_state`，再按笔记/搜索参考的引用来源路线查找，不自动建库或修改归属。
+- 书库不存在、无匹配、或库内无划线，不等于账号没有该书来源的引用。用户已明确得到电子书时，可用 `getnote notes --source dedao --note-type ref --reference-type ebook --page-size 20 -o json` 按来源补查，在 `reference.title/author/book_id` 匹配；按搜索参考的预算和分页规则继续，必要时用真实 `reference.resource_id` 精确筛选。只对当前授权范围下结论，不新建库、不修改归属。
 
 ## 文件夹和归档流程
 
@@ -115,9 +129,9 @@ getnote note original '<返回的 note_id>' -o json
 
 ## 完成、处理中与失败后的动作
 
-- `kbs`、`kbs-sub`、`kb`、`dir`、博主和直播的空列表都是成功结果：如实说“目前没有”，不要自动创建知识库、目录或订阅。
+- `kbs`、`kbs-sub`、`kb`、`dir`、博主和直播的空列表是本次查询无结果；按用户目标核对筛选、分页与已说明的补查路径，再说明“在本次范围内未找到”，不直接说账号没有，不自动创建知识库、目录或订阅。
 - `kb create`、`kb add`、`mkdir`、`mvdir` 等写操作的 `data` 可能因服务版本不同而不提供完整对象。只在 `success=true` 时确认动作已提交；若要向用户返回新目录 ID、最终层级或笔记归属，必须紧接着重新读取 `gnote kb dir` 或 `getnote kb <topic_id>`，不能猜字段。
 - `kb add` 即使请求成功，也不能把“已发起加入”说成“已进入某个目录”；只有重新读取后在 `resources[]` 的同一项出现对应字符串 `note_id` 和 `directory_id`，才能展示最终归属。
 - `kb remove`、`rmdir` 前必须有用户明确确认并带 `--yes`；若 `reason=knowledge_directory_not_empty`，明确提示“目录非空，请先移出内容或删除子目录”，不要原请求重试。其它失败也应说明真实原因和下一步，绝不宣称已删除。
-- 用户给的团队知识库不在 `getnote kbs` 返回中时，先说明当前账号没有访问权限；不能把个人知识库同名项替代成团队知识库。
+- 知识库未出现在某一页或某种 scope 的列表中不能直接推断权限不足；先核对 scope、完整分页以及自有/订阅范围。实际返回权限错误才说明无权访问；不把个人知识库同名项替代团队知识库。
 - “这条笔记”只能复用当前会话中已经由 CLI 返回并验证过的字符串 `note_id`。没有可靠上下文时先请用户提供笔记 ID；不能从不受支持的私有链接、标题或雪花 ID 数值转换中猜测。

package/skills/getnote-note/SKILL.md

@@ -64,7 +64,7 @@ getnote note original '<note_id>' -o json
 
 `original` 只按真实类型读取上述字段，并返回 `original_source`；原文缺失或类型不支持会报错，不能把评论或定位片段补成原文。列表中的 `content_state` 会标明正文被省略；详情接口返回完整正文和元数据。用 `metadata_state.reference/topics` 区分完整、部分、不可用的元数据；缺失的作者、书 ID、来源 URL 不猜测补写。
 
-文章或课程没有知识库时，先从已有详情或语义搜索候选读取真实 `reference`，再精确查找：
+文章或课程没有知识库时，已有候选可从详情或搜索结果读取真实 `reference` 后精确查找。只有课程名/文稿名或评论、尚无候选时，先执行搜索 Skill 的“课程、文稿与评论定位”：语义搜索无来源匹配后，按来源分页列定位信息再匹配元数据；不要要求用户提供内部 ID，也不要因 `topics=[]` 放弃。拿到候选后精确查找：
 
 ```bash
 getnote notes --source dedao --note-type ref --reference-type course_article --reference-id '<reference.resource_id>' --all -o json
@@ -72,9 +72,9 @@ getnote notes --source dedao --note-type ref --reference-type course_article --r
 getnote notes --source dedao --note-type ref --article-url '<reference.article.url>' --all -o json
 ```
 
-平台值取 `reference.source`；资源类型取 `reference.resource_type`，不要用标签或内部 ptype 猜枚举。`--reference-id` 必须同时传 `--source` 和 `--reference-type`。引用的 `resource_id`、`original_note_id`、书 ID 与笔记 ID 都是不同身份；始终按返回的字符串使用。URL 保留 query/fragment，不自行去参。同一文章可以有多个不同的 `original_note_id`，不可按文章 ID 合并成一条划线。
+平台值取 `reference.source`；资源类型取 `reference.resource_type`，不要用标签或内部 ptype 猜枚举。`--reference-id` 必须同时传 `--source` 和 `--reference-type`。课程文稿的 `resource_id` 指向单篇文稿，不能据此取全整门课程；整门课程需按搜索参考的课程来源匹配遍历。引用的 `resource_id`、`original_note_id`、书 ID 与笔记 ID 都是不同身份；始终按返回的字符串使用。课程主页与文稿 URL 不通用；用户给的是课程主页时按搜索参考匹配 `reference.url`，不能传到 `--article-url`。URL 保留 query/fragment，不自行去参。同一文章可以有多个不同的 `original_note_id`，不可按文章 ID 合并成一条划线。
 
-创建、正文编辑、记录更新是三个独立时间轴。按需使用 `--created-from/to`、`--edited-from/to`、`--record-updated-from/to`，值必须为带时区 RFC3339；区间 from 包含、to 不包含。不得把 `updated_at` 当正文编辑时间。
+创建、正文编辑、记录更新是三个独立时间轴。按需使用 `--created-from/to`、`--edited-from/to`、`--record-updated-from/to`，值必须为带时区 RFC3339；区间 from 包含、to 不包含。不得把 `updated_at` 当正文编辑时间。“今天/上周”按用户当前日期和时区换算边界；保存时间不是文章发布日期，不把“最近”擅自解释成固定一个月。用户同时限定课程/知识库时保留这些条件。
 
 新参数需要服务端对应 `meta.capabilities` 且 `applied_filters` 与请求一致；不支持时停止该查询并说明升级服务/客户端的需要，不自动移除筛选。全量按知识库参考中的分页规则验收；只拿一页或一次语义搜索，不能说“全部找到”。
 
@@ -109,7 +109,7 @@ getnote notes --source dedao --note-type ref --article-url '<reference.article.u
 
 1. “最近、列表、有哪些”使用 `getnote notes`；有明确书名或引用来源时按上面的来源/知识库路线查找，模糊主题才交给搜索 Skill。
 2. 用户给出 ID 时直接读取详情；雪花 ID 全程按字符串原样传递。“这条笔记”只复用当前会话中已经由 CLI 返回并验证过的字符串 ID。当前 CLI 若不能直接接收某种私有链接，就先请用户提供 ID，不能自行截取、猜测或转成数字。
-3. 列表先展示标题、字符串 ID 和真实 `note_url`，用户选择后再读取全文。
+3. 用户只要列表时展示标题、字符串 ID 和真实 `note_url`。用户明确要某条或某来源的划线、原文、评论时，定位匹配候选后直接读详情完成请求，不额外等待用户选择；仅在候选仍有歧义、无法确认目标时请用户选择。
 4. 不确定笔记类型时先读 `getnote note <id> -o json`：
    - 引用/链接/文字原文：`original`；
    - 录音、会议、课堂逐字稿：`transcript`；
@@ -134,7 +134,7 @@ getnote notes --source dedao --note-type ref --article-url '<reference.article.u
 |---|---|---|
 | `getnote save … -o json` | `success=true`、`data.note.note_id/title/note_url` | 回复“已保存《标题》”和真实链接。链接/图片先只得到 `task_id` 时还未成功，继续查任务。 |
 | `getnote task <task_id> -o json` | `data.task_id/status/note_id?/msg?/error_msg?` | 仅 `done`/`success` 且有 `note_id` 为完成；`pending`/`processing` 是处理中；`failed` 说明真实原因。 |
-| `getnote notes -o json` | `data.notes[].note_id/title/note_url`、`has_more/cursor/total` | 返回标题、字符串 ID 和真实链接；下一页只用返回的 `cursor`。 |
+| `getnote notes -o json` | `data.notes[].note_id/title/note_url`；新筛选响应另有 `pagination` | 返回标题、字符串 ID 和真实链接。新筛选按 `pagination.has_more/next_cursor` 翻页；仅无 `pagination` 的旧响应按 `has_more/cursor`。旧 `total` 不能当作筛选后数量。 |
 | `getnote note <id> -o json` | `data.note.note_id/title/note_url/note_type`，按需读 `content` | 先给摘要和链接；私密全文只在用户明确要求时展开。 |
 | `getnote note original <id> -o json` | `data.note_id/title/original/original_source` | 只把 `original` 当原文；原文不可用会失败，不能拿评论或摘要补全。 |
 | `getnote note transcript <id> -o json` | `data.note_id/title/transcript` | 仅录音类笔记可用；不可用时如实说明。 |

package/skills/getnote-search/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: getnote-search
-description: 在得到大脑的全部笔记或指定知识库中按自然语言进行语义搜索，返回真实标题、摘要、字符串 ID 和可打开的笔记链接。
+description: 在得到大脑查找笔记：按书名、课程名、文稿标题、作者、评论或模糊记忆选择来源定位与语义搜索，返回真实笔记和链接。
 ---
 
 # 得到大脑搜索
@@ -15,15 +15,60 @@ description: 在得到大脑的全部笔记或指定知识库中按自然语言
 
 ## 先选查找路径
 
-- 明确书名、作者，尤其要“全部划线”：先读知识库参考，用 `kbs --scope BOOKSPACE --query` 定位，必要时 `--author/--book-id` 消歧，再 `kb <topic_id> --note-type ref --all` 定位笔记，需要全文时按 ID 调用 `note`。
-- 明确文章/课程：已有候选时从 `reference.source/resource_type/resource_id` 或 `reference.article.url` 进入笔记参考的精确来源筛选；`topics=[]` 不阻断这条路线。没有候选时，语义搜索只用于发现来源候选，核对引用后再查全部。
+- 明确书籍（书名或书籍作者），尤其要“全部划线”：先读知识库参考。书名用 `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，不能自行放大。
+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` 的非笔记结果可以展示内容，但不能伪造“打开笔记”链接。
@@ -61,7 +106,7 @@ getnote search "客户反馈" --kb <topic_id> --limit 5 -o json
 你想看哪一条的详情或原文？
 ```
 
-若 `data.partial=true` 或存在 `data.warnings`，先说明检索有部分结果未能完成权限验证或读取，并按 warnings 解释原因；空结果也不能表述为完整检索后无命中。仅当没有部分失败时，若 `data.results=[]`，回复“没有找到相关笔记；可以换关键词、时间范围或指定知识库再试”，不要说“接口失败”，也不要自动扩大检索范围、创建笔记或调用模型编造结果。
+若 `data.partial=true` 或存在 `data.warnings`，先说明检索有部分结果未能完成权限验证或读取，并按 warnings 解释原因；空结果也不能表述为完整检索后无命中。若 `data.results=[]` 或结果均不符合用户指定来源，先按已选路径完成同一请求范围内的来源补查；补查不是跨知识库或跨账号扩大范围。只有主题搜索且无可用来源线索时，说明“这次语义搜索未找到”，不要说接口失败或全库没有；不创建笔记、不编造结果。
 
 ## 失败、隐私与后续动作