mac-notes-agent

与 macOS Notes 应用程序 (Apple Notes) 集成。 支持创建、列出、阅读、更新、删除和搜索笔记 通过桥接 AppleScript 的简单 Node.js CLI。

# Mac Notes Agent

## Overview

This skill lets the agent talk to **Apple Notes** on macOS using AppleScript
(via `osascript`). It is implemented as a small Node.js CLI:

```bash
node skills/mac-notes-agent/cli.js <command> [options]
```

> Requires macOS with the built-in **Notes** app and `osascript` available.

All operations target the **default Notes account**. Optionally you can specify
which folder to use.

---

## Commands

### 1) Add a new note

```bash
node skills/mac-notes-agent/cli.js add \
  --title "Meeting notes" \
  --body "First line\nSecond line\nThird line" \
  [--folder "Jarvis"]
```

- `--title` (required): Note title
- `--body` (required): Note body text. Use `
` for line breaks.
- `--folder` (optional): Folder name. If omitted, uses system default folder. If folder doesn't exist, it will be created.

> Line breaks (`
`) are converted to `<br>` tags internally for proper rendering in Notes.

**Result (JSON):**

```json
{
  "status": "ok",
  "id": "Jarvis::2026-02-09T08:40:00::Meeting notes",
  "title": "Meeting notes",
  "folder": "Jarvis"
}
```

---

### 2) List notes

```bash
node skills/mac-notes-agent/cli.js list [--folder "Jarvis"] [--limit 50]
```

- Lists notes in the given folder (or all folders if omitted).
- Output is JSON array with `title`, `folder`, `creationDate`, and synthetic `id`.

---

### 3) Read a note (get)

```bash
# By folder + title
node skills/mac-notes-agent/cli.js get \
  --folder "Jarvis" \
  --title "Meeting notes"

# By synthetic id
node skills/mac-notes-agent/cli.js get --id "Jarvis::2026-02-09T08:40:00::Meeting notes"
```

---

### 4) Update a note (replace body)

```bash
node skills/mac-notes-agent/cli.js update \
  --folder "Jarvis" \
  --title "Meeting notes" \
  --body "New content\nReplaces everything"
```

- Replaces the entire body of the matching note.
- Can also use `--id` for identification.

---

### 5) Append to a note

```bash
node skills/mac-notes-agent/cli.js append \
  --folder "Jarvis" \
  --title "Meeting notes" \
  --body "\n---\nAdditional notes here"
```

- Appends new content to the end of the existing note.

---

### 6) Delete a note

```bash
node skills/mac-notes-agent/cli.js delete \
  --folder "Jarvis" \
  --title "Meeting notes"
```

---

### 7) Search notes

```bash
node skills/mac-notes-agent/cli.js search \
  --query "keyword" \
  [--folder "Jarvis"] \
  [--limit 20]
```

- Searches note titles and bodies for the keyword.

---

## Identification Model

Apple Notes doesn't expose stable IDs. This CLI uses:

- Primary key: `(folderName, title)`
- Synthetic ID: `folderName::creationDate::title`

When multiple notes share the same title, the CLI operates on the most recently created one.

---

## Environment

- **macOS only**: Uses AppleScript via `osascript`
- **No npm dependencies**: Uses only Node.js built-ins (`child_process`)

---

## 中文说明

# Mac Notes Agent

## 概述

此技能让 agent 能够使用 AppleScript（通过 `osascript`）与 macOS 上的 **Apple Notes** 进行交互。它以一个小型 Node.js CLI 的形式实现：

```bash
node skills/mac-notes-agent/cli.js <command> [options]
```

> 需要 macOS，并具备内置的 **Notes** 应用程序以及可用的 `osascript`。

所有操作都针对**默认的 Notes 账户**。你也可以选择指定要使用的文件夹。

---

## 命令

### 1) 添加新笔记

```bash
node skills/mac-notes-agent/cli.js add \
  --title "Meeting notes" \
  --body "First line\nSecond line\nThird line" \
  [--folder "Jarvis"]
```

- `--title`（必填）：笔记标题
- `--body`（必填）：笔记正文文本。使用 `
` 表示换行。
- `--folder`（可选）：文件夹名称。如果省略，则使用系统默认文件夹。如果文件夹不存在，将会被创建。

> 换行符 (`
`) 会在内部被转换为 `<br>` 标签，以便在 Notes 中正确渲染。

**结果 (JSON):**

```json
{
  "status": "ok",
  "id": "Jarvis::2026-02-09T08:40:00::Meeting notes",
  "title": "Meeting notes",
  "folder": "Jarvis"
}
```

---

### 2) 列出笔记

```bash
node skills/mac-notes-agent/cli.js list [--folder "Jarvis"] [--limit 50]
```

- 列出指定文件夹中的笔记（如果省略则列出所有文件夹中的笔记）。
- 输出为 JSON 数组，包含 `title`、`folder`、`creationDate` 以及合成的 `id`。

---

### 3) 阅读笔记 (get)

```bash
# By folder + title
node skills/mac-notes-agent/cli.js get \
  --folder "Jarvis" \
  --title "Meeting notes"

# By synthetic id
node skills/mac-notes-agent/cli.js get --id "Jarvis::2026-02-09T08:40:00::Meeting notes"
```

---

### 4) 更新笔记（替换正文）

```bash
node skills/mac-notes-agent/cli.js update \
  --folder "Jarvis" \
  --title "Meeting notes" \
  --body "New content\nReplaces everything"
```

- 替换匹配笔记的整个正文。
- 也可以使用 `--id` 来标识。

---

### 5) 追加到笔记

```bash
node skills/mac-notes-agent/cli.js append \
  --folder "Jarvis" \
  --title "Meeting notes" \
  --body "\n---\nAdditional notes here"
```

- 将新内容追加到现有笔记的末尾。

---

### 6) 删除笔记

```bash
node skills/mac-notes-agent/cli.js delete \
  --folder "Jarvis" \
  --title "Meeting notes"
```

---

### 7) 搜索笔记

```bash
node skills/mac-notes-agent/cli.js search \
  --query "keyword" \
  [--folder "Jarvis"] \
  [--limit 20]
```

- 在笔记标题和正文中搜索关键词。

---

## 标识模型

Apple Notes 不提供稳定的 ID。此 CLI 使用：

- 主键：`(folderName, title)`
- 合成 ID：`folderName::creationDate::title`

当多个笔记共享同一标题时，CLI 会操作最近创建的那个。

---

## 环境

- **仅限 macOS**：通过 `osascript` 使用 AppleScript
- **无 npm 依赖**：仅使用 Node.js 内置模块 (`child_process`)