Iris

Iris — 別再靠感覺交付 agent

Iris 為每一次 agent 執行評分品質、安全性與成本——在你的機器上，無需 SDK、無需帳號。 多數 agent 專案靠跑幾個記得的提示詞、再目測輸出，來檢查品質。Iris 用你可稽核的數字取代這套做法：你的 agent 執行紀錄會落入你磁碟上的 SQLite 資料庫，25 條內建規則以確定性方式為其評分——PII、提示注入、幻覺標記、成本門檻，以及 agent 自身的工具呼叫——免費、不需 LLM 呼叫，另可選配設有每次評估硬性成本上限的 LLM 評審，處理語意層面的問題。每一條規則都可檢視、可編輯，因為無法稽核的評審，不過是披著數字的感覺。MIT 授權、無遙測。除非你開啟以下任一功能，否則沒有任何資料離開你的機器：OpenTelemetry 端點（IRIS_OTEL_ENDPOINT），可將追蹤匯出到你指定的 collector；使用你自己金鑰的 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 提供儀表板（首次執行時瀏覽器會自動開啟）。儀表板預設停在 Failures：先顯示最嚴重、最新的失敗，每張卡片標明規則與證據。值得點進去看看——被安全規則攔下的 PII 外洩、論壇貼文中隱藏指令被摘要器遵從、來源文件從未提到的數字、同一組十二道問題的兩次執行以區間比較（Runs）、一條已部署的自訂規則與一條暫停的規則及其稽核列，以及一次失敗的 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 或更新版本時（Claude Desktop 1.1.6679 搭載 24.13）以該 Node 執行 Iris，而 Iris 使用 Node 內建的 SQLite 儲存追蹤，存放在與其他安裝相同的 ~/.iris。發行說明會說明如何驗證其簽章與建置證明。

它可在任何 MCP 用戶端中執行，而它所點名的每個用戶端都有一列記錄實際檢查過的內容。每次 CI 執行皆已驗證：Claude Code、Gemini CLI——真實用戶端會從安裝程式寫入的設定啟動 Iris，並回報已連線（claude mcp list、gemini mcp list），涵蓋 Linux、macOS 與 Windows；Claude Code 的 capture 外掛鉤子也是透過真實腳本驅動。根據各用戶端自身的 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 要求記錄時才會被記錄——無論是你叫它做，還是你的程式碼直接呼叫工具。叫你的 agent「把這個記錄到 Iris 並評估」即可。如果你想要不依賴模型選擇的擷取方式，POST /api/v1/traces 正是做這件事——你的程式碼透過純 HTTP 傳送追蹤，迴路中沒有模型（見 docs/http-ingest.md）。路線圖上的 CLI 與主機鉤子將是同一端點的輕量用戶端。

透過 HTTP 擷取（迴路中無模型）

ingest 端點位於儀表板埠——預設為 6920，而非 MCP 傳輸埠——且僅在儀表板執行期間存在。傳入 --dashboard（或設定 IRIS_DASHBOARD=true）；單獨的 --transport http 不會啟動它，而對傳輸埠的請求會回傳 404。儀表板啟動後，任何能傳送 HTTP 請求的東西都能記錄追蹤——並可選擇在同一請求中執行確定性評估。同一埠上的 GET /api/v1/capabilities 會說明此伺服器能評判什麼、每條規則需要什麼、評審狀態及啟用步驟、以及限制——與 MCP 資源 iris://capabilities 提供的物件相同——因此 HTTP 呼叫端能取得 MCP 用戶端在 initialize 時得到的框架：

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 工具相同的主體，並與儀表板其餘部分共用同一中介層堆疊：預設啟用 loopback 綁定與 DNS-rebinding 防護，設定 Bearer 驗證後亦會啟用。關於它的兩個事實： 除非 Iris 以 --api-key（或 IRIS_API_KEY）啟動，否則它接受未驗證的寫入——loopback 綁定是預設將其限制在你機器上的機制，因此在綁定到 loopback 之外前請先設定金鑰；它所儲存的內容是逐字保留——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，儲存的評估文字中會遮蔽關鍵片段——這種擷取不依賴模型決定呼叫工具。它絕不會記錄模型已記錄過的回合、絕不輸出、絕不阻塞、絕不將任何資料傳送到任何地方。單獨安裝 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": []}

一個針對 0.16.0 及更新版本伺服器 HTTP API 的輕量用戶端，獨立版本化——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 span），含輸入、輸出、工具呼叫、token 用量與判定。Python 在用戶端中（下一個版本，尚未發布至 PyPI），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 detector_veto

或 GitHub Action（0.16.0），會在你指定的判定上讓工作失敗、將收據寫入工作摘要，並以單一 pull-request 留言原位更新發布：uses: iris-eval/mcp-server/.github/actions/gate@v0.19.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；每個框架一個配方（Pydantic AI、Google ADK、LangGraph via LangSmith、CrewAI、OpenAI Agents SDK（Python 和 JavaScript）、LlamaIndex、AutoGen、Microsoft Agent Framework、Semantic Kernel、Vercel AI SDK 和 Mastra），每個配方都由一個 fixture 驗證，詳見 docs/otel-recipes.md。ingest 從 stdin 或檔案讀取一個 JSON trace（或 NDJSON，每行一個），儲存它，並在 evaluate_output 執行的完全相同的規則下評估它，每個 trace 輸出一行 JSON，包含 verdict 及其依據，當 verdict 符合 --fail-on 時以退出碼 1 結束。--dataset <id|label> 將該門檻限制為資料集中的 case keys（POST /api/v1/datasets 將一次執行的 case keys 提升為一個），因此工作只會在您選擇的 cases 上失敗。完整配方、退出碼和八個依據位於 docs/ci-gate.md。

將規則寫成程式碼

eval.plugins 在 config.json 中載入您編寫的規則 — 一個 ES module，其 default export 是 { name, kind, mechanism, version, needs, evaluate(ctx) } — 並以檔案的 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

每個入口上的一個 body：它是 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，並指明路徑），報告您的資料庫搜尋索引的位置（完整、背景建置迄今已索引多少 traces，或此 SQLite 上沒有 FTS5），讀取您的資料庫 schema（如果此版本或固定到較舊版本的 MCP 用戶端無法開啟它，退出碼 1，並附上修復方法），然後在隔離的臨時 home 中執行其檢查 — 儲存往返、植入的 SSN 和植入的注入被安全規則捕獲、儀表板啟動、DNS-rebinding 防護。您的真實資料庫只會被讀取，絕不會更改。Iris 寫入的所有內容都位於一個目錄下，您的 Iris home：預設為 ~/.iris（Windows 上為 %USERPROFILE%\.iris），或 IRIS_HOME 指向的任何位置。iris.db、config.json、custom-rules.json、audit.log、preferences.json 和 demo 檔案都位於此處；將 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）將 traces 持久儲存在 ~/.iris/iris.db。使用 npx，traces 會持久儲存在相同位置，但由於套件解析，啟動速度較慢。

您獲得的內容

接下來發展方向：能力地圖 — 每個 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 作為評判者，以及語意引用驗證：

• log_trace — 記錄代理程式執行，包含跨度、工具呼叫、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）進行語意評估。七種範本：準確性、有用性、安全性、正確性、忠實性、任務完成、相關性。有成本上限，每次評估價格公開。自備 API 金鑰（IRIS_ANTHROPIC_API_KEY 或 IRIS_OPENAI_API_KEY）——Iris 不代理或轉發 LLM 呼叫。
• verify_citations — 從輸出中擷取引用（編號、作者-年份、URL、DOI），透過受 SSRF 防護且網域白名單的解析器取得來源，並使用 LLM 評判者檢查每個來源是否確實支援被引用的主張。選擇性啟用對外 HTTP。與 evaluate_with_llm_judge 相同的 BYOK 要求。
• 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：在 run 指令加上 -e IRIS_ANTHROPIC_API_KEY=...。HTTP 或 CI：在啟動 iris-eval 前先 export。
3. 重新啟動 MCP 工作階段。執行中的處理程序永遠不會看到啟動後才設定的變數。
4. 從用戶端內部確認：讀取 iris://capabilities——judge.enabled 必須為 true。在你的 shell 中 export 的金鑰不會傳遞給你用戶端啟動的處理程序，除非其設定列出它。在機器上，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 美元）設上限，若最壞情況會超過則在花費前拒絕。Iris 直接使用你的金鑰呼叫提供者，絕不代理。
6. 選用：設定 IRIS_RELEVANCE_JUDGE_MODEL 為有價格的模型 ID（例如 claude-haiku-4-5），讓 answers_the_ask 要求評判者檢查每個答案是否回應其提問，並讓離題的答案失敗。這是每次帶有輸入的評估的一次評判者呼叫，使用你的金鑰且在上述上限內；僅有金鑰不會啟用它。每次呼叫會將該輸入和輸出傳送給模型的提供者，個人資料和憑證的 no_pii 旗標會先被取代（IRIS_RELEVANCE_JUDGE_REDACT=off 則原樣傳送）。每個 UTC 日最多花費 IRIS_RELEVANCE_JUDGE_DAILY_BUDGET_USD（預設 1 美元），每個請求最多進行 IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST 次呼叫（預設 20）；超過任一限制後，answers_the_ask 會以詞彙方式讀取提問並說明原因。

當 IRIS_OTEL_ENDPOINT 已設定時，log_trace 呼叫也會發出盡力而為的 OTLP/HTTP JSON 匯出，送往任何 OpenTelemetry 收集器（Jaeger、Grafana Tempo、Datadog OTLP、Honeycomb 等）。請參閱 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，所有套件都會執行——完整性、相關性、安全性、成本和任何自訂規則——且回應會以 note 說明 eval_type: "all" 已執行預設，並附上每個套件的 categories 對應。沒有可評判內容的套件（無 cost_usd 的成本、無 input 的相關性）會在該處回報 passed: null——未評估、未失敗——且永遠不計入裁決。回應永遠會回應已執行的 eval_type，因此你的閘道可以驗證覆蓋範圍；以 passed 作為裁決的關鍵，且僅在想要較窄的執行時指定套件。

編寫自訂規則

新增規則有兩種方式。內聯規則隨單次 evaluate_output 呼叫（custom_rules，每次呼叫最多 10 個）一起執行；它們與你選擇的任何 eval_type 套件一起觸發，或單獨使用 eval_type: "custom"。已部署規則透過 deploy_rule 註冊一次，在 custom-rules.json 中你的 Iris 主目錄下持久化，並在未來每次其 evalType 的 evaluate_output 時觸發。定義無論哪種方式都是相同形狀：

deploy_rule 以 name、選用的 description、evalType（completeness · relevance · safety · cost · custom）和 severity 包裝定義。嚴重性說明失敗的意義：low/medium 僅降低分數；high/critical 硬性失敗評估——passed: false，在 critical_failures 中點名的規則——無論加權分數為何。跳過的規則（沒有 cost_usd 的 cost_threshold 規則，或在 100 毫秒沙箱預算中被終止的正則表達式）尚未評判輸出，並改列在 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": { "…": "…" } } }

從下一次帶有 eval_type: "safety" 的 evaluate_output 開始，提及 db-primary.internal.example 的輸出會以 passed: false 回傳，附上 critical_failures: ["no_internal_hostnames"]——即使所有五個內建安全規則都通過且加權分數為 0.895。正則表達式模式必須在部署時通過 ReDoS 檢查，且總是在沙箱工作者中於 100 毫秒的硬性期限內執行。list_rules 顯示已部署的內容；儀表板的規則組合器會從你點擊的失敗中建立相同形狀。完整參考、每種類型的評分方式，以及實際範例：docs/custom-rules.md。

完整的工具結構和設定：iris-eval.com

託管功能

Iris 目前完全在你的機器上執行，它所做的一切都是免費且 MIT 授權，沒有限制也不需要帳號。 託管儲存、共享團隊歷史紀錄與警示功能正在評估中，尚未開始建置。目前沒有定價，也沒有任何需要購買的項目。如果共享歷史紀錄對您有幫助，等候名單是我們了解這是否值得開發的方式——加入名單不需承擔任何義務。

無論如何，我們有兩項承諾不變：今日免費的功能絕不會移到付費牆之後，且在取得合規認證之前，絕不會宣稱擁有該認證。

範例

• Claude Desktop 設定 — 適用於 stdio 與 HTTP 模式的 MCP 設定
• TypeScript — MCP SDK 用戶端 — 連線並呼叫工具
• HTTP 傳輸（TS + Python） — 適用於 REST 風格整合的完整用戶端程式碼
• LangGraph 代理，逐次執行評分（Python） — 在圖形的回呼中使用 IrisCallbackHandler；CI 以腳本化模型執行相同的圖形
• 基於 OpenTelemetry 的 CrewAI 團隊（Python） — 將 OpenInference 儀器直接連到 Iris 的 OTLP 端點，CrewAI 配方以腳本形式呈現
• 基於 OpenTelemetry 的 OpenAI Agents SDK 代理（Python） 與 (JavaScript)，以及 LlamaIndex 代理 — 每個配方皆為 CI 對真實 Iris 伺服器執行的腳本

社群

• GitHub Issues — 錯誤回報與功能請求
• 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 對您有用，請考慮為儲存庫加星——這有助於其他人找到它。

MIT 授權。