automating-reminders

用途

Automating Reminders 用于以编程方式自动化 macOS 的提醒事项（Apple Reminders）。它适合在需要“以编程方式创建提醒”“自动化提醒列表”或使用 JXA 操作 Reminders 时使用。该技能以 JXA 为主，同时通过 AppleScript 字典进行探索，并提供了 PyXA 与 PyObjC with Scripting Bridge 的示例。

主要能力

访问提醒列表：通过名称或 ID 获取列表，例如 app.lists.byName('Work')，并在列表不存在时回退到第一个可用列表。
读取与写入属性：使用 name()、id() 等方法读取属性，通过赋值写入。
过滤查询：使用 .whose 进行服务端过滤，例如按名称包含关键字或按日期比较（_lessThan/_greaterThan），以减少性能开销。
创建提醒：使用构造函数 Reminder({...}) 配合 .push() 添加，避免使用 make 导致的错误。可设置名称、正文、截止日期、提醒时间和优先级。
批量操作：在修改前收集 ID，然后批量更新或删除。
移动提醒：由于没有原生 move 命令，需将项目复制到新列表后删除原项目。
优先级映射：1 为高，5 为中，9 为低，0 为无。
多语言示例：提供 JXA、PyXA 和 PyObjC with Scripting Bridge 三种创建提醒的代码示例。

使用方式

确保已授予 Reminders 权限（权限设置参见 automating-mac-apps 技能）。
在 Script Editor 中切换到 JavaScript 视图，查看 Reminders 字典以了解可用属性。
按需加载参考文档：
- 基础：automating-reminders/references/reminders-basics.md（specifiers 与简单操作）
- 配方：automating-reminders/references/reminders-recipes.md（创建/查询/批量示例）
- 高级：automating-reminders/references/reminders-advanced.md（优先级、限制、调试）
- 字典：automating-reminders/references/reminders-dictionary.md（完整类型映射）
- PyXA API 参考：automating-reminders/references/reminders-pyxa-api-reference.md
使用 PyXA 示例前，需参考 automating-mac-apps 技能中的 PyXA 安装说明。

JXA 快速开始示例（创建提醒并设置提醒时间）：

try {
  const app = Application("Reminders");

  // Get list by name, or fall back to first available list
  let list;
  try {
    list = app.lists.byName("Reminders");
    list.name(); // Verify it exists
  } catch (e) {
    // Fall back to first available list
    const lists = app.lists();
    if (lists.length === 0) {
      throw new Error("No reminder lists found");
    }
    list = lists[0];
  }

  const r = app.Reminder({
    name: "Prepare deck",
    body: "Client review",
    dueDate: new Date(Date.now() + 3*86400*1000), // 3 days from now
    remindMeDate: new Date(Date.now() + 2*86400*1000), // Reminder 1 day before due
    priority: 1 // High priority
  });
  list.reminders.push(r);
  console.log("Reminder created in '" + list.name() + "'");
} catch (error) {
  console.error("Failed to create reminder: " + error.message);
  // Common errors: Permissions denied, list not found
}

PyXA 示例（推荐现代方式）：

import PyXA
from datetime import datetime, timedelta

try:
    reminders = PyXA.Reminders()

    # Get Inbox list
    inbox = reminders.lists().by_name("Inbox")

    # Create reminder with due date and reminder alert
    reminder = inbox.reminders().push({
        "name": "Prepare deck",
        "body": "Client review",
        "due_date": datetime.now() + timedelta(days=3),
        "remind_me_date": datetime.now() + timedelta(days=2),
        "priority": 1  # High priority
    })

    print("Reminder created successfully")

except Exception as error:
    print(f"Failed to create reminder: {error}")
    # Common errors: Permissions denied, Inbox list not found

PyObjC with Scripting Bridge 示例：

from ScriptingBridge import SBApplication
from Foundation import NSDate

try:
    reminders = SBApplication.applicationWithBundleIdentifier_("com.apple.Reminders")

    # Get Inbox list
    lists = reminders.lists()
    inbox = None
    for lst in lists:
        if lst.name() == "Inbox":
            inbox = lst
            break

    if inbox:
        # Create reminder
        reminder = reminders.classForScriptingClass_("reminder").alloc().init()
        reminder.setName_("Prepare deck")
        reminder.setBody_("Client review")

        # Set due date (3 days from now)
        due_date = NSDate.dateWithTimeIntervalSinceNow_(3 * 24 * 60 * 60)
        reminder.setDueDate_(due_date)

        # Set reminder date (2 days from now)
        remind_date = NSDate.dateWithTimeIntervalSinceNow_(2 * 24 * 60 * 60)
        reminder.setRemindMeDate_(remind_date)

        reminder.setPriority_(1)  # High priority

        # Add to inbox
        inbox.reminders().addObject_(reminder)

        print("Reminder created successfully")
    else:
        print("Inbox list not found")

except Exception as error:
    print(f"Failed to create reminder: {error}")

默认工作流：

发现：打开 Script Editor，在 JavaScript 模式下查看 Reminders 字典，了解可用属性。
定位列表：按名称或 ID 获取列表。
过滤：使用 .whose 查询，例如 reminders.whose({name: {_contains: 'meeting'}})；日期使用 _lessThan/_greaterThan。
创建：用 Reminder({...}) 构建，再通过 .push() 添加，避免错误。
批量操作：修改前收集 ID，批量更新/删除。
移动：复制项目到新列表，再删除原项目（无原生 move）。
高级功能：重复/位置提醒可调用 Shortcuts 或克隆模板项。

过滤逾期提醒示例：

const overdue = list.reminders.whose({dueDate: {_lessThan: new Date()}})();

适用场景

以编程方式创建提醒，并设置截止日期、提醒时间和优先级。
自动化提醒列表的查询、过滤、批量更新与删除。
在 macOS 上使用 JXA、PyXA 或 PyObjC 集成 Reminders。

限制与注意事项

权限错误：需在系统偏好设置 > 安全性与隐私中授予 Reminders 访问权限。
-10024 错误：使用构造函数 + push，而不是 make。
无效日期：赋值前需验证。
列表缺失：使用前用 app.lists.byName(name) 检查是否存在。
无原生移动命令：需复制后删除。
重复和基于位置的提醒脚本支持有限，需使用 Shortcuts。
不适用于跨平台任务管理（可用 Todoist API 等）、非 macOS 平台，或需要复杂重复模式、位置提醒编程设置的场景。

验证清单

实现 Reminders 自动化后：

确认已授予 Reminders 权限。
测试列表访问：app.lists().length > 0。
确认使用有效日期创建提醒。
检查提醒是否出现在 Reminders 界面中。
验证 .whose 查询返回预期结果。