故障排查 FAQ 与术语表
遇到问题先别急着改配置。这一页把常见故障按「症状 → 怎么修」列清楚，照着排查通常几分钟就能解决。页尾还有几个进阶功能的说明，以及一份术语表——你在界面、日志或报错里撞见的词，这里都有人话解释。
macOS 打开时提示「已损坏，无法打开」或被拦截
Section titled “macOS 打开时提示「已损坏，无法打开」或被拦截”MailAgent 使用 Apple Developer ID 签名并经过公证，正常下载安装后不应出现这类提示。如果确实遇到，多半是下载过程不完整或下载工具清除了必要的标记：
- 删除已下载的
.dmg和已安装的MailAgent.app； - 用浏览器直接从 GitHub Releases 重新下载；
- 重新安装。
Windows 提示「Windows 已保护你的电脑」（SmartScreen）
Section titled “Windows 提示「Windows 已保护你的电脑」（SmartScreen）”这是预期提示（安装包目前没有代码签名），点 更多信息 → 仍要运行 即可，详见 安装桌面 App。
启动后长时间停留在初始化界面
Section titled “启动后长时间停留在初始化界面”大邮箱在版本升级后，数据库结构迁移可能需要一段时间，属正常现象——请等待完成，不要中途强制退出。如果长时间（超过几分钟）没有进展，可以退出重启一次；仍未恢复的，从设置里导出诊断包（见下方「怎么排查更深的问题」）附在反馈里。
macOS：Mail.app 自动化被拒 / 提示「自动化权限被拒」
Section titled “macOS：Mail.app 自动化被拒 / 提示「自动化权限被拒」”如果使用的是 AppleScript 后端（标已读、标旗、起草回复需要控制 Mail.app）：
- 打开 系统设置 → 隐私与安全性 → 自动化；
- 找到
MailAgent，勾上它下面的Mail。
如果列表里没有 MailAgent，先在 App 里对任意邮件触发一次需要自动化的操作（比如起草回复），触发权限请求后再回到上面的位置勾选。
macOS：完全磁盘访问未授权
Section titled “macOS：完全磁盘访问未授权”AppleScript 后端读取 Mail.app 自身的邮件数据需要这项权限：系统设置 → 隐私与安全性 → 完全磁盘访问权限 → +，把 MailAgent.app 加进去。改用 DavMail 后端则不需要这项权限。
Windows：Outlook 授权提示反复出现，或提示不支持
Section titled “Windows：Outlook 授权提示反复出现，或提示不支持”- 确认安装的是经典版 Outlook，不是新版「New Outlook」——新版没有自动化接口，本机 Outlook 后端无法使用。
- 首次运行时 Outlook 会弹出「有程序正尝试访问」的提示，选择 允许访问 并选最长时长；如果每次启动都重新弹出，检查是否选错了时长选项。
DavMail 连不上，或提示 token 过期
Section titled “DavMail 连不上，或提示 token 过期”参见 用 DavMail 接入企业邮箱 的「确认 DavMail 在跑」与「token 失效时怎么办」两节。设备被管理员移出租户会导致刷新令牌永久失效，需要重新走一遍交互认证。
AI 与 Notion
Section titled “AI 与 Notion”模型连接测试失败
Section titled “模型连接测试失败”进 设置 → AI → 模型服务，检查对应服务商的配置：
- API 地址（Base URL）是否正确，官方模板一般不需要改；
- API Key 是否过期或输入有误；
- 网络是否可以访问该服务商。
修正后重新点一次连接测试。
Notion 一键授权失败
Section titled “Notion 一键授权失败”常见原因和对应处理：
| 提示 | 处理 |
|---|---|
| 授权已取消 | 原有配置不受影响，重新点一次「连接 Notion」即可 |
| 5 分钟内没有完成授权 | 重新发起一次，尽快在弹出的浏览器里完成 |
| 本机端口被占用 | 关掉占用 9280 / 9281 端口的程序后重试 |
| 没找到数据库 | 重新授权时选择复制官方模板，或勾选包含邮件库、日历库的页面 |
也可以跳过一键授权，改用手填 Token 与数据库 ID 的方式；或者完全不接 Notion，同步、搜索、AI 分类都不受影响。
邮件迟迟没同步 / 界面看起来卡住
Section titled “邮件迟迟没同步 / 界面看起来卡住”先看后台服务是否在运行——重启一次 App 通常能恢复。如果长期不同步，检查网络与邮件后端（DavMail 是否在跑、Outlook 是否保持登录）。
历史邮件同步显示「只覆盖到某一天」
Section titled “历史邮件同步显示「只覆盖到某一天」”DavMail 模式下，IMAP 视图只保留最近一段时间的邮件（用于避免大邮箱同步拖慢），超出这个范围的历史邮件补不回来，界面会如实标注实际覆盖到哪一天，不会显示成完整成功。
有邮件进了「死信」队列
Section titled “有邮件进了「死信」队列”少数邮件多次同步失败后会被搁进死信队列，不再自动重试，以免反复失败拖累整体。系统会通过通知中心提醒你（进异常告一次，恢复后再告一次）。少量死信通常是个别邮件格式特殊或临时网络问题导致，从源码运行后端的开发者可以用命令行重试：
mailagent admin dead-letter listmailagent admin dead-letter retry <internal_id>怎么排查更深的问题
Section titled “怎么排查更深的问题”打包版 App 的用户：在设置里找到「诊断」区块，点 导出诊断包——会打包近 7 天的运行日志与脱敏后的配置快照，反馈问题时可以直接附上。
从源码运行后端的开发者，可以直接看日志文件：
tail -f ~/Documents/MailAgent/logs/sync.log # 从源码运行时的日志路径打包版 App 的日志在数据目录下的 logs/（~/Library/Application Support/mailagent-frontend/logs/，见 更新、升级与卸载 的「数据在哪里」）。
同步多个文件夹（仅 DavMail）
Section titled “同步多个文件夹（仅 DavMail）”默认 MailAgent 只同步收件箱和发件箱。如果你在 Exchange 里整理了自定义文件夹，可以在设置里把它们也纳入同步——被列入的文件夹和收件箱享受完全一样的待遇：AI 分类、Notion 同步、全文搜索、写操作都一样，且可以单独配置图标、是否推送通知、是否跑 AI 分类。
知识大脑（KOS）
Section titled “知识大脑（KOS）”KOS 是一个跨来源的知识库，把邮件语料、个人笔记、产品知识汇到一起，让 AI 回信或对话时能先查一下「已知什么」。这是一组默认关闭的进阶开关，需要先配好外部知识库的接入凭据；开启后最直观的变化是 AI 对话里的回答会带上具体的引用来源，而不是凭空给结论。缺凭据时它会静默不生效，不影响其他功能。
在界面、日志或报错里你可能撞见这些词，下面是人话版解释：
| 术语 | 大白话 |
|---|---|
| 本地优先 / SSoT（单一真实来源） | 数据「以谁为准」。MailAgent 以本机数据库为准，Notion 只是它的可选镜像。 |
| dead-letter（死信） | 多次同步失败、被暂时搁置不再自动重试的邮件，需要手动重试或等自愈。 |
| DavMail | 一个本地桥接程序，让 MailAgent 用标准协议（IMAP/SMTP/CalDAV）和 Exchange / Microsoft 365 通信。 |
| 本机 Outlook（outlook_com） | Windows 上直接驱动本机已登录的经典版 Outlook 读写邮件的后端，暂不支持日历。 |
| AppleScript 后端 | macOS 上直接驱动 Mail.app 读写邮件的后端，是零额外组件的默认路径。 |
| 审批卡 / approval card | Agent 请求执行某个写操作时弹出的确认卡片，是发送邮件、执行命令等操作的默认关卡。 |
| 能力卡 / capability card | 设置里按功能分组展示的一组工具与其审批档位（自动 / 询问 / 关闭）。 |
| FTS5 | 支撑全文搜索的检索引擎，覆盖邮件正文与附件文本。 |
| 跟进 Agent | 事项里的只读助手，定期检索证据后以「提案」形式给出更新建议，不会自己直接修改事项。 |
还没解决？到 GitHub Issues 反馈，附上导出的诊断包会更快定位。