| name | maa-logging |
| description | MaaFramework C++ 日志宏用法指南。用于写 C++ MaaFramework 扩展、Custom 组件或工具代码时使用 LogInfo/LogError/LogWarn/LogDebug/LogTrace、VAR、容器输出和自定义类型日志。 |
MaaFramework C++ 日志宏用法
头文件：<MaaUtils/Logger.h>
可用宏
| 宏 | 级别 / 用途 |
|---|
LogFatal | 致命错误 |
LogError | 不可恢复或当前操作失败的错误 |
LogWarn | 可恢复异常、环境风险、降级行为 |
LogInfo | 关键状态、任务阶段、初始化结果 |
LogDebug | 调试信息、中间结果 |
LogTrace | 高频或详细数据 |
LogFunc | 函数作用域 enter/leave 和耗时 |
VAR(x) | 格式化为 [x=value] |
VAR_VOIDP(x) | 将指针转为 void* 后输出 |
核心原则：不要手动拼日志字符串
使用 << 流式输出，各片段自动分隔：
LogInfo << "matched" << VAR(zone_id) << VAR(x) << VAR(y) << VAR(score);
LogError << "locator init failed";
避免：
LogInfo << "position: " + std::to_string(x) + ", " + std::to_string(y);
LogInfo << std::format("position: ({}, {})", x, y);
std::format 可用于一般字符串构建，但日志中优先直接输出字段。
典型用法
#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;
}
多变量输出
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：
std::vector<std::string> names = { "a", "b", "c" };
LogInfo << "names" << names;
std::map<std::string, int> config;
LogInfo << "config" << config;
不需要手写循环打印容器内容。
自定义类型输出
给结构体加 MEO_TOJSON(...) 或 MEO_JSONIZATION(...)，即可直接输出：
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);
容器嵌套也可以工作：
std::vector<LocateOutput> results;
LogInfo << VAR(results);
日志级别建议
| 场景 | 级别 |
|---|
| 初始化成功/失败、关键状态变更 | LogInfo |
| 任务阶段切换、最终识别结果 | LogInfo |
| 中间分数、候选数量、调试变量 | LogDebug |
| 完整矩阵、向量、逐帧详细数据 | LogTrace |
| 可恢复异常、环境风险 | LogWarn |
| 当前操作无法继续 | LogError |
| 进程级不可恢复错误 | LogFatal |
高频日志约束
- 每帧推理、循环匹配、滚动扫描中的大量数据不要用
LogInfo。
- 详细数组、完整 softmax、候选列表优先用
LogTrace。
- 用户需要定位问题的关键结果用
LogInfo 或 LogDebug。
原理简述
LogStream::stream 通常按优先级尝试：
- 可构造
json::value → dumps() 输出。
- 可构造
json::array → dumps() 输出。
- 可构造
json::object → dumps() 输出。
- 有
operator<< → 直接流输出。
- 以上都不满足 → 编译期报错。
如果遇到 “Unsupported type”，给类型加 MEO_TOJSON、MEO_JSONIZATION，或特化 json::ext::jsonization<T>。
审查清单
