Maa Logging
Developmentmaa-loggingMaa Logging is an Agent Skill for development published in the MaaXYZ/MaaFramework repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
MaaFramework 日志宏用法指南。Use when writing logging code, using LogInfo/LogError/LogWarn/LogDebug/LogTrace, outputting containers or custom types to logs, or when the user asks about logging best practices.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/MaaXYZ/MaaFramework/blob/HEAD/.claude/skills/maa-logging/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/maa-logging, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
MaaFramework 日志宏用法
头文件:source/MaaUtils/include/MaaUtils/Logger.h
可用宏
| 宏 | 级别 |
|---|---|
LogFatal / LogError / LogWarn | 错误与警告 |
LogInfo / LogDebug / LogTrace | 信息与调试 |
LogFunc | 函数作用域(进入打 enter,离开打 leave + 耗时) |
VAR(x) | 格式化为 [x=value] |
VAR_VOIDP(x) | 同上,但将指针转为 void* 输出 |
核心原则:不要手动拼字符串
用 << 流式输出即可,各片段间自动加空格分隔:
// Good
LogInfo << "Screen size:" << width << "x" << height;
LogError << "failed to override_pipeline" << VAR(entry) << VAR(pipeline_override);
// Bad - 不要手动拼接
LogInfo << "Screen size: " + std::to_string(width) + "x" + std::to_string(height);
LogInfo << std::format("Screen size: {}x{}", width, height);
容器直接输出
vector、set、map<string, T> 等 STL 容器可以直接 <<,会自动序列化为 JSON:
std::vector<std::string> names = { "a", "b", "c" };
LogInfo << "names:" << names; // 输出: names: ["a","b","c"]
std::map<std::string, int> config;
LogInfo << "config:" << config; // 输出: config: {"key":value,...}
不需要手动写 for 循环来打印容器内容。
自定义类型输出
给结构体加 MEO_TOJSON(...) 或 MEO_JSONIZATION(...),即可直接输出:
struct ProcessInfo
{
os_pid pid = 0;
std::string name;
MEO_TOJSON(pid, name); // 只需序列化,不需要反序列化
};
// MEO_JSONIZATION = MEO_TOJSON + MEO_FROMJSON + MEO_CHECKJSON
struct OCRerResult
{
std::wstring text;
cv::Rect box {};
double score = 0.0;
MEO_JSONIZATION(text, box, score);
};
// 直接输出,包括容器嵌套也能工作
LogInfo << VAR(results); // results 是 vector<OCRerResult>
原理简述
LogStream::stream 按优先级尝试:
- 可构造
json::value→dumps()输出(含MEO_TOJSON类型、基本类型) - 可构造
json::array→dumps()输出(含序列容器) - 可构造
json::object→dumps()输出(含map<string, T>) - 有
operator<<→ 直接流输出 - 以上都不满足 →
static_assert编译失败
如果遇到编译报错 "Unsupported type",给类型加 MEO_TOJSON 或特化 json::ext::jsonization<T> 即可。