failproofai 1.0.1-beta.1 → 1.0.1

package/.next/standalone/docs-old/zh/agenteye/api-keys.mdx

@@ -0,0 +1,280 @@
+---
+title: "API 密钥"
+description: "API 密钥控制谁以及什么可以访问您的 Failproof AI Observability 服务器，使采集器可以发送事件而无需获得读取或管理员权限。"
+---
+
+
+API 密钥控制谁以及什么可以访问您的 Failproof AI Observability 服务器，使采集器可以发送事件而无需获得读取或管理员权限。每个密钥携带一个或多个权限，每个权限控制特定的服务器路由；您只需授予某项工作所需的少量权限。大多数部署只需创建三种类型的密钥。
+
+## 大多数部署所需的 3 种密钥
+
+| 密钥 | 权限 | 使用者 |
+|---|---|---|
+| 采集器密钥 | `events:add` | 每台 Agent 机器上的 `agenteye-collector`，用于发送事件。 |
+| 仪表板读取密钥 | `events:read`、`keys:read` | 查询数据但不修改数据的只读操作员或集成。 |
+| 引导管理员密钥 | 所有权限 | 首次启动实例（及仪表板）的操作员。由 `ADMIN_KEY` 环境变量初始化。参见[引导管理员密钥](#bootstrap-admin-key)。 |
+
+从这里开始。仅在需要更窄的自定义作用域密钥时，才参考下方的完整权限目录。另请参阅[推荐密钥布局](#recommended-key-layout)和[创建密钥](#creating-keys)。
+
+---
+
+## 权限
+
+服务器执行固定的权限目录；每个权限控制特定的 HTTP 路由。**管理员密钥**拥有所有权限；作用域密钥只拥有您在创建时授予的子集。创建密钥时，未知的权限字符串将被拒绝。
+
+> **注意：** 有两个有效权限仅供人工/仪表板使用，不能授予 API 密钥：`orgs:admin`（实例管理，仅限操作员）和 `keys:update`。尝试授予其中任一权限的 `POST /keys` 或 `PATCH /keys/:id` 请求将被拒绝并返回 HTTP 422。请参阅下方 `keys:update` 行，了解为何持有者密钥可以创建密钥但永远无法编辑密钥。
+
+### 事件摄取与查询
+
+| 权限 | HTTP 路由 | 允许的操作 |
+|---|---|---|
+| `events:add` | `POST /events` | 从采集器摄取批量事件。这是采集器唯一需要的权限。 |
+| `events:read` | `GET /events`、`GET /events/latency_aggregate`、`GET /events/environments`、`GET /events/models`、`GET /sessions/:session_id/export` | 查询事件、列出已知环境、列出数据中出现的模型标识符（供模型视图和模型过滤器使用）、计算为热图/百分位带提供支持的延迟聚合，以及将会话导出为 JSONL。共享筛选栏分面端点 `GET /events/environments` 和 `GET /events/agent_ids` 可通过 `events:read` **或** `evaluations:read` 任一权限访问，因此会话页面（受 `evaluations:read` 控制）可复用相同的按组织分面。`GET /events/models` 不在其中：它需要 `events:read`，因此仅持有 `evaluations:read` 的主体访问时将收到 403。 |
+
+### 会话与评估
+
+| 权限 | HTTP 路由 | 允许的操作 |
+|---|---|---|
+| `evaluations:read` | `GET /sessions`、`GET /evaluations`、`GET /evaluations/aggregate`、`GET /evaluations/environments`、`GET /evaluation-jobs` | 列出会话、读取评估结果、仪表板使用的汇总评估健康状况，以及评估任务工作队列状态。 |
+| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | 手动为已完成的会话排队重新评估。 |
+
+### 仪表板
+
+| 权限 | HTTP 路由 | 允许的操作 |
+|---|---|---|
+| `dashboards:read` | `GET /dashboards`、`GET /dashboards/:id`、`GET /dashboards/:id/tiles` | 列出仪表板、加载某个仪表板并读取其磁贴。 |
+| `dashboards:write` | `POST /dashboards`、`PUT /dashboards/:id`、`POST /dashboards/:id/tiles`、`PUT /dashboards/:id/tiles/:tile_id`、`DELETE /dashboards/:id/tiles/:tile_id`、`PUT /dashboards/:id/tiles/layout` | 创建和编辑仪表板、添加/编辑/删除磁贴，以及重新排列磁贴网格。 |
+| `dashboards:delete` | `DELETE /dashboards/:id` | 删除整个仪表板（磁贴级别的删除属于 `dashboards:write`）。 |
+
+### 已保存查询（SQL 编辑器）
+
+| 权限 | HTTP 路由 | 允许的操作 |
+|---|---|---|
+| `queries:read` | `GET /queries`、`GET /queries/:id`、`GET /queries/schema` | 列出已保存的查询、加载某个查询，并检查编辑器所针对的只读架构。 |
+| `queries:write` | `POST /queries`、`PUT /queries/:id` | 创建和编辑已保存的查询。SQL 仍然通过与 `queries:run` 调用相同的只读角色和受保护的 SQL 检查进行路由。 |
+| `queries:delete` | `DELETE /queries/:id` | 删除已保存的查询。 |
+| `queries:run` | `POST /queries/run` | 针对编辑器使用的只读角色执行已保存或临时 SQL。 |
+
+### AI 助手
+
+| 权限 | HTTP 路由 | 允许的操作 |
+|---|---|---|
+| `agent:use` | `GET /agent/conversations`、`POST /agent/conversations`、`GET /agent/conversations/:id`、`PATCH /agent/conversations/:id`、`DELETE /agent/conversations/:id`、`PUT /agent/conversations/:id/messages` | 与 AI 助手对话并管理您自己的（私人）会话。在**用户**上需要此权限才能看到助手面板；助手自身的密钥为 `dashboard-assistant`，单独初始化（见下文）。 |
+
+### API 密钥
+
+| 权限 | HTTP 路由 | 允许的操作 |
+|---|---|---|
+| `keys:create` | `POST /keys` | 创建新的作用域 API 密钥。**不**授予编辑现有密钥权限的能力（那是 `keys:update`）。 |
+| `keys:read` | `GET /keys` | 列出现有密钥。此端点永远不会返回密钥密文。 |
+| `keys:update` | `PATCH /keys/:id` | 编辑现有密钥的权限。这是一个**仅供人工/仪表板使用**的权限；不能分配给 API 密钥（持有者密钥可以创建密钥，但永远无法编辑密钥）。 |
+| `keys:disable` | `POST /keys/:id/disable` | 吊销密钥。受保护的密钥（`admin`、`dashboard-assistant`）无法被禁用；请通过更改环境变量并重启来轮换它们。 |
+| `keys:regenerate` | `POST /keys/:id/regenerate` | 轮换密钥的密文。受保护的密钥无法通过此路由重新生成。 |
+
+### 仪表板用户
+
+| 权限 | HTTP 路由 | 允许的操作 |
+|---|---|---|
+| `users:create` | `POST /users`、`GET /users/defaults` | 邀请新的仪表板用户（发送电子邮件及一次性密码 (OTP) 登录），并读取用于预填邀请表单的仪表板配置默认权限集。 |
+| `users:read` | `GET /users`、`GET /users/:id` | 列出用户并加载单个用户记录。 |
+| `users:update` | `PUT /users/:id` | 编辑用户的权限。更新会向受影响的用户发送权限变更邮件，并在其下一次请求时生效；无需重新登录。 |
+| `users:delete` | `DELETE /users/:id`、`POST /users/:id/enable` | 禁用用户（立即吊销其会话）并重新启用之前被禁用的用户。 |
+
+这些权限支撑仪表板的**用户**页面，每个成员授予的作用域以标签形式显示：
+
+![用户页面：每个仪表板用户一张卡片，显示其电子邮件、已授予的权限以及编辑/禁用控件](/agenteye/images/users.png)
+
+### 操作设置
+
+| 权限 | HTTP 路由 | 允许的操作 |
+|---|---|---|
+| `settings:read` | `GET /settings`、`GET /settings/schema`、`GET /settings/model-context-windows`、`GET /settings/model-context-windows/resolve` | 查看仪表板管理的操作设置及其元数据；列出每个模型的上下文窗口覆盖值；以及解析模型的有效窗口。 |
+| `settings:write` | `PUT /settings/:key`、`PUT /settings/model-context-windows`、`DELETE /settings/model-context-windows` | 编辑操作设置，以及添加、更改或删除每个模型的上下文窗口覆盖值。更改会影响新事件，无需重启服务器。 |
+
+![设置页面：仪表板管理的操作设置，例如允许的登录方式和会话/OTP 有效期，可在不重启的情况下编辑](/agenteye/images/settings.png)
+
+### 告警与事件
+
+| 权限 | HTTP 路由 | 允许的操作 |
+|---|---|---|
+| `alerts:read` | `GET /alerts`、`GET /alerts/:id` | 查看已配置的告警定义。 |
+| `alerts:write` | `POST /alerts`、`PUT /alerts/:id`、`DELETE /alerts/:id`、`POST /alerts/:id/test` | 创建、编辑、删除和测试触发告警定义。 |
+| `incidents:read` | `GET /alerts/incidents`、`GET /alerts/incidents/:iid`、`GET /alerts/incidents/:iid/comments`、`GET /alerts/incidents/:iid/subscribers` | 查看事件及其分类记录。 |
+| `incidents:write` | `POST /alerts/:id/incidents` | 针对现有告警手动开启一个事件。 |
+| `incidents:ack` | `POST /alerts/incidents/:iid/ack`、`POST /alerts/incidents/:iid/assign`、`POST /alerts/incidents/:iid/resolve`、`POST /alerts/incidents/:iid/comments`、`POST /alerts/incidents/:iid/subscribe`、`POST /alerts/incidents/:iid/unsubscribe` | 确认、分配、解决事件并对其进行评论。 |
+
+### 审计
+
+| 权限 | HTTP 路由 | 允许的操作 |
+|---|---|---|
+| `audits:read` | `GET /audits`、`GET /audits/:id`、`GET /audits/:id/runs`、`GET /audits/findings`、`GET /audits/findings/:fid` | 查看审计定义、运行历史和发现结果。 |
+| `audits:write` | `POST /audits`、`PUT /audits/:id`、`DELETE /audits/:id`、`POST /audits/:id/run`、`POST /audits/findings/:fid/status` | 创建、编辑、删除和运行审计；对发现结果进行分类（确认/静默/忽略/解决/重新开启/分配）。 |
+
+> **注意：** 要为密钥授予审计权限，请显式授予 `audits:*`。有关审计功能上线时现有授权者的迁移方式，请参阅[升级和向后兼容性说明](#upgrade-and-backward-compatibility-notes)。
+
+> 收件人选择器端点 `GET /alerts/recipients`（列出告警编辑器可通知的成员邮箱）可由持有 `alerts:read` **或** `alerts:write` 任一权限的用户访问，因此告警编辑器无需被授予 `users:read` 即可填充选择器。
+
+> 仪表板查看者需要**同时具备** `dashboards:read`（加载已保存的视图）和 `evaluations:read`（健康指标从评估数据中计算）。授予 `dashboards:write` 可让用户创建或编辑仪表板，授予 `dashboards:delete` 可删除仪表板。
+
+> `/health` 和 `/auth/*`（OTP 请求、OTP 验证、会话检查、登出）在设计上不需要身份验证；它们是登录流程和存活探针。`GET /access-granters` 需要有效密钥但不需要特定权限，因此任何已登录的用户都可以查看哪些管理员可联系以进行访问变更。
+
+---
+
+## 权限集
+
+权限集允许您应用命名角色，而无需每次手动挑选单个令牌。与其为每个新仪表板用户或 API 密钥逐一选择十几个权限，不如选择一个集合，分配到该集合的所有人都持有一致且可审查的授权。编辑自定义集合会将新授权重新应用于已分配该集合的每个用户，因此角色变更只需一次编辑，而无需逐一遍历每个成员。
+
+每个组织初始化时都带有三个内置集合：
+
+| 集合 | 权限 | 适用对象 |
+|---|---|---|
+| `read-only` | `events:read`、`keys:read`、`users:read`、`evaluations:read`、`dashboards:read`、`queries:read`、`settings:read`、`alerts:read`、`audits:read`、`incidents:read` | 对所有操作界面的只读访问。 |
+| `standard` | `read-only` 中的所有权限，加上 `evaluations:trigger`、`queries:run`、`incidents:ack`、`agent:use` | 只读权限加上日常值班操作：运行查询、重新评估会话、确认事件以及使用 AI 助手。 |
+| `admin` | 所有可分配的权限 | 对组织的完全控制。 |
+
+三个内置集合是**不可变的**；其名称始终代表相同含义，因此 `read-only`、`standard` 和 `admin` 可在策略和入职流程中安全引用。操作员可以创建额外的**自定义集合**，以建模特定于您组织的角色（例如"仪表板作者"角色或"仅采集器"角色）。
+
+集合在仪表板中展示，并通过 API 进行管理：`GET /permission-sets`（列出，受 `users:read` 控制）以及 `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name`（创建、编辑、删除自定义集合，受 `settings:write` 控制）。删除或编辑内置集合的请求将被拒绝。
+
+集合成员资格支撑着另外两项功能：
+
+- **`DEFAULT_USER_PERMISSIONS`**（管理员打开 **+ 新用户** 时预选的授权）默认为 `standard` 集合。
+- **`agenteye-orgctl` 上的 `--set` 标志**（操作员成员管理）从命名集合初始化成员，然后您可以使用 `--add` / `--remove` 进行微调。
+
+> **注意：** 当集合包含不可分配给密钥的权限时（例如携带 `keys:update` 的自定义集合），从该集合初始化密钥时会删除不可分配的令牌；否则服务器将以 HTTP 422 拒绝该密钥。仪表板用户不受此限制。
+
+---
+
+## 引导管理员密钥
+
+管理员密钥是单一根凭证，允许操作员从零开始建立访问权限：使用它可以创建所有其他作用域密钥、邀请第一批仪表板用户，并在任何其他密钥存在之前配置实例。这是唯一不通过密钥 API 创建的密钥；它从环境中配置，以便服务器在首次启动时即可访问。
+
+在服务器上设置 `ADMIN_KEY` 环境变量。每次启动时，服务器会将此值更新插入为具有所有权限的管理员密钥。
+
+轮换方式：将 `ADMIN_KEY` 更改为新密文并重启服务器。
+
+---
+
+## 组织作用域
+
+**组织本身由操作员在带外创建和管理，而不是通过此密钥 API。** 组织和成员的生命周期（创建/重命名/删除/清除组织；添加/更新/移除成员）通过 **`agenteye-orgctl`** CLI 完成；没有对应的 HTTP API 或仪表板按钮。**不变的是：按组织的 API 密钥仍由组织成员在仪表板（或通过此密钥 API）中创建。**
+
+在多组织部署中，组织成员创建的每个密钥（通过此密钥 API 或仪表板**密钥**页面）都属于**一个组织**，只能读取或写入该组织的数据；组织在创建时被标记到密钥上，并在每次请求时强制执行。两个引导密钥是唯一的例外：`admin` 密钥（从 `ADMIN_KEY` 初始化）和 `dashboard-assistant` 密钥（从 `AGENT_API_KEY` 初始化）是**实例作用域**（不携带组织信息）。仪表板使用 `admin` 密钥进行身份验证，以便代表已登录的成员代理每个组织的请求。单租户部署无需考虑这一点；所有密钥都属于内置的 `default` 组织。
+
+---
+
+## 创建密钥
+
+使用管理员密钥（或任何具有 `keys:create` 权限的密钥）来创建其他作用域密钥。
+
+### 采集器密钥（仅摄取）
+
+```bash
+curl -s -X POST http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "prod-collector",
+    "key": "your-collector-secret",
+    "permissions": ["events:add"]
+  }'
+```
+
+### 仪表板密钥（只读）
+
+```bash
+curl -s -X POST http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "dashboard",
+    "key": "your-dashboard-secret",
+    "permissions": ["events:read", "keys:read"]
+  }'
+```
+
+通过 HTTP API 创建密钥时，您需要自行提供 `key` 值；请选择强密文并安全存储。（仪表板的方式相反：它会为您生成强密文，并在创建时仅显示一次；参见[仪表板中的密钥管理](#key-management-in-the-dashboard)。）响应确认密钥已创建：
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "prod-collector",
+  "permissions": ["events:add"],
+  "created_at": "2026-04-01T12:00:00Z"
+}
+```
+
+---
+
+## 列出密钥
+
+```bash
+curl -s http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+列表响应中不返回密钥密文，只返回 ID、名称和权限。
+
+---
+
+## 禁用密钥
+
+禁用会立即吊销访问权限，而不删除密钥记录。
+
+```bash
+curl -s -X POST http://your-server/keys/<id>/disable \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+---
+
+## 重新生成密钥
+
+为现有密钥生成新密文。旧密文立即失效。
+
+```bash
+curl -s -X POST http://your-server/keys/<id>/regenerate \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+响应包含新的明文密文，**仅显示一次**。
+
+---
+
+## 仪表板中的密钥管理
+
+仪表板中的**密钥**页面为上述所有操作提供了 UI。您需要具有 `keys:read` 权限的密钥才能查看列表，以及分别具有 `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` 权限才能执行创建/编辑/禁用/重新生成操作。编辑密钥权限（`keys:update`）与创建密钥（`keys:create`）是分开的，因此您可以授予操作员创建密钥的能力，而不授予重新界定现有密钥作用域的能力，反之亦然。管理员密钥涵盖所有这些操作。
+
+从仪表板创建密钥时，您无需提供密文；仪表板会为您生成强密文，并在创建时**仅显示一次**。请立即复制并安全存储；与重新生成密钥一样，它不会再次显示。您仍然可以直接选择密钥的权限，或从权限集初始化（见下文）。
+
+![API 密钥页面：每个密钥一张卡片，显示其名称、已授予的权限和创建时间，以及重新生成和禁用操作；受保护的密钥（如 `admin`）会被标记](/agenteye/images/api-keys.png)
+
+---
+
+## 推荐密钥布局
+
+| 密钥 | 权限 | 使用者 |
+|---|---|---|
+| `admin`（通过 `ADMIN_KEY` 环境变量引导） | 所有 | 运维/配置，以及仪表板（使用 `ADMIN_KEY` 进行身份验证，通过权限检查代理用户请求） |
+| 每主机采集器密钥 | `events:add` | 每台 Agent 机器上的采集器 |
+| `dashboard-assistant`（通过 `AGENT_API_KEY` 环境变量引导） | `events:read`、`evaluations:read`、`dashboards:read`、`dashboards:write`、`queries:read`、`queries:write`、`queries:run` | AI 助手，自动初始化，**受保护**；无法通过 API 编辑 |
+| 助手遥测密钥（可选） | `events:add` | AI 助手自我检测（如已启用） |
+
+> **注意：** 助手的密钥由服务器从 `AGENT_API_KEY` 环境变量**自动初始化**（Agent 以 `AGENTEYE_API_KEY` 形式呈现同一密文）；无需手动创建密钥，也不涉及管理员密钥。其权限在源代码中固定，因此作用域不会因配置错误而被扩展：对事件/评估/仪表板的读取权限，加上用于"让 AI 编写查询"创作流程的仪表板写入和查询读取/写入/运行权限。所有 SQL 仍然通过与用户编写的查询相同的只读角色和受保护 SQL 路径，因此这扩展了*创作界面*，而非数据界面；破坏性操作（`queries:delete`、`dashboards:delete`）刻意不在助手密钥中。与 `admin` 密钥一样，它是**受保护的**：无法通过密钥 API 禁用或重新生成，只能通过更改 `AGENT_API_KEY` 并重启来轮换。仪表板*用户*还需要 `agent:use` 权限才能看到并使用助手。如果您启用了自我检测，请为助手提供一个单独的仅 `events:add` 密钥。
+
+---
+
+## 升级和向后兼容性说明
+
+仅在升级现有实例时才需要以下内容；新部署可跳过。
+
+> 审计功能上线时，现有授权者按照与告警相同的角色形态进行了扩展：每个持有 `alerts:read` 的用户和权限集获得了 `audits:read`，每个持有 `alerts:write` 的用户获得了 `audits:write`。现有 API 密钥**未被扩展**。如果密钥需要审计功能，请显式授予 `audits:*`。
+
+> 旧版 `alerts:ack` 令牌的存储授权被解析为 `incidents:ack`，以便值班人员无需重新创建密钥即可保留访问权限。该令牌不再可从仪表板用户编辑器分配；矩阵现在提供 `incidents:ack`。
+
+---
+
+## 后续步骤
+
+- [Python SDK](/zh/agenteye/python-sdk)：您的 Agent 代码在发送事件时如何进行身份验证。
+- [安全性](/zh/agenteye/security)：登录、访问控制和每个组织的数据隔离如何工作。

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

@@ -0,0 +1,63 @@
+---
+title: "AI 助手"
+description: "用自然语言向 Agent 数据提问，并直接获取链接到具体证据的答案。"
+---
+
+
+用自然语言向 Agent 数据提问，并直接获取链接到具体证据的答案。无需编写 SQL，无需翻查仪表盘——**Failproof AI Observability** 助手是团队中任何人获取 Agent 相关答案的最快方式。
+
+![Failproof AI Observability 助手在仪表盘中回答自然语言问题的界面，展示了实时 Agent 活动表、按 Agent 划分的模型使用情况，以及文字摘要，所执行的查询也内联显示](/agenteye/images/assistant.png)
+*用自然语言提问，答案直接来自你自己的数据。这里它分解了哪些 Agent 最繁忙、它们使用了哪些模型，并展示了执行的查询，方便你核实每一个数字。*
+
+无需任何学习成本。打开对话框，输入你想了解的内容，然后点击它返回的链接：
+
+```
+You:  which sessions errored today?
+AI:   5 sessions errored today, newest first. Each one is linked:
+      • checkout-agent   14:02   tool timeout
+      • billing-agent    11:47   unhandled error
+      • ...and 3 more
+
+You:  summarize this session          (asked while viewing a run)
+AI:   This run took 12 steps across 3 tools and failed near the end when a
+      payment tool returned an error. It scored low on your "resolved" eval.
+      Links: the session, the failing event, and that evaluation.
+```
+
+## 直接提问，直达证据
+
+你不再需要凭猜测，也不再需要手写查询。问"本周生产环境的质量趋势如何？"、"今天哪些 Session 出错了？"或"总结这个 Session"，几秒钟内便能得到直接答案，而无需自己构建查询并逐行阅读。
+
+每个答案都附有来源依据。助手会链接到它用于得出答案的确切 Session、已保存查询和仪表盘，让你可以点进去核实，而不必盲目信任它的结论。它还具备**页面感知**能力：在查看某个 Session 时询问"这个 Session"，它就已经知道你指的是哪次运行。稍后可以从历史切换器中重新打开任意早期对话，从上次中断的地方继续。
+
+## 将满意的答案保存为查询或仪表盘
+
+当一个答案值得保留时，直接让助手保存它即可。它会起草 SQL 生成已保存查询，或根据这些查询组装仪表盘，然后向你展示一张 **Approve / Reject** 确认卡片。在你点击 Approve 之前，任何内容都不会被写入，因此你既享有"直接提问"的速度，又始终掌握最终决定权。
+
+在 **Queries** 页面，助手更进一步，化身 SQL 编写者：描述你想要的查询（"显示过去 7 天内各 Agent 的错误率"），它会将 SQL 直接流式输入编辑器，并打开差异视图，让你在内容落定前选择 **Accept** 或 **Reject**。
+
+![Observability Queries 页面及其 SQL 编辑器](/agenteye/images/query-lab.png)
+*Queries 页面：编辑器是助手流式生成草稿查询的地方，查询为只读状态，供你接受或拒绝。*
+
+在此通过提问来编写 SQL 使用的是 `queries:run` 权限，与编辑器中 **Run** 按钮背后的权限相同。其他地方的对话则需要 `agent:use` 权限。
+
+## 可以放心开放给整个团队
+
+你可以将助手开放给所有人使用，无需担心它会触碰什么：
+
+- **它只读取你已有权限查看的内容。** 答案受限于你自己的读取权限，因此它不会扩大你的数据访问范围。
+- **每次写入操作都需要你确认。** 已保存查询和仪表盘只有在你明确点击 Approve 后才会创建，且没有任何设置可以关闭这道审批门。
+- **它永远无法删除任何内容。** 没有删除工具暴露给助手，它也不持有删除权限。删除操作始终由你在仪表盘中亲自完成。
+- **它仅限于你的组织内部。** 助手只能查看你当前所在的组织。
+- **你的问题属于你自己。** 提示词和答案存储在你自己的 Observability 数据库中；产品分析功能只记录使用元数据，从不记录你的提示词文本。
+
+## 在哪里找到它
+
+助手常驻于你的组织（`/<org-slug>/...`）每个页面的右侧边栏。点击侧边栏，或按 `⌘J` / `Ctrl+J`，即可展开完整的对话面板；拖动边缘可调整大小，宽度设置会在页面刷新后保留。使用助手需要 **`agent:use`** 权限，否则侧边栏将显示为灰色不可用状态。如果你的部署尚未启用助手（需要配置 LLM 连接），你将看到一个静默的侧边栏，而非可用的对话框。
+
+## 相关内容
+
+- [CLI 与 Agents](/zh/agenteye/cli-and-agents)
+- [查询](/zh/agenteye/queries)
+- [仪表盘](/zh/agenteye/dashboards)
+- [评估套件](/zh/agenteye/evaluation-suite)

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

@@ -0,0 +1,54 @@
+---
+title: "审计：您的自动可靠性分析师"
+description: "Failproof AI Observability 会主动发现那些您从未为之编写规则的故障，并为您提供一份按优先级排列、有证据支撑的待办清单，告诉您究竟需要修复什么。"
+---
+
+
+Failproof AI Observability 会主动发现那些您从未为之编写规则的故障，并为您提供一份按优先级排列、有证据支撑的待办清单，告诉您究竟需要修复什么。这就像每晚都有一位分析师梳理您的日志，然后在清晨将简短的清单放在您的桌上。
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/C5nHKGQIqZQ?autoplay=1&mute=1&loop=1&playlist=C5nHKGQIqZQ&rel=0&playsinline=1" title="Watch: Automatically find where your agent is failing (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*两分钟概览：从计划运行到可付诸行动的修复方案。*
+
+![审计页面：定期扫描会话以发现故障模式的周期性任务，每项任务都有计划和灵敏度设置](/agenteye/images/audits.png)
+*每个审计都是一个周期性任务，负责挖掘您的会话数据并输出按优先级排列、有证据支撑的改进建议。*
+
+## 不再猜测下一步修复什么
+
+告警捕获的是您已知需要关注的问题。审计捕获的是您尚未意识到的问题。按照您设定的计划，审计会读取所有 Agent 会话，主动寻找值得修复的模式，让您将时间花在处理发现结果上，而不是滚动日志、期望自己碰巧发现问题。
+
+一次运行会针对生产环境中真正会破坏 Agent 的故障模式展开分析：
+
+- **错误聚类**：在共同根因下反复出现的相同故障。
+- **与基线的偏移**：行为悄然偏离已知良好窗口的情况。
+- **对话记录中的目标失败**：技术上已完成但实际上未完成任务的运行。
+- **工具误用**：使用了错误的工具、传入了错误的参数，或陷入消耗调用次数的循环。
+- **质量与成本的权衡**：在本可以更低成本获得相同输出的地方支付了过高费用。
+- **覆盖盲区**：没有任何评估或告警在监控的行为。
+
+您可以通过单一的**灵敏度**设置（低、中或高）来决定分析的深度，从而让嘈杂的预发布 Agent 和严格的生产环境 Agent 各自调整到所需的信号水平。
+
+## 每条建议都有凭据
+
+您无需凭信任接受任何发现结果。每条建议都会引用其来源的确切会话以及发现该问题所用的 SQL，因此您只需点击一下即可查看证据并确认问题，而无需对某个结论进行反向推导。
+
+当某个发现涉及泄露的凭据时，系统会更进一步，链接到匹配的具体事件。点击后您将直接跳转到会话中的那一精确时刻，且该时刻已被选中——而非需要您从头滚动的冗长对话记录。链接中只显示事件名称，从不将检测到的密钥复制到发现结果中，因此阅读发现结果不会成为您的凭据被记录的第二个地方。如果某个事件因会话已超过您的数据保留期限而不再存在，页面会直接说明，而不是让您疑惑自己是否点错了。
+
+这也是审计保持诚实的原因所在。服务器会验证每个被引用的会话确实存在，并**丢弃任何证据不成立的建议**，因此审计只会调查，绝不凭空捏造。出现在您清单上的结果都是真实可复现的，并按其重要性排序，影响最大的改进排在最前面。
+
+## 将修复转化为安全护栏
+
+修复一个问题只是成功的一半。另一半是确保问题不会悄悄卷土重来。每条发现结果都附带一个**一键快捷方式，可起草一个复现告警**，并预填了一个合理的初始触发条件供您调整。关闭发现结果，启用告警，下次该模式再次出现时，您将收到通知，而不是在未来某次审计中重新发现它。
+
+## 在哪里找到它
+
+审计位于仪表板的 **`/<org-slug>/audits`** 路径下（侧边栏 → *analyze* → *audits*）。查看运行记录和发现结果需要 **`audits:read`** 权限；创建、编辑和处理审计需要 **`audits:write`** 权限。设置审计的范围和频率，然后在需要立即获得结果而不想等待下一次计划运行时点击 **Run now**。
+
+## 相关内容
+
+- [告警](/zh/agenteye/alerts)：在您已知的阈值被触发的瞬间收到通知。
+- [评估](/zh/agenteye/evaluations)：对每次运行进行评分，让质量回归问题自动浮现。
+- [错误追踪](/zh/agenteye/error-tracking)：对 Agent 抛出的错误进行分组和跟踪。
+- [事件](/zh/agenteye/incidents)：将审计发现的问题追踪至最终修复完成。

package/.next/standalone/docs-old/zh/agenteye/cli-and-agents.mdx

@@ -0,0 +1,79 @@
+---
+title: "CLI"
+description: "您的整个 Failproof AI 可观测性部署，一条命令即可搞定。"
+---
+
+您的整个 Failproof AI 可观测性部署，一条命令即可搞定。无需离开终端，即可检查生产环境、创建 API 密钥或确认事件，还可以将任意操作编写成 CI 脚本，或者用自然语言让编程智能体替您完成。
+
+```bash
+pipx install agenteye
+agenteye login --email you@example.com      # 一个 6 位验证码将发送到您的邮箱
+agenteye --json sessions --since 24h         # 过去一天的所有智能体运行记录，按最新排序
+```
+
+*`agenteye` CLI 与您的仪表板通信，是一个独立工具，与负责将事件发送到服务器的采集器不同。*
+
+## 您的整个部署，一条命令即可搞定
+
+不必再为一个简单问题而反复切换标签页。`agenteye` CLI 通过单一二进制文件读取您的数据并管理您的组织，原本需要在仪表板中点来点去才能完成的检查，现在只需一行命令即可复用、设置别名或粘贴到操作手册中。它提供四个操作入口：
+
+- **读取数据：** `sessions`、`events`、`evals` 和 `errors`，支持按时间、智能体和环境过滤。
+- **管理组织：** `keys`、`users`、`settings`、`alerts` 和 `incidents`。
+- **运行分析：** 支持保存的 SQL 查询，以及针对事件数据的即席 `query` 执行。
+- **询问助手：** `agent ask` 可访问与仪表板中相同的只读分析助手。
+
+使用 `pipx` 一次性安装，通过邮件发送的 6 位验证码登录，即可开始使用。会话有效期约为一天，过期后重新运行 `agenteye login` 即可。无需打开浏览器，直接用它检查生产环境、创建密钥或快速处理正在触发的事件：
+
+```bash
+agenteye errors --since 24h --aggregate      # 查看故障情况，按错误类型分组
+agenteye incidents list --state firing       # 查看当前正在触发的事件
+agenteye keys create ci --add events:add     # 创建一个仅能推送事件的密钥，密钥值仅显示一次
+```
+
+有一个使用习惯需要注意：`--json` 等全局选项必须放在命令之前。`agenteye --json sessions` 是正确的，`agenteye sessions --json` 则不行。
+
+## 编写脚本，集成到 CI
+
+每条命令都支持 `--json`，这带来了质的变化。干净的 JSON 输出到 stdout，而人类可读的状态信息和警告则输出到 stderr，因此使用 `--json` 捕获的内容可以直接通过管道传给 `jq`，无需过滤多余的行。这也是 CLI 既适合您在终端直接使用，也适合编程智能体解析输出的原因：
+
+```bash
+agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'
+```
+
+它专为无人值守运行而设计。当没有终端连接时，确认提示会自动跳过，因此在管道中不会卡住，而且每条命令都会返回有意义的退出码：`0` 表示成功，`4` 表示未登录，`5` 表示缺少权限（消息中会指明具体权限，例如 `alerts:write`），`3` 表示仪表板无法访问。脚本可以根据 `4` 进行重新认证，或根据 `5` 精确告知需要向管理员申请哪些权限，而不是盲目失败。
+
+## 用自然语言让编程智能体来驱动
+
+更好的是，您根本不需要记住这些参数。**CLI 技能**是一个名为 `agenteye-cli` 的小型 Agent Skill 文件夹，它可以教会 Claude Code 或 Codex 等编程智能体通过自然语言来驱动 CLI。只需问"今天有什么问题吗？"，智能体就会选择合适的命令，以您的身份执行，并以文字形式给出答复。
+
+对于 Claude Code，将 `agenteye-cli` 文件夹放入 `~/.claude/skills/` 即可自动发现。Failproof AI 可观测性提供该文件夹；无需额外安装任何内容，因为它只是驱动您已经安装的 CLI。请先自行登录：技能无法替您完成邮件验证码登录流程。
+
+由于智能体以您的身份运行 CLI，它可以执行您的登录权限所允许的一切操作，包括读写：创建密钥、修改设置、解决事件。CLI 的"您确定吗？"提示对智能体不会触发，因此技能的设计是：在执行任何变更操作前，先明确说明将要执行的命令，并等待您确认。您就是那个确认步骤。
+
+```text
+您      为什么会话 run-001 失败了？
+
+智能体  正在运行：agenteye --json events --session-id run-001 --all
+        checkout-agent 在第三次工具调用时遇到了 TimeoutError。
+```
+
+读取操作立即完成，所有写入操作都会先等待您确认：
+
+```text
+您      给 CI 创建一个只能推送事件的密钥。
+
+智能体  这将创建一个 API 密钥，我将执行：
+          agenteye keys create ci --add events:add
+        确认继续吗？
+
+您      是的
+
+智能体  完成。已创建密钥 "ci"，仅具有 events:add 权限。密钥值仅显示一次，请立即保存。
+```
+
+## 相关链接
+
+- [CLI 参考文档](/zh/agenteye/cli)：所有命令、参数和 JSON 格式说明。
+- [面向智能体的 CLI 使用示例](/zh/agenteye/cli-recipes)：可直接复制的 `jq` 模式和退出码处理方法。
+- [CLI 智能体技能](/zh/agenteye/cli-skill)：安装和运行 `agenteye-cli` 技能。
+- [AI 助手](/zh/agenteye/assistant)：仪表板内置分析助手，也是 `agent ask` 的访问目标。