目录
目录来源 (Directory source) 是 MacroSIP 按姓名或号码查找人员的地方：您公司的 LDAP 服务器、某个 URL 上的 CSV 或 JSON 文件、您的 Google 通讯录，或 macOS 通讯录应用。结果在您输入时出现在号码栏中，用于为来电者命名，并可导入到联系人中。对应面板是设置 › 目录 (Directory)。
来源
在设置 › 目录中用 + 添加。添加目录来源 (Add Directory Source) 表单包含类型 (Type) 弹出式菜单、名称 (Name)、按类型不同的字段，以及结果 (Results) 选项（见下文）。测试 (Test) 检查连接并回答“已连接 · 184 个条目”。
| 类型 | 字段与行为 |
|---|---|
| LDAP | 服务器 (Server)（ldap://ldap.example.com 或 ldaps://…；“尽可能使用 ldaps:// 或 StartTLS。”）、使用 StartTLS (Use StartTLS) 开关（ldaps 时忽略）、Base DN、Bind DN（“留空为匿名搜索。”）、密码 (Password)（“存储在钥匙串中。”）、搜索过滤器 (Search filter)（默认 (|(cn=*%s*)(telephoneNumber=*%s*))；“%s 是输入的文本。”）。 |
| URL（CSV 或 JSON） (URL (CSV or JSON)) | URL（http、https 或 file）、格式 (Format) CSV / JSON（在您修改前根据扩展名猜测）、刷新间隔 (Refresh every) 每小时 / 每 6 小时 / 每天 / 每周。CSV 需要标题行；分隔符可为逗号、分号或制表符；编码为 UTF-8 或 Windows-1251。JSON 是一个对象数组（或包含该数组的对象）。可识别的列：name、first name、last name、number / phone / telephone / extension、mobile / cell、email / mail、organization / company（忽略大小写、空格、_ 和 -）。没有号码的行会被跳过。 |
| macOS 通讯录 (macOS Contacts) | 没有字段。来源命名为“macOS Contacts”并显示“This Mac”。允许访问 (Allow access) 触发系统的通讯录权限提示（“当您从号码栏搜索时，MacroSIP 会在通讯录中查找姓名和号码。”）；启动时不会询问。如果拒绝，状态显示“访问被拒绝”并提供打开系统设置… (Open System Settings…)。 |
| Google 通讯录 (Google Contacts) | 使用 Google 登录 (Sign in with Google)：“在浏览器中打开 Google 一次，以允许对您的通讯录进行只读访问。MacroSIP 只保留访问令牌，存储在钥匙串中；您可以随时在 Google 账号中撤销访问权限。”浏览器显示 Google 的授权页面；同时按钮被替换为“正在等待 Google…”，关闭表单会放弃登录。Google 返回应用后，Google 账号 (Google account) 行显示您的电子邮件和一个绿色勾号，添加 (Add) 存储该来源（状态“已连接”）。此后它与其他来源一样被搜索、导入和用于查询来电者姓名；结果行带有 Google 标记。没有 Google 客户端 ID 的构建会回答“此构建未配置 Google 登录”。 |
来源列表显示来源（名称、地址、“仅搜索”或“导入到联系人”）、状态和一个开 (On) 开关。“结果按此顺序列出；拖移可重新排序。已关闭的来源不会被搜索也不会同步。”− 询问“移除‘Head office LDAP’？”——“已从此来源导入的联系人仍保留在联系人中。”
退出 Google 通讯录登录就是用 − 移除该来源：访问令牌随之从钥匙串中删除，已导入的名片保留。也可以在 Google 账号中撤销访问权限；来源随后显示需要登录 (Sign in required)，面板提供登录… (Sign In…)（“访问已过期或被撤销”——“在您重新登录之前，搜索会跳过此来源。”），它会再次打开浏览器。
仅搜索或导入到联系人
每个来源是以下两者之一：
- 仅搜索 (Search only) — “结果不会被存储”。条目出现在号码栏和来电者查询中，不写入任何内容。
- 导入到联系人 (Import into Contacts) — “复制并每天刷新”。每个条目都成为一张联系人名片。URL 来源按自己的间隔刷新；其他来源每天一次，macOS 通讯录仅在已授予访问权限时刷新。
号码栏中的建议
开启从号码栏搜索目录 (Search directories from the number field) 后，在号码栏中输入会显示联系人 (Contacts) 部分（您自己的名片优先）和按来源顺序列出结果的目录 (Directory) 部分。每行显示头像、匹配字母加粗的姓名、号码和来源标记（LDAP、URL、Contacts、Google）。带旋转指示器的“正在搜索 Head office LDAP…”表示尚未应答的来源；搜索在 3 秒后停止等待。所有来源都应答后，列表以“来自 2 个来源的 7 个结果”结束。已在联系人中的号码只显示一次，作为本地联系人。
设置：最少字符数 (Minimum characters)（1–5，默认 2；“输入达到此字符数并停顿 300 ms 后开始搜索。”）和每个来源的结果数 (Results per source)（1–10，默认 5）。纯数字文本同样会被搜索。
点按一行将其号码放入号码栏；在高亮的行上按 Return 呼叫它；Esc 关闭列表，再按一次 Esc 清空号码栏。右键菜单提供呼叫 (Call)、拷贝号码 (Copy Number) 和添加到联系人 (Add to Contacts)（创建一张您自己的名片）。
来电者查询
查询来电者姓名 (Look up names of incoming callers)（默认开启）：“在来电响铃期间向仅搜索的来源查询最多 1 秒。”已导入的来源已在联系人中，在本地匹配。号码按数字比较，因此 +1 202 555-0123 和 2025550123 是同一行。SIP 显示名称为空或只是号码时使用目录中的姓名，并存入通话记录条目。
立即导入与计划
对于设置为导入的来源，状态列显示立即导入 (Import now)（运行时为“正在导入…”）。结果以列表下方的横幅显示十秒：“已导入 120 位联系人（14 位已更新）”、“没有可导入的内容”或“导入失败：无法连接到 ldap.example.com”。导入失败不会禁用按钮或计划；“5 分钟前同步”显示的是上次成功的时间。
合并规则
- 条目按号码与现有联系人匹配，绝不重复。
- 由同一来源创建的名片在每次导入时跟随目录：姓名、组织、电子邮件和照片被替换，缺少的号码被添加。
- 您自己创建或编辑过的名片保留其姓名、照片和其余内容；它只接收自己缺少的部分（空的组织或电子邮件、缺失的照片、新号码）。
- 备注、个人收藏和首选账户绝不会被改动。
- 新名片会获得备注“从 Head office LDAP 导入”。
状态
| 状态 | 含义 |
|---|---|
| 已连接 (Connected) | 测试或上次搜索成功。 |
| 5 分钟前同步 (Synced 5 min. ago) | 上次成功导入（URL 来源：上次获取）。 |
| 需要登录 (Sign in required) | 没有令牌或访问权限已被 Google 撤销的 Google 通讯录；在您按**登录…**并在浏览器中完成登录之前，该来源会被跳过。 |
| 访问被拒绝 (Access denied) | macOS 拒绝了通讯录访问；请在系统设置 › 隐私与安全性 › 通讯录中允许 MacroSIP。 |
| 关 (Off) | “开”开关已关闭。 |
| 错误文本 | “已超时”、“无法连接到 ldap.example.com”、“Bind DN 或密码无效”、“HTTP 404”、“标题行中没有号码列”、“文件不是有效的 JSON”、“JSON 中没有联系人数组”、“服务器必须为 ldap://host 或 ldaps://host”、“此构建未配置 Google 登录”。失败的来源会被跳过 60 秒，然后重试。 |