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 已启用。
• 附件上传和下载涉及本地文件路径，请确保路径正确且有读写权限。