failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,350 @@
+---
+title: "CLI"
+description: "通过终端或脚本驱动所有 Failproof AI Observability 功能，无需往返控制台。"
+---
+
+
+通过终端或脚本驱动所有 Failproof AI Observability 功能，无需往返控制台。`agenteye` CLI 可查询您的数据（会话、事件日志、评估结果）并管理您的组织（API 密钥、用户、设置、告警、事件、已保存查询），非常适合自动化检查、将 Observability 集成到 CI 流程，或让编码智能体检查生产环境。每个命令均支持 `--json` 标志，因此无论是您在终端交互使用，还是编码智能体（Claude Code、Cursor）调用并解析结果，都同样适用。
+
+使用这一个二进制文件，您可以：
+
+- **读取数据**：`sessions`、`events`、`evals`、`errors`（按时间、智能体、环境、评分筛选）。
+- **管理组织**：`keys`、`users`、`settings`、`alerts`、`incidents`。
+- **运行分析**：已保存的 SQL 和临时查询执行器（`query`）。
+- **咨询 AI 助手**：与控制台中相同的只读分析师（`agent`）。
+
+> **注意：** 这是 `agenteye` CLI，与采集器守护进程（`agenteye-collector`）是不同的工具。CLI 与您的控制台通信；采集器负责将事件上报到服务器。
+
+---
+
+## 快速开始
+
+从零到获得第一个结果只需四行命令。将 CLI 指向您的控制台，登录，确认身份，然后拉取最近一天的运行记录：
+
+```bash
+pipx install agenteye
+agenteye --base-url https://agenteye.example.com login --email you@example.com   # 系统会发送6位验证码到您的邮箱
+agenteye whoami                                                                  # 确认用户 + 当前激活的组织
+agenteye --json sessions --since 24h                                             # 每行对应一次智能体运行，最近24小时
+```
+
+最后一条命令输出最近会话的 JSON 对象（最新的排在最前，默认最多50条）。可以通过管道传给 `jq` 进行切片处理，或去掉 `--json` 以获得带边框的彩色表格。每行包含运行状态，以及评估器评分后的指标分数（此处为简略版）：
+
+```json
+{
+  "sessions": [
+    {
+      "session_id": "run-8f2a",
+      "agent_id": "checkout-bot",
+      "environment": "prod",
+      "status": "error",
+      "scores": { "helpfulness": 0.42, "tool_efficiency": 0.55 },
+      "event_count": 37,
+      "started_at": "2026-07-16T09:14:02Z",
+      "last_event_at": "2026-07-16T09:14:48Z"
+    }
+  ],
+  "next_cursor": null
+}
+```
+
+本页其余部分将逐一说明各个环节：[安装](#installation)（隔离安装）、[登录](#authentication)、[配置](#configuration)、所有命令共用的[全局约定](#global-options--conventions)，以及[完整命令参考](#command-reference)。
+
+---
+
+## 安装
+
+CLI 是一个公开的 PyPI 包，名为 **`agenteye`**。建议安装到隔离环境中，以确保其拥有独立的依赖项：
+
+```bash
+pipx install agenteye
+# 或
+uv tool install agenteye
+```
+
+需要 Python 3.10+。安装后的命令为 **`agenteye`**：
+
+```bash
+agenteye --version
+agenteye --help
+```
+
+> **注意：** Failproof AI Observability Python SDK 也使用 `agenteye` 这个发行包名称。使用 `pipx` 或 `uv tool` 安装 CLI（而非 `pip install` 到共享虚拟环境中）可以避免两者冲突。只有在同一环境中未安装 SDK 的情况下，才可以直接使用 `pip install agenteye`。
+
+---
+
+## 认证
+
+CLI 通过邮件一次性验证码向**控制台**进行身份验证：
+
+```bash
+agenteye login --email you@example.com
+# 系统会向您的邮箱发送6位验证码，粘贴到提示符处即可。
+```
+
+会话令牌存储在 `~/.agenteye/cli.json` 中（仅您本人可读，权限为 `0600`），默认有效期为 24 小时。过期后，重新运行 `agenteye login` 即可。
+
+```bash
+agenteye whoami     # 显示当前用户、激活的组织及权限
+agenteye logout     # 吊销会话并清除存储的令牌
+```
+
+`whoami` 在会话缺失或过期时不会报错，而是返回 `logged_in: false`，因此脚本或智能体可以安全地探测认证状态（如果未设置 base URL 或控制台不可达，仍可能以非零状态退出）。
+
+**要求：** 您的邮箱必须获准登录控制台（请联系您的 Failproof AI Observability 管理员），且控制台必须可通过其 base URL 访问（参见[配置](#configuration)）。如果申请了验证码但未收到，您的邮箱可能尚未开通控制台访问权限。
+
+---
+
+## 选择组织（多租户）
+
+如果您的账户属于多个组织，请在**登录时**选择当前激活的组织；该选择会被保存并用于后续所有命令：
+
+```bash
+agenteye login --org acme           # 在一步中完成身份验证并设置激活的租户
+agenteye orgs list                  # 您可访问的组织列表（激活的组织有标记）
+agenteye orgs switch globex         # 更改已保存的默认组织
+agenteye --org globex sessions      # 仅对单条命令覆盖组织
+```
+
+如果您只属于一个组织，系统会自动选中，无需关注 `--org`。如果您属于多个组织但未指定，CLI 会列出所有组织并要求您重新运行并加上 `--org <slug>`。激活的组织会随每次请求发送到控制台，权限按**每个组织**单独解析；`agenteye whoami` 会显示激活的组织、您在其中的权限以及您的所有成员资格。
+
+---
+
+## 配置
+
+| 设置项 | 标志 | 环境变量 | 默认值 |
+|---|---|---|---|
+| 控制台 base URL | `--base-url` | `AGENTEYE_DASHBOARD_URL` | **必填**（无默认值） |
+| 激活的组织/租户 | `--org` | `AGENTEYE_ORG` | 登录时选择；保存在 `~/.agenteye/cli.json` |
+| 会话令牌 | `--token` | `AGENTEYE_CLI_TOKEN` | 来自 `~/.agenteye/cli.json` |
+| JSON 输出 | `--json` | `AGENTEYE_CLI_JSON` | 关闭 |
+| 跳过 TLS 验证 | `--insecure` / `--secure` | `AGENTEYE_INSECURE` | 关闭（登录时保存） |
+| 请求超时（秒） | `--timeout` | _（无）_ | 30 |
+| 禁用使用遥测 | _（无）_ | `AGENTEYE_ANALYTICS_DISABLED`（或 `DO_NOT_TRACK`） | 遥测目前已禁用；不发送任何数据 |
+
+解析优先级为**标志 → 环境变量 → 配置文件**。没有默认值；您必须将 CLI 指向您的控制台，可以在每条命令中指定（`--base-url https://agenteye.example.com`），也可以通过环境变量设置一次（首次 `login` 后也会自动保存）：
+
+```bash
+export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com
+```
+
+配置目录遵循 `AGENTEYE_HOME`（与 SDK 和采集器使用相同约定）；如果设置了该变量，`cli.json` 位于 `$AGENTEYE_HOME/cli.json`。
+
+### 自签名或内部 TLS
+
+如果您的控制台使用自签名或内部证书通过 HTTPS 提供服务（例如原始负载均衡器主机名），TLS 验证会以 `CERTIFICATE_VERIFY_FAILED` 错误拒绝连接。传入 `--insecure` 可跳过证书验证：
+
+```bash
+agenteye --base-url https://agenteye.internal --insecure login
+```
+
+**`--insecure` 在登录时会被保存到 `cli.json`**，因此后续命令会自动跳过验证，无需重复传入该标志。传入 `--secure` 可对单次调用进行强制验证，或在下次登录时将验证重新开启并保存。在验证被禁用期间，CLI 在任何联系控制台的命令之前都会向 stderr 打印警告。跳过验证会消除对中间人攻击的防护；请确保在依赖此选项之前，您信任通往控制台的网络路径（VPN、私有子网等）。
+
+---
+
+## 遥测与隐私
+
+> **注意：** 目前发布的 CLI **不发送任何使用遥测数据。** 主开关处于关闭状态，无论您的环境如何配置，均不会传输任何数据。以下内容描述了一旦遥测功能启用时的退出机制。
+
+即使在启用状态下，遥测也**仅为匿名使用分析数据**，绝不包含您的智能体、会话或事件数据：
+
+- **您的智能体、会话或事件数据绝不会离开您的基础设施。** 仅上报 CLI 使用情况：命令和子命令名称（例如 `keys create`）、您使用的标志**名称**（绝不包含标志值）、成功/退出状态和耗时，以及变更操作的单次事件（例如 `api_key_created`、`query_run`，仅包含静态名称/枚举和粗略计数）。您的控制台 URL、会话令牌、邮箱、组织 slug、资源 id、SQL、密钥密文和查询过滤器**绝不会被发送**。运营者仅以不透明的内部 id 标识，绝不以邮箱标识。
+- **提前退出**可通过在 CLI 环境中设置 `AGENTEYE_ANALYTICS_DISABLED=1`（CLI 也支持跨工具的 `DO_NOT_TRACK=1` 约定）实现。一旦遥测功能开启，该设置立即生效，因此注重隐私的环境可以永久保持退出状态。
+- 如果遥测功能启用，CLI 会直接向 PostHog（`https://us.i.posthog.com`）发送数据；屏蔽了该主机的机器将静默地不发送任何数据，且 CLI 不受任何影响。
+
+---
+
+## 全局选项与约定
+
+请阅读一遍；以下内容适用于每一条命令。
+
+- **全局选项必须放在命令之前。** `agenteye --json sessions` 是正确的；`agenteye sessions --json` 会报用法错误。全局选项包括：`--json`、`--base-url`、`--org`、`--token`、`--insecure`/`--secure`、`--timeout`、`--quiet` 和 `--no-color`。
+- **`--json` 仅向 stdout 输出纯 JSON，不输出其他内容。** 人类可读的状态行、警告和错误均输出到 **stderr**，因此 `--json` 的 stdout 捕获保持干净，即使显示了状态行也可以直接通过管道传给 `jq`。不使用 `--json` 时，将显示适合人类阅读的带框彩色表格。
+- **通过 `--help` 探索功能。** 每个命令和子命令都支持 `--help`（以及 `-h` 别名）：`agenteye -h`、`agenteye sessions -h`、`agenteye keys create -h`。顶层帮助还列出了退出码和全局选项。没有全局机器可读的接口导出；请使用各命令的 `--help`，以及特定领域的 `agenteye query schema` 和 `agenteye settings schema` 来了解这两个注册表。
+- **确认提示在脚本和智能体中自动跳过。** 创建/更新/删除命令在交互式终端中会提示"确认吗？"，但**在 `--json` 模式下或 stdin 不是 TTY 时会自动跳过该提示**（TTY 是交互式终端会话；管道或 CI 运行器不是），因此脚本和智能体不会挂起。传入 `--yes`/`-y` 可显式跳过提示。由于智能体不会触发提示，智能体应在执行破坏性操作前先与用户确认。
+- **分页：** 结果按最新优先排列，使用游标分页（每页返回一个令牌用于获取下一页）。`--limit N`（别名 `-n`）限制行数，**默认为 50**；`--all` 自动翻页（每次 200 行）**但仍受 `--limit` 限制**，因此单独使用 `--all` 仍会在 50 条时停止。如需完整扫描，请传入较大的显式上限：`--all --limit 1000`。`--page-size N` 控制每次请求的块大小（最大 200）；`--cursor <id>` 从上一页的 `next_cursor` 恢复。
+- **时间过滤器：** `--since` 接受相对时间窗口：`15m`、`1h`、`6h`、`24h`、`7d` 或 `all`（控制台的预设值）。对于更长或自定义的范围（例如最近 30 天），请使用 `--from`/`--to`：**必须包含 `T` 和时区的** ISO-8601 UTC 时间戳（例如 `2026-06-01T00:00:00Z`），会覆盖 `--since`。以空格分隔或不含时区的值会报用法错误。
+- **`--fields a,b,c`**（适用于 `events`、`sessions`、`evals`、`errors`）将输出限制为指定字段，对表格和 `--json` 均有效。未知字段名称会被拒绝并显示有效列表，这是一种快速探索字段名称的方法。
+- **`--file payload.json`**（或 `--file -` 读取 stdin）用于提供完整的 JSON 请求体，适用于资源结构复杂的情况（`alerts create/update`、`settings set` 和 `users create/update`）。已保存查询的 SQL 使用 `--sql @file.sql` 代替。
+- **多值过滤器** 使用逗号分隔 → 以集合方式匹配（同一过滤器内为并集，跨过滤器为交集）：`--event-type tool_use,tool_result`。Click 选项不支持可变参数，因此 `--add a b` 会出错。请使用 `--add a,b`、重复标志（`--add a --add b`）或加引号（`--add "a b"`）。
+
+---
+
+## 命令参考
+
+### 最常用的 5 个命令
+
+日常工作中大多数操作只需用到少数几个读取命令。从这里开始，有需要时再查阅下方完整列表：
+
+| 命令 | 功能 | 示例 |
+|---|---|---|
+| `sessions` | 每行对应一次智能体运行：时间、环境、智能体、状态、最新评分。 | `agenteye --json sessions --since 24h --status error` |
+| `events` | 运行内每一步的原始事件流（加 `--full` 获取完整载荷）。 | `agenteye --json events --session-id run-001 --all` |
+| `evals` | 评估结果和评分；`--aggregate` 汇总统计。 | `agenteye --json evals --aggregate --since 7d --env prod` |
+| `errors` | 仅显示出错事件；`--aggregate` 按类型统计数量。 | `agenteye --json errors --since 24h --aggregate` |
+| `list` | 探索有效的过滤器值（智能体、环境、模型……）。 | `agenteye list agents` |
+
+### CLI 的全部功能
+
+以下是完整功能列表。CLI 共有 **18 个顶层命令**。所有读取命令均支持 `--json` 和上述全局选项；运行 `agenteye <command> -h`（或 `<command> <subcommand> -h`）可查看任一命令的详细标志列表和 JSON 输出结构。
+
+### 身份认证：`login` · `logout` · `whoami` · `orgs` · `version` · `help`
+
+```bash
+agenteye login --email you@example.com [--org acme]   # 邮件一次性验证码；保存会话
+agenteye logout                                       # 清除本机保存的会话
+agenteye whoami                                       # 当前用户、激活的组织及权限
+agenteye version                                      # 输出 CLI 版本（与 --version 相同）
+agenteye help                                         # 顶层帮助（与 --help 相同）
+```
+
+`orgs` 用于查看和切换当前激活的租户：
+
+```bash
+agenteye orgs list        # 您的组织列表 + 您在各组织中的角色（激活的已标记）
+agenteye orgs switch acme # 更改已保存的激活组织（在 TTY 上省略 slug 可从列表中选择）
+agenteye orgs current     # 当前激活组织的身份信息
+agenteye orgs perms       # 您在当前激活组织中的权限，按资源分组
+```
+
+### 观测（只读）：`events` · `sessions` · `evals` · `errors` · `list`
+
+这些命令均无需确认。共用过滤器：`--session-id`、`--agent-id`、`--env`（**不是** `--environment`）以及时间范围（`--since` / `--from` / `--to`）。
+
+```bash
+# events（别名：原始每步事件流），最新优先
+agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000
+agenteye --json events --since 1h --search timeout --all | jq '.events[].payload'
+
+# sessions：每行对应一次智能体运行（时间/环境/智能体/会话/状态；不支持评分过滤）
+agenteye --json sessions --since 24h --status error
+agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000
+
+# evals：评估结果 + 评分；--score 按指标过滤，--aggregate 汇总统计
+agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3
+agenteye --json evals --aggregate --since 7d --env prod        # 状态分布 + 各键评分统计
+
+# errors：出错事件；--aggregate 统计数量/会话/智能体/最后出现时间
+agenteye --json errors --since 24h --aggregate
+agenteye --json errors --since 24h --error-type timeout --all --limit 1000
+
+# list：过滤前先探索有效的过滤器值
+agenteye list envs        # 还支持：agents event_types score_filters models hooks tools error_types
+```
+
+`--score KEY:MIN..MAX`（适用于 **`evals`**，不适用于 `sessions`）可重复使用，多个条件取交集；任一边界均可省略（`..0.5` 表示 ≤ 0.5，`0.9..` 表示 ≥ 0.9）。每次请求最多支持 20 个评分过滤器。`evals --scores-full` 是**仅适用于人类表格**的显示标志；它会显示所有评分对，而不是前几个加上 `+N` 计数。在 `--json` 模式下无效，`--json` 始终返回完整的评分对象。如需**端到端读取一个会话**，可将事件流与其评估结果结合使用：
+
+```bash
+agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'
+agenteye --json evals  --session-id run-001                       # 对应的评分 + 状态
+```
+
+### 管理（需要权限）：`keys` · `users` · `settings` · `alerts` · `incidents`
+
+**`keys`**：API 密钥。密文在本地生成后发送到服务器（服务器仅存储其哈希值），并在创建/重新生成时**仅显示一次**；请立即保存。使用 `--json` 时，密文仅出现在 `key` 字段中。通过**名称**引用。
+
+```bash
+agenteye keys list                                   # 先显示激活的密钥，再显示已吊销的
+agenteye keys show ci-bot
+agenteye keys create ci-bot --add events:read.add    # 按需限定权限范围；一次性输出密文
+agenteye keys create ops --permission-set standard --remove queries:run   # 从预设开始，再裁剪
+agenteye keys update ci-bot --add evaluations:read --yes
+agenteye keys regenerate ci-bot --yes                # 轮换密文（旧密文立即失效）
+agenteye keys disable ci-bot --yes                   # 吊销
+```
+
+权限计算方式为 `(permission-set ∪ --add) − --remove`。令牌格式为 `slug:action`（例如 `events:read`），或 `slug:action.action` 在单个资源上展开多个权限（`events:read.add` → `events:read`、`events:add`）。预设值：`read-only`、`standard`、`admin`。人类专用权限（`keys:update`）不能授予给密钥。
+
+**`users`**：组织成员，通过**邮箱**引用（也接受 UUID id）。
+
+```bash
+agenteye users list [--active-only]
+agenteye users show dev@corp.com
+agenteye users create dev@corp.com --permission-set standard
+agenteye users update dev@corp.com --add alerts:write --remove queries:delete   # 预览 + 确认
+agenteye users disable dev@corp.com --yes            # 有受保护/自身保护机制
+agenteye users enable dev@corp.com
+```
+
+**`settings`**：固定注册表（您只能读取和修改现有键；不能创建新键）。
+
+```bash
+agenteye settings list                               # 键 · 值 · 类型 · 更新时间（密文已遮蔽）
+agenteye settings schema                             # 每个键的接受规范（类型 · 范围 · 描述）
+agenteye settings set session_ttl_secs --value 86400 --yes
+```
+
+**`alerts`**：告警定义，通过**名称**引用。`create` 接受位置参数 NAME，以及标志或通过 `--file` 提供的完整 JSON 请求体。
+
+```bash
+agenteye alerts list
+agenteye alerts show high-errors
+agenteye alerts create high-errors --file alert.json          # NAME 为必填（位置参数）
+agenteye alerts update high-errors --severity critical --yes
+agenteye alerts test high-errors --yes                        # 触发测试通知
+agenteye alerts delete high-errors --yes
+```
+
+**`incidents`**：告警事件，通过 id 引用（支持短 id）。`show` 输出完整的活动日志；在操作前请先阅读。
+
+```bash
+agenteye incidents list --state firing                # 还支持：acknowledged, resolved
+agenteye incidents count
+agenteye incidents show <id>
+agenteye incidents ack <id>
+agenteye incidents assign <id> you@corp.com           # 受托人必须是运营者
+agenteye incidents resolve <id> --yes
+agenteye incidents open --alert-id <id> --severity critical    # 针对告警手动开启一个事件
+agenteye incidents comment-add <id> "root cause: upstream 5xx"
+agenteye incidents comment-list <id> ; agenteye incidents comment-delete <id> <comment-id>
+agenteye incidents subscribe <id> ; agenteye incidents unsubscribe <id> ; agenteye incidents subscribers <id>
+```
+
+### 分析与助手：`query` · `agent`
+
+**`query`**：针对分析存储的已保存 SQL，以及临时查询执行器。已保存查询通过**名称**引用；SQL 在服务器端验证（仅支持 SELECT/WITH，有语句超时和行数上限）。
+
+```bash
+agenteye query schema [TABLE]                         # 分析视图的列布局
+agenteye query run --sql "select count(*) from analytics.events"
+agenteye query run errs --arg prod --limit 100        # 运行已保存查询 + 位置参数 $1
+agenteye query list ; agenteye query show errs
+agenteye query create errs --sql @errs.sql --description "errored events (24h)"
+agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes
+```
+
+**`agent`**：与内置 **AI 助手**对话（与控制台中相同的只读分析师）。对话通过短 chat-id 引用（支持前缀解析）。
+
+```bash
+agenteye agent health                                 # AI 助手是否已配置/可访问
+agenteye agent models                                 # 可通过 --model 传入的模型列表（默认已标记）
+agenteye agent ask "which agents errored most in the last day?"    # 开启对话；输出其短 id
+agenteye agent ask --chat <short-id> "and which tools did they call?"   # 继续该对话
+agenteye agent chats ; agenteye agent show <short-id>
+agenteye agent rename <short-id> --title "error triage" ; agenteye agent delete <short-id>
+```
+
+---
+
+## 退出码
+
+| 代码 | 含义 |
+|---|---|
+| 0 | 成功 |
+| 1 | 意外错误（例如控制台返回 5xx） |
+| 2 | 用法错误（无效参数、未知命令/标志、名称冲突） |
+| 3 | 无法连接控制台 |
+| 4 | 未登录或会话已过期；请运行 `agenteye login` |
+| 5 | 已认证，但账户缺少所需权限（消息中会指明具体权限） |
+| 6 | 请求的资源未找到（例如未知的会话或事件 id） |
+
+这些退出码使 CLI 适合脚本化使用：编码智能体可以根据 `4` 提示您重新认证，或根据 `5` 提示缺少的权限。请参阅 [CLI 智能体使用食谱](/zh/agenteye/cli-recipes)，了解退出码处理模式和 JSON 输出结构。
+
+---
+
+## 下一步
+
+- **[CLI 智能体使用食谱](/zh/agenteye/cli-recipes)**：可直接复用的查询模式、`jq` 单行命令、`--fields` 投影、退出码处理以及 JSON 输出结构，专为驱动 CLI 的编码智能体编写。
+- **[CLI 智能体技能](/zh/agenteye/cli-skill)**：将此 CLI 打包为可安装的 Claude Code / Codex *技能*，让编码智能体通过自然语言请求驱动 Failproof AI Observability。
+- **[API 密钥](/zh/agenteye/api-keys)**：`keys create --add …` 背后的权限模型。
+- **[AI 助手](/zh/agenteye/assistant)**：启用 `agent ask` 所使用的助手。

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

@@ -0,0 +1,55 @@
+---
+title: "Codex 会话捕获"
+description: "将团队本地 OpenAI Codex 会话以普通会话和事件的形式导入 AgentEye，无需改变现有的 Codex 使用方式。"
+---
+
+您的工程师每天都在使用 OpenAI Codex。Codex 会话捕获功能将这些编码会话以普通会话和事件的形式引入 AgentEye，让您可以对其进行搜索、回放，并与其他所有观测数据放在一起进行评估。它与 [Python SDK](/zh/agenteye/python-sdk) 相辅相成：SDK 用于对您自己编写的 Agent 进行埋点，而此功能则捕获团队日常使用 Codex 产生的会话数据——无需任何改动。
+
+一个轻量级的后台采集器会在 Codex 本地会话记录写入时实时读取，并将其上报至 AgentEye。每台机器只需部署一个采集器，即可同时捕获所有本地 Codex 界面的数据，无需逐一配置。
+
+同一采集器还支持其他 Agent 的捕获——详见 [OpenClaw](/zh/agenteye/openclaw-capture) 和 [Hermes](/zh/agenteye/hermes-capture)。您可以按需启用，单个采集器能够同时捕获多个来源。
+
+---
+
+## 捕获内容
+
+所有**本地**运行的 Codex 界面都会生成相同的磁盘会话记录，采集器会统一采集以下来源：
+
+- Codex **CLI** 及 `codex exec`
+- **VS Code / IDE 扩展**
+- **桌面应用**（仅限本地执行的会话）
+
+每个 Codex 会话都会成为 AgentEye 中的一个[会话](/zh/agenteye/sessions)；其中的用户消息、助手消息、推理过程、工具调用、工具结果以及 Token 用量将转化为对应的[事件](/zh/agenteye/event-stream)。每个会话的来源界面（CLI、IDE 或桌面应用）均会被记录，便于您加以区分。
+
+> **云端会话不在捕获范围内。** 桌面应用越来越多地将会话运行在 Codex 云端，本地仅保留元数据，没有可供读取的本地记录。只有本地执行的会话才会被捕获。
+
+---
+
+## 启用捕获
+
+捕获功能默认关闭，需手动启用。请使用具有 `events:add` 权限的 API 密钥（参见 [API 密钥](/zh/agenteye/api-keys)）安装采集器，并开启 Codex 捕获：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/FailproofAI/agenteye-collector/main/install.sh \
+  | sh -s -- --key <YOUR_API_KEY> --codex-enabled
+```
+
+该命令将安装采集器、将其注册为后台服务并立即开始捕获。运行以下命令确认服务正常运行：
+
+```bash
+agenteye-collector health
+```
+
+首次运行时，现有的 Codex 会话将被一次性回填，此后的新活动将在数秒内实时上报。采集器对 Codex 的本地文件仅执行读取操作，不会对其进行修改、移动或删除，且每个会话只会上报一次，重启后亦然。
+
+---
+
+## 数据展示
+
+捕获的会话将出现在 **Sessions** 中，其事件将出现在 **Events** 流中，与您观测的其他 Agent 数据完全一致——因此[会话回放](/zh/agenteye/sessions)、[搜索](/zh/agenteye/queries)、[评估](/zh/agenteye/evaluations)和[告警](/zh/agenteye/alerts)均可正常使用。通过筛选 Codex Agent，可单独查看其数据。
+
+---
+
+## 隐私说明
+
+Codex 会话记录包含完整的会话内容——包括命令输出、文件内容以及 Codex 读写的所有信息——可能涉及敏感数据。捕获的会话将原样上报，因此请仅在适合将相关内容集中存储至 AgentEye 的机器和团队中启用此功能，并为采集器配置仅限 `events:add` 权限的密钥。数据隔离机制详见[安全说明](/zh/agenteye/security)。

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

@@ -0,0 +1,87 @@
+---
+title: "概念"
+description: "Failproof AI 可观测性的术语词汇表——事件、会话、评估、审计、发现与事件单——集中定义于此。"
+---
+
+
+本页定义了 Failproof AI 可观测性所使用的术语词汇。如果您在其他指南中遇到不熟悉的术语，可在此查找其定义。无需从头到尾通读：快速浏览即可，或在遇到需要明确含义的词汇时随时跳回查阅。
+
+---
+
+## 数据模型
+
+**事件（Event）**
+最小数据单元。一条事件记录了您的 Agent 执行的单个步骤：一次 `tool_use`、一次 `model_request`、一次 `hook_completed`、一次 `error` 等等。您的 Agent 通过 [Python SDK](/zh/agenteye/python-sdk) 发出事件，这些事件会实时显示在**事件（Events）**页面上。
+
+**会话（Session）**
+一次 Agent 运行，以 `session_id` 标识。会话是共享同一 ID 的所有事件的集合，在**会话（Sessions）**页面上汇总为单行，并在详情页上以执行图的形式呈现。会话通常以 `agent_start` 开始，以 `agent_end` 结束。
+
+**Agent**
+一次运行中具名的参与者，以 `agent_id` 标识。一次运行可以涉及多个 Agent：例如一个规划器（planner）派生出一个摘要子 Agent。子 Agent 携带 `parent_id`，正是这个字段使 Failproof AI 可观测性能够在执行图中将它们绘制在各自的泳道上。
+
+**环境（Environment）**
+标识运行发生位置的标签：`production`、`staging`、`dev`。您在配置 SDK 时设置一次，几乎每个仪表板页面都可以按环境进行筛选。
+
+**上下文窗口占用率（Context-window fill）**
+模型响应所消耗的上下文窗口百分比。Failproof AI 可观测性会在其识别的模型的 `model_response` 事件上标记该数值，使提示词增长趋势和即将到来的压缩行为直接在事件流中可见。
+
+---
+
+## 质量
+
+**评估（Evaluation）**
+由您运行的评分服务为已完成会话生成的质量分数。评估为选装功能：在接入评估器之前，会话只会被记录，不会被评分。每次评估可以包含多个命名维度的分数（例如 `helpfulness`、`factuality`、`tool_efficiency`），每个维度附带简短的推理说明。请参阅[评估套件（Evaluation suite）](/zh/agenteye/evaluation-suite)。
+
+**分数键（Score key）**
+评估器报告的某一维度名称，例如 `helpfulness`。告警规则和审计可以随时间追踪特定的分数键。
+
+**评估器（Evaluator）**
+您的评分服务。Failproof AI 可观测性会将已完成运行的对话记录以 POST 方式发送给它，并存储其返回的分数。平台不内置默认评估器，评分逻辑由您自行实现。
+
+---
+
+## 发现与修复故障
+
+**Hook**
+您的 Agent 框架在某个步骤前后运行的守卫或副作用逻辑：内容安全检查、PII 脱敏、预算限制等。Hook 会发出 `hook_triggered` / `hook_completed` 事件，携带 `outcome`（allow、deny、modify），并拥有独立的观测页面。
+
+**告警规则（Alert rule）**
+当指标超过您设定的阈值时触发的规则：错误率、p95 延迟、Token 成本或评估分数。规则触发时，会创建一个事件单并通过您选择的渠道（邮件、Slack、Webhook、仪表板内）发送通知。请参阅[告警（Alerts）](/zh/agenteye/alerts)。
+
+**事件单（Incident）**
+告警规则触发时创建的待处理问题。事件单具有生命周期（确认、分配、解决）以及记录每次操作的活动时间线。您也可以手动创建事件单。
+
+**审计（Audit）**
+定期（每小时至每周）运行的调查任务，在*跨会话*的日志中挖掘您尚未编写规则的故障模式：错误聚类、低分、延迟异常值、工具调用循环以及未正常结束的运行。告警监控的是您已知的指标，而审计则告诉您下一步应该关注什么。请参阅[审计（Audits）](/zh/agenteye/audits)。
+
+**发现（Finding）**
+一次审计运行产出的带有排名和证据支撑的结果。发现会描述一种模式，关联到其背后的具体会话，并具有分级处理生命周期（确认、解决、静默、忽略）。Failproof AI 可观测性会对多次运行间的发现进行去重，使已知模式得到更新而不是不断堆积。
+
+**AI 助手（The AI assistant）**
+仪表板内的对话工具，能够用自然语言回答关于您的 Agent 的问题，基于您自己的数据。默认为只读模式；其创建的任何内容（已保存的查询、仪表板）均需审批，且无法执行删除操作。请参阅 [AI 助手（AI assistant）](/zh/agenteye/assistant)。
+
+---
+
+## 运行方式
+
+**组织（Organization / 租户）**
+隔离的工作空间。一个 Failproof AI 可观测性实例可以托管多个组织，每个组织拥有独立的用户、密钥和数据。所有仪表板 URL 均限定在您的组织标识符下（`/<org-slug>/…`）。
+
+**采集器（Collector）**
+`agenteye-collector`，运行在每台 Agent 机器上的轻量级守护进程，负责批量处理 SDK 写入磁盘的事件并将其发送到服务器。
+
+**API 密钥（API key）**
+用于向服务器验证客户端身份的作用域令牌。密钥携带细粒度权限（例如，采集器使用 `events:add`，仪表板密钥使用只读作用域）。请参阅 [API 密钥（API keys）](/zh/agenteye/api-keys)。
+
+**服务器（Server）**
+数据采集和 API 服务。负责采集事件、将运行状态存储到您的数据库中，并提供仪表板和 CLI 服务。
+
+**仪表板（Dashboard）**
+Web 界面。每个页面均限定在某个组织范围内，通过服务器 API 读取数据。
+
+---
+
+## 后续步骤
+
+- [概览（Overview）](/zh/agenteye/overview)：了解各组件如何协同工作。
+- [可观测性（Observability）](/zh/agenteye/observability)：各观测页面（Events、Sessions、Models、Tools、Hooks、Errors）的详细介绍。

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

@@ -0,0 +1,46 @@
+---
+title: "仪表板"
+description: "将实时智能体数据转化为团队共享的统一视图。"
+---
+
+
+将实时智能体数据转化为团队共享的统一视图。将重要查询固定为图表，团队所有人一眼即可看到相同的数据，无需重复执行任何查询。
+
+![基于已保存查询构建的仪表板：每小时事件折线图、按类型划分的错误柱状图、延迟面积图和按模型划分的 token 用量](/agenteye/images/dashboard-fleet.png)
+
+*一块看板，四个已保存查询：每小时事件数、按类型划分的错误、延迟和按模型划分的 token 用量。*
+
+## 团队共享同一数据源
+
+不再需要将截图粘贴到聊天中，也不再需要每天重复运行相同的查询五次。仪表板是一个团队共享的组织级看板，任何团队成员都可以打开查看完全相同的视图。当底层数据发生变化时，图表会随之更新，因此看板始终保持最新状态，无需再为过时的数据争论不休。
+
+上方的集群仪表板是日常运维的良好起点：
+
+- **每小时事件数**折线图，用于监控吞吐量并及时发现突发下降
+- **按类型划分的错误**柱状图，让最主要的故障类别一目了然
+- **延迟**面积图，在用户投诉之前提前发现响应变慢的问题
+- **按模型划分的 token 用量**明细，让成本始终可见
+
+您可以在 `/<org-slug>/dashboards` 找到您的看板。
+
+## 固定已保存的查询
+
+每个图块都从已保存的查询开始。在[查询](/zh/agenteye/queries)库（包含内置预设以及您自定义的查询，覆盖事件和评估数据）中构建并保存您关心的查询，然后将其固定到仪表板，选择最适合数据的图表类型：**折线图**用于展示随时间变化的趋势，**柱状图**用于对比各分类，**面积图**用于展示数据量，**饼图**用于展示占比分布。
+
+由于图块本质上就是将已保存的查询渲染为图表，因此无需手动同步任何内容。只需更新一次查询，所有使用该查询的仪表板都会自动更新。
+
+## 关注质量，而不仅仅是数量
+
+数量告诉您智能体正在忙碌运行，质量才能告诉您它们是否真正完成了工作。将仪表板指向您的[评估分数](/zh/agenteye/evaluations)，即可获得一块追踪运行质量随时间变化的看板，让质量下降以图表曲线低谷的形式呈现，而不是来自用户的意外投诉。
+
+![基于已保存评估查询构建的质量仪表板](/agenteye/images/dashboard-quality.png)
+
+*质量看板将评估分数置于核心位置，与运营数据并排展示。*
+
+将运营看板和质量看板并排放置，团队就拥有了一个统一的地方，既能回答"它运行正常吗？"，也能回答"它表现良好吗？"，而无需任何人重新运行查询。
+
+## 相关内容
+
+- [查询](/zh/agenteye/queries)：构建并保存成为图块的查询。
+- [评估](/zh/agenteye/evaluations)：对运行结果评分，以便随时间追踪质量变化。
+- [告警](/zh/agenteye/alerts)：对任意指标设置阈值并触发通知。

package/.next/standalone/docs-old/zh/agenteye/error-tracking.mdx

@@ -0,0 +1,40 @@
+---
+title: "错误追踪"
+description: "在一处查看所有 Agent 产生的失败，并自动归组，让密集的错误爆发呈现为单一问题。"
+---
+
+在一处查看所有 Agent 产生的失败，并自动归组，让密集的错误爆发呈现为单一问题。你只需一键，便能从"某处出现红色报错"直接跳转到确切的出问题运行记录，无需滚动实时日志去寻找。
+
+![错误页面：顶部是错误随时间分布的直方图，下方是分组的红色错误行，每行都有一键式"+ alert"按钮](/agenteye/images/errors.png)
+*错误页面：顶部是错误随时间分布的直方图，重复失败会折叠为每个事件一行。*
+
+## 所有失败，自动为你汇总
+
+Agent 出错时，你不应该还要滚动实时事件流，焦急地等待红色行出现，又担心它们随即消失。**错误**页面替你完成收集工作。它将仪表板中所有标红的内容汇聚到一个统一的分诊界面，让你第一眼看到的是哪里出了问题，而不是去哪里找问题。
+
+它捕获的不只是显而易见的错误。除了显式的 `error` 事件，Failproof AI Observability 还会把那些悄无声息的失败浮出水面：任何携带失败信息的 `tool_result`、`hook_completed` 或 `agent_end` 都会出现在这里。工具返回了错误，或者 hook 异常退出，即使没有抛出明显的异常，它们也不会再悄悄溜走。
+
+页面顶部的直方图展示了错误随时间的分布情况。一眼即可判断这是持续的背景噪音，还是几分钟前突然出现的峰值——让你立刻决定是否需要放下手头的工作去处理。
+
+与所有观测界面一样，错误页面的数据归属于你的组织，并支持按日期范围、环境、Agent 和会话进行筛选。这意味着你可以从全局列表出发，快速缩小到你真正关心的那一个 Agent 或那一个环境。
+
+## 一个事件，而非数百条相同的行
+
+一个依赖损坏可能每分钟触发数百次相同的错误。如果原始展示，那就是一大堵几乎相同的日志行，把你真正需要看的信息完全淹没。
+
+Failproof AI Observability 会将同一会话中相同错误类型的重复失败折叠为一行。一次爆发呈现为一个事件。你数的是问题数，而不是日志行数，关键信号始终置于顶端，不会被自身的数量所淹没。
+
+## 从"某处出现红色"直达确切事件
+
+点击任意一行，即可直接进入该运行的会话，并定位到出错的确切事件。无需复制会话 ID，无需滚动寻找出问题的时刻：你直接就站在那里，完整的执行图一目了然，让你能清楚看到 Agent 在出错前都做了什么。
+
+如果你拥有 `alerts:write` 权限，每一行还带有一个 **+ alert** 按钮。点击后，Observability 会打开一条新的告警规则，并预填好内容以捕获相同的失败。你刚刚处理过的事件，下次发生时会主动通知你，而不是再次让你措手不及。
+
+**访问路径：** **错误**页面位于仪表板的观测区域，路径为 `/<org-slug>/errors`。
+
+## 相关内容
+
+- [告警](/zh/agenteye/alerts)：将任何失败转化为通知规则。
+- [事件](/zh/agenteye/incidents)：追踪从触发到解决的完整告警过程。
+- [会话](/zh/agenteye/sessions)：打开任意错误背后的完整运行记录。
+- [审计](/zh/agenteye/audits)：让 Observability 自动为你发现运行中的失败模式。