1 插件介绍
Url Apis 是一款为 MarginNote 4 提供 REST 风格 URL 接口的插件。它基于 MarginNote 的 URL Scheme 机制（marginnote4app://addon/api?...），将笔记的读取、搜索、创建、修改、删除等操作，暴露为可通过链接直接调用的 API。
这意味着：
- macOS 上可以用
open命令或快捷指令触发 - iOS/macOS 快捷指令 App 可一键调用，无需手动复制粘贴
- Obsidian、Drafts、Scriptable 等 App 可以通过 URL 与 MarginNote 双向联动
- 你甚至可以把它当作 MarginNote 的远程控制网关，用任意能发起 URL 请求的工具来操作笔记
适用场景
| 场景 | 说明 |
|---|---|
| 快捷指令自动化 | 一键搜索笔记、创建卡片、收集剪贴板内容 |
| Obsidian 联动 | 从 Obsidian 读取/写入 MarginNote 笔记 |
| 跨应用集成 | 通过 Drafts、Scriptable 等 App 控制 MarginNote |
| 批量操作 | 脚本批量修改笔记、移动卡片、清理垃圾笔记 |
2 功能说明
2.1 认证与权限
插件内置了完善的鉴权系统。点击 MarginNote 工具栏中的插件图标，即可打开密钥管理面板。
- 生成密钥：点击权限按钮（EMPTY / READ / WRITE / ADMIN / ALL）生成不同权限的密钥，自动复制到剪贴板
- 密钥管理：查看、复制、删除密钥，添加备注，修改权限
- 权限分级：
| 权限组 | 允许的操作 |
|---|---|
| EMPTY（空权限） | 无法执行任何操作 |
| READ（只读） | ping、read、ls、find、tree |
| WRITE（写入） | 只读 + write |
| ADMIN（管理） | 写入 + delete |
| ALL（全部） | 通配所有操作 |
2.2 防重放机制
为防止中间人截获 URL 后重复执行相同请求，每次请求必须携带独一无二的 requestId。同一密钥下执行过的 requestId 在 2 分钟内会被拒绝执行，有效防御重放攻击。
2.3 路径定位
插件使用直观的 URI 路径模型定位笔记：
| 路径格式 | 说明 |
|---|---|
notebook:// |
所有笔记本根节点 |
notebook://笔记本名称 |
定位到具体笔记本 |
notebook://笔记本名/父卡片/子卡片 |
按标题层级定位 |
@id:noteId |
通过笔记内部 ID 定位 |
@current |
当前学习窗口中聚焦的笔记或笔记本 |
@root |
等同于 notebook:// |
2.4 可用动作
| 动作 | 说明 |
|---|---|
| ping | 健康检查，测试密钥和网关是否可用 |
| ls | 列出指定路径下的笔记本或笔记项，支持深度展开和类型过滤 |
| read | 读取笔记本或卡片的详细信息（标题、正文、评论、子节点等） |
| find | 全局搜索关键词，匹配标题或内容 |
| tree | 导出层级结构的笔记树和带缩进的文本渲染 |
| write | 创建、更新、追加评论或移动笔记 |
| delete | 删除指定卡片（需 ADMIN 权限） |
3 使用教程
3.1 安装与准备
- 在 MarginNote 4 中安装本插件
- 点击工具栏中的插件图标，打开密钥管理面板
- 点击 READ（只读）或 WRITE（写入）等权限按钮，生成密钥并自动复制
3.2 构建 URL
所有请求通过标准的 URL Scheme 触发，入口固定为：
marginnote4app://addon/api
通过 URL Query 传递控制字段：
| 参数 | 必须 | 说明 |
|---|---|---|
requestId |
是 | 请求唯一标识符（如 UUID），用于防重放 |
action |
是 | 操作名称：ping、read、ls、find、tree、write、delete |
secret |
是 | 密钥管理面板生成的密钥（如 mnsec_xxx...） |
x-success |
是 | 成功回调 URL，处理完成后跳转并携带结果 |
x-error |
是 | 失败回调 URL |
payload |
按需 | 操作参数，JSON 字符串进行 URL Encode |
3.3 常用示例
健康检查（ping）
marginnote4app://addon/api?requestId=req_001&action=ping&secret=mnsec_xxx&x-success=myapp://success&x-error=myapp://error
列出所有笔记本（ls）
marginnote4app://addon/api?requestId=req_002&action=ls&secret=mnsec_xxx&x-success=myapp://success&x-error=myapp://error&payload=%7B%22path%22%3A%22notebook%3A%2F%2F%22%7D
payload URL Decode 后为：{"path":"notebook://"}
读取当前学习笔记（read）
marginnote4app://addon/api?requestId=req_003&action=read&secret=mnsec_xxx&x-success=myapp://success&x-error=myapp://error&payload=%7B%22path%22%3A%22%40current%22%7D
payload URL Decode 后为：{"path":"@current"}
创建新卡片（write）
marginnote4app://addon/api?requestId=req_004&action=write&secret=mnsec_xxx&x-success=myapp://success&x-error=myapp://error&payload=%7B%22mode%22%3A%22create%22%2C%22path%22%3A%22notebook%3A%2F%2F%E5%A4%87%E5%BF%98%E5%BD%95%22%2C%22title%22%3A%22%E6%96%B0%E5%8D%A1%E7%89%87%22%7D
payload URL Decode 后为：{"mode":"create","path":"notebook://备忘录","title":"新卡片"}
3.4 回调响应格式
每个请求处理完成后，插件会通过 x-success 或 x-error 回调，将结果 JSON 追加在 payload 参数中：
myapp://success?payload=%7B%22code%22%3A%22OK%22...%7D
解码后为：
{
"code": "OK",
"message": "OK",
"requestId": "req_001",
"data": {},
"details": null
}
| 错误码 | 说明 |
|---|---|
OK |
成功 |
BAD_REQUEST |
请求参数错误 |
AUTH_FAILED |
密钥认证失败 |
FORBIDDEN |
权限不足 |
NOT_FOUND |
目标路径或资源不存在 |
REPLAY_DETECTED |
防重放触发，requestId 已被使用 |
INTERNAL_ERROR |
插件内部异常 |
3.5 快捷指令集成示例
在 iOS/macOS 快捷指令 App 中，使用「打开 URL」/「打开 X-Callback URL」操作，填入上述 URL 即可调用。配合「获取 URL 内容」和「字典」操作，可以解析返回的 JSON 数据，实现自动化工作流。可以在GitHub查看示例快捷指令
