让AI替你写日志：evlog Agent Skills实战，AI助手自动落地日志规范

evlog 是一个覆盖全部 TypeScript 运行时的结构化日志库，核心思想是"宽事件（Wide Events）"与自解释的结构化错误。而 evlog Agent Skills 更进一步：它把日志规范打包成 AI 编程助手可直接安装的技能包，让 AI 自动审查、重构并守护你的日志质量。本文将带你在 1 分钟完成安装，并看清 3 个 AI 替你写日志、查日志的实战场景。

🤖 为什么 AI 写的日志总是一盘散沙

让 AI 助手写一个 API，它十有八九会写出这种"野生"风格：

console.log('Request received') console.log('User:', user.id) console.log('Payment failed') // 凌晨三点很难找到这一行 throw new Error('Something went wrong')

三个隐形代价：

• 日志碎片化：一个请求产生 10 行以上日志，故障时只能靠祈祷去关联
• 错误无信息量："Something went wrong" 对值班的人毫无帮助
• AI 无人约束：助手默认习惯console.log和new Error(...)，除非仓库里有东西明确告诉它"别这么写"

evlog 的理念恰好相反：一次请求 = 一条宽事件，所有上下文合并进一条 JSON；错误自带why/fix字段自我解释。Agent Skills 就是让 AI 自动按这套方式写代码的"规范大脑"。

📦 什么是 evlog Agent Skills

Agent Skills 是一种把领域知识打包成可安装技能包的开放规范，AI 助手安装后即可按包内的知识工作。evlog 的技能包就存放在仓库根目录的skills/中，由官方文档与审查清单直接转化而来：

review-logging-patterns技能还内置了 3 份 AI 工作时会引用的参考清单：宽事件模式（wide-events.md）、结构化错误（structured-errors.md）、代码审查清单（code-review.md）。

⚡ 1 分钟安装：一条命令教会 AI 日志规范

在项目根目录执行：

npx evlog agents

输出类似：

✓ created AGENTS.md ✓ created CLAUDE.md ✓ installed the evlog skills

背后是 3 件事（实现见 commands/agents.ts）：

1. 在AGENTS.md写入约定块：声明规则——一次操作一条宽事件、分组上下文、结构化错误、敏感操作要审计、什么永远不能进日志。这个块刻意保持简短，因为它会被加载进 AI 的每一轮对话
2. 生成CLAUDE.md：一行指向 AGENTS.md，让不同 AI 助手读到同一套规则
3. 安装技能包：委托 skills CLI 自动解析各助手的技能目录（如.claude/skills、.agents/skills），保证只有一份可更新的副本

该命令幂等、可安全重复执行：再次运行只会报告"已是最新"，工作区保持干净。建议升级 evlog 后重跑一次。

🛠️ 实战场景 1：让 AI 审查并重构你的日志代码

安装完成后，对 AI 说一句：

Review this file for logging anti-patterns（审查这个文件的日志反模式）

AI 会按清单开工：找出console.log调用、泛化throw new Error(...)、"日志+抛错"反模式、缺少请求上下文的 handler，并给出重构建议。重构后的形态大致是：

const log = useLogger(event) log.set({ user: { id: user.id, plan: 'premium' } }) log.set({ cart: { items: 3, total: 9999 } }) throw createError({ message: 'Payment failed', why: 'Card declined', fix: 'Try a different payment method', })

请求结束时，框架自动发出一条宽事件：method、path、耗时、所有log.set的上下文都在一条 JSON 里，why/fix也会随错误进入日志——人和 AI 都能直接读懂。完整模式见宽事件文档与结构化错误文档。

🔍 实战场景 2：AI 直接读日志帮你排障

开启文件系统 drain 后，宽事件会被写入.evlog/logs/*.jsonl：每个请求一行、每天一个文件。analyze-logs技能教 AI 直接使用这些文件，你只需要自然语言提问：

• "Why is the checkout endpoint failing?"→ AI 定位level: error的事件，读出error.data.why直接告诉你根因
• "Show me the slowest requests from today"→ 按durationMs排序，列出最慢的接口
• "追踪某个 requestId"→ 一行日志取出该请求的全部上下文

因为每行都是自包含的宽事件，AI 不需要在碎片行之间来回关联——这正是 evlog 的设计初衷。

📈 给规范"打分"：让 AI 循环改进日志覆盖

如果你的项目使用 Nuxt、Next.js、Hono、Express、Fastify 等受支持框架，还可以让 AI 跑一次覆盖度扫描：

npx evlog map --no-write

输出会给每个入口打分（满分 100），并直接点名最该修的 "FIX FIRST"：

score /100 29 entry points scanned FIX FIRST 1. ANY /api/auth/:all* A — touches auth and logs nothing

典型闭环是：AI 按顺序修完 FIX FIRST → 重跑map→ 看分数上涨。在 CI 里可以用--min-score 80（低于阈值即失败）或--baseline（本次 PR 让分数变差即失败）把规范锁死。

📋 快速回顾

• 安装：npx evlog agents，一条命令写入约定块 + 安装技能包
• 审查：说一句"审查我的日志代码"，AI 按清单修复反模式
• 排障：问一句"为什么报错了"，AI 直接读.evlog/logs/给出根因
• 打分：evlog map给出分数与修复清单，配合 CI 门禁防止规范退化

更多细节可参考官方文档 Agent Skills 参考 与 evlog agents 命令。从此，写规范的日志不再是负担——而是 AI 的活儿。