@getnote/cli 1.6.0 → 1.7.0

package/README.md

@@ -1,5 +1,9 @@
 # 得到大脑（Get笔记） CLI
 
+## 1.7.0 查找与引用
+
+支持书库身份与书名查找、引用来源筛选及完整分页。列表用于定位，完整内容由 `getnote note <id>` 读取；引用原文与个人评论分别返回。搜索保留部分结果与资源身份，Top-K 不代表全量。随包五个领域 Skill 已同步这些调用规则。
+
 ## v1.6：文件上传与独立报告
 
 - `getnote note chapters <id> -o json` 读取章节；`note timeline` 保留录音 moments，`marks <note_id>` 独立读取标记。

package/package.json

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

package/skills/getnote-kb/SKILL.md

@@ -45,6 +45,27 @@ description: 查看和管理得到大脑的知识库、文件夹、书籍、客
 4. 订阅知识库通常只读。若列表结果明确返回角色或可写标记，按真实字段判断；当前 CLI 契约未保证权限字段时，不得声称已经预检为 owner/admin，可在用户明确授权后尝试写入，并忠实处理权限失败。
 5. 普通成员写入失败时明确说明权限不足，不尝试绕过。当前不代替用户新建团队知识库。
 
+## 按书名找全部划线
+
+用户要某本书的划线或“全部笔记”时，先定位书籍知识库，不把语义搜索的 Top-K 当全量。
+
+```bash
+getnote kbs --scope BOOKSPACE --query '书名' --author '用户提供的作者' --all -o json
+# 用户明确查订阅库，或自有库无匹配时，再查询真实订阅的书籍库
+getnote kbs-sub --scope BOOKSPACE --query '书名' --all -o json
+getnote kb '<返回的 topic_id>' --note-type ref --page-size 20 --all -o json
+getnote note original '<返回的 note_id>' -o json
+```
+
+- 作者未知时省略 `--author`。先用 `name`、`scope=BOOKSPACE`、`book_info.title/author/book_id` 核对候选；同名多作者、多版本仍不唯一时请用户选择，不能用第一项代替。已有真实书 ID 可加 `--book-id`，它不是知识库 ID。
+- query/author 会做 NFKC、外围书名号/引号和大小写归一化；这只是候选定位，不证明同名书是同一本。
+- 普通知识库在笔记的 `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`，再按笔记/搜索参考的引用来源路线查找，不自动建库或修改归属。
+
 ## 文件夹和归档流程
 
 1. 用户要求放入文件夹时，用 `gnote kb dir <topic_id> -o json` 读取根目录或指定目录。

package/skills/getnote-note/SKILL.md

@@ -29,7 +29,7 @@ description: 使用得到大脑保存文字、链接、图片和长笔记，查
 | 查询异步保存任务 | `getnote task` |
 | 查看最近笔记 | `getnote notes` |
 | 查看详情或字段 | `getnote note` |
-| 链接/文字原文 | `getnote note original` |
+| 引用/链接/文字原文 | `getnote note original` |
 | 录音、会议或课堂转写 | `getnote note transcript` |
 | 图片、音频和文件附件 | `getnote note attachments` |
 | 录音或会议时间线 | `getnote note timeline` |
@@ -45,6 +45,39 @@ description: 使用得到大脑保存文字、链接、图片和长笔记，查
 
 不确定参数时先运行目标命令 `--help`。
 
+## 来源筛选、轻量定位与原文
+
+列表接口只返回定位信息，再用详情接口读取完整笔记。`display_title` 是展示标题，不覆盖原始 `title`；引用笔记空标题很正常。`preview` 是带来源和截断标记的定位片段，不是全文。
+
+```bash
+getnote notes --source dedao --note-type ref --page-size 20 -o json
+getnote note '<note_id>' -o json
+getnote note original '<note_id>' -o json
+```
+
+| note_type | 原文字段 | content 的语义 |
+|---|---|---|
+| ref | ref_content | 用户评论，不是引用原文 |
+| plain_text | content | 用户正文 |
+| link | web_page.content | 通常是摘要 |
+| audio / local_audio | audio.original | 通常是摘要 |
+
+`original` 只按真实类型读取上述字段，并返回 `original_source`；原文缺失或类型不支持会报错，不能把评论或定位片段补成原文。列表中的 `content_state` 会标明正文被省略；详情接口返回完整正文和元数据。用 `metadata_state.reference/topics` 区分完整、部分、不可用的元数据；缺失的作者、书 ID、来源 URL 不猜测补写。
+
+文章或课程没有知识库时，先从已有详情或语义搜索候选读取真实 `reference`，再精确查找：
+
+```bash
+getnote notes --source dedao --note-type ref --reference-type course_article --reference-id '<reference.resource_id>' --all -o json
+# 缺少资源 ID，但有 reference.article.url 时，可改用精确文章 URL
+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 合并成一条划线。
+
+创建、正文编辑、记录更新是三个独立时间轴。按需使用 `--created-from/to`、`--edited-from/to`、`--record-updated-from/to`，值必须为带时区 RFC3339；区间 from 包含、to 不包含。不得把 `updated_at` 当正文编辑时间。
+
+新参数需要服务端对应 `meta.capabilities` 且 `applied_filters` 与请求一致；不支持时停止该查询并说明升级服务/客户端的需要，不自动移除筛选。全量按知识库参考中的分页规则验收；只拿一页或一次语义搜索，不能说“全部找到”。
+
 ## 保存流程
 
 ### 文字与长文
@@ -74,11 +107,11 @@ description: 使用得到大脑保存文字、链接、图片和长笔记，查
 
 ## 查询和深层读取
 
-1. “最近、列表、有哪些”使用 `getnote notes`；“找、搜、关于某主题”交给搜索 Skill。
+1. “最近、列表、有哪些”使用 `getnote notes`；有明确书名或引用来源时按上面的来源/知识库路线查找，模糊主题才交给搜索 Skill。
 2. 用户给出 ID 时直接读取详情；雪花 ID 全程按字符串原样传递。“这条笔记”只复用当前会话中已经由 CLI 返回并验证过的字符串 ID。当前 CLI 若不能直接接收某种私有链接，就先请用户提供 ID，不能自行截取、猜测或转成数字。
 3. 列表先展示标题、字符串 ID 和真实 `note_url`，用户选择后再读取全文。
 4. 不确定笔记类型时先读 `getnote note <id> -o json`：
-   - 链接/文字原文：`original`；
+   - 引用/链接/文字原文：`original`；
    - 录音、会议、课堂逐字稿：`transcript`；
    - 图片、音频、文件：`attachments`；
    - 章节时间点与会议过程：`chapters`，读取 `chapter_timeline.items`，保留规则解析来源 `source`；录音 moments 使用 `timeline`，两者不是同一份数据；
@@ -103,7 +136,7 @@ description: 使用得到大脑保存文字、链接、图片和长笔记，查
 | `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 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` 当原文；空字段就是该笔记没有可用原文。 |
+| `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` | 仅录音类笔记可用；不可用时如实说明。 |
 | `getnote note attachments <id> -o json` | `data.note_id/title/attachments[]` | 列出真实附件，不把笔记封面冒充附件。 |
 | `getnote note timeline <id> -o json` | `data.note_id/title/timeline` | 仅在存在录音/会议时间线时展示。 |

package/skills/getnote-search/SKILL.md

@@ -9,10 +9,18 @@ description: 在得到大脑的全部笔记或指定知识库中按自然语言
 
 ## 何时使用
 
-- “找找、搜一下、关于某主题、我之前记过什么”：使用 `getnote search`。
+- “关于某主题、模糊记忆”：使用 `getnote search`；明确书籍/来源或要全量时按下方路径选择。
 - “最近有哪些笔记、按保存时间列出来”：交给笔记 Skill 的 `getnote notes`，不要把列表误当语义搜索。
 - 用户选中某一条后，再交给笔记 Skill 用 `getnote note <note_id>` 读取详情；搜索阶段不自动修改、移动、分享或创建笔记。
 
+## 先选查找路径
+
+- 明确书名、作者，尤其要“全部划线”：先读知识库参考，用 `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=[]` 不阻断这条路线。没有候选时，语义搜索只用于发现来源候选，核对引用后再查全部。
+- 只有主题或模糊记忆：语义搜索 → 按字符串笔记 ID 去重 → 对选中候选读详情/原文。Top-K（最大 10）不是完整清单；零命中也不能证明全库没有相关笔记。
+
+增强结果的 `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 时只呈现真实资源信息，不能拼笔记链接。
+
 ## 执行步骤
 
 1. 用户没有指定知识库时，直接执行 `getnote search <query> --limit <1-10> -o json`。默认上限是 10，不能自行放大。
@@ -36,16 +44,16 @@ getnote search "客户反馈" --kb <topic_id> --limit 5 -o json
 |---|---|---|
 | `success` | 业务是否成功 | 只有 `true` 才继续呈现结果。 |
 | `data.results[]` | 搜索结果 | 空数组是一次成功的“未找到”，不是失败。 |
-| `data.results[].title` | 笔记标题 | 列表主标题；为空时如实显示“未命名笔记”。 |
+| `data.results[].title` | 笔记标题 | 优先用 note.display_title；旧响应再用 title，均缺失才显示未命名。 |
 | `data.results[].note_id` | 笔记雪花 ID | 始终作为字符串原样传入后续 `note` 命令。 |
 | `data.results[].note_url` | 真实笔记链接 | 只有非空时才给用户“打开笔记”。 |
 | `data.results[].content` | 命中摘要或正文片段 | 只摘取与问题相关的短片段，不能冒充全文。 |
-| `data.results[].score` | 相关性分数 | 仅用于内部排序，不向用户虚构“准确率”。 |
+| `data.results[].score` | 相关性分数，可为 null | null 表示未知；仅用于内部排序，不向用户虚构“准确率”。 |
 
 成功时按相关性给出编号列表，例如：
 
 ```text
-找到 3 条相关笔记：
+这次搜索找到 3 条不同的相关笔记：
 1. 《支付流程优化想法》——“用户等待时增加进度提示…”
    打开：<真实 note_url>
 2. 《客户支付反馈》——“…”
@@ -53,7 +61,7 @@ getnote search "客户反馈" --kb <topic_id> --limit 5 -o json
 你想看哪一条的详情或原文？
 ```
 
-若 `data.results=[]`，回复“没有找到相关笔记；可以换关键词、时间范围或指定知识库再试”，不要说“接口失败”，也不要自动扩大检索范围、创建笔记或调用模型编造结果。
+若 `data.partial=true` 或存在 `data.warnings`，先说明检索有部分结果未能完成权限验证或读取，并按 warnings 解释原因；空结果也不能表述为完整检索后无命中。仅当没有部分失败时，若 `data.results=[]`，回复“没有找到相关笔记；可以换关键词、时间范围或指定知识库再试”，不要说“接口失败”，也不要自动扩大检索范围、创建笔记或调用模型编造结果。
 
 ## 失败、隐私与后续动作