平滑重构日志系统只需用新框架参数替换旧调用，不改逻辑、不增依赖；核心参数包括level、module、task_id、duration_ms、status及可选error_code与trace_id，统一结构化为JSON对接ELK/Graylog。
直接用新日志框架参数替换旧日志调用，不改逻辑、不增依赖，就能完成平滑重构。
明确新框架的参数契约
最新统一日志框架（如适配 OpenClaw-system-maintenance 或金仓自治运维体系）普遍采用结构化字段契约，核心参数包括：level（日志级别）、module（所属模块名）、task_id（任务唯一标识）、duration_ms（执行耗时毫秒）、status（成功/失败/跳过）和可选的 error_code 与 trace_id。这些字段已内建序列化为 JSON 并对接 ELK/Graylog，无需额外格式化。
重构前先确认脚本中所有日志输出点是否覆盖这六项关键上下文。未覆盖的（如仅 print("done")）需补全，但只需传入默认值（例如 status="success"、duration_ms=0），不影响运行。
分层替换策略：从封装函数切入
不要逐行改 print 或 logger.info；而是统一收口到一个轻量日志函数，再注入新参数：
- 在每个脚本顶部或公共 utils.py 中定义
log_event(**kwargs)，内部调用新框架的写入接口（如log_client.send()） - 原脚本中所有日志语句，如
logger.info("Backup started")，改为log_event(level="INFO", module="backup", task_id="bk-20260520-01", status="running") - 对带耗时的操作，用上下文管理器或装饰器自动注入 duration_ms，避免手动计时
- 错误分支统一捕获异常后调用
log_event(level="ERROR", error_code="E001", status="failed", trace_id=...)
保留旧日志兼容性过渡期
生产环境切换需零感知，建议启用双写模式：
- 新日志函数默认同时写入新框架 + 原始文本文件（如 /var/log/maint/real-time-monitor.log）
- 通过环境变量控制，如
LOG_MODE=unified关闭双写，LOG_MODE=legacy回退至旧路径 - 监控平台告警规则暂不变更，仍基于原有日志路径匹配关键字；待新字段在 Kibana 中验证稳定后再切告警源
验证与灰度上线要点
重构不是改完就结束，重点验证三件事：
- 所有定时任务（real-time-monitor.sh、daily-maintenance.sh 等）执行后，新日志中 task_id 是否唯一且可追溯，module 是否准确对应脚本职能
- 当 weekly-optimization.sh 生成周报时，其引用的日志数据能否按 status 和 duration_ms 正确聚合统计
- 在故障自愈场景下（如网关挂起后 real-time-monitor.sh 自动重启），新日志是否完整记录“检测→判定→执行→验证”闭环，且 trace_id 贯穿全过程
先选一台非核心节点部署重构版脚本跑 48 小时，比对新旧日志条目数、关键事件覆盖率、告警触发一致性，无差异再批量推送。
