Iris

官方

MCP原生代理评估与可观测性服务器,具备追踪日志、输出质量评估、成本追踪、12条内置评估规则、实时仪表盘及PII检测功能

你可以用 Iris MCP 做什么?

  • 记录并评分一次运行 — 让你的助手将一次智能体运行记录到 Iris 并评估其输出,然后在仪表板上查看判定结果和评分。
  • 检查安全与成本规则 — 运行 28 条内置确定性规则,检查个人身份信息、提示注入、幻觉标记和成本阈值,全程无需调用任何 LLM。
  • 检查并编辑规则 — 列出内置规则并查看或修改它们,因为每条规则都可检查和编辑。
  • 添加自定义规则 — 通过 config.json 中的 eval.plugins 加载你编写的代码规则,并通过文件哈希固定版本。
  • 比较运行结果 — 在仪表板的 Runs 视图中并排打开针对相同问题的两次运行,并查看区间。
  • 根据判定结果设置 CI 门禁 — 使用 --evaluate --fail-on any 运行 ingest,只要判定结果不是通过,就让任务失败。

文档

Iris — 别凭感觉发布智能体

CI OpenSSF Scorecard OpenSSF Best Practices npm version License: MIT Install in Cursor Install in VS Code

把一次智能体运行发送给 Iris,让它评判其质量、安全性和成本——在你的机器上,无需 SDK 或账户。 大多数智能体项目通过运行几个记得住的提示词,再凭感觉查看输出,来检查质量。Iris 用可审计的数字取代这种做法:智能体的运行记录会存入你磁盘上的 SQLite 数据库,28 条内置规则以确定性方式为其评分——PII、提示注入、幻觉标记、成本阈值,以及智能体自身的工具调用;免费,不调用 LLM。对于语义问题,可选的 LLM 评判器会处理,并设有严格的单次评估成本上限。每条规则都可检查、可编辑,因为无法审计的评判器,不过是披着数字外衣的感觉。采用 MIT 许可证,无遥测。除非你启用以下功能之一,否则任何内容都不会离开你的机器:OpenTelemetry 端点(IRIS_OTEL_ENDPOINT),它会将追踪导出到你指定的收集器;使用你自己的密钥的 LLM 评判器,它会将待评判文本发送给相应服务商,且其引用检查会获取输出所引用的页面;或者 Webhook,它会向你设置的地址发送 ID、评判结果和规则名称,绝不发送文本。

需要 Node.js 22.13 或更高版本。 使用 node --version 检查。

The demo: Failures, a failure opened, two runs compared

演示数据库由 scripts/demo-media.mts 录制;源文件位于 demo.mp4。静态图:dashboard-overview.png。

60 秒内看到一次失败

无需接入智能体,无需配置——只需一条命令:

npx @iris-eval/mcp-server --demo

这会创建一个演示数据库——包含五个小型智能体、两周的运行记录,以及全部由引擎自身生成的评判结果——并基于该数据库启动仪表板,地址为 **http://localhost:6920**(首次运行时会自动在浏览器中打开)。仪表板默认显示 Failures:失败项按严重程度和时间从高到低排列,每张卡片都标明规则及其证据。值得点进去看看——安全规则捕获到的 PII 泄露;摘要器遵从了论坛帖子中的隐藏指令;源文档从未提及的数字;对同一组十二个问题的两次运行进行区间比较(Runs);已部署的自定义规则和已暂停的规则及其审计记录;以及带有理由说明的失败 LLM 评判分数。

演示数据存放在独立数据库中(位于 Iris 主目录下的 demo.db——macOS/Linux 上为 ~/.iris,Windows 上为 %USERPROFILE%\.iris),不会与真实追踪记录混在一起。使用一条命令即可全部删除:

npx @iris-eval/mcp-server --demo-clear

接入你自己的智能体

首先,验证安装在这台机器上能正常工作——此操作离线运行,不会打开你的任何内容:

npx @iris-eval/mcp-server --self-test   # exit 0 = healthy

然后将 Iris 添加到你的 MCP 客户端。一条命令即可写入客户端自己的配置文件,保留其中的所有其他服务器,并固定为你运行的版本:

npx -y @iris-eval/mcp-server install claude-code

支持的客户端:claude-code、claude-desktop、cursor、windsurf、continue、vscode、cline、zed、codex、gemini。install --list 会显示在这台机器上找到的客户端、各自运行的 Iris 版本以及读取的文件;install <client> --uninstall 可再次移除 Iris。所有客户端共用一个数据库,因此升级后请使用 install --upgrade 一次性迁移所有客户端(更新)。重启客户端以加载配置。

Claude Desktop:一键安装。 从 0.20.0 起的每个版本都会附带 iris-eval.mcpb,即一个 MCP Bundle:下载最新版本并打开,Claude Desktop 就会显示安装对话框。对话框中的所有选项都不是必需的——用于 LLM 评判器的 Anthropic 或 OpenAI 密钥是可选项,仪表板也是一个默认关闭的开关。Bundle 包含 npm 包及其依赖项,因此无需安装其他内容:只要 Claude Desktop 自带的 Node 版本为 22.13 或更高版本,它就会用该 Node 运行 Iris(Claude Desktop 1.1.6679 自带 24.13),而 Iris 会使用 Node 内置的 SQLite 将追踪记录存储在与其他安装相同的 ~/.iris 中。版本说明介绍了如何验证其签名和构建证明。

Iris 可在任何 MCP 客户端中运行,并且每个列出的客户端都有一行说明其验证方式。每次 CI 运行都会验证:Claude Code、Gemini CLI——真实客户端会根据安装程序写入的配置启动 Iris,并报告连接成功(claude mcp list、gemini mcp list),覆盖 Linux、macOS 和 Windows;Claude Code 的捕获插件钩子也会通过真实脚本运行。根据各客户端自己的 MCP 文档进行配置——安装程序会按照每个客户端文档规定的路径和格式写入文件(mcpServers 块、VS Code 的 servers、Zed 的 context_servers、Codex 的 TOML),保留注释和其他所有服务器;单元测试会依据文档验证每个路径和每种格式的写入器:Claude Desktop、Cursor、Devin Desktop (Windsurf)、Continue、VS Code、Cline、Zed、OpenAI Codex CLI。每一行都附有来源和查阅日期:https://iris-eval.com/clients. 如果想手动配置,只需添加一个代码块,包含仪表板:

{
  "mcpServers": {
    "iris-eval": {
      "command": "npx",
      "args": ["-y", "@iris-eval/mcp-server", "--dashboard"]
    }
  }
}

客户端连接后会列出 Iris 的十二个工具,仪表板地址为 http://localhost:6920. 现在把这句话发给你的智能体:

将刚才的任务记录到 Iris,并评估输出。

追踪记录及其评分会显示在仪表板上。想让 MCP 服务器以无头模式运行?从参数中移除 --dashboard——你随时可以用 npx @iris-eval/mcp-server --dashboard 打开同一个仪表板。

有一点值得提前了解: MCP 工具只有在模型决定调用时才会被调用。Iris 不会拦截你的智能体,因此只有在智能体要求记录时才会记录追踪——要么是因为你告诉它这么做,要么是因为你的代码直接调用了这些工具。告诉智能体“将此记录到 Iris 并进行评估”,它就会执行。如果你希望捕获过程不依赖模型是否选择调用,POST /api/v1/traces 正好可以做到——你的代码通过普通 HTTP 发送追踪记录,不需要模型参与(参见 docs/http-ingest.md)。路线图中的 CLI 和宿主钩子将作为同一端点的轻量客户端。

通过 HTTP 捕获(无需模型参与)

数据接收端点位于仪表板端口——默认是 6920,而不是 MCP 传输端口——且仅在仪表板运行时存在。传入 --dashboard(或设置 IRIS_DASHBOARD=true);单独使用 --transport http 不会启动它,向传输端口发送请求会返回 404。仪表板启动后,任何能够发送 HTTP 请求的程序都可以记录追踪,并可选择在同一请求中运行确定性评估。同一端口上的 GET /api/v1/capabilities 会说明此服务器能够评判的内容、每条规则所需的信息、评判器状态及启用步骤,以及各项限制——它与 MCP 资源 iris://capabilities 提供的是同一个对象,因此 HTTP 调用方也能获得 MCP 客户端在初始化时得到的信息:

curl -s -X POST "http://127.0.0.1:6920/api/v1/traces" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "support-bot",
    "input": "What is the refund policy?",
    "output": "Refunds are available within 30 days of purchase.",
    "evaluate": true,
    "eval_type": "safety"
  }'

返回 201,其中包含已存储的 trace_id 和评估结果(在 --demo 模式下,端点会以 403 拒绝写入,因此演示数据不会与真实数据混在一起)。端点接受与 log_trace 工具相同的请求体,并使用与仪表板其余部分相同的中间件栈:默认绑定到回环地址并启用 DNS 重绑定防护;如果设置了密钥,还会启用 Bearer 身份验证。关于它,有两点需要明确: 除非 Iris 使用 --api-key(或 IRIS_API_KEY)启动,否则它接受未经身份验证的写入——默认情况下,回环地址绑定会将其限制在你的机器上,因此如果要绑定到回环地址之外,请先设置密钥;它存储的内容是原样保存的——input 和 output 会按发送时的原样写入 iris.db,包括之后会被 no_pii 标记的任何文本。完整契约、字段参考和错误语义见:docs/http-ingest.md。

捕获 Claude Code 的每一轮对话(可选)

/plugin marketplace add iris-eval/mcp-server
/plugin install iris-eval-capture@iris-eval

这是一个单独安装的第二个插件:它的钩子会记录每一轮的提示词、工具调用(包括失败的调用及智能体收到的错误)和最终回答,并以提示词为键,因此中断轮次中的调用和后台子智能体的调用也会被发送;随后它会将这些内容交给 iris-eval ingest,以分离模式运行,并在存储的评估文本中对关键跨度进行脱敏——这种捕获方式不依赖模型是否决定调用工具。因 API 错误而结束的轮次会被存储,但不会进行评判;如果模型也记录了该轮次,两条追踪都会保留,插件记录的名称会标明是模型记录的。它绝不打印内容、阻塞流程或向任何地方发送数据。仅安装 iris-eval 不会改变你的轮次处理流程。限制和卸载方法见:claude-plugin-capture/README.md。

Python

pip install iris-eval
from iris_eval import IrisClient
iris = IrisClient()                       # IRIS_URL, or the running dashboard's runtime.json
iris.evaluate_output("…", input="…", agent_name="support-bot")["verdict"]   # {"state": "pass", "basis": "clean", "by": []}

这是一个基于服务器 HTTP API 的轻量客户端,适用于 0.16.0 及更高版本,并独立进行版本管理——iris_eval.__version__ 和 PyPI 页面会显示它自己的版本号,而非服务器版本:log_trace()、evaluate_output()、get_traces()、get_trace()、health()、capabilities(),支持同步和异步调用、类型化答案,以及服务器在拒绝请求时给出的原文说明;还提供 pytest 插件:一个 iris fixture,以及一个会断言评判结果状态的 assert_iris(output, expect="pass")。packages/python/README.md。

记录每一次 OpenAI 和 Anthropic 调用

from iris_eval import wrap_openai
client = wrap_openai(OpenAI(), agent_name="support-bot")   # every call: a GenAI span to POST /v1/traces, scored
import { wrapOpenAI } from '@iris-eval/sdk';
const openai = wrapOpenAI(new OpenAI(), { agentName: 'support-bot' });

只需包装一次服务商客户端,每次模型调用就会变成一个 OpenTelemetry GenAI span,发送到 OTLP 入口,并连同输入、输出、token 用量和工具调用一起存储和评分:这种捕获方式不依赖模型是否调用工具。Python 客户端中的 wrap_openai / wrap_anthropic;以及 @iris-eval/sdk 中适用于 Vercel AI SDK 的 wrapOpenAI、wrapAnthropic 和 irisMiddleware。两者目前都尚未发布(下一个 iris-eval 版本将在 PyPI 发布;@iris-eval/sdk 在首次 npm 发布前需从源码构建)。支持流式响应、SDK 的流式辅助函数和工具调用;不会修改原始客户端;即使 Iris 停机也不会导致调用失败——packages/sdk/README.md、packages/python/README.md。

为每次 LangChain 和 LangGraph 运行评分

from iris_eval.langchain import IrisCallbackHandler
graph.invoke(inputs, config={"callbacks": [IrisCallbackHandler(agent_name="support-bot")]})

每次顶层运行都会成为一条追踪记录(包含运行本身、模型调用、工具调用和作为 GenAI spans 的图节点),并记录其输入、输出、工具调用、token 用量和评判结果。Python 客户端(pip install iris-eval,0.2.0 及更高版本);JavaScript 版本为 @iris-eval/langchain(位于此仓库中,尚未发布到 npm)。两者都已在 CI 中通过真实 LangGraph 应用和脚本化模型验证;LangSmith 自带的 OpenTelemetry 导出也以同样方式验证——docs/otel-recipes.md。

无需服务器的 CI 门禁

npx -y @iris-eval/mcp-server ingest --file traces.ndjson --evaluate --fail-on any

any 会在每个非通过的评判结果上使作业失败:包括失败结果,以及未经检查的评判结果。也可以改为指定一个依据(--fail-on detector_veto),这样只有该依据不通过时才会失败。

或者使用 GitHub Action(0.16.0):它会根据你指定的评判结果使作业失败,将回执写入作业摘要,并以一条拉取请求评论发布,后续更新时会原地更新:使用 uses: iris-eval/mcp-server/.github/actions/gate@v0.21.0 和 traces: traces.ndjson——docs/ci-gate.md。 第四扇门(0.15.0):仪表板端口上的 POST /v1/traces 接收你的 OpenTelemetry 插桩已经发出的 OTLP/HTTP JSON 或 protobuf(Python SDK 的导出器只支持 protobuf,所以这也是 Python 的接入方式),并将每条 OTLP trace 转换为包含其 spans 的 Iris trace — docs/otel-integration.md;docs/otel-recipes.md 为每种框架提供一个配方(Pydantic AI、Google ADK、通过 LangSmith 接入的 LangGraph、CrewAI、Python 和 JavaScript 版 OpenAI Agents SDK、LlamaIndex、AutoGen、Microsoft Agent Framework、Semantic Kernel、Vercel AI SDK 和 Mastra),每个配方都由 fixture 验证。ingest 从 stdin 或文件读取一条 JSON trace(或 NDJSON,每行一条),将其存储起来,严格按照 evaluate_output 执行的规则进行评估,为每条 trace 输出一行包含判定结果及其依据的 JSON,并在判定结果匹配 --fail-on 时以状态码 1 退出。--dataset <id|label> 将此门禁限制为数据集中的 case keys(POST /api/v1/datasets 会将一次运行的 case keys 提取到一个数据集中),因此作业只会在你选定的用例上失败。完整配方、退出码和八种判定依据见 docs/ci-gate.md。

将规则编写为代码

eval.plugins 在 config.json 中加载你编写的规则 — 一个默认导出为 { name, kind, mechanism, version, needs, evaluate(ctx) } 的 ES 模块,并通过文件的 sha256 固定版本;如果文件在固定版本后发生更改,程序会拒绝启动,而不是运行该文件。已加载的插件会像内置规则一样触发,并在 list_rules 的 plugins 下显示。接口约定、哈希计算方法以及插件可返回的内容见:docs/plugins.md。

在你自己的进程中使用引擎

评估引擎可导入 — 无需服务器、数据库或模型:

import { EvalEngine, defaultConfig } from '@iris-eval/mcp-server/engine';

const engine = new EvalEngine(defaultConfig.eval.defaultThreshold, defaultConfig.eval.ruleThresholds, defaultConfig.eval);
const result = await engine.evaluateAll({ output: answer, input: prompt, toolCalls, costUsd });
result.verdict.state;       // 'pass' | 'fail' | 'unknown', with result.verdict.basis and result.interpretations

它与服务器运行的引擎、规则和 composer 完全相同;builtInRules()、createCustomRule()、compose() 以及已发布准确率的读取器也一并导出。

HTTP 路由的类型化客户端

import { createClient } from '@iris-eval/mcp-server/client';

const iris = createClient({ baseUrl: 'http://127.0.0.1:6920', apiKey: process.env.IRIS_API_KEY });
const { trace_id, evaluation } = await iris.logTrace({ agent_name: 'support-bot', input, output, tool_calls, evaluate: true });
evaluation?.verdict?.state;  // the same object evaluate_output returns

所有接入方式都使用同一个请求体:log_trace 和 iris-eval ingest 都接受它。请求被拒绝时,会抛出 IrisClientError,其中包含服务器原样返回的说明和状态码。每次构建都会从打包后的 tarball 检查这两个子路径。

验证安装

npx @iris-eval/mcp-server --self-test   # offline diagnostic; exit 0 = healthy, 1 = a check failed
npx @iris-eval/mcp-server --version     # prints the bare version, e.g. 1.2.3

--self-test 会先在 Iris home 不存在时创建它,并检查其是否可写(如果不可写,则以状态码 1 退出并指出路径);报告数据库搜索索引的状态(完整、后台构建目前已索引的 trace 数量,或此 SQLite 不支持 FTS5);读取数据库架构(如果此版本或固定在较旧版本的 MCP 客户端无法打开数据库,则以状态码 1 退出并提供修复方法);然后在隔离的临时 home 中运行检查 — 存储往返、检测植入的 SSN 和注入内容的安全规则、仪表板启动以及 DNS 重绑定防护。你的真实数据库只会被读取,不会被修改。Iris 写入的所有内容都位于一个目录中,即你的 Iris home:默认是 ~/.iris(Windows 上为 %USERPROFILE%\.iris),也可以是 IRIS_HOME 指定的位置。iris.db、config.json、custom-rules.json、audit.log、preferences.json 和演示文件都存放在这里;将 IRIS_HOME 指向一个临时目录,即可在不触碰真实数据的情况下试用 Iris。

按工具设置
客户端状态含义阅读
Claude Code已验证每次 CI 运行都会通过测试驱动真实客户端2026-09-25
Claude Desktop声称支持根据客户端自己的 MCP 文档配置;安装程序的路径和格式经过单元测试2026-09-25
Cursor声称支持根据客户端自己的 MCP 文档配置;安装程序的路径和格式经过单元测试2026-09-25
Devin Desktop (Windsurf)声称支持根据客户端自己的 MCP 文档配置;安装程序的路径和格式经过单元测试2026-09-25
Continue声称支持根据客户端自己的 MCP 文档配置;安装程序的路径和格式经过单元测试2026-09-25
VS Code声称支持根据客户端自己的 MCP 文档配置;安装程序的路径和格式经过单元测试2026-09-25
Cline声称支持根据客户端自己的 MCP 文档配置;安装程序的路径和格式经过单元测试2026-09-25
Zed声称支持根据客户端自己的 MCP 文档配置;安装程序的路径和格式经过单元测试2026-09-25
OpenAI Codex CLI声称支持根据客户端自己的 MCP 文档配置;安装程序的路径和格式经过单元测试2026-09-25
Gemini CLI已验证每次 CI 运行都会通过测试驱动真实客户端2026-09-25

每一行对应的检查内容见:iris-eval.com/clients。没有对应行的客户端不会被称为受支持。

npx -y @iris-eval/mcp-server install <client> 会为你写入以上所有配置。也可以按客户端手动配置:

Claude Desktop

编辑 MCP 配置文件:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

添加上面的 JSON 配置,然后重启 Claude Desktop。

Claude Code

claude mcp add --transport stdio iris-eval -- npx -y @iris-eval/mcp-server

然后重启会话(/clear 或重新启动),以加载工具。

Windows 注意事项: 不要使用 cmd /c 包装器 — 它会导致路径解析问题。npx 命令可以直接运行。

Cursor

将上面的 JSON 配置添加到 ~/.cursor/mcp.json(适用于所有项目)或工作区中的 .cursor/mcp.json,并在 iris-eval 条目中设置 "type": "stdio" — Cursor 文档将其标记为必填项。

Devin Desktop (Windsurf)

将上面的 JSON 配置添加到 mcp_config.json:macOS 和 Linux 上为 ~/.config/devin/mcp_config.json,Windows 上为 %APPDATA%\devin\mcp_config.json。

Continue

将上面的 JSON 配置另存为独立文件,放入 Continue 的 mcpServers 文件夹:~/.continue/mcpServers/iris-eval.json(适用于每个工作区)或其中的 .continue/mcpServers/iris-eval.json。

VS Code(原生 MCP)

在工作区的 .vscode/mcp.json 中添加(注意:VS Code 使用 servers,而不是 mcpServers):

{
  "servers": {
    "iris-eval": {
      "command": "npx",
      "args": ["-y", "@iris-eval/mcp-server"]
    }
  }
}

Cline

打开 Cline 的 MCP Servers 面板 → Configure MCP Servers,并将上面的 mcpServers JSON 配置添加到 cline_mcp_settings.json(~/.cline/data/settings/cline_mcp_settings.json,由 VS Code、JetBrains 和 CLI 中的 Cline 共用)。

Zed

添加到 Zed 的 settings.json:

{
  "context_servers": {
    "iris-eval": {
      "command": "npx",
      "args": ["-y", "@iris-eval/mcp-server"],
      "env": {}
    }
  }
}

OpenAI Codex CLI

添加到 ~/.codex/config.toml:

[mcp_servers.iris-eval]
command = "npx"
args = ["-y", "@iris-eval/mcp-server"]

Gemini CLI

将上面的 mcpServers JSON 配置添加到 ~/.gemini/settings.json。Gemini CLI 只会在其信任的文件夹中连接 MCP 服务器:如果 gemini mcp list 显示 iris-eval 为 Disabled,请在该文件夹中运行 /permissions。

其他支持 MCP 的客户端

Iris 是标准的 stdio MCP 服务器 — 只需一条 npx @iris-eval/mcp-server 命令,无需 SDK,也无需修改代码。如果你的客户端支持 MCP,就支持 Iris。客户端配置格式可能会变化;如有疑问,请查阅客户端的 MCP 文档,并将其指向该命令。

其他安装方式

# Global install (recommended for persistent data and faster startup)
npm install -g @iris-eval/mcp-server
iris-eval --dashboard

# Docker — two servers, two ports: 3000 = MCP HTTP transport,
# 6920 = dashboard (which also serves the POST /api/v1/traces ingest endpoint).
# The image binds 0.0.0.0 inside the container, so a key is required (see Production).
# The volume is the Iris home: the database, deployed rules and audit log persist in it.
docker run -p 3000:3000 -p 6920:6920 -v iris-data:/data \
  -e IRIS_API_KEY="$(openssl rand -hex 32)" ghcr.io/iris-eval/mcp-server

提示: 全局安装(npm install -g)会将 trace 持久化存储在 ~/.iris/iris.db。使用 npx 时,trace 也会持久化在同一位置,但由于需要解析软件包,启动速度较慢。

容器镜像,以及列出 Iris 的 MCP 目录:

Docker Glama Score PulseMCP mcp.so

你将获得什么

Trace 日志记录层级化 span 树,包含每次工具调用的延迟、token 用量和美元成本。存储在 SQLite 中,可即时查询。
输出评估4 个类别中的 28 条内置规则:完整性、相关性、安全性和成本。PII 检测(21 种模式:SSN、信用卡、电话、电子邮件、IBAN、出生日期、MRN、IP、API 密钥、护照,以及 AWS/Slack/SendGrid/GitHub/Google/npm/DigitalOcean token、URL 中的凭据、以机密命名的赋值、PEM 私钥块和助记词;出生日期、病历号、护照和助记词只有在其标签附近才会触发,这是有意设计的);提示注入检测(38 种模式,涵盖短语和结构);占位输出检测;幻觉检测(25 种基于上下文的捏造/矛盾信号 — 传入 input,即可根据智能体的源材料进行核验);以及六条轨迹规则,用于读取智能体实际执行的操作:未确认的失败工具调用;重复调用(按调用、重复序列,或在你传入 tools 后按目标识别);工具自身的 JSON Schema 拒绝其参数且智能体未重试的调用;答案中引用的文件、目录或 URL 未出现在智能体读取的任何内容中;指令出现在 TOOL RESULT 中,随后被后续调用遵循;以及工具调用次数超过步骤预算的任务。另有两条规则会将一次运行与同一智能体此前针对同一用例的运行进行比较,无需任何人编写预期结果:此前运行从未执行过的操作;以及此前每次运行都执行、但本次未执行的步骤。轨迹可以作为 tool_calls 传入,也可以作为 OpenTelemetry TOOL spans 传入。使用 Zod schemas 添加自定义规则。
LLM-as-Judge可选的语义评分,通过 Anthropic 或 OpenAI 提供 — 使用你自己的 API 密钥。提供七种模板。设置 IRIS_RELEVANCE_JUDGE_MODEL 后,answers_the_ask 会调用 relevance judge,并对偏离主题的回答判定失败;未设置时,该规则会通过词汇匹配读取问题并给出建议。每次评估都有严格的成本上限(IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL,默认 $0.25),结果中会披露每次评估的定价。
成本可见性在任意时间范围内汇总所有智能体的成本。设置预算阈值。智能体超支时会收到标记。对于发送了 token 数量和模型、但未发送成本的 trace(大多数 OpenTelemetry 和框架 trace 都如此),系统会按模型的标价计算,并在所有显示位置标记为估算值;内置表中没有的模型可通过 pricing.models 在 config.json 中定价 — docs/cost.md。
Web 仪表板实时深色模式界面,优先显示失败项,并按最差和最新排序 — 提供 trace 可视化、对每条 trace 文本进行全文搜索、评估结果、成本明细,以及可搜索自定义规则、trace 和评估的命令面板(⌘K)。
本地优先所有内容都存储在你磁盘上的 SQLite 中。自托管服务器无需账户或注册,也不会发送遥测数据。只有在你主动选择时才会发出外部 HTTP 请求:使用你自己的 LLM judge 密钥、获取引用内容、配置 OTel 导出器,或设置 webhook。

接下来的发展方向:能力地图 — 列出可以向 Iris 询问的所有主题和问题,并说明它已掌握和缺少的内容 — 以及三条路线。

有实测,不靠宣称

每条内置规则都有已发布的精确率、召回率和 F1 值及其 95% 置信区间。这些指标是在本仓库中的带标签语料库(proof/corpus/)上测得的,并且可以通过一条命令(npm run proof)离线重新生成,无需密钥,也不涉及模型。这些数字分为两种不同类型,本页绝不会将它们相加:部分规则是根据模型通过阅读故障本身给出的标签进行测量的,这衡量的是检测能力;其余规则则依据各自记录的定义独立检查,表明代码实现了相应公式,但并不说明该公式能否捕获故障。proof/RESULTS.md 和证明页面会标明每条规则的类型。CI 会在每个拉取请求上重新运行测量;如果提交的数字与代码生成的结果不同,就会失败,因此规则发生变化时,其对应数字也必须随之变化。相关数字见 iris-eval.com/proof 和 proof/RESULTS.md;语料库的制作方式、它不是什么,以及如何解读置信区间,见 docs/proof.md。该语料库是合成的,并由模型标注——人工盲标尚未完成,页面对此有明确说明;node proof/blind-sample.mjs 会抽取可复现的样本,以便最终确定结果。

MCP 工具

Iris 注册了十二种工具,任何兼容 MCP 的智能体都可以调用——用于跟踪和规则生命周期管理、跨运行比较、LLM-as-judge 以及语义引用验证:

  • log_trace — 记录一次智能体执行,包括 spans、工具调用、token 用量和成本;传入 evaluate: true,即可在同一次调用中为其评分
  • evaluate_output — 根据完整性、相关性、安全性和成本规则评估输出质量(启发式、确定性、免费)
  • get_traces — 查询已存储的跟踪记录,支持筛选、分页和时间范围;还可通过 q 查找智能体说过某句话的运行记录:对输入、输出、工具调用值和元数据进行全文搜索,按相关性排序,并标出匹配词
  • list_rules — 列出已部署的自定义评估规则(只读)
  • deploy_rule — 注册新的自定义评估规则,使其在该类别的每个 evaluate_output 上触发
  • delete_rule — 移除已部署的自定义规则(破坏性操作,可幂等执行)
  • delete_trace — 按 ID 移除一条已存储的跟踪记录(破坏性操作,限定于租户)
  • evaluate_with_llm_judge — 通过 LLM 进行语义评估(Anthropic 或 OpenAI)。提供七种模板:accuracy、helpfulness、safety、correctness、faithfulness、task_completed、relevance。费用设有上限,并公开每次评估的定价。请自备 API 密钥(IRIS_ANTHROPIC_API_KEY 或 IRIS_OPENAI_API_KEY)——Iris 不会代理或转发 LLM 调用。
  • verify_citations — 从输出中提取引用(编号引用、作者-年份格式、URL、DOI),通过带 SSRF 防护和域名白名单的解析器获取来源,并使用 LLM 评审器检查每个来源是否确实支持所引用的论断。需选择启用出站 HTTP。BYOK 要求与 evaluate_with_llm_judge 相同。
  • compare_runs — 某项更改是否让智能体表现变差?比较两次运行中存储的评估:如果两次运行共享案例键,则进行配对精确检验;否则计算差值的置信区间;也可能诚实地回答“无法判断”,并给出所需案例数,或回答“在一定误差范围内等效”。每条规则都有自己的单侧检验,并统一进行校正(Benjamini–Hochberg),避免二十条规则凭空制造出回归
  • compare_traces — 智能体对同一问题的回答有多可靠?提供每个案例的通过率及置信区间,优先列出不稳定案例,并给出考虑重复次数的总体通过率
  • evaluate_runs — 按照当前规则重新评分某次运行中的每条跟踪记录,并生成一次新运行,避免将规则变更误读为智能体变更

启用 LLM 评审器(可选;确定性规则始终不需要它)

  1. 从 Anthropic 或 OpenAI 获取 API 密钥。
  2. 将密钥放入运行 Iris 的进程环境中,而不只是放在 shell 环境中。Claude Code、Claude Desktop、Cursor 和大多数 MCP 客户端:在 MCP 配置中 iris-eval 条目的 "env" 块里设置——"iris-eval": { "command": "npx", "args": ["-y", "@iris-eval/mcp-server"], "env": { "IRIS_ANTHROPIC_API_KEY": "sk-ant-..." } }(OpenAI 密钥使用 IRIS_OPENAI_API_KEY)。Docker:在运行命令中添加 -e IRIS_ANTHROPIC_API_KEY=...。HTTP 或 CI:启动 iris-eval 前先导出该变量。
  3. 重启 MCP 会话。运行中的进程无法看到它启动后才设置的变量。
  4. 在客户端内部确认:读取 iris://capabilities——其中 judge.enabled 必须为 true。除非客户端配置中列出了该变量,否则 shell 中导出的密钥不会传递给客户端启动的进程。在机器上,npx @iris-eval/mcp-server --self-test 会为当前 shell 打印评审器状态;运行中的仪表板则可通过 GET /api/v1/health 报告 judge.enabled。
  5. 费用保护:每次调用的费用上限由 IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL 控制(默认 0.25 USD);如果最坏情况下的费用会超过上限,则会在产生任何费用前拒绝调用。Iris 使用你的密钥发起的所有评审器调用共用一个每日预算 IRIS_LLM_JUDGE_DAILY_BUDGET_USD(默认每个 UTC 日 1 USD);超出预算后,直到 UTC 午夜前都不会再发起调用。Iris 使用你的密钥直接调用服务提供商,不会代理该调用。
  6. 可选:将 IRIS_RELEVANCE_JUDGE_MODEL 设置为一个有定价的模型 ID(例如 claude-haiku-4-5),让 answers_the_ask 请求评审器判断每个回答是否回应了问题,并判定离题回答失败。每次包含输入的评估会调用一次评审器,使用你的密钥并受上述费用上限约束;仅有密钥并不会自动启用此功能。每次调用都会将输入和输出发送给模型服务提供商,并在发送前替换带有 no_pii 标记的个人数据和凭据(IRIS_RELEVANCE_JUDGE_REDACT=off 会原样发送)。调用费用计入该每日预算;每个请求最多调用 IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST 次(默认 20);达到任一上限后,answers_the_ask 会改为按词面分析问题并说明原因。

配置 IRIS_OTEL_ENDPOINT 后,log_trace 调用还会尽力向任意 OpenTelemetry 收集器(Jaeger、Grafana Tempo、Datadog OTLP、Honeycomb 等)导出 OTLP/HTTP JSON。参见 docs/otel-integration.md。

如何判定 passed

evaluate_output 会同时返回一个 score 和一个 passed 标志——它们回答的是不同问题:

  • score(0..1)是已运行规则的加权平均值——反映质量梯度。
  • passed 是是否可以发布的判定,完全不会参考分数。判定器会根据每条规则所作声明的类型分别处理:你配置的策略规则会作为门禁;关键检测器可以否决;已请求但无法作出判断的关键检查会使判定变为未知(passed: false),而不是通过;其余检测器则合并为一个输出有问题的概率,并根据你在 eval.falsePassCost 中声明的损失比进行权衡(默认值为 1,因此阈值为 0.5)。verdict.basis 会指出作出判定的层,verdict.by 会列出相关规则,verdict.also 会列出所有后续也会作出该判定的层;interpretations[] 会说明失败规则为何没有参与判定、哪些设置可以改变这一点,并指出任何未评审的问题以及使其能够得到评审的输入。

真正的安全违规会直接导致失败。默认情况下,no_pii、no_injection_patterns 和 no_blocklist_words 是关键规则:其中任何一条失败,评估都会报告 passed: false,无论其他规则得分多高;响应会在 critical_failures 中列出违规规则。泄露的 SSN 不能被平均分抵消。哪些内置规则属于关键规则是部署设置(eval.criticalRules / eval.nonCriticalRules),哪些检测器仅报告结果也是部署设置(eval.advisoryRules);每条规则的结果都会带有生效的 critical 标志和 criticalSource,而 list_rules 会报告此服务器采用的规则清单。通过 severity: "high" 或 "critical" 部署的自定义规则也会以相同方式直接导致失败;low/medium 严重级别只影响分数。需要了解的一条边界规则,在所有界面上的表述都相同:关键规则如果跳过(缺少上下文、定义损坏,或正则表达式在沙箱预算内被终止),就没有对输出作出判断,因此不会否决——所有此类规则都会列在 critical_skipped 中。必须采用失败关闭策略的门禁,应将非空的 critical_skipped 视为未知,而不是通过;也可以将 rule_results 中任何 budgetExceeded 跳过的情况同样处理。

对于 CI 门禁:如果省略 eval_type,所有规则包都会运行——完整性、相关性、安全性、成本以及任何自定义规则;响应会通过 eval_type: "all" 表示默认规则包已运行,并附带 note,以及按规则包划分的 categories 映射。每一行都包含 state:该规则包所含规则的判定,因此某一行不会在评估失败的规则上显示通过。没有可评估内容的规则包(没有 cost_usd 时的成本规则包、没有 input 时的相关性规则包)会在相应位置报告 state: "unknown" 和 passed: null——表示未评估,而非失败——并且不会计入总体判定。响应始终会回显实际运行的 eval_type,以便门禁验证覆盖范围;使用 passed 获取判定,只有需要缩小运行范围时才指定规则包。

编写自定义规则

添加规则有两种方式。内联规则随一次 evaluate_output 调用一并传入(每次调用最多 custom_rules 条);它们会与所选的 eval_type 规则包一同触发,也可以通过 eval_type: "custom" 单独运行。已部署规则只需通过 deploy_rule 注册一次,就会持久保存在你 Iris 主目录下的 custom-rules.json 中,并在其所属类别的每个后续 evaluate_output 上触发(类别为 evalType)。两种方式使用相同格式的定义:

字段必填说明
name是1–80 个字符;在结果中显示为 ruleName
type是以下之一:regex_match · regex_no_match · min_length · max_length · contains_keywords · excludes_keywords · json_schema · cost_threshold
config是对应类型的键:两种正则表达式类型使用 pattern(可选 flags);字符数使用 min_length / max_length;两种关键词类型使用 keywords(可选 threshold,范围为 0–1,默认 1 = 必须全部出现);json_schema 使用 {};cost_threshold 使用以 USD 计的 max_cost
weight否在分数中的权重;默认值为 1

deploy_rule 会将定义与 name、可选的 description、evalType(completeness · relevance · safety · cost · custom)以及 severity 封装在一起。严重级别说明失败意味着什么:low/medium 只会降低分数;high/critical 会直接导致评估失败——passed: false,并在 critical_failures 中列出该规则——无论加权分数如何。跳过的规则(缺少 cost_usd 的 cost_threshold 规则,或在 100 ms 沙箱预算内被终止的正则表达式)并未对输出作出判断,而是会列在 critical_skipped 中。部署一条关键规则,禁止智能体在任何回复中提及内部主机名:

{
  "name": "no_internal_hostnames",
  "description": "Output must not mention internal hostnames.",
  "evalType": "safety",
  "severity": "critical",
  "definition": {
    "name": "no_internal_hostnames",
    "type": "regex_no_match",
    "config": { "pattern": "\\b[a-z0-9-]+\\.internal\\.example\\b", "flags": "i" }
  }
}

响应内容就是已持久化的规则——请保留 id,以供 delete_rule 使用:

{ "rule": { "id": "rule-588823d0", "name": "no_internal_hostnames", "evalType": "safety", "severity": "critical", "enabled": true, "version": 1, "definition": { "…": "…" } } }

从下一个 evaluate_output 开始,使用 eval_type: "safety" 时,提及 db-primary.internal.example 的输出会以 passed: false 和 critical_failures: ["no_internal_hostnames"] 返回——尽管所有五条内置安全规则都已通过,且加权得分为 0.895。正则表达式模式必须在部署时通过 ReDoS 检查,并始终在沙箱工作进程中运行,且硬性截止时间为 100 ms。list_rules 展示了已部署的内容;仪表板的规则编辑器会根据你点击的失败项构建相同的结构。完整参考、各类型评分和示例:docs/custom-rules.md。

完整工具架构和配置:iris-eval.com

自托管且免费

Iris 可在你的机器或自有基础设施上运行。开源核心免费且采用 MIT 许可证,没有使用限制,也无需账户。托管存储、团队共享历史记录和告警功能仍在考虑中,尚未开始开发;如果这些功能对你有帮助,请通过 hello@iris-eval.com 告诉我们。

我们坚持两项承诺:今天免费的功能不会转为付费功能,并且在获得合规认证之前,不会声称已获得该认证。

示例

社区

  • GitHub Issues — 报告错误和提出功能请求
  • GitHub Discussions — 提问和交流想法
  • 获取帮助 — 提问、报告错误或报告漏洞的渠道
  • 贡献指南 — 如何参与贡献;AGENTS.md 是面向编码智能体的同一份指南
  • 治理 — 谁负责决策、变更如何合并,以及如何制作和验证发布版本
  • HTTP Ingest — 通过 POST /api/v1/traces 确定性地捕获追踪
  • 功能地图 — 可以向 Iris 提出的所有问题,以及它尚不具备的功能
  • 版本策略 — 每个版本号代表什么,以及 1.0 发布前必须满足哪些条件
配置与安全

CLI 参数

标志默认值说明
--transportstdio传输类型:stdio 或 http
--port3000HTTP 传输端口
--db-path~/.iris/iris.dbSQLite 数据库路径
--config~/.iris/config.json配置文件路径
--api-key—用于 HTTP 身份验证的 API 密钥(传输和仪表板,包括 POST /api/v1/traces)
--dashboardfalse启用 Web 仪表板。也是启动 POST /api/v1/traces ingest 端点的唯一方式——它绝不会随 --transport http 隐式启动
--dashboard-port6920仪表板端口
--dashboard-host127.0.0.1仪表板绑定地址。默认仅绑定回环地址——除非设置了 --api-key,否则仪表板不需要身份验证,因此绑定到回环地址以外的地址会暴露完整的追踪历史记录
--demofalse初始化演示数据库(与真实追踪数据分开),并使用该数据库提供仪表板服务
--demo-clearfalse删除演示数据库并退出
--self-testfalse在隔离的临时主目录中运行离线安装诊断,然后退出(0 = 正常,1 = 检查失败)。它还会以只读方式读取已配置的数据库;如果此版本或固定版本的 MCP 客户端无法打开该数据库,则检查失败
--purgefalse删除已配置数据库中的所有追踪、跨度和评估,压缩文件并截断预写日志,避免已删除的文本残留在磁盘上,然后退出。已部署的规则、审计日志和偏好设置会保留。此操作不可撤销。请先停止所有正在运行的 Iris 服务器——文件会原地压缩。不能与 --demo、--demo-clear 或 --self-test 同时使用
--version—将纯版本号(例如 1.2.3)打印到 stdout 并以状态码 0 退出。不会读取 Iris 主目录中的任何内容

有三个命令会接收各自的参数并退出:iris-eval ingest 从文件或 stdin 加载追踪(无需服务器的 CI 门禁);iris-eval export traces|evaluations --format csv|jsonl 将已存储的内容按仪表板列表的筛选方式筛选后,写入 stdout 或 --out(docs/api-reference.md);iris-eval install <client> 将 Iris 写入 MCP 客户端的配置——--uninstall 会将其移除,--list 会显示在此机器上找到的客户端及其运行的 Iris 版本,--upgrade 会将所有运行 Iris 的客户端迁移到此版本(接入你自己的智能体、更新)。这些命令都不会启动服务器。

Iris 启动时会验证 config.json。 如果 Iris 不读取某个键——例如拼写错误的 eval.critcalRules、来自其他工具的键——或值的类型不正确,启动就会被拒绝,并显示一句话,指出完整键名、最可能的正确键名或所需类型。文件中的任何内容都不会被静默忽略。

环境变量

每个变量都由 --help 记录说明。如果 CLI 标志和环境变量同时设置,CLI 标志优先。

变量描述
IRIS_TRANSPORT传输类型(stdio 或 http)
IRIS_HOSTHTTP 传输绑定地址(默认 127.0.0.1)
IRIS_PORTHTTP 传输端口(1-65535,默认 3000)
IRIS_HOME所有按用户划分的文件所在目录:config.json、iris.db、custom-rules.json、audit.log、preferences.json(默认 ~/.iris)
IRIS_DB_PATHSQLite 数据库路径(仅对数据库覆盖 IRIS_HOME)
IRIS_SQLITE_DRIVER用于保存数据库的 SQLite 驱动:native(better-sqlite3,默认)或 node(Node 内置的 node:sqlite,Node 22.13+)。未设置时使用 native;如果无法加载原生模块(或该构建版本会在此 Node 版本上导致进程中止),Iris 会警告一次并回退到内置驱动
IRIS_SEARCH_BUDGET_MS一次跟踪搜索(q)最多读取多长时间,然后返回目前找到的匹配项和 search.complete: false,单位为毫秒(50 到 60000,默认 1000)。搜索读取数据时会阻塞其他请求,因此这也是其他请求可能等待的最长时间。另见 config.json 中的 storage.searchBudgetMs
IRIS_SEARCH_INDEXon(默认)或 off。off 不会为跟踪保留全文索引:写入时只存储跟踪,不做其他处理;跟踪搜索(q)会在 IRIS_SEARCH_BUDGET_MS 内按时间倒序读取跟踪本身,因此在数据量较大的存储中,可能只返回部分匹配项(search.complete: false)。关闭此功能会删除数据库保留的索引;重新开启后会在后台构建新索引。另见 config.json 中的 storage.searchIndex
IRIS_LOG_LEVEL日志级别:debug、info、warn、error
IRIS_DASHBOARDtrue/1/yes/on 启用 Web 仪表板;false/0/no/off 禁用它(也会覆盖 config.json 中的 dashboard.enabled)
IRIS_DASHBOARD_PORT仪表板端口(1-65535,默认 6920)
IRIS_WEBHOOK_URL在某个时刻触发的 webhook 接收方——与 config.json 中的 notify.webhook 合并(docs/webhooks.md)
IRIS_WEBHOOK_SECRETwebhook 的签名密钥(任意字符串,或 whsec_ + base64);iris 格式未设置密钥时会拒绝运行
IRIS_DASHBOARD_HOST仪表板绑定地址(默认 127.0.0.1)
IRIS_API_KEY用于 HTTP 身份验证的 API 密钥。若要将 HTTP 传输或仪表板绑定到回环地址以外的地址(0.0.0.0、局域网地址、容器),则必须设置此项;否则服务器会拒绝启动
IRIS_API_KEY_FILE密钥文件路径——文件内容去除首尾空白后即为 API 密钥。这是 Docker 和 Kubernetes 挂载机密文件的模式,因此密钥不会出现在环境变量块中。设置此项或 IRIS_API_KEY,但不能同时设置
IRIS_ALLOW_UNAUTHENTICATED设置为 1,以有意在不使用密钥的情况下绑定到非回环地址(解除拒绝限制;此时网络就是你的安全边界)
IRIS_ALLOWED_ORIGINS以逗号分隔的来源允许列表。仪表板:CORS 标头(支持通配符,例如 http://localhost:*)。HTTP 传输:用于防止 DNS 重绑定的精确匹配 Origin 允许列表(忽略通配符;始终允许服务器自身的回环来源)
IRIS_MAX_INPUT_ELEMENTS输入在验证前最多可包含的数组元素和对象键数量(整数,默认 100000):适用于所有传输上的工具调用参数,以及仪表板端口上的请求正文(API 的 JSON 正文和 POST /v1/traces,JSON 或 protobuf)。超出限制的工具调用会返回错误结果;正文则会 413。默认值足以容纳所有经过测量的合法 JSON 输入,即使请求填满整个 1 MB 限额也不例外。POST /v1/traces 上的 protobuf 正文有自己的上限:每 5 字节 security.requestSizeLimit 最多一个元素(1 MB 时为 209,716),或者使用此设置中更高的值,因此请求大小范围内的导出器批次不会因元素过密而被拒绝(测量过的最密集真实导出器正文每 7.5 字节包含一个元素);提高 requestSizeLimit 以支持采集器更大的批次时,此上限也会提高。另见 config.json 中的 security.maxInputElements
IRIS_MAX_TOOL_INPUT_ELEMENTS0.21.0 之前 IRIS_MAX_INPUT_ELEMENTS 的名称;仅当新名称未设置时读取(config.json 中的 security.maxToolInputElements 也同样如此)
IRIS_NO_AUTO_LAUNCH设置为 1,以禁用首次运行时自动启动仪表板
IRIS_ANTHROPIC_API_KEY使用 provider=anthropic 时,evaluate_with_llm_judge + verify_citations 必需
IRIS_OPENAI_API_KEY使用 provider=openai 时,evaluate_with_llm_judge + verify_citations 必需
IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL每次 LLM 评审调用的硬性费用上限(默认 0.25)。max_cost_usd 可以降低单次调用的上限,但不能提高
IRIS_RELEVANCE_JUDGE_MODEL具有定价信息的评审模型 ID(例如 claude-haiku-4-5)。设置此项并提供相应提供商的密钥后,answers_the_ask 会在每次包含输入的评估中询问此 LLM 评审模型,并根据其相关性判定进行门控——每次评估调用一次评审模型,受上述费用上限和以下两个限制约束。每次此类评估的输入和输出都会通过你的密钥发送给该模型的提供商(Anthropic 或 OpenAI),发送前会替换 no_pii 标记的个人数据和凭据。未设置(默认)时,answers_the_ask 会以词法方式读取问题并给出建议,不会发送任何内容(docs/llm-as-judge.md)
IRIS_LLM_JUDGE_DAILY_BUDGET_USD每个 UTC 日、每个租户的所有评审调用合计最多可花费的金额(默认 1):相关性评审、evaluate_with_llm_judge 和 verify_citations 共用此额度。额度保存在数据库中,因此重启不会重置。只有当调用的最坏情况费用不超过剩余额度时才会发起调用;超过后,answers_the_ask 会以词法方式读取问题(judge.withheld: "daily_budget"),评审工具则会返回 IRIS_BUDGET_EXCEEDED(引用,daily_budget_reached)。0 会停止所有调用
IRIS_RELEVANCE_JUDGE_DAILY_BUDGET_USD0.21.0 之前 IRIS_LLM_JUDGE_DAILY_BUDGET_USD 的名称,当时仅限制相关性评审。仅当新名称未设置时读取,此时它会限制所有评审调用;服务器会在启动时说明这一点
IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST单个请求可发起的相关性评审调用次数(默认 20):OTLP 批次或 evaluate_runs 重新评分会评审前 20 条跟踪,其余部分以词法方式读取,并受 judge.withheld: "request_cap" 限制
IRIS_RELEVANCE_JUDGE_REDACTon(默认):发送给相关性评审模型之前,输入和输出中每个 span 的 no_pii 标记(个人数据和凭据)都会替换为 [REDACTED:<kind>#<n>] 标记。off 则会原样发送
IRIS_CITATION_ALLOW_FETCH设置为 1,以允许 verify_citations 发起出站 HTTP 请求(默认关闭)。工具参数可以在单次调用中关闭此项,但不能开启
IRIS_CITATION_DOMAINS以逗号分隔的 verify_citations 主机名允许列表(后缀匹配)。工具参数可以缩小范围,但不能添加条目
IRIS_CITATION_MAX_COST_USD_TOTAL单次 verify_citations 调用在评审调用上的最高花费(默认 1)。max_cost_usd_total 可以降低单次调用的上限,但不能提高
IRIS_OTEL_ENDPOINT启用尽力而为的 OTLP/HTTP JSON 跟踪导出到此采集器 URL
IRIS_OTEL_SERVICE_NAMEOTel 导出的 service.name 资源属性(默认 iris-eval)
IRIS_OTEL_HEADERS以逗号分隔的 OTel 导出 k=v 标头(例如 authorization=Bearer abc)
IRIS_OTEL_TIMEOUT_MS单次导出的超时时间(默认 15000)
RATE_LIMIT_SALT仅限网站——为 iris-eval.com 游乐场速率限制所保存的地址哈希添加盐值;服务器不会读取此项

安全

使用 HTTP 传输时,Iris 包含以下安全措施:

  • 使用时序安全比较进行 API 密钥身份验证(API 客户端使用 Bearer;浏览器通过 ?key= 登录仪表板)
  • 默认将 CORS 限制为 localhost
  • 按客户端地址和分钟进行速率限制:仪表板 API 每分钟 600 个请求(security.rateLimit.api),MCP 端点每分钟 20 个请求(security.rateLimit.mcp),两者均在 config.json 中设置;超出限制的 MCP 请求会收到一条 JSON-RPC 错误,其中会指出对应的键
  • Helmet 安全标头
  • 对所有路由进行 Zod 输入验证
  • 自定义评估规则使用可防止 ReDoS 的正则表达式
  • 所有传输均有一个 1MB 请求大小限制(security.requestSizeLimit):HTTP 会返回 413;stdio 会返回 JSON-RPC 错误并保持会话打开
  • 输入中的数组元素和对象键总数限制为 100,000,且在验证前计数(security.maxInputElements):所有传输上的工具调用参数超出限制时会返回错误结果;仪表板或 OTLP 请求正文超出限制时会返回 413
  • 验证错误最多返回 20 条问题及总数(issueCount),因此无论请求有多大问题,响应都能保持精简
# Production deployment
iris-eval --transport http --port 3000 --api-key "$(openssl rand -hex 32)" --dashboard

设置密钥后,API 客户端——MCP 客户端、采集 SDK、POST /api/v1/traces——会发送 Authorization: Bearer <key>。要在浏览器中打开仪表板,只需在任意仪表板 URL 后附加一次密钥,http://localhost:6920/?key=<api key>:Iris 会将其换成 HttpOnly、SameSite=Lax 会话 Cookie,并重定向到同一页面,同时从地址栏中移除密钥。未登录会话的页面会显示登录表单,并执行相同的交换流程。密钥不会存储在浏览器中,会话仅存在于服务器进程中(最多同时有 256 个有效会话;如果登录时所有会话都有效,则会拒绝登录,而不是驱逐现有会话)。

生产环境

多个密钥,无间断轮换。 config.json 中的 security.apiKeys 可保存任意数量的其他密钥,每个密钥都有一个 id,并且必须且只能设置 keyFile(文件内容去除首尾空白后即为密钥)或 keyHash(密钥的 sha256 十六进制值,因此配置文件不包含机密——printf %s "$KEY" | openssl dgst -sha256),还可选设置 expiresAt(ISO 8601),指定密钥从该时刻起停止匹配。轮换步骤:添加新密钥、迁移客户端、移除旧密钥。config.json 中的密钥和密钥文件中的密钥无需重启即可生效(0.20.0):每次请求时,服务器都会检查 config.json 或其指定的密钥文件是否发生变化;如果发生变化,就会在响应前重新读取密钥。若从 security.apiKeys 中移除密钥,或删除其密钥文件,该密钥会在下一个请求时被撤销:该请求会被拒绝,所有使用该密钥打开的浏览器会话也会退出登录。无法读取的 config.json(例如文件只写入了一部分)会按关闭失败处理;修复之前,只接受来自 IRIS_API_KEY 或 --api-key 的密钥。IRIS_API_KEY 或 --api-key 中的密钥本身,以及是否启用身份验证,仍然只能通过重启更改。每个密钥在被移除或过期之前都可用于身份验证,Bearer 路径和浏览器登录均适用;启动日志会列出密钥 ID。security.rateLimit.mcpKeyBy: "apiKey" 会按密钥而非客户端地址计算 MCP 端点的每分钟额度,因此同一地址后的多个代理各自拥有独立的每分钟额度。

多个客户端。 --transport http 可在同一地址上服务任意数量的 MCP 客户端:每个 initialize 都会通过同一个引擎和存储独立打开一个会话,最多同时支持 256 个会话。使用 stdio 时,每个客户端都会启动自己的服务器进程,这些进程共享 Iris 主目录:通过一个进程部署、关闭或删除的规则会在 20 ms 内应用到其他所有进程;一个进程写入的标签会立即被其他进程读取;多个进程同时更改规则时,也不会丢失任何更改。 Iris 在 HTTP 传输或仪表板绑定到回环地址以外的位置时——0.0.0.0、局域网地址、容器——如果没有 API 密钥,会拒绝启动,并用一句话说明原因,其中点名 IRIS_API_KEY。这也包括镜像的裸 docker run,它会在容器内绑定 0.0.0.0,因为通过已发布端口无法访问回环地址。没有密钥时,回环地址仍可正常使用(HTTP 传输会发出警告):此时机器边界就是暴露控制措施。

# The image: pass a key
docker run -p 3000:3000 -p 6920:6920 -v iris-data:/data \
  -e IRIS_API_KEY="$(openssl rand -hex 32)" ghcr.io/iris-eval/mcp-server

# Compose: the file requires the variable and refuses before the container starts
IRIS_API_KEY="$(openssl rand -hex 32)" docker compose up

# A network you have already fenced some other way: run open, on purpose
IRIS_ALLOW_UNAUTHENTICATED=1 iris-eval --transport http --dashboard

按设计开放的带密钥服务器:传输上的 GET /health 和仪表板上的 GET /api/v1/health 无需密钥即可访问,也不受任何速率限制,且返回统一格式:状态、版本、运行时间、SQLite 驱动、存储的 checks、已部署规则文件和迁移(与已知迁移对照后显示已应用的迁移)、搜索索引状态(search:就绪,或显示构建进度占跟踪总数的比例),以及是否存在评审密钥——绝不返回密钥、跟踪内容或跟踪数量。只有所有检查都通过时,status 才是 ok;否则为 degraded,并返回 HTTP 503,Docker 镜像自带的 HEALTHCHECK 会读取此状态。其他所有内容都需要 Authorization: Bearer <key> 或浏览器会话。每台服务器都会执行保留清理:启动时、服务器开始响应请求后,以及每隔 retention.sweepIntervalHours,都会删除早于 retention.days(默认 30)的跟踪和评估;清理分成短时步骤,不会让请求长时间等待;--self-test 会打印此安装的策略,iris://capabilities / GET /api/v1/capabilities 会将其作为 retention 携带。

Webhook 会在特定时刻触发(0.16.0):在 config.json 中设置 notify.webhook(或设置 IRIS_WEBHOOK_URL 和 IRIS_WEBHOOK_SECRET)以指定接收端;当判定失败、严重检测器否决、成本异常、规则失败率变化,或某个案例首次出现正反两种回答时,Iris 会发送一条签名消息——包含 ID、判定、规则和数值,绝不包含代理文本。签名同时遵循 Standard Webhooks 和 GitHub 的方式,失败时采用退避重试,按代理和规则分别设置冷却时间,且绝不阻碍评估;内置 Slack 和 Discord 消息体。docs/webhooks.md。

磁盘上的数据

Iris 存储的所有内容都位于 Iris 主目录(~/.iris 或 IRIS_HOME)下。iris.db 会原样保存每条跟踪的 input 和 output——包括 no_pii 后续会标记的任何文本;除非你主动要求,否则检测不会进行脱敏:在 config.json 中设置 storage.redact: "critical_spans",即可保存每次评估的输出,并将严重检测器标记的片段替换为 [REDACTED:<pattern>](默认关闭;证据偏移量仍对应调用方看到的文本)。storage.synchronous 用于设置写入何时落盘:normal(默认值)会在每次检查点同步预写日志,因此 Iris 崩溃不会丢失数据,文件也不会损坏;但断电或操作系统崩溃可能会撤销上次同步之后的写入;full 会在每次提交时同步,并确保数据在这两种情况下都能保留,但每次写入约多耗时 1.5 毫秒。启动时,以及之后每隔 retention.sweepIntervalHours(默认 24,0 可禁用计时器),都会删除早于 retention.days(默认 30,0 可禁用;在 config.json 中设置)的跟踪和评估,并检查点化预写日志。有一项内容会保留超过此期限:已固定的基线运行及其评估,因为后续每次运行都要与它比较。每次清理若保留了部分内容,都会在日志中说明运行和数量;取消固定该运行后,下次清理就会将其删除。数据集案例和标签不属于跟踪或评估,不会被清理。通过 delete_trace 或清理操作删除跟踪时,会擦除与其关联的每次评估中的文本(输出、预期文本和规则消息),并写入时间戳 erased_at;判定、分数和证据偏移量会保留。每次删除都会在返回前检查点化预写日志,因此已删除的文本不会继续留在 iris.db 或 iris.db-wal 中(如果此时搜索正在读取文件,或另一个进程正在读写文件,删除操作会立即返回,不会等待;文本会在操作完成后从文件中移除)。若要立即删除所有内容,请停止服务器并运行 --purge:它会删除所有已存储的跟踪、片段和评估,压缩数据库并截断预写日志,使文本从磁盘上消失,同时保留已部署规则、审计日志和偏好设置。发布版本对现有 iris.db 应用迁移前,会在其旁边复制该文件(iris.db.<from>-to-<to>.<time>.bak,仅所有者可访问,保留最新的三个副本;降级):副本保留原样的跟踪,因此保留清理会删除早于 retention.days 的内容,而 --purge 会删除所有内容。服务器会在响应客户端后,于独立线程中执行复制和迁移:期间到达的工具调用、资源读取和 HTTP 请求会等待,最长各等待 30 秒,之后会收到说明服务器正在执行何种操作的拒绝消息(IRIS_STORAGE_ERROR,可重试;HTTP 503,带有 Retry-After)。健康检查会始终响应,并说明升级正在执行的操作。从 0.19.0 升级时,在 100,000 条每条都代表一次代理循环的跟踪数据下,复制和迁移耗时约 6 秒。iris-eval ingest、--purge 和 --self-test 仍会在执行任何操作前先升级。

Iris 不会对静态数据进行加密。iris.db 及其预写日志文件会以仅所有者可访问的权限创建(模式 600),Iris 主目录则以模式 700 创建(Windows 上由文件 ACL 控制)。数据库不会存储 LLM 提供商密钥:IRIS_ANTHROPIC_API_KEY 和 IRIS_OPENAI_API_KEY 从环境中读取,绝不会写入磁盘。数据库确实会原样存储跟踪输入和输出,因此请将 Iris 主目录放在加密磁盘或卷上(FileVault、BitLocker、LUKS,或 Docker 镜像的 /data 挂载所用的加密云卷)。

导出文件——仪表板“跟踪”和“评估”页面上的 导出 按钮、GET /api/v1/traces/export 和 /api/v1/evaluations/export,或 iris-eval export——会原样携带已存储的文本,与仪表板显示的内容一致:跟踪输入和输出原样保留,评估输出则应用 storage.redact。请像保护其来源数据库一样保护导出文件。

故障排除

第一步:运行自检

npx @iris-eval/mcp-server --self-test

它会在隔离的临时主目录中检查存储、确定性评估和仪表板,并打印每个步骤的判定结果——失败输出会指出出错步骤。退出代码 0 表示安装正常。

Iris 无法启动 / ERR_MODULE_NOT_FOUND

你可能缓存了较旧版本。清除 npx 缓存后重试:

npx --yes @iris-eval/mcp-server@latest

或者全局安装,以彻底避免缓存问题:

npm install -g @iris-eval/mcp-server@latest

npm install --ignore-scripts 导致 SQLite 绑定失败

Iris 使用 better-sqlite3 存储跟踪数据;这是一个原生模块,会在安装脚本中下载或编译其绑定。如果该脚本被跳过——例如在命令行中使用了 --ignore-scripts、在 .npmrc 中设置了 ignore-scripts=true(企业机器上很常见),或注册表镜像移除了 postinstall——启动时就会失败,并输出一大段“Could not locate the bindings file”错误,其中列出尝试过的十几个路径。重新构建该模块即可:

npm rebuild better-sqlite3
# for a global install:
npm rebuild -g better-sqlite3

Claude Code 中未显示工具

MCP 工具只会在会话启动时加载。添加 iris-eval 后,使用 /clear 重启会话,或重新启动终端。

检查版本

npx @iris-eval/mcp-server --version

启动日志的第一行也会显示版本(Starting Iris MCP server vX.Y.Z),--self-test 会在摘要中打印版本。对于全局安装,npm ls -g @iris-eval/mcp-server 会显示已安装的版本。

更新

同一台机器上的所有 MCP 客户端共用一个数据库(~/.iris/iris.db),而 install 会将每个客户端固定到写入其配置的发布版本。当某个发布版本更改数据库架构时,该版本中第一个打开文件的进程会升级数据库;此后,仍固定在旧版本的客户端将拒绝启动。因此,请在升级前或升级后立即一次性迁移所有客户端:

npx -y @iris-eval/mcp-server@latest install --upgrade

它会查找这台机器上所有运行 Iris 的客户端配置,并将每个客户端的版本固定值更新到该发布版本(保留你添加到条目中的内容,例如 --dashboard 或 env 块);不会更改固定到较新版本的配置,也不会更改运行 npm 包以外程序的条目,并会列出执行的操作。重启它列出的客户端。install --list 会显示每个客户端运行的 Iris 版本。

有两种安装方式不在这些文件中:打开较新的 Claude Desktop 扩展包时,扩展(iris-eval.mcpb)会随之更新;Claude Code 插件则通过 claude plugin marketplace update iris-eval,然后 claude plugin update iris-eval@iris-eval 更新(捕获插件还需使用 claude plugin update iris-eval-capture@iris-eval)。

从 0.19.x 升级到 0.20.0。 0.20.0 会向数据库添加搜索索引及其他内容(迁移 015 及后续迁移)。任何 0.20.0 进程打开 ~/.iris/iris.db(Claude Desktop 扩展、npx iris-eval,或未指定版本的 npx @iris-eval/mcp-server)后,固定在 0.19.x 的客户端就会因 This database was migrated by a newer Iris (…) — migration(s) 015-trace-search, … are unknown to v0.19.0. Upgrade Iris, … 而停止运行。该消息来自 0.19.x,无法更改;解决方法是运行上面的命令。升级前,0.20.0 会在旁边复制数据库文件,因此也可以回退(见下文)。

升级数据库的启动过程会在 stderr 上打印执行情况:创建的副本、哪些旧版本将无法再打开该文件,以及这台机器上固定到这些版本的客户端,并附上相应命令。--self-test 会以只读方式检查数据库,不做任何更改,并在你启动任何程序前显示相同信息。

对于全局安装,先运行 npm update -g @iris-eval/mcp-server,然后运行 iris-eval install --upgrade。

降级

升级数据库的发布版本会先在数据库文件旁创建副本:位于 Iris 主目录中的 iris.db.<from>-to-<to>.<time>.bak(<from> 是最后一次更改文件架构的发布版本,<to> 是执行升级的发布版本;启动日志行会打印确切路径)。若要回退:

  1. 停止所有 MCP 客户端以及任何使用该数据库的其他 Iris 进程。
  2. 保留升级后的文件,以便日后恢复:将 iris.db 重命名为 iris.db.upgraded,并在存在时删除 iris.db-wal 和 iris.db-shm。
  3. 将备份复制到 iris.db:cp ~/.iris/iris.db.0.19.0-to-0.20.0.<time>.bak ~/.iris/iris.db。
  4. 将每个客户端固定回旧版本:对每个客户端运行 npx -y @iris-eval/mcp-server@0.19.0 install <client>(install --upgrade 绝不会将客户端回退)。

升级后存储的跟踪位于 iris.db.upgraded,不在备份中。如果没有创建副本(启动日志会说明原因,例如磁盘已满),旧版本就无法打开升级后的文件;此时只能通过 install --upgrade 继续。

存储驱动

在没有预编译 better-sqlite3 的平台上,安装仍会成功。 better-sqlite3 是可选依赖:如果 npm 既无法下载适用于你的 Node 和平台的预编译二进制文件,也无法编译(编译需要 Python 和 C++ 工具链——Windows 上需要 Visual Studio 的 C++ 生成工具),npm 会打印构建错误、跳过该模块并完成安装。随后 Iris 会使用 Node 内置的 SQLite 运行,并明确说明这一点:启动时会在 stderr 上打印一行,说明原因;--self-test 会显示 driver node: better-sqlite3 is not installed …。若要恢复原生驱动,请在具备预编译版本或工具链的环境中安装它(在项目中运行 npm install better-sqlite3;全局安装时,工具链可用后使用 npm install -g @iris-eval/mcp-server 重新安装 Iris)。CI 会在每次变更时强制原生构建失败,以此安装打包后的服务器,并要求安装顺利完成,且自检能够使用内置驱动存储并读取跟踪。 Iris 将所有内容保存在一个 SQLite 文件中,并通过 better-sqlite3 打开该文件——这是一个原生插件,会针对你的 Node 版本和平台下载或编译。如果该模块无法加载,Iris 会回退到 Node 内置的 SQLite(node:sqlite,Node 22.13 或更高版本),并在 stderr 上输出一条警告,因此缺少预编译版本只会让启动变慢,而不会导致启动失败。对于在你的机器上使用 Node 24.19 或更高版本的头文件编译、并在 Node 24.19 至 24.21 上运行的 better-sqlite3,Iris 也会在加载它之前执行相同的回退:在这些版本上,这样的二进制文件会在首次释放语句时中止整个进程(Assertion failed: (env) != nullptr,nodejs/node#65446)。Node 24.22.0 已包含此修复,Iris 会在该版本上加载此二进制文件。npm rebuild better-sqlite3 会将其替换为预编译二进制文件,该文件在所有版本上都安全。IRIS_SQLITE_DRIVER=node 会有意选择内置驱动,native 则禁止回退。内置驱动在关闭扩展加载和 trusted_schema 的情况下打开;Node 加载它时会在 stderr 上输出自己的 ExperimentalWarning: SQLite is an experimental feature 行,Iris 不会将其屏蔽。--self-test 和 GET /health 用于标识当前使用的驱动;性能证明页面上的所有数字均在原生驱动上测得,测试套件也会在 CI 中使用两种驱动运行。

Node.js 版本

Iris 要求 Node.js 22.13 或更高版本。Node 20 已于 2026-04-30 结束生命周期,不受支持;Node 18 已于 2025 年 4 月结束生命周期。

最低版本设为 22.13 而非 22.0,是因为 22.13.0 是首个随附 node:sqlite 的版本。这使它成为首个所有受支持的 Iris 安装都拥有第二种存储驱动的版本:当原生 better-sqlite3 插件无法加载时,Iris 会回退到 Node 内置的 SQLite,而不是启动失败。在 22.13 以下的版本中——以及 Node 20 的整个生命周期内——始终只有一种驱动,缺少预编译版本就会导致启动失败。

node --version  # Must be v22.13.0 or newer

Windows:不需要 cmd /c

Claude Code 的 /doctor 可能会建议使用 cmd /c 包装 npx。这没有必要,还会导致路径解析问题。请直接使用 npx:

# Correct
claude mcp add --transport stdio iris-eval -- npx -y @iris-eval/mcp-server

# Wrong (causes /c to be parsed as a path)
claude mcp add --transport stdio iris-eval -- cmd /c "npx -y @iris-eval/mcp-server"

如果 Iris 对你有用,欢迎考虑为仓库点个星——这有助于其他人发现它。

Star on GitHub

采用 MIT 许可证。