---
title: "Agent 技能"
description: "使用 Agent 技能进行 AI 辅助代码审查和 evlog 迁移。借助 Agent 技能，让 AI 审查你的日志模式并指导迁移到宽事件。"
canonical_url: "https://evlog.zhcndoc.com/reference/agent-skills"
---
# Agent 技能

> 使用 Agent 技能进行 AI 辅助代码审查和 evlog 迁移。借助 Agent 技能，让 AI 审查你的日志模式并指导迁移到宽事件。

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

## 什么是 Agent 技能？

[Agent Skills](https://agentskills.io/) 是一种用于打包 AI 助手能力的开放规范。技能提供：

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

## 可用的技能

<table>
<thead>
  <tr>
    <th>
      技能
    </th>
    
    <th>
      描述
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        skills/review-logging-patterns
      </code>
    </td>
    
    <td>
      审查日志记录模式，建议采用 evlog；可选择使用 <code>
        evlog map
      </code>
      
       检查覆盖范围
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        skills/build-audit-logs
      </code>
    </td>
    
    <td>
      设计、接入并审查具备防篡改能力的审计追踪：策略、<code>
        auditEnricher
      </code>
      
      、<code>
        auditOnly
      </code>
      
      、<code>
        signed
      </code>
      
      、拒绝、脱敏、测试
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        skills/analyze-logs
      </code>
    </td>
    
    <td>
      分析 <code>
        .evlog/logs/
      </code>
      
       中的应用程序日志，以调试错误、调查性能并了解行为
    </td>
  </tr>
</tbody>
</table>

## 安装技能

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

使用 skills CLI 安装：

```bash [Terminal]
npx skills add https://www.evlog.dev
```

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

```bash [Terminal]
npx evlog agents
```

### 技能安装位置

`evlog agents` 默认全局安装到 `~/.agents/skills`：这是 Codex 和其他读取 `.agents/skills` 的 agent 共享的目录。Claude Code 会在 `~/.claude/skills` 中获得指向该副本的相对符号链接，因此两者共用一套文件。传入 `--local` 则改为安装到项目中：项目根目录下的 `.agents/skills` 和 `.claude/skills`，旁边还会有 `skills-lock.json`。

evlog 不会传入其他 agent。若要添加其他 agent，请自行运行 skills CLI，例如 `npx skills add https://www.evlog.dev --agent cursor`。

## 技能的作用

### 代码审查

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

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

在 Nuxt、Nitro、Next.js、TanStack Start、Hono、Express 和 Fastify 中，首先要求助手尝试 [`evlog map`](https://evlog.zhcndoc.com/cli/map)（`npx evlog map --no-write`）：它会对每个入口点进行评分，并列出 FIX FIRST。偏好结构化输出的代理可以使用 `npx evlog map --json --no-write`。即使没有 CLI，该技能仍然有效；map 仍处于早期阶段，在可用时可以让审查更快。

### 采用指南

该技能可帮助你：

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

### 日志分析

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

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

### 示例提示

向你的 AI 助手提问：

<prompt :actions="["copy","cursor","claude"]" description="审查我的代码中的日志反模式" icon="i-lucide-search-code">

审查此文件中的日志反模式

</prompt>

<prompt :actions="["copy","cursor","claude"]" description="提高我的 evlog map 得分" icon="i-lucide-radar">

在此项目中运行 `npx evlog map --no-write` 并阅读报告。

- 按顺序修复“优先修复”项下列出的入口点
- 对每个入口点，先运行 `npx evlog map <file> --no-write`，查看建议的结构
- 保持改动最小：在报告指出缺少的位置添加 `useLogger()`、`log.set()`、`log.audit()` 或 `createError({ why, fix })`
- 重新运行 `npx evlog map --no-write`，确认得分有所提高

文档：[https://www.evlog.dev/cli/map](https://www.evlog.dev/cli/map)
规则：[https://www.evlog.dev/cli/rules](https://www.evlog.dev/cli/rules)

</prompt>

<prompt :actions="["copy","cursor","claude"]" description="将 console.log 调用转换为宽事件" icon="i-lucide-layers">

帮助我将这些 `console.log` 调用转换为宽事件

</prompt>

<prompt :actions="["copy","cursor","claude"]" description="建议添加到宽事件中的上下文" icon="i-lucide-sparkles">

我应该向这个宽事件添加哪些上下文？

</prompt>

<prompt :actions="["copy","cursor","claude"]" description="使用 evlog 设计或审查审计轨迹" icon="i-lucide-shield-check">

按照 **build-audit-logs** 技能。帮助我使用 evlog（[https://www.evlog.dev/use-cases/audit/overview）设计、实现或审查审计轨迹。](https://www.evlog.dev/use-cases/audit/overview%EF%BC%89%E8%AE%BE%E8%AE%A1%E3%80%81%E5%AE%9E%E7%8E%B0%E6%88%96%E5%AE%A1%E6%9F%A5%E5%AE%A1%E8%AE%A1%E8%BD%A8%E8%BF%B9%E3%80%82)

</prompt>

<prompt :actions="["copy","cursor","claude"]" description="使用 evlog 结构化此错误" icon="i-lucide-shield-alert">

如何使用 evlog 结构化这个错误？

</prompt>

<prompt :actions="["copy","cursor","claude"]" description="根据日志调试失败的端点" icon="i-lucide-bug">

为什么 checkout 端点失败了？

</prompt>

<prompt :actions="["copy","cursor","claude"]" description="查找今天最慢的请求" icon="i-lucide-gauge">

显示今天最慢的请求

</prompt>

## 技能结构

```text
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

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

## 下一步

- [快速开始](https://evlog.zhcndoc.com/start/quick-start) - 快速开始使用 evlog
- [宽事件](https://evlog.zhcndoc.com/learn/wide-events) - 了解宽事件设计
- [结构化错误](https://evlog.zhcndoc.com/learn/structured-errors) - 错误处理模式。

---

- [Agent 技能规范](https://agentskills.io)


## Sitemap

See the full [sitemap](https://evlog.zhcndoc.com/sitemap.md) for all pages.