git:20260319.d841107 to git:20260329.db8d868

---

name: joplin

description: 完整的 Joplin REST API 客户端，支持笔记(Notes)、笔记本(Folders)、标签(Tags)、资源/附件(Resources)的 CRUD 操作，以及搜索、修订版本和事件流。

---

# Joplin Skill (Complete API)

此 Skill 提供了对 Joplin REST API 的全面访问，允许 Agent 深度管理 Joplin 笔记库。

## 环境配置

- `JOPLIN_TOKEN`: Joplin API Token（保存在项目根目录 `.env` 文件中）。

- `JOPLIN_BASE_URL`: 默认为 `http://localhost:41184`。

## 功能列表与命令指南

建议使用 `uv run --project joplin/scripts joplin/scripts/joplin_tool.py <command>` 执行。

### 1. 全局与系统

- **检查连接**: `ping`

- **获取事件流**: `events [--cursor <cursor>] [--limit <limit>]`

- **获取修订版本**:

- `revision list`

- `revision get <id>`

### 2. 笔记 (Note)

- **列出笔记**: `note list [--limit 10] [--page 1] [--fields "id,title"] [--order-by "updated_time"] [--order-dir "DESC"]`

- **获取详情**: `note get <id>`

- **删除笔记**: `note delete <id>`

- **查看笔记标签**: `note tags <id>`

- **查看笔记资源**: `note resources <id>`

### 3. 笔记本 (Folder)

- **列出笔记本**: `folder list [--fields "id,title,parent_id"]`

- **获取详情**: `folder get <id>`

- **创建笔记本**: `folder create "标题" [--parent <parent_id>]`

- **更新笔记本**: `folder update <id> "新标题"`

- **删除笔记本**: `folder delete <id>`

### 4. 标签 (Tag)

- **列出标签**: `tag list`

- **获取详情**: `tag get <id>`

- **创建标签**: `tag create "标题"`

- **更新标签**: `tag update <id> "新标题"`

- **删除标签**: `tag delete <id>`

- **给笔记打标签**: `tag add <tag_id> <note_id>`

- **移除笔记标签**: `tag remove <tag_id> <note_id>`

### 5. 资源/附件 (Resource)

- **列出资源**: `resource list [--limit 100]`

- **获取详情**: `resource get <id>`

- **上传附件**: `resource upload <file_path> [--title "标题"]`

- **下载附件**: `resource download <id> <dest_path>`

- **删除资源**: `resource delete <id>`

### 6. 搜索 (Search)

- **执行搜索**: `search --query "关键词" [--type note|folder|tag] [--limit 10] [--page 1]`

## 测试流程

执行以下命令进行完整验证：

1. `uv run --project joplin/scripts joplin/scripts/joplin_tool.py ping`

2. `uv run --project joplin/scripts joplin/scripts/joplin_tool.py folder list`

3. `uv run --project joplin/scripts joplin/scripts/joplin_tool.py note list --limit 1`

## 注意事项

- 必须确保 Joplin 桌面端的 **Web Clipper** 已启用。

- 附件上传和下载涉及本地文件路径，请确保路径正确且有读写权限。