Agent 技能

evlog 包含可帮助 AI 助手审查日志模式并指导采用 evlog 的 Agent 技能。当你希望获得可评分的覆盖范围图时，可将它们与 @evlog/cli 配合使用。这些技能讲解模式；evlog map 则会指向尚未处理的入口点。

什么是 Agent 技能？

Agent Skills 是一种用于打包 AI 助手能力的开放规范。技能提供：

• 领域知识：宽事件和结构化错误处理的最佳实践
• 代码审查：识别代码库中的日志反模式
• 引导迁移：逐步帮助迁移到 evlog。

可用的技能

安装技能

兼容的代理（Cursor、Claude Code 等）可以自动发现并使用技能。

使用 skills CLI 安装：

npx skills add https://www.evlog.dev

evlog agents 会为你运行相同的命令，并额外将一段简短的 evlog 约定写入项目的 AGENTS.md，其中包含代理在每次日志变更时都应遵循的规则，而技能会提供详细支持：

npx @evlog/cli agents

技能的作用

代码审查

该技能会分析你的代码库，识别以下问题：

• 分散的日志记录：请求处理程序中多个 console.log 或 logger.info 调用
• 缺少上下文：没有用户、请求或业务上下文的日志
• 无用的错误：不带结构化字段的 throw new Error()
• 关联缺失：缺少请求 ID 或跟踪 ID

在 Nuxt、Nitro、Next.js 和 TanStack Start 中，首先要求助手尝试 evlog map（npx @evlog/cli map --no-write）：它会对每个入口点进行评分，并列出 FIX FIRST。偏好结构化输出的代理可以使用 npx @evlog/cli map --json --no-write。即使没有 CLI，该技能仍然有效；map 是一个独立的早期工具包，在可用时可以让审查更快。

采用指南

该技能可帮助你：

• 将传统日志转换为宽事件
• 设计高效的宽事件架构
• 使用 why、fix 和 link 实现结构化错误
• 在 Nuxt、Nitro 或独立 TypeScript 中设置 evlog

日志分析

analyze-logs 技能可让 AI 助手读取 .evlog/logs/ 中的结构化日志：

• 错误调试：查找并解释错误、堆栈跟踪和失败模式
• 性能调查：通过持续时间识别缓慢请求
• 请求跟踪：使用 requestId 跟踪请求的生命周期
• 模式检测：发现重复问题或异常

示例提示

向你的 AI 助手提问：

技能结构

skills/
├── review-logging-patterns/
│   ├── SKILL.md              # 主要技能说明
│   └── references/
│       ├── wide-events.md    # 宽事件模式
│       ├── structured-errors.md # 错误处理指南
│       └── code-review.md    # 审查清单
├── build-audit-logs/
│   ├── SKILL.md              # 审计策略、接入、审查清单
│   └── references/
│       └── framework-wiring.md
└── analyze-logs/
    └── SKILL.md              # .evlog/logs/ 的日志分析

参考文档

该技能包含提供以下内容的参考文档：

wide-events.md

• 宽事件结构与最佳实践
• 上下文分组模式
• 输出格式示例

structured-errors.md

• 错误字段定义
• 状态码指南
• 前端集成模式

code-review.md

• 日志代码审查清单
• 要识别的常见反模式
• 迁移建议。

下一步

• 快速开始 - 快速开始使用 evlog
• 宽事件 - 了解宽事件设计
• 结构化错误 - 错误处理模式。