@getnote/cli 0.1.5 → 0.1.6

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.6",
   "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,77 @@
+---
+name: getnote-auth
+version: 0.1.0
+description: Manage authentication for Get笔记 CLI
+---
+
+# getnote-auth Skill
+
+Log in, log out, and check authentication status for the `getnote` CLI.
+
+## Commands
+
+### Log in
+
+```
+getnote auth login [--api-key <key>] [--client-id <id>]
+```
+
+Two modes:
+
+| Mode | Command | Description |
+|------|---------|-------------|
+| OAuth (recommended) | `getnote auth login` | Opens browser to authorize; saves credentials automatically |
+| API Key | `getnote auth login --api-key <key>` | Saves API key directly, no browser needed |
+
+**Examples:**
+```bash
+# OAuth flow (opens browser)
+getnote auth login
+
+# Direct API key
+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
+```
+
+Shows whether the CLI is authenticated and which API key is in use.
+
+**Example:**
+```bash
+getnote auth status
+```
+
+---
+
+### Log out
+
+```
+getnote auth logout
+```
+
+Removes the saved API key from local config.
+
+**Example:**
+```bash
+getnote auth logout
+```
+
+---
+
+## Agent Usage Notes
+
+- Always run `getnote auth status` before other commands to verify authentication.
+- If not authenticated, prompt the user to run `getnote auth login`.
+- The `--api-key` flag on any command overrides the saved config temporarily (does not save).
+- Credentials are stored locally; `auth logout` removes them.

package/skills/getnote-kb/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: getnote-kb
+version: 0.1.0
+description: Manage knowledge bases in Get笔记 via the getnote CLI
+---
+
+# getnote-kb Skill
+
+Manage knowledge bases (话题/topic) in Get笔记 — list, create, and add or remove notes.
+
+## Prerequisites
+
+- `getnote` CLI installed and authenticated (`getnote auth status` should show "Authenticated")
+- API key configured via `getnote auth login --api-key <key>` or the `GETNOTE_API_KEY` environment variable
+
+## Commands
+
+### List knowledge bases
+
+```
+getnote kb list [--output json|table]
+```
+
+Returns all knowledge bases accessible to the authenticated user.
+
+**Examples:**
+```bash
+# Human-friendly table
+getnote kb list
+
+# Machine-readable JSON
+getnote kb list --output json
+```
+
+---
+
+### Create a knowledge base
+
+```
+getnote kb create <name> [--desc <description>]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--desc` | Optional description for the knowledge base |
+
+**Examples:**
+```bash
+getnote kb create "Research Papers"
+getnote kb create "Project Docs" --desc "Documentation links for the main project"
+```
+
+---
+
+### List notes in a knowledge base
+
+```
+getnote kb notes <topic_id> [--limit <n>] [--output json|table]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--limit` | 20 | Maximum number of notes to return |
+
+**Examples:**
+```bash
+# List notes in a knowledge base
+getnote kb notes kb_abc123
+
+# Get more results
+getnote kb notes kb_abc123 --limit 50
+
+# Machine-readable output
+getnote kb notes kb_abc123 --output json
+```
+
+---
+
+### Add notes to a knowledge base
+
+```
+getnote kb add <topic_id> <note_id> [note_id...]
+```
+
+Supports adding multiple notes in a single call.
+
+**Examples:**
+```bash
+# Add a single note
+getnote kb add kb_abc123 note_xyz789
+
+# Add multiple notes at once
+getnote kb add kb_abc123 note_xyz789 note_def456 note_ghi012
+```
+
+---
+
+### Remove notes from a knowledge base
+
+```
+getnote kb remove <topic_id> <note_id> [note_id...]
+```
+
+Supports removing multiple notes in a single call.
+
+**Examples:**
+```bash
+# Remove a single note
+getnote kb remove kb_abc123 note_xyz789
+
+# Remove multiple notes at once
+getnote kb remove kb_abc123 note_xyz789 note_def456
+```
+
+---
+
+## Agent Usage Notes
+
+- Use `--output json` for all commands when parsing responses programmatically.
+- To get a `topic_id`, first call `getnote kb list --output json` and extract the `id` field.
+- `kb add` and `kb remove` accept multiple note IDs in a single call — prefer batching over multiple calls.
+- Exit code `0` = success; non-zero = error. Error details go to stderr.
+- Combine with `getnote note list --output json` to get note IDs before adding them to a knowledge base.

package/skills/getnote-note/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: getnote-note
+version: 0.1.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")
+- API key configured via `getnote auth login --api-key <key>` or the `GETNOTE_API_KEY` environment variable
+
+## Commands
+
+### Save a note
+
+```
+getnote note save <url|text> [--title <title>] [--tag <tag>]...
+```
+
+| Flag | Description |
+|------|-------------|
+| `--title` | Optional title for the note |
+| `--tag` | Tag to apply; may be repeated |
+
+- If the argument starts with `http://` or `https://`, it is saved as a **link note**.
+- Otherwise it is saved as a **text note**.
+
+**Examples:**
+```bash
+# Save a URL
+getnote note save https://example.com/article --title "Interesting article" --tag reading
+
+# Save plain text
+getnote note save "Remember to review the API docs" --tag todo
+
+# Save with multiple tags
+getnote note save https://docs.example.com --tag docs --tag reference
+```
+
+The response includes a `task_id` you can use to track progress:
+```bash
+getnote note task <task_id>
+```
+
+---
+
+### List notes
+
+```
+getnote note list [--limit <n>] [--since-id <id>] [--output json|table]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--limit` | 20 | Maximum number of notes to return |
+| `--since-id` | — | Cursor for pagination (ID of last note seen) |
+| `--output` | table | Output format: `table` or `json` |
+
+**Examples:**
+```bash
+# List recent 20 notes
+getnote note list
+
+# List 50 notes
+getnote note list --limit 50
+
+# Paginate using cursor
+getnote note list --since-id note_abc123
+
+# Machine-readable JSON output
+getnote note list --output json
+```
+
+---
+
+### Get note details
+
+```
+getnote note get <note_id>
+```
+
+**Example:**
+```bash
+getnote note get note_abc123
+getnote note get note_abc123 --output json
+```
+
+---
+
+### Update a note
+
+```
+getnote note update <note_id> [--title <title>] [--content <content>] [--tags <tag1,tag2>]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--title` | New title |
+| `--content` | New content body |
+| `--tags` | Comma-separated tags (replaces all existing tags) |
+
+**Example:**
+```bash
+getnote note update note_abc123 --title "Updated title" --tags "work,important"
+```
+
+---
+
+### Delete a note
+
+```
+getnote note delete <note_id> [--yes]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--yes` | Skip the confirmation prompt |
+
+**Examples:**
+```bash
+# Interactive confirmation
+getnote note delete note_abc123
+
+# Skip confirmation (useful in scripts)
+getnote note delete note_abc123 --yes
+```
+
+---
+
+### Query task progress
+
+```
+getnote note task <task_id>
+```
+
+Use this after `note save` to check whether a URL has been processed.
+
+**Example:**
+```bash
+getnote note task task_xyz789
+getnote note task task_xyz789 --output json
+```
+
+---
+
+## Agent Usage Notes
+
+- Use `--output json` for all commands when parsing responses programmatically.
+- `note save` may be async for URLs; poll `note task <task_id>` until `status` is `done`.
+- `note list --output json` returns a JSON array suitable for further processing with `jq`.
+- Pass `--yes` to `note delete` to avoid interactive prompts in automated workflows.
+- Exit code `0` = success; non-zero = error. Error details go to stderr.

package/skills/getnote-search/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: getnote-search
+version: 0.1.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 in Get笔记.
+
+## Prerequisites
+
+- `getnote` CLI installed and authenticated (`getnote auth status` should show "Authenticated")
+- API key configured via `getnote auth login --api-key <key>` or the `GETNOTE_API_KEY` environment variable
+
+## Commands
+
+### Search notes
+
+```
+getnote search <query> [--kb <topic_id>] [--limit <n>] [--output json|table]
+```
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--kb` | — | Limit search to a specific knowledge base (topic_id) |
+| `--limit` | 10 | Max results to return (max 10) |
+| `--output` | table | Output format: `table` or `json` |
+
+**Examples:**
+```bash
+# Search across all notes
+getnote search "大模型 API"
+
+# Search within a specific knowledge base
+getnote search "RAG" --kb qnNX75j0
+
+# Limit results and get JSON output
+getnote search "机器学习" --limit 5 --output json
+```
+
+---
+
+## Agent Usage Notes
+
+- Use `--output json` when parsing results programmatically.
+- To search within a knowledge base, first get the `topic_id` via `getnote kb list --output json`.
+- Results are ranked by semantic relevance, not recency.
+- Max `--limit` is 10; for broader discovery use `getnote notes list` instead.
+- Exit code `0` = success; non-zero = error. Error details go to stderr.

package/skills/getnote-tag/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: getnote-tag
+version: 0.1.0
+description: Manage note tags in Get笔记 via the getnote CLI
+---
+
+# getnote-tag Skill
+
+Add, list, and remove tags on notes in Get笔记.
+
+## Prerequisites
+
+- `getnote` CLI installed and authenticated (`getnote auth status` should show "Authenticated")
+- API key configured via `getnote auth login --api-key <key>` or the `GETNOTE_API_KEY` environment variable
+
+## Commands
+
+### List tags on a note
+
+```
+getnote tag list <note_id> [--output json|table]
+```
+
+**Examples:**
+```bash
+getnote tag list 1896830231705320746
+getnote tag list 1896830231705320746 --output json
+```
+
+Returns tag list including tag IDs (needed for `tag remove`).
+
+---
+
+### Add a tag to a note
+
+```
+getnote tag add <note_id> <tag>
+```
+
+**Examples:**
+```bash
+getnote tag add 1896830231705320746 工作
+getnote tag add 1896830231705320746 阅读
+```
+
+---
+
+### Remove a tag from a note
+
+```
+getnote tag remove <note_id> <tag_id>
+```
+
+> ⚠️ Requires **tag ID** (not tag name). Use `getnote tag list <note_id>` to find the tag ID first.
+> System tags cannot be removed.
+
+**Examples:**
+```bash
+# First, find the tag ID
+getnote tag list 1896830231705320746 --output json
+
+# Then remove by tag ID
+getnote tag remove 1896830231705320746 123
+```
+
+---
+
+## Agent Usage Notes
+
+- Use `--output json` on `tag list` to get tag IDs for use with `tag remove`.
+- `tag remove` takes a **tag ID** (integer), not a tag name — always call `tag list` first if you only have the name.
+- System tags cannot be deleted; the CLI will return an error if attempted.
+- Exit code `0` = success; non-zero = error. Error details go to stderr.