为 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吗? - 是否按预期顺序执行了指定的命令?
这些检查开销很小。在引入模型评分前,您就能很快获得结果,并看出原因。
一个精简的运行程序
可以先用下面这个简单但够用的方案:
- 针对每条提示词运行
codex exec --json --full-auto "<prompt>" - 将 JSONL 执行轨迹保存到磁盘
- 解析执行轨迹,对其中的事件执行确定性检查
将下面的 Go 程序保存为 eval.go。运行 go run eval.go 时,当前目录应是包含 setup-demo-app 技能的项目目录。运行前,请确保检出的项目中没有名为 demo-app 的文件或目录。如果该输出已存在,程序会拒绝运行。程序会调用已安装的 Codex CLI,将执行轨迹写入项目中的 evals/artifacts/test-01.jsonl。无论评估成功还是失败,执行轨迹都会保留,程序也会在报告结果或错误时给出轨迹文件的路径。
// 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 的配置方式是否符合预期。仅靠检查文件是否存在或统计命令数量,很难评估这些要求。
一个可行的办法是在评估流程中增加第二轮检查,让模型参与评分:
- 运行搭建应用的技能(这一步会将代码写入磁盘)
- 对生成的代码仓库执行只读风格检查
- 要求模型返回结构化响应,以便执行框架按一致的方式评分
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增加一轮按评分标准进行的结构化评估,可靠地判断风格和规范是否符合要求。 - 根据实际失败情况扩充测试覆盖范围。 把每次手动修复暴露出的问题写成测试,确保技能以后也能正确处理同样的情况。