@getnote/cli 1.3.1 → 1.5.0

package/README.md

@@ -8,8 +8,27 @@
 
 ## 安装
 
+### 让本地 AI 自动完成安装（推荐）
+
+适用于 Codex、Claude Code 和 Cursor：
+
+```bash
+npx -y @getnote/cli@latest setup
+```
+
+这条命令会安装 CLI、识别本机支持的平台、安装五个原子 Skill，并引导完成一次得到大脑授权。安装后运行：
+
+```bash
+getnote doctor -o json
+```
+
+安装完成后，`getnote` 和更短的 `gnote` 可以互换使用，例如 `gnote notes`。
+
+### 只安装命令行
+
 ```bash
 npm install -g @getnote/cli
+getnote auth login
 ```
 
 或者从 [Releases](https://github.com/iswalle/getnote-cli/releases) 下载对应平台的二进制文件，放到 `$PATH` 里。
@@ -34,23 +53,16 @@ npm install -g @getnote/cli --ignore-scripts
 
 ---
 
-## 三步开始用
-
-**第一步：安装**
-```bash
-# 已完成，如上
-```
+## 开始使用
 
-**（可选）安装 AI Agent Skill**
-
-在 Claude Code、Cursor 等 AI 编程工具里用自然语言操作笔记，需要额外安装 Skill：
+如果已经单独安装 CLI，还可以为 Codex、Claude Code、Cursor 补装内置的五个原子 Skill：
 ```bash
 npx skills add iswalle/getnote-cli -y -g
 ```
 
-> ⚠️ 需先完成第一步安装 CLI，再安装 Skill。
+使用 `getnote setup` 时不需要再执行这条命令。
 
-**第二步：登录**
+登录：
 ```bash
 getnote auth login
 ```
@@ -59,7 +71,7 @@ getnote auth login
 getnote auth login --api-key gk_live_xxx --client-id cli_xxx
 ```
 
-**第三步：开始用**
+开始用：
 ```bash
 # 存一篇文章
 getnote save https://example.com/article --tag 阅读
@@ -71,6 +83,25 @@ getnote save "周五前要回复王总的邮件" --tag 待办
 getnote notes
 ```
 
+## 检查和升级
+
+```bash
+# 查看当前版本并检查是否有新版
+getnote version --check-update
+
+# 只检查，不安装
+getnote update --check
+
+# 升级到最新 GitHub Release
+getnote update
+```
+
+如果通过 npm 安装，也可以完整更新 npm 包和可执行程序：
+
+```bash
+npm install -g @getnote/cli@latest
+```
+
 ---
 
 ## 典型使用场景
@@ -126,7 +157,9 @@ getnote search "关键词" -o json
 getnote save https://example.com -o json   # 自动轮询，返回最终笔记
 ```
 
-`skills/` 目录下有 Claude Code 专用的 Skill 文件，安装后 AI Agent 可以直接用自然语言操作笔记：
+保存、列表、详情和搜索的 JSON 结果都会返回当前环境可打开的 `note_url`。测试环境会返回测试站地址，生产环境返回 `https://www.biji.com/note/{id}`。
+
+`skills/` 目录是 CLI 内置的五个原子 Skill，也是本地 Agent 的唯一维护源。安装后 AI Agent 可以直接用自然语言操作笔记：
 
 ```bash
 npx skills add iswalle/getnote-cli -y -g
@@ -134,6 +167,8 @@ npx skills add iswalle/getnote-cli -y -g
 
 安装后在 Claude Code / Cursor 里说「帮我搜一下关于 RAG 的笔记」即可直接调用。
 
+独立的聚合 Skill 面向 WorkBuddy、QClaw 和 OpenClaw 生态，只负责意图理解，底层仍调用同一个 CLI，不再维护第二套 OpenAPI 请求实现。
+
 ---
 
 ## 完整命令参考
@@ -145,6 +180,9 @@ getnote auth login                   OAuth 登录（浏览器授权）
 getnote auth login --api-key <key> --client-id <id>  直接用 API Key 登录
 getnote auth status                  查看当前登录状态
 getnote auth logout                  退出登录
+getnote doctor                       检查安装、登录和 API 连通性
+getnote capabilities                 查看当前版本的稳定能力
+getnote setup                        为本机 AI 安装原子 Skill 并引导授权
 ```
 
 ### 保存笔记
@@ -156,6 +194,8 @@ getnote save <url|文字|图片路径>      保存链接/文字/图片笔记
   --topic-id <topic_id>               直接存入普通/书籍/客户档案知识库
   --parent-id <note_id>               创建子笔记（ID 推荐传字符串）
   --idempotency-key <key>             同一创建请求重试时复用的幂等键
+  --content-file <文件>               从 UTF-8 文件读取长文本，避免命令行转义和长度限制
+  --stdin                              从标准输入读取长文本
 
 getnote task <task_id>               查看异步任务进度
 ```
@@ -171,10 +211,17 @@ getnote notes                        最近 20 条笔记
 
 getnote note <id>                    笔记详情
   --field <字段名>                   只输出某个字段的值
-                                     （id/title/content/type/
+                                     （id/note_url/title/content/type/
                                        created_at/url/excerpt/
                                        web_content/audio_original）
 
+getnote note original <id>           按笔记类型直接输出真实原文
+getnote note transcript <id>         直接输出录音、会议或课堂转写原文
+getnote note attachments <id>        列出图片、音频和文件附件
+getnote note timeline <id>           读取录音或会议时间线
+getnote note quick-note <id>         读取录音快捷笔记
+getnote note todos <id>              读取会议总结中明确章节解析出的待办
+
 getnote note update <id>             更新笔记
   --title <标题>
   --content <内容>                   仅文字笔记可用
@@ -199,7 +246,7 @@ getnote note share <id>              生成公开分享链接
 | 知识库博主内容 | `post_media_text`（via `kb blogger-content`）| `content` |
 | 知识库直播 | `post_media_text`（via `kb live`）| `post_summary` |
 
-> **AI Agent 提示**：用户要求"读原文"时，先用 `getnote note <id> -o json` 查看 `note_type`，再按上表选择对应字段。
+> **AI Agent 提示**：用户要求“读原文”时优先使用 `getnote note original`；明确要求录音、会议或课堂转写时使用 `getnote note transcript`，避免把 AI 摘要误当成原文。
 
 ### 搜索
 
@@ -213,14 +260,14 @@ getnote search <关键词>              全局语义搜索
 
 ```
 getnote tag add <note_id> <标签>     给笔记加标签
-getnote tag remove <note_id> <标签>  删除笔记标签
+getnote tag remove <note_id> <tag_id>  按标签 ID 删除笔记标签
 getnote tag list <note_id>           查看笔记的所有标签
 ```
 
 ### 知识库
 
 ```
-getnote kbs                          列出所有自有知识库（DEFAULT / BOOKSPACE / CUSTOMER）
+getnote kbs                          列出所有可访问知识库（DEFAULT / BOOKSPACE / CUSTOMER / TEAMSPACE）
 
 getnote kb <topic_id>                知识库内的笔记
   --limit <n>
@@ -231,12 +278,28 @@ getnote kb create <名称>             新建知识库
   --desc <描述>
 
 getnote kb add <topic_id> <note_id> [note_id...]     加入知识库
+getnote kb add <topic_id> <note_id> --directory-id <id>  加入指定文件夹
 getnote kb remove <topic_id> <note_id> [note_id...]  移出知识库
+getnote kb directories <topic_id>                    浏览文件夹和资源
+getnote kb directory-create <topic_id> <名称>        创建文件夹
+getnote kb directory-update <topic_id> <id> --name <名称>  重命名或移动文件夹
+getnote kb directory-delete <topic_id> <id> --yes    删除空文件夹
+getnote kb blogger-follow <topic_id> <抖音链接>      订阅抖音博主
 getnote kb live-follow <topic_id> <url>              订阅得到直播课，直播结束后 AI 摘要自动入库
 
 getnote kbs-sub                                      获取我订阅的知识库列表
 ```
 
+常用目录命令提供短别名，旧命令继续兼容：
+
+```bash
+gnote kb dir <topic_id>
+gnote kb mkdir <topic_id> <名称>
+gnote kb mvdir <topic_id> <directory_id> --name <新名称>
+gnote kb rmdir <topic_id> <directory_id> --yes
+gnote note quick <note_id>
+```
+
 ---
 
 ## 全局参数
@@ -245,7 +308,6 @@ getnote kbs-sub                                      获取我订阅的知识库
 |------|------|
 | `--api-key <key>` | 临时覆盖 API Key |
 | `-o, --output json\|table` | 输出格式（默认 table） |
-| `--env prod\|dev` | 切换 API 环境 |
 
 ---
 
@@ -267,6 +329,7 @@ getnote kbs-sub                                      获取我订阅的知识库
 | `GETNOTE_API_KEY` | API Key |
 | `GETNOTE_CLIENT_ID` | Client ID |
 | `GETNOTE_API_URL` | 覆盖 API 地址 |
+| `GETNOTE_WEB_URL` | 覆盖笔记网页地址；通常无需设置，CLI 会随 API 环境自动选择 |
 
 `GETNOTE_API_URL` 可传站点根地址、`/open` 或完整 `/open/api/v1`，业务请求和 OAuth 会同时使用该地址；未设置时仍使用生产环境。
 
@@ -280,7 +343,7 @@ getnote kbs-sub                                      获取我订阅的知识库
 
 ## 从源码构建
 
-需要 Go 1.21+。
+需要 Go 1.24.2+。
 
 ```bash
 git clone https://github.com/iswalle/getnote-cli.git
@@ -316,6 +379,7 @@ $ getnote search "工作日志" --limit 7 -o json
 
 | 日期 | 版本 | 新能力 | 适合怎么用 |
 |------|------|--------|------------|
+| 2026-08-11 | **v1.4.0** | 1. Skill 2.0 稳定执行契约<br>2. 所有子命令完整 `-h` / `--help`<br>3. `getnote update --check` 与升级引导<br>4. `--content-file` / `--stdin` 安全保存长文本 | 让独立 Skill 和 CLI 内置原子 Skills 共用同一套真实命令，降低 AI 猜参数和长内容转义失败的概率 |
 | 2026-04-23 | **v1.1.1** | 1. 笔记内链<br>2. 保存分享链接自动变笔记 | 1. 用内链串联每天的工作日志和项目笔记，实践时间日志法<br>2. 收到别人发来的分享链接直接存入笔记 |
 | 2026-04-16 | **v1.1.0** | 1. `getnote note share`：生成分享链接<br>2. `getnote kb live-follow`：订阅得到直播 | 1. 把笔记一键分享给朋友<br>2. 在知识库里订阅得到直播课，直播结束后 AI 摘要自动入库 |
 | 2026-04-03 | **v1.0.x** | 1. `getnote kb bloggers/lives`：查看博主和直播列表<br>2. `getnote update`：自动升级 | 1. 查看订阅博主的内容更新和直播摘要<br>2. 直接运行 `getnote update` 升级到最新版 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getnote/cli",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "CLI tool for 得到大脑（Get笔记） — manage notes and knowledge bases from the terminal",
   "keywords": [
     "getnote",
@@ -15,7 +15,8 @@
   },
   "license": "MIT",
   "bin": {
-    "getnote": "./bin/getnote.js"
+    "getnote": "./bin/getnote.js",
+    "gnote": "./bin/getnote.js"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.js"

package/scripts/postinstall.js

@@ -75,7 +75,8 @@ async function main() {
     fs.chmodSync(binaryPath, 0o755);
     console.log(`getnote installed at ${binaryPath}`);
 
-    // Create symlink in npm global bin directory so `getnote` is on PATH
+    // `getnote` is linked directly to the downloaded binary. The compact
+    // `gnote` alias is provided by package.json and uses bin/getnote.js.
     createSymlink(binaryPath, binaryName);
   } catch (err) {
     console.error('Failed to install getnote:', err.message);

package/skills/getnote-auth/SKILL.md

@@ -1,70 +1,71 @@
 ---
 name: getnote-auth
-version: 0.5.0
-description: Manage authentication for Get笔记 CLI
+description: 安装和连接得到大脑，完成浏览器授权、环境诊断、配额检查、CLI 升级与领域 Skill 同步。用户说“安装/连接/登录/更新得到大脑”“检查为什么不能用”“查看额度”时使用。
 ---
 
-# getnote-auth Skill
+# 得到大脑连接、诊断与升级
 
-Log in, log out, and check authentication status.
+负责把“用户想用得到大脑”推进到真正可执行的状态。不要只说“已安装”：CLI 可执行、账号已授权、API 可读三项都通过才算连接成功。
 
-## Commands
+## 首次安装闭环
 
-### Log in
+按顺序执行，已经满足的步骤直接跳过：
 
-```
-getnote auth login [--api-key <key>]
-```
+1. 若当前来自独立 GetNote Skill 包，先运行 `bash scripts/install.sh --ensure`。它负责检查 Node.js 20+ 并确保官方 CLI 存在；不要因为 Skill 已安装就假设 CLI 存在。
+2. 若当前环境只有 CLI 内置 Skill、没有上述安装器，则用 `command -v getnote` 检查 CLI；缺失时检查 `node --version` 和 `npm --version`，再自动执行 `npm install -g @getnote/cli@latest`。这是 Agent 的工作，不要求用户手工复制命令；只有系统弹出安装授权时才请用户确认。
+3. 执行 `getnote version`，必须能够正常启动。
+4. 执行 `getnote auth status`。未登录时运行 `getnote auth login`，让用户只在浏览器中确认，不索要 API Key、Cookie 或 Authorization。
+5. 执行 `getnote doctor -o json`。只有 `success=true`，且 `checks` 中 `cli`、`auth`、`api` 均为 `ok=true`，才能宣布连接完成。
+6. 在 Codex、Claude Code 或 Cursor 等本地 Agent 中，执行 `getnote setup` 同步 5 个领域 Skill；如果当前平台已经由独立 Skill 包携带这些领域 Skill，或 CLI 明确提示未检测到受支持平台，不把这一步失败误报成账号连接失败。
+7. 先用 `getnote notes --limit 1 -o json` 做无写入验收。只有用户同意创建测试内容时，才保存测试笔记。
 
-| Mode | Command | Description |
-|------|---------|-------------|
-| OAuth (recommended) | `getnote auth login` | Opens browser to authorize; saves credentials automatically |
-| API Key | `getnote auth login --api-key <key>` | Saves key directly, no browser needed |
+## 日常路由
 
-```bash
-# OAuth flow (opens browser)
-getnote auth login
+| 意图 | 命令 |
+|---|---|
+| 登录 | `getnote auth login` |
+| 查看登录状态 | `getnote auth status` |
+| 退出登录 | `getnote auth logout` |
+| 诊断连接 | `getnote doctor -o json` |
+| 查看 CLI 能力契约 | `getnote capabilities -o json` |
+| 为本机 AI 同步领域 Skill | `getnote setup` |
+| 查看 AI 对话额度 | `getnote quota -o json` |
+| 查看版本 | `getnote version` |
+| 检查升级 | `getnote update --check` |
+| 执行升级 | `getnote update` |
 
-# API key directly
-getnote auth login --api-key gk_live_xxx
-```
+参数不确定时读取对应命令的 `--help`，不要凭旧文档猜参数。
 
-Get your API key at: https://www.biji.com/settings/developer (keys start with `gk_live_`)
+## 每条命令的结果与下一步
 
----
-
-### Check status
-
-```
-getnote auth status
-```
+| 命令 | 成功后读取/确认 | 成功后怎么做 |
+|---|---|---|
+| `getnote auth login` | 浏览器已确认，凭证已写入本机 | 再运行 `doctor -o json`；不在聊天中展示凭证。 |
+| `getnote auth status` | `Authenticated` / `Not authenticated` 或环境变量登录状态 | 未登录才启动 `auth login`；状态里只能出现掩码。 |
+| `getnote auth logout` | `Logged out successfully.` | 只说明本机已退出；不声称已撤销服务端授权。 |
+| `getnote doctor -o json` | `success`、`cli_version`、`checks[].name/ok/message`、`platforms[]` | 只有 `cli`、`auth`、`api` 均为 `ok=true` 才宣布可用。 |
+| `getnote capabilities -o json` | `contract_version`、`commands`、`command_aliases`、`command_results`、`guarantees` | 只在安装、升级或兼容排查时读取；这是命令和结果字段的唯一事实源。 |
+| `getnote setup -o json` | `success`、`targets[]`、`installed_skills`、`authenticated`、`next` | 仅同步本机 Agent 的领域 Skill；没有可识别目标不等于账号失败。 |
+| `getnote quota -o json` | `data.read/write/write_note` 下的 `daily/monthly.limit/used/remaining/reset_at` | 按真实桶说明剩余额度，不自行换算或合并桶。 |
+| `getnote version` | 版本文本 | 只用于展示版本；机器契约仍以 `capabilities -o json` 为准。 |
+| `getnote update --check` | 当前/可用新版本文本 | 有新版本再运行 `getnote update`。 |
+| `getnote update` | 更新完成文本 | 必须再运行 `version` 和 `doctor -o json`，通过后才能说升级完成。 |
 
-Shows whether authenticated and which API key is active.
+所有命令以退出码为第一判断：退出码非 0 即失败。使用 `-o json` 的 API 与本地错误均返回 `success=false`、`data=null`、`error.code/message/reason/retryable` 和可选 `request_id`；不能把 HTTP 200 或“命令运行过”当成成功。
 
-```bash
-getnote auth status
-```
-
----
+## 更新闭环
 
-### Log out
+用户说“帮我更新得到大脑”已经构成更新授权：
 
-```
-getnote auth logout
-```
-
-Removes saved credentials from `~/.getnote/config.json`.
-
-```bash
-getnote auth logout
-```
-
----
+1. 若当前来自独立 GetNote Skill 包，执行 `bash scripts/install.sh --update`。它升级 CLI，并在有新版发布包时刷新主 Skill 和五个领域 Skill。
+2. 若当前环境只有 CLI 内置 Skill，执行 `getnote update --check`；有新版本时执行 `getnote update`，若 CLI 明确提示 npm 安装方式，则用 `npm install -g @getnote/cli@latest`。
+3. 执行 `getnote version` 和 `getnote doctor -o json`。
+4. 执行 `getnote setup` 同步内置领域 Skill；技能市场托管的独立 Skill 需要平台更新时，只让用户完成唯一必要的点击。
+5. 用最近笔记读取做验收，再告诉用户版本、诊断结果和仍需动作。
 
-## Agent Usage Notes
+## 安全与恢复
 
-- Always run `getnote auth status` first to verify authentication before other commands.
-- 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.
+- 不展示或记录完整凭证；`auth status` 只能出现掩码。
+- 用户未明确要求时不退出登录。
+- 授权超时、拒绝或验证码过期时重新启动一次登录流程，不复用旧 code。
+- 失败时保留执行步骤、错误原因和 `request_id`；不要只回复“连接失败”。

package/skills/getnote-kb/SKILL.md

@@ -1,243 +1,87 @@
 ---
 name: getnote-kb
-version: 0.6.0
-description: Manage knowledge bases in Get笔记 via the getnote CLI
+description: 查看和管理得到大脑的默认知识库、书籍、客户档案、团队知识库、文件夹、抖音博主订阅与直播，并把笔记准确归档到指定知识库和目录。
 ---
 
-# getnote-kb Skill
-
-Manage knowledge bases — list, create, browse notes, add/remove notes. Also supports subscribed knowledge bases, blogger content, live sessions, and quota.
-
-## Prerequisites
-
-- `getnote` CLI installed and authenticated (`getnote auth status` should show "Authenticated")
-
-## Commands
-
-### List all knowledge bases
-
-```
-getnote kbs
-```
-
-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
-
-```
-getnote kbs-sub [--page <n>]
-```
-
-Returns knowledge bases the user has subscribed to. Supports pagination.
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--page` | 1 | Page number |
-
-```bash
-getnote kbs-sub
-getnote kbs-sub --page 2
-getnote kbs-sub -o json
-```
-
-> Use `getnote kb <topic_id>` to browse notes inside a subscribed knowledge base.
-
----
-
-### List notes in a knowledge base
-
-```
-getnote kb <topic_id> [--limit <n>] [--all]
-```
-
-Returns 20 notes per page by default.
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--limit` | 20 | Notes per page |
-| `--all` | — | Fetch all notes (auto-paginate) |
-
-```bash
-getnote kb vnrOAaGY
-getnote kb vnrOAaGY --all
-getnote kb vnrOAaGY -o json
-```
-
----
-
-### Create a knowledge base
-
-```
-getnote kb create <name> [--desc <description>]
-```
-
-```bash
-getnote kb create "Research Papers"
-getnote kb create "Project Docs" --desc "Documentation links"
-```
-
-> Max 50 knowledge bases per day (resets at 00:00 Beijing time).
-
----
-
-### Add notes to a knowledge base
-
-```
-getnote kb add <topic_id> <note_id> [note_id...]
-```
-
-Supports multiple note IDs. Max 20 per call.
-
-```bash
-getnote kb add vnrOAaGY 1234567890
-getnote kb add vnrOAaGY 1234567890 9876543210
-```
-
-> Already-existing notes are silently skipped.
-
----
-
-### Remove notes from a knowledge base
-
-```
-getnote kb remove <topic_id> <note_id> [note_id...]
-```
-
-```bash
-getnote kb remove vnrOAaGY 1234567890
-```
-
-> ⚠️ **订阅知识库限制**：如果目标知识库是他人创建（通过 `getnote kbs-sub` 获取），且用户不是该知识库的管理员，则无法添加或移除笔记，API 会返回错误。只有自己创建的知识库（`getnote kbs`）才支持完整的增删操作。
-
----
-
-### List bloggers in a knowledge base
-
-```
-getnote kb bloggers <topic_id> [--page <n>]
-```
-
-Returns subscribed bloggers. Each item includes: `follow_id` (required for content queries), `account_name`, `platform`, `follow_time`.
-
-```bash
-getnote kb bloggers vnrOAaGY
-getnote kb bloggers vnrOAaGY --page 2 -o json
-```
-
----
-
-### List blogger contents
-
-```
-getnote kb blogger-contents <topic_id> <follow_id> [--page <n>]
-```
-
-Returns content list (no full text). Use `post_id_alias` to fetch detail.
-
-```bash
-getnote kb blogger-contents vnrOAaGY follow123
-getnote kb blogger-contents vnrOAaGY follow123 --page 2
-```
-
----
-
-### Show blogger content detail
-
-```
-getnote kb blogger-content <topic_id> <post_id>
-```
-
-Returns full content including original text (`post_media_text`).
-
-```bash
-getnote kb blogger-content vnrOAaGY post_abc123
-getnote kb blogger-content vnrOAaGY post_abc123 -o json
-```
-
----
-
-### List completed lives in a knowledge base
-
-```
-getnote kb lives <topic_id> [--page <n>]
-```
-
-Returns only completed live sessions that have been AI-processed.
-
-```bash
-getnote kb lives vnrOAaGY
-getnote kb lives vnrOAaGY --page 2
-```
-
----
-
-### Show live detail
-
-```
-getnote kb live <topic_id> <live_id>
-```
-
-Returns AI summary (`post_summary`) and full transcript (`post_media_text`).
-
-```bash
-getnote kb live vnrOAaGY live_abc123
-getnote kb live vnrOAaGY live_abc123 -o json
-```
-
----
-
-### Follow a live channel in a knowledge base
-
-```
-getnote kb live-follow <topic_id> <link> [--platform <platform>]
-```
-
-Subscribes a Dedao live channel to a knowledge base. Once the live session ends and is AI-processed, it will appear in `kb lives`.
-
-> ⚠️ Currently only Dedao App live links are supported.
-
-```bash
-getnote kb live-follow vnrOAaGY https://m.dedao.cn/live/xxxxx
-getnote kb live-follow vnrOAaGY https://m.dedao.cn/live/xxxxx -o json
-```
-
-Returns: `follow_id`, `url`, `platform`, `type`, `created_at`.
-
----
-
-### Show API quota usage
-
-```
-getnote quota
-```
-
-```bash
-getnote quota
-getnote quota -o json
-```
-
----
-
-## Agent Usage Notes
-
-- Use `-o json` when parsing results programmatically.
-- `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`). 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.
-- `kb lives` → get `live_id` → `kb live` for AI summary + transcript.
-- `kb live-follow <topic_id> <link>` to subscribe a live channel; newly finished lives will appear in `kb lives`.
-- `quota -o json` returns `{"success":true,"data":{"read":{"daily":{limit,used,remaining,reset_at},"monthly":{...}},"write":{...},"write_note":{...}}}`
-- Exit code `0` = success; non-zero = error. Error details go to stderr.
+# 得到大脑知识库
+
+通过官方 CLI 读取真实知识库、权限和目录后再操作；不能用名称猜 ID。机器调用统一使用 `-o json`；只有退出码为 0 且 `success=true` 才是业务成功。返回中的所有知识库、目录、博主和笔记 ID 都按字符串原样传递。
+
+所有 API 命令的 JSON 都先判断 `success`。`success=false` 或退出码非 0 时读取 `error.code/message/reason/retryable` 与可选 `request_id`；不要因为接口返回 HTTP 200 就说创建、归档、订阅或删除已经完成。
+
+## 意图路由
+
+| 意图 | 命令入口 |
+|---|---|
+| 自有/可管理知识库 | `getnote kbs` |
+| 订阅知识库 | `getnote kbs-sub` |
+| 知识库笔记 | `getnote kb <topic_id>` |
+| 新建个人知识库 | `getnote kb create` |
+| 加入笔记 | `getnote kb add` |
+| 移出笔记 | `getnote kb remove` |
+| 浏览文件夹 | `gnote kb dir` |
+| 创建文件夹 | `gnote kb mkdir` |
+| 重命名/移动文件夹 | `gnote kb mvdir` |
+| 删除空文件夹 | `gnote kb rmdir` |
+| 博主列表 | `getnote kb bloggers` |
+| 博主内容列表 | `getnote kb blogger-contents` |
+| 博主内容详情 | `getnote kb blogger-content` |
+| 订阅抖音博主 | `getnote kb blogger-follow` |
+| 直播列表 | `getnote kb lives` |
+| 直播详情 | `getnote kb live` |
+| 订阅直播 | `getnote kb live-follow` |
+
+`gnote` 和短命令是稳定别名；旧环境没有别名时回退到 `getnote kb directories/directory-create/directory-update/directory-delete`。参数一律以目标命令 `--help` 为准。
+
+## 选择知识库和权限
+
+1. 先执行 `getnote kbs -o json`，保留全部真实 Scope：`DEFAULT`、`BOOKSPACE`、`CUSTOMER`、`TEAMSPACE`，不能只返回默认知识库。
+2. 按名称和 `scope` 匹配；同名或用户意图不明确时让用户选择，不猜 `topic_id`。
+3. 订阅知识库通常只读。团队知识库（`TEAMSPACE`）成员可以读取；只有接口返回具备维护权限的拥有者或管理员才能创建目录、加入笔记或订阅内容。
+4. 普通成员写入失败时明确说明权限不足，不尝试绕过。当前不代替用户新建团队知识库。
+
+## 文件夹和归档流程
+
+1. 用户要求放入文件夹时，用 `gnote kb dir <topic_id> -o json` 读取根目录或指定目录。
+2. 已有文件夹使用返回的真实 `directory_id`；缺失时先询问是否创建，再用 `mkdir`。
+3. `getnote kb add` 同时传真实 `topic_id`、字符串 `note_id` 和 CLI 帮助中规定的目录参数。
+4. 每批最多 20 条。移出笔记和删除目录必须先确认；删除目录还必须由 CLI/服务校验为空。
+5. 移动或重命名时只改变用户指定项，未指定的名称或父目录保持不变。
+
+## 博主和直播
+
+1. 用户给出抖音主页并要求持续关注时，先确认目标知识库和写权限，再使用 `blogger-follow`；只是找某条内容时先查询，不创建订阅。
+2. 列表先返回博主/直播名称、真实字符串 ID 和必要状态，选中后再读取完整内容。
+3. 博主内容详情中的 `post_media_text` 才是完整原文，不用摘要冒充。
+
+## 每条命令的结果与回复格式
+
+| 命令 | 成功结果必须包含 | 回复规则 |
+|---|---|---|
+| `getnote kbs -o json` | `success=true`、`data.topics[].topic_id/name/scope/stats`、`has_more/total` | 展示全部真实 Scope，不只展示默认知识库。 |
+| `getnote kbs-sub -o json` | `success=true`、`data.topics[].topic_id/name`、`has_more/total` | 订阅知识库通常只读，不能把它当作可写知识库。 |
+| `getnote kb <topic_id> -o json` | `success=true`、`data.notes[].note_id/title/note_type`、`has_more/total` | 返回知识库内真实笔记；需要链接时再用 `note` 读取详情。 |
+| `getnote kb create <name> -o json` | `success=true`、`data?` | 仅创建个人知识库；不得在没有返回 ID 时虚构 `topic_id`。 |
+| `getnote kb add <topic_id> <note_id…> -o json` | `success=true`、`data?` | 最多 20 条；需要确认最终目录归属时重新读取目录。 |
+| `getnote kb remove <topic_id> <note_id…> --yes -o json` | `success=true`、`data?` | 最多 20 条；先确认，再说明已从该知识库移出。 |
+| `gnote kb dir <topic_id> -o json` | `success=true`、`data.current_directory?`、`directories[].id/name`、`resources[]`、`total` | 只使用返回的 `directory_id`；旧环境回退 `getnote kb directories`。 |
+| `gnote kb mkdir <topic_id> --name <name> -o json` | `success=true`、`data?` | 也兼容位置参数 `<name>`；二者不可同时使用。若需给出新目录 ID 或层级，随后重新读取目录。 |
+| `gnote kb mvdir <topic_id> <directory_id> … -o json` | `success=true`、`data?` | 只确认用户指定的改名/移动；需要最终名称或父级时重新读取目录。 |
+| `gnote kb rmdir <topic_id> <directory_id> --yes -o json` | `success=true`、`data?` | 只删除空目录；说明已删除前必须拿到业务成功。 |
+| `getnote kb bloggers <topic_id> -o json` | `success=true`、`data.bloggers[].follow_id_str/account_name/platform`、`has_more/total` | 列表中使用 `follow_id_str` 作为后续查询 ID。 |
+| `getnote kb blogger-follow <topic_id> <link> -o json` | `success=true`、`data.follow_id_str/url/platform/type/created_at` | 说明实际订阅的平台和对象；先确认目标知识库有写权限。 |
+| `getnote kb blogger-contents <topic_id> <follow_id> -o json` | `success=true`、`data.contents[].post_id_alias/post_title/post_publish_time`、`has_more/total` | 返回标题与摘要；阅读全文前让用户选择具体内容。 |
+| `getnote kb blogger-content <topic_id> <post_id> -o json` | `success=true`、`data.post_title/post_summary?/post_media_text?/post_url?/post_publish_time` | `post_media_text` 才是完整原文，摘要不能替代它。 |
+| `getnote kb lives <topic_id> -o json` | `success=true`、`data.lives[].live_id/name/status`、`has_more/total` | 先列出真实直播，再按用户选择读取详情。 |
+| `getnote kb live <topic_id> <live_id> -o json` | `success=true`、`data.post_title/post_summary?/post_media_text?/post_publish_time` | `post_media_text` 是直播原文/转写；没有时不凭摘要补写。 |
+| `getnote kb live-follow <topic_id> <link> -o json` | `success=true`、`data.follow_id_str/url/platform/type/created_at` | 说明真实订阅对象和平台。 |
+
+权限不足、目录非空、批量超限等失败必须原样解释，不伪造降级成功；保留 `request_id` 和 `retryable`。
+
+## 完成、处理中与失败后的动作
+
+- `kbs`、`kbs-sub`、`kb`、`dir`、博主和直播的空列表都是成功结果：如实说“目前没有”，不要自动创建知识库、目录或订阅。
+- `kb create`、`kb add`、`mkdir`、`mvdir` 等写操作的 `data` 可能因服务版本不同而不提供完整对象。只在 `success=true` 时确认动作已提交；若要向用户返回新目录 ID、最终层级或笔记归属，必须紧接着重新读取 `gnote kb dir` 或 `getnote kb <topic_id>`，不能猜字段。
+- `kb add` 即使请求成功，也不能把“已发起加入”说成“已进入某个目录”；只有重新读取后出现对应 `note_id` / `directory_id` 才能展示最终归属。
+- `kb remove`、`rmdir` 前必须有用户明确确认并带 `--yes`；若 `reason=knowledge_directory_not_empty`，明确提示“目录非空，请先移出内容或删除子目录”，不要原请求重试。其它失败也应说明真实原因和下一步，绝不宣称已删除。
+- 用户给的团队知识库不在 `getnote kbs` 返回中时，先说明当前账号没有访问权限；不能把个人知识库同名项替代成团队知识库。

package/skills/getnote-note/SKILL.md

@@ -1,195 +1,112 @@
 ---
 name: getnote-note
-version: 0.5.0
-description: Manage notes in Get笔记 via the getnote CLI
+description: 使用得到大脑保存文字、链接、图片和长笔记，查看笔记详情、原文、录音转写、附件、时间线、快捷笔记和会议待办，并安全更新、删除或分享笔记。
 ---
 
-# getnote-note Skill
+# 得到大脑笔记
 
-Save, list, view, update, and delete notes in Get笔记.
+通过官方 `getnote` CLI 完成真实操作。不要自己拼 OpenAPI 请求、ID 或笔记链接；机器调用优先使用 `-o json`，以退出码和下述结果契约判断结果。
 
-## Prerequisites
+## 统一结果判定
 
-- `getnote` CLI installed and authenticated (`getnote auth status` should show "Authenticated")
+所有 API 命令的 JSON 结果先看下面这层结构，再读取每条命令规定的 `data` 字段：
 
-## Commands
-
-### Save a note
-
-```
-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
-  - **Internal note link** (`biji.com/note/{note_id}`) → this is the format for linking to another note inside note content; use it in `content` field when referencing other notes. If the current note will be shared publicly, prefer using the referenced note's share link (`getnote note share <id>`) instead of the internal link format
-  - **Other URLs** → async, auto-polls until done
-- Local image path → image note (async, auto-polls until done)
-- Otherwise → text note (sync)
-
-```bash
-getnote save https://example.com --title "Great article"
-getnote save "Remember to review the docs" --tag work --tag important
-getnote save ./screenshot.png --title "Design mockup"
-```
-
-In `-o json` mode, silently polls and returns the final note JSON (including `title`, `content`/summary, `note_type`, `tags`, `created_at`).
-
----
-
-### Track save task
-
-```
-getnote task <task_id>
-```
-
-Manually check progress of an async save task.
-
-```bash
-getnote task task_xyz789 -o json
-```
-
-Returns `status` (`pending` / `processing` / `success` / `failed`) and `note_id` when done.
-
----
-
-### List recent notes
-
-```
-getnote notes [--cursor <cursor>] [--limit <n>] [--all]
-```
-
-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
-getnote notes
-getnote notes --all
-getnote notes --cursor 1914025811879486080
-getnote notes -o json
+```json
+{
+  "success": true,
+  "data": {},
+  "request_id": "可选"
+}
 ```
 
-**Note types**: `plain_text` / `img_text` / `link` / `audio` / `meeting` / `local_audio` / `internal_record` / `class_audio` / `recorder_audio` / `recorder_flash_audio`
+失败结果为 `success=false` 或命令退出码非 0，读取 `error.code`、`error.message`、`error.reason`、`error.retryable` 和可选 `request_id`。HTTP 成功、上传完成、出现任务 ID 或拿到空笔记链接，都不能替代最终成功结果。
 
----
-
-### Get note details
-
-```
-getnote note <id> [--field <field>]
-```
-
-Returns full note including content, tags, attachments. Use `--field` to extract a single value.
-
-| `--field` values | Description |
-|------|-------------|
-| `id` | Note ID |
-| `title` | Title |
-| `content` | Content / AI summary |
-| `type` | Note type |
-| `created_at` | Creation time |
-| `updated_at` | Last updated time |
-| `url` | Source URL (link notes) |
-| `excerpt` | Excerpt |
-| `web_content` | Full web page content (link notes only) |
-| `audio_original` | 录音笔记的转写原文（`audio` 类型笔记专用，非 AI 总结） |
-| `source` | Note source (e.g. `openapi`, `manual`) |
-| `tags` | Comma-separated tag names |
-
-```bash
-getnote note 1234567890
-getnote note 1234567890 --field content
-getnote note 1234567890 --field url
-getnote note 1234567890 -o json
-```
-
----
-
-### Update a note
-
-```
-getnote note update <id> [--title <title>] [--content <content>] [--tag <tags>]
-```
+## 意图路由
 
-| Flag | Description |
-|------|-------------|
-| `--title` | New title |
-| `--content` | New content (plain_text notes only) |
-| `--tag` | Comma-separated tags — **replaces all existing tags** |
+| 意图 | 命令入口 |
+|---|---|
+| 保存文字、链接或本地图片 | `getnote save` |
+| 查询异步保存任务 | `getnote task` |
+| 查看最近笔记 | `getnote notes` |
+| 查看详情或字段 | `getnote note` |
+| 链接/文字原文 | `getnote note original` |
+| 录音、会议或课堂转写 | `getnote note transcript` |
+| 图片、音频和文件附件 | `getnote note attachments` |
+| 录音或会议时间线 | `getnote note timeline` |
+| 录音快捷笔记 | `gnote note quick`，旧版回退 `getnote note quick-note` |
+| 会议总结中的派生待办 | `getnote note todos` |
+| 修改笔记 | `getnote note update` |
+| 删除笔记 | `getnote note delete` |
+| 公开分享 | `getnote note share` |
 
-```bash
-getnote note update 1234567890 --title "Updated title"
-getnote note update 1234567890 --tag "work,important"
-```
+不确定参数时先运行目标命令 `--help`。
 
-> ⚠️ `--tag` replaces all tags. For partial tag changes use `getnote tag add/remove`.
-> ⚠️ Content update only works on `plain_text` notes.
+## 保存流程
 
----
+### 文字与长文
 
-### Delete a note
+1. 保留用户原意，不擅自扩写；未指定时不添加知识库、父笔记、标签或公开分享。
+2. 短文本可作为参数传入。长文本、Markdown、含复杂引号或换行的内容必须使用 `--content-file` 或 `--stdin`，避免截断和转义损坏。
+3. 重试同一次创建时复用同一个 `--idempotency-key`。
+4. 只有命令退出码为 0，且最终结构中存在非空字符串 `data.note.note_id`、`data.note.title`、`data.note.note_url`，才回复保存成功。
 
-```
-getnote note delete <id> [-y]
-```
+### 链接
 
-Moves note to trash.
+1. 以 `http://` 或 `https://` 开头且用户表达保存意图时按链接保存，不当作普通文字。
+2. CLI 会轮询异步任务。处理中可以告诉用户“正在抓取并生成笔记”，但不能提前给出成功结论。
+3. 最终成功必须满足文字保存的三项字段，并且 `data.note` 已能读取；不要自行拼接链接。
 
-```bash
-getnote note delete 1234567890 -y
-```
+### 图片
 
----
+1. 使用本轮用户明确给出的本地图片路径，不把文件名保存成文字，也不带上历史图片。
+2. CLI 会校验真实文件格式、上传图片并轮询识别任务。
+3. 只有最终笔记详情返回有效 `note_id/title/note_url` 才算成功；“图片已上传”不是“笔记已生成”。
 
-### Share a note
+### 异步超时与安全重试
 
-```
-getnote note share <id> [--exclude-audio]
-```
-
-Generates a public share link for a note. Idempotent — calling multiple times returns the same URL.
-
-```bash
-getnote note share 1234567890
-getnote note share 1234567890 --exclude-audio
-getnote note share 1234567890 -o json
-```
-
-Returns: `share_url` (e.g. `https://biji.com/note/share_note/rBzdMlXrzgYVM`)
+- `getnote save ... -o json` 正常会等待最终结果；若退出码非 0 且输出含 `task_id`、`status=pending|processing`，操作结果仍不确定。
+- 结果不确定时使用 `getnote task <task_id> -o json` 查询原任务。`done|success` 且有有效 `note_id` 后再读取笔记；`failed` 时展示 `error_msg` 或 `msg`。
+- 超时、断流或网络错误后禁止直接再次保存；先查询原任务或最近笔记。只有 CLI/API 明确 `retryable=true` 且已确认原操作没有成功时才重试。
 
----
+## 查询和深层读取
 
-## Agent Usage Notes
+1. “最近、列表、有哪些”使用 `getnote notes`；“找、搜、关于某主题”交给搜索 Skill。
+2. 用户给出 ID 或私有笔记链接时读取详情；雪花 ID 全程按字符串原样传递。
+3. 列表先展示标题、字符串 ID 和真实 `note_url`，用户选择后再读取全文。
+4. 不确定笔记类型时先读 `getnote note <id> -o json`：
+   - 链接/文字原文：`original`；
+   - 录音、会议、课堂逐字稿：`transcript`；
+   - 图片、音频、文件：`attachments`；
+   - 时间点与会议过程：`timeline`；
+   - 用户现场快捷记录：`quick-note`；
+   - 会议待办：`todos`，必须保留 `source`，不得把规则解析结果说成上游原生待办。
+5. 不拿 `content` 中的 AI 摘要冒充原文。
 
-- Use `-o json` when parsing responses programmatically.
-- 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 总结）
+1. 先读取目标笔记和当前版本，确认用户指向的对象。
+2. 追加或前置内容必须使用 CLI 当前帮助中对应的增量语义，不用覆盖模拟追加。
+3. 覆盖正文、替换全部标签、删除和公开分享必须先确认；确认后才使用 `--yes`。
+4. 用户未要求公开时只返回私有 `note_url`，不自动生成分享链接。
 
-不同笔记类型的"原文"字段不同，`content` 通常是 AI 总结而非原文。用户要求"读原文"时，先用 `getnote note <id> -o json` 查看 `note_type`，再按下表选择对应字段：
+## 每条命令的结果与回复格式
 
-| 笔记类型 | 原文字段 | AI 总结字段 |
-|---------|---------|------------|
-| 普通文字笔记 | `content` | `content` |
-| 链接/网页笔记 | `web_content` | `content` |
-| 录音笔记 | `audio_original` | `content` |
-| 知识库博主内容 | `post_media_text`（via `kb blogger-content`）| `content` |
-| 知识库直播 | `post_media_text`（via `kb live`）| `post_summary` |
+| 命令 | 成功结果必须包含 | 回复规则 |
+|---|---|---|
+| `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 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 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` | 仅在存在录音/会议时间线时展示。 |
+| `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`。 |
+| `getnote note delete <id> --yes -o json` | `success=true`、`data?` | 只能说“已移入回收站”，不是永久删除。 |
+| `getnote note share <id> --yes -o json` | `success=true`、`data.note_id/share_id/share_url` | 只返回真实 `share_url`，并明确其为公开链接。 |
+
+API 失败时回复失败步骤、`error.message/reason`、是否可重试和 `request_id`；不能把 HTTP 200 当业务成功。
+
+群聊或共享会话中只先展示必要标题和链接，不主动展开私密全文。

package/skills/getnote-search/SKILL.md

@@ -1,53 +1,62 @@
 ---
 name: getnote-search
-version: 0.5.0
-description: Semantic search across notes in Get笔记 via the getnote CLI
+description: 在得到大脑的全部笔记或指定知识库中按自然语言进行语义搜索，返回真实标题、摘要、字符串 ID 和可打开的笔记链接。
 ---
 
-# getnote-search Skill
+# 得到大脑搜索
 
-Semantic search across all notes or within a specific knowledge base.
+通过官方 `getnote` CLI 搜索真实笔记。不要自己拼 OpenAPI 请求、笔记 ID 或访问链接。机器调用使用 `-o json`；只有退出码为 0 且 JSON 的 `success=true` 才是业务成功。
 
-## Prerequisites
+## 何时使用
 
-- `getnote` CLI installed and authenticated (`getnote auth status` should show "Authenticated")
+- “找找、搜一下、关于某主题、我之前记过什么”：使用 `getnote search`。
+- “最近有哪些笔记、按保存时间列出来”：交给笔记 Skill 的 `getnote notes`，不要把列表误当语义搜索。
+- 用户选中某一条后，再交给笔记 Skill 用 `getnote note <note_id>` 读取详情；搜索阶段不自动修改、移动、分享或创建笔记。
 
-## Commands
+## 执行步骤
 
-### Search notes
+1. 用户没有指定知识库时，直接执行 `getnote search <query> --limit <1-10> -o json`。默认上限是 10，不能自行放大。
+2. 用户指定知识库名称时，先执行 `getnote kbs -o json`，用返回的真实 `topic_id` 和 `scope` 匹配；同名、多个团队知识库或意图不明确时必须让用户选择。
+3. 已确认知识库后执行 `getnote search <query> --kb <topic_id> --limit <1-10> -o json`。
+4. 只从返回值读取标题、摘要、字符串 `note_id` 和真实 `note_url`。没有 `note_id/note_url` 的非笔记结果可以展示内容，但不能伪造“打开笔记”链接。
 
-```
-getnote search <query> [--kb <topic_id>] [--limit <n>]
-```
-
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--kb` | — | Limit search to a knowledge base (`topic_id`) |
-| `--limit` | 10 | Max results (max 10) |
-
-Results are ranked by semantic relevance (high → low). Each result includes: `note_id`, `title`, `content` (excerpt), `score`, `created_at`, `note_type`.
+## 命令结果与用户呈现
 
-> Note: `note_type` is one of `NOTE`, `FILE`, `BLOGGER`, `LIVE`, `URL`, `DEDAO`. `note_id` is only populated for `NOTE` type results; other types return an empty `note_id`.
+### 搜索
 
 ```bash
-# Search across all notes
-getnote search "大模型 API"
-
-# Search within a knowledge base
-getnote search "RAG" --kb qnNX75j0
+getnote search "支付流程" --limit 10 -o json
+getnote search "客户反馈" --kb <topic_id> --limit 5 -o json
+```
 
-# Limit results + JSON output
-getnote search "机器学习" --limit 5 -o json
+成功 JSON 的稳定字段：
+
+| 字段 | 含义 | Agent 如何使用 |
+|---|---|---|
+| `success` | 业务是否成功 | 只有 `true` 才继续呈现结果。 |
+| `data.results[]` | 搜索结果 | 空数组是一次成功的“未找到”，不是失败。 |
+| `data.results[].title` | 笔记标题 | 列表主标题；为空时如实显示“未命名笔记”。 |
+| `data.results[].note_id` | 笔记雪花 ID | 始终作为字符串原样传入后续 `note` 命令。 |
+| `data.results[].note_url` | 真实笔记链接 | 只有非空时才给用户“打开笔记”。 |
+| `data.results[].content` | 命中摘要或正文片段 | 只摘取与问题相关的短片段，不能冒充全文。 |
+| `data.results[].score` | 相关性分数 | 仅用于内部排序，不向用户虚构“准确率”。 |
+
+成功时按相关性给出编号列表，例如：
+
+```text
+找到 3 条相关笔记：
+1. 《支付流程优化想法》——“用户等待时增加进度提示…”
+   打开：<真实 note_url>
+2. 《客户支付反馈》——“…”
+   打开：<真实 note_url>
+你想看哪一条的详情或原文？
 ```
 
----
+若 `data.results=[]`，回复“没有找到相关笔记；可以换关键词、时间范围或指定知识库再试”，不要说“接口失败”，也不要自动扩大检索范围、创建笔记或调用模型编造结果。
 
-## Agent Usage Notes
+## 失败、隐私与后续动作
 
-- Use `-o json` when parsing results programmatically.
-- JSON response: `{"success":true,"results":[{"note_id":"...","title":"...","content":"...","score":0.95,"created_at":"...","note_type":"..."}]}`
-- Note: `results` is at the top level, not nested under `data`.
-- Get `topic_id` for `--kb` from `getnote kbs -o json` → `data.topics[].topic_id`.
-- For `NOTE` type results, use `getnote note <note_id>` to get the full content.
-- Max `--limit` is 10; use `getnote notes` for browsing without a query.
-- Exit code `0` = success; non-zero = error. Error details go to stderr.
+- `success=false` 或退出码非 0：回复失败步骤、`error.message` / `error.reason`、是否 `retryable` 和可选 `request_id`；不要将 HTTP 成功或空输出说成搜索成功。
+- 若 CLI 提示“搜索服务响应超时”，这是检索未完成，不是“没有结果”。建议稍后重试，或缩小关键词、指定知识库后再试；不要伪造空列表。
+- 检索结果可能包含私密正文。群聊或共享会话默认只展示标题、必要摘要和真实链接；用户明确要求后再展开全文。
+- 用户选中结果后，复用返回的字符串 `note_id`，再读取 `getnote note <note_id> -o json`；不要从 URL 截取或转换为数字。

package/skills/getnote-tag/SKILL.md

@@ -1,73 +1,61 @@
 ---
 name: getnote-tag
-version: 0.4.0
-description: Manage note tags in Get笔记 via the getnote CLI
+description: 查看得到大脑笔记已有标签，为笔记添加标签，或按真实标签 ID 安全删除标签，并避免误删系统标签或覆盖其他标签。
 ---
 
-# getnote-tag Skill
+# 得到大脑标签
 
-Add, list, and remove tags on notes.
+通过官方 `getnote` CLI 管理真实标签。不要自己构造标签 ID，也不要把标签名误当成删除参数。机器调用统一使用 `-o json`；退出码为 0 但 `success=false` 仍是失败。
 
-## Prerequisites
+## 路由与安全边界
 
-- `getnote` CLI installed and authenticated (`getnote auth status` should show "Authenticated")
+| 用户意图 | 命令 | 不能做什么 |
+|---|---|---|
+| “这条笔记有哪些标签” | `getnote tag list <note_id>` | 不自动添加或删除。 |
+| “给这条笔记加上产品优化” | `getnote tag add <note_id> <tag>` | 只新增指定标签，不覆盖原标签。 |
+| “删掉这个标签” | 先 `tag list`，再 `getnote tag remove <note_id> <tag_id>` | 不能把标签名称直接当作 `tag_id`。 |
+| “替换为这些标签” | 先读取当前标签，再交给 `getnote note update --help` | 属于覆盖性操作，必须先确认。 |
 
-## Commands
+笔记 ID、标签 ID 及任何雪花 ID 始终作为字符串原样传递。系统标签不可删除；权限不足、标签不存在或笔记不存在时不能说“已经删掉”。
 
-### List tags on a note
+## 命令结果与用户呈现
 
-```
-getnote tag list <note_id>
-```
-
-Returns all tags with their IDs and types.
-
-Tag types:
-- `ai` — auto-generated by AI
-- `manual` — added by the user
-- `system` — system tag (**cannot be deleted**)
+### 查看标签
 
 ```bash
-getnote tag list 1896830231705320746
-getnote tag list 1896830231705320746 -o json
+getnote tag list <note_id> -o json
 ```
 
----
+成功 JSON：
 
-### Add a tag
+| 字段 | 含义 | 回复规则 |
+|---|---|---|
+| `success=true` | 标签读取成功 | 才能展示列表。 |
+| `data.note_id` | 实际读取的笔记 | 必须与目标笔记一致。 |
+| `data.tags[].id` | 标签真实 ID | 仅用于后续删除，不必在普通回复中暴露。 |
+| `data.tags[].name` | 标签名称 | 展示给用户。 |
+| `data.tags[].type` | 普通/系统等标签类型 | 系统类型明确不能删除。 |
 
-```
-getnote tag add <note_id> <tag>
-```
+若 `tags=[]`，回复“这条笔记目前没有标签”，这是成功结果。
+
+### 添加标签
 
 ```bash
-getnote tag add 1896830231705320746 工作
+getnote tag add <note_id> "产品优化" -o json
 ```
 
----
-
-### Remove a tag
+成功 JSON 必须有 `success=true`、`data.note_id` 与更新后的 `data.tags[]`。回复“已添加「产品优化」”，并在用户要求时列出当前全部标签；不要说“已替换标签”。如果结果没有新的标签集合，先再执行一次 `tag list` 核验，再向用户确认。
 
-```
-getnote tag remove <note_id> <tag_id>
-```
-
-> ⚠️ Requires **tag ID** (integer from `tag list`), not tag name.
-> ⚠️ `system` type tags cannot be removed.
+### 删除标签
 
 ```bash
-# Step 1: get tag IDs
-getnote tag list 1896830231705320746 -o json
-
-# Step 2: remove by tag ID
-getnote tag remove 1896830231705320746 123
+getnote tag remove <note_id> <tag_id> -o json
 ```
 
----
+删除前必须从当前 `tag list` 结果中拿到真实 `tag_id`，并确认该条不是系统标签。成功返回 `success=true` 才能回复“已删除「标签名」”；如果用户需要看剩余标签，再执行 `tag list`，不能猜测剩余集合。
 
-## Agent Usage Notes
+## 失败与恢复
 
-- `tag list -o json` returns `{"note_id":"...","tags":[{"id":"...","name":"...","type":"..."}]}` (flat, no `success` wrapper).
-- `tag remove` takes a **numeric tag ID**, not a name — always call `tag list` first.
-- To replace all tags at once, use `getnote note update --tag "tag1,tag2"` instead.
-- Exit code `0` = success; non-zero = error. Error details go to stderr.
+- 失败时展示实际 `error.message` / `error.reason`、是否可重试和 `request_id`；不要把“标签不存在”“系统标签”“无权限”归为通用网络错误。
+- 不能确定用户要删除哪一个同名标签时，先列出名称和类型让用户确认；不要按第一个结果擅自删除。
+- 在群聊中仅展示用户当前要求的标签信息；不通过标签列表推断或泄露笔记其他正文。