evalsmith-mcp

每当检索器、提示词或 Agent 发生变化时，evalsmith 都能回答以下四个问题：

1. 检索效果够好吗？ 根据 qrels 和排序结果计算 recall@k、precision@k、nDCG@k、命中率和 MRR。
2. 哪个配置更好，差距是否真实？ 对 2-3 个配置进行排名，并使用带固定种子的配对自助法计算置信区间。
3. Agent 是否调用了正确的工具？ 对比轨迹与预期调用，支持严格或宽松的顺序匹配和参数匹配器。
4. 提示词变更是否造成了问题？ 对比基线输出和候选输出，检查黄金集。

所有操作都是确定性的，并且可离线运行。你也可以使用大模型评判器征求第二意见，但它默认关闭，且绝不会决定最终结果。结果可输出为终端表格、Markdown、JSON、JUnit XML 或自包含 HTML 报告；GitHub Action还能将评估结果用作合并门禁。

---

同一核心上的多个接口

flowchart LR
    subgraph Clients
        A[MCP client<br/>desktop app, IDE, agent]
        B[Remote MCP client<br/>or service]
        C[Terminal / CI job]
        D[GitHub workflow]
    end
    subgraph evalsmith
        S1[MCP server<br/>stdio]
        S2[MCP server<br/>Streamable HTTP, stateless]
        S3[CLI<br/>evalsmith run]
        S4[GitHub Action<br/>uses: evalsmith-mcp@v0]
        CORE[(src/core<br/>metrics, bootstrap, matchers,<br/>checks, gates, reports)]
    end
    A --> S1 --> CORE
    B --> S2 --> CORE
    C --> S3 --> CORE
    D --> S4 --> CORE
    S3 -. exit code + JUnit + HTML .-> C
    S4 -. outputs + job summary .-> D

接口	入口	使用者	存在的意义
MCP over stdio	dist/mcp/server.js	桌面 MCP 客户端、IDE 助手、本地 Agent	助手可以在对话过程中为运行评分、比较配置或审查跟踪记录，并返回带类型的 structuredContent。
MCP over Streamable HTTP	EVALSMITH_TRANSPORT=http	远程客户端、内部平台、MCP Inspector	通过网络提供相同的工具。无状态：无需存储会话，可水平扩展。
CLI / CI	evalsmith run evalsmith.yaml	流水线和终端	--fail-under recall@5=0.8 可将指标设为合并门槛。提供退出代码、Markdown 摘要、JUnit XML 和 HTML 报告。
GitHub Action	uses: diegoperezg7/evalsmith-mcp@v0	GitHub 工作流	以步骤形式设置相同的门槛，并提供输出、作业摘要，且无需安装。

这四种接口都会调用 src/core 中的相同函数。MCP 工具只是轻量适配器：使用 Zod 解析输入，调用核心，并返回通过输出架构验证的 structuredContent。

---

MCP 接口

flowchart TB
    subgraph Tools
        T1[evaluate_retrieval]
        T2[compare_configs]
        T3[check_tool_calls]
        T4[detect_prompt_regression]
        T5[generate_report]
        T6[run_suite]
    end
    subgraph Resources
        R1["evalsmith://examples/{name}<br/>12 synthetic datasets + suite"]
    end
    subgraph Prompts
        P1[compare_rag_configs]
        P2[audit_agent_trace]
        P3[review_prompt_change]
    end
    T1 -- structuredContent --> T5
    T2 -- structuredContent --> T5
    T3 -- structuredContent --> T5
    T4 -- structuredContent --> T5
    classDef tool fill:#ffedd5,stroke:#c2410c,color:#431407
    classDef res fill:#e0f2fe,stroke:#0369a1,color:#082f49
    classDef prom fill:#ede9fe,stroke:#6d28d9,color:#2e1065
    class T1,T2,T3,T4,T5,T6 tool
    class R1 res
    class P1,P2,P3 prom

工具

每个工具都声明了输入和输出 Zod schema，返回 structuredContent 和一个 JSON 文本块，并标注为只读且不会造成破坏。其中四个工具还具有幂等性，并限定在封闭世界范围内。detect_prompt_regression 和 run_suite 被声明为开放世界且非幂等：注释因工具而异；启用评审器后，它们会调用外部模型，其回答可能有所不同。评审器关闭时（默认设置），它们的行为与其他工具相同。

工具	输入	输出
evaluate_retrieval	qrels、run、可选的 k 列表	每个 k 对应的平均召回率/精确率/nDCG/命中率、MRR、每个查询的值、已跳过和缺失的查询
compare_configs	qrels、2-3 个 {name, run}、主 metric、bootstrap {samples, seed, confidence}	带区间的排名、获胜者、亚军、差值的配对区间、significant
check_tool_calls	trace（按日志记录的格式，支持 evalsmith、Anthropic Messages、OpenAI Chat 或 Responses）、expected、order: strict | lax	passed、分数、每个预期调用的匹配位置和原因、意外调用
detect_prompt_regression	golden、baseline、candidate、可选的 judge {enabled}	结论、通过率、回归、改进、每个用例的失败情况、启用评审器时的评审器投票
generate_report	上述任意结果、gates、format: markdown | json | junit	passed、渲染后的报告
run_suite	可选的 config 路径，指向 evalsmith.yaml、gates、judge、format	passed、渲染后的报告和每个部分的结果（从套件文件中读取）

run_suite 运行与 evalsmith run 相同的套件，因此客户端可以评估存储在文件中的数据，而不必将其粘贴到对话中。它只会读取工作区根目录（EVALSMITH_ROOT；默认是服务启动时所在的目录）内的内容，并会在检查前解析符号链接。未提供 config 时，它会运行捆绑的示例套件。

无效输入（未知指标、重复的配置名称、没有相关文档的 qrels）会以 InvalidParams 工具错误返回，并附带模型可据此采取操作的消息。评审器端点无法访问或返回 HTTP 错误时，会产生 InternalError。

资源

evalsmith://examples/{name} 会列出并提供 examples/datasets 中的合成数据集，以便客户端在接入自己的数据前试用每个工具：

名称	内容
rag-corpus、rag-queries、rag-qrels	虚构发票应用的 20 篇帮助中心文章、12 个问题、分级相关性判断
rag-run-bm25、rag-run-hybrid、rag-run-hybrid-rerank	三种检索配置的 Top-10 排名
agent-trace、agent-expected	支持 Agent 退还一笔重复扣款的过程，以及它应该进行的调用
prompts-golden、prompts-baseline、prompts-candidate、prompts-candidate-regressed	六个黄金用例和三组输出
suite	示例 evalsmith.yaml

提示词

提示词	参数	要求模型执行的操作
compare_rag_configs	metric	比较配置，报告差距及其区间，并指出表现最弱的查询
audit_agent_trace	order	检查跟踪记录，并为每个失败步骤提出最小修复方案
review_prompt_change	candidate	检测回归、生成 Markdown 报告，并决定是否发布

与 MCP 客户端的对话

sequenceDiagram
    autonumber
    actor User
    participant Host as MCP client (LLM host)
    participant ES as evalsmith (stdio)
    participant Core as src/core

    User->>Host: "Is the reranker worth it on our help-center set?"
    Host->>ES: initialize, tools/list, resources/list
    ES-->>Host: 6 tools + JSON Schemas, 13 resources
    Host->>ES: resources/read evalsmith://examples/rag-qrels (+ 3 runs)
    ES-->>Host: qrels and runs as JSON
    Host->>ES: tools/call compare_configs {metric: "ndcg@5", configs: [...]}
    ES->>Core: compareConfigs(qrels, configs, "ndcg@5", {seed: 42})
    Core-->>ES: ranking, intervals, paired delta
    ES-->>Host: structuredContent {winner: "hybrid+rerank", significant: true, ...}
    Host->>ES: tools/call generate_report {format: "markdown", comparison}
    ES-->>Host: Markdown report
    Host-->>User: "Yes: +0.153 nDCG@5 over hybrid, 95% CI [0.069, 0.251]."

---

指标

对于查询 $q$，其相关集合为 $R_q$（等级 $> 0$ 的文档），排名为 $D_q$，其中 $D_q^{k}$ 表示前 $k$ 个文档：

\mathrm{Recall@}k = \frac{|R_q \cap D_q^{k}|}{|R_q|}
\qquad
\mathrm{Precision@}k = \frac{|R_q \cap D_q^{k}|}{k}
\qquad
\mathrm{HitRate@}k = \mathbb{1}\left[\,R_q \cap D_q^{k} \neq \varnothing\,\right]

\mathrm{RR}_q = \frac{1}{\text{rank of the first relevant document}}
\qquad
\mathrm{MRR} = \frac{1}{|Q|}\sum_{q \in Q} \mathrm{RR}_q

\mathrm{DCG@}k = \sum_{i=1}^{k} \frac{\mathrm{rel}_i}{\log_2(i+1)}
\qquad
\mathrm{nDCG@}k = \frac{\mathrm{DCG@}k}{\mathrm{IDCG@}k}

$\mathrm{rel}_i$ 是排名第 $i$ 位文档的分级相关性判断（采用线性增益，与 trec_eval 一致），IDCG 是按判断等级降序排列后的 DCG。报告值为已判断查询的均值。

约定如下，均已由测试覆盖：

• 判断等级全为 0 的查询会被跳过，并列在 skippedQueries 中。
• 在运行结果中缺失的已判断查询得分为 0，并列在 missingFromRun 中。
• Precision 除以 $k$，而不是排名长度。
• 排名中重复的文档 ID 仅保留首次出现的位置，与 trec_eval 一致，因此运行结果不能通过重复相关文档获得超过 1 的分数。
• 截断值从 1 开始：不接受 recall@0。

示例（tests/core/retrieval.test.ts）：判断等级为 a=2, b=1, c=0，排名为 d, a, e, b, c。 DCG@5 $= 2/\log_2 3 + 1/\log_2 5 = 1.69254$，IDCG@5 $= 2/\log_2 2 + 1/\log_2 3 = 2.63093$，因此 nDCG@5 $= 0.64332$；recall@3 $= 0.5$，precision@5 $= 0.4$，RR $= 0.5$。

Bootstrap。 compare_configs 会对查询进行有放回重采样，每次重采样对所有配置使用相同的索引（配对），共 samples 次；随机数来自有种子的 PRNG（mulberry32）。区间为重采样均值的百分位数。当胜出配置与第二名之差的区间不包含零时，领先结果为 significant。相同的种子在每台机器上都会得到相同的区间。

工具调用匹配器

{
  "tool": "create_refund",
  "args": {
    "invoice_id": { "type": "exact", "value": "INV-2041" },
    "reason": { "type": "any" },
    "metadata": { "type": "subset", "value": { "ticket": "T-5532" } },
    "to": { "type": "regex", "pattern": "@acme-robotics\\.example$" }
  }
}

strict 要求跟踪记录严格按照预期调用的顺序排列；超出预期序列的调用会导致检查失败，并作为失败的测试用例出现在 JUnit 中。lax 忽略顺序，并通过最大二分匹配（增广路径）将预期调用与跟踪记录中的调用配对，因此，宽松匹配器不会抢占严格匹配器唯一能接受的调用。额外调用会被报告，但不会导致失败。每个匹配器（包括 exact）在缺少参数时都会失败。

提示词检查

exact（默认会先去除首尾空白）、regex、contains（默认不区分大小写）、json_schema（解析输出并使用 Ajv 验证）和 length（字符数的 min / max）。回归指基准版本通过、候选版本失败的用例。缺少输出视为失败。

可选的评审器会将两个输出发送到任意兼容 OpenAI 的 /chat/completions 端点（包括 Ollama），温度设为 0。为消除位置偏差，每个用例会评审两次：先将基准版本作为答案 A，再将其作为答案 B。只有两种顺序的结果一致时，某一方才算胜出；结果不一致则视为平局。每个用例会产生两次请求。评审器的投票会与判定结果一并报告。

---

快速入门

npx -y evalsmith-mcp                       # MCP server on stdio
npm install -g evalsmith-mcp               # or install the `evalsmith` CLI and `evalsmith-mcp` server
docker build -t evalsmith-mcp . && docker run --rm -i evalsmith-mcp   # or run the server in a container

要运行打包的示例和源代码中的测试：

git clone https://github.com/diegoperezg7/evalsmith-mcp.git
cd evalsmith-mcp
npm ci            # also builds dist/ through the prepare script
npx playwright install chromium   # the HTML report tests open it in a real browser
npm test          # metrics, traces, MCP in-memory + HTTP, CLI exit codes, HTML report, action

node dist/cli/index.js run examples/evalsmith.yaml

连接 MCP 客户端（stdio）

在终端中运行：

claude mcp add evalsmith -- npx -y evalsmith-mcp     # Claude Code
codex mcp add evalsmith -- npx -y evalsmith-mcp      # Codex CLI
code --add-mcp '{"name":"evalsmith","command":"npx","args":["-y","evalsmith-mcp"]}'   # VS Code

其他桌面 MCP 客户端读取类似这样的 mcpServers 配置块（examples/mcp-client-config.json）：

{
  "mcpServers": {
    "evalsmith": {
      "command": "npx",
      "args": ["-y", "evalsmith-mcp"],
      "env": { "LOG_LEVEL": "warn" }
    }
  }
}

重启客户端，然后尝试 compare_rag_configs 提示词，或让它读取 evalsmith://examples/agent-trace 并进行检查。

Streamable HTTP

EVALSMITH_TRANSPORT=http EVALSMITH_HTTP_PORT=3333 node dist/mcp/server.js
curl -s localhost:3333/healthz                  # {"status":"ok","version":"0.1.0"}
npx @modelcontextprotocol/inspector             # connect to http://127.0.0.1:3333/mcp

变量	默认值	用途
EVALSMITH_TRANSPORT	stdio	stdio 或 http
EVALSMITH_HTTP_HOST / EVALSMITH_HTTP_PORT	127.0.0.1 / 3333	HTTP 绑定地址
EVALSMITH_JUDGE_BASE_URL	http://localhost:11434/v1	可选评审器使用的兼容 OpenAI 的端点
EVALSMITH_JUDGE_MODEL	llama3.1:8b	评审器模型
EVALSMITH_JUDGE_API_KEY	unset	仅用于托管端点
EVALSMITH_ROOT	当前目录	run_suite 可从中读取套件和数据的目录
LOG_LEVEL	info	pino 日志级别；日志始终输出到 stderr

---

CLI 和 CI

evalsmith run <config> [--fail-under metric=value ...] [--format table|json|markdown|html]
                       [--report file.{md,json,xml,html}] [--report-format markdown|json|junit|html]
evalsmith doctor [config] [--judge]

门槛接受 recall@k、precision@k、ndcg@k、hit_rate@k、mrr、tool_calls（check_tool_calls 的分数）和 prompt_pass_rate。YAML 文件中的门槛同样适用；同名的命令行门槛会覆盖它。即使未设置门槛，提示词回归或工具调用检查失败也会导致运行失败。

退出代码	含义
0	所有门槛均通过，且没有回归
1	某个门槛低于阈值、候选版本出现回归，或工具调用不匹配
2	用法错误、配置无效、指标未知、数据集不可读、评估器端点不可用

实际输出

在捆绑的数据集上运行 node dist/cli/index.js run examples/evalsmith.yaml（examples/evalsmith.yaml）：

evalsmith · ledgerly-support-assistant

Retrieval (12 queries, MRR 0.8403)
┌────┬────────┬───────────┬────────┬──────────┐
│  k │ recall │ precision │   nDCG │ hit rate │
├────┼────────┼───────────┼────────┼──────────┤
│  1 │ 0.4583 │    0.7500 │ 0.6667 │   0.7500 │
│  3 │ 0.7500 │    0.4167 │ 0.7442 │   0.9167 │
│  5 │ 0.9167 │    0.3000 │ 0.8059 │   1.0000 │
│ 10 │ 1.0000 │    0.1667 │ 0.8285 │   1.0000 │
└────┴────────┴───────────┴────────┴──────────┘

Comparison on ndcg@5 (paired bootstrap, 2000 samples, seed 42)
┌───┬───────────────┬────────┬──────────────────┐
│ # │ config        │ ndcg@5 │ 95% CI           │
├───┼───────────────┼────────┼──────────────────┤
│ 1 │ hybrid+rerank │ 0.9588 │ [0.8950, 1.0000] │
│ 2 │ hybrid        │ 0.8059 │ [0.6875, 0.9141] │
│ 3 │ bm25          │ 0.5596 │ [0.3782, 0.7354] │
└───┴───────────────┴────────┴──────────────────┘
hybrid+rerank wins on ndcg@5 (0.9588), +0.1528 over hybrid; 95% interval of the gap [0.0692, 0.2506] excludes zero.

Agent tool calls (strict)
┌──────────────────┬─────────┬────────┬───────┐
│ expected         │ matched │ status │ notes │
├──────────────────┼─────────┼────────┼───────┤
│ search_customers │ #1      │ pass   │       │
│ get_invoice      │ #2      │ pass   │       │
│ create_refund    │ #3      │ pass   │       │
│ send_email       │ #4      │ pass   │       │
└──────────────────┴─────────┴────────┴───────┘
All 4 expected call(s) matched (strict order).

Prompt regression
┌───────────────────────┬──────────┬───────────┬────────────────────┐
│ case                  │ baseline │ candidate │ candidate failures │
├───────────────────────┼──────────┼───────────┼────────────────────┤
│ classify-intent       │ pass     │ pass      │                    │
│ extract-invoice-id    │ pass     │ pass      │                    │
│ refund-policy-summary │ fail     │ pass      │                    │
│ due-date-format       │ pass     │ pass      │                    │
│ refuse-card-number    │ pass     │ pass      │                    │
│ refund-payload        │ pass     │ pass      │                    │
└───────────────────────┴──────────┴───────────┴────────────────────┘
No regressions across 6 case(s). Pass rate 83.3% -> 100.0%.

Gates
┌────────────┬────────┬────────┬────────┐
│ metric     │    min │ actual │ status │
├────────────┼────────┼────────┼────────┤
│ recall@5   │ 0.8000 │ 0.9167 │ pass   │
│ ndcg@5     │ 0.7500 │ 0.8059 │ pass   │
│ tool_calls │ 1.0000 │ 1.0000 │ pass   │
└────────────┴────────┴────────┴────────┘

PASS

提高标准后，同一次运行会导致构建失败：

$ node dist/cli/index.js run examples/evalsmith.yaml --fail-under recall@5=0.95 --fail-under mrr=0.9 --report report.xml
...
Gates
┌────────────┬────────┬────────┬────────┐
│ metric     │    min │ actual │ status │
├────────────┼────────┼────────┼────────┤
│ recall@5   │ 0.9500 │ 0.9167 │ FAIL   │
│ ndcg@5     │ 0.7500 │ 0.8059 │ pass   │
│ tool_calls │ 1.0000 │ 1.0000 │ pass   │
│ mrr        │ 0.9000 │ 0.8403 │ FAIL   │
└────────────┴────────┴────────┴────────┘

FAIL · 2 gate(s) below threshold
Report written to report.xml
$ echo $?
1

HTML 报告

--report report.html（或在标准输出上使用 --format html）会将整个运行结果写入一个 HTML 文件，该文件可离线打开，并遵循系统的浅色或深色模式：

• 判定结果，以及每个门槛对应的一张卡片，显示其数值、阈值和状态；
• 按 k 展示检索指标，使用条形图并显示查询上的自助法区间，同时标出门槛；
• 配置对比，包括每个区间、胜出者和与次优者之间的差距；
• 预期与实际的工具调用，匹配的调用对带有链接，不匹配项会标出；
• 每个黄金用例的基线与候选版本对比，失败的检查点一下即可查看。

深色模式和已展开的提示词回归

数据集文本（用例 ID、工具名称、失败消息）以 JSON 形式嵌入不可执行的 <script type="application/json"> 块中，并且只通过 textContent 渲染。内容安全策略禁止网络访问，并仅允许执行页面自身通过哈希标识的脚本。测试会在 Chromium 中打开一份包含大量标记的报告，并检查报告中的内容不会运行。运行 npm run docs:screenshots 可重新生成上方的图片。

---

GitHub Action

- uses: actions/checkout@v5
- uses: diegoperezg7/evalsmith-mcp@v0
  id: evals
  with:
    config: evals/evalsmith.yaml
    fail-under: |
      recall@5=0.8
      ndcg@10=0.7
      tool_calls=1
    html-report: evalsmith-report.html

当某个门槛低于阈值、提示词候选版本出现退化或工具调用不匹配时，此步骤会失败，并将包含判定结果的 Markdown 报告写入作业摘要。它通过打包的 node24 脚本运行与 CLI 相同的核心逻辑，无需安装步骤，也不使用 shell。examples/github-workflow.yml 是一个完整的工作流示例，其中还会将 HTML 报告保留为构建产物，并将 JUnit XML 发布为检查运行。

输入	默认值	说明
config	evalsmith.yaml	套件文件。其中的数据集路径相对于该文件
fail-under		每行一个 metric=value。添加到套件文件中的门槛，并覆盖同名门槛
report-file		报告文件：.md、.json、.xml（JUnit）或 .html
report-format	根据扩展名	markdown、json、junit 或 html
html-report		自包含 HTML 报告的路径
upload-summary	true	将 Markdown 报告附加到作业摘要

输出	说明
verdict	pass 或 fail
failed-gates	低于阈值的门槛
metrics	检索指标（JSON），例如 fromJSON(steps.evals.outputs.metrics)['recall@5']
mrr	检索运行的 MRR
tool-calls	工具调用得分，匹配数 / 预期数
prompt-pass-rate	黄金集上的候选版本通过率
prompt-regressions	基线版本通过而候选版本失败的案例
winner	比较中的胜出配置
report-file	report-file 的路径；未请求时为空
html-report	HTML 报告的路径；未请求时为空

套件中不存在的部分，其输出为空。打印到日志的数据集文本会被 ::stop-commands:: 包裹，因此案例 ID 或工具名称无法发出工作流命令。与 CLI 一样，评审器会从步骤环境中读取 EVALSMITH_JUDGE_*。

不使用该 Action 时，可在任何 CI 中通过 CLI 执行相同操作：

npx evalsmith run evals/evalsmith.yaml --fail-under recall@5=0.8 --format markdown --report evalsmith-report.xml >> "$GITHUB_STEP_SUMMARY"

---

套件文件

name: ledgerly-support-assistant
retrieval:
  qrels: datasets/rag/qrels.json # { queryId: { docId: grade } }
  run: datasets/rag/runs/hybrid.json # { queryId: [docId, ...] }
  k: [1, 3, 5, 10]
compare:
  metric: ndcg@5
  configs:
    - { name: bm25, run: datasets/rag/runs/bm25.json }
    - { name: hybrid, run: datasets/rag/runs/hybrid.json }
    - { name: hybrid+rerank, run: datasets/rag/runs/hybrid-rerank.json }
  bootstrap: { samples: 2000, seed: 42, confidence: 0.95 }
agent:
  trace: datasets/agent/trace.json
  expected: datasets/agent/expected.json
  order: strict
prompts:
  golden: datasets/prompts/golden.json
  baseline: datasets/prompts/baseline.json
  candidate: datasets/prompts/candidate.json
  judge: { enabled: false }
gates:
  recall@5: 0.8
  ndcg@5: 0.75
  tool_calls: 1.0

每个部分都是可选的。路径相对于 YAML 文件。

---

与 ragcompass 配合使用

ragcompass 会分析语料库，并建议如何配置 RAG 流水线：解析器、分块、top-k、混合搜索、重排。evalsmith 用于检查该配置是否经得起考验：

flowchart LR
    A[Documents] --> B[ragcompass analyze<br/>recommended configs]
    B --> C[Index 2-3 candidate configs]
    C --> D[Run the eval queries<br/>save rankings]
    D --> E[evalsmith compare_configs<br/>winner + intervals]
    E --> F[evalsmith run in CI<br/>--fail-under gates]

---

设计决策

• 确定性优先。 指标、匹配器和检查项都是纯函数，并通过手工计算的测试验证。无需模型即可得出判定，因此不同运行之间的结果不会漂移，也不需要付费 API 密钥。
• 默认不启用裁判。 启用后，它会通过任何兼容 OpenAI 的端点运行（本地 Ollama 也可），其投票会与判定并列展示，而不会改变判定结果。
• 关注区间，而不只是均值。 12 次查询就可能让 0.03 的领先看起来很明显。使用固定种子的配对自助法，可以让不确定性清晰可见且可复现。
• 妥善实现无状态 HTTP。 无状态的 StreamableHTTPServerTransport 不能跨请求重复使用，因此每个 POST 请求都会创建自己的服务器和传输。注册开销很小，并且有一项测试通过真实 HTTP 连续调用两次来验证这一点。
• stdout 专供协议使用。 pino 写入 stderr，ESLint 禁止在 src/ 中使用 console，因此不会有多余字节破坏 stdio 传输。CLI 仅将 stdout 用于输出结果。
• 一个 schema，三种用途。 src/core/schemas.ts 中的 Zod schemas 用于验证 MCP 输入、生成客户端可见的 JSON Schemas，并为核心代码提供类型。

---

项目布局

src/
  core/         metrics, bootstrap, tool-call matchers, prompt checks, judge, gates, reports (incl. HTML), suite runner
  mcp/          server (stdio + HTTP), tools/, resources/, prompts/
  cli/          evalsmith run | doctor, table/json/markdown/html output
  action/       GitHub Action entry point, bundled into dist/action
  shared/       config (Zod), pino logger on stderr, MCP errors
tests/
  core/         hand-computed metrics, bootstrap, matchers, checks, reports, HTML in Chromium
  mcp/          InMemoryTransport client and real Streamable HTTP client
  cli/          exit codes 0 / 1 / 2, JUnit file, doctor
examples/
  datasets/     synthetic RAG corpus + qrels + 3 runs, agent trace, golden prompts
  evalsmith.yaml, github-workflow.yml, mcp-client-config.json

npm run check     # typecheck + eslint + prettier + vitest
npm run inspect   # MCP Inspector against the built stdio server

发布基于版本标签：release.yml 会通过 provenance 发布到 npm、MCP Registry 和 GitHub Releases，而 action 会在发布时发布到 Marketplace。docs/RELEASING.md 介绍了相关步骤，包括 action bundle 和 v0 标签。变更记录见 CHANGELOG.md。

许可证

MIT