---
title: "evlog 代理"
description: "教会在你的代码仓库中工作的代理如何使用 evlog：在 AGENTS.md 中添加一小段约定，以及已发布的技能。"
canonical_url: "https://evlog.zhcndoc.com/cli/agents"
---
# evlog 代理

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

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

`evlog agents` 会写入这部分内容。

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

```text [Output]
nuxt

✓ created AGENTS.md
✓ installed the evlog skills for Claude Code, Codex and the others
  ran      npx --yes skills add https://www.evlog.dev --agent universal --agent claude-code --global --yes
```

## 写入内容

<table>
<thead>
  <tr>
    <th>
      文件
    </th>
    
    <th>
      处理方式
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        AGENTS.md
      </code>
    </td>
    
    <td>
      如果文件不存在则创建。否则，在 <code>
        <!-- evlog:start -->
      </code>
      
       和 <code>
        <!-- evlog:end -->
      </code>
      
       之间原地替换 evlog 块——这些标记之外的所有内容都保持完全不变。
    </td>
  </tr>
</tbody>
</table>

不会写入 `CLAUDE.md`。大多数 agent 会直接读取 `AGENTS.md`；除非上层存在 `CLAUDE.md`，否则 Claude Code 也会这样做。如果你需要显式指针，请自行添加单行 `@AGENTS.md`。现有的 `CLAUDE.md` 永远不会被修改。

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

## 技能不是由我们来安装的

[代理技能](https://evlog.zhcndoc.com/reference/agent-skills)来自 [`npx skills`](https://github.com/vercel-labs/skills)，`evlog agents` 会调用它，就像 [`evlog init`](https://evlog.zhcndoc.com/cli/init) 运行你的包管理器，而不是自行解压 tarball 一样。

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

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

```text [Output]
· AGENTS.md is up to date
✓ skills already installed · .agents/skills, .claude/skills
   npx skills update to refresh them
```

<callout color="neutral" icon="i-lucide-info">

以交互方式运行时，skills CLI 仍然会询问它自己的问题，因此 `evlog agents` 会把终端交给它，而不是代替你回答。会显式传入目标 agent（共享的 `.agents/skills` 目录，以及 Codex 和其他读取它的 agent，还有 Claude Code），因此 skills CLI 不会安装到它检测到的每个 agent 中。非交互式运行（`--json`、`--yes`、CI、没有 TTY）会传递 `--yes`，这样就不会因为没有人回答提示而卡住。

</callout>

### 你所信任的内容

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

- **会运行什么。** 只有一个命令，并且绝不会从任何你未传入的内容中组装：`npx --yes skills add <source> --agent universal --agent claude-code --global`；当你要求选择技能时附加 `--skill`，当你要求项目安装时用 `--local` 替代 `--global`，非交互式运行时再附加末尾的 `--yes`。交互式运行时它会显示两次：一次是在你确认的计划中，另一次是在步骤开始时。非交互式运行（`--json`、`--yes`、CI、没有 TTY）时，它会出现在运行结束后打印的报告中。无论哪种情况，该字符串都是逐个参数对应的命令，因此重新输入它就能完全复现此次运行；`--dry-run` 会显示它但不运行任何内容。
- **未固定版本。** `npx` 会在运行时解析最新的 [`skills`](https://www.npmjs.com/package/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`，它不会接触网络，你可以按自己喜欢的方式安装技能。

## 可安全重复运行

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

## 标志

<table>
<thead>
  <tr>
    <th>
      标志
    </th>
    
    <th>
      功能
    </th>
  </tr>
</thead>

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

Earlier versions took `--global`. Global is now the default, so that flag is gone.

```bash [Terminal]
evlog agents --skills review-logging-patterns
evlog agents --local
evlog agents --no-skills
evlog agents --dry-run
```

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

## 作为 `evlog init` 的一部分

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

```bash [Terminal]
evlog init --no-agents
```

## 后续步骤

- [代理技能](https://evlog.zhcndoc.com/reference/agent-skills)：每个技能教授的内容
- [`evlog map`](https://evlog.zhcndoc.com/cli/map)：评估你的代理还有哪些内容尚未覆盖
- [宽事件](https://evlog.zhcndoc.com/learn/wide-events)：代码块所概括的约定

---

- [代理技能](https://evlog.zhcndoc.com/reference/agent-skills)


## Sitemap

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