1bananachicken MaaNTE Python 日志规范
架构
MaaNTE 的日志系统位于 agent/utils/logger.py，提供统一的 logger 对象：
- 优先 loguru：若已安装
loguru，则使用 loguru 的彩色输出与结构化日志。 - 回退标准 logging：若未安装 loguru，使用标准库
logging+TimedRotatingFileHandler。 - 控制台：根据客户端类型（MXU / MFAAvalonia / 其他）自动适配输出格式（HTML 彩色 / 短标签 / ANSI 颜色）。
- MXU 模式：console_level 自动降为
"WARNING"，用户只看到 WARNING/ERROR；INFO/DEBUG 仅入文件日志。 - 文件：按天滚动，保留 2 周，压缩归档；文件日志固定带时间戳和调用位置。
logger 与 maafocus 的职责分离
logger → 开发者日志（内部状态、算法细节、调试信息）
maafocus → 用户可见消息（任务进度、状态变更、错误提示）
logger.debug/info在 MXU 模式下不会出现在用户面前（console_level = WARNING）。- 所有面向用户的消息必须使用
maafocus.Print(context, msg)或maafocus.PrintT(context, key, *args)。 maafocus.PrintT()自动通过utils.i18n.T()查翻译，支持多语言。- 详见 python-action-guide。
导入
from utils.logger import logger
如果模块在 custom/action/ 下且 utils 不在直接路径中，参考已有代码的相对导入方式。少数子模块（如 SoundDodgeAction.py）通过 custom.action.Common.logger.get_logger(__name__) 获取独立 logger，这是为了利用 loguru 的 {name} 字段；若不关心区分 logger 名，直接用 from utils.logger import logger 即可。
日志级别
| 级别 | 用途 | 示例 |
|---|---|---|
logger.info |
内部关键步骤、启动初始化 | logger.info("已加载演奏配置文件: %s", path) |
logger.debug |
识别细节、中间计算结果 | logger.debug("未识别到 %s", name) |
logger.warning |
可恢复异常、降级、配置缺失 | logger.warning("鼓面模板缺失，演奏检测不可用") |
logger.error |
不可恢复错误 | logger.error("Error: %s", e) |
logger.success |
操作成功确认（loguru） | logger.success("初始化完成") |
logger.trace |
逐帧/高频细节（loguru） | logger.trace("候选入队: ...") |
注意：MXU 模式下 console_level 为 "WARNING"，logger.info 不会出现在用户面前。用户可见的消息请用 maafocus.PrintT()。
格式化
使用 %s / %d 等 % 风格占位符（loguru 风格），不要手动拼接字符串：
# Good
logger.info("演奏开始 | FPS=%d | 鼓面检测=%s", target_fps, drum_available)
logger.debug("未识别到 %s", name)
logger.warning("候选丢弃: lane=%s target=%.3f reason=min_interval", lane, target_time)
# Bad
logger.info("演奏开始 | FPS=" + str(target_fps))
logger.info(f"演奏开始 | FPS={target_fps}")
禁止 print / logger.info 用户消息
用户可见的消息必须通过 maafocus.Print() / PrintT() 发送，禁止 print() 和 logger.info()。
# Bad — 用户看不到（MXU 模式下 logger.info 被过滤）
logger.info("冲咖啡任务开始")
print("=== Auto Make Coffee Action Started ===")
# Good — 用户能看的用 maafocus
PrintT(context, "coffee.started")
PrintT(context, "coffee.making", count + 1, make_count)
# Good — 开发者调试用 logger
logger.debug("识别分数: prob=%.2f", prob)
logger.warning("模板缺失，功能降级")
logger.error("不可恢复错误: %s", e)
敏感信息
不要在日志中输出密钥、完整文件路径中包含敏感信息的用户名等。
审查清单
- 导入使用
from utils.logger import logger（或合理的相对导入） - 日志级别合理：info 用于关键节点，debug 用于识别细节
- 使用
%风格占位符，不拼接字符串、不用 f-string - 无
print()调用（应使用 logger 或 pipeline focus） - 无高频大量日志（循环内使用 debug/trace）
- 异常信息包含足够的上下文（参数值、当前步骤）