@getnote/cli 0.1.5 → 0.1.7

package/README.md

@@ -23,6 +23,13 @@ npm install -g @getnote/cli
 npm install -g @getnote/cli
 ```
 
+**（可选）安装 AI Agent Skill**
+
+在 Claude Code、Cursor 等 AI 编程工具里用自然语言操作笔记，需要额外安装 Skill：
+```bash
+npx skills add @getnote/cli -y -g
+```
+
 **第二步：登录**
 ```bash
 getnote auth login
@@ -99,7 +106,13 @@ getnote search "关键词" -o json
 getnote save https://example.com -o json   # 自动轮询，返回最终笔记
 ```
 
-`skills/` 目录下有 Claude Code 专用的 Skill 文件，加到项目上下文后，AI Agent 可以直接用自然语言操作笔记。
+`skills/` 目录下有 Claude Code 专用的 Skill 文件，安装后 AI Agent 可以直接用自然语言操作笔记：
+
+```bash
+npx skills add @getnote/cli -y -g
+```
+
+安装后在 Claude Code / Cursor 里说「帮我搜一下关于 RAG 的笔记」即可直接调用。
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getnote/cli",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "CLI tool for Get笔记 — manage notes and knowledge bases from the terminal",
   "keywords": [
     "getnote",
@@ -23,6 +23,7 @@
   "files": [
     "bin/",
     "scripts/",
+    "skills/",
     "README.md"
   ]
 }

package/skills/getnote-auth/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: getnote-auth
+version: 0.2.0
+description: Manage authentication for Get笔记 CLI
+---
+
+# getnote-auth Skill
+
+Log in, log out, and check authentication status.
+
+## Commands
+
+### Log in
+
+```
+getnote auth login [--api-key <key>] [--client-id <id>]
+```
+
+| Mode | Command | Description |
+|------|---------|-------------|
+| OAuth (recommended) | `getnote auth login` | Opens browser to authorize |
+| API Key | `getnote auth login --api-key <key>` | Saves key directly, no browser |
+
+```bash
+# OAuth flow
+getnote auth login
+
+# API key directly
+getnote auth login --api-key gk_live_xxx
+
+# API key + Client ID
+getnote auth login --api-key gk_live_xxx --client-id cli_xxx
+```
+
+API keys start with `gk_live_`. Get yours at: https://www.biji.com/settings/developer
+
+---
+
+### Check status
+
+```
+getnote auth status
+```
+
+```bash
+getnote auth status
+```
+
+---
+
+### Log out
+
+```
+getnote auth logout
+```
+
+Removes saved credentials from local config.
+
+```bash
+getnote auth logout
+```
+
+---
+
+## 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 override and does not save credentials.
+- Credentials are stored in `~/.getnote/config.json`; `auth logout` removes them.

package/skills/getnote-kb/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: getnote-kb
+version: 0.2.0
+description: Manage knowledge bases in Get笔记 via the getnote CLI
+---
+
+# getnote-kb Skill
+
+Manage knowledge bases in Get笔记 — list, create, browse notes, add/remove notes.
+
+## Prerequisites
+
+- `getnote` CLI installed and authenticated (`getnote auth status` should show "Authenticated")
+
+## Commands
+
+### List all knowledge bases
+
+```
+getnote kbs
+```
+
+```bash
+getnote kbs
+getnote kbs -o json
+```
+
+---
+
+### List notes in a knowledge base
+
+```
+getnote kb <topic_id> [--limit <n>] [--all]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--limit` | 20 | Notes per page |
+| `--all` | — | Fetch all notes (auto-paginate) |
+
+```bash
+getnote kb vnrOAaGY
+getnote kb vnrOAaGY --limit 5
+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 for the main project"
+```
+
+---
+
+### Add notes to a knowledge base
+
+```
+getnote kb add <topic_id> <note_id> [note_id...]
+```
+
+Supports multiple note IDs in one call.
+
+```bash
+getnote kb add vnrOAaGY 1234567890
+getnote kb add vnrOAaGY 1234567890 9876543210
+```
+
+---
+
+### Remove notes from a knowledge base
+
+```
+getnote kb remove <topic_id> <note_id> [note_id...]
+```
+
+```bash
+getnote kb remove vnrOAaGY 1234567890
+getnote kb remove vnrOAaGY 1234567890 9876543210
+```
+
+---
+
+## Agent Usage Notes
+
+- Use `-o json` when parsing results programmatically.
+- Get `topic_id` from `getnote kbs -o json` (the `id` field).
+- `kb add` / `kb remove` accept multiple note IDs — prefer batching over multiple calls.
+- Exit code `0` = success; non-zero = error. Error details go to stderr.

package/skills/getnote-note/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: getnote-note
+version: 0.2.0
+description: Manage notes in Get笔记 via the getnote CLI
+---
+
+# getnote-note Skill
+
+Manage individual notes in Get笔记 — save, list, get, update, delete, and track save tasks.
+
+## Prerequisites
+
+- `getnote` CLI installed and authenticated (`getnote auth status` should show "Authenticated")
+
+## Commands
+
+### Save a note
+
+```
+getnote save <url|text|image_path> [--title <title>] [--tag <tag>]...
+```
+
+| Flag | Description |
+|------|-------------|
+| `--title` | Optional title |
+| `--tag` | Tag to apply; may be repeated |
+
+- URL (`http://` or `https://`) → saved as link note
+- Local image path → saved as image note
+- Otherwise → saved as text note
+
+**Examples:**
+```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"
+```
+
+URL saves are async; the CLI auto-polls until done, then shows the result.
+In `-o json` mode, silently polls and returns the final note JSON.
+
+---
+
+### Track save task
+
+```
+getnote task <task_id>
+```
+
+Check progress of an async save task (returned by `save` for URLs).
+
+```bash
+getnote task task_xyz789
+getnote task task_xyz789 -o json
+```
+
+---
+
+### List recent notes
+
+```
+getnote notes [--limit <n>] [--since-id <id>] [--all]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--limit` | 20 | Notes per page |
+| `--since-id` | — | Pagination cursor (last note ID seen) |
+| `--all` | — | Fetch all notes (auto-paginate, streams output) |
+
+```bash
+getnote notes
+getnote notes --limit 5
+getnote notes --all
+getnote notes --since-id 1234567890
+getnote notes -o json
+```
+
+---
+
+### Get note details
+
+```
+getnote note <id> [--field <field>]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--field` | Output a single field: `id` / `title` / `content` / `type` / `created_at` / `updated_at` / `url` / `excerpt` |
+
+```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) |
+
+```bash
+getnote note update 1234567890 --title "Updated title"
+getnote note update 1234567890 --tag "work,important"
+```
+
+---
+
+### Delete a note
+
+```
+getnote note delete <id> [-y]
+```
+
+Moves note to trash.
+
+| Flag | Description |
+|------|-------------|
+| `-y` | Skip confirmation prompt |
+
+```bash
+getnote note delete 1234567890
+getnote note delete 1234567890 -y
+```
+
+---
+
+## Agent Usage Notes
+
+- Use `-o json` when parsing responses programmatically.
+- `save` for URLs is async; in `-o json` mode the CLI auto-polls and returns the final note — no manual `task` polling needed.
+- `note update --tag` replaces **all** existing tags; use `getnote tag add/remove` for partial updates.
+- Exit code `0` = success; non-zero = error. Error details go to stderr.

package/skills/getnote-search/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: getnote-search
+version: 0.2.0
+description: Semantic search across notes in Get笔记 via the getnote CLI
+---
+
+# getnote-search Skill
+
+Semantic search across all notes or within a specific knowledge base.
+
+## Prerequisites
+
+- `getnote` CLI installed and authenticated (`getnote auth status` should show "Authenticated")
+
+## Commands
+
+### Search notes
+
+```
+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) |
+
+```bash
+# Search across all notes
+getnote search "大模型 API"
+
+# Search within a knowledge base
+getnote search "RAG" --kb qnNX75j0
+
+# Limit results + JSON output
+getnote search "机器学习" --limit 5 -o json
+```
+
+---
+
+## Agent Usage Notes
+
+- Use `-o json` when parsing results programmatically.
+- Get `topic_id` for `--kb` from `getnote kbs -o json`.
+- Results are ranked by semantic relevance, not recency.
+- Max `--limit` is 10; use `getnote notes` for broader browsing.
+- Exit code `0` = success; non-zero = error. Error details go to stderr.

package/skills/getnote-tag/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: getnote-tag
+version: 0.2.0
+description: Manage note tags in Get笔记 via the getnote CLI
+---
+
+# getnote-tag Skill
+
+Add, list, and remove tags on notes.
+
+## Prerequisites
+
+- `getnote` CLI installed and authenticated (`getnote auth status` should show "Authenticated")
+
+## Commands
+
+### List tags on a note
+
+```
+getnote tag list <note_id>
+```
+
+Returns all tags including their IDs (needed for `tag remove`).
+
+```bash
+getnote tag list 1896830231705320746
+getnote tag list 1896830231705320746 -o json
+```
+
+---
+
+### Add a tag
+
+```
+getnote tag add <note_id> <tag>
+```
+
+```bash
+getnote tag add 1896830231705320746 工作
+```
+
+---
+
+### Remove a tag
+
+```
+getnote tag remove <note_id> <tag_id>
+```
+
+> ⚠️ Requires **tag ID** (integer), not tag name. Run `getnote tag list <note_id>` first to get the ID.
+> System tags cannot be removed.
+
+```bash
+# Get tag IDs first
+getnote tag list 1896830231705320746 -o json
+
+# Remove by tag ID
+getnote tag remove 1896830231705320746 123
+```
+
+---
+
+## Agent Usage Notes
+
+- `tag remove` takes a **tag ID**, not a name — always call `tag list` first if you only have the name.
+- For bulk tag replacement, use `getnote note update --tag` instead (replaces all tags at once).
+- Exit code `0` = success; non-zero = error. Error details go to stderr.