Mac Notes Agent

核心用法

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 被拒绝执行。

核心用法

Mac Notes Agent 是一款专为 macOS 设计的 Apple Notes 桥接工具，通过 Node.js CLI 调用 AppleScript（osascript）与系统原生备忘录应用交互。该技能支持完整的 CRUD 操作：创建笔记（add）、列出笔记（list）、读取内容（get）、更新正文（update）、追加内容（append）、删除笔记（delete）以及全文搜索（search）。所有操作均针对默认 Notes 账户，可指定目标文件夹（不存在时自动创建）。由于 Apple Notes 未暴露稳定 ID，该工具采用复合主键策略：优先使用 (folderName, title) 定位，同时生成合成 ID folderName::creationDate::title 作为备用标识。

显著优点

极致轻量与安全：零外部 npm 依赖，仅使用 Node.js 内置 child_process 模块，彻底规避供应链攻击风险。代码层面采用 execFileSync 替代 exec 避免 shell 注入，并配备自定义 esc() 函数对字符串参数进行转义处理，安全性经过充分考量。

原生集成体验：直接复用 macOS 系统级 Apple Notes，无需额外安装或配置，数据完全本地存储，与 iCloud 生态无缝衔接（取决于用户设置）。

功能完整实用：覆盖笔记管理的全生命周期，支持 `
转
` 的富文本渲染，自动文件夹创建机制降低使用门槛。

潜在缺点与局限性

平台强绑定：严格限定 macOS 环境，Windows/Linux 用户无法使用，且依赖 osascript 命令可用，部分企业定制系统可能受限。

ID 机制脆弱：合成 ID 基于创建时间戳，若用户手动修改系统时间或出现并发操作，可能导致标识冲突；同名笔记默认操作最近创建的一条，存在误操作隐患。

功能边界明确：不支持附件管理（图片、PDF 等）、标签系统、协作共享等进阶功能；无法检测 iCloud 同步状态，网络异常时可能出现数据延迟。

社区成熟度待观察：仓库创建仅 5 个月，零 stars/forks，作者为个人开发者（T3 级别），长期维护承诺存疑。

适合的目标群体

• macOS 重度用户：已将 Apple Notes 作为主力笔记工具，希望扩展自动化能力的个人用户
• Agent 工作流搭建者：需要让 AI 助手记录会议纪要、每日待办、灵感随想并同步至原生备忘录的场景
• 隐私敏感型用户：拒绝第三方云服务、坚持数据本地化的安全优先人群
• 轻量级自动化需求：无需复杂笔记功能，满足基础文本记录与检索即可的极简主义者

使用风险与注意事项

性能层面：AppleScript 调用存在一定延迟，高频批量操作（如一次性导入上千条笔记）可能出现性能瓶颈；execFileSync 同步执行模式会阻塞 Node.js 事件循环。

数据可靠性：建议关键业务配合本地备份机制，避免因 Apple Notes 数据库异常或同步冲突导致数据丢失；同名笔记操作需格外谨慎。

依赖稳定性：尽管当前实现稳健，但 T3 来源属性意味着需关注后续更新动态，警惕引入外部依赖或网络功能的版本变更。

输入校验建议：虽已实现转义防护，但缺乏长度限制，极端情况下超长参数可能引发异常，建议业务层前置校验。