# Joplin

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

- Skill: `zrong/joplin` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds add zrong/joplin`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zrong/joplin/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: zrong (https://skillmd.com/u/zrong)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/zrong/joplin

---


# 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 create --title "标题" [--body "内容"] [--body-from <文件路径>] [--parent <folder_id>]`
  - `--body` 适用于短文本；长文本或含有多行内容的，推荐用 `--body-from <文件路径>` 从本地文件读取
- **更新笔记**: `note update <id> [--title "新标题"] [--body "新内容"] [--body-from <文件路径>] [--parent <new_folder_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** 已启用。
- 附件上传和下载涉及本地文件路径，请确保路径正确且有读写权限。