如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题
Jan 22, 2026 Codex

用评估系统地测试智能体技能

了解如何测试智能体技能、为其评分,并持续改进。

作者: Dominik Kundel, Gabriel Chua

用评估系统地测试智能体技能

为 Codex 这样的智能体迭代技能时,您很难判断技能是真的有了改进,还是仅仅改变了行为。一个版本感觉更快,另一个看起来更可靠,却可能在不经意间出现回归:技能没有触发、跳过了必要步骤,或留下了多余文件。

技能本质上是为 LLM 编排的一组提示词和指令。要持续改进技能,最可靠的办法就是像评估 LLM 应用中的其他提示词一样评估它。

Evals(evaluations 的简称,即评估)用来检查模型的输出以及生成输出所采取的步骤是否符合您的预期。有了评估,您就可以把“感觉是不是好了一点?”换成几个具体的问题:

  • 智能体调用了技能吗?
  • 它执行了预期的命令吗?
  • 生成的结果符合您关心的规范吗?

一次评估的流程如下:一条提示词 → 一次运行记录(执行轨迹 + 产物)→ 几项检查 → 一个可与历次结果比较的分数。

在实践中,智能体技能评估很像轻量级端到端测试:运行智能体,记录实际发生的情况,再按几条规则为结果评分。

本文将用 Codex 演示这一流程。您将先定义成功标准,再添加确定性检查并按评分标准打分,从而清楚地看出哪些改动带来了改进,哪些引入了回归。

1. 在编写技能前定义成功标准

在编写技能之前,先用可衡量的标准写下怎样才算“成功”。您可以把检查分为几类:

  • 结果目标: 任务完成了吗?应用能运行吗?
  • 过程目标: Codex 是否调用了技能、使用了指定的工具,并按预期步骤执行?
  • 风格目标: 输出是否符合您要求的规范?
  • 效率目标: 执行过程是否避免了无谓的反复操作,例如运行不必要的命令或消耗过多 Token?

清单要简短,只列出必须通过的检查,优先覆盖您最在意的行为。

例如,本文评估的是一个搭建演示应用的技能。有些检查很具体。它执行了 npm install 吗?创建了 package.json 吗?此外,本文还会用一套结构化的风格评分标准来评估代码规范和布局。

将两类检查结合起来,可以在最终得出通过或失败的结论之前,迅速发现并定位具体的回归。

2. 创建技能

一个 Codex 技能是一个包含 SKILL.md 文件的目录。文件开头是 YAML 前置元数据(name、description),接下来是定义技能行为的 Markdown 指令。目录中还可以放资源和脚本。名称和描述比看起来更重要。Codex 主要依据它们判断 是否 调用技能,以及 何时 将 SKILL.md 的其余内容加入智能体的上下文。名称和描述如果含糊不清,或涵盖的用途过多,技能就很难在恰当的时候触发。

最快的入门方式是使用 Codex 内置的技能创建工具(它本身也是一个技能)。运行以下命令,它会引导您完成创建过程:

$skill-creator

创建工具会询问技能的用途、何时应触发,以及是只需指令还是需要脚本支持(默认推荐只使用指令)。如需详细了解如何创建技能,请查阅文档。

技能示例

本文用一个精简的技能作为示例。它搭建一个小型 React 演示应用,让每次搭建的过程和结果都可预期、可复现。

这个技能会:

  • 使用 Vite 的 React + TypeScript 模板初始化项目
  • 使用 Tailwind CSS 官方提供的 Vite 插件进行配置
  • 确保文件结构精简且一致
  • 明确规定怎样才算“完成”,以便判断是否成功

下面是一份精简的草稿,您可以将其粘贴到以下任一位置:

  • .codex/skills/setup-demo-app/SKILL.md(在当前代码仓库中生效),或
  • ~/.codex/skills/setup-demo-app/SKILL.md(对当前用户生效)。
---
name: setup-demo-app
description: Scaffold a Vite + React + Tailwind demo app with a small, consistent project structure.
---

## 适用场景

需要新建演示应用来快速开展 UI 实验或复现问题时,使用此技能。

## 搭建目标

使用 Vite 创建采用 TypeScript 的 React 应用,并配置 Tailwind。保持应用精简。

搭建完成后的项目结构:

- src/
  - main.tsx(入口文件)
  - App.tsx(界面根组件)
  - components/
    - Header.tsx
    - Card.tsx
  - index.css(在此导入 Tailwind)
- index.html
- package.json

风格要求:

- 使用 TypeScript 编写组件
- 仅使用函数式组件
- 使用 Tailwind 类设置样式(不使用 CSS 模块)
- 不引入额外的 UI 库

## 步骤

1. 使用 Vite 的 React TS 模板初始化项目:
   npm create vite@latest demo-app -- --template react-ts

2. 安装依赖项:
   cd demo-app
   npm install

3. 使用 Vite 插件安装并配置 Tailwind。
   - npm install tailwindcss @tailwindcss/vite
   - 在 vite.config.ts 中添加 Tailwind 插件
   - 将 src/index.css 的内容替换为:
     @import "tailwindcss";

4. 实现最简界面:
   - Header 显示应用标题和简短的副标题
   - Card 提供可复用的卡片容器
   - App 渲染 Header 和 2 个 Card 组件,每张卡片都显示占位文本

## 完成标准

- 运行 npm run dev 可以成功启动开发服务器
- package.json 文件存在
- src/components/Header.tsx 和 src/components/Card.tsx 两个文件均存在

这个示例特意规定了具体的实现方式,让评估有明确的依据。

3. 手动触发技能,找出隐含的假设

技能是否会被调用,在很大程度上取决于 SKILL.md 中的 名称 和 描述。因此,首先要检查 setup-demo-app 技能能否在您预期的情况下触发。

刚开始时,可以在实际的代码仓库或临时目录中,通过 /skills 斜杠命令或用 $ 前缀引用技能,显式激活它,然后观察哪里出了问题。这样可以发现几类偏差:技能完全没有触发、在不该触发时被触发,或者虽然运行了,却偏离了预期步骤。

先找出技能中隐含的假设,速度和细节可以稍后再优化。常见的假设有:

  • 关于触发条件的假设:“快速搭建一个 React 演示应用”这类提示词 应该 调用 setup-demo-app,却没有触发,而“添加 Tailwind 样式”这类更宽泛的提示词却意外触发了它。

  • 关于环境的假设:技能假定当前目录为空,或者假定 npm 已经可用,而且是首选的包管理器。

  • 关于执行过程的假设:智能体以为依赖项已经安装,便跳过 npm install,或是在 Vite 项目创建之前就开始配置 Tailwind。

准备好重复执行这些测试时,可以改用 codex exec。它专为自动化和 CI 设计,会将进度实时输出到 stderr,并仅将最终结果写入 stdout,便于用脚本运行测试、保存记录并查看结果。

默认情况下,codex exec 在受限沙盒中运行。如果任务需要写入文件,请在运行时加上 --full-auto。一般来说,只授予完成任务所需的最低权限,尤其是在自动化运行时。

一次基本的手动运行可以这样写:

codex exec --full-auto \
  '使用 $setup-demo-app 技能在当前目录中创建项目。'

第一次动手运行时,优先找出边界情况,验证正确性还在其次。这里手动修复的每个问题,例如补上缺少的 npm install、修正 Tailwind 配置或把触发条件描述得更准确,都可以写成后续的评估用例。这样,在大规模评估之前,您就可以用测试明确哪些行为必须保留。

4. 用少量有针对性的提示词及早发现回归

评估可以从小规模入手。对于单个技能,10–20 条提示词就足以让您及早发现回归并验证改进。

先建一个小型 CSV 文件,在开发或使用过程中遇到实际问题时再逐步扩充。每一行都对应一个您关心的场景,明确 setup-demo-app 技能 应该 还是 不应该 激活,以及激活后怎样才算成功。

例如,最初的 evals/setup-demo-app.prompts.csv 可以写成这样:

id,should_trigger,prompt
test-01,true,"Create a demo app named `devday-demo` using the $setup-demo-app skill"
test-02,true,"Set up a minimal React demo app with Tailwind for quick UI experiments"
test-03,true,"Create a small demo app to showcase the Responses API"
test-04,false,"Add Tailwind styling to my existing React app"

这些用例的测试重点各不相同:

  • 显式调用(test-01)
    这条提示词直接点名技能。它用来确认 Codex 能按要求调用 setup-demo-app,并确保修改技能名称、描述或指令后,仍然可以按名称调用技能。

  • 隐式调用(test-02)
    这条提示词未提及技能名称,却 准确 描述了技能的目标场景,也就是搭建一个极简的 React + Tailwind 演示应用。它用来测试 SKILL.md 中的名称和描述是否足够清楚,让 Codex 能自行选中这个技能。

  • 根据上下文调用(test-03)
    这条提示词加入了特定领域的背景信息(Responses API),所需的搭建步骤仍然相同。它用来检查在更贴近实际使用、带有少量额外信息的提示词中,技能能否触发,以及生成的应用是否仍符合预期的结构和规范。

  • 阴性对照(test-04)
    这条提示词不应调用 setup-demo-app。它代表一种常见的相关请求(“给现有应用添加 Tailwind”),可能意外匹配技能描述(“React + Tailwind 演示应用”)。至少加入一个 should_trigger=false 用例,有助于发现误触发:用户只想修改现有项目,Codex 却选中了技能,创建了新项目。

评估既要确认显式调用时技能的行为正确,也要检验用户未提及技能名称时,实际使用中的提示词能否在适当的场景触发技能。

遇到遗漏的场景、未能触发技能的提示词,或输出偏离预期的情况时,就在 CSV 中新增一行。随着用例不断积累,这个小文件会持续记录 setup-demo-app 技能必须正确处理的各种场景。

随着时间推移,这个小型数据集将持续记录技能必须始终满足的要求。

5. 从轻量级确定性评分器入手

评估的核心是使用 codex exec --json,让评估执行框架在查看最终输出之外,还能根据 实际发生的行为 评分。

启用 --json 后,stdout 输出的是由结构化事件组成的 JSONL 流。这样,您就可以针对关心的行为直接编写确定性检查,例如:

  • 执行了 npm install 吗?
  • 创建了 package.json 吗?
  • 是否按预期顺序执行了指定的命令?

这些检查开销很小。在引入模型评分前,您就能很快获得结果,并看出原因。

一个精简的运行程序

可以先用下面这个简单但够用的方案:

  1. 针对每条提示词运行 codex exec --json --full-auto "<prompt>"
  2. 将 JSONL 执行轨迹保存到磁盘
  3. 解析执行轨迹,对其中的事件执行确定性检查
运行 Codex 评估
// evals/run-setup-demo-app-evals.mjs
import { spawnSync } from "node:child_process";
import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
import path from "node:path";

function runCodex(prompt: string, outJsonlPath: string) {
  const res = spawnSync(
    "codex",
    [
      "exec",
      "--json", // REQUIRED: emit structured events
      "--sandbox",
      "workspace-write", // Allow changes inside the example repository
      prompt,
    ],
    { encoding: "utf8" }
  );

  if (res.error) throw res.error;
  mkdirSync(path.dirname(outJsonlPath), { recursive: true });

  // stdout is JSONL when --json is enabled
  writeFileSync(outJsonlPath, res.stdout, "utf8");

  return { exitCode: res.status ?? 1, stderr: res.stderr };
}

function parseJsonl(jsonlText: string) {
  return jsonlText
    .split("\n")
    .filter(Boolean)
    .map((line: string) => JSON.parse(line));
}

// deterministic check: did the agent run `npm install`?
function checkRanNpmInstall(
  events: {
    type: string;
    item?: { type: string; status: string; exit_code: number; command: string };
  }[]
) {
  return events.some(
    (e) =>
      e.type === "item.completed" &&
      e.item?.type === "command_execution" &&
      e.item.status === "completed" &&
      e.item.exit_code === 0 &&
      typeof e.item?.command === "string" &&
      e.item.command.includes("npm install")
  );
}

// deterministic check: did `package.json` get created?
function checkPackageJsonExists(projectDir: string) {
  return existsSync(path.join(projectDir, "package.json"));
}

// Example single-case run
const projectDir = process.cwd();
const tracePath = path.join(projectDir, "evals", "artifacts", "test-01.jsonl");

const prompt =
  "Create a demo app named demo-app using the $setup-demo-app skill";

const { exitCode, stderr } = runCodex(prompt, tracePath);
if (exitCode !== 0) {
  throw new Error(`Codex exited with status ${exitCode}: ${stderr}`);
}

const events = parseJsonl(readFileSync(tracePath, "utf8"));

console.log({
  ranNpmInstall: checkRanNpmInstall(events),
  hasPackageJson: checkPackageJsonExists(path.join(projectDir, "demo-app")),
});

这种做法的好处在于,所有检查都具有确定性,而且便于调试。

如果某项检查失败,您可以打开 JSONL 文件,查看具体发生了什么。每次命令执行都会按顺序记录为 item.* 事件。这样,您就能查明回归原因并修复问题。

6. 用 Codex 按评分标准进行定性检查

确定性检查能回答 “基本步骤完成了吗?”。要回答 “完成方式符合您的要求吗?”,还需要定性检查。

对于 setup-demo-app 这样的技能,许多要求都是定性的,例如组件结构、样式规范,或 Tailwind 的配置方式是否符合预期。仅靠检查文件是否存在或统计命令数量,很难评估这些要求。

一个可行的办法是在评估流程中增加第二轮检查,让模型参与评分:

  1. 运行搭建应用的技能(这一步会将代码写入磁盘)
  2. 对生成的代码仓库执行只读风格检查
  3. 要求模型返回结构化响应,以便执行框架按一致的方式评分

Codex 通过 --output-schema 直接支持这种做法,可以让最终响应符合您定义的 JSON 模式。

一个精简的评分模式

先定义一个精简的模式,列出您关心的检查项。例如,创建 evals/style-rubric.schema.json:

{
  "type": "object",
  "properties": {
    "overall_pass": { "type": "boolean" },
    "score": { "type": "integer", "minimum": 0, "maximum": 100 },
    "checks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "pass": { "type": "boolean" },
          "notes": { "type": "string" }
        },
        "required": ["id", "pass", "notes"],
        "additionalProperties": false
      }
    }
  },
  "required": ["overall_pass", "score", "checks"],
  "additionalProperties": false
}

这个模式提供了一组固定字段(overall_pass、score 和各检查项的结果),便于您汇总结果、比较差异并持续跟踪变化。

风格检查提示词

接下来,再运行一次 codex exec,让它 只检查代码仓库,并输出符合评分标准的 JSON 响应:

codex exec \
  "请根据以下要求评估 demo-app 代码仓库:
   - 代码仓库中有一个使用 Vite + React + TypeScript 的项目
   - 项目通过 @tailwindcss/vite 配置 Tailwind,并在 CSS 中导入 tailwindcss
   - src/components 中包含 Header.tsx 和 Card.tsx
   - 组件均为函数式组件,使用 Tailwind 工具类设置样式(不使用 CSS 模块)
   以 JSON 格式返回评分结果,各检查项的标识符为 vite、tailwind、structure、style。" \
  --output-schema ./evals/style-rubric.schema.json \
  -o ./evals/artifacts/test-01.style.json

使用 --output-schema 可以获得结构固定的 JSON 对象,便于评估执行框架解析、比较并统一为多次运行的结果评分。

如果以后将这套评估迁移到 CI,可以将 --output-schema 传给 Codex GitHub Action 的 codex-args,要求自动化工作流使用相同的结构化输出。

7. 随着技能逐渐成熟,扩展评估范围

建立基本的评估流程后,您可以根据技能最重要的要求来扩展评估。从小范围开始,只在更深入的检查确实有助于确认技能可靠性时,再逐步添加。

例如:

  • 命令数量和重复操作: 统计 JSONL 执行轨迹中的 command_execution 项,可以发现智能体开始陷入循环或反复执行命令这类回归。您还可以从 turn.completed 事件中查看 Token 用量。

  • Token 预算: 跟踪 usage.input_tokens 和 usage.output_tokens,以发现提示词意外变长的情况,并比较不同版本的效率。

  • 构建检查: 技能执行完毕后运行 npm run build。构建能更有力地验证端到端结果,并发现导入失败或工具配置错误等问题。

  • 运行时冒烟测试: 运行 npm run dev,用 curl 向开发服务器发送请求。如果已有轻量级 Playwright 检查,也可以运行该检查。这类检查能进一步验证应用是否正常运行,但会增加耗时,适合按需使用。

  • 代码仓库整洁度: 确保运行过程没有生成多余文件,并确认 git status --porcelain 的输出为空(或与明确列出的允许变更项一致)。

  • 沙盒和权限回归: 验证技能在预定的权限范围内仍能正常工作。实现自动化后,默认采用最小权限尤为重要。

先用能解释行为的快速检查,再按需加入速度较慢、开销较大的检查,前提是这些检查确实能降低风险。

8. 要点回顾

要验证 setup-demo-app 是否真的有所改进,可以运行智能体、记录实际发生的情况,再用几项检查为结果评分。建立这个流程后,每次调整的效果都更容易验证,也更容易发现回归。

  • 衡量真正重要的行为。 好的评估能让您看出哪里发生了回归,并解释失败原因。
  • 先写下可验证的完成标准。 使用 $skill-creator 创建初稿,再细化指令,直到成功标准清楚明确。
  • 根据实际行为进行评估。 用 codex exec --json 保存 JSONL 执行轨迹,并针对 command_execution 事件编写确定性检查。
  • 规则难以判断的地方,交给 Codex 评估。 使用 --output-schema 增加一轮按评分标准进行的结构化评估,可靠地判断风格和规范是否符合要求。
  • 根据实际失败情况扩充测试覆盖范围。 把每次手动修复暴露出的问题写成测试,确保技能以后也能正确处理同样的情况。