QQ 邮箱验证码监听器

一个本地优先的 Windows 桌面小工具：监听 QQ 邮箱、Outlook 或 163 邮箱未读邮件，发现高置信验证码后自动复制到剪贴板。

能做到什么

• 通过 QQ 邮箱、Outlook/Hotmail/Live、163 邮箱或自定义 IMAP 拉取未读邮件。
• 支持配置多个邮箱账号，并一键检查全部已启用账号。
• 支持后台定时监听全部已启用账号。
• 在本机解析验证码，不上传邮件内容。
• 高置信验证码自动复制到系统剪贴板。
• 本地 SQLite 保存最近历史。
• 断网时仍可启动、查看历史、导入 .eml 文件并解析验证码。

重要边界

软件本体可以断网运行，但新邮件送达到电脑必须联网连接 QQ 邮箱服务器。断网时可用的能力是历史查看、剪贴板复制、导入已下载的 .eml 邮件和本地解析。

运行

$env:PYTHONPATH='src'
python -m qq_code_listener

开机自启动

在界面中勾选 开机自启动 并点击 保存设置 后，软件会在当前 Windows 用户的启动文件夹中创建 QQCodeListener.cmd。这个脚本只包含启动命令和 PYTHONPATH，不包含邮箱密码、授权码、OAuth token 或邮件内容。

取消勾选并保存会删除这个启动脚本。

账号默认会把授权码保存到 Windows 凭据管理器。保存成功后，开机自启动会自动从当前 Windows 用户的凭据管理器读取邮箱授权码或 Outlook refresh token，不需要重新输入授权码或重新完成 OAuth 登录。

如果你手动取消保存凭据，开机自启动只会自动打开软件并恢复账号列表，授权码/应用密码仍需要重新输入。

测试

$env:PYTHONPATH='src'
python -m unittest discover -s tests -v

邮箱设置

多邮箱同时检测

1. 点击 添加账号。
2. 为每个账号选择服务商，填写邮箱地址和当前服务商显示的登录信息。
3. 需要参与监听的账号保持 启用此账号 勾选。
4. 保存到 Windows 凭据管理器 默认已勾选；填写授权码后点击 保存设置、检查当前邮箱、检查全部邮箱 或 开始监听 都会自动保存凭据。
5. 点击 保存设置 保存账号列表。
6. 点击 检查当前邮箱 只检查当前选中账号。
7. 点击 检查全部邮箱 会按列表顺序检查所有已启用账号。
8. 点击 开始监听 后，软件会按 轮询间隔(秒) 自动检查全部已启用账号；点击 停止监听 可结束后台轮询。

某个邮箱登录失败或网络失败时，只会影响该邮箱，本轮仍会继续检查其他已启用邮箱。历史记录会显示验证码来源邮箱。

Outlook 如果使用 OAuth 登录，先选中对应 Outlook 账号并点击 Outlook OAuth 登录。登录成功后，本次窗口内的 检查全部邮箱 和 开始监听 会复用内存里的 OAuth token。默认会保存 Outlook refresh token，重启后自动刷新 access token。

取消勾选 保存到 Windows 凭据管理器 并保存，或删除账号，会删除该账号已保存的 Windows 凭据。

账号编辑区会根据服务商自动显示需要的字段：

• QQ 邮箱和 163 邮箱只显示授权码/客户端授权密码输入框。
• Outlook / Hotmail / Live 只显示 OAuth Client ID 和 Outlook OAuth 登录。
• 自定义 IMAP 显示授权码/应用密码、IMAP 主机和端口。
• 下方指引会随服务商变化，提示授权码或 OAuth 的获取方式。

QQ 邮箱

1. 打开 QQ 邮箱设置。
2. 开启 IMAP 服务。
3. 生成授权码。
4. 在本软件里填写 QQ 邮箱地址和授权码。

请使用 QQ 邮箱授权码，不要使用 QQ 密码。

Outlook / Hotmail / Live

1. 在服务商下拉框选择 Outlook / Hotmail / Live。
2. IMAP 主机会自动填为 outlook.office365.com，端口为 993。
3. 填写 Outlook 邮箱地址。
4. 填写 Azure 应用的 OAuth Client ID。
5. 点击 Outlook OAuth 登录，软件会打开 Microsoft 授权页面，并把设备验证码复制到剪贴板。
6. 在浏览器里粘贴设备验证码并完成授权。

Outlook OAuth 使用设备码登录和 IMAP XOAUTH2。桌面软件不需要保存 client secret，也不会把 access token 写入设置文件。长期登录态默认通过 Windows 凭据管理器保存 refresh token。

Azure 应用配置要求：

• 应用注册必须允许个人 Microsoft 账号，或使用适合该邮箱类型的账号范围。
• 在 Authentication 中启用移动和桌面/公共客户端流程，否则设备码登录会返回 The client application must be marked as 'mobile.'。
• API 权限需要允许 Outlook IMAP scope：IMAP.AccessAsUser.All。
• 本桌面软件不需要 client secret；如果曾经把 client secret 发给别人，建议在 Azure 中撤销并重新生成。

常见登录失败检查：

• 确认 Outlook 网页设置里已开启 IMAP。
• 确认使用的是 Microsoft 账号应用密码，不是普通登录密码。
• 如果应用密码返回 AUTHENTICATE failed，改用 Outlook OAuth 登录。
• 如果 OAuth 也失败，检查 Azure 应用是否允许个人 Microsoft 账号，并已授予 IMAP.AccessAsUser.All 权限。

163 邮箱

1. 在服务商下拉框选择 163 邮箱。
2. IMAP 主机会自动填为 imap.163.com，端口为 993。
3. 在 163 邮箱网页版设置中开启 IMAP/SMTP 服务。
4. 生成客户端授权密码。
5. 在软件里填写 163 邮箱地址和客户端授权密码。

请使用 163 的客户端授权密码，不要使用网页登录密码。

隐私

• 验证码提取完全在本机完成。
• 设置文件不保存授权码、应用密码、client secret、access token 或 refresh token。
• 默认会把授权码/应用密码或 Outlook refresh token 保存到当前 Windows 用户的凭据管理器；手动取消保存凭据后不会保存。
• 本地历史默认只保存邮件 ID、发件人、标题、片段、验证码和复制状态。
• 可以在界面中清空本地历史。