Apple Contacts

核心用法

mac-contacts 是 macOS 原生通讯录（Contacts.app）的 CLI 封装，基于 CNContactStore 框架实现。它允许用户通过终端完成联系人查询、创建、更新、删除及分组管理，输出格式为 YAML，便于脚本解析。

主要子命令：

• search：跨字段模糊搜索（姓名、邮箱、电话、城市等），支持按列表过滤
• show：展示单个联系人的完整信息，包括所属分组
• create/update/delete：联系人增删改，支持多邮箱、多电话、地址等字段
• add_to_list/remove_from_list/list_groups：分组管理

安装要求： Python 3 + pyobjc-framework-Contacts + PyYAML，首次运行需在系统设置中授予终端通讯录访问权限。

显著优点

1. 原生集成：直接调用 macOS CNContactStore，读取时自动合并 iCloud/本地/Exchange 统一视图
2. 原子写入：所有写操作通过 CNSaveRequest 原子提交，避免数据损坏
3. 模糊匹配：电话搜索自动剥离非数字字符，支持 4 位以上数字片段匹配
4. 分组兼容：自动创建不存在的分组；移除分组成员时使用 osascript 绕过 iCloud 组的已知 API 缺陷

潜在缺点与局限性

• 笔记只读：因缺少 com.apple.developer.contacts.notes entitlement，无法写入联系人笔记字段
• 更新追加逻辑：update 对电话、邮箱、地址只能追加不能替换，需删除重建才能修改旧值
• 模糊匹配歧义：show 按姓名子串匹配，多个结果时仅返回第一个，可能误操作
• macOS 独占：完全依赖 Apple 私有框架，无跨平台可能

适合人群

• 习惯终端工作流的 macOS 高级用户
• 需要批量处理联系人、自动化通讯录维护的开发者/运维人员
• 编写个人效率脚本（如自动同步名片、按城市筛选客户）的技术用户

常规风险

• 隐私权限：工具需要完整通讯录读取权限，敏感数据可能通过终端输出泄露到日志或剪贴板
• 误删除风险：delete --force 无二次确认，脚本调用时需谨慎
• iCloud 同步延迟：写入后 Contacts.app 可能需数秒同步，连续操作需考虑延迟
• API 行为差异：iCloud 分组与本地分组在移除成员时行为不一致，依赖 AppleScript workaround 可能随系统更新失效