wzz-server-monitor

wzz-server-monitor — 服务器资源监控通知

监控 CPU / 内存 / 磁盘使用率，超过阈值时通过 SMTP 发送邮件告警。核心脚本由 cron 独立定时运行，与任何 AI Agent 无关；本 SKILL.md 是配置文档和交互入口。

1. 快速开始

新用户三步完成：

1. 初始化（检查依赖、生成配置目录与模板）：

   python3 /scripts/monitor.py setup
   

2. 编辑配置 ~/.config/resource-monitor/config.yaml，填入：

   • smtp：SMTP 服务器、账号、授权码（国内邮箱 QQ/163 均可；QQ 用「授权码」而非登录密码）
   • metrics：CPU/内存/磁盘阈值
   • window：允许发送的时间窗口（可选）
   • cooldown_minutes：通知频率（可选）

   SMTP 密码建议写入独立文件 ~/.config/resource-monitor/.smtp_secret（chmod 600），配置文件只引用路径。

3. 校验 + 安装定时任务：

   python3 /scripts/monitor.py validate-config
   python3 /scripts/monitor.py send-test       # 收一封测试邮件
   bash /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 更新影响）：

4. 发送决策模型

一份邮件聚合列出所有超限指标（不是每项一封）。状态机基于 state.json：

• 状态变化去重：只有指标从「正常 → 超限」才进入告警状态；恢复后重置，下次超限重新计时。
• cooldown 节流：同一告警两次实际发送之间强制最小间隔 cooldown_minutes，防止刷屏。
• 单日上限：daily_cap 限制当日发送总数，防止异常失控。
• 时间窗口：window.rules 之外即使超限也静默不发，但状态照常记录、不推进上次发送时间——窗口一打开的第一轮检查就会补发（夜间超限、早上准时收到）。
• 恢复通知：recovery: true 时，恢复正常会发一封恢复邮件（受 cooldown 与窗口约束）。

决策优先级：冷却期内 → 当日已达上限 → 窗口外静默 → 发送。

5. 配置参考

见 assets/config.example.yaml（带注释的完整示例）。校验命令：

python3 /scripts/monitor.py validate-config --smtp-connect

--smtp-connect 会额外执行 SMTP 连接与认证握手（不发信）。

6. 模板编写

模板文件在 assets/templates/，使用 Jinja2 语法。可在 config.yaml → templates 修改主题与正文文件名。

暴露给模板的变量白名单（SMTP 凭据绝不会进入模板上下文）：

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. 日常维护

日志位置 ~/.local/state/resource-monitor/monitor.log，长跑后手动截断（> log）。

9. 故障排查

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  ~/.codex/skills/wzz-server-monitor

11. 安全说明

• SMTP 密码存 ~/.config/resource-monitor/.smtp_secret（chmod 600），不写入配置文件。
• 模板上下文只注入白名单变量，凭据与完整配置不进模板。
• 脚本只读取系统指标与发送邮件，不做任何删除/修改系统操作。
• 发布版本不包含任何用户数据；config.yaml、state.json、.smtp_secret 均生成于用户本地目录。