核心用法
Mac Notes Agent 是一套针对 macOS 原生「备忘录」App 的轻量级桥接方案。它通过 Node.js 调用 osascript 执行 AppleScript，将命令行操作映射为 Notes 的 CRUD 动作。支持七种核心指令：添加（add）、列表（list）、读取（get）、更新（update）、追加（append）、删除（delete）与搜索（search）。用户可通过 --folder 指定目标文件夹，系统会自动创建不存在的目录；通过合成 ID（folder::creationDate::title）或「文件夹+标题」组合定位单条笔记。
显著优点
1. 零外部依赖：仅使用 Node.js 内置模块（child_process），无需 npm install，部署极简。
2. 原生集成：直接操控 Apple Notes，数据完全本地化，无需云端同步或第三方账户。
3. 灵活定位：支持标题匹配与合成 ID 双模式，兼顾人机可读与机器精准定位。
4. 格式兼容：自动将 \n 转换为 <br>，确保换行在富文本备忘录中正确渲染。
潜在局限
- 平台锁定：仅限 macOS，且依赖
osascript与系统预装的 Notes App，无法跨平台。 - ID 不稳定：Apple Notes 未暴露持久 UUID，CLI 以「创建时间」作为合成 ID 的一部分，若用户手动修改时间或出现重复标题，可能引发歧义。
- 并发风险：AppleScript 单线程执行，高频写入可能出现竞态；多笔记同名时仅操作最新一条，易误触。
- 富文本限制：仅支持纯文本写入，无法直接插入图片、表格或样式化文本。
适合人群
- 需在自动化工作流（如 AI Agent、Shell 脚本）中读写本地备忘录的 macOS 开发者与高级用户。
- 偏好数据本地存储、拒绝第三方云笔记的隐私敏感型用户。
- 构建个人知识管理（PKM）自动化链路的极客玩家。
常规风险
- 误删误改：update 与 delete 操作不可逆，且无回收站二次确认机制，脚本逻辑错误将导致数据丢失。
- AppleScript 阻塞：osascript 调用为同步进程，大量笔记查询时可能阻塞 Node.js 事件循环。
- 系统权限：首次运行需在「系统设置 > 隐私与安全性 > 辅助功能」中授予终端或父进程控制 Notes 的权限，否则 AppleScript 被拒绝执行。