wzz-server-monitor — 服务器资源监控通知
监控 CPU / 内存 / 磁盘使用率，超过阈值时通过 SMTP 发送邮件告警。核心脚本由 cron 独立定时运行，与任何 AI Agent 无关；本 SKILL.md 是配置文档和交互入口。
1. 快速开始
新用户三步完成：
- 初始化（检查依赖、生成配置目录与模板）：
sh
python3 <skill-dir>/scripts/monitor.py setup
- 编辑配置
~/.config/resource-monitor/config.yaml，填入：
-smtp：SMTP 服务器、账号、授权码（国内邮箱 QQ/163 均可；QQ 用「授权码」而非登录密码）
-metrics：CPU/内存/磁盘阈值
-window：允许发送的时间窗口（可选）
-cooldown_minutes：通知频率（可选）
SMTP 密码建议写入独立文件 ~/.config/resource-monitor/.smtp_secret（chmod 600），配置文件只引用路径。
- 校验 + 安装定时任务：
sh
python3 <skill-dir>/scripts/monitor.py validate-config
python3 <skill-dir>/scripts/monitor.py send-test # 收一封测试邮件
bash <skill-dir>/assets/install.sh # 自动写入 crontab
> Claude 交互：用户说「看下服务器负载」→ 运行 status；「测一下告警邮件」→ send-test；「帮我配置监控」→ 引导用户完成 setup + 编辑 config.yaml + validate-config + send-test。
2. 依赖
- Python ≥ 3.9
psutil、pyyaml、jinja2（第三方，安装时可用国内镜像加速）
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple psutil pyyaml jinja2
模板渲染优先 jinja2；缺失时脚本自动回退到 Python 标准库 string.Template，功能不中断。
3. 文件布局
skill 目录（随版本更新，只读）：
| 路径 | 说明 |
|---|---|
SKILL.md |
本文档 |
scripts/monitor.py |
核心监控脚本（cron 直接调用） |
assets/config.example.yaml |
配置模板 |
assets/install.sh |
一键安装辅助 |
assets/templates/*.html |
邮件文案模板 |
运行时数据（用户环境，不受 skill 更新影响）：
| 路径 | 说明 |
|---|---|
~/.config/resource-monitor/config.yaml |
用户配置 |
~/.config/resource-monitor/.smtp_secret |
SMTP 密码（chmod 600） |
~/.local/state/resource-monitor/state.json |
运行状态（告警去重/节流） |
~/.local/state/resource-monitor/monitor.log |
运行日志 |
4. 发送决策模型
一份邮件聚合列出所有超限指标（不是每项一封）。状态机基于 state.json：
- 状态变化去重：只有指标从「正常 → 超限」才进入告警状态；恢复后重置，下次超限重新计时。
- cooldown 节流：同一告警两次实际发送之间强制最小间隔
cooldown_minutes，防止刷屏。 - 单日上限：
daily_cap限制当日发送总数，防止异常失控。 - 时间窗口：
window.rules之外即使超限也静默不发，但状态照常记录、不推进上次发送时间——窗口一打开的第一轮检查就会补发（夜间超限、早上准时收到）。 - 恢复通知：
recovery: true时，恢复正常会发一封恢复邮件（受 cooldown 与窗口约束）。
决策优先级：冷却期内 → 当日已达上限 → 窗口外静默 → 发送。
5. 配置参考
见 assets/config.example.yaml（带注释的完整示例）。校验命令：
python3 <skill-dir>/scripts/monitor.py validate-config --smtp-connect
--smtp-connect 会额外执行 SMTP 连接与认证握手（不发信）。
6. 模板编写
模板文件在 assets/templates/，使用 Jinja2 语法。可在 config.yaml → templates 修改主题与正文文件名。
暴露给模板的变量白名单（SMTP 凭据绝不会进入模板上下文）：
| 变量 | 说明 |
|---|---|
hostname |
服务器名（hostname_label 或系统主机名） |
timestamp |
本地时间 YYYY-MM-DD HH:MM:SS |
status |
alarm / recovery / test |
alarm_count |
超限指标个数 |
alarms |
[{metric, current, threshold, path}] 超限指标列表 |
metrics |
全量指标 {key: {percent, threshold, path}} |
uptime |
运行时长（timedelta） |
load_avg |
psutil.getloadavg() 三元组 |
subject 同样支持模板变量，如 [{{ hostname }}] 资源告警 ({{ alarm_count }}项)。
7. cron
脚本由 cron 定时运行，每 5 分钟一次全天运行；时间窗口在脚本内过滤（二者正交，改窗口不影响 cron）。
*/5 * * * * /usr/bin/python3 ~/.claude/skills/wzz-server-monitor/scripts/monitor.py check --config ~/.config/resource-monitor/config.yaml >> ~/.local/state/resource-monitor/monitor.log 2>&1
- 使用绝对路径
python3，不依赖 cron 的 PATH。 - 检查频率决定「多久看一次」，通知频率由
cooldown_minutes控制。 bash assets/install.sh可自动写入并去重 crontab。
WSL2 / 容器 cron 自启
WSL2 与多数容器默认不启动 cron 服务。手动启动：
sudo service cron start
开机自启（WSL2）：编辑 /etc/wsl.conf：
[boot]
command = service cron start
8. 日常维护
| 需求 | 命令 |
|---|---|
| 查看当前指标与状态 | monitor.py status |
| 手动触发一次检查 | monitor.py check --dry-run（只打印决策） |
| 绕过窗口测试 | monitor.py check --now |
| 重置告警状态 | monitor.py reset-state |
| 修改配置后校验 | monitor.py validate-config |
日志位置 ~/.local/state/resource-monitor/monitor.log，长跑后手动截断（> log）。
9. 故障排查
| 现象 | 排查 |
|---|---|
| SMTP 认证失败 | QQ/163 邮箱必须用「授权码」（设置里生成）而非登录密码；检查 security/port 是否匹配（ssl=465, tls=587） |
| 日志为空 | 检查 cron 服务是否运行（WSL2 见上）；crontab -l 确认条目 |
| CPU 恒为 0% | cron 每轮是全新进程，cpu_interval 必须 > 0（默认 0.5） |
| 窗口内仍没收到 | validate-config 确认时间格式；status 查看 window: 开/关 |
| 不想收到重复告警 | 调大 cooldown_minutes 或开启 recovery 恢复通知 |
10. 在其他 Agent 中使用（Claude / Codex 等）
本 skill 遵循 Agent Skills 开放标准，核心格式（SKILL.md + YAML frontmatter + Markdown）在 Claude Code、OpenAI Codex、Cursor 等主流 Agent 间通用：
- 本文件的
name/description/version是通用字段；user-invocable、allowed-tools是 Claude Code 增强，其他 Agent 会忽略。 - 监控功能本身与 Agent 无关：即使不经过任何 Agent，
cron直接运行scripts/monitor.py check即可工作。
在 Codex 等其他 Agent 中使用时，把本 skill 目录软链到它的 skills 发现路径：
mkdir -p ~/.codex/skills # 或 .agents/skills
ln -s <skill-dir> ~/.codex/skills/wzz-server-monitor
11. 安全说明
- SMTP 密码存
~/.config/resource-monitor/.smtp_secret（chmod 600），不写入配置文件。 - 模板上下文只注入白名单变量，凭据与完整配置不进模板。
- 脚本只读取系统指标与发送邮件，不做任何删除/修改系统操作。
- 发布版本不包含任何用户数据；
config.yaml、state.json、.smtp_secret均生成于用户本地目录。
