apple-notes

apple-notes — 通过 AppleScript 在本地管理 Apple Notes

通过 macOS 上的 Notes.app 操作用户真实的 Apple Notes。Apple 从未为 Notes 提供云 API，因此无需进行 OAuth 授权，也无需注入令牌——此技能在用户自己的 Mac 上运行，并通过 AppleScript（osascript）与 Notes.app 通信。它适用于在 macOS 上运行的各种 Agent：AceDataCloud 桌面应用（可在用户的 Mac 上执行本地工具／本地 MCP）、macOS 上的 Claude Code，或用户 Mac 上的 CodingBridge 节点。

frontmatter 中的 surfaces: [mac] 表示此技能仅适用于 macOS 桌面端——无法在 Web／iOS／Android／Windows 界面上运行（这些平台没有本地 Notes.app）。技能／连接器目录 UI 会读取此信息，为卡片添加「macOS 桌面端」标记，并引导用户从 macOS 桌面应用安装。若未设置 surfaces，则默认该技能在所有平台均可用。

此技能附带 scripts/notes.py——这是一个独立脚本，仅使用 Python 标准库（通过 shell 调用 osascript；无需 pip install，也无需 brew）。动态值通过环境变量传递，绝不会插入 AppleScript 源码，因此笔记内容不会破坏脚本或注入命令。

要求

• macOS 和 Notes 应用。需要 python3（系统自带的 Python 即可）。
• 自动化权限。 首次调用时，macOS 会显示提示：「终端想要控制 Notes。」 请批准，或在 系统设置 › 隐私与安全性 › 自动化 ›（你的终端／Agent）› Notes 中启用权限。若出现授权错误，CLI 会准确告知用户如何处理——不要循环重试。
• 引用 Notes 时，应用会在后台启动（不会强制打开窗口）。

NOTES="${SKILL_DIR:-.}/scripts/notes.py"   # run from this skill's directory
python3 "$NOTES" folders                    # smoke-test the connection

命令

命令	读／写	用途
folders	读	列出文件夹及笔记数量
list [--folder F] [--limit N]	读	列出笔记（按时间从新到旧）：ID、标题、文件夹、日期
search QUERY [--folder F] [--limit N]	读	在标题和正文中进行不区分大小写的子串匹配
view NOTE_ID [--format json|text|html]	读	显示一条笔记（元数据和正文）
export NOTE_ID [--format md|html|text] [-o FILE]	读	将一条笔记导出为 Markdown／HTML／文本
create --title T [--body B | --body-file F] [--folder F]	写	创建笔记
append NOTE_ID [--body B | --body-file F]	写	在现有笔记后追加文本
move NOTE_ID --folder F	写	将笔记移至其他文件夹
new-folder NAME	写	创建文件夹
delete NOTE_ID	写	将笔记移至最近删除（可恢复）

大多数命令会输出 JSON（错误始终以 JSON 格式输出：{"error": ...}）。例外情况是会将原始笔记内容输出到 stdout 的命令：view --format text|html，以及未指定 -o 的 export。NOTE_ID 是由 list／search 返回的不透明 x-coredata://… ID——务必先获取最新 ID；不要猜测。

读取示例

python3 "$NOTES" folders
python3 "$NOTES" list --limit 20
python3 "$NOTES" list --folder "Work" --limit 50
python3 "$NOTES" search "invoice" --limit 20
python3 "$NOTES" view "x-coredata://…/p42"
python3 "$NOTES" export "x-coredata://…/p42" --format md -o note.md

写入操作受限（除非末尾附加 --confirm，否则执行试运行）

create、append、move、new-folder 和 delete 会更改用户的真实笔记。末尾没有 --confirm 时，这些命令只会试运行并打印将要执行的操作。仅当 --confirm 是最后一个参数时才会生效。务必先展示试运行结果，获得明确的「是」，然后再附加 --confirm 重新运行。

# Create — dry-run, then confirm
python3 "$NOTES" create --title "Groceries" --body "milk\neggs"                # preview
python3 "$NOTES" create --title "Groceries" --body "milk\neggs" --confirm      # writes

# Create in a folder, body from a file
python3 "$NOTES" create --title "Spec" --body-file draft.md --folder "Work" --confirm

# Append to an existing note
python3 "$NOTES" append "x-coredata://…/p42" --body "one more line" --confirm

# Move / organize
python3 "$NOTES" new-folder "Archive" --confirm
python3 "$NOTES" move "x-coredata://…/p42" --folder "Archive" --confirm

# Delete → goes to Recently Deleted (recoverable ~30 days)
python3 "$NOTES" delete "x-coredata://…/p42" --confirm

内容会被视为纯文本（每一行都会成为一个段落；--title 是笔记的第一行，Notes 会将其显示为标题）。输入中的 HTML 会经过转义，因此无法注入标记。可在 --body 中使用 \n 表示换行，或通过 --body-file 传入文件。

注意事项

• 这是用户的真实 Notes 账户。 写入前请先确认。
• list 会扫描整个资料库——对于大型账户，可能需要几秒钟。使用 --folder 缩小范围，并用 --limit 限制结果数量（默认值为 50）。search 会在 Notes 中筛选，速度更快。
• **附件／图像：**包含图像或附件的笔记可以读取并导出为文本，但 append 可能无法保留嵌入的附件——请避免在此处编辑含附件的笔记，改为在 Notes 中打开。
• 导出 → Markdown 会转换 Notes 中常见的格式（标题、粗体／斜体、列表、链接、换行）。富媒体对象（表格、绘图、扫描文档）会降级为纯文本。
• move 仅限在同一账户内移动（例如 iCloud）。跨账户移动会失败。
• 切勿假定 NOTE_ID——ID 因存储位置而异；请务必先从 list／search 获取。
• 如果持续出现授权错误，说明缺少 Automation 权限——请告知用户授予该权限（参见 Requirements），然后停止；不要循环重试。