automating-contacts

用途

本技能用于自动化 macOS 通讯录（Contacts），主要面向 Contacts 相关的操作，包括查询、增删改查（CRUD）和群组管理。实现上以 JXA（JavaScript for Automation）为先，并借助 AppleScript 字典进行发现与验证。

与其他技能的关系

针对 Contacts 独立使用：用于 Contacts 专属操作（查询、CRUD、群组）。
复用 automating-mac-apps 的部分：TCC 权限设置、shell 命令辅助、UI 脚本回退方案以及 ObjC 桥接模式。
集成：当把 Contacts 自动化与更广泛的 macOS 脚本结合时，可同时加载这两个技能。
PyXA 安装：若要使用本技能中的 PyXA 示例，参见 automating-mac-apps 技能中的 PyXA 安装章节。

核心框架

Contacts 字典以 AppleScript 为先；在 AppleScript 中做发现，在 JXA 中实现。
对象说明符：读取用方法（name()、emails()），写入用赋值。
多值字段（emails、phones、addresses）是元素；使用构造器加 .push() 添加。
群组成员关系：用 add ... to 命令或 .people.push；需防御性处理重复项。
需要 TCC 权限：运行宿主必须拥有 Contacts 访问权限。

工作流（默认）

在脚本编辑器（Script Editor，JavaScript 视图）中查看 Contacts 字典。
用最小 AppleScript 做原型以验证动词；再以说明符读写移植到 JXA。
用 .whose 做粗过滤；必要时回退到混合方式（粗过滤加 JS 精炼）。
用 proxy 加 make 创建记录，然后赋原始值并 push 多值；用 Contacts.save() 持久化。
验证持久化：保存后检查 person.id() 是否存在；处理 TCC 权限错误。
创建联系人之后再管理群组；用存在性检查防止重复成员关系。
对于照片或桥接损坏的情况，使用 ObjC/剪贴板回退；对于重型查询，批量读取或预过滤。
测试操作：运行→检查结果→修复错误，循环迭代。

校验清单

已授予 Contacts 权限（系统设置 > 隐私与安全性 > 通讯录）
已在脚本编辑器中查看字典并验证动词
AppleScript 原型运行无错误
JXA 移植正确处理说明符
多值字段正确 push 到数组
创建群组前检查其是否存在
操作已保存并用 .id() 检查验证
所有操作都包裹了错误处理

快速上手（upsert 加群组）

代码示例（保持原样）：

const Contacts = Application("Contacts");
const email = "ada@example.com";
try {
  const existing = Contacts.people.whose({ emails: { value: { _equals: email } } })();
  const person = existing.length ? existing[0] : Contacts.Person().make();
  person.firstName = "Ada";
  person.lastName = "Lovelace";
  
  // Handle multi-value email
  const work = Contacts.Email({ label: "Work", value: email });
  person.emails.push(work);
  Contacts.save();
  
  // Handle groups with error checking
  let grp;
  try { 
    grp = Contacts.groups.byName("VIP"); 
    grp.name(); // Verify exists
  } catch (e) {
    grp = Contacts.Group().make(); 
    grp.name = "VIP";
  }
  Contacts.add(person, { to: grp });
  Contacts.save();
  console.log("Contact upserted successfully");
} catch (error) {
  console.error("Contacts operation failed:", error);
}

常见陷阱

TCC 权限：照片/附件需要 TCC 加辅助功能权限；被阻止时使用剪贴板回退。
无年份生日：无法干净地脚本化；使用完整日期。
高级触发器：将地理围栏委托给「快捷指令」（Shortcuts）应用。
重型查询：批量读取或预过滤以避免超时。

不适用场景

非 macOS 平台（使用平台特定 API）。
仅用简单 AppleScript 即可的方案（可跳过 JXA 的复杂度）。
iCloud 同步操作（使用原生 Contacts 框架）。
面向用户的应用（使用原生 Contacts 框架）。
跨平台通讯录管理（使用 CardDAV 或 vCard API）。

加载内容

JXA 基础与说明符：automating-contacts/references/contacts-basics.md
配方（查询、创建、多值、群组）：automating-contacts/references/contacts-recipes.md
高级（混合过滤、剪贴板图像、TCC、日期陷阱）：automating-contacts/references/contacts-advanced.md
字典与类型映射：automating-contacts/references/contacts-dictionary.md
PyXA API 参考（完整类/方法文档）：automating-contacts/references/contacts-pyxa-api-reference.md

技能介绍

用途

与其他技能的关系

核心框架

工作流（默认）

校验清单

快速上手（upsert 加群组）

常见陷阱

不适用场景

加载内容