failproofai 1.0.1-beta.1 → 1.0.1

package/.next/standalone/docs-old/zh/agenteye/evaluation-suite.mdx

@@ -0,0 +1,300 @@
+---
+title: "评估套件"
+description: "Failproof AI Observability 可以自动对每次已完成的 Agent 运行进行质量评分：您提供一个小型评分服务，Observability 负责其余一切。"
+---
+
+
+Failproof AI Observability 可以自动对每次已完成的 Agent 运行进行质量评分：您提供一个小型评分服务，Observability 负责其余一切。使用它来追踪您关心的维度（有用性、工具效率、事实准确性、安全性；由您决定），及早发现回归问题，并一眼比较不同 Agent 或环境的表现。评分功能为可选项：在服务器上设置 `EVALUATOR_ENDPOINT` 之前，该流水线不会执行任何操作。
+
+> **注意：** 评分维度由您自行定义。您的评估器可以返回任意数值键；Observability 会存储、趋势分析并展示您返回的所有内容。
+
+## 概览
+
+1. **编写评分器。** 搭建一个小型 HTTP 服务，读取会话转录并返回评分。Observability 附带一个可直接复制使用的参考实现。请参阅[使用 SDK 编写评估器](#writing-an-evaluator-with-the-sdk)。
+2. **将 Observability 指向该服务。** 在服务器进程上设置 `EVALUATOR_ENDPOINT`（以及共享的 `EVALUATOR_TOKEN`）。
+3. **查看评分结果。** 每个已完成的会话都会被自动评分；结果显示在会话详情页、会话列表和已保存的仪表盘上。
+
+![会话详情视图，右侧边栏显示评估摘要、各维度评分条及推理文本](/agenteye/images/session-detail.png)
+
+*配置评估器后，每次已完成的运行都会被评分，结果出现在会话的右侧边栏：顶部为摘要，其下为带推理说明的各维度评分条。*
+
+---
+
+## 工作原理
+
+```mermaid
+flowchart LR
+    ING["ingest /events<br/>agent_end"] --> SRV["Observability server"]
+    SRV -->|"POST /evaluate"| EV["Evaluator service"]
+    EV -->|"done or pending"| SRV
+    SRV -->|"poll GET /evaluate/{job_id}"| EV
+    EV -->|"done"| SRV
+    SRV --> RES["evaluations<br/>terminal results"]
+```
+
+当 Observability SDK 为某个会话发出 `agent_end` 事件时，服务器会调度一次评估。随后它将完整的事件转录以 POST 方式发送到您的评估器服务，评估器可以：
+
+- **内联返回结果**，格式为 `{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}`。结果将追加到该会话的评估时间线中。`reasoning` 和 `summary` 为可选字段。
+- **延迟处理**，返回 `{"status":"pending", "job_id":"abc-123"}`。Observability 随后会轮询 `GET {EVALUATOR_ENDPOINT}/evaluate/abc-123`，直到评估器返回 `{"status":"done", ...}` 或 `{"status":"error", "error":"..."}`。
+
+  轮询频率按任务设置：`pending` 响应中可包含 `next_poll_secs` 来覆盖默认值；否则 Observability 使用 `GET /config` 返回的 `default_poll_interval_secs`；若未设置则回退到服务器的 `EVALUATOR_POLLING_INTERVAL_SECS`（默认 10 秒）。所有值均被限制在 [1s, 1h] 范围内。
+
+从未发出 `agent_end` 的会话（例如 Agent 进程崩溃）也可以被处理：评估器的 `GET /config` 可返回 `{"inactivity_timeout_secs": 1800}`，Observability 将对闲置超过该时长的会话进行评估。将该字段设为 `null` 或省略可禁用此回退机制。
+
+当 `EVALUATOR_ENDPOINT` 未设置时，该流水线完全为空操作。
+
+一个会话可以**随时间累积多条终态评估记录**：每个 `agent_end` 事件（以及从仪表盘手动触发的重新评估）都会追加一条新的评估行。这是评估已恢复对话的支持方式：用户结束一个 Agent，稍后返回，发送更多事件，再次结束 Agent，第二次评估将针对完整的更新后转录执行。仪表盘将最新评估显示为主要结果，将之前的评估显示为可折叠的时间线。当某个会话有一次评估正在进行时，该会话后续的 `agent_end` 事件将被忽略；等运行中的评估完成后，下一个 `agent_end` 事件将照常触发新的评估入队。
+
+闲置回退机制在已恢复的会话中同样生效：如果在上一次终态评估之后有新事件到达，且会话随后再次闲置超过 `inactivity_timeout_secs`，则会入队一次新的评估。
+
+暂时性失败（5xx、429、超时、网络错误）将以指数退避方式重试，最多重试 `EVALUATOR_MAX_ATTEMPTS` 次；4xx 响应为终态错误。Observability 支持多实例水平扩展运行，工作会被分区处理，确保同一会话不会被同时分发两次。
+
+---
+
+## HTTP 协议规范
+
+所有需要认证的路由均使用**Bearer Token 认证**。两端必须配置相同的值：
+
+- Observability 服务器：环境变量 `EVALUATOR_TOKEN`
+- 评估器服务：以相同方式配置（`agenteye-evaluator` SDK 按惯例读取 `EVALUATOR_TOKEN`）
+
+如果 `EVALUATOR_TOKEN` 未设置，服务器将不发送 `Authorization` 请求头；评估器可以接受匿名请求，这在纯内部网络中是可以接受的，但不建议在公共互联网上使用。
+
+### 评估器必须提供的路由
+
+| 路由 | 请求体/参数 | 响应 |
+|---|---|---|
+| `GET /health` | 无 | `{"status":"ok"}`（公开，无需认证） |
+| `GET /config` | 无 | `{"inactivity_timeout_secs": <int> \| null, "default_poll_interval_secs": <int> \| omitted}` |
+| `POST /evaluate` | `EvalRequest` JSON | `{"status":"done", ...}` 或 `{"status":"pending", "job_id":"..."}` |
+| `GET /evaluate/{id}` | 无 | 与 `/evaluate` 相同的响应格式 |
+
+### 服务器发送的 `EvalRequest` 请求体
+
+```json
+{
+  "schema_version": "1",
+  "session_id":     "session-abc123",
+  "agent_id":       "planner",
+  "environment":    "production",
+  "started_at":     "2026-05-10T12:00:00Z",
+  "ended_at":       "2026-05-10T12:05:00Z",
+  "events": [
+    { "id": 1234, "ts": "...", "event_type": "agent_start", "payload": { ... } },
+    ...
+  ]
+}
+```
+
+### 响应格式
+
+**同步（done）：**
+
+```json
+{
+  "status": "done",
+  "scores": { "helpfulness": 0.85, "tool_efficiency": 0.6 },
+  "reasoning": {
+    "helpfulness": "answered the question directly with citations",
+    "tool_efficiency": "called list_files three times when one would have done"
+  },
+  "summary": "strong answer quality, weak tool selection"
+}
+```
+
+`reasoning`（每个评分的理由映射）和 `summary`（整体一段式叙述）均为可选字段。`reasoning` 中的键应与 `scores` 中的键对应；仪表盘会在每个评分条下方内联渲染对应条目。只返回 `scores` 的旧版评估器无需修改即可继续使用；`reasoning` 和 `summary` 将显示为 null，对应的 UI 元素将被省略。
+
+**异步（延迟处理）：**
+
+```json
+{ "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 }
+```
+
+`next_poll_secs` 为可选字段；若省略，服务器将回退到评估器 `/config` 中的 `default_poll_interval_secs`，再回退到自身的 `EVALUATOR_POLLING_INTERVAL_SECS` 环境变量。
+
+**评估器侧终态错误：**
+
+```json
+{ "status": "error", "error": "model service unavailable" }
+```
+
+服务器将任何其他 2xx 响应体视为协议错误，并为该会话记录一条终态 `error`。
+
+---
+
+## 使用 SDK 编写评估器
+
+您不必手动实现 HTTP 协议规范。`agenteye-evaluator` Python 包提供了一个带类型的 FastAPI 封装，帮您处理认证、路由以及请求/响应格式。
+
+Failproof AI Observability 还附带了一个**可直接使用的参考评估器**，它根据转录的结构为 `helpfulness`、`tool_efficiency` 和 `factuality` 进行评分。您可以将其作为起点，替换为自己的逻辑：LLM 裁判、规则引擎，或任何适合您质量标准的方法。
+
+最小可用评估器示例：
+
+```python
+import os
+from agenteye_evaluator import Evaluator, EvalRequest, EvalResponse
+
+app = Evaluator(token=os.environ["EVALUATOR_TOKEN"])
+
+@app.evaluator
+def run(req: EvalRequest) -> EvalResponse:
+    # Inspect req.events (the full session transcript) and return scores.
+    tool_calls = sum(1 for e in req.events if e.event_type == "tool_use")
+    return EvalResponse(
+        scores={"tool_calls": float(tool_calls)},
+        reasoning={"tool_calls": f"{tool_calls} tool invocations in the transcript"},
+        summary="tight tool loop" if tool_calls < 5 else "agent looped on tools",
+    )
+```
+
+`app` 实例可在任何 ASGI 服务器下运行，使用 `uvicorn module:app` 即可启动。
+
+对于需要延迟执行高开销任务的评估器，可返回 `JobPending` 并注册一个 `@app.job_lookup` 处理器；Observability 服务器会轮询 `GET /evaluate/{job_id}`，直到您返回终态状态或达到 `EVALUATOR_MAX_POLL_DURATION_SECS` 上限（默认 1 小时）。
+
+完整的 API 参考、异步模式和事件模式请参阅 `agenteye-evaluator` SDK 的 README。
+
+---
+
+## 运行您的评估器
+
+评估器是**您自己的服务** —— Failproof AI Observability 不提供默认评估器，因此您需要在自己的服务基础设施中构建并运行它。它可在任何 ASGI 服务器下运行（例如 `uvicorn my_evaluator:app`）；按照 [HTTP 协议规范](#http-contract) 提供 `/health`、`/config` 和 `/evaluate` 路由，然后将服务器指向该地址（参见[配置服务器](#configuring-the-server)）。
+
+评估器可访问后，`GET /health` 将返回 `{"status":"ok"}`。Agent 完整运行结束后，在服务器上执行 `GET /evaluations` 将返回一条 `status: "done"` 的记录及您的评估器产生的评分。
+
+---
+
+## 配置服务器
+
+在服务器进程上设置以下环境变量：
+
+| 环境变量 | 说明 |
+|---|---|
+| `EVALUATOR_ENDPOINT` | 评估器的基础 URL（如 `http://evaluator:9000`）。未设置 = 流水线禁用。 |
+| `EVALUATOR_TOKEN` | Bearer Token。必须与评估器服务配置的值相同。 |
+| `EVALUATOR_WORKERS` | 每个服务器实例的工作任务数（默认 2）。 |
+| `EVALUATOR_CLAIM_BATCH` | 每次工作任务轮询时领取的行数（默认 4）。批次**并发**处理；评估器端点的实际并发量为 `EVALUATOR_WORKERS × EVALUATOR_CLAIM_BATCH`。 |
+| `EVALUATOR_POLL_IDLE_SECS` | 当没有待处理评估时，工作任务在两次分发尝试之间的休眠时长（默认 2 秒）。 |
+| `EVALUATOR_POLLING_INTERVAL_SECS` | 当响应中的 `next_poll_secs` 和评估器的 `default_poll_interval_secs` 均未设置时，`GET /evaluate/{id}` 轮询频率的最终回退值（默认 10 秒）。 |
+| `EVALUATOR_REQUEST_TIMEOUT_MS` | 单次请求超时时间（默认 30000）。 |
+| `EVALUATOR_MAX_ATTEMPTS` | 达到此次数的暂时性失败后，结果将记录为终态 `error`（默认 5）。 |
+| `EVALUATOR_CONFIG_REFRESH_SECS` | `GET /config` 刷新频率（默认 300）。 |
+| `EVALUATOR_MAX_POLL_DURATION_SECS` | 会话在轮询队列中保留的最长实际时间，超出后记录为 `timeout`（默认 3600 秒）。防止评估器持续返回 `pending` 的情况。 |
+
+要开启自动评分，在服务器上同时设置 `EVALUATOR_ENDPOINT` 和 `EVALUATOR_TOKEN`，然后重启服务器使配置生效。未设置 `EVALUATOR_ENDPOINT` 时，流水线保持空操作状态。
+
+上述调优参数均为可选项；仅在需要覆盖默认值时才在服务器上设置对应的环境变量。
+
+---
+
+## API 参考
+
+| 方法 | 路径 | 所需权限 | 用途 |
+|---|---|---|---|
+| `GET` | `/evaluations` | `evaluations:read` | 查询终态结果。支持 `session_id`、`agent_id`、`environment`、`status`（`done`/`error`/`timeout`）、`ts_from`、`ts_to`、`cursor`、`limit`、`score_filters`、`latest_per_session` 参数。`limit` 默认为 50，上限为 200（注意与 `/events` 不同，后者上限为 1000）。`environment` 接受逗号分隔的列表（如 `environment=prod,staging`）；单个值同样有效。`latest_per_session=true` 时，响应中每个 `session_id` 最多返回一条记录（按 `completed_at` 最新的一条），供会话列表页将会话评估时间线折叠为当前主要结果使用。默认为 false（返回完整历史记录）。 |
+| `GET` | `/evaluations/aggregate` | `evaluations:read` | 对过滤后的数据片段进行评估健康状况汇总：总数量、done/error/timeout 分类统计、各评分键的统计数据（count/avg/min/max/p50，针对任意 `scores` 键），以及按时间分桶的趋势时间线。接受与 `/evaluations` **相同的过滤参数**，额外支持 `featured_keys`（要趋势展示的评分键 CSV）和 `latest_per_session`。为仪表盘功能提供数据；指标对整个匹配集进行精确计算，不进行采样。 |
+| `GET` | `/evaluations/environments` | `evaluations:read` | 从 `evaluations` 表中获取不重复的 environment 值。用于填充评估数据范围内的过滤下拉菜单。 |
+| `GET` | `/evaluation-jobs` | `evaluations:read` | 查看进行中的评估。支持按 `status`（`pending`/`polling`）过滤。 |
+| `GET` | `/events` | `events:read` | 流式获取会话的原始事件。支持 `session_id`、`agent_id`、`event_type`（CSV）、`environment`（CSV）、`ts_from`、`ts_to`、`cursor`、`limit` 和 `order` 参数。`order` 为 `desc`（最新优先，默认值）或 `asc`（最旧优先）；无法识别的值将回退为 `desc`。通过响应中的 `next_cursor`（事件 id）进行游标分页：将其作为 `cursor` 传回以获取下一页；`asc` 模式下下一页为该 id 之后的事件，`desc` 模式下为该 id 之前的事件。`limit` 默认为 50，上限为 1000。 |
+| `GET` | `/sessions/:session_id/export` | `events:read` | 返回评估器将接收到的该会话的精确 JSON 请求体，以可下载附件形式提供，文件名为 `session-<id>.json`。适用于将生产会话通过 `agenteye-evaluator` 进行离线测试回放。字节内容与评估流水线实际发送的完全一致。 |
+| `POST` | `/sessions/:session_id/re-evaluate` | `evaluations:trigger` | 为会话入队一次新的评估；无论是否存在之前的评估均可执行。新结果将**追加**到会话的评估时间线，而不是覆盖之前的结果，因此历史评分仍然可见。入队成功返回 `202`，会话不存在返回 `404`，已有评估正在进行中返回 `409`。适用于部署新评估器后，或对从未发出 `agent_end` 的会话重新评估。 |
+
+### 按评分范围过滤：`score_filters`
+
+`GET /evaluations` 接受可选的 `score_filters` 参数，用于按 `scores` 对象中的数值缩小结果范围。该参数为逗号分隔的 `key:min..max` 条目列表；上下界均可省略。多个条目以逻辑 AND 组合。指定键不存在或非数值的行将被排除。单次请求最多可包含 20 条过滤条目；超出后返回 HTTP 400。
+
+示例：
+```text
+# helpfulness 在 [0.5, 0.8] 范围内
+GET /evaluations?score_filters=helpfulness:0.5..0.8
+
+# tool_efficiency 最高为 0.3（无下限）
+GET /evaluations?score_filters=tool_efficiency:..0.3
+
+# helpfulness >= 0.5 且 factuality >= 0.9
+GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9..
+```
+
+每条 `/evaluations` 响应对象包含以下字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `evaluation_id` | string (UUID) | 此终态评估的规范标识符。每次终态评估都会获得一个新的 UUID；单个会话可包含多条评估。 |
+| `id` | string (UUID) | 向后兼容别名，与 `evaluation_id` 值相同。 |
+| `session_id` | string | 此评估所针对的会话。一个会话在时间线中可包含多条评估。 |
+| `agent_id` | string | 标识产生该会话的 Agent。 |
+| `environment` | string | 从会话中复制的环境标签。 |
+| `status` | enum | `"done"`、`"error"` 或 `"timeout"` 之一。 |
+| `scores` | object \| null | 评估器返回的评分。 |
+| `reasoning` | object \| null | 评估器返回的可选逐评分理由映射。键通常与 `scores` 中的键对应。仪表盘在每个评分条下方渲染各条目。 |
+| `summary` | string \| null | 评估器返回的可选整体一段式叙述。仪表盘在各评分详情上方将其渲染为评估的主要标题。 |
+| `error` | string \| null | 仅在 `"error"` / `"timeout"` 时填充。 |
+| `attempt_count` | integer | 分发尝试次数（≥ 1）。 |
+| `duration_ms` | integer \| null | 最后一次尝试的耗时。 |
+| `completed_at` | string (ISO 8601 UTC) | 终态结果的记录时间。结果按 `completed_at` 排序（最新优先）。 |
+| `created_at` | string (ISO 8601 UTC) | 与 `completed_at` 时间戳相同（写入后不可修改）。 |
+
+---
+
+## 权限
+
+| 权限 | 授予能力 |
+|---|---|
+| `evaluations:read` | 列出评估结果、在仪表盘中查看评分，以及加载仪表盘健康指标。 |
+| `evaluations:trigger` | 通过 `POST /sessions/:session_id/re-evaluate` 或仪表盘的重新评估按钮手动为会话入队评估。 |
+| `dashboards:read` | 查看已保存的仪表盘（同时需要 `evaluations:read` 以加载指标）。 |
+| `dashboards:write` | 创建和编辑仪表盘。 |
+| `dashboards:delete` | 删除仪表盘。 |
+
+引导管理员（`ADMIN_KEY`、`ADMIN_EMAIL`）会自动获得上述所有权限。
+
+---
+
+## 查看结果
+
+- **`/sessions/<id>`**：事件时间线 + 右侧边栏，显示会话的评分及分发尝试中的任何错误。如果您的密钥具有 `evaluations:trigger` 权限，导出按钮旁会出现**重新评估**按钮，适用于从未发出 `agent_end` 的会话，或部署新评估器后刷新评分。仪表盘会轮询新结果，并在结果就绪时更新右侧边栏。
+- **`/sessions`**：可过滤的会话列表；评分列一眼显示每个会话的评估状态和评分。
+- **`/dashboards`**：已保存的评估健康视图（参见下方[仪表盘](#dashboards)）。
+
+![会话列表，显示每个会话的评估状态标签和颜色编码的评分徽章（helpfulness、factuality、tool_efficiency、safety、coherence）](/agenteye/images/sessions-list.png)
+
+*会话列表一眼显示每次运行的评估状态和评分；红/黄/绿徽章让低评分一目了然。*
+
+---
+
+## 仪表盘
+
+**仪表盘**页面（`/dashboards`）允许您将一组评估过滤条件保存为命名的可复用视图，并一眼了解该数据片段的评估状况。仪表盘在**整个组织内共享**；所有具有 `dashboards:read` 权限的人都能看到相同的仪表盘集合。
+
+每个仪表盘固定以下配置：
+
+- **过滤条件**：与会话页面相同的控件：环境、状态、Agent、滚动时间窗口和评分范围过滤器（`key:min..max`）。
+- **显示配置**：要重点展示的评分键、绿/黄/红健康阈值、要显示的面板，以及是否折叠为每个会话的最新评估。
+
+每张卡片显示匹配会话数量、done/error/timeout 分类统计、每个重点评分的平均值，以及小型趋势迷你图。打开仪表盘可查看全尺寸面板；**"在会话中打开"**可跳转至预先过滤到该数据片段的会话页面。指标通过 `GET /evaluations/aggregate` 在服务端对整个匹配集进行精确计算，结果为精确值而非采样值。
+
+![评估健康仪表盘，显示每个评估维度的平均评分条、工具正常/错误分类统计、热门工具及每小时事件趋势](/agenteye/images/dashboard-quality.png)
+
+**权限：** 查看需要同时具备 `dashboards:read` 和 `evaluations:read`；创建和编辑需要 `dashboards:write`；删除需要 `dashboards:delete`。引导管理员会自动获得所有这些权限。
+
+---
+
+## 故障排查
+
+**会话存在但未创建任何评估。** 确认服务器进程上已设置 `EVALUATOR_ENDPOINT`，服务器和评估器使用相同的 `EVALUATOR_TOKEN` 值，且评估器的 `/health` 端点可从服务器访问。未设置 `EVALUATOR_ENDPOINT` 时，流水线为空操作。
+
+**进行中的评估积压。** 查询 `GET /evaluation-jobs` 查看进行中的队列。检查每条记录的 `attempt_count`、`next_attempt_at` 和 `last_error`。常见原因：评估器服务不可达或返回 5xx（以退避方式重试）、`EVALUATOR_TOKEN` 错误（401 为终态错误），或异步评估器无限期返回 `pending`（参见下文）。
+
+**会话已完成但无终态评估。** 查询 `GET /evaluation-jobs?status=polling`；结果可能仍在进行中。如果某个任务卡在 `pending` 状态，说明服务器无法访问评估器；检查评估器是否正常运行且 `EVALUATOR_TOKEN` 是否匹配。
+
+**`HTTP 401 from evaluator: invalid bearer token`。** 服务器上的 `EVALUATOR_TOKEN` 与评估器服务配置的值不匹配。两者必须完全相同。
+
+**异步评估器持续返回 `pending`。** 服务器会轮询 `GET /evaluate/{job_id}`，直到评估器返回 `done` 或 `error`，或达到 `EVALUATOR_MAX_POLL_DURATION_SECS` 上限（默认 1 小时）。超出上限后，评估将被记录为 `timeout` 并从进行中的队列中移除。如果您的评估器合理地需要超过默认时长，请适当增大 `EVALUATOR_MAX_POLL_DURATION_SECS`。
+
+---
+
+## 后续步骤
+
+- [评估器 Agent 技能](/zh/agenteye/evaluator-skill)：让编码 Agent 针对真实会话设计您的评估维度并为您构建该服务。
+- [Python SDK](/zh/agenteye/python-sdk)：发出触发评分的 `agent_end` 事件。
+- [API 密钥](/zh/agenteye/api-keys)：`evaluations:read` 和 `evaluations:trigger` 权限。
+- [审计](/zh/agenteye/audits)：Observability 的另一个自动化质量功能，用于基于策略的审查。

package/.next/standalone/docs-old/zh/agenteye/evaluations.mdx

@@ -0,0 +1,51 @@
+---
+title: "评估"
+description: "质量问题主动找上门，而不是等到用户投诉时你才得知。"
+---
+
+
+质量问题主动找上门，而不是等到用户投诉时你才得知。只需接入一次你自己的评分服务，Failproof AI Observability 就会自动对每一次完成的运行打分——帮助性下降或幻觉激增等问题会在用户察觉之前自动浮现。
+
+![Sessions 网格中的分数列：每次运行都带有评估状态标记，以及颜色编码的帮助性、真实性和工具效率徽章](/agenteye/images/sessions-list.png)
+
+*Sessions 网格中的每次运行都携带其评分；红色、琥珀色和绿色徽章让问题运行一眼可见，无需打开任何一条记录。*
+
+## 告别手动抽样检查
+
+过去你只能抽查少数几次运行，然后祈祷其余的没有问题。现在，每一次已完成的会话在结束的那一刻就会按你关心的维度自动评分：帮助性、工具效率、真实性、安全性，以及任何你设定的质量标准。你来定义评分键；Failproof AI Observability 负责存储、追踪并展示评估器返回的所有内容。没有任何运行会漏掉评分，你也不必再从支持工单里得知回归问题。
+
+评分会随着会话展示在 **`/<org-slug>/sessions`** 的 Sessions 网格上（侧边栏 → *observe* → *sessions*），每行一组徽章簇。只想查看表现不达标的运行？按分数范围筛选，比如帮助性低于 0.5，精准定位值得深入阅读的运行。查看评分需要 `evaluations:read` 权限。
+
+## 了解运行低分的原因
+
+数字告诉你某次运行表现不佳；会话页面则告诉你原因。打开任意一次运行，右侧面板首先显示总体摘要，随后按维度展示评分条，每条下方附有评估器自身的推理说明——让你在几秒内从"真实性评分 0.4"定位到具体出错的那个论断。
+
+![会话的右侧面板：顶部是评估摘要，下方是各维度评分条及各条推理说明，旁边是完整的事件时间线](/agenteye/images/session-detail.png)
+
+*会话详情视图：摘要、各维度评分条，以及每项评分背后的推理说明，与运行事件时间线并排显示。*
+
+部署了更精准的评估器，或者遇到运行在评分前崩溃的情况？**重新评估**按钮（需要 `evaluations:trigger` 权限）可以就地对会话重新评分，并将最新结果追加到其时间线中，此前的评分作为历史记录仍然可见。你可以在 **`/<org-slug>/sessions/<session-id>`** 找到该按钮。
+
+## 监控整个队列的质量趋势
+
+单次运行低分是噪声；整个批次下滑才是信号。已保存的仪表板将你的评分转化为可一目了然的趋势：本周与上周的平均帮助性对比，按 Agent、按环境分别呈现。
+
+![质量仪表板：各评估维度的平均分柱状图，以及时间趋势折线](/agenteye/images/dashboard-quality.png)
+
+*已保存的质量仪表板展示你关注的评分键趋势，让缓慢的下滑在演变为事故之前早早显现。*
+
+仪表板位于 **`/<org-slug>/dashboards`**（侧边栏 → *analyze* → *dashboards*），在整个组织内共享。每张卡片汇总对应的会话数据：运行数量、每个关注评分的平均值，以及趋势迷你折线图。点击"在 Sessions 中打开"可直接跳转到任意数字背后已预筛选的运行列表。查看需要 `dashboards:read` 和 `evaluations:read` 权限。
+
+## 一次接入评估器
+
+评分功能为可选项，在你将 Failproof AI Observability 指向一个评分服务之前，始终保持关闭状态。你只需搭建一个小型 HTTP 服务（Observability 提供了一个可直接复制的参考实现），在服务器上设置两个值，此后每次运行都会自动获得评分。完整操作指南、评分契约和 SDK 详见深度指南。
+
+不确定该从哪些维度开始评分？[评估器 Agent 技能](/zh/agenteye/evaluator-skill)可以让你的编码 Agent 结合你自己的会话数据找出答案，然后构建并部署该服务。
+
+## 相关内容
+
+- [评估套件](/zh/agenteye/evaluation-suite)：接入评估器、评分契约与 SDK。
+- [评估器 Agent 技能](/zh/agenteye/evaluator-skill)：让编码 Agent 选定评分维度并构建评估器。
+- [Sessions](/zh/agenteye/sessions)：展示评分的逐次运行网格。
+- [仪表板](/zh/agenteye/dashboards)：在组织内保存并共享质量趋势。
+- [审计](/zh/agenteye/audits)：Observability 的另一项自动质量功能，用于跨会话调查。

package/.next/standalone/docs-old/zh/agenteye/evaluator-skill.mdx

@@ -0,0 +1,167 @@
+---
+title: "Failproof AI 可观测性评估器 Agent 技能"
+description: "让您的编程 Agent 既负责决策又负责构建，从「我觉得我们的 Agent 有时表现很差」直接走向部署完毕的评分服务。"
+---
+
+
+让您的编程 Agent 既负责决策又负责构建，从*「我觉得我们的 Agent 有时表现很差」*直接走向部署完毕的评分服务。**Failproof AI 可观测性评估器技能**（`agenteye-evaluator`）是一种 *Agent Skill*：一个小型指令文件夹，供 Claude Code 或 Codex 等编程 Agent 按需加载。它能引导 Agent 确定哪些质量维度值得为*您的* Agent 跟踪，然后编写、测试并部署对这些维度进行评分的[评估器服务](/zh/agenteye/evaluation-suite)。
+
+它**不是**一个托管评分器、一个您上传到的注册表，也不是插件系统。您的评估器始终是运行在您自己基础设施上的 HTTP 服务，与[评估套件](/zh/agenteye/evaluation-suite)指南中所描述的完全一致。该技能只是教您的 Agent 如何把它构建好——它所做的一切，您完全可以自己动手写同样的代码来实现。
+
+---
+
+## 难点在于决定评分什么
+
+SDK 接口很简洁——一个装饰器和两个模型——Agent 仅凭[契约](/zh/agenteye/evaluation-suite#http-contract)就能把代码写出来。评估器真正的失败之处不在这里。它们失败是因为评错了东西，而评错对象的评估器比没有还糟：它产出的仪表盘会让所有人习惯性地无视。
+
+因此，该技能的大部分工作发生在任何代码存在之前。它让 Agent 对您进行访谈（*「描述一次进展顺利的运行；再描述一次进展糟糕的」*），然后通过 [`agenteye` CLI](/zh/agenteye/cli) 提取您的真实会话并从头到尾阅读。这两部分通常会出现分歧，而这个差距正是关键所在：您打算衡量什么，与您的对话记录实际上能支撑什么，往往并不一致。一个维度只有在**可从事件中计算**且**具有区分度**时才能保留——如果它在您的好运行和差运行上都打出 0.9 分，那什么也说明不了，直接剔除。
+
+最终返回的是一份包含 2-4 个维度的提案，附带推理说明，供您在写下任何一行代码之前确认。
+
+```mermaid
+flowchart TD
+    YOU["您：「我想为我的支持机器人做评估」"] --> AGENT["编程 Agent（Claude Code / Codex）<br/>加载 agenteye-evaluator 技能"]
+    AGENT -->|"访谈：好的表现和差的表现分别是什么样的？"| YOU
+    AGENT -->|"agenteye --json sessions / events"| DATA["您的真实会话<br/>实际发生的情况"]
+    DATA --> DIMS["2-4 个维度，由您确认"]
+    DIMS --> SVC["您的评估器服务<br/>agenteye-evaluator SDK"]
+    SVC --> SCORES["评分出现在仪表盘<br/>和 agenteye evals 中"]
+```
+
+---
+
+## 与其他评估组件的关系
+
+共有四份文档涵盖评分相关内容，它们按顺序相互衔接：
+
+| 页面 | 内容 | 适用场景 |
+|---|---|---|
+| **[评估（Evaluations）](/zh/agenteye/evaluations)** | 该功能：会话网格上的评分、仪表盘、重新评估 | 您想了解自动评分能带来什么 |
+| **[评估套件（Evaluation suite）](/zh/agenteye/evaluation-suite)** | HTTP 契约、SDK、服务器环境变量 | 您正在自行实现或调试评估器 |
+| **评估器技能**（本文档） | 设计*并*构建评分器的自然语言入口 | 您想从「我想要评估」走到一个正在运行的服务 |
+| **[CLI 技能](/zh/agenteye/cli-skill)** | `agenteye` CLI 的自然语言入口 | 您想*读取*已有的评分结果 |
+| **[Python SDK 技能](/zh/agenteye/python-sdk-skill)** | 为您的 Agent 添加埋点的自然语言入口 | 您的 Agent 尚未输出会话——还没有东西可以评分 |
+
+### 与 CLI 技能的区别：构建 vs. 读取
+
+这两个技能在职责上刻意不重叠，同时安装两者是常规配置——Agent 会根据您的提问在二者之间切换：
+
+- **`agenteye-evaluator`**（本文档）构建*产生*评分的东西。它的任务在评分首次出现时结束。
+- **[`agenteye-cli`](/zh/agenteye/cli-skill)** 读取已存在的评分（`agenteye evals`）。「本周质量下降了吗？」是它回答的问题，不是本技能的职责。
+
+---
+
+## 前提条件
+
+1. **已安装并登录 `agenteye` CLI**（`pipx install agenteye`，然后 `agenteye login`）。该技能会用到它两次：拉取真实会话用于设计，以及在最后确认评分是否落地。您的登录账户需要 `events:read` 权限，以及用于最终检查的 `evaluations:read` 权限。与 CLI 技能一样，它**无法**替您完成邮件一次性验证码登录。
+2. **一个放置评估器的地方。** 评估器会被构建成镜像并作为长期运行的服务运行，因此它需要一个真实的代码仓库，而不是临时文件。评估器通常独立存在于自己的仓库中，与被评分的 Agent 分开——该技能会寻找现有仓库，并在搭建新仓库之前征询您的意见。
+3. **`agenteye-evaluator` SDK wheel**——在让您的 Agent 开始输入 `pip` 命令之前，请先阅读下一节。
+
+---
+
+## 获取方式
+
+该技能发布于 Failproof AI 的公共技能集合中：
+
+**[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-evaluator/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-evaluator)
+
+该仓库是公开的，技能本身不需要任何凭据——它只是用*您*登录时的会话驱动 `agenteye` CLI，并在*您的*仓库中写代码。请注意，它以独立文件夹的形式发布，**不在** `pipx install agenteye` 包内，请勿在那里寻找它。
+
+## 安装技能
+
+最快的方式是使用 [`skills`](https://skills.sh) CLI，它会拉取文件夹并放到您的 Agent 查找的位置：
+
+```bash
+# Claude Code，仅限当前项目
+npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code
+
+# 所有项目（安装到 ~/.claude/skills/）
+npx skills add FailproofAI/skills --skill agenteye-evaluator -a claude-code -g --copy
+
+# 改用 Codex
+npx skills add FailproofAI/skills --skill agenteye-evaluator -a codex
+```
+
+然后像管理其他技能一样管理它：
+
+```bash
+npx skills list -a claude-code           # 查看已安装的技能
+npx skills update agenteye-evaluator     # 拉取最新版本
+npx skills remove agenteye-evaluator     # 移除它
+```
+
+喜欢手动安装？Agent Skill 只是一个包含 `SKILL.md`（以及可选引用文件）的文件夹，直接复制也可以：
+
+- **Claude Code**：将 `agenteye-evaluator/` 文件夹放入 `~/.claude/skills/`（所有项目）或 `<your-repo>/.claude/skills/`（仅该仓库）。Claude Code 会自动发现它——通过 `/skills` 列表验证，或者直接询问评估相关问题即可。
+- **Codex（OpenAI）**：Codex 读取同一个 `SKILL.md`。捆绑的 `agents/openai.yaml` 设置了 `allow_implicit_invocation: true`，因此当任务匹配时 Codex 会自动选择该技能；否则可以通过 `$agenteye-evaluator` 显式调用它。
+
+---
+
+## SDK 不在公共 PyPI 上
+
+> **警告：** 在让 Agent 安装 SDK 之前，请先阅读本节。
+
+该技能是公开的；它所驱动的 SDK 则不是。`agenteye-evaluator` 仅作为私有发布产物发布，且与 `agenteye` 不同，该名称在**公共 PyPI 上尚未被注册**——因此直接执行 `pip install agenteye-evaluator` 可能会将陌生人的包安装到读取您生产对话记录的服务中。这是一个供应链问题，而不是笔误。
+
+该技能了解这一点，因此会按照安装梯队依次尝试，在第一个适用的环节停下：如果您在 AgentEye 仓库内，则使用 monorepo 源码；否则使用 GitHub Releases 上的私有发布 wheel（需要访问权限）；如果两者都无法访问，它会**停止并告诉您联系 Failproof AI 联系人获取 wheel**，而不是自行发挥。
+
+因此，如果您的 Agent 提议从公共 PyPI 直接执行 `pip install agenteye-evaluator`，这就说明该技能根本没有加载。请立即停止并检查技能是否已安装。
+
+---
+
+## 可以问它什么
+
+一次真实的完整流程从模糊的需求开始，以一个经过确认的设计方案结束，而不是直接以代码开始：
+
+```text
+您    ▸ 我想为我们的支持机器人做评估。我觉得它有时表现很差。
+
+Agent ▸ 在我写任何东西之前：描述一次进展顺利的运行，
+        以及一次进展糟糕的。
+
+您    ▸ 好的情况：它从文档中给出答案。差的情况：它胡编乱造，
+        或者放弃并说「请联系支持」。
+
+Agent ▸ 正在运行：agenteye --json sessions --status error --since 7d
+        读取 5 个会话，包括您认为表现差的两个。
+
+        您的描述说的是事实性和推诿。对话记录在推诿方面
+        与描述吻合（5 个中有 2 个以转接支持结束，
+        在 model_response.content 中清晰可见），但事实性
+        需要您的事件中没有的基准真值。
+
+        因此我会评分三件事：
+          - deflection      基于规则，成本低，能区分您的两次运行
+          - tool_efficiency 基于规则，能捕捉 run-004 中的重试循环
+          - groundedness    LLM 评判：每个声明都在它检索的文档中吗？
+
+        「事实性」需要我们没有的基准真值；groundedness
+        是您的对话记录实际上能支撑的最接近的替代。
+        这三个名称可以吗？之后重命名会导致历史记录断裂。
+
+您    ▸ 好的
+
+Agent ▸ 这个仓库中没有评估器。要在这里搭建一个，
+        还是您在别处已经有了？
+```
+
+之后，它会先编写基于规则的维度（免费、即时、确定性），针对真实捕获的会话（包括那些会让朴素评估器崩溃的空会话和未完成会话）进行测试，只在主观维度上才会使用 LLM 评判器。它了解[调度器的限制](/zh/agenteye/evaluation-suite#configuring-the-server)——30 秒请求超时和全局 8 个并发调用——因此如果评判器不能可靠地在时限内完成，它会使用 `JobPending` 异步处理，而不是让您的评判器被取消并以五倍成本重试五次。
+
+然后它进行部署，设置两个服务器环境变量，并通过 `agenteye --json evals --session-id <id>` 确认评分确实落地。评分落地是唯一的证明。
+
+---
+
+## 需要注意的事项
+
+- **维度名称几乎是永久性的。** 评分键是任意字符串，平台会对您发送的任何内容进行趋势分析，这意味着下游没有任何东西能纠正一个错误的选择。之后重命名会导致历史记录断裂：旧会话保留旧键，趋势就此中断。这就是为什么该技能在写代码之前要明确征得您的同意——请认真对待那个提示。
+- **测试夹具是真实的生产对话记录。** 针对真实会话进行设计意味着要将它们拉取到磁盘上，而它们可能包含客户数据。该技能会在将其提交到 git 之前征询您的意见；如有疑虑，请将 `fixtures/` 排除在仓库之外，让每位开发者自行拉取。
+- **Agent 会编写并部署一个读取所有对话记录的服务。** 它以您的身份行事，受您的 CLI 登录权限约束，但请像审查其他接触生产数据的代码一样审查评估器。
+
+---
+
+## 后续步骤
+
+- **[评估套件（Evaluation suite）](/zh/agenteye/evaluation-suite)**：HTTP 契约、SDK 以及该技能所配置的服务器环境变量。
+- **[评估（Evaluations）](/zh/agenteye/evaluations)**：评分落地后出现的位置。
+- **[CLI 技能](/zh/agenteye/cli-skill)**：与本技能配套的技能，用于读取结果而非构建评分器。
+- **[CLI](/zh/agenteye/cli)**：该技能所依赖的会话数据背后的命令参考。

package/.next/standalone/docs-old/zh/agenteye/event-stream.mdx

@@ -0,0 +1,50 @@
+---
+title: "事件流"
+description: "智能体一有动作，你立刻知晓。"
+---
+
+
+智能体一有动作，你立刻知晓。事件流是你对生产环境中每个智能体的实时脉搏：无需等待，无需翻查日志，无需猜测刚刚发生了什么。
+
+![实时事件流：颜色编码的事件行实时滚动，可按环境、智能体、会话、事件类型和自由文本过滤](/agenteye/images/events-stream.png)
+
+*来自你组织中每个智能体的所有事件，最新的排在最前，实时更新。*
+
+## 对每个智能体的实时脉搏
+
+当智能体启动一次运行、调用模型、触发工具、执行钩子或遭遇错误时，该行会在事件发生的瞬间出现在流的顶部。它实时追踪你组织中每个智能体的所有事件，最新的排在最前，让你始终掌握当前状态，而非过时信息。
+
+这意味着你无需在某台服务器上追踪日志文件，无需跨机器 grep，也无需手动拼凑时间戳。打开一个页面，你就已经在监视生产环境。
+
+各行按类型用颜色编码，你一眼就能读懂流，而不必逐行解析。每行一眼可见：
+
+- **类型**，颜色编码：`agent_start`、`model_response`、`tool_use`、`hook_completed`、`error` 等。
+- **一行摘要**，描述发生了什么，这样你几乎不需要点开任何内容就能了解要点。
+- **该步骤的 Token 计数**。
+- **上下文窗口占用徽章**（适用时），让提示词增长和即将到来的压缩在造成影响前就清晰可见。
+
+实时监视意味着你能在恶性部署、失控循环或错误爆发发生时立即发现，而不是等到明天的日志复查时才知晓。
+
+## 找到那条关键运行记录
+
+当某些情况看起来不对劲时，你不需要面对海量数据，你需要的是那条出问题的单次运行。事件流的过滤很迅速：按环境、按智能体、按会话、按事件类型，或按自由文本。
+
+按会话 ID 或智能体 ID 过滤，可以从第一个事件到最后一个事件追踪一次运行的完整过程。按事件类型过滤，可以隔离某一类活动，例如在一个视图中查看组织内所有的 `error`。叠加过滤条件，几次点击就能从"所有内容、全部范围"缩小到"这个智能体、在生产环境、正在报错"，然后采取相应行动。
+
+自由文本搜索可以直接定位到某条消息、某个工具名称或你手头已有的 ID，让客户反馈在几秒内变成精确的运行记录。
+
+## 在哪里找到它
+
+事件流是你的组织主页。登录后，它是你首先看到的界面，位于 `/<org-slug>/`，让你一到达就能立刻开始排查。
+
+在其背后，你的智能体通过 SDK 发送事件，收集器将它们传输到你的 Failproof AI 可观测性服务器，流在事件到达时对其进行追踪，整个基础设施由你掌控。如果你需要的是汇总视图而非原始记录，每次运行的事件会在"会话"中折叠为一行，一键即达。
+
+这是所有其他观测界面所基于的原始数据来源，因此当其他地方的数字看起来有误时，事件流就是你确认真实情况的地方。
+
+## 相关内容
+
+- [Sessions](/zh/agenteye/sessions)：相同的事件按每次运行汇总为一行，并附有 git 风格的执行图。
+- [Telemetry](/zh/agenteye/telemetry)：你的智能体发送什么内容，以及事件如何到达流。
+- [Error tracking](/zh/agenteye/error-tracking)：统一的错误排查界面，涵盖所有出错情况。
+- [Alerts](/zh/agenteye/alerts)：将任意阈值转化为告警规则。
+- [CLI and agents](/zh/agenteye/cli-and-agents)：从终端获取相同的实时追踪。

package/.next/standalone/docs-old/zh/agenteye/hermes-capture.mdx

@@ -0,0 +1,53 @@
+---
+title: "Hermes 会话捕获"
+description: "将团队的 Hermes 网关会话（包括 Slack、Telegram、CLI 和定时运行）作为普通会话和事件引入 AgentEye。"
+---
+
+[Hermes](https://hermes-agent.nousresearch.com) 可以在团队常用的任意平台上为他们提供解答——Slack、Telegram、CLI 或定时运行。Hermes 会话捕获功能将所有这些内容作为普通会话和事件引入 AgentEye，让团队每天交互的助手与你自己编写的 Agent 一样具备可观测性。
+
+一个小型后台采集器会在 Hermes 本地会话存储写入时读取其内容，并将会话发送至 AgentEye。其工作方式与 [Codex](/zh/agenteye/codex-capture) 和 [OpenClaw](/zh/agenteye/openclaw-capture) 捕获相同，且单个采集器可以同时捕获多个来源。
+
+---
+
+## 捕获内容
+
+机器上的每一个 Hermes 会话都会被捕获，无论来自哪个渠道。每个会话都会成为 AgentEye 中的一个 [session（会话）](/zh/agenteye/sessions)；其中的用户消息、助手消息、工具调用和工具结果将成为对应的 [events（事件）](/zh/agenteye/event-stream)。
+
+会话的来源渠道——Slack、Telegram、CLI 或定时运行——会被记录在会话上，便于区分和按渠道筛选。同时还会记录会话运行所用的模型、发起会话的聊天窗口和用户，以及当某个会话由另一个会话派生时，其指向父会话的关联链接。
+
+无论是否已有消息，只要 Hermes 启动会话，该会话即可立即呈现；每轮对话的回复及其工具调用均按实际发生顺序排列。会话结束时，你还可以获取会话结束的原因、消耗的费用以及使用的 token 数量。
+
+---
+
+## 启用方法
+
+捕获功能默认关闭，需手动启用。使用具有 `events:add` 权限的 API 密钥（参见 [API keys](/zh/agenteye/api-keys)）安装采集器，并开启 Hermes 捕获：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \
+  | sh -s -- --key <YOUR_API_KEY> --hermes-enabled
+```
+
+该命令会安装采集器、将其注册为后台服务并开始捕获。确认其运行状态：
+
+```bash
+agenteye-collector health
+```
+
+需要在同一台机器上捕获多个 Agent？在同一命令中添加各自的标志即可，例如 `--hermes-enabled --codex-enabled`。
+
+首次运行时，已有的 Hermes 会话会被一次性回填，此后新活动将在数秒内实时流入。Hermes 自身的数据仅会被读取，不会被修改或删除；即使采集器重启，每条消息也只会发送一次。
+
+`health` 命令还会显示采集器捕获的内容是否全部成功到达 AgentEye。若某批数据无法投递，会被保留并重试，而非丢弃；只要有任何数据仍在等待中，检查结果就会显示为不健康——因此"健康"意味着数据已成功送达，而非仅仅进程在运行。
+
+---
+
+## 数据呈现位置
+
+捕获的会话出现在 **Sessions** 中，其事件出现在 **Events** 流中，与其他被观测的 Agent 完全一致——因此 [session replay（会话回放）](/zh/agenteye/sessions)、[search（搜索）](/zh/agenteye/queries)、[evaluations（评估）](/zh/agenteye/evaluations) 和 [alerts（告警）](/zh/agenteye/alerts) 均可对其使用。通过筛选 Hermes Agent 可单独查看这些会话。
+
+---
+
+## 隐私说明
+
+Hermes 会话包含完整的对话记录——包括命令输出、文件内容以及 Agent 读取或写入的任何内容——并可能包含敏感信息。捕获的会话将原样发送，因此请仅在将该内容集中存储至 AgentEye 合适的场景下启用捕获功能，并为采集器提供仅限 `events:add` 权限范围的密钥。数据隔离保护的详细说明请参见 [Security（安全性）](/zh/agenteye/security)。