Menu
MaaNTE Python 日志规范。覆盖 agent/utils/logger.py 的 loguru/标准 logging 使用方式、日志级别选择、格式化与最佳实践。在编写或修改 agent/ 下的 Python 代码、添加日志输出、或审查日志质量时使用。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
MaaNTE Pipeline JSON 编写指南。基于 MaaFramework Pipeline 协议，提供节点命名、识别算法、动作类型、流程控制、可复用节点等编码规范与模式参考。在编写、修改或审查 Pipeline JSON、设计节点流程、使用 TemplateMatch/OCR/Custom 识别或 Click/Swipe 动作时使用。
MaaNTE Python 自定义动作（CustomAction）编写指南。覆盖 agent/custom/action/ 下的 Python 代码的架构、注册、命名、maafocus 用户消息、日志、Controller API、Pipeline 集成、错误处理等编码规范和模式参考。在编写、修改或审查 Python 自定义动作，或需要了解 agent 项目结构与 MaaFramework Python 绑定集成方式时使用。
MaaNTE 任务配置（tasks/*.json）编写指南。覆盖任务入口、选项类型（switch/input/select）、pipeline_override、i18n、控制器限制等。在添加新任务、修改任务选项、配置 pipeline_override 时使用。
分析 MaaNTE 上游仓库公开 Issue（`https://github.com/1bananachicken/MaaNTE/issues/...` 或 `#1234`）。自动抓取 issue 正文和评论中的日志附件（`MaaNTE-logs-*.zip` 或裸日志文件），下载解压后从 `maa.log`、agent 日志（`debug/custom/`）、`mxu-tauri.log`、`mxu-web-*.log`、`mxu-agent*.log`、`config/*`、`on_error/` 截图、`.dmp` 崩溃转储中筛选关键证据，并结合 MaaNTE 当前仓库代码、MaaFramework 文档、MXU 文档判断根因、给出修复方案。供分析 MaaNTE issue、日志包、识别失败、任务卡死、控制器差异、Pipeline/Agent/MXU 问题时使用。
用"赛博道士 + 故障玄学 + 半懂不懂技术分析"的风格回复 MaaNTE 用户的简略求助。用于用户只给一句模糊问题、没有日志、没有截图、没有报错时，做一段短小离谱但认真的玄学诊断。触发词可包括"赛博算卦""玄学回复""评论区整活""帮我写一段离谱但正经的故障分析"
分析 Windows 崩溃转储文件（.dmp），诊断 MaaNTE 及其依赖项（MaaFramework、MXU）的崩溃。自动从 GitHub Releases 下载对应版本 PDB 符号，使用 minidump-stackwalk 解析堆栈轨迹并定位崩溃根因。当 issue 日志包或附件中发现 .dmp 文件，或用户要求分析 DMP/崩溃转储时使用。
| name | maa-logging |
| description | MaaNTE Python 日志规范。覆盖 agent/utils/logger.py 的 loguru/标准 logging 使用方式、日志级别选择、格式化与最佳实践。在编写或修改 agent/ 下的 Python 代码、添加日志输出、或审查日志质量时使用。 |
MaaNTE 的日志系统位于 agent/utils/logger.py，提供统一的 logger 对象：
loguru，则使用 loguru 的彩色输出与结构化日志。logging + TimedRotatingFileHandler。"WARNING"，用户只看到 WARNING/ERROR；INFO/DEBUG 仅入文件日志。logger → 开发者日志（内部状态、算法细节、调试信息）
maafocus → 用户可见消息（任务进度、状态变更、错误提示）
logger.debug/info 在 MXU 模式下不会出现在用户面前（console_level = WARNING）。maafocus.Print(context, msg) 或 maafocus.PrintT(context, key, *args)。maafocus.PrintT() 自动通过 utils.i18n.T() 查翻译，支持多语言。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}")
用户可见的消息必须通过 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（或合理的相对导入）% 风格占位符，不拼接字符串、不用 f-stringprint() 调用（应使用 logger 或 pipeline focus）