Joplin API 管理器

要解决什么问题

Joplin 的数据都落在本地 SQLite 里。一旦想做批量迁移、外部索引、自动归档，或者和别的工具联动，直接翻数据库并不是好主意。这个技能把 Joplin 桌面版自带的 Web Clipper Service REST API 整理成一套可直接调用的操作集，让你用脚本管理笔记、笔记本、标签和附件，而不是在客户端里手工点来点去。

技能如何工作

连接很直接：Joplin 桌面版运行中，从 工具 → 选项 → Web Clipper → 显示高级设置 里复制 Authorization Token，每个请求以 ?token= 查询参数附加到 URL。默认端口 41184（范围 41184–41194），动手前先用 GET /ping 确认服务在线。

核心能力覆盖四类资源：

• 笔记：GET/POST/PUT/DELETE /notes，创建时传 title、body（Markdown）、parent_id；PUT 是部分更新，只修改传入的字段
• 笔记本：GET /folders 返回树结构，子笔记本在 children 下；PUT /folders/:id 改 parent_id 即可移动整个目录
• 标签：POST /tags 建标签，POST /tags/:id/notes 绑定到笔记，DELETE /tags/:id/notes/:note_id 解绑
• 资源：POST /resources 以 multipart/form-data 上传文件，GET /resources/:id/file 取回实际内容

此外还提供全文搜索（笔记走 FTS4，type=folder、type=tag 走简单通配符匹配）、变更事件（创建/更新/删除）用于增量同步，以及 fields 字段过滤、order_by 排序和 page/limit 分页。

适用边界与注意点

几个实测会踩的坑：

• 含中文的请求体必须用 Python urllib 以 UTF-8 编码发送，PowerShell 的 Invoke-RestMethod 会把中文变成问号
• page 和 limit 只在 /notes 和 /folders 上可靠，parent_id 过滤会返回 403，找文件夹得用搜索替代
• DELETE 返回空 body，直接 json.loads 会抛 JSONDecodeError，先判断响应是否为空
• 时间为 Unix 毫秒时间戳，布尔值是 0 或 1
• Windows 控制台是 GBK 编码，print emoji 会 UnicodeEncodeError

不适合的场景：多用户并发写入，或者脱离 Joplin 桌面版常驻的服务端部署——这套 API 依赖本地 Web Clipper 服务在线。