Iris

Iris — 别再凭感觉发布 Agent

Iris 会对每次 Agent 运行的质量、安全性和成本进行评分——在你的机器上完成，无需 SDK 或账户。 大多数 Agent 项目通过运行几个印象中的提示词，再凭感觉查看输出，来检查质量。Iris 用可审计的数字取代这种做法：Agent 的运行记录会写入你磁盘上的 SQLite 数据库，内置的 26 条规则会以确定性方式为其评分，涵盖个人身份信息（PII）、提示词注入、幻觉标记、成本阈值以及 Agent 自身的工具调用；这一切免费完成，不调用大模型。对于语义问题，还可启用 LLM 评判器，并设置严格的单次评估成本上限。每条规则都可检查和编辑，因为无法审计的评判器，不过是披着数字外衣的凭感觉判断。采用 MIT 许可，无遥测。除非你启用以下任一功能，否则数据不会离开你的机器：OpenTelemetry 端点（IRIS_OTEL_ENDPOINT），它会将追踪数据导出到你指定的收集器；使用你自己的密钥启用 LLM 评判器，它会将待评判文本发送给相应服务提供商，且其引用检查会获取输出中引用的页面；或者启用 Webhook，它会向你设置的地址发送 ID、判定结果和规则名称，绝不会发送文本。

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

_{演示数据库由 scripts/demo-media.mts 录制；源文件为 demo.mp4。静态截图：dashboard-overview.png。}

60 秒内在屏幕上看到一次失败

无需连接 Agent，无需配置——只需一条命令：

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

这会填充一个演示数据库——其中有五个小型 Agent、两周的运行记录，以及引擎自己的所有判定——并在 http://localhost:6920 上展示基于该数据库的仪表板（首次运行时会自动打开浏览器）。仪表板会显示在失败页面：失败项按严重程度和时间从高到低排列，每张卡片都标明规则及其证据。值得点进去看看：安全规则捕获到的 PII 泄漏；摘要器照办了论坛帖子中的隐藏指令；源文档中从未提及的数字；对同一组十二个问题的两次运行进行区间对比（运行记录）；一条已部署的自定义规则和一条已暂停的规则，以及它们的审计记录；还有一次失败的 LLM 评判分数及其理由。

演示数据存放在独立的数据库中（Iris 主目录下的 demo.db——macOS/Linux 上为 ~/.iris，Windows 上为 %USERPROFILE%\.iris），绝不会与真实追踪记录混在一起。只需一条命令即可删除所有演示数据：

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

接入你自己的 Agent

首先，验证安装可在这台机器上正常运行——它离线运行，不会打开你的任何文件：

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 文档声明支持——安装程序会写入客户端文档中规定的配置格式，并针对该格式测试写入器；Iris 团队无人实际观察过这些客户端成功连接：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**。现在，把这句话发给你的 Agent：

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

跟踪记录及其评分会显示在仪表板上。若希望 MCP 服务以无头模式运行，请从参数中移除 --dashboard——你随时可以通过 npx @iris-eval/mcp-server --dashboard 打开同一个仪表板。

有一点最好一开始就了解： MCP 工具只有在模型决定调用时才会运行。Iris 不会拦截你的 Agent，因此只有当 Agent 请求 Iris 记录跟踪时，跟踪记录才会被记录——这可能是因为你告诉了它，也可能是因为你的代码直接调用了这些工具。让 Agent“将此记录到 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

另一个需要单独安装的插件：它的钩子会记录每一轮对话的提示词、工具调用（包括失败的调用及 Agent 收到的错误）和最终回答，并以提示词为键，因此中断轮次的调用和后台子 Agent 的调用也会发送给 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 接口，并连同输入、输出、令牌用量和工具调用一起存储和评分：这种采集方式不依赖模型调用工具。Python 客户端使用 wrap_openai / wrap_anthropic；Vercel AI SDK 使用 @iris-eval/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")]})

每次顶层运行都会成为一条 trace（运行本身、模型调用、工具调用和图节点均作为 GenAI span），其中包含输入、输出、工具调用、令牌用量和判定结果。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/[email protected]，并设置 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 从标准输入或文件读取一条 JSON trace（或每行一条的 NDJSON），存储该 trace，严格按照 evaluate_output 运行时使用的规则对其进行评估，针对每条 trace 输出一行包含判定结果及其依据的 JSON；当判定结果符合 --fail-on 时，退出码为 1。--dataset <id|label> 会将门禁限制为数据集中的 case key（POST /api/v1/datasets 可将一次运行的 case key 加入数据集），因此作业只会因你选择的案例而失败。完整配方、退出码和八种依据见 docs/ci-gate.md。

将规则编写为代码

config.json 中的 eval.plugins 会加载你编写的规则——一个默认导出 { 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

与服务运行的引擎、规则和组合器完全相同；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 主目录不存在时创建该目录，并检查其是否可写（如果不可写，则以退出码 1 退出并指出路径）；报告数据库搜索索引的状态（完整、后台构建目前已索引的追踪数量，或此 SQLite 不支持 FTS5）；读取数据库架构（如果此版本或固定使用旧版的 MCP 客户端无法打开数据库，则以退出码 1 退出并提供修复方法）；然后在隔离的临时主目录中运行检查，包括存储往返测试、检测由安全规则拦截的预置 SSN 和预置注入内容、仪表板启动以及 DNS 重绑定防护。它只会读取你的真实数据库，不会修改它。Iris 写入的所有内容都存放在一个目录中，即你的 Iris 主目录：默认路径为 ~/.iris（Windows 上为 %USERPROFILE%\.iris），也可以是 IRIS_HOME 指定的路径。iris.db、config.json、custom-rules.json、audit.log、preferences.json 和演示文件都存放在此处；将 IRIS_HOME 指向临时目录，即可在不触碰真实数据的情况下试用 Iris。

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

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

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

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

其他安装方式

# 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）会将追踪记录持久存储在 ~/.iris/iris.db。使用 npx 时，追踪记录也会持久保存在同一位置，但由于需要解析软件包，启动速度较慢。

你将获得什么

接下来将如何发展：能力图谱——列出可向 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 的 Agent 都可以调用 — 覆盖追踪和规则生命周期、跨运行比较、LLM-as-judge 以及语义引用核验：

• log_trace — 记录一次 Agent 执行，包括 spans、工具调用、令牌用量和成本；传入 evaluate: true 可在同一次调用中对其评分
• evaluate_output — 根据完整性、相关性、安全性和成本规则评估输出质量（启发式、确定性、免费）
• get_traces — 查询已存储的追踪记录，支持筛选、分页和时间范围；也可通过 q 查找 Agent 说过某内容的运行记录：对输入、输出、工具调用值和元数据进行全文搜索，按相关性排序，并标出匹配词
• list_rules — 列出已部署的自定义评估规则（只读）
• deploy_rule — 注册新的自定义评估规则，使其在该类别的每次 evaluate_output 调用中生效
• delete_rule — 移除已部署的自定义规则（破坏性操作、幂等）
• delete_trace — 按 ID 移除单条已存储的追踪记录（破坏性操作，限定租户）
• evaluate_with_llm_judge — 通过 LLM 进行语义评估（Anthropic 或 OpenAI）。提供七种模板：准确性、帮助性、安全性、正确性、忠实度、任务完成度、相关性。设有成本上限，并公开每次评估的定价。请自备 API 密钥（IRIS_ANTHROPIC_API_KEY 或 IRIS_OPENAI_API_KEY）— Iris 不会代理或中继 LLM 调用。
• verify_citations — 从输出中提取引用（编号引用、作者-年份格式、URL、DOI），通过受 SSRF 防护且设有域名白名单的解析器获取来源，并使用 LLM judge 检查每个来源是否确实支持相应引用主张。默认不启用出站 HTTP。与 evaluate_with_llm_judge 有相同的 BYOK 要求。
• compare_runs — 某项更改是否让 Agent 表现变差？比较两次运行中存储的评估：如果两次运行共享案例键，则进行配对精确检验；否则计算差值区间；如果无法判断，则如实给出“无法判断”以及所需的案例数；也可能得出“在误差范围内等效”。每条规则都有自己的单侧检验，并统一进行校正（Benjamini–Hochberg），避免二十条规则凭空制造出回归
• compare_traces — Agent 对同一问题的回答有多可靠？显示各案例的通过率及其区间，优先列出不稳定案例，并提供考虑重复次数的总体通过率
• evaluate_runs — 根据当前规则重新评估某次运行中的所有追踪记录，并生成新的运行记录，避免将规则变更误判为 Agent 变更 启用 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：在 run 命令中添加 -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）；每条规则结果都会携带生效的 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，每次最多 10 条）；它们会与所选 eval_type 规则集一同触发，也可以单独使用 eval_type: "custom"。已部署规则通过 deploy_rule 注册一次，保存在 Iris 主目录下的 custom-rules.json 中，并会在之后每次 evaluate_output 的 evalType 与之匹配时触发。两种方式的定义格式相同：

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。部署一条关键规则，禁止 Agent 输出任何内部主机名：

{
  "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": { "…": "…" } } }

从下一次 eval_type: "safety" 的 evaluate_output 开始，凡是提及 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 许可证，没有使用限制，也无需账户。托管存储、团队共享历史记录和告警功能目前仍在考虑中，尚未开始开发；如果这些功能对你有帮助，请发送邮件至 [email protected] 告诉我们。

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

示例

• Claude Desktop 配置 — 适用于 stdio 和 HTTP 模式的 MCP 配置
• TypeScript — MCP SDK 客户端 — 连接并调用工具
• HTTP 传输（TS + Python） — 用于 REST 风格集成的完整客户端代码
• 一个逐次评分的 LangGraph Agent（Python） — 在图的回调中使用 IrisCallbackHandler；CI 使用脚本化模型运行同一张图
• 通过 OpenTelemetry 接入的 CrewAI 团队（Python） — OpenInference 插桩直接连接 Iris 的 OTLP 接口，并将 CrewAI 配方作为脚本运行
• 通过 OpenTelemetry 接入的 OpenAI Agents SDK Agent（Python） 和 (JavaScript)，以及 一个 LlamaIndex Agent — 每个配方都作为脚本，由 CI 对接真实的 Iris 服务运行

社区

• GitHub Issues — Bug 报告和功能请求
• GitHub Discussions — 问题和想法
• 贡献指南 — 如何参与贡献
• HTTP 接收 — 通过 POST /api/v1/traces 确定性地捕获追踪数据
• 功能一览 — 可以向 Iris 提出的所有问题，以及它无法回答的内容
• 版本策略 — 每个版本号代表什么，以及发布 1.0 前必须满足的条件

# Production deployment
iris-eval --transport http --port 3000 --api-key "$(openssl rand -hex 32)" --dashboard

# 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

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

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

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

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

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

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

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

# 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——这能帮助其他人找到它。

采用 MIT 许可。