菜单
MaaNTE Python 日志规范。覆盖 agent/utils/logger.py 的 loguru/标准 logging 使用方式、日志级别选择、格式化与最佳实践。在编写或修改 agent/ 下的 Python 代码、添加日志输出、或审查日志质量时使用。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
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）