failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,179 @@
+---
+title: "面向 Agent 的 CLI 实用脚本"
+description: "可直接复制粘贴的查询模式和 jq 脚本，将会话、事件和评估数据转化为脚本或 AI Coding Agent 可自动化处理的格式。"
+---
+
+
+直接通过脚本或 AI Coding Agent 拉取会话、事件和评估数据（并触发重新评估），输出干净的 JSON 到 stdout，可直接通过管道传入 `jq`。这些脚本将 Failproof AI Observability 的数据转化为终端用户或 AI Coding Agent（Claude Code、Cursor）可以查询和自动化处理的格式，无需点击仪表盘。
+
+以下模式均可直接复制粘贴，适用于 Failproof AI Observability CLI（`agenteye`）。安装、认证及完整选项列表请参阅 [CLI](/zh/agenteye/cli)；运行 `agenteye -h` 或 `agenteye <command> -h` 查看内置帮助。
+
+## 基本规则
+
+1. **全局选项必须放在命令*之前*。** `agenteye --json sessions` 是正确的；`agenteye sessions --json` 则不对。全局选项包括 `--json`、`--base-url`、`--org`、`--token`、`--insecure`/`--secure`、`--timeout`、`--quiet`、`--no-color`。
+2. **解析输出时始终传入 `--json`。** 数据以 JSON 格式输出到 **stdout**；人类可读的状态和错误信息输出到 **stderr**，因此 stdout 保持干净，可直接通过管道传入 `jq`。
+3. **根据退出码而非 stderr 文本做分支判断：** `0` 正常 · `1` 意外错误 · `2` 参数有误 · `3` 无法连接仪表盘 · `4` 未登录或已过期 · `5` 缺少权限 · `6` 资源未找到。
+4. **通过 `-h` 探索命令。** 每个命令都会说明其过滤器、值格式和 JSON 结构。
+
+## 一次性初始化
+
+```bash
+export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # 避免重复输入 --base-url
+agenteye login --email you@example.com                       # 粘贴邮件中的验证码；有效期约 24h
+```
+
+## 执行操作前确认认证状态
+
+`whoami` 在会话缺失或过期时不会报错，而是返回 `logged_in:false`，因此 Agent 可以安全地探测认证状态。（如果未设置 base URL 或仪表盘不可达，仍可能以非零状态退出。）
+
+```bash
+if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then
+  echo "Not authenticated. Run: agenteye login" >&2; exit 1
+fi
+```
+
+## 查找失败或低分会话
+
+```bash
+# 过去 24h 中评估出错的会话
+agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'
+
+# 某个 Agent 的 helpfulness 评分 <= 0.5 的评估结果
+agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \
+  | jq '.evaluations[] | {session_id, scores}'
+```
+
+评分过滤在 **`evals`** 上进行，而非 `sessions`。`--score KEY:MIN..MAX` 可重复使用，多个条件取 AND；任意一端为可选（`..0.5` 表示 ≤ 0.5，`0.9..` 表示 ≥ 0.9）。每次请求最多可传入 20 个评分过滤条件，超出则返回 HTTP 400。`sessions` 与 `evals` 共享 `--env`、`--status`、`--agent-id`、`--session-id` 以及时间范围过滤器，但不支持 `--score`。
+
+## 端到端读取一个会话
+
+没有单独的 `session show` 命令，可将事件轨迹与会话评估结合使用：
+
+```bash
+# 该会话的最新评估结果（状态 + 分数）
+agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}'
+
+# 该次运行的所有事件（提高 --limit 以获取完整数据）
+agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'
+
+# 会话中仅工具调用的事件（获取原始载荷需加 --full）
+agenteye --json events --full --session-id run-001 --event-type tool_use,tool_result --all \
+  | jq '.events[].payload'
+```
+
+> **注意：** 默认情况下，`events` 读取的是快速、无载荷的数据流。每个事件包含服务端计算的单行 `summary` 以及 `is_error`、token 计数等标志，但 `payload` 返回为 `{}`。若要获取原始载荷，请添加 `--full`（或 `--fields payload`）。完整数据流在数据量大时速度较慢，因此建议限制范围：将 `--full` 与单个 `--session-id` 配合使用。
+
+## 获取全量数据（分页）
+
+结果按最新优先排序，使用游标分页。
+
+```bash
+# 一次性获取：以 200 行为一页，最多获取 500 行
+agenteye --json events --session-id run-001 --limit 500 --all > events.json
+
+# 手动分页：将 next_cursor 传回
+page=$(agenteye --json events --limit 100)
+cursor=$(echo "$page" | jq -r '.next_cursor // empty')
+[ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor"
+```
+
+## 通过 --fields 精简输出
+
+限制字段（表格和 `--json` 均适用），减少 Agent 需要读取的内容。
+
+```bash
+agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]'
+agenteye --json events --session-id run-001 --fields ts,event_type --all
+```
+
+未知字段名会被拒绝（退出码 `2`）并附带有效字段列表，这也是探索字段名的便捷方式。
+
+## 探索有效过滤器值
+
+```bash
+agenteye --json list envs | jq -r '.values[]'           # --env 的可用值
+agenteye --json list tools | jq -r '.values[]'          # 工具名称；以及 agents、models、event_types 等
+agenteye --json list score_filters | jq -r '.values[]'  # --score KEY:MIN..MAX 的有效 KEY
+```
+
+## 选择组织（多租户）
+
+如果你属于多个组织，可在登录时选择当前租户（会保存选择）：
+
+```bash
+agenteye login --org acme --email you@corp.com   # 登录的同时设置租户
+agenteye --json orgs list | jq -r '.orgs[].org_slug'
+agenteye --org globex --json sessions --since 24h   # 单次命令临时覆盖
+```
+
+多组织登录时若未指定 `--org`，将以非零状态退出并列出可选择的组织。
+
+## 为 SDK/collector 创建 API 密钥
+
+```bash
+# 密钥仅打印一次，--json 模式下位于 .key 字段
+key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key')
+agenteye keys regenerate ci-bot --yes    # 轮换密钥；agenteye keys disable ci-bot --yes 可吊销
+```
+
+## 运行已保存或临时查询
+
+```bash
+agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows'
+agenteye --json query run errs --arg prod | jq '.rows'   # 已保存的查询 + 位置参数 $1
+```
+
+## 非交互式故障排查
+
+```bash
+id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id')
+agenteye incidents ack "$id"
+agenteye incidents assign "$id" --assignee you@corp.com
+agenteye incidents resolve "$id" --yes
+```
+
+> **注意：** 在 `--json` 模式下或当 stdin 不是 TTY 时，变更操作会自动跳过确认提示，因此 Agent 不会挂起；在其他情况下可显式传入 `--yes`/`-y` 跳过确认。
+
+## 脚本中的退出码处理
+
+```bash
+out=$(agenteye --json sessions --since 1h) || code=$?
+case "${code:-0}" in
+  0) echo "$out" | jq '.sessions | length' ;;
+  4) echo "Session expired - run 'agenteye login'." >&2 ;;
+  5) echo "Missing permission (ask an admin for evaluations:read)." >&2 ;;
+  3) echo "Dashboard unreachable - check the URL." >&2 ;;
+  *) echo "Unexpected error (exit ${code})." >&2 ;;
+esac
+```
+
+## JSON 输出结构
+
+| 命令 | stdout JSON（使用 `--json`） |
+|---|---|
+| `whoami` | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` 或 `{"logged_in": false}` |
+| `orgs list` | `{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}` |
+| `events` | `{"events": [...], "next_cursor": <cursor or null>}` |
+| `evals` | `{"evaluations": [...], "next_cursor": <cursor or null>}` |
+| `sessions` | `{"sessions": [...], "next_cursor": <cursor or null>}` |
+| `errors` | `{"errors": [...], "next_cursor": <cursor or null>}` |
+| `list <kind>` | `{"kind", "values": [...]}` |
+| `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}`（`key` 仅显示一次） |
+| `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` |
+| `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` |
+| `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` |
+| create/update/delete（任意） | 资源对象，或删除时返回 `{"deleted": true, "id"}` |
+| 失败（任意，使用 `--json`） | stdout 输出 `{"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."}` |
+
+- 每个 **event** 条目（`events`）：`id, session_id, agent_id, event_type, ts, payload, environment, summary, is_error, error_type, output_tokens, context_window, context_fill`。注意：除非通过 `--full`（或 `--fields payload`）请求完整数据流，否则 `payload` 为 `{}`。
+- 每个 **evaluation** 条目（`evals`）：`id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`。
+- 每个 **session** 条目（`sessions`）：`session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`。
+
+每个命令的 `--fields` 只接受其对应条目的字段名。`sessions` 和 `evals` 的字段集不同，因此对一个命令有效的字段名可能被另一个命令拒绝。
+
+## 下一步
+
+- [CLI](/zh/agenteye/cli)：安装、认证及每个命令的完整选项参考。
+- [CLI agent skill](/zh/agenteye/cli-skill)：将这些脚本打包为 AI Coding Agent 可加载的技能。
+- [API keys](/zh/agenteye/api-keys)：创建并限定 CLI、SDK 和 collector 认证所用密钥的权限范围。
+- [Python SDK](/zh/agenteye/python-sdk)：向 Failproof AI Observability 发送事件，为上述脚本提供可查询的数据。

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

@@ -0,0 +1,159 @@
+---
+title: "Failproof AI 可观测性 CLI Agent Skill"
+description: "向你的编程 Agent 询问「今天有什么问题吗？」，让它直接从你的实时 Failproof AI 可观测性数据中给出答案，无需记忆任何命令。"
+---
+
+
+向你的编程 Agent 询问*「今天有什么问题吗？」*，让它直接从你的实时 Failproof AI 可观测性数据中给出答案，无需记忆任何命令。**Failproof AI 可观测性 CLI skill**（`agenteye-cli`）是一种 *Agent Skill*：一个包含说明文件的小型文件夹，供 Claude Code 或 Codex 等编程 Agent 按需加载。它使 Agent 能够通过 [`agenteye` CLI](/zh/agenteye/cli)，以自然语言请求（如*「给 CI 创建一个只能推送事件的密钥」*或*「确认正在触发的告警并将其分配给我」*）来操作你的可观测性部署。
+
+它**不是**服务或独立的二进制文件，无需任何部署。它构建在你已安装的 CLI 之上：Agent 调用 `agenteye --json …`，解析干净的 JSON，然后用自然语言回答你。它能做的一切，你都可以自己输入相同的命令来完成。
+
+---
+
+## 与 Failproof AI 可观测性其他接口的关系
+
+Failproof AI 可观测性提供四种方式访问相同的数据和控制功能，它们相互补充：
+
+| 接口 | 说明 | 运行环境 | 适用场景 |
+|---|---|---|---|
+| **[CLI](/zh/agenteye/cli)** | `agenteye` 的命令与参数参考文档 | 你的终端 | 需要运行或脚本化某个具体命令时 |
+| **[CLI 使用示例](/zh/agenteye/cli-recipes)** | 可直接复制的 `jq`/管道模式 | 你的终端 / 脚本 | 将 CLI 集成到自动化流程时 |
+| **CLI skill**（本文档） | 基于 CLI 的自然语言入口 | 你工作站上的编程 Agent | 想要直接提问、让 Agent 选择命令时 |
+| **[Evaluator skill](/zh/agenteye/evaluator-skill)** | 用于设计和构建评分服务的同类 skill | 你工作站上的编程 Agent | 想要*生成*评估分数而非读取时 |
+| **[Python SDK skill](/zh/agenteye/python-sdk-skill)** | 为你的 Agent 添加遥测数据发送能力的同类 skill | 你工作站上的编程 Agent | 想让你的 Agent *生成*本 skill 所读取的事件时 |
+| **[仪表盘内置 AI 助手](/zh/agenteye/assistant)** | 内嵌于仪表盘的聊天功能 | 服务端（仪表盘内） | 需要在仪表盘中对数据进行问答时 |
+
+Skill 本身没有任何特权，它只是将你的语言转化为以你身份运行的 CLI 调用：
+
+```mermaid
+flowchart TD
+    YOU["你：「确认正在触发的告警」"] --> AGENT["编程 Agent（Claude Code / Codex）<br/>加载 agenteye-cli skill"]
+    AGENT --> CLI["agenteye --json incidents ack ..."]
+    CLI -->|你已认证的 CLI 会话| API["可观测性仪表盘 API"]
+```
+
+### 与仪表盘内置 AI 助手的重要区别
+
+这是两个截然不同的工具，影响范围差异显著：
+
+- **仪表盘内置 AI 助手**（[AI 助手](/zh/agenteye/assistant)）是嵌入仪表盘的聊天功能，由 Agent 服务提供支持。它**只读，且写入操作需要明确审批**：可以起草已保存的查询和仪表盘，但每次写入都会暂停并等待你的明确点击确认，且不会执行删除操作。它受 `agent:use` 权限限制，只能查看你当前所在组织的数据。
+- **CLI skill** 在*你的*工作站上运行，在*你的*编程 Agent 内部以**你的身份**驱动 `agenteye` CLI。它可以执行 CLI 的**全部功能，包括变更操作**（创建/轮换/禁用 API 密钥、修改组织设置、解决告警、删除已保存的查询），仅受你的 CLI 登录权限约束。请像对待手动输入这些命令一样谨慎对待它。
+
+---
+
+## 前置条件
+
+1. 已安装 **`agenteye` CLI** 并添加到 `PATH`（参见 [CLI](/zh/agenteye/cli) 参考文档：`pipx install agenteye`）。
+2. 已设置**仪表盘 URL**（`AGENTEYE_DASHBOARD_URL`，或由 Agent 传入 `--base-url`）。
+3. 已**登录会话**：需先自行运行 `agenteye login`。Skill **无法**代你完成邮件一次性验证码登录；若会话缺失或过期（CLI 退出码 `4`），它会提示你运行 `agenteye login`。
+
+---
+
+## 获取方式
+
+Skill 发布于 Failproof AI 的公开 skill 集合中：
+
+**[github.com/FailproofAI/skills](https://github.com/FailproofAI/skills)** → [`skills/agenteye-cli/`](https://github.com/FailproofAI/skills/tree/main/skills/agenteye-cli)
+
+无任何访问限制——该仓库完全公开，skill 本身不需要任何凭证，因为它只是使用*你*登录的会话，通过**公开的** `agenteye` CLI 访问*你的*仪表盘。你无需向任何人申请。
+
+请注意，它作为独立文件夹发布，**不包含**在 `pipx install agenteye` 包中，请勿在该包中查找。
+
+## 安装 Skill
+
+最快捷的方式是使用 [`skills`](https://skills.sh) CLI，它会自动获取文件夹并放置到 Agent 的查找路径中：
+
+```bash
+# Claude Code，仅限当前项目
+npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code
+
+# 所有项目（安装至 ~/.claude/skills/）
+npx skills add FailproofAI/skills --skill agenteye-cli -a claude-code -g --copy
+
+# 使用 Codex
+npx skills add FailproofAI/skills --skill agenteye-cli -a codex
+```
+
+管理方式与其他 skill 相同：
+
+```bash
+npx skills list -a claude-code      # 查看已安装的 skill
+npx skills update agenteye-cli      # 拉取最新版本
+npx skills remove agenteye-cli      # 移除 skill
+```
+
+prefer 手动安装？Agent Skill 本质上只是一个包含 `SKILL.md`（以及可选参考文件）的文件夹，直接复制即可：
+
+- **Claude Code**：将 `agenteye-cli/` 文件夹放入 `~/.claude/skills/`（所有项目）或 `<你的仓库>/.claude/skills/`（仅该仓库）。Claude Code 会自动发现它——通过 `/skills` 列表验证，或直接提问一个与其描述匹配的问题。
+- **Codex（OpenAI）**：Codex 读取相同的 `SKILL.md`。内置的 `agents/openai.yaml` 设置了 `allow_implicit_invocation: true`，因此当任务匹配时 Codex 会自动选择该 skill；否则可通过 `$agenteye-cli` 显式调用。
+
+---
+
+## 安全注意事项：Agent 运行 CLI 时变更操作不会出现确认提示
+
+> **警告：** 在让 Agent 执行变更操作前，请先阅读本节。
+
+`agenteye` CLI 通常会在执行破坏性操作前询问*「确定吗？」*。**当它未连接到终端时（这正是编程 Agent 的运行方式），该确认会被自动跳过；`--json` 参数也会跳过确认。** 因此，安全确认提示对 Agent **不会**触发。
+
+Skill 的设计已对此进行补偿：它会在执行任何状态变更前，说明将要运行的确切命令，并等待你明确的**确认**。请保持这一规范。当你通过 Agent 操作 Failproof AI 可观测性时，*你*就是确认步骤。需要特别注意的变更类命令：
+
+- `keys create` / `update` / `disable` / `regenerate`
+- `users create` / `update` / `disable` / `enable`
+- `settings set`
+- `alerts create` / `update` / `delete` / `test`
+- 写入类 `incidents` 子命令：`ack` / `assign` / `resolve` / `open` / `comment-add` / `comment-delete` / `subscribe` / `unsubscribe`
+- `query create` / `update` / `delete`
+- `agent rename` / `delete`
+- `orgs switch`
+
+**观测**类命令（`events`、`sessions`、`evals`、`errors`、`list`、`whoami`、`orgs list/current/perms`）均为只读，不会产生任何变更。
+
+由于 Agent 以**你的身份**操作，它只能执行你的登录所允许的操作；权限按**组织**级别解析（参见 [API 密钥](/zh/agenteye/api-keys)）。若某个命令超出你的权限，会返回退出码 `5` 并精确说明所缺权限，Agent 可以告诉你需要向管理员申请什么权限，而不是模糊地报错。
+
+---
+
+## 你可以问它什么
+
+以下是真实的交互示例——先是一次只读查询，然后是一次等待你确认的变更操作：
+
+```text
+you   ▸ 最近一天有什么问题吗？
+
+agent ▸ 正在运行：agenteye --json errors --since 24h --aggregate
+        过去 24 小时内有 3 种错误类型。最多的是 TimeoutError
+        （18 次，全部发生在 checkout-agent），其次是 RateLimited（5 次）。
+        需要查看 TimeoutError 的失败会话吗？
+
+you   ▸ 给 CI 创建一个只能推送事件的密钥。
+
+agent ▸ 这将创建一个 API 密钥。我将运行：
+          agenteye keys create ci --add events:add
+        确认继续吗？
+
+you   ▸ 是的
+
+agent ▸ 完成。密钥「ci」已创建，仅具有 events:add 权限。
+        密钥只显示一次，请立即保存。我无法再次显示它。
+```
+
+Skill 将每种自然语言意图映射到正确的 `agenteye` 命令，会先查询有效值（`list <kind>`、`whoami`）而不是猜测，并在任何变更前说明确切命令。更多示例：
+
+- *「最近 24 小时有什么问题/故障吗？」* → `errors --since 24h --aggregate`，然后给出明细。
+- *「为什么会话 `run-001` 失败了？」* → `events --session-id run-001 --all` + `evals --session-id run-001`。
+- *「本周质量趋势如何？」* → `evals --aggregate --since 7d`，然后深入查看低分运行。
+- *「给 CI 创建一个只能推送事件的密钥。」* → `keys create ci --add events:add`（说明命令后创建，并捕获一次性密钥）。
+- *「谁有访问权限？将 Dana 设为只读。」* → `users list` → `users update dana@… --permission-set read-only`（向你确认后执行）。
+- *「确认正在触发的告警并分配给我。」* → `incidents list --state firing` → `incidents ack <id>` / `incidents assign <id> you@…`。
+
+有关这些操作背后的确切命令、参数和 JSON 格式，请参见 [CLI](/zh/agenteye/cli) 参考文档和 [Agent 的 CLI 使用示例](/zh/agenteye/cli-recipes)。
+
+---
+
+## 下一步
+
+- **[CLI](/zh/agenteye/cli)**：`agenteye` 完整命令与参数参考文档。
+- **[Agent 的 CLI 使用示例](/zh/agenteye/cli-recipes)**：可直接复制的 `jq` 模式和退出码处理方法。
+- **[Evaluator agent skill](/zh/agenteye/evaluator-skill)**：同类 skill，用于构建 `agenteye evals` 读取其分数的评估器。
+- **[Python SDK agent skill](/zh/agenteye/python-sdk-skill)**：同类 skill，用于为 Agent 添加遥测数据发送能力，使 `agenteye` 能够读取相应数据。
+- **[AI 助手](/zh/agenteye/assistant)**：仪表盘内置助手（与本终端 skill 不同）。
+- **[API 密钥](/zh/agenteye/api-keys)**：限定 skill 可执行操作范围的按组织权限模型。