Metadata-Version: 2.4
Name: wuzhou-communicator
Version: 0.1.5
Summary: Markdown email communicator for QQ Mail SMTP.
Author: Dawalishi
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/wuzhou-communicator/
Project-URL: Issues, https://pypi.org/project/wuzhou-communicator/
Keywords: email,markdown,smtp,qq-mail,cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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`：

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

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

## 3. 命令行发送

### 安装为本地 Python 工具

开发安装：

```powershell
pip install -e .
```

直接从 PyPI 安装：

```powershell
pip install wuzhou-communicator
```

构建 wheel：

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

安装 wheel：

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

安装后会有两个命令：

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

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

### CLI 使用

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

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

安装后也可以使用：

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

首次创建配置：

```powershell
wuzhou-mail init --config .\Tools\communicator.local.json --sender 123456789@qq.com --to 987654321@qq.com --auth-code 你的SMTP授权码
```

只测试 SMTP 登录：

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

发送测试邮件：

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

只检查不发送：

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

临时覆盖标题：

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

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

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

## 4. 在其他 Python 程序里调用

安装后推荐调用：

```python
from wuzhou_communicator import send_markdown_file

send_markdown_file("message.md")
```

训练结束时调用：

```python
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
```

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

```python
from wuzhou_communicator import send_markdown_file

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

## 5. Markdown 通信内容示例

```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：

```powershell
.\gradlew.bat assembleDebug
```

APK 输出位置：

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

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

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

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

消息列表支持：

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

## 7. Android Studio Gradle Sources 报错

如果 Android Studio 报：

```text
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. 删除损坏缓存后重试：

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

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

```powershell
.\gradlew.bat assembleDebug
```
