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、treeWRITE（写入）只读 + writeADMIN（管理）写入 + deleteALL（全部）通配所有操作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、deletesecret是密钥管理面板生成的密钥（如 mnsec_xxx...）x-success是成功回调 URL，处理完成后跳转并携带结果x-error是失败回调 URLpayload按需操作参数，JSON 字符串进行 URL Encode3.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%7Dpayload 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%7Dpayload 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%7Dpayload 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」操作，填入上述 URL 即可调用。配合「获取 URL 内容」和「字典」操作，可以解析返回的 JSON 数据，实现自动化工作流。4 插件下载url-apis-v0.2.0.mnaddon (23.3 KB)