wuzhou-communicator 0.1.5

Markdown email communicator for QQ Mail SMTP.

Auto Email Communicater

这是一个 Markdown 邮件通信器。发件邮箱、目标邮箱、默认标题都放在通讯器配置里；后续程序调用时只需要传入一个 .md 文件路径。

通讯器会读取 .md 的原始文本，并把它作为 text/markdown 邮件正文发送。不会把 .md 文件作为附件发送。

1. 获取 QQ 邮箱 SMTP 授权码

1. 登录发送方 QQ 邮箱网页版。
2. 点击 设置。
3. 进入 账户。
4. 找到 POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV 服务。
5. 开启 POP3/SMTP服务 或 IMAP/SMTP服务。
6. 按页面提示完成手机验证。
7. QQ 邮箱会生成一串 授权码。

这个授权码就是 Python 登录 SMTP 时使用的 code。它不是 QQ 密码。

2. 配置通讯器

复制 communicator.example.json 为 communicator.local.json：

{
  "sender": "[e-mail]",
  "recipients": [
    "[e-mail]"
  ],
  "subject": "自动任务通知",
  "auth_code": "你的SMTP授权码",
  "smtp_host": "smtp.qq.com",
  "smtp_port": 465,
  "use_ssl": true
}

当前版本只从 JSON 配置或命令行 --auth-code 读取授权码，不再读取环境变量。

3. 命令行发送

安装为本地 Python 工具

开发安装：

pip install -e .

直接从 PyPI 安装：

pip install wuzhou-communicator

构建 wheel：

python -m pip wheel . -w dist --no-deps

安装 wheel：

pip install .\dist\wuzhou_communicator-0.1.0-py3-none-any.whl

安装后会有两个命令：

wuzhou-mail --help
wuzhou-mail-gui
python -m wuzhou_communicator --help

GUI 可以配置发件邮箱、收件邮箱、授权码，并进行登录测试、测试邮件发送和 Markdown 发送测试。

CLI 使用

默认读取 Tools/communicator.local.json：

python .\Tools\email_communicator.py .\message.md

安装后也可以使用：

wuzhou-mail send .\message.md --config .\Tools\communicator.local.json

首次创建配置：

wuzhou-mail init --config .\Tools\communicator.local.json --sender [e-mail] --to [e-mail] --auth-code 你的SMTP授权码

只测试 SMTP 登录：

wuzhou-mail test --config .\Tools\communicator.local.json

发送测试邮件：

wuzhou-mail test --config .\Tools\communicator.local.json --send

只检查不发送：

python .\Tools\email_communicator.py .\message.md --dry-run

临时覆盖标题：

python .\Tools\email_communicator.py .\message.md --subject "训练结束"

使用 Markdown 第一个一级标题作为标题：

python .\Tools\email_communicator.py .\message.md --subject-from-h1

4. 在其他 Python 程序里调用

安装后推荐调用：

from wuzhou_communicator import send_markdown_file

send_markdown_file("message.md")

训练结束时调用：

from wuzhou_communicator import send_markdown_file

try:
    # train()
    send_markdown_file("reports/train_success.md")
except Exception:
    send_markdown_file("reports/train_failed.md")
    raise

如果配置文件不在默认位置：

from wuzhou_communicator import send_markdown_file

send_markdown_file(
    "reports/train_success.md",
    config_path="Tools/communicator.local.json",
)

5. Markdown 通信内容示例

# train_finished

status: success
run_id: exp_001
finished_at: 2026-05-01 14:30:00

## metrics

- accuracy: 0.982
- loss: 0.041

## artifacts

- report_path: reports/exp_001.html
- result_path: outputs/result.csv

6. Android 接收端

Android app 会通过 QQ IMAP 读取收件箱，缓存消息，并把新消息作为系统通知推送出来。消息详情页会渲染 Markdown，不直接展示原始 Markdown 标记。

首次打开会进入登录页，输入监听邮箱、该邮箱自己的 QQ 邮箱授权码，以及允许接收的发件邮箱。登录时会真实连接 imap.qq.com 并打开 INBOX，验证成功后才保存登录信息。

登录信息保存在 app 私有目录的 account.dat 文件中，内容经过 APK 内置算法 AES/GCM 加密，不以明文保存。退出登录会删除这个文件、清空缓存消息，并停止后台轮询。再次进入 app 会回到登录页。

默认不内置任何允许接收的发件邮箱。登录后需要进入独立的 账号管理 页面填写电脑上位机实际使用的发件邮箱；修改后会清空当前缓存并按新的发件邮箱重新监听。

构建 APK：

.\gradlew.bat assembleDebug

APK 输出位置：

app/build/outputs/apk/debug/app-debug.apk

安装后建议在系统设置里给 app 打开：

• 通知权限
• 自启动
• 后台运行
• 电池策略不限制

Android 系统限制后台长期常驻，当前实现使用 WorkManager 低功耗轮询，默认 15 分钟检查一次。打开 app 后可以在消息列表下拉刷新；下拉刷新会直接连接 IMAP 拉取最近 200 封邮件，比后台任务更适合立即验证。

消息列表支持：

• 未读消息红点
• 顶部未读数量
• 一键全部已读
• 右滑标记已读
• 左滑删除消息
• 点击消息查看渲染后的 Markdown

7. Android Studio Gradle Sources 报错

如果 Android Studio 报：

Unexpected exception while resolving Gradle distribution sources
Could not get resource 'https://services.gradle.org/distributions/gradle-8.13-src.zip'
Connection reset

这通常不是项目代码编译失败，而是 IDE 在下载 Gradle 源码包用于脚本补全/跳转时网络连接被重置。命令行 .\gradlew.bat assembleDebug 能成功就说明项目本身可以构建。

常用处理方式：

1. 在 Android Studio 里重新 Sync Project with Gradle Files。
2. 确认网络或代理能访问 services.gradle.org 和 GitHub release 下载地址。
3. 删除损坏缓存后重试：

Remove-Item -Recurse -Force "$env:USERPROFILE\.gradle\caches\modules-2\files-2.1\gradle"

4. 如果只是影响源码下载、不影响构建，可以暂时忽略。
5. 用命令行确认真实构建状态：

.\gradlew.bat assembleDebug