用途：该技能提供一组 Python 辅助脚本，封装 macOS 的 Contacts 框架，用于搜索、导出、审计和写入 Apple 通讯录。它可以在不打开通讯录应用的情况下读取整个地址簿，支持跨账户查看和合并关联卡片。
主要能力：
- 搜索联系人：可按姓名、昵称、公司、职位、邮箱、电话号码数字、群组、账户等字段查找，也支持查找缺少某字段的联系人。
- 导出：支持按群组或全部导出为 vCard 3.0 或 CSV，可包含备注和照片。
- 审计：检测重复联系人（按姓名+邮箱/电话等信号分级，支持模糊匹配），检查不完整卡片，并支持国际电话号码检查。
- 导入：从 CSV（兼容常见表头如 First Name/Last Name、Name、Email、Phone/Mobile、Company、Job Title、地址、生日、备注等，Google 和 Outlook 导出可用）或 vCard 导入联系人，可创建群组、指定账户，支持 --dry-run 预览。
- 写入：创建单个联系人，更新联系人（合并或替换字段），创建/管理群组，删除联系人（默认预览，需 --yes 确认）。
- 内置读回验证：写入后自动重新读取并比对，导出文件会重新解析计数，另有独立验证脚本可用于检查文件或群组。
使用方式：
- 脚本位于 scripts/ 目录，首次运行时会在 ~/Library/Caches/apple-contacts/ 下缓存编译好的 cn 工具。
- 常用命令示例：python3 $S/ct-search.py -q anna；ct-export.py --group "Running Club" --out club.vcf --out club.csv；ct-audit.py duplicates；ct-write.py import --csv people.csv --group "Club" --create-group --account "On My Mac" --dry-run；ct-write.py create --given Anna --family Nagy --email work:anna@acme.com --phone mobile:+36301234567。
- 群组和账户可用名称或 id 指定；联系人 id 通过 --format json 获取。
- 首次调用可能需要授予终端/IDE 通讯录访问权限；若拒绝，读取会回退到 AppleScript（无账户、关联卡片未合并），写入会停止并退出码 3。
适用场景：需要在本地批量搜索、导出、备份、去重、检查不完整联系人、从 CSV/vCard 导入、创建或更新联系人及群组的 macOS 用户。
限制与安全规则：
- 默认只读，仅当用户明确要求添加、修改或删除联系人或群组时才执行写操作。
- 不自动合并重复项，只报告重复组及置信度和原因，由用户决定；合并需用户明确要求。
- 写入时必须说明使用的账户（新联系人和群组按 --account、群组所在账户、系统默认顺序选择），联系人和所属群组必须同账户。
- 删除操作默认仅预览，需 --yes 才执行；删除群组不会删除成员。
- 联系人属个人数据，保持本地：不使用委托代理、Web 服务或上传，只输出用户需要的行。
- 每次调用为一次性进程并有超时；无后台运行或端口监听。退出码：2 输入错误或拒绝，3 无访问权限，4 读回或验证不匹配，124 超时。
- 已验证于 macOS 27.0.1 上的 Contacts 14.0。
- 联系人备注在框架中默认不可见，需通过 AppleScript 补充；保存带备注的联系人也有特定限制，详见参考文档。
参考文档：references/recipes.md 提供具体任务示例；references/contacts-api.md 说明联系人 JSON 字段、cn 命令和保存操作、AppleScript 字典；references/gotchas.md 说明权限、备注与保存限制、关联卡片、账户、标签、电话匹配和安全姿态。