# @agentproto/eval 中文文档

规范地址：https://npmcn.com/package/%40agentproto/eval/

版本：1\.0\.1
npm 元数据更新时间：2026-11-04T00:05:34.762Z
中文译文更新时间：2026-11-09T20:10:32.057Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agentproto/eval
原文对照：https://npmcn.com/package/%40agentproto/eval/?lang=original
项目主页：https://agentproto.sh/
源码仓库：https://github.com/agentproto/ts

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：204 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2026-07-08T14:51:18.014Z
- 最新版本发布：2026-11-04T00:05:34.403Z
- 近 30 天下载量：1757（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

AIP-14 TOOL合同+AIP-30 PROVIDER内置的1份合同的确定性参考分数。 计分器是一个工具,其输出Schema是共享的 `Score` 形状 — 没有新的计分器端口。 船舶精确相接,正格相接,json-schema-valid,和平稳预算. 无LLM/m

## 安装

```sh
npm install @agentproto/eval
```

也可以使用：`pnpm add @agentproto/eval`、`yarn add @agentproto/eval`、`bun add @agentproto/eval`

## README

# @ agentproto/ eval (英语)

代理Proto的确定性参考分数——作为AIP-14 TOOL运输 合同加AIP-30 PROVIDER中的合同.

## 计分器是一种工具

有一个 **没有单独的"记分器端口"**。计分器是一种普通的 AIP-14 工具 作者为 `defineTool`,其 `outputSchema` 为共享 `Score` 形状, 执行 `implementTool` 捆入一个 `defineDriver` 完全一样 所有其它的建筑。 这种再利用购买了登记簿、复试和 `toMastraTool` 编号 : `toAiSdkTool` 免费的预测.

```ts
export const scoreSchema = z.object({
  value: z.number().min(0).max(1), // normalized score
  passed: z.boolean(),             // clears the scorer's threshold
  label: z.string(),               // scorer id, e.g. "exact-match"
  rationale: z.string().optional(),// human-readable why
})
```

## 四个决定分数

所有这些都是其输入的纯函数——没有LLM/型号调用. 对a 模型后置计分器,见 [LLM 现职评分员](https://npmcn.com/package/%40agentproto/eval/#readme-llm-as-judge-scorer) 见下文.

| 工具标识 | 投入 | 行为 |
| --- | --- | --- |
| `eval.exact-match` | `{ actual, expected, trim? }` | `value` 1 当相等(在可选修饰后),否则为0. |
| `eval.regex-match` | `{ actual, pattern, flags? }` | 1 当编译的 RegExp 匹配时, 否则为 0 。 一个 **无效模式** 返回已键入的失败 `Score` (单位:千美元)`value 0`, (中文(简体) ), `rationale: "invalid pattern: …"`)——它从不掷出. |
| `eval.json-schema-valid` | `{ actual, schema }` | 顶级最小结构检查 `required` + 键 `properties.type` 只有这个 1 有效时, 其他 0 有第一次违反 `rationale`。 。 。 . |
| `eval.latency-budget` | `{ durationMs, budgetMs }` | `passed = durationMs <= budgetMs`· ; `value` 1在预算内,否则 `max(0, 1 - (durationMs - budgetMs) / budgetMs)`。 。 。 . |

### `eval.json-schema-valid` 限制

要保持此包的光度( 否) `ajv`检查计划是故意的 最小: 它验证顶层 `type`,每个名字在 `required` 实值 现在,以及任何 `properties.<name>.type` 匹配该值的原始值 类型。 没错 **没有** 重复到嵌入式计划,不执行 jSON Schema的其余部分`enum`, (中文(简体) ), `format`, (中文(简体) ), `oneOf`, (中文(简体) ), `items`(中文(简体) ). 更充实 验证器是后一步 .

## 运行计分器

通过车手调出任何计分器 `runTool`,通过提供者作为 唯一候选人:

```ts
import { runTool } from "@agentproto/driver"
import { exactMatchTool, evalScorersProvider } from "@agentproto/eval"

const score = await runTool({
  tool: exactMatchTool,
  candidates: [evalScorersProvider],
  input: { actual: "hello", expected: "hello" },
})
// → { value: 1, passed: true, label: "exact-match", rationale: "actual equals expected" }
```

## 运行套房

一个 **eval 是一个工作流程**: 每种情况运行一个 `target`评分 目标输出一个分数 `tool` 步骤/ 装订、 汇总和报告 通过 `@agentproto/telemetry` 端口 . `runEval` 构成a `@agentproto/workflow-runtime` `RuntimeWorkflow` 每个案件——目标 结构化输出是每个计分器步骤的输入选择器——并滚动 个案结果为: `EvalReport`。 。 。 .

每个记分员都是作为 `ScorerBinding` (数量) `tool`页:1 `driver`,则a `mapInput` 并用 `bindScorer` 因此,记分器 不同输入类型 共存在一个套间.

```ts
import { arrayTelemetry } from "@agentproto/telemetry"
import {
  runEval,
  bindScorer,
  exactMatchTool,
  latencyBudgetTool,
  evalScorersProvider,
  type EvalEvent,
  type TypedEvalSuite,
} from "@agentproto/eval"

interface Answer { text: string; latencyMs: number }

const suite: TypedEvalSuite<{ prompt: string }, Answer> = {
  id: "greeting-suite",
  cases: [
    { id: "hello", input: { prompt: "hi" }, expected: "hello" },
    { id: "world", input: { prompt: "wo" }, expected: "world" },
  ],
  scorers: [
    bindScorer<Answer, { actual: string; expected: string }>({
      id: "exact",
      tool: exactMatchTool,
      driver: evalScorersProvider,
      mapInput: ({ output, expected }) => ({
        actual: output.text,
        expected: typeof expected === "string" ? expected : "",
      }),
    }),
    bindScorer<Answer, { durationMs: number; budgetMs: number }>({
      id: "latency",
      tool: latencyBudgetTool,
      driver: evalScorersProvider,
      mapInput: ({ output }) => ({ durationMs: output.latencyMs, budgetMs: 100 }),
    }),
  ],
}

const telemetry = arrayTelemetry<EvalEvent>()
const report = await runEval(suite, {
  target: async ({ prompt }) => ({ text: prompt === "hi" ? "hello" : "world", latencyMs: 10 }),
  telemetry,
})
// report.passedCount / report.meanValue aggregate across cases;
// telemetry.events runs eval.started … eval.finished in order.
```

这个 `target` 是一个平面合成函数( 不需要成为工具); a 工具/代理目标是一个记录的后续行动。 事件通过共享遥测 端口 —— `Telemetry<EvalEvent>` 下层 `agentproto/eval/v1` 计划 (单位:千美元)`eval.started`, (中文(简体) ), `eval.case.started`, (中文(简体) ), `eval.case.scored`, (中文(简体) ), `eval.case.finished`, (中文(简体) ), `eval.finished`. Sinks MUSST 容忍未知种类(前-后相).

## LLM 现职评分员

`eval.llm-judge` 是一个 **模式支持** 计分员——但它仍然是TOOL,准确的说 就像上面的4个决定分数 不同之处在于模型在哪里 生命:注射式法官被关闭 **驱动程序**线性 通过工具输入/文本,通过 `makeLlmJudgeDriver(judge)`这表示 由现有的 `bindScorer` 编号 : `runEval` 改为零 也一样.

法官本身是一个注入功能—— `JudgeFn` - 所以这个包裹留下 供应商中立:这里没有LLM SDK,没有网络依赖性.

```ts
export type JudgeFn = (args: {
  output: JsonValue
  criteria: string
  expected?: JsonValue
}) => Promise<JudgeVerdict>
// JudgeVerdict = { value: number (0..1); passed?: boolean; rationale?: string }
```

在法官周围建一个驱动程序,然后直接调用工具或使用 `llmJudge(...)` 方便随时使用 `ScorerBinding`数字 :

```ts
import { runTool } from "@agentproto/driver"
import {
  llmJudgeTool,
  makeLlmJudgeDriver,
  llmJudge,
  bindScorer,
  type JudgeFn,
} from "@agentproto/eval"

// A real judge is injected by the caller — an LLM call, an agent session,
// or the supervisor's judge-gate. Shown here as a stand-in.
const judge: JudgeFn = async ({ output, criteria }) => {
  // ... call out to a model, or whatever satisfies JudgeFn ...
  return { value: 0.9, rationale: "meets the criteria" }
}

// Direct tool invocation:
const score = await runTool({
  tool: llmJudgeTool,
  candidates: [makeLlmJudgeDriver(judge, { threshold: 0.7 })],
  input: { output: "the produced answer", criteria: "Is the answer helpful?" },
})

// Or as a suite scorer:
const binding = bindScorer(
  llmJudge<Answer>({
    id: "helpfulness",
    judge,
    criteria: "Is the answer helpful and correct?",
    threshold: 0.7,
    mapOutput: ({ output }) => output.text,
  }),
)
```

`passed` 决议:当法官的裁决包括明确 `passed`, (中文(简体) ), 这个 **赢** 一个法官说: `passed: false` 永远不能被高地压倒 `value`,反之亦然。 否则 `passed = value >= threshold` (单位:千美元)`threshold` 默认为 `0.5`) (中文(简体) ).

真正的适配电线 `JudgeFn` 直至代理会议或主管会议 法官门是一个有文件记载的后续行动——不是在这个一揽子计划中建立的.

## 样式计分器

再来五个 `eval.*` 托尔合同 `src/style/` (见DESIGN.md §7: `factory` 计划生产带/门 这些回。 两个是 确定性——捆绑在一起 `styleScorersProvider` 完全一样 `evalScorersProvider` - 3个是模型后置的,每个模型由 `make*Driver(...)` 关闭的工厂 一个注入,供应商中立 能力。 没有LLM SDK,没有网络依赖性,与纪律相同 `eval.llm-judge`。 。 。 .

| 工具标识 | 投入 | 行为 |
| --- | --- | --- |
| `eval.text-stats` | `{ text, thresholds? }` | 决取相取. 计算出弹行比、第一人称比、提问率和平均句长(+) `inBand`) 超过法文本. `passed` 来源于呼叫器提供 `thresholds` (单位:千美元)`maxBulletsRatio` 默认为 0.02, `minFirstPersonRatio` 默认为 0.6, `lengthBand` 默认 `{min: 5, max: 30}` words)——这个工具没有固定的门. |
| `eval.lexicon-hit-rate` | `{ text, lexicon (min 1), threshold? }` | 决取相取. 分数 `lexicon` 以整体表示的术语 `text`,Unicode-aware(出现术语如 `écrire` 正确匹配; ASCII `\b` 会想念他们。 文本和术语在匹配前为NFC-正态. `passed = hitRate >= threshold` (默认为0.5). 与纯助手建立签名词典离线 `extractLexicon(corpusTexts, { top?, minLen?, background? })` 与 `background`而不是原始频率(一个简单的频率比估测器,而不是完全差异加权的Dirichlet估测器). |
| `eval.style-pairwise` | `{ reference, a, b, criteria }` | 通过模型支持 `makeStylePairwiseDriver(judge: JudgeFn)` - 重新使用 `eval.llm-judge` `JudgeFn` 结接( 原判 ) `judgeVerdictSchema`; 错误的判决失败而不是宣传 `NaN`) (中文(简体) ). `value` 编码偏好(1=) `a` 赢, 0 = `b` 胜负,0.5=平分). 纯洁的帮助者 `pairwiseWinRate(verdicts)` 合计 `PairwiseVerdict[]` (每个携带要求的 `item` 页:1 `{ winRate, kappa, n, nNormal, nSwapped, balanced }`数字 : `winRate` 平均正常订单和相换订单利率(回落到所存在的先后顺序,通过 `balanced: false`(一) 当一个人完全失踪时; `kappa` 科恩的Kappa在两位代表人数最多的法官之间 `item` (所以同一物品上的普通+被擦伤的一对是一分观察,不是二分观察)——这是 `null`,不是默认 `1`当法官人数少于两名或少于两个共同项目时,a `null` 必须是门故障,不能跳过. |
| `eval.style-embedding` | `{ candidate, references[] (min 1) }` | 通过模型支持 `makeStyleEmbeddingDriver(embed: EmbedFn)`, (中文(简体) ), `EmbedFn = (texts) => Promise<number[][]>`。 。 。 . `value` = 余弦相似度 `candidate` 页:1 `references` centroid, 夹到 `[0, 1]` 通过 `max(0, cosine)` - 不通过 `(cosine + 1) / 2`,使非信息正交候选人与默认通过阈值相同。 考生等于百分数分数1;正交或对立考生得分为0. 异相嵌入维度(相匹配的候选/参考向量) 以一个理由来失败分数,而不是默默地粘贴/truncing. 纯助手 : `cosineToCentroid(candidate, references)` (掷出) `EmbeddingDimensionError` 关于维度不匹配——工具边界的呼叫者必须抓住它. |
| `eval.outline-fidelity` | `{ outline, answer }` | 通过模型支持 `makeOutlineFidelityDriver(judge: JudgeFn)`。 。 。 . `value` = 判断范围; `passed = value >= 0.95` a 包括: **已固定** 门,从来没有被法官自己压倒 `passed` (不一样) `eval.llm-judge`'"阈值语义". 原判通过 `judgeVerdictSchema`; 错误的判决失败分数. |

使用法文文本的公约 `eval.text-stats`: 第一人称标记为 `je`, (中文(简体) ), `j'`, (中文(简体) ), `moi`, (中文(简体) ), `mon`编号 :`ma`编号 :`mes`, (中文(简体) ), `me`编号 :`m'`, (中文(简体) ), `nous`, (中文(简体) ), `notre`编号 :`nos`, (中文(简体) ), `mien(ne)(s)`; 弹出线从 `-`, (中文(简体) ), `*`, (中文(简体) ), `•`标记 喜欢 `1.` 后为白空间( e)`1.5 million` 财务报告和审定财务报表 `-42 degrés` 是传教士, 不是子弹。 按通用法语缩写划分警卫的刑期 (单位:千美元)`M.`, (中文(简体) ), `Mme`, (中文(简体) ), `Dr`, (中文(简体) ), `etc.`, (中文(简体) ), `cf.`, (中文(简体) ), `p. ex.`)和孤立的资本首字母 (单位:千美元)`J. Dupont`因此,这些期限不被视为句尾.

```ts
import { runTool } from "@agentproto/driver"
import { textStatsTool, styleScorersProvider } from "@agentproto/eval"

const score = await runTool({
  tool: textStatsTool,
  candidates: [styleScorersProvider],
  input: { text: "Je pense que ceci illustre bien mon propos.", thresholds: { minFirstPersonRatio: 0.5 } },
})
```

## 作为CI门

`toVitest` 将套房改为测试登记——一个 `it(caseId)` 百分比 并宣称每个计分员都通过了 维特自己的 `describe` 编号 : `it` 编号 : `expect` 为: **已注射**,所以这个包裹没有带维特 运行时间依赖 :

```ts
import { describe, it, expect } from "vitest"
import { toVitest } from "@agentproto/eval"

toVitest(
  suite,
  { target: async ({ prompt }) => ({ text: prompt === "hi" ? "hello" : "world", latencyMs: 10 }) },
  { describe, it, expect },
)
```

## 出口

-   `runEval`, (中文(简体) ), `bindScorer` - 电子控制带(`EvalCase`, (中文(简体) ), `ScorerBinding`, (中文(简体) ), `BoundScorer`, (中文(简体) ), `EvalSuite`, (中文(简体) ), `TypedEvalSuite`, (中文(简体) ), `EvalReport`, (中文(简体) ), `CaseReport`, (中文(简体) ), `CaseScore`, (中文(简体) ), `RunEvalOptions`(中文(简体) )
-   `EVAL_EVENT_SCHEMA`, (中文(简体) ), `EvalEvent` 遥测-端口事件联盟
-   `toVitest` ——CI出入口大桥(`VitestHooks`, (中文(简体) ), `ExpectApi`, (中文(简体) ), `ToVitestOptions`(中文(简体) )
-   `JsonValue`, (中文(简体) ), `JsonObject`, (中文(简体) ), `jsonValueSchema` - 犬科JSON模型
-   `scoreSchema`, (中文(简体) ), `Score`
-   `exactMatchTool` 编号 : `exactMatchImpl`
-   `regexMatchTool` 编号 : `regexMatchImpl`
-   `jsonSchemaValidTool` 编号 : `jsonSchemaValidImpl` (单位:千美元)`MinimalJsonSchema`(中文(简体) )
-   `latencyBudgetTool` 编号 : `latencyBudgetImpl`
-   `evalScorersProvider` - 内置的PROVIDER捆绑所有四个
-   `llmJudgeTool` - 那个 `eval.llm-judge` TOOL合同
-   `makeLlmJudgeDriver` - 建立一个DRIVER,关闭一个注射 `JudgeFn`
-   `llmJudge` ——方便:建设即用即用 `ScorerBinding` 在法官身边
-   `JudgeFn`, (中文(简体) ), `JudgeVerdict`, (中文(简体) ), `judgeVerdictSchema`, (中文(简体) ), `LlmJudgeInput`, (中文(简体) ), `MakeLlmJudgeDriverOptions`, (中文(简体) ), `LlmJudgeBinding`
-   `textStatsTool` 编号 : `textStatsImpl` ——外加纯助工 `bulletsRatio`, (中文(简体) ), `firstPersonRatio`, (中文(简体) ), `questionRate`, (中文(简体) ), `meanSentenceLength`, (中文(简体) ), `splitSentences`, (中文(简体) ), `computeTextStats` (单位:千美元)`TextStats`, (中文(简体) ), `LengthBand`(中文(简体) )
-   `lexiconHitRateTool` 编号 : `lexiconHitRateImpl` 加上 `extractLexicon` (单位:千美元)`ExtractLexiconOptions`(中文(简体) )
-   `styleScorersProvider` 将两者捆绑在一起 决断风格计分器
-   `stylePairwiseTool`, (中文(简体) ), `makeStylePairwiseDriver`, (中文(简体) ), `pairwiseWinRate` (单位:千美元)`StylePairwiseInput`, (中文(简体) ), `PairwiseWinner`, (中文(简体) ), `PairwiseVerdict`, (中文(简体) ), `PairwiseWinRateResult`(中文(简体) )
-   `styleEmbeddingTool`, (中文(简体) ), `makeStyleEmbeddingDriver`, (中文(简体) ), `cosineToCentroid`, (中文(简体) ), `EmbeddingDimensionError` (单位:千美元)`StyleEmbeddingInput`, (中文(简体) ), `EmbedFn`, (中文(简体) ), `MakeStyleEmbeddingDriverOptions`(中文(简体) )
-   `outlineFidelityTool`, (中文(简体) ), `makeOutlineFidelityDriver` (单位:千美元)`OutlineFidelityInput`(中文(简体) )
-   `parseVerdict` ——共享 `style/` 助手: 验证一个原始判断返回值 反对 `judgeVerdictSchema`返回时 `null` 输入错误

## 许可证

麻省理工学院

## 常见问题

### @agentproto/eval 是什么？

AIP-14 TOOL合同\+AIP-30 PROVIDER内置的1份合同的确定性参考分数。 计分器是一个工具,其输出Schema是共享的 Score 形状 — 没有新的计分器端口。 船舶精确相接,正格相接,json-schema-valid,和平稳预算\. 无LLM/m

### 如何安装 @agentproto/eval？

在项目目录运行 npm install @agentproto/eval，或使用 pnpm add / yarn add / bun add。

### @agentproto/eval 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agentproto/eval 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @agentproto/eval 可以商用吗？

@agentproto/eval 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @agentproto/eval 的下载量有多少？

根据 npm 官方下载统计，@agentproto/eval 在 2026/10/05 – 2026/11/03 这 30 天内被下载 1,757 次，日均约 59 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agentproto/eval 还在维护吗？

最新版本 1\.0\.1 发布于 2026/11/04（5 天前）；至今共发布 28 个版本，其中过去 12 个月发布了 28 个；首次发布于 2026/07/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。