maa-logging

# MaaFramework C++ 日志宏用法 头文件：`<MaaUtils/Logger.h>` ## 可用宏 | 宏 | 级别 / 用途 | | -------------- | ------------------------------ | | `LogFatal` | 致命错误 | | `LogError` | 不可恢复或当前操作失败的错误 | | `LogWarn` | 可恢复异常、环境风险、降级行为 | | `LogInfo` | 关键状态、任务阶段、初始化结果 | | `LogDebug` | 调试信息、中间结果 | | `LogTrace` | 高频或详细数据 | | `LogFunc` | 函数作用域 enter/leave 和耗时 | | `VAR(x)` | 格式化为 `[x=value]` | | `VAR_VOIDP(x)` | 将指针转为 `void*` 后输出 | ## 核心原则：不要手动拼日志字符串 使用 `<<` 流式输出，各片段自动分隔： ```cpp LogInfo << "matched" << VAR(zone_id) << VAR(x) << VAR(y) << VAR(score); LogError << "locator init failed"; ``` 避免： ```cpp LogInfo << "position: " + std::to_string(x) + ", " + std::to_string(y); LogInfo << std::format("position: ({}, {})", x, y); ``` `std::format` 可用于一般字符串构建，但日志中优先直接输出字段。 ## 典型用法 ```cpp #include <MaaUtils/Logger.h> MaaBool MyRecognitionRun(MaaContext* context, MaaTaskId task_id, const char* node_name) { LogInfo << VAR(context) << VAR(task_id) << VAR(node_name); if (context == nullptr) { LogError << "context is null"; return MAA_FALSE; } LogDebug << "recognition input prepared" << VAR(task_id); return MAA_TRUE; } ``` ## 多变量输出 ```cpp LogInfo << "phase transition" << VAR(from_phase) << VAR(to_phase) << VAR(reason); LogDebug << "match result" << VAR(score) << VAR(x) << VAR(y) << VAR(width) << VAR(height); ``` ## 容器直接输出 `vector`、`set`、`map<string, T>` 等 STL 容器可以直接 `<<`，会自动序列化为 JSON： ```cpp std::vector<std::string> names = { "a", "b", "c" }; LogInfo << "names" << names; std::map<std::string, int> config; LogInfo << "config" << config; ``` 不需要手写循环打印容器内容。 ## 自定义类型输出 给结构体加 `MEO_TOJSON(...)` 或 `MEO_JSONIZATION(...)`，即可直接输出： ```cpp struct LocateOutput { int status = 0; std::string message; int x = 0; int y = 0; MEO_JSONIZATION(status, message, MEO_OPT x, MEO_OPT y) }; LogInfo << VAR(output); ``` 容器嵌套也可以工作： ```cpp std::vector<LocateOutput> results; LogInfo << VAR(results); ``` ## 日志级别建议 | 场景 | 级别 | | ----------------------------- | ---------- | | 初始化成功/失败、关键状态变更 | `LogInfo` | | 任务阶段切换、最终识别结果 | `LogInfo` | | 中间分数、候选数量、调试变量 | `LogDebug` | | 完整矩阵、向量、逐帧详细数据 | `LogTrace` | | 可恢复异常、环境风险 | `LogWarn` | | 当前操作无法继续 | `LogError` | | 进程级不可恢复错误 | `LogFatal` | ## 高频日志约束 - 每帧推理、循环匹配、滚动扫描中的大量数据不要用 `LogInfo`。 - 详细数组、完整 softmax、候选列表优先用 `LogTrace`。 - 用户需要定位问题的关键结果用 `LogInfo` 或 `LogDebug`。 ## 原理简述 `LogStream::stream` 通常按优先级尝试： 1. 可构造 `json::value` → `dumps()` 输出。 2. 可构造 `json::array` → `dumps()` 输出。 3. 可构造 `json::object` → `dumps()` 输出。 4. 有 `operator<<` → 直接流输出。 5. 以上都不满足 → 编译期报错。 如果遇到 “Unsupported type”，给类型加 `MEO_TOJSON`、`MEO_JSONIZATION`，或特化 `json::ext::jsonization<T>`。 ## 审查清单 - [ ] 日志没有手动拼接多个字段。 - [ ] 关键上下文使用 `VAR(x)` 输出。 - [ ] 高频详细数据不使用 `LogInfo`。 - [ ] 错误路径有 `LogError` 或合理级别日志。 - [ ] 自定义类型日志支持 JSON 化或流输出。