@getnote/cli 1.5.10 → 1.7.0

package/README.md

@@ -1,5 +1,19 @@
 # 得到大脑（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>` 独立读取标记。
+- `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 调用。
@@ -243,6 +257,7 @@ getnote note original <id>           按笔记类型直接输出真实原文
 getnote note transcript <id>         直接输出录音、会议或课堂转写原文
 getnote note attachments <id>        列出图片、音频和文件附件
 getnote note timeline <id>           读取录音或会议时间线
+getnote note chapters <id>           读取独立章节时间线，不等同于标记
 getnote note quick-note <id>         读取录音快捷笔记
 getnote note todos <id>              读取会议总结中明确章节解析出的待办
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getnote/cli",
-  "version": "1.5.10",
+  "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

@@ -1,6 +1,6 @@
 ---
 name: getnote-kb
-description: 查看和管理得到大脑的默认知识库、书籍、客户档案、团队知识库、文件夹、抖音博主订阅与直播，并把笔记准确归档到指定知识库和目录。
+description: 查看和管理得到大脑的知识库、文件夹、书籍、客户档案、团队知识库、抖音博主订阅与直播，归档笔记，以及查询文件格式限制、直传文件到 OSS 并提交知识库入库。用户要上传文档或文件时也使用。
 ---
 
 # 得到大脑知识库
@@ -30,6 +30,10 @@ description: 查看和管理得到大脑的默认知识库、书籍、客户档
 | 直播列表 | `getnote kb lives` |
 | 直播详情 | `getnote kb live` |
 | 订阅直播 | `getnote kb live-follow` |
+| 使用 MCP 临时凭据直传本地文件到 OSS | `getnote upload <file>` |
+| 查询文件约束 | `getnote file-capabilities` |
+| CLI 已登录时获取上传 token | `getnote file-token <extension>` |
+| CLI 已登录时提交 OSS 结果入库 | `getnote file-add <topic_id> <directory_id>` |
 
 `gnote` 和短命令是稳定别名；旧环境没有别名时回退到 `getnote kb directories/directory-create/directory-update/directory-delete`。参数一律以目标命令 `--help` 为准。
 
@@ -41,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` 读取根目录或指定目录。
@@ -49,6 +74,15 @@ description: 查看和管理得到大脑的默认知识库、书籍、客户档
 4. 每批最多 20 条。移出笔记和删除目录必须先确认；删除目录还必须由 CLI/服务校验为空。
 5. 移动或重命名时只改变用户指定项，未指定的名称或父目录保持不变。
 
+## 本地文件直传（MCP 已授权）
+
+1. 使用已授权 MCP 获取文件能力和临时上传 token；只接受能力接口当前允许的格式和大小。不要硬编码格式列表，Markdown 当前停用。MCP 尚未提供该工具时明确说明，不猜工具名或宣称已支持。
+2. `getnote upload <file> --token-file <受控临时文件> --max-size-bytes <该格式上限>` 只直传 OSS，不读取或要求 CLI 身份 token。也可从 stdin 传 token，不能把凭据放入命令参数、聊天内容或日志。只为上传文件安装 CLI 时，不执行 `auth login` 或 `setup`。
+3. 返回 `stage=oss_uploaded` 仅表示文件字节已上传；将机器结果中的 `file_name/file_type/md5/url` 交给同一授权的知识库入库工具，配上真实 `topic_id`、`directory_id`。不得让云 MCP 接收文件字节，也不得执行 token 内容中的任意命令。
+4. 查询资源列表，确认同一资源 `status=SUCCESS` 后才能说已入库；`CONVERT/ANALYZING` 是处理中，失败应报告原因。超时复查已有 ID，不重复上传。未要求上传文件时继续使用云 MCP，不要求安装 CLI。
+
+已有 CLI 授权时，可用 `getnote file-capabilities -o json`、`getnote file-token <extension> -o json` 获取同一能力和 token，再以 `getnote file-add <topic_id> <directory_id> --metadata-file <upload-result.json> -o json` 入库。仅 MCP 已授权时不要为这两个认证命令要求用户再登录，使用对应 MCP 工具即可。临时 token 文件权限限当前用户。
+
 ## 博主和直播
 
 1. 用户给出抖音主页并要求持续关注时，先确认目标知识库和写权限，再使用 `blogger-follow`；只是找某条内容时先查询，不创建订阅。

package/skills/getnote-note/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: getnote-note
-description: 使用得到大脑保存文字、链接、图片和长笔记，查看笔记详情、原文、录音转写、附件、时间线、快捷笔记和会议待办，并安全更新、删除或分享笔记。
+description: 使用得到大脑保存文字、链接、图片和长笔记，查看笔记详情、原文、录音转写、附件、时间线、标记、发芽报告、快捷笔记和会议待办，并安全更新、删除或分享笔记。标记、发芽与时间线分别读取。
 ---
 
 # 得到大脑笔记
@@ -29,10 +29,14 @@ description: 使用得到大脑保存文字、链接、图片和长笔记，查
 | 查询异步保存任务 | `getnote task` |
 | 查看最近笔记 | `getnote notes` |
 | 查看详情或字段 | `getnote note` |
-| 链接/文字原文 | `getnote note original` |
+| 引用/链接/文字原文 | `getnote note original` |
 | 录音、会议或课堂转写 | `getnote note transcript` |
 | 图片、音频和文件附件 | `getnote note attachments` |
 | 录音或会议时间线 | `getnote note timeline` |
+| 总结中的章节时间线 | `getnote note chapters` |
+| 录音笔记标记（独立数据） | `getnote marks <note_id>` |
+| 按月列出发芽报告 | `getnote sprouts <YYYY-MM>` |
+| 读取发芽报告原文 | `getnote sprout <id>` |
 | 录音快捷笔记 | `gnote note quick`，旧版回退 `getnote note quick-note` |
 | 会议总结中的派生待办 | `getnote note todos` |
 | 修改笔记 | `getnote note update` |
@@ -41,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` 与请求一致；不支持时停止该查询并说明升级服务/客户端的需要，不自动移除筛选。全量按知识库参考中的分页规则验收；只拿一页或一次语义搜索，不能说“全部找到”。
+
 ## 保存流程
 
 ### 文字与长文
@@ -70,17 +107,18 @@ 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`；
-   - 时间点与会议过程：`timeline`；
+   - 章节时间点与会议过程：`chapters`，读取 `chapter_timeline.items`，保留规则解析来源 `source`；录音 moments 使用 `timeline`，两者不是同一份数据；
    - 用户现场快捷记录：`quick-note`；
    - 会议待办：`todos`，必须保留 `source`，不得把规则解析结果说成上游原生待办。
 5. 不拿 `content` 中的 AI 摘要冒充原文。
+6. 标记从 `getnote marks` 的 `data.marks[]` 读取，不使用 Timeline 的条数或内容替代。发芽从 `getnote sprouts` 列出报告，再用 `getnote sprout` 读取正文；`has_sprout=false` 如实表示没有可读报告，不把标记或笔记总结当作发芽。
 
 ## 修改、删除和分享
 
@@ -98,10 +136,11 @@ 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` | 仅在存在录音/会议时间线时展示。 |
+| `getnote note chapters <id> -o json` | `data.note_id/title/chapter_timeline` | `items[].start_ms` 为毫秒；空数组表示无可解析章节，不拿标记补齐。 |
 | `gnote note quick <id> -o json` | `data.note_id/title/quick_note` | 返回现场快捷笔记；旧环境回退 `getnote note quick-note`。 |
 | `getnote note todos <id> -o json` | `data.note_id/title/meeting_todos[]` | 保留每项 `source`；这是从明确会议总结章节按规则解析，不说成上游原生待办。 |
 | `getnote note update <id> … -o json` | `success=true`、`data?` | 修改正文或全量标签前必须 `--yes`；需要展示最终内容时再读一次 `note`。 |

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=[]`，回复“没有找到相关笔记；可以换关键词、时间范围或指定知识库再试”，不要说“接口失败”，也不要自动扩大检索范围、创建笔记或调用模型编造结果。
 
 ## 失败、隐私与后续动作