macOS Notes

核心用法

macos-notes 是一款基于 AppleScript 的 macOS 专属技能，通过 osascript 与系统备忘录应用（Notes.app）深度集成，实现笔记的自动化管理。该技能采用 shell 脚本封装层 ($SKILL_DIR/scripts/notes.sh) 作为统一入口，支持六大核心操作：列出账户与文件夹、创建笔记、读取笔记、列出笔记、搜索笔记。

所有交互均通过 JSON 格式经 stdin 传递，避免命令行参数泄露敏感数据。创建笔记时支持纯文本自动转 HTML，或直接传入富文本 HTML；读取时则自动将内部 HTML 渲染为纯文本返回。技能强制要求先执行 list-folders 以识别账户结构，解决跨账户同名文件夹的歧义问题。

显著优点

1. 原生系统集成：直接调用 AppleScript，无需第三方云服务或 API 密钥，数据完全保留在本地 iCloud/本地账户中。
2. 零配置依赖：仅需系统预装的 osascript 和 python3，无额外二进制依赖。
3. 安全传输设计：JSON 通过 stdin 传递，规避进程列表暴露敏感内容的风险。
4. 自动格式转换：底层处理 HTML/文本转换，用户侧只需关注内容本身。
5. 审计日志：所有操作记录至 logs/notes.log，便于追溯。

潜在缺点与局限性

1. 平台严格受限：仅支持 macOS，Windows/Linux 用户无法使用。
2. 密码笔记不可访问：受 AppleScript 沙盒限制，无法读取或修改受密码保护的笔记。
3. 标题精确匹配：read-note 依赖笔记标题精确匹配，容错性较低。
4. 无并发控制：未提及锁机制，多进程同时写入可能导致数据竞争。
5. HTML 能力有限：虽支持原始 HTML 注入，但 Notes.app 实际渲染能力受限于其内部 HTML 子集，复杂样式可能被过滤。

适合人群

• macOS 重度用户，希望将笔记管理纳入自动化工作流
• 注重隐私、拒绝云服务同步的本地优先用户
• 需快速记录会议纪要、待办事项或碎片化信息的效率工作者
• 与其他 CLI 工具链（如 fzf、jq）集成的开发者

常规风险

• 数据误操作：精确匹配标题机制下，误删或覆盖同名笔记风险存在
• 脚本注入：虽经 JSON 转义，但 html 字段的原始 HTML 注入仍需警惕 XSS 样式的内容污染
• iCloud 同步延迟：依赖系统级同步，网络异常时可能出现笔记状态不一致
• 权限变更：macOS 版本升级可能收紧 osascript 对 Notes.app 的自动化权限，导致技能失效

核心用法

macos-notes 是一款专为 macOS 设计的 Apple Notes 管理 Skill，通过 AppleScript 与系统原生备忘录应用深度集成。用户可通过自然语言指令完成笔记的全生命周期管理：快速记录灵感（"记下这个 API 格式"）、创建结构化会议笔记、按关键词搜索历史内容、读取特定标题的笔记详情，以及浏览最近笔记列表。所有操作均通过 notes.sh 脚本执行，支持 JSON 标准输入和纯文本/ HTML 内容格式，自动处理账户与文件夹的层级关系。

使用时需注意关键流程：涉及账户或文件夹选择时，必须先执行 `list-folders` 获取可用账户列表，避免跨账户的文件夹命名冲突；创建笔记时纯文本内容会自动转换为 HTML 存储，而指定 html 字段可保留富格式；读取功能依赖精确标题匹配，不支持模糊搜索。

显著优点

原生生态无缝衔接：直接调用 Apple Notes 应用，笔记数据完全存储于用户 iCloud 或本地账户，与 iPhone、iPad 实时同步，无需第三方云服务中转。

零外部网络依赖：所有操作均为本地系统调用（osascript/python3），无 API 密钥、无服务器通信，从根本上杜绝数据泄露和网络攻击风险。

安全设计周全：自动跳过密码保护笔记，输入严格校验（100KB 长度限制、类型检查），JSON 通过 stdin 传递避免命令行泄露，日志仅记录操作元数据而不含正文内容。

轻量化无依赖：除系统自带工具外零第三方依赖，供应链攻击面极小，MIT 开源许可保障代码可审计。

潜在缺点与局限性

平台独占性：仅限 macOS 系统，Windows/Linux 用户无法使用；需 Notes.app 处于可用状态，若应用被卸载或损坏则 Skill 失效。

功能边界严格：无法读取/修改密码保护笔记（安全特性但构成限制）；不支持富文本编辑器的完整功能（如手写、扫描件、复杂排版）；搜索仅支持标题匹配，不支持全文内容检索。

交互模式局限：依赖精确标题进行读取操作，用户必须准确记忆笔记命名；批量操作能力有限，缺乏标签系统、智能分类等高级管理功能。

无协作能力：仅操作个人本地笔记，不支持共享笔记的权限管理或多人协作编辑。

适合的目标群体

• Apple 生态深度用户：已全面使用 iCloud Notes 进行跨设备同步，希望在 AI Agent 中无缝调用笔记数据
• 效率工具整合者：需要将会议纪要、灵感碎片、待办事项自动归档至 Notes，构建统一的个人知识库
• 隐私敏感型用户：拒绝云端第三方笔记服务，要求数据完全本地化处理与存储
• 轻量级笔记管理者：不需要 Notion/Obsidian 的复杂功能，满足于原生备忘录的简洁体验

使用风险

本地敏感数据暴露：Skill 具备读取所有非加密笔记的权限，若 Agent 提示词被恶意构造，可能导致隐私笔记内容被诱导输出。建议为敏感主题笔记启用原生密码保护。

日志残留风险：操作日志记录笔记标题（可能包含敏感关键词），长期使用后日志文件可能积累可分析的隐私模式，需定期手动清理 logs/notes.log。

误操作覆盖：create-note 若使用已存在的标题，Notes.app 默认行为可能创建重复条目或产生混淆，建议建立命名规范（如带日期前缀）。

AppleScript 性能瓶颈：大规模笔记操作（如批量导入）可能受 Apple Events 性能限制，出现响应延迟；极端情况下 Notes.app 无响应会导致 Skill 阻塞。

账户配置依赖：若用户更改 iCloud 账户、关闭 Notes 同步或修改文件夹结构，Skill 的默认账户/文件夹假设可能失效，需重新执行 list-folders 适配。