@getnote/cli 1.2.1 → 1.3.0

package/README.md

@@ -30,7 +30,7 @@ npm install -g @getnote/cli --ignore-scripts
 >
 > OpenAPI（包括本 CLI 和 Skill）仅对**得到大脑会员**开放。未开通会员时执行命令会提示 `OpenAPI 仅对会员开放`。
 >
-> 开通会员：在 [得到大脑 App](https://biji.com) 内订阅，或访问官网了解详情。
+> 开通会员：[前往得到大脑会员购买页](https://www.biji.com/checkout?product_alias=9Ab36BB3ZD&spm=openapi_cli)。
 
 ---
 
@@ -153,6 +153,9 @@ getnote auth logout                  退出登录
 getnote save <url|文字|图片路径>      保存链接/文字/图片笔记
   --title <标题>                      可选标题
   --tag <标签>                        标签（可重复）
+  --topic-id <topic_id>               直接存入普通/书籍/客户档案知识库
+  --parent-id <note_id>               创建子笔记（ID 推荐传字符串）
+  --idempotency-key <key>             同一创建请求重试时复用的幂等键
 
 getnote task <task_id>               查看异步任务进度
 ```
@@ -179,6 +182,9 @@ getnote note update <id>             更新笔记
 
 getnote note delete <id>             删除笔记（移入回收站）
   -y                                 跳过确认
+
+getnote note share <id>              生成公开分享链接
+  --exclude-audio                    分享时排除音频
 ```
 
 ### 字段语义说明（适合 AI Agent 参考）
@@ -214,7 +220,7 @@ getnote tag list <note_id>           查看笔记的所有标签
 ### 知识库
 
 ```
-getnote kbs                          列出所有知识库
+getnote kbs                          列出所有自有知识库（DEFAULT / BOOKSPACE / CUSTOMER）
 
 getnote kb <topic_id>                知识库内的笔记
   --limit <n>
@@ -226,7 +232,7 @@ getnote kb create <名称>             新建知识库
 
 getnote kb add <topic_id> <note_id> [note_id...]     加入知识库
 getnote kb remove <topic_id> <note_id> [note_id...]  移出知识库
-getnote kb live-follow <url>                         订阅得到直播课，直播结束后 AI 摘要自动入库
+getnote kb live-follow <topic_id> <url>              订阅得到直播课，直播结束后 AI 摘要自动入库
 
 getnote kbs-sub                                      获取我订阅的知识库列表
 ```
@@ -262,6 +268,14 @@ getnote kbs-sub                                      获取我订阅的知识库
 | `GETNOTE_CLIENT_ID` | Client ID |
 | `GETNOTE_API_URL` | 覆盖 API 地址 |
 
+`GETNOTE_API_URL` 可传站点根地址、`/open` 或完整 `/open/api/v1`，业务请求和 OAuth 会同时使用该地址；未设置时仍使用生产环境。
+
+### 新版 API 兼容约定
+
+- `note_id`、`parent_note_id`、`children_ids`、`cursor` 等雪花 ID 按字符串无损输出；历史 `id` / `next_cursor` 数字字段继续保留。
+- HTTP 200 且 `success:false` 仍按失败处理并返回非零退出码；错误保留 `code/reason/retryable/field/constraint/expected_type/request_id`。
+- `getnote save --idempotency-key` 用于防止网络重试产生重复笔记；同一请求必须复用同一个键。
+
 ---
 
 ## 从源码构建

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getnote/cli",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "CLI tool for 得到大脑（Get笔记） — manage notes and knowledge bases from the terminal",
   "keywords": [
     "getnote",
@@ -26,4 +26,4 @@
     "skills/",
     "README.md"
   ]
-}
+}

package/skills/getnote-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: getnote-auth
-version: 0.4.0
+version: 0.5.0
 description: Manage authentication for Get笔记 CLI
 ---
 
@@ -67,3 +67,4 @@ getnote auth logout
 - If not authenticated, prompt the user to run `getnote auth login`.
 - `--api-key` on any command is a temporary per-invocation override and does not save credentials.
 - Credentials saved at `~/.getnote/config.json`; env vars `GETNOTE_API_KEY` / `GETNOTE_CLIENT_ID` take higher priority.
+- `GETNOTE_API_URL` may override the business API host for an explicitly selected test environment; otherwise production remains the default.

package/skills/getnote-kb/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: getnote-kb
-version: 0.5.2
+version: 0.6.0
 description: Manage knowledge bases in Get笔记 via the getnote CLI
 ---
 
@@ -20,13 +20,15 @@ Manage knowledge bases — list, create, browse notes, add/remove notes. Also su
 getnote kbs
 ```
 
-Returns all knowledge bases. Each item includes: `topic_id`, `name`, `description`, `note_count`, `created_at`.
+Returns all owned knowledge bases, including `DEFAULT` (normal), `BOOKSPACE` (book), and `CUSTOMER` (customer profile). Each item includes `topic_id`, `name`, `scope`, `description`, and stats.
 
 ```bash
 getnote kbs
 getnote kbs -o json
 ```
 
+> When saving into a named knowledge base, select it from the complete list by `name` and `scope`, then call `getnote save ... --topic-id <topic_id>`. Do not filter the list to `DEFAULT` only.
+
 ---
 
 ### List subscribed knowledge bases
@@ -231,7 +233,7 @@ getnote quota -o json
 - `kbs -o json` returns `{"success":true,"data":{"topics":[...],"total":N}}`
 - `kbs-sub -o json` returns the same shape as `kbs -o json`.
 - `kb <topic_id> -o json` returns `{"success":true,"data":{"notes":[...],"has_more":...}}`
-- Get `topic_id` from `getnote kbs -o json` or `getnote kbs-sub -o json` → `data.topics[].topic_id` field (not `id`).
+- Get `topic_id` from `getnote kbs -o json` or `getnote kbs-sub -o json` → `data.topics[].topic_id` field (not `id`). Owned lists include DEFAULT / BOOKSPACE / CUSTOMER.
 - `kb add` / `kb remove` accept multiple note IDs — prefer batching over multiple calls.
 - **Subscribed KBs are read-only** unless the user is an admin of that KB. `kb add` / `kb remove` will return an API error on subscribed KBs owned by others. Use `getnote kbs` (owned) vs `getnote kbs-sub` (subscribed) to distinguish.
 - `kb bloggers` → get `follow_id` → `kb blogger-contents` → get `post_id_alias` → `kb blogger-content` for full text.

package/skills/getnote-note/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: getnote-note
-version: 0.4.0
+version: 0.5.0
 description: Manage notes in Get笔记 via the getnote CLI
 ---
 
@@ -17,13 +17,16 @@ Save, list, view, update, and delete notes in Get笔记.
 ### Save a note
 
 ```
-getnote save <url|text|image_path> [--title <title>] [--tag <tag>]...
+getnote save <url|text|image_path> [--title <title>] [--tag <tag>]... [--topic-id <topic_id>] [--parent-id <note_id>] [--idempotency-key <key>]
 ```
 
 | Flag | Description |
 |------|-------------|
 | `--title` | Optional title |
 | `--tag` | Tag to apply; may be repeated |
+| `--topic-id` | Save directly into an owned DEFAULT / BOOKSPACE / CUSTOMER knowledge base |
+| `--parent-id` | Create a child note; pass the snowflake ID as a decimal string |
+| `--idempotency-key` | Stable 1-128 character request key; reuse it for retries of the same create request |
 
 - URL (`http://` or `https://`) → link note:
   - **Share link** (`biji.com/note/share_note/*` or `d.biji.com/*` short link) → **sync**, returns `note_id` directly, no polling needed
@@ -61,14 +64,15 @@ Returns `status` (`pending` / `processing` / `success` / `failed`) and `note_id`
 ### List recent notes
 
 ```
-getnote notes [--cursor <cursor>] [--all]
+getnote notes [--cursor <cursor>] [--limit <n>] [--all]
 ```
 
-Returns 20 notes per page (fixed). No `--limit` flag.
+The API fetches 20 notes per page. `--limit` returns the first N and rewrites `cursor` to the last visible note, so the next page does not skip data.
 
 | Flag | Description |
 |------|-------------|
 | `--cursor` | Pagination cursor (the `cursor` value from the previous page) |
+| `--limit` | Number of notes to return from the fetched page |
 | `--all` | Fetch all notes (auto-paginate, streams output) |
 
 ```bash
@@ -171,13 +175,11 @@ Returns: `share_url` (e.g. `https://biji.com/note/share_note/rBzdMlXrzgYVM`)
 ## Agent Usage Notes
 
 - Use `-o json` when parsing responses programmatically.
-- All JSON responses follow `{"success":true,"data":{...}}` structure, **except**:
-  - `save` (text): returns `{"note_id":"..."}` directly
-  - `save` (share link): returns `{"note_id":"...","title":"...","created_at":"...","updated_at":"..."}` directly
-  - `save` (regular link/image): returns `{"data":{"tasks":[{"task_id":"..."}],...}}`
-  - `task`: returns `{"success":true,"data":{"status":"...","note_id":"..."}}`
-- `notes` list returns **20 per page** (no `--limit`); paginate with `--cursor` (the `cursor` value from the previous page).
+- JSON responses preserve the API envelope `{"success":true,"data":{...}}`.
+- Link/image saves read the async ID from `data.tasks[0].task_id`; task polling only treats `error_msg` as meaningful when `status=failed`.
+- `notes` fetches 20 from the API and may apply a smaller local `--limit`; paginate with the returned string `cursor`.
 - Note IDs are int64 — always handle as strings to avoid precision loss in JavaScript.
+- HTTP 200 with `success:false` is still an error. The CLI exits non-zero and preserves `code`, `reason`, `retryable`, `field`, `constraint`, `expected_type`, and `request_id`.
 - Exit code `0` = success; non-zero = error. Error details go to stderr.
 
 ### 字段语义提示（"原文" vs AI 总结）

package/skills/getnote-search/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: getnote-search
-version: 0.4.0
+version: 0.5.0
 description: Semantic search across notes in Get笔记 via the getnote CLI
 ---
 

package/skills/getnote-tag/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: getnote-tag
-version: 0.3.0
+version: 0.4.0
 description: Manage note tags in Get笔记 via the getnote CLI
 ---