macos-calendar

通过 AppleScript 创建、列出和管理 macOS 日历事件。当用户要求添加提醒、安排活动、创建日历条目、设置截止日期或涉及 macOS 上的 Apple 日历的任何内容时使用。触发“3 天后提醒我”、“添加到我的日历”、“安排下周一下午 2 点举行会议”、“创建每周定期活动”等请求。仅限 macOS。

# macOS Calendar

Manage Apple Calendar events via `$SKILL_DIR/scripts/calendar.sh`. All date handling uses relative math (`current date + N * days`) to avoid locale issues (FR/EN/DE date formats).

## Quick start

### List calendars

Always list calendars first to find the correct calendar name:

```bash
"$SKILL_DIR/scripts/calendar.sh" list-calendars
```

### Create an event

```bash
echo '<json>' | "$SKILL_DIR/scripts/calendar.sh" create-event
```

JSON fields:

| Field | Required | Default | Description |
|---|---|---|---|
| `summary` | yes | - | Event title |
| `calendar` | no | first calendar | Calendar name (from list-calendars) |
| `description` | no | "" | Event notes |
| `offset_days` | no | 0 | Days from today (0=today, 1=tomorrow, 7=next week) |
| `iso_date` | no | - | Absolute date `YYYY-MM-DD` (overrides offset_days) |
| `hour` | no | 9 | Start hour (0-23) |
| `minute` | no | 0 | Start minute (0-59) |
| `duration_minutes` | no | 30 | Duration |
| `alarm_minutes` | no | 0 | Alert N minutes before (0=no alarm) |
| `all_day` | no | false | All-day event |
| `recurrence` | no | - | iCal RRULE string. See [references/recurrence.md](references/recurrence.md) |

## Interpreting natural language

Map user requests to JSON fields:

| User says | JSON |
|---|---|
| "tomorrow at 2pm" | `offset_days: 1, hour: 14` |
| "in 3 days" | `offset_days: 3` |
| "next Monday at 10am" | Calculate offset_days from today to next Monday, `hour: 10` |
| "February 25 at 3:30pm" | `iso_date: "2026-02-25", hour: 15, minute: 30` |
| "every weekday at 9am" | `hour: 9, recurrence: "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"` |
| "remind me 1 hour before" | `alarm_minutes: 60` |
| "all day event on March 1" | `iso_date: "2026-03-01", all_day: true` |

For "next Monday", "next Friday" etc: compute the day offset using the current date. Use `date` command if needed:

```bash
# Days until next Monday (1=Monday)
target=1; today=$(date +%u); echo $(( (target - today + 7) % 7 ))
```


## Example prompts

These are real user prompts and the commands you should run:

**"Remind me to call the dentist in 2 days"**
```bash
"$SKILL_DIR/scripts/calendar.sh" list-calendars
```
Then:
```bash
echo '{"calendar":"Personnel","summary":"Call dentist","offset_days":2,"hour":9,"duration_minutes":15,"alarm_minutes":30}' | "$SKILL_DIR/scripts/calendar.sh" create-event
```

**"Schedule a team sync every Tuesday at 2pm with a 10-min reminder"**
```bash
echo '{"calendar":"Work","summary":"Team sync","hour":14,"duration_minutes":60,"recurrence":"FREQ=WEEKLY;BYDAY=TU","alarm_minutes":10}' | "$SKILL_DIR/scripts/calendar.sh" create-event
```

**"Block July 15 as a vacation day"**
```bash
echo '{"calendar":"Personnel","summary":"Vacances","iso_date":"2026-07-15","all_day":true}' | "$SKILL_DIR/scripts/calendar.sh" create-event
```

**"I have a doctor appointment next Thursday at 3:30pm, remind me 1 hour before"**
```bash
# First compute offset_days to next Thursday (4=Thursday)
target=4; today=$(date +%u); offset=$(( (target - today + 7) % 7 )); [ "$offset" -eq 0 ] && offset=7
```
Then:
```bash
echo "{\"calendar\":\"Personnel\",\"summary\":\"Doctor appointment\",\"offset_days\":$offset,\"hour\":15,\"minute\":30,\"duration_minutes\":60,\"alarm_minutes\":60}" | "$SKILL_DIR/scripts/calendar.sh" create-event
```

**"Set up a daily standup at 9am on weekdays for the next 4 weeks"**
```bash
echo '{"calendar":"Work","summary":"Daily standup","hour":9,"duration_minutes":15,"recurrence":"FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;COUNT=20"}' | "$SKILL_DIR/scripts/calendar.sh" create-event
```

**"Add a biweekly 1-on-1 with my manager on Fridays at 11am"**
```bash
echo '{"calendar":"Work","summary":"1-on-1 Manager","hour":11,"duration_minutes":30,"recurrence":"FREQ=WEEKLY;INTERVAL=2;BYDAY=FR","alarm_minutes":5}' | "$SKILL_DIR/scripts/calendar.sh" create-event
```

## Critical rules

1. **Always list calendars first** if the user hasn't specified one — calendars marked `[read-only]` cannot be used for event creation
2. **Never use hardcoded date strings** in AppleScript — always use `offset_days` or `iso_date`
3. **Confirm the calendar name** with the user if multiple personal calendars exist
4. **Never target a `[read-only]` calendar** — the script will reject it with an error
5. **For recurring events**, consult [references/recurrence.md](references/recurrence.md) for RRULE syntax
6. **Pass JSON via stdin** — never as a CLI argument (avoids leaking data in process list)
7. **All fields are validated** by the script (type coercion, range checks, format validation) — invalid input is rejected with an error message
8. **All actions are logged** to `logs/calendar.log` with timestamp, command, calendar, and summary

---

## 中文说明

# macOS 日历

通过 `$SKILL_DIR/scripts/calendar.sh` 管理 Apple 日历事件。所有日期处理均采用相对运算（`current date + N * days`），以避免本地化问题（FR/EN/DE 日期格式）。

## 快速开始

### 列出日历

务必先列出日历，以找到正确的日历名称：

```bash
"$SKILL_DIR/scripts/calendar.sh" list-calendars
```

### 创建事件

```bash
echo '<json>' | "$SKILL_DIR/scripts/calendar.sh" create-event
```

JSON 字段：

| 字段 | 必填 | 默认值 | 说明 |
|---|---|---|---|
| `summary` | 是 | - | 事件标题 |
| `calendar` | 否 | 第一个日历 | 日历名称（来自 list-calendars） |
| `description` | 否 | "" | 事件备注 |
| `offset_days` | 否 | 0 | 距今天的天数（0=今天，1=明天，7=下周） |
| `iso_date` | 否 | - | 绝对日期 `YYYY-MM-DD`（覆盖 offset_days） |
| `hour` | 否 | 9 | 开始小时（0-23） |
| `minute` | 否 | 0 | 开始分钟（0-59） |
| `duration_minutes` | 否 | 30 | 持续时长 |
| `alarm_minutes` | 否 | 0 | 提前 N 分钟提醒（0=无提醒） |
| `all_day` | 否 | false | 全天事件 |
| `recurrence` | 否 | - | iCal RRULE 字符串。参见 [references/recurrence.md](references/recurrence.md) |

## 解析自然语言

将用户请求映射到 JSON 字段：

| 用户表达 | JSON |
|---|---|
| "tomorrow at 2pm" | `offset_days: 1, hour: 14` |
| "in 3 days" | `offset_days: 3` |
| "next Monday at 10am" | 计算从今天到下周一的 offset_days，`hour: 10` |
| "February 25 at 3:30pm" | `iso_date: "2026-02-25", hour: 15, minute: 30` |
| "every weekday at 9am" | `hour: 9, recurrence: "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"` |
| "remind me 1 hour before" | `alarm_minutes: 60` |
| "all day event on March 1" | `iso_date: "2026-03-01", all_day: true` |

对于 "next Monday"、"next Friday" 等：使用当前日期计算天数偏移。如有需要可使用 `date` 命令：

```bash
# Days until next Monday (1=Monday)
target=1; today=$(date +%u); echo $(( (target - today + 7) % 7 ))
```


## 示例提示

以下是真实的用户提示以及你应运行的命令：

**"Remind me to call the dentist in 2 days"**
```bash
"$SKILL_DIR/scripts/calendar.sh" list-calendars
```
然后：
```bash
echo '{"calendar":"Personnel","summary":"Call dentist","offset_days":2,"hour":9,"duration_minutes":15,"alarm_minutes":30}' | "$SKILL_DIR/scripts/calendar.sh" create-event
```

**"Schedule a team sync every Tuesday at 2pm with a 10-min reminder"**
```bash
echo '{"calendar":"Work","summary":"Team sync","hour":14,"duration_minutes":60,"recurrence":"FREQ=WEEKLY;BYDAY=TU","alarm_minutes":10}' | "$SKILL_DIR/scripts/calendar.sh" create-event
```

**"Block July 15 as a vacation day"**
```bash
echo '{"calendar":"Personnel","summary":"Vacances","iso_date":"2026-07-15","all_day":true}' | "$SKILL_DIR/scripts/calendar.sh" create-event
```

**"I have a doctor appointment next Thursday at 3:30pm, remind me 1 hour before"**
```bash
# First compute offset_days to next Thursday (4=Thursday)
target=4; today=$(date +%u); offset=$(( (target - today + 7) % 7 )); [ "$offset" -eq 0 ] && offset=7
```
然后：
```bash
echo "{\"calendar\":\"Personnel\",\"summary\":\"Doctor appointment\",\"offset_days\":$offset,\"hour\":15,\"minute\":30,\"duration_minutes\":60,\"alarm_minutes\":60}" | "$SKILL_DIR/scripts/calendar.sh" create-event
```

**"Set up a daily standup at 9am on weekdays for the next 4 weeks"**
```bash
echo '{"calendar":"Work","summary":"Daily standup","hour":9,"duration_minutes":15,"recurrence":"FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;COUNT=20"}' | "$SKILL_DIR/scripts/calendar.sh" create-event
```

**"Add a biweekly 1-on-1 with my manager on Fridays at 11am"**
```bash
echo '{"calendar":"Work","summary":"1-on-1 Manager","hour":11,"duration_minutes":30,"recurrence":"FREQ=W