Buddy加油站签到通知套件
帮用户部署纯本机的全自动签到通知链路：本机定时签到 → 取积分 → 组装文案 → 本机 SMTP 直发邮件。
整个链路 100% 在本机闭环，不依赖云端沙箱、不依赖第三方收集端点、不需要注册任何服务。用户只需准备一个邮箱。
3 分钟速通（只想快点装好？看这里）
① 装 Node.js ≥ 20 和 Python 3 （约 1 分钟，官网下载）
② 邮箱开 SMTP、拿授权码 （约 1 分钟，163/QQ 设置页）
③ 建 ~/.email_notify/config.json 填邮箱和授权码
④ 跑一次安装脚本，看到 [6] 邮件通知已发送 ✅ → 完成
具体的命令与路径在下方「部署四步」。只有第 ②③ 步需要你动手填内容，其余都是照抄命令。
> 遇到问题不用从头读文档：直接翻 references/troubleshooting.md，它是按"现象 → 原因 → 怎么办"组织的，可以当查询手册用。
> v1.1.0 是本套件的一次架构级重写：通知链路从「云端代发」整体前移到本机。变更原因与完整复盘见下方《为什么有 v1.1.0》。如果你是从旧版升级，请务必读这一节。
架构
用户本机（Windows / macOS / Linux） ← 全部流程都在这里
┌──────────────────────────────────────────────┐
│ 计划任务 07:00 │
│ └ wb-daily.py │
│ ├ 1. 读登录态（toolkit / decrypt-token.js）│
│ ├ 2. 查签到前积分 │
│ ├ 3. 执行签到（幂等） │
│ ├ 4. 查签到后积分 │
│ ├ 5. 组装结果文案 │
│ ├ 6. 本机 SMTP 直发邮件 ← 通知在这 │
│ └ 7. 写本机日志 logs/checkin-*.log │
└──────────────────────────────────────────────┘
没有云端环节。 沙箱是否重置、网络端点是否失效，都与本链路无关。
为什么有 v1.1.x（必读）
v1.1.1 变更摘要
补强可靠性，针对反馈中「网络波动时不会重试」的问题：
| # | 变更 |
|---|---|
| 1 | 邮件失败自动重试：网络类失败重试 2 次（间隔 30s / 60s）；认证类失败不重试（重试无意义） |
| 2 | 错误分类诊断：把底层异常翻译成「原因 + 处理建议」，直接告诉用户该改什么 |
| 3 | 失败兜底告警：邮件最终失败时，写 NOTIFY_FAILED.txt 到签到包根目录，并写一份到桌面 |
| 4 | Windows 补上重试层：新增 run-wb-daily.ps1，与 macOS/Linux 的 run-wb-daily.sh 对齐 |
> 完整变更历史与 v1.0.0 架构故障复盘见 references/changelog.md。
v1.1.0 架构摘要（一句话）
通知链路从「云端代发」整体重写为「本机直发邮件」，并移除依赖云端的项目留言。原因是旧架构把不可再生凭据放在了会被重置的沙箱磁盘上，导致 2026-10 一次真实故障中通知静默中断 4 天。新版不依赖任何云端服务，沙箱重置对本链路零影响。
> 详细复盘（含根因分析、四条通用教训）见 references/changelog.md——如果你是从旧版升级，建议读一遍。
部署四步
Step 0 · 前提与三个问题
前提检查（缺一不可）：
| 依赖 | 说明 |
|---|---|
| WorkBuddy 桌面端已登录 | 提供本地登录态；必须登录过至少一次 |
| Node.js ≥ 20 | v5.3.8+ 明文登录态用纯 Node 读取 |
| Python 3 | 计划任务直接跑 wb-daily.py |
| 一个可发信的邮箱 | 如 163 / QQ 邮箱，需开启 SMTP 并生成授权码 |
旧版 WorkBuddy/CodeBuddy（state.vscdb）账户另需 Electron，见 workbuddy-checkin skill。
先问用户三件事：
- 本机操作系统（Windows / macOS / Linux）？
- 希望每天几点签到？（默认 07:00）
- 用来收通知的邮箱是哪个？发件邮箱用哪家（163 / QQ / 其他）？
> 平台分支（重要）：确认用户为 macOS 后，必须接着读 references/platform-macos.md（插电才能稳定唤醒、TCC 隐私授权弹窗、launchd 命令、依赖差异）。Windows 与 Linux 无需读该文件。
Step 1 · 部署签到套件到本机
- 把
assets/checkin-kit/整个目录复制到用户可见位置（如/workspace/checkin-kit/），让用户下载到本机任意目录； - 用户在包内把
config.env.txt复制为config.env； - 安装调度：
- Windows（管理员 PowerShell）：
powershell -ExecutionPolicy Bypass -File scheduler\setup-daily-checkin.ps1
它会：清除旧 WorkBuddy 任务 → 注册每天CHECKIN_TIME（默认 07:00）单任务（WakeToRun 睡眠唤醒 + StartWhenAvailable）→ 任务动作指向run-wb-daily.ps1包装层（提供网络类失败自动重试，v1.1.1 新增）；
- macOS（先读references/platform-macos.md）：
bash scheduler/install.sh。三个必知差异：① 必须插电，电池供电时 Wake 唤醒会被电源策略抑制；② 首次运行可能出现隐私授权弹窗（钥匙串/磁盘访问），需用户点同意；③ Node.js ≥ 20 必须装；
- Linux：同上bash scheduler/install.sh（systemd user timer + WakeSystem）。
> v1.1.0 起 config.env 中的 REPORT_URL / COLLECT_TOKEN 保持留空（纯本机模式）。旧版会引导用户去 Svix Play 注册端点——这一步已不再需要，请勿再引导用户注册任何第三方服务。
Step 2 · 配置邮件通知
这是本套件的核心环节，通知能否到达全靠这一步。
- 生成 SMTP 授权码（只有用户能做）：
- 163：登录邮箱网页版 → 设置 → POP3/SMTP/IMAP → 开启 SMTP 服务 → 新增授权码
- QQ：设置 → 账户 → POP3/IMAP/SMTP 服务 → 开启 → 生成授权码
- ⚠️ 授权码不是邮箱登录密码，是单独生成的一串字符 - 写配置文件到固定位置（注意开头有个点）：
- Windows：C:\Users\<用户名>\.email_notify\config.json
- macOS / Linux：~/.email_notify/config.json
- 模板见assets/checkin-kit/email_notify.config.json.txt - 填入内容（英文双引号，保留引号）：
{
"smtp_host": "smtp.163.com",
"smtp_port": 465,
"username": "你的邮箱@163.com",
"auth_code": "粘贴授权码",
"from_name": "Buddy加油站",
"to_addr": "收件邮箱（可与发件相同）"
}
常见 smtp_host：163 → smtp.163.com，QQ → smtp.qq.com，Gmail → smtp.gmail.com（端口均 465 SSL）。
> 安全：授权码只存本机，不进沙箱、不进留言、不写日志。配置文件建议设 600 权限（macOS/Linux：chmod 600 ~/.email_notify/config.json）。用户可随时在邮箱后台撤销授权码。
Step 3 · 验证
手动跑一次完整流程：
# Windows
python "<签到包>\scripts\wb-daily.py"
# macOS / Linux
python3 <签到包>/scripts/wb-daily.py
成功时应看到：
[1] 签到前: total_credits=900 streak=9
[2] 签到退出码=0
[5] REPORT_URL 未配置，跳过云端上报（纯本地模式）
[6] 邮件通知已发送 ✅
END
然后让用户去邮箱确认收到（首次建议提醒查看垃圾箱并标记「非垃圾邮件」）。
只想验登录态、不真签到：python wb-daily.py --dry-run
Step 4 · 验证清单
| # | 验证点 | 方法 |
|---|---|---|
| 1 | 登录态可读 | wb-daily.py --dry-run 能输出积分 |
| 2 | 签到成功 | 完整跑一次，输出 [2] 签到退出码=0 |
| 3 | 邮件已发送 | 输出 [6] 邮件通知已发送 ✅ |
| 4 | 邮件已收到 | 用户邮箱里能看到（含垃圾箱检查） |
| 5 | 计划任务正确 | Windows：schtasks /query /tn WorkBuddyDailyCheckin /v /fo LIST；看「下次运行时间」是否正确 |
全部通过后向用户汇报：签到时间、邮件到达时间、以及静默规则（签到失败或邮件失败时不会有邮件，需自行查看本机日志）。
排错
完整的故障对照表见 references/troubleshooting.md。最高频的三个：
| 现象 | 原因 | 处理 |
|---|---|---|
[6] 邮件未启用（...不存在），跳过 |
配置文件路径/名字不对 | 确认是 ~/.email_notify/config.json，注意开头的点 |
[6] 邮件通知失败: EMAIL_FAIL ... |
授权码错 / SMTP 没开 | 核对授权码；确认邮箱里 SMTP 服务已开启 |
完全看不到 [6] 行 |
wb-daily.py 没被替换成新版 |
检查文件时间戳 |
记住：以上任何一种情况，签到本身都已经完成了，积分不受影响。
安全红线
- SMTP 授权码只存用户本机
~/.email_notify/config.json，不进沙箱、不进留言、不写日志、不在汇报中回显；用户可随时撤销。 - 登录态令牌只在本机内存流转：不落盘、不进日志、不上传任何端点（内核脚本已按此实现）。
- 本套件不引导用户注册任何第三方服务，无任何外发数据。
- 不要把含个人信息的
config.env提交到公共仓库。
已知限制（要提前告知用户）
- 彻底关机 = 当天漏签：睡眠可被唤醒，硬关机无法唤醒（硬件限制）。漏签次日连签中断。
- 邮件可能进垃圾箱：首次收到后建议标记「非垃圾邮件」。
- 通知只在签到流程跑过之后才发：若当天电脑全程关机，当天不会有邮件。
- 积分/连签天数来自官方
checkin-activity-status接口，语义以服务端为准（实测见过服务端重置连签/积分的情况，属正常现象，脚本只如实转发）。
参考资料（按需读取，不必通读）
| 文件 | 何时读 |
|---|---|
references/platform-macos.md |
用户本机是 macOS 时必读：插电唤醒、TCC 授权、launchd 命令、依赖差异、快速验证清单 |
references/troubleshooting.md |
遇到故障时读：按「现象→原因→怎么办」组织，可当查询手册。邮件分类码排查表在第 1.1 节 |
references/architecture.md |
需要理解数据流、双路径容错、邮件开关机制、架构决策时读 |
references/changelog.md |
想知道改了什么、为什么改时读（含 v1.0.0 架构故障完整复盘） |
