calendar-reminders

日历提醒管道：围绕 gcalcli（Google 日历）的配置驱动包装器以及通过 vdirsyncer+khal 的可选 CalDAV 源，以及为一次性 OpenClaw 提醒输出 JSON 计划的提醒计划程序。

# gcalcli calendar wrapper + reminder planner

This skill provides:
- `scripts/calendar` — wrapper around `gcalcli`
- `scripts/calendar_reminder_plan.py` — produces a JSON plan for reminder scheduling
- `references/openclaw-calendar.example.json` — example config format

## Config

Copy the example config to a private location and edit it:

- Default path: `~/.config/openclaw/calendar.json`
- Override with env: `OPENCLAW_CALENDAR_CONFIG=/path/to/calendar.json`

## Requirements

- Required: `python3`, `gcalcli`
- Optional (for CalDAV/iCloud): `vdirsyncer`, `khal`

## Security notes (why ClawHub may flag this)

This skill *invokes external binaries* and is config-driven.

- The planner runs `gcalcli`/`khal` using `subprocess.check_output([...], shell=False)` (argument-list form; safe against shell injection from event titles).
- If you wire a cron job to run `vdirsyncerSyncCommand`, make sure you run it as an **argv list** (`subprocess.run(cmd_list, shell=False)`), not as a shell string.
- Only point `gcalcliPath` / `khalBin` to **trusted binaries** (prefer absolute paths). Don’t run untrusted paths.

## Auth (Google)

`gcalcli` requires OAuth. On headless servers you may need SSH port-forwarding.
The wrapper uses `--noauth_local_server` to print instructions.

## Reminder planning

The planner outputs a JSON blob describing reminders to schedule. A separate cron job
(or an agent turn) can read it and create one-shot OpenClaw reminders.

Defaults:
- Ignore birthdays.
- Timed events are considered important.
- All-day events only trigger reminders if their title matches configured keywords.

## Wiring a daily reminder scheduler (OpenClaw)

Create a daily cron job (e.g. 00:05 local time) that:

1) If CalDAV is enabled in config, runs the configured `vdirsyncer` sync command.
2) Runs `scripts/calendar_reminder_plan.py` to get a JSON plan.
3) For each planned reminder, creates a one-shot OpenClaw `systemEvent` reminder at `reminderAtUtc`.
4) Writes a small state file so you don’t schedule duplicates.

(Our skill intentionally provides the wrapper + planner; scheduling is left to your cron/agent wiring.)

---

## 中文说明

# gcalcli 日历包装器 + 提醒计划程序

此技能提供：
- `scripts/calendar` — `gcalcli` 的包装器
- `scripts/calendar_reminder_plan.py` — 为提醒调度生成 JSON 计划
- `references/openclaw-calendar.example.json` — 示例配置格式

## 配置

将示例配置复制到一个私密位置并编辑它：

- 默认路径：`~/.config/openclaw/calendar.json`
- 用环境变量覆盖：`OPENCLAW_CALENDAR_CONFIG=/path/to/calendar.json`

## 依赖要求

- 必需：`python3`、`gcalcli`
- 可选（用于 CalDAV/iCloud）：`vdirsyncer`、`khal`

## 安全说明（为什么 ClawHub 可能会标记此技能）

此技能*调用外部二进制文件*并且是配置驱动的。

- 计划程序使用 `subprocess.check_output([...], shell=False)`（参数列表形式；可防止来自事件标题的 shell 注入）运行 `gcalcli`/`khal`。
- 如果你接入一个 cron 作业来运行 `vdirsyncerSyncCommand`，请确保将其作为 **argv 列表**（`subprocess.run(cmd_list, shell=False)`）运行，而不是作为 shell 字符串。
- 仅将 `gcalcliPath` / `khalBin` 指向**受信任的二进制文件**（优先使用绝对路径）。不要运行不受信任的路径。

## 身份验证（Google）

`gcalcli` 需要 OAuth。在无头服务器上，你可能需要 SSH 端口转发。
包装器使用 `--noauth_local_server` 来打印操作说明。

## 提醒计划

计划程序输出一个描述要调度的提醒的 JSON 数据块。一个单独的 cron 作业
（或一个代理回合）可以读取它并创建一次性的 OpenClaw 提醒。

默认设置：
- 忽略生日。
- 定时事件被视为重要。
- 全天事件仅在其标题匹配配置的关键词时才触发提醒。

## 接入每日提醒调度程序（OpenClaw）

创建一个每日 cron 作业（例如本地时间 00:05），它会：

1) 如果配置中启用了 CalDAV，则运行配置的 `vdirsyncer` 同步命令。
2) 运行 `scripts/calendar_reminder_plan.py` 以获取 JSON 计划。
3) 对于每个计划好的提醒，在 `reminderAtUtc` 创建一个一次性的 OpenClaw `systemEvent` 提醒。
4) 写入一个小型状态文件，这样你就不会调度重复项。

（我们的技能有意提供包装器 + 计划程序；调度则留给你的 cron/代理接入。）