evlog.
CLI

evlog 代理

代理技能
教会在你的代码仓库中工作的代理如何使用 evlog：在 AGENTS.md 中添加一小段约定，以及已发布的技能。

将 evlog 接入应用只是工作的一半。另一半是由助手编写处理程序，而它会不断使用 console.log 和 throw new Error(...)，直到代码仓库中的某些内容告诉它不要这样做。

evlog agents 会写入这部分内容。

Terminal
evlog agents
Output
nuxt

✓ created AGENTS.md
✓ created CLAUDE.md
✓ installed the evlog skills
  ran      npx --yes skills add https://www.evlog.dev

写入内容

文件处理方式
AGENTS.md如果文件不存在则创建。否则，在 <!-- evlog:start --> 和 <!-- evlog:end --> 之间原地替换 evlog 块——这些标记之外的所有内容都保持完全不变。
CLAUDE.md如果文件不存在，则创建为单行内容 @AGENTS.md。如果文件已存在且已经提到 AGENTS.md，则保持不变。

该代码块有意保持简短，因为它会在每次代理轮次中加载。它陈述了规则（每个操作对应一个宽事件、分组上下文、结构化错误、对敏感操作进行审计、绝不记录哪些内容），并指向技能以获取详细信息。其中命名的日志记录器访问器遵循你的框架：Nuxt 和 Nitro 使用 useLogger(event)，Next.js 使用来自你的 lib/evlog.ts 的 useLogger()，TanStack Start 使用 req.context.log。未检测到框架时，仍会写入一个通用访问器，而这些约定同样适用于 Express 或 Hono。

技能不是由我们来安装的

代理技能来自 npx skills，evlog agents 会调用它，就像 evlog init 运行你的包管理器，而不是自行解压 tarball 一样。

这是有意为之的。每个代理读取不同的目录（.claude/skills、.agents/skills、.codex/skills，……），而 skills CLI 已经会针对每个代理解析这些目录、链接一个规范副本，并支持全局范围。它也不会保留清单，因此我们暗中写入的任何副本都会变成它永远无法更新的第二份副本。委托给它意味着只保留一份副本，并且 npx skills update / remove / list 仍然可以正常操作。

在运行任何内容之前，evlog agents 会查找已经安装的 evlog 技能（任何代理、项目本地或全局），如果找到则不会触碰它们：

Output
· AGENTS.md is up to date
· CLAUDE.md already points at AGENTS.md
✓ skills already installed · .agents/skills, .claude/skills
   npx skills update to refresh them
以交互方式运行时，skills CLI 会询问它自己的问题：要为哪些代理安装，以及安装到项目范围还是全局范围。这个问题应该由它来询问，因此 evlog agents 会把终端交给它，而不是代替你回答。非交互式运行（--json、--yes、CI、没有 TTY）会传递 --yes，这样就不会因为没有人回答提示而卡住。

你所信任的内容

委托执行意味着运行第三方代码，因此有必要明确说明信任模型。

  • 会运行什么。 只有一个命令，并且绝不会从任何你未传入的内容中组装：npx --yes skills add <source>，当运行是非交互式时再附加一个末尾的 --yes，而当你要求时则附加 --skill / --global。交互式运行时它会显示两次：一次是在你确认的计划中，另一次是在步骤开始时。非交互式运行（--json、--yes、CI、没有 TTY）时，它会出现在运行结束后打印的报告中。无论哪种情况，该字符串都是逐个参数对应的命令，因此重新输入它就能完全复现此次运行；--dry-run 会显示它但不运行任何内容。
  • 未固定版本。 npx 会在运行时解析最新的 skills。这正是目的所在，因为技能指南跟随文档网站而不是 CLI 版本发布，但这也意味着你今天获得的版本可能不是上个月获得的版本。如果你的策略要求固定版本，请使用 --no-skills，然后运行你自己固定版本的 npx skills@<version> add https://www.evlog.dev。
  • 会验证 --source。 它必须是一个普通的 http: / https: 源：只能包含字母、数字和 . _ ~ : / -，因此不能包含查询字符串或 shell 元字符。--skills 条目必须是小写且使用短横线连接的名称。在 Windows 上，启动进程需要 shell 才能解析 npx（Node 拒绝在没有 shell 的情况下运行 .cmd），因此两者都会在启动任何进程之前完成检查，而不是在调用链中继续盲目信任。
  • 未经决定不会启动任何进程。 --no-skills 会完全跳过它，而交互式流程在你确认计划之前也不会执行到该命令。

如果这些都不符合你的策略，evlog agents --no-skills 仍然会写入 AGENTS.md 和 CLAUDE.md，它们不会接触网络，你可以按自己喜欢的方式安装技能。

可安全重复运行

再次运行会根据当前 CLI 刷新代码块。任何已经完全相同的内容都会被报告，而不会被重写，因此第二次运行会保持工作树干净。在升级 @evlog/cli 后运行它。

标志

标志功能
--skills <list>以逗号分隔的技能名称，传递给 npx skills add --skill（默认为全部技能）
--no-skills仍然写入 AGENTS.md 和 CLAUDE.md；仅跳过技能安装 — 不会启动任何进程
--global, -g为所有项目安装技能，而不仅仅是当前项目
--source <url>技能发布地址 — 一个纯 http(s) 源（默认为 https://www.evlog.dev）
--dry-run显示计划，但不写入或运行任何内容
--yes, -y无需确认直接应用
Terminal
evlog agents --skills review-logging-patterns
evlog agents --global
evlog agents --no-skills
evlog agents --dry-run

如果 skills CLI 失败，无论是因为没有网络还是没有 npx，代码块仍会保留在磁盘上，并且命令会报告失败并以 1 退出。AGENTS.md 代码块从不需要网络。

作为 evlog init 的一部分

evlog init 将此作为最后一个问题。AGENTS.md 和 CLAUDE.md 的写入会与 evlog 接入放在同一个计划中，在一个列表里通过一次确认完成，技能运行则与包管理器安装同时进行。使用 --no-agents 跳过它：

Terminal
evlog init --no-agents

后续步骤

遥测

evlog CLI 会收集哪些关于自身使用情况的数据、如何查看这些数据，以及关闭它的三种方式——DO_NOT_TRACK、EVLOG_TELEMETRY=0，或 evlog telemetry disable。

可观测性评分

根据 evlog 日志规则检查受支持的入口点，了解评分，并在添加 CI 门禁前修复一个具体缺口