@getnote/cli 1.7.1 → 1.8.1

package/README.md

@@ -1,23 +1,5 @@
 # 得到大脑（Get笔记） CLI
 
-## 1.7.1 查找修复
-
-修复订阅书库查询因布尔筛选字段而解析失败的问题，保留作者、书名和分页校验。随包 Skill 明确作者与书名的不同查法，补充课程、文稿、评论的来源补查，并区分全部笔记与划线。
-
-## 1.7.0 查找与引用
-
-支持书库身份与书名查找、引用来源筛选及完整分页。列表用于定位，完整内容由 `getnote note <id>` 读取；引用原文与个人评论分别返回。搜索保留部分结果与资源身份，Top-K 不代表全量。随包五个领域 Skill 已同步这些调用规则。
-
-## v1.6：文件上传与独立报告
-
-- `getnote note chapters <id> -o json` 读取章节；`note timeline` 保留录音 moments，`marks <note_id>` 独立读取标记。
-- `sprouts <YYYY-MM>` 列表从 `data.tasks[].sprouts[]` 取真实报告 id，再运行 `sprout <id>`；不要将 task_id 当报告 id。
-- `file-capabilities` 查询当前格式、大小及页数限制，不在 Agent 中写死限制。
-
-云 MCP 已授权时，无需再登录 CLI：MCP 获取临时上传 token，将 JSON 经受控文件或 stdin 交给 `getnote upload <file> --max-size-bytes <能力接口上限>`。此命令不读取 CLI 身份凭证，只向 OSS 上传，返回 `stage=oss_uploaded` 和文件元数据。随后由同一个已授权 MCP 提交知识库入库并查询最终 `SUCCESS`；上传成功不等于入库完成。不要将 token 放入命令参数、聊天或日志。
-
-CLI 已登录时也可使用 `file-token <extension>` 获取 token、`upload` 直传，再用 `file-add <topic_id> <directory_id> --metadata-file <上传结果文件>` 提交。临时 token 不提供通用 OpenAPI 权限。
-
 得到大脑（Get笔记）的命令行工具，让你在终端和 AI Agent 里直接管理笔记和知识库。
 
 存链接、记文字、搜笔记、管知识库——一条命令搞定，支持脚本和 AI Agent 调用。
@@ -164,6 +146,27 @@ getnote search "LLM 推荐阅读"
 getnote search "产品设计" --kb vnrOAaGY
 ```
 
+**按书名、作者或课程查找**
+
+```bash
+# 按书名查书库；query 不匹配作者
+getnote kbs --scope BOOKSPACE --query '沙之书' --all -o json
+
+# 只有作者线索时用 author
+getnote kbs --scope BOOKSPACE --author '博尔赫斯' --all -o json
+
+# 使用返回的 topic_id 读取全部笔记；只要划线时再加 --note-type ref
+getnote kb '<topic_id>' --page-size 20 --all -o json
+
+# 得到课程文稿：先列出引用定位信息，再核对课程名和文稿标题
+getnote notes --source dedao --note-type ref --reference-type course_article --page-size 20 -o json
+
+# 定位后读取完整内容
+getnote note '<note_id>' -o json
+```
+
+书名和作者同时传入时须同时匹配。课程列表没有课程名筛选参数，AI 根据返回的来源元数据匹配，并按 `pagination.next_cursor` 继续查询。语义搜索 Top-K 不是全部笔记；搜索为空也不能证明没有相关内容。
+
 **场景 3：管理知识库**
 ```bash
 # 列出默认知识库；特殊类型使用 --scope
@@ -215,6 +218,23 @@ npx skills add iswalle/getnote-cli -y -g
 
 ## 完整命令参考
 
+### 课程定位与按需正文
+
+以下为本分支的增量能力，需当前服务端声明对应 capability；安装 CLI 不代表服务已发布。旧命令与默认正文行为保留。
+
+```bash
+getnote references list --source dedao --resource-type course --query '课程名' --author '准确老师姓名' --all -o json
+getnote notes --source dedao --course-type '66' --course-id '<返回的course_id>' --note-type ref --all -o json
+getnote notes batch '<note_id_1>' '<note_id_2>' --fields original --max-total-chars 32000 -o json
+getnote search '主题' --response-mode snippet --max-snippet-chars 400 -o json
+```
+
+课程名可 exact/prefix，老师精确匹配；query/author 至少一个。ID 全程用字符串，课程 ID 与课节 ID 不互换。查课程需沿空页的有效游标继续；课程与知识库交集、课程内语义搜索尚未开放。批量只读个人笔记，最多20个去重ID、默认32000/上限64000个Unicode码点及1MiB；保留 status/pending_ids，整条超预算可改用旧单条详情读取。snippet full 表示完整命中片段，不能冒充全文。新选项要求当前接口 capability 与筛选回显，不接受旧服务忽略筛选的成功结果。
+
+课程响应的 `coverage` 说明实际覆盖范围，省略类型也不表示包含未关联课程身份的心得或录音。JSON 输出及 `--all` 保留该对象中的未知类型和新增字段；任一页的 `partial` 或警告都会保留，存在未解决问题时 `traversal.completed=false`，不能因分页结束便声称结果完整。
+
+错误保留合法值和等待建议；已知只读瞬时429最多额外重试2次，累计等待不超过5秒。配额耗尽、写操作和凭证签发不自动重试。
+
 ### 认证
 
 ```
@@ -279,11 +299,12 @@ getnote note share <id>              生成公开分享链接
 
 ### 字段语义说明（适合 AI Agent 参考）
 
-不同笔记类型的"原文"字段不同，`content` 通常是 AI 总结而非原文：
+不同笔记类型的原文字段不同；`content` 可能是正文、AI 总结或个人评论：
 
-| 笔记类型 | 原文字段 | AI 总结字段 |
+| 笔记类型 | 原文字段 | 正文 / 总结 / 评论字段 |
 |---------|---------|------------|
-| 普通文字笔记 | `content` | `content` |
+| 普通文字笔记 | `content` | `content`（正文） |
+| 引用 / 划线笔记 | `ref_content` | `content`（个人评论） |
 | 链接/网页笔记 | `web_content` | `content` |
 | 录音笔记 | `audio_original` | `content` |
 | 知识库博主内容 | `post_media_text`（via `kb blogger-content`）| `content` |
@@ -312,6 +333,11 @@ getnote tag list <note_id>           查看笔记的所有标签
 ```
 getnote kbs                          列出 DEFAULT 知识库
   --scope <scope>                    指定 DEFAULT / BOOKSPACE / CUSTOMER / TEAMSPACE
+  --query <名称>                     按知识库名 / 书名查找
+  --author <作者>                    按书籍作者查找（仅 BOOKSPACE）
+  --book-id <book_id>                 按书籍 ID 查找（仅 BOOKSPACE）
+  --page-size <n>                    每页数量；新查询默认 20
+  --all                              按返回分页遍历；kbs-sub 同样支持上述查找参数
 
 getnote kb <topic_id>                知识库内的笔记
   --limit <n>
@@ -348,6 +374,18 @@ gnote note quick <note_id>
 
 ---
 
+### 文件上传与独立报告
+
+- `getnote note chapters <id> -o json` 读取章节；`note timeline` 保留录音 moments，`marks <note_id>` 独立读取标记。
+- `sprouts <YYYY-MM>` 列表从 `data.tasks[].sprouts[]` 取真实报告 id，再运行 `sprout <id>`；不要将 task_id 当报告 id。
+- `file-capabilities` 查询当前格式、大小及页数限制，不在 Agent 中写死限制。
+
+云 MCP 已授权时，无需再登录 CLI：MCP 获取临时上传 token，将 JSON 经受控文件或 stdin 交给 `getnote upload <file> --max-size-bytes <能力接口上限>`。此命令不读取 CLI 身份凭证，只向 OSS 上传，返回 `stage=oss_uploaded` 和文件元数据。随后由同一个已授权 MCP 提交知识库入库并查询最终 `SUCCESS`；上传成功不等于入库完成。不要将 token 放入命令参数、聊天或日志。
+
+CLI 已登录时也可使用 `file-token <extension>` 获取 token、`upload` 直传，再用 `file-add <topic_id> <directory_id> --metadata-file <上传结果文件>` 提交。临时 token 不提供通用 OpenAPI 权限。
+
+---
+
 ## 全局参数
 
 | 参数 | 说明 |
@@ -425,6 +463,9 @@ $ getnote search "工作日志" --limit 7 -o json
 
 | 日期 | 版本 | 新能力 | 适合怎么用 |
 |------|------|--------|------------|
+| 2026-10-13 | **v1.7.1** | 修复订阅书库布尔筛选字段解析错误；完善随包 Skill 的作者、课程、文稿和评论查找规则 | 按作者查书籍；搜索未命中时在同一来源范围补查，区分全部笔记与划线 |
+| 2026-10-13 | **v1.7.0** | 支持书名、作者、书籍 ID 定位；引用来源与时间筛选；保留分页和来源元数据 | 列表定位后通过 detail 读取完整笔记，分别核对原文与评论；Top-K 不代表全量 |
+| 2026-09-24 | **v1.6.0** | 支持文件上传、临时 OSS 上传凭据，以及独立标记、发芽和章节时间线 | 云 MCP 已授权时可用 CLI 直传文件，提交入库后确认解析状态 |
 | 2026-09-02 | **v1.5.8** | 1. `kbs` 与 `kbs-sub` 默认只返回 `DEFAULT` 知识库<br>2. 新增 `--scope`，可按 `CUSTOMER`、`BOOKSPACE`、`TEAMSPACE` 精确读取<br>3. 订阅列表不再混入自己创建的知识库 | 避免书籍库和自有库挤占订阅列表分页；需要特殊知识库时显式选择 scope |
 | 2026-08-19 | **v1.5.6** | 1. `getnote update` 默认升级 CLI、同步五个领域 Skill 并运行诊断<br>2. capabilities 2.2 提供机器可读的安装、更新、验证与平台托管边界<br>3. 移除失效的 `install.sh` 引导 | 用户只说“安装”或“更新”即可，AI Agent 无需让用户选择内部组件，并能按统一成功条件完成验收 |
 | 2026-08-19 | **v1.5.5** | 1. 一键安装自动识别本机 AI Agent，并按平台显示安装结果<br>2. 新增 GitHub Copilot、Gemini CLI、Windsurf、OpenCode 和 Cline 自动安装<br>3. OpenClaw（小龙虾）和 QClaw 仅在检测到时提供 ClawHub 确认入口<br>4. 保留 `SKILLS` 品牌开场，隐藏底层安装术语<br>5. `doctor` 按平台真实目录检查 Skill 状态 | 用户只需运行一次安装命令；AI 能根据结构化结果判断安装状态并给出明确修复动作 |
@@ -448,3 +489,7 @@ $ getnote search "工作日志" --limit 7 -o json
 ## License
 
 [MIT](https://opensource.org/licenses/MIT)
+
+## 录音台与录音卡笔记
+
+录音台（AI录音台/MOAN）按 `getnote notes --source vendor_moan --all -o json` 查找，录音卡（GetSeed）使用 `--source getseed`。来源和 note_type 独立：查设备全部笔记不额外限制 audio/meeting，录音卡长录音和闪念均保留。可叠加创建/编辑时间与知识库条件；完整性以真实分页、partial/warnings 和授权范围为准，不包含设备端未同步的会议记录。转写用 `getnote note transcript <note_id>` 读取。

package/package.json

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

package/skills/getnote-kb/SKILL.md

@@ -79,6 +79,8 @@ getnote note original '<返回的 note_id>' -o json
 - `--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；循环、空页仍声称有下一页、重复结果无进展或中途失败都不能声称“全部找到”。
 - 书库不存在、无匹配、或库内无划线，不等于账号没有该书来源的引用。用户已明确得到电子书时，可用 `getnote notes --source dedao --note-type ref --reference-type ebook --page-size 20 -o json` 按来源补查，在 `reference.title/author/book_id` 匹配；按搜索参考的预算和分页规则继续，必要时用真实 `reference.resource_id` 精确筛选。只对当前授权范围下结论，不新建库、不修改归属。
+- 平台未限定且书库路线无匹配时，可用 `getnote notes --note-type ref --page-size 20 -o json` 读取个人引用定位信息，再按真实 `reference.resource_type/book_id/title/author` 核对书籍候选；保留已知时间、平台及知识库约束，不自加 dedao。一次发现最多5页，未翻完说明范围未查完；只按需读取匹配候选正文。用户限定只查某库时就在该库补查，不扩大到个人笔记。
+- `book_info.author` 是书籍目录作者，`reference.author` 是同步引用保存的来源作者。两者冲突时分别标注来源，把引用保留为待核验候选，不把空书库查询说成账号没有笔记，也不直接认定该候选就是所问作者的著作；不会自动改写作者或笔记归属。
 
 ## 文件夹和归档流程
 

package/skills/getnote-note/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: getnote-note
-description: 使用得到大脑保存文字、链接、图片和长笔记，查看笔记详情、原文、录音转写、附件、时间线、标记、发芽报告、快捷笔记和会议待办，并安全更新、删除或分享笔记。标记、发芽与时间线分别读取。
+description: 使用得到大脑保存文字、链接、图片和长笔记，按录音台或录音卡来源查找笔记，查看笔记详情、原文、录音转写、附件、时间线、标记、发芽报告、快捷笔记和会议待办，并安全更新、删除或分享笔记。标记、发芽与时间线分别读取。
 ---
 
 # 得到大脑笔记
@@ -28,6 +28,7 @@ description: 使用得到大脑保存文字、链接、图片和长笔记，查
 | 保存文字、链接或本地图片 | `getnote save` |
 | 查询异步保存任务 | `getnote task` |
 | 查看最近笔记 | `getnote notes` |
+| 按预算读取少量个人笔记正文/原文 | `getnote notes batch` |
 | 查看详情或字段 | `getnote note` |
 | 引用/链接/文字原文 | `getnote note original` |
 | 录音、会议或课堂转写 | `getnote note transcript` |
@@ -45,6 +46,21 @@ description: 使用得到大脑保存文字、链接、图片和长笔记，查
 
 不确定参数时先运行目标命令 `--help`。
 
+## 录音台与录音卡来源定位
+
+设备来源与笔记类型是两个独立条件。用户明确说“录音台”“AI录音台”“墨案/MOAN录音台”时使用 `--source vendor_moan`；“录音卡”“GetSeed录音卡”使用 `--source getseed`。查设备全部笔记时只限定来源，不额外加 `--note-type audio` 或 `meeting`，避免漏掉其他实际类型；录音卡长录音和闪念也由同一个 getseed 来源覆盖。用户明确只要长录音/闪念时，才分别叠加 `recorder_audio` / `recorder_flash_audio`。
+
+```bash
+getnote notes --source vendor_moan --page-size 20 --all -o json
+getnote notes --source getseed --page-size 20 --all -o json
+```
+
+“昨天/上周的录音台笔记”同时保留对应 `--created-from/to`，按用户时区换算为 RFC3339，from 包含、to 不包含；明确修改时间才改用 edited 或 record-updated。翻页始终保留 source、时间、知识库等原条件，核对 `applied_filters.source` 和每条笔记的 `source`，按真实游标继续并按字符串 note_id 去重。仅在遍历结束、没有未解决的 partial/warnings 或错误时，才能说当前授权范围已遍历；旧 total 不是设备范围的总条数。
+
+结果只涵盖已经同步成笔记且当前账号有权读取的主笔记，不代表设备端未同步、尚未形成笔记的全部会议记录。空结果不能改查其他来源后声称完成，不能用“AI录音台”标签或标题猜来源。只说“录音笔记”而未限定设备时不加 vendor_moan/getseed；按已知录音模式核对真实类型，模式不明时保留不同类型候选并说明范围。
+
+来源内有正文主题时，先在该来源和时间范围列出候选，再按需读取目标正文核实；`search` 不提供设备来源筛选，不能把全局 Top-K 后过滤当作该设备完整搜索。录音台/录音卡转写使用 `getnote note transcript '<note_id>' -o json`，不把 AI 总结、preview 或缺失转写当作原文。
+
 ## 来源筛选、轻量定位与原文
 
 列表接口只返回定位信息，再用详情接口读取完整笔记。`display_title` 是展示标题，不覆盖原始 `title`；引用笔记空标题很正常。`preview` 是带来源和截断标记的定位片段，不是全文。
@@ -62,9 +78,24 @@ getnote note original '<note_id>' -o json
 | link | web_page.content | 通常是摘要 |
 | audio / local_audio | audio.original | 通常是摘要 |
 
+录音按真实类型选择：即时录音/普通录音用 `--note-type audio`，上传的音频文件用 `local_audio`，自己录制的课堂笔记用 `class_audio`，会议录音用 `meeting`，系统内录用 `internal_record`，录音卡长录音/闪念分别用 `recorder_audio` / `recorder_flash_audio`。这些类型与得到课程引用不同；用户未限定平台时不加 `--source dedao` 或课程筛选。只说“录音”且模式不明时保留候选并说明类型，不能把上传音频当即时录音。
+
+```bash
+getnote notes --note-type audio --all -o json
+getnote notes --note-type local_audio --all -o json
+```
+
 `original` 只按真实类型读取上述字段，并返回 `original_source`；原文缺失或类型不支持会报错，不能把评论或定位片段补成原文。列表中的 `content_state` 会标明正文被省略；详情接口返回完整正文和元数据。用 `metadata_state.reference/topics` 区分完整、部分、不可用的元数据；缺失的作者、书 ID、来源 URL 不猜测补写。
 
-文章或课程没有知识库时，已有候选可从详情或搜索结果读取真实 `reference` 后精确查找。只有课程名/文稿名或评论、尚无候选时，先执行搜索 Skill 的“课程、文稿与评论定位”：语义搜索无来源匹配后，按来源分页列定位信息再匹配元数据；不要要求用户提供内部 ID，也不要因 `topics=[]` 放弃。拿到候选后精确查找：
+得到课程无需知识库：已知课程名/老师时先按搜索 Skill 执行 `getnote references list --source dedao --resource-type course --query '<课程名>' --all -o json`，再用真实课程容器身份筛选；author 精确匹配老师，query 可显式 prefix。同名版本先消歧，topics=[] 不阻断；不要求用户提供内部 ID。
+
+```bash
+getnote notes --source dedao --course-type '<course_type>' --course-id '<course_id>' --note-type ref --all -o json
+```
+
+课程容器身份是 course_type+course_id；当前66，不能用课节65的 resource_id 代替。课程筛选包含课程直接引用和所属课节，增量 reference.course 不改旧 resource_id。首版 course+topic_id 不支持，不用个人笔记冒充知识库交集。新能力缺失时报告不支持，不删除筛选继续查询。
+
+单篇文稿已有真实 reference ID 或文章 URL 时继续使用旧精确筛选：
 
 ```bash
 getnote notes --source dedao --note-type ref --reference-type course_article --reference-id '<reference.resource_id>' --all -o json
@@ -72,12 +103,22 @@ 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` 指向单篇文稿，不能据此取全整门课程；整门课程需按搜索参考的课程来源匹配遍历。引用的 `resource_id`、`original_note_id`、书 ID 与笔记 ID 都是不同身份；始终按返回的字符串使用。课程主页与文稿 URL 不通用；用户给的是课程主页时按搜索参考匹配 `reference.url`，不能传到 `--article-url`。URL 保留 query/fragment，不自行去参。同一文章可以有多个不同的 `original_note_id`，不可按文章 ID 合并成一条划线。
+平台值取 `reference.source`；资源类型取 `reference.resource_type`，不要用标签或内部 ptype 猜枚举。`--reference-id` 必须同时传 `--source` 和 `--reference-type`。课程文稿的 resource_id 指向单篇文稿，课程筛选再加 reference-id 时取交集。resource_id、course_id、original_note_id、书 ID 与笔记 ID 是不同身份；全程用返回的字符串。课程主页不传到 --article-url，也不解析编码 ID；文章 URL 保留 query/fragment。同篇文稿的不同笔记 ID 仍是不同划线。
 
 创建、正文编辑、记录更新是三个独立时间轴。按需使用 `--created-from/to`、`--edited-from/to`、`--record-updated-from/to`，值必须为带时区 RFC3339；区间 from 包含、to 不包含。不得把 `updated_at` 当正文编辑时间。“今天/上周”按用户当前日期和时区换算边界；保存时间不是文章发布日期，不把“最近”擅自解释成固定一个月。用户同时限定课程/知识库时保留这些条件。
 
 新参数需要服务端对应 `meta.capabilities` 且 `applied_filters` 与请求一致；不支持时停止该查询并说明升级服务/客户端的需要，不自动移除筛选。全量按知识库参考中的分页规则验收；只拿一页或一次语义搜索，不能说“全部找到”。
 
+分页结束与来源完整性分别判断：`partial=true`、`warnings`、候选 `metadata_state=partial` 仍须说明。特别是 `course_directory_no_lessons` 表示课程目录缺少课节，即使 `has_more=false` 或 `traversal.completed=true` 也不能保证找全老师的所有课程；保留已找到的真实结果和缺口，不通过删除筛选或重复同一请求消除警告。
+
+## 有预算的批量正文读取
+
+不超过20个已定位个人笔记用 `getnote notes batch '<note_id_1>' '<note_id_2>' --fields original -o json`。默认 fields=content,ref_content,reference；original 显式选择，引用原文来自 ref_content，个人评论来自 content。默认32000个Unicode码点，--max-total-chars 可设1..64000，服务端另有1MiB上限；不是给旧单条详情加截断。
+
+退出码0和 success=true 只代表批量调用成功：逐条检查 status=ok/unavailable/failed/deferred_budget、content_state、partial、pending_ids。成功项正文完整，deferred_budget 整条待读，不能把 omitted 当空正文；未知未来状态原样保留并说明未确认。用户确需全文时再用旧 `getnote note original '<真实note_id>' -o json` 补读，不自动并发20次单条请求。不存在与无权统一 unavailable，不判断对象是否存在；首版不批量读知识库共享笔记，不绕过原单条权限。
+
+参数错误读取 field/supported_values；限流保留 retry_after_seconds。CLI 已对已知只读瞬时429做最多额外2次、累计等待5秒重试；Agent 不叠加重试，日/月配额、写操作与上传凭证不自动重试。
+
 ## 保存流程
 
 ### 文字与长文

package/skills/getnote-search/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: getnote-search
-description: 在得到大脑查找笔记：按书名、课程名、文稿标题、作者、评论或模糊记忆选择来源定位与语义搜索，返回真实笔记和链接。
+description: 在得到大脑查找笔记：按录音台、录音卡来源，以及书名、课程名、文稿标题、作者、评论或模糊记忆选择来源定位与语义搜索，返回真实笔记和链接。
 ---
 
 # 得到大脑搜索
@@ -15,6 +15,7 @@ description: 在得到大脑查找笔记：按书名、课程名、文稿标题
 
 ## 先选查找路径
 
+- 明确录音台或录音卡：先读笔记 Skill 的“录音台与录音卡来源定位”，分别用 `notes --source vendor_moan` / `notes --source getseed`，保留时间与知识库条件。设备全部笔记不默认加 note-type，也不先全局语义搜索。
 - 明确书籍（书名或书籍作者），尤其要“全部划线”：先读知识库参考。书名用 `kbs --scope BOOKSPACE --query`；只有作者名时用 `kbs --scope BOOKSPACE --author` 并省略 `--query`，不能把作者塞进只匹配名称的 query。书名和作者都已知时才同时传，两者为 AND 条件。必要时用真实 `--book-id` 消歧，再按用户要“全部笔记”还是“划线”选择是否加 `--note-type ref`，需要全文时按 ID 调用 `note`。
 - 明确文章/课程（包括“某老师的课”）：按下方“课程、文稿与评论定位”执行。已有真实来源 ID/文章链接时直接精确筛选；没有候选也能按来源列定位信息。`topics=[]` 不阻断这条路线。
 - 只有主题或模糊记忆：语义搜索 → 按字符串笔记 ID 去重 → 对选中候选读详情/原文。Top-K（最大 10）不是完整清单；零命中也不能证明全库没有相关笔记。
@@ -26,9 +27,10 @@ description: 在得到大脑查找笔记：按书名、课程名、文稿标题
 | “找博尔赫斯的书籍笔记” / “找提到博尔赫斯的笔记” | 前者按书籍 author 定位；后者是内容主题搜索，不把所有提到一个人的笔记都限制为其著作。 |
 | “某课程共读《某本书》那篇文稿” | 明确课程/文稿时优先课程引用路径，书名在这里是文稿线索，不跳去 BOOKSPACE。 |
 | “课程笔记” | 先区分得到课程引用与自己录制的课堂笔记；只有用户明确来源时才设 dedao/course_article，不能把课堂录音排除掉。 |
+| “即时录音” / “上传的音频” | 前者用 notes --note-type audio，后者用 local_audio；课堂录音为 class_audio，会议为 meeting。平台未限定时不加 dedao 或课程条件。 |
 | “某库/某书里关于某主题” | 先定位真实 topic_id，再 search --kb；未命中按知识库参考在该库列表补查，不把空搜索当作库内没有，不得遗漏库范围。 |
 | “上周保存/昨天修改的某课程笔记” | 列表用对应时间筛选；search 没有时间/来源筛选参数，语义候选需核对 timestamps/reference。不能把时间词拼进 query 就宣称完成了时间筛选。 |
-| “某课程链接下的笔记” / “这篇文稿链接的划线” | 课程主页 URL 匹配 reference.url 后取该课程各篇；文稿 URL 才传 --article-url。URL 中的编码 ID 不是 --reference-id，不自行转换。 |
+| “某课程链接下的笔记” / “这篇文稿链接的划线” | 已知课程名/老师时查课程容器；只有主页 URL 时核对真实 reference.url，不猜课程 ID。文稿 URL 才传 --article-url。 |
 | “全部笔记” / “全部划线” | 前者不默认加 note-type ref；书籍库可能有心得等非引用笔记。得到课程引用路径只能证明该来源下的划线集合，不能涵盖用户另写的课程心得或录音。 |
 
 多条件查询要保留用户全部约束；从候选转入精确文稿列表时也保留已指定的 topic/time/source。条件冲突或作者、版本不符时说明实际候选，不静默删除条件。有正文主题限制时，来源匹配只证明“来自这里”，还需核对正文；截断 preview 未出现某词不能当作全文不包含。多个库/多本书合并结果时按字符串 note_id 去重，不能合并不同 ID 的不同划线。
@@ -37,37 +39,48 @@ description: 在得到大脑查找笔记：按书名、课程名、文稿标题
 
 ## 课程、文稿与评论定位
 
-`search` 是 Top-K 语义召回，来源元数据出现在返回值中不保证它参与了召回。不要因为搜到了别的笔记就把指定课程的任务判为成功。
+先区分课程容器和单篇文稿；`search` 是 Top-K 语义召回，来源元数据出现在结果中不能证明课程范围参与召回。课程名、老师、主题、评论、时间和真实知识库范围均需保留。
 
-1. **提取约束**：区分课程名、文稿名、授课人、内容主题、评论和用户给定时间。例如“帮我找林老师《科学课》里讲概率那篇划线”应保留课程/授课人约束，不把整句话只搜一次便结束。已提供精确文章 URL 时直接读笔记参考的来源筛选。
-2. **发现候选**：可先用课程/文稿关键词 `getnote search '<课程名或文稿标题关键词>' --limit 10 -o json`。核对结果的 `note.reference`；旧结果没有它时对相关候选读 `note`。无来源匹配、只有无关结果，或用户要“整门课程的全部笔记”时，进入下面的来源列表，不反复换整句搜索。
-3. **来源列表补查**：用户明确说得到课程时执行以下命令；同一对话可复用已经读取的页，但用户说新增了笔记时必须重新读取。
+### 已知课程名或老师：先查课程容器
+
+使用 `getnote references list`，无需用户提供内部 ID，也不需要先建知识库：
 
 ```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
+getnote references list --source dedao --resource-type course --query '<课程名>' --author '<准确老师姓名>' --match-mode exact --all -o json
+getnote notes --source dedao --course-type '<course_type>' --course-id '<course_id>' --note-type ref --all -o json
 ```
 
-用户给定时间/知识库时同时保留对应筛选，不擅自增加“最近一个月”等限制；来源未明确时先依据候选核实，不把所有课程都当作得到来源。只读取定位信息，不先下载全库正文。此命令没有课程名查询参数，名称由 Agent 在返回的元数据中匹配，不能说成服务端按课程名直接筛选。
+只传已知的 query/author，至少一个；二者为 AND 条件，query 只匹配课程名，author 精确匹配老师。课程名不完整时显式用 `--match-mode prefix`；不把“讲概率”这样的正文主题塞进课程名。结果同名或版本不明时列候选消歧；用返回的 `course_type`+`course_id`，当前支持66，不解析标题、URL或课节 ID 生成课程 ID。空结果页若 `pagination.has_more=true` 仍按真实 `next_cursor` 继续，保持所有条件；循环或失败表示遍历未完成。`--all` 成功的 `traversal.completed=true` 只证明当前同步、授权范围内的遍历，不是得到 App 的全部划线。
 
-| 用户线索 | 核对字段与边界 |
-|---|---|
-| 课程名称、简称 | `reference.title`；允许忽略外围书名号、空格、全半角差异来找候选，保留季数/版本，不把“日课6”当成其它季。 |
-| 文稿标题 | `reference.article.title`；片段可用于候选匹配，详情核验后再认定。 |
-| 老师/作者 | 优先 `reference.author`；缺失时，名称出现在课程标题中可作为候选线索，但不能虚构 author 字段或断言身份。 |
-| 同课程、多篇文稿 | 用真实 `reference.url` 区分课程，缺失或同名冲突时列候选；每篇文稿的 resource_id 不能代替课程 ID。 |
-| 个人评论 | 读取候选详情的 `content`，不在 `preview` 或 `ref_content` 中猜评论。 |
+课程筛选同时包含课程直接引用和所属课节；显式增加 `--reference-type course_article` 会再限制为课节引用，`--reference-id` 仍是原课节 ID，组合按交集。需要时间条件时保留对应创建/编辑/记录更新时间参数。首版只支持个人笔记，course+topic_id 明确不支持；用户同时指定真实知识库时说明当前交集尚不可用，不能改查个人笔记后声称满足库范围。课程内语义搜索尚未开放，不能在全局 Top-K 后过滤冒充；可先精确列出课程笔记，再按需读正文核实主题。
+
+新请求需当前服务端声明 `reference.resources.v1` / `note.course_filter.v1`，并核对 applied_filters。服务未支持时报告能力缺失，不自动删除课程条件继续，不把 CLI 安装成功当作服务已发布。旧参数和默认调用继续可用。
+
+每页的 `partial`、`warnings` 和候选 `metadata_state` 都要保留。`course_directory_no_lessons` 表示目录缺少课节；翻到末页或 `traversal.completed=true` 不会消除这个缺口，回复“已找到这些，部分课程目录不完整，无法保证全部”。`candidate_work_budget` 且有下一游标时按原条件继续；游标结束后仍有目录警告，就保留部分完成结论，不改用账号全量扫描来宣称目录已经补齐。
+
+### 已知单篇文稿或文章 URL
+
+直接使用已验证的 `reference.resource_id`+`reference.resource_type` 或 `reference.article.url` 精确筛选：
 
-4. **控制遍历与消歧**：按返回 `pagination.has_more/next_cursor` 翻页，按字符串 note_id 去重，并核对 capabilities/applied_filters；遇到游标循环、重复无进展或中途失败就说明未完成。一次来源候选发现先读最多 5 页（每页 20 条）；超过时保留已找到候选与进度，说明仍未查完，结合用户线索缩小范围或询问是否继续。不得把这个执行预算当作“全库没有”。用户明确要求全部时按知识库参考的完整分页规则继续；只有确实遍历完成才能给全量结论。同名课程/同名文稿无法区分时列候选让用户选择。相关 `metadata_state.reference` 为 partial/unavailable 或所需字段缺失时，保留为待核验候选，必要时读详情；不能仅靠字段缺失断言不属于目标来源。
-5. **完成用户的目标**：找一条时读取匹配候选详情；找同篇全部划线时，用笔记参考的 `--reference-id` 或 `--article-url` 精确取全；找整门课全部时需完成课程引用范围遍历，按课程来源分组，再逐条按需读详情。保留原文、个人评论、来源的区别；不按文稿 ID 把多条划线合并成一条。
+```bash
+getnote notes --source dedao --note-type ref --reference-type course_article --reference-id '<真实课节ID>' --all -o json
+getnote notes --source dedao --note-type ref --article-url '<真实文章URL>' --all -o json
+```
+
+仅有文稿标题时可语义查候选并核对真实 reference.article.title；找到了课程线索就进入课程容器流程缩小范围。课程主页 URL 与文稿 URL 不互换，不从编码链接猜 ID。没有名称线索的课程主页可沿用既有来源列表核对 reference.url，但不得假称服务端按课程名筛选；定位前5页的预算到达时说明未完成，用户要全部时继续合法分页。metadata_state.reference 为 partial/unavailable 时保留为待核验候选，不能凭缺失字段排除。
 
-只记得个人评论时：先用评论的实质文本做语义搜索并读详情核对。若用户已限定得到课程但搜索无匹配，可按上述来源列表缩小候选；评论在列表被省略，不能据此排除候选。小候选集（不超过 20 条）可按需逐条读取详情匹配，多于 20 条时先用已给的课程/文稿/时间进一步缩小，仍不足再向用户询问线索，不能批量下载整个账号全文。“有启发”等泛化评论可能对应多条，返回全部已核实候选而非随意选第一条。用户没有限定来源时，不自行只查课程后声称查完所有评论。
+### 读取原文与评论
+
+对不超过20个已定位的个人笔记，使用 `getnote notes batch '<note_id_1>' '<note_id_2>' --fields original -o json`；引用原文来自 ref_content，查个人评论改用 fields=content。保留每条 status、content_state、pending_ids、partial；deferred_budget 表示整条待读，不能说完整，也不自动并发20次单条读取。用户确需未读全文时使用旧 `getnote note original '<note_id>' -o json`。知识库共享详情继续原单条权限路径，不用个人批量绕过权限。
+
+只记得评论时先语义搜索实质文本并读 content 核对；已指定课程就先按课程缩小，不因 preview 没出现评论而排除。定位候选多于20条时保留用户线索继续缩小或分页按需读取，不下载整个账号正文。同一篇文稿的不同笔记 ID 是不同划线，不按文章 ID 合并。
 
 ## 语义搜索执行步骤
 
 仅当上面的路径选择需要语义搜索时执行；没有指定知识库不等于必须先语义搜索。
 
+定位时可显式使用 `getnote search '<主题>' --response-mode snippet --max-snippet-chars 400 -o json`，需当前接口声明 search.snippet.v1。旧调用不加参数仍返回原契约。摘要 full 只表示本次命中的完整片段，不是全文；保留 snippet_source、truncated、content_state 和资源身份，未知来源/类型原样保留。需要全文时读真实笔记详情。
+
 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`。
@@ -111,6 +124,7 @@ getnote search "客户反馈" --kb <topic_id> --limit 5 -o json
 ## 失败、隐私与后续动作
 
 - `success=false` 或退出码非 0：回复失败步骤、`error.message` / `error.reason`、是否 `retryable` 和可选 `request_id`；不要将 HTTP 成功或空输出说成搜索成功。
+- 参数错误先读取 field/supported_values；限流保留 retry_after_seconds。CLI 已对已知只读瞬时429做最多额外2次、累计等待5秒的重试，Agent 不再叠加无界重试；日/月配额和写操作不自动重试。
 - 若 CLI 提示“搜索服务响应超时”，这是检索未完成，不是“没有结果”。建议稍后重试，或缩小关键词、指定知识库后再试；不要伪造空列表。
 - 检索结果可能包含私密正文。群聊或共享会话默认只展示标题、必要摘要和真实链接；用户明确要求后再展开全文。
 - 用户选中结果后，复用返回的字符串 `note_id`，再读取 `getnote note <note_id> -o json`；不要从 URL 截取或转换为数字。